@richhardry/codor 0.10.0

package/node_modules/@codor/cli/dist/setup.js

@@ -0,0 +1,878 @@
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir, release } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { CryptoVault, pairingUrl } from '@codor/switchboard';
+import { packageRuntimePaths, resolveRuntimePaths } from './runtime-paths.js';
+import { defaultInstallIo, detectInstalledRuntime, durableRuntimeLocation, installDurableRuntime, installedCliRoot, resolveInstallSource, } from './runtime-install.js';
+import { SetupSession, isInteractiveSetup, } from './setup-session.js';
+import { SETUP_STAGE_TITLES, renderPairingCard } from './setup-ui.js';
+import { renderTerminalQr } from './terminal-qr.js';
+const HARNESSES = ['claude', 'codex', 'opencode', 'gemini', 'copilot', 'cursor-agent', 'agy'];
+const LAUNCH_AGENT_LABEL = 'app.codor.switchboard';
+const defaultExec = (command, args) => execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+}).trim();
+const defaultWhich = (command) => {
+    try {
+        const locator = process.platform === 'win32' ? 'where.exe' : 'which';
+        return defaultExec(locator, [command]).split(/\r?\n/)[0]?.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+function uniquePath(parts, delimiter = ':') {
+    return [...new Set(parts.flatMap((part) => part?.split(delimiter) ?? []).filter(Boolean))]
+        .join(delimiter);
+}
+// harn:assume wsl-setup-keeps-private-windows-loopback ref=wsl-bind-selection
+function wslSystemdBindHost(env, kernelRelease, exec, which) {
+    const isWsl = Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP || /microsoft/i.test(kernelRelease));
+    if (!isWsl)
+        return '127.0.0.1';
+    if (!/wsl2/i.test(kernelRelease))
+        return '127.0.0.1';
+    let networkingMode;
+    const wslinfo = which('wslinfo');
+    if (wslinfo) {
+        try {
+            networkingMode = exec('wslinfo', ['--networking-mode']).trim().toLowerCase() || undefined;
+        }
+        catch {
+            // A present-but-broken probe cannot safely distinguish NAT from mirrored networking.
+            return '127.0.0.1';
+        }
+    }
+    if ((wslinfo === undefined && networkingMode === undefined)
+        || networkingMode === 'nat'
+        || networkingMode === 'virtioproxy') {
+        return '0.0.0.0';
+    }
+    return '127.0.0.1';
+}
+// harn:end wsl-setup-keeps-private-windows-loopback
+function systemdQuote(value) {
+    if (/[\0\r\n]/.test(value))
+        throw new Error('codor setup paths cannot contain control characters');
+    return `"${value
+        .replaceAll('\\', '\\\\')
+        .replaceAll('"', '\\"')
+        .replaceAll('%', '%%')}"`;
+}
+function systemdPath(value) {
+    if (/[\0\r\n]/.test(value))
+        throw new Error('codor setup paths cannot contain control characters');
+    return value.replaceAll('%', '%%');
+}
+function renderSystemdUnit(template, options) {
+    const args = [
+        options.nodePath,
+        options.runtime.cliEntrypoint,
+        '--data-dir',
+        options.dataDir,
+        'up',
+        ...(options.host === '0.0.0.0' ? ['--host', options.host] : []),
+        '--static-root',
+        options.runtime.staticRoot,
+        '--channel',
+        'desk',
+        '--channel-name',
+        'Desk',
+    ];
+    const rendered = template
+        .replace(/^WorkingDirectory=.*$/m, `WorkingDirectory=${systemdPath(options.runtime.root)}`)
+        .replace(/^EnvironmentFile=.*$/m, `EnvironmentFile=${systemdPath(options.envPath)}`)
+        .replace(/^ExecStart=.*$/m, `ExecStart=${args.map(systemdQuote).join(' ')}`);
+    if (rendered === template || rendered.includes('%h/codor')) {
+        throw new Error('codor setup could not render the systemd service for the invoking runtime');
+    }
+    return rendered;
+}
+function xml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+// harn:assume operator-launches-serve-web-next ref=launchd-current-web-client
+function renderLaunchAgent(options) {
+    const values = {
+        dataDir: xml(options.dataDir),
+        entrypoint: xml(options.runtime.cliEntrypoint),
+        errorLog: xml(join(options.logDir, 'codor.err.log')),
+        nodePath: xml(options.nodePath),
+        outputLog: xml(join(options.logDir, 'codor.log')),
+        repoRoot: xml(options.runtime.root),
+        servicePath: xml(options.servicePath),
+        staticRoot: xml(options.runtime.staticRoot),
+        token: xml(options.token),
+    };
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCH_AGENT_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${values.nodePath}</string>
+    <string>${values.entrypoint}</string>
+    <string>--data-dir</string>
+    <string>${values.dataDir}</string>
+    <string>up</string>
+    <string>--static-root</string>
+    <string>${values.staticRoot}</string>
+    <string>--channel</string>
+    <string>desk</string>
+    <string>--channel-name</string>
+    <string>Desk</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${values.repoRoot}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>CODOR_TOKEN</key>
+    <string>${values.token}</string>
+    <key>PATH</key>
+    <string>${values.servicePath}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>Umask</key>
+  <integer>63</integer>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+  <key>ExitTimeOut</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>${values.outputLog}</string>
+  <key>StandardErrorPath</key>
+  <string>${values.errorLog}</string>
+</dict>
+</plist>
+`;
+}
+/** The full launchctl error text and whether it is the transient exit-5. */
+function classifyBootstrapError(error) {
+    const err = error;
+    const text = [err.message, err.stderr?.toString()].filter(Boolean).join('\n').trim();
+    const retryable = err.status === 5 || /input\/output error|bootstrap failed:\s*5\b/i.test(text);
+    return { text, retryable };
+}
+// harn:assume setup-macos-launchd-confirms-loaded-and-healthy ref=launchd-bootstrap-recovery
+/**
+ * Bootstrap the per-user LaunchAgent, recovering from a transient
+ * `Bootstrap failed: 5: Input/output error` (which arrives with the retryable
+ * text on a later line and exit status 5). Continues past a bootstrap error
+ * only when `launchctl print` confirms the target is loaded AND the HTTP probe
+ * answers — a briefly-answering booted-out orphan is not success. Never
+ * suggests root.
+ */
+export async function bootstrapLaunchAgent(deps) {
+    const { exec, probe, sleep, domain, target, plistPath, nodePath, cliEntrypoint, endpoint, log } = deps;
+    const exists = deps.exists ?? existsSync;
+    const MAX_ATTEMPTS = 3;
+    const RETRY_DELAY_MS = 500;
+    // Validate before unloading anything, so a broken install never tears down a
+    // working prior instance: the plist parses, and the executables it references
+    // exist.
+    if (!existsSync(plistPath))
+        throw new Error(`the LaunchAgent plist is missing at ${plistPath}`);
+    try {
+        exec('plutil', ['-lint', plistPath]);
+    }
+    catch (error) {
+        throw new Error(`the LaunchAgent plist did not pass plutil -lint: ${classifyBootstrapError(error).text.split('\n')[0]}`);
+    }
+    if (!exists(nodePath))
+        throw new Error(`the LaunchAgent Node executable does not exist at ${nodePath}`);
+    if (!exists(cliEntrypoint))
+        throw new Error(`the Codor CLI entrypoint does not exist at ${cliEntrypoint}`);
+    const bootout = () => { try {
+        exec('launchctl', ['bootout', target]);
+    }
+    catch { /* not loaded */ } };
+    // `launchctl print <target>` exits non-zero when the target is not loaded.
+    const printState = () => {
+        try {
+            const printed = exec('launchctl', ['print', target]).trim();
+            const line = printed.split('\n').map((entry) => entry.trim()).find((entry) => entry.length > 0);
+            return { loaded: true, summary: line === undefined ? '' : ` (launchctl print: ${line})` };
+        }
+        catch {
+            return { loaded: false, summary: ' (launchctl print: target not loaded)' };
+        }
+    };
+    bootout();
+    let bootstrapped = false;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+        try {
+            exec('launchctl', ['bootstrap', domain, plistPath]);
+            bootstrapped = true;
+            break;
+        }
+        catch (error) {
+            const { text, retryable } = classifyBootstrapError(error);
+            const state = printState();
+            const healthy = await probe(endpoint);
+            // Loaded AND healthy is the only success on a bootstrap error; a
+            // briefly-answering orphan whose target print is absent is not loaded.
+            if (state.loaded && healthy) {
+                log('Codor is already loaded and healthy; keeping it running');
+                return;
+            }
+            if (attempt >= MAX_ATTEMPTS || !retryable) {
+                throw new Error(`launchctl could not start the Codor LaunchAgent: ${text.split('\n').find((line) => line.trim().length > 0) ?? text}${state.summary}`);
+            }
+            log(`launchctl bootstrap did not take (attempt ${String(attempt)}); unloading and retrying`);
+            bootout();
+            await sleep(RETRY_DELAY_MS);
+        }
+    }
+    if (bootstrapped) {
+        exec('launchctl', ['enable', target]);
+        exec('launchctl', ['kickstart', '-k', target]);
+    }
+}
+// harn:end setup-macos-launchd-confirms-loaded-and-healthy
+const TAILSCALE_MACOS_LOCATIONS = [
+    '/Applications/Tailscale.app/Contents/MacOS/Tailscale',
+];
+// harn:assume setup-resolves-and-capability-probes-tailscale-serve ref=tailscale-resolution
+/** Resolve the Tailscale CLI through PATH, then standard macOS app locations. */
+export function resolveTailscale(which, platform, exists = existsSync) {
+    // Normalize the PATH hit to the absolute executable path actually invoked.
+    const onPath = which('tailscale');
+    if (onPath !== undefined && onPath.trim() !== '')
+        return resolve(onPath.trim());
+    if (platform === 'darwin') {
+        for (const location of TAILSCALE_MACOS_LOCATIONS)
+            if (exists(location))
+                return location;
+    }
+    return undefined;
+}
+/** Capability-probe the resolved CLI for Serve support (not an OS allowlist). */
+export function tailscaleServeSupported(tailscalePath, exec) {
+    try {
+        exec(tailscalePath, ['serve', '--help']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Publish Serve through the resolved absolute path and return the HTTPS origin.
+ *  Throws a distinct diagnostic when the serve command itself fails. */
+export function configureTailscaleServe(tailscalePath, localEndpoint, exec) {
+    // Preserve the full message and stderr: real permission/operator guidance often
+    // lands on a later line (the same class of bug fixed for launchctl).
+    const diagnostic = (error) => {
+        const err = error;
+        return [err.message, err.stderr?.toString()].filter(Boolean).join('\n').trim() || String(error);
+    };
+    let status;
+    try {
+        exec(tailscalePath, ['serve', '--bg', localEndpoint]);
+        status = exec(tailscalePath, ['serve', 'status']);
+    }
+    catch (error) {
+        throw new Error(`Tailscale Serve command failed: ${diagnostic(error)}`);
+    }
+    const origin = status.match(/https:\/\/[^\s/]+/)?.[0];
+    if (origin === undefined)
+        throw new Error('Tailscale Serve did not report a private HTTPS origin');
+    return origin;
+}
+const RETRY_OR_LOCAL = [
+    { id: 'retry', label: 'Retry detection', description: 'Check again for Tailscale.', available: true },
+    { id: 'here', label: 'Continue on this computer', description: 'Skip remote access for now.', available: true },
+];
+// harn:assume setup-defers-remote-access-behind-consent ref=setup-remote-access-subflow
+/**
+ * Resolve interactive access. "This computer" never touches Tailscale. "Remote"
+ * detects Tailscale only now, offers Retry/Continue-local when it is missing or
+ * cannot Serve, asks a separate consent before configuring Serve, and degrades
+ * to local — with the exact copyable recovery command — if configuring fails.
+ * Purely a decision function: it mutates nothing but the injected log.
+ */
+export async function runRemoteAccess(deps) {
+    const local = (note) => {
+        deps.log(note);
+        return { access: 'localhost', endpoint: deps.localEndpoint, summary: 'This computer' };
+    };
+    if (deps.choice !== 'remote')
+        return local('this computer only');
+    for (;;) {
+        const { path, serve } = deps.detect();
+        if (path === undefined || !serve) {
+            const message = path === undefined
+                ? 'Tailscale is not installed. Install it from https://tailscale.com/download, then retry.'
+                : 'This Tailscale CLI cannot Serve. Update Tailscale, then retry.';
+            const next = await deps.choose({ message, options: RETRY_OR_LOCAL });
+            if (next === 'retry') {
+                deps.resetDetect();
+                continue;
+            }
+            return local('continuing on this computer only');
+        }
+        const consent = await deps.choose({
+            message: 'Codor can configure Tailscale Serve so you can reach it securely from your other devices. Configure it now?',
+            options: [
+                { id: 'configure', label: 'Configure Tailscale Serve', description: 'Publish Codor privately to your tailnet.', available: true },
+                { id: 'here', label: 'Just this computer', description: 'Keep Codor local for now.', available: true },
+            ],
+        });
+        if (consent !== 'configure')
+            return local('this computer only');
+        try {
+            const endpoint = deps.configureServe(path);
+            deps.log(`private browser origin ${endpoint}`);
+            return { access: 'tailscale', endpoint, summary: 'Tailscale Serve' };
+        }
+        catch (error) {
+            // Keep local Codor working and hand over the exact command to finish later,
+            // derived from the real resolved path and error — never invented sudo.
+            deps.log(`could not configure Tailscale Serve: ${error instanceof Error ? error.message : String(error)}`);
+            deps.log(`to finish remote access later, run: ${path} serve --bg ${deps.localEndpoint}`);
+            deps.log('Codor still works on this computer.');
+            return { access: 'localhost', endpoint: deps.localEndpoint, summary: 'This computer (remote access deferred)' };
+        }
+    }
+}
+// harn:end setup-defers-remote-access-behind-consent
+// harn:assume windows-setup-installs-private-task-service ref=windows-service-rendering
+export function renderWindowsServiceScript(options) {
+    const quote = (value) => value.replaceAll("'", "''");
+    const entrypoint = options.runtime.cliEntrypoint;
+    const staticRoot = options.runtime.staticRoot;
+    return [
+        `$env:CODOR_TOKEN = (Get-Content -Raw -Path '${quote(options.tokenPath)}').Trim()`,
+        `$env:PATH = '${quote(options.servicePath)}'`,
+        `Set-Location -Path '${quote(options.runtime.root)}'`,
+        `& '${quote(options.nodePath)}' '${quote(entrypoint)}' --data-dir '${quote(options.dataDir)}' up --static-root '${quote(staticRoot)}' --channel desk --channel-name Desk >> '${quote(join(options.logDir, 'codor.out.log'))}' 2>> '${quote(join(options.logDir, 'codor.err.log'))}'`,
+        'exit $LASTEXITCODE',
+    ].join('\r\n') + '\r\n';
+}
+export function renderWindowsScheduledTask(options) {
+    const command = `-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${options.scriptPath}"`;
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <Triggers><LogonTrigger><Enabled>true</Enabled><UserId>${xml(options.user)}</UserId></LogonTrigger></Triggers>
+  <Principals><Principal id="Author"><UserId>${xml(options.user)}</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+  <Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><AllowHardTerminate>true</AllowHardTerminate><StartWhenAvailable>true</StartWhenAvailable><RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable><IdleSettings><StopOnIdleEnd>false</StopOnIdleEnd><RestartOnIdle>false</RestartOnIdle></IdleSettings><AllowStartOnDemand>true</AllowStartOnDemand><Enabled>true</Enabled><Hidden>true</Hidden><RunOnlyIfIdle>false</RunOnlyIfIdle><WakeToRun>false</WakeToRun><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><Priority>7</Priority></Settings>
+  <Actions Context="Author"><Exec><Command>powershell.exe</Command><Arguments>${xml(command)}</Arguments></Exec></Actions>
+</Task>
+`;
+}
+// harn:end windows-setup-installs-private-task-service
+export async function probeCodorStatus(endpoint) {
+    try {
+        const response = await fetch(new URL('/api/pairing/status', endpoint), {
+            signal: AbortSignal.timeout(1_000),
+        });
+        if (!response.ok)
+            return false;
+        const body = await response.json();
+        return typeof body.trusted_enrollment === 'boolean';
+    }
+    catch {
+        return false;
+    }
+}
+const defaultSleep = async (milliseconds) => new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
+// harn:assume setup-verifies-codor-before-creating-pairing-code ref=setup-readiness-and-pairing
+export async function waitForCodor(endpoint, probe, sleep) {
+    for (let attempt = 1; attempt <= 20; attempt += 1) {
+        if (await probe(endpoint))
+            return;
+        if (attempt < 20)
+            await sleep(250);
+    }
+    throw new Error(`Codor did not become ready at ${endpoint}; inspect the user-service logs`);
+}
+// harn:end setup-verifies-codor-before-creating-pairing-code
+function runtimeVersion(runtime) {
+    const manifestPath = runtime.layout === 'installed-package'
+        ? join(runtime.root, 'package.json')
+        : join(runtime.root, 'packages', 'cli', 'package.json');
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : 'dev';
+    }
+    catch {
+        return 'dev';
+    }
+}
+// harn:assume windows-setup-installs-private-task-service ref=windows-setup-runtime
+// harn:assume setup-preserves-private-platform-service ref=setup-platform-service-runtime
+export async function runSetup(options) {
+    const overrides = options.overrides ?? {};
+    const platform = overrides.platform ?? process.platform;
+    if (platform !== 'linux' && platform !== 'darwin' && platform !== 'win32') {
+        throw new Error(`codor setup supports Linux, macOS, and Windows; received ${platform}`);
+    }
+    const runtime = overrides.runtime ?? resolveRuntimePaths({ repoRoot: overrides.repoRoot });
+    const home = resolve(overrides.home ?? options.env.HOME ?? homedir());
+    const nodePath = resolve(overrides.nodePath ?? process.execPath);
+    const exec = overrides.exec ?? defaultExec;
+    const which = overrides.which ?? defaultWhich;
+    const renderQr = overrides.renderQr ?? renderTerminalQr;
+    const probe = overrides.probe ?? probeCodorStatus;
+    const sleep = overrides.sleep ?? defaultSleep;
+    const configDir = join(home, '.config', 'codor');
+    const dataDir = join(home, '.codor');
+    const tokenPath = join(configDir, 'token');
+    const envPath = join(configDir, 'env');
+    const userUnitDir = join(home, '.config', 'systemd', 'user');
+    const userUnitPath = join(userUnitDir, 'codor.service');
+    const launchAgentDir = join(home, 'Library', 'LaunchAgents');
+    const launchAgentPath = join(launchAgentDir, `${LAUNCH_AGENT_LABEL}.plist`);
+    const logDir = join(dataDir, 'logs');
+    // The service must reference a durable runtime. An ephemeral (npx/temp)
+    // invoking runtime is copied to ~/.codor/runtime by the Install step; the
+    // service is rendered against that stable copy, while the service template is
+    // still read from the source runtime, which exists now.
+    const version = overrides.version ?? runtimeVersion(runtime);
+    const installIo = overrides.installIo ?? defaultInstallIo;
+    const installSource = resolveInstallSource(runtime);
+    const serviceLocation = installSource.durable ? installSource.installRoot : durableRuntimeLocation(dataDir);
+    const serviceRuntime = installSource.durable ? runtime : packageRuntimePaths(installedCliRoot(serviceLocation));
+    const windowsScriptPath = join(configDir, 'codor-service.ps1');
+    const windowsTaskPath = join(configDir, 'codor-task.xml');
+    const windowsUser = options.env.USERNAME ?? options.env.USER;
+    if (platform === 'win32' && !windowsUser) {
+        throw new Error('codor setup could not determine the Windows user name');
+    }
+    const detected = HARNESSES.flatMap((harness) => {
+        const path = which(harness);
+        return path === undefined ? [] : [{ harness, path }];
+    });
+    // Tailscale is inspected lazily: step 1 never touches it, and the interactive
+    // remote sub-flow probes only after the operator chooses remote access.
+    let tailscaleProbe;
+    const detectTailscale = () => {
+        if (tailscaleProbe === undefined) {
+            const path = resolveTailscale(which, platform);
+            tailscaleProbe = { path, serve: path !== undefined && tailscaleServeSupported(path, exec) };
+        }
+        return tailscaleProbe;
+    };
+    const servicePath = uniquePath([
+        join(home, '.local', 'bin'),
+        dirname(nodePath),
+        ...detected.map(({ path }) => dirname(path)),
+        options.env.PATH,
+    ], platform === 'win32' ? ';' : ':');
+    const systemdBindHost = platform === 'linux'
+        ? wslSystemdBindHost(options.env, overrides.kernelRelease ?? release(), exec, which)
+        : '127.0.0.1';
+    const unitContent = platform === 'linux'
+        ? renderSystemdUnit(readFileSync(runtime.serviceTemplate, 'utf8'), {
+            dataDir, envPath, host: systemdBindHost, nodePath, runtime: serviceRuntime,
+        })
+        : undefined;
+    const launchUid = platform === 'darwin'
+        ? overrides.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined)
+        : undefined;
+    if (platform === 'darwin' && (!Number.isInteger(launchUid) || launchUid < 0)) {
+        throw new Error('codor setup could not determine the macOS user id');
+    }
+    const launchDomain = launchUid === undefined ? undefined : `gui/${String(launchUid)}`;
+    const launchTarget = launchDomain === undefined ? undefined : `${launchDomain}/${LAUNCH_AGENT_LABEL}`;
+    const windowsScript = platform === 'win32'
+        ? renderWindowsServiceScript({ dataDir, logDir, nodePath, runtime: serviceRuntime, servicePath, tokenPath })
+        : undefined;
+    const windowsTask = platform === 'win32'
+        ? renderWindowsScheduledTask({ scriptPath: windowsScriptPath, user: windowsUser })
+        : undefined;
+    // harn:assume setup-unattended-mutation-requires-explicit-intent ref=setup-unattended-runtime
+    const interactive = !options.dryRun && options.yes !== true && isInteractiveSetup(overrides.streams);
+    if (!options.dryRun && !interactive) {
+        if (options.yes !== true) {
+            throw new Error('non-interactive setup requires --yes and --access <localhost|tailscale>');
+        }
+        if (options.access === undefined) {
+            throw new Error('non-interactive setup with --yes also requires --access <localhost|tailscale>');
+        }
+    }
+    // harn:end setup-unattended-mutation-requires-explicit-intent
+    // harn:assume setup-dry-run-reports-without-mutation-or-secret ref=setup-dry-run-runtime
+    if (options.dryRun) {
+        const access = options.access ?? 'localhost';
+        if (access === 'tailscale') {
+            const { path, serve } = detectTailscale();
+            if (!serve) {
+                throw new Error(path === undefined
+                    ? '--access tailscale requires the Tailscale CLI (not found on PATH or in /Applications)'
+                    : '--access tailscale requires a Tailscale CLI that supports Serve');
+            }
+        }
+        options.out(installSource.durable
+            ? `[dry-run] use the Codor runtime in place at ${serviceLocation}`
+            : `[dry-run] install a durable Codor runtime -> ${serviceLocation}`);
+        options.out(`[dry-run] create ${configDir} and ${dataDir} mode 700; create ${tokenPath} mode 600 if absent`);
+        if (platform === 'linux') {
+            options.out(`[dry-run] install ${runtime.serviceTemplate} -> ${userUnitPath} mode 600`);
+            options.out('[dry-run] unit content:');
+            for (const line of unitContent.trimEnd().split('\n'))
+                options.out(line);
+            options.out(`[dry-run] write ${envPath} mode 600`);
+            options.out('CODOR_TOKEN=<redacted generated-or-existing token>');
+            options.out(`PATH=${servicePath}`);
+            options.out('[dry-run] systemctl --user daemon-reload');
+            options.out('[dry-run] systemctl --user enable --now codor.service');
+        }
+        else if (platform === 'darwin') {
+            const launchAgent = renderLaunchAgent({
+                dataDir, logDir, nodePath, runtime: serviceRuntime, servicePath,
+                token: '<redacted generated-or-existing token>',
+            });
+            options.out(`[dry-run] create ${logDir} mode 700`);
+            options.out(`[dry-run] install generated LaunchAgent -> ${launchAgentPath} mode 600`);
+            options.out('[dry-run] launch agent content:');
+            for (const line of launchAgent.trimEnd().split('\n'))
+                options.out(line);
+            options.out(`[dry-run] launchctl bootout ${launchTarget} (ignore not-loaded)`);
+            options.out(`[dry-run] launchctl bootstrap ${launchDomain} ${launchAgentPath}`);
+            options.out(`[dry-run] launchctl enable ${launchTarget}`);
+            options.out(`[dry-run] launchctl kickstart -k ${launchTarget}`);
+        }
+        else {
+            options.out(`[dry-run] protect ${tokenPath} for ${windowsUser} with icacls`);
+            options.out(`[dry-run] create ${logDir}`);
+            options.out(`[dry-run] install generated ServiceScript -> ${windowsScriptPath}`);
+            for (const line of windowsScript.trimEnd().split(/\r?\n/))
+                options.out(line);
+            options.out(`[dry-run] install generated ScheduledTaskXml -> ${windowsTaskPath} as UTF-16LE`);
+            for (const line of windowsTask.trimEnd().split('\n'))
+                options.out(line);
+            options.out(`[dry-run] schtasks /Create /TN "Codor Switchboard" /XML "${windowsTaskPath}" /F`);
+            options.out('[dry-run] schtasks /Run /TN "Codor Switchboard"');
+        }
+        if (access === 'tailscale') {
+            options.out('[dry-run] tailscale serve --bg http://127.0.0.1:8137');
+            options.out('[dry-run] tailscale serve status');
+        }
+        else {
+            options.out('[dry-run] access localhost; skip Tailscale Serve');
+        }
+        options.out('[dry-run] wait for Codor pairing status, then generate a ten-minute QR, URL, and pairing code');
+        return;
+    }
+    // harn:end setup-dry-run-reports-without-mutation-or-secret
+    const stepTitles = SETUP_STAGE_TITLES;
+    // Shared state the steps thread through. `pairing` and `serviceStarted` are
+    // memoized so a Retry re-runs the step's work idempotently: the daemon is not
+    // restarted and the pairing code is not re-minted.
+    // The readiness probe always targets the local daemon; the pairing endpoint
+    // becomes the tailnet HTTPS origin only when Tailscale Serve succeeds.
+    const localEndpoint = 'http://127.0.0.1:8137';
+    let endpoint = localEndpoint;
+    let selectedAccess = options.access;
+    let pairing;
+    let serviceStarted = false;
+    const checkStep = (log) => {
+        // Read-only detection; Tailscale is not inspected here.
+        log(`${platform} with Node ${process.versions.node}`);
+        log(detected.length > 0
+            ? `found ${detected.map(({ harness }) => harness).join(', ')}`
+            : 'no supported coding agents detected');
+        return detected.length > 0
+            ? `${platform}; ${detected.map(({ harness }) => harness).join(', ')}`
+            : `${platform}; no agents on PATH`;
+    };
+    const prepareStep = (log) => {
+        mkdirSync(configDir, { recursive: true, mode: 0o700 });
+        mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+        if (!existsSync(tokenPath)) {
+            const token = overrides.randomToken?.() ?? randomBytes(32).toString('hex');
+            writeFileSync(tokenPath, `${token}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        }
+        if (platform === 'win32')
+            exec('icacls', [tokenPath, '/inheritance:r', '/grant:r', `${windowsUser}:F`]);
+        else {
+            chmodSync(configDir, 0o700);
+            chmodSync(dataDir, 0o700);
+            chmodSync(tokenPath, 0o600);
+        }
+        log('private configuration and data are ready');
+        return 'config and mode-600 token ready';
+    };
+    // harn:assume setup-installs-durable-per-user-runtime-atomically ref=setup-install-runtime-wiring
+    // Install Codor: make the invoking runtime durable (so the service never
+    // references an npx cache), then create the private config, data, and token.
+    const installStep = (log, intent = 'ensure') => {
+        const result = installDurableRuntime({ runtime, dataDir, version, intent, io: installIo });
+        log(result.action === 'in-place'
+            ? `using the Codor runtime in place at ${result.location}`
+            : `${result.action} the Codor ${result.version} runtime at ${result.location}`);
+        prepareStep(log);
+        return `Codor ${result.version} at ${result.location}`;
+    };
+    // harn:end setup-installs-durable-per-user-runtime-atomically
+    // Non-interactive access selection (used by --yes and the linear fallback).
+    const chooseStep = (log, choice) => {
+        if (choice !== 'localhost' && choice !== 'tailscale')
+            throw new Error('setup requires an access choice');
+        if (choice === 'localhost') {
+            selectedAccess = 'localhost';
+            endpoint = localEndpoint;
+            log('localhost only');
+            return 'Localhost';
+        }
+        const { path, serve } = detectTailscale();
+        if (path === undefined)
+            throw new Error('Tailscale is not installed; pick localhost or install Tailscale');
+        if (!serve)
+            throw new Error('this Tailscale CLI does not support Serve; pick localhost');
+        endpoint = configureTailscaleServe(path, localEndpoint, exec);
+        selectedAccess = 'tailscale';
+        log(`private browser origin ${endpoint}`);
+        return 'Tailscale Serve';
+    };
+    // Interactive access: delegates to the testable runRemoteAccess and applies
+    // its decision to the shared endpoint/access state.
+    const whereStep = async (log, choice, choose) => {
+        const result = await runRemoteAccess({
+            choice, localEndpoint, log, choose,
+            detect: detectTailscale,
+            resetDetect: () => { tailscaleProbe = undefined; },
+            configureServe: (path) => configureTailscaleServe(path, localEndpoint, exec),
+        });
+        selectedAccess = result.access;
+        endpoint = result.endpoint;
+        return result.summary;
+    };
+    const startStep = async (log) => {
+        // A Retry must not reinstall or restart a daemon that is already up; when
+        // the service was started this run and still answers, short-circuit.
+        if (serviceStarted && await probe(localEndpoint)) {
+            log('Codor is already running; reusing it');
+            return 'service already running';
+        }
+        if (!existsSync(tokenPath))
+            throw new Error(`operator token is missing at ${tokenPath}`);
+        serviceStarted = true;
+        if (platform === 'linux') {
+            const token = readFileSync(tokenPath, 'utf8').trim();
+            mkdirSync(userUnitDir, { recursive: true, mode: 0o700 });
+            writeFileSync(userUnitPath, unitContent, { encoding: 'utf8', mode: 0o600 });
+            chmodSync(userUnitPath, 0o600);
+            writeFileSync(envPath, `CODOR_TOKEN=${token}\nPATH=${servicePath}\n`, { encoding: 'utf8', mode: 0o600 });
+            chmodSync(envPath, 0o600);
+            exec('systemctl', ['--user', 'daemon-reload']);
+            exec('systemctl', ['--user', 'enable', '--now', 'codor.service']);
+            try {
+                const linger = exec('loginctl', ['show-user', options.env.USER ?? '', '-p', 'Linger', '--value']);
+                if (linger.trim() !== 'yes')
+                    log(`for boot startup: loginctl enable-linger ${options.env.USER ?? '$USER'}`);
+            }
+            catch {
+                log(`check lingering: loginctl enable-linger ${options.env.USER ?? '$USER'}`);
+            }
+        }
+        else if (platform === 'darwin') {
+            const token = readFileSync(tokenPath, 'utf8').trim();
+            mkdirSync(launchAgentDir, { recursive: true });
+            mkdirSync(logDir, { recursive: true, mode: 0o700 });
+            chmodSync(logDir, 0o700);
+            writeFileSync(launchAgentPath, renderLaunchAgent({
+                dataDir, logDir, nodePath, runtime: serviceRuntime, servicePath, token,
+            }), { encoding: 'utf8', mode: 0o600 });
+            chmodSync(launchAgentPath, 0o600);
+            await bootstrapLaunchAgent({
+                exec, probe, sleep,
+                exists: overrides.exists,
+                domain: launchDomain,
+                target: launchTarget,
+                plistPath: launchAgentPath,
+                nodePath,
+                cliEntrypoint: serviceRuntime.cliEntrypoint,
+                endpoint: localEndpoint,
+                log,
+            });
+        }
+        else {
+            mkdirSync(logDir, { recursive: true });
+            writeFileSync(windowsScriptPath, windowsScript, 'utf8');
+            writeFileSync(windowsTaskPath, Buffer.from(`${windowsTask}`, 'utf16le'));
+            exec('schtasks', ['/Create', '/TN', 'Codor Switchboard', '/XML', windowsTaskPath, '/F']);
+            exec('schtasks', ['/Run', '/TN', 'Codor Switchboard']);
+        }
+        await waitForCodor(localEndpoint, probe, sleep);
+        log('Codor answered its pairing status check');
+        if (systemdBindHost === '0.0.0.0')
+            log('WSL2 NAT is reachable through Windows localhost');
+        return 'service enabled and answering';
+    };
+    const pairStep = (log) => {
+        if (pairing === undefined) {
+            const crypto = new CryptoVault(dataDir);
+            try {
+                const offer = crypto.pairing.issue(endpoint);
+                const url = pairingUrl(offer);
+                pairing = { code: offer.pairing_code, expires: offer.expires_at, qr: renderQr(url), url };
+            }
+            finally {
+                crypto.close();
+            }
+        }
+        log(`pairing code ${pairing.code}`);
+        return `code ${pairing.code}`;
+    };
+    const cardColumns = overrides.streams?.output?.columns ?? process.stdout.columns ?? 80;
+    // Rows available to the pairing card once the frame's header, heading, and the
+    // reserved Finish control are set aside; the card omits its QR to fit.
+    const cardRows = overrides.streams?.output?.rows ?? process.stdout.rows ?? 24;
+    const cardMaxRows = Math.max(8, cardRows - 8);
+    const emitPairing = () => {
+        options.out(renderPairingCard({
+            code: pairing.code,
+            url: pairing.url,
+            expires: pairing.expires,
+            qr: pairing.qr,
+            instruction: 'Scan the QR or enter the code in your browser to finish pairing.',
+        }, cardColumns));
+    };
+    if (interactive) {
+        const session = new SetupSession({ version, streams: overrides.streams });
+        const existingInstall = detectInstalledRuntime(dataDir, installIo);
+        const installMenu = existingInstall === undefined
+            ? {
+                message: 'Install Codor on this computer?',
+                options: [
+                    { id: 'install', label: 'Install Codor', description: 'Copy a durable runtime, then create your private config, data, and token.', available: true },
+                    { id: 'later', label: 'Not now', description: 'Do not change anything on this computer.', available: true },
+                ],
+            }
+            : existingInstall.version === version
+                ? {
+                    message: `Codor ${version} is already installed. Continue?`,
+                    options: [
+                        { id: 'continue', label: 'Continue', description: 'Use the installed runtime and ensure your private files.', available: true },
+                        { id: 'update', label: 'Reinstall', description: 'Re-copy the durable runtime.', available: true },
+                        { id: 'later', label: 'Not now', description: 'Do not change anything.', available: true },
+                    ],
+                }
+                : {
+                    message: `Update Codor from ${existingInstall.version} to ${version}?`,
+                    options: [
+                        { id: 'update', label: 'Update Codor', description: 'Re-copy the durable runtime at the new version.', available: true },
+                        { id: 'keep', label: 'Keep current', description: `Keep ${existingInstall.version} and ensure your private files.`, available: true },
+                        { id: 'later', label: 'Not now', description: 'Do not change anything.', available: true },
+                    ],
+                };
+        const steps = [
+            { title: stepTitles[0], description: 'Read-only — nothing on your computer changes.', run: async ({ log }) => checkStep(log) },
+            {
+                title: stepTitles[1],
+                description: 'Set up Codor in a stable per-user location.',
+                // Consent gate: no runtime is copied and no files are created until an
+                // affirmative choice; "Not now" leaves the computer unchanged.
+                menu: installMenu,
+                run: async ({ log, choice }) => (choice === 'later'
+                    ? { skip: true, summary: '(run codor install when ready)', skipFollowing: true }
+                    : installStep(log, choice === 'update' ? 'update' : choice === 'keep' ? 'keep' : 'ensure')),
+            },
+            {
+                title: stepTitles[2],
+                description: 'Choose where you will use Codor.',
+                menu: {
+                    message: 'Where will you use Codor?',
+                    options: [
+                        { id: 'here', label: 'On this computer only', description: 'Reach Codor from this computer.', available: true },
+                        { id: 'remote', label: 'On this computer and remotely', description: 'Also reach Codor from your other devices, over Tailscale.', available: true },
+                    ],
+                },
+                run: async ({ log, choice, choose }) => whereStep(log, choice, choose),
+            },
+            {
+                title: stepTitles[3],
+                description: 'Install and start the private background service.',
+                // Consent gate: nothing is installed or started until Start is chosen.
+                menu: {
+                    message: 'Run Codor in the background?',
+                    options: [
+                        { id: 'start', label: 'Start Codor', description: 'Install and start the private background service.', available: true },
+                        { id: 'later', label: 'Not now', description: 'Do not install or start anything yet.', available: true },
+                    ],
+                },
+                run: async ({ log, choice }) => (choice === 'start'
+                    ? startStep(log)
+                    : { skip: true, summary: '(run codor install when ready)', skipFollowing: true }),
+            },
+            {
+                title: stepTitles[4],
+                description: 'Connect a browser with a short-lived pairing code.',
+                // Consent gate: no pairing code is minted until Create is chosen.
+                menu: {
+                    message: 'Pair a browser now?',
+                    options: [
+                        { id: 'create', label: 'Create a pairing code', description: 'Mint a ten-minute code and QR now.', available: true },
+                        { id: 'later', label: 'Set this up later', description: 'Keep the service running and pair from a browser later.', available: true },
+                    ],
+                },
+                run: async ({ log, choice, presentResult }) => {
+                    if (choice !== 'create')
+                        return { skip: true, summary: '(run codor pair later)' };
+                    const summary = pairStep(log);
+                    // Replace the question in-frame with the QR/code result card, so it is
+                    // visible before Finish closes the installer.
+                    presentResult(renderPairingCard({
+                        code: pairing.code,
+                        url: pairing.url,
+                        expires: pairing.expires,
+                        qr: pairing.qr,
+                        instruction: 'Scan the QR or enter the code in your browser to finish pairing.',
+                    }, cardColumns, cardMaxRows));
+                    return summary;
+                },
+            },
+        ];
+        await session.run(steps);
+        const harnesses = detected.map(({ harness }) => harness);
+        if (!serviceStarted) {
+            // Start was declined: nothing was installed, and pairing was skipped too.
+            session.finish({ headline: 'Setup paused - Codor is not running.', harnesses, nextAction: 'Run `codor install` when you are ready to install and start Codor.' });
+        }
+        else if (pairing === undefined) {
+            // The service is up but the operator declined pairing.
+            session.finish({ headline: 'Codor is running.', endpoint, harnesses, nextAction: 'Run `codor pair` when you want to connect a browser.' });
+        }
+        else {
+            // The pairing result card is already visible in-frame; keep it as the
+            // final frame and close without re-emitting it.
+            session.finish();
+        }
+    }
+    else {
+        const linear = (index) => (message) => options.out(`[${String(index + 1)}/5] ${message}`);
+        options.out(`[1/5] ${stepTitles[0]}`);
+        checkStep(linear(0));
+        options.out(`[2/5] ${stepTitles[1]}`);
+        installStep(linear(1));
+        options.out(`[3/5] ${stepTitles[2]}`);
+        chooseStep(linear(2), options.access);
+        options.out(`[4/5] ${stepTitles[3]}`);
+        await startStep(linear(3));
+        options.out(`[5/5] ${stepTitles[4]}`);
+        pairStep(linear(4));
+        emitPairing();
+    }
+}
+// harn:end setup-preserves-private-platform-service
+// harn:end windows-setup-installs-private-task-service
+//# sourceMappingURL=setup.js.map