diff --git a/AGENTS.md b/AGENTS.md index 3888d138060..7fdbe171b15 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -182,8 +182,10 @@ const table = sqliteTable("session", { ### Feature Flags +- 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. - 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 73c6bbd3af2..34bfca3f712 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -2545,6 +2545,7 @@ export type ConfigEntry = } experimental?: { portable_shell_scanner?: boolean + all_flags?: boolean todo?: boolean background_compaction?: boolean media_blob?: boolean diff --git a/packages/core/src/flag.ts b/packages/core/src/flag.ts index 118c9dd78fe..7b28160c3fc 100644 --- a/packages/core/src/flag.ts +++ b/packages/core/src/flag.ts @@ -2,7 +2,7 @@ export * as Flag from "./flag.js" import { Context, Effect, Option, Record } from "effect" import { ConfigFlag } from "@opencode/schema/config/flag" -import type { Entry } from "@opencode/schema/config" +import type { Document, Entry } from "@opencode/schema/config" import { App } from "./app.js" import { Config } from "./config.js" @@ -14,7 +14,10 @@ export interface State { readonly source: "env" | "config" | "default" } -/** `OPENCODE_FLAGS`, a comma-separated list such as `schedules,-media_blob`; a leading `-` turns a flag off. */ +/** + * `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`. + */ export const Overrides = Context.Reference("@opencode/Flag/Overrides", { defaultValue: () => process.env.OPENCODE_FLAGS, }) @@ -23,8 +26,10 @@ export const Overrides = Context.Reference("@opencode/Flag/O const onByDefault = (channel: string) => channel === "local" || channel === "dev" /** - * Resolves every flag: `OPENCODE_FLAGS`, then `experimental.` from the highest-priority document that sets - * `experimental` (the same document every other `experimental` setting reads), then on for local and dev builds. + * Resolves every flag: `OPENCODE_FLAGS` (`-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. * A remote kill switch belongs above `OPENCODE_FLAGS` here. */ export function resolve(input: { @@ -39,10 +44,15 @@ export function resolve(input: { .filter(Boolean) .map((item): [string, boolean] => (item.startsWith("-") ? [item.slice(1), false] : [item, true])), ) + const all = env.get(ConfigFlag.wildcard) === true const experimental = Config.latest(input.entries, "experimental") + const allFlags = + input.entries.findLast( + (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) - const configured = experimental?.[key] + const override = env.get(key) ?? (all ? true : undefined) + const configured = experimental?.[key] ?? (allFlags ? true : undefined) const [enabled, source]: [boolean, State["source"]] = override !== undefined ? [override, "env"] diff --git a/packages/core/test/config/normalization.test.ts b/packages/core/test/config/normalization.test.ts index eed91b86a03..ceea5010c0d 100644 --- a/packages/core/test/config/normalization.test.ts +++ b/packages/core/test/config/normalization.test.ts @@ -608,6 +608,16 @@ describe("ConfigNormalize", () => { ]) }) + test("passes experimental.all_flags through as a boolean", () => { + expect(normalized({ experimental: { all_flags: true } }).encoded.experimental).toEqual({ all_flags: true }) + expect(normalized({ experimental: { all_flags: false } }).encoded.experimental).toEqual({ all_flags: false }) + const invalid = normalized({ experimental: { all_flags: "yes" } }) + expect(invalid.encoded.experimental).toBeUndefined() + expect(invalid.diagnostics.map((item) => [item.kind, item.path])).toEqual([ + ["invalid", ["experimental", "all_flags"]], + ]) + }) + test("never emits experimental policies", () => { expect( normalized({ experimental: { policies: [{ action: "provider.use", resource: "*", effect: "deny" }] } }).encoded, diff --git a/packages/core/test/flag.test.ts b/packages/core/test/flag.test.ts index ed80984db1b..f49b6718964 100644 --- a/packages/core/test/flag.test.ts +++ b/packages/core/test/flag.test.ts @@ -4,7 +4,8 @@ import { Config } from "@opencode/core/config" import { Flag } from "@opencode/core/flag" import { Document, Info } from "@opencode/schema/config" import { ConfigExperimental } from "@opencode/schema/config/experimental" -import { Effect, Layer } from "effect" +import { ConfigFlag } from "@opencode/schema/config/flag" +import { Effect, Layer, Record } from "effect" import { testEffect } from "./lib/effect" const document = (experimental?: ConstructorParameters[0]) => @@ -13,6 +14,8 @@ const document = (experimental?: ConstructorParameters Record.map(ConfigFlag.registry, () => state) + 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) => [ @@ -49,6 +52,48 @@ 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", () => { + const entries = [document({ media_blob: false })] + expect(Flag.resolve({ entries, channel: "latest", overrides: "all" })).toEqual( + every({ enabled: true, source: "env" }), + ) + expect(Flag.resolve({ entries: [], channel: "latest", overrides: " -media_blob , all, " })).toEqual({ + ...every({ enabled: true, source: "env" }), + media_blob: { enabled: false, source: "env" }, + }) + expect(Flag.resolve({ entries, channel: "latest", overrides: "-all" })).toEqual( + Flag.resolve({ entries, channel: "latest" }), + ) + }) + + test("experimental.all_flags turns every flag on below OPENCODE_FLAGS and below a per-flag setting", () => { + const entries = [document({ all_flags: true, media_blob: false })] + expect(Flag.resolve({ entries, channel: "latest", overrides: "-artifacts" })).toEqual({ + ...every({ enabled: true, source: "config" }), + media_blob: { enabled: false, source: "config" }, + artifacts: { enabled: false, source: "env" }, + }) + }) + + 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" }), + ) + expect(Flag.resolve({ entries: [], channel: "latest", overrides: "all_flags" })).toEqual( + Flag.resolve({ entries: [], channel: "latest" }), + ) + }) + + test("a global all_flags survives a project experimental block, and a project all_flags: false stops it", () => { + 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" } }) + expect(Flag.resolve({ entries: [global, document({ all_flags: false })], channel: "latest" })).toEqual( + every({ enabled: false, source: "default" }), + ) + }) }) const it = testEffect( diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index b45a7a289a8..7d743594ea1 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -16655,6 +16655,9 @@ "portable_shell_scanner": { "type": "boolean" }, + "all_flags": { + "type": "boolean" + }, "todo": { "type": "boolean" }, diff --git a/packages/schema/src/config/experimental.ts b/packages/schema/src/config/experimental.ts index 0c7428e8434..760633510ed 100644 --- a/packages/schema/src/config/experimental.ts +++ b/packages/schema/src/config/experimental.ts @@ -10,6 +10,10 @@ export class Info extends Schema.Class("ConfigExperimental.Info")({ portable_shell_scanner: Schema.Boolean.pipe(optional).annotate({ description: "Deprecated: the built-in shell permission scanner is now always enabled.", }), + 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.", + }), ...Record.map(ConfigFlag.registry, (description) => Schema.Boolean.pipe(optional).annotate({ description: `${description} Defaults to on in local and dev builds and off in releases.`, diff --git a/packages/schema/src/config/flag.ts b/packages/schema/src/config/flag.ts index 948524c93ad..8bfe2f9f974 100644 --- a/packages/schema/src/config/flag.ts +++ b/packages/schema/src/config/flag.ts @@ -1,8 +1,12 @@ 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. */ +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. Read one with Core's `Flag.enabled("")`. + * `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("")`. */ export const registry = { todo: "Enable the experimental todowrite tool.", diff --git a/packages/schema/test/config.test.ts b/packages/schema/test/config.test.ts index 0eb35d73429..37f9c94e596 100644 --- a/packages/schema/test/config.test.ts +++ b/packages/schema/test/config.test.ts @@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test" import { Schema } from "effect" import { Config } from "../src/config.js" import { ConfigAgent } from "../src/config/agent.js" +import { ConfigFlag } from "../src/config/flag.js" import { ConfigMCP } from "../src/config/mcp.js" import { ConfigPolicy } from "../src/config/policy.js" import { ConfigProvider } from "../src/config/provider.js" @@ -186,3 +187,8 @@ describe("Config.Entry", () => { expect(encoded.info.providers?.custom).not.toHaveProperty("canonical") }) }) + +test("no flag is named after the everything-on switches", () => { + expect(ConfigFlag.registry).not.toHaveProperty("all_flags") + expect(ConfigFlag.registry).not.toHaveProperty(ConfigFlag.wildcard) +})