wiki-formant 0.86.1 → 0.86.3

package/dist/scripts.js

@@ -1,138 +1,144 @@
-// scripts.ts — what a wiki's direct-database scripts share: the client, the
-// store over it, the block builders, the shape check and the revision write.
+// scripts.ts — what a wiki's seed and sweep scripts share: a client on the
+// app's database that rolls back on a throw and expires the wiki's cache tag
+// after a write, the store over it, the block builders, and the two writes
+// every script makes: a revision over a page it read, and an upsert.
 //
-// Node-only. A script bypasses the app's write routes, so it bypasses their
-// validation and their cache busting too; both are here so no script can skip
-// them. radix-wiki's seed-utils.mjs and caper's wiki-utils.ts had each written
-// this half, and each had a piece the other lacked: the shape check, the
-// write-tracking pool and the rollback on one side, the upsert that records a
-// revision only when something changed on the other.
-import { execFileSync } from 'node:child_process';
+// radix-wiki's `seed-utils.mjs` and caper's `wiki-utils.ts` had each written
+// these, in different languages, with different halves of the same guards.
+// Node-only, like the bins: `pg` is the app's, imported when a client is made.
 import { randomUUID } from 'node:crypto';
-import { bump } from './versioning.js';
+import { execFileSync } from 'node:child_process';
 import { wikiStore } from './store.js';
+import { bump } from './versioning.js';
 import { validateLinkGroups, validateReferenceItems } from './validation.js';
-// ---- block builders ---------------------------------------------------------
 export const uid = () => randomUUID();
-export const content = (html) => ({ id: uid(), type: 'content', text: html });
-/**
- * A notice. Always pass `text`: the variant's standard message lives in the
- * renderer, not the row, so a banner without it is invisible to search.
- */
+export const content = (text) => ({ id: uid(), type: 'content', text });
+/** Always pass `text`: the renderer's default message lives in React, and search indexes only what the row holds. */
 export const banner = (variant, text) => ({ id: uid(), type: 'banner', variant, text });
-/** A facts panel leading an article: `table` is the inner `<table>` HTML. */
+/** A facts panel that leads an article: `table` is the inner `<table>` HTML. */
 export const infobox = (table) => ({ id: uid(), type: 'infobox', blocks: [content(table)] });
-// ---- the shape check --------------------------------------------------------
 /**
- * Throw on a link-grid link or reference list whose URL fields are mis-shaped.
- *
- * The app's validator rejects these, and scripts never reach it. The views drop
- * an entry whose URL fails rather than rendering it inert, so a `{ label, url }`
- * link (the shape is `{ label, href }`) shows as a heading with no pills and
- * nothing reports it. A throw inside `withClient` is a rollback and a failed run.
+ * Refuse block content whose URL-bearing leaves are mis-shaped, before it
+ * reaches the database. `LinkGridView` and `ReferencesView` drop an entry whose
+ * URL fails `safeLinkHref` rather than rendering it inert, so a one-field slip
+ * (`url` for a link, whose shape is `{ label, href }`) shows as a heading with
+ * no pills and nothing reports it. Throws, so `withClient` rolls back.
  */
 export function assertLinkShapes(blocks, where = 'content') {
     const bad = [];
     const leaf = (b, path) => {
-        if (!b || typeof b !== 'object')
+        const block = b;
+        if (!block || typeof block !== 'object')
             return;
-        if (b.type === 'linkGrid')
-            for (const [gi, g] of (b.groups ?? []).entries())
-                for (const [li, l] of (g?.links ?? []).entries())
-                    if (!validateLinkGroups([{ id: '', heading: '', links: [l] }]))
+        if (block.type === 'linkGrid') {
+            for (const [gi, g] of (block.groups ?? []).entries()) {
+                for (const [li, l] of (g?.links ?? []).entries()) {
+                    if (!validateLinkGroups([{ id: '', heading: '', links: [l] }])) {
                         bad.push(`${path}.groups[${gi}].links[${li}] "${l?.label ?? '(no label)'}" has fields {${Object.keys(l ?? {}).sort().join(', ')}} -- LinkGridLink is { label, href }`);
-        if (b.type === 'references' && !validateReferenceItems(b.items))
+                    }
+                }
+            }
+        }
+        if (block.type === 'references' && !validateReferenceItems(block.items))
             bad.push(`${path}.items -- ReferenceItem is { id, text, url? }`);
     };
-    (Array.isArray(blocks) ? blocks : []).forEach((b, i) => {
+    blocks.forEach((b, i) => {
         leaf(b, `[${i}]`);
-        if (b?.type === 'infobox')
-            (b.blocks ?? []).forEach((n, j) => leaf(n, `[${i}].blocks[${j}]`));
-        if (b?.type === 'columns')
-            (b.columns ?? []).forEach((c, ci) => (c?.blocks ?? []).forEach((n, j) => leaf(n, `[${i}].columns[${ci}].blocks[${j}]`)));
+        const block = b;
+        if (block?.type === 'infobox')
+            (block.blocks ?? []).forEach((n, j) => leaf(n, `[${i}].blocks[${j}]`));
+        if (block?.type === 'columns') {
+            (block.columns ?? []).forEach((c, ci) => (c?.blocks ?? []).forEach((n, j) => leaf(n, `[${i}].columns[${ci}].blocks[${j}]`)));
+        }
     });
     if (bad.length)
         throw new Error(`${where}: ${bad.length} mis-shaped link(s)\n  ${bad.join('\n  ')}`);
 }
-// ---- the client and the cache -----------------------------------------------
-/**
- * Mark everything cached under `tag` stale on the project `cwd` is linked to.
- * A script's write reaches no route that would bust it, and pages hold a day.
- */
-export function invalidate(tag, cwd = process.cwd()) {
+/** `vercel cache invalidate --tag`, reported either way. */
+export function invalidate(tag, cwd) {
     try {
-        execFileSync('vercel', ['cache', 'invalidate', '--tag', tag, '--yes'], { cwd, stdio: 'ignore' });
+        execFileSync('vercel', ['cache', 'invalidate', '--tag', tag, '--yes'], { stdio: 'ignore', ...(cwd ? { cwd } : {}) });
         console.log(`cache: ${tag} tag invalidated`);
     }
     catch (e) {
-        console.warn(`cache: ${tag} tag NOT invalidated (${e.message}); run \`vercel cache invalidate --tag ${tag}\` from ${cwd}`);
+        console.warn(`cache: ${tag} tag NOT invalidated (${e.message}); run \`vercel cache invalidate --tag ${tag}\``);
     }
 }
 /**
- * Run `fn` on a connected client, then release it and its pool. A throw rolls
- * back the open transaction and fails the process: every script writes to the
- * live database, and a half-applied edit must never pass for a success. A run
- * that wrote anything ends by invalidating `tag`.
+ * Run `fn` against a connected client, then release the client and the pool.
+ * A throw rolls back whatever transaction was open and fails the process:
+ * every one of these scripts writes to the live database, so a half-applied
+ * edit must never be left behind and never look like a success. A run that
+ * wrote anything ends by expiring the wiki's cache tag, because a script
+ * bypasses the routes that purge the pages they change.
  */
-export async function withClient(fn, { tag = 'wiki', cwd = process.cwd() } = {}) {
-    const { default: pg } = await import('pg');
-    const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 1, ssl: { rejectUnauthorized: false } });
-    const conn = await pool.connect();
+export async function withClient(fn, { tag = 'wiki', cwd, url } = {}) {
+    if (!url && !process.env.DATABASE_URL) {
+        try {
+            process.loadEnvFile('.env');
+        }
+        catch {
+            // reported below
+        }
+    }
+    const connectionString = url ?? process.env.DATABASE_URL;
+    if (!connectionString)
+        throw new Error('no DATABASE_URL in the environment or ./.env');
+    const { default: pg } = (await import('pg'));
+    const pool = new pg.Pool({ connectionString, max: 1, ssl: { rejectUnauthorized: false } });
+    const client = await pool.connect();
     let wrote = false;
-    const client = {
-        query: (text, values) => {
-            // Anywhere in the text: the store's writes are data-modifying CTEs.
-            if (/\b(insert\s+into|update\s+\S+\s+set|delete\s+from)\b/i.test(text))
-                wrote = true;
-            return conn.query(text, values);
-        },
+    const query = client.query.bind(client);
+    client.query = (text, values) => {
+        if (/\b(insert\s+into|update\s+\S+\s+set|delete\s+from)\b/i.test(text))
+            wrote = true;
+        return query(text, values);
     };
     try {
         return await fn(client);
     }
     catch (e) {
-        await conn.query('ROLLBACK').catch(() => { });
+        await client.query('ROLLBACK').catch(() => { });
         console.error('ERROR:', e.message);
         process.exitCode = 1;
         return undefined;
     }
     finally {
-        conn.release();
+        client.release();
         await pool.end();
-        // A run that throws part-way may have committed earlier writes.
         if (wrote)
             invalidate(tag, cwd);
     }
 }
-// ---- reads and writes through the app's store ---------------------------------
-/** The app's own store over a script's client, so a script writes what the editor writes. */
+/** The app's own store over a script's client, so a script writes exactly what the editor writes. */
 export const storeFor = (client, siteId = '') => wikiStore({ sql: async (q, ...v) => (await client.query(q, v)).rows, siteId });
 /** A page row by path, every column: what `writeRevision` takes. Null when there is none. */
-export const readPage = (client, tagPath, slug, siteId = '') => storeFor(client, siteId).get(tagPath, slug);
+export const readPage = (client, tagPath, slug, siteId) => storeFor(client, siteId).get(tagPath, slug);
 /**
- * Write edited blocks back to a page row from `readPage` as one revision. The
- * save names the version it read, so an edit landing in between is refused
- * (409) rather than overwritten. Returns the new version.
+ * Write edited blocks back to a page from `readPage` as one revision, through
+ * the store: the page and its revision in one statement, the version bumped
+ * from the stored one by `change`. The save names the version it read, so an
+ * edit landing in between is refused (409) instead of overwritten. Returns the
+ * new version.
  */
-export async function writeRevision(client, page, blocks, { change = 'minor', message, verified = false, dry = false, metadata, authorId = null } = {}) {
+export async function writeRevision(client, page, blocks, { change = 'minor', message, verified = false, dry = false, metadata, authorId = null, siteId } = {}) {
     if (dry)
         return bump(page.version, change);
     assertLinkShapes(blocks, page.title);
-    const { page: saved } = await storeFor(client, page.siteId).save({
+    const { page: saved } = await storeFor(client, siteId).save({
         tagPath: page.tagPath, slug: page.slug, content: blocks, metadata,
         change, message, verified, authorId, baseVersion: page.version,
     });
     return saved.version;
 }
 /**
- * Create a page or update it in place, keyed by site, tag path and slug. A
- * change to its title or blocks writes a revision; a re-run that changes
- * nothing writes none. `change` records that bump instead of the diff's, and
- * always writes one.
+ * Create a page, or replace its title and blocks: a change writes a revision
+ * bumped from the page's own version, a re-run that changes nothing writes
+ * none, and a stated `change` always records one.
  */
 export async function upsertWikiPage(client, input) {
-    const { siteId = '', ...save } = input;
-    assertLinkShapes(save.content, `${save.tagPath}/${save.slug}`);
+    assertLinkShapes(input.content, `${input.tagPath}/${input.slug}`);
+    const { siteId, ...save } = input;
     const { created } = await storeFor(client, siteId).save(save);
     return created ? 'created' : 'updated';
 }

package/dist/validation.d.ts

@@ -1,4 +1,3 @@
-import { type BlockTreeShape } from './blocks.js';
 /**
  * An href acceptable to persist: http, https, mailto, tel, or a relative path or
  * fragment. Everything else — `javascript:`, `data:`, `vbscript:`, a
@@ -87,45 +86,39 @@ export declare function duplicateBlockIds<B extends {
     type: string;
     id: string;
 }>(block: B, newId?: () => string): B;
-type Checked = Record<string, unknown>;
+/** A leaf check over the stored record; `core` is the package's check for the core types. */
+export type LeafCheck = (block: Record<string, unknown>, core: (block: Record<string, unknown>) => boolean) => boolean;
 export interface BlockModelOptions<B extends {
     id: string;
     type: string;
 }> {
-    /** What inserting each type makes. Its keys are the types this wiki knows. */
+    /** A new block of every type, without its id: `{ ...coreBlockDefaults(), daoTimeline: () => … }`. */
     defaults: Record<B['type'], () => Omit<B, 'id'>>;
-    /**
-     * The leaf check for each native type, and for a core type the wiki narrows.
-     * `core` is the core check, for a narrowing that adds to it rather than
-     * replacing it. A type with no entry gets the core check.
-     */
-    checks?: Partial<Record<B['type'], (block: Checked, core: (block: Checked) => boolean) => boolean>>;
-    /** As `coreAtomicValidator`'s. */
+    /** The wiki's own leaf checks, and any core check it narrows (`list: (b, core) => core(b) && isSection(b.under)`). */
+    checks?: Partial<Record<B['type'], LeafCheck>>;
+    /** What `coreAtomicValidator` takes. */
     pageId?: (id: string) => boolean;
     maxRows?: number;
 }
-export interface BlockModel<B extends {
-    id: string;
-    type: string;
-}> {
-    /** Every type, in the order `defaults` lists them. */
-    types: B['type'][];
-    /** Every type but the two containers: what may nest inside one. */
-    atomicTypes: B['type'][];
-    shape: BlockTreeShape<B>;
-    createBlock: (type: B['type']) => B;
-    duplicateBlock: (block: B) => B;
-    validateBlocks: (content: unknown) => content is B[];
-    blockIssues: (content: unknown) => BlockIssue[];
-}
 /**
- * A wiki's block model from its type set: the new-block factories and the leaf
- * checks are its own, and everything derived from them is this. Each wiki had
- * derived the same seven things by hand, and two kept a list of nestable types
- * that drifted from the types the write path accepted.
+ * Everything a wiki derives from its block set: the shape every tree walk
+ * takes, the types, a new block, a copy with fresh ids, and the validator
+ * with its issues. Three wikis had assembled these from the same seven
+ * primitives, each a hundred lines; a fourth kind of block now costs a default
+ * and a check.
  */
 export declare function defineBlocks<B extends {
     id: string;
     type: string;
-}>(opts: BlockModelOptions<B>): BlockModel<B>;
-export {};
+}>(opts: BlockModelOptions<B>): {
+    shape: import("./blocks.js").BlockTreeShape<B>;
+    types: B["type"][];
+    atomicTypes: B["type"][];
+    isAtomic: (type: string) => boolean;
+    createBlock: (type: B["type"]) => B;
+    duplicateBlock: (block: B) => B;
+    validateBlocks: (content: unknown) => content is B[];
+    validateBlock: (block: unknown) => boolean;
+    validateAtomicBlock: (block: unknown) => boolean;
+    blockIssues: (content: unknown) => BlockIssue[];
+};

package/dist/validation.js

@@ -242,29 +242,35 @@ export function duplicateBlockIds(block, newId = () => crypto.randomUUID()) {
     return { ...block, id: newId() };
 }
 /**
- * A wiki's block model from its type set: the new-block factories and the leaf
- * checks are its own, and everything derived from them is this. Each wiki had
- * derived the same seven things by hand, and two kept a list of nestable types
- * that drifted from the types the write path accepted.
+ * Everything a wiki derives from its block set: the shape every tree walk
+ * takes, the types, a new block, a copy with fresh ids, and the validator
+ * with its issues. Three wikis had assembled these from the same seven
+ * primitives, each a hundred lines; a fourth kind of block now costs a default
+ * and a check.
  */
 export function defineBlocks(opts) {
     const { defaults, checks = {}, pageId, maxRows } = opts;
     const types = Object.keys(defaults);
-    const atomicTypes = types.filter(t => t !== 'columns' && t !== 'infobox');
-    const core = coreAtomicValidator({ pageId, maxRows });
-    const own = checks;
-    const { validateBlocks, blockIssues } = createBlockValidator({
-        isKnownType: t => Object.hasOwn(defaults, t),
-        isAtomicType: t => atomicTypes.includes(t),
-        validateAtomic: b => (own[b.type] ?? core)(b, core),
+    const core = coreAtomicValidator({ ...(pageId ? { pageId } : {}), ...(maxRows ? { maxRows } : {}) });
+    const isAtomic = (type) => type !== 'columns' && type !== 'infobox';
+    const validator = createBlockValidator({
+        isKnownType: t => t in defaults,
+        isAtomicType: isAtomic,
+        validateAtomic: b => {
+            const own = checks[b.type];
+            return own ? own(b, core) : core(b);
+        },
     });
     return {
-        types,
-        atomicTypes,
         shape: coreBlockShape(),
-        createBlock: type => ({ id: crypto.randomUUID(), ...defaults[type]() }),
-        duplicateBlock: block => duplicateBlockIds(block),
-        validateBlocks: (content) => validateBlocks(content),
-        blockIssues,
+        types,
+        atomicTypes: types.filter(isAtomic),
+        isAtomic,
+        createBlock: (type) => ({ id: crypto.randomUUID(), ...defaults[type]() }),
+        duplicateBlock: (block) => duplicateBlockIds(block),
+        validateBlocks: (content) => validator.validateBlocks(content),
+        validateBlock: validator.validateBlock,
+        validateAtomicBlock: validator.validateAtomicBlock,
+        blockIssues: validator.blockIssues,
     };
 }

package/dist/well-known.d.ts

@@ -150,29 +150,32 @@ export declare function descriptorHandler(body: unknown, opts?: {
 /** The whole `<mcp-url>/server-card` route, projected from server.json. */
 export declare const serverCardHandler: (manifest: ServerManifest) => ((request: Request) => Response);
 export interface WellKnownDocs {
-    agentCard: unknown;
-    mcpManifest: unknown;
-    openapi: unknown;
-    /**
-     * The registry's key material, read from the environment by default. `null`
-     * serves no proof: a tenant of a host whose namespace is the host's own.
-     */
+    /** Served at both `agent.json` and `agent-card.json`. */
+    agentCard?: unknown;
+    /** `mcp.json`. */
+    mcpManifest?: unknown;
+    /** `openapi.json`. */
+    openapi?: unknown;
+    /** The registry proof, `mcp-registry-auth`: a key, or a handler; defaults to the environment's key. Pass null to serve none. */
     registryAuth?: {
         publicKey?: string;
         keyType?: string;
-    } | null;
+    } | (() => Response) | null;
 }
 /**
- * The `/.well-known/[doc]` route: the agent card at `agent.json` and
- * `agent-card.json` (A2A v0.3 renamed it; older clients ask for the first), the
- * MCP manifest at `mcp.json`, the OpenAPI spec at `openapi.json` and the
- * registry's domain proof at `mcp-registry-auth`. Every other name is a 404.
+ * The whole `/.well-known/` directory as one dynamic route,
+ * `src/app/.well-known/[doc]/route.ts`:
  *
- * Each app served these as five or six one-line routes re-exporting each other;
- * one dynamic segment holds them all, and a rewrite puts `/openapi.json` on it.
+ *   export const GET = wellKnownHandler({ agentCard: CARD, mcpManifest: MANIFEST, openapi: SPEC });
+ *
+ * Four repos carried five one-line route files each, twenty in all, and one
+ * of them answered a path the others 404'd. A document the app does not pass
+ * is a 404 here too, so an origin without an MCP server still serves its card.
  */
 export declare function wellKnownHandler(docs: WellKnownDocs): (request: Request, context: {
     params: Promise<{
         doc: string;
-    }>;
+    }> | {
+        doc: string;
+    };
 }) => Promise<Response>;

package/dist/well-known.js

@@ -1,6 +1,5 @@
 // well-known.ts — the descriptors an agent finds before it knows anything else
-// about an origin: the A2A Agent Card, the MCP manifest and the registry's
-// domain proof, and the one route that serves them.
+// about an origin: the A2A Agent Card and the MCP registry's domain proof.
 //
 // All three apps here serve both, and all three had written them out. The
 // registry-auth handler was identical bar a domain named in a comment; the
@@ -220,27 +219,30 @@ export function descriptorHandler(body, opts = {}) {
 /** The whole `<mcp-url>/server-card` route, projected from server.json. */
 export const serverCardHandler = (manifest) => descriptorHandler(serverCard(manifest, MCP_PROTOCOL_VERSIONS));
 /**
- * The `/.well-known/[doc]` route: the agent card at `agent.json` and
- * `agent-card.json` (A2A v0.3 renamed it; older clients ask for the first), the
- * MCP manifest at `mcp.json`, the OpenAPI spec at `openapi.json` and the
- * registry's domain proof at `mcp-registry-auth`. Every other name is a 404.
+ * The whole `/.well-known/` directory as one dynamic route,
+ * `src/app/.well-known/[doc]/route.ts`:
  *
- * Each app served these as five or six one-line routes re-exporting each other;
- * one dynamic segment holds them all, and a rewrite puts `/openapi.json` on it.
+ *   export const GET = wellKnownHandler({ agentCard: CARD, mcpManifest: MANIFEST, openapi: SPEC });
+ *
+ * Four repos carried five one-line route files each, twenty in all, and one
+ * of them answered a path the others 404'd. A document the app does not pass
+ * is a 404 here too, so an origin without an MCP server still serves its card.
  */
 export function wellKnownHandler(docs) {
-    const { registryAuth = {} } = docs;
-    const bodies = {
-        'agent.json': docs.agentCard,
-        'agent-card.json': docs.agentCard,
-        'mcp.json': docs.mcpManifest,
-        'openapi.json': docs.openapi,
+    const auth = docs.registryAuth;
+    const registry = auth === null ? null
+        : typeof auth === 'function' ? auth
+            : registryAuthHandler(auth?.publicKey ?? process.env.MCP_REGISTRY_PUBLIC_KEY, auth?.keyType ?? process.env.MCP_REGISTRY_KEY_TYPE);
+    const served = {
+        'agent.json': docs.agentCard === undefined ? undefined : descriptorHandler(docs.agentCard),
+        'agent-card.json': docs.agentCard === undefined ? undefined : descriptorHandler(docs.agentCard),
+        'mcp.json': docs.mcpManifest === undefined ? undefined : descriptorHandler(docs.mcpManifest),
+        'openapi.json': docs.openapi === undefined ? undefined : descriptorHandler(docs.openapi),
+        'mcp-registry-auth': registry ?? undefined,
     };
     return async (request, { params }) => {
         const { doc } = await params;
-        if (doc === 'mcp-registry-auth' && registryAuth) {
-            return registryAuthHandler(registryAuth.publicKey ?? process.env.MCP_REGISTRY_PUBLIC_KEY, registryAuth.keyType ?? process.env.MCP_REGISTRY_KEY_TYPE)();
-        }
-        return Object.hasOwn(bodies, doc) ? descriptorResponse(request, bodies[doc]) : new Response('Not found', { status: 404 });
+        const handler = Object.hasOwn(served, doc) ? served[doc] : undefined;
+        return handler ? handler(request) : new Response('Not found', { status: 404 });
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.86.1",
+  "version": "0.86.3",
   "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",