@roulabs/mx 1.1.1 → 1.2.1

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.1",
   "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
 ```
@@ -114,7 +115,7 @@ Example entry:
 
 Primary path:
 
-1. Read `<runtime>/context/INDEX.json` — every entry's metadata in one Read.
+1. **Read `<runtime>/context/INDEX.json` on every task** — trivial or not, small or large. Skimming a metadata index is cheap; the cost of missing a relevant entry is high. This is a hard rule, not a heuristic.
 2. Open files at `<runtime>/context/<path>.md` for entries whose metadata matches the current task.
 
 When INDEX descriptions don't surface what you need — and often they won't — fall back to anything that works:
@@ -122,12 +123,10 @@ When INDEX descriptions don't surface what you need — and often they won't —
 - **Grep `<runtime>/context/`** for keywords. Frequently the term you need lives in a body, not in any description.
 - **`ls` the folder recursively** to spot entries on disk that aren't indexed (orphans), and read them directly when relevant.
 - **Follow `related` chains** outward from a known-relevant entry to find the rest of a cluster.
-- **Read everything** if the registry is small (< ~30 entries) and you're starting unfamiliar work — cheaper than guessing.
+- **Read everything** when in doubt — better than guessing.
 
 INDEX is the *primary* discovery surface, not the only one. Use whatever gets you to the right entry fastest — direct grep, full-content scan, recursive read, following links, your judgment.
 
-A 30-second skim of INDEX is free; do it before any non-trivial task. Skip only for typo-fix-level work.
-
 ### Maintain INDEX.json as you go
 
 When you add, rename, remove, or restructure an entry, update INDEX in the same change. Drift means orphan files (invisible to future sessions) or stale entries (false positives). After editing INDEX, sanity-check it parses as valid JSON.
@@ -150,6 +149,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