chore: update vendored skills and record provenance

humanizer 2.2.0 -> 2.9.1 (blader/humanizer, MIT): adds a Voice Calibration section and a passive-voice pattern, reworks negative parallelisms and em dashes. Version moved to metadata.version upstream. impeccable 3.6.0 -> 4.0.4 (pbakaus/impeccable, Apache-2.0): the repo tags the skill and the npm CLI separately, so 3.6.0 was a real release and npm's 3.5.0 was never the comparison. Adds native-platform reference briefs. Each now carries an UPSTREAM file; bin/check-vendored.sh reports drift.
2026-08-01 14:25:26 +00:00
parent 2f7f512cec
commit 9023ed3ef9
144 changed files with 28302 additions and 5511 deletions
@@ -0,0 +1,197 @@
+/**
+ * Crash-safe injection journal.
+ *
+ * Injection writes into the user's source tree: generated components, a Nuxt
+ * client plugin, marker blocks inside a layout, a patched CSP meta tag. The
+ * clean path removes all of it on stop. The unclean paths do not:
+ *
+ *   - the dev server is SIGKILLed, so `--remove` never runs;
+ *   - the project changes shape between start and stop (a nuxt.config appears,
+ *     a package.json is edited), so detection resolves a different framework
+ *     and the old framework's artifacts are nobody's business;
+ *   - stop runs from a different directory than start did.
+ *
+ * So every inject records what it wrote to `.impeccable/live/inject-journal.json`
+ * before the next one runs, and both inject and `--remove` reconcile that
+ * record against the tree.
+ *
+ * **The journal is a claim of ownership, not a to-do list.** Healing an
+ * artifact only ever removes what still carries our marker; a generated file
+ * the user has since replaced, or a layout they have since un-patched by hand,
+ * is dropped from the journal untouched.
+ *
+ * **Path resolution is appRoot-relative.** Live entry scripts chdir onto the
+ * roots manifest (`enterLiveRoot`) before doing anything, so a journal written
+ * by a session started in the app root is found by a stop issued from any
+ * directory inside the repo.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { PATCH_UNDOERS } from './index.mjs';
+
+export const INJECT_JOURNAL_VERSION = 1;
+export const INJECT_JOURNAL_RELPATH = '.impeccable/live/inject-journal.json';
+
+export function injectJournalPath(cwd = process.cwd()) {
+  return path.join(cwd, ...INJECT_JOURNAL_RELPATH.split('/'));
+}
+
+export function readInjectJournal(cwd = process.cwd()) {
+  const file = injectJournalPath(cwd);
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.artifacts)) return null;
+  return raw;
+}
+
+export function clearInjectJournal(cwd = process.cwd()) {
+  try { fs.unlinkSync(injectJournalPath(cwd)); } catch { /* already gone */ }
+}
+
+function writeInjectJournal(cwd, journal) {
+  const file = injectJournalPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(journal, null, 2) + '\n', 'utf-8');
+  return file;
+}
+
+/**
+ * Record the artifacts an injection just wrote. Replaces any previous record:
+ * callers heal first (see healInjectJournal), so nothing survivable is lost.
+ */
+export function recordInjection(cwd = process.cwd(), { framework, port, artifacts = [] } = {}) {
+  if (!artifacts.length) {
+    clearInjectJournal(cwd);
+    return null;
+  }
+  return writeInjectJournal(cwd, {
+    version: INJECT_JOURNAL_VERSION,
+    appRoot: path.resolve(cwd),
+    framework: framework || null,
+    port: Number.isFinite(Number(port)) ? Number(port) : null,
+    pid: process.pid,
+    recordedAt: new Date().toISOString(),
+    artifacts,
+  });
+}
+
+function normalizeRel(cwd, rel) {
+  return path.resolve(cwd, String(rel || '')).split(path.sep).join('/');
+}
+
+function readIfPresent(abs) {
+  try {
+    return fs.readFileSync(abs, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function pruneEmptyDirs(dir, stopDir) {
+  let current = path.resolve(dir);
+  const stop = path.resolve(stopDir);
+  while (current !== stop && current.startsWith(stop + path.sep)) {
+    try {
+      if (fs.readdirSync(current).length > 0) return;
+      fs.rmdirSync(current);
+    } catch {
+      return;
+    }
+    current = path.dirname(current);
+  }
+}
+
+function insideProject(cwd, abs) {
+  const rel = path.relative(path.resolve(cwd), path.resolve(abs));
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function healArtifact(cwd, artifact, undoers) {
+  const abs = path.resolve(cwd, artifact.path);
+  // The journal is a project-local file, i.e. attacker-writable input in a
+  // cloned repo. Never touch anything outside the project tree, whatever the
+  // journal claims to own.
+  if (!insideProject(cwd, abs)) return { path: artifact.path, action: 'refused_outside_project' };
+  const content = readIfPresent(abs);
+  if (content === null) return { path: artifact.path, action: 'absent' };
+
+  if (artifact.kind === 'created') {
+    // Only reclaim a generated file that still carries our marker; a created
+    // artifact with no marker at all is unverifiable and stays untouched.
+    if (!artifact.marker || !content.includes(artifact.marker)) {
+      return { path: artifact.path, action: 'disowned' };
+    }
+    try { fs.rmSync(abs, { force: true }); } catch { return null; }
+    if (artifact.pruneTo !== undefined) {
+      const pruneRoot = path.resolve(cwd, artifact.pruneTo || '.');
+      if (insideProject(cwd, pruneRoot) || pruneRoot === path.resolve(cwd)) {
+        pruneEmptyDirs(path.dirname(abs), pruneRoot);
+      }
+    }
+    return { path: artifact.path, action: 'removed' };
+  }
+
+  if (artifact.kind === 'patched') {
+    const markers = Array.isArray(artifact.markers) ? artifact.markers : [];
+    // No marker left means the patch is already gone; never run an undo over
+    // a file we no longer recognize (the undoers normalize whitespace).
+    if (markers.length && !markers.some((marker) => content.includes(marker))) {
+      return { path: artifact.path, action: 'disowned' };
+    }
+    const undo = undoers[artifact.patch];
+    if (typeof undo !== 'function') return null;
+    const next = undo(content);
+    if (next === content) return { path: artifact.path, action: 'disowned' };
+    try { fs.writeFileSync(abs, next, 'utf-8'); } catch { return null; }
+    return { path: artifact.path, action: 'unpatched' };
+  }
+
+  return null;
+}
+
+/**
+ * Reconcile the journal against the tree.
+ *
+ * `keep` is the set of paths the current operation legitimately owns — the
+ * artifacts an inject is about to (re)write. Everything else in the journal is
+ * an orphan of a session that is gone, and gets healed. This keeps a repeat
+ * inject byte-idempotent: the artifacts it is about to rewrite are kept, not
+ * torn down and rebuilt.
+ *
+ * Returns `{ healed, kept }`. `healed` lists only artifacts whose file was
+ * actually changed or removed, so callers can stay silent when nothing was
+ * orphaned. Idempotent: a second call finds an empty journal.
+ */
+export function healInjectJournal(cwd = process.cwd(), { keep = [], undoers = PATCH_UNDOERS } = {}) {
+  const journal = readInjectJournal(cwd);
+  if (!journal) return { healed: [], kept: [] };
+
+  const keepSet = new Set(keep.map((rel) => normalizeRel(cwd, rel)));
+  const healed = [];
+  const kept = [];
+
+  for (const artifact of journal.artifacts) {
+    if (!artifact || typeof artifact.path !== 'string') continue;
+    if (keepSet.has(normalizeRel(cwd, artifact.path))) {
+      kept.push(artifact);
+      continue;
+    }
+    const outcome = healArtifact(cwd, artifact, undoers);
+    if (outcome && (outcome.action === 'removed' || outcome.action === 'unpatched')) {
+      healed.push(outcome);
+    }
+  }
+
+  if (kept.length) {
+    writeInjectJournal(cwd, { ...journal, artifacts: kept });
+  } else {
+    clearInjectJournal(cwd);
+  }
+
+  return { healed, kept };
+}