@nemus-cli/nemus 0.15.2 → 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.2",
+  "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/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`);
+}