@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/lib/fix-plan.mjs

@@ -0,0 +1,71 @@
+// claude-packs fix: a scan's findings as a work order Claude can follow, step by step, with the kit's own laws. Each finding is a box to tick,
+// in the order a senior engineer would fix them: what can leak first, what loses data next, then the copies, then the rest.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { scan } from './scan.mjs';
+
+const CLI = 'npx --no-install @thedecipherist/claude-packs';
+const pointerOf = (dir) => join(tmpdir(), `claude-packs-last-scan-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 12)}`);
+export const rememberScan = (dir, json) => writeFileSync(pointerOf(dir), json);
+
+const box = (text) => `- [ ] ${text}`;
+const code = (text) => `\`${String(text).replace(/`/g, "'")}\``;
+
+function checksOf(results, kind) {
+  return results.filter((r) => r.kind === kind).sort((a, b) => b.hits.length - a.hits.length)
+    .flatMap((r) => [`### ${r.id} (${r.hits.length})`, '', r.why, r.rule ? `Law: \`${r.rule}\`` : '', '', ...r.hits.map((h) => box(`${h.file}:${h.line}: ${code(h.text)}`)), ''].filter((l, i, a) => l !== '' || a[i - 1] !== ''));
+}
+
+const section = (title, intro, lines) => (lines.length ? [`## ${title}`, '', intro, '', ...lines, ''] : []);
+
+function repeatBox(r) {
+  const differs = r.parameters?.length ? ` Differs in: ${r.parameters.map(code).join(', ')}.` : '';
+  return box(`${r.copies} copies of ${r.what}: ${r.at.join(', ')}. Make it ${r.template}.${differs}`);
+}
+
+export function planText(dir, s) {
+  const packs = [...(s.pick?.packs ?? []).map((p) => p.pack)];
+  const howMany = (s.secrets?.length ?? 0) + (s.results ?? []).reduce((n, r) => n + r.hits.length, 0) + (s.repeats?.length ?? 0) + (s.near?.length ?? 0) + (s.remade?.length ?? 0) + (s.longFiles?.length ?? 0);
+  return [
+    '# Fix plan', '',
+    `A work order from the scan of ${dir}: ${howMany} finding(s). Work it from the top; each box is one fix. Skill: \`fix-from-scan\`.`, '',
+    '## How to work this plan', '',
+    '- A finding is a candidate, not a fact. Read the code first. If it is not real, tick the box and say why on its line.',
+    '- One work branch per section, pushed from its first commit. Commit each fix by name.',
+    '- A bug gets a failing test first (`bug-fix-starts-red`). Run only the tests a change reaches; the whole suite once, when the section is done, then land it.',
+    '- Never change a behaviour to quiet a finding. Ask when the fix would change what users see.', '',
+    '## 0. Install the kit', '',
+    box(`${CLI} init --auto${s.pick?.config ? ` (configuration ${s.pick.config}${packs.length ? `, packs ${packs.join(', ')}` : ''})` : ''}`),
+    box('Fit `.claude/layout.json` to the project, then run `doctor --strict`'), '',
+    ...section('1. Secrets', 'Any that is real has leaked: rotate it first, then move it to an ignored `.env` and read it by name.', (s.secrets ?? []).map((x) => box(`${x.file}:${x.line}: ${x.name}`))),
+    ...section('2. Security', 'What an attacker can reach.', checksOf(s.results ?? [], 'security')),
+    ...section('3. Failures and lost data', 'What breaks in production, or loses work silently.', checksOf(s.results ?? [], 'failures and lost data')),
+    ...section('4. Copies become templates', 'Largest first, with `make-it-a-template`: take the copies out, then write the one template, then test it once.', [
+      ...(s.near ?? []).map((n) => box(`${n.file}:${n.line} is close to ${n.other}:${n.from}-${n.to} (${n.matched} of ${n.of} statements). Make it one function.`)),
+      ...(s.repeats ?? []).map(repeatBox),
+      ...(s.remade ?? []).map((m) => box(`${m.name} is defined ${m.at.length} times: ${m.at.join(', ')}. Keep one and call it, or name each for its job.`)),
+    ]),
+    ...section('5. Quality', 'Group by check: one law, fixed everywhere at once.', checksOf(s.results ?? [], 'quality')),
+    ...section('6. Long files', 'Split by what the code does, so each file has one job.', (s.longFiles ?? []).map((f) => box(f))),
+    ...section('7. Repo weight', 'Move these out of git: to object storage, a release, or the bin.', [...(s.weight?.big ?? []).map((b) => box(`${b.file}: ${b.mb} MB`)), ...(s.weight?.rootImages ?? []).map((f) => box(f))]),
+    ...section('8. Public text', 'Read it as the author. Dates and quotes that are facts stay.', checksOf(s.results ?? [], 'public text')),
+    '## 9. What no check can see', '',
+    box(`Run the review: ${code(`${CLI} scan --prompt`)}. Its findings become boxes here.`), '',
+    '## Done when', '',
+    `Every box is ticked, and ${code(`${CLI} scan`)} finds nothing new. What it still lists has its reason written here.`, '',
+  ].join('\n');
+}
+
+export async function fixPlan(dir, { from = null, out = null, log = console.log } = {}) {
+  const pointer = pointerOf(dir);
+  let json = from ?? (existsSync(pointer) ? readFileSync(pointer, 'utf8').trim() : null);
+  if (!json || !existsSync(json)) json = join((await scan(dir, { log: () => {} })).copy, 'claude-packs-scan.json');
+  const file = out ?? join(dir, '.claude/fix-plan.md');
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, planText(dir, JSON.parse(readFileSync(json, 'utf8'))));
+  log(`Fix plan: ${file}`);
+  log('Give it to Claude: "work through .claude/fix-plan.md" (skill: fix-from-scan).');
+  return file;
+}

package/lib/git-tokens.mjs

@@ -0,0 +1,64 @@
+// Doctor's token sweep (Sub37 WB-3): every git repo that belongs to the project, its nested clones
+// (build/_deps, vendored repos) and the repos in its sibling folders, has its .git/config read for
+// a URL that carries a secret or a bare GitHub token. The token itself is never printed.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const SECRET_URL = /\b[a-z][\w+.-]*:\/\/([^\s/@'"]+)@\S*/gi;
+const SECRET_USER = /:|^(gh[pousr]_|github_pat_|glpat-|x-access-token|oauth2)/i;
+const BARE = /\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_\w{20,})\b/;
+const SKIP = /^(node_modules|\.git|worktrees|\.claude-packs-backup)$/;
+
+function configOf(dir) {
+  const dotGit = join(dir, '.git');
+  try {
+    if (statSync(dotGit).isDirectory()) return join(dotGit, 'config');
+    const gitdir = resolve(dir, readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+)$/m)[1].trim());
+    const common = existsSync(join(gitdir, 'commondir')) ? resolve(gitdir, readFileSync(join(gitdir, 'commondir'), 'utf8').trim()) : gitdir;
+    return join(common, 'config');
+  } catch {
+    return null;
+  }
+}
+
+function repos(dir, depth, out) {
+  if (existsSync(join(dir, '.git'))) out.push(dir);
+  if (depth === 0) return;
+  let entries = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) if (e.isDirectory() && !SKIP.test(e.name)) repos(join(dir, e.name), depth - 1, out);
+}
+
+export function findings(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    const url = [...line.matchAll(SECRET_URL)].find((m) => SECRET_USER.test(m[1]));
+    if (url) out.push(`${line.trim().split(/\s*=/)[0]} = ${url[0].replace(/:\/\/[^@]+@/, '://***@')}`);
+    else if (BARE.test(line)) out.push(`${line.trim().split(/\s*=/)[0]} = (a GitHub token)`);
+  }
+  return out;
+}
+
+export function tokenProblems(projectDir, siblings = []) {
+  const found = [];
+  repos(projectDir, 4, found);
+  for (const s of siblings) {
+    const dir = resolve(projectDir, s);
+    if (!existsSync(dir)) continue;
+    if (existsSync(join(dir, '.git'))) found.push(dir);
+    else repos(dir, 1, found);
+  }
+  const seen = new Set();
+  const problems = [];
+  for (const dir of found) {
+    const cfg = configOf(dir);
+    if (!cfg || !existsSync(cfg)) continue;
+    const real = realpathSync(cfg);
+    if (seen.has(real)) continue;
+    seen.add(real);
+    const hits = findings(readFileSync(cfg, 'utf8'));
+    const name = relative(projectDir, join(dir, '.git', 'config')).replace(/\\/g, '/');
+    if (hits.length) problems.push(`${name} holds a token (${hits.join('; ')}); set the URL back to the plain one and rotate the token`);
+  }
+  return problems;
+}

package/lib/global.mjs

@@ -0,0 +1,125 @@
+// `claude-packs global add|remove|doctor`: the only things this package ever puts in ~/.claude. The global
+// part is exactly three pieces; everything else is per project:
+//   - latest-versions: the skill and its version-pin-guard hook ("check for the newest release" applies to every
+//     project, including new ones with no packs yet);
+//   - gnu-shell and shell-traps. Global by design: they fix this machine's shell for Claude, not any project's rules.
+// Same never-overwrite law as project installs. A hook already there, byte for byte the package's, is taken over, and
+// its settings entry with it, never doubled. The house's hand-installed Python forerunners (~/.claude/hooks/
+// shell-traps.py and gnu-shell.py) lose their settings entries to the Node hooks; their files are left where they are.
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const SRC = fileURLToPath(new URL('../global/', import.meta.url));
+export const FILES = [
+  ['skills/latest-versions/SKILL.md', 'skills/latest-versions/SKILL.md'],
+  ['hooks/version-pin-guard.mjs', 'hooks/claude-packs/version-pin-guard.mjs'],
+  ['hooks/lib/shell-writes.mjs', 'hooks/claude-packs/lib/shell-writes.mjs'],
+  ['hooks/lib/program-writes.mjs', 'hooks/claude-packs/lib/program-writes.mjs'],
+  ['hooks/lib/program-read.mjs', 'hooks/claude-packs/lib/program-read.mjs'],
+  ['hooks/shell-traps.mjs', 'hooks/shell-traps.mjs'],
+  ['hooks/gnu-shell.mjs', 'hooks/gnu-shell.mjs'],
+];
+// Each hook's settings entry.
+const HOOKS = [
+  { rel: 'hooks/claude-packs/version-pin-guard.mjs', event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit|Bash', command: (claude) => `node "${join(claude, 'hooks/claude-packs/version-pin-guard.mjs')}"`, timeout: 10 },
+  { rel: 'hooks/shell-traps.mjs', event: 'PreToolUse', matcher: 'Bash', command: () => 'node "$HOME/.claude/hooks/shell-traps.mjs"', timeout: 10 },
+  { rel: 'hooks/gnu-shell.mjs', event: 'SessionStart', command: () => 'node "$HOME/.claude/hooks/gnu-shell.mjs"', timeout: 10 },
+];
+// The Python forerunners: their settings entries are the package's to replace.
+const FORERUNNERS = ['hooks/shell-traps.py', 'hooks/gnu-shell.py'];
+const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
+
+function paths(home) {
+  const claude = join(home ?? homedir(), '.claude');
+  return { claude, lock: join(claude, 'claude-packs-global.json'), settings: join(claude, 'settings.json') };
+}
+
+function readJson(file, fallback) {
+  if (!existsSync(file)) return fallback;
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch (e) { throw new Error(`${file} is not valid JSON (${e.message}); fix it first, nothing was changed`); }
+}
+
+const ours = (h) => typeof h?.command === 'string' && [...HOOKS.map((x) => x.rel), ...FORERUNNERS].some((rel) => h.command.includes(`.claude/${rel}`));
+
+function writeSettings(file, settings, add, claude) {
+  settings.hooks = { ...(settings.hooks ?? {}) };
+  for (const event of Object.keys(settings.hooks)) {
+    settings.hooks[event] = (settings.hooks[event] ?? []).map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !ours(h)) })).filter((g) => g.hooks.length > 0);
+  }
+  if (add) {
+    for (const h of HOOKS) {
+      const groups = (settings.hooks[h.event] ??= []);
+      let group = groups.find((g) => g.matcher === h.matcher && g._claudePacks);
+      if (!group) groups.push((group = { ...(h.matcher ? { matcher: h.matcher } : {}), _claudePacks: true, hooks: [] }));
+      group.hooks.push({ type: 'command', command: h.command(claude), ...(h.timeout ? { timeout: h.timeout } : {}) });
+    }
+    for (const groups of Object.values(settings.hooks)) for (const g of groups) delete g._claudePacks;
+  }
+  for (const event of Object.keys(settings.hooks)) if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+}
+
+export function globalAdd({ home, force = false, log = console.log } = {}) {
+  const p = paths(home);
+  const settings = readJson(p.settings, {});
+  const lock = readJson(p.lock, { files: {} });
+  for (const [from, to] of FILES) {
+    const src = join(SRC, from);
+    const dest = join(p.claude, to);
+    mkdirSync(dirname(dest), { recursive: true });
+    const theirs = existsSync(dest) && sha(dest) !== sha(src) && lock.files[to] !== sha(dest);
+    if (theirs && !force) {
+      copyFileSync(src, `${dest}.pack-new`);
+      log(`kept your ${to}; the package version is beside it as ${to}.pack-new`);
+      continue;
+    }
+    copyFileSync(src, dest);
+    lock.files[to] = sha(dest);
+  }
+  writeSettings(p.settings, settings, true, p.claude);
+  writeFileSync(p.lock, `${JSON.stringify(lock, null, 2)}\n`);
+  log(`OK: latest-versions (skill and version-pin-guard), gnu-shell and shell-traps installed in ${p.claude}`);
+  return 0;
+}
+
+export function globalRemove({ home, log = console.log } = {}) {
+  const p = paths(home);
+  const settings = readJson(p.settings, {});
+  const lock = readJson(p.lock, { files: {} });
+  for (const [, to] of FILES) {
+    const dest = join(p.claude, to);
+    if (existsSync(dest) && lock.files[to] === sha(dest)) rmSync(dest);
+    else if (existsSync(dest)) log(`kept ${to}: you edited it`);
+  }
+  for (const dir of ['skills/latest-versions', 'hooks/claude-packs/lib', 'hooks/claude-packs']) {
+    const d = join(p.claude, dir);
+    try { rmSync(d, { recursive: false }); } catch { /* not empty or gone */ }
+  }
+  writeSettings(p.settings, settings, false, p.claude);
+  rmSync(p.lock, { force: true });
+  log('OK: global latest-versions removed');
+  return 0;
+}
+
+export function globalDoctor({ home, log = console.log } = {}) {
+  const p = paths(home);
+  const problems = [];
+  for (const [, to] of FILES) if (!existsSync(join(p.claude, to))) problems.push(`missing ${to}`);
+  const settings = readJson(p.settings, {});
+  for (const h of HOOKS) {
+    const wired = (settings.hooks?.[h.event] ?? []).some((g) => (g.hooks ?? []).some((x) => x.command?.includes(`.claude/${h.rel}`)));
+    if (!wired) problems.push(`${h.rel} is not in ~/.claude/settings.json (${h.event})`);
+    const hook = join(p.claude, h.rel);
+    const r = existsSync(hook) && spawnSync(h.rel.endsWith('.py') ? 'python3' : 'node', [hook, '--selftest'], { env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' } });
+    if (r && r.status !== 0) problems.push(`${h.rel} --selftest fails`);
+  }
+  if (problems.length) { problems.forEach((x) => log(`- ${x}`)); return 1; }
+  log('OK: global latest-versions');
+  return 0;
+}

package/lib/hook-proof.mjs

@@ -0,0 +1,28 @@
+// A hook that should refuse and does not (0.18.0: whenever a hook is supposed to exit 2 and it exits 0, it is caught). Only exit 2
+// blocks, so a guard fails open and silently. doctor sees two of the ways: a hook no settings entry runs (dispatch-once was that way for
+// a moment in 0.11.0), and a hook that crashed since it last changed, from its exit code in .claude/hooks.log. A hook killed at its
+// timeout leaves no line and is not seen.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const RUNNER = 'run-hooks.mjs';
+const ANSWERS = new Set(['0', '2', '-', 'undefined', 'null']);
+
+export async function hookProofProblems(projectDir, settingsText) {
+  const dir = join(projectDir, '.claude', 'hooks');
+  if (!existsSync(dir)) return [];
+  const hooks = readdirSync(dir).filter((f) => /\.(mjs|py)$/.test(f) && f !== RUNNER);
+  const problems = hooks.filter((f) => !settingsText.includes(`.claude/hooks/${f}`)).map((f) => `${f} is in .claude/hooks but no settings entry runs it, so it refuses nothing`);
+  const log = join(dir, 'lib', 'hook-log.mjs');
+  if (!existsSync(log)) return problems;
+  const { readHookLog } = await import(pathToFileURL(log).href);
+  const crashed = new Map();
+  for (const row of readHookLog(projectDir, { rotated: true })) {
+    const file = hooks.find((f) => f.replace(/\.(mjs|py)$/, '') === row.hook);
+    if (!file || ANSWERS.has(String(row.code))) continue;
+    if (Date.parse(row.time) > statSync(join(dir, file)).mtimeMs) crashed.set(file, (crashed.get(file) ?? 0) + 1);
+  }
+  for (const [f, n] of crashed) problems.push(`${f} crashed on ${n} call(s) since it last changed: those calls were not judged, and went through (.claude/hooks.log, .claude/logs/)`);
+  return problems;
+}

package/lib/hook-timing.mjs

@@ -0,0 +1,42 @@
+// doctor's hook timing (KWB-24): every hook writes one line per call to .claude/hooks.log (packs/base/hooks/lib/hook-log.mjs,
+// lib/house.py's log_hook); per hook, the median and the worst of its last 100 calls. A hook whose MEDIAN is over 500 ms is a
+// red check: the median is what every call pays, so a slow median is a slow hook. The worst is printed, never judged: one
+// call on a loaded machine, or the once-only index built the first time, is a spike and not the hook's cost. A hook with fewer
+// than MIN_CALLS calls logged is printed, not judged.
+// The runner's own line (run-hooks: one process for a settings entry, node's start-up included) is judged the same way.
+import { readHookLog } from '../packs/base/hooks/lib/hook-log.mjs';
+
+export const SLOW_MS = 500;
+export const LAST = 100;
+export const MIN_CALLS = 3; // one or two calls are not a median: printed, not judged
+
+export function median(values) {
+  const s = [...values].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+
+// -> [{ hook, calls, median, worst }], slowest median first
+export function hookTimes(projectDir, last = LAST) {
+  const by = new Map();
+  for (const r of readHookLog(projectDir)) {
+    if (!by.has(r.hook)) by.set(r.hook, []);
+    by.get(r.hook).push(r.ms);
+  }
+  return [...by].map(([hook, all]) => {
+    const ms = all.slice(-last);
+    return { hook, calls: ms.length, median: median(ms), worst: Math.max(...ms) };
+  }).sort((a, b) => b.median - a.median || a.hook.localeCompare(b.hook));
+}
+
+export function timingProblems(projectDir, log = console.log) {
+  const times = hookTimes(projectDir);
+  if (!times.length) {
+    log('  hook timing: no calls logged yet (.claude/hooks.log fills as the hooks run)');
+    return [];
+  }
+  log(`  hook timing (ms, each hook's last ${LAST} calls at most): ${times.map((t) => `${t.hook} ${t.median}/${t.worst}`).join(', ')} (median/worst)`);
+  return times.filter((t) => t.calls >= MIN_CALLS && t.median > SLOW_MS).map((t) =>
+    `${t.hook}: median ${t.median} ms over its last ${t.calls} calls (worst ${t.worst} ms), over ${SLOW_MS} ms: find what it does on every call ` +
+    '(a scan of the repo, a child process, a whole transcript read) and make it incremental');
+}

package/lib/hover-gate.mjs

@@ -0,0 +1,29 @@
+// 0.10.1 (Stellix B-261): a project with UI code names the gate that proves its hover.
+// layout.json "gates": { "hover": "<command>" }. doctor is red when the hover rule is installed, a file stands under its paths (the
+// ui concept), and no gate is declared; or the command names a file (a word with a "/") that is not there. "none: <reason>" declines.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { projectFiles } from './coverage.mjs';
+
+// One gate: the rule whose paths say where it applies, its key in layout.json "gates", and the skill that builds it.
+async function gateProblems(projectDir, layout, { rule, key, skill }) {
+  const rulesDir = join(projectDir, '.claude', 'rules');
+  const rules = existsSync(rulesDir) ? readdirSync(rulesDir).filter((f) => rule.test(f)) : [];
+  if (!rules.length) return [];
+  const globs = rules.flatMap((f) => [...(readFileSync(join(rulesDir, f), 'utf8').match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '').matchAll(/^\s*-\s*"([^"]+)"/gm)].map((m) => m[1]));
+  if (!globs.length) return [];
+  const { matchesAny } = await import(pathToFileURL(join(projectDir, '.claude', 'hooks', 'lib', 'glob.mjs')).href);
+  const ui = projectFiles(projectDir).filter((f) => matchesAny(f, globs));
+  const gate = layout.gates?.[key];
+  if (typeof gate === 'string' && /^none:\s*\S/.test(gate)) return [];
+  if (ui.length === 0) return []; // no UI code yet: nothing to prove, and a gate named ahead of its file (a profile) is not red
+  const hint = `name it in layout.json as "gates": { "${key}": "<command>" } (the ${skill} skill says how to build it), or "none: <reason>"`;
+  if (typeof gate !== 'string' || !gate.trim() || /^none:/.test(gate)) return [`no ${key} gate declared for the UI code (${ui.slice(0, 3).join(', ')}${ui.length > 3 ? ', …' : ''}): ${hint}`];
+  const missing = gate.split(/\s+/).filter((w) => w.includes('/') && !w.startsWith('-') && !/^[a-z]+:\/\//.test(w)).filter((w) => !existsSync(join(projectDir, w)));
+  return missing.map((w) => `the ${key} gate "${gate}" names ${w}, which is not there`);
+}
+
+export const hoverGateProblems = (projectDir, layout) => gateProblems(projectDir, layout, { rule: /(?:hover-every-pressable|pointer-feedback)\.md$/, key: 'hover', skill: 'hover-state' });
+// 0.17.0: a page is proved rendered (rule page-proved-rendered): the same law for accessibility and layout.
+export const pageGateProblems = (projectDir, layout) => gateProblems(projectDir, layout, { rule: /page-proved-rendered\.md$/, key: 'a11y', skill: 'prove-page' });

package/lib/kit-lock.mjs

@@ -0,0 +1,149 @@
+// The kit lock (.claude-packs-lock at a checkout's root of the claude-packs repo; the repo's own .claude/hooks/kit-lock.mjs
+// takes it, renews it, and refuses another session's commits, merges and releases). Here: its one format, the lease, and
+// `claude-packs lock status|take|release` (KWB-25: a lock left by a gone session could only be released by an rm by hand).
+//   The form: { version: 2, holder: { session, pid }, branch, started_at, last_seen }, with the old keys session and time beside
+//   them so an older kit-lock reads it. The old forms { session, branch, time } and { session, branch } are read too.
+//   The lock is a LEASE (KWB-29): its holder's hook renews last_seen at most once a minute (RENEW_MS) on every
+//   tool call; a holder whose session runs outside the kit (a Stellix lead and its agents, whose hooks are Stellix's) renews it
+//   by working: its transcript, or a subagent's, written later than last_seen counts as seen. No renewal for LEASE_MIN minutes
+//   and the lease is stale: the next session that starts work takes it over, logged in the main checkout's .claude/kit-lock.log
+//   (who held it, branch, since, last seen). A live lease is never taken or deleted; `lock release --force` is the only way.
+//   lock status                     each checkout's lock: holder, branch, held since, last seen, live or stale
+//   lock take [--branch <b>]        take it for CLAUDE_CODE_SESSION_ID (a session whose own hooks are not the kit's)
+//   lock release [--force]          the caller's own lock and stale ones go; another live lease stays (exit 1) unless --force
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const LOCK = '.claude-packs-lock';
+export const LOG = join('.claude', 'kit-lock.log');
+export const LEASE_MIN = 30;
+export const RENEW_MS = 60000;
+const git = (cwd, ...a) => { try { return execFileSync('git', a, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
+const branchOf = (dir) => git(dir, 'symbolic-ref', '--short', 'HEAD') || git(dir, 'rev-parse', '--abbrev-ref', 'HEAD') || '?';
+const ms = (t) => { const v = Date.parse(t ?? ''); return Number.isFinite(v) ? v : null; };
+
+// Every checkout of the repo dir is in: the main one first, then each worktree.
+export function checkouts(root) {
+  const out = git(root, 'worktree', 'list', '--porcelain').split('\n').filter((l) => l.startsWith('worktree ')).map((l) => l.slice(9));
+  return out.length ? out : [root];
+}
+
+// -> { session, pid, branch, startedAt, lastSeen } | null, from any form; a time the lock lacks is null, never undefined
+export function readLock(dir) {
+  let raw;
+  try { raw = JSON.parse(readFileSync(join(dir, LOCK), 'utf8')); } catch { return null; }
+  if (!raw || typeof raw !== 'object') return null;
+  const startedAt = ms(raw.started_at) !== null ? raw.started_at : ms(raw.time) !== null ? raw.time : null;
+  return { session: raw.holder?.session ?? raw.session ?? 'unknown', pid: raw.holder?.pid ?? null, branch: raw.branch ?? '?', startedAt, lastSeen: ms(raw.last_seen) !== null ? raw.last_seen : startedAt };
+}
+
+const write = (dir, l) => writeFileSync(join(dir, LOCK), `${JSON.stringify({ version: 2, holder: { session: l.session, pid: l.pid }, branch: l.branch, started_at: l.startedAt, last_seen: l.lastSeen, session: l.session, time: l.startedAt }, null, 2)}\n`);
+
+export function takeLock(root, session, branch = branchOf(root), pid = Number(process.env.CLAUDE_PID) || null, now = Date.now()) {
+  const at = new Date(now).toISOString();
+  const lock = { session, pid, branch, startedAt: at, lastSeen: at };
+  write(root, lock);
+  return lock;
+}
+
+// The holder's heartbeat: each checkout's lock held by `session` gets last_seen = now, when it is RENEW_MS old or more.
+export function renew(dirs, session, now = Date.now()) {
+  let renewed = false;
+  for (const d of dirs) {
+    const l = readLock(d);
+    if (!l || l.session !== session || (ms(l.lastSeen) !== null && now - ms(l.lastSeen) < RENEW_MS)) continue;
+    write(d, { ...l, startedAt: l.startedAt ?? new Date(now).toISOString(), lastSeen: new Date(now).toISOString() });
+    renewed = true;
+  }
+  return renewed;
+}
+
+// The latest write of the session's transcript or one of its subagents' (~/.claude/projects/<p>/<session>[.jsonl|/subagents/]).
+export function transcriptSeen(session, home = homedir()) {
+  const projects = join(home, '.claude', 'projects');
+  let latest = null;
+  const see = (f) => { try { latest = Math.max(latest ?? 0, statSync(f).mtimeMs); } catch { /* none */ } };
+  let dirs = [];
+  try { dirs = readdirSync(projects); } catch { /* no transcripts */ }
+  for (const d of dirs) {
+    see(join(projects, d, `${session}.jsonl`));
+    const sub = join(projects, d, session, 'subagents');
+    let files = [];
+    try { files = readdirSync(sub); } catch { /* none */ }
+    for (const f of files) if (f.endsWith('.jsonl')) see(join(sub, f));
+  }
+  return latest;
+}
+
+// -> { live, seenAt, why }
+export function liveness(lock, home = homedir(), now = Date.now()) {
+  const lease = ms(lock.lastSeen);
+  const t = transcriptSeen(lock.session, home);
+  const seenAt = Math.max(lease ?? -Infinity, t ?? -Infinity);
+  if (!Number.isFinite(seenAt)) return { live: false, seenAt: null, why: 'never seen (no last_seen, no transcript)' };
+  const age = (now - seenAt) / 60000;
+  const by = t !== null && (lease === null || t > lease) ? 'its transcript' : 'its lease';
+  return { live: age < LEASE_MIN, seenAt, why: `last seen ${new Date(seenAt).toISOString()}, ${age.toFixed(0)} min ago, by ${by}` };
+}
+
+export const describe = (lock, l) => `held by session ${lock.session} (branch ${lock.branch}, held since ${lock.startedAt ?? 'start unknown'}; ${l.why}): ` +
+  (l.live ? 'live' : `stale (no renewal for ${LEASE_MIN} min)`);
+
+// A stale lease out, the taker's in, the take-over logged in the main checkout's .claude/kit-lock.log.
+export function takeOver(root, where, lock, l, session, now = Date.now()) {
+  const main = checkouts(root)[0];
+  mkdirSync(join(main, '.claude'), { recursive: true });
+  appendFileSync(join(main, LOG), `${new Date(now).toISOString()} took over ${join(where, LOCK)}: ${describe(lock, l)}; by session ${session}\n`);
+  rmSync(join(where, LOCK), { force: true });
+}
+
+// The lock for `session` in checkout `dir`: its own already, none (taken), or a stale one (taken over). Another live lease:
+// { held: { lock, where, l } } and nothing is changed.
+export function acquire(dir, session, { home = homedir(), now = Date.now(), branch } = {}) {
+  const locks = checkouts(dir).map((where) => ({ where, lock: readLock(where) })).filter((x) => x.lock);
+  const mine = locks.find((x) => x.lock.session === session);
+  if (mine) return { mine: mine.where };
+  // The same claude process under a new session id (a reload) is its own holder, never another session (KWB-40).
+  const pid = Number(process.env.CLAUDE_PID) || null;
+  const own = pid && locks.find((x) => x.lock.pid === pid);
+  if (own) { takeLock(own.where, session, own.lock.branch, pid, now); return { mine: own.where }; }
+  const others = locks.map((x) => ({ ...x, l: liveness(x.lock, home, now) }));
+  const live = others.find((x) => x.l.live);
+  if (live) return { held: live };
+  for (const x of others) takeOver(dir, x.where, x.lock, x.l, session, now);
+  return { took: takeLock(dir, session, branch ?? branchOf(dir), undefined, now) };
+}
+
+export function lockCommand(sub, dir, { force = false, branch, session = process.env.CLAUDE_CODE_SESSION_ID ?? null, home = homedir(), log = console.log } = {}) {
+  if (!['status', 'take', 'release'].includes(sub)) throw new Error('use `lock status`, `lock take [--branch <b>]` or `lock release [--force]`');
+  if (sub === 'take') {
+    if (!session) { log('no CLAUDE_CODE_SESSION_ID: run it from the session that takes the lock'); return 1; }
+    const r = acquire(dir, session, { home, branch });
+    if (r.held) { log(`kept ${join(r.held.where, LOCK)}: ${describe(r.held.lock, r.held.l)}. Ask the user; --force on release is the only way to remove a live lease`); return 1; }
+    log(r.mine ? `already yours: ${join(r.mine, LOCK)}` : `took ${join(dir, LOCK)} for session ${session} (branch ${r.took.branch})`);
+    return 0;
+  }
+  let code = 0;
+  let any = false;
+  for (const c of checkouts(dir)) {
+    const lock = readLock(c);
+    if (!lock) continue;
+    any = true;
+    const l = liveness(lock, home);
+    const where = join(c, LOCK);
+    if (sub === 'status') { log(`${where}: ${describe(lock, l)}`); continue; }
+    const mine = session && lock.session === session;
+    if (mine || !l.live || force) {
+      if (!mine && !l.live) takeOver(dir, c, lock, l, `${session ?? 'unknown'} (lock release)`);
+      rmSync(where, { force: true });
+      log(`released ${where}: ${describe(lock, l)}${mine ? ' (your own)' : !l.live ? '' : ' (--force)'}`);
+    } else {
+      log(`kept ${where}: session ${lock.session} is live (${l.why}). It is another session's lease: wait for its release or for it to go stale (${LEASE_MIN} min without renewal), or ask the user; --force is the only way to release a live lease`);
+      code = 1;
+    }
+  }
+  if (!any) log('no kit lock in any checkout');
+  return code;
+}

package/lib/layout.mjs

@@ -0,0 +1,75 @@
+// Builds .claude/layout.json from the installed packs, keeping every edit the user made.
+// The layout may also hold (all project-owned, never overwritten by an update):
+//   "files":     { alias: path }      special files that checks refer to as "@alias"
+//   "protected": [globs]              extra read-only paths (vendored copies)
+//   "buildOutput": [globs]            the build output (default build/**); read-only, as vendored code
+//   "writeOnce": [globs]              evidence: a new file may be added, an existing one never changed or removed (KWB-21)
+//   "keepWorktrees": [names]          agent worktrees build-sweep never sweeps (the build the user plays)
+//   "disable":   ["checks/x.json", "hooks/y.mjs", "rules/z.md", "skills/w"]   pack items this project replaces with its own
+//   "commands":  { name: "shell command" }   how this project builds, tests and benches (skills use these)
+//   "paramIds":  { "extensions", "patterns" }   where param-id-lock reads parameter ids (default: JUCE ParameterID literals)
+//   "enable":    ["hooks/x.py", "checks/y.json"]   pack items this project switches on: opt-in hooks, and hooks or
+//                checks a later package version adds to a pack the project already had (see switches.mjs)
+//   "sourceFiles": "<regex>"   what is source to folder-law and doctor (written once from the configuration's; KWB-37)
+//   "gates":    { "hover": "<command>", "a11y": "<command>" }   the gate that proves the UI's hover (doctor is red for UI code without one; "none: <reason>" declines; 0.10.1)
+//   "guards":    { "git", "copy", "time", "browser", "images" }   the project's values for the house guards
+//                (repo owner and token, the sanctioned copy tools, ...); each hook has its defaults
+// A seed layout (a profile, or one written from docs/project.md) is used when no layout exists yet.
+// "configuration" names the project's configuration (lib/configs.mjs); its layout template is read like a pack's folders,
+// before the packs', so a project gets the folder structure of its kind (0.10.0).
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPack } from './packs.mjs';
+
+const OWNED = ['files', 'protected', 'buildOutput', 'writeOnce', 'keepWorktrees', 'disable', 'enable', 'commands', 'siblings', 'maxFileLines', 'paramIds', 'guards', 'sourceFiles', 'gates'];
+// "complete": true marks a tailored layout; see below.
+
+export function buildLayout(claudeDir, packNames, seed = null, config = null) {
+  const file = join(claudeDir, 'layout.json');
+  const current = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : (seed ?? {});
+  const layout = {
+    _comment: 'Where everything lives. folders = the folders; kinds = what goes where (CLAUDE.md shows it, placement-law enforces it); concepts = which rules fire where. Edit here, then run `npx --no-install @thedecipherist/claude-packs update`.',
+    ...(config ? { configuration: config.name } : current.configuration ? { configuration: current.configuration } : {}),
+    folders: { ...(current.folders ?? {}) },
+    concepts: { ...(current.concepts ?? {}) },
+    kinds: { ...(current.kinds ?? {}) },
+  };
+  for (const key of OWNED) {
+    if (current[key] !== undefined) layout[key] = current[key];
+    else if (!['maxFileLines', 'paramIds', 'guards', 'buildOutput', 'writeOnce', 'keepWorktrees', 'sourceFiles', 'gates'].includes(key)) layout[key] = key === 'files' || key === 'commands' ? {} : [];
+  }
+  // A kind's content pattern that is exactly a pattern the pack used to ship ("contentWas") is
+  // replaced by the pack's current one; a pattern the project wrote itself is kept.
+  // "sourceFiles" (what folder-law and doctor count as source; KWB-37) comes from the configuration once, then is the project's
+  if (config?.sourceFiles && layout.sourceFiles === undefined) layout.sourceFiles = config.sourceFiles;
+  const sources = [...(config?.layout ? [config.layout] : []), ...packNames.map(readPack)];
+  for (const pack of sources) {
+    for (const [k, v] of Object.entries(pack.kinds ?? {})) {
+      const mine = layout.kinds[k];
+      if (mine && v.contentWas?.includes(mine.content)) layout.kinds[k] = { ...mine, content: v.content };
+    }
+  }
+  // A layout marked "complete" (a tailored project) gets no default folders from the packs. It
+  // still gains new pack concepts made only of raw globs (no folder names), such as "claude",
+  // so a rule added in a later package version always resolves.
+  if (current.complete) {
+    layout.complete = true;
+    for (const pack of sources) {
+      for (const [k, v] of Object.entries(pack.concepts ?? {})) {
+        if (!layout.concepts[k] && v.every((e) => e.startsWith('kind:') || e.includes('/') || e.includes('*') || e.includes('.'))) layout.concepts[k] = v;
+      }
+    }
+    writeFileSync(file, JSON.stringify(layout, null, 2) + '\n');
+    return layout;
+  }
+  for (const pack of sources) {
+    for (const [k, v] of Object.entries(pack.folders ?? {})) layout.folders[k] ??= v;
+    for (const [k, v] of Object.entries(pack.files ?? {})) layout.files[k] ??= v;
+    for (const [k, { contentWas, ...v }] of Object.entries(pack.kinds ?? {})) layout.kinds[k] ??= v;
+    for (const [k, v] of Object.entries(pack.concepts ?? {})) {
+      if (!current.concepts?.[k]) layout.concepts[k] = [...new Set([...(layout.concepts[k] ?? []), ...v])];
+    }
+  }
+  writeFileSync(file, JSON.stringify(layout, null, 2) + '\n');
+  return layout;
+}