@ttctl/cli 0.0.0 → 0.1.0-rc.2

package/dist/commands/timesheet/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/commands/timesheet/shared.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAoB,EAAE,GAAY,EAAE,SAAuB,QAAQ;IACtG,iBAAiB,CAAC,YAAY,EAAE,GAAG,EAAE,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAC/F,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,IAAkC;IAC9D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,WAAW;YACd,OAAO,2EAA2E,CAAC;QACrF,KAAK,eAAe;YAClB,OAAO,kGAAkG,CAAC;QAC5G,KAAK,kBAAkB;YACrB,OAAO,2GAA2G,CAAC;QACrH,KAAK,yBAAyB;YAC5B,OAAO,2IAA2I,CAAC;QACrJ,KAAK,gBAAgB;YACnB,OAAO,6JAA6J,CAAC;QACvK;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/commands/timesheet/show.d.ts

@@ -0,0 +1,19 @@
+import { timesheet } from "@ttctl/core";
+import type { OutputFormat } from "../../lib/output.js";
+/**
+ * Action handler for `ttctl timesheet show <id>`. `<id>` is the
+ * BillingCycle.id from `ttctl timesheet list`.
+ *
+ * Pretty rendering is a multi-line key:value layout grouped into
+ * sections (Header, Engagement, Submission, Agreement, Records). Empty
+ * sections are omitted. `json` / `yaml` always emit the full server
+ * payload (including `timesheetUrl`, `actualAgreement`, the full
+ * records array, etc.).
+ */
+export declare function runTimesheetShow(id: string, output: OutputFormat): Promise<void>;
+/**
+ * Render the timesheet detail as a sectioned multi-line block. Pure —
+ * directly unit-testable.
+ */
+export declare function formatTimesheetDetail(item: timesheet.TimesheetDetail): string;
+//# sourceMappingURL=show.d.ts.map

package/dist/commands/timesheet/show.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.d.ts","sourceRoot":"","sources":["../../../src/commands/timesheet/show.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAatF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,CAAC,eAAe,GAAG,MAAM,CAgF7E"}

package/dist/commands/timesheet/show.js

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { timesheet } from "@ttctl/core";
+import { emitResult } from "../../lib/output.js";
+import { handleTimesheetError, loadAuthTokenOrExit } from "./shared.js";
+/**
+ * Action handler for `ttctl timesheet show <id>`. `<id>` is the
+ * BillingCycle.id from `ttctl timesheet list`.
+ *
+ * Pretty rendering is a multi-line key:value layout grouped into
+ * sections (Header, Engagement, Submission, Agreement, Records). Empty
+ * sections are omitted. `json` / `yaml` always emit the full server
+ * payload (including `timesheetUrl`, `actualAgreement`, the full
+ * records array, etc.).
+ */
+export async function runTimesheetShow(id, output) {
+    const token = await loadAuthTokenOrExit("timesheet show", output);
+    let item;
+    try {
+        item = await timesheet.show(token, id);
+    }
+    catch (err) {
+        handleTimesheetError("timesheet show", err, output);
+    }
+    emitResult(item, output, {
+        pretty: (data) => formatTimesheetDetail(data),
+    });
+}
+/**
+ * Render the timesheet detail as a sectioned multi-line block. Pure —
+ * directly unit-testable.
+ */
+export function formatTimesheetDetail(item) {
+    const lines = [];
+    lines.push(`Timesheet ${item.id}`);
+    lines.push(`  Week: ${item.startDate} → ${item.endDate}`);
+    lines.push(`  Hours: ${item.hours}`);
+    lines.push(`  Submitted: ${String(item.timesheetSubmitted)}`);
+    lines.push(`  Overdue: ${String(item.timesheetOverdue)}`);
+    if (item.timesheetSubmissionOpenDatetime !== null) {
+        lines.push(`  Submission opens: ${item.timesheetSubmissionOpenDatetime}`);
+    }
+    if (item.timesheetSubmissionDeadlineDatetime !== null) {
+        lines.push(`  Submission deadline: ${item.timesheetSubmissionDeadlineDatetime}`);
+    }
+    if (item.timesheetUrl !== null) {
+        lines.push(`  URL: ${item.timesheetUrl}`);
+    }
+    lines.push("");
+    lines.push("Engagement");
+    if (item.engagement.job.title !== null)
+        lines.push(`  ${item.engagement.job.title}`);
+    if (item.engagement.job.client?.fullName != null) {
+        lines.push(`  Client: ${item.engagement.job.client.fullName}`);
+    }
+    // Note: this is `Engagement.id` (TalentEngagement), NOT `JobActivityItem.id`.
+    // The `--engagement <id>` flag on `timesheet list/submit` consumes the
+    // `JobActivityItem.id` surfaced by `engagements list`, which is a
+    // distinct identifier — we name the field verbosely here so users don't
+    // copy-paste this id back into `--engagement` and get a NOT_FOUND.
+    lines.push(`  TalentEngagement id: ${item.engagement.id}`);
+    if (item.engagement.expectedHours !== null) {
+        lines.push(`  Expected hours: ${item.engagement.expectedHours.toString()}`);
+    }
+    if (item.minimumCommitment !== null && item.minimumCommitment.applicable) {
+        lines.push("");
+        lines.push("Minimum commitment");
+        if (item.minimumCommitment.minimumHours !== null) {
+            lines.push(`  Minimum hours: ${item.minimumCommitment.minimumHours.toString()}`);
+        }
+    }
+    if (item.actualAgreement !== null) {
+        lines.push("");
+        lines.push("Agreement");
+        if (item.actualAgreement.applicationRate !== null) {
+            lines.push(`  Application rate: ${item.actualAgreement.applicationRate}`);
+        }
+        if (item.actualAgreement.talentHourlyRate !== null) {
+            lines.push(`  Hourly rate: ${item.actualAgreement.talentHourlyRate}`);
+        }
+        if (item.actualAgreement.marketplaceMargin !== null) {
+            lines.push(`  Marketplace margin: ${item.actualAgreement.marketplaceMargin}`);
+        }
+    }
+    if (item.timesheetComment !== null && item.timesheetComment !== "") {
+        lines.push("");
+        lines.push("Comment");
+        for (const para of item.timesheetComment.split(/\n+/)) {
+            if (para.trim().length > 0)
+                lines.push(`  ${para}`);
+        }
+    }
+    if (item.timesheetRecords.length > 0) {
+        lines.push("");
+        lines.push(`Records (${item.timesheetRecords.length.toString()})`);
+        for (const rec of item.timesheetRecords) {
+            // `duration` is a string-encoded decimal in minutes (e.g., "480.0"
+            // for an 8-hour day). `Number()` parses "480.0" → 480; division by
+            // 60 yields hours. Pre-#???: this divided by 3600 assuming
+            // number-typed seconds, rendering 8h as 0.13h.
+            const hours = (Number(rec.duration) / 60).toFixed(2);
+            const tag = rec.isDayOff ? " [day off]" : "";
+            const note = rec.note != null && rec.note !== "" ? ` — ${rec.note}` : "";
+            lines.push(`  ${rec.date}: ${hours}h${tag}${note}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=show.js.map

package/dist/commands/timesheet/show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.js","sourceRoot":"","sources":["../../../src/commands/timesheet/show.ts"],"names":[],"mappings":"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"}

package/dist/commands/timesheet/submit.d.ts

@@ -0,0 +1,50 @@
+import type { OutputFormat } from "../../lib/output.js";
+/**
+ * Action handler for `ttctl timesheet submit [id]`.
+ *
+ * Per #13 spec, submit is destructive (one-way on the wire). The
+ * action is gated behind one of:
+ *
+ *   - `--confirm` flag (script-safe, no prompt)
+ *   - Interactive TTY confirm via `@clack/prompts` (non-TTY without
+ *     `--confirm` refuses with a clear error envelope)
+ *
+ * `<id>` is a positional BillingCycle.id. When omitted, the runner
+ * calls {@link timesheet.resolveCurrentCycle} to auto-resolve the
+ * single cycle whose submission window contains "now". Optional
+ * `--engagement <id>` scopes the resolve to one engagement (uses the
+ * `JobActivityItem.id` from `engagements list`).
+ *
+ * Auto-resolve outcomes:
+ *
+ *   - `kind: "found"`     → proceed to confirm + submit
+ *   - `kind: "none"`      → error envelope with code `NO_CURRENT_CYCLE`
+ *   - `kind: "multiple"`  → error envelope with code
+ *                            `MULTIPLE_CURRENT_CYCLES` listing candidate
+ *                            ids in `errors[0].hint` so scripts can
+ *                            disambiguate.
+ *
+ * Success returns the write-success envelope per #128:
+ * `{ok: true, version: "1.0", operation: "timesheet.submit", updated: <detail>}`.
+ *
+ * Dry-run path: when `getCliDryRun()` is true (the CLI-global
+ * `--dry-run` flag was passed), the destructive mutation is replaced
+ * by a {@link DryRunPreview}. The confirm gate AND the auto-resolve
+ * read are BOTH skipped — auto-resolve uses the placeholder string
+ * `<auto-resolved-at-apply-time>` for the id, surfaced via the
+ * envelope `notice` so machine consumers don't mistake it for a real
+ * cycle id. See {@link DRY_RUN_PLACEHOLDER_NOTICE}.
+ */
+export interface TimesheetSubmitOptions {
+    confirm: boolean;
+    engagement?: string;
+    output: OutputFormat;
+}
+/**
+ * Internal seam: `runTimesheetSubmit` decides whether to prompt based
+ * on a deterministic predicate. Exported via `isStdinTty` so tests can
+ * stub it cleanly without poking `process.stdin.isTTY`.
+ */
+export declare function isStdinTty(): boolean;
+export declare function runTimesheetSubmit(id: string | undefined, opts: TimesheetSubmitOptions): Promise<void>;
+//# sourceMappingURL=submit.d.ts.map

package/dist/commands/timesheet/submit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../../src/commands/timesheet/submit.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB;AAYD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+H5G"}

package/dist/commands/timesheet/submit.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import * as p from "@clack/prompts";
+import { timesheet } from "@ttctl/core";
+import { getCliDryRun } from "../../lib/dry-run.js";
+import { emitDryRunSuccess, emitErrorAndExit, emitUpdateSuccess } from "../../lib/envelopes.js";
+import { handleTimesheetError, loadAuthTokenOrExit } from "./shared.js";
+import { formatTimesheetDetail } from "./show.js";
+/**
+ * Notice surfaced on the dry-run envelope when the caller omitted the
+ * positional `<id>` AND the apply path would have auto-resolved the
+ * current cycle. The preview's `variables.id` carries the placeholder
+ * string `<auto-resolved-at-apply-time>`; the real BillingCycle.id is
+ * resolved at apply time via `PendingTimesheets` (skipped on dry-run).
+ */
+const DRY_RUN_PLACEHOLDER_NOTICE = "id in the preview is the placeholder string `<auto-resolved-at-apply-time>`; the apply path resolves the real BillingCycle.id via a PendingTimesheets query before issuing the mutation — this read is skipped on dry-run.";
+/**
+ * Internal seam: `runTimesheetSubmit` decides whether to prompt based
+ * on a deterministic predicate. Exported via `isStdinTty` so tests can
+ * stub it cleanly without poking `process.stdin.isTTY`.
+ */
+export function isStdinTty() {
+    return process.stdin.isTTY === true;
+}
+export async function runTimesheetSubmit(id, opts) {
+    const token = await loadAuthTokenOrExit("timesheet submit", opts.output);
+    const dryRun = getCliDryRun();
+    // Step 1: resolve the cycle id (explicit positional OR auto-resolve).
+    // Dry-run path: skip the auto-resolve read entirely and stamp the
+    // placeholder. The destructive mutation is never sent.
+    let cycleId;
+    let usedPlaceholder = false;
+    if (id !== undefined) {
+        cycleId = id;
+    }
+    else if (dryRun) {
+        cycleId = "<auto-resolved-at-apply-time>";
+        usedPlaceholder = true;
+    }
+    else {
+        const resolveOpts = {};
+        if (opts.engagement !== undefined)
+            resolveOpts.engagement = opts.engagement;
+        let resolution;
+        try {
+            resolution = await timesheet.resolveCurrentCycle(token, resolveOpts);
+        }
+        catch (err) {
+            handleTimesheetError("timesheet submit", err, opts.output);
+        }
+        if (resolution.kind === "none") {
+            emitErrorAndExit({
+                operation: "timesheet.submit",
+                format: opts.output,
+                errors: [
+                    {
+                        code: "NO_CURRENT_CYCLE",
+                        message: "No billing cycle is currently in its submission window. Either nothing is due, or every pending cycle is too early / past deadline.",
+                        hint: "Run `ttctl timesheet list` to see what's pending, or specify a cycle id explicitly.",
+                    },
+                ],
+                prettySummary: "timesheet submit failed (NO_CURRENT_CYCLE): no current pending timesheet.",
+            });
+        }
+        if (resolution.kind === "multiple") {
+            const candidateLines = resolution.candidates.map((c) => {
+                const client = c.engagement.job.client?.fullName ?? "(no client)";
+                const title = c.engagement.job.title ?? "(untitled)";
+                return `  - ${c.id} (${client} — ${title}, ${c.startDate} → ${c.endDate})`;
+            });
+            emitErrorAndExit({
+                operation: "timesheet.submit",
+                format: opts.output,
+                errors: [
+                    {
+                        code: "MULTIPLE_CURRENT_CYCLES",
+                        message: `${resolution.candidates.length.toString()} billing cycles match the current submission window — specify one explicitly.`,
+                        hint: `Candidates:\n${candidateLines.join("\n")}`,
+                    },
+                ],
+                prettySummary: `timesheet submit failed (MULTIPLE_CURRENT_CYCLES): ${resolution.candidates.length.toString()} candidates.`,
+            });
+        }
+        cycleId = resolution.cycle.id;
+    }
+    // Step 2: --confirm OR interactive TTY confirm gate.
+    // Dry-run path: skip the confirm gate entirely — there's nothing
+    // destructive to confirm. The preview is emitted regardless of
+    // --confirm / stdin TTY-ness.
+    if (!dryRun && !opts.confirm) {
+        if (!isStdinTty()) {
+            emitErrorAndExit({
+                operation: "timesheet.submit",
+                format: opts.output,
+                errors: [
+                    {
+                        code: "CONFIRMATION_REQUIRED",
+                        message: "timesheet submit is destructive (one-way) and requires explicit confirmation. Pass --confirm or run in an interactive terminal.",
+                        hint: "Add `--confirm` to the command, or run `ttctl timesheet submit` from a TTY.",
+                    },
+                ],
+                prettySummary: "timesheet submit refused: --confirm flag required (non-TTY stdin).",
+            });
+        }
+        const proceed = await p.confirm({
+            message: `Submit timesheet ${cycleId}? This is one-way and cannot be undone.`,
+            initialValue: false,
+        });
+        if (p.isCancel(proceed) || !proceed) {
+            emitErrorAndExit({
+                operation: "timesheet.submit",
+                format: opts.output,
+                errors: [
+                    {
+                        code: "CONFIRMATION_DECLINED",
+                        message: "Submission cancelled by user.",
+                    },
+                ],
+                prettySummary: "timesheet submit cancelled by user.",
+                exitCode: 1,
+            });
+        }
+    }
+    // Step 3: perform the submission (or build the dry-run preview).
+    let outcome;
+    try {
+        outcome = await timesheet.submit(token, cycleId, { dryRun });
+    }
+    catch (err) {
+        handleTimesheetError("timesheet submit", err, opts.output);
+    }
+    // Step 4: branch on outcome — dry-run preview OR apply-path envelope.
+    if (outcome.kind === "preview") {
+        emitDryRunSuccess({
+            operation: "timesheet.submit",
+            format: opts.output,
+            preview: outcome.preview,
+            ...(usedPlaceholder ? { notice: DRY_RUN_PLACEHOLDER_NOTICE } : {}),
+        });
+        return;
+    }
+    const { result: updated } = outcome;
+    emitUpdateSuccess({
+        operation: "timesheet.submit",
+        format: opts.output,
+        updated,
+        prettySummary: `timesheet ${updated.id} submitted (${updated.startDate} → ${updated.endDate}, ${updated.hours}h)`,
+        prettyEntity: (entity) => formatTimesheetDetail(entity),
+    });
+}
+//# sourceMappingURL=submit.js.map

package/dist/commands/timesheet/submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.js","sourceRoot":"","sources":["../../../src/commands/timesheet/submit.ts"],"names":[],"mappings":"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"}

package/dist/crash-handlers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Discriminator for the two top-level crash paths Node.js exposes.
+ * `uncaughtException` fires for synchronous throws that escape every
+ * try/catch frame; `unhandledRejection` fires for rejected promises with
+ * no `.catch()` or `await` upstream. Both are terminal — the process
+ * is exiting; the only question is whether the crash output leaks an
+ * in-memory secret on the way out.
+ */
+export type CrashKind = "uncaughtException" | "unhandledRejection";
+/**
+ * Build the redacted crash log for an uncaught throw or unhandled
+ * promise rejection. Returns a multi-line string suitable for stderr.
+ *
+ * Wire shape:
+ *
+ *     [<kind>] <ErrorName>: <message>
+ *     <stack>
+ *
+ * For non-`Error` rejections (`reject("string")`, `reject(42)`,
+ * `reject(undefined)`), the name falls back to `UnknownError` and the
+ * message is `String(reason)`; there is no stack.
+ *
+ * **Redaction**: the assembled string is run through {@link redactString}
+ * from `@ttctl/core`, replacing every canonical Toptal session bearer
+ * (`user_<24hex>_<20alnum>`) with `***REDACTED***`. The crash log
+ * intentionally does NOT include `process.env`, command-line arguments,
+ * or any other ambient runtime state — those are the load-bearing
+ * defenses against process-environment leakage (env vars carrying
+ * 1Password session tokens, shell history hints, etc.). Bearer
+ * scrubbing is defense-in-depth for the case where a thrown error's
+ * message or stack frame interpolates a captured bearer.
+ *
+ * Pure — no I/O, no process state mutation.
+ *
+ * See `SECURITY.md` § Crash-output secret invariant for the
+ * cross-cutting contract this function satisfies.
+ */
+export declare function formatCrashLog(err: unknown, kind: CrashKind): string;
+/**
+ * Install global crash handlers for `uncaughtException` and
+ * `unhandledRejection` (issue #207). Each handler:
+ *
+ * 1. Formats the throw via {@link formatCrashLog} (bearer-pattern
+ *    scrubbed via `@ttctl/core` `redactString`).
+ * 2. Writes the formatted block to `process.stderr` — never `stdout`
+ *    (the data channel `-o json` / `-o yaml` is owned by command
+ *    handlers and must remain uncontaminated even on crash).
+ * 3. Exits with code `1` (non-zero — generic error).
+ *
+ * Handlers do NOT log `process.env`, `process.argv`, or any other
+ * ambient runtime state; those would risk dumping shell-history hints,
+ * 1Password session env vars (`OP_SESSION_*`), and other secrets that
+ * tested crash-output assertions cannot catch from the application
+ * side.
+ *
+ * The umbrella bin (`packages/ttctl/src/cli.ts`) calls this once at
+ * startup before invoking `main()`. Calling twice would register two
+ * listeners for each event — Node.js permits this but it doubles the
+ * stderr output, so callers should treat this as a startup-only API.
+ *
+ * Exit channel: writers use `process.stderr.write` directly rather
+ * than `console.error` because the latter can be redirected by
+ * downstream test infrastructure in surprising ways. `stderr.write` is
+ * the most direct path to the parent process's standard-error stream.
+ */
+export declare function installCrashHandlers(): void;
+//# sourceMappingURL=crash-handlers.d.ts.map

package/dist/crash-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-handlers.d.ts","sourceRoot":"","sources":["../src/crash-handlers.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAQpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAS3C"}

package/dist/crash-handlers.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { redactString } from "@ttctl/core";
+/**
+ * Build the redacted crash log for an uncaught throw or unhandled
+ * promise rejection. Returns a multi-line string suitable for stderr.
+ *
+ * Wire shape:
+ *
+ *     [<kind>] <ErrorName>: <message>
+ *     <stack>
+ *
+ * For non-`Error` rejections (`reject("string")`, `reject(42)`,
+ * `reject(undefined)`), the name falls back to `UnknownError` and the
+ * message is `String(reason)`; there is no stack.
+ *
+ * **Redaction**: the assembled string is run through {@link redactString}
+ * from `@ttctl/core`, replacing every canonical Toptal session bearer
+ * (`user_<24hex>_<20alnum>`) with `***REDACTED***`. The crash log
+ * intentionally does NOT include `process.env`, command-line arguments,
+ * or any other ambient runtime state — those are the load-bearing
+ * defenses against process-environment leakage (env vars carrying
+ * 1Password session tokens, shell history hints, etc.). Bearer
+ * scrubbing is defense-in-depth for the case where a thrown error's
+ * message or stack frame interpolates a captured bearer.
+ *
+ * Pure — no I/O, no process state mutation.
+ *
+ * See `SECURITY.md` § Crash-output secret invariant for the
+ * cross-cutting contract this function satisfies.
+ */
+export function formatCrashLog(err, kind) {
+    const isError = err instanceof Error;
+    const name = isError ? err.name : "UnknownError";
+    const message = isError ? err.message : String(err);
+    const stack = isError && err.stack !== undefined && err.stack !== "" ? err.stack : undefined;
+    const head = `[${kind}] ${name}: ${message}`;
+    const body = stack !== undefined ? `${head}\n${stack}` : head;
+    return redactString(body);
+}
+/**
+ * Install global crash handlers for `uncaughtException` and
+ * `unhandledRejection` (issue #207). Each handler:
+ *
+ * 1. Formats the throw via {@link formatCrashLog} (bearer-pattern
+ *    scrubbed via `@ttctl/core` `redactString`).
+ * 2. Writes the formatted block to `process.stderr` — never `stdout`
+ *    (the data channel `-o json` / `-o yaml` is owned by command
+ *    handlers and must remain uncontaminated even on crash).
+ * 3. Exits with code `1` (non-zero — generic error).
+ *
+ * Handlers do NOT log `process.env`, `process.argv`, or any other
+ * ambient runtime state; those would risk dumping shell-history hints,
+ * 1Password session env vars (`OP_SESSION_*`), and other secrets that
+ * tested crash-output assertions cannot catch from the application
+ * side.
+ *
+ * The umbrella bin (`packages/ttctl/src/cli.ts`) calls this once at
+ * startup before invoking `main()`. Calling twice would register two
+ * listeners for each event — Node.js permits this but it doubles the
+ * stderr output, so callers should treat this as a startup-only API.
+ *
+ * Exit channel: writers use `process.stderr.write` directly rather
+ * than `console.error` because the latter can be redirected by
+ * downstream test infrastructure in surprising ways. `stderr.write` is
+ * the most direct path to the parent process's standard-error stream.
+ */
+export function installCrashHandlers() {
+    process.on("uncaughtException", (err) => {
+        process.stderr.write(formatCrashLog(err, "uncaughtException") + "\n");
+        process.exit(1);
+    });
+    process.on("unhandledRejection", (reason) => {
+        process.stderr.write(formatCrashLog(reason, "unhandledRejection") + "\n");
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=crash-handlers.js.map

package/dist/crash-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-handlers.js","sourceRoot":"","sources":["../src/crash-handlers.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,IAAe;IAC1D,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,OAAO,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7F,MAAM,IAAI,GAAG,IAAI,IAAI,KAAK,IAAI,KAAK,OAAO,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAU,EAAE,EAAE;QAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,EAAE,mBAAmB,CAAC,GAAG,IAAI,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAe,EAAE,EAAE;QACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+import { TtctlError } from "@ttctl/core";
+/**
+ * CLI presentation contract for `TtctlError` subclasses (issue #77).
+ *
+ * The CLI surface renders any `TtctlError` in a uniform multi-block format
+ * so users see the same shape whether the failure was an auth revocation,
+ * a Cloudflare 403, or a (post-v1) scheduler-bearer expiry:
+ *
+ *     Error: <error.message>
+ *
+ *     Recovery: <error.recovery>
+ *
+ *     (Code: <error.code>)
+ *
+ * `error.message` may be multi-line (e.g. `Cf403Error.formatMessage`
+ * produces a 3-paragraph walkthrough); the renderer passes it through
+ * verbatim. `recovery` is one short imperative sentence. `code` is a
+ * stable machine-readable token script consumers can branch on without
+ * parsing prose.
+ *
+ * Pure function — no I/O. Callers route the result to `process.stderr` and
+ * choose an exit code via `exitCodeForTtctlError`.
+ */
+export declare function formatTtctlErrorMessage(err: TtctlError): string;
+/**
+ * Map a `TtctlError` to a process exit code.
+ *
+ * Default is `1` (general error — auth revoked, Cloudflare clearance
+ * expired, etc.). The 1 / 2 split mirrors the existing `auth status`
+ * convention (1 = auth-related, 2 = transient/retryable). `Cf403*` codes
+ * map to `2` because they are transport-level blocks the user cannot fix
+ * by re-authenticating.
+ */
+export declare function exitCodeForTtctlError(err: TtctlError): number;
+/**
+ * Side-effecting renderer: write the formatted block to `process.stderr`
+ * and `process.exit` with the corresponding code. Never returns.
+ *
+ * Command handlers gate this with `instanceof TtctlError` so the uniform
+ * presentation only applies to typed-hierarchy errors — other domain
+ * errors (`ProfileError`, `SignInError`, …) keep their existing
+ * command-specific "(CODE): message" rendering.
+ */
+export declare function presentTtctlError(err: TtctlError): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAK7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,KAAK,CAGxD"}

package/dist/errors.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { TtctlError } from "@ttctl/core";
+/**
+ * CLI presentation contract for `TtctlError` subclasses (issue #77).
+ *
+ * The CLI surface renders any `TtctlError` in a uniform multi-block format
+ * so users see the same shape whether the failure was an auth revocation,
+ * a Cloudflare 403, or a (post-v1) scheduler-bearer expiry:
+ *
+ *     Error: <error.message>
+ *
+ *     Recovery: <error.recovery>
+ *
+ *     (Code: <error.code>)
+ *
+ * `error.message` may be multi-line (e.g. `Cf403Error.formatMessage`
+ * produces a 3-paragraph walkthrough); the renderer passes it through
+ * verbatim. `recovery` is one short imperative sentence. `code` is a
+ * stable machine-readable token script consumers can branch on without
+ * parsing prose.
+ *
+ * Pure function — no I/O. Callers route the result to `process.stderr` and
+ * choose an exit code via `exitCodeForTtctlError`.
+ */
+export function formatTtctlErrorMessage(err) {
+    return [`Error: ${err.message}`, "", `Recovery: ${err.recovery}`, "", `(Code: ${err.code})`].join("\n");
+}
+/**
+ * Map a `TtctlError` to a process exit code.
+ *
+ * Default is `1` (general error — auth revoked, Cloudflare clearance
+ * expired, etc.). The 1 / 2 split mirrors the existing `auth status`
+ * convention (1 = auth-related, 2 = transient/retryable). `Cf403*` codes
+ * map to `2` because they are transport-level blocks the user cannot fix
+ * by re-authenticating.
+ */
+export function exitCodeForTtctlError(err) {
+    if (err.code === "CF_403_CLEARANCE" || err.code === "CF_403_PERSISTENT") {
+        return 2;
+    }
+    return 1;
+}
+/**
+ * Side-effecting renderer: write the formatted block to `process.stderr`
+ * and `process.exit` with the corresponding code. Never returns.
+ *
+ * Command handlers gate this with `instanceof TtctlError` so the uniform
+ * presentation only applies to typed-hierarchy errors — other domain
+ * errors (`ProfileError`, `SignInError`, …) keep their existing
+ * command-specific "(CODE): message" rendering.
+ */
+export function presentTtctlError(err) {
+    process.stderr.write(formatTtctlErrorMessage(err) + "\n");
+    process.exit(exitCodeForTtctlError(err));
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAe;IACrD,OAAO,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,aAAa,GAAG,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,UAAU,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1G,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAe;IACnD,IAAI,GAAG,CAAC,IAAI,KAAK,kBAAkB,IAAI,GAAG,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;QACxE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAe;IAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { buildProgram } from "./program.js";
+export { exitCodeForTtctlError, formatTtctlErrorMessage, presentTtctlError } from "./errors.js";
+export { formatCrashLog, installCrashHandlers } from "./crash-handlers.js";
+export type { CrashKind } from "./crash-handlers.js";
+export { TtctlError } from "@ttctl/core";
+export { ConfigError } from "@ttctl/core";
+export type { ConfigErrorCode } from "@ttctl/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAMzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}