wiki-formant 0.59.0 → 0.61.0

package/dist/tree.js

@@ -0,0 +1,122 @@
+// tree.ts – a wiki's category tree, and what a URL path means against it.
+//
+// Three wikis declared their tree three ways: radix-wiki's `TAG_HIERARCHY`
+// (slug + children, keys and sort inherited down the trail), caper's
+// `WIKI_CATEGORIES` (each node naming its full `tagPath`, with a `categoryTrail`
+// walk of its own) and acuiq's `WIKI_SECTIONS` (one flat level). Each then
+// re-derived the same answers by hand: is this a real category, which metadata
+// keys apply here, which article is this page "part of a series on", what sort
+// does a listing default to, which paths are back office.
+//
+// The node holds what every wiki reads; anything only one wiki reads (an XRD
+// threshold, a band, an icon set) rides on the node as an extra field, and the
+// app folds it from `trail`. Pure: no data access, so a client component and
+// the server route read paths through the same parser.
+const segmentsOf = (tagPath) => typeof tagPath === 'string' ? tagPath.split('/').filter(Boolean) : tagPath.filter(Boolean);
+export function createTree(nodes, opts = {}) {
+    const globalKeys = [...(opts.globalKeys ?? [])];
+    const cache = new Map();
+    function resolve(tagPath) {
+        const segments = segmentsOf(tagPath);
+        const key = segments.join('/');
+        const hit = cache.get(key);
+        if (hit)
+            return hit;
+        const trail = [];
+        const metadataKeys = [];
+        let level = nodes;
+        let sort = 'title';
+        let mainArticle;
+        let hidden = false;
+        for (const segment of segments) {
+            const node = level.find(n => n.slug === segment);
+            if (!node) {
+                const missing = { node: null, trail: [], valid: false, hidden: false, sort: 'title', metadataKeys: [] };
+                cache.set(key, missing);
+                return missing;
+            }
+            trail.push(node);
+            if (node.metadataKeys)
+                metadataKeys.push(...node.metadataKeys);
+            if (node.sort)
+                sort = node.sort;
+            if (node.mainArticle)
+                mainArticle = node.mainArticle;
+            hidden ||= !!node.hidden;
+            level = node.children ?? [];
+        }
+        metadataKeys.push(...globalKeys);
+        const resolved = { node: trail.at(-1) ?? null, trail, valid: trail.length > 0, hidden, sort, mainArticle, metadataKeys };
+        cache.set(key, resolved);
+        return resolved;
+    }
+    /** Every path in the tree, depth first, parents before children. */
+    function paths(level = nodes, parent = '', inherited = false, depth = 0) {
+        return level.flatMap(node => {
+            const path = parent ? `${parent}/${node.slug}` : node.slug;
+            const hidden = inherited || !!node.hidden;
+            return [{ path, node: node, hidden, depth }, ...paths(node.children ?? [], path, hidden, depth + 1)];
+        });
+    }
+    const all = paths();
+    return {
+        nodes,
+        resolve,
+        paths: () => all,
+        /** Back-office paths, which a listing leaves out unless it names one. Pass to `wikiStore({ hidden })`. */
+        hiddenPaths: all.filter(p => p.hidden && p.path).map(p => p.path),
+        isValid: (tagPath) => resolve(tagPath).valid,
+        node: (tagPath) => resolve(tagPath).node,
+        metadataKeys: (tagPath) => resolve(tagPath).metadataKeys,
+        /** A category's name, or its last segment unslugged when the tree does not know it. */
+        label: (tagPath) => resolve(tagPath).node?.name ?? (segmentsOf(tagPath).at(-1) ?? '').replace(/-/g, ' '),
+        /**
+         * One crumb per segment, so the trail can never be shorter than the URL. A
+         * segment the tree knows is a link to its category; one it does not is text.
+         */
+        crumbs: (tagPath) => {
+            const segments = segmentsOf(tagPath);
+            return segments.map((segment, i) => {
+                const path = segments.slice(0, i + 1).join('/');
+                const node = resolve(path).node;
+                return { path, label: node?.name ?? segment.replace(/-/g, ' '), linked: !!node };
+            });
+        },
+    };
+}
+/** The views a page or a category has beside itself, each a final path segment. */
+export const WIKI_MODES = ['edit', 'history'];
+/**
+ * What a path means: the home page, a category (its hub article is the empty
+ * slug), a page, or nothing, each optionally in one of `modes`. A path that is
+ * itself a category wins over a mode suffix, so a category named `history` is
+ * still reachable; `/<category>/edit` edits the category's hub.
+ *
+ * Static routes are the app's: check them before calling this.
+ */
+export function parseWikiPath(tree, segments = [], { modes = WIKI_MODES } = {}) {
+    const parts = segments.filter(Boolean);
+    const last = parts.at(-1);
+    const mode = last && modes.includes(last) && !tree.isValid(parts) ? last : null;
+    const path = mode ? parts.slice(0, -1) : parts;
+    const invalid = { type: 'invalid', tagPath: '', slug: '', mode: null };
+    if (!path.length)
+        return { type: 'home', tagPath: '', slug: '', mode };
+    if (tree.isValid(path))
+        return { type: 'category', tagPath: path.join('/'), slug: '', mode };
+    if (path.length < 2 || !tree.isValid(path.slice(0, -1)))
+        return invalid;
+    return { type: 'page', tagPath: path.slice(0, -1).join('/'), slug: path.at(-1), mode };
+}
+/**
+ * A slug no page in `tagPath` can hold, because `parseWikiPath` reads that URL
+ * as something else: a mode, or a child category. Creating a page treats it as
+ * taken.
+ */
+export function isReservedSlug(tree, tagPath, slug, modes = WIKI_MODES) {
+    return modes.includes(slug) || tree.isValid([...segmentsOf(tagPath), slug]);
+}
+/** A page's path: the category for its hub, `/` for the home page. */
+export function wikiPath(tagPath, slug) {
+    return `/${[tagPath, slug].filter(Boolean).join('/')}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",
@@ -117,6 +117,16 @@
       "import": "./dist/search.js",
       "default": "./dist/search.js"
     },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js",
+      "default": "./dist/store.js"
+    },
+    "./tree": {
+      "types": "./dist/tree.d.ts",
+      "import": "./dist/tree.js",
+      "default": "./dist/tree.js"
+    },
     "./feed": {
       "types": "./dist/feed.d.ts",
       "import": "./dist/feed.js",
@@ -296,6 +306,7 @@
     "sanitize-html": "^2.17.7"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.3.9",
     "@radixdlt/rola": "^2.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
@@ -308,12 +319,12 @@
     "typescript": "^5.9.0"
   },
   "peerDependencies": {
+    "@radixdlt/rola": ">=2",
+    "@vercel/blob": ">=2",
+    "jose": ">=6",
     "pg": ">=8",
     "react": ">=18",
-    "jose": ">=6",
-    "@radixdlt/rola": ">=2",
-    "sharp": ">=0.33",
-    "@vercel/blob": ">=2"
+    "sharp": ">=0.33"
   },
   "peerDependenciesMeta": {
     "react": {

package/prisma/wiki.prisma

@@ -0,0 +1,62 @@
+// Shipped by wiki-formant (`npx prisma-models`). Edit it there, not here:
+// `prisma-models --check` fails on a copy that has drifted.
+//
+// A wiki's pages and their revisions, read and written by wiki-formant/store.
+// Its SQL names these tables and columns as written, so they carry no @@map.
+// `siteId` is "" in an app that serves one wiki; a multi-tenant app keys every
+// row to its site, and caper keys a DAO's own layer to the DAO.
+//
+// A page lives at `tagPath` + `slug`. The empty slug is the category's own hub
+// article, and `''/''` the home page. Everything a page says beyond its blocks
+// and title is `metadata`: facet keys, an excerpt, a banner, a subtitle. Which
+// keys a listing may carry is the tree's answer, not the column's.
+//
+// Ids and timestamps default in the database, so the store's raw SQL and a
+// Prisma client write the same rows. `authorId` is the app's own user key, as
+// text; it has no relation because no two apps key their users alike.
+
+model WikiPage {
+  id             String         @id @default(dbgenerated("(gen_random_uuid())::text"))
+  siteId         String         @default("")
+  tagPath        String         @default("")
+  slug           String
+  title          String
+  content        Json           @default("[]")
+  metadata       Json           @default("{}")
+  version        String         @default("1.0.0")
+  authorId       String?
+  lastVerifiedAt DateTime?      @db.Timestamptz(3)
+  createdAt      DateTime       @default(now()) @db.Timestamptz(3)
+  updatedAt      DateTime       @default(now()) @db.Timestamptz(3)
+  // Title at weight A, block prose at B, GENERATED ALWAYS ... STORED by
+  // `npx fts-ddl '"WikiPage"'`. Declared only so `db push` leaves it alone:
+  // push must never create it, since Prisma would write a plain column that
+  // stays empty. Read only through raw SQL.
+  searchTsv      Unsupported("tsvector")? @map("search_tsv")
+  revisions      WikiRevision[]
+
+  @@unique([siteId, tagPath, slug])
+  @@index([siteId, tagPath, updatedAt])
+  @@index([siteId, updatedAt])
+  // Declared for the same reason: undeclared, push drops it.
+  @@index([searchTsv], type: Gin, map: "WikiPage_search_tsv_idx")
+}
+
+// One row per saved version, newest last. A revision holds the whole page as
+// it was saved; what changed is diffed from consecutive rows when it is read,
+// so a script's revision and the editor's carry the same history.
+model WikiRevision {
+  id         String   @id @default(dbgenerated("(gen_random_uuid())::text"))
+  pageId     String
+  title      String
+  content    Json
+  version    String
+  changeType String
+  message    String?
+  authorId   String?
+  createdAt  DateTime @default(now()) @db.Timestamptz(3)
+  page       WikiPage @relation(fields: [pageId], references: [id], onDelete: Cascade)
+
+  @@index([pageId, createdAt])
+  @@index([authorId, createdAt])
+}

package/prisma/wiki.sql

@@ -0,0 +1,68 @@
+-- Shipped by wiki-formant. The tables prisma/wiki.prisma declares, as
+-- `prisma migrate diff` writes them, for a migration that moves an existing
+-- wiki's rows in: create these, INSERT ... SELECT the old rows, retarget any
+-- foreign keys, drop the old tables, then build search_tsv with fts-ddl.
+
+
+
+-- CreateTable
+CREATE TABLE "WikiPage" (
+    "id" TEXT NOT NULL DEFAULT (gen_random_uuid())::text,
+    "siteId" TEXT NOT NULL DEFAULT '',
+    "tagPath" TEXT NOT NULL DEFAULT '',
+    "slug" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "content" JSONB NOT NULL DEFAULT '[]',
+    "metadata" JSONB NOT NULL DEFAULT '{}',
+    "version" TEXT NOT NULL DEFAULT '1.0.0',
+    "authorId" TEXT,
+    "lastVerifiedAt" TIMESTAMPTZ(3),
+    "createdAt" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "WikiPage_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "WikiRevision" (
+    "id" TEXT NOT NULL DEFAULT (gen_random_uuid())::text,
+    "pageId" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "content" JSONB NOT NULL,
+    "version" TEXT NOT NULL,
+    "changeType" TEXT NOT NULL,
+    "message" TEXT,
+    "authorId" TEXT,
+    "createdAt" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "WikiRevision_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "WikiPage_siteId_tagPath_updatedAt_idx" ON "WikiPage"("siteId", "tagPath", "updatedAt");
+
+-- CreateIndex
+CREATE INDEX "WikiPage_siteId_updatedAt_idx" ON "WikiPage"("siteId", "updatedAt");
+
+-- CreateIndex
+
+-- CreateIndex
+CREATE UNIQUE INDEX "WikiPage_siteId_tagPath_slug_key" ON "WikiPage"("siteId", "tagPath", "slug");
+
+-- CreateIndex
+CREATE INDEX "WikiRevision_pageId_createdAt_idx" ON "WikiRevision"("pageId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "WikiRevision_authorId_createdAt_idx" ON "WikiRevision"("authorId", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "WikiRevision" ADD CONSTRAINT "WikiRevision_pageId_fkey" FOREIGN KEY ("pageId") REFERENCES "WikiPage"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+
+-- STRUCTURE S7: the Data API gets nothing. Prisma connects as postgres, which
+-- bypasses RLS; with no policies, anon and authenticated read nothing.
+ALTER TABLE "WikiPage" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "WikiRevision" ENABLE ROW LEVEL SECURITY;
+
+-- The full-text column and its index: `npx fts-ddl '"WikiPage"'` after the
+-- rows are in, never a plain tsvector column (it would stay empty).