diff --git a/AGENTS.md b/AGENTS.md index 7ce72dcb52c..8df3cc2c466 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -182,8 +182,8 @@ const table = sqliteTable("session", { - When you open a PR, decide whether the change needs a flag: new user-visible behavior, risky core changes, and anything not ready to release get one; fixes, refactors, docs and tests do not. - Gate risky behavior, or behavior that lands over several PRs, with a key and a description in `packages/schema/src/config/flag.ts`, and read it with `Flag.enabled("")` from `@opencode/core/flag`. -- Flags are on in local and dev builds and off in releases; `experimental.` in config and `OPENCODE_FLAGS="key,-other"` override that. -- Say in the PR body which flag guards the change. To try every flag at once, use `OPENCODE_FLAGS=all` or `experimental.all_flags: true`; a `-` opt-out or `experimental.: false` still wins, and neither `all` nor `all_flags` is a flag key. +- Flags default to on in local and dev builds and off in releases, except `optInOnly` flags (such as `full_codemode`), which require an explicit `OPENCODE_FLAGS=` or `experimental.: true` in every build. +- Say in the PR body which flag guards the change. The reserved switches `OPENCODE_FLAGS=all` and `experimental.all_flags: true` skip opt-in-only flags; use `all,-` or `experimental.: false` to opt out within the respective source. - Ship a feature by deleting its flag and the checks that read it. ## Testing diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index fc8133fb489..f0748c53651 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -2595,6 +2595,7 @@ export type ConfigEntry = artifacts?: boolean console_watches?: boolean mcp_events?: boolean + full_codemode?: boolean part_rows?: boolean image_generate?: boolean | { model?: string | { providerID: string; model: string; variant?: string } } subagent_depth?: number diff --git a/packages/core/src/flag.ts b/packages/core/src/flag.ts index f39a090b26e..3ee4b502b68 100644 --- a/packages/core/src/flag.ts +++ b/packages/core/src/flag.ts @@ -25,7 +25,7 @@ export class Service extends Context.Service()("@opencode/Fl /** * `OPENCODE_FLAGS`, a comma-separated list such as `schedules,-media_blob`; a leading `-` turns a flag off, and - * `all` turns every flag on unless the same list opts one out, as in `all,-media_blob`. + * `all` enables all flags except opt-in-only flags and any disabled in the same list, as in `all,-media_blob`. */ export const Overrides = Context.Reference("@opencode/Flag/Overrides", { defaultValue: () => process.env.OPENCODE_FLAGS, @@ -35,10 +35,11 @@ export const Overrides = Context.Reference("@opencode/Flag/O const onByDefault = (channel: string) => channel === "local" || channel === "dev" /** - * Resolves every flag: `OPENCODE_FLAGS` (`-key`, then `all`), then `experimental.` from the highest-priority + * Resolves every flag: `OPENCODE_FLAGS` (`key` or `-key`, then `all`), then `experimental.` from the highest-priority * document that sets `experimental` (the same document every other `experimental` setting reads), then `all_flags: true` * from the highest-priority document that sets `all_flags`, so a global switch survives a project's own `experimental` * block, then on for local and dev builds. `all_flags: false` falls through rather than turning flags off. + * Opt-in-only flags skip both wildcards and default to off on every channel. * A remote kill switch belongs above `OPENCODE_FLAGS` here. */ export function resolve(input: { @@ -60,14 +61,15 @@ export function resolve(input: { (entry): entry is Document => entry.type === "document" && entry.info.experimental?.all_flags !== undefined, )?.info.experimental?.all_flags === true return Record.map(ConfigFlag.registry, (_, key): State => { - const override = env.get(key) ?? (all ? true : undefined) - const configured = experimental?.[key] ?? (allFlags ? true : undefined) + const optInOnly = ConfigFlag.optInOnly.has(key) + const override = env.get(key) ?? (all && !optInOnly ? true : undefined) + const configured = experimental?.[key] ?? (allFlags && !optInOnly ? true : undefined) const [enabled, source]: [boolean, State["source"]] = override !== undefined ? [override, "env"] : configured !== undefined ? [configured, "config"] - : [onByDefault(input.channel), "default"] + : [!optInOnly && onByDefault(input.channel), "default"] return { enabled, source } }) } diff --git a/packages/core/test/config/normalization.test.ts b/packages/core/test/config/normalization.test.ts index 946a95cf375..aa32eea379f 100644 --- a/packages/core/test/config/normalization.test.ts +++ b/packages/core/test/config/normalization.test.ts @@ -617,8 +617,10 @@ describe("ConfigNormalize", () => { }) test("normalizes every registered flag as a boolean", () => { - const result = normalized({ experimental: { todo: true, media_blob: false, schedules: "yes" } }) - expect(result.encoded.experimental).toEqual({ todo: true, media_blob: false }) + const result = normalized({ + experimental: { todo: true, media_blob: false, schedules: "yes", full_codemode: true }, + }) + expect(result.encoded.experimental).toEqual({ todo: true, media_blob: false, full_codemode: true }) expect(result.diagnostics.map((item) => [item.kind, item.path])).toEqual([ ["invalid", ["experimental", "schedules"]], ]) diff --git a/packages/core/test/flag.test.ts b/packages/core/test/flag.test.ts index fbef2642bf2..93e1492a192 100644 --- a/packages/core/test/flag.test.ts +++ b/packages/core/test/flag.test.ts @@ -26,26 +26,38 @@ const document = (experimental?: ConstructorParameters Record.map(ConfigFlag.registry, () => state) +const implicit = (state: Flag.State): Record => ({ + ...Record.map(ConfigFlag.registry, () => state), + full_codemode: { enabled: false, source: "default" }, +}) describe("Flag.resolve", () => { - test("turns flags on by default only in local and dev builds", () => { - const table = ["local", "dev", "beta", "latest", "my-branch", "unknown"].map((channel) => [ - channel, - Flag.resolve({ entries: [], channel }).todo.enabled, - ]) - expect(Object.fromEntries(table)).toEqual({ - local: true, - dev: true, - beta: false, - latest: false, - "my-branch": false, - unknown: false, - }) + test.each([ + ["local", true], + ["dev", true], + ["beta", false], + ["latest", false], + ["my-branch", false], + ["unknown", false], + ] as const)("applies %s build defaults and leaves full_codemode off", (channel, enabled) => { + expect(Flag.resolve({ entries: [], channel })).toEqual(implicit({ enabled, source: "default" })) }) - test("every registered flag is off in a latest release build", () => { - expect(Flag.resolve({ entries: [], channel: "latest" })).toEqual(every({ enabled: false, source: "default" })) + test("full_codemode can be enabled or disabled by name", () => { + const channel = "latest" + const entries = [document({ full_codemode: true })] + expect(Flag.resolve({ entries: [], channel, overrides: "full_codemode" }).full_codemode).toEqual({ + enabled: true, + source: "env", + }) + expect(Flag.resolve({ entries, channel }).full_codemode).toEqual({ enabled: true, source: "config" }) + expect(Flag.resolve({ entries, channel, overrides: "-full_codemode" }).full_codemode).toEqual({ + enabled: false, + source: "env", + }) + expect( + Flag.resolve({ entries: [document({ full_codemode: false })], channel, overrides: "all" }).full_codemode, + ).toEqual({ enabled: false, source: "config" }) }) test("config overrides the default and OPENCODE_FLAGS overrides config", () => { @@ -69,13 +81,13 @@ describe("Flag.resolve", () => { expect([flags.todo.enabled, flags.todo.source]).toEqual([false, "default"]) }) - test("OPENCODE_FLAGS=all turns every flag on, and a -key in the same list still wins", () => { + test("OPENCODE_FLAGS=all skips opt-in-only flags, and a -key in the same list still wins", () => { const entries = [document({ media_blob: false })] expect(Flag.resolve({ entries, channel: "latest", overrides: "all" })).toEqual( - every({ enabled: true, source: "env" }), + implicit({ enabled: true, source: "env" }), ) expect(Flag.resolve({ entries: [], channel: "latest", overrides: " -media_blob , all, " })).toEqual({ - ...every({ enabled: true, source: "env" }), + ...implicit({ enabled: true, source: "env" }), media_blob: { enabled: false, source: "env" }, }) expect(Flag.resolve({ entries, channel: "latest", overrides: "-all" })).toEqual( @@ -83,10 +95,10 @@ describe("Flag.resolve", () => { ) }) - test("experimental.all_flags turns every flag on below OPENCODE_FLAGS and below a per-flag setting", () => { + test("experimental.all_flags skips opt-in-only flags and yields to OPENCODE_FLAGS and per-flag settings", () => { const entries = [document({ all_flags: true, media_blob: false })] expect(Flag.resolve({ entries, channel: "latest", overrides: "-artifacts" })).toEqual({ - ...every({ enabled: true, source: "config" }), + ...implicit({ enabled: true, source: "config" }), media_blob: { enabled: false, source: "config" }, artifacts: { enabled: false, source: "env" }, }) @@ -94,7 +106,7 @@ describe("Flag.resolve", () => { test("experimental.all_flags: false is not a kill switch, and all_flags in OPENCODE_FLAGS does nothing", () => { expect(Flag.resolve({ entries: [document({ all_flags: false })], channel: "dev" })).toEqual( - every({ enabled: true, source: "default" }), + implicit({ enabled: true, source: "default" }), ) expect(Flag.resolve({ entries: [], channel: "latest", overrides: "all_flags" })).toEqual( Flag.resolve({ entries: [], channel: "latest" }), @@ -105,9 +117,9 @@ describe("Flag.resolve", () => { const global = document({ all_flags: true }) expect( Flag.resolve({ entries: [global, document({ subagent_depth: 2, todo: false })], channel: "latest" }), - ).toEqual({ ...every({ enabled: true, source: "config" }), todo: { enabled: false, source: "config" } }) + ).toEqual({ ...implicit({ enabled: true, source: "config" }), todo: { enabled: false, source: "config" } }) expect(Flag.resolve({ entries: [global, document({ all_flags: false })], channel: "latest" })).toEqual( - every({ enabled: false, source: "default" }), + implicit({ enabled: false, source: "default" }), ) }) }) diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 8a95ff085ce..98161135b21 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -16677,6 +16677,9 @@ "mcp_events": { "type": "boolean" }, + "full_codemode": { + "type": "boolean" + }, "part_rows": { "type": "boolean" }, diff --git a/packages/schema/src/config/experimental.ts b/packages/schema/src/config/experimental.ts index d46710bcdcc..5e8fcf35350 100644 --- a/packages/schema/src/config/experimental.ts +++ b/packages/schema/src/config/experimental.ts @@ -15,11 +15,13 @@ export class Info extends Schema.Class("ConfigExperimental.Info")({ }), all_flags: Schema.Boolean.pipe(optional).annotate({ description: - "Turn every feature flag on regardless of the build channel, like OPENCODE_FLAGS=all; explicit per-flag settings still win, and false is not a kill switch.", + "Enable all flags except opt-in-only flags on any build channel, like OPENCODE_FLAGS=all. Per-flag config settings take precedence over all_flags; false leaves the build defaults in effect.", }), - ...Record.map(ConfigFlag.registry, (description) => + ...Record.map(ConfigFlag.registry, (description, key) => Schema.Boolean.pipe(optional).annotate({ - description: `${description} Defaults to on in local and dev builds and off in releases.`, + description: ConfigFlag.optInOnly.has(key) + ? description + : `${description} Defaults to on in local and dev builds and off in releases.`, }), ), part_rows: Schema.Boolean.pipe(optional).annotate({ diff --git a/packages/schema/src/config/flag.ts b/packages/schema/src/config/flag.ts index 3111d6f06bf..22001a1ae53 100644 --- a/packages/schema/src/config/flag.ts +++ b/packages/schema/src/config/flag.ts @@ -1,12 +1,11 @@ export * as ConfigFlag from "./flag.js" -/** The `OPENCODE_FLAGS` entry that turns every flag on, as in `all,-media_blob`. It is not a flag key. */ +/** The `OPENCODE_FLAGS` entry that enables all flags except opt-in-only flags, as in `all,-media_blob`. */ export const wildcard = "all" /** - * Every feature flag, by key, with what it turns on. A flag is on in local and dev builds and off in released ones; - * `experimental.` in config and `OPENCODE_FLAGS` override that, and `OPENCODE_FLAGS=all` or - * `experimental.all_flags: true` turn every flag on. Read one with Core's `Flag.enabled("")`. + * Flags default to on in local and dev builds and off in releases, except for `optInOnly` flags, which must be + * named explicitly in `experimental.` or `OPENCODE_FLAGS`. Read a flag with Core's `Flag.enabled("")`. */ export const registry = { todo: "Enable the experimental todowrite tool.", @@ -19,5 +18,9 @@ export const registry = { "Watch Slack threads, GitHub pull requests, issues, commits and Actions runs, and the workspace's MCP servers' events through OpenCode Console, and wake sessions when they change.", mcp_events: "Enable experimental MCP Events, a draft MCP extension: declare support to MCP servers and read the events of servers that offer them.", + full_codemode: + "Enable the full Code Mode work in progress. Off by default in every build, including local and dev; opt in with OPENCODE_FLAGS=full_codemode or experimental.full_codemode: true.", } as const satisfies Record export type Key = keyof typeof registry + +export const optInOnly: ReadonlySet = new Set(["full_codemode"]) diff --git a/packages/schema/test/config.test.ts b/packages/schema/test/config.test.ts index 37f9c94e596..8a89274f500 100644 --- a/packages/schema/test/config.test.ts +++ b/packages/schema/test/config.test.ts @@ -188,7 +188,7 @@ describe("Config.Entry", () => { }) }) -test("no flag is named after the everything-on switches", () => { +test("wildcard switches are reserved flag names", () => { expect(ConfigFlag.registry).not.toHaveProperty("all_flags") expect(ConfigFlag.registry).not.toHaveProperty(ConfigFlag.wildcard) })