@ulysses-ai/create-workspace 0.22.0-beta.0 → 0.23.0-beta.0

package/template/_claude/scripts/classify-update.mjs

@@ -3,14 +3,20 @@
 // can batch the safe cases and ask only where a decision is needed.
 //
 // Usage:
-//   node classify-update.mjs [--root <dir>] [--payload <dir>]
+//   node classify-update.mjs [--root <dir>] [--payload <dir>] [--baseline <file>]
 //   node classify-update.mjs --root <dir> --payload <dir> --write-baseline
 //   node classify-update.mjs --root <dir> --payload <dir> --merge-claude-md
 //
-// --root    workspace root; defaults to the current working directory (never
-//           derived from this script's location — the upgrade payload runs
-//           this file from <workspace>/.workspace-update/.claude/scripts/)
-// --payload the staged payload; defaults to <root>/.workspace-update
+// --root     workspace root; defaults to the current working directory (never
+//            derived from this script's location — the upgrade payload runs
+//            this file from <workspace>/.workspace-update/.claude/scripts/)
+// --payload  the staged payload; defaults to <root>/.workspace-update
+// --baseline the baseline to classify against; defaults to
+//            <root>/.claude/.template-baseline.json, falling back to
+//            <payload>/.template-baseline.reconstructed.json (what --upgrade
+//            reconstructs for pre-baseline workspaces) when the root has none.
+//            Pass it explicitly in the worktree flow, where <root> is the
+//            worktree and the launcher's baseline may not be reachable.
 //
 // The default mode prints JSON with these lists:
 //   new        — no installed counterpart and no baseline entry; safe to
@@ -24,6 +30,23 @@
 //                edit AND a template change — the one case that needs a
 //                per-file decision (or the workspace predates baselines and
 //                has no entry to compare).
+//   config     — .mcp.json and .claude/settings.json: JSON the workspace
+//                owns jointly with the template (its own MCP servers and
+//                settings live beside template keys). Never classified by
+//                content and never batch-copied — instead each entry carries
+//                a key-level diff (`added` keys the template ships, keys
+//                `workspaceOnly`, keys `changed` in both, nested paths joined
+//                with '/'), and /workspace-update merges key by key: add
+//                template keys, keep workspace-only keys, ask on conflicting
+//                keys. Array-valued keys (hooks event lists,
+//                permissions.allow/deny) diff by ELEMENT instead of whole:
+//                each `arrays` entry is { path, added, workspaceOnly } with
+//                the element lists, and the skill merges arrays as a union —
+//                the workspace's elements kept, the template's new ones
+//                appended — so only true scalar conflicts ask. Entries flag
+//                `notInstalled` (no workspace file — ask once whether to
+//                install the payload's copy) or `unparseable` (broken JSON on
+//                either side — ask, never merge blind).
 //   localOnly  — installed file differs from the payload, but the payload
 //                equals the baseline: the template hasn't touched the file
 //                since the last update, so the difference is purely local.
@@ -38,6 +61,8 @@
 //                active rule stays (gh:180)
 //   removed    — installed file with no payload counterpart: the template
 //                stopped shipping it. Excludes what the workspace owns:
+//                the config files above (the template dropping one hands it
+//                to the workspace, it never deletes user content),
 //                *.test.mjs (see staleTests), anything gitignored
 //                (machine-local), paths under .claude/worktrees/, and entries
 //                of workspace.json → workspace.localFiles (array of
@@ -48,21 +73,25 @@
 //                checkout and are never updated by /workspace-update; the
 //                skill offers to remove them (tests live in the template repo)
 //
-// Plus `hasBaseline`: whether .claude/.template-baseline.json exists. Without
-// it (workspaces older than the baseline's introduction) template changes
-// cannot be told from local edits, so they land in `differs` — the first
-// update after v0.21 asks per file; once it writes the baseline, later updates
-// won't.
+// Plus `hasBaseline`: whether a usable baseline was found, `baselineSource`
+// (which file it came from) and `baselineReconstructed`. The default
+// resolution is <root>/.claude/.template-baseline.json, then the payload's
+// .template-baseline.reconstructed.json (both unparseable-as-absent); without
+// either, template changes cannot be told from local edits, so they land in
+// `differs` — the first update asks per file; once it writes the baseline,
+// later updates won't.
 //
 // Content comparisons hash with CRLF normalized to LF on both sides (binary
 // files hash byte-exact), so a git autocrlf checkout that stores CRLF where
 // the payload ships LF classifies as identical rather than locally modified.
 //
-// Only verbatim-installed files are classified: everything under .claude/,
-// plus .mcp.json and .claudeignore. The payload's templates (*.tmpl, which
-// install with {{project-name}} substitution), _gitignore (merged line-by-line
-// into the workspace's .gitignore), and .manifest.json (payload metadata) are
-// handled by their own steps in /workspace-update and are excluded here.
+// Only verbatim-installed files are classified: everything under .claude/
+// except .claude/settings.json, plus .mcp.json and .claudeignore — the two
+// JSON configs route to `config` instead of the content lists. The payload's
+// templates (*.tmpl, which install with {{project-name}} substitution),
+// _gitignore (merged line-by-line into the workspace's .gitignore), and
+// .manifest.json (payload metadata) are handled by their own steps in
+// /workspace-update and are excluded here.
 //
 // The other two modes are /workspace-update bookends:
 //   --write-baseline  write .claude/.template-baseline.json recording the
@@ -89,7 +118,13 @@ import {
 import { basename, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gitIgnoredPaths } from './build-workspace-context.mjs';
-import { BASELINE_PATH, hashBytes, readBaseline, writeBaseline } from './template-baseline.mjs';
+import {
+  BASELINE_PATH,
+  RECONSTRUCTED_BASELINE_NAME,
+  hashBytes,
+  readBaselineFile,
+  writeBaseline,
+} from './template-baseline.mjs';
 
 function isMainModule(metaUrl) {
   if (!process.argv[1]) return false;
@@ -99,11 +134,12 @@ function isMainModule(metaUrl) {
 }
 
 function parseArgs(argv) {
-  const args = { root: process.cwd(), payload: null, writeBaseline: false, mergeClaudeMd: false };
+  const args = { root: process.cwd(), payload: null, baseline: null, writeBaseline: false, mergeClaudeMd: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--root') args.root = argv[++i];
     else if (a === '--payload') args.payload = argv[++i];
+    else if (a === '--baseline') args.baseline = argv[++i];
     else if (a === '--write-baseline') args.writeBaseline = true;
     else if (a === '--merge-claude-md') args.mergeClaudeMd = true;
     else throw new Error(`Unknown arg: ${a}`);
@@ -115,6 +151,104 @@ function parseArgs(argv) {
 // Everything else in the payload is a template or metadata handled elsewhere.
 const VERBATIM_ROOTS = ['.claude', '.mcp.json', '.claudeignore'];
 
+// JSON configs the workspace owns jointly with the template: its own MCP
+// servers sit inside .mcp.json's mcpServers, its own settings beside the
+// template's keys in .claude/settings.json. Content classification would
+// file every one of them as `differs` the moment the workspace adds
+// anything, and a batch copy would wipe the workspace's entries — so they
+// are reported in `config` with a key-level diff and merged key by key,
+// never compared by bytes and never copied wholesale (gh:186).
+const CONFIG_PATHS = new Set(['.mcp.json', '.claude/settings.json']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Key-level diff between the payload's config object and the workspace's.
+ * Paths join keys with '/' (mcpServers/playwright) and stop at two
+ * segments: these configs are maps of named units — mcpServers/{server},
+ * permissions/{allow} — and a unit's own internals (a server's args vs
+ * command) merge as one decision, not as separate asks. Arrays the key
+ * carries on both sides diff by ELEMENT (a union merge needs no decision),
+ * and any other non-object value compares by JSON value and reports at its
+ * unit's path.
+ */
+const CONFIG_DIFF_DEPTH = 2;
+
+function arrayElementDiff(payloadArr, workspaceArr) {
+  const wsSet = new Set(workspaceArr.map((e) => JSON.stringify(e)));
+  const plSet = new Set(payloadArr.map((e) => JSON.stringify(e)));
+  return {
+    added: payloadArr.filter((e) => !wsSet.has(JSON.stringify(e))),
+    workspaceOnly: workspaceArr.filter((e) => !plSet.has(JSON.stringify(e))),
+  };
+}
+
+function configKeyDiff(payloadObj, workspaceObj, prefix = '') {
+  const added = [];
+  const workspaceOnly = [];
+  const changed = [];
+  const arrays = [];
+  const keys = new Set([...Object.keys(payloadObj), ...Object.keys(workspaceObj)]);
+  for (const key of [...keys].sort()) {
+    const path = prefix ? `${prefix}/${key}` : key;
+    const inPayload = Object.prototype.hasOwnProperty.call(payloadObj, key);
+    const inWorkspace = Object.prototype.hasOwnProperty.call(workspaceObj, key);
+    if (inPayload && !inWorkspace) { added.push(path); continue; }
+    if (!inPayload && inWorkspace) { workspaceOnly.push(path); continue; }
+    const pv = payloadObj[key];
+    const wv = workspaceObj[key];
+    if (
+      prefix.split('/').filter(Boolean).length + 1 < CONFIG_DIFF_DEPTH
+      && isPlainObject(pv) && isPlainObject(wv)
+    ) {
+      const sub = configKeyDiff(pv, wv, path);
+      added.push(...sub.added);
+      workspaceOnly.push(...sub.workspaceOnly);
+      changed.push(...sub.changed);
+      arrays.push(...sub.arrays);
+    } else if (Array.isArray(pv) && Array.isArray(wv)) {
+      // An array both sides hold is a set the workspace extends: element
+      // lists let the skill union-merge instead of choosing one side whole.
+      const diff = arrayElementDiff(pv, wv);
+      if (diff.added.length > 0 || diff.workspaceOnly.length > 0) {
+        arrays.push({ path, ...diff });
+      }
+    } else if (JSON.stringify(pv) !== JSON.stringify(wv)) {
+      changed.push(path);
+    }
+  }
+  return { added, workspaceOnly, changed, arrays };
+}
+
+/**
+ * One `config` entry: the key-level diff for a payload-shipped config file
+ * against the workspace's copy, or a flag when no diff is possible —
+ * `notInstalled` (no workspace file; the skill asks once whether to install
+ * the payload's copy) and `unparseable` (broken JSON on either side; the
+ * skill asks rather than merging blind).
+ */
+function configEntry(absRoot, absPayload, rel) {
+  let payloadJson;
+  try {
+    payloadJson = JSON.parse(readFileSync(join(absPayload, rel), 'utf8'));
+  } catch {
+    return { path: rel, unparseable: true };
+  }
+  if (!isPlainObject(payloadJson)) return { path: rel, unparseable: true };
+  const installed = join(absRoot, rel);
+  if (!existsSync(installed)) return { path: rel, notInstalled: true };
+  let workspaceJson;
+  try {
+    workspaceJson = JSON.parse(readFileSync(installed, 'utf8'));
+  } catch {
+    return { path: rel, unparseable: true };
+  }
+  if (!isPlainObject(workspaceJson)) return { path: rel, unparseable: true };
+  return { path: rel, ...configKeyDiff(payloadJson, workspaceJson) };
+}
+
 function isClassified(payloadRelPath) {
   const first = payloadRelPath.split('/')[0];
   return VERBATIM_ROOTS.includes(first);
@@ -196,7 +330,31 @@ function isOwnedByWorkspace(rel, localFiles) {
   return localFiles.some((pattern) => globMatches(pattern, claudeRel));
 }
 
-export function classifyUpdate({ root, payload }) {
+/**
+ * Which baseline the classification runs against. An explicit --baseline
+ * wins; otherwise the workspace's own <root>/.claude/.template-baseline.json
+ * is tried first, then the payload's .template-baseline.reconstructed.json
+ * (staged by --upgrade for workspaces that predate baselines). The fallback
+ * matters in the worktree flow: <root> is the task worktree, which cannot
+ * see launcher-only files, while the payload travels there by absolute path.
+ * A file that exists but does not parse counts as absent — a corrupt
+ * baseline must not block the reconstructed one (gh:186).
+ */
+export function resolveBaseline({ root, payload, baseline = null }) {
+  const candidates = baseline !== null
+    ? [{ path: resolve(baseline), label: baseline }]
+    : [
+      { path: join(resolve(root), BASELINE_PATH), label: BASELINE_PATH },
+      { path: join(resolve(payload), RECONSTRUCTED_BASELINE_NAME), label: `.workspace-update/${RECONSTRUCTED_BASELINE_NAME}` },
+    ];
+  for (const candidate of candidates) {
+    const parsed = readBaselineFile(candidate.path);
+    if (parsed !== null) return { baseline: parsed, source: candidate.label };
+  }
+  return { baseline: null, source: null };
+}
+
+export function classifyUpdate({ root, payload, baseline: baselineArg = null }) {
   const absRoot = resolve(root);
   const absPayload = resolve(payload ?? join(absRoot, '.workspace-update'));
   if (!existsSync(absPayload)) {
@@ -205,21 +363,30 @@ export function classifyUpdate({ root, payload }) {
 
   const payloadFiles = [...walkFiles(absPayload)].filter(isClassified);
   const payloadSet = new Set(payloadFiles);
-  const baseline = readBaseline(absRoot);
+  const { baseline, source } = resolveBaseline({ root: absRoot, payload: absPayload, baseline: baselineArg });
 
   const result = {
     new: [],
     identical: [],
     updated: [],
     differs: [],
+    config: [],
     localOnly: [],
     deletedLocally: [],
     activated: [],
     removed: [],
     staleTests: [],
     hasBaseline: baseline !== null,
+    baselineSource: source,
+    baselineReconstructed: baseline !== null && baseline.reconstructed === true,
   };
   for (const rel of payloadFiles) {
+    // Jointly-owned JSON configs never compare by content — the config
+    // list carries a key-level diff for the skill to merge instead.
+    if (CONFIG_PATHS.has(rel)) {
+      result.config.push(configEntry(absRoot, absPayload, rel));
+      continue;
+    }
     // A .skip rule whose active counterpart is installed was deliberately
     // activated by this workspace: report it as activated, not new.
     if (rel.startsWith('.claude/rules/') && rel.endsWith('.md.skip')) {
@@ -270,6 +437,9 @@ export function classifyUpdate({ root, payload }) {
   const gitignored = gitIgnoredPaths(absRoot, installedFiles);
   for (const rel of installedFiles) {
     if (skipSet.has(rel)) continue;
+    // A config file the payload dropped stays with the workspace: it holds
+    // user content the template never deletes.
+    if (CONFIG_PATHS.has(rel)) continue;
     // An active rule whose .skip twin is in the payload is an activated rule,
     // not a removed one.
     if (rel.startsWith('.claude/rules/') && rel.endsWith('.md') && skipSet.has(`${rel}.skip`)) continue;
@@ -417,7 +587,17 @@ function resolvePayload(args) {
 }
 
 function writeBaselineMode(args) {
-  const baseline = writeBaseline(args.root, resolvePayload(args));
+  const absPayload = resolvePayload(args);
+  // The previous baseline decides which declined updates keep their old
+  // entry — resolve it exactly as classification does, so the worktree flow
+  // (no baseline of its own yet) carries over from the payload's
+  // reconstructed one instead of starting from nothing.
+  const { baseline: previous } = resolveBaseline({
+    root: args.root,
+    payload: absPayload,
+    baseline: args.baseline,
+  });
+  const baseline = writeBaseline(args.root, absPayload, { previous });
   process.stdout.write(JSON.stringify({
     written: true,
     path: BASELINE_PATH,
@@ -453,7 +633,7 @@ function main() {
   } else if (args.mergeClaudeMd) {
     mergeClaudeMdMode(args);
   } else {
-    const result = classifyUpdate({ root: args.root, payload: args.payload });
+    const result = classifyUpdate({ root: args.root, payload: args.payload, baseline: args.baseline });
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   }
 }

package/template/_claude/scripts/cleanup-work-session.mjs

@@ -4,7 +4,10 @@
 // Teardown order is MANDATORY:
 //   1. Remove each project worktree from its project repo
 //   2. Remove the workspace worktree from the workspace repo
-//   3. Prune each project repo (belt-and-suspenders)
+//   3. Prune each project repo (belt-and-suspenders — and only when every
+//      prunable record in the repo belongs to this session; a repo also
+//      holding an unrelated external worktree is never pruned, so its
+//      record survives gh:187)
 //   4. Delete all local branches
 //   5. Remove the whole work-sessions/{name}/ folder
 //
@@ -83,6 +86,25 @@ function isRepoSegment(name) {
   return !/^\.+$/.test(segs[0]);
 }
 
+// `worktree list --porcelain` stanzas reduced to what prune scoping needs:
+// each stanza's worktree path and whether git marked it prunable. Paths
+// are kept exactly as git printed them (realOf is applied by callers, so
+// a record whose directory is gone survives the comparison).
+function worktreeStanzas(porcelain) {
+  const stanzas = [];
+  let cur = null;
+  for (const line of String(porcelain).split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) {
+      if (cur) stanzas.push(cur);
+      cur = { path: line.slice(9), prunable: false };
+    } else if (cur && line.startsWith('prunable')) {
+      cur.prunable = true;
+    }
+  }
+  if (cur) stanzas.push(cur);
+  return stanzas;
+}
+
 const args = process.argv.slice(2);
 const getArg = (name) => {
   const idx = args.indexOf(`--${name}`);
@@ -335,9 +357,42 @@ if (existsSync(wsWorktree)) {
 }
 
 // === Step 3: Prune each project repo to mop up orphans ===
+//
+// `git worktree prune` has no path filter: one invocation drops EVERY
+// prunable record the repo holds, including records of worktrees that
+// have nothing to do with this workspace — a scratch checkout in tmp, a
+// directory on another drive (gh:187). Those belong to no session, so
+// prune runs only when every prunable record in the repo sits under this
+// session's folder; otherwise it is skipped and the records are named in
+// the output, left registered for whoever owns them.
+const sessionFolderReal = realOf(sessionFolder);
+const sessionFolderAbs = resolve(sessionFolder);
+const underSessionFolder = (recordedPath) => {
+  const normalized = realOf(recordedPath);
+  return [sessionFolderReal, sessionFolderAbs].some(
+    (base) => normalized === base || normalized.startsWith(base + sep)
+      || recordedPath === base || recordedPath.startsWith(base + sep),
+  );
+};
 for (const repo of repos) {
   const repoDir = join(reposDir, repo);
   if (!existsSync(repoDir)) continue;
+  const listRes = git(repoDir, ['worktree', 'list', '--porcelain']);
+  if (!listRes.ok) {
+    errors.push(`Could not list worktrees in ${repo}: ${listRes.err || listRes.out}`);
+    continue;
+  }
+  const foreign = worktreeStanzas(listRes.out)
+    .filter((s) => s.prunable && !underSessionFolder(s.path))
+    .map((s) => s.path);
+  if (foreign.length > 0) {
+    skipped.push({
+      step: 'prune',
+      repo,
+      reason: `prune skipped: ${repo} has prunable worktree records outside this session (${foreign.join(', ')}) — a blanket prune would drop them; they were left registered for their owner`,
+    });
+    continue;
+  }
   const res = git(repoDir, ['worktree', 'prune']);
   if (!res.ok) {
     // Prune is a safety net, but if it fails on a repo we touched, surface
@@ -407,8 +462,14 @@ for (const repo of repos) {
     continue;
   }
   const wtList = listRes.out;
-  if (wtList.includes('prunable')) {
-    errors.push(`Prunable worktree record remains in ${repo} after cleanup (gh:119 symptom)`);
+  // Only this session's own prunable records are a leftover gh:119 orphan;
+  // a prunable record elsewhere in the repo is someone else's worktree and
+  // stays exactly as found (step 3 refused to prune it for that reason).
+  const leftover = worktreeStanzas(wtList)
+    .filter((s) => s.prunable && underSessionFolder(s.path))
+    .map((s) => s.path);
+  if (leftover.length > 0) {
+    errors.push(`Prunable worktree record(s) remain in ${repo} after cleanup (${leftover.join(', ')}) — the gh:119 symptom; inspect them, then run git -C ${repoDir} worktree prune yourself`);
   }
   if (wtList.includes(wsPath)) {
     errors.push(`${repo} still has a worktree record referencing the session path`);