@nemus-cli/nemus 0.15.2 → 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/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

package/src/utils/workspace-lock.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  parseLock,
+  serializeLock,
+  parseGitHost,
+  reconstructRepo,
+  buildLock,
+  isSafeSegment,
+  isAllowedCloneUrl,
+  isSafeGitRef,
+  LOCK_VERSION,
+  type WorkspaceLock,
+  type LockRepo,
+} from './workspace-lock';
+import type { WorkspaceMetadata } from '../types';
+
+const execFileAsync = promisify(execFile);
+
+const validLock: WorkspaceLock = {
+  version: LOCK_VERSION,
+  workspace: 'checkout-flow',
+  generatedAt: '2026-09-09T10:00:00.000Z',
+  repositories: [
+    { name: 'web', owner: 'acme', directoryName: 'web', cloneUrl: 'git@github.com:acme/web.git', branch: 'feat/x', commit: 'abc1234' },
+  ],
+};
+
+describe('parseLock', () => {
+  it('round-trips a valid lock through serialize + parse', () => {
+    const parsed = parseLock(serializeLock(validLock));
+    expect(parsed).toEqual(validLock);
+  });
+
+  it('rejects non-JSON', () => {
+    expect(() => parseLock('not json')).toThrow(/valid JSON/i);
+  });
+
+  it('rejects an unsupported version', () => {
+    const bad = JSON.stringify({ ...validLock, version: 99 });
+    expect(() => parseLock(bad)).toThrow(/version 99/);
+  });
+
+  it('rejects a missing workspace name', () => {
+    const bad = JSON.stringify({ ...validLock, workspace: '' });
+    expect(() => parseLock(bad)).toThrow(/workspace/i);
+  });
+
+  it('rejects a non-array repositories field', () => {
+    const bad = JSON.stringify({ ...validLock, repositories: {} });
+    expect(() => parseLock(bad)).toThrow(/repositories/i);
+  });
+
+  it('rejects a repo entry missing a required field', () => {
+    const bad = JSON.stringify({ ...validLock, repositories: [{ name: 'web', owner: 'acme', directoryName: 'web' }] });
+    expect(() => parseLock(bad)).toThrow(/cloneUrl/);
+  });
+
+  it('accepts entries without optional branch/commit', () => {
+    const minimal = { ...validLock, repositories: [{ name: 'web', owner: 'acme', directoryName: 'web', cloneUrl: 'https://github.com/acme/web.git' }] };
+    expect(() => parseLock(JSON.stringify(minimal))).not.toThrow();
+  });
+
+  // Untrusted-input hardening: fields that reach git / path.join are validated.
+  it('rejects a directoryName that escapes the workspace', () => {
+    for (const directoryName of ['../evil', 'a/b', '..', 'a\\b']) {
+      const bad = { ...validLock, repositories: [{ name: 'web', owner: 'acme', directoryName, cloneUrl: 'https://h/o/r.git' }] };
+      expect(() => parseLock(JSON.stringify(bad)), directoryName).toThrow(/path segment/);
+    }
+  });
+
+  it('rejects an owner/name that is not a safe path segment (reconstructRepo builds URLs from them)', () => {
+    const badOwner = { ...validLock, repositories: [{ name: 'web', owner: '../x', directoryName: 'web', cloneUrl: 'https://h/o/r.git' }] };
+    expect(() => parseLock(JSON.stringify(badOwner))).toThrow(/owner/);
+    const badName = { ...validLock, repositories: [{ name: 'a/b', owner: 'acme', directoryName: 'web', cloneUrl: 'https://h/o/r.git' }] };
+    expect(() => parseLock(JSON.stringify(badName))).toThrow(/name/);
+  });
+
+  it('rejects a cloneUrl with no recognized transport (option-injection)', () => {
+    for (const cloneUrl of ['--upload-pack=/x', '-oProxyCommand=x', '/local/path.git', 'file:///x']) {
+      const bad = { ...validLock, repositories: [{ name: 'web', owner: 'acme', directoryName: 'web', cloneUrl }] };
+      expect(() => parseLock(JSON.stringify(bad)), cloneUrl).toThrow(/transport/);
+    }
+  });
+
+  it('rejects a branch/commit that could smuggle git flags', () => {
+    const badBranch = { ...validLock, repositories: [{ name: 'web', owner: 'acme', directoryName: 'web', cloneUrl: 'https://h/o/r.git', branch: '--upload-pack=x' }] };
+    expect(() => parseLock(JSON.stringify(badBranch))).toThrow(/branch/);
+    const badCommit = { ...validLock, repositories: [{ name: 'web', owner: 'acme', directoryName: 'web', cloneUrl: 'https://h/o/r.git', commit: '-x' }] };
+    expect(() => parseLock(JSON.stringify(badCommit))).toThrow(/commit/);
+  });
+});
+
+describe('field validators', () => {
+  it('isSafeSegment accepts plain names, rejects traversal/separators', () => {
+    for (const ok of ['web', 'my-repo', 'repo.git', 'a..b']) expect(isSafeSegment(ok), ok).toBe(true);
+    for (const no of ['', '.', '..', 'a/b', 'a\\b', '../x']) expect(isSafeSegment(no), no).toBe(false);
+  });
+  it('isAllowedCloneUrl accepts real remotes, rejects options/paths', () => {
+    for (const ok of ['https://github.com/a/b.git', 'ssh://git@h/a/b', 'git@github.com:a/b.git', 'git://h/a/b']) expect(isAllowedCloneUrl(ok), ok).toBe(true);
+    for (const no of ['--upload-pack=x', '/local/path', 'file:///x', 'ext::sh -c x']) expect(isAllowedCloneUrl(no), no).toBe(false);
+  });
+  it('isSafeGitRef accepts real refs, rejects flags/metachars', () => {
+    for (const ok of ['main', 'feat/x', 'release-1.2', 'abc1234']) expect(isSafeGitRef(ok), ok).toBe(true);
+    for (const no of ['-x', '--flag', 'a b', 'a..b', 'a~1', 'a^', 'a:b', '']) expect(isSafeGitRef(no), no).toBe(false);
+  });
+});
+
+describe('parseGitHost', () => {
+  it('parses scp-style URLs', () => {
+    expect(parseGitHost('git@github.com:acme/web.git')).toBe('github.com');
+    expect(parseGitHost('git@gitlab.example.com:team/app.git')).toBe('gitlab.example.com');
+  });
+  it('parses URL-style remotes', () => {
+    expect(parseGitHost('https://github.com/acme/web.git')).toBe('github.com');
+    expect(parseGitHost('ssh://git@code.corp/team/app')).toBe('code.corp');
+  });
+  it('returns undefined for garbage', () => {
+    expect(parseGitHost('not-a-url')).toBeUndefined();
+  });
+});
+
+describe('reconstructRepo', () => {
+  it('synthesizes https + ssh forms for a known host so getCloneUrl can pick', () => {
+    const repo = reconstructRepo({ name: 'web', owner: 'acme', directoryName: 'web', cloneUrl: 'git@github.com:acme/web.git' });
+    expect(repo.url).toBe('https://github.com/acme/web');
+    expect(repo.sshUrl).toBe('git@github.com:acme/web.git');
+    expect(repo.owner.login).toBe('acme');
+  });
+
+  it('preserves a non-default host from the locked URL', () => {
+    const repo = reconstructRepo({ name: 'app', owner: 'team', directoryName: 'app', cloneUrl: 'git@gitlab.corp:team/app.git' });
+    expect(repo.url).toBe('https://gitlab.corp/team/app');
+    expect(repo.sshUrl).toBe('git@gitlab.corp:team/app.git');
+  });
+
+  it('falls back to the stored URL when the host is unparseable', () => {
+    const url = './local/path.git';
+    const repo = reconstructRepo({ name: 'x', owner: 'y', directoryName: 'x', cloneUrl: url });
+    expect(repo.url).toBe(url);
+    expect(repo.sshUrl).toBe(url);
+  });
+});
+
+describe('buildLock', () => {
+  let tmp: string;
+  let repoDir: string;
+
+  beforeAll(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'nemus-lock-'));
+    repoDir = path.join(tmp, 'web');
+    await fs.mkdir(repoDir, { recursive: true });
+    const git = (args: string[]) => execFileAsync('git', args, { cwd: repoDir });
+    await git(['init', '-q']);
+    await git(['config', 'user.email', 'test@example.com']);
+    await git(['config', 'user.name', 'Test']);
+    await git(['checkout', '-q', '-b', 'feat/x']);
+    await fs.writeFile(path.join(repoDir, 'f.txt'), 'hi');
+    await git(['add', '.']);
+    await git(['commit', '-q', '-m', 'init']);
+  });
+
+  afterAll(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it('captures the live branch + commit for each repo', async () => {
+    const metadata: WorkspaceMetadata = {
+      workspaceName: 'demo',
+      createdAt: 'now',
+      repositories: [
+        { name: 'web', directoryName: 'web', owner: 'acme', clonedAt: 'now', cloneUrl: 'git@github.com:acme/web.git', status: 'success' },
+      ],
+    };
+    const lock = await buildLock(tmp, metadata);
+    expect(lock.version).toBe(LOCK_VERSION);
+    expect(lock.workspace).toBe('demo');
+    expect(lock.repositories).toHaveLength(1);
+    const [r] = lock.repositories;
+    expect(r.branch).toBe('feat/x');
+    expect(r.commit).toMatch(/^[0-9a-f]{7,}$/);
+  });
+
+  it('skips repos whose clone failed', async () => {
+    const metadata: WorkspaceMetadata = {
+      workspaceName: 'demo',
+      createdAt: 'now',
+      repositories: [
+        { name: 'web', directoryName: 'web', owner: 'acme', clonedAt: 'now', cloneUrl: 'x', status: 'success' },
+        { name: 'gone', directoryName: 'gone', owner: 'acme', clonedAt: 'now', cloneUrl: 'x', status: 'failed', error: 'nope' },
+      ],
+    };
+    const lock = await buildLock(tmp, metadata);
+    expect(lock.repositories.map((r: LockRepo) => r.name)).toEqual(['web']);
+  });
+});