faf-cli 7.13.0 → 7.13.1

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

@@ -1,3 +1,61 @@
+/**
+ * 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';
 /**
@@ -133,6 +191,45 @@ export declare function resolveInside(dir: string, name: string, opts?: ResolveI
 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

package/dist/core/slots.d.ts

@@ -32,8 +32,8 @@ export declare const PLACEHOLDERS: Set<string>;
  *  Only in a tech slot the app-type leaves out does faf auto write
  *  `slotignored` over them — the app-type's decision, never the words'. */
 export declare const EXPLICIT_NONE: ReadonlySet<string>;
-/** The value that marks a slot as not applicable (the What-Not). It comes
- *  only from the app-type (shown to people as N/A); a typed word never means it. */
+/** The value that marks a slot as not required and not scored (the What-Not).
+ *  It comes only from the app-type; a typed word never means it. */
 export declare const SLOTIGNORED = "slotignored";
 /** True for a typed none — counts as an empty slot: `None`, `N/A`,
  *  `not applicable`, `none` (any case, any padding). */

package/dist/core/typed-none.d.ts

@@ -15,7 +15,7 @@ export interface TypedNoneHintOptions {
  *   - a slot the app-type needs:
  *     `<slot> says '<words>' — this app-type needs it, so it counts as empty until filled.`
  *   - a slot the app-type leaves out (before `faf auto` has run):
- *     `<slot> says '<words>' — this app-type doesn't use it; faf auto marks it slotignored (N/A).`
+ *     `<slot> says '<words>' — this app-type doesn't use it; faf auto marks it slotignored.`
  * A file whose type faf does not know, or whose type is the `library`
  * detection fell back to (see {@link typeIsFallback}), gives the first line
  * for the slots a library needs (as faf's detection reads such a file) and no

package/dist/detect/assemble.d.ts

@@ -29,7 +29,7 @@ export declare function assembleFreshFaf(dir: string): Record<string, unknown>;
  *     has them, comment included; faf never writes `''` over them.
  *   - In a tech slot the file's app-type (`project.type`) leaves out, the
  *     app-type's decision is the fact: with no repo fact, the slot becomes
- *     `slotignored` (shown as N/A) in place of the words, an empty value or a
+ *     `slotignored` in place of the words, an empty value or a
  *     placeholder. A real value there is kept. `slotignored` comes only from
  *     the app-type — in a slot the app-type uses, it is never written, even
  *     when detection reads the repo as another type; such a slot gets the