nestjs-boost 0.0.0-stage → 1.2.0

package/lib/installer.mjs

@@ -0,0 +1,450 @@
+// nestjs-boost core: detect a NestJS project, choose the matching Agent Skills, and sync them
+// (plus a guidelines block) into the folders each coding agent reads.
+//
+// Safety rules, enforced here so the CLI and the postinstall hook share them:
+// - Writes only inside the project root, only to skill folders, guideline files and the lock file.
+// - Edits guideline files only between the marker comments; everything else is kept.
+// - Never overwrites or deletes a skill folder the user changed (tracked by content hash in
+//   the lock file) unless `force` is set. Customize through `.ai/skills/<name>/` instead.
+// - Never follows symbolic links: a link anywhere on a path it writes or deletes is refused, and
+//   links inside skill folders, `.ai/skills` and `.ai/guidelines` are skipped.
+// - Trusts nothing in the lock file: only skill-folder and guideline paths it could have written
+//   are honoured, so a tampered lock file can't point a delete at other project files.
+// - No network access, no child processes, no dependencies.
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENTS, AGENT_IDS, ALL_INSTRUCTION_FILES, ALL_SKILL_DIRS, DEFAULT_AGENTS, instructionFiles, planSkillDirs } from './agents.mjs';
+
+export { AGENTS, AGENT_IDS, AGENT_LIST, DEFAULT_AGENTS, planSkillDirs } from './agents.mjs';
+export const PACK_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const MANIFEST = JSON.parse(readFileSync(join(PACK_DIR, 'manifest.json'), 'utf8'));
+export const PACK_VERSION = JSON.parse(readFileSync(join(PACK_DIR, 'package.json'), 'utf8')).version;
+const START = '<!-- nestjs-boost:start -->';
+const END = '<!-- nestjs-boost:end -->';
+export const LOCK = '.ai/nestjs-boost.lock.json';
+const CONFIG_FILE = '.ai/nestjs-boost.json';
+
+export class BoostError extends Error {}
+const fail = (msg) => { throw new BoostError(msg); };
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+const toList = (v) => (Array.isArray(v) ? v : v ? String(v).split(',') : []).map((s) => String(s).trim()).filter(Boolean);
+
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+// Lock-file allowlist, derived from the agent registry: `<some agent's skills dir>/<skill name>`.
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const SKILL_PATH_RE = new RegExp(`^(${ALL_SKILL_DIRS.map(escapeRe).join('|')})/[a-z0-9]+(-[a-z0-9]+)*$`);
+const GUIDELINE_FILES = new Set(ALL_INSTRUCTION_FILES);
+const lstat = (p) => { try { return lstatSync(p); } catch { return null; } };
+
+// Returns the first symbolic link (or Windows junction) between root (exclusive) and full, if any.
+function linkOnPath(root, full) {
+  let cur = root;
+  for (const part of relative(root, full).split(sep)) {
+    cur = join(cur, part);
+    const st = lstat(cur);
+    if (!st) return null; // the rest doesn't exist yet
+    if (st.isSymbolicLink()) return cur;
+  }
+  return null;
+}
+
+// Resolve a path strictly below the project root, refusing symbolic links on the way, so
+// writes and deletes can't be redirected outside the project.
+function inside(root, p) {
+  const full = resolve(root, p);
+  if (!full.startsWith(root + sep)) fail(`refusing to touch a path outside the project: ${p}`);
+  const link = linkOnPath(root, full);
+  if (link) fail(`refusing to follow a symbolic link: ${relative(root, link).split(sep).join('/')}`);
+  return full;
+}
+
+// A real (non-symlinked) directory below root, or null.
+function safeDir(root, rel) {
+  const full = resolve(root, rel);
+  if (!full.startsWith(root + sep) || linkOnPath(root, full)) return null;
+  return lstat(full)?.isDirectory() ? full : null;
+}
+
+// Stable content hash of a directory (relative paths + bytes), used to spot user edits.
+// Symbolic links and special files are skipped (and never copied), so a link can't pull outside
+// content in or make the walk loop. Anything that isn't a directory gets a sentinel hash, so it is
+// treated as user content and left alone.
+export function hashDir(dir) {
+  const st = lstat(dir);
+  if (!st) return null;
+  if (!st.isDirectory()) return 'not-a-directory';
+  const h = createHash('sha256');
+  const walk = (d) => {
+    for (const ent of readdirSync(d, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const full = join(d, ent.name);
+      if (ent.isDirectory()) walk(full);
+      else if (ent.isFile()) h.update(relative(dir, full).split(sep).join('/')).update('\0').update(readFileSync(full)).update('\0');
+    }
+  };
+  walk(dir);
+  return h.digest('hex').slice(0, 16);
+}
+const noLinks = (src) => !lstatSync(src).isSymbolicLink();
+
+// Read the lock file, keeping only entries nestjs-boost itself could have written.
+export function readLock(lockPath) {
+  const raw = readJson(lockPath);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const ignored = [];
+  const files = {};
+  for (const [rel, hash] of Object.entries(raw.files && typeof raw.files === 'object' ? raw.files : {})) {
+    if (SKILL_PATH_RE.test(rel) && typeof hash === 'string') files[rel] = hash;
+    else ignored.push(rel);
+  }
+  const guidelineList = (v) => (Array.isArray(v) ? v : []).filter((f) => {
+    const ok = GUIDELINE_FILES.has(f);
+    if (!ok) ignored.push(String(f));
+    return ok;
+  });
+  return {
+    ...raw,
+    agents: Array.isArray(raw.agents) ? raw.agents.map(String) : undefined,
+    files,
+    guidelines: guidelineList(raw.guidelines),
+    createdGuidelines: guidelineList(raw.createdGuidelines),
+    ignored: [...new Set(ignored)],
+  };
+}
+const ignoredWarning = (lock) => (lock?.ignored.length
+  ? [`lock file lists paths nestjs-boost never writes; ignored: ${lock.ignored.join(', ')}`] : []);
+
+// ---------- detection ----------
+export function isNestProject(root) {
+  const pkg = readJson(join(root, 'package.json'));
+  return Boolean(pkg && { ...pkg.devDependencies, ...pkg.dependencies }['@nestjs/core']);
+}
+
+export function detect(root) {
+  const rootPkg = readJson(join(root, 'package.json'));
+  if (!rootPkg) fail(`no package.json in ${root}`);
+  const pkgs = [rootPkg];
+  for (const dir of ['apps', 'libs', 'packages']) {
+    const base = join(root, dir);
+    if (!existsSync(base) || !statSync(base).isDirectory()) continue;
+    for (const name of readdirSync(base)) {
+      const p = readJson(join(base, name, 'package.json'));
+      if (p) pkgs.push(p);
+    }
+  }
+  const deps = {};
+  for (const p of pkgs) Object.assign(deps, p.devDependencies, p.dependencies);
+  if (!deps['@nestjs/core']) fail('no @nestjs/core in package.json; run this in a NestJS project');
+
+  const installedCore = readJson(join(root, 'node_modules/@nestjs/core/package.json'))?.version;
+  const coreVersion = installedCore ?? String(deps['@nestjs/core']).replace(/^[^\d]*/, '');
+  const nestMajor = Number(coreVersion.split('.')[0]) || null;
+
+  const has = (name) => Boolean(deps[name]);
+  const adapter = has('@nestjs/platform-node') ? 'Node adapter (@nestjs/platform-node)'
+    : has('@nestjs/platform-fastify') ? 'Fastify (@nestjs/platform-fastify)'
+    : has('@nestjs/platform-express') ? 'Express (@nestjs/platform-express)' : 'none (no HTTP platform package)';
+  const esm = rootPkg.type === 'module';
+  const testRunner = has('vitest') ? 'Vitest' : has('jest') ? 'Jest' : 'unknown';
+  const linter = has('oxlint') ? 'oxlint' : has('eslint') ? 'ESLint' : has('@biomejs/biome') ? 'Biome' : 'none';
+  const pm = existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm'
+    : existsSync(join(root, 'yarn.lock')) ? 'yarn'
+    : existsSync(join(root, 'bun.lockb')) || existsSync(join(root, 'bun.lock')) ? 'bun' : 'npm';
+  const schemaLib = ['zod', 'valibot', 'arktype'].find(has);
+  const validation = [schemaLib && `Standard Schema (${schemaLib}) with StandardSchemaValidationPipe`, has('class-validator') && 'class-validator with ValidationPipe']
+    .filter(Boolean).join(' + ') || 'none installed yet (default: zod + StandardSchemaValidationPipe)';
+  const nestCli = readJson(join(root, 'nest-cli.json')) ?? {};
+
+  const scripts = rootPkg.scripts ?? {};
+  const run = (s) => (pm === 'npm' ? (s === 'test' ? 'npm test' : `npm run ${s}`) : `${pm} ${s}`);
+  const cmd = (s, fallback) => (scripts[s] ? run(s) : fallback);
+
+  return {
+    root, deps, nestMajor, coreVersion, adapter, esm, testRunner, linter, pm, validation,
+    config: rootPkg['nestjs-boost'] ?? null,
+    monorepo: nestCli.monorepo === true,
+    files: (names) => names.filter((n) => existsSync(join(root, n))),
+    commands: {
+      build: cmd('build', 'npx nest build'),
+      lint: cmd('lint', '# no lint script'),
+      test: cmd('test', '# no test script'),
+      e2e: cmd('test:e2e', '# no e2e script'),
+      start: cmd('start:prod', 'node dist/main'),
+    },
+  };
+}
+
+// Agents whose files are already in the project (registry order); empty if none.
+export function findAgents(root) {
+  return AGENT_IDS.filter((id) => AGENTS[id].markers.some((m) => existsSync(join(root, m))));
+}
+
+export function detectAgents(root) {
+  const found = findAgents(root);
+  return found.length ? found : DEFAULT_AGENTS;
+}
+
+// Validate and normalise an agent list: known ids only, registry order, no duplicates.
+export function normalizeAgents(list) {
+  const ids = toList(list);
+  const unknown = ids.filter((a) => !AGENTS[a]);
+  if (unknown.length) fail(`unknown agent(s): ${unknown.join(', ')} (known: ${AGENT_IDS.join(', ')}; see \`nestjs-boost agents\`)`);
+  return AGENT_IDS.filter((id) => ids.includes(id));
+}
+
+// Options precedence: explicit (CLI) > package.json "nestjs-boost" > .ai/nestjs-boost.json > lock > detection.
+// `agentSource` says which one decided the agents, so the CLI knows whether to ask.
+export function resolveOptions(root, facts, explicit = {}, lock = null) {
+  const file = readJson(join(root, CONFIG_FILE)) ?? {};
+  const pkg = facts.config ?? {};
+  const given = (v) => v !== undefined && !(Array.isArray(v) && !v.length) && v !== '';
+  const pick = (key) => [explicit[key], pkg[key], file[key]].find(given);
+  const agentSources = [['cli', explicit.agents], ['package.json', pkg.agents], [CONFIG_FILE, file.agents], ['lock', lock?.agents]];
+  const [agentSource, agentList] = agentSources.find(([, v]) => toList(v).length) ?? [findAgents(root).length ? 'detected' : 'default', detectAgents(root)];
+  const agents = normalizeAgents(agentList);
+  return {
+    agents,
+    agentSource,
+    all: Boolean(pick('all')),
+    include: toList(pick('include')),
+    exclude: toList(pick('exclude')),
+    guidelines: pick('guidelines') !== false,
+  };
+}
+
+// ---------- skill selection ----------
+export function selectSkills(facts, { all = false, include = [], exclude = [] } = {}) {
+  const known = new Set(MANIFEST.skills.map((s) => s.name));
+  const unknown = [...include, ...exclude].filter((n) => !known.has(n));
+  if (unknown.length) fail(`unknown skill(s): ${unknown.join(', ')} (see \`nestjs-boost list --all\`)`);
+  const selected = [];
+  for (const s of MANIFEST.skills) {
+    const w = s.installWhen ?? {};
+    let reason = null;
+    if (w.always) reason = 'foundation';
+    else if (w.anyDependency?.some((d) => facts.deps[d])) reason = `dependency: ${w.anyDependency.filter((d) => facts.deps[d]).join(', ')}`;
+    else if (w.anyFile && facts.files(w.anyFile).length) reason = `file: ${facts.files(w.anyFile).join(', ')}`;
+    else if (w.nestjsMajorBelow && facts.nestMajor && facts.nestMajor < w.nestjsMajorBelow) reason = `NestJS ${facts.nestMajor} < ${w.nestjsMajorBelow}`;
+    if (!reason && (all || include.includes(s.name))) reason = all ? 'all' : 'include';
+    if (reason && exclude.includes(s.name)) reason = null;
+    if (reason && existsSync(join(PACK_DIR, 'skills', s.name, 'SKILL.md'))) selected.push({ name: s.name, reason });
+  }
+  return selected;
+}
+
+// ---------- guidelines ----------
+function skillSummary(skillDir) {
+  const md = readFileSync(join(skillDir, 'SKILL.md'), 'utf8');
+  const desc = md.match(/^description:\s*(.+)$/m)?.[1] ?? '';
+  const use = desc.match(/Use when (.+?)(?:\. Not for |\.?$)/)?.[1];
+  return use ? `use when ${use}` : desc;
+}
+
+export function renderGuidelines(facts, skills, root, customSkills = []) {
+  let tpl = readFileSync(join(PACK_DIR, 'guidelines/core.md'), 'utf8');
+  const runnerApi = facts.testRunner === 'Vitest' ? '`vi.fn()`, `vi.spyOn()`' : facts.testRunner === 'Jest' ? '`jest.fn()`, `jest.spyOn()`' : 'the configured runner';
+  const values = {
+    nestjsVersion: facts.coreVersion,
+    docsCrawled: MANIFEST.docs.crawled,
+    httpAdapter: facts.adapter,
+    moduleFormat: facts.esm ? 'ESM (`"type": "module"`)' : 'CommonJS',
+    testRunner: facts.testRunner,
+    linter: facts.linter,
+    packageManager: facts.pm,
+    validation: facts.validation,
+    esmNote: facts.esm ? 'This is an **ESM** project: relative imports use the `.js` extension (`import { X } from \'./x.service.js\'`), and `main.ts` may use top-level `await`.' : '',
+    buildCommand: facts.commands.build,
+    lintCommand: facts.commands.lint,
+    testCommand: facts.commands.test,
+    e2eCommand: facts.commands.e2e,
+    startCommand: facts.commands.start,
+    testRunnerApi: runnerApi,
+    skillMap: [
+      ...skills.map((s) => `- \`${s.name}\`: ${skillSummary(join(PACK_DIR, 'skills', s.name))}`),
+      ...customSkills.map((n) => `- \`${n}\` (project): ${skillSummary(join(root, '.ai/skills', n))}`),
+    ].join('\n'),
+  };
+  tpl = tpl.replace(/\{\{(\w+)\}\}/g, (_, k) => values[k] ?? '');
+  const extraDir = safeDir(root, '.ai/guidelines');
+  if (extraDir) {
+    const extras = readdirSync(extraDir, { withFileTypes: true })
+      .filter((d) => d.isFile() && d.name.endsWith('.md')).map((d) => d.name).sort();
+    for (const f of extras) tpl += `\n\n${readFileSync(join(extraDir, f), 'utf8').trim()}\n`;
+  }
+  return stripMarkers(tpl).replace(/\n{3,}/g, '\n\n').trim();
+}
+
+// Project-supplied text (custom guidelines, skill descriptions) must not contain the block
+// markers, or it would move the block boundaries and later syncs could overwrite user text.
+const stripMarkers = (text) => text.split(START).join('').split(END).join('');
+
+// Replace only the marked block; keep everything the user wrote outside it.
+export function upsertBlock(existing, body) {
+  const block = `${START}\n${body}\n${END}`;
+  if (!existing) return `${block}\n`;
+  const s = existing.indexOf(START);
+  const e = existing.indexOf(END);
+  if (s !== -1 && e > s) return existing.slice(0, s) + block + existing.slice(e + END.length);
+  return `${existing.trimEnd()}\n\n${block}\n`;
+}
+
+export function removeBlock(existing) {
+  const s = existing.indexOf(START);
+  const e = existing.indexOf(END);
+  if (s === -1 || e < s) return existing;
+  return `${existing.slice(0, s).trimEnd()}\n\n${existing.slice(e + END.length).trimStart()}`.trim() + '\n';
+}
+
+// ---------- sync ----------
+// Returns a report; writes nothing when dryRun is set.
+export function sync(root, explicit = {}, { dryRun = false, force = false, prune = true } = {}) {
+  root = resolve(root);
+  const lockPath = inside(root, LOCK);
+  const lock = readLock(lockPath);
+  const facts = detect(root);
+  const opts = resolveOptions(root, facts, explicit, lock);
+  const skills = selectSkills(facts, opts);
+  const warnings = ignoredWarning(lock);
+  const overridesDir = safeDir(root, '.ai/skills');
+  const overrides = [];
+  for (const d of overridesDir ? readdirSync(overridesDir, { withFileTypes: true }) : []) {
+    const skillFile = lstat(join(overridesDir, d.name, 'SKILL.md'));
+    if (!d.isDirectory() || !skillFile?.isFile()) {
+      if (d.isSymbolicLink()) warnings.push(`.ai/skills/${d.name}: symbolic link; skipped`);
+      continue;
+    }
+    if (!NAME_RE.test(d.name)) { warnings.push(`.ai/skills/${d.name}: skill names must be lowercase-with-hyphens; skipped`); continue; }
+    overrides.push(d.name);
+  }
+  const custom = overrides.filter((n) => !skills.some((s) => s.name === n));
+  const prevFiles = lock?.files ?? {};
+  const files = {};
+  const changes = [];
+
+  const wanted = new Map();
+  const skillDirs = planSkillDirs(opts.agents);
+  for (const { dir } of skillDirs) {
+    for (const s of skills) wanted.set(`${dir}/${s.name}`, overrides.includes(s.name) ? join(overridesDir, s.name) : join(PACK_DIR, 'skills', s.name));
+    for (const n of custom) wanted.set(`${dir}/${n}`, join(overridesDir, n));
+  }
+
+  for (const [rel, src] of wanted) {
+    const dest = inside(root, rel);
+    const srcHash = hashDir(src);
+    const destHash = hashDir(dest);
+    const tracked = prevFiles[rel];
+    if (destHash === srcHash) { files[rel] = srcHash; continue; }
+    if (destHash && !force && (tracked === undefined || destHash !== tracked)) {
+      warnings.push(`${rel}: ${tracked === undefined ? 'exists and was not installed by nestjs-boost' : 'was edited'}; left as is (customize via .ai/skills/${rel.split('/').pop()}/, or use --force)`);
+      if (tracked !== undefined) files[rel] = tracked;
+      continue;
+    }
+    changes.push({ action: destHash ? 'update' : 'add', path: rel });
+    if (!dryRun) {
+      rmSync(dest, { recursive: true, force: true });
+      mkdirSync(dirname(dest), { recursive: true });
+      cpSync(src, dest, { recursive: true, filter: noLinks });
+    }
+    files[rel] = srcHash;
+  }
+
+  // Skills installed earlier whose condition no longer holds.
+  for (const [rel, hash] of Object.entries(prevFiles)) {
+    if (wanted.has(rel)) continue;
+    const dest = inside(root, rel);
+    const current = hashDir(dest);
+    if (!current) continue;
+    if (!prune || (current !== hash && !force)) {
+      if (prune) warnings.push(`${rel}: no longer needed but was edited; left as is (delete it yourself, or use --force)`);
+      files[rel] = hash;
+      continue;
+    }
+    changes.push({ action: 'remove', path: rel });
+    if (!dryRun) rmSync(dest, { recursive: true, force: true });
+  }
+
+  // Guidelines block in each agent's instructions file.
+  const guidelineFiles = opts.guidelines ? instructionFiles(opts.agents) : [];
+  const created = new Set(lock?.createdGuidelines ?? []);
+  if (guidelineFiles.length) {
+    const body = renderGuidelines(facts, skills, root, custom);
+    for (const rel of guidelineFiles) {
+      const dest = inside(root, rel);
+      const before = existsSync(dest) ? readFileSync(dest, 'utf8') : '';
+      const after = upsertBlock(before, body);
+      if (!before) created.add(rel);
+      if (before === after) continue;
+      changes.push({ action: before ? 'update' : 'add', path: `${rel} (guidelines block)` });
+      if (!dryRun) { mkdirSync(dirname(dest), { recursive: true }); writeFileSync(dest, after); }
+    }
+  }
+  // Instructions files of agents no longer selected (or guidelines turned off): take the block out.
+  if (prune) {
+    for (const rel of lock?.guidelines ?? []) {
+      if (!guidelineFiles.includes(rel)) removeGuideline(root, rel, lock.createdGuidelines.includes(rel), changes, dryRun);
+    }
+  }
+  if (!dryRun) removeEmptyDirs(root, changes);
+
+  const nextLock = {
+    pack: MANIFEST.pack, version: PACK_VERSION, agents: opts.agents,
+    skills: skills.map((s) => s.name), guidelines: guidelineFiles,
+    createdGuidelines: [...created].filter((f) => guidelineFiles.includes(f)).sort(), files,
+  };
+  const lockText = JSON.stringify(nextLock, null, 2) + '\n';
+  if (!dryRun && (!existsSync(lockPath) || readFileSync(lockPath, 'utf8') !== lockText)) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    writeFileSync(lockPath, lockText);
+  }
+  return { facts, opts, foundAgents: findAgents(root), skills, custom, skillDirs, guidelineFiles, changes, warnings, dryRun };
+}
+
+// Take the nestjs-boost block out of an instructions file; delete the file if nestjs-boost created
+// it and nothing else is left.
+function removeGuideline(root, rel, createdByUs, changes, dryRun) {
+  const dest = inside(root, rel);
+  if (!lstat(dest)?.isFile()) return;
+  const before = readFileSync(dest, 'utf8');
+  const after = removeBlock(before);
+  if (before === after) return;
+  const drop = after.trim() === '' && createdByUs;
+  changes.push({ action: drop ? 'remove' : 'update', path: `${rel}${drop ? '' : ' (guidelines block removed)'}` });
+  if (!dryRun) drop ? rmSync(dest) : writeFileSync(dest, after);
+}
+
+// After removing skill folders, also remove the skills folder and its agent folder (e.g. `.cursor/`)
+// if that left them empty. Only folders above a removed path are considered.
+function removeEmptyDirs(root, changes, extra = []) {
+  const removed = changes.filter((c) => c.action === 'remove').map((c) => c.path);
+  const candidates = [...new Set([...removed.flatMap((p) => [dirname(p), dirname(dirname(p))]), ...extra])]
+    .filter((d) => d !== '.' && (ALL_SKILL_DIRS.some((s) => s === d || dirname(s) === d) || extra.includes(d)));
+  for (const rel of candidates) {
+    const d = safeDir(root, rel);
+    try { if (d && !readdirSync(d).length) rmSync(d, { recursive: true }); } catch { /* absent or busy */ }
+  }
+}
+
+// Remove everything nestjs-boost installed (edited skills are kept unless force).
+export function uninstall(root, { dryRun = false, force = false } = {}) {
+  root = resolve(root);
+  const lockPath = inside(root, LOCK);
+  const lock = readLock(lockPath);
+  const changes = [];
+  if (!lock) return { changes, warnings: ['nothing to remove: no .ai/nestjs-boost.lock.json'], dryRun };
+  const warnings = ignoredWarning(lock);
+  for (const [rel, hash] of Object.entries(lock.files)) {
+    const dest = inside(root, rel);
+    const current = hashDir(dest);
+    if (!current) continue;
+    if (current !== hash && !force) { warnings.push(`${rel}: edited; kept (use --force to remove)`); continue; }
+    changes.push({ action: 'remove', path: rel });
+    if (!dryRun) rmSync(dest, { recursive: true, force: true });
+  }
+  for (const rel of lock.guidelines) removeGuideline(root, rel, lock.createdGuidelines.includes(rel), changes, dryRun);
+  if (!dryRun) {
+    rmSync(lockPath, { force: true });
+    removeEmptyDirs(root, changes, ['.ai']);
+  }
+  return { changes, warnings, dryRun };
+}

package/lib/prompt.mjs

@@ -0,0 +1,131 @@
+// Minimal interactive prompts (multi-select and yes/no) on top of node:readline, so the package
+// keeps zero dependencies. Every prompt takes an `io` object ({ input, output, env }) so tests can
+// drive it with fake streams. Callers must check canPrompt() first; without a real terminal they
+// should fall back to flags, config or detection instead of asking.
+import { emitKeypressEvents } from 'node:readline';
+
+export class PromptCancelled extends Error {
+  constructor() { super('cancelled'); }
+}
+
+const defaultIo = () => ({ input: process.stdin, output: process.stdout, env: process.env });
+
+export function canPrompt(io = defaultIo()) {
+  return Boolean(io.input?.isTTY && io.output?.isTTY && typeof io.input.setRawMode === 'function');
+}
+
+// Unicode symbols where the terminal is known to render them; ASCII elsewhere (old Windows consoles).
+function theme(io) {
+  const { env, output } = io;
+  const unicode = process.platform !== 'win32' || Boolean(env.WT_SESSION || env.TERM_PROGRAM || env.ConEmuANSI === 'ON');
+  const color = !env.NO_COLOR && (typeof output.hasColors === 'function' ? output.hasColors() : Boolean(output.isTTY));
+  const paint = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
+  return {
+    dim: paint('2'), bold: paint('1'), cyan: paint('36'), green: paint('32'), red: paint('31'),
+    pointer: unicode ? '❯' : '>', on: unicode ? '◉' : '[x]', off: unicode ? '◯' : '[ ]',
+    ask: unicode ? '?' : '?', done: unicode ? '✔' : 'v',
+  };
+}
+
+// Runs one prompt: raw-mode key handling plus in-place redraw. `render` returns the lines to show;
+// `onKey` returns { done: value } to finish, or nothing to keep going.
+function session(io, render, onKey) {
+  const { input, output } = io;
+  return new Promise((resolve, reject) => {
+    let drawn = 0;
+    const width = () => Math.max(20, (output.columns || 80) - 1);
+    // Lines are cut to the terminal width so a wrapped line can't break the redraw.
+    const fit = (line) => {
+      let visible = 0;
+      let out = '';
+      for (const part of line.split(/(\x1b\[[0-9;]*m)/)) {
+        if (part.startsWith('\x1b[')) { out += part; continue; }
+        const room = width() - visible;
+        if (room <= 0) break;
+        out += part.length > room ? `${part.slice(0, Math.max(0, room - 1))}…` : part;
+        visible += Math.min(part.length, room);
+      }
+      return `${out}\x1b[0m`;
+    };
+    const draw = (lines) => {
+      if (drawn) output.write(`\x1b[${drawn}A\x1b[0J`);
+      output.write(`${lines.map(fit).join('\n')}\n`);
+      drawn = lines.length;
+    };
+    const finish = (fn, finalLines) => {
+      input.removeListener('keypress', handler);
+      if (input.isTTY) input.setRawMode(false);
+      input.pause();
+      if (finalLines) draw(finalLines);
+      output.write('\x1b[?25h');
+      fn();
+    };
+    const handler = (str, key = {}) => {
+      if ((key.ctrl && key.name === 'c') || key.name === 'escape') {
+        return finish(() => reject(new PromptCancelled()));
+      }
+      const result = onKey(str, key);
+      if (result && 'done' in result) return finish(() => resolve(result.done), result.final);
+      draw(render());
+    };
+    emitKeypressEvents(input);
+    if (input.isTTY) input.setRawMode(true);
+    input.on('keypress', handler);
+    input.resume();
+    output.write('\x1b[?25l');
+    draw(render());
+  });
+}
+
+// choices: [{ value, label, hint?, tag?, checked? }]. Resolves to the selected values in list order.
+export function multiSelect({ message, choices, min = 1 }, io = defaultIo()) {
+  const t = theme(io);
+  let cursor = 0;
+  let error = '';
+  const selected = new Set(choices.filter((c) => c.checked).map((c) => c.value));
+  const labelWidth = Math.max(...choices.map((c) => c.label.length));
+  const tagWidth = Math.max(0, ...choices.map((c) => (c.tag ?? '').length));
+  const render = () => [
+    `${t.cyan(t.ask)} ${t.bold(message)}`,
+    t.dim('  ↑/↓ move · space select · a all/none · enter confirm · esc cancel'),
+    ...choices.map((c, i) => {
+      const here = i === cursor;
+      const box = selected.has(c.value) ? t.green(t.on) : t.dim(t.off);
+      const label = here ? t.cyan(c.label.padEnd(labelWidth)) : c.label.padEnd(labelWidth);
+      const tag = tagWidth ? ` ${t.green((c.tag ?? '').padEnd(tagWidth))}` : '';   // own column, keeps hints aligned
+      return `${here ? t.cyan(t.pointer) : ' '} ${box} ${label}${tag}  ${t.dim(c.hint ?? '')}`;
+    }),
+    ...(error ? [t.red(`  ${error}`)] : []),
+  ];
+  return session(io, render, (str, key) => {
+    error = '';
+    if (key.name === 'up' || str === 'k') cursor = (cursor - 1 + choices.length) % choices.length;
+    else if (key.name === 'down' || str === 'j') cursor = (cursor + 1) % choices.length;
+    else if (key.name === 'space') {
+      const v = choices[cursor].value;
+      selected.has(v) ? selected.delete(v) : selected.add(v);
+    } else if (str === 'a') {
+      const all = selected.size === choices.length;
+      choices.forEach((c) => (all ? selected.delete(c.value) : selected.add(c.value)));
+    } else if (key.name === 'return' || key.name === 'enter') {
+      if (selected.size < min) { error = `Select at least ${min} (press space).`; return undefined; }
+      const values = choices.filter((c) => selected.has(c.value)).map((c) => c.value);
+      const names = choices.filter((c) => selected.has(c.value)).map((c) => c.label).join(', ');
+      return { done: values, final: [`${t.green(t.done)} ${t.bold(message)} ${t.cyan(names)}`] };
+    }
+    return undefined;
+  });
+}
+
+export function confirm({ message, initial = true }, io = defaultIo()) {
+  const t = theme(io);
+  const render = () => [`${t.cyan(t.ask)} ${t.bold(message)} ${t.dim(initial ? '(Y/n)' : '(y/N)')}`];
+  return session(io, render, (str, key) => {
+    let answer;
+    if (str === 'y' || str === 'Y') answer = true;
+    else if (str === 'n' || str === 'N') answer = false;
+    else if (key.name === 'return' || key.name === 'enter') answer = initial;
+    if (answer === undefined) return undefined;
+    return { done: answer, final: [`${t.green(t.done)} ${t.bold(message)} ${t.cyan(answer ? 'Yes' : 'No')}`] };
+  });
+}

package/lib/setup.mjs

@@ -0,0 +1,60 @@
+// Interactive `nestjs-boost install`: pick agents, review the plan, confirm, install.
+// All writing goes through installer.sync(); this module only asks questions and reports.
+import { AGENTS, AGENT_LIST, sync } from './installer.mjs';
+import { confirm, multiSelect } from './prompt.mjs';
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// Picker entries: every registry agent, pre-checking the current choice (lock, detection or default).
+export function agentChoices(current, found) {
+  return AGENT_LIST.map((a) => ({
+    value: a.id,
+    label: a.name,
+    tag: found.includes(a.id) ? '(detected)' : '',
+    hint: `${a.skills.dir}/ · ${a.instructions}${a.hint ? ` · ${a.hint}` : ''}`,
+    checked: current.includes(a.id),
+  }));
+}
+
+// A short, human description of what an install will do, built from a dry-run report.
+export function describePlan(report) {
+  const { skills, custom, skillDirs, guidelineFiles, changes, opts } = report;
+  const lines = [];
+  const foundation = skills.filter((s) => s.reason === 'foundation').length;
+  const extra = [`${foundation} foundation`, `${skills.length - foundation} for your packages`, ...(custom.length ? [`${custom.length} project`] : [])];
+  lines.push(`Skills: ${plural(skills.length + custom.length, 'skill')} (${extra.join(', ')})`);
+  for (const { dir, agents } of skillDirs) {
+    lines.push(`  ${`${dir}/`.padEnd(20)} read by ${agents.map((id) => AGENTS[id].name).join(', ')}`);
+  }
+  if (guidelineFiles.length) lines.push(`Guidelines block: ${guidelineFiles.join(', ')}`);
+  const count = (action) => changes.filter((c) => c.action === action).length;
+  const summary = ['add', 'update', 'remove'].map((a) => (count(a) ? `${count(a)} ${a === 'add' ? 'new' : a === 'update' ? 'updated' : 'removed'}` : '')).filter(Boolean);
+  lines.push(summary.length ? `Changes: ${summary.join(', ')}` : 'Changes: none, already up to date');
+  if (opts.agentSource === 'package.json' || opts.agentSource === '.ai/nestjs-boost.json') {
+    lines.push(`(agents come from ${opts.agentSource}; edit it there to change them)`);
+  }
+  return lines;
+}
+
+// Returns the final sync report, or null when the user declines.
+export async function interactiveInstall(root, explicit, run, io, log = console.log) {
+  // Dry run first: fails early outside a NestJS project and tells us the current agents.
+  const current = sync(root, explicit, { ...run, dryRun: true });
+  const pinned = ['package.json', '.ai/nestjs-boost.json'].includes(current.opts.agentSource);
+  let agents = current.opts.agents;
+  if (!pinned) {
+    agents = await multiSelect({
+      message: 'Which AI coding agents do you use?',
+      choices: agentChoices(current.opts.agents, current.foundAgents),
+    }, io);
+  }
+  const choice = { ...explicit, agents };
+  const plan = sync(root, choice, { ...run, dryRun: true });
+  log('');
+  for (const line of describePlan(plan)) log(line);
+  for (const w of plan.warnings) log(`  ! ${w}`);
+  if (!plan.changes.length) return plan;
+  log('');
+  if (!(await confirm({ message: 'Install now?' }, io))) return null;
+  return sync(root, choice, run);
+}