@fro.bot/wiki-write-core 0.1.4 → 0.3.0

package/README.md

@@ -15,7 +15,13 @@ pnpm add @fro.bot/wiki-write-core
 - Node `>=24`.
 - **ESM-only.** The exports declare `import` and `types` conditions, with no `require` condition and no CommonJS build. CommonJS consumers fail at package resolution by design.
 
-The package ships unbundled ESM JavaScript with declaration files from the committed `dist/` directory. No install-time build step is required. CI rebuilds `dist/` in a temporary directory and fails when the committed output differs from `src/`.
+The published package ships unbundled ESM JavaScript with declaration files in `dist/`. No install-time build step is required.
+
+In the repository the package resolves to its TypeScript source: `exports` maps every subpath to `./src/<name>.ts`, and the only file committed under `dist/` is `gate-contract.json`. The release build compiles `dist/` and stages a manifest that differs from the committed one in `exports` alone, pointing each subpath at `./dist/<name>.js` with `./dist/<name>.d.ts` as its types. `npm pack` and `npm publish` run from that staged directory, so the committed manifest is never rewritten.
+
+`bun run check:wiki-write-core-package` is the local and CI check: it builds the package, fails when the committed `dist/gate-contract.json` differs from the fresh build, packs the staged package, unpacks the tarball into a scratch `node_modules`, then resolves and imports every `exports` subpath under Node and type-checks a consumer module that imports them all. `bun run build` rewrites the committed marker after a change under `src/`, `tsconfig.build.json` or the manifest's `exports` or `files`.
+
+`--stage <dir>` replaces whatever is at `<dir>`, so it refuses anything but a target that resolves (through symlinks) to somewhere strictly under the OS temp directory or `RUNNER_TEMP`, and it replaces an existing directory only when a previous stage left its `wiki-write-core-stage.marker` there. A root must be absolute and must not resolve to a filesystem root (so `RUNNER_TEMP=/` is refused), and a stage that contains a hidden file or directory is refused, because `upload-artifact` drops them and the publish job's digest would no longer match. The target is judged before anything is built or written, so a refused run leaves the committed `dist/gate-contract.json` alone, and again just before the replacement. Refusals happen before anything is created, moved or removed. If a replacement fails and the original cannot be restored either, the original is kept in a `.wiki-write-core-dist-backup-*` sibling and the error names it.
 
 ## Fro Bot defaults
 
@@ -27,9 +33,9 @@ The package targets the Fro Bot control plane and carries its coordinates as def
 
 When a call receives no Octokit client (`params.octokit`), it reads `GITHUB_TOKEN` from the environment and fails with a remediation message if the variable is unset.
 
-The build also emits `dist/gate-contract.json` with `version` from `GATE_CONTRACT_VERSION` and `sourceTreeHash` from the same computed source hash embedded in `gate-contract.js`. Downstream writers can fetch this marker through the repository contents API; the same distribution drift check verifies the committed marker. `version` is the gate criterion: a mismatch means a deliberate contract break and refuses writes. `sourceTreeHash` is diagnostic only: it moves with ordinary source changes and reports drift in the pinned copy, but must never block writes.
+The build also emits `dist/gate-contract.json` with `version` from `GATE_CONTRACT_VERSION` and `sourceTreeHash` from the same computed source hash embedded in `gate-contract.js`. This is the one file committed under `dist/`: downstream writers fetch it from `main`, so it stays at that path. `bun run check:wiki-write-core-package` verifies the committed marker against a fresh build, and the same marker ships in the tarball. `version` is the gate criterion: a mismatch means a deliberate contract break and refuses writes. `sourceTreeHash` is diagnostic only: it moves with ordinary source changes and reports drift in the pinned copy, but must never block writes.
 
-The package exports `GATE_CONTRACT_VERSION` and `GATE_SOURCE_TREE_HASH` from its root entrypoint. The build embeds a deterministic hash covering every non-test TypeScript file under `src/`, the resolved `tsconfig.build.json` configuration including inherited settings, and canonicalized `exports` and `files` values from `package.json`. Object-key order and `files` array order do not affect the hash. The hash does not cover tests, this README, other manifest fields such as dependencies or version, or runtime dependencies. Because it hashes the _resolved_ compiler configuration, a TypeScript upgrade that changes an inherited default or the `--showConfig` serialization moves the hash with no semantic change to the shipped code; a hash that shifts across a compiler bump is expected and does not by itself indicate gate drift.
+The package exports `GATE_CONTRACT_VERSION` and `GATE_SOURCE_TREE_HASH` from its root entrypoint. In the repository that entrypoint is source, so `GATE_SOURCE_TREE_HASH` is the placeholder `__SOURCE_TREE_HASH__`; only the built `dist/gate-contract.js` in the tarball carries the hash. The build embeds a deterministic hash covering every non-test TypeScript file under `src/`, the resolved `tsconfig.build.json` configuration including inherited settings, and canonicalized `exports` and `files` values of the published manifest (`exports` in its `dist` form). Object-key order and `files` array order do not affect the hash. The hash does not cover tests, this README, other manifest fields such as dependencies or version, or runtime dependencies. Because it hashes the _resolved_ compiler configuration, a TypeScript upgrade that changes an inherited default or the `--showConfig` serialization moves the hash with no semantic change to the shipped code; a hash that shifts across a compiler bump is expected and does not by itself indicate gate drift.
 
 `GATE_SOURCE_TREE_HASH` is the automatic drift detector: compare it when you need to know whether the shipped gate inputs changed. `GATE_CONTRACT_VERSION` is a deliberate, human-set marker for an intentional consumer-visible contract break; it is not expected to change for every source edit. Neither value proves that dependencies or the runtime behave identically. Consumers should compare the source hash for ordinary gate-input drift and the contract version when deciding whether an intentional contract migration is required.
 
@@ -39,6 +45,30 @@ The package exports `GATE_CONTRACT_VERSION` and `GATE_SOURCE_TREE_HASH` from its
 
 `WikiLintFindingKind` includes `correction-eroded` for a blocking active-correction failure and `correction-needs-reconfirmation` for an advisory lifecycle or formatting-only change. Both retain the existing `{kind, path, message, target?}` runtime shape and fingerprint derivation. Consumers with exhaustive matches must handle both kinds.
 
+A page that opens a frontmatter block and never closes it is reported as `invalid-frontmatter`; it was reported as `missing-frontmatter` while the block was read as no block. Wiki repair counts such a page as out of scope, as it does for any `invalid-frontmatter` finding.
+
+## Frontmatter block
+
+`splitFrontmatterBlock(content)` (exported from the root entry and from `@fro.bot/wiki-write-core/frontmatter`) finds the YAML frontmatter block at the start of a document. It does not parse YAML. The root entry already exports the wiki page reader as `splitFrontmatter`, so the splitter has another name.
+
+- The block opens only when the content starts with a line that is exactly `---`. A trailing space, a byte-order mark or a blank line before it means there is no block.
+- A line ending is LF or CRLF; a lone CR is part of its line.
+- The block closes at the first later line that is `---` followed only by spaces or tabs. `---x`, `----` and `--- text` are content of the block.
+- The result is `{kind: 'none'}`, `{kind: 'malformed'}` (opened and never closed, which includes a file that is only `---`) or `{kind: 'block', opening, text, textEnding, closing, body}`. A block carries the pieces that put the document back: `opening + text + textEnding + closing + body` is the original content. `text` is what a YAML parser reads (it is `''` for an empty block); `textEnding` is the line ending of the last line of `text`, or `''` for a block with no lines; `closing` is the closing line with its spaces, tabs and line ending. A caller that rewrites a line of `text` rebuilds the file from the result alone and keeps every other byte.
+- The scan visits each line once, so its running time grows linearly with the content, an unclosed block included.
+
+The package's own readers (`parseFrontmatterDocument`, `splitFrontmatter`, the ingest's page parser and the repo-page move) all use it. Each keeps its error texts and its body handling. An empty block is an empty mapping for the document reader and the ingest parser; a block that parses to `null` (whitespace, comments, `null`, `...`) is not a mapping and gets each reader's rule for a non-mapping. The wiki page reader reports an unclosed block as `Invalid frontmatter: missing closing --- delimiter`.
+
+The wiki page reader also says why a page could not be read, apart from the text. `splitFrontmatter` returns `errorKind` next to `error`, and `parseWikiPage` and `collectWikiPages` return `frontmatterErrorKind` next to `frontmatterError` (type `WikiFrontmatterErrorKind` from `@fro.bot/wiki-write-core/wiki-utils`). The kind is `'unclosed'` for a block that opens and never closes (the text above) and `'invalid'` for a block the YAML parser rejects (`Invalid YAML frontmatter: <parser message>`). The kind is present exactly when the text is, and the text is unchanged. A block that parses to something other than a mapping is read as empty frontmatter with no error, so it has no kind. Switch on the kind; do not match the wording of the text.
+
+## Target page sources
+
+When the ingest writes the page of the `repo:` target and that page lists no sources (no `sources` key, or an empty list), the page lists `{url, accessed}` with the target's `https://github.com/<owner>/<name>` URL and the date of the ingest's timestamp. When the page on the branch already has an entry for the target, its whole `sources` list is carried over as it is, so a repeat write changes nothing, a repeat after a migration included. The stamp applies only when the owner and name are plain GitHub names (ASCII letters, digits, `.`, `_` and `-`, not `.` or `..`); for any other target the page is written without one. A page that lists any source is never changed, and neither is a `sources` value that is not a list. When the ingest migrates a page to the target's slug by a trusted node ID, the merged page also gains the target's URL if no entry matches it, and keeps its other entries. No other repo page in the write is stamped, and a write whose target is a page path (the dashboard's case) is never stamped. Whether an entry matches the target uses the privacy gate's URL rule: `https`, host `github.com`, no port, owner and name equal without case, any path after them.
+
+## Gate contract version
+
+`GATE_CONTRACT_VERSION` stays at 1 for the splitter and the reader changes. A bump makes every dashboard save fail until the dashboard ships a release that carries the same version, and the changes here do not need that: no page on `data` changes meaning, the dashboard already has a message for both lint finding kinds, and the dashboard writes with its own installed copy of this package. `dist/gate-contract.json` still changes, because its `sourceTreeHash` follows the source.
+
 ## Releasing
 
 A merge to `main` that changes `packages/wiki-write-core/` releases the package through `.github/workflows/release-wiki-write-core.yaml`. Versions are the `wiki-write-core-v<version>` tags (for example `wiki-write-core-v0.1.1`), and each tag has a GitHub release.
@@ -55,10 +85,13 @@ Only commits that touch `packages/wiki-write-core/` are analyzed. The commit typ
 - A scoped suppression wins over a breaking marker: `build(dev)!:` releases nothing.
 - While the package is 0.x it never releases a major version; a breaking change is a minor bump.
 - A commit containing `[skip release]` (or `[release skip]`) is ignored by the release analysis.
+- Pull requests are squash-merged with `squash_merge_commit_title: PR_TITLE` (`common-settings.yaml`), so the PR title is the commit header the analysis reads. Pick the title type for the release you want.
+- A PR that changes only tests, docs other than the README, or other files under `packages/wiki-write-core/` that should not ship needs a non-releasing title (`test:`, `docs:`, `chore:`, `refactor:` or `build(dev):`). A `fix:` or `build:` title there publishes a patch.
+- A PR that changes nothing under `packages/wiki-write-core/` does not count toward the release type, whatever its own type. The release runs on every push to `main` and reads every package commit since the last release tag, so such a merge can still publish an earlier package change that has not been released yet.
 
 ### Publishing
 
-The `publish` job uses npm trusted publishing (OIDC) from `release-wiki-write-core.yaml` in the `release` environment, and publishes with provenance. There is no npm token. It publishes the committed `dist/`, which the `build` job proves equals a fresh build.
+The `publish` job uses npm trusted publishing (OIDC) from `release-wiki-write-core.yaml` in the `release` environment, and publishes with provenance. There is no npm token. It publishes the package the `build` job staged: the compiled `dist/` and a manifest whose `exports` point at it. The `build` job proves the packed tarball resolves, imports and type-checks every export. The `publish` job runs no repository script. The `build` job exposes a digest of the staged tree (sha256 over the `<sha256>  <path>` listing of every file, in byte order of the path) as a job output, which comes from the runner that built the package and not from the artifact store. The `publish` job recomputes it over what it downloaded and refuses unless the two are equal, before it reads or installs anything. It then checks that the staged manifest is the committed one with `exports` rewritten (each `./src/<name>.ts` becomes `./dist/<name>.js` with `./dist/<name>.d.ts` as its types, and no target has a `.`, `..` or empty segment) and replaces the checkout's `package.json` and `dist/` with the staged files. semantic-release then changes only the manifest's `version` (`npm version`, which the digest does not cover because it is checked first), and `npm publish` packs the same files the `build` job's tarball check proved.
 
 Verify a release:
 

package/dist/frontmatter-block.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What `splitFrontmatterBlock` found at the start of a document.
+ *
+ * - `none`: the content does not open a block.
+ * - `malformed`: the content opens a block and never closes it. It carries no content, so a caller cannot read
+ *   the pieces of a block that was not closed.
+ * - `block`: the content opens and closes a block. The five strings put the content back byte for byte:
+ *   `opening + text + textEnding + closing + body` is the original content.
+ *
+ * The pieces are strings, not offsets, so an editor that rewrites a line of the block rebuilds the file from the
+ * result alone, with the line endings, trailing spaces and body it found.
+ */
+export type FrontmatterBlockSplit = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'malformed';
+} | {
+    readonly kind: 'block';
+    /** The opening line with its line ending: `---` and LF or CRLF. */
+    readonly opening: string;
+    /**
+     * The lines between the opening and the closing line, each with the line ending it has, except the last line,
+     * whose ending is `textEnding`. It is what a YAML parser reads. It is `''` for a block with no lines and for
+     * a block of one blank line, which `textEnding` tells apart.
+     */
+    readonly text: string;
+    /** The line ending of the last line of `text`: `\n`, `\r\n`, or `''` when the block has no lines. */
+    readonly textEnding: string;
+    /** The closing line: `---`, any spaces or tabs after it, and its line ending. It has none at the end of the content. */
+    readonly closing: string;
+    /** Everything after the closing line, untouched. */
+    readonly body: string;
+};
+/**
+ * Finds the YAML frontmatter block at the start of `content`. It does not parse the YAML.
+ *
+ * The block rule:
+ * - The content starts with a line that is exactly `---`. A space, a byte-order mark, a blank line or any other
+ *   character before it or after it, on that line, means there is no block.
+ * - A line ending is LF or CRLF. A lone CR is part of its line.
+ * - The block ends at the first later line that is `---` followed only by spaces or tabs. A line such as `---x`,
+ *   `----` or `--- text` is part of the block.
+ * - A block can be empty: `---` directly followed by `---` gives empty text.
+ * - A block that is opened and never closed is malformed, and so is a file that is only `---`.
+ *
+ * The content is cut at its line feeds once and each piece is visited once, so the running time is linear in the
+ * length of the content, and the loop is bounded by the number of pieces.
+ */
+export declare function splitFrontmatterBlock(content: string): FrontmatterBlockSplit;

package/dist/frontmatter-block.js

@@ -0,0 +1,62 @@
+/**
+ * Finds the YAML frontmatter block at the start of `content`. It does not parse the YAML.
+ *
+ * The block rule:
+ * - The content starts with a line that is exactly `---`. A space, a byte-order mark, a blank line or any other
+ *   character before it or after it, on that line, means there is no block.
+ * - A line ending is LF or CRLF. A lone CR is part of its line.
+ * - The block ends at the first later line that is `---` followed only by spaces or tabs. A line such as `---x`,
+ *   `----` or `--- text` is part of the block.
+ * - A block can be empty: `---` directly followed by `---` gives empty text.
+ * - A block that is opened and never closed is malformed, and so is a file that is only `---`.
+ *
+ * The content is cut at its line feeds once and each piece is visited once, so the running time is linear in the
+ * length of the content, and the loop is bounded by the number of pieces.
+ */
+export function splitFrontmatterBlock(content) {
+    const pieces = content.split('\n');
+    const lastIndex = pieces.length - 1;
+    // `offset` is where the piece being read starts. `openingLength` is the length of the opening line with its line
+    // feed, and `textEnd` is where the lines before the piece end, before their line ending.
+    let offset = 0;
+    let openingLength = 0;
+    let textEnd = 0;
+    for (const [index, piece] of pieces.entries()) {
+        // A piece that ends with a carriage return has a CRLF ending when a line feed followed it, that is, unless it is
+        // the last piece.
+        const line = index < lastIndex && piece.endsWith('\r') ? piece.slice(0, -1) : piece;
+        if (index === 0) {
+            if (line !== '---')
+                return { kind: 'none' };
+            openingLength = piece.length + 1;
+            textEnd = openingLength;
+        }
+        else if (isCloseLine(line)) {
+            const lineEnd = offset + piece.length + 1;
+            return {
+                kind: 'block',
+                opening: content.slice(0, openingLength),
+                text: content.slice(openingLength, textEnd),
+                textEnding: content.slice(textEnd, offset),
+                closing: content.slice(offset, lineEnd),
+                body: content.slice(lineEnd),
+            };
+        }
+        else {
+            textEnd = offset + line.length;
+        }
+        offset += piece.length + 1;
+    }
+    return { kind: 'malformed' };
+}
+/** Whether `line` is `---` followed only by spaces and tabs. */
+function isCloseLine(line) {
+    if (!line.startsWith('---'))
+        return false;
+    for (let at = 3; at < line.length; at += 1) {
+        const character = line.charAt(at);
+        if (character !== ' ' && character !== '\t')
+            return false;
+    }
+    return true;
+}

package/dist/frontmatter.d.ts

@@ -1,8 +1,12 @@
+export { splitFrontmatterBlock, type FrontmatterBlockSplit } from './frontmatter-block.js';
 export interface FrontmatterDocument {
     readonly values: Record<string, unknown>;
     readonly body: string;
 }
-/** Parse a validated wiki document while retaining its raw body. */
+/**
+ * Parse a validated wiki document while retaining its raw body. A document with no block, or with a block that is
+ * never closed, is missing its frontmatter. A block with no lines is an empty mapping; any other block must parse to one.
+ */
 export declare function parseFrontmatterDocument(content: string): FrontmatterDocument;
 /** Reconstruct a wiki document with system-owned frontmatter and normalized body. */
 export declare function renderFrontmatterDocument(values: Record<string, unknown>, body: string): string;

package/dist/frontmatter.js

@@ -1,14 +1,20 @@
 import { parse, stringify } from 'yaml';
-/** Parse a validated wiki document while retaining its raw body. */
+import { splitFrontmatterBlock } from "./frontmatter-block.js";
+export { splitFrontmatterBlock } from "./frontmatter-block.js";
+/**
+ * Parse a validated wiki document while retaining its raw body. A document with no block, or with a block that is
+ * never closed, is missing its frontmatter. A block with no lines is an empty mapping; any other block must parse to one.
+ */
 export function parseFrontmatterDocument(content) {
-    const match = /^---\n([\s\S]+?)\n---\n?/u.exec(content);
-    if (match === null || match[1] === undefined) {
+    const split = splitFrontmatterBlock(content);
+    if (split.kind !== 'block') {
         throw new Error('validated wiki page is missing frontmatter');
     }
-    const parsed = parse(match[1]);
+    // Only a block with no lines is an empty mapping. A block of one blank line parses to null, like any blank text.
+    const parsed = split.text === '' && split.textEnding === '' ? {} : parse(split.text);
     if (!isRecord(parsed))
         throw new Error('validated wiki page frontmatter is not an object');
-    return { values: parsed, body: content.slice(match[0].length) };
+    return { values: parsed, body: split.body };
 }
 /** Reconstruct a wiki document with system-owned frontmatter and normalized body. */
 export function renderFrontmatterDocument(values, body) {

package/dist/gate-contract.js

@@ -1,4 +1,4 @@
 // Bump deliberately when an intentional consumer-visible gate contract break ships.
 export const GATE_CONTRACT_VERSION = 1;
 // Replaced with the deterministic source-tree hash by the package build.
-export const GATE_SOURCE_TREE_HASH = 'f5e534cd9cc3438f27eee34dd45045ae986891c230ad0af86fcc35ea1e12a2f6';
+export const GATE_SOURCE_TREE_HASH = 'bc3fa911b668e723571bcdb57e15a619e6998ac71675b03330719ad662d54d1b';

package/dist/gate-contract.json

@@ -1 +1 @@
-{"version":1,"sourceTreeHash":"f5e534cd9cc3438f27eee34dd45045ae986891c230ad0af86fcc35ea1e12a2f6"}
+{"version":1,"sourceTreeHash":"bc3fa911b668e723571bcdb57e15a619e6998ac71675b03330719ad662d54d1b"}

package/dist/repo-page-move.js

@@ -13,6 +13,7 @@
  *   repository URL. The body is never consulted.
  * - `log.md` history and `knowledge/wiki/README.md` are never rewritten.
  */
+import { splitFrontmatterBlock } from "./frontmatter-block.js";
 import { parseFrontmatterDocument, renderFrontmatterDocument } from "./frontmatter.js";
 import { parseRelatedFlow } from "./line-scanners.js";
 import { appendLogEntry, rebuildWikiIndex, validateWikilinks, WikiIngestError } from "./wiki-ingest.js";
@@ -293,21 +294,21 @@ function repairRelated(content, oldSlug, newSlug) {
 }
 /**
  * Edit only the `related:` lines of the frontmatter text, so the rest of the page keeps its bytes.
- * Returns `undefined` for a layout it does not recognize; the caller then re-renders structurally.
+ * Returns `undefined` for a layout it does not recognize, and for a block with a CRLF line ending anywhere in it,
+ * the closing line included, which the edit would otherwise leave half rewritten; the caller then re-renders structurally.
  */
 function editRelatedText(content, oldSlug, newSlug) {
-    const match = /^---\n([\s\S]+?)\n---\n?/u.exec(content);
-    const frontmatter = match?.[1];
-    if (frontmatter === undefined)
+    const split = splitFrontmatterBlock(content);
+    if (split.kind !== 'block' || hasCrlf(split))
         return undefined;
-    const lines = frontmatter.split('\n');
+    const lines = split.text.split('\n');
     const flowIndex = lines.findIndex(line => parseRelatedFlow(line) !== undefined);
     if (flowIndex !== -1) {
         const inner = parseRelatedFlow(lines[flowIndex] ?? '') ?? '';
         const items = inner.split(',').map(item => item.trim());
         const mapped = dedupe(items.map(item => (stripQuotes(item) === oldSlug ? swapQuoted(item, newSlug) : item)));
         lines[flowIndex] = `related: [${mapped.join(', ')}]`;
-        return replaceFrontmatter(content, frontmatter, lines.join('\n'));
+        return rebuild(split, lines.join('\n'));
     }
     const keyIndex = lines.findIndex(line => RELATED_BLOCK_KEY.test(line));
     if (keyIndex === -1)
@@ -327,7 +328,7 @@ function editRelatedText(content, oldSlug, newSlug) {
         kept.push(item.value === oldSlug ? `${item.prefix}${item.quote}${newSlug}${item.quote}${item.suffix}` : line);
     }
     lines.splice(keyIndex + 1, cursor - keyIndex - 1, ...kept);
-    return replaceFrontmatter(content, frontmatter, lines.join('\n'));
+    return rebuild(split, lines.join('\n'));
 }
 /** Parse one `  - value` line of a block sequence without a backtracking regex. */
 function parseBlockItem(line) {
@@ -346,9 +347,16 @@ function parseBlockItem(line) {
     const quoted = raw.length >= 2 && (first === "'" || first === '"') && raw.endsWith(first);
     return { prefix, quote: quoted ? (first ?? '') : '', value: quoted ? raw.slice(1, -1) : raw, suffix };
 }
-function replaceFrontmatter(content, original, next) {
-    const start = '---\n'.length;
-    return `${content.slice(0, start)}${next}${content.slice(start + original.length)}`;
+/** Whether the opening line, the block text, the line before the close or the closing line ends with CRLF. */
+function hasCrlf(block) {
+    return (block.opening.endsWith('\r\n') ||
+        block.textEnding === '\r\n' ||
+        block.text.includes('\r\n') ||
+        block.closing.endsWith('\r\n'));
+}
+/** The page with the block text replaced and every other byte of it kept. */
+function rebuild(block, text) {
+    return block.opening + text + block.textEnding + block.closing + block.body;
 }
 function readRelated(content) {
     try {

package/dist/wiki-ingest.js

@@ -9,6 +9,8 @@ import { assertBranchWritable } from "./branch-safety.js";
 import { verifyCorrectionSurvival } from "./corrections-survival.js";
 import { CorrectionStoreError, readCorrections } from "./corrections.js";
 import { bootstrapDataBranch as defaultBootstrapDataBranch, } from "./data-branch-bootstrap.js";
+import { splitFrontmatterBlock } from "./frontmatter-block.js";
+import { parseFrontmatterDocument } from "./frontmatter.js";
 import { findIndexEntryLines } from "./line-scanners.js";
 import { assertReposFile } from "./schemas.js";
 import { computeRepoSlug } from "./wiki-slug.js";
@@ -661,23 +663,16 @@ export function appendLogEntry(existingLog, params) {
     return normalizeText(`${base}\n## [${stamp}] ${logOperation} | ${params.target}\n\n${params.summary}\n\n${sources}\n`);
 }
 function parseFrontmatter(path, content) {
-    const match = /^---\n([\s\S]+?)\n---\n?/u.exec(content);
-    if (match === null) {
+    const split = splitFrontmatterBlock(content);
+    if (split.kind !== 'block') {
         throw new WikiIngestError({
             code: 'INVALID_FRONTMATTER',
             message: `${path} is missing YAML frontmatter`,
             remediation: 'Add frontmatter with type, title, created, and updated fields before ingesting the page.',
         });
     }
-    const frontmatterText = match[1];
-    if (frontmatterText === undefined) {
-        throw new WikiIngestError({
-            code: 'INVALID_FRONTMATTER',
-            message: `${path} frontmatter could not be extracted`,
-            remediation: 'Ensure the page begins with a valid YAML frontmatter block.',
-        });
-    }
-    const parsed = parse(frontmatterText);
+    // Only a block with no lines is an empty mapping. A block of one blank line parses to null, like any blank text.
+    const parsed = split.text === '' && split.textEnding === '' ? {} : parse(split.text);
     if (!isRecord(parsed)) {
         throw new WikiIngestError({
             code: 'INVALID_FRONTMATTER',
@@ -715,6 +710,7 @@ function prepareWikiPage(page, existingFiles, params, deletedPaths, migrations)
     const targetSlug = repoTargetSlug(params.target);
     const trackedNodeId = params.trackedRepoNodeIds?.get(pageSlug);
     const isTargetPage = targetSlug === pageSlug;
+    const stamp = isTargetPage ? buildTargetStamp(params, existingFiles[page.path]) : undefined;
     const identity = resolvePageIdentity({
         trackedNodeId,
         targetNodeId: isTargetPage ? params.targetNodeId : undefined,
@@ -727,7 +723,7 @@ function prepareWikiPage(page, existingFiles, params, deletedPaths, migrations)
             : undefined;
         return {
             path: page.path,
-            content: updateRepoPageFrontmatter(page.content, preserveNodeId),
+            content: updateRepoPageFrontmatter(page.content, preserveNodeId, stamp),
         };
     }
     const nodeMatch = identity.trusted ? findRepoPageByNodeId(existingFiles, identity.nodeId) : undefined;
@@ -747,12 +743,13 @@ function prepareWikiPage(page, existingFiles, params, deletedPaths, migrations)
                 nodeId: identity.nodeId,
                 title: repoTargetTitle(params.target) ?? incomingFrontmatter.title,
                 aliases: [nodeMatch.slug],
+                stamp,
             }),
         };
     }
     return {
         path: page.path,
-        content: updateRepoPageFrontmatter(page.content, identity.nodeId),
+        content: updateRepoPageFrontmatter(page.content, identity.nodeId, stamp),
     };
 }
 function resolvePageIdentity(params) {
@@ -812,17 +809,98 @@ function mergeRepoPageContent(incomingContent, historicalContents, changes) {
             body = body === '' ? historicalBody : `${body}\n\n${historicalBody}`;
         }
     }
+    // The ingest matched the old page to the target by a trusted node ID, so the merged page is the target's.
+    if (changes.stamp !== undefined)
+        addTargetSource(values, changes.stamp);
     return renderFrontmatterDocument(values, body);
 }
-function updateRepoPageFrontmatter(content, nodeId) {
+function updateRepoPageFrontmatter(content, nodeId, stamp) {
     const document = parseFrontmatterDocument(content);
     if (nodeId === undefined)
         delete document.values.node_id;
     else
         document.values.node_id = nodeId;
     delete document.values.database_id;
+    if (stamp !== undefined)
+        stampEmptySources(document.values, stamp);
     return renderFrontmatterDocument(document.values, document.body);
 }
+function buildTargetStamp(params, existingContent) {
+    const parts = repoTargetParts(params.target);
+    // Only a target whose owner and name are plain GitHub names is listed on its page. Anything else is written
+    // without a stamp, as before, and never makes the ingest throw.
+    if (parts === undefined || !isPlainGitHubName(parts.owner) || !isPlainGitHubName(parts.name))
+        return undefined;
+    return {
+        owner: parts.owner,
+        name: parts.name,
+        url: `https://github.com/${parts.owner}/${parts.name}`,
+        accessed: params.timestamp.toISOString().slice(0, 10),
+        existingContent,
+    };
+}
+/** A GitHub owner or repository name: ASCII letters, digits, `.`, `_` and `-`, and not `.` or `..`. */
+function isPlainGitHubName(value) {
+    return value !== '.' && value !== '..' && /^[\w.-]+$/u.test(value);
+}
+/**
+ * Lists the target on its own page when the page lists no sources: no `sources` key, or an empty list. A page that
+ * lists any source is never changed, and neither is a `sources` value that is not a list. When the page on the
+ * branch already lists the target, the whole `sources` list it has is carried over as it is, dates and other
+ * entries included, so a repeat write changes nothing. Otherwise the page gets the one new entry.
+ */
+function stampEmptySources(values, stamp) {
+    const sources = values.sources;
+    if (sources !== undefined && !Array.isArray(sources))
+        return;
+    if (sources !== undefined && sources.length > 0)
+        return;
+    values.sources = findExistingSourcesWithTarget(stamp) ?? [{ url: stamp.url, accessed: stamp.accessed }];
+}
+/** Adds the target to a migrated page's sources when no entry matches it, keeping every other entry. */
+function addTargetSource(values, stamp) {
+    const sources = values.sources;
+    if (sources !== undefined && !Array.isArray(sources))
+        return;
+    const listed = sources ?? [];
+    if (listed.some(entry => sourceMatchesTarget(entry, stamp)))
+        return;
+    values.sources = [...listed, { url: stamp.url, accessed: stamp.accessed }];
+}
+/** The `sources` list of the page on the branch, when it has an entry for the target. */
+function findExistingSourcesWithTarget(stamp) {
+    if (stamp.existingContent === undefined)
+        return undefined;
+    try {
+        const sources = parseFrontmatterDocument(stamp.existingContent).values.sources;
+        return Array.isArray(sources) && sources.some(entry => sourceMatchesTarget(entry, stamp)) ? sources : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sourceMatchesTarget(entry, stamp) {
+    return isRecord(entry) && typeof entry.url === 'string' && sourceUrlMatchesRepo(entry.url, stamp.owner, stamp.name);
+}
+/**
+ * Whether `sourceUrl` refers to the repository `owner`/`name` on github.com by the rule the privacy gate applies to
+ * a page's sources (`sourceUrlMatchesRepo` in `check-wiki-private-presence.ts`): `https`, host `github.com`, no
+ * port, owner and name equal without case, and any path after them. This package cannot import the gate, so the
+ * rule is copied and a test pins the copy against the gate's own cases.
+ */
+function sourceUrlMatchesRepo(sourceUrl, owner, name) {
+    let parsed;
+    try {
+        parsed = new URL(sourceUrl);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'https:' || parsed.hostname !== 'github.com' || parsed.port !== '')
+        return false;
+    const segments = parsed.pathname.split('/').filter(segment => segment.length > 0);
+    return segments[0]?.toLowerCase() === owner.toLowerCase() && segments[1]?.toLowerCase() === name.toLowerCase();
+}
 function getExistingRepoNodeId(content, path) {
     if (content === undefined)
         return undefined;
@@ -859,16 +937,6 @@ function mergeFrontmatterArray(records, key) {
     }
     return values;
 }
-function parseFrontmatterDocument(content) {
-    const match = /^---\n([\s\S]+?)\n---\n?/u.exec(content);
-    if (match === null || match[1] === undefined) {
-        throw new Error('validated wiki page is missing frontmatter');
-    }
-    const parsed = parse(match[1]);
-    if (!isRecord(parsed))
-        throw new Error('validated wiki page frontmatter is not an object');
-    return { values: parsed, body: content.slice(match[0].length) };
-}
 function isRepoPagePath(path) {
     return path.startsWith(`${WIKI_ROOT}/repos/`) && path.endsWith('.md');
 }

package/dist/wiki-utils.d.ts

@@ -1,6 +1,13 @@
 /** Canonical root directory for wiki page content. Shared by every wiki script. */
 export declare const WIKI_ROOT = "knowledge/wiki";
 export type WikiPageType = 'repo' | 'topic' | 'entity' | 'comparison';
+/**
+ * Why a page's frontmatter could not be read, as a closed vocabulary a caller can switch on without matching the
+ * wording of the error text. `unclosed` is a block that opens with `---` and never closes; `invalid` is a block the
+ * YAML parser rejects. A block that parses to something other than a mapping is read as empty frontmatter and is
+ * not an error, so it has no kind.
+ */
+export type WikiFrontmatterErrorKind = 'unclosed' | 'invalid';
 export interface WikiPage {
     readonly path: string;
     readonly slug: string;
@@ -11,17 +18,21 @@ export interface WikiPage {
     readonly body: string;
     readonly frontmatter: Record<string, unknown>;
     readonly frontmatterError?: string;
+    /** Set exactly when `frontmatterError` is. */
+    readonly frontmatterErrorKind?: WikiFrontmatterErrorKind;
 }
 export interface SplitFrontmatterResult {
     readonly frontmatter: Record<string, unknown>;
     readonly body: string;
     readonly error?: string;
+    /** Set exactly when `error` is. */
+    readonly errorKind?: WikiFrontmatterErrorKind;
 }
 /**
  * Split raw wiki page content into frontmatter and body.
  *
- * Stricter than a naive split: malformed YAML frontmatter is surfaced via `error`
- * rather than silently discarded, so downstream safety/lint logic can observe it.
+ * Stricter than a naive split: malformed YAML frontmatter, and a block that is opened and never closed, are
+ * surfaced via `error` rather than silently discarded, so downstream safety/lint logic can observe them.
  */
 export declare function splitFrontmatter(content: string): SplitFrontmatterResult;
 /** Collect `[[target]]` and `[[target|label]]` wikilink targets from page body content. */

package/dist/wiki-utils.js

@@ -2,38 +2,44 @@ import { Buffer } from 'node:buffer';
 import { basename } from 'node:path';
 import { parse } from 'yaml';
 import { findCodeRegions, findRegionAt } from "./code-regions.js";
+import { splitFrontmatterBlock } from "./frontmatter-block.js";
 /** Canonical root directory for wiki page content. Shared by every wiki script. */
 export const WIKI_ROOT = 'knowledge/wiki';
 /**
  * Split raw wiki page content into frontmatter and body.
  *
- * Stricter than a naive split: malformed YAML frontmatter is surfaced via `error`
- * rather than silently discarded, so downstream safety/lint logic can observe it.
+ * Stricter than a naive split: malformed YAML frontmatter, and a block that is opened and never closed, are
+ * surfaced via `error` rather than silently discarded, so downstream safety/lint logic can observe them.
  */
 export function splitFrontmatter(content) {
-    const match = /^---\n([\s\S]+?)\n---\n?/u.exec(content);
-    if (match === null) {
+    const split = splitFrontmatterBlock(content);
+    if (split.kind === 'none') {
         return { frontmatter: {}, body: content.trim() };
     }
-    const frontmatterText = match[1];
-    if (frontmatterText === undefined) {
-        return { frontmatter: {}, body: content.trim() };
+    if (split.kind === 'malformed') {
+        return {
+            frontmatter: {},
+            body: content.trim(),
+            error: 'Invalid frontmatter: missing closing --- delimiter',
+            errorKind: 'unclosed',
+        };
     }
     let parsed;
     try {
-        parsed = parse(frontmatterText);
+        parsed = parse(split.text);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : 'Unknown YAML parse error';
         return {
             frontmatter: {},
-            body: content.slice(match[0].length).trim(),
+            body: split.body.trim(),
             error: `Invalid YAML frontmatter: ${message}`,
+            errorKind: 'invalid',
         };
     }
     return {
         frontmatter: isRecord(parsed) ? parsed : {},
-        body: content.slice(match[0].length).trim(),
+        body: split.body.trim(),
     };
 }
 /**
@@ -100,7 +106,7 @@ export function findWikilinkSpans(content) {
 }
 /** Parse a single wiki page's content (relative path + raw content) into a page record. */
 export function parseWikiPage(path, content) {
-    const { frontmatter, body, error } = splitFrontmatter(content);
+    const { frontmatter, body, error, errorKind } = splitFrontmatter(content);
     const slug = basename(path, '.md');
     return {
         path,
@@ -114,6 +120,7 @@ export function parseWikiPage(path, content) {
         body,
         frontmatter,
         frontmatterError: error,
+        frontmatterErrorKind: errorKind,
     };
 }
 /** Collect all `knowledge/wiki/**.md` pages from a path→content file map. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/wiki-write-core",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Shared validation and commit primitives for Fro Bot wiki writes",
   "homepage": "https://github.com/fro-bot/.github/tree/main/packages/wiki-write-core#readme",
   "bugs": {