@cyberismo/backend 1.1.2 → 1.3.0

package/src/domain/cards/service.ts

@@ -1,38 +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/>.
-*/
-
-import { convert } from '@asciidoctor/core';
+// 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');
     }
@@ -47,48 +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,
-) {
-  await commands.atomic(async () => {
+): Promise<void> {
+  await ws.atomic(async () => {
     if (body.state) {
-      await commands.transitionCmd.cardTransition(key, body.state);
+      await ws.cards.transition(key, body.state);
     }
     if (body.content != null) {
-      await commands.editCmd.editCardContent(key, body.content);
+      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>,
         );
       }
     }
     if (body.parent) {
-      await commands.moveCmd.moveCard(key, body.parent);
+      await ws.cards.move(key, body.parent);
     }
     if (body.index != null) {
-      await commands.moveCmd.rankByIndex(key, body.index);
+      await ws.cards.rankAt(key, body.index);
     }
   }, `Update card ${key}`);
 }
 
-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,
   );
@@ -100,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);
       }
     }
@@ -133,71 +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 openAttachment(
-  commands: CommandManager,
-  key: string,
-  filename: string,
-) {
-  validateAttachmentFileName(filename);
-  await commands.showCmd.openAttachment(key, filename);
-  return { message: 'Attachment opened 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',
-    );
-
-    const projectPrefix = commands.project.projectPrefix;
-    const parsedContent = (
-      await convert(asciidocContent, {
-        safe: 'safe',
-        attributes: {
-          imagesdir: `/api/projects/${projectPrefix}/cards/${key}/a`,
-          icons: 'font',
-        },
-      })
-    ).toString();
-
-    return { parsedContent };
-  });
+  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,
@@ -209,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,
@@ -232,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,
@@ -256,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,
@@ -280,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);
 }
 
 /**
@@ -295,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) =>
@@ -326,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

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { Hono } from 'hono';
+import { disableSSG } from 'hono/ssg';
+import { streamSSE, type SSEMessage } from 'hono/streaming';
+import { isAtLeastRole, requireRole } from '../../middleware/auth.js';
+import { zValidator } from '../../middleware/zvalidator.js';
+import { UserRole } from '../../types.js';
+import { computeLifetimeMs } from './lifetime.js';
+import { presenceSchema } from './schema.js';
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+const router = new Hono();
+
+router.get('/', disableSSG(), requireRole(UserRole.Reader), (c) => {
+  const events = c.get('events');
+  const user = c.get('user');
+  const capabilities = {
+    canSeeIdentity: isAtLeastRole(user.role, UserRole.Editor),
+    canDeclareEditing: isAtLeastRole(user.role, UserRole.Editor),
+    canSeePresence: isAtLeastRole(user.role, UserRole.Editor),
+  };
+  return streamSSE(c, async (stream) => {
+    if (stream.aborted) return;
+    let finish: () => void = () => {};
+    const closed = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    let stopped = false;
+    let release = () => {};
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
+      release();
+      finish();
+    };
+    // Ends the stream after one last message. Deliberately does not call
+    // `release()`: a rotating connection has been retired, and disconnecting
+    // it would drop the presence entry that bridges the client's reconnect.
+    const terminate = (message: SSEMessage) => {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(heartbeat);
+      clearTimeout(rotate);
+      void stream.writeSSE(message).then(finish);
+    };
+    // Hono swallows stream write errors; `onAbort` is the only teardown signal.
+    stream.onAbort(stop);
+    const connectionId = events.connect(user, capabilities, {
+      send: (message) => void stream.writeSSE(message),
+      close: stop,
+      terminate,
+    });
+    release = () => events.disconnect(connectionId);
+    const heartbeat = setInterval(
+      () => void stream.writeSSE({ event: 'hb', data: '' }),
+      HEARTBEAT_INTERVAL_MS,
+    );
+    const rotate = setTimeout(
+      () => {
+        events.retire(connectionId);
+        terminate({ event: 'rotating', data: '' });
+      },
+      computeLifetimeMs(c.get('tokenExp')),
+    );
+    try {
+      await closed;
+    } finally {
+      clearInterval(heartbeat);
+      clearTimeout(rotate);
+      stop();
+    }
+  });
+});
+
+router.put(
+  '/presence',
+  requireRole(UserRole.Reader),
+  zValidator('json', presenceSchema),
+  (c) => {
+    const { connectionId, sequence, cardKey, mode } = c.req.valid('json');
+    if (cardKey && !c.get('ws').cards.has(cardKey)) {
+      return c.json({ error: 'Card not found' }, 404);
+    }
+    const events = c.get('events');
+    const known = events.update(
+      connectionId,
+      c.get('user').id,
+      sequence,
+      cardKey,
+      mode,
+    );
+    if (!known) {
+      return c.json({ error: 'Presence connection not found' }, 404);
+    }
+    return c.body(null, 204);
+  },
+);
+
+export default router;