faf-cli 7.12.1 → 7.13.0

package/dist/interop/inject.d.ts

@@ -6,40 +6,130 @@
  */
 export declare const FAF_START = "<!-- faf:start -->";
 export declare const FAF_END = "<!-- faf:end -->";
+/** Split into lines keeping each line's own terminator (\r\n, \r or \n). */
+export declare function linesWithEnds(text: string): string[];
+export declare const stripEnd: (line: string) => string;
 /**
- * Locate the faf-managed block in `text`: the first START marker line and the
- * first END marker line after it. Returns the char range covering both marker
- * lines (terminator of the END line excluded), or null when there is no
- * complete block.
+ * faf's marked range in `text`: in each reading, the last START line before
+ * the first END line after it (the innermost pair — text between an earlier
+ * START and the last one is kept), both outside every Markdown region. The
+ * two readings must find the same pair; otherwise there is no range. Returns
+ * the char range covering both lines (the END line's terminator excluded), or
+ * null. A leading BOM on line 1 stays outside the range. `isStart` and
+ * `isEnd` are asked about each line shown as text in at least one reading,
+ * once, in order, on the line with its terminator and that BOM removed. Past
+ * MAX_OPEN_CONTAINERS open containers the CommonMark reading stops, and there
+ * is no range (a pair found before that point still counts). Time grows with
+ * the text's length, not with how deep it nests.
+ */
+export declare function findMarkedRange(text: string, isStart: (line: string) => boolean, isEnd: (line: string) => boolean): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Locate the faf-managed block in `text`: a START marker line and the first
+ * END marker line after it, both outside fenced and indented code, raw HTML
+ * blocks and multi-line HTML comments, under both readings (see
+ * {@link findMarkedRange}). Returns the char range covering both marker lines
+ * (terminator of the END line excluded), or null when there is no complete
+ * block both readings agree on.
  *
- * Markers are matched as WHOLE LINES at column 0, never as substrings. Substring
- * search was a real bug (7.1.4–7.11.0): renderAgentsMd quoted the marker tokens
- * in its own blockquote, so on every re-run `indexOf(end)` hit the quote, cut
- * the old block in half and appended its stale tail below the new block —
- * `faf export --agents` grew AGENTS.md by ~49 lines per run. The same happened
- * to users who documented the markers in a code fence above the block.
+ * Markers are matched as WHOLE LINES at column 0 — exactly the marker text,
+ * nothing after it — never as substrings. Substring search was a real bug
+ * (7.1.4–7.11.0): renderAgentsMd quoted the marker tokens in its own
+ * blockquote, so on every re-run `indexOf(end)` hit the quote, cut the old
+ * block in half and appended its stale tail below the new block — `faf
+ * export --agents` grew AGENTS.md by ~49 lines per run. The same happened to
+ * users who documented the markers in a code fence above the block.
  *
- * Two passes. The first skips START candidates inside fenced code, so a fenced
- * example is not mistaken for the block. Fence detection is a plain toggle and
- * Markdown has shapes it misreads (list-item fences, ```` around ```, a stray
- * unclosed fence), so if the first pass finds nothing the second ignores fences
- * entirely. A miss must never be silent: the caller treats "no block" as a
- * user file and prefixes — it does not overwrite.
+ * Two START lines before an END: the pair is the last START and that END.
+ * faf's own body never holds a column-0 START (see {@link wrapFafBlock}), so
+ * the text between the two STARTs is the user's and stays. A START with no
+ * END is not a block: the caller treats "no block" as a user file and
+ * prefixes — it never reclaims. faf's own block is always found again where
+ * faf put it (see {@link placeFafBlock}).
  */
 export declare function findFafBlock(text: string, start?: string, end?: string): {
     start: number;
     end: number;
 } | null;
+/** No line of faf's own body leaves more block quotes, lists and list items
+ *  open than this (as CommonMark reads it) — far below the reader's cap,
+ *  MAX_OPEN_CONTAINERS, so the next run always reads the block to its end,
+ *  quoted (one quote more) or not. See {@link capDepth}. */
+export declare const BODY_MAX_CONTAINERS = 16;
+/**
+ * `head`, faf's block (`wrapped`, from {@link wrapFafBlock}) and `tail` as one
+ * text in which {@link findFafBlock} finds the block exactly where it was put
+ * — so the next write updates it in place and never stacks a second one. A
+ * body that would not be found there (it leaves a region open in only one
+ * reading, or the text before it holds a raw HTML block the body continues)
+ * is quoted line by line instead. If even that is not found, it throws a
+ * SafePathError (`unplaceable`) naming `path` (the file being written):
+ * "<file>: faf could not place its block where the next run finds it again —
+ * faf left it unchanged" — one line, and nothing is written.
+ */
+export declare function placeFafBlock(head: string, wrapped: string, tail: string, start?: string, end?: string, path?: string): string;
+/** The managed block: START, the body (guarded — see guardBody), END. */
+export declare function wrapFafBlock(block: string, start?: string, end?: string): string;
+/** The file's new text: `existing` (null when there is no file) with `wrapped`
+ *  as its managed block, placed where the next scan finds it again (see
+ *  {@link placeFafBlock}; `path` names the file in its refusal). */
+export declare function withFafBlock(existing: string | null, wrapped: string, start?: string, end?: string, path?: string): string;
+/** Read a resolved path, or null when nothing is there yet. Only ENOENT reads
+ *  as "no file"; any other error is thrown, so a file faf could not read is
+ *  never treated as empty and written fresh. The text is decoded strictly: a
+ *  file that is not UTF-8 (a UTF-16 file, cp1252 bytes) is refused
+ *  (SafePathError `not-utf8`) and left as it is — see readUtf8. */
+export declare function readIfPresent(path: string): string | null;
+export interface InjectOptions {
+    /** The project folder the file must stay inside. Default: the file's own
+     *  folder. Pass it when the file sits in a subfolder (`.github/…`), so a
+     *  linked subfolder cannot carry the write out of the project. */
+    root?: string;
+}
 /**
  * Non-destructively write a faf-managed block into a file.
  *
  *   - file does not exist     → create it containing just the block
  *   - file has the markers    → replace ONLY the content between them (update in place)
- *   - legacy faf file         → metastamp-led, no marker lines: reclaim in place
- *   - file exists, no block   → PREFIX the block; everything the user wrote is preserved
+ *   - anything else           → PREFIX the block; everything already there is preserved
+ *                               (a leading BOM stays at byte 0)
+ *
+ * faf replaces only text it can prove it wrote: what sits between its own
+ * marker lines. A file with no marker lines is never reclaimed, whatever it
+ * starts or ends with. Idempotent: re-running updates the managed block in
+ * place and never duplicates it. Enhance, never replace.
  *
- * Idempotent: re-running updates the managed block in place and never duplicates
- * it or touches a byte the user owns. faf owns what's between the markers; the
- * user owns everything else. Enhance, never replace.
+ * The file is resolved inside its project first: a link that leads outside,
+ * a dangling link, a link to a file with another name (CLAUDE.md → README.md)
+ * and anything in `.git` are refused (SafePathError) and nothing is written; a
+ * link to a file of the same name, or between AI context files (CLAUDE.md →
+ * AGENTS.md), is written through and stays a link. A file that is not UTF-8
+ * is refused and left as it is. The write is atomic — a failure leaves the
+ * original exactly as it was — and is refused if the file changed on disk
+ * after faf read it. A block faf cannot place where its next run finds it
+ * again is refused too (SafePathError `unplaceable`), and nothing is written.
+ */
+export declare function injectFafBlock(path: string, block: string, start?: string, end?: string, opts?: InjectOptions): void;
+/**
+ * The one line the CLI prints when faf's block goes on top of a file that has
+ * no block of its own but holds older faf text — or null:
+ *   - the file's first line is faf's old metastamp (`<!-- faf: … -->`): faf
+ *     never reclaims such a file (it cannot prove it wrote the text), so the
+ *     old faf text stays below the new block;
+ *   - a whole-line START marker sits inside a code fence, a raw HTML block
+ *     or an HTML comment (in either reading — see {@link findFafBlock}): the
+ *     older block there is an example to faf, and stays below the new one;
+ *   - a whole-line START marker sits past more than MAX_OPEN_CONTAINERS
+ *     nested lists or quotes: faf did not read that far, and the older block
+ *     stays below the new one.
+ * `label` names the file (`CLAUDE.md`). `existing` is the file's text before
+ * the write (null when there was none). faf-mcp and claude-faf-mcp print the
+ * same line through this export.
  */
-export declare function injectFafBlock(path: string, block: string, start?: string, end?: string): void;
+export declare function legacyStampNote(label: string, existing: string | null, start?: string, end?: string): string | null;
+/** {@link legacyStampNote} for the file at `path`, read the way
+ *  injectFafBlock reads it — before the write. Null when there is no note, or
+ *  when the file cannot be read (the write itself then says why). */
+export declare function legacyStampNoteAt(path: string, label: string, start?: string, end?: string, opts?: InjectOptions): string | null;

package/dist/interop/projecthtml.d.ts

@@ -1,7 +1,24 @@
 import type { FafData, ScoreResult } from '../core/types.js';
 /** Render project.faf data + its score into a self-contained HTML string. */
 export declare function renderProjectHtml(data: FafData, result: ScoreResult, fafPath?: string): string;
-/** Write project.html beside project.faf (repo root). */
-export declare function writeProjectHtml(dir: string, data: FafData, result: ScoreResult, fafPath?: string): void;
+/** True when `bytes` are a project.html faf rendered: a line that is faf's
+ *  description meta (every faf release has written it). */
+export declare function hasProjectHtmlMark(bytes: Uint8Array): boolean;
+/** Options for {@link writeProjectHtml}. */
+export interface ProjectHtmlWriteOptions {
+    /** Replace a project.html faf cannot prove it wrote — no faf mark, edited
+     *  since faf wrote it, or from before 7.13 — the explicit overwrite
+     *  (`--force`). Default: it is refused and left as it is. */
+    force?: boolean;
+}
+/** Write project.html beside project.faf (repo root) — atomically, and never
+ *  through a link that leaves `dir` or dangles (SafePathError). The page
+ *  carries faf's render hash (`<meta name="faf-render" content="sha256:…">`,
+ *  the hash of the page without that line). A project.html already there is
+ *  replaced only when it is byte for byte what faf last wrote (its hash still
+ *  fits); a page edited since, a hand-written page, or a page from before 7.13
+ *  that is not exactly faf's render of `data` is refused (SafePathError
+ *  `not-owned`) and left byte for byte, unless `force`. */
+export declare function writeProjectHtml(dir: string, data: FafData, result: ScoreResult, fafPath?: string, write?: ProjectHtmlWriteOptions): void;
 /** @deprecated Use {@link renderProjectHtml}. Removed in the next major. */
 export declare const generateProjectHtml: typeof renderProjectHtml;

package/dist/interop/servercard.d.ts

@@ -63,10 +63,59 @@ export declare function registryName(data: FafData): string;
  *  omitted rather than shipped invalid — GitHub's registry then derives a name
  *  from the namespace, so set `project.title` to control the display. */
 export declare function registryTitle(data: FafData): string | undefined;
+/** True when `bytes` are a Server Card faf wrote: JSON carrying the FAF
+ *  context-block at `_meta["one.faf/context"]`, as every card faf has
+ *  written does. */
+export declare function hasServerCardMark(bytes: Uint8Array): boolean;
+/** True when `bytes` are a registry `server.json` carrying faf's identity:
+ *  `_meta[REGISTRY_PUBLISHER_KEY]["one.faf/context"]`. */
+export declare function hasRegistryMark(bytes: Uint8Array): boolean;
+/** Options for the card writers ({@link writeServerCard}, `faf cards`). */
+export interface CardWriteOptions {
+    /** Replace a card faf cannot prove it wrote — no faf mark, edited since
+     *  faf wrote it, or from before 7.13 — the explicit overwrite (`--force`).
+     *  Default: such a file is refused and left as it is. */
+    force?: boolean;
+}
 /** Write the Server Card to a `server-card` file. Returns the path.
  *  Per experimental-ext-server-card#22 the reserved location is
  *  `<streamable-http-url>/server-card` (no longer `.well-known`); serve the
- *  emitted file there as `application/mcp-server-card+json`. */
-export declare function writeServerCard(dir: string, data: FafData, opts?: ServerCardOptions): string;
+ *  emitted file there as `application/mcp-server-card+json`.
+ *
+ *  The card carries faf's render hash at `_meta["one.faf/render"]` (the hash
+ *  of the card without that key; the Server Card schema leaves `_meta` open
+ *  for namespaced keys). A `server-card` already there is replaced only when
+ *  it is byte for byte what faf last wrote (its hash still fits); a card edited
+ *  since, a hand-written card, or a card from before 7.13 that is not exactly
+ *  faf's render of `data` is refused (SafePathError `not-owned`) and left byte
+ *  for byte, unless `force`. The write is atomic and never goes through a link
+ *  that leaves `dir` or dangles. */
+export declare function writeServerCard(dir: string, data: FafData, opts?: ServerCardOptions, write?: CardWriteOptions): string;
+/** The identity faf owns in a registry `server.json`. */
+export interface ServerJsonIdentity {
+    /** The reverse-DNS registry name ({@link registryName}). */
+    name: string;
+    /** The display title ({@link registryTitle}); when undefined the file's own title is kept. */
+    title?: string;
+    /** A version to set (`--set-version`); when undefined the file's own is kept. */
+    version?: string;
+    /** The `_meta` faf writes ({@link registryMeta}). */
+    meta: Record<string, unknown>;
+}
+/**
+ * Put faf's identity into the text of a registry `server.json`, changing
+ * nothing else: the `name` value, the `title` (only when faf has one — the
+ * file's own title is kept otherwise), a `version` asked for, and the keys of
+ * faf's context-block under `_meta[REGISTRY_PUBLISHER_KEY]["one.faf/context"]`.
+ * Each is a text edit of that one value, or the key added when missing; no
+ * field is deleted, and every other byte — key order, a 20-digit number, an
+ * array on one line, spacing, CRLF — stays as it was. Throws a JsonEditError,
+ * changing nothing, when the text cannot be edited that way (not valid JSON,
+ * not an object, a key repeated on the way, a `_meta` that is not an object).
+ */
+export declare function patchServerJson(text: string, identity: ServerJsonIdentity): {
+    text: string;
+    changed: boolean;
+};
 /** @deprecated Use {@link buildServerCard}. Removed in the next major. */
 export declare const generateServerCard: typeof buildServerCard;

package/dist/wasm/kernel.d.ts

@@ -1,11 +1,14 @@
 import type { KernelScoreResult, FafbInfo } from '../core/types.js';
-/** Score a .faf YAML string (21 base slots) */
+/** Score a .faf YAML string (21 base slots), as the file is. A typed None /
+ *  N/A / not applicable at a slot is an empty slot, as in every engine. A
+ *  leading BOM is not scored (`faf auto` and `faf score` read a BOM file). */
 export declare function score(yaml: string): KernelScoreResult;
-/** Score a .faf YAML string (33 enterprise slots) */
+/** Score a .faf YAML string (33 enterprise slots), as the file is (a leading BOM is not scored). */
 export declare function scoreEnterprise(yaml: string): KernelScoreResult;
-/** Validate .faf YAML */
+/** Validate .faf YAML (a leading BOM is left out, as in {@link score}: `faf check` reads a BOM file). */
 export declare function validate(yaml: string): boolean;
-/** Compile .faf YAML to FAFb binary */
+/** Compile .faf YAML to FAFb binary (a leading BOM is not compiled, as in
+ *  {@link score}: `faf compile` and `faf refresh` read a BOM file). */
 export declare function compile(yaml: string): Uint8Array;
 /** Decompile FAFb binary to JSON info */
 export declare function decompile(bytes: Uint8Array): FafbInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faf-cli",
-  "version": "7.12.1",
+  "version": "7.13.0",
   "description": "Persistent AI context + memory — .faf and .fafm, IANA-registered. Anthropic-merged.",
   "type": "module",
   "icon": "https://faf.one/orange-smiley.svg",
@@ -31,10 +31,11 @@
     "compile:all": "bun build src/cli.ts --compile --bytecode --minify --target=bun-darwin-arm64 --outfile faf-darwin-arm64 && bun build src/cli.ts --compile --bytecode --minify --target=bun-darwin-x64 --outfile faf-darwin-x64 && bun build src/cli.ts --compile --bytecode --minify --target=bun-linux-x64 --outfile faf-linux-x64 && bun build src/cli.ts --compile --bytecode --minify --target=bun-windows-x64 --outfile faf-windows-x64.exe",
     "test": "bun test --timeout=120000",
     "test:watch": "bun test --watch --timeout=120000",
-    "lint": "eslint src/**/*.ts",
+    "lint": "eslint 'src/**/*.ts'",
     "format": "prettier --write 'src/**/*.ts'",
     "check:no-hardcode": "! grep -rEln '/(Users|home/runner|private/var)/' dist/ || (echo '❌ Hardcoded build-machine path leaked into dist — see grep output above. Externalize the offending dep in the build script.'; exit 1)",
-    "prepublishOnly": "bun run build && bun run check:no-hardcode"
+    "check:engines": "node scripts/check-engines.mjs",
+    "prepublishOnly": "bun run check:engines && bun run build && bun run check:no-hardcode"
   },
   "keywords": [
     "faf",
@@ -94,7 +95,7 @@
     "picomatch": "^4.0.5"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "publishConfig": {
     "access": "public"

package/project.faf

@@ -1,8 +1,8 @@
 faf_version: "3.0"
 project:
   name: faf-cli
-  version: "7.12.1"
-  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v7.12.1 The Open Renderers Edition."
+  version: "7.13.0"
+  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v7.13.0 The Co-Author Edition."
   main_language: TypeScript
   type: cli  # found: package.json bin
 # Commands + key_files feed `faf export --agents` (hand values win over detection).
@@ -58,7 +58,7 @@ human_context:
   what: Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-merged.
   why: Eliminates 91% context re-discovery tax — define once, AI remembers forever
   where: npm registry, Homebrew, GitHub
-  when: Production since September 2025; Bun-native since v6; current package 7.12.1
+  when: Production since September 2025; Bun-native since v6; current package 7.13.0
   how: bunx faf-cli auto, then project.faf versions with your code — faf show renders it human-visible
 monorepo:
   packages_count: slotignored
@@ -68,7 +68,7 @@ monorepo:
   remote_cache: slotignored
 surfaces:
   # Distribution map — the machine-checkable form of human_context.where. Score-neutral.
-  auto:                      # derived from manifests; regenerate with `faf surface --sync`
+  auto:                      # derived from manifests; re-derive with the /surface skill
     - { type: npm,    id: faf-cli,           source: "package.json#name" }
     - { type: github, id: Wolfe-Jam/faf-cli, source: "package.json#repository" }
   declared:                  # hand-authored: surfaces the manifests don't carry + targets
@@ -89,3 +89,10 @@ ai_instructions:
     testing: WJTTC — zero errors always; bun test green before any ship.
     runtime: Bun-native since v6, TypeScript strict, Rust→WASM scoring kernel.
     releases: Atomic via /pubpro — bump, verify, tag, publish in one motion.
+tech_stack:
+  - TypeScript
+  - Bun
+  - commander
+  - faf-scoring-kernel
+  - open
+  - yaml