@warnyin/sdlc 0.8.0 → 0.10.0

package/lib/lenses.mjs

@@ -1,48 +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;
-}
+// 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 };
+}