@north-light/api 0.3.580 → 0.3.588

package/dist/commands/sys/setup-settings-runner.d.ts

@@ -0,0 +1,13 @@
+import { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
+import type { BindingId, BindingResolution } from '../../core/keybindings/index.js';
+import { type TuiPageContext, type TuiPageControl, type TuiPageSurface } from '../../core/tui/page-host.js';
+/** Setup and settings both edit pi's model configuration, so their host adds
+ * the model runtime to the shared page context. Every other page concern —
+ * theme, keybindings, terminal lifecycle — belongs to `runTuiPage`. */
+type SetupSettingsProcessContext = TuiPageContext & {
+    agentDir: string;
+    runtime: ModelRuntime;
+    registry: ModelRegistry;
+};
+export declare function runSetupSettingsProcess<Result>(createSurface: (context: SetupSettingsProcessContext, control: TuiPageControl<Result>) => TuiPageSurface, interceptCancel?: (data: string, bindings: BindingResolution<BindingId>) => boolean): Promise<Result | undefined>;
+export {};

package/dist/commands/sys/setup-settings-runner.js

@@ -0,0 +1,15 @@
+import { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
+import { join } from 'node:path';
+import { piAgentDir } from '../../core/runtime/package-health.js';
+import { ApiCredentialStore } from '../../core/model-auth/api-credential-store.js';
+import { cliClient } from '../api-client.js';
+import { runTuiPage, } from '../../core/tui/page-host.js';
+export async function runSetupSettingsProcess(createSurface, interceptCancel) {
+    const agentDir = piAgentDir();
+    const runtime = await ModelRuntime.create({
+        credentials: new ApiCredentialStore(() => cliClient()),
+        modelsPath: join(agentDir, "models.json"),
+    });
+    const registry = new ModelRegistry(runtime);
+    return runTuiPage((context, control) => createSurface({ ...context, agentDir, runtime, registry }, control), interceptCancel);
+}

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

@@ -0,0 +1,52 @@
+import { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
+import { TUI, type Component, type Focusable } from '@earendil-works/pi-tui';
+import { type BindingId, type BindingResolution } from '../../core/keybindings/index.js';
+import { type SetupPackageId, type SetupPackageManifestEntry, type SetupSubmission, type SetupSystemInstallPlan } from './setup-core.js';
+import { type OptionAsAltPlan } from './terminal-option.js';
+/** The host owns step navigation, focus, submission and composition. Each step
+ *  owns its own mutable UI state. */
+export declare class SetupWizard implements Component, Focusable {
+    private readonly bindings;
+    private readonly terminalRows;
+    private readonly providers;
+    private readonly plugins;
+    private readonly pluginEnv;
+    private readonly dependencies;
+    private readonly terminal;
+    private readonly steps;
+    private step;
+    private confirming;
+    private cachedWidth;
+    private cachedHeight;
+    private cachedLines;
+    private _focused;
+    private readonly installedPackageIds;
+    onSubmit?: (submission: SetupSubmission) => void;
+    onCancel?: () => void;
+    constructor(manifest: SetupPackageManifestEntry[], installedPackageIds: Set<SetupPackageId>, systemPlans: SetupSystemInstallPlan[], tui: TUI, agentDir: string, runtime: ModelRuntime, registry: ModelRegistry, bindings: BindingResolution<BindingId>, terminalRows: () => number, existingEnvNames: Set<string>, optionPlan?: OptionAsAltPlan | null);
+    set focused(value: boolean);
+    get focused(): boolean;
+    invalidate(): void;
+    private matches;
+    private label;
+    /** Gestures safe to advertise while a text field owns the keyboard. */
+    private fieldSafeLabel;
+    private setStep;
+    private moveStep;
+    /** Enter on a non-final step walks forward; on the last one it finishes. */
+    private advance;
+    private cancel;
+    dispose(): void;
+    private hasPendingInstalls;
+    private buildSubmission;
+    private finalize;
+    private currentPanel;
+    handleInput(data: string): void;
+    /** `Providers › Plugins › Dependencies`, active step lit, done
+     *  steps checked — a first run should always show how much is left. */
+    private renderTrail;
+    private footer;
+    private renderConfirm;
+    render(width: number): string[];
+}
+export declare function runSetup(): Promise<'completed' | 'skipped'>;

package/dist/commands/sys/setup-wizard.js

@@ -0,0 +1,351 @@
+// The `crtr sys setup` first-run installer: log in a provider, then install the
+// companion packages and system dependencies a fresh machine needs.
+//
+// Ongoing configuration — models, keybindings, display preferences, panes,
+// broker limits, updates — lives in settings-shell.ts. Both hosts share the
+// panels in ./panels; this one is a linear stepper that ends in a single
+// confirmed install, that one is a persistent editor that saves as you go.
+import { matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+import { formatGesture, formatMovePair, matchesPiTuiInput, } from '../../core/keybindings/index.js';
+import { buildSetupInitialState, executeSetupSubmission, formatSetupExecutionSummary, packagePlanAction, reconcileInboxFrontDoor, renderSetupStaticInstructions, setupPluginEnvFields, } from './setup-core.js';
+import { runSetupSettingsProcess } from './setup-settings-runner.js';
+import { DependenciesPanel } from './panels/dependencies-panel.js';
+import { PAGE_CHROME_ROWS, pageFrame, theme, } from '../../core/tui/panel.js';
+import { PluginsPanel } from './panels/plugins-panel.js';
+import { ProviderPanel } from './panels/provider-panel.js';
+import { PluginEnvPanel } from './panels/plugin-env-panel.js';
+import { TerminalPanel } from './panels/terminal-panel.js';
+import { describeEdit, planOptionAsAlt } from './terminal-option.js';
+import { homedir } from 'node:os';
+import { cliClient } from '../api-client.js';
+const BASE_STEPS = ["Providers", "Plugins", "Plugin env", "Dependencies"];
+/** Appended AFTER the existing steps, and only on macOS, so the original order
+ *  and content never change. */
+const OPTION_STEP = "Option key";
+/** The host owns step navigation, focus, submission and composition. Each step
+ *  owns its own mutable UI state. */
+export class SetupWizard {
+    bindings;
+    terminalRows;
+    providers;
+    plugins;
+    pluginEnv;
+    dependencies;
+    terminal;
+    steps;
+    step = 0;
+    confirming = false;
+    cachedWidth;
+    cachedHeight;
+    cachedLines;
+    _focused = false;
+    installedPackageIds;
+    onSubmit;
+    onCancel;
+    constructor(manifest, installedPackageIds, systemPlans, tui, agentDir, runtime, registry, bindings, terminalRows, existingEnvNames, optionPlan = null) {
+        this.bindings = bindings;
+        this.terminalRows = terminalRows;
+        this.installedPackageIds = installedPackageIds;
+        const invalidate = () => this.invalidate();
+        this.providers = new ProviderPanel(tui, agentDir, runtime, registry);
+        this.providers.onChange = invalidate;
+        this.plugins = new PluginsPanel(manifest, installedPackageIds, invalidate);
+        this.pluginEnv = new PluginEnvPanel(existingEnvNames, invalidate);
+        this.dependencies = new DependenciesPanel(systemPlans, invalidate);
+        this.terminal = optionPlan === null ? undefined : new TerminalPanel(optionPlan, invalidate);
+        this.steps = this.terminal === undefined ? BASE_STEPS : [...BASE_STEPS, OPTION_STEP];
+    }
+    set focused(value) {
+        this._focused = value;
+    }
+    get focused() {
+        return this._focused;
+    }
+    invalidate() {
+        this.cachedWidth = undefined;
+        this.cachedHeight = undefined;
+        this.cachedLines = undefined;
+    }
+    matches(id, data) {
+        return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    label(id) {
+        const gestures = this.bindings.gestures(id);
+        return gestures.length === 0
+            ? "disabled"
+            : formatGesture(gestures[0].split(" > ").pop());
+    }
+    /** Gestures safe to advertise while a text field owns the keyboard. */
+    fieldSafeLabel(id) {
+        const gestures = this.bindings.gestures(id).filter((gesture) => {
+            if (gesture.includes(" > "))
+                return true;
+            const key = gesture.split("+").pop();
+            return (!(key === "up" || key === "down" || key === "left" || key === "right") &&
+                (key.length > 1 || gesture.includes("+")));
+        });
+        return gestures.length === 0
+            ? "Disabled"
+            : gestures.map(formatGesture).join(" / ");
+    }
+    setStep(next) {
+        if (next === 2 && this.step !== 2)
+            this.pluginEnv.setFields(setupPluginEnvFields(this.plugins.selected));
+        this.step = next;
+        this.invalidate();
+    }
+    moveStep(delta) {
+        this.setStep(((this.step + delta + this.steps.length) % this.steps.length));
+    }
+    /** Enter on a non-final step walks forward; on the last one it finishes. */
+    advance() {
+        if (this.step === this.steps.length - 1)
+            this.finalize();
+        else if (this.step !== 2 || this.pluginEnv.complete)
+            this.moveStep(1);
+    }
+    cancel() {
+        if (this.confirming) {
+            this.confirming = false;
+            this.invalidate();
+            return;
+        }
+        this.onCancel?.();
+    }
+    dispose() {
+        this.providers.dispose();
+    }
+    hasPendingInstalls() {
+        return (this.plugins.selected.some((entry) => !this.installedPackageIds.has(entry.id)) || this.dependencies.selected.length > 0 || this.terminal?.selectedEdit !== undefined);
+    }
+    buildSubmission() {
+        return {
+            packages: [...this.plugins.selected],
+            installedPackageIds: new Set(this.installedPackageIds),
+            systemDeps: [...this.dependencies.selected],
+            pluginEnv: new Map(this.pluginEnv.values),
+            ...(this.terminal?.selectedEdit === undefined ? {} : { terminalEdit: this.terminal.selectedEdit }),
+        };
+    }
+    finalize() {
+        if (this.confirming || !this.hasPendingInstalls()) {
+            this.onSubmit?.(this.buildSubmission());
+            return;
+        }
+        this.confirming = true;
+        this.invalidate();
+    }
+    currentPanel() {
+        return this.step === 0
+            ? this.providers
+            : this.step === 1
+                ? this.plugins
+                : this.step === 2
+                    ? this.pluginEnv
+                    : this.step === 3
+                        ? this.dependencies
+                        : this.terminal;
+    }
+    handleInput(data) {
+        const panel = this.currentPanel();
+        const match = (id, input) => this.matches(id, input);
+        const nestedInput = this.step === 0 && this.providers.isNestedFlowActive();
+        if (nestedInput) {
+            if (panel.handleInput(data, match))
+                this.invalidate();
+            return;
+        }
+        if (this.confirming) {
+            if (this.matches("crtr.setup.confirm.accept", data))
+                this.onSubmit?.(this.buildSubmission());
+            else if (this.matches("crtr.setup.confirm.back", data)) {
+                this.confirming = false;
+                this.invalidate();
+            }
+            return;
+        }
+        if (this.step === 2 && this.pluginEnv.handleInput(data)) {
+            this.invalidate();
+            return;
+        }
+        if (this.matches("crtr.setup.cancel", data)) {
+            this.cancel();
+            return;
+        }
+        if (this.matches("crtr.setup.tab-next", data)) {
+            if (this.step === 2 && !this.pluginEnv.complete)
+                return;
+            this.moveStep(1);
+            return;
+        }
+        if (this.matches("crtr.setup.tab-previous", data)) {
+            this.moveStep(-1);
+            return;
+        }
+        if (panel.handleInput(data, match)) {
+            this.invalidate();
+            return;
+        }
+        if (this.matches("crtr.setup.advance", data))
+            this.advance();
+    }
+    /** `Providers › Plugins › Dependencies`, active step lit, done
+     *  steps checked — a first run should always show how much is left. */
+    renderTrail(width) {
+        const parts = this.steps.map((label, index) => {
+            if (index === this.step)
+                return theme.bg("selectedBg", ` ${index + 1} ${label} `);
+            const mark = index < this.step ? theme.fg("success", "\u2713") : `${index + 1}`;
+            return theme.fg("dim", ` ${mark} ${label} `);
+        });
+        const trail = parts.join(theme.fg("dim", "\u203a"));
+        return visibleWidth(trail) <= width
+            ? [truncateToWidth(trail, width), ""]
+            : [
+                truncateToWidth(`${theme.fg("dim", `Step ${this.step + 1} of ${this.steps.length}`)}  ${theme.fg("accent", theme.bold(this.steps[this.step]))}`, width),
+                "",
+            ];
+    }
+    footer(width) {
+        const steps = `${this.fieldSafeLabel("crtr.setup.tab-next")}/${this.fieldSafeLabel("crtr.setup.tab-previous")} step \u00b7 ${this.label("crtr.setup.cancel")} cancel`;
+        const move = formatMovePair(this.bindings, "crtr.setup.list-down", "crtr.setup.list-up");
+        const advance = this.label("crtr.setup.advance");
+        let left;
+        // Narrow-terminal fallback for the left hint, so the step keys on the right
+        // never get dropped — they are the only visible way between steps.
+        let compact;
+        if (this.confirming)
+            left = `${this.label("crtr.setup.confirm.accept")} confirm \u00b7 ${this.label("crtr.setup.confirm.back")} go back`;
+        else if (this.step === 0) {
+            const enter = this.providers.isAddRowSelected() ? `${advance} add provider` : `${advance} next`;
+            left = this.providers.isNestedFlowActive()
+                ? "OAuth in progress \u00b7 esc cancel"
+                : `${move} select \u00b7 ${enter} \u00b7 a add \u00b7 p prefer \u00b7 r rename \u00b7 l re-login \u00b7 x remove`;
+            if (!this.providers.isNestedFlowActive())
+                compact = `${move} select \u00b7 ${enter} \u00b7 a add \u00b7 l re-login`;
+        }
+        else if (this.step === 1)
+            left = `${move} move \u00b7 ${this.label("crtr.setup.toggle")} toggle \u00b7 ${this.label("crtr.setup.details")} details \u00b7 ${this.label("crtr.setup.advance")} next`;
+        else if (this.step === 2)
+            left = `type value \u00b7 Enter save/skip \u00b7 ${this.pluginEnv.complete ? `${this.label("crtr.setup.advance")} next` : 'complete keys to continue'}`;
+        else if (this.step === 3)
+            left = `${move} move \u00b7 ${this.label("crtr.setup.toggle")} toggle \u00b7 ${this.label("crtr.setup.advance")} ${this.steps.length > 4 ? "next" : "finish"}`;
+        else
+            left = `${this.terminal?.canApply ? `${this.label("crtr.setup.toggle")} apply for me \u00b7 ` : ""}${this.label("crtr.setup.advance")} finish`;
+        for (const candidate of compact === undefined ? [left] : [left, compact]) {
+            const gap = width - visibleWidth(candidate) - visibleWidth(steps);
+            if (gap >= 2)
+                return `${theme.fg("dim", candidate)}${" ".repeat(gap)}${theme.fg("dim", steps)}`;
+        }
+        return theme.fg("dim", compact ?? left);
+    }
+    renderConfirm(width) {
+        const submission = this.buildSubmission();
+        const out = [
+            truncateToWidth(theme.fg("warning", theme.bold("Confirm installs")), width),
+            "",
+        ];
+        if (submission.packages.length === 0 && submission.systemDeps.length === 0 && submission.terminalEdit === undefined)
+            return [
+                ...out,
+                truncateToWidth(theme.fg("success", `Nothing to install; ${this.label("crtr.setup.confirm.accept")} finish.`), width),
+            ];
+        if (submission.packages.length) {
+            out.push(truncateToWidth(theme.fg("accent", "Packages"), width));
+            for (const entry of submission.packages)
+                out.push(truncateToWidth(`  \u2022 ${entry.name} ${theme.fg("dim", "\u2192")} ${this.installedPackageIds.has(entry.id) ? theme.fg("success", "skip (already installed)") : theme.fg("muted", packagePlanAction(entry))}`, width));
+        }
+        if (submission.systemDeps.length) {
+            out.push(truncateToWidth(theme.fg("accent", "System deps"), width));
+            for (const plan of submission.systemDeps)
+                out.push(truncateToWidth(`  \u2022 ${plan.tool} ${theme.fg("dim", "\u2192")} ${theme.fg("muted", plan.command ?? plan.hint)}`, width));
+        }
+        if (submission.terminalEdit !== undefined) {
+            out.push(truncateToWidth(theme.fg("accent", "Terminal config"), width));
+            for (const line of describeEdit(submission.terminalEdit))
+                out.push(truncateToWidth(theme.fg("muted", `  ${line}`), width));
+        }
+        return out;
+    }
+    render(width) {
+        const bypass = this.step === 0;
+        const height = this.terminalRows();
+        if (!bypass &&
+            this.cachedLines &&
+            this.cachedWidth === width &&
+            this.cachedHeight === height)
+            return this.cachedLines;
+        const panel = this.currentPanel();
+        // On a terminal too short for both, the step content wins over the trail:
+        // a frame that shows only "which step" and none of the step is useless.
+        const budget = Math.max(1, height - PAGE_CHROME_ROWS);
+        const trail = this.confirming || budget <= 2 ? [] : this.renderTrail(width);
+        const bodyHeight = Math.max(1, budget - trail.length);
+        const lines = pageFrame({
+            width,
+            height,
+            title: "crouter setup",
+            meta: this.confirming
+                ? "review"
+                : `step ${this.step + 1} of ${this.steps.length}`,
+            body: [
+                ...trail,
+                ...(this.confirming
+                    ? this.renderConfirm(width)
+                    : panel.render(width, bodyHeight)),
+            ],
+            footer: this.footer(width),
+        });
+        if (!bypass) {
+            this.cachedWidth = width;
+            this.cachedHeight = height;
+            this.cachedLines = lines;
+        }
+        return lines;
+    }
+}
+/** The wizard renders inline on the main screen, so stopping its TUI leaves the
+ *  last frame — confirm page, footer — sitting above whatever prints next. Wipe
+ *  the screen and home the cursor so the install lines, the summary and the
+ *  front door's profile picker start at the top of a blank page. Cancel and
+ *  interrupt come back through the same await, so they clear too. */
+function clearWizardFrame() {
+    process.stdout.write('\u001b[2J\u001b[H');
+}
+export async function runSetup() {
+    const state = buildSetupInitialState();
+    let interrupted = false;
+    await reconcileInboxFrontDoor();
+    if (!process.stdout.isTTY) {
+        process.stdout.write(renderSetupStaticInstructions(state));
+        return 'skipped';
+    }
+    const existingEnvNames = new Set((await cliClient().listAppEnv()).names);
+    const submission = await runSetupSettingsProcess(({ tui, terminal, agentDir, runtime, registry, bindings }, control) => {
+        const wizard = new SetupWizard(state.manifest, state.installedPackageIds, state.systemPlans, tui, agentDir, runtime, registry, bindings, () => terminal.rows, existingEnvNames, planOptionAsAlt({ env: process.env, platform: process.platform, home: homedir() }));
+        wizard.onCancel = control.cancel;
+        wizard.onSubmit = control.submit;
+        return wizard;
+    }, (data, bindings) => {
+        if (data === "\u0003") {
+            interrupted = true;
+            return true;
+        }
+        return (data.length > 0 &&
+            data.charCodeAt(0) < 32 &&
+            matchesPiTuiInput(bindings, "crtr.setup.cancel", data, (input, gesture) => matchesKey(input, gesture)));
+    });
+    clearWizardFrame();
+    if (interrupted) {
+        const error = new Error('Interrupted');
+        error.name = 'AbortError';
+        throw error;
+    }
+    if (submission === undefined)
+        return 'skipped';
+    for (const [name, value] of submission.pluginEnv)
+        await cliClient().setAppEnv(name, value);
+    const summary = await executeSetupSubmission(submission);
+    process.stdout.write(formatSetupExecutionSummary(summary));
+    return 'completed';
+}

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,41 @@
+// 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: 'bootstrap a fresh machine — provider login, companion packages, system dependencies',
+    whenToUse: 'you need to re-run the first-launch installer — sign in to another provider, add companion packages or system dependencies, or repair package paths. A person never needs it to get started: the first bare `crtr` in a terminal opens this installer itself. Use sys settings to change configuration on an installed machine, and sys config set for scriptable edits.',
+    help: {
+        name: 'sys setup',
+        summary: 'reopen the installer bare `crtr` runs on first launch: provider login, companion packages, system dependencies',
+        inputNote: 'No input parameters.',
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Opens a three-step pi-tui installer. Step one 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.',
+            'The remaining steps collect companion package installs and system dependency installs, then confirm them all at once.',
+            'On macOS, a final step detects the terminal and explains how to make Option act as Alt (crouter\'s menu is Alt+C). Where the setting is safely scriptable (Ghostty, stock VS Code) it can write the one line for you, but only if you tick it and after showing exactly what will be written.',
+            'Runs the bundled pi CLI to install the selected companion packages and prints a summary.',
+            'The companion-package list includes the official crtr marketplace and the plugins installed from it (currently `capture` and `exa-search`), all checked by default and registered or installed into the user scope when left checked. Nothing else registers a marketplace, so an install that never runs setup fetches no catalog. An unreachable marketplace is reported as skipped rather than failing setup. Vendor credentials belong to the plugin that needs them, never to setup.',
+            'In a terminal, records setup as done (the same record the first bare `crtr` writes), so the next bare `crtr` boots a conversation instead of reopening the installer, and offers the tutorial if no conversation has started since setup first ran.',
+            '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 () => {
+        const outcome = await (await import('./setup-wizard.js')).runSetup();
+        // A TTY run counts as first-run setup, so the next bare `crtr` boots straight
+        // to a root instead of opening the wizard again.
+        if (process.stdout.isTTY) {
+            await (await import('../../core/runtime/setup-marker.js')).recordSetupCompleted(outcome);
+        }
+    },
+    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/signin.d.ts

@@ -0,0 +1,7 @@
+import { type SignInPrompt } from '../../core/directory/person-credential.js';
+/** Print the pairing code and open the confirm page: what the person sees while `signIn` polls. */
+export declare function showSignIn(prompt: SignInPrompt & {
+    complete: string;
+}): void;
+export declare const sysSigninLeaf: import("../../core/command.js").LeafDef;
+export declare const sysSignoutLeaf: import("../../core/command.js").LeafDef;