contextdevkit 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ this project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- **Legacy-install migration (rename follow-through).** `install.mjs` now carries
+  an old `vibekit/` install forward to `contextkit/` automatically on `npx
+  contextdevkit --update` (and via an explicit `node install.mjs --migrate
+  [--dry-run]`). New `tools/install/migrate.mjs`: atomically MOVES the folder
+  (preserving memory/ADRs, config + level, pipeline tasks, `.env`), rewrites the
+  rename tokens in `settings.json` (killing the duplicate-hook trap),
+  `.gitignore`, `.gitattributes`, git-hook wrappers, `contextkit/.env`, and
+  `CLAUDE.md` (the last two backed up to `*.bak`), and deletes the stale
+  `/vibe-*` + `setupvibedevkit` command files. Refuses (no-op + warning) when
+  BOTH folders exist; idempotent; never throws into the installer (rule 2). New
+  `tools/integration-test-migrate.mjs` (25 asserts) wired into `test` +
+  `prepublishOnly`.
 - **agent-forge squad — Fase 6: declarative pipeline DSL + dry-run engine
   (ADR-0015 Part A).** The forge's orchestration is now a diffable, simulate-
   impact-mappable plan. New `templates/contextkit/squads/agent-forge/pipeline.yaml`

package/install.mjs

@@ -29,6 +29,7 @@ import { ensureDir, read, writeIfMissing, overwrite, copyTree, copyTreeIfMissing
 import { detectStack, requireBasename, looksGreenfield } from './tools/install/project.mjs';
 import { installGitHooks, patchGitignore, patchGitattributes } from './tools/install/git.mjs';
 import { uninstall } from './tools/install/uninstall.mjs';
+import { migrateLegacy } from './tools/install/migrate.mjs';
 import { isValidLevel } from './templates/contextkit/runtime/config/levels.mjs';
 import { parseArgs, HELP, prompt, LEVEL_LABELS } from './tools/install/cli.mjs';
 
@@ -63,6 +64,18 @@ async function main() {
     return;
   }
 
+  // Standalone migration: carry a legacy vibekit/ install forward, then stop.
+  if (args.migrate) {
+    const { report } = await migrateLegacy(target, { dryRun: args.dryRun });
+    console.log(report.length ? '\n' + report.join('\n') + '\n' : '\nℹ️  no legacy vibekit/ install found — nothing to migrate.\n');
+    return;
+  }
+
+  // Auto-migration: before ANYTHING reads contextkit/ (config, settings), carry a
+  // legacy vibekit/ install forward so `npx contextdevkit --update` just works.
+  const migration = await migrateLegacy(target, { dryRun: false });
+  if (migration.report.length) console.log('\n' + migration.report.join('\n') + '\n');
+
   const interactive = !args.yes && process.stdout.isTTY;
   let level = Number.isInteger(args.level) ? args.level : undefined;
   let name = args.name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextdevkit",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Portable, level-based AI-assisted development platform for Claude Code — hooks, slash commands, sub-agents, and durable project memory for any stack.",
   "type": "module",
   "bin": {
@@ -9,8 +9,8 @@
   "scripts": {
     "install:here": "node install.mjs --target .",
     "check": "node tools/selfcheck.mjs",
-    "test": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs",
-    "prepublishOnly": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs"
+    "test": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs && node tools/integration-test-migrate.mjs",
+    "prepublishOnly": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs && node tools/integration-test-migrate.mjs"
   },
   "files": [
     "install.mjs",

package/tools/install/cli.mjs

@@ -5,11 +5,13 @@
 export { LEVEL_LABELS } from '../../templates/contextkit/runtime/config/levels.mjs';
 
 export function parseArgs(argv) {
-  const args = { yes: false, rewire: false, force: false, uninstall: false, help: false, version: false, purge: false, update: false };
+  const args = { yes: false, rewire: false, force: false, uninstall: false, help: false, version: false, purge: false, update: false, migrate: false, dryRun: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--yes' || a === '-y') args.yes = true;
     else if (a === '--update') { args.update = true; args.yes = true; }
+    else if (a === '--migrate') args.migrate = true;
+    else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--rewire') args.rewire = true;
     else if (a === '--force') args.force = true;
     else if (a === '--uninstall') args.uninstall = true;
@@ -33,6 +35,8 @@ Usage:
                    [--mode greenfield|existing] [--yes] [--force]
   node install.mjs --update                   safe update: refresh engine + commands,
                                               keep your level/config/memory/CLAUDE.md
+  node install.mjs --migrate [--dry-run]      carry a legacy vibekit/ install forward
+                                              to contextkit/ (preview with --dry-run)
   node install.mjs --rewire --level <1-7>     only recompose .claude/settings.json
   node install.mjs --uninstall [--purge]      unwire hooks (--purge also removes engine)
   node install.mjs --help | --version
@@ -47,6 +51,9 @@ Flags:
   --force           overwrite CLAUDE.md / memory seeds if they exist
   --update          safe update: refresh engine/commands/agents + re-wire hooks for
                     the CURRENT level; never touches CLAUDE.md, config, or memory
+  --migrate         carry a legacy vibekit/ install forward to contextkit/ (moves the
+                    folder, preserves memory/config, rewires settings/CLAUDE.md/hooks)
+  --dry-run         with --migrate: report what would change without writing
   --rewire          only recompose settings.json for the given --level
   --uninstall       remove ContextDevKit hook wiring + git hooks (keeps memory)
   --purge           with --uninstall, also delete contextkit/ engine + commands/agents

package/tools/install/migrate.mjs

@@ -0,0 +1,162 @@
+/**
+ * Legacy-install migration: VibeDevKit (`vibekit/`) → ContextDevKit (`contextkit/`).
+ *
+ * Existing users installed the old `vibedevkit` package, which laid down a
+ * `vibekit/` platform folder, `/vibe-*` slash commands, `vibekit/...` hook
+ * wiring and `VibeDevKit` / `VIBE_*` references. After the rename, running
+ * `npx contextdevkit --update` must carry that install FORWARD — without data
+ * loss and without leaving two installs side by side.
+ *
+ * Strategy (idempotent, refuse-on-ambiguity — constitution rule 8):
+ *   1. detect a legacy `vibekit/` with no `contextkit/`;
+ *   2. MOVE the folder (atomic rename → preserves memory / config / pipeline / .env);
+ *   3. rewrite the rename tokens in the control files (settings.json, .gitignore,
+ *      .gitattributes, git hooks, contextkit/.env, CLAUDE.md — the last two backed
+ *      up to `*.bak` first, as they hold user content);
+ *   4. delete the stale `/vibe-*` + `setupvibedevkit` command files.
+ * The normal installer flow then refreshes the engine into `contextkit/`.
+ *
+ * Zero third-party deps (runs via `npx` on a bare machine). Rule 2: it never
+ * throws into the installer — all I/O is defensive; a failure degrades to a
+ * warning and leaves the project untouched.
+ */
+import { rename, cp, rm, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const LEGACY_DIR = 'vibekit';
+const NEW_DIR = 'contextkit';
+
+// Order matters: longest / most-specific tokens first so no rule eats another.
+const TOKENS = [
+  ['VibeDevKit', 'ContextDevKit'],
+  ['VIBEDEVKIT', 'CONTEXTDEVKIT'],
+  ['vibedevkit', 'contextdevkit'],
+  ['vibekit', 'contextkit'],
+  ['VIBE_', 'CONTEXT_'],
+  ['vibe-', 'context-'],
+];
+
+/** Control files whose kit-managed content carries old tokens. `backup` files hold user content. */
+const CONTROL = [
+  { rel: '.claude/settings.json', backup: false },
+  { rel: '.gitignore', backup: false },
+  { rel: '.gitattributes', backup: false },
+  { rel: 'CLAUDE.md', backup: true },
+  { rel: join(NEW_DIR, '.env'), backup: true }, // after the move
+];
+const GIT_HOOKS = ['pre-commit', 'commit-msg', 'pre-push'];
+const STALE_COMMANDS = [
+  '.claude/commands/vibe-stats.md',
+  '.claude/commands/setup/vibe-config.md',
+  '.claude/commands/setup/vibe-doctor.md',
+  '.claude/commands/setup/vibe-level.md',
+  '.claude/commands/setup/setupvibedevkit.md',
+];
+
+function rewriteTokens(text) {
+  let out = text;
+  for (const [from, to] of TOKENS) out = out.split(from).join(to);
+  return out;
+}
+
+/**
+ * Detects whether `target` holds a legacy install and whether the new folder
+ * already exists. A legacy install is a `vibekit/` with a config or runtime.
+ */
+export function detectLegacy(target) {
+  const legacy = join(target, LEGACY_DIR);
+  const isLegacy = existsSync(legacy) && (existsSync(join(legacy, 'config.json')) || existsSync(join(legacy, 'runtime')));
+  return { isLegacy, hasNew: existsSync(join(target, NEW_DIR)) };
+}
+
+async function rewriteFile(path, { backup, dryRun }) {
+  if (!existsSync(path)) return false;
+  let text;
+  try {
+    text = await readFile(path, 'utf-8');
+  } catch {
+    return false;
+  }
+  const next = rewriteTokens(text);
+  if (next === text) return false;
+  if (dryRun) return true;
+  if (backup && !existsSync(`${path}.bak`)) await writeFile(`${path}.bak`, text, 'utf-8').catch(() => {});
+  await writeFile(path, next, 'utf-8').catch(() => {});
+  return true;
+}
+
+async function moveFolder(from, to) {
+  try {
+    await rename(from, to);
+  } catch (err) {
+    if (err && err.code === 'EXDEV') {
+      // Cross-device (e.g. target on another volume): copy then remove.
+      await cp(from, to, { recursive: true, force: true });
+      await rm(from, { recursive: true, force: true });
+      return;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Runs the legacy → new migration on `target`. No-ops cleanly when there is
+ * nothing to migrate. NEVER throws — returns `{ migrated, report }`.
+ *
+ * @param {string} target project root
+ * @param {{ dryRun?: boolean }} [opts] `dryRun` reports without writing
+ * @returns {Promise<{ migrated: boolean, report: string[] }>}
+ */
+export async function migrateLegacy(target, opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const report = [];
+  let det;
+  try {
+    det = detectLegacy(target);
+  } catch {
+    return { migrated: false, report };
+  }
+  if (!det.isLegacy) return { migrated: false, report };
+
+  if (det.hasNew) {
+    report.push('⚠️  found BOTH vibekit/ (legacy) and contextkit/ — not merging automatically.');
+    report.push('    Your old data is in vibekit/. Move what you need into contextkit/, then delete vibekit/.');
+    return { migrated: false, report };
+  }
+
+  const tag = dryRun ? '[dry-run] would' : '✓';
+  report.push(dryRun ? '🔎 legacy VibeDevKit install detected (dry-run — no changes):' : '🔄 migrating legacy VibeDevKit install → ContextDevKit…');
+
+  // 1) move the folder — carries ALL user data (memory, config, pipeline, .env) forward.
+  if (!dryRun) {
+    try {
+      await moveFolder(join(target, LEGACY_DIR), join(target, NEW_DIR));
+    } catch (err) {
+      report.push(`⚠️  could not move vibekit/ → contextkit/ (${err?.code || err}); migration aborted, nothing changed.`);
+      return { migrated: false, report };
+    }
+  }
+  report.push(`  ${tag} vibekit/ → contextkit/ (memory, config, pipeline, .env preserved)`);
+
+  // 2) rewrite the control files (CLAUDE.md + .env are backed up to *.bak first).
+  for (const { rel, backup } of CONTROL) {
+    if (await rewriteFile(join(target, rel), { backup, dryRun })) report.push(`  ${tag} updated ${rel}${backup ? ' (backup *.bak)' : ''}`);
+  }
+
+  // 3) git-hook wrappers (best-effort; the installer re-installs them properly afterwards).
+  for (const hook of GIT_HOOKS) {
+    if (await rewriteFile(join(target, '.git', 'hooks', hook), { backup: false, dryRun })) report.push(`  ${tag} rewired .git/hooks/${hook}`);
+  }
+
+  // 4) delete the stale /vibe-* + setupvibedevkit command files (new ones reinstalled by the flow).
+  for (const rel of STALE_COMMANDS) {
+    const path = join(target, rel);
+    if (!existsSync(path)) continue;
+    if (!dryRun) await rm(path, { force: true }).catch(() => {});
+    report.push(`  ${tag} removed stale ${rel}`);
+  }
+
+  report.push(dryRun ? '🔎 dry-run complete — re-run without --dry-run to apply.' : '✅ migration complete — continuing with the engine refresh…');
+  return { migrated: !dryRun, report };
+}

package/tools/integration-test-migrate.mjs

@@ -0,0 +1,151 @@
+/**
+ * Integration test — legacy `vibekit/` → `contextkit/` migration (the rename).
+ *
+ * Scaffolds a throwaway project that looks like an OLD `vibedevkit` install,
+ * then drives the real installer to prove the migration:
+ *   - `--migrate --dry-run` changes nothing;
+ *   - `--migrate` moves the folder (preserving user memory/config/.env), rewrites
+ *     settings.json / CLAUDE.md / .gitignore / git hooks, backs up user files,
+ *     and deletes the stale /vibe-* commands;
+ *   - `--update` auto-migrates end-to-end and refreshes the engine (no dup hooks);
+ *   - BOTH folders present → refuse (no changes);
+ *   - re-running on a migrated project is a no-op.
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { KIT, node, run, git, reporter } from './it-helpers.mjs';
+
+const rep = reporter();
+const read = (p) => readFileSync(p, 'utf-8');
+const tmp = () => mkdtempSync(join(tmpdir(), 'contextkit-mig-'));
+
+/** Scaffolds a project that looks like a legacy VibeDevKit install. */
+function makeLegacy(proj, { withGit = false } = {}) {
+  if (withGit) {
+    git(['init', '-b', 'main'], proj);
+    git(['config', 'user.email', 'it@example.com'], proj);
+    git(['config', 'user.name', 'IT'], proj);
+  }
+  const w = (rel, body) => {
+    const p = join(proj, rel);
+    mkdirSync(join(p, '..'), { recursive: true });
+    writeFileSync(p, body, 'utf-8');
+  };
+  w('vibekit/config.json', JSON.stringify({ level: 5, setup: { completed: true }, ledger: {} }, null, 2));
+  w('vibekit/runtime/hooks/session-start.mjs', '// legacy dummy engine\n');
+  w('vibekit/memory/decisions/0001-user-decision.md', '# 0001 — a precious user ADR\nkeep me\n');
+  w('vibekit/.env', 'GOOGLE_AI_API_KEY=secret\nVIBE_GIT_TIMEOUT_MS=5000\n');
+  w('.claude/settings.json', JSON.stringify({
+    hooks: { SessionStart: [{ hooks: [{ type: 'command', command: 'node vibekit/runtime/hooks/session-start.mjs' }] }] } },
+    null, 2));
+  w('.claude/commands/setup/vibe-level.md', 'old vibe-level command\n');
+  w('.claude/commands/vibe-stats.md', 'old vibe-stats command\n');
+  w('CLAUDE.md', 'This project uses VibeDevKit. Engine in vibekit/runtime. Run /vibe-level to change level.\n');
+  w('.gitignore', '# VibeDevKit — local runtime state (do not commit)\nvibekit/memory/tech-debt-findings.json\n');
+}
+
+// ── Scenario A: dry-run changes nothing ──────────────────────────────────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj);
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate', '--dry-run']);
+    out.status === 0 ? rep.ok('--migrate --dry-run exits 0') : rep.bad(`dry-run status ${out.status}: ${out.stderr}`);
+    existsSync(join(proj, 'vibekit')) && !existsSync(join(proj, 'contextkit'))
+      ? rep.ok('dry-run left vibekit/ in place and created no contextkit/')
+      : rep.bad('dry-run mutated the filesystem');
+    read(join(proj, 'CLAUDE.md')).includes('vibekit/') ? rep.ok('dry-run left CLAUDE.md untouched') : rep.bad('dry-run rewrote CLAUDE.md');
+    /dry-run/i.test(out.stdout) ? rep.ok('dry-run output flags itself') : rep.bad('dry-run output missing the marker');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario B: real migration preserves data + rewrites references ──────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj);
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    out.status === 0 ? rep.ok('--migrate exits 0') : rep.bad(`--migrate status ${out.status}: ${out.stderr}`);
+
+    !existsSync(join(proj, 'vibekit')) ? rep.ok('vibekit/ is gone') : rep.bad('vibekit/ still present');
+    existsSync(join(proj, 'contextkit')) ? rep.ok('contextkit/ exists') : rep.bad('contextkit/ missing');
+
+    // user data preserved
+    const adr = join(proj, 'contextkit', 'memory', 'decisions', '0001-user-decision.md');
+    existsSync(adr) && read(adr).includes('precious user ADR') ? rep.ok('user ADR preserved through the move') : rep.bad('user ADR lost');
+    try {
+      JSON.parse(read(join(proj, 'contextkit', 'config.json'))).level === 5 ? rep.ok('config level 5 preserved') : rep.bad('config level changed');
+    } catch { rep.bad('config.json unreadable after migration'); }
+
+    // .env migrated + backed up
+    const env = read(join(proj, 'contextkit', '.env'));
+    env.includes('CONTEXT_GIT_TIMEOUT_MS') && !env.includes('VIBE_') ? rep.ok('.env VIBE_* → CONTEXT_*') : rep.bad('.env env-var not migrated');
+    existsSync(join(proj, 'contextkit', '.env.bak')) ? rep.ok('.env backed up to .env.bak') : rep.bad('.env.bak missing');
+
+    // settings.json rewired (no legacy paths, no duplicate)
+    const settings = read(join(proj, '.claude', 'settings.json'));
+    !settings.includes('vibekit/') && settings.includes('contextkit/runtime/hooks') ? rep.ok('settings.json rewired to contextkit/') : rep.bad('settings.json still references vibekit/');
+
+    // CLAUDE.md rewritten + backed up
+    const claude = read(join(proj, 'CLAUDE.md'));
+    !claude.includes('vibekit/') && claude.includes('contextkit/') && claude.includes('/context-level') && claude.includes('ContextDevKit')
+      ? rep.ok('CLAUDE.md references rewritten') : rep.bad('CLAUDE.md not fully rewritten');
+    existsSync(join(proj, 'CLAUDE.md.bak')) && read(join(proj, 'CLAUDE.md.bak')).includes('VibeDevKit')
+      ? rep.ok('CLAUDE.md backed up to .bak') : rep.bad('CLAUDE.md.bak missing/wrong');
+
+    // stale commands removed
+    !existsSync(join(proj, '.claude', 'commands', 'setup', 'vibe-level.md')) && !existsSync(join(proj, '.claude', 'commands', 'vibe-stats.md'))
+      ? rep.ok('stale /vibe-* command files removed') : rep.bad('stale command files left behind');
+
+    // .gitignore de-duplicated (now ContextDevKit)
+    read(join(proj, '.gitignore')).includes('ContextDevKit') ? rep.ok('.gitignore block rewritten') : rep.bad('.gitignore not migrated');
+
+    // idempotent: second run is a clean no-op
+    const again = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    again.status === 0 && /nothing to migrate/i.test(again.stdout) ? rep.ok('re-running --migrate is a no-op') : rep.bad('second --migrate was not a clean no-op');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario C: BOTH folders present → refuse, change nothing ────────────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj);
+    mkdirSync(join(proj, 'contextkit'), { recursive: true });
+    writeFileSync(join(proj, 'contextkit', 'config.json'), JSON.stringify({ level: 3 }), 'utf-8');
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    out.status === 0 ? rep.ok('refuse-both exits 0') : rep.bad(`refuse-both status ${out.status}`);
+    /BOTH/i.test(out.stdout) ? rep.ok('warns about BOTH installs') : rep.bad('no BOTH warning');
+    existsSync(join(proj, 'vibekit')) ? rep.ok('refuse-both left vibekit/ untouched') : rep.bad('refuse-both deleted vibekit/');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario D: --update auto-migrates AND refreshes the real engine ─────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj, { withGit: true });
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--update']);
+    out.status === 0 ? rep.ok('--update on a legacy install exits 0') : rep.bad(`--update status ${out.status}: ${out.stderr}`);
+    !existsSync(join(proj, 'vibekit')) ? rep.ok('--update migrated away vibekit/') : rep.bad('--update left vibekit/');
+    // real engine refreshed (the dummy 1-line hook is replaced by the actual script)
+    const hook = join(proj, 'contextkit', 'runtime', 'hooks', 'session-start.mjs');
+    existsSync(hook) && read(hook).length > 200 ? rep.ok('--update refreshed the real engine') : rep.bad('engine not refreshed');
+    // no duplicate hooks: exactly one SessionStart group, referencing contextkit/
+    const s = JSON.parse(read(join(proj, '.claude', 'settings.json')));
+    const ss = s.hooks?.SessionStart || [];
+    ss.length === 1 && !JSON.stringify(s).includes('vibekit/') ? rep.ok('no duplicate hooks after --update') : rep.bad(`duplicate/legacy hooks remain (SessionStart groups: ${ss.length})`);
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario E: fresh install is unaffected (no legacy → no-op) ──────────────
+(() => {
+  const proj = tmp();
+  try {
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    out.status === 0 && /nothing to migrate/i.test(out.stdout) ? rep.ok('no-legacy --migrate is a clean no-op') : rep.bad('no-legacy --migrate misbehaved');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+rep.finish('Integration (migration)');