@wenrwa/marketplace-cli 0.8.7 → 0.8.9

package/dist/bridge/previewCheckout.js

@@ -0,0 +1,677 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewRunner = exports.PREVIEW_PASSTHROUGH_ENV = exports.PREVIEW_BIND_HOST = void 0;
+exports.buildPreviewEnv = buildPreviewEnv;
+exports.loopbackArgs = loopbackArgs;
+exports.machineExternalAddresses = machineExternalAddresses;
+exports.listensBeyondLoopback = listensBeyondLoopback;
+exports.parseSymrefHead = parseSymrefHead;
+exports.installCommand = installCommand;
+exports.probeOnce = probeOnce;
+/**
+ * tp-05 — Team preview checkout on the owner's HOSTED machine
+ * (docs/prd/team-preview.md module 5, ADR-0014).
+ *
+ * The owner's box runs the workspace's DEFAULT branch as a preview, with the
+ * owner's `.env`, apart from the owner's own working copy.
+ *
+ * ── What runs ───────────────────────────────────────────────────────────────
+ * Only the default branch, and never anything else. No frame carries a branch
+ * (ADR-0014's "hard truth": whoever picks the code picks what the keys do, so
+ * the checkout is pinned to what the remote calls HEAD, which only owners and
+ * managers can move by merging). The branch is asked of the REMOTE
+ * (`ls-remote --symref origin HEAD`), never of a caller.
+ *
+ * ── Where it runs ───────────────────────────────────────────────────────────
+ * `<previewsBaseDir>/<workspaceId>/{a,b}` — two separate clones, never the
+ * owner's `/data/repos/<workspaceId>` working copy, so an uncommitted edit in
+ * the working copy can never appear in the preview. Two SLOTS so an update
+ * builds beside the version that is serving: a failed build (or a new build
+ * that won't come up) leaves the last good version running.
+ *
+ * ── The env ────────────────────────────────────────────────────────────────
+ * The owner's `.env` is read from the WORKING COPY with `loadRepoEnv`, the
+ * same loader (and the same reserved-name filter) terminals use. The preview
+ * process does NOT inherit the bridge's env: that env holds HiveOp's own
+ * credentials (relay token, connect token), and the preview runs merged member
+ * code that can print `process.env`. Only a short allowlist of plain process
+ * names (PATH, HOME, locale) is passed through, then the repo `.env`, then the
+ * fixed PORT. The git credential reaches `git` only, never install/build/start.
+ *
+ * ── Processes ───────────────────────────────────────────────────────────────
+ * Every step is spawned `detached` so it leads its own process group; it is
+ * stopped by signalling exactly that group (`-pid` of the PID this module
+ * spawned). Never pkill/killall, never a name match: restarting the preview
+ * must not touch the owner's terminals. The serving PID is also written to a
+ * pidfile so a bridge restart can stop the one it left behind (again by that
+ * exact PID) instead of finding the port taken.
+ *
+ * ── One preview per box ─────────────────────────────────────────────────────
+ * There is one fixed preview port (the tp-06 forwarder forwards to it and to
+ * nothing else). A second workspace asking to start while another is serving
+ * is REFUSED (`busy_other_workspace`), never swapped in: the gateway routes a
+ * workspace's members to this port, and silently serving a different
+ * workspace's app (with that workspace's keys) to them is the one outcome that
+ * must not happen.
+ *
+ * ── Logs ────────────────────────────────────────────────────────────────────
+ * Install/build/start output goes to `<previewsBaseDir>/<workspaceId>/
+ * preview.log`, on the machine. `logs()` returns a masked tail; the backend
+ * only ever asks for it on an owner-only route.
+ *
+ * ── Loopback only (SECURITY) ───────────────────────────────────────────────
+ * Fly's 6PN is organisation-wide: an app listening on all interfaces is
+ * reachable by every other tenant's box, skipping the gateway's member check
+ * entirely. So the app is told to bind 127.0.0.1 (HOST / HOSTNAME env, plus
+ * `-H 127.0.0.1` for Next and `--host 127.0.0.1` for Vite/Astro), and once it
+ * answers, the runner tries the port on every NON-loopback address this
+ * machine has. If any of them connects, the new version is killed and the
+ * request is refused `unsupported_bind` — never served exposed.
+ *
+ * Local lane: not here at all — see previewFrames.ts (ADR-0014 scopes it out).
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const repoEnv_1 = require("./repoEnv");
+const repoCheckout_1 = require("./repoCheckout");
+const redact_1 = require("../secrets/redact");
+/** The only names a preview process takes from the bridge's own env. */
+/** The only address a preview app may listen on. */
+exports.PREVIEW_BIND_HOST = '127.0.0.1';
+exports.PREVIEW_PASSTHROUGH_ENV = ['PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'SHELL'];
+const DEFAULT_READY_TIMEOUT = { built: 120_000, dev: 300_000 };
+const DEFAULT_STEP_TIMEOUT_MS = 15 * 60_000;
+const LOG_TAIL_LINES = 200;
+const LOG_TAIL_MAX_CHARS = 16_000;
+const LOG_TAIL_READ_BYTES = 256 * 1024;
+const BRANCH_RE = /^[A-Za-z0-9._/-]{1,200}$/;
+const WORKSPACE_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+/**
+ * The preview env: allowlisted process names < the owner's repo `.env`
+ * (reserved names already removed by loadRepoEnv) < the fixed PORT.
+ * Pure, so the "bridge secrets never reach the preview" rule is testable.
+ */
+function buildPreviewEnv(baseEnv, repoEnv, port) {
+    const out = {};
+    for (const name of exports.PREVIEW_PASSTHROUGH_ENV) {
+        const v = baseEnv[name];
+        if (typeof v === 'string')
+            out[name] = v;
+    }
+    // Forced last: the repo .env can't move the port or widen the bind.
+    return { ...out, ...repoEnv, PORT: String(port), HOST: exports.PREVIEW_BIND_HOST, HOSTNAME: exports.PREVIEW_BIND_HOST };
+}
+/**
+ * Extra args that pin a known framework's server to loopback, appended after
+ * `--` to `npm run <script>`. Only for scripts whose command IS that
+ * framework's server — appending flags to an arbitrary script could break it.
+ * Anything else relies on HOST/HOSTNAME and the runtime bind check.
+ */
+function loopbackArgs(scriptCommand) {
+    const cmd = scriptCommand.trim();
+    if (/^next\s+(start|dev)(\s|$)/.test(cmd))
+        return ['-H', exports.PREVIEW_BIND_HOST];
+    if (/^(vite|astro)(\s+(preview|dev|serve))?(\s|$)/.test(cmd))
+        return ['--host', exports.PREVIEW_BIND_HOST];
+    return [];
+}
+/** Non-loopback addresses of this machine (IPv4 + IPv6, link-local scoped). */
+function machineExternalAddresses() {
+    const out = [];
+    for (const list of Object.values(os.networkInterfaces())) {
+        for (const a of list ?? []) {
+            if (a.internal)
+                continue;
+            out.push(a.family === 'IPv6' && a.scopeid ? `${a.address}%${a.scopeid}` : a.address);
+        }
+    }
+    return out;
+}
+/** True when ANY non-loopback address answers on the port, i.e. the app is exposed. */
+async function listensBeyondLoopback(port, addresses, timeoutMs = 800) {
+    const results = await Promise.all(addresses.map((host) => new Promise((resolve) => {
+        const sock = net.connect({ host, port });
+        const done = (v) => { sock.destroy(); resolve(v); };
+        sock.setTimeout(timeoutMs, () => done(false));
+        sock.once('connect', () => done(true));
+        sock.once('error', () => done(false));
+    })));
+    return results.some(Boolean);
+}
+/** `ref: refs/heads/main\tHEAD` → `main`; null when the remote names no HEAD. */
+function parseSymrefHead(lsRemoteOutput) {
+    for (const line of lsRemoteOutput.split(/\r?\n/)) {
+        const m = line.match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD$/);
+        if (m && BRANCH_RE.test(m[1]) && !m[1].includes('..'))
+            return m[1];
+    }
+    return null;
+}
+/** Which install command a checkout wants, by lockfile. */
+function installCommand(files) {
+    if (files('pnpm-lock.yaml'))
+        return ['pnpm', ['install', '--frozen-lockfile']];
+    if (files('yarn.lock'))
+        return ['yarn', ['install', '--frozen-lockfile']];
+    if (files('package-lock.json'))
+        return ['npm', ['ci']];
+    return ['npm', ['install']];
+}
+function runnerFor(files) {
+    if (files('pnpm-lock.yaml'))
+        return 'pnpm';
+    if (files('yarn.lock'))
+        return 'yarn';
+    return 'npm';
+}
+class PreviewRunner {
+    opts;
+    states = new Map();
+    /** One port, so one operation at a time across the whole box. */
+    chain = Promise.resolve();
+    orphanSwept = false;
+    constructor(opts) {
+        this.opts = {
+            previewsBaseDir: opts.previewsBaseDir,
+            workingCopyDir: opts.workingCopyDir,
+            port: opts.port,
+            baseEnv: opts.baseEnv ?? process.env,
+            readyTimeoutMs: opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT,
+            probeIntervalMs: opts.probeIntervalMs ?? 500,
+            stepTimeoutMs: opts.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS,
+            killGraceMs: opts.killGraceMs ?? 5_000,
+            externalAddresses: opts.externalAddresses ?? machineExternalAddresses,
+        };
+    }
+    /** Bring the preview up. Already serving this workspace in this mode → answered as-is. */
+    start(req) {
+        return this.serialize(async () => {
+            const mode = req.mode ?? 'built';
+            const st = this.states.get(req.workspaceId);
+            if (st && st.child && st.status !== 'stopped' && st.mode === mode && st.runningSha) {
+                return this.snapshot(req.workspaceId, { status: st.status });
+            }
+            return this.deploy(req, mode);
+        });
+    }
+    /** Fetch the default branch again and, when it moved, rebuild and swap. */
+    update(req) {
+        return this.serialize(() => this.deploy(req, req.mode ?? this.states.get(req.workspaceId)?.mode ?? 'built'));
+    }
+    stop(req) {
+        return this.serialize(async () => {
+            const st = this.states.get(req.workspaceId);
+            if (st?.child)
+                await this.killChild(st.child);
+            this.clearPidfile(req.workspaceId);
+            const mode = st?.mode ?? 'built';
+            this.states.set(req.workspaceId, { status: 'stopped', mode, builtSha: st?.builtSha });
+            return { workspaceId: req.workspaceId, status: 'stopped', mode, ...(st?.builtSha ? { builtSha: st.builtSha } : {}) };
+        });
+    }
+    /** The masked tail of this workspace's preview log. Owner-scoped by the caller. */
+    logs(req) {
+        if (!WORKSPACE_ID_RE.test(req.workspaceId))
+            return { log: '', truncated: false };
+        const file = this.logPath(req.workspaceId);
+        let text = '';
+        let truncated = false;
+        try {
+            const size = fs.statSync(file).size;
+            const start = Math.max(0, size - LOG_TAIL_READ_BYTES);
+            truncated = start > 0;
+            const fd = fs.openSync(file, 'r');
+            try {
+                const buf = Buffer.alloc(size - start);
+                fs.readSync(fd, buf, 0, buf.length, start);
+                text = buf.toString('utf8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            return { log: '', truncated: false };
+        }
+        let lines = text.split('\n');
+        if (lines.length > LOG_TAIL_LINES) {
+            lines = lines.slice(-LOG_TAIL_LINES);
+            truncated = true;
+        }
+        let out = lines.join('\n');
+        if (out.length > LOG_TAIL_MAX_CHARS) {
+            out = out.slice(-LOG_TAIL_MAX_CHARS);
+            truncated = true;
+        }
+        return { log: (0, redact_1.redact)(out), truncated };
+    }
+    status(workspaceId) {
+        return this.snapshot(workspaceId, {});
+    }
+    /** Stop every preview this runner started (bridge shutdown). Exact PIDs only. */
+    async shutdown() {
+        for (const [ws, st] of this.states) {
+            if (st.child)
+                await this.killChild(st.child);
+            this.clearPidfile(ws);
+        }
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    serialize(fn) {
+        const next = this.chain.then(fn, fn);
+        this.chain = next.catch(() => undefined);
+        return next;
+    }
+    snapshot(workspaceId, extra) {
+        const st = this.states.get(workspaceId);
+        return {
+            workspaceId,
+            status: st?.status ?? 'stopped',
+            mode: st?.mode ?? 'built',
+            ...(st?.runningSha ? { runningSha: st.runningSha } : {}),
+            ...(st?.builtSha ? { builtSha: st.builtSha } : {}),
+            ...extra,
+        };
+    }
+    wsDir(workspaceId) {
+        return path.join(this.opts.previewsBaseDir, workspaceId);
+    }
+    logPath(workspaceId) {
+        return path.join(this.wsDir(workspaceId), 'preview.log');
+    }
+    pidfilePath(workspaceId) {
+        return path.join(this.wsDir(workspaceId), 'preview.pid');
+    }
+    clearPidfile(workspaceId) {
+        try {
+            fs.rmSync(this.pidfilePath(workspaceId), { force: true });
+        }
+        catch { /* best effort */ }
+    }
+    /**
+     * A bridge restart loses `states` but not the detached server it started,
+     * which would keep the port. Stop it by the exact PID this module recorded —
+     * only if that PID still leads a process group we would have created.
+     */
+    async sweepOrphans() {
+        if (this.orphanSwept)
+            return;
+        this.orphanSwept = true;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(this.opts.previewsBaseDir);
+        }
+        catch {
+            return;
+        }
+        for (const ws of entries) {
+            if (this.states.get(ws)?.child)
+                continue;
+            const pf = this.pidfilePath(ws);
+            let pid = NaN;
+            try {
+                pid = Number(JSON.parse(fs.readFileSync(pf, 'utf8')).pid);
+            }
+            catch {
+                continue;
+            }
+            if (Number.isInteger(pid) && pid > 1) {
+                try {
+                    process.kill(-pid, 'SIGTERM');
+                }
+                catch { /* already gone */ }
+                await delay(Math.min(this.opts.killGraceMs, 2_000));
+                try {
+                    process.kill(-pid, 'SIGKILL');
+                }
+                catch { /* already gone */ }
+            }
+            this.clearPidfile(ws);
+        }
+    }
+    otherServingWorkspace(workspaceId) {
+        for (const [ws, st] of this.states) {
+            if (ws !== workspaceId && st.child && st.child.exitCode === null && st.child.signalCode === null)
+                return ws;
+        }
+        return null;
+    }
+    async deploy(req, mode) {
+        const { workspaceId } = req;
+        if (!WORKSPACE_ID_RE.test(workspaceId)) {
+            return { workspaceId, status: 'failed', mode, reason: 'git_failed', message: 'Invalid workspace.' };
+        }
+        await this.sweepOrphans();
+        if (this.otherServingWorkspace(workspaceId)) {
+            return {
+                workspaceId,
+                status: 'failed',
+                mode,
+                reason: 'busy_other_workspace',
+                message: 'Another workspace preview is running.',
+            };
+        }
+        if (!req.repoUrl) {
+            return this.fail(workspaceId, mode, 'no_repo_url', 'No repo to preview.');
+        }
+        const prev = this.states.get(workspaceId) ?? { status: 'stopped', mode };
+        const serving = !!(prev.child && prev.child.exitCode === null && prev.child.signalCode === null);
+        const targetSlot = prev.activeSlot === 'a' ? 'b' : 'a';
+        const slotDir = path.join(this.wsDir(workspaceId), targetSlot);
+        fs.mkdirSync(this.wsDir(workspaceId), { recursive: true });
+        const logFile = this.logPath(workspaceId);
+        fs.writeFileSync(logFile, `--- preview ${new Date().toISOString()} (${mode}) ---\n`);
+        this.states.set(workspaceId, { ...prev, status: serving ? prev.status : 'building', mode: prev.mode ?? mode });
+        // 1. Sync the slot to the remote's default branch. Never the working copy.
+        const sha = await this.syncSlot(slotDir, req.repoUrl, req.gitCredential, logFile);
+        if (!sha) {
+            this.states.set(workspaceId, { ...prev, status: serving ? 'running' : 'failed' });
+            return this.withServing(workspaceId, { status: 'failed', reason: 'git_failed', mode, message: 'Could not fetch the default branch.' });
+        }
+        // Nothing new to show: same sha, same mode, still serving.
+        if (serving && prev.runningSha === sha && prev.mode === mode) {
+            this.states.set(workspaceId, { ...prev, status: 'running' });
+            return this.snapshot(workspaceId, { sha });
+        }
+        const has = (name) => fs.existsSync(path.join(slotDir, name));
+        if (!has('package.json')) {
+            this.states.set(workspaceId, { ...prev, status: serving ? 'running' : 'failed' });
+            return this.withServing(workspaceId, { status: 'failed', reason: 'no_package_json', mode, sha, message: 'No package.json on the default branch.' });
+        }
+        const scripts = readScripts(path.join(slotDir, 'package.json'));
+        const runScript = mode === 'dev' ? 'dev' : 'start';
+        if (!scripts[runScript]) {
+            this.states.set(workspaceId, { ...prev, status: serving ? 'running' : 'failed' });
+            return this.withServing(workspaceId, {
+                status: 'failed', reason: 'no_start_script', mode, sha,
+                message: `No "${runScript}" script in package.json.`,
+            });
+        }
+        const env = buildPreviewEnv(this.opts.baseEnv, (0, repoEnv_1.loadRepoEnv)(this.opts.workingCopyDir(workspaceId)), this.opts.port);
+        // 2. Install, then (built) build — beside whatever is serving.
+        const [installCmd, installArgs] = installCommand(has);
+        const installed = await this.runStep(installCmd, installArgs, slotDir, env, logFile);
+        let built = installed.ok;
+        if (built && mode === 'built' && scripts.build) {
+            built = (await this.runStep(runnerFor(has), ['run', 'build'], slotDir, env, logFile)).ok;
+        }
+        if (!built) {
+            this.states.set(workspaceId, { ...prev, status: serving ? 'running' : 'build_failed' });
+            return this.withServing(workspaceId, { status: 'build_failed', mode, sha, message: 'Build failed. See the preview log.' });
+        }
+        const builtSha = sha;
+        // 3. Swap: stop the old server (exact PID), start the new one, probe.
+        if (prev.child)
+            await this.killChild(prev.child);
+        this.clearPidfile(workspaceId);
+        if (await probeOnce(this.opts.port)) {
+            // Something we did not start holds the port; a probe would lie.
+            const restored = await this.restoreSlot(workspaceId, prev, env, logFile);
+            this.states.set(workspaceId, restored ?? { status: 'failed', mode, builtSha });
+            return this.withServing(workspaceId, { status: 'failed', reason: 'port_in_use', mode, sha, builtSha, message: 'The preview port is in use.' });
+        }
+        const child = this.spawnServer(runnerFor(has), runArgs(runScript, scripts[runScript]), slotDir, env, logFile, workspaceId, targetSlot, sha);
+        const ready = await this.waitReady(child, mode);
+        if (ready && (await listensBeyondLoopback(this.opts.port, this.opts.externalAddresses()))) {
+            // SECURITY: serving this would hand the owner's app (and keys) to every
+            // tenant on the private network. Kill it and refuse, typed.
+            fs.appendFileSync(logFile, `refused: the app listens beyond ${exports.PREVIEW_BIND_HOST}\n`);
+            await this.killChild(child);
+            this.clearPidfile(workspaceId);
+            const restored = await this.restoreSlot(workspaceId, prev, env, logFile);
+            this.states.set(workspaceId, restored ? { ...restored, builtSha } : { status: 'failed', mode, builtSha });
+            return this.withServing(workspaceId, {
+                status: 'failed', reason: 'unsupported_bind', mode, sha, builtSha,
+                message: `The app must listen on ${exports.PREVIEW_BIND_HOST} only.`,
+            });
+        }
+        if (ready) {
+            this.states.set(workspaceId, { status: 'running', mode, activeSlot: targetSlot, runningSha: sha, builtSha, child });
+            return this.snapshot(workspaceId, { sha });
+        }
+        await this.killChild(child);
+        this.clearPidfile(workspaceId);
+        const restored = await this.restoreSlot(workspaceId, prev, env, logFile);
+        this.states.set(workspaceId, restored ? { ...restored, builtSha } : { status: 'start_failed', mode, builtSha });
+        return this.withServing(workspaceId, { status: 'start_failed', mode, sha, builtSha, message: 'The app did not start. See the preview log.' });
+    }
+    /** Bring the previous slot back after a failed swap, if there was one. */
+    async restoreSlot(workspaceId, prev, env, logFile) {
+        if (!prev.activeSlot || !prev.runningSha)
+            return null;
+        const dir = path.join(this.wsDir(workspaceId), prev.activeSlot);
+        const has = (name) => fs.existsSync(path.join(dir, name));
+        const script = prev.mode === 'dev' ? 'dev' : 'start';
+        fs.appendFileSync(logFile, `--- restoring ${prev.runningSha.slice(0, 7)} ---\n`);
+        const child = this.spawnServer(runnerFor(has), runArgs(script, readScripts(path.join(dir, 'package.json'))[script] ?? ''), dir, env, logFile, workspaceId, prev.activeSlot, prev.runningSha);
+        if (await this.waitReady(child, prev.mode) && !(await listensBeyondLoopback(this.opts.port, this.opts.externalAddresses()))) {
+            return { status: 'running', mode: prev.mode, activeSlot: prev.activeSlot, runningSha: prev.runningSha, builtSha: prev.builtSha, child };
+        }
+        await this.killChild(child);
+        this.clearPidfile(workspaceId);
+        return null;
+    }
+    /** The request's own verdict, plus what is actually serving now. */
+    withServing(workspaceId, r) {
+        const st = this.states.get(workspaceId);
+        const builtSha = r.builtSha ?? st?.builtSha;
+        return {
+            workspaceId,
+            ...r,
+            ...(st?.runningSha && st.child ? { runningSha: st.runningSha } : {}),
+            ...(builtSha ? { builtSha } : {}),
+        };
+    }
+    fail(workspaceId, mode, reason, message) {
+        return this.withServing(workspaceId, { status: 'failed', mode, reason, message });
+    }
+    async syncSlot(slotDir, repoUrl, cred, logFile) {
+        const gitEnv = { ...process.env, ...(0, repoCheckout_1.cloneCredentialEnv)(cred?.token ? { token: cred.token, repoFullName: cred.repoFullName } : undefined), GIT_TERMINAL_PROMPT: '0' };
+        const git = (args) => execGit(args, gitEnv);
+        try {
+            if (!fs.existsSync(path.join(slotDir, '.git'))) {
+                fs.rmSync(slotDir, { recursive: true, force: true });
+                await git(['clone', '--filter=blob:none', '--no-checkout', repoUrl, slotDir]);
+            }
+            else {
+                await git(['-C', slotDir, 'remote', 'set-url', 'origin', repoUrl]);
+            }
+            const branch = parseSymrefHead(await git(['-C', slotDir, 'ls-remote', '--symref', 'origin', 'HEAD']));
+            if (!branch)
+                throw new Error('remote has no default branch');
+            await git(['-C', slotDir, 'fetch', '--prune', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+            await git(['-C', slotDir, 'checkout', '--force', '-B', branch, `refs/remotes/origin/${branch}`]);
+            await git(['-C', slotDir, 'reset', '--hard', `refs/remotes/origin/${branch}`]);
+            // Untracked leftovers go; ignored ones (node_modules, build output) stay
+            // so an unchanged dependency set doesn't reinstall from scratch.
+            await git(['-C', slotDir, 'clean', '-ffd']);
+            const sha = (await git(['-C', slotDir, 'rev-parse', 'HEAD'])).trim();
+            fs.appendFileSync(logFile, `default branch ${branch} @ ${sha.slice(0, 12)}\n`);
+            return /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+        }
+        catch (err) {
+            fs.appendFileSync(logFile, `git: ${(0, redact_1.redact)(err instanceof Error ? err.message : String(err))}\n`);
+            return null;
+        }
+    }
+    runStep(cmd, args, cwd, env, logFile) {
+        return new Promise((resolve) => {
+            fs.appendFileSync(logFile, `$ ${cmd} ${args.join(' ')}\n`);
+            const fd = fs.openSync(logFile, 'a');
+            let child;
+            try {
+                child = (0, child_process_1.spawn)(cmd, args, { cwd, env, detached: true, stdio: ['ignore', fd, fd] });
+            }
+            catch {
+                fs.closeSync(fd);
+                resolve({ ok: false });
+                return;
+            }
+            fs.closeSync(fd);
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                void this.killChild(child);
+            }, this.opts.stepTimeoutMs);
+            child.on('error', () => {
+                clearTimeout(timer);
+                resolve({ ok: false });
+            });
+            child.on('exit', (code) => {
+                clearTimeout(timer);
+                resolve({ ok: code === 0 && !timedOut, timedOut });
+            });
+        });
+    }
+    spawnServer(cmd, args, cwd, env, logFile, workspaceId, slot, sha) {
+        fs.appendFileSync(logFile, `$ ${cmd} ${args.join(' ')} (port ${this.opts.port})\n`);
+        const fd = fs.openSync(logFile, 'a');
+        const child = (0, child_process_1.spawn)(cmd, args, { cwd, env, detached: true, stdio: ['ignore', fd, fd] });
+        fs.closeSync(fd);
+        child.on('error', () => { });
+        if (child.pid) {
+            try {
+                fs.writeFileSync(this.pidfilePath(workspaceId), JSON.stringify({ pid: child.pid, slot, sha }));
+            }
+            catch { /* best effort */ }
+        }
+        child.on('exit', () => {
+            const st = this.states.get(workspaceId);
+            if (st?.child === child) {
+                this.states.set(workspaceId, { ...st, child: undefined, status: 'stopped', runningSha: undefined });
+                this.clearPidfile(workspaceId);
+            }
+        });
+        return child;
+    }
+    async waitReady(child, mode) {
+        const deadline = Date.now() + this.opts.readyTimeoutMs[mode];
+        while (Date.now() < deadline) {
+            if (child.exitCode !== null || child.signalCode !== null || !child.pid)
+                return false;
+            if (await probeOnce(this.opts.port))
+                return child.exitCode === null && child.signalCode === null;
+            await delay(this.opts.probeIntervalMs);
+        }
+        return false;
+    }
+    /** Stop the process GROUP this module spawned — by its exact leader PID. */
+    killChild(child) {
+        const pid = child.pid;
+        if (!pid || child.exitCode !== null || child.signalCode !== null) {
+            // The leader is gone; its group may not be (npm → node). Same exact PGID.
+            if (pid) {
+                try {
+                    process.kill(-pid, 'SIGKILL');
+                }
+                catch { /* none left */ }
+            }
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                // npm may exit before its own child does — clear the rest of the group.
+                try {
+                    process.kill(-pid, 'SIGKILL');
+                }
+                catch { /* none left */ }
+                resolve();
+            };
+            child.once('exit', finish);
+            try {
+                process.kill(-pid, 'SIGTERM');
+            }
+            catch {
+                finish();
+                return;
+            }
+            const timer = setTimeout(() => {
+                try {
+                    process.kill(-pid, 'SIGKILL');
+                }
+                catch { /* gone */ }
+                setTimeout(finish, 200);
+            }, this.opts.killGraceMs);
+        });
+    }
+}
+exports.PreviewRunner = PreviewRunner;
+function runArgs(script, scriptCommand) {
+    const extra = loopbackArgs(scriptCommand);
+    return extra.length ? ['run', script, '--', ...extra] : ['run', script];
+}
+function readScripts(pkgPath) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        return pkg && typeof pkg.scripts === 'object' && pkg.scripts ? pkg.scripts : {};
+    }
+    catch {
+        return {};
+    }
+}
+function execGit(args, env) {
+    return new Promise((resolve, reject) => {
+        (0, child_process_1.execFile)('git', args, { env, maxBuffer: 4 * 1024 * 1024, timeout: 5 * 60_000 }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error(`git ${args.filter((a) => !a.includes('://')).slice(0, 4).join(' ')}: ${String(stderr || err.message).trim()}`));
+            else
+                resolve(String(stdout));
+        });
+    });
+}
+/** Any HTTP answer on 127.0.0.1:port counts as "up". */
+function probeOnce(port, timeoutMs = 1_500) {
+    return new Promise((resolve) => {
+        const req = http.get({ host: '127.0.0.1', port, path: '/', timeout: timeoutMs }, (res) => {
+            res.resume();
+            resolve(true);
+        });
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+        req.on('error', () => resolve(false));
+    });
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}