@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/lib/pack-manifest.mjs

@@ -0,0 +1,20 @@
+// A pack.json is a manifest like a package.json (0.19.0: it says stock or custom, has a git url, and who made it). A custom pack comes
+// from somebody else's repository, so these fields are how a project knows what it is running: what it is, who made it, where it lives.
+const TYPES = ['stock', 'custom'];
+const SEMVER = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
+const GIT_URL = /^(?:https?:\/\/|ssh:\/\/|file:\/\/|git@)\S+$/;
+
+const FIELDS = {
+  version: (p) => SEMVER.test(p.version ?? '') || 'needs a version like 1.2.0',
+  description: (p) => Boolean(p.description?.trim()) || 'needs a description',
+  type: (p) => TYPES.includes(p.type) || `needs a type: ${TYPES.join(' or ')}`,
+  author: (p) => Boolean(String(p.author?.name ?? p.author ?? '').trim()) || 'needs an author: who made it',
+  license: (p) => Boolean(p.license?.trim()) || 'needs a license',
+  repository: (p) => GIT_URL.test(p.repository?.url ?? '') || 'needs repository.url: the git url it lives at',
+};
+
+// The problems of one manifest; `folder` is where it was found, and its name must say the same.
+export function manifestProblems(pack, folder = pack.name) {
+  const said = Object.values(FIELDS).map((check) => check(pack)).filter((r) => r !== true).map((r) => `pack ${folder} ${r}`);
+  return pack.name === folder ? said : [`pack ${folder} says its name is ${pack.name}`, ...said];
+}

package/lib/packs.mjs

@@ -0,0 +1,109 @@
+// Reads the packs shipped in this npm package and plans which file goes where in a project.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'packs');
+const CLAUDE_DIRS = ['rules', 'checks', 'hooks', 'tools'];
+// A tool's own config, read from the project's root: the project's once written, so a pack's file never replaces it.
+const PROJECT_ROOT_FILES = [['clang-tidy', '.clang-tidy'], ['clippy.toml', 'clippy.toml']];
+
+// Packs from a team's own repository (lib/custom-packs.mjs): name -> the folder it was fetched to.
+const CUSTOM = new Map();
+export const registerPack = (name, folder) => CUSTOM.set(name, folder);
+export const customPacks = () => [...CUSTOM.keys()];
+export const packRoot = (name) => CUSTOM.get(name) ?? join(PACKS_DIR, name);
+
+export function availablePacks() {
+  return [...readdirSync(PACKS_DIR).filter((d) => existsSync(join(PACKS_DIR, d, 'pack.json'))), ...CUSTOM.keys()];
+}
+
+export function readPack(name) {
+  const file = join(packRoot(name), 'pack.json');
+  if (!existsSync(file)) throw new Error(`unknown pack "${name}" (available: ${availablePacks().join(', ')})`);
+  const pack = JSON.parse(readFileSync(file, 'utf8'));
+  if (!CUSTOM.has(name)) return pack;
+  // A hook runs code on every tool call, so somebody else's hook is off until the project names it in "enable".
+  const hooks = join(packRoot(name), 'hooks');
+  return { ...pack, optIn: [...(pack.optIn ?? []), ...(existsSync(hooks) ? readdirSync(hooks).filter((f) => /\.(mjs|py)$/.test(f)).map((f) => `hooks/${f}`) : [])] };
+}
+
+// Python's byte-code caches are never pack files (a selftest run inside the package makes them).
+const JUNK = /^(__pycache__|\.DS_Store)$|\.pyc$/;
+
+function walk(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((entry) => !JUNK.test(entry)).flatMap((entry) => {
+    const abs = join(dir, entry);
+    return statSync(abs).isDirectory() ? walk(abs) : [abs];
+  });
+}
+
+// Returns [{ src, rel }] where rel is the destination relative to the project root.
+// Skills go to the pack's own folder (lazy-loaded nested skills) when it declares one.
+export function planFiles(name, layout) {
+  const pack = readPack(name);
+  const root = packRoot(name);
+  const plan = [];
+  // A rule that states a hook's law ("# hook: <file>" in its frontmatter) goes where its hook goes: held or left out with it (0.10.0).
+  const ruleHook = (src) => readFileSync(src, 'utf8').match(/^---\n(?:[^\n]*\n)*?# hook:\s*(\S+)\s*\n(?:[^\n]*\n)*?---/)?.[1];
+  const off = (src) => {
+    const rel = relative(root, src);
+    if (isDisabled(layout, rel)) return true;
+    const hook = /^rules[\\/][^\\/]+\.md$/.test(rel) && ruleHook(src);
+    return Boolean(hook) && isDisabled(layout, `hooks/${hook}`);
+  };
+  for (const dir of CLAUDE_DIRS) {
+    for (const src of walk(join(root, dir))) if (!off(src)) plan.push({ src, rel: join('.claude', relative(root, src)) });
+  }
+  const skillFolder = pack.skillsIn && layout.folders[pack.skillsIn];
+  const skillBase = skillFolder ? join(skillFolder.path, '.claude') : '.claude';
+  for (const src of walk(join(root, 'skills'))) if (!off(src)) plan.push({ src, rel: join(skillBase, relative(root, src)) });
+  for (const [file, rel] of PROJECT_ROOT_FILES) if (existsSync(join(root, file))) plan.push({ src: join(root, file), rel, userOwned: true });
+  return plan;
+}
+
+// Every hook script any pack ships (node .mjs or python3 .py), by file name. settings.json entries
+// that run one of these are the package's; every other hook entry is the project's own.
+export function kitHookScripts() {
+  const out = new Set();
+  for (const name of availablePacks()) {
+    const dir = join(PACKS_DIR, name, 'hooks');
+    if (existsSync(dir)) for (const f of readdirSync(dir)) if (/\.(mjs|py)$/.test(f)) out.add(f);
+  }
+  return out;
+}
+
+// layout.disable lists pack items a project switches off because it already has its own:
+// "checks/one-seeded-random.json", "hooks/no-shipped-images.mjs", "rules/x.md", "skills/gpu-capture".
+export function isDisabled(layout, packRel) {
+  const p = packRel.replace(/\\/g, '/');
+  return (layout.disable ?? []).some((d) => p === d || p.startsWith(`${d.replace(/\/$/, '')}/`));
+}
+
+// A preset names a stack; `init node-api` installs exactly the packs that stack needs (v7 additions 0.11.0, v8 0.12.0). The
+// configuration is then the smallest one that takes those packs (lib/configs.mjs inferConfig): `node` for the node
+// presets, `synth-creator` for synth.
+export const PRESETS = {
+  'node-api': ['js-ts', 'http-api', 'mongo', 'fastify', 'ai', 'docker'],
+  'node-ui': ['js-ts', 'http-api', 'mongo', 'fastify', 'html-ui', 'stored-text', 'ui-craft', 'docker'],
+  'next-app': ['js-ts', 'http-api', 'react', 'mongo', 'web', 'stored-text', 'ui-craft', 'ai', 'docker'],
+  'mcp-server': ['js-ts', 'mongo', 'ai', 'shell-hooks'],
+  'node-cli': ['js-ts', 'tui'],
+  'node-lib': ['js-ts'],
+  edge: ['nginx', 'docker'],
+  synth: ['cpp', 'audio-core'],
+  'synth-rebuild': ['cpp', 'audio-core', 'reverse-engineering', 'midi', 'sound-design', 'instrument-shell'],
+  'python-app': ['python', 'shell', 'docker'],
+  'shell-tools': ['shell'],
+  'go-app': ['go', 'shell', 'docker', 'ci'],
+  'rust-app': ['rust', 'shell', 'docker', 'ci'],
+};
+
+// Base always first, no duplicates, presets expanded, in the order given.
+export function normalisePacks(names) {
+  const out = ['base'];
+  for (const n of names.flatMap((p) => (Object.hasOwn(PRESETS, p) ? PRESETS[p] : [p]))) if (!out.includes(n)) out.push(n);
+  for (const n of out) readPack(n);
+  return out;
+}

package/lib/planner.mjs

@@ -0,0 +1,59 @@
+// The planner-skills generator (0.10.0, STEP 3 item 5; KWB-35): one project-layout skill body per configuration, made
+// from that configuration's layout template, its packs and its preamble, for a planner that briefs work before any project
+// of that kind exists (or without reading one). `claude-packs planner-skills` prints them; `--out <dir>` writes
+// <dir>/<configuration>/project-layout/SKILL.md.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { availableConfigs, itemsOf, planOf, readConfig } from './configs.mjs';
+
+export function plannerSkill(name) {
+  const c = readConfig(name);
+  const folders = c.layout?.folders ?? {};
+  const where = (k) => (folders[k.in] ? `${folders[k.in].path}/` : k.in);
+  const items = itemsOf(planOf(c, [...c.packs.always, ...c.packs.default]));
+  return [
+    '---',
+    'name: project-layout',
+    `description: Use when planning, briefing or placing work in a ${name} project: where a new file, folder or kind of thing goes, and which laws hold there.`,
+    '---',
+    `# Project layout: ${name}`,
+    '',
+    c.description,
+    '',
+    '## Folders',
+    '',
+    ...Object.values(folders).map((f) => `- \`${f.path}/\`: ${f.purpose}`),
+    '',
+    ...(Object.keys(c.layout?.kinds ?? {}).length ? ['## What goes where', '', ...Object.values(c.layout.kinds).map((k) => `- ${k.what} → \`${where(k)}\``), ''] : []),
+    '## What it installs',
+    '',
+    `- packs: ${c.packs.always.join(', ')}${c.packs.choose.length ? `; to choose: ${c.packs.choose.join(', ')}` : ''}`,
+    `- hooks: ${items.hooks.join(', ')}`,
+    `- skills: ${items.skills.join(', ') || 'none'}`,
+    `- rules: ${items.rules.length} (\`npx --no-install @thedecipherist/claude-packs configs\` lists the configurations)`,
+    '',
+    '## House rules',
+    '',
+    '<constraints>',
+    'Always do:',
+    '- Put every kind of thing in its one place (the folders above); a new folder goes into `.claude/layout.json` first.',
+    ...c.preamble.always.map((l) => `- ${l}`),
+    '',
+    'Never do:',
+    ...c.preamble.never.map((l) => `- ${l}`),
+    '</constraints>',
+    '',
+  ].join('\n');
+}
+
+export function plannerSkills(out = null, log = console.log) {
+  for (const name of availableConfigs()) {
+    const body = plannerSkill(name);
+    if (!out) { log(`==> ${name}/project-layout/SKILL.md\n${body}`); continue; }
+    const dir = join(out, name, 'project-layout');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'SKILL.md'), body);
+    log(`  wrote ${join(dir, 'SKILL.md')}`);
+  }
+  return 0;
+}

package/lib/repeats.mjs

@@ -0,0 +1,65 @@
+// What a project repeats, for `scan`: every shape written by hand more than once, the copies of it, and what it should become. A run seen as
+// many overlapping windows is reported once, from its first window.
+import { extname } from 'node:path';
+import { TEMPLATE, TESTS, copiesNeeded, shapesOf, skippedBy } from '../packs/base/hooks/lib/elements.mjs';
+import { parametersOf } from '../packs/base/hooks/lib/code-shapes.mjs';
+import { languageOf } from '../packs/base/hooks/lib/languages.mjs';
+import { definesOf, fingerprint, nearCopy } from '../packs/base/hooks/lib/near-copies.mjs';
+import { matchesAny } from '../packs/base/hooks/lib/glob.mjs';
+
+const copiesOf = (group) => new Set(group.map((x) => `${x.rel}:${x.line}`)).size;
+const oneName = (group) => new Set(group.map((x) => x.what)).size === 1;
+const isRepeat = (g) => copiesOf(g) >= copiesNeeded(g[0], oneName(g)) && (g[0].kind !== 'setup' || !sameObject(g));
+// One object set up twice in one file is one object.
+const sameObject = (g) => new Set(g.map((x) => `${x.rel} ${x.what}`)).size < 2;
+
+function firstWindows(groups) {
+  const seen = new Set(groups.filter((g) => g[0].kind === 'run').map((g) => g.map((x) => `${x.rel}:${x.at}`).join()));
+  return groups.filter((g) => g[0].kind !== 'run' || !seen.has(g.map((x) => `${x.rel}:${x.at - 1}`).join()));
+}
+
+export function repeatedShapes(texts, layout = {}) {
+  const by = new Map();
+  for (const [rel, text] of texts) {
+    if (matchesAny(rel, [...TESTS, ...skippedBy(layout)])) continue;
+    for (const s of shapesOf(text, extname(rel))) { if (!by.has(s.id)) by.set(s.id, []); by.get(s.id).push({ ...s, rel }); }
+  }
+  const source = new Map(texts);
+  return firstWindows([...by.values()].filter(isRepeat)).sort((a, b) => b.length * b[0].nodes - a.length * a[0].nodes).map((g) => {
+    const [a, b] = g;
+    return { kind: g[0].kind, what: g[0].what, copies: g.length, at: g.map((x) => `${x.rel}:${x.line}`), template: TEMPLATE[g[0].kind],
+      parameters: g[0].kind === 'run' ? parametersOf(a.id, source.get(a.rel), source.get(b.rel), extname(a.rel)).slice(0, 6) : [] };
+  });
+}
+
+export const repeatLine = (r) => `  - ${r.copies}x ${r.what}: ${r.at.slice(0, 4).join(', ')}${r.copies > 4 ? ', ...' : ''}. Make it ${r.template}${r.parameters.length ? ` (differs in: ${r.parameters.join(', ').replace(/`/g, "'")})` : ''}`;
+
+const sourceTexts = (texts, layout) => texts.filter(([rel]) => languageOf(extname(rel)) && !matchesAny(rel, [...TESTS, ...skippedBy(layout)]));
+
+// Files that hold most of another, in order, with other names. A pair is reported once.
+export function nearCopies(texts, layout = {}) {
+  const all = sourceTexts(texts, layout).map(([file, text]) => ({ file, st: fingerprint(text, extname(file)), lang: languageOf(extname(file)) }));
+  const seen = new Set();
+  const out = [];
+  for (const x of all) {
+    const hit = nearCopy(x.st, all.filter((o) => o !== x && o.lang === x.lang));
+    if (!hit || seen.has(`${hit.file} ${x.file}`)) continue;
+    seen.add(`${x.file} ${hit.file}`);
+    out.push({ file: x.file, line: hit.line, other: hit.file, from: hit.from, to: hit.to, matched: hit.matched, of: hit.of });
+  }
+  return out.sort((a, b) => b.matched - a.matched);
+}
+
+// Compound names defined in two or three files: a helper made again. More files than that is a convention.
+export function remadeNames(texts, layout = {}) {
+  const by = new Map();
+  for (const [rel, text] of sourceTexts(texts, layout)) {
+    for (const [name, line] of definesOf(text, extname(rel))) {
+      if (!/[a-z0-9][A-Z]|[a-z0-9]_[a-z0-9]/.test(name)) continue;
+      const key = `${languageOf(extname(rel)).name} ${name}`;
+      if (!by.has(key)) by.set(key, { name, at: [] });
+      by.get(key).at.push(`${rel}:${line}`);
+    }
+  }
+  return [...by.values()].filter((m) => m.at.length >= 2 && m.at.length <= 3 && new Set(m.at.map((a) => a.split(':')[0])).size >= 2);
+}

package/lib/repo-weight.mjs

@@ -0,0 +1,28 @@
+// What a repo carries that is not source: its tracked size, files too big for git, and working screenshots in its root. For `scan`; the `repo-litter`
+// hook stops new ones at `git add`.
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { BIG_MB, isRootImage } from '../packs/base/hooks/repo-litter.mjs';
+
+const MB = 1024 * 1024;
+
+// A build folder is known by what the build leaves in it, whatever it was called: `build-reso/` held 43% of one repo's tracked files.
+const BUILD_MARK = /^(.*?\/)?(?:CMakeFiles\/|CMakeCache\.txt$)/;
+export function buildFolders(files) {
+  const folders = new Set(files.map((f) => f.match(BUILD_MARK)).filter((m) => m?.[1]).map((m) => m[1]));
+  return [...folders].filter((d) => ![...folders].some((o) => o !== d && d.startsWith(o)));
+}
+
+export function repoWeight(dir, files) {
+  const sized = files.flatMap((file) => { try { return [{ file, bytes: statSync(join(dir, file)).size }]; } catch { return []; } });
+  const total = sized.reduce((n, f) => n + f.bytes, 0);
+  const big = sized.filter((f) => f.bytes > BIG_MB * MB).sort((a, b) => b.bytes - a.bytes).map((f) => ({ file: f.file, mb: Math.round(f.bytes / MB) }));
+  const built = buildFolders(files).map((folder) => ({ folder, files: files.filter((f) => f.startsWith(folder)).length }));
+  return { mb: Math.round(total / MB), big, rootImages: files.filter((f) => isRootImage(f, [])), built, files: files.length };
+}
+
+export const weightLines = (w) => [
+  `- ${w.mb} MB tracked; ${w.big.length} file(s) over ${BIG_MB} MB${w.big.length ? `: ${w.big.slice(0, 5).map((b) => `${b.file} (${b.mb} MB)`).join(', ')}` : ''}`,
+  ...w.built.map((b) => `- build output held in git: ${b.folder} (${b.files} of ${w.files} files), left out of this scan`),
+  ...(w.rootImages.length ? [`- ${w.rootImages.length} image(s) in the repo root, which look like working screenshots: ${w.rootImages.slice(0, 5).join(', ')}`] : []),
+];

package/lib/rule-tests.mjs

@@ -0,0 +1,42 @@
+// KF-31: a rule's Check can name a test, and an install reads as if the test exists. Three rules of the MPX 500 named tests that were never written, and
+// the gap held four real bugs while every hook, scan and doctor stayed quiet. doctor is red for a live rule (one that matches a file of the project)
+// whose Check names a test nothing answers to. A test answers by naming the rule (`proves: <rule>`, in a test, bench or gate file), or layout.json
+// "ruleTests" points the rule at a file, or declines it with "none: <reason>".
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const TEST_PLACE = /(^|\/)(tests?|specs?|e2e|bench|benches|benchmarks?|gates?)(\/|$)|(^|[._-])(test|spec)[._-][^/]*$|_test\.[^/]+$/i;
+const MAX_BYTES = 2 * 1024 * 1024;
+const checkOf = (text) => text.split(/^## Check[ \t]*$/m)[1]?.split(/^## /m)[0] ?? '';
+
+// "Test:", "Tests:", "- Unit test:", "ThreadSanitizer stress test:", "Benchmark test, offline render:" at the head of a line of the Check.
+export const namesATest = (text) => /^[ \t]*(?:(?:[-*]|\d+\.)[ \t]+)?(?:[\w'-]+[ \t]+){0,3}tests?(?:,[^:\n]*)?:/im.test(checkOf(text));
+
+// A file's text, or '' for one too big to be a test or gone since it was listed.
+const smallFileText = (file) => { try { return statSync(file).size > MAX_BYTES ? '' : readFileSync(file, 'utf8'); } catch { return ''; } };
+const inTestFolder = (rel, folders) => TEST_PLACE.test(rel) || folders.some((f) => rel === f || rel.startsWith(`${f}/`));
+
+export function ruleTestProblems(projectDir, layout, { liveRules, files }) {
+  const dir = join(projectDir, '.claude', 'rules');
+  if (!existsSync(dir)) return [];
+  const named = readdirSync(dir).filter((f) => liveRules.includes(f) && namesATest(smallFileText(join(dir, f)))).map((f) => basename(f, '.md'));
+  if (!named.length) return [];
+  const folders = (layout.concepts?.tests ?? []).map((f) => layout.folders?.[f]?.path ?? f).filter((f) => !f.includes('*'));
+  const tests = files.filter((f) => inTestFolder(f, folders)).map((f) => smallFileText(join(projectDir, f)));
+  const declared = layout.ruleTests ?? {};
+  const problems = [];
+  const open = named.filter((rule) => {
+    const said = declared[rule];
+    if (/^none:\s*\S/.test(said ?? '')) return false;
+    if (said && said !== 'none') {
+      if (!existsSync(join(projectDir, said))) problems.push(`${rule}: ruleTests names ${said}, which does not exist`);
+      return false;
+    }
+    return !tests.some((t) => t.includes(rule));
+  });
+  if (open.length) {
+    const how = 'Write the test its Check names, and put `proves: <rule>` in it. Or set layout.json "ruleTests": { "<rule>": "<path>" }, or "none: <reason>".';
+    problems.push(`${open.length} rule(s) name a test nothing in this project answers to: ${open.join(', ')}\n    ${how}`);
+  }
+  return problems;
+}

package/lib/rules.mjs

@@ -0,0 +1,40 @@
+// Regenerates every rule's `paths:` from its `# concepts:` line and the layout.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { globsForConcepts as kitGlobs } from '../packs/base/hooks/lib/layout.mjs';
+
+// A rule's text with its `paths:` written from its concepts and the layout; null for a rule
+// without a `# concepts:` line, or (unless strict, which throws) whose concepts resolve to nothing.
+export function renderRule(text, layout, globsForConcepts = kitGlobs, strict = false) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  const line = fm?.[1].match(/^# concepts:\s*(.+)$/m);
+  if (!fm || !line) return null;
+  const concepts = line[1].split(',').map((s) => s.trim()).filter(Boolean);
+  let globs;
+  try { globs = globsForConcepts(layout, concepts); } catch (e) { if (strict) throw e; return null; }
+  const head = ['---', `# concepts: ${concepts.join(', ')}`, 'paths:', ...globs.map((g) => `  - "${g}"`), '---'].join('\n');
+  return text.replace(fm[0], head);
+}
+
+async function layoutLib(projectDir) {
+  return import(pathToFileURL(join(projectDir, '.claude', 'hooks', 'lib', 'layout.mjs')).href);
+}
+
+export async function applyPaths(projectDir, { checkOnly = false, skip = new Set() } = {}) {
+  const { readLayout, globsForConcepts } = await layoutLib(projectDir);
+  const layout = readLayout(projectDir);
+  const dir = join(projectDir, '.claude', 'rules');
+  if (!existsSync(dir)) return { stale: 0 };
+  let stale = 0;
+  for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+    if (skip.has(join('.claude', 'rules', file))) continue; // the user's file or a rule they edited
+    const text = readFileSync(join(dir, file), 'utf8');
+    const next = renderRule(text, layout, globsForConcepts, true);
+    if (next !== null && next !== text) {
+      stale += 1;
+      if (!checkOnly) writeFileSync(join(dir, file), next);
+    }
+  }
+  return { stale };
+}

package/lib/scan-detect.mjs

@@ -0,0 +1,130 @@
+// What a project is, from its files and its dependencies: the configuration and the packs `scan` recommends, each with its evidence.
+// One row per pack: a pack is recommended when its row finds something, and says what it found.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isContent } from '../packs/base/hooks/lib/content.mjs';
+import { readConfig } from './configs.mjs';
+
+const dep = (ctx, ...names) => names.find((n) => ctx.deps.has(n) || [...ctx.deps].some((d) => d.startsWith(`${n}/`)));
+const file = (ctx, re) => ctx.files.find((f) => re.test(f));
+const said = (hit, what) => (hit ? `${what}: ${hit}` : null);
+// The first of a project's files with this name that holds this text: a name says too little where every project has the same files.
+const MOST_READ = 40;
+function holds(ctx, name, text) {
+  return ctx.files.filter((f) => name.test(f)).slice(0, MOST_READ).find((f) => { try { return text.test(readFileSync(join(ctx.dir, f), 'utf8')); } catch { return false; } });
+}
+
+// A project at its start has no source, and only its notes say what it will be (KF-3: a JUCE plugin's first `suggest` said base, with no warning). Once code
+// exists the code decides, and a word in a README adds nothing.
+const NOTES = /(^|\/)(?:README|PROMPT|BRIEF|SPEC|PLAN)[^/]*\.md$|^docs\/(?:[^/]+\/)*[^/]+\.md$/i;
+const NOTED = {
+  'audio-core': /\bJUCE\b|\bVST3?\b|\baudio plug-?in\b/i,
+  cpp: /\bC\+\+/,
+  midi: /\bMIDI\b/,
+  'sound-design': /\b(?:reverb|synth|synthesi[sz]er|oscillator)\b/i,
+  'instrument-shell': /\b(?:front panel|plug-?in editor)\b/i,
+  'reverse-engineering': /\bfirmware\b|\breverse[- ]engineer/i,
+  python: /\bPython\b/,
+  rust: /\bRust\b/,
+};
+function noted(ctx, pack) {
+  if (!ctx.early || !NOTED[pack]) return null;
+  const notes = [...ctx.files, ...ctx.published].filter((f) => NOTES.test(f)).slice(0, MOST_READ);
+  const hit = notes.find((f) => { try { return NOTED[pack].test(readFileSync(join(ctx.dir, f), 'utf8')); } catch { return false; } });
+  return said(hit, 'named in the notes');
+}
+
+// A driver alone says Postgres; a tool that speaks several databases says it only with this second signal in its own file.
+const POSTGRES_FILES = [
+  [/(^|\/)(?:requirements[^/]*\.txt|pyproject\.toml|Pipfile)$/, /\b(?:psycopg2?(?:-binary)?|asyncpg)\b/],
+  [/(^|\/)go\.mod$/, /jackc\/pgx|lib\/pq\b|gorm\.io\/driver\/postgres/],
+  [/(^|\/)Cargo\.toml$/, /\b(?:tokio-postgres|deadpool-postgres)\b|\b(?:sqlx|diesel|sea-orm)\b[^\n]*postgres/],
+  [/(^|\/)Gemfile$/, /^\s*gem\s+['"]pg['"]/m],
+  [/\.prisma$/, /provider\s*=\s*"postgresql"/],
+  [/(^|\/)drizzle\.config\.[cm]?[jt]s$/, /dialect:\s*['"]postgresql['"]/],
+  [/(^|\/)[\w.-]*compose[\w.-]*\.ya?ml$/, /image:\s*['"]?[\w./-]*(?:postgres|postgis|pgvector|timescale)/],
+];
+
+const ROWS = {
+  'js-ts': (c) => said(file(c, /\.(ts|tsx|js|jsx|mjs|cjs)$/), 'JS or TS source'),
+  mongo: (c) => said(dep(c, 'mongodb', 'mongoose'), 'dependency'),
+  postgres: (c) => said(dep(c, 'pg', 'postgres', 'pg-promise', '@neondatabase/serverless', '@vercel/postgres'), 'dependency')
+    ?? said(POSTGRES_FILES.map(([name, text]) => holds(c, name, text)).find(Boolean), 'Postgres named in'),
+  fastify: (c) => said(dep(c, 'fastify'), 'dependency'),
+  ai: (c) => said(dep(c, '@anthropic-ai/sdk', 'openai', 'ai', '@ai-sdk'), 'dependency'),
+  docker: (c) => said(file(c, /(^|\/)(Dockerfile[^/]*|[\w.-]*compose[\w.-]*\.ya?ml)$/), 'file'),
+  'shell-hooks': (c) => said(file(c, /(^|\/)hooks\/[^/]+\.(sh|mjs|js|cjs)$/), 'hook file'),
+  'html-ui': (c) => said(file(c, /(^|\/)(ui|views|templates)\/[^/]+\.ts$|\.view\.ts$/), 'server-rendered UI'),
+  web: (c) => said(dep(c, 'next', 'react', 'vue', 'svelte') ?? file(c, /\.(tsx|jsx|vue|svelte|html)$/), 'web UI'),
+  tui: (c) => said(dep(c, 'ink', 'blessed', 'terminal-kit'), 'dependency'),
+  nginx: (c) => said(file(c, /(^|\/)nginx[^/]*\.conf(?:\.template)?$|\/nginx\/.+\.conf$/), 'file'),
+  'stored-text': (c) => (ROWS.web(c) || ROWS['html-ui'](c)) && (ROWS.mongo(c) || dep(c, 'pg', 'mysql2', 'sqlite3', 'better-sqlite3', 'prisma', 'drizzle-orm')) ? 'a UI and a database' : null,
+  'ui-craft': (c) => ROWS.web(c) ?? ROWS['html-ui'](c),
+  cpp: (c) => said(file(c, /\.(?:cc|cpp|cxx|hh|hpp|mm)$/), 'C++ source'),
+  python: (c) => said(file(c, /\.py$/), 'Python source'),
+  go: (c) => said(file(c, /\.go$/), 'Go source'),
+  rust: (c) => said(file(c, /(^|\/)Cargo\.toml$/) ?? file(c, /\.rs$/), 'Rust crate'),
+  midi: (c) => said(file(c, /\.(syx|mid)$|(^|\/)\w*(Midi|MIDI|Sysex|SysEx)\w*\.(h|hpp|cpp|cc)$/), 'MIDI file')
+    ?? said(holds(c, /\.(h|hpp|cpp|cc)$/, /\b(MidiMessage|isController|isNoteOn|getSysExData)\b/), 'MIDI handling'),
+  'sound-design': (c) => said(file(c, /(^|\/)\w*(Voice|Oscillator|Filter|Reverb|Envelope|Lfo|LFO)\w*\.(h|hpp|cpp|cc)$/), 'DSP source'),
+  'reverse-engineering': (c) => said(file(c, /(^|\/)[\w-]*(firmware|disasm|disassembl|x86dis|dis8051|reverse[-_]engineer)[\w-]*\.(md|py)$|(^|\/)[\w.-]+[-_]re\.md$|(^|\/)tools\/re\//i), 'reverse-engineering notes')
+    ?? said(holds(c, /(^|\/)(research|laws|provenance)\.md$/, /\[FW\]/), 'firmware findings'),
+  'instrument-shell': (c) => said(file(c, /(^|\/)PluginEditor\.(h|cpp)$/), 'plugin editor'),
+  'content-site': (c) => said(c.published.find((f) => /\.(md|mdx|html)$/.test(f)) ?? file(c, /(^|\/)sitemap\.xml$/), 'published page'),
+  'dynamic-data': (c) => said(file(c, /(^|[/_-])(cms|entity[-_]?definitions?|field[-_]?configs?|page[-_]?builder|admin[-_]?generator)([/_.-]|$)/i), 'definition-driven file'),
+  ci: (c) => said(file(c, /^\.github\/workflows\/[^/]+\.ya?ml$/), 'workflow'),
+  'http-api': (c) => said(dep(c, 'express', 'fastify', 'koa', 'hono', '@nestjs/core', 'next'), 'dependency') ?? said(file(c, /(^|\/)app\/api\/.*route\.ts$|(^|\/)routes\/[^/]+\.[jt]s$/), 'route file'),
+  react: (c) => said(dep(c, 'react'), 'dependency') ?? said(file(c, /\.[jt]sx$/), 'JSX source'),
+  websocket: (c) => said(dep(c, 'ws', 'socket.io', 'uWebSockets.js', '@fastify/websocket'), 'dependency'),
+  'multi-tenant': (c) => said(file(c, /(^|[/_-])(tenants?|compan(?:y|ies)|organi[sz]ations?|workspaces?)([/_.-]|$)/i), 'tenant file'),
+  'host-agent': (c) => said(dep(c, 'ssh2'), 'dependency') ?? said(file(c, /(^|\/)install[-_]agent|\.service$/), 'agent file'),
+  shell: (c) => said(file(c, /\.(?:sh|bash|zsh)$/), 'shell script'),
+  'audio-core': (c) => said(file(c, /(^|\/)(JuceHeader\.h|.*\.jucer)$/) ?? file(c, /PluginProcessor\.(h|cpp)$/), 'JUCE file'),
+  'gpu-painter': (c) => said(file(c, /\.wgsl$/), 'shader'),
+};
+
+// The configuration of the project: a synth; else the language most of its files are in; else base. full-stack is offered, never assumed: it fixes a folder layout.
+const LEADS = [['cpp', /\.(?:c|cc|cpp|cxx|h|hh|hpp|mm)$/, 'C++ sources'], ['node', /\.(?:ts|tsx|js|jsx|mjs|cjs)$/, 'JS or TS sources'], ['python', /\.py$/, 'Python sources'], ['go', /\.go$/, 'Go sources'], ['rust', /\.rs$|(^|\/)Cargo\.toml$/, 'Rust sources']];
+
+function configFor(ctx) {
+  if (ROWS['audio-core'](ctx)) return { name: 'synth-creator', why: 'JUCE sources' };
+  if (noted(ctx, 'audio-core')) return { name: 'synth-creator', why: 'named in the notes' };
+  const [lead] = LEADS.map(([name, re, why]) => ({ name, why, n: ctx.files.filter((f) => re.test(f)).length })).sort((a, b) => b.n - a.n);
+  return lead.n ? lead : { name: 'base', why: 'no stack the kit has a configuration for' };
+}
+
+const INSTALLED = /(^|\/)(\.claude|node_modules)\//;
+
+// A project that names its configuration has decided; reading the files again can only disagree with it.
+function namedConfig(projectDir) {
+  try {
+    const name = JSON.parse(readFileSync(join(projectDir, '.claude/layout.json'), 'utf8')).configuration;
+    return name && readConfig(name) ? { name, why: 'named in its layout.json' } : null;
+  } catch { return null; }
+}
+
+export function recommend(projectDir, files) {
+  const deps = new Set();
+  for (const f of files.filter((x) => /(^|\/)package\.json$/.test(x))) {
+    const p = join(projectDir, f);
+    if (!existsSync(p)) continue;
+    try {
+      const j = JSON.parse(readFileSync(p, 'utf8'));
+      for (const k of ['dependencies', 'devDependencies', 'peerDependencies']) for (const n of Object.keys(j[k] ?? {})) deps.add(n);
+    } catch { /* a package.json that does not parse says nothing */ }
+  }
+  const own = files.filter((f) => !INSTALLED.test(f)); // the kit's own files and installed dependencies say nothing about the project
+  const ctx = { deps, dir: projectDir, files: own.filter((f) => !isContent(f)), published: own.filter(isContent) };
+  ctx.early = !LEADS.some(([, re]) => ctx.files.some((f) => re.test(f)));
+  const { name, why } = namedConfig(projectDir) ?? configFor(ctx);
+  const config = readConfig(name);
+  const packs = [];
+  const leftOut = [];
+  for (const pack of config.packs.choose) {
+    const found = ROWS[pack]?.(ctx) ?? noted(ctx, pack);
+    if (found) packs.push({ pack, why: found });
+    else leftOut.push(pack);
+  }
+  const fullStack = dep(ctx, 'next') && dep(ctx, 'fastify');
+  return { config: name, why, always: config.packs.always, packs, leftOut, early: ctx.early, fullStack: Boolean(fullStack) };
+}