@ttctl/cli 0.0.0 → 0.1.0-rc.2

package/dist/index.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export { buildProgram } from "./program.js";
+export { exitCodeForTtctlError, formatTtctlErrorMessage, presentTtctlError } from "./errors.js";
+export { formatCrashLog, installCrashHandlers } from "./crash-handlers.js";
+// Re-export the typed-error base so the umbrella package's top-level error
+// handler can `instanceof`-check without a direct `@ttctl/core` dependency.
+// CLI consumers typically catch concrete subclasses instead.
+export { TtctlError } from "@ttctl/core";
+// Also re-export ConfigError so the umbrella's MCP branch can render the
+// startup-time `NO_CREDS` failure (#113 fail-fast contract) in the same
+// uniform `Error (CODE): message` form the CLI surface uses, without
+// pulling `@ttctl/core` as a direct dependency on the umbrella.
+export { ConfigError } from "@ttctl/core";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,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;AAG3E,2EAA2E;AAC3E,4EAA4E;AAC5E,6DAA6D;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,yEAAyE;AACzE,wEAAwE;AACxE,qEAAqE;AACrE,gEAAgE;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/config-context.d.ts

@@ -0,0 +1,41 @@
+import type { TtctlConfig } from "@ttctl/core";
+/**
+ * Capture the explicit config path from the root program's `--config`
+ * global option. Called by the program's `preAction` hook before any
+ * sub-command runs. Pass `undefined` when `--config` was omitted.
+ */
+export declare function setCliConfigPath(path: string | undefined): void;
+/**
+ * Read the captured `--config` value. Returns `undefined` when `--config`
+ * was not passed; in that case `resolveConfigForCli` falls back to the
+ * core resolution chain.
+ *
+ * Exported primarily for tests and rare callers that need the raw value
+ * (e.g., to forward it to a subprocess via `TTCTL_CONFIG_FILE`).
+ */
+export declare function getCliConfigPath(): string | undefined;
+/**
+ * Reset the captured path. Tests call this in `beforeEach` to avoid
+ * bleeding state across cases. Not used in production.
+ */
+export declare function resetCliConfigPath(): void;
+/**
+ * The CLI surface's single entry point into the core's config resolver.
+ *
+ * Honors the explicit `--config` value captured by the root program's
+ * `preAction` hook; falls back to the core resolution chain
+ * (`TTCTL_CONFIG_FILE` → `$XDG_CONFIG_HOME/ttctl/config.yaml` →
+ * `~/.config/ttctl/config.yaml`) when `--config` was not passed.
+ *
+ * AC contract (#93): every CLI command that touches config MUST call
+ * `resolveConfigForCli()` rather than the bare `resolveConfig()` from
+ * `@ttctl/core`. The bare form re-triggers the env→default chain and
+ * silently ignores `--config` — that's the bug this wrapper exists to
+ * prevent. A grep over `packages/cli/src/` for `resolveConfig\(\)`
+ * (no args) should surface only this file.
+ */
+export declare function resolveConfigForCli(): {
+    config: TtctlConfig;
+    path: string;
+};
+//# sourceMappingURL=config-context.d.ts.map

package/dist/lib/config-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-context.d.ts","sourceRoot":"","sources":["../../src/lib/config-context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAyB/C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,IAAI;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAM3E"}

package/dist/lib/config-context.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { resolveConfig } from "@ttctl/core";
+/**
+ * Process-scoped holder for the explicit config path supplied via the
+ * root program's `--config <path>` global option.
+ *
+ * Set once by the root program's `preAction` hook (see `program.ts`) before
+ * any sub-command's action handler runs; read by every CLI call site that
+ * loads `.ttctl.yaml`. Holding the path in a module-level variable lets
+ * action handlers stay focused on their domain logic without each having to
+ * walk Commander's parent chain via `cmd.optsWithGlobals()` — every leaf
+ * already accepts a `commandLabel` string for error prefixing, and adding a
+ * `cmd: Command` parameter to ~25 handlers would be invasive.
+ *
+ * When undefined (i.e., `--config` was not passed), `resolveConfigForCli`
+ * falls back to the core resolution chain (`TTCTL_CONFIG_FILE` env var →
+ * `$XDG_CONFIG_HOME/ttctl/config.yaml` → `~/.config/ttctl/config.yaml`).
+ *
+ * Tests must call `resetCliConfigPath()` in `beforeEach` to avoid bleeding
+ * state across cases. The CLI surface invokes `setCliConfigPath` once per
+ * process via the program's `preAction` hook, so production code never sees
+ * stale values.
+ */
+let cliConfigPath;
+/**
+ * Capture the explicit config path from the root program's `--config`
+ * global option. Called by the program's `preAction` hook before any
+ * sub-command runs. Pass `undefined` when `--config` was omitted.
+ */
+export function setCliConfigPath(path) {
+    cliConfigPath = path;
+}
+/**
+ * Read the captured `--config` value. Returns `undefined` when `--config`
+ * was not passed; in that case `resolveConfigForCli` falls back to the
+ * core resolution chain.
+ *
+ * Exported primarily for tests and rare callers that need the raw value
+ * (e.g., to forward it to a subprocess via `TTCTL_CONFIG_FILE`).
+ */
+export function getCliConfigPath() {
+    return cliConfigPath;
+}
+/**
+ * Reset the captured path. Tests call this in `beforeEach` to avoid
+ * bleeding state across cases. Not used in production.
+ */
+export function resetCliConfigPath() {
+    cliConfigPath = undefined;
+}
+/**
+ * The CLI surface's single entry point into the core's config resolver.
+ *
+ * Honors the explicit `--config` value captured by the root program's
+ * `preAction` hook; falls back to the core resolution chain
+ * (`TTCTL_CONFIG_FILE` → `$XDG_CONFIG_HOME/ttctl/config.yaml` →
+ * `~/.config/ttctl/config.yaml`) when `--config` was not passed.
+ *
+ * AC contract (#93): every CLI command that touches config MUST call
+ * `resolveConfigForCli()` rather than the bare `resolveConfig()` from
+ * `@ttctl/core`. The bare form re-triggers the env→default chain and
+ * silently ignores `--config` — that's the bug this wrapper exists to
+ * prevent. A grep over `packages/cli/src/` for `resolveConfig\(\)`
+ * (no args) should surface only this file.
+ */
+export function resolveConfigForCli() {
+    // Conditionally include `path` so the `ResolveConfigOptions.path?: string`
+    // contract is honored under `exactOptionalPropertyTypes: true` — passing
+    // `{ path: undefined }` would be a type error even though the runtime
+    // semantics are identical to omitting the field.
+    return cliConfigPath !== undefined ? resolveConfig({ path: cliConfigPath }) : resolveConfig();
+}
+//# sourceMappingURL=config-context.js.map

package/dist/lib/config-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-context.js","sourceRoot":"","sources":["../../src/lib/config-context.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,IAAI,aAAiC,CAAC;AAEtC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAwB;IACvD,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,aAAa,GAAG,SAAS,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB;IACjC,2EAA2E;IAC3E,yEAAyE;IACzE,sEAAsE;IACtE,iDAAiD;IACjD,OAAO,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;AAChG,CAAC"}

package/dist/lib/dry-run.d.ts

@@ -0,0 +1,70 @@
+import type { Command } from "commander";
+/**
+ * Capture the global `--dry-run` value from the root program's
+ * `preAction` hook. Pass `false` when the flag was omitted (Commander's
+ * default for boolean Options is `undefined`, which the hook normalises
+ * to `false` before invoking this setter).
+ */
+export declare function setCliDryRun(value: boolean): void;
+/**
+ * Read the captured `--dry-run` value. Returns `false` when the flag
+ * was not passed (the apply-path default).
+ *
+ * Mutation action handlers call this directly — when the leaf is marked
+ * as a mutation (see {@link markMutation}), the global flag has been
+ * captured and the handler is responsible for routing through the
+ * core's `dryRun` option.
+ */
+export declare function getCliDryRun(): boolean;
+/**
+ * Reset the captured value. Tests call this in `beforeEach` to avoid
+ * bleeding state across cases. Not used in production — the program's
+ * `preAction` hook calls `setCliDryRun` once per invocation, so stale
+ * values are not possible at runtime.
+ */
+export declare function resetCliDryRun(): void;
+/**
+ * Tag `cmd` as a mutation entry point. Mutation commands are responsible
+ * for routing the `--dry-run` flag through to the core layer's `dryRun`
+ * option; commands NOT tagged are treated as read-only / unsupported by
+ * the program's `preAction` hook (which emits a stderr no-op note when
+ * `--dry-run` is set on a non-mutation leaf).
+ *
+ * Tagging happens once at command construction (in the `build*Command`
+ * functions). Returns the same `Command` so call sites can chain:
+ *
+ *   markMutation(profile.command("update").description(...).action(...));
+ *
+ * Future mutation surfaces (timesheet submit per #13, additional
+ * profile-domain updates per #74-76) MUST call this when they ship —
+ * forgetting to mark fires the read-no-op note instead of routing
+ * through the dry-run path. Lint / test coverage at the program level
+ * is the safety net for that contract.
+ */
+export declare function markMutation(cmd: Command): Command;
+/**
+ * True when `cmd` was previously tagged via {@link markMutation}. Used
+ * by the program's `preAction` hook to decide whether the `--dry-run`
+ * flag should route through the handler's dry-run path or fire the
+ * read-no-op stderr note.
+ *
+ * Returns `false` for any Commander Command that was not tagged —
+ * including mutations whose authors forgot to call `markMutation`. Such
+ * commands will silently fall into the read-no-op path; tests at the
+ * program level catch this regression.
+ */
+export declare function isMutationCommand(cmd: Command): boolean;
+/**
+ * Verbatim stderr text emitted by the program's `preAction` hook when
+ * `--dry-run` is set on a leaf that has NOT been tagged via {@link
+ * markMutation}. The exact wording is locked by the AC for issue #52
+ * ("`--dry-run` is a no-op for read commands") — pinning it as a
+ * constant lets tests assert against the same string the production
+ * code emits without duplicating it.
+ *
+ * The trailing newline is part of the constant so callers writing to
+ * stderr with `process.stderr.write` can pass it directly without
+ * appending `"\n"`.
+ */
+export declare const DRY_RUN_NO_OP_STDERR_NOTE: "note: `--dry-run` is a no-op for read commands\n";
+//# sourceMappingURL=dry-run.d.ts.map

package/dist/lib/dry-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../../src/lib/dry-run.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAiBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGlD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,EAAG,kDAA2D,CAAC"}

package/dist/lib/dry-run.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Process-scoped holder for the global `--dry-run` flag (issue #52).
+ *
+ * Set once by the root program's `preAction` hook (see `program.ts`)
+ * before any sub-command's action handler runs; read by mutation
+ * handlers that need to route through the core layer's `dryRun` option
+ * to short-circuit before transport. Mirrors the pattern established by
+ * `cliConfigPath` in `lib/config-context.ts`: a module-scoped variable
+ * keeps each handler's signature focused on its domain (no `cmd:
+ * Command` parameter threading) while exposing a single place to test
+ * the captured value.
+ *
+ * Tests must call `resetCliDryRun()` in `beforeEach` to avoid bleeding
+ * state across cases — the module-scoped variable persists across
+ * Vitest's `vi.resetModules` only when the module under test is the
+ * one importing this file.
+ */
+let cliDryRun = false;
+/**
+ * Capture the global `--dry-run` value from the root program's
+ * `preAction` hook. Pass `false` when the flag was omitted (Commander's
+ * default for boolean Options is `undefined`, which the hook normalises
+ * to `false` before invoking this setter).
+ */
+export function setCliDryRun(value) {
+    cliDryRun = value;
+}
+/**
+ * Read the captured `--dry-run` value. Returns `false` when the flag
+ * was not passed (the apply-path default).
+ *
+ * Mutation action handlers call this directly — when the leaf is marked
+ * as a mutation (see {@link markMutation}), the global flag has been
+ * captured and the handler is responsible for routing through the
+ * core's `dryRun` option.
+ */
+export function getCliDryRun() {
+    return cliDryRun;
+}
+/**
+ * Reset the captured value. Tests call this in `beforeEach` to avoid
+ * bleeding state across cases. Not used in production — the program's
+ * `preAction` hook calls `setCliDryRun` once per invocation, so stale
+ * values are not possible at runtime.
+ */
+export function resetCliDryRun() {
+    cliDryRun = false;
+}
+/**
+ * Symbol-keyed marker used by {@link markMutation} and {@link
+ * isMutationCommand} to tag Commander `Command` instances as mutation
+ * entry points. Symbol-keyed (rather than a string property) so the
+ * marker cannot collide with any future Commander internal field, and
+ * cannot be reached via accidental `for-in` iteration on the command.
+ *
+ * `Symbol.for` (the cross-realm registry) instead of a fresh `Symbol`
+ * so the same marker resolves identically across module boundaries —
+ * Vitest's module isolation occasionally re-evaluates this file in a
+ * fresh realm, and a non-registered symbol would silently lose the
+ * tag on Command instances built by the production program.
+ */
+const MUTATION_MARKER = Symbol.for("ttctl.cli.command.isMutation");
+/**
+ * Tag `cmd` as a mutation entry point. Mutation commands are responsible
+ * for routing the `--dry-run` flag through to the core layer's `dryRun`
+ * option; commands NOT tagged are treated as read-only / unsupported by
+ * the program's `preAction` hook (which emits a stderr no-op note when
+ * `--dry-run` is set on a non-mutation leaf).
+ *
+ * Tagging happens once at command construction (in the `build*Command`
+ * functions). Returns the same `Command` so call sites can chain:
+ *
+ *   markMutation(profile.command("update").description(...).action(...));
+ *
+ * Future mutation surfaces (timesheet submit per #13, additional
+ * profile-domain updates per #74-76) MUST call this when they ship —
+ * forgetting to mark fires the read-no-op note instead of routing
+ * through the dry-run path. Lint / test coverage at the program level
+ * is the safety net for that contract.
+ */
+export function markMutation(cmd) {
+    cmd[MUTATION_MARKER] = true;
+    return cmd;
+}
+/**
+ * True when `cmd` was previously tagged via {@link markMutation}. Used
+ * by the program's `preAction` hook to decide whether the `--dry-run`
+ * flag should route through the handler's dry-run path or fire the
+ * read-no-op stderr note.
+ *
+ * Returns `false` for any Commander Command that was not tagged —
+ * including mutations whose authors forgot to call `markMutation`. Such
+ * commands will silently fall into the read-no-op path; tests at the
+ * program level catch this regression.
+ */
+export function isMutationCommand(cmd) {
+    return cmd[MUTATION_MARKER] === true;
+}
+/**
+ * Verbatim stderr text emitted by the program's `preAction` hook when
+ * `--dry-run` is set on a leaf that has NOT been tagged via {@link
+ * markMutation}. The exact wording is locked by the AC for issue #52
+ * ("`--dry-run` is a no-op for read commands") — pinning it as a
+ * constant lets tests assert against the same string the production
+ * code emits without duplicating it.
+ *
+ * The trailing newline is part of the constant so callers writing to
+ * stderr with `process.stderr.write` can pass it directly without
+ * appending `"\n"`.
+ */
+export const DRY_RUN_NO_OP_STDERR_NOTE = "note: `--dry-run` is a no-op for read commands\n";
+//# sourceMappingURL=dry-run.js.map

package/dist/lib/dry-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run.js","sourceRoot":"","sources":["../../src/lib/dry-run.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAIpC;;;;;;;;;;;;;;;;GAgBG;AACH,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACtC,GAA0C,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;IACpE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAQ,GAA0C,CAAC,eAAe,CAAC,KAAK,IAAI,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,kDAA2D,CAAC"}

package/dist/lib/empty-state-cta.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Per-command empty-state hint registry and detection helper for the
+ * `formatResult` empty-state wrapper (introduced #122; format names
+ * updated for the #126 reframe). The wrapper checks for empty
+ * collection input BEFORE per-format dispatch and emits a per-format
+ * empty payload — `[]` for `json`, prose with create-CTA for `pretty`,
+ * normal block-style rendering for `yaml`.
+ *
+ * This module is the single source of truth for the empty-state CTA
+ * wording across all `list` leaves; per-formatter `if (items.length ===
+ * 0) return "(no foo)"` branches in individual sub-domain formatters
+ * become production-unreachable once the call site opts into the
+ * wrapper via `OutputFormatters#empty`.
+ */
+/**
+ * Per-command empty-state metadata. Looked up by canonical command path
+ * (e.g. `profile.skills.list`) when the wrapper fires.
+ *
+ * - `entityPlural`: noun for the "No <entity-plural> found." line
+ *   (e.g., `"skills"`, `"portfolio items"`).
+ * - `addHint`: optional copy-pasteable command the user can run to
+ *   create their first item (e.g., `"ttctl profile skills add <name>"`).
+ *   Omitted for sub-domains where empty-state isn't user-resolvable
+ *   (e.g., pending reviews are server-driven, not user-created).
+ */
+export interface EmptyStateCta {
+    entityPlural: string;
+    addHint?: string;
+}
+/**
+ * Frozen registry mapping canonical command paths to their empty-state
+ * metadata. Keys MUST match the `command` value passed by the caller via
+ * `OutputFormatters#empty.command`.
+ *
+ * Extension policy: when adding a new `list` leaf, add a registry entry
+ * here AND wire the call site to pass `empty: { command: "<key>" }`.
+ * Missing entries fall through to a generic `"No items found."` line —
+ * surfaced but not silenced — so the wrapper degrades gracefully when a
+ * sub-domain ships before its registry entry.
+ */
+export declare const EMPTY_STATE_CTAS: Readonly<Record<string, EmptyStateCta>>;
+/**
+ * Render the empty-state prose line for a given command path. Returns
+ * `"No <entity-plural> found. Add one with: <addHint>"` when both
+ * `entityPlural` and `addHint` are registered; degrades to
+ * `"No <entity-plural> found."` when only the noun is registered; falls
+ * back to `"No items found."` when the command is unknown.
+ *
+ * Pure — directly unit-testable.
+ */
+export declare function emptyStateProse(command: string): string;
+/**
+ * Detect collection-shaped input that the empty-state wrapper should
+ * intercept. Returns `true` for both `[]` (current top-level list shape)
+ * and `{items: []}` (the future `{items, pageInfo?}` envelope reserved
+ * by the v0.4 reframe — see #121). Returns `false` for anything else,
+ * including non-collection objects, scalars, `null`, and `undefined`,
+ * so the wrapper never accidentally fires on a `show` payload.
+ *
+ * Pure — directly unit-testable.
+ */
+export declare function isEmptyCollection(value: unknown): boolean;
+//# sourceMappingURL=empty-state-cta.d.ts.map

package/dist/lib/empty-state-cta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-state-cta.d.ts","sourceRoot":"","sources":["../../src/lib/empty-state-cta.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CA+BnE,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYzD"}

package/dist/lib/empty-state-cta.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Frozen registry mapping canonical command paths to their empty-state
+ * metadata. Keys MUST match the `command` value passed by the caller via
+ * `OutputFormatters#empty.command`.
+ *
+ * Extension policy: when adding a new `list` leaf, add a registry entry
+ * here AND wire the call site to pass `empty: { command: "<key>" }`.
+ * Missing entries fall through to a generic `"No items found."` line —
+ * surfaced but not silenced — so the wrapper degrades gracefully when a
+ * sub-domain ships before its registry entry.
+ */
+export const EMPTY_STATE_CTAS = Object.freeze({
+    "profile.skills.list": {
+        entityPlural: "skills",
+        addHint: "ttctl profile skills add <name>",
+    },
+    "profile.portfolio.list": {
+        entityPlural: "portfolio items",
+        addHint: "ttctl profile portfolio add",
+    },
+    "profile.industries.list": {
+        entityPlural: "industries",
+        addHint: "ttctl profile industries add <name>",
+    },
+    "profile.visas.list": {
+        entityPlural: "travel visas",
+        addHint: "ttctl profile visas add",
+    },
+    // Reviews are pending-review records the server creates when a profile
+    // section needs re-attestation; the user resolves them via `approve`,
+    // not by adding new ones — the empty case is a happy state, not a
+    // call-to-create.
+    "profile.reviews.list": {
+        entityPlural: "pending section reviews",
+    },
+    // Activity items (#15) are server-driven — applications, availability
+    // requests, interviews, and engagements all materialize when the
+    // recruiter / client side acts. Empty case is a happy state for new
+    // users; no `addHint` (no `apply` verb in TTCtl per project non-goals).
+    "applications.list": {
+        entityPlural: "activity items",
+    },
+});
+/**
+ * Render the empty-state prose line for a given command path. Returns
+ * `"No <entity-plural> found. Add one with: <addHint>"` when both
+ * `entityPlural` and `addHint` are registered; degrades to
+ * `"No <entity-plural> found."` when only the noun is registered; falls
+ * back to `"No items found."` when the command is unknown.
+ *
+ * Pure — directly unit-testable.
+ */
+export function emptyStateProse(command) {
+    const cta = EMPTY_STATE_CTAS[command];
+    if (cta === undefined) {
+        return "No items found.";
+    }
+    if (cta.addHint === undefined) {
+        return `No ${cta.entityPlural} found.`;
+    }
+    return `No ${cta.entityPlural} found. Add one with: ${cta.addHint}`;
+}
+/**
+ * Detect collection-shaped input that the empty-state wrapper should
+ * intercept. Returns `true` for both `[]` (current top-level list shape)
+ * and `{items: []}` (the future `{items, pageInfo?}` envelope reserved
+ * by the v0.4 reframe — see #121). Returns `false` for anything else,
+ * including non-collection objects, scalars, `null`, and `undefined`,
+ * so the wrapper never accidentally fires on a `show` payload.
+ *
+ * Pure — directly unit-testable.
+ */
+export function isEmptyCollection(value) {
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    if (!Object.prototype.hasOwnProperty.call(value, "items")) {
+        return false;
+    }
+    const items = value.items;
+    return Array.isArray(items) && items.length === 0;
+}
+//# sourceMappingURL=empty-state-cta.js.map

package/dist/lib/empty-state-cta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-state-cta.js","sourceRoot":"","sources":["../../src/lib/empty-state-cta.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAiCpC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA4C,MAAM,CAAC,MAAM,CAAC;IACrF,qBAAqB,EAAE;QACrB,YAAY,EAAE,QAAQ;QACtB,OAAO,EAAE,iCAAiC;KAC3C;IACD,wBAAwB,EAAE;QACxB,YAAY,EAAE,iBAAiB;QAC/B,OAAO,EAAE,6BAA6B;KACvC;IACD,yBAAyB,EAAE;QACzB,YAAY,EAAE,YAAY;QAC1B,OAAO,EAAE,qCAAqC;KAC/C;IACD,oBAAoB,EAAE;QACpB,YAAY,EAAE,cAAc;QAC5B,OAAO,EAAE,yBAAyB;KACnC;IACD,uEAAuE;IACvE,sEAAsE;IACtE,kEAAkE;IAClE,kBAAkB;IAClB,sBAAsB,EAAE;QACtB,YAAY,EAAE,yBAAyB;KACxC;IACD,sEAAsE;IACtE,iEAAiE;IACjE,oEAAoE;IACpE,wEAAwE;IACxE,mBAAmB,EAAE;QACnB,YAAY,EAAE,gBAAgB;KAC/B;CACF,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,MAAM,GAAG,CAAC,YAAY,SAAS,CAAC;IACzC,CAAC;IACD,OAAO,MAAM,GAAG,CAAC,YAAY,yBAAyB,GAAG,CAAC,OAAO,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAI,KAA4B,CAAC,KAAK,CAAC;IAClD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;AACpD,CAAC"}