@north-light/api 0.3.579 → 0.3.587

package/dist/commands/sys/limits.js

@@ -0,0 +1,133 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { LimitInputError, parseSize } from '../../launcher/limits/settings.js';
+import { cliClient } from '../api-client.js';
+const SIZE = 'A size: a byte count, a number with KiB, MiB, GiB or TiB, or `unlimited`.';
+const APP = 'An app id such as `app:terminal`.';
+function size(input, field) {
+    const raw = input[field];
+    if (raw === undefined)
+        return undefined;
+    try {
+        return parseSize(String(raw));
+    }
+    catch (error) {
+        if (error instanceof LimitInputError) {
+            throw new InputError({ error: 'invalid_size', message: `${error.message}; received ${String(raw)}`, field, next: 'Pass a size such as 2GiB, 512MiB, 1073741824 or unlimited.' });
+        }
+        throw error;
+    }
+}
+const cap = (bytes) => bytes === null ? 'none' : `${(bytes / 1024 ** 3).toFixed(bytes < 1024 ** 3 ? 3 : 1)} GiB`;
+const mib = (bytes) => bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(2)} GiB` : `${(bytes / 1024 ** 2).toFixed(0)} MiB`;
+function diskLine(d) {
+    const part = (name, bytes) => bytes === null ? '' : `, ${name} ${mib(bytes)}`;
+    return `Data disk: ${mib(d.used_bytes)} used of ${mib(d.total_bytes)} (${((100 * d.used_bytes) / Math.max(d.total_bytes, 1)).toFixed(0)}%)${part('/user', d.user_bytes)}${part('/runtime', d.runtime_bytes)}.`;
+}
+function line(a) {
+    const used = a.disk_used_bytes === null ? '' : `, disk used ${mib(a.disk_used_bytes)}`;
+    return `- \`${a.app}\` — memory ${cap(a.memory_bytes)} (${a.memory_source}), disk ${cap(a.disk_bytes)} (${a.disk_source})${used}`;
+}
+const OUTPUT_APP = { name: 'limits', type: 'AppLimitsDTO', required: true, constraint: 'Record: {app, memory_bytes, disk_bytes, memory_source, disk_source, disk_used_bytes}. A null cap means none.' };
+const show = defineLeaf({
+    name: 'show',
+    description: 'show each app\'s memory and disk caps and whether this host enforces them',
+    whenToUse: 'checking what an app may use, or why a run was stopped for memory',
+    help: {
+        name: 'sys limits show',
+        summary: 'list effective per-app memory and disk caps, marking the person-set overrides',
+        params: [],
+        output: [
+            { name: 'memory_enforced', type: 'boolean', required: true, constraint: 'False when this host cannot write cgroup memory limits; reason in memory_reason.' },
+            { name: 'memory_reason', type: 'string', required: false, constraint: 'Why memory limits are not enforced, or null.' },
+            { name: 'disk_enforced', type: 'boolean', required: true, constraint: 'False when the apps volume has no project quota; reason in disk_reason.' },
+            { name: 'disk_reason', type: 'string', required: false, constraint: 'Why disk limits are not enforced, or null.' },
+            { name: 'apps', type: 'AppLimitsDTO[]', required: true, constraint: 'One record per known app, by id; disk_used_bytes is measured by walking the app\'s folder when the host has no project quota.' },
+            { name: 'data_disk', type: 'DataDiskDTO', required: false, constraint: 'Record: {total_bytes, used_bytes, user_bytes, runtime_bytes} for the data volume; absent on a host without a launcher.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => ({ ...(await cliClient().showLimits()) }),
+    render: (result) => {
+        const r = result;
+        return [
+            r.memory_enforced ? 'Memory limits: enforced.' : `Memory limits: not enforced (${r.memory_reason}).`,
+            r.disk_enforced ? 'Disk limits: enforced.' : `Disk limits: not enforced (${r.disk_reason}).`,
+            ...(r.data_disk ? [diskLine(r.data_disk)] : []),
+            ...r.apps.map(line),
+        ].join('\n');
+    },
+});
+const set = defineLeaf({
+    name: 'set',
+    description: 'set an app\'s memory and/or disk cap',
+    whenToUse: 'raising or lowering what one app may use, or removing its cap with `unlimited`',
+    help: {
+        name: 'sys limits set',
+        summary: 'store a person-set memory and/or disk cap for one app and apply it now',
+        params: [
+            { kind: 'flag', name: 'app', type: 'string', required: true, constraint: APP },
+            { kind: 'flag', name: 'memory', type: 'string', required: false, constraint: `${SIZE} Total resident memory of all the app's running processes; at least 64 MiB.` },
+            { kind: 'flag', name: 'disk', type: 'string', required: false, constraint: `${SIZE} Bytes under the app's folder, cache included; at least 16 MiB.` },
+        ],
+        output: [
+            { name: 'app', type: 'string', required: true, constraint: 'The app changed.' },
+            { name: 'applied', type: 'boolean', required: true, constraint: 'True when the launcher wrote the caps to the host now; false when this host has no launcher, so the caps are only recorded.' },
+            OUTPUT_APP,
+        ],
+        outputKind: 'object',
+        effects: [
+            'Writes limits.json in the runtime directory, which no sandbox mounts.',
+            'The launcher rewrites the app\'s cgroup memory.max and project quota at once; running processes keep running, and a process over a lowered memory cap is reclaimed or OOM-killed by the kernel.',
+        ],
+    },
+    run: async (input) => {
+        const memory = size(input, 'memory');
+        const disk = size(input, 'disk');
+        if (memory === undefined && disk === undefined) {
+            throw new InputError({ error: 'nothing_to_set', message: 'received neither --memory nor --disk', next: 'Pass --memory <size>, --disk <size>, or both.' });
+        }
+        const out = await cliClient().setAppLimits(String(input['app']), { ...(memory === undefined ? {} : { memory_bytes: memory }), ...(disk === undefined ? {} : { disk_bytes: disk }) });
+        return out;
+    },
+    render: (result) => `${line(result.limits)}${result.applied ? '' : '\nRecorded only: this host has no launcher to enforce it.'}`,
+});
+const remove = defineLeaf({
+    name: 'remove',
+    description: 'remove a person-set cap so the app returns to its default',
+    whenToUse: 'undoing a `sys limits set` override',
+    help: {
+        name: 'sys limits remove',
+        summary: 'drop an app\'s memory and/or disk override; with neither flag, both',
+        params: [
+            { kind: 'flag', name: 'app', type: 'string', required: true, constraint: APP },
+            { kind: 'flag', name: 'memory', type: 'bool', required: false, constraint: 'Remove the memory override.' },
+            { kind: 'flag', name: 'disk', type: 'bool', required: false, constraint: 'Remove the disk override.' },
+        ],
+        output: [
+            { name: 'app', type: 'string', required: true, constraint: 'The app changed.' },
+            { name: 'applied', type: 'boolean', required: true, constraint: 'True when the launcher wrote the default caps now.' },
+            OUTPUT_APP,
+        ],
+        outputKind: 'object',
+        effects: ['Edits limits.json and has the launcher apply the default caps at once.'],
+    },
+    run: async (input) => {
+        const fields = [...(input['memory'] === true ? ['memory'] : []), ...(input['disk'] === true ? ['disk'] : [])];
+        const out = await cliClient().removeAppLimits(String(input['app']), fields.length === 0 ? ['memory', 'disk'] : fields);
+        return out;
+    },
+    render: (result) => line(result.limits),
+});
+export const sysLimitsBranch = defineBranch({
+    name: 'limits',
+    description: 'per-app memory and disk caps on this runtime',
+    whenToUse: 'a person needs to see, raise, lower or remove what one app may use of the hosted runtime\'s memory and disk',
+    help: {
+        name: 'sys limits',
+        summary: 'view and change per-app memory and disk caps',
+        model: 'Every app has a default memory and disk cap; the terminal app has none. A person-set override replaces the default for one resource of one app and applies immediately. An app cannot change its own caps. A host without cgroup memory control or disk project quota records the caps and reports the limit as not enforced.',
+    },
+    children: [show, set, remove],
+});

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

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

package/dist/commands/sys/logs.js

@@ -0,0 +1,129 @@
+import { defineLeaf } from '../../core/command.js';
+import { isSafeNodeId } from '../../core/canvas/paths.js';
+import { usage } from '../../core/errors.js';
+import { validateOperationId } from '../../core/events/operation-id.js';
+import { readLogSnapshot } from '../../core/events/read.js';
+import { emitLine, isJsonOutput, recordPreviewLine } from '../../core/io.js';
+const ISO_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/u;
+const MAX_PATTERN_BYTES = 4_096;
+function invalidFlag(flag, received, expected) {
+    throw usage(`--${flag} ${expected}; received ${JSON.stringify(received)}.`, {
+        received,
+        field: flag,
+        next: `Retry with a value that ${expected}.`,
+    });
+}
+function parseTimestamp(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw.trim();
+    const match = ISO_TIMESTAMP.exec(value);
+    const parsed = Date.parse(value);
+    if (match === null || !Number.isFinite(parsed)) {
+        invalidFlag(flag, raw, 'must be a valid ISO 8601 timestamp with a timezone');
+    }
+    const calendar = new Date(Date.parse(`${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`));
+    if (calendar.getUTCFullYear() !== Number(match[1])
+        || calendar.getUTCMonth() + 1 !== Number(match[2])
+        || calendar.getUTCDate() !== Number(match[3])
+        || calendar.getUTCHours() !== Number(match[4])
+        || calendar.getUTCMinutes() !== Number(match[5])
+        || calendar.getUTCSeconds() !== Number(match[6])) {
+        invalidFlag(flag, raw, 'must be a valid ISO 8601 timestamp with a timezone');
+    }
+    return parsed;
+}
+function parseNodeId(raw) {
+    if (raw === undefined)
+        return undefined;
+    const nodeId = raw.trim();
+    if (!isSafeNodeId(nodeId)) {
+        invalidFlag('node', raw, 'must be one non-empty path segment of at most 128 UTF-8 bytes');
+    }
+    return nodeId;
+}
+function parseOperationId(raw) {
+    if (raw === undefined)
+        return undefined;
+    const operationId = raw.trim();
+    try {
+        return validateOperationId(operationId);
+    }
+    catch {
+        invalidFlag('operation', raw, 'must be 32 lowercase non-zero hexadecimal characters');
+    }
+}
+function parsePattern(raw) {
+    if (raw === undefined)
+        return undefined;
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (bytes === 0 || bytes > MAX_PATTERN_BYTES) {
+        invalidFlag('pattern', raw, `must be a non-empty literal of at most ${MAX_PATTERN_BYTES.toLocaleString('en-US')} UTF-8 bytes`);
+    }
+    return raw;
+}
+function renderEvent(envelope) {
+    const { v: _version, ts, level, event, component, operation_id: operationId, ...optional } = envelope;
+    const suffix = Object.keys(optional).length === 0 ? '' : ` ${JSON.stringify(optional)}`;
+    return `${ts} ${level.toUpperCase()} ${component} ${event} op=${operationId}${suffix}`;
+}
+export const sysLogsLeaf = defineLeaf({
+    name: 'logs',
+    description: 'inspect recent local runtime events',
+    whenToUse: 'you need a bounded local diagnostic snapshot, especially to correlate a node with an operation ID.',
+    help: {
+        name: 'sys logs',
+        summary: 'show the latest 200 matching local event and raw-residue records, oldest first',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Safe node ID; the node need not still be active.' },
+            { kind: 'flag', name: 'component', type: 'enum', choices: ['daemon', 'broker'], required: false, constraint: 'Owning runtime component.' },
+            { kind: 'flag', name: 'operation', type: 'string', required: false, constraint: 'Exact 32-character lowercase non-zero hexadecimal operation ID.' },
+            { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'Inclusive ISO 8601 lower bound with a timezone.' },
+            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Inclusive ISO 8601 upper bound with a timezone; cannot precede --since.' },
+            { kind: 'flag', name: 'level', type: 'enum', choices: ['debug', 'info', 'warn', 'error'], required: false, constraint: 'Minimum severity.' },
+            { kind: 'flag', name: 'pattern', type: 'string', required: false, constraint: 'Case-insensitive literal, non-empty and at most 4,096 UTF-8 bytes.' },
+        ],
+        output: [
+            { name: 'record', type: 'EventEnvelope | RAW line', required: false, constraint: 'At most 200 matches, oldest to newest. Default canonical summaries occupy one line; unstructured daemon/broker residue is visibly prefixed RAW. Machine JSON output is canonical EventEnvelope JSONL only.' },
+        ],
+        outputKind: 'jsonl',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nodeId = parseNodeId(input.node);
+        const operationId = parseOperationId(input.operation);
+        const sinceMs = parseTimestamp('since', input.since);
+        const untilMs = parseTimestamp('until', input.until);
+        if (sinceMs !== undefined && untilMs !== undefined && sinceMs > untilMs) {
+            throw usage('--since cannot be later than --until.', {
+                received: { since: input.since, until: input.until },
+                field: 'since/until',
+                next: 'Retry with an inclusive range whose lower bound does not exceed its upper bound.',
+            });
+        }
+        const query = {
+            nodeId,
+            component: input.component,
+            operationId,
+            sinceMs,
+            untilMs,
+            minimumLevel: input.level,
+            pattern: parsePattern(input.pattern),
+        };
+        const json = isJsonOutput();
+        const snapshot = readLogSnapshot(query, !json);
+        for (const item of snapshot.items) {
+            if (item.kind === 'event') {
+                if (json)
+                    emitLine({ ...item.envelope });
+                else {
+                    recordPreviewLine({ ...item.envelope });
+                    process.stdout.write(`${renderEvent(item.envelope)}\n`);
+                }
+            }
+            else if (!json) {
+                process.stdout.write(`RAW ${item.source} ${new Date(item.effectiveTsMs).toISOString()} ${JSON.stringify(item.content)}\n`);
+            }
+        }
+    },
+});

package/dist/commands/sys/machine/rotate.d.ts

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

package/dist/commands/sys/machine/rotate.js

@@ -0,0 +1,49 @@
+import { defineBranch, defineLeaf } from '../../../core/command.js';
+import { general, usage } from '../../../core/errors.js';
+import { personBearer } from '../../../core/directory/person-credential.js';
+import { readMachineConfig, writeMachineCredential } from '../../../daemon/machine-link/config.js';
+const rotate = defineLeaf({
+    name: 'rotate',
+    description: 'replace this Mac\'s machine credential',
+    whenToUse: 'the credential this imported Mac presents on its link to Northlight may have leaked, or the console revoked it',
+    help: {
+        name: 'sys machine rotate',
+        summary: 'ask the control plane for a new machine credential for this Mac and store it',
+        params: [],
+        output: [{ name: 'environment_id', type: 'string', required: true, constraint: 'The machine environment the new credential belongs to.' }],
+        outputKind: 'object',
+        effects: [
+            'Calls `POST /v1/imports/<run>/machine-credential?rotate=1`, which replaces the stored hash for this machine environment, then writes the new secret to `runtime/secrets/machine-credential` (mode 0600). Authenticates with the person\'s sign-in (`crtr sys signin`; `not_signed_in` without one). Fails when `runtime/machine.json` is missing: this install was not imported as a machine.',
+            'The old credential stops opening links as soon as the control plane has replaced it, and the link it already holds is closed within 15 seconds; the Mac reconnects with the new credential.',
+        ],
+    },
+    run: async () => {
+        const config = readMachineConfig();
+        if (config === undefined)
+            throw usage('this install was not imported as a machine: runtime/machine.json is missing');
+        // The sign-in stored by `crtr sys signin` (or by the import): the same person who imported this Mac.
+        const token = await personBearer(config.directoryUrl);
+        const url = new URL(`/v1/imports/${encodeURIComponent(config.runId)}/machine-credential?rotate=1`, config.apiUrl);
+        const response = await fetch(url, { method: 'POST', headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(30_000) });
+        const text = await response.text();
+        if (!response.ok)
+            throw general(`the control plane answered ${response.status}: ${text.slice(0, 300)}`);
+        const body = JSON.parse(text);
+        if (typeof body.credential !== 'string' || typeof body.environment_id !== 'string')
+            throw general('the control plane answered without a credential');
+        writeMachineCredential(body.credential);
+        return { environment_id: body.environment_id };
+    },
+    render: (result) => `<machine environment="${result['environment_id']}" credential="rotated"/>`,
+});
+export const sysMachineBranch = defineBranch({
+    name: 'machine',
+    description: 'this Mac\'s link to Northlight after import',
+    whenToUse: 'an imported Mac\'s machine credential must be replaced',
+    help: {
+        name: 'sys machine',
+        summary: 'manage the machine credential of an imported Mac',
+        model: 'After import the Mac runs `crtrd --role machine`: it holds one outbound link to Northlight, authenticated by a machine credential stored in `runtime/secrets/machine-credential`, and executes the runner calls Northlight sends over it.',
+    },
+    children: [rotate],
+});

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

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

package/dist/commands/sys/migrate.js

@@ -0,0 +1,79 @@
+// `crtr sys migrate`: the offline layout migration, then the daemon-owned
+// canvas import (004-canvas-documents) of the legacy memory stores.
+import { defineLeaf } from '../../core/command.js';
+import { general } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { layoutNeedsMigration } from '../../core/layout.js';
+import { migrateLayout } from '../../core/layout-migrate/index.js';
+export const sysMigrateLeaf = defineLeaf({
+    name: 'migrate',
+    description: 'migrate an old runtime layout offline, then import the legacy memory stores into the canvas',
+    whenToUse: 'when the daemon reports startup `blocked` by the canvas import, or after moving from a release that kept memory as markdown stores. Run --dry-run first to see the plan and what it resolves; a write run on an imported home does nothing.',
+    help: {
+        name: 'sys migrate',
+        summary: 'move an old runtime layout offline, then plan or run the daemon-owned canvas import',
+        guide: 'A layout migration requires the daemon to be stopped, runs in this process, and stops after writing the layout version; start the daemon and run `crtr sys migrate` again. The daemon then plans the canvas import: every legacy store (the user store, each profile store, every repository `.crouter/memory` reached from a profile project or a node\'s cwd, node context folders and reports) becomes documents with their revision history, owned by the person, a profile, a repo, or a node. Both stages resolve leftovers and clashes themselves (a folder with no node row is set aside, two repos with one namespace get distinct handles, an unparseable file imports as its raw text, and so on) and list each in `layout_resolutions` and `resolutions`, on the dry run too. The daemon runs the import itself at startup; only a blocker (the store migrations of a skipped release never ran) makes it write nothing and hold startup in `blocked`. The import writes in one transaction and resumes startup. The markdown files are left on disk and are never read again.',
+        params: [
+            { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Plan and report without writing. On an imported home, returns the recorded report with pending false.' },
+        ],
+        output: [
+            { name: 'loose_keys', type: 'string[]', required: false, constraint: 'Loose credential paths moved or set aside; never values.' },
+            { name: 'layout_moved', type: 'number', required: false, constraint: 'Old-layout paths moved or stored paths rewritten on this run; present when the layout migration ran.' },
+            { name: 'layout_resolutions', type: 'string[]', required: false, constraint: 'One line per leftover the layout migration resolved (or, under --dry-run, will resolve): set-aside folders, moved profile files, closed worktree rows, cleared transcript paths.' },
+            { name: 'layout_absent_credentials', type: 'string[]', required: false, constraint: 'Old credential files the layout migration looked for and did not find (or, under --dry-run, will not find); present when the layout migration ran. An absent file is legitimate when the old home never held that credential.' },
+            { name: 'stores', type: 'object[]', required: false, constraint: 'Every store root found: {root, owner, docs, skipped?}; skipped is duplicate-worktree for a second checkout of an imported repo.' },
+            { name: 'counts', type: 'object', required: false, constraint: 'Planned (or written) totals: documents.<kind>, documents.owner.<person|profile|repo|node>, revisions, documents.rewritten, owners, stores, profile-limits, and informational counts. Empty on a write run over an imported home.' },
+            { name: 'rewrites', type: 'object[]', required: false, constraint: 'Pointer rewrites in head bodies: {path, from, to}.' },
+            { name: 'dropped_fields', type: 'object[]', required: false, constraint: 'Frontmatter fields with no canvas equivalent: {path, field}.' },
+            { name: 'skipped', type: 'object[]', required: false, constraint: 'Files or roots not imported, with the reason: {path, reason}.' },
+            { name: 'resolutions', type: 'object[]', required: false, constraint: 'Clashes the import resolved itself: {kind, message, paths}; kind is invalid-source, invalid-history, name-clash, repo-handle, profile-handle, repo-identity, or delivery-limit.' },
+            { name: 'blockers', type: 'object[]', required: false, constraint: '{kind, message, paths}; kind is marker (the store migrations of a skipped release never ran). A blocker makes the command fail with this whole report in `received`; nothing is written.' },
+            { name: 'dryRun', type: 'boolean', required: true, constraint: 'True when nothing was written.' },
+            { name: 'pending', type: 'boolean', required: false, constraint: 'True while this home has not been imported.' },
+            { name: 'resumed', type: 'boolean', required: false, constraint: 'True only when this run resumed a blocked daemon startup.' },
+            { name: 'resume_error', type: 'string', required: false, constraint: 'Present when the import succeeded but normal daemon startup then failed.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'With an old layout and no layout version, refuses while a daemon answers, moves the runtime records, sets aside leftovers under runtime/set-aside/, rewrites stored paths and writes the layout version last, then stops; the next run, with the daemon started, plans or runs the canvas import.',
+            'Without --dry-run and with no blockers: stores revision bodies, converts profile project memory caps into profile delivery limits, and writes owners, documents, revisions, links, and the authoring nodes\' watches in one canvas transaction, recorded so it runs once.',
+            'Under --dry-run: read-only, writes nothing.',
+        ],
+    },
+    run: async (input) => {
+        const dryRun = input.dryRun === true;
+        const layout = layoutNeedsMigration() ? await migrateLayout(dryRun) : null;
+        if (dryRun && layout !== null) {
+            return { layout_resolutions: layout.resolutions, layout_absent_credentials: layout.absentCredentials, dryRun, follow_up: 'Preview only — re-run without --dry-run to migrate the layout; the canvas import is planned after it.' };
+        }
+        // The layout run is offline: no daemon owns this volume yet.
+        if (layout !== null) {
+            return {
+                layout_moved: layout.moved,
+                layout_resolutions: layout.resolutions,
+                layout_absent_credentials: layout.absentCredentials,
+                dryRun,
+                follow_up: 'Layout migrated. Start the daemon (in a container, `docker compose exec`), then run `crtr sys migrate --dry-run` against it to plan the canvas import.',
+            };
+        }
+        let report;
+        try {
+            report = await cliClient().migrateState({ dry_run: dryRun });
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+        if (report.blockers.length > 0) {
+            throw general(`canvas import blocked by ${report.blockers.length} finding(s) — nothing was written`, {
+                received: report,
+                next: 'Do what received.blockers[].message says, then run `crtr sys migrate` again.',
+            });
+        }
+        return {
+            ...report,
+            follow_up: !report.pending
+                ? (dryRun ? 'Already imported — this is the recorded report.' : undefined)
+                : 'Preview only — re-run without --dry-run to import.',
+        };
+    },
+});

package/dist/commands/sys/panels/broker-limits-panel.d.ts

@@ -0,0 +1,17 @@
+import { Input } from '@earendil-works/pi-tui';
+import { type SetupPanel } from '../../../core/tui/panel.js';
+export declare class BrokerLimitsPanel implements SetupPanel {
+    private readonly onChange;
+    readonly warningInput: Input;
+    readonly hardCapInput: Input;
+    private index;
+    private notice;
+    private _focused;
+    constructor(onChange: () => void);
+    set focused(value: boolean);
+    private selected;
+    private move;
+    private save;
+    handleInput(data: string, matches?: (id: string, input: string) => boolean): boolean;
+    render(width: number): string[];
+}

package/dist/commands/sys/panels/broker-limits-panel.js

@@ -0,0 +1,110 @@
+import { Input, truncateToWidth } from '@earendil-works/pi-tui';
+import { readConfig, updateRawConfigAtomically } from '../../../core/config.js';
+import { BROKER_LIMIT_OVERRIDE_PRECEDENCE } from '../setup.js';
+import { padAnsi, theme, wrapText } from '../../../core/tui/panel.js';
+function positive(value) {
+    return /^\d+$/.test(value) &&
+        Number.isSafeInteger(Number(value)) &&
+        Number(value) >= 1
+        ? Number(value)
+        : undefined;
+}
+export class BrokerLimitsPanel {
+    onChange;
+    warningInput = new Input();
+    hardCapInput = new Input();
+    index = 0;
+    notice;
+    _focused = false;
+    constructor(onChange) {
+        this.onChange = onChange;
+        const thresholds = readConfig("user").brokerThresholds;
+        this.warningInput.setValue(String(thresholds.warning));
+        this.warningInput.handleInput("\x05");
+        this.hardCapInput.setValue(String(thresholds.automaticReviveCap));
+        this.hardCapInput.handleInput("\x05");
+        this.warningInput.onSubmit = () => this.save();
+        this.hardCapInput.onSubmit = () => this.save();
+    }
+    set focused(value) {
+        this._focused = value;
+        this.warningInput.focused = value && this.index === 0;
+        this.hardCapInput.focused = value && this.index === 1;
+    }
+    selected() {
+        return this.index === 0 ? this.warningInput : this.hardCapInput;
+    }
+    move(delta) {
+        this.index = ((this.index + delta + 2) % 2);
+        this.focused = this._focused;
+        this.notice = undefined;
+    }
+    async save() {
+        const warning = positive(this.warningInput.getValue());
+        const cap = positive(this.hardCapInput.getValue());
+        if (warning === undefined || cap === undefined)
+            this.notice = "Both broker limits must be positive integers.";
+        else if (warning > cap)
+            this.notice =
+                "Warning threshold cannot exceed the automatic-revive hard cap.";
+        else {
+            await updateRawConfigAtomically("user", (latest) => ({
+                ...latest,
+                brokerThresholds: { warning, automaticReviveCap: cap },
+            }));
+            this.notice = `Saved to user config. Applies next tick. ${BROKER_LIMIT_OVERRIDE_PRECEDENCE}`;
+        }
+        this.onChange();
+    }
+    handleInput(data, matches) {
+        if (/^\d+$/.test(data)) {
+            this.selected().handleInput(data);
+            this.notice = undefined;
+            this.onChange();
+            return true;
+        }
+        if (!matches)
+            return false;
+        if (matches("crtr.setup.list-down", data))
+            this.move(1);
+        else if (matches("crtr.setup.list-up", data))
+            this.move(-1);
+        // DEL (\x7f) is what terminals send for backspace and its code point sits
+        // above the control range, so it has to be excluded here or editing an
+        // existing value is refused as a non-digit keystroke.
+        else if (data.length > 0 &&
+            [...data].every((char) => {
+                const code = char.codePointAt(0);
+                return code >= 32 && code !== 127;
+            }))
+            this.notice = "Broker limits accept digits only.";
+        else {
+            this.selected().handleInput(data);
+            if (data !== "\r" && data !== "\n")
+                this.notice = undefined;
+        }
+        this.onChange();
+        return true;
+    }
+    render(width) {
+        const out = [
+            truncateToWidth(`${theme.fg("accent", theme.bold("Broker limits"))}${theme.fg("dim", "  user scope · defaults 16 / 32")}`, width),
+            truncateToWidth(theme.fg("dim", "These bounds govern daemon automatic revive; explicit node revives remain available."), width),
+            "",
+        ];
+        const line = (index, label, description, input) => {
+            const selected = index === this.index;
+            out.push(truncateToWidth(`${selected ? theme.fg("accent", "▶") : " "} ${padAnsi(selected ? theme.fg("accent", label) : label, 24)} ${input.render(Math.max(8, width - 28))[0] ?? ""}`, width));
+            out.push(truncateToWidth(theme.fg("dim", `    ${description}`), width));
+        };
+        line(0, "Warning threshold", "Warn when live brokers reach this count. Default: 16.", this.warningInput);
+        line(1, "Automatic-revive hard cap", "Defer automatic revives at this count. Default: 32.", this.hardCapInput);
+        out.push("");
+        for (const text of wrapText(`Configured limits apply next tick. ${BROKER_LIMIT_OVERRIDE_PRECEDENCE}`, width))
+            out.push(theme.fg("dim", text));
+        if (this.notice)
+            for (const text of wrapText(this.notice, width))
+                out.push(theme.fg(this.notice.startsWith("Saved") ? "success" : "warning", text));
+        return out;
+    }
+}

package/dist/commands/sys/panels/dependencies-panel.d.ts

@@ -0,0 +1,14 @@
+import type { SetupSystemInstallPlan } from '../setup-core.js';
+import { type SetupPanel } from '../../../core/tui/panel.js';
+export declare class DependenciesPanel implements SetupPanel {
+    private readonly plans;
+    private readonly onChange;
+    private readonly selectedTools;
+    private index;
+    constructor(plans: SetupSystemInstallPlan[], onChange: () => void);
+    badge(): string;
+    get selected(): readonly SetupSystemInstallPlan[];
+    private current;
+    handleInput(data: string, matches?: (id: string, input: string) => boolean): boolean;
+    render(width: number): string[];
+}

package/dist/commands/sys/panels/dependencies-panel.js

@@ -0,0 +1,80 @@
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import { theme } from '../../../core/tui/panel.js';
+function toolLabel(tool) {
+    return tool === "nvim" ? "nvim" : tool === "nerd-font" ? "Nerd Font" : "tmux";
+}
+export class DependenciesPanel {
+    plans;
+    onChange;
+    selectedTools = new Set();
+    index = 0;
+    constructor(plans, onChange) {
+        this.plans = plans;
+        this.onChange = onChange;
+        for (const plan of plans)
+            if (!plan.installed && plan.autoInstall)
+                this.selectedTools.add(plan.tool);
+        const firstMissing = plans.findIndex((plan) => !plan.installed);
+        this.index = firstMissing >= 0 ? firstMissing : 0;
+    }
+    badge() {
+        const missing = this.plans.filter((plan) => !plan.installed).length;
+        return missing === 0 ? "\u2713" : `${missing} missing`;
+    }
+    get selected() {
+        return this.plans.filter((tool) => !tool.installed && this.selectedTools.has(tool.tool));
+    }
+    current() {
+        return this.plans[this.index];
+    }
+    handleInput(data, matches) {
+        if (!matches)
+            return false;
+        if (matches("crtr.setup.list-down", data) ||
+            matches("crtr.setup.list-up", data)) {
+            const entries = this.plans
+                .map((tool, index) => ({ tool, index }))
+                .filter(({ tool }) => !tool.installed);
+            if (entries.length === 0)
+                return true;
+            const current = entries.findIndex(({ index }) => index === this.index);
+            const delta = matches("crtr.setup.list-down", data) ? 1 : -1;
+            this.index =
+                entries[((current >= 0 ? current : 0) + delta + entries.length) %
+                    entries.length].index;
+        }
+        else if (matches("crtr.setup.toggle", data)) {
+            const tool = this.current();
+            if (tool && !tool.installed)
+                this.selectedTools.has(tool.tool)
+                    ? this.selectedTools.delete(tool.tool)
+                    : this.selectedTools.add(tool.tool);
+        }
+        else
+            return false;
+        this.onChange();
+        return true;
+    }
+    render(width) {
+        const out = [
+            truncateToWidth(`${theme.fg("accent", theme.bold("System deps"))}${theme.fg("dim", "  tmux + nvim + Nerd Font check")}`, width),
+        ];
+        for (const [index, tool] of this.plans.entries()) {
+            const selected = index === this.index;
+            const marker = selected ? theme.fg("accent", "▶") : theme.fg("dim", " ");
+            if (tool.installed) {
+                out.push(truncateToWidth(`${marker} ${theme.fg("success", "✓ installed")} ${theme.fg("muted", toolLabel(tool.tool))}`, width));
+                continue;
+            }
+            const checked = this.selectedTools.has(tool.tool)
+                ? theme.fg("success", "[x]")
+                : theme.fg("dim", "[ ]");
+            const label = tool.command ?? tool.hint;
+            const name = selected
+                ? theme.fg("accent", `Install ${toolLabel(tool.tool)}`)
+                : `Install ${toolLabel(tool.tool)}`;
+            out.push(truncateToWidth(`${marker} ${checked} ${name} ${theme.fg("dim", "—")} ${theme.fg("muted", label)} ${theme.fg("warning", "not installed")}`, width));
+        }
+        return out;
+    }
+}