@ulysses-ai/create-workspace 0.19.0-beta.0 → 0.21.0-beta.0

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

@@ -0,0 +1,212 @@
+#!/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 with five lists:
+//   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
+//   activated — the payload ships rules/{name}.md.skip while the workspace
+//               deliberately keeps {name}.md active; nothing to install, the
+//               active rule stays (gh:180)
+//   removed   — installed file with no payload counterpart: the template
+//               stopped shipping it. Excludes what the workspace owns:
+//               *.test.mjs (the npm tarball does not ship tests, dev-checkout
+//               installs do — every test file would otherwise read as
+//               removed), anything gitignored (machine-local), paths under
+//               .claude/worktrees/, and entries of workspace.json →
+//               workspace.localFiles (array of .claude/-relative paths or
+//               globs for files this workspace owns) (gh:180)
+//
+// 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';
+import { gitIgnoredPaths } from './build-workspace-context.mjs';
+
+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);
+}
+
+// Directories never walked when looking for removed files. .claude/worktrees/
+// holds entire nested worktrees — walking them is slow and every file inside
+// is unmanaged by the template.
+const SKIPPED_DIRS = new Set(['worktrees']);
+
+function* walkFiles(dir, prefix = '', skipDirs = null) {
+  let entries;
+  try {
+    entries = readdirSync(dir).sort();
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (skipDirs && skipDirs.has(name)) continue;
+    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, skipDirs);
+    else if (st.isFile()) yield rel;
+  }
+}
+
+// Installed files under the verbatim-managed roots: the .claude/ tree (minus
+// skipped directories) plus the two standalone files. Nothing else in the
+// workspace root is walked — repos/ and work-sessions/ hold entire worktrees
+// the template never manages.
+function* walkInstalledFiles(absRoot) {
+  yield* walkFiles(join(absRoot, '.claude'), '.claude', SKIPPED_DIRS);
+  for (const name of ['.mcp.json', '.claudeignore']) {
+    if (existsSync(join(absRoot, name))) yield name;
+  }
+}
+
+/** workspace.json → workspace.localFiles, normalized to .claude/-relative globs. */
+function readLocalFiles(absRoot) {
+  const configPath = join(absRoot, 'workspace.json');
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    const entries = config?.workspace?.localFiles;
+    if (!Array.isArray(entries)) return [];
+    return entries
+      .filter((e) => typeof e === 'string' && e.length > 0)
+      .map((e) => e.replace(/^(\.claude\/)+/, ''));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Match `rel` (a .claude/-relative posix path) against a localFiles entry —
+ * an exact path or a glob where `**` spans separators and `*` does not.
+ * No glob library: the shapes localFiles needs are these two stars.
+ */
+function globMatches(pattern, rel) {
+  if (pattern === rel) return true;
+  if (!pattern.includes('*')) return false;
+  const re = new RegExp(
+    `^${pattern.split('**').map(
+      (part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*'),
+    ).join('.*')}$`,
+  );
+  return re.test(rel);
+}
+
+function isOwnedByWorkspace(rel, localFiles) {
+  if (rel.endsWith('.test.mjs')) return true;
+  // The template's own .gitignore declares these machine-local.
+  if (rel === '.claude/settings.local.json' || rel === '.claude/.active-session.json') return true;
+  if (!rel.startsWith('.claude/')) return false;
+  const claudeRel = rel.slice('.claude/'.length);
+  return localFiles.some((pattern) => globMatches(pattern, claudeRel));
+}
+
+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 payloadFiles = [...walkFiles(absPayload)].filter(isClassified);
+  const payloadSet = new Set(payloadFiles);
+
+  const result = { new: [], identical: [], differs: [], activated: [], removed: [] };
+  for (const rel of payloadFiles) {
+    // 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')) {
+      const active = rel.replace(/\.skip$/, '');
+      if (existsSync(join(absRoot, active)) && !existsSync(join(absRoot, rel))) {
+        result.activated.push({ skip: rel, active });
+        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);
+    }
+  }
+
+  // Removed: installed verbatim-managed files with no payload counterpart.
+  const skipSet = new Set(payloadFiles);
+  const localFiles = readLocalFiles(absRoot);
+  const installedFiles = [...walkInstalledFiles(absRoot)];
+  const gitignored = gitIgnoredPaths(absRoot, installedFiles);
+  for (const rel of installedFiles) {
+    if (skipSet.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;
+    if (gitignored.has(rel)) continue;
+    if (isOwnedByWorkspace(rel, localFiles)) continue;
+    result.removed.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/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}` });
   }
 }
 

package/template/_claude/scripts/merge-mode.mjs

@@ -0,0 +1,61 @@
+// Merge-mode resolution for the task lifecycle (gh:173), shared by
+// task-worktree.mjs (which branch a new task worktree starts from) and
+// task-pr.mjs (push-and-PR versus merge-in-the-source-clone). It lives in
+// its own module because those two import each other's helpers: housing
+// the rule here keeps its definition singular without a circular import.
+
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// The workspace repo (the launcher) is addressed as "." — the one repo
+// name that is not a directory under repos/.
+const WORKSPACE_REPO = '.';
+
+// "." is the workspace repo itself — the git repo at the root. Every other
+// name is a directory under repos/.
+function repoDirFor(rootDir, repo) {
+  return repo === WORKSPACE_REPO ? rootDir : join(rootDir, 'repos', repo);
+}
+
+function readWorkspace(rootDir) {
+  try {
+    return JSON.parse(readFileSync(join(rootDir, 'workspace.json'), 'utf-8'));
+  } catch {
+    throw new Error(`cannot read ${join(rootDir, 'workspace.json')} — is --root the launcher?`);
+  }
+}
+
+// Same remote shapes the forge adapters resolve a repo from. A URL that
+// does not match is not forge-hosted, and the forge path supports
+// forge-hosted repos only — a local/bare remote has no PR concept to aim at.
+const FORGE_REMOTE_RE = /github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/;
+
+function parseForgeRemote(url) {
+  const m = String(url).trim().match(FORGE_REMOTE_RE);
+  return m ? { owner: m[1], name: m[2] } : null;
+}
+
+/**
+ * Resolve how a task repo merges: "local" — nothing pushed, merged in the
+ * repo's own source clone — when workspace.json asks for it
+ * (repos.{repo}.merge, or workspace.merge for the workspace repo; the
+ * right call for a clone whose origin is a third-party upstream nobody
+ * here may push to) or when the repo has no origin remote at all;
+ * "forge" — pushed and PR'd — when its origin parses as a forge-hosted
+ * owner/name. An origin that is neither (say a local bare mirror with no
+ * override) resolves to null: the caller stops with the override spelled
+ * out rather than pushing somewhere that cannot host a PR.
+ */
+function mergeModeFor(root, repo, deps = {}) {
+  const gitFn = deps.gitFn ?? spawnSync;
+  const rootDir = resolve(root);
+  const ws = readWorkspace(rootDir);
+  const override = repo === WORKSPACE_REPO ? ws?.workspace?.merge : ws?.repos?.[repo]?.merge;
+  if (override === 'local') return 'local';
+  const res = gitFn('git', ['-C', repoDirFor(rootDir, repo), 'remote', 'get-url', 'origin'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) return 'local'; // no origin — nowhere to push
+  return parseForgeRemote(String(res.stdout || '').trim()) ? 'forge' : null;
+}
+
+export { WORKSPACE_REPO, repoDirFor, readWorkspace, parseForgeRemote, mergeModeFor };

package/template/_claude/scripts/migrate-canonical-priority.mjs

@@ -7,7 +7,9 @@
 //   node migrate-canonical-priority.mjs [--root <path>]
 //
 // Walks <root>/workspace-context/shared/locked/*.md. For each file:
-//   - Skip non-.md files and files without parseable frontmatter (warn to stderr).
+//   - Skip non-.md files, local-only-* files (machine-local drafts that
+//     happen to sit under shared/locked/ — never canonical), and files
+//     without parseable frontmatter (warn to stderr).
 //   - If `priority` is already set (any value), leave the file untouched.
 //   - Otherwise add `priority: critical` losslessly via updateSessionContent.
 //
@@ -62,6 +64,10 @@ export function migrateCanonicalPriority({ root }) {
 
   for (const name of entries) {
     if (!name.endsWith('.md')) continue;
+    // local-only-* files are machine-local and gitignored — they are never
+    // canonical, so back-filling a canonical priority field on them would be
+    // both wrong and a surprise on the next build-workspace-context run.
+    if (name.startsWith('local-only-')) continue;
     const full = join(lockedDir, name);
     let st;
     try { st = statSync(full); } catch { continue; }

package/template/_claude/scripts/migrate-claude-md-freshness-include.mjs

@@ -2,10 +2,16 @@
 // Idempotent migrator: ensures CLAUDE.md includes @local-only-template-freshness.md.
 // Appends one line at end if missing. Preserves the rest of the file byte-for-byte.
 //
-// Run standalone: node .claude/scripts/migrate-claude-md-freshness-include.mjs
+// Run standalone: node migrate-claude-md-freshness-include.mjs [--root <dir>]
 // Or import { runMigration } and call programmatically.
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { join, dirname, resolve } from 'path';
+//
+// The root is --root when given, else the current working directory. It is
+// never derived from this script's location: the upgrade payload runs this
+// file from <workspace>/.workspace-update/.claude/scripts/, and a
+// script-relative root would point inside the payload instead of at the
+// workspace.
+import { existsSync, readFileSync, writeFileSync, realpathSync } from 'fs';
+import { join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
 const INCLUDE_LINE = '@local-only-template-freshness.md';
@@ -20,11 +26,30 @@ export function runMigration({ workspaceRoot }) {
   return { action: 'appended' };
 }
 
-// CLI entry point — workspace root is two levels up from this file
-// (.claude/scripts/migrate-... → workspace root).
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const root = resolve(here, '..', '..');
-  const result = runMigration({ workspaceRoot: root });
-  console.log(JSON.stringify(result));
+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() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--root') args.root = argv[++i];
+    else throw new Error(`Unknown arg: ${a}`);
+  }
+  return args;
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const args = parseArgs(process.argv);
+    const result = runMigration({ workspaceRoot: resolve(args.root) });
+    console.log(JSON.stringify(result));
+  } catch (err) {
+    console.error(`migrate-claude-md-freshness-include: ${err.message}`);
+    process.exit(1);
+  }
 }

package/template/_claude/scripts/migrate-session-layout.mjs

@@ -22,15 +22,26 @@ import {
   readdirSync,
   copyFileSync,
   statSync,
+  realpathSync,
 } from 'fs';
 import { join } from 'path';
+import { fileURLToPath } from 'url';
 import {
-  getWorkspaceRoot,
   getWorkspacePaths,
   getMainRoot,
   readJSON,
 } from '../hooks/_utils.mjs';
 
+// Compare real paths: macOS temp dirs are symlinked (/var → /private/var),
+// so a naive import.meta.url === `file://${process.argv[1]}` silently fails
+// to detect main-module runs from tmpdir fixtures.
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
 export function migrateSession(root, sessionName) {
   const { workSessionsDir } = getWorkspacePaths(root);
   const sessionFolder = join(workSessionsDir, sessionName);
@@ -189,19 +200,19 @@ export function migrateMain(root) {
 }
 
 // CLI entry
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
   const getArg = (name) => {
     const i = args.indexOf(`--${name}`);
     return i >= 0 && args[i + 1] ? args[i + 1] : null;
   };
 
-  // The script lives in either the launcher's .claude/scripts/ or a session
-  // worktree's .claude/scripts/. getWorkspaceRoot returns the script's
-  // grandparent; when that's a worktree, promote it to the launcher via
-  // the .active-session.json pointer.
-  const inferred = getWorkspaceRoot(import.meta.url);
-  const root = getArg('root') || getMainRoot(inferred);
+  // The workspace root is --root when given, else the cwd — promoted to the
+  // launcher via the .active-session.json pointer when the cwd is a session
+  // worktree. It is never derived from this script's location: an upgrade
+  // payload runs this file from <workspace>/.workspace-update/.claude/scripts/,
+  // and a script-relative root would point inside the payload.
+  const root = getArg('root') || getMainRoot(process.cwd());
 
   const runAll = args.includes('--all');
   const runMain = args.includes('--main');