@ttctl/cli 0.0.0 → 0.1.0-rc.2

package/dist/lib/kill-switch-hook.d.ts

@@ -0,0 +1,49 @@
+/**
+ * CLI-side wire-up for the remote version-killed manifest (#312).
+ *
+ * Invoked from the root program's `preAction` hook (see `program.ts`).
+ * Per AC 3:
+ *   - Fetches the manifest at startup (synchronous-await, up to 3s).
+ *   - Warns on match (stderr).
+ *   - Refuses (exit non-zero) when `entry.action === "refuse"`.
+ *   - Never blocks on fetch failure — fail-silent contract.
+ *
+ * The running version is resolved via `readPackageVersion(import.meta.url)`
+ * from this module's location, which points at
+ * `packages/cli/package.json` post-build. All workspace packages are
+ * stamped to the same version at release time
+ * (`pnpm -r exec npm version` in `.github/workflows/release.yml`), so
+ * either the cli or the umbrella package's version is correct.
+ *
+ * Why synchronous (not fire-and-forget): the CLI is a short-lived
+ * process. If the warning is printed asynchronously after the action's
+ * output, it risks getting buried or missed. Synchronous-await before
+ * the action runs ensures the warning is the first thing the user sees
+ * when their version is flagged. Worst-case 3s latency (timeout cap);
+ * typical 50-200ms against raw.githubusercontent.com.
+ *
+ * Exposed as a separate `preAction` hook (rather than mixed into the
+ * existing one) so the existing hook stays sync — Commander runs
+ * registered hooks in order, so the sync hook fires first (diagnostic
+ * logger, dry-run capture, format mutex), then this async one.
+ *
+ * `exit` is parameterised for testability — production callers omit it
+ * (defaults to `process.exit`); tests inject a spy that throws instead
+ * of terminating the test runner.
+ */
+export interface KillSwitchHookOptions {
+    /** Override for `process.exit`. Defaults to the real exit (refuse path). */
+    exit?: (code: number) => never;
+    /** Override for stderr writer. Defaults to `process.stderr.write`. */
+    writeStderr?: (chunk: string) => void;
+    /** Override the running version (default: read from this package's package.json). */
+    version?: string;
+    /** Override the manifest URL (default: project raw.githubusercontent.com URL). */
+    url?: string;
+    /** Override the timeout (default: `KILL_SWITCH_DEFAULT_TIMEOUT_MS`). */
+    timeoutMs?: number;
+    /** Injected fetch (default: global). Tests pass a mock. */
+    fetchFn?: typeof globalThis.fetch;
+}
+export declare function runKillSwitchAtStartup(opts?: KillSwitchHookOptions): Promise<void>;
+//# sourceMappingURL=kill-switch-hook.d.ts.map

package/dist/lib/kill-switch-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-switch-hook.d.ts","sourceRoot":"","sources":["../../src/lib/kill-switch-hook.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;IAC/B,sEAAsE;IACtE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACnC;AAED,wBAAsB,sBAAsB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAmC5F"}

package/dist/lib/kill-switch-hook.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { checkKillSwitch, formatKillSwitchMessage, KILL_SWITCH_DEFAULT_TIMEOUT_MS, readPackageVersion, } from "@ttctl/core";
+export async function runKillSwitchAtStartup(opts = {}) {
+    const writeStderr = opts.writeStderr ??
+        ((chunk) => {
+            process.stderr.write(chunk);
+        });
+    const exit = opts.exit ??
+        ((code) => {
+            process.exit(code);
+        });
+    const version = opts.version ?? readPackageVersion(import.meta.url);
+    const result = await checkKillSwitch({
+        version,
+        ...(opts.url !== undefined ? { url: opts.url } : {}),
+        timeoutMs: opts.timeoutMs ?? KILL_SWITCH_DEFAULT_TIMEOUT_MS,
+        ...(opts.fetchFn !== undefined ? { fetchFn: opts.fetchFn } : {}),
+    });
+    if (result.status !== "match") {
+        // disabled | no-match | fetch-failed — all silent per fail-silent
+        // contract. Diagnostic logging of fetch-failed is intentionally
+        // omitted to avoid noise in restrictive networks (corporate, CI,
+        // offline laptops); users can flip TTCTL_DEBUG_CONFIG to inspect
+        // the configWriter taxonomy but kill-switch deliberately stays
+        // out of that surface.
+        return;
+    }
+    writeStderr(formatKillSwitchMessage({ toolName: "ttctl", version, entry: result.entry }));
+    if (result.entry.action === "refuse") {
+        exit(1);
+    }
+}
+//# sourceMappingURL=kill-switch-hook.js.map

package/dist/lib/kill-switch-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-switch-hook.js","sourceRoot":"","sources":["../../src/lib/kill-switch-hook.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,8BAA8B,EAC9B,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAkDrB,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAA8B,EAAE;IAC3E,MAAM,WAAW,GACf,IAAI,CAAC,WAAW;QAChB,CAAC,CAAC,KAAa,EAAQ,EAAE;YACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;IACL,MAAM,IAAI,GACR,IAAI,CAAC,IAAI;QACT,CAAC,CAAC,IAAY,EAAS,EAAE;YACvB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEpE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;QACnC,OAAO;QACP,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,8BAA8B;QAC3D,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC9B,kEAAkE;QAClE,gEAAgE;QAChE,iEAAiE;QACjE,iEAAiE;QACjE,+DAA+D;QAC/D,uBAAuB;QACvB,OAAO;IACT,CAAC;IAED,WAAW,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE1F,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,CAAC,CAAC,CAAC,CAAC;IACV,CAAC;AACH,CAAC"}

package/dist/lib/output.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Cross-CLI output format for `show` and `list` commands.
+ *
+ * - `pretty`: human-formatted layout (default; trimmed/laid out for direct
+ *   terminal reading). Internally dispatches on shape — `show` verbs render
+ *   a curated key:value layout via the caller-supplied `pretty` formatter,
+ *   `list` verbs render a column-aligned table via the caller-supplied
+ *   `table` formatter, and paragraph-bearing lists render a curated
+ *   multi-line layout (the override registry at
+ *   `lib/format-overrides.ts` carries the strategy classification; the
+ *   shape dispatch is internal — `pretty` is the only user-visible name
+ *   for the human layout).
+ * - `json`: stable single-line JSON, suitable for piping to `jq` or `yq`.
+ * - `yaml`: block-style YAML rendered via `yaml.stringify` with
+ *   `customTags: []` (no `!!timestamp` auto-parse on roundtrip),
+ *   `aliasDuplicateObjects: false` (no `&anchor`/`*alias` noise on
+ *   duplicate references), and `lineWidth: 0` (no line wrapping —
+ *   preserves field-level semantic boundaries; the terminal wraps if
+ *   needed). Multi-paragraph string fields surface as `|` literal block
+ *   scalars; lists as block style (`- item`, not `[item]`). The data
+ *   layer is responsible for shaping `Date` values to ISO 8601 strings
+ *   BEFORE invoking the helper — explicit conversion is safer than
+ *   relying on the YAML lib's date handling.
+ *
+ * The JSON shape commitment is "may break across 0.x" pre-1.0 and
+ * "stable across majors per semver" at 1.0+; the helper enforces
+ * single-line JSON to keep that contract observable to downstream tools.
+ *
+ * The pre-#126 enum carried `text` and `table` as user-visible values;
+ * both were collapsed into the single `pretty` name with internal shape
+ * dispatch. Pre-launch is free moves — there are no backward-compat
+ * aliases.
+ */
+export type OutputFormat = "pretty" | "json" | "yaml";
+/**
+ * All valid `OutputFormat` values, intended for `commander`'s
+ * `Option#choices()`. Frozen at the type level via `readonly` so callers
+ * cannot mutate the shared array.
+ */
+export declare const OUTPUT_FORMATS: readonly OutputFormat[];
+/**
+ * Caller-supplied formatters per format. Each returns the exact string
+ * to emit on stdout (the helper appends a single trailing newline). The
+ * `json` and `yaml` formats have no formatter slot — the helper
+ * stringifies the data directly via `JSON.stringify(data)` /
+ * `formatYaml(data)`.
+ *
+ * `pretty` is the user-visible human-layout slot used by `show` verbs
+ * for curated key:value renderings. `table` is an internal-only slot
+ * used by `list` verbs to provide a column-aligned table rendering.
+ * The user-visible `pretty` format internally dispatches on data shape
+ * (per #126):
+ *
+ * - data is array-shaped or `{items: [...]}`-shaped (list) → prefer
+ *   `table`, fall back to `pretty`.
+ * - data is object-shaped (show) → prefer `pretty`, fall back to
+ *   `table`.
+ * - neither formatter present → fall through to
+ *   `JSON.stringify(_, null, 2)` plus a stderr warning.
+ *
+ * The shape dispatch is internal — `pretty` is the only user-visible
+ * name for the human layout. Show / list / paragraph-bearing-list
+ * routing is the dispatcher's job, not the user's.
+ *
+ * `empty` opts the call site into the empty-state wrapper (#122). When
+ * present AND `isEmptyCollection(data)` returns true, the wrapper
+ * short-circuits BEFORE per-format dispatch and emits a per-format
+ * empty payload — `[]` (single-line) for `json`; the prose+CTA from
+ * `emptyStateProse(empty.command)` for `pretty` (deliberately AVOIDS a
+ * header-only `cli-table3` grid, which the v0.4 reframe categorised
+ * as a "looks broken" pattern). The wrapper is opt-in (not auto-fire on
+ * every call) so search leaves like `autocomplete` — which return
+ * arrays but want a query-aware "no matches" line, not a create-CTA —
+ * can keep their custom empty handling without overriding.
+ */
+export interface OutputFormatters<T> {
+    pretty?: (data: T) => string;
+    table?: (data: T) => string;
+    empty?: {
+        command: string;
+    };
+}
+/**
+ * Stderr hint surfaced when the helper falls through to pretty-printed
+ * JSON because no `pretty` or `table` formatter was provided. Exposed as
+ * a constant so tests can assert on the exact wording without
+ * duplicating it.
+ */
+export declare const PRETTY_FALLBACK_HINT = "note: no pretty formatter provided; falling back to pretty-printed JSON.";
+/**
+ * Render `data` as block-style YAML.
+ *
+ * Behavior:
+ *
+ * - Multi-paragraph strings surface as `|` literal block scalars (the
+ *   YAML lib's default for strings containing newlines), preserving
+ *   paragraph breaks visually rather than escaping them as `\n`.
+ * - Strings already shaped as ISO 8601 by the data layer (e.g.,
+ *   `"2026-05-10T05:45:00Z"`) render quoted, NOT auto-converted to a
+ *   `!!timestamp` tag — `customTags: []` ensures stability of the
+ *   roundtrip contract.
+ * - Numeric fields render as their natural YAML scalar type (numbers,
+ *   not strings).
+ * - Lists and maps render in block style (`- item`, `key: value`),
+ *   never flow style (`[item]`, `{key: value}`).
+ *
+ * The yaml lib's `stringify` always appends a trailing newline; this
+ * helper strips it so the formatter contract matches `JSON.stringify`'s
+ * (no trailing newline). `emitResult` then appends exactly one trailing
+ * newline when writing to stdout.
+ *
+ * The helper does NOT validate `data` for YAML-safe shapes (cycles,
+ * `BigInt`, `Date` objects, `undefined`, etc.); callers shape data into
+ * YAML-friendly form before invoking. In particular: convert `Date` to
+ * ISO 8601 strings at the data layer.
+ */
+export declare function formatYaml(data: unknown): string;
+/**
+ * Result of resolving a `(data, format, options)` triple to a string for
+ * stdout. The optional `warning` field is present only when the helper
+ * fell through to a default branch worth surfacing on stderr (currently:
+ * `pretty` with neither `pretty` nor `table` formatter). Callers using
+ * `formatResult` directly can inspect this field instead of letting
+ * `emitResult` write to stderr.
+ *
+ * `exactOptionalPropertyTypes` is enabled, so `warning` is either absent
+ * or a string — never `undefined`.
+ */
+export type FormatResult = {
+    output: string;
+} | {
+    output: string;
+    warning: string;
+};
+/**
+ * Format `data` per `format` and return the string to emit, plus an
+ * optional `warning` line suitable for stderr. Pure — no I/O.
+ *
+ * Behavior summary:
+ *
+ * - `json` → `JSON.stringify(data)` (single-line; no extra whitespace)
+ * - `yaml` → `formatYaml(data)` (block-style YAML; no formatter slot —
+ *   the helper is the single source of truth for `yaml` rendering)
+ * - `pretty` → shape-dispatched human layout:
+ *   - list-shape data (array, `{items: [...]}`) → prefer
+ *     `options.table`, fall back to `options.pretty`
+ *   - show-shape data (single object) → prefer `options.pretty`, fall
+ *     back to `options.table`
+ *   - neither formatter present → `JSON.stringify(data, null, 2)` plus
+ *     a stderr warning
+ *
+ * The helper does NOT validate `data` for JSON/YAML-safe shapes
+ * (cycles, `undefined`, `Date`, `BigInt`, etc.); callers are
+ * responsible for shaping data into a serialization-friendly form
+ * before passing it.
+ *
+ * The `format` parameter defaults to `"pretty"` so the spec's "default
+ * format is pretty" behavior holds even when commander defaults aren't
+ * available (e.g., direct programmatic use).
+ */
+export declare function formatResult<T>(data: T, format?: OutputFormat, options?: OutputFormatters<T>): FormatResult;
+/**
+ * Format `data` per `format` and write the result to `process.stdout`
+ * (with a trailing newline). When `formatResult` surfaces a `warning`
+ * (`pretty` fall-through with neither formatter), it's written to
+ * `process.stderr` BEFORE the stdout payload — keeping stdout
+ * structured for downstream consumers.
+ *
+ * Tests can spy on `process.stdout.write` and `process.stderr.write` to
+ * assert the exact bytes emitted.
+ */
+export declare function emitResult<T>(data: T, format?: OutputFormat, options?: OutputFormatters<T>): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/lib/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/lib/output.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAA+B,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B;AAsBD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,6EAA6E,CAAC;AAyB/G;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAGhD;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,CAAC,EACP,MAAM,GAAE,YAAuB,EAC/B,OAAO,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAChC,YAAY,CAmCd;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAE,YAAuB,EAAE,OAAO,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAAG,IAAI,CAM/G"}

package/dist/lib/output.js

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { stringify as yamlStringify } from "yaml";
+import { emptyStateProse, isEmptyCollection } from "./empty-state-cta.js";
+/**
+ * All valid `OutputFormat` values, intended for `commander`'s
+ * `Option#choices()`. Frozen at the type level via `readonly` so callers
+ * cannot mutate the shared array.
+ */
+export const OUTPUT_FORMATS = ["pretty", "json", "yaml"];
+/**
+ * Detect whether `data` is list-shaped — an array (current top-level
+ * shape) or `{items: [...]}` (the future `{items, pageInfo?}` envelope
+ * reserved by the v0.4 reframe). Used by the `pretty` dispatcher to
+ * pick `table` vs `pretty` formatter on shape (`list` → `table`,
+ * `show` → `pretty`).
+ *
+ * Returns `false` for `null`, scalars, and objects without an `items`
+ * field — those collapse to the show branch. Note this is a
+ * NON-emptiness signal: `[]` is still list-shape (the empty-state
+ * wrapper handles the empty case BEFORE the dispatcher fires; once it
+ * passes through to dispatch, the array's emptiness no longer matters).
+ */
+function isListShape(data) {
+    if (Array.isArray(data))
+        return true;
+    if (typeof data !== "object" || data === null)
+        return false;
+    if (!Object.prototype.hasOwnProperty.call(data, "items"))
+        return false;
+    return Array.isArray(data.items);
+}
+/**
+ * Stderr hint surfaced when the helper falls through to pretty-printed
+ * JSON because no `pretty` or `table` formatter was provided. Exposed as
+ * a constant so tests can assert on the exact wording without
+ * duplicating it.
+ */
+export const PRETTY_FALLBACK_HINT = "note: no pretty formatter provided; falling back to pretty-printed JSON.";
+/**
+ * Configuration object passed to `yaml.stringify` for the `yaml` output
+ * format. Module-private; `const`-declared so callers cannot rebind
+ * (the yaml lib's options type is mutable, so we cannot deep-freeze
+ * without a type cast — module isolation is sufficient).
+ *
+ * - `customTags: []` — disable the lib's optional tags (`!!timestamp`,
+ *   `!!binary`, etc.) so dates/datetimes encoded as ISO 8601 strings by
+ *   the data layer surface verbatim instead of being re-emitted with
+ *   tag prefixes (which would break roundtrip parsers configured to
+ *   reject custom tags).
+ * - `aliasDuplicateObjects: false` — emit duplicate object references
+ *   inline rather than as `&anchor`/`*alias` pairs, keeping output
+ *   readable for non-YAML-savvy consumers.
+ * - `lineWidth: 0` — disable line wrapping. Field-level semantic
+ *   boundaries stay intact; the terminal wraps for display if needed.
+ */
+const YAML_STRINGIFY_OPTIONS = {
+    customTags: [],
+    aliasDuplicateObjects: false,
+    lineWidth: 0,
+};
+/**
+ * Render `data` as block-style YAML.
+ *
+ * Behavior:
+ *
+ * - Multi-paragraph strings surface as `|` literal block scalars (the
+ *   YAML lib's default for strings containing newlines), preserving
+ *   paragraph breaks visually rather than escaping them as `\n`.
+ * - Strings already shaped as ISO 8601 by the data layer (e.g.,
+ *   `"2026-05-10T05:45:00Z"`) render quoted, NOT auto-converted to a
+ *   `!!timestamp` tag — `customTags: []` ensures stability of the
+ *   roundtrip contract.
+ * - Numeric fields render as their natural YAML scalar type (numbers,
+ *   not strings).
+ * - Lists and maps render in block style (`- item`, `key: value`),
+ *   never flow style (`[item]`, `{key: value}`).
+ *
+ * The yaml lib's `stringify` always appends a trailing newline; this
+ * helper strips it so the formatter contract matches `JSON.stringify`'s
+ * (no trailing newline). `emitResult` then appends exactly one trailing
+ * newline when writing to stdout.
+ *
+ * The helper does NOT validate `data` for YAML-safe shapes (cycles,
+ * `BigInt`, `Date` objects, `undefined`, etc.); callers shape data into
+ * YAML-friendly form before invoking. In particular: convert `Date` to
+ * ISO 8601 strings at the data layer.
+ */
+export function formatYaml(data) {
+    const out = yamlStringify(data, YAML_STRINGIFY_OPTIONS);
+    return out.endsWith("\n") ? out.slice(0, -1) : out;
+}
+/**
+ * Format `data` per `format` and return the string to emit, plus an
+ * optional `warning` line suitable for stderr. Pure — no I/O.
+ *
+ * Behavior summary:
+ *
+ * - `json` → `JSON.stringify(data)` (single-line; no extra whitespace)
+ * - `yaml` → `formatYaml(data)` (block-style YAML; no formatter slot —
+ *   the helper is the single source of truth for `yaml` rendering)
+ * - `pretty` → shape-dispatched human layout:
+ *   - list-shape data (array, `{items: [...]}`) → prefer
+ *     `options.table`, fall back to `options.pretty`
+ *   - show-shape data (single object) → prefer `options.pretty`, fall
+ *     back to `options.table`
+ *   - neither formatter present → `JSON.stringify(data, null, 2)` plus
+ *     a stderr warning
+ *
+ * The helper does NOT validate `data` for JSON/YAML-safe shapes
+ * (cycles, `undefined`, `Date`, `BigInt`, etc.); callers are
+ * responsible for shaping data into a serialization-friendly form
+ * before passing it.
+ *
+ * The `format` parameter defaults to `"pretty"` so the spec's "default
+ * format is pretty" behavior holds even when commander defaults aren't
+ * available (e.g., direct programmatic use).
+ */
+export function formatResult(data, format = "pretty", options = {}) {
+    // Empty-state wrapper (#122): fires BEFORE per-format dispatch when
+    // the caller opts in via `options.empty` AND `data` is detected as an
+    // empty collection (`[]` or `{items: []}`). Pretty mode renders the
+    // CTA prose; JSON / YAML fall through to normal serialization so the
+    // list envelope (`{version, items: []}`, per #128) is preserved on
+    // empty collections — the pre-#147 behavior of emitting a literal
+    // "[]" on the JSON path silently dropped the envelope wrapper, which
+    // tripped E2E suites that read `.items` (surfaced by #147 round-trip).
+    if (options.empty !== undefined && isEmptyCollection(data)) {
+        if (format === "pretty") {
+            return { output: emptyStateProse(options.empty.command) };
+        }
+        // json / yaml: fall through to normal serialization
+    }
+    if (format === "json") {
+        return { output: JSON.stringify(data) };
+    }
+    if (format === "yaml") {
+        return { output: formatYaml(data) };
+    }
+    // pretty branch — internal shape dispatch (per #126 AC):
+    // - list-shape data → table formatter (the column-aligned default for
+    //   list verbs; matches pre-#126 `--output=table` behavior)
+    // - show-shape data → pretty formatter (the curated key:value layout
+    //   for show verbs; matches pre-#126 `--output=text` behavior)
+    // - missing formatters fall through to JSON pretty-print + warning
+    if (isListShape(data)) {
+        if (options.table !== undefined)
+            return { output: options.table(data) };
+        if (options.pretty !== undefined)
+            return { output: options.pretty(data) };
+    }
+    else {
+        if (options.pretty !== undefined)
+            return { output: options.pretty(data) };
+        if (options.table !== undefined)
+            return { output: options.table(data) };
+    }
+    return { output: JSON.stringify(data, null, 2), warning: PRETTY_FALLBACK_HINT };
+}
+/**
+ * Format `data` per `format` and write the result to `process.stdout`
+ * (with a trailing newline). When `formatResult` surfaces a `warning`
+ * (`pretty` fall-through with neither formatter), it's written to
+ * `process.stderr` BEFORE the stdout payload — keeping stdout
+ * structured for downstream consumers.
+ *
+ * Tests can spy on `process.stdout.write` and `process.stderr.write` to
+ * assert the exact bytes emitted.
+ */
+export function emitResult(data, format = "pretty", options = {}) {
+    const result = formatResult(data, format, options);
+    if ("warning" in result) {
+        process.stderr.write(`${result.warning}\n`);
+    }
+    process.stdout.write(`${result.output}\n`);
+}
+//# sourceMappingURL=output.js.map

package/dist/lib/output.js.map

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

package/dist/lib/pagination.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pagination flag values as parsed off a Commander leaf. Both fields
+ * are independent — one may be passed without the other (the server
+ * fills the missing one with its default). User-facing values are
+ * 1-indexed; service-layer translation to wire-indexing happens inside
+ * the per-service `list()` adapter, not here.
+ *
+ * Declared per paginating leaf (#183, follow-up to #138). Action
+ * handlers read these directly off their Commander `opts()` payload —
+ * no module-scoped capture, no global enforcement. Leaves whose wire
+ * operation does not paginate simply do not declare the flags; Commander
+ * emits its standard `error: unknown option '--page'` (exit 1) when a
+ * user passes the flag to such a leaf, which is the right error
+ * pedagogy (a global advertisement followed by a per-command refusal
+ * was an architectural category error — see #183 deliberation).
+ *
+ * `exactOptionalPropertyTypes` is enabled, so absent fields are
+ * literally missing rather than `undefined`.
+ */
+export interface PaginationOptions {
+    /** 1-indexed page number; must be ≥ 1. */
+    page?: number;
+    /** Items per page; must be ≥ 1. Upper bound is server-enforced. */
+    perPage?: number;
+}
+/**
+ * Custom Commander argument parser for `--page <number>` and
+ * `--per-page <number>`. Both flags share the same constraint set —
+ * positive integers — so the parser is reused via `Option.argParser`
+ * on each paginating leaf.
+ *
+ * Rejects:
+ *
+ * - empty strings (`""`)
+ * - non-numeric input (`"abc"`, `"1.5"`, `"1e3"`, `"0x10"`)
+ * - non-finite values (`NaN`, `Infinity`)
+ * - zero or negative values (`"0"`, `"-1"`)
+ *
+ * Returns the parsed integer on success. Throws
+ * `InvalidArgumentError` (Commander surfaces it as a parse-time error
+ * before any sub-command action runs).
+ *
+ * The strict regex (`^[1-9][0-9]*$`) is the gating check — `Number()`
+ * alone would accept `"1.5"`, `"1e3"`, `"0x10"`, leading/trailing
+ * whitespace, signs, etc. The integer-shape constraint is part of the
+ * AC contract ("--page <number>", 1-indexed) and the wire constraint.
+ */
+export declare function parsePaginationFlag(name: string, raw: string): number;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/lib/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CASrE"}

package/dist/lib/pagination.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { InvalidArgumentError } from "commander";
+/**
+ * Custom Commander argument parser for `--page <number>` and
+ * `--per-page <number>`. Both flags share the same constraint set —
+ * positive integers — so the parser is reused via `Option.argParser`
+ * on each paginating leaf.
+ *
+ * Rejects:
+ *
+ * - empty strings (`""`)
+ * - non-numeric input (`"abc"`, `"1.5"`, `"1e3"`, `"0x10"`)
+ * - non-finite values (`NaN`, `Infinity`)
+ * - zero or negative values (`"0"`, `"-1"`)
+ *
+ * Returns the parsed integer on success. Throws
+ * `InvalidArgumentError` (Commander surfaces it as a parse-time error
+ * before any sub-command action runs).
+ *
+ * The strict regex (`^[1-9][0-9]*$`) is the gating check — `Number()`
+ * alone would accept `"1.5"`, `"1e3"`, `"0x10"`, leading/trailing
+ * whitespace, signs, etc. The integer-shape constraint is part of the
+ * AC contract ("--page <number>", 1-indexed) and the wire constraint.
+ */
+export function parsePaginationFlag(name, raw) {
+    if (!/^[1-9][0-9]*$/.test(raw)) {
+        throw new InvalidArgumentError(`${name} must be a positive integer (got: ${JSON.stringify(raw)})`);
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new InvalidArgumentError(`${name} must be a positive integer (got: ${JSON.stringify(raw)})`);
+    }
+    return n;
+}
+//# sourceMappingURL=pagination.js.map

package/dist/lib/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AA4BjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,GAAW;IAC3D,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,qCAAqC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrG,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,qCAAqC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/program.d.ts

@@ -0,0 +1,80 @@
+import { Command } from "commander";
+/**
+ * Build the root TTCtl Commander program. Sub-commands are registered as they
+ * land in milestones; the program is shaped as a noun-verb tree (e.g.,
+ * `ttctl profile show`, `ttctl timesheet list`).
+ *
+ * Global options:
+ *
+ *   `--config <path>` — explicit path to the YAML config, takes precedence
+ *   over `TTCTL_CONFIG_FILE` and the home dotfile. Validated at invocation
+ *   time (before any sub-command's action runs) — a missing file surfaces
+ *   as `ConfigError(code: NO_CREDS)` rather than failing later inside
+ *   `loadConfigFile`. Honors `aws --profile` / `kubectl --kubeconfig` UX
+ *   expectations.
+ *
+ *   Resolution precedence (highest → lowest, post-#107):
+ *
+ *     1. `--config <path>`         — this flag (per-invocation)
+ *     2. `TTCTL_CONFIG_FILE` env   — process-scoped (CI, direnv)
+ *     3. `~/.ttctl.yaml`           — POSIX home dotfile (only fallback)
+ *
+ *   The CWD `./.ttctl.yaml` is NOT auto-discovered (closed in #92).
+ *   XDG paths (`$XDG_CONFIG_HOME/ttctl/config.yaml`,
+ *   `~/.config/ttctl/config.yaml`) are NOT consulted (closed in #107 — the
+ *   single-file model places the captured bearer in the same YAML, so
+ *   `~/.ttctl.yaml` is the canonical home location).
+ *
+ *   `--json` / `--yaml` — boolean shortcuts for `--output=json` /
+ *   `--output=yaml` (post-#126). Mutual exclusion with `--output`/`-o` is
+ *   enforced in the preAction hook: any two of `{--output, -o, --json,
+ *   --yaml}` present together raise a parse-time error before the
+ *   sub-command's action runs.
+ *
+ *   `--dry-run` (issue #52) — preview a mutation without sending it.
+ *   Captured into the module-scoped `cliDryRun` holder via
+ *   `setCliDryRun` in the preAction hook so mutation handlers can read
+ *   it through `getCliDryRun()`. Leaf commands tagged via
+ *   `markMutation()` (in their `build*Command` factories) route the
+ *   value through to the core layer's `dryRun` option; non-mutation
+ *   leaves get a one-line stderr no-op note from the preAction hook
+ *   (`DRY_RUN_NO_OP_STDERR_NOTE`) and proceed normally.
+ *
+ *   MCP tool integration is conditional on issue #10 having landed —
+ *   when MCP tools that wrap mutations ship, they accept the same
+ *   `dryRun?: boolean` input parameter and route through the same core
+ *   `dryRun` option. Until then, no MCP-side wiring is required.
+ *
+ *   `--verbose` / `--debug` (issue #139) — diagnostic observability for
+ *   transport-level request/response activity. `--verbose` emits a
+ *   one-line request descriptor + one-line response status per
+ *   transport call to STDERR; `--debug` emits full JSON-encoded
+ *   request/response envelopes (including redacted headers and body)
+ *   to STDERR. Both write EXCLUSIVELY to stderr — the stdout data
+ *   channel (json/yaml/pretty envelopes per #126/#128) is never
+ *   touched, so `--debug --output=json` works as one would expect:
+ *   structured data on stdout, redacted debug trace on stderr.
+ *
+ *   Mutual relationship: `--debug` is a strict superset of
+ *   `--verbose`; if both are passed, `--debug` wins (no warning —
+ *   the user got what they implicitly asked for, the verbose-tier
+ *   data is a subset of the debug-tier data). The preAction hook
+ *   computes the effective level and routes it through
+ *   `setDiagnosticLogger` so every transport (stockTransport,
+ *   impersonatedTransport, impersonatedMultipartTransport, and the
+ *   hand-rolled photo-upload path in profile/basic) emits the same
+ *   shape. Secret redaction (cookies, authorization headers,
+ *   password / token / secret body fields, the
+ *   `user_<24hex>_<20alnum>` bearer pattern) is applied by the
+ *   `redact` module BEFORE serialization, so verbatim bearers /
+ *   cookies cannot appear in either log tier.
+ *
+ * Pagination flags are declared PER paginating leaf (`jobs list`,
+ * `jobs saved`, `jobs viewed`, `jobs not-interested-list`) rather
+ * than globally — see #183 (follow-up to #138). The leaf's `--help`
+ * is the source of truth for "does this command paginate?"; Commander
+ * emits its standard `error: unknown option '--page'` (exit 1) when
+ * the flag is passed to a non-paginating leaf.
+ */
+export declare function buildProgram(): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAoB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAoLtC"}