@nemus-cli/nemus 0.15.1 → 0.16.0

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,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "workspaces": [
     "packages/*"
   ],
@@ -83,6 +83,6 @@
     "@types/react": "^19.2.2",
     "ts-node": "^10.9.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   }
 }

package/scripts/postinstall.js

@@ -17,18 +17,88 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-// Skip in CI environments
-if (process.env.CI) process.exit(0);
-
-// Only run first-run setup for a real GLOBAL install (`npm i -g`). A transient
-// `npx @nemus-cli/nemus …` (npm exec) or a local dependency install is not
-// global: the `nemus`/`nem` bins aren't persisted on PATH, so shell integration
-// is pointless — and worse, the interactive `configure` below reaches the
-// controlling terminal via /dev/tty and would HANG a non-interactive
-// `npx … --help`/`--version` invocation waiting for input. npm sets
-// npm_config_global="true" only for `-g`/`--global`; npx and local installs
-// leave it false/unset.
-if (String(process.env.npm_config_global).toLowerCase() !== 'true') process.exit(0);
+/**
+ * Classify the install context, so first-run setup (interactive `configure` +
+ * shell integration) runs only when it makes sense — and NEVER on a transient
+ * one-off runner (npx / dlx), where an interactive prompt on the controlling
+ * terminal would HANG. Pure (all inputs injected) so it's unit-tested.
+ *
+ * Returns: 'ci' | 'transient' | 'local' | 'global-npm' | 'global-other'.
+ *
+ * Detection is empirical (env dumped from real runners), because the managers
+ * disagree on what they set:
+ *   • npm  — npx sets npm_command="exec"; `-g` sets npm_config_global="true"; a
+ *            local install sets it "false". Reliable.
+ *   • pnpm — `pnpm dlx` sets NEITHER npm_command NOR npm_config_global, only
+ *            npm_config_user_agent="pnpm/…". It DOES stage the package under a
+ *            per-run cache path ("…/pnpm/dlx/<hash>/…"), which we key on.
+ *   • yarn — classic `yarn global add` sets only "yarn/…" (no npm_command /
+ *            npm_config_global); berry `yarn dlx` stages under a temp dir.
+ * So a bare yarn/pnpm user-agent is treated as a GLOBAL install UNLESS the
+ * install PATH shows a transient runner cache. The path is matched RAW (only the
+ * macOS /private symlink prefix is string-normalized, below) — deliberately NOT
+ * fs.realpathSync'd: realpath resolves a pnpm/yarn staging dir through its
+ * symlinks into a content-addressed store path that no longer contains /dlx/,
+ * which would defeat the marker. String-normalizing just the /private prefix
+ * fixes the macOS /var↔/private/var temp-dir case without touching the markers.
+ *
+ * NOTE on failure mode: because the interactive `configure` (the step that can
+ * hang on /dev/tty) is separately gated to a confirmed npm `-g` install (see
+ * `certainNpmGlobal`), a misclassified `pnpm dlx`/`yarn dlx` lands in
+ * 'global-other' and can never hang — it skips `configure`. The path signal's
+ * real job is therefore to stop a throwaway dlx run from spuriously appending
+ * the source line to the user's shell RC, not to provide hang-safety.
+ */
+function classifyInstall({ env, dirname, tmpDir }) {
+  if (env.CI) return 'ci';
+
+  const cmd = (env.npm_command || '').toLowerCase();
+  // macOS surfaces the temp dir both as /var/folders/… (os.tmpdir(), a symlink)
+  // and /private/var/folders/… (the realpath a staged package resolves to). Strip
+  // the well-known /private symlink prefix from both sides so the temp-dir
+  // comparison survives it — done by string, not fs.realpathSync, to keep this
+  // function pure (and correct for paths that don't exist yet, e.g. in tests).
+  const norm = (p) => String(p || '').replace(/\\/g, '/').replace(/^\/private(?=\/)/, '');
+  const dir = norm(dirname);
+  const tmp = norm(tmpDir);
+  const stagedInRunnerCache =
+    /\/_npx\//.test(dir) ||                              // npm  npx
+    /\/dlx\//.test(dir) ||                               // pnpm dlx (or any /dlx/ cache)
+    (tmp !== '' && (dir === tmp || dir.startsWith(tmp + '/'))); // yarn berry dlx et al.
+  if (cmd === 'exec' || cmd === 'dlx' || stagedInRunnerCache) return 'transient';
+
+  const global = String(env.npm_config_global).toLowerCase();
+  if (global === 'true') return 'global-npm';
+  if (global === 'false') return 'local';
+
+  // No npm_config_global (yarn/pnpm): a bare manager user-agent means a global
+  // install here (their transient runners were caught above).
+  const manager = (env.npm_config_user_agent || '').toLowerCase().split('/')[0];
+  if (manager === 'yarn' || manager === 'pnpm') return 'global-other';
+  return 'local';
+}
+
+module.exports = { classifyInstall };
+
+// When imported (unit tests) rather than run as the postinstall script, stop
+// here — export the classifier without executing any install side effects.
+// (CommonJS wraps modules in a function, so a top-level return is valid.)
+if (require.main !== module) return;
+
+// Pass the RAW __dirname (not realpath'd): the transient-runner markers below
+// (/_npx/, /dlx/) live in the path the runner *constructs*, and fs.realpathSync
+// would resolve a pnpm/yarn staging dir through its symlinks into a
+// content-addressed store path that no longer contains the marker — defeating
+// the very check. The macOS /var↔/private/var temp symlink is instead handled
+// deterministically by string normalization inside classifyInstall.
+const installDecision = classifyInstall({ env: process.env, dirname: __dirname, tmpDir: os.tmpdir() });
+// Only 'global-*' installs get first-run setup; ci/transient/local are no-ops.
+if (installDecision !== 'global-npm' && installDecision !== 'global-other') process.exit(0);
+// Interactive `configure` (reaches /dev/tty) fires ONLY when we're certain it's
+// an npm `-g` install. yarn/pnpm can't be told apart from their dlx runners by
+// env alone, so they get the NON-interactive shell integration below + a hint —
+// which can never hang.
+const certainNpmGlobal = installDecision === 'global-npm';
 
 const PKG_ROOT = path.join(__dirname, '..');
 const SHELL_SCRIPT = path.join(PKG_ROOT, 'install-shell-integration.sh');
@@ -79,7 +149,7 @@ function openControllingTty() {
   }
 }
 
-if (!optedOut() && fs.existsSync(CLI_BIN) && !alreadyConfigured()) {
+if (certainNpmGlobal && !optedOut() && fs.existsSync(CLI_BIN) && !alreadyConfigured()) {
   const tty = openControllingTty();
   if (tty !== null) {
     try {
@@ -156,6 +226,12 @@ console.log('');
 console.log('  Or open a new terminal tab. Until then, auto-CD into a new');
 console.log('  workspace won\'t work (the CLI itself still runs fine).');
 console.log('');
+if (!certainNpmGlobal) {
+  // yarn/pnpm global: we installed shell integration but deliberately did NOT
+  // launch the interactive configure — point the user at it explicitly.
+  console.log('  \x1b[90m(yarn/pnpm install — run \x1b[36mnemus configure\x1b[90m to finish first-time setup.)\x1b[0m');
+  console.log('');
+}
 console.log('  Tip: \x1b[36mnemus\x1b[0m works immediately (\x1b[36mgv\x1b[0m is a short alias):');
 console.log('       \x1b[36mnemus configure\x1b[0m   \x1b[90m# first-time setup\x1b[0m');
 console.log('       \x1b[36mnemus list\x1b[0m        \x1b[90m# list workspaces\x1b[0m');

package/skills/nemus/SKILL.md

@@ -72,6 +72,18 @@ Global flags: `-f/--force-refresh` (skip repo cache), `-y/--yes` (skip prompts),
 | Import suite(s) from JSON | [suite-import](references/suite-import.md) | `nemus suite import <file>` |
 | Create workspace from suite | [suite-use](references/suite-use.md) | `nemus suite use` |
 
+### Portable Workspaces (lock / restore)
+
+| Intent | Reference | CLI |
+|---|---|---|
+| Snapshot a workspace to a committable `nemus.lock` | [lock](references/lock.md) | `nemus lock [ws] [-o file\|-]` |
+| Recreate a workspace from a `nemus.lock` | [restore](references/restore.md) | `nemus restore [file\|-] [-w name] [--pin]` |
+
+`lock`/`restore` is portable and recreates repos from scratch (vs. `snapshot`,
+which is local time-travel within an existing workspace; vs. `suite`, a reusable
+repo *template*). The lockfile records repos + owner + each repo's branch + HEAD
+commit; it holds no secrets (only what `git remote -v` exposes).
+
 ### Cache & Repo Discovery
 
 | Intent | Reference | CLI |

package/skills/nemus/references/lock.md

@@ -0,0 +1,38 @@
+# lock
+
+Snapshot a workspace into a committable `nemus.lock` — the repos, each repo's
+owner + directory name + clone URL, the branch it's currently on, and its HEAD
+commit. Share the file (commit it, drop it in a ticket) and anyone recreates the
+exact workspace with [`restore`](restore.md).
+
+## CLI
+
+```bash
+nemus lock [workspace] [options]
+```
+
+- `[workspace]` — workspace name; omitted, resolves the current/default one.
+- `-o, --output <file>` — write to `<file>` instead of `<workspace>/nemus.lock`.
+  Use `-o -` to print the lockfile JSON to stdout (pipe/redirect it anywhere).
+- `--all` — write a `nemus.lock` into **every** workspace (makes a whole machine
+  portable in one shot). Skips workspaces that already have a lockfile unless
+  `--force` is given. Cannot be combined with `--output`. This is the explicit
+  alternative to a hidden snapshot side effect in `migrate`.
+
+## Examples
+
+```bash
+nemus lock                       # write ./nemus.lock into the current workspace
+nemus lock checkout-flow          # snapshot a named workspace
+nemus lock checkout-flow -o cf.lock
+nemus lock checkout-flow -o - | pbcopy   # copy the manifest to the clipboard
+nemus lock --all                 # lock every workspace (skips existing lockfiles)
+nemus lock --all --force          # …and overwrite existing ones
+```
+
+## Notes
+
+- Repos whose original clone failed are skipped.
+- A repo on a detached HEAD records only its commit (no branch).
+- The lockfile contains only what `git remote -v` already exposes — safe to commit.
+- Distinct from `snapshot` (local time-travel) and `suite` (reusable template).

package/skills/nemus/references/mcp.md

@@ -28,4 +28,6 @@ nemus mcp status
 
 When installed, Claude Code gains access to Nemus tools:
 - `create-workspace`, `list-workspaces`, `workspace-status`, etc.
+- `lock-workspace` / `restore-workspace` — snapshot a workspace to a portable
+  `nemus.lock` and recreate it elsewhere (accepts the manifest inline).
 - Enables natural language workspace management via `nemus -- <prompt>`

package/skills/nemus/references/restore.md

@@ -0,0 +1,39 @@
+# restore
+
+Recreate a workspace from a `nemus.lock` (see [`lock`](lock.md)) on any machine:
+clones every repo and checks out the recorded branch, then writes metadata +
+agent context exactly like `create`.
+
+## CLI
+
+```bash
+nemus restore [lockfile] [options]
+```
+
+- `[lockfile]` — path to a `nemus.lock`; omitted, uses `./nemus.lock`. Use `-`
+  to read the lockfile from stdin.
+- `-w, --workspace <name>` — override the workspace name baked into the lockfile
+  (also used to resolve a name clash).
+- `--pin` — check out the exact recorded commit for each repo instead of the
+  branch tip.
+- `-y, --yes` — non-interactive (skips the post-restore agent launch).
+
+## Examples
+
+```bash
+nemus restore                          # from ./nemus.lock
+nemus restore cf.lock                    # from a specific file
+nemus restore cf.lock -w experiment      # into a differently-named workspace
+nemus restore cf.lock --pin              # reproduce exact commits, not branch tips
+cat cf.lock | nemus restore -            # from stdin
+```
+
+## Notes
+
+- URLs are rebuilt for the restorer's `cloneProtocol` (https/ssh) using the
+  locked host + owner + name, so an ssh-locked workspace restores fine for an
+  https user.
+- If a recorded branch no longer exists on the remote, restore falls back to the
+  recorded commit and warns.
+- Name clashes auto-resolve to a suffixed name (same as `create`).
+- Needs GitHub auth for private repos (warns if `gh` is unauthenticated).

package/src/commands/lock.ts

@@ -0,0 +1,129 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { WORKSPACES_DIR } from '../utils/config';
+import { loadMetadata, listWorkspaces } from '../utils/workspace-meta';
+import { resolveWorkspace, getGlobalOpts } from '../utils/command-helpers';
+import { buildLock, serializeLock, writeLock, LOCK_FILENAME } from '../utils/workspace-lock';
+import { logError, logInfo, logSuccess, logWarning } from '../utils/logger';
+import { colorize } from '../utils/colors';
+
+export function registerLockCommand(parent: Command) {
+  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 = getGlobalOpts(cmd);
+      await handleLock({ workspace, ...opts, ...globalOpts });
+    });
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function handleLock(opts: {
+  workspace?: string;
+  output?: string;
+  all?: boolean;
+  force?: boolean;
+}) {
+  if (opts.all) {
+    await handleLockAll(opts);
+    return;
+  }
+
+  try {
+    const workspaceName = await resolveWorkspace(opts.workspace);
+    const workspacePath = path.join(WORKSPACES_DIR, workspaceName);
+
+    const metadata = await loadMetadata(workspacePath);
+    if (!metadata) {
+      logError(`Workspace not found: ${workspaceName}`);
+      process.exit(1);
+    }
+
+    const lock = await buildLock(workspacePath, metadata);
+
+    // `-o -`: emit only the lockfile JSON so it can be piped/redirected cleanly.
+    if (opts.output === '-') {
+      process.stdout.write(serializeLock(lock));
+      return;
+    }
+
+    const outPath = opts.output
+      ? path.resolve(opts.output)
+      : path.join(workspacePath, LOCK_FILENAME);
+    await writeLock(outPath, lock);
+
+    logSuccess(`Wrote ${colorize(LOCK_FILENAME, 'cyan')} (${lock.repositories.length} repos) → ${outPath}`);
+    logInfo('Commit or share it, then recreate the workspace with: nemus restore');
+  } catch (error) {
+    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: { output?: string; force?: boolean }) {
+  if (opts.output) {
+    logError('--all writes one nemus.lock per workspace and cannot be combined with --output.');
+    process.exit(1);
+  }
+
+  const workspaces = await listWorkspaces(false);
+  if (workspaces.length === 0) {
+    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 loadMetadata(ws.path));
+    if (!metadata) {
+      logWarning(`  ${ws.name}: no metadata — skipped (run 'nemus migrate' first)`);
+      skipped++;
+      continue;
+    }
+
+    const outPath = path.join(ws.path, LOCK_FILENAME);
+    if (!opts.force && (await fileExists(outPath))) {
+      logInfo(`  ${colorize(ws.name, 'cyan')}: ${LOCK_FILENAME} already exists — skipped (use --force to overwrite)`);
+      skipped++;
+      continue;
+    }
+
+    try {
+      const lock = await buildLock(ws.path, metadata);
+      await writeLock(outPath, lock);
+      logSuccess(`  ${colorize(ws.name, 'cyan')}: wrote ${LOCK_FILENAME} (${lock.repositories.length} repos)`);
+      written++;
+    } catch (error) {
+      logError(`  ${ws.name}: ${error instanceof Error ? error.message : 'failed to write lockfile'}`);
+      errors++;
+    }
+  }
+
+  console.log('');
+  logInfo('Bulk lock complete:');
+  console.log(`  ${colorize(String(written), 'green')} written`);
+  if (skipped > 0) console.log(`  ${colorize(String(skipped), 'yellow')} skipped`);
+  if (errors > 0) console.log(`  ${colorize(String(errors), 'red')} errors`);
+}