@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/node-context.js

@@ -0,0 +1,172 @@
+// `crtr node inspect context` — browse this node's context and reports dirs and those of
+// every node it subscribes to, in one read-only nvim file explorer.
+//
+// crtr makes a STRONG CLAIM that nvim is installed (see crouter/CLAUDE.md): the
+// file explorer + file viewer are nvim, not a hand-rolled view-contract surface.
+// We synthesize a temp dir of LABELLED NODE DIRS — `self` first, then one per
+// subscription — and place `context` / `reports` symlinks inside each label dir
+// for the node's existing on-disk dirs. We then open `nvim -R` on the temp tree
+// (read-only: this is a viewer into siblings' state, edits never write back).
+// The symlinks are torn down when nvim exits; the real node dirs are untouched.
+//
+// The /context popup (src/pi-extensions/canvas-context.ts) shells this leaf inside
+// a tmux display-popup, exactly as /view shells the surface-view picker. Piped / non-TTY
+// it prints the resolved roster (node · path · file count) and exits 0.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode, subscriptionsOf } from '../core/canvas/index.js';
+import { contextDir, nodeDir, reportsDir } from '../core/canvas/paths.js';
+/** Make a node label safe as a directory name (netrw shows it verbatim). */
+function sanitize(s) {
+    return s.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'node';
+}
+/** Shallow file count for the roster (cheap; 0 when the dir is empty/absent). */
+function countFiles(dir) {
+    try {
+        return readdirSync(dir).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function nodeFiles(nodeId) {
+    return countFiles(contextDir(nodeId)) + countFiles(reportsDir(nodeId));
+}
+/** Resolve the current node + every node it subscribes to into browse roots,
+ *  keeping any node whose `context/` or `reports/` dir exists on disk. `self`
+ *  is always first and labelled `self`. */
+function resolveRoots(selfId) {
+    const roots = [];
+    const selfMeta = getNode(selfId);
+    const selfContext = contextDir(selfId);
+    const selfReports = reportsDir(selfId);
+    if (existsSync(selfContext) || existsSync(selfReports)) {
+        roots.push({
+            nodeId: selfId,
+            label: `self-${sanitize(selfMeta?.name ?? selfId.slice(0, 8))}`,
+            dir: nodeDir(selfId),
+            self: true,
+            fileCount: nodeFiles(selfId),
+            contextDir: selfContext,
+            reportsDir: selfReports,
+        });
+    }
+    for (const sub of subscriptionsOf(selfId)) {
+        const context = contextDir(sub.node_id);
+        const reports = reportsDir(sub.node_id);
+        if (!existsSync(context) && !existsSync(reports))
+            continue;
+        const meta = getNode(sub.node_id);
+        const short = sub.node_id.slice(0, 8);
+        roots.push({
+            nodeId: sub.node_id,
+            label: `${sanitize(meta?.name ?? sub.node_id)}-${short}`,
+            dir: nodeDir(sub.node_id),
+            self: false,
+            fileCount: nodeFiles(sub.node_id),
+            contextDir: context,
+            reportsDir: reports,
+        });
+    }
+    return roots;
+}
+/** Is `nvim` on PATH and runnable? */
+function nvimAvailable() {
+    const r = spawnSync('nvim', ['--version'], { stdio: 'ignore' });
+    return r.error === undefined && (r.status === 0 || r.status === null);
+}
+/** Build a temp dir of labelled node dirs. Self's label is prefixed `0-` so it
+ *  sorts first in netrw; each label dir contains `context` and `reports` symlinks
+ *  for whichever of those dirs exist on disk. */
+function buildSymlinkTree(roots) {
+    const tree = mkdtempSync(join(tmpdir(), 'crtr-context-'));
+    for (const r of roots) {
+        const name = r.self ? `0-${r.label}` : r.label;
+        const nodeRoot = join(tree, name);
+        mkdirSync(nodeRoot, { recursive: true });
+        try {
+            if (r.contextDir !== undefined && existsSync(r.contextDir)) {
+                symlinkSync(r.contextDir, join(nodeRoot, 'context'), 'dir');
+            }
+            if (r.reportsDir !== undefined && existsSync(r.reportsDir)) {
+                symlinkSync(r.reportsDir, join(nodeRoot, 'reports'), 'dir');
+            }
+        }
+        catch {
+            /* best-effort: a label collision or symlink failure just drops that node */
+        }
+    }
+    return tree;
+}
+export const nodeContextLeaf = defineLeaf({
+    name: 'context',
+    description: 'browse this node + its subscriptions’ context and reports dirs in an nvim popup',
+    whenToUse: 'you want to SEE what the nodes you subscribe to have written — open a read-only nvim file explorer over this node’s context and reports dirs and every subscribed node’s context and reports dirs at once. The /context popup shells this. Piped it prints the roster instead',
+    help: {
+        name: 'node inspect context',
+        summary: 'open a read-only nvim file explorer over this node’s context and reports dirs and those of every node it subscribes to',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node id to root on. Defaults to $CRTR_NODE_ID (the calling node).' },
+        ],
+        output: [
+            { name: 'roots', type: 'object[]', required: true, constraint: 'Resolved browse roots: {node_id, label, dir, self, files}. Returned on the piped/non-TTY path.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'TTY: builds a temp dir of labelled node dirs, symlinking each available `context`/`reports` dir inside it, then execs `nvim -R` on the tree; the temp links are removed on exit (real dirs untouched).',
+            'Requires nvim on PATH (a crtr strong dependency). Missing nvim -> error with an install hint.',
+            'Non-TTY / piped: prints the resolved roster and exits 0; opens nothing.',
+        ],
+    },
+    run: async (input) => {
+        const selfId = input['node']?.trim() || process.env['CRTR_NODE_ID'];
+        if (selfId === undefined || selfId === '') {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no current node: $CRTR_NODE_ID is unset and --node was not given',
+                field: 'node',
+                next: 'Run this from inside a canvas node (the /context popup does), or pass --node <id>.',
+            });
+        }
+        if (getNode(selfId) === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${selfId}`, field: 'node', next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const roots = resolveRoots(selfId);
+        const rosterOut = roots.map((r) => ({ node_id: r.nodeId, label: r.label, dir: r.dir, self: r.self, files: r.fileCount }));
+        // Non-TTY: print the roster and exit. Opens nothing.
+        if (!process.stdout.isTTY) {
+            return { roots: rosterOut };
+        }
+        if (!nvimAvailable()) {
+            throw new InputError({
+                error: 'nvim_missing',
+                message: 'nvim is not on PATH — `crtr node inspect context` opens the context explorer in nvim',
+                next: 'Install Neovim (macOS: `brew install neovim`; Debian/Ubuntu: `apt install neovim`), then retry.',
+            });
+        }
+        const tree = buildSymlinkTree(roots);
+        try {
+            // `nvim -R .` opens netrw (or the user's dir handler) read-only, cwd = the
+            // symlink tree, so the explorer roots on `self` + each subscription.
+            spawnSync('nvim', ['-R', '.'], { cwd: tree, stdio: 'inherit' });
+        }
+        finally {
+            rmSync(tree, { recursive: true, force: true }); // removes symlinks only; targets untouched
+        }
+        return { roots: rosterOut };
+    },
+    render: (result) => {
+        const roots = result['roots'] ?? [];
+        if (roots.length === 0)
+            return 'No node dirs to show (no subscriptions with written context or reports, and this node’s own context/reports dirs are empty/absent).';
+        const lines = roots.map((r) => {
+            const tag = r['self'] === true ? ' (self)' : '';
+            return `  ${String(r['label'])}${tag}\t${String(r['files'])} files\t${String(r['dir'])}`;
+        });
+        return [`Context roots (${roots.length}):`, ...lines].join('\n');
+    },
+});

package/dist/commands/node-snapshot.d.ts

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

package/dist/commands/node-snapshot.js

@@ -0,0 +1,126 @@
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode } from '../core/canvas/index.js';
+import { sessionPtrPath } from '../core/canvas/paths.js';
+import { SessionManager } from '../core/runtime/broker-sdk.js';
+import { BUILTIN_SLASH_COMMANDS } from '../core/runtime/pi-vendored.js';
+function resolveSessionFile(nodeId, metaFile) {
+    if (typeof metaFile === 'string' && metaFile !== '' && existsSync(metaFile))
+        return metaFile;
+    const ptr = sessionPtrPath(nodeId);
+    if (!existsSync(ptr))
+        return null;
+    const raw = readFileSync(ptr, 'utf8').trim();
+    if (raw === '')
+        return null;
+    if (existsSync(raw))
+        return raw;
+    return null;
+}
+function emptyStats(sessionId, sessionFile) {
+    return {
+        sessionFile,
+        sessionId,
+        userMessages: 0,
+        assistantMessages: 0,
+        toolCalls: 0,
+        toolResults: 0,
+        totalMessages: 0,
+        tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        cost: 0,
+    };
+}
+function statsFromMessages(messages, sessionId, sessionFile) {
+    const stats = emptyStats(sessionId, sessionFile);
+    stats.totalMessages = messages.length;
+    for (const message of messages) {
+        if (message.role === 'user')
+            stats.userMessages++;
+        else if (message.role === 'assistant') {
+            stats.assistantMessages++;
+            const content = Array.isArray(message.content) ? message.content : [];
+            stats.toolCalls += content.filter((c) => c !== null && typeof c === 'object' && c.type === 'toolCall').length;
+            const usage = message.usage;
+            if (usage !== undefined) {
+                stats.tokens.input += usage.input ?? 0;
+                stats.tokens.output += usage.output ?? 0;
+                stats.tokens.cacheRead += usage.cacheRead ?? 0;
+                stats.tokens.cacheWrite += usage.cacheWrite ?? 0;
+                stats.cost += usage.cost?.total ?? 0;
+            }
+        }
+        else if (message.role === 'toolResult') {
+            stats.toolResults++;
+        }
+    }
+    stats.tokens.total = stats.tokens.input + stats.tokens.output + stats.tokens.cacheRead + stats.tokens.cacheWrite;
+    return stats;
+}
+export const nodeSnapshotLeaf = defineLeaf({
+    name: 'snapshot',
+    description: 'read a dormant node session snapshot without launching its broker',
+    whenToUse: 'you need a read-only broker-compatible snapshot of a dormant node; it copies the session JSONL before parsing and never revives the node',
+    help: {
+        name: 'node inspect snapshot',
+        summary: 'read-only dormant node snapshot in the broker welcome shape',
+        params: [{ kind: 'positional', name: 'id', type: 'string', required: true, constraint: 'Canvas node id.' }],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node id.' },
+            { name: 'snapshot', type: 'object', required: true, constraint: 'BrokerSnapshot-compatible {messages, stats, state}.' },
+            { name: 'commands', type: 'object[]', required: true, constraint: "Builtin slash commands only: {name,description,source:'builtin'}." },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: copies the session JSONL to a temp dir, parses the copy, then deletes the temp dir. Does not launch or revive brokers.'],
+        // Full session reconstruction (every message) for tooling, not a
+        // human/agent glance — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async (input) => {
+        const nodeId = input['id'];
+        const node = getNode(nodeId);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'id', next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const sessionFile = resolveSessionFile(nodeId, node.pi_session_file);
+        if (sessionFile === null) {
+            throw new InputError({ error: 'no_session', message: `node has no readable session file: ${nodeId}`, field: 'id', next: 'Revive the node first, or choose a node that has captured pi_session_file.' });
+        }
+        const tempDir = mkdtempSync(join(tmpdir(), 'crtr-node-snapshot-'));
+        try {
+            const copy = join(tempDir, basename(sessionFile));
+            copyFileSync(sessionFile, copy);
+            const manager = SessionManager.open(copy);
+            const context = manager.buildSessionContext();
+            const messages = context.messages;
+            const sessionId = manager.getSessionId();
+            const sessionName = manager.getSessionName();
+            const snapshot = {
+                messages,
+                stats: statsFromMessages(messages, sessionId, sessionFile),
+                state: {
+                    sessionId,
+                    sessionFile,
+                    model: context.model?.modelId,
+                    isStreaming: false,
+                    thinkingLevel: context.thinkingLevel,
+                    steeringMode: 'one-at-a-time',
+                    followUpMode: 'one-at-a-time',
+                    sessionName,
+                    autoCompactionEnabled: true,
+                    pendingMessageCount: 0,
+                },
+            };
+            return {
+                node_id: nodeId,
+                snapshot,
+                commands: BUILTIN_SLASH_COMMANDS.map((c) => ({ ...c, source: 'builtin' })),
+            };
+        }
+        finally {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    },
+});

package/dist/commands/node.d.ts

@@ -6,11 +6,11 @@ import { type BranchDef } from '../core/command.js';
 export declare function childFollowUp(spawnerId: string | undefined): string;
 /** The live node "in front of you" in a tmux pane, HOST-AGNOSTIC. Defaults to
  *  $TMUX_PANE / the caller's current pane when `pane` is omitted — shared by
- *  `node recycle` / `node demote` / `node lifecycle` / `node close` / `node
+ *  `node lifecycle recycle` / `node lifecycle demote` / `node config --lifecycle` / `node lifecycle close` / `node
  *  cycle`, and the `canvas chord` leaf.
  *
  *  Two resolutions, tried in order:
- *    1. VIEWER pane (broker host): a `crtr attach` viewer self-tags its pane with
+ *    1. VIEWER pane (broker host): a `crtr surface attach` viewer self-tags its pane with
  *       the node it views (`@crtr_node`). A broker engine runs DETACHED with
  *       window=null, so the window→node lookup never finds it — the pane tag is
  *       the only handle. Checked FIRST because the tag is pane-precise, whereas a