peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/vm-spawn-command.js

@@ -0,0 +1,177 @@
+// src/cli/commands/vm-spawn-command.ts
+//
+// `peaks vm spawn` — pick a hypervisor, probe it, spawn the VM and write the
+// lease. Split out of `vm-commands.ts`; every refusal code, message, `data`
+// field, next-action string and exit code is unchanged.
+import { existsSync } from 'node:fs';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { DEFAULT_VM_IMAGE, finalizeVmLease, generateVmLeaseId, vmLeaseFilePath } from '../../services/vm/vm-lease.js';
+import { detectHypervisor } from './vm-hypervisor-probe.js';
+import { spawnVmWithHypervisor } from './vm-hypervisor-runtime.js';
+import { joinPathSession, resolveTtlMs, resolveVmSessionId } from './vm-command-shared.js';
+/** Explicit `--hypervisor` wins; otherwise only `/dev/kvm` auto-detects. */
+function pickHypervisor(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    // No platform detector for hyperkit / hyperv — those require --hypervisor.
+    if (existsSync('/dev/kvm'))
+        return 'kvm';
+    return null;
+}
+function buildSpawnContext(options, projectRoot, sessionId, hypervisor) {
+    return {
+        projectRoot,
+        sessionId,
+        hypervisor,
+        image: options.image ?? DEFAULT_VM_IMAGE,
+        mount: options.mount ?? projectRoot,
+        ttlMs: resolveTtlMs(options.ttl, options.role),
+        leaseId: generateVmLeaseId(),
+        now: Date.now()
+    };
+}
+function emitSpawnRefusal(io, options, refusal) {
+    printResult(io, fail('vm.spawn', refusal.code, refusal.message, refusal.data, refusal.nextActions), options.json ?? false);
+    process.exitCode = 1;
+}
+function emitHypervisorUnspecified(io, options, sessionId) {
+    emitSpawnRefusal(io, options, {
+        code: 'VM_HYPERVISOR_UNSPECIFIED',
+        message: 'No --hypervisor given and the host does not advertise /dev/kvm. Pass --hypervisor hyperkit|hyperv to force one.',
+        data: { rid: options.rid, sessionId },
+        nextActions: [
+            'Linux KVM: ensure /dev/kvm exists and the kvm kernel module is loaded.',
+            'macOS HyperKit: install hvftool (brew install hyperkit) and pass --hypervisor hyperkit.',
+            'Windows Hyper-V: install the hvc shim and pass --hypervisor hyperv.'
+        ]
+    });
+}
+function emitRuntimeUnavailable(io, options, detail) {
+    emitSpawnRefusal(io, options, {
+        code: 'VM_RUNTIME_UNAVAILABLE',
+        message: `${detail.hypervisor} runtime not available: ${detail.stderr}`,
+        data: { rid: options.rid, hypervisor: detail.hypervisor, sessionId: detail.sessionId },
+        nextActions: [
+            `Install the ${detail.hypervisor} runtime binary on PATH.`,
+            'The dispatch fail-fast prevents fallback to a different hypervisor (caller chose this mode for a reason).'
+        ]
+    });
+}
+/** Spawn, or print the spawn failure and return null. */
+function spawnOrFail(io, options, ctx) {
+    try {
+        return spawnVmWithHypervisor({
+            hypervisor: ctx.hypervisor,
+            image: ctx.image,
+            mount: ctx.mount,
+            leaseId: ctx.leaseId,
+            rid: options.rid,
+            workdir: ctx.projectRoot
+        }).vmId;
+    }
+    catch (err) {
+        emitSpawnRefusal(io, options, {
+            code: 'VM_SPAWN_FAILED',
+            message: getErrorMessage(err),
+            data: {
+                rid: options.rid,
+                hypervisor: ctx.hypervisor,
+                image: ctx.image,
+                sessionId: ctx.sessionId
+            },
+            nextActions: [
+                'Verify the image / vhdx is reachable on the host.',
+                `For ${ctx.hypervisor}: the spawn helper expects domain XML / hvftool args / hvc shim.`
+            ]
+        });
+        return null;
+    }
+}
+function emitSpawnSuccess(io, options, spawned) {
+    const { ctx, vmId, binary } = spawned;
+    const lease = finalizeVmLease({
+        leaseId: ctx.leaseId,
+        rid: options.rid,
+        role: options.role,
+        path: ctx.mount,
+        hypervisor: ctx.hypervisor,
+        image: ctx.image,
+        vmId,
+        createdAt: ctx.now,
+        expiresAt: ctx.now + ctx.ttlMs,
+        purpose: options.purpose
+    });
+    atomicWriteJson(vmLeaseFilePath(joinPathSession(ctx.projectRoot, ctx.sessionId), ctx.leaseId), lease);
+    printResult(io, ok('vm.spawn', {
+        lease,
+        sessionId: ctx.sessionId,
+        projectRoot: ctx.projectRoot,
+        hypervisor: ctx.hypervisor,
+        runtime: binary,
+        ttlMs: ctx.ttlMs,
+        nextActions: [
+            `VM domain id: ${vmId}`,
+            `Image: ${ctx.image}`,
+            `Lease expires at: ${new Date(lease.expiresAt).toISOString()}`,
+            'Run `peaks vm release --lease-id <lease-id>` when done',
+            'For inside-the-VM exec, a follow-up rid adds `peaks vm exec` (Part 35 ships lease + spawn/release only).'
+        ]
+    }, [], []), options.json ?? false);
+}
+export function runVmSpawn(io, options) {
+    try {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = resolveVmSessionId(projectRoot, options.session);
+        const detected = pickHypervisor(options.hypervisor);
+        if (detected === null) {
+            emitHypervisorUnspecified(io, options, sessionId);
+            return;
+        }
+        const probe = detectHypervisor(detected);
+        if (!probe.ok) {
+            emitRuntimeUnavailable(io, options, {
+                sessionId,
+                hypervisor: detected,
+                stderr: probe.stderr
+            });
+            return;
+        }
+        const ctx = buildSpawnContext(options, projectRoot, sessionId, detected);
+        const vmId = spawnOrFail(io, options, ctx);
+        if (vmId === null)
+            return;
+        emitSpawnSuccess(io, options, { ctx, vmId, binary: probe.binary });
+    }
+    catch (err) {
+        emitSpawnRefusal(io, options, {
+            code: 'SPAWN_FAILED',
+            message: getErrorMessage(err),
+            data: {
+                rid: options.rid,
+                sessionId: options.session ?? process.env.PEAKS_SESSION_ID ?? 'unknown-sid'
+            },
+            nextActions: [
+                'See error message; if the lease was not written, retry after fixing the underlying issue.'
+            ]
+        });
+    }
+}
+export function registerVmSpawnCommand(cmd, io) {
+    addJsonOption(cmd
+        .command('spawn')
+        .description('Spawn a VM via the requested hypervisor (kvm | hyperkit | hyperv) and write a VM lease. ' +
+        'Default TTL is role-aware (rd=30m / qa=15m / ui=1h); pass --ttl <ms> to override. ' +
+        'Default image is `peaks-base:22-slim`; pass --image <name> to override.')
+        .requiredOption('--rid <rid>', 'peaks request id the lease is associated with')
+        .requiredOption('--role <role>', 'sub-agent role (rd | qa | ui | sc | prd | general-purpose)')
+        .requiredOption('--purpose <text>', 'why this VM was spawned (audit log)')
+        .option('--hypervisor <name>', 'hypervisor to use: kvm | hyperkit | hyperv (default: auto-detect from host)')
+        .option('--image <name>', `container image / vhdx to boot (default ${DEFAULT_VM_IMAGE})`)
+        .option('--ttl <ms>', 'time-to-live in ms (default role-aware; override with positive number)')
+        .option('--mount <path>', 'host path to mount as the VM working dir (default: <projectRoot>)')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runVmSpawn(io, options));
+}

package/dist/cli/commands/web-command-shared.d.ts

@@ -0,0 +1,12 @@
+import { fail } from 'peaks-loop-shared/result';
+/** A daemon-supplied value that is expected to be a string, or `''`. */
+export declare function text(value: unknown): string;
+/** A daemon-supplied value that is expected to be a count, or `0`. */
+export declare function count(value: unknown): number;
+/** Resolve this project's session, or report `NO_SESSION` exactly once. */
+export declare function resolveSession(): {
+    projectRoot: string;
+    sessionId: string;
+} | null;
+/** The shared `NO_SESSION` envelope for both lifecycle verbs. */
+export declare function noSession(command: string): ReturnType<typeof fail>;

package/dist/cli/commands/web-command-shared.js

@@ -0,0 +1,30 @@
+// src/cli/commands/web-command-shared.ts
+//
+// What every `peaks web …` verb shares: the session binding lookup, the
+// `NO_SESSION` refusal, and the two readers that coerce a daemon-supplied value
+// to the shape the envelope promises. The first two were split out of
+// `web-lifecycle-commands.ts`; `text` / `count` came with the `web-commands.ts`
+// split, where they had a copy each in the payload and failure modules.
+import { fail } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+/** A daemon-supplied value that is expected to be a string, or `''`. */
+export function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+/** A daemon-supplied value that is expected to be a count, or `0`. */
+export function count(value) {
+    return typeof value === 'number' ? value : 0;
+}
+/** Resolve this project's session, or report `NO_SESSION` exactly once. */
+export function resolveSession() {
+    const projectRoot = resolveCanonicalProjectRoot(process.cwd());
+    const sessionId = getCurrentSessionId(projectRoot);
+    return sessionId === null ? null : { projectRoot, sessionId };
+}
+/** The shared `NO_SESSION` envelope for both lifecycle verbs. */
+export function noSession(command) {
+    return fail(command, 'NO_SESSION', 'No peaks session is bound to this project root', {}, [
+        'Bind a session first (the LLM runs `peaks workspace init` on your behalf)'
+    ]);
+}

package/dist/cli/commands/web-commands.d.ts

@@ -8,21 +8,14 @@
  * The envelope is built once, in `runWebOp`, and that is also the single place
  * `WRAPPED_OPS` is applied — one place, not six. Every page- or daemon-derived
  * string that leaves this process (payload, diagnostic, warning) is capped and
- * wrapped here, because this is the boundary the model actually reads.
+ * wrapped there, because this is the boundary the model actually reads.
+ *
+ * The pieces live beside this file: the verb table in `web-verb-specs.ts`, the
+ * op's envelope in `web-op-runner.ts`, its payload shaping in
+ * `web-op-payload.ts`, its refusal texts in `web-op-refusals.ts`, and the
+ * daemon-lifecycle verbs in `web-lifecycle-commands.ts`.
  */
 import type { Command } from 'commander';
-import type { WebOp } from '../../services/web/web-protocol.js';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerWebCommands(program: Command, io: ProgramIO): void;
-/**
- * Resolve the session, ensure a daemon, invoke one op, and emit exactly one
- * envelope. `WRAPPED_OPS` is applied here, after the byte caps the daemon
- * already imposed, so the UNTRUSTED markers are never themselves truncated.
- *
- * The `PEAKS_WEB_DISABLED` gate is the FIRST thing that happens (tech-doc §5.1
- * step 1, AC5). Before the session lookup, so a project with no binding still
- * gets `WEB_DISABLED` rather than `NO_SESSION`; before `ensureDaemon`, so
- * nothing is spawned and no lock is taken; and therefore before anything that
- * could touch the browser cache.
- */
-export declare function runWebOp(io: ProgramIO, op: WebOp, args: Record<string, unknown>, asJson: boolean): Promise<void>;
+export { runWebOp } from './web-op-runner.js';

package/dist/cli/commands/web-commands.js

@@ -1,73 +1,7 @@
-import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
-import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
-import { capText, MAX_TEXT_BYTES } from '../../services/web/bounded-output.js';
-import { ensureDaemon } from '../../services/web/daemon-supervisor.js';
-import { wrapUntrusted, WRAPPED_OPS } from '../../services/web/untrusted-envelope.js';
-import { WebDaemonClient } from '../../services/web/web-client.js';
-import { degradedEnvelope } from '../../services/web/web-fallback.js';
-import { isWebDisabled } from '../../services/web/web-install-service.js';
-import { cappedEcho, resolveProfileName } from '../../services/web/web-login-profile.js';
-import { addJsonOption, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { addJsonOption } from '../cli-helpers.js';
 import { registerWebLifecycleCommands } from './web-lifecycle-commands.js';
-/** A browser op is user-visible latency; 30 s is generous but bounded. */
-const OP_TIMEOUT_MS = 30_000;
-/**
- * The option text names the read-only half out loud: a caller who browses with a
- * profile must not assume the profile was refreshed by it.
- */
-const PROFILE_OPTION_DESCRIPTION = 'navigate with a saved login profile (`peaks web login --profile <name>`): [a-z0-9._-], ' +
-    '1-64 chars, upper case folds to lower. The profile is READ-ONLY here — this run loads it ' +
-    'and never writes it back, so browser activity is not saved into it.';
-const WEB_VERBS = [
-    {
-        name: 'open',
-        op: 'open',
-        description: 'Navigate the dispatch browser context to <url>. With --profile, the page loads that ' +
-            'saved login.',
-        argument: { name: '<url>', description: 'absolute URL to load' },
-        takesProfile: true,
-        toArgs: (positional, profile) => ({
-            url: positional[0] ?? '',
-            ...(profile === undefined ? {} : { profile })
-        })
-    },
-    {
-        name: 'text',
-        op: 'text',
-        description: 'Return the visible text of the page (or of [selector]), byte-capped.',
-        argument: { name: '[selector]', description: 'CSS selector (default: body)' },
-        toArgs: (positional) => ({ selector: positional[0] })
-    },
-    {
-        name: 'snap',
-        op: 'snap',
-        description: 'Return a pruned ARIA snapshot of the page (or of [selector]), byte-capped.',
-        argument: { name: '[selector]', description: 'CSS selector (default: body)' },
-        toArgs: (positional) => ({ selector: positional[0] })
-    },
-    {
-        name: 'click',
-        op: 'click',
-        description: 'Click the element matching <selector> in the dispatch browser context.',
-        argument: { name: '<selector>', description: 'CSS selector to click' },
-        toArgs: (positional) => ({ selector: positional[0] ?? '' })
-    },
-    {
-        name: 'shot',
-        op: 'shot',
-        description: 'Screenshot the page (or [selector]) into the session web/ directory.',
-        argument: { name: '[selector]', description: 'CSS selector (default: full page)' },
-        toArgs: (positional) => ({ selector: positional[0] })
-    },
-    {
-        name: 'metrics',
-        op: 'metrics',
-        description: 'Return Core Web Vitals for the dispatch page, or why they are unavailable.',
-        argument: null,
-        toArgs: () => ({})
-    }
-];
+import { runWebOp } from './web-op-runner.js';
+import { PROFILE_OPTION_DESCRIPTION, WEB_VERBS } from './web-verb-specs.js';
 export function registerWebCommands(program, io) {
     const web = program
         .command('web')
@@ -97,248 +31,6 @@ export function registerWebCommands(program, io) {
     }
     registerWebLifecycleCommands(web, io);
 }
-/**
- * Resolve the session, ensure a daemon, invoke one op, and emit exactly one
- * envelope. `WRAPPED_OPS` is applied here, after the byte caps the daemon
- * already imposed, so the UNTRUSTED markers are never themselves truncated.
- *
- * The `PEAKS_WEB_DISABLED` gate is the FIRST thing that happens (tech-doc §5.1
- * step 1, AC5). Before the session lookup, so a project with no binding still
- * gets `WEB_DISABLED` rather than `NO_SESSION`; before `ensureDaemon`, so
- * nothing is spawned and no lock is taken; and therefore before anything that
- * could touch the browser cache.
- */
-export async function runWebOp(io, op, args, asJson) {
-    const command = `peaks.web.${op}`;
-    // Declared outside the try so the CATCH reports the fold too (S4's F5/S5 rule
-    // for `login`, applied here): a run that dies after the name was resolved
-    // knows the canonical name just as well as a successful one.
-    let foldWarnings = [];
-    try {
-        if (isWebDisabled(process.env)) {
-            // The gate is statement #1, so a `--profile` has NOT been through the
-            // resolver yet and is still unbounded caller text. `degradedEnvelope`
-            // carries every string arg into the payload, so it is capped here — the
-            // same cap the `login` gate applies, for the same reason (S1's bounded
-            // output is a property of the envelope, not only of stdout).
-            const gateArgs = typeof args['profile'] === 'string'
-                ? { ...args, profile: cappedEcho(args['profile']) }
-                : args;
-            printResult(io, degradedEnvelope(op, 'PEAKS_WEB_DISABLED=1', 3, gateArgs), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        // A caller-supplied `--profile` is validated HERE, before anything is sent,
-        // and the daemon runs the SAME resolver again on the payload it receives (a
-        // value off the wire is not trusted). `resolveProfileName` folds to lower
-        // case, so the canonical name is what travels, and the fold is reported
-        // rather than silent — the contract `login` honours.
-        let profile;
-        if (typeof args['profile'] === 'string') {
-            const typed = args['profile'];
-            try {
-                profile = resolveProfileName(typed);
-            }
-            catch (error) {
-                printResult(io, fail(command, 'WEB_PROFILE_NAME_INVALID', profileRefusal(error), {}, PROFILE_NEXT_ACTIONS), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            if (profile !== typed) {
-                foldWarnings = [
-                    `--profile ${JSON.stringify(cappedEcho(typed))} resolved to the profile "${profile}"`
-                ];
-            }
-        }
-        const opArgs = profile === undefined ? args : { ...args, profile };
-        const projectRoot = resolveCanonicalProjectRoot(process.cwd());
-        const sessionId = getCurrentSessionId(projectRoot);
-        if (sessionId === null) {
-            printResult(io, withFold(fail(command, 'NO_SESSION', 'No peaks session is bound to this project root', {}, [
-                'Bind a session first (the LLM runs `peaks workspace init` on your behalf)'
-            ]), foldWarnings), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        const info = await ensureDaemon(projectRoot, sessionId);
-        // The daemon reads `projectRoot` back from `daemon.json` — the record it
-        // itself wrote — and that round-trip is the only path that survives the
-        // macOS `/var` <-> `/private/var` symlink: the writer's prefix may not
-        // match `projectRoot` resolved from `process.cwd()` (the kernel resolves
-        // symlinks on `chdir`), and the integration test asserts on that exact
-        // round-tripped value.
-        const daemonProjectRoot = info.projectRoot;
-        const response = await new WebDaemonClient(info).call(op, { ...opArgs, dispatchId: dispatchId(), projectRoot: daemonProjectRoot, sessionId }, OP_TIMEOUT_MS);
-        if (!response.ok || response.data === null) {
-            const code = safeDaemonCode(response.code);
-            // The daemon no longer downloads (R3), so "the browser is not installed"
-            // arrives as a refusal. It is AC5's tier-3 branch, not an opaque op
-            // failure: the caller must be handed the same envelope — MCP tool,
-            // install command, screenshot consequence — that the gate produces.
-            printResult(io, code === 'WEB_INSTALL_REQUIRED'
-                ? withFold(degradedEnvelope(op, `WEB_INSTALL_REQUIRED: ${response.message ?? ''}`, 3, opArgs), foldWarnings)
-                : withFold(fail(command, code, failureMessage(op, response.message, response.nextActions), {}, []), foldWarnings), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        const wrapped = wrapPageData(op, response.data);
-        emit(io, ok(command, wrapped.data, [...foldWarnings, ...wrapDiagnostics(response.warnings)]), asJson, wrapped.human);
-    }
-    catch (error) {
-        printResult(io, withFold(fail(command, 'WEB_OP_FAILED', failureMessage(op, redactSensitiveErrorMessage(getErrorMessage(error)), []), {}, []), foldWarnings), asJson);
-        process.exitCode = 1;
-    }
-}
-/**
- * What a caller can do after a refused `--profile` — the same sentence `login`
- * gives, because it is the same mistake and the same verb fixes it.
- */
-const PROFILE_NEXT_ACTIONS = [
-    'Re-run with a name matching [a-z0-9._-], 1-64 chars',
-    'Or run `peaks web login --profile <name>` to create that profile'
-];
-/**
- * The resolver's own message begins with the code, and `fail()` puts the code in
- * front of the message again — strip it, so human output does not read
- * `WEB_PROFILE_NAME_INVALID: WEB_PROFILE_NAME_INVALID: …` (the `login` verb does
- * the same).
- */
-function profileRefusal(error) {
-    return getErrorMessage(error).replace(/^WEB_PROFILE_NAME_INVALID:\s*/, '');
-}
-/** Prepend the fold notice to an envelope's warnings; never rewrite them away. */
-function withFold(envelope, warnings) {
-    return warnings.length === 0
-        ? envelope
-        : { ...envelope, warnings: [...warnings, ...envelope.warnings] };
-}
-/**
- * A daemon- or page-derived diagnostic is DATA, never an instruction: it is
- * byte-capped and wrapped before it can reach `message` or `warnings` (AC4 /
- * R4 — the envelope must cover the diagnostic channel, not only `data`).
- *
- * This matters because Playwright's own error messages embed the matched
- * elements' HTML, so a page with two elements matching a selector can put
- * arbitrary text on a channel the CLI would otherwise print verbatim to stdout.
- */
-function wrapDiagnostic(raw) {
-    const capped = capText(text(raw), MAX_TEXT_BYTES).text;
-    return capped === '' ? '' : wrapUntrusted(capped);
-}
-/** Every daemon warning, capped and wrapped. Empty entries are dropped. */
-function wrapDiagnostics(values) {
-    return values.map((value) => wrapDiagnostic(value)).filter((value) => value !== '');
-}
-/**
- * Our own static sentence, then the daemon's own words as a wrapped, capped
- * block. The daemon's `nextActions` are folded into that block rather than
- * forwarded: `printResult` prints `nextActions` to STDOUT as `next: …`, the
- * channel the notice calls instruction, and the daemon's text is not ours to
- * promote there.
- */
-function failureMessage(op, message, nextActions) {
-    const detail = [text(message), ...nextActions.map((action) => text(action))]
-        .filter((line) => line !== '')
-        .join('\n');
-    const wrapped = wrapDiagnostic(detail);
-    return wrapped === ''
-        ? `peaks web ${op} failed in the daemon`
-        : `peaks web ${op} failed in the daemon\n${wrapped}`;
-}
-/**
- * A daemon-supplied `code` is printed on the envelope's first line, so only a
- * protocol-shaped identifier is accepted; anything else falls back to ours.
- */
-function safeDaemonCode(value) {
-    return typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(value)
-        ? value
-        : 'WEB_OP_FAILED';
-}
-/**
- * Wrap the page-controlled part of each verb's payload (AC4 / §6.2) and pick
- * the bytes that human mode prints verbatim. `shot` is unwrapped: its path and
- * byte count are ours, not the page's.
- */
-function wrapPageData(op, raw) {
-    if (!WRAPPED_OPS.has(op)) {
-        return { data: raw, human: null };
-    }
-    switch (op) {
-        case 'open': {
-            const title = wrapUntrusted(text(raw['title']));
-            return { data: { url: wrapUntrusted(text(raw['url'])), title }, human: title };
-        }
-        case 'text': {
-            const value = wrapUntrusted(text(raw['text']));
-            return {
-                data: {
-                    text: value,
-                    truncated: raw['truncated'] === true,
-                    droppedBytes: count(raw['droppedBytes'])
-                },
-                human: value
-            };
-        }
-        case 'snap': {
-            const snapshot = wrapUntrusted(text(raw['snapshot']));
-            return {
-                data: {
-                    snapshot,
-                    droppedNodes: count(raw['droppedNodes']),
-                    depthCapped: raw['depthCapped'] === true,
-                    nodeCapped: raw['nodeCapped'] === true,
-                    truncated: raw['truncated'] === true,
-                    droppedBytes: count(raw['droppedBytes'])
-                },
-                human: snapshot
-            };
-        }
-        case 'click': {
-            const result = wrapUntrusted(text(raw['result']));
-            return { data: { result }, human: result };
-        }
-        case 'metrics': {
-            // The rendered lines come from the daemon's payload, so they are capped
-            // here as well as at the producer: this is the boundary that reaches
-            // stdout, and the ceiling must hold whatever the daemon sends.
-            const metrics = wrapUntrusted(capText(renderMetrics(raw), MAX_TEXT_BYTES).text);
-            return { data: { metrics }, human: metrics };
-        }
-        default:
-            return { data: raw, human: null };
-    }
-}
-/**
- * Print the envelope. Failures and `--json` go through `printResult`; a
- * successful wrapped op in human mode prints its payload RAW, because the
- * UNTRUSTED delimiters must stay on their own lines (AC4) and AC2 measures the
- * byte count of exactly this stdout.
- */
-function emit(io, result, asJson, humanPayload) {
-    if (!result.ok || asJson || humanPayload === null) {
-        printResult(io, result, asJson);
-        return;
-    }
-    io.stdout(humanPayload);
-    for (const warning of result.warnings) {
-        io.stderr(`warning: ${warning}`);
-    }
-}
-/** `available: false` is reported as such — never as fabricated zeros (C4). */
-function renderMetrics(raw) {
-    if (raw['available'] !== true) {
-        return `available: false\nreason: ${text(raw['reason']) || 'unavailable'}`;
-    }
-    const values = (raw['values'] ?? {});
-    const lines = Object.entries(values).map(([key, value]) => `${key}: ${String(value)}`);
-    return lines.length > 0 ? lines.join('\n') : 'available: true';
-}
-function dispatchId() {
-    return process.env['PEAKS_DISPATCH_ID'] ?? 'current';
-}
-function text(value) {
-    return typeof value === 'string' ? value : '';
-}
-function count(value) {
-    return typeof value === 'number' ? value : 0;
-}
+// Re-export for tests / external consumers; the implementation moved to
+// `web-op-runner.ts` with the split.
+export { runWebOp } from './web-op-runner.js';

package/dist/cli/commands/web-install-command.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * `peaks web install` — the explicit form of the lazy download, plus R6's
+ * recovery path (`--force`).
+ *
+ * The gate is step 1 of the ordered gate (tech-doc §5.1) — see {@link installRefusal}.
+ */
+export declare function runWebInstall(io: ProgramIO, asJson: boolean, force: boolean): Promise<void>;
+export declare function registerWebInstallCommand(web: Command, io: ProgramIO): void;