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

package/README.md

@@ -90,7 +90,7 @@ A scaffolded workspace with:
 
 - **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
 - **7 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
-- **9 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- **10 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
 - A **`shared-context/`** memory system with three visibility levels: locked (team truths), root (team-visible ephemerals), user-scoped (personal)
 - Conventions for **multi-repo work sessions** with isolated git worktrees, parallelizable from separate terminals
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.14.0-beta.1",
+  "version": "0.15.0-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/.claude/agents/reviewer.md

@@ -27,7 +27,7 @@ You are reviewing code changes. Your job is to find problems, not to fix them.
 3. **Edge cases** — are there scenarios not handled?
 4. **Test coverage** — are tests covering the right scenarios? Are they testing behavior, not implementation?
 5. **Security** — any injection, XSS, or auth issues?
-6. **Consistency** — does it match existing patterns in shared-context/locked/?
+6. **Consistency** — does it match existing patterns in workspace-context/shared/locked/?
 
 ## What NOT to review
 - Style preferences (defer to linters/formatters)

package/template/.claude/hooks/pre-compact.mjs

@@ -30,5 +30,5 @@ if (pointer) {
     respond(`Context is about to be compacted. No session tracker found for "${pointer.name}". Use /handoff to capture progress before context is lost.`);
   }
 } else {
-  respond(`Context is about to be compacted — earlier conversation details will be lost.\n\nIf this session produced decisions or progress worth keeping:\n  /braindump [name] — capture discussion and reasoning\n  /handoff [name]   — capture workstream state and next steps\n\nFiles in shared-context/ will persist. Conversation details won't.`);
+  respond(`Context is about to be compacted — earlier conversation details will be lost.\n\nIf this session produced decisions or progress worth keeping:\n  /braindump [name] — capture discussion and reasoning\n  /handoff [name]   — capture workstream state and next steps\n\nFiles in workspace-context/ will persist. Conversation details won't.`);
 }

package/template/.claude/hooks/repo-write-detection.mjs

@@ -94,9 +94,9 @@ if (toolName === 'Bash') {
   }
 }
 
-// Check if this write targets repos/, shared-context/, work-sessions/, or template files
+// Check if this write targets repos/, workspace-context/, work-sessions/, or template files
 const isRepoWrite = /(?:^|[\s/])repos\//.test(paths) || paths.includes('work-sessions/');
-const isContextWrite = paths.includes('shared-context/') && !basename(filePathArg).startsWith('local-only-');
+const isContextWrite = paths.includes('workspace-context/') && !basename(filePathArg).startsWith('local-only-');
 const isTemplateWrite = paths.includes('.claude/') && !paths.includes(scratchpadName);
 
 if (isRepoWrite || isContextWrite || isTemplateWrite) {

package/template/.claude/hooks/session-start.mjs

@@ -22,7 +22,8 @@ const input = await readStdin();
 const config = readJSON(join(root, 'workspace.json'));
 
 const chatId = input.session_id || null;
-const contextDir = join(root, 'shared-context');
+const contextDir = join(root, 'workspace-context');
+const sharedDir = join(contextDir, 'shared');
 const reposDir = join(root, 'repos');
 const lines = [];
 
@@ -113,8 +114,11 @@ if (trackers.length > 0) {
   lines.push('Use /start-work to resume a session or start new work.');
 }
 
-// Surface shared context (secondary)
-if (existsSync(contextDir)) {
+// Surface team-shared workspace context (secondary)
+// Only scan shared/ — locked/ is now a sub-dir of shared/ and is included
+// naturally. team-member/ is per-user (loaded via CLAUDE.local.md).
+// release-notes/ is operational, not knowledge.
+if (existsSync(sharedDir)) {
   const entries = [];
 
   function scanDir(dir, depth = 0) {
@@ -123,11 +127,10 @@ if (existsSync(contextDir)) {
       const fullPath = join(dir, entry);
       const stat = statSync(fullPath);
       if (stat.isDirectory()) {
-        if (entry === 'locked' || entry === '.keep') continue;
+        if (entry === '.keep') continue;
         scanDir(fullPath, depth + 1);
       } else if (entry.endsWith('.md') && entry !== '.keep' && !entry.startsWith('local-only-')) {
         const relPath = relative(contextDir, fullPath);
-        if (relPath.startsWith('locked/')) continue;
         const content = readFileSync(fullPath, 'utf-8');
         const topicMatch = content.match(/^topic:\s*(.+)$/m);
         const lifecycleMatch = content.match(/^lifecycle:\s*(.+)$/m);
@@ -139,10 +142,10 @@ if (existsSync(contextDir)) {
     }
   }
 
-  scanDir(contextDir);
+  scanDir(sharedDir);
   if (entries.length > 0) {
     lines.push('');
-    lines.push('Shared context:');
+    lines.push('Workspace context:');
     lines.push(...entries);
   }
 }

package/template/.claude/hooks/subagent-start.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-// SubagentStart hook — inject shared-context/locked/ into subagent context
+// SubagentStart hook — inject workspace-context/shared/locked/ into subagent context
 import { readdirSync, readFileSync, existsSync } from 'fs';
 import { join, basename } from 'path';
 import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
 
 const root = getWorkspaceRoot(import.meta.url);
 const config = readJSON(join(root, 'workspace.json'));
-const lockedDir = join(root, 'shared-context', 'locked');
+const lockedDir = join(root, 'workspace-context', 'shared', 'locked');
 
 const maxBytes = config?.workspace?.subagentContextMaxBytes || 10240;
 
@@ -38,7 +38,7 @@ if (Buffer.byteLength(context) > maxBytes) {
     return `- ${basename(f, '.md')}: ${firstLine}`;
   }).join('\n');
 
-  context = `[Locked shared context exceeds ${maxBytes} byte limit (${Buffer.byteLength(context)} bytes). Summary of ${files.length} files:]\n${summary}\n[Read individual files from shared-context/locked/ if you need full content.]`;
+  context = `[Locked shared context exceeds ${maxBytes} byte limit (${Buffer.byteLength(context)} bytes). Summary of ${files.length} files:]\n${summary}\n[Read individual files from workspace-context/shared/locked/ if you need full content.]`;
 }
 
 respond(context);

package/template/.claude/hooks/version-freshness-check.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// SessionStart hook — refresh the template freshness banner if cache is stale.
+// Gated on workspace.versionCheck.ambient (default true; will flip to false at v1.0).
+// Always silent: surfaces only via the local-only-template-freshness.md banner,
+// which CLAUDE.md includes via @ syntax. Never blocks session start.
+import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
+import { refreshIfStale } from '../lib/freshness.mjs';
+
+const TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+const root = getWorkspaceRoot(import.meta.url);
+const config = readJSON(`${root}/workspace.json`);
+
+// Default lifecycle: ambient=true during beta, missing-block fallback flips
+// to false at v1.0 by editing this default.
+const AMBIENT_DEFAULT = true;
+const ambient = config?.workspace?.versionCheck?.ambient ?? AMBIENT_DEFAULT;
+
+if (!ambient) {
+  respond();
+  process.exit(0);
+}
+
+try {
+  await refreshIfStale({ workspaceRoot: root, ttlMs: TTL_MS });
+} catch {
+  // Hooks must never block session start. The banner reflects last-known
+  // state; the user sees stale but never broken.
+}
+respond();

package/template/.claude/lib/freshness.mjs

@@ -0,0 +1,75 @@
+import './require-node.mjs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { compareVersions, getLatestVersion, readCache, writeCache } from './registry-check.mjs';
+
+const BANNER_FILENAME = 'local-only-template-freshness.md';
+const CACHE_FILENAME = '.version-check.json';
+
+/**
+ * Refresh the version cache if stale, then write or delete the banner file
+ * based on a comparison of workspace.templateVersion to the latest npm version.
+ *
+ * Returns:
+ *   { status: 'outdated', current, latest, checkedAt }
+ *   { status: 'current',  current, latest, checkedAt }
+ *   { status: 'unknown',  current, latest: null, checkedAt: null }
+ *   { skipped: 'uninitialized' }
+ *
+ * Pure I/O is parameterized via fetchFn / nowFn for testability.
+ */
+export async function refreshIfStale({
+  workspaceRoot,
+  ttlMs,
+  fetchFn = fetch,
+  nowFn = () => new Date(),
+}) {
+  const wsConfigPath = join(workspaceRoot, 'workspace.json');
+  let wsConfig;
+  try {
+    wsConfig = JSON.parse(readFileSync(wsConfigPath, 'utf-8'));
+  } catch {
+    return { skipped: 'no-workspace-json' };
+  }
+  const current = wsConfig?.workspace?.templateVersion;
+  if (!current || current === '0.0.0') {
+    return { skipped: 'uninitialized' };
+  }
+
+  const scratchpadDir = wsConfig?.workspace?.scratchpadDir || 'workspace-scratchpad';
+  const cachePath = join(workspaceRoot, scratchpadDir, CACHE_FILENAME);
+  const bannerPath = join(workspaceRoot, BANNER_FILENAME);
+
+  let cache = readCache(cachePath);
+  const now = nowFn();
+  const cacheAgeMs = cache?.checkedAt ? now.getTime() - new Date(cache.checkedAt).getTime() : Infinity;
+  const stale = cacheAgeMs > ttlMs;
+
+  if (stale) {
+    const fresh = await getLatestVersion({ fetchFn });
+    if (fresh.version) {
+      cache = { latestVersion: fresh.version, checkedAt: now.toISOString() };
+      writeCache(cachePath, cache);
+    }
+    // On fetch error, keep whatever cache we already had (could be null).
+  }
+
+  if (!cache) {
+    // No cache and offline (or fetch error). Leave banner alone — we have no
+    // basis to write or delete it.
+    return { status: 'unknown', current, latest: null, checkedAt: null };
+  }
+
+  const latest = cache.latestVersion;
+  const cmp = compareVersions(current, latest);
+  if (cmp < 0) {
+    writeFileSync(
+      bannerPath,
+      `## Template update available\n\nYour workspace is on template v${current}; latest on npm is v${latest}.\nRun \`/maintenance\` for details or \`npx @ulysses-ai/create-workspace --upgrade\` to apply.\n`,
+    );
+    return { status: 'outdated', current, latest, checkedAt: cache.checkedAt };
+  } else {
+    if (existsSync(bannerPath)) unlinkSync(bannerPath);
+    return { status: 'current', current, latest, checkedAt: cache.checkedAt };
+  }
+}

package/template/.claude/lib/freshness.test.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// Unit tests for freshness.mjs
+// Run: node template/.claude/lib/freshness.test.mjs
+import { refreshIfStale } from './freshness.mjs';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync, mkdirSync } 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 setupWorkspace({ templateVersion, ambientBlock = '', cache = null } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'freshness-test-'));
+  const wsConfig = {
+    workspace: {
+      name: 'test',
+      scratchpadDir: 'workspace-scratchpad',
+      templateVersion,
+      ...(ambientBlock ? { versionCheck: { ambient: ambientBlock === 'on' } } : {}),
+    },
+    repos: {},
+  };
+  writeFileSync(join(root, 'workspace.json'), JSON.stringify(wsConfig));
+  if (cache) {
+    const cacheDir = join(root, 'workspace-scratchpad');
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(join(cacheDir, '.version-check.json'), JSON.stringify(cache));
+  }
+  return root;
+}
+
+function fakeFetchOk(version) {
+  return async () => ({ ok: true, json: async () => ({ version }) });
+}
+
+const fakeFetchErr = async () => { throw new Error('offline'); };
+
+console.log('# refreshIfStale');
+
+// Outdated workspace, fresh fetch, banner written
+{
+  const root = setupWorkspace({ templateVersion: '0.13.0' });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.status, 'outdated', 'outdated status');
+  assertEq(result.current, '0.13.0', 'current version reported');
+  assertEq(result.latest, '0.14.0', 'latest version reported');
+  assertEq(existsSync(join(root, 'local-only-template-freshness.md')), true, 'banner file created');
+  const banner = readFileSync(join(root, 'local-only-template-freshness.md'), 'utf-8');
+  assertEq(banner.includes('v0.13.0'), true, 'banner mentions current');
+  assertEq(banner.includes('v0.14.0'), true, 'banner mentions latest');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Up-to-date workspace, banner deleted if present
+{
+  const root = setupWorkspace({ templateVersion: '0.14.0' });
+  // Pre-existing banner from when it was outdated
+  writeFileSync(join(root, 'local-only-template-freshness.md'), '## stale banner');
+  await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(existsSync(join(root, 'local-only-template-freshness.md')), false, 'banner deleted when current');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Fresh cache, no fetch happens
+{
+  const root = setupWorkspace({
+    templateVersion: '0.13.0',
+    cache: { latestVersion: '0.14.0', checkedAt: '2026-04-24T20:00:00Z' },
+  });
+  let fetchCalled = false;
+  await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: async () => { fetchCalled = true; return { ok: true, json: async () => ({ version: '0.14.0' }) }; },
+    nowFn: () => new Date('2026-04-24T21:00:00Z'), // 1h after cache
+  });
+  assertEq(fetchCalled, false, 'fresh cache skips fetch');
+  assertEq(existsSync(join(root, 'local-only-template-freshness.md')), true, 'banner still written from cache');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Stale cache triggers fetch
+{
+  const root = setupWorkspace({
+    templateVersion: '0.13.0',
+    cache: { latestVersion: '0.13.5', checkedAt: '2026-04-20T20:00:00Z' },
+  });
+  let fetchCalled = false;
+  await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: async () => { fetchCalled = true; return { ok: true, json: async () => ({ version: '0.14.0' }) }; },
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(fetchCalled, true, 'stale cache triggers fetch');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Stale cache + offline: keep cached value, return unknown only if no cache
+{
+  const root = setupWorkspace({
+    templateVersion: '0.13.0',
+    cache: { latestVersion: '0.13.9', checkedAt: '2026-04-20T20:00:00Z' },
+  });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchErr,
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.status, 'outdated', 'falls back to cached value when offline');
+  assertEq(result.latest, '0.13.9', 'cached value used');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// No cache + offline: status unknown
+{
+  const root = setupWorkspace({ templateVersion: '0.13.0' });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchErr,
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.status, 'unknown', 'unknown when no cache and offline');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Uninitialized workspace (templateVersion missing)
+{
+  const root = mkdtempSync(join(tmpdir(), 'freshness-test-'));
+  writeFileSync(join(root, 'workspace.json'), JSON.stringify({ workspace: {}, repos: {} }));
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.skipped, 'uninitialized', 'uninitialized workspace skipped');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// templateVersion 0.0.0 treated as uninitialized
+{
+  const root = setupWorkspace({ templateVersion: '0.0.0' });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.skipped, 'uninitialized', '0.0.0 treated as uninitialized');
+  rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/template/.claude/lib/registry-check.mjs

@@ -0,0 +1,106 @@
+import './require-node.mjs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+/**
+ * SemVer 2.0 comparison limited to the formats this scaffolder publishes:
+ * `x.y.z` and `x.y.z-prerelease.N`. Returns -1, 0, or 1.
+ *
+ * Rules:
+ *   - Compare major, minor, patch numerically.
+ *   - A pre-release version is older than the same x.y.z without a tag.
+ *   - Pre-release identifiers compare per-identifier; numeric identifiers
+ *     compare numerically (so `beta.10 > beta.2`), non-numeric lexically.
+ */
+export function compareVersions(a, b) {
+  if (a === b) return 0;
+  const [aBase, aPre] = a.split('-', 2);
+  const [bBase, bPre] = b.split('-', 2);
+  const aParts = aBase.split('.').map(Number);
+  const bParts = bBase.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((aParts[i] || 0) < (bParts[i] || 0)) return -1;
+    if ((aParts[i] || 0) > (bParts[i] || 0)) return 1;
+  }
+  if (!aPre && !bPre) return 0;
+  if (!aPre && bPre)  return 1;
+  if (aPre && !bPre)  return -1;
+  const aIds = aPre.split('.');
+  const bIds = bPre.split('.');
+  const len = Math.max(aIds.length, bIds.length);
+  for (let i = 0; i < len; i++) {
+    const ai = aIds[i];
+    const bi = bIds[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    const aNum = /^\d+$/.test(ai);
+    const bNum = /^\d+$/.test(bi);
+    if (aNum && bNum) {
+      const an = Number(ai), bn = Number(bi);
+      if (an < bn) return -1;
+      if (an > bn) return 1;
+    } else if (aNum && !bNum) {
+      return -1;
+    } else if (!aNum && bNum) {
+      return 1;
+    } else {
+      if (ai < bi) return -1;
+      if (ai > bi) return 1;
+    }
+  }
+  return 0;
+}
+
+const REGISTRY_URL = 'https://registry.npmjs.org/@ulysses-ai/create-workspace/latest';
+const DEFAULT_TIMEOUT_MS = 3000;
+
+/**
+ * Fetch the latest version of the scaffolder from the npm registry.
+ * Returns { version, error } — exactly one of them is non-null.
+ *
+ * Caller injects fetchFn for testing. Default uses global fetch (Node 18+).
+ */
+export async function getLatestVersion({ fetchFn = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) {
+      return { version: null, error: `registry returned ${res.status} ${res.statusText || ''}`.trim() };
+    }
+    const body = await res.json();
+    if (typeof body?.version !== 'string') {
+      return { version: null, error: 'registry response missing version field' };
+    }
+    return { version: body.version, error: null };
+  } catch (err) {
+    return { version: null, error: err?.message || String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Read the version cache file. Returns the parsed object if it has a string
+ * `latestVersion` field; otherwise null. Treats missing file, malformed JSON,
+ * and shape mismatches all as "no cache".
+ */
+export function readCache(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf-8'));
+    if (typeof data?.latestVersion !== 'string') return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the version cache file, creating parent directories as needed.
+ */
+export function writeCache(path, data) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}

package/template/.claude/lib/registry-check.test.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// Unit tests for registry-check.mjs
+// Run: node template/.claude/lib/registry-check.test.mjs
+import { compareVersions } from './registry-check.mjs';
+
+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}`);
+  }
+}
+
+console.log('# compareVersions');
+assertEq(compareVersions('0.13.0', '0.14.0'),               -1, 'older minor');
+assertEq(compareVersions('0.14.0', '0.13.0'),                1, 'newer minor');
+assertEq(compareVersions('0.13.0', '0.13.0'),                0, 'equal');
+assertEq(compareVersions('1.0.0',  '0.99.99'),               1, 'newer major');
+assertEq(compareVersions('0.14.0-beta.1', '0.14.0'),        -1, 'prerelease < release');
+assertEq(compareVersions('0.14.0', '0.14.0-beta.1'),         1, 'release > prerelease');
+assertEq(compareVersions('0.14.0-beta.1', '0.14.0-beta.2'), -1, 'prerelease numeric ordering');
+assertEq(compareVersions('0.14.0-beta.10', '0.14.0-beta.2'), 1, 'prerelease numeric not lexical');
+assertEq(compareVersions('0.14.0-beta.5', '0.14.0-beta.5'),  0, 'equal prerelease');
+assertEq(compareVersions('0.14.0-alpha.1', '0.14.0-beta.1'),-1, 'alpha < beta lexical');
+
+import { getLatestVersion } from './registry-check.mjs';
+
+console.log('\n# getLatestVersion');
+
+// Helper: build a fake fetch
+function fakeFetch(response) {
+  return async () => response;
+}
+
+// Success path
+{
+  const fakeOk = fakeFetch({
+    ok: true,
+    json: async () => ({ version: '0.14.0', name: '@ulysses-ai/create-workspace' }),
+  });
+  const result = await getLatestVersion({ fetchFn: fakeOk });
+  assertEq(result, { version: '0.14.0', error: null }, 'success returns version');
+}
+
+// Non-2xx response
+{
+  const fake404 = fakeFetch({ ok: false, status: 404, statusText: 'Not Found' });
+  const result = await getLatestVersion({ fetchFn: fake404 });
+  assertEq(result.version, null, 'non-2xx version is null');
+  assertEq(typeof result.error, 'string', 'non-2xx returns error string');
+}
+
+// Malformed body (no version field)
+{
+  const fakeBad = fakeFetch({ ok: true, json: async () => ({ name: 'foo' }) });
+  const result = await getLatestVersion({ fetchFn: fakeBad });
+  assertEq(result.version, null, 'missing version field is null');
+  assertEq(typeof result.error, 'string', 'missing version returns error');
+}
+
+// Network error (fetch throws)
+{
+  const fakeThrow = async () => { throw new Error('ECONNREFUSED'); };
+  const result = await getLatestVersion({ fetchFn: fakeThrow });
+  assertEq(result.version, null, 'thrown error returns null version');
+  assertEq(result.error.includes('ECONNREFUSED'), true, 'thrown error message preserved');
+}
+
+import { readCache, writeCache } from './registry-check.mjs';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+console.log('\n# readCache / writeCache');
+
+function withTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'reg-cache-test-'));
+  try { fn(dir); } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+// readCache: missing file returns null
+withTempDir((dir) => {
+  const result = readCache(join(dir, 'missing.json'));
+  assertEq(result, null, 'missing file returns null');
+});
+
+// readCache: malformed JSON returns null
+withTempDir((dir) => {
+  const path = join(dir, 'bad.json');
+  writeFileSync(path, '{not json');
+  const result = readCache(path);
+  assertEq(result, null, 'malformed JSON returns null');
+});
+
+// readCache: valid file returns parsed object
+withTempDir((dir) => {
+  const path = join(dir, 'good.json');
+  writeFileSync(path, JSON.stringify({ latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' }));
+  const result = readCache(path);
+  assertEq(result, { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' }, 'valid file parsed');
+});
+
+// readCache: missing required fields returns null
+withTempDir((dir) => {
+  const path = join(dir, 'partial.json');
+  writeFileSync(path, JSON.stringify({ checkedAt: '2026-04-24T21:00:00Z' }));
+  const result = readCache(path);
+  assertEq(result, null, 'missing latestVersion returns null');
+});
+
+// writeCache + readCache round-trip
+withTempDir((dir) => {
+  const path = join(dir, 'rt.json');
+  writeCache(path, { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' });
+  assertEq(readCache(path), { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' }, 'round-trip equal');
+});
+
+// writeCache creates parent dir if missing
+withTempDir((dir) => {
+  const path = join(dir, 'nested', 'deep', 'cache.json');
+  writeCache(path, { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' });
+  assertEq(readCache(path)?.latestVersion, '0.14.0', 'parent dir created');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);