@roulabs/mx 2.2.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", "files", "tmp", "sessions", "hooks"]) {
+  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.2.0",
+  "version": "2.4.0",
   "description": "mx — run several features in parallel across shared repos using git worktrees",
   "type": "module",
   "bin": {

package/templates/CLAUDE.md

@@ -70,6 +70,7 @@ mx/
         │   ├── repo-a/     # worktree of repo-a on this feature's branch
         │   └── repo-b/     # worktree of repo-b on this feature's branch
         ├── scripts/        # ad-hoc per-work scripts
+        ├── bin/            # executables/binaries a session builds or fetches
         ├── files/          # artifacts worth keeping (agent/user drop zone)
         ├── tmp/            # throwaway scratch — may be deleted at any time
         ├── hooks/          # per-work lifecycle hooks (see § Work lifecycle hooks)
@@ -91,7 +92,7 @@ mx/
 - `works/<feature>/hooks/` holds **per-work lifecycle hooks** — mx-owned scripts mx runs around
   `mx work archive`/`unarchive`. mx stamps documented no-op scripts you customize (see § Work
   lifecycle hooks).
-- `works/<feature>/{scripts,files,tmp}/` are the only places to put non-mx files in a work — see
+- `works/<feature>/{scripts,bin,files,tmp}/` are the only places to put non-mx files in a work — see
   § The work folder holds mx-native files only.
 
 ## Work lifecycle hooks
@@ -131,6 +132,8 @@ subfolders. When you or the user need to write anything else, use one of these,
 - **`tmp/`** — throwaway scratch. Its contents may be deleted at **any** time, with no guarantees —
   never rely on anything here persisting.
 - **`scripts/`** — ad-hoc scripts for this work.
+- **`bin/`** — executables and binaries this work needs: tools you compile, CLIs you download, helper
+  binaries. Add it to `PATH` for the work if useful. Starts empty.
 
 The one exception: a runtime file a session legitimately needs to create at the work root for tooling
 to work (e.g. an MCP connection file like `.<something>-mcp`) is fine. The rule targets *ad-hoc*
@@ -306,7 +309,7 @@ clarity; dropping it works while you're inside the work.
 5. **Don't destroy anything unless asked.** Worktrees stay until the user confirms the feature is merged.
    Teardown keeps feature branches; never delete them.
 6. **Never create ad-hoc files in the work-folder root.** Keepable artifacts go in `files/`, throwaway
-   scratch in `tmp/`, scripts in `scripts/`. The root is mx-native only (only exception: a tooling
+   scratch in `tmp/`, scripts in `scripts/`, executables/binaries in `bin/`. The root is mx-native only (only exception: a tooling
    file a session genuinely needs there, e.g. an MCP connection file). See § The work folder holds
    mx-native files only.