@ulysses-ai/create-workspace 0.14.0-beta.1 → 0.14.0-beta.3

package/template/.claude/scripts/build-shared-context-index.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// Generate shared-context/index.md by walking shared-context/ and reading frontmatter.
+//
+// Source of truth is the filesystem. Hand edits to index.md are overwritten.
+//
+// Usage:
+//   node build-shared-context-index.mjs --write [--root <workspace-root>]
+//   node build-shared-context-index.mjs --check [--root <workspace-root>]
+//
+// --write regenerates shared-context/index.md.
+// --check exits 0 if the on-disk index matches what would be generated, 1 otherwise.
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { parseSessionContent } from '../lib/session-frontmatter.mjs';
+
+const INDEX_FILENAME = 'index.md';
+const LOCKED_DIR = 'locked';
+const IGNORE_FILENAME = '.indexignore';
+
+function parseArgs(argv) {
+  const args = { mode: null, root: process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--write') args.mode = 'write';
+    else if (a === '--check') args.mode = 'check';
+    else if (a === '--root') args.root = argv[++i];
+  }
+  if (!args.mode) {
+    throw new Error('Specify --write or --check');
+  }
+  return args;
+}
+
+function walkMarkdown(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      out.push(...walkMarkdown(full));
+    } else if (st.isFile() && name.endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function readDescription(filePath) {
+  let frontmatter = {};
+  let body = '';
+  try {
+    const parsed = parseSessionContent(readFileSync(filePath, 'utf-8'));
+    frontmatter = parsed.fields || {};
+    body = parsed.body || '';
+  } catch {
+    body = readFileSync(filePath, 'utf-8');
+  }
+
+  if (typeof frontmatter.description === 'string' && frontmatter.description.trim()) {
+    return frontmatter.description.trim();
+  }
+
+  const stripped = body.replace(/^#.*$/m, '').trim();
+  const firstParagraph = stripped.split(/\n\s*\n/, 1)[0] || '';
+  const firstSentence = firstParagraph.replace(/\n/g, ' ').match(/[^.!?]+[.!?]/);
+  if (firstSentence) {
+    const candidate = firstSentence[0].trim();
+    if (candidate.length > 0 && candidate.length <= 200) return candidate;
+  }
+
+  const filename = filePath.split(sep).pop() || '';
+  return filename.replace(/\.md$/, '').replace(/-/g, ' ');
+}
+
+function classify(relativePath) {
+  const parts = relativePath.split(sep);
+  if (parts.length === 1) return { group: '__root__', sortKey: parts[0] };
+  if (parts[0] === LOCKED_DIR) return { group: LOCKED_DIR, sortKey: parts.slice(1).join('/') };
+  return { group: parts[0], sortKey: parts.slice(1).join('/') };
+}
+
+function readIgnorePrefixes(sharedContextDir) {
+  const ignorePath = join(sharedContextDir, IGNORE_FILENAME);
+  if (!existsSync(ignorePath)) return [];
+  return readFileSync(ignorePath, 'utf-8')
+    .split('\n')
+    .map((line) => line.replace(/#.*/, '').trim())
+    .filter((line) => line.length > 0);
+}
+
+function isIgnored(relativePath, prefixes) {
+  for (const prefix of prefixes) {
+    if (relativePath === prefix) return true;
+    if (relativePath.startsWith(prefix.endsWith('/') ? prefix : prefix + '/')) return true;
+  }
+  return false;
+}
+
+function buildEntries(workspaceRoot) {
+  const sharedContextDir = join(workspaceRoot, 'shared-context');
+  if (!existsSync(sharedContextDir)) return [];
+
+  const ignorePrefixes = readIgnorePrefixes(sharedContextDir);
+
+  const files = walkMarkdown(sharedContextDir).filter((f) => {
+    const rel = relative(sharedContextDir, f).split(sep).join('/');
+    if (rel === INDEX_FILENAME) return false;
+    if (isIgnored(rel, ignorePrefixes)) return false;
+    return true;
+  });
+
+  return files
+    .map((file) => {
+      const rel = relative(sharedContextDir, file);
+      const { group, sortKey } = classify(rel);
+      return {
+        group,
+        sortKey,
+        relativePath: rel.split(sep).join('/'),
+        description: readDescription(file),
+      };
+    })
+    .sort((a, b) => {
+      const groupOrder = (g) =>
+        g === LOCKED_DIR ? 0 : g === '__root__' ? 1 : 2;
+      const ga = groupOrder(a.group);
+      const gb = groupOrder(b.group);
+      if (ga !== gb) return ga - gb;
+      if (a.group !== b.group) return a.group.localeCompare(b.group);
+      return a.sortKey.localeCompare(b.sortKey);
+    });
+}
+
+function groupHeading(group) {
+  if (group === LOCKED_DIR) return 'Locked (team truths, always loaded)';
+  if (group === '__root__') return 'Team-shared (root)';
+  return group;
+}
+
+function renderIndex(entries, generatedAt) {
+  const lines = [
+    '---',
+    'type: index',
+    `generated: ${generatedAt}`,
+    '---',
+    '',
+    '# shared-context — index',
+    '',
+    '> Auto-generated by `.claude/scripts/build-shared-context-index.mjs`. Hand edits will be overwritten — update the source files instead.',
+    '',
+  ];
+
+  let currentGroup = null;
+  for (const entry of entries) {
+    if (entry.group !== currentGroup) {
+      if (currentGroup !== null) lines.push('');
+      lines.push(`## ${groupHeading(entry.group)}`, '');
+      currentGroup = entry.group;
+    }
+    lines.push(`- [${entry.relativePath}](${entry.relativePath}) — ${entry.description}`);
+  }
+
+  if (entries.length === 0) {
+    lines.push('_(no shared-context files yet)_');
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function fingerprint(content) {
+  return content
+    .split('\n')
+    .filter((line) => !line.startsWith('generated:'))
+    .join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const indexPath = join(args.root, 'shared-context', INDEX_FILENAME);
+  const entries = buildEntries(args.root);
+  const generatedAt = new Date().toISOString();
+  const fresh = renderIndex(entries, generatedAt);
+
+  if (args.mode === 'check') {
+    if (!existsSync(indexPath)) {
+      process.stdout.write(JSON.stringify({ status: 'missing' }) + '\n');
+      process.exit(1);
+    }
+    const onDisk = readFileSync(indexPath, 'utf-8');
+    if (fingerprint(onDisk) === fingerprint(fresh)) {
+      process.stdout.write(JSON.stringify({ status: 'current', entries: entries.length }) + '\n');
+      process.exit(0);
+    }
+    process.stdout.write(JSON.stringify({ status: 'stale', entries: entries.length }) + '\n');
+    process.exit(1);
+  }
+
+  if (args.mode === 'write') {
+    writeFileSync(indexPath, fresh);
+    process.stdout.write(
+      JSON.stringify({ status: 'written', entries: entries.length, path: indexPath }) + '\n',
+    );
+    process.exit(0);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { buildEntries, renderIndex, fingerprint, readDescription };

package/template/.claude/scripts/build-shared-context-index.test.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// Unit tests for build-shared-context-index.mjs
+// Run: node template/.claude/scripts/build-shared-context-index.test.mjs
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { buildEntries, renderIndex, fingerprint, readDescription } from './build-shared-context-index.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function assert(cond, msg) {
+  if (cond) { passed++; } else { failed++; console.error(`  FAIL: ${msg}`); }
+}
+
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+function setupFixture() {
+  const root = mkdtempSync(join(tmpdir(), 'sc-index-test-'));
+  mkdirSync(join(root, 'shared-context'), { recursive: true });
+  mkdirSync(join(root, 'shared-context', 'locked'), { recursive: true });
+  mkdirSync(join(root, 'shared-context', 'alice'), { recursive: true });
+  return root;
+}
+
+function cleanup(root) {
+  rmSync(root, { recursive: true, force: true });
+}
+
+console.log('# readDescription priority');
+
+{
+  const root = setupFixture();
+  writeFileSync(
+    join(root, 'shared-context', 'with-fm.md'),
+    `---
+state: locked
+type: reference
+description: Frontmatter description wins.
+updated: 2026-04-25
+---
+
+# Title
+
+This is the body.
+`,
+  );
+  const desc = readDescription(join(root, 'shared-context', 'with-fm.md'));
+  assertEq(desc, 'Frontmatter description wins.', 'frontmatter description preferred');
+  cleanup(root);
+}
+
+{
+  const root = setupFixture();
+  writeFileSync(
+    join(root, 'shared-context', 'no-fm-desc.md'),
+    `---
+state: ephemeral
+type: braindump
+updated: 2026-04-25
+---
+
+# Some Title
+
+This is the first paragraph that should be used. It has multiple sentences.
+
+This is a second paragraph.
+`,
+  );
+  const desc = readDescription(join(root, 'shared-context', 'no-fm-desc.md'));
+  assertEq(desc, 'This is the first paragraph that should be used.', 'first sentence fallback');
+  cleanup(root);
+}
+
+{
+  const root = setupFixture();
+  writeFileSync(
+    join(root, 'shared-context', 'no-frontmatter.md'),
+    `# Bare File
+
+Content without frontmatter at all.
+`,
+  );
+  const desc = readDescription(join(root, 'shared-context', 'no-frontmatter.md'));
+  assertEq(desc, 'Content without frontmatter at all.', 'works without frontmatter');
+  cleanup(root);
+}
+
+{
+  const root = setupFixture();
+  writeFileSync(join(root, 'shared-context', 'empty-body.md'), `---
+type: index
+---
+`);
+  const desc = readDescription(join(root, 'shared-context', 'empty-body.md'));
+  assertEq(desc, 'empty body', 'filename slug fallback');
+  cleanup(root);
+}
+
+console.log('# buildEntries grouping & sort');
+
+{
+  const root = setupFixture();
+  writeFileSync(
+    join(root, 'shared-context', 'locked', 'project-status.md'),
+    `---
+description: Project status here.
+---
+
+body
+`,
+  );
+  writeFileSync(
+    join(root, 'shared-context', 'locked', 'naming.md'),
+    `---
+description: Naming convention.
+---
+
+body
+`,
+  );
+  writeFileSync(
+    join(root, 'shared-context', 'inventory.md'),
+    `---
+description: Top-level inventory.
+---
+
+body
+`,
+  );
+  writeFileSync(
+    join(root, 'shared-context', 'alice', 'notes.md'),
+    `---
+description: Alice notes.
+---
+
+body
+`,
+  );
+
+  const entries = buildEntries(root);
+  assertEq(entries.length, 4, '4 entries');
+  assertEq(entries[0].group, 'locked', 'locked first');
+  assertEq(entries[0].sortKey, 'naming.md', 'alphabetical within locked (naming before project)');
+  assertEq(entries[1].sortKey, 'project-status.md', 'second locked entry');
+  assertEq(entries[2].group, '__root__', 'root group second');
+  assertEq(entries[3].group, 'alice', 'user dir last');
+
+  cleanup(root);
+}
+
+console.log('# renderIndex output');
+
+{
+  const entries = [
+    { group: 'locked', sortKey: 'a.md', relativePath: 'locked/a.md', description: 'A.' },
+    { group: '__root__', sortKey: 'b.md', relativePath: 'b.md', description: 'B.' },
+    { group: 'alice', sortKey: 'c.md', relativePath: 'alice/c.md', description: 'C.' },
+  ];
+  const output = renderIndex(entries, '2026-04-25T00:00:00Z');
+  assert(output.includes('## Locked (team truths, always loaded)'), 'has locked heading');
+  assert(output.includes('## Team-shared (root)'), 'has team-shared heading');
+  assert(output.includes('## alice'), 'has user dir heading');
+  assert(output.includes('- [locked/a.md](locked/a.md) — A.'), 'links use relative path');
+  assert(output.includes('generated: 2026-04-25T00:00:00Z'), 'frontmatter has generated timestamp');
+}
+
+{
+  const output = renderIndex([], '2026-04-25T00:00:00Z');
+  assert(output.includes('_(no shared-context files yet)_'), 'empty state');
+}
+
+console.log('# fingerprint ignores generated line');
+
+{
+  const a = `---
+type: index
+generated: 2026-04-25T00:00:00Z
+---
+
+body
+`;
+  const b = `---
+type: index
+generated: 2026-04-26T00:00:00Z
+---
+
+body
+`;
+  assertEq(fingerprint(a), fingerprint(b), 'different generated, same body → same fingerprint');
+}
+
+{
+  const a = `---
+generated: 2026-04-25T00:00:00Z
+---
+
+body one
+`;
+  const b = `---
+generated: 2026-04-25T00:00:00Z
+---
+
+body two
+`;
+  assert(fingerprint(a) !== fingerprint(b), 'different body → different fingerprint');
+}
+
+console.log('# missing shared-context dir');
+
+{
+  const root = mkdtempSync(join(tmpdir(), 'sc-index-empty-'));
+  const entries = buildEntries(root);
+  assertEq(entries, [], 'no shared-context dir yields empty entries');
+  cleanup(root);
+}
+
+console.log('# .indexignore prefix excludes');
+
+{
+  const root = setupFixture();
+  mkdirSync(join(root, 'shared-context', 'archive'), { recursive: true });
+  writeFileSync(
+    join(root, 'shared-context', 'archive', 'old1.md'),
+    `---
+description: Archived 1.
+---
+body
+`,
+  );
+  writeFileSync(
+    join(root, 'shared-context', 'archive', 'old2.md'),
+    `---
+description: Archived 2.
+---
+body
+`,
+  );
+  writeFileSync(
+    join(root, 'shared-context', 'live.md'),
+    `---
+description: Live file.
+---
+body
+`,
+  );
+  writeFileSync(join(root, 'shared-context', '.indexignore'), 'archive/\n# comment\n\n');
+
+  const entries = buildEntries(root);
+  assertEq(entries.length, 1, 'archive/ excluded by .indexignore');
+  assertEq(entries[0].relativePath, 'live.md', 'only live.md survives');
+  cleanup(root);
+}
+
+{
+  const root = setupFixture();
+  writeFileSync(
+    join(root, 'shared-context', 'a.md'),
+    `---
+description: A.
+---
+body
+`,
+  );
+  writeFileSync(
+    join(root, 'shared-context', 'b.md'),
+    `---
+description: B.
+---
+body
+`,
+  );
+  writeFileSync(join(root, 'shared-context', '.indexignore'), 'a.md\n');
+  const entries = buildEntries(root);
+  assertEq(entries.length, 1, 'specific file excluded by .indexignore');
+  assertEq(entries[0].relativePath, 'b.md', 'only b.md survives');
+  cleanup(root);
+}
+
+console.log('# index.md is excluded from its own entries');
+
+{
+  const root = setupFixture();
+  writeFileSync(
+    join(root, 'shared-context', 'index.md'),
+    `---
+type: index
+---
+
+# index
+`,
+  );
+  writeFileSync(
+    join(root, 'shared-context', 'real.md'),
+    `---
+description: Real file.
+---
+
+body
+`,
+  );
+  const entries = buildEntries(root);
+  assertEq(entries.length, 1, 'only the non-index file');
+  assertEq(entries[0].relativePath, 'real.md', 'index.md excluded');
+  cleanup(root);
+}
+
+console.log('');
+console.log(`${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

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

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// 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
+// Or import { runMigration } and call programmatically.
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const INCLUDE_LINE = '@local-only-template-freshness.md';
+
+export function runMigration({ workspaceRoot }) {
+  const path = join(workspaceRoot, 'CLAUDE.md');
+  if (!existsSync(path)) return { action: 'skipped', reason: 'no-claude-md' };
+  const before = readFileSync(path, 'utf-8');
+  if (before.includes(INCLUDE_LINE)) return { action: 'unchanged' };
+  const after = before.endsWith('\n') ? before + INCLUDE_LINE + '\n' : before + '\n' + INCLUDE_LINE + '\n';
+  writeFileSync(path, after);
+  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));
+}

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

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Unit tests for migrate-claude-md-freshness-include.mjs
+// Run: node template/.claude/scripts/migrate-claude-md-freshness-include.test.mjs
+import { runMigration } from './migrate-claude-md-freshness-include.mjs';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+let failed = 0;
+let passed = 0;
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+function withTemp(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'claude-md-mig-'));
+  try { fn(dir); } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+console.log('# migrate-claude-md-freshness-include');
+
+// CLAUDE.md missing → no-op
+withTemp((dir) => {
+  const result = runMigration({ workspaceRoot: dir });
+  assertEq(result.action, 'skipped', 'no CLAUDE.md is skipped');
+});
+
+// CLAUDE.md missing the include → appended
+withTemp((dir) => {
+  const path = join(dir, 'CLAUDE.md');
+  writeFileSync(path, '# Workspace\n@workspace.json\n');
+  const result = runMigration({ workspaceRoot: dir });
+  assertEq(result.action, 'appended', 'missing line is appended');
+  const after = readFileSync(path, 'utf-8');
+  assertEq(after.includes('@local-only-template-freshness.md'), true, 'line present after migration');
+});
+
+// CLAUDE.md already has the include → no-op
+withTemp((dir) => {
+  const path = join(dir, 'CLAUDE.md');
+  const original = '# Workspace\n@workspace.json\n@local-only-template-freshness.md\n';
+  writeFileSync(path, original);
+  const result = runMigration({ workspaceRoot: dir });
+  assertEq(result.action, 'unchanged', 'already-present line is unchanged');
+  assertEq(readFileSync(path, 'utf-8'), original, 'file content unchanged');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/template/.claude/settings.json

@@ -15,6 +15,12 @@
             "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"${CLAUDE_PROJECT_DIR:-$PWD}\"; else echo \"${CLAUDE_PROJECT_DIR:-$PWD}\"; fi)\"/.claude/hooks/session-start.mjs",
             "timeout": 30000,
             "statusMessage": "Syncing workspace..."
+          },
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"${CLAUDE_PROJECT_DIR:-$PWD}\"; else echo \"${CLAUDE_PROJECT_DIR:-$PWD}\"; fi)\"/.claude/hooks/version-freshness-check.mjs",
+            "timeout": 5000,
+            "statusMessage": "Checking template freshness..."
           }
         ]
       }