diff --git a/changelog.d/inc2-incident-overlay.md b/changelog.d/inc2-incident-overlay.md new file mode 100644 index 00000000..90bba278 --- /dev/null +++ b/changelog.d/inc2-incident-overlay.md @@ -0,0 +1 @@ +- An incident overlay renderer (`docs/assets/readme/incident-overlay.mjs`, `render-incident.mjs`) that draws one incident on the published harness figure from a small JSON, and its first picture, `v2/incidents/claude-settings-secrets.png`. diff --git a/docs/assets/readme/incident-overlay.mjs b/docs/assets/readme/incident-overlay.mjs new file mode 100644 index 00000000..fca7847a --- /dev/null +++ b/docs/assets/readme/incident-overlay.mjs @@ -0,0 +1,58 @@ +// Incident overlay: the published harness figure (where-chock-sits.mjs, unchanged) with one incident drawn on it. The spec JSON names the path, the numbered steps, the ringed catch points and the refusal text; layout and colours come from the figure. +import { layout, where, DEFAULT_PALETTE } from './where-chock-sits.mjs'; + +// The order layout() pushes its arrows in; a test asserts the count so a layout change cannot shift the names silently. +export const EDGES = ['you-prompt', 'prompt-loop', 'session-loop', 'context-loop', 'loop-model', 'loop-gate', 'gate-loop', 'gate-tools', 'tools-loop', 'tools-external', 'loop-subagents', 'tools-commit', 'commit-push', 'push-ci', 'ci-main']; +const RED = '#DC2626'; +const esc = (s) => String(s).replace(/&/g, '&').replace(/ `
${inner}
`; + +const corners = (d) => [...d.matchAll(/([MHV])(-?[\d.]+)(?: (-?[\d.]+))?/g)].reduce((pts, m) => { + const [x, y] = pts.length ? pts[pts.length - 1] : [0, 0]; + pts.push(m[1] === 'M' ? [+m[2], +m[3]] : m[1] === 'H' ? [+m[2], y] : [x, +m[2]]); + return pts; +}, []); +// A point a third of the way along the segment's longest straight run, where a numbered mark fits beside the arrow label. +const markAt = (d) => { + const p = corners(d), runs = p.slice(1).map((q, i) => [p[i], q]); + const [a, b] = runs.reduce((best, r) => (Math.hypot(r[1][0] - r[0][0], r[1][1] - r[0][1]) > Math.hypot(best[1][0] - best[0][0], best[1][1] - best[0][1]) ? r : best)); + return [a[0] + (b[0] - a[0]) * 0.3, a[1] + (b[1] - a[1]) * 0.3]; +}; + +export const checkSpec = (L, spec) => { + if (L.segs.length !== EDGES.length) throw new Error(`layout has ${L.segs.length} arrows, EDGES names ${EDGES.length}`); + const unknown = [...spec.path.edges, ...spec.steps.map((s) => s.edge)].filter((e) => !EDGES.includes(e)); + if (unknown.length) throw new Error(`unknown edge ${unknown}`); + const ids = new Set(L.badges.map((b) => b.p.id)), cards = new Set(Object.keys(L.cards)); + [...spec.rings, ...spec.dashed].filter((r) => !ids.has(r.point)).forEach((r) => { throw new Error(`no badge ${r.point}`); }); + spec.path.cards.filter((c) => !cards.has(c)).forEach((c) => { throw new Error(`no card ${c}`); }); +}; + +export const incident = (page, W, spec, palette = DEFAULT_PALETTE) => { + const base = JSON.parse(JSON.stringify(W)); + base.harness.title = spec.title; + const L = layout(base); + checkSpec(L, spec); + const { paper: PAPER, ink: INK, soft: SOFT, line: LINE } = palette; + const edge = (e) => L.segs[EDGES.indexOf(e)]; + const dim = Object.values(L.cards).filter((c) => !spec.path.cards.includes(c.id)).map((c) => abs(c.x, c.y, c.w, c.h, `background:${PAPER};opacity:.62;border-radius:12px`)).join(''); + const marker = ``; + const lines = spec.path.edges.map((e) => ``).join(''); + const disc = (x, y, text, size = 20) => abs(x - size / 2, y - size / 2, size, size, `border-radius:50%;background:${RED};color:#fff;font-size:12px;font-weight:700;line-height:${size}px;text-align:center`, esc(text)); + const steps = spec.steps.map((s, i) => { const [x, y] = markAt(edge(s.edge).d); return disc(x, y, i + 1); }).join(''); + const ringed = (r, i, dashed) => { const b = L.badges.find((q) => q.p.id === r.point), g = 3; return abs(b.x - g, b.y - g, b.w + 2 * g, b.h + 2 * g, `box-sizing:border-box;border:3px ${dashed ? 'dashed' : 'solid'} ${RED};border-radius:999px`) + disc(b.x + b.w + g, b.y - g, String.fromCharCode(65 + i), 18); }; + const rings = spec.rings.map((r, i) => ringed(r, i, false)).join('') + spec.dashed.map((r, i) => ringed(r, spec.rings.length + i, true)).join(''); + const cropH = 78 + L.Ht + 20 + 56; + const frame = where((body) => body, base, palette); + const overlay = `
${dim}${marker}${lines}${steps}${rings}
`; + const row = (mark, text, round) => `
${mark}${esc(text)}
`; + const key = spec.steps.map((s, i) => row(i + 1, s.text, true)).join('') + spec.rings.map((r, i) => row(String.fromCharCode(65 + i), r.label, false)).join('') + spec.dashed.map((r, i) => row(String.fromCharCode(65 + spec.rings.length + i), r.label, false)).join('') + (spec.dashed.length ? `
solid ring: a check the proof ran and recorded. dashed ring: a place a rule can be added.
` : ''); + const refusals = spec.refusals.length + ? spec.refusals.map((r) => `
${esc(r.sample)}: exit ${esc(r.exit)}
${esc(r.text)}
`).join('') + : `
no proof recorded yet
`; + return page(`
+
${frame}${overlay}
+
${esc(spec.path.title)}
${key} +
${esc(spec.refusal_title)}
${refusals}
+
${esc(spec.footer)}
`); +}; diff --git a/docs/assets/readme/incidents/claude-settings-secrets.json b/docs/assets/readme/incidents/claude-settings-secrets.json new file mode 100644 index 00000000..2e1551b8 --- /dev/null +++ b/docs/assets/readme/incidents/claude-settings-secrets.json @@ -0,0 +1,81 @@ +{ + "_": "Per-incident spec read by incident-overlay.mjs. 'rings' (solid) stay empty until a proof run records a refusal at that badge; only recorded refusals may be ringed. 'dashed' marks places a rule can be added; its labels never claim the point caught the incident.", + "title": "Keep the agent's local settings out of git", + "path": { + "title": "The path, in red", + "edges": [ + "you-prompt", + "prompt-loop", + "loop-gate", + "gate-tools", + "tools-commit", + "commit-push", + "push-ci", + "ci-main" + ], + "cards": [ + "you", + "prompt", + "loop", + "gate", + "tools", + "commit", + "push", + "ci", + "main" + ] + }, + "steps": [ + { + "edge": "gate-tools", + "text": "You approve \"Yes, and don't ask again\" on a command that carries a secret." + }, + { + "edge": "tools-commit", + "text": "The command, secret included, is saved to .claude/settings.local.json in the project." + }, + { + "edge": "commit-push", + "text": "git commit takes the file along with the rest of the code." + }, + { + "edge": "push-ci", + "text": "git push puts it in the repository, public or not." + } + ], + "rings": [ + { + "point": "git-commit", + "label": "commit: scan-secrets refuses the staged settings file (exit 1)" + } + ], + "refusal_title": "What the checks printed", + "refusals": [ + { + "sample": "git commit, sample a (API key in the right provider format)", + "exit": "1", + "text": "Potential secret detected in this change. Remove credentials and rotate any exposed keys. ...\n- .claude/settings.local.json: content pattern" + }, + { + "sample": "git commit, sample b (password in a connection string)", + "exit": "1", + "text": "Potential secret detected in this change. Remove credentials and rotate any exposed keys. ...\n- .claude/settings.local.json: content pattern" + } + ], + "footer": "The example rules here are from Chock.", + "alt": "The published harness figure with the incident's path drawn in red: you approve a command that carries a secret, the agent loop runs it through the tool gate, the tool saves it to the settings file, and git commit, git push, CI and the main branch carry it on. Cards off the path are dimmed. A solid ring on the commit badge marks the check that refused two test files at commit; dashed rings mark three places a rule could be added.", + "dashed": [ + { + "point": "prompt_submit", + "label": "your own rule could check here: a secret pasted into the prompt, before it reaches the model and the saved transcript" + }, + { + "point": "pre_tool", + "label": "a rule could check here: the proposed command that carries the secret, before it runs" + }, + { + "point": "file_changed", + "label": "a rule could notice here, before the commit: the settings file now holds a secret (warns; it cannot undo the write)" + } + ] +} diff --git a/docs/assets/readme/render-incident.mjs b/docs/assets/readme/render-incident.mjs new file mode 100644 index 00000000..a33bc23c --- /dev/null +++ b/docs/assets/readme/render-incident.mjs @@ -0,0 +1,27 @@ +// Renders one incident overlay to PNG: node docs/assets/readme/render-incident.mjs [out.png] (needs `playwright`; CHROMIUM=/path to use a preinstalled Chromium) +import { chromium } from 'playwright'; +import { mkdirSync, readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import path from 'node:path'; +import { incident } from './incident-overlay.mjs'; + +const HERE = path.dirname(fileURLToPath(import.meta.url)); +const [slug, out = path.join(HERE, 'v2', 'incidents', `${slug}.png`)] = process.argv.slice(2); +const read = (...p) => JSON.parse(readFileSync(path.join(HERE, ...p), 'utf8')); +const CSS = `*{box-sizing:border-box}body{margin:0;background:#FBF7EE;font-family:"Instrument Sans",system-ui,sans-serif;font-weight:500}.mono{font-family:"JetBrains Mono",ui-monospace,monospace}.eyebrow{font-family:"JetBrains Mono",ui-monospace,monospace;letter-spacing:.14em;text-transform:uppercase}`; +const page = (body) => `${body}`; +const html = incident(page, read('where-chock-sits.json'), read('incidents', `${slug}.json`)); +const browser = await chromium.launch({ executablePath: process.env.CHROMIUM || undefined, args: ['--no-sandbox'] }); +const pg = await (await browser.newContext({ deviceScaleFactor: 2 })).newPage(); +await pg.setViewportSize({ width: 880, height: 800 }); +await pg.setContent(html, { waitUntil: 'networkidle' }); +const ok = await pg.evaluate(async () => { + const fonts = ['16px "Instrument Sans"', '600 16px "Instrument Sans"', '14px "JetBrains Mono"']; + await Promise.all(fonts.map((f) => document.fonts.load(f))); + return fonts.map((f) => document.fonts.check(f)); +}); +if (!ok.every(Boolean)) throw new Error(`fonts missing (Instrument Sans / JetBrains Mono): ${ok}`); +mkdirSync(path.dirname(out), { recursive: true }); +await pg.locator('#incident').screenshot({ path: out }); +await browser.close(); +console.log(out); diff --git a/docs/assets/readme/v2/incidents/claude-settings-secrets.png b/docs/assets/readme/v2/incidents/claude-settings-secrets.png new file mode 100644 index 00000000..0d972983 Binary files /dev/null and b/docs/assets/readme/v2/incidents/claude-settings-secrets.png differ diff --git a/tests/test_incident_overlay.py b/tests/test_incident_overlay.py new file mode 100644 index 00000000..1af5c487 --- /dev/null +++ b/tests/test_incident_overlay.py @@ -0,0 +1,63 @@ +"""The incident overlay draws only on the published harness figure, rings only recorded refusals and keeps the product name in the footer.""" + +from __future__ import annotations + +import json +import shutil +import struct +import subprocess + +import pytest +from readme_figure_support import ASSETS, FIGURE, ROOT + +SLUG = "claude-settings-secrets" +SPEC = json.loads((ASSETS / "incidents" / f"{SLUG}.json").read_text(encoding="utf-8")) +PNG = ASSETS / "v2" / "incidents" / f"{SLUG}.png" +POINTS = {p["id"] for p in FIGURE["points"]} + + +def _node(script: str) -> str: + node = shutil.which("node") + if not node: + pytest.skip("node is not installed") + done = subprocess.run( + [node, "--input-type=module", "-e", script], cwd=ROOT, capture_output=True, text=True, check=False + ) + assert done.returncode == 0, done.stderr + return done.stdout + + +def test_png_exists_and_is_the_size_the_page_renders_at() -> None: + assert PNG.stat().st_size > 10_000 + width, height = struct.unpack(">II", PNG.read_bytes()[16:24]) + assert width == 1760 and height > 2000 + + +def test_overlay_builds_without_a_crowded_card_and_edges_match_the_layout() -> None: + script = ( + "import {incident, EDGES} from './docs/assets/readme/incident-overlay.mjs';" + "import {layout, crowded} from './docs/assets/readme/where-chock-sits.mjs';" + "import {readFileSync} from 'node:fs';" + "const r = (p) => JSON.parse(readFileSync(p, 'utf8'));" + f"const W = r('docs/assets/readme/where-chock-sits.json'), S = r('docs/assets/readme/incidents/{SLUG}.json');" + "incident((b) => b, W, S);" + "console.log(JSON.stringify({crowded: crowded(layout(W)), edges: layout(W).segs.length === EDGES.length}));" + ) + assert json.loads(_node(script)) == {"crowded": [], "edges": True} + + +def test_every_ring_is_a_real_badge_and_solid_rings_have_a_recorded_refusal() -> None: + assert {r["point"] for r in SPEC["rings"] + SPEC["dashed"]} <= POINTS + assert not {r["point"] for r in SPEC["rings"]} & {r["point"] for r in SPEC["dashed"]} + assert SPEC["rings"] and SPEC["refusals"] + assert all(r["exit"] == "1" and "Potential secret detected" in r["text"] for r in SPEC["refusals"]) + + +def test_dashed_labels_never_claim_a_catch() -> None: + for ring in SPEC["dashed"]: + assert "could" in ring["label"] and "caught" not in ring["label"] and "refuse" not in ring["label"] + + +def test_the_product_name_is_only_in_the_footer() -> None: + text = json.dumps({k: v for k, v in SPEC.items() if k not in ("_", "footer", "alt")}).lower() + assert "chock" not in text and "chock" in SPEC["footer"].lower()