@golden-frijoles/cli 0.1.0

package/dist/help.js

@@ -0,0 +1,118 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.1 — `--help`, rendered from the command table.
+//
+// ── D5: this output is a CONTRACT ─────────────────────────────────────────────────────────────
+// `src/__golden__/help.txt` holds these exact bytes and `golden.test.ts` diffs them. That is not
+// pedantry about copy: an agent handed `gf --help` reads it to learn the verbs and the flags, so a
+// silent change to this text changes what every agent believes the tool can do. A golden file makes
+// the change arrive in review, where someone can decide it is intended.
+//
+// Nothing here is hand-maintained prose about which verbs exist. It is rendered from `COMMANDS`, so
+// the help and the dispatcher cannot disagree.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.helpAsData = helpAsData;
+exports.commandAsData = commandAsData;
+exports.renderRootHelp = renderRootHelp;
+exports.renderCommandHelp = renderCommandHelp;
+const exit_codes_1 = require("./exit-codes");
+const output_1 = require("./output");
+const HEADER = `gf — the Golden Frijoles CLI
+
+  Create a flag in every environment, roll it out, and kill it, from a terminal
+  or from an agent. Every command takes --json.`;
+const GLOBAL_FLAGS = `Global flags
+  --json                 machine-readable output on stdout, and nothing else
+  --project <slug>       act on this project (default: the one from \`gf projects use\`)
+  --api <url>            the deployment to talk to (default: the one you logged in to)
+  --token <token>        use this credential instead of the saved one
+  --help, -h             this text, or a verb's own
+  --version, -V          print the version and exit`;
+const ENVIRONMENT = `Environment
+  GOLDEN_FRIJOLES_TOKEN    a CLI token. Wins over the saved credential — this is the CI path,
+                           and it means CI never has to write a token to disk.
+  GOLDEN_FRIJOLES_URL      the deployment to talk to.
+  GOLDEN_FRIJOLES_PROJECT  the active project.`;
+/** The verb list, aligned. Grouped by first word so `flags` reads as a family. */
+function verbList(commands) {
+    const width = Math.max(...commands.map((command) => command.path.join(' ').length));
+    const groups = new Map();
+    for (const command of commands) {
+        const group = command.path.length === 1 ? '' : command.path[0];
+        groups.set(group, [...(groups.get(group) ?? []), command]);
+    }
+    return [...groups.entries()]
+        .map(([group, members]) => {
+        const lines = members.map((command) => `  ${(0, output_1.pad)(command.path.join(' '), width)}  ${command.summary}`);
+        return group === '' ? lines.join('\n') : [`  ${group}`, ...lines].join('\n');
+    })
+        .join('\n\n');
+}
+function exitCodes() {
+    return [
+        'Exit codes',
+        ...exit_codes_1.EXIT_CODE_TABLE.map((row) => `  ${row.code}  ${(0, output_1.pad)(row.name, 9)}  ${row.means}`),
+    ].join('\n');
+}
+/**
+ * `--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.
+ */
+function helpAsData(commands) {
+    return {
+        usage: 'gf <command> [flags]',
+        commands: commands.map((command) => ({
+            command: command.path.join(' '),
+            summary: command.summary,
+            usage: command.usage,
+            needsAuth: command.needsAuth,
+            flags: command.flags.map((flag) => ({
+                flag: `--${flag.name}`,
+                takesValue: flag.value !== undefined,
+                describe: flag.describe,
+            })),
+        })),
+        globalFlags: ['--json', '--project', '--api', '--token', '--help', '--version'],
+        environment: ['GOLDEN_FRIJOLES_TOKEN', 'GOLDEN_FRIJOLES_URL', 'GOLDEN_FRIJOLES_PROJECT'],
+        exitCodes: exit_codes_1.EXIT_CODE_TABLE.map((row) => ({ code: row.code, name: row.name, means: row.means })),
+    };
+}
+function commandAsData(command) {
+    return helpAsData([command]).commands[0];
+}
+function renderRootHelp(commands) {
+    return [
+        HEADER,
+        `Usage\n  gf <command> [flags]`,
+        `Commands\n${verbList(commands)}`,
+        GLOBAL_FLAGS,
+        ENVIRONMENT,
+        exitCodes(),
+    ].join('\n\n');
+}
+function renderCommandHelp(command) {
+    const parts = [`gf ${command.path.join(' ')} — ${command.summary}`, `Usage\n  ${command.usage}`];
+    if (command.detail)
+        parts.push(command.detail);
+    if (command.flags.length > 0) {
+        const width = Math.max(...command.flags.map((flag) => `--${flag.name}${flag.value ? ` ${flag.value}` : ''}`.length));
+        parts.push([
+            'Flags',
+            ...command.flags.map((flag) => {
+                const left = `--${flag.name}${flag.value ? ` ${flag.value}` : ''}`;
+                return `  ${(0, output_1.pad)(left, width)}  ${flag.describe}`;
+            }),
+        ].join('\n'));
+    }
+    parts.push(exitCodes());
+    return parts.join('\n\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { run, type RunOptions } from './run';
+export { COMMANDS } from './commands';
+export { EXIT, EXIT_CODE_TABLE, exitForServerCode, type ExitCode } from './exit-codes';
+export { parseArgs, type ParsedArgs } from './args';
+export { renderCommandHelp, renderRootHelp } from './help';
+export { VERSION } from './version';
+export { DEFAULT_API_URL, CLI_TOKEN_FORMAT, credentialsPath, normalizeApiUrl, readCredentials, resolveAuth, writeCredentials, type Credentials, } from './credentials';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeCredentials = exports.resolveAuth = exports.readCredentials = exports.normalizeApiUrl = exports.credentialsPath = exports.CLI_TOKEN_FORMAT = exports.DEFAULT_API_URL = exports.VERSION = exports.renderRootHelp = exports.renderCommandHelp = exports.parseArgs = exports.exitForServerCode = exports.EXIT_CODE_TABLE = exports.EXIT = exports.COMMANDS = exports.run = void 0;
+// The programmatic surface. Small on purpose: this package is a BINARY, and everything exported
+// here is something the repo's own tests or a future MCP bridge needs to reach.
+var run_1 = require("./run");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_1.run; } });
+var commands_1 = require("./commands");
+Object.defineProperty(exports, "COMMANDS", { enumerable: true, get: function () { return commands_1.COMMANDS; } });
+var exit_codes_1 = require("./exit-codes");
+Object.defineProperty(exports, "EXIT", { enumerable: true, get: function () { return exit_codes_1.EXIT; } });
+Object.defineProperty(exports, "EXIT_CODE_TABLE", { enumerable: true, get: function () { return exit_codes_1.EXIT_CODE_TABLE; } });
+Object.defineProperty(exports, "exitForServerCode", { enumerable: true, get: function () { return exit_codes_1.exitForServerCode; } });
+var args_1 = require("./args");
+Object.defineProperty(exports, "parseArgs", { enumerable: true, get: function () { return args_1.parseArgs; } });
+var help_1 = require("./help");
+Object.defineProperty(exports, "renderCommandHelp", { enumerable: true, get: function () { return help_1.renderCommandHelp; } });
+Object.defineProperty(exports, "renderRootHelp", { enumerable: true, get: function () { return help_1.renderRootHelp; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });
+var credentials_1 = require("./credentials");
+Object.defineProperty(exports, "DEFAULT_API_URL", { enumerable: true, get: function () { return credentials_1.DEFAULT_API_URL; } });
+Object.defineProperty(exports, "CLI_TOKEN_FORMAT", { enumerable: true, get: function () { return credentials_1.CLI_TOKEN_FORMAT; } });
+Object.defineProperty(exports, "credentialsPath", { enumerable: true, get: function () { return credentials_1.credentialsPath; } });
+Object.defineProperty(exports, "normalizeApiUrl", { enumerable: true, get: function () { return credentials_1.normalizeApiUrl; } });
+Object.defineProperty(exports, "readCredentials", { enumerable: true, get: function () { return credentials_1.readCredentials; } });
+Object.defineProperty(exports, "resolveAuth", { enumerable: true, get: function () { return credentials_1.resolveAuth; } });
+Object.defineProperty(exports, "writeCredentials", { enumerable: true, get: function () { return credentials_1.writeCredentials; } });

package/dist/output.d.ts

@@ -0,0 +1,26 @@
+export type Writer = {
+    out: (text: string) => void;
+    err: (text: string) => void;
+};
+/** The real one. Injected everywhere so the whole surface is assertable without capturing a process. */
+export declare const processWriter: Writer;
+export type Emitter = {
+    readonly json: boolean;
+    /** A successful result. Under `--json` this is the one document; otherwise `human` is printed. */
+    ok(payload: Record<string, unknown>, human: string): void;
+    /** A failure. `code` is the machine-readable reason; `message` is the sentence. */
+    fail(code: string, message: string, extra?: Record<string, unknown>): void;
+    /** Progress and asides. NEVER reaches stdout under `--json`. */
+    note(text: string): void;
+};
+export declare function createEmitter(writer: Writer, json: boolean): Emitter;
+/** Left-pad a table column. No dependency, and no colour — see `--no-color`'s absence of an opposite. */
+export declare function pad(text: string, width: number): string;
+/**
+ * A plain-text table. Human mode only.
+ *
+ * Column widths are computed from the DATA, so a long flag key does not shear the row — the
+ * alternative (a fixed width with truncation) hides the end of exactly the identifiers a person is
+ * scanning for.
+ */
+export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;

package/dist/output.js

@@ -0,0 +1,68 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.1 — the two output modes, and the rule that separates
+// them.
+//
+// ── The rule: `--json` writes ONE JSON document to stdout, and nothing else, ever ─────────────
+// Not a progress line, not a warning, not a "minting…". An agent runs `gf … --json` and pipes
+// stdout into a parser; one stray human sentence makes the whole document unparseable, and it does
+// so intermittently — only on the runs that happened to warn. So under `--json`, stdout carries
+// exactly one `JSON.stringify` and every human word goes to stderr or nowhere.
+//
+// ── Errors go to STDOUT under --json, and that is deliberate ──────────────────────────────────
+// The reflex is stderr. It is wrong here: the machine-readable failure IS the result, and a caller
+// who captured stdout and got an empty string cannot tell a failure from a command that produced
+// nothing. The exit code says it failed; stdout says why, in the same shape as a success. Human
+// mode keeps errors on stderr, where a human's shell expects them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processWriter = void 0;
+exports.createEmitter = createEmitter;
+exports.pad = pad;
+exports.table = table;
+/** The real one. Injected everywhere so the whole surface is assertable without capturing a process. */
+exports.processWriter = {
+    out: (text) => process.stdout.write(`${text}\n`),
+    err: (text) => process.stderr.write(`${text}\n`),
+};
+function createEmitter(writer, json) {
+    return {
+        json,
+        ok(payload, human) {
+            if (json)
+                writer.out(JSON.stringify({ ok: true, ...payload }, null, 2));
+            else
+                writer.out(human);
+        },
+        fail(code, message, extra) {
+            if (json)
+                writer.out(JSON.stringify({ ok: false, code, error: message, ...extra }, null, 2));
+            else
+                writer.err(message);
+        },
+        note(text) {
+            // Under `--json` a note is DROPPED, not redirected to stderr. Redirecting looks tidier and is
+            // worse: CI captures stderr too, and an agent asked to report the command's output would
+            // surface a progress line as though it were part of the answer.
+            if (!json)
+                writer.err(text);
+        },
+    };
+}
+/** Left-pad a table column. No dependency, and no colour — see `--no-color`'s absence of an opposite. */
+function pad(text, width) {
+    return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+/**
+ * A plain-text table. Human mode only.
+ *
+ * Column widths are computed from the DATA, so a long flag key does not shear the row — the
+ * alternative (a fixed width with truncation) hides the end of exactly the identifiers a person is
+ * scanning for.
+ */
+function table(headers, rows) {
+    const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => (row[column] ?? '').length)));
+    const line = (cells) => cells
+        .map((cell, column) => pad(cell ?? '', widths[column]))
+        .join('  ')
+        .trimEnd();
+    return [line(headers), line(widths.map((width) => '─'.repeat(width))), ...rows.map(line)].join('\n');
+}

package/dist/run.d.ts

@@ -0,0 +1,13 @@
+import { type Command } from './command';
+import { type ExitCode } from './exit-codes';
+import { type Writer } from './output';
+export type RunOptions = {
+    argv: readonly string[];
+    writer?: Writer;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    /** Injected in tests. Production passes nothing and the global `fetch` is used. */
+    fetchImpl?: typeof fetch;
+    commands?: readonly Command[];
+};
+export declare function run(options: RunOptions): Promise<ExitCode>;

package/dist/run.js

@@ -0,0 +1,135 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.1 — the dispatcher.
+//
+// ── `run()` returns an exit code; only `bin.ts` calls `process.exit` ──────────────────────────
+// So the whole CLI can be driven in-process by a test with a captured writer, an injected `fetch`
+// and a temporary HOME — and asserted on its exact bytes and its exit code. A dispatcher that
+// exited the process could only be tested by spawning one, which is how a CLI ends up with three
+// assertions and a lot of confidence.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const args_1 = require("./args");
+const api_1 = require("./api");
+const command_1 = require("./command");
+const commands_1 = require("./commands");
+const credentials_1 = require("./credentials");
+const exit_codes_1 = require("./exit-codes");
+const help_1 = require("./help");
+const output_1 = require("./output");
+const version_1 = require("./version");
+async function run(options) {
+    const writer = options.writer ?? output_1.processWriter;
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const commands = options.commands ?? commands_1.COMMANDS;
+    const args = (0, args_1.parseArgs)(options.argv);
+    const emit = (0, output_1.createEmitter)(writer, args.json);
+    // `--version` before everything, including before the command table: someone asking which version
+    // they have is asking a question about the binary, not about a verb, and it must answer on a
+    // machine with no credential, no network and a typo in the command.
+    //
+    // ⚠️ **`args.path.length === 0` used to be part of this condition, and that made `--help`'s
+    // "global flags" section false** (cross-family review, Codex, PR #149). `gf whoami --version`
+    // entered `whoami`, demanded a credential and then made a network call — for a question about the
+    // binary. A flag documented as global is honoured globally, as `git --version` and `npm --version`
+    // are; the alternative is a help text an agent cannot trust, which is the whole of D5.
+    if (args.version) {
+        emit.ok({ version: version_1.VERSION }, version_1.VERSION);
+        return exit_codes_1.EXIT.OK;
+    }
+    if (args.path.length === 0 || args.path[0] === 'help') {
+        const target = args.path[0] === 'help' ? args.path.slice(1) : [];
+        if (target.length > 0) {
+            const found = (0, command_1.matchCommand)(commands, target);
+            if (!found)
+                return unknownCommand(target, emit);
+            // Through the EMITTER, not `writer.out`. Writing help directly bypassed `--json` entirely, so
+            // `gf --json help <verb>` emitted prose on the stdout an agent was parsing (Codex, round 2).
+            emit.ok({ help: (0, help_1.commandAsData)(found.command) }, (0, help_1.renderCommandHelp)(found.command));
+            return exit_codes_1.EXIT.OK;
+        }
+        emit.ok({ help: (0, help_1.helpAsData)(commands) }, (0, help_1.renderRootHelp)(commands));
+        // `gf` with no arguments prints help and exits 0 — it is what a person types to find out what
+        // this is, and answering their question is not an error. `gf nonsense` is (see below).
+        return exit_codes_1.EXIT.OK;
+    }
+    const found = (0, command_1.matchCommand)(commands, args.path);
+    if (!found)
+        return unknownCommand(args.path, emit);
+    const { command, rest } = found;
+    if (args.help) {
+        emit.ok({ help: (0, help_1.commandAsData)(command) }, (0, help_1.renderCommandHelp)(command));
+        return exit_codes_1.EXIT.OK;
+    }
+    // Leftover path words become positionals. `gf flags get checkout.demo` matches `['flags','get']`
+    // and leaves `checkout.demo`, which is how a verb receives its subject without the parser needing
+    // to know the arity of every command.
+    const withPositionals = { ...args, positionals: [...rest, ...args.positionals] };
+    // ⚠️ An unknown flag is a USAGE ERROR, not something to ignore. An agent that types `--environment`
+    // for `--env` and is silently ignored gets a flag created in the wrong place, with exit 0 — the
+    // CLI agreeing with a command nobody wrote.
+    const unknown = (0, args_1.unknownFlags)(withPositionals, command.flags.map((flag) => flag.name));
+    if (unknown.length > 0) {
+        emit.fail('invalid', `Unknown flag${unknown.length === 1 ? '' : 's'} for \`gf ${command.path.join(' ')}\`: ` +
+            `${unknown.map((name) => `--${name}`).join(', ')}. Run \`gf ${command.path.join(' ')} --help\`.`);
+        return exit_codes_1.EXIT.USAGE;
+    }
+    // ⚠️ **A flag supplied with an EMPTY value is a usage error — for every flag, not one** (cross-family
+    // review, Codex, round 6). `gf init --project "$UNSET_VAR"` expands to `--project ""`, and every
+    // resolver here is written `flagValue(...)?.trim() || <default>`, so the empty string is falsy and
+    // silently FELL BACK to the remembered project — minting a credential for a tenant the caller
+    // did not name, having visibly tried to name one. The reviewer found it on `--project`; the same
+    // `|| default` shape sits behind `--env`, `--api`, `--token` and `--reason`.
+    //
+    // Fixed at the parser boundary so the class is gone rather than one instance patched: a caller
+    // who typed a flag meant to supply it, and an empty value is never what they meant.
+    const blank = [...withPositionals.flags.entries()]
+        .filter(([, values]) => values.some((value) => value.trim() === ''))
+        .map(([name]) => `--${name}`)
+        .sort();
+    if (blank.length > 0) {
+        emit.fail('invalid', `${blank.join(', ')} ${blank.length === 1 ? 'was' : 'were'} given no value. An empty value is ` +
+            `refused rather than defaulted — check for an unset shell variable.`);
+        return exit_codes_1.EXIT.USAGE;
+    }
+    const auth = (0, credentials_1.resolveAuth)({
+        tokenFlag: (0, args_1.flagValue)(withPositionals, 'token'),
+        apiFlag: (0, args_1.flagValue)(withPositionals, 'api'),
+        env,
+    });
+    const clientFor = (token) => (0, api_1.createApiClient)({
+        baseUrl: auth.apiUrl,
+        token,
+        userAgent: `golden-frijoles-cli/${version_1.VERSION}`,
+        fetchImpl: options.fetchImpl,
+    });
+    if (command.needsAuth && auth.token === null) {
+        // ONE sentence, in one place, rather than every verb re-checking and phrasing it differently.
+        emit.fail('unauthorized', 'Not signed in. Run `gf login`, or set GOLDEN_FRIJOLES_TOKEN. `gf doctor` explains what it found.');
+        return exit_codes_1.EXIT.AUTH;
+    }
+    const context = {
+        args: withPositionals,
+        emit,
+        writer,
+        auth,
+        env,
+        cwd,
+        api: auth.token === null ? null : clientFor(auth.token),
+        clientFor,
+        fetchImpl: options.fetchImpl ?? fetch,
+    };
+    try {
+        return await command.run(context);
+    }
+    catch (err) {
+        // A handler that throws is a bug in this CLI, and it says so rather than printing a stack the
+        // caller cannot act on. EXIT.SERVER because the remedy — retry, then report — is the same.
+        emit.fail('server_error', `\`gf ${command.path.join(' ')}\` failed unexpectedly: ${err instanceof Error ? err.message : String(err)}`);
+        return exit_codes_1.EXIT.SERVER;
+    }
+}
+function unknownCommand(path, emit) {
+    emit.fail('invalid', `Unknown command \`gf ${path.join(' ')}\`. Run \`gf --help\` for the list.`);
+    return exit_codes_1.EXIT.USAGE;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+// The published version, as a constant.
+//
+// ⚠️ **Not `require('../package.json').version`.** The build emits `dist/` beside `package.json`, so
+// the relative path differs between source and build, and a `resolveJsonModule` import would put a
+// copy of the manifest into the bundle. Worse, it is exactly the kind of runtime lookup that
+// silently returns `undefined` on a packaging change and prints `gf undefined`.
+//
+// It is a literal, and `version.test.ts` asserts it equals `package.json`'s — so the two cannot
+// drift, and the drift is caught by the unit gate rather than by someone reading `gf --version`.
+exports.VERSION = '0.1.0';

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@golden-frijoles/cli",
+  "private": false,
+  "version": "0.1.0",
+  "description": "The Golden Frijoles CLI — create, roll out and kill feature flags from a terminal, or from an agent.",
+  "bin": {
+    "gf": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "feature-flags",
+    "cli",
+    "golden-frijoles",
+    "agent"
+  ],
+  "license": "UNLICENSED",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ./scripts/make-executable.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@golden-frijoles/sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  }
+}