@kodiak-finance/orderly-sdk-docs 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,438 @@
+/** Date-stamped API version (tech §6.5 + build-policy.json) */
+declare const API_VERSION = "2026-04-02";
+
+type ComponentDocIndexEntry = {
+    entityId: string;
+    mdPath: string;
+    package: string;
+    name: string;
+    source: "curated" | "generated";
+};
+type Manifest = {
+    schemaVersion: string;
+    gitSha: string;
+    generatedAt: string;
+    releaseVersion: string | null;
+    artifactKinds: string[];
+    roots: {
+        markdownRoot: string;
+        generatedRoot: string;
+    };
+    indexPaths: {
+        idIndex: string;
+        symbolIndex: string;
+        packageIndex: string;
+        keywordIndex: string;
+        componentDocIndex?: string;
+        /** @deprecated removed from generator */
+        chunkIndex?: string;
+    };
+    qmd?: Record<string, unknown>;
+    analysisStats: {
+        totalSymbols: number;
+        fullyResolved: number;
+        degradedCount: number;
+    };
+};
+type LoadedBundle = {
+    repoRoot: string;
+    generatedRoot: string;
+    manifest: Manifest;
+    idIndex: Record<string, unknown>;
+    symbolIndex: Record<string, {
+        entityId: string;
+        artifactKind: string;
+        jsonPath: string;
+        sourcePath: string;
+        package: string;
+    }>;
+    packageIndex: Record<string, unknown>;
+    keywordIndex: Record<string, string[]>;
+    componentDocIndex: Record<string, ComponentDocIndexEntry>;
+};
+/**
+ * Clears the in-memory bundle cache (e.g. after switching `ORDERLY_AI_DOCS_REPO_ROOT` in tests).
+ */
+declare function clearLoadBundleCache(): void;
+/**
+ * @param repoRoot - Monorepo root (contains `apps/ai-docs/generated/manifest.json`) or any directory
+ *   that is a full copy of `generated/` (e.g. `bundled/` after `sync:bundle`). When omitted, uses
+ *   {@link resolveAiDocsRepoRoot}.
+ */
+declare function loadBundle(repoRoot?: string): LoadedBundle;
+/**
+ * @param generatedRoot - {@link LoadedBundle.generatedRoot} (the `apps/ai-docs/generated` folder or a synced `bundled/` copy)
+ * @param jsonRelPath - e.g. symbol index `jsonPath` (`json/hooks.json`)
+ */
+declare function readEntityJson<T>(generatedRoot: string, jsonRelPath: string): T[];
+
+/**
+ * Resolve monorepo root from env or by walking up for `pnpm-workspace.yaml`.
+ */
+declare function resolveRepoRoot(cwd?: string): string;
+declare function aiDocsGeneratedRoot(repoRoot: string): string;
+/**
+ * Monorepo layout: `{root}/apps/ai-docs/generated/manifest.json`.
+ * Packaged flat layout: `{root}/manifest.json` next to `indexes/`.
+ */
+declare function manifestExistsAtRepoRoot(repoRoot: string): boolean;
+type ResolveAiDocsRepoRootOptions = {
+    /**
+     * `import.meta.url` from a facade module under `dist/` so packaged `bundled/` can be found
+     * next to `dist/` (see sync:bundle layout).
+     */
+    moduleUrl?: string;
+};
+/**
+ * Resolves the synthetic "repo root" where `apps/ai-docs/generated/manifest.json` exists.
+ *
+ * Precedence:
+ * 1. `ORDERLY_AI_DOCS_REPO_ROOT` — monorepo root, or a flat `bundled/` dir (`manifest.json` + `indexes/`)
+ * 2. `ORDERLY_REPO_ROOT` — when it is the monorepo root and manifest exists
+ * 3. Walk from cwd for `pnpm-workspace.yaml` (monorepo) when manifest exists
+ * 4. Packaged bundle: `{package}/bundled` (flat copy from `sync:bundle`)
+ */
+declare function resolveAiDocsRepoRoot(opts?: ResolveAiDocsRepoRootOptions): string;
+/**
+ * When the package is installed from npm, `bundled/` (flat generated copy) sits beside `dist/`.
+ *
+ * @param moduleUrl - typically `import.meta.url` from `dist/chunk-*.js` under `dist/`
+ */
+declare function resolveBundledSyntheticRepoRoot(moduleUrl: string): string | null;
+/** Reject path traversal in user-supplied relative paths */
+declare function assertSafeRelPath(rel: string): void;
+
+/**
+ * Unified tool response envelope (tech §6.2).
+ */
+type MatchKind = "exact" | "narrative" | "manifest";
+type Citation = {
+    path: string;
+    startLine?: number;
+    endLine?: number;
+    id?: string;
+    why: string;
+};
+type DocsMetaOk<T> = {
+    gitSha: string;
+    generatedAt: string;
+    queryMs: number;
+    matchKind: MatchKind;
+    apiVersion: string;
+    citations: Citation[];
+    resolutionLevel?: "full" | "partial" | "syntax-only";
+    degradedReason?: "OOM" | "TIMEOUT" | "UNSUPPORTED_TYPE";
+    deprecations?: Array<{
+        message: string;
+        alternative?: string;
+    }>;
+};
+type DocsResult<T> = {
+    ok: true;
+    data: T;
+    meta: DocsMetaOk<T>;
+} | {
+    ok: false;
+    error: {
+        code: "NOT_FOUND" | "STALE_INDEX" | "BACKEND_UNAVAILABLE" | "INVALID_INPUT" | "INVALID_INDEX_SHAPE";
+        message: string;
+        hint?: string;
+    };
+    meta: {
+        gitSha?: string;
+        generatedAt?: string;
+        apiVersion?: string;
+    };
+};
+type NarrativeHit = {
+    id: string;
+    path: string;
+    heading: string;
+    text: string;
+    kind?: string;
+    score: number;
+    /**
+     * Optional narrative metadata (typically from markdown frontmatter).
+     * Helps callers reason about retrieval intent/domain alignment.
+     */
+    domain?: string;
+    docType?: string;
+    packageName?: string;
+    intentTags?: string[];
+    lang?: string;
+};
+
+/**
+ * Pluggable Markdown narrative retrieval (QMD or fallback).
+ */
+type NarrativeQuery = {
+    query: string;
+    k: number;
+    kinds?: string[];
+    packages?: string[];
+    queryVariants?: string[];
+};
+interface NarrativeRetrieval {
+    search(q: NarrativeQuery): Promise<NarrativeHit[]>;
+}
+
+/**
+ * Release cached QMD DB (e.g. after tests or switching ORDERLY_AI_DOCS_REPO_ROOT).
+ */
+declare function clearQmdStoreCache(): void;
+/**
+ * QMD-backed narrative search: BM25 + optional vector similarity, with per-token BM25 fallback.
+ *
+ * Rationale: {@link QMDStore.searchLex} builds an FTS5 query that ANDs terms; multi-word English
+ * queries often miss. Merging {@link QMDStore.searchVector} helps when `qmd:index` + `embed` ran;
+ * token-wise BM25 improves recall without loading embedding models when vectors are absent.
+ */
+declare class QmdNarrativeRetrieval implements NarrativeRetrieval {
+    private bundle;
+    constructor(bundle: LoadedBundle);
+    search(q: NarrativeQuery): Promise<NarrativeHit[]>;
+}
+
+type BuildMetaOkInput<T> = {
+    bundle: LoadedBundle;
+    matchKind: MatchKind;
+    queryMs: number;
+    citations: Citation[];
+    resolutionLevel?: DocsMetaOk<T>["resolutionLevel"];
+    degradedReason?: DocsMetaOk<T>["degradedReason"];
+    deprecations?: DocsMetaOk<T>["deprecations"];
+};
+/**
+ * Fills version fields from the loaded manifest for every successful tool response.
+ */
+declare function buildMetaOk<T>(input: BuildMetaOkInput<T>): DocsMetaOk<T>;
+/** @param started - `performance.now()` or `Date.now()` at query start */
+declare function elapsedMs(started: number): number;
+/**
+ * Successful {@link DocsResult} with manifest-backed metadata.
+ */
+declare function okResult<T>(bundle: LoadedBundle, data: T, matchKind: MatchKind, citations: Citation[], started: number, extra?: Pick<DocsMetaOk<T>, "resolutionLevel" | "degradedReason" | "deprecations">): DocsResult<T>;
+type ErrCode = NonNullable<Extract<DocsResult<never>, {
+    ok: false;
+}>["error"]>["code"];
+/**
+ * Failed {@link DocsResult}; includes manifest version when bundle is available.
+ */
+declare function errResult<T = never>(code: ErrCode, message: string, hint: string | undefined, bundle: LoadedBundle | null): DocsResult<T>;
+
+type SymbolIndexEntry = LoadedBundle["symbolIndex"][string];
+declare function resolveEntityByArtifactKind(bundle: LoadedBundle, raw: string, artifactKind: "component" | "type" | "hook"): {
+    ok: true;
+    entityId: string;
+    entry: SymbolIndexEntry;
+} | {
+    ok: false;
+    code: "NOT_FOUND" | "INVALID_INPUT";
+    message: string;
+    hint?: string;
+};
+
+/**
+ * Exact structured lookup for a React component record (props metadata, etc.).
+ */
+declare function getComponent(bundle: LoadedBundle, query: string, started: number): DocsResult<Record<string, unknown>>;
+/**
+ * Exact structured lookup for a type / enum record.
+ */
+declare function getType(bundle: LoadedBundle, query: string, started: number): DocsResult<Record<string, unknown>>;
+/**
+ * Exact structured lookup for a React hook record (params, returns, jsDoc).
+ */
+declare function getHook(bundle: LoadedBundle, query: string, started: number): DocsResult<Record<string, unknown>>;
+type PackageSurfaceData = {
+    packageName: string;
+    exports: string[];
+    componentIds: string[];
+    hookIds: string[];
+    typeIds: string[];
+};
+/**
+ * Returns the indexed export surface for an npm package name (e.g. `@orderly.network/ui`).
+ */
+declare function getPackageSurface(bundle: LoadedBundle, packageName: string, started: number): DocsResult<PackageSurfaceData>;
+type ReleaseContextData = {
+    manifest: LoadedBundle["manifest"];
+    buildStamp: {
+        gitSha: string;
+        generatedAt: string;
+    } | null;
+};
+/**
+ * Manifest + optional `build-stamp.json` for release / provenance context.
+ */
+declare function getReleaseContext(bundle: LoadedBundle, started: number): DocsResult<ReleaseContextData>;
+
+type NarrativeDocBody = {
+    path: string;
+    /** Full file text (no chunk-index fallback). */
+    text: string;
+    sections: Array<{
+        id: string;
+        heading: string;
+        text: string;
+        startLine?: number;
+        endLine?: number;
+    }>;
+    source: "repo-markdown";
+};
+/**
+ * Curated workflow markdown (repo file only).
+ */
+declare function getWorkflow(bundle: LoadedBundle, slug: string, started: number): DocsResult<NarrativeDocBody>;
+/**
+ * Minimal recipe markdown (repo file only).
+ */
+declare function getRecipe(bundle: LoadedBundle, name: string, started: number): DocsResult<NarrativeDocBody>;
+/**
+ * Guardrails document (repo file only).
+ */
+declare function getGuardrails(bundle: LoadedBundle, started: number): DocsResult<NarrativeDocBody>;
+
+/**
+ * Resolve absolute path to component markdown (curated under repo root, generated under generated root).
+ */
+declare function resolveComponentDocAbsPath(bundle: LoadedBundle, entityId: string): string | null;
+/**
+ * Full component markdown for examples / narrative (JSON props stay on getComponent).
+ */
+declare function getComponentDoc(bundle: LoadedBundle, query: string, started: number): DocsResult<NarrativeDocBody>;
+
+type SearchDocsInput = {
+    query: string;
+    k?: number;
+    kinds?: string[];
+    packages?: string[];
+};
+type SearchDocsData = {
+    narrativeHits: NarrativeHit[];
+    /** Set when the query equals a known id-index key (agent can call getComponent/getType/getHook next). */
+    matchedEntityId?: string;
+    /** The artifactKind of the matched entity (component, type, hook, function). */
+    matchedEntityKind?: string;
+    /** When the first whitespace-delimited token maps to exactly one keyword-index entry. */
+    keywordSingletonId?: string;
+    /** The artifactKind of the keyword singleton entity. */
+    keywordSingletonKind?: string;
+    /** Query variants used by retrieval (English-only normalization in current phase). */
+    queryVariants?: string[];
+    /** Inferred package candidates from user intent. */
+    inferredPackages?: string[];
+    /** Lightweight package surface hints for likely next exact lookup calls. */
+    packageSurfaceHints?: Array<{
+        packageName: string;
+        exportsPreview: string[];
+        componentIdsPreview: string[];
+    }>;
+};
+/**
+ * Narrative search via QMD only; optional id/keyword hints from in-memory JSON indexes first.
+ */
+declare function searchDocs(bundle: LoadedBundle, qmdNarrative: NarrativeRetrieval, input: SearchDocsInput, started: number): Promise<DocsResult<SearchDocsData>>;
+
+type FetchSdkSourceInput = {
+    /** Repo-relative path (POSIX), same shape as symbol `sourcePath`. */
+    relPath: string;
+    /** 1-based start line for excerpt (optional). */
+    line?: number;
+    /** 1-based end line inclusive (optional). With `line`, defines range; ignored window logic if both set. */
+    endLine?: number;
+    /** Half-window size when only `line` is set (default 15). */
+    contextLines?: number;
+};
+type SdkGithubSourceExcerpt = {
+    startLine: number;
+    endLine: number;
+    text: string;
+};
+type SdkGithubSourceData = {
+    relPath: string;
+    ref: string;
+    rawUrl: string;
+    blobUrl: string;
+    /** Full file contents from the fetched blob. */
+    text: string;
+    /** Present when line options were used. */
+    excerpt?: SdkGithubSourceExcerpt;
+};
+/**
+ * Builds `raw.githubusercontent.com` URL for a repo-relative file path.
+ */
+declare function buildGithubRawUrl(owner: string, repo: string, ref: string, relPath: string): string;
+/**
+ * Builds human-readable `github.com/.../blob/...` URL; optional fragment for line range.
+ */
+declare function buildGithubBlobUrl(owner: string, repo: string, ref: string, relPath: string, fragment?: {
+    startLine: number;
+    endLine: number;
+}): string;
+/**
+ * Fetches a source file from the public Orderly JS SDK GitHub repo (default ref: branch `main`).
+ */
+declare function fetchSdkSource(bundle: LoadedBundle, input: FetchSdkSourceInput, started: number): Promise<DocsResult<SdkGithubSourceData>>;
+
+type AiDocsFacadeOptions = {
+    /** Override QMD retrieval; defaults to {@link QmdNarrativeRetrieval}. */
+    qmdNarrative?: NarrativeRetrieval;
+};
+/**
+ * Orderly-facing docs access object: exact entity lookup, narrative docs, and QMD-backed search.
+ */
+type AiDocsFacade = {
+    readonly bundle: LoadedBundle;
+    getComponent: (query: string) => DocsResult<Record<string, unknown>>;
+    getHook: (query: string) => DocsResult<Record<string, unknown>>;
+    getType: (query: string) => DocsResult<Record<string, unknown>>;
+    getPackageSurface: (packageName: string) => DocsResult<PackageSurfaceData>;
+    getReleaseContext: () => DocsResult<ReleaseContextData>;
+    getWorkflow: (slug: string) => DocsResult<NarrativeDocBody>;
+    getRecipe: (name: string) => DocsResult<NarrativeDocBody>;
+    getGuardrails: () => DocsResult<NarrativeDocBody>;
+    getComponentDoc: (query: string) => DocsResult<NarrativeDocBody>;
+    searchDocs: (input: SearchDocsInput) => Promise<DocsResult<SearchDocsData>>;
+    /** Fetches source from GitHub (OrderlyNetwork/js-sdk) at manifest ref or env overrides. */
+    fetchSdkSource: (input: FetchSdkSourceInput) => Promise<DocsResult<SdkGithubSourceData>>;
+};
+/**
+ * @param bundle - Typically from {@link loadBundle}; reused for all calls.
+ */
+declare function createAiDocsFacade(bundle: LoadedBundle, opts?: AiDocsFacadeOptions): AiDocsFacade;
+
+type McpServerConfigEntry = {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    [key: string]: unknown;
+};
+
+type InstallClient = "claude" | "codex" | "cursor" | "opencode";
+type InstallScope = "user" | "project";
+type ClientAdapter = {
+    client: InstallClient;
+    resolvePath(scope: InstallScope, cwd: string): string;
+    mergeConfig(raw: Record<string, unknown>, entryName: string, entry: McpServerConfigEntry, force: boolean): {
+        merged: Record<string, unknown>;
+        action: "updated" | "noop";
+    };
+};
+type ClientAdapterRegistry = {
+    /** Returns a registered adapter by client id, or undefined when missing. */
+    get(client: InstallClient): ClientAdapter | undefined;
+    /** Registers or replaces an adapter by its client id. */
+    register(adapter: ClientAdapter): void;
+    /** Returns all currently registered adapters in insertion order. */
+    list(): ClientAdapter[];
+};
+
+/** Creates a mutable adapter registry so install targets can be extended safely. */
+declare function createClientAdapterRegistry(initialAdapters?: ClientAdapter[]): ClientAdapterRegistry;
+
+declare const builtinClientAdapters: ClientAdapter[];
+/** Default adapter registry used by install command callers. */
+declare const defaultClientAdapterRegistry: ClientAdapterRegistry;
+
+export { API_VERSION, type AiDocsFacade, type AiDocsFacadeOptions, type Citation, type ClientAdapterRegistry, type ComponentDocIndexEntry, type DocsMetaOk, type DocsResult, type FetchSdkSourceInput, type LoadedBundle, type Manifest, type MatchKind, type NarrativeDocBody, type NarrativeHit, type NarrativeQuery, type NarrativeRetrieval, type PackageSurfaceData, QmdNarrativeRetrieval, type ReleaseContextData, type ResolveAiDocsRepoRootOptions, type SdkGithubSourceData, type SdkGithubSourceExcerpt, type SearchDocsData, type SearchDocsInput, aiDocsGeneratedRoot, assertSafeRelPath, buildGithubBlobUrl, buildGithubRawUrl, buildMetaOk, builtinClientAdapters, clearLoadBundleCache, clearQmdStoreCache, createAiDocsFacade, createClientAdapterRegistry, defaultClientAdapterRegistry, elapsedMs, errResult, fetchSdkSource, getComponent, getComponentDoc, getGuardrails, getHook, getPackageSurface, getRecipe, getReleaseContext, getType, getWorkflow, loadBundle, manifestExistsAtRepoRoot, okResult, readEntityJson, resolveAiDocsRepoRoot, resolveBundledSyntheticRepoRoot, resolveComponentDocAbsPath, resolveEntityByArtifactKind, resolveRepoRoot, searchDocs };

package/dist/index.js

@@ -0,0 +1,75 @@
+import {
+  API_VERSION,
+  QmdNarrativeRetrieval,
+  aiDocsGeneratedRoot,
+  assertSafeRelPath,
+  buildGithubBlobUrl,
+  buildGithubRawUrl,
+  buildMetaOk,
+  builtinClientAdapters,
+  clearLoadBundleCache,
+  clearQmdStoreCache,
+  createAiDocsFacade,
+  createClientAdapterRegistry,
+  defaultClientAdapterRegistry,
+  elapsedMs,
+  errResult,
+  fetchSdkSource,
+  getComponent,
+  getComponentDoc,
+  getGuardrails,
+  getHook,
+  getPackageSurface,
+  getRecipe,
+  getReleaseContext,
+  getType,
+  getWorkflow,
+  loadBundle,
+  manifestExistsAtRepoRoot,
+  okResult,
+  readEntityJson,
+  resolveAiDocsRepoRoot,
+  resolveBundledSyntheticRepoRoot,
+  resolveComponentDocAbsPath,
+  resolveEntityByArtifactKind,
+  resolveRepoRoot,
+  searchDocs
+} from "./chunk-EPLR7UGM.js";
+export {
+  API_VERSION,
+  QmdNarrativeRetrieval,
+  aiDocsGeneratedRoot,
+  assertSafeRelPath,
+  buildGithubBlobUrl,
+  buildGithubRawUrl,
+  buildMetaOk,
+  builtinClientAdapters,
+  clearLoadBundleCache,
+  clearQmdStoreCache,
+  createAiDocsFacade,
+  createClientAdapterRegistry,
+  defaultClientAdapterRegistry,
+  elapsedMs,
+  errResult,
+  fetchSdkSource,
+  getComponent,
+  getComponentDoc,
+  getGuardrails,
+  getHook,
+  getPackageSurface,
+  getRecipe,
+  getReleaseContext,
+  getType,
+  getWorkflow,
+  loadBundle,
+  manifestExistsAtRepoRoot,
+  okResult,
+  readEntityJson,
+  resolveAiDocsRepoRoot,
+  resolveBundledSyntheticRepoRoot,
+  resolveComponentDocAbsPath,
+  resolveEntityByArtifactKind,
+  resolveRepoRoot,
+  searchDocs
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/mcp-cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node