@cyberismo/backend 1.2.0 → 1.3.0

package/src/domain/cards/mermaid.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Regex that matches standard AsciiDoc mermaid diagram blocks.
+ * Supports [mermaid], [mermaid,id], [mermaid,id,format=svg], etc.
+ * Matches both literal blocks (....) and listing blocks (----).
+ * Supports both LF and CRLF line endings.
+ */
+const MERMAID_BLOCK_REGEX =
+  /\[mermaid[^\]]*\]\r?\n(\.{4,}|-{4,})\r?\n([\s\S]*?)\r?\n\1/g;
+
+/**
+ * Pre-processes AsciiDoc content to convert [mermaid] blocks into passthrough HTML
+ * that can be detected and rendered by the frontend.
+ * This must run BEFORE asciidoctor.js converts the AsciiDoc to HTML.
+ * @param content - Raw AsciiDoc content
+ * @returns AsciiDoc content with mermaid blocks replaced by passthrough HTML divs
+ */
+export function preprocessMermaidBlocksForHtml(content: string): string {
+  return content.replace(MERMAID_BLOCK_REGEX, (_match, _delim, code) => {
+    const encoded = Buffer.from(code, 'utf-8').toString('base64');
+    return `++++\n<div class="mermaid-block" data-mermaid-code="${encoded}"></div>\n++++`;
+  });
+}

package/src/domain/cards/schema.ts

@@ -1,18 +1,10 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2026
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import { z } from 'zod';
 
+export const cardKeyParamSchema = z.object({ key: z.string().min(1) });
+
 const linkDirection = z.enum(['outbound', 'inbound']);
 
 export const createLinkSchema = z.object({
@@ -56,3 +48,7 @@ export const exportCardPdfSchema = z.object({
 });
 
 export type ExportCardPdfRequestBody = z.infer<typeof exportCardPdfSchema>;
+
+export const cardBatchSchema = z.object({
+  keys: z.array(z.string()).min(1).max(100),
+});

package/src/domain/cards/service.ts

@@ -1,37 +1,130 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2025
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import type {
+  AttachmentContent,
+  Card,
   ExportPdfOptions,
   MetadataContent,
-} from '@cyberismo/data-handler/interfaces/project-interfaces';
-import type { attachmentPayload } from '@cyberismo/data-handler/interfaces/request-status-interfaces';
-import { type CommandManager, evaluateMacros } from '@cyberismo/data-handler';
-import { preprocessMermaidBlocksForHtml } from '@cyberismo/data-handler/utils/mermaid-renderer';
-import { rewriteAsciidocCardXrefs } from '@cyberismo/data-handler/utils/asciidoc-xref';
+  QueryResult,
+} from '@cyberismo/model';
+import { AsciidoctorPdfError, type Workspace } from '@cyberismo/data-handler';
+import { preprocessMermaidBlocksForHtml } from './mermaid.js';
 import { allCards } from './lib.js';
+import { getCardQueryResult } from '../../export.js';
 import type { TreeOptions } from '../../types.js';
 
-export async function getProjectInfo(commands: CommandManager) {
-  return commands.consistent(async () => {
-    const projectResponse = await commands.showCmd.showProject();
+type RenderMode = 'inject' | 'staticSite';
+
+async function renderAdoc(
+  ws: Workspace,
+  key: string,
+  content: string,
+  mode: RenderMode,
+  fallback?: string,
+): Promise<string> {
+  let { content: asciidocContent } = await ws.render.macros(content, {
+    context: mode === 'staticSite' ? 'exportedSite' : 'localApp',
+    mode,
+    cardKey: key,
+    fallback,
+  });
+
+  // Convert [mermaid] AsciiDoc blocks to passthrough HTML before asciidoctor processes them
+  asciidocContent = preprocessMermaidBlocksForHtml(asciidocContent);
+
+  // Rewrite native AsciiDoc xrefs that target other cards into
+  // /projects/<prefix>/cards/<key> links.
+  return ws.render.xrefs(asciidocContent, mode);
+}
+
+export async function getCardData(
+  ws: Workspace,
+  key: string,
+  staticMode: boolean,
+): Promise<QueryResult<'card'>> {
+  return ws.consistent(async () => {
+    // The key reaches the logic program unchecked; details() rejects unknown keys first.
+    await ws.cards.details(key);
+    const card = staticMode
+      ? await getCardQueryResult(ws, key)
+      : await ws.queries.runQuery('card', 'localApp', { cardKey: key });
+    if (card.length !== 1) {
+      throw new Error('Query failed. Check card-query syntax');
+    }
+    // Hidden fields stay off the static site; the card view never shows them.
+    const data = staticMode
+      ? { ...card[0], fields: card[0].fields.filter((f) => f.visibility) }
+      : card[0];
+    return data;
+  });
+}
+
+/** One solve for many cards; keys the project does not hold are left out. */
+export async function getCardBatch(
+  ws: Workspace,
+  keys: string[],
+): Promise<Record<string, QueryResult<'card'>>> {
+  return ws.consistent(async () => {
+    // The keys reach the logic program unchecked; only known ones go through.
+    const cardKeys = [...new Set(keys)].filter((key) => ws.cards.has(key));
+    // The card query reads an empty list as no list and answers every card.
+    if (cardKeys.length === 0) {
+      return {};
+    }
+    const cards = await ws.queries.runQuery('card', 'localApp', { cardKeys });
+    return Object.fromEntries(cards.map((card) => [card.key, card]));
+  });
+}
+
+export async function getCardContent(
+  ws: Workspace,
+  key: string,
+  staticMode: boolean,
+): Promise<{ adocContent: string }> {
+  return ws.consistent(async () => {
+    const card = await ws.cards.details(key);
+    const adocContent = await renderAdoc(
+      ws,
+      key,
+      card.content || '',
+      staticMode ? 'staticSite' : 'inject',
+      '',
+    );
+    return { adocContent };
+  });
+}
+
+// The static site publishes no more of the stored card than its card view reads.
+type StaticCardSource = Pick<Card, 'key' | 'path' | 'content' | 'attachments'>;
+
+export async function getCardSource(
+  ws: Workspace,
+  key: string,
+  staticMode: boolean,
+): Promise<Card | StaticCardSource> {
+  const card = await ws.cards.details(key);
+  if (!staticMode) {
+    return card;
+  }
+  return {
+    key: card.key,
+    path: card.path,
+    content: card.content,
+    attachments: card.attachments,
+  };
+}
+
+export async function getProjectInfo(ws: Workspace) {
+  return ws.consistent(async () => {
+    const projectResponse = await ws.settings.info();
 
-    const workflowsResponse = await commands.showCmd.showWorkflowsWithDetails();
+    const workflowsResponse = await ws.resources.contents('workflows');
     if (!workflowsResponse) {
       throw new Error('No workflows found');
     }
 
-    const cardTypesResponse = await commands.showCmd.showCardTypesWithDetails();
+    const cardTypesResponse = await ws.resources.contents('cardTypes');
     if (!cardTypesResponse) {
       throw new Error('No card types found');
     }
@@ -46,55 +139,48 @@ export async function getProjectInfo(commands: CommandManager) {
 }
 
 export async function updateCard(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   body: any,
-): Promise<boolean> {
-  let written = false;
-  await commands.atomic(async () => {
+): Promise<void> {
+  await ws.atomic(async () => {
     if (body.state) {
-      await commands.transitionCmd.cardTransition(key, body.state);
-      written = true;
+      await ws.cards.transition(key, body.state);
     }
     if (body.content != null) {
-      await commands.editCmd.editCardContent(key, body.content);
-      written = true;
+      await ws.cards.edit(key, body.content);
     }
     if (body.metadata) {
       for (const [metadataKey, metadataValue] of Object.entries(
         body.metadata,
       )) {
-        await commands.editCmd.editCardMetadata(
+        await ws.cards.editField(
           key,
           metadataKey,
-          metadataValue as MetadataContent,
+          metadataValue as Exclude<MetadataContent, bigint>,
         );
-        written = true;
       }
     }
     if (body.parent) {
-      await commands.moveCmd.moveCard(key, body.parent);
-      written = true;
+      await ws.cards.move(key, body.parent);
     }
     if (body.index != null) {
-      await commands.moveCmd.rankByIndex(key, body.index);
-      written = true;
+      await ws.cards.rankAt(key, body.index);
     }
   }, `Update card ${key}`);
-  return written;
 }
 
-export async function deleteCard(commands: CommandManager, key: string) {
-  await commands.removeCmd.remove('card', key);
+export async function deleteCard(ws: Workspace, key: string) {
+  await ws.cards.remove(key);
 }
 
 export async function createCard(
-  commands: CommandManager,
+  ws: Workspace,
   template: string,
   parentKey?: string,
 ) {
-  const result = await commands.createCmd.createCard(
+  const result = await ws.cards.create(
     template,
     parentKey === 'root' ? undefined : parentKey,
   );
@@ -106,20 +192,16 @@ export async function createCard(
 }
 
 export async function uploadAttachments(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   files: File[],
 ) {
   const succeeded: string[] = [];
-  await commands.atomic(async () => {
+  await ws.atomic(async () => {
     for (const file of files) {
       if (file instanceof File) {
         const buffer = await file.arrayBuffer();
-        await commands.createCmd.createAttachment(
-          key,
-          file.name,
-          Buffer.from(buffer),
-        );
+        await ws.cards.addAttachment(key, file.name, Buffer.from(buffer));
         succeeded.push(file.name);
       }
     }
@@ -139,50 +221,27 @@ function validateAttachmentFileName(filename: string): void {
 }
 
 export async function removeAttachment(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   filename: string,
 ) {
   validateAttachmentFileName(filename);
-  await commands.removeCmd.remove('attachment', key, filename);
+  await ws.cards.removeAttachment(key, filename);
   return { message: 'Attachment removed successfully' };
 }
 
 export async function parseContent(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   content: string,
 ) {
-  return commands.consistent(async () => {
-    let asciidocContent: string;
-    try {
-      asciidocContent = await evaluateMacros(content, {
-        context: 'localApp',
-        mode: 'inject',
-        project: commands.project,
-        cardKey: key,
-      });
-    } catch (error) {
-      asciidocContent = `Macro error: ${error instanceof Error ? error.message : 'Unknown error'}\n\n${content}`;
-    }
-
-    // Convert [mermaid] AsciiDoc blocks to passthrough HTML before asciidoctor processes them
-    asciidocContent = preprocessMermaidBlocksForHtml(asciidocContent);
-
-    // Rewrite native AsciiDoc xrefs that target other cards into
-    // /projects/<prefix>/cards/<key> links.
-    asciidocContent = rewriteAsciidocCardXrefs(
-      asciidocContent,
-      commands.project,
-      'inject',
-    );
-
-    return { adocContent: asciidocContent };
-  });
+  return ws.consistent(async () => ({
+    adocContent: await renderAdoc(ws, key, content, 'inject'),
+  }));
 }
 
 export async function createLink(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   target: string,
   linkType: string,
@@ -194,19 +253,13 @@ export async function createLink(
   const source = direction === 'outbound' ? key : target;
   const destination = direction === 'outbound' ? target : key;
 
-  await commands.createCmd.createLink(
-    source,
-    destination,
-    linkType,
-    description,
-    direction,
-  );
+  await ws.cards.addLink(source, destination, linkType, description, direction);
 
   return { message: 'Link created successfully' };
 }
 
 export async function removeLink(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   target: string,
   linkType: string,
@@ -217,18 +270,12 @@ export async function removeLink(
   // For inbound: target is source, key is destination
   const source = direction === 'outbound' ? key : target;
   const destination = direction === 'outbound' ? target : key;
-  await commands.removeCmd.remove(
-    'link',
-    source,
-    destination,
-    linkType,
-    description,
-  );
+  await ws.cards.removeLink(source, destination, linkType, description);
   return { message: 'Link removed successfully' };
 }
 
 export async function updateLink(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   toCard: string,
   linkType: string,
@@ -241,18 +288,11 @@ export async function updateLink(
 ) {
   // For simplicity create the new link first so that duplicate-link validation runs before
   // the old link is removed. This also handles direction changes.
-  return commands.atomic(async () => {
-    await createLink(
-      commands,
-      key,
-      toCard,
-      linkType,
-      direction,
-      linkDescription,
-    );
+  return ws.atomic(async () => {
+    await createLink(ws, key, toCard, linkType, direction, linkDescription);
 
     await removeLink(
-      commands,
+      ws,
       key,
       previousToCard,
       previousLinkType,
@@ -265,12 +305,12 @@ export async function updateLink(
 }
 
 export async function getAttachment(
-  commands: CommandManager,
+  ws: Workspace,
   key: string,
   filename: string,
-): Promise<attachmentPayload> {
+): Promise<AttachmentContent> {
   validateAttachmentFileName(filename);
-  return commands.showCmd.showAttachment(key, filename);
+  return ws.cards.attachment(key, filename);
 }
 
 /**
@@ -280,25 +320,25 @@ export async function getAttachment(
  * @returns all cards in a flattened array
  */
 export async function findAllCards(
-  commands: CommandManager,
+  ws: Workspace,
   options?: TreeOptions,
 ): ReturnType<typeof allCards> {
-  return allCards(commands, options);
+  return allCards(ws, options);
 }
 /**
  * Gets all attachments that are required for rendering the wanted cards
- * @param commands the command manager used for the query
+ * @param ws the command manager used for the query
  * @param options optional tree query options
  * @returns all attachments for cards returned by the tree query
  */
 export async function findRelevantAttachments(
-  commands: CommandManager,
+  ws: Workspace,
   options?: TreeOptions,
 ) {
   const cards = new Set<string>(
-    (await allCards(commands, options)).map((c) => c.key),
+    (await allCards(ws, options)).map((c) => c.key),
   );
-  const attachments = await commands.showCmd.showAttachments();
+  const attachments = await ws.cards.attachments();
   return attachments
     .filter(
       (attachment) =>
@@ -311,9 +351,16 @@ export async function findRelevantAttachments(
 }
 
 export async function exportCard(
-  commands: CommandManager,
+  ws: Workspace,
   options: ExportPdfOptions,
-): Promise<Buffer> {
-  const result = await commands.exportCmd.exportPdfBuffer(options);
-  return result;
+): Promise<Uint8Array> {
+  try {
+    return (await ws.export.pdf(options)).pdf;
+  } catch (error) {
+    // Diagnostics can carry server paths: logged here, never sent.
+    if (error instanceof AsciidoctorPdfError) {
+      console.error(error.message, error.diagnostics.join('\n'));
+    }
+    throw error;
+  }
 }

package/src/domain/connectors/index.ts

@@ -1,15 +1,6 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2026
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation. This program is distributed in the hope that it
-  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
-  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-  See the GNU Affero General Public License for more details.
-  You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
 import { Hono } from 'hono';
 import { isSSGContext } from 'hono/ssg';
 import * as connectorsService from './service.js';
@@ -31,8 +22,8 @@ router.get('/', requireRole(UserRole.Reader), async (c) => {
   if (isSSGContext(c)) {
     return c.json([]);
   }
-  const commands = c.get('commands');
-  const connectors = await connectorsService.getConnectors(commands);
+  const ws = c.get('ws');
+  const connectors = await connectorsService.getConnectors(ws);
   return c.json(connectors);
 });
 

package/src/domain/connectors/service.ts

@@ -1,17 +1,7 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2024
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
-import type { CommandManager } from '@cyberismo/data-handler';
+import type { Workspace } from '@cyberismo/data-handler';
 
 export interface ExternalItem {
   key: string;
@@ -24,13 +14,8 @@ export interface Connector {
   items: ExternalItem[];
 }
 
-export async function getConnectors(
-  commands: CommandManager,
-): Promise<Connector[]> {
-  const results = await commands.calculateCmd.runQuery(
-    'connectors',
-    'localApp',
-  );
+export async function getConnectors(ws: Workspace): Promise<Connector[]> {
+  const results = await ws.queries.runQuery('connectors', 'localApp');
 
   // Separate connectors from items based on type field
   const connectorsMap = new Map<string, Connector>();

package/src/domain/events/events-by-project.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { SYSTEM_ACTOR, type ProjectDirectory } from '@cyberismo/data-handler';
+import { ProjectEvents } from './project-events.js';
+
+/**
+ * The events of each project of a directory, by prefix. A project's events
+ * follow its changes, read through a system handle, from first use.
+ */
+export class EventsByProject {
+  private readonly events = new Map<string, ProjectEvents>();
+
+  constructor(private readonly directory: ProjectDirectory) {}
+
+  /**
+   * The events of the project with `prefix`.
+   * @throws ProjectNotFoundError if the directory has no such project.
+   */
+  async for(prefix: string): Promise<ProjectEvents> {
+    const known = this.events.get(prefix);
+    if (known) {
+      return known;
+    }
+    const ws = await this.directory.open(prefix, SYSTEM_ACTOR);
+    // Another request may have created them while this one waited.
+    let events = this.events.get(prefix);
+    if (!events) {
+      const held = new ProjectEvents(ws.changes);
+      this.events.set(prefix, held);
+      // An event names the project's prefix once its write is done, so a
+      // rename is followed as the directory follows it.
+      ws.changes.subscribe(({ project }) => this.follow(held, project));
+      events = held;
+    }
+    return events;
+  }
+
+  // Keeps `events` under `prefix`, its project's prefix now, unless another
+  // project's events hold it.
+  private follow(events: ProjectEvents, prefix: string) {
+    if (this.events.has(prefix)) {
+      return;
+    }
+    for (const [key, held] of this.events) {
+      if (held === events) {
+        this.events.delete(key);
+        this.events.set(prefix, events);
+        return;
+      }
+    }
+  }
+
+  /** Disposes the project's events, closing their connections. */
+  drop(prefix: string) {
+    this.events.get(prefix)?.dispose();
+    this.events.delete(prefix);
+  }
+}

package/src/domain/events/index.ts

@@ -1,15 +1,5 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2026
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import { Hono } from 'hono';
 import { disableSSG } from 'hono/ssg';
@@ -91,7 +81,7 @@ router.put(
   zValidator('json', presenceSchema),
   (c) => {
     const { connectionId, sequence, cardKey, mode } = c.req.valid('json');
-    if (cardKey && !c.get('commands').project.hasCard(cardKey)) {
+    if (cardKey && !c.get('ws').cards.has(cardKey)) {
       return c.json({ error: 'Card not found' }, 404);
     }
     const events = c.get('events');

package/src/domain/events/lifetime.ts

@@ -1,15 +1,5 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2026
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 const MAX_LIFETIME_MS = 30 * 60_000;
 const ROTATION_MARGIN_MS = 30_000;