@golden-frijoles/cli 0.1.0

package/dist/commands/flags-read.d.ts

@@ -0,0 +1,71 @@
+import type { Command, CommandContext } from '../command';
+import { type ExitCode } from '../exit-codes';
+export type CliFlagEnvironment = {
+    environment: string;
+    state: 'on' | 'off' | 'never';
+    version: number | null;
+    serving: unknown;
+    readable: boolean;
+    updatedAt: string | null;
+};
+export type CliFlag = {
+    key: string;
+    valueType: string | null;
+    description: string | null;
+    latestVersion: number | null;
+    environments: CliFlagEnvironment[];
+};
+export type FlagsListBody = {
+    project: string;
+    flags: CliFlag[];
+    environments: Array<{
+        environment: string;
+        snapshotVersion: number;
+        updatedAt: string;
+    }>;
+};
+export type FlagDetailBody = {
+    project: string;
+    flag: CliFlag & {
+        versions: Array<{
+            version: number;
+            versionId: string;
+            createdAt: string;
+            definition: unknown;
+            servedBy: string[];
+        }>;
+        audit: Array<{
+            action: string;
+            environment: string | null;
+            reason: string;
+            createdAt: string;
+            actor: string;
+        }>;
+    };
+    environments: Array<{
+        environment: string;
+        snapshotVersion: number;
+        updatedAt: string;
+    }>;
+};
+/**
+ * The project this command acts on: `--project`, else the remembered one.
+ *
+ * Returns null rather than guessing. A CLI that picked "the first project" when none was chosen
+ * would act on a tenant the caller did not name, which is the one mistake a multi-tenant tool must
+ * not make quietly.
+ */
+export declare function resolveProject(context: CommandContext): string | null;
+export declare function missingProject(context: CommandContext): ExitCode;
+/**
+ * What an environment is serving, as ONE cell of text.
+ *
+ * ⚠️ Three outcomes, and collapsing any two of them would be the defect this whole area of the
+ * product exists to stop making:
+ *   • `never` / `off` — nothing is served here. The consumer falls back to its own literal.
+ *   • a value — what a context with no attributes actually gets, from the SDK's own evaluator.
+ *   • `unreadable` — the stored row disagrees with the parser that wrote it. Never a guess.
+ */
+export declare function describeServing(row: CliFlagEnvironment): string;
+export declare const flagsLsCommand: Command;
+export declare const flagsGetCommand: Command;

package/dist/commands/flags-read.js

@@ -0,0 +1,124 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.5 — `gf flags ls` and `gf flags get`.
+//
+// Read-only. Every write verb lands in Sprint 2 and goes through the shared command core; nothing
+// in this file plans or posts anything.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flagsGetCommand = exports.flagsLsCommand = void 0;
+exports.resolveProject = resolveProject;
+exports.missingProject = missingProject;
+exports.describeServing = describeServing;
+const args_1 = require("../args");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+/**
+ * The project this command acts on: `--project`, else the remembered one.
+ *
+ * Returns null rather than guessing. A CLI that picked "the first project" when none was chosen
+ * would act on a tenant the caller did not name, which is the one mistake a multi-tenant tool must
+ * not make quietly.
+ */
+function resolveProject(context) {
+    return (0, args_1.flagValue)(context.args, 'project')?.trim() || context.auth.activeProject || null;
+}
+function missingProject(context) {
+    context.emit.fail('invalid', 'No project chosen. Pass --project <slug>, or run `gf projects use <slug>`.');
+    return exit_codes_1.EXIT.USAGE;
+}
+/**
+ * What an environment is serving, as ONE cell of text.
+ *
+ * ⚠️ Three outcomes, and collapsing any two of them would be the defect this whole area of the
+ * product exists to stop making:
+ *   • `never` / `off` — nothing is served here. The consumer falls back to its own literal.
+ *   • a value — what a context with no attributes actually gets, from the SDK's own evaluator.
+ *   • `unreadable` — the stored row disagrees with the parser that wrote it. Never a guess.
+ */
+function describeServing(row) {
+    if (row.state === 'never')
+        return '—';
+    if (row.state === 'off')
+        return 'off (nothing served)';
+    if (!row.readable)
+        return 'unreadable';
+    return `${JSON.stringify(row.serving)}  v${row.version}`;
+}
+exports.flagsLsCommand = {
+    path: ['flags', 'ls'],
+    summary: 'every flag, and what each environment serves',
+    usage: 'gf flags ls [--project <slug>] [--json]',
+    needsAuth: true,
+    detail: `The "serving" column is what a context with no attributes actually GETS — the
+  answer the SDK's own evaluator gives, which is the answer production gives.
+
+  ⚠️ It is NOT the same as "a version is activated here". A definition whose default
+  variant is false is activated AND serves false; reporting those as one fact is how a
+  console once labelled 34 of 42 flags the wrong way round.`,
+    flags: [{ name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' }],
+    async run(context) {
+        const project = resolveProject(context);
+        if (!project)
+            return missingProject(context);
+        const result = await context.api.get('api/v1/cli/flags', { project });
+        if (result.kind === 'network') {
+            context.emit.fail('server_error', result.message);
+            return exit_codes_1.EXIT.SERVER;
+        }
+        if (result.kind === 'error') {
+            context.emit.fail(result.code, result.message);
+            return (0, exit_codes_1.exitForServerCode)(result.code);
+        }
+        const { flags, environments } = result.body;
+        context.emit.ok({ project, flags, environments }, flags.length === 0
+            ? `No flags in ${project} yet. Create one with \`gf flags create <key> --kill-switch --all-envs\`.`
+            : (0, output_1.table)(['FLAG', 'TYPE', 'DEVELOPMENT', 'PREVIEW', 'PRODUCTION'], flags.map((flag) => [
+                flag.key,
+                flag.valueType ?? '—',
+                ...['development', 'preview', 'production'].map((environment) => {
+                    const row = flag.environments.find((candidate) => candidate.environment === environment);
+                    return row ? describeServing(row) : '—';
+                }),
+            ])));
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.flagsGetCommand = {
+    path: ['flags', 'get'],
+    summary: 'one flag: its definition, its versions and who changed it',
+    usage: 'gf flags get <key> [--project <slug>] [--json]',
+    needsAuth: true,
+    flags: [{ name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' }],
+    async run(context) {
+        const key = context.args.positionals[0];
+        if (!key) {
+            context.emit.fail('invalid', 'Name a flag: `gf flags get <key>`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const project = resolveProject(context);
+        if (!project)
+            return missingProject(context);
+        const result = await context.api.get('api/v1/cli/flags', { project, key });
+        if (result.kind === 'network') {
+            context.emit.fail('server_error', result.message);
+            return exit_codes_1.EXIT.SERVER;
+        }
+        if (result.kind === 'error') {
+            context.emit.fail(result.code, result.message);
+            return (0, exit_codes_1.exitForServerCode)(result.code);
+        }
+        const { flag } = result.body;
+        context.emit.ok({ project, flag }, [
+            `${flag.key}  (${flag.valueType ?? 'unknown type'})`,
+            flag.description ?? '',
+            '',
+            (0, output_1.table)(['ENVIRONMENT', 'SERVING', 'SINCE'], flag.environments.map((row) => [row.environment, describeServing(row), row.updatedAt ?? '—'])),
+            '',
+            (0, output_1.table)(['VERSION', 'CREATED', 'SERVED BY'], flag.versions.map((version) => [
+                `v${version.version}`,
+                version.createdAt,
+                version.servedBy.join(', ') || '—',
+            ])),
+        ].join('\n'));
+        return exit_codes_1.EXIT.OK;
+    },
+};

package/dist/commands/flags-sync.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../command';
+export declare const flagsSyncCommand: Command;

package/dist/commands/flags-sync.js

@@ -0,0 +1,129 @@
+"use strict";
+// golden-frijoles-cli · Sprint 2, Story 2.5 — `gf flags sync`, the catalog bridge.
+//
+// ── It uses a DIFFERENT credential, and that is the whole design of this verb ─────────────────
+// Every other write verb rides the CLI's PAT. This one rides a `flag_sync` key, because the thing
+// it is bridging is a CI job publishing a catalog out of source control — a job that must not hold
+// a credential that can also roll out or kill a flag. `lib/credential-inventory.ts` models exactly
+// that difference: "create flag definitions from an outside catalog; CANNOT turn a flag on or off
+// in any environment."
+//
+// So the key comes from `--sync-key` or `GOLDEN_FRIJOLES_FLAG_SYNC_KEY`, and the PAT is not a
+// fallback. Falling back would quietly hand a pipeline the wider credential the moment someone
+// forgot to set the narrower one — which is the failure mode the split exists to prevent.
+//
+// ── It wraps the SHIPPED client, it does not reimplement the protocol ─────────────────────────
+// `createFlagDefinitionSyncClient` from `@golden-frijoles/sdk` owns the request shape, the entry
+// cap and the body limit. A second implementation here would drift from the route the first time
+// either changed.
+//
+// ── Sync NEVER activates, and this verb says so ───────────────────────────────────────────────
+// The route does not activate, by design — a catalog import creates immutable definition versions
+// and nothing else. A CLI that printed "synced" and left the reader assuming production had changed
+// would be papering over that, so the output names it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flagsSyncCommand = void 0;
+const node_fs_1 = require("node:fs");
+const sdk_1 = require("@golden-frijoles/sdk");
+const args_1 = require("../args");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+exports.flagsSyncCommand = {
+    path: ['flags', 'sync'],
+    summary: 'publish a flag catalog from source control',
+    usage: 'gf flags sync --file flags.json [--dry-run]',
+    needsAuth: false,
+    detail: `Uses a flag_sync key — NOT your CLI token — from --sync-key or
+  GOLDEN_FRIJOLES_FLAG_SYNC_KEY. There is deliberately no fallback to the CLI token: a
+  pipeline that forgot to set the narrow credential must fail, not quietly get the wide one.
+
+  Mint one with: gf keys create --type flag_sync --source <name> --label <text>
+
+  ⚠️ Sync NEVER activates, deactivates or deletes a flag. It creates immutable definition
+  versions. A key that already exists with an identical definition reports created: false;
+  semantic drift from an existing version is a conflict for an owner to resolve through the
+  normal version lifecycle.`,
+    flags: [
+        { name: 'file', value: '<path>', describe: 'a JSON array of { key, definition } entries' },
+        { name: 'sync-key', value: '<key>', describe: 'the flag_sync credential (or set the env var)' },
+        { name: 'dry-run', describe: 'parse and report, send nothing' },
+    ],
+    async run(context) {
+        const path = (0, args_1.flagValue)(context.args, 'file');
+        if (!path) {
+            context.emit.fail('invalid', 'Usage: `gf flags sync --file flags.json`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        let catalog;
+        try {
+            catalog = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        }
+        catch (err) {
+            context.emit.fail('invalid', `Could not read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+            return exit_codes_1.EXIT.USAGE;
+        }
+        if (!Array.isArray(catalog)) {
+            context.emit.fail('invalid', `${path} must contain a JSON ARRAY of { key, definition } entries.`);
+            return exit_codes_1.EXIT.USAGE;
+        }
+        if ((0, args_1.boolFlag)(context.args, 'dry-run')) {
+            // Reports what WOULD be sent and sends nothing — including no credential, which is why the
+            // key check is below this branch: a dry run is useful precisely when you have not wired the
+            // credential up yet.
+            context.emit.ok({
+                dryRun: true,
+                file: path,
+                entries: catalog.length,
+                keys: catalog.map((entry) => entry.key ?? null),
+            }, `${catalog.length} entr${catalog.length === 1 ? 'y' : 'ies'} in ${path}. Nothing was sent.`);
+            return exit_codes_1.EXIT.OK;
+        }
+        const syncKey = (0, args_1.flagValue)(context.args, 'sync-key')?.trim() || context.env.GOLDEN_FRIJOLES_FLAG_SYNC_KEY?.trim();
+        if (!syncKey) {
+            context.emit.fail('unauthorized', 'A flag_sync credential is required — pass --sync-key or set GOLDEN_FRIJOLES_FLAG_SYNC_KEY. ' +
+                'Your CLI token is deliberately NOT accepted here: catalog publishing gets the narrower key.');
+            return exit_codes_1.EXIT.AUTH;
+        }
+        const client = (0, sdk_1.createFlagDefinitionSyncClient)({ baseUrl: context.auth.apiUrl, flagSyncKey: syncKey });
+        const result = await client.syncFlagDefinitions(catalog);
+        if (!result.ok) {
+            // `kind` is the SDK's own vocabulary for what went wrong, and it is deliberately NOT the same
+            // vocabulary as this CLI's exit codes — mapping between them is this file's job.
+            //
+            // The mapping turns on the HTTP status for `kind: 'http'`, because that is where the two
+            // outcomes an agent can act on differently live: a 409 is catalog DRIFT (an existing immutable
+            // version disagrees with the file — resolvable by the caller, exit 4), and a 401 is the sync
+            // credential (exit 2). Everything else is exit 6. `validation` is the caller's file and never
+            // reached the network at all, so it is a usage error.
+            const code = result.kind === 'validation'
+                ? exit_codes_1.EXIT.USAGE
+                : result.kind === 'http' && result.status === 409
+                    ? exit_codes_1.EXIT.CONFLICT
+                    : result.kind === 'http' && result.status === 401
+                        ? exit_codes_1.EXIT.AUTH
+                        : exit_codes_1.EXIT.SERVER;
+            context.emit.fail(result.kind, result.error, 
+            // The parser's own messages, verbatim, when it has any. An agent branches on these; folding
+            // them into the sentence would turn a list into prose.
+            'issues' in result && result.issues !== undefined ? { issues: result.issues } : undefined);
+            return code;
+        }
+        const created = result.entries.filter((entry) => entry.created);
+        context.emit.ok({ file: path, entries: result.entries }, [
+            `${created.length} new definition version${created.length === 1 ? '' : 's'} from ${result.entries.length} entr${result.entries.length === 1 ? 'y' : 'ies'}.`,
+            '',
+            (0, output_1.table)(['FLAG', 'VERSION', 'RESULT'], result.entries.map((entry) => [
+                entry.key,
+                `v${entry.definitionVersion}`,
+                // `created: false` is an identical no-op, NOT a failure — the route is idempotent by
+                // design and re-running a pipeline must not read as "nothing worked".
+                entry.created ? 'created' : 'unchanged',
+            ])),
+            '',
+            // Said every time, not only when something changed. The absence of this line is how someone
+            // concludes a sync turned a flag on.
+            'Sync creates definitions only. Nothing was activated — use `gf flags set` or `gf flags create --all-envs` for that.',
+        ].join('\n'));
+        return exit_codes_1.EXIT.OK;
+    },
+};

package/dist/commands/flags-write.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from '../command';
+export declare const flagsCreateCommand: Command;
+export declare const flagsSetCommand: Command;
+export declare const flagsRolloutCommand: Command;
+export declare const flagsRulesCommand: Command;
+export declare const flagsKillCommand: Command;

package/dist/commands/flags-write.js

@@ -0,0 +1,311 @@
+"use strict";
+// golden-frijoles-cli · Sprint 2 — the write verbs.
+//
+// ── Every one of these is a thin shell ────────────────────────────────────────────────────────
+// Parse flags, post one request, render the D2 report. The DECISIONS — what a kill-switch serves,
+// what killing clears, whether 150 is a percent — all live in `@golden-frijoles/sdk`'s planners and
+// run server-side. That is D4: this file and the MCP write tools are two callers of one brain, so
+// they cannot disagree, and there is nothing here for them to disagree with.
+//
+// ── The exit code comes from the BODY, not the status ─────────────────────────────────────────
+// A partial answers 200, because the definition version was created and some environments did
+// change — a 4xx would tell a caller nothing happened when something did, and a caller who retried
+// on that basis would create a second version. So `outcome: 'partial'` is what produces EXIT.PARTIAL.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flagsKillCommand = exports.flagsRulesCommand = exports.flagsRolloutCommand = exports.flagsSetCommand = exports.flagsCreateCommand = void 0;
+const node_fs_1 = require("node:fs");
+const sdk_1 = require("@golden-frijoles/sdk");
+const args_1 = require("../args");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+const flags_read_1 = require("./flags-read");
+/** `--env` (repeatable) and `--all-envs`, shared by every write verb. */
+const ENVIRONMENT_FLAGS = [
+    { name: 'env', value: '<environment>', describe: 'development | preview | production (repeatable)' },
+    { name: 'all-envs', describe: 'all three environments, under the partial-failure contract' },
+    { name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' },
+    { name: 'reason', value: '<text>', describe: 'why — it goes in the audit trail (default: "via gf")' },
+];
+/**
+ * The environments a write names.
+ *
+ * ⚠️ `--all-envs` and `--env` together is a USAGE ERROR, not a union. A caller who typed both meant
+ * one of them, and picking either silently is how a change reaches an environment nobody named.
+ */
+function resolveEnvironments(context) {
+    const named = (0, args_1.flagValues)(context.args, 'env');
+    const all = (0, args_1.boolFlag)(context.args, 'all-envs');
+    if (all && named.length > 0)
+        return { error: '--all-envs and --env say different things. Pass one of them, not both.' };
+    if (all)
+        return { allEnvs: true };
+    if (named.length === 0)
+        return {
+            error: `Name an environment with --env (${sdk_1.FLAG_ENVIRONMENTS.join(' | ')}), or use --all-envs.`,
+        };
+    const invalid = named.filter((value) => !sdk_1.FLAG_ENVIRONMENTS.includes(value));
+    if (invalid.length > 0)
+        return { error: `Not an environment: ${invalid.join(', ')}. Use ${sdk_1.FLAG_ENVIRONMENTS.join(', ')}.` };
+    return { environments: named };
+}
+/** Post a write and render the D2 report. The one place a write verb talks to the server. */
+async function submit(context, key, payload, humanVerb) {
+    const project = (0, flags_read_1.resolveProject)(context);
+    if (!project)
+        return (0, flags_read_1.missingProject)(context);
+    const environments = resolveEnvironments(context);
+    if ('error' in environments) {
+        context.emit.fail('invalid', environments.error);
+        return exit_codes_1.EXIT.USAGE;
+    }
+    const result = await context.api.post('api/v1/cli/flags/write', {
+        project,
+        key,
+        reason: (0, args_1.flagValue)(context.args, 'reason')?.trim() || 'via gf',
+        ...environments,
+        ...payload,
+    });
+    if (result.kind === 'network') {
+        context.emit.fail('server_error', result.message);
+        return exit_codes_1.EXIT.SERVER;
+    }
+    if (result.kind === 'error') {
+        context.emit.fail(result.code, result.message, result.body.issues ? { issues: result.body.issues } : undefined);
+        return (0, exit_codes_1.exitForServerCode)(result.code);
+    }
+    const body = result.body;
+    context.emit.ok({ project, ...body }, [
+        `${humanVerb} ${body.flagKey} — v${body.version}, serving ${JSON.stringify(body.serving)}`,
+        '',
+        (0, output_1.table)(['ENVIRONMENT', 'RESULT', 'SNAPSHOT'], body.environments.map((row) => [
+            row.environment,
+            row.error ? `${row.status}: ${row.error}` : row.status,
+            row.snapshotVersion === null ? '—' : String(row.snapshotVersion),
+        ])),
+    ].join('\n'));
+    // ⚠️ D2. `partial` is neither a success nor a clean failure — some environments changed and some
+    // did not — and a CLI with no code for it forces the caller to parse prose. The version WAS
+    // created in every case, which is why this is never EXIT.OK.
+    return body.outcome === 'partial' ? exit_codes_1.EXIT.PARTIAL : exit_codes_1.EXIT.OK;
+}
+exports.flagsCreateCommand = {
+    path: ['flags', 'create'],
+    summary: 'create a flag, with a polarity, in the environments you name',
+    usage: 'gf flags create <key> --kill-switch|--enablement --all-envs',
+    needsAuth: true,
+    detail: `Polarity decides what the flag serves on the day it is born, and the CLI derives the
+  default variant AND the activation from it — so the wrong combination cannot be typed:
+
+    --kill-switch   default "on",  serves TRUE  everywhere    (it is on until you kill it)
+    --enablement    default "off", serves FALSE everywhere    (you open it deliberately later)
+
+  ⚠️ BOTH polarities ACTIVATE. A flag that is not activated is absent from the environment's
+  snapshot, so your app falls back to its own literal and the flag is invisible in the
+  provider — which is the failure this tool exists to end. "Disabled" means serving false.
+
+  For a non-boolean flag use --type with --variants and --default; polarity does not apply,
+  because "which way is off?" has no answer for a string.`,
+    flags: [
+        ...ENVIRONMENT_FLAGS,
+        { name: 'kill-switch', describe: 'born serving true — the incident switch' },
+        { name: 'enablement', describe: 'born serving false — the gate you open later' },
+        { name: 'description', value: '<text>', describe: 'what the flag is for' },
+        { name: 'type', value: '<type>', describe: 'string | number | json (omit for a boolean)' },
+        { name: 'variants', value: '<json>', describe: 'a JSON array of {key,value} — with --type' },
+        { name: 'default', value: '<key>', describe: 'which variant is served by default — with --type' },
+    ],
+    async run(context) {
+        const key = context.args.positionals[0];
+        if (!key) {
+            context.emit.fail('invalid', 'Name a flag: `gf flags create <key> --kill-switch --all-envs`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const killSwitch = (0, args_1.boolFlag)(context.args, 'kill-switch');
+        const enablement = (0, args_1.boolFlag)(context.args, 'enablement');
+        const type = (0, args_1.flagValue)(context.args, 'type');
+        if (killSwitch && enablement) {
+            // The one combination the planner's input type cannot forbid, because the command line can
+            // carry both words. Refused here so it never reaches a planner that would have to pick.
+            context.emit.fail('invalid', 'A flag is a kill-switch or an enablement, not both.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        if (type !== undefined) {
+            if (killSwitch || enablement) {
+                context.emit.fail('invalid', 'Polarity is a boolean concept — "which way is off?" has no answer for a ' +
+                    `${type} flag. Use --variants and --default instead.`);
+                return exit_codes_1.EXIT.USAGE;
+            }
+            const rawVariants = (0, args_1.flagValue)(context.args, 'variants');
+            const defaultVariantKey = (0, args_1.flagValue)(context.args, 'default');
+            if (!rawVariants || !defaultVariantKey) {
+                context.emit.fail('invalid', '--type needs --variants \'[{"key":"a","value":1}]\' and --default <key>.');
+                return exit_codes_1.EXIT.USAGE;
+            }
+            let variants;
+            try {
+                variants = JSON.parse(rawVariants);
+            }
+            catch {
+                context.emit.fail('invalid', '--variants must be valid JSON.');
+                return exit_codes_1.EXIT.USAGE;
+            }
+            return submit(context, key, {
+                command: 'create',
+                valueType: type,
+                variants,
+                defaultVariantKey,
+                description: (0, args_1.flagValue)(context.args, 'description') ?? '',
+            }, 'Created');
+        }
+        if (!killSwitch && !enablement) {
+            // No default polarity, on purpose. Guessing "enablement" would create a flag serving `false`
+            // for someone who meant a kill-switch, and the two are opposites on the day they matter.
+            context.emit.fail('invalid', 'Say which kind of flag this is: --kill-switch (born on) or --enablement (born off).');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        return submit(context, key, {
+            command: 'create',
+            polarity: killSwitch ? 'kill-switch' : 'enablement',
+            description: (0, args_1.flagValue)(context.args, 'description') ?? '',
+        }, 'Created');
+    },
+};
+exports.flagsSetCommand = {
+    path: ['flags', 'set'],
+    summary: 'change which variant a flag serves by default',
+    usage: 'gf flags set <key> --value true|false --env production',
+    needsAuth: true,
+    detail: `--value true|false is shorthand for the "on" / "off" variants every flag \`gf flags
+  create\` makes. For a flag created elsewhere, or a non-boolean one, name the variant with
+  --variant; the server lists the real variant keys if the one you name is not there.
+
+  Rules are carried across untouched. A set that quietly dropped a targeting rule would be
+  the worst kind of surprise on a flag someone is mid-rollout on — use \`gf flags kill\` when
+  clearing the rules is what you mean.`,
+    flags: [
+        ...ENVIRONMENT_FLAGS,
+        { name: 'value', value: 'true|false', describe: 'shorthand for the on / off variant' },
+        { name: 'variant', value: '<key>', describe: 'the variant to serve, by name' },
+    ],
+    async run(context) {
+        const key = context.args.positionals[0];
+        if (!key) {
+            context.emit.fail('invalid', 'Name a flag: `gf flags set <key> --value true --env production`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const variant = (0, args_1.flagValue)(context.args, 'variant');
+        const value = (0, args_1.flagValue)(context.args, 'value');
+        if (variant && value) {
+            context.emit.fail('invalid', '--value and --variant say the same thing two ways. Pass one.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        let variantKey = variant;
+        if (value !== undefined) {
+            const normalized = value.trim().toLowerCase();
+            if (normalized !== 'true' && normalized !== 'false') {
+                context.emit.fail('invalid', '--value takes true or false. For anything else use --variant <key>.');
+                return exit_codes_1.EXIT.USAGE;
+            }
+            // The SDK's own constants, not the literals 'on'/'off' — `create` writes these exact keys, so
+            // a typo in either place would produce a `set` that silently misses.
+            variantKey = normalized === 'true' ? sdk_1.ON_VARIANT_KEY : sdk_1.OFF_VARIANT_KEY;
+        }
+        if (!variantKey) {
+            context.emit.fail('invalid', 'Say what to serve: --value true|false, or --variant <key>.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        return submit(context, key, { command: 'set', variantKey }, 'Set');
+    },
+};
+exports.flagsRolloutCommand = {
+    path: ['flags', 'rollout'],
+    summary: 'serve a flag to a percentage of contexts',
+    usage: 'gf flags rollout <key> --percent 25 --env production',
+    needsAuth: true,
+    detail: `⚠️ REPLACES the rule list with one unconditional rollout rule, and says so here rather
+  than surprising you. An unconditional rollout beside existing clause rules is ambiguous
+  about which one wins at a glance, and "ambiguous at a glance" is what an operator reaches
+  for at 3am. Use \`gf flags rules --rules-file\` to compose several.
+
+  --percent is rejected, never clamped: 150 is a typo, and agreeing with a typo is worse
+  than refusing it. 0 and 100 are exactly expressible.`,
+    flags: [
+        ...ENVIRONMENT_FLAGS,
+        { name: 'percent', value: '<0-100>', describe: 'the share of matching contexts served' },
+        { name: 'variant', value: '<key>', describe: 'which variant to roll out (default: on)' },
+    ],
+    async run(context) {
+        const key = context.args.positionals[0];
+        const raw = (0, args_1.flagValue)(context.args, 'percent');
+        if (!key || raw === undefined) {
+            context.emit.fail('invalid', 'Usage: `gf flags rollout <key> --percent <0-100> --env production`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const percent = Number(raw);
+        if (!Number.isFinite(percent)) {
+            context.emit.fail('invalid', '--percent takes a number from 0 to 100.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        return submit(context, key, { command: 'rollout', percent, variantKey: (0, args_1.flagValue)(context.args, 'variant') }, 'Rolled out');
+    },
+};
+exports.flagsRulesCommand = {
+    path: ['flags', 'rules'],
+    summary: 'replace a flag’s targeting rules from a file',
+    usage: 'gf flags rules <key> --rules-file rules.json --env production',
+    needsAuth: true,
+    detail: `A FILE, never a command-line expression language. A rule DSL is the appetite trap
+  this epic named, and a file has a property that matters more: rules live in source
+  control, reviewed, beside the code they target.
+
+  The file is a JSON array of rules. The caps come from the SDK's own constants, so the CLI
+  and the parser cannot disagree about how many rules a flag may have.`,
+    flags: [...ENVIRONMENT_FLAGS, { name: 'rules-file', value: '<path>', describe: 'a JSON array of rules' }],
+    async run(context) {
+        const key = context.args.positionals[0];
+        const path = (0, args_1.flagValue)(context.args, 'rules-file');
+        if (!key || !path) {
+            context.emit.fail('invalid', 'Usage: `gf flags rules <key> --rules-file rules.json --env production`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        let rules;
+        try {
+            rules = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        }
+        catch (err) {
+            // The path and the reason, both. "Could not read rules" sends someone looking at the rules.
+            context.emit.fail('invalid', `Could not read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+            return exit_codes_1.EXIT.USAGE;
+        }
+        if (!Array.isArray(rules)) {
+            context.emit.fail('invalid', `${path} must contain a JSON ARRAY of rules.`);
+            return exit_codes_1.EXIT.USAGE;
+        }
+        return submit(context, key, { command: 'rules', rules }, 'Replaced the rules of');
+    },
+};
+exports.flagsKillCommand = {
+    path: ['flags', 'kill'],
+    summary: 'the 3am verb — serve false, and clear every rule',
+    usage: 'gf flags kill <key> --env production',
+    needsAuth: true,
+    detail: `Two things happen, and the second is the one a hand-composed "set --value false"
+  forgets:
+
+    1. the default variant becomes the one whose value is false, AND
+    2. EVERY RULE IS CLEARED.
+
+  Without (2) a flag reads as "off" on the flags page while a 10% rollout is still serving
+  true to one caller in ten — which is exactly the state you are killing the flag to escape.
+
+  Refuses a non-boolean flag rather than guessing: there is no defensible "off" for a string.`,
+    flags: ENVIRONMENT_FLAGS,
+    async run(context) {
+        const key = context.args.positionals[0];
+        if (!key) {
+            context.emit.fail('invalid', 'Name a flag: `gf flags kill <key> --env production`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        return submit(context, key, { command: 'kill' }, 'Killed');
+    },
+};

package/dist/commands/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../command';
+export declare const COMMANDS: readonly Command[];