@greatwait/cli 0.2.3 → 0.3.1

package/README.md

@@ -43,6 +43,13 @@ directory, readable by you and nobody else. A staging credential is never
 presented to production, because the two are separate entries rather than one
 current context.
 
+For a short script that needs a bearer token, `greatwait token` prints the
+credential for the selected API origin, refreshing an expiring OAuth sign-in
+first. Add `--api-url <origin>` to choose an origin explicitly. `--json` prints
+`{token, origin, expiresAt}`; an API key is returned unchanged with `null` expiry.
+This output is a secret: keep it out of logs, shell tracing and shared files.
+Use a scoped API key for unattended automation.
+
 ## First callback
 
 Use a public HTTPS receiver you control. Once signed in, schedule directly to
@@ -99,6 +106,8 @@ grant and remove local credentials.
 ## Output and exit codes
 
 `--json` is a versioned machine shape, not a serialization of the human text.
+The deliberate secret-output command `token --json` returns the credential object
+described above.
 The exit status is a class rather than a code per failure:
 
 | code | meaning                                                                |

package/dist/bulk.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedArguments } from "./args.js";
+import { type CliRuntime } from "./runtime.js";
+import type { CommandResult } from "./output.js";
+type Command = (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandResult>;
+export declare const BULK_COMMANDS: Readonly<Record<string, Command>>;
+export {};

package/dist/bulk.js

@@ -0,0 +1,178 @@
+import { bulkPreviewRequestSchema, bulkConfirmRequestSchema, bulkControlRequestSchema, bulkJobSchema, bulkListRequestSchema, bulkItemListRequestSchema, } from "@greatwait/contracts";
+import { confirmChange } from "./confirm.js";
+import { CliError } from "./runtime.js";
+import { openSession } from "./session.js";
+import { apiUrlOption, readJsonOption, parseResponse, positionals, pageRequest, drainPages, continuationNote, table, } from "./support.js";
+const session = (runtime, args) => openSession(runtime, { apiUrl: apiUrlOption(args) });
+function jobId(runtime, args, command) {
+    const [id] = positionals(args, ["<job>"], `${runtime.programName} bulk ${command} <job>`);
+    const parsed = bulkJobSchema.shape.id.safeParse(id);
+    if (!parsed.success)
+        throw new CliError("Give a valid bjo_ job identity from bulk preview", "usage");
+    return parsed.data;
+}
+function renderJob(job) {
+    const counts = job.counts;
+    return {
+        data: job,
+        human: [
+            `Job          ${job.id}`,
+            `Operation    ${job.intent.operation} ${job.intent.target}`,
+            `State        ${job.state}`,
+            `Version      ${String(job.version)}`,
+            `Selection    ${job.intent.selection.kind === "all_matching" ? "all matching results" : "explicit selected IDs"}`,
+            `Counts       ${job.complete ? "exact" : "incomplete preparation; lower bounds"}`,
+            `Matched      ${String(counts.matched)}; eligible ${String(counts.eligible)}; ineligible ${String(counts.ineligible)}`,
+            `Progress     pending ${String(counts.pending)}; running ${String(counts.running)}; succeeded ${String(counts.succeeded)}; no-op ${String(counts.noOp)}; skipped ${String(counts.skipped)}; conflicted ${String(counts.conflicted)}; failed ${String(counts.failed)}; cancelled ${String(counts.cancelled)}`,
+            ...(job.intentDigest === undefined
+                ? []
+                : [`Intent       ${job.intentDigest}`]),
+            ...(job.previewExpiresAt === undefined
+                ? []
+                : [`Confirm by   ${job.previewExpiresAt}`]),
+            ...(job.executionExpiresAt === undefined
+                ? []
+                : [`Deadline     ${job.executionExpiresAt}`]),
+            ...job.warnings.map((warning) => `Warning      ${warning}`),
+            `Billing      ${job.billing.note}`,
+            ...(job.billing.currentLimits === undefined
+                ? []
+                : [`Admission    ${JSON.stringify(job.billing.currentLimits)}`]),
+        ].join("\n"),
+    };
+}
+const preview = async (runtime, args) => {
+    const parsed = bulkPreviewRequestSchema.safeParse(await readJsonOption(runtime, "--intent", args.options["--intent"]));
+    if (!parsed.success)
+        throw new CliError("--intent must match the canonical bulk operation request", "usage", parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; "));
+    const active = await session(runtime, args);
+    const job = parseResponse("bulk.preview", await active.client.request("bulk_preview", parsed.data));
+    return {
+        ...renderJob(job),
+        nextMove: `Inspect this frozen selection: ${runtime.programName} bulk read ${job.id}; ${runtime.programName} bulk items ${job.id} --all`,
+    };
+};
+const read = async (runtime, args) => {
+    const id = jobId(runtime, args, "read");
+    const active = await session(runtime, args);
+    return renderJob(parseResponse("bulk.read", await active.client.request("bulk_read", id)));
+};
+const confirm = async (runtime, args) => {
+    const id = jobId(runtime, args, "confirm");
+    const parsed = bulkConfirmRequestSchema.safeParse({
+        intentDigest: args.options["--intent-digest"],
+        confirmed: true,
+        acknowledgeDuplicateEffects: args.booleans.has("--acknowledge-duplicate-effects"),
+    });
+    if (!parsed.success)
+        throw new CliError("Give the exact --intent-digest from bulk read", "usage");
+    const active = await session(runtime, args);
+    const current = parseResponse("bulk.read", await active.client.request("bulk_read", id));
+    if (!current.complete || current.intentDigest !== parsed.data.intentDigest)
+        throw new CliError("The job is incomplete or the intent digest differs; refresh the preview", "validation");
+    if (current.intent.operation === "retry" &&
+        !parsed.data.acknowledgeDuplicateEffects)
+        throw new CliError("Retry requires --acknowledge-duplicate-effects", "usage", "A receiver may already have acted; explicit redelivery can repeat external effects.");
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Confirm ${current.intent.operation} for frozen bulk job ${id}.`,
+        effect: [
+            `authority ${JSON.stringify(current.authority)}`,
+            `intent ${parsed.data.intentDigest}`,
+            `selection ${JSON.stringify(current.intent.selection)}`,
+            `parameters ${JSON.stringify(current.intent.parameters)}`,
+            `matched ${String(current.counts.matched)}; eligible ${String(current.counts.eligible)}; ineligible ${String(current.counts.ineligible)}`,
+            ...current.warnings,
+            "Already-sent requests cannot be recalled and ordinary quotas and per-attempt billing apply.",
+        ],
+    });
+    const key = args.options["--idempotency-key"] ??
+        `greatwait-bulk-${id}-${parsed.data.intentDigest}`;
+    runtime.stderr(`Retry key ${key}; retain it with this intent if the response is lost.\n`);
+    const job = parseResponse("bulk.confirm", await active.client.request("bulk_confirm", id, parsed.data, {
+        "Idempotency-Key": key,
+    }));
+    return {
+        ...renderJob(job),
+        data: { job, confirmation, idempotencyKey: key },
+        nextMove: `Monitor: ${runtime.programName} bulk read ${id}`,
+    };
+};
+function control(action) {
+    return async (runtime, args) => {
+        const id = jobId(runtime, args, action);
+        const raw = args.options["--expected-version"];
+        const parsed = bulkControlRequestSchema.safeParse({
+            expectedVersion: raw === undefined ? undefined : Number(raw),
+        });
+        if (!parsed.success)
+            throw new CliError("Give --expected-version from bulk read", "usage");
+        const active = await session(runtime, args);
+        const current = parseResponse("bulk.read", await active.client.request("bulk_read", id));
+        const confirmation = await confirmChange(runtime, args, {
+            action: `${action} remaining work in bulk job ${id}.`,
+            effect: [
+                `operation ${current.intent.operation}; state ${current.state}; expected version ${String(parsed.data.expectedVersion)}`,
+                "This controls the job, not selected schedules. Already-started items may finish; committed effects remain.",
+            ],
+        });
+        const job = parseResponse(`bulk.${action}`, await active.client.request(`bulk_${action}`, id, parsed.data));
+        return { ...renderJob(job), data: { job, confirmation } };
+    };
+}
+function list(items) {
+    return async (runtime, args) => {
+        const id = items ? jobId(runtime, args, "items") : undefined;
+        const active = await session(runtime, args);
+        const operation = items ? "bulk.items" : "bulk.list";
+        const state = args.options["--state"];
+        const parsed = (items ? bulkItemListRequestSchema : bulkListRequestSchema).safeParse({
+            ...pageRequest(args),
+            ...(state === undefined ? {} : { state }),
+        });
+        if (!parsed.success)
+            throw new CliError("Invalid bulk listing page or state", "usage");
+        const command = `${runtime.programName} bulk ${items ? `items ${id}` : "list"}${state === undefined ? "" : ` --state ${state}`}`;
+        const pages = await drainPages(runtime, args, pageRequest(args), async (request) => {
+            const query = { ...request, ...(state === undefined ? {} : { state }) };
+            const response = items
+                ? await active.client.request("bulk_items", id, query)
+                : await active.client.request("bulk_list", query);
+            const page = parseResponse(operation, response);
+            return { ...page, freshness: { kind: "authoritative" } };
+        });
+        const note = continuationNote(pages, command);
+        return {
+            data: {
+                rows: pages.rows,
+                pages: pages.pages,
+                ceilingReached: pages.ceilingReached,
+                ...(pages.nextCursor === undefined
+                    ? {}
+                    : { nextCursor: pages.nextCursor }),
+            },
+            human: table(items
+                ? ["STATE", "REASON", "SCHEDULE", "ITEM"]
+                : ["STATE", "OPERATION", "MATCHED", "JOB"], pages.rows.map((row) => "intent" in row
+                ? [
+                    row.state,
+                    row.intent.operation,
+                    String(row.counts.matched),
+                    row.id,
+                ]
+                : [row.state, row.reason, row.scheduleId, row.id]), items ? "No items match this page." : "No authorized bulk jobs match."),
+            ...(note === undefined ? {} : { nextMove: note }),
+        };
+    };
+}
+export const BULK_COMMANDS = {
+    "bulk preview": preview,
+    "bulk confirm": confirm,
+    "bulk read": read,
+    "bulk list": list(false),
+    "bulk items": list(true),
+    "bulk pause": control("pause"),
+    "bulk resume": control("resume"),
+    "bulk cancel": control("cancel"),
+};

package/dist/catalog.js

@@ -279,6 +279,111 @@ export const MEMBER_COMMANDS = [
     },
 ];
 export const COMMAND_CATALOG = [
+    {
+        group: "Bulk operations",
+        words: "bulk preview",
+        summary: "Prepare an exact all-matching or selected-ID preview for retry, cancel, reschedule, pause or resume.",
+        operations: ["bulk.preview"],
+        positionals: [],
+        options: [
+            API_URL,
+            {
+                flag: "--intent",
+                value: "<json|@file|->",
+                summary: "Canonical bulk request: operation, target, selection and operation-specific parameters. Preview never sends deliveries or changes schedules.",
+            },
+        ],
+    },
+    {
+        group: "Bulk operations",
+        words: "bulk confirm",
+        summary: "Confirm the exact frozen preview and start its bounded asynchronous job.",
+        operations: ["bulk.read", "bulk.confirm"],
+        confirms: true,
+        positionals: [
+            { name: "<job>", summary: "The bjo_ identity returned by bulk preview." },
+        ],
+        options: [
+            API_URL,
+            CONFIRM,
+            IDEMPOTENCY,
+            {
+                flag: "--intent-digest",
+                value: "<digest>",
+                summary: "Exact digest from the complete unexpired preview.",
+            },
+            {
+                flag: "--acknowledge-duplicate-effects",
+                summary: "Explicitly acknowledge retry's potential duplicate receiver effects; required for retry.",
+            },
+        ],
+    },
+    {
+        group: "Bulk operations",
+        words: "bulk read",
+        summary: "Read preview progress, job counts, limits, warnings and results.",
+        operations: ["bulk.read"],
+        positionals: [
+            { name: "<job>", summary: "The bjo_ identity returned by bulk preview." },
+        ],
+        options: [API_URL],
+    },
+    {
+        group: "Bulk operations",
+        words: "bulk list",
+        summary: "List authorized retained bulk jobs in this project and environment.",
+        operations: ["bulk.list"],
+        positionals: [],
+        options: [
+            API_URL,
+            ...PAGE_OPTIONS,
+            {
+                flag: "--state",
+                value: "<state>",
+                summary: "Only jobs in this lifecycle state.",
+            },
+        ],
+    },
+    {
+        group: "Bulk operations",
+        words: "bulk items",
+        summary: "Inspect every frozen target and its durable outcome.",
+        operations: ["bulk.items"],
+        positionals: [
+            { name: "<job>", summary: "The bjo_ identity returned by bulk preview." },
+        ],
+        options: [
+            API_URL,
+            ...PAGE_OPTIONS,
+            {
+                flag: "--state",
+                value: "<state>",
+                summary: "Only items in this state.",
+            },
+        ],
+    },
+    ...["pause", "resume", "cancel"].map((action) => ({
+        group: "Bulk operations",
+        words: `bulk ${action}`,
+        summary: `${action[0].toUpperCase()}${action.slice(1)} remaining bulk-job work; already-started items may finish.`,
+        operations: ["bulk.read", `bulk.${action}`],
+        confirms: true,
+        positionals: [
+            {
+                name: "<job>",
+                summary: "The bjo_ identity returned by bulk preview.",
+            },
+        ],
+        options: [
+            API_URL,
+            CONFIRM,
+            {
+                flag: "--expected-version",
+                value: "<version>",
+                summary: "Mandatory job version from bulk read; stale controls conflict.",
+            },
+        ],
+    })),
     {
         group: "Planning",
         words: "notifications show",
@@ -388,6 +493,14 @@ export const COMMAND_CATALOG = [
         summary: "Sign out, and forget the credential stored on this machine.",
         words: "logout",
     },
+    {
+        group: "Session",
+        operations: [],
+        options: [API_URL],
+        positionals: [],
+        summary: "Print the credential for the selected origin, refreshing OAuth first when needed. Output is a secret: keep it out of logs and shell tracing. --json prints token, origin and expiresAt (null for API keys).",
+        words: "token",
+    },
     {
         group: "Session",
         operations: ["context.read"],
@@ -557,6 +670,58 @@ export const COMMAND_CATALOG = [
         summary: "Find retained runs, newest first, by host identifier or tag.",
         words: "executions list",
     },
+    {
+        group: "Schedules",
+        operations: ["attempts.search"],
+        options: [
+            API_URL,
+            {
+                flag: "--started-from",
+                value: "<instant>",
+                summary: "Required UTC attempt start, inclusive (RFC 3339).",
+            },
+            {
+                flag: "--started-before",
+                value: "<instant>",
+                summary: "Required UTC attempt end, exclusive (RFC 3339).",
+            },
+            {
+                flag: "--http-status",
+                value: "<status>",
+                summary: "Only attempts with this HTTP response status, such as 503.",
+            },
+            {
+                flag: "--status-class",
+                value: "<class>",
+                summary: "Only one HTTP status class: 1xx through 5xx.",
+            },
+            {
+                flag: "--outcome",
+                value: "<outcome>",
+                summary: "The matched attempt's outcome, independently of later recovery.",
+            },
+            {
+                flag: "--diagnostic",
+                value: "<category>",
+                summary: "A classified attempt diagnostic, including transport failures without a response.",
+            },
+            {
+                flag: "--endpoint",
+                value: "<destination>",
+                summary: "Only attempts for this destination (ep_).",
+            },
+            {
+                flag: "--schedule",
+                value: "<schedule>",
+                summary: "Only attempts for this schedule (sch_).",
+            },
+            ...CORRELATION_FILTER_OPTIONS,
+            ...PAGE_OPTIONS,
+        ],
+        positionals: [],
+        summary: "Search retained attempts by actual UTC start time, including failures that later recovered.",
+        words: "attempts search",
+    },
     /* --- Schedules -------------------------------------------------------- */
     {
         group: "Schedules",
@@ -566,9 +731,29 @@ export const COMMAND_CATALOG = [
             ...CORRELATION_FILTER_OPTIONS,
             {
                 flag: "--endpoint",
-                summary: "Only the schedules that call this destination. Its id starts ep_.",
+                summary: "Only schedules that call this destination (ep_), or none for timer-only.",
                 value: "<destination>",
             },
+            {
+                flag: "--status",
+                value: "<status>",
+                summary: "Active, paused, cancelled or completed schedules.",
+            },
+            {
+                flag: "--recurrence",
+                value: "<kind>",
+                summary: "One recurrence kind: at, every or cron.",
+            },
+            {
+                flag: "--text",
+                value: "<text>",
+                summary: "Case-insensitive text in a schedule name, address or identifier.",
+            },
+            {
+                flag: "--due-before",
+                value: "<instant>",
+                summary: "Only schedules with an unsettled run before this RFC 3339 instant.",
+            },
             ...PAGE_OPTIONS,
         ],
         positionals: [],
@@ -654,6 +839,21 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                flag: "--completion",
+                value: "<response|callback>",
+                summary: "How work finishes: response or callback. Defaults to response on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--on-overlap",
+                value: "<skip|queue>",
+                summary: "When the next run is due before work finishes: skip or queue. Defaults to skip on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--delivery-timeout",
+                value: "<duration>",
+                summary: "How long the receiver may take, such as 20s or 5m (whole seconds). Defaults to 5s on create; replace keeps the stored timeout. Response completion allows up to 30m; callback completion allows up to 24h. Separate from --timeout for --wait.",
+            },
             IDEMPOTENCY,
             {
                 flag: "--wait",
@@ -736,6 +936,21 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                flag: "--completion",
+                value: "<response|callback>",
+                summary: "How work finishes: response or callback. Defaults to response on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--on-overlap",
+                value: "<skip|queue>",
+                summary: "When the next run is due before work finishes: skip or queue. Defaults to skip on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--delivery-timeout",
+                value: "<duration>",
+                summary: "Override only the receiver timeout, such as 20s or 5m (whole seconds). Keeps completion and overlap settings. Response completion allows up to 30m; existing callback completion allows up to 1d. Omit to preserve the timeout.",
+            },
             IF_MATCH,
             CONFIRM,
         ],
@@ -745,7 +960,7 @@ export const COMMAND_CATALOG = [
                 summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
             },
         ],
-        summary: "Change when a schedule runs. Its destination, data and HTTP settings stay unless you give new ones.",
+        summary: "Change when a schedule runs. Destination, data, HTTP and delivery settings stay unless you give new ones. Timing is replaced; latency class and lateness policy are re-derived; pending occurrences are discarded. A concurrent edit can refuse this change.",
         words: "schedules replace",
     },
     {

package/dist/commands.js

@@ -10,7 +10,7 @@ import { awaitRedirect, buildAuthorization, codeFrom, discover, exchangeCode, re
 import { redactSecret } from "./output.js";
 import { CliError, sleepOrAbort } from "./runtime.js";
 import { publishedWait, recoveryFor, renderJourney, STEP_COMMANDS, } from "./journey.js";
-import { anonymousClient, ENVIRONMENT_NAMES, openSession, resolveOrigin, storeFor, } from "./session.js";
+import { anonymousClient, ENVIRONMENT_NAMES, openCredential, openSession, resolveOrigin, storeFor, } from "./session.js";
 import { OPERATE_COMMANDS, destinationLines, scheduleRequest } from "./operate.js";
 import { apiUrlOption, expectNoExtraArguments, parseResponse, positionals, } from "./support.js";
 /* -------------------------------------------------------------------------- */
@@ -317,6 +317,13 @@ const CREDENTIAL_LABELS = {
     "environment-key": `an API credential from ${ENVIRONMENT_NAMES.apiKey}`,
     oauth: "an OAuth grant",
 };
+const token = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, `${runtime.programName} token [--api-url <origin>]`);
+    const { token, origin, expiresAt } = await openCredential(runtime, {
+        apiUrl: apiUrlOption(args),
+    });
+    return { human: token, data: { token, origin, expiresAt } };
+};
 const whoami = async (runtime, args) => {
     expectNoExtraArguments(args, 0, `${runtime.programName} whoami [--api-url <origin>]`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
@@ -677,6 +684,7 @@ const schedulesCreate = async (runtime, args) => {
     const schedule = created.schedule.id;
     const occurrence = created.occurrence.id;
     const data = {
+        delivery: created.schedule.delivery,
         ...(created.endpointSigningSecret === undefined
             ? {}
             : {
@@ -803,12 +811,20 @@ const schedulesRead = async (runtime, args) => {
     const answer = await session.client.requestDetailed("schedules_read", id);
     const view = responseSchemaFor("schedules.read")?.parse(answer.body);
     const etag = answer.headers["ETag"];
+    const failedOneShot = view.schedule.status === "active" &&
+        view.schedule.recurrence.kind === "at" &&
+        view.occurrence.generation === view.schedule.generation &&
+        view.occurrence.state === "terminal_failed";
     return {
         data: {
             ...(etag === undefined ? {} : { etag }),
             recurrence: view.schedule.recurrence.kind,
             schedule: view.schedule.id,
             status: view.schedule.status,
+            ...(view.schedule.delivery === undefined
+                ? {}
+                : { delivery: view.schedule.delivery }),
+            ...(failedOneShot ? { runState: view.occurrence.state } : {}),
             autoPauseAfterFailures: view.schedule.autoPauseAfterFailures,
             consecutiveFailedRuns: view.schedule.consecutiveFailedRuns,
             autoPauseReason: view.schedule.autoPauseReason,
@@ -820,7 +836,15 @@ const schedulesRead = async (runtime, args) => {
         },
         human: [
             `Schedule     ${view.schedule.id}`,
-            `Status       ${view.schedule.status}`,
+            `Status       ${failedOneShot ? "failed (schedule active)" : view.schedule.status}`,
+            ...(failedOneShot
+                ? ["Next         The only run failed. Nothing more is planned."]
+                : []),
+            ...(view.schedule.delivery === undefined
+                ? []
+                : [
+                    `Delivery     ${String(view.schedule.delivery.maxDurationSeconds)}s timeout (${view.schedule.delivery.completion}, overlap ${view.schedule.delivery.onOverlap})`,
+                ]),
             `Auto-pause   ${String(view.schedule.autoPauseAfterFailures ?? 5)}`,
             `Failed runs  ${String(view.schedule.consecutiveFailedRuns ?? 0)}`,
             ...(view.schedule.autoPauseReason == null
@@ -1036,6 +1060,7 @@ const IMPLEMENTATIONS = {
     "occurrences wait": occurrencesWait,
     "schedules create": schedulesCreate,
     "schedules read": schedulesRead,
+    token,
     whoami,
 };
 /**

package/dist/operate.d.ts

@@ -34,7 +34,7 @@ type Command = (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandRe
  * 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>>>;
+declare function scheduleRequest(runtime: CliRuntime, args: ParsedArguments, usage: string, mode?: "create" | "replace"): Promise<Readonly<Record<string, unknown>>>;
 /**
  * Where a schedule written with `--url` delivers, and where its signing
  * secret is.

package/dist/operate.js

@@ -1,5 +1,6 @@
+import { BULK_COMMANDS } from "./bulk.js";
 import { writeFile } from "node:fs/promises";
-import { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, httpRequestSchema, externalIdentifierSchema, scheduleTagsSchema, scheduleTagSchema, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRedeemRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
+import { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, deliveryDurationSecondsSchema, deliveryCompletionModeSchema, deliveryOverlapPolicySchema, scheduleRequestSchema, httpRequestSchema, externalIdentifierSchema, scheduleTagsSchema, scheduleTagSchema, scheduleSelectionSchema, normalizeScheduleSelection, projectAttemptSearchRequestSchema, normalizeAttemptSelection, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRedeemRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
 import { parseDuration } from "./args.js";
 import { confirmChange } from "./confirm.js";
 import { redactSecret } from "./output.js";
@@ -79,7 +80,7 @@ const RECURRENCE_FLAGS = ["--in", "--at", "--every", "--cron"];
  * machine's would make the same expression mean different things on a laptop
  * and on a build runner.
  */
-async function scheduleRequest(runtime, args, usage) {
+async function scheduleRequest(runtime, args, usage, mode = "create") {
     const given = RECURRENCE_FLAGS.filter((flag) => args.options[flag] !== undefined);
     if (given.length !== 1) {
         throw new CliError(given.length === 0
@@ -125,6 +126,33 @@ async function scheduleRequest(runtime, args, usage) {
         throw new CliError('--auto-pause-after-failures must be a whole number from 1 to 100, or "never"', "usage");
     const latencyClass = args.options["--latency-class"];
     const partitionKey = args.options["--partition-key"];
+    const timeoutInput = args.options["--delivery-timeout"];
+    const timeout = timeoutInput === undefined
+        ? undefined
+        : deliveryDurationSecondsSchema.safeParse(parseDuration(timeoutInput));
+    if (timeout !== undefined && !timeout.success)
+        throw new CliError("--delivery-timeout is invalid", "usage", timeout.error.issues.map((issue) => issue.message).join("; "));
+    const completionInput = args.options["--completion"];
+    const completion = completionInput === undefined
+        ? undefined
+        : deliveryCompletionModeSchema.safeParse(completionInput);
+    if (completion !== undefined && !completion.success)
+        throw new CliError('--completion (delivery.completion) must be "response" or "callback"', "usage");
+    const overlapInput = args.options["--on-overlap"];
+    const overlap = overlapInput === undefined
+        ? undefined
+        : deliveryOverlapPolicySchema.safeParse(overlapInput);
+    if (overlap !== undefined && !overlap.success)
+        throw new CliError('--on-overlap (delivery.onOverlap) must be "skip" or "queue"', "usage");
+    const delivery = {
+        ...(timeout?.success ? { maxDurationSeconds: timeout.data } : {}),
+        ...(completion?.success ? { completion: completion.data } : {}),
+        ...(overlap?.success ? { onOverlap: overlap.data } : {}),
+    };
+    // Replacement validates the resulting pair after reading the stored settings.
+    // An omitted completion there can mean a retained callback, not response.
+    if (mode === "create")
+        validateDelivery(delivery);
     const external_identifier = args.options["--external-identifier"];
     if (external_identifier !== undefined &&
         !externalIdentifierSchema.safeParse(external_identifier).success)
@@ -138,6 +166,7 @@ async function scheduleRequest(runtime, args, usage) {
         ...(external_identifier === undefined ? {} : { external_identifier }),
         ...(parsedTags?.success ? { tags: parsedTags.data } : {}),
         ...(http?.success ? { http: http.data } : {}),
+        ...(Object.keys(delivery).length === 0 ? {} : { delivery }),
         ...(endpoint === undefined ? {} : { endpoint }),
         ...(url === undefined ? {} : { url }),
         ...(latencyClass === undefined ? {} : { latencyClass }),
@@ -147,6 +176,14 @@ async function scheduleRequest(runtime, args, usage) {
         ...recurrence,
     };
 }
+/** Use the canonical contract's relation between completion and timeout. */
+function validateDelivery(delivery) {
+    const parsed = scheduleRequestSchema.safeParse({ delaySeconds: 1, delivery });
+    if (!parsed.success)
+        throw new CliError(parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; "), "usage");
+}
 /**
  * Where a schedule written with `--url` delivers, and where its signing
  * secret is.
@@ -352,16 +389,92 @@ const executionsList = async (runtime, args) => {
         row: (run) => [run.state, run.plannedFor, run.schedule, run.id],
     });
 };
+const attemptsSearch = async (runtime, args) => {
+    const from = args.options["--started-from"];
+    const before = args.options["--started-before"];
+    if (from === undefined || before === undefined)
+        throw new CliError("--started-from and --started-before are required UTC timestamps", "usage");
+    const parsed = projectAttemptSearchRequestSchema.safeParse({
+        ...correlationFilters(args),
+        startedFrom: parseInstant(from, "--started-from"),
+        startedBefore: parseInstant(before, "--started-before"),
+        responseStatus: args.options["--http-status"] === undefined
+            ? undefined
+            : Number(args.options["--http-status"]),
+        statusClass: args.options["--status-class"],
+        outcome: args.options["--outcome"],
+        diagnostic: args.options["--diagnostic"],
+        endpoint: args.options["--endpoint"],
+        schedule: args.options["--schedule"],
+    });
+    if (!parsed.success)
+        throw new CliError("The attempt filters are invalid", "usage", parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; "));
+    const active = await session(runtime, args);
+    const flags = [
+        "--started-from",
+        "--started-before",
+        "--http-status",
+        "--status-class",
+        "--outcome",
+        "--diagnostic",
+        "--endpoint",
+        "--schedule",
+    ];
+    return listing(runtime, args, {
+        columns: [
+            "STARTED (UTC)",
+            "ATTEMPT OUTCOME",
+            "HTTP / DIAGNOSTIC",
+            "RUN OUTCOME",
+            "SCHEDULE",
+            "RUN",
+            "ATTEMPT",
+        ],
+        command: `${runtime.programName} attempts search${flags.flatMap((flag) => (args.options[flag] === undefined ? [] : [` ${flag} '${args.options[flag].replaceAll("'", "'\"'\"'")}'`])).join("")}${correlationCommand(args)}`,
+        empty: "No retained attempts match these filters. Older evidence may have expired.",
+        read: (request) => page("attempts.search", () => active.client.request("attempts_search", {
+            ...normalizeAttemptSelection(parsed.data),
+            ...request,
+        })),
+        row: (result) => [
+            result.attempt.startedAt,
+            result.attempt.state ?? "in_flight",
+            result.attempt.responseStatus?.toString() ??
+                result.attempt.diagnostic ??
+                "pending",
+            result.occurrence.state,
+            result.schedule.id,
+            result.occurrence.id,
+            result.attempt.id,
+        ],
+    });
+};
 const schedulesList = async (runtime, args) => {
-    const filters = correlationFilters(args);
+    const parsed = scheduleSelectionSchema.safeParse({
+        ...correlationFilters(args),
+        endpoint: args.options["--endpoint"],
+        status: args.options["--status"],
+        recurrence: args.options["--recurrence"],
+        text: args.options["--text"],
+        dueBefore: args.options["--due-before"] === undefined
+            ? undefined
+            : parseInstant(args.options["--due-before"], "--due-before"),
+    });
+    if (!parsed.success)
+        throw new CliError("The schedule filters are invalid", "usage", parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; "));
+    const filters = normalizeScheduleSelection(parsed.data);
     const active = await session(runtime, args);
     const endpoint = args.options["--endpoint"];
     return listing(runtime, args, {
         columns: ["STATUS", "NAME", "RECURRENCE", "DELIVERS TO", "SCHEDULE"],
-        command: `${runtime.programName} schedules list${endpoint === undefined ? "" : ` --endpoint ${endpoint}`}${correlationCommand(args)}`,
+        command: `${runtime.programName} schedules list${endpoint === undefined ? "" : ` --endpoint ${endpoint}`}${correlationCommand(args)}${["--status", "--recurrence", "--text", "--due-before"].flatMap((flag) => (args.options[flag] === undefined ? [] : [` ${flag} '${args.options[flag].replaceAll("'", "'\"'\"'")}'`])).join("")}`,
         // An empty filtered page answers the filter, not the project: "no
         // schedules yet" read as the project being empty when nothing matched.
-        empty: Object.keys(filters).length > 0
+        empty: Object.keys(filters).some((key) => key !== "endpoint")
             ? "No schedule matches these filters."
             : endpoint === undefined
                 ? "This project has no schedules yet."
@@ -390,11 +503,19 @@ const schedulesList = async (runtime, args) => {
 async function scheduleChange(runtime, args, options) {
     const active = await session(runtime, args);
     let confirmation;
+    let currentView;
     if (options.confirm !== undefined) {
-        const current = parseResponse("schedules.read", await active.client.request("schedules_read", options.id)).schedule;
+        const answer = await active.client.requestDetailed("schedules_read", options.id);
+        const current = parseResponse("schedules.read", answer.body).schedule;
+        currentView = {
+            schedule: current,
+            ...(answer.headers["ETag"] === undefined
+                ? {}
+                : { etag: answer.headers["ETag"] }),
+        };
         confirmation = await confirmChange(runtime, args, options.confirm(current));
     }
-    const answer = await options.act(active, options.id);
+    const answer = await options.act(active, options.id, currentView);
     const view = parseResponse(options.operation, answer.body);
     const nextMove = options.nextMove?.(view.schedule);
     return {
@@ -424,15 +545,47 @@ async function scheduleChange(runtime, args, options) {
 const schedulesReplace = async (runtime, args) => {
     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);
+    const request = await scheduleRequest(runtime, args, usage, "replace");
     return scheduleChange(runtime, args, {
-        act: (active, scheduleId) => active.client.requestDetailed("schedules_replace", scheduleId, request, conditionalHeaders(args)),
+        act: (active, scheduleId, current) => {
+            if (current === undefined)
+                throw new CliError("Replacement needs its schedule read", "internal");
+            const delivery = {
+                ...current.schedule.delivery,
+                ...request["delivery"],
+            };
+            const changesDelivery = request["delivery"] !== undefined;
+            validateDelivery(delivery);
+            if (changesDelivery &&
+                current.schedule.endpoint === undefined &&
+                request["endpoint"] === undefined &&
+                request["url"] === undefined)
+                throw new CliError("Delivery settings need a callback destination", "usage", "Give --endpoint or --url when attaching a callback to a timer-only schedule.");
+            // The API replaces delivery settings with defaults when callback fields
+            // are supplied. Carry all stored settings, including completion/overlap.
+            // Naming the retained endpoint also makes a delivery-only change reach
+            // that callback replacement path. Fence the read against concurrent edits.
+            return active.client.requestDetailed("schedules_replace", scheduleId, {
+                ...request,
+                ...(Object.keys(delivery).length === 0 ? {} : { delivery }),
+                ...(changesDelivery &&
+                    request["endpoint"] === undefined &&
+                    request["url"] === undefined &&
+                    current.schedule.endpoint !== undefined
+                    ? { endpoint: current.schedule.endpoint }
+                    : {}),
+            }, {
+                ...(current.etag === undefined ? {} : { "If-Match": current.etag }),
+                ...conditionalHeaders(args),
+            });
+        },
         confirm: (current) => ({
             action: `Replace the definition of schedule ${current.id}.`,
             effect: [
                 `now      ${recurrenceOf(current)}, ${current.status}, version ${String(current.version)}`,
-                `after    the timing on this command line. Destination, data and HTTP`,
-                `         settings are kept unless this command line gives new ones.`,
+                `after    the timing on this command line. Destination, data, HTTP and`,
+                `         delivery settings are kept unless this command line gives new ones.`,
+                `Latency class and lateness policy are re-derived unless supplied.`,
                 `Occurrences already planned under the old definition are discarded.`,
             ],
         }),
@@ -1769,6 +1922,7 @@ function notificationPreferenceResult(settings) {
 /* -------------------------------------------------------------------------- */
 /** The operate-and-diagnose commands, keyed by the words that select them. */
 export const OPERATE_COMMANDS = {
+    ...BULK_COMMANDS,
     "notifications show": async (runtime, args) => {
         const [project] = positionals(args, ["<project>"], `${runtime.programName} notifications show <project>`);
         const active = await session(runtime, args);
@@ -1887,6 +2041,7 @@ export const OPERATE_COMMANDS = {
     "schedules cancel": schedulesCancel,
     "schedules list": schedulesList,
     "executions list": executionsList,
+    "attempts search": attemptsSearch,
     "schedules pause": schedulesPause,
     "schedules replace": schedulesReplace,
     "schedules resume": schedulesResume,

package/dist/output.js

@@ -27,6 +27,9 @@ export function renderResult(command, result, json) {
             ? `${result.human}\n`
             : `${result.human}\n\n${result.nextMove}\n`;
     }
+    // The token command is a shell credential primitive with a bare JSON shape.
+    if (command === "token")
+        return `${JSON.stringify(result.data)}\n`;
     return `${JSON.stringify({
         command,
         data: result.data,

package/dist/session.d.ts

@@ -49,9 +49,20 @@ export declare function anonymousClient(runtime: CliRuntime, origin: string): De
  * reason nothing on their machine explains. Persisting first costs one write
  * and removes the whole failure.
  */
+export interface SessionCredential {
+    readonly token: string;
+    readonly expiresAt: string | null;
+    readonly credentialKind: Session["credentialKind"];
+    readonly origin: string;
+    readonly originSource: ResolvedOrigin["source"];
+}
 export declare function openSession(runtime: CliRuntime, options: {
     readonly apiUrl?: string | undefined;
 }): Promise<Session>;
+/** Resolve the exact credential used by commands, persisting refresh before use. */
+export declare function openCredential(runtime: CliRuntime, options: {
+    readonly apiUrl?: string | undefined;
+}): Promise<SessionCredential>;
 /**
  * How long before expiry a grant is refreshed rather than presented.
  *

package/dist/session.js

@@ -69,31 +69,28 @@ export function anonymousClient(runtime, origin) {
         fetch: runtime.fetch,
     });
 }
-/**
- * An authenticated session, refreshing an expired grant on the way.
- *
- * **The rotated pair is written back before the token is used.** A refresh
- * exchange invalidates the refresh token it was given, so a process that
- * refreshed, made its call, and crashed would leave a stored refresh token the
- * service no longer honours — and the person would have to sign in again for a
- * reason nothing on their machine explains. Persisting first costs one write
- * and removes the whole failure.
- */
 export async function openSession(runtime, options) {
+    const credential = await openCredential(runtime, options);
+    return {
+        client: createGreatwaitClient({
+            baseUrl: credential.origin,
+            credential: credential.token,
+            fetch: runtime.fetch,
+        }),
+        credentialKind: credential.credentialKind,
+        origin: credential.origin,
+        originSource: credential.originSource,
+    };
+}
+/** Resolve the exact credential used by commands, persisting refresh before use. */
+export async function openCredential(runtime, options) {
     const store = storeFor(runtime);
     const resolved = await resolveOrigin(runtime, store, options.apiUrl);
-    // **The environment wins, and only for an API key.** Non-interactive
-    // automation is the case this exists for, and the journey's own variable is
-    // the one it already exports. A stored OAuth grant is a person's, and a cron
-    // job that silently used one would be acting as them.
     const fromEnvironment = runtime.env[ENVIRONMENT_NAMES.apiKey];
     if (fromEnvironment !== undefined && fromEnvironment !== "") {
         return {
-            client: createGreatwaitClient({
-                baseUrl: resolved.origin,
-                credential: fromEnvironment,
-                fetch: runtime.fetch,
-            }),
+            token: fromEnvironment,
+            expiresAt: null,
             credentialKind: "environment-key",
             origin: resolved.origin,
             originSource: resolved.source,
@@ -101,15 +98,11 @@ 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 — ${runtime.programName} 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 with ${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);
+    const secret = await presentableSecret(runtime, store, resolved.origin, stored);
     return {
-        client: createGreatwaitClient({
-            baseUrl: resolved.origin,
-            credential,
-            fetch: runtime.fetch,
-        }),
+        ...secret,
         credentialKind: stored.kind,
         origin: resolved.origin,
         originSource: resolved.source,
@@ -132,26 +125,35 @@ async function presentableSecret(runtime, store, origin, stored) {
         if (stored.secret === undefined) {
             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;
+        return { token: stored.secret, expiresAt: null };
     }
     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: ${runtime.programName} login --api-url ${origin}`);
     }
     if (expiresAtMs === undefined ||
-        expiresAtMs - REFRESH_MARGIN_MS > runtime.now() ||
-        refreshToken === undefined) {
-        return accessToken;
+        expiresAtMs - REFRESH_MARGIN_MS > runtime.now()) {
+        return {
+            token: accessToken,
+            expiresAt: expiresAtMs === undefined ? null : new Date(expiresAtMs).toISOString(),
+        };
+    }
+    if (refreshToken === undefined) {
+        throw new CliError(`the stored grant for ${origin} needs refreshing but carries no refresh token`, "authentication", `Sign in with ${runtime.programName} login --api-url ${origin}`);
     }
     const server = await discover(runtime, origin);
     const rotated = await refresh(runtime, server, { clientId, refreshToken });
+    const refreshedExpiresAtMs = runtime.now() + rotated.expiresInSeconds * 1000;
     await store.write(origin, {
         accessToken: rotated.accessToken,
         clientId,
-        expiresAtMs: runtime.now() + rotated.expiresInSeconds * 1000,
+        expiresAtMs: refreshedExpiresAtMs,
         kind: "oauth",
         refreshToken: rotated.refreshToken,
         scope: rotated.scope,
     });
-    return rotated.accessToken;
+    return {
+        token: rotated.accessToken,
+        expiresAt: new Date(refreshedExpiresAtMs).toISOString(),
+    };
 }

package/package.json

@@ -7,8 +7,8 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.2.3",
-    "@greatwait/contracts": "0.2.3"
+    "@greatwait/api-client": "0.3.1",
+    "@greatwait/contracts": "0.3.1"
   },
   "description": "The GreatWait command line: sign in, schedule a call to a URL, and read its delivery outcome over the public API.",
   "engines": {
@@ -48,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.2.3"
+  "version": "0.3.1"
 }