@north-light/api 0.3.580 → 0.3.587

package/dist/commands/surface-node.js

@@ -0,0 +1,19 @@
+// `crtr surface node` — screen navigation for canvas-node viewers.
+import { defineBranch } from '../core/command.js';
+import { surfaceNodeFocusLeaf } from './surface/node/focus.js';
+import { surfaceNodeCycleLeaf } from './surface/node/cycle.js';
+import { surfaceNodeIdLeaf } from './surface/node/id.js';
+import { surfaceNodePinLeaf } from './surface/node/pin.js';
+export function registerSurfaceNode() {
+    return defineBranch({
+        name: 'node',
+        description: 'navigate and identify node viewer surfaces',
+        whenToUse: 'you need to bring a node viewer into focus, move through live node viewers, copy the node id shown in a pane, or pin that node in your canvas navigator',
+        help: {
+            name: 'surface node',
+            summary: 'navigate and identify node viewer surfaces',
+            model: 'Focus jumps to one named node, cycle walks the live viewer order, id copies the node shown in a pane, and pin stars that node in your navigator.',
+        },
+        children: [surfaceNodeFocusLeaf, surfaceNodeCycleLeaf, surfaceNodeIdLeaf, surfaceNodePinLeaf],
+    });
+}

package/dist/commands/surface-reload.d.ts

@@ -0,0 +1,7 @@
+import type { LeafDef } from '../core/command.js';
+/** The node a `crtr surface attach to <id>` command line targets. Panes opened
+ *  by a respawn path (the Markdown file-open bridge, the review companion) carry
+ *  a shell-quoted id, so the raw command line is not comparable to the canonical
+ *  one — the target node is. */
+export declare function attachTargetNode(command: string): string | undefined;
+export declare const surfaceReloadLeaf: LeafDef;

package/dist/commands/surface-reload.js

@@ -0,0 +1,129 @@
+// `crtr surface reload` — hot-reload a viewer pane in place.
+//
+// A viewer process loads its runtime generation at startup and never reloads
+// it, so after a runtime roll an already-open pane keeps running the old
+// generation against the new crtrd. Respawning the pane with the viewer's own
+// `crtr surface attach to <id>` command line means the fresh process picks up
+// the currently selected generation while the pane and broker are untouched.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { listProcessTable } from '../core/canvas/pid.js';
+import { displayMessage } from '../core/runtime/tmux-chrome.js';
+import { nodeInPane, paneCurrentPath, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, viewerSplitEnv, } from './surface/node/placement.js';
+/** True when `rootPid` (the pane's `#{pane_pid}`) or any descendant of it is a
+ *  live `crtr surface attach to <nodeId>` viewer process. This is how a
+ *  shell-hosted viewer is recognized: older panes were opened as a login shell
+ *  that then ran the viewer, so their `#{pane_start_command}` is `zsh -l` and
+ *  only the live process tree reveals the viewer. One process-table snapshot, walked
+ *  from the pane's root pid. */
+function paneTreeHasViewer(rootPid, nodeId) {
+    const table = listProcessTable();
+    if (table === null)
+        return false;
+    const childrenOf = new Map();
+    const commandOf = new Map();
+    for (const { pid, ppid, command } of table) {
+        commandOf.set(pid, command);
+        const siblings = childrenOf.get(ppid) ?? [];
+        siblings.push(pid);
+        childrenOf.set(ppid, siblings);
+    }
+    // Node ids are [a-z0-9-] so splicing one into a regex is safe. The viewer
+    // shows up as e.g. `node /opt/homebrew/bin/crtr surface attach to <id>`.
+    const viewer = new RegExp(`(?:^|\\s)surface attach to ${nodeId}(?:\\s|$)`);
+    const queue = [rootPid];
+    while (queue.length > 0) {
+        const pid = queue.pop();
+        const command = commandOf.get(pid);
+        if (command !== undefined && viewer.test(command))
+            return true;
+        const kids = childrenOf.get(pid);
+        if (kids !== undefined)
+            queue.push(...kids);
+    }
+    return false;
+}
+/** The node a `crtr surface attach to <id>` command line targets. Panes opened
+ *  by a respawn path (the Markdown file-open bridge, the review companion) carry
+ *  a shell-quoted id, so the raw command line is not comparable to the canonical
+ *  one — the target node is. */
+export function attachTargetNode(command) {
+    const match = /(?:^|\s)surface attach to\s+(?:'([^']*)'|"([^"]*)"|(\S+))/.exec(command);
+    return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+export const surfaceReloadLeaf = defineLeaf({
+    name: 'reload',
+    description: 'respawn a viewer pane in place onto the current runtime generation',
+    whenToUse: 'a viewer pane predates a runtime roll and should be refreshed onto the selected generation without losing the pane or the node it views',
+    help: {
+        name: 'surface reload',
+        summary: 'kill and re-run a viewer pane’s `crtr surface attach to <node>` command line in place, so the fresh viewer picks up the currently selected runtime generation',
+        params: [
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id hosting the viewer to reload. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
+        ],
+        output: [
+            { name: 'pane', type: 'string', required: true, constraint: 'The respawned tmux pane.' },
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose viewer was reloaded.' },
+        ],
+        outputKind: 'object',
+        effects: ['Kills the pane’s viewer process and re-runs the viewer command line in the same pane; the node’s broker engine keeps running untouched.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        if (pane === undefined || pane === '') {
+            throw new InputError({ error: 'not_in_tmux', message: 'viewer reload is tmux-only — no tmux pane to target', next: 'Run it inside tmux, or pass --pane <pane-id> of a tmux viewer pane.' });
+        }
+        // Only respawn a pane that actually hosts a viewer FOR THE TAGGED NODE. The
+        // node tag alone is not enough — workspace shell panes carry `@crtr_node`
+        // too, and respawning one would kill a live shell the user is working in.
+        // Two shapes qualify:
+        //   1. The pane's start command IS the viewer (tmux launched `crtr surface
+        //      attach to <id>` as the pane command) → a bare `respawn-pane -k`
+        //      replays that exact line.
+        //   2. The pane was started as a shell (`zsh -l`) that is now RUNNING the
+        //      viewer as a live child process → respawn with an explicit
+        //      `crtr surface attach to <node>` command, because replaying the
+        //      shell line would leave a bare shell instead of a viewer.
+        // A tagged pane sitting at a shell prompt with no live viewer matches
+        // neither and is refused — killing it would lose the user's shell.
+        const nodeId = nodeInPane(pane);
+        if (nodeId === undefined) {
+            displayMessage('crtr: no viewer in pane', pane);
+            throw new InputError({ error: 'no_viewer', message: 'this pane does not host an attach viewer', next: 'Pass --pane <pane-id> for a pane running `crtr surface attach to <node>`.' });
+        }
+        const viewerCommand = `crtr surface attach to ${nodeId}`;
+        // tmux wraps #{pane_start_command} in literal double quotes.
+        const startCommand = paneStartCommand(pane)?.replace(/^"|"$/g, '');
+        if (startCommand !== undefined && startCommand.startsWith('crtr surface attach ')) {
+            // The start command must target the TAGGED node — a mismatch means the
+            // tag is stale or the viewer belongs to another node; don't touch it.
+            if (attachTargetNode(startCommand) !== nodeId) {
+                displayMessage('crtr: viewer/node mismatch in pane', pane);
+                throw new InputError({ error: 'no_viewer', message: `this pane's viewer command (${startCommand}) does not match its node tag (${nodeId})`, next: 'Pass --pane <pane-id> for a pane running `crtr surface attach to <node>`.' });
+            }
+            if (!respawnPaneInPlace(pane)) {
+                displayMessage('crtr: viewer reload failed', pane);
+                throw new InputError({ error: 'respawn_failed', message: `tmux could not respawn pane ${pane}`, next: 'Check the tmux server is reachable, then retry.' });
+            }
+            displayMessage('crtr: viewer reloaded', pane);
+            return { pane, node_id: nodeId };
+        }
+        const rootPid = panePid(pane);
+        if (rootPid === undefined || !paneTreeHasViewer(rootPid, nodeId)) {
+            displayMessage('crtr: no viewer in pane', pane);
+            throw new InputError({ error: 'no_viewer', message: 'this pane does not host an attach viewer', next: 'Pass --pane <pane-id> for a pane running `crtr surface attach to <node>`.' });
+        }
+        // Shell-hosted viewer: respawn onto the viewer command directly. The pane
+        // deliberately converges on the viewer-as-pane-command shape every other
+        // crtr surface uses today, so its start command becomes truthful and the
+        // next reload takes the replay path.
+        const cwd = paneCurrentPath(pane) ?? process.cwd();
+        if (!respawnPaneSync({ pane, cwd, env: viewerSplitEnv(), command: viewerCommand })) {
+            displayMessage('crtr: viewer reload failed', pane);
+            throw new InputError({ error: 'respawn_failed', message: `tmux could not respawn pane ${pane}`, next: 'Check the tmux server is reachable, then retry.' });
+        }
+        displayMessage('crtr: viewer reloaded', pane);
+        return { pane, node_id: nodeId };
+    },
+    render: (r) => `Reloaded viewer for ${r['node_id']} in pane ${r['pane']}.`,
+});

package/dist/commands/surface-tmux-spread.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const tmuxSpreadLeaf: LeafDef;

package/dist/commands/surface-tmux-spread.js

@@ -0,0 +1,214 @@
+// `crtr surface tmux-spread <node>` — explode the local subtree into a tiled grid.
+//
+// A genuine viewer-placement decision (tile every live viewer in a subtree into
+// one window), so it lives under `surface` alongside the other viewer-placement commands.
+// The command expands the graph being watched: the caller's
+// own viewer pane is broken out into a BRAND-NEW window, then a surface-attach
+// viewer pane is tiled beside it for every broker-alive node in the local
+// subtree (ancestry root → self → descendants), so the user lands on a single
+// window showing the whole live subtree at once.
+//
+// SCOPE — the LOCAL SUBTREE: climbRoot(self) → the ancestry root, then every
+// node under it (subtreeIds). TARGET — "broker-alive" nodes: status in
+// (active, idle) AND isPidAlive(pi_pid); self included. CAP — 8 panes total,
+// most-recently-active first (pi session-file mtime, descending). Self's pane is
+// always shown (it is the anchor being broken out); up to 7 others fill the rest,
+// and any beyond that are an `overflow` count.
+//
+// crtr is tmux-only and this is pure viewer chrome: it opens/moves viewer panes
+// through the pure placement-tmux seam (openViewerPane + breakPane/selectLayout,
+// never importing tmux.ts directly) and registers the resulting focus rows via
+// the daemon API (cliClient.registerFocus), so it never touches canvas.db.
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliCanvasSource, cliClient } from './api-client.js';
+import { jobDir } from '../core/canvas/paths.js';
+import { isPidAlive } from '../core/canvas/pid.js';
+// The tmux verbs (break/split/layout/navigate + the broker-socket wait) run
+// LOCALLY here via the pure placement-tmux seam; the viewer-registry rows
+// (focusOf/focusByPane/register/set-pane/close) route through the daemon API
+// (cliClient), and the subtree/root graph walk reads via cliCanvasSource. This
+// leaf reaches ZERO canvas.db/canvas.js code.
+import { inTmux, currentTmux, breakPane, selectLayout, openViewerPane, paneLocation, paneExists, closePane, getPaneOption, switchClient, selectWindow, waitForBrokerViewSocket, } from '../core/runtime/placement-tmux.js';
+/** Climb to the ancestry root via the daemon-API graph (managers = subscribers):
+ *  mirror the attach viewer's `climbRootFromSource` — walk up the first subscriber (the manager)
+ *  until there is none, cycle-guarded. */
+async function climbRootViaSource(source, self) {
+    let cur = self;
+    const seen = new Set([cur]);
+    for (;;) {
+        const mgr = (await source.subscribersOf(cur))[0]?.node_id;
+        if (mgr === undefined || seen.has(mgr))
+            break;
+        seen.add(mgr);
+        cur = mgr;
+    }
+    return cur;
+}
+/** Hard ceiling on panes in the spread window (self + up to 7 siblings). */
+const PANE_CAP = 8;
+/** Telemetry mtime approximates last activity; nodes without telemetry sort last. */
+function sessionMtime(nodeId) {
+    try {
+        const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+        return st?.mtimeMs ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** A node whose broker engine is currently live and attachable. */
+function brokerAlive(meta) {
+    return (meta.status === 'active' || meta.status === 'idle') && isPidAlive(meta.pi_pid ?? null);
+}
+export const tmuxSpreadLeaf = defineLeaf({
+    name: 'tmux-spread',
+    description: 'break the caller\'s pane into a new window and tile a viewer for every broker-alive node in the local subtree',
+    whenToUse: 'you want the whole live subtree you are watching on one tiled tmux window at once, instead of hunting down each node\'s viewer by hand — also bound to the `/graph` view\'s `e` key',
+    help: {
+        name: 'surface tmux-spread',
+        summary: 'Explode the local subtree into a tiled grid: break the caller\'s viewer pane into a brand-new window, then tile a surface-attach viewer pane beside it for every broker-alive node (status active/idle + live pi_pid) in the ancestry-root subtree, most-recently-active first, capped at 8 panes',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: true,
+                constraint: 'The spread anchor (self) — its ancestry root + descendants define the subtree to tile. Passed as {self} by the `/graph` view\'s `e` key.',
+            },
+            {
+                kind: 'flag',
+                name: 'pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id of the caller\'s viewer (the pane broken into the new window). Defaults to $TMUX_PANE.',
+            },
+        ],
+        output: [
+            { name: 'window', type: 'string', required: false, constraint: 'The new window id holding the tiled spread.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The session the spread window lives in (the caller\'s session — break-pane keeps it).' },
+            { name: 'nodes', type: 'string', required: true, constraint: 'Space-joined ids tiled into the window (self first).' },
+            { name: 'overflow', type: 'number', required: true, constraint: 'Broker-alive siblings beyond the cap that were NOT shown.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Breaks the caller\'s viewer pane into a brand-new tmux window (tmux break-pane).',
+            'Opens a surface-attach viewer pane (and a focuses row) for each shown sibling, moving any that had a viewer elsewhere into the spread.',
+            'Tiles the window and switches the client onto it.',
+        ],
+    },
+    run: async (input) => {
+        if (!inTmux()) {
+            throw new InputError({
+                error: 'no_tmux',
+                message: 'tmux-spread needs a tmux server — crtr placement is tmux-only.',
+                next: 'Run from inside a tmux session (an agent viewer pane).',
+            });
+        }
+        const anchorId = input['node'];
+        // Resolve the caller's viewer pane like placement.focus() does: an explicit
+        // --pane, else $TMUX_PANE (set when run via tmux run-shell / the alt+c
+        // chord), else the attached client's active pane (the graph-modal `e` path
+        // shells from the headless broker, which carries no $TMUX_PANE).
+        const callerPane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+        if (callerPane === undefined || callerPane === '') {
+            throw new InputError({
+                error: 'no_pane',
+                message: 'no caller pane to break out',
+                next: 'Run from inside an agent\'s pane, or pass --pane <pane-id>.',
+            });
+        }
+        const source = cliCanvasSource();
+        const client = cliClient();
+        const anchor = await source.getNode(anchorId);
+        if (anchor === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no node: ${anchorId}`,
+                next: 'List nodes with `crtr node inspect list`.',
+            });
+        }
+        // Local subtree: ancestry root → every descendant (root itself is excluded by
+        // the view walk, so prepend it). Then keep only broker-alive nodes.
+        const root = await climbRootViaSource(source, anchorId);
+        const subtree = await source.view(root);
+        const metas = await Promise.all([root, ...subtree].map((id) => source.getNode(id)));
+        const candidates = metas.filter((m) => m !== null && brokerAlive(m));
+        // Rank the OTHER nodes most-recently-active first; self is always the anchor,
+        // so it claims one pane and up to PANE_CAP-1 siblings fill the rest.
+        const others = candidates
+            .filter((m) => m.node_id !== anchorId)
+            .sort((a, b) => sessionMtime(b.node_id) - sessionMtime(a.node_id));
+        const shown = others.slice(0, PANE_CAP - 1);
+        const overflow = others.length - shown.length;
+        // Break the caller's pane into a fresh window — the spread anchor. The pane
+        // keeps its %id, only its window changes; break-pane keeps it in the caller's
+        // session. A failure here is a real error (no half-spread fallback).
+        const broken = breakPane(callerPane);
+        if (broken === null) {
+            throw new InputError({
+                error: 'break_failed',
+                message: `tmux break-pane failed for ${callerPane}`,
+                next: 'Ensure the pane exists and tmux is healthy.',
+            });
+        }
+        const anchorPane = broken.pane;
+        const window = broken.window;
+        const session = paneLocation(anchorPane)?.session ?? null;
+        // Keep the viewer registry correct: re-point self's focus row at the moved
+        // pane's (possibly new) session cache.
+        const selfFocus = await client.focusByPane(callerPane);
+        if (selfFocus !== null)
+            await client.setFocusPane(selfFocus.focus_id, { pane: anchorPane, session });
+        const spreadIds = [anchorId];
+        for (const m of shown) {
+            const id = m.node_id;
+            // UNIQUE(node_id): a sibling that already has a viewer ELSEWHERE must be
+            // MOVED into the spread — vacate its old pane + row first (mirror focus()
+            // case (c)): only kill the pane if it still carries THIS node's @crtr_node
+            // tag (else it is the user's shell / another node's viewer — drop the stale
+            // row only).
+            const prior = await client.focusOf(id);
+            if (prior !== null && prior.pane !== null) {
+                if (paneExists(prior.pane) && getPaneOption(prior.pane, '@crtr_node') === id) {
+                    closePane(prior.pane);
+                }
+                await client.closeFocus(prior.focus_id);
+            }
+            // Broker is already alive, but close the cold-start race before attach.
+            await waitForBrokerViewSocket(id);
+            const opened = openViewerPane(id, session ?? '', { cwd: m.cwd, besidePane: anchorPane });
+            if (opened === null)
+                continue; // tmux refused this split (e.g. no space) — best-effort skip
+            const row = await client.registerFocus({
+                node_id: id,
+                pane: opened.pane,
+                session: opened.session,
+                window: opened.window,
+            });
+            if (row === null)
+                continue;
+            spreadIds.push(id);
+            // Re-tile after each split so the next split has room (a fixed anchor pane
+            // would otherwise halve until tmux runs out of space).
+            selectLayout(window, 'tiled');
+        }
+        selectLayout(window, 'tiled');
+        if (session !== null) {
+            switchClient(session);
+            selectWindow(session, window);
+        }
+        return {
+            window,
+            session: session ?? undefined,
+            nodes: spreadIds.join(' '),
+            overflow,
+        };
+    },
+    render: (out) => {
+        const o = out;
+        const tail = o.overflow > 0 ? ` (+${o.overflow} more not shown)` : '';
+        return `spread viewers into window ${o.window ?? '?'}${tail}`;
+    },
+});

package/dist/commands/surface.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerSurface(): BranchDef;

package/dist/commands/surface.js

@@ -0,0 +1,29 @@
+// `crtr surface` — the screen-facing entrypoints.
+//
+// Groups the screen-facing surface families under one canonical noun.
+import { defineBranch } from '../core/command.js';
+import { registerAttach } from '../clients/attach/command.js';
+import { tmuxSpreadLeaf } from './surface-tmux-spread.js';
+import { surfaceEditLeaf } from './surface-edit.js';
+import { registerSurfaceNode } from './surface-node.js';
+import { surfaceInspectLeaf } from './surface-inspect.js';
+import { surfaceReloadLeaf } from './surface-reload.js';
+import { surfaceInboxLeaf } from './surface-inbox.js';
+import { surfaceDashboardLeaf } from './surface-dashboard.js';
+export function registerSurface() {
+    const attach = registerAttach('surface', 'important');
+    return defineBranch({
+        name: 'surface',
+        rootEntry: {
+            concept: 'screen-facing surfaces — node viewers, live broker attachment, and the Inspector',
+            desc: 'open and manage screen-facing surfaces',
+            useWhen: 'you need a UI or presentation surface rather than a node, document, or graph operation — node-viewer navigation, live broker attachment, node inspection, tmux placement, or an editor pane',
+        },
+        help: {
+            name: 'surface',
+            summary: 'open and manage screen-facing surfaces',
+            model: 'Choose `node` for navigation among node viewers. The other commands open a broker attachment, node Inspector, subtree spread, reload, or adjacent editor pane.',
+        },
+        children: [registerSurfaceNode(), attach, surfaceInspectLeaf, surfaceReloadLeaf, tmuxSpreadLeaf, surfaceEditLeaf, surfaceInboxLeaf, surfaceDashboardLeaf],
+    });
+}

package/dist/commands/sys/branch.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef, LeafDef } from '../../core/command.js';
+export declare function defineSysBranch(children: (LeafDef | BranchDef)[]): BranchDef;

package/dist/commands/sys/branch.js

@@ -0,0 +1,19 @@
+import { defineBranch } from '../../core/command.js';
+const SYS_ROOT_ENTRY = {
+    concept: 'crtr configuration, diagnostics, and self-management',
+    desc: 'settings, config, connect, setup, tutorial, doctor, context, sync, migrate, join, update, version, feedback, logs, retry-delivery, support, limits, daemon',
+    useWhen: 'managing the crtr installation, inspecting diagnostics, operating the crtrd supervisor process, or registering a hosted runtime with its directory before first boot',
+};
+const SYS_HELP = {
+    name: 'sys',
+    summary: 'crtr system configuration, settings, diagnostics, and self-management',
+    model: 'Configuration and settings own durable behavior; diagnostics and support observe it. Setup, migration, sync, and update change installed or generated state, and join registers a stopped runtime with its directory from an enrollment token, while daemon control owns the supervisor lifecycle.',
+};
+export function defineSysBranch(children) {
+    return defineBranch({
+        name: 'sys',
+        rootEntry: SYS_ROOT_ENTRY,
+        help: { ...SYS_HELP },
+        children,
+    });
+}

package/dist/commands/sys/config.d.ts

@@ -0,0 +1 @@
+export declare const configBranch: import("../../core/command.js").BranchDef;