@warnyin/sdlc 0.7.0 → 0.9.0

package/lib/lenses.mjs

@@ -0,0 +1,48 @@
+// Canonical lens list — the single source of truth for which expert lenses a change may
+// record. `payload/playbook/lenses.md` describes each one under `## Lens: <name>`, and
+// tests/lenses.test.mjs fails the build if the two drift.
+//
+// A change records lenses in frontmatter as `<lens>@builtin`, `<lens>@project:<skill>` or
+// `<lens>@user:<skill>`; the skill name uses the inventory's own name rule, so whatever
+// `warnyin-sdlc skills` lists is exactly what a change can record.
+
+// Names are only ever added: removing or renaming one turns open changes that recorded it
+// into validation errors, so that needs a migration, not an edit here.
+//
+// SKILL_NAME_RE is owned here (not by the inventory) so the validator, which hooks load on
+// every write, does not pull in filesystem scanning. `.` and `..` are refused so a recorded
+// name can never be a path hop.
+export const SKILL_NAME_RE = /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,64}$/;
+
+export const LENSES = Object.freeze(['ux-ui', 'api', 'data']);
+
+const ENTRY_RE = /^([^@\s]+)@(builtin|project:(.*)|user:(.*))$/;
+
+// Returns error strings, each naming the offending entry. An absent or empty list is valid:
+// no lens means no stage loads one.
+export function lensErrors(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return [`lenses must be a list, got "${value}"`];
+  const errors = [];
+  const seen = new Set();
+  for (const raw of value) {
+    const entry = String(raw);
+    const m = entry.match(ENTRY_RE);
+    if (!m) {
+      errors.push(`lens entry "${entry}" must be <lens>@builtin, <lens>@project:<skill> or <lens>@user:<skill>`);
+      continue;
+    }
+    const [, lens, , projectSkill, userSkill] = m;
+    const skill = projectSkill ?? userSkill;
+    if (!LENSES.includes(lens)) {
+      errors.push(`lens entry "${entry}" names unknown lens "${lens}" (catalog: ${LENSES.join('|')})`);
+    } else if (seen.has(lens)) {
+      errors.push(`lens "${lens}" is recorded more than once — keep one source per lens`);
+    }
+    if (skill !== undefined && !SKILL_NAME_RE.test(skill)) {
+      errors.push(`lens entry "${entry}" has an invalid skill name (allowed: ${SKILL_NAME_RE.source})`);
+    }
+    seen.add(lens);
+  }
+  return errors;
+}

package/lib/manifest.mjs

@@ -1,99 +1,99 @@
-// Manifest + prune guards (ported from the battle-tested warnyin-agents
-// installer). The manifest records sha256 of every payload-owned file so
-// `update` can distinguish ours-unmodified (refresh), ours-modified-by-user
-// (keep + warn), and stale (prune with guards).
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-export const PRUNE_BLAST_CAP = 50;
-
-// Payload-owned roots — prune may only ever touch paths under these.
-const PRUNABLE_PREFIXES = [
-  'sdlc/.playbook/',
-  'sdlc/.hooks/',
-  '.claude/commands/sdlc/',
-];
-const AGENT_ALLOW_RE = /^\.claude\/agents\/sdlc-[^/]+\.md$/;
-const SKILL_ALLOW_RE = /^\.claude\/skills\/(delta-spec-format|contract-writing|sdlc-conventions)\/[^/]+$/;
-const ADAPTER_ALLOW = new Set([
-  '.cursor/rules/sdlc.mdc',
-  '.windsurf/rules/sdlc.md',
-]);
-
-export function parseManifest(text) {
-  const map = new Map();
-  for (const line of (text ?? '').split(/\r?\n/)) {
-    if (!line.trim() || line.startsWith('#')) continue;
-    const m = line.match(/^([a-f0-9]{64})\s{2}(.+)$/);
-    if (!m) continue;
-    map.set(m[2], m[1]);
-  }
-  return map;
-}
-
-export function renderManifest(map) {
-  const lines = ['# @warnyin/sdlc manifest — sha256  path (posix, relative to project root)'];
-  for (const [p, hash] of [...map.entries()].sort()) lines.push(`${hash}  ${p}`);
-  return lines.join('\n') + '\n';
-}
-
-// Guard 1: structural path safety (manifest is data — never trust it blindly).
-export function isSafeRelPath(relPosix) {
-  if (typeof relPosix !== 'string' || relPosix === '') return false;
-  if (relPosix.includes('\\') || relPosix.startsWith('/') || /^[A-Za-z]:/.test(relPosix)) return false;
-  if (/[\u0000-\u001f]/.test(relPosix)) return false;
-  const segments = relPosix.split('/');
-  return segments.every((s) => s !== '' && s !== '.' && s !== '..');
-}
-
-// Guard 2: scope — only payload-owned locations are ever prunable.
-export function isPrunablePath(relPosix) {
-  if (!isSafeRelPath(relPosix)) return false;
-  if (PRUNABLE_PREFIXES.some((p) => relPosix.startsWith(p))) return true;
-  if (AGENT_ALLOW_RE.test(relPosix)) return true;
-  if (SKILL_ALLOW_RE.test(relPosix)) return true;
-  if (ADAPTER_ALLOW.has(relPosix)) return true;
-  return false;
-}
-
-// Stale = in the old manifest but absent from the new payload set.
-// Every candidate must pass path + scope guards; the caller additionally
-// checks hash-match-on-disk and realpath containment before deleting.
-export function computeStale(oldManifest, newPaths) {
-  const stale = [];
-  const rejected = [];
-  for (const [relPath, hash] of oldManifest.entries()) {
-    if (newPaths.has(relPath)) continue;
-    if (!isPrunablePath(relPath)) {
-      rejected.push({ path: relPath, reason: 'outside prunable scope' });
-      continue;
-    }
-    stale.push({ path: relPath, hash });
-  }
-  return { stale, rejected, overCap: stale.length > PRUNE_BLAST_CAP };
-}
-
-export function containedIn(rootAbs, targetAbs) {
-  const rel = path.relative(rootAbs, targetAbs);
-  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
-}
-
-// Guard: no path segment between root and target may be a symlink. Without
-// this, a symlinked ancestor inside a prunable prefix redirects the delete to
-// whatever real file it points at (arbitrary-deletion class — the manifest is
-// untrusted, user-writable input).
-export function hasSymlinkSegment(rootAbs, targetAbs) {
-  const rel = path.relative(rootAbs, targetAbs);
-  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return true; // suspicious → treat as unsafe
-  let cur = rootAbs;
-  for (const seg of rel.split(path.sep)) {
-    cur = path.join(cur, seg);
-    try {
-      if (fs.lstatSync(cur).isSymbolicLink()) return true;
-    } catch {
-      return false; // component missing — nothing to follow
-    }
-  }
-  return false;
-}
+// Manifest + prune guards (ported from the battle-tested warnyin-agents
+// installer). The manifest records sha256 of every payload-owned file so
+// `update` can distinguish ours-unmodified (refresh), ours-modified-by-user
+// (keep + warn), and stale (prune with guards).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PRUNE_BLAST_CAP = 50;
+
+// Payload-owned roots — prune may only ever touch paths under these.
+const PRUNABLE_PREFIXES = [
+  'sdlc/.playbook/',
+  'sdlc/.hooks/',
+  '.claude/commands/sdlc/',
+];
+const AGENT_ALLOW_RE = /^\.claude\/agents\/sdlc-[^/]+\.md$/;
+const SKILL_ALLOW_RE = /^\.claude\/skills\/(delta-spec-format|contract-writing|sdlc-conventions)\/[^/]+$/;
+const ADAPTER_ALLOW = new Set([
+  '.cursor/rules/sdlc.mdc',
+  '.windsurf/rules/sdlc.md',
+]);
+
+export function parseManifest(text) {
+  const map = new Map();
+  for (const line of (text ?? '').split(/\r?\n/)) {
+    if (!line.trim() || line.startsWith('#')) continue;
+    const m = line.match(/^([a-f0-9]{64})\s{2}(.+)$/);
+    if (!m) continue;
+    map.set(m[2], m[1]);
+  }
+  return map;
+}
+
+export function renderManifest(map) {
+  const lines = ['# @warnyin/sdlc manifest — sha256  path (posix, relative to project root)'];
+  for (const [p, hash] of [...map.entries()].sort()) lines.push(`${hash}  ${p}`);
+  return lines.join('\n') + '\n';
+}
+
+// Guard 1: structural path safety (manifest is data — never trust it blindly).
+export function isSafeRelPath(relPosix) {
+  if (typeof relPosix !== 'string' || relPosix === '') return false;
+  if (relPosix.includes('\\') || relPosix.startsWith('/') || /^[A-Za-z]:/.test(relPosix)) return false;
+  if (/[\u0000-\u001f]/.test(relPosix)) return false;
+  const segments = relPosix.split('/');
+  return segments.every((s) => s !== '' && s !== '.' && s !== '..');
+}
+
+// Guard 2: scope — only payload-owned locations are ever prunable.
+export function isPrunablePath(relPosix) {
+  if (!isSafeRelPath(relPosix)) return false;
+  if (PRUNABLE_PREFIXES.some((p) => relPosix.startsWith(p))) return true;
+  if (AGENT_ALLOW_RE.test(relPosix)) return true;
+  if (SKILL_ALLOW_RE.test(relPosix)) return true;
+  if (ADAPTER_ALLOW.has(relPosix)) return true;
+  return false;
+}
+
+// Stale = in the old manifest but absent from the new payload set.
+// Every candidate must pass path + scope guards; the caller additionally
+// checks hash-match-on-disk and realpath containment before deleting.
+export function computeStale(oldManifest, newPaths) {
+  const stale = [];
+  const rejected = [];
+  for (const [relPath, hash] of oldManifest.entries()) {
+    if (newPaths.has(relPath)) continue;
+    if (!isPrunablePath(relPath)) {
+      rejected.push({ path: relPath, reason: 'outside prunable scope' });
+      continue;
+    }
+    stale.push({ path: relPath, hash });
+  }
+  return { stale, rejected, overCap: stale.length > PRUNE_BLAST_CAP };
+}
+
+export function containedIn(rootAbs, targetAbs) {
+  const rel = path.relative(rootAbs, targetAbs);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Guard: no path segment between root and target may be a symlink. Without
+// this, a symlinked ancestor inside a prunable prefix redirects the delete to
+// whatever real file it points at (arbitrary-deletion class — the manifest is
+// untrusted, user-writable input).
+export function hasSymlinkSegment(rootAbs, targetAbs) {
+  const rel = path.relative(rootAbs, targetAbs);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return true; // suspicious → treat as unsafe
+  let cur = rootAbs;
+  for (const seg of rel.split(path.sep)) {
+    cur = path.join(cur, seg);
+    try {
+      if (fs.lstatSync(cur).isSymbolicLink()) return true;
+    } catch {
+      return false; // component missing — nothing to follow
+    }
+  }
+  return false;
+}

package/lib/settings-merge.mjs

@@ -1,63 +1,63 @@
-// Non-destructive management of our hook entries inside the project's
-// .claude/settings.json. Ownership marker: any hook command that references
-// `sdlc/.hooks/` is ours; everything else is the user's and is never touched.
-// Merge is idempotent: remove ours, re-add current set, preserve the rest.
-
-const OWNERSHIP_MARKER = 'sdlc/.hooks/';
-
-const hookCmd = (script, extraArgs = '') =>
-  `node "$CLAUDE_PROJECT_DIR/sdlc/.hooks/${script}"${extraArgs ? ' ' + extraArgs : ''}`;
-
-export function sdlcHookEntries() {
-  return {
-    SessionStart: [
-      { hooks: [{ type: 'command', command: hookCmd('inject-context.mjs') }] },
-    ],
-    PreToolUse: [
-      {
-        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
-        hooks: [{ type: 'command', command: hookCmd('guard-writes.mjs') }],
-      },
-    ],
-    PostToolUse: [
-      {
-        matcher: 'Edit|Write|MultiEdit',
-        hooks: [{ type: 'command', command: hookCmd('validate-artifact.mjs') }],
-      },
-    ],
-    Stop: [
-      { hooks: [{ type: 'command', command: hookCmd('session-summary.mjs') }] },
-    ],
-    PreCompact: [
-      { hooks: [{ type: 'command', command: hookCmd('journal.mjs', 'note compact') }] },
-    ],
-  };
-}
-
-function isOurs(matcherEntry) {
-  return (matcherEntry?.hooks ?? []).some(
-    (h) => typeof h?.command === 'string' && h.command.includes(OWNERSHIP_MARKER),
-  );
-}
-
-// settingsJson: parsed object (or {}). Returns a NEW object (immutability).
-export function mergeHookSettings(settingsJson) {
-  const settings = structuredClone(settingsJson ?? {});
-  const hooks = { ...(settings.hooks ?? {}) };
-  for (const [event, entries] of Object.entries(sdlcHookEntries())) {
-    const existing = (hooks[event] ?? []).filter((e) => !isOurs(e));
-    hooks[event] = [...existing, ...entries];
-  }
-  return { ...settings, hooks };
-}
-
-export function removeHookSettings(settingsJson) {
-  const settings = structuredClone(settingsJson ?? {});
-  if (!settings.hooks) return settings;
-  const hooks = {};
-  for (const [event, entries] of Object.entries(settings.hooks)) {
-    const kept = entries.filter((e) => !isOurs(e));
-    if (kept.length) hooks[event] = kept;
-  }
-  return { ...settings, hooks };
-}
+// Non-destructive management of our hook entries inside the project's
+// .claude/settings.json. Ownership marker: any hook command that references
+// `sdlc/.hooks/` is ours; everything else is the user's and is never touched.
+// Merge is idempotent: remove ours, re-add current set, preserve the rest.
+
+const OWNERSHIP_MARKER = 'sdlc/.hooks/';
+
+const hookCmd = (script, extraArgs = '') =>
+  `node "$CLAUDE_PROJECT_DIR/sdlc/.hooks/${script}"${extraArgs ? ' ' + extraArgs : ''}`;
+
+export function sdlcHookEntries() {
+  return {
+    SessionStart: [
+      { hooks: [{ type: 'command', command: hookCmd('inject-context.mjs') }] },
+    ],
+    PreToolUse: [
+      {
+        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+        hooks: [{ type: 'command', command: hookCmd('guard-writes.mjs') }],
+      },
+    ],
+    PostToolUse: [
+      {
+        matcher: 'Edit|Write|MultiEdit',
+        hooks: [{ type: 'command', command: hookCmd('validate-artifact.mjs') }],
+      },
+    ],
+    Stop: [
+      { hooks: [{ type: 'command', command: hookCmd('session-summary.mjs') }] },
+    ],
+    PreCompact: [
+      { hooks: [{ type: 'command', command: hookCmd('journal.mjs', 'note compact') }] },
+    ],
+  };
+}
+
+function isOurs(matcherEntry) {
+  return (matcherEntry?.hooks ?? []).some(
+    (h) => typeof h?.command === 'string' && h.command.includes(OWNERSHIP_MARKER),
+  );
+}
+
+// settingsJson: parsed object (or {}). Returns a NEW object (immutability).
+export function mergeHookSettings(settingsJson) {
+  const settings = structuredClone(settingsJson ?? {});
+  const hooks = { ...(settings.hooks ?? {}) };
+  for (const [event, entries] of Object.entries(sdlcHookEntries())) {
+    const existing = (hooks[event] ?? []).filter((e) => !isOurs(e));
+    hooks[event] = [...existing, ...entries];
+  }
+  return { ...settings, hooks };
+}
+
+export function removeHookSettings(settingsJson) {
+  const settings = structuredClone(settingsJson ?? {});
+  if (!settings.hooks) return settings;
+  const hooks = {};
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    const kept = entries.filter((e) => !isOurs(e));
+    if (kept.length) hooks[event] = kept;
+  }
+  return { ...settings, hooks };
+}

package/lib/skills.mjs

@@ -0,0 +1,148 @@
+// Skill/agent inventory — what expertise is already installed for this project and user.
+// Used by: CLI (`warnyin-sdlc skills`), which the opening playbook reads to resolve lenses.
+//
+// Skill files are third-party content, so the inventory is deliberately shallow: it reads a
+// bounded prefix of each file, keeps only frontmatter `name` + `description`, and never
+// emits body text. Project entries whose real location leaves the project are skipped (a
+// repo can ship a link); the user's own home may link wherever the user put their skills.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+import { containedIn } from './manifest.mjs';
+import { SKILL_NAME_RE } from './lenses.mjs';
+
+export { SKILL_NAME_RE };
+export const INVENTORY_CEILING = 200;
+// Per-directory bound on how many candidates are opened at all: a checked-out repo can plant
+// thousands of folders, and the ceiling alone would still pay to read every one of them.
+export const SCAN_LIMIT_PER_DIR = 1000;
+export const DESCRIPTION_MAX = 160;
+export const READ_PREFIX_BYTES = 8 * 1024;
+
+const KINDS = Object.freeze(['skill', 'agent']);
+// Built from code points so the source file itself carries no invisible characters: C0, DEL,
+// C1, zero-width and bidi marks/overrides, line/paragraph separators, BOM — anything that
+// can move a terminal cursor or visually reorder the line a human or model reads.
+const cp = (n) => String.fromCharCode(n);
+const CONTROL_CHARS = new RegExp(
+  `[${cp(0)}-${cp(0x1f)}${cp(0x7f)}-${cp(0x9f)}${cp(0x200b)}-${cp(0x200f)}${cp(0x2028)}-${cp(0x202e)}${cp(0x2066)}-${cp(0x2069)}${cp(0xfeff)}]+`,
+  'g');
+const LEADING_BOM = new RegExp(`^${String.fromCharCode(0xfeff)}`);
+
+// Reads at most READ_PREFIX_BYTES; a frontmatter that does not close inside that prefix is
+// treated as absent rather than read further. The open is non-blocking where the platform
+// has it, and the descriptor itself must be a regular file, so a FIFO or device swapped in
+// after the earlier checks can neither hang nor feed the read.
+function readPrefix(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+    if (!fs.fstatSync(fd).isFile()) return null;
+    const buf = Buffer.alloc(READ_PREFIX_BYTES);
+    const n = fs.readSync(fd, buf, 0, READ_PREFIX_BYTES, 0);
+    return buf.subarray(0, n).toString('utf8').replace(LEADING_BOM, '');
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+// One line, no control characters (terminal escapes included), cut with a visible marker.
+export function cleanDescription(raw) {
+  const flat = String(raw).replace(CONTROL_CHARS, ' ').replace(/\s+/g, ' ').trim();
+  if (flat.length <= DESCRIPTION_MAX) return { description: flat, truncated: false };
+  return { description: `${flat.slice(0, DESCRIPTION_MAX - 1).trimEnd()}…`, truncated: true };
+}
+
+function readEntry(file) {
+  const text = readPrefix(file);
+  if (text === null) return null;
+  const { data } = parseFrontmatter(text);
+  const name = typeof data.name === 'string' ? data.name.trim() : '';
+  if (!SKILL_NAME_RE.test(name)) return null;
+  if (typeof data.description !== 'string' || data.description.trim() === '') return null;
+  return { name, ...cleanDescription(data.description) };
+}
+
+function isInside(rootReal, target) {
+  try {
+    return containedIn(rootReal, fs.realpathSync.native(target));
+  } catch {
+    return false;
+  }
+}
+
+// The first SCAN_LIMIT_PER_DIR names (sorted), and how many were left unopened.
+function listDir(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir).sort();
+  } catch {
+    return { names: [], unscanned: 0 };
+  }
+  return { names: names.slice(0, SCAN_LIMIT_PER_DIR), unscanned: Math.max(0, names.length - SCAN_LIMIT_PER_DIR) };
+}
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+// Candidate files for one `.claude` root, each paired with every path that must stay contained.
+function candidates(claudeDir, kind) {
+  if (kind === 'skill') {
+    const skillsDir = path.join(claudeDir, 'skills');
+    const { names, unscanned } = listDir(skillsDir);
+    const items = names.map((d) => {
+      const folder = path.join(skillsDir, d);
+      const file = path.join(folder, 'SKILL.md');
+      return { file, checks: [folder, file] };
+    });
+    return { items, unscanned };
+  }
+  const agentsDir = path.join(claudeDir, 'agents');
+  const { names, unscanned } = listDir(agentsDir);
+  const items = names
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => ({ file: path.join(agentsDir, f), checks: [path.join(agentsDir, f)] }));
+  return { items, unscanned };
+}
+
+function scanRoot(claudeDir, source, containRoot) {
+  const entries = [];
+  let unscanned = 0;
+  for (const kind of KINDS) {
+    const found = candidates(claudeDir, kind);
+    unscanned += found.unscanned;
+    for (const { file, checks } of found.items) {
+      if (containRoot && !checks.every((c) => isInside(containRoot, c))) continue;
+      if (!isFile(file)) continue;
+      const entry = readEntry(file);
+      if (entry) entries.push({ source, kind, ...entry });
+    }
+  }
+  entries.sort((a, b) => KINDS.indexOf(a.kind) - KINDS.indexOf(b.kind) || a.name.localeCompare(b.name));
+  return { entries, unscanned };
+}
+
+export function scanInventory(projectRoot, { home = os.homedir() } = {}) {
+  let projectReal = null;
+  try { projectReal = fs.realpathSync.native(projectRoot); } catch { /* unreadable root → no project entries */ }
+  const none = { entries: [], unscanned: 0 };
+  const project = projectReal ? scanRoot(path.join(projectRoot, '.claude'), 'project', projectReal) : none;
+  const user = home ? scanRoot(path.join(home, '.claude'), 'user', null) : none;
+  const all = [...project.entries, ...user.entries];
+  // `omitted` = valid entries past the ceiling + candidates never opened (scan limit).
+  return {
+    entries: all.slice(0, INVENTORY_CEILING),
+    omitted: Math.max(0, all.length - INVENTORY_CEILING) + project.unscanned + user.unscanned,
+  };
+}
+
+export function renderInventory({ entries, omitted }) {
+  const lines = entries.map((e) => `${e.source}  ${e.kind}  ${e.name}  ${e.description}`);
+  if (omitted > 0) lines.push(`… ${omitted} more not listed`);
+  return lines.join('\n');
+}