@north-light/api 0.3.580 → 0.3.588

package/dist/clients/inbox/tui/types.d.ts

@@ -0,0 +1,73 @@
+import type { Key } from './keys.js';
+import type { ProductPageComponents } from '../../../types.js';
+import type { PageCommentAnchor, PageManifest, PageResponses, PageSlot, SlotResponse } from '../../../core/human/page-schema.js';
+export type Phase = 'overview' | 'item-review' | 'final';
+export type InputMode = null | {
+    kind: 'comment';
+    buffer: string;
+    cursor: number;
+    anchor: PageCommentAnchor;
+} | {
+    kind: 'freetext';
+    buffer: string;
+    cursor: number;
+} | {
+    kind: 'text';
+    buffer: string;
+    cursor: number;
+};
+export interface TuiState {
+    phase: Phase;
+    currentIndex: number;
+    manifest: PageManifest;
+    /** The authored display JSX (headings, paragraphs, prose outside slots),
+     *  projected to markdown — same projection the inline chat block uses.
+     *  Empty when the page has none, or its document was unavailable. */
+    displayMarkdown: string;
+    slots: PageSlot[];
+    responses: Map<string, SlotResponse>;
+    productKinds: ProductPageComponents;
+    inputMode: InputMode;
+    selectedAction: number;
+    scrollOffset: number;
+    /** Whether the overview window is following the j/k selection. Set by moving
+     *  the selection, cleared the moment the user scrolls the window themselves —
+     *  otherwise the follow would drag the window back on every manual scroll. */
+    followSelection: boolean;
+    hscrollOffset: number;
+    hscrollMax: number;
+    wrapWidth: number;
+    editorAvailable: boolean;
+    hint?: string;
+    persist?: () => void;
+}
+export interface MountedPanelOpts {
+    manifest: PageManifest;
+    /** The raw page document — needed only to project display markdown; a jsx
+     *  page without one just shows no display content, same as a read failure. */
+    document?: string;
+    productKinds?: ProductPageComponents;
+    initialResponses?: PageResponses | null;
+    cols: number;
+    rows: number;
+    onEditorRequest?: () => void;
+    onProgress?: (responses: PageResponses) => void;
+    onComplete?: (responses: PageResponses) => void;
+    onExit?: () => void;
+    onDirty?: () => void;
+}
+export interface MountedPanel {
+    handleKey(input: string, key: Key): void;
+    render(): string[];
+    handleResize(cols: number, rows: number): string[];
+    unmount(): void;
+    loadPage(manifest: PageManifest, opts?: {
+        document?: string;
+        initialResponses?: PageResponses | null;
+        productKinds?: ProductPageComponents;
+    }): void;
+    canAcceptHostKeys(): boolean;
+    atPageTop(): boolean;
+    getInputBuffer(): string | undefined;
+    setInputBuffer(text: string): void;
+}

package/dist/clients/inbox/tui/types.js

@@ -0,0 +1 @@
+export {};

package/dist/clients/inbox/tui.d.ts

@@ -0,0 +1,17 @@
+import type { InboxRow } from './dto-adapt.js';
+export declare const KIND_ICON: Record<string, string>;
+export declare const KIND_COLOR: Record<string, string>;
+export declare function formatTimeAgo(iso: string): string;
+/** What the list is currently showing, and the key that changes it. */
+export interface InboxScope {
+    /** Display name of the active scope; never used to decide membership. */
+    label: string;
+    /** Toggle hint, absent when there is no other scope to reach. */
+    hint?: string;
+}
+/** Pure inbox rows; selection and terminal ownership belong to InboxController.
+ *  The header carries the scope and its toggle whether or not anything is
+ *  listed: an empty list is when the reader most needs the way to the rest. */
+export declare function buildInboxLines(items: InboxRow[], width: number, selectedIndex: number, scope: InboxScope, height?: number): string[];
+/** What the agent suggests, for a row that says so without opening the page. */
+export declare function recommendedLabel(item: InboxRow): string | undefined;

package/dist/clients/inbox/tui.js

@@ -0,0 +1,92 @@
+import { RESET, BOLD, DIM, ITALIC, CYAN, RED, GRAY, YELLOW, truncateRow } from './tui/ansi.js';
+function ansiColor(text, color) {
+    switch (color) {
+        case 'gray': return `${GRAY}${text}${RESET}`;
+        case 'cyan': return `${CYAN}${text}${RESET}`;
+        case 'red': return `${RED}${text}${RESET}`;
+        case 'yellow': return `${YELLOW}${text}${RESET}`;
+        default: return text;
+    }
+}
+export const KIND_ICON = { notify: '✉', decision: '◆', context: '✎', error: '⚠', review: '▤', display: '✉', rich: '▣', interactive: '◆' };
+export const KIND_COLOR = { notify: 'gray', decision: 'cyan', context: 'cyan', error: 'red', review: 'yellow', display: 'gray', rich: 'cyan', interactive: 'cyan' };
+export function formatTimeAgo(iso) {
+    const minutes = Math.floor((Date.now() - new Date(iso).getTime()) / 60000);
+    if (minutes >= 60)
+        return `${Math.floor(minutes / 60)}h ago`;
+    if (minutes > 0)
+        return `${minutes}m ago`;
+    return 'just now';
+}
+/** Pure inbox rows; selection and terminal ownership belong to InboxController.
+ *  The header carries the scope and its toggle whether or not anything is
+ *  listed: an empty list is when the reader most needs the way to the rest. */
+export function buildInboxLines(items, width, selectedIndex, scope, height = Number.MAX_SAFE_INTEGER) {
+    const header = [`  ${BOLD}${items.length} pending${RESET}  ${DIM}· ${scope.label}${RESET}`];
+    if (scope.hint !== undefined)
+        header.push(`  ${DIM}${scope.hint}${RESET}`);
+    header.push('');
+    if (items.length === 0)
+        return [...header, `  ${DIM}${ITALIC}No pending interactions${RESET}`];
+    const contentWidth = width - 4;
+    const itemLines = items.map((item, index) => buildItemLines(item, index, selectedIndex, contentWidth));
+    const window = visibleWindow(itemLines, selectedIndex, Math.max(1, height - header.length));
+    const lines = [...header];
+    if (window.start > 0)
+        lines.push(`  ${DIM}↑ ${window.start} above${RESET}`);
+    for (let index = window.start; index < window.end; index++)
+        lines.push(...itemLines[index]);
+    if (window.end < items.length)
+        lines.push(`  ${DIM}↓ ${items.length - window.end} below${RESET}`);
+    return lines;
+}
+function buildItemLines(item, index, selectedIndex, contentWidth) {
+    const kind = item.kind === 'page'
+        ? item.awaitsResponse === false ? 'display' : 'rich'
+        : item.kind;
+    const icon = KIND_ICON[kind] ?? '·';
+    // The inbox is a title-first triage surface. Origin details remain available
+    // after opening a ticket, rather than consuming the list's scarce row width.
+    const age = formatTimeAgo(item.kind === 'page' ? item.emittedAt : item.blockedSince);
+    const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
+    const titleWidth = Math.max(1, contentWidth - age.length - 6);
+    const row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} ${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
+    const subtitle = item.claim ? `claimed by ${item.claim.owner} · ${item.subtitle}` : item.subtitle;
+    const lines = [row, `      ${DIM}${truncateRow(subtitle, contentWidth - 6)}${RESET}`];
+    const recommended = recommendedLabel(item);
+    if (recommended !== undefined)
+        lines.push(`      ${DIM}Recommended: ${truncateRow(recommended, Math.max(1, contentWidth - 19))}${RESET}`);
+    return lines;
+}
+/** What the agent suggests, for a row that says so without opening the page. */
+export function recommendedLabel(item) {
+    if (item.kind !== 'page' || item.recommendedOptions.length === 0)
+        return undefined;
+    return item.recommendedOptions.map((option) => option.label).join(' · ');
+}
+/** Select a contiguous row window that always contains the selected ticket. */
+function visibleWindow(rows, selectedIndex, capacity) {
+    let start = Math.max(0, Math.min(selectedIndex, rows.length - 1));
+    let end = start + 1;
+    let preferBelow = true;
+    while (true) {
+        const below = end < rows.length ? { start, end: end + 1 } : undefined;
+        const above = start > 0 ? { start: start - 1, end } : undefined;
+        const preferred = preferBelow ? [below, above] : [above, below];
+        const next = preferred.find((candidate) => candidate !== undefined && windowHeight(rows, candidate.start, candidate.end) <= capacity);
+        if (next === undefined)
+            break;
+        start = next.start;
+        end = next.end;
+        preferBelow = !preferBelow;
+    }
+    return { start, end };
+}
+function windowHeight(rows, start, end) {
+    let height = start > 0 ? 1 : 0;
+    for (let index = start; index < end; index++)
+        height += rows[index].length;
+    if (end < rows.length)
+        height++;
+    return height;
+}

package/dist/clients/surfaces/host.d.ts

@@ -0,0 +1,74 @@
+import type { Component } from '@earendil-works/pi-tui';
+/**
+ * A surface root: a pi-tui component rendered inside a host-assigned rectangle.
+ * The host pushes the rectangle height before every render and on resize; a
+ * surface must render exactly that many rows and must not read terminal or
+ * process geometry itself. A surface must never place its cursor marker on row
+ * 0, which is reserved for host notices.
+ */
+export interface SurfaceComponent extends Component {
+    /** Set the number of rows assigned by the host for the next render. */
+    setRows(rows: number): void;
+    /** Consume wheel input when applicable. */
+    handleWheel?(direction: 'up' | 'down', lines: number): boolean;
+}
+/** The identities used for mounted surfaces. */
+export type SurfaceId = 'inbox' | 'review';
+/** How long a notice stays up. */
+export interface SurfaceNoticeOptions {
+    /** Keep the notice up until it is replaced or cleared, with no auto-clear. */
+    sticky?: boolean;
+}
+/**
+ * The only host boundary available to a surface. Surfaces render only through
+ * the mounted component and use {@link notice} as their only output channel;
+ * they never write to the terminal, stdout, stderr, or raw input themselves.
+ */
+export interface SurfaceHost {
+    /**
+     * Mount a component into the host-assigned full rectangle. When the focused
+     * input component differs from the rendered root, pass it as `focus` so
+     * input and cursor ownership remain with that component.
+     */
+    mount(component: SurfaceComponent, opts?: {
+        focus?: Component;
+    }): SurfaceHandle;
+    /** Report transient output through the host; this is the only surface output channel. */
+    notice(text: string, opts?: SurfaceNoticeOptions): void;
+    /**
+     * Temporarily release the terminal for a child process and return a resume
+     * closure. Callers must invoke the closure in a `finally` block.
+     */
+    suspendForChild(): () => void;
+    /** Bring a node's viewer to the front; failures are reported through notice and never reject. */
+    focusNode(nodeId: string): Promise<boolean>;
+    /** Mount the shared review-file picker and resolve to its chosen path or null on cancellation. */
+    pickReviewFile(spec: {
+        candidates: readonly string[];
+        cwd: string;
+        title?: string;
+    }): Promise<string | null>;
+    /** Capability facts resolved once by the host for this session. */
+    readonly capabilities: {
+        /** True when this viewer is attached to a remote session. */
+        readonly remote: boolean;
+        /** True when focusing another node's viewer is available. */
+        readonly canFocusNode: boolean;
+        /** This viewer's own tmux pane — the target a surface splits against.
+         *  Undefined outside tmux. */
+        readonly selfPane: string | undefined;
+    };
+}
+/** A mounted surface's lifecycle controls. */
+export interface SurfaceHandle {
+    /** Close this surface and any surfaces mounted above it. Idempotent. */
+    close(): void;
+    /** Mark the surface dirty; the host schedules a redraw rather than drawing synchronously. */
+    invalidate(): void;
+    /**
+     * Register the only sanctioned teardown hook for timers, watchers, listeners,
+     * and poll re-arms. Closing initiates both synchronous and asynchronous
+     * cleanup; asynchronous cleanup is not awaited by the host.
+     */
+    onClose(fn: () => void | Promise<void>): void;
+}

package/dist/clients/surfaces/host.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/api-client.d.ts

@@ -0,0 +1,113 @@
+import { CrtrClient } from '../api/index.js';
+import { CrtrError } from '../core/errors.js';
+import type { CanvasSource } from '../core/canvas/source.js';
+import type { NodeStatus, SubscriptionRef } from '../core/canvas/types.js';
+import type { Scope } from '../types.js';
+import type { NodeDetailDTO } from '../api/dto/nodes.js';
+import type { NodeMeta, NodeRow } from '../core/canvas/types.js';
+import type { RosterDTO } from '../api/dto/canvas.js';
+import type { ReportDTO } from '../api/index.js';
+/** Rethrow an `ApiError` as the clean structured CLI error agents parse
+ *  (`core/io` `handle`) — instead of the generic "internal bug" stderr path a
+ *  raw non-`CrtrError` throw would take. The mapping itself lives in ONE place
+ *  (`apiErrorToCliError`, `core/io.ts`); this is the explicit-catch helper a
+ *  leaf uses when it wants to attach a call-site `next` hint. Non-`ApiError`
+ *  throws propagate unchanged (a genuine bug still reads as `internal`). Typed
+ *  `never` so callers can use it as the tail of a `catch` without confusing
+ *  definite assignment. */
+export declare function rethrowAsCliError(err: unknown, next?: string): never;
+/** Fetch a node, mapping ONLY a 404 to `null` (the "not found" contract every
+ *  existence-check leaf wants) and surfacing every other failure as the clean
+ *  network-class CLI error via `rethrowAsCliError`. This replaces the old
+ *  `.catch(() => null)` idiom that, post-B-1 (`getNode` is now an HTTP round-trip),
+ *  masked a broken/slow/restarting daemon as a false "node not found". Same
+ *  404-only→null mapping as `ApiCanvasSource.orNull`, but returning the raw DTO
+ *  and rethrowing non-404s as CLI errors rather than swallowing them. */
+export declare function getNodeOrNull(nodeId: string): Promise<NodeDetailDTO | null>;
+export declare const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4096;
+/** Read a bounded tail of crtrd's event log to enrich a `daemon_unavailable`
+ *  cold-start timeout, so the actual startup failure is not discarded behind a
+ *  bare message. Bounds the I/O itself — opens the file and reads only the
+ *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
+ *  never `readFileSync`-ing the whole append-only log — then decodes/filters
+ *  that bounded slice. Best-effort and synchronous per the `coldStartDiagnostic`
+ *  contract — a missing/unreadable/empty log yields `undefined` so the base
+ *  message is used unchanged. */
+export declare function readColdStartDiagnostic(): string | undefined;
+/** Where a `crtr` process outside a node reaches the control plane instead of a local daemon: a machine cron's run token goes to
+ *  `CRTR_API_URL`; an imported Mac (`runtime/machine.json`) goes to its `apiUrl` with the signed-in person's bearer. Neither: undefined,
+ *  and the local socket is used. `CRTR_API_SOCKET` (inside a node) is checked by the caller first and is never remote. */
+export declare function remoteTarget(): {
+    client(timeoutMs?: number): CrtrClient;
+} | undefined;
+/** A move whose cloud run reached `done` but whose computer has not switched over: the account holds the records, the local daemon stays drained,
+ *  and no command may run against either side until `crtr sys signin` finishes it (design D14). The record is deleted only once the machine-role daemon
+ *  is up (`finishMove`, or that daemon's own start), so a `machine.json` written before a failed restart does not lift this. */
+export declare function moveUnfinished(): CrtrError | undefined;
+/** The local-socket `CrtrClient` every CLI verb uses. Autostart is on by
+ *  default: on a cold socket the injected `onColdSocket` hook fires
+ *  `ensureDaemon()` (spawns crtrd detached via the branded host), then the
+ *  client polls `/healthz` to a bounded deadline and retries once (the poll
+ *  lives inside `CrtrClient`, A-2). If crtrd never becomes reachable, the
+ *  client surfaces the final observed transport failure. This is the ONLY CLI
+ *  reference to `ensureDaemon`.
+ *
+ *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
+ *  returns immediately, so the client's OWN `/healthz` poll is the only
+ *  deadline the initiating CLI invocation actually waits on. It must never be
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows.
+ *  Both callers use the shared startup policy so a valid on-disk migration
+ *  cannot outlast the initiating CLI command. */
+export declare function cliClient(opts?: {
+    timeoutMs?: number;
+    local?: boolean;
+}): CrtrClient;
+export declare class ApiCanvasSource implements CanvasSource {
+    private readonly client;
+    private rosterCache;
+    private rosterInFlight;
+    constructor(client?: CrtrClient);
+    private roster;
+    /** Map a 404 from the API to the interface's `null` "not found" contract;
+     *  re-throw everything else. */
+    private orNull;
+    getNode(nodeId: string): Promise<NodeMeta | null>;
+    getRow(nodeId: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+        under?: string;
+    }): Promise<NodeRow[]>;
+    /** The browse screen uses one slim, compressed read for rows AND topology.
+     * The same roster index feeds subscriptionsOf/view until its normal TTL ends. */
+    browseSnapshot(): Promise<NodeRow[]>;
+    panelRoster(): Promise<RosterDTO>;
+    subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
+    subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
+    /** BFS over the active `subscribes_to` edges from `root` (its transitive view),
+     *  excluding `root` itself — the same traversal shape as
+     *  `RemoteCanvasSource.view`, expressed over the API's edge lists. */
+    view(root: string): Promise<string[]>;
+    /** Per-NODE open-ticket counts across `root`'s view. The renderer badges each
+     * node with the tickets it raised (the human bridge's parent), so this must
+     * be per-node. Request only this view's ids: using the
+     * enriched full-canvas snapshot for a five-second viewer poll blocked crtrd
+     * behind metadata and telemetry reads for every historical node. */
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
+    /** True when `nodeId` has at least one active (`active` edge flag, not just a
+     *  live subscriber) subscription to a node that is currently live
+     *  (`active`/`idle` status). `subscriptionsOf`'s roster-backed edges carry the
+     *  real per-edge `active` flag, so this filter is exact, not an over-report. */
+    newestReport(nodeId: string): Promise<ReportDTO | null>;
+    hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
+}
+/** The active read source for a CLI command. Mirrors `resolveCanvasSource`'s
+ *  selection WITHOUT importing `core/canvas/source.ts` (which pulls
+ *  `LocalCanvasSource` → `openDb`, failing the Stage-C import checker): an
+ *  explicit `--canvas <name>` wins, else the durable `crtr canvas use` selection
+ *  (`ScopeState.activeCanvas`), else the API-backed local source. The remote
+ *  branch reuses the verified-openDb-free `RemoteCanvasSource` (plan Q-3). */
+export declare function cliCanvasSource(opts?: {
+    canvasName?: string;
+    scope?: Scope;
+}, sandboxed?: boolean): CanvasSource;