@gmickel/gno 1.33.0 → 1.34.0

package/README.md

@@ -117,7 +117,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.33.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.34.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -174,6 +174,10 @@ gno daemon --detach  # headless indexing + resident MCP gateway
   `local_only`, `lan`, or `remote` boundary that follows mixed and derived
   evidence through resident serving, inference, publishing, exports, Capsules,
   and traces. Authentication never overrides policy.
+- **Read-only integrity audits**: `gno audit` and MCP `gno_audit` inspect local
+  links, declared provenance, and source/index freshness offline. Stable,
+  bounded findings distinguish complete, partial, unavailable, and changing
+  evidence without repairing or persisting anything.
 - **Schema-lite content types**: optional `contentTypes` rules map configured
   frontmatter `type` values or path prefixes to canonical `contentType` metadata
   in JSON search/query results and can apply one bounded, explainable
@@ -945,7 +949,8 @@ graph TD
 | **Local LLM**        | AI answers via llama.cpp, no API keys                                                       |
 | **Remote Inference** | Optional HTTP endpoints for embedding, reranking, expansion, and generation                 |
 | **Privacy First**    | Fail-closed per-collection egress policy; no telemetry; explicit network use                |
-| **MCP Server**       | 10 automatic client targets; 25 read-only tools, 40 with writes enabled                     |
+| **MCP Server**       | 10 automatic client targets; 32 read-only tools, 50 with writes enabled                     |
+| **Integrity Audits** | Offline link, declared-provenance, and freshness reports with stable IDs                    |
 | **Knowledge Delta**  | Bounded metadata history, structural diffs, and dependency impact paths                     |
 | **Context Capsules** | Deterministic evidence bundles plus saved-file freshness reverification                     |
 | **Verified Ask**     | Claim-by-claim evidence checks with explicit abstention                                     |

package/assets/skill/SKILL.md

@@ -313,6 +313,23 @@ at the remote service. For gno.sh, supported private links can be revoked or
 expired in Studio; public-space deletion is not yet self-service, so request
 takedown. Encrypted gno.sh shares are client-encrypted and never server-decrypted.
 
+## Read-Only Knowledge Integrity Audits
+
+Use `gno audit [links|provenance|freshness|all] --json` or read-only MCP
+`gno_audit` only when the user asks what needs attention in a workspace. These
+offline audits inspect parsed local links, explicitly declared capture/logical-
+record provenance, and observable source/index freshness. They never repair,
+rewrite, persist findings, judge factual truth, or replace retrieval.
+
+Treat exit `4` as a complete report with findings. Exit `5` or report status
+`partial`/`changed_during_audit` means evidence is unavailable, inconclusive,
+cancelled, truncated, or repeatedly changed—never healthy. Preserve stable
+finding IDs and exact totals when summarizing bounded results. Age is only a
+review signal when `maxAgeDays`/`--max-age-days` is explicitly supplied. Apply
+collection/path/tag scope and orphan roots/ignore prefixes only from the user's
+request. `gno egress-audit` is separate: it manages content-free transport-
+policy receipts.
+
 ## MCP Retrieval Strategy
 
 For a long-lived client that supports Streamable HTTP, start one resident owner
@@ -377,6 +394,8 @@ Use narrower tools when the request tells you to:
 - `gno_search`: exact phrase, filename, identifier, stack trace, error text
 - `gno_vsearch`: conceptual similarity when exact wording differs
 - `gno_status`: stale results, missing embeddings, vector unavailable
+- `gno_audit`: explicit offline workspace-integrity review; report findings and
+  partial evidence, never mutate or imply repairs
 - `gno_graph`: graph report/stats, hubs, isolates, unresolved links, edge confidence/audit, communities, unfamiliar corpus overview
 - `gno_graph_query`: bounded typed-edge traversal from a known document
 - `gno_graph_neighbors`: relationship/corpus-navigation questions around a known document

package/browser-extension/artifacts/gno-browser-clipper-v1.34.0.zip.sha256

@@ -0,0 +1 @@
+0acc125d848721bdced540fe49412ef8c83df5d4ff3ba086076c46ed9d441998  gno-browser-clipper-v1.34.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.33.0"
+  "version": "1.34.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -692,6 +692,50 @@ projection.
 content-free decision, lineage, partial disclosure, audit metadata, and
 remediation contract.
 
+### gno audit
+
+Read-only, offline knowledge-integrity audits. This command is distinct from
+`gno egress-audit`: it examines workspace links, declared provenance
+requirements, and source/index freshness without persisting findings or
+modifying notes, configuration, index rows, graph edges, or daemon state.
+
+```bash
+gno audit [links|provenance|freshness|all] [--collection <name>...] \
+  [--path <prefix>...] [--tag <tag>...] [--max-findings <n>] \
+  [--max-age-days <days>] [--orphan-root <uri>...] \
+  [--orphan-ignore-prefix <prefix>...] [--no-progress] \
+  [--json] [--output <path>]
+```
+
+The default category is `all`; `--max-findings` defaults to 100 and is bounded
+to 1–1000. Truncation limits returned findings but preserves exact totals.
+`--output` writes only the requested report artifact with local file
+permissions. Human output renders the same report represented by
+`audit-report.schema.json`.
+When attached to a terminal, human mode reports snapshot/rule progress on
+stderr; `--no-progress`, `--quiet`, and JSON mode suppress it. `Ctrl-C` returns
+the bounded report gathered so far with partial status and exit 5. Freshness
+age is reported only when `--max-age-days` supplies an explicit policy.
+
+Rule statuses are `pass`, `fail`, `skip`, `unavailable`, and `inconclusive`.
+Report statuses are `complete`, `partial`, `changed_during_audit`, and `failed`.
+A skipped, unavailable, inconclusive, or changing check is never rendered as
+healthy.
+
+**Exit Codes:**
+
+- `0` — complete and clean
+- `1` — invalid input
+- `2` — runtime failure
+- `4` — complete report with findings
+- `5` — partial, inconclusive, unavailable, or changed-during-audit evidence
+
+The JSON contract is versioned as `gno://schemas/audit-report@1.0`. Finding IDs
+are stable SHA-256 identities derived from rule, normalized subject/location,
+and load-bearing evidence. Wall-clock timing and traversal order do not affect
+identity. A source/index fingerprint change causes one bounded retry and then
+`changed_during_audit`; it can never produce a clean exit.
+
 ### gno egress-audit
 
 Manage local content-free policy decision receipts:

package/spec/mcp.md

@@ -152,6 +152,27 @@ Collection names are case-insensitive on input and normalized to lowercase in re
 
 ## Tools
 
+### Knowledge integrity audit contract
+
+`gno_audit` is a read-only, offline tool that returns the same
+`gno://schemas/audit-report@1.0` report as `gno audit`. Its closed input accepts
+`category` (`links`, `provenance`, `freshness`, or `all`), collection/path/tag
+filters, and `maxFindings` (1–1000). `maxAgeDays`, `orphanRoots`, and
+`orphanIgnorePrefixes` are optional explicit policy inputs. Request
+cancellation returns a partial report rather than a false clean result. The
+tool is annotated with
+`readOnlyHint: true`; the implementation must additionally prove that it never
+modifies source files, config, index rows, graph edges, daemon state, or a
+persisted audit baseline.
+
+Rules report `pass`, `fail`, `skip`, `unavailable`, or `inconclusive`; reports
+are `complete`, `partial`, `changed_during_audit`, or `failed`. Unavailable or
+changing evidence never appears healthy. Stable finding IDs are derived from
+rule, normalized subject/location, and evidence fingerprint. Responses are
+canonically ordered and bounded while retaining exact pre-truncation totals.
+This knowledge audit is distinct from the content-free `gno_egress_audit_*`
+receipt-management tools.
+
 ### Agent Retrieval Playbook
 
 - Prefer `gno_context` when the agent needs a complete, bounded evidence handoff

package/spec/output-schemas/audit-report.schema.json

@@ -0,0 +1,284 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/audit-report@1.0",
+  "title": "GNO Knowledge Integrity Audit Report",
+  "description": "Deterministic read-only audit report for links, provenance, and freshness. Not egress-audit receipts.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "ruleSetVersion",
+    "status",
+    "scope",
+    "capabilities",
+    "fingerprints",
+    "versions",
+    "startedAt",
+    "completedAt",
+    "durationMs",
+    "rules",
+    "findings",
+    "counts",
+    "truncation",
+    "timing"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "ruleSetVersion": { "const": "1.0" },
+    "status": {
+      "enum": ["complete", "partial", "changed_during_audit", "failed"]
+    },
+    "scope": { "$ref": "#/definitions/scope" },
+    "capabilities": { "$ref": "#/definitions/capabilities" },
+    "fingerprints": { "$ref": "#/definitions/fingerprints" },
+    "versions": { "$ref": "#/definitions/versions" },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "completedAt": { "type": "string", "format": "date-time" },
+    "durationMs": { "type": "integer", "minimum": 0 },
+    "rules": {
+      "type": "array",
+      "maxItems": 256,
+      "items": { "$ref": "#/definitions/ruleResult" }
+    },
+    "findings": {
+      "type": "array",
+      "maxItems": 1000,
+      "items": { "$ref": "#/definitions/finding" }
+    },
+    "counts": { "$ref": "#/definitions/counts" },
+    "truncation": { "$ref": "#/definitions/truncation" },
+    "timing": { "$ref": "#/definitions/timing" }
+  },
+  "definitions": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "category": {
+      "enum": ["links", "provenance", "freshness"]
+    },
+    "ruleStatus": {
+      "enum": ["pass", "fail", "skip", "unavailable", "inconclusive"]
+    },
+    "severity": {
+      "enum": ["error", "warning", "info"]
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["categories", "collections", "paths", "tags", "indexName"],
+      "properties": {
+        "categories": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 3,
+          "items": { "$ref": "#/definitions/category" },
+          "uniqueItems": true
+        },
+        "collections": {
+          "type": "array",
+          "maxItems": 256,
+          "items": { "type": "string", "minLength": 1, "maxLength": 256 }
+        },
+        "paths": {
+          "type": "array",
+          "maxItems": 256,
+          "items": { "type": "string", "minLength": 1, "maxLength": 2048 }
+        },
+        "tags": {
+          "type": "array",
+          "maxItems": 256,
+          "items": { "type": "string", "minLength": 1, "maxLength": 256 }
+        },
+        "indexName": { "type": "string", "minLength": 1, "maxLength": 64 }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "indexReadable",
+        "sourcesReadable",
+        "linksGraphAvailable",
+        "provenanceSchemaAvailable",
+        "offline",
+        "llmDisabled"
+      ],
+      "properties": {
+        "indexReadable": { "type": "boolean" },
+        "sourcesReadable": { "type": "boolean" },
+        "linksGraphAvailable": { "type": "boolean" },
+        "provenanceSchemaAvailable": { "type": "boolean" },
+        "offline": { "const": true },
+        "llmDisabled": { "const": true }
+      }
+    },
+    "fingerprints": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["config", "source", "index", "rules"],
+      "properties": {
+        "config": { "type": "string", "minLength": 0, "maxLength": 128 },
+        "source": { "type": "string", "minLength": 0, "maxLength": 128 },
+        "index": { "type": "string", "minLength": 0, "maxLength": 128 },
+        "rules": { "type": "string", "minLength": 0, "maxLength": 128 }
+      }
+    },
+    "versions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gno", "schema", "ruleSet"],
+      "properties": {
+        "gno": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "schema": { "const": "1.0" },
+        "ruleSet": { "const": "1.0" }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "summary"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "uri": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "path": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "detail": { "type": "string", "minLength": 1, "maxLength": 512 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "ruleId",
+        "category",
+        "severity",
+        "subject",
+        "location",
+        "message",
+        "evidence",
+        "guidance",
+        "evidenceFingerprint"
+      ],
+      "properties": {
+        "id": { "$ref": "#/definitions/sha256" },
+        "ruleId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "category": { "$ref": "#/definitions/category" },
+        "severity": { "$ref": "#/definitions/severity" },
+        "subject": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "location": { "type": ["string", "null"], "maxLength": 2048 },
+        "message": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "evidence": {
+          "type": "array",
+          "maxItems": 8,
+          "items": { "$ref": "#/definitions/evidence" }
+        },
+        "guidance": {
+          "type": "array",
+          "maxItems": 4,
+          "items": { "type": "string", "minLength": 1, "maxLength": 256 }
+        },
+        "evidenceFingerprint": { "$ref": "#/definitions/sha256" }
+      }
+    },
+    "ruleResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ruleId",
+        "category",
+        "status",
+        "message",
+        "findings",
+        "findingCount",
+        "examinedCount",
+        "durationMs",
+        "skipReason"
+      ],
+      "properties": {
+        "ruleId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "category": { "$ref": "#/definitions/category" },
+        "status": { "$ref": "#/definitions/ruleStatus" },
+        "message": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "findings": {
+          "type": "array",
+          "maxItems": 1000,
+          "items": { "$ref": "#/definitions/finding" }
+        },
+        "findingCount": { "type": "integer", "minimum": 0 },
+        "examinedCount": { "type": "integer", "minimum": 0 },
+        "durationMs": { "type": "integer", "minimum": 0 },
+        "skipReason": { "type": ["string", "null"], "maxLength": 512 }
+      }
+    },
+    "counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rules", "findings", "examined"],
+      "properties": {
+        "rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "pass",
+            "fail",
+            "skip",
+            "unavailable",
+            "inconclusive",
+            "total"
+          ],
+          "properties": {
+            "pass": { "type": "integer", "minimum": 0 },
+            "fail": { "type": "integer", "minimum": 0 },
+            "skip": { "type": "integer", "minimum": 0 },
+            "unavailable": { "type": "integer", "minimum": 0 },
+            "inconclusive": { "type": "integer", "minimum": 0 },
+            "total": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "findings": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["total", "returned", "truncated"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0 },
+            "returned": { "type": "integer", "minimum": 0, "maximum": 1000 },
+            "truncated": { "type": "boolean" }
+          }
+        },
+        "examined": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["documents"],
+          "properties": {
+            "documents": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "truncation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["findingsTruncated", "maxFindings"],
+      "properties": {
+        "findingsTruncated": { "type": "boolean" },
+        "maxFindings": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        }
+      }
+    },
+    "timing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["snapshotMs", "rulesMs", "totalMs"],
+      "properties": {
+        "snapshotMs": { "type": "integer", "minimum": 0 },
+        "rulesMs": { "type": "integer", "minimum": 0 },
+        "totalMs": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/src/cli/commands/audit.ts

@@ -0,0 +1,231 @@
+/** Read-only knowledge-integrity audit CLI adapter. */
+
+// node:fs/promises provides atomic filesystem structure operations with no Bun equivalent.
+import { chmod, mkdtemp, rename, rmdir, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import type {
+  AuditCategory,
+  AuditReport,
+  AuditRunResult,
+} from "../../core/audit";
+import type { WorkspaceAuditProgress } from "../../core/audit-workspace";
+
+import { getIndexDbPath } from "../../app/constants";
+import { loadConfig } from "../../config";
+import {
+  auditExitCode,
+  AUDIT_CATEGORIES,
+  serializeAuditReportCanonical,
+} from "../../core/audit";
+import { runWorkspaceAudit } from "../../core/audit-workspace";
+import { normalizeTag, validateTag } from "../../core/tags";
+import { normalizeCollectionName } from "../../core/validation";
+import { SqliteAdapter } from "../../store/sqlite/adapter";
+
+export interface AuditCommandOptions {
+  category?: string;
+  configPath?: string;
+  indexName?: string;
+  collections?: string[];
+  paths?: string[];
+  tags?: string[];
+  maxFindings?: number;
+  maxAgeDays?: number;
+  orphanRoots?: string[];
+  orphanIgnorePrefixes?: string[];
+  signal?: AbortSignal;
+  onProgress?: (progress: WorkspaceAuditProgress) => void | Promise<void>;
+}
+
+export type AuditCommandResult =
+  | { success: true; report: AuditReport; exitCode: number }
+  | { success: false; error: string; invalid: boolean };
+
+const resolveCategories = (
+  value: string | undefined
+): AuditCategory[] | null => {
+  const normalized = (value ?? "all").trim().toLowerCase();
+  if (normalized === "all") return [...AUDIT_CATEGORIES];
+  return (AUDIT_CATEGORIES as readonly string[]).includes(normalized)
+    ? [normalized as AuditCategory]
+    : null;
+};
+
+const invalidPositiveInteger = (value: number | undefined): boolean =>
+  value !== undefined && (!Number.isSafeInteger(value) || value < 1);
+
+const AUDIT_SCOPE_FILTER_MAX_ITEMS = 256;
+
+const oversizedScopeFilter = (
+  options: AuditCommandOptions
+): "collections" | "paths" | "tags" | null => {
+  for (const name of ["collections", "paths", "tags"] as const) {
+    if ((options[name]?.length ?? 0) > AUDIT_SCOPE_FILTER_MAX_ITEMS) {
+      return name;
+    }
+  }
+  return null;
+};
+
+export const audit = async (
+  options: AuditCommandOptions
+): Promise<AuditCommandResult> => {
+  const categories = resolveCategories(options.category);
+  if (!categories) {
+    return {
+      success: false,
+      invalid: true,
+      error: "category must be links, provenance, freshness, or all",
+    };
+  }
+  if (invalidPositiveInteger(options.maxFindings)) {
+    return {
+      success: false,
+      invalid: true,
+      error: "maxFindings must be a positive integer",
+    };
+  }
+  if (invalidPositiveInteger(options.maxAgeDays)) {
+    return {
+      success: false,
+      invalid: true,
+      error: "maxAgeDays must be a positive integer",
+    };
+  }
+  const oversizedFilter = oversizedScopeFilter(options);
+  if (oversizedFilter) {
+    return {
+      success: false,
+      invalid: true,
+      error: `${oversizedFilter} must contain at most ${AUDIT_SCOPE_FILTER_MAX_ITEMS} values`,
+    };
+  }
+  const configResult = await loadConfig(options.configPath);
+  if (!configResult.ok) {
+    return { success: false, invalid: true, error: configResult.error.message };
+  }
+  const config = configResult.value;
+  const requestedCollections = (options.collections ?? []).map(
+    normalizeCollectionName
+  );
+  const requestedTags = (options.tags ?? []).map(normalizeTag);
+  const invalidTag = requestedTags.find((tag) => !validateTag(tag));
+  if (invalidTag) {
+    return {
+      success: false,
+      invalid: true,
+      error: `Invalid tag: "${invalidTag}"`,
+    };
+  }
+  const knownCollections = new Set(
+    config.collections.map((collection) => collection.name)
+  );
+  const missingCollection = requestedCollections.find(
+    (collection) => !knownCollections.has(collection)
+  );
+  if (missingCollection) {
+    return {
+      success: false,
+      invalid: true,
+      error: `Collection not found: ${missingCollection}`,
+    };
+  }
+  const dbPath = getIndexDbPath(options.indexName);
+  if (!(await Bun.file(dbPath).exists())) {
+    return {
+      success: false,
+      invalid: false,
+      error: `Index database not found: ${dbPath}. Run gno index first.`,
+    };
+  }
+  const store = new SqliteAdapter();
+  const opened = store.openReadOnly(dbPath);
+  if (!opened.ok) {
+    return { success: false, invalid: false, error: opened.error.message };
+  }
+  try {
+    const result: AuditRunResult = await runWorkspaceAudit({
+      store,
+      config,
+      collections: config.collections,
+      indexName: options.indexName ?? "default",
+      categories,
+      collectionFilters: requestedCollections,
+      pathFilters: options.paths,
+      tagFilters: requestedTags,
+      maxFindings: options.maxFindings,
+      agePolicy:
+        options.maxAgeDays === undefined
+          ? undefined
+          : { maxAgeDays: options.maxAgeDays },
+      orphanRoots: options.orphanRoots,
+      orphanIgnorePrefixes: options.orphanIgnorePrefixes,
+      signal: options.signal,
+      onProgress: options.onProgress,
+    });
+    if (!result.ok) {
+      return { success: false, invalid: true, error: result.error };
+    }
+    return {
+      success: true,
+      report: result.report,
+      exitCode: auditExitCode(result.exit),
+    };
+  } finally {
+    await store.close();
+  }
+};
+
+export const formatAuditReport = (
+  report: AuditReport,
+  options: { json?: boolean } = {}
+): string => {
+  if (options.json) return serializeAuditReportCanonical(report);
+  const lines = [
+    `Audit: ${report.status}`,
+    `Categories: ${report.scope.categories.join(", ")}`,
+    `Rules: ${report.counts.rules.total} (${report.counts.rules.fail} failed, ${report.counts.rules.unavailable} unavailable, ${report.counts.rules.inconclusive} inconclusive)`,
+    `Findings: ${report.counts.findings.total}${report.counts.findings.truncated ? ` (${report.counts.findings.returned} shown)` : ""}`,
+    `Examined: ${report.counts.examined.documents} document/rule observations`,
+    `Duration: ${report.durationMs}ms`,
+  ];
+  for (const finding of report.findings) {
+    const location = finding.location ? ` ${finding.location}` : "";
+    lines.push(
+      `- [${finding.severity}] ${finding.ruleId}: ${finding.subject}${location} — ${finding.message}`
+    );
+  }
+  for (const rule of report.rules) {
+    if (
+      rule.status === "skip" ||
+      rule.status === "unavailable" ||
+      rule.status === "inconclusive"
+    ) {
+      lines.push(`- [${rule.status}] ${rule.ruleId}: ${rule.message}`);
+    }
+  }
+  return lines.join("\n");
+};
+
+export const writeAuditReport = async (
+  path: string,
+  report: AuditReport,
+  options: { json?: boolean } = {}
+): Promise<void> => {
+  const temporaryDirectory = await mkdtemp(
+    join(dirname(path), `.${basename(path)}-`)
+  );
+  const temporaryPath = join(temporaryDirectory, "report");
+  try {
+    await Bun.write(temporaryPath, `${formatAuditReport(report, options)}\n`, {
+      createPath: false,
+      mode: 0o600,
+    });
+    await chmod(temporaryPath, 0o600);
+    await rename(temporaryPath, path);
+  } finally {
+    await unlink(temporaryPath).catch(() => undefined);
+    await rmdir(temporaryDirectory).catch(() => undefined);
+  }
+};