@fro.bot/wiki-write-core 0.1.0 → 0.1.2

package/README.md

@@ -38,3 +38,45 @@ The package exports `GATE_CONTRACT_VERSION` and `GATE_SOURCE_TREE_HASH` from its
 ## Finding kinds
 
 `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.
+
+## 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.
+
+Only commits that touch `packages/wiki-write-core/` are analyzed. The commit type decides the release:
+
+| Commit                                                                                          | Release |
+| ----------------------------------------------------------------------------------------------- | ------- |
+| Breaking change (`!` or a `BREAKING CHANGE:` footer)                                            | minor   |
+| `feat`                                                                                          | minor   |
+| `fix`, `build`, `docs(readme)`                                                                  | patch   |
+| `build(dev)`, other `docs`, `chore`, `ci`, `test`, `refactor`, `skip`, non-conventional commits | none    |
+
+- 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.
+
+### 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.
+
+Verify a release:
+
+- `npm view @fro.bot/wiki-write-core dist-tags.latest` returns the released version.
+- `npm view @fro.bot/wiki-write-core@<version> --json` lists the provenance attestation under `dist.attestations`.
+- The version page on npmjs.com shows the provenance badge, linking to `fro-bot/.github` and `release-wiki-write-core.yaml`.
+
+### Failure recovery
+
+Start from the registry and tag state, not from the run's conclusion: a green run can release nothing.
+
+| State | Recovery |
+| --- | --- |
+| No tag, no npm version | Fix the cause, then run the workflow with `workflow_dispatch` on `main` |
+| Green run, package commits since the last tag, no release (`main` moved past the checkout, or the push run was skipped by `[skip ci]`) | `workflow_dispatch` on `main` |
+| Tag present, version neither live nor staged on npm | Delete the tag and its GitHub release if one exists, then `workflow_dispatch` on `main`. Do this before merging any other package change |
+| Tag and GitHub release present, npm skipped the publish (for example `private` in the manifest) | Fix the manifest, delete the tag and GitHub release, then `workflow_dispatch` on `main` |
+| Version staged on npm instead of live | Promote it on npm, then set the trusted publisher to allow `npm publish` |
+| OIDC publish fails (expired, misconfigured or stage-only trusted publisher) | Delete and recreate the trusted publisher: owner `fro-bot`, repo `.github`, workflow `release-wiki-write-core.yaml`, environment `release`, allowed action `npm publish`. Then resolve the tag as in the third row |
+| Tag and version live, no GitHub release | Create the GitHub release from the tag. Never delete the tag |
+| Bad version published | Deprecate it and ship a fix release. Never delete the tag |

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 = '9d17212cc85afbc7cb228fdce2cb436caa29ec2b0ba7c2f3e06b0db0de3b16be';
+export const GATE_SOURCE_TREE_HASH = '28283aa25287ac6172f333c8114de4879c0c14b3c6521908bb0607bb7e55ec6e';

package/dist/gate-contract.json

@@ -1 +1 @@
-{"version":1,"sourceTreeHash":"9d17212cc85afbc7cb228fdce2cb436caa29ec2b0ba7c2f3e06b0db0de3b16be"}
+{"version":1,"sourceTreeHash":"28283aa25287ac6172f333c8114de4879c0c14b3c6521908bb0607bb7e55ec6e"}

package/dist/wiki-ingest.d.ts

@@ -55,11 +55,21 @@ export interface CommitWikiChangesParams {
     message: string;
     files: Record<string, string>;
     deletedPaths?: readonly string[];
+    /**
+     * The data-branch commit `files` and `deletedPaths` were derived from: the base of the write guard.
+     * Every attempt, the first included, compares each write-set path on the head it reads with the same
+     * path in this commit's tree and fails closed if any differs.
+     * - A commit SHA: that commit's tree is the base. It is resolved once and never re-read, so the base
+     *   stays fixed across retries.
+     * - Omitted: the head tree of the first successful read in this call is the base, so only changes
+     *   after that read are caught.
+     */
+    baseCommitSha?: string;
     octokit?: OctokitClient;
     maxRetries?: number;
     /**
      * Idempotent data-branch bootstrap. Called before data-branch writes so wiki
-     * ingest recovers when GitHub deletes the `data` source ref after promotion.
+     * ingest recovers when the `data` branch is missing: it recreates the branch from `main`.
      */
     bootstrapDataBranch?: (params: DataBranchBootstrapParams) => Promise<DataBranchBootstrapResult>;
 }
@@ -91,6 +101,15 @@ export declare class WikiIngestError extends Error {
     });
 }
 export declare function buildWikiIngestChanges(params: BuildWikiIngestChangesParams): BuildWikiIngestChangesResult;
+/**
+ * Commits `params.files` (and removes `params.deletedPaths`) as one commit on the data branch.
+ *
+ * Every attempt is guarded: if any path in the write set (files and deletions) differs on the head read
+ * in that attempt from the tree the files were derived from (`baseCommitSha`, or the first head read
+ * when it is omitted), another writer changed it, so the write fails with `CONFLICT_EXHAUSTED` and
+ * nothing is written. A ref race (`updateRef` 409, or 422 not-a-fast-forward) re-reads the head and
+ * replays the same files on it, up to `maxRetries` attempts, under the same guard.
+ */
 export declare function commitWikiChanges(params: CommitWikiChangesParams): Promise<CommitWikiChangesResult>;
 export declare function validateWikilinks(files: Record<string, string>): void;
 /**

package/dist/wiki-ingest.js

@@ -121,6 +121,15 @@ function collectWikiFrontmatter(files) {
     }
     return frontmatter;
 }
+/**
+ * Commits `params.files` (and removes `params.deletedPaths`) as one commit on the data branch.
+ *
+ * Every attempt is guarded: if any path in the write set (files and deletions) differs on the head read
+ * in that attempt from the tree the files were derived from (`baseCommitSha`, or the first head read
+ * when it is omitted), another writer changed it, so the write fails with `CONFLICT_EXHAUSTED` and
+ * nothing is written. A ref race (`updateRef` 409, or 422 not-a-fast-forward) re-reads the head and
+ * replays the same files on it, up to `maxRetries` attempts, under the same guard.
+ */
 export async function commitWikiChanges(params) {
     const owner = params.owner ?? DEFAULT_OWNER;
     const repo = params.repo ?? DEFAULT_REPO;
@@ -143,11 +152,30 @@ export async function commitWikiChanges(params) {
     if (shouldBootstrapDataBranch) {
         await bootstrapDataBranch();
     }
+    // The tree the write set was derived from, once resolved (see `CommitWikiChangesParams.baseCommitSha`).
+    let baseTreeSha;
     for (let attempt = 1; attempt <= maxRetries; attempt += 1) {
+        // Only an `updateRef` 422 is a ref race ("not a fast forward": the branch moved after this attempt
+        // read its tip). A 422 from createBlob, createTree or createCommit is a bad request and stays terminal.
+        let updatingRef = false;
         try {
             await assertWritableWikiBranch(octokit, owner, repo, branch);
             const head = await octokit.rest.git.getRef({ owner, repo, ref: `heads/${branch}` });
             const commit = await octokit.rest.git.getCommit({ owner, repo, commit_sha: head.data.object.sha });
+            // Resolved on the first attempt and reused: the base must not move while the write retries.
+            baseTreeSha ??=
+                params.baseCommitSha === undefined
+                    ? commit.data.tree.sha
+                    : await readCommitTreeSha(octokit, owner, repo, params.baseCommitSha);
+            const guardBaseTreeSha = baseTreeSha;
+            if (commit.data.tree.sha !== guardBaseTreeSha) {
+                await assertWriteSetUnchanged(octokit, owner, repo, {
+                    baseTreeSha: guardBaseTreeSha,
+                    headTreeSha: commit.data.tree.sha,
+                    paths: [...Object.keys(params.files), ...(params.deletedPaths ?? [])],
+                    location: `${owner}/${repo}@${branch}`,
+                });
+            }
             const tree = [];
             for (const [path, content] of Object.entries(params.files)) {
                 const blob = await octokit.rest.git.createBlob({ owner, repo, content, encoding: 'utf-8' });
@@ -175,6 +203,7 @@ export async function commitWikiChanges(params) {
                 tree: createdTree.data.sha,
                 parents: [commit.data.sha],
             });
+            updatingRef = true;
             await octokit.rest.git.updateRef({
                 owner,
                 repo,
@@ -189,11 +218,12 @@ export async function commitWikiChanges(params) {
                 await bootstrapDataBranch();
                 continue;
             }
-            if (isConflictError(error) && attempt < maxRetries) {
+            const refRace = isConflictError(error) || (updatingRef && isApiErrorStatus(error, 422));
+            if (refRace && attempt < maxRetries) {
                 await delayConflictRetry(attempt);
                 continue;
             }
-            if (isConflictError(error)) {
+            if (refRace) {
                 throw new WikiIngestError({
                     code: 'CONFLICT_EXHAUSTED',
                     message: `wiki ingest exhausted ${maxRetries} attempt(s) updating ${owner}/${repo}@${branch}`,
@@ -234,6 +264,47 @@ async function getPresentPathsInTree(octokit, owner, repo, treeSha) {
         return new Set();
     return new Set(tree.flatMap(entry => (isRecord(entry) && typeof entry.path === 'string' ? [entry.path] : [])));
 }
+async function readCommitTreeSha(octokit, owner, repo, sha) {
+    const commit = await octokit.rest.git.getCommit({ owner, repo, commit_sha: sha });
+    return commit.data.tree.sha;
+}
+/**
+ * Fail closed unless every path in the write set has the same tree entry (sha, mode, type; absence
+ * counts) on the new head as in the tree the files were derived from. A replay onto a head where
+ * another writer touched one of them would silently overwrite that writer's change.
+ */
+async function assertWriteSetUnchanged(octokit, owner, repo, params) {
+    const refuse = (reason) => {
+        throw new WikiIngestError({
+            code: 'CONFLICT_EXHAUSTED',
+            message: `wiki ingest did not replay onto ${params.location}: ${reason}`,
+            remediation: 'Another writer updated the data branch concurrently. Retry the workflow so it rebuilds on the new head.',
+        });
+    };
+    const base = await readTreeEntries(octokit, owner, repo, params.baseTreeSha);
+    const head = await readTreeEntries(octokit, owner, repo, params.headTreeSha);
+    if (base === undefined || head === undefined)
+        return refuse('a tree read was truncated, so the write set cannot be verified');
+    if (params.paths.some(path => base.get(path) !== head.get(path))) {
+        return refuse('another writer changed a path in the write set');
+    }
+}
+/** Path to `mode type sha`, for every non-directory entry. `undefined` when the read is truncated. */
+async function readTreeEntries(octokit, owner, repo, treeSha) {
+    const response = await octokit.rest.git.getTree({ owner, repo, tree_sha: treeSha, recursive: 'true' });
+    if (response.data.truncated === true)
+        return undefined;
+    const tree = response.data.tree;
+    const entries = new Map();
+    if (!Array.isArray(tree))
+        return entries;
+    for (const entry of tree) {
+        if (!isRecord(entry) || typeof entry.path !== 'string' || entry.type === 'tree')
+            continue;
+        entries.set(entry.path, `${String(entry.mode)} ${String(entry.type)} ${String(entry.sha)}`);
+    }
+    return entries;
+}
 async function createOctokitFromEnv() {
     const token = process.env.GITHUB_TOKEN;
     if (token === undefined || token === '') {
@@ -794,8 +865,15 @@ function formatTimestamp(value) {
     const minute = `${value.getUTCMinutes()}`.padStart(2, '0');
     return `${year}-${month}-${day} ${hour}:${minute}`;
 }
+/**
+ * Read the existing wiki files from the working tree, and report the data-branch commit they were
+ * synced from: `WIKI_INGEST_DATA_TIP_SHA`, when the workflow exports the tip it synced `knowledge/` from.
+ * Without it there is no recorded base and the commit guards from its own first read.
+ */
 async function loadExistingWikiFiles() {
     const files = {};
+    const recordedTip = process.env.WIKI_INGEST_DATA_TIP_SHA;
+    const baseCommitSha = recordedTip === undefined || recordedTip === '' ? undefined : recordedTip;
     for (const path of [INDEX_PATH, LOG_PATH]) {
         try {
             files[path] = await readFile(path, 'utf8');
@@ -836,7 +914,7 @@ async function loadExistingWikiFiles() {
             }
         }
     }
-    return files;
+    return { files, baseCommitSha };
 }
 async function loadWorkingTreeWikiFiles(paths) {
     const files = {};
@@ -958,7 +1036,7 @@ export async function runWikiIngestCli(dependencies = {}) {
     const readCorrectionsImpl = dependencies.readCorrections ?? readCorrections;
     const commitWikiChangesImpl = dependencies.commitWikiChanges ?? commitWikiChanges;
     const getChangedWikiPathsImpl = dependencies.getChangedWikiPaths ?? getChangedWikiPaths;
-    const existingFiles = await loadExistingWikiFiles();
+    const { files: existingFiles, baseCommitSha } = await loadExistingWikiFiles();
     let correctionRead;
     try {
         correctionRead = await readCorrectionsImpl();
@@ -1063,6 +1141,7 @@ export async function runWikiIngestCli(dependencies = {}) {
         message,
         files: built.files,
         deletedPaths: built.deletedPaths,
+        ...(baseCommitSha === undefined ? {} : { baseCommitSha }),
     });
     const pagesChanged = countWikiPages(committedPagePaths);
     await emitPagesChanged(pagesChanged);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/wiki-write-core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {