faf-cli 7.12.1 → 7.13.1

package/dist/core/cwd-guard.d.ts

@@ -0,0 +1,8 @@
+/** True if dir is the user's home directory or the filesystem root — compared
+ *  by identity (device + inode), not by spelling. */
+export declare function isNonProjectRoot(dir?: string): boolean;
+/**
+ * Exit 1 with a clear cd instruction if cwd cannot be a project root.
+ * Call at the top of commands that create or interview project.faf.
+ */
+export declare function assertProjectCwd(dir?: string, command?: string): void;

package/dist/core/faf-dna.d.ts

@@ -0,0 +1,147 @@
+/**
+ * FAF DNA — the lifecycle of AI context. The "first heartbeat".
+ *
+ * Every project.faf gets a `.faf-dna` lineage record (separate file, NOT
+ * embedded in the .faf — so it's compatible with the clean dialect):
+ *   - Birth Certificate: the honest first score (even 0%) — the "before" picture
+ *   - Growth Record: version history as the score improves
+ *   - Journey: the one-line story, e.g. "22% → 85% → 99% ← 92%"
+ *
+ * Birth DNA = the raw slot-based score at init. The growth from Birth DNA to
+ * the current score is the demonstrated value of FAF.
+ *
+ * Restored 2026-05-21 — silently dropped in the v6.0 clean-architecture rewrite
+ * (it was never knowingly removed). Ported from v5 (sync, v6-native, load-compatible).
+ *
+ * Other shapes. `.faf-dna` is committed lineage, and other tools have written
+ * it in their own shape (claude-faf-mcp's faf_dna wrote `milestones` at the top
+ * level and no `versions` or `growth`). Reading never throws on such a file: it
+ * reads what it can, and missing parts are derived from what is there. Writing
+ * is different: recordGrowth rewrites the file only when faf can prove it wrote
+ * every byte — the file is in faf's shape AND its text is exactly faf's own
+ * serialisation of what it holds (`JSON.stringify(data, null, 2)` and a final
+ * newline), and nothing faf would replace carries a note of the user's. Hand
+ * formatting, CRLF, reordered keys, a repeated key or a number JSON cannot hold
+ * exactly (a 20-digit id) would all be lost in a rewrite, so such a file — like
+ * one in another shape — is read and left exactly as it is, and
+ * `readOnlyReason()` says why in one line. `faf init --force` starts a fresh
+ * lineage when you ask it to.
+ */
+export interface BirthCertificate {
+    born: string;
+    birthDNA: number;
+    birthDNASource: 'init' | 'legacy';
+    projectDNA: string;
+    certificate: string;
+}
+export interface VersionEntry {
+    version: string;
+    timestamp: string;
+    score: number;
+    changes: string[];
+    growth: number;
+}
+/** Journey markers only — not score tiers.
+ *  Tiers live solely in tiers.ts (Trophy 100 · Gold 99 · Silver 95 · Bronze 85 · …).
+ *  There is no championship / elite / perfect milestone. */
+export interface Milestone {
+    type: 'birth' | 'doubled' | 'peak' | 'current';
+    score: number;
+    date: string;
+    version: string;
+    label: string;
+    emoji: string;
+}
+export interface FafDNA {
+    birthCertificate: BirthCertificate;
+    versions: VersionEntry[];
+    current: {
+        version: string;
+        score: number;
+        lastSync: string;
+    };
+    growth: {
+        totalGrowth: number;
+        daysActive: number;
+        milestones: Milestone[];
+    };
+    lastModified: string;
+    format: 'faf-dna-v1';
+}
+/**
+ * The `.faf-dna` lineage of one project: birth, growth and the journey line.
+ * This is the API `faf init` (birth), `faf auto` / `faf refresh` (recordGrowth)
+ * and `faf dna` (getJourney, getBirthDNADisplay, getLog) use.
+ *
+ *   - `birth(score)` starts a new lineage and writes it, replacing any
+ *     `.faf-dna` there (check `exists()` first unless a fresh start is meant —
+ *     `faf init` births only when there is none, or with `--force`).
+ *   - `recordGrowth(score, changes)` adds a version when the score changed.
+ *     It adds only to a file faf can prove it wrote (see the file header);
+ *     for any other file it writes nothing and returns null, and
+ *     `readOnlyReason()` says why.
+ *   - Reads never throw: a missing, unreadable, non-UTF-8 or non-JSON file,
+ *     or one with no usable birth certificate, reads as null / '' / [].
+ *
+ * Every write is atomic and stays inside the project: a `.faf-dna` link that
+ * leads out of the project, dangles or leads to a file with another name is
+ * refused (and reads as absent). A write is refused, too, when the file
+ * changed on disk after this manager read it (another `faf` process recorded
+ * growth meanwhile, say): SafePathError `changed`, nothing written.
+ */
+export declare class FafDNAManager {
+    private readonly projectPath;
+    private readonly dnaPath;
+    private dna;
+    /** True when the loaded file is one faf wrote (so it may be added to). */
+    private own;
+    /** The text read from `.faf-dna` (or last written), for the write's check. */
+    private text;
+    /** Why the file is read only, when it is; null when faf may add to it. */
+    private reason;
+    /** True once this manager found no `.faf-dna` (exists / load / birth) and
+     *  has not written one since: a birth then refuses a file that appeared
+     *  meanwhile instead of writing over it. */
+    private sawNoFile;
+    constructor(projectPath: string);
+    exists(): boolean;
+    /** Birth — the first heartbeat. Writes the birth certificate with the honest first score.
+     *  When this manager found no `.faf-dna` (now, or at an earlier exists() /
+     *  load()), a file that appeared since is refused (SafePathError `changed`)
+     *  rather than written over; over a `.faf-dna` that is there, birth starts a
+     *  fresh lineage (`faf init --force`). */
+    birth(birthDNA: number): FafDNA;
+    /** True when `.faf-dna` exists and is one faf wrote — in faf's shape, and
+     *  exactly faf's own text — so recordGrowth may add to it. Any other file is
+     *  read, not written. */
+    isFafShape(): boolean;
+    /** Why faf leaves this `.faf-dna` as it is, in one plain line — or null when
+     *  there is none, or recordGrowth may add to it. */
+    readOnlyReason(): string | null;
+    /** Record growth — a new score on the journey. Returns null when there is no
+     *  DNA yet, or when the file is in another tool's shape (nothing is written). */
+    recordGrowth(newScore: number, changes: string[]): FafDNA | null;
+    /** The one-line journey: e.g. "22% → 85% → 99% ← 92%". */
+    getJourney(): string;
+    getBirthDNADisplay(): {
+        current: number;
+        birthDNA: number;
+        growth: number;
+        born: string;
+    } | null;
+    /** Complete version history, newest last. */
+    getLog(): string[];
+    /** Load `.faf-dna`. Never throws: missing, unreadable, not UTF-8, not JSON, a
+     *  refused link, or no usable birth certificate → null. A file faf did not
+     *  write (another shape, or not exactly faf's text) loads as a readable view
+     *  (see the file header). */
+    load(): FafDNA | null;
+    /** The file's text (strict UTF-8) and its JSON, or null with the reason noted. */
+    private read;
+    private save;
+    private generateProjectDNA;
+    private generateCertificate;
+    private incrementVersion;
+    private daysSince;
+    private updateMilestones;
+}

package/dist/core/faf-source.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Where .faf data came from: the file readFaf read it from (its real path) and
+ * the text it read. writeFaf checks a write of that data against it — when the
+ * file changed on disk after the read, the write is refused instead of being
+ * made over the newer edit. Kept apart from interop/faf.ts so the pure parts
+ * of detection (updateExistingFaf) can carry it without importing a module
+ * that runs git.
+ */
+/** The file a data object was read from, and the text read. */
+export interface FafSource {
+    real: string;
+    text: string;
+}
+/** The source recorded for `data`, if any. */
+export declare function fafSourceOf(data: unknown): FafSource | undefined;
+/** Record that `data` holds what `source.text` (read from `source.real`) says. */
+export declare function setFafSource(data: object, source: FafSource): void;
+/** Let `to` — data made from `from` (a copy with empty slots filled, say) —
+ *  carry the file `from` was read from. Returns `to`. */
+export declare function carryFafSource<T extends object>(from: unknown, to: T): T;
+/** Mark `data` as a fill of the file it was read from — what `faf auto`
+ *  (updateExistingFaf) makes: detected values in the file's empty slots.
+ *  writeFaf leaves a node with an anchor that an alias reads as written in
+ *  such data, since filling it would change every alias. Returns `data`. */
+export declare function markAsFill<T extends object>(data: T): T;
+/** True when `data` was marked with {@link markAsFill}. */
+export declare function isFill(data: unknown): boolean;

package/dist/core/json-edit.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Text-preserving JSON edits: change the value of a key, or add a key that is
+ * missing, and keep every other byte of the file — key order, spacing, a
+ * 20-digit integer, an array written on one line. faf uses it for the one
+ * JSON file it shares with its owner, a registry `server.json`, where faf owns
+ * only the identity keys (`faf server-card`, `faf cards --target registry`).
+ *
+ * A patch is a plain object. For each key: a plain-object value is a folder to
+ * go into (the file's value must be an object too); any other value replaces
+ * the value's text when it differs, or is added when the key is missing.
+ * Nothing is ever deleted, and `undefined` is skipped. When the file cannot be
+ * edited that way — not valid JSON, not an object, a key it repeats on the way,
+ * a value faf would have to replace to go into it, or an object or array in the
+ * file where faf sets a plain value — a JsonEditError says why in one line and
+ * nothing is changed.
+ *
+ * Two more edits keep the same promise: {@link upsertJsonRows} updates or
+ * appends faf's own rows in an array (the `faf cards` catalog), and
+ * {@link removeJsonKey} takes out one key faf added (its render hash).
+ */
+/** Why a JSON text cannot be edited in place (one line). */
+export declare class JsonEditError extends Error {
+    constructor(message: string);
+}
+/** Where to add a missing key: after the first of these keys the object has
+ *  (else after its last key). Keyed by the dotted path of the object ('' is the root). */
+export type InsertAfter = Record<string, Record<string, readonly string[]>>;
+/**
+ * Apply `patch` to the JSON `text`, changing only the value text of the keys
+ * it names and adding the keys it has that the text lacks (see the file
+ * header). Returns the new text and whether it changed. Throws a
+ * JsonEditError, having changed nothing, when the text cannot be edited that
+ * way. `after` says where a missing key goes (default: after the object's last key).
+ */
+export declare function editJsonText(text: string, patch: Record<string, unknown>, after?: InsertAfter): {
+    text: string;
+    changed: boolean;
+};
+/**
+ * Update or add rows in the array at the root key `key`, changing nothing
+ * else: a row whose `id` value is exactly a row's in the file is updated in
+ * place — only the values of its `update` keys change (or are added) — and any
+ * other row is appended after the file's last item, laid out like the items
+ * around it (the array, or the key, is added when missing). Every item faf
+ * does not update stays byte for byte. Never matched by anything but `id`.
+ * Throws a JsonEditError, having changed nothing, when the text cannot be
+ * edited that way: not a JSON object, `key` not an array or there more than
+ * once, a row's id there more than once, or a value faf sets that is an object
+ * or array in the file.
+ */
+export declare function upsertJsonRows(text: string, key: string, rows: readonly Record<string, unknown>[], opts: {
+    id: string;
+    update: readonly string[];
+}): {
+    text: string;
+    changed: boolean;
+};
+/**
+ * The value at `path` in the JSON object `text` (each step a key of an
+ * object): `count` 1 with its parsed `value`, 0 when a step is missing or not
+ * an object, more than 1 when a key on the way is repeated. Throws a
+ * JsonEditError when `text` is not a JSON object.
+ */
+export declare function locateJsonKey(text: string, path: readonly string[]): {
+    count: number;
+    value?: unknown;
+};
+/**
+ * `text` with the key at `path` taken out — the reverse of {@link editJsonText}
+ * adding it (see {@link removal}); every other byte stays. With
+ * `dropEmptyParent`, when that key is its object's only key, the object's own
+ * key is taken out instead. Returns null when the key is not there exactly
+ * once; throws a JsonEditError when `text` is not a JSON object.
+ */
+export declare function removeJsonKey(text: string, path: readonly string[], opts?: {
+    dropEmptyParent?: boolean;
+}): string | null;

package/dist/core/render-hash.d.ts

@@ -0,0 +1,55 @@
+/** The `_meta` key a JSON file faf renders carries its render hash under. */
+export declare const RENDER_KEY = "one.faf/render";
+/** `sha256:<hex>` of `text` (UTF-8). */
+export declare function renderHash(text: string): string;
+/** How faf records its hash in a file: an HTML meta line, or a JSON `_meta` key. */
+export type RenderFormat = 'html' | 'json';
+/**
+ * Whether the bytes of a whole file faf renders are exactly what faf wrote:
+ * `match` — they carry faf's render hash, the hash is that of the rest of the
+ * file, and the file is laid out exactly as faf writes it; `mismatch` — they
+ * carry a render hash that no longer fits, or (project.html) a render line
+ * that is not exactly faf's form (the file was edited since faf wrote it);
+ * `none` — they carry no render hash (a file from before 7.13, or one faf
+ * never wrote). The bytes are taken as they are: see {@link writeRendered}
+ * for a file git checked out with CRLF line ends.
+ */
+export declare function renderOwnership(bytes: Uint8Array, format: RenderFormat): 'match' | 'mismatch' | 'none';
+/** Options for {@link writeRendered}. */
+export interface RenderedWriteOptions {
+    /** The project folder the write must stay inside. */
+    root: string;
+    /** How the hash is recorded: `html` (project.html) or `json` (the cards, server.json, a snapshot). */
+    format: RenderFormat;
+    /** True when the bytes carry faf's older mark — a file faf wrote before render hashes. */
+    hasMark: (bytes: Buffer) => boolean;
+    /** That mark in words, for the refusal of a file without it. */
+    mark: string;
+    /** Replace the file whatever it holds — the explicit overwrite (`--force`). */
+    force?: boolean;
+}
+/** What {@link writeRendered} did. */
+export type RenderedResult = 'created' | 'updated' | 'unchanged';
+/**
+ * Write the whole file faf renders at `path`: `render` (faf's text, without a
+ * render hash) with faf's render hash added. The link rules and the atomic,
+ * compare-before-rename write are safe-write's. A file already there is
+ * replaced only when {@link renderOwnership} says `match`; with a `mismatch`,
+ * or with no hash, it is refused (SafePathError `not-owned`) and left byte for
+ * byte:
+ *   - "<file> was edited since faf wrote it — faf left it unchanged. Use --force to replace it."
+ *   - with faf's older mark (written before 7.13): exactly faf's `render` →
+ *     nothing to change (`unchanged`); otherwise "<file> has no faf render hash
+ *     (written before 7.13), so faf cannot tell whether it was edited — faf
+ *     left it unchanged. Use --force once to replace it; after that faf
+ *     recognises its own output."
+ *   - without the mark: "<file> has no <mark>, so faf did not write it — faf left it unchanged."
+ * `force` replaces it anyway. A file already holding exactly the new bytes is
+ * not written again. A file whose every line ends CRLF (git's
+ * `core.autocrlf`) is judged with those line ends read as LF, and is written
+ * back with CRLF line ends.
+ */
+export declare function writeRendered(path: string, render: string, opts: RenderedWriteOptions): {
+    path: string;
+    result: RenderedResult;
+};

package/dist/core/safe-write.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Safe file access — the one primitive every faf writer, and every read of
+ * project context, goes through. It is also the only module in faf that calls
+ * a filesystem write, rename, delete, mkdir or chmod API (tests/write-guard
+ * enforces that for all of src/).
+ *
+ * Rule 1 — stay inside the project. Before faf touches a path it resolves it on
+ * disk (realpath: every link followed). If that leads outside the project
+ * folder, faf refuses. A dangling link is refused — faf never creates a file at
+ * the end of a link. Anything whose real path is inside a `.git` folder is
+ * refused, always — with two narrow exceptions: faf's own git hook
+ * (`allowGitHooks`: one file directly inside the repo's hooks folder), and
+ * the repo's own git config file (`allowGitConfig`: the file `config`
+ * directly in the folder git names for it), where `faf diff
+ * --uninstall-driver` removes the section faf's install wrote.
+ *
+ * Rule 2 — a link leads to the same kind of file. faf follows a link only to a
+ * file with the same name (CLAUDE.md → docs/CLAUDE.md), or from one AI context
+ * file to another (CLAUDE.md → AGENTS.md; the set is FAF_CONTEXT_FILES). The
+ * link itself survives: faf writes the file it points at. `CLAUDE.md →
+ * README.md` or `project.html → package.json` is refused — faf would be
+ * writing a file it was never asked to write. A read of project context
+ * through a link must land on a .faf or .fafm file instead, so `project.faf →
+ * .env` is refused even though .env is in the project — or, for a read of an
+ * AI context file, on another AI context file (`faf recover` reads CLAUDE.md →
+ * AGENTS.md), the rule the writers use.
+ *
+ * Rule 3 — never leave a half-written file. A write goes to a temp file in the
+ * same folder, is flushed to disk (fsync), then renamed over the original in
+ * one step, keeping the original's permissions. If any step fails the temp
+ * file is removed and the original is exactly as it was: "not written;
+ * original kept". A plain writeFileSync truncates first, so a full disk, a
+ * quota or a killed process used to leave the user's file cut short. With
+ * `expect` (the bytes the caller read), the file is read again just before the
+ * rename and the write is refused if it changed in the meantime. Its mode is
+ * checked too: a file made read-only, or given other permissions, while faf
+ * was writing is not replaced.
+ *
+ * Rule 4 — text faf edits is UTF-8. readUtf8 decodes strictly: a UTF-16 file or
+ * any bytes that are not UTF-8 are refused, never turned into U+FFFD and
+ * written back.
+ *
+ * Rule 5 — a whole file faf renders replaces a file already there only when
+ * faf can prove it wrote it: project.html, the cards, `faf server-card --out`,
+ * a `faf taf --output` snapshot and a `faf decompile --output` file must be
+ * byte for byte what faf last wrote (their render hash, render-hash.ts); a
+ * `.fafb` must carry the FAFB header (see {@link safeReplaceOwned}). Anything
+ * else is refused unless the caller passes `force` (the CLI's `--force`).
+ *
+ * Rule 6 — detection reads stay inside the project. The files faf reads to fill
+ * slots and render context (README.md, package.json, pyproject.toml,
+ * Cargo.toml, go.mod, …) go through {@link repoFile}: resolved on disk, every
+ * link followed. A file whose real path, or the folder it sits in, leaves the
+ * project folder, runs through `.git`, or is a dangling link is absent to
+ * detection: it does not exist, and reading it gives nothing. A link that
+ * stays inside the project is followed (README.md → docs/README.md).
+ */
+import { type Dirent, type Stats } from 'fs';
+/** Why a path was refused. */
+export type SafePathReason = 'outside' | 'dangling' | 'not-a-file' | 'not-faf' | 'other-file' | 'git' | 'not-utf8' | 'changed' | 'not-owned' | 'not-yaml' | 'unplaceable';
+/**
+ * A path faf will not read or write, or a file faf will not change. Nothing
+ * was written; the file on disk is exactly as it was.
+ *   - `outside`, `dangling`, `not-a-file`, `not-faf`, `other-file`, `git`: the
+ *     path is refused (see {@link resolveInside}).
+ *   - `not-utf8`: the file is not UTF-8 (see {@link readUtf8}).
+ *   - `changed`: the file changed on disk after faf read it — its bytes, or its
+ *     mode (see the `expect` option of {@link safeWriteFile}).
+ *   - `not-owned`: a whole file faf renders is already there and faf cannot
+ *     prove it wrote every byte of it — it has no faf mark, or it was edited
+ *     since faf wrote it, or it is from before faf recorded a render hash (see
+ *     {@link safeReplaceOwned} and render-hash.ts).
+ *   - `not-yaml`: a .faf faf reads or edits is not valid YAML: "<file> is not
+ *     valid YAML (<reason>, line N) — faf left it unchanged"; or it parses to
+ *     a scalar or a list, not a mapping; or faf's scoring kernel cannot read
+ *     it (`faf score`, `faf compile`, `faf refresh`).
+ *   - `unplaceable`: faf could not place its managed block where its next run
+ *     finds it again, so it wrote nothing (see inject.ts).
+ *
+ * `onWrite` is true when faf refused at the write itself — it may have read
+ * the file before (a `.faf` read through a link, say) — and false when it
+ * refused before reading or writing anything.
+ */
+export declare class SafePathError extends Error {
+    readonly reason: SafePathReason;
+    /** The path as the caller named it (absolute). */
+    readonly path: string;
+    /** True when the refusal came at the write (faf may have read the file first). */
+    readonly onWrite: boolean;
+    constructor(reason: SafePathReason, path: string, message: string, opts?: {
+        onWrite?: boolean;
+        cause?: unknown;
+    });
+}
+export interface ResolveInsideOptions {
+    /** Resolving for a read of project context: a link must end at a `.faf` or
+     *  `.fafm` file — or, when the name is an AI context file (CLAUDE.md), at
+     *  another AI context file (CLAUDE.md → AGENTS.md), the rule the writers
+     *  use. A plain file is read under the name the caller gave. */
+    read?: boolean;
+    /**
+     * Resolving faf's own git hook (`faf hooks`) — one of the two exceptions
+     * to the `.git` rule. `dir` must be the repo's hooks folder as git names it
+     * (`git rev-parse --git-path hooks`, a folder named `hooks`), and `name` a
+     * hook file sitting directly in it (`pre-commit`). Only that file may be
+     * inside `.git`; nothing below or beside it. Links are still checked: a
+     * link must stay inside the hooks folder's real folder and end at a file of
+     * the same name.
+     */
+    allowGitHooks?: boolean;
+    /**
+     * Resolving the repo's own git config file (`faf diff --uninstall-driver`)
+     * — the other exception to the `.git` rule. `dir` must be the folder git
+     * names for it (the folder of `git rev-parse --git-path config`), and `name`
+     * the file `config` directly in it. Only that file may be inside `.git`;
+     * nothing below or beside it. A link must stay inside that folder and end
+     * at a file named `config`.
+     */
+    allowGitConfig?: boolean;
+}
+export interface SafeWriteOptions {
+    /** The project folder the write must stay inside. Default: the file's own folder. */
+    root?: string;
+    /**
+     * The bytes the caller read from the file. Just before the rename the file
+     * is read again; when it no longer equals `expect`, the temp file is removed
+     * and a SafePathError (`changed`) is thrown: "<file> changed on disk while
+     * faf was writing — not written; original kept". A string is compared as its
+     * UTF-8 bytes. `null` means the caller found no file there: if one has
+     * appeared, the write is refused the same way (a missing file stays
+     * missing). Omit it to write without the byte check (the mode check below
+     * still runs).
+     */
+    expect?: string | Uint8Array | null;
+    /** Write faf's own git hook: see {@link ResolveInsideOptions.allowGitHooks}. `root` is the hooks folder. */
+    allowGitHooks?: boolean;
+    /** Write the repo's own git config file: see {@link ResolveInsideOptions.allowGitConfig}. `root` is its folder. */
+    allowGitConfig?: boolean;
+    /** Permission bits for the written file. Default: the original's (a new
+     *  file gets the default create mode). */
+    mode?: number;
+}
+/**
+ * The files faf's block injector writes — one managed block, every other byte
+ * of the file kept. Each injector writer (writeClaudeMd, writeAgentsMd,
+ * writeGeminiMd, writeCursorrules, writeCopilotInstructions, writeMemoryMd,
+ * writeLlmsTxt, writeClaudeMemory) takes its file name from this table, so
+ * the set is exactly the files those writers target. A link from one of these
+ * names to another (CLAUDE.md → AGENTS.md) may be followed.
+ */
+export declare const FAF_CONTEXT_FILES: Readonly<{
+    readonly claude: "CLAUDE.md";
+    readonly agents: "AGENTS.md";
+    readonly gemini: "GEMINI.md";
+    readonly cursorrules: ".cursorrules";
+    readonly copilot: "copilot-instructions.md";
+    readonly memory: "MEMORY.md";
+    readonly llms: "llms.txt";
+}>;
+/**
+ * Resolve `name` inside the project folder `dir` and return the real path to
+ * read or write — or throw a SafePathError.
+ *
+ *   - the folder the file sits in must resolve to `dir` or below it
+ *   - a path whose real form runs through `.git` → refused, always (the two
+ *     exceptions: `allowGitHooks`, a hook file directly in the hooks folder,
+ *     and `allowGitConfig`, the file `config` directly in its git folder)
+ *   - a file that does not exist yet → its path inside the project
+ *   - a regular file → its path (spelled as on disk)
+ *   - a link → the file it points at, when that exists, is a regular file, is
+ *     inside the project and out of `.git`, and has the link's own name (or
+ *     both names are AI context files: CLAUDE.md → AGENTS.md). With `read`, the
+ *     file must be a .faf/.fafm file instead (`project.faf → config/team.faf`),
+ *     or — for an AI context file — another AI context file.
+ *   - anything else (a link out, a dangling link, a link to a file with
+ *     another name, a folder, a device) → refused
+ *
+ * `name` may be relative to `dir` or absolute. `dir` and the folder `name` sits
+ * in must exist (their ENOENT is thrown as is).
+ */
+export declare function resolveInside(dir: string, name: string, opts?: ResolveInsideOptions): string;
+/**
+ * Read a text file faf may write back — strictly as UTF-8. A UTF-8 BOM is kept
+ * (U+FEFF at the start of the text, as a plain read gives it). A UTF-16 BOM
+ * (FF FE or FE FF) or any byte sequence that is not UTF-8 is refused with a
+ * SafePathError (`not-utf8`): "<file> is not UTF-8 — faf left it unchanged". A
+ * lenient read would turn those bytes into U+FFFD, and the next write would
+ * lose them. Other read errors (ENOENT, EACCES, …) are thrown as they are.
+ * `path` is read as given: resolve it with {@link resolveInside} first.
+ */
+export declare function readUtf8(path: string): string;
+/** The bytes at `path`, or null when nothing is there (only ENOENT). */
+export declare function readBytesIfPresent(path: string): Buffer | null;
+/**
+ * Where detection may read `rel` in the project folder `dir` — its real path —
+ * or null when detection treats it as absent (Rule 6). `rel` names a file or a
+ * folder, relative to `dir` (as `join(dir, rel)`). Every link on the way is
+ * followed, the folders included; the result is null when:
+ *   - nothing is there, or a link on the way dangles or loops
+ *   - the real path leaves `dir` (README.md → ~/.aws/credentials, or a folder
+ *     on the way that is a link out)
+ *   - the real path runs through `.git` (README.md → .git/config)
+ * A link that stays inside `dir` is followed. `dir` is the folder detection
+ * was handed: the project, or a folder below it that detection reads on its
+ * own (a subfolder's manifest), so a link may not leave that folder either.
+ */
+export declare function repoFile(dir: string, rel: string): string | null;
+/**
+ * Run `scan` with `root` as the project folder for every detection read under
+ * it: a read in a subfolder (web/package.json) may then follow a link to
+ * anywhere inside `root` (../shared/web-package.json), not only inside that
+ * subfolder. A link out of `root` is still absent. Subfolder scans use this.
+ */
+export declare function withRepoRoot<T>(root: string, scan: () => T): T;
+/** True when `rel` (a file or a folder) is in the project folder `dir` for
+ *  detection: see {@link repoFile}. */
+export declare function repoExists(dir: string, rel: string): boolean;
+/** The text of the file `rel` in the project folder `dir` (UTF-8, read the way
+ *  detection reads it), or null when detection treats it as absent (see
+ *  {@link repoFile}), it is not a regular file, or it cannot be read. */
+export declare function readRepoFile(dir: string, rel: string): string | null;
+/** What `rel` is (its real path's stats) in the project folder `dir`, or null
+ *  when detection treats it as absent (see {@link repoFile}). */
+export declare function statRepoFile(dir: string, rel: string): Stats | null;
+/**
+ * The entries of the folder `rel` (default: `dir` itself) in the project
+ * folder `dir`, or null when detection treats the folder as absent (see
+ * {@link repoFile}) or it cannot be read. A link among them that leaves `dir`,
+ * dangles, or leads into `.git` is left out: detection does not see it. Each
+ * entry says what it is itself (a link is a link, as readdirSync gives it).
+ */
+export declare function readRepoDir(dir: string, rel?: string): Dirent[] | null;
+/**
+ * A write that failed partway — a full disk, a quota, a read-only file, a
+ * killed rename — with the file on disk exactly as it was: "<file>: not
+ * written; original kept (<why>)" ("not written" alone when there was no file).
+ * `cause` is the error underneath. The CLI prints it as one line.
+ */
+export declare class NotWrittenError extends Error {
+    /** The file that was not written. */
+    readonly path: string;
+    constructor(path: string, message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Write a file inside a project, safely: resolved with {@link resolveInside}
+ * (a link that leaves the project, dangles, or leads to a file with another
+ * name, and anything in `.git`, is refused), then replaced atomically (temp
+ * file in the same folder, fsync, rename; the original's permissions — and,
+ * where the OS allows, its owner — kept). On any failure the original is
+ * untouched and the Error says "not written; original kept". With `expect`,
+ * a file that changed after the caller read it is not replaced either
+ * (SafePathError `changed`); nor is one whose mode changed, or that became
+ * read-only, while faf was writing. Returns the real path written — the
+ * link's target when `path` is an in-project link.
+ */
+export declare function safeWriteFile(path: string, content: string | Uint8Array, opts?: SafeWriteOptions): string;
+/** Options for {@link safeReplaceOwned}. */
+export interface ReplaceOwnedOptions {
+    /** The project folder the write must stay inside. Default: the file's own folder. */
+    root?: string;
+    /** True when the bytes already at the path carry faf's own mark (faf wrote them). */
+    owns: (existing: Buffer) => boolean;
+    /** faf's mark in words, for the refusal: "the `_meta[\"one.faf/context\"]` block". */
+    mark: string;
+    /** Replace a file without the mark anyway — the explicit overwrite (`--force`). */
+    force?: boolean;
+    /** The bytes the caller read there earlier (`null`: no file then). When
+     *  given, the file must still hold them, else SafePathError `changed`. */
+    expect?: string | Uint8Array | null;
+}
+/**
+ * Write a whole file faf renders (project.html, a Server Card, an A2A card, a
+ * `.fafb`), replacing a file already at `path` only when faf can prove it wrote
+ * it: its bytes carry faf's own mark (`owns`). A file without the mark is
+ * refused — SafePathError `not-owned`: "<file> has no <mark>, so faf did not
+ * write it — faf left it unchanged." — and stays byte for byte, unless `force`
+ * asks to replace it. The link rules and the atomic write are
+ * {@link safeWriteFile}'s, and the write is refused if the file changed on
+ * disk after faf read it. Returns the real path written.
+ */
+export declare function safeReplaceOwned(path: string, content: string | Uint8Array, opts: ReplaceOwnedOptions): string;
+/**
+ * Create the folder `dir` inside the project folder `root`, with any missing
+ * folders between them, and return its real path. `root` itself is the
+ * caller's own folder: it is created as named when missing. Below it, faf
+ * never creates a folder through a link: an existing folder on the way that
+ * is a link leading out of `root` (or a dangling link) is refused, as is any
+ * part inside `.git` and anything on the way that is not a folder — so
+ * `.github → ~/elsewhere` cannot make faf create `~/elsewhere/workflows`.
+ */
+export declare function makeDirInside(root: string, dir?: string): string;
+/**
+ * Remove a file faf wrote — only when it still holds exactly `expect` (the
+ * bytes faf wrote or read there) and is a regular file inside `root` (default:
+ * its own folder), out of `.git`. A link is never removed (faf did not make
+ * it), and a file whose bytes changed is left as it is (SafePathError
+ * `changed`). Returns false when nothing was there.
+ */
+export declare function safeUnlink(path: string, opts: {
+    root?: string;
+    expect: string | Uint8Array;
+}): boolean;
+/** The marker file makeTempDir writes into every temp folder it makes, and
+ *  its exact content: `faf clear` removes only a folder that carries it. */
+export declare const TEMP_MARKER = ".faf-temp";
+/** Make a new temp folder for faf's own use — `<os temp>/<prefix>XXXXXX`, a
+ *  fresh name no one else can have made (mkdtemp) — write faf's marker file
+ *  into it ({@link TEMP_MARKER}), and return its real path. Anything faf puts
+ *  there (a clone, say) goes in a subfolder, beside the marker. */
+export declare function makeTempDir(prefix: string): string;
+/** Remove a temp folder {@link makeTempDir} made in this process, with what is
+ *  in it. Any other folder is refused (an Error; nothing removed). */
+export declare function removeTempDir(dir: string): void;
+/**
+ * Remove faf's own temp folders left behind by earlier runs (`faf clear`):
+ * only folders faf made — entries of the OS temp folder named exactly as
+ * mkdtemp names them (`prefix` plus six letters or digits), that are real
+ * folders (a link is left alone), belong to this user and carry the marker
+ * file {@link makeTempDir} writes into each one. A folder of yours that only
+ * starts with the prefix (`faf-git-my-notes`) stays. Returns how many were
+ * removed. A folder that cannot be read or removed is skipped.
+ */
+export declare function removeStaleTempDirs(prefix: string): number;

package/dist/core/scorer.d.ts

@@ -1,4 +1,8 @@
 import type { KernelScoreResult, ScoreResult } from './types.js';
+/** A score as text for display: `85%`, or `unknown (—)` when the result says
+ *  the score is not known (`unknown: true` — an About Repo with no
+ *  source_score). Never `-1%`. */
+export declare function scoreText(result: Pick<ScoreResult, 'score' | 'unknown'>): string;
 /** Convert kernel result into enriched ScoreResult */
 export declare function enrichScore(kernel: KernelScoreResult): ScoreResult;
 /**
@@ -8,8 +12,9 @@ export declare function enrichScore(kernel: KernelScoreResult): ScoreResult;
  * (`about.represents`). The scorer reads `about.source_score` and emits
  * that directly — no slot scoring, no kernel call.
  *
- * Optional: `about.source_score: <number>` — without it, score is -1
- * (renders as "—" honest unknown).
+ * Optional: `about.source_score: <number>` — without it the score is not
+ * known: the result carries `unknown: true` (with score -1 and a White tier
+ * as placeholders). Render that as "unknown" (—), never as "-1/100" or "-1%".
  *
  * Doctrine: memory/private-source-public-about-pattern.md.
  *