@kernhq/module-quire 0.2.0

package/src/client/rank.ts

@@ -0,0 +1,100 @@
+/**
+ * Fractional indexing for `Page.position`.
+ *
+ * Copied from the tracker's `rank.ts` rather than imported: modules do not depend on one another,
+ * and a pure algorithm is the one thing worth duplicating. Keep them in step if either changes.
+ *
+ * A page tree must survive concurrent edits: two people dragging different pages at the same time
+ * should not have to renumber anything. Each page therefore carries a short string key, and moving
+ * one between two siblings only mints a new key strictly between its neighbours — no other row is
+ * touched, and the result sorts with a plain string comparison.
+ *
+ * The alphabet is ordered by code point (digits, uppercase, lowercase) so lexicographic order and
+ * numeric order agree, which is what `ORDER BY position` in Postgres relies on.
+ */
+
+const DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+const BASE = DIGITS.length
+
+const indexOfDigit = (ch: string) => {
+  const i = DIGITS.indexOf(ch)
+  if (i < 0) throw new Error(`invalid rank character: ${JSON.stringify(ch)}`)
+  return i
+}
+
+/** True when `rank` only uses the rank alphabet and has no trailing zero (the canonical form). */
+export function isValidRank(rank: string): boolean {
+  if (rank.length === 0) return false
+  for (const ch of rank) if (!DIGITS.includes(ch)) return false
+  return !rank.endsWith(DIGITS[0] as string)
+}
+
+/**
+ * A key strictly between `before` and `after`. Pass `null` for an open end: `rankBetween(null, first)`
+ * puts an item at the top of the list, `rankBetween(last, null)` at the bottom.
+ */
+export function rankBetween(before: string | null, after: string | null): string {
+  const lo = before ?? ''
+  const hi = after ?? ''
+  if (lo && hi && lo >= hi) {
+    throw new Error(`rankBetween expects before < after, got ${JSON.stringify(lo)} >= ${JSON.stringify(hi)}`)
+  }
+
+  let prefix = ''
+  // once the digit we keep is strictly below the upper bound's digit, the rest of `hi` cannot
+  // constrain us any more and we are free to use the whole alphabet
+  let free = hi === ''
+
+  for (let i = 0; ; i++) {
+    const da = i < lo.length ? indexOfDigit(lo[i] as string) : -1
+    const db = free ? BASE : i < hi.length ? indexOfDigit(hi[i] as string) : 0
+    /**
+     * An absent lower bound is digit 0, not "below 0".
+     *
+     * Digit 0 can never be the last digit of a key: nothing sorts strictly between `''` and `'0'`,
+     * so a key ending in 0 leaves no room to insert in front of it. Treating the absent bound as -1
+     * makes the midpoint of (nothing, '2') come out as '0', and the next insertion at the front then
+     * looks for a key below '0', finds none, and appends a digit for ever — a loop inside a request
+     * handler that allocates until the process dies. Reaching it takes five insertions at the top of
+     * the same list.
+     */
+    const low = da >= 0 ? da : 0
+    if (db - low > 1) return prefix + DIGITS[Math.floor((low + db) / 2)]
+    prefix += DIGITS[low]
+    if (!free && low < db) free = true
+  }
+}
+
+/** First rank in an empty list. */
+export function initialRank(): string {
+  return rankBetween(null, null)
+}
+
+/**
+ * `count` evenly spread ranks, for seeding a list. Cheaper and tidier than calling `rankBetween`
+ * repeatedly, which would bias every new key towards the end.
+ */
+export function rankSequence(count: number): string[] {
+  const out: string[] = []
+  let prev: string | null = null
+  for (let i = 0; i < count; i++) {
+    prev = rankBetween(prev, null)
+    out.push(prev)
+  }
+  return out
+}
+
+/** Ascending comparator for anything carrying a `rank`. */
+export function byRank(a: { rank: string }, b: { rank: string }): number {
+  return a.rank < b.rank ? -1 : a.rank > b.rank ? 1 : 0
+}
+
+/**
+ * The rank an item needs to land at `targetIndex` of `ordered` (the list it is being dropped into,
+ * already excluding the dragged item).
+ */
+export function rankForIndex(ordered: Array<{ rank: string }>, targetIndex: number): string {
+  const before = targetIndex > 0 ? (ordered[targetIndex - 1]?.rank ?? null) : null
+  const after = targetIndex < ordered.length ? (ordered[targetIndex]?.rank ?? null) : null
+  return rankBetween(before, after)
+}

package/src/contract/capabilities.ts

@@ -0,0 +1,36 @@
+import { defineCapabilities } from '@kernhq/contracts'
+
+/**
+ * Sub-features a workspace can switch off inside this module.
+ *
+ * Only the foundation exists today, and it is `required` — always on, never offered as a switch — so
+ * that the optional ones arriving later have something to depend on. A capability is not a second
+ * permission system: a permission asks whether this *person* may do something, a capability asks
+ * whether this *workspace* has the feature at all, and a procedure behind a disabled one answers
+ * `notFound` rather than `forbidden`, because a surface the workspace never enabled is not being
+ * withheld — it is not there.
+ *
+ * Planned, each of which is a real "different customers want different amounts of this": databases,
+ * public publishing, blogs and page analytics. They are declared when the feature lands, not before:
+ * a switch that does nothing is worse than no switch.
+ */
+export const quireCapabilities = defineCapabilities([
+  {
+    id: 'pages',
+    label: 'Spaces and pages',
+    description: 'The page tree itself',
+    required: true,
+  },
+])
+
+/**
+ * Which procedures belong to which capability, as data.
+ *
+ * Declared rather than inferred, because a missing `requiresCapability` is invisible: the procedure
+ * type-checks, the tests pass, and the only symptom is that a workspace which switched the feature
+ * off can still call it. `module.test.ts` reads this and fails when a procedure named here is not
+ * carrying the extra middleware.
+ *
+ * Everything Quire offers today belongs to the module as a whole, so this is empty.
+ */
+export const quireCapabilityProcedures: Record<string, readonly string[]> = {}

package/src/contract/events.ts

@@ -0,0 +1,22 @@
+import { defineEvent, Id, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+
+const page = z.object({ pageId: Id, spaceId: Id, workspaceId: WorkspaceId })
+
+/** `<module>.<entity>.<action>`. Anything that emits one declares it here. */
+export const quireEvents = {
+  spaceCreated: defineEvent('quire.space.created', z.object({ spaceId: Id, workspaceId: WorkspaceId })),
+  spaceUpdated: defineEvent('quire.space.updated', z.object({ spaceId: Id, workspaceId: WorkspaceId })),
+  spaceArchived: defineEvent(
+    'quire.space.archived',
+    z.object({ spaceId: Id, workspaceId: WorkspaceId, archived: z.boolean() }),
+  ),
+  pageCreated: defineEvent('quire.page.created', page),
+  pageUpdated: defineEvent('quire.page.updated', page),
+  pageMoved: defineEvent('quire.page.moved', page.extend({ parentId: Id.nullable() })),
+  pageArchived: defineEvent('quire.page.archived', page.extend({ archived: z.boolean() })),
+  pageTrashed: defineEvent('quire.page.trashed', page.extend({ count: z.number().int().nonnegative() })),
+  pageRestored: defineEvent('quire.page.restored', page),
+  /** The page and its descendants are gone; anything holding a reference should drop it. */
+  pageDeleted: defineEvent('quire.page.deleted', page.extend({ pageIds: z.array(Id) })),
+} as const

package/src/contract/index.ts

@@ -0,0 +1,5 @@
+export * from './capabilities.js'
+export * from './events.js'
+export * from './models.js'
+export * from './permissions.js'
+export * from './router.js'

package/src/contract/models.ts

@@ -0,0 +1,93 @@
+import { Id, Timestamp, UserId, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+
+/** Lowercase, 2-32 characters. Names the API prefix, the Postgres schema `mod_quire` and every event. */
+export const MODULE_ID = 'quire'
+
+/**
+ * How a space decides who may see it before any binding is consulted.
+ *
+ * `open` — every member of the workspace may read it.
+ * `restricted` — members may find it and see its name, and need a binding to read a page.
+ * `private` — only people with a binding know it exists at all.
+ */
+export const SpaceVisibility = z.enum(['open', 'restricted', 'private'])
+export type SpaceVisibility = z.infer<typeof SpaceVisibility>
+
+export const Space = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  /** unique per workspace; it is what appears in the URL */
+  key: z
+    .string()
+    .min(2)
+    .max(48)
+    .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, 'lowercase letters, digits and dashes'),
+  name: z.string().min(1).max(120),
+  description: z.string().max(2000),
+  /** a Lucide icon name, or an emoji */
+  icon: z.string().max(64).nullable(),
+  visibility: SpaceVisibility,
+  /** the page shown when somebody opens the space; null until one is set */
+  homepageId: Id.nullable(),
+  createdBy: UserId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+  archivedAt: Timestamp.nullable(),
+})
+export type Space = z.infer<typeof Space>
+
+/**
+ * What a page *is*, which decides what a reader sees.
+ *
+ * `page` — has a published version and a draft. Everyone editing shares one live document; a reader
+ * without edit rights, and every public URL, is served the last published version instead. This is
+ * what a documentation site is made of.
+ * `live` — always live, like a shared note. There is no draft and no unpublished-changes state;
+ * versions still accumulate so history and restore work the same way.
+ * `database` — the page *is* a database. Its own body is the description above the view.
+ */
+export const PageKind = z.enum(['page', 'live', 'database'])
+export type PageKind = z.infer<typeof PageKind>
+
+export const Page = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  spaceId: Id,
+  parentId: Id.nullable(),
+  /**
+   * A fractional index, not an integer. Moving one page between two others must not renumber its
+   * siblings: two people reordering at once would then write different numbers for the same rows.
+   */
+  position: z.string().min(1).max(256),
+  kind: PageKind,
+  title: z.string().max(300),
+  icon: z.string().max(64).nullable(),
+  coverUrl: z.string().max(2048).nullable(),
+  /** the version a reader without edit rights sees; null while a `page` has never been published */
+  publishedVersionId: Id.nullable(),
+  /** whether the live document has changed since `publishedVersionId` was written */
+  hasUnpublishedChanges: z.boolean(),
+  createdBy: UserId.nullable(),
+  updatedBy: UserId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+  archivedAt: Timestamp.nullable(),
+  deletedAt: Timestamp.nullable(),
+})
+export type Page = z.infer<typeof Page>
+
+/** A page in the sidebar tree: enough to draw a row, and nothing that costs a join. */
+export const PageNode = z.object({
+  id: Id,
+  parentId: Id.nullable(),
+  position: z.string(),
+  kind: PageKind,
+  title: z.string(),
+  icon: z.string().nullable(),
+  hasChildren: z.boolean(),
+  archivedAt: Timestamp.nullable(),
+})
+export type PageNode = z.infer<typeof PageNode>
+
+export const Ok = z.object({ ok: z.literal(true) })

package/src/contract/permissions.ts

@@ -0,0 +1,59 @@
+import { definePermissions } from '@kernhq/contracts'
+
+/**
+ * `<module>.<resource>.<action>`, each at the narrowest scope that works.
+ *
+ * Almost everything here is bound at **space** scope rather than workspace scope. That scope kind has
+ * existed in the permission model since before there was anything to use it, and this is what it was
+ * for: "everyone may read the Handbook, the design team may write it, and the contractor may read one
+ * page of it". Bindings resolve nearest-first, so a binding on a page beats one on its space, which
+ * beats one on the workspace — and a deny beats an allow at the same level.
+ */
+export const quirePermissions = definePermissions([
+  {
+    key: 'quire.space.view',
+    label: 'See a space',
+    description: 'Find the space and read its name, whatever its pages allow',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member', 'guest'],
+    dangerous: false,
+  },
+  {
+    key: 'quire.space.manage',
+    label: 'Create and configure spaces',
+    description: 'Rename, set the home page, change who may read it, archive it',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'quire.page.view',
+    label: 'Read pages',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member', 'guest'],
+    dangerous: false,
+  },
+  {
+    key: 'quire.page.create',
+    label: 'Create pages',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    key: 'quire.page.edit',
+    label: 'Edit pages',
+    description: 'Write in a page, rename it, and move it in the tree',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    key: 'quire.page.delete',
+    label: 'Delete pages permanently',
+    description: 'Empty the trash. A purged page and its history cannot be recovered.',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: true,
+  },
+])

package/src/contract/router.ts

@@ -0,0 +1,121 @@
+import { baseContract, Id, PageInput, page, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+import { Ok, Page, PageKind, PageNode, Space, SpaceVisibility } from './models.js'
+
+const ws = z.object({ workspaceId: WorkspaceId })
+const t = (...tags: string[]) => ({ tags })
+
+export const quireContract = {
+  spaces: {
+    list: baseContract
+      .route({ method: 'GET', path: '/spaces', ...t('spaces') })
+      .input(ws.extend({ includeArchived: z.boolean().default(false) }))
+      .output(z.array(Space)),
+    get: baseContract
+      .route({ method: 'GET', path: '/spaces/{spaceId}', ...t('spaces') })
+      .input(ws.extend({ spaceId: Id }))
+      .output(Space),
+    create: baseContract
+      .route({ method: 'POST', path: '/spaces', ...t('spaces') })
+      .input(
+        ws.extend({
+          key: Space.shape.key,
+          name: Space.shape.name,
+          description: z.string().max(2000).default(''),
+          icon: z.string().max(64).nullable().default(null),
+          visibility: SpaceVisibility.default('open'),
+        }),
+      )
+      .output(Space),
+    update: baseContract
+      .route({ method: 'PATCH', path: '/spaces/{spaceId}', ...t('spaces') })
+      .input(
+        ws.extend({
+          spaceId: Id,
+          name: Space.shape.name.optional(),
+          description: z.string().max(2000).optional(),
+          icon: z.string().max(64).nullable().optional(),
+          visibility: SpaceVisibility.optional(),
+          homepageId: Id.nullable().optional(),
+        }),
+      )
+      .output(Space),
+    archive: baseContract
+      .route({ method: 'POST', path: '/spaces/{spaceId}/archive', ...t('spaces') })
+      .input(ws.extend({ spaceId: Id, archived: z.boolean().default(true) }))
+      .output(Space),
+  },
+
+  pages: {
+    /**
+     * The whole tree of one space in one call. A wiki sidebar shows every level at once, and asking
+     * per level turns opening a space into a request per expanded node.
+     */
+    tree: baseContract
+      .route({ method: 'GET', path: '/spaces/{spaceId}/tree', ...t('pages') })
+      .input(ws.extend({ spaceId: Id, includeArchived: z.boolean().default(false) }))
+      .output(z.array(PageNode)),
+    get: baseContract
+      .route({ method: 'GET', path: '/pages/{pageId}', ...t('pages') })
+      .input(ws.extend({ pageId: Id }))
+      .output(Page),
+    /** Everything in the space's trash, newest first. */
+    trash: baseContract
+      .route({ method: 'GET', path: '/spaces/{spaceId}/trash', ...t('pages') })
+      .input(ws.extend({ spaceId: Id }).extend(PageInput.shape))
+      .output(page(Page)),
+    create: baseContract
+      .route({ method: 'POST', path: '/pages', ...t('pages') })
+      .input(
+        ws.extend({
+          spaceId: Id,
+          parentId: Id.nullable().default(null),
+          title: z.string().max(300).default(''),
+          kind: PageKind.default('page'),
+          icon: z.string().max(64).nullable().default(null),
+          /** place it after this sibling; null means first */
+          afterId: Id.nullable().default(null),
+        }),
+      )
+      .output(Page),
+    update: baseContract
+      .route({ method: 'PATCH', path: '/pages/{pageId}', ...t('pages') })
+      .input(
+        ws.extend({
+          pageId: Id,
+          title: z.string().max(300).optional(),
+          icon: z.string().max(64).nullable().optional(),
+          coverUrl: z.string().max(2048).nullable().optional(),
+          kind: PageKind.optional(),
+        }),
+      )
+      .output(Page),
+    /** Reparent, reorder, or both. `afterId` is the sibling to land behind; null means first. */
+    move: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/move', ...t('pages') })
+      .input(ws.extend({ pageId: Id, parentId: Id.nullable(), afterId: Id.nullable().default(null) }))
+      .output(Page),
+    /** Out of the tree but not gone: still searchable, still restorable, no longer in the sidebar. */
+    archive: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/archive', ...t('pages') })
+      .input(ws.extend({ pageId: Id, archived: z.boolean().default(true) }))
+      .output(Page),
+    /** Into the trash, with every descendant. Reversible until `purge`. */
+    trashPage: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/trash', ...t('pages') })
+      .input(ws.extend({ pageId: Id }))
+      .output(z.object({ ok: z.literal(true), count: z.number().int().nonnegative() })),
+    restore: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/restore', ...t('pages') })
+      .input(ws.extend({ pageId: Id }))
+      .output(Page),
+    /** Gone, with its collaborative document and every descendant. */
+    purge: baseContract
+      .route({ method: 'DELETE', path: '/pages/{pageId}', ...t('pages') })
+      .input(ws.extend({ pageId: Id }))
+      .output(z.object({ ok: z.literal(true), count: z.number().int().nonnegative() })),
+  },
+} as const
+export type QuireContract = typeof quireContract
+
+export { Ok }