quiver-cli 1.3.1 → 2.0.0

package/template/.agents/skills/design/impeccable/scripts/critique-storage.mjs

@@ -1,473 +0,0 @@
-#!/usr/bin/env node
-/**
- * Critique persistence helper.
- *
- * Each critique run writes a per-target snapshot to
- *   .impeccable/critique/<timestamp>__<slug>.md
- * with a small YAML frontmatter carrying the score + P0/P1 counts.
- *
- * The polish workflow reads the latest matching snapshot at start as its
- * fix backlog. No other skill auto-reads critique output.
- *
- * The slug is derived mechanically from the *resolved* primary artifact
- * (file path or URL), never from the user's natural-language phrasing.
- * Slug stability across runs is what lets the trend display work.
- *
- * CLI entry points (called from skill instructions):
- *   node critique-storage.mjs slug <resolved-target>
- *   node critique-storage.mjs write <slug> <snapshot-body-file>
- *   node critique-storage.mjs latest <slug> [--json]
- *   node critique-storage.mjs trend <slug> [limit]
- *   node critique-storage.mjs close <resolved-target> <snapshot-file>
- *
- * Note: there is intentionally no `ignore` subcommand. ignore.md is a plain
- * markdown file; the model reads it directly with its file-read tool. This
- * helper only exists for operations the model can't trivially do inline
- * (normalizing paths, generating filenames, globbing + parsing frontmatter).
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { createHash } from 'node:crypto';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { getCritiqueDir } from './lib/impeccable-paths.mjs';
-import { slugFromTarget } from './lib/target-slug.mjs';
-
-export { slugFromTarget } from './lib/target-slug.mjs';
-
-/**
- * Mechanically derive a slug from a resolved target. Returns null if the
- * input doesn't look like a stable identifier (empty, project root, etc).
- *
- * Accepts file paths and URLs. The model resolves "the homepage" to a
- * concrete artifact before calling this — we never slug a natural-language
- * phrase.
- */
-/**
- * Filename-safe UTC ISO timestamp: hyphens for separators, trailing Z.
- * Plain colons aren't allowed on Windows filesystems.
- */
-export function nowFilenameStamp(date = new Date()) {
-  const iso = date.toISOString();           // 2026-05-12T18:30:00.123Z
-  return iso.replace(/[:.]/g, '-').replace(/-\d+Z$/, 'Z');
-}
-
-/**
- * Return an exact content fingerprint for a local file target. URLs and
- * non-files return null because their content is not available here.
- *
- * The fingerprint deliberately describes bytes, not Git state or mtimes:
- * critique often assesses an uncommitted file, and a later polish run should
- * inherit that backlog when the bytes are unchanged regardless of staging.
- */
-function resolveLocalTargetPath(target, { cwd = process.cwd() } = {}) {
-  if (!target || /^https?:\/\//i.test(target)) return null;
-  return path.isAbsolute(target) ? path.resolve(target) : path.resolve(cwd, target);
-}
-
-function resolveTargetIdentity(target, { cwd = process.cwd() } = {}) {
-  if (!target || typeof target !== 'string') return null;
-  if (/^https?:\/\//i.test(target)) {
-    try {
-      const url = new URL(target);
-      const pathname = url.pathname.replace(/\/+$/, '') || '/';
-      return `url:${url.origin}${pathname}`;
-    } catch {
-      return null;
-    }
-  }
-  const filePath = resolveLocalTargetPath(target, { cwd });
-  return filePath ? `file:${filePath}` : null;
-}
-
-export function fingerprintTarget(target, { cwd = process.cwd() } = {}) {
-  const filePath = resolveLocalTargetPath(target, { cwd });
-  if (!filePath) return null;
-  try {
-    if (!fs.statSync(filePath).isFile()) return null;
-    return `sha256:${createHash('sha256').update(fs.readFileSync(filePath)).digest('hex')}`;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Write a snapshot for `slug`. `meta` carries the small structured frontmatter
- * keys read back by readTrend(). `body` is the human-readable critique
- * report (everything below the frontmatter).
- *
- * Returns the absolute path written.
- */
-export function writeSnapshot({ slug, meta, body, cwd = process.cwd(), now = new Date() }) {
-  if (!slug) throw new Error('writeSnapshot requires a slug');
-  const dir = getCritiqueDir(cwd);
-  fs.mkdirSync(dir, { recursive: true });
-  const timestamp = nowFilenameStamp(now);
-  // Spread `meta` first so internally computed `timestamp` and `slug`
-  // always win. Otherwise a caller-supplied meta blob (parsed from the
-  // IMPECCABLE_CRITIQUE_META env var) could clobber them, leaving the
-  // filename in disagreement with its frontmatter and corrupting trends.
-  const front = serializeFrontmatter({ ...meta, timestamp, slug });
-  const contents = `${front}\n${body.trim()}\n`;
-
-  // A second critique can finish in the same UTC second. Use exclusive
-  // creation and a fixed-width suffix so concurrent writers cannot replace
-  // history and lexical ordering still keeps collision entries newest.
-  for (let collision = 0; collision <= 9999; collision += 1) {
-    const suffix = collision === 0 ? '' : `~${String(collision).padStart(4, '0')}`;
-    const filePath = path.join(dir, `${timestamp}${suffix}__${slug}.md`);
-    try {
-      fs.writeFileSync(filePath, contents, { encoding: 'utf-8', flag: 'wx' });
-      return filePath;
-    } catch (error) {
-      if (error?.code !== 'EEXIST') throw error;
-    }
-  }
-  throw new Error(`Too many critique snapshots for ${slug} at ${timestamp}`);
-}
-
-function serializeFrontmatter(obj) {
-  const lines = ['---'];
-  for (const [key, value] of Object.entries(obj)) {
-    if (value === undefined || value === null) continue;
-    const str = typeof value === 'string' ? value : String(value);
-    // Quote strings that contain : or # to keep parsing simple.
-    const needsQuotes = typeof value === 'string' && /[:#]/.test(str);
-    lines.push(`${key}: ${needsQuotes ? JSON.stringify(str) : str}`);
-  }
-  lines.push('---');
-  return lines.join('\n');
-}
-
-function parseFrontmatter(text) {
-  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return {};
-  const out = {};
-  for (const line of match[1].split(/\r?\n/)) {
-    const colon = line.indexOf(':');
-    if (colon < 0) continue;
-    const key = line.slice(0, colon).trim();
-    let value = line.slice(colon + 1).trim();
-    if (/^".*"$/.test(value)) {
-      try { value = JSON.parse(value); } catch { /* leave as-is */ }
-    } else if (/^-?\d+$/.test(value)) {
-      value = Number(value);
-    } else if (value === 'true' || value === 'false') {
-      value = value === 'true';
-    }
-    out[key] = value;
-  }
-  return out;
-}
-
-/**
- * Return snapshot files matching `suffix`, sorted oldest → newest.
- */
-const SNAPSHOT_FILENAME = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z(?:~\d{4})?__.+\.md$/;
-
-function listSnapshots(suffix, cwd) {
-  const dir = getCritiqueDir(cwd);
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir)
-    .filter((f) => SNAPSHOT_FILENAME.test(f) && f.endsWith(suffix))
-    .sort()
-    .map((f) => path.join(dir, f));
-}
-
-function readSnapshot(filePath) {
-  if (!filePath) return null;
-  const body = fs.readFileSync(filePath, 'utf-8');
-  return { path: filePath, body, meta: parseFrontmatter(body) };
-}
-
-function snapshotTargetIdentity(snapshot) {
-  const targetPath = snapshot?.meta.target_path;
-  return snapshot?.meta.target_identity
-    || (targetPath ? `file:${targetPath}` : null);
-}
-
-function readNewestSnapshot(slug, { cwd = process.cwd() } = {}) {
-  return readSnapshot(listSnapshots(`__${slug}.md`, cwd).at(-1));
-}
-
-function readNewestSnapshotForIdentity(
-  slug,
-  targetIdentity,
-  { cwd = process.cwd() } = {},
-) {
-  const matches = listSnapshots(`__${slug}.md`, cwd)
-    .map(readSnapshot)
-    .filter((snapshot) => snapshotTargetIdentity(snapshot) === targetIdentity);
-  return matches.at(-1) || null;
-}
-
-/**
- * Return the most recent snapshot for `slug`, or null. Polish reads this
- * to find its fix backlog when the slug matches.
- */
-export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
-  const latest = readNewestSnapshot(slug, { cwd });
-  return latest?.meta.closed === true ? null : latest;
-}
-
-/**
- * Mark one exact snapshot closed without deleting the score history consumed
- * by `trend`. Exact identity matters: a newer critique may land after polish
- * reads its backlog, and that newer snapshot must remain live. `snapshotFile`
- * may be the absolute path returned by readLatestSnapshot() or the basename
- * emitted by `latest --json`. Returns the path marked closed, or null.
- */
-export function closeSnapshot(snapshotFile, { cwd = process.cwd() } = {}) {
-  if (!snapshotFile || typeof snapshotFile !== 'string') return null;
-  const dir = path.resolve(getCritiqueDir(cwd));
-  const snapshotPath = path.isAbsolute(snapshotFile)
-    ? path.resolve(snapshotFile)
-    : path.resolve(dir, snapshotFile);
-  const filename = path.basename(snapshotPath);
-  if (
-    path.dirname(snapshotPath) !== dir
-    || !SNAPSHOT_FILENAME.test(filename)
-  ) return null;
-
-  let snapshot;
-  try {
-    if (!fs.lstatSync(snapshotPath).isFile()) return null;
-    snapshot = readSnapshot(snapshotPath);
-  } catch {
-    return null;
-  }
-  if (!snapshot || snapshot.meta.closed === true) return null;
-  const closedBody = snapshot.body.replace(
-    /^(---\r?\n[\s\S]*?)(\r?\n---)/,
-    '$1\nclosed: true$2',
-  );
-  if (closedBody === snapshot.body) {
-    throw new Error(`Cannot close snapshot without frontmatter: ${snapshot.path}`);
-  }
-  fs.writeFileSync(snapshot.path, closedBody, 'utf-8');
-  return snapshot.path;
-}
-
-/** Return the most recent snapshot across all targets, or null. */
-export function readLatestSnapshotAcrossTargets({ cwd = process.cwd() } = {}) {
-  const snapshots = listSnapshots('.md', cwd).map(readSnapshot);
-  const identifiedSlugs = new Set(
-    snapshots
-      .filter((snapshot) => snapshotTargetIdentity(snapshot))
-      .map((snapshot) => snapshot.meta.slug),
-  );
-  const latestByTarget = new Map();
-  for (const snapshot of snapshots) {
-    if (!snapshot?.meta.slug) continue;
-    // Slugs are lossy: distinct targets such as foo/bar and foo-bar can share
-    // one. Keep each known identity's latest open/closed state independent so
-    // closing one target cannot hide another target's live backlog. Once a
-    // slug has any identity-aware snapshot, its older legacy records are no
-    // longer independently routable and must not resurface as zombie work.
-    const targetIdentity = snapshotTargetIdentity(snapshot);
-    if (!targetIdentity && identifiedSlugs.has(snapshot.meta.slug)) continue;
-    const streamKey = targetIdentity || `slug:${snapshot.meta.slug}`;
-    latestByTarget.set(streamKey, snapshot);
-  }
-  return [...latestByTarget.values()]
-    .filter((snapshot) => snapshot.meta.closed !== true)
-    .sort((a, b) => a.path.localeCompare(b.path))
-    .at(-1) || null;
-}
-
-/**
- * Return the last `limit` snapshots' frontmatter, oldest → newest.
- * Critique appends a one-line trend to its output using this.
- */
-export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
-  const all = listSnapshots(`__${slug}.md`, cwd);
-  const slice = all.slice(-limit);
-  return slice.map((file) => parseFrontmatter(fs.readFileSync(file, 'utf-8')));
-}
-
-// ---- CLI ---------------------------------------------------------------
-
-// Accept either a ready slug or a concrete target (path/URL) everywhere, so
-// callers never have to run the slug step separately. Anything containing a
-// path or URL marker is resolved through slugFromTarget.
-function isReadySlug(value) {
-  return /^[a-z0-9-]+$/.test(value || '') && !value.includes('/');
-}
-
-function coerceSlug(value) {
-  if (!value) return null;
-  if (isReadySlug(value)) return value;
-  return slugFromTarget(value);
-}
-
-function main(argv) {
-  const [cmd, ...args] = argv;
-  switch (cmd) {
-    case 'slug': {
-      const slug = slugFromTarget(args[0]);
-      if (!slug) { process.stderr.write('no stable slug for input\n'); process.exit(1); }
-      process.stdout.write(`${slug}\n`);
-      return;
-    }
-    case 'write': {
-      const [slugArg, bodyFile] = args;
-      const slug = coerceSlug(slugArg);
-      if (!slug || !bodyFile) { process.stderr.write('usage: write <slug-or-target> <body-file>\n'); process.exit(1); }
-      const raw = fs.readFileSync(bodyFile, 'utf-8');
-      // The body file may be a full report. The caller passes the meta as
-      // a JSON object on stdin if it wants structured frontmatter; otherwise
-      // we write with minimal metadata.
-      let meta = {};
-      const metaArg = process.env.IMPECCABLE_CRITIQUE_META;
-      if (metaArg) {
-        try { meta = JSON.parse(metaArg); } catch { /* ignore */ }
-      }
-      // The helper, not caller-provided metadata, owns the target fingerprint.
-      // This makes the snapshot describe the exact file bytes critique saw.
-      delete meta.target_fingerprint;
-      delete meta.target_path;
-      delete meta.target_identity;
-      const targetIdentity = resolveTargetIdentity(slugArg);
-      if (targetIdentity) meta.target_identity = targetIdentity;
-      const targetFingerprint = fingerprintTarget(slugArg);
-      if (targetFingerprint) {
-        meta.target_fingerprint = targetFingerprint;
-        meta.target_path = resolveLocalTargetPath(slugArg);
-      }
-      const out = writeSnapshot({ slug, meta, body: raw });
-      process.stdout.write(`${out}\n`);
-      return;
-    }
-    case 'latest': {
-      const target = args[0];
-      const format = args[1];
-      const slug = coerceSlug(target);
-      if (!slug || (format && format !== '--json')) {
-        process.stderr.write('usage: latest <slug-or-target> [--json]\n');
-        process.exit(1);
-      }
-      const targetFingerprint = fingerprintTarget(target);
-      const targetPath = resolveLocalTargetPath(target);
-      const targetIdentity = resolveTargetIdentity(target);
-      const readySlug = isReadySlug(target);
-      const newestForSlug = readNewestSnapshot(slug);
-      if (!newestForSlug) { process.exit(2); }
-
-      // Concrete targets select the newest snapshot for their exact identity,
-      // not merely the newest filename for a lossy slug. This keeps distinct
-      // targets such as foo/bar and foo-bar from hiding each other's backlog.
-      const exactSnapshot = readNewestSnapshotForIdentity(slug, targetIdentity);
-      let latest = exactSnapshot;
-      if (!latest && !readySlug) {
-        // Legacy snapshots have no identity. Preserve their old explicit
-        // path/URL behavior only when no known target identity was selected.
-        latest = readNewestSnapshotForIdentity(slug, null);
-      }
-      if (!latest) latest = newestForSlug;
-      if (latest.meta.closed === true) { process.exit(2); }
-
-      const recordedTargetPath = latest.meta.target_path;
-      const recordedTargetIdentity = snapshotTargetIdentity(latest);
-      const matchingIdentity = recordedTargetIdentity === targetIdentity;
-
-      // Bare slugs remain a supported lookup mode, including for URL
-      // snapshots. But when a same-named local file exists, the request is
-      // ambiguous unless that exact file owns the snapshot identity.
-      if (readySlug && !recordedTargetIdentity) {
-        process.stderr.write(
-          'ambiguous legacy snapshot target; use an explicit ./path or full URL\n',
-        );
-        process.exit(2);
-      }
-      if (readySlug && targetPath && fs.existsSync(targetPath) && !matchingIdentity) {
-        process.stderr.write(
-          'ambiguous snapshot slug; use an explicit ./path or remove the local name collision\n',
-        );
-        process.exit(2);
-      }
-
-      const concreteTarget = !readySlug || matchingIdentity;
-      if (concreteTarget && recordedTargetIdentity && !matchingIdentity) {
-        process.exit(2);
-      }
-      const concreteLocalTarget = concreteTarget && targetPath;
-      if (concreteLocalTarget && latest.meta.target_fingerprint !== targetFingerprint) {
-        closeSnapshot(latest.path);
-        process.exit(2);
-      }
-      if (format === '--json') {
-        process.stdout.write(JSON.stringify({
-          snapshot_file: path.basename(latest.path),
-          body: latest.body,
-        }, null, 2) + '\n');
-      } else {
-        process.stdout.write(latest.body);
-      }
-      return;
-    }
-    case 'close': {
-      const [slugArg, snapshotFile, ...extra] = args;
-      const slug = coerceSlug(slugArg);
-      if (!slug || !snapshotFile || extra.length > 0) {
-        process.stderr.write('usage: close <resolved-target> <snapshot-file>\n');
-        process.exit(1);
-      }
-      if (
-        path.basename(snapshotFile) !== snapshotFile
-        || !SNAPSHOT_FILENAME.test(snapshotFile)
-        || !snapshotFile.endsWith(`__${slug}.md`)
-      ) process.exit(2);
-
-      // A slug and filename are not enough to prove ownership because two
-      // distinct targets can normalize to the same slug. Modern snapshots
-      // carry a canonical identity, so require the supplied resolved target
-      // to match it before allowing the exact snapshot to be closed. Legacy
-      // snapshots without identity retain their historical close behavior.
-      const snapshotPath = path.join(getCritiqueDir(process.cwd()), snapshotFile);
-      let snapshot;
-      try {
-        if (!fs.lstatSync(snapshotPath).isFile()) process.exit(2);
-        snapshot = readSnapshot(snapshotPath);
-      } catch {
-        process.exit(2);
-      }
-      const recordedTargetIdentity = snapshotTargetIdentity(snapshot);
-      if (
-        recordedTargetIdentity
-        && recordedTargetIdentity !== resolveTargetIdentity(slugArg)
-      ) process.exit(2);
-
-      const closed = closeSnapshot(snapshotFile);
-      if (!closed) { process.exit(2); }
-      process.stdout.write(`${closed}\n`);
-      return;
-    }
-    case 'trend': {
-      const rows = readTrend(coerceSlug(args[0]), { limit: args[1] ? Number(args[1]) : 5 });
-      process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
-      return;
-    }
-    default:
-      process.stderr.write('usage: critique-storage.mjs <slug|write|latest|trend|close> [args]\n');
-      process.exit(1);
-  }
-}
-
-function isMainModule() {
-  if (!process.argv[1]) return false;
-  try {
-    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1]);
-  } catch {
-    // pathToFileURL normalizes Windows paths; keep it as a fallback for any
-    // environment where realpath is unavailable.
-    return import.meta.url === pathToFileURL(process.argv[1]).href;
-  }
-}
-
-// Why the realpath check: generated skills are often reached through symlinked
-// harness directories (for example a demo repo's `.agents` -> source `.agents`).
-// Node resolves import.meta.url to the real file, while process.argv[1] keeps
-// the symlink path. Comparing canonical paths prevents a silent exit-0 no-op.
-if (isMainModule()) {
-  main(process.argv.slice(2));
-}

package/template/.agents/skills/design/impeccable/scripts/data/font-index-failures.json

@@ -1,121 +0,0 @@
-[
- {
-  "family": "Betania Patmos GDL",
-  "weight": 400,
-  "category": "handwriting",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Betania Patmos In GDL",
-  "weight": 400,
-  "category": "handwriting",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Doto",
-  "weight": 300,
-  "category": "sans",
-  "variable": true,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Doto",
-  "weight": 700,
-  "category": "sans",
-  "variable": true,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Jacquard 12 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Jacquard 24 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Jacquarda Bastarda 9 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Jersey 10 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Jersey 15 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Jersey 20 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Jersey 25 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Micro 5 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Montserrat Underline",
-  "weight": 400,
-  "category": "sans",
-  "variable": true,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Montserrat Underline",
-  "weight": 700,
-  "category": "sans",
-  "variable": true,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Redacted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Yarndings 12 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- },
- {
-  "family": "Yarndings 20 Charted",
-  "weight": 400,
-  "category": "display",
-  "variable": false,
-  "reason": "not loaded or no lettering"
- }
-]