@anokye-labs/kbexplorer-engine 0.1.0

package/dist/sources.cjs

@@ -0,0 +1,1191 @@
+'use strict';
+
+var kbexplorerCore = require('@anokye-labs/kbexplorer-core');
+var marked = require('marked');
+require('sanitize-html');
+var yaml = require('yaml');
+var promises = require('fs/promises');
+var path = require('path');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var yaml__default = /*#__PURE__*/_interopDefault(yaml);
+
+// src/glob.ts
+function globToRegex(pattern) {
+  let re = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === "*" && pattern[i + 1] === "*") {
+      re += ".*";
+      i += 1;
+      if (pattern[i + 1] === "/") i += 1;
+    } else if (c === "*") {
+      re += "[^/]*";
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (".+^${}()|[]\\".includes(c)) {
+      re += "\\" + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+// src/sources/manifest-source.ts
+var ManifestSource = class {
+  id = "manifest";
+  name = "Repo Manifest";
+  /** A manifest is a frozen snapshot — read is the only possible affordance. */
+  possibleAffordances = ["read"];
+  manifest;
+  config;
+  constructor(manifest, config) {
+    this.manifest = manifest;
+    this.config = config;
+  }
+  async getRepoData() {
+    const manifest = this.manifest;
+    const listFiles = async (pattern) => {
+      const regex = globToRegex(pattern);
+      return Object.keys(manifest.nodemapFiles ?? {}).filter((p) => regex.test(p));
+    };
+    const data = {
+      repo: this.config.source.repo,
+      tree: manifest.tree,
+      authoredContent: manifest.authoredContent,
+      nodemapRaw: manifest.nodemapRaw ?? null,
+      listFiles,
+      issues: manifest.issues,
+      pullRequests: manifest.pullRequests,
+      commits: manifest.commits,
+      branches: manifest.branches ?? [],
+      repoMetadata: manifest.repoMetadata ?? null,
+      releases: manifest.releases ?? [],
+      structuralFiles: manifest.structuralFiles ?? {},
+      structuredNodeMapRaw: manifest.structuredNodeMapRaw ?? null,
+      contentModel: manifest.contentModel ?? null,
+      readme: manifest.readme,
+      themeFileRaw: manifest.themeFileRaw ?? null
+    };
+    if (manifest.nodemapFiles !== void 0) data.nodemapFiles = manifest.nodemapFiles;
+    if (manifest.nodemapDirs !== void 0) {
+      data.nodemapDirs = manifest.nodemapDirs;
+    }
+    return data;
+  }
+  /**
+   * 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.
+   */
+  async retrieve(query) {
+    const kind = query.kind;
+    const out = [];
+    if (!kind || kind === "file" || kind === "tree") {
+      for (const item of this.manifest.tree) {
+        if (kind === "file" && item.type !== "blob") continue;
+        if (kind === "tree" && item.type !== "tree") continue;
+        out.push(this.fileResource(item));
+      }
+    }
+    if (!kind || kind === "issue") {
+      for (const issue of this.manifest.issues) {
+        out.push(this.issueResource(issue.number, issue.title));
+      }
+    }
+    return out;
+  }
+  async get(href) {
+    const all = await this.retrieve({});
+    return all.find((r) => r.href === href);
+  }
+  fileResource(item) {
+    return {
+      href: `git://${this.config.source.repo}/${item.path}`,
+      kind: item.type === "tree" ? "tree" : "file",
+      affordances: ["read"],
+      links: [{ rel: "self", href: `git://${this.config.source.repo}/${item.path}` }],
+      body: { path: item.path }
+    };
+  }
+  issueResource(number, title) {
+    return {
+      href: `github://${this.config.source.repo}/issues/${number}`,
+      kind: "issue",
+      affordances: ["read"],
+      links: [{ rel: "self", href: `github://${this.config.source.repo}/issues/${number}` }],
+      body: { number, title }
+    };
+  }
+};
+
+// src/github-client.ts
+var GITHUB_ENDPOINT_PATTERNS = [
+  "contents/",
+  "git/trees/",
+  "issues",
+  "pulls",
+  "commits",
+  "releases",
+  "branches",
+  "languages"
+];
+var DEFAULT_GH_API_BASE = "https://api.github.com";
+function resolveApiBase(env) {
+  return env?.VITE_GH_API_BASE ?? DEFAULT_GH_API_BASE;
+}
+async function ghFetch(path, env, etag) {
+  const headers = {
+    Accept: "application/vnd.github.v3+json"
+  };
+  const token = env?.GITHUB_TOKEN ?? env?.GH_TOKEN;
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const res = await fetch(`${resolveApiBase(env)}${path}`, { headers });
+  if (res.status === 304) {
+    throw new NotModifiedError();
+  }
+  if (res.status === 403 && res.headers.get("X-RateLimit-Remaining") === "0") {
+    const reset = res.headers.get("X-RateLimit-Reset");
+    throw new RateLimitError(reset ? new Date(Number(reset) * 1e3) : void 0);
+  }
+  if (!res.ok) {
+    throw new GitHubApiError(res.status, await res.text());
+  }
+  const data = await res.json();
+  const responseEtag = res.headers.get("ETag");
+  return responseEtag ? { data, etag: responseEtag } : { data };
+}
+var NotModifiedError = class extends Error {
+  constructor() {
+    super("Not modified");
+    this.name = "NotModifiedError";
+  }
+};
+var RateLimitError = class extends Error {
+  resetAt;
+  constructor(resetAt) {
+    super(`GitHub API rate limit exceeded${resetAt ? `. Resets at ${resetAt.toISOString()}` : ""}`);
+    this.name = "RateLimitError";
+    if (resetAt) this.resetAt = resetAt;
+  }
+};
+var GitHubApiError = class extends Error {
+  status;
+  constructor(status, body) {
+    super(`GitHub API error ${status}: ${body}`);
+    this.name = "GitHubApiError";
+    this.status = status;
+  }
+};
+async function fetchFile(source, path, env, cache) {
+  const branch = source.branch ?? "main";
+  const key = `file:${source.owner}/${source.repo}:${path}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const { data } = await ghFetch(
+    `/repos/${source.owner}/${source.repo}/contents/${path}?ref=${branch}`,
+    env
+  );
+  const binary = atob(data.content);
+  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  const decoded = new TextDecoder().decode(bytes);
+  cache?.set(key, decoded);
+  return decoded;
+}
+async function fetchTree(source, path, env, cache) {
+  const branch = source.branch ?? "main";
+  const key = `tree:${source.owner}/${source.repo}:${path ?? ""}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const { data } = await ghFetch(
+    `/repos/${source.owner}/${source.repo}/git/trees/${branch}?recursive=1`,
+    env
+  );
+  const items = path ? data.tree.filter((item) => item.path.startsWith(path + "/")) : data.tree;
+  cache?.set(key, items);
+  return items;
+}
+async function fetchIssues(source, env, cache) {
+  const key = `issues:${source.owner}/${source.repo}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const allIssues = [];
+  let page = 1;
+  const perPage = 100;
+  while (true) {
+    const { data } = await ghFetch(
+      `/repos/${source.owner}/${source.repo}/issues?state=all&per_page=${perPage}&page=${page}`,
+      env
+    );
+    const issues = data.filter((i) => !i.pull_request);
+    allIssues.push(...issues);
+    if (data.length < perPage) break;
+    page++;
+  }
+  cache?.set(key, allIssues);
+  return allIssues;
+}
+async function fetchPullRequests(source, env, cache) {
+  const key = `prs:${source.owner}/${source.repo}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const allPRs = [];
+  let page = 1;
+  const perPage = 100;
+  while (true) {
+    const { data } = await ghFetch(
+      `/repos/${source.owner}/${source.repo}/pulls?state=all&per_page=${perPage}&page=${page}`,
+      env
+    );
+    allPRs.push(...data);
+    if (data.length < perPage) break;
+    page++;
+  }
+  cache?.set(key, allPRs);
+  return allPRs;
+}
+async function fetchCommits(source, count = 30, env, cache) {
+  const key = `commits:${source.owner}/${source.repo}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const branch = source.branch ?? "main";
+  const { data } = await ghFetch(
+    `/repos/${source.owner}/${source.repo}/commits?sha=${branch}&per_page=${count}`,
+    env
+  );
+  cache?.set(key, data);
+  return data;
+}
+async function fetchReleases(source, limit = 30, env, cache) {
+  const key = `releases:${source.owner}/${source.repo}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const { data } = await ghFetch(`/repos/${source.owner}/${source.repo}/releases?per_page=${limit}`, env);
+  const releases = data.filter((r) => !r.draft).sort((a, b) => new Date(b.published_at ?? 0).getTime() - new Date(a.published_at ?? 0).getTime()).slice(0, limit).map((r) => ({
+    tag_name: r.tag_name ?? "",
+    name: r.name ?? r.tag_name ?? "",
+    body: r.body ?? "",
+    html_url: r.html_url ?? "",
+    published_at: r.published_at ?? "",
+    prerelease: r.prerelease ?? false
+  }));
+  cache?.set(key, releases);
+  return releases;
+}
+async function fetchFiles(source, paths, env, cache) {
+  const results = /* @__PURE__ */ new Map();
+  const settled = await Promise.allSettled(
+    paths.map(async (path) => {
+      const content = await fetchFile(source, path, env, cache);
+      return { path, content };
+    })
+  );
+  for (const result of settled) {
+    if (result.status === "fulfilled") {
+      results.set(result.value.path, result.value.content);
+    }
+  }
+  return results;
+}
+async function fetchBranches(source, env, cache) {
+  const key = `branches:${source.owner}/${source.repo}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const all = [];
+  let page = 1;
+  const perPage = 100;
+  while (true) {
+    const { data } = await ghFetch(
+      `/repos/${source.owner}/${source.repo}/branches?per_page=${perPage}&page=${page}`,
+      env
+    );
+    all.push(...data.map((b) => ({ name: b.name, protected: b.protected ?? false })));
+    if (data.length < perPage) break;
+    page++;
+  }
+  cache?.set(key, all);
+  return all;
+}
+async function fetchRepoMetadata(source, env, cache) {
+  const key = `repoMetadata:${source.owner}/${source.repo}`;
+  const hit = cache?.get(key);
+  if (hit !== void 0) return hit;
+  const [{ data: repo }, languagesMap] = await Promise.all([
+    ghFetch(`/repos/${source.owner}/${source.repo}`, env),
+    ghFetch(`/repos/${source.owner}/${source.repo}/languages`, env).then((r) => r.data).catch(() => ({}))
+  ]);
+  const languages = Object.entries(languagesMap).sort((a, b) => b[1] - a[1]).map(([name, size]) => ({ name, size }));
+  const metadata = {
+    name: repo.name ?? "",
+    description: repo.description ?? "",
+    html_url: repo.html_url ?? "",
+    homepage: repo.homepage ?? "",
+    default_branch: repo.default_branch ?? "main",
+    stargazers_count: repo.stargazers_count ?? 0,
+    forks_count: repo.forks_count ?? 0,
+    private: repo.private ?? false,
+    topics: repo.topics ?? [],
+    primary_language: repo.language ?? "",
+    languages,
+    owner: {
+      login: repo.owner?.login ?? "",
+      avatar_url: repo.owner?.avatar_url ?? ""
+    }
+  };
+  cache?.set(key, metadata);
+  return metadata;
+}
+new marked.Marked();
+kbexplorerCore.resolveAccessExclusion(kbexplorerCore.DEFAULT_ACCESS_EXCLUSION);
+
+// src/default-config.ts
+var DEFAULT_CONFIG = {
+  title: "kbexplorer",
+  subtitle: "Interactive Knowledge Base Explorer",
+  author: "Anokye Labs",
+  source: { owner: "anokye-labs", repo: "kbexplorer", path: "content", branch: "main" },
+  clusters: {
+    // Each cluster may also carry an optional `tokens` delta (Fluent token name
+    // → CSS value, same shape as theme.tokens) to shift only that cluster's
+    // scoped surfaces (cards/badges/reading header). Omitted here so defaults
+    // inherit the active global theme unchanged.
+    feature: { name: "Feature", color: "#4A9CC8" },
+    task: { name: "Task", color: "#8CB050" },
+    bug: { name: "Bug", color: "#C04040" },
+    epic: { name: "Epic", color: "#E8A838" },
+    code: { name: "Code", color: "#9A8A78" },
+    docs: { name: "Documentation", color: "#D4A050" },
+    "pull-request": { name: "Pull Request", color: "#A86FDF" },
+    commits: { name: "Commits", color: "#5A98A8" },
+    releases: { name: "Releases", color: "#F78166" }
+  },
+  visuals: {
+    mode: "emoji",
+    fallback: "emoji"
+  },
+  theme: {
+    default: "dark",
+    font: {
+      heading: "'Segoe UI Variable', 'Segoe UI', system-ui, sans-serif",
+      body: "'Segoe UI Variable', 'Segoe UI', system-ui, sans-serif",
+      mono: "'Cascadia Code', 'Cascadia Mono', Consolas, monospace"
+    }
+    // brand / tokens / themes are optional, additive overrides (see KBConfig.theme).
+    // Left unset by default so the built-in dark/light/sepia themes are unchanged.
+    // themesFile (also unset by default) may point at a dedicated theme file in the
+    // host repo (e.g. "content/themes/extra.yaml"); when set it is fetched at runtime
+    // like config.yaml and its named themes are merged into the THEME_MAP, overriding
+    // any inline theme.themes of the same name. Unset means no fetch, no behavior change.
+    // moduleUrl (also unset by default) is the most powerful escape hatch: a
+    // security-sensitive opt-in that dynamically import()s a host-provided ESM JS
+    // module exporting a Fluent Theme / BrandVariants and registers it into the
+    // THEME_MAP. Off by default, meaning no import, pure no-op. Only set it for a
+    // module you trust (ideally self-hosted in this repo) and tighten CSP accordingly
+    // — see the theming docs' CSP note.
+  },
+  graph: {
+    physics: true,
+    layout: "force-atlas-2"
+  },
+  features: {
+    hud: true,
+    minimap: true,
+    readingTools: true,
+    keyboardNav: true,
+    sparkAnimation: false,
+    search: true
+  }
+  // branding omitted by default — host repos may set branding.logo (a repo-relative
+  // image path) to render a logo on the HomePage hero and HUD header, and
+  // branding.favicon (a repo-relative image path) to swap the favicon at
+  // runtime, and branding.css (a repo-relative path or URL) to inject a raw CSS
+  // override sheet last in <head> for full control over --colorNeutral*/
+  // --colorBrand*/--kbe-* variables. Text title and the static /favicon.svg are
+  // used as graceful fallbacks; branding.css is unset by default so nothing is
+  // injected.
+};
+
+// src/parser.ts
+async function loadConfig(source, env, cache) {
+  try {
+    const raw = await fetchFile(
+      source,
+      source.path ? `${source.path}/config.yaml` : "content/config.yaml",
+      env,
+      cache
+    );
+    const parsed = yaml__default.default.parse(raw);
+    return { ...DEFAULT_CONFIG, ...parsed, source };
+  } catch {
+    return { ...DEFAULT_CONFIG, source };
+  }
+}
+
+// src/structured-content.ts
+var DEFAULT_STRUCTURED_CONTENT_PATH = "content-model";
+function normalizeRepoRelativeDir(raw) {
+  if (typeof raw !== "string") return null;
+  let value = raw.trim().replace(/\\/g, "/");
+  while (value.startsWith("./")) value = value.slice(2);
+  value = value.replace(/\/+$/g, "");
+  if (!value || /^[a-zA-Z]:\//.test(value) || value.startsWith("/") || value.includes("://") || value === ".." || value.startsWith("../") || value.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    return null;
+  }
+  return value;
+}
+function resolveStructuredContentPath(config, env) {
+  const engineEnv = env ?? {};
+  const envValue = engineEnv.VITE_KB_STRUCTURED_CONTENT_PATH ?? engineEnv.VITE_KB_CONTENT_MODEL_PATH;
+  const normalizedEnv = normalizeRepoRelativeDir(envValue);
+  if (normalizedEnv) return normalizedEnv;
+  const cfg = config;
+  const configured = cfg.structuredContent?.path ?? cfg.contentModel?.path;
+  const normalizedConfig = normalizeRepoRelativeDir(configured);
+  return normalizedConfig ?? DEFAULT_STRUCTURED_CONTENT_PATH;
+}
+function hasExplicitStructuredContentPath(config, env) {
+  const engineEnv = env ?? {};
+  const envValue = engineEnv.VITE_KB_STRUCTURED_CONTENT_PATH ?? engineEnv.VITE_KB_CONTENT_MODEL_PATH;
+  if (normalizeRepoRelativeDir(envValue)) return true;
+  const cfg = config;
+  const configured = cfg.structuredContent?.path ?? cfg.contentModel?.path;
+  return normalizeRepoRelativeDir(configured) !== null;
+}
+function globToRegex2(pattern) {
+  let re = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === "*" && pattern[i + 1] === "*") {
+      re += ".*";
+      i += 1;
+      if (pattern[i + 1] === "/") i += 1;
+    } else if (c === "*") {
+      re += "[^/]*";
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (".+^${}()|[]\\".includes(c)) {
+      re += "\\" + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+function matchesAnyGlob(path, patterns) {
+  return patterns.some((p) => globToRegex2(p).test(path));
+}
+async function collectNodemapData(nodemapRaw, tree, readFile2, listDirectory) {
+  let map;
+  try {
+    map = yaml__default.default.parse(nodemapRaw);
+  } catch {
+    return { nodemapFiles: {}, nodemapDirs: {} };
+  }
+  if (!map?.nodes?.length) return { nodemapFiles: {}, nodemapDirs: {} };
+  const nodemapFiles = {};
+  const nodemapDirs = {};
+  const expandGlob = (pattern, exclude) => {
+    const regex = globToRegex2(pattern);
+    let matches = tree.filter((e) => e.type === "blob" && regex.test(e.path)).map((e) => e.path);
+    if (exclude?.length) {
+      matches = matches.filter((p) => !matchesAnyGlob(p, exclude));
+    }
+    return matches;
+  };
+  for (const entry of map.nodes) {
+    if (entry.file) {
+      const content = await readFile2(entry.file);
+      if (content !== null) nodemapFiles[entry.file] = content;
+    }
+    if (entry.files) {
+      for (const f of entry.files) {
+        const content = await readFile2(f);
+        if (content !== null) nodemapFiles[f] = content;
+      }
+    }
+    if (entry.glob && entry.each === "file") {
+      for (const match of expandGlob(entry.glob, entry.exclude)) {
+        const content = await readFile2(match);
+        if (content !== null) nodemapFiles[match] = content;
+      }
+    }
+    if (entry.directory) {
+      nodemapDirs[entry.directory] = await listDirectory(entry.directory);
+    }
+  }
+  return { nodemapFiles, nodemapDirs };
+}
+
+// src/sources/github-api-source.ts
+function isStructuralPath(path) {
+  return path.startsWith(".github/") || /(^|\/)CODEOWNERS$/.test(path);
+}
+var MAX_STRUCTURAL_FILE_SIZE = 256 * 1024;
+async function fetchStructuredNodeMap(source, env, cache) {
+  for (const name of ["structured-node-map.yaml", "structured-node-map.yml"]) {
+    try {
+      return await fetchFile(source, name, env, cache);
+    } catch {
+    }
+  }
+  return null;
+}
+async function fetchNodemapRaw(source, env, cache) {
+  for (const name of ["nodemap.yaml", "nodemap.yml"]) {
+    try {
+      return await fetchFile(source, name, env, cache);
+    } catch {
+    }
+  }
+  return null;
+}
+var GitHubApiSource = class {
+  id = "github-api";
+  name = "GitHub API";
+  /** Advisory universe; authoritative affordances live on each retrieval. */
+  possibleAffordances = ["read", "write", "stage", "comment", "close", "merge"];
+  fetchPromise = null;
+  source;
+  preset;
+  env;
+  cache;
+  constructor(source, preset = "standard", env, cache) {
+    this.source = source;
+    this.preset = preset;
+    this.env = env;
+    this.cache = cache;
+  }
+  /** The locator of this repo's staging area (git index). */
+  get stagingHref() {
+    return `git://${this.source.repo}/.git/index`;
+  }
+  /** Fetch (memoized) so `resolveConfig` + `getRepoData` share one round-trip. */
+  fetch() {
+    if (!this.fetchPromise) this.fetchPromise = this.fetchGitHubData();
+    return this.fetchPromise;
+  }
+  /** Resolve the config without re-fetching. */
+  async resolveConfig() {
+    return (await this.fetch()).config;
+  }
+  async resolveThemeFileRaw() {
+    return (await this.fetch()).themeFileRaw;
+  }
+  async getRepoData() {
+    const data = await this.fetch();
+    return {
+      repo: this.source.repo,
+      tree: data.tree,
+      authoredContent: data.authoredContent,
+      nodemapRaw: data.nodemapRaw,
+      // `nodemapFiles`/`nodemapDirs` are omitted (rather than assigned empty
+      // objects) when there's nothing to report — this package enables
+      // exactOptionalPropertyTypes, and the loader/manifest convention is to
+      // leave optional fields unset rather than emit noisy `{}`.
+      ...Object.keys(data.nodemapFiles).length > 0 ? { nodemapFiles: data.nodemapFiles } : {},
+      ...Object.keys(data.nodemapDirs).length > 0 ? { nodemapDirs: data.nodemapDirs } : {},
+      listFiles: async () => [],
+      issues: data.issues,
+      // Reproduce the former remote shaping: no head_branch (so WorkProvider
+      // emits no branch connections), user/assignees retained for people.
+      // (user/assignees are set conditionally because this package's config
+      // enables exactOptionalPropertyTypes — an explicit `undefined` value is
+      // not assignable to the optional target fields.)
+      pullRequests: data.pullRequests.map((pr) => {
+        const mapped = {
+          number: pr.number,
+          title: pr.title,
+          body: pr.body ?? "",
+          state: pr.state,
+          labels: pr.labels.map((l) => ({ name: l.name, color: l.color ?? "" })),
+          html_url: pr.html_url,
+          created_at: pr.created_at,
+          updated_at: pr.updated_at
+        };
+        if (pr.user) mapped.user = pr.user;
+        if (pr.assignees) mapped.assignees = pr.assignees;
+        return mapped;
+      }),
+      commits: data.commits,
+      branches: data.branches,
+      repoMetadata: data.repoMetadata,
+      releases: data.releases,
+      structuralFiles: data.structuralFiles,
+      structuredNodeMapRaw: data.structuredNodeMapRaw,
+      contentModel: data.contentModel ?? null,
+      readme: data.readme,
+      themeFileRaw: data.themeFileRaw
+    };
+  }
+  // ── Formal resource surface (Git ≠ GitHub, per-retrieval affordances) ─────
+  async retrieve(query) {
+    const data = await this.fetch();
+    const kind = query.kind;
+    const worktree = query.worktree === true;
+    const staged = query.staged === true;
+    const out = [];
+    if (kind === "staging-area") {
+      out.push(this.stagingAreaResource());
+      return out;
+    }
+    if (!kind || kind === "file" || kind === "tree") {
+      for (const item of data.tree) {
+        if (kind === "file" && item.type !== "blob") continue;
+        if (kind === "tree" && item.type !== "tree") continue;
+        out.push(this.gitFileResource(item, { worktree, staged }));
+      }
+    }
+    if (!kind || kind === "commit") {
+      for (const c of data.commits) out.push(this.commitResource(c));
+    }
+    if (!kind || kind === "issue") {
+      for (const issue of data.issues) out.push(this.issueResource(issue));
+    }
+    if (!kind || kind === "pull-request") {
+      for (const pr of data.pullRequests) out.push(this.pullRequestResource(pr));
+    }
+    if (!kind || kind === "release") {
+      for (const r of data.releases) out.push(this.releaseResource(r));
+    }
+    return out;
+  }
+  async get(href) {
+    if (href === this.stagingHref) return this.stagingAreaResource();
+    const all = await this.retrieve({});
+    return all.find((r) => r.href === href);
+  }
+  /**
+   * 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.
+   */
+  gitFileResource(item, ctx) {
+    const href = `git://${this.source.repo}/${item.path}`;
+    const affordances = ctx.worktree || ctx.staged ? ["read", "write", "stage"] : ["read"];
+    const links = [{ rel: "self", href }];
+    if (ctx.staged) {
+      links.push({ rel: kbexplorerCore.STAGING_AREA_REL, href: this.stagingHref });
+    }
+    return { href, kind: item.type === "tree" ? "tree" : "file", affordances, links, body: { path: item.path } };
+  }
+  stagingAreaResource() {
+    return {
+      href: this.stagingHref,
+      kind: "staging-area",
+      affordances: ["read", "stage"],
+      links: [{ rel: "self", href: this.stagingHref }],
+      body: { repo: this.source.repo }
+    };
+  }
+  commitResource(c) {
+    const href = `git://${this.source.repo}/commit/${c.sha}`;
+    return {
+      href,
+      kind: "commit",
+      affordances: ["read"],
+      links: [{ rel: "self", href }],
+      body: { sha: c.sha, message: c.commit.message }
+    };
+  }
+  issueResource(issue) {
+    const href = `github://${this.source.repo}/issues/${issue.number}`;
+    return {
+      href,
+      kind: "issue",
+      affordances: ["read", "comment", "close"],
+      links: [{ rel: "self", href }],
+      body: { number: issue.number, title: issue.title, state: issue.state }
+    };
+  }
+  pullRequestResource(pr) {
+    const href = `github://${this.source.repo}/pull/${pr.number}`;
+    return {
+      href,
+      kind: "pull-request",
+      affordances: ["read", "comment", "close", "merge"],
+      links: [{ rel: "self", href }],
+      body: { number: pr.number, title: pr.title, state: pr.state }
+    };
+  }
+  releaseResource(r) {
+    const href = `github://${this.source.repo}/releases/${r.tag_name}`;
+    return {
+      href,
+      kind: "release",
+      affordances: ["read"],
+      links: [{ rel: "self", href }],
+      body: { tag: r.tag_name }
+    };
+  }
+  // ── Data path (moved verbatim from the former remote loader) ──────────────
+  async fetchGitHubData() {
+    const source = this.source;
+    const preset = this.preset;
+    const env = this.env;
+    const cache = this.cache;
+    const config = await loadConfig(source, env, cache);
+    const themeFilePromise = config.theme?.themesFile ? fetchFile(source, config.theme.themesFile, env, cache).catch(() => null) : Promise.resolve(null);
+    const [issues, readme, releases, themeFileRaw, branches, repoMetadata, nodemapRaw] = await Promise.all([
+      fetchIssues(source, env, cache).catch(() => []),
+      fetchFile(source, "README.md", env, cache).catch(() => null),
+      fetchReleases(source, 30, env, cache).catch(() => []),
+      themeFilePromise,
+      fetchBranches(source, env, cache).catch(() => []),
+      fetchRepoMetadata(source, env, cache).catch(() => null),
+      fetchNodemapRaw(source, env, cache)
+    ]);
+    let tree = [];
+    let pullRequests = [];
+    let commits = [];
+    const authoredContent = {};
+    const structuralFiles = {};
+    let structuredNodeMapRaw = null;
+    let contentModel = null;
+    let nodemapFiles = {};
+    let nodemapDirs = {};
+    if (preset === "standard" || preset === "full") {
+      const [treeResult, prResult] = await Promise.all([
+        fetchTree(source, void 0, env, cache).catch(() => []),
+        fetchPullRequests(source, env, cache).catch(() => [])
+      ]);
+      tree = treeResult;
+      pullRequests = prResult;
+      if (config.source.path) {
+        try {
+          const contentTree = await fetchTree(source, config.source.path, env, cache);
+          const mdFiles = contentTree.filter((item) => item.type === "blob" && item.path.endsWith(".md")).map((item) => item.path);
+          const files = await fetchFiles(source, mdFiles, env, cache);
+          for (const [path, content] of files) {
+            authoredContent[path] = content;
+          }
+        } catch {
+        }
+      }
+      contentModel = await this.fetchContentModel(config);
+      try {
+        const structuralPaths = tree.filter(
+          (item) => item.type === "blob" && isStructuralPath(item.path) && !(typeof item.size === "number" && item.size > MAX_STRUCTURAL_FILE_SIZE)
+        ).map((item) => item.path);
+        if (structuralPaths.length > 0) {
+          const files = await fetchFiles(source, structuralPaths, env, cache);
+          for (const [path, content] of files) {
+            if (content.length > MAX_STRUCTURAL_FILE_SIZE) continue;
+            structuralFiles[path] = content;
+          }
+        }
+        structuredNodeMapRaw = await fetchStructuredNodeMap(source, env, cache);
+      } catch {
+      }
+      if (nodemapRaw !== null) {
+        try {
+          const collected = await collectNodemapData(
+            nodemapRaw,
+            tree,
+            (path) => fetchFile(source, path, env, cache).catch(() => null),
+            (dir) => this.listNodemapDirFromTree(tree, dir)
+          );
+          nodemapFiles = collected.nodemapFiles;
+          nodemapDirs = collected.nodemapDirs;
+        } catch {
+        }
+      }
+    }
+    if (preset === "full") {
+      commits = await fetchCommits(source, 50, env, cache).catch(() => []);
+    }
+    return {
+      issues,
+      pullRequests,
+      tree,
+      readme,
+      commits,
+      releases,
+      branches,
+      repoMetadata,
+      authoredContent,
+      structuralFiles,
+      structuredNodeMapRaw,
+      contentModel,
+      config,
+      themeFileRaw: themeFileRaw ?? null,
+      nodemapRaw,
+      nodemapFiles,
+      nodemapDirs
+    };
+  }
+  /**
+   * 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`.
+   */
+  listNodemapDirFromTree(tree, dir) {
+    const prefix = `${dir}/`;
+    const out = tree.filter((item) => {
+      if (!item.path.startsWith(prefix)) return false;
+      const rest = item.path.slice(prefix.length);
+      if (rest === "" || rest.includes("/")) return false;
+      return !rest.startsWith(".");
+    });
+    return Promise.resolve(out);
+  }
+  async fetchContentModel(config) {
+    const env = this.env;
+    const cache = this.cache;
+    const root = resolveStructuredContentPath(config, env);
+    const explicitPath = hasExplicitStructuredContentPath(config, env);
+    try {
+      const contentModelTree = await fetchTree(this.source, root, env, cache);
+      const paths = contentModelTree.filter((item) => item.type === "blob").map((item) => item.path).filter((path) => !path.slice(root.length + 1).split("/").some((segment) => segment.startsWith(".")));
+      if (paths.length === 0) {
+        if (explicitPath) {
+          console.warn(`[github-api-source] No structured content files found at configured path ${root}`);
+        }
+        return null;
+      }
+      const files = await fetchFiles(this.source, paths, env, cache);
+      const sourceFiles = {};
+      for (const [path, content] of files) {
+        const relativePath = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+        sourceFiles[relativePath] = content;
+      }
+      if (Object.keys(sourceFiles).length === 0) {
+        if (explicitPath) {
+          console.warn(`[github-api-source] Structured content path ${root} was listed but no files could be fetched`);
+        }
+        return null;
+      }
+      return { root, files: sourceFiles };
+    } catch (error) {
+      console.warn(`[github-api-source] Failed to fetch structured content from ${root}:`, error);
+      return null;
+    }
+  }
+};
+
+// src/sources/build-manifest.ts
+function toManifestPullRequest(pr) {
+  const mapped = {
+    number: pr.number,
+    title: pr.title,
+    body: pr.body,
+    state: pr.state,
+    labels: pr.labels,
+    html_url: pr.html_url,
+    created_at: pr.created_at,
+    updated_at: pr.updated_at
+  };
+  if (pr.head_branch !== void 0) mapped.head_branch = pr.head_branch;
+  return mapped;
+}
+async function buildManifest(source, options = {}) {
+  const data = await source.getRepoData();
+  const manifest = {
+    configRaw: options.configRaw ?? null,
+    authoredContent: data.authoredContent,
+    tree: data.tree,
+    readme: data.readme,
+    issues: data.issues,
+    pullRequests: data.pullRequests.map(toManifestPullRequest),
+    commits: data.commits,
+    generatedAt: options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (data.branches.length > 0) manifest.branches = data.branches;
+  if (data.releases.length > 0) manifest.releases = data.releases;
+  if (data.repoMetadata) manifest.repoMetadata = data.repoMetadata;
+  if (data.nodemapRaw !== null) manifest.nodemapRaw = data.nodemapRaw;
+  if (data.nodemapFiles !== void 0) manifest.nodemapFiles = data.nodemapFiles;
+  if (data.nodemapDirs !== void 0) manifest.nodemapDirs = data.nodemapDirs;
+  if (data.structuredNodeMapRaw !== null) manifest.structuredNodeMapRaw = data.structuredNodeMapRaw;
+  if (Object.keys(data.structuralFiles).length > 0) manifest.structuralFiles = data.structuralFiles;
+  if (data.contentModel) manifest.contentModel = data.contentModel;
+  if (data.themeFileRaw) manifest.themeFileRaw = data.themeFileRaw;
+  if (options.augmentFrom) {
+    const live = await options.augmentFrom.getRepoData();
+    manifest.issues = live.issues;
+    manifest.pullRequests = live.pullRequests.map(toManifestPullRequest);
+    manifest.commits = live.commits;
+    if (live.repoMetadata !== null) manifest.repoMetadata = live.repoMetadata;
+    if (live.branches.length > 0) manifest.branches = live.branches;
+    if (live.releases.length > 0) manifest.releases = live.releases;
+  }
+  return manifest;
+}
+var ALWAYS_IGNORE = /* @__PURE__ */ new Set([".git", "node_modules", "dist"]);
+var MAX_STRUCTURAL_FILE_SIZE2 = 256 * 1024;
+function isStructuralPath2(path) {
+  return path.startsWith(".github/") || /(^|\/)CODEOWNERS$/.test(path);
+}
+var FileSystemSource = class {
+  id = "filesystem";
+  name = "File System";
+  /** A local snapshot read — read is the only possible affordance. */
+  possibleAffordances = ["read"];
+  rootDir;
+  repo;
+  contentPath;
+  contentModelPath;
+  ignore;
+  includeFileTree;
+  cache = null;
+  constructor(rootDir, options = {}) {
+    this.rootDir = path.resolve(rootDir);
+    this.repo = options.repo ?? path.basename(this.rootDir);
+    this.contentPath = options.contentPath ?? "content";
+    this.contentModelPath = options.contentModelPath ?? "content-model";
+    this.ignore = /* @__PURE__ */ new Set([...ALWAYS_IGNORE, ...options.ignore ?? []]);
+    this.includeFileTree = options.includeFileTree ?? true;
+  }
+  async getRepoData() {
+    if (!this.cache) this.cache = this.readRepoData();
+    return this.cache;
+  }
+  async readRepoData() {
+    const files = await this.walk();
+    const paths = files.map((f) => f.path);
+    const tree = this.includeFileTree ? files.map((f) => ({ path: f.path, type: f.type })) : [];
+    const authoredContent = {};
+    const structuralFiles = {};
+    const rootScan = this.contentPath === "" || this.contentPath === ".";
+    const contentPrefix = rootScan ? "" : `${this.contentPath}/`;
+    const contentModelPrefix = `${this.contentModelPath}/`;
+    const contentModelFiles = {};
+    let readme = null;
+    let structuredNodeMapRaw = null;
+    for (const file of files) {
+      if (file.type !== "blob") continue;
+      const isAuthoredMd = file.path.endsWith(".md") && file.path !== "README.md" && (rootScan ? !file.path.includes("/") : file.path.startsWith(contentPrefix));
+      if (isAuthoredMd) {
+        authoredContent[file.path] = await this.read(file.path);
+        continue;
+      }
+      if (isStructuralPath2(file.path) && (file.size ?? 0) <= MAX_STRUCTURAL_FILE_SIZE2) {
+        const content = await this.read(file.path);
+        if (content.length <= MAX_STRUCTURAL_FILE_SIZE2) structuralFiles[file.path] = content;
+        continue;
+      }
+      if (file.path.startsWith(contentModelPrefix)) {
+        const relativePath = file.path.slice(contentModelPrefix.length);
+        contentModelFiles[relativePath] = await this.read(file.path);
+        continue;
+      }
+      if (file.path === "README.md") {
+        readme = await this.read(file.path);
+        continue;
+      }
+      if (structuredNodeMapRaw === null && (file.path === "structured-node-map.yaml" || file.path === "structured-node-map.yml")) {
+        structuredNodeMapRaw = await this.read(file.path);
+      }
+    }
+    const contentModel = Object.keys(contentModelFiles).length > 0 ? { root: this.contentModelPath, files: contentModelFiles } : null;
+    const listFiles = async (pattern) => {
+      const regex = globToRegex(pattern);
+      return paths.filter((p) => regex.test(p));
+    };
+    const nodemapRaw = await this.readNodemapRaw();
+    let nodemapFiles;
+    let nodemapDirs;
+    if (nodemapRaw !== null) {
+      const collected = await collectNodemapData(
+        nodemapRaw,
+        files,
+        (path) => this.readSafe(path),
+        (dir) => this.listNodemapDir(dir)
+      );
+      nodemapFiles = collected.nodemapFiles;
+      nodemapDirs = collected.nodemapDirs;
+    }
+    const themeFileRaw = await this.resolveThemeFileRaw();
+    return {
+      repo: this.repo,
+      tree,
+      authoredContent,
+      nodemapRaw,
+      ...nodemapFiles !== void 0 ? { nodemapFiles } : {},
+      ...nodemapDirs !== void 0 ? { nodemapDirs } : {},
+      listFiles,
+      issues: [],
+      pullRequests: [],
+      commits: [],
+      // Legitimately empty/null in local mode — there is no live GitHub to
+      // fetch branches/repo metadata from (anokye-labs/kbexplorer-engine#23).
+      branches: [],
+      repoMetadata: null,
+      releases: [],
+      structuralFiles,
+      structuredNodeMapRaw,
+      contentModel,
+      readme,
+      themeFileRaw
+    };
+  }
+  /** Read one repo-relative file as UTF-8. */
+  read(repoRelative) {
+    return promises.readFile(path.join(this.rootDir, repoRelative), "utf8");
+  }
+  /** Read one repo-relative file as UTF-8, returning `null` when missing/unreadable. */
+  async readSafe(repoRelative) {
+    try {
+      return await promises.readFile(path.join(this.rootDir, repoRelative), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  /** Read `nodemap.yaml`/`nodemap.yml` from the repo root, or `null` if neither exists. */
+  async readNodemapRaw() {
+    for (const name of ["nodemap.yaml", "nodemap.yml"]) {
+      const content = await this.readSafe(name);
+      if (content !== null) return content;
+    }
+    return null;
+  }
+  /** Read `${contentPath}/config.yaml`(`.yml`), falling back to a root-level `config.yaml`. */
+  async readConfigRaw() {
+    const rootScan = this.contentPath === "" || this.contentPath === ".";
+    const contentPrefix = rootScan ? "" : `${this.contentPath}/`;
+    const candidates = [`${contentPrefix}config.yaml`, `${contentPrefix}config.yml`, "config.yaml"];
+    for (const candidate of candidates) {
+      const content = await this.readSafe(candidate);
+      if (content !== null) return content;
+    }
+    return null;
+  }
+  /**
+   * 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.
+   */
+  async resolveThemeFileRaw() {
+    const configRaw = await this.readConfigRaw();
+    if (!configRaw) return null;
+    let parsed;
+    try {
+      parsed = yaml__default.default.parse(configRaw);
+    } catch {
+      return null;
+    }
+    const themesFile = parsed?.theme?.themesFile;
+    if (!themesFile || typeof themesFile !== "string") return null;
+    if (path.isAbsolute(themesFile)) return null;
+    const abs = path.resolve(this.rootDir, themesFile);
+    const rel = path.relative(this.rootDir, abs);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+    try {
+      return await promises.readFile(abs, "utf8");
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * 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`.
+   */
+  async listNodemapDir(dirPath) {
+    const abs = path.join(this.rootDir, dirPath);
+    let entries;
+    try {
+      entries = await promises.readdir(abs, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const entryPath = dirPath ? `${dirPath}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        out.push({ path: entryPath, type: "tree" });
+      } else if (entry.isFile()) {
+        try {
+          const st = await promises.stat(path.join(abs, entry.name));
+          out.push({ path: entryPath, type: "blob", size: st.size });
+        } catch {
+          out.push({ path: entryPath, type: "blob" });
+        }
+      }
+    }
+    return out;
+  }
+  /** Convert an absolute path under the root into a POSIX repo-relative path. */
+  toRepoRelative(absolutePath) {
+    return absolutePath.slice(this.rootDir.length + 1).split(path.sep).join("/");
+  }
+  /**
+   * 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).
+   */
+  async walk() {
+    const out = [];
+    const stack = [this.rootDir];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      const entries = await promises.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".github") continue;
+        if (entry.isDirectory() && this.ignore.has(entry.name)) continue;
+        const absolutePath = path.join(dir, entry.name);
+        const repoRelative = this.toRepoRelative(absolutePath);
+        if (entry.isDirectory()) {
+          out.push({ path: repoRelative, type: "tree" });
+          stack.push(absolutePath);
+        } else if (entry.isFile()) {
+          out.push({ path: repoRelative, type: "blob" });
+        }
+      }
+    }
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+  }
+  // ── Read-only resource surface (mirrors ManifestSource) ───────────────────
+  async retrieve(query) {
+    const kind = query.kind;
+    const out = [];
+    if (!kind || kind === "file" || kind === "tree") {
+      const { tree } = await this.getRepoData();
+      for (const item of tree) {
+        if (kind === "file" && item.type !== "blob") continue;
+        if (kind === "tree" && item.type !== "tree") continue;
+        out.push(this.fileResource(item));
+      }
+    }
+    return out;
+  }
+  async get(href) {
+    const all = await this.retrieve({});
+    return all.find((r) => r.href === href);
+  }
+  fileResource(item) {
+    const href = `file://${this.repo}/${item.path}`;
+    return {
+      href,
+      kind: item.type === "tree" ? "tree" : "file",
+      affordances: ["read"],
+      links: [{ rel: "self", href }],
+      body: { path: item.path }
+    };
+  }
+};
+
+exports.FileSystemSource = FileSystemSource;
+exports.GITHUB_ENDPOINT_PATTERNS = GITHUB_ENDPOINT_PATTERNS;
+exports.GitHubApiError = GitHubApiError;
+exports.GitHubApiSource = GitHubApiSource;
+exports.ManifestSource = ManifestSource;
+exports.NotModifiedError = NotModifiedError;
+exports.RateLimitError = RateLimitError;
+exports.buildManifest = buildManifest;
+exports.fetchCommits = fetchCommits;
+exports.fetchFile = fetchFile;
+exports.fetchFiles = fetchFiles;
+exports.fetchIssues = fetchIssues;
+exports.fetchPullRequests = fetchPullRequests;
+exports.fetchReleases = fetchReleases;
+exports.fetchTree = fetchTree;