@roulabs/mx 2.3.0 → 2.4.0

package/README.md

@@ -43,7 +43,7 @@ Inside a work folder or worktree you can drop `-n` — mx infers the work/repo f
 | `mx info [--all] [--porcelain]` | list repos, works, worktrees, ports |
 | `mx sync` | re-stamp the runtime's mx-owned files (`CLAUDE.md`, per-repo/per-work scaffolding) from the current CLI — same-major, non-destructive |
 | `mx update` | self-update the CLI within its major (`npm i -g`); flags a newer major if one exists |
-| `mx migrate` | upgrade an older-version runtime to the version this CLI supports (the only command allowed on a version-mismatched runtime) |
+| `mx migrate [--dry-run]` | upgrade an older-version runtime to the version this CLI supports (the only command allowed on a version-mismatched runtime); `--dry-run` previews the plan without changing anything |
 | `mx repo add <git-url> [--name <n>]` | clone a pristine repo (into `repos/<repo>/git`; stamps its `hydrate.sh`/`health.sh`) |
 | `mx repo ls` / `mx repo -n <name> fetch\|info\|rm` | manage pristine repos |
 | `mx repo health` / `mx repo -n <name> health` | local-only health check (augmented by the repo's `health.sh`) |

package/bin/mx.js

@@ -222,13 +222,18 @@ function requireRuntime(opts = {}) {
 function listRepoNames(root) {
   return listDirs(reposDir(root)).filter((n) => isGitRepo(repoGitDir(root, n)));
 }
-function migrateRepoLayout(root) {
+function migrateRepoLayout(root, opts = {}) {
+  const dry = opts.dryRun === true;
   const migrated = [];
   for (const name of listDirs(reposDir(root))) {
     const container = repoPath(root, name);
     const gitdir = repoGitDir(root, name);
     if (isGitRepo(gitdir)) continue;
     if (!isGitRepo(container)) continue;
+    if (dry) {
+      migrated.push(container);
+      continue;
+    }
     const tmp = path3.join(reposDir(root), `.${name}.mxmig`);
     if (exists(tmp)) fs4.rmSync(tmp, { recursive: true, force: true });
     fs4.renameSync(container, tmp);
@@ -242,7 +247,8 @@ function migrateRepoLayout(root) {
   }
   return migrated;
 }
-function migrateWorkLayout(root) {
+function migrateWorkLayout(root, opts = {}) {
+  const dry = opts.dryRun === true;
   const changed = [];
   for (const name of listWorkNames(root)) {
     let work;
@@ -257,6 +263,10 @@ function migrateWorkLayout(root) {
       const flat = path3.join(wd, wt.repo);
       const dest = path3.join(wtDir, wt.repo);
       if (exists(dest) || !exists(flat)) continue;
+      if (dry) {
+        changed.push(dest);
+        continue;
+      }
       fs4.mkdirSync(wtDir, { recursive: true });
       try {
         git(["-C", repoGitDir(root, wt.repo), "worktree", "move", flat, dest]);
@@ -276,12 +286,12 @@ function migrateWorkLayout(root) {
       let touched = false;
       for (const f of ws.folders ?? []) {
         if (f.path && !f.path.startsWith("wt/") && repos.has(f.path)) {
-          f.path = `wt/${f.path}`;
+          if (!dry) f.path = `wt/${f.path}`;
           touched = true;
         }
       }
       if (touched) {
-        writeJson(wsFile, ws);
+        if (!dry) writeJson(wsFile, ws);
         changed.push(wsFile);
       }
     }
@@ -360,32 +370,37 @@ function initRuntime(target0, templatesDir2) {
   removeStaleRuntimeReadme(target);
   return { runtime: target, created };
 }
-function ensureWorkScaffolding(root, workName) {
+function ensureWorkScaffolding(root, workName, opts = {}) {
+  const dry = opts.dryRun === true;
   const created = [];
   const wd = workDir(root, workName);
   for (const d of ["wt", "scripts", "bin", "files", "tmp", "sessions", "hooks"]) {
     const p = path3.join(wd, d);
     if (!exists(p)) {
-      fs4.mkdirSync(p, { recursive: true });
+      if (!dry) fs4.mkdirSync(p, { recursive: true });
       created.push(p);
     }
   }
   const claudeMd = path3.join(wd, "CLAUDE.md");
   if (!exists(claudeMd)) {
-    fs4.writeFileSync(claudeMd, workClaudeMd(workName));
+    if (!dry) fs4.writeFileSync(claudeMd, workClaudeMd(workName));
     created.push(claudeMd);
   }
   const settings = path3.join(wd, ".claude", "settings.json");
   if (!exists(settings)) {
-    fs4.mkdirSync(path3.dirname(settings), { recursive: true });
-    fs4.writeFileSync(settings, workClaudeSettings(root));
+    if (!dry) {
+      fs4.mkdirSync(path3.dirname(settings), { recursive: true });
+      fs4.writeFileSync(settings, workClaudeSettings(root));
+    }
     created.push(settings);
   }
   for (const event of WORK_HOOK_EVENTS) {
     const hook = workHookScript(root, workName, event);
     if (!exists(hook)) {
-      fs4.writeFileSync(hook, workHookScriptBody(event));
-      fs4.chmodSync(hook, 493);
+      if (!dry) {
+        fs4.writeFileSync(hook, workHookScriptBody(event));
+        fs4.chmodSync(hook, 493);
+      }
       created.push(hook);
     }
   }
@@ -472,20 +487,23 @@ var STEPS = {
   1: {
     from: 1,
     to: 2,
-    run: (root) => {
+    run: (root, { dryRun }) => {
       const changed = [];
-      changed.push(...migrateRepoLayout(root));
-      changed.push(...migrateWorkLayout(root));
-      for (const work of listWorkNames(root)) changed.push(...ensureWorkScaffolding(root, work));
-      writeRuntimeVersion(root, 2);
+      changed.push(...migrateRepoLayout(root, { dryRun }));
+      changed.push(...migrateWorkLayout(root, { dryRun }));
+      for (const work of listWorkNames(root)) {
+        changed.push(...ensureWorkScaffolding(root, work, { dryRun }));
+      }
+      if (!dryRun) writeRuntimeVersion(root, 2);
       return changed;
     }
   }
 };
-function migrateRuntime(root) {
+function migrateRuntime(root, opts = {}) {
+  const dryRun = opts.dryRun === true;
   const from = readRuntimeVersion(root);
   if (from === RUNTIME_VERSION) {
-    return { from, to: RUNTIME_VERSION, applied: [], changed: [] };
+    return { from, to: RUNTIME_VERSION, applied: [], changed: [], dryRun };
   }
   if (from > RUNTIME_VERSION) {
     throw new MxError(
@@ -505,10 +523,10 @@ function migrateRuntime(root) {
   const changed = [];
   for (let v = from; v < RUNTIME_VERSION; v++) {
     const step = STEPS[v];
-    changed.push(...step.run(root));
+    changed.push(...step.run(root, { dryRun }));
     applied.push({ from: step.from, to: step.to });
   }
-  return { from, to: RUNTIME_VERSION, applied, changed };
+  return { from, to: RUNTIME_VERSION, applied, changed, dryRun };
 }
 
 // ../../packages/core/src/repos.ts
@@ -1002,7 +1020,8 @@ function parseArgs(argv) {
     all: false,
     archived: false,
     open: false,
-    noHydrate: false
+    noHydrate: false,
+    dryRun: false
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -1024,6 +1043,8 @@ function parseArgs(argv) {
       flags.open = true;
     } else if (a === "--no-hydrate") {
       flags.noHydrate = true;
+    } else if (a === "--dry-run") {
+      flags.dryRun = true;
     } else if (a.startsWith("--") && a.includes("=")) {
       const eq = a.indexOf("=");
       const key = VALUE_FLAGS[a.slice(0, eq)];
@@ -1109,7 +1130,7 @@ Global:
   mx info [--all] [--porcelain]          show runtime version, repos, works, ports (active only by default; --all to include archived; alias: mx i)
   mx sync                                re-stamp runtime files (CLAUDE.md, scaffolding) from current templates \u2014 same-major, non-breaking
   mx update                              self-update the mx CLI within its major (npm i -g); flags a newer major if one exists
-  mx migrate                             upgrade an older-version runtime to the version this CLI supports (the only command allowed on a mismatched runtime)
+  mx migrate [--dry-run]                 upgrade an older-version runtime to the version this CLI supports (the only command allowed on a mismatched runtime); --dry-run previews the plan without changing anything
   mx help | version
 
 Repos (pristine clones):
@@ -1276,13 +1297,26 @@ function runGlobal(positionals, flags) {
     }
     case "migrate": {
       const root = requireRuntime({ runtime: flags.runtime, allowVersionMismatch: true });
-      const res = migrateRuntime(root);
+      const res = migrateRuntime(root, { dryRun: flags.dryRun });
       emit(() => {
         if (res.applied.length === 0) {
           console.log(`${check()} Runtime already at v${res.to} \u2014 nothing to migrate.`);
           return;
         }
         const steps = res.applied.map((a) => `v${a.from}\u2192v${a.to}`).join(", ");
+        if (res.dryRun) {
+          console.log(
+            `${dim("[dry run]")} Would migrate runtime ${bold(`v${res.from}\u2192v${res.to}`)} ${dim(`(${steps})`)}`
+          );
+          if (res.changed.length === 0) {
+            console.log(`  ${dim("(no path changes \u2014 version stamp only)")}`);
+          } else {
+            for (const p of res.changed) console.log(`  ${dim(`+ ${p}`)}`);
+          }
+          console.log();
+          console.log(`  ${dim("No changes were made. Re-run without --dry-run to apply.")}`);
+          return;
+        }
         console.log(
           `${check()} Migrated runtime ${bold(`v${res.from}\u2192v${res.to}`)} ${dim(`(${steps})`)}`
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roulabs/mx",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "mx — run several features in parallel across shared repos using git worktrees",
   "type": "module",
   "bin": {