@nemus-cli/nemus 0.15.1 → 0.16.0

package/src/commands/restore.ts

@@ -0,0 +1,219 @@
+import { Command } from 'commander';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+import { getGlobalOpts } from '../utils/command-helpers';
+import { readLockFile, parseLock, reconstructRepo, LOCK_FILENAME, type WorkspaceLock, type LockRepo } from '../utils/workspace-lock';
+import { cloneRepositories, reportCloneResults } from '../utils/git-operations';
+import { warnIfGhqMissing } from '../utils/ghq-integration';
+import { createMetadata, saveMetadata } from '../utils/workspace-meta';
+import { generateClaudeContext } from '../utils/claude-integration';
+import { verifyGhAuth } from '../utils/github';
+import { validateWorkspaceName, checkWorkspaceExists, sanitizeWorkspaceName, resolveWorkspaceNameConflict, safeWorkspacePath } from '../utils/validation';
+import { logError, logInfo, logSuccess, logStep, logWarning } from '../utils/logger';
+import { colorize } from '../utils/colors';
+import { printBanner } from '../utils/banner';
+import type { CloneResult } from '../types';
+
+export interface RestoreResult {
+  workspaceName: string;
+  workspacePath: string;
+  results: CloneResult[];
+}
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT = 30000;
+
+export function registerRestoreCommand(parent: Command) {
+  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 = getGlobalOpts(cmd);
+      await handleRestore({ lockfile, ...opts, ...globalOpts });
+    });
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  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: string, branch: string): Promise<boolean> {
+  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: string, commit: string): Promise<boolean> {
+  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).
+ */
+export async function restoreWorkspace(
+  lock: WorkspaceLock,
+  opts: { workspace?: string; pin?: boolean } = {}
+): Promise<RestoreResult> {
+  if (lock.repositories.length === 0) {
+    throw new Error('Lockfile has no repositories to restore');
+  }
+
+  // Resolve the target workspace name
+  let workspaceName = sanitizeWorkspaceName(opts.workspace || lock.workspace);
+  const nameError = validateWorkspaceName(workspaceName);
+  if (nameError !== true) {
+    throw new Error(typeof nameError === 'string' ? nameError : 'Invalid workspace name');
+  }
+  if (await checkWorkspaceExists(workspaceName)) {
+    const resolved = await resolveWorkspaceNameConflict(
+      workspaceName,
+      lock.repositories.map(r => r.directoryName)
+    );
+    logInfo(`Workspace "${workspaceName}" already exists — using "${colorize(resolved, 'cyan')}" instead.`);
+    workspaceName = resolved;
+  }
+
+  const workspacePath = safeWorkspacePath(workspaceName);
+  logInfo(`Restoring ${colorize(String(lock.repositories.length), 'cyan')} repos into workspace "${colorize(workspaceName, 'cyan')}"`);
+
+  // Clone every repo (reuses the create pipeline: ghq, concurrency, dedup)
+  logStep(1, 3, 'Cloning repositories...');
+  const { mkdir } = await import('fs/promises');
+  await mkdir(workspacePath, { recursive: true });
+  await warnIfGhqMissing();
+
+  const entries = lock.repositories.map(r => ({
+    repo: reconstructRepo(r),
+    directoryName: r.directoryName,
+  }));
+  const results = await cloneRepositories(entries, workspacePath);
+  reportCloneResults(results);
+
+  // Check out the recorded branch (or pinned commit) per repo
+  logStep(2, 3, opts.pin ? 'Checking out pinned commits...' : 'Checking out recorded branches...');
+  const byDir = new Map<string, LockRepo>(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 = colorize(result.directoryName, 'cyan');
+
+    if (opts.pin && entry.commit) {
+      if (!(await checkoutCommit(repoPath, entry.commit))) {
+        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)) {
+        logInfo(`${display} → ${entry.branch}`);
+      } else if (entry.commit && (await checkoutCommit(repoPath, entry.commit))) {
+        logWarning(`${display}: branch "${entry.branch}" not found — checked out commit ${entry.commit} instead`);
+      } else {
+        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)) {
+        logInfo(`${display} → ${entry.commit} (detached)`);
+      } else {
+        logWarning(`${display}: could not check out commit ${entry.commit} — left on the default branch`);
+      }
+    }
+  }
+
+  // Metadata + agent context (same as create)
+  logStep(3, 3, 'Saving workspace metadata...');
+  const metadata = createMetadata(workspaceName, results, { prompt: `Restored from ${LOCK_FILENAME}` });
+  await saveMetadata(workspacePath, metadata);
+
+  const successfulRepos = results.filter(r => r.status === 'success').map(r => r.repo);
+  if (successfulRepos.length > 0) {
+    await generateClaudeContext(workspacePath, workspaceName, successfulRepos, metadata);
+  }
+
+  return { workspaceName, workspacePath, results };
+}
+
+async function handleRestore(opts: {
+  lockfile?: string;
+  workspace?: string;
+  pin?: boolean;
+  yes: boolean;
+}) {
+  printBanner();
+
+  try {
+    // Step 1: Load + validate the lockfile
+    let lock: WorkspaceLock;
+    if (opts.lockfile === '-') {
+      lock = parseLock(await readStdin());
+    } else {
+      const lockPath = path.resolve(opts.lockfile || LOCK_FILENAME);
+      try {
+        lock = await readLockFile(lockPath);
+      } catch (error) {
+        logError(`Could not read lockfile at ${lockPath}`);
+        if (error instanceof Error) logError(error.message);
+        logInfo('Pass a path (nemus restore path/to/nemus.lock) or pipe one with: nemus restore -');
+        process.exit(1);
+      }
+    }
+
+    if (lock.repositories.length === 0) {
+      logError('Lockfile has no repositories to restore');
+      process.exit(1);
+    }
+
+    // gh auth (soft — private repos need it, public/other creds may not)
+    if (!(await verifyGhAuth())) {
+      logWarning('GitHub CLI not authenticated — private repositories may fail to clone.');
+    }
+
+    const { workspaceName, workspacePath } = await restoreWorkspace(lock, {
+      workspace: opts.workspace,
+      pin: opts.pin,
+    });
+
+    logSuccess(`Workspace "${colorize(workspaceName, 'cyan')}" restored!`);
+
+    // Shell-integration auto-CD (same hook create uses)
+    try {
+      const { writeFile } = await import('fs/promises');
+      const os = await import('os');
+      await writeFile(path.join(os.homedir(), '.workspace-last-created'), workspacePath, 'utf-8');
+    } catch {
+      // non-critical
+    }
+  } catch (error) {
+    logError('Failed to restore workspace');
+    if (error instanceof Error) logError(error.message);
+    process.exit(1);
+  }
+}

package/src/mcp/server.ts

@@ -41,6 +41,8 @@ import {
   handleSuiteImport,
   handleSuiteUse,
   handleSaveContext,
+  handleLockWorkspace,
+  handleRestoreWorkspace,
 } from './tools';
 
 import { getPackageVersion } from '../utils/config';
@@ -567,6 +569,44 @@ server.tool(
   }
 );
 
+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: z.string().optional().describe('Optional path to write the lockfile to instead of <workspace>/nemus.lock'),
+  },
+  async ({ workspace, output }) => {
+    try {
+      const result = await 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: z.string().optional().describe('The nemus.lock manifest JSON, inline (preferred for agents)'),
+    lockfile: 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: z.boolean().optional().describe('Check out the exact recorded commit instead of the branch tip'),
+  },
+  async ({ lockContent, lockfile, workspace, pin }) => {
+    try {
+      const result = await 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 StdioServerTransport();
   await server.connect(transport);

package/src/mcp/tools.ts

@@ -21,6 +21,8 @@ import { removeNodeModules, removeBuildArtifacts } from '../utils/cleanup-operat
 import { runPostCloneHooks } from '../utils/hooks';
 import { SuiteEntry, WorkspaceSuite, SuitesStore } from '../types';
 import { resolveWorkspaceNameConflict, sanitizeWorkspaceName, safeWorkspacePath } from '../utils/validation';
+import { buildLock, writeLock, readLockFile, parseLock, LOCK_FILENAME } from '../utils/workspace-lock';
+import { restoreWorkspace } from '../commands/restore';
 
 /**
  * Redirects stdout to stderr for the duration of a function call.
@@ -1017,3 +1019,70 @@ export async function handleSaveContext(workspace: string, content: string, appe
     };
   });
 }
+
+// ── 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.
+ */
+export async function handleLockWorkspace(workspace: string, output?: string) {
+  return withStdoutProtection(async () => {
+    if (!workspace || workspace.trim().length === 0) {
+      throw new Error('Workspace name is required');
+    }
+    const workspacePath = safeWorkspacePath(sanitizeWorkspaceName(workspace));
+    const metadata = await loadMetadata(workspacePath);
+    if (!metadata) {
+      throw new Error(`Workspace not found: ${workspace}`);
+    }
+    const lock = await buildLock(workspacePath, metadata);
+    const outPath = output ? path.resolve(output) : path.join(workspacePath, LOCK_FILENAME);
+    await 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`).
+ */
+export async function handleRestoreWorkspace(opts: {
+  workspace?: string;
+  lockfile?: string;
+  lockContent?: string;
+  pin?: boolean;
+}) {
+  return withStdoutProtection(async () => {
+    const lock = opts.lockContent
+      ? parseLock(opts.lockContent)
+      : await readLockFile(path.resolve(opts.lockfile || LOCK_FILENAME));
+
+    const { workspaceName, workspacePath, results } = await 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/src/postinstall.test.ts

@@ -1,52 +1,125 @@
 import { describe, it, expect } from 'vitest';
 import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 const SCRIPT = join(__dirname, '..', 'scripts', 'postinstall.js');
+// postinstall.js guards its side effects with `require.main !== module`, so
+// importing it just exposes the pure classifier.
+const { classifyInstall } = createRequire(__filename)(SCRIPT) as {
+  classifyInstall: (i: { env: Record<string, string | undefined>; dirname: string; tmpDir: string }) => string;
+};
 
-describe('postinstall.js', () => {
-  // Regression: a transient `npx @nemus-cli/nemus …` (npm exec) or a local
-  // dependency install is NOT global. Such installs must not launch the
-  // interactive `configure` (which reaches /dev/tty and would HANG a
-  // non-interactive `npx … --help`) nor mutate the user's shell RC — the bins
-  // aren't persisted on PATH for them anyway.
-  it('is a fast no-op for a non-global install: exits 0 and never touches the shell RC', () => {
-    const home = mkdtempSync(join(tmpdir(), 'nemus-postinstall-'));
-    const rc = join(home, '.zshrc');
-    writeFileSync(rc, '# user rc\n');
-    const env = { ...process.env, HOME: home, SHELL: '/bin/zsh', NEMUS_CACHE_DIR: join(home, '.nemus') };
-    // Delete CI so the global gate — not the CI early-exit — is what protects npx.
-    delete env.CI;
-    delete env.npm_config_global; // npx / local install leaves this unset
-    try {
-      // Throws on non-zero exit; throws on the 15s timeout if it ever hangs.
-      execFileSync(process.execPath, [SCRIPT], { env, stdio: 'ignore', timeout: 15_000 });
-      // RC untouched — no guarded `source` line appended.
-      expect(readFileSync(rc, 'utf8')).toBe('# user rc\n');
-    } finally {
-      rmSync(home, { recursive: true, force: true });
-    }
-  });
-
-  it('treats npm_config_global="false" the same as unset (still a no-op)', () => {
-    const home = mkdtempSync(join(tmpdir(), 'nemus-postinstall-'));
-    const rc = join(home, '.bashrc');
-    writeFileSync(rc, '# user rc\n');
-    const env = {
-      ...process.env,
-      HOME: home,
-      SHELL: '/bin/bash',
-      NEMUS_CACHE_DIR: join(home, '.nemus'),
-      npm_config_global: 'false',
-    };
-    delete env.CI;
-    try {
-      execFileSync(process.execPath, [SCRIPT], { env, stdio: 'ignore', timeout: 15_000 });
-      expect(readFileSync(rc, 'utf8')).toBe('# user rc\n');
-    } finally {
-      rmSync(home, { recursive: true, force: true });
-    }
+const NPM_UA = 'npm/10.9.0 node/v22.13.0 darwin arm64 workspaces/false';
+const YARN_UA = 'yarn/1.22.22 npm/? node/v22.13.0 darwin arm64';
+const PNPM_UA = 'pnpm/10.34.5 npm/? node/v22.13.0';
+const TMP = '/var/folders/xy/T';
+
+describe('classifyInstall', () => {
+  it('CI → ci', () => {
+    expect(classifyInstall({ env: { CI: 'true' }, dirname: '/anywhere', tmpDir: TMP })).toBe('ci');
+  });
+
+  it('npm -g → global-npm; npm local → local', () => {
+    expect(classifyInstall({ env: { npm_config_global: 'true', npm_config_user_agent: NPM_UA }, dirname: '/usr/local/lib/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('global-npm');
+    expect(classifyInstall({ env: { npm_config_global: 'false', npm_config_user_agent: NPM_UA }, dirname: '/proj/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('local');
+  });
+
+  it('npx (npm_command=exec) → transient', () => {
+    expect(classifyInstall({ env: { npm_command: 'exec', npm_config_user_agent: NPM_UA }, dirname: '/home/u/.npm/_npx/abc123/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('transient');
+  });
+
+  it('yarn global add (bare yarn UA, no npm_command/global) → global-other', () => {
+    expect(classifyInstall({ env: { npm_config_user_agent: YARN_UA }, dirname: '/home/u/.config/yarn/global/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('global-other');
+  });
+
+  it('pnpm add -g (bare pnpm UA) → global-other', () => {
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: '/home/u/Library/pnpm/global/5/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('global-other');
+  });
+
+  // The reviewer's case: `pnpm dlx` sets NEITHER npm_command NOR
+  // npm_config_global — only the pnpm user-agent. UA-only logic would call this
+  // "global-other" and re-introduce the /dev/tty hang. The install PATH
+  // (".../pnpm/dlx/<hash>/...") is the signal that saves us.
+  it('pnpm dlx (only pnpm UA, staged under .../pnpm/dlx/...) → transient', () => {
+    const dir = '/home/u/Library/Caches/pnpm/dlx/ed050d93/1a07/node_modules/@nemus-cli/nemus/scripts';
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: dir, tmpDir: TMP })).toBe('transient');
+  });
+
+  // A realistic pnpm dlx __dirname (verified by dumping a real run): the /dlx/
+  // marker sits BEFORE the symlinky `.pnpm` store segments. postinstall.js
+  // passes the RAW __dirname (never fs.realpathSync'd) precisely so the marker
+  // isn't resolved away into a content-addressed store path — this asserts the
+  // deep, real-shaped path still classifies transient.
+  it('pnpm dlx deep real path (marker before the .pnpm store segments) → transient', () => {
+    const dir =
+      '/Users/u/Library/Caches/pnpm/dlx/9622a716fa/1a0757951f6-12d63/node_modules/.pnpm/nemus@file+..+..+tmp/node_modules/@nemus-cli/nemus/scripts';
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: dir, tmpDir: TMP })).toBe('transient');
+  });
+
+  it('yarn berry dlx (only yarn UA, staged under the OS temp dir) → transient', () => {
+    const dir = `${TMP}/xfs-9f/node_modules/@nemus-cli/nemus/scripts`;
+    expect(classifyInstall({ env: { npm_config_user_agent: YARN_UA }, dirname: dir, tmpDir: TMP })).toBe('transient');
+  });
+
+  // The real macOS case: os.tmpdir() reports /var/folders/… (a symlink) while a
+  // package staged under it resolves to /private/var/folders/… . A raw
+  // startsWith would miss this and misclassify the dlx run as global-other
+  // (spurious shell-RC write). The classifier must normalize the /private prefix.
+  it('yarn/pnpm dlx staged under /private/var while tmpDir is /var → transient', () => {
+    const tmpDir = '/var/folders/xy/T';
+    const dir = '/private/var/folders/xy/T/xfs-9f/node_modules/@nemus-cli/nemus/scripts';
+    expect(classifyInstall({ env: { npm_config_user_agent: YARN_UA }, dirname: dir, tmpDir })).toBe('transient');
+    // symmetric: tmpDir realpath'd to /private while dir stays /var
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: '/var/folders/xy/T/d/node_modules/x', tmpDir: '/private/var/folders/xy/T' })).toBe('transient');
+  });
+});
+
+/** Run the real postinstall.js in a sandbox HOME with a controlled environment.
+ *  stdio is ignored and there's no tty, and NEMUS_SKIP_CONFIGURE guards a
+ *  tty-bearing host, so we exercise the gate + non-interactive shell-integration
+ *  path end-to-end (dirname is the real repo path — never transient). */
+function runPostinstall(rcName: string, extraEnv: Record<string, string | undefined>) {
+  const home = mkdtempSync(join(tmpdir(), 'nemus-postinstall-'));
+  const rc = join(home, rcName);
+  writeFileSync(rc, '# user rc\n');
+  const env: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    HOME: home,
+    NEMUS_CACHE_DIR: join(home, '.nemus'),
+    NEMUS_SKIP_CONFIGURE: '1',
+  };
+  delete env.CI;
+  for (const [k, v] of Object.entries(extraEnv)) {
+    if (v === undefined) delete env[k];
+    else env[k] = v;
+  }
+  execFileSync(process.execPath, [SCRIPT], { env, stdio: 'ignore', timeout: 20_000 });
+  const rcAfter = readFileSync(rc, 'utf8');
+  rmSync(home, { recursive: true, force: true });
+  return rcAfter;
+}
+
+describe('postinstall.js (end-to-end)', () => {
+  it('npx / npm exec → no-op, RC untouched', () => {
+    expect(runPostinstall('.zshrc', { npm_command: 'exec', npm_config_user_agent: NPM_UA, npm_config_global: undefined, SHELL: '/bin/zsh' })).toBe('# user rc\n');
+  });
+
+  it('npm local dependency install (global="false") → no-op, RC untouched', () => {
+    expect(runPostinstall('.zshrc', { npm_command: 'install', npm_config_user_agent: NPM_UA, npm_config_global: 'false', SHELL: '/bin/zsh' })).toBe('# user rc\n');
+  });
+
+  it('npm global install → runs shell integration (RC gets the source line)', () => {
+    expect(runPostinstall('.zshrc', { npm_command: 'install', npm_config_user_agent: NPM_UA, npm_config_global: 'true', SHELL: '/bin/zsh' })).toContain('.nemus/shell-integration.sh');
+  });
+
+  it('yarn global add (no npm_config_global) → runs shell integration', () => {
+    expect(runPostinstall('.bashrc', { npm_command: undefined, npm_config_user_agent: YARN_UA, npm_config_global: undefined, SHELL: '/bin/bash' })).toContain('.nemus/shell-integration.sh');
+  });
+
+  it('pnpm add -g (no npm_config_global) → runs shell integration', () => {
+    expect(runPostinstall('.bashrc', { npm_command: undefined, npm_config_user_agent: PNPM_UA, npm_config_global: undefined, SHELL: '/bin/bash' })).toContain('.nemus/shell-integration.sh');
   });
 });

package/src/program.ts

@@ -64,6 +64,8 @@ import { registerMigrateCommand } from './commands/migrate';
 import { registerReportBugCommand } from './commands/report-bug';
 import { registerCompletionCommand } from './commands/completion';
 import { registerReflectCommand } from './commands/reflect';
+import { registerLockCommand } from './commands/lock';
+import { registerRestoreCommand } from './commands/restore';
 
 registerCreateCommand(program);
 registerListCommand(program);
@@ -92,6 +94,8 @@ registerMigrateCommand(program);
 registerReportBugCommand(program);
 registerCompletionCommand(program);
 registerReflectCommand(program);
+registerLockCommand(program);
+registerRestoreCommand(program);
 
 // Register TUI (delegates to existing Ink/React implementation)
 program