@ulysses-ai/create-workspace 0.18.0-beta.0 → 0.20.0-beta.0

package/template/{.claude → _claude}/scripts/build-workspace-context.mjs

@@ -9,12 +9,14 @@
 // Source of truth: the filesystem. Hand edits are overwritten on regeneration.
 // Gitignored files are excluded automatically. .indexignore adds prefix excludes.
 //
-// Canonical files honor a configurable byte budget. Each locked file declares
+// Canonical files honor an opt-in byte budget. Each locked file declares
 // `priority: critical | reference` in its frontmatter (default: critical).
 // Section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` markers
-// fence droppable spans inside reference files. When canonical body bytes exceed
-// the budget, the builder trims reference files first, then stubs them, in that
-// deterministic order. Critical files are never modified.
+// fence droppable spans inside reference files. When a budget is set and the
+// canonical body exceeds it, the builder trims reference files first, then
+// stubs them, in that deterministic order. Critical files are never modified.
+// `workspace.canonicalBudgetBytes` is off unless it holds a number: absent or
+// null means every locked file ships in full and nothing is trimmed.
 //
 // Usage:
 //   node build-workspace-context.mjs --write [--root <workspace-root>]
@@ -25,6 +27,7 @@
 //   0 — all artifacts current and canonical within budget
 //   1 — at least one artifact missing or stale (regenerate via --write)
 //   2 — artifacts current, but canonical body exceeds budget after trimming and stubbing
+//       (only reachable when a budget is set; off means nothing can exceed it)
 // Stale wins over over-budget when both apply.
 
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, realpathSync } from 'node:fs';
@@ -301,16 +304,19 @@ export function extractCanonicalVariants({ name, rawContent }) {
 }
 
 /**
- * Read `workspace.canonicalBudgetBytes` from `workspace.json`.
+ * Read `workspace.canonicalBudgetBytes` from `workspace.json`. The budget is
+ * opt-in — the whole always-loaded set is measured by `alwaysLoadedBudgetBytes`
+ * instead, so a canonical-only ceiling is something a workspace opts into.
  * Returns:
- *   - The integer value when set to a non-negative integer.
- *   - 0 when set to 0 or a negative number (treated as disabled).
- *   - DEFAULT_CANONICAL_BUDGET when the field is absent or workspace.json is missing.
+ *   - 0 when the field is absent or `null`, or workspace.json is missing (off).
+ *   - 0 when set to 0 or a negative number (treated as off).
+ *   - The integer value when set to a positive number.
+ *   - DEFAULT_CANONICAL_BUDGET when set to a non-number (invalid, rejected as before).
  *   - DEFAULT_CANONICAL_BUDGET (with a stderr warning) when workspace.json fails to parse.
  */
 export function readWorkspaceBudget(workspaceRoot) {
   const path = join(workspaceRoot, 'workspace.json');
-  if (!existsSync(path)) return DEFAULT_CANONICAL_BUDGET;
+  if (!existsSync(path)) return 0;
   let parsed;
   try {
     parsed = JSON.parse(readFileSync(path, 'utf-8'));
@@ -319,9 +325,10 @@ export function readWorkspaceBudget(workspaceRoot) {
     return DEFAULT_CANONICAL_BUDGET;
   }
   const ws = parsed && typeof parsed === 'object' ? parsed.workspace : null;
-  if (!ws || typeof ws !== 'object') return DEFAULT_CANONICAL_BUDGET;
-  if (!('canonicalBudgetBytes' in ws)) return DEFAULT_CANONICAL_BUDGET;
+  if (!ws || typeof ws !== 'object') return 0;
+  if (!('canonicalBudgetBytes' in ws)) return 0;
   const v = ws.canonicalBudgetBytes;
+  if (v === null) return 0;
   if (typeof v !== 'number' || !Number.isFinite(v)) return DEFAULT_CANONICAL_BUDGET;
   if (v <= 0) return 0;
   return Math.floor(v);
@@ -359,7 +366,8 @@ export function renderCanonicalBody(resolvedItems) {
  *   4. Keep stage-3 resolution; status `over-budget`, overBy populated.
  *
  * Special cases:
- *   - budgetBytes <= 0: stage 1 always wins, selection.budgetBytes = null.
+ *   - budgetBytes <= 0 (off — absent, null, 0, or negative): stage 1 always
+ *     wins, selection.budgetBytes = null.
  *   - No reference items present and stage 1 fails: status `over-budget`,
  *     no transformation possible. Stderr warning is emitted.
  */
@@ -380,7 +388,7 @@ export function selectCanonicalContent(items, budgetBytes, opts) {
     return { name: item.name, priority: item.priority, content: item.full };
   });
 
-  // Disabled-budget path.
+  // No-budget path (off because unset, or explicitly disabled).
   if (!Number.isFinite(budgetBytes) || budgetBytes <= 0) {
     const resolved = resolveAt(1);
     return {
@@ -537,6 +545,8 @@ function renderCanonical(resolvedItems, selection) {
     lines.push(
       `> Budget: ${selection.budgetBytes} bytes (body); current: ${selection.currentBytes} bytes; status: ${selection.status} (${summarizeSelection(selection)}).`,
     );
+  } else if (selection) {
+    lines.push(`> Budget: off; current: ${selection.currentBytes} bytes.`);
   }
   lines.push('');
 
@@ -673,7 +683,8 @@ function regenerateAll(workspaceRoot) {
  *   0 — all artifacts current and canonical body is within budget.
  *   1 — at least one artifact is missing or stale on disk. Run `--write`.
  *   2 — artifacts are current but canonical body exceeds budget after
- *       trimming and stubbing eligible reference files. Triage via
+ *       trimming and stubbing eligible reference files (only reachable when
+ *       a budget is set — off means nothing can exceed it). Triage via
  *       `/maintenance cleanup`. If both stale and over-budget, exit 1.
  *
  * `--write` always exits 0 on successful regeneration; over-budget is

package/template/{.claude → _claude}/scripts/chat-record.mjs

@@ -20,6 +20,18 @@
 //   node chat-record.mjs --root <dir> --list
 //   node chat-record.mjs --root <dir> --read  <chat-name>
 //   node chat-record.mjs --root <dir> --reconcile --session-id <id> --name <n>
+//   node chat-record.mjs --root <dir> --whoami
+//   node chat-record.mjs --root <dir> --add-task    --chat <n> --branch <b> [--repo <r>] [--work-item <id>]
+//   node chat-record.mjs --root <dir> --remove-task --chat <n> (--work-item <id> | --branch <b>) [--repo <r>]
+//
+// --add-task / --remove-task report `action`: "added" | "updated" for
+// --add-task, "removed" | "unchanged" for --remove-task. They also keep the
+// older `updated` boolean / `removed` count fields — `updated` means "an
+// existing entry was replaced", not "anything changed" — but new callers
+// should read `action`. --whoami prints this chat's record name by matching
+// $CLAUDE_CODE_SESSION_ID against the records' sessionId, nothing and exit
+// 1 when there is no match: the `Chat record:` hook line can be missing
+// after context compaction, and this is the recovery path.
 
 import {
   readFileSync, writeFileSync, existsSync, mkdirSync,
@@ -179,35 +191,54 @@ function resolveChatName(root, { sessionId, registryName = null } = {}) {
 }
 
 
-// A task is a tracker issue plus a branch plus the repo it lands in. It is
-// created on demand and disappears when it merges — nothing about it is
-// durable except the issue and the commits, so the record holds only the
-// pointer, never a copy of the issue.
+// A task is a branch plus the repo it lands in, plus the tracker issue when
+// the workspace has one. It is created on demand and disappears when it
+// merges — nothing about it is durable except the issue and the commits, so
+// the record holds only the pointer, never a copy of the issue.
 //
 // Identity is workItem + repo: the same issue can legitimately be open against
 // two repos in a multi-repo task, and re-recording the same one must update
-// rather than duplicate. /start-work is not always run exactly once.
-function addTask(root, chatName, { workItem, branch, repo = null } = {}) {
-  if (!workItem) throw new Error('addTask: workItem is required');
+// rather than duplicate. /start-work is not always run exactly once. A task
+// recorded without a tracker (gh:173) carries `workItem: null` and is keyed
+// by branch + repo instead — the branch is the only identity it has — so
+// both add and remove take the branch for those entries.
+function addTask(root, chatName, { workItem = null, branch, repo = null } = {}) {
   if (!branch) throw new Error('addTask: branch is required');
   const rec = readRecord(root, chatName);
   if (!rec) throw new Error(`addTask: no chat record for "${chatName}"`);
-  const i = rec.tasks.findIndex((t) => t.workItem === workItem && (t.repo ?? null) === repo);
+  const i = rec.tasks.findIndex(
+    (t) => (t.workItem ?? null) === workItem && (t.repo ?? null) === repo
+      && (workItem !== null || t.branch === branch),
+  );
   const task = { workItem, branch, repo };
   if (i >= 0) rec.tasks[i] = task;
   else rec.tasks.push(task);
   writeRecord(root, rec);
-  return { record: rec, updated: i >= 0 };
+  return { record: rec, action: i >= 0 ? 'updated' : 'added', updated: i >= 0 };
 }
 
-function removeTask(root, chatName, { workItem, repo = null } = {}) {
-  if (!workItem) throw new Error('removeTask: workItem is required');
+function removeTask(root, chatName, { workItem = null, branch = null, repo = null } = {}) {
+  if (workItem === null && !branch) throw new Error('removeTask: workItem or branch is required');
   const rec = readRecord(root, chatName);
   if (!rec) throw new Error(`removeTask: no chat record for "${chatName}"`);
   const before = rec.tasks.length;
-  rec.tasks = rec.tasks.filter((t) => !(t.workItem === workItem && (t.repo ?? null) === repo));
+  rec.tasks = rec.tasks.filter(
+    (t) => !((t.workItem ?? null) === workItem && (t.repo ?? null) === repo
+      && (workItem !== null || t.branch === branch)),
+  );
   writeRecord(root, rec);
-  return { record: rec, removed: before - rec.tasks.length };
+  return { record: rec, action: before - rec.tasks.length > 0 ? 'removed' : 'unchanged', removed: before - rec.tasks.length };
+}
+
+// The record name for the chat running now. The SessionStart hook injects
+// a `Chat record:` line, but compaction can drop it; the sessionId the
+// hook keyed on is stable, so matching it against the records recovers the
+// name without guessing. Null when the env var is unset or nothing matches.
+function whoami(root, { env = process.env } = {}) {
+  const sid = env.CLAUDE_CODE_SESSION_ID;
+  if (!sid) return null;
+  const mine = listRecords(root).find((r) => r.sessionId === sid);
+  return mine ? mine.chat : null;
 }
 
 // Scope is what a chat declares it owns. The Aug 26 coordination burst had
@@ -230,6 +261,7 @@ function parseArgs(argv) {
     if (a === '--list') { args.mode = 'list'; continue; }
     if (a === '--read') { args.mode = 'read'; args.chat = rest[++i]; continue; }
     if (a === '--reconcile') { args.mode = 'reconcile'; continue; }
+    if (a === '--whoami') { args.mode = 'whoami'; continue; }
     if (a === '--add-task') { args.mode = 'add-task'; continue; }
     if (a === '--remove-task') { args.mode = 'remove-task'; continue; }
     if (a === '--chat') { args.chat = rest[++i]; continue; }
@@ -240,28 +272,37 @@ function parseArgs(argv) {
     if (a === '--name') { args.name = rest[++i]; continue; }
     throw new Error(`unknown argument: ${a}`);
   }
-  if (!args.mode) throw new Error('one of --list, --read <chat>, --reconcile is required');
+  if (!args.mode) throw new Error('one of --list, --read <chat>, --reconcile, --whoami is required');
   if (args.mode === 'reconcile' && (!args.sessionId || !args.name)) {
     throw new Error('--reconcile requires --session-id and --name');
   }
-  if (args.mode === 'add-task' && (!args.chat || !args.workItem || !args.branch)) {
-    throw new Error('--add-task requires --chat, --work-item and --branch');
+  if (args.mode === 'add-task' && (!args.chat || !args.branch)) {
+    throw new Error('--add-task requires --chat and --branch (--work-item is optional — omitted without a tracker)');
   }
-  if (args.mode === 'remove-task' && (!args.chat || !args.workItem)) {
-    throw new Error('--remove-task requires --chat and --work-item');
+  if (args.mode === 'remove-task' && (!args.chat || (!args.workItem && !args.branch))) {
+    throw new Error('--remove-task requires --chat and --work-item or --branch');
   }
   return args;
 }
 
 function main() {
   const args = parseArgs(process.argv);
+  if (args.mode === 'whoami') {
+    // A bare name, not JSON: the caller wants something to put on a command
+    // line. No match prints nothing and exits 1 — the caller decides what
+    // an unidentified chat means.
+    const name = whoami(args.root);
+    if (name === null) process.exit(1);
+    process.stdout.write(`${name}\n`);
+    return;
+  }
   let out;
   if (args.mode === 'list') out = listRecords(args.root);
   else if (args.mode === 'read') out = readRecord(args.root, args.chat);
   else if (args.mode === 'add-task') {
-    out = addTask(args.root, args.chat, { workItem: args.workItem, branch: args.branch, repo: args.repo });
+    out = addTask(args.root, args.chat, { workItem: args.workItem ?? null, branch: args.branch, repo: args.repo });
   } else if (args.mode === 'remove-task') {
-    out = removeTask(args.root, args.chat, { workItem: args.workItem, repo: args.repo });
+    out = removeTask(args.root, args.chat, { workItem: args.workItem ?? null, branch: args.branch, repo: args.repo });
   } else out = reconcile(args.root, { sessionId: args.sessionId, name: args.name });
   process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
 }
@@ -278,5 +319,5 @@ if (isMainModule(import.meta.url)) {
 export {
   recordPath, drawerPath, emptyRecord, readRecord, writeRecord,
   listRecords, reconcile, parseArgs, readSessionRegistry, resolveChatName,
-  addTask, removeTask, setScope, CHATS_DIR,
+  addTask, removeTask, setScope, whoami, CHATS_DIR,
 };

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

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Classify an upgrade payload's files against the workspace so /workspace-update
+// can batch the safe cases and ask only where a decision is needed.
+//
+// Usage:
+//   node classify-update.mjs [--root <dir>] [--payload <dir>]
+//
+// --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
+//
+// Prints JSON: { "new": [...], "identical": [...], "differs": [...] }
+//   new       — no installed counterpart; safe to batch-apply after one confirm
+//   identical — installed file already equals the payload byte-for-byte
+//   differs   — installed file differs; needs a per-file decision
+//
+// 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.
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  realpathSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+function parseArgs(argv) {
+  const args = { root: process.cwd(), payload: null };
+  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 throw new Error(`Unknown arg: ${a}`);
+  }
+  return args;
+}
+
+// Payload-relative paths that install verbatim at the same relative path.
+// Everything else in the payload is a template or metadata handled elsewhere.
+const VERBATIM_ROOTS = ['.claude', '.mcp.json', '.claudeignore'];
+
+function isClassified(payloadRelPath) {
+  const first = payloadRelPath.split('/')[0];
+  return VERBATIM_ROOTS.includes(first);
+}
+
+function* walkFiles(dir, prefix = '') {
+  let entries;
+  try {
+    entries = readdirSync(dir).sort();
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const rel = prefix ? `${prefix}/${name}` : name;
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) yield* walkFiles(full, rel);
+    else if (st.isFile()) yield rel;
+  }
+}
+
+export function classifyUpdate({ root, payload }) {
+  const absRoot = resolve(root);
+  const absPayload = resolve(payload ?? join(absRoot, '.workspace-update'));
+  if (!existsSync(absPayload)) {
+    throw new Error(`No payload found at ${absPayload} — run npx @ulysses-ai/create-workspace --upgrade first`);
+  }
+
+  const result = { new: [], identical: [], differs: [] };
+  for (const rel of walkFiles(absPayload)) {
+    if (!isClassified(rel)) continue;
+    const installed = join(absRoot, rel);
+    if (!existsSync(installed)) {
+      result.new.push(rel);
+      continue;
+    }
+    const payloadBytes = readFileSync(join(absPayload, rel));
+    const installedBytes = readFileSync(installed);
+    if (Buffer.compare(payloadBytes, installedBytes) === 0) {
+      result.identical.push(rel);
+    } else {
+      result.differs.push(rel);
+    }
+  }
+  return result;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const result = classifyUpdate({ root: args.root, payload: args.payload });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`classify-update: ${err.message}\n`);
+    process.exit(1);
+  }
+}

package/template/{.claude → _claude}/scripts/cleanup-work-session.mjs

@@ -146,9 +146,11 @@ if (repos.length === 0) {
       if (found.length > 0) {
         repos = found;
         discovered = true;
+        // Informational wording: discovery is a normal success path here
+        // (gh:172) — not a warning about the tracker.
         skipped.push({
           step: 'discovery',
-          reason: `Tracker missing repos; discovered ${found.length} from ${nestedReposDir}: ${found.join(', ')}`,
+          reason: `repos discovered from disk: ${found.length} (${found.join(', ')})`,
         });
       }
     } catch (err) {
@@ -209,7 +211,7 @@ if (!branch && existsSync(wsWorktree)) {
   const res = git(wsWorktree, ['rev-parse', '--abbrev-ref', 'HEAD']);
   if (res.ok && res.out.trim() !== '' && res.out.trim() !== 'HEAD') {
     branch = res.out.trim();
-    skipped.push({ step: 'discovery', reason: `Tracker missing branch; discovered from worktree: ${branch}` });
+    skipped.push({ step: 'discovery', reason: `branch discovered from the worktree: ${branch}` });
   }
 }