@cleocode/contracts 2026.5.103 → 2026.5.105

package/src/render/__tests__/envelope.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Compile-time + runtime narrowing tests for `RenderableEnvelope<T>` and the
+ * per-kind type guards.
+ *
+ * Each test constructs a valid envelope of a single `kind` and asserts that
+ * the matching guard narrows it correctly while every other guard returns
+ * `false`. This catches both schema drift and accidental short-circuits in
+ * the guards.
+ *
+ * @epic T10114
+ * @task T10141
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  isGenericEnvelope,
+  isGroupedListEnvelope,
+  isListEnvelope,
+  isSectionEnvelope,
+  isSingleEnvelope,
+  isTableEnvelope,
+  isTreeEnvelope,
+  type RenderableEnvelope,
+} from '../envelope.js';
+import { isGroupedListResponse, isListResponse } from '../list.js';
+import { isTableResponse } from '../table.js';
+import { isTreeResponse } from '../tree.js';
+
+interface Sample {
+  readonly x: number;
+}
+
+describe('RenderableEnvelope<T> discriminated-union narrowing', () => {
+  it('narrows the tree variant and rejects all others', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'tree',
+      data: { tree: [], root: 'T1', totalNodes: 0, maxDepth: 0 },
+    };
+    expect(isTreeEnvelope(env)).toBe(true);
+    expect(isTableEnvelope(env)).toBe(false);
+    expect(isListEnvelope(env)).toBe(false);
+    expect(isGroupedListEnvelope(env)).toBe(false);
+    expect(isSectionEnvelope(env)).toBe(false);
+    expect(isSingleEnvelope(env)).toBe(false);
+    expect(isGenericEnvelope(env)).toBe(false);
+    if (isTreeEnvelope(env)) {
+      expect(env.data.root).toBe('T1');
+    } else {
+      throw new Error('expected tree narrowing');
+    }
+  });
+
+  it('narrows the table variant and rejects all others', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'table',
+      data: {
+        rows: [{ x: 1 }],
+        schema: { columns: [{ key: 'x', header: 'X' }] },
+        total: 1,
+      },
+    };
+    expect(isTableEnvelope(env)).toBe(true);
+    expect(isTreeEnvelope(env)).toBe(false);
+    if (isTableEnvelope(env)) {
+      expect(env.data.rows[0]?.x).toBe(1);
+    } else {
+      throw new Error('expected table narrowing');
+    }
+  });
+
+  it('narrows the flat list variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'list',
+      data: { items: [{ x: 7 }], total: 1, renderItem: 'kv' },
+    };
+    expect(isListEnvelope(env)).toBe(true);
+    expect(isGroupedListEnvelope(env)).toBe(false);
+    if (isListEnvelope(env)) {
+      expect(env.data.items[0]?.x).toBe(7);
+      expect(env.data.renderItem).toBe('kv');
+    } else {
+      throw new Error('expected list narrowing');
+    }
+  });
+
+  it('narrows the grouped-list variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'grouped-list',
+      data: {
+        groups: [{ key: 'a', label: 'A', items: [{ x: 2 }] }],
+        total: 1,
+      },
+    };
+    expect(isGroupedListEnvelope(env)).toBe(true);
+    expect(isListEnvelope(env)).toBe(false);
+    if (isGroupedListEnvelope(env)) {
+      expect(env.data.groups[0]?.items[0]?.x).toBe(2);
+    } else {
+      throw new Error('expected grouped-list narrowing');
+    }
+  });
+
+  it('narrows the section variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'section',
+      data: { header: 'Summary', icon: 'i', items: ['a', 'b'] },
+    };
+    expect(isSectionEnvelope(env)).toBe(true);
+    if (isSectionEnvelope(env)) {
+      expect(env.data.items).toEqual(['a', 'b']);
+    } else {
+      throw new Error('expected section narrowing');
+    }
+  });
+
+  it('narrows the single variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'single',
+      data: { x: 42 },
+    };
+    expect(isSingleEnvelope(env)).toBe(true);
+    if (isSingleEnvelope(env)) {
+      expect(env.data.x).toBe(42);
+    } else {
+      throw new Error('expected single narrowing');
+    }
+  });
+
+  it('narrows the generic variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'generic',
+      data: { foo: 'bar', count: 3 },
+    };
+    expect(isGenericEnvelope(env)).toBe(true);
+    if (isGenericEnvelope(env)) {
+      expect(env.data.foo).toBe('bar');
+    } else {
+      throw new Error('expected generic narrowing');
+    }
+  });
+
+  it('exhaustively switches on kind without falling through', () => {
+    const envelopes: Array<RenderableEnvelope<Sample>> = [
+      { kind: 'tree', data: { tree: [], root: 'r', totalNodes: 0, maxDepth: 0 } },
+      {
+        kind: 'table',
+        data: { rows: [], schema: { columns: [] }, total: 0 },
+      },
+      { kind: 'list', data: { items: [], total: 0 } },
+      { kind: 'grouped-list', data: { groups: [], total: 0 } },
+      { kind: 'section', data: { header: 'h', items: [] } },
+      { kind: 'single', data: { x: 0 } },
+      { kind: 'generic', data: {} },
+    ];
+    const seen = new Set<RenderableEnvelope<Sample>['kind']>();
+    for (const env of envelopes) {
+      switch (env.kind) {
+        case 'tree':
+        case 'table':
+        case 'list':
+        case 'grouped-list':
+        case 'section':
+        case 'single':
+        case 'generic':
+          seen.add(env.kind);
+          break;
+        default: {
+          const _exhaustive: never = env;
+          throw new Error(`unreachable: ${JSON.stringify(_exhaustive)}`);
+        }
+      }
+    }
+    expect(seen.size).toBe(7);
+  });
+});
+
+describe('per-response type guards', () => {
+  it('accepts valid response shapes', () => {
+    expect(isTreeResponse({ tree: [], root: 'r', totalNodes: 0, maxDepth: 0 })).toBe(true);
+    expect(isTableResponse({ rows: [], schema: { columns: [] }, total: 0 })).toBe(true);
+    expect(isListResponse({ items: [], total: 0 })).toBe(true);
+    expect(isGroupedListResponse({ groups: [], total: 0 })).toBe(true);
+  });
+
+  it('rejects invalid response shapes', () => {
+    expect(isTreeResponse(null)).toBe(false);
+    expect(isTreeResponse({})).toBe(false);
+    expect(isTreeResponse({ tree: 'nope', root: 'r', totalNodes: 0, maxDepth: 0 })).toBe(false);
+    expect(isTableResponse({ rows: [], total: 0 })).toBe(false);
+    expect(isTableResponse({ rows: [], schema: 'nope', total: 0 })).toBe(false);
+    expect(isListResponse({ items: 'nope', total: 0 })).toBe(false);
+    expect(isGroupedListResponse({ groups: 'nope', total: 0 })).toBe(false);
+  });
+});

package/src/render/envelope.ts

@@ -0,0 +1,112 @@
+/**
+ * Typed render contracts — top-level `RenderableEnvelope<T>` discriminated union.
+ *
+ * Part of the Human Render Contract (Epic T10114, ADR-077). Every renderable
+ * value flowing from CLEO commands to presenters MUST be wrapped in one of the
+ * variants below. Presenters dispatch on `kind` to pick the right renderer.
+ *
+ * @epic T10114
+ * @task T10141
+ */
+
+import type { GroupedListResponse, ListResponse } from './list.js';
+import type { TableResponse } from './table.js';
+import type { TreeResponse } from './tree.js';
+
+/**
+ * Free-form section block — a labelled header with an ordered set of
+ * pre-formatted item strings. Used for ad-hoc human output that doesn't fit
+ * the structured `tree` / `table` / `list` shapes.
+ */
+export interface SectionResponse {
+  /** Heading rendered above the items. */
+  readonly header: string;
+  /** Optional icon hint — presenters MAY prepend it to the header. */
+  readonly icon?: string;
+  /** Pre-formatted item strings rendered as a bulleted block. */
+  readonly items: ReadonlyArray<string>;
+}
+
+/**
+ * Discriminated union of every renderable envelope variant CLEO presenters
+ * understand.
+ *
+ * The `kind` field is the discriminator — narrow on it inside a `switch`
+ * statement or via the per-kind type guards exported below.
+ *
+ * @typeParam T — caller-defined payload shape. For `single` it is the entire
+ *                payload; for the collection variants it parameterises the
+ *                inner response type. `section` and `generic` are independent
+ *                of `T`.
+ */
+export type RenderableEnvelope<T> =
+  | { readonly kind: 'tree'; readonly data: TreeResponse<T> }
+  | { readonly kind: 'table'; readonly data: TableResponse<T> }
+  | { readonly kind: 'list'; readonly data: ListResponse<T> }
+  | { readonly kind: 'grouped-list'; readonly data: GroupedListResponse<T> }
+  | { readonly kind: 'section'; readonly data: SectionResponse }
+  | { readonly kind: 'single'; readonly data: T }
+  | { readonly kind: 'generic'; readonly data: Record<string, unknown> };
+
+/**
+ * Type guard — narrows to the `tree` variant.
+ */
+export function isTreeEnvelope<T>(
+  env: RenderableEnvelope<T>,
+): env is Extract<RenderableEnvelope<T>, { kind: 'tree' }> {
+  return env.kind === 'tree';
+}
+
+/**
+ * Type guard — narrows to the `table` variant.
+ */
+export function isTableEnvelope<T>(
+  env: RenderableEnvelope<T>,
+): env is Extract<RenderableEnvelope<T>, { kind: 'table' }> {
+  return env.kind === 'table';
+}
+
+/**
+ * Type guard — narrows to the flat `list` variant.
+ */
+export function isListEnvelope<T>(
+  env: RenderableEnvelope<T>,
+): env is Extract<RenderableEnvelope<T>, { kind: 'list' }> {
+  return env.kind === 'list';
+}
+
+/**
+ * Type guard — narrows to the `grouped-list` variant.
+ */
+export function isGroupedListEnvelope<T>(
+  env: RenderableEnvelope<T>,
+): env is Extract<RenderableEnvelope<T>, { kind: 'grouped-list' }> {
+  return env.kind === 'grouped-list';
+}
+
+/**
+ * Type guard — narrows to the `section` variant.
+ */
+export function isSectionEnvelope<T>(
+  env: RenderableEnvelope<T>,
+): env is Extract<RenderableEnvelope<T>, { kind: 'section' }> {
+  return env.kind === 'section';
+}
+
+/**
+ * Type guard — narrows to the `single` variant.
+ */
+export function isSingleEnvelope<T>(
+  env: RenderableEnvelope<T>,
+): env is Extract<RenderableEnvelope<T>, { kind: 'single' }> {
+  return env.kind === 'single';
+}
+
+/**
+ * Type guard — narrows to the `generic` variant.
+ */
+export function isGenericEnvelope<T>(
+  env: RenderableEnvelope<T>,
+): env is Extract<RenderableEnvelope<T>, { kind: 'generic' }> {
+  return env.kind === 'generic';
+}

package/src/render/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 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';

package/src/render/list.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 function isListResponse<T>(value: unknown): value is ListResponse<T> {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  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<T>(value: unknown): value is GroupedListResponse<T> {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return Array.isArray(v.groups) && typeof v.total === 'number';
+}

package/src/render/table.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 function isTableResponse<T>(value: unknown): value is TableResponse<T> {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (!Array.isArray(v.rows)) return false;
+  if (typeof v.total !== 'number') return false;
+  const schema = v.schema as Record<string, unknown> | undefined;
+  if (typeof schema !== 'object' || schema === null) return false;
+  return Array.isArray(schema.columns);
+}

package/src/render/tree.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 function isTreeResponse<T>(value: unknown): value is TreeResponse<T> {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    Array.isArray(v.tree) &&
+    typeof v.root === 'string' &&
+    typeof v.totalNodes === 'number' &&
+    typeof v.maxDepth === 'number'
+  );
+}