@agentwhy/cli 0.0.0-dev

package/dist/setup/protected-patterns.js

@@ -0,0 +1,30 @@
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+const LONGEST = 200;
+/** Splits what was typed on commas, and separates what can be written from what cannot. */
+export function patternsIn(typed) {
+    return patternsOf(typed.split(',').map((pattern) => pattern.trim()));
+}
+/** The same rules for patterns given one at a time, as `--protect` gives them. */
+export function patternsOf(given) {
+    const patterns = [];
+    const refused = [];
+    for (const pattern of given.map((one) => one.trim())) {
+        if (pattern === '')
+            continue;
+        const reason = reasonToRefuse(pattern);
+        if (reason !== undefined)
+            refused.push({ pattern, reason });
+        else if (!patterns.includes(pattern))
+            patterns.push(pattern);
+    }
+    return { patterns, refused };
+}
+function reasonToRefuse(pattern) {
+    if (pattern.includes('(') || pattern.includes(')'))
+        return 'a deny rule is written as Read(...), so a bracket cannot be part of the path';
+    if (CONTROL.test(pattern))
+        return 'it holds a character that cannot be in a file name';
+    if (pattern.length > LONGEST)
+        return `it is longer than ${LONGEST} characters`;
+    return undefined;
+}

package/dist/shared/colour.js

@@ -0,0 +1,23 @@
+// `indigo` is the brand colour of the wordmark (`--indigo`, #7C8CF8), as the nearest of the 256 colours every modern
+// terminal has. It marks the tool itself and never an outcome.
+const CODES = {
+    bold: '1',
+    dim: '2',
+    red: '31',
+    green: '32',
+    yellow: '33',
+    indigo: '38;5;105',
+};
+/** Every escape `paint` writes, so that a test - or a reader piping a coloured report on - can remove them. */
+export const ESCAPES = /\u001b\[[0-9;]*m/g;
+/** `text` wrapped in the escape for `hue`. Removing the escapes gives `text` back exactly. */
+export function paint(text, hue) {
+    return text === '' ? text : `\u001b[${CODES[hue]}m${text}\u001b[0m`;
+}
+/**
+ * Whether stdout may be coloured: only when it is a terminal, and never when `NO_COLOR` holds anything but the
+ * empty string, which is how no-color.org defines it. Flags narrow this further; nothing widens it.
+ */
+export function colourWanted(stdoutIsTerminal, noColor) {
+    return stdoutIsTerminal && (noColor === undefined || noColor === '');
+}

package/dist/shared/compare.js

@@ -0,0 +1,4 @@
+/** Orders strings by UTF-16 code units — the order `Array.prototype.sort` uses without a comparator. */
+export function byString(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/shared/content-version.js

@@ -0,0 +1,13 @@
+/**
+ * A short name for a content, so that two contents can be told apart without keeping either (`live-pages` L1). FNV-1a,
+ * 32 bits, in base 36: it guards nothing - a page only asks "is my file still what I was sent?" - and a collision costs
+ * one update shown two seconds late, never a wrong answer about a session.
+ */
+export function contentVersion(text) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(36);
+}

package/dist/shared/counter.js

@@ -0,0 +1,11 @@
+import { byString } from './compare.js';
+/** Counts occurrences per key and reports them sorted by key, so the same input always yields the same output. */
+export class Counter {
+    #counts = new Map();
+    add(key) {
+        this.#counts.set(key, (this.#counts.get(key) ?? 0) + 1);
+    }
+    toCounts() {
+        return Object.fromEntries([...this.#counts.keys()].sort(byString).map((key) => [key, this.#counts.get(key) ?? 0]));
+    }
+}

package/dist/shared/file-stamp.js

@@ -0,0 +1,4 @@
+/** A moment as part of a file name: it sorts by time, and holds no character a file system refuses. */
+export function fileStamp(now) {
+    return new Date(now).toISOString().replace(/[:.]/g, '-');
+}

package/dist/shared/json.js

@@ -0,0 +1,13 @@
+export function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parses text that should hold a JSON object. Invalid JSON and any other JSON value yield undefined. */
+export function parseJsonObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return isJsonObject(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/shared/label.js

@@ -0,0 +1,13 @@
+// Labels come only from structural positions: keys, line types, tool names, enumerations. A label must look
+// like an identifier, and anything else is replaced, so free text cannot reach the output even from a
+// malformed transcript. Known limit: an identifier-shaped secret placed in a structural position would pass;
+// recognising secrets is the job of the secret scanner (spec §5.4), not of this guard.
+const LABEL_PATTERN = /^[A-Za-z0-9_.:-]{1,64}$/;
+export const ABSENT_LABEL = '(absent)';
+export const INVALID_LABEL = '(invalid)';
+export function toLabel(value) {
+    if (value === undefined)
+        return ABSENT_LABEL;
+    const text = typeof value === 'number' || typeof value === 'boolean' ? String(value) : value;
+    return typeof text === 'string' && LABEL_PATTERN.test(text) ? text : INVALID_LABEL;
+}

package/dist/shared/package-name.js

@@ -0,0 +1,6 @@
+/**
+ * The name agentwhy is published under. npm refuses the unscoped `agentwhy` as too close to `agent-why`, so the package
+ * is scoped while the command it installs stays `agentwhy`. Written into a hook by the finder and read back from one by
+ * the settings adapter (`a-hook-runs-what-you-ran.md` J2, `nothing-updates-by-itself.md` U1).
+ */
+export const PACKAGE = '@agentwhy/cli';

package/dist/shared/plain-invocation.js

@@ -0,0 +1,44 @@
+import { PACKAGE } from './package-name.js';
+/**
+ * What separates two words: a space or a tab, the only characters a shell splits on. Found by a review: `\s` also takes
+ * a non-breaking space, a line break and the like, so `npx<NBSP>@agentwhy/cli` read as two words here and ran as one
+ * relative path in the shell, and a second line passed for the flags of the first.
+ */
+export const WORD_BREAK = '[ \\t]+';
+/** `npx`, with `--yes` or `-y`, up to the package's name: what the pinned form (`hook-entries.ts`) is read after too. */
+export const NPX_BEFORE_NAME = `npx(?:${WORD_BREAK}(?:--yes|-y))?${WORD_BREAK}`;
+/** A version after `@`, as plain words allow one: `0.3.0`, `0.3.0-beta.1`, `latest`. */
+export const VERSION = '[\\w.+-]+';
+/**
+ * One segment of an absolute path: no space, quote, variable, `~` or anything else a shell reads as more, and not `.`
+ * or `..`, which lead back up to where a path is not what it says.
+ */
+const SEGMENT = '(?!\\.\\.?(?![\\w@%+=:,.-]))[\\w@%+=:,.-]+';
+/**
+ * Where an absolute path may start: anywhere but `/proc` and `/dev`. Found by a review: `/proc/self/cwd/…` is absolute
+ * and is the working directory - on Linux, the project a hook runs in - and `/dev/fd/…` is a file already open.
+ */
+const ROOTED = '(?!/(?:proc|dev)/)';
+/**
+ * agentwhy named in plain words (`a-hook-runs-what-you-ran.md` J4, `the-agent-tells-you.md` R18), as a pattern's source
+ * with no anchors: `agentwhy` or an absolute path to its bin; `npx`, with `--yes` or `-y`, before the published name or
+ * the unscoped `agentwhy`, either with a version; or `node` before an absolute path to agentwhy's own entry - its bin,
+ * or `dist/cli.js` or `src/cli.ts` under a folder with agentwhy in its name.
+ *
+ * Found by a review: any word that merely held agentwhy was taken, so a cloned project's settings could have
+ * `npx @someone/agentwhy`, `npx agentwhy-helper` or `node --require=./x/agentwhy.js` repeated into the person's own
+ * hooks and handed to the agent. A name is now one agentwhy publishes, and a path is absolute - a relative one runs a
+ * file of the project the settings came from, and `~` a guessable one. A second review: after `node`, any absolute
+ * path with agentwhy in it passed, `/tmp/agentwhy-x.js` too, and an agent can write that file itself. A shape only
+ * narrows this - a folder laid out like the package passes - it does not prove the file is agentwhy's.
+ */
+export const PLAIN_INVOCATION_SOURCE = [
+    `(?:${ROOTED}(?:/${SEGMENT})*/)?agentwhy`,
+    `${NPX_BEFORE_NAME}(?:${PACKAGE}|agentwhy)(?:@${VERSION})?`,
+    `node${WORD_BREAK}${ROOTED}(?:/${SEGMENT})*/(?:[\\w@%+=:,.-]*agentwhy[\\w@%+=:,.-]*(?:/${SEGMENT})*/(?:dist/cli\\.js|src/cli\\.ts)|agentwhy)`,
+].join('|');
+const PLAIN_INVOCATION = new RegExp(`^(?:${PLAIN_INVOCATION_SOURCE})$`);
+/** Whether a command's invocation, the words before its subcommand, runs agentwhy in plain words and nothing else. */
+export function isPlainInvocation(invocation) {
+    return PLAIN_INVOCATION.test(invocation);
+}

package/dist/shared/plain-version.js

@@ -0,0 +1,21 @@
+const PLAIN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/**
+ * `x.y.z` and nothing else. A pre-release (`0.3.0-beta.1`), a build (`0.0.0-dev`) or a range is not plain: no rule here
+ * orders one against a release, so none is guessed (`nothing-updates-by-itself.md` U1, U2).
+ */
+export function plainVersion(text) {
+    const match = PLAIN.exec(text);
+    return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** Whether `version` is an older release than `than`. False where either is not plain: unknown is never older. */
+export function isOlder(version, than) {
+    const a = plainVersion(version);
+    const b = plainVersion(than);
+    if (a === undefined || b === undefined)
+        return false;
+    for (let part = 0; part < 3; part += 1) {
+        if (a[part] !== b[part])
+            return (a[part] ?? 0) < (b[part] ?? 0);
+    }
+    return false;
+}

package/dist/shared/printable.js

@@ -0,0 +1,25 @@
+/**
+ * Text from a file as a terminal may be shown it: every character a terminal obeys rather than draws, as a space. A
+ * settings file, a transcript and a folder's name all arrive from outside this tool - a committed settings file and a
+ * folder's name with a clone - so an escape sequence in one would be run: `\u001b[2K\u001b[1G` rewrites the line a person
+ * reads to decide what to do next.
+ *
+ * The marks that turn the direction of text, and the separators that break a line, go too. Found by a review: they are
+ * no control characters, so `Stop\u{202e}…` in a committed key showed the rest of its line reversed in the plan a person
+ * reads before "Update it?". A second review found the title of a session and the name of a folder guarded by rules of
+ * their own, or none, so there is one set of rules for every place. Letters of any script are left as they are.
+ */
+export function printable(text) {
+    return text.replace(/[\u0000-\u001f\u007f-\u009f\u{061c}\u{200e}\u{200f}\u{2028}\u{2029}\u{202a}-\u{202e}\u{2066}-\u{2069}]/gu, ' ');
+}
+/**
+ * One line of plain words, for a title drawn in a list: `printable`, with the spaces it leaves - a line break among them,
+ * which would split one row in two - run together. Found by a review: a title guarded against control characters alone
+ * reached the `sessions` chooser with a mark that turns the direction of text.
+ */
+export function oneLine(text) {
+    return printable(text)
+        .split(' ')
+        .filter((word) => word !== '')
+        .join(' ');
+}

package/dist/shared/renderer.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/sentence.js

@@ -0,0 +1,20 @@
+/**
+ * The first sentence of a piece of writing, capped (`specs/2026-09-15-why-this-call.md` §5.1, level B). Measured on one
+ * session: 311 of 315 first sentences run under 200 characters, so the cap is rarely reached - and when
+ * it is, the cut is reported rather than hidden, because a truncation read as a whole thought is a lie about the
+ * record.
+ */
+export const SENTENCE_CAP = 200;
+const ENDS = /[.!?](\s|$)/;
+export function firstSentence(text, cap = SENTENCE_CAP) {
+    const written = text.trim().replace(/\s+/g, ' ');
+    const line = written.split('\n')[0] ?? written;
+    const end = ENDS.exec(line);
+    const sentence = end === null ? line : line.slice(0, end.index + 1);
+    if (sentence.length <= cap)
+        return { text: sentence, cut: sentence.length < written.length && end === null };
+    // Cut at a word, not inside one: a half word reads as a typo rather than as a cut.
+    const room = sentence.slice(0, cap);
+    const space = room.lastIndexOf(' ');
+    return { text: (space > cap / 2 ? room.slice(0, space) : room).trimEnd(), cut: true };
+}

package/dist/shared/terminal-logo.js

@@ -0,0 +1,41 @@
+import { paint } from './colour.js';
+/**
+ * The agentwhy wordmark for a terminal: the letters of `agentwhy-logo-transparent.svg` in two rows of block
+ * characters, "agent" in the text colour and "why" in the brand indigo, as the page draws them.
+ */
+const ROWS = [
+    { agent: '▄▀█ █▀▀ █▀▀ █▄ █ ▀█▀', why: '█ █ █ █ █ █▄█' },
+    { agent: '█▀█ █▄█ ██▄ █ ▀█  █ ', why: '▀▄▀▄▀ █▀█  █ ' },
+];
+/** The name in letters, for a terminal trusted with ASCII alone (§7.5 constraint 2). */
+const NAME = 'agentwhy';
+/** Between the mark and the words beside it. */
+const BESIDE = '   ';
+/** What the tool is for, in the words its package describes it with. Said beside the mark wherever it is drawn. */
+export const TAGLINE = 'why an agent reached for protected data';
+/** How many columns the mark takes, gap included, before the words beside it start. */
+export function logoWidth(ascii) {
+    const mark = ascii ? NAME.length : Math.max(...ROWS.map(({ agent, why }) => agent.length + 1 + why.length));
+    return mark + BESIDE.length;
+}
+/**
+ * The mark, one string per row, with up to two lines of words beside it: the mark shares its rows rather than
+ * pushing everything below it further down. Colour only repeats what is drawn - removing the escapes gives exactly
+ * the rows drawn without it.
+ */
+export function terminalLogo(beside, view) {
+    if (view.ascii) {
+        if (beside.length === 0)
+            return [NAME];
+        return beside.map((words, row) => `${row === 0 ? NAME : ' '.repeat(NAME.length)}${BESIDE}${words}`);
+    }
+    return ROWS.map(({ agent, why: letters }, row) => {
+        const words = beside[row] ?? '';
+        // A row with nothing beside it ends where the letters do, not in the padding that keeps two rows level.
+        const why = words === '' ? letters.trimEnd() : letters;
+        const mark = view.colour ? `${paint(agent, 'bold')} ${paint(why, 'indigo')}` : `${agent} ${why}`;
+        if (words === '')
+            return mark;
+        return `${mark}${BESIDE}${view.colour ? paint(words, 'dim') : words}`;
+    });
+}

package/dist/shared/text-table.js

@@ -0,0 +1,15 @@
+import { byString } from './compare.js';
+const EMPTY_COUNTS = '(none)';
+/** Rows with their labels aligned into one column. */
+export function table(rows, indentWidth) {
+    const width = Math.max(...rows.map(([label]) => label.length));
+    return rows.map(([label, value]) => `${' '.repeat(indentWidth)}${label.padEnd(width)}  ${value}`);
+}
+/** Counts as a table, largest first and ties by key, with the numbers right-aligned. */
+export function countsTable(values, indentWidth) {
+    const entries = Object.entries(values).sort(([keyA, a], [keyB, b]) => b - a || byString(keyA, keyB));
+    if (entries.length === 0)
+        return [`${' '.repeat(indentWidth)}${EMPTY_COUNTS}`];
+    const width = Math.max(...entries.map(([, value]) => String(value).length));
+    return table(entries.map(([key, value]) => [key, String(value).padStart(width)]), indentWidth);
+}

package/dist/shared/wrap.js

@@ -0,0 +1,29 @@
+/**
+ * Breaks text into lines that fit a width, at spaces where it can and inside a long run where it must - a URL
+ * or a path is never silently truncated, because a report that hides half a finding is worse than a wide line.
+ */
+export function wrap(text, width) {
+    const usable = Math.max(width, 8);
+    return text.split('\n').flatMap((paragraph) => wrapParagraph(paragraph, usable));
+}
+function wrapParagraph(paragraph, width) {
+    const lines = [];
+    let current = '';
+    for (const word of paragraph.split(/\s+/).filter((part) => part !== '')) {
+        if (current === '')
+            current = word;
+        else if (`${current} ${word}`.length <= width)
+            current = `${current} ${word}`;
+        else {
+            lines.push(current);
+            current = word;
+        }
+        while (current.length > width) {
+            lines.push(current.slice(0, width));
+            current = current.slice(width);
+        }
+    }
+    if (current !== '')
+        lines.push(current);
+    return lines.length === 0 ? [''] : lines;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@agentwhy/cli",
+  "version": "0.0.0-dev",
+  "description": "Reconstructs from transcripts why an AI agent reached for protected data",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karolkozer/agentwhy.git"
+  },
+  "homepage": "https://github.com/karolkozer/agentwhy#readme",
+  "bugs": {
+    "url": "https://github.com/karolkozer/agentwhy/issues"
+  },
+  "bin": {
+    "agentwhy": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=23.6",
+      "onFail": "warn"
+    }
+  },
+  "scripts": {
+    "doctor": "node src/cli.ts doctor",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "check:canary": "node scripts/check-canary.mjs",
+    "snapshot:doctor": "node src/cli.ts doctor --input tests/fixtures/redacted/951c4f76-9d2a-40d2-9c76-1e57cf47ae4e --json > tests/fixtures/doctor-report.snapshot.json",
+    "golden:report": "node scripts/regenerate-golden.mjs",
+    "demo:report": "node scripts/generate-dashboard-demo.mjs",
+    "demo:index": "node scripts/generate-index-demo.mjs",
+    "demo:settings": "node scripts/generate-settings-demo.mjs",
+    "demo:to-fix": "node scripts/generate-to-fix-demo.mjs",
+    "demo:onboarding": "node scripts/generate-onboarding-demo.mjs",
+    "demo:month": "node scripts/generate-month-demo.mjs",
+    "demo:report-page": "node scripts/generate-report-page-demo.mjs",
+    "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "prepack": "rm -rf dist && npm run build",
+    "check:package": "node scripts/check-package.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "agents",
+    "secrets",
+    "audit",
+    "postmortem"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1"
+  }
+}