@greatwait/cli 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowXO LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @greatwait/cli
+
+The Greatwait command line. Install it, sign in, and reach a first callback
+against a receiver you control.
+
+```sh
+npm install --global @greatwait/cli
+greatwait login --api-url https://api.greatwait.dev
+greatwait journey
+```
+
+## What it is
+
+A thin executable over the public API — the same operations `@greatwait/api-client`
+exposes and the same contracts the OpenAPI document publishes. It adds no
+endpoint, no retry policy and no behaviour of its own: anything you can do here
+you can do with `curl`, and anything you cannot do with `curl` you cannot do
+here.
+
+## Signing in
+
+`greatwait login` uses OAuth: it registers itself with the service, opens your
+browser, and receives the answer on a loopback port it has already bound.
+Nothing is configured — the endpoints come from the origin's own published
+metadata.
+
+```sh
+greatwait login                 # opens a browser
+greatwait login --no-browser    # prints the address to open yourself
+```
+
+For automation, use a scoped API credential created in the dashboard. It is
+never taken as a command-line argument, because an argument is visible to every
+other process on the machine and is written to your shell history:
+
+```sh
+printf %s "$GREATWAIT_API_KEY" | greatwait login --api-key
+```
+
+or export `GREATWAIT_API_KEY` and skip signing in altogether.
+
+Credentials are stored per API origin in your platform's configuration
+directory, readable by you and nobody else. A staging credential is never
+presented to production, because the two are separate entries rather than one
+current context.
+
+## First value
+
+`greatwait journey` prints the published first-value sequence — the same nine
+steps the website and the quickstarts walk — with the command for each one.
+
+```sh
+greatwait destinations create --url https://your-receiver.example.com/greatwait
+greatwait schedules create --endpoint ep_… --in 30s --data '{"greeting":"first value"}'
+greatwait occurrences wait sch_… occ_…
+greatwait attempts list sch_… occ_…
+```
+
+## Output and exit codes
+
+`--json` is a versioned machine shape, not a serialization of the human text.
+The exit status is a class rather than a code per failure:
+
+| code | meaning                                                                |
+| ---: | ---------------------------------------------------------------------- |
+|    0 | it worked                                                              |
+|    1 | a defect in this command                                               |
+|    2 | the command line was wrong                                             |
+|    3 | no usable credential — `greatwait login`                               |
+|    4 | the credential may not do this                                         |
+|    5 | the request was refused on its merits                                  |
+|    6 | the service could not answer now; the identical request may work later |
+|    7 | a deadline passed                                                      |
+|  130 | interrupted                                                            |
+
+The service's own problem code is preserved in `--json` and in the message, so a
+script that already branches on one against the REST surface does not need a
+second vocabulary.
+
+## License
+
+MIT

package/dist/args.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The command line, parsed.
+ *
+ * **Deliberately small, and one rule in it is a security control rather than a
+ * convenience.** `--api-key` takes no value. Not "should not" — cannot: the
+ * parser refuses `--api-key=…` and refuses a bare `--api-key` followed by
+ * anything that is not another option. Every other argument on a process's
+ * command line is readable by any other process on the machine through `ps`,
+ * lands in shell history, and is captured by a crash reporter; a flag that
+ * accepted a secret would be a flag somebody uses once in a script and never
+ * looks at again.
+ */
+export interface ParsedArguments {
+    readonly booleans: ReadonlySet<string>;
+    readonly command: readonly string[];
+    readonly options: Readonly<Record<string, string>>;
+}
+/**
+ * What to say to somebody who has just put a credential in their shell history.
+ *
+ * One sentence about the harm and two ways to avoid it, stated once because
+ * both spellings — attached and separated — deserve the same answer. Neither
+ * repeats the value back.
+ */
+export declare const SECRET_ARGUMENT_ADVICE = "A credential given as an argument is visible to every process on this machine and is written to your shell history \u2014 treat the one you just typed as exposed and replace it. Run the command with a bare --api-key and paste the secret when asked, or pipe it in: printf %s \"$KEY\" | greatwait login --api-key";
+export declare function parseArguments(argv: readonly string[], 
+/**
+ * The words that begin a command, so the rule below can tell a subcommand
+ * from a leaked secret.
+ *
+ * **Without it the rule refused `greatwait --api-key login`.** The parser is
+ * position-independent by design, so a bare `--api-key` before the command
+ * word is a legitimate line that used to work; refusing it says "this flag
+ * does not take a value" to somebody who never typed one. Passed in rather
+ * than imported, because `commands.ts` reads this module and the cycle would
+ * be the wrong way round.
+ */
+commandWords?: ReadonlySet<string>): ParsedArguments;
+/**
+ * A duration written the way a person writes one: `30s`, `5m`, `2h`.
+ *
+ * Bare digits are refused rather than assumed to be seconds. "in 30" is a
+ * sentence with a missing word, and guessing at it is how somebody schedules
+ * something thirty milliseconds — or thirty hours — from now.
+ */
+export declare function parseDuration(value: string): number;

package/dist/args.js

@@ -0,0 +1,118 @@
+import { CliError } from "./runtime.js";
+/** Options that take a value. Anything else is a boolean flag. */
+const VALUED_OPTIONS = new Set([
+    "--api-url",
+    "--at",
+    "--data",
+    "--endpoint",
+    "--idempotency-key",
+    "--in",
+    "--scope",
+    "--timeout",
+    "--url",
+]);
+/**
+ * Options that must never take a value, whatever they look like.
+ *
+ * Separate from "not in `VALUED_OPTIONS`" so the refusal can say *why* — a
+ * person who typed `--api-key sk_...` has just put a secret in their shell
+ * history and needs to be told that, not told the flag was unrecognised.
+ */
+const SECRET_BEARING_FLAGS = new Set(["--api-key"]);
+/**
+ * What to say to somebody who has just put a credential in their shell history.
+ *
+ * One sentence about the harm and two ways to avoid it, stated once because
+ * both spellings — attached and separated — deserve the same answer. Neither
+ * repeats the value back.
+ */
+export const SECRET_ARGUMENT_ADVICE = 'A credential given as an argument is visible to every process on this machine and is written to your shell history — treat the one you just typed as exposed and replace it. Run the command with a bare --api-key and paste the secret when asked, or pipe it in: printf %s "$KEY" | greatwait login --api-key';
+export function parseArguments(argv, 
+/**
+ * The words that begin a command, so the rule below can tell a subcommand
+ * from a leaked secret.
+ *
+ * **Without it the rule refused `greatwait --api-key login`.** The parser is
+ * position-independent by design, so a bare `--api-key` before the command
+ * word is a legitimate line that used to work; refusing it says "this flag
+ * does not take a value" to somebody who never typed one. Passed in rather
+ * than imported, because `commands.ts` reads this module and the cycle would
+ * be the wrong way round.
+ */
+commandWords = new Set()) {
+    const command = [];
+    const options = {};
+    const booleans = new Set();
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index];
+        if (!token.startsWith("--")) {
+            command.push(token);
+            index += 1;
+            continue;
+        }
+        const equals = token.indexOf("=");
+        const name = equals === -1 ? token : token.slice(0, equals);
+        if (SECRET_BEARING_FLAGS.has(name)) {
+            if (equals !== -1) {
+                throw new CliError(`${name} does not take a value on the command line`, "usage", SECRET_ARGUMENT_ADVICE);
+            }
+            // **The next token is refused here, rather than left to a command.**
+            // Leaving it to become a positional argument was the first design, and a
+            // review round found what that cost: `login` refuses an unexpected
+            // argument by *naming* it, so `greatwait login --api-key sk_live_…`
+            // printed the credential back — on standard error, and inside the
+            // `--json` envelope on standard output, which is the stream a
+            // continuous-integration job captures. The flag exists so that a secret
+            // never reaches output, and its own refusal was the one place it did.
+            //
+            // Nothing is echoed. Somebody who has just typed their credential needs
+            // to be told so, not shown it again.
+            const following = argv[index + 1];
+            if (following !== undefined &&
+                !following.startsWith("--") &&
+                !commandWords.has(following)) {
+                throw new CliError(`${name} does not take a value on the command line`, "usage", SECRET_ARGUMENT_ADVICE);
+            }
+            booleans.add(name);
+            index += 1;
+            continue;
+        }
+        if (VALUED_OPTIONS.has(name)) {
+            if (equals !== -1) {
+                options[name] = token.slice(equals + 1);
+                index += 1;
+                continue;
+            }
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new CliError(`${name} needs a value`, "usage");
+            }
+            options[name] = value;
+            index += 2;
+            continue;
+        }
+        if (equals !== -1) {
+            throw new CliError(`${name} does not take a value`, "usage");
+        }
+        booleans.add(name);
+        index += 1;
+    }
+    return { booleans, command, options };
+}
+/**
+ * A duration written the way a person writes one: `30s`, `5m`, `2h`.
+ *
+ * Bare digits are refused rather than assumed to be seconds. "in 30" is a
+ * sentence with a missing word, and guessing at it is how somebody schedules
+ * something thirty milliseconds — or thirty hours — from now.
+ */
+export function parseDuration(value) {
+    const match = /^(?<amount>\d+)(?<unit>s|m|h|d)$/u.exec(value);
+    if (match?.groups === undefined) {
+        throw new CliError(`${value} is not a duration`, "usage", "Write it with a unit: 30s, 5m, 2h, 1d.");
+    }
+    const amount = Number(match.groups["amount"]);
+    const seconds = { d: 86_400, h: 3_600, m: 60, s: 1 }[match.groups["unit"]];
+    return amount * seconds;
+}

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+import { type CliRuntime } from "./runtime.js";
+/**
+ * One run of `greatwait`, from argv to an exit code.
+ *
+ * **A function of a runtime rather than a process.** Every case criterion 7
+ * names — a browser that will not open, a callback that never arrives, a
+ * deadline passing, Ctrl-C halfway through a wait, a configuration path on
+ * another platform — is a fact about the surroundings, and this shape is what
+ * lets a test construct one. `main.ts` is the only file that knows there is a
+ * process at all.
+ */
+declare const USAGE = "greatwait \u2014 the Greatwait command line\n\n  greatwait login [--api-url <origin>] [--api-key] [--no-browser]\n  greatwait logout [--api-url <origin>]\n  greatwait whoami\n  greatwait doctor\n  greatwait context [list | use <origin>]\n  greatwait journey\n\n  greatwait destinations create --url <https receiver>\n  greatwait destinations disable <destination>\n  greatwait schedules create --endpoint <destination> (--in 30s | --at <instant>) [--data <json>]\n  greatwait schedules read <schedule>\n  greatwait occurrences wait <schedule> <occurrence>\n  greatwait attempts list <schedule> <occurrence>\n\n  --json    machine-readable output, versioned\n  --help    this text\n\nRun `greatwait journey` for the published first-value sequence.";
+export declare function run(runtime: CliRuntime): Promise<number>;
+export { USAGE };

package/dist/cli.js

@@ -0,0 +1,191 @@
+import { GreatwaitClientError } from "@greatwait/api-client";
+import { parseArguments } from "./args.js";
+import { COMMANDS } from "./commands.js";
+import { UnsafeConfigError } from "./config.js";
+import { EXIT_CLASSES, classifyStatus } from "./exit.js";
+import { renderFailure, renderResult } from "./output.js";
+import { CliError, InterruptedError } from "./runtime.js";
+/**
+ * One run of `greatwait`, from argv to an exit code.
+ *
+ * **A function of a runtime rather than a process.** Every case criterion 7
+ * names — a browser that will not open, a callback that never arrives, a
+ * deadline passing, Ctrl-C halfway through a wait, a configuration path on
+ * another platform — is a fact about the surroundings, and this shape is what
+ * lets a test construct one. `main.ts` is the only file that knows there is a
+ * process at all.
+ */
+const USAGE = `greatwait — the Greatwait command line
+
+  greatwait login [--api-url <origin>] [--api-key] [--no-browser]
+  greatwait logout [--api-url <origin>]
+  greatwait whoami
+  greatwait doctor
+  greatwait context [list | use <origin>]
+  greatwait journey
+
+  greatwait destinations create --url <https receiver>
+  greatwait destinations disable <destination>
+  greatwait schedules create --endpoint <destination> (--in 30s | --at <instant>) [--data <json>]
+  greatwait schedules read <schedule>
+  greatwait occurrences wait <schedule> <occurrence>
+  greatwait attempts list <schedule> <occurrence>
+
+  --json    machine-readable output, versioned
+  --help    this text
+
+Run \`greatwait journey\` for the published first-value sequence.`;
+/**
+ * Which command a set of leading words names.
+ *
+ * Two words before one, so `schedules read` is found before a hypothetical
+ * `schedules`. Written as a lookup rather than a switch because the same table
+ * is what `--help` and the tests enumerate.
+ */
+/**
+ * Every word that can begin a command.
+ *
+ * Handed to the parser so it can tell `greatwait --api-key login` — a
+ * legitimate, position-independent line — from a credential typed where a
+ * value would go. Derived from the table rather than listed, so a command
+ * added later needs no second edit.
+ */
+const COMMAND_WORDS = new Set(Object.keys(COMMANDS).map((key) => key.split(" ")[0]));
+function select(words) {
+    for (const length of [2, 1]) {
+        const key = words.slice(0, length).join(" ");
+        if (Object.hasOwn(COMMANDS, key)) {
+            return { key, rest: words.slice(length) };
+        }
+    }
+    return undefined;
+}
+function problemOf(error) {
+    return error instanceof GreatwaitClientError ? error.problem : undefined;
+}
+/**
+ * The class and the sentence for anything that stopped a command.
+ *
+ * **The service's own refusal is preferred to this command's paraphrase.** A
+ * problem document carries a title and a detail written for the person reading
+ * them, and a client that replaced those with its own wording would be
+ * maintaining a second copy of every refusal the service can produce.
+ */
+function classify(error) {
+    if (error instanceof InterruptedError) {
+        return {
+            exit: "interrupted",
+            human: "Stopped. Nothing was cancelled at the service — anything already created is still there.",
+            nextMove: undefined,
+            problem: undefined,
+        };
+    }
+    if (error instanceof CliError) {
+        return {
+            exit: error.exit,
+            human: error.message,
+            nextMove: error.nextMove,
+            problem: undefined,
+        };
+    }
+    if (error instanceof UnsafeConfigError) {
+        return {
+            exit: "internal",
+            human: error.message,
+            nextMove: undefined,
+            problem: undefined,
+        };
+    }
+    if (error instanceof GreatwaitClientError) {
+        const problem = problemOf(error);
+        return {
+            exit: classifyStatus(error.status, problem?.code),
+            human: problem === undefined
+                ? `The service answered ${String(error.status)}.`
+                : `${problem.title} (${problem.code})`,
+            nextMove: problem?.code === "authentication_required"
+                ? "Sign in: greatwait login"
+                : problem?.code === "scope_missing"
+                    ? "This credential does not carry the permission this call needs. Create one that does, rather than widening this one."
+                    : error.retryable
+                        ? "The identical request is safe to repeat."
+                        : undefined,
+            problem,
+        };
+    }
+    // **`internal`, and the message is kept.** Anything reaching here is a defect
+    // in this command rather than a refusal the service published, and swallowing
+    // the message would leave a person with an exit code and nothing to report.
+    return {
+        exit: "internal",
+        human: error instanceof Error ? error.message : String(error),
+        nextMove: undefined,
+        problem: undefined,
+    };
+}
+export async function run(runtime) {
+    let json = false;
+    let command = "greatwait";
+    try {
+        const args = parseArguments(runtime.argv, COMMAND_WORDS);
+        json = args.booleans.has("--json");
+        if (args.booleans.has("--help") || args.command.length === 0) {
+            runtime.stdout(`${USAGE}\n`);
+            return EXIT_CLASSES.ok;
+        }
+        const selected = select(args.command);
+        if (selected === undefined) {
+            throw new CliError(`unknown command ${args.command.join(" ")}`, "usage", "Run greatwait --help for the list.");
+        }
+        command = selected.key;
+        const result = await COMMANDS[selected.key](runtime, { ...args, command: selected.rest });
+        // **A command that answered prints on standard output, whatever the news
+        // is.** `doctor` reporting a failed check is an answer with a shape, and
+        // routing it to `stderr` — or through the error envelope — would hand a
+        // script a rendered table where its data should be.
+        (result.exit === undefined || json ? runtime.stdout : runtime.stderr)(renderResult(command, result, json));
+        // **The sentence for a person reaches standard error under `--json`,
+        // whichever way the answer went.** It used to do so only for a failing
+        // one, so a success with something worth saying — a grant the service
+        // could not describe, an environment that delivers for real — said it
+        // nowhere at all. The document is the machine's and this is the person's,
+        // and neither has to filter the other.
+        if (json && result.nextMove !== undefined) {
+            runtime.stderr(`${result.nextMove}\n`);
+        }
+        return EXIT_CLASSES[result.exit ?? "ok"];
+    }
+    catch (error) {
+        const classified = classify(error);
+        // **A `--json` failure goes to standard output, and a plain one to standard
+        // error.** Found by the staging browser suite, which could not parse a
+        // refusal because Node had written a deprecation warning to the same stream
+        // first — a machine consumer reading `stderr` is reading a channel it does
+        // not own and cannot bound. With `--json` the document is the command's
+        // answer whether or not it worked, so it belongs where the answer goes;
+        // the exit class is what says which it was. Without `--json` the ordinary
+        // shell convention holds and diagnostics stay off `stdout`.
+        (json ? runtime.stdout : runtime.stderr)(renderFailure(command, {
+            exit: classified.exit,
+            human: classified.human,
+            ...(classified.nextMove === undefined
+                ? {}
+                : { nextMove: classified.nextMove }),
+            ...(classified.problem === undefined
+                ? {}
+                : { problem: classified.problem }),
+        }, json));
+        // **The next move still reaches a person under `--json`, on the other
+        // stream.** It is a sentence written for a reader and it changes whenever
+        // it reads badly, so putting it in the document would make every rewording
+        // a change to a versioned contract — the thing `--json` exists not to be.
+        // Dropping it instead left somebody scripting with no idea what to do,
+        // which is how this was found. The machine reads `stdout`, the person reads
+        // `stderr`, and neither has to filter the other.
+        if (json && classified.nextMove !== undefined) {
+            runtime.stderr(`${classified.nextMove}\n`);
+        }
+        return EXIT_CLASSES[classified.exit];
+    }
+}
+export { USAGE };

package/dist/commands.d.ts

@@ -0,0 +1,14 @@
+import { type ParsedArguments } from "./args.js";
+import { type StoredCredential } from "./config.js";
+import { type CommandResult } from "./output.js";
+import { type CliRuntime } from "./runtime.js";
+type Command = (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandResult>;
+interface CredentialContextView {
+    readonly environmentKind: string;
+    readonly principal: string;
+    readonly project: string;
+    readonly scopes: readonly string[];
+}
+/** Every command, keyed by the words that select it. */
+export declare const COMMANDS: Readonly<Record<string, Command>>;
+export type { Command, CredentialContextView, StoredCredential };