@north-light/crouter 0.3.154

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

@@ -0,0 +1,6 @@
+import type { LeafDef } from '../../core/command.js';
+/** Shared with the wizard's own limits tab, which imports it back from here —
+ *  keeping it in this cheap module is what lets the leaf's help text state the
+ *  precedence rule without loading the wizard. */
+export declare const BROKER_LIMIT_OVERRIDE_PRECEDENCE = "Valid CRTR_WARN_LIVE_BROKERS and CRTR_MAX_LIVE_BROKERS environment overrides take precedence over their corresponding configured limits.";
+export declare const sysSetupLeaf: LeafDef;

package/dist/commands/sys/setup.js

@@ -0,0 +1,36 @@
+// The `crtr sys setup` leaf DEFINITION only. The wizard itself lives in
+// setup-wizard.ts and is loaded on demand, because it pulls pi's model
+// runtime, login dialog and TUI components — a ~270ms module graph. Registering
+// the `sys` subtree (every `crtr sys …` invocation, and root `-h`, which builds
+// the full tree) needs the help metadata below and nothing else, so the wizard
+// must NOT be reachable by a static import from here.
+import { defineLeaf } from '../../core/command.js';
+/** Shared with the wizard's own limits tab, which imports it back from here —
+ *  keeping it in this cheap module is what lets the leaf's help text state the
+ *  precedence rule without loading the wizard. */
+export const BROKER_LIMIT_OVERRIDE_PRECEDENCE = 'Valid CRTR_WARN_LIVE_BROKERS and CRTR_MAX_LIVE_BROKERS environment overrides take precedence over their corresponding configured limits.';
+export const sysSetupLeaf = defineLeaf({
+    name: 'setup',
+    description: 'manage providers, setup dependencies and keys, crouter keybindings, and broker limits',
+    whenToUse: 'you want to bootstrap this machine or change setup-owned settings: manage configured model providers, install vendored pi plugins or system dependencies, save an Exa API key, edit crouter-owned keybindings, or set broker warning and automatic-revive limits.',
+    help: {
+        name: 'sys setup',
+        summary: 'open the multi-tab setup wizard for providers, dependencies, keys, keybindings, and broker limits',
+        inputNote: 'No input parameters.',
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Opens a pi-tui wizard whose first tab logs in to a model provider (pi\'s real OAuth/API-key flow, same as in-app /login) so a fresh install has credentials before running any node.',
+            'Collects companion package installs, system dependency installs, API keys, sparse user overrides for crouter-owned keybindings, and user-scope broker limits across the remaining tabs.',
+            'Saves validated keybinding changes atomically in the user config and refreshes crouter-owned tmux bindings without overwriting occupied user keys.',
+            `Saves positive-integer broker warning and automatic-revive hard-cap values under user config brokerThresholds; crtrd reads them on its next supervision tick. ${BROKER_LIMIT_OVERRIDE_PRECEDENCE}`,
+            'Runs the bundled pi CLI to install the selected companion packages, writes EXA_API_KEY to ~/.crouter/exa.key when provided, and prints a summary.',
+            'The companion-package list includes crtr marketplace plugins (currently `capture`), checked by default and installed into the user scope when left checked. An unreachable marketplace is reported as skipped rather than failing setup.',
+            'On every invocation (best-effort, idempotent), refreshes crouter-owned tmux bindings and registers known nodes\' interaction roots so resolved tickets can call back into the asking node. The inbox popup toggle is a crouter-owned keybinding, editable on the keybindings tab.',
+        ],
+    },
+    run: async () => {
+        await (await import('./setup-wizard.js')).runSetup();
+    },
+    render: () => '',
+});

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

@@ -0,0 +1,51 @@
+import type { Scope } from '../../types.js';
+export declare const PKG_ROOT: string;
+interface ManifestFile {
+    path: string;
+    size: number;
+    sha256: string;
+    symlink?: boolean;
+}
+export interface RuntimeManifest {
+    id: string;
+    packageVersion: string;
+    files: ManifestFile[];
+    entries: Record<string, string>;
+}
+interface RuntimeManifestModule {
+    GENERATION_ID: RegExp;
+    runtimeHome(): string;
+    contained(root: string, candidate: string): boolean;
+    parseSelectionTarget(target: string): string | null;
+    sortInventory(files: ManifestFile[]): ManifestFile[];
+    validateManifestShape(manifest: unknown, context: {
+        id: string;
+        entryName: string;
+    }): {
+        ok: true;
+        entry: string;
+    } | {
+        ok: false;
+        error: string;
+    };
+}
+export declare const runtimeManifest: RuntimeManifestModule;
+export interface GenerationLocation {
+    id: string;
+    root: string;
+}
+export interface LocatedGeneration extends GenerationLocation {
+    manifest: RuntimeManifest;
+}
+export interface GenerationLookup {
+    generation: LocatedGeneration | null;
+    error: string | null;
+}
+/** Find the immutable generation containing this loaded module, if any. */
+export declare function processGeneration(): GenerationLocation | null;
+/** Read the selected symlink without treating an absent runtime as an exception in a source checkout. */
+export declare function selectedGeneration(): GenerationLookup;
+export declare function processLocatedGeneration(): GenerationLookup;
+export declare function readPackageVersion(): string;
+export declare function resolveScope(raw: string | undefined): Scope;
+export {};

package/dist/commands/sys/shared.js

@@ -0,0 +1,81 @@
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { usage } from '../../core/errors.js';
+const modulePath = fileURLToPath(import.meta.url);
+function packageRoot() {
+    for (let current = dirname(modulePath);; current = dirname(current)) {
+        if (existsSync(join(current, 'bin', 'runtime-generation-manifest.mjs')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error('cannot locate crouter package root');
+    }
+}
+export const PKG_ROOT = packageRoot();
+// dist is deliberately not a second implementation of the runtime manifest
+// contract. The package root is discovered from this module's own URL so both a
+// sealed generation and a source checkout load the same dependency-free bin module.
+export const runtimeManifest = (await import(pathToFileURL(join(PKG_ROOT, 'bin', 'runtime-generation-manifest.mjs')).href));
+/** Find the immutable generation containing this loaded module, if any. */
+export function processGeneration() {
+    for (let current = dirname(modulePath);; current = dirname(current)) {
+        const parent = dirname(current);
+        const id = basename(current);
+        if (basename(parent) === 'generations' && runtimeManifest.GENERATION_ID.test(id)) {
+            return { id, root: current };
+        }
+        if (parent === current)
+            return null;
+    }
+}
+function locateGeneration(root, id) {
+    try {
+        const physical = realpathSync(root);
+        if (!lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink())
+            return { generation: null, error: `${root} is not a generation directory` };
+        const manifest = JSON.parse(readFileSync(join(physical, 'generation.json'), 'utf8'));
+        return { generation: { id, root: physical, manifest }, error: null };
+    }
+    catch (error) {
+        return { generation: null, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Read the selected symlink without treating an absent runtime as an exception in a source checkout. */
+export function selectedGeneration() {
+    const root = runtimeManifest.runtimeHome();
+    const selected = join(root, 'selected');
+    let target;
+    try {
+        target = readlinkSync(selected);
+    }
+    catch {
+        return { generation: null, error: `no selected runtime generation (${selected} is absent)` };
+    }
+    const id = runtimeManifest.parseSelectionTarget(target);
+    if (!id)
+        return { generation: null, error: `selected target is invalid: ${JSON.stringify(target)}` };
+    const generations = join(root, 'generations');
+    const candidate = resolve(root, target);
+    if (!runtimeManifest.contained(generations, candidate))
+        return { generation: null, error: `selected target escapes ${generations}` };
+    return locateGeneration(candidate, id);
+}
+export function processLocatedGeneration() {
+    const location = processGeneration();
+    return location === null
+        ? { generation: null, error: 'no process generation (development checkout)' }
+        : locateGeneration(location.root, location.id);
+}
+export function readPackageVersion() {
+    const raw = readFileSync(join(PKG_ROOT, 'package.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.version;
+}
+export function resolveScope(raw) {
+    if (raw === undefined)
+        return 'user';
+    if (raw === 'user' || raw === 'project')
+        return raw;
+    throw usage(`scope must be 'user' or 'project', got: ${raw}`);
+}

package/dist/commands/sys/support/prepare.d.ts

@@ -0,0 +1,13 @@
+import type { LeafDef } from '../../../core/command.js';
+export interface SupportPrepareResult {
+    status: 'prepared';
+    reference: string;
+    path: string;
+    node_id: string;
+    source_count: number;
+    bytes: number;
+}
+/** Output-free: collects and writes the prepared artifact and returns a
+ *  small result. Never prints; the leaf below owns argv/rendering. */
+export declare function prepareSupportBundle(nodeId: string): SupportPrepareResult;
+export declare const supportPrepareLeaf: LeafDef;

package/dist/commands/sys/support/prepare.js

@@ -0,0 +1,235 @@
+// `crtr sys support prepare` — the local, zero-egress half of the support
+// bundle flow. Collects one node's diagnostics into a bounded artifact that
+// satisfies the plain manifest/bundle shape `sys support submit` validates
+// before any upload; prepare never touches the network, gh, or a repository.
+import { randomBytes } from 'node:crypto';
+import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readSync, rmSync, writeFileSync, } from 'node:fs';
+import { join, relative } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { general, usage } from '../../../core/errors.js';
+import { crtrHome, isSafeNodeId, jobDir } from '../../../core/canvas/paths.js';
+import { MAX_EVENT_RECORD_BYTES } from '../../../core/events/serialize.js';
+import { readLogSnapshot } from '../../../core/events/read.js';
+import { userScopeRoot } from '../../../core/scope.js';
+const MANIFEST_NAME = 'manifest.json';
+const BUNDLE_NAME = 'bundle.jsonl';
+const CAP_BYTES = 2_097_152;
+const MAX_RUNTIME_STATE_BYTES = MAX_EVENT_RECORD_BYTES - 1;
+const CATEGORIES = ['events', 'runtime_state', 'raw_residue'];
+// ---- reference generation ----
+function pad(value, length) {
+    return String(value).padStart(length, '0');
+}
+/** `YYYYMMDDTHHmmssSSSZ-xxxxxxxx`, matching submit's REFERENCE_PATTERN. */
+function generateReference(now) {
+    const date = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1, 2)}${pad(now.getUTCDate(), 2)}`;
+    const time = `${pad(now.getUTCHours(), 2)}${pad(now.getUTCMinutes(), 2)}${pad(now.getUTCSeconds(), 2)}${pad(now.getUTCMilliseconds(), 3)}`;
+    return `${date}T${time}Z-${randomBytes(4).toString('hex')}`;
+}
+// ---- compact bundle records ----
+function compactLine(record) {
+    return Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
+}
+/** Node-relevant canonical events plus visibly selected broker/daemon raw
+ *  residue, from the one bounded snapshot call this leaf is allowed. Returned
+ *  newest-first (the snapshot itself is chronological ascending) so that
+ *  `fitToCap`'s tail-drop trims the oldest history first. */
+function collectSnapshotRecords(nodeId, sources) {
+    const snapshot = readLogSnapshot({ nodeId }, true);
+    const records = [];
+    for (const item of snapshot.items) {
+        const category = item.kind === 'event' ? 'events' : 'raw_residue';
+        const ts = item.kind === 'event' ? item.envelope.ts : new Date(item.effectiveTsMs).toISOString();
+        const content = item.kind === 'event' ? item.envelope : item.content;
+        const existing = sources.get(item.source);
+        if (existing === undefined) {
+            sources.set(item.source, { category, status: 'read', truncated: item.truncated });
+        }
+        else if (item.truncated) {
+            existing.truncated = true;
+        }
+        records.push({ source: item.source, line: compactLine({ category, source: item.source, ts, content }) });
+    }
+    return records.reverse();
+}
+/** A single, shared, capped, no-symlink, identity-safe read of one fixed
+ *  state file — used for both job/fault and job/telemetry.json. Never follows
+ *  a symlink and confirms the fd it reads is the exact file it lstat'd. */
+function readFixedStateFile(absolute, maxBytes) {
+    let lst;
+    try {
+        lst = lstatSync(absolute);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { status: 'absent', truncated: false };
+        return { status: 'unreadable', truncated: false };
+    }
+    if (lst.isSymbolicLink() || !lst.isFile())
+        return { status: 'unreadable', truncated: false };
+    let fd;
+    try {
+        fd = openSync(absolute, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch {
+        return { status: 'unreadable', truncated: false };
+    }
+    try {
+        const fst = fstatSync(fd);
+        if (!fst.isFile() || fst.dev !== lst.dev || fst.ino !== lst.ino)
+            return { status: 'raced', truncated: false };
+        if (!Number.isSafeInteger(fst.size) || fst.size < 0)
+            return { status: 'unreadable', truncated: false };
+        const length = Math.min(fst.size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        let offset = 0;
+        while (offset < length) {
+            const got = readSync(fd, buffer, offset, length - offset, offset);
+            if (got <= 0)
+                return { status: 'unreadable', truncated: false };
+            offset += got;
+        }
+        let content;
+        try {
+            content = JSON.parse(buffer.toString('utf8'));
+        }
+        catch {
+            content = buffer.toString('utf8');
+        }
+        return { status: 'read', truncated: fst.size > maxBytes, content };
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // Best effort; the read already succeeded or failed.
+        }
+    }
+}
+/** Current job/fault and job/telemetry.json, one shared safe read each. */
+function collectRuntimeState(nodeId, ts, sources) {
+    const dir = jobDir(nodeId);
+    const home = crtrHome();
+    const records = [];
+    for (const name of ['fault', 'telemetry.json']) {
+        const absolute = join(dir, name);
+        const label = relative(home, absolute);
+        const read = readFixedStateFile(absolute, MAX_RUNTIME_STATE_BYTES);
+        sources.set(label, { category: 'runtime_state', status: read.status, truncated: read.truncated });
+        if (read.status === 'read') {
+            records.push({ source: label, line: compactLine({ category: 'runtime_state', source: label, ts, content: read.content }) });
+        }
+    }
+    return records;
+}
+// ---- manifest + cap fitting ----
+function renderManifestBuffer(base, sources) {
+    const manifest = {
+        reference: base.reference,
+        created_at: base.created_at,
+        node_id: base.node_id,
+        sources: [...sources.entries()].map(([source, state]) => ({
+            source,
+            category: state.category,
+            status: state.status,
+            truncated: state.truncated,
+        })),
+    };
+    return Buffer.from(`${JSON.stringify(manifest)}\n`, 'utf8');
+}
+/** Drop only trailing admitted records until manifest+bundle fit the cap.
+ *  Nothing in the manifest depends on the final byte count, so no fixed-point
+ *  convergence is needed — each drop can only flip a source's `truncated`
+ *  from false to true, and the loop is bounded by the record count. */
+function fitToCap(records, sources, base) {
+    const admitted = records.slice();
+    for (;;) {
+        const manifestBuffer = renderManifestBuffer(base, sources);
+        const bundleBuffer = Buffer.concat(admitted.map((record) => record.line));
+        if (manifestBuffer.length + bundleBuffer.length <= CAP_BYTES)
+            return { manifestBuffer, bundleBuffer };
+        if (admitted.length === 0)
+            throw general(`prepared support manifest alone exceeds the ${CAP_BYTES}-byte cap`);
+        const dropped = admitted.pop();
+        const state = sources.get(dropped.source);
+        if (state !== undefined)
+            state.truncated = true;
+    }
+}
+// ---- core ----
+/** Output-free: collects and writes the prepared artifact and returns a
+ *  small result. Never prints; the leaf below owns argv/rendering. */
+export function prepareSupportBundle(nodeId) {
+    if (typeof nodeId !== 'string' || !isSafeNodeId(nodeId)) {
+        throw usage('node_id must be a safe, non-empty single path segment of at most 128 UTF-8 bytes.');
+    }
+    const referenceRoot = join(userScopeRoot(), 'support');
+    mkdirSync(referenceRoot, { recursive: true });
+    const reference = generateReference(new Date());
+    const dir = join(referenceRoot, reference);
+    mkdirSync(dir); // Exclusive: throws if `reference` already names anything.
+    try {
+        const createdAt = new Date().toISOString();
+        const sources = new Map();
+        // Tiny, high-value current state goes first so a cap-trim only ever drops
+        // from the (potentially large) historical event/residue tail, and drops
+        // the oldest of that tail first — never runtime_state, never the newest
+        // history — without any per-category budget or priority machinery.
+        const runtimeRecords = collectRuntimeState(nodeId, createdAt, sources);
+        const snapshotRecords = collectSnapshotRecords(nodeId, sources);
+        const records = [...runtimeRecords, ...snapshotRecords];
+        const { manifestBuffer, bundleBuffer } = fitToCap(records, sources, { reference, created_at: createdAt, node_id: nodeId });
+        writeFileSync(join(dir, MANIFEST_NAME), manifestBuffer, { flag: 'wx' });
+        writeFileSync(join(dir, BUNDLE_NAME), bundleBuffer, { flag: 'wx' });
+        return {
+            status: 'prepared',
+            reference,
+            path: dir,
+            node_id: nodeId,
+            source_count: sources.size,
+            bytes: manifestBuffer.length + bundleBuffer.length,
+        };
+    }
+    catch (error) {
+        rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+export const supportPrepareLeaf = defineLeaf({
+    name: 'prepare',
+    description: 'locally collect one node\u2019s diagnostics into a bounded support bundle (zero egress)',
+    whenToUse: 'you want to hand a maintainer diagnostics for one node without exposing anything beyond that node\u2019s canonical events, current fault/telemetry state, and residue mentioning it. This step never leaves the machine; run `crtr sys support submit <reference>` afterward to actually share it.',
+    help: {
+        name: 'sys support prepare',
+        summary: 'locally collect one node\u2019s bounded diagnostics into ~/.crouter/support/<reference>/manifest.json + bundle.jsonl',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node_id',
+                required: true,
+                constraint: 'The node to collect diagnostics for — a safe, non-empty single path segment.',
+            },
+        ],
+        output: [
+            { name: 'status', type: 'string', required: true, constraint: 'Always "prepared" on success; every failure throws.' },
+            { name: 'reference', type: 'string', required: true, constraint: 'YYYYMMDDTHHmmssSSSZ-xxxxxxxx — pass this to `crtr sys support submit`.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the new ~/.crouter/support/<reference>/ directory.' },
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node the bundle was collected for.' },
+            { name: 'source_count', type: 'number', required: true, constraint: 'Number of distinct sources declared in the manifest.' },
+            { name: 'bytes', type: 'number', required: true, constraint: 'Combined size of manifest.json + bundle.jsonl, always \u2264 2,097,152.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Reads only local diagnostic sources for node_id: canonical events (node-relevant across daemon/broker/web), current job/fault and job/telemetry.json, and broker/daemon raw residue mentioning the node.',
+            'Creates a new ~/.crouter/support/<reference>/ directory containing exactly manifest.json and bundle.jsonl, bounded to 2,097,152 combined bytes; removes that directory if preparation fails partway.',
+            'Performs no network, DNS, gh, or repository access — the bundle stays entirely local until an explicit `crtr sys support submit <reference>`.',
+        ],
+    },
+    run: async (input) => {
+        const nodeId = input['node_id'];
+        if (nodeId === undefined || nodeId === '')
+            throw usage('node_id is required. Run `crtr sys support prepare -h`.');
+        return prepareSupportBundle(nodeId);
+    },
+});

package/dist/commands/sys/support/submit.d.ts

@@ -0,0 +1,19 @@
+import type { LeafDef } from '../../../core/command.js';
+export interface GhRunResult {
+    code: number | null;
+    stdout: Buffer;
+    stderr: string;
+    error?: Error;
+    /** HTTP status parsed from `gh api --include`; absent is deliberately indeterminate. */
+    httpStatus?: number;
+}
+export type GhRunner = (args: string[], input?: Buffer) => GhRunResult;
+export declare function defaultGhRunner(args: string[], input?: Buffer): GhRunResult;
+export interface SubmitResult {
+    status: 'submitted';
+    reference: string;
+    repository: string;
+    url: string;
+}
+export declare function submitPreparedBundle(reference: string, env: NodeJS.ProcessEnv, ghRunner?: GhRunner): Promise<SubmitResult>;
+export declare const supportSubmitLeaf: LeafDef;