wiki-formant 0.59.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.
@@ -60,7 +105,7 @@ const letters = taxonomy.alphaControls('ecosystem', all, state); // [] below the
 Every control arrives as `{value, label, count, href, active}`, its `href` already built through your one builder with **every other axis carried along** — the arithmetic that, done by hand, drops the reader's letter the first time they press a chip.
 
 - **The reset control leads the row**, flagged `reset`, so a consumer that maps the array cannot ship a narrowed view with nothing to press to widen it.
-- **`alphaControls` returns `[]` below the index threshold**, folding in `needsAlphaIndex` — one call is either the index you needed or nothing, rather than a decision each caller makes and one caller forgets.
+- **`alphaControls` returns `[]` below the index threshold**, folding in `needsAlphaIndex` — one call is either the index you needed or nothing, rather than a decision each caller makes and one caller forgets. A hub's sort toggle reads the same predicate over the same unfiltered count (`needsAlphaIndex(all.length)`; 40 pages unless `alphaIndexMinPages` says otherwise), so a set small enough to need no index offers no sort either.
 - **`resolveLetter` drops a letter no page starts with.** A stray `?letter=Q` would otherwise empty the grid with no control marked to explain why.
 
 
@@ -367,7 +412,7 @@ are unit-tested without a DOM.
 `wiki-formant/react` carries `'use client'`, and that is a module-level boundary: anything exported from it hydrates in the consumer's tree whether or not it uses a hook. `wiki-formant/react-server` is the same React, without the directive — for the parts of a wiki that are pure functions of their props and should ship no JavaScript at all.
 
 `FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site.
-`FacetBar` takes a `count` class to render each count as its own element, and `alphaFirst` to lead with the A–Z row. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
+`FacetBar` takes a `count` class to render each count as its own element, and `alphaFirst` to lead with the A–Z row. A chip row above the grid and a panel beside it are the same markup laid out by different stylesheets, so the class names are what tell them apart: `letterRow`, `letterControl` and `letterControlActive` style the A–Z row apart from the facet rows (each falls back to `row`, `control` or `controlActive`); a `text` class wraps each label in its own element and gives a facet option its value as `title`, so a long value can truncate while its count stays in view; and `letterCounts="title"` keeps each letter a bare glyph with its count in the tooltip. With none of them set the markup is what it was. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
 
 `PageNav` is the previous/next pair at the foot of an article — the sequential read the infobox rail's lateral links do not cover. Ordering is the caller's, because it is the one part that is never portable: a wiki's sequence is its section's configured sort, a knowledge base's is a taxonomy walk. Pair it with `adjacentPages` from `wiki-formant/pagination` over a list you already hold — neither wiki needs a query for it, and the two indexed lookups the neighbours used to cost were the reason one of them dropped the control.
 
@@ -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/react-server.d.ts

@@ -31,15 +31,35 @@ export declare const Anchor: WikiLinkComponent;
  * tree, which is a shared convention, these are each design system's own words
  * for a chip and a row. Defaults are given so a consumer that shares them writes
  * nothing.
+ *
+ * Whether the bar is a chip row above the grid or a panel beside it is decided
+ * here and nowhere else: the markup is the same, the stylesheet behind these
+ * names lays it out.
  */
 export interface FacetBarClassNames {
     root?: string;
+    /** Each facet's row, and the A–Z row unless `letterRow` is set. */
     row?: string;
+    /** A row's heading: the facet's label, or `alphaLabel`. */
     label?: string;
+    /** A facet option, and a letter unless `letterControl` is set. */
     control?: string;
     controlActive?: string;
     /** Set it and each count is its own `<span>` with this class, not ` (n)` text. */
     count?: string;
+    /**
+     * Set it and each control's text is its own `<span>` with this class, and a
+     * facet option carries its value as `title`: the hook for truncating a long
+     * value while its count stays in view, with the full value one hover away.
+     */
+    text?: string;
+    /**
+     * The A–Z row and its letters, which a panel draws as a block of glyphs
+     * while its facet options run full width. Each falls back to its shared key.
+     */
+    letterRow?: string;
+    letterControl?: string;
+    letterControlActive?: string;
 }
 export interface FacetBarProps {
     link: WikiLinkComponent;
@@ -49,6 +69,11 @@ export interface FacetBarProps {
     alphaLabel?: string;
     /** Lead with the A–Z row: two lines against a facet block's twenty. */
     alphaFirst?: boolean;
+    /**
+     * Where a letter's count goes. `'inline'` prints it like an option's;
+     * `'title'` keeps the letter a bare glyph and puts its count in the tooltip.
+     */
+    letterCounts?: 'inline' | 'title';
     classNames?: FacetBarClassNames;
     /** The landmark's accessible name. */
     label?: string;
@@ -63,7 +88,7 @@ export interface FacetBarProps {
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export declare function FacetBar({ link: Link, facets, letters, alphaLabel, alphaFirst, classNames, label: navLabel, }: FacetBarProps): import("react").JSX.Element | null;
+export declare function FacetBar({ link: Link, facets, letters, alphaLabel, alphaFirst, letterCounts, classNames, label: navLabel, }: FacetBarProps): import("react").JSX.Element | null;
 export interface FacetSummaryProps {
     shown: number;
     total: number;

package/dist/react-server.js

@@ -28,7 +28,8 @@ import { blockLocation } from './revisions.js';
  * Exported because `block-views` renders links too and had declared the same
  * three lines; a default that exists twice is a default that can diverge.
  */
-export const Anchor = ({ href, className, children }) => _jsx("a", { href: href, className: className, children: children });
+export const Anchor = (props) => _jsx("a", { ...props });
+const pagesPhrase = (n) => `${n} page${n === 1 ? '' : 's'}`;
 /**
  * The section's second axis, as pressable chips.
  *
@@ -39,20 +40,16 @@ export const Anchor = ({ href, className, children }) => _jsx("a", { href: href,
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', alphaFirst = false, classNames = {}, label: navLabel = 'Filter pages', }) {
+export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', alphaFirst = false, letterCounts = 'inline', classNames = {}, label: navLabel = 'Filter pages', }) {
     if (!facets.length && !letters.length)
         return null;
-    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', count, } = classNames;
-    const chip = (c) => (_jsxs(Link, { href: c.href, className: c.active ? controlActive : control, "aria-current": c.active ? 'true' : undefined, ...(c.title ? { title: c.title } : {}), children: [c.text, count ? _jsx("span", { className: count, children: c.n }) : ` (${c.n})`] }, c.key));
-    const facetRows = facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(o => chip({ key: o.value, href: o.href, active: o.active, text: o.value, n: o.count }))] }, facet.key)));
+    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', count, text, letterRow = row, letterControl = control, letterControlActive = controlActive, } = classNames;
+    const chip = (c, classes, opts) => (_jsxs(Link, { href: c.href, className: c.active ? classes.active : classes.idle, "aria-current": c.active ? 'true' : undefined, ...(opts.title ? { title: opts.title } : {}), children: [text ? _jsx("span", { className: text, children: c.label }) : c.label, opts.showCount && (count ? _jsx("span", { className: count, children: c.count }) : ` (${c.count})`)] }, c.value || 'all'));
+    const facetRows = facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(o => chip(o, { idle: control, active: controlActive }, { title: text ? o.label : undefined, showCount: true }))] }, facet.key)));
     // The reset control leads the letters and says what it resets to.
-    const alphaRow = letters.length > 0 && (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(l => chip({
-                key: l.value || 'all',
-                href: l.href,
-                active: l.active,
-                text: l.label,
-                n: l.count,
-                ...(l.reset ? { title: `All ${l.count} pages` } : {}),
+    const alphaRow = letters.length > 0 && (_jsxs("div", { className: letterRow, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(l => chip(l, { idle: letterControl, active: letterControlActive }, {
+                title: l.reset ? `All ${l.count} pages` : letterCounts === 'title' ? pagesPhrase(l.count) : undefined,
+                showCount: letterCounts === 'inline',
             }))] }, "alpha"));
     // A landmark: every control in it narrows the list below, and a screen
     // reader user skipping between regions should be able to land on it.