@kodiak-finance/orderly-sdk-docs 1.0.2

package/dist/chunk-EPLR7UGM.js

@@ -0,0 +1,1628 @@
+// src/constants.ts
+var API_VERSION = "2026-04-02";
+
+// src/paths.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function resolveRepoRoot(cwd = process.cwd()) {
+  const fromEnv = process.env.ORDERLY_REPO_ROOT;
+  if (fromEnv && fs.existsSync(path.join(fromEnv, "pnpm-workspace.yaml"))) {
+    return path.resolve(fromEnv);
+  }
+  let cur = path.resolve(cwd);
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(cur, "pnpm-workspace.yaml"))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  throw new Error(
+    "Could not find repo root (pnpm-workspace.yaml). Set ORDERLY_REPO_ROOT or run from the monorepo."
+  );
+}
+function aiDocsGeneratedRoot(repoRoot) {
+  return path.join(repoRoot, "apps/ai-docs/generated");
+}
+function manifestExistsAtRepoRoot(repoRoot) {
+  const nested = path.join(
+    repoRoot,
+    "apps",
+    "ai-docs",
+    "generated",
+    "manifest.json"
+  );
+  if (fs.existsSync(nested)) return true;
+  const flatManifest = path.join(repoRoot, "manifest.json");
+  const flatIdIndex = path.join(repoRoot, "indexes", "id-index.json");
+  return fs.existsSync(flatManifest) && fs.existsSync(flatIdIndex);
+}
+function resolveAiDocsRepoRoot(opts) {
+  const explicit = process.env.ORDERLY_AI_DOCS_REPO_ROOT;
+  if (explicit) {
+    const r = path.resolve(explicit);
+    if (!manifestExistsAtRepoRoot(r)) {
+      throw new Error(
+        `ORDERLY_AI_DOCS_REPO_ROOT must be a monorepo root with apps/ai-docs/generated, or a flat bundle dir with manifest.json + indexes/ (checked under ${r})`
+      );
+    }
+    return r;
+  }
+  const envRepo = process.env.ORDERLY_REPO_ROOT;
+  if (envRepo) {
+    const r = path.resolve(envRepo);
+    if (fs.existsSync(path.join(r, "pnpm-workspace.yaml")) && manifestExistsAtRepoRoot(r)) {
+      return r;
+    }
+  }
+  try {
+    const r = resolveRepoRoot();
+    if (manifestExistsAtRepoRoot(r)) return r;
+  } catch {
+  }
+  if (opts?.moduleUrl) {
+    const bundledRoot = resolveBundledSyntheticRepoRoot(opts.moduleUrl);
+    if (bundledRoot && manifestExistsAtRepoRoot(bundledRoot))
+      return bundledRoot;
+  }
+  throw new Error(
+    "Could not resolve AI docs data root. Options: set ORDERLY_AI_DOCS_REPO_ROOT to a tree with apps/ai-docs/generated, work in a monorepo after `pnpm --filter @orderly.network/ai-docs generate`, or run `pnpm --filter @orderly.network/sdk-docs sync:bundle` before using the published package."
+  );
+}
+function resolveBundledSyntheticRepoRoot(moduleUrl) {
+  const distDir = path.dirname(fileURLToPath(moduleUrl));
+  const bundledRoot = path.resolve(distDir, "..", "bundled");
+  return manifestExistsAtRepoRoot(bundledRoot) ? bundledRoot : null;
+}
+function assertSafeRelPath(rel) {
+  if (rel.includes("..")) {
+    throw new Error("INVALID_PATH_TRAVERSAL");
+  }
+}
+
+// src/bundle.ts
+import fs2 from "fs";
+import path2 from "path";
+import { z } from "zod";
+var BUNDLE_LOADER_MODULE_URL = import.meta.url;
+var ManifestSchema = z.object({
+  schemaVersion: z.string(),
+  gitSha: z.string(),
+  generatedAt: z.string(),
+  releaseVersion: z.string().nullable(),
+  artifactKinds: z.array(z.string()),
+  roots: z.object({
+    markdownRoot: z.string(),
+    generatedRoot: z.string()
+  }),
+  indexPaths: z.object({
+    idIndex: z.string(),
+    symbolIndex: z.string(),
+    packageIndex: z.string(),
+    keywordIndex: z.string(),
+    componentDocIndex: z.string().optional(),
+    chunkIndex: z.string().optional()
+  }),
+  qmd: z.record(z.string(), z.unknown()).optional(),
+  analysisStats: z.object({
+    totalSymbols: z.number(),
+    fullyResolved: z.number(),
+    degradedCount: z.number()
+  })
+}).passthrough();
+var SUPPORTED_MANIFEST_SCHEMA_MAJOR = 1;
+function parseManifestSchemaMajor(schemaVersion) {
+  if (/^\d+$/.test(schemaVersion)) return Number(schemaVersion);
+  const semverMatch = /^(\d+)\./.exec(schemaVersion);
+  return semverMatch ? Number(semverMatch[1]) : null;
+}
+function assertManifestCompatibility(manifest) {
+  const major = parseManifestSchemaMajor(manifest.schemaVersion);
+  if (major === null) {
+    throw new Error(
+      `Unsupported manifest schemaVersion "${manifest.schemaVersion}" \u2014 expected major ${SUPPORTED_MANIFEST_SCHEMA_MAJOR}`
+    );
+  }
+  if (major !== SUPPORTED_MANIFEST_SCHEMA_MAJOR) {
+    throw new Error(
+      `Incompatible manifest schema major ${major}; runtime supports ${SUPPORTED_MANIFEST_SCHEMA_MAJOR}. Regenerate artifacts with the matching ai-docs version.`
+    );
+  }
+}
+var _cache = null;
+var LEGACY_GENERATED_PREFIX = "apps/ai-docs/generated/";
+function relUnderGeneratedRoot(rel) {
+  return rel.startsWith(LEGACY_GENERATED_PREFIX) ? rel.slice(LEGACY_GENERATED_PREFIX.length) : rel;
+}
+function clearLoadBundleCache() {
+  _cache = null;
+}
+function loadBundle(repoRoot) {
+  const root = repoRoot ?? resolveAiDocsRepoRoot({ moduleUrl: BUNDLE_LOADER_MODULE_URL });
+  if (_cache && _cache.repoRoot === root) return _cache;
+  const nestedManifest = path2.join(
+    root,
+    "apps",
+    "ai-docs",
+    "generated",
+    "manifest.json"
+  );
+  const flatManifest = path2.join(root, "manifest.json");
+  let generatedRoot;
+  let manifestPath;
+  if (fs2.existsSync(nestedManifest)) {
+    generatedRoot = path2.dirname(nestedManifest);
+    manifestPath = nestedManifest;
+  } else if (fs2.existsSync(flatManifest)) {
+    const flatIdIndex = path2.join(root, "indexes", "id-index.json");
+    if (!fs2.existsSync(flatIdIndex)) {
+      throw new Error(
+        `Invalid AI docs data dir at ${root} \u2014 expected indexes/id-index.json next to manifest.json`
+      );
+    }
+    generatedRoot = root;
+    manifestPath = flatManifest;
+  } else {
+    throw new Error(
+      `Missing AI docs manifest under ${root} \u2014 run pnpm --filter @orderly.network/ai-docs generate (monorepo) or pnpm --filter @orderly.network/sdk-docs sync:bundle`
+    );
+  }
+  const manifest = ManifestSchema.parse(
+    JSON.parse(fs2.readFileSync(manifestPath, "utf8"))
+  );
+  assertManifestCompatibility(manifest);
+  const readIdx = (rel) => JSON.parse(
+    fs2.readFileSync(
+      path2.join(generatedRoot, relUnderGeneratedRoot(rel)),
+      "utf8"
+    )
+  );
+  const idIndex = readIdx(
+    manifest.indexPaths.idIndex
+  );
+  const symbolIndex = readIdx(
+    manifest.indexPaths.symbolIndex
+  );
+  const packageIndex = readIdx(
+    manifest.indexPaths.packageIndex
+  );
+  const keywordIndex = readIdx(
+    manifest.indexPaths.keywordIndex
+  );
+  let componentDocIndex = {};
+  const docRel = manifest.indexPaths.componentDocIndex;
+  if (docRel) {
+    componentDocIndex = readIdx(docRel);
+  }
+  _cache = {
+    repoRoot: root,
+    generatedRoot,
+    manifest,
+    idIndex,
+    symbolIndex,
+    packageIndex,
+    keywordIndex,
+    componentDocIndex
+  };
+  return _cache;
+}
+function readEntityJson(generatedRoot, jsonRelPath) {
+  const abs = path2.join(generatedRoot, relUnderGeneratedRoot(jsonRelPath));
+  return JSON.parse(fs2.readFileSync(abs, "utf8"));
+}
+
+// src/narrative/qmdAdapter.ts
+import { createStore, extractSnippet } from "@tobilu/qmd";
+import fs3 from "fs";
+import path3 from "path";
+var storeCache = null;
+var docMetaCache = null;
+function clearQmdStoreCache() {
+  void storeCache?.store.close().catch(() => {
+  });
+  storeCache = null;
+  docMetaCache = null;
+}
+function resolveQmdDbPath(bundle) {
+  const qmdMeta = bundle.manifest.qmd;
+  const indexRel = qmdMeta && typeof qmdMeta.indexPath === "string" ? qmdMeta.indexPath : "qmd/index.sqlite";
+  return path3.join(bundle.generatedRoot, indexRel);
+}
+async function getStore(bundle) {
+  const dbPath = resolveQmdDbPath(bundle);
+  if (!fs3.existsSync(dbPath)) return null;
+  if (storeCache?.dbPath === dbPath) return storeCache.store;
+  if (storeCache) {
+    await storeCache.store.close().catch(() => {
+    });
+    storeCache = null;
+  }
+  const store = await createStore({ dbPath });
+  storeCache = { dbPath, store };
+  return store;
+}
+function hitToNarrativeHit(row, query) {
+  const text = row.body && row.body.length > 0 ? extractSnippet(row.body, query, 800).snippet : row.title;
+  return {
+    id: row.docid,
+    path: row.displayPath || row.filepath,
+    heading: row.title,
+    text,
+    score: row.score
+  };
+}
+function normalizePackageNeedle(p) {
+  return p.toLowerCase().replace(/^@orderly\.network\//, "").replace(/^@/, "");
+}
+function normalizeToken(t) {
+  return t.toLowerCase().trim();
+}
+function parseFrontmatter(filepath) {
+  try {
+    if (!fs3.existsSync(filepath)) return {};
+    const text = fs3.readFileSync(filepath, "utf8");
+    if (!text.startsWith("---\n")) return {};
+    const end = text.indexOf("\n---\n", 4);
+    if (end <= 4) return {};
+    const block = text.slice(4, end);
+    const meta = {};
+    for (const line of block.split("\n")) {
+      const idx = line.indexOf(":");
+      if (idx <= 0) continue;
+      const key = line.slice(0, idx).trim();
+      const rawValue = line.slice(idx + 1).trim();
+      if (!rawValue) continue;
+      if (key === "domain") meta.domain = rawValue;
+      if (key === "kind") meta.kind = rawValue;
+      if (key === "docType") meta.docType = rawValue;
+      if (key === "package") meta.package = rawValue;
+      if (key === "lang") meta.lang = rawValue.toLowerCase();
+      if (key === "intentTags") {
+        meta.intentTags = rawValue.replace(/^\[|\]$/g, "").split(",").map((x) => normalizeToken(x)).filter(Boolean);
+      }
+    }
+    return meta;
+  } catch {
+    return {};
+  }
+}
+function resolveDocMetaIndexPath(bundle) {
+  const qmd = bundle.manifest.qmd;
+  const rel = qmd?.docMetaIndexPath;
+  if (typeof rel !== "string" || !rel) return null;
+  const abs = path3.join(bundle.generatedRoot, rel);
+  return fs3.existsSync(abs) ? abs : null;
+}
+function getDocMetaMap(bundle) {
+  const idx = resolveDocMetaIndexPath(bundle);
+  if (!idx) return null;
+  if (docMetaCache?.indexPath === idx) return docMetaCache.map;
+  try {
+    const map = JSON.parse(fs3.readFileSync(idx, "utf8"));
+    docMetaCache = { indexPath: idx, map };
+    return map;
+  } catch {
+    return null;
+  }
+}
+function readDocMeta(bundle, filepath, displayPath) {
+  const map = getDocMetaMap(bundle);
+  if (map) {
+    const hit = map[filepath] ?? map[displayPath];
+    if (hit) return hit;
+  }
+  return parseFrontmatter(filepath);
+}
+function toIntentTokens(query) {
+  return significantTokens(query).map((t) => normalizeToken(t));
+}
+function packageMatches(metaPackage, displayPath, packages) {
+  if (!packages?.length) return true;
+  const needles = packages.map((p2) => normalizePackageNeedle(p2));
+  const candidate = (metaPackage ?? "").toLowerCase();
+  const p = displayPath.toLowerCase();
+  return needles.some((n) => {
+    if (!n) return false;
+    return candidate.includes(n) || p.includes(n);
+  });
+}
+function kindMatches(meta, displayPath, kinds) {
+  if (!kinds?.length) return true;
+  const kindNeedles = kinds.map((k) => normalizeToken(k));
+  const hay = `${meta.kind ?? ""} ${meta.docType ?? ""} ${meta.domain ?? ""} ${displayPath}`.toLowerCase();
+  return kindNeedles.some((k) => hay.includes(k));
+}
+function isEnglishDoc(meta) {
+  if (!meta.lang) return true;
+  return meta.lang === "en";
+}
+function computeIntentBoost(row, meta, intentTokens) {
+  const p = (row.displayPath || row.filepath).toLowerCase();
+  const title = row.title.toLowerCase();
+  const domain = (meta.domain ?? "").toLowerCase();
+  const kind = (meta.kind ?? "").toLowerCase();
+  const tags = (meta.intentTags ?? []).map((x) => x.toLowerCase());
+  let boost = 0;
+  for (const tok of intentTokens) {
+    if (tok.length < 2) continue;
+    if (title.includes(tok)) boost += 0.12;
+    if (kind.includes(tok)) boost += 0.1;
+    if (domain.includes(tok)) boost += 0.1;
+    if (tags.some((t) => t.includes(tok))) boost += 0.14;
+    if (p.includes(tok)) boost += 0.06;
+  }
+  if (p.includes("packages/plugin-core/doc/guide.md")) boost += 0.12;
+  if (p.includes("packages/plugin-core/doc/tech.md")) boost += 0.12;
+  if (p.includes("packages/plugin-core/doc/injectable-targets.md"))
+    boost += 0.12;
+  if (p.includes("packages/layout-core/doc/layout_customization.md"))
+    boost += 0.12;
+  const isWorkflowDoc = p.includes("apps/ai-docs/workflows/") || p.includes("orderly-ai-docs/workflows/");
+  if (isWorkflowDoc) {
+    boost += 0.24;
+  }
+  const asksHowTo = intentTokens.some(
+    (t) => ["how", "integrate", "integration", "steps", "workflow"].includes(t)
+  );
+  const asksPluginFlow = intentTokens.some(
+    (t) => ["plugin", "layout", "host", "provider"].includes(t)
+  );
+  if (asksHowTo && kind === "workflow") {
+    boost += 0.5;
+  }
+  if (asksHowTo && asksPluginFlow && isWorkflowDoc) {
+    boost += 0.35;
+  }
+  return boost;
+}
+function fuseRows(bundle, lexRows, vecRows, query, q) {
+  const lexById = new Map(lexRows.map((r) => [r.docid, r]));
+  const vecById = new Map(vecRows.map((r) => [r.docid, r]));
+  const ids = /* @__PURE__ */ new Set([...lexById.keys(), ...vecById.keys()]);
+  const out = [];
+  const intentTokens = toIntentTokens(query);
+  for (const id of ids) {
+    const lex = lexById.get(id);
+    const vec = vecById.get(id);
+    const base = lex ?? vec;
+    if (!base) continue;
+    const displayPath = base.displayPath || base.filepath;
+    const meta = readDocMeta(bundle, base.filepath, displayPath);
+    if (!isEnglishDoc(meta)) continue;
+    if (!packageMatches(meta.package, displayPath, q.packages)) continue;
+    if (!kindMatches(meta, displayPath, q.kinds)) continue;
+    const fusedScore = (lex?.score ?? 0) * 0.65 + (vec?.score ?? 0) * 0.35 + computeIntentBoost(base, meta, intentTokens);
+    out.push({
+      ...base,
+      score: fusedScore
+    });
+  }
+  return out.sort((a, b) => b.score - a.score);
+}
+function significantTokens(query) {
+  return query.trim().split(/\s+/).filter((t) => t.length > 0 && /[\p{L}\p{N}]/u.test(t));
+}
+var QmdNarrativeRetrieval = class {
+  constructor(bundle) {
+    this.bundle = bundle;
+  }
+  async search(q) {
+    const store = await getStore(this.bundle);
+    if (!store) return [];
+    const k = q.k;
+    const fetchLimit = Math.min(120, Math.max(k * 3, 24));
+    let rows = [];
+    try {
+      const variants = q.queryVariants?.length ? q.queryVariants : [q.query];
+      const pairRows = await Promise.all(
+        variants.map(async (variant) => {
+          const [lexRows2, vecRows2] = await Promise.all([
+            store.searchLex(variant, { limit: fetchLimit }).catch(() => []),
+            store.searchVector(variant, { limit: fetchLimit }).catch(() => [])
+          ]);
+          return { lexRows: lexRows2, vecRows: vecRows2 };
+        })
+      );
+      const lexRows = pairRows.flatMap((x) => x.lexRows);
+      const vecRows = pairRows.flatMap((x) => x.vecRows);
+      rows = fuseRows(this.bundle, lexRows, vecRows, q.query, q);
+      if (rows.length < k) {
+        const tokens = significantTokens(q.query);
+        if (tokens.length > 1) {
+          for (const tok of tokens) {
+            if (rows.length >= fetchLimit) break;
+            const part = await store.searchLex(tok, { limit: fetchLimit }).catch(() => []);
+            const fusedFallback = fuseRows(
+              this.bundle,
+              [...rows],
+              part,
+              q.query,
+              q
+            );
+            rows = mergedDedupByIdScored([...rows, ...fusedFallback]);
+          }
+        }
+      }
+      rows = rows.slice(0, k);
+      return rows.map((r) => {
+        const displayPath = r.displayPath || r.filepath;
+        const meta = readDocMeta(this.bundle, r.filepath, displayPath);
+        const hit = hitToNarrativeHit(r, q.query);
+        return {
+          ...hit,
+          ...meta.domain ? { domain: meta.domain } : {},
+          ...meta.docType ? { docType: meta.docType } : {},
+          ...meta.package ? { packageName: meta.package } : {},
+          ...meta.intentTags ? { intentTags: meta.intentTags } : {},
+          ...meta.lang ? { lang: meta.lang } : {}
+        };
+      });
+    } catch {
+      return [];
+    }
+  }
+};
+function mergedDedupByIdScored(rows) {
+  const best = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    const cur = best.get(r.docid);
+    if (!cur || r.score > cur.score) {
+      best.set(r.docid, r);
+    }
+  }
+  return [...best.values()].sort((a, b) => b.score - a.score);
+}
+
+// src/envelope.ts
+function buildMetaOk(input) {
+  const {
+    bundle,
+    matchKind,
+    queryMs,
+    citations,
+    resolutionLevel,
+    degradedReason,
+    deprecations
+  } = input;
+  return {
+    gitSha: bundle.manifest.gitSha,
+    generatedAt: bundle.manifest.generatedAt,
+    queryMs,
+    matchKind,
+    apiVersion: API_VERSION,
+    citations,
+    ...resolutionLevel !== void 0 ? { resolutionLevel } : {},
+    ...degradedReason !== void 0 ? { degradedReason } : {},
+    ...deprecations !== void 0 ? { deprecations } : {}
+  };
+}
+function elapsedMs(started) {
+  return Math.round(Math.max(0, performance.now() - started));
+}
+function okResult(bundle, data, matchKind, citations, started, extra) {
+  return {
+    ok: true,
+    data,
+    meta: buildMetaOk({
+      bundle,
+      matchKind,
+      queryMs: elapsedMs(started),
+      citations,
+      ...extra
+    })
+  };
+}
+function errResult(code, message, hint, bundle) {
+  return {
+    ok: false,
+    error: { code, message, ...hint !== void 0 ? { hint } : {} },
+    meta: {
+      ...bundle ? {
+        gitSha: bundle.manifest.gitSha,
+        generatedAt: bundle.manifest.generatedAt
+      } : {},
+      apiVersion: API_VERSION
+    }
+  };
+}
+
+// src/entityResolve.ts
+function findSymbolEntryByEntityId(bundle, entityId) {
+  for (const entry of Object.values(bundle.symbolIndex)) {
+    if (entry.entityId === entityId) return entry;
+  }
+  return void 0;
+}
+function toolForKind(kind) {
+  if (kind === "hook") return "orderly_docs_get_hook";
+  if (kind === "component") return "orderly_docs_get_component";
+  if (kind === "type") return "orderly_docs_get_type";
+  return `orderly_docs_get_type (kind: ${kind})`;
+}
+var SHARD_PATHS = {
+  component: "json/components.json",
+  type: "json/types.json",
+  hook: "json/hooks.json"
+};
+function resolveEntityByArtifactKind(bundle, raw, artifactKind) {
+  const query = raw.trim();
+  if (!query) {
+    return {
+      ok: false,
+      code: "INVALID_INPUT",
+      message: "Query must be non-empty."
+    };
+  }
+  const wantKind = artifactKind;
+  const idMeta = bundle.idIndex[query];
+  if (idMeta?.kind === wantKind) {
+    let entry = findSymbolEntryByEntityId(bundle, query);
+    if (!entry) {
+      const synthetic = {
+        entityId: query,
+        artifactKind,
+        jsonPath: SHARD_PATHS[artifactKind] ?? `json/${artifactKind}s.json`,
+        sourcePath: idMeta.path ?? "",
+        package: idMeta.package ?? ""
+      };
+      entry = synthetic;
+    } else if (entry.artifactKind !== artifactKind) {
+      return {
+        ok: false,
+        code: "INVALID_INPUT",
+        message: `Entity id "${query}" is indexed as ${entry.artifactKind}, expected ${artifactKind}.`
+      };
+    }
+    return { ok: true, entityId: query, entry };
+  }
+  if (idMeta?.kind && idMeta.kind !== wantKind) {
+    return {
+      ok: false,
+      code: "INVALID_INPUT",
+      message: `Entity id "${query}" is a ${idMeta.kind}, not a ${artifactKind}.`,
+      hint: `Use the matching tool: ${toolForKind(idMeta.kind)}.`
+    };
+  }
+  const direct = bundle.symbolIndex[query];
+  if (direct?.artifactKind === artifactKind) {
+    return { ok: true, entityId: direct.entityId, entry: direct };
+  }
+  if (direct && direct.artifactKind !== artifactKind) {
+    return {
+      ok: false,
+      code: "INVALID_INPUT",
+      message: `"${query}" resolves to ${direct.artifactKind} "${direct.entityId}", not ${artifactKind}.`,
+      hint: `Use ${toolForKind(direct.artifactKind)} instead.`
+    };
+  }
+  const qualified = [];
+  const suffix = `:${query}`;
+  for (const [key, entry] of Object.entries(bundle.symbolIndex)) {
+    if (entry.artifactKind !== artifactKind) continue;
+    if (key === query || key.endsWith(suffix)) {
+      qualified.push(entry);
+    }
+  }
+  const byEntity = /* @__PURE__ */ new Map();
+  for (const e of qualified) {
+    byEntity.set(e.entityId, e);
+  }
+  if (byEntity.size === 1) {
+    const entry = [...byEntity.values()][0];
+    return { ok: true, entityId: entry.entityId, entry };
+  }
+  if (byEntity.size > 1) {
+    return {
+      ok: false,
+      code: "INVALID_INPUT",
+      message: `Ambiguous ${artifactKind} name "${query}" (${byEntity.size} definitions).`,
+      hint: "Disambiguate with `@scope/package:Name` or the full entity id (component.* / type.*)."
+    };
+  }
+  const lastSegment = query.includes(".") ? query.split(".").pop() : void 0;
+  return {
+    ok: false,
+    code: "NOT_FOUND",
+    message: `No ${artifactKind} found for "${query}".`,
+    hint: lastSegment && lastSegment !== query ? `"${query}" looks like an interceptor target path. Try orderly_docs_get_component with the full path first (supports interceptor fallback), or try "${lastSegment}" and related props types like "${lastSegment}Props".` : void 0
+  };
+}
+
+// src/exactLookup.ts
+import fs4 from "fs";
+import path4 from "path";
+function findInShard(generatedRoot, jsonRelPath, entityId) {
+  const rows = readEntityJson(generatedRoot, jsonRelPath);
+  return rows.find((r) => r.id === entityId);
+}
+function entityCitation(entry, via) {
+  return {
+    path: entry.sourcePath,
+    why: via,
+    id: entry.entityId
+  };
+}
+function interceptorTargetCandidates(query) {
+  const trimmed = query.trim();
+  if (!trimmed.includes(".")) return null;
+  const rawParts = trimmed.split(".").map((p) => p.trim()).filter(Boolean);
+  if (rawParts.length < 2) return null;
+  const parts = rawParts.map(
+    (part) => part.replace(/[^A-Za-z0-9]+/g, " ").split(/\s+/).filter(Boolean).map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("")
+  );
+  const tailComponent = parts.slice(1).join("");
+  const leafComponent = parts[parts.length - 1] ?? "";
+  const componentName = tailComponent || leafComponent;
+  if (!componentName) return null;
+  const propsTypeCandidates = [
+    .../* @__PURE__ */ new Set([`${componentName}Props`, `${leafComponent}Props`])
+  ];
+  return { componentName, propsTypeCandidates };
+}
+function resolveInterceptorPropsFallback(bundle, query) {
+  const candidates = interceptorTargetCandidates(query);
+  if (!candidates) return null;
+  for (const typeName of candidates.propsTypeCandidates) {
+    const resolvedType = resolveEntityByArtifactKind(bundle, typeName, "type");
+    if (resolvedType.ok) {
+      return {
+        typeEntityId: resolvedType.entityId,
+        typeEntry: resolvedType.entry,
+        componentName: candidates.componentName,
+        propsTypeName: typeName
+      };
+    }
+  }
+  return null;
+}
+function getComponent(bundle, query, started) {
+  const resolved = resolveEntityByArtifactKind(bundle, query, "component");
+  if (!resolved.ok) {
+    if (resolved.code === "NOT_FOUND") {
+      const fallback = resolveInterceptorPropsFallback(bundle, query);
+      if (fallback) {
+        const typeRecord = findInShard(
+          bundle.generatedRoot,
+          fallback.typeEntry.jsonPath,
+          fallback.typeEntityId
+        );
+        if (typeRecord) {
+          return okResult(
+            bundle,
+            {
+              id: `component.synthetic.${fallback.componentName}`,
+              name: fallback.componentName,
+              displayName: fallback.componentName,
+              artifactKind: "component",
+              resolutionLevel: "interceptor-props-fallback",
+              sourceKind: "type-fallback",
+              propsTypeId: fallback.typeEntityId,
+              propsTypeName: fallback.propsTypeName,
+              propsType: typeRecord
+            },
+            "exact",
+            [
+              entityCitation(
+                {
+                  sourcePath: fallback.typeEntry.sourcePath,
+                  entityId: fallback.typeEntityId
+                },
+                "interceptor target fallback via type metadata"
+              )
+            ],
+            started
+          );
+        }
+      }
+    }
+    return errResult(
+      resolved.code,
+      resolved.message,
+      resolved.hint,
+      bundle
+    );
+  }
+  const { entityId, entry } = resolved;
+  const record = findInShard(bundle.generatedRoot, entry.jsonPath, entityId);
+  if (!record) {
+    return errResult(
+      "NOT_FOUND",
+      `Component "${entityId}" missing from shard ${entry.jsonPath}.`,
+      "Regenerate AI docs (pnpm --filter @orderly.network/ai-docs generate).",
+      bundle
+    );
+  }
+  const resLevel = record.resolutionLevel;
+  return okResult(
+    bundle,
+    record,
+    "exact",
+    [
+      entityCitation(
+        { sourcePath: entry.sourcePath, entityId },
+        "symbol-index + json/components"
+      )
+    ],
+    started,
+    resLevel === "syntax-only" ? { resolutionLevel: "syntax-only" } : void 0
+  );
+}
+function getType(bundle, query, started) {
+  const resolved = resolveEntityByArtifactKind(bundle, query, "type");
+  if (!resolved.ok) {
+    return errResult(
+      resolved.code,
+      resolved.message,
+      resolved.hint,
+      bundle
+    );
+  }
+  const { entityId, entry } = resolved;
+  const record = findInShard(bundle.generatedRoot, entry.jsonPath, entityId);
+  if (!record) {
+    return errResult(
+      "NOT_FOUND",
+      `Type "${entityId}" missing from shard ${entry.jsonPath}.`,
+      "Regenerate AI docs (pnpm --filter @orderly.network/ai-docs generate).",
+      bundle
+    );
+  }
+  return okResult(
+    bundle,
+    record,
+    "exact",
+    [
+      entityCitation(
+        { sourcePath: entry.sourcePath, entityId },
+        "symbol-index + json/types"
+      )
+    ],
+    started
+  );
+}
+function getHook(bundle, query, started) {
+  const resolved = resolveEntityByArtifactKind(bundle, query, "hook");
+  if (!resolved.ok) {
+    return errResult(
+      resolved.code,
+      resolved.message,
+      resolved.hint,
+      bundle
+    );
+  }
+  const { entityId, entry } = resolved;
+  const record = findInShard(bundle.generatedRoot, entry.jsonPath, entityId);
+  if (!record) {
+    return errResult(
+      "NOT_FOUND",
+      `Hook "${entityId}" missing from shard ${entry.jsonPath}.`,
+      "Regenerate AI docs (pnpm --filter @orderly.network/ai-docs generate).",
+      bundle
+    );
+  }
+  const resLevel = record.resolutionLevel;
+  return okResult(
+    bundle,
+    record,
+    "exact",
+    [
+      entityCitation(
+        { sourcePath: entry.sourcePath, entityId },
+        "symbol-index + json/hooks"
+      )
+    ],
+    started,
+    resLevel === "syntax-only" ? { resolutionLevel: "syntax-only" } : void 0
+  );
+}
+var PACKAGE_ALIASES = {
+  layout: "@orderly.network/layout-core",
+  "layout-core": "@orderly.network/layout-core",
+  plugin: "@orderly.network/plugin-core",
+  "plugin-core": "@orderly.network/plugin-core",
+  ui: "@orderly.network/ui"
+};
+function normalizePkgName(name) {
+  return name.trim().toLowerCase();
+}
+function resolvePackageName(bundle, packageName) {
+  const raw = packageName.trim();
+  if (!raw) return {};
+  if (bundle.packageIndex[raw]) return { resolved: raw };
+  const normalized = normalizePkgName(raw);
+  const aliasHit = PACKAGE_ALIASES[normalized];
+  if (aliasHit && bundle.packageIndex[aliasHit]) {
+    return { resolved: aliasHit };
+  }
+  const all = Object.keys(bundle.packageIndex);
+  const ranked = all.map((k) => ({
+    key: k,
+    score: (k.toLowerCase().includes(normalized) ? 3 : 0) + (normalized.includes(k.toLowerCase()) ? 2 : 0)
+  })).filter((x) => x.score > 0).sort((a, b) => b.score - a.score).slice(0, 3).map((x) => x.key);
+  return { didYouMean: ranked.length ? ranked : void 0 };
+}
+function getPackageSurface(bundle, packageName, started) {
+  const name = packageName.trim();
+  if (!name) {
+    return errResult(
+      "INVALID_INPUT",
+      "packageName must be non-empty.",
+      void 0,
+      bundle
+    );
+  }
+  const { resolved, didYouMean } = resolvePackageName(bundle, name);
+  const lookupName = resolved ?? name;
+  const row = bundle.packageIndex[lookupName];
+  if (!row || !Array.isArray(row.exports)) {
+    return errResult(
+      "NOT_FOUND",
+      `No package index entry for "${name}".`,
+      didYouMean?.length ? `Did you mean: ${didYouMean.join(", ")}` : "Use the full package name such as @orderly.network/layout-core.",
+      bundle
+    );
+  }
+  const data = {
+    packageName: lookupName,
+    exports: row.exports,
+    componentIds: Array.isArray(row.componentIds) ? row.componentIds : [],
+    hookIds: Array.isArray(row.hookIds) ? row.hookIds : [],
+    typeIds: Array.isArray(row.typeIds) ? row.typeIds : []
+  };
+  return okResult(
+    bundle,
+    data,
+    "exact",
+    [{ path: name, why: "package-index" }],
+    started
+  );
+}
+function getReleaseContext(bundle, started) {
+  const stampPath = path4.join(bundle.generatedRoot, "build-stamp.json");
+  let buildStamp = null;
+  if (fs4.existsSync(stampPath)) {
+    try {
+      buildStamp = JSON.parse(fs4.readFileSync(stampPath, "utf8"));
+    } catch {
+      buildStamp = null;
+    }
+  }
+  return okResult(
+    bundle,
+    { manifest: bundle.manifest, buildStamp },
+    "manifest",
+    [{ path: "manifest.json", why: "release-context" }],
+    started
+  );
+}
+
+// src/componentDoc.ts
+import fs5 from "fs";
+import path5 from "path";
+function resolveComponentDocAbsPath(bundle, entityId) {
+  const row = bundle.componentDocIndex[entityId];
+  if (!row) return null;
+  if (row.source === "curated") {
+    try {
+      return path5.join(resolveRepoRoot(), row.mdPath);
+    } catch {
+      return null;
+    }
+  }
+  return path5.join(bundle.generatedRoot, row.mdPath);
+}
+function getComponentDoc(bundle, query, started) {
+  const resolved = resolveEntityByArtifactKind(bundle, query, "component");
+  if (!resolved.ok) {
+    return errResult(
+      resolved.code,
+      resolved.message,
+      resolved.hint,
+      bundle
+    );
+  }
+  const row = bundle.componentDocIndex[resolved.entityId];
+  if (!row) {
+    return errResult(
+      "NOT_FOUND",
+      `No component markdown index entry for "${resolved.entityId}".`,
+      "Run pnpm --filter @orderly.network/ai-docs generate.",
+      bundle
+    );
+  }
+  const abs = resolveComponentDocAbsPath(bundle, resolved.entityId);
+  if (!abs || !fs5.existsSync(abs)) {
+    return errResult(
+      "NOT_FOUND",
+      `Component markdown file missing (${row.mdPath}).`,
+      "Run generate from the monorepo root, or sync bundled artifacts.",
+      bundle
+    );
+  }
+  const text = fs5.readFileSync(abs, "utf8");
+  const pathForCitation = path5.relative(bundle.repoRoot, abs).replace(/\\/g, "/") || row.mdPath;
+  return okResult(
+    bundle,
+    { path: pathForCitation, text, sections: [], source: "repo-markdown" },
+    "narrative",
+    [{ path: pathForCitation, why: "component-doc-index + file" }],
+    started
+  );
+}
+
+// src/narrativeDocs.ts
+import fs6 from "fs";
+import path6 from "path";
+function normalizeSlug(raw) {
+  const s = raw.trim().replace(/\.md$/i, "");
+  if (!s || s.includes("..") || s.includes("/") || s.includes("\\")) {
+    return "";
+  }
+  return s;
+}
+function normalizeLooseToken(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function markdownRoot(bundle) {
+  const mr = bundle.manifest.roots?.markdownRoot ?? "apps/ai-docs";
+  return mr;
+}
+function listMarkdownBasenames(bundle, subdir) {
+  try {
+    const root = resolveRepoRoot();
+    const absDir = path6.join(root, markdownRoot(bundle), subdir);
+    if (!fs6.existsSync(absDir) || !fs6.statSync(absDir).isDirectory()) {
+      return [];
+    }
+    return fs6.readdirSync(absDir).filter((name) => name.toLowerCase().endsWith(".md")).map((name) => name.replace(/\.md$/i, ""));
+  } catch {
+    return [];
+  }
+}
+function resolveMarkdownSlug(input, available) {
+  if (available.includes(input)) {
+    return { ok: true, slug: input };
+  }
+  const inputToken = normalizeLooseToken(input);
+  if (!inputToken) {
+    return {
+      ok: false,
+      message: "Invalid input after normalization."
+    };
+  }
+  const tokenMatches = available.filter(
+    (entry) => normalizeLooseToken(entry) === inputToken
+  );
+  if (tokenMatches.length === 1) {
+    return { ok: true, slug: tokenMatches[0] };
+  }
+  if (tokenMatches.length > 1) {
+    return {
+      ok: false,
+      message: `Ambiguous input. Candidates: ${tokenMatches.join(", ")}`
+    };
+  }
+  const partialMatches = available.filter((entry) => {
+    const token = normalizeLooseToken(entry);
+    return token.includes(inputToken) || inputToken.includes(token);
+  });
+  if (partialMatches.length === 1) {
+    return { ok: true, slug: partialMatches[0] };
+  }
+  if (partialMatches.length > 1) {
+    return {
+      ok: false,
+      message: `Ambiguous input. Candidates: ${partialMatches.join(", ")}`
+    };
+  }
+  return {
+    ok: false,
+    message: "No matching document slug found."
+  };
+}
+function tryReadMarkdownFile(bundle, relFromMarkdownRoot) {
+  try {
+    const root = resolveRepoRoot();
+    const abs = path6.join(root, markdownRoot(bundle), relFromMarkdownRoot);
+    if (fs6.existsSync(abs) && fs6.statSync(abs).isFile()) {
+      return fs6.readFileSync(abs, "utf8");
+    }
+  } catch {
+  }
+  return null;
+}
+function readOrNotFound(bundle, relFromMarkdownRoot, citationPath, started, label) {
+  const repoFull = tryReadMarkdownFile(bundle, relFromMarkdownRoot);
+  if (repoFull !== null) {
+    return okResult(
+      bundle,
+      {
+        path: citationPath,
+        text: repoFull,
+        sections: [],
+        source: "repo-markdown"
+      },
+      "narrative",
+      [{ path: citationPath, why: `${label} (repo file)` }],
+      started
+    );
+  }
+  return errResult(
+    "NOT_FOUND",
+    `Missing markdown for ${label} at ${citationPath}.`,
+    "Use a monorepo checkout with apps/ai-docs, or copy the workflow/recipe files next to your bundle.",
+    bundle
+  );
+}
+function getWorkflow(bundle, slug, started) {
+  const s = normalizeSlug(slug);
+  if (!s) {
+    return errResult(
+      "INVALID_INPUT",
+      "Invalid workflow slug (use a single filename segment without path separators).",
+      void 0,
+      bundle
+    );
+  }
+  const available = listMarkdownBasenames(bundle, "workflows");
+  const resolved = resolveMarkdownSlug(s, available);
+  if (!resolved.ok) {
+    return errResult(
+      "INVALID_INPUT",
+      `Unable to resolve workflow slug "${slug}". ${resolved.message}`,
+      available.length ? `Try one of: ${available.join(", ")}` : "Run in monorepo context so workflow files can be discovered.",
+      bundle
+    );
+  }
+  const rel = path6.join("workflows", `${resolved.slug}.md`);
+  const citationPath = path6.join(markdownRoot(bundle), rel).replace(/\\/g, "/");
+  return readOrNotFound(
+    bundle,
+    rel,
+    citationPath,
+    started,
+    `workflow:${resolved.slug}`
+  );
+}
+function getRecipe(bundle, name, started) {
+  const s = normalizeSlug(name);
+  if (!s) {
+    return errResult(
+      "INVALID_INPUT",
+      "Invalid recipe name (use a single filename segment without path separators).",
+      void 0,
+      bundle
+    );
+  }
+  const available = listMarkdownBasenames(bundle, "recipes");
+  const resolved = resolveMarkdownSlug(s, available);
+  if (!resolved.ok) {
+    return errResult(
+      "INVALID_INPUT",
+      `Unable to resolve recipe name "${name}". ${resolved.message}`,
+      available.length ? `Try one of: ${available.join(", ")}` : "Run in monorepo context so recipe files can be discovered.",
+      bundle
+    );
+  }
+  const rel = path6.join("recipes", `${resolved.slug}.md`);
+  const citationPath = path6.join(markdownRoot(bundle), rel).replace(/\\/g, "/");
+  return readOrNotFound(
+    bundle,
+    rel,
+    citationPath,
+    started,
+    `recipe:${resolved.slug}`
+  );
+}
+function getGuardrails(bundle, started) {
+  const rel = "guardrails.md";
+  const citationPath = path6.join(markdownRoot(bundle), rel).replace(/\\/g, "/");
+  return readOrNotFound(bundle, rel, citationPath, started, "guardrails");
+}
+
+// src/searchDocs.ts
+function looksLikeEntityId(q) {
+  return /^[a-z][a-z0-9_]*\.[A-Za-z0-9_.]+$/.test(q);
+}
+function normalizeEnglishQuery(q) {
+  return q.toLowerCase().replace(/[?.,!;:()[\]{}"']/g, " ").replace(/\s+/g, " ").trim();
+}
+function inferPackagesFromQuery(query) {
+  const q = ` ${normalizeEnglishQuery(query)} `;
+  const out = /* @__PURE__ */ new Set();
+  if (q.includes(" layout ")) out.add("@orderly.network/layout-core");
+  if (q.includes(" plugin ") || q.includes(" interceptor ") || q.includes(" injectable ")) {
+    out.add("@orderly.network/plugin-core");
+  }
+  return [...out];
+}
+function buildPackageSurfaceHints(bundle, inferredPackages) {
+  return inferredPackages.map((name) => {
+    const row = bundle.packageIndex[name];
+    if (!row || !Array.isArray(row.exports)) return null;
+    return {
+      packageName: name,
+      exportsPreview: row.exports.slice(0, 8),
+      componentIdsPreview: Array.isArray(row.componentIds) ? row.componentIds.slice(0, 8) : []
+    };
+  }).filter((x) => x !== null);
+}
+async function searchDocs(bundle, qmdNarrative, input, started) {
+  const query = input.query.trim();
+  if (!query) {
+    return errResult(
+      "INVALID_INPUT",
+      "search query must be non-empty.",
+      void 0,
+      bundle
+    );
+  }
+  const k = Math.min(50, Math.max(1, input.k ?? 8));
+  const normalizedQuery = normalizeEnglishQuery(query);
+  const queryVariants = [...new Set([query, normalizedQuery].filter(Boolean))];
+  const inferredPackages = inferPackagesFromQuery(query);
+  const effectivePackages = input.packages && input.packages.length > 0 ? input.packages : inferredPackages;
+  const baseQ = {
+    query,
+    k,
+    kinds: input.kinds,
+    packages: effectivePackages,
+    queryVariants
+  };
+  let matchedEntityId;
+  let matchedEntityKind;
+  if (looksLikeEntityId(query) && bundle.idIndex[query]) {
+    matchedEntityId = query;
+    const idMeta = bundle.idIndex[query];
+    matchedEntityKind = idMeta?.kind;
+  }
+  let keywordSingletonId;
+  let keywordSingletonKind;
+  const firstTok = query.toLowerCase().split(/\s+/)[0] ?? "";
+  if (firstTok.length > 1) {
+    const ids = bundle.keywordIndex[firstTok];
+    if (ids?.length === 1) {
+      keywordSingletonId = ids[0];
+      const idMeta = bundle.idIndex[ids[0]];
+      keywordSingletonKind = idMeta?.kind;
+    }
+  }
+  const narrativeHits = await qmdNarrative.search(baseQ);
+  const citations = narrativeHits.slice(0, 5).map((h) => ({
+    path: h.path,
+    id: h.id,
+    why: "narrative-hit",
+    ...h.heading ? {} : {}
+  }));
+  return okResult(
+    bundle,
+    {
+      narrativeHits,
+      ...matchedEntityId !== void 0 ? { matchedEntityId } : {},
+      ...matchedEntityKind !== void 0 ? { matchedEntityKind } : {},
+      ...keywordSingletonId !== void 0 ? { keywordSingletonId } : {},
+      ...keywordSingletonKind !== void 0 ? { keywordSingletonKind } : {},
+      ...queryVariants.length > 0 ? { queryVariants } : {},
+      ...inferredPackages.length > 0 ? { inferredPackages } : {},
+      ...inferredPackages.length > 0 ? {
+        packageSurfaceHints: buildPackageSurfaceHints(
+          bundle,
+          inferredPackages
+        )
+      } : {}
+    },
+    "narrative",
+    citations,
+    started
+  );
+}
+
+// src/fetchSdkSource.ts
+var MAX_RAW_BYTES = 2 * 1024 * 1024;
+var DEFAULT_OWNER = "OrderlyNetwork";
+var DEFAULT_REPO = "js-sdk";
+var DEFAULT_BRANCH = "main";
+var DEFAULT_CONTEXT_LINES = 15;
+function githubOwner() {
+  return (process.env.ORDERLY_SDK_GITHUB_OWNER || DEFAULT_OWNER).trim() || DEFAULT_OWNER;
+}
+function githubRepo() {
+  return (process.env.ORDERLY_SDK_GITHUB_REPO || DEFAULT_REPO).trim() || DEFAULT_REPO;
+}
+function resolvePreferredRef() {
+  const fromEnv = process.env.ORDERLY_SDK_GITHUB_REF?.trim();
+  if (fromEnv) return fromEnv;
+  return DEFAULT_BRANCH;
+}
+function normalizeRelPath(raw) {
+  const s = raw.trim().replace(/\\/g, "/");
+  return s.replace(/^\/+/, "");
+}
+function buildGithubRawUrl(owner, repo, ref, relPath) {
+  const enc = relPath.split("/").map((seg) => encodeURIComponent(seg)).join("/");
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${enc}`;
+}
+function buildGithubBlobUrl(owner, repo, ref, relPath, fragment) {
+  const enc = relPath.split("/").map((seg) => encodeURIComponent(seg)).join("/");
+  let url = `https://github.com/${owner}/${repo}/blob/${ref}/${enc}`;
+  if (fragment) {
+    const { startLine, endLine } = fragment;
+    url += startLine === endLine ? `#L${startLine}` : `#L${startLine}-L${endLine}`;
+  }
+  return url;
+}
+function splitLines(text) {
+  return text.split(/\r\n|\r|\n/);
+}
+function computeExcerptRange(lineCount, line, endLine, contextLines) {
+  if (lineCount === 0) {
+    return { ok: false, message: "File is empty." };
+  }
+  const ctx = Math.max(0, Math.min(200, contextLines));
+  if (line === void 0 && endLine === void 0) {
+    return { ok: false, message: "Internal: no line options." };
+  }
+  let start;
+  let end;
+  if (line !== void 0 && endLine !== void 0) {
+    if (!Number.isInteger(line) || !Number.isInteger(endLine)) {
+      return { ok: false, message: "`line` and `endLine` must be integers." };
+    }
+    if (line < 1) {
+      return { ok: false, message: "`line` must be >= 1." };
+    }
+    if (endLine < line) {
+      return { ok: false, message: "`endLine` must be >= `line`." };
+    }
+    start = line;
+    end = endLine;
+  } else if (line !== void 0) {
+    if (!Number.isInteger(line)) {
+      return { ok: false, message: "`line` must be an integer." };
+    }
+    if (line < 1) {
+      return { ok: false, message: "`line` must be >= 1." };
+    }
+    start = Math.max(1, line - ctx);
+    end = Math.min(lineCount, line + ctx);
+  } else {
+    if (!Number.isInteger(endLine)) {
+      return { ok: false, message: "`endLine` must be an integer." };
+    }
+    if (endLine < 1) {
+      return { ok: false, message: "`endLine` must be >= 1." };
+    }
+    start = 1;
+    end = endLine;
+  }
+  start = Math.max(1, Math.min(start, lineCount));
+  end = Math.max(start, Math.min(end, lineCount));
+  return { ok: true, start, end };
+}
+async function fetchSdkSource(bundle, input, started) {
+  const relPath = normalizeRelPath(input.relPath);
+  if (!relPath) {
+    return errResult(
+      "INVALID_INPUT",
+      "`relPath` must be non-empty.",
+      void 0,
+      bundle
+    );
+  }
+  if (relPath.includes("://")) {
+    return errResult(
+      "INVALID_INPUT",
+      "`relPath` must be a relative repo path, not a URL.",
+      void 0,
+      bundle
+    );
+  }
+  try {
+    assertSafeRelPath(relPath);
+  } catch {
+    return errResult(
+      "INVALID_INPUT",
+      "Invalid `relPath` (no `..` segments).",
+      void 0,
+      bundle
+    );
+  }
+  const owner = githubOwner();
+  const repo = githubRepo();
+  let ref = resolvePreferredRef();
+  const tryRefs = ref === DEFAULT_BRANCH ? [ref] : [ref, DEFAULT_BRANCH];
+  const wantsExcerpt = input.line !== void 0 || input.endLine !== void 0;
+  let fragment;
+  if (wantsExcerpt) {
+    if (input.line !== void 0 && (!Number.isInteger(input.line) || input.line < 1)) {
+      return errResult(
+        "INVALID_INPUT",
+        "`line` must be a positive integer.",
+        void 0,
+        bundle
+      );
+    }
+    if (input.endLine !== void 0 && (!Number.isInteger(input.endLine) || input.endLine < 1)) {
+      return errResult(
+        "INVALID_INPUT",
+        "`endLine` must be a positive integer.",
+        void 0,
+        bundle
+      );
+    }
+    if (input.line !== void 0 && input.endLine !== void 0 && input.endLine < input.line) {
+      return errResult(
+        "INVALID_INPUT",
+        "`endLine` must be >= `line`.",
+        void 0,
+        bundle
+      );
+    }
+  }
+  const headers = {
+    Accept: "text/plain,*/*;q=0.1",
+    "User-Agent": "orderly-sdk-docs-fetch"
+  };
+  const token = process.env.GITHUB_TOKEN?.trim() || process.env.ORDERLY_GITHUB_TOKEN?.trim();
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  let res;
+  let rawUrl = "";
+  for (let i = 0; i < tryRefs.length; i++) {
+    const attemptRef = tryRefs[i];
+    ref = attemptRef;
+    rawUrl = buildGithubRawUrl(owner, repo, attemptRef, relPath);
+    try {
+      res = await fetch(rawUrl, { redirect: "follow", headers });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return errResult(
+        "BACKEND_UNAVAILABLE",
+        `Failed to reach GitHub: ${msg}`,
+        "Check network, proxy, or try again.",
+        bundle
+      );
+    }
+    if (res.status !== 404 || i === tryRefs.length - 1) break;
+  }
+  if (res.status === 404) {
+    const preferred = resolvePreferredRef();
+    return errResult(
+      "NOT_FOUND",
+      `GitHub raw content not found (HTTP 404) for path "${relPath}".`,
+      [
+        `URL: ${rawUrl}`,
+        `Tried ref(s): ${tryRefs.join(", ")}.`,
+        preferred !== DEFAULT_BRANCH ? `If "${preferred}" is a local-only commit, set ORDERLY_SDK_GITHUB_REF=main or omit it.` : "Confirm the file path exists on the public js-sdk repo at this ref."
+      ].join(" "),
+      bundle
+    );
+  }
+  if (!res.ok) {
+    return errResult(
+      "BACKEND_UNAVAILABLE",
+      `GitHub returned HTTP ${res.status} for raw content.`,
+      `URL: ${rawUrl}`,
+      bundle
+    );
+  }
+  const lenHeader = res.headers.get("content-length");
+  if (lenHeader) {
+    const n = parseInt(lenHeader, 10);
+    if (Number.isFinite(n) && n > MAX_RAW_BYTES) {
+      return errResult(
+        "INVALID_INPUT",
+        `Refused to fetch file: Content-Length ${n} exceeds limit ${MAX_RAW_BYTES}.`,
+        "Use a smaller file or increase limit in source if appropriate.",
+        bundle
+      );
+    }
+  }
+  const buf = await res.arrayBuffer();
+  if (buf.byteLength > MAX_RAW_BYTES) {
+    return errResult(
+      "INVALID_INPUT",
+      `Response size ${buf.byteLength} exceeds limit ${MAX_RAW_BYTES}.`,
+      void 0,
+      bundle
+    );
+  }
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(buf);
+  const lines = splitLines(text);
+  const lineCount = lines.length;
+  if (wantsExcerpt && input.line !== void 0 && input.line > lineCount) {
+    return errResult(
+      "INVALID_INPUT",
+      `Requested line ${input.line} is past end of file (${lineCount} lines).`,
+      void 0,
+      bundle
+    );
+  }
+  let excerpt;
+  let blobUrl;
+  if (wantsExcerpt) {
+    const range = computeExcerptRange(
+      lineCount,
+      input.line,
+      input.endLine,
+      input.contextLines ?? DEFAULT_CONTEXT_LINES
+    );
+    if (!range.ok) {
+      return errResult("INVALID_INPUT", range.message, void 0, bundle);
+    }
+    fragment = { startLine: range.start, endLine: range.end };
+    const slice = lines.slice(range.start - 1, range.end);
+    excerpt = {
+      startLine: range.start,
+      endLine: range.end,
+      text: slice.join("\n")
+    };
+    blobUrl = buildGithubBlobUrl(owner, repo, ref, relPath, fragment);
+  } else {
+    blobUrl = buildGithubBlobUrl(owner, repo, ref, relPath);
+  }
+  const data = {
+    relPath,
+    ref,
+    rawUrl,
+    blobUrl,
+    text,
+    ...excerpt !== void 0 ? { excerpt } : {}
+  };
+  return okResult(
+    bundle,
+    data,
+    "exact",
+    [
+      {
+        path: relPath,
+        why: "github raw + resolved ref",
+        startLine: fragment?.startLine,
+        endLine: fragment?.endLine
+      }
+    ],
+    started
+  );
+}
+
+// src/facade.ts
+function createAiDocsFacade(bundle, opts) {
+  const qmdNarrative = opts?.qmdNarrative ?? new QmdNarrativeRetrieval(bundle);
+  return {
+    bundle,
+    getComponent: (query) => getComponent(bundle, query, performance.now()),
+    getHook: (query) => getHook(bundle, query, performance.now()),
+    getType: (query) => getType(bundle, query, performance.now()),
+    getPackageSurface: (packageName) => getPackageSurface(bundle, packageName, performance.now()),
+    getReleaseContext: () => getReleaseContext(bundle, performance.now()),
+    getWorkflow: (slug) => getWorkflow(bundle, slug, performance.now()),
+    getRecipe: (name) => getRecipe(bundle, name, performance.now()),
+    getGuardrails: () => getGuardrails(bundle, performance.now()),
+    getComponentDoc: (query) => getComponentDoc(bundle, query, performance.now()),
+    searchDocs: (input) => searchDocs(bundle, qmdNarrative, input, performance.now()),
+    fetchSdkSource: (input) => fetchSdkSource(bundle, input, performance.now())
+  };
+}
+
+// src/install/adapterRegistry.ts
+function createClientAdapterRegistry(initialAdapters = []) {
+  const adapters = /* @__PURE__ */ new Map();
+  for (const adapter of initialAdapters) {
+    adapters.set(adapter.client, adapter);
+  }
+  return {
+    get(client) {
+      return adapters.get(client);
+    },
+    register(adapter) {
+      adapters.set(adapter.client, adapter);
+    },
+    list() {
+      return Array.from(adapters.values());
+    }
+  };
+}
+
+// src/install/clients.ts
+import path7 from "path";
+function mergeByMcpServers(raw, entryName, entry, force) {
+  const next = { ...raw };
+  const mcpServers = next.mcpServers && typeof next.mcpServers === "object" ? { ...next.mcpServers } : {};
+  const current = mcpServers[entryName];
+  if (!force && current && typeof current === "object") {
+    const currentObject = current;
+    const commandEqual = currentObject.command === entry.command;
+    const argsEqual = JSON.stringify(currentObject.args ?? []) === JSON.stringify(entry.args ?? []);
+    const envEqual = JSON.stringify(currentObject.env ?? {}) === JSON.stringify(entry.env ?? {});
+    if (commandEqual && argsEqual && envEqual) {
+      return { merged: raw, action: "noop" };
+    }
+    mcpServers[entryName] = {
+      ...currentObject,
+      command: entry.command,
+      args: entry.args ?? [],
+      ...entry.env ? { env: entry.env } : {}
+    };
+    next.mcpServers = mcpServers;
+    return { merged: next, action: "updated" };
+  }
+  mcpServers[entryName] = entry;
+  next.mcpServers = mcpServers;
+  return { merged: next, action: "updated" };
+}
+function byScope(scope, cwd, userPath, projectPath) {
+  return scope === "project" ? path7.join(cwd, projectPath) : userPath;
+}
+function makeAdapter(client, userPath, projectPath) {
+  return {
+    client,
+    resolvePath(scope, cwd) {
+      return byScope(scope, cwd, userPath, projectPath);
+    },
+    mergeConfig(raw, entryName, entry, force) {
+      return mergeByMcpServers(raw, entryName, entry, force);
+    }
+  };
+}
+var home = process.env.HOME || process.env.USERPROFILE || "";
+var builtinClientAdapters = [
+  makeAdapter("claude", path7.join(home, ".claude.json"), ".claude.json"),
+  makeAdapter(
+    "codex",
+    path7.join(home, ".codex", "config.json"),
+    ".codex/config.json"
+  ),
+  makeAdapter(
+    "cursor",
+    path7.join(home, ".cursor", "mcp.json"),
+    ".cursor/mcp.json"
+  ),
+  makeAdapter(
+    "opencode",
+    path7.join(home, ".opencode", "config.json"),
+    ".opencode/config.json"
+  )
+];
+var defaultClientAdapterRegistry = createClientAdapterRegistry(
+  builtinClientAdapters
+);
+
+export {
+  API_VERSION,
+  resolveRepoRoot,
+  aiDocsGeneratedRoot,
+  manifestExistsAtRepoRoot,
+  resolveAiDocsRepoRoot,
+  resolveBundledSyntheticRepoRoot,
+  assertSafeRelPath,
+  clearLoadBundleCache,
+  loadBundle,
+  readEntityJson,
+  clearQmdStoreCache,
+  QmdNarrativeRetrieval,
+  buildMetaOk,
+  elapsedMs,
+  okResult,
+  errResult,
+  resolveEntityByArtifactKind,
+  getComponent,
+  getType,
+  getHook,
+  getPackageSurface,
+  getReleaseContext,
+  resolveComponentDocAbsPath,
+  getComponentDoc,
+  getWorkflow,
+  getRecipe,
+  getGuardrails,
+  searchDocs,
+  buildGithubRawUrl,
+  buildGithubBlobUrl,
+  fetchSdkSource,
+  createAiDocsFacade,
+  createClientAdapterRegistry,
+  builtinClientAdapters,
+  defaultClientAdapterRegistry
+};
+//# sourceMappingURL=chunk-EPLR7UGM.js.map