@readymadeit/mcp 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,6 @@
+export { startHttpServer } from "./http.js";
+export { findRepositoryRoot, KnowledgeRepository } from "./repository.js";
+export { readymadeToolSchemas } from "./schemas.js";
+export { createReadymadeMcpServer } from "./server.js";
+export * from "./types.js";
+export { validateBoard } from "./validation.js";

package/dist/repository.d.ts

@@ -0,0 +1,49 @@
+import { type KnowledgeKind, type KnowledgeReference, type Provenance, type RuntimeName, type ServiceContract } from "./types.js";
+import { type ValidationCatalog } from "./validation.js";
+export declare class KnowledgeRepository implements ValidationCatalog {
+    readonly root: string;
+    readonly buildVersion: string;
+    readonly commit: string;
+    readonly indexedAt: string;
+    private readonly entries;
+    private readonly sourceEntries;
+    private readonly byPath;
+    private readonly contracts;
+    private constructor();
+    static create(root: string, buildVersion?: string): Promise<KnowledgeRepository>;
+    private buildContracts;
+    /** Every indexed service contract, one per runtime and service ID. */
+    listContracts(): readonly ServiceContract[];
+    hasService(serviceId: string, runtime?: RuntimeName): boolean;
+    search(query: string, options?: {
+        runtime?: RuntimeName;
+        kind?: KnowledgeKind;
+        limit?: number;
+    }): KnowledgeReference[];
+    readDocuments(paths: string[]): Array<{
+        content: string;
+        provenance: Provenance;
+    }>;
+    getServiceContract(serviceId: string, runtime: RuntimeName, version?: string): ServiceContract;
+    findCompatibleServices(inputType: string, outputType: string, runtime?: RuntimeName): ServiceContract[];
+    findBoardExamples(serviceIds: string[], runtime?: RuntimeName, limit?: number): KnowledgeReference[];
+    inspectServiceSource(serviceId: string, runtime: RuntimeName, version?: string, maxLines?: number): Array<{
+        content: string;
+        lineStart: number;
+        lineEnd: number;
+        provenance: Provenance;
+    }>;
+    validateBoard(board: unknown): import("./types.js").BoardValidationResult;
+    stats(): {
+        documents: number;
+        boards: number;
+        contracts: number;
+        sourceFiles: number;
+        buildVersion: string;
+        commit: string;
+        indexedAt: string;
+    };
+    private findSourceEntries;
+}
+export declare function findRepositoryRoot(start?: string): Promise<string>;
+//# sourceMappingURL=repository.d.ts.map

package/dist/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AA+MxE,qBAAa,mBAAoB,YAAW,iBAAiB;IAKzD,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAThC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,OAAO;WAYM,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,SAAqD,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA+DlI,OAAO,CAAC,cAAc;IAwBtB,sEAAsE;IACtE,aAAa,IAAI,SAAS,eAAe,EAAE;IAI3C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO;IAK7D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,WAAW,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,kBAAkB,EAAE;IAsB1H,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,CAAC;IAWlF,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe;IAa9F,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,eAAe,EAAE;IAavG,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,SAAK,GAAG,kBAAkB,EAAE;IAoBhG,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,CAAC;IAmBvL,aAAa,CAAC,KAAK,EAAE,OAAO;IAI5B,KAAK;;;;;;;;;IAIL,OAAO,CAAC,iBAAiB;CAoB1B;AAED,wBAAsB,kBAAkB,CAAC,KAAK,SAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAY/E"}

package/dist/repository.js

@@ -0,0 +1,452 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { readBundleCommits, readCommit } from "./git.js";
+import { canonicalServiceId, normalizeRuntime, } from "./types.js";
+import { validateBoard } from "./validation.js";
+// scripts/bundle.mjs copies these folders; keep the two lists in step.
+const sourceRoots = [
+    { directory: "hkp-frontend/src/runtime/browser", repository: "readymade", runtime: "browser", extensions: [".ts", ".tsx"] },
+    { directory: "hkp-node/src", repository: "hkp-node", runtime: "node", extensions: [".ts"] },
+    { directory: "hkp-python/src/hkp", repository: "hkp-python", runtime: "python", extensions: [".py"] },
+    { directory: "hkp-rt/lib", repository: "readymade", runtime: "cpp", extensions: [".h", ".hpp", ".cpp"] },
+];
+const knownTypes = [
+    "FloatRingBuffer",
+    "ControlFlowData",
+    "BinaryData",
+    "MixedData",
+    "TextData",
+    "Undefined",
+    "String",
+    "JSON",
+    "Null",
+    "Any",
+];
+function contentSha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+async function walk(directory, extensions) {
+    const result = [];
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist")
+            continue;
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            result.push(...await walk(absolute, extensions));
+        else if (entry.isFile() && extensions.includes(path.extname(entry.name).toLowerCase()))
+            result.push(absolute);
+    }
+    return result;
+}
+function heading(content, fallback) {
+    return /^#\s+(.+)$/m.exec(content)?.[1].trim() ?? fallback;
+}
+function firstParagraph(content) {
+    const withoutTitle = content.replace(/^#\s+.+\n+/, "");
+    return withoutTitle.split(/\n\s*\n/).map((part) => part.trim()).find((part) => part && !part.startsWith("---") && !part.startsWith("#")) ?? "";
+}
+function section(content, names) {
+    const escaped = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+    const match = new RegExp(`^##\\s+(?:${escaped})\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im").exec(content);
+    return match?.[1]?.trim() ?? "";
+}
+function extractTypes(value) {
+    const result = new Set();
+    for (const type of knownTypes) {
+        if (new RegExp(`\\b${type}\\b`, "i").test(value))
+            result.add(type);
+    }
+    if (/any\s+(?:json\s+)?value/i.test(value))
+        result.add("Any");
+    if (/object|array|structured/i.test(value))
+        result.add("JSON");
+    return [...result];
+}
+function parseAvailability(content) {
+    const found = new Map();
+    // `| Runtime | `id` |`, or several ids in one cell when a page documents
+    // services that belong together: `| Browser | `a`, `b` |`. The cell must hold
+    // nothing but ids, which keeps configuration tables out.
+    const tablePattern = /^\|\s*([^|]+?)\s*\|\s*(`[^`]+`(?:\s*,\s*`[^`]+`)*)\s*\|/gm;
+    const bulletPattern = /^[-*]\s+(.+?)\s+[—-]+\s+service ID\s+(`[^`]+`)/gim;
+    for (const pattern of [tablePattern, bulletPattern]) {
+        for (const match of content.matchAll(pattern)) {
+            const runtime = normalizeRuntime(match[1]);
+            if (!runtime)
+                continue;
+            for (const id of match[2].matchAll(/`([^`]+)`/g)) {
+                const serviceId = id[1].trim();
+                found.set(`${runtime}:${serviceId}`, { runtime, serviceId });
+            }
+        }
+    }
+    return [...found.values()];
+}
+function parseConfiguration(content) {
+    const configuration = section(content, ["Configuration", "Configuration options", "Configuration Options"]);
+    const result = [];
+    for (const line of configuration.split("\n")) {
+        const cells = splitMarkdownTableRow(line).map((cell) => cell.trim().replace(/^`|`$/g, ""));
+        if (cells.length < 3 || /^-+$/.test(cells[0]) || /^property$/i.test(cells[0]))
+            continue;
+        result.push({
+            property: cells[0].replace(/`/g, ""),
+            type: cells[1].replace(/`/g, ""),
+            defaultValue: cells.length >= 4 ? cells[2].replace(/`/g, "") : undefined,
+            description: cells.at(-1)?.replace(/`/g, "") ?? "",
+        });
+    }
+    return result;
+}
+function splitMarkdownTableRow(line) {
+    if (!line.trim().startsWith("|"))
+        return [];
+    const cells = [];
+    let cell = "";
+    let inCode = false;
+    for (let index = 1; index < line.length; index += 1) {
+        const character = line[index];
+        if (character === "`" && line[index - 1] !== "\\")
+            inCode = !inCode;
+        if (character === "|" && line[index - 1] !== "\\" && !inCode) {
+            cells.push(cell.replaceAll("\\|", "|"));
+            cell = "";
+        }
+        else {
+            cell += character;
+        }
+    }
+    if (cell.trim())
+        cells.push(cell);
+    return cells;
+}
+function parseServiceDocument(content, fallbackName) {
+    const availability = parseAvailability(content);
+    const io = section(content, ["Input / Output", "Input and output", "Input and Output", "Output Data"]);
+    const inputLines = io.split("\n").filter((line) => /input/i.test(line)).join(" ");
+    const outputLines = io.split("\n").filter((line) => /output|emits|returns/i.test(line)).join(" ");
+    return {
+        name: heading(content, fallbackName),
+        summary: firstParagraph(content),
+        availability,
+        inputTypes: extractTypes(inputLines),
+        outputTypes: extractTypes(outputLines || io),
+        configuration: parseConfiguration(content),
+    };
+}
+function serviceIdsFromBoard(value, output = new Set()) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            serviceIdsFromBoard(entry, output);
+    }
+    else if (typeof value === "object" && value !== null) {
+        const object = value;
+        if (typeof object.serviceId === "string")
+            output.add(canonicalServiceId(object.serviceId));
+        for (const nested of Object.values(object))
+            serviceIdsFromBoard(nested, output);
+    }
+    return output;
+}
+function runtimesFromBoard(value) {
+    if (typeof value !== "object" || value === null || !Array.isArray(value.runtimes))
+        return [];
+    const result = new Set();
+    for (const runtime of value.runtimes) {
+        if (typeof runtime !== "object" || runtime === null)
+            continue;
+        const item = runtime;
+        const normalized = item.type === "browser" ? "browser" : normalizeRuntime(`${item.name ?? ""} ${item.id ?? ""} ${item.url ?? ""}`);
+        if (normalized)
+            result.add(normalized);
+    }
+    return [...result];
+}
+function excerpt(content, queryTokens, maxLength = 700) {
+    const lower = content.toLowerCase();
+    const indexes = queryTokens.map((token) => lower.indexOf(token)).filter((index) => index >= 0);
+    const center = indexes.length ? Math.min(...indexes) : 0;
+    const start = Math.max(0, center - Math.floor(maxLength / 3));
+    const prefix = start > 0 ? "…" : "";
+    const suffix = start + maxLength < content.length ? "…" : "";
+    return `${prefix}${content.slice(start, start + maxLength).trim()}${suffix}`;
+}
+function score(entry, tokens) {
+    const pathText = `${entry.relativePath} ${entry.title} ${entry.serviceIds.join(" ")}`.toLowerCase();
+    const content = entry.content.toLowerCase();
+    let value = 0;
+    for (const token of tokens) {
+        if (pathText.includes(token))
+            value += 12;
+        const matches = content.split(token).length - 1;
+        value += Math.min(matches, 8);
+    }
+    return value;
+}
+function provenanceFor(entry, requestedVersion) {
+    return { ...entry.provenance, exactBuildMatch: !requestedVersion || requestedVersion === entry.provenance.buildVersion };
+}
+export class KnowledgeRepository {
+    root;
+    buildVersion;
+    commit;
+    indexedAt;
+    entries;
+    sourceEntries;
+    byPath = new Map();
+    contracts = [];
+    constructor(root, buildVersion, commit, indexedAt, entries, sourceEntries) {
+        this.root = root;
+        this.buildVersion = buildVersion;
+        this.commit = commit;
+        this.indexedAt = indexedAt;
+        this.entries = entries;
+        this.sourceEntries = sourceEntries;
+        for (const entry of entries)
+            this.byPath.set(entry.relativePath, entry);
+        this.buildContracts();
+    }
+    static async create(root, buildVersion = process.env.READYMADE_BUILD_VERSION ?? "workspace") {
+        const absoluteRoot = path.resolve(root);
+        const bundleCommits = await readBundleCommits(absoluteRoot);
+        const rootCommit = bundleCommits?.readymade ?? await readCommit(absoluteRoot);
+        const indexedAt = new Date().toISOString();
+        const entries = [];
+        const sourceEntries = [];
+        for (const absolute of await walk(path.join(absoluteRoot, "docs", "content"), [".md"])) {
+            const relativePath = path.relative(absoluteRoot, absolute).split(path.sep).join("/");
+            const content = await readFile(absolute, "utf8");
+            const isService = relativePath.startsWith("docs/content/services/");
+            const parsed = isService ? parseServiceDocument(content, path.basename(absolute, ".md")) : undefined;
+            entries.push({
+                kind: isService ? "service" : "documentation",
+                title: heading(content, path.basename(absolute, ".md")),
+                relativePath,
+                content,
+                runtimes: parsed ? [...new Set(parsed.availability.map((item) => item.runtime))] : [],
+                serviceIds: parsed ? [...new Set(parsed.availability.map((item) => canonicalServiceId(item.serviceId)))] : [],
+                provenance: { repository: "readymade", commit: rootCommit, contentSha256: contentSha256(content), path: relativePath, buildVersion, exactBuildMatch: true, indexedAt },
+            });
+        }
+        for (const absolute of await walk(path.join(absoluteRoot, "boards"), [".json"])) {
+            const relativePath = path.relative(absoluteRoot, absolute).split(path.sep).join("/");
+            const content = await readFile(absolute, "utf8");
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                parsed = undefined;
+            }
+            const boardName = typeof parsed === "object" && parsed !== null && typeof parsed.boardName === "string"
+                ? String(parsed.boardName)
+                : path.basename(absolute, ".json");
+            entries.push({
+                kind: "board",
+                title: boardName,
+                relativePath,
+                content,
+                runtimes: runtimesFromBoard(parsed),
+                serviceIds: [...serviceIdsFromBoard(parsed)],
+                provenance: { repository: "readymade", commit: rootCommit, contentSha256: contentSha256(content), path: relativePath, buildVersion, exactBuildMatch: true, indexedAt },
+            });
+        }
+        for (const sourceRoot of sourceRoots) {
+            const worktree = path.join(absoluteRoot, sourceRoot.directory.split("/")[0]);
+            const sourceCommit = sourceRoot.repository === "readymade" ? rootCommit : bundleCommits?.[sourceRoot.repository] ?? await readCommit(worktree);
+            for (const absolute of await walk(path.join(absoluteRoot, sourceRoot.directory), sourceRoot.extensions)) {
+                const relativePath = path.relative(absoluteRoot, absolute).split(path.sep).join("/");
+                const content = await readFile(absolute, "utf8");
+                sourceEntries.push({
+                    kind: "source",
+                    title: path.basename(absolute),
+                    relativePath,
+                    content,
+                    runtimes: [sourceRoot.runtime],
+                    serviceIds: [],
+                    provenance: { repository: sourceRoot.repository, commit: sourceCommit, contentSha256: contentSha256(content), path: relativePath, buildVersion, exactBuildMatch: true, indexedAt },
+                });
+            }
+        }
+        return new KnowledgeRepository(absoluteRoot, buildVersion, rootCommit, indexedAt, entries, sourceEntries);
+    }
+    buildContracts() {
+        for (const entry of this.entries.filter((item) => item.kind === "service")) {
+            const parsed = parseServiceDocument(entry.content, entry.title);
+            for (const availability of parsed.availability) {
+                const canonical = canonicalServiceId(availability.serviceId);
+                const sourceReferences = this.findSourceEntries(canonical, availability.runtime, 5).map((source) => source.provenance);
+                this.contracts.push({
+                    serviceId: availability.serviceId,
+                    name: parsed.name,
+                    runtime: availability.runtime,
+                    aliases: parsed.availability
+                        .filter((item) => item.runtime === availability.runtime && item.serviceId !== availability.serviceId)
+                        .map((item) => item.serviceId),
+                    inputTypes: parsed.inputTypes,
+                    outputTypes: parsed.outputTypes,
+                    configuration: parsed.configuration,
+                    summary: parsed.summary,
+                    documentation: entry.provenance,
+                    sourceReferences,
+                });
+            }
+        }
+    }
+    /** Every indexed service contract, one per runtime and service ID. */
+    listContracts() {
+        return this.contracts;
+    }
+    hasService(serviceId, runtime) {
+        const canonical = canonicalServiceId(serviceId);
+        return this.contracts.some((contract) => canonicalServiceId(contract.serviceId) === canonical && (!runtime || contract.runtime === runtime));
+    }
+    search(query, options = {}) {
+        const tokens = query.toLowerCase().split(/[^a-z0-9_./-]+/).filter((token) => token.length > 1);
+        if (!tokens.length)
+            return [];
+        const limit = Math.max(1, Math.min(options.limit ?? 8, 20));
+        return this.entries
+            .filter((entry) => !options.kind || entry.kind === options.kind)
+            .filter((entry) => !options.runtime || entry.runtimes.length === 0 || entry.runtimes.includes(options.runtime))
+            .map((entry) => ({ entry, score: score(entry, tokens) }))
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score || a.entry.relativePath.localeCompare(b.entry.relativePath))
+            .slice(0, limit)
+            .map(({ entry, score: rank }) => ({
+            kind: entry.kind,
+            title: entry.title,
+            excerpt: excerpt(entry.content, tokens),
+            score: rank,
+            runtimes: entry.runtimes,
+            serviceIds: entry.serviceIds,
+            provenance: entry.provenance,
+        }));
+    }
+    readDocuments(paths) {
+        return paths.map((requestedPath) => {
+            const normalized = requestedPath.replaceAll("\\", "/").replace(/^\.\//, "");
+            const entry = this.byPath.get(normalized);
+            if (!entry || (entry.kind !== "documentation" && entry.kind !== "service" && entry.kind !== "board")) {
+                throw new Error(`Path is not an indexed document or board: ${requestedPath}`);
+            }
+            return { content: entry.content.slice(0, 80_000), provenance: entry.provenance };
+        });
+    }
+    getServiceContract(serviceId, runtime, version) {
+        const canonical = canonicalServiceId(serviceId);
+        const contract = this.contracts.find((item) => item.runtime === runtime && canonicalServiceId(item.serviceId) === canonical);
+        if (!contract)
+            throw new Error(`No indexed ${runtime} contract for service '${serviceId}'.`);
+        const exact = !version || version === this.buildVersion;
+        return {
+            ...contract,
+            documentation: { ...contract.documentation, exactBuildMatch: exact },
+            sourceReferences: contract.sourceReferences.map((item) => ({ ...item, exactBuildMatch: exact })),
+            warning: exact ? undefined : `Requested build '${version}' is not indexed; this result describes '${this.buildVersion}'.`,
+        };
+    }
+    findCompatibleServices(inputType, outputType, runtime) {
+        const wantedInput = inputType.toLowerCase();
+        const wantedOutput = outputType.toLowerCase();
+        return this.contracts.filter((contract) => {
+            if (runtime && contract.runtime !== runtime)
+                return false;
+            const inputs = contract.inputTypes.map((item) => item.toLowerCase());
+            const outputs = contract.outputTypes.map((item) => item.toLowerCase());
+            const inputMatch = inputs.includes(wantedInput) || inputs.includes("any") || wantedInput === "any";
+            const outputMatch = outputs.includes(wantedOutput) || wantedOutput === "any";
+            return inputMatch && outputMatch;
+        }).slice(0, 30);
+    }
+    findBoardExamples(serviceIds, runtime, limit = 10) {
+        const wanted = new Set(serviceIds.map(canonicalServiceId));
+        return this.entries
+            .filter((entry) => entry.kind === "board")
+            .filter((entry) => !runtime || entry.runtimes.includes(runtime))
+            .map((entry) => ({ entry, matches: entry.serviceIds.filter((id) => wanted.has(canonicalServiceId(id))).length }))
+            .filter((item) => item.matches > 0)
+            .sort((a, b) => b.matches - a.matches || a.entry.relativePath.localeCompare(b.entry.relativePath))
+            .slice(0, Math.max(1, Math.min(limit, 20)))
+            .map(({ entry, matches }) => ({
+            kind: "board",
+            title: entry.title,
+            excerpt: excerpt(entry.content, [...wanted]),
+            score: matches,
+            runtimes: entry.runtimes,
+            serviceIds: entry.serviceIds,
+            provenance: entry.provenance,
+        }));
+    }
+    inspectServiceSource(serviceId, runtime, version, maxLines = 180) {
+        const canonical = canonicalServiceId(serviceId);
+        const exact = !version || version === this.buildVersion;
+        return this.findSourceEntries(canonical, runtime, 5).map((entry) => {
+            const lines = entry.content.split("\n");
+            const token = canonical.replaceAll("-", "_");
+            const matchIndex = lines.findIndex((line) => line.toLowerCase().includes(canonical) || line.toLowerCase().includes(token));
+            const count = Math.max(20, Math.min(maxLines, 400));
+            const lineStart = Math.max(1, (matchIndex >= 0 ? matchIndex + 1 : 1) - 20);
+            const lineEnd = Math.min(lines.length, lineStart + count - 1);
+            return {
+                content: lines.slice(lineStart - 1, lineEnd).join("\n"),
+                lineStart,
+                lineEnd,
+                provenance: { ...provenanceFor(entry, version), exactBuildMatch: exact },
+            };
+        });
+    }
+    validateBoard(board) {
+        return validateBoard(board, this);
+    }
+    stats() {
+        return { documents: this.entries.filter((entry) => entry.kind !== "board").length, boards: this.entries.filter((entry) => entry.kind === "board").length, contracts: this.contracts.length, sourceFiles: this.sourceEntries.length, buildVersion: this.buildVersion, commit: this.commit, indexedAt: this.indexedAt };
+    }
+    findSourceEntries(serviceId, runtime, limit) {
+        const tokens = [...new Set([serviceId, serviceId.replaceAll("-", "_"), serviceId.replaceAll("-", "")])].filter(Boolean);
+        return this.sourceEntries
+            .filter((entry) => entry.runtimes.includes(runtime))
+            .map((entry) => {
+            const lowerPath = entry.relativePath.toLowerCase();
+            const lowerContent = entry.content.toLowerCase();
+            let rank = 0;
+            for (const token of tokens) {
+                if (lowerPath.includes(token))
+                    rank += 30;
+                if (lowerContent.includes(`serviceid: \"${token}\"`) || lowerContent.includes(`service_id=\"${token}\"`) || lowerContent.includes(`\"${token}\"`))
+                    rank += 15;
+                else if (lowerContent.includes(token))
+                    rank += 2;
+            }
+            return { entry, rank };
+        })
+            .filter((item) => item.rank >= 15)
+            .sort((a, b) => b.rank - a.rank || a.entry.relativePath.localeCompare(b.entry.relativePath))
+            .slice(0, limit)
+            .map((item) => item.entry);
+    }
+}
+export async function findRepositoryRoot(start = process.cwd()) {
+    let current = path.resolve(start);
+    while (true) {
+        try {
+            const docs = await stat(path.join(current, "docs", "content"));
+            const boards = await stat(path.join(current, "boards"));
+            if (docs.isDirectory() && boards.isDirectory())
+                return current;
+        }
+        catch { /* keep walking */ }
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new Error("Could not find a Readymade repository root containing docs/content and boards.");
+        current = parent;
+    }
+}

package/dist/schemas.d.ts

@@ -0,0 +1,156 @@
+import * as z from "zod/v4";
+export declare const runtimeSchema: z.ZodEnum<{
+    browser: "browser";
+    node: "node";
+    python: "python";
+    cpp: "cpp";
+    go: "go";
+    graphql: "graphql";
+}>;
+export declare const searchKnowledgeInput: z.ZodObject<{
+    query: z.ZodString;
+    runtime: z.ZodOptional<z.ZodEnum<{
+        browser: "browser";
+        node: "node";
+        python: "python";
+        cpp: "cpp";
+        go: "go";
+        graphql: "graphql";
+    }>>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        documentation: "documentation";
+        board: "board";
+        service: "service";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const getServiceContractInput: z.ZodObject<{
+    serviceId: z.ZodString;
+    runtime: z.ZodEnum<{
+        browser: "browser";
+        node: "node";
+        python: "python";
+        cpp: "cpp";
+        go: "go";
+        graphql: "graphql";
+    }>;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const findCompatibleServicesInput: z.ZodObject<{
+    inputType: z.ZodString;
+    outputType: z.ZodString;
+    runtime: z.ZodOptional<z.ZodEnum<{
+        browser: "browser";
+        node: "node";
+        python: "python";
+        cpp: "cpp";
+        go: "go";
+        graphql: "graphql";
+    }>>;
+}, z.core.$strip>;
+export declare const findBoardExamplesInput: z.ZodObject<{
+    serviceIds: z.ZodArray<z.ZodString>;
+    runtime: z.ZodOptional<z.ZodEnum<{
+        browser: "browser";
+        node: "node";
+        python: "python";
+        cpp: "cpp";
+        go: "go";
+        graphql: "graphql";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const readDocumentInput: z.ZodObject<{
+    paths: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const inspectServiceSourceInput: z.ZodObject<{
+    serviceId: z.ZodString;
+    runtime: z.ZodEnum<{
+        browser: "browser";
+        node: "node";
+        python: "python";
+        cpp: "cpp";
+        go: "go";
+        graphql: "graphql";
+    }>;
+    version: z.ZodOptional<z.ZodString>;
+    maxLines: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const validateBoardInput: z.ZodObject<{
+    board: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const readymadeToolSchemas: {
+    readonly search_knowledge: z.ZodObject<{
+        query: z.ZodString;
+        runtime: z.ZodOptional<z.ZodEnum<{
+            browser: "browser";
+            node: "node";
+            python: "python";
+            cpp: "cpp";
+            go: "go";
+            graphql: "graphql";
+        }>>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            documentation: "documentation";
+            board: "board";
+            service: "service";
+        }>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly get_service_contract: z.ZodObject<{
+        serviceId: z.ZodString;
+        runtime: z.ZodEnum<{
+            browser: "browser";
+            node: "node";
+            python: "python";
+            cpp: "cpp";
+            go: "go";
+            graphql: "graphql";
+        }>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly find_compatible_services: z.ZodObject<{
+        inputType: z.ZodString;
+        outputType: z.ZodString;
+        runtime: z.ZodOptional<z.ZodEnum<{
+            browser: "browser";
+            node: "node";
+            python: "python";
+            cpp: "cpp";
+            go: "go";
+            graphql: "graphql";
+        }>>;
+    }, z.core.$strip>;
+    readonly find_board_examples: z.ZodObject<{
+        serviceIds: z.ZodArray<z.ZodString>;
+        runtime: z.ZodOptional<z.ZodEnum<{
+            browser: "browser";
+            node: "node";
+            python: "python";
+            cpp: "cpp";
+            go: "go";
+            graphql: "graphql";
+        }>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly read_document: z.ZodObject<{
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    readonly inspect_service_source: z.ZodObject<{
+        serviceId: z.ZodString;
+        runtime: z.ZodEnum<{
+            browser: "browser";
+            node: "node";
+            python: "python";
+            cpp: "cpp";
+            go: "go";
+            graphql: "graphql";
+        }>;
+        version: z.ZodOptional<z.ZodString>;
+        maxLines: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly validate_board: z.ZodObject<{
+        board: z.ZodUnknown;
+    }, z.core.$strip>;
+};
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B,eAAO,MAAM,aAAa;;;;;;;EAAuB,CAAC;AAElD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;iBAK/B,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;iBAIlC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;iBAItC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;iBAIjC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;iBAE5B,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;iBAKpC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;iBAAmC,CAAC;AAEnE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQvB,CAAC"}