@nemus-cli/nemus 0.15.2 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-09
+
+### Added
+
+- **`nemus dev` — multi-repo dev orchestrator.** Start every repo's dev server in
+  a workspace at once and stream their output into one terminal with a
+  color-coded, aligned per-repo prefix; a single Ctrl-C tears them all down
+  cleanly. Each service runs in its own process group and shutdown SIGTERMs the
+  group then SIGKILLs stragglers after `--kill-timeout` (default 5s), so child
+  process trees (a dev server's own subprocesses) are never orphaned. For each
+  repo it runs `--command "<cmd>"` if given, else the first `package.json` script
+  that exists (`--script` → `dev` → `develop` → `start` → `serve`) using the
+  repo's own package manager (pnpm/yarn/npm from its lockfile); repos with no
+  runnable script are skipped with a notice. Flags: `--only <repos>`,
+  `--script`, `--command`, `--exit-on-failure`, `--kill-timeout`.
+
+## [0.16.0] - 2026-09-09
+
+### Added
+
+- **Portable workspaces: `nemus lock` & `nemus restore`.** `nemus lock` writes a
+  small, committable `nemus.lock` capturing every repo (owner, directory, clone
+  URL), the branch each repo is currently on, and its HEAD commit; `-o <file>`
+  writes elsewhere and `-o -` prints it to stdout. `nemus restore` recreates the
+  workspace from a lockfile (defaults to `./nemus.lock`, or `-` for stdin) on any
+  machine — it clones every repo and checks out the recorded branch, then writes
+  metadata + agent context exactly like `create`. `--pin` checks out the exact
+  recorded commit instead of the branch tip, and `-w/--workspace` overrides the
+  name baked into the lockfile. `nemus lock --all` drops a lockfile into every
+  workspace at once (skipping existing ones unless `--force`) — the explicit way
+  to make a whole machine portable, rather than a hidden side effect in
+  `migrate`. The MCP server gains matching `lock-workspace` / `restore-workspace`
+  tools (restore accepts the manifest inline via `lockContent`) so agents have
+  the same portability as `create`/`update`/`delete`. Restore rebuilds https/ssh URLs for the
+  restorer's `cloneProtocol` from the locked host+owner+name (falling back to the
+  stored URL), so an ssh-locked workspace restores fine for an https user. The
+  lockfile holds only what `git remote -v` already exposes — no secrets — so it's
+  safe to commit. Unlike a local `snapshot` (time-travel within an existing
+  workspace) or a `suite` (reusable repo template), a lockfile pins one
+  workspace's exact repos + branch state and recreates it from nothing.
+
 ## [0.15.2] - 2026-09-04
 
 ### Fixed

package/README.md

@@ -240,9 +240,42 @@ nemus status my-workspace     # (st) git status for every repo
 nemus sync my-workspace       # (s) git pull every repo (auto-retries on flaky network)
 nemus diff my-workspace       # (d) combined diff summary  (--full for raw diffs)
 nemus run my-workspace "npm install"   # (r) run a command in every repo
+nemus dev my-workspace        # start every repo's dev server together (one Ctrl-C stops all)
 nemus doctor my-workspace     # (doc) health checks + score
 ```
 
+### `nemus dev` — run all your services together
+
+A workspace is usually a set of services you run *together*. `nemus dev` starts
+each repo's dev server at once and streams their output into one terminal with a
+color-coded, aligned per-repo prefix; a single Ctrl-C tears them all down cleanly
+(process-group kill, so child trees die too).
+
+```bash
+nemus dev                     # start every runnable repo in the current workspace
+nemus dev payments --only web,api      # just a subset
+nemus dev payments --script start       # prefer a specific npm script
+nemus dev payments --command "make run"  # run an exact command in every repo
+nemus dev payments --exit-on-failure     # stop everything if any service crashes
+```
+
+```
+web      | VITE ready in 412 ms
+api      | listening on :4000
+worker   | [queue] connected
+```
+
+For each repo it runs `--command` if given, else the first `package.json` script
+that exists (`--script` → `dev` → `develop` → `start` → `serve`), using the
+repo's own package manager (pnpm/yarn/npm from its lockfile). Repos with no
+runnable script are skipped with a notice, so a library in the workspace won't
+block the services.
+
+> On **macOS/Linux** each service runs in its own process group, so shutdown
+> reliably takes down the whole child tree. On **Windows** there are no POSIX
+> process groups; teardown falls back to `taskkill /T /F` (force-kill the tree,
+> no graceful SIGTERM phase).
+
 ```
 Repo             Branch       Status        Ahead/Behind   Modified
 ─────────────────────────────────────────────────────────────────────
@@ -354,6 +387,34 @@ nemus snapshot save ws        # (ss) capture exact branches/commits/dirty state
 nemus snapshot restore <id>   # (sr)
 ```
 
+### Portable workspaces — `lock` & `restore`
+
+Share the *exact* workspace you're in. `nemus lock` writes a small, committable
+`nemus.lock` (repos + owner + the branch each repo is on + its HEAD commit);
+`nemus restore` recreates that workspace from scratch on any machine — clones
+every repo and checks out the recorded branch.
+
+```bash
+nemus lock                    # write ./nemus.lock for the current workspace
+nemus lock my-ws -o my-ws.lock   # or a named workspace, to a file
+nemus lock my-ws -o -            # print the lockfile to stdout (pipe it anywhere)
+nemus lock --all [--force]     # drop a nemus.lock into every workspace at once
+
+nemus restore                 # recreate from ./nemus.lock
+nemus restore my-ws.lock       # from a specific file (or `-` to read stdin)
+nemus restore my-ws.lock -w exp --pin   # new name; pin exact commits, not branch tips
+```
+
+Commit `nemus.lock` next to a design doc or drop it in a ticket, and a teammate
+runs `nemus restore` to land in the identical multi-repo setup. It contains only
+what `git remote -v` already exposes — no secrets — so it's safe to commit.
+
+> **`lock`/`restore` vs. `snapshot`:** a *snapshot* is local time-travel for a
+> workspace that already exists on your machine; `lock`/`restore` is portable —
+> it recreates the workspace (repos and all) from nothing, on any machine.
+> **vs. `suite`:** a *suite* is a reusable repo *template*; a lockfile pins one
+> workspace's *exact* repos and branch state.
+
 ### Reflect — improve your setup over time
 
 ```bash

package/dist/commands/dev.js

@@ -0,0 +1,118 @@
+"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.registerDevCommand = registerDevCommand;
+const path = __importStar(require("path"));
+const config_1 = require("../utils/config");
+const workspace_meta_1 = require("../utils/workspace-meta");
+const command_helpers_1 = require("../utils/command-helpers");
+const dev_orchestrator_1 = require("../utils/dev-orchestrator");
+const logger_1 = require("../utils/logger");
+const colors_1 = require("../utils/colors");
+function registerDevCommand(parent) {
+    parent
+        .command('dev [workspace]')
+        .description('Start every repo\'s dev server together, with unified color-coded logs (Ctrl-C stops all)')
+        .option('--only <repos>', 'Comma-separated subset of repos to start')
+        .option('--script <name>', 'npm script to prefer (default: dev → develop → start → serve)')
+        .option('--command <cmd>', 'Run this exact command in every selected repo instead of a script')
+        .option('--exit-on-failure', 'Tear everything down if any service exits non-zero')
+        .option('--kill-timeout <seconds>', 'Grace period before SIGKILL on shutdown', '5')
+        .action(async (workspace, opts, cmd) => {
+        const globalOpts = (0, command_helpers_1.getGlobalOpts)(cmd);
+        await handleDev({ workspace, ...opts, ...globalOpts });
+    });
+}
+async function handleDev(opts) {
+    try {
+        const workspaceName = await (0, command_helpers_1.resolveWorkspace)(opts.workspace);
+        const workspacePath = path.join(config_1.WORKSPACES_DIR, workspaceName);
+        const metadata = await (0, workspace_meta_1.loadMetadata)(workspacePath);
+        if (!metadata) {
+            (0, logger_1.logError)(`Workspace not found: ${workspaceName}`);
+            process.exit(1);
+        }
+        let repos = metadata.repositories.filter(r => r.status === 'success');
+        if (opts.only) {
+            const wanted = new Set((0, command_helpers_1.parseList)(opts.only));
+            repos = repos.filter(r => wanted.has(r.directoryName) || wanted.has(r.name));
+            if (repos.length === 0) {
+                (0, logger_1.logError)(`No repos in "${workspaceName}" matched --only ${opts.only}`);
+                process.exit(1);
+            }
+        }
+        const services = [];
+        const skipped = [];
+        for (const repo of repos) {
+            const cwd = path.join(workspacePath, repo.directoryName);
+            const command = (0, dev_orchestrator_1.resolveDevCommand)(cwd, { commandOverride: opts.command, script: opts.script });
+            if (!command) {
+                skipped.push(repo.directoryName);
+                continue;
+            }
+            services.push({ label: repo.directoryName, cwd, command });
+        }
+        if (services.length === 0) {
+            (0, logger_1.logError)(`Nothing to run in "${workspaceName}".`);
+            (0, logger_1.logInfo)(opts.script
+                ? `No repo has a "${opts.script}" script.`
+                : 'No repo has a dev/develop/start/serve script. Pass --command "<cmd>" to run something explicitly.');
+            process.exit(1);
+        }
+        if (skipped.length > 0) {
+            (0, logger_1.logWarning)(`Skipped (no runnable script): ${skipped.join(', ')}`);
+        }
+        console.log('\n' + (0, colors_1.colorize)('Starting dev servers', 'bright') + (0, colors_1.colorize)(` · ${workspaceName}`, 'cyan'));
+        for (const s of services) {
+            console.log(`  ${(0, colors_1.colorize)(s.label, 'cyan')}  ${(0, colors_1.colorize)(s.command.command, 'gray')} ${(0, colors_1.colorize)(`(${s.command.source})`, 'gray')}`);
+        }
+        console.log((0, colors_1.colorize)('  Ctrl-C to stop all.\n', 'gray'));
+        // NaN check (not `|| 5`) so an explicit --kill-timeout 0 (immediate SIGKILL)
+        // is honored rather than coerced back to the default.
+        const parsedTimeout = Number(opts.killTimeout);
+        const killTimeoutMs = Math.max(0, Number.isFinite(parsedTimeout) ? parsedTimeout : 5) * 1000;
+        const code = await (0, dev_orchestrator_1.runDev)(services, {
+            exitOnFailure: opts.exitOnFailure,
+            killTimeoutMs,
+        });
+        process.exit(code);
+    }
+    catch (error) {
+        (0, logger_1.logError)('Failed to start dev servers');
+        if (error instanceof Error)
+            (0, logger_1.logError)(error.message);
+        process.exit(1);
+    }
+}

package/dist/commands/lock.js

@@ -0,0 +1,148 @@
+"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.registerLockCommand = registerLockCommand;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs/promises"));
+const config_1 = require("../utils/config");
+const workspace_meta_1 = require("../utils/workspace-meta");
+const command_helpers_1 = require("../utils/command-helpers");
+const workspace_lock_1 = require("../utils/workspace-lock");
+const logger_1 = require("../utils/logger");
+const colors_1 = require("../utils/colors");
+function registerLockCommand(parent) {
+    parent
+        .command('lock [workspace]')
+        .description('Snapshot a workspace into a committable nemus.lock (repos + branches)')
+        .option('-o, --output <file>', 'Write the lockfile to <file> ("-" for stdout) instead of the workspace root')
+        .option('--all', 'Write a nemus.lock into every workspace (skips ones that already have one)')
+        .option('--force', 'With --all, overwrite an existing nemus.lock')
+        .action(async (workspace, opts, cmd) => {
+        const globalOpts = (0, command_helpers_1.getGlobalOpts)(cmd);
+        await handleLock({ workspace, ...opts, ...globalOpts });
+    });
+}
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function handleLock(opts) {
+    if (opts.all) {
+        await handleLockAll(opts);
+        return;
+    }
+    try {
+        const workspaceName = await (0, command_helpers_1.resolveWorkspace)(opts.workspace);
+        const workspacePath = path.join(config_1.WORKSPACES_DIR, workspaceName);
+        const metadata = await (0, workspace_meta_1.loadMetadata)(workspacePath);
+        if (!metadata) {
+            (0, logger_1.logError)(`Workspace not found: ${workspaceName}`);
+            process.exit(1);
+        }
+        const lock = await (0, workspace_lock_1.buildLock)(workspacePath, metadata);
+        // `-o -`: emit only the lockfile JSON so it can be piped/redirected cleanly.
+        if (opts.output === '-') {
+            process.stdout.write((0, workspace_lock_1.serializeLock)(lock));
+            return;
+        }
+        const outPath = opts.output
+            ? path.resolve(opts.output)
+            : path.join(workspacePath, workspace_lock_1.LOCK_FILENAME);
+        await (0, workspace_lock_1.writeLock)(outPath, lock);
+        (0, logger_1.logSuccess)(`Wrote ${(0, colors_1.colorize)(workspace_lock_1.LOCK_FILENAME, 'cyan')} (${lock.repositories.length} repos) → ${outPath}`);
+        (0, logger_1.logInfo)('Commit or share it, then recreate the workspace with: nemus restore');
+    }
+    catch (error) {
+        (0, logger_1.logError)(error instanceof Error ? error.message : 'Failed to write lockfile');
+        process.exit(1);
+    }
+}
+/**
+ * Bulk mode: drop a nemus.lock into every workspace so a whole machine's
+ * workspaces become portable in one shot. Existing lockfiles are left alone
+ * (they may be hand-edited / committed) unless --force is given — this is the
+ * explicit, discoverable alternative to burying a snapshot side effect inside
+ * `migrate`, which is meant to be re-run freely.
+ */
+async function handleLockAll(opts) {
+    if (opts.output) {
+        (0, logger_1.logError)('--all writes one nemus.lock per workspace and cannot be combined with --output.');
+        process.exit(1);
+    }
+    const workspaces = await (0, workspace_meta_1.listWorkspaces)(false);
+    if (workspaces.length === 0) {
+        (0, logger_1.logInfo)('No workspaces found. Nothing to lock.');
+        return;
+    }
+    let written = 0;
+    let skipped = 0;
+    let errors = 0;
+    for (const ws of workspaces) {
+        const metadata = ws.metadata ?? (await (0, workspace_meta_1.loadMetadata)(ws.path));
+        if (!metadata) {
+            (0, logger_1.logWarning)(`  ${ws.name}: no metadata — skipped (run 'nemus migrate' first)`);
+            skipped++;
+            continue;
+        }
+        const outPath = path.join(ws.path, workspace_lock_1.LOCK_FILENAME);
+        if (!opts.force && (await fileExists(outPath))) {
+            (0, logger_1.logInfo)(`  ${(0, colors_1.colorize)(ws.name, 'cyan')}: ${workspace_lock_1.LOCK_FILENAME} already exists — skipped (use --force to overwrite)`);
+            skipped++;
+            continue;
+        }
+        try {
+            const lock = await (0, workspace_lock_1.buildLock)(ws.path, metadata);
+            await (0, workspace_lock_1.writeLock)(outPath, lock);
+            (0, logger_1.logSuccess)(`  ${(0, colors_1.colorize)(ws.name, 'cyan')}: wrote ${workspace_lock_1.LOCK_FILENAME} (${lock.repositories.length} repos)`);
+            written++;
+        }
+        catch (error) {
+            (0, logger_1.logError)(`  ${ws.name}: ${error instanceof Error ? error.message : 'failed to write lockfile'}`);
+            errors++;
+        }
+    }
+    console.log('');
+    (0, logger_1.logInfo)('Bulk lock complete:');
+    console.log(`  ${(0, colors_1.colorize)(String(written), 'green')} written`);
+    if (skipped > 0)
+        console.log(`  ${(0, colors_1.colorize)(String(skipped), 'yellow')} skipped`);
+    if (errors > 0)
+        console.log(`  ${(0, colors_1.colorize)(String(errors), 'red')} errors`);
+}

package/dist/commands/restore.js

@@ -0,0 +1,232 @@
+"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.registerRestoreCommand = registerRestoreCommand;
+exports.restoreWorkspace = restoreWorkspace;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const path = __importStar(require("path"));
+const command_helpers_1 = require("../utils/command-helpers");
+const workspace_lock_1 = require("../utils/workspace-lock");
+const git_operations_1 = require("../utils/git-operations");
+const ghq_integration_1 = require("../utils/ghq-integration");
+const workspace_meta_1 = require("../utils/workspace-meta");
+const claude_integration_1 = require("../utils/claude-integration");
+const github_1 = require("../utils/github");
+const validation_1 = require("../utils/validation");
+const logger_1 = require("../utils/logger");
+const colors_1 = require("../utils/colors");
+const banner_1 = require("../utils/banner");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const GIT_TIMEOUT = 30000;
+function registerRestoreCommand(parent) {
+    parent
+        .command('restore [lockfile]')
+        .description('Recreate a workspace from a nemus.lock (defaults to ./nemus.lock, "-" for stdin)')
+        .option('-w, --workspace <name>', 'Override the workspace name baked into the lockfile')
+        .option('--pin', 'Check out the exact recorded commit instead of the branch tip')
+        .action(async (lockfile, opts, cmd) => {
+        const globalOpts = (0, command_helpers_1.getGlobalOpts)(cmd);
+        await handleRestore({ lockfile, ...opts, ...globalOpts });
+    });
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+}
+// `branch`/`commit` come from an untrusted lockfile (already ref-validated in
+// parseLock); the `--end-of-options` guard is defense-in-depth so a ref can
+// never be reparsed as a git option even if validation is bypassed.
+/** Check out `branch` in a freshly-cloned repo, creating a tracking branch if needed. */
+async function checkoutBranch(repoPath, branch) {
+    try {
+        await execFileAsync('git', ['checkout', '--end-of-options', branch], { cwd: repoPath, timeout: GIT_TIMEOUT });
+        return true;
+    }
+    catch {
+        try {
+            await execFileAsync('git', ['checkout', '-b', branch, '--end-of-options', `origin/${branch}`], { cwd: repoPath, timeout: GIT_TIMEOUT });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+async function checkoutCommit(repoPath, commit) {
+    try {
+        await execFileAsync('git', ['checkout', '--end-of-options', commit], { cwd: repoPath, timeout: GIT_TIMEOUT });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Core restore: clone every repo in a (already-validated) lock and check out the
+ * recorded branch (or the exact commit with `pin`), then write metadata + agent
+ * context — exactly like `create`. Throws on fatal errors (no process.exit) and
+ * logs progress via the logger (stderr), so both the CLI and the MCP tool can
+ * call it. Callers own presentation (final message, shell-CD hook).
+ */
+async function restoreWorkspace(lock, opts = {}) {
+    if (lock.repositories.length === 0) {
+        throw new Error('Lockfile has no repositories to restore');
+    }
+    // Resolve the target workspace name
+    let workspaceName = (0, validation_1.sanitizeWorkspaceName)(opts.workspace || lock.workspace);
+    const nameError = (0, validation_1.validateWorkspaceName)(workspaceName);
+    if (nameError !== true) {
+        throw new Error(typeof nameError === 'string' ? nameError : 'Invalid workspace name');
+    }
+    if (await (0, validation_1.checkWorkspaceExists)(workspaceName)) {
+        const resolved = await (0, validation_1.resolveWorkspaceNameConflict)(workspaceName, lock.repositories.map(r => r.directoryName));
+        (0, logger_1.logInfo)(`Workspace "${workspaceName}" already exists — using "${(0, colors_1.colorize)(resolved, 'cyan')}" instead.`);
+        workspaceName = resolved;
+    }
+    const workspacePath = (0, validation_1.safeWorkspacePath)(workspaceName);
+    (0, logger_1.logInfo)(`Restoring ${(0, colors_1.colorize)(String(lock.repositories.length), 'cyan')} repos into workspace "${(0, colors_1.colorize)(workspaceName, 'cyan')}"`);
+    // Clone every repo (reuses the create pipeline: ghq, concurrency, dedup)
+    (0, logger_1.logStep)(1, 3, 'Cloning repositories...');
+    const { mkdir } = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+    await mkdir(workspacePath, { recursive: true });
+    await (0, ghq_integration_1.warnIfGhqMissing)();
+    const entries = lock.repositories.map(r => ({
+        repo: (0, workspace_lock_1.reconstructRepo)(r),
+        directoryName: r.directoryName,
+    }));
+    const results = await (0, git_operations_1.cloneRepositories)(entries, workspacePath);
+    (0, git_operations_1.reportCloneResults)(results);
+    // Check out the recorded branch (or pinned commit) per repo
+    (0, logger_1.logStep)(2, 3, opts.pin ? 'Checking out pinned commits...' : 'Checking out recorded branches...');
+    const byDir = new Map(lock.repositories.map(r => [r.directoryName, r]));
+    for (const result of results) {
+        if (result.status !== 'success')
+            continue;
+        const entry = byDir.get(result.directoryName);
+        if (!entry)
+            continue;
+        const repoPath = path.join(workspacePath, result.directoryName);
+        const display = (0, colors_1.colorize)(result.directoryName, 'cyan');
+        if (opts.pin && entry.commit) {
+            if (!(await checkoutCommit(repoPath, entry.commit))) {
+                (0, logger_1.logWarning)(`${display}: could not check out pinned commit ${entry.commit} — left on the default branch`);
+            }
+        }
+        else if (entry.branch) {
+            if (await checkoutBranch(repoPath, entry.branch)) {
+                (0, logger_1.logInfo)(`${display} → ${entry.branch}`);
+            }
+            else if (entry.commit && (await checkoutCommit(repoPath, entry.commit))) {
+                (0, logger_1.logWarning)(`${display}: branch "${entry.branch}" not found — checked out commit ${entry.commit} instead`);
+            }
+            else {
+                (0, logger_1.logWarning)(`${display}: could not check out "${entry.branch}" — left on the default branch`);
+            }
+        }
+        else if (entry.commit) {
+            // No branch was recorded (detached HEAD at lock time) — restore the commit
+            // so that state isn't silently lost even without --pin.
+            if (await checkoutCommit(repoPath, entry.commit)) {
+                (0, logger_1.logInfo)(`${display} → ${entry.commit} (detached)`);
+            }
+            else {
+                (0, logger_1.logWarning)(`${display}: could not check out commit ${entry.commit} — left on the default branch`);
+            }
+        }
+    }
+    // Metadata + agent context (same as create)
+    (0, logger_1.logStep)(3, 3, 'Saving workspace metadata...');
+    const metadata = (0, workspace_meta_1.createMetadata)(workspaceName, results, { prompt: `Restored from ${workspace_lock_1.LOCK_FILENAME}` });
+    await (0, workspace_meta_1.saveMetadata)(workspacePath, metadata);
+    const successfulRepos = results.filter(r => r.status === 'success').map(r => r.repo);
+    if (successfulRepos.length > 0) {
+        await (0, claude_integration_1.generateClaudeContext)(workspacePath, workspaceName, successfulRepos, metadata);
+    }
+    return { workspaceName, workspacePath, results };
+}
+async function handleRestore(opts) {
+    (0, banner_1.printBanner)();
+    try {
+        // Step 1: Load + validate the lockfile
+        let lock;
+        if (opts.lockfile === '-') {
+            lock = (0, workspace_lock_1.parseLock)(await readStdin());
+        }
+        else {
+            const lockPath = path.resolve(opts.lockfile || workspace_lock_1.LOCK_FILENAME);
+            try {
+                lock = await (0, workspace_lock_1.readLockFile)(lockPath);
+            }
+            catch (error) {
+                (0, logger_1.logError)(`Could not read lockfile at ${lockPath}`);
+                if (error instanceof Error)
+                    (0, logger_1.logError)(error.message);
+                (0, logger_1.logInfo)('Pass a path (nemus restore path/to/nemus.lock) or pipe one with: nemus restore -');
+                process.exit(1);
+            }
+        }
+        if (lock.repositories.length === 0) {
+            (0, logger_1.logError)('Lockfile has no repositories to restore');
+            process.exit(1);
+        }
+        // gh auth (soft — private repos need it, public/other creds may not)
+        if (!(await (0, github_1.verifyGhAuth)())) {
+            (0, logger_1.logWarning)('GitHub CLI not authenticated — private repositories may fail to clone.');
+        }
+        const { workspaceName, workspacePath } = await restoreWorkspace(lock, {
+            workspace: opts.workspace,
+            pin: opts.pin,
+        });
+        (0, logger_1.logSuccess)(`Workspace "${(0, colors_1.colorize)(workspaceName, 'cyan')}" restored!`);
+        // Shell-integration auto-CD (same hook create uses)
+        try {
+            const { writeFile } = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+            const os = await Promise.resolve().then(() => __importStar(require('os')));
+            await writeFile(path.join(os.homedir(), '.workspace-last-created'), workspacePath, 'utf-8');
+        }
+        catch {
+            // non-critical
+        }
+    }
+    catch (error) {
+        (0, logger_1.logError)('Failed to restore workspace');
+        if (error instanceof Error)
+            (0, logger_1.logError)(error.message);
+        process.exit(1);
+    }
+}

package/dist/mcp/server.js

@@ -387,6 +387,34 @@ server.tool('save-context', 'Save a progress summary to the workspace. Use this
         return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
     }
 });
+server.tool('lock-workspace', 'Snapshot a workspace into a committable nemus.lock manifest (repos + owner + the branch each repo is on + its HEAD commit) so it can be shared and recreated elsewhere with restore-workspace. Writes nemus.lock to the workspace root by default and returns the manifest.', {
+    workspace: wsName.describe('Name of the workspace to lock'),
+    output: zod_1.z.string().optional().describe('Optional path to write the lockfile to instead of <workspace>/nemus.lock'),
+}, async ({ workspace, output }) => {
+    try {
+        const result = await (0, tools_1.handleLockWorkspace)(workspace, output);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    }
+});
+server.tool('restore-workspace', 'Recreate a workspace from a nemus.lock manifest: clone every repo and check out the recorded branch (or the exact commit with pin). Provide the manifest inline via lockContent, or a path via lockfile (defaults to ./nemus.lock).', {
+    lockContent: zod_1.z.string().optional().describe('The nemus.lock manifest JSON, inline (preferred for agents)'),
+    lockfile: zod_1.z.string().optional().describe('Path to a nemus.lock file (used when lockContent is not given; defaults to ./nemus.lock)'),
+    workspace: wsName.optional().describe('Override the workspace name baked into the lockfile'),
+    pin: zod_1.z.boolean().optional().describe('Check out the exact recorded commit instead of the branch tip'),
+}, async ({ lockContent, lockfile, workspace, pin }) => {
+    try {
+        const result = await (0, tools_1.handleRestoreWorkspace)({ lockContent, lockfile, workspace, pin });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    }
+});
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);