@mthanh/vespercli 1.8.0 → 2.0.1

package/scripts/generate-legacy-digests.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Generate `assets/legacy/claude-1x-digests.json` — the PINNED proof of what every released
+ * Vesper 1.x build wrote into a Claude project (epic f, the 1.x migration).
+ *
+ * WHY. Vesper 2.0 removes a file it may have written only when it can PROVE the file is
+ * Vesper's (`src/cli/utils/proven-removal.js`): the file's hash equals the hash recorded when
+ * Vesper wrote it, or its bytes equal the shipped source. A 1.x project catalog carries no
+ * recorded hash (1.x kept a bare path list), and 2.0 ships a different catalog (no commands at
+ * all), so neither proof exists — the migration had to either keep every 1.x file (leaving a
+ * project-level agent that silently overrides its plugin twin) or delete without proof. This
+ * table is the missing proof: the LF-normalized sha256 of every file each 1.x RELEASE copied
+ * into a project. A file whose bytes hash to one of these is exactly what a 1.x release wrote,
+ * untouched; anything else (an edit, a hand-authored namesake) is not, and is kept.
+ *
+ * SOURCE. Read straight from git history at the release commits (never from the working
+ * tree), so the table can be regenerated and audited by anyone with the repository:
+ *   - the committed catalog `assets/claude/{agents,commands,skills}` — written into
+ *     `.claude/{agents,commands,skills}` by 1.9.0 and 1.9.1 only;
+ *   - the machine-wide plugin folder `~/.claude/skills/vesper/{agents,commands,skills}` — written
+ *     by every release 1.1.0 … 1.8.0 (`pluginFiles`), so that folder is removed FILE BY FILE
+ *     with the same proof (an edited or user-added file there is kept);
+ *   - the orchestrator playbook `assets/claude/vesper-orchestrator.md` — written into
+ *     `.claude/vesper/orchestrator.md` by every 1.x release that had a Claude target.
+ *
+ * Run: `node scripts/generate-legacy-digests.js` (from the repository root). Deterministic:
+ * keys and hash lists are sorted, so an unchanged history regenerates byte-identical output.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { writeFileSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, relative, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const OUT = join(ROOT, 'assets', 'legacy', 'claude-1x-digests.json');
+
+/** Releases that wrote the committed project catalog (`.claude/{agents,commands,skills}`). */
+export const CATALOG_RELEASES = Object.freeze([
+  { version: '1.9.0', commit: 'ae42da8' },
+  { version: '1.9.1', commit: '9f97546' },
+]);
+
+/**
+ * Releases that installed the MACHINE-WIDE plugin folder `~/.claude/skills/vesper/`
+ * (`{agents,commands,skills}` copied from `assets/claude/` + a generated
+ * `.claude-plugin/plugin.json`). 1.9.x moved the catalog into the project, so these are every
+ * earlier 1.x release. Release source history, read per release: this folder is the ONLY home
+ * location any 1.x build ever wrote.
+ */
+export const PLUGIN_RELEASES = Object.freeze(
+  ['1.1.0', '1.1.1', '1.1.2', '1.2.0', '1.2.1', '1.3.1', '1.3.2', '1.3.3', '1.4.0', '1.5.0',
+    '1.5.1', '1.6.0', '1.7.0', '1.7.1', '1.8.0'].map((v) => ({ version: v, commit: `v${v}` })),
+);
+
+/** Every 1.x release with a Claude target (each wrote `.claude/vesper/orchestrator.md`). */
+export const PLAYBOOK_RELEASES = Object.freeze([
+  ...['1.1.0', '1.1.1', '1.1.2', '1.2.0', '1.2.1', '1.3.1', '1.3.2', '1.3.3', '1.4.0', '1.5.0',
+    '1.5.1', '1.6.0', '1.7.0', '1.7.1', '1.8.0'].map((v) => ({ version: v, commit: `v${v}` })),
+  ...CATALOG_RELEASES,
+]);
+
+function git(...args) {
+  return execFileSync('git', args, { cwd: ROOT, maxBuffer: 256 * 1024 * 1024 });
+}
+
+/** LF-normalized sha256 — byte-for-byte `ownership.js#hashContent` / `proven-removal.js#lfSha256`. */
+function lfSha256(buf) {
+  const normalized = buf.toString('utf-8').replace(/\r\n/g, '\n');
+  return `sha256:${createHash('sha256').update(normalized, 'utf8').digest('hex')}`;
+}
+
+function add(map, key, hash) {
+  if (!map[key]) map[key] = new Set();
+  map[key].add(hash);
+}
+
+/** Every regular file under `root`, POSIX-relative. */
+function walk(root, dir = root, out = []) {
+  for (const name of readdirSync(dir)) {
+    const abs = join(dir, name);
+    if (statSync(abs).isDirectory()) walk(root, abs, out);
+    else out.push(relative(root, abs).split(sep).join('/'));
+  }
+  return out;
+}
+
+/**
+ * What each release's VENDORED-asset engine wrote into a project (the skill body, the Claude
+ * rule, the Copilot activation file), per target shape. The engine is a function of the release's
+ * code, not a copied file, so the release's own `src/` is checked out into a temp dir and RUN
+ * (opt-in forced, into scratch workspaces, `$HOME` sandboxed). Files the current build renders
+ * identically need no pin; a 1.x render that differs (the Copilot activation's pointer moved in
+ * 2.0) is how the migration recognises an untouched 1.x copy — and replaces it — instead of
+ * keeping it as if the user had edited it.
+ */
+async function vendoredDigests(releases) {
+  const out = {};
+  const savedHome = process.env.HOME;
+  for (const { commit } of releases) {
+    const src = git('show', `${commit}:src/cli/utils/claude-target.js`).toString('utf-8');
+    if (!/export async function ensureVendoredAssetForInit/.test(src)) continue;
+    const tmp = mkdtempSync(join(tmpdir(), 'vesper-legacy-vendored-'));
+    try {
+      execFileSync('sh', ['-c', `git archive ${commit} src assets/vendor package.json | tar -x -C "${tmp}"`], { cwd: ROOT });
+      symlinkSync(join(ROOT, 'node_modules'), join(tmp, 'node_modules'));
+      const home = join(tmp, '__home');
+      mkdirSync(home, { recursive: true });
+      process.env.HOME = home;
+      const mod = await import(pathToFileURL(join(tmp, 'src', 'cli', 'utils', 'claude-target.js')).href);
+      const optIn = join(home, 'optin.json');
+      for (const shape of [{ claude: {} }, { paths: ['x'] }, { claude: {}, paths: ['x'] }]) {
+        for (const entry of mod.VENDORED_ASSETS || []) {
+          const ws = mkdtempSync(join(tmp, 'ws-'));
+          writeFileSync(join(ws, '.vesperrc'), JSON.stringify(shape));
+          writeFileSync(optIn, JSON.stringify({ vendored: { [entry.id]: { optIn: true } }, [entry.id]: { optIn: true } }));
+          await mod.ensureVendoredAssetForInit(entry.id, ws, { userConfigPath: optIn });
+          for (const rel of walk(ws)) {
+            if (rel === '.vesperrc' || rel === 'CLAUDE.md') continue; // a record / a region, not a vendored whole file
+            add(out, rel, lfSha256(readFileSync(join(ws, rel))));
+          }
+        }
+      }
+    } finally {
+      process.env.HOME = savedHome;
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const files = {};
+  for (const { commit } of CATALOG_RELEASES) {
+    const listing = git('ls-tree', '-r', '--name-only', commit, 'assets/claude/agents', 'assets/claude/commands', 'assets/claude/skills')
+      .toString('utf-8').split('\n').filter(Boolean);
+    for (const path of listing) {
+      const rel = path.replace(/^assets\/claude\//, '');
+      // Top-level agents/commands are `.md` files only (1.x `copyCatalogDir` skipped others).
+      const [top, ...rest] = rel.split('/');
+      if ((top === 'agents' || top === 'commands') && (rest.length !== 1 || !rel.endsWith('.md'))) continue;
+      add(files, rel, lfSha256(git('show', `${commit}:${path}`)));
+    }
+  }
+  // The machine-wide plugin folder, keyed relative to `~/.claude/skills/vesper/` (e.g.
+  // `agents/code-reviewer.md`, `skills/debugging/SKILL.md`), plus the `plugin.json` description
+  // strings each release generated (the version field is the running package's, so it is free).
+  const pluginFiles = {};
+  const pluginDescriptions = new Set();
+  for (const { commit } of PLUGIN_RELEASES) {
+    const listing = git('ls-tree', '-r', '--name-only', commit, 'assets/claude/agents', 'assets/claude/commands', 'assets/claude/skills')
+      .toString('utf-8').split('\n').filter(Boolean);
+    for (const path of listing) {
+      const rel = path.replace(/^assets\/claude\//, '');
+      const [top, ...rest] = rel.split('/');
+      if ((top === 'agents' || top === 'commands') && (rest.length !== 1 || !rel.endsWith('.md'))) continue;
+      add(pluginFiles, rel, lfSha256(git('show', `${commit}:${path}`)));
+    }
+    const src = git('show', `${commit}:src/cli/utils/claude-target.js`).toString('utf-8');
+    const m = /writePluginManifest[\s\S]*?description:\s*'([^']+)'/.exec(src);
+    if (m) pluginDescriptions.add(m[1]);
+  }
+  const playbook = new Set();
+  for (const { commit } of PLAYBOOK_RELEASES) {
+    playbook.add(lfSha256(git('show', `${commit}:assets/claude/vesper-orchestrator.md`)));
+  }
+  const sortedFiles = {};
+  for (const key of Object.keys(files).sort()) sortedFiles[key] = [...files[key]].sort();
+  const sortedPlugin = {};
+  for (const key of Object.keys(pluginFiles).sort()) sortedPlugin[key] = [...pluginFiles[key]].sort();
+  const vendored = await vendoredDigests([...PLUGIN_RELEASES, ...CATALOG_RELEASES]);
+  const sortedVendored = {};
+  for (const key of Object.keys(vendored).sort()) sortedVendored[key] = [...vendored[key]].sort();
+  const out = {
+    description: 'Pinned LF-normalized sha256 digests of every file released Vesper 1.x builds copied into a Claude project. Generated by scripts/generate-legacy-digests.js from git history; never edit by hand.',
+    catalogReleases: CATALOG_RELEASES.map((r) => `${r.version} (${r.commit})`),
+    playbookReleases: PLAYBOOK_RELEASES.map((r) => `${r.version} (${r.commit})`),
+    playbook: [...playbook].sort(),
+    files: sortedFiles,
+    pluginReleases: PLUGIN_RELEASES.map((r) => `${r.version} (${r.commit})`),
+    pluginManifestDescriptions: [...pluginDescriptions].sort(),
+    pluginFiles: sortedPlugin,
+    vendoredFiles: sortedVendored,
+  };
+  mkdirSync(dirname(OUT), { recursive: true });
+  writeFileSync(OUT, `${JSON.stringify(out, null, 1)}\n`, 'utf-8');
+  process.stdout.write(`wrote ${OUT}: ${Object.keys(sortedFiles).length} catalog paths, ${playbook.size} playbook digests, ${Object.keys(sortedPlugin).length} plugin-folder paths, ${Object.keys(sortedVendored).length} vendored paths\n`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) await main();

package/scripts/generate-manifests.js

@@ -1,154 +1,33 @@
 #!/usr/bin/env node
 /**
- * Generate manifests for Vesper assets
- * 
- * 1. Global manifest.json at assets/ root - lists all available assets
- * 2. Per-skill manifest.json - lists files within each skill
- * 
- * Run: node scripts/generate-skill-manifests.js
- *      npm run manifest
+ * Regenerate `assets/manifest.json` ONLY.
+ *
+ * Vesper 2.0 (epic (d) review): the asset generator now writes this manifest itself,
+ * from the same in-memory tree it emits, so there is no longer a load-bearing run
+ * order between the two scripts. This entry point is kept for tooling that still
+ * calls it; it is idempotent and order-independent.
+ *
+ * Two things were deliberately REMOVED:
+ *   - The `generated` timestamp. In a repo worked on from parallel worktrees it made
+ *     every regeneration a guaranteed merge conflict for zero information.
+ *   - Per-skill `assets/copilot/skills/<name>/manifest.json` files. Their only reader
+ *     was `src/cli/utils/remote.js#copySkillFolder`, and `remote.js` is imported by
+ *     nothing (dead code) — recorded in the epic (d) change log for removal.
+ *
+ * Run: node scripts/generate-manifests.js
  */
 
-import { readdir, stat, writeFile } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { buildCopilotTree, serializeManifest, ASSETS_DIR } from './generate-claude-assets.js';
 
-const ASSETS_DIR = join(__dirname, '..', 'assets');
-const SKILLS_DIR = join(ASSETS_DIR, 'skills');
-
-/**
- * Recursively get all files in a directory
- * @param {string} dir - Directory to scan
- * @param {string} base - Base path for relative paths
- * @returns {Promise<string[]>} Array of relative file paths
- */
-async function getFilesRecursive(dir, base = '') {
-  const files = [];
-  const entries = await readdir(dir, { withFileTypes: true });
-  
-  for (const entry of entries) {
-    // Skip hidden files and manifest.json itself
-    if (entry.name.startsWith('.') || entry.name === 'manifest.json') {
-      continue;
-    }
-    
-    const rel = base ? join(base, entry.name) : entry.name;
-    
-    if (entry.isDirectory()) {
-      files.push(...await getFilesRecursive(join(dir, entry.name), rel));
-    } else {
-      files.push(rel);
-    }
-  }
-  
-  return files;
-}
-
-/**
- * Generate manifest for a single skill
- * @param {string} skillName - Name of the skill
- */
-async function generateSkillManifest(skillName) {
-  const skillDir = join(SKILLS_DIR, skillName);
-  const files = await getFilesRecursive(skillDir);
-  
-  const manifest = {
-    name: skillName,
-    version: '1.0.0',
-    generated: new Date().toISOString(),
-    files: files.sort()
-  };
-  
-  const manifestPath = join(skillDir, 'manifest.json');
-  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-  
-  return files.length;
-}
-
-/**
- * Get asset names from a directory
- * @param {string} dir - Directory path
- * @param {string} extension - File extension to filter (empty for folders)
- * @param {boolean} isFolder - Whether assets are folders
- * @returns {Promise<string[]>} Array of asset names
- */
-async function getAssetNames(dir, extension, isFolder = false) {
-  try {
-    const entries = await readdir(dir, { withFileTypes: true });
-    
-    if (isFolder) {
-      return entries
-        .filter(e => e.isDirectory() && !e.name.startsWith('.'))
-        .map(e => e.name)
-        .sort();
-    }
-    
-    return entries
-      .filter(e => e.isFile() && e.name.endsWith(extension))
-      .map(e => e.name.replace(extension, ''))
-      .sort();
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Generate global manifest listing all available assets
- */
-async function generateGlobalManifest() {
-  const agents = await getAssetNames(join(ASSETS_DIR, 'agents'), '.agent.md');
-  const prompts = await getAssetNames(join(ASSETS_DIR, 'prompts'), '.prompt.md');
-  const instructions = await getAssetNames(join(ASSETS_DIR, 'instructions'), '.instructions.md');
-  const skills = await getAssetNames(SKILLS_DIR, '', true);
-  
-  const manifest = {
-    version: '1.0.0',
-    generated: new Date().toISOString(),
-    description: 'Available Vesper assets. Use with: vespercli add agents|prompts|instructions|skills <name>',
-    agents,
-    prompts,
-    instructions,
-    skills
-  };
-  
-  const manifestPath = join(ASSETS_DIR, 'manifest.json');
-  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-  
-  return { agents: agents.length, prompts: prompts.length, instructions: instructions.length, skills: skills.length };
-}
-
-async function main() {
-  console.log('Generating Vesper manifests...\n');
-  
-  // 1. Generate global manifest
-  console.log('Global manifest:');
-  const counts = await generateGlobalManifest();
-  console.log(`  ✓ ${counts.agents} agents`);
-  console.log(`  ✓ ${counts.prompts} prompts`);
-  console.log(`  ✓ ${counts.instructions} instructions`);
-  console.log(`  ✓ ${counts.skills} skills`);
-  console.log(`  → assets/manifest.json\n`);
-  
-  // 2. Generate per-skill manifests
-  console.log('Skill manifests:');
-  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
-  const skills = entries.filter(e => e.isDirectory() && !e.name.startsWith('.'));
-  
-  let totalFiles = 0;
-  
-  for (const skill of skills) {
-    const count = await generateSkillManifest(skill.name);
-    console.log(`  ✓ ${skill.name}: ${count} files`);
-    totalFiles += count;
-  }
-  
-  console.log(`\nDone. ${skills.length} skill manifests with ${totalFiles} total files.`);
-}
-
-main().catch(err => {
-  console.error('Error:', err.message);
+const { manifest, errors } = await buildCopilotTree();
+if (errors.length > 0) {
+  console.error(`✗ ${errors.length} canonical-source error(s); fix them and run the generator:`);
+  for (const e of errors) console.error(`  - ${e}`);
   process.exit(1);
-});
+}
+await writeFile(join(ASSETS_DIR, 'manifest.json'), serializeManifest(manifest), 'utf-8');
+console.log(`✓ assets/manifest.json — ${manifest.agents.length} agents, ${manifest.prompts.length} prompts, `
+  + `${manifest.coreInstructions.length} core + ${manifest.instructions.length} extended instructions, ${manifest.skills.length} skills`);