@cyberismo/backend 0.0.21 → 0.0.23

package/src/domain/cards/lib.ts

@@ -30,122 +30,124 @@ export async function getCardDetails(
   staticMode: boolean,
   raw: boolean,
 ): Promise<result> {
-  let cardDetailsResponse: Card;
-  try {
-    cardDetailsResponse = commands.showCmd.showCardDetails(key);
-  } catch {
-    return { status: 400, message: `Card ${key} not found from project` };
-  }
+  return commands.consistent(async () => {
+    let cardDetailsResponse: Card;
+    try {
+      cardDetailsResponse = await commands.showCmd.showCardDetails(key);
+    } catch {
+      return { status: 400, message: `Card ${key} not found from project` };
+    }
 
-  if (!cardDetailsResponse) {
-    return { status: 400, message: `Card ${key} not found from project` };
-  }
+    if (!cardDetailsResponse) {
+      return { status: 400, message: `Card ${key} not found from project` };
+    }
 
-  // always parse for now if not in export mode
-  if (!staticMode && !raw) {
-    await commands.calculateCmd.generate();
-  }
+    let asciidocContent = '';
+    try {
+      asciidocContent = await evaluateMacros(
+        cardDetailsResponse.content || '',
+        {
+          context: staticMode ? 'exportedSite' : 'localApp',
+          mode: staticMode ? 'staticSite' : 'inject',
+          project: commands.project,
+          cardKey: key,
+        },
+      );
+    } catch (error) {
+      asciidocContent = `Macro error: ${error instanceof Error ? error.message : 'Unknown error'}\n\n${asciidocContent}`;
+    }
 
-  let asciidocContent = '';
-  try {
-    asciidocContent = await evaluateMacros(cardDetailsResponse.content || '', {
-      context: staticMode ? 'exportedSite' : 'localApp',
-      mode: staticMode ? 'staticSite' : 'inject',
-      project: commands.project,
-      cardKey: key,
-    });
-  } catch (error) {
-    asciidocContent = `Macro error: ${error instanceof Error ? error.message : 'Unknown error'}\n\n${asciidocContent}`;
-  }
+    const htmlContent = Processor()
+      .convert(asciidocContent, {
+        safe: 'safe',
+        attributes: {
+          imagesdir: `/api/cards/${key}/a`,
+          icons: 'font',
+        },
+      })
+      .toString();
 
-  const htmlContent = Processor()
-    .convert(asciidocContent, {
-      safe: 'safe',
-      attributes: {
-        imagesdir: `/api/cards/${key}/a`,
-        icons: 'font',
-      },
-    })
-    .toString();
+    if (raw) {
+      if (!cardDetailsResponse.metadata) {
+        throw new Error('Card has no metadata');
+      }
+      const cardType = await commands.showCmd.showResource(
+        cardDetailsResponse.metadata.cardType,
+        'cardTypes',
+      );
 
-  if (raw) {
-    if (!cardDetailsResponse.metadata) {
-      throw new Error('Card has no metadata');
+      const fields = [];
+      let i = 0;
+      for (const customField of cardType.customFields) {
+        const fieldType = await commands.showCmd.showResource(
+          customField.name,
+          'fieldTypes',
+        );
+        fields.push({
+          key: customField.name,
+          visibility: 'always',
+          index: i++,
+          fieldDisplayName: fieldType.displayName,
+          fieldDescription: fieldType.description,
+          dataType: fieldType.dataType,
+          isCalculated: customField.isCalculated,
+          value: cardDetailsResponse.metadata[customField.name],
+          enumValues: fieldType.enumValues ?? [],
+        });
+      }
+      return {
+        status: 200,
+        data: {
+          key: cardDetailsResponse.key,
+          rank: cardDetailsResponse.metadata?.rank,
+          title: cardDetailsResponse.metadata?.title || '',
+          cardType: cardDetailsResponse.metadata?.cardType || '',
+          cardTypeDisplayName: cardDetailsResponse.metadata.cardType,
+          workflowState: '',
+          lastUpdated: cardDetailsResponse.metadata.lastUpdated,
+          createdAt: cardDetailsResponse.metadata.createdAt,
+          fields,
+          labels: cardDetailsResponse.metadata?.labels || [],
+          links: [],
+          notifications: [],
+          policyChecks: {
+            successes: [],
+            failures: [],
+          },
+          deniedOperations: {
+            transition: [],
+            move: [],
+            delete: [],
+            editField: [],
+            editContent: [],
+          },
+          rawContent: cardDetailsResponse.content || '',
+          parsedContent: htmlContent,
+          attachments: cardDetailsResponse.attachments,
+        },
+      };
     }
-    const cardType = await commands.showCmd.showResource(
-      cardDetailsResponse.metadata.cardType,
-      'cardTypes',
-    );
 
-    const fields = [];
-    let i = 0;
-    for (const customField of cardType.customFields) {
-      const fieldType = await commands.showCmd.showResource(
-        customField.name,
-        'fieldTypes',
-      );
-      fields.push({
-        key: customField.name,
-        visibility: 'always',
-        index: i++,
-        fieldDisplayName: fieldType.displayName,
-        fieldDescription: fieldType.description,
-        dataType: fieldType.dataType,
-        isCalculated: customField.isCalculated,
-        value: cardDetailsResponse.metadata[customField.name],
-        enumValues: fieldType.enumValues ?? [],
-      });
+    const card = staticMode
+      ? await getCardQueryResult(commands, key)
+      : await commands.calculateCmd.runQuery('card', 'localApp', {
+          cardKey: key,
+        });
+
+    if (card.length !== 1) {
+      throw new Error('Query failed. Check card-query syntax');
     }
+
     return {
       status: 200,
       data: {
-        key: cardDetailsResponse.key,
-        rank: cardDetailsResponse.metadata?.rank,
-        title: cardDetailsResponse.metadata?.title || '',
-        cardType: cardDetailsResponse.metadata?.cardType || '',
-        cardTypeDisplayName: cardDetailsResponse.metadata.cardType,
-        workflowState: '',
-        lastUpdated: cardDetailsResponse.metadata.lastUpdated,
-        fields,
-        labels: cardDetailsResponse.metadata?.labels || [],
-        links: [],
-        notifications: [],
-        policyChecks: {
-          successes: [],
-          failures: [],
-        },
-        deniedOperations: {
-          transition: [],
-          move: [],
-          delete: [],
-          editField: [],
-          editContent: [],
-        },
+        ...card[0],
         rawContent: cardDetailsResponse.content || '',
         parsedContent: htmlContent,
         attachments: cardDetailsResponse.attachments,
       },
     };
-  }
-
-  const card = staticMode
-    ? await getCardQueryResult(commands.project.basePath, key)
-    : await commands.calculateCmd.runQuery('card', 'localApp', {
-        cardKey: key,
-      });
-  if (card.length !== 1) {
-    throw new Error('Query failed. Check card-query syntax');
-  }
-
-  return {
-    status: 200,
-    data: {
-      ...card[0],
-      rawContent: cardDetailsResponse.content || '',
-      parsedContent: htmlContent,
-      attachments: cardDetailsResponse.attachments,
-    },
-  };
+  });
 }
 /**
  * Returns all cards from a tree query, flattened.

package/src/domain/cards/presence.ts

@@ -0,0 +1,124 @@
+/**
+  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/>.
+*/
+
+import type { UserInfo } from '../../types.js';
+import type { SSEMessage } from 'hono/streaming';
+
+export interface PresenceEntry {
+  userId: string;
+  userName: string;
+  mode: 'viewing' | 'editing';
+}
+
+interface Connection {
+  user: UserInfo;
+  mode: 'viewing' | 'editing';
+  send: (message: SSEMessage) => void;
+}
+
+/**
+ * In-memory presence tracker for card editing/viewing.
+ * Tracks which users are currently looking at or editing each card,
+ * and notifies all connected clients via SSE when presence changes.
+ */
+class PresenceStore {
+  // cardKey -> connectionId -> Connection
+  private connections = new Map<string, Map<string, Connection>>();
+  private nextId = 0;
+
+  /**
+   * Add a user connection for a card. Returns a connection ID for later removal.
+   */
+  add(
+    cardKey: string,
+    user: UserInfo,
+    mode: 'viewing' | 'editing',
+    send: (message: SSEMessage) => void,
+  ): string {
+    const connId = String(this.nextId++);
+
+    if (!this.connections.has(cardKey)) {
+      this.connections.set(cardKey, new Map());
+    }
+
+    this.connections.get(cardKey)!.set(connId, { user, mode, send });
+    this.broadcast(cardKey);
+
+    return connId;
+  }
+
+  /**
+   * Remove a connection and broadcast updated presence.
+   */
+  remove(cardKey: string, connId: string): void {
+    const cardConns = this.connections.get(cardKey);
+    if (!cardConns) return;
+
+    cardConns.delete(connId);
+
+    if (cardConns.size === 0) {
+      this.connections.delete(cardKey);
+    } else {
+      this.broadcast(cardKey);
+    }
+  }
+
+  /**
+   * Get current presence list for a card.
+   */
+  getPresence(cardKey: string): PresenceEntry[] {
+    const cardConns = this.connections.get(cardKey);
+    if (!cardConns) return [];
+
+    // Deduplicate by userId — if a user has multiple connections,
+    // prefer the 'editing' mode
+    const byUser = new Map<string, PresenceEntry>();
+    for (const conn of cardConns.values()) {
+      const existing = byUser.get(conn.user.id);
+      if (!existing || conn.mode === 'editing') {
+        byUser.set(conn.user.id, {
+          userId: conn.user.id,
+          userName: conn.user.name,
+          mode: conn.mode,
+        });
+      }
+    }
+
+    return Array.from(byUser.values());
+  }
+
+  /**
+   * Broadcast current presence to all connected clients for a card.
+   */
+  private broadcast(cardKey: string): void {
+    const cardConns = this.connections.get(cardKey);
+    if (!cardConns) return;
+
+    const presence = this.getPresence(cardKey);
+    const data = JSON.stringify({ editors: presence });
+    const message: SSEMessage = { event: 'presence', data };
+
+    for (const conn of cardConns.values()) {
+      conn.send(message);
+    }
+  }
+
+  /**
+   * Remove all connections. Intended for test cleanup.
+   */
+  removeAll(): void {
+    this.connections.clear();
+  }
+}
+
+export const presenceStore = new PresenceStore();

package/src/domain/cards/schema.ts

@@ -0,0 +1,41 @@
+/**
+  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/>.
+*/
+
+import { z } from 'zod';
+
+const linkDirection = z.enum(['outbound', 'inbound']);
+
+export const createLinkSchema = z.object({
+  toCard: z.string(),
+  linkType: z.string(),
+  direction: linkDirection.default('outbound'),
+  description: z.string().optional(),
+});
+
+export const removeLinkSchema = z.object({
+  toCard: z.string(),
+  linkType: z.string(),
+  direction: linkDirection.default('outbound'),
+  description: z.string().optional(),
+});
+
+export const updateLinkSchema = z.object({
+  toCard: z.string(),
+  linkType: z.string(),
+  direction: linkDirection,
+  description: z.string().optional(),
+  previousToCard: z.string(),
+  previousLinkType: z.string(),
+  previousDirection: linkDirection,
+  previousDescription: z.string().optional(),
+});

package/src/domain/cards/service.ts

@@ -13,29 +13,32 @@
 
 import Processor from '@asciidoctor/core';
 import { type 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 { allCards } from './lib.js';
 import type { TreeOptions } from '../../types.js';
 
 export async function getProjectInfo(commands: CommandManager) {
-  const projectResponse = await commands.showCmd.showProject();
+  return commands.consistent(async () => {
+    const projectResponse = await commands.showCmd.showProject();
 
-  const workflowsResponse = await commands.showCmd.showWorkflowsWithDetails();
-  if (!workflowsResponse) {
-    throw new Error('No workflows found');
-  }
+    const workflowsResponse = await commands.showCmd.showWorkflowsWithDetails();
+    if (!workflowsResponse) {
+      throw new Error('No workflows found');
+    }
 
-  const cardTypesResponse = await commands.showCmd.showCardTypesWithDetails();
-  if (!cardTypesResponse) {
-    throw new Error('No card types found');
-  }
+    const cardTypesResponse = await commands.showCmd.showCardTypesWithDetails();
+    if (!cardTypesResponse) {
+      throw new Error('No card types found');
+    }
 
-  return {
-    name: projectResponse.name,
-    prefix: projectResponse.prefix,
-    workflows: workflowsResponse,
-    cardTypes: cardTypesResponse,
-  };
+    return {
+      name: projectResponse.name,
+      prefix: projectResponse.prefix,
+      workflows: workflowsResponse,
+      cardTypes: cardTypesResponse,
+    };
+  });
 }
 
 export async function updateCard(
@@ -44,54 +47,31 @@ export async function updateCard(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   body: any,
 ) {
-  const errors = [];
-
-  if (body.state) {
-    try {
+  await commands.atomic(async () => {
+    if (body.state) {
       await commands.transitionCmd.cardTransition(key, body.state);
-    } catch (error) {
-      if (error instanceof Error) errors.push(error.message);
     }
-  }
-
-  if (body.content != null) {
-    try {
+    if (body.content != null) {
       await commands.editCmd.editCardContent(key, body.content);
-    } catch (error) {
-      if (error instanceof Error) errors.push(error.message);
     }
-  }
-
-  if (body.metadata) {
-    for (const [metadataKey, metadataValue] of Object.entries(body.metadata)) {
-      const value = metadataValue as MetadataContent;
-
-      try {
-        await commands.editCmd.editCardMetadata(key, metadataKey, value);
-      } catch (error) {
-        if (error instanceof Error) errors.push(error.message);
+    if (body.metadata) {
+      for (const [metadataKey, metadataValue] of Object.entries(
+        body.metadata,
+      )) {
+        await commands.editCmd.editCardMetadata(
+          key,
+          metadataKey,
+          metadataValue as MetadataContent,
+        );
       }
     }
-  }
-
-  if (body.parent) {
-    try {
+    if (body.parent) {
       await commands.moveCmd.moveCard(key, body.parent);
-    } catch (error) {
-      if (error instanceof Error) errors.push(error.message);
     }
-  }
-  if (body.index != null) {
-    try {
+    if (body.index != null) {
       await commands.moveCmd.rankByIndex(key, body.index);
-    } catch (error) {
-      if (error instanceof Error) errors.push(error.message);
     }
-  }
-
-  if (errors.length > 0) {
-    throw new Error(errors.join('\n'));
-  }
+  }, `Update card ${key}`);
 }
 
 export async function deleteCard(commands: CommandManager, key: string) {
@@ -119,18 +99,20 @@ export async function uploadAttachments(
   key: string,
   files: File[],
 ) {
-  const succeeded = [];
-  for (const file of files) {
-    if (file instanceof File) {
-      const buffer = await file.arrayBuffer();
-      await commands.createCmd.createAttachment(
-        key,
-        file.name,
-        Buffer.from(buffer),
-      );
-      succeeded.push(file.name);
+  const succeeded: string[] = [];
+  await commands.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),
+        );
+        succeeded.push(file.name);
+      }
     }
-  }
+  }, `Add attachments to ${key}`);
 
   return {
     message: 'Attachments uploaded successfully',
@@ -161,59 +143,122 @@ export async function parseContent(
   key: string,
   content: string,
 ) {
-  let asciidocContent = '';
-  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}`;
-  }
+  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}`;
+    }
+
+    const processor = Processor();
+    const parsedContent = processor
+      .convert(asciidocContent, {
+        safe: 'safe',
+        attributes: {
+          imagesdir: `/api/cards/${key}/a`,
+          icons: 'font',
+        },
+      })
+      .toString();
 
-  const processor = Processor();
-  const parsedContent = processor
-    .convert(asciidocContent, {
-      safe: 'safe',
-      attributes: {
-        imagesdir: `/api/cards/${key}/a`,
-        icons: 'font',
-      },
-    })
-    .toString();
-
-  return { parsedContent };
+    return { parsedContent };
+  });
 }
 
 export async function createLink(
   commands: CommandManager,
   key: string,
-  toCard: string,
+  target: string,
   linkType: string,
+  direction: 'outbound' | 'inbound' = 'outbound',
   description?: string,
 ) {
-  await commands.createCmd.createLink(key, toCard, linkType, description);
+  // For outbound: key is source, target is destination
+  // For inbound: target is source, key is destination
+  const source = direction === 'outbound' ? key : target;
+  const destination = direction === 'outbound' ? target : key;
+
+  await commands.createCmd.createLink(
+    source,
+    destination,
+    linkType,
+    description,
+    direction,
+  );
+
   return { message: 'Link created successfully' };
 }
 
 export async function removeLink(
   commands: CommandManager,
   key: string,
-  toCard: string,
+  target: string,
   linkType: string,
+  direction: 'outbound' | 'inbound' = 'outbound',
   description?: string,
 ) {
-  await commands.removeCmd.remove('link', key, toCard, linkType, description);
+  // For outbound: key is source, target is destination
+  // 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,
+  );
   return { message: 'Link removed successfully' };
 }
 
-export function getAttachment(
+export async function updateLink(
   commands: CommandManager,
   key: string,
-  filename: string,
+  toCard: string,
+  linkType: string,
+  direction: 'outbound' | 'inbound',
+  previousToCard: string,
+  previousLinkType: string,
+  previousDirection: 'outbound' | 'inbound',
+  linkDescription?: string,
+  previousLinkDescription?: string,
 ) {
+  // 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,
+    );
+
+    await removeLink(
+      commands,
+      key,
+      previousToCard,
+      previousLinkType,
+      previousDirection,
+      previousLinkDescription,
+    );
+
+    return { message: 'Link updated successfully' };
+  }, `Update link on ${key} to ${toCard}`);
+}
+
+export async function getAttachment(
+  commands: CommandManager,
+  key: string,
+  filename: string,
+): Promise<attachmentPayload> {
   return commands.showCmd.showAttachment(key, filename);
 }