wiki-formant 0.20.0 → 0.22.0

package/dist/crawlers.js

@@ -53,6 +53,19 @@ export function detectAiBot(userAgent) {
 export function aiCrawlerTokens() {
     return AI_CRAWLERS.map(c => c.token);
 }
+/**
+ * The agent surface an S10 origin serves, allowed in every group. All three
+ * `robots.ts` files listed these by hand, and a path missing from one list is
+ * an endpoint the origin advertises and then closes to the callers it named.
+ */
+export const AGENT_SURFACE_PATHS = [
+    '/api/mcp',
+    '/llms.txt',
+    '/llms-index.txt',
+    '/llms-full.txt',
+    '/openapi.json',
+    '/.well-known/',
+];
 /**
  * The wildcard group followed by one group per crawler.
  *
@@ -62,7 +75,7 @@ export function aiCrawlerTokens() {
  * agent everything, because it stops matching `*` the moment it matches itself.
  */
 export function aiCrawlerRules(opts) {
-    const aiAllow = [opts.aiAllow].flat();
+    const aiAllow = [...new Set([...[opts.aiAllow ?? []].flat(), ...AGENT_SURFACE_PATHS])];
     return [
         // `aiAllow` rides on the default group too, not only on the named roster.
         // The agent surface an origin advertises has to be reachable by a caller it

package/dist/editor.d.ts

@@ -46,6 +46,11 @@ export declare function insertEmbed(editor: Editor, url: string, { resolveMapUrl
 export declare const TABLE_ACTIONS: ReadonlyArray<[command: string, label: string, danger?: boolean]>;
 /** `editor.isActive` as a toolbar button's `active` descriptor expresses it. */
 export type ActiveDescriptor = string | [string, Record<string, unknown>];
+/**
+ * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
+ * back. Two editors carried it character for character, `alert` included.
+ */
+export declare function uploadImageTo(endpoint: string): (file: File) => Promise<string | null>;
 export interface WikiEditorOptions {
     value: string;
     onChange: (html: string) => void;

package/dist/editor.js

@@ -136,6 +136,30 @@ export const TABLE_ACTIONS = [
     ['deleteRow', '-Row', true],
     ['deleteTable', '-Tbl', true],
 ];
+// ---- the editor -------------------------------------------------------------
+/**
+ * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
+ * back. Two editors carried it character for character, `alert` included.
+ */
+export function uploadImageTo(endpoint) {
+    return async (file) => {
+        const form = new FormData();
+        form.append('file', file);
+        try {
+            const res = await fetch(endpoint, { method: 'POST', body: form });
+            const body = (await res.json());
+            if (!res.ok) {
+                alert(body.error || 'Upload failed');
+                return null;
+            }
+            return body.url ?? null;
+        }
+        catch {
+            alert('Upload failed');
+            return null;
+        }
+    };
+}
 /**
  * The editor, its upload plumbing and the state a toolbar reads.
  *

package/dist/freshness.d.ts

@@ -17,3 +17,17 @@ export declare function isStale(page: FreshnessInput, now: number, maxAgeDays?:
  * being re-typed either side of the extraction.
  */
 export declare function freshnessNotice(page: FreshnessInput): string;
+/**
+ * A synthetic `outdated` banner block for a stale page, or null when it is
+ * fresh — the shape every wiki's `banner` type already stores, so it drops
+ * into the tree the renderer walks. Two wikis carried this function
+ * identically. `nowMs` comes from a server component: reading the clock
+ * during a client render would let a page near the boundary be stale on the
+ * server and fresh in the browser.
+ */
+export declare function freshnessBanner(page: FreshnessInput, nowMs: number, maxAgeDays?: number): {
+    id: string;
+    type: 'banner';
+    variant: 'outdated';
+    text: string;
+} | null;

package/dist/freshness.js

@@ -40,3 +40,16 @@ export function freshnessNotice(page) {
         : 'not yet verified against sources';
     return `This page was ${when} and may be out of date. Please help re-check its facts against current sources and the live ledger.`;
 }
+/**
+ * A synthetic `outdated` banner block for a stale page, or null when it is
+ * fresh — the shape every wiki's `banner` type already stores, so it drops
+ * into the tree the renderer walks. Two wikis carried this function
+ * identically. `nowMs` comes from a server component: reading the clock
+ * during a client render would let a page near the boundary be stale on the
+ * server and fresh in the browser.
+ */
+export function freshnessBanner(page, nowMs, maxAgeDays = DEFAULT_MAX_AGE_DAYS) {
+    if (!isStale(page, nowMs, maxAgeDays))
+        return null;
+    return { id: '__freshness__', type: 'banner', variant: 'outdated', text: freshnessNotice(page) };
+}

package/dist/headings.d.ts

@@ -7,6 +7,13 @@ export interface Heading {
 }
 /** The default slug rule: lowercase words joined by hyphens. */
 export declare function slugifyHeading(text: string): string;
+/**
+ * `base`, or `base-2`, `base-3`… — the first one `used` does not hold. Records
+ * nothing: the caller adds the id it keeps. Shared with the editor's heading
+ * decoration, so the id a heading shows while it is being written is the id it
+ * is published under.
+ */
+export declare function uniqueHeadingId(base: string, used: ReadonlySet<string>): string;
 export interface HeadingIdOptions {
     /**
      * How heading text becomes an id. Defaults to `slugifyHeading`. Pass the rule

package/dist/headings.js

@@ -20,6 +20,20 @@ export function slugifyHeading(text) {
         .replace(/[\s_-]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+/**
+ * `base`, or `base-2`, `base-3`… — the first one `used` does not hold. Records
+ * nothing: the caller adds the id it keeps. Shared with the editor's heading
+ * decoration, so the id a heading shows while it is being written is the id it
+ * is published under.
+ */
+export function uniqueHeadingId(base, used) {
+    if (!base)
+        return base;
+    let id = base;
+    for (let n = 2; used.has(id); n++)
+        id = `${base}-${n}`;
+    return id;
+}
 const HEADING = /<(h[1-6])([^>]*)>([\s\S]*?)<\/\1>/gi;
 const defaultAnchor = (id) => `<a class="heading-anchor" href="#${id}" aria-label="Permalink to this section" tabindex="-1"></a>`;
 /**
@@ -37,15 +51,9 @@ export function injectHeadingIds(html, options = {}) {
         if (content.includes('heading-anchor'))
             return match;
         const existing = getAttr(attrs, 'id');
-        let id = existing || slug(stripTags(content));
+        const id = existing || uniqueHeadingId(slug(stripTags(content)), used);
         if (!id)
             return match;
-        if (!existing) {
-            const base = id;
-            let n = 2;
-            while (used.has(id))
-                id = `${base}-${n++}`;
-        }
         used.add(id);
         return `<${tag}${existing ? attrs : `${attrs} id="${id}"`}>${content}${anchor(id)}</${tag}>`;
     });

package/dist/http.d.ts

@@ -9,7 +9,15 @@ export declare function corpusEtag(parts: Array<string | number | Date | null |
  * prefix, and a crawler reformats the date. Each of those took a full render
  * from a response that was already fresh.
  */
-export declare function notModified(request: Request, etag: string, lastModified?: string | null): Response | null;
+export declare function notModified(request: Request, etag: string, lastModified?: string | null, 
+/**
+ * The headers the 200 would carry. RFC 9110 15.4.5 requires a 304 to send
+ * the Cache-Control and Vary a 200 would have, and a cross-origin client
+ * needs the CORS header on it too; without them a revalidated copy loses its
+ * freshness and a negotiated URL loses its Vary. The body's own headers
+ * (Content-Type, Content-Length) are dropped.
+ */
+sent?: Record<string, string>): Response | null;
 /**
  * A 404 that teaches, for the plain-GET half of an agent surface.
  *
@@ -49,6 +57,25 @@ export declare function markdownHeaders(lastModified?: string | null, opts?: {
     etag?: string;
     extra?: Record<string, string>;
 }): Record<string, string>;
+/**
+ * Whether a request to a URL that serves both JSON and markdown asked for the
+ * markdown: `?format=text`, or an Accept naming text/markdown or text/plain.
+ * The `.md` suffix is the caller's to add — it lives in the path, not here.
+ *
+ * Both branches of such a route must send `VARY_ACCEPT`. Two wikis answered
+ * one URL in two formats under `public, s-maxage` with no Vary, so a shared
+ * cache could hand the markdown to the next JSON client, or the reverse.
+ */
+export declare function wantsMarkdown(request: {
+    url: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}): boolean;
+/** The header every response from a content-negotiated URL carries. */
+export declare const VARY_ACCEPT: {
+    readonly Vary: "Accept";
+};
 /**
  * Headers for a JSON descriptor — an agent card, an OpenAPI document, a
  * registry manifest. These are the documents a client refetches most and the

package/dist/http.js

@@ -30,8 +30,17 @@ const bareTag = (tag) => tag.trim().replace(/^W\//, '');
  * prefix, and a crawler reformats the date. Each of those took a full render
  * from a response that was already fresh.
  */
-export function notModified(request, etag, lastModified) {
+export function notModified(request, etag, lastModified, 
+/**
+ * The headers the 200 would carry. RFC 9110 15.4.5 requires a 304 to send
+ * the Cache-Control and Vary a 200 would have, and a cross-origin client
+ * needs the CORS header on it too; without them a revalidated copy loses its
+ * freshness and a negotiated URL loses its Vary. The body's own headers
+ * (Content-Type, Content-Length) are dropped.
+ */
+sent = {}) {
     const headers = {
+        ...Object.fromEntries(Object.entries(sent).filter(([k]) => !/^content-(type|length)$/i.test(k))),
         ETag: etag,
         ...(lastModified ? { 'Last-Modified': lastModified } : {}),
     };
@@ -110,6 +119,21 @@ export function markdownHeaders(lastModified, opts = {}) {
         ...opts.extra,
     };
 }
+/**
+ * Whether a request to a URL that serves both JSON and markdown asked for the
+ * markdown: `?format=text`, or an Accept naming text/markdown or text/plain.
+ * The `.md` suffix is the caller's to add — it lives in the path, not here.
+ *
+ * Both branches of such a route must send `VARY_ACCEPT`. Two wikis answered
+ * one URL in two formats under `public, s-maxage` with no Vary, so a shared
+ * cache could hand the markdown to the next JSON client, or the reverse.
+ */
+export function wantsMarkdown(request) {
+    return (new URL(request.url).searchParams.get('format') === 'text' ||
+        /text\/(markdown|plain)/.test(request.headers.get('accept') ?? ''));
+}
+/** The header every response from a content-negotiated URL carries. */
+export const VARY_ACCEPT = { Vary: 'Accept' };
 /**
  * Headers for a JSON descriptor — an agent card, an OpenAPI document, a
  * registry manifest. These are the documents a client refetches most and the
@@ -137,7 +161,8 @@ export function descriptorHeaders(etag, opts = {}) {
 export function descriptorResponse(request, body, opts = {}) {
     const text = JSON.stringify(body);
     const etag = corpusEtag([text]);
-    return notModified(request, etag) ?? new Response(text, { headers: descriptorHeaders(etag, opts) });
+    const sent = descriptorHeaders(etag, opts);
+    return notModified(request, etag, null, sent) ?? new Response(text, { headers: sent });
 }
 /** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
 export function cleanSnippet(text, max = 160) {
@@ -172,7 +197,7 @@ export function pageLine(opts) {
 export function corpusRoute(validators, build, headers = textHeaders) {
     return async (request) => {
         const { etag, lastModified } = await validators();
-        return (notModified(request, etag, lastModified) ??
-            new Response(await build(), { headers: headers(etag, lastModified) }));
+        const sent = headers(etag, lastModified);
+        return notModified(request, etag, lastModified, sent) ?? new Response(await build(), { headers: sent });
     };
 }

package/dist/index.d.ts

@@ -19,3 +19,4 @@ export * from './revisions.js';
 export * from './feed.js';
 export * from './license.js';
 export * from './seeded.js';
+export * from './metadata.js';

package/dist/index.js

@@ -24,3 +24,4 @@ export * from './revisions.js';
 export * from './feed.js';
 export * from './license.js';
 export * from './seeded.js';
+export * from './metadata.js';

package/dist/license.d.ts

@@ -43,3 +43,12 @@ export declare function licenseLines({ license, scope, scopeVerb, excludes, head
 export declare function licenseBlock(opts: LicenseBlockOptions): string;
 /** The one-line form, for a frontmatter field or a feed's `<copyright>`. */
 export declare function licenseNote(license: License): string;
+/**
+ * The OpenAPI 3.1 `info.license` object. Name plus SPDX `identifier` — the
+ * spec makes `identifier` and `url` mutually exclusive, and the three specs
+ * here had each picked a different pair, one of them a hand-typed name.
+ */
+export declare function openApiLicense(license: License): {
+    name: string;
+    identifier: string;
+};

package/dist/license.js

@@ -47,3 +47,11 @@ export function licenseBlock(opts) {
 export function licenseNote(license) {
     return `${license.name} (${license.spdx}): ${license.url}`;
 }
+/**
+ * The OpenAPI 3.1 `info.license` object. Name plus SPDX `identifier` — the
+ * spec makes `identifier` and `url` mutually exclusive, and the three specs
+ * here had each picked a different pair, one of them a hand-typed name.
+ */
+export function openApiLicense(license) {
+    return { name: license.name, identifier: license.spdx };
+}

package/dist/link-check.d.ts

@@ -88,5 +88,30 @@ export declare function extractEmbeds(html: string): Array<{
     kind: string;
     url: string;
 }>;
+/** What a page links to, split the way a checker probes it. */
+export interface BlockLinks {
+    /** Absolute http(s) targets. */
+    external: string[];
+    /** Site-relative paths, fragment and trailing slash dropped. `/` stays `/`. */
+    internal: string[];
+    /** `<iframe>` and `<img>` sources. */
+    embeds: Array<{
+        kind: string;
+        url: string;
+    }>;
+}
+/**
+ * Every link in a block tree, from every core type that carries one.
+ *
+ * The two checkers that walked this had each fixed a bug the other still had.
+ * One read reference URLs, which live in `items[].url` and never in an anchor;
+ * the other missed every citation. The other decoded `&amp;` before probing —
+ * a stored href is an attribute, and probing it raw turns query-sensitive APIs
+ * into false failures — and stopped a bare `/` collapsing to `''`, the
+ * homepage reported broken. Neither read link-grid hrefs. This does all four.
+ */
+export declare function collectBlockLinks<B extends {
+    type: string;
+}>(blocks: readonly B[], containers?: (block: B) => B[][] | null): BlockLinks;
 /** `Promise.all` with a ceiling, preserving input order in the results. */
 export declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/link-check.js

@@ -11,6 +11,8 @@
 // rather than death, which serialising per hostname fixes. A sweep missing any
 // one of these strips good citations.
 import { stripTags } from './html.js';
+import { decodeEntities } from './markdown.js';
+import { coreBlockShape, leafBlocks } from './blocks.js';
 const DEFAULTS = { timeoutMs: 12_000, slowTimeoutMs: 40_000 };
 /**
  * TLS-verification failures are NOT death.
@@ -180,7 +182,9 @@ export async function probeYouTube(videoId, opts = {}) {
 }
 /** An external anchor, with a video treated as a video. */
 export async function probeExternal(url, opts = {}) {
-    const yt = url.match(YOUTUBE_WATCH);
+    // Watch and embed URLs alike: an /embed/ page answers 200 for a deleted
+    // video, so a checker that probed embeds as plain URLs never saw one die.
+    const yt = url.match(YOUTUBE_WATCH) ?? url.match(YOUTUBE_EMBED);
     if (yt?.[1])
         return { url, videoId: yt[1], ...(await probeYouTube(yt[1], opts)) };
     return probeUrl(url, opts);
@@ -228,6 +232,57 @@ export function extractEmbeds(html) {
     }
     return out;
 }
+const records = (v) => Array.isArray(v) ? v.filter((x) => !!x && typeof x === 'object') : [];
+const text = (v) => (typeof v === 'string' ? v : '');
+/**
+ * Every link in a block tree, from every core type that carries one.
+ *
+ * The two checkers that walked this had each fixed a bug the other still had.
+ * One read reference URLs, which live in `items[].url` and never in an anchor;
+ * the other missed every citation. The other decoded `&` before probing —
+ * a stored href is an attribute, and probing it raw turns query-sensitive APIs
+ * into false failures — and stopped a bare `/` collapsing to `''`, the
+ * homepage reported broken. Neither read link-grid hrefs. This does all four.
+ */
+export function collectBlockLinks(blocks, containers = coreBlockShape().containers) {
+    const out = { external: [], internal: [], embeds: [] };
+    const href = (raw) => {
+        const url = decodeEntities(raw).trim();
+        if (/^https?:\/\//i.test(url))
+            out.external.push(url);
+        else if (url.startsWith('/') && !url.startsWith('//'))
+            out.internal.push(url.split('#')[0].replace(/(.)\/+$/, '$1'));
+    };
+    const html = (fragment) => {
+        for (const link of extractLinks(fragment))
+            href(link.href);
+        for (const embed of extractEmbeds(fragment)) {
+            const url = decodeEntities(embed.url).trim();
+            if (/^https?:\/\//i.test(url))
+                out.embeds.push({ kind: embed.kind, url });
+        }
+    };
+    for (const block of leafBlocks(blocks, containers)) {
+        if (block.type === 'content')
+            html(text(block.text));
+        if (block.type === 'references') {
+            for (const item of records(block.items)) {
+                html(text(item.text));
+                if (text(item.url))
+                    href(text(item.url));
+            }
+        }
+        if (block.type === 'linkGrid') {
+            for (const group of records(block.groups)) {
+                html(text(group.description));
+                for (const link of records(group.links))
+                    if (text(link.href))
+                        href(text(link.href));
+            }
+        }
+    }
+    return out;
+}
 // ---- concurrency ------------------------------------------------------------
 /** `Promise.all` with a ceiling, preserving input order in the results. */
 export async function mapLimit(items, limit, fn) {

package/dist/maps.d.ts

@@ -14,5 +14,28 @@ export declare function extractCoordsFromUrl(url: string): MapCoords | null;
  * understands. Already-embeddable URLs pass through untouched.
  */
 export declare function toMapEmbedUrl(url: string): string | null;
-/** True for the shortener forms that only a redirect can resolve. */
-export declare const isShortMapUrl: (url: string) => boolean;
+/** True for the shortener forms only a redirect can resolve. Exact hostnames, never a substring. */
+export declare function isShortMapUrl(url: string): boolean;
+/**
+ * Follow a shortened maps link ONE hop, server-side, and return where it
+ * lands — or null unless both ends are on the allowlists. Never follows a
+ * redirect chain: every hop is a request to a host this code did not choose.
+ */
+export declare function resolveShortMapUrl(url: string, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<string | null>;
+/**
+ * The whole `GET /api/resolve-map?url=…` route. `authorize` is the wiki's own
+ * sign-in check: the route makes an outbound request per call, so it belongs
+ * behind the same gate as the editor that calls it.
+ */
+export declare function resolveMapHandler(opts: {
+    authorize: (request: Request) => boolean | Promise<boolean>;
+    timeoutMs?: number;
+}): (request: Request) => Promise<Response>;
+/**
+ * A pasted map URL as an embeddable one, following a shortener through the
+ * wiki's resolve route when the URL cannot be read directly. The editor's map
+ * node and embed dialog both take this as their `resolveMapUrl`.
+ */
+export declare function resolveMapUrl(url: string, endpoint?: string): Promise<string | null>;

package/dist/maps.js

@@ -1,8 +1,9 @@
 // maps.ts — turn a map URL a human pasted into one an <iframe> will accept.
 //
-// Both wikis carried this byte-for-byte apart from one `export` keyword. It is
-// pure string work over Google and Apple Maps URL shapes, with no framework or
-// database in it, which is why neither copy had a reason to diverge.
+// Both wikis carried the parsing byte-for-byte apart from one `export`
+// keyword. It is pure string work over Google and Apple Maps URL shapes. The
+// shortener hop at the bottom is the one part that makes a request, and the
+// part the two copies did NOT agree on.
 /** A plain embed URL for a coordinate pair. */
 function mapsEmbedUrl(lat, lon, zoom = 15) {
     return `https://maps.google.com/maps?q=${lat},${lon}&z=${zoom}&output=embed`;
@@ -73,5 +74,90 @@ export function toMapEmbedUrl(url) {
     }
     return null;
 }
-/** True for the shortener forms that only a redirect can resolve. */
-export const isShortMapUrl = (url) => /maps\.app\.goo\.gl|goo\.gl\/maps/.test(url);
+// ---- shortened links ---------------------------------------------------------
+//
+// A `maps.app.goo.gl` link only resolves through a redirect, which the editor
+// cannot read cross-origin, so each wiki runs a route that follows it. One of
+// the two copies matched its host as a SUBSTRING — `https://evil.example/?goo.gl`
+// passed — then followed every redirect with no timeout and no login: an
+// anonymous fetcher for any URL. The other followed one hop, between exact
+// host lists, with a timeout, for signed-in members only. That one is below.
+const SHORTLINK_HOSTS = new Set(['goo.gl', 'maps.app.goo.gl']);
+/**
+ * Where a resolved shortlink may land: Google Maps on a Google country domain
+ * (google.com, maps.google.com, www.google.co.uk, www.google.com.au). An
+ * anchored list, because the suffix match it replaced, `google\.[a-z.]+`,
+ * admitted google.evil.com.
+ */
+const RESOLVED_HOST = /^(?:www\.|maps\.)?google\.(?:com|com?\.[a-z]{2}|[a-z]{2})$/;
+const parse = (url, base) => {
+    try {
+        return new URL(url, base);
+    }
+    catch {
+        return null;
+    }
+};
+/** True for the shortener forms only a redirect can resolve. Exact hostnames, never a substring. */
+export function isShortMapUrl(url) {
+    const u = parse(url);
+    if (!u || !SHORTLINK_HOSTS.has(u.hostname))
+        return false;
+    return u.hostname === 'maps.app.goo.gl' || u.pathname.startsWith('/maps');
+}
+/**
+ * Follow a shortened maps link ONE hop, server-side, and return where it
+ * lands — or null unless both ends are on the allowlists. Never follows a
+ * redirect chain: every hop is a request to a host this code did not choose.
+ */
+export async function resolveShortMapUrl(url, { timeoutMs = 5_000 } = {}) {
+    const source = parse(url);
+    if (!source || source.protocol !== 'https:' || !isShortMapUrl(url))
+        return null;
+    try {
+        const res = await fetch(source, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+        const location = res.headers.get('location');
+        const target = location ? parse(location, source) : null;
+        return target && target.protocol === 'https:' && RESOLVED_HOST.test(target.hostname) ? target.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The whole `GET /api/resolve-map?url=…` route. `authorize` is the wiki's own
+ * sign-in check: the route makes an outbound request per call, so it belongs
+ * behind the same gate as the editor that calls it.
+ */
+export function resolveMapHandler(opts) {
+    return async (request) => {
+        if (!(await opts.authorize(request)))
+            return Response.json({ error: 'Unauthorized' }, { status: 401 });
+        const url = new URL(request.url).searchParams.get('url') ?? '';
+        if (!url.startsWith('https:') || !isShortMapUrl(url)) {
+            return Response.json({ error: 'Invalid URL' }, { status: 400 });
+        }
+        const resolved = await resolveShortMapUrl(url, opts);
+        return resolved
+            ? Response.json({ resolved })
+            : Response.json({ error: 'Failed to resolve' }, { status: 502 });
+    };
+}
+/**
+ * A pasted map URL as an embeddable one, following a shortener through the
+ * wiki's resolve route when the URL cannot be read directly. The editor's map
+ * node and embed dialog both take this as their `resolveMapUrl`.
+ */
+export async function resolveMapUrl(url, endpoint = '/api/resolve-map') {
+    const direct = toMapEmbedUrl(url);
+    if (direct || !isShortMapUrl(url))
+        return direct;
+    try {
+        const res = await fetch(`${endpoint}?url=${encodeURIComponent(url)}`);
+        const { resolved } = (await res.json());
+        return resolved ? toMapEmbedUrl(resolved) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/mcp.d.ts

@@ -202,6 +202,43 @@ export declare class McpToolError extends Error {
     readonly details?: Record<string, unknown> | undefined;
     constructor(message: string, details?: Record<string, unknown> | undefined);
 }
+/** A value the server used in place of the one the caller sent, and why. */
+export interface ArgAdjustment {
+    param: string;
+    requested: unknown;
+    used: unknown;
+    reason: string;
+}
+/**
+ * Typed, clamped reads over a tool's raw arguments, recording every value it
+ * had to override.
+ *
+ * Defaults belong in the tool's description, where a model reads them; what a
+ * result should echo is only the case where the server overrode what the
+ * caller actually asked for, so `adjustments` stays signal. The three servers
+ * here had one of these, one inline `clamp`, and one server coercing per tool,
+ * where `Math.min(Number(limit) || 12, 50)` let a negative limit through.
+ */
+export declare function readArgs(raw: Record<string, unknown>): {
+    adjustments: ArgAdjustment[];
+    note(a: ArgAdjustment): void;
+    /** A whole number in `[min, max]`; `def` when absent or not a number at all. */
+    num: (name: string, def: number, min: number, max: number) => number;
+    /** Any number in `[min, max]` — an age that is a cohort mean, a price; `def` (often null) when absent. */
+    decimal: <D extends number | null>(name: string, def: D, min: number, max: number) => number | D;
+    /** Trimmed text; `def` when absent. */
+    str(name: string, def?: string): string;
+    /** True only for a JSON `true`. */
+    bool(name: string): boolean;
+    /** The string members of an array argument; `[]` when absent. */
+    list(name: string): string[];
+};
+/** `result`, plus `adjustments` when `readArgs` had to override anything. */
+export declare const withAdjustments: <T extends object>(args: {
+    adjustments: readonly ArgAdjustment[];
+}, result: T) => T | (T & {
+    adjustments: readonly ArgAdjustment[];
+});
 /** One entry in a JSON-RPC envelope. Exported because `wiki-formant/x402`
  *  gates the envelope before `handleMcp` ever sees it. */
 export type RpcRequest = {