@golden-frijoles/cli 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @golden-frijoles/cli
+
+Create a feature flag in every environment, roll it out, and kill it — from a terminal, or from an
+agent. No browser, no human click.
+
+```bash
+npx @golden-frijoles/cli --version
+```
+
+## The one-minute version
+
+```bash
+npm i -g @golden-frijoles/cli          # or use npx for everything below
+
+gf login                                # paste a token from /app/setup/cli
+gf init                                 # project + key + .env.local + the snippet
+gf flags create checkout.demo_enabled --kill-switch --all-envs
+gf flags rollout checkout.demo_enabled --env production --percent 25
+gf flags kill checkout.demo_enabled --env production
+```
+
+## Why this exists
+
+Every high-risk change ships behind a flag, and a flag is invisible until it exists **in the
+provider**. Before this, the one line of a release that most needs to be reliable — *create the flag
+in every environment* — was the line that stopped and waited for someone to open a browser.
+
+`gf flags create … --all-envs` is that line.
+
+## Signing in
+
+Mint a token at **`/app/setup/cli`** in the console, then:
+
+```bash
+gf login                # reads the token from stdin — never from argv, never from your history
+gf whoami               # who you are, which credential, which projects
+```
+
+In CI, set `GOLDEN_FRIJOLES_TOKEN` and skip `gf login` entirely. Nothing is written to disk on that
+path.
+
+A token signs you in as **you**: it can do exactly what your console session can do, across every
+project you are a member of, and nothing more. Revoke it at `/app/setup/cli`.
+
+## Polarity — the thing to get right
+
+A flag's polarity decides what it serves the day it is born, and the CLI derives everything else
+from it, so the wrong combination is not expressible:
+
+| You type | Default variant | Every environment serves | Reach for it when |
+|---|---|---|---|
+| `--kill-switch` | `on` | `true` | it is **on** until you kill it |
+| `--enablement` | `off` | `false` | you will **open** it deliberately later |
+
+Both polarities **activate in every environment you name.** "Created disabled" means *serving
+`false`*, not *absent* — a flag that is not activated is missing from the 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.
+
+## `--all-envs`, and what happens when one fails
+
+Three environments, three writes, no transaction. So:
+
+- each environment is written **idempotently**,
+- you get a **per-environment report**, and
+- the exit code is **5** if any environment failed.
+
+Never a silent partial.
+
+## `--json` everywhere
+
+Every command takes `--json`. Under it, **stdout carries exactly one JSON document and nothing
+else** — no progress lines, no warnings. A failure is a JSON document too, on stdout, with a stable
+`code`:
+
+```json
+{ "ok": false, "code": "not_found", "error": "No project `acme` is available to this account." }
+```
+
+`--help` output and these envelopes are pinned by golden-file tests. They do not change on a copy
+edit.
+
+## Exit codes
+
+| Code | Name | Means |
+|---|---|---|
+| `0` | ok | it worked |
+| `1` | usage | the command is wrong — nothing was sent |
+| `2` | auth | the credential is not accepted — run `gf login` |
+| `3` | not-found | no such thing, or not yours |
+| `4` | conflict | someone else changed it — re-read and retry |
+| `5` | partial | some environments changed and some did not |
+| `6` | server | the server or the network is unwell — retry |
+
+## When something is wrong
+
+```bash
+gf doctor
+```
+
+It runs without a credential — diagnosing a missing one is the point — and reports every check it
+could run: the credentials file, the credential, its shape, whether the deployment answers, whether
+it accepts you, whether your active project is reachable, and whether this CLI is current. It never
+prints key material.
+
+## Environment
+
+| Variable | What it does |
+|---|---|
+| `GOLDEN_FRIJOLES_TOKEN` | a CLI token; wins over the saved credential. The CI path. |
+| `GOLDEN_FRIJOLES_URL` | the deployment to talk to |
+| `GOLDEN_FRIJOLES_PROJECT` | the active project |
+
+`gf init` writes `GOLDEN_FRIJOLES_URL`, `GOLDEN_FRIJOLES_FLAG_READ_KEY` and
+`GOLDEN_FRIJOLES_ENVIRONMENT` into `.env.local` (mode `0600`), adds that file to `.gitignore` — or
+refuses — and prints the `@golden-frijoles/sdk` snippet that reads exactly those names.
+
+## What it deliberately does not do
+
+- **Send events.** That is the SDK's path (`@golden-frijoles/sdk`), and a second one would be a
+  parallel pipeline.
+- **Experiments, journeys, north star, scenarios, destinations, breakers.** Out of v1 on purpose.
+- **A TUI.** Plain output and `--json`.
+- **Plans and quotas.** Every account is unlimited today; `gf` will learn about plans when there is
+  a plan to learn about.

package/dist/api.d.ts

@@ -0,0 +1,28 @@
+export type ApiSuccess<T> = {
+    kind: 'ok';
+    status: number;
+    body: T;
+};
+export type ApiFailure = {
+    kind: 'error';
+    status: number;
+    code: string;
+    message: string;
+    body: Record<string, unknown>;
+} | {
+    kind: 'network';
+    message: string;
+};
+export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
+export type ApiClient = {
+    readonly baseUrl: string;
+    get<T>(path: string, query?: Record<string, string | undefined>): Promise<ApiResult<T>>;
+    post<T>(path: string, body: unknown): Promise<ApiResult<T>>;
+    del<T>(path: string, query?: Record<string, string | undefined>): Promise<ApiResult<T>>;
+};
+export declare function createApiClient(options: {
+    baseUrl: string;
+    token: string;
+    userAgent: string;
+    fetchImpl?: typeof fetch;
+}): ApiClient;

package/dist/api.js

@@ -0,0 +1,104 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1 — the only place this package speaks HTTP.
+//
+// ── One client, so one place decides what a failure MEANS ─────────────────────────────────────
+// Every command returns `ApiResult`, which carries the server's own `code` (`unauthorized`,
+// `not_found`, `conflict`, `invalid`, `disabled`) rather than an HTTP status. The status is an
+// implementation detail of the transport; the code is the contract `lib/cli-auth.ts` publishes, and
+// `exitForServerCode` is the one mapping from it to an exit code.
+//
+// ── A network failure is NOT a 500 and must not read like one ─────────────────────────────────
+// `fetch` rejecting (DNS, a dropped connection, a timeout) produces `kind: 'network'`, separate
+// from a server that answered badly. The remedy differs: one is "check your connection or the URL",
+// the other is "the deployment is unwell". `gf doctor`'s whole job is telling those apart, and it
+// cannot if the client has already collapsed them.
+//
+// ── A non-JSON body is a failure, not an empty success ────────────────────────────────────────
+// A proxy's HTML error page parses as nothing; treating that as `{}` would let a command report
+// success against a response it never understood (CODE-QUALITY #7).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiClient = createApiClient;
+/** How long any single request may take. A CLI that hangs is a CI job that hangs. */
+const TIMEOUT_MS = 30_000;
+function createApiClient(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    async function request(method, path, init) {
+        const url = new URL(path, `${options.baseUrl}/`);
+        for (const [key, value] of Object.entries(init.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, value);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        let response;
+        try {
+            response = await doFetch(url.toString(), {
+                method,
+                headers: {
+                    // The credential. Never in the URL — a URL travels through history, proxy logs and
+                    // screenshots, which is the argument the connector-token migration makes at length.
+                    authorization: `Bearer ${options.token}`,
+                    accept: 'application/json',
+                    'user-agent': options.userAgent,
+                    ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+                },
+                body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error && err.name === 'AbortError'
+                ? `No answer from ${options.baseUrl} within ${TIMEOUT_MS / 1000}s.`
+                : `Could not reach ${options.baseUrl}: ${err instanceof Error ? err.message : String(err)}`;
+            return { kind: 'network', message };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await response.text();
+        let parsed;
+        try {
+            parsed = text === '' ? {} : JSON.parse(text);
+        }
+        catch {
+            // An HTML error page from a proxy, or a 404 from a deployment that does not have these routes.
+            // Reported with the STATUS in the sentence, because that is the only thing we actually learned.
+            return {
+                kind: 'error',
+                status: response.status,
+                code: 'server_error',
+                message: `${options.baseUrl} answered ${response.status} with a body that is not JSON.`,
+                body: {},
+            };
+        }
+        const body = (parsed ?? {});
+        if (response.ok && body.ok !== false)
+            return { kind: 'ok', status: response.status, body: body };
+        return {
+            kind: 'error',
+            status: response.status,
+            // The server's own vocabulary, with a status-derived fallback for a response that came from
+            // somewhere else in the stack (a Vercel 502, an upstream 404) and carries no `code`.
+            code: typeof body.code === 'string' ? body.code : codeFromStatus(response.status),
+            message: typeof body.error === 'string' ? body.error : `Request failed with status ${response.status}.`,
+            body,
+        };
+    }
+    function codeFromStatus(status) {
+        if (status === 401 || status === 403)
+            return 'unauthorized';
+        if (status === 404)
+            return 'not_found';
+        if (status === 409)
+            return 'conflict';
+        if (status === 400 || status === 422)
+            return 'invalid';
+        return 'server_error';
+    }
+    return {
+        baseUrl: options.baseUrl,
+        get: (path, query) => request('GET', path, { query }),
+        post: (path, body) => request('POST', path, { body }),
+        del: (path, query) => request('DELETE', path, { query }),
+    };
+}

package/dist/args.d.ts

@@ -0,0 +1,26 @@
+export type ParsedArgs = {
+    /** The verb path: `['flags', 'create']` for `gf flags create …`. */
+    path: string[];
+    /** Everything that was not a flag and not part of the verb path. */
+    positionals: string[];
+    /** `--flag value`, `--flag=value` and repeated flags (which accumulate). */
+    flags: Map<string, string[]>;
+    /** `--json` anywhere. Hoisted because every command honours it. */
+    json: boolean;
+    /** `--help`/`-h` anywhere, including after a verb. */
+    help: boolean;
+    /** `--version`/`-V` anywhere. */
+    version: boolean;
+};
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare function flagValue(args: ParsedArgs, name: string): string | undefined;
+export declare function flagValues(args: ParsedArgs, name: string): string[];
+export declare function boolFlag(args: ParsedArgs, name: string): boolean;
+/**
+ * Flags the caller passed that this command does not know about.
+ *
+ * ⚠️ **Reported as a usage error rather than ignored, and that is not pedantry.** An agent that
+ * types `--environment` instead of `--env` and is silently ignored gets a flag created in the wrong
+ * place with exit 0 — the CLI agreeing with a command nobody wrote. Fail loud (CODE-QUALITY #7).
+ */
+export declare function unknownFlags(args: ParsedArgs, known: readonly string[]): string[];

package/dist/args.js

@@ -0,0 +1,156 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.1 — the argument parser. PURE, and no dependency.
+//
+// ── Why hand-written and not `commander`/`yargs` ──────────────────────────────────────────────
+// A published CLI's dependency tree is its install time and its supply-chain surface, and this one
+// is meant to be reached with `npx` on a machine that has never seen it. The whole grammar here is
+// "verbs, then `--flag value`", which is forty lines. A parser library would be the largest thing
+// in the package by an order of magnitude, to save those forty lines.
+//
+// ── Pure, so the contract can be asserted without spawning anything ───────────────────────────
+// Every parsing rule below is tested directly (CODE-QUALITY #5). Spawning `gf` to find out whether
+// `--percent` accepts `=` is a test that also exercises the network, the filesystem and a token.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.flagValue = flagValue;
+exports.flagValues = flagValues;
+exports.boolFlag = boolFlag;
+exports.unknownFlags = unknownFlags;
+/**
+ * Boolean flags — the ones that take NO value.
+ *
+ * ⚠️ A closed list, and it has to exist. Without it `gf flags create k --all-envs --kill-switch`
+ * parses `--kill-switch` as the VALUE of `--all-envs`, and the command then silently creates a flag
+ * in one environment with no polarity — a wrong result from a correct-looking command line, which
+ * is the worst failure shape a CLI has. Adding a boolean flag means adding it here.
+ */
+const BOOLEAN_FLAGS = new Set([
+    'json',
+    'help',
+    'h',
+    'version',
+    'V',
+    'all-envs',
+    'kill-switch',
+    'enablement',
+    'dry-run',
+    'yes',
+    'no-color',
+]);
+function parseArgs(argv) {
+    const path = [];
+    const positionals = [];
+    const flags = new Map();
+    function push(name, value) {
+        flags.set(name, [...(flags.get(name) ?? []), value]);
+    }
+    // ⚠️ **Every bare word goes to `path`, wherever it appears — not only the LEADING run** (cross-
+    // family review, Codex, round 8). The first version collected the path only until the first
+    // flag, so `gf --json flags ls` parsed as an empty path and printed ROOT HELP with exit 0 — an
+    // agent that put its global flags first (which the help calls "global" and the README says work
+    // "anywhere") got a success code and none of the output it asked for.
+    //
+    // The command table decides where the verb ends and the subject begins: `matchCommand` takes the
+    // longest known prefix and hands the rest to the verb as positionals. So `path` here is simply
+    // "the bare words, in order", and flags may sit anywhere among them. A value-taking flag still
+    // consumes its value below, so `--env production` never leaks `production` into the path.
+    for (let index = 0; index < argv.length; index++) {
+        const token = argv[index];
+        if (!token.startsWith('-')) {
+            path.push(token);
+            continue;
+        }
+        // `--` ends flag parsing: everything after it is a positional, even if it starts with a dash.
+        // A rules file called `--weird.json` is not this CLI's problem to guess about.
+        if (token === '--') {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        const body = token.replace(/^--?/, '');
+        const equals = body.indexOf('=');
+        if (equals !== -1) {
+            // `--flag=value` always carries its own value, even for a name in BOOLEAN_FLAGS — `--json=false`
+            // is a caller saying something explicit, and swallowing the `=false` would invert it.
+            push(body.slice(0, equals), body.slice(equals + 1));
+            continue;
+        }
+        if (BOOLEAN_FLAGS.has(body)) {
+            push(body, 'true');
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next === undefined || next.startsWith('-')) {
+            // A value-taking flag with nothing after it. Recorded as EMPTY rather than as `true`, so the
+            // command reports "--env needs a value" instead of treating the flag as a boolean it is not.
+            push(body, '');
+            continue;
+        }
+        push(body, next);
+        index++;
+    }
+    return {
+        path,
+        positionals,
+        flags,
+        json: readBoolean(flags, 'json'),
+        help: readBoolean(flags, 'help') || readBoolean(flags, 'h'),
+        version: readBoolean(flags, 'version') || readBoolean(flags, 'V'),
+    };
+}
+/**
+ * A boolean flag's value.
+ *
+ * Present with no value ⇒ true. `--flag=false` / `=0` / `=no` ⇒ false, because a caller who typed
+ * an explicit value meant it. Anything else present ⇒ true.
+ */
+function readBoolean(flags, name) {
+    const values = flags.get(name);
+    if (values === undefined)
+        return false;
+    const last = values[values.length - 1];
+    return !['false', '0', 'no', 'off'].includes(last.toLowerCase());
+}
+function flagValue(args, name) {
+    const values = args.flags.get(name);
+    // The LAST wins for a single-valued flag: `--env production --env preview` on a verb that takes
+    // one environment is a caller correcting themselves, and taking the first would silently act on
+    // the value they replaced.
+    return values === undefined ? undefined : values[values.length - 1];
+}
+function flagValues(args, name) {
+    return (args.flags.get(name) ?? []).filter((value) => value !== '');
+}
+function boolFlag(args, name) {
+    return readBoolean(args.flags, name);
+}
+/**
+ * Flags the caller passed that this command does not know about.
+ *
+ * ⚠️ **Reported as a usage error rather than ignored, and that is not pedantry.** An agent that
+ * types `--environment` instead of `--env` and is silently ignored gets a flag created in the wrong
+ * place with exit 0 — the CLI agreeing with a command nobody wrote. Fail loud (CODE-QUALITY #7).
+ */
+function unknownFlags(args, known) {
+    // ⚠️ **`project` belongs in this list, and its absence made `gf --help` lie** (fresh reviewer,
+    // PR #149). The help's "Global flags" block documents `--project`, and six verbs — `whoami`,
+    // `login`, `logout`, `projects ls|create|use` — rejected it with exit 1 and a JSON error saying
+    // the flag it had just been shown does not exist.
+    //
+    // This is the identical defect `run.ts` records fixing for `--version` in the same review: a flag
+    // documented as global is honoured globally, and the alternative is a help text an agent cannot
+    // trust, which is the whole of D5. Accepting it on a verb that ignores it costs nothing; the
+    // verbs that USE it still declare it so it appears in their own `--help`.
+    const allowed = new Set([
+        ...known,
+        'json',
+        'help',
+        'h',
+        'version',
+        'V',
+        'no-color',
+        'api',
+        'token',
+        'project',
+    ]);
+    return [...args.flags.keys()].filter((name) => !allowed.has(name)).sort();
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// The executable. The ONLY place in this package that touches `process.exit` or `process.argv`.
+//
+// Everything else returns an exit code, which is what lets the whole CLI run in-process in a test
+// with a captured writer and an injected `fetch`.
+const run_1 = require("./run");
+(0, run_1.run)({ argv: process.argv.slice(2) })
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    // `run()` already catches a handler throwing. Reaching here means the dispatcher itself failed —
+    // a broken install, an unreadable module. Say so plainly rather than printing a bare stack.
+    process.stderr.write(`gf failed to start: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 6;
+});

package/dist/command.d.ts

@@ -0,0 +1,75 @@
+import type { ParsedArgs } from './args';
+import type { ApiClient } from './api';
+import type { Emitter, Writer } from './output';
+import type { ResolvedAuth } from './credentials';
+import type { ExitCode } from './exit-codes';
+export type FlagDoc = {
+    /** `--env`, written without the dashes. */
+    name: string;
+    /** The value's placeholder — `<environment>` — or undefined for a boolean flag. */
+    value?: string;
+    describe: string;
+};
+export type CommandContext = {
+    args: ParsedArgs;
+    emit: Emitter;
+    writer: Writer;
+    auth: ResolvedAuth;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /**
+     * The HTTP client, already carrying the resolved token.
+     *
+     * `null` when there is no credential. A command with `needsAuth: true` never sees `null` — the
+     * dispatcher refuses first, with EXIT.AUTH and one sentence — so handlers do not each re-check.
+     */
+    api: ApiClient | null;
+    /** Build a client against an arbitrary token. `gf login` needs one before a token is saved. */
+    clientFor(token: string): ApiClient;
+    /**
+     * The `fetch` this run should use, for the ONE call that is not to this deployment's API.
+     *
+     * ⚠️ Only `gf doctor`'s npm-registry check needs it, and it exists because the alternative was a
+     * bare global `fetch` — which is how `packages/cli` grew a second HTTP path twice in one sprint
+     * (`probeFlagReadKey` was the other). A direct global call skips the injected stub, so
+     * `npm run test:unit` made a REAL network request to registry.npmjs.org on every doctor test, and
+     * the check it performs could not be asserted at all.
+     *
+     * Everything talking to the deployment goes through `api` / `clientFor` instead — this is not a
+     * general escape hatch, and a second consumer should be a reason to ask why.
+     */
+    fetchImpl: typeof fetch;
+};
+export type Command = {
+    /** `['flags', 'create']`. The dispatcher matches the LONGEST path first. */
+    path: string[];
+    summary: string;
+    /** One line, as a person would type it. Rendered into `--help` and pinned by the golden file. */
+    usage: string;
+    flags: FlagDoc[];
+    /**
+     * Does this verb need a credential?
+     *
+     * `false` for `login`, `doctor`, `help` and `version` — and `doctor` is the important one: its job
+     * is diagnosing a missing credential, so a dispatcher that refused it for want of one would make
+     * the tool useless exactly when it is needed.
+     */
+    needsAuth: boolean;
+    /** Longer prose for `gf <verb> --help`. Optional; the summary carries most verbs. */
+    detail?: string;
+    run(context: CommandContext): Promise<ExitCode>;
+};
+/**
+ * Find the command whose path is the longest prefix of what was typed.
+ *
+ * Longest-first so `flags create` wins over a hypothetical bare `flags`, and so adding a
+ * sub-verb later cannot shadow an existing one by accident.
+ *
+ * Returns the leftover words as `positionals` — `gf flags get checkout.demo` matches
+ * `['flags','get']` and leaves `['checkout.demo']`, which is how a verb receives its subject
+ * without the parser having to know the arity of every command.
+ */
+export declare function matchCommand(commands: readonly Command[], path: readonly string[]): {
+    command: Command;
+    rest: string[];
+} | null;

package/dist/command.js

@@ -0,0 +1,34 @@
+"use strict";
+// golden-frijoles-cli · Sprint 1, Story 1.1 — the command shape, and the context every verb gets.
+//
+// ── One table, and `--help` is RENDERED from it ───────────────────────────────────────────────
+// The help text is not written anywhere. It is generated from the same array the dispatcher reads,
+// so a verb cannot exist without being documented and cannot be documented without existing — and
+// the golden file (D5) then pins the rendered result. The failure this prevents is ordinary and
+// constant: a flag added to a handler and not to its help, which an agent then never learns about.
+//
+// ── Why a handler returns an exit code instead of calling process.exit ────────────────────────
+// So the whole CLI can be run in-process by a test, with a captured writer and an injected `fetch`,
+// and asserted on its exit code and its exact bytes. A handler that exits the process is a handler
+// that can only be tested by spawning one.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchCommand = matchCommand;
+/**
+ * Find the command whose path is the longest prefix of what was typed.
+ *
+ * Longest-first so `flags create` wins over a hypothetical bare `flags`, and so adding a
+ * sub-verb later cannot shadow an existing one by accident.
+ *
+ * Returns the leftover words as `positionals` — `gf flags get checkout.demo` matches
+ * `['flags','get']` and leaves `['checkout.demo']`, which is how a verb receives its subject
+ * without the parser having to know the arity of every command.
+ */
+function matchCommand(commands, path) {
+    const byLength = [...commands].sort((left, right) => right.path.length - left.path.length);
+    for (const command of byLength) {
+        if (command.path.every((segment, index) => path[index] === segment)) {
+            return { command, rest: path.slice(command.path.length) };
+        }
+    }
+    return null;
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from '../command';
+export declare const loginCommand: Command;
+export declare const logoutCommand: Command;
+export declare const whoamiCommand: Command;