quiver-cli 1.3.0 → 2.0.0

package/template/.agents/skills/design/impeccable/scripts/doctor.mjs

@@ -1,336 +0,0 @@
-#!/usr/bin/env node
-/**
- * Deep staleness pass over Impeccable's own project artifacts.
- *
- *   node doctor.mjs                 # human-readable report
- *   node doctor.mjs --json          # machine-readable, for the skill command
- *   node doctor.mjs --fix           # apply the mechanical migrations only
- *   node doctor.mjs --target <path> # pick a monorepo workspace
- *
- * The boot check in context.mjs reports what a session can afford to measure.
- * This runs everything: git drift, per-workspace sweep, ignore-list validation
- * against the live rule registry, hook script resolution.
- *
- * `--fix` is deliberately narrow. It performs only the migrations marked
- * severity 'auto', the ones with no judgment in them: stamp the product record,
- * move a sidecar out of a retired location. Anything that needs an answer from
- * the user (a platform value, whether an inherited record still describes an
- * app, whether a document has drifted from the code) is reported and left
- * alone. Exit code is 0 unless the run itself failed; findings are not errors.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { loadContext, extractPlatform, resolveTargetSelection } from './context.mjs';
-import { parseTargetOptions } from './lib/target-args.mjs';
-import { IMPECCABLE_COMMAND, IMPECCABLE_PROVIDER_ID } from './lib/provider.mjs';
-import { parseDesignMd } from './lib/design-parser.mjs';
-import {
-  PRODUCT_SCHEMA_VERSION,
-  readProductSchemaVersion,
-  stampProductSchema,
-} from './lib/artifact-schema.mjs';
-import {
-  checkConfig,
-  checkDesignSidecar,
-  checkNativePlatformEvidence,
-  checkProduct,
-  checkProjectRoots,
-  checkSurfaceBriefs,
-  designSidecarCandidatesFor,
-} from './lib/staleness.mjs';
-import {
-  checkDesignCoverage,
-  checkDesignDrift,
-  checkDetectorIgnores,
-  checkHookInstallation,
-  checkLegacyLiveState,
-  checkWorkspaces,
-  loadKnownRuleIds,
-} from './lib/staleness-deep.mjs';
-
-const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
-
-function safeRead(filePath) {
-  try {
-    return fs.readFileSync(filePath, 'utf-8');
-  } catch {
-    return null;
-  }
-}
-
-function parseArgs(argv) {
-  const passthrough = [];
-  const flags = { json: false, fix: false, help: false };
-  for (const arg of argv) {
-    if (arg === '--json') flags.json = true;
-    else if (arg === '--fix') flags.fix = true;
-    else if (arg === '--help' || arg === '-h') flags.help = true;
-    else passthrough.push(arg);
-  }
-  return { flags, targetOptions: parseTargetOptions(passthrough, { strict: true }) };
-}
-
-function usage() {
-  return [
-    `Usage: node doctor.mjs [--json] [--fix] [--target <path>]`,
-    '',
-    "Report drift between this project's Impeccable artifacts and what the",
-    'installed version reads: PRODUCT.md, DESIGN.md and its sidecar,',
-    '.impeccable/config.json, surface briefs, and the design hook.',
-    '',
-    '  --json           Emit findings as JSON.',
-    '  --fix            Apply the mechanical migrations (severity "auto") only.',
-    '  --target <path>  Select a workspace in a monorepo.',
-  ].join('\n');
-}
-
-async function collect(cwd, targetOptions) {
-  const ctx = loadContext(cwd, targetOptions);
-  const projectRoot = ctx.projectRoot || cwd;
-  const absProductPath = ctx.productPath ? path.resolve(cwd, ctx.productPath) : null;
-  const absDesignPath = ctx.designPath ? path.resolve(cwd, ctx.designPath) : null;
-  const sidecarCandidates = designSidecarCandidatesFor(projectRoot, ctx.contextDir);
-  const knownRuleIds = await loadKnownRuleIds(SCRIPTS_DIR);
-
-  const selection = resolveTargetSelection(cwd, targetOptions);
-  const workspaceCandidates = selection?.targetCandidates || [];
-
-  const workspaceResult = checkWorkspaces({
-    repoRoot: ctx.repoRoot,
-    candidates: workspaceCandidates,
-    checkNativePlatformEvidence,
-    extractPlatform,
-    readFile: safeRead,
-  });
-
-  const findings = [
-    ...checkProduct(ctx.product, ctx.productPath || 'PRODUCT.md'),
-    ...(ctx.product
-      ? checkNativePlatformEvidence({
-          projectRoot,
-          platform: ctx.platform,
-          product: ctx.product,
-          productPath: ctx.productPath,
-        })
-      : []),
-    ...checkDesignSidecar({ designPath: absDesignPath, sidecarCandidates, projectRoot }),
-    ...checkDesignDrift({ designPath: absDesignPath, projectRoot }),
-    ...checkDesignCoverage({ design: ctx.design, designPath: ctx.designPath, parseDesignMd }),
-    ...checkConfig({ projectRoot, repoRoot: ctx.repoRoot }),
-    ...checkDetectorIgnores({ projectRoot, knownRuleIds }),
-    ...checkSurfaceBriefs({ candidates: ctx.surfaceBriefCandidates, projectRoot }),
-    ...checkHookInstallation({
-      projectRoot,
-      repoRoot: ctx.repoRoot,
-      providerId: IMPECCABLE_PROVIDER_ID,
-    }),
-    ...checkLegacyLiveState({ projectRoot }),
-    ...checkProjectRoots({
-      patterns: readProjectRootPatterns(ctx.repoRoot),
-      candidates: workspaceCandidates,
-    }),
-    ...workspaceResult.findings,
-  ];
-
-  return {
-    ctx,
-    projectRoot,
-    absProductPath,
-    sidecarCandidates,
-    findings,
-    workspaces: workspaceResult.workspaces,
-    ruleRegistryAvailable: knownRuleIds !== null,
-  };
-}
-
-// Read straight from disk rather than importing context.mjs's private reader.
-// Only the positive/negative pattern strings matter here.
-function readProjectRootPatterns(repoRoot) {
-  if (!repoRoot) return [];
-  const patterns = [];
-  for (const name of ['config.json', 'config.local.json']) {
-    try {
-      const raw = JSON.parse(fs.readFileSync(path.join(repoRoot, '.impeccable', name), 'utf-8'));
-      if (Array.isArray(raw?.projectRoots)) {
-        for (const entry of raw.projectRoots) {
-          if (typeof entry === 'string' && entry.trim()) patterns.push(entry.trim());
-        }
-      }
-    } catch { /* missing or malformed: nothing to check */ }
-  }
-  return patterns;
-}
-
-/**
- * Apply the migrations that carry no decision. Returns what was done and what
- * was deliberately left for the user.
- */
-function applyFixes(report) {
-  const applied = [];
-  const skipped = [];
-
-  for (const entry of report.findings) {
-    if (entry.severity !== 'auto') {
-      skipped.push({ id: entry.id, reason: 'needs a decision from the user' });
-      continue;
-    }
-    if (entry.id === 'design-sidecar-legacy-path') {
-      const canonical = report.sidecarCandidates[0];
-      const present = report.sidecarCandidates.find((candidate) => fs.existsSync(candidate));
-      if (!canonical || !present || path.resolve(canonical) === path.resolve(present)) continue;
-      if (fs.existsSync(canonical)) {
-        skipped.push({ id: entry.id, reason: `${rel(canonical, report.projectRoot)} already exists; not overwriting` });
-        continue;
-      }
-      fs.mkdirSync(path.dirname(canonical), { recursive: true });
-      fs.renameSync(present, canonical);
-      applied.push(`Moved ${rel(present, report.projectRoot)} to ${rel(canonical, report.projectRoot)}.`);
-      continue;
-    }
-    if (entry.id === 'legacy-live-state') {
-      // Reported, never deleted here: a running live session still reads these,
-      // and losing session state to a doctor run is a worse outcome than a
-      // stale file. The report says what to remove and when.
-      skipped.push({ id: entry.id, reason: 'delete by hand once no live session is running' });
-      continue;
-    }
-    skipped.push({ id: entry.id, reason: 'no automatic migration implemented' });
-  }
-
-  // Stamping the product record is additive and safe, and it is what stops a
-  // later version proposing an interview the user has already sat through.
-  const productPath = report.absProductPath;
-  if (productPath && report.ctx.product && readProductSchemaVersion(report.ctx.product) === null
-    && !report.findings.some((entry) => entry.id === 'product-schema-legacy')) {
-    fs.writeFileSync(productPath, stampProductSchema(report.ctx.product), 'utf-8');
-    applied.push(`Stamped ${rel(productPath, report.projectRoot)} as product-schema ${PRODUCT_SCHEMA_VERSION}.`);
-  }
-
-  return { applied, skipped };
-}
-
-function rel(filePath, root) {
-  const value = path.relative(root, filePath);
-  return value && !value.startsWith('..') ? value.split(path.sep).join('/') : filePath;
-}
-
-const SEVERITY_LABEL = {
-  auto: 'automatic',
-  mention: 'worth saying',
-  route: 'needs a command',
-};
-
-function renderText(report, fixes) {
-  const lines = [];
-  const { findings } = report;
-
-  lines.push(`Impeccable doctor: ${rel(report.projectRoot, process.cwd()) || '.'}`);
-  if (report.ctx.isMonorepo) {
-    lines.push(`Monorepo, repo root ${rel(report.ctx.repoRoot, process.cwd()) || '.'}.`);
-  }
-  lines.push('');
-
-  if (!findings.length) {
-    lines.push('No drift found. Every artifact matches what this version reads.');
-  } else {
-    const order = ['route', 'mention', 'auto'];
-    for (const severity of order) {
-      const group = findings.filter((entry) => entry.severity === severity);
-      if (!group.length) continue;
-      lines.push(`${SEVERITY_LABEL[severity]} (${group.length}):`);
-      for (const entry of group) {
-        lines.push(`  ${entry.id}${entry.path ? `  [${entry.path}]` : ''}`);
-        lines.push(`    ${entry.summary}`);
-        lines.push(`    → ${entry.fix}`);
-      }
-      lines.push('');
-    }
-  }
-
-  if (report.workspaces.length) {
-    lines.push('Workspaces:');
-    for (const workspace of report.workspaces) {
-      lines.push(`  ${workspace.path}  product: ${workspace.productStatus}`
-        + `  design: ${workspace.designStatus}`
-        + `${workspace.platform ? `  platform: ${workspace.platform}` : ''}`);
-    }
-    lines.push('');
-  }
-
-  if (!report.ruleRegistryAvailable) {
-    lines.push('Note: the bundled detector could not be resolved, so ignored rule ids were not validated.');
-    lines.push('');
-  }
-
-  if (fixes) {
-    lines.push(fixes.applied.length ? 'Applied:' : 'Applied nothing.');
-    for (const entry of fixes.applied) lines.push(`  ${entry}`);
-    const held = fixes.skipped.filter((entry) => entry.reason !== 'needs a decision from the user');
-    if (held.length) {
-      lines.push('Left alone:');
-      for (const entry of held) lines.push(`  ${entry.id}: ${entry.reason}`);
-    }
-  } else if (findings.some((entry) => entry.severity === 'auto')) {
-    lines.push(`Run \`node doctor.mjs --fix\` to apply the automatic migrations, `
-      + `or \`${IMPECCABLE_COMMAND} doctor\` to work through all of them.`);
-  }
-
-  return lines.join('\n');
-}
-
-async function cli() {
-  let parsed;
-  try {
-    parsed = parseArgs(process.argv.slice(2));
-  } catch (err) {
-    process.stderr.write(`${err.message}\n`);
-    process.exit(1);
-  }
-  if (parsed.flags.help) {
-    process.stdout.write(`${usage()}\n`);
-    return;
-  }
-
-  const report = await collect(process.cwd(), parsed.targetOptions);
-  const fixes = parsed.flags.fix ? applyFixes(report) : null;
-
-  if (parsed.flags.json) {
-    process.stdout.write(`${JSON.stringify({
-      projectRoot: report.projectRoot,
-      repoRoot: report.ctx.repoRoot,
-      isMonorepo: report.ctx.isMonorepo,
-      productPath: report.ctx.productPath,
-      designPath: report.ctx.designPath,
-      platform: report.ctx.platform,
-      ruleRegistryAvailable: report.ruleRegistryAvailable,
-      findings: report.findings,
-      workspaces: report.workspaces,
-      ...(fixes ? { fixes } : {}),
-    }, null, 2)}\n`);
-    return;
-  }
-
-  process.stdout.write(`${renderText(report, fixes)}\n`);
-}
-
-function invokedAsScript() {
-  const arg = process.argv[1];
-  if (!arg) return false;
-  try {
-    return fs.realpathSync(arg) === fs.realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
-  }
-}
-
-if (invokedAsScript()) {
-  cli().catch((err) => {
-    process.stderr.write(`impeccable doctor failed: ${err?.message || err}\n`);
-    process.exit(1);
-  });
-}
-
-export { collect, applyFixes, renderText };

package/template/.agents/skills/design/impeccable/scripts/embed-prompt.mjs

@@ -1,133 +0,0 @@
-#!/usr/bin/env node
-// Embed a generation prompt into an image so the intent travels with the file,
-// across harnesses and machines. Read it back with --read.
-//
-//   node embed-prompt.mjs <image> --prompt "the prompt text"
-//   node embed-prompt.mjs <image> --prompt-file prompt.txt
-//   node embed-prompt.mjs <image> --read
-//
-// Formats: PNG (tEXt chunk, keyword "impeccable:prompt"), JPEG (COM segment).
-// WebP and anything else fall back to a `<image>.json` sidecar; --read checks
-// the sidecar for every format, so the fallback stays recoverable. Embedding
-// rewrites a few MB at most: latency is milliseconds, generation is minutes.
-// Caveat worth knowing: image optimizers in build pipelines often strip
-// metadata from their OUTPUT files; the intent lives on the source asset,
-// which is the one a builder reads.
-
-import fs from 'node:fs';
-import zlib from 'node:zlib';
-
-const KEYWORD = 'impeccable:prompt';
-const args = process.argv.slice(2);
-const file = args.find(a => !a.startsWith('--'));
-const readMode = args.includes('--read');
-const argOf = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : null; };
-
-if (!file || !fs.existsSync(file)) { console.error('embed-prompt: image file required'); process.exit(1); }
-
-const buf = fs.readFileSync(file);
-const isPng = buf.length > 8 && buf.readUInt32BE(0) === 0x89504e47;
-const isJpeg = buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8;
-
-const crcTable = (() => {
-  const t = new Uint32Array(256);
-  for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0; }
-  return t;
-})();
-const crc32 = (data) => { let c = 0xffffffff; for (const b of data) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
-
-function pngChunk(type, data) {
-  const out = Buffer.alloc(12 + data.length);
-  out.writeUInt32BE(data.length, 0);
-  out.write(type, 4, 'ascii');
-  data.copy(out, 8);
-  out.writeUInt32BE(crc32(Buffer.concat([Buffer.from(type, 'ascii'), data])), 8 + data.length);
-  return out;
-}
-
-function readPngText(b) {
-  let off = 8;
-  while (off + 12 <= b.length) {
-    const len = b.readUInt32BE(off);
-    const type = b.toString('ascii', off + 4, off + 8);
-    if (type === 'tEXt' || type === 'zTXt') {
-      const data = b.subarray(off + 8, off + 8 + len);
-      const nul = data.indexOf(0);
-      if (nul !== -1 && data.toString('latin1', 0, nul) === KEYWORD) {
-        if (type === 'tEXt') return data.toString('utf8', nul + 1);
-        return zlib.inflateSync(data.subarray(nul + 2)).toString('utf8');
-      }
-    }
-    off += 12 + len;
-  }
-  return null;
-}
-
-function readJpegCom(b) {
-  let off = 2;
-  while (off + 4 <= b.length && b[off] === 0xff) {
-    const marker = b[off + 1];
-    if (marker === 0xda) break; // start of scan: no more segments
-    const len = b.readUInt16BE(off + 2);
-    if (marker === 0xfe) {
-      const text = b.toString('utf8', off + 4, off + 2 + len);
-      if (text.startsWith(KEYWORD + '\0')) return text.slice(KEYWORD.length + 1);
-    }
-    off += 2 + len;
-  }
-  return null;
-}
-
-const sidecar = `${file}.json`;
-if (readMode) {
-  let prompt = null;
-  if (isPng) prompt = readPngText(buf);
-  else if (isJpeg) prompt = readJpegCom(buf);
-  if (prompt == null && fs.existsSync(sidecar)) {
-    try { prompt = JSON.parse(fs.readFileSync(sidecar, 'utf8')).prompt ?? null; } catch { /* fall through */ }
-  }
-  if (prompt == null) { console.error('embed-prompt: no embedded prompt found'); process.exit(2); }
-  console.log(prompt);
-  process.exit(0);
-}
-
-const prompt = argOf('--prompt') ?? (argOf('--prompt-file') ? fs.readFileSync(argOf('--prompt-file'), 'utf8') : null);
-if (!prompt) { console.error('embed-prompt: --prompt or --prompt-file required'); process.exit(1); }
-
-if (isPng) {
-  // Insert (or replace) our tEXt chunk immediately before IEND.
-  const iend = buf.indexOf(Buffer.from('IEND', 'ascii')) - 4;
-  if (iend < 8) { console.error('embed-prompt: malformed PNG'); process.exit(1); }
-  // Drop any existing chunk with our keyword to keep embedding idempotent.
-  let body = buf.subarray(8, iend);
-  const existing = readPngText(buf);
-  if (existing != null) {
-    const parts = [];
-    let off = 8;
-    while (off + 12 <= buf.length && off < iend + 12) {
-      const len = buf.readUInt32BE(off);
-      const type = buf.toString('ascii', off + 4, off + 8);
-      const chunk = buf.subarray(off, off + 12 + len);
-      const data = buf.subarray(off + 8, off + 8 + len);
-      const nul = data.indexOf(0);
-      const ours = (type === 'tEXt' || type === 'zTXt') && nul !== -1 && data.toString('latin1', 0, nul) === KEYWORD;
-      if (!ours && type !== 'IEND') parts.push(chunk);
-      off += 12 + len;
-    }
-    body = Buffer.concat(parts).subarray(8 * 0); // parts exclude signature
-    fs.writeFileSync(file, Buffer.concat([buf.subarray(0, 8), body, pngChunk('tEXt', Buffer.concat([Buffer.from(KEYWORD, 'latin1'), Buffer.from([0]), Buffer.from(prompt, 'utf8')])), pngChunk('IEND', Buffer.alloc(0))]));
-  } else {
-    fs.writeFileSync(file, Buffer.concat([buf.subarray(0, iend), pngChunk('tEXt', Buffer.concat([Buffer.from(KEYWORD, 'latin1'), Buffer.from([0]), Buffer.from(prompt, 'utf8')])), buf.subarray(iend)]));
-  }
-  console.log(`EMBEDDED: ${file} (png tEXt, ${prompt.length} chars)`);
-} else if (isJpeg) {
-  const seg = Buffer.from(`${KEYWORD}\0${prompt}`, 'utf8');
-  if (seg.length + 2 > 0xffff) { console.error('embed-prompt: prompt too long for a JPEG segment'); process.exit(1); }
-  const com = Buffer.alloc(4 + seg.length);
-  com[0] = 0xff; com[1] = 0xfe; com.writeUInt16BE(seg.length + 2, 2); seg.copy(com, 4);
-  fs.writeFileSync(file, Buffer.concat([buf.subarray(0, 2), com, buf.subarray(2)]));
-  console.log(`EMBEDDED: ${file} (jpeg COM, ${prompt.length} chars)`);
-} else {
-  fs.writeFileSync(sidecar, JSON.stringify({ prompt, createdAt: new Date().toISOString() }, null, 2));
-  console.log(`EMBEDDED: ${sidecar} (sidecar fallback for this format)`);
-}