orcasynth 1.1.2 → 1.2.1

package/dist/cli/commands.js

@@ -10,16 +10,18 @@ export function defaultLifecycleDeps(version) {
         update: realUpdate,
     };
 }
-/** Render a one-glance status block. A service is shown stopped, running-but-unhealthy, or healthy. */
-export function formatStatus(s) {
+/** Render a one-glance status block. A service is shown stopped, running-but-unhealthy, or healthy.
+ *  When `version` is given, a header line is prepended. */
+export function formatStatus(s, version) {
     const line = (name, svc, url) => {
         if (!svc.running)
-            return `  ${name.padEnd(7)} ○ stopped`;
+            return `  ${name.padEnd(7)} ○  stopped`;
         const dot = svc.healthy ? '●' : '◐';
         const health = svc.healthy ? 'healthy' : 'starting…';
-        return `  ${name.padEnd(7)} ${dot} running  :${svc.port}  ${health}  ${svc.healthy ? url : ''}`.trimEnd();
+        return `  ${name.padEnd(7)} ${dot}  running  :${svc.port}  ${health}${svc.healthy && url ? `  ${url}` : ''}`.trimEnd();
     };
-    return [line('daemon', s.daemon, ''), line('web', s.web, `http://localhost:${s.web.port}`)].join('\n');
+    const body = [line('daemon', s.daemon, ''), line('web', s.web, `http://localhost:${s.web.port || 4500}`)];
+    return (version ? [`  orcasynth v${version}`, '', ...body] : body).join('\n');
 }
 /** Dispatch the install-lifecycle commands. Returns true when handled, false for anything else (the
  *  caller then falls through to the daemon-backed API CLI). Lifecycle commands manage the daemon
@@ -38,7 +40,7 @@ export async function runLifecycle(cmd, env, deps) {
             return true;
         }
         case 'status': {
-            deps.log(formatStatus(await deps.status(env)));
+            deps.log(formatStatus(await deps.status(env), deps.version));
             return true;
         }
         case 'update': {

package/dist/cli/index.js

@@ -7,6 +7,15 @@ import { OrcaClient } from './client.js';
 import { defaultLifecycleDeps, runLifecycle } from './commands.js';
 import { menu } from './menu.js';
 const BASE = process.env.ORCA_URL ?? 'http://localhost:4400';
+const USAGE = 'usage: orca [menu] | install | <up|down|status|update> | <ls|ready|sessions|close|plan submit|overseer poll|overseer decide>';
+/** Commands that talk to the daemon API — only these justify auto-starting it. Everything else
+ *  (help, unknown verbs) must NOT spawn a daemon: a stray detached daemon squats the port and starves
+ *  the systemd-managed one into a restart loop. */
+const API_COMMANDS = new Set(['ls', 'ready', 'sessions', 'close', 'plan', 'overseer']);
+/** True only for verbs that need the daemon API up — the gate for ensureDaemon's auto-spawn. */
+export function needsDaemon(cmd) {
+    return cmd !== undefined && API_COMMANDS.has(cmd);
+}
 /** This package's version, read from its package.json (two dirs up from dist/cli/index.js). */
 function pkgVersion() {
     try {
@@ -136,7 +145,7 @@ export async function run(argv, c, env) {
             break;
         }
         default:
-            console.error('usage: orca [menu] | <up|down|status|update> | <ls|ready|sessions|close|plan submit|overseer poll|overseer decide>');
+            console.error(USAGE);
             process.exit(1);
     }
 }
@@ -149,10 +158,31 @@ async function main() {
         await menu(process.env, version);
         return;
     }
+    // Help / bare non-TTY invocation: print usage and stop. Must NOT fall through to ensureDaemon.
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+        console.log(USAGE);
+        return;
+    }
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        console.log(version);
+        return;
+    }
+    // `orca install` is the root provisioning wizard — it sets up systemd, the proxy and the admin
+    // itself, so it must run BEFORE ensureDaemon (no auto-spawn) and before the lifecycle commands.
+    if (argv[0] === 'install') {
+        const { install } = await import('./install/index.js');
+        await install(argv.slice(1));
+        return;
+    }
     // Install-lifecycle commands manage the daemon/web themselves — handle them BEFORE ensureDaemon so
     // they don't trigger the API-CLI's auto-spawn.
     if (await runLifecycle(argv[0], process.env, defaultLifecycleDeps(version)))
         return;
+    // Only API commands may auto-start the daemon; an unknown verb errors out without spawning anything.
+    if (!needsDaemon(argv[0])) {
+        console.error(USAGE);
+        process.exit(1);
+    }
     await ensureDaemon();
     const c = new OrcaClient(BASE, process.env.ORCA_TOKEN);
     await run(argv, c, process.env);

package/dist/cli/install/agentClis.js

@@ -0,0 +1,16 @@
+export const AGENT_CLIS = [
+    { id: 'claude', bin: 'claude', pkg: '@anthropic-ai/claude-code' },
+    { id: 'opencode', bin: 'opencode', pkg: 'opencode-ai' },
+    { id: 'codex', bin: 'codex', pkg: '@openai/codex' },
+];
+/** Resolve each CLI on the SERVICE USER's PATH (not root's) — that's who runs the agents, and where
+ *  their `… login` auth must live. */
+export async function detectAgentClis(r, asUser) {
+    return Promise.all(AGENT_CLIS.map(async (c) => {
+        const path = await r.which(c.bin, asUser);
+        return { ...c, installed: path !== null, path };
+    }));
+}
+export function installCommand(cli) {
+    return { cmd: 'npm', args: ['install', '-g', cli.pkg] };
+}

package/dist/cli/install/index.js

@@ -0,0 +1,358 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve, join } from 'node:path';
+import * as p from '@clack/prompts';
+import { realRunner } from './runner.js';
+import { preflight, preflightBlockers } from './preflight.js';
+import { ensureServiceUser, userHome } from './serviceUser.js';
+import { detectAgentClis, installCommand } from './agentClis.js';
+import { daemonUnit, webUnit } from './systemdUnits.js';
+import { detectProxy, nginxVhost, apacheVhost, certbotCommand } from './proxy.js';
+import { applySetup, buildSetupPlan, isFirstRun } from '../setup.js';
+import { runSetupWizard } from '../setupWizard.js';
+const DAEMON_PORT = Number(process.env.ORCA_PORT ?? 4400);
+const WEB_PORT = Number(process.env.ORCA_WEB_PORT ?? 4500);
+// ── package + npm path resolution ────────────────────────────────────────────
+/** Absolute paths into the globally-installed package — this file lives at
+ *  <pkgRoot>/dist/cli/install/index.js, so the daemon entry and web bundle resolve relative to it. */
+function packagePaths() {
+    const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+    return { daemonEntry: join(pkgRoot, 'dist', 'daemon', 'index.js'), webServer: join(pkgRoot, 'web-dist', 'server.js') };
+}
+/** npm's global bin dir (where the `orca` symlink + globally-installed agent CLIs land). */
+async function npmGlobalBin(r) {
+    const res = await r.exec('npm', ['prefix', '-g']);
+    return join(res.stdout.trim() || '/usr/local', 'bin');
+}
+// ── small helpers ────────────────────────────────────────────────────────────
+const base = `http://127.0.0.1:${DAEMON_PORT}`;
+function bail(v) {
+    if (p.isCancel(v)) {
+        p.cancel('Installation cancelled.');
+        process.exit(1);
+    }
+}
+async function step(label, fn) {
+    // Off a TTY (unattended / CI / piped logs) a spinner just spams frames — emit one line per step.
+    if (!process.stdout.isTTY) {
+        try {
+            const out = await fn();
+            p.log.success(label);
+            return out;
+        }
+        catch (e) {
+            p.log.error(`${label} — failed`);
+            throw e;
+        }
+    }
+    const s = p.spinner();
+    s.start(label);
+    try {
+        const out = await fn();
+        s.stop(`${label} ✓`);
+        return out;
+    }
+    catch (e) {
+        s.stop(`${label} ✗`);
+        throw e;
+    }
+}
+/** Run a command and throw with its stderr when it fails — used for the system mutations where a
+ *  non-zero exit must abort the wizard rather than silently continue. */
+async function must(r, cmd, args, opts) {
+    const res = await r.exec(cmd, args, opts);
+    if (res.code !== 0)
+        throw new Error(`${cmd} ${args.join(' ')} failed: ${(res.stderr || res.stdout).trim() || res.code}`);
+}
+/** Poll the daemon's /setup endpoint until it answers (services just came up) or we give up. */
+async function waitForDaemon(tries = 40) {
+    for (let i = 0; i < tries; i++) {
+        try {
+            if ((await fetch(`${base}/setup`)).ok)
+                return true;
+        }
+        catch { /* not up yet */ }
+        await new Promise((res) => setTimeout(res, 500));
+    }
+    return false;
+}
+/** End-to-end check: the admin can authenticate against the running daemon. */
+async function loginSmokeTest(username, password) {
+    const res = await fetch(`${base}/auth/login`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ username, password }),
+    });
+    if (!res.ok)
+        throw new Error(`login returned ${res.status}`);
+    const body = await res.json();
+    if (!body.token)
+        throw new Error('login returned no token');
+}
+// ── prompt-free executors (shared by interactive + unattended) ───────────────
+async function aptInstall(r, ...pkgs) {
+    await must(r, 'apt-get', ['update']);
+    await must(r, 'apt-get', ['install', '-y', ...pkgs]);
+}
+/** Write + enable the two systemd units and verify they came active. */
+async function provisionSystemd(r, user, home) {
+    const { daemonEntry, webServer } = packagePaths();
+    const params = {
+        user, home, nodePath: process.execPath, daemonEntry, webServer,
+        npmGlobalBin: await npmGlobalBin(r), daemonPort: DAEMON_PORT, webPort: WEB_PORT,
+    };
+    // Ensure the data tree exists and is owned by the service user before first boot.
+    await must(r, 'mkdir', ['-p', join(home, '.config', 'orca', 'logs')]);
+    await must(r, 'chown', ['-R', `${user}:`, join(home, '.config', 'orca')]);
+    await r.writeFile('/etc/systemd/system/orca-daemon.service', daemonUnit(params));
+    await r.writeFile('/etc/systemd/system/orca-web.service', webUnit(params));
+    await must(r, 'systemctl', ['daemon-reload']);
+    await must(r, 'systemctl', ['enable', '--now', 'orca-daemon.service']);
+    await must(r, 'systemctl', ['enable', '--now', 'orca-web.service']);
+    for (const svc of ['orca-daemon', 'orca-web']) {
+        const res = await r.exec('systemctl', ['is-active', svc]);
+        if (res.stdout.trim() !== 'active')
+            throw new Error(`${svc} did not start (journalctl -u ${svc})`);
+    }
+}
+/** Detect the installed reverse proxy, installing the preferred one when none is present. */
+async function resolveProxy(r, preference) {
+    const existing = await detectProxy(r);
+    if (existing)
+        return existing;
+    await aptInstall(r, preference === 'nginx' ? 'nginx' : 'apache2');
+    return preference;
+}
+/** Render the vhost for the domain and make the proxy serve it. */
+async function configureVhost(r, kind, domain) {
+    if (kind === 'nginx') {
+        await r.writeFile('/etc/nginx/sites-available/orca.conf', nginxVhost(domain, WEB_PORT));
+        await must(r, 'ln', ['-sf', '/etc/nginx/sites-available/orca.conf', '/etc/nginx/sites-enabled/orca.conf']);
+        await must(r, 'nginx', ['-t']);
+        await must(r, 'systemctl', ['reload', 'nginx']);
+    }
+    else {
+        await r.writeFile('/etc/apache2/sites-available/orca.conf', apacheVhost(domain, WEB_PORT));
+        await must(r, 'a2enmod', ['proxy', 'proxy_http']);
+        await must(r, 'a2ensite', ['orca']);
+        await must(r, 'systemctl', ['reload', 'apache2']);
+    }
+}
+/** Install certbot if needed and obtain + install a Let's Encrypt certificate. */
+async function obtainTls(r, kind, domain, email) {
+    if (!(await r.which('certbot'))) {
+        await aptInstall(r, 'certbot', kind === 'nginx' ? 'python3-certbot-nginx' : 'python3-certbot-apache');
+    }
+    const { cmd, args } = certbotCommand(kind, domain, email ?? undefined);
+    await must(r, cmd, args);
+}
+/** Create the first admin from the plan (only when the daemon has no users yet) and prove login. */
+async function provisionAdmin(answers) {
+    if (!(await isFirstRun(fetch, base))) {
+        p.log.info('Admin already exists — skipping account creation.');
+        return;
+    }
+    await applySetup(fetch, base, buildSetupPlan(answers));
+    await loginSmokeTest(answers.username, answers.password);
+}
+/** Provision a box from a fully-resolved plan. Used directly by the unattended path; the interactive
+ *  path drives the same executors with spinners and inline prompts. */
+async function execute(r, plan) {
+    if (plan.installTmux)
+        await step('Installing tmux', () => aptInstall(r, 'tmux'));
+    const { home } = await step(`Service user "${plan.user.username}"`, () => ensureServiceUser(r, plan.user));
+    for (const id of plan.agents) {
+        const { cmd, args } = installCommand({ id, bin: id, pkg: agentPkg(id) });
+        await step(`Installing ${id}`, () => must(r, cmd, args));
+    }
+    await step('Configuring systemd services', () => provisionSystemd(r, plan.user.username, home));
+    const ready = await step('Waiting for the daemon', () => waitForDaemon());
+    if (!ready)
+        throw new Error('daemon did not become reachable — check: journalctl -u orca-daemon');
+    if (plan.domain) {
+        const kind = await step('Configuring reverse proxy', async () => {
+            const k = await resolveProxy(r, plan.proxyPreference);
+            await configureVhost(r, k, plan.domain);
+            return k;
+        });
+        if (plan.tls)
+            await step('Requesting HTTPS certificate', () => obtainTls(r, kind, plan.domain, plan.email));
+    }
+    if (plan.admin)
+        await step('Creating admin + verifying login', () => provisionAdmin(plan.admin));
+}
+/** npm package for an agent CLI id (so the executor needn't carry the full AgentCli around). */
+function agentPkg(id) {
+    const map = { claude: '@anthropic-ai/claude-code', opencode: 'opencode-ai', codex: '@openai/codex' };
+    const pkg = map[id];
+    if (!pkg)
+        throw new Error(`unknown agent CLI: ${id}`);
+    return pkg;
+}
+// ── unattended front-end ─────────────────────────────────────────────────────
+function flag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+/** Build a plan from CLI flags for `--unattended`. Resolves create-vs-existing from whether the user
+ *  already exists, so the same command is idempotent across re-runs. */
+async function planFromArgs(r, args) {
+    const username = flag(args, '--user') ?? 'orca';
+    const exists = (await userHome(r, username)) !== null;
+    const agentsRaw = flag(args, '--agents');
+    const agents = !agentsRaw || agentsRaw === 'none' ? []
+        : agentsRaw === 'all' ? ['claude', 'opencode', 'codex']
+            : agentsRaw.split(',').map((s) => s.trim()).filter(Boolean);
+    const domain = flag(args, '--domain') ?? null;
+    const adminUser = flag(args, '--admin-user');
+    const adminPass = flag(args, '--admin-pass');
+    const admin = adminUser && adminPass
+        ? { username: adminUser, password: adminPass, apiUrl: flag(args, '--llm-url') ?? 'https://api.openai.com/v1', apiKey: flag(args, '--llm-key') ?? '', model: flag(args, '--llm-model') ?? 'gpt-4o-mini' }
+        : null;
+    return {
+        installTmux: !args.includes('--no-tmux'),
+        user: { mode: exists ? 'existing' : 'create', username },
+        agents,
+        domain,
+        proxyPreference: flag(args, '--proxy') === 'apache' ? 'apache' : 'nginx',
+        tls: domain !== null && !args.includes('--no-tls'),
+        email: flag(args, '--email') ?? null,
+        admin,
+    };
+}
+// ── interactive front-end ────────────────────────────────────────────────────
+async function chooseServiceUser() {
+    const mode = await p.select({
+        message: 'Which user should the ORCA services and agents run as?',
+        options: [
+            { value: 'create', label: 'Create a dedicated "orca" system user', hint: 'recommended' },
+            { value: 'existing', label: 'Use an existing user' },
+        ],
+    });
+    bail(mode);
+    const name = await p.text({
+        message: mode === 'existing' ? 'Existing username' : 'New username',
+        initialValue: mode === 'existing' ? '' : 'orca',
+        validate: (v) => (mode === 'existing' && !(v ?? '').trim() ? 'Required' : undefined),
+    });
+    bail(name);
+    return { mode: mode, username: name.trim() || 'orca' };
+}
+async function chooseAgents(r, user) {
+    const detected = await detectAgentClis(r, user);
+    const installed = detected.filter((c) => c.installed).map((c) => c.id);
+    const missing = detected.filter((c) => !c.installed);
+    if (installed.length)
+        p.log.success(`Found agent CLIs: ${installed.join(', ')}`);
+    if (!missing.length)
+        return [];
+    const pick = await p.multiselect({
+        message: 'Install missing agent CLIs? (space to toggle, enter to confirm)',
+        required: false,
+        options: missing.map((c) => ({ value: c.id, label: c.id, hint: c.pkg })),
+    });
+    if (p.isCancel(pick))
+        return [];
+    return pick;
+}
+async function chooseProxy(r) {
+    const domain = await p.text({
+        message: 'Domain for the web UI (blank to skip the reverse proxy and serve on localhost only)',
+        placeholder: 'orca.example.com',
+    });
+    bail(domain);
+    if (!domain.trim())
+        return { domain: null, proxyPreference: 'nginx', tls: false, email: null };
+    let proxyPreference = 'nginx';
+    if (!(await detectProxy(r))) {
+        const which = await p.select({
+            message: 'No reverse proxy found. Install one?',
+            options: [{ value: 'nginx', label: 'nginx', hint: 'recommended' }, { value: 'apache', label: 'apache2' }],
+        });
+        bail(which);
+        proxyPreference = which;
+    }
+    const wantTls = await p.confirm({ message: `Obtain a free HTTPS certificate for ${domain.trim()} via Let's Encrypt?` });
+    if (p.isCancel(wantTls) || !wantTls)
+        return { domain: domain.trim(), proxyPreference, tls: false, email: null };
+    const email = await p.text({ message: 'Email for renewal notices (blank to register without email)', placeholder: 'you@example.com' });
+    bail(email);
+    return { domain: domain.trim(), proxyPreference, tls: true, email: email.trim() || null };
+}
+// ── entry point ──────────────────────────────────────────────────────────────
+/** Human recap of what the wizard is about to do — shown for confirmation before anything is touched. */
+function planSummary(plan) {
+    const pad = (s) => s.padEnd(9);
+    const web = plan.domain
+        ? `${plan.proxyPreference} → ${plan.domain}${plan.tls ? ' + HTTPS (Let’s Encrypt)' : ' (HTTP only)'}`
+        : `localhost only — http://127.0.0.1:${WEB_PORT} (no reverse proxy)`;
+    return [
+        `${pad('User')}${plan.user.mode === 'create' ? `create system user "${plan.user.username}"` : `existing user "${plan.user.username}"`}`,
+        `${pad('Agents')}${plan.agents.length ? plan.agents.join(', ') : 'none (install later)'}`,
+        `${pad('tmux')}${plan.installTmux ? 'install' : 'present / skipped'}`,
+        `${pad('Web')}${web}`,
+        `${pad('Admin')}${plan.admin ? plan.admin.username : 'create interactively once the daemon is up'}`,
+    ].join('\n');
+}
+/** `orca install` — provision a fresh Debian/Ubuntu box. Run as root. Pass `--unattended` (with flags)
+ *  for a non-interactive install; otherwise an interactive wizard collects every answer. */
+export async function install(args = []) {
+    const r = realRunner();
+    const unattended = args.includes('--unattended');
+    p.intro(`🐋 orca install${unattended ? ' (unattended)' : ''}`);
+    const pf = await preflight(r);
+    const blockers = preflightBlockers(pf);
+    if (blockers.length) {
+        blockers.forEach((b) => p.log.error(b));
+        p.outro('Cannot continue.');
+        process.exit(1);
+    }
+    if (pf.tmux)
+        p.log.success('tmux present');
+    let plan;
+    if (unattended) {
+        plan = await planFromArgs(r, args);
+    }
+    else {
+        let installTmux = false;
+        if (!pf.tmux) {
+            const wantTmux = await p.confirm({ message: 'tmux is required to run agents and is not installed. Install it now?' });
+            installTmux = !p.isCancel(wantTmux) && wantTmux === true;
+            if (!installTmux)
+                p.log.warn('Continuing without tmux — agents will not run until it is installed.');
+        }
+        const user = await chooseServiceUser();
+        const agents = await chooseAgents(r, user.username);
+        const proxy = await chooseProxy(r);
+        // Admin is created via the shared wizard AFTER the daemon is up, so collect it there instead.
+        plan = { installTmux, user, agents, ...proxy, admin: null };
+    }
+    // Recap everything before touching the system — last chance to back out.
+    p.note(planSummary(plan), 'Install plan');
+    if (!unattended) {
+        const go = await p.confirm({ message: 'Proceed with installation?' });
+        if (p.isCancel(go) || !go) {
+            p.cancel('Nothing was changed.');
+            process.exit(0);
+        }
+    }
+    await execute(r, plan);
+    // Interactive: now that the daemon is live, run the shared first-run wizard for the admin + LLM.
+    let adminUser = plan.admin?.username ?? null;
+    if (!unattended) {
+        p.log.step('Create the first admin account');
+        const creds = await runSetupWizard(base);
+        if (creds) {
+            adminUser = creds.username;
+            await step('Verifying login', () => loginSmokeTest(creds.username, creds.password));
+        }
+    }
+    const url = plan.domain ? (plan.tls ? `https://${plan.domain}` : `http://${plan.domain}`) : `http://127.0.0.1:${WEB_PORT}`;
+    const summary = [
+        `Open       ${url}`,
+        adminUser ? `Sign in    ${adminUser}` : 'Sign in    create an admin in the web UI',
+        `Status     systemctl status orca-daemon orca-web`,
+        `Logs       journalctl -u orca-daemon -f`,
+        `Restart    systemctl restart orca-daemon orca-web`,
+    ].join('\n');
+    p.note(summary, 'ORCA is ready 🐋');
+    p.outro(`Done — ORCA is live at ${url}`);
+}

package/dist/cli/install/preflight.js

@@ -0,0 +1,25 @@
+const MIN_NODE_MAJOR = 22;
+export async function preflight(r) {
+    const id = await r.exec('id', ['-u']);
+    const node = await r.exec('node', ['-v']);
+    const version = node.stdout.trim();
+    const major = Number(version.replace(/^v/, '').split('.')[0]) || 0;
+    return {
+        isRoot: id.stdout.trim() === '0',
+        pkgManager: (await r.which('apt-get')) ? 'apt' : null,
+        node: { ok: major >= MIN_NODE_MAJOR, version },
+        tmux: (await r.which('tmux')) !== null,
+    };
+}
+/** Hard blockers (must be empty to proceed). tmux is NOT a blocker — the wizard offers to apt-install
+ *  it — so it isn't listed here. */
+export function preflightBlockers(p) {
+    const out = [];
+    if (!p.isRoot)
+        out.push('Must run as root — try: sudo orca install');
+    if (!p.pkgManager)
+        out.push('Unsupported OS: orca install needs apt (Debian/Ubuntu) in this version');
+    if (!p.node.ok)
+        out.push(`Node ${MIN_NODE_MAJOR}+ required (found ${p.node.version || 'none'})`);
+    return out;
+}

package/dist/cli/install/proxy.js

@@ -0,0 +1,56 @@
+/** Which reverse proxy is installed, preferring nginx. null when neither — the wizard then offers to
+ *  apt-install one. */
+export async function detectProxy(r) {
+    if (await r.which('nginx'))
+        return 'nginx';
+    if (await r.which('apache2'))
+        return 'apache';
+    return null;
+}
+/** nginx vhost. `proxy_buffering off` + a long read timeout keep the SSE event stream (`/events`,
+ *  proxied via the web's `/api`) flowing instead of being buffered/idle-closed. certbot --nginx
+ *  rewrites this to add the :443 server and the HTTP→HTTPS redirect. */
+export function nginxVhost(domain, webPort) {
+    return `server {
+    listen 80;
+    listen [::]:80;
+    server_name ${domain};
+
+    location / {
+        proxy_pass http://127.0.0.1:${webPort};
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "";
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+    }
+}
+`;
+}
+/** apache vhost. Needs mod_proxy + mod_proxy_http (the wizard enables them). certbot --apache adds TLS. */
+export function apacheVhost(domain, webPort) {
+    return `<VirtualHost *:80>
+    ServerName ${domain}
+    ProxyPreserveHost On
+    ProxyPass / http://127.0.0.1:${webPort}/
+    ProxyPassReverse / http://127.0.0.1:${webPort}/
+    # SSE: do not buffer the event stream
+    SetEnv proxy-sendchunked 1
+    ProxyTimeout 3600
+</VirtualHost>
+`;
+}
+/** certbot invocation for the chosen plugin: obtain + install the cert and add an HTTP→HTTPS redirect,
+ *  non-interactively. With an email it registers normally; without, registers email-less. */
+export function certbotCommand(kind, domain, email) {
+    const plugin = kind === 'nginx' ? '--nginx' : '--apache';
+    const reg = email ? ['-m', email] : ['--register-unsafely-without-email'];
+    return {
+        cmd: 'certbot',
+        args: [plugin, '-d', domain, '--redirect', ...reg, '--agree-tos', '--non-interactive'],
+    };
+}

package/dist/cli/install/runner.js

@@ -0,0 +1,28 @@
+import { execFile } from 'node:child_process';
+import { writeFile, access } from 'node:fs/promises';
+export function realRunner() {
+    const run = (cmd, args, input) => new Promise((resolve) => {
+        const child = execFile(cmd, args, { maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0;
+            resolve({ code, stdout: stdout?.toString() ?? '', stderr: stderr?.toString() ?? '' });
+        });
+        if (input !== undefined) {
+            child.stdin?.end(input);
+        }
+    });
+    return {
+        exec: (cmd, args, opts) => opts?.user
+            // -H so $HOME is the target user's (agent CLIs read ~/.config etc); login shell for full PATH.
+            ? run('sudo', ['-u', opts.user, '-H', 'bash', '-lc', [cmd, ...args].map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')], opts.input)
+            : run(cmd, args, opts?.input),
+        which: async (cmd, asUser) => {
+            const r = asUser
+                ? await run('sudo', ['-u', asUser, '-H', 'bash', '-lc', `command -v '${cmd}'`])
+                : await run('bash', ['-lc', `command -v '${cmd}'`]);
+            const out = r.stdout.trim();
+            return r.code === 0 && out ? out : null;
+        },
+        writeFile: (path, content) => writeFile(path, content, 'utf8'),
+        exists: (path) => access(path).then(() => true, () => false),
+    };
+}

package/dist/cli/install/serviceUser.js

@@ -0,0 +1,27 @@
+/** HOME directory of a user from getent, or null when the user doesn't exist. */
+export async function userHome(r, username) {
+    const res = await r.exec('getent', ['passwd', username]);
+    if (res.code !== 0)
+        return null;
+    const home = res.stdout.trim().split(':')[5];
+    return home || null;
+}
+/** Create the service user (idempotent) or validate the chosen existing one, returning its resolved
+ *  username + HOME. A created user is a `--system` account with its own HOME and a real shell (so
+ *  `sudo -u … -H bash -lc` gives the agent CLIs a normal environment). */
+export async function ensureServiceUser(r, choice) {
+    const existingHome = await userHome(r, choice.username);
+    if (choice.mode === 'existing') {
+        if (!existingHome)
+            throw new Error(`user '${choice.username}' does not exist`);
+        return { username: choice.username, home: existingHome };
+    }
+    if (!existingHome) {
+        const home = `/var/lib/${choice.username}`;
+        const res = await r.exec('useradd', ['--system', '--create-home', '--home-dir', home, '--shell', '/bin/bash', choice.username]);
+        if (res.code !== 0)
+            throw new Error(`useradd failed: ${res.stderr.trim() || res.code}`);
+        return { username: choice.username, home };
+    }
+    return { username: choice.username, home: existingHome };
+}

package/dist/cli/install/systemdUnits.js

@@ -0,0 +1,47 @@
+/** Pure renderers for the two systemd unit files `orca install` writes. Kept string-only and
+ *  side-effect-free so they're unit-tested without touching /etc; the wizard writes + enables them. */
+const BASE_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
+export function daemonUnit(p) {
+    return `[Unit]
+Description=ORCA daemon (REST API)
+After=network.target
+
+[Service]
+Type=simple
+User=${p.user}
+Environment=ORCA_CLI=orca
+Environment=ORCA_DB=${p.home}/.config/orca/orca.db
+Environment=ORCA_LOG_DIR=${p.home}/.config/orca/logs
+Environment=ORCA_PORT=${p.daemonPort}
+Environment=ORCA_HOST=127.0.0.1
+Environment=PATH=${p.npmGlobalBin}:${BASE_PATH}
+ExecStart=${p.nodePath} ${p.daemonEntry}
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+export function webUnit(p) {
+    return `[Unit]
+Description=ORCA web UI
+After=network.target orca-daemon.service
+Wants=orca-daemon.service
+
+[Service]
+Type=simple
+User=${p.user}
+Environment=PORT=${p.webPort}
+Environment=HOSTNAME=127.0.0.1
+Environment=ORCA_DAEMON_URL=http://127.0.0.1:${p.daemonPort}
+Environment=ORCA_LOG_DIR=${p.home}/.config/orca/logs
+Environment=PATH=${p.npmGlobalBin}:${BASE_PATH}
+ExecStart=${p.nodePath} ${p.webServer}
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+`;
+}