wiki-formant 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wiki-formant contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# wiki-formant
+
+The portable half of a wiki: derived taxonomy, a spec-correct MCP transport, markdown twins, and the conditional-GET plumbing an agent surface needs.
+
+Zero runtime dependencies. Web-standard `Request`/`Response`, so it runs unchanged on Next route handlers, Hono, Bun, Deno and workers.
+
+```bash
+npm install wiki-formant
+```
+
+## What this is, and what it deliberately is not
+
+Every wiki needs a page store, a design system and a set of block types. Those are the parts you must own — they encode your schema, your brand and your content model, and a package that tried to own them would fight you.
+
+What every wiki *also* needs, rebuilds by hand, and then lets drift, is the layer above: the second browsing axis derived from metadata you are already storing, the HTML→markdown converter behind every `.md` twin, the JSON-RPC edges that decide whether an MCP client can talk to you at all, and the ETag arithmetic that turns a recrawl into a 304.
+
+This package was extracted from three production wikis that had each grown their own copy. By the time it was lifted, the copies had already diverged — one had lost the alphabetical index and the related-page ranking; one had `ToolAnnotations` the others lacked; one had MCP prompts the others lacked. Everything here is the union, with tests pinning the specific bugs that shipped.
+
+## Taxonomy
+
+`tagPath` puts a page in exactly one place in a tree. The `select`-typed metadata it already carries is a *cross-cutting* axis — and it is almost always stored, rendered once in an infobox as dead text, and never made pressable. The failure mode is a 141-page category rendered as one flat grid while the data to split it sits unread in a JSON column.
+
+The tree is yours; supply `getMetadataKeys` and the rest is derived.
+
+```ts
+import { createTaxonomy } from 'wiki-formant/taxonomy';
+
+const taxonomy = createTaxonomy({
+  getMetadataKeys: tagPath => TAGS[tagPath]?.metadataKeys ?? [],
+  href: (tagPath, { sort, filters, letter }) => /* your URL contract */,
+});
+
+const filters = taxonomy.facetFilters('ecosystem', searchParams);
+const pages   = taxonomy.filterPages(allPages, filters, letter);
+const facets  = taxonomy.buildFacets('ecosystem', allPages, filters, letter);
+const index   = taxonomy.needsAlphaIndex(allPages.length)
+  ? taxonomy.alphaIndex(allPages, filters) : [];
+```
+
+Four behaviours worth knowing, because each replaces a plausible wrong answer:
+
+- **Each facet is counted over the set narrowed by every *other* active filter**, so its own options stay switchable instead of collapsing to the one already chosen.
+- **Values come from the data, not from the declared `options`.** A key that declares four values while the pages hold seven would otherwise hide three behind a bar claiming to cover everything. Render what is there and the drift becomes visible.
+- **A single-valued facet hides — unless it is the active one.** An infobox row can set a filter the chips never offered; without its chip the reader lands on a narrowed list with nothing to press to widen it.
+- **`rankRelated` ranks by shared facet values** and returns the shared axis as `{key, value}`, so the *See also* heading can be the link into the filtered set. The behaviour it replaces — `pages.slice(0, 5)` — shows every page in a large category the same five links.
+
+One `href` builder is passed in and used by every chip, letter and sort button. A sort button that drops the active filters is the tell that a project grew a second one.
+
+## MCP
+
+A minimal [Model Context Protocol](https://modelcontextprotocol.io) server over Streamable HTTP, with the transport edges most implementations get wrong.
+
+```ts
+import { mcpResponse, mcpGet, mcpOptions, McpToolError } from 'wiki-formant/mcp';
+
+const config = {
+  serverInfo: { name: 'my-wiki', version: '1.4.0' },
+  instructions: 'Call search_pages first; get_page needs a full path.',
+  docsUrl: 'https://example.com/llms.txt',
+  tools: [{
+    name: 'search_pages',
+    description: 'Full-text search across the wiki.',
+    inputSchema: {
+      type: 'object',
+      properties: { q: { type: 'string', description: 'query' } },
+      required: ['q'],
+    },
+    annotations: { readOnlyHint: true },
+    handler: async ({ q }) => search(String(q)),
+  }],
+  onCall: (req, body) => track(req, body),
+};
+
+export const POST = (req: Request) => mcpResponse(req, config);
+export const GET  = () => mcpGet(config.docsUrl);
+export const OPTIONS = () => mcpOptions();
+```
+
+What it gets right:
+
+- **A caller-fixable mistake is a tool result with `isError`, never `-32603`.** Bad arguments come back naming every bad field at once, quoting the legal values and appending the schema, so one retry can fix all of them.
+- **Capabilities advertise only what the config populates.** An advertised `resources` whose list comes back empty reads as a bug, not as honesty. The `-32601` method list narrows the same way.
+- **A notification-only POST answers a bare `202`**, not a `200` carrying JSON `null`.
+- **Malformed JSON is `-32700` with a `400`**, never a 500.
+- **`GET` is an explicit 405 with CORS headers.** A framework's automatic 405 carries none, so a browser client cannot even read the refusal.
+- **The preflight allow-list includes `Accept` and `Mcp-Protocol-Version`.** One missing entry fails the preflight rather than the POST, which presents as "the server is down".
+- **Batches are capped** (default 20) with a teaching error, because the rate limiter charges one token per HTTP request before the body is parsed.
+
+## Markdown twins
+
+`htmlToMarkdown` preserves the structure an agent cites by — headings, lists, tables, code, emphasis — rather than flattening to prose. Tables convert first so the generic rules cannot eat their markup, ordered lists number per list, pipes inside cells are escaped, and a headerless table gets a synthesised header because GFM has no other form.
+
+```ts
+import { htmlToMarkdown, markdownDocument } from 'wiki-formant/markdown';
+
+return new Response(
+  markdownDocument(
+    { title: page.title, url, updated: page.updatedAt, lastVerified: page.lastVerifiedAt,
+      license: { spdx: 'CC-BY-4.0', url: 'https://creativecommons.org/licenses/by/4.0/' } },
+    blocksToMarkdown(page.content), // your block types, your function
+  ),
+  { headers: markdownHeaders(lastModified) },
+);
+```
+
+Block trees stay in your app — every project owns its own type set. Give this module HTML and it gives you markdown.
+
+> A trap worth naming: if you serve twins via a rewrite, Next drops the destination query string. The rewrite must carry the `.md` extension through to the destination path, or the twin silently serves JSON.
+
+## Conditional GET
+
+The `llms.txt` / `llms-index.txt` / `llms-full.txt` trio are the most-recrawled URLs a wiki serves and the most expensive to render. Without a corpus-derived ETag, every AI crawler pays full price on every pass, forever.
+
+```ts
+import { corpusEtag, notModified, textHeaders } from 'wiki-formant/http';
+
+const etag = corpusEtag([pageCount, newestUpdatedAt]);
+const lastModified = newestUpdatedAt.toUTCString();
+
+export async function GET(request: Request) {
+  return notModified(request, etag, lastModified)
+    ?? new Response(buildCorpus(), { headers: textHeaders(etag, lastModified) });
+}
+```
+
+## Pagination and versioning
+
+`parsePagination` clamps `page ≥ 1` and `pageSize` to 1–100; `paginatedResponse` always carries `totalPages`. Reshaping that response is a breaking change to every client that pages, which is why it lives here rather than being re-typed per repo.
+
+`parseVersion` / `bump` / `compareVersions` handle revision semver tolerantly — a page always has a version, even when the column holds `null` or junk.
+
+## API
+
+| Export | From |
+|---|---|
+| `createTaxonomy`, `defaultHref`, `firstLetter`, `toggleFilter` | `wiki-formant/taxonomy` |
+| `mcpResponse`, `mcpGet`, `mcpOptions`, `handleMcp`, `withMcpCors`, `McpToolError`, `MCP_CORS`, `MCP_PROTOCOL_VERSION` | `wiki-formant/mcp` |
+| `htmlToMarkdown`, `inlineToMarkdown`, `tableToMarkdown`, `frontmatter`, `markdownDocument`, `decodeEntities` | `wiki-formant/markdown` |
+| `corpusEtag`, `notModified`, `textHeaders`, `markdownHeaders`, `cleanSnippet`, `pageLine` | `wiki-formant/http` |
+| `parsePagination`, `paginatedResponse`, `toOffset` | `wiki-formant/pagination` |
+| `parseVersion`, `formatVersion`, `incrementVersion`, `bump`, `compareVersions` | `wiki-formant/versioning` |
+
+All are also re-exported from the package root.
+
+## Licence
+
+MIT.

package/dist/entities.d.ts

@@ -0,0 +1,3 @@
+export declare const NAMED_ENTITIES: Record<string, string>;
+export declare function decodeEntities(s: string): string;
+//# sourceMappingURL=entities.d.ts.map

package/dist/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAejD,CAAC;AAEF,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAOhD"}

package/dist/entities.js

@@ -0,0 +1,30 @@
+// entities.ts — HTML entity decoding for text exports.
+//
+// Rich-text editors store typographic punctuation as named entities, so pages
+// carry raw `—` / `“` / `’` into every text export — ampersand
+// soup an agent has to read through. Numeric forms decode generically; the named
+// table covers what wiki corpora actually use (punctuation, arrows, maths,
+// accented Latin, Greek) rather than attempting the full HTML5 list.
+export const NAMED_ENTITIES = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+    mdash: '—', ndash: '–', hellip: '…', middot: '·', bull: '•', sect: '§', para: '¶', dagger: '†',
+    ldquo: '“', rdquo: '”', lsquo: '‘', rsquo: '’', laquo: '«', raquo: '»',
+    larr: '←', rarr: '→', uarr: '↑', darr: '↓', harr: '↔',
+    times: '×', divide: '÷', minus: '−', plusmn: '±', ne: '≠', le: '≤', ge: '≥',
+    asymp: '≈', radic: '√', infin: '∞', sum: '∑', prod: '∏', int: '∫', deg: '°', permil: '‰',
+    sup2: '²', sup3: '³', frac12: '½', frac14: '¼', frac34: '¾',
+    euro: '€', pound: '£', yen: '¥', cent: '¢', copy: '©', reg: '®', trade: '™',
+    eacute: 'é', egrave: 'è', ecirc: 'ê', aacute: 'á', agrave: 'à', acirc: 'â', aring: 'å',
+    auml: 'ä', ouml: 'ö', uuml: 'ü', iacute: 'í', oacute: 'ó', uacute: 'ú', ntilde: 'ñ',
+    ccedil: 'ç', oslash: 'ø', szlig: 'ß', aelig: 'æ',
+    alpha: 'α', beta: 'β', gamma: 'γ', delta: 'δ', epsilon: 'ε', theta: 'θ', lambda: 'λ',
+    mu: 'μ', nu: 'ν', pi: 'π', rho: 'ρ', sigma: 'σ', tau: 'τ', phi: 'φ', omega: 'ω',
+    Delta: 'Δ', Sigma: 'Σ', Omega: 'Ω', Lambda: 'Λ', Phi: 'Φ', Pi: 'Π',
+};
+export function decodeEntities(s) {
+    return s
+        .replace(/&#x([0-9a-fA-F]{1,6});/g, (_m, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d{1,7});/g, (_m, dec) => String.fromCodePoint(Number(dec)))
+        .replace(/&([a-zA-Z][a-zA-Z0-9]{1,9});/g, (m, name) => NAMED_ENTITIES[name] ?? m);
+}
+//# sourceMappingURL=entities.js.map

package/dist/entities.js.map

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

package/dist/http.d.ts

@@ -0,0 +1,25 @@
+/** A stable ETag from whatever the corpus revision is (count + newest stamp). */
+export declare function corpusEtag(parts: Array<string | number | Date | null | undefined>): string;
+/** 304 when the client already holds this revision, else `null` to render. */
+export declare function notModified(request: Request, etag: string, lastModified: string): Response | null;
+/**
+ * Headers for a plain-text export. `maxAge` is the edge window — a curated
+ * corpus can sit on hours, a projection of live data should pass a short one.
+ */
+export declare function textHeaders(etag: string, lastModified: string, maxAge?: number): Record<string, string>;
+/**
+ * Headers for a markdown twin. Separate from `textHeaders` because the twin is
+ * addressed per page and carries its own `Last-Modified`, and because a client
+ * that asked for `.md` should not be handed `text/plain`.
+ */
+export declare function markdownHeaders(lastModified: string, maxAge?: number): Record<string, string>;
+/** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
+export declare function cleanSnippet(text: string, max?: number): string;
+/** One markdown bullet: linked title, excerpt, and the date an agent diffs on. */
+export declare function pageLine(opts: {
+    title: string;
+    url: string;
+    excerpt?: string;
+    updated?: Date | string | null;
+}): string;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAOA,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAY1F;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAMjG;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,MAAM,SAAO,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3F;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAQ5D;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;CAChC,GAAG,MAAM,CAMT"}

package/dist/http.js

@@ -0,0 +1,72 @@
+// http.ts — conditional-GET plumbing for text corpus endpoints.
+//
+// The three llms depths (llms.txt / llms-index.txt / llms-full.txt) are the
+// most-recrawled URLs a wiki serves and the most expensive to render. With a
+// corpus-derived ETag a recrawl costs a 304 instead of a full corpus build.
+// Without one, every AI crawler pays full price on every pass, forever.
+/** A stable ETag from whatever the corpus revision is (count + newest stamp). */
+export function corpusEtag(parts) {
+    const seed = parts
+        .map(p => (p instanceof Date ? p.toISOString() : String(p ?? '')))
+        .join('|');
+    // FNV-1a: short, stable across processes, and no dependency. Collisions do
+    // not matter here — the seed already carries the count and the newest stamp.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) {
+        hash ^= seed.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `W/"${hash.toString(36)}-${seed.length.toString(36)}"`;
+}
+/** 304 when the client already holds this revision, else `null` to render. */
+export function notModified(request, etag, lastModified) {
+    const inm = request.headers.get('if-none-match');
+    const ims = request.headers.get('if-modified-since');
+    const fresh = inm ? inm === etag : Boolean(ims && ims === lastModified);
+    if (!fresh)
+        return null;
+    return new Response(null, { status: 304, headers: { ETag: etag, 'Last-Modified': lastModified } });
+}
+/**
+ * Headers for a plain-text export. `maxAge` is the edge window — a curated
+ * corpus can sit on hours, a projection of live data should pass a short one.
+ */
+export function textHeaders(etag, lastModified, maxAge = 3600) {
+    return {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': `public, s-maxage=${maxAge}, stale-while-revalidate=${maxAge * 24}`,
+        ETag: etag,
+        'Last-Modified': lastModified,
+    };
+}
+/**
+ * Headers for a markdown twin. Separate from `textHeaders` because the twin is
+ * addressed per page and carries its own `Last-Modified`, and because a client
+ * that asked for `.md` should not be handed `text/plain`.
+ */
+export function markdownHeaders(lastModified, maxAge = 3600) {
+    return {
+        'Content-Type': 'text/markdown; charset=utf-8',
+        'Cache-Control': `public, s-maxage=${maxAge}, stale-while-revalidate=${maxAge * 24}`,
+        'Last-Modified': lastModified,
+    };
+}
+/** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
+export function cleanSnippet(text, max = 160) {
+    return text
+        .replace(/\(https?:\/\/[^)]*\)/g, '')
+        .replace(/https?:\/\/\S+/g, '')
+        .replace(/\(\s*\)/g, '')
+        .replace(/\s{2,}/g, ' ')
+        .trim()
+        .slice(0, max);
+}
+/** One markdown bullet: linked title, excerpt, and the date an agent diffs on. */
+export function pageLine(opts) {
+    const excerpt = opts.excerpt ? `: ${cleanSnippet(opts.excerpt)}` : '';
+    const stamp = opts.updated
+        ? (typeof opts.updated === 'string' ? opts.updated : opts.updated.toISOString()).split('T')[0]
+        : '';
+    return `- [${opts.title}](${opts.url})${excerpt}${stamp ? ` _(updated ${stamp})_` : ''}`;
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './taxonomy.js';
+export * from './mcp.js';
+export * from './markdown.js';
+export * from './entities.js';
+export * from './http.js';
+export * from './pagination.js';
+export * from './versioning.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// wiki-formant — the portable half of a wiki.
+//
+// Nothing here touches a database, a framework or a design system. Those are
+// the parts every wiki must own; these are the parts every wiki rebuilds and
+// then lets drift.
+export * from './taxonomy.js';
+export * from './mcp.js';
+export * from './markdown.js';
+export * from './entities.js';
+export * from './http.js';
+export * from './pagination.js';
+export * from './versioning.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,mBAAmB;AAEnB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/markdown.d.ts

@@ -0,0 +1,25 @@
+/** Inline-level HTML → markdown. Applied inside cells, list items, headings. */
+export declare function inlineToMarkdown(html: string): string;
+/** One `<table>` → a GFM table. Falls back to nothing when there are no rows. */
+export declare function tableToMarkdown(html: string): string;
+/** Block-level HTML → markdown. */
+export declare function htmlToMarkdown(html: string): string;
+export interface FrontmatterFields {
+    title: string;
+    url: string;
+    updated?: Date | string | null;
+    /** When the page's facts were last checked against sources — the freshness
+     *  signal an agent actually needs, and the one most twins omit. */
+    lastVerified?: Date | string | null;
+    license?: {
+        spdx: string;
+        url: string;
+    } | null;
+    /** Any additional scalar rows, emitted in insertion order. */
+    extra?: Record<string, string | number | undefined>;
+}
+/** YAML frontmatter block, `---` fences included. */
+export declare function frontmatter(fields: FrontmatterFields): string;
+/** A complete markdown document: frontmatter, an H1, and a body you supply. */
+export declare function markdownDocument(fields: FrontmatterFields, body: string): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAcA,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBrD;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBpD;AAED,mCAAmC;AACnC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwDnD;AAKD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B;uEACmE;IACnE,YAAY,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/C,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;CACrD;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAgB7D;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhF"}

package/dist/markdown.js

@@ -0,0 +1,107 @@
+// markdown.ts — HTML → markdown for the `.md` twin of a content page.
+//
+// Distinct from a plain text extractor, which flattens everything to prose.
+// This preserves the structure an agent navigates and cites by — headings,
+// lists, tables, code, emphasis — so a fetched page can be quoted precisely
+// instead of re-summarised.
+//
+// Block trees are NOT handled here: every project owns its own block type set,
+// so `blocksToMarkdown` belongs in the app. Give this module HTML and it gives
+// you markdown; give `frontmatter` the fields and it gives you the document
+// head. That is the whole portable half.
+import { decodeEntities } from './entities.js';
+/** Inline-level HTML → markdown. Applied inside cells, list items, headings. */
+export function inlineToMarkdown(html) {
+    return decodeEntities(html
+        .replace(/<br\s*\/?>/gi, ' ')
+        .replace(/<(?:strong|b)\b[^>]*>(.*?)<\/(?:strong|b)>/gi, '**$1**')
+        .replace(/<(?:em|i)\b[^>]*>(.*?)<\/(?:em|i)>/gi, '_$1_')
+        .replace(/<code\b[^>]*>(.*?)<\/code>/gi, '`$1`')
+        .replace(/<a\b[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, '[$2]($1)')
+        .replace(/<img\b[^>]*alt="([^"]*)"[^>]*src="([^"]*)"[^>]*>/gi, '![$1]($2)')
+        .replace(/<img\b[^>]*src="([^"]*)"[^>]*>/gi, '![]($1)')
+        .replace(/<[^>]+>/g, ''))
+        // HTML collapses whitespace in inline context, so the converter has to as
+        // well — including newlines. Editor-produced HTML arrives on one line and
+        // never exposes this, but hand-authored HTML is indented, and without the
+        // newline in this class every wrapped source line reaches the reader with a
+        // leading space and markdown renderers start seeing stray indentation.
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** One `<table>` → a GFM table. Falls back to nothing when there are no rows. */
+export function tableToMarkdown(html) {
+    const rows = [...html.matchAll(/<tr\b[^>]*>([\s\S]*?)<\/tr>/gi)].map(m => [...m[1].matchAll(/<(t[hd])\b[^>]*>([\s\S]*?)<\/\1>/gi)].map(c => inlineToMarkdown(c[2]).replace(/\|/g, '\\|')));
+    if (!rows.length)
+        return '';
+    const width = Math.max(...rows.map(r => r.length));
+    const pad = (r) => [...r, ...Array(width - r.length).fill('')];
+    // A table whose first row is all <th> has a header; otherwise synthesise an
+    // empty one, since GFM has no headerless table form.
+    const headed = /<th\b/i.test(html.slice(0, html.indexOf('</tr>') + 1));
+    const [head, ...body] = headed
+        ? [pad(rows[0]), ...rows.slice(1).map(pad)]
+        : [Array(width).fill(''), ...rows.map(pad)];
+    return [
+        `| ${head.join(' | ')} |`,
+        `| ${Array(width).fill('---').join(' | ')} |`,
+        ...body.map(r => `| ${r.join(' | ')} |`),
+    ].join('\n');
+}
+/** Block-level HTML → markdown. */
+export function htmlToMarkdown(html) {
+    let out = html;
+    // Tables first — their inner markup must not be eaten by the generic rules.
+    out = out.replace(/<table\b[^>]*>[\s\S]*?<\/table>/gi, m => `\n\n${tableToMarkdown(m)}\n\n`);
+    // Lists. `<ol>` numbering is computed per-list, which is why this cannot be a
+    // single regex with a `$1` backreference — inside a replace callback `$1` is
+    // a literal, not a substitution. (That exact bug shipped once and rendered
+    // every ordered list as a column of `1. $1`.)
+    out = out.replace(/<ul\b[^>]*>([\s\S]*?)<\/ul>/gi, (_m, body) => {
+        const items = [...body.matchAll(/<li\b[^>]*>([\s\S]*?)<\/li>/gi)].map(i => `- ${inlineToMarkdown(i[1])}`);
+        return `\n\n${items.join('\n')}\n\n`;
+    });
+    out = out.replace(/<ol\b[^>]*>([\s\S]*?)<\/ol>/gi, (_m, body) => {
+        const items = [...body.matchAll(/<li\b[^>]*>([\s\S]*?)<\/li>/gi)].map((i, n) => `${n + 1}. ${inlineToMarkdown(i[1])}`);
+        return `\n\n${items.join('\n')}\n\n`;
+    });
+    out = out
+        .replace(/<pre\b[^>]*>\s*<code\b[^>]*>([\s\S]*?)<\/code>\s*<\/pre>/gi, (_m, code) => `\n\n\`\`\`\n${decodeEntities(code).trim()}\n\`\`\`\n\n`)
+        .replace(/<pre\b[^>]*>([\s\S]*?)<\/pre>/gi, (_m, code) => `\n\n\`\`\`\n${decodeEntities(code).trim()}\n\`\`\`\n\n`)
+        .replace(/<blockquote\b[^>]*>([\s\S]*?)<\/blockquote>/gi, (_m, body) => `\n\n${inlineToMarkdown(body)
+        .split('\n')
+        .map(l => `> ${l}`)
+        .join('\n')}\n\n`)
+        .replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (_m, level, body) => `\n\n${'#'.repeat(Number(level))} ${inlineToMarkdown(body)}\n\n`)
+        .replace(/<hr\s*\/?>/gi, '\n\n---\n\n')
+        .replace(/<p\b[^>]*>([\s\S]*?)<\/p>/gi, (_m, body) => `\n\n${inlineToMarkdown(body)}\n\n`)
+        .replace(/<div\b[^>]*>([\s\S]*?)<\/div>/gi, (_m, body) => `\n\n${inlineToMarkdown(body)}\n\n`);
+    return decodeEntities(out.replace(/<[^>]+>/g, ''))
+        .replace(/[ \t]+$/gm, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+const isoDate = (d) => (typeof d === 'string' ? d : d.toISOString()).split('T')[0];
+/** YAML frontmatter block, `---` fences included. */
+export function frontmatter(fields) {
+    const esc = (s) => s.replace(/"/g, '\\"');
+    return [
+        '---',
+        `title: "${esc(fields.title)}"`,
+        `url: "${fields.url}"`,
+        ...(fields.updated ? [`updated: ${isoDate(fields.updated)}`] : []),
+        ...(fields.lastVerified ? [`last_verified: ${isoDate(fields.lastVerified)}`] : []),
+        ...(fields.license
+            ? [`license: ${fields.license.spdx}`, `license_url: "${fields.license.url}"`]
+            : []),
+        ...Object.entries(fields.extra ?? {})
+            .filter(([, v]) => v !== undefined && v !== '')
+            .map(([k, v]) => (typeof v === 'number' ? `${k}: ${v}` : `${k}: "${esc(String(v))}"`)),
+        '---',
+    ].join('\n');
+}
+/** A complete markdown document: frontmatter, an H1, and a body you supply. */
+export function markdownDocument(fields, body) {
+    return `${frontmatter(fields)}\n\n# ${fields.title}\n\n${body.trim()}\n`;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

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

package/dist/mcp.d.ts

@@ -0,0 +1,123 @@
+export declare const MCP_PROTOCOL_VERSION = "2025-03-26";
+export type ToolParam = {
+    type: 'string' | 'number' | 'boolean' | 'array';
+    description: string;
+    enum?: string[];
+    items?: {
+        type: 'string' | 'number';
+    };
+};
+export type ToolSchema = {
+    type: 'object';
+    properties: Record<string, ToolParam>;
+    required?: string[];
+};
+/**
+ * Behavioural hints a client uses to decide what needs a human in the loop.
+ * Without them every tool looks alike, so a client that auto-approves read-only
+ * calls has no way to tell a lookup from one that reaches a payment processor.
+ */
+export type ToolAnnotations = {
+    /** Human-facing label for the tool. */
+    title?: string;
+    /** Does not modify anything. */
+    readOnlyHint?: boolean;
+    /** May destroy or overwrite state (only meaningful when not read-only). */
+    destructiveHint?: boolean;
+    /** Repeating the identical call has no additional effect. */
+    idempotentHint?: boolean;
+    /** Touches systems beyond this server. */
+    openWorldHint?: boolean;
+};
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: ToolSchema;
+    annotations?: ToolAnnotations;
+    /** Surfaced as an A2A skill on the agent card. Not sent over MCP. */
+    skill?: {
+        id: string;
+        tags: string[];
+        examples?: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export interface McpResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    read: () => Promise<string | null>;
+}
+export interface McpPrompt {
+    name: string;
+    description: string;
+    /**
+     * The user message the client inserts when someone picks this prompt. Name
+     * the tool sequence outright rather than restating the question: the model
+     * reading it has the tool list but no reason to prefer one call order over
+     * another, which is the same gap `instructions` exists to close.
+     */
+    text: string;
+}
+export interface McpServerConfig {
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    /**
+     * Server-level usage guide returned by `initialize`. Say which tool to reach
+     * for first and what NOT to do; it is the only text an agent sees before the
+     * tool list.
+     */
+    instructions: string;
+    tools: McpTool[];
+    resources?: McpResource[];
+    /**
+     * The entry point a client offers after install. Tools are what an agent
+     * reaches for once it already has a question; prompts are what a person
+     * clicks when they do not have one yet.
+     */
+    prompts?: McpPrompt[];
+    /** Appended to the GET refusal so a browser that lands here learns where to go. */
+    docsUrl?: string;
+    /**
+     * Cap on JSON-RPC batch size. The rate limiter charges one token per HTTP
+     * request, before the body is parsed — an unbounded batch would let a single
+     * token fan out into thousands of concurrent handler executions, each its own
+     * query. Keep this aligned with whatever ceiling the batching tools advertise.
+     */
+    maxBatch?: number;
+    /** Per-request analytics hook. Runs before dispatch; never blocks the response. */
+    onCall?: (request: Request, body: unknown) => void;
+}
+/**
+ * A caller-fixable failure inside a handler (page not found, empty input).
+ * Reported as a tool result with `isError` so the model sees the text and can
+ * correct itself, per the spec's split between protocol and execution errors.
+ */
+export declare class McpToolError extends Error {
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
+type RpcRequest = {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    method: string;
+    params?: unknown;
+};
+/** Dispatch a parsed body. `null` means notification-only — answer 202, not 200. */
+export declare function handleMcp(body: RpcRequest | RpcRequest[], config: McpServerConfig): Promise<object | object[] | null>;
+export declare const MCP_CORS: Record<string, string>;
+export declare function withMcpCors<T extends Response>(res: T): T;
+export declare function mcpOptions(): Response;
+/**
+ * Streamable HTTP lets a server decline the SSE leg by answering GET with 405.
+ * A framework's automatic 405 carries no CORS headers, so a browser client
+ * could not even read the refusal — answer it here, and say what to do instead.
+ */
+export declare function mcpGet(docsUrl?: string): Response;
+/** The whole POST leg: parse, track, dispatch, and answer with the right status. */
+export declare function mcpResponse(request: Request, config: McpServerConfig): Promise<Response>;
+export {};
+//# sourceMappingURL=mcp.d.ts.map