@nemus-cli/nemus 0.15.2 → 0.17.0

package/dist/mcp/tools.js

@@ -65,6 +65,8 @@ exports.handleSuiteExport = handleSuiteExport;
 exports.handleSuiteImport = handleSuiteImport;
 exports.handleSuiteUse = handleSuiteUse;
 exports.handleSaveContext = handleSaveContext;
+exports.handleLockWorkspace = handleLockWorkspace;
+exports.handleRestoreWorkspace = handleRestoreWorkspace;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -87,6 +89,8 @@ const branch_operations_1 = require("../utils/branch-operations");
 const cleanup_operations_1 = require("../utils/cleanup-operations");
 const hooks_1 = require("../utils/hooks");
 const validation_1 = require("../utils/validation");
+const workspace_lock_1 = require("../utils/workspace-lock");
+const restore_1 = require("../commands/restore");
 /**
  * Redirects stdout to stderr for the duration of a function call.
  * MCP uses stdout exclusively for JSON-RPC, so any console.log from
@@ -920,3 +924,60 @@ async function handleSaveContext(workspace, content, append) {
         };
     });
 }
+// ── Portable workspaces: lock / restore ─────────────────────────────────────
+/**
+ * Snapshot a workspace into a nemus.lock manifest (repos + branch + commit).
+ * Writes it to the workspace root by default and also returns the manifest so
+ * an agent can share/commit it.
+ */
+async function handleLockWorkspace(workspace, output) {
+    return withStdoutProtection(async () => {
+        if (!workspace || workspace.trim().length === 0) {
+            throw new Error('Workspace name is required');
+        }
+        const workspacePath = (0, validation_1.safeWorkspacePath)((0, validation_1.sanitizeWorkspaceName)(workspace));
+        const metadata = await (0, workspace_meta_1.loadMetadata)(workspacePath);
+        if (!metadata) {
+            throw new Error(`Workspace not found: ${workspace}`);
+        }
+        const lock = await (0, workspace_lock_1.buildLock)(workspacePath, metadata);
+        const outPath = output ? path.resolve(output) : path.join(workspacePath, workspace_lock_1.LOCK_FILENAME);
+        await (0, workspace_lock_1.writeLock)(outPath, lock);
+        return {
+            workspace: metadata.workspaceName,
+            lockfilePath: outPath,
+            repoCount: lock.repositories.length,
+            lock,
+        };
+    });
+}
+/**
+ * Recreate a workspace from a nemus.lock. Accepts either inline `lockContent`
+ * (the manifest JSON) or a `lockfile` path (defaults to ./nemus.lock). Clones
+ * every repo and checks out the recorded branch (or exact commit with `pin`).
+ */
+async function handleRestoreWorkspace(opts) {
+    return withStdoutProtection(async () => {
+        const lock = opts.lockContent
+            ? (0, workspace_lock_1.parseLock)(opts.lockContent)
+            : await (0, workspace_lock_1.readLockFile)(path.resolve(opts.lockfile || workspace_lock_1.LOCK_FILENAME));
+        const { workspaceName, workspacePath, results } = await (0, restore_1.restoreWorkspace)(lock, {
+            workspace: opts.workspace,
+            pin: opts.pin,
+        });
+        const cloned = results.filter(r => r.status === 'success');
+        const failed = results.filter(r => r.status === 'failed');
+        return {
+            workspace: workspaceName,
+            path: workspacePath,
+            cloned: cloned.length,
+            failed: failed.length,
+            repositories: results.map(r => ({
+                name: r.repo.name,
+                directoryName: r.directoryName,
+                status: r.status,
+                ...(r.error ? { error: r.error } : {}),
+            })),
+        };
+    });
+}

package/dist/program.js

@@ -95,6 +95,9 @@ const migrate_1 = require("./commands/migrate");
 const report_bug_1 = require("./commands/report-bug");
 const completion_1 = require("./commands/completion");
 const reflect_1 = require("./commands/reflect");
+const lock_1 = require("./commands/lock");
+const restore_1 = require("./commands/restore");
+const dev_1 = require("./commands/dev");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -122,6 +125,9 @@ const reflect_1 = require("./commands/reflect");
 (0, report_bug_1.registerReportBugCommand)(exports.program);
 (0, completion_1.registerCompletionCommand)(exports.program);
 (0, reflect_1.registerReflectCommand)(exports.program);
+(0, lock_1.registerLockCommand)(exports.program);
+(0, restore_1.registerRestoreCommand)(exports.program);
+(0, dev_1.registerDevCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')

package/dist/utils/dev-orchestrator.js

@@ -0,0 +1,324 @@
+"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.PREFIX_COLORS = exports.DEFAULT_SCRIPT_ORDER = void 0;
+exports.detectPackageManager = detectPackageManager;
+exports.pickDevScript = pickDevScript;
+exports.scriptRunCommand = scriptRunCommand;
+exports.resolveDevCommand = resolveDevCommand;
+exports.assignColors = assignColors;
+exports.formatPrefix = formatPrefix;
+exports.createLineSplitter = createLineSplitter;
+exports.runDev = runDev;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const colors_1 = require("./colors");
+/** Detect a repo's package manager from its lockfile (defaults to npm). */
+function detectPackageManager(repoPath) {
+    if (fs.existsSync(path.join(repoPath, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(repoPath, 'yarn.lock')))
+        return 'yarn';
+    return 'npm';
+}
+/** Default script preference order when the user doesn't pass --script. */
+exports.DEFAULT_SCRIPT_ORDER = ['dev', 'develop', 'start', 'serve'];
+/**
+ * Pick the dev script to run from a package.json `scripts` map. If `preferred`
+ * is given and present, it wins; otherwise the first of DEFAULT_SCRIPT_ORDER
+ * that exists. Returns null when nothing matches.
+ */
+function pickDevScript(scripts, preferred) {
+    if (!scripts)
+        return null;
+    if (preferred)
+        return scripts[preferred] ? preferred : null;
+    for (const name of exports.DEFAULT_SCRIPT_ORDER) {
+        if (scripts[name])
+            return name;
+    }
+    return null;
+}
+/** The command string a package manager uses to run a script. */
+function scriptRunCommand(pm, script) {
+    // npm needs `run`; yarn/pnpm accept the bare script name.
+    return pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`;
+}
+/**
+ * Resolve the command to run for a repo. An explicit `commandOverride` always
+ * wins; otherwise we read package.json and pick a script. Returns null when the
+ * repo has nothing runnable (e.g. a library with no dev script).
+ */
+function resolveDevCommand(repoPath, opts = {}) {
+    if (opts.commandOverride) {
+        return { command: opts.commandOverride, source: 'command' };
+    }
+    const pkgPath = path.join(repoPath, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return null;
+    let scripts;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        scripts = pkg?.scripts;
+    }
+    catch {
+        return null;
+    }
+    const script = pickDevScript(scripts, opts.script);
+    if (!script)
+        return null;
+    const pm = detectPackageManager(repoPath);
+    return { command: scriptRunCommand(pm, script), source: `${pm} · ${script}` };
+}
+/** Palette used to color per-repo prefixes (cycled if there are more repos). */
+exports.PREFIX_COLORS = [
+    'cyan', 'green', 'yellow', 'magenta', 'blue', 'red', 'white',
+];
+function assignColors(names) {
+    const map = new Map();
+    names.forEach((name, i) => map.set(name, exports.PREFIX_COLORS[i % exports.PREFIX_COLORS.length]));
+    return map;
+}
+/** Build the aligned, colored `"label | "` prefix for a service's output. */
+function formatPrefix(label, width, color) {
+    return (0, colors_1.colorize)(`${label.padEnd(width)} ${(0, colors_1.colorize)('|', 'gray')}`, color);
+}
+/**
+ * Stateful line splitter: feed it chunks, it returns complete lines and holds
+ * the trailing partial until the next chunk. `flush()` yields any remainder.
+ */
+function createLineSplitter() {
+    let buffer = '';
+    return {
+        push(chunk) {
+            buffer += chunk;
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            return lines;
+        },
+        flush() {
+            if (buffer.length === 0)
+                return null;
+            const rest = buffer;
+            buffer = '';
+            return rest;
+        },
+    };
+}
+/**
+ * Start every service, multiplex their output with colored prefixes, and drive a
+ * clean shutdown on Ctrl-C. Resolves with the exit code to use (first non-zero
+ * child code, or 0) once all services have exited.
+ */
+function runDev(services, opts = {}) {
+    const out = opts.stdout ?? process.stdout;
+    const err = opts.stderr ?? process.stderr;
+    const spawnFn = opts.spawnFn ?? child_process_1.spawn;
+    const killTimeoutMs = opts.killTimeoutMs ?? 5000;
+    const kill = opts.killFn ?? killGroup;
+    const width = Math.max(...services.map(s => s.label.length), 1);
+    const colors = assignColors(services.map(s => s.label));
+    return new Promise((resolve) => {
+        const running = [];
+        let shuttingDown = false;
+        let finished = false;
+        let firstFailureCode = 0;
+        let killTimer = null;
+        let disposeSignals = () => { };
+        const writePrefixed = (sink, label, text) => {
+            const prefix = formatPrefix(label, width, colors.get(label) ?? 'white');
+            sink.write(`${prefix} ${text}\n`);
+        };
+        // SIGKILL every started service's process GROUP. Unconditional by design: a
+        // detached leader (the shell) can exit on SIGTERM while its group still has
+        // living members (e.g. a grandchild that ignores SIGTERM) — gating on the
+        // leader having exited is exactly what leaks orphans. kill(-pid) on an empty
+        // group is a harmless ESRCH.
+        //
+        // Deliberate scope: the sweep only runs as part of shutdown (Ctrl-C, or
+        // --exit-on-failure). A single service that exits on its own while others
+        // keep running is NOT swept — its stray detached grandchildren (if any) are
+        // reaped at the eventual overall shutdown, not immediately. Sweeping a live
+        // run per-exit would risk killing an unrelated process that reused the pgid.
+        const sigkillSweep = () => {
+            for (const r of running)
+                kill(r.child, 'SIGKILL');
+        };
+        const finalize = () => {
+            if (finished)
+                return;
+            finished = true;
+            if (killTimer)
+                clearTimeout(killTimer);
+            disposeSignals();
+            resolve(firstFailureCode);
+        };
+        const maybeFinish = () => {
+            if (!running.every(r => r.exited))
+                return;
+            // All direct children are gone. If we were shutting down, force-reap any
+            // orphaned group members (detached grandchildren) before finishing —
+            // otherwise we'd exit and leave them running.
+            if (shuttingDown)
+                sigkillSweep();
+            finalize();
+        };
+        const shutdown = (reason) => {
+            if (shuttingDown) {
+                // Second Ctrl-C: escalate immediately.
+                sigkillSweep();
+                return;
+            }
+            shuttingDown = true;
+            err.write(`\n${(0, colors_1.colorize)(`▸ ${reason} — stopping ${running.filter(r => !r.exited).length} service(s)…`, 'yellow')}\n`);
+            for (const r of running)
+                kill(r.child, 'SIGTERM');
+            // Backstop: SIGKILL anything still alive after the grace period, then finish.
+            killTimer = setTimeout(() => {
+                sigkillSweep();
+                finalize();
+            }, killTimeoutMs);
+            if (typeof killTimer.unref === 'function')
+                killTimer.unref();
+        };
+        disposeSignals = (opts.onSignal ?? defaultOnSignal)((sig) => shutdown(`received ${sig}`));
+        for (const service of services) {
+            const child = spawnFn(service.command.command, {
+                cwd: service.cwd,
+                shell: true,
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: process.env,
+            });
+            const rec = { service, child, exited: false, exitCode: null };
+            running.push(rec);
+            const outSplitter = createLineSplitter();
+            const errSplitter = createLineSplitter();
+            child.stdout?.setEncoding('utf-8');
+            child.stderr?.setEncoding('utf-8');
+            child.stdout?.on('data', (chunk) => {
+                for (const line of outSplitter.push(chunk))
+                    writePrefixed(out, service.label, line);
+            });
+            child.stderr?.on('data', (chunk) => {
+                for (const line of errSplitter.push(chunk))
+                    writePrefixed(err, service.label, line);
+            });
+            child.on('error', (e) => {
+                if (rec.exited)
+                    return; // 'exit' already handled this service
+                writePrefixed(err, service.label, (0, colors_1.colorize)(`failed to start: ${e.message}`, 'red'));
+                rec.exited = true;
+                rec.exitCode = 1;
+                if (firstFailureCode === 0)
+                    firstFailureCode = 1;
+                maybeFinish();
+            });
+            child.on('exit', (code, signal) => {
+                if (rec.exited)
+                    return; // 'error' already handled this service
+                for (const line of [outSplitter.flush(), errSplitter.flush()]) {
+                    if (line)
+                        writePrefixed(out, service.label, line);
+                }
+                rec.exited = true;
+                rec.exitCode = code ?? (signal ? 0 : 1);
+                const desc = signal ? `signal ${signal}` : `code ${code}`;
+                const color = code && code !== 0 ? 'red' : 'gray';
+                err.write(`${(0, colors_1.colorize)(`▸ ${service.label} exited (${desc})`, color)}\n`);
+                if (code && code !== 0 && firstFailureCode === 0)
+                    firstFailureCode = code;
+                if (!shuttingDown && opts.exitOnFailure && code && code !== 0) {
+                    shutdown(`${service.label} failed`);
+                }
+                maybeFinish();
+            });
+        }
+        if (running.length === 0)
+            finalize();
+    });
+}
+/**
+ * Kill a detached child's whole process tree.
+ *
+ * POSIX: the child is its own process-group leader (spawned detached), so
+ * `kill(-pid)` signals the entire group — the reliable way to take down
+ * shell→pm→server→… trees. Windows has no process groups or POSIX signals, so
+ * `kill(-pid)` throws; we fall back to `taskkill /T /F` to force-kill the tree
+ * (graceful SIGTERM isn't meaningful for a Windows console child tree). If even
+ * that isn't available we degrade to a single `child.kill()` (leaf only).
+ */
+function killGroup(child, signal) {
+    if (child.pid == null)
+        return;
+    if (process.platform === 'win32') {
+        // spawn() reports failures (e.g. taskkill missing → ENOENT) via an async
+        // 'error' event, not a synchronous throw, so a try/catch can't catch it — and
+        // an unhandled 'error' event would crash the process. Attach a handler that
+        // degrades to a leaf-only kill.
+        const tk = (0, child_process_1.spawn)('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+        tk.on('error', () => {
+            try {
+                child.kill();
+            }
+            catch {
+                // already gone
+            }
+        });
+        return;
+    }
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+function defaultOnSignal(handler) {
+    const onSigint = () => handler('SIGINT');
+    const onSigterm = () => handler('SIGTERM');
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    return () => {
+        process.off('SIGINT', onSigint);
+        process.off('SIGTERM', onSigterm);
+    };
+}

package/dist/utils/workspace-lock.js

@@ -0,0 +1,256 @@
+"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.LOCK_VERSION = exports.LOCK_FILENAME = void 0;
+exports.readRepoBranch = readRepoBranch;
+exports.readRepoCommit = readRepoCommit;
+exports.buildLock = buildLock;
+exports.serializeLock = serializeLock;
+exports.writeLock = writeLock;
+exports.parseLock = parseLock;
+exports.isSafeSegment = isSafeSegment;
+exports.isAllowedCloneUrl = isAllowedCloneUrl;
+exports.isSafeGitRef = isSafeGitRef;
+exports.readLockFile = readLockFile;
+exports.parseGitHost = parseGitHost;
+exports.reconstructRepo = reconstructRepo;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const GIT_TIMEOUT = 15000;
+/** Committable manifest that fully describes a workspace's repos + branch state. */
+exports.LOCK_FILENAME = 'nemus.lock';
+exports.LOCK_VERSION = 1;
+/** Read the current branch of a git repo, or undefined for a detached HEAD / error. */
+async function readRepoBranch(repoPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: repoPath,
+            timeout: GIT_TIMEOUT,
+        });
+        const branch = stdout.trim();
+        return branch && branch !== 'HEAD' ? branch : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the short HEAD SHA of a git repo, or undefined on error. */
+async function readRepoCommit(repoPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--short', 'HEAD'], {
+            cwd: repoPath,
+            timeout: GIT_TIMEOUT,
+        });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a lock manifest from a workspace's metadata, reading the live branch +
+ * commit for each successfully-cloned repo directory.
+ */
+async function buildLock(workspacePath, metadata) {
+    const repos = metadata.repositories.filter(r => r.status !== 'failed');
+    const repositories = await Promise.all(repos.map(async (r) => {
+        const repoPath = path.join(workspacePath, r.directoryName);
+        const [branch, commit] = await Promise.all([
+            readRepoBranch(repoPath),
+            readRepoCommit(repoPath),
+        ]);
+        return {
+            name: r.name,
+            owner: r.owner,
+            directoryName: r.directoryName,
+            cloneUrl: r.cloneUrl,
+            ...(branch ? { branch } : {}),
+            ...(commit ? { commit } : {}),
+        };
+    }));
+    return {
+        version: exports.LOCK_VERSION,
+        workspace: metadata.workspaceName,
+        generatedAt: new Date().toISOString(),
+        repositories,
+    };
+}
+/** Serialize a lock to canonical JSON (trailing newline). */
+function serializeLock(lock) {
+    return JSON.stringify(lock, null, 2) + '\n';
+}
+async function writeLock(filePath, lock) {
+    await fs.writeFile(filePath, serializeLock(lock), 'utf-8');
+}
+/** Parse + validate a lock manifest. Throws a helpful error on malformed input. */
+function parseLock(content) {
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch {
+        throw new Error('Not valid JSON — is this a nemus.lock file?');
+    }
+    if (!data || typeof data !== 'object') {
+        throw new Error('Lockfile is not an object');
+    }
+    const lock = data;
+    if (lock.version !== exports.LOCK_VERSION) {
+        throw new Error(`Unsupported lockfile version ${String(lock.version)} (this nemus supports version ${exports.LOCK_VERSION})`);
+    }
+    if (typeof lock.workspace !== 'string' || !lock.workspace) {
+        throw new Error('Lockfile is missing a "workspace" name');
+    }
+    if (!Array.isArray(lock.repositories)) {
+        throw new Error('Lockfile is missing a "repositories" array');
+    }
+    // A lockfile is untrusted shared input — people commit it and hand it around,
+    // then `restore` feeds these fields to git + path.join. Validate every field
+    // that reaches a side effect, not just that it's a non-empty string.
+    for (const [i, r] of lock.repositories.entries()) {
+        if (!r || typeof r !== 'object')
+            throw new Error(`repositories[${i}] is not an object`);
+        const entry = r;
+        for (const field of ['name', 'owner', 'directoryName', 'cloneUrl']) {
+            if (typeof entry[field] !== 'string' || !entry[field]) {
+                throw new Error(`repositories[${i}] is missing "${field}"`);
+            }
+        }
+        if (!isSafeSegment(entry.directoryName)) {
+            throw new Error(`repositories[${i}].directoryName "${entry.directoryName}" is not a single path segment`);
+        }
+        // owner/name are what `reconstructRepo` rebuilds the clone URL from, so they
+        // must be safe segments too — not merely non-empty.
+        if (!isSafeSegment(entry.owner)) {
+            throw new Error(`repositories[${i}].owner "${entry.owner}" is not a valid path segment`);
+        }
+        if (!isSafeSegment(entry.name)) {
+            throw new Error(`repositories[${i}].name "${entry.name}" is not a valid path segment`);
+        }
+        if (!isAllowedCloneUrl(entry.cloneUrl)) {
+            throw new Error(`repositories[${i}].cloneUrl "${entry.cloneUrl}" has no recognized git transport (expected https/ssh/git:// or user@host:path)`);
+        }
+        if (entry.branch !== undefined && (typeof entry.branch !== 'string' || !isSafeGitRef(entry.branch))) {
+            throw new Error(`repositories[${i}].branch "${entry.branch}" is not a valid git ref`);
+        }
+        if (entry.commit !== undefined && (typeof entry.commit !== 'string' || !isSafeGitRef(entry.commit))) {
+            throw new Error(`repositories[${i}].commit "${entry.commit}" is not a valid git ref`);
+        }
+    }
+    return lock;
+}
+/**
+ * A `directoryName` from a lockfile flows into `path.join(workspacePath, …)`, so
+ * it must be a single, non-traversing path segment — no separators, and not `.`
+ * or `..` — or a crafted lockfile could write repos outside the workspace.
+ */
+function isSafeSegment(name) {
+    return (name.length > 0 &&
+        !name.includes('/') &&
+        !name.includes('\\') &&
+        !name.includes('\0') &&
+        name !== '.' &&
+        name !== '..');
+}
+/**
+ * A `cloneUrl` is passed to `git clone`; without a recognized transport scheme a
+ * value like `--upload-pack=…` would be parsed as a git option. Allow only
+ * https/http/ssh/git URLs and scp-style `user@host:path` remotes.
+ */
+function isAllowedCloneUrl(url) {
+    if (/^(https?|ssh|git):\/\//i.test(url))
+        return true;
+    if (/^[^\s@/]+@[^\s@:/]+:/.test(url))
+        return true;
+    return false;
+}
+/**
+ * A `branch`/`commit` from a lockfile is handed to `git checkout`. Reject refs
+ * that could smuggle git options (leading `-`) or aren't valid refs
+ * (whitespace/control chars, the metacharacters git itself forbids, or `..`).
+ */
+function isSafeGitRef(ref) {
+    return (ref.length > 0 &&
+        !ref.startsWith('-') &&
+        // eslint-disable-next-line no-control-regex
+        !/[\s\x00-\x1f\x7f~^:?*[\\]/.test(ref) &&
+        !ref.includes('..'));
+}
+async function readLockFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return parseLock(content);
+}
+/**
+ * Extract the git host from a clone URL — supports scp-style
+ * (`git@github.com:owner/repo.git`) and URL-style
+ * (`https://github.com/owner/repo.git`, `ssh://git@host/owner/repo`).
+ * Returns undefined if it can't be determined.
+ */
+function parseGitHost(cloneUrl) {
+    const scp = cloneUrl.match(/^[^@/]+@([^:/]+):/);
+    if (scp)
+        return scp[1];
+    try {
+        const u = new URL(cloneUrl);
+        if (u.hostname)
+            return u.hostname;
+    }
+    catch {
+        // not a URL
+    }
+    return undefined;
+}
+/**
+ * Rebuild a `GitHubRepo` for cloning from a lock entry. When the host is known
+ * we synthesize both https + ssh forms for `<host>/<owner>/<name>` so
+ * `getCloneUrl` can honor the restorer's `cloneProtocol`; otherwise we fall back
+ * to the stored `cloneUrl` for both fields (clone from exactly what was locked).
+ */
+function reconstructRepo(entry) {
+    const host = parseGitHost(entry.cloneUrl);
+    const url = host ? `https://${host}/${entry.owner}/${entry.name}` : entry.cloneUrl;
+    const sshUrl = host ? `git@${host}:${entry.owner}/${entry.name}.git` : entry.cloneUrl;
+    return {
+        name: entry.name,
+        url,
+        sshUrl,
+        owner: { login: entry.owner },
+        description: '',
+        isPrivate: false,
+    };
+}