@nemus-cli/nemus 0.15.1 → 0.16.0

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']);
+  });
+});

package/src/utils/workspace-lock.ts

@@ -0,0 +1,245 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { GitHubRepo, WorkspaceMetadata } from '../types';
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT = 15000;
+
+/** Committable manifest that fully describes a workspace's repos + branch state. */
+export const LOCK_FILENAME = 'nemus.lock';
+export const LOCK_VERSION = 1;
+
+export interface LockRepo {
+  name: string;
+  owner: string;
+  directoryName: string;
+  cloneUrl: string;
+  /** Current branch at lock time. Omitted for a detached HEAD. */
+  branch?: string;
+  /** Short HEAD SHA at lock time (used by `restore --pin`, and as a fallback). */
+  commit?: string;
+}
+
+export interface WorkspaceLock {
+  version: number;
+  workspace: string;
+  generatedAt: string;
+  repositories: LockRepo[];
+}
+
+/** Read the current branch of a git repo, or undefined for a detached HEAD / error. */
+export async function readRepoBranch(repoPath: string): Promise<string | undefined> {
+  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. */
+export async function readRepoCommit(repoPath: string): Promise<string | undefined> {
+  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.
+ */
+export async function buildLock(
+  workspacePath: string,
+  metadata: WorkspaceMetadata
+): Promise<WorkspaceLock> {
+  const repos = metadata.repositories.filter(r => r.status !== 'failed');
+
+  const repositories: LockRepo[] = await Promise.all(
+    repos.map(async (r): Promise<LockRepo> => {
+      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: LOCK_VERSION,
+    workspace: metadata.workspaceName,
+    generatedAt: new Date().toISOString(),
+    repositories,
+  };
+}
+
+/** Serialize a lock to canonical JSON (trailing newline). */
+export function serializeLock(lock: WorkspaceLock): string {
+  return JSON.stringify(lock, null, 2) + '\n';
+}
+
+export async function writeLock(filePath: string, lock: WorkspaceLock): Promise<void> {
+  await fs.writeFile(filePath, serializeLock(lock), 'utf-8');
+}
+
+/** Parse + validate a lock manifest. Throws a helpful error on malformed input. */
+export function parseLock(content: string): WorkspaceLock {
+  let data: unknown;
+  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 as Partial<WorkspaceLock>;
+  if (lock.version !== LOCK_VERSION) {
+    throw new Error(
+      `Unsupported lockfile version ${String(lock.version)} (this nemus supports version ${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 as Partial<LockRepo>;
+    for (const field of ['name', 'owner', 'directoryName', 'cloneUrl'] as const) {
+      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 as WorkspaceLock;
+}
+
+/**
+ * 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.
+ */
+export function isSafeSegment(name: string): boolean {
+  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.
+ */
+export function isAllowedCloneUrl(url: string): boolean {
+  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 `..`).
+ */
+export function isSafeGitRef(ref: string): boolean {
+  return (
+    ref.length > 0 &&
+    !ref.startsWith('-') &&
+    // eslint-disable-next-line no-control-regex
+    !/[\s\x00-\x1f\x7f~^:?*[\\]/.test(ref) &&
+    !ref.includes('..')
+  );
+}
+
+export async function readLockFile(filePath: string): Promise<WorkspaceLock> {
+  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.
+ */
+export function parseGitHost(cloneUrl: string): string | undefined {
+  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).
+ */
+export function reconstructRepo(entry: LockRepo): GitHubRepo {
+  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,
+  };
+}