@greatwait/cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/cli.d.ts

@@ -9,6 +9,15 @@ import { type CliRuntime } from "./runtime.js";
  * 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.";
+/**
+ * The overview, rendered from the catalog rather than kept beside it.
+ *
+ * **It was a string literal, and by the end of this story it would have been
+ * wrong.** Thirty-odd commands maintained in a template beside thirty-odd
+ * declarations is a list that drifts on the first rename, and the drift is
+ * invisible: nothing executes a usage string. Generating it means a command
+ * that exists appears here, and one that does not, cannot.
+ */
+declare function usage(programName: string): string;
 export declare function run(runtime: CliRuntime): Promise<number>;
-export { USAGE };
+export { usage };

package/dist/cli.js

@@ -1,9 +1,11 @@
 import { GreatwaitClientError } from "@greatwait/api-client";
 import { parseArguments } from "./args.js";
+import { COMMAND_CATALOG, commandHelp, overview } from "./catalog.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 { remediationFor } from "./remediation.js";
 import { CliError, InterruptedError } from "./runtime.js";
 /**
  * One run of `greatwait`, from argv to an exit code.
@@ -15,26 +17,25 @@ import { CliError, InterruptedError } from "./runtime.js";
  * 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
+/**
+ * The overview, rendered from the catalog rather than kept beside it.
+ *
+ * **It was a string literal, and by the end of this story it would have been
+ * wrong.** Thirty-odd commands maintained in a template beside thirty-odd
+ * declarations is a list that drifts on the first rename, and the drift is
+ * invisible: nothing executes a usage string. Generating it means a command
+ * that exists appears here, and one that does not, cannot.
+ */
+function usage(programName) {
+    return `${programName} — the GreatWait command line
 
-  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>
+${overview()}
 
   --json    machine-readable output, versioned
-  --help    this text
+  --help    this text, or the help for a command that precedes it
 
-Run \`greatwait journey\` for the published first-value sequence.`;
+Run \`${programName} journey\` for the published first-value sequence.`;
+}
 /**
  * Which command a set of leading words names.
  *
@@ -71,7 +72,7 @@ function problemOf(error) {
  * 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) {
+function classify(error, programName) {
     if (error instanceof InterruptedError) {
         return {
             exit: "interrupted",
@@ -101,15 +102,17 @@ function classify(error) {
         return {
             exit: classifyStatus(error.status, problem?.code),
             human: problem === undefined
-                ? `The service answered ${String(error.status)}.`
+                ? error.status === 0
+                    ? "The service could not be reached."
+                    : `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,
+            // **Every published code, not the two that were spelled out here.** This
+            // was a two-branch conditional naming `authentication_required` and
+            // `scope_missing`, so a `credential_revoked` — the same 401, and the one
+            // that means sign in again — arrived with the right exit number and no
+            // idea what to do about it. The record it now reads is exhaustive by
+            // type, so the next code the contract publishes cannot arrive silent.
+            nextMove: remediationFor(problem, error.retryable, programName),
             problem,
         };
     }
@@ -125,17 +128,27 @@ function classify(error) {
 }
 export async function run(runtime) {
     let json = false;
-    let command = "greatwait";
+    let command = runtime.programName;
     try {
-        const args = parseArguments(runtime.argv, COMMAND_WORDS);
+        const args = parseArguments(runtime.argv, COMMAND_WORDS, runtime.programName);
         json = args.booleans.has("--json");
+        const selected = select(args.command);
         if (args.booleans.has("--help") || args.command.length === 0) {
-            runtime.stdout(`${USAGE}\n`);
+            // **The help for the command that was named, where one was.** `greatwait
+            // schedules replace --help` printing the whole overview is the answer to
+            // a question nobody asked: somebody who has typed two words wants to know
+            // what those two words take, and the alternative is reading a thirty-line
+            // list to find the same line they started from.
+            const declaration = selected === undefined
+                ? undefined
+                : COMMAND_CATALOG.find((candidate) => candidate.words === selected.key);
+            runtime.stdout(`${declaration === undefined
+                ? usage(runtime.programName)
+                : commandHelp(declaration, runtime.programName)}\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.");
+            throw new CliError(`unknown command ${args.command.join(" ")}`, "usage", `Run ${runtime.programName} --help for the list.`);
         }
         command = selected.key;
         const result = await COMMANDS[selected.key](runtime, { ...args, command: selected.rest });
@@ -156,7 +169,7 @@ export async function run(runtime) {
         return EXIT_CLASSES[result.exit ?? "ok"];
     }
     catch (error) {
-        const classified = classify(error);
+        const classified = classify(error, runtime.programName);
         // **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
@@ -188,4 +201,4 @@ export async function run(runtime) {
         return EXIT_CLASSES[classified.exit];
     }
 }
-export { USAGE };
+export { usage };

package/dist/commands.d.ts

@@ -2,6 +2,16 @@ import { type ParsedArguments } from "./args.js";
 import { type StoredCredential } from "./config.js";
 import { type CommandResult } from "./output.js";
 import { type CliRuntime } from "./runtime.js";
+/**
+ * The commands, each bounded and each useful on its own.
+ *
+ * **There is no `greatwait demo`.** The project specification excludes one by
+ * name, and the reason is that a single command whose success proves everything
+ * teaches nothing: somebody who ran it has watched a callback arrive and still
+ * cannot make a second one. Every command here is a step somebody would take
+ * again on their own work, and together they are the published first-value
+ * journey — which `greatwait journey` renders rather than restates.
+ */
 type Command = (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandResult>;
 interface CredentialContextView {
     readonly environmentKind: string;
@@ -9,6 +19,28 @@ interface CredentialContextView {
     readonly project: string;
     readonly scopes: readonly string[];
 }
-/** Every command, keyed by the words that select it. */
+/**
+ * Every implementation, keyed by the words that select it.
+ *
+ * Not the dispatch table: that is built from the catalog below, so a command
+ * cannot be documented without existing and cannot exist without being
+ * documented. This half is the functions, and `packages/cli/src/catalog.ts` is
+ * what says they are the right set.
+ */
+declare const IMPLEMENTATIONS: Readonly<Record<string, Command>>;
+/**
+ * The dispatch table, assembled from the catalog.
+ *
+ * **A declaration with no function raises here, at import.** The alternative
+ * was a test that compared two lists, which is a check the published reference
+ * page can still contradict: the page is generated from the catalog, so a
+ * command documented and never implemented would ship as a promise the
+ * executable does not keep. Raising means the binary does not start.
+ *
+ * The other direction is a test rather than a raise — an implementation nobody
+ * declared is unreachable rather than dangerous, and `commands.test.ts` names
+ * it.
+ */
 export declare const COMMANDS: Readonly<Record<string, Command>>;
+export { IMPLEMENTATIONS };
 export type { Command, CredentialContextView, StoredCredential };