@warnyin/sdlc 0.5.2 → 0.7.0

package/lib/journal.mjs

@@ -0,0 +1,128 @@
+// Journal residency — where a change's telemetry lives, and how the two possible
+// streams are read back as one.
+//
+// Telemetry is appended by hooks on their own schedule, so it must never live in a
+// version-controlled file: a session would dirty the tree by merely running, and two
+// people on one change would conflict on the appended tail. While a change is open it
+// goes to `sdlc/.state/journal/<id>.ndjson` — `.state/` is gitignored in every
+// installed project — and `archive` seals it into the shipped change folder, one
+// write, at ship. Projects installed before this carry a legacy in-tree journal; it is
+// still read, and consumed at ship.
+//
+// Shared by the CLI, the report builder and the installed hooks, so `node:*` only.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Windows resolves these to devices no matter what extension follows, so a write to
+// `COM1.ndjson` goes to a serial port rather than a file.
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+
+// A change id reaches the path builder from `sdlc/.state/active.json` and from CLI
+// argv — both user-writable. An id that is not a single safe path segment is refused
+// outright rather than normalized: normalizing invites a `..` to be resolved into a
+// write outside `.state/`, and there is no legitimate id that needs it.
+//
+// The Windows-specific rejections are not hypothetical for a CLI that installs itself
+// into other people's checkouts: `:` makes NTFS treat the rest as an alternate data
+// stream (`foo:bar.ndjson` writes a hidden stream on `foo`, invisible to a directory
+// listing), and a trailing dot or space is stripped silently, so `add-2fa.` would
+// alias onto the real `add-2fa` change and fold one change's telemetry into another's.
+export function isSafeChangeId(id) {
+  return typeof id === 'string'
+    && id.length > 0
+    && id.length <= 100
+    && id !== '.'
+    && id !== '..'
+    && !id.includes('\0')
+    && !/[/\\:]/.test(id)
+    && !/[. ]$/.test(id)
+    && !WINDOWS_RESERVED.test(id);
+}
+
+// The stream a session appends to while the change is open. `null` for an unsafe id,
+// so callers fall back to the global journal instead of writing somewhere surprising.
+export function liveJournalPath(sdlcRoot, changeId) {
+  if (!isSafeChangeId(changeId)) return null;
+  return path.join(sdlcRoot, '.state', 'journal', `${changeId}.ndjson`);
+}
+
+// Events with no change to attribute them to.
+export function globalJournalPath(sdlcRoot) {
+  return path.join(sdlcRoot, '.state', 'journal.ndjson');
+}
+
+// Where projects installed before this change already have telemetry. Read-only as far
+// as new events are concerned — nothing appends here any more.
+export function legacyJournalPath(sdlcRoot, changeId) {
+  if (!isSafeChangeId(changeId)) return null;
+  return path.join(sdlcRoot, 'changes', changeId, 'journal.ndjson');
+}
+
+// The sealed journal inside a shipped change folder.
+export function sealedJournalPath(changeDir) {
+  return path.join(changeDir, 'journal.ndjson');
+}
+
+// One malformed line must not cost the rest of the stream: telemetry is best-effort
+// evidence, and a truncated tail from a killed process is a normal way to find it.
+export function parseJournal(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const event = JSON.parse(trimmed);
+      if (event && typeof event === 'object') out.push(event);
+    } catch { /* skip the line, keep the stream */ }
+  }
+  return out;
+}
+
+export function readJournalFile(p) {
+  if (!p || !fs.existsSync(p)) return [];
+  try {
+    return parseJournal(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+// Merge two streams by recorded time. The sort is stable and the tie-break is explicit
+// — equal timestamps keep stream order (`older` first), then file order — so the sealed
+// journal is byte-identical whatever order the reads happened in.
+export function mergeByTime(older, newer) {
+  const decorated = [];
+  [older, newer].forEach((events, stream) => {
+    events.forEach((event, position) => decorated.push({ event, stream, position }));
+  });
+  decorated.sort((a, b) => {
+    const at = typeof a.event.ts === 'string' ? a.event.ts : '';
+    const bt = typeof b.event.ts === 'string' ? b.event.ts : '';
+    if (at !== bt) return at < bt ? -1 : 1;
+    if (a.stream !== b.stream) return a.stream - b.stream;
+    return a.position - b.position;
+  });
+  return decorated.map((d) => d.event);
+}
+
+// Everything recorded for an open change, legacy first so it wins a timestamp tie —
+// it is by definition the older stream.
+export function readChangeJournal(sdlcRoot, changeId) {
+  return mergeByTime(
+    readJournalFile(legacyJournalPath(sdlcRoot, changeId)),
+    readJournalFile(liveJournalPath(sdlcRoot, changeId)),
+  );
+}
+
+// Always `\n`: a legacy journal checked out on Windows can arrive with CRLF, and the
+// sealed file is committed — mixing endings there would churn every diff after it.
+export function serializeJournal(events) {
+  if (!events.length) return '';
+  return events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+}
+
+export function appendEvent(filePath, event) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, JSON.stringify(event) + '\n');
+}

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/observe.mjs

@@ -5,17 +5,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseFrontmatter } from './frontmatter.mjs';
 import { CAPS, countEffectiveLines } from './caps.mjs';
-
-function readJournal(dir) {
-  const p = path.join(dir, 'journal.ndjson');
-  if (!fs.existsSync(p)) return [];
-  return fs.readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
-    try { return JSON.parse(l); } catch { return null; }
-  }).filter(Boolean);
+import { readChangeJournal, readJournalFile, sealedJournalPath, globalJournalPath } from './journal.mjs';
+
+// An open change's telemetry lives out of tree (plus a legacy in-tree stream in
+// projects installed before that); a shipped one carries its sealed journal in the
+// archived folder. Reading only the folder would report an open change as having done
+// nothing, which reads as a quiet change rather than as a broken reader.
+//
+// `id` means different things on the two branches — a change id when open, the dated
+// archive folder name when shipped — so the directory is derived here rather than
+// passed in, and the layout rule stays in one place.
+function changeEvents(sdlcRoot, id, archived) {
+  if (archived) return readJournalFile(sealedJournalPath(path.join(sdlcRoot, 'changes', 'archive', id)));
+  return readChangeJournal(sdlcRoot, id);
 }
 
-function summarizeChange(dir, id, archived) {
-  const events = readJournal(dir);
+function summarizeChange(sdlcRoot, dir, id, archived) {
+  const events = changeEvents(sdlcRoot, id, archived);
   const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
   let costUsd = 0;
   let costKnown = false;
@@ -76,13 +82,13 @@ export function buildReport(sdlcRoot) {
   if (fs.existsSync(changesDir)) {
     for (const d of fs.readdirSync(changesDir, { withFileTypes: true })) {
       if (!d.isDirectory() || d.name === 'archive') continue;
-      changes.push(summarizeChange(path.join(changesDir, d.name), d.name, false));
+      changes.push(summarizeChange(sdlcRoot, path.join(changesDir, d.name), d.name, false));
     }
     const archiveDir = path.join(changesDir, 'archive');
     if (fs.existsSync(archiveDir)) {
       for (const d of fs.readdirSync(archiveDir, { withFileTypes: true })) {
         if (!d.isDirectory()) continue;
-        changes.push(summarizeChange(path.join(archiveDir, d.name), d.name, true));
+        changes.push(summarizeChange(sdlcRoot, path.join(archiveDir, d.name), d.name, true));
       }
     }
   }
@@ -96,17 +102,14 @@ export function buildReport(sdlcRoot) {
   const steering = [];
   const pointerHits = new Map();
   for (const c of changes) {
-    const dir = c.archived
-      ? path.join(sdlcRoot, 'changes', 'archive', c.id)
-      : path.join(sdlcRoot, 'changes', c.id);
-    for (const e of readJournal(dir)) {
+    for (const e of changeEvents(sdlcRoot, c.id, c.archived)) {
       if (e.event === 'pointer' && e.steering) {
         pointerHits.set(e.steering, (pointerHits.get(e.steering) ?? 0) + 1);
       }
     }
   }
   // Global journal (events with no active change) counts too.
-  for (const e of readJournal(path.join(sdlcRoot, '.state'))) {
+  for (const e of readJournalFile(globalJournalPath(sdlcRoot))) {
     if (e.event === 'pointer' && e.steering) {
       pointerHits.set(e.steering, (pointerHits.get(e.steering) ?? 0) + 1);
     }

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 };
+}