@roulabs/mx 2.1.1 → 2.3.0

package/README.md

@@ -52,7 +52,7 @@ Inside a work folder or worktree you can drop `-n` — mx infers the work/repo f
 | `mx work -n <name> worktree add <repo> [--branch <b>] [--base <ref>] [--no-hydrate]` | add a worktree (runs the repo's `hydrate.sh` unless `--no-hydrate`) |
 | `mx work -n <name> worktree ls\|rm\|hydrate <repo>` | list / remove / re-run hydrate for a worktree |
 | `mx work -n <name> port set\|unset\|ls <repo> <service> [<port>]` | allocate/release ports |
-| `mx work -n <name> archive [--yes]` / `unarchive` | soft-delete / restore a work (keeps branches) |
+| `mx work -n <name> archive [--yes]` / `unarchive` | soft-delete / restore a work (keeps branches); runs the work's `hooks/{pre,post}-{archive,unarchive}.sh` (a `pre-*` non-zero exit aborts) |
 | `mx work -n <name> destroy --force` | permanently remove the work folder (keeps branches) |
 
 ## License

package/bin/mx.js

@@ -168,6 +168,14 @@ var workManifest = (root, name) => path3.join(workDir(root, name), "work.json");
 var workspaceFile = (root, name) => path3.join(workDir(root, name), `${name}.code-workspace`);
 var worktreesDir = (root, name) => path3.join(workDir(root, name), "wt");
 var worktreePath = (root, name, repo) => path3.join(worktreesDir(root, name), repo);
+var WORK_HOOK_EVENTS = [
+  "pre-archive",
+  "post-archive",
+  "pre-unarchive",
+  "post-unarchive"
+];
+var workHooksDir = (root, name) => path3.join(workDir(root, name), "hooks");
+var workHookScript = (root, name, event) => path3.join(workHooksDir(root, name), `${event}.sh`);
 var RUNTIME_VERSION = 2;
 var mxConfigFile = (root) => path3.join(root, "mx.json");
 function readMxConfig(root) {
@@ -355,7 +363,7 @@ function initRuntime(target0, templatesDir2) {
 function ensureWorkScaffolding(root, workName) {
   const created = [];
   const wd = workDir(root, workName);
-  for (const d of ["wt", "scripts", "files", "tmp", "sessions"]) {
+  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 });
@@ -373,6 +381,14 @@ function ensureWorkScaffolding(root, workName) {
     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);
+      created.push(hook);
+    }
+  }
   return created;
 }
 function workClaudeMd(name) {
@@ -402,6 +418,40 @@ function workClaudeSettings(root) {
   };
   return JSON.stringify(settings, null, 2) + "\n";
 }
+function workHookScriptBody(event) {
+  const isPre = event.startsWith("pre-");
+  const op = event.replace(/^(pre|post)-/, "");
+  const failNote = isPre ? `# A NON-ZERO EXIT ABORTS the ${op}: nothing is mutated and mx errors with
+# HOOK_FAILED. Use this to veto (e.g. block on unpushed commits).` : `# Runs only after the ${op} succeeds. A non-zero exit is reported as a
+# warning; it cannot undo the ${op}.`;
+  let stateNote;
+  if (op === "archive") {
+    stateNote = isPre ? "# State when this runs: worktrees still present under wt/." : "# State when this runs: worktrees removed, branches kept, work flagged archived.";
+  } else {
+    stateNote = isPre ? "# State when this runs: work is archived, no worktrees on disk yet." : "# State when this runs: worktrees re-created under wt/, archive flag cleared.";
+  }
+  return `#!/usr/bin/env bash
+#
+# mx ${event} hook for this work.
+#
+# Runs around \`mx work -n <work> ${op}\`.
+${failNote}
+${stateNote}
+#
+# mx runs this with the work folder as the working directory and passes context
+# both as positional args and environment variables:
+#
+#   $1 / $MX_EVENT       the lifecycle event ("${event}")
+#   $2 / $MX_WORK_PATH   absolute path to the work folder
+#   $MX_WORK             work name
+#   $MX_RUNTIME          runtime root
+#
+set -euo pipefail
+
+# No-op by default. Add your ${event} logic below.
+exit 0
+`;
+}
 function syncRuntime(root, templatesDir2) {
   const updated = [];
   updated.push(stampClaudeMd(root, templatesDir2));
@@ -1643,6 +1693,28 @@ function runWorktreeHydrate(ctx, quiet) {
   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";
+function runWorkHook(root, work, event, quiet) {
+  const script = workHookScript(root, work, event);
+  if (!existsSync3(script)) return { ran: false, ok: true, missing: true };
+  const wp = workPath(root, work).path;
+  const env = {
+    ...process.env,
+    MX_RUNTIME: root,
+    MX_WORK: work,
+    MX_WORK_PATH: wp,
+    MX_EVENT: event
+  };
+  const r = spawnSync4(script, [event, wp], {
+    cwd: wp,
+    env,
+    stdio: quiet ? ["ignore", "ignore", "ignore"] : "inherit"
+  });
+  return { ran: true, ok: r.status === 0, missing: false };
+}
+
 // src/commands/work.ts
 function need2(v, msg) {
   if (v == null || v === "") throw new MxError(msg, "BAD_ARGS");
@@ -1806,7 +1878,23 @@ function dispatchWork(positionals, flags) {
           return;
         }
       }
+      if (workInfo(root, name).isArchived !== true) {
+        const preArchive = runWorkHook(root, name, "pre-archive", flags.porcelain);
+        if (preArchive.ran && !preArchive.ok) {
+          throw new MxError(
+            `pre-archive hook for "${name}" exited non-zero \u2014 archive aborted`,
+            "HOOK_FAILED"
+          );
+        }
+      }
       const res = archiveWork(root, name);
+      const postArchive = runWorkHook(root, name, "post-archive", flags.porcelain);
+      if (postArchive.ran && !postArchive.ok && !flags.porcelain) {
+        process.stderr.write(
+          `${warn()} ${dim(`post-archive hook for ${name} exited non-zero (archive already applied)`)}
+`
+        );
+      }
       emit(() => {
         const removed = res.removedWorktrees.join(", ") || "none";
         console.log(`${check()} archived work ${bold(name)}`);
@@ -1827,7 +1915,23 @@ function dispatchWork(positionals, flags) {
         }
         overrides[tok.slice(0, eq)] = tok.slice(eq + 1);
       }
+      if (workInfo(root, name).isArchived === true) {
+        const preUnarchive = runWorkHook(root, name, "pre-unarchive", flags.porcelain);
+        if (preUnarchive.ran && !preUnarchive.ok) {
+          throw new MxError(
+            `pre-unarchive hook for "${name}" exited non-zero \u2014 unarchive aborted`,
+            "HOOK_FAILED"
+          );
+        }
+      }
       const res = unarchiveWork(root, name, overrides);
+      const postUnarchive = runWorkHook(root, name, "post-unarchive", flags.porcelain);
+      if (postUnarchive.ran && !postUnarchive.ok && !flags.porcelain) {
+        process.stderr.write(
+          `${warn()} ${dim(`post-unarchive hook for ${name} exited non-zero (unarchive already applied)`)}
+`
+        );
+      }
       emit(() => {
         console.log(`${check()} unarchived work ${bold(name)}`);
         for (const r of res.restored) {

package/package.json

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

package/templates/CLAUDE.md

@@ -70,8 +70,12 @@ 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)
+        │   ├── pre-archive.sh · post-archive.sh
+        │   └── pre-unarchive.sh · post-unarchive.sh
         └── sessions/       # session summaries (see § Session summaries)
 ```
 
@@ -85,9 +89,39 @@ mx/
   `CLAUDE.md` for any session started in the work folder (Claude Code walks up from the session's cwd).
   mx stamps it once (an explanatory comment, otherwise empty) and then **never touches it** — it's where
   you and the user record rules specific to this work.
-- `works/<feature>/{scripts,files,tmp}/` are the only places to put non-mx files in a work — see
+- `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,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
+
+Each work has a `hooks/` folder with mx-owned scripts that fire around archive/unarchive. mx stamps
+four documented **no-op** scripts (they just `exit 0`) when the work is created — edit a script's body
+to make it do something; leave it as-is to opt out.
+
+| hook | when it runs | non-zero exit |
+|---|---|---|
+| `pre-archive.sh` | before `mx work archive` removes worktrees (worktrees still on disk) | **aborts** the archive (`HOOK_FAILED`); nothing is mutated |
+| `post-archive.sh` | after the work is archived (worktrees gone, branches kept) | warning only — the archive already happened |
+| `pre-unarchive.sh` | before `mx work unarchive` re-creates worktrees (none on disk yet) | **aborts** the unarchive (`HOOK_FAILED`) |
+| `post-unarchive.sh` | after worktrees are restored | warning only |
+
+A `pre-*` hook is a veto point (e.g. block archive if a branch has unpushed commits); a `post-*` hook
+is for cleanup/notification after the fact. mx runs each with the **work folder** as the working
+directory and passes context as positional args and environment variables:
+
+```
+$1 / $MX_EVENT       the event name (e.g. "pre-archive")
+$2 / $MX_WORK_PATH   absolute path to the work folder
+$MX_WORK             work name
+$MX_RUNTIME          runtime root
+```
+
+These hooks are mx-owned but **yours to edit** — `mx sync` only re-stamps a script if it's missing,
+never clobbering your changes, and backfills `hooks/` for works created before this feature existed.
+
 ## The work folder holds mx-native files only
 
 **Never create ad-hoc files directly in the work-folder root.** The root is reserved for mx-native
@@ -98,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*
@@ -273,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.