@cleocode/contracts 2026.5.104 → 2026.5.106

package/dist/render/icon.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Typed icon enums for the human-render contract (ADR-077).
+ *
+ * Single source of truth for the visual language used across all renderers
+ * (tree, table, list, badge). Each enum is emoji-first; `ascii()` returns the
+ * NO_COLOR-safe fallback for non-UTF-8 terminals or `NO_COLOR=1` environments.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Status icons — agent-task lifecycle states.
+ *
+ * Emoji-first; `ascii()` returns a NO_COLOR-safe fallback.
+ */
+export declare enum StatusIcon {
+    /** Task is queued and has not started. */
+    PENDING = "\u23F3",
+    /** Task is in progress. */
+    ACTIVE = "\uD83D\uDEA7",
+    /** Task completed successfully. */
+    DONE = "\u2705",
+    /** Task is blocked on a dependency or gate. */
+    BLOCKED = "\uD83D\uDEAA",
+    /** Task is archived and no longer actively tracked. */
+    ARCHIVED = "\uD83D\uDDC4",
+    /** Task was cancelled before completion. */
+    CANCELLED = "\u2717"
+}
+/**
+ * Task-kind icons — Saga / Epic / Task / Subtask plus ancillary kinds.
+ */
+export declare enum KindIcon {
+    /** Saga — multi-release theme grouping ≥ 2 Epics. */
+    SAGA = "\uD83C\uDF32",
+    /** Epic — one releasable slice. */
+    EPIC = "\uD83D\uDCCB",
+    /** Task — one atomic PR-sized change. */
+    TASK = "\u2022",
+    /** Subtask — one commit contributing to a Task's PR. */
+    SUBTASK = "\u25E6",
+    /** Research task — investigation or audit. */
+    RESEARCH = "\uD83D\uDCD6",
+    /** Bug task — defect tracking. */
+    BUG = "\uD83D\uDC1B",
+    /** Release task — shipping work. */
+    RELEASE = "\uD83D\uDE80"
+}
+/**
+ * Badge icons — flags attached to tasks (empty, orphan, nested, etc).
+ */
+export declare enum BadgeIcon {
+    /** Container has no children. */
+    EMPTY = "\uD83E\uDEA6",
+    /**
+     * Task has no parent and is unreachable from a Saga or Epic.
+     *
+     * NOTE: ADR-077 §2 originally specified `'🚪'`, identical to `StatusIcon.BLOCKED`.
+     * TypeScript string enums share a single runtime string so `ascii()` cannot
+     * disambiguate. Resolved by switching to `'👻'` (abandoned/lonely semantics).
+     * A follow-up ADR amendment lands in T10137 (B12).
+     */
+    ORPHAN = "\uD83D\uDC7B",
+    /** Task is nested deeper than the depth budget allows. */
+    NESTED = "\uD83D\uDD01",
+    /** Caution — something needs human attention. */
+    CAUTION = "\u26A0",
+    /** Recently added — surfaced for visibility. */
+    NEW = "\u2605"
+}
+/**
+ * Relation icons — edge semantics in tree views.
+ */
+export declare enum RelationIcon {
+    /** Saga groups Epic via `task_relations.relation_type='groups'`. */
+    GROUPS = "\u2282",
+    /** Parent edge — direct hierarchical parent. */
+    PARENT = "\u2934",
+    /** Depends-on edge — A cannot start until B is done. */
+    DEPENDS = "\u21E8",
+    /** Blocks edge — A actively blocks B from progressing. */
+    BLOCKS = "\u2298"
+}
+/**
+ * Union of every icon enum — useful as the parameter type for helpers that
+ * accept any icon without caring which category it came from.
+ */
+export type AnyIcon = StatusIcon | KindIcon | BadgeIcon | RelationIcon;
+/**
+ * Maps an emoji icon to its NO_COLOR-safe ASCII equivalent.
+ *
+ * Used when stdout is not a UTF-8 TTY or `NO_COLOR=1` is set. Every enum
+ * member has an explicit ASCII fallback — the exhaustive switch ensures the
+ * TypeScript compiler flags any future icon added without an ASCII mapping.
+ *
+ * @param icon - Any icon from `StatusIcon`, `KindIcon`, `BadgeIcon`, or `RelationIcon`.
+ * @returns The ASCII-only string to render in NO_COLOR contexts.
+ */
+export declare function ascii(icon: AnyIcon): string;
+/**
+ * Options for {@link pickIcon}.
+ */
+export interface PickIconOptions {
+    /**
+     * Force ASCII fallback. When omitted, falls back to `NO_COLOR=1` or
+     * `TERM=dumb` in `process.env`.
+     */
+    noColor?: boolean;
+}
+/**
+ * Returns the icon to render given the current environment.
+ *
+ * Honors `NO_COLOR=1` and `TERM=dumb` for ASCII fallback when `opts.noColor`
+ * is not provided explicitly.
+ *
+ * @param icon - The icon to render.
+ * @param opts - Optional override for NO_COLOR detection.
+ * @returns The emoji icon, or its ASCII equivalent if NO_COLOR mode is active.
+ */
+export declare function pickIcon<I extends AnyIcon>(icon: I, opts?: PickIconOptions): string;
+//# sourceMappingURL=icon.d.ts.map

package/dist/render/icon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon.d.ts","sourceRoot":"","sources":["../../src/render/icon.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,oBAAY,UAAU;IACpB,0CAA0C;IAC1C,OAAO,WAAM;IACb,2BAA2B;IAC3B,MAAM,iBAAO;IACb,mCAAmC;IACnC,IAAI,WAAM;IACV,+CAA+C;IAC/C,OAAO,iBAAO;IACd,uDAAuD;IACvD,QAAQ,iBAAO;IACf,4CAA4C;IAC5C,SAAS,WAAM;CAChB;AAED;;GAEG;AACH,oBAAY,QAAQ;IAClB,qDAAqD;IACrD,IAAI,iBAAO;IACX,mCAAmC;IACnC,IAAI,iBAAO;IACX,yCAAyC;IACzC,IAAI,WAAM;IACV,wDAAwD;IACxD,OAAO,WAAM;IACb,8CAA8C;IAC9C,QAAQ,iBAAO;IACf,kCAAkC;IAClC,GAAG,iBAAO;IACV,oCAAoC;IACpC,OAAO,iBAAO;CACf;AAED;;GAEG;AACH,oBAAY,SAAS;IACnB,iCAAiC;IACjC,KAAK,iBAAO;IACZ;;;;;;;OAOG;IACH,MAAM,iBAAO;IACb,0DAA0D;IAC1D,MAAM,iBAAO;IACb,iDAAiD;IACjD,OAAO,WAAM;IACb,gDAAgD;IAChD,GAAG,WAAM;CACV;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,oEAAoE;IACpE,MAAM,WAAM;IACZ,gDAAgD;IAChD,MAAM,WAAM;IACZ,wDAAwD;IACxD,OAAO,WAAM;IACb,0DAA0D;IAC1D,MAAM,WAAM;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAmD3C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAInF"}

package/dist/render/icon.js

@@ -0,0 +1,163 @@
+/**
+ * Typed icon enums for the human-render contract (ADR-077).
+ *
+ * Single source of truth for the visual language used across all renderers
+ * (tree, table, list, badge). Each enum is emoji-first; `ascii()` returns the
+ * NO_COLOR-safe fallback for non-UTF-8 terminals or `NO_COLOR=1` environments.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Status icons — agent-task lifecycle states.
+ *
+ * Emoji-first; `ascii()` returns a NO_COLOR-safe fallback.
+ */
+export var StatusIcon;
+(function (StatusIcon) {
+    /** Task is queued and has not started. */
+    StatusIcon["PENDING"] = "\u23F3";
+    /** Task is in progress. */
+    StatusIcon["ACTIVE"] = "\uD83D\uDEA7";
+    /** Task completed successfully. */
+    StatusIcon["DONE"] = "\u2705";
+    /** Task is blocked on a dependency or gate. */
+    StatusIcon["BLOCKED"] = "\uD83D\uDEAA";
+    /** Task is archived and no longer actively tracked. */
+    StatusIcon["ARCHIVED"] = "\uD83D\uDDC4";
+    /** Task was cancelled before completion. */
+    StatusIcon["CANCELLED"] = "\u2717";
+})(StatusIcon || (StatusIcon = {}));
+/**
+ * Task-kind icons — Saga / Epic / Task / Subtask plus ancillary kinds.
+ */
+export var KindIcon;
+(function (KindIcon) {
+    /** Saga — multi-release theme grouping ≥ 2 Epics. */
+    KindIcon["SAGA"] = "\uD83C\uDF32";
+    /** Epic — one releasable slice. */
+    KindIcon["EPIC"] = "\uD83D\uDCCB";
+    /** Task — one atomic PR-sized change. */
+    KindIcon["TASK"] = "\u2022";
+    /** Subtask — one commit contributing to a Task's PR. */
+    KindIcon["SUBTASK"] = "\u25E6";
+    /** Research task — investigation or audit. */
+    KindIcon["RESEARCH"] = "\uD83D\uDCD6";
+    /** Bug task — defect tracking. */
+    KindIcon["BUG"] = "\uD83D\uDC1B";
+    /** Release task — shipping work. */
+    KindIcon["RELEASE"] = "\uD83D\uDE80";
+})(KindIcon || (KindIcon = {}));
+/**
+ * Badge icons — flags attached to tasks (empty, orphan, nested, etc).
+ */
+export var BadgeIcon;
+(function (BadgeIcon) {
+    /** Container has no children. */
+    BadgeIcon["EMPTY"] = "\uD83E\uDEA6";
+    /**
+     * Task has no parent and is unreachable from a Saga or Epic.
+     *
+     * NOTE: ADR-077 §2 originally specified `'🚪'`, identical to `StatusIcon.BLOCKED`.
+     * TypeScript string enums share a single runtime string so `ascii()` cannot
+     * disambiguate. Resolved by switching to `'👻'` (abandoned/lonely semantics).
+     * A follow-up ADR amendment lands in T10137 (B12).
+     */
+    BadgeIcon["ORPHAN"] = "\uD83D\uDC7B";
+    /** Task is nested deeper than the depth budget allows. */
+    BadgeIcon["NESTED"] = "\uD83D\uDD01";
+    /** Caution — something needs human attention. */
+    BadgeIcon["CAUTION"] = "\u26A0";
+    /** Recently added — surfaced for visibility. */
+    BadgeIcon["NEW"] = "\u2605";
+})(BadgeIcon || (BadgeIcon = {}));
+/**
+ * Relation icons — edge semantics in tree views.
+ */
+export var RelationIcon;
+(function (RelationIcon) {
+    /** Saga groups Epic via `task_relations.relation_type='groups'`. */
+    RelationIcon["GROUPS"] = "\u2282";
+    /** Parent edge — direct hierarchical parent. */
+    RelationIcon["PARENT"] = "\u2934";
+    /** Depends-on edge — A cannot start until B is done. */
+    RelationIcon["DEPENDS"] = "\u21E8";
+    /** Blocks edge — A actively blocks B from progressing. */
+    RelationIcon["BLOCKS"] = "\u2298";
+})(RelationIcon || (RelationIcon = {}));
+/**
+ * Maps an emoji icon to its NO_COLOR-safe ASCII equivalent.
+ *
+ * Used when stdout is not a UTF-8 TTY or `NO_COLOR=1` is set. Every enum
+ * member has an explicit ASCII fallback — the exhaustive switch ensures the
+ * TypeScript compiler flags any future icon added without an ASCII mapping.
+ *
+ * @param icon - Any icon from `StatusIcon`, `KindIcon`, `BadgeIcon`, or `RelationIcon`.
+ * @returns The ASCII-only string to render in NO_COLOR contexts.
+ */
+export function ascii(icon) {
+    switch (icon) {
+        // Status
+        case StatusIcon.PENDING:
+            return '[ ]';
+        case StatusIcon.ACTIVE:
+            return '[~]';
+        case StatusIcon.DONE:
+            return '[x]';
+        case StatusIcon.BLOCKED:
+            return '[!]';
+        case StatusIcon.ARCHIVED:
+            return '[#]';
+        case StatusIcon.CANCELLED:
+            return '[-]';
+        // Kind
+        case KindIcon.SAGA:
+            return 'SG';
+        case KindIcon.EPIC:
+            return 'E';
+        case KindIcon.TASK:
+            return '-';
+        case KindIcon.SUBTASK:
+            return '.';
+        case KindIcon.RESEARCH:
+            return 'R';
+        case KindIcon.BUG:
+            return 'B';
+        case KindIcon.RELEASE:
+            return '>';
+        // Badge
+        case BadgeIcon.EMPTY:
+            return '(empty)';
+        case BadgeIcon.ORPHAN:
+            return '(orphan)';
+        case BadgeIcon.NESTED:
+            return '(nested)';
+        case BadgeIcon.CAUTION:
+            return '(!)';
+        case BadgeIcon.NEW:
+            return '(new)';
+        // Relation
+        case RelationIcon.GROUPS:
+            return 'in';
+        case RelationIcon.PARENT:
+            return '^';
+        case RelationIcon.DEPENDS:
+            return '->';
+        case RelationIcon.BLOCKS:
+            return '!>';
+    }
+}
+/**
+ * Returns the icon to render given the current environment.
+ *
+ * Honors `NO_COLOR=1` and `TERM=dumb` for ASCII fallback when `opts.noColor`
+ * is not provided explicitly.
+ *
+ * @param icon - The icon to render.
+ * @param opts - Optional override for NO_COLOR detection.
+ * @returns The emoji icon, or its ASCII equivalent if NO_COLOR mode is active.
+ */
+export function pickIcon(icon, opts) {
+    const noColor = opts?.noColor ?? (process.env['NO_COLOR'] === '1' || process.env['TERM'] === 'dumb');
+    return noColor ? ascii(icon) : icon;
+}
+//# sourceMappingURL=icon.js.map

package/dist/render/icon.js.map

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

package/dist/render/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Barrel for the typed render contracts (Epic T10114, ADR-077).
+ *
+ * Icon enums are intentionally omitted — they ship with T10127 (B2).
+ *
+ * @epic T10114
+ */
+export type { RenderableEnvelope, SectionResponse } from './envelope.js';
+export { isGenericEnvelope, isGroupedListEnvelope, isListEnvelope, isSectionEnvelope, isSingleEnvelope, isTableEnvelope, isTreeEnvelope, } from './envelope.js';
+export type { GroupedListResponse, ListGroup, ListItemStyle, ListResponse, } from './list.js';
+export { isGroupedListResponse, isListResponse } from './list.js';
+export type { ColumnAlign, TableColumn, TableResponse, TableSchema, } from './table.js';
+export { isTableResponse } from './table.js';
+export type { FlatTreeNode, RenderTreeOptions, TreeNodeKind, TreeNodeStatus, TreeResponse, } from './tree.js';
+export { isTreeResponse } from './tree.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/render/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/render/index.js

@@ -0,0 +1,12 @@
+/**
+ * Barrel for the typed render contracts (Epic T10114, ADR-077).
+ *
+ * Icon enums are intentionally omitted — they ship with T10127 (B2).
+ *
+ * @epic T10114
+ */
+export { isGenericEnvelope, isGroupedListEnvelope, isListEnvelope, isSectionEnvelope, isSingleEnvelope, isTableEnvelope, isTreeEnvelope, } from './envelope.js';
+export { isGroupedListResponse, isListResponse } from './list.js';
+export { isTableResponse } from './table.js';
+export { isTreeResponse } from './tree.js';
+//# sourceMappingURL=index.js.map

package/dist/render/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,eAAe,CAAC;AAOvB,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAOlE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAQ7C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/render/list.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Typed render contracts — list (flat) and grouped-list.
+ *
+ * Part of the Human Render Contract (Epic T10114, ADR-077). The list shape is
+ * the canonical wire format for ordered or grouped sequential output —
+ * presenters render each item according to `renderItem` (or a default).
+ *
+ * @epic T10114
+ * @task T10140
+ */
+/**
+ * Per-item rendering style hint for list responses.
+ *
+ * - `'text'`   — render the item as a plain string (default presenter behaviour).
+ * - `'badge'`  — render with status / category styling.
+ * - `'kv'`     — render as a key/value pair block.
+ */
+export type ListItemStyle = 'text' | 'badge' | 'kv';
+/**
+ * Flat list response — items rendered in `items` order.
+ *
+ * @typeParam T — caller-defined item payload shape.
+ */
+export interface ListResponse<T> {
+    /** Item payloads in render order. */
+    readonly items: ReadonlyArray<T>;
+    /**
+     * Total item count. May exceed `items.length` when the response is paginated
+     * or truncated.
+     */
+    readonly total: number;
+    /** Optional per-item rendering style hint. */
+    readonly renderItem?: ListItemStyle;
+}
+/**
+ * One labelled bucket inside a grouped list response.
+ *
+ * @typeParam T — caller-defined item payload shape.
+ */
+export interface ListGroup<T> {
+    /** Stable group identifier — used for diff / equality, not display. */
+    readonly key: string;
+    /** Human-readable group label rendered above its items. */
+    readonly label: string;
+    /** Item payloads inside this group, in render order. */
+    readonly items: ReadonlyArray<T>;
+}
+/**
+ * Grouped list response — items split across labelled buckets.
+ *
+ * @typeParam T — caller-defined item payload shape.
+ */
+export interface GroupedListResponse<T> {
+    /** Ordered list of labelled groups. */
+    readonly groups: ReadonlyArray<ListGroup<T>>;
+    /** Total item count across all groups. */
+    readonly total: number;
+}
+/**
+ * Runtime type guard for `ListResponse<T>`.
+ *
+ * Checks the envelope shape only — does not inspect item payloads against `T`.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `ListResponse<T>` envelope shape.
+ */
+export declare function isListResponse<T>(value: unknown): value is ListResponse<T>;
+/**
+ * Runtime type guard for `GroupedListResponse<T>`.
+ *
+ * Checks the envelope shape only — does not inspect item payloads against `T`.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `GroupedListResponse<T>` envelope shape.
+ */
+export declare function isGroupedListResponse<T>(value: unknown): value is GroupedListResponse<T>;
+//# sourceMappingURL=list.d.ts.map

package/dist/render/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/render/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC,CAI1E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAAC,CAAC,CAAC,CAIxF"}

package/dist/render/list.js

@@ -0,0 +1,39 @@
+/**
+ * Typed render contracts — list (flat) and grouped-list.
+ *
+ * Part of the Human Render Contract (Epic T10114, ADR-077). The list shape is
+ * the canonical wire format for ordered or grouped sequential output —
+ * presenters render each item according to `renderItem` (or a default).
+ *
+ * @epic T10114
+ * @task T10140
+ */
+/**
+ * Runtime type guard for `ListResponse<T>`.
+ *
+ * Checks the envelope shape only — does not inspect item payloads against `T`.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `ListResponse<T>` envelope shape.
+ */
+export function isListResponse(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return Array.isArray(v.items) && typeof v.total === 'number';
+}
+/**
+ * Runtime type guard for `GroupedListResponse<T>`.
+ *
+ * Checks the envelope shape only — does not inspect item payloads against `T`.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `GroupedListResponse<T>` envelope shape.
+ */
+export function isGroupedListResponse(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return Array.isArray(v.groups) && typeof v.total === 'number';
+}
+//# sourceMappingURL=list.js.map

package/dist/render/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/render/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsDH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAI,KAAc;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC;AAC/D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAI,KAAc;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC;AAChE,CAAC"}

package/dist/render/table.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Typed render contracts — table (column-schema-driven rows).
+ *
+ * Part of the Human Render Contract (Epic T10114, ADR-077). The table shape is
+ * the canonical wire format for tabular CLI output — presenters consume the
+ * schema to compute widths, headers, and per-cell formatting.
+ *
+ * @epic T10114
+ * @task T10139
+ */
+/**
+ * Horizontal alignment hint for a column.
+ */
+export type ColumnAlign = 'left' | 'right' | 'center';
+/**
+ * Schema entry for a single table column.
+ *
+ * `key` MUST be a string-typed property on the row payload `T`. Presenters
+ * are expected to extract `row[column.key]` and pipe it through `format` when
+ * one is supplied.
+ *
+ * @typeParam T — caller-defined row payload shape.
+ */
+export interface TableColumn<T> {
+    /** Property key on the row payload. */
+    readonly key: keyof T & string;
+    /** Display header rendered above the column. */
+    readonly header: string;
+    /** Optional alignment hint. Defaults to `'left'`. */
+    readonly align?: ColumnAlign;
+    /** Optional fixed width (character count) hint. */
+    readonly width?: number;
+    /**
+     * Optional per-cell formatter. Receives the raw value at `row[key]` and
+     * returns the display string. When absent, presenters call `String(value)`.
+     */
+    readonly format?: (value: unknown) => string;
+}
+/**
+ * Column-schema metadata that accompanies every table response.
+ *
+ * @typeParam T — caller-defined row payload shape.
+ */
+export interface TableSchema<T> {
+    /** Ordered list of column descriptors. Rendering order matches this order. */
+    readonly columns: ReadonlyArray<TableColumn<T>>;
+}
+/**
+ * Top-level envelope returned by a table-shaped renderer.
+ *
+ * @typeParam T — caller-defined row payload shape.
+ */
+export interface TableResponse<T> {
+    /** Row payloads in the order they should be rendered. */
+    readonly rows: ReadonlyArray<T>;
+    /** Column schema — drives presenter formatting. */
+    readonly schema: TableSchema<T>;
+    /**
+     * Total row count. May exceed `rows.length` when the response is paginated
+     * or truncated; presenters use this to render "showing N of M" hints.
+     */
+    readonly total: number;
+}
+/**
+ * Runtime type guard for `TableResponse<T>`.
+ *
+ * Checks the envelope shape only — does not inspect row payloads against `T`.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `TableResponse<T>` envelope shape.
+ */
+export declare function isTableResponse<T>(value: unknown): value is TableResponse<T>;
+//# sourceMappingURL=table.d.ts.map

package/dist/render/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/render/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,CAQ5E"}

package/dist/render/table.js

@@ -0,0 +1,32 @@
+/**
+ * Typed render contracts — table (column-schema-driven rows).
+ *
+ * Part of the Human Render Contract (Epic T10114, ADR-077). The table shape is
+ * the canonical wire format for tabular CLI output — presenters consume the
+ * schema to compute widths, headers, and per-cell formatting.
+ *
+ * @epic T10114
+ * @task T10139
+ */
+/**
+ * Runtime type guard for `TableResponse<T>`.
+ *
+ * Checks the envelope shape only — does not inspect row payloads against `T`.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `TableResponse<T>` envelope shape.
+ */
+export function isTableResponse(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (!Array.isArray(v.rows))
+        return false;
+    if (typeof v.total !== 'number')
+        return false;
+    const schema = v.schema;
+    if (typeof schema !== 'object' || schema === null)
+        return false;
+    return Array.isArray(schema.columns);
+}
+//# sourceMappingURL=table.js.map

package/dist/render/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../src/render/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA2DH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAI,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,MAAM,GAAG,CAAC,CAAC,MAA6C,CAAC;IAC/D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChE,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC"}

package/dist/render/tree.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Typed render contracts — tree (flattened hierarchy).
+ *
+ * Part of the Human Render Contract (Epic T10114, ADR-077). The flat-tree shape
+ * is the canonical wire format for hierarchical task / saga / epic listings —
+ * presenters re-materialise the parent/child structure from `parentId` + `depth`.
+ *
+ * @epic T10114
+ * @task T10138
+ */
+/**
+ * Discriminator for a node's place in the task hierarchy.
+ *
+ * Matches the CLEO 4-tier task model (Saga → Epic → Task → Subtask).
+ */
+export type TreeNodeKind = 'saga' | 'epic' | 'task' | 'subtask';
+/**
+ * Lifecycle status of a tree node.
+ *
+ * Mirrors the canonical task status union used across CLEO.
+ */
+export type TreeNodeStatus = 'pending' | 'in_progress' | 'done' | 'blocked' | 'cancelled' | 'archived';
+/**
+ * One row in a flattened tree response.
+ *
+ * `parentId === null` identifies the root. `depth` is the integer distance
+ * from the root (root is `0`). `metadata` is the caller-defined payload —
+ * presenters MUST NOT assume any specific shape beyond `T`.
+ *
+ * @typeParam T — caller-defined metadata payload attached to the node.
+ */
+export interface FlatTreeNode<T> {
+    /** Stable, unique identifier (typically a CLEO task ID such as `T1234`). */
+    readonly id: string;
+    /** Parent identifier, or `null` if this row is the root. */
+    readonly parentId: string | null;
+    /** Integer distance from the root (root = `0`). */
+    readonly depth: number;
+    /** Discriminator slot in the CLEO 4-tier model. */
+    readonly kind: TreeNodeKind;
+    /** Lifecycle status. */
+    readonly status: TreeNodeStatus;
+    /** Display title — short enough to render on a single line. */
+    readonly title: string;
+    /** Caller-defined metadata payload. */
+    readonly metadata: T;
+}
+/**
+ * Top-level envelope returned by a tree-shaped renderer.
+ *
+ * @typeParam T — caller-defined metadata payload attached to each node.
+ */
+export interface TreeResponse<T> {
+    /** Flattened list of nodes in pre-order traversal. */
+    readonly tree: ReadonlyArray<FlatTreeNode<T>>;
+    /** Identifier of the root node — must match a node in `tree` with `parentId === null`. */
+    readonly root: string;
+    /** Total number of nodes — equal to `tree.length`. */
+    readonly totalNodes: number;
+    /** Maximum `depth` seen across `tree`. `0` for a single-node tree. */
+    readonly maxDepth: number;
+}
+/**
+ * Caller-supplied options that shape a tree response.
+ *
+ * All fields are optional. Presenters interpret unset fields as "no constraint"
+ * (e.g. unset `depth` means render the full tree).
+ */
+export interface RenderTreeOptions {
+    /** Cap the maximum depth rendered. */
+    readonly depth?: number;
+    /** Restrict the rendered node kinds. */
+    readonly kinds?: ReadonlyArray<TreeNodeKind>;
+    /** When `true`, presenters may emit unicode icons next to each row. */
+    readonly icons?: boolean;
+    /** When set, collapse subtrees beyond this child-count threshold. */
+    readonly foldAt?: number;
+    /** When `true`, presenters MAY annotate inter-task dependencies. */
+    readonly withDeps?: boolean;
+    /** When `true`, presenters MAY annotate blocker relationships. */
+    readonly withBlockers?: boolean;
+}
+/**
+ * Runtime type guard for `TreeResponse<T>`.
+ *
+ * Verifies the envelope shape without inspecting node payloads — the generic
+ * `T` cannot be checked at runtime, so callers must layer per-node validation
+ * separately if they need stronger guarantees.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `TreeResponse<T>` envelope shape.
+ */
+export declare function isTreeResponse<T>(value: unknown): value is TreeResponse<T>;
+//# sourceMappingURL=tree.d.ts.map