@golden-frijoles/cli 0.1.0

package/dist/commands/auth.js

@@ -0,0 +1,214 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.2 — `gf login`, `gf logout`, `gf whoami`.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whoamiCommand = exports.logoutCommand = exports.loginCommand = void 0;
+const args_1 = require("../args");
+const credentials_1 = require("../credentials");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+/**
+ * Read a token from stdin when `--token` was not given.
+ *
+ * ⚠️ **stdin, not `argv`, and not a prompt with echo.** A token in `argv` is readable by every
+ * process on the machine (`ps`) and lands in shell history; the shaping listed key material on disk
+ * as a rabbit hole and this is the same hazard one step earlier. Piping (`… | gf login`) is the CI
+ * shape and works identically.
+ */
+async function readTokenFromStdin(context) {
+    // ⚠️ **The `--json` branch used to only SUPPRESS the prompt, and then read stdin anyway** (fresh
+    // reviewer, PR #149, graded Blocking). On an interactive terminal `gf login --json` printed
+    // nothing at all and blocked until the user guessed at Ctrl-D — strictly worse than the
+    // non-`--json` path it was meant to improve on, and on the credential-entry path. The comment
+    // above it claimed it returned a usage error. It did not.
+    //
+    // Now the two conditions are separate facts and both are acted on:
+    //   • nothing is piped AND there is no one to ask (`--json`) ⇒ return null, the caller exits 1
+    //   • nothing is piped and there IS someone to ask ⇒ prompt, then read
+    //   • something is piped ⇒ read it, prompt or not. This is the CI shape and must never block.
+    if (process.stdin.isTTY) {
+        if (context.emit.json)
+            return null;
+        context.emit.note('Paste your CLI token and press Enter:');
+        // ⚠️ **ONE LINE, not "read to EOF"** (cross-family review, Codex, round 3, graded Blocking).
+        // `for await (const chunk of process.stdin)` ends at EOF, and pressing Enter on a terminal does
+        // NOT close stdin — so the documented happy path, `gf login` with no flags, printed the prompt,
+        // accepted the paste, and then hung until the user guessed at Ctrl-D. The verb every new user
+        // runs first, unusable, under a prompt that said it was waiting for Enter.
+        //
+        // `readline` is the thing that knows what a line is. The interface is closed either way, so the
+        // process does not stay alive holding the TTY open.
+        const readline = await Promise.resolve().then(() => __importStar(require('node:readline/promises')));
+        const rl = readline.createInterface({ input: process.stdin, terminal: false });
+        try {
+            const line = await rl[Symbol.asyncIterator]().next();
+            const value = typeof line.value === 'string' ? line.value.trim() : '';
+            return value === '' ? null : value;
+        }
+        finally {
+            rl.close();
+        }
+    }
+    // PIPED. Read to EOF, which is exactly right here and is the CI shape: `echo $TOKEN | gf login`
+    // closes stdin, and a token that arrives in several chunks is reassembled.
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    const value = Buffer.concat(chunks).toString('utf8').trim();
+    return value === '' ? null : value;
+}
+exports.loginCommand = {
+    path: ['login'],
+    summary: 'save a CLI token for this machine',
+    usage: 'gf login [--token <token>] [--api <url>]',
+    needsAuth: false,
+    detail: `Mint a token at /app/setup/cli in the console, then paste it here.
+
+  With no --token, the token is read from STDIN — so it never appears in your shell
+  history or in \`ps\`. For CI, set GOLDEN_FRIJOLES_TOKEN instead and skip this verb;
+  nothing is written to disk in that case.`,
+    flags: [
+        { name: 'token', value: '<token>', describe: 'the token, instead of reading stdin' },
+        { name: 'api', value: '<url>', describe: `the deployment (default: ${credentials_1.DEFAULT_API_URL})` },
+    ],
+    async run(context) {
+        const token = (0, args_1.flagValue)(context.args, 'token')?.trim() || (await readTokenFromStdin(context));
+        if (!token) {
+            context.emit.fail('invalid', 'No token supplied. Pass --token, or pipe one into `gf login`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const apiUrl = (0, credentials_1.normalizeApiUrl)((0, args_1.flagValue)(context.args, 'api')?.trim() || context.env.GOLDEN_FRIJOLES_URL?.trim() || credentials_1.DEFAULT_API_URL);
+        // ⚠️ VERIFY before saving. Writing an unverified token produces a credentials file that looks
+        // fine and fails on every later command with an error about that command — which is how someone
+        // spends an afternoon debugging `gf flags ls` when the real answer is "that paste was truncated".
+        const probe = await context.clientFor(token).get('api/v1/cli/whoami');
+        if (probe.kind === 'network') {
+            context.emit.fail('server_error', probe.message);
+            return exit_codes_1.EXIT.SERVER;
+        }
+        if (probe.kind === 'error') {
+            context.emit.fail(probe.code, probe.message);
+            return (0, exit_codes_1.exitForServerCode)(probe.code);
+        }
+        const existing = (0, credentials_1.readCredentials)(context.env);
+        const path = (0, credentials_1.writeCredentials)({
+            token,
+            apiUrl,
+            // Keep the active project only if it is still one this account can reach. A token swapped
+            // for a different account would otherwise leave `gf flags ls` pointed at a project the new
+            // credential 404s on, and the error would name the flag rather than the stale selection.
+            activeProject: probe.body.projects.some((project) => project.slug === existing?.activeProject)
+                ? existing?.activeProject
+                : probe.body.projects[0]?.slug,
+        }, context.env);
+        context.emit.ok({
+            account: probe.body.account,
+            apiUrl,
+            credentialsPath: path,
+            projects: probe.body.projects,
+        }, `Signed in as ${probe.body.account.email ?? probe.body.account.userId} on ${apiUrl}.\n` +
+            `Saved to ${path} (mode 0600).`);
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.logoutCommand = {
+    path: ['logout'],
+    summary: 'forget the saved token on this machine',
+    usage: 'gf logout',
+    needsAuth: false,
+    detail: `Removes the local credential only. It does NOT revoke the token — anything else
+  holding it still works. Revoke at /app/setup/cli when that is what you mean.`,
+    flags: [],
+    async run(context) {
+        const path = (0, credentials_1.credentialsPath)(context.env);
+        if (!(0, credentials_1.readCredentials)(context.env)) {
+            context.emit.ok({ removed: false, credentialsPath: path }, 'No saved credential to remove.');
+            return exit_codes_1.EXIT.OK;
+        }
+        // Overwritten with an empty token rather than unlinked: `readCredentials` treats it as "not
+        // logged in", the file keeps its 0600 mode, and `gf doctor` can still report where it looked.
+        (0, credentials_1.writeCredentials)({ token: '', apiUrl: credentials_1.DEFAULT_API_URL }, context.env);
+        context.emit.ok({ removed: true, credentialsPath: path }, `Removed the saved credential from ${path}. The token itself is NOT revoked — revoke it at /app/setup/cli.`);
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.whoamiCommand = {
+    path: ['whoami'],
+    summary: 'the account, the credential and the projects it reaches',
+    usage: 'gf whoami [--json]',
+    needsAuth: true,
+    flags: [],
+    async run(context) {
+        const result = await context.api.get('api/v1/cli/whoami');
+        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 { account, credential, projects } = result.body;
+        context.emit.ok({
+            account,
+            // The credential's id and LABEL. Never the token — `gf doctor`'s rule applies here too, and
+            // `whoami` is the command most likely to be pasted into an issue.
+            credential,
+            apiUrl: context.api.baseUrl,
+            tokenSource: context.auth.source,
+            activeProject: context.auth.activeProject,
+            projects,
+        }, [
+            `${account.email ?? account.userId}  on ${context.api.baseUrl}`,
+            `credential: ${credential.label} (from ${describeSource(context.auth.source)})`,
+            `active project: ${context.auth.activeProject ?? 'none — run `gf projects use <slug>`'}`,
+            '',
+            (0, output_1.table)(['PROJECT', 'ROLE'], projects.map((project) => [
+                project.slug + (project.slug === context.auth.activeProject ? ' *' : ''),
+                project.role,
+            ])),
+        ].join('\n'));
+        return exit_codes_1.EXIT.OK;
+    },
+};
+function describeSource(source) {
+    if (source === 'env')
+        return 'GOLDEN_FRIJOLES_TOKEN';
+    if (source === 'flag')
+        return '--token';
+    if (source === 'file')
+        return 'the saved credentials file';
+    return 'nowhere';
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../command';
+export type CheckStatus = 'ok' | 'fail' | 'warn' | 'skipped';
+export type Check = {
+    id: string;
+    status: CheckStatus;
+    /** One sentence a person can act on. Never "something went wrong". */
+    detail: string;
+};
+export declare const doctorCommand: Command;

package/dist/commands/doctor.js

@@ -0,0 +1,239 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.5 — `gf doctor`.
+//
+// ── What this verb is for ─────────────────────────────────────────────────────────────────────
+// The seed's words: *"an agent that can't tell WHY it's unauthenticated burns a whole session
+// guessing."* So `doctor` runs the checks in dependency order and reports every one of them —
+// including the ones it could not run, and why — rather than stopping at the first failure with a
+// single sentence.
+//
+// ── It requires no credential, and that is load-bearing ───────────────────────────────────────
+// `needsAuth: false`. The dispatcher refusing this verb for want of a credential would make the
+// tool useless exactly when it is needed: diagnosing a missing credential.
+//
+// ── It NEVER prints key material ──────────────────────────────────────────────────────────────
+// Not the token, not a prefix, not a length. `doctor` output is the thing people paste into an
+// issue, and `cli.test.ts`'s "gf doctor never prints key material, in either mode" asserts that a
+// known token string appears nowhere in its output — a claim about a security property gets an
+// assertion, not a comment. (That citation named a `doctor.test.ts` which does not exist; a
+// pointer to a missing guard is how the next reader concludes there isn't one.)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctorCommand = void 0;
+const node_fs_1 = require("node:fs");
+const args_1 = require("../args");
+const credentials_1 = require("../credentials");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+const version_1 = require("../version");
+exports.doctorCommand = {
+    path: ['doctor'],
+    summary: 'why is it not working — every check, in order',
+    usage: 'gf doctor [--json]',
+    needsAuth: false,
+    detail: `Runs whether or not you are logged in — diagnosing a missing credential is the
+  point. Prints no key material in either mode.
+
+  Exits 0 when every check that could run passed, and non-zero naming the first that did not.`,
+    flags: [{ name: 'project', value: '<slug>', describe: 'check this project instead of the remembered one' }],
+    async run(context) {
+        const checks = [];
+        const path = (0, credentials_1.credentialsPath)(context.env);
+        // ── 1. is there a credential at all, and where did it come from ───────────────────────────
+        const fileExists = (0, node_fs_1.existsSync)(path);
+        const parsedFile = (0, credentials_1.readCredentials)(context.env);
+        if (fileExists && parsedFile === null) {
+            // The one case where "no credential" has a different remedy: the file is there and unusable.
+            // Collapsing it into "not logged in" sends someone to `gf login` when the answer may be a
+            // half-written file from an interrupted paste.
+            checks.push({
+                id: 'credentials-file',
+                status: 'fail',
+                detail: `${path} exists but could not be read as a credential. Delete it and run \`gf login\`.`,
+            });
+        }
+        else if (fileExists) {
+            checks.push({ id: 'credentials-file', status: 'ok', detail: `Readable at ${path}.` });
+        }
+        else {
+            checks.push({
+                id: 'credentials-file',
+                status: context.auth.source === 'env' ? 'skipped' : 'warn',
+                detail: context.auth.source === 'env'
+                    ? `No file at ${path} — GOLDEN_FRIJOLES_TOKEN is in use, which is the CI path.`
+                    : `No file at ${path}. Run \`gf login\`.`,
+            });
+        }
+        if (context.auth.token === null) {
+            checks.push({
+                id: 'credential',
+                status: 'fail',
+                detail: 'No credential. Run `gf login`, or set GOLDEN_FRIJOLES_TOKEN.',
+            });
+            return report(context, checks);
+        }
+        checks.push({
+            id: 'credential',
+            status: 'ok',
+            // The SOURCE, never the value.
+            detail: `Found, from ${describeSource(context.auth.source)}.`,
+        });
+        // ── 2. does it even look like one ─────────────────────────────────────────────────────────
+        // A local shape check, before the network, so a truncated paste is named as a truncated paste
+        // rather than as a rejected credential — different remedies, and the server cannot tell them
+        // apart because it deliberately answers both the same way.
+        if (!credentials_1.CLI_TOKEN_FORMAT.test(context.auth.token)) {
+            checks.push({
+                id: 'credential-shape',
+                status: 'fail',
+                detail: 'That credential is not shaped like a CLI token (`gf_pat_…`). It may have been truncated.',
+            });
+            return report(context, checks);
+        }
+        checks.push({ id: 'credential-shape', status: 'ok', detail: 'Shaped like a CLI token.' });
+        // ── 3. is the deployment reachable, and does it have the CLI API ──────────────────────────
+        const whoami = await context.api.get('api/v1/cli/whoami');
+        if (whoami.kind === 'network') {
+            checks.push({ id: 'api-reachable', status: 'fail', detail: whoami.message });
+            return report(context, checks);
+        }
+        if (whoami.kind === 'error' && whoami.code === 'disabled') {
+            checks.push({
+                id: 'api-reachable',
+                status: 'fail',
+                detail: `${context.api.baseUrl} answers, but its CLI API is switched off (CLI_WRITE_API_ENABLED=false).`,
+            });
+            return report(context, checks);
+        }
+        if (whoami.kind === 'error' && whoami.code === 'unauthorized') {
+            checks.push({ id: 'api-reachable', status: 'ok', detail: `${context.api.baseUrl} answers.` });
+            checks.push({
+                id: 'credential-accepted',
+                status: 'fail',
+                // Unknown, revoked and expired are one answer at the server by design, so `doctor` must not
+                // invent a distinction it cannot have. It names all three and one remedy that covers them.
+                detail: 'The deployment rejected this credential — unknown, revoked or expired. Mint a new one at /app/setup/cli.',
+            });
+            return report(context, checks);
+        }
+        if (whoami.kind === 'error') {
+            checks.push({
+                id: 'api-reachable',
+                status: 'fail',
+                detail: `${context.api.baseUrl} answered ${whoami.status}: ${whoami.message}`,
+            });
+            return report(context, checks);
+        }
+        checks.push({ id: 'api-reachable', status: 'ok', detail: `${context.api.baseUrl} answers.` });
+        checks.push({
+            id: 'credential-accepted',
+            status: 'ok',
+            detail: `Signed in as ${whoami.body.account.email ?? whoami.body.account.userId} (${whoami.body.credential.label}).`,
+        });
+        // ── 4. is the active project one this credential can reach ────────────────────────────────
+        const wanted = (0, args_1.flagValue)(context.args, 'project')?.trim() || context.auth.activeProject;
+        if (!wanted) {
+            checks.push({
+                id: 'active-project',
+                status: 'warn',
+                detail: 'No project chosen. Run `gf projects use <slug>` or pass --project.',
+            });
+        }
+        else if (whoami.body.projects.some((project) => project.slug === wanted)) {
+            checks.push({ id: 'active-project', status: 'ok', detail: `\`${wanted}\` is reachable.` });
+        }
+        else {
+            checks.push({
+                id: 'active-project',
+                status: 'fail',
+                detail: `\`${wanted}\` is not a project this credential can reach. ` +
+                    `Available: ${whoami.body.projects.map((project) => project.slug).join(', ') || 'none'}.`,
+            });
+        }
+        // ── 5. is this CLI current ────────────────────────────────────────────────────────────────
+        checks.push(await versionCheck(context.fetchImpl));
+        return report(context, checks);
+    },
+};
+/**
+ * Is a newer `@golden-frijoles/cli` published?
+ *
+ * ⚠️ It takes the run's `fetchImpl` rather than calling the global `fetch`. A direct call made
+ * every `doctor` test reach registry.npmjs.org for real, and left this check unassertable — the
+ * same second-HTTP-path defect `init.ts`'s `probeFlagReadKey` records having already made once.
+ *
+ * ⚠️ A `warn` or a `skipped`, NEVER a `fail`. The registry is a third party: an offline machine, a
+ * corporate proxy or an npm outage must not make `gf doctor` report that the CLI is broken. Being
+ * unable to check is a different fact from being out of date, and this reports which.
+ */
+async function versionCheck(fetchImpl) {
+    try {
+        const response = await fetchImpl('https://registry.npmjs.org/@golden-frijoles/cli/latest', {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!response.ok)
+            return {
+                id: 'cli-version',
+                status: 'skipped',
+                detail: `Running ${version_1.VERSION}. Could not reach the npm registry to compare.`,
+            };
+        const body = (await response.json());
+        const latest = typeof body.version === 'string' ? body.version : null;
+        if (!latest)
+            return {
+                id: 'cli-version',
+                status: 'skipped',
+                detail: `Running ${version_1.VERSION}. The registry gave no version to compare.`,
+            };
+        return latest === version_1.VERSION
+            ? { id: 'cli-version', status: 'ok', detail: `Running ${version_1.VERSION}, the latest.` }
+            : {
+                id: 'cli-version',
+                status: 'warn',
+                detail: `Running ${version_1.VERSION}; ${latest} is published. Update with \`npm i -g @golden-frijoles/cli\`.`,
+            };
+    }
+    catch {
+        return {
+            id: 'cli-version',
+            status: 'skipped',
+            detail: `Running ${version_1.VERSION}. Could not reach the npm registry to compare.`,
+        };
+    }
+}
+function describeSource(source) {
+    if (source === 'env')
+        return 'GOLDEN_FRIJOLES_TOKEN';
+    if (source === 'flag')
+        return '--token';
+    return 'the saved credentials file';
+}
+/**
+ * Print every check and choose the exit code.
+ *
+ * A `warn` does NOT fail. "No project chosen" and "a newer CLI exists" are both things a caller may
+ * legitimately be living with, and a doctor that exits non-zero for them is a doctor whose exit code
+ * nobody can put in a CI step.
+ */
+function report(context, checks) {
+    const failed = checks.find((check) => check.status === 'fail');
+    context.emit.ok({ checks, healthy: failed === undefined }, checks.map((check) => `${symbol(check.status)} ${(0, output_1.pad)(check.id, 20)} ${check.detail}`).join('\n'));
+    if (!failed)
+        return exit_codes_1.EXIT.OK;
+    // The failing check decides the code, so a caller branching on it gets the same vocabulary the
+    // other verbs use rather than a doctor-specific number.
+    if (failed.id === 'api-reachable')
+        return exit_codes_1.EXIT.SERVER;
+    if (failed.id === 'active-project')
+        return exit_codes_1.EXIT.NOT_FOUND;
+    return exit_codes_1.EXIT.AUTH;
+}
+function symbol(status) {
+    if (status === 'ok')
+        return 'ok  ';
+    if (status === 'fail')
+        return 'FAIL';
+    if (status === 'warn')
+        return 'warn';
+    return 'skip';
+}

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

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

package/dist/commands/flags-history.js

@@ -0,0 +1,183 @@
+"use strict";
+// golden-frijoles-cli · Sprint 2, Story 2.4 — `gf flags history` and `gf flags diff`.
+//
+// ── READ-ONLY, and that is asserted rather than asserted-about ────────────────────────────────
+// Both verbs are served by the SAME `GET /api/v1/cli/flags?key=…` the read verbs use. There is no
+// POST in this file, no version created, no activation touched, no audit row written — and a spec
+// pins that by counting the requests each one makes. A "read" verb that could write is one someone
+// will run during an incident to find out what happened.
+//
+// ── The diff is SEMANTIC, and it is the console's diff ────────────────────────────────────────
+// `diffFlagDefinitions` comes from `@golden-frijoles/sdk` — the same function `/app/flags` renders
+// its version history with, moved there by D4 precisely so `gf flags diff` and the console produce
+// the SAME sentences. A JSON text diff would have been easier and would have said "two lines
+// changed" where the console says "rollout 10% → 25%".
+//
+// It also ADMITS what it cannot describe. `unexplained` means something changed outside the six
+// parts the differ covers, and the CLI prints the raw JSON rather than a confident sentence that
+// happens to omit it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flagsDiffCommand = exports.flagsHistoryCommand = void 0;
+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");
+async function loadFlag(context, project, key) {
+    const result = await context.api.get('api/v1/cli/flags', { project, key });
+    if (result.kind === 'network') {
+        context.emit.fail('server_error', result.message);
+        return { ok: false, code: exit_codes_1.EXIT.SERVER };
+    }
+    if (result.kind === 'error') {
+        context.emit.fail(result.code, result.message);
+        return { ok: false, code: (0, exit_codes_1.exitForServerCode)(result.code) };
+    }
+    return { ok: true, body: result.body };
+}
+exports.flagsHistoryCommand = {
+    path: ['flags', 'history'],
+    summary: 'every version of a flag, and who changed what',
+    usage: 'gf flags history <key> [--project <slug>] [--json]',
+    needsAuth: true,
+    detail: `Read-only: it creates no version, touches no activation and writes no audit row.
+
+  ⚠️ The audit window is CAPPED by the control plane at the most recent entries, so a flag
+  with a very long history shows the newest of them rather than all of them. Saying so is
+  the point — a list that implies completeness it does not have is worse than a short one.`,
+    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 history <key>`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const project = (0, flags_read_1.resolveProject)(context);
+        if (!project)
+            return (0, flags_read_1.missingProject)(context);
+        const loaded = await loadFlag(context, project, key);
+        if (!loaded.ok)
+            return loaded.code;
+        const { flag } = loaded.body;
+        context.emit.ok({ project, key: flag.key, versions: flag.versions, audit: flag.audit }, [
+            (0, output_1.table)(['VERSION', 'CREATED', 'SERVED BY'], flag.versions.map((version) => [
+                `v${version.version}`,
+                version.createdAt,
+                version.servedBy.join(', ') || '—',
+            ])),
+            '',
+            flag.audit.length === 0
+                ? 'No lifecycle events recorded for this flag.'
+                : (0, output_1.table)(['WHEN', 'WHAT', 'WHERE', 'WHO', 'WHY'], flag.audit.map((row) => [
+                    row.createdAt,
+                    row.action,
+                    row.environment ?? '—',
+                    row.actor,
+                    row.reason,
+                ])),
+        ].join('\n'));
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.flagsDiffCommand = {
+    path: ['flags', 'diff'],
+    summary: 'what changed between two versions, in words',
+    usage: 'gf flags diff <key> --from 3 --to 4    ·    gf flags diff <key> --env preview --env production',
+    needsAuth: true,
+    detail: `Two ways to ask:
+    --from <n> --to <n>          compare two version numbers
+    --env <a> --env <b>          compare what two environments are serving
+
+  The sentences are the console's own — one implementation, so the terminal and the page
+  cannot describe the same change differently. Anything outside the six parts the differ
+  covers is reported as such, with the raw JSON, rather than silently omitted.`,
+    flags: [
+        { name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' },
+        { name: 'from', value: '<version>', describe: 'the version to compare FROM' },
+        { name: 'to', value: '<version>', describe: 'the version to compare TO' },
+        { name: 'env', value: '<environment>', describe: 'pass twice to compare two environments' },
+    ],
+    async run(context) {
+        const key = context.args.positionals[0];
+        if (!key) {
+            context.emit.fail('invalid', 'Name a flag: `gf flags diff <key> --from 3 --to 4`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const project = (0, flags_read_1.resolveProject)(context);
+        if (!project)
+            return (0, flags_read_1.missingProject)(context);
+        const environments = (0, args_1.flagValues)(context.args, 'env');
+        const from = (0, args_1.flagValue)(context.args, 'from');
+        const to = (0, args_1.flagValue)(context.args, 'to');
+        const byVersion = from !== undefined && to !== undefined;
+        const byEnvironment = environments.length === 2;
+        if (byVersion === byEnvironment) {
+            // Both, or neither. Both is ambiguous and neither is incomplete; guessing which the caller
+            // meant would produce a confident answer to a question they did not ask.
+            context.emit.fail('invalid', 'Pass EITHER --from <version> --to <version>, OR --env twice. Not both, and not neither.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const loaded = await loadFlag(context, project, key);
+        if (!loaded.ok)
+            return loaded.code;
+        const { flag } = loaded.body;
+        let before = null;
+        let after = null;
+        if (byVersion) {
+            const find = (raw) => flag.versions.find((version) => version.version === Number(raw));
+            const left = find(from);
+            const right = find(to);
+            if (!left || !right) {
+                const known = flag.versions.map((version) => `v${version.version}`).join(', ');
+                context.emit.fail('not_found', `No such version. ${key} has: ${known || 'none'}.`);
+                return exit_codes_1.EXIT.NOT_FOUND;
+            }
+            before = { label: `v${left.version}`, definition: left.definition };
+            after = { label: `v${right.version}`, definition: right.definition };
+        }
+        else {
+            const resolveEnvironment = (name) => {
+                const row = flag.environments.find((candidate) => candidate.environment === name);
+                if (!row || row.version === null)
+                    return null;
+                const version = flag.versions.find((candidate) => candidate.version === row.version);
+                return version
+                    ? { label: `${name} (v${version.version})`, definition: version.definition }
+                    : null;
+            };
+            before = resolveEnvironment(environments[0]);
+            after = resolveEnvironment(environments[1]);
+            if (!before || !after) {
+                // Naming WHICH one, because "one of them serves nothing" sends the reader to check both.
+                const empty = [before ? null : environments[0], after ? null : environments[1]].filter(Boolean);
+                context.emit.fail('not_found', `${empty.join(' and ')} ${empty.length === 1 ? 'is' : 'are'} serving nothing, so there is nothing to compare.`);
+                return exit_codes_1.EXIT.NOT_FOUND;
+            }
+        }
+        const diff = (0, sdk_1.diffFlagDefinitions)(before.definition, after.definition);
+        context.emit.ok({
+            project,
+            key: flag.key,
+            from: before.label,
+            to: after.label,
+            changes: diff.changes,
+            unexplained: diff.unexplained,
+            // The raw definitions travel in --json ONLY when the differ could not explain everything,
+            // so an agent has what it needs exactly when the sentences are insufficient.
+            ...(diff.unexplained ? { definitions: { from: before.definition, to: after.definition } } : {}),
+        }, [
+            `${before.label} → ${after.label}`,
+            ...(diff.changes.length === 0 && !diff.unexplained
+                ? ['Nothing changed in the parts this compares.']
+                : []),
+            ...diff.changes.map((change) => `  · ${change}`),
+            ...(diff.unexplained
+                ? [
+                    '  · something changed outside what this can describe — the JSON:',
+                    JSON.stringify(after.definition, null, 2),
+                ]
+                : []),
+        ].join('\n'));
+        return exit_codes_1.EXIT.OK;
+    },
+};