@anokye-labs/kbexplorer-engine 0.1.0

package/dist/sources.d.cts

@@ -0,0 +1,194 @@
+import { Affordance, KBConfig, ResourceQuery, Resource, SourceConfig } from '@anokye-labs/kbexplorer-core';
+import { R as RepoManifest, C as CacheStore } from './build-manifest-BkgZUL0E.cjs';
+export { B as BuildManifestOptions, G as GHFileContent, i as GITHUB_ENDPOINT_PATTERNS, j as GitHubApiError, N as NotModifiedError, k as RateLimitError, b as buildManifest, f as fetchCommits, a as fetchFile, c as fetchFiles, d as fetchIssues, e as fetchPullRequests, g as fetchReleases, h as fetchTree } from './build-manifest-BkgZUL0E.cjs';
+import { R as RepoSource, d as RepoData, E as EngineEnv } from './repo-data-0JvFdLGv.cjs';
+export { k as GHCommit, G as GHIssue, c as GHRelease, b as GHTreeItem, w as RepoMetadata, x as RepoPullRequest } from './repo-data-0JvFdLGv.cjs';
+
+/**
+ * ManifestSource (Phase 4 / F4 #320; moved in
+ * anokye-labs/kbexplorer-template#472, slice 4/5).
+ *
+ * A read-only {@link RepoSource} backed by a pre-built `repo-manifest.json`.
+ * Every resource it retrieves carries exactly `['read']` — a manifest is a
+ * frozen snapshot, so nothing can be written or staged through it. There is no
+ * staging area (and therefore no `staging-area` link): staging is a Git/GitHub
+ * concern, absent from a static manifest.
+ */
+
+declare class ManifestSource implements RepoSource {
+    readonly id = "manifest";
+    readonly name = "Repo Manifest";
+    /** A manifest is a frozen snapshot — read is the only possible affordance. */
+    readonly possibleAffordances: Affordance[];
+    private readonly manifest;
+    private readonly config;
+    constructor(manifest: RepoManifest, config: KBConfig);
+    getRepoData(): Promise<RepoData>;
+    /**
+     * Read-only resource surface. Files (tree blobs/trees) and issues are
+     * retrievable; every resource is afforded `['read']` and links only to
+     * itself. No write/stage, no staging area.
+     */
+    retrieve(query: ResourceQuery): Promise<Resource[]>;
+    get(href: string): Promise<Resource | undefined>;
+    private fileResource;
+    private issueResource;
+}
+
+/**
+ * GitHubApiSource (Phase 4 / F4 #321, #322; moved in
+ * anokye-labs/kbexplorer-template#472, slice 4/5).
+ *
+ * A composite {@link RepoSource} over the live GitHub API. It is deliberately a
+ * *composite* of two resource families that are never conflated:
+ *
+ *  • **Git** resources — `file` / `tree` / `commit` / `staging-area`, with the
+ *    git-worktree affordances `read` / `write` / `stage`. Addressed `git://`.
+ *  • **GitHub** resources — `issue` / `pull-request` / `release`, with their own
+ *    operations (`comment` / `close` / `merge`). Addressed `github://`.
+ *
+ * Affordances are **per-retrieval**: the same file comes back `['read']` from a
+ * plain read, `['read','write','stage']` when retrieved against a writable
+ * worktree, and — once staged — additionally carries a first-class
+ * `{ rel: 'staging-area', href }` link to the retrievable staging area. PR
+ * draft/proposed/merge states are GitHub concepts and never appear as git
+ * `stage` sub-states.
+ *
+ * The data path (`getRepoData`) reproduces the former remote loader's fetch
+ * exactly, so the unified loader stays byte-identical for this source. The one
+ * adaptation vs template is env-injection: the GitHub client's API base is now
+ * supplied per call, so this source threads its optional {@link EngineEnv}
+ * through every fetch it makes.
+ */
+
+type ResolutionPreset = 'summary' | 'standard' | 'full';
+declare class GitHubApiSource implements RepoSource {
+    readonly id = "github-api";
+    readonly name = "GitHub API";
+    /** Advisory universe; authoritative affordances live on each retrieval. */
+    readonly possibleAffordances: Affordance[];
+    private fetchPromise;
+    private readonly source;
+    private readonly preset;
+    private readonly env?;
+    private readonly cache?;
+    constructor(source: SourceConfig, preset?: ResolutionPreset, env?: EngineEnv, cache?: CacheStore);
+    /** The locator of this repo's staging area (git index). */
+    private get stagingHref();
+    /** Fetch (memoized) so `resolveConfig` + `getRepoData` share one round-trip. */
+    private fetch;
+    /** Resolve the config without re-fetching. */
+    resolveConfig(): Promise<KBConfig>;
+    resolveThemeFileRaw(): Promise<string | null>;
+    getRepoData(): Promise<RepoData>;
+    retrieve(query: ResourceQuery): Promise<Resource[]>;
+    get(href: string): Promise<Resource | undefined>;
+    /**
+     * A git file/tree resource. Affordances are situational:
+     *  - plain read → `['read']`
+     *  - writable worktree → `['read','write','stage']`
+     *  - staged → `['read','write','stage']` PLUS a `staging-area` link.
+     */
+    private gitFileResource;
+    private stagingAreaResource;
+    private commitResource;
+    private issueResource;
+    private pullRequestResource;
+    private releaseResource;
+    private fetchGitHubData;
+    /**
+     * Direct children of `dir` in an already-fetched git tree — a nodemap
+     * `directory:` entry's listing derived with no extra API call. Skips
+     * dotfile-named children, mirroring the local source's `listNodemapDir`.
+     */
+    private listNodemapDirFromTree;
+    private fetchContentModel;
+}
+
+/** Options controlling how a {@link FileSystemSource} interprets a directory. */
+interface FileSystemSourceOptions {
+    /**
+     * `owner/name` slug used for file-node identity. Defaults to the root
+     * directory's base name (with no owner segment).
+     */
+    repo?: string;
+    /**
+     * Sub-directory (relative to the root) whose `.md` files become authored
+     * content nodes. Defaults to `'content'`. Pass `''` (or `'.'`) to treat
+     * **top-level** `.md` files in the root itself as authored content (the
+     * legacy root-scan convention) — `README.md` still stays the repo readme.
+     */
+    contentPath?: string;
+    /**
+     * Sub-directory (relative to the root) holding structured content-model
+     * files. Defaults to `'content-model'`.
+     */
+    contentModelPath?: string;
+    /**
+     * Directory names to skip while walking (in addition to the always-skipped
+     * `.git`, `node_modules`, and `dist`).
+     */
+    ignore?: string[];
+    /**
+     * Whether the walked file tree is exposed as `RepoData.tree` (which the
+     * unified loader turns into structural file/dir/repo-root nodes via
+     * `FilesProvider`). Defaults to `true` (byte-identical to prior behavior).
+     * Set `false` for a **content-only** graph — authored content + provider
+     * entities, with none of the file-tree scaffolding nodes. `listFiles` and
+     * authored-content ingestion are unaffected; only the emitted `tree` (and the
+     * `retrieve`/`get` resource surface derived from it) is suppressed.
+     */
+    includeFileTree?: boolean;
+}
+declare class FileSystemSource implements RepoSource {
+    readonly id = "filesystem";
+    readonly name = "File System";
+    /** A local snapshot read — read is the only possible affordance. */
+    readonly possibleAffordances: Affordance[];
+    private readonly rootDir;
+    private readonly repo;
+    private readonly contentPath;
+    private readonly contentModelPath;
+    private readonly ignore;
+    private readonly includeFileTree;
+    private cache;
+    constructor(rootDir: string, options?: FileSystemSourceOptions);
+    getRepoData(): Promise<RepoData>;
+    private readRepoData;
+    /** Read one repo-relative file as UTF-8. */
+    private read;
+    /** Read one repo-relative file as UTF-8, returning `null` when missing/unreadable. */
+    private readSafe;
+    /** Read `nodemap.yaml`/`nodemap.yml` from the repo root, or `null` if neither exists. */
+    private readNodemapRaw;
+    /** Read `${contentPath}/config.yaml`(`.yml`), falling back to a root-level `config.yaml`. */
+    private readConfigRaw;
+    /**
+     * Read the raw contents of the dedicated theme file referenced by
+     * `config.theme.themesFile`, mirroring the old generator's `readThemeFile`.
+     * `null` when no `themesFile` is configured, the config can't be parsed, the
+     * path escapes the repo root, or the file is missing — a safe no-op.
+     */
+    private resolveThemeFileRaw;
+    /**
+     * One-level directory listing (with file sizes) for a nodemap `directory:`
+     * entry — distinct from `walk()`, which is recursive and does not stat
+     * files. Mirrors the old generator's `listDir`.
+     */
+    private listNodemapDir;
+    /** Convert an absolute path under the root into a POSIX repo-relative path. */
+    private toRepoRelative;
+    /**
+     * Recursively enumerate the root directory into blob/tree entries with
+     * POSIX-separated, repo-relative paths (sorted for determinism). Skips
+     * dotfiles/dot-directories (except `.github`, which the StructuralProvider
+     * reads) in addition to the always-ignored directories — mirrors the old
+     * generator's `walkFileSystem` (anokye-labs/kbexplorer-engine#23).
+     */
+    private walk;
+    retrieve(query: ResourceQuery): Promise<Resource[]>;
+    get(href: string): Promise<Resource | undefined>;
+    private fileResource;
+}
+
+export { CacheStore, FileSystemSource, type FileSystemSourceOptions, GitHubApiSource, ManifestSource, RepoData, RepoManifest, RepoSource, type ResolutionPreset };

package/dist/sources.d.ts

@@ -0,0 +1,194 @@
+import { Affordance, KBConfig, ResourceQuery, Resource, SourceConfig } from '@anokye-labs/kbexplorer-core';
+import { R as RepoManifest, C as CacheStore } from './build-manifest-BT0sY84J.js';
+export { B as BuildManifestOptions, G as GHFileContent, i as GITHUB_ENDPOINT_PATTERNS, j as GitHubApiError, N as NotModifiedError, k as RateLimitError, b as buildManifest, f as fetchCommits, a as fetchFile, c as fetchFiles, d as fetchIssues, e as fetchPullRequests, g as fetchReleases, h as fetchTree } from './build-manifest-BT0sY84J.js';
+import { R as RepoSource, d as RepoData, E as EngineEnv } from './repo-data-0JvFdLGv.js';
+export { k as GHCommit, G as GHIssue, c as GHRelease, b as GHTreeItem, w as RepoMetadata, x as RepoPullRequest } from './repo-data-0JvFdLGv.js';
+
+/**
+ * ManifestSource (Phase 4 / F4 #320; moved in
+ * anokye-labs/kbexplorer-template#472, slice 4/5).
+ *
+ * A read-only {@link RepoSource} backed by a pre-built `repo-manifest.json`.
+ * Every resource it retrieves carries exactly `['read']` — a manifest is a
+ * frozen snapshot, so nothing can be written or staged through it. There is no
+ * staging area (and therefore no `staging-area` link): staging is a Git/GitHub
+ * concern, absent from a static manifest.
+ */
+
+declare class ManifestSource implements RepoSource {
+    readonly id = "manifest";
+    readonly name = "Repo Manifest";
+    /** A manifest is a frozen snapshot — read is the only possible affordance. */
+    readonly possibleAffordances: Affordance[];
+    private readonly manifest;
+    private readonly config;
+    constructor(manifest: RepoManifest, config: KBConfig);
+    getRepoData(): Promise<RepoData>;
+    /**
+     * Read-only resource surface. Files (tree blobs/trees) and issues are
+     * retrievable; every resource is afforded `['read']` and links only to
+     * itself. No write/stage, no staging area.
+     */
+    retrieve(query: ResourceQuery): Promise<Resource[]>;
+    get(href: string): Promise<Resource | undefined>;
+    private fileResource;
+    private issueResource;
+}
+
+/**
+ * GitHubApiSource (Phase 4 / F4 #321, #322; moved in
+ * anokye-labs/kbexplorer-template#472, slice 4/5).
+ *
+ * A composite {@link RepoSource} over the live GitHub API. It is deliberately a
+ * *composite* of two resource families that are never conflated:
+ *
+ *  • **Git** resources — `file` / `tree` / `commit` / `staging-area`, with the
+ *    git-worktree affordances `read` / `write` / `stage`. Addressed `git://`.
+ *  • **GitHub** resources — `issue` / `pull-request` / `release`, with their own
+ *    operations (`comment` / `close` / `merge`). Addressed `github://`.
+ *
+ * Affordances are **per-retrieval**: the same file comes back `['read']` from a
+ * plain read, `['read','write','stage']` when retrieved against a writable
+ * worktree, and — once staged — additionally carries a first-class
+ * `{ rel: 'staging-area', href }` link to the retrievable staging area. PR
+ * draft/proposed/merge states are GitHub concepts and never appear as git
+ * `stage` sub-states.
+ *
+ * The data path (`getRepoData`) reproduces the former remote loader's fetch
+ * exactly, so the unified loader stays byte-identical for this source. The one
+ * adaptation vs template is env-injection: the GitHub client's API base is now
+ * supplied per call, so this source threads its optional {@link EngineEnv}
+ * through every fetch it makes.
+ */
+
+type ResolutionPreset = 'summary' | 'standard' | 'full';
+declare class GitHubApiSource implements RepoSource {
+    readonly id = "github-api";
+    readonly name = "GitHub API";
+    /** Advisory universe; authoritative affordances live on each retrieval. */
+    readonly possibleAffordances: Affordance[];
+    private fetchPromise;
+    private readonly source;
+    private readonly preset;
+    private readonly env?;
+    private readonly cache?;
+    constructor(source: SourceConfig, preset?: ResolutionPreset, env?: EngineEnv, cache?: CacheStore);
+    /** The locator of this repo's staging area (git index). */
+    private get stagingHref();
+    /** Fetch (memoized) so `resolveConfig` + `getRepoData` share one round-trip. */
+    private fetch;
+    /** Resolve the config without re-fetching. */
+    resolveConfig(): Promise<KBConfig>;
+    resolveThemeFileRaw(): Promise<string | null>;
+    getRepoData(): Promise<RepoData>;
+    retrieve(query: ResourceQuery): Promise<Resource[]>;
+    get(href: string): Promise<Resource | undefined>;
+    /**
+     * A git file/tree resource. Affordances are situational:
+     *  - plain read → `['read']`
+     *  - writable worktree → `['read','write','stage']`
+     *  - staged → `['read','write','stage']` PLUS a `staging-area` link.
+     */
+    private gitFileResource;
+    private stagingAreaResource;
+    private commitResource;
+    private issueResource;
+    private pullRequestResource;
+    private releaseResource;
+    private fetchGitHubData;
+    /**
+     * Direct children of `dir` in an already-fetched git tree — a nodemap
+     * `directory:` entry's listing derived with no extra API call. Skips
+     * dotfile-named children, mirroring the local source's `listNodemapDir`.
+     */
+    private listNodemapDirFromTree;
+    private fetchContentModel;
+}
+
+/** Options controlling how a {@link FileSystemSource} interprets a directory. */
+interface FileSystemSourceOptions {
+    /**
+     * `owner/name` slug used for file-node identity. Defaults to the root
+     * directory's base name (with no owner segment).
+     */
+    repo?: string;
+    /**
+     * Sub-directory (relative to the root) whose `.md` files become authored
+     * content nodes. Defaults to `'content'`. Pass `''` (or `'.'`) to treat
+     * **top-level** `.md` files in the root itself as authored content (the
+     * legacy root-scan convention) — `README.md` still stays the repo readme.
+     */
+    contentPath?: string;
+    /**
+     * Sub-directory (relative to the root) holding structured content-model
+     * files. Defaults to `'content-model'`.
+     */
+    contentModelPath?: string;
+    /**
+     * Directory names to skip while walking (in addition to the always-skipped
+     * `.git`, `node_modules`, and `dist`).
+     */
+    ignore?: string[];
+    /**
+     * Whether the walked file tree is exposed as `RepoData.tree` (which the
+     * unified loader turns into structural file/dir/repo-root nodes via
+     * `FilesProvider`). Defaults to `true` (byte-identical to prior behavior).
+     * Set `false` for a **content-only** graph — authored content + provider
+     * entities, with none of the file-tree scaffolding nodes. `listFiles` and
+     * authored-content ingestion are unaffected; only the emitted `tree` (and the
+     * `retrieve`/`get` resource surface derived from it) is suppressed.
+     */
+    includeFileTree?: boolean;
+}
+declare class FileSystemSource implements RepoSource {
+    readonly id = "filesystem";
+    readonly name = "File System";
+    /** A local snapshot read — read is the only possible affordance. */
+    readonly possibleAffordances: Affordance[];
+    private readonly rootDir;
+    private readonly repo;
+    private readonly contentPath;
+    private readonly contentModelPath;
+    private readonly ignore;
+    private readonly includeFileTree;
+    private cache;
+    constructor(rootDir: string, options?: FileSystemSourceOptions);
+    getRepoData(): Promise<RepoData>;
+    private readRepoData;
+    /** Read one repo-relative file as UTF-8. */
+    private read;
+    /** Read one repo-relative file as UTF-8, returning `null` when missing/unreadable. */
+    private readSafe;
+    /** Read `nodemap.yaml`/`nodemap.yml` from the repo root, or `null` if neither exists. */
+    private readNodemapRaw;
+    /** Read `${contentPath}/config.yaml`(`.yml`), falling back to a root-level `config.yaml`. */
+    private readConfigRaw;
+    /**
+     * Read the raw contents of the dedicated theme file referenced by
+     * `config.theme.themesFile`, mirroring the old generator's `readThemeFile`.
+     * `null` when no `themesFile` is configured, the config can't be parsed, the
+     * path escapes the repo root, or the file is missing — a safe no-op.
+     */
+    private resolveThemeFileRaw;
+    /**
+     * One-level directory listing (with file sizes) for a nodemap `directory:`
+     * entry — distinct from `walk()`, which is recursive and does not stat
+     * files. Mirrors the old generator's `listDir`.
+     */
+    private listNodemapDir;
+    /** Convert an absolute path under the root into a POSIX repo-relative path. */
+    private toRepoRelative;
+    /**
+     * Recursively enumerate the root directory into blob/tree entries with
+     * POSIX-separated, repo-relative paths (sorted for determinism). Skips
+     * dotfiles/dot-directories (except `.github`, which the StructuralProvider
+     * reads) in addition to the always-ignored directories — mirrors the old
+     * generator's `walkFileSystem` (anokye-labs/kbexplorer-engine#23).
+     */
+    private walk;
+    retrieve(query: ResourceQuery): Promise<Resource[]>;
+    get(href: string): Promise<Resource | undefined>;
+    private fileResource;
+}
+
+export { CacheStore, FileSystemSource, type FileSystemSourceOptions, GitHubApiSource, ManifestSource, RepoData, RepoManifest, RepoSource, type ResolutionPreset };