@crombolo/server 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,69 @@
+crombolo
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. crombolo is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @crombolo/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @crombolo/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @crombolo/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@crombolo/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@crombolo/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "The crombolo HTTP server: routing, configuration, media stores and background jobs.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@crombolo/api-management": "0.9.1",
+    "@crombolo/assistant": "0.9.1",
+    "@crombolo/auth": "0.9.1",
+    "@crombolo/backoffice-host": "0.9.1",
+    "@crombolo/contracts": "0.9.1",
+    "@crombolo/core": "0.9.1",
+    "@crombolo/data": "0.9.1",
+    "@crombolo/render": "0.9.1",
+    "@crombolo/schema": "0.9.1",
+    "@crombolo/transfer": "0.9.1",
+    "@logtape/logtape": "^2.3.8"
+  }
+}

package/src/access.ts

@@ -0,0 +1,114 @@
+/**
+ * What authorization needs from the database: where nodes sit in their trees,
+ * and each signed-in user's combined start nodes, group verbs and languages.
+ */
+import type { NodeChain, NodeLookup, Principal } from '@crombolo/api-management'
+import { combineStartNodes, normaliseUuid, ObjectTypes } from '@crombolo/core'
+import { type Db, fromDbBool, UserRepository } from '@crombolo/data'
+
+const inList = (values: readonly unknown[]) => values.map(() => '?').join(', ')
+
+async function chains(
+  db: Db,
+  rows: Array<{ id: number; unique_id: string; path: string; trashed: unknown }>,
+): Promise<Map<string, NodeChain>> {
+  const ids = [
+    ...new Set(
+      rows.flatMap((r) =>
+        String(r.path)
+          .split(',')
+          .map(Number)
+          .filter((id) => id > 0),
+      ),
+    ),
+  ]
+  const keys = new Map<number, string>()
+  if (ids.length > 0)
+    for (const row of await db.query<{ id: number; unique_id: string }>(
+      `SELECT id, unique_id FROM node WHERE id IN (${inList(ids)})`,
+      ids,
+    ))
+      keys.set(Number(row.id), normaliseUuid(String(row.unique_id)))
+  return new Map(
+    rows.map((row) => [
+      normaliseUuid(String(row.unique_id)),
+      {
+        chain: String(row.path)
+          .split(',')
+          .map(Number)
+          .filter((id) => id > 0)
+          .flatMap((id) => {
+            const key = keys.get(id)
+            return key ? [key] : []
+          }),
+        trashed: fromDbBool(row.trashed),
+      },
+    ]),
+  )
+}
+
+export function createNodeLookup(db: Db): NodeLookup {
+  const byKeys = async (objectType: string, keys: readonly string[]) => {
+    const wanted = keys.filter((k) => /^[0-9a-f-]{32,36}$/i.test(k)).map(normaliseUuid)
+    if (wanted.length === 0) return new Map<string, NodeChain>()
+    return chains(
+      db,
+      await db.query(
+        `SELECT id, unique_id, path, trashed FROM node
+         WHERE node_object_type = ? AND unique_id IN (${inList(wanted)})`,
+        [objectType, ...wanted],
+      ),
+    )
+  }
+  return {
+    documents: (keys) => byKeys(ObjectTypes.Document, keys),
+    media: (keys) => byKeys(ObjectTypes.Media, keys),
+    async documentDescendants(key) {
+      const node = (
+        await db.query<{ path: string }>('SELECT path FROM node WHERE unique_id = ?', [
+          normaliseUuid(key),
+        ])
+      )[0]
+      if (!node) return []
+      return [
+        ...(
+          await chains(
+            db,
+            await db.query(
+              'SELECT id, unique_id, path, trashed FROM node WHERE node_object_type = ? AND path LIKE ?',
+              [ObjectTypes.Document, `${node.path},%`],
+            ),
+          )
+        ).values(),
+      ]
+    },
+    async versionDocument(versionId) {
+      const id = Number(versionId)
+      if (!Number.isInteger(id)) return undefined
+      const row = (
+        await db.query<{ unique_id: string }>(
+          'SELECT n.unique_id FROM content_version cv JOIN node n ON n.id = cv.node_id WHERE cv.id = ?',
+          [id],
+        )
+      )[0]
+      return row ? normaliseUuid(String(row.unique_id)) : undefined
+    },
+  }
+}
+
+/** A user's languages, combined start nodes per tree, and group verbs. */
+export async function loadAccess(
+  db: Db,
+  userId: number,
+): Promise<Pick<Principal, 'languages' | 'startNodes' | 'groups'>> {
+  const data = await new UserRepository(db).access(userId)
+  return {
+    languages: data.languages,
+    groups: data.groups,
+    startNodes: {
+      document: combineStartNodes(data.groupStartNodes.document, data.userStartNodes.document),
+      media: combineStartNodes(data.groupStartNodes.media, data.userStartNodes.media),
+      element: combineStartNodes(data.groupStartNodes.element, data.userStartNodes.element),
+    },
+  }
+}

package/src/adapters/assistant.ts

@@ -0,0 +1,229 @@
+/**
+ * Changeset persistence for the assistant, over the tables migration 017 adds.
+ *
+ * A proposal has to outlive the conversation that produced it: one raised over
+ * MCP by an agent in a terminal is reviewed in the backoffice by a person in a
+ * browser, in another process. `body` and `params` are stored as JSON because
+ * they are a prepared Management API request and nothing here inspects them —
+ * only the approval path, which dispatches them.
+ */
+import type {
+  ChangeOrigin,
+  ChangeStatus,
+  Changeset,
+  ChangesetStore,
+  ProposedChange,
+} from '@crombolo/assistant'
+import { normaliseUuid } from '@crombolo/core'
+import { type Db, DbDate } from '@crombolo/data'
+
+interface ChangesetRow {
+  key: string
+  user_key: string
+  title: string
+  origin: string
+  create_date: unknown
+  update_date: unknown
+}
+
+interface ChangeRow {
+  key: string
+  kind: string
+  summary: string
+  status: string
+  params: string
+  body: string
+  baseline: string | null
+  problems: string
+  error: string | null
+  create_date: unknown
+}
+
+const iso = (value: unknown): string => (DbDate.fromDb(value) ?? new Date(0)).toISOString()
+
+const parse = <T>(value: string, fallback: T): T => {
+  try {
+    return JSON.parse(value) as T
+  } catch {
+    return fallback
+  }
+}
+
+const hydrateChange = (row: ChangeRow): ProposedChange => ({
+  key: normaliseUuid(String(row.key)),
+  kind: String(row.kind) as ProposedChange['kind'],
+  summary: String(row.summary),
+  params: parse<Record<string, string>>(String(row.params), {}),
+  body: parse<unknown>(String(row.body), null),
+  baseline: row.baseline === null ? undefined : String(row.baseline),
+  problems: parse<ProposedChange['problems']>(String(row.problems), []),
+  status: String(row.status) as ChangeStatus,
+  error: row.error === null ? undefined : String(row.error),
+  createDate: iso(row.create_date),
+})
+
+export function createChangesetStore(db: Db): ChangesetStore {
+  const changesOf = async (changesetKey: string): Promise<ProposedChange[]> => {
+    const rows = await db.query<ChangeRow>(
+      `SELECT key, kind, summary, status, params, body, baseline, problems, error, create_date
+         FROM assistant_change WHERE changeset_key = ? ORDER BY sort_order, id`,
+      [changesetKey],
+    )
+    return rows.map(hydrateChange)
+  }
+
+  const hydrate = async (row: ChangesetRow): Promise<Changeset> => ({
+    key: normaliseUuid(String(row.key)),
+    userKey: normaliseUuid(String(row.user_key)),
+    title: String(row.title),
+    origin: String(row.origin) as ChangeOrigin,
+    changes: await changesOf(normaliseUuid(String(row.key))),
+    createDate: iso(row.create_date),
+    updateDate: iso(row.update_date),
+  })
+
+  const touch = (key: string) =>
+    db.exec('UPDATE assistant_changeset SET update_date = ? WHERE key = ?', [
+      DbDate.toDb(new Date()),
+      key,
+    ])
+
+  return {
+    async create(input) {
+      const key = normaliseUuid(crypto.randomUUID())
+      const now = new Date()
+      await db.exec(
+        `INSERT INTO assistant_changeset (key, user_key, title, origin, create_date, update_date)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+        [
+          key,
+          normaliseUuid(input.userKey),
+          input.title,
+          input.origin,
+          DbDate.toDb(now),
+          DbDate.toDb(now),
+        ],
+      )
+      return {
+        key,
+        userKey: normaliseUuid(input.userKey),
+        title: input.title,
+        origin: input.origin,
+        changes: [],
+        createDate: now.toISOString(),
+        updateDate: now.toISOString(),
+      }
+    },
+
+    async load(key) {
+      const rows = await db.query<ChangesetRow>(
+        `SELECT key, user_key, title, origin, create_date, update_date
+           FROM assistant_changeset WHERE key = ?`,
+        [normaliseUuid(key)],
+      )
+      return rows[0] ? await hydrate(rows[0]) : undefined
+    },
+
+    async listFor(userKey, limit = 20) {
+      const rows = await db.query<ChangesetRow>(
+        `SELECT key, user_key, title, origin, create_date, update_date
+           FROM assistant_changeset WHERE user_key = ?
+          ORDER BY update_date DESC, id DESC LIMIT ?`,
+        [normaliseUuid(userKey), limit],
+      )
+      const out: Changeset[] = []
+      for (const row of rows) out.push(await hydrate(row))
+      return out
+    },
+
+    async changeFor(userKey, changeKey) {
+      const rows = await db.query<ChangeRow>(
+        `SELECT c.key, c.kind, c.summary, c.status, c.params, c.body, c.baseline, c.problems,
+                c.error, c.create_date
+           FROM assistant_change c
+           JOIN assistant_changeset s ON s.key = c.changeset_key
+          WHERE c.key = ? AND s.user_key = ?`,
+        [normaliseUuid(changeKey), normaliseUuid(userKey)],
+      )
+      return rows[0] ? hydrateChange(rows[0]) : undefined
+    },
+
+    async openFor(userKey, origin) {
+      const rows = await db.query<ChangesetRow>(
+        `SELECT s.key, s.user_key, s.title, s.origin, s.create_date, s.update_date
+           FROM assistant_changeset s
+          WHERE s.user_key = ? AND s.origin = ?
+            AND EXISTS (SELECT 1 FROM assistant_change c
+                         WHERE c.changeset_key = s.key AND c.status = 'proposed')
+          ORDER BY s.update_date DESC, s.id DESC LIMIT 1`,
+        [normaliseUuid(userKey), origin],
+      )
+      return rows[0] ? await hydrate(rows[0]) : undefined
+    },
+
+    async append(changesetKey, change) {
+      const key = normaliseUuid(changesetKey)
+      const counted = await db.query<{ next: number | null }>(
+        'SELECT MAX(sort_order) AS next FROM assistant_change WHERE changeset_key = ?',
+        [key],
+      )
+      const sortOrder = (counted[0]?.next ?? -1) + 1
+      await db.exec(
+        `INSERT INTO assistant_change
+           (key, changeset_key, sort_order, kind, summary, status, params, body, baseline, problems, error, create_date)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          normaliseUuid(change.key),
+          key,
+          sortOrder,
+          change.kind,
+          change.summary,
+          change.status,
+          JSON.stringify(change.params),
+          JSON.stringify(change.body ?? null),
+          change.baseline ?? null,
+          JSON.stringify(change.problems),
+          change.error ?? null,
+          DbDate.toDb(new Date(change.createDate)),
+        ],
+      )
+      await touch(key)
+    },
+
+    async replaceBody(changeKey, body, problems) {
+      const key = normaliseUuid(changeKey)
+      await db.exec('UPDATE assistant_change SET body = ?, problems = ? WHERE key = ?', [
+        JSON.stringify(body ?? null),
+        JSON.stringify(problems),
+        key,
+      ])
+      const rows = await db.query<{ changeset_key: string }>(
+        'SELECT changeset_key FROM assistant_change WHERE key = ?',
+        [key],
+      )
+      const owner = rows[0]?.changeset_key
+      if (owner) await touch(String(owner))
+    },
+
+    async settle(changeKey, outcome) {
+      const key = normaliseUuid(changeKey)
+      await db.exec('UPDATE assistant_change SET status = ?, error = ? WHERE key = ?', [
+        outcome.status,
+        outcome.error ?? null,
+        key,
+      ])
+      const rows = await db.query<{ changeset_key: string }>(
+        'SELECT changeset_key FROM assistant_change WHERE key = ?',
+        [key],
+      )
+      const owner = rows[0]?.changeset_key
+      if (owner) await touch(String(owner))
+    },
+
+    async remove(key) {
+      const owner = normaliseUuid(key)
+      await db.exec('DELETE FROM assistant_change WHERE changeset_key = ?', [owner])
+      await db.exec('DELETE FROM assistant_changeset WHERE key = ?', [owner])
+    },
+  }
+}

package/src/adapters/blueprints.ts

@@ -0,0 +1,163 @@
+/**
+ * Document blueprints ("Document Blueprints" in Settings, "Create Document
+ * Blueprint" on a page): stored as documents of their own object type in their
+ * own folder tree, never published.
+ */
+import type { BlueprintPort, Principal } from '@crombolo/api-management'
+import { ObjectTypes, type TreeItem } from '@crombolo/core'
+import {
+  type Db,
+  DocumentRepository,
+  FolderRepository,
+  type NodeSchemaState,
+  type ValueIntake,
+  WriteRejectedError,
+} from '@crombolo/data'
+import { createFolderPort, createSettingsTree } from './content.ts'
+
+export function createBlueprintPort(
+  db: Db,
+  options: { nodeState?: NodeSchemaState; valueIntake?: ValueIntake } = {},
+): BlueprintPort {
+  const repo = new DocumentRepository(db, {
+    nodeState: options.nodeState,
+    kind: 'blueprint',
+    valueIntake: options.valueIntake,
+  })
+  const documents = new DocumentRepository(db, { nodeState: options.nodeState })
+  const container = ObjectTypes.DocumentBlueprintContainer
+  const folders = new FolderRepository(db, container, ObjectTypes.DocumentBlueprint)
+
+  const decorate = async (item: TreeItem) => {
+    const blueprint = await repo.byKey(item.key)
+    item.icon = blueprint?.contentTypeIcon ?? 'icon-blueprint'
+    item.contentTypeKey = blueprint?.contentTypeKey ?? null
+  }
+  const tree = createSettingsTree(repo.nodes, container, ObjectTypes.DocumentBlueprint, decorate)
+
+  const userIdOf = async (principal: Principal): Promise<number | undefined> => {
+    const rows = await db.query<{ id: number }>('SELECT id FROM user_account WHERE key = ?', [
+      principal.id,
+    ])
+    return rows[0] ? Number(rows[0].id) : undefined
+  }
+  const failure = (error: unknown) => {
+    if (error instanceof WriteRejectedError)
+      return { ok: false as const, reason: error.message, status: 409 }
+    return {
+      ok: false as const,
+      reason: error instanceof Error ? error.message : String(error),
+      status: 400,
+    }
+  }
+
+  return {
+    byKey: (key) => repo.byKey(key),
+
+    async create(input, principal) {
+      try {
+        await repo.create({ ...input, componentKey: null, userId: await userIdOf(principal) })
+        return { ok: true as const }
+      } catch (error) {
+        return failure(error)
+      }
+    },
+
+    async update(key, input, principal) {
+      try {
+        const updated = await repo.update({
+          ...input,
+          key,
+          componentKey: null,
+          userId: await userIdOf(principal),
+        })
+        if (!updated)
+          return { ok: false as const, reason: 'The blueprint could not be found.', status: 404 }
+        return { ok: true as const }
+      } catch (error) {
+        return failure(error)
+      }
+    },
+
+    async fromDocument(documentKey, init, principal) {
+      const document = await documents.byKey(documentKey)
+      if (!document)
+        return { ok: false as const, reason: 'The document could not be found.', status: 404 }
+      try {
+        const created = await repo.create({
+          key: init.key,
+          contentTypeKey: document.contentTypeKey,
+          componentKey: null,
+          parentKey: init.parentKey,
+          values: document.values,
+          variants: document.variants.map((v) => ({
+            culture: v.culture,
+            segment: v.segment,
+            name: v.culture === null ? init.name : v.name,
+          })),
+          userId: await userIdOf(principal),
+        })
+        return { ok: true as const, key: created.key }
+      } catch (error) {
+        return failure(error)
+      }
+    },
+
+    remove: (key) => repo.delete(key),
+
+    async move(key, targetKey) {
+      const result = await repo.move(key, targetKey)
+      if (result === 'moved') return { ok: true as const }
+      return result === 'notFound'
+        ? { ok: false as const, reason: 'The blueprint or folder could not be found.', status: 404 }
+        : { ok: false as const, reason: 'A blueprint cannot move there.', status: 400 }
+    },
+
+    versions: (key) => repo.versions(key),
+    async systemUserKey() {
+      const rows = await db.query<{ key: string }>(
+        'SELECT key FROM user_account ORDER BY id LIMIT 1',
+      )
+      return rows[0] ? String(rows[0].key).toLowerCase() : null
+    },
+
+    async forContentType(contentTypeKey, paging) {
+      const rows = await db.query(
+        `SELECT n.unique_id, n.text FROM node n JOIN content c ON c.node_id = n.id
+         JOIN node t ON t.id = c.content_type_id
+         WHERE n.node_object_type = ? AND t.unique_id = ? ORDER BY n.text, n.id`,
+        [ObjectTypes.DocumentBlueprint, contentTypeKey.toLowerCase()],
+      )
+      const all = rows.map((row) => ({
+        key: String(row.unique_id).toLowerCase(),
+        name: String(row.text ?? ''),
+      }))
+      return { total: all.length, items: all.slice(paging.skip, paging.skip + paging.take) }
+    },
+
+    treeRoot: tree.treeRoot,
+    treeChildren: tree.treeChildren,
+    treeAncestors: tree.ancestors,
+    treeSiblings: tree.siblings,
+
+    async items(keys) {
+      const found = []
+      for (const key of keys) {
+        const blueprint = await repo.byKey(key)
+        if (!blueprint) continue
+        found.push({
+          key: blueprint.key,
+          name:
+            blueprint.variants.find((v) => v.culture === null)?.name ??
+            blueprint.variants[0]?.name ??
+            '',
+          contentTypeKey: blueprint.contentTypeKey,
+          icon: blueprint.contentTypeIcon,
+        })
+      }
+      return found
+    },
+
+    folders: createFolderPort(folders, tree, async () => {}),
+  }
+}