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

package/lib/init.mjs

@@ -2,6 +2,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, readdirSync, statSync } from 'fs';
 import { join, basename } from 'path';
 import { stagePayload } from './payload.mjs';
+import { writeBaseline } from '../template/_claude/scripts/template-baseline.mjs';
 
 function ensureDir(dir) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -127,6 +128,14 @@ export async function initWorkspace(targetDir) {
     }
   }
 
+  // Record the template baseline — the sha256 of every verbatim payload file —
+  // so the first /workspace-update can tell template changes from local edits
+  // three ways (gh:183). Entries always hold the payload's content, so the
+  // components /workspace-init installs verbatim are already covered;
+  // /workspace-init refreshes the baseline after the full install anyway.
+  writeBaseline(targetDir, payloadDir, { version: toVersion });
+  console.log('  Wrote template baseline (.claude/.template-baseline.json)');
+
   console.log(`
   Workspace initialized (v${toVersion}).
 

package/lib/init.test.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Test for init.mjs (--init scaffolding)
+// Run: node lib/init.test.mjs
+//
+// --init stages the template payload, installs the bootstrap skills plus
+// hooks/scripts/lib, and must leave a template baseline behind: the sha256 of
+// every verbatim payload file, so the first /workspace-update classifies
+// three ways instead of treating every template change as a local edit
+// (gh:183).
+import { initWorkspace } from './init.mjs';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+let failed = 0;
+let passed = 0;
+function check(label, ok) {
+  if (ok) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${label}`);
+  }
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgVersion = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version;
+const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
+
+const root = mkdtempSync(join(tmpdir(), 'init-test-'));
+
+try {
+  await initWorkspace(root);
+
+  const baselinePath = join(root, '.claude', '.template-baseline.json');
+  check('baseline written at .claude/.template-baseline.json', existsSync(baselinePath));
+  const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+
+  check(`baseline records the payload version (${pkgVersion})`, baseline.templateVersion === pkgVersion);
+  check(
+    'baseline covers the bootstrap skills --init installs',
+    typeof baseline.files['.claude/skills/workspace-update/SKILL.md'] === 'string'
+      && typeof baseline.files['.claude/skills/workspace-init/SKILL.md'] === 'string',
+  );
+  check(
+    'baseline covers hooks and scripts',
+    typeof baseline.files['.claude/hooks/session-start.mjs'] === 'string'
+      && typeof baseline.files['.claude/scripts/classify-update.mjs'] === 'string',
+  );
+  check(
+    'baseline covers the standalone verbatim files',
+    typeof baseline.files['.mcp.json'] === 'string' && typeof baseline.files['.claudeignore'] === 'string',
+  );
+  check(
+    'entry hash matches the installed file byte-for-byte',
+    baseline.files['.claude/scripts/classify-update.mjs'] === sha(join(root, '.claude', 'scripts', 'classify-update.mjs')),
+  );
+  check(
+    'baseline never covers tests (the tarball ships none)',
+    Object.keys(baseline.files).every((k) => !k.endsWith('.test.mjs')),
+  );
+  check(
+    'baseline never covers machine-local files',
+    !('.claude/settings.local.json' in baseline.files) && !('.claude/.active-session.json' in baseline.files),
+  );
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}
+
+if (failed > 0) {
+  console.error(`${failed} check(s) failed, ${passed} passed`);
+  process.exit(1);
+}
+console.log(`${passed} checks passed`);

package/lib/payload.mjs

@@ -1,7 +1,13 @@
 // lib/payload.mjs
-import { existsSync, cpSync, rmSync, mkdirSync, writeFileSync, readFileSync, renameSync } from 'fs';
-import { join, dirname } from 'path';
+import {
+  existsSync, cpSync, rmSync, mkdirSync, writeFileSync, readFileSync, renameSync,
+  mkdtempSync, readdirSync,
+} from 'fs';
+import { join, dirname, resolve, sep } from 'path';
 import { fileURLToPath } from 'url';
+import { tmpdir } from 'os';
+import { spawnSync } from 'child_process';
+import { gunzipSync } from 'zlib';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE_DIR = join(__dirname, '..', 'template');
@@ -59,3 +65,165 @@ export function cleanPayload(targetDir) {
     rmSync(payloadDir, { recursive: true });
   }
 }
+
+// ---------- published-tarball reader ----------
+//
+// Baseline reconstruction (lib/upgrade.mjs) needs the template tree of an
+// OLDER published version, and the npm registry is the only place that
+// still has it. Node ships no tar module and the package takes no
+// dependencies, so what follows is a minimal reader for the tar variants
+// npm actually writes: ustar headers, PAX extended headers ('x'), and GNU
+// long names ('L'). Links and devices are skipped — the template is plain
+// files and directories.
+
+const TAR_BLOCK = 512;
+
+function tarString(buffer, offset, length) {
+  const slice = buffer.subarray(offset, offset + length);
+  const nul = slice.indexOf(0);
+  return slice.subarray(0, nul === -1 ? length : nul).toString('utf8');
+}
+
+function tarSize(header) {
+  // GNU tar sets the high bit and switches to base-256 once a size no
+  // longer fits octal; npm's tarballs stay far below that, but reading
+  // the flag is two lines and keeps the reader from truncating silently.
+  if (header[124] & 0x80) {
+    let value = 0n;
+    for (let i = 125; i < 136; i++) value = (value << 8n) | BigInt(header[i]);
+    return Number(value);
+  }
+  const s = tarString(header, 124, 12).trim();
+  return s === '' ? 0 : parseInt(s, 8);
+}
+
+function ustarName(header) {
+  const name = tarString(header, 0, 100);
+  const prefix = tarString(header, 345, 155);
+  return prefix ? `${prefix}/${name}` : name;
+}
+
+// A version that can name a real published tarball. It comes from the
+// workspace's own workspace.json, so anything that is not plain semver is
+// rejected before it reaches a URL or an npm argument.
+function isVersionString(version) {
+  return typeof version === 'string' && /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version);
+}
+
+/**
+ * Extract every entry under `prefix` (e.g. 'template/') from a gzipped
+ * tarball into `destDir`, returning the number of files written. Entries
+ * that would escape destDir are skipped — absolute paths, '..' segments,
+ * and anything the resolved destination fails to prove is inside destDir.
+ * The tarball comes from the npm registry, but the guard costs a line and
+ * tar names written on Windows can carry '\' separators, which are treated
+ * as directory separators like '/'.
+ */
+export function extractTarballEntries(tarballBytes, destDir, { prefix = '' } = {}) {
+  const tar = gunzipSync(tarballBytes);
+  const absDestDir = resolve(destDir);
+  let files = 0;
+  let pendingName = null; // set by a preceding GNU 'L' or PAX 'x' entry
+  for (let off = 0; off + TAR_BLOCK <= tar.length;) {
+    const header = tar.subarray(off, off + TAR_BLOCK);
+    if (header.every((b) => b === 0)) break; // end-of-archive marker
+    const size = tarSize(header);
+    const type = String.fromCharCode(header[156] || 0x30);
+    const dataStart = off + TAR_BLOCK;
+    const data = tar.subarray(dataStart, dataStart + size);
+    off = dataStart + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+
+    if (type === 'L') {
+      pendingName = tarString(data, 0, data.length);
+    } else if (type === 'x') {
+      // PAX records are "<length> key=value" lines; only the path override
+      // matters here.
+      const m = data.toString('utf8').match(/(?:^|\n)\d+ path=([^\n]+)/);
+      if (m) pendingName = m[1];
+    } else {
+      // Every other entry consumes or discards the pending name — an 'L'/'x'
+      // record naming a link or device must not leak onto the entry after it.
+      const raw = (pendingName !== null ? pendingName : ustarName(header)).replace(/\\/g, '/');
+      pendingName = null;
+      if (type === '5' || type === '0') {
+        if (!raw.startsWith(prefix)) continue;
+        const relParts = raw.slice(prefix.length).split('/');
+        const rel = relParts.join('/');
+        const dest = join(absDestDir, rel);
+        // Belt and braces beyond the '..' check: whatever the parts say, the
+        // resolved destination must land inside destDir.
+        const inside = rel !== '' && !relParts.includes('..')
+          && resolve(dest).startsWith(absDestDir + sep);
+        if (!inside) continue;
+        if (type === '5') {
+          mkdirSync(dest, { recursive: true });
+        } else {
+          mkdirSync(dirname(dest), { recursive: true });
+          writeFileSync(dest, data);
+          files++;
+        }
+      }
+      // Links, devices, fifos, global PAX never appear in an npm tarball of
+      // this package — skip them (their name, pending or not, is gone).
+    }
+  }
+  return files;
+}
+
+// Both network paths are bounded: a hung registry or npm must not stall an
+// upgrade indefinitely — reconstruction is best-effort and falls back to
+// asking per file on the next /workspace-update.
+const FETCH_TIMEOUT_MS = 15000;
+const NPM_PACK_TIMEOUT_MS = 30000;
+
+/**
+ * Fetch the published package tarball for `version` as bytes, or null when
+ * it cannot be fetched. The registry URL needs no subprocess and works on
+ * every platform; `npm pack` is the fallback because it honors the user's
+ * configured registry and auth.
+ */
+export async function fetchPackageTarball(version, { registry = process.env.NPM_CONFIG_REGISTRY } = {}) {
+  if (!isVersionString(version)) return null;
+  const base = (registry || 'https://registry.npmjs.org').replace(/\/+$/, '');
+  try {
+    const res = await fetch(`${base}/@ulysses-ai/create-workspace/-/create-workspace-${version}.tgz`, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (res.ok) return Buffer.from(await res.arrayBuffer());
+  } catch { /* offline, blocked host, timed out — try npm pack */ }
+  return npmPackTarball(version);
+}
+
+function npmPackTarball(version) {
+  const dest = mkdtempSync(join(tmpdir(), 'create-workspace-pack-'));
+  try {
+    const argv = [
+      'pack', `@ulysses-ai/create-workspace@${version}`, '--pack-destination', dest, '--json',
+    ];
+    // Windows resolves `npm` to npm.cmd, which spawnSync cannot execute
+    // without a shell. The args are a validated semver spec and one temp
+    // path — quoting each keeps the joined command line honest even when
+    // the temp path contains spaces. Elsewhere argv runs shell-free.
+    const isWin = process.platform === 'win32';
+    const r = isWin
+      ? spawnSync('npm.cmd', argv.map((a) => `"${a}"`), {
+        shell: true, timeout: NPM_PACK_TIMEOUT_MS, encoding: 'utf-8',
+      })
+      : spawnSync('npm', argv, { timeout: NPM_PACK_TIMEOUT_MS, encoding: 'utf-8' });
+    if (r.error || r.status !== 0) return null;
+    let name = null;
+    try {
+      const parsed = JSON.parse(r.stdout);
+      name = Array.isArray(parsed) ? parsed[0]?.filename : parsed?.filename;
+    } catch { /* older npm prints a bare filename line — take the directory listing */ }
+    const candidates = name
+      ? [join(dest, name)]
+      : readdirSync(dest).filter((f) => f.endsWith('.tgz')).map((f) => join(dest, f));
+    for (const path of candidates) {
+      if (existsSync(path)) return readFileSync(path);
+    }
+    return null;
+  } finally {
+    rmSync(dest, { recursive: true, force: true });
+  }
+}

package/lib/payload.test.mjs

@@ -6,11 +6,14 @@
 // the /workspace-update skill already installed in existing workspaces,
 // which reads .workspace-update/.claude/... and .workspace-update/.mcp.json.
 // These tests pin that layout even though template/ itself stores the
-// protected paths under the inert names _claude/ and _mcp.json.
-import { stagePayload, cleanPayload } from './payload.mjs';
-import { mkdtempSync, rmSync, existsSync } from 'fs';
+// protected paths under the inert names _claude/ and _mcp.json. The
+// published-tarball reader (baseline reconstruction's input) is covered
+// here too, against fixture tarballs built in-memory — no network.
+import { stagePayload, cleanPayload, extractTarballEntries, fetchPackageTarball } from './payload.mjs';
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import { gzipSync } from 'zlib';
 
 let failed = 0;
 let passed = 0;
@@ -48,6 +51,158 @@ try {
   rmSync(root, { recursive: true, force: true });
 }
 
+// ---- extractTarballEntries ----
+
+// Minimal ustar writer: 512-byte header + padded body, matching what npm's
+// tarballs carry for paths under 100 chars.
+function tarEntry(name, content, type = '0') {
+  const body = Buffer.from(content, 'utf8');
+  const header = Buffer.alloc(512);
+  header.write(name, 0, 100, 'utf8');
+  header.write(body.length.toString(8).padStart(11, '0') + '\0', 124, 'ascii');
+  header.write(type, 156, 'ascii');
+  header.write('ustar', 257, 'ascii');
+  header.write('00', 263, 'ascii');
+  let sum = 0;
+  for (const byte of header) sum += byte;
+  header.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 'ascii');
+  const pad = Buffer.alloc((512 - (body.length % 512)) % 512);
+  return Buffer.concat([header, body, pad]);
+}
+
+function makeTarball(entries) {
+  return gzipSync(Buffer.concat([
+    ...entries.map(([name, content, type]) => tarEntry(name, content, type)),
+    Buffer.alloc(1024),
+  ]));
+}
+
+// A GNU long-name record ('L') followed by the entry it names.
+function makeTarballWithLongName(longPath, content) {
+  const blocks = [
+    tarEntry('././@LongLink', longPath, 'L'),
+    tarEntry(longPath.slice(0, 20), content),
+    Buffer.alloc(1024),
+  ];
+  return gzipSync(Buffer.concat(blocks));
+}
+
+// A PAX extended header ('x') carrying a path override, then the entry.
+function makeTarballWithPaxPath(path, content) {
+  const record = `${path.length + 20} path=${path}\n`;
+  const blocks = [
+    tarEntry('PaxHeaders/x', record, 'x'),
+    tarEntry('short-name', content),
+    Buffer.alloc(1024),
+  ];
+  return gzipSync(Buffer.concat(blocks));
+}
+
+{
+  const dest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+  try {
+    const files = extractTarballEntries(makeTarball([
+      ['template/_claude/hooks/a.mjs', '// a\n'],
+      ['template/_claude/rules', '', '5'],
+      ['template/_mcp.json', '{"mcpServers":{}}\n'],
+      ['template/.claudeignore', 'scratch/\n'],
+      ['package/package.json', '{"version":"9.9.9"}\n'],
+      ['README.md', 'not under the prefix\n'],
+    ]), dest, { prefix: 'template/' });
+    check('extracts the three prefixed files', files === 3);
+    check('nested file content round-trips',
+      readFileSync(join(dest, '_claude', 'hooks', 'a.mjs'), 'utf8') === '// a\n');
+    check('directory entry materializes', existsSync(join(dest, '_claude', 'rules')));
+    check('entries outside the prefix are not extracted',
+      !existsSync(join(dest, '..', 'package')) && !existsSync(join(dest, 'package')));
+    check('unprefixed top-level files are not extracted', !existsSync(join(dest, 'README.md')));
+
+    // A traversal attempt inside the prefix is skipped, not written.
+    const guardDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarball([
+      ['template/../escape.txt', 'nope\n'],
+      ['template/ok.txt', 'fine\n'],
+    ]), guardDest, { prefix: 'template/' });
+    check('.. paths are refused', !existsSync(join(guardDest, '..', 'escape.txt')));
+    check('sibling of .. entry still extracted', existsSync(join(guardDest, 'ok.txt')));
+    rmSync(guardDest, { recursive: true, force: true });
+
+    // GNU long names and PAX path overrides both resolve to the real name.
+    const longPath = `template/_claude/scripts/${'very-long-name-'.repeat(8)}.mjs`;
+    const longDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarballWithLongName(longPath, '// long\n'), longDest, { prefix: 'template/' });
+    check('GNU long-name entries extract under their full path',
+      readFileSync(join(longDest, '_claude', 'scripts', `${'very-long-name-'.repeat(8)}.mjs`), 'utf8') === '// long\n');
+    rmSync(longDest, { recursive: true, force: true });
+
+    const paxDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarballWithPaxPath('template/_claude/pax.mjs', '// pax\n'), paxDest, { prefix: 'template/' });
+    check('PAX path overrides extract under the overridden path',
+      readFileSync(join(paxDest, '_claude', 'pax.mjs'), 'utf8') === '// pax\n');
+    rmSync(paxDest, { recursive: true, force: true });
+
+    // A PAX override that belongs to a NON-file entry (a symlink) dies with
+    // it: the file after the link extracts under its own header name, never
+    // under the leaked override.
+    const leakDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    const record = `${'template/_claude/leaked.mjs'.length + 20} path=template/_claude/leaked.mjs\n`;
+    extractTarballEntries(makeTarball([
+      ['PaxHeaders/x', record, 'x'],
+      ['target', 'template/elsewhere.mjs', '2'],
+      ['template/_claude/own-name.mjs', '// own\n'],
+    ]), leakDest, { prefix: 'template/' });
+    check('a PAX name followed by a non-file entry does not leak',
+      !existsSync(join(leakDest, '_claude', 'leaked.mjs'))
+      && !existsSync(join(leakDest, '_claude', 'elsewhere.mjs')));
+    check('the entry after a discarded override uses its own name',
+      readFileSync(join(leakDest, '_claude', 'own-name.mjs'), 'utf8') === '// own\n');
+    rmSync(leakDest, { recursive: true, force: true });
+
+    // Tar names written on Windows carry '\' separators — treated as
+    // directory separators like '/'.
+    const bsDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarball([
+      ['template\\_claude\\hooks\\win.mjs', '// win\n'],
+    ]), bsDest, { prefix: 'template/' });
+    check('backslash-separated entry names extract as directories',
+      readFileSync(join(bsDest, '_claude', 'hooks', 'win.mjs'), 'utf8') === '// win\n');
+    rmSync(bsDest, { recursive: true, force: true });
+  } finally {
+    rmSync(dest, { recursive: true, force: true });
+  }
+}
+
+// fetchPackageTarball rejects non-semver versions before any network or
+// npm call — a workspace.json value is user input.
+{
+  const bogus = await fetchPackageTarball('0.15.0; rm -rf /');
+  check('non-semver version fetches nothing', bogus === null);
+  const alsoBogus = await fetchPackageTarball('');
+  check('empty version fetches nothing', alsoBogus === null);
+}
+
+// The registry fetch is bounded: a hung connection must not stall an
+// upgrade indefinitely (reconstruction falls back to asking per file).
+{
+  const realFetch = globalThis.fetch;
+  const tarball = makeTarball([['package/template/.claudeignore', 'x/\n']]);
+  let seenInit = null;
+  globalThis.fetch = async (url, init) => {
+    seenInit = { url, init };
+    return { ok: true, arrayBuffer: async () => tarball };
+  };
+  try {
+    const bytes = await fetchPackageTarball('0.15.0');
+    check('registry fetch returns the tarball bytes', bytes !== null && bytes.equals(tarball));
+    check('registry fetch targets the versioned tarball URL',
+      seenInit !== null && seenInit.url.endsWith('/create-workspace-0.15.0.tgz'));
+    check('registry fetch carries an abort timeout signal',
+      seenInit !== null && seenInit.init?.signal instanceof AbortSignal);
+  } finally {
+    globalThis.fetch = realFetch;
+  }
+}
+
 if (failed > 0) {
   console.error(`${failed} check(s) failed, ${passed} passed`);
   process.exit(1);

package/lib/scaffold.mjs

@@ -1,6 +1,7 @@
 import { cpSync, mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, rmSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { writeBaseline, INERT_PAIRS } from '../template/_claude/scripts/template-baseline.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE_DIR = join(__dirname, '..', 'template');
@@ -98,5 +99,12 @@ export async function scaffold(answers) {
     }
   }
 
+  // Record the template baseline — the sha256 of every verbatim-installed
+  // file — so /workspace-update can classify three ways (workspace vs payload
+  // vs baseline) instead of treating every template change as a local edit
+  // (gh:183). The template tree carries the inert names; entries always hold
+  // the template's content, so hashes come straight from the source of truth.
+  writeBaseline(directory, TEMPLATE_DIR, { pairs: INERT_PAIRS, version: pkgJson.version });
+
   return directory;
 }

package/lib/scaffold.test.mjs

@@ -48,6 +48,26 @@ try {
   check('no _claude/ leftover', !existsSync(join(directory, '_claude')));
   check('no _mcp.json leftover', !existsSync(join(directory, '_mcp.json')));
   check('no _gitignore leftover', !existsSync(join(directory, '_gitignore')));
+
+  // Template baseline: hashes of the verbatim-installed files, for three-way
+  // update classification (gh:183)
+  const baselinePath = join(directory, '.claude', '.template-baseline.json');
+  check('template baseline written', existsSync(baselinePath));
+  const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+  const pkgVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  check(`baseline records the package version (${pkgVersion})`, baseline.templateVersion === pkgVersion);
+  check(
+    'baseline covers rules installed verbatim from the template',
+    typeof baseline.files['.claude/rules/coherent-revisions.md'] === 'string',
+  );
+  check(
+    'baseline covers .mcp.json via its inert source name',
+    typeof baseline.files['.mcp.json'] === 'string' && typeof baseline.files['.claudeignore'] === 'string',
+  );
+  check(
+    'baseline never covers tests or machine-local files',
+    Object.keys(baseline.files).every((k) => !k.endsWith('.test.mjs') && k !== '.claude/settings.local.json'),
+  );
 } finally {
   rmSync(directory, { recursive: true, force: true });
 }