wiki-formant 0.60.0 → 0.61.0

package/README.md

@@ -10,12 +10,57 @@ 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.
+Every wiki needs a design system and a set of block types beyond the core. Those are the parts you must own: they encode your brand and your content model, and a package that tried to own them would fight you.
+
+The page store is no longer one of them. Three wikis kept their own pages and revisions on three schemas that had drifted apart (cuid ids against int ids, a version column on one, no author on another, a tenant key on the third), and each wrote its page and its revision its own way. The tables are now the package's (`prisma/wiki.prisma`), and so is the SQL that reads and writes them (`wiki-formant/store`), so one wiki engine serves a standalone wiki and a multi-tenant host alike. The connection, the cache and the auth stay the app's.
 
 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.
 
+## Store
+
+`wikiStore` reads and writes `WikiPage` and `WikiRevision` through one `Sql` function the app binds to its own client, scoped to one site.
+
+```ts
+import { wikiStore } from 'wiki-formant/store';
+
+const store = wikiStore({
+  sql: (query, ...values) => prisma.$queryRawUnsafe(query, ...values),
+  siteId: '',                 // a multi-tenant app passes the site's key
+  hidden: tree.hiddenPaths,   // back office: never listed unasked
+});
+
+const page = await store.get('contents/tech', 'radix-engine');
+const cards = await store.list('contents/tech', { sort: 'recent' });
+const { items, total } = await store.search('validators', { take: 20 });
+await store.save({ tagPath, slug, content, authorId, message, baseVersion: page.version });
+```
+
+- **A save is one statement.** The page update and its revision are a data-modifying CTE guarded on the version the save read. A save that lost a race writes nothing and throws a 409 `HttpError`; pass `baseVersion` and a save opened on an old version is refused the same way, instead of erasing the edit in between.
+- **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.
+- 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
+
+`createTree` is the category tree every wiki declares, and the walks each had written by hand.
+
+```ts
+import { createTree, parseWikiPath } from 'wiki-formant/tree';
+
+const tree = createTree(NODES, { globalKeys: [QUALITY] });
+tree.resolve('contents/tech');   // { node, trail, valid, hidden, sort, mainArticle, metadataKeys }
+parseWikiPath(tree, ['contents', 'tech', 'radix-engine', 'history']);
+// { type: 'page', tagPath: 'contents/tech', slug: 'radix-engine', mode: 'history' }
+```
+
+- Metadata keys accumulate down the trail; `sort`, `mainArticle` and `hidden` are inherited, the nearest declaration winning. A field only one wiki reads (an XRD threshold, a band) rides on the node, and the app folds it from `trail`.
+- 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.
+
 ## 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.
@@ -741,6 +786,10 @@ const SCHEMA: BlockSchema<Block> = {
 
 The dispatch stays a `switch` over the wiki's own union, so a new type is a compile error there. `CodeTabsFields`, `StatsFields`, `ReferencesFields`, `LinkGridFields`, `BannerFields`, `PageListFields`, `ColumnsFields` and `InfoboxFields` take the core blocks `wiki-formant/blocks` declares; the two containers hold the same list, offering `nestedTypes`. `Field`, `Choice` and `LimitField` are exported for a wiki's own editors, so its native types wear the same kit. A card is marked `data-selected` while it is being edited and `data-nested` inside a container; a type the build does not know is shown by its raw type and carried through untouched. Keep the kit and the schema stable — a module constant or a `useMemo` — since both reach every card through context, and a fresh one re-renders every card on every keystroke.
 
+An editor that draws each block in place, with a list of its own (miow's), hosts the same fields in `<BlockFieldsKit kit={KIT}>`, without `<BlockEditor>`. Only the two container fields need the full editor, since they hold a block list.
+
+A banner with no text of its own shows `BANNER_MESSAGES` from `wiki-formant/text`, a sentence per variant that names no wiki; `BannerView` takes it unless `message` overrides it.
+
 The core blocks are `ContentBlock`, `CodeTabsBlock`, `StatsBlock`, `LinkGridBlock`, `ReferencesBlock`, `BannerBlock`, `ColumnsBlock<A>` and `InfoboxBlock<A>`, `A` being the wiki's atomic union. A wiki builds its union from them beside its own `recentPages` and `pageList`, which hold its own page rows or a section, and its native types.
 
 ## Analytics
@@ -1037,17 +1086,16 @@ npx fts-ddl pages
 npx fts-ddl '"WikiPage"'
 ```
 
-`mark-verified` stamps `last_verified_at` on pages a sweep checked and found current, so `freshnessBanner` stops calling them outdated, and `maintenance-log` is the state I/O of a wiki-sweep routine whose memory lives in one page's `metadata.state`: `read`, `write` (the whole state, or `-` for stdin), `compact` and `backlog-add`, which appends under a row lock so another routine's item cannot be lost to a concurrent `write`. Every write compacts and re-renders the page, holding at most as many FLAG FOR A HUMAN items as the page shows; a revision is written at most once a day. `write` refuses a state whose `totalRuns` is below the stored one, which is a state read before another run wrote. Two wikis carried both scripts against their own tables, so the tables are arguments. Run them from the app's root, like `passkey-invite`:
+`mark-verified` stamps `lastVerifiedAt` on pages a sweep checked and found current, so `freshnessBanner` stops calling them outdated, and `maintenance-log` is the state I/O of a wiki-sweep routine whose memory lives in one page's `metadata.state`: `read`, `write` (the whole state, or `-` for stdin), `compact` and `backlog-add`, which appends under a row lock so another routine's item cannot be lost to a concurrent `write`. Every write compacts and re-renders the page, holding at most as many FLAG FOR A HUMAN items as the page shows; a revision is written at most once a day. `write` refuses a state whose `totalRuns` is below the stored one, which is a state read before another run wrote. Both work on the package's own `WikiPage` and `WikiRevision`. Run them from the app's root, like `passkey-invite`:
 
 ```sh
 npx mark-verified contents/tech/radix-engine scrypto       # one page
 npx mark-verified --all ecosystem --invalidate wiki        # a tag path, then the cache tag
 npx maintenance-log read --at contents/tech/operations/wiki-maintenance-log --routine wiki-sweep --author <id>
-npx maintenance-log backlog-add '[{"item": "…"}]' --at operations/wiki-maintenance-log --routine caper-wiki-sweep \
-  --pages wiki_pages --revisions wiki_revisions --page-key wiki_page_id --scope caper_id
+npx maintenance-log backlog-add '[{"item": "…"}]' --at operations/wiki-maintenance-log --routine caper-wiki-sweep
 ```
 
-`--scope column` keeps to rows where the column is NULL (`=value` for one value), `--table`/`--pages`/`--revisions` default to `pages` and `revisions`, and `--invalidate <tag>` runs `vercel cache invalidate` after a write.
+`--site <siteId>` names the wiki in a multi-tenant app (default `""`), and `--invalidate <tag>` runs `vercel cache invalidate` after a write.
 
 ## A reusable workflow
 

package/bin/maintenance-log.mjs

@@ -4,23 +4,21 @@
 // The routine's memory between runs lives in one wiki page's metadata.state,
 // and the page shows it, re-rendered and capped on every write (the rules are
 // `src/maintenance.ts`). radix-wiki and caper each carried this script with the
-// same rules against a different table, so the tables are arguments. Run it
-// from the app's root, where `pg` is installed and `.env` holds DATABASE_URL.
+// same rules against a different table; the tables are now the package's own
+// (`prisma/wiki.prisma`). Run it from the app's root, where `pg` is installed
+// and `.env` holds DATABASE_URL.
 //
 //   npx maintenance-log read                    # print the state as JSON
 //   npx maintenance-log write '<json>'          # replace it (or `write -` from stdin)
 //   npx maintenance-log compact [--dry-run]     # re-apply the caps to what is stored
 //   npx maintenance-log backlog-add '<json>'    # append items under a row lock
 //
-// with the page and its tables named every time:
+// with the page named every time:
 //
 //   --at <tagPath>/<slug>      the log page, e.g. contents/tech/operations/wiki-maintenance-log
 //   --routine <name>           named on the page and in the revision message
-//   --pages <table>            default pages
-//   --revisions <table>        default revisions
-//   --page-key <column>        the revisions column naming the page, default page_id
-//   --scope <column>[=<value>] only rows where the column is NULL, or equals the value
-//   --author <id>              revisions.author_id, default NULL
+//   --site <siteId>            the wiki the page belongs to, default "" (a one-wiki app)
+//   --author <id>              the revision's authorId, default NULL
 //   --invalidate <tag>         `vercel cache invalidate --tag` after a write
 //
 // `write` takes the whole new state: read, change, write back. A revision is
@@ -30,11 +28,9 @@
 // below the stored one: that state was read before another run wrote.
 // `backlog-add` is how another routine files an
 // item: `write` replaces the whole state, so an append through it could lose a
-// concurrent run's, and the row lock serialises the two. A revision's version
-// is the page's `version` column bumped a minor where the table has one, else
-// the latest revision's.
-import { randomUUID } from 'node:crypto';
-import { PINNED, addBacklog, compact, ident, render, scopeSql, staleWrite } from '../dist/maintenance.js';
+// concurrent run's, and the row lock serialises the two. A revision bumps the
+// page's version a minor.
+import { PINNED, addBacklog, compact, render, staleWrite } from '../dist/maintenance.js';
 import { bump } from '../dist/versioning.js';
 import { arg, connect, invalidate } from './_cli.mjs';
 
@@ -46,15 +42,13 @@ const routine = arg('--routine');
 const slugAt = at.lastIndexOf('/');
 
 if (!['read', 'write', 'compact', 'backlog-add'].includes(mode) || slugAt < 1 || !routine) {
-  console.error('usage: maintenance-log <read|write|compact|backlog-add> [json|-] --at <tagPath>/<slug> --routine <name> [--pages t] [--revisions t] [--page-key c] [--scope c[=v]] [--author id] [--invalidate tag] [--dry-run]');
+  console.error('usage: maintenance-log <read|write|compact|backlog-add> [json|-] --at <tagPath>/<slug> --routine <name> [--site id] [--author id] [--invalidate tag] [--dry-run]');
   process.exit(2);
 }
-const pages = ident(arg('--pages') ?? 'pages', '--pages');
-const revisions = ident(arg('--revisions') ?? 'revisions', '--revisions');
-const pageKey = ident(arg('--page-key') ?? 'page_id', '--page-key');
-const scope = scopeSql(arg('--scope'), 3);
-const where = `tag_path = $1 AND slug = $2 AND ${scope.sql}`;
-const address = [at.slice(0, slugAt), at.slice(slugAt + 1), ...scope.values];
+const pages = '"WikiPage"';
+const revisions = '"WikiRevision"';
+const where = `"tagPath" = $1 AND slug = $2 AND "siteId" = $3`;
+const address = [at.slice(0, slugAt), at.slice(slugAt + 1), arg('--site') ?? ''];
 
 const readStdin = async () => {
   let data = '';
@@ -90,7 +84,7 @@ try {
       for (const a of added) console.log(`     ${a.item}`);
       if (dry) await q('ROLLBACK');
       else {
-        await q(`UPDATE ${pages} SET content = $1, metadata = $2, updated_at = now() WHERE id = $3`, [
+        await q(`UPDATE ${pages} SET content = $1, metadata = $2, "updatedAt" = now() WHERE id = $3`, [
           JSON.stringify(render(next, routine)),
           JSON.stringify({ state: next, lastVerified: today }),
           page.id,
@@ -114,12 +108,11 @@ try {
     const content = render(state, routine);
 
     const [last] = await q(
-      `SELECT version, created_at FROM ${revisions} WHERE ${pageKey} = $1 ORDER BY created_at DESC LIMIT 1`,
+      `SELECT "createdAt" FROM ${revisions} WHERE "pageId" = $1 ORDER BY "createdAt" DESC LIMIT 1`,
       [page.id],
     );
-    const revise = mode === 'compact' || !last || last.created_at.toISOString().slice(0, 10) !== today;
-    const was = 'version' in page ? page.version : last?.version;
-    const version = revise ? bump(was, 'minor') : was;
+    const revise = mode === 'compact' || !last || last.createdAt.toISOString().slice(0, 10) !== today;
+    const version = revise ? bump(page.version, 'minor') : page.version;
 
     for (const key of ['backlog', 'runHistory', 'feedback']) {
       const [before, after] = [(input[key] ?? []).length, state[key].length];
@@ -140,32 +133,18 @@ try {
     if (!dry) {
       await q('BEGIN');
       await q(
-        `UPDATE ${pages} SET content = $1, metadata = $2, updated_at = now()${'version' in page ? ', version = $4' : ''} WHERE id = $3`,
-        [JSON.stringify(content), JSON.stringify({ state, lastVerified: today }), page.id, ...('version' in page ? [version] : [])],
+        `UPDATE ${pages} SET content = $1, metadata = $2, "updatedAt" = now(), version = $4 WHERE id = $3`,
+        [JSON.stringify(content), JSON.stringify({ state, lastVerified: today }), page.id, version],
       );
       if (revise) {
-        // An id with no database default (a Prisma cuid) is supplied here.
-        const [{ has_default }] = await q(
-          `SELECT column_default IS NOT NULL AS has_default FROM information_schema.columns
-           WHERE table_schema = current_schema() AND table_name = $1 AND column_name = 'id'`,
-          [revisions.slice(1, -1)],
-        );
-        const row = {
-          ...(has_default ? {} : { id: randomUUID() }),
-          [pageKey.slice(1, -1)]: page.id,
-          title: page.title,
-          content: JSON.stringify(content),
-          version,
-          change_type: 'minor',
-          author_id: arg('--author') ?? null,
-          message: mode === 'compact'
-            ? 'Compact the log: drop closed and duplicated backlog items, cap the append-only lists'
-            : `${routine} run ${state.lastRun ?? today}`,
-        };
-        const columns = Object.keys(row);
         await q(
-          `INSERT INTO ${revisions} (${columns.map(c => `"${c}"`).join(', ')}) VALUES (${columns.map((_, i) => `$${i + 1}`).join(', ')})`,
-          Object.values(row),
+          `INSERT INTO ${revisions} ("pageId", title, content, version, "changeType", "authorId", message) VALUES ($1, $2, $3, $4, 'minor', $5, $6)`,
+          [
+            page.id, page.title, JSON.stringify(content), version, arg('--author') ?? null,
+            mode === 'compact'
+              ? 'Compact the log: drop closed and duplicated backlog items, cap the append-only lists'
+              : `${routine} run ${state.lastRun ?? today}`,
+          ],
         );
       }
       await q('COMMIT');

package/bin/mark-verified.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// bin/mark-verified.mjs – stamp last_verified_at on pages a sweep has checked
+// bin/mark-verified.mjs – stamp lastVerifiedAt on pages a sweep has checked
 // against their sources and found current, so `freshnessBanner`
 // (`wiki-formant/freshness`) stops calling them outdated. A page that needed an
 // edit gets its revision instead; this is for one that did not.
@@ -10,36 +10,33 @@
 //   npx mark-verified <tagPath> <slug>          one page ('' is a category hub)
 //   npx mark-verified --all <tagPath>           every page at or under a tag path
 //
-//   --table <table>             default pages
-//   --scope <column>[=<value>]  only rows where the column is NULL, or equals the value
+//   --site <siteId>             the wiki the pages belong to, default "" (a one-wiki app)
 //   --invalidate <tag>          `vercel cache invalidate --tag` after a write
-import { ident, scopeSql } from '../dist/maintenance.js';
 import { arg, connect, invalidate } from './_cli.mjs';
 
 const args = process.argv.slice(2);
 const all = args.includes('--all');
-const [tagPath, slug] = args.filter((a, i) => !a.startsWith('--') && !['--table', '--scope', '--invalidate'].includes(args[i - 1]));
+const [tagPath, slug] = args.filter((a, i) => !a.startsWith('--') && !['--site', '--invalidate'].includes(args[i - 1]));
 
 if (!tagPath || (!all && slug === undefined)) {
-  console.error('usage: mark-verified <tagPath> <slug> | --all <tagPath>  [--table t] [--scope c[=v]] [--invalidate tag]');
+  console.error('usage: mark-verified <tagPath> <slug> | --all <tagPath>  [--site id] [--invalidate tag]');
   process.exit(2);
 }
-const table = ident(arg('--table') ?? 'pages', '--table');
-const scope = scopeSql(arg('--scope'), 3);
+const site = arg('--site') ?? '';
 
 let client;
 try {
   client = await connect();
   const { rowCount } = all
     ? await client.query(
-        `UPDATE ${table} SET last_verified_at = now() WHERE (tag_path = $1 OR tag_path LIKE $2) AND ${scope.sql}`,
-        [tagPath, `${tagPath}/%`, ...scope.values],
+        `UPDATE "WikiPage" SET "lastVerifiedAt" = now() WHERE "siteId" = $3 AND ("tagPath" = $1 OR "tagPath" LIKE $2)`,
+        [tagPath, `${tagPath}/%`, site],
       )
     : await client.query(
-        `UPDATE ${table} SET last_verified_at = now() WHERE tag_path = $1 AND slug = $2 AND ${scope.sql}`,
-        [tagPath, slug, ...scope.values],
+        `UPDATE "WikiPage" SET "lastVerifiedAt" = now() WHERE "siteId" = $3 AND "tagPath" = $1 AND slug = $2`,
+        [tagPath, slug, site],
       );
-  console.log(`Stamped last_verified_at on ${rowCount} page(s).`);
+  console.log(`Stamped lastVerifiedAt on ${rowCount} page(s).`);
   const tag = arg('--invalidate');
   if (rowCount && tag) await invalidate(tag);
 } catch (e) {

package/bin/prisma-models.mjs

@@ -2,18 +2,18 @@
 // bin/prisma-models.mjs – copy the Prisma models wiki-formant's SQL reads into an
 // app's schema folder, or check that the copies there have not drifted.
 //
-// `wiki-formant/analytics` and `wiki-formant/passkey` own their SQL and name
+// `wiki-formant/analytics`, `wiki-formant/passkey` and `wiki-formant/store` own their SQL and name
 // their tables as written, so the models are the package's. Three apps carried
 // them byte for byte, and the package kept a fourth copy as a comment.
 //
 // Prisma reads a schema split across the .prisma files of one folder. The app
 // points prisma.config.ts at the folder (`schema: 'prisma/schema'`), keeps its
 // generator, datasource and own models in prisma/schema/schema.prisma, and this
-// writes analytics.prisma and passkey.prisma beside them. Run it from the app's
+// writes analytics.prisma, passkey.prisma and wiki.prisma beside them. Run it from the app's
 // root:
 //
-//   npx prisma-models                   # write both into prisma/schema
-//   npx prisma-models --check           # exit 1 if either is missing or differs
+//   npx prisma-models                   # write all three into prisma/schema
+//   npx prisma-models --check           # exit 1 if any is missing or differs
 //   npx prisma-models analytics         # only the ones named
 //   npx prisma-models --dir db/schema   # another folder
 //
@@ -26,7 +26,7 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { arg } from './_cli.mjs';
 
-const MODELS = ['analytics', 'passkey'];
+const MODELS = ['analytics', 'passkey', 'wiki'];
 const args = process.argv.slice(2);
 const check = args.includes('--check');
 const dir = arg('--dir') ?? 'prisma/schema';

package/dist/block-editor.d.ts

@@ -120,6 +120,15 @@ export interface BlockSchema<B extends EditableBlock> {
     /** Types a list holds at most one of, such as an infobox an article lifts into its rail. */
     single?: readonly B['type'][];
 }
+/**
+ * The core blocks' fields outside a `<BlockEditor>`, in `kit`'s style: for an
+ * editor that draws each block in place and has a list of its own, as miow's
+ * does. The two container fields hold a block list and still need the editor.
+ */
+export declare function BlockFieldsKit({ kit, children }: {
+    kit: BlockEditorKit;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export interface BlockEditorProps<B extends EditableBlock> {
     blocks: B[];
     onChange: (blocks: B[]) => void;

package/dist/block-editor.js

@@ -34,6 +34,25 @@ function useEditorContext() {
         throw new Error('A block field editor must render inside <BlockEditor>.');
     return ctx;
 }
+const NO_LIST = {
+    meta: () => undefined,
+    create: () => {
+        throw new Error('ColumnsFields and InfoboxFields hold a block list: render them inside <BlockEditor>.');
+    },
+    duplicate: block => block,
+    renderBody: () => null,
+    types: [],
+    nestedTypes: [],
+};
+/**
+ * The core blocks' fields outside a `<BlockEditor>`, in `kit`'s style: for an
+ * editor that draws each block in place and has a list of its own, as miow's
+ * does. The two container fields hold a block list and still need the editor.
+ */
+export function BlockFieldsKit({ kit, children }) {
+    const value = useMemo(() => ({ kit, schema: NO_LIST }), [kit]);
+    return _jsx(Context.Provider, { value: value, children: children });
+}
 /**
  * A page's blocks, edited: each in a card with its add-below, move, duplicate
  * and delete controls, and an add menu at the foot. Columns and infoboxes hold

package/dist/block-views.d.ts

@@ -119,7 +119,8 @@ export declare function StatsView({ items, columns, }: {
 export declare function BannerView({ variant, text, message, icon, policy, }: {
     variant: string;
     text?: string | null;
-    message: string;
+    /** The sentence when the block has none. Defaults to `BANNER_MESSAGES`. */
+    message?: string;
     icon?: ReactNode;
     policy?: string;
 }): import("react").JSX.Element;

package/dist/block-views.js

@@ -21,7 +21,7 @@ import { Fragment, useState } from 'react';
 import { Anchor } from './react-server.js';
 import { safeLinkHref } from './validation.js';
 import { cx } from './html.js';
-import { BANNER_LABELS, bannerVariant } from './text.js';
+import { BANNER_LABELS, BANNER_MESSAGES, bannerVariant } from './text.js';
 /**
  * Tabbed code samples. Every tab's body stays mounted and the inactive ones are
  * hidden rather than unmounted: remounting a highlighted panel would re-run
@@ -129,6 +129,7 @@ export function StatsView({ items, columns = 4, }) {
  */
 export function BannerView({ variant, text, message, icon, policy, }) {
     const known = bannerVariant(variant);
+    message ??= BANNER_MESSAGES[known];
     const label = BANNER_LABELS[known];
     return (_jsxs("div", { className: cx('editorial-banner', `editorial-banner-${known}`), role: "note", children: [icon, _jsxs("p", { className: "editorial-banner-body", children: [_jsxs("strong", { children: [policy ? _jsx("a", { href: policy, children: label }) : label, "."] }), " ", text?.trim() || message] })] }));
 }

package/dist/maintenance.d.ts

@@ -55,14 +55,3 @@ export declare function render(state: LogState, routine: string, newId?: () => s
     type: "content";
     text: string;
 }[];
-/** A table or column name from the command line, quoted, or a thrown usage error. */
-export declare function ident(name: string | undefined, what: string): string;
-/**
- * `--scope column` limits a bin to rows whose column is NULL, `--scope
- * column=value` to rows where it equals the value: caper's platform pages
- * have no caper, and its company pages share their tag paths.
- */
-export declare function scopeSql(scope: string | undefined, param: number): {
-    sql: string;
-    values: unknown[];
-};

package/dist/maintenance.js

@@ -132,23 +132,3 @@ export function render(state, routine, newId = () => crypto.randomUUID()) {
         block(`<h2>Recent runs</h2>${table(['Date', 'Category', 'Summary', 'Tweet'], runRows)}`),
     ];
 }
-const IDENT = /^[a-z_][a-z0-9_]*$/;
-/** A table or column name from the command line, quoted, or a thrown usage error. */
-export function ident(name, what) {
-    if (!name || !IDENT.test(name))
-        throw new Error(`${what} must be a lower-case SQL identifier, got ${JSON.stringify(name)}`);
-    return `"${name}"`;
-}
-/**
- * `--scope column` limits a bin to rows whose column is NULL, `--scope
- * column=value` to rows where it equals the value: caper's platform pages
- * have no caper, and its company pages share their tag paths.
- */
-export function scopeSql(scope, param) {
-    if (!scope)
-        return { sql: 'TRUE', values: [] };
-    const [column, value] = scope.split('=');
-    return value === undefined
-        ? { sql: `${ident(column, '--scope')} IS NULL`, values: [] }
-        : { sql: `${ident(column, '--scope')} = $${param}`, values: [value] };
-}

package/dist/mcp.d.ts

@@ -39,7 +39,7 @@ export type ToolParam = {
     description: string;
     enum?: string[];
     items?: {
-        type: 'string' | 'number' | 'object';
+        type?: 'string' | 'number' | 'object';
     };
 };
 export type ToolSchema = {

package/dist/mcp.js

@@ -203,11 +203,14 @@ function validateArgs(tool, args) {
             }
         }
         else if (spec.type === 'array') {
-            const itemType = spec.items?.type ?? 'string';
+            // No `items` means strings. Items with no one type (a `oneOf` of shapes,
+            // as a zod union emits) are the tool's own to check: read as strings, every
+            // well-formed call was refused.
+            const itemType = spec.items ? spec.items.type : 'string';
             if (actual !== 'array') {
-                problems.push(`Parameter "${key}" must be an array of ${itemType}s; received ${actual} (${JSON.stringify(value)}).`);
+                problems.push(`Parameter "${key}" must be an array${itemType ? ` of ${itemType}s` : ''}; received ${actual} (${JSON.stringify(value)}).`);
             }
-            else if (value.some(item => typeOf(item) !== itemType)) {
+            else if (itemType && value.some(item => typeOf(item) !== itemType)) {
                 problems.push(`Parameter "${key}" must contain only ${itemType}s.`);
             }
         }

package/dist/store.d.ts

@@ -0,0 +1,166 @@
+import type { Sql } from './analytics.js';
+import type { BlockGroup, DiffBlock } from './revisions.js';
+import { type ChangeType } from './versioning.js';
+import { type HistoryChange } from './history.js';
+export type { Sql };
+export type PageMetadata = Record<string, unknown>;
+/** A page as stored. */
+export interface WikiPageRow<B = unknown> {
+    id: string;
+    siteId: string;
+    tagPath: string;
+    slug: string;
+    title: string;
+    content: B[];
+    metadata: PageMetadata;
+    version: string;
+    authorId: string | null;
+    lastVerifiedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * A page as a listing carries it: one line of the article instead of the
+ * article. A category of 200 cards otherwise ships 200 block arrays to the
+ * browser.
+ */
+export type WikiPageListing = Omit<WikiPageRow, 'content'> & {
+    snippet: string;
+};
+export interface WikiPageRef {
+    tagPath: string;
+    slug: string;
+    title: string;
+}
+export interface WikiRevisionRow<B = unknown> {
+    id: string;
+    pageId: string;
+    title: string;
+    content: B[];
+    version: string;
+    changeType: string;
+    message: string | null;
+    authorId: string | null;
+    createdAt: Date;
+}
+export type WikiRevisionEntry = Omit<WikiRevisionRow, 'content'> & {
+    changes: HistoryChange[];
+};
+export type ListSort = 'title' | 'recent' | 'date';
+export interface WikiStoreOptions<B extends DiffBlock> {
+    sql: Sql;
+    /** The site every read and write is scoped to. "" in an app that serves one wiki. */
+    siteId?: string;
+    /**
+     * Tag paths a listing leaves out unless it names them: a wiki's back office,
+     * such as the maintenance log a routine rewrites every few hours. A hidden
+     * page keeps its URL, its twin and its history; it never arrives unasked.
+     */
+    hidden?: readonly string[];
+    /** The block tree's containers, for diffs. Defaults to the core model's (`coreBlockGroups`). */
+    containers?: (block: B) => BlockGroup<B>[] | null;
+    /**
+     * A listing's line for a page when nothing better is found: a search hit
+     * whose match is in the title alone, and every card. Defaults to the
+     * article's opening; a wiki that keeps a written summary in metadata says so.
+     */
+    snippet?: (page: Pick<WikiPageRow<B>, 'content' | 'metadata'>) => string;
+}
+export interface SaveInput<B> {
+    tagPath: string;
+    slug: string;
+    title?: string;
+    content?: B[];
+    /** Replaces the page's metadata whole. Omit to keep it. */
+    metadata?: PageMetadata;
+    authorId?: string | null;
+    /** The history's line for this save. Defaults to what the diff found ("1 block modified"). */
+    message?: string | null;
+    /**
+     * The version the writer opened. A save that finds the page has moved on is
+     * refused with 409 rather than quietly overwriting the edit in between.
+     */
+    baseVersion?: string;
+    /**
+     * The bump to record instead of the one the diff picks, for a writer that
+     * knows. Stated, it always writes a revision, even for a save the diff finds
+     * empty: a routine recording a reading in metadata wants it in the history.
+     */
+    change?: Exclude<ChangeType, 'none'>;
+    /** The writer's word that the page's facts were checked: stamps `lastVerifiedAt`. */
+    verified?: boolean;
+    /** Moves the page to another slug in the same tag path. */
+    newSlug?: string;
+}
+export interface SaveResult<B> {
+    page: WikiPageRow<B>;
+    created: boolean;
+    /** `none` when the save changed nothing a revision records, so none was written. */
+    changeType: ChangeType;
+    summary: string;
+}
+/** A row as a listing carries it, for an app that runs a listing query of its own. */
+export declare function toListing<R extends {
+    content?: unknown;
+}>(row: R): Omit<R, 'content'> & {
+    snippet: string;
+};
+/** Re-order rows to match an id list, dropping ids that no longer resolve. */
+export declare function orderByIds<T extends {
+    id: string;
+}>(rows: readonly T[], ids: readonly string[]): T[];
+export declare function wikiStore<B extends DiffBlock = DiffBlock>(o: WikiStoreOptions<B>): {
+    siteId: string;
+    hidden: string[];
+    isHidden: (tagPath: string) => boolean;
+    get: (tagPath: string, slug: string) => Promise<NonNullable<WikiPageRow<B> & {
+        revisionCount: number;
+    }> | null>;
+    getById: (id: string) => Promise<NonNullable<WikiPageRow<B> & {
+        revisionCount: number;
+    }> | null>;
+    list: (tagPath: string, { sort, limit, offset }?: {
+        sort?: ListSort;
+        limit?: number;
+        offset?: number;
+    }) => Promise<WikiPageListing[]>;
+    articles: (tagPath: string, { sort, limit, offset }?: {
+        sort?: ListSort;
+        limit?: number;
+        offset?: number;
+    }) => Promise<WikiPageRow<B>[]>;
+    subtree: (tagPath: string) => Promise<WikiPageRef[]>;
+    recent: ({ tagPath, limit }?: {
+        tagPath?: string;
+        limit?: number;
+    }) => Promise<WikiPageListing[]>;
+    byIds: (ids: readonly string[]) => Promise<WikiPageListing[]>;
+    refs: () => Promise<Omit<WikiPageRow<unknown>, "content">[]>;
+    corpus: () => Promise<WikiPageRow<B>[]>;
+    stats: () => Promise<{
+        pages: number;
+        updated: Date | null;
+    }>;
+    search: (query: string, { tagPath, skip, take }?: {
+        tagPath?: string | null;
+        skip?: number;
+        take?: number;
+    }) => Promise<{
+        items: (WikiPageListing & {
+            score: number;
+        })[];
+        total: number;
+    }>;
+    history: (pageId: string, { limit, offset }?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<WikiRevisionEntry[]>;
+    revision: (pageId: string, revisionId: string) => Promise<WikiRevisionRow<B> | null>;
+    save: (input: SaveInput<B>) => Promise<SaveResult<B>>;
+    restore: (tagPath: string, slug: string, revisionId: string, by?: {
+        authorId?: string | null;
+    }) => Promise<SaveResult<B>>;
+    remove: (tagPath: string, slug: string) => Promise<boolean>;
+    verify: (tagPath: string, slug: string) => Promise<boolean>;
+};
+export type WikiStore<B extends DiffBlock = DiffBlock> = ReturnType<typeof wikiStore<B>>;