@roulabs/mx 1.1.1 → 1.2.0

package/bin/mx.js

@@ -298,19 +298,37 @@ function removeFolderFromWorkspace(root, name, repo) {
   ws.folders = (ws.folders ?? []).filter((f) => f.path !== repo);
   writeJson(file, ws);
 }
+function clearWorkspaceFolders(root, name) {
+  const file = workspaceFile(root, name);
+  if (!exists(file)) return;
+  const ws = readJson(file);
+  ws.folders = [];
+  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 });
+  fs6.mkdirSync(path4.join(dir, "sessions"), { recursive: true });
   const work = { name, description, worktrees: [] };
   writeWork(root, work);
   writeJson(workspaceFile(root, name), { folders: [], settings: {} });
   return { ...work, path: dir };
 }
-function listWorksInfo(root) {
+function listWorksInfo(root, opts = {}) {
   return listWorkNames(root).map((name) => {
     const w = readWork(root, name);
-    return { name, description: w.description ?? "", worktrees: (w.worktrees ?? []).length };
+    return {
+      name,
+      description: w.description ?? "",
+      worktrees: (w.worktrees ?? []).length,
+      isArchived: w.isArchived === true,
+      archived_at: w.archived_at ?? null
+    };
+  }).filter((s) => {
+    if (opts.onlyArchived) return s.isArchived;
+    if (opts.includeArchived) return true;
+    return !s.isArchived;
   });
 }
 function workInfo(root, name) {
@@ -372,7 +390,13 @@ function worktreeRemove(root, name, repo) {
   removeFolderFromWorkspace(root, name, repo);
   return { work: name, repo, branch: wt.branch, removed: true };
 }
-function workDestroy(root, name) {
+function workDestroy(root, name, opts = {}) {
+  if (!opts.force) {
+    throw new MxError(
+      `refusing to destroy "${name}" \u2014 destroy is permanent and removes the work folder including any session summaries. Use \`mx work archive\` to soft-delete (recoverable via \`mx work unarchive\`), or re-run with \`--force\` if you really want this gone.`,
+      "NEED_FORCE"
+    );
+  }
   const work = readWork(root, name);
   const dirty = [];
   for (const wt of work.worktrees ?? []) {
@@ -394,6 +418,74 @@ function workDestroy(root, name) {
   fs6.rmSync(workDir(root, name), { recursive: true, force: true });
   return { work: name, removedWorktrees: removed, branchesKept: true };
 }
+function archiveWork(root, name) {
+  const work = readWork(root, name);
+  if (work.isArchived === true) {
+    throw new MxError(`work "${name}" is already archived`, "ALREADY_ARCHIVED");
+  }
+  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 archive "${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);
+  }
+  clearWorkspaceFolders(root, name);
+  const archived_at = (/* @__PURE__ */ new Date()).toISOString();
+  work.isArchived = true;
+  work.archived_at = archived_at;
+  writeWork(root, work);
+  return { work: name, archived_at, removedWorktrees: removed, branchesKept: true };
+}
+function unarchiveWork(root, name, overrides = {}) {
+  const work = readWork(root, name);
+  if (work.isArchived !== true) {
+    throw new MxError(`work "${name}" is not archived`, "NOT_ARCHIVED");
+  }
+  const desired = (work.worktrees ?? []).map((wt) => ({
+    repo: wt.repo,
+    branch: overrides[wt.repo] ?? wt.branch,
+    ports: wt.ports ?? {}
+  }));
+  const missing = [];
+  for (const d of desired) {
+    const rp = repoPath(root, d.repo);
+    if (!isGitRepo(rp)) {
+      throw new MxError(`pristine clone missing for repo: ${d.repo}`, "NO_REPO");
+    }
+    if (!branchExists(rp, d.branch)) missing.push({ repo: d.repo, branch: d.branch });
+  }
+  if (missing.length) {
+    const list = missing.map((m) => `${m.repo}=${m.branch}`).join(", ");
+    const overrideHint = missing.map((m) => `${m.repo}=<branch>`).join(" ");
+    throw new MxError(
+      `cannot unarchive "${name}" \u2014 branch(es) not found: ${list}. Re-run with explicit overrides: \`mx work -n ${name} unarchive ${overrideHint}\`.`,
+      "NO_REF"
+    );
+  }
+  const restored = [];
+  for (const d of desired) {
+    const dest = path4.join(workDir(root, name), d.repo);
+    git(["-C", repoPath(root, d.repo), "worktree", "add", dest, d.branch]);
+    addFolderToWorkspace(root, name, d.repo);
+    restored.push({ repo: d.repo, branch: d.branch, path: dest, ports: d.ports });
+  }
+  work.worktrees = restored.map((r) => ({ repo: r.repo, branch: r.branch, ports: r.ports }));
+  work.isArchived = false;
+  delete work.archived_at;
+  writeWork(root, work);
+  return { work: name, restored };
+}
 
 // ../../packages/core/src/ports.ts
 var PORT_BASE = 3e3;
@@ -480,7 +572,14 @@ var VALUE_FLAGS = {
 };
 function parseArgs(argv) {
   const positionals = [];
-  const flags = { porcelain: false, help: false, version: false };
+  const flags = {
+    porcelain: false,
+    help: false,
+    version: false,
+    force: false,
+    all: false,
+    archived: false
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--porcelain" || a === "--json") {
@@ -489,6 +588,12 @@ function parseArgs(argv) {
       flags.help = true;
     } else if (a === "--version" || a === "-v") {
       flags.version = true;
+    } else if (a === "--force") {
+      flags.force = true;
+    } else if (a === "--all") {
+      flags.all = true;
+    } else if (a === "--archived") {
+      flags.archived = true;
     } else if (a.startsWith("--") && a.includes("=")) {
       const eq = a.indexOf("=");
       const key = VALUE_FLAGS[a.slice(0, eq)];
@@ -546,18 +651,20 @@ Repos (pristine clones):
   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 new <name> [--description <t>]                creates folder + empty work.json + sessions/
+  mx work ls [--all|--archived] [--porcelain]           default: active only
   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> 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> 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
+  mx work -n <name> archive                             removes worktrees; keeps folder + work.json + sessions; recoverable
+  mx work -n <name> unarchive [<repo>=<branch>...]      re-creates worktrees from work.json; override per-repo branch if recorded one is missing
+  mx work -n <name> destroy --force                     PERMANENT: deletes the work folder including session summaries (branches kept). Prefer archive.
 
 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.
@@ -733,12 +840,16 @@ function dispatchWork(positionals, flags) {
   }
   if (action === "ls") {
     const root2 = requireRuntime({ runtime: flags.runtime });
-    const works = listWorksInfo(root2);
+    const works = listWorksInfo(root2, {
+      includeArchived: flags.all,
+      onlyArchived: flags.archived
+    });
     emit(() => {
       for (const w of works) {
-        console.log(
-          `${w.name}  (${w.worktrees} worktree${w.worktrees === 1 ? "" : "s"})${w.description ? `  \u2014 ${w.description}` : ""}`
-        );
+        const chip = w.isArchived ? `[archived ${(w.archived_at ?? "").slice(0, 10)}]  ` : "";
+        const desc = w.description ? `  \u2014 ${w.description}` : "";
+        const wts = `(${w.worktrees} worktree${w.worktrees === 1 ? "" : "s"})`;
+        console.log(`${chip}${w.name}  ${wts}${desc}`);
       }
     }, works);
     return;
@@ -770,7 +881,13 @@ function dispatchWork(positionals, flags) {
     case "port":
       return workPort(root, name, positionals);
     case "destroy": {
-      const res = workDestroy(root, name);
+      if (flags.force && !flags.porcelain) {
+        process.stderr.write(
+          `\u26A0  permanently removing work "${name}" \u2014 folder and any session summaries will be deleted (branches kept). This cannot be undone.
+`
+        );
+      }
+      const res = workDestroy(root, name, { force: flags.force });
       emit(
         () => console.log(
           `destroyed work ${name} (worktrees removed: ${res.removedWorktrees.join(", ") || "none"}; branches kept)`
@@ -779,6 +896,41 @@ function dispatchWork(positionals, flags) {
       );
       return;
     }
+    case "archive": {
+      if (!flags.porcelain) {
+        process.stderr.write(
+          `Reminder: write any pending session summary into works/${name}/sessions/ before archiving.
+`
+        );
+      }
+      const res = archiveWork(root, name);
+      emit(
+        () => console.log(
+          `archived work ${name} at ${res.archived_at} (worktrees removed: ${res.removedWorktrees.join(", ") || "none"}; branches kept)`
+        ),
+        res
+      );
+      return;
+    }
+    case "unarchive": {
+      const overrides = {};
+      for (const tok of positionals.slice(2)) {
+        const eq = tok.indexOf("=");
+        if (eq <= 0 || eq === tok.length - 1) {
+          throw new MxError(
+            `bad override: "${tok}" \u2014 expected <repo>=<branch>`,
+            "BAD_ARGS"
+          );
+        }
+        overrides[tok.slice(0, eq)] = tok.slice(eq + 1);
+      }
+      const res = unarchiveWork(root, name, overrides);
+      emit(() => {
+        console.log(`unarchived work ${name}`);
+        for (const r of res.restored) console.log(`  ${r.repo}  [${r.branch}]  -> ${r.path}`);
+      }, res);
+      return;
+    }
     default:
       throw new MxError(`unknown work command: ${action ?? "(none)"}`, "BAD_ARGS");
   }

package/package.json

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

package/templates/CLAUDE.md

@@ -41,6 +41,7 @@ mx/
     └── feature-a/
         ├── work.json       # manifest — owned by `mx`, do not hand-edit
         ├── feature-a.code-workspace
+        ├── sessions/       # session summaries (see § Session summaries)
         ├── repo-a/         # worktree of repo-a on this feature's branch
         └── repo-b/         # worktree of repo-b on this feature's branch
 ```
@@ -150,6 +151,37 @@ For ephemeral scratch (a debugging journey in progress, a hypothesis you're test
 
 **What's worth writing:** rationale, history, gotchas, cross-system invariants, debugging journeys, RCAs, session summaries, project-local procedures, imported reference material — your call. When in doubt, save it; prune later.
 
+## Session summaries — detailed record of each working session
+
+Each work has a `sessions/` folder that accumulates one markdown file per working session. The goal: another agent (a fresh Claude session, or a different agent like Codex / Cursor) can read these files and start a new session with full context — including findings from external sources that may no longer be accessible.
+
+### Single trigger — never auto-write
+
+Write a session summary **only when the user explicitly asks at end of session**: *"add the session summary before I close"*, *"save this session"*, etc. Never auto-write. Never propose mid-session. Never proactively suggest at end of session unless asked. The user owns the trigger.
+
+### Filename
+
+`works/<feature>/sessions/YYYY-MM-DD-HH-MM-<slug>.md` — date, 24-hour time (dash-separated; colons aren't portable on Windows), then a short kebab-case slug describing the session's subject. Use the time you started the session (or now, if unsure).
+
+### Content — distillation, not transcript
+
+The summary is detailed but **not a transcript**. Capture the substance of what happened so a future agent can pick up the work without re-doing all the discovery:
+
+- **Goal** — what we set out to do this session.
+- **What we learned from external sources.** When you fetched URLs, looked at attached images, read attached files, or ran web searches: distill the relevant findings into the summary. The URL, file path, or image may not be accessible later — the *information* must live in the summary.
+- **What worked** — code shipped, decisions reached, approaches that succeeded. Include commit SHAs and PR links when applicable.
+- **Dead ends** — hypotheses tried and falsified, approaches abandoned, and *why* each was abandoned (saves the next session from re-running the same dead end).
+- **Files touched** — paths modified, with a sentence on what changed and why.
+- **State at session end** — in-flight changes, tests passing/failing, PRs open, commits ahead of main.
+- **Next steps / open questions** — what should the next session pick up?
+- **Cross-references** — context-registry entries (by `path`) created or updated this session; prior session files this builds on (by filename).
+
+Length is not a virtue; completeness is. The bar: a fresh agent can read just this file and continue the work cold.
+
+### Cross-link with the context registry
+
+Sessions and the context registry complement each other. When this session created or updated an entry in `<runtime>/context/`, list it under "Cross-references" in the session file. Conversely, when promoting a finding into a durable registry entry, you may reference the session file in the entry's body for provenance.
+
 ## 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