@anokye-labs/kbexplorer-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anokye Labs
+
+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/README.md

@@ -0,0 +1,77 @@
+# @anokye-labs/kbexplorer-engine
+
+The runtime-agnostic engine for kbexplorer: it turns a knowledge-base source
+(a manifest, the GitHub API, or a local directory) into a computed `KBGraph`,
+and provides a small scriptable query API over that graph. The core (`.`) entry
+stays portable across Node and browser-like environments; Node-specific pieces
+(like `FileSystemSource`) live behind the `./sources` subpath.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+## Package shape
+
+- `.` — the engine core: graph building (`buildGraph`), the unified loader
+  (`loadKnowledgeBase`), the query helpers, providers, parsing, identity, and
+  supporting types.
+- `./sources` — source adapters (`ManifestSource`, `GitHubApiSource`,
+  `FileSystemSource`) and the `RepoSource` / `RepoData` contracts.
+- `./store` — the optional sqlite-backed graph store entry point.
+
+## Loading a knowledge base
+
+`loadKnowledgeBase` has two call shapes, distinguished by the first argument:
+
+```ts
+import { loadKnowledgeBase } from '@anokye-labs/kbexplorer-engine';
+import { GitHubApiSource, FileSystemSource } from '@anokye-labs/kbexplorer-engine/sources';
+
+// Config-first (scripting): returns a bare KBGraph.
+// With no `source`, a GitHubApiSource is built from config.source.
+const graph = await loadKnowledgeBase(config);
+const localGraph = await loadKnowledgeBase(config, { source: new FileSystemSource('./my-kb') });
+
+// Positional (advanced): returns { graph, config }. This is the SHA-pinned
+// contract consumed by kbexplorer-template — it is unchanged.
+const { graph: g, config: c } = await loadKnowledgeBase(new GitHubApiSource(config.source), config);
+```
+
+The two forms differ only in ergonomics and return shape; the positional form
+is fully preserved.
+
+## Query API
+
+Pure, runtime-agnostic helpers over a computed `KBGraph`:
+
+```ts
+import {
+  getNode, findNodes, neighbors, related, subgraph, shortestPath,
+} from '@anokye-labs/kbexplorer-engine';
+
+getNode(graph, 'home');                         // KBNode | undefined
+findNodes(graph, n => n.cluster === 'engine');  // KBNode[]
+neighbors(graph, 'home', { direction: 'out' }); // KBNode[]
+related(graph, 'home');                          // KBNode[] (precomputed index)
+subgraph(graph, 'home', { radius: 2 });          // KBGraph neighborhood
+shortestPath(graph, 'home', 'loader');           // string[] | null
+```
+
+## Sources
+
+- `ManifestSource(manifest, config)` — a frozen, pre-built snapshot.
+- `GitHubApiSource(sourceConfig)` — the live GitHub API.
+- `FileSystemSource(rootDir, options?)` — **Node-only** adapter that walks a
+  local directory into the same `RepoData` bundle a manifest yields (authored
+  `content/`, `.github` structural files, `content-model/`, README).
+
+## Recipes
+
+Runnable examples of the scriptable API against an in-repo fixture live in
+[`docs/recipes.md`](./docs/recipes.md). CI builds the package and runs all eight
+scripts on every pull request.

package/dist/build-manifest-BT0sY84J.d.ts

@@ -0,0 +1,239 @@
+import { SourceConfig } from '@anokye-labs/kbexplorer-core';
+import { E as EngineEnv, k as GHCommit, G as GHIssue, c as GHRelease, b as GHTreeItem, a as ContentModelSource, R as RepoSource } from './repo-data-0JvFdLGv.js';
+
+/**
+ * GitHub API client for fetching repository content at runtime.
+ *
+ * Runtime-agnostic, boundary-pure port of kbexplorer-template's
+ * `src/api/github.ts` (anokye-labs/kbexplorer-template#472, slice 4/5). The
+ * template client wrapped every call in a browser-storage cache and read the
+ * API base from a Vite build-time env at module scope. Neither of those belongs
+ * in this runtime-agnostic engine package, so this port drops the cache layer
+ * entirely (it stays template-side as a thin wrapper) and injects the API base
+ * per call via an optional {@link EngineEnv} argument — mirroring the injection
+ * idiom already used in `src/store/config.ts`. `resolveImageUrl` (a pure
+ * UI/dev-server concern) is intentionally not ported; it stays in template.
+ *
+ * Supports two modes:
+ *   - authored: fetches markdown files from a content directory
+ *   - repo-aware: fetches issues, PRs, README, and file tree
+ */
+
+/**
+ * The distinct GitHub REST endpoint path patterns this client's `ghFetch` call
+ * sites hit — one entry per endpoint family. Exported as a single source of
+ * truth so an out-of-repo drift-detection test (kbexplorer-template's
+ * `twin-coverage.test.ts`) can import it instead of regexing this file's raw
+ * source text: adding a new endpoint here fails that test until a matching twin
+ * route exists. Keep this in sync with the paths passed to `ghFetch` below.
+ */
+declare const GITHUB_ENDPOINT_PATTERNS: readonly ["contents/", "git/trees/", "issues", "pulls", "commits", "releases", "branches", "languages"];
+declare class NotModifiedError extends Error {
+    constructor();
+}
+declare class RateLimitError extends Error {
+    resetAt?: Date;
+    constructor(resetAt?: Date);
+}
+declare class GitHubApiError extends Error {
+    status: number;
+    constructor(status: number, body: string);
+}
+interface GHFileContent {
+    name: string;
+    path: string;
+    sha: string;
+    content: string;
+    encoding: string;
+}
+interface CacheStore {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+}
+/** Fetch and decode a single file from the repo. */
+declare function fetchFile(source: SourceConfig, path: string, env?: EngineEnv, cache?: CacheStore): Promise<string>;
+/** List all files in a directory (recursive via Git Trees API). */
+declare function fetchTree(source: SourceConfig, path?: string, env?: EngineEnv, cache?: CacheStore): Promise<GHTreeItem[]>;
+/** Fetch issues (not PRs) from the repo. */
+declare function fetchIssues(source: SourceConfig, env?: EngineEnv, cache?: CacheStore): Promise<GHIssue[]>;
+/** Fetch pull requests from the repo. */
+declare function fetchPullRequests(source: SourceConfig, env?: EngineEnv, cache?: CacheStore): Promise<GHIssue[]>;
+/** Fetch recent commits from the repo. */
+declare function fetchCommits(source: SourceConfig, count?: number, env?: EngineEnv, cache?: CacheStore): Promise<GHCommit[]>;
+/** Fetch GitHub releases (non-draft, newest-first, capped at 30). */
+declare function fetchReleases(source: SourceConfig, limit?: number, env?: EngineEnv, cache?: CacheStore): Promise<GHRelease[]>;
+/** Fetch multiple files in parallel. */
+declare function fetchFiles(source: SourceConfig, paths: string[], env?: EngineEnv, cache?: CacheStore): Promise<Map<string, string>>;
+
+/**
+ * RepoManifest — the pre-built snapshot shape a {@link ManifestSource} is
+ * constructed from (relocated from kbexplorer-template's `src/engine/
+ * local-loader.ts` in anokye-labs/kbexplorer-template#472, slice 4/5).
+ *
+ * It moves into this package because `ManifestSource`'s constructor takes one.
+ * The manifest-generation script and the local (manifest-import) loader remain
+ * template-side; only the interface travels here.
+ */
+
+interface RepoManifest {
+    configRaw: string | null;
+    authoredContent: Record<string, string>;
+    tree: Array<{
+        path: string;
+        type: 'blob' | 'tree';
+        size?: number;
+    }>;
+    readme: string | null;
+    issues: GHIssue[];
+    pullRequests: Array<{
+        number: number;
+        title: string;
+        body: string;
+        state: string;
+        labels: Array<{
+            name: string;
+            color: string;
+        }>;
+        html_url: string;
+        created_at: string;
+        updated_at: string;
+        head_branch?: string;
+    }>;
+    commits: Array<{
+        sha: string;
+        commit: {
+            message: string;
+            author: {
+                name: string;
+                date: string;
+            };
+        };
+        html_url: string;
+    }>;
+    branches?: Array<{
+        name: string;
+        protected: boolean;
+    }>;
+    /**
+     * GitHub releases (non-draft, newest-first, capped at 30). Absent/empty in
+     * repos without releases — the WorkProvider handles this gracefully (safe no-op).
+     */
+    releases?: GHRelease[];
+    repoMetadata?: {
+        name: string;
+        description: string;
+        html_url: string;
+        /** Repo homepage URL (blank when unset). Matches the old generator's 12-key `fetchRepoMetadata` shape. */
+        homepage: string;
+        default_branch: string;
+        stargazers_count: number;
+        forks_count: number;
+        private: boolean;
+        topics: string[];
+        primary_language: string;
+        languages: Array<{
+            name: string;
+            size: number;
+        }>;
+        owner: {
+            login: string;
+            avatar_url: string;
+        };
+    } | null;
+    nodemapRaw?: string | null;
+    nodemapFiles?: Record<string, string>;
+    nodemapDirs?: Record<string, Array<{
+        path: string;
+        type: 'blob' | 'tree';
+        size?: number;
+    }>>;
+    structuredNodeMapRaw?: string | null;
+    structuralFiles?: Record<string, string>;
+    /**
+     * Optional content-model source (F2): schema files + entity files keyed by
+     * path relative to `structuredContent.path` (default `content-model/`). Absent
+     * (null) in repos without a content model — the ContentModelProvider is then a
+     * safe no-op.
+     */
+    contentModel?: ContentModelSource | null;
+    /**
+     * Optional raw contents of the dedicated theme file referenced by
+     * `config.theme.themesFile` (F5/T5.1). Read at manifest-generation time from
+     * the host repo and merged into the theme block in local mode the same way
+     * the remote loader fetches it at runtime. Null/absent when no themesFile is
+     * configured or the file is missing — a safe no-op.
+     */
+    themeFileRaw?: string | null;
+    generatedAt: string;
+}
+
+/**
+ * buildManifest() — the manifest PRODUCER (anokye-labs/kbexplorer-engine#17,
+ * the anchor child of the thin-CLI/fat-engine epic
+ * anokye-labs/kbexplorer-template#463).
+ *
+ * The engine already owned the manifest **consume** path — `ManifestSource`,
+ * the `RepoSource` acquisition adapters (`GitHubApiSource`, `FileSystemSource`),
+ * and the `RepoManifest` snapshot shape itself (`./repo-manifest`). What was
+ * missing was the **producer**: something that turns a `RepoSource` into a
+ * `RepoManifest`. That logic lived duplicated outside the engine, in
+ * kbexplorer-template's `scripts/generate-manifest.js` and the CLI's
+ * byte-parallel `src/lib/repo-manifest.ts` fork (flagged by cli#232).
+ *
+ * `buildManifest` closes that loop *without* re-implementing any fetching:
+ * acquisition (GitHub REST calls, local filesystem walks) already lives on the
+ * injected `RepoSource`. This function drives it through the existing
+ * `getRepoData()` seam exactly once and re-shapes the normalized `RepoData`
+ * bundle into the serializable `RepoManifest` snapshot — the mechanical,
+ * source-agnostic half of what the template script does before it writes
+ * `repo-manifest.json` to disk. It is deliberately the mirror image of
+ * `ManifestSource.getRepoData()` (which maps `RepoManifest` → `RepoData`);
+ * this maps `RepoData` → `RepoManifest`.
+ *
+ * Signature note (`buildManifest(source, options)`, not `(source, config)`):
+ * every `RepoManifest` field this function assembles comes straight off
+ * `RepoData` — none of them need a resolved `KBConfig`. The two fields a
+ * `RepoSource` cannot uniformly supply are threaded in via `options` instead:
+ *
+ *  - `configRaw` — the raw (pre-YAML-parse) `config.yaml` text. `KBConfig`
+ *    (what `GitHubApiSource.resolveConfig()` / a local `loadConfig()` caller
+ *    would have) is already-parsed, so it can't round-trip back to source
+ *    text. Callers already hold (or can cheaply obtain) the raw text — a local
+ *    caller reads the same file `FileSystemSource` walks, and a remote caller
+ *    already has the engine's exported `fetchFile` to hand — so this function
+ *    accepts it rather than duplicating a second raw-fetch code path.
+ *  - `generatedAt` — the snapshot timestamp. Defaults to
+ *    `new Date().toISOString()` but is overridable so callers (and this
+ *    package's own tests) can produce deterministic output for
+ *    idempotency/`--check`-drift assertions, matching the issue's requirement
+ *    that source-derived fields (everything *except* `generatedAt`/live
+ *    GitHub state) be deterministic.
+ *
+ * `nodemapFiles`/`nodemapDirs` are passed through as-is from `RepoData` when a
+ * source populates them (neither shipped `RepoSource` does yet — both leave
+ * `nodemapRaw: null`, matching their existing, unchanged behavior — so
+ * `buildManifest` carries whatever future sources supply without
+ * re-implementing the template script's nodemap-collection logic itself,
+ * which is out of this issue's scope: see the issue's "non-goals").
+ */
+
+/** Options for fields `RepoData` cannot uniformly supply (see module docs). */
+interface BuildManifestOptions {
+    /** Raw (pre-parse) `config.yaml` text to embed, or `null`/omitted when there is none. */
+    configRaw?: string | null;
+    /**
+     * Overrides the snapshot timestamp. Defaults to `new Date().toISOString()`.
+     * Pass a fixed value for deterministic/idempotency tests and `--check` drift
+     * comparisons, which must ignore this volatile field regardless.
+     */
+    generatedAt?: string;
+    /** When set, overlay the live-GitHub fields from this source onto the primary-source manifest (hybrid: local content + live augmentation). */
+    augmentFrom?: RepoSource;
+}
+/**
+ * Drive `source.getRepoData()` once and assemble a `RepoManifest` snapshot
+ * from the result — the producer half of the `ManifestSource` contract.
+ */
+declare function buildManifest(source: RepoSource, options?: BuildManifestOptions): Promise<RepoManifest>;
+
+export { type BuildManifestOptions as B, type CacheStore as C, type GHFileContent as G, NotModifiedError as N, type RepoManifest as R, fetchFile as a, buildManifest as b, fetchFiles as c, fetchIssues as d, fetchPullRequests as e, fetchCommits as f, fetchReleases as g, fetchTree as h, GITHUB_ENDPOINT_PATTERNS as i, GitHubApiError as j, RateLimitError as k };

package/dist/build-manifest-BkgZUL0E.d.cts

@@ -0,0 +1,239 @@
+import { SourceConfig } from '@anokye-labs/kbexplorer-core';
+import { E as EngineEnv, k as GHCommit, G as GHIssue, c as GHRelease, b as GHTreeItem, a as ContentModelSource, R as RepoSource } from './repo-data-0JvFdLGv.cjs';
+
+/**
+ * GitHub API client for fetching repository content at runtime.
+ *
+ * Runtime-agnostic, boundary-pure port of kbexplorer-template's
+ * `src/api/github.ts` (anokye-labs/kbexplorer-template#472, slice 4/5). The
+ * template client wrapped every call in a browser-storage cache and read the
+ * API base from a Vite build-time env at module scope. Neither of those belongs
+ * in this runtime-agnostic engine package, so this port drops the cache layer
+ * entirely (it stays template-side as a thin wrapper) and injects the API base
+ * per call via an optional {@link EngineEnv} argument — mirroring the injection
+ * idiom already used in `src/store/config.ts`. `resolveImageUrl` (a pure
+ * UI/dev-server concern) is intentionally not ported; it stays in template.
+ *
+ * Supports two modes:
+ *   - authored: fetches markdown files from a content directory
+ *   - repo-aware: fetches issues, PRs, README, and file tree
+ */
+
+/**
+ * The distinct GitHub REST endpoint path patterns this client's `ghFetch` call
+ * sites hit — one entry per endpoint family. Exported as a single source of
+ * truth so an out-of-repo drift-detection test (kbexplorer-template's
+ * `twin-coverage.test.ts`) can import it instead of regexing this file's raw
+ * source text: adding a new endpoint here fails that test until a matching twin
+ * route exists. Keep this in sync with the paths passed to `ghFetch` below.
+ */
+declare const GITHUB_ENDPOINT_PATTERNS: readonly ["contents/", "git/trees/", "issues", "pulls", "commits", "releases", "branches", "languages"];
+declare class NotModifiedError extends Error {
+    constructor();
+}
+declare class RateLimitError extends Error {
+    resetAt?: Date;
+    constructor(resetAt?: Date);
+}
+declare class GitHubApiError extends Error {
+    status: number;
+    constructor(status: number, body: string);
+}
+interface GHFileContent {
+    name: string;
+    path: string;
+    sha: string;
+    content: string;
+    encoding: string;
+}
+interface CacheStore {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+}
+/** Fetch and decode a single file from the repo. */
+declare function fetchFile(source: SourceConfig, path: string, env?: EngineEnv, cache?: CacheStore): Promise<string>;
+/** List all files in a directory (recursive via Git Trees API). */
+declare function fetchTree(source: SourceConfig, path?: string, env?: EngineEnv, cache?: CacheStore): Promise<GHTreeItem[]>;
+/** Fetch issues (not PRs) from the repo. */
+declare function fetchIssues(source: SourceConfig, env?: EngineEnv, cache?: CacheStore): Promise<GHIssue[]>;
+/** Fetch pull requests from the repo. */
+declare function fetchPullRequests(source: SourceConfig, env?: EngineEnv, cache?: CacheStore): Promise<GHIssue[]>;
+/** Fetch recent commits from the repo. */
+declare function fetchCommits(source: SourceConfig, count?: number, env?: EngineEnv, cache?: CacheStore): Promise<GHCommit[]>;
+/** Fetch GitHub releases (non-draft, newest-first, capped at 30). */
+declare function fetchReleases(source: SourceConfig, limit?: number, env?: EngineEnv, cache?: CacheStore): Promise<GHRelease[]>;
+/** Fetch multiple files in parallel. */
+declare function fetchFiles(source: SourceConfig, paths: string[], env?: EngineEnv, cache?: CacheStore): Promise<Map<string, string>>;
+
+/**
+ * RepoManifest — the pre-built snapshot shape a {@link ManifestSource} is
+ * constructed from (relocated from kbexplorer-template's `src/engine/
+ * local-loader.ts` in anokye-labs/kbexplorer-template#472, slice 4/5).
+ *
+ * It moves into this package because `ManifestSource`'s constructor takes one.
+ * The manifest-generation script and the local (manifest-import) loader remain
+ * template-side; only the interface travels here.
+ */
+
+interface RepoManifest {
+    configRaw: string | null;
+    authoredContent: Record<string, string>;
+    tree: Array<{
+        path: string;
+        type: 'blob' | 'tree';
+        size?: number;
+    }>;
+    readme: string | null;
+    issues: GHIssue[];
+    pullRequests: Array<{
+        number: number;
+        title: string;
+        body: string;
+        state: string;
+        labels: Array<{
+            name: string;
+            color: string;
+        }>;
+        html_url: string;
+        created_at: string;
+        updated_at: string;
+        head_branch?: string;
+    }>;
+    commits: Array<{
+        sha: string;
+        commit: {
+            message: string;
+            author: {
+                name: string;
+                date: string;
+            };
+        };
+        html_url: string;
+    }>;
+    branches?: Array<{
+        name: string;
+        protected: boolean;
+    }>;
+    /**
+     * GitHub releases (non-draft, newest-first, capped at 30). Absent/empty in
+     * repos without releases — the WorkProvider handles this gracefully (safe no-op).
+     */
+    releases?: GHRelease[];
+    repoMetadata?: {
+        name: string;
+        description: string;
+        html_url: string;
+        /** Repo homepage URL (blank when unset). Matches the old generator's 12-key `fetchRepoMetadata` shape. */
+        homepage: string;
+        default_branch: string;
+        stargazers_count: number;
+        forks_count: number;
+        private: boolean;
+        topics: string[];
+        primary_language: string;
+        languages: Array<{
+            name: string;
+            size: number;
+        }>;
+        owner: {
+            login: string;
+            avatar_url: string;
+        };
+    } | null;
+    nodemapRaw?: string | null;
+    nodemapFiles?: Record<string, string>;
+    nodemapDirs?: Record<string, Array<{
+        path: string;
+        type: 'blob' | 'tree';
+        size?: number;
+    }>>;
+    structuredNodeMapRaw?: string | null;
+    structuralFiles?: Record<string, string>;
+    /**
+     * Optional content-model source (F2): schema files + entity files keyed by
+     * path relative to `structuredContent.path` (default `content-model/`). Absent
+     * (null) in repos without a content model — the ContentModelProvider is then a
+     * safe no-op.
+     */
+    contentModel?: ContentModelSource | null;
+    /**
+     * Optional raw contents of the dedicated theme file referenced by
+     * `config.theme.themesFile` (F5/T5.1). Read at manifest-generation time from
+     * the host repo and merged into the theme block in local mode the same way
+     * the remote loader fetches it at runtime. Null/absent when no themesFile is
+     * configured or the file is missing — a safe no-op.
+     */
+    themeFileRaw?: string | null;
+    generatedAt: string;
+}
+
+/**
+ * buildManifest() — the manifest PRODUCER (anokye-labs/kbexplorer-engine#17,
+ * the anchor child of the thin-CLI/fat-engine epic
+ * anokye-labs/kbexplorer-template#463).
+ *
+ * The engine already owned the manifest **consume** path — `ManifestSource`,
+ * the `RepoSource` acquisition adapters (`GitHubApiSource`, `FileSystemSource`),
+ * and the `RepoManifest` snapshot shape itself (`./repo-manifest`). What was
+ * missing was the **producer**: something that turns a `RepoSource` into a
+ * `RepoManifest`. That logic lived duplicated outside the engine, in
+ * kbexplorer-template's `scripts/generate-manifest.js` and the CLI's
+ * byte-parallel `src/lib/repo-manifest.ts` fork (flagged by cli#232).
+ *
+ * `buildManifest` closes that loop *without* re-implementing any fetching:
+ * acquisition (GitHub REST calls, local filesystem walks) already lives on the
+ * injected `RepoSource`. This function drives it through the existing
+ * `getRepoData()` seam exactly once and re-shapes the normalized `RepoData`
+ * bundle into the serializable `RepoManifest` snapshot — the mechanical,
+ * source-agnostic half of what the template script does before it writes
+ * `repo-manifest.json` to disk. It is deliberately the mirror image of
+ * `ManifestSource.getRepoData()` (which maps `RepoManifest` → `RepoData`);
+ * this maps `RepoData` → `RepoManifest`.
+ *
+ * Signature note (`buildManifest(source, options)`, not `(source, config)`):
+ * every `RepoManifest` field this function assembles comes straight off
+ * `RepoData` — none of them need a resolved `KBConfig`. The two fields a
+ * `RepoSource` cannot uniformly supply are threaded in via `options` instead:
+ *
+ *  - `configRaw` — the raw (pre-YAML-parse) `config.yaml` text. `KBConfig`
+ *    (what `GitHubApiSource.resolveConfig()` / a local `loadConfig()` caller
+ *    would have) is already-parsed, so it can't round-trip back to source
+ *    text. Callers already hold (or can cheaply obtain) the raw text — a local
+ *    caller reads the same file `FileSystemSource` walks, and a remote caller
+ *    already has the engine's exported `fetchFile` to hand — so this function
+ *    accepts it rather than duplicating a second raw-fetch code path.
+ *  - `generatedAt` — the snapshot timestamp. Defaults to
+ *    `new Date().toISOString()` but is overridable so callers (and this
+ *    package's own tests) can produce deterministic output for
+ *    idempotency/`--check`-drift assertions, matching the issue's requirement
+ *    that source-derived fields (everything *except* `generatedAt`/live
+ *    GitHub state) be deterministic.
+ *
+ * `nodemapFiles`/`nodemapDirs` are passed through as-is from `RepoData` when a
+ * source populates them (neither shipped `RepoSource` does yet — both leave
+ * `nodemapRaw: null`, matching their existing, unchanged behavior — so
+ * `buildManifest` carries whatever future sources supply without
+ * re-implementing the template script's nodemap-collection logic itself,
+ * which is out of this issue's scope: see the issue's "non-goals").
+ */
+
+/** Options for fields `RepoData` cannot uniformly supply (see module docs). */
+interface BuildManifestOptions {
+    /** Raw (pre-parse) `config.yaml` text to embed, or `null`/omitted when there is none. */
+    configRaw?: string | null;
+    /**
+     * Overrides the snapshot timestamp. Defaults to `new Date().toISOString()`.
+     * Pass a fixed value for deterministic/idempotency tests and `--check` drift
+     * comparisons, which must ignore this volatile field regardless.
+     */
+    generatedAt?: string;
+    /** When set, overlay the live-GitHub fields from this source onto the primary-source manifest (hybrid: local content + live augmentation). */
+    augmentFrom?: RepoSource;
+}
+/**
+ * Drive `source.getRepoData()` once and assemble a `RepoManifest` snapshot
+ * from the result — the producer half of the `ManifestSource` contract.
+ */
+declare function buildManifest(source: RepoSource, options?: BuildManifestOptions): Promise<RepoManifest>;
+
+export { type BuildManifestOptions as B, type CacheStore as C, type GHFileContent as G, NotModifiedError as N, type RepoManifest as R, fetchFile as a, buildManifest as b, fetchFiles as c, fetchIssues as d, fetchPullRequests as e, fetchCommits as f, fetchReleases as g, fetchTree as h, GITHUB_ENDPOINT_PATTERNS as i, GitHubApiError as j, RateLimitError as k };