rbxstudio-mcp 2.3.2 → 2.4.0

package/dist/docs/embeddings/manager.js

@@ -0,0 +1,97 @@
+import { buildIndex, loadIndex } from './index.js';
+import { EMBED_MODEL } from './embedder.js';
+let cached = null;
+/** In-flight load/build promise for de-duplication of concurrent calls. */
+let inFlight = null;
+/**
+ * Test seam: lets unit tests inject a precanned index and skip the
+ * load/build path entirely. The keyword + hybrid rerank machinery
+ * uses `getOrBuild` directly, so injecting here is enough to
+ * deterministically exercise reranking.
+ */
+export function __setIndexForTests(entry) {
+    cached = entry;
+    inFlight = null;
+}
+/**
+ * Return a usable in-memory index for `cacheDir`@`docsSha`, building
+ * it if necessary. Returns null when the index can't be obtained — the
+ * caller should fall back to keyword-only mode in that case.
+ *
+ * Decision tree:
+ *   1. We already have a hot index for this (cacheDir, sha) → return it.
+ *   2. Otherwise try to loadIndex() from disk — if it matches the sha,
+ *      cache + return it.
+ *   3. Otherwise, if loadOnly: return null.
+ *   4. Otherwise build a fresh index. Heavy: ~25MB model download +
+ *      embedding ~19k chunks. Measured at ~8 minutes on a single CPU
+ *      box; faster on multi-core / GPU. Subsequent process restarts
+ *      load from disk in <100ms.
+ *
+ * Errors during build are swallowed (returned as null) because we
+ * don't want a semantic-index failure to break the keyword search.
+ */
+export async function getOrBuild(cacheDir, docsSha, options = {}) {
+    if (cached && cached.cacheDir === cacheDir && cached.sha === docsSha) {
+        return cached.index;
+    }
+    if (inFlight)
+        return inFlight;
+    inFlight = (async () => {
+        try {
+            // 1. Try disk first — if the on-disk index matches our expected
+            //    sha+model, just memo it.
+            const loaded = await loadIndex(cacheDir, docsSha, EMBED_MODEL);
+            if (loaded) {
+                cached = { cacheDir, sha: docsSha, index: loaded };
+                return loaded;
+            }
+            if (options.loadOnly)
+                return null;
+            // 2. Build from scratch. Heavy: model download + embed every
+            //    chunk. Subsequent process restarts hit the disk cache.
+            const meta = await buildIndex(cacheDir, docsSha, {
+                model: EMBED_MODEL,
+                onProgress: options.onProgress,
+            });
+            // Reload from disk after building — keeps the load/build paths
+            // exercising the same code (so a bug in load doesn't only
+            // manifest after a process restart).
+            const built = await loadIndex(cacheDir, docsSha, EMBED_MODEL);
+            if (!built) {
+                // Shouldn't happen — we just wrote it. Log via stderr so a
+                // partial build is at least visible.
+                // eslint-disable-next-line no-console
+                console.error(`[rbxstudio-mcp] built docs index reported ${meta.chunkCount} chunks but reload failed`);
+                return null;
+            }
+            cached = { cacheDir, sha: docsSha, index: built };
+            return built;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error(`[rbxstudio-mcp] semantic index unavailable (${err?.message ?? err}); ` +
+                `falling back to keyword-only search`);
+            return null;
+        }
+        finally {
+            inFlight = null;
+        }
+    })();
+    return inFlight;
+}
+/**
+ * Drop the in-memory cache. Used when the docs cache itself is
+ * re-fetched and we know the on-disk vectors are now stale. The
+ * fetcher (or its caller) is expected to nuke the index directory
+ * separately if it wants the on-disk vectors gone too — typically
+ * `buildIndex` will overwrite atomically on the next call anyway.
+ */
+export function invalidate() {
+    cached = null;
+}
+/** Diagnostic: is anything cached right now? */
+export function currentMeta() {
+    return cached?.index.meta ?? null;
+}
+//# sourceMappingURL=manager.js.map

package/dist/docs/embeddings/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/docs/embeddings/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAkC,MAAM,YAAY,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AA2B5C,IAAI,MAAM,GAAuB,IAAI,CAAC;AACtC,2EAA2E;AAC3E,IAAI,QAAQ,GAAqC,IAAI,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,MAAM,GAAG,KAAK,CAAC;IACf,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB,EAChB,OAAe,EACf,UAA6B,EAAE;IAE/B,IAAI,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QACrE,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;QACrB,IAAI,CAAC;YACH,gEAAgE;YAChE,8BAA8B;YAC9B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;YAC/D,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;gBACnD,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,IAAI,OAAO,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAElC,6DAA6D;YAC7D,4DAA4D;YAC5D,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE;gBAC/C,KAAK,EAAE,WAAW;gBAClB,UAAU,EAAE,OAAO,CAAC,UAAU;aAC/B,CAAC,CAAC;YACH,+DAA+D;YAC/D,0DAA0D;YAC1D,qCAAqC;YACrC,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;YAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,2DAA2D;gBAC3D,qCAAqC;gBACrC,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CACX,6CAA6C,IAAI,CAAC,UAAU,2BAA2B,CACxF,CAAC;gBACF,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAClD,OAAO,KAAK,CAAC;QACf,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,sCAAsC;YACtC,OAAO,CAAC,KAAK,CACX,+CAA+C,GAAG,EAAE,OAAO,IAAI,GAAG,KAAK;gBACrE,qCAAqC,CACxC,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,WAAW;IACzB,OAAO,MAAM,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC;AACpC,CAAC"}

package/dist/docs/fetcher.d.ts

@@ -0,0 +1,29 @@
+import { type DocsMeta } from './cache.js';
+export interface EnsureDocsResult {
+    cacheDir: string;
+    meta: DocsMeta;
+    /** What did this call actually do? */
+    action: 'fresh' | 'sha-short-circuit' | 'redownloaded' | 'first-download';
+    /** Wall-clock duration of the operation in ms. */
+    durationMs: number;
+}
+export interface EnsureDocsOptions {
+    /** Force a redownload regardless of TTL/SHA. */
+    force?: boolean;
+    /** Override the TTL window (ms). Default 24h. */
+    ttlMs?: number;
+}
+/**
+ * Public entry point used by all docs tools. Guarantees that, by the
+ * time it returns, `cacheDir/content/...` contains a usable mirror of
+ * the docs (or throws).
+ *
+ * Decision tree:
+ *   1. No cache on disk          → first-download
+ *   2. force=true                → redownloaded
+ *   3. cache age <= TTL          → fresh (no network call)
+ *   4. cache age >  TTL && SHA same → sha-short-circuit (network: SHA only)
+ *   5. cache age >  TTL && SHA different → redownloaded
+ */
+export declare function ensureDocsCache(options?: EnsureDocsOptions): Promise<EnsureDocsResult>;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/docs/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../src/docs/fetcher.ts"],"names":[],"mappings":"AAKA,OAAO,EAQL,KAAK,QAAQ,EACd,MAAM,YAAY,CAAC;AA0DpB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,OAAO,GAAG,mBAAmB,GAAG,cAAc,GAAG,gBAAgB,CAAC;IAC1E,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA8FD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgDhG"}

package/dist/docs/fetcher.js

@@ -0,0 +1,244 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+import * as tar from 'tar';
+import { approxSizeOnDisk, clearContent, contentRoot, ensureCacheDir, readMeta, resolveCacheDir, writeMeta, } from './cache.js';
+import { clearIndex } from './embeddings/index.js';
+import { invalidate as invalidateSemanticIndex } from './embeddings/manager.js';
+/**
+ * Mirror Roblox/creator-docs locally as a flat file tree, refreshed on
+ * demand.
+ *
+ * Why tarball instead of `git clone`?
+ *   1. No git binary requirement — works on any Node install.
+ *   2. ~30MB filtered tarball downloads in ~3s on a normal connection.
+ *   3. We don't need history, only the current tree.
+ *
+ * Why scope-filter to a subset of `content/en-us/`?
+ *   The full creator-docs repo is ~200MB. The AI overwhelmingly needs
+ *   the API reference (`reference/engine`) plus the long-form guides
+ *   for things it tends to struggle with (animation, characters, ui,
+ *   workspace). Filtering during extract keeps the on-disk footprint
+ *   to ~30MB.
+ */
+const REPO_OWNER = 'Roblox';
+const REPO_NAME = 'creator-docs';
+const REPO_BRANCH = 'main';
+/**
+ * Path prefixes (relative to repo root) we keep on disk.
+ *
+ * After the tarball is extracted with `strip: 2`, the leading
+ * `<repo>-<branch>/content/` is removed, so on-disk these become
+ * `<cacheDir>/content/en-us/...`. The filter however receives the
+ * pre-strip path, so we match the `content/en-us/...` form here.
+ */
+const KEEP_PREFIXES = [
+    'content/en-us/reference/',
+    'content/en-us/animation/',
+    'content/en-us/characters/',
+    'content/en-us/ui/',
+    'content/en-us/scripting/',
+    'content/en-us/physics/',
+    'content/en-us/workspace/',
+    'content/en-us/players/',
+    'content/en-us/input/',
+    'content/en-us/cloud-services/',
+    'content/en-us/sound/',
+];
+/** File extensions we keep within the prefixes above. */
+const KEEP_EXTENSIONS = new Set(['.md', '.yaml', '.yml']);
+/** GitHub API: latest commit SHA on a branch. */
+const REFS_URL = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/commits/${REPO_BRANCH}`;
+/** codeload.github.com tarball — much faster + no auth required. */
+const TARBALL_URL = `https://codeload.github.com/${REPO_OWNER}/${REPO_NAME}/tar.gz/refs/heads/${REPO_BRANCH}`;
+/** How long a cache entry is "fresh enough" before we re-check upstream. */
+const TTL_MS = 24 * 60 * 60 * 1000; // 24h
+function commonHeaders() {
+    // Identify ourselves to GitHub. They rate-limit unauthenticated
+    // requests but the daily SHA check is well under the limit.
+    return {
+        'User-Agent': 'rbxstudio-mcp (Roblox docs cache, https://github.com/boshyxd/robloxstudio-mcp)',
+        Accept: 'application/vnd.github+json',
+    };
+}
+/** Hit GitHub's commits API to get the current head SHA on `main`. */
+async function fetchHeadSha() {
+    const res = await fetch(REFS_URL, { headers: commonHeaders() });
+    if (!res.ok) {
+        throw new Error(`GitHub API ${res.status} ${res.statusText} when fetching ${REFS_URL}`);
+    }
+    const body = await res.json();
+    if (typeof body?.sha !== 'string') {
+        throw new Error('GitHub API returned no sha for HEAD commit');
+    }
+    return body.sha;
+}
+/**
+ * Strip the leading `<repo>-<branch>/` directory that codeload tarballs
+ * wrap everything in, returning the path relative to the repo root.
+ * Returns null for the wrapper directory entry itself.
+ */
+function relativizeTarPath(tarPath) {
+    const slash = tarPath.indexOf('/');
+    if (slash < 0)
+        return null;
+    const rel = tarPath.slice(slash + 1);
+    if (!rel || rel === '/')
+        return null;
+    return rel;
+}
+/**
+ * Download the tarball and stream it through tar's extractor with a
+ * filter so only matching paths are written to disk.
+ *
+ * Note on tar v7 behavior: the `filter` callback receives the ORIGINAL
+ * (pre-strip) path, not the post-strip path. `strip:1` only affects the
+ * on-disk output path. So we relativize here just to make the filter
+ * comparison readable.
+ */
+async function downloadAndExtract(cacheDir) {
+    const dest = contentRoot(cacheDir);
+    // Wipe before extract so deleted upstream files don't linger.
+    await clearContent(cacheDir);
+    await fs.mkdir(dest, { recursive: true });
+    const res = await fetch(TARBALL_URL, { headers: commonHeaders() });
+    if (!res.ok || !res.body) {
+        throw new Error(`Tarball download failed: ${res.status} ${res.statusText} from ${TARBALL_URL}`);
+    }
+    let fileCount = 0;
+    const extractor = tar.x({
+        cwd: dest,
+        // `strip: 2` drops both the "<repo>-<branch>/" wrapper directory AND
+        // the upstream "content/" directory, so on-disk we end up with
+        //   <cacheDir>/content/en-us/reference/engine/classes/Motor6D.yaml
+        // matching what `contentRoot()` expects.
+        //
+        // Filter still sees the ORIGINAL pre-strip path
+        // (`creator-docs-main/content/en-us/…`), which is why we relativize
+        // it manually before checking against KEEP_PREFIXES.
+        strip: 2,
+        filter: (tarPath) => {
+            const rel = relativizeTarPath(tarPath);
+            if (!rel)
+                return false;
+            // Directory entries end in `/` — let tar create them if needed.
+            // We only care about counting / filtering files.
+            if (rel.endsWith('/')) {
+                return KEEP_PREFIXES.some((p) => p.startsWith(rel) || rel.startsWith(p));
+            }
+            if (!KEEP_PREFIXES.some((p) => rel.startsWith(p)))
+                return false;
+            const ext = path.extname(rel).toLowerCase();
+            if (!KEEP_EXTENSIONS.has(ext))
+                return false;
+            fileCount++;
+            return true;
+        },
+    });
+    // node-fetch / undici body is a Web ReadableStream. Convert to a
+    // Node Readable and pipe into tar.
+    const nodeStream = Readable.fromWeb(res.body);
+    await pipeline(nodeStream, extractor);
+    return { fileCount };
+}
+/**
+ * Public entry point used by all docs tools. Guarantees that, by the
+ * time it returns, `cacheDir/content/...` contains a usable mirror of
+ * the docs (or throws).
+ *
+ * Decision tree:
+ *   1. No cache on disk          → first-download
+ *   2. force=true                → redownloaded
+ *   3. cache age <= TTL          → fresh (no network call)
+ *   4. cache age >  TTL && SHA same → sha-short-circuit (network: SHA only)
+ *   5. cache age >  TTL && SHA different → redownloaded
+ */
+export async function ensureDocsCache(options = {}) {
+    const cacheDir = resolveCacheDir();
+    const ttlMs = options.ttlMs ?? TTL_MS;
+    const t0 = Date.now();
+    await ensureCacheDir(cacheDir);
+    const existing = await readMeta(cacheDir);
+    // 1. No cache yet.
+    if (!existing || !existing.sha) {
+        return await doDownload(cacheDir, t0, 'first-download');
+    }
+    // 2. Forced.
+    if (options.force) {
+        return await doDownload(cacheDir, t0, 'redownloaded');
+    }
+    // 3. Within TTL window — trust the cache.
+    const downloadedAt = Date.parse(existing.downloadedAt);
+    const fresh = Number.isFinite(downloadedAt) && Date.now() - downloadedAt <= ttlMs;
+    if (fresh) {
+        return {
+            cacheDir,
+            meta: existing,
+            action: 'fresh',
+            durationMs: Date.now() - t0,
+        };
+    }
+    // 4 / 5. TTL expired — ask GitHub if anything changed.
+    const upstreamSha = await fetchHeadSha();
+    if (upstreamSha === existing.sha) {
+        // Just bump lastCheckedAt so the next call hits TTL again.
+        const updated = {
+            ...existing,
+            lastCheckedAt: new Date().toISOString(),
+        };
+        await writeMeta(cacheDir, updated);
+        return {
+            cacheDir,
+            meta: { ...updated, schemaVersion: 1 },
+            action: 'sha-short-circuit',
+            durationMs: Date.now() - t0,
+        };
+    }
+    return await doDownload(cacheDir, t0, 'redownloaded');
+}
+async function doDownload(cacheDir, t0, action) {
+    // Get the SHA we're locking to. If this fails, we can't sensibly
+    // record provenance, but the tarball itself is the source of truth.
+    let sha = '';
+    try {
+        sha = await fetchHeadSha();
+    }
+    catch {
+        // Network blip on the SHA endpoint shouldn't block the download.
+        sha = '';
+    }
+    const { fileCount } = await downloadAndExtract(cacheDir);
+    const bytesOnDisk = await approxSizeOnDisk(contentRoot(cacheDir));
+    const now = new Date().toISOString();
+    const meta = {
+        repo: `${REPO_OWNER}/${REPO_NAME}`,
+        branch: REPO_BRANCH,
+        sha,
+        downloadedAt: now,
+        lastCheckedAt: now,
+        fileCount,
+        bytesOnDisk,
+    };
+    await writeMeta(cacheDir, meta);
+    // Vectors are tied 1:1 to the file tree we just blew away. Drop the
+    // in-memory cache and the on-disk index so the next semantic query
+    // rebuilds from the fresh docs. (We don't proactively rebuild here
+    // — that would block this call for ~60s for a feature the caller
+    // might not even use.)
+    invalidateSemanticIndex();
+    try {
+        await clearIndex(cacheDir);
+    }
+    catch {
+        // Best-effort — a stale index is annoying but not fatal; the
+        // schema/sha check inside loadIndex() will reject it next time.
+    }
+    return {
+        cacheDir,
+        meta: { ...meta, schemaVersion: 1 },
+        action,
+        durationMs: Date.now() - t0,
+    };
+}
+//# sourceMappingURL=fetcher.js.map

package/dist/docs/fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.js","sourceRoot":"","sources":["../../src/docs/fetcher.ts"],"names":[],"mappings":"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"}

package/dist/docs/reference.d.ts

@@ -0,0 +1,37 @@
+declare const CATEGORY_DIRS: {
+    readonly class: "classes";
+    readonly datatype: "datatypes";
+    readonly enum: "enums";
+    readonly global: "globals";
+    readonly library: "libraries";
+};
+export type ReferenceCategory = keyof typeof CATEGORY_DIRS;
+export interface ReferenceLookupResult {
+    /** Where it was found, e.g. "classes" or "datatypes". */
+    category: ReferenceCategory;
+    /** The canonical name as it appears on disk (e.g. "Motor6D"). */
+    name: string;
+    /** Path relative to the content root. */
+    path: string;
+    /** Parsed YAML body. Shape mirrors creator-docs' API schema. */
+    data: unknown;
+    /** Raw YAML source — handy for grep-style follow-ups. */
+    raw: string;
+}
+/**
+ * Resolve a bare name like "Motor6D" or "CFrame" to a parsed YAML doc.
+ *
+ * Resolution order (when `category` is omitted):
+ *   1. classes
+ *   2. datatypes
+ *   3. enums
+ *   4. globals
+ *   5. libraries
+ *
+ * The first match wins. Roblox's namespace doesn't currently have name
+ * collisions across these categories that I know of, but if it ever
+ * does the caller can disambiguate via `category`.
+ */
+export declare function resolveReference(cacheDir: string, name: string, category?: ReferenceCategory): Promise<ReferenceLookupResult | null>;
+export {};
+//# sourceMappingURL=reference.d.ts.map

package/dist/docs/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../src/docs/reference.ts"],"names":[],"mappings":"AAwBA,QAAA,MAAM,aAAa;;;;;;CAMT,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,aAAa,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,OAAO,CAAC;IACd,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;CACb;AAmCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAgCvC"}

package/dist/docs/reference.js

@@ -0,0 +1,108 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { contentRoot } from './cache.js';
+/**
+ * `get_roblox_api_reference` resolver.
+ *
+ * The creator-docs repo stores structured API reference under:
+ *
+ *   content/en-us/reference/engine/
+ *     classes/<ClassName>.yaml      (e.g. Motor6D.yaml, Part.yaml)
+ *     datatypes/<TypeName>.yaml     (e.g. CFrame.yaml, Vector3.yaml)
+ *     enums/<EnumName>.yaml         (e.g. Material.yaml, KeyCode.yaml)
+ *     globals/<API>.yaml            (e.g. RobloxGlobals.yaml)
+ *     libraries/<Lib>.yaml          (e.g. math.yaml, string.yaml)
+ *
+ * The model usually knows what it's looking for ("Motor6D", "CFrame",
+ * "Material") but doesn't know which subdirectory to look in. This
+ * module resolves a name to the correct file and returns parsed YAML.
+ */
+const ENGINE_REL = path.join('en-us', 'reference', 'engine');
+const CATEGORY_DIRS = {
+    class: 'classes',
+    datatype: 'datatypes',
+    enum: 'enums',
+    global: 'globals',
+    library: 'libraries',
+};
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findInDir(dir, name) {
+    // Try the obvious filename first (cheap, no readdir).
+    const direct = path.join(dir, `${name}.yaml`);
+    if (await exists(direct))
+        return direct;
+    // Fall back to a case-insensitive scan. Roblox YAML names are
+    // PascalCase, but the model sometimes lowercases them ("part",
+    // "cframe"). Scanning the directory once is fine — there are
+    // <2k files total across all categories.
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return null;
+    }
+    const target = `${name.toLowerCase()}.yaml`;
+    for (const f of entries) {
+        if (f.toLowerCase() === target) {
+            return path.join(dir, f);
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a bare name like "Motor6D" or "CFrame" to a parsed YAML doc.
+ *
+ * Resolution order (when `category` is omitted):
+ *   1. classes
+ *   2. datatypes
+ *   3. enums
+ *   4. globals
+ *   5. libraries
+ *
+ * The first match wins. Roblox's namespace doesn't currently have name
+ * collisions across these categories that I know of, but if it ever
+ * does the caller can disambiguate via `category`.
+ */
+export async function resolveReference(cacheDir, name, category) {
+    if (!name)
+        return null;
+    const root = path.join(contentRoot(cacheDir), ENGINE_REL);
+    const order = category
+        ? [category]
+        : ['class', 'datatype', 'enum', 'global', 'library'];
+    for (const cat of order) {
+        const dir = path.join(root, CATEGORY_DIRS[cat]);
+        const hit = await findInDir(dir, name);
+        if (!hit)
+            continue;
+        const raw = await fs.readFile(hit, 'utf8');
+        let data = null;
+        try {
+            data = yaml.load(raw, { filename: hit, schema: yaml.JSON_SCHEMA });
+        }
+        catch (err) {
+            // Don't fail the tool call just because YAML parse went sideways
+            // — return the raw text so the model can still grep through it.
+            data = { __parseError: err?.message ?? String(err) };
+        }
+        return {
+            category: cat,
+            name: path.basename(hit, '.yaml'),
+            path: path.relative(contentRoot(cacheDir), hit),
+            data,
+            raw,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=reference.js.map

package/dist/docs/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../src/docs/reference.ts"],"names":[],"mappings":"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"}