@greatwait/cli 0.2.3 → 0.3.0

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",
@@ -557,6 +662,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 +723,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 +831,11 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                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; longer needs existing callback completion. Separate from --timeout for --wait.",
+            },
             IDEMPOTENCY,
             {
                 flag: "--wait",
@@ -736,6 +918,11 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                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 +932,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

@@ -803,12 +803,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 +828,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

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, 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";
@@ -125,6 +126,12 @@ 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 external_identifier = args.options["--external-identifier"];
     if (external_identifier !== undefined &&
         !externalIdentifierSchema.safeParse(external_identifier).success)
@@ -138,6 +145,9 @@ async function scheduleRequest(runtime, args, usage) {
         ...(external_identifier === undefined ? {} : { external_identifier }),
         ...(parsedTags?.success ? { tags: parsedTags.data } : {}),
         ...(http?.success ? { http: http.data } : {}),
+        ...(timeout?.success
+            ? { delivery: { maxDurationSeconds: timeout.data } }
+            : {}),
         ...(endpoint === undefined ? {} : { endpoint }),
         ...(url === undefined ? {} : { url }),
         ...(latencyClass === undefined ? {} : { latencyClass }),
@@ -352,16 +362,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 +476,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 {
@@ -426,13 +520,50 @@ const schedulesReplace = async (runtime, args) => {
     const [id] = positionals(args, ["<schedule>"], usage);
     const request = await scheduleRequest(runtime, args, usage);
     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;
+            const timeout = args.options["--delivery-timeout"];
+            if (timeout !== undefined &&
+                current.schedule.endpoint === undefined &&
+                request["endpoint"] === undefined &&
+                request["url"] === undefined)
+                throw new CliError("--delivery-timeout needs 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 timeout-only change reach
+            // that callback replacement path. Fence the read against concurrent edits.
+            return active.client.requestDetailed("schedules_replace", scheduleId, {
+                ...request,
+                ...(delivery === undefined
+                    ? {}
+                    : {
+                        delivery: {
+                            ...delivery,
+                            ...(timeout === undefined
+                                ? {}
+                                : { maxDurationSeconds: parseDuration(timeout) }),
+                        },
+                    }),
+                ...(timeout !== undefined &&
+                    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 +1900,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 +2019,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/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.0",
+    "@greatwait/contracts": "0.3.0"
   },
   "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.0"
 }