@nyuchi/mzizi-mcp 0.9.0 → 0.10.0

package/dist/issue-report.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The issue desk's report shape and the pure functions that turn a report into
+ * a GitHub issue.
+ *
+ * Split out of `issue-desk.ts` for one concrete reason: that module imports
+ * `cloudflare:workers` for the `DurableObject` base class, which only resolves
+ * inside workerd. Everything here is ordinary TypeScript, so it runs — and is
+ * tested — under plain Node. The rendering is where this feature can be
+ * silently wrong (a body claiming a reproduction that never ran will be
+ * believed by whoever reads the issue), so it is the part that most needs to be
+ * reachable by a test that does not need a runtime.
+ */
+/**
+ * Stages, in order. A report only ever moves forward, and `failed` is terminal
+ * for the attempt rather than for the report — `retry` re-enters at the stage
+ * that failed instead of starting again, so a fundi outage does not cost the
+ * reproduction that already succeeded.
+ *
+ * The last stage is `logged`, not `filed`, and the rename is the change itself
+ * rather than a tidy-up. This desk no longer files anything: it hands the
+ * drafted report to fundi, which owns the GitHub credential, the issue log and
+ * the lifecycle write-back. Calling the terminal stage `filed` would claim a
+ * GitHub issue that, at that instant, does not exist yet — the same class of
+ * overclaim as a body asserting a reproduction that never ran.
+ */
+export type Stage = "opened" | "reproducing" | "drafted" | "logged" | "failed";
+export type ReportKind = "feedback" | "observability" | "chaos";
+export type Severity = "low" | "medium" | "high" | "critical";
+export interface OpenInput {
+    kind: ReportKind;
+    message: string;
+    component?: string;
+    severity?: Severity;
+    /** fundi skill to run for the reproduction, when one applies. */
+    skill?: string;
+}
+export interface Report {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    kind: ReportKind;
+    component: string | null;
+    severity: Severity | null;
+    message: string;
+    stage: Stage;
+    /** fundi's answer to the reproduce stage, verbatim. */
+    repro: unknown | null;
+    /** The drafted issue body — present from `drafted` onward. */
+    draft: string | null;
+    /**
+     * `fundi_issues.id` once the report has been logged.
+     *
+     * The handle everything downstream hangs off: fundi files the GitHub issue
+     * from this row, writes the lifecycle back onto it, and the console at
+     * app.mzizi.dev lists it. A report that has one is recorded somewhere a
+     * maintainer can see, which is the thing the old GitHub-token path could
+     * never honestly claim.
+     */
+    fundiIssueId: number | null;
+    /** fundi's status for that row: open, triaged, in_progress, closed, … */
+    issueStatus: string | null;
+    /**
+     * The GitHub issue, once fundi has filed it.
+     *
+     * Null at the moment a report is logged and filled in on a later read — fundi
+     * files on a cron pass, so the URL arrives minutes after the report does.
+     */
+    issueUrl: string | null;
+    error: string | null;
+}
+export interface Actor {
+    userId: string;
+    email?: string;
+}
+/**
+ * Everything the desk needs from the request that is not part of the report.
+ *
+ * A Durable Object has no request context of its own: it cannot see `ctx.props`,
+ * so it cannot name the reporter or authenticate to fundi on its own behalf.
+ * Both have to be handed in by the Worker, and this is the object that carries
+ * them.
+ *
+ * This type exists because they were NOT handed in. `mcp-api-handler.ts` passed
+ * the DO stub straight to the tool layer through `as unknown as
+ * IssueDeskContext`, and that double assertion silenced a real arity mismatch:
+ * the interface declares `open(input)` while the class implements
+ * `open(input, actor)`. Every report therefore reached `renderIssueBody` with
+ * `actor === undefined` and threw on `actor.email`. Grouping the two into a
+ * named parameter makes the omission a type error rather than a runtime one.
+ */
+export interface DeskCaller {
+    actor: Actor;
+    /**
+     * The signed-in user's WorkOS access token, forwarded to fundi as
+     * `X-Fundi-User-Token`.
+     *
+     * A string rather than the thunk `fundi-client.ts` uses, because the desk
+     * resolves it once per request and calls fundi immediately — there is no
+     * long-lived session here for it to go stale across. Optional because a token
+     * that cannot be resolved must not stop a report being filed: reproduction is
+     * the non-fatal stage, and losing it costs evidence, not the report.
+     */
+    userToken?: string;
+}
+/**
+ * fundi names its skills; they are never inferred from instruction text
+ * (`fundi-a2a.ts` §2). This maps the report KIND — which the caller does
+ * choose from a closed set — onto one, and takes an explicit `skill` override
+ * when the caller knows better.
+ *
+ * `feedback` maps to NOTHING, and that is the point. It used to fall through to
+ * `a11y-audit`, so every free-text report was submitted as an accessibility
+ * audit — including one about stale organisational text in the registry, which
+ * has no visual surface for an audit to look at. Two costs, not one: the repro
+ * field filled with an irrelevant result, and `a11y-audit` is entitlement-gated
+ * behind a paid fundi_tester subscription, so most reporters got a 403 recorded
+ * against a report that was otherwise fine.
+ *
+ * A caller who knows a skill applies can still name one explicitly. Returning
+ * null means "do not reproduce", which the desk treats as a normal outcome
+ * rather than a failure.
+ */
+export declare function defaultSkill(kind: ReportKind): string | null;
+export declare function reproInstruction(input: OpenInput): string;
+export declare function issueTitle(report: Report): string;
+/**
+ * The issue body.
+ *
+ * Three things a hand-written report usually lacks and this one always has:
+ * what the reproduction attempt actually returned (including "it did not run"),
+ * the reporter's recent history so a maintainer can see a pattern, and the
+ * report id so a follow-up can be tied to it.
+ */
+export declare function renderIssueBody(report: Report, history: Report[], actor: {
+    userId: string;
+    email?: string;
+}): string;
+//# sourceMappingURL=issue-report.d.ts.map

package/dist/issue-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-report.d.ts","sourceRoot":"","sources":["../src/issue-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE9E,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,eAAe,GAAG,OAAO,CAAA;AAC/D,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAE7D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,KAAK,CAAA;IACZ,uDAAuD;IACvD,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IACrB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;;;;OAQG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,yEAAyE;IACzE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAA;IACZ;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAU5D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAGzD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKjD;AAUD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,MAAM,CAqER"}

package/dist/issue-report.js

@@ -0,0 +1,112 @@
+/**
+ * The issue desk's report shape and the pure functions that turn a report into
+ * a GitHub issue.
+ *
+ * Split out of `issue-desk.ts` for one concrete reason: that module imports
+ * `cloudflare:workers` for the `DurableObject` base class, which only resolves
+ * inside workerd. Everything here is ordinary TypeScript, so it runs — and is
+ * tested — under plain Node. The rendering is where this feature can be
+ * silently wrong (a body claiming a reproduction that never ran will be
+ * believed by whoever reads the issue), so it is the part that most needs to be
+ * reachable by a test that does not need a runtime.
+ */
+/**
+ * fundi names its skills; they are never inferred from instruction text
+ * (`fundi-a2a.ts` §2). This maps the report KIND — which the caller does
+ * choose from a closed set — onto one, and takes an explicit `skill` override
+ * when the caller knows better.
+ *
+ * `feedback` maps to NOTHING, and that is the point. It used to fall through to
+ * `a11y-audit`, so every free-text report was submitted as an accessibility
+ * audit — including one about stale organisational text in the registry, which
+ * has no visual surface for an audit to look at. Two costs, not one: the repro
+ * field filled with an irrelevant result, and `a11y-audit` is entitlement-gated
+ * behind a paid fundi_tester subscription, so most reporters got a 403 recorded
+ * against a report that was otherwise fine.
+ *
+ * A caller who knows a skill applies can still name one explicitly. Returning
+ * null means "do not reproduce", which the desk treats as a normal outcome
+ * rather than a failure.
+ */
+export function defaultSkill(kind) {
+    switch (kind) {
+        case "chaos":
+            return "chaos-run";
+        case "observability":
+            return "security-scan";
+        case "feedback":
+        default:
+            return null;
+    }
+}
+export function reproInstruction(input) {
+    const where = input.component ? `component \`${input.component}\`` : "the Mzizi registry";
+    return `Reproduce a reported problem in ${where}. Reported symptom: ${input.message}`;
+}
+export function issueTitle(report) {
+    const scope = report.component ? `${report.component}: ` : "";
+    const firstLine = report.message.split("\n")[0].trim();
+    const body = firstLine.length > 80 ? `${firstLine.slice(0, 77)}…` : firstLine;
+    return `${scope}${body}`;
+}
+/* `labelsFor` used to live here, building `reported-via-mcp` / kind / severity
+   labels for the desk's own `POST /repos/…/issues` call. That call is gone, and
+   so is the label vocabulary: fundi labels what it files, from the row, as
+   `fundi:severity/…`, `fundi:type/…` and `fundi:source/mcp-issue-desk` — the
+   same canonical `fundi:<dim>/<value>` form its webhook parses back off an
+   issue. Two label vocabularies on one tracker is how a webhook filter starts
+   silently missing issues. */
+/**
+ * The issue body.
+ *
+ * Three things a hand-written report usually lacks and this one always has:
+ * what the reproduction attempt actually returned (including "it did not run"),
+ * the reporter's recent history so a maintainer can see a pattern, and the
+ * report id so a follow-up can be tied to it.
+ */
+export function renderIssueBody(report, history, actor) {
+    const lines = [];
+    lines.push(report.message.trim(), "");
+    lines.push("## Report", "");
+    lines.push(`| | |`, `| --- | --- |`);
+    lines.push(`| kind | \`${report.kind}\` |`);
+    if (report.component)
+        lines.push(`| component | \`${report.component}\` |`);
+    if (report.severity)
+        lines.push(`| severity | \`${report.severity}\` |`);
+    lines.push(`| reported by | ${actor.email ?? actor.userId} |`);
+    lines.push(`| report id | \`${report.id}\` |`);
+    lines.push("");
+    lines.push("## Reproduction", "");
+    const repro = report.repro;
+    if (!repro || repro.attempted === false) {
+        lines.push(`No reproduction was attempted — ${repro?.reason ?? "the reproduction stage did not run"}.`);
+    }
+    else if (repro.error) {
+        lines.push(`The reproduction call failed: \`${repro.error}\``);
+    }
+    else {
+        lines.push(`Delegated to fundi as skill \`${repro.skill}\`; fundi answered HTTP \`${repro.status}\`.`, "", "<details><summary>fundi's response, verbatim</summary>", "", "```json", JSON.stringify(repro.response, null, 2).slice(0, 4000), "```", "", "</details>", "", "> fundi currently records a submitted task and parks it — its executors are not", "> built yet, so an `accepted-not-executed` status above means the report has NOT", "> been independently reproduced. Read the symptom, not the status.");
+    }
+    lines.push("");
+    const previous = history.filter((h) => h.id !== report.id);
+    if (previous.length > 0) {
+        lines.push("## Earlier reports from the same person", "");
+        for (const h of previous.slice(0, 5)) {
+            const url = h.issueUrl ? ` — ${h.issueUrl}` : "";
+            const scope = h.component ? `\`${h.component}\`: ` : "";
+            lines.push(`- ${h.createdAt.slice(0, 10)} · ${scope}${h.message.split("\n")[0].slice(0, 100)}${url}`);
+        }
+        lines.push("", "> Included because a repeated complaint from one reporter is often one bug, and", "> three separate issues is how it stops looking like one.", "");
+    }
+    lines.push("---", "");
+    // Present tense about the logging, future about the filing — because this
+    // string is rendered at the DRAFT stage, before the report has been logged at
+    // all, and it is handed straight back to the caller as `report.draft`. Saying
+    // "which filed this issue" would assert a GitHub issue that does not exist
+    // yet and may not for another five minutes, which is the same overclaim the
+    // `logged` stage name exists to avoid.
+    lines.push("_Reported through the Mzizi MCP issue desk (`mzizi_report_issue`) and logged to fundi, which files the GitHub issue and tracks it from there._");
+    return lines.join("\n");
+}
+//# sourceMappingURL=issue-report.js.map

package/dist/issue-report.js.map

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

package/dist/rate-limit.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Abuse protection for the free tier: a per-IP limit on anonymous requests.
+ *
+ * Enforced by the Workers rate-limit binding (`[[ratelimits]]` in
+ * wrangler.toml, `ANON_RATE_LIMIT`), not by code here. The binding needs no
+ * resource created on the Cloudflare side: `namespace_id` is a number chosen
+ * in the config, and `wrangler deploy` applies it. Its counters are kept per
+ * Cloudflare location and are eventually consistent, which is what abuse
+ * protection needs; it is not a metering system and is not used as one.
+ *
+ * Signed-in requests are not limited here. They carry an identity, and the
+ * OAuth provider has already spent a KV read validating the token.
+ *
+ * Where the binding is absent (the stdio bin never gets here; an older local
+ * runtime might) the request is let through. Failing closed would take the
+ * free tier down with a missing binding, and the limit is a guard, not a gate.
+ */
+/** The binding's shape (`RateLimit` in @cloudflare/workers-types). */
+export type RateLimiter = {
+    limit(options: {
+        key: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+};
+/**
+ * The key for one client: the connecting IP Cloudflare reports.
+ *
+ * `CF-Connecting-IP` is set by Cloudflare's edge and cannot be forged from
+ * outside it. Off the edge (`wrangler dev`) it may be missing, and every such
+ * request shares one bucket, which is correct for a single local client.
+ */
+export declare function clientKey(request: Request): string;
+/**
+ * `null` when the request may proceed, or the 429 to send.
+ *
+ * The body is a JSON-RPC error so an MCP client can show it, and it names the
+ * way past the limit: signing in.
+ */
+export declare function limitAnonymous(limiter: RateLimiter | undefined, request: Request): Promise<Response | null>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,sEAAsE;AACtE,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAChE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAuB1B"}

package/dist/rate-limit.js

@@ -0,0 +1,58 @@
+/**
+ * Abuse protection for the free tier: a per-IP limit on anonymous requests.
+ *
+ * Enforced by the Workers rate-limit binding (`[[ratelimits]]` in
+ * wrangler.toml, `ANON_RATE_LIMIT`), not by code here. The binding needs no
+ * resource created on the Cloudflare side: `namespace_id` is a number chosen
+ * in the config, and `wrangler deploy` applies it. Its counters are kept per
+ * Cloudflare location and are eventually consistent, which is what abuse
+ * protection needs; it is not a metering system and is not used as one.
+ *
+ * Signed-in requests are not limited here. They carry an identity, and the
+ * OAuth provider has already spent a KV read validating the token.
+ *
+ * Where the binding is absent (the stdio bin never gets here; an older local
+ * runtime might) the request is let through. Failing closed would take the
+ * free tier down with a missing binding, and the limit is a guard, not a gate.
+ */
+import { ANONYMOUS_RATE_LIMIT, SIGN_IN_MCP_URL } from "./access.js";
+/**
+ * The key for one client: the connecting IP Cloudflare reports.
+ *
+ * `CF-Connecting-IP` is set by Cloudflare's edge and cannot be forged from
+ * outside it. Off the edge (`wrangler dev`) it may be missing, and every such
+ * request shares one bucket, which is correct for a single local client.
+ */
+export function clientKey(request) {
+    return request.headers.get("CF-Connecting-IP") ?? "unknown";
+}
+/**
+ * `null` when the request may proceed, or the 429 to send.
+ *
+ * The body is a JSON-RPC error so an MCP client can show it, and it names the
+ * way past the limit: signing in.
+ */
+export async function limitAnonymous(limiter, request) {
+    if (!limiter)
+        return null;
+    const { success } = await limiter.limit({ key: clientKey(request) });
+    if (success)
+        return null;
+    const { limit, periodSeconds } = ANONYMOUS_RATE_LIMIT;
+    return new Response(JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+            code: -32000,
+            message: `Rate limit: anonymous requests are limited to ${limit} per ${periodSeconds} seconds per IP address. Wait and retry, or sign in (free) at ${SIGN_IN_MCP_URL} for no limit.`,
+        },
+    }), {
+        status: 429,
+        headers: {
+            "Content-Type": "application/json",
+            "Retry-After": String(periodSeconds),
+            "Access-Control-Allow-Origin": "*",
+        },
+    });
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAOpE;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,OAAgB;IACxC,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,SAAS,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAgC,EAChC,OAAgB;IAEhB,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACrE,IAAI,OAAO;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,oBAAoB,CAAC;IACtD,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC;QACb,OAAO,EAAE,KAAK;QACd,EAAE,EAAE,IAAI;QACR,KAAK,EAAE;YACL,IAAI,EAAE,CAAC,KAAK;YACZ,OAAO,EAAE,iDAAiD,KAAK,QAAQ,aAAa,iEAAiE,eAAe,gBAAgB;SACrL;KACF,CAAC,EACF;QACE,MAAM,EAAE,GAAG;QACX,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC;YACpC,6BAA6B,EAAE,GAAG;SACnC;KACF,CACF,CAAC;AACJ,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The registry this MCP serves — read from files bundled into the build.
+ *
+ * `src/generated/registry.ts` is produced at build time by
+ * `scripts/generate-registry.mjs` from mzizi-dev/mzizi-registry at the commit
+ * pinned in `registry.pin.json`. It holds the exact payloads the registry's own
+ * API route handlers produce for that commit, so a tool answering from here and
+ * a consumer reading `api.mzizi.dev/v1` at the same commit get the same bytes.
+ *
+ * There is no network call and no database anywhere below. That is the owner's
+ * ruling — nothing but the console touches the database — and it also removes a
+ * class of failure: a tool can no longer be "down" because an upstream is.
+ *
+ * Failure policy is unchanged from the HTTP client this replaced: every method
+ * returns a discriminated result, so a tool turns "no such component" into a
+ * sentence the caller can act on rather than an exception.
+ */
+export type Ok<T> = {
+    ok: true;
+    data: T;
+};
+export type Miss = {
+    ok: false;
+    reason: "not_found" | "invalid";
+    message: string;
+};
+export type Result<T> = Ok<T> | Miss;
+/** The shape of the generated module, and of a test fixture. Values are JSON strings. */
+export type RawRegistry = {
+    REGISTRY_PIN: {
+        readonly repository: string;
+        readonly ref: string;
+    };
+    SECTIONS: Readonly<Record<string, string>>;
+    COMPONENTS: Readonly<Record<string, string>>;
+    COMPONENT_DOCS: Readonly<Record<string, string>>;
+    NODES: Readonly<Record<string, string>>;
+    AI_INSTRUCTIONS: Readonly<Record<string, string>>;
+};
+export type IndexRow = {
+    name: string;
+    type?: string;
+    title?: string;
+    description?: string;
+    categories?: string[];
+    dependencies?: string[];
+    registryDependencies?: string[];
+    node?: number;
+    nodeLabel?: string;
+    owner?: string;
+    collection?: string;
+};
+type IndexPayload = {
+    items: IndexRow[];
+    [k: string]: unknown;
+};
+export type ListQuery = {
+    node?: number;
+    owner?: string;
+    collection?: string;
+    type?: string;
+    limit?: number;
+    offset?: number;
+};
+export type SearchHit = {
+    kind: "component" | "convention" | "ai-instruction" | "release";
+    name: string;
+    title?: string;
+    description?: string;
+};
+export type Registry = ReturnType<typeof createRegistry>;
+export declare function createRegistry(raw: RawRegistry): {
+    pin: {
+        readonly repository: string;
+        readonly ref: string;
+    };
+    resolveName: (name: string) => string | undefined;
+    /** The index, filtered and paged exactly as `GET /v1/ui` does it. */
+    listComponents(q?: ListQuery): Ok<IndexPayload & {
+        meta: Record<string, unknown>;
+    }>;
+    /** One component, shadcn-shaped, with its source inline. */
+    getComponent(name: string): Result<unknown>;
+    /** Use cases, variants, sizes, a11y notes — from the item's `meta` in registry.json. */
+    getComponentDocs(name: string): Result<unknown>;
+    /**
+     * Version history, derived from the changelog and the rename map.
+     *
+     * `GET /v1/ui/{name}/versions` reads the database's `component_versions` view,
+     * which this server must not touch. The committed changelog records which
+     * release added, modified, deprecated or removed each component, and the
+     * rename map records every earlier name — together that is the history the
+     * files hold. The row shape therefore differs from the database view's; it
+     * is documented in the README.
+     */
+    getComponentVersions(name: string): Result<unknown>;
+    /**
+     * Word search over components, conventions, AI instruction sets and releases.
+     *
+     * Documentation pages are NOT here — they live on docs.mzizi.dev, which this
+     * server federates as the `docs_*` tools.
+     */
+    search(query: string, limit?: number): Ok<{
+        data: SearchHit[];
+        meta: Record<string, unknown>;
+    }>;
+    getArchitecture(): Ok<unknown>;
+    /** One node or rung. `n` is uncapped — a missing number is a gap, not an error. */
+    getNode(n: number): Result<unknown>;
+    getBrand(): Ok<Record<string, unknown>>;
+    getUbuntuPillars(): Ok<unknown>;
+    getUbuntuPrinciples(): Ok<unknown>;
+    listAiInstructions(): Ok<unknown>;
+    /** By name, or by target audience (mcp-server, claude-system-prompt, …), as the API resolves it. */
+    getAiInstructions(name: string): Result<unknown>;
+    /** The mzizi conventions — the list omits bodies; pass a name for one in full. */
+    listConventions(): Ok<unknown>;
+    getConvention(name: string): Result<unknown>;
+};
+/**
+ * The registry bundled into this build. Imported lazily so a module that only
+ * needs the types (or a test with a fixture) does not load 4 MB of strings.
+ */
+export declare function bundledRegistry(): Promise<Registry>;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,EAAE,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC;AAC1C,MAAM,MAAM,IAAI,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AACnF,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AAErC,yFAAyF;AACzF,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,KAAK,YAAY,GAAG;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAgBhE,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,WAAW,GAAG,YAAY,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAKF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAEzD,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW;;6BA3DR,MAAM;sBAAgB,MAAM;;wBAmFtC,MAAM,KAAG,MAAM,GAAG,SAAS;IAmBpD,qEAAqE;uBACnD,SAAS,GAAQ,EAAE,CAAC,YAAY,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IA+BvF,4DAA4D;uBACzC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IAY3C,wFAAwF;2BACjE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IAM/C;;;;;;;;;OASG;+BACwB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IA+BnD;;;;;OAKG;kBACW,MAAM,mBAAe,EAAE,CAAC;QAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;uBAgExE,EAAE,CAAC,OAAO,CAAC;IAI9B,mFAAmF;eACxE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;gBAUvB,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;wBAInB,EAAE,CAAC,OAAO,CAAC;2BAIR,EAAE,CAAC,OAAO,CAAC;0BAIZ,EAAE,CAAC,OAAO,CAAC;IAIjC,oGAAoG;4BAC5E,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IAYhD,kFAAkF;uBAC/D,EAAE,CAAC,OAAO,CAAC;wBAKV,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;EAO/C;AAID;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,QAAQ,CAAC,CAGzD"}