@roulabs/mx 2.3.0 → 2.5.0

package/README.md

@@ -43,8 +43,9 @@ 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 new <name> [--quick] [-o]` | create a fresh local repo with no remote (git init on main + README + initial commit); `--quick` also makes a `dev-<name>` work + a `develop` worktree (quick-experiment one-shot) |
 | `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`) |
 | `mx work new <name> [--description <t>] [-o]` | create a work; `-o` opens a fullscreen Terminal + editor (macOS) |

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
@@ -528,6 +546,28 @@ function repoAdd(root, url, name0) {
   git(["clone", url, gitdir], { stdio: ["ignore", "inherit", "inherit"] });
   return { name, path: container, remote: remoteUrl(gitdir), branch: currentBranch(gitdir) };
 }
+function repoNew(root, name, opts = {}) {
+  if (!name || name.includes("/") || name.includes("\\") || name === "." || name === "..") {
+    throw new MxError(`invalid repo name: ${JSON.stringify(name)}`, "BAD_ARGS");
+  }
+  const container = repoPath(root, name);
+  if (exists(container)) throw new MxError(`repo already exists: ${name}`, "EXISTS");
+  const gitdir = repoGitDir(root, name);
+  fs5.mkdirSync(gitdir, { recursive: true });
+  git(["-C", gitdir, "init", "-q", "-b", "main"]);
+  const withReadme = opts.readme !== false;
+  if (withReadme) {
+    fs5.writeFileSync(path4.join(gitdir, "README.md"), `# ${name}
+`);
+    git(["-C", gitdir, "add", "README.md"]);
+  }
+  const haveIdentity = gitQuiet(["-C", gitdir, "config", "user.name"]) !== null && gitQuiet(["-C", gitdir, "config", "user.email"]) !== null;
+  const idArgs = haveIdentity ? [] : ["-c", "user.name=mx", "-c", "user.email=mx@localhost"];
+  const commitArgs = ["-C", gitdir, ...idArgs, "commit", "-q", "-m", "init"];
+  if (!withReadme) commitArgs.push("--allow-empty");
+  git(commitArgs);
+  return { name, path: container, remote: null, branch: currentBranch(gitdir) };
+}
 function listReposInfo(root) {
   return listRepoNames(root).map((name) => ({
     name,
@@ -1002,7 +1042,9 @@ function parseArgs(argv) {
     all: false,
     archived: false,
     open: false,
-    noHydrate: false
+    noHydrate: false,
+    dryRun: false,
+    quick: false
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -1024,6 +1066,10 @@ 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 === "--quick") {
+      flags.quick = true;
     } else if (a.startsWith("--") && a.includes("=")) {
       const eq = a.indexOf("=");
       const key = VALUE_FLAGS[a.slice(0, eq)];
@@ -1109,11 +1155,12 @@ 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):
   mx repo add <git-url> [--name <n>]     clone a repo into the runtime
+  mx repo new <name> [--quick] [-o]      create a fresh local repo (no remote); --quick also makes a dev-<name> work + develop worktree
   mx repo ls [--porcelain]
   mx repo -n <name> path                 print the repo container path (cd "$(mx repo -n <name> path)")
   mx repo -n <name> fetch                git fetch (+ ff the checked-out and base branches)
@@ -1276,13 +1323,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})`)}`
         );
@@ -1378,6 +1438,107 @@ function renderStatus(data) {
   console.log();
 }
 
+// src/open.ts
+import { execFileSync as execFileSync3 } from "child_process";
+function osascript(script) {
+  try {
+    execFileSync3("osascript", ["-e", script], { stdio: ["ignore", "ignore", "pipe"] });
+  } catch (e) {
+    const err = e;
+    throw new MxError(
+      `osascript failed: ${(err.stderr ?? err.message ?? "").toString().trim()}`,
+      "OSASCRIPT"
+    );
+  }
+}
+function aplStr(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function openWorkLayout(workdir, workspace) {
+  if (process.platform !== "darwin") {
+    throw new MxError("-o/--open is only supported on macOS", "UNSUPPORTED");
+  }
+  let editorProcess = "Cursor";
+  try {
+    execFileSync3("open", ["-a", "Cursor", workspace], { stdio: "ignore" });
+  } catch {
+    try {
+      execFileSync3("open", ["-a", "Visual Studio Code", workspace], { stdio: "ignore" });
+      editorProcess = "Code";
+    } catch {
+      editorProcess = "";
+    }
+  }
+  osascript(
+    [
+      'tell application "Terminal"',
+      "  activate",
+      "  set winCountBefore to count of windows",
+      `  do script "cd \\"${aplStr(workdir)}\\""`,
+      "  delay 0.5",
+      "  set winCountAfter to count of windows",
+      "end tell",
+      "if winCountAfter is less than or equal to winCountBefore then",
+      '  tell application "System Events" to tell process "Terminal"',
+      "    try",
+      '      click menu item "Move Tab to New Window" of menu "Window" of menu bar 1',
+      "      delay 0.4",
+      "    end try",
+      "  end tell",
+      "end if",
+      'tell application "System Events" to tell process "Terminal"',
+      "  try",
+      '    set value of attribute "AXFullScreen" of window 1 to true',
+      "  end try",
+      "end tell"
+    ].join("\n")
+  );
+  if (editorProcess) {
+    const appName = editorProcess === "Code" ? "Visual Studio Code" : "Cursor";
+    osascript(
+      [
+        `tell application "${appName}" to activate`,
+        // wait until the app is frontmost (cold launch can take a few seconds)
+        'tell application "System Events"',
+        "  set n to 0",
+        `  repeat until (exists process "${editorProcess}") and (frontmost of process "${editorProcess}" is true)`,
+        "    delay 0.3",
+        "    set n to n + 1",
+        "    if n > 40 then exit repeat",
+        "  end repeat",
+        "end tell",
+        // let the workbench finish loading so it accepts the keybinding
+        "delay 1.2",
+        'tell application "System Events" to key code 3 using {control down, command down}'
+      ].join("\n")
+    );
+  }
+}
+
+// src/hydrate.ts
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+function runWorktreeHydrate(ctx, quiet) {
+  const script = repoHydrateScript(ctx.root, ctx.repo);
+  if (!existsSync2(script)) return { ran: false, ok: true, missing: true };
+  const env = {
+    ...process.env,
+    MX_RUNTIME: ctx.root,
+    MX_WORK: ctx.work,
+    MX_REPO: ctx.repo,
+    MX_WORKTREE_PATH: ctx.worktreePath,
+    MX_BRANCH: ctx.branch,
+    MX_BASE: ctx.base ?? "",
+    MX_WORK_PATH: workPath(ctx.root, ctx.work).path
+  };
+  const r = spawnSync3(script, [ctx.worktreePath, ctx.branch], {
+    cwd: ctx.worktreePath,
+    env,
+    stdio: quiet ? ["ignore", "ignore", "ignore"] : "inherit"
+  });
+  return { ran: true, ok: r.status === 0, missing: false };
+}
+
 // src/commands/repo.ts
 function need(v, msg) {
   if (v == null || v === "") throw new MxError(msg, "BAD_ARGS");
@@ -1395,6 +1556,57 @@ function dispatchRepo(positionals, flags) {
       emit(() => console.log(`${check()} cloned ${bold(res.name)} ${dim(`\u2192 ${res.path}`)}`), res);
       return;
     }
+    case "new": {
+      const name = need(
+        positionals[2],
+        "usage: mx repo new <name> [--quick] [-o] [--description <t>]"
+      );
+      const res = repoNew(root, name);
+      stampRepoScripts(repoPath(root, res.name), templatesDir());
+      if (!flags.quick) {
+        emit(() => {
+          console.log(`${check()} created repo ${bold(res.name)} ${dim("(local, no remote)")}`);
+          console.log(`  ${dim(res.path)}`);
+          console.log(`  ${dim(`next: mx repo new ${res.name} --quick -o (or add it to a work yourself)`)}`);
+        }, res);
+        return;
+      }
+      const workName = `dev-${name}`;
+      const workRes = workNew(root, workName, flags.description ?? "");
+      const wtRes = worktreeAdd(root, workName, name, { branch: "develop" });
+      if (!flags.noHydrate) {
+        const outcome = runWorktreeHydrate(
+          { root, work: workName, repo: name, worktreePath: wtRes.path, branch: wtRes.branch },
+          flags.porcelain
+        );
+        if (outcome.ran && !outcome.ok && !flags.porcelain) {
+          process.stderr.write(
+            `${warn()} ${dim(`hydrate.sh exited non-zero \u2014 worktree kept. Re-run: mx work -n ${workName} worktree hydrate ${name}`)}
+`
+          );
+        }
+      }
+      let opened = false;
+      if (flags.open) {
+        try {
+          openWorkLayout(workRes.path, workspaceFile(root, workName));
+          opened = true;
+        } catch (e) {
+          const msg = e instanceof MxError ? e.message : String(e);
+          process.stderr.write(`${warn()} ${dim(`could not open layout: ${msg}`)}
+`);
+        }
+      }
+      emit(() => {
+        console.log(`${check()} created repo ${bold(res.name)} ${dim("(local, no remote)")}`);
+        console.log(`${check()} created work ${bold(workRes.name)} ${dim(`\u2192 ${workRes.path}`)}`);
+        console.log(
+          `${check()} added worktree ${bold(wtRes.repo)} ${dim(`[${wtRes.branch}]`)} ${dim(`\u2192 ${wtRes.path}`)}`
+        );
+        if (opened) console.log(`${check()} opened ${dim("(Terminal + editor)")}`);
+      }, { repo: res, work: workRes, worktree: wtRes, opened });
+      return;
+    }
     case "ls": {
       const repos = listReposInfo(root);
       emit(() => {
@@ -1592,107 +1804,6 @@ function renderHealthDetail(h) {
 // src/commands/work.ts
 import * as path8 from "path";
 
-// src/open.ts
-import { execFileSync as execFileSync3 } from "child_process";
-function osascript(script) {
-  try {
-    execFileSync3("osascript", ["-e", script], { stdio: ["ignore", "ignore", "pipe"] });
-  } catch (e) {
-    const err = e;
-    throw new MxError(
-      `osascript failed: ${(err.stderr ?? err.message ?? "").toString().trim()}`,
-      "OSASCRIPT"
-    );
-  }
-}
-function aplStr(s) {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-function openWorkLayout(workdir, workspace) {
-  if (process.platform !== "darwin") {
-    throw new MxError("-o/--open is only supported on macOS", "UNSUPPORTED");
-  }
-  let editorProcess = "Cursor";
-  try {
-    execFileSync3("open", ["-a", "Cursor", workspace], { stdio: "ignore" });
-  } catch {
-    try {
-      execFileSync3("open", ["-a", "Visual Studio Code", workspace], { stdio: "ignore" });
-      editorProcess = "Code";
-    } catch {
-      editorProcess = "";
-    }
-  }
-  osascript(
-    [
-      'tell application "Terminal"',
-      "  activate",
-      "  set winCountBefore to count of windows",
-      `  do script "cd \\"${aplStr(workdir)}\\""`,
-      "  delay 0.5",
-      "  set winCountAfter to count of windows",
-      "end tell",
-      "if winCountAfter is less than or equal to winCountBefore then",
-      '  tell application "System Events" to tell process "Terminal"',
-      "    try",
-      '      click menu item "Move Tab to New Window" of menu "Window" of menu bar 1',
-      "      delay 0.4",
-      "    end try",
-      "  end tell",
-      "end if",
-      'tell application "System Events" to tell process "Terminal"',
-      "  try",
-      '    set value of attribute "AXFullScreen" of window 1 to true',
-      "  end try",
-      "end tell"
-    ].join("\n")
-  );
-  if (editorProcess) {
-    const appName = editorProcess === "Code" ? "Visual Studio Code" : "Cursor";
-    osascript(
-      [
-        `tell application "${appName}" to activate`,
-        // wait until the app is frontmost (cold launch can take a few seconds)
-        'tell application "System Events"',
-        "  set n to 0",
-        `  repeat until (exists process "${editorProcess}") and (frontmost of process "${editorProcess}" is true)`,
-        "    delay 0.3",
-        "    set n to n + 1",
-        "    if n > 40 then exit repeat",
-        "  end repeat",
-        "end tell",
-        // let the workbench finish loading so it accepts the keybinding
-        "delay 1.2",
-        'tell application "System Events" to key code 3 using {control down, command down}'
-      ].join("\n")
-    );
-  }
-}
-
-// src/hydrate.ts
-import { spawnSync as spawnSync3 } from "child_process";
-import { existsSync as existsSync2 } from "fs";
-function runWorktreeHydrate(ctx, quiet) {
-  const script = repoHydrateScript(ctx.root, ctx.repo);
-  if (!existsSync2(script)) return { ran: false, ok: true, missing: true };
-  const env = {
-    ...process.env,
-    MX_RUNTIME: ctx.root,
-    MX_WORK: ctx.work,
-    MX_REPO: ctx.repo,
-    MX_WORKTREE_PATH: ctx.worktreePath,
-    MX_BRANCH: ctx.branch,
-    MX_BASE: ctx.base ?? "",
-    MX_WORK_PATH: workPath(ctx.root, ctx.work).path
-  };
-  const r = spawnSync3(script, [ctx.worktreePath, ctx.branch], {
-    cwd: ctx.worktreePath,
-    env,
-    stdio: quiet ? ["ignore", "ignore", "ignore"] : "inherit"
-  });
-  return { ran: true, ok: r.status === 0, missing: false };
-}
-
 // src/workhooks.ts
 import { spawnSync as spawnSync4 } from "child_process";
 import { existsSync as existsSync3 } from "fs";

package/package.json

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

package/templates/CLAUDE.md

@@ -293,6 +293,10 @@ clarity; dropping it works while you're inside the work.
   - After the worktree is created, the repo's `repos/<repo>/hydrate.sh` runs automatically with the new
     worktree as the working directory (copy a `.env`, install deps, etc.). Pass `--no-hydrate` to skip it,
     or re-run it later with `mx work -n <feature> worktree hydrate <repo>`.
+- **Spin up a quick local app (no remote):** for a throwaway/experiment repo you don't want on GitHub,
+  `mx repo new <name>` creates a fresh local repo (git init on `main` + README + initial commit). Add
+  `--quick` (and `-o`) to also create a `dev-<name>` work + a worktree on `develop` and open it in one
+  shot: `mx repo new <name> --quick -o`. Like adding any repo/worktree, **ask the user first.**
 - **Allocate a port:** `mx work -n <feature> port set <repo> <service>` returns a free port (unique
   across all works). This only records the port in `work.json` — **you** must then wire that port
   into the repo's own env/config (`.env`, `PORT=`, etc.) and remap any outbound URL to a sibling