@cyberismo/backend 1.2.0 → 1.3.0

package/src/domain/cards/index.ts

@@ -1,19 +1,7 @@
-/**
-  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 Context, Hono } from 'hono';
-import type { ContentfulStatusCode } from 'hono/utils/http-status';
-import { getCardDetails } from './lib.js';
 import * as cardService from './service.js';
 import { isSSGContext, ssgParams } from 'hono/ssg';
 import type { AppContext } from '../../types.js';
@@ -21,19 +9,17 @@ import { UserRole } from '../../types.js';
 import { requireRole } from '../../middleware/auth.js';
 import { zValidator } from '../../middleware/zvalidator.js';
 import {
+  cardKeyParamSchema,
   createLinkSchema,
   removeLinkSchema,
   updateLinkSchema,
   exportCardPdfSchema,
+  cardBatchSchema,
   type ExportCardPdfRequestBody,
 } from './schema.js';
 
 const router = new Hono();
 
-function notifyCardsUpdated(c: Context, keys: string[]) {
-  c.get('events').cardsUpdated(keys, c.get('user'));
-}
-
 /**
  * @swagger
  * /api/cards:
@@ -49,10 +35,10 @@ function notifyCardsUpdated(c: Context, keys: string[]) {
  *         description: project_path not set.
  */
 router.get('/', requireRole(UserRole.Reader), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
 
   try {
-    const response = await cardService.getProjectInfo(commands);
+    const response = await cardService.getProjectInfo(ws);
     return c.json(response);
   } catch (error) {
     return c.text(
@@ -104,10 +90,10 @@ router.post(
   requireRole(UserRole.Reader),
   zValidator('json', exportCardPdfSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const body = (await c.req.json()) as ExportCardPdfRequestBody;
     try {
-      const result = await cardService.exportCard(commands, {
+      const result = await cardService.exportCard(ws, {
         cardKey: body.cardKey,
         title: body.title,
         name: body.name,
@@ -133,64 +119,140 @@ router.post(
   },
 );
 
+/**
+ * @swagger
+ * /api/cards/batch:
+ *   post:
+ *     summary: Returns the card query results of many cards in one solve.
+ *     description: Keys the project does not hold are left out of the response. Not served on the static site.
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               keys:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 minItems: 1
+ *                 maxItems: 100
+ *     responses:
+ *       200:
+ *         description: Object of card key to QueryResult<'card'>.
+ *       400:
+ *         description: Missing keys or more than 100 keys.
+ */
+router.post(
+  '/batch',
+  requireRole(UserRole.Reader),
+  zValidator('json', cardBatchSchema),
+  async (c) => {
+    const { keys } = c.req.valid('json');
+    return c.json(await cardService.getCardBatch(c.get('ws'), keys));
+  },
+);
+
+const cardKeyParams = ssgParams(async (c: AppContext) => {
+  const ws = c.get('ws');
+  const opts = c.get('tree');
+  const cards = await cardService.findAllCards(ws, opts);
+  return cards.map((card) => ({ key: card.key }));
+});
+
 /**
  * @swagger
  * /api/cards/{key}:
  *   get:
- *     summary: Returns the full content of a specific card including calculations.
- *     description: The key parameter is the unique identifier ("cardKey") of the card. The response includes the content as asciidoc(editable) and parsed html, which also has macros already injected
+ *     summary: Returns the card query result of a specific card.
+ *     description: The key parameter is the unique identifier ("cardKey") of the card. The response holds the calculated card data only; use /content for the rendered content and /source for the stored card.
  *     parameters:
  *       - name: key
  *         in: path
  *         required: true
  *         description: Card key (string)
- *       - name: raw
- *         in: query
- *         required: false
- *         schema:
- *           type: boolean
- *         description: When true, returns the raw card data without triggering calculations
  *     responses:
  *       200:
- *         description: Object containing card details. See lib/api/types.ts/CardResponse for the structure.
+ *         description: The card query result. See QueryResult<'card'> in @cyberismo/model.
  *       400:
- *        description: No search key or card not found with given key
+ *        description: No search key
+ *       404:
+ *        description: Card not found with given key
  *       500:
  *         description: project_path not set.
  */
 router.get(
   '/:key',
   requireRole(UserRole.Reader),
-  ssgParams(async (c: AppContext) => {
-    const commands = c.get('commands');
-    const opts = c.get('tree');
-    const cards = await cardService.findAllCards(commands, opts);
-    return cards.map((card) => ({ key: card.key }));
-  }),
+  cardKeyParams,
+  zValidator('param', cardKeyParamSchema),
   async (c) => {
-    const key = c.req.param('key');
-    if (!key) {
-      return c.text('No search key', 400);
-    }
+    const { key } = c.req.valid('param');
+    return c.json(
+      await cardService.getCardData(c.get('ws'), key, isSSGContext(c)),
+    );
+  },
+);
 
-    const raw = c.req.query('raw');
+/**
+ * @swagger
+ * /api/cards/{key}/content:
+ *   get:
+ *     summary: Returns the content of a specific card as AsciiDoc with its macros evaluated.
+ *     parameters:
+ *       - name: key
+ *         in: path
+ *         required: true
+ *         description: Card key (string)
+ *     responses:
+ *       200:
+ *         description: Object with adocContent.
+ *       400:
+ *        description: No search key
+ *       404:
+ *        description: Card not found with given key
+ */
+router.get(
+  '/:key/content',
+  requireRole(UserRole.Reader),
+  cardKeyParams,
+  zValidator('param', cardKeyParamSchema),
+  async (c) => {
+    const { key } = c.req.valid('param');
+    return c.json(
+      await cardService.getCardContent(c.get('ws'), key, isSSGContext(c)),
+    );
+  },
+);
 
-    const result = await getCardDetails(
-      c.get('commands'),
-      key,
-      isSSGContext(c),
-      raw?.toLowerCase() === 'true' ? true : false,
+/**
+ * @swagger
+ * /api/cards/{key}/source:
+ *   get:
+ *     summary: Returns a specific card as stored, with its unevaluated content, metadata and attachments.
+ *     parameters:
+ *       - name: key
+ *         in: path
+ *         required: true
+ *         description: Card key (string)
+ *     responses:
+ *       200:
+ *         description: The stored card. See Card in @cyberismo/model.
+ *       400:
+ *        description: No search key
+ *       404:
+ *        description: Card not found with given key
+ */
+router.get(
+  '/:key/source',
+  requireRole(UserRole.Reader),
+  cardKeyParams,
+  zValidator('param', cardKeyParamSchema),
+  async (c) => {
+    const { key } = c.req.valid('param');
+    return c.json(
+      await cardService.getCardSource(c.get('ws'), key, isSSGContext(c)),
     );
-    if (result.status === 200) {
-      return c.json(result.data);
-    } else {
-      return c.json(
-        {
-          error: result.message || 'Unknown error',
-        },
-        result.status as ContentfulStatusCode,
-      );
-    }
   },
 );
 
@@ -213,16 +275,10 @@ router.get(
  *         in: body
  *         type: object
  *         required: false
- *         description: New metadata for the card. Must be an object with key-value pairs.
- *       - name: raw
- *         in: query
- *         required: false
- *         schema:
- *           type: boolean
- *         description: When true, returns the raw card data without triggering calculations
+ *         description: New metadata for the card. Must be an object with key-value pairs. Setting a custom field to null or an empty string clears it.
  *     responses:
  *       200:
- *         description: Object containing card details, same as GET. See definitions.ts/CardDetails for the structure.
+ *         description: The updated card query result, same as GET.
  *       207:
  *         description: Partial success. some updates failed, some succeeded. Returns card object with successful updates.
  *       400:
@@ -230,44 +286,27 @@ router.get(
  *       500:
  *         description: project_path not set.
  */
-router.patch('/:key', requireRole(UserRole.Editor), async (c) => {
-  const commands = c.get('commands');
-  const key = c.req.param('key');
-  if (!key) {
-    return c.text('No search key', 400);
-  }
-
-  const raw = c.req.query('raw');
+router.patch(
+  '/:key',
+  requireRole(UserRole.Editor),
+  zValidator('param', cardKeyParamSchema),
+  async (c) => {
+    const ws = c.get('ws');
+    const { key } = c.req.valid('param');
 
-  const body = await c.req.json();
+    const body = await c.req.json();
 
-  try {
-    if (await cardService.updateCard(commands, key, body)) {
-      notifyCardsUpdated(c, [key]);
-    }
-    const result = await getCardDetails(
-      c.get('commands'),
-      key,
-      isSSGContext(c),
-      raw?.toLowerCase() === 'true' ? true : false,
-    );
-    if (result.status === 200) {
-      return c.json(result.data);
-    } else {
-      return c.json(
-        {
-          error: result.message || 'Unknown error',
-        },
-        result.status as ContentfulStatusCode,
+    try {
+      await cardService.updateCard(ws, key, body);
+      return c.json(await cardService.getCardData(ws, key, isSSGContext(c)));
+    } catch (error) {
+      return c.text(
+        error instanceof Error ? error.message : 'Unknown error',
+        400,
       );
     }
-  } catch (error) {
-    return c.text(
-      error instanceof Error ? error.message : 'Unknown error',
-      400,
-    );
-  }
-});
+  },
+);
 
 /**
  * @swagger
@@ -290,14 +329,14 @@ router.patch('/:key', requireRole(UserRole.Editor), async (c) => {
  *         description: project_path not set.
  */
 router.delete('/:key', requireRole(UserRole.Editor), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
   const key = c.req.param('key');
   if (!key) {
     return c.text('No search key', 400);
   }
 
   try {
-    await cardService.deleteCard(commands, key);
+    await cardService.deleteCard(ws, key);
     return new Response(null, { status: 204 });
   } catch (error) {
     return c.json(
@@ -345,7 +384,7 @@ router.post('/:key', requireRole(UserRole.Editor), async (c) => {
 
   try {
     const result = await cardService.createCard(
-      c.get('commands'),
+      c.get('ws'),
       body.template,
       key,
     );
@@ -389,7 +428,7 @@ router.post('/:key', requireRole(UserRole.Editor), async (c) => {
  *         description: Server error
  */
 router.post('/:key/attachments', requireRole(UserRole.Editor), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
   const key = c.req.param('key');
 
   try {
@@ -400,11 +439,10 @@ router.post('/:key/attachments', requireRole(UserRole.Editor), async (c) => {
     }
 
     const result = await cardService.uploadAttachments(
-      commands,
+      ws,
       key,
       files as File[],
     );
-    notifyCardsUpdated(c, [key]);
     return c.json(result);
   } catch (error) {
     return c.json(
@@ -447,16 +485,11 @@ router.delete(
   '/:key/attachments/:filename',
   requireRole(UserRole.Editor),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const { key, filename } = c.req.param();
 
     try {
-      const result = await cardService.removeAttachment(
-        commands,
-        key,
-        filename,
-      );
-      notifyCardsUpdated(c, [key]);
+      const result = await cardService.removeAttachment(ws, key, filename);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -500,7 +533,7 @@ router.delete(
  *         description: Server error
  */
 router.post('/:key/parse', requireRole(UserRole.Reader), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
   const key = c.req.param('key');
   const { content } = await c.req.json();
 
@@ -509,7 +542,7 @@ router.post('/:key/parse', requireRole(UserRole.Reader), async (c) => {
   }
 
   try {
-    const result = await cardService.parseContent(commands, key, content);
+    const result = await cardService.parseContent(ws, key, content);
     return c.json(result);
   } catch (error) {
     return c.json(
@@ -558,20 +591,19 @@ router.post(
   requireRole(UserRole.Editor),
   zValidator('json', createLinkSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const key = c.req.param('key');
     const { toCard, linkType, description, direction } = c.req.valid('json');
 
     try {
       const result = await cardService.createLink(
-        commands,
+        ws,
         key,
         toCard,
         linkType,
         direction,
         description,
       );
-      notifyCardsUpdated(c, [key, toCard]);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -621,20 +653,19 @@ router.delete(
   requireRole(UserRole.Editor),
   zValidator('json', removeLinkSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const key = c.req.param('key');
     const { toCard, linkType, description, direction } = c.req.valid('json');
 
     try {
       const result = await cardService.removeLink(
-        commands,
+        ws,
         key,
         toCard,
         linkType,
         direction,
         description,
       );
-      notifyCardsUpdated(c, [key, toCard]);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -694,7 +725,7 @@ router.put(
   requireRole(UserRole.Editor),
   zValidator('json', updateLinkSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const key = c.req.param('key');
 
     const {
@@ -710,7 +741,7 @@ router.put(
 
     try {
       const result = await cardService.updateLink(
-        commands,
+        ws,
         key,
         toCard,
         linkType,
@@ -721,7 +752,6 @@ router.put(
         description,
         previousDescription,
       );
-      notifyCardsUpdated(c, [key, toCard, previousToCard]);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -763,11 +793,11 @@ router.get(
   '/:key/a/:attachment',
   requireRole(UserRole.Reader),
   ssgParams(async (c: Context) => {
-    const commands = c.get('commands');
-    return await cardService.findRelevantAttachments(commands, c.get('tree'));
+    const ws = c.get('ws');
+    return await cardService.findRelevantAttachments(ws, c.get('tree'));
   }),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const { key, attachment } = c.req.param();
     const filename = decodeURI(attachment);
 
@@ -777,7 +807,7 @@ router.get(
 
     try {
       const attachmentResponse = await cardService.getAttachment(
-        commands,
+        ws,
         key,
         filename,
       );

package/src/domain/cards/lib.ts

@@ -1,176 +1,24 @@
-/**
-  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 { Card } from '@cyberismo/data-handler/interfaces/project-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';
-import { getCardQueryResult } from '../../export.js';
+import type { QueryResult } from '@cyberismo/model';
+import type { Workspace } from '@cyberismo/data-handler';
 import type { TreeOptions } from '../../types.js';
-import type { QueryResult } from '@cyberismo/data-handler/types/queries';
-
-interface result {
-  status: number;
-  message?: string;
-  data?: object;
-}
-
-export async function getCardDetails(
-  commands: CommandManager,
-  key: string,
-  staticMode: boolean,
-  raw: boolean,
-): Promise<result> {
-  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` };
-    }
-
-    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}`;
-    }
-
-    // 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,
-      staticMode ? 'staticSite' : 'inject',
-    );
+/** Routes exported per card: data, content and source. */
+export const CARD_ROUTES_PER_KEY = 3;
 
-    if (raw) {
-      if (!cardDetailsResponse.metadata) {
-        throw new Error('Card has no metadata');
-      }
-      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,
-          isOverridable: !!(
-            customField.isCalculated && customField.enableOverride
-          ),
-          overrideValue:
-            customField.isCalculated && customField.enableOverride
-              ? cardDetailsResponse.metadata[customField.name]
-              : undefined,
-          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 || '',
-          adocContent: asciidocContent,
-          attachments: cardDetailsResponse.attachments,
-          path: cardDetailsResponse.path,
-        },
-      };
-    }
-
-    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: {
-        ...card[0],
-        rawContent: cardDetailsResponse.content || '',
-        adocContent: asciidocContent,
-        attachments: cardDetailsResponse.attachments,
-        path: cardDetailsResponse.path,
-      },
-    };
-  });
-}
 /**
  * Returns all cards from a tree query, flattened.
- * @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 a promise that resolves to an array of all cards
  */
 export async function allCards(
-  commands: CommandManager,
+  ws: Workspace,
   options?: TreeOptions,
 ): Promise<QueryResult<'tree'>[]> {
-  const fetchedCards = await commands.calculateCmd.runQuery(
+  const fetchedCards = await ws.queries.runQuery(
     'tree',
     'exportedSite',
     options || {},