@greatwait/cli 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/operate.js

@@ -1,10 +1,10 @@
-import { billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
+import { httpRequestSchema, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
 import { parseDuration } from "./args.js";
 import { confirmChange } from "./confirm.js";
 import { redactSecret } from "./output.js";
 import { CliError } from "./runtime.js";
 import { openSession } from "./session.js";
-import { apiUrlOption, conditionalHeaders, continuationNote, drainPages, freshnessNote, pageRequest, parseInstant, parseResponse, positionals, readJsonOption, table, } from "./support.js";
+import { apiUrlOption, conditionalHeaders, continuationNote, drainPages, freshnessNote, pageRequest, parseInstant, parseResponse, positionals, readJsonOption, readPrivateJsonOption, table, } from "./support.js";
 /* -------------------------------------------------------------------------- */
 /* Shared plumbing                                                            */
 /* -------------------------------------------------------------------------- */
@@ -102,18 +102,78 @@ async function scheduleRequest(runtime, args, usage) {
                 ? { everySeconds: parseDuration(value) }
                 : { cron: value };
     const endpoint = args.options["--endpoint"];
+    const url = args.options["--url"];
+    if (endpoint !== undefined && url !== undefined) {
+        // Refused here as well as by the service, because "you gave both" is a
+        // sentence about the line somebody typed. The service's own refusal says
+        // the same thing a round trip later.
+        throw new CliError("give --endpoint or --url, not both", "usage", "--url uses this project's destination at that address, or creates one. --endpoint names a destination that already exists.");
+    }
     const data = await readJsonOption(runtime, "--data", args.options["--data"]);
+    const httpInput = await readPrivateJsonOption(runtime, "--http", args.options["--http"]);
+    const http = httpInput === undefined
+        ? undefined
+        : httpRequestSchema.safeParse(httpInput);
+    if (http !== undefined && !http.success)
+        throw new CliError("--http settings are invalid", "usage", http.error.issues.map((issue) => issue.message).join("; "));
     const latencyClass = args.options["--latency-class"];
     const partitionKey = args.options["--partition-key"];
     return {
         ...(data === undefined ? {} : { data }),
+        ...(http?.success ? { http: http.data } : {}),
         ...(endpoint === undefined ? {} : { endpoint }),
+        ...(url === undefined ? {} : { url }),
         ...(latencyClass === undefined ? {} : { latencyClass }),
         ...(partitionKey === undefined ? {} : { partitionKey }),
         ...(timeZone === undefined ? {} : { timeZone }),
         ...recurrence,
     };
 }
+/**
+ * Where a schedule written with `--url` delivers, and where its signing
+ * secret is.
+ *
+ * **Only the API's notice, never a secret.** A schedule write that names a
+ * `url` answers with `endpointSigningSecret` — `returned: false` and the
+ * dashboard page where a member reveals the secret — and nothing else about
+ * it, so there is nothing here that could print one. Absent when the write
+ * named `--endpoint`: that caller already holds the destination it chose.
+ */
+export function destinationLines(schedule, notice, 
+/**
+ * The `--url` that was sent. A schedule write answers without
+ * `endpointUrl` (only reads carry it), and the address is the one the
+ * destination was found or made at.
+ */
+requestedUrl) {
+    if (notice === undefined)
+        return [];
+    const address = schedule.endpointUrl ?? canonical(requestedUrl);
+    return [
+        ...(schedule.endpoint === undefined
+            ? []
+            : [
+                `Destination  ${schedule.endpoint}${address === undefined ? "" : ` at ${address}`}`,
+            ]),
+        ``,
+        `GreatWait signs every call to this address. Your receiver checks the`,
+        `signature with the destination's signing secret, which isn't shown here.`,
+        notice.revealUrl === undefined
+            ? `A project member can reveal it on the destination's page in the dashboard.`
+            : `Reveal it on the destination's page: ${notice.revealUrl}`,
+    ];
+}
+/** An address as the service stores it, or as typed if it will not parse. */
+function canonical(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).href;
+    }
+    catch {
+        return url;
+    }
+}
 /** How a schedule's recurrence reads in one column. */
 function recurrenceOf(schedule) {
     return schedule.recurrence.kind;
@@ -176,6 +236,12 @@ const destinationsUpdate = async (runtime, args) => {
     if (url === undefined) {
         throw new CliError(`${runtime.programName} destinations update needs --url`, "usage", `Usage: ${runtime.programName} destinations update <destination> --url https://your-receiver.example.com/greatwait`);
     }
+    const headerInput = await readPrivateJsonOption(runtime, "--headers", args.options["--headers"]);
+    const headers = headerInput === undefined
+        ? undefined
+        : endpointHeaderChangesSchema.safeParse(headerInput);
+    if (headers !== undefined && !headers.success)
+        throw new CliError("--headers settings are invalid", "usage", headers.error.issues.map((issue) => issue.message).join("; "));
     const active = await session(runtime, args);
     // Read first, so the preview is the destination as it stands rather than the
     // arguments read back.
@@ -188,7 +254,7 @@ const destinationsUpdate = async (runtime, args) => {
             `Deliveries in flight keep going to the receiver they started for.`,
         ],
     });
-    const updated = parseResponse("endpoints.update", await active.client.request("endpoints_update", id, { url }, conditionalHeaders(args)));
+    const updated = parseResponse("endpoints.update", await active.client.request("endpoints_update", id, { url, ...(headers?.success ? { headers: headers.data } : {}) }, conditionalHeaders(args)));
     return {
         data: { confirmation, endpoint: updated },
         human: endpointBlock(updated).join("\n"),
@@ -226,9 +292,11 @@ const destinationsRotateKey = async (runtime, args) => {
             ``,
             `Signing key  ${rotated.secret}`,
             ``,
-            `This key is shown once and is not recoverable. Add it to your receiver's`,
+            `This is the only call that returns the key. Add it to your receiver's`,
             `accepted set now, alongside the current one; reading this destination back`,
-            `will show ${redactSecret(rotated.secret)} instead.`,
+            `will show ${redactSecret(rotated.secret)} instead. If you lose it, a`,
+            `signed-in member can read it again on this destination's page in the`,
+            `dashboard; no command here can.`,
         ].join("\n"),
     };
 };
@@ -277,6 +345,9 @@ async function scheduleChange(runtime, args, options) {
     return {
         data: {
             ...(confirmation === undefined ? {} : { confirmation }),
+            ...(view.endpointSigningSecret === undefined
+                ? {}
+                : { endpointSigningSecret: view.endpointSigningSecret }),
             ...(view.occurrence === undefined ? {} : { occurrence: view.occurrence }),
             schedule: view.schedule,
         },
@@ -290,12 +361,13 @@ async function scheduleChange(runtime, args, options) {
                 : [
                     `Next         ${view.occurrence.id} planned for ${view.occurrence.plannedFor} (${view.occurrence.state})`,
                 ]),
+            ...destinationLines(view.schedule, view.endpointSigningSecret, args.options["--url"]),
         ].join("\n"),
         ...(nextMove === undefined ? {} : { nextMove }),
     };
 }
 const schedulesReplace = async (runtime, args) => {
-    const usage = `${runtime.programName} schedules replace <schedule> --endpoint <destination> (--in <duration> | --at <instant> | --every <duration> | --cron <expression>)`;
+    const usage = `${runtime.programName} schedules replace <schedule> (--endpoint <destination> | --url <https url>) (--in <duration> | --at <instant> | --every <duration> | --cron <expression>)`;
     const [id] = positionals(args, ["<schedule>"], usage);
     const request = await scheduleRequest(runtime, args, usage);
     return scheduleChange(runtime, args, {
@@ -304,7 +376,8 @@ const schedulesReplace = async (runtime, args) => {
             action: `Replace the definition of schedule ${current.id}.`,
             effect: [
                 `now      ${recurrenceOf(current)}, ${current.status}, version ${String(current.version)}`,
-                `after    the definition on this command line, and nothing of the old one`,
+                `after    the timing on this command line. Destination, data and HTTP`,
+                `         settings are kept unless this command line gives new ones.`,
                 `Occurrences already planned under the old definition are discarded.`,
             ],
         }),
@@ -445,7 +518,7 @@ const attemptsRead = async (runtime, args) => {
         ].join("\n"),
         ...(found.remediation === "review_before_redelivery"
             ? {
-                nextMove: "This attempt was ambiguous: the receiver may have processed it even though Greatwait never saw an answer. Check the receiver before redelivering.",
+                nextMove: "This attempt was ambiguous: the receiver may have processed it even though GreatWait never saw an answer. Check the receiver before redelivering.",
             }
             : {}),
     };
@@ -462,6 +535,46 @@ function window(args) {
         ...(to === undefined ? {} : { to: parseInstant(to, "--to") }),
     };
 }
+const limitsShow = async (runtime, args) => {
+    positionals(args, [], `${runtime.programName} limits show`);
+    const active = await session(runtime, args);
+    const view = parseResponse("limits.read", await active.client.request("limits_read"));
+    const rows = [
+        [
+            "Inline payload",
+            String(view.limits.inlinePayloadBytes),
+            "bytes",
+            view.provenance.inlinePayloadBytes,
+        ],
+        [
+            "Partition keys",
+            view.limits.partitionKeyCeiling === undefined
+                ? "No configured ceiling"
+                : String(view.limits.partitionKeyCeiling),
+            "keys",
+            view.provenance.partitionKeyCeiling ?? "default",
+        ],
+        [
+            "Forecast horizon",
+            String(view.limits.forecastHorizonSeconds),
+            "seconds",
+            view.provenance.forecastHorizonSeconds,
+        ],
+        [
+            "Usage window",
+            String(view.limits.usageWindowDays),
+            "days",
+            view.provenance.usageWindowDays,
+        ],
+    ];
+    return {
+        data: view,
+        human: [
+            table(["SETTING", "VALUE", "UNIT", "ORIGIN"], rows, ""),
+            `Policy revisions: global ${String(view.revision.global)}, organization ${String(view.revision.organization)}`,
+        ].join("\n"),
+    };
+};
 const forecast = async (runtime, args) => {
     const active = await session(runtime, args);
     const bucket = args.options["--bucket"];
@@ -678,18 +791,38 @@ const billingNotificationSettings = async (runtime, args) => {
 };
 const billingNotificationSettingsUpdate = async (runtime, args) => {
     const noncritical = args.options["--noncritical-email"];
+    // Three meanings, matching the contract: omitted leaves the threshold as it
+    // is, chosen or not; `auto` sends null, which returns it to a fifth of the
+    // latest credit grant; an amount chooses it. `off` is how other commands
+    // spell "no amount", and there is no "no threshold" here, so it is refused
+    // along with zero, negatives and fractions of a cent.
+    const lowCreditRaw = args.options["--low-credit"];
+    const lowCredit = lowCreditRaw === undefined
+        ? undefined
+        : lowCreditRaw === "auto"
+            ? null
+            : budgetMoney(args, "--low-credit");
+    const refusal = "--low-credit must be a positive exact-cent USD amount or auto, and --noncritical-email must be on or off";
+    if (lowCreditRaw !== undefined &&
+        lowCreditRaw !== "auto" &&
+        lowCredit === null)
+        throw new CliError(refusal, "usage");
     const parsed = billingNotificationSettingsUpdateRequestSchema.safeParse({
         expectedRevision: expectedRevision(args),
-        lowCreditThreshold: budgetMoney(args, "--low-credit"),
+        ...(lowCredit === undefined ? {} : { lowCreditThreshold: lowCredit }),
         noncriticalEmail: noncritical === "on" ? true : noncritical === "off" ? false : undefined,
     });
     if (!parsed.success) {
-        throw new CliError("--low-credit must be a positive exact-cent USD amount and --noncritical-email must be on or off", "usage");
+        throw new CliError(refusal, "usage");
     }
     const confirmation = await confirmChange(runtime, args, {
         action: "Replace this organization's billing notification settings.",
         effect: [
-            `low-credit threshold ${money(parsed.data.lowCreditThreshold)}`,
+            lowCredit === undefined
+                ? "low-credit threshold unchanged"
+                : lowCredit === null
+                    ? "low-credit threshold automatic (a fifth of the latest credit grant)"
+                    : `low-credit threshold ${money(lowCredit)}`,
             `noncritical email ${parsed.data.noncriticalEmail ? "on" : "off"}`,
             "Critical email remains mandatory for owners and active billing-role members.",
         ],
@@ -877,12 +1010,12 @@ const billingRefundRequest = async (runtime, args) => {
         throw new CliError("Provide a positive exact-cent --amount, --payment-operation and --reason", "usage");
     }
     const confirmation = await confirmChange(runtime, args, {
-        action: "Record this unused-credit refund request for operator review.",
+        action: "Reserve this unused purchased credit against the payment for refund.",
         effect: [
             `amount ${money(parsed.data.amount)}`,
             `payment ${parsed.data.paymentOperation}`,
             `reason ${parsed.data.reason}`,
-            "This records a request only. It does not submit a provider refund or cash out credit.",
+            "This reserves credit only. It does not submit a provider refund or cash out credit.",
         ],
     });
     const active = await session(runtime, args);
@@ -898,7 +1031,7 @@ const billingRefundRequest = async (runtime, args) => {
             `Requested ${view.requestedAt}`,
             `Retry key ${key}`,
         ].join("\n"),
-        nextMove: "An operator must review this request before any provider refund.",
+        nextMove: "A Stripe refund of this payment settles or supersedes the reservation; resolve-refund --decision declined releases it.",
     };
 };
 const billingRefundResolution = async (runtime, args) => {
@@ -1020,6 +1153,99 @@ const billingChangeProject = async (runtime, args) => {
         data: { confirmation, idempotencyKey: key, ...view },
     };
 };
+const billingPaymentMethod = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const view = parseResponse("billing.paymentmethod", await active.client.request("billing_paymentmethod"));
+    return {
+        data: view,
+        human: paymentMethodLine(view),
+    };
+};
+/**
+ * The saved payment method in one line (W9-14). The label is the service's,
+ * so a card reads "Visa ending in 4242" here exactly as on the dashboard, and
+ * Link or Cash App Pay is named rather than reported as no card.
+ */
+function paymentMethodLine(view) {
+    const method = view.method;
+    if (method === null)
+        return "No payment method on file. Add one with billing add-card; automatic top-up and paid projects need it.";
+    return method.type === "card"
+        ? `Payment method on file: ${method.label}, expires ${String(method.expMonth).padStart(2, "0")}/${String(method.expYear)}`
+        : `Payment method on file: ${method.label}`;
+}
+const billingInvoices = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const view = parseResponse("billing.invoices", await active.client.request("billing_invoices"));
+    return {
+        data: view,
+        human: table(["CREATED", "AMOUNT", "STATE", "RECEIPT"], view.data.map((invoice) => [
+            invoice.createdAt,
+            money(invoice.amount),
+            invoice.state,
+            invoice.receiptUrl ?? "",
+        ]), "No project subscription charges."),
+    };
+};
+const billingPaymentHistory = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        command: `${runtime.programName} billing payment-history`,
+        columns: ["CREATED", "AMOUNT", "STATE", "RECEIPT"],
+        empty: "No execution-credit payments.",
+        read: (request) => page("billing.paymenthistory", () => active.client.request("billing_paymenthistory", request)),
+        row: (payment) => [
+            payment.createdAt,
+            money(payment.gross ?? payment.credit),
+            payment.state,
+            payment.receiptUrl ?? "",
+        ],
+    });
+};
+const billingInvoiceHistory = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        command: `${runtime.programName} billing invoice-history`,
+        columns: ["CREATED", "AMOUNT", "STATE", "RECEIPT"],
+        empty: "No project subscription charges.",
+        read: (request) => page("billing.invoicehistory", () => active.client.request("billing_invoicehistory", request)),
+        row: (invoice) => [
+            invoice.createdAt,
+            money(invoice.amount),
+            invoice.state,
+            invoice.receiptUrl ?? "",
+        ],
+    });
+};
+const billingAddCard = async (runtime, args) => {
+    await confirmChange(runtime, args, {
+        action: "Create a hosted link for adding or replacing this organization's payment method.",
+        effect: [
+            "The page offers a card, Link and any other method the account accepts. Saving one there charges nothing. It becomes what automatic top-ups and project subscriptions charge.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const view = parseResponse("billing.paymentmethodsetup", await active.client.request("billing_paymentmethodsetup", {}));
+    return { data: view, human: view.url };
+};
+const billingRemoveCard = async (runtime, args) => {
+    await confirmChange(runtime, args, {
+        action: "Remove this organization's saved payment method.",
+        effect: [
+            "Project subscriptions stop renewing: paid projects keep running until the end of the period already paid for, then stop. The included project keeps running.",
+            "Automatic top-up is turned off immediately. Nothing more is charged.",
+            "Saving a payment method again before the period ends keeps those projects.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const view = parseResponse("billing.paymentmethodremove", await active.client.request("billing_paymentmethodremove", {
+        confirmed: true,
+    }));
+    return {
+        data: view,
+        human: "Payment method removed. No payment method on file.",
+    };
+};
 const billingPortal = async (runtime, args) => {
     await confirmChange(runtime, args, {
         action: "Create this organization's hosted billing recovery link.",
@@ -1093,7 +1319,9 @@ const billingLedger = async (runtime, args) => {
         row: (entry) => [
             entry.sequence,
             entry.recordedAt,
-            entry.kind,
+            entry.note === "provider-details-attached"
+                ? `${entry.kind} (details attached)`
+                : entry.kind,
             money(entry.amount),
             entry.reference.attempt ??
                 entry.reference.creditLot ??
@@ -1230,7 +1458,9 @@ const sinksCreate = async (runtime, args) => {
     const program = await readJsonOption(runtime, "--program", args.options["--program"]);
     const sink = parseResponse("testsinks.create", await active.client.request("testsinks_create", {
         endpoint,
-        ...(program === undefined ? {} : { program }),
+        // The program is passed as typed and validated by the service, which
+        // names the field it refuses; the client's type cannot know it yet.
+        ...(program === undefined ? {} : { program: program }),
     }));
     return {
         data: { sink },
@@ -1281,7 +1511,7 @@ const sinksDelete = async (runtime, args) => {
         action: `Delete test sink ${current.id}.`,
         effect: [
             `received     ${String(current.deliveryCount)} deliveries, which go with it`,
-            `The recorded bodies are the only copy Greatwait keeps. Read anything you`,
+            `The recorded bodies are the only copy GreatWait keeps. Read anything you`,
             `still need first.`,
         ],
     });
@@ -1345,6 +1575,7 @@ const sinksDelivery = async (runtime, args) => {
 /* -------------------------------------------------------------------------- */
 /** The operate-and-diagnose commands, keyed by the words that select them. */
 export const OPERATE_COMMANDS = {
+    "limits show": limitsShow,
     "attempts read": attemptsRead,
     billing,
     "billing budgets": billingBudgets,
@@ -1364,6 +1595,12 @@ export const OPERATE_COMMANDS = {
     "billing resolve-refund": billingRefundResolution,
     "billing change-project": billingChangeProject,
     "billing portal": billingPortal,
+    "billing payment-method": billingPaymentMethod,
+    "billing invoices": billingInvoices,
+    "billing payment-history": billingPaymentHistory,
+    "billing invoice-history": billingInvoiceHistory,
+    "billing add-card": billingAddCard,
+    "billing remove-card": billingRemoveCard,
     timing,
     "credentials list": credentialsList,
     "credentials revoke": credentialsRevoke,

package/dist/remediation.d.ts

@@ -30,6 +30,6 @@ export declare function remediationFor(problem: Problem | undefined, retryable:
  * 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" | "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>>;
+export declare const REMEDIATION: Readonly<Record<"authentication_required" | "billing_not_ready" | "capability_not_configured" | "credential_expired" | "credential_revoked" | "idempotency_key_reused" | "invalid_request" | "not_found" | "payload_too_large" | "plan_limit_reached" | "project_archived" | "rate_limited" | "revision_conflict" | "scope_missing" | "service_unavailable" | "state_conflict" | "test_to_live_escalation" | "version_conflict", string>>;
 /** Exposed so a case can assert the records cover the published vocabularies. */
 export { isRetryable, remediationTable };

package/dist/remediation.js

@@ -19,6 +19,14 @@ import { CANONICAL_PROGRAM_NAME } from "./catalog.js";
 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.",

package/dist/session.js

@@ -42,7 +42,7 @@ 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 — ${runtime.programName} 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 — ${runtime.programName} context use ${known[0]} — or pass --api-url on this command.`);
 }

package/dist/support.d.ts

@@ -31,6 +31,8 @@ export declare function expectNoExtraArguments(args: ParsedArguments, used: numb
  * "unexpected argument" rule is applied from the same count.
  */
 export declare function positionals(args: ParsedArguments, names: readonly string[], usage: string): readonly string[];
+/** Secret-bearing option documents are accepted through files/stdin only. */
+export declare function readPrivateJsonOption(runtime: CliRuntime, flag: string, value: string | undefined): Promise<unknown>;
 /** The payload, from an argument, a file, or standard input. */
 export declare function readJsonOption(runtime: CliRuntime, flag: string, value: string | undefined): Promise<unknown>;
 /**
@@ -60,13 +62,9 @@ export declare function parseCount(value: string, flag: string, bounds: {
 /**
  * How many pages `--all` will follow before it stops and says so.
  *
- * **Published, and generous rather than equal to a page.** A ceiling nobody can
- * see is a truncation somebody reports as data loss, and one set at the
- * contract's page maximum would make `--all` mean "one page" for every
- * collection that has ever grown. Fifty pages at the contract's maximum size is
- * five thousand rows; past that, this stops, says how far it got, and hands
- * back the cursor to carry on from — which is the difference between a bound
- * and a lie.
+ * 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 {

package/dist/support.js

@@ -76,6 +76,13 @@ export function positionals(args, names, usage) {
     expectNoExtraArguments(args, names.length, usage);
     return found;
 }
+/** Secret-bearing option documents are accepted through files/stdin only. */
+export async function readPrivateJsonOption(runtime, flag, value) {
+    if (value !== undefined && value !== "-" && !value.startsWith("@")) {
+        throw new CliError(`${flag} must be @file.json or -`, "usage", "Read secret-bearing settings from a private file or standard input, never a command-line argument.");
+    }
+    return readJsonOption(runtime, flag, value);
+}
 /** The payload, from an argument, a file, or standard input. */
 export async function readJsonOption(runtime, flag, value) {
     if (value === undefined)
@@ -134,24 +141,15 @@ export function parseCount(value, flag, bounds) {
 /**
  * How many pages `--all` will follow before it stops and says so.
  *
- * **Published, and generous rather than equal to a page.** A ceiling nobody can
- * see is a truncation somebody reports as data loss, and one set at the
- * contract's page maximum would make `--all` mean "one page" for every
- * collection that has ever grown. Fifty pages at the contract's maximum size is
- * five thousand rows; past that, this stops, says how far it got, and hands
- * back the cursor to carry on from — which is the difference between a bound
- * and a lie.
+ * 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"];
-    if (cursor !== undefined && args.booleans.has("--all")) {
-        // Not a contradiction the service can catch: it would follow the cursor and
-        // report a partial collection as the whole of it.
-        throw new CliError("--cursor continues one listing and --all reads every page, so only one of them can be meant", "usage", "Drop --cursor to read from the start, or drop --all to read one page from where you were.");
-    }
     return {
         ...(cursor === undefined ? {} : { cursor }),
         ...(limit === undefined
@@ -229,7 +227,7 @@ export function continuationNote(drained, command) {
     if (drained.nextCursor === undefined)
         return undefined;
     return drained.ceilingReached
-        ? `Stopped after ${String(drained.pages)} pages, which is where --all stops. Continue with: ${command} --cursor ${drained.nextCursor}`
+        ? `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}`;
 }
 /* -------------------------------------------------------------------------- */

package/package.json

@@ -7,10 +7,10 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.1.0-alpha.4",
-    "@greatwait/contracts": "0.1.0-alpha.4"
+    "@greatwait/api-client": "0.1.0-alpha.6",
+    "@greatwait/contracts": "0.1.0-alpha.6"
   },
-  "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"
   },
@@ -48,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0-alpha.4"
+  "version": "0.1.0-alpha.6"
 }