@golden-frijoles/cli 0.1.0

package/dist/commands/keys.js

@@ -0,0 +1,177 @@
+"use strict";
+// golden-frijoles-cli · Sprint 2, Story 2.6 — `gf keys ls | create | revoke`.
+//
+// ── The three kinds are NOT flattened, and the CLI is where that is easiest to get wrong ──────
+// `lib/credential-inventory.ts` models three blast radii and the seed says the CLI must not
+// collapse them: `ingest` sends events into a project, `flag_read` reads ONE environment's
+// snapshot, `flag_sync` writes definitions from an outside catalog. So `--type` is REQUIRED — there
+// is no default kind — and each kind's own argument is required too. A defaulted `--env` would mint
+// a credential pointed at an environment the caller did not choose, which is the kind of quiet
+// wrong that only shows up when the wrong thing is served.
+//
+// ── The plaintext is printed ONCE and never saved ─────────────────────────────────────────────
+// It goes to stdout and nowhere else. It is not written to the credentials file, not echoed by
+// `gf doctor`, not returned by `gf keys ls`. Only the hash was stored, so there is nothing to
+// re-show and the CLI says so rather than implying it could.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keysRevokeCommand = exports.keysCreateCommand = exports.keysLsCommand = void 0;
+const args_1 = require("../args");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+const flags_read_1 = require("./flags-read");
+const KEY_TYPES = ['ingest', 'flag_read', 'flag_sync'];
+exports.keysLsCommand = {
+    path: ['keys', 'ls'],
+    summary: 'every credential that can reach this project',
+    usage: 'gf keys ls [--project <slug>] [--json]',
+    needsAuth: true,
+    detail: `Owner-only, exactly as the console's Keys page is — an ordinary member can read the
+  dashboards but must not enumerate the credentials production runs on.
+
+  ⚠️ It does NOT list connector URLs, share links or your CLI tokens. Those are managed on
+  their own surfaces and are not project-scoped credentials; saying so is better than a list
+  that implies completeness it does not have.`,
+    flags: [{ name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' }],
+    async run(context) {
+        const project = (0, flags_read_1.resolveProject)(context);
+        if (!project)
+            return (0, flags_read_1.missingProject)(context);
+        const result = await context.api.get('api/v1/cli/keys', { 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 { keys } = result.body;
+        context.emit.ok({ project, keys }, keys.length === 0
+            ? `No credentials in ${project} yet.`
+            : (0, output_1.table)(['ID', 'TYPE', 'LABEL', 'SCOPE', 'EXPIRES', 'STATE'], keys.map((key) => [
+                key.id,
+                key.type,
+                key.label || 'untitled',
+                // "Everywhere" for a kind with no scope, never a blank: a blank cell reads as missing
+                // data, and "this kind has no environment" is a fact.
+                key.scope ?? 'everywhere',
+                key.expiresAt ?? 'no expiry',
+                key.revokedAt ? 'revoked' : 'active',
+            ])));
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.keysCreateCommand = {
+    path: ['keys', 'create'],
+    summary: 'mint a credential — the kind is required, never guessed',
+    usage: 'gf keys create --type flag_read --env production --label "my app"',
+    needsAuth: true,
+    detail: `--type is required and has no default:
+
+    ingest      sends events into this project, and reads its funnels through the SDK
+    flag_read   reads ONE environment's flag snapshot — needs --env
+    flag_sync   registers flag definitions from an outside catalog — needs --source
+
+  These have different blast radii and the product models them separately; a CLI that
+  flattened them into "a key" would hand out the widest one by accident.
+
+  The value is printed ONCE. Only its hash is stored, so it cannot be shown again.`,
+    flags: [
+        { name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' },
+        { name: 'type', value: '<kind>', describe: `${KEY_TYPES.join(' | ')} — required` },
+        { name: 'label', value: '<text>', describe: 'what holds it — required' },
+        { name: 'env', value: '<environment>', describe: 'required for flag_read' },
+        { name: 'source', value: '<name>', describe: 'required for flag_sync' },
+    ],
+    async run(context) {
+        const project = (0, flags_read_1.resolveProject)(context);
+        if (!project)
+            return (0, flags_read_1.missingProject)(context);
+        const type = (0, args_1.flagValue)(context.args, 'type');
+        if (!type || !KEY_TYPES.includes(type)) {
+            context.emit.fail('invalid', `--type is required, and must be one of: ${KEY_TYPES.join(', ')}.`);
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const label = (0, args_1.flagValue)(context.args, 'label')?.trim();
+        if (!label) {
+            context.emit.fail('invalid', '--label is required. Name what will hold this credential.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        // Refused HERE as well as at the server, so a caller learns what is missing without spending a
+        // round-trip on it — and so the message names the kind they actually asked for.
+        if (type === 'flag_read' && !(0, args_1.flagValue)(context.args, 'env')) {
+            context.emit.fail('invalid', 'A flag_read key reads ONE environment. Pass --env.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        if (type === 'flag_sync' && !(0, args_1.flagValue)(context.args, 'source')) {
+            context.emit.fail('invalid', 'A flag_sync key is attributed to a source catalog. Pass --source.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const result = await context.api.post('api/v1/cli/keys', {
+            project,
+            type,
+            label,
+            environment: (0, args_1.flagValue)(context.args, 'env'),
+            source: (0, args_1.flagValue)(context.args, 'source'),
+        });
+        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 minted = result.body;
+        context.emit.ok(minted, [
+            `${minted.type} credential for ${project}${minted.scope ? ` (${minted.scope})` : ''}`,
+            '',
+            minted.key,
+            '',
+            'This is the only time it is shown — only a hash was stored.',
+            minted.expiresAt
+                ? `It expires ${minted.expiresAt}.`
+                : 'It does not expire; revoke it when you are done.',
+        ].join('\n'));
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.keysRevokeCommand = {
+    path: ['keys', 'revoke'],
+    summary: 'kill a credential, immediately and permanently',
+    usage: 'gf keys revoke <id> --type ingest',
+    needsAuth: true,
+    detail: `--type is required, and it is not bureaucracy: each kind is revoked through its own
+  path so the audit trail records what actually happened. A trail whose label can be chosen
+  by picking an endpoint is worse than no trail — an operator asking "why did ingest stop?"
+  must not find the answer filed under something else.
+
+  Idempotent. A credential that is already revoked, never existed, or belongs to another
+  project is one answer: not found.`,
+    flags: [
+        { name: 'project', value: '<slug>', describe: 'the project (default: the remembered one)' },
+        { name: 'type', value: '<kind>', describe: `${KEY_TYPES.join(' | ')} — required` },
+    ],
+    async run(context) {
+        const project = (0, flags_read_1.resolveProject)(context);
+        if (!project)
+            return (0, flags_read_1.missingProject)(context);
+        const id = context.args.positionals[0];
+        const type = (0, args_1.flagValue)(context.args, 'type');
+        if (!id || !type || !KEY_TYPES.includes(type)) {
+            context.emit.fail('invalid', `Usage: \`gf keys revoke <id> --type ${KEY_TYPES.join('|')}\`.`);
+            return exit_codes_1.EXIT.USAGE;
+        }
+        const result = await context.api.del('api/v1/cli/keys', { project, type, id });
+        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);
+        }
+        context.emit.ok({ project, type, id, revoked: true }, `Revoked ${type} credential ${id}.`);
+        return exit_codes_1.EXIT.OK;
+    },
+};

package/dist/commands/projects.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from '../command';
+export declare const projectsLsCommand: Command;
+export declare const projectsCreateCommand: Command;
+export declare const projectsUseCommand: Command;

package/dist/commands/projects.js

@@ -0,0 +1,114 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.3 — `gf projects ls | create | use`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectsUseCommand = exports.projectsCreateCommand = exports.projectsLsCommand = void 0;
+const credentials_1 = require("../credentials");
+const exit_codes_1 = require("../exit-codes");
+const output_1 = require("../output");
+exports.projectsLsCommand = {
+    path: ['projects', 'ls'],
+    summary: 'the projects this credential reaches',
+    usage: 'gf projects ls [--json]',
+    needsAuth: true,
+    flags: [],
+    async run(context) {
+        const result = await context.api.get('api/v1/cli/projects');
+        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 { projects } = result.body;
+        context.emit.ok({ projects, activeProject: context.auth.activeProject }, projects.length === 0
+            ? 'This account belongs to no project yet. Run `gf projects create`.'
+            : (0, output_1.table)(['PROJECT', 'ROLE', ''], projects.map((project) => [
+                project.slug,
+                project.role,
+                project.slug === context.auth.activeProject ? 'active' : '',
+            ])));
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.projectsCreateCommand = {
+    path: ['projects', 'create'],
+    summary: 'make sure this account has a project (idempotent)',
+    usage: 'gf projects create [--json]',
+    needsAuth: true,
+    detail: `⚠️ An ENSURE, not a second project.
+
+  The database enforces one self-serve project per account — a partial unique index that
+  closes a signup race, not a plan limit. So this reports the project you already have,
+  with created: false, and never mints a second. Use it in a script that wants to be sure
+  before \`gf init\`, without parsing \`gf projects ls\`.
+
+  It cannot rescue an account that has NO project: holding a CLI token already means you
+  have one. If you are in that state, open /app in a browser — it retries provisioning for
+  you.
+
+  It also never returns an ingest key. Use \`gf keys create --type ingest\` for that, where
+  the credential gets its own confirmation and its own audit row.`,
+    flags: [],
+    async run(context) {
+        const result = await context.api.post('api/v1/cli/projects', {});
+        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 { created, slug } = result.body;
+        context.emit.ok({ created, slug }, created ? `Created project ${slug}.` : `This account already has project ${slug}. Nothing changed.`);
+        return exit_codes_1.EXIT.OK;
+    },
+};
+exports.projectsUseCommand = {
+    path: ['projects', 'use'],
+    summary: 'remember which project the other commands act on',
+    usage: 'gf projects use <slug>',
+    needsAuth: true,
+    detail: `Writes the choice into the saved credentials file. --project on any command
+  overrides it for that one run, and GOLDEN_FRIJOLES_PROJECT overrides both — which is
+  what CI should set, since CI has no credentials file to write.`,
+    flags: [],
+    async run(context) {
+        const slug = context.args.positionals[0];
+        if (!slug) {
+            context.emit.fail('invalid', 'Name a project: `gf projects use <slug>`.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        // ⚠️ VERIFIED against the server before it is saved. Writing an unchecked slug produces a file
+        // that makes every later command fail with that command's error — "no flag `x` in `y`" when the
+        // real answer is "`y` is not a project you can see" — which is the class of misdirection
+        // `gf doctor` exists to end, so it must not be created here in the first place.
+        const result = await context.api.get('api/v1/cli/projects');
+        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);
+        }
+        if (!result.body.projects.some((project) => project.slug === slug)) {
+            // Not-a-member and does-not-exist are ONE answer, here as at the server (AGENTS #10).
+            context.emit.fail('not_found', `No project \`${slug}\` is available to this account.`);
+            return exit_codes_1.EXIT.NOT_FOUND;
+        }
+        const existing = (0, credentials_1.readCredentials)(context.env);
+        if (!existing) {
+            // Reachable with GOLDEN_FRIJOLES_TOKEN and no saved file — CI. There is nothing to remember
+            // into, and inventing a credentials file to hold a preference would write a token to a CI
+            // runner's home directory, which is precisely what the env-var path exists to avoid.
+            context.emit.fail('invalid', 'There is no saved credential to record this in. Set GOLDEN_FRIJOLES_PROJECT, or run `gf login` first.');
+            return exit_codes_1.EXIT.USAGE;
+        }
+        (0, credentials_1.writeCredentials)({ ...existing, activeProject: slug }, context.env);
+        context.emit.ok({ activeProject: slug }, `Now using ${slug}.`);
+        return exit_codes_1.EXIT.OK;
+    },
+};

package/dist/credentials.d.ts

@@ -0,0 +1,60 @@
+export declare const DEFAULT_API_URL = "https://goldenfrijoles.com";
+/**
+ * What a CLI token looks like.
+ *
+ * ⚠️ **A SECOND copy of a regex that also lives in `apps/web/lib/cli-tokens.ts`, and the duplication
+ * is deliberate.** This package is published to npm and cannot import from the app; the alternative
+ * — no local check at all — costs a network round-trip to tell someone their paste was truncated,
+ * which is `gf doctor`'s single most useful answer.
+ *
+ * It is safe to duplicate because of what it is used FOR on each side. Here it is a HINT: a
+ * malformed token is reported early, and a token this rejects would have been rejected by the
+ * server anyway. There it is the lookup's own shape guard. The failure mode of drift is that this
+ * copy becomes stricter than the server (a valid token refused locally, which `gf --token` bypasses
+ * and `doctor` names) — never that an invalid one is accepted, because this side grants nothing.
+ */
+export declare const CLI_TOKEN_FORMAT: RegExp;
+export type Credentials = {
+    token: string;
+    /** The deployment this token belongs to. A token is not portable between deployments. */
+    apiUrl: string;
+    /** `gf projects use` writes this. Absent until someone chooses. */
+    activeProject?: string;
+};
+/**
+ * `$XDG_CONFIG_HOME/golden-frijoles/credentials.json`, falling back to `~/.config/…`.
+ *
+ * XDG first because a machine that sets it means it — putting the file in `~/.config` anyway is how
+ * a credential ends up outside whatever the operator has arranged to protect or to exclude from
+ * backups.
+ */
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials | null;
+export declare function writeCredentials(next: Credentials, env?: NodeJS.ProcessEnv): string;
+export type ResolvedAuth = {
+    token: string | null;
+    apiUrl: string;
+    activeProject: string | null;
+    /** Where the token came from — `gf doctor` and `gf whoami` say so, and never print the token. */
+    source: 'env' | 'flag' | 'file' | 'none';
+};
+/**
+ * The single resolution every command uses.
+ *
+ * Returns `token: null` rather than throwing, because "not logged in" is a normal state with its own
+ * exit code and its own sentence — and because `gf doctor` has to be able to describe it rather than
+ * die of it.
+ */
+export declare function resolveAuth(options: {
+    tokenFlag?: string;
+    apiFlag?: string;
+    env?: NodeJS.ProcessEnv;
+}): ResolvedAuth;
+/**
+ * Trim a trailing slash and add a scheme if one is missing.
+ *
+ * A bare `localhost:3000` becomes `http://localhost:3000` and anything else becomes `https://…`.
+ * Guessing `http` for a public hostname would downgrade a credential-bearing request to plaintext,
+ * so the guess only goes that way for a loopback address.
+ */
+export declare function normalizeApiUrl(raw: string): string;

package/dist/credentials.js

@@ -0,0 +1,120 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.2 — where the token lives on disk.
+//
+// ── `0600`, and the directory `0700` ──────────────────────────────────────────────────────────
+// This file holds a credential that signs its holder in to every project they belong to. The
+// shaping named the failure: "key material on disk — 0600, never in the repo, never echoed by
+// doctor". The mode is applied at WRITE time on every write, not only at creation, so a file whose
+// permissions were loosened by hand is tightened the next time `gf login` runs.
+//
+// ── Precedence: env var, then flag, then file ─────────────────────────────────────────────────
+// `GOLDEN_FRIJOLES_TOKEN` wins, because CI has no credentials file and must not be made to write
+// one — a CI job that writes a token to `$HOME` leaves it in whatever the runner caches. The file
+// is the interactive path.
+//
+// ⚠️ `--token` on the command line is accepted and deliberately NOT documented as the way to log
+// in: `argv` is visible to every process on the machine and lands in shell history. `gf login` with
+// no flag reads stdin instead, which does neither.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_TOKEN_FORMAT = exports.DEFAULT_API_URL = void 0;
+exports.credentialsPath = credentialsPath;
+exports.readCredentials = readCredentials;
+exports.writeCredentials = writeCredentials;
+exports.resolveAuth = resolveAuth;
+exports.normalizeApiUrl = normalizeApiUrl;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.DEFAULT_API_URL = 'https://goldenfrijoles.com';
+/**
+ * What a CLI token looks like.
+ *
+ * ⚠️ **A SECOND copy of a regex that also lives in `apps/web/lib/cli-tokens.ts`, and the duplication
+ * is deliberate.** This package is published to npm and cannot import from the app; the alternative
+ * — no local check at all — costs a network round-trip to tell someone their paste was truncated,
+ * which is `gf doctor`'s single most useful answer.
+ *
+ * It is safe to duplicate because of what it is used FOR on each side. Here it is a HINT: a
+ * malformed token is reported early, and a token this rejects would have been rejected by the
+ * server anyway. There it is the lookup's own shape guard. The failure mode of drift is that this
+ * copy becomes stricter than the server (a valid token refused locally, which `gf --token` bypasses
+ * and `doctor` names) — never that an invalid one is accepted, because this side grants nothing.
+ */
+exports.CLI_TOKEN_FORMAT = /^gf_pat_[A-Za-z0-9_-]{20,64}$/;
+/**
+ * `$XDG_CONFIG_HOME/golden-frijoles/credentials.json`, falling back to `~/.config/…`.
+ *
+ * XDG first because a machine that sets it means it — putting the file in `~/.config` anyway is how
+ * a credential ends up outside whatever the operator has arranged to protect or to exclude from
+ * backups.
+ */
+function credentialsPath(env = process.env) {
+    const base = env.XDG_CONFIG_HOME?.trim() || (0, node_path_1.join)(env.HOME || (0, node_os_1.homedir)(), '.config');
+    return (0, node_path_1.join)(base, 'golden-frijoles', 'credentials.json');
+}
+function readCredentials(env = process.env) {
+    const path = credentialsPath(env);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        if (typeof parsed.token !== 'string' || parsed.token === '')
+            return null;
+        return {
+            token: parsed.token,
+            apiUrl: typeof parsed.apiUrl === 'string' && parsed.apiUrl !== '' ? parsed.apiUrl : exports.DEFAULT_API_URL,
+            activeProject: typeof parsed.activeProject === 'string' ? parsed.activeProject : undefined,
+        };
+    }
+    catch {
+        // A corrupt file reads as "not logged in" rather than throwing. `gf doctor` is the verb that
+        // explains WHY — it re-reads the file itself and reports it as unreadable — so the ordinary
+        // commands can treat every "no usable credential" the same way and print one remedy.
+        return null;
+    }
+}
+function writeCredentials(next, env = process.env) {
+    const path = credentialsPath(env);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    // ⚠️ chmod AFTER the write, every time. `writeFileSync`'s `mode` is only applied when the file is
+    // CREATED — an existing file keeps whatever mode it had, so a re-login into a world-readable file
+    // left it world-readable. This is the line that makes the 0600 claim true on the second run.
+    (0, node_fs_1.chmodSync)(path, 0o600);
+    return path;
+}
+/**
+ * The single resolution every command uses.
+ *
+ * Returns `token: null` rather than throwing, because "not logged in" is a normal state with its own
+ * exit code and its own sentence — and because `gf doctor` has to be able to describe it rather than
+ * die of it.
+ */
+function resolveAuth(options) {
+    const env = options.env ?? process.env;
+    const file = readCredentials(env);
+    const envToken = env.GOLDEN_FRIJOLES_TOKEN?.trim();
+    const apiUrl = normalizeApiUrl(options.apiFlag?.trim() || env.GOLDEN_FRIJOLES_URL?.trim() || file?.apiUrl || exports.DEFAULT_API_URL);
+    const activeProject = env.GOLDEN_FRIJOLES_PROJECT?.trim() || file?.activeProject || null;
+    if (envToken)
+        return { token: envToken, apiUrl, activeProject, source: 'env' };
+    if (options.tokenFlag?.trim())
+        return { token: options.tokenFlag.trim(), apiUrl, activeProject, source: 'flag' };
+    if (file)
+        return { token: file.token, apiUrl, activeProject, source: 'file' };
+    return { token: null, apiUrl, activeProject, source: 'none' };
+}
+/**
+ * Trim a trailing slash and add a scheme if one is missing.
+ *
+ * A bare `localhost:3000` becomes `http://localhost:3000` and anything else becomes `https://…`.
+ * Guessing `http` for a public hostname would downgrade a credential-bearing request to plaintext,
+ * so the guess only goes that way for a loopback address.
+ */
+function normalizeApiUrl(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, '');
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    const loopback = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i.test(trimmed);
+    return `${loopback ? 'http' : 'https'}://${trimmed}`;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,24 @@
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly USAGE: 1;
+    readonly AUTH: 2;
+    readonly NOT_FOUND: 3;
+    readonly CONFLICT: 4;
+    readonly PARTIAL: 5;
+    readonly SERVER: 6;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/**
+ * The server's `code` → this CLI's exit code.
+ *
+ * `lib/cli-auth.ts` carries the other half of this mapping. They are two files in two packages and
+ * cannot share a type, so the pairing is asserted by an e2e spec rather than assumed — an API that
+ * grew a seventh code would otherwise fall silently into `SERVER` here.
+ */
+export declare function exitForServerCode(code: string | undefined): ExitCode;
+/** Every code, for `--help` and for the golden file. Ordered by value so the list cannot reshuffle. */
+export declare const EXIT_CODE_TABLE: ReadonlyArray<{
+    code: ExitCode;
+    name: string;
+    means: string;
+}>;

package/dist/exit-codes.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_CODE_TABLE = exports.EXIT = void 0;
+exports.exitForServerCode = exitForServerCode;
+// golden-frijoles-cli · Sprint 1, Story 1.1 — the exit codes, as named constants.
+//
+// ── Why an enum and not `process.exit(1)` at forty call sites ─────────────────────────────────
+// The point of this CLI is that an agent drives it. An agent branches on the exit code, and a shell
+// script branches on nothing else at all. So the codes are a CONTRACT — pinned by a golden file
+// (D5), printed by `gf --help`, and named here once so a new verb cannot invent a meaning for `4`
+// that disagrees with every other verb's `4`.
+//
+// ── Why these seven, and no more ──────────────────────────────────────────────────────────────
+// Each one exists because a caller would do something DIFFERENT about it. That is the test for
+// adding an eighth: if the remedy is the same, it is the same code.
+//
+//   USAGE      — fix the command. Nothing was sent.
+//   AUTH       — log in again. The credential is not accepted.
+//   NOT_FOUND  — the thing is not there, or is not yours. Deliberately one code: "not yours" and
+//                "not there" are indistinguishable by design (AGENTS #10), so an exit code that
+//                told them apart would leak what the API refuses to.
+//   CONFLICT   — someone else moved it. Re-read and retry. This is the one an agent can RESOLVE by
+//                itself, which is why it must not collapse into SERVER.
+//   PARTIAL    — D2. Some environments changed and some did not. Not a success and not a clean
+//                failure, and a CLI with no code for it forces the caller to parse prose.
+//   SERVER     — the server or the network is unwell. RETRY; do not mint anything new.
+exports.EXIT = {
+    OK: 0,
+    USAGE: 1,
+    AUTH: 2,
+    NOT_FOUND: 3,
+    CONFLICT: 4,
+    PARTIAL: 5,
+    SERVER: 6,
+};
+/**
+ * The server's `code` → this CLI's exit code.
+ *
+ * `lib/cli-auth.ts` carries the other half of this mapping. They are two files in two packages and
+ * cannot share a type, so the pairing is asserted by an e2e spec rather than assumed — an API that
+ * grew a seventh code would otherwise fall silently into `SERVER` here.
+ */
+function exitForServerCode(code) {
+    switch (code) {
+        case 'unauthorized':
+            return exports.EXIT.AUTH;
+        case 'not_found':
+            return exports.EXIT.NOT_FOUND;
+        case 'invalid':
+            return exports.EXIT.USAGE;
+        case 'conflict':
+            return exports.EXIT.CONFLICT;
+        case 'disabled':
+            // The CLI API is switched off on this deployment. Not an auth problem and not the caller's
+            // mistake — there is nothing to fix in the command, so it reads as a server-side condition.
+            return exports.EXIT.SERVER;
+        default:
+            return exports.EXIT.SERVER;
+    }
+}
+/** Every code, for `--help` and for the golden file. Ordered by value so the list cannot reshuffle. */
+exports.EXIT_CODE_TABLE = [
+    { code: exports.EXIT.OK, name: 'ok', means: 'it worked' },
+    { code: exports.EXIT.USAGE, name: 'usage', means: 'the command is wrong — nothing was sent' },
+    { code: exports.EXIT.AUTH, name: 'auth', means: 'the credential is not accepted — run `gf login`' },
+    { code: exports.EXIT.NOT_FOUND, name: 'not-found', means: 'no such thing, or not yours' },
+    { code: exports.EXIT.CONFLICT, name: 'conflict', means: 'someone else changed it — re-read and retry' },
+    { code: exports.EXIT.PARTIAL, name: 'partial', means: 'some environments changed and some did not' },
+    { code: exports.EXIT.SERVER, name: 'server', means: 'the server or the network is unwell — retry' },
+];

package/dist/help.d.ts

@@ -0,0 +1,49 @@
+import type { Command } from './command';
+/**
+ * `--help` as DATA, for `--json`.
+ *
+ * ⚠️ **This exists because `gf --json --help` printed the plain-text help to stdout** (cross-family
+ * review, Codex, round 2). `output.ts` states the contract in one line — under `--json`, stdout
+ * carries exactly one JSON document and nothing else — and the help path wrote straight to the
+ * writer, bypassing the emitter entirely. An agent that piped `gf --json --help` into a parser got
+ * a wall of prose.
+ *
+ * It is a STRUCTURED shape rather than `{ help: "<the same text>" }`, because the reason an agent
+ * asks for help is to learn the verbs and their flags — and a string forces it to parse the layout
+ * of a table it did not write. Both forms are pinned by golden files; changing either is a change
+ * to what every agent believes this tool can do.
+ */
+export declare function helpAsData(commands: readonly Command[]): {
+    usage: string;
+    commands: {
+        command: string;
+        summary: string;
+        usage: string;
+        needsAuth: boolean;
+        flags: {
+            flag: string;
+            takesValue: boolean;
+            describe: string;
+        }[];
+    }[];
+    globalFlags: string[];
+    environment: string[];
+    exitCodes: {
+        code: import("./exit-codes").ExitCode;
+        name: string;
+        means: string;
+    }[];
+};
+export declare function commandAsData(command: Command): {
+    command: string;
+    summary: string;
+    usage: string;
+    needsAuth: boolean;
+    flags: {
+        flag: string;
+        takesValue: boolean;
+        describe: string;
+    }[];
+};
+export declare function renderRootHelp(commands: readonly Command[]): string;
+export declare function renderCommandHelp(command: Command): string;