@horizon36596/zenith-github 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Horizon (FTC 36596)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,18 @@
+Zenith
+Copyright (c) 2026 Horizon (FTC 36596)
+
+Zenith is licensed under the MIT License; see LICENSE.
+
+Third-party assets
+
+- BIOBUZZ field images (apps/web/public/fields/biobuzz/*.webp) by Team Juice 16236, from the r/FTC
+  post "BIOBUZZ custom field images (MeepMeep compatible)". Used with the credit the author asks for.
+
+Bundled fonts
+
+The following fonts are bundled in apps/web/public/fonts/. Each is licensed under the SIL Open Font
+License, Version 1.1. The full licence text ships next to each font file.
+
+- Jost, licensed under the SIL Open Font License 1.1 (jost-OFL.txt).
+- IBM Plex Sans, licensed under the SIL Open Font License 1.1 (ibm-plex-sans-OFL.txt).
+- JetBrains Mono, licensed under the SIL Open Font License 1.1 (jetbrains-mono-OFL.txt).

package/README.md

@@ -0,0 +1,108 @@
+# @horizon36596/zenith-github
+
+GitHub collaboration for [Zenith](https://libraries.horizon36596.org/zenith/), the FTC autonomous
+planner by Horizon (FTC 36596): propose an auto as a pull request, and load a review link, from the
+browser or Node.
+
+```
+npm install @horizon36596/zenith-github
+```
+
+Documentation: https://libraries.horizon36596.org/zenith/. Licence: MIT.
+
+## Package reference
+
+An isomorphic (browser + Node) GitHub client, built on `fetch` with no Octokit and no Node-only
+APIs. It is the only package that talks to `api.github.com`; `apps/web` and `packages/cli` both
+build on it. The user-facing side is the docs site's GitHub page
+(https://libraries.horizon36596.org/zenith/github/).
+
+### Creating a token
+
+Zenith v1 signs in with a pasted **fine-grained personal access token**.
+There is no OAuth App and no device flow yet.
+
+1. On github.com: **Settings -> Developer settings -> Personal access tokens -> Fine-grained
+   tokens -> Generate new token**.
+2. **Resource owner**: the account or organisation that owns the robot repository.
+3. **Repository access**: "Only select repositories", and pick the one robot repository the token
+   is for (e.g. `example-team/robot`). Do not grant access to every repository the account can
+   see; Zenith only ever needs the one.
+4. **Permissions** (under "Repository permissions"):
+   - **Contents**: Read and write — reads `zenith.json` and the robot/field/waypoints/auto files,
+     writes commits to work branches.
+   - **Pull requests**: Read and write — opens and updates the PR `propose` creates, and reads PR
+     metadata and changed files for review mode.
+   - Everything else can stay "No access".
+5. Set an expiry (GitHub's fine-grained tokens require one) and generate. Paste the token into
+   Zenith's sign-in screen when it asks.
+
+A fine-grained token scoped this way cannot read or write any other repository, cannot see issues,
+actions, settings or anything else in the one repository it can reach, and expires on its own.
+
+### How the token is stored
+
+- The token is held in memory for the life of the tab or process. It is never written to disk by
+  this package.
+- In the browser, `BrowserTokenStore` can also mirror it to `sessionStorage` (the default) so a
+  page reload does not force a re-paste; that mirror is cleared when the tab closes. It is never
+  written to `localStorage`, which would outlive the browser session.
+- In Node (the CLI), `NodeTokenStore` is a no-op: nothing persists between runs, and it is the
+  caller's job (an environment variable, a local file the user manages themselves, an interactive
+  prompt) to hand the token to `PatAuth` each time.
+- `GitHubClient` sends the token as an `Authorization: Bearer` header to `apiBase` only (default
+  `https://api.github.com`). It is never logged, never included in error messages beyond GitHub's
+  own response text, and never sent to any other host.
+
+### Safety guarantees
+
+These are enforced in code,
+not just by convention:
+
+- **The base branch is never written to.** `GitHubProject.save` throws `BaseBranchWriteError`
+  before making any network call if the target branch equals the project's base branch.
+- **No force-pushes.** The client has no method that force-updates an existing ref; branches are
+  only ever created fresh (`branches.create`, from the base branch's current sha) or advanced by
+  ordinary commits (`contents.put`).
+- **Path allowlist.** `GitHubProject.save` refuses (`PathNotAllowedError`) any path that is not
+  under `zenith.json`'s `autosDir`, `deploy.dir` or `codegen.dir` (which is where
+  `autosDir/.renders/` already lives). This is checked locally before any request is sent.
+- **Tokens go to `api.github.com` only.** See the storage section above.
+- **Merge conflicts are surfaced, not hidden.** `repos.merge` throws a typed `MergeConflictError`
+  naming the files involved when the work branch cannot be brought up to date with the base branch
+  cleanly, instead of leaving a half-merged branch behind.
+
+### Where the device flow plugs in later
+
+Everything in this package that needs a token depends only on the `AuthProvider` interface:
+
+```ts
+interface AuthProvider {
+  token(): Promise<string>;
+}
+```
+
+`PatAuth` is the only implementation today: it wraps a pasted token and always returns it. A later
+device-flow implementation (show a code, poll `github.com` for the token, store it with the same `TokenStore`) is a second class implementing the
+same interface; `GitHubClient`, `GitHubProject`, `propose` and `loadReview` take an `AuthProvider`
+and never construct one, so none of them change when it arrives. Swapping sign-in methods is then a
+matter of which `AuthProvider` the app hands to `GitHubClient`, not a rewrite of this package.
+
+### Exported API
+
+See `src/index.ts` for the full surface. In short:
+
+- **Auth**: `AuthProvider`, `PatAuth`, `validateToken`, `TokenStore` (`MemoryTokenStore`,
+  `BrowserTokenStore`, `NodeTokenStore`).
+- **Client**: `GitHubClient` — `repos`, `branches`, `contents`, `git`, `pulls`, `users`.
+- **Project**: `GitHubProject` — `open`, `workBranch`, `save`; `isPathAllowed` /
+  `assertPathAllowed`.
+- **Propose**: `propose`, `RENDER_URL_PLACEHOLDER`.
+- **Review**: `loadReview`, `lineAnchor`, `diffFileHash`, `diffAnchor`.
+- **Errors**: `AuthError`, `NotFoundError`, `ConflictError`, `RateLimitError`,
+  `MergeConflictError`, `PathNotAllowedError`, `BaseBranchWriteError`, `GitHubError`.
+
+### Testing
+
+`pnpm exec vitest run --project github` (or `pnpm test` for the whole workspace). Every test uses
+the hand-rolled `fetch` stub in `test/fetchStub.ts`; nothing here touches the network.

package/dist/allowlist.d.ts

@@ -0,0 +1,14 @@
+import type { Link } from "@horizon36596/zenith-schema";
+/**
+ * The write allowlist of site/docs/github.md: only `autosDir`,
+ * `deploy.dir` and `codegen.dir` from `zenith.json` (and, redundantly but explicitly per the
+ * spec, `autosDir/.renders/`, which is already inside `autosDir`).
+ */
+export declare function isPathAllowed(link: Link, path: string): boolean;
+/** Throws `PathNotAllowedError` unless `isPathAllowed` is true. */
+export declare function assertPathAllowed(link: Link, path: string): void;
+/** `autosDir/.renders/<name>.svg`, the fixed location `propose` commits the render SVG to. */
+export declare function renderPath(link: Link, autoName: string): string;
+/** `autosDir/<name>.auto.json`, the fixed location an auto file lives at. */
+export declare function autoPath(link: Link, autoName: string): string;
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../src/allowlist.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAaxD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ/D;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED,8FAA8F;AAC9F,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/allowlist.js

@@ -0,0 +1,42 @@
+import { PathNotAllowedError } from "./errors.js";
+/** Strips a leading `./`, converts `\` to `/`, and drops a leading `/`. */
+function normalize(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+function withinDir(path, dir) {
+    const normalizedDir = normalize(dir).replace(/\/+$/, "");
+    return path === normalizedDir || path.startsWith(`${normalizedDir}/`);
+}
+/**
+ * The write allowlist of site/docs/github.md: only `autosDir`,
+ * `deploy.dir` and `codegen.dir` from `zenith.json` (and, redundantly but explicitly per the
+ * spec, `autosDir/.renders/`, which is already inside `autosDir`).
+ */
+export function isPathAllowed(link, path) {
+    const normalized = normalize(path);
+    if (normalized.length === 0)
+        return false;
+    if (normalized.split("/").includes(".."))
+        return false;
+    if (withinDir(normalized, link.autosDir))
+        return true;
+    if (link.deploy && withinDir(normalized, link.deploy.dir))
+        return true;
+    if (link.codegen && withinDir(normalized, link.codegen.dir))
+        return true;
+    return false;
+}
+/** Throws `PathNotAllowedError` unless `isPathAllowed` is true. */
+export function assertPathAllowed(link, path) {
+    if (!isPathAllowed(link, path))
+        throw new PathNotAllowedError(path);
+}
+/** `autosDir/.renders/<name>.svg`, the fixed location `propose` commits the render SVG to. */
+export function renderPath(link, autoName) {
+    return `${normalize(link.autosDir).replace(/\/+$/, "")}/.renders/${autoName}.svg`;
+}
+/** `autosDir/<name>.auto.json`, the fixed location an auto file lives at. */
+export function autoPath(link, autoName) {
+    return `${normalize(link.autosDir).replace(/\/+$/, "")}/${autoName}.auto.json`;
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../src/allowlist.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,2EAA2E;AAC3E,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,GAAW;IAC1C,MAAM,aAAa,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,aAAa,GAAG,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,IAAY;IACpD,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvD,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,IAAI,CAAC,OAAO,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAC,IAAU,EAAE,IAAY;IACxD,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,UAAU,CAAC,IAAU,EAAE,QAAgB;IACrD,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,QAAQ,MAAM,CAAC;AACpF,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,QAAQ,CAAC,IAAU,EAAE,QAAgB;IACnD,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,QAAQ,YAAY,CAAC;AACjF,CAAC"}

package/dist/auth.d.ts

@@ -0,0 +1,69 @@
+/**
+ * How the client gets a bearer token for `api.github.com`. v1 ships one implementation
+ * (`PatAuth`, a pasted fine-grained PAT, site/docs/github.md); this seam is
+ * what lets a later device-flow implementation plug in without touching `GitHubClient`,
+ * `GitHubProject`, `propose` or `loadReview`.
+ */
+export interface AuthProvider {
+    /** Resolves to a bearer token, or rejects (typically with `AuthError`) when none is available. */
+    token(): Promise<string>;
+}
+/** v1's only `AuthProvider`: a fine-grained personal access token pasted into the app or the CLI. */
+export declare class PatAuth implements AuthProvider {
+    #private;
+    constructor(pat: string);
+    token(): Promise<string>;
+}
+/** What `validateToken` reports back about the token it was given. */
+export interface TokenInfo {
+    login: string;
+    /**
+     * Scopes from the `x-oauth-scopes` response header. GitHub sets this header for classic PATs and
+     * OAuth Apps; a fine-grained PAT authenticates fine but does not echo its permissions here, so
+     * this is `[]` for one, not a sign that the token has no access.
+     */
+    scopes: string[];
+}
+/**
+ * Confirms the token works and reports who it belongs to, the way the app's sign-in screen and
+ * `zenith propose`'s preflight both want (06 §2). Throws `AuthError` on 401/403.
+ */
+export declare function validateToken(auth: AuthProvider, apiBase?: string, fetchImpl?: typeof fetch): Promise<TokenInfo>;
+/** Loads, saves and clears the pasted token. Never `localStorage` (00-decisions.md GitHub mode). */
+export interface TokenStore {
+    load(): string | null;
+    save(token: string): void;
+    clear(): void;
+}
+/** Works anywhere; the token disappears when the page or process does. */
+export declare class MemoryTokenStore implements TokenStore {
+    private token;
+    load(): string | null;
+    save(token: string): void;
+    clear(): void;
+}
+/**
+ * The browser store. Memory is the source of truth; when `persist` is on and `sessionStorage` is
+ * reachable, the token is mirrored there too, so a page reload does not force a re-paste. Falls
+ * back to memory-only, quietly, if storage throws (private browsing, a locked-down iframe).
+ * Deliberately has no `localStorage` mode: the token must not outlive the browser session.
+ */
+export declare class BrowserTokenStore implements TokenStore {
+    private readonly memory;
+    private readonly storage;
+    constructor(options?: {
+        persist?: boolean;
+        storage?: Storage;
+    });
+    private static readonly KEY;
+    load(): string | null;
+    save(token: string): void;
+    clear(): void;
+}
+/** Node (the CLI) has no browser storage; the token lives only where the caller puts it. */
+export declare class NodeTokenStore implements TokenStore {
+    load(): string | null;
+    save(): void;
+    clear(): void;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,kGAAkG;IAClG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED,qGAAqG;AACrG,qBAAa,OAAQ,YAAW,YAAY;;gBAQ9B,GAAG,EAAE,MAAM;IAKjB,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAG/B;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,YAAY,EAClB,OAAO,SAA2B,EAClC,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,SAAS,CAAC,CAyBpB;AAED,oGAAoG;AACpG,MAAM,WAAW,UAAU;IACzB,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,0EAA0E;AAC1E,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,KAAK,CAAuB;IAEpC,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;CAGd;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;gBAE7B,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO;IAclE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAEpD,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IASzB,KAAK,IAAI,IAAI;CAQd;AAED,4FAA4F;AAC5F,qBAAa,cAAe,YAAW,UAAU;IAC/C,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB,IAAI,IAAI,IAAI;IAIZ,KAAK,IAAI,IAAI;CAGd"}

package/dist/auth.js

@@ -0,0 +1,118 @@
+import { AuthError } from "./errors.js";
+/** v1's only `AuthProvider`: a fine-grained personal access token pasted into the app or the CLI. */
+export class PatAuth {
+    // A real JS private field (`#pat`), not a TypeScript `private` constructor parameter: the latter
+    // still compiles to an ordinary own enumerable property, so `JSON.stringify(patAuthInstance)` (or
+    // any code that walks `state.backend`'s object graph down to this) would print the token in the
+    // clear. `#pat` has no enumerable representation at
+    // all — `Object.keys`, `JSON.stringify` and `for...in` all skip it.
+    #pat;
+    constructor(pat) {
+        if (!pat.trim())
+            throw new AuthError("A personal access token is required.");
+        this.#pat = pat;
+    }
+    async token() {
+        return this.#pat;
+    }
+}
+/**
+ * Confirms the token works and reports who it belongs to, the way the app's sign-in screen and
+ * `zenith propose`'s preflight both want (06 §2). Throws `AuthError` on 401/403.
+ */
+export async function validateToken(auth, apiBase = "https://api.github.com", fetchImpl = fetch) {
+    const token = await auth.token();
+    const response = await fetchImpl(`${apiBase}/user`, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new AuthError(`GitHub rejected this token (${response.status}). Paste a fresh fine-grained PAT with repo contents and pull requests read/write.`, response.status);
+    }
+    if (!response.ok) {
+        throw new AuthError(`Could not validate the token: GitHub returned ${response.status}.`, response.status);
+    }
+    const body = (await response.json());
+    const scopesHeader = response.headers.get("x-oauth-scopes") ?? "";
+    const scopes = scopesHeader
+        .split(",")
+        .map((scope) => scope.trim())
+        .filter((scope) => scope.length > 0);
+    return { login: body.login, scopes };
+}
+/** Works anywhere; the token disappears when the page or process does. */
+export class MemoryTokenStore {
+    token = null;
+    load() {
+        return this.token;
+    }
+    save(token) {
+        this.token = token;
+    }
+    clear() {
+        this.token = null;
+    }
+}
+/**
+ * The browser store. Memory is the source of truth; when `persist` is on and `sessionStorage` is
+ * reachable, the token is mirrored there too, so a page reload does not force a re-paste. Falls
+ * back to memory-only, quietly, if storage throws (private browsing, a locked-down iframe).
+ * Deliberately has no `localStorage` mode: the token must not outlive the browser session.
+ */
+export class BrowserTokenStore {
+    memory = new MemoryTokenStore();
+    storage;
+    constructor(options = {}) {
+        const persist = options.persist ?? true;
+        const candidate = options.storage ?? (typeof sessionStorage === "undefined" ? null : sessionStorage);
+        this.storage = persist ? candidate : null;
+        if (this.storage) {
+            try {
+                const stored = this.storage.getItem(BrowserTokenStore.KEY);
+                if (stored)
+                    this.memory.save(stored);
+            }
+            catch {
+                this.storage = null;
+            }
+        }
+    }
+    static KEY = "zenith.github.token";
+    load() {
+        return this.memory.load();
+    }
+    save(token) {
+        this.memory.save(token);
+        try {
+            this.storage?.setItem(BrowserTokenStore.KEY, token);
+        }
+        catch {
+            // sessionStorage can throw (quota, privacy mode); memory still has the token.
+        }
+    }
+    clear() {
+        this.memory.clear();
+        try {
+            this.storage?.removeItem(BrowserTokenStore.KEY);
+        }
+        catch {
+            // Nothing to clean up if storage was never reachable.
+        }
+    }
+}
+/** Node (the CLI) has no browser storage; the token lives only where the caller puts it. */
+export class NodeTokenStore {
+    load() {
+        return null;
+    }
+    save() {
+        // Intentionally a no-op: see the class comment.
+    }
+    clear() {
+        // Intentionally a no-op: see the class comment.
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/base64.d.ts

@@ -0,0 +1,10 @@
+/**
+ * UTF-8 safe base64, using only `atob`/`btoa` and `TextEncoder`/`TextDecoder` so the package stays
+ * isomorphic: those four are global in every evergreen browser and in Node 18+, unlike `Buffer`,
+ * which is Node-only. The Contents API sends and receives base64 with the file's bytes; going
+ * through `atob`/`btoa` directly (which only understand Latin-1) would corrupt anything outside
+ * that range.
+ */
+export declare function encodeBase64Utf8(text: string): string;
+export declare function decodeBase64Utf8(base64: string): string;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIvD"}

package/dist/base64.js

@@ -0,0 +1,20 @@
+/**
+ * UTF-8 safe base64, using only `atob`/`btoa` and `TextEncoder`/`TextDecoder` so the package stays
+ * isomorphic: those four are global in every evergreen browser and in Node 18+, unlike `Buffer`,
+ * which is Node-only. The Contents API sends and receives base64 with the file's bytes; going
+ * through `atob`/`btoa` directly (which only understand Latin-1) would corrupt anything outside
+ * that range.
+ */
+export function encodeBase64Utf8(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+export function decodeBase64Utf8(base64) {
+    const binary = atob(base64.replace(/\n/g, ""));
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+//# sourceMappingURL=base64.js.map

package/dist/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+import type { Link } from "@horizon36596/zenith-schema";
+import type { AuthProvider } from "./auth.js";
+import { type HttpOptions } from "./http.js";
+import type { Branch, ContentEntry, ContentFile, MergeResult, PullFile, PullRequest, PutResult, Repo, RepoSummary, User } from "./types.js";
+export type GitHubClientOptions = HttpOptions;
+/**
+ * Bounds a write `GitHubClient.contents.put`/`deleteFile` may make: `base` is the branch a write
+ * must never target, and `link` is `zenith.json`'s own allowlist of directories a path must fall
+ * under. Passed by `GitHubProject` on every call it makes, so the guard lives in the client method
+ * itself — not only in `GitHubProject.save`'s own pre-check — and a raw `GitHubClient` call that
+ * passes the same guard is refused exactly the same way. The guard used to sit above the client,
+ * which let a direct client call around it.
+ */
+export interface ContentWriteGuard {
+    base: string;
+    link: Link;
+}
+/** The lighter guard `repos.merge` needs: it has no path, only a branch that must never be the
+ * merge's write target. */
+export interface MergeWriteGuard {
+    base: string;
+}
+/**
+ * An isomorphic (browser + Node), `fetch`-based GitHub client: no Octokit, no Node-only APIs. One
+ * instance is bound to an `AuthProvider`, not to a repository — `GitHubProject` is the layer bound
+ * to `{owner, repo, base}` (site/docs/github.md).
+ */
+export declare class GitHubClient {
+    private readonly http;
+    constructor(auth: AuthProvider, options?: GitHubClientOptions);
+    /** The most recent `x-ratelimit-*` snapshot seen, or `null` before the first request. */
+    get rateLimit(): import("./http.js").RateLimitSnapshot | null;
+    readonly repos: {
+        /** Repositories the authenticated account can push to, across personal and org affiliation. */
+        listWritable: () => Promise<RepoSummary[]>;
+        get: (owner: string, repo: string) => Promise<Repo>;
+        /**
+         * Merges `head` into `base` (`POST /repos/{owner}/{repo}/merges`) — the "update the work
+         * branch from the base branch" step of propose (06 §3 step 2). On conflict, recovers the
+         * files in play by comparing both branches against their merge base; see `MergeConflictError`.
+         * `guard`, when given, refuses the call outright when `base` (the ref the merge commit lands
+         * on) is the project's protected base branch (finding 12).
+         */
+        merge: (owner: string, repo: string, base: string, head: string, guard?: MergeWriteGuard) => Promise<MergeResult>;
+    };
+    readonly branches: {
+        list: (owner: string, repo: string) => Promise<Branch[]>;
+        get: (owner: string, repo: string, branch: string) => Promise<Branch>;
+        /** Creates `name` pointing at `from`'s current sha. Never touches an existing ref (no force-push). */
+        create: (owner: string, repo: string, name: string, from: {
+            branch: string;
+        }) => Promise<Branch>;
+    };
+    readonly contents: {
+        get: (owner: string, repo: string, path: string, ref: string) => Promise<ContentFile>;
+        /** `guard`, when given, refuses a write to the base branch or to a path outside `link`'s
+         * allowlist before any network call (finding 12). `GitHubProject.save` always passes one; a
+         * raw `GitHubClient` caller that cares about the same protection can pass one too. */
+        put: (owner: string, repo: string, path: string, text: string, message: string, branch: string, sha?: string, guard?: ContentWriteGuard) => Promise<PutResult>;
+        list: (owner: string, repo: string, dir: string, ref: string) => Promise<ContentEntry[]>;
+        /** Same guard as `put` (site/docs/github.md): the "never write base, only inside
+         * the allowlist" rule covers a delete exactly as much as it covers a write. */
+        deleteFile: (owner: string, repo: string, path: string, message: string, branch: string, sha: string, guard?: ContentWriteGuard) => Promise<void>;
+    };
+    readonly git: {
+        /** The commit both `base` and `head` descend from, via the compare API's `merge_base_commit`. */
+        mergeBase: (owner: string, repo: string, base: string, head: string) => Promise<string | null>;
+    };
+    readonly pulls: {
+        create: (owner: string, repo: string, input: {
+            title: string;
+            head: string;
+            base: string;
+            body: string;
+        }) => Promise<PullRequest>;
+        update: (owner: string, repo: string, number: number, input: {
+            title?: string;
+            body?: string;
+            state?: "open" | "closed";
+        }) => Promise<PullRequest>;
+        get: (owner: string, repo: string, number: number) => Promise<PullRequest>;
+        listForBranch: (owner: string, repo: string, branch: string, state?: "open" | "closed" | "all") => Promise<PullRequest[]>;
+        files: (owner: string, repo: string, number: number) => Promise<PullFile[]>;
+        requestReviewers: (owner: string, repo: string, number: number, reviewers: string[]) => Promise<void>;
+    };
+    readonly users: {
+        me: () => Promise<User>;
+    };
+    /** Follows `Link: rel="next"` headers to collect every page. */
+    private paginate;
+    /** Files touched on both sides since the merge base: a conservative guess at the conflict set. */
+    private conflictingFiles;
+    private comparedFiles;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}