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

package/dist/exit.d.ts

@@ -33,6 +33,18 @@ export declare const EXIT_CLASSES: {
     readonly retryable: 6;
     /** A deadline this command was given passed before the answer arrived. */
     readonly timeout: 7;
+    /**
+     * The service is not configured to do this, and repeating will not change
+     * that.
+     *
+     * **A separate number from `retryable` because a script must not loop on
+     * it.** Both are 5xx and both mean "the service, not you" — but one clears
+     * on its own and the other waits on somebody changing the deployment. Until
+     * FXO-2497 these shared class 6, so a client told "the identical request is
+     * safe to repeat" would retry a condition that is permanent, and a customer
+     * was offered a "Try again" control that could never work.
+     */
+    readonly unconfigured: 8;
     /**
      * Interrupted.
      *
@@ -44,6 +56,15 @@ export declare const EXIT_CLASSES: {
     readonly interrupted: 130;
 };
 export type ExitClass = keyof typeof EXIT_CLASSES;
+/**
+ * What each class means, in the words the reference publishes.
+ *
+ * **Beside the numbers rather than in the page**, because a table of exit codes
+ * written out in documentation is a table that describes last month's classes.
+ * The reference renders this, so adding a class without describing it does not
+ * compile.
+ */
+export declare const EXIT_CLASS_MEANINGS: Readonly<Record<ExitClass, string>>;
 /**
  * The class an HTTP status falls in.
  *
@@ -51,8 +72,9 @@ export type ExitClass = keyof typeof EXIT_CLASSES;
  * A refusal from an edge proxy carries no problem document at all — there is no
  * code to read — and a client that branched on the code first would classify
  * every one of those as internal. The code refines the answer where it
- * disagrees with the status, which is exactly once: `scope_missing` is a `403`
- * and belongs in `authorization`, and everything else in the 4xx range that is
+ * disagrees with the status, which is exactly twice: `scope_missing` is a `403`
+ * and belongs in `authorization`, `capability_not_configured` is a `503` that
+ * must not be called retryable, and everything else in the 4xx range that is
  * not authentication is the caller's request to fix.
  */
 export declare function classifyStatus(status: number, problemCode?: string): ExitClass;

package/dist/exit.js

@@ -33,6 +33,18 @@ export const EXIT_CLASSES = {
     retryable: 6,
     /** A deadline this command was given passed before the answer arrived. */
     timeout: 7,
+    /**
+     * The service is not configured to do this, and repeating will not change
+     * that.
+     *
+     * **A separate number from `retryable` because a script must not loop on
+     * it.** Both are 5xx and both mean "the service, not you" — but one clears
+     * on its own and the other waits on somebody changing the deployment. Until
+     * FXO-2497 these shared class 6, so a client told "the identical request is
+     * safe to repeat" would retry a condition that is permanent, and a customer
+     * was offered a "Try again" control that could never work.
+     */
+    unconfigured: 8,
     /**
      * Interrupted.
      *
@@ -43,6 +55,26 @@ export const EXIT_CLASSES = {
      */
     interrupted: 130,
 };
+/**
+ * What each class means, in the words the reference publishes.
+ *
+ * **Beside the numbers rather than in the page**, because a table of exit codes
+ * written out in documentation is a table that describes last month's classes.
+ * The reference renders this, so adding a class without describing it does not
+ * compile.
+ */
+export const EXIT_CLASS_MEANINGS = {
+    authentication: "No usable credential. Sign in.",
+    authorization: "A credential that authenticated and may not do this.",
+    internal: "A defect in this program.",
+    interrupted: "Stopped — Ctrl-C, or a confirmation declined.",
+    ok: "It did what it was asked.",
+    retryable: "The service could not answer now. The identical request may work later.",
+    timeout: "A deadline this command was given passed before the answer arrived.",
+    unconfigured: "The service is not configured to do this. Repeating will not help; it needs somebody to change the service.",
+    usage: "The command line was wrong.",
+    validation: "The request was refused on its merits: invalid, missing, or conflicting.",
+};
 /**
  * The class an HTTP status falls in.
  *
@@ -50,13 +82,23 @@ export const EXIT_CLASSES = {
  * A refusal from an edge proxy carries no problem document at all — there is no
  * code to read — and a client that branched on the code first would classify
  * every one of those as internal. The code refines the answer where it
- * disagrees with the status, which is exactly once: `scope_missing` is a `403`
- * and belongs in `authorization`, and everything else in the 4xx range that is
+ * disagrees with the status, which is exactly twice: `scope_missing` is a `403`
+ * and belongs in `authorization`, `capability_not_configured` is a `503` that
+ * must not be called retryable, and everything else in the 4xx range that is
  * not authentication is the caller's request to fix.
  */
 export function classifyStatus(status, problemCode) {
     if (problemCode === "scope_missing")
         return "authorization";
+    // Without this the status alone decides, and a 503 falls through to
+    // `retryable` below — which is the defect: a permanent configuration refusal
+    // telling a script that repeating it is safe.
+    if (problemCode === "capability_not_configured")
+        return "unconfigured";
+    // The SDK uses zero when no HTTP answer survives its transport retries.
+    // This is a failed exchange, not a successful command.
+    if (status === 0)
+        return "retryable";
     if (status === 401)
         return "authentication";
     if (status === 403)

package/dist/gw.d.ts

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

package/dist/gw.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { start } from "./start.js";
+/**
+ * The same command, under the short name.
+ *
+ * Everything it prints names `gw`, because the whole point of a two-letter
+ * command is not typing the long one — and a tool that answers `gw schedules
+ * read` with "Next: greatwait attempts list …" hands back the thing it was
+ * installed to avoid.
+ *
+ * `greatwait` stays the canonical name: it is what the published reference, the
+ * quickstarts and the first-value journey say, and what one name has to be for
+ * a written instruction to be followable by somebody who installed either.
+ */
+await start("gw");

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { run, USAGE } from "./cli.js";
+export { run, usage } from "./cli.js";
 export { COMMANDS } from "./commands.js";
 export { configDirectory, configLocations, createCredentialStore, originKey, UnsafeConfigError, type CredentialStore, type StoredCredential, } from "./config.js";
 export { EXIT_CLASSES, classifyStatus, type ExitClass } from "./exit.js";
@@ -6,4 +6,6 @@ export { nodeRuntime, openLoopback } from "./node-runtime.js";
 export { OUTPUT_VERSION, redactSecret, renderFailure, renderResult, } from "./output.js";
 export { parseArguments, parseDuration } from "./args.js";
 export { publishedWait, renderJourney, STEP_COMMANDS } from "./journey.js";
+export { CANONICAL_PROGRAM_NAME } from "./catalog.js";
+export { start } from "./start.js";
 export { CliError, InterruptedError, type CliRuntime, type LoopbackListener, } from "./runtime.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { run, USAGE } from "./cli.js";
+export { run, usage } from "./cli.js";
 export { COMMANDS } from "./commands.js";
 export { configDirectory, configLocations, createCredentialStore, originKey, UnsafeConfigError, } from "./config.js";
 export { EXIT_CLASSES, classifyStatus } from "./exit.js";
@@ -6,4 +6,6 @@ export { nodeRuntime, openLoopback } from "./node-runtime.js";
 export { OUTPUT_VERSION, redactSecret, renderFailure, renderResult, } from "./output.js";
 export { parseArguments, parseDuration } from "./args.js";
 export { publishedWait, renderJourney, STEP_COMMANDS } from "./journey.js";
+export { CANONICAL_PROGRAM_NAME } from "./catalog.js";
+export { start } from "./start.js";
 export { CliError, InterruptedError, } from "./runtime.js";

package/dist/journey.d.ts

@@ -23,8 +23,8 @@ export interface RenderedStep {
     readonly purpose: string;
     readonly title: string;
 }
-export declare function renderStep(step: JourneyStep): RenderedStep;
-export declare function renderJourney(): {
+export declare function renderStep(step: JourneyStep, programName?: string): RenderedStep;
+export declare function renderJourney(programName?: string): {
     readonly prerequisites: readonly {
         readonly action: string;
         readonly because: string;

package/dist/journey.js

@@ -1,4 +1,5 @@
 import { FIRST_VALUE_JOURNEY, journeyStepVariables, } from "@greatwait/contracts";
+import { CANONICAL_PROGRAM_NAME } from "./catalog.js";
 /**
  * The published first-value sequence, rendered for a terminal.
  *
@@ -25,9 +26,24 @@ export const STEP_COMMANDS = {
     "read-schedule": "greatwait schedules read <schedule>",
     "replay-one-shot": "greatwait schedules create --endpoint <destination> --in 30s --idempotency-key <the same key>",
 };
-export function renderStep(step) {
+/**
+ * A step's command, under the name this executable was invoked as.
+ *
+ * **`STEP_COMMANDS` stays canonical and this rewrites the first word.** That
+ * table is re-exported into `first-value-projection.ts`, which renders it into
+ * the website's journey, the curl page and the JavaScript page — surfaces with
+ * no invocation to speak of. So the published text says `greatwait` and the
+ * terminal says whichever of the two names is on the person's PATH.
+ */
+function stepCommand(key, programName) {
+    const command = STEP_COMMANDS[key];
+    return command === undefined
+        ? undefined
+        : command.replace(/^greatwait\b/u, programName);
+}
+export function renderStep(step, programName = CANONICAL_PROGRAM_NAME) {
     return {
-        command: STEP_COMMANDS[step.key],
+        command: stepCommand(step.key, programName),
         key: step.key,
         // What the step must be given, as the journey names it — the path
         // parameters an earlier step captured, and the references in its body and
@@ -38,14 +54,14 @@ export function renderStep(step) {
         title: step.title,
     };
 }
-export function renderJourney() {
+export function renderJourney(programName = CANONICAL_PROGRAM_NAME) {
     return {
         prerequisites: FIRST_VALUE_JOURNEY.prerequisites.map((prerequisite) => ({
             action: prerequisite.action,
             because: prerequisite.because,
             title: prerequisite.title,
         })),
-        steps: FIRST_VALUE_JOURNEY.steps.map(renderStep),
+        steps: FIRST_VALUE_JOURNEY.steps.map((step) => renderStep(step, programName)),
     };
 }
 /**

package/dist/main.js

@@ -1,24 +1,14 @@
 #!/usr/bin/env node
-import { run } from "./cli.js";
-import { nodeRuntime } from "./node-runtime.js";
+import { start } from "./start.js";
 /**
- * The installed executable.
+ * The installed executable, under the name the package is called.
  *
  * **The whole file is the part the repository's own test suite cannot reach**,
  * which is why criterion 7 asks for a regression against a `bin` that does
- * nothing: every case here drives `run` directly, so a package whose source is
+ * nothing: every case drives `run` directly, so a package whose source is
  * perfect and whose `bin` entry points at a file that does not exist passes all
  * of them. `scripts/verify-clean-install.ts` installs the packed tarball and
- * executes this path.
- *
- * `process.exitCode` rather than `process.exit`: the second truncates whatever
- * is still buffered on stdout, and this command's last act is to print.
+ * executes this path — and `gw.ts` beside it, because a second `bin` is a
+ * second thing that can be wired to nothing.
  */
-const controller = new AbortController();
-process.on("SIGINT", () => {
-    controller.abort();
-});
-process.on("SIGTERM", () => {
-    controller.abort();
-});
-process.exitCode = await run(nodeRuntime(controller.signal));
+await start("greatwait");

package/dist/node-runtime.d.ts

@@ -32,4 +32,18 @@ export declare function promptSecret(question: string, streams?: {
     readonly input: NodeJS.ReadStream;
     readonly output: NodeJS.WriteStream;
 }): Promise<string>;
-export declare function nodeRuntime(signal: AbortSignal): CliRuntime;
+/**
+ * Asks a question on the terminal and reads the answer back, echoed.
+ *
+ * **The question goes to standard error and the answer is read from standard
+ * input**, so a command whose result is being piped somewhere still asks a
+ * person who can see it. Ctrl-C at the prompt is an interruption rather than an
+ * empty answer, for the same reason it is at the secret prompt: a shell reports
+ * 130 for a process the person stopped, and treating it as "no" would be
+ * indistinguishable from a deliberate decline in a log.
+ */
+export declare function promptLine(question: string, streams?: {
+    readonly input: NodeJS.ReadStream;
+    readonly output: NodeJS.WriteStream;
+}): Promise<string>;
+export declare function nodeRuntime(signal: AbortSignal, programName: string): CliRuntime;

package/dist/node-runtime.js

@@ -49,7 +49,7 @@ export async function openLoopback() {
             return;
         }
         response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
-        response.end("Greatwait received the answer. You can close this tab.\n");
+        response.end("GreatWait received the answer. You can close this tab.\n");
         deliver?.(url.searchParams);
     });
     await new Promise((resolve, reject) => {
@@ -148,6 +148,34 @@ export async function promptSecret(question, streams = { input: process.stdin, o
         readline.close();
     }
 }
+/**
+ * Asks a question on the terminal and reads the answer back, echoed.
+ *
+ * **The question goes to standard error and the answer is read from standard
+ * input**, so a command whose result is being piped somewhere still asks a
+ * person who can see it. Ctrl-C at the prompt is an interruption rather than an
+ * empty answer, for the same reason it is at the secret prompt: a shell reports
+ * 130 for a process the person stopped, and treating it as "no" would be
+ * indistinguishable from a deliberate decline in a log.
+ */
+export async function promptLine(question, streams = { input: process.stdin, output: process.stderr }) {
+    const readline = createInterface({
+        input: streams.input,
+        output: streams.output,
+    });
+    try {
+        return await new Promise((resolve, reject) => {
+            readline.once("SIGINT", () => {
+                streams.output.write("\n");
+                reject(new InterruptedError());
+            });
+            readline.question(question, resolve);
+        });
+    }
+    finally {
+        readline.close();
+    }
+}
 async function readStdin() {
     if (process.stdin.isTTY)
         return "";
@@ -177,7 +205,7 @@ function sleep(milliseconds, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
-export function nodeRuntime(signal) {
+export function nodeRuntime(signal, programName) {
     return {
         argv: process.argv.slice(2),
         env: process.env,
@@ -188,6 +216,8 @@ export function nodeRuntime(signal) {
         now: () => Date.now(),
         openBrowser,
         platform: process.platform,
+        programName,
+        promptLine: (question) => promptLine(question),
         promptSecret: (question) => promptSecret(question),
         randomBytes: (length) => crypto.getRandomValues(new Uint8Array(length)),
         randomUuid: () => crypto.randomUUID(),

package/dist/oauth.d.ts

@@ -66,7 +66,7 @@ export declare function buildAuthorization(runtime: CliRuntime, server: Authoriz
  * else's state is not a code to exchange — it is a request this process did not
  * make — and reading the code first would exchange it anyway.
  */
-export declare function codeFrom(returned: URLSearchParams, state: string): string;
+export declare function codeFrom(returned: URLSearchParams, state: string, programName: string): string;
 export declare function exchangeCode(runtime: CliRuntime, server: AuthorizationServer, options: {
     readonly clientId: string;
     readonly code: string;

package/dist/oauth.js

@@ -17,9 +17,9 @@ async function readJson(runtime, url, init) {
     }
     return { body, status: response.status };
 }
-function requireString(value, field, source) {
+function requireString(value, field, source, programName) {
     if (typeof value !== "string" || value === "") {
-        throw new CliError(`${source} does not name a ${field}`, "internal", "This origin publishes authorization metadata this command cannot use. Sign in with an API key instead: greatwait login --api-key");
+        throw new CliError(`${source} does not name a ${field}`, "internal", `This origin publishes authorization metadata this command cannot use. Sign in with an API key instead: ${programName} login --api-key`);
     }
     return value;
 }
@@ -35,13 +35,13 @@ export async function discover(runtime, origin) {
     const resourceUrl = `${origin}/.well-known/oauth-protected-resource`;
     const resource = await readJson(runtime, resourceUrl);
     if (resource.status !== 200) {
-        throw new CliError(`${origin} does not publish protected-resource metadata (${String(resource.status)})`, "validation", "Check the origin. A Greatwait API answers GET /__greatwait/version with no credential; try greatwait doctor --api-url <origin>.");
+        throw new CliError(`${origin} does not publish protected-resource metadata (${String(resource.status)})`, "validation", `Check the origin. A GreatWait API answers GET /__greatwait/version with no credential; try ${runtime.programName} doctor --api-url <origin>.`);
     }
     const resourceBody = resource.body;
     const servers = Array.isArray(resourceBody.authorization_servers)
         ? resourceBody.authorization_servers
         : [];
-    const issuer = requireString(servers[0], "authorization server", resourceUrl);
+    const issuer = requireString(servers[0], "authorization server", resourceUrl, runtime.programName);
     const metadataUrl = `${issuer}/.well-known/oauth-authorization-server`;
     const metadata = await readJson(runtime, metadataUrl);
     if (metadata.status !== 200) {
@@ -50,7 +50,7 @@ export async function discover(runtime, origin) {
     const body = metadata.body;
     const scopes = body["scopes_supported"];
     return {
-        authorizationEndpoint: requireString(body["authorization_endpoint"], "authorization endpoint", metadataUrl),
+        authorizationEndpoint: requireString(body["authorization_endpoint"], "authorization endpoint", metadataUrl, runtime.programName),
         registrationEndpoint: typeof body["registration_endpoint"] === "string"
             ? body["registration_endpoint"]
             : undefined,
@@ -59,23 +59,23 @@ export async function discover(runtime, origin) {
         // minted for one audience must not be accepted by another, and a client
         // that names an audience it invented is asserting something it did not
         // check.
-        resource: requireString(resourceBody.resource, "resource", resourceUrl),
+        resource: requireString(resourceBody.resource, "resource", resourceUrl, runtime.programName),
         revocationEndpoint: typeof body["revocation_endpoint"] === "string"
             ? body["revocation_endpoint"]
             : undefined,
         scopesSupported: Array.isArray(scopes)
             ? scopes.filter((scope) => typeof scope === "string")
             : [],
-        tokenEndpoint: requireString(body["token_endpoint"], "token endpoint", metadataUrl),
+        tokenEndpoint: requireString(body["token_endpoint"], "token endpoint", metadataUrl, runtime.programName),
     };
 }
 export async function registerClient(runtime, server, options) {
     if (server.registrationEndpoint === undefined) {
-        throw new CliError("this authorization server does not offer dynamic client registration", "validation", "Sign in with an API key instead: greatwait login --api-key");
+        throw new CliError("this authorization server does not offer dynamic client registration", "validation", `Sign in with an API key instead: ${runtime.programName} login --api-key`);
     }
     const registered = await readJson(runtime, server.registrationEndpoint, {
         body: JSON.stringify({
-            client_name: "Greatwait CLI",
+            client_name: "GreatWait CLI",
             client_uri: "https://greatwait.dev",
             grant_types: ["authorization_code", "refresh_token"],
             redirect_uris: [options.redirectUri],
@@ -92,7 +92,7 @@ export async function registerClient(runtime, server, options) {
         throw new CliError(`dynamic client registration was refused (${String(registered.status)}: ${registered.body?.error ??
             "no reason given"})`, "validation");
     }
-    return requireString(registered.body.client_id, "client_id", server.registrationEndpoint);
+    return requireString(registered.body.client_id, "client_id", server.registrationEndpoint, runtime.programName);
 }
 export async function buildAuthorization(runtime, server, options) {
     const state = base64Url(runtime.randomBytes(24));
@@ -116,16 +116,16 @@ export async function buildAuthorization(runtime, server, options) {
  * else's state is not a code to exchange — it is a request this process did not
  * make — and reading the code first would exchange it anyway.
  */
-export function codeFrom(returned, state) {
+export function codeFrom(returned, state, programName) {
     const error = returned.get("error");
     if (error !== null) {
         throw new CliError(`authorization was refused (${error})`, "authentication", error === "access_denied"
-            ? "Nothing was granted. Run greatwait login again and approve the request, or use an API key."
+            ? `Nothing was granted. Run ${programName} login again and approve the request, or use an API key.`
             : undefined);
     }
     const returnedState = returned.get("state");
     if (returnedState !== state) {
-        throw new CliError(`the redirect carried ${returnedState === null ? "no state" : "a state this run did not issue"}`, "authentication", "A browser tab left open from an earlier sign-in is the usual cause. Close it and run greatwait login again.");
+        throw new CliError(`the redirect carried ${returnedState === null ? "no state" : "a state this run did not issue"}`, "authentication", `A browser tab left open from an earlier sign-in is the usual cause. Close it and run ${programName} login again.`);
     }
     const code = returned.get("code");
     if (code === null) {
@@ -142,14 +142,14 @@ async function exchange(runtime, server, form) {
     if (response.status !== 200) {
         const error = response.body?.error;
         throw new CliError(`the authorization server refused the token request (${error ?? String(response.status)})`, "authentication", error === "invalid_grant"
-            ? "The grant is no longer usable — it expired, was revoked, or was already spent. Run greatwait login again."
+            ? `The grant is no longer usable — it expired, was revoked, or was already spent. Run ${runtime.programName} login again.`
             : undefined);
     }
     const body = response.body;
     return {
-        accessToken: requireString(body["access_token"], "access_token", server.tokenEndpoint),
+        accessToken: requireString(body["access_token"], "access_token", server.tokenEndpoint, runtime.programName),
         expiresInSeconds: typeof body["expires_in"] === "number" ? body["expires_in"] : 0,
-        refreshToken: requireString(body["refresh_token"], "refresh_token", server.tokenEndpoint),
+        refreshToken: requireString(body["refresh_token"], "refresh_token", server.tokenEndpoint, runtime.programName),
         scope: typeof body["scope"] === "string" ? body["scope"] : "",
     };
 }

package/dist/operate.d.ts

@@ -0,0 +1,39 @@
+import { type ParsedArguments } from "./args.js";
+import { type CommandResult } from "./output.js";
+import { type CliRuntime } from "./runtime.js";
+/**
+ * Operating and diagnosing, after first value has already happened.
+ *
+ * W10-01 built the shortest path from an empty machine to an observed callback.
+ * This is the rest of the lifecycle: listing what exists, changing it, watching
+ * it, and recovering from it. The split is by *when somebody runs it* rather
+ * than by resource, which is why `schedules create` is still next to `login`
+ * and `schedules cancel` is here.
+ *
+ * Every command in this file follows the same three rules. It reads before it
+ * changes, so the confirmation shows the object as it is now rather than
+ * repeating the arguments back. It sends the conditional header when one was
+ * given, so a change to something somebody else has moved is refused rather
+ * than applied. And it renders identifiers in a column somebody can select,
+ * because the next command needs them.
+ */
+type Command = (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandResult>;
+/**
+ * A schedule definition from the command line.
+ *
+ * **One recurrence, named explicitly.** The four spellings are the four the
+ * contract publishes, and giving none or giving two is refused here rather than
+ * sent: "you gave --in and --cron" is a sentence about the line somebody typed,
+ * and `invalid_request` a round trip later is not.
+ *
+ * `--time-zone` is what keeps daylight saving honest. A cron expression without
+ * one fires on a fixed offset, so "every weekday at 09:00" drifts an hour twice
+ * a year; with one, the service moves the instant and the local time stays put.
+ * The command line does not choose a default zone, because guessing the
+ * machine's would make the same expression mean different things on a laptop
+ * and on a build runner.
+ */
+declare function scheduleRequest(runtime: CliRuntime, args: ParsedArguments, usage: string): Promise<Readonly<Record<string, unknown>>>;
+/** The operate-and-diagnose commands, keyed by the words that select them. */
+export declare const OPERATE_COMMANDS: Readonly<Record<string, Command>>;
+export { scheduleRequest, type Command };