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

package/dist/remediation.d.ts

@@ -0,0 +1,35 @@
+import { isRetryable, type Problem, type ProblemCode } from "@greatwait/contracts";
+/**
+ * What to do about each refusal the service publishes.
+ *
+ * **One entry per public problem code, and the type makes it exhaustive.** A
+ * code added to the contract stops this file compiling until somebody says what
+ * a person should do about it, which is the only way a promise like "every
+ * problem code maps to a remediation" stays true past the week it was written.
+ *
+ * These are sentences for a person and they are deliberately *not* in the
+ * `--json` document: a machine branches on the code, which is published and
+ * stable, and a sentence rewritten because it read badly must not be a change
+ * to a versioned contract.
+ *
+ * The advice names a command wherever there is one to run. "Check your
+ * permissions" is not advice; `greatwait credentials list` is.
+ */
+declare function remediationTable(programName: string): Readonly<Record<ProblemCode, string>>;
+/**
+ * The next move for a refusal, or nothing when there is nothing useful to say.
+ *
+ * A problem the client could not parse — an edge proxy's `503` carries no
+ * document at all — still gets the retryable sentence, because the status alone
+ * is enough to say whether repeating is safe.
+ */
+export declare function remediationFor(problem: Problem | undefined, retryable: boolean, programName: string): string | undefined;
+/**
+ * The table under the canonical name, for the cases that read its sentences.
+ *
+ * A case asserting what the advice *says* wants one spelling; a case asserting
+ * that it follows the invoked name passes its own.
+ */
+export declare const REMEDIATION: Readonly<Record<"invalid_request" | "not_found" | "state_conflict" | "version_conflict" | "authentication_required" | "billing_not_ready" | "capability_not_configured" | "credential_expired" | "credential_revoked" | "idempotency_key_reused" | "payload_too_large" | "plan_limit_reached" | "project_archived" | "rate_limited" | "revision_conflict" | "scope_missing" | "service_unavailable" | "test_to_live_escalation", string>>;
+/** Exposed so a case can assert the records cover the published vocabularies. */
+export { isRetryable, remediationTable };

package/dist/remediation.js

@@ -0,0 +1,81 @@
+import { isRetryable, } from "@greatwait/contracts";
+import { CANONICAL_PROGRAM_NAME } from "./catalog.js";
+/**
+ * What to do about each refusal the service publishes.
+ *
+ * **One entry per public problem code, and the type makes it exhaustive.** A
+ * code added to the contract stops this file compiling until somebody says what
+ * a person should do about it, which is the only way a promise like "every
+ * problem code maps to a remediation" stays true past the week it was written.
+ *
+ * These are sentences for a person and they are deliberately *not* in the
+ * `--json` document: a machine branches on the code, which is published and
+ * stable, and a sentence rewritten because it read badly must not be a change
+ * to a versioned contract.
+ *
+ * The advice names a command wherever there is one to run. "Check your
+ * permissions" is not advice; `greatwait credentials list` is.
+ */
+function remediationTable(programName) {
+    return {
+        authentication_required: `Sign in: ${programName} login`,
+        // Nothing to fix and nothing to do but wait a moment — so the advice says
+        // that, rather than sending somebody to look for a fault that is not there.
+        billing_not_ready: "Billing for this organization is still being set up. It finishes on its own within a minute; run the command again then. Nothing has been charged and no schedule is affected.",
+        // **Not "try again", because trying again is exactly what does not work.**
+        // The distinction from `service_unavailable` below is the whole of
+        // FXO-2497's second limb: both are 503, and only one of them clears by
+        // itself.
+        capability_not_configured: "This service is not configured for that. Repeating the command will not change it — somebody with access to the deployment has to turn the capability on. The detail above names which one.",
+        credential_expired: `This credential has passed its expiry. Sign in again — ${programName} login — or rotate the one your automation presents: ${programName} credentials rotate <credential>`,
+        credential_revoked: `This credential has been revoked and will not work again. Sign in again: ${programName} login`,
+        idempotency_key_reused: "This key was used for a different request. Use a new --idempotency-key, or repeat the original request exactly to get the original answer back.",
+        invalid_request: "The service refused the request itself. The detail above names the field.",
+        not_found: `Nothing here answers to that identifier — check the identifier, and check ${programName} whoami is the project and environment you meant.`,
+        payload_too_large: "The payload is over the published cap. Send a reference to the data rather than the data.",
+        // **Which ceiling is in the detail, and not every ceiling is occurrences.**
+        // This named `greatwait usage` alone, which reports terminal occurrences by
+        // day — so for the two ceilings that send no detail at all, the endpoint
+        // count and the test-sink count, the only guidance a person got pointed at a
+        // report that cannot show what is full.
+        plan_limit_reached: `A platform ceiling stopped this. Which one is in the detail above where the service sends one: ${programName} usage counts terminal occurrences, ${programName} destinations list and ${programName} sinks list count the objects.`,
+        project_archived: "This project is archived. Restore it from Settings > General before acting on its resources.",
+        rate_limited: "Too many requests for now. The identical request is safe to repeat after the wait the service asked for.",
+        revision_conflict: "The billing budget changed since the revision you read. Read billing again and retry with the current --expected-revision.",
+        scope_missing: "This credential does not carry the permission this call needs. Create one that does, rather than widening this one.",
+        service_unavailable: "The service could not answer. The identical request is safe to repeat.",
+        // **No command name, because this refusal is not about one resource.** It
+        // named `greatwait schedules read`, and the same code is raised for a
+        // disabled destination and for a test sink an endpoint already has — where
+        // that sentence sends somebody to the wrong object.
+        //
+        // It does not point at the detail either, which the first correction did:
+        // two of the raise sites — update and rotate on a *disabled*
+        // endpoint — send a title and no detail at all, so "the detail above names
+        // the state" would have described a line that was never printed.
+        state_conflict: "The object is in a state that does not allow this. Read it back and act on the state it is in.",
+        test_to_live_escalation: "This credential acts in the test environment and the request named the live one. Use a live credential to act in live.",
+        version_conflict: "Somebody else changed this since the version you read. Read it again, take the new ETag, and pass it as --if-match.",
+    };
+}
+/**
+ * The next move for a refusal, or nothing when there is nothing useful to say.
+ *
+ * A problem the client could not parse — an edge proxy's `503` carries no
+ * document at all — still gets the retryable sentence, because the status alone
+ * is enough to say whether repeating is safe.
+ */
+export function remediationFor(problem, retryable, programName) {
+    if (problem !== undefined)
+        return remediationTable(programName)[problem.code];
+    return retryable ? "The identical request is safe to repeat." : undefined;
+}
+/**
+ * The table under the canonical name, for the cases that read its sentences.
+ *
+ * A case asserting what the advice *says* wants one spelling; a case asserting
+ * that it follows the invoked name passes its own.
+ */
+export const REMEDIATION = remediationTable(CANONICAL_PROGRAM_NAME);
+/** Exposed so a case can assert the records cover the published vocabularies. */
+export { isRetryable, remediationTable };

package/dist/runtime.d.ts

@@ -23,6 +23,26 @@ export interface CliRuntime {
     /** Hands a URL to the platform's browser. Rejects when there is none. */
     readonly openBrowser: (url: string) => Promise<void>;
     readonly platform: string;
+    /**
+     * The name this executable was invoked as — `greatwait`, or `gw`.
+     *
+     * **Every sentence written for a person uses it.** A command line installed
+     * under a short name and answering "Next: greatwait attempts list …" hands
+     * back exactly the typing the short name exists to save, and sends somebody
+     * to a command they may not have on their PATH at all.
+     *
+     * Not derived from `process.argv[1]`, which is the resolved module path
+     * behind npm's symlinked shim. The entry point states it.
+     */
+    readonly programName: string;
+    /**
+     * Reads one line, echoing it. Only ever used for a confirmation.
+     *
+     * Separate from `promptSecret` because the two have opposite obligations:
+     * one must never show what is typed and this one must, so somebody can see
+     * they answered the question that was asked.
+     */
+    readonly promptLine: (question: string) => Promise<string>;
     /** Reads one line without echoing it. Only ever used for a secret. */
     readonly promptSecret: (question: string) => Promise<string>;
     readonly randomBytes: (length: number) => Uint8Array;
@@ -45,7 +65,7 @@ export interface LoopbackListener {
 }
 /** Raised where the reason is already a sentence a person can act on. */
 export declare class CliError extends Error {
-    readonly exit: "authentication" | "authorization" | "internal" | "retryable" | "timeout" | "usage" | "validation";
+    readonly exit: "authentication" | "authorization" | "internal" | "interrupted" | "retryable" | "timeout" | "usage" | "validation";
     readonly nextMove: string | undefined;
     constructor(message: string, exit: CliError["exit"], nextMove?: string);
 }

package/dist/session.js

@@ -42,9 +42,9 @@ export async function resolveOrigin(runtime, store, argumentValue) {
         return { origin: known[0], source: "sole" };
     }
     if (known.length === 0) {
-        throw new CliError("no Greatwait service has been chosen", "usage", `Sign in first — greatwait login --api-url https://api.greatwait.dev — or set ${ENVIRONMENT_NAMES.apiUrl}.`);
+        throw new CliError("no GreatWait service has been chosen", "usage", `Sign in first — ${runtime.programName} login --api-url https://api.greatwait.dev — or set ${ENVIRONMENT_NAMES.apiUrl}.`);
     }
-    throw new CliError(`${String(known.length)} services are signed in and none is selected`, "usage", `Choose one — greatwait context use ${known[0]} — or pass --api-url on this command.`);
+    throw new CliError(`${String(known.length)} services are signed in and none is selected`, "usage", `Choose one — ${runtime.programName} context use ${known[0]} — or pass --api-url on this command.`);
 }
 function normalize(value) {
     try {
@@ -101,7 +101,7 @@ export async function openSession(runtime, options) {
     }
     const stored = await store.read(resolved.origin);
     if (stored === undefined) {
-        throw new CliError(`no credential is stored for ${resolved.origin}`, "authentication", `Sign in — greatwait login --api-url ${resolved.origin} — or export ${ENVIRONMENT_NAMES.apiKey} for a non-interactive run.`);
+        throw new CliError(`no credential is stored for ${resolved.origin}`, "authentication", `Sign in — ${runtime.programName} login --api-url ${resolved.origin} — or export ${ENVIRONMENT_NAMES.apiKey} for a non-interactive run.`);
     }
     const credential = await presentableSecret(runtime, store, resolved.origin, stored);
     return {
@@ -130,13 +130,13 @@ export const REFRESH_MARGIN_MS = 60_000;
 async function presentableSecret(runtime, store, origin, stored) {
     if (stored.kind === "api-key") {
         if (stored.secret === undefined) {
-            throw new CliError(`the stored credential for ${origin} carries no secret`, "authentication", `Sign in again: greatwait login --api-url ${origin} --api-key`);
+            throw new CliError(`the stored credential for ${origin} carries no secret`, "authentication", `Sign in again: ${runtime.programName} login --api-url ${origin} --api-key`);
         }
         return stored.secret;
     }
     const { accessToken, clientId, expiresAtMs, refreshToken } = stored;
     if (accessToken === undefined || clientId === undefined) {
-        throw new CliError(`the stored grant for ${origin} is incomplete`, "authentication", `Sign in again: greatwait login --api-url ${origin}`);
+        throw new CliError(`the stored grant for ${origin} is incomplete`, "authentication", `Sign in again: ${runtime.programName} login --api-url ${origin}`);
     }
     if (expiresAtMs === undefined ||
         expiresAtMs - REFRESH_MARGIN_MS > runtime.now() ||

package/dist/start.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The body both installed executables share.
+ *
+ * **Two entry files rather than one that works out what it was called.**
+ * `process.argv[1]` is the *resolved* path of the main module, and npm links a
+ * bin as a symlink into `node_modules/.bin`, so a program deriving its own name
+ * from argv would read `main.js` — and the version that guesses correctly on
+ * macOS is the version that guesses differently under a shell wrapper, on
+ * Windows, or with `--preserve-symlinks-main`. The name is a property of the
+ * entry point, so the entry point states it.
+ *
+ * `process.exitCode` rather than `process.exit`: the second truncates whatever
+ * is still buffered on stdout, and this command's last act is to print.
+ */
+export declare function start(programName: string): Promise<void>;

package/dist/start.js

@@ -0,0 +1,26 @@
+import { run } from "./cli.js";
+import { nodeRuntime } from "./node-runtime.js";
+/**
+ * The body both installed executables share.
+ *
+ * **Two entry files rather than one that works out what it was called.**
+ * `process.argv[1]` is the *resolved* path of the main module, and npm links a
+ * bin as a symlink into `node_modules/.bin`, so a program deriving its own name
+ * from argv would read `main.js` — and the version that guesses correctly on
+ * macOS is the version that guesses differently under a shell wrapper, on
+ * Windows, or with `--preserve-symlinks-main`. The name is a property of the
+ * entry point, so the entry point states it.
+ *
+ * `process.exitCode` rather than `process.exit`: the second truncates whatever
+ * is still buffered on stdout, and this command's last act is to print.
+ */
+export async function start(programName) {
+    const controller = new AbortController();
+    process.on("SIGINT", () => {
+        controller.abort();
+    });
+    process.on("SIGTERM", () => {
+        controller.abort();
+    });
+    process.exitCode = await run(nodeRuntime(controller.signal, programName));
+}

package/dist/support.d.ts

@@ -0,0 +1,129 @@
+import { type ParsedArguments } from "./args.js";
+import { type CliRuntime } from "./runtime.js";
+/**
+ * What every command needs and no command should spell twice.
+ *
+ * Extracted when the command surface grew past first value: the alternative was
+ * `commands.ts` importing `operate.ts` and back again for the same six
+ * helpers, and a positional-argument refusal written slightly differently in
+ * thirty places.
+ */
+/**
+ * A response, validated against the shape the contract publishes for it.
+ *
+ * **A missing schema raises rather than yielding `undefined`.** The first
+ * spelling of this was `responseSchemaFor(id)?.parse(body) as T`, which turns
+ * an operation the registry does not describe into a successfully parsed
+ * `undefined` — and then into a `TypeError` several lines later, in the
+ * rendering, naming a property rather than the operation. There is no case
+ * where a command should carry on without knowing what it received.
+ */
+export declare function parseResponse<TView>(operation: string, body: unknown): TView;
+export declare function apiUrlOption(args: ParsedArguments): string | undefined;
+/** The program name a usage line opens with. */
+export declare function programNameFrom(usage: string): string;
+export declare function expectNoExtraArguments(args: ParsedArguments, used: number, usage: string): void;
+/**
+ * The positional arguments a command needs, or a refusal naming the shape.
+ *
+ * Reads them all at once so a command missing its second of three says so
+ * rather than refusing the first thing it happens to check, and so the
+ * "unexpected argument" rule is applied from the same count.
+ */
+export declare function positionals(args: ParsedArguments, names: readonly string[], usage: string): readonly string[];
+/** The payload, from an argument, a file, or standard input. */
+export declare function readJsonOption(runtime: CliRuntime, flag: string, value: string | undefined): Promise<unknown>;
+/**
+ * An instant, in the exact spelling the contract publishes.
+ *
+ * **Refused here rather than by the service, and normalised on the way.**
+ * `--in` was already read before anything was sent and `--at` was not, so
+ * `--at "next tuesday"` cost a round trip and came back as `invalid_request` —
+ * which calls a mistake in the command line a fault in the request. And the
+ * ordinary ISO spelling somebody types, `2030-01-01T00:00:00Z`, is refused by
+ * the contract for having no milliseconds; that is a real instant written a
+ * normal way, so it is formatted rather than rejected. Nothing is guessed: a
+ * value `Date` cannot read is refused, and the refusal says what a good one
+ * looks like.
+ */
+export declare function parseInstant(value: string, flag?: string): string;
+/**
+ * A whole number an option was given, refused here rather than by the service.
+ *
+ * The contract's own bounds, so `--limit 500` says what the maximum is instead
+ * of spending a round trip to be told `invalid_request`.
+ */
+export declare function parseCount(value: string, flag: string, bounds: {
+    readonly max: number;
+    readonly min: number;
+}): number;
+/**
+ * How many pages `--all` will follow before it stops and says so.
+ *
+ * A bounded invocation holds at most fifty response pages in memory. Its
+ * cursor can be used with `--all` again, so this limits one invocation's
+ * allocation and request burst without preventing access to later records.
+ */
+export declare const ALL_PAGES_CEILING = 50;
+export interface PageRequest {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+/** The page arguments, validated against the contract's own bounds. */
+export declare function pageRequest(args: ParsedArguments): PageRequest;
+export interface Page<TRow> {
+    readonly data: readonly TRow[];
+    readonly freshness: Freshness;
+    readonly nextCursor?: string;
+}
+export type Freshness = {
+    readonly kind: "authoritative";
+} | {
+    readonly asOf: string;
+    readonly kind: "projected";
+    readonly lagSeconds: number;
+};
+export interface DrainedPages<TRow> {
+    readonly ceilingReached: boolean;
+    readonly freshness: Freshness;
+    readonly nextCursor: string | undefined;
+    readonly pages: number;
+    readonly rows: readonly TRow[];
+}
+/**
+ * One page, or every page, without either being a different command.
+ *
+ * The freshness reported is the *stalest* page seen rather than the last one:
+ * a listing assembled from several projected pages is only as fresh as its
+ * worst, and reporting the final page's age would describe a collection as
+ * current on the strength of the part that happened to be read last.
+ */
+export declare function drainPages<TRow>(runtime: CliRuntime, args: ParsedArguments, request: PageRequest, read: (request: PageRequest) => Promise<Page<TRow>>): Promise<DrainedPages<TRow>>;
+/** The freshness of an answer, in a sentence, or nothing to say. */
+export declare function freshnessNote(freshness: Freshness): string | undefined;
+/**
+ * What to say about a listing that stopped before the collection did.
+ *
+ * The cursor is handed back rather than swallowed: it is the only way to
+ * continue, and a command that knew where it stopped and did not say would
+ * make the ceiling indistinguishable from the end of the data.
+ */
+export declare function continuationNote(drained: DrainedPages<unknown>, command: string): string | undefined;
+/**
+ * `If-Match`, from the ETag a read handed out.
+ *
+ * The header rather than a version number, because that is what the service
+ * publishes and what `schedules read` prints. Turning one into the other here
+ * would make this command the only place that knows the mapping.
+ */
+export declare function conditionalHeaders(args: ParsedArguments): Readonly<Record<string, string>>;
+/**
+ * A column-aligned table, or a sentence when there is nothing in it.
+ *
+ * **Identifiers are present and are not the first thing read.** The story asks
+ * for output where identifiers are available without dominating it, and the
+ * answer is ordinary column alignment: the state somebody is looking for lines
+ * up down the left, and the identifier they will paste into the next command is
+ * where they can select it.
+ */
+export declare function table(columns: readonly string[], rows: readonly (readonly string[])[], empty: string): string;

package/dist/support.js

@@ -0,0 +1,261 @@
+import { responseSchemaFor } from "@greatwait/contracts";
+import { CANONICAL_PROGRAM_NAME } from "./catalog.js";
+import { PAGE_SIZE } from "@greatwait/contracts/protocol";
+import { secretArgumentAdvice } from "./args.js";
+import { CliError } from "./runtime.js";
+import { readFile } from "node:fs/promises";
+/**
+ * What every command needs and no command should spell twice.
+ *
+ * Extracted when the command surface grew past first value: the alternative was
+ * `commands.ts` importing `operate.ts` and back again for the same six
+ * helpers, and a positional-argument refusal written slightly differently in
+ * thirty places.
+ */
+/**
+ * A response, validated against the shape the contract publishes for it.
+ *
+ * **A missing schema raises rather than yielding `undefined`.** The first
+ * spelling of this was `responseSchemaFor(id)?.parse(body) as T`, which turns
+ * an operation the registry does not describe into a successfully parsed
+ * `undefined` — and then into a `TypeError` several lines later, in the
+ * rendering, naming a property rather than the operation. There is no case
+ * where a command should carry on without knowing what it received.
+ */
+export function parseResponse(operation, body) {
+    const schema = responseSchemaFor(operation);
+    if (schema === undefined) {
+        throw new CliError(`the contract publishes no response shape for ${operation}`, "internal");
+    }
+    return schema.parse(body);
+}
+export function apiUrlOption(args) {
+    return args.options["--api-url"];
+}
+/** The program name a usage line opens with. */
+export function programNameFrom(usage) {
+    return usage.split(" ")[0] ?? CANONICAL_PROGRAM_NAME;
+}
+export function expectNoExtraArguments(args, used, usage) {
+    if (args.command.length <= used)
+        return;
+    // **A refusal never names an argument when `--api-key` is on the line.**
+    // The parser refuses a value immediately after that flag, but it cannot
+    // refuse one further along — `greatwait --api-key login <secret>` parses
+    // `login` as the command and leaves the secret as a positional — and naming
+    // it here is how the credential reached standard error and the `--json`
+    // envelope in the first place. Two layers, because either alone leaves a
+    // spelling uncovered.
+    if (args.booleans.has("--api-key")) {
+        // **The name this was invoked as, taken from the usage line.** Every caller
+        // builds that line starting with it — the same string the refusal below
+        // prints — so there is one source rather than a second parameter threaded
+        // through thirty call sites, and a case pins the derivation.
+        throw new CliError("unexpected argument after --api-key", "usage", secretArgumentAdvice(programNameFrom(usage)));
+    }
+    throw new CliError(`unexpected argument ${args.command[used]}`, "usage", `Usage: ${usage}`);
+}
+/**
+ * The positional arguments a command needs, or a refusal naming the shape.
+ *
+ * Reads them all at once so a command missing its second of three says so
+ * rather than refusing the first thing it happens to check, and so the
+ * "unexpected argument" rule is applied from the same count.
+ */
+export function positionals(args, names, usage) {
+    const found = names.map((_, index) => args.command[index]);
+    const missing = names.filter((_, index) => found[index] === undefined);
+    if (missing.length > 0) {
+        // The command words alone, without the argument shapes: the usage line
+        // repeats them a line later, and "greatwait attempts read <schedule>
+        // <occurrence> <attempt> needs <occurrence> and <attempt>" reads as though
+        // the arguments were given and rejected.
+        const words = (usage.split(/\s[<[]/u)[0] ?? usage).trim();
+        throw new CliError(`${words} needs ${missing.join(" and ")}`, "usage", `Usage: ${usage}`);
+    }
+    expectNoExtraArguments(args, names.length, usage);
+    return found;
+}
+/** The payload, from an argument, a file, or standard input. */
+export async function readJsonOption(runtime, flag, value) {
+    if (value === undefined)
+        return undefined;
+    const text = value === "-"
+        ? await runtime.readStdin()
+        : value.startsWith("@")
+            ? await readFile(value.slice(1), "utf8")
+            : value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliError(`${flag} is not JSON`, "usage", `Pass a JSON object, @a-file.json, or - to read it from standard input.`);
+    }
+}
+/**
+ * An instant, in the exact spelling the contract publishes.
+ *
+ * **Refused here rather than by the service, and normalised on the way.**
+ * `--in` was already read before anything was sent and `--at` was not, so
+ * `--at "next tuesday"` cost a round trip and came back as `invalid_request` —
+ * which calls a mistake in the command line a fault in the request. And the
+ * ordinary ISO spelling somebody types, `2030-01-01T00:00:00Z`, is refused by
+ * the contract for having no milliseconds; that is a real instant written a
+ * normal way, so it is formatted rather than rejected. Nothing is guessed: a
+ * value `Date` cannot read is refused, and the refusal says what a good one
+ * looks like.
+ */
+export function parseInstant(value, flag = "--at") {
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        throw new CliError(`${value} is not an instant`, "usage", `Write ${flag} as UTC, such as 2030-01-01T09:00:00.000Z.`);
+    }
+    return new Date(parsed).toISOString();
+}
+/**
+ * A whole number an option was given, refused here rather than by the service.
+ *
+ * The contract's own bounds, so `--limit 500` says what the maximum is instead
+ * of spending a round trip to be told `invalid_request`.
+ */
+export function parseCount(value, flag, bounds) {
+    if (!/^\d+$/u.test(value)) {
+        throw new CliError(`${flag} must be a whole number`, "usage");
+    }
+    const count = Number(value);
+    if (count < bounds.min || count > bounds.max) {
+        throw new CliError(`${flag} must be between ${String(bounds.min)} and ${String(bounds.max)}`, "usage");
+    }
+    return count;
+}
+/* -------------------------------------------------------------------------- */
+/* Pagination                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * How many pages `--all` will follow before it stops and says so.
+ *
+ * A bounded invocation holds at most fifty response pages in memory. Its
+ * cursor can be used with `--all` again, so this limits one invocation's
+ * allocation and request burst without preventing access to later records.
+ */
+export const ALL_PAGES_CEILING = 50;
+/** The page arguments, validated against the contract's own bounds. */
+export function pageRequest(args) {
+    const limit = args.options["--limit"];
+    const cursor = args.options["--cursor"];
+    return {
+        ...(cursor === undefined ? {} : { cursor }),
+        ...(limit === undefined
+            ? {}
+            : { limit: parseCount(limit, "--limit", PAGE_SIZE) }),
+    };
+}
+/**
+ * One page, or every page, without either being a different command.
+ *
+ * The freshness reported is the *stalest* page seen rather than the last one:
+ * a listing assembled from several projected pages is only as fresh as its
+ * worst, and reporting the final page's age would describe a collection as
+ * current on the strength of the part that happened to be read last.
+ */
+export async function drainPages(runtime, args, request, read) {
+    const all = args.booleans.has("--all");
+    const rows = [];
+    let freshness = { kind: "authoritative" };
+    let cursor = request.cursor;
+    let pages = 0;
+    for (;;) {
+        if (runtime.signal.aborted) {
+            throw new CliError("stopped while reading pages", "interrupted");
+        }
+        const page = await read({
+            ...(cursor === undefined ? {} : { cursor }),
+            ...(request.limit === undefined ? {} : { limit: request.limit }),
+        });
+        pages += 1;
+        rows.push(...page.data);
+        freshness = stalest(freshness, page.freshness);
+        cursor = page.nextCursor;
+        if (!all || cursor === undefined) {
+            return {
+                ceilingReached: false,
+                freshness,
+                nextCursor: cursor,
+                pages,
+                rows,
+            };
+        }
+        if (pages >= ALL_PAGES_CEILING) {
+            return {
+                ceilingReached: true,
+                freshness,
+                nextCursor: cursor,
+                pages,
+                rows,
+            };
+        }
+    }
+}
+function stalest(left, right) {
+    if (left.kind === "authoritative")
+        return right;
+    if (right.kind === "authoritative")
+        return left;
+    return right.lagSeconds > left.lagSeconds ? right : left;
+}
+/** The freshness of an answer, in a sentence, or nothing to say. */
+export function freshnessNote(freshness) {
+    if (freshness.kind === "authoritative")
+        return undefined;
+    return `Read from a projection that was ${String(freshness.lagSeconds)}s behind at ${freshness.asOf}, so something newer than that may be missing.`;
+}
+/**
+ * What to say about a listing that stopped before the collection did.
+ *
+ * The cursor is handed back rather than swallowed: it is the only way to
+ * continue, and a command that knew where it stopped and did not say would
+ * make the ceiling indistinguishable from the end of the data.
+ */
+export function continuationNote(drained, command) {
+    if (drained.nextCursor === undefined)
+        return undefined;
+    return drained.ceilingReached
+        ? `Stopped after ${String(drained.pages)} pages; this result is incomplete. Continue with: ${command} --cursor ${drained.nextCursor} --all`
+        : `More to read. Continue with: ${command} --cursor ${drained.nextCursor}`;
+}
+/* -------------------------------------------------------------------------- */
+/* Conditional writes                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * `If-Match`, from the ETag a read handed out.
+ *
+ * The header rather than a version number, because that is what the service
+ * publishes and what `schedules read` prints. Turning one into the other here
+ * would make this command the only place that knows the mapping.
+ */
+export function conditionalHeaders(args) {
+    const etag = args.options["--if-match"];
+    return etag === undefined ? {} : { "If-Match": etag };
+}
+/* -------------------------------------------------------------------------- */
+/* Human output                                                               */
+/* -------------------------------------------------------------------------- */
+/**
+ * A column-aligned table, or a sentence when there is nothing in it.
+ *
+ * **Identifiers are present and are not the first thing read.** The story asks
+ * for output where identifiers are available without dominating it, and the
+ * answer is ordinary column alignment: the state somebody is looking for lines
+ * up down the left, and the identifier they will paste into the next command is
+ * where they can select it.
+ */
+export function table(columns, rows, empty) {
+    if (rows.length === 0)
+        return empty;
+    const widths = columns.map((heading, index) => Math.max(heading.length, ...rows.map((row) => (row[index] ?? "").length)));
+    const render = (cells) => cells
+        .map((cell, index) => index === cells.length - 1 ? cell : cell.padEnd(widths[index]))
+        .join("  ")
+        .trimEnd();
+    return [render(columns), ...rows.map(render)].join("\n");
+}

package/package.json

@@ -1,15 +1,16 @@
 {
   "bin": {
-    "greatwait": "./dist/main.js"
+    "greatwait": "./dist/main.js",
+    "gw": "./dist/gw.js"
   },
   "bugs": {
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.1.0-alpha.3",
-    "@greatwait/contracts": "0.1.0-alpha.3"
+    "@greatwait/api-client": "0.1.0-alpha.5",
+    "@greatwait/contracts": "0.1.0-alpha.5"
   },
-  "description": "The Greatwait command line: sign in, create a destination and a one-shot schedule, and wait for the callback, over the public API.",
+  "description": "The GreatWait command line: sign in, create a destination and a one-shot schedule, and wait for the callback, over the public API.",
   "engines": {
     "node": ">=22.13.0"
   },
@@ -47,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0-alpha.3"
+  "version": "0.1.0-alpha.5"
 }