friction-log 0.0.0-stage → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to `friction-log` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.6.1] - 2026-10-10
+
+First release cut for the tag-driven `publish-npm.yml` workflow (npm Trusted Publishing), which publishes with `--provenance`.
+
+### Fixed
+
+- The CLI now refuses to start on a Node version below the `engines.node` range (currently `>=22`), exiting 1 with a stderr message that names the required and the running version. Previously npm only warned, and the first database command crashed with a SIGSEGV. The check runs in a small entry module (`dist/cli.js`) before the real CLI, and thus `better-sqlite3`, is loaded; `--help` and `--version` are refused as well. (11dc376f)
+
+## [0.6.0] - 2026-10-10
+
+First release published to npm (`npm i -g friction-log`). Earlier versions ran from a local build of this repository. The entries below cover everything since the 0.5.0 milestone tag.
+
+0.6.0 was published by hand from a build of commit `48926fca`, because npm accepts a Trusted Publisher entry only for a package that already exists; it therefore has no provenance attestation. There is deliberately no `friction-log/v0.6.0` git tag: pushing it would trigger `publish-npm.yml`, which refuses a registry version without an attestation and would fail red.
+
+### Added
+
+- Opt-in `sync_export` config block and a `sync-export` command: a deterministic, atomic, no-op-skipping export of the local database, written through after each of the six mutating commands (`log`, `update`, `rm`, `file`, `import`, `scan`). Without the config block everything is an exact no-op. See [sync export](docs/sync-export.md).
+- `digest --include-peers`: merges the exports of other machines into the digest, with origin-labeled sections, by replaying them into an in-memory database and reusing the regular digest query.
+- The npm package ships `LICENSE`, `README.md`, and this changelog next to `dist/` and `templates/`.
+
+### Changed
+
+- `engines.node` is now `>=22`, matching `better-sqlite3` 13 (which declares `>=22` and ships prebuilt binaries inside its own package, so the install needs no compiler and no download step). Node 20 is no longer a supported runtime.
+
+### Fixed
+
+- `log --session <id>` no longer fails with a raw `FOREIGN KEY constraint failed` when the session id is not yet in the `sessions` table: the row is now created before the friction is inserted.
+- `better-sqlite3` is bumped to `^13`, so the package installs on Node 26. `^11` has no prebuilt binary for that ABI and its source build fails against Node 26's V8 headers.
+
+### Security
+
+Runtime (shipped):
+
+- The declared `yaml` floor is raised to `^2.8.3` so installs cannot resolve an older release. The lockfile already resolved 2.9.0, so only the declared range changes.
+- `better-sqlite3` moves from 11.10.0 to 13.0.1 (see Changed and Fixed). Its install-time download chain (`prebuild-install`, `tar-fs`, `rc`, `minimist`, and related packages) is gone from the lockfile.
+
+Development-only (not shipped, not part of the published package):
+
+- `tsx` to `^4.22.4` (resolved 4.22.4), which pulls `esbuild` 0.28.1.
+- `vitest` to `^4.1.6` (resolved 4.1.11) and `vite` to 8.3.0, now built on `rolldown` 1.2.8 instead of `rollup`.
+- Lockfile bumps for `nanoid`, `postcss`, `source-map-js`, `picomatch`, and `tinyglobby`.
+
+### Notes
+
+Node 20 is unsupported: `better-sqlite3` 13 requires Node 22 or newer, and on Node 20 the process crashes with SIGSEGV on the first database command.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lan Nguyen Si
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# friction-log
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Capture, query, and infer agent-workflow frictions. SQLite-backed, sink-pluggable, zero-config default.
+
+> Most agent tooling helps a model *write* the code. `friction-log` keeps a structured record of the moments where the agent's tools, MCP verbs, or harness behave unexpectedly, so the friction doesn't evaporate between sessions and the dogfood loop stays honest.
+
+## Overview
+
+Two recurring patterns in agent-driven development go unaddressed by most tooling: the per-friction reflex (the agent notices a tool acting unexpectedly mid-task, mentally notes it, then moves on and the note evaporates) and the end-of-session bilanz (a retrospective naming tools exercised, frictions observed, tasks filed, easy to skip if nothing makes it cheap). `friction-log` lowers the cost of both: a one-line `log` for the per-moment capture, a one-command `file` to push the friction into whatever issue tracker the team uses, and a passive Stop-hook scan plus `bilanz` so missed frictions still get a second chance at the session boundary. The data isn't the goal; the goal is the inferences a few weeks of accumulated data enable (which tools cause the most friction, which categories recur, how long frictions take to become fixes), which is why the schema (SQLite + FTS5) is the foundation everything else builds on.
+
+**Status:** M5 (this release) completes the v1 surface. `init` writes a YAML config and optionally installs the Claude Code Stop-hook in one command (with a `--yes` non-interactive mode for scripted bootstrap). `import --format markdown-frontmatter <dir>` bulk-loads existing markdown notes into the database, idempotent on re-run via a content-hash dedup. Four templates round out the v1 set (`tool-missing-capability`, `auth-expiry`, `schema-drift`, `doc-gap`), all auto-picked by matching the friction's `category`.
+
+## Key features
+
+- One-command `init`: detects the local environment and writes config, optionally installing the Claude Code Stop-hook
+- Structured `log`, `list`, `search` (FTS5), `export`, and `digest` (aggregations) over a local SQLite store
+- Five pluggable filing sinks: `markdown-file` (default, zero-dependency), `stdout-json`, `github-issues`, `agent-tasks`, `linear`
+- Idempotent `scan` of Claude Code transcripts (deduped on session, tool, and title) and `import` of existing markdown notes (content-hash deduped)
+- Optional multi-machine `sync-export`: deterministic, config-gated JSON file dump with read-only peer merge into `digest`
+- Auto-linked recurrence detection on repeated (tool, title) matches
+
+## Install / quick start
+
+Install from npm (Node.js 22 or later):
+
+```bash
+npm i -g friction-log
+friction-log --version
+
+# Log a friction you noticed
+friction-log log \
+  --title "tasks_list returns 149kB blob" \
+  --tool "mcp:agent-tasks/tasks_list" \
+  --category output-overflow \
+  --severity high
+
+# See it in the local database
+friction-log list
+
+# Render and file it via the default markdown sink
+friction-log file 1
+```
+
+The global install puts a `friction-log` command on PATH, which the Stop-hook below needs.
+
+To run from a local build instead (for development on this repository):
+
+```bash
+git clone https://github.com/LanNguyenSi/agent-dx && cd agent-dx
+cd packages/friction-log && npm install && npm run build
+node dist/cli.js --help
+```
+
+A markdown record lands under `~/.local/share/friction-log/frictions/` with full frontmatter, ready to commit, paste into a chat, or pipe into another tool.
+
+## Usage
+
+Wire automatic capture into every Claude Code session with a Stop-hook, then review with `bilanz`:
+
+```jsonc
+// ~/.claude/settings.json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "friction-log scan --silent --stdin-payload" }]
+      }
+    ]
+  }
+}
+```
+
+```bash
+friction-log bilanz
+```
+
+See [Command reference](./docs/commands.md) for every subcommand, including manual transcript scanning; run any command with `--help` for its complete flag list.
+
+## Documentation
+
+- [Command reference](./docs/commands.md): full subcommand table, Stop-hook wiring, manual scan, templates
+- [Sinks](./docs/sinks.md): configuration for `markdown-file`, `stdout-json`, `github-issues`, `agent-tasks`, `linear`
+- [Sync-export](./docs/sync-export.md): optional multi-machine file merge, format, and write-through semantics
+- [Storage](./docs/storage.md): SQLite schema and `recurrence_of_id` matching rule
+- [Design notes](./docs/design.md): ADR for the sink options bag, roadmap, and how this relates to `slop-detector`
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Entry point. Static imports are evaluated before any code in the importing
+// module, and the real CLI reaches better-sqlite3 through them. So this file
+// imports only the dependency-free guard and loads the CLI dynamically after
+// the Node version check has passed.
+import { nodeGuardMessage, readEnginesNode } from "./node-guard.js";
+const message = nodeGuardMessage(process.versions.node, readEnginesNode());
+if (message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+await import("./main.js");
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,qCAAqC;AACrC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEpE,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;AAC3E,IAAI,OAAO,EAAE,CAAC;IACZ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AACD,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC"}

package/dist/commands/bilanz.d.ts

@@ -0,0 +1,23 @@
+import type { Friction, Session, Task } from "../types.js";
+export interface BilanzCommandInput {
+    sessionId?: string;
+    dbPath?: string;
+}
+export interface BilanzCommandOutput {
+    session: Session;
+    toolsExercised: string[];
+    frictions: Array<Friction & {
+        tasks: Task[];
+    }>;
+    formatted: string;
+}
+export declare function runBilanz(input: BilanzCommandInput): Promise<BilanzCommandOutput>;
+interface BilanzInput {
+    session: Session;
+    toolsExercised: string[];
+    frictions: Array<Friction & {
+        tasks: Task[];
+    }>;
+}
+export declare function formatBilanz(b: BilanzInput): string;
+export {};

package/dist/commands/bilanz.js

@@ -0,0 +1,106 @@
+import { FrictionDb } from "../db.js";
+import { defaultDbPath } from "../paths.js";
+import { loadScanner } from "../scanners/index.js";
+export async function runBilanz(input) {
+    const db = new FrictionDb(input.dbPath ?? defaultDbPath());
+    try {
+        const session = input.sessionId
+            ? db.getSession(input.sessionId)
+            : db.getMostRecentSession();
+        if (!session) {
+            throw new Error(input.sessionId
+                ? `friction-log: session ${input.sessionId} not found in db`
+                : `friction-log: no sessions in db yet. Run friction-log scan first.`);
+        }
+        const frictions = db.listFrictionsForSession(session.id);
+        const withTasks = frictions.map((f) => ({
+            ...f,
+            tasks: db.listTasksForFriction(f.id),
+        }));
+        const toolsExercised = await extractToolsExercised(session);
+        const formatted = formatBilanz({
+            session,
+            toolsExercised,
+            frictions: withTasks,
+        });
+        return { session, toolsExercised, frictions: withTasks, formatted };
+    }
+    finally {
+        db.close();
+    }
+}
+async function extractToolsExercised(session) {
+    if (!session.transcriptPath)
+        return [];
+    try {
+        const scanner = loadScanner(session.adapter);
+        const result = await scanner.scan({
+            sessionId: session.id,
+            transcriptPath: session.transcriptPath,
+        });
+        const tools = new Set();
+        for (const c of result.frictionCandidates) {
+            if (c.toolSurface)
+                tools.add(c.toolSurface);
+        }
+        return [...tools].sort();
+    }
+    catch {
+        return [];
+    }
+}
+export function formatBilanz(b) {
+    const lines = [];
+    lines.push(`## Dogfood bilanz`);
+    lines.push("");
+    lines.push(`Session: \`${b.session.id}\` (${b.session.startedAt}${b.session.endedAt ? ` to ${b.session.endedAt}` : ""})`);
+    if (b.session.projectPaths && b.session.projectPaths.length > 0) {
+        lines.push(`Project paths: ${b.session.projectPaths.map((p) => `\`${p}\``).join(", ")}`);
+    }
+    lines.push("");
+    lines.push(`**Tools exercised** (${b.toolsExercised.length}):`);
+    if (b.toolsExercised.length === 0) {
+        lines.push("  _none captured by the scan adapter_");
+    }
+    else {
+        for (const t of b.toolsExercised) {
+            lines.push(`  - ${t}`);
+        }
+    }
+    lines.push("");
+    const filed = b.frictions.filter((f) => f.tasks.length > 0);
+    const unfiled = b.frictions.filter((f) => f.tasks.length === 0 && f.status === "open");
+    lines.push(`**Frictions noticed** (${b.frictions.length}):`);
+    if (b.frictions.length === 0) {
+        lines.push("  _none recorded for this session_");
+    }
+    else {
+        for (const f of b.frictions) {
+            const marker = f.tasks.length > 0 ? "filed" : f.status;
+            lines.push(`  - [${marker}] id=${f.id} ${f.toolSurface ? `(${f.toolSurface}) ` : ""}${f.title}`);
+        }
+    }
+    lines.push("");
+    lines.push(`**Tasks filed** (${filed.length}):`);
+    if (filed.length === 0) {
+        lines.push("  _none yet_");
+    }
+    else {
+        for (const f of filed) {
+            for (const t of f.tasks) {
+                const ref = t.externalRef ?? t.sinkTarget ?? "?";
+                lines.push(`  - friction id=${f.id} -> ${t.sinkName}: ${ref}`);
+            }
+        }
+    }
+    lines.push("");
+    if (unfiled.length > 0) {
+        lines.push(`**Open frictions without a filed task** (${unfiled.length}) -- consider \`friction-log file <id>\`:`);
+        for (const f of unfiled) {
+            lines.push(`  - id=${f.id} ${f.toolSurface ? `(${f.toolSurface}) ` : ""}${f.title}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+//# sourceMappingURL=bilanz.js.map

package/dist/commands/bilanz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bilanz.js","sourceRoot":"","sources":["../../src/commands/bilanz.ts"],"names":[],"mappings":"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"}

package/dist/commands/digest.d.ts

@@ -0,0 +1,36 @@
+import { type DigestGroupBy, type DigestRow } from "../db.js";
+export interface DigestCommandInput {
+    groupBy: DigestGroupBy;
+    last?: string;
+    dbPath?: string;
+    configPath?: string;
+    includePeers?: boolean;
+}
+/**
+ * One peer's contribution to `digest --include-peers`. `rows` is always
+ * computed with the identical GROUP BY SQL as the local digest (see
+ * buildPeerSection), so the two are directly comparable, except for the
+ * `recurrences` column which is patched in from the raw export data (see
+ * countPeerRecurrences). A missing/corrupt peer file degrades to an empty,
+ * error-annotated section rather than throwing; a peer file with some
+ * malformed individual records degrades those specific records only,
+ * reported via `skipped`.
+ */
+export interface DigestPeerSection {
+    origin: string;
+    sourcePath: string;
+    rows: DigestRow[];
+    /** Count of raw entries in the peer's `records` array that failed
+     * validation (missing/non-string title, unknown status, unparseable
+     * capturedAt) and were dropped rather than silently miscounted. */
+    skipped: number;
+    error?: string;
+}
+export interface DigestCommandOutput {
+    groupBy: DigestGroupBy;
+    sinceIso: string | null;
+    rows: DigestRow[];
+    peers?: DigestPeerSection[];
+}
+export declare function runDigest(input: DigestCommandInput): DigestCommandOutput;
+export declare function formatDigest(output: DigestCommandOutput): string;

package/dist/commands/digest.js

@@ -0,0 +1,288 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { loadConfig } from "../config.js";
+import { FrictionDb } from "../db.js";
+import { defaultDbPath } from "../paths.js";
+import { parseAge } from "./list.js";
+export function runDigest(input) {
+    const db = new FrictionDb(input.dbPath ?? defaultDbPath());
+    try {
+        const sinceIso = parseAge(input.last) ?? null;
+        const rows = db.digest(input.groupBy, sinceIso ?? undefined);
+        const out = { groupBy: input.groupBy, sinceIso, rows };
+        if (input.includePeers) {
+            const config = loadConfig(input.configPath);
+            const peerPaths = config.syncExport?.peerPaths ?? [];
+            out.peers = peerPaths.map((p) => buildPeerSection(p, input.groupBy, sinceIso));
+        }
+        return out;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Validates one raw JSON array entry from a peer's `records`. Returns null
+ * (caller counts it as `skipped`) rather than silently defaulting a bad
+ * field, because a wrong default here would otherwise corrupt the digest
+ * numbers without any visible sign: an unknown/missing `status` used to
+ * fall through to the db's default of 'open', and a non-ISO `capturedAt`
+ * used to pass a `--last` window check unpredictably (it is compared as a
+ * plain string against another ISO string, and most garbage strings sort
+ * after any real date).
+ */
+function normalizePeerRecord(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const rec = raw;
+    if (typeof rec.title !== "string" || rec.title.trim() === "")
+        return null;
+    if (!isFrictionStatus(rec.status))
+        return null;
+    if (typeof rec.capturedAt !== "string")
+        return null;
+    // Lenient on input, canonical in storage: Date.parse accepts many
+    // non-ISO spellings ('Jan 1 1999'), and every downstream comparison
+    // (--last windows, recurrence cutoffs) is a plain string compare
+    // against ISO timestamps — so a parseable-but-non-ISO value must be
+    // re-rendered as ISO or it sorts above every real date.
+    const capturedAtDate = new Date(rec.capturedAt);
+    if (Number.isNaN(capturedAtDate.getTime()))
+        return null;
+    return {
+        toolSurface: typeof rec.toolSurface === "string" ? rec.toolSurface : null,
+        title: rec.title,
+        description: typeof rec.description === "string" ? rec.description : null,
+        capturedAt: capturedAtDate.toISOString(),
+        severity: isSeverity(rec.severity) ? rec.severity : null,
+        category: typeof rec.category === "string" ? rec.category : null,
+        status: rec.status,
+        // Unlike status/capturedAt/title, an invalid severity or source
+        // degrades gracefully to a legitimate "unknown" value instead of
+        // dropping the whole record: severity is already nullable in the
+        // schema, and 'import' is a real, meaningful "unclassified" source.
+        source: isFrictionSource(rec.source) ? rec.source : "import",
+        recurrenceOfId: typeof rec.recurrenceOfId === "number" ? rec.recurrenceOfId : null,
+    };
+}
+/**
+ * Reads one peer's sync-export JSON (read-only; never mutates it), replays
+ * its valid records into a throwaway :memory: FrictionDb via insertFriction,
+ * and reuses db.digest() so peer totals/open/filed/resolved/wontfix/
+ * avg-hours numbers are computed with exactly the same SQL as the local
+ * digest. `tasks` is never populated for peer data (the export payload
+ * carries no task history), so avgHoursToTriage is always null for peer
+ * rows: expected, not a bug.
+ *
+ * `recurrences` is the one column NOT taken from the scratch db's own
+ * recurrence_of_id (see countPeerRecurrences for why) and is patched onto
+ * the rows afterward.
+ */
+function buildPeerSection(peerPath, groupBy, sinceIso) {
+    const fallbackOrigin = basename(peerPath);
+    let raw;
+    try {
+        raw = readFileSync(peerPath, "utf8");
+    }
+    catch (err) {
+        return {
+            origin: fallbackOrigin,
+            sourcePath: peerPath,
+            rows: [],
+            skipped: 0,
+            error: `could not read peer file: ${err.message}`,
+        };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            origin: fallbackOrigin,
+            sourcePath: peerPath,
+            rows: [],
+            skipped: 0,
+            error: `could not parse peer file as JSON: ${err.message}`,
+        };
+    }
+    const origin = typeof payload.origin === "string" && payload.origin.trim()
+        ? payload.origin
+        : fallbackOrigin;
+    if (!Array.isArray(payload.records)) {
+        return {
+            origin,
+            sourcePath: peerPath,
+            rows: [],
+            skipped: 0,
+            error: 'peer file is missing a "records" array',
+        };
+    }
+    let skipped = 0;
+    const validRecords = [];
+    for (const rawRecord of payload.records) {
+        const normalized = normalizePeerRecord(rawRecord);
+        if (!normalized) {
+            skipped++;
+            continue;
+        }
+        validRecords.push(normalized);
+    }
+    const scratch = new FrictionDb(":memory:");
+    try {
+        for (const rec of validRecords) {
+            const inserted = scratch.insertFriction({
+                toolSurface: rec.toolSurface,
+                title: rec.title,
+                description: rec.description,
+                capturedAt: rec.capturedAt,
+                severity: rec.severity,
+                category: rec.category,
+                source: rec.source,
+            });
+            if (rec.status !== "open") {
+                scratch.updateFrictionStatus(inserted.id, rec.status);
+            }
+        }
+        const rows = scratch.digest(groupBy, sinceIso ?? undefined);
+        const recurrenceCounts = countPeerRecurrences(validRecords, groupBy, sinceIso);
+        const withRecurrences = rows.map((r) => ({
+            ...r,
+            recurrences: recurrenceCounts.get(r.group) ?? 0,
+        }));
+        return { origin, sourcePath: peerPath, rows: withRecurrences, skipped };
+    }
+    catch (err) {
+        return {
+            origin,
+            sourcePath: peerPath,
+            rows: [],
+            skipped,
+            error: `could not replay peer records: ${err.message}`,
+        };
+    }
+    finally {
+        scratch.close();
+    }
+}
+/**
+ * Derives the `recurrences` count directly from the exported records' own
+ * `recurrenceOfId !== null` flag, grouped exactly like db.digest()'s SQL
+ * (`coalesce(column, '(unset)')`) and filtered by the same `--last` window.
+ *
+ * This does NOT read the scratch db's recurrence_of_id column, and
+ * deliberately never re-derives or dereferences one. Two independent
+ * reasons: (1) a peer's numeric recurrenceOfId is a different machine's
+ * AUTOINCREMENT id, meaningless (and possibly FK-invalid) once replayed
+ * into another database; (2) recomputing it via insertFriction's own
+ * open-root heuristic against the replayed subset actively disagrees with
+ * the origin's real bookkeeping (a friction the origin explicitly linked as
+ * a recurrence can fail to re-derive as one once replayed with a different
+ * insertion order or status mix, silently changing the count). Counting the
+ * boolean flag from the source data sidesteps both problems.
+ */
+function countPeerRecurrences(records, groupBy, sinceIso) {
+    const counts = new Map();
+    for (const rec of records) {
+        if (sinceIso && rec.capturedAt < sinceIso)
+            continue;
+        if (rec.recurrenceOfId == null)
+            continue;
+        const group = groupValueFor(rec, groupBy);
+        counts.set(group, (counts.get(group) ?? 0) + 1);
+    }
+    return counts;
+}
+function groupValueFor(rec, groupBy) {
+    switch (groupBy) {
+        case "tool":
+            return rec.toolSurface ?? "(unset)";
+        case "category":
+            return rec.category ?? "(unset)";
+        case "severity":
+            return rec.severity ?? "(unset)";
+        case "source":
+            return rec.source;
+    }
+}
+const SEVERITIES = ["low", "medium", "high", "critical"];
+const SOURCES = ["scan", "manual", "import"];
+const STATUSES = [
+    "open",
+    "filed",
+    "resolved",
+    "wontfix",
+];
+function isSeverity(v) {
+    return typeof v === "string" && SEVERITIES.includes(v);
+}
+function isFrictionSource(v) {
+    return typeof v === "string" && SOURCES.includes(v);
+}
+function isFrictionStatus(v) {
+    return typeof v === "string" && STATUSES.includes(v);
+}
+export function formatDigest(output) {
+    const { groupBy, sinceIso, rows, peers } = output;
+    const window = sinceIso ? `since ${sinceIso}` : "all-time";
+    const parts = [];
+    if (rows.length === 0) {
+        parts.push(`digest by ${groupBy} (${window}): no frictions match`);
+    }
+    else {
+        parts.push(`digest by ${groupBy} (${window})`, "", renderDigestTable(rows));
+    }
+    if (peers) {
+        for (const peer of peers) {
+            const skippedNote = peer.skipped > 0
+                ? `, ${peer.skipped} record(s) skipped as malformed`
+                : "";
+            parts.push("", `peer origin=${peer.origin} (${peer.sourcePath})${skippedNote}:`);
+            if (peer.error) {
+                parts.push(`  WARNING: ${peer.error}`);
+            }
+            else if (peer.rows.length === 0) {
+                parts.push("  no frictions match");
+            }
+            else {
+                parts.push(indent(renderDigestTable(peer.rows), "  "));
+            }
+        }
+    }
+    return parts.join("\n");
+}
+function renderDigestTable(rows) {
+    const header = [
+        "group",
+        "total",
+        "open",
+        "filed",
+        "resolved",
+        "wontfix",
+        "open%",
+        "recurrences",
+        "avg-h-triage",
+    ];
+    const body = rows.map((r) => [
+        r.group,
+        String(r.total),
+        String(r.open),
+        String(r.filed),
+        String(r.resolved),
+        String(r.wontfix),
+        r.total > 0 ? `${Math.round((r.open / r.total) * 100)}%` : "-",
+        String(r.recurrences),
+        r.avgHoursToTriage == null ? "-" : r.avgHoursToTriage.toFixed(1),
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length)));
+    const sep = widths.map((w) => "-".repeat(w)).join("  ");
+    const fmt = (row) => row.map((c, i) => c.padEnd(widths[i])).join("  ");
+    return [fmt(header), sep, ...body.map(fmt)].join("\n");
+}
+function indent(text, prefix) {
+    return text
+        .split("\n")
+        .map((line) => prefix + line)
+        .join("\n");
+}
+//# sourceMappingURL=digest.js.map