1#!/usr/bin/env node
2/**
3 * Critique persistence helper.
4 *
5 * Each run of /impeccable critique writes a per-target snapshot to
6 *   .impeccable/critique/<timestamp>__<slug>.md
7 * with a small YAML frontmatter carrying the score + P0/P1 counts.
8 *
9 * /impeccable polish reads the latest matching snapshot at start as its
10 * fix backlog. No other skill auto-reads critique output.
11 *
12 * The slug is derived mechanically from the *resolved* primary artifact
13 * (file path or URL), never from the user's natural-language phrasing.
14 * Slug stability across runs is what lets the trend display work.
15 *
16 * CLI entry points (called from skill instructions):
17 *   node critique-storage.mjs slug <resolved-target>
18 *   node critique-storage.mjs write <slug> <snapshot-body-file>
19 *   node critique-storage.mjs latest <slug>
20 *   node critique-storage.mjs trend <slug> [limit]
21 *
22 * Note: there is intentionally no `ignore` subcommand. ignore.md is a plain
23 * markdown file; the model reads it directly with its file-read tool. This
24 * helper only exists for operations the model can't trivially do inline
25 * (normalizing paths, generating filenames, globbing + parsing frontmatter).
26 */
27 
28import fs from 'node:fs';
29import path from 'node:path';
30import { getCritiqueDir } from './impeccable-paths.mjs';
31 
32const SLUG_MAX = 50;
33 
34/**
35 * Mechanically derive a slug from a resolved target. Returns null if the
36 * input doesn't look like a stable identifier (empty, project root, etc).
37 *
38 * Accepts file paths and URLs. The model resolves "the homepage" to a
39 * concrete artifact before calling this — we never slug a natural-language
40 * phrase.
41 */
42export function slugFromTarget(resolved, { cwd = process.cwd() } = {}) {
43  if (!resolved || typeof resolved !== 'string') return null;
44  const trimmed = resolved.trim();
45  if (!trimmed) return null;
46 
47  // URL
48  if (/^https?:\/\//i.test(trimmed)) {
49    let url;
50    try { url = new URL(trimmed); } catch { return null; }
51    const hostPath = `${url.hostname}${url.pathname}`;
52    return kebab(hostPath);
53  }
54 
55  // File path. Make it project-relative so two devs critiquing the same
56  // checkout get the same slug regardless of where their repo is cloned.
57  const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
58  let rel = path.relative(cwd, abs);
59  // If the target is outside cwd, fall back to the basename so we still
60  // produce a stable slug (vs the absolute path, which would include
61  // home dirs / usernames).
62  if (rel.startsWith('..') || path.isAbsolute(rel)) {
63    rel = path.basename(abs);
64  }
65  if (!rel || rel === '.' || rel === '') return null;
66  return kebab(rel);
67}
68 
69function kebab(s) {
70  const slug = s
71    .toLowerCase()
72    .replace(/[/\\.]+/g, '-')
73    .replace(/[^a-z0-9-]+/g, '-')
74    .replace(/-+/g, '-')
75    .replace(/^-|-$/g, '');
76  if (!slug) return null;
77  // Cap from the tail — the tail (filename) is more identifying than the
78  // top-level directory.
79  return slug.length <= SLUG_MAX ? slug : slug.slice(slug.length - SLUG_MAX).replace(/^-/, '');
80}
81 
82/**
83 * Filename-safe UTC ISO timestamp: hyphens for separators, trailing Z.
84 * Plain colons aren't allowed on Windows filesystems.
85 */
86export function nowFilenameStamp(date = new Date()) {
87  const iso = date.toISOString();           // 2026-05-12T18:30:00.123Z
88  return iso.replace(/[:.]/g, '-').replace(/-\d+Z$/, 'Z');
89}
90 
91/**
92 * Write a snapshot for `slug`. `meta` carries the small structured frontmatter
93 * keys read back by readTrend(). `body` is the human-readable critique
94 * report (everything below the frontmatter).
95 *
96 * Returns the absolute path written.
97 */
98export function writeSnapshot({ slug, meta, body, cwd = process.cwd(), now = new Date() }) {
99  if (!slug) throw new Error('writeSnapshot requires a slug');
100  const dir = getCritiqueDir(cwd);
101  fs.mkdirSync(dir, { recursive: true });
102  const timestamp = nowFilenameStamp(now);
103  const filePath = path.join(dir, `${timestamp}__${slug}.md`);
104  // Spread `meta` first so internally computed `timestamp` and `slug`
105  // always win. Otherwise a caller-supplied meta blob (parsed from the
106  // IMPECCABLE_CRITIQUE_META env var) could clobber them, leaving the
107  // filename in disagreement with its frontmatter and corrupting trends.
108  const front = serializeFrontmatter({ ...meta, timestamp, slug });
109  fs.writeFileSync(filePath, `${front}\n${body.trim()}\n`, 'utf-8');
110  return filePath;
111}
112 
113function serializeFrontmatter(obj) {
114  const lines = ['---'];
115  for (const [key, value] of Object.entries(obj)) {
116    if (value === undefined || value === null) continue;
117    const str = typeof value === 'string' ? value : String(value);
118    // Quote strings that contain : or # to keep parsing simple.
119    const needsQuotes = typeof value === 'string' && /[:#]/.test(str);
120    lines.push(`${key}: ${needsQuotes ? JSON.stringify(str) : str}`);
121  }
122  lines.push('---');
123  return lines.join('\n');
124}
125 
126function parseFrontmatter(text) {
127  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
128  if (!match) return {};
129  const out = {};
130  for (const line of match[1].split(/\r?\n/)) {
131    const colon = line.indexOf(':');
132    if (colon < 0) continue;
133    const key = line.slice(0, colon).trim();
134    let value = line.slice(colon + 1).trim();
135    if (/^".*"$/.test(value)) {
136      try { value = JSON.parse(value); } catch { /* leave as-is */ }
137    } else if (/^-?\d+$/.test(value)) {
138      value = Number(value);
139    }
140    out[key] = value;
141  }
142  return out;
143}
144 
145/**
146 * Return all snapshot files for `slug`, sorted oldest → newest.
147 */
148function listSnapshotsForSlug(slug, cwd) {
149  const dir = getCritiqueDir(cwd);
150  if (!fs.existsSync(dir)) return [];
151  const suffix = `__${slug}.md`;
152  return fs.readdirSync(dir)
153    .filter((f) => f.endsWith(suffix))
154    .sort()
155    .map((f) => path.join(dir, f));
156}
157 
158/**
159 * Return the most recent snapshot for `slug`, or null. Polish reads this
160 * to find its fix backlog when the slug matches.
161 */
162export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
163  const all = listSnapshotsForSlug(slug, cwd);
164  if (!all.length) return null;
165  const latest = all[all.length - 1];
166  const body = fs.readFileSync(latest, 'utf-8');
167  return { path: latest, body, meta: parseFrontmatter(body) };
168}
169 
170/**
171 * Return the last `limit` snapshots' frontmatter, oldest → newest.
172 * Critique appends a one-line trend to its output using this.
173 */
174export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
175  const all = listSnapshotsForSlug(slug, cwd);
176  const slice = all.slice(-limit);
177  return slice.map((file) => parseFrontmatter(fs.readFileSync(file, 'utf-8')));
178}
179 
180// ---- CLI ---------------------------------------------------------------
181 
182function main(argv) {
183  const [cmd, ...args] = argv;
184  switch (cmd) {
185    case 'slug': {
186      const slug = slugFromTarget(args[0]);
187      if (!slug) { process.stderr.write('no stable slug for input\n'); process.exit(1); }
188      process.stdout.write(`${slug}\n`);
189      return;
190    }
191    case 'write': {
192      const [slug, bodyFile] = args;
193      if (!slug || !bodyFile) { process.stderr.write('usage: write <slug> <body-file>\n'); process.exit(1); }
194      const raw = fs.readFileSync(bodyFile, 'utf-8');
195      // The body file may be a full report. The caller passes the meta as
196      // a JSON object on stdin if it wants structured frontmatter; otherwise
197      // we write with minimal metadata.
198      let meta = {};
199      const metaArg = process.env.IMPECCABLE_CRITIQUE_META;
200      if (metaArg) {
201        try { meta = JSON.parse(metaArg); } catch { /* ignore */ }
202      }
203      const out = writeSnapshot({ slug, meta, body: raw });
204      process.stdout.write(`${out}\n`);
205      return;
206    }
207    case 'latest': {
208      const latest = readLatestSnapshot(args[0]);
209      if (!latest) { process.exit(2); }
210      process.stdout.write(latest.body);
211      return;
212    }
213    case 'trend': {
214      const rows = readTrend(args[0], { limit: args[1] ? Number(args[1]) : 5 });
215      process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
216      return;
217    }
218    default:
219      process.stderr.write('usage: critique-storage.mjs <slug|write|latest|trend> [args]\n');
220      process.exit(1);
221  }
222}
223 
224if (import.meta.url === `file://${process.argv[1]}`) {
225  main(process.argv.slice(2));
226}
227