wiki-formant 0.61.0 → 0.62.0

package/README.md

@@ -41,7 +41,9 @@ await store.save({ tagPath, slug, content, authorId, message, baseVersion: page.
 - **The bump is the diff's.** Added, removed or moved blocks are `major`, changed prose or title `minor`; `change` overrides it for a script that knows better. A metadata-only save moves no version and writes no revision.
 - **History is diffed on read.** A revision stores the page as it was saved, never a diff, so a script's revision and the editor's carry the same history. `history(pageId, { limit })` reads one row more than it returns, so the oldest entry shown is diffed against its real predecessor.
 - **Listings carry a snippet, not the article.** `list`, `recent` and `byIds` drop `content` for one line of it; a category of 200 cards otherwise ships 200 block arrays.
-- **Search is four tiers**: title prefix, title, literal prose, then full text on `search_tsv` with Postgres' own headline as the snippet. Hidden paths are left out unless the search names one.
+- **Search is four tiers**: title prefix, title, literal prose, then full text on `search_tsv` with Postgres' own headline as the snippet. Hidden paths are left out unless the search names one; `content: true` keeps each row's blocks.
+- **A path under a hidden one is hidden too**, in every listing, whether or not the tree names it.
+- **`branch` is an agent's walk**: a path and everything under it, newest first or A–Z, with the total a pager needs and an optional `since`. `counts` is pages per tag path, the back office and the home page left out.
 - Ids and timestamps default in the database, so the store's SQL and a Prisma client write the same rows. Copy the models with `npx prisma-models wiki` (a tenant-keyed app checks its own copy with `--tenant`), then build the full-text column with `npx fts-ddl '"WikiPage"'`.
 
 ## Tree
@@ -61,6 +63,37 @@ parseWikiPath(tree, ['contents', 'tech', 'radix-engine', 'history']);
 - A path that is itself a category wins over a mode suffix, so a category named `history` stays reachable. The empty slug is a category's hub article, and `/<category>/edit` edits it.
 - `crumbs` makes one crumb per URL segment, linked only where the tree knows the segment, so a trail can never be shorter than the address bar.
 
+## Category view
+
+`categoryView` is a category page as radix.wiki browses one, from the tree, the taxonomy and anything that reads like the store: the count, a sort that shows only once the set needs an A–Z index (by a `date` key where the category declares one), the facets its `select` keys give, a letter that exists, and a card per visible section listing its own pages, then its sections.
+
+```ts
+import { categoryView } from 'wiki-formant/category';
+
+const view = await categoryView({ tree, taxonomy, pages: store }, 'ecosystem', searchParams);
+// { sort, total, pages, all, filters, letter, facets, letters, sortable, clearHref, sortHref, sections }
+```
+
+- `pages` is the store, or the app's cached and decorated wrapper over its `list` and `subtree`.
+- A link carries `sort` only when it is not the category's own, so the bare category and its default are one address.
+
+## Wiki read tools
+
+`wikiReadTools` is the read half of a wiki's MCP server over its store and tree: `search_wiki`, `get_page`, `get_pages`, `list_pages`, `get_categories`, `get_recent_changes` and `get_full_corpus`. `searchWiki` is the same rows for an app's plain-GET `?q=` and its search page, so the three never disagree.
+
+```ts
+import { wikiReadTools, searchWiki } from 'wiki-formant/wiki-tools';
+
+const reading = { store, tree, url: (tagPath, slug) => `${SITE}/${tagPath}/${slug}`, text: extractText, noun: 'the Radix Wiki', corpusTitle: 'Radix Wiki' };
+const tools = [...wikiReadTools(reading), ...myOwnTools];
+const { items, total } = await searchWiki(reading, 'validators', { page: 1, size: 20 });
+```
+
+- Every row carries `path`, which every read tool takes back, and `chars` where the page's text was read. A pasted URL resolves, with `pathPrefix` stripped; a category's path reads its hub article; a miss names the nearest pages.
+- `privateHidden` closes the back office to every tool; without it a hidden page is unlisted but readable by path, as its URL is.
+- `metadata`, `label`, `corpus`, `noMatch` and `skills` are the app's: what a row adds, how a category is named, the sections its llms-full.txt is made of, what an empty search says, and the A2A skills.
+- Writes stay with each app, because who may write is the one thing no two of them agree on.
+
 ## 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.

package/dist/category.d.ts

@@ -0,0 +1,64 @@
+import type { ListSort, WikiPageRef } from './store.js';
+import type { Taxonomy, FacetablePage, FacetFilters, FacetControlGroup, Control } from './taxonomy.js';
+import { type WikiNode, type WikiTree } from './tree.js';
+/** What the view reads pages through: the store, or the app's cached and decorated wrappers over it. */
+export interface CategoryReader<P> {
+    list: (tagPath: string, opts: {
+        sort: ListSort;
+        limit: number;
+    }) => Promise<P[]>;
+    subtree: (tagPath: string) => Promise<WikiPageRef[]>;
+}
+export interface CategoryOptions {
+    /** A page's address. Defaults to `wikiPath`; a wiki mounted under a prefix adds it. */
+    href?: (tagPath: string, slug: string) => string;
+    /** How many of a section's own pages its card lists. */
+    cardPages?: number;
+    /** The most pages one category reads. */
+    limit?: number;
+}
+export interface CategorySection {
+    name: string;
+    href: string;
+    description?: string;
+    /** Pages in the section's whole branch. */
+    total: number;
+    /** Its own pages, in that listing's order, then its sections, so neither half of a mixed one hides. */
+    links: {
+        title: string;
+        href: string;
+    }[];
+}
+export type CategoryQuery = Record<string, string | string[] | undefined>;
+/**
+ * A category's pages narrowed by its facets and an A–Z letter, sorted A–Z or
+ * newest first (by a `date` key where the category declares one), and a card
+ * per visible child. A set small enough to need no index offers no sort: it is
+ * A–Z.
+ */
+export declare function categoryView<P extends FacetablePage & {
+    tagPath: string;
+    slug: string;
+}>({ tree, taxonomy, pages: reader }: {
+    tree: WikiTree<WikiNode>;
+    taxonomy: Taxonomy;
+    pages: CategoryReader<P>;
+}, tagPath: string, query: CategoryQuery, { href, cardPages, limit }?: CategoryOptions): Promise<{
+    sort: "title" | "recent";
+    filters: FacetFilters;
+    letter: string | undefined;
+    total: number;
+    pages: P[];
+    /** Every page before narrowing, for what describes the category as a whole (its JSON-LD). */
+    all: P[];
+    facets: FacetControlGroup[];
+    letters: Control[];
+    sortable: boolean;
+    clearHref: string | undefined;
+    sortHref: (to: "title" | "recent") => string;
+    sections: CategorySection[];
+}>;
+export type CategoryView<P> = Awaited<ReturnType<typeof categoryView<P & FacetablePage & {
+    tagPath: string;
+    slug: string;
+}>>>;

package/dist/category.js

@@ -0,0 +1,65 @@
+// category.ts – a category page as radix-wiki browses one, from the tree, the
+// taxonomy and the store.
+//
+// radix-wiki assembled this inside its route and miow copied it line for line:
+// the count, a sort that only shows once the set needs an A–Z index, the facets
+// its `select` keys give, a letter that exists, and a card per section listing
+// what it holds. acuiq2 kept a subset that had drifted (no sort, no cards). The
+// view is the app's; the arithmetic is here.
+import { wikiPath } from './tree.js';
+const one = (v) => (Array.isArray(v) ? v[0] : v);
+/**
+ * A category's pages narrowed by its facets and an A–Z letter, sorted A–Z or
+ * newest first (by a `date` key where the category declares one), and a card
+ * per visible child. A set small enough to need no index offers no sort: it is
+ * A–Z.
+ */
+export async function categoryView({ tree, taxonomy, pages: reader }, tagPath, query, { href = wikiPath, cardPages = 6, limit = 2000 } = {}) {
+    const resolved = tree.resolve(tagPath);
+    const order = (path, sort) => sort === 'recent' && tree.metadataKeys(path).some(k => k.key === 'date' && k.type === 'date') ? 'date' : sort;
+    const fallback = (path) => (tree.resolve(path).sort === 'title' ? 'title' : 'recent');
+    const asked = one(query.sort);
+    const requested = asked === 'title' || asked === 'recent' ? asked : fallback(tagPath);
+    const fetched = await reader.list(tagPath, { sort: order(tagPath, requested), limit });
+    const sort = taxonomy.needsAlphaIndex(fetched.length) ? requested : 'title';
+    const all = sort === requested ? fetched : await reader.list(tagPath, { sort: order(tagPath, sort), limit });
+    const filters = taxonomy.facetFilters(tagPath, query);
+    const letter = taxonomy.resolveLetter(all, filters, one(query.letter)?.toUpperCase());
+    const sortable = taxonomy.needsAlphaIndex(all.length);
+    // A link carries the sort only when it is not the category's own, so the bare
+    // category and its default are one address, not two.
+    const state = { sort: sortable && sort !== fallback(tagPath) ? sort : undefined, filters, letter };
+    const children = (resolved.node?.children ?? []).filter(c => !c.hidden);
+    const refs = children.length ? await reader.subtree(tagPath) : [];
+    const sections = await Promise.all(children.map(async (child) => {
+        const path = `${tagPath}/${child.slug}`;
+        const direct = await reader.list(path, { sort: order(path, fallback(path)), limit: cardPages });
+        return {
+            name: child.name,
+            href: href(path, ''),
+            description: child.description,
+            total: refs.filter(r => r.tagPath === path || r.tagPath.startsWith(`${path}/`)).length,
+            links: [
+                ...direct.slice(0, cardPages).map(p => ({ title: p.title, href: href(p.tagPath, p.slug) })),
+                ...(child.children ?? []).filter(g => !g.hidden).map(g => ({ title: g.name, href: href(`${path}/${g.slug}`, '') })),
+            ],
+        };
+    }));
+    const facets = taxonomy.facetControls(tagPath, all, state);
+    const letters = taxonomy.alphaControls(tagPath, all, state);
+    return {
+        sort,
+        filters,
+        letter,
+        total: all.length,
+        pages: taxonomy.filterPages(all, filters, letter),
+        /** Every page before narrowing, for what describes the category as a whole (its JSON-LD). */
+        all,
+        facets,
+        letters,
+        sortable,
+        clearHref: Object.keys(filters).length || letter ? taxonomy.href(tagPath, { sort: state.sort }) : undefined,
+        sortHref: (to) => taxonomy.href(tagPath, { ...state, sort: to === fallback(tagPath) ? undefined : to }),
+        sections,
+    };
+}

package/dist/store.d.ts

@@ -137,17 +137,47 @@ export declare function wikiStore<B extends DiffBlock = DiffBlock>(o: WikiStoreO
     byIds: (ids: readonly string[]) => Promise<WikiPageListing[]>;
     refs: () => Promise<Omit<WikiPageRow<unknown>, "content">[]>;
     corpus: () => Promise<WikiPageRow<B>[]>;
+    branch: ({ tagPath, sort, limit, offset, since }?: {
+        tagPath?: string;
+        sort?: ListSort;
+        limit?: number;
+        offset?: number;
+        since?: Date;
+    }) => Promise<{
+        items: {
+            content: B[];
+            title: string;
+            metadata: PageMetadata;
+            id: string;
+            tagPath: string;
+            slug: string;
+            siteId: string;
+            version: string;
+            authorId: string | null;
+            lastVerifiedAt: Date | null;
+            createdAt: Date;
+            updatedAt: Date;
+            snippet: string;
+        }[];
+        total: number;
+    }>;
+    counts: () => Promise<{
+        tagPath: string;
+        pages: number;
+    }[]>;
     stats: () => Promise<{
         pages: number;
         updated: Date | null;
     }>;
-    search: (query: string, { tagPath, skip, take }?: {
+    search: (query: string, { tagPath, skip, take, content: withContent }?: {
         tagPath?: string | null;
         skip?: number;
         take?: number;
+        content?: boolean;
     }) => Promise<{
         items: (WikiPageListing & {
             score: number;
+            content?: B[];
         })[];
         total: number;
     }>;

package/dist/store.js

@@ -50,6 +50,11 @@ export function wikiStore(o) {
     const hidden = [...(o.hidden ?? [])];
     const rows = async (query, ...values) => (await o.sql(query, ...values));
     const one = async (query, ...values) => (await rows(query, ...values))[0] ?? null;
+    /**
+     * `isHidden` in SQL, over a table aliased `p`, `param` holding the list: a
+     * path under a hidden one is back office too, whether or not the tree names it.
+     */
+    const hiddenSql = (param) => `EXISTS (SELECT 1 FROM unnest(${param}::text[]) h WHERE p."tagPath" = h OR starts_with(p."tagPath", h || '/'))`;
     const isHidden = (tagPath) => hidden.some(h => tagPath === h || tagPath.startsWith(`${h}/`));
     /** A page with how many revisions it has, which every article's foot states. */
     const get = (tagPath, slug) => one(`SELECT ${COLUMNS}, ${REVISION_COUNT} FROM ${PAGE} p WHERE "siteId" = $1 AND "tagPath" = $2 AND slug = $3`, site, tagPath, slug);
@@ -65,8 +70,8 @@ export function wikiStore(o) {
     /** A category's pages with their content, for a listing that reads the bodies (a reading time, a word count). */
     const articles = (tagPath, { sort = 'title', limit = 200, offset = 0 } = {}) => rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND "tagPath" = $2 AND slug <> '' ORDER BY ${ORDER[sort]} LIMIT $3::int OFFSET $4::int`, site, tagPath, limit, offset);
     /** Every page under a category, by title: the card that lists a subcategory's articles. */
-    const subtree = (tagPath) => rows(`SELECT "tagPath", slug, title FROM ${PAGE}
-        WHERE "siteId" = $1 AND "tagPath" LIKE $2 AND slug <> '' AND NOT ("tagPath" = ANY($3::text[]))
+    const subtree = (tagPath) => rows(`SELECT "tagPath", slug, title FROM ${PAGE} p
+        WHERE "siteId" = $1 AND "tagPath" LIKE $2 AND slug <> '' AND NOT ${hiddenSql('$3')}
         ORDER BY title ASC`, site, `${escapeLikeTerm(tagPath)}/%`, hidden);
     /**
      * The newest pages. One that names a path gets that path, hidden or not; one
@@ -75,14 +80,37 @@ export function wikiStore(o) {
      */
     const recent = async ({ tagPath, limit = 10 } = {}) => (await (tagPath !== undefined
         ? rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND "tagPath" = $2 ORDER BY "updatedAt" DESC LIMIT $3::int`, site, tagPath, limit)
-        : rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND NOT ("tagPath" = ANY($2::text[])) ORDER BY "updatedAt" DESC LIMIT $3::int`, site, hidden, limit))).map(listing);
+        : rows(`SELECT ${COLUMNS} FROM ${PAGE} p WHERE "siteId" = $1 AND NOT ${hiddenSql('$2')} ORDER BY "updatedAt" DESC LIMIT $3::int`, site, hidden, limit))).map(listing);
     const byIds = async (ids) => ids.length
         ? orderByIds((await rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND id = ANY($2::text[])`, site, [...ids])).map(listing), ids)
         : [];
     /** Every page without its content: the sitemap, llms.txt and a site's page list. */
     const refs = () => rows(`SELECT id, "siteId", "tagPath", slug, title, metadata, version, "authorId", "lastVerifiedAt", "createdAt", "updatedAt" FROM ${PAGE} WHERE "siteId" = $1 ORDER BY "tagPath", slug`, site);
     /** Every page with its content, for a corpus export. Hidden paths are left out. */
-    const corpus = () => rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND NOT ("tagPath" = ANY($2::text[])) ORDER BY "tagPath", slug`, site, hidden);
+    const corpus = () => rows(`SELECT ${COLUMNS} FROM ${PAGE} p WHERE "siteId" = $1 AND NOT ${hiddenSql('$2')} ORDER BY "tagPath", slug`, site, hidden);
+    /**
+     * A branch for an agent walking the wiki: the path named and everything
+     * under it, with the total a pager needs. Naming a path gets it even when it
+     * is hidden, and never a hidden path beneath it; naming none gets article
+     * space, the home page excepted. `since` keeps what changed from then on.
+     */
+    const branch = async ({ tagPath, sort = 'recent', limit = 20, offset = 0, since } = {}) => {
+        const where = `"siteId" = $1
+        AND ($2::text IS NULL OR "tagPath" = $2 OR starts_with("tagPath", $2 || '/'))
+        AND (("tagPath" = $2) IS TRUE OR NOT ${hiddenSql('$3')})
+        AND NOT ("tagPath" = '' AND slug = '')
+        AND ($4::timestamptz IS NULL OR "updatedAt" >= $4)`;
+        const values = [site, tagPath || null, hidden, since ?? null];
+        const [found, count] = await Promise.all([
+            rows(`SELECT ${COLUMNS} FROM ${PAGE} p WHERE ${where} ORDER BY ${ORDER[sort]} LIMIT $5::int OFFSET $6::int`, ...values, limit, offset),
+            one(`SELECT count(*)::int AS total FROM ${PAGE} p WHERE ${where}`, ...values),
+        ]);
+        return { items: found.map(row => ({ ...listing(row), content: row.content })), total: count?.total ?? 0 };
+    };
+    /** How many pages each tag path holds, back office and the home page left out: a category tree's counts. */
+    const counts = () => rows(`SELECT "tagPath", count(*)::int AS pages FROM ${PAGE} p
+        WHERE "siteId" = $1 AND NOT ("tagPath" = '' AND slug = '') AND NOT ${hiddenSql('$2')}
+        GROUP BY "tagPath" ORDER BY "tagPath"`, site, hidden);
     const stats = async () => {
         const row = await one(`SELECT count(*)::int AS pages, max("updatedAt") AS updated FROM ${PAGE} WHERE "siteId" = $1`, site);
         return { pages: row?.pages ?? 0, updated: row?.updated ?? null };
@@ -103,7 +131,7 @@ export function wikiStore(o) {
      * page is never a result. A tier-3 row's snippet is Postgres' own headline,
      * because a stem match has no literal substring to window on.
      */
-    const search = async (query, { tagPath = null, skip = 0, take = 25 } = {}) => {
+    const search = async (query, { tagPath = null, skip = 0, take = 25, content: withContent = false } = {}) => {
         const term = escapeLikeTerm(query);
         if (!term)
             return { items: [], total: 0 };
@@ -113,15 +141,15 @@ export function wikiStore(o) {
          SELECT p.*, q.tsq,
                 CASE WHEN p.title ILIKE $2 THEN 0
                      WHEN p.title ILIKE $3 THEN 1
-                     WHEN NOT (p."tagPath" = ANY($4::text[])) AND ${prose} ILIKE $3 THEN 2
+                     WHEN NOT ${hiddenSql('$4')} AND ${prose} ILIKE $3 THEN 2
                      ELSE 3 END AS tier,
                 ts_rank_cd(p.search_tsv, q.tsq, ${FTS_RANK_NORMALIZATION}) AS fts
            FROM ${PAGE} p CROSS JOIN q
           WHERE p."siteId" = $5 AND NOT (p."tagPath" = '' AND p.slug = '')
-            AND ($6::text IS NOT NULL OR NOT (p."tagPath" = ANY($4::text[])))
+            AND ($6::text IS NOT NULL OR NOT ${hiddenSql('$4')})
             AND ($6::text IS NULL OR p."tagPath" = $6)
             AND (p.title ILIKE $3
-                 OR (NOT (p."tagPath" = ANY($4::text[]))
+                 OR (NOT ${hiddenSql('$4')}
                      AND (${prose} ILIKE $3 OR (q.tsq IS NOT NULL AND p.search_tsv @@ q.tsq))))
        ),
        paged AS (
@@ -135,6 +163,7 @@ export function wikiStore(o) {
         ORDER BY tier, CASE WHEN tier = 0 THEN title END, CASE WHEN tier = 3 THEN fts END DESC, "updatedAt" DESC`, query.trim(), `${term}%`, `%${term}%`, hidden, site, tagPath, take, skip);
         const items = found.map(({ tier, total: _, headline, content, ...row }) => ({
             ...row,
+            ...(withContent ? { content: content } : {}),
             score: tier,
             snippet: (headline ? decodeEntities(headline).replace(/\s+/g, ' ').trim() : '')
                 || matchSnippet(content, query, () => opening({ content: content, metadata: row.metadata })),
@@ -231,7 +260,7 @@ export function wikiStore(o) {
     const verify = async (tagPath, slug) => (await rows(`UPDATE ${PAGE} SET "lastVerifiedAt" = now() WHERE "siteId" = $1 AND "tagPath" = $2 AND slug = $3 RETURNING id`, site, tagPath, slug)).length > 0;
     return {
         siteId: site, hidden, isHidden,
-        get, getById, list, articles, subtree, recent, byIds, refs, corpus, stats, search,
+        get, getById, list, articles, subtree, recent, byIds, refs, corpus, branch, counts, stats, search,
         history, revision, save, restore, remove, verify,
     };
 }

package/dist/wiki-tools.d.ts

@@ -0,0 +1,66 @@
+import { type McpTool } from './mcp.js';
+import { type CorpusSection } from './corpus.js';
+import { type WikiNode, type WikiTree } from './tree.js';
+import type { WikiStore, WikiPageListing, PageMetadata } from './store.js';
+import type { DiffBlock } from './revisions.js';
+type ToolName = 'search_wiki' | 'get_page' | 'get_pages' | 'list_pages' | 'get_categories' | 'get_recent_changes' | 'get_full_corpus';
+export interface WikiToolsOptions<B extends DiffBlock> {
+    store: WikiStore<B>;
+    tree: WikiTree<WikiNode>;
+    /** A page's absolute, canonical address. */
+    url: (tagPath: string, slug: string) => string;
+    /** A page's blocks as plain prose: what `get_page` returns and `chars` counts. */
+    text: (blocks: B[]) => string;
+    /** The wiki as the descriptions name it: "the Radix Wiki", "this DAO's wiki". */
+    noun: string;
+    /** The corpus document's heading. */
+    corpusTitle: string;
+    /** A prefix a pasted page URL may carry before the page's path, such as "/wiki". */
+    pathPrefix?: string;
+    /** Back-office pages are private here, not merely unlisted: no tool reads one. */
+    privateHidden?: boolean;
+    /** What a listing row adds from the page's metadata, or null for nothing. */
+    metadata?: (tagPath: string, metadata: PageMetadata) => Record<string, unknown> | null;
+    /** A category's name as the tree lists it. Defaults to the node's `name`. */
+    label?: (node: WikiNode) => string;
+    /** The corpus as sections, when the app's llms-full.txt sets their form. Defaults to one per page from the store. */
+    corpus?: (tagPath?: string) => Promise<CorpusSection[]>;
+    /** What an empty search says. */
+    noMatch?: (query: string, tagPath?: string) => string;
+    /** A2A skills by tool, beside the defaults. */
+    skills?: Partial<Record<ToolName, McpTool['skill']>>;
+}
+/** A read tool: the package's always say whether they write. */
+export type WikiTool = McpTool & Required<Pick<McpTool, 'title' | 'annotations'>>;
+type Rowable<B> = Pick<WikiPageListing, 'title' | 'tagPath' | 'slug' | 'snippet' | 'metadata' | 'updatedAt' | 'lastVerifiedAt'> & {
+    content?: B[];
+};
+/** The row every listing returns: search, list, recent changes, and the app's own `?q=` twin. */
+declare const rowFor: <B extends DiffBlock>(o: Pick<WikiToolsOptions<B>, "url" | "text" | "metadata">) => (p: Rowable<B>) => {
+    metadata?: Record<string, unknown> | undefined;
+    lastVerified?: string | undefined;
+    snippet: string;
+    updatedAt: string;
+    chars?: number | undefined;
+    title: string;
+    path: string;
+    url: string;
+    tagPath: string;
+    slug: string;
+};
+export type WikiRow = ReturnType<ReturnType<typeof rowFor>>;
+/**
+ * A page of ranked search rows, as `search_wiki` returns them. An app's plain
+ * GET `?q=` and its search page call this too, so the three stay row for row
+ * the same.
+ */
+export declare function searchWiki<B extends DiffBlock>(o: Pick<WikiToolsOptions<B>, 'store' | 'privateHidden' | 'url' | 'text' | 'metadata'>, query: string, { tagPath, page, size }?: {
+    tagPath?: string;
+    page?: number;
+    size?: number;
+}): Promise<{
+    items: WikiRow[];
+    total: number;
+}>;
+export declare function wikiReadTools<B extends DiffBlock>(o: WikiToolsOptions<B>): WikiTool[];
+export {};

package/dist/wiki-tools.js

@@ -0,0 +1,342 @@
+// wiki-tools.ts – the read half of a wiki's MCP server, over its store and tree.
+//
+// radix-wiki wrote these seven tools first; caper copied them, kept the names
+// and defaults, and added a batch read, a `path` on every row, a size and a miss
+// that names the nearest pages. Both then ran them over Prisma queries of their
+// own beside the store. miow had none, so a wiki it hosted answered no agent.
+// One set now, the union of the two, over `wiki-formant/store`: every wiki that
+// lists a page here lists it the way its HTML route does, hidden paths included.
+//
+// What is the app's: where a page lives (`url`), how blocks read as text,
+// what a row adds (`metadata`), and how its corpus reads when it has an
+// llms-full.txt to match. Writes stay with each app, because who may write
+// is the one thing no two of them agree on.
+import { McpToolError, readArgs, withAdjustments } from './mcp.js';
+import { listEnvelope } from './pagination.js';
+import { CORPUS_BUDGET, sliceCorpus } from './corpus.js';
+import { isoDate } from './freshness.js';
+import { wikiPath } from './tree.js';
+import { describe } from './metadata.js';
+import { openingText } from './text.js';
+const MAX_BATCH_PATHS = 20;
+const READ = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+const pathOf = (tagPath, slug) => wikiPath(tagPath, slug).slice(1);
+/** Whether a tag path is closed to these tools: a back office the wiki keeps private. */
+const offFor = (o) => (tagPath) => !!tagPath && !!o.privateHidden && o.store.isHidden(tagPath);
+/** The row every listing returns: search, list, recent changes, and the app's own `?q=` twin. */
+const rowFor = (o) => (p) => {
+    const meta = o.metadata?.(p.tagPath, (p.metadata ?? {}));
+    return {
+        title: p.title,
+        path: pathOf(p.tagPath, p.slug),
+        url: o.url(p.tagPath, p.slug),
+        tagPath: p.tagPath,
+        slug: p.slug,
+        ...(p.content ? { chars: o.text(p.content).length } : {}),
+        snippet: p.snippet,
+        updatedAt: isoDate(p.updatedAt),
+        ...(p.lastVerifiedAt ? { lastVerified: isoDate(p.lastVerifiedAt) } : {}),
+        ...(meta ? { metadata: meta } : {}),
+    };
+};
+/**
+ * A page of ranked search rows, as `search_wiki` returns them. An app's plain
+ * GET `?q=` and its search page call this too, so the three stay row for row
+ * the same.
+ */
+export async function searchWiki(o, query, { tagPath, page = 1, size = 20 } = {}) {
+    if (offFor(o)(tagPath))
+        return { items: [], total: 0 };
+    const { items, total } = await o.store.search(query, { tagPath, skip: (page - 1) * size, take: size, content: true });
+    return { items: items.map(rowFor(o)), total };
+}
+export function wikiReadTools(o) {
+    const { store, tree, noun } = o;
+    const off = offFor(o);
+    const summary = rowFor(o);
+    /** "tag/path/slug", from the path itself or a pasted URL of it. */
+    const target = (input) => {
+        let clean = input.trim().replace(/^https?:\/\/[^/]+/, '');
+        if (o.pathPrefix && (clean === o.pathPrefix || clean.startsWith(`${o.pathPrefix}/`)))
+            clean = clean.slice(o.pathPrefix.length);
+        const parts = clean.split(/[?#]/)[0].split('/').filter(Boolean);
+        const slug = parts.pop();
+        return slug ? { tagPath: parts.join('/'), slug } : null;
+    };
+    /** The article at a path, else the hub of the category the whole path is. The article wins where both exist. */
+    const read = async (t) => {
+        const page = (await store.get(t.tagPath, t.slug)) ?? (await store.get(pathOf(t.tagPath, t.slug), ''));
+        return page && !off(page.tagPath) ? page : null;
+    };
+    const full = (page) => ({
+        ...summary({ ...page, snippet: describe(openingText(page.content)) }),
+        version: page.version,
+        content: o.text(page.content),
+    });
+    const sections = async (tagPath) => {
+        if (o.corpus)
+            return o.corpus(tagPath);
+        const pages = (await store.corpus())
+            .filter(p => !(p.tagPath === '' && p.slug === '') && (!tagPath || p.tagPath === tagPath || p.tagPath.startsWith(`${tagPath}/`)))
+            .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+        return pages.map(p => {
+            const path = pathOf(p.tagPath, p.slug);
+            return { path, tagPath: p.tagPath, section: `## ${p.title}\n\nPath: ${path}\nURL: ${o.url(p.tagPath, p.slug)}\nUpdated: ${isoDate(p.updatedAt)}\n\n${o.text(p.content)}` };
+        });
+    };
+    const tools = [
+        {
+            name: 'search_wiki',
+            title: 'Search the wiki',
+            annotations: READ,
+            skill: { id: 'search', tags: ['search', 'wiki'] },
+            description: `Keyword search across ${noun}: the first call when you know what you are looking for but not where it lives. ` +
+                'Matches titles and body prose, ranked in four tiers: titles starting with the term, titles containing it, literal body hits, then English full-text hits by relevance, which stem words and drop stopwords. ' +
+                'Not semantic: one distinctive word beats a sentence. ' +
+                'Each row carries a `path`, its size in `chars` and a snippet windowed on the match. Feed the paths to get_pages in one call rather than looping get_page. ' +
+                'Narrow with tagPath when a term is common. Defaults: page 1, pageSize 20 (max 50); keep paging while `hasMore` is true.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search term, matched against page titles and body text' },
+                    tagPath: { type: 'string', description: 'Only pages at this tag path, e.g. a path from get_categories' },
+                    page: { type: 'number', description: '1-based page number (default 1)' },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 50)' },
+                },
+                required: ['query'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const query = r.str('query');
+                const tagPath = r.str('tagPath') || undefined;
+                const page = r.num('page', 1, 1, 100_000);
+                const size = r.num('pageSize', 20, 1, 50);
+                if (!query)
+                    throw new McpToolError('`query` is empty. Pass a keyword to search for, or call list_pages to enumerate a branch instead.');
+                const { items, total } = await searchWiki(o, query, { tagPath, page, size });
+                return withAdjustments(r, {
+                    query,
+                    ...listEnvelope(items, total, page, size, o.noMatch?.(query, tagPath)
+                        ?? `Nothing matches "${query}"${tagPath ? ` under "${tagPath}"` : ''}. Search is keyword, not semantic: try one distinctive word${tagPath ? ', or drop the tagPath filter' : ''}, or call get_categories to see what ${noun} covers.`),
+                });
+            },
+        },
+        {
+            name: 'get_page',
+            title: 'Read a page',
+            annotations: READ,
+            skill: { id: 'read', tags: ['read', 'content', 'article'] },
+            description: `One page of ${noun} in full: its text, version, update date and metadata. ` +
+                'Address it by `path` ("tag/path/slug", exactly the `path` or `url` a listing returns), or by `tagPath` + `slug`; a category\'s own path reads its hub article. Not a title. ' +
+                'For 2 to 20 pages call get_pages, one round trip rather than N. A miss names the nearest pages, so a wrong guess is fixed in one retry. ' +
+                'A page\'s URL with `.md` appended is its markdown.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'The page\'s whole path, e.g. "developers/scrypto/blueprints". Preferred over tagPath + slug.' },
+                    tagPath: { type: 'string', description: 'Tag path only ("" for a top-level page). Ignored when `path` is set.' },
+                    slug: { type: 'string', description: 'Page slug. Ignored when `path` is set.' },
+                },
+                requireOneOf: ['path', 'slug'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const raw = r.str('path');
+                const t = raw ? target(raw) : { tagPath: r.str('tagPath'), slug: r.str('slug') };
+                if (!t?.slug)
+                    throw new McpToolError('Pass either `path` ("tag/path/slug") or `slug` (with optional `tagPath`).');
+                const page = await read(t);
+                if (!page) {
+                    const near = await store.search(t.slug.replace(/-/g, ' '), { take: 5 });
+                    throw new McpToolError(`No page at path "${pathOf(t.tagPath, t.slug)}".`, {
+                        didYouMean: near.items.filter(p => !off(p.tagPath)).map(p => ({ path: pathOf(p.tagPath, p.slug), title: p.title })),
+                        hint: 'Paths are exact. Use search_wiki for a keyword, or list_pages with the tagPath to enumerate the branch.',
+                    });
+                }
+                return withAdjustments(r, full(page));
+            },
+        },
+        {
+            name: 'get_pages',
+            title: `Read up to ${MAX_BATCH_PATHS} pages`,
+            annotations: READ,
+            description: `Batch read: 1 to ${MAX_BATCH_PATHS} pages of ${noun} in full in one call, which is how to read search or listing results. ` +
+                'Pass `paths` as the listings return them. Paths that do not exist come back in `missing` rather than failing the call, ' +
+                `anything past ${MAX_BATCH_PATHS} in \`remaining\`, and pages past \`maxChars\` (default 250000) in \`omitted\` with their sizes.`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    paths: { type: 'array', items: { type: 'string' }, description: `Page paths, 1 to ${MAX_BATCH_PATHS} per call` },
+                    maxChars: { type: 'number', description: 'Total characters across the pages returned (default 250000, max 1000000)' },
+                },
+                required: ['paths'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const maxChars = r.num('maxChars', 250_000, 1_000, 1_000_000);
+                const requested = [...new Set(r.list('paths').map(s => String(s).trim()).filter(Boolean))];
+                if (!requested.length)
+                    throw new McpToolError('`paths` is empty. Pass at least one page path.', { hint: 'search_wiki and list_pages return a `path` for every result.' });
+                const taken = requested.slice(0, MAX_BATCH_PATHS);
+                const remaining = requested.slice(MAX_BATCH_PATHS);
+                if (remaining.length)
+                    r.note({ param: 'paths', requested: requested.length, used: taken.length, reason: `max ${MAX_BATCH_PATHS} paths per call; the rest are listed in \`remaining\`` });
+                const found = await Promise.all(taken.map(async (input) => {
+                    const t = target(input);
+                    return { input, page: t && (await read(t)) };
+                }));
+                const pages = [];
+                const missing = [];
+                const omitted = [];
+                let used = 0;
+                for (const { input, page } of found) {
+                    if (!page) {
+                        missing.push(input);
+                        continue;
+                    }
+                    const row = full(page);
+                    // At least one page always comes back, so one oversized page can still be read.
+                    if (pages.length && used + row.content.length > maxChars) {
+                        omitted.push({ path: row.path, chars: row.content.length });
+                        continue;
+                    }
+                    used += row.content.length;
+                    pages.push(row);
+                }
+                return withAdjustments(r, {
+                    requested: requested.length,
+                    returned: pages.length,
+                    characters: used,
+                    maxChars,
+                    pages,
+                    ...(missing.length ? { missing, missingHint: 'Not found. Re-check the path with search_wiki or list_pages.' } : {}),
+                    ...(omitted.length ? { omitted, omittedHint: 'Skipped to stay inside maxChars. Ask for these on their own or raise maxChars.' } : {}),
+                    ...(remaining.length ? { remaining } : {}),
+                });
+            },
+        },
+        {
+            name: 'list_pages',
+            title: 'List pages',
+            annotations: READ,
+            skill: { id: 'list', tags: ['list', 'browse', 'categories'] },
+            description: `Browse ${noun} by tag path rather than by keyword: every page under a branch, newest first by default. ` +
+                '`tagPath` matches the branch and everything beneath it; omit it to walk the whole wiki. Sort by title for an A–Z pass. ' +
+                'Same rows as search_wiki, with `totalPages`, `hasMore` and `nextPage`. Defaults: page 1, pageSize 20 (max 100).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tagPath: { type: 'string', description: 'The branch to list, e.g. a path from get_categories. Includes its descendants.' },
+                    sort: { type: 'string', enum: ['title', 'updatedAt'], description: 'Sort order (default "updatedAt", newest first)' },
+                    page: { type: 'number', description: '1-based page number (default 1)' },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 100)' },
+                },
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const tagPath = r.str('tagPath') || undefined;
+                const page = r.num('page', 1, 1, 100_000);
+                const size = r.num('pageSize', 20, 1, 100);
+                const sort = r.str('sort') === 'title' ? 'title' : 'recent';
+                const { items, total } = off(tagPath) ? { items: [], total: 0 } : await store.branch({ tagPath, sort, limit: size, offset: (page - 1) * size });
+                return withAdjustments(r, {
+                    ...(tagPath ? { tagPath } : {}),
+                    ...listEnvelope(items.map(summary), total, page, size, tagPath ? `No pages at tagPath "${tagPath}". Call get_categories for the tag paths that exist.` : `${noun} has no pages yet.`),
+                });
+            },
+        },
+        {
+            name: 'get_categories',
+            title: 'List categories',
+            annotations: READ,
+            description: `The category tree of ${noun}, the cheapest way to orient before searching. ` +
+                'Each node carries its `path` (a tagPath list_pages and search_wiki take), name, description, `pageCount` (pages filed at that path) and `pageCountDeep` (with every descendant). ' +
+                '`tagPaths` lists every tag path that holds pages, including any the tree does not name.',
+            inputSchema: { type: 'object', properties: {} },
+            handler: async () => {
+                const rows = await store.counts();
+                const exact = (path) => rows.find(c => c.tagPath === path)?.pages ?? 0;
+                const deep = (path) => rows.filter(c => c.tagPath === path || c.tagPath.startsWith(`${path}/`)).reduce((n, c) => n + c.pages, 0);
+                const build = (nodes, parent) => nodes.filter(n => !n.hidden && n.slug).map(n => {
+                    const path = parent ? `${parent}/${n.slug}` : n.slug;
+                    const children = n.children?.length ? build(n.children, path) : [];
+                    return {
+                        path,
+                        name: o.label?.(n) ?? n.name,
+                        ...(n.description ? { description: n.description } : {}),
+                        pageCount: exact(path),
+                        pageCountDeep: deep(path),
+                        ...(children.length ? { children } : {}),
+                    };
+                });
+                return {
+                    totalPages: rows.reduce((n, c) => n + c.pages, 0),
+                    categories: build(tree.nodes, ''),
+                    tagPaths: [...rows].sort((a, b) => b.pages - a.pages).map(c => ({ path: c.tagPath, pageCount: c.pages })),
+                };
+            },
+        },
+        {
+            name: 'get_recent_changes',
+            title: 'Recent changes',
+            annotations: READ,
+            description: `Pages of ${noun} edited within the last N days, newest first: what to poll when you are watching the wiki rather than reading it. ` +
+                'Same rows as list_pages. Defaults: days 7 (max 30), limit 20 (max 50). `truncated: true` means the limit cut the list; raise it, or page through list_pages.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    days: { type: 'number', description: 'Look back this many days (default 7, max 30)' },
+                    limit: { type: 'number', description: 'Most pages returned (default 20, max 50)' },
+                },
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const days = r.num('days', 7, 1, 30);
+                const limit = r.num('limit', 20, 1, 50);
+                // N × 24h back, not N calendar days: a DST change would move the window by an hour.
+                const since = new Date(Date.now() - days * 86_400_000);
+                const { items, total } = await store.branch({ sort: 'recent', limit, since });
+                return withAdjustments(r, {
+                    days,
+                    since: since.toISOString(),
+                    limit,
+                    total,
+                    count: items.length,
+                    truncated: total > items.length,
+                    pages: items.map(summary),
+                });
+            },
+        },
+        {
+            name: 'get_full_corpus',
+            title: 'Whole corpus',
+            annotations: READ,
+            description: `The whole of ${noun} as one text document, for bulk ingestion. ` +
+                'Preflight first: sizeOnly=true returns the character count, a token estimate, the per-branch breakdown and the largest pages. ' +
+                `Then pull it with \`maxChars\` (default ${CORPUS_BUDGET.default}, max ${CORPUS_BUDGET.max}), or one branch at a time with \`tagPath\`. ` +
+                'Truncation is page-aligned: `truncated`, `omittedPages` and `nextSkip` say where to resume (pass skip=nextSkip). For a handful of pages get_pages is cheaper.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sizeOnly: { type: 'boolean', description: 'Sizes and breakdowns only, no document. Do this before the first real pull.' },
+                    tagPath: { type: 'string', description: 'One branch and its descendants. Omit for everything.' },
+                    maxChars: { type: 'number', description: `Character budget for \`document\` (default ${CORPUS_BUDGET.default}, max ${CORPUS_BUDGET.max})` },
+                    skip: { type: 'number', description: 'Resume from this page index: the `nextSkip` of the previous truncated call (default 0)' },
+                },
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const tagPath = r.str('tagPath') || undefined;
+                const slice = sliceCorpus(off(tagPath) ? [] : await sections(tagPath), {
+                    title: o.corpusTitle,
+                    sizeOnly: r.bool('sizeOnly'),
+                    maxChars: r.num('maxChars', CORPUS_BUDGET.default, CORPUS_BUDGET.min, CORPUS_BUDGET.max),
+                    skip: r.num('skip', 0, 0, 1_000_000),
+                    hint: 'Pull with maxChars, or one branch at a time with tagPath. get_pages is cheaper for a handful of pages.',
+                });
+                return withAdjustments(r, { scope: o.corpusTitle, ...(tagPath ? { tagPath } : {}), ...slice });
+            },
+        },
+    ];
+    return tools.map(t => (o.skills?.[t.name] ? { ...t, skill: o.skills[t.name] } : t));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",
@@ -127,6 +127,16 @@
       "import": "./dist/tree.js",
       "default": "./dist/tree.js"
     },
+    "./category": {
+      "types": "./dist/category.d.ts",
+      "import": "./dist/category.js",
+      "default": "./dist/category.js"
+    },
+    "./wiki-tools": {
+      "types": "./dist/wiki-tools.d.ts",
+      "import": "./dist/wiki-tools.js",
+      "default": "./dist/wiki-tools.js"
+    },
     "./feed": {
       "types": "./dist/feed.d.ts",
       "import": "./dist/feed.js",