@roulabs/mx 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rousan Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# mx
+
+**mx** ("multiplexer") runs several features in parallel across shared repos using git worktrees. Each feature gets an isolated environment — its own worktrees, branches, and ports — so you switch between features instantly without stashing or branch-juggling.
+
+mx manages a **runtime**: a single `mx/` folder holding pristine repo clones (`repos/`) and one folder per feature (`works/`), each with git worktrees on its own branch. mx owns the per-work manifest (`work.json`) and a VS Code workspace file; you drive everything through `mx` commands.
+
+## Install
+
+```bash
+npm install -g @roulabs/mx      # provides the `mx` command
+```
+
+Requires Node >= 22 and git.
+
+## Point mx at a runtime
+
+mx resolves its runtime in this order: `--runtime <path>` flag, then `$MX_RUNTIME`, then the default `~/mx`. Set it once in your shell:
+
+```bash
+export MX_RUNTIME="$HOME/mx"
+```
+
+## Quick start
+
+```bash
+mx init                                  # scaffold the runtime (at $MX_RUNTIME or ~/mx)
+mx repo add git@github.com:you/app.git   # clone a pristine repo into the runtime
+mx work new my-feature                   # create a work (prints its folder path)
+mx work -n my-feature worktree add app   # add a worktree on branch my-feature
+mx work -n my-feature port set app web   # allocate a free port (across all works)
+mx status                                # see repos, works, worktrees, ports
+```
+
+Inside a work folder or worktree you can drop `-n` — mx infers the work/repo from your cwd. Read commands accept `--porcelain` for stable JSON; errors are `{"error","code"}` with a non-zero exit.
+
+## Commands
+
+| command | does |
+|---|---|
+| `mx init [path]` | scaffold/adopt a runtime (`repos/`, `works/`, `.mx-root`, `CLAUDE.md`) |
+| `mx status [--porcelain]` | list repos, works, worktrees, ports |
+| `mx update` | re-stamp the runtime's `CLAUDE.md` |
+| `mx repo add <git-url> [--name <n>]` | clone a pristine repo |
+| `mx repo ls` / `mx repo -n <name> fetch\|info\|rm` | manage pristine repos |
+| `mx work new <name> [--description <t>]` | create a work |
+| `mx work ls` / `mx work -n <name> info\|describe\|path` | manage works |
+| `mx work -n <name> worktree add\|ls\|rm <repo> [--branch <b>] [--base <ref>]` | manage worktrees |
+| `mx work -n <name> port set\|unset\|ls <repo> <service> [<port>]` | allocate/release ports |
+| `mx work -n <name> destroy` | remove worktrees + work folder (keeps branches) |
+
+## License
+
+MIT

package/bin/mx.js

@@ -0,0 +1,869 @@
+#!/usr/bin/env node
+
+// ../../packages/core/src/errors.ts
+var MxError = class extends Error {
+  /**
+   * Stable error code identifying the failure category. Surfaced verbatim in
+   * the CLI's `--porcelain` error output.
+   */
+  code;
+  /**
+   * @param message - Human-readable explanation of the failure.
+   * @param code - Stable category code; defaults to a generic `ERROR`.
+   */
+  constructor(message, code = "ERROR") {
+    super(message);
+    this.name = "MxError";
+    this.code = code;
+  }
+};
+
+// ../../packages/core/src/runtime.ts
+import * as fs4 from "fs";
+import * as os from "os";
+import * as path3 from "path";
+
+// ../../packages/core/src/fsutil.ts
+import * as fs from "fs";
+import * as path from "path";
+function exists(p) {
+  return fs.existsSync(p);
+}
+function isGitRepo(dir) {
+  return exists(path.join(dir, ".git"));
+}
+function listDirs(dir) {
+  if (!exists(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".")).map((d) => d.name).sort();
+}
+function realpath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+// ../../packages/core/src/json.ts
+import * as fs2 from "fs";
+function readJson(file) {
+  return JSON.parse(fs2.readFileSync(file, "utf8"));
+}
+function writeJson(file, obj) {
+  const tmp = file + ".tmp";
+  fs2.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
+  fs2.renameSync(tmp, file);
+}
+
+// ../../packages/core/src/templates.ts
+import * as fs3 from "fs";
+import * as path2 from "path";
+function stampClaudeMd(targetDir, templatesDir2) {
+  const src = path2.join(templatesDir2, "CLAUDE.md");
+  if (!exists(src)) throw new MxError(`missing template: ${src}`, "NO_TEMPLATE");
+  const dest = path2.join(targetDir, "CLAUDE.md");
+  fs3.copyFileSync(src, dest);
+  return dest;
+}
+function removeStaleRuntimeReadme(targetDir) {
+  const readme = path2.join(targetDir, "README.md");
+  if (exists(readme)) {
+    fs3.rmSync(readme);
+    return true;
+  }
+  return false;
+}
+
+// ../../packages/core/src/runtime.ts
+var DEFAULT_RUNTIME = path3.join(os.homedir(), "mx");
+function defaultRuntime() {
+  return path3.resolve(DEFAULT_RUNTIME);
+}
+var reposDir = (root) => path3.join(root, "repos");
+var worksDir = (root) => path3.join(root, "works");
+var repoPath = (root, name) => path3.join(reposDir(root), name);
+var workDir = (root, name) => path3.join(worksDir(root), name);
+var workManifest = (root, name) => path3.join(workDir(root, name), "work.json");
+var workspaceFile = (root, name) => path3.join(workDir(root, name), `${name}.code-workspace`);
+function discoverRuntime(opts = {}) {
+  const p = opts.runtime || process.env.MX_RUNTIME || DEFAULT_RUNTIME;
+  return path3.resolve(p);
+}
+function requireRuntime(opts = {}) {
+  const root = discoverRuntime(opts);
+  if (!exists(path3.join(root, ".mx-root"))) {
+    throw new MxError(`not an mx runtime (no .mx-root): ${root} \u2014 run \`mx init\``, "NO_RUNTIME");
+  }
+  return root;
+}
+function listRepoNames(root) {
+  return listDirs(reposDir(root)).filter((n) => isGitRepo(repoPath(root, n)));
+}
+function listWorkNames(root) {
+  return listDirs(worksDir(root)).filter((n) => exists(workManifest(root, n)));
+}
+function readWork(root, name) {
+  const file = workManifest(root, name);
+  if (!exists(file)) {
+    if (!exists(workDir(root, name))) throw new MxError(`no such work: ${name}`, "NO_WORK");
+    throw new MxError(
+      `work "${name}" has no work.json \u2014 recreate it with \`mx work new\``,
+      "NO_MANIFEST"
+    );
+  }
+  return readJson(file);
+}
+function writeWork(root, work) {
+  writeJson(workManifest(root, work.name), work);
+}
+function findWorktree(work, repo) {
+  return (work.worktrees ?? []).find((w) => w.repo === repo) ?? null;
+}
+function inferContext(root) {
+  const cwd = realpath(process.cwd());
+  const segmentsUnder = (base) => {
+    if (!exists(base)) return null;
+    const rel = path3.relative(realpath(base), cwd);
+    if (rel === "" || rel.startsWith("..") || path3.isAbsolute(rel)) return null;
+    return rel.split(path3.sep);
+  };
+  const w = segmentsUnder(worksDir(root));
+  if (w) return { work: w[0], repo: w[1] ?? null };
+  const r = segmentsUnder(reposDir(root));
+  if (r) return { work: null, repo: r[0] };
+  return { work: null, repo: null };
+}
+function initRuntime(target0, templatesDir2) {
+  const target = path3.resolve(target0);
+  const created = [];
+  for (const d of [target, reposDir(target), worksDir(target)]) {
+    if (!exists(d)) {
+      fs4.mkdirSync(d, { recursive: true });
+      created.push(d);
+    }
+  }
+  const marker = path3.join(target, ".mx-root");
+  if (!exists(marker)) {
+    fs4.writeFileSync(marker, "");
+    created.push(marker);
+  }
+  created.push(stampClaudeMd(target, templatesDir2));
+  removeStaleRuntimeReadme(target);
+  return { runtime: target, created };
+}
+function updateRuntime(root, templatesDir2) {
+  const dest = stampClaudeMd(root, templatesDir2);
+  removeStaleRuntimeReadme(root);
+  return { runtime: root, updated: [dest] };
+}
+
+// ../../packages/core/src/repos.ts
+import * as fs5 from "fs";
+
+// ../../packages/core/src/git.ts
+import { execFileSync } from "child_process";
+function git(args, opts = {}) {
+  try {
+    const out = execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...opts
+    });
+    return (out == null ? "" : String(out)).trim();
+  } catch (e) {
+    const err = e;
+    const msg = (err.stderr ?? err.stdout ?? err.message ?? "").toString().trim();
+    throw new MxError(`git ${args.join(" ")} failed: ${msg}`, "GIT");
+  }
+}
+function gitQuiet(args, opts = {}) {
+  try {
+    const out = execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      ...opts
+    });
+    return (out == null ? "" : String(out)).trim();
+  } catch {
+    return null;
+  }
+}
+function currentBranch(repoPath2) {
+  return gitQuiet(["-C", repoPath2, "rev-parse", "--abbrev-ref", "HEAD"]) ?? "(detached)";
+}
+function remoteUrl(repoPath2) {
+  return gitQuiet(["-C", repoPath2, "remote", "get-url", "origin"]) ?? gitQuiet(["-C", repoPath2, "config", "--get", "remote.origin.url"]) ?? null;
+}
+function branchExists(repoPath2, branch) {
+  return gitQuiet(["-C", repoPath2, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]) !== null;
+}
+function isDirty(worktreePath) {
+  const s = gitQuiet(["-C", worktreePath, "status", "--porcelain"]);
+  return s == null ? false : s.length > 0;
+}
+function remoteBranchList(repoPath2) {
+  const out = gitQuiet(["-C", repoPath2, "for-each-ref", "--format=%(refname)", "refs/remotes/origin"]);
+  if (!out) return [];
+  return out.split("\n").map((s) => s.trim()).filter((s) => s && !s.endsWith("/HEAD")).map((s) => s.replace(/^refs\/remotes\/origin\//, ""));
+}
+function resolveBase(repoPath2, base) {
+  return gitQuiet(["-C", repoPath2, "rev-parse", "--verify", `${base}^{commit}`]) ?? gitQuiet(["-C", repoPath2, "rev-parse", "--verify", `origin/${base}^{commit}`]) ?? null;
+}
+
+// ../../packages/core/src/repos.ts
+function repoNameFromUrl(url) {
+  const base = url.split("/").pop() || url;
+  return base.replace(/\.git$/, "");
+}
+function repoAdd(root, url, name0) {
+  const name = name0 || repoNameFromUrl(url);
+  const dest = repoPath(root, name);
+  if (exists(dest)) throw new MxError(`repo already exists: ${name}`, "EXISTS");
+  git(["clone", url, dest], { stdio: ["ignore", "inherit", "inherit"] });
+  return { name, path: dest, remote: remoteUrl(dest), branch: currentBranch(dest) };
+}
+function listReposInfo(root) {
+  return listRepoNames(root).map((name) => ({
+    name,
+    branch: currentBranch(repoPath(root, name)),
+    remote: remoteUrl(repoPath(root, name))
+  }));
+}
+function repoFetch(root, name) {
+  const rp = repoPath(root, name);
+  if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
+  git(["-C", rp, "fetch", "--all", "--prune", "--tags"]);
+  gitQuiet(["-C", rp, "merge", "--ff-only", "@{u}"]);
+  return { name, branch: currentBranch(rp), remoteBranches: remoteBranchList(rp) };
+}
+function repoInfo(root, name) {
+  const rp = repoPath(root, name);
+  if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
+  const usedBy = listWorkNames(root).filter((w) => findWorktree(readWork(root, w), name));
+  return {
+    name,
+    path: rp,
+    branch: currentBranch(rp),
+    remote: remoteUrl(rp),
+    worktreesInWorks: usedBy
+  };
+}
+function repoRemove(root, name) {
+  const rp = repoPath(root, name);
+  if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
+  const usedBy = listWorkNames(root).filter((w) => findWorktree(readWork(root, w), name));
+  if (usedBy.length) {
+    throw new MxError(
+      `repo "${name}" still has worktrees in: ${usedBy.join(", ")} \u2014 remove those first`,
+      "IN_USE"
+    );
+  }
+  fs5.rmSync(rp, { recursive: true, force: true });
+  return { name, removed: true };
+}
+
+// ../../packages/core/src/works.ts
+import * as fs6 from "fs";
+import * as path4 from "path";
+function addFolderToWorkspace(root, name, repo) {
+  const file = workspaceFile(root, name);
+  const ws = exists(file) ? readJson(file) : { folders: [], settings: {} };
+  ws.folders = ws.folders ?? [];
+  if (!ws.folders.some((f) => f.path === repo)) ws.folders.push({ name: repo, path: repo });
+  writeJson(file, ws);
+}
+function removeFolderFromWorkspace(root, name, repo) {
+  const file = workspaceFile(root, name);
+  if (!exists(file)) return;
+  const ws = readJson(file);
+  ws.folders = (ws.folders ?? []).filter((f) => f.path !== repo);
+  writeJson(file, ws);
+}
+function workNew(root, name, description = "") {
+  const dir = workDir(root, name);
+  if (exists(dir)) throw new MxError(`work already exists: ${name}`, "EXISTS");
+  fs6.mkdirSync(dir, { recursive: true });
+  const work = { name, description, worktrees: [] };
+  writeWork(root, work);
+  writeJson(workspaceFile(root, name), { folders: [], settings: {} });
+  return { ...work, path: dir };
+}
+function listWorksInfo(root) {
+  return listWorkNames(root).map((name) => {
+    const w = readWork(root, name);
+    return { name, description: w.description ?? "", worktrees: (w.worktrees ?? []).length };
+  });
+}
+function workInfo(root, name) {
+  return readWork(root, name);
+}
+function workDescribe(root, name, text) {
+  const work = readWork(root, name);
+  work.description = text;
+  writeWork(root, work);
+  return work;
+}
+function workPath(root, name) {
+  const dir = workDir(root, name);
+  if (!exists(dir)) throw new MxError(`no such work: ${name}`, "NO_WORK");
+  return { name, path: dir };
+}
+function worktreeAdd(root, name, repo, opts = {}) {
+  const work = readWork(root, name);
+  const rp = repoPath(root, repo);
+  if (!isGitRepo(rp)) throw new MxError(`no such repo: ${repo}`, "NO_REPO");
+  if (findWorktree(work, repo)) {
+    throw new MxError(`work "${name}" already has worktree for ${repo}`, "EXISTS");
+  }
+  const branch = opts.branch || name;
+  const dest = path4.join(workDir(root, name), repo);
+  if (branchExists(rp, branch)) {
+    git(["-C", rp, "worktree", "add", dest, branch]);
+  } else {
+    const args = ["-C", rp, "worktree", "add", "-b", branch, dest];
+    if (opts.base) {
+      const sha = resolveBase(rp, opts.base);
+      if (!sha) {
+        throw new MxError(`base ref not found: ${opts.base} (tried also origin/${opts.base})`, "NO_REF");
+      }
+      args.push(sha);
+    }
+    git(args);
+  }
+  work.worktrees = work.worktrees ?? [];
+  work.worktrees.push({ repo, branch, ports: {} });
+  writeWork(root, work);
+  addFolderToWorkspace(root, name, repo);
+  return { work: name, repo, branch, path: dest, ports: {} };
+}
+function worktreeList(root, name) {
+  return readWork(root, name).worktrees ?? [];
+}
+function worktreeRemove(root, name, repo) {
+  const work = readWork(root, name);
+  const wt = findWorktree(work, repo);
+  if (!wt) throw new MxError(`work "${name}" has no worktree for ${repo}`, "NO_WORKTREE");
+  const dest = path4.join(workDir(root, name), repo);
+  if (exists(dest) && isDirty(dest)) {
+    throw new MxError(`worktree ${repo} has uncommitted changes \u2014 commit or discard them first`, "DIRTY");
+  }
+  git(["-C", repoPath(root, repo), "worktree", "remove", dest]);
+  work.worktrees = work.worktrees.filter((w) => w.repo !== repo);
+  writeWork(root, work);
+  removeFolderFromWorkspace(root, name, repo);
+  return { work: name, repo, branch: wt.branch, removed: true };
+}
+function workDestroy(root, name) {
+  const work = readWork(root, name);
+  const dirty = [];
+  for (const wt of work.worktrees ?? []) {
+    const dest = path4.join(workDir(root, name), wt.repo);
+    if (exists(dest) && isDirty(dest)) dirty.push(wt.repo);
+  }
+  if (dirty.length) {
+    throw new MxError(
+      `cannot destroy "${name}" \u2014 uncommitted changes in: ${dirty.join(", ")}. Commit or discard, then retry.`,
+      "DIRTY"
+    );
+  }
+  const removed = [];
+  for (const wt of work.worktrees ?? []) {
+    const dest = path4.join(workDir(root, name), wt.repo);
+    if (exists(dest)) git(["-C", repoPath(root, wt.repo), "worktree", "remove", dest]);
+    removed.push(wt.repo);
+  }
+  fs6.rmSync(workDir(root, name), { recursive: true, force: true });
+  return { work: name, removedWorktrees: removed, branchesKept: true };
+}
+
+// ../../packages/core/src/ports.ts
+var PORT_BASE = 3e3;
+function allocatedPorts(root, except = null) {
+  const used = /* @__PURE__ */ new Map();
+  for (const name of listWorkNames(root)) {
+    let work;
+    try {
+      work = readWork(root, name);
+    } catch {
+      continue;
+    }
+    for (const wt of work.worktrees ?? []) {
+      for (const [service, port] of Object.entries(wt.ports ?? {})) {
+        if (except && except.work === name && except.repo === wt.repo && except.service === service) {
+          continue;
+        }
+        used.set(Number(port), `${name}/${wt.repo}/${service}`);
+      }
+    }
+  }
+  return used;
+}
+function nextFreePort(used) {
+  let p = PORT_BASE;
+  while (used.has(p)) p++;
+  return p;
+}
+function portSet(root, name, repo, service, port) {
+  const work = readWork(root, name);
+  const wt = findWorktree(work, repo);
+  if (!wt) throw new MxError(`work "${name}" has no worktree for ${repo} \u2014 add it first`, "NO_WORKTREE");
+  wt.ports = wt.ports ?? {};
+  const used = allocatedPorts(root, { work: name, repo, service });
+  let chosen;
+  if (port != null) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new MxError(`invalid port: ${port}`, "BAD_ARGS");
+    }
+    if (used.has(port)) {
+      throw new MxError(`port ${port} already allocated to ${used.get(port)}`, "PORT_TAKEN");
+    }
+    chosen = port;
+  } else {
+    chosen = nextFreePort(used);
+  }
+  wt.ports[service] = chosen;
+  writeWork(root, work);
+  return { work: name, repo, service, port: chosen };
+}
+function portUnset(root, name, repo, service) {
+  const work = readWork(root, name);
+  const wt = findWorktree(work, repo);
+  if (!wt || !wt.ports || !(service in wt.ports)) {
+    throw new MxError(`no port set for ${repo}.${service} in ${name}`, "NO_PORT");
+  }
+  const released = wt.ports[service];
+  delete wt.ports[service];
+  writeWork(root, work);
+  return { work: name, repo, service, released };
+}
+function portList(root, name) {
+  const work = readWork(root, name);
+  const map = {};
+  for (const wt of work.worktrees ?? []) map[wt.repo] = wt.ports ?? {};
+  return map;
+}
+
+// ../../packages/core/src/status.ts
+function statusRuntime(root) {
+  const repos = listReposInfo(root);
+  const works = listWorkNames(root).map((name) => readWork(root, name));
+  return { runtime: root, repos, works };
+}
+
+// src/args.ts
+var VALUE_FLAGS = {
+  "-n": "name",
+  "--name": "name",
+  "--runtime": "runtime",
+  "--description": "description",
+  "--branch": "branch",
+  "--base": "base"
+};
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = { porcelain: false, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--porcelain" || a === "--json") {
+      flags.porcelain = true;
+    } else if (a === "--help" || a === "-h") {
+      flags.help = true;
+    } else if (a === "--version" || a === "-v") {
+      flags.version = true;
+    } else if (a.startsWith("--") && a.includes("=")) {
+      const eq = a.indexOf("=");
+      const key = VALUE_FLAGS[a.slice(0, eq)];
+      if (!key) throw new MxError(`unknown flag: ${a.slice(0, eq)}`, "BAD_ARGS");
+      flags[key] = a.slice(eq + 1);
+    } else {
+      const key = VALUE_FLAGS[a];
+      if (key) flags[key] = argv[++i];
+      else positionals.push(a);
+    }
+  }
+  return { positionals, flags };
+}
+
+// src/output.ts
+var porcelain = false;
+function setPorcelain(value) {
+  porcelain = value;
+}
+function emit(human, data) {
+  if (porcelain) {
+    process.stdout.write(JSON.stringify(data ?? null, null, 2) + "\n");
+  } else if (typeof human === "function") {
+    human();
+  } else if (human != null) {
+    process.stdout.write(human + "\n");
+  }
+}
+function fail(err) {
+  const code = err instanceof MxError ? err.code : "INTERNAL";
+  const message = err instanceof Error ? err.message : String(err);
+  if (porcelain) {
+    process.stdout.write(JSON.stringify({ error: message, code }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`mx: ${message}
+`);
+  }
+  process.exit(1);
+}
+
+// src/help.ts
+var HELP = `mx \u2014 control panel for the mx runtime
+
+Global:
+  mx init [path]                         scaffold/adopt a runtime (default ~/mx)
+  mx status [--porcelain]                show runtime, repos, works, ports
+  mx update                              re-stamp runtime CLAUDE.md from templates
+  mx help | version
+
+Repos (pristine clones):
+  mx repo add <git-url> [--name <n>]     clone a repo into the runtime
+  mx repo ls [--porcelain]
+  mx repo -n <name> fetch                git fetch (+ ff current branch)
+  mx repo -n <name> info [--porcelain]
+  mx repo -n <name> rm                   refuses if any work uses it
+
+Works (features):
+  mx work new <name> [--description <t>]
+  mx work ls [--porcelain]
+  mx work -n <name> info [--porcelain]
+  mx work -n <name> path                 print the work folder path (cd "$(mx work -n <name> path)")
+  mx work -n <name> describe <text>
+  mx work -n <name> worktree add <repo> [--branch <b>] [--base <ref>]
+  mx work -n <name> worktree ls [--porcelain]
+  mx work -n <name> worktree rm <repo>   refuses on uncommitted changes; keeps branch
+  mx work -n <name> port set <repo> <service> [<port>]   auto-picks a free port if omitted
+  mx work -n <name> port unset <repo> <service>
+  mx work -n <name> port ls [--porcelain]
+  mx work -n <name> destroy              removes worktrees + folder; keeps branches
+
+The -n <name> selector may be omitted when your cwd implies it: inside a work folder or
+worktree (works/<work>/...) the work is inferred; inside repos/<repo>/... the repo is inferred.
+
+Runtime discovery: --runtime <path>  ->  $MX_RUNTIME  ->  default ~/mx.
+--porcelain emits stable JSON on reads; errors are {"error","code"} with a non-zero exit.
+`;
+
+// src/commands/global.ts
+import * as path6 from "path";
+
+// src/paths.ts
+import * as path5 from "path";
+import { fileURLToPath } from "url";
+function templatesDir() {
+  if (process.env.MX_TEMPLATES_DIR) return process.env.MX_TEMPLATES_DIR;
+  const here = path5.dirname(fileURLToPath(import.meta.url));
+  return path5.join(here, "..", "templates");
+}
+
+// src/commands/global.ts
+function runtimeEnvHint(runtime) {
+  const envRuntime = process.env.MX_RUNTIME ? path6.resolve(process.env.MX_RUNTIME) : null;
+  if (envRuntime === runtime) {
+    return ["", `$MX_RUNTIME already points here \u2014 you're set.`];
+  }
+  if (runtime === defaultRuntime() && !envRuntime) {
+    return ["", `This is the default mx runtime (~/mx) \u2014 no MX_RUNTIME setup needed.`];
+  }
+  return [
+    "",
+    `Point mx at this runtime by adding to your shell config (~/.zshrc, ~/.bashrc):`,
+    "",
+    `  export MX_RUNTIME="${runtime}"`,
+    "",
+    `Without it, future \`mx\` commands fall back to the default ~/mx.`
+  ];
+}
+function runGlobal(positionals, flags) {
+  switch (positionals[0]) {
+    case "init": {
+      const target = positionals[1] || discoverRuntime({ runtime: flags.runtime });
+      const res = initRuntime(target, templatesDir());
+      emit(() => {
+        console.log(`Runtime ready at ${res.runtime}`);
+        for (const c of res.created) console.log(`  + ${c}`);
+        for (const line of runtimeEnvHint(res.runtime)) console.log(line);
+      }, res);
+      return;
+    }
+    case "status": {
+      const root = requireRuntime({ runtime: flags.runtime });
+      const data = statusRuntime(root);
+      emit(() => {
+        console.log(`runtime: ${data.runtime}
+`);
+        console.log(`repos (${data.repos.length}):`);
+        for (const r of data.repos) {
+          console.log(`  ${r.name}  [${r.branch}]  ${r.remote ?? "(no remote)"}`);
+        }
+        console.log(`
+works (${data.works.length}):`);
+        for (const w of data.works) {
+          console.log(`  ${w.name}${w.description ? `  \u2014 ${w.description}` : ""}`);
+          for (const wt of w.worktrees) {
+            const ports = Object.entries(wt.ports).map(([s, p]) => `${s}:${p}`).join(", ");
+            console.log(`    ${wt.repo}  [${wt.branch}]${ports ? `  (${ports})` : ""}`);
+          }
+        }
+      }, data);
+      return;
+    }
+    case "update": {
+      const root = requireRuntime({ runtime: flags.runtime });
+      const res = updateRuntime(root, templatesDir());
+      emit(() => console.log(`Re-stamped CLAUDE.md into ${res.runtime}`), res);
+      return;
+    }
+    default:
+      throw new MxError(`unknown command: ${positionals[0]}`, "BAD_ARGS");
+  }
+}
+
+// src/commands/repo.ts
+function need(v, msg) {
+  if (v == null || v === "") throw new MxError(msg, "BAD_ARGS");
+  return v;
+}
+function dispatchRepo(positionals, flags) {
+  const action = positionals[1];
+  const root = requireRuntime({ runtime: flags.runtime });
+  const ctxRepo = inferContext(root).repo;
+  switch (action) {
+    case "add": {
+      const url = need(positionals[2], "usage: mx repo add <git-url> [--name <n>]");
+      const res = repoAdd(root, url, flags.name);
+      emit(() => console.log(`cloned ${res.name} -> ${res.path}`), res);
+      return;
+    }
+    case "ls": {
+      const repos = listReposInfo(root);
+      emit(() => {
+        for (const r of repos) console.log(`${r.name}  [${r.branch}]  ${r.remote ?? "(no remote)"}`);
+      }, repos);
+      return;
+    }
+    case "fetch": {
+      const name = need(
+        flags.name || ctxRepo,
+        "which repo? pass -n <name> or run inside a repo (mx repo -n <name> fetch)"
+      );
+      const res = repoFetch(root, name);
+      emit(
+        () => console.log(
+          `fetched ${res.name} \u2014 ${res.remoteBranches.length} branch(es) on origin, now on ${res.branch}`
+        ),
+        res
+      );
+      return;
+    }
+    case "info": {
+      const name = need(
+        flags.name || ctxRepo,
+        "which repo? pass -n <name> or run inside a repo (mx repo -n <name> info)"
+      );
+      const res = repoInfo(root, name);
+      emit(() => {
+        console.log(
+          `${res.name}
+  path:   ${res.path}
+  branch: ${res.branch}
+  remote: ${res.remote ?? "(none)"}`
+        );
+        console.log(
+          `  used by works: ${res.worktreesInWorks.length ? res.worktreesInWorks.join(", ") : "(none)"}`
+        );
+      }, res);
+      return;
+    }
+    case "rm": {
+      const name = need(
+        flags.name || ctxRepo,
+        "which repo? pass -n <name> or run inside a repo (mx repo -n <name> rm)"
+      );
+      const res = repoRemove(root, name);
+      emit(() => console.log(`removed repo ${res.name}`), res);
+      return;
+    }
+    default:
+      throw new MxError(`unknown repo command: ${action ?? "(none)"}`, "BAD_ARGS");
+  }
+}
+
+// src/commands/work.ts
+function need2(v, msg) {
+  if (v == null || v === "") throw new MxError(msg, "BAD_ARGS");
+  return v;
+}
+function dispatchWork(positionals, flags) {
+  const action = positionals[1];
+  if (action === "new") {
+    const root2 = requireRuntime({ runtime: flags.runtime });
+    const name2 = need2(positionals[2], "usage: mx work new <name> [--description <text>]");
+    const res = workNew(root2, name2, flags.description ?? "");
+    emit(() => {
+      console.log(`created work ${res.name}`);
+      console.log(`  ${res.path}`);
+    }, res);
+    return;
+  }
+  if (action === "ls") {
+    const root2 = requireRuntime({ runtime: flags.runtime });
+    const works = listWorksInfo(root2);
+    emit(() => {
+      for (const w of works) {
+        console.log(
+          `${w.name}  (${w.worktrees} worktree${w.worktrees === 1 ? "" : "s"})${w.description ? `  \u2014 ${w.description}` : ""}`
+        );
+      }
+    }, works);
+    return;
+  }
+  const root = requireRuntime({ runtime: flags.runtime });
+  const name = need2(
+    flags.name || inferContext(root).work,
+    `which work? pass -n <name> or run inside a work folder (mx work -n <name> ${action ?? "<command>"})`
+  );
+  switch (action) {
+    case "info": {
+      const work = workInfo(root, name);
+      emit(() => console.log(JSON.stringify(work, null, 2)), work);
+      return;
+    }
+    case "path": {
+      const res = workPath(root, name);
+      emit(() => console.log(res.path), res);
+      return;
+    }
+    case "describe": {
+      const text = need2(positionals[2], "usage: mx work -n <name> describe <text>");
+      const work = workDescribe(root, name, text);
+      emit(() => console.log(`updated description of ${name}`), work);
+      return;
+    }
+    case "worktree":
+      return workWorktree(root, name, positionals, flags);
+    case "port":
+      return workPort(root, name, positionals);
+    case "destroy": {
+      const res = workDestroy(root, name);
+      emit(
+        () => console.log(
+          `destroyed work ${name} (worktrees removed: ${res.removedWorktrees.join(", ") || "none"}; branches kept)`
+        ),
+        res
+      );
+      return;
+    }
+    default:
+      throw new MxError(`unknown work command: ${action ?? "(none)"}`, "BAD_ARGS");
+  }
+}
+function workWorktree(root, name, positionals, flags) {
+  const sub = positionals[2];
+  switch (sub) {
+    case "add": {
+      const repo = need2(
+        positionals[3],
+        "usage: mx work -n <name> worktree add <repo> [--branch <b>] [--base <ref>]"
+      );
+      const res = worktreeAdd(root, name, repo, { branch: flags.branch, base: flags.base });
+      emit(() => console.log(`added worktree ${res.repo} [${res.branch}] -> ${res.path}`), res);
+      return;
+    }
+    case "ls": {
+      const list = worktreeList(root, name);
+      emit(() => {
+        for (const wt of list) {
+          const ports = Object.entries(wt.ports ?? {}).map(([s, p]) => `${s}:${p}`).join(", ");
+          console.log(`${wt.repo}  [${wt.branch}]${ports ? `  (${ports})` : ""}`);
+        }
+      }, list);
+      return;
+    }
+    case "rm": {
+      const repo = need2(positionals[3], "usage: mx work -n <name> worktree rm <repo>");
+      const res = worktreeRemove(root, name, repo);
+      emit(() => console.log(`removed worktree ${res.repo} from ${name} (branch ${res.branch} kept)`), res);
+      return;
+    }
+    default:
+      throw new MxError(`unknown worktree command: ${sub ?? "(none)"}`, "BAD_ARGS");
+  }
+}
+function workPort(root, name, positionals) {
+  const sub = positionals[2];
+  switch (sub) {
+    case "set": {
+      const usage = "usage: mx work -n <name> port set <repo> <service> [<port>]";
+      const repo = need2(positionals[3], usage);
+      const service = need2(positionals[4], usage);
+      const portArg = positionals[5];
+      let port;
+      if (portArg != null) {
+        port = Number(portArg);
+        if (!Number.isInteger(port)) throw new MxError(`invalid port: ${portArg}`, "BAD_ARGS");
+      }
+      const res = portSet(root, name, repo, service, port);
+      emit(() => console.log(`${res.repo}.${res.service} -> ${res.port}`), res);
+      return;
+    }
+    case "unset": {
+      const usage = "usage: mx work -n <name> port unset <repo> <service>";
+      const repo = need2(positionals[3], usage);
+      const service = need2(positionals[4], usage);
+      const res = portUnset(root, name, repo, service);
+      emit(() => console.log(`unset ${res.repo}.${res.service} (was ${res.released})`), res);
+      return;
+    }
+    case "ls": {
+      const map = portList(root, name);
+      emit(() => {
+        for (const [repo, ports] of Object.entries(map)) {
+          for (const [service, port] of Object.entries(ports)) {
+            console.log(`${repo}.${service} -> ${port}`);
+          }
+        }
+      }, map);
+      return;
+    }
+    default:
+      throw new MxError(`unknown port command: ${sub ?? "(none)"}`, "BAD_ARGS");
+  }
+}
+
+// src/main.ts
+var VERSION = "0.1.0";
+function main() {
+  const { positionals, flags } = parseArgs(process.argv.slice(2));
+  setPorcelain(flags.porcelain);
+  try {
+    if (flags.version || positionals[0] === "version") {
+      emit(() => console.log(`mx ${VERSION}`), { version: VERSION });
+      return;
+    }
+    if (flags.help || positionals.length === 0 || positionals[0] === "help") {
+      process.stdout.write(HELP);
+      return;
+    }
+    switch (positionals[0]) {
+      case "init":
+      case "status":
+      case "update":
+        return runGlobal(positionals, flags);
+      case "repo":
+        return dispatchRepo(positionals, flags);
+      case "work":
+        return dispatchWork(positionals, flags);
+      default:
+        throw new MxError(`unknown command: ${positionals[0]}`, "BAD_ARGS");
+    }
+  } catch (e) {
+    fail(e);
+  }
+}
+
+// src/bin/mx.ts
+main();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@roulabs/mx",
+  "version": "1.0.0",
+  "description": "mx — run several features in parallel across shared repos using git worktrees",
+  "type": "module",
+  "bin": {
+    "mx": "./bin/mx.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roulabs/mx.git"
+  },
+  "homepage": "https://github.com/roulabs/mx#readme",
+  "bugs": "https://github.com/roulabs/mx/issues",
+  "keywords": [
+    "git",
+    "worktree",
+    "monorepo",
+    "cli",
+    "multiplexer",
+    "parallel",
+    "workflow",
+    "dev"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/CLAUDE.md

@@ -0,0 +1,113 @@
+<!-- Installed by the mx CLI. Don't hand-edit this file in the runtime —
+     edit templates/CLAUDE.md in the mx source repo and run `mx update`. -->
+
+# mx — multiplexed parallel work across repos
+
+**mx** ("multiplexer") is a system for running several features in parallel across shared repos,
+using git worktrees. You are running inside an mx runtime. Read this fully before acting — the
+rules here are not optional.
+
+## The one idea that governs everything
+
+**`mx` owns all runtime state.** The work manifest (`work.json`) and the VS Code workspace file
+are managed *only* through `mx` commands. You **never** hand-edit `work.json` or the
+`.code-workspace`, and you **never** create or remove worktrees with raw `git`. Whenever you need
+to read or change the work — its repos, branches, ports — you call an `mx` command. Treat
+`work.json` as read-only build output: look at it for orientation, but mutate it through `mx`.
+
+Every read command takes `--porcelain` for stable JSON; parse that instead of scraping text.
+
+## What this runtime is for
+
+`mx/` is where **feature work** happens. Sessions launched here implement a feature inside a
+`works/<feature>/` folder. mx *itself* — this template, the `mx` CLI — is maintained in a separate
+**mx source checkout** (the `github.com/roulabs/mx` repo), outside this tree. If you were opened
+here to change how mx works, you're in the wrong place: switch to that repo. Don't edit `repos/`,
+`works/`, or the runtime files from here.
+
+## Layout
+
+```
+mx/
+├── CLAUDE.md               # this file (installed by the mx CLI)
+├── .mx-root                # empty marker: "this is the mx root"
+├── repos/                  # PRISTINE reference clones, each on its default branch
+│   ├── repo-a/
+│   └── repo-b/
+└── works/                  # one folder per feature/work
+    └── feature-a/
+        ├── work.json       # manifest — owned by `mx`, do not hand-edit
+        ├── feature-a.code-workspace
+        ├── repo-a/         # worktree of repo-a on this feature's branch
+        └── repo-b/         # worktree of repo-b on this feature's branch
+```
+
+- `repos/<repo>` are **source-of-truth clones** — read-only reference. Worktrees fork from them
+  and share their `.git` object store. Never edit, commit, or run dev servers in `repos/`.
+- `works/<feature>/<repo>` are **worktrees**, each on its own feature branch. All work happens here.
+
+## work.json (per-work manifest, owned by mx)
+
+```json
+{
+  "name": "feature-a",
+  "description": "Add a chatbox to the answer panel",
+  "worktrees": [
+    { "repo": "repo-a", "branch": "feature-a", "ports": { "web": 3000, "api": 3001 } },
+    { "repo": "repo-b", "branch": "feature-a", "ports": { "worker": 3002 } }
+  ]
+}
+```
+
+- One worktree per repo. `ports` is a `service -> port` map local to that worktree.
+- The work's `name` is immutable. There is no port-block concept — each port is allocated
+  individually and is unique across **all** works.
+
+## Orient yourself at the start of every session
+
+1. You are launched from a **work folder** (`works/<feature>/`), not a single repo. There is no "main repo."
+2. Read the work's state with `mx work -n <feature> info --porcelain` to learn its repos, branches, and ports.
+3. When you edit a repo's worktree, follow that repo's own `CLAUDE.md`, linters, and conventions —
+   its instructions live inside the worktree and apply.
+4. The work root is **not** a git repo. Run build/test/git commands from inside the relevant worktree.
+5. If several sessions share one work, the user gives each a lane (usually one repo). Stay in your lane.
+
+## How to do things (always via mx)
+
+You are launched from the work folder, so you can **omit `-n <feature>`** — mx infers the work from
+your cwd (and the repo, when you're inside a worktree). The commands below show `-n <feature>` for
+clarity; dropping it works while you're inside the work.
+
+- **See the work:** `mx work info --porcelain` (or `mx work -n <feature> info --porcelain`)
+- **Add a repo to the work (needs a worktree):** if a repo you need has no worktree yet, **stop and
+  ask the user.** Only when they say so, run:
+  ```
+  mx work -n <feature> worktree add <repo> [--branch <b>] [--base <ref>]
+  ```
+  This creates the worktree from the pristine clone, registers it in `work.json`, and adds it to the
+  workspace — all at once. Never run `git worktree add` yourself.
+  - `--branch <b>` is the **new** branch to create (defaults to the work name; if it already exists, it's reused).
+  - `--base <ref>` is where to **fork from** — any ref. A bare branch name (e.g. `main`,
+    `migration-to-mt-service-from-cf`) resolves to that local branch or, failing that, `origin/<name>`.
+    Run `mx repo -n <repo> fetch` first if you want the base at its latest upstream commit. Omit
+    `--base` to fork from the pristine clone's current HEAD.
+- **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
+  service to its allocated port too. Release with `port unset`.
+- **Tear down (user-initiated, after merge):** `mx work -n <feature> destroy` removes the worktrees
+  and the work folder but **keeps the branches**. It refuses if any worktree has uncommitted changes.
+
+## Hard rules
+
+1. **Never edit, stage, commit, or run dev servers inside `repos/`.** Those clones are read-only base for worktrees.
+2. **Never hand-edit `work.json` or the `.code-workspace`.** Change them only through `mx` commands.
+3. **Never create or remove worktrees with raw `git`.** Use `mx work ... worktree add/rm`.
+4. **Creating a worktree requires the user in the loop** — only when they explicitly tell you to in this session.
+5. **Don't destroy anything unless asked.** Worktrees stay until the user confirms the feature is merged.
+   Teardown keeps feature branches; never delete them.
+
+## The one rule that matters most
+
+`repos/` is read-only reference; real work lives in worktrees under `works/<feature>/`; and `mx`
+owns the manifest. If a repo you need has no worktree yet, ask before adding one — then add it with `mx`.

package/templates/work.json

@@ -0,0 +1,5 @@
+{
+  "name": "",
+  "description": "",
+  "worktrees": []
+}

package/templates/workspace.code-workspace

@@ -0,0 +1,4 @@
+{
+  "folders": [],
+  "settings": {}
+}