@kernhq/module-quire 0.2.0

package/migrations/meta/0000_snapshot.json

@@ -0,0 +1,358 @@
+{
+  "id": "73e5ffbb-8a14-4b41-bdfd-776e51bec7d7",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "mod_quire.pages": {
+      "name": "pages",
+      "schema": "mod_quire",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "space_id": {
+          "name": "space_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parent_id": {
+          "name": "parent_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "position": {
+          "name": "position",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'page'"
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_url": {
+          "name": "cover_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_version_id": {
+          "name": "published_version_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "has_unpublished_changes": {
+          "name": "has_unpublished_changes",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_by": {
+          "name": "updated_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "pages_ws_space_idx": {
+          "name": "pages_ws_space_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "space_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "pages_ws_parent_idx": {
+          "name": "pages_ws_parent_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "pages_ws_updated_idx": {
+          "name": "pages_ws_updated_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "mod_quire.spaces": {
+      "name": "spaces",
+      "schema": "mod_quire",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "visibility": {
+          "name": "visibility",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'open'"
+        },
+        "homepage_id": {
+          "name": "homepage_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "spaces_ws_key_uq": {
+          "name": "spaces_ws_key_uq",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "spaces_ws_idx": {
+          "name": "spaces_ws_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {
+    "mod_quire": "mod_quire"
+  },
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/migrations/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1787566823449,
+      "tag": "0000_init",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1787566824449,
+      "tag": "0001_rls",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@kernhq/module-quire",
+  "version": "0.2.0",
+  "description": "Kern Quire: collaborative documents, spaces and page trees",
+  "homepage": "https://kernaio.com",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KernAIO/modules",
+    "directory": "packages/quire"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "src/client",
+    "src/contract"
+  ],
+  "exports": {
+    "./contract": {
+      "types": "./dist/contract/index.d.ts",
+      "import": "./dist/contract/index.js",
+      "default": "./dist/contract/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "svelte": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./migrations": "./migrations",
+    "./client/*": {
+      "types": "./src/client/*",
+      "svelte": "./src/client/*",
+      "default": "./src/client/*"
+    }
+  },
+  "dependencies": {
+    "@kernhq/contracts": "^0.5.0",
+    "@kernhq/kernel": "^0.6.0",
+    "@kernhq/sdk": "^0.1.0",
+    "@orpc/contract": "^1.15.0",
+    "@orpc/server": "^1.15.0",
+    "drizzle-orm": "^0.45.0",
+    "zod": "^4.1.0"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "svelte": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@kernhq/tsconfig": "^0.1.0",
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.0",
+    "drizzle-kit": "^0.31.0",
+    "pg": "^8.16.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "test": "vitest run",
+    "db:generate": "drizzle-kit generate"
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,67 @@
+import { createModuleClient, type KernClientOptions } from '@kernhq/sdk'
+import type { ContractRouterClient } from '@orpc/contract'
+import type { PageNode, QuireContract } from '../contract/index.js'
+
+/**
+ * The client half.
+ *
+ * Published as **source**, not compiled: the consumer builds the TypeScript and Svelte with its own
+ * toolchain, which is what lets `$state` in a module store stay reactive inside the app. Two
+ * consequences worth knowing before you edit anything here — nothing in this package compiles it,
+ * so `pnpm build` passes over a syntax error and only the app finds it; and `files` in package.json
+ * must cover every directory this entry reaches, contract source included.
+ *
+ * What lives here: the typed API client, and any logic that is about this module but not about a
+ * screen (formatting, grouping, parsing). What does not: the `defineClientModule` manifest and the
+ * Svelte components, which live in the app so their labels can go through its message catalogue.
+ * `pnpm new-module` generates both halves.
+ */
+export type QuireApi = ContractRouterClient<QuireContract>
+
+export function createQuireClient(opts: KernClientOptions): QuireApi {
+  return createModuleClient<QuireApi>(opts, 'quire')
+}
+
+export {
+  MODULE_ID,
+  type Page,
+  type PageKind,
+  type PageNode,
+  quirePermissions,
+  type Space,
+  type SpaceVisibility,
+} from '../contract/index.js'
+export * from './rank.js'
+
+/** The permission keys, so the app gates on a constant rather than a string it retyped. */
+export const QUIRE_PERMISSIONS = {
+  spaceView: 'quire.space.view',
+  spaceManage: 'quire.space.manage',
+  pageView: 'quire.page.view',
+  pageCreate: 'quire.page.create',
+  pageEdit: 'quire.page.edit',
+  pageDelete: 'quire.page.delete',
+} as const
+
+/**
+ * Build the sidebar tree from the flat, position-ordered list `pages.tree` returns.
+ *
+ * Isomorphic on purpose: the app draws it and the published-site renderer will need the same shape,
+ * and neither should re-derive it. Rows whose parent is missing — because it was archived and this
+ * caller asked for the live tree — are lifted to the top rather than dropped, so a page is never
+ * invisible because of where it happens to sit.
+ */
+export interface PageTreeNode extends PageNode {
+  children: PageTreeNode[]
+}
+
+export function buildPageTree(nodes: readonly PageNode[]): PageTreeNode[] {
+  const byId = new Map<string, PageTreeNode>(nodes.map((n) => [n.id, { ...n, children: [] }]))
+  const roots: PageTreeNode[] = []
+  for (const node of byId.values()) {
+    const parent = node.parentId ? byId.get(node.parentId) : undefined
+    if (parent) parent.children.push(node)
+    else roots.push(node)
+  }
+  return roots
+}

package/src/client/rank.test.ts

@@ -0,0 +1,92 @@
+/**
+ * The ordering invariants a page tree depends on.
+ *
+ * This algorithm is duplicated from the tracker on purpose — modules do not import one another — so
+ * it carries its own test rather than trusting that the original still holds.
+ */
+import { describe, expect, it } from 'vitest'
+import { initialRank, isValidRank, rankBetween, rankSequence } from './rank.js'
+
+describe('rankBetween', () => {
+  it('lands strictly between its neighbours', () => {
+    const a = initialRank()
+    const c = rankBetween(a, null)
+    const b = rankBetween(a, c)
+    expect(a < b).toBe(true)
+    expect(b < c).toBe(true)
+  })
+
+  it('opens either end', () => {
+    const first = initialRank()
+    expect(rankBetween(null, first) < first).toBe(true)
+    expect(rankBetween(first, null) > first).toBe(true)
+  })
+
+  it('refuses neighbours that are the wrong way round', () => {
+    const a = initialRank()
+    const b = rankBetween(a, null)
+    expect(() => rankBetween(b, a)).toThrow()
+  })
+
+  it('keeps finding room, however many times the same gap is split', () => {
+    // The failure this guards against is a key that runs out of precision and starts colliding, so
+    // two pages dropped in the same place end up in an order nobody chose.
+    let lo = initialRank()
+    const hi = rankBetween(lo, null)
+    const seen = new Set<string>([lo, hi])
+    for (let i = 0; i < 200; i++) {
+      const mid = rankBetween(lo, hi)
+      expect(lo < mid, `${lo} < ${mid} failed at split ${i}`).toBe(true)
+      expect(mid < hi, `${mid} < ${hi} failed at split ${i}`).toBe(true)
+      expect(seen.has(mid), `collision at split ${i}`).toBe(false)
+      expect(isValidRank(mid)).toBe(true)
+      seen.add(mid)
+      lo = mid
+    }
+  })
+
+  it('never mints a key ending in the lowest digit, so there is always room below', () => {
+    let prev: string | null = null
+    for (let i = 0; i < 50; i++) {
+      const next: string = rankBetween(prev, null)
+      expect(isValidRank(next)).toBe(true)
+      prev = next
+    }
+  })
+})
+
+describe('inserting at the front, over and over', () => {
+  it('keeps finding room instead of looping until the process dies', () => {
+    // The regression this guards: an absent lower bound was treated as "below digit 0", so the
+    // fifth insertion at the top of a list minted '0', and the sixth searched for something below
+    // it for ever — growing a string until the heap gave out. It took five pages created at the top
+    // of one space to hit it.
+    let first = initialRank()
+    const seen = new Set<string>([first])
+    for (let i = 0; i < 200; i++) {
+      const next = rankBetween(null, first)
+      expect(next < first, `${next} < ${first} failed at insertion ${i}`).toBe(true)
+      expect(isValidRank(next), `${next} is not a valid key at insertion ${i}`).toBe(true)
+      expect(seen.has(next), `collision at insertion ${i}`).toBe(false)
+      seen.add(next)
+      first = next
+    }
+  })
+
+  it('never mints a key with no room below it', () => {
+    let first = initialRank()
+    for (let i = 0; i < 50; i++) {
+      first = rankBetween(null, first)
+      expect(first.endsWith('0'), `${first} ends in the lowest digit`).toBe(false)
+    }
+  })
+})
+
+describe('rankSequence', () => {
+  it('produces keys that already sort into the order they were asked for', () => {
+    const keys = rankSequence(25)
+    expect(keys).toHaveLength(25)
+    expect([...keys].sort()).toEqual(keys)
+    expect(new Set(keys).size).toBe(25)
+  })
+})