@cyberismo/backend 0.0.23 → 0.0.25

package/src/domain/cards/index.ts

@@ -26,6 +26,8 @@ import {
   createLinkSchema,
   removeLinkSchema,
   updateLinkSchema,
+  exportCardPdfSchema,
+  type ExportCardPdfRequestBody,
 } from './schema.js';
 
 const router = new Hono();
@@ -58,6 +60,77 @@ router.get('/', requireRole(UserRole.Reader), async (c) => {
   }
 });
 
+/**
+ * @swagger
+ * /api/cards/export-pdf:
+ *   post:
+ *     summary: Export a card as a PDF
+ *     description: Exports the specified card as a PDF
+ *     parameters:
+ *       - name: key
+ *         in: path
+ *         required: true
+ *         description: Card key (string)
+ *    requestBody:
+ *      content:
+ *       application/json:
+ *        schema:
+ *        type: object
+ *       properties:
+ *        title:
+ *         type: string
+ *       description: Title of the exported PDF
+ *       name:
+ *         type: string
+ *       description: Name of the exported PDF
+ *       exportChildCards:
+ *         type: boolean
+ *       description: Whether to export child cards
+ *       version:
+ *         type: string
+ *       description: Version of the exported PDF (optional)
+ *     responses:
+ *       200:
+ *         description: Card exported successfully
+ *       400:
+ *         description: Missing or invalid parameters.
+ *       500:
+ *         description: project_path not set
+ */
+router.post(
+  '/export-pdf',
+  requireRole(UserRole.Reader),
+  zValidator('json', exportCardPdfSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const body = (await c.req.json()) as ExportCardPdfRequestBody;
+    try {
+      const result = await cardService.exportCard(commands, {
+        cardKey: body.cardKey,
+        title: body.title,
+        name: body.name,
+        recursive: body.exportChildCards,
+        version: body.version,
+      });
+      return new Response(result, {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/pdf',
+          'Cache-Control': 'no-store',
+        },
+      });
+    } catch (error) {
+      return c.json(
+        {
+          error:
+            error instanceof Error ? error.message : 'Failed to export card',
+        },
+        500,
+      );
+    }
+  },
+);
+
 /**
  * @swagger
  * /api/cards/{key}:

package/src/domain/cards/lib.ts

@@ -14,6 +14,7 @@
 import Processor from '@asciidoctor/core';
 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 { getCardQueryResult } from '../../export.js';
 import type { TreeOptions } from '../../types.js';
 import type { QueryResult } from '@cyberismo/data-handler/types/queries';
@@ -57,11 +58,15 @@ export async function getCardDetails(
       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);
+
+    const projectPrefix = commands.project.projectPrefix;
     const htmlContent = Processor()
       .convert(asciidocContent, {
         safe: 'safe',
         attributes: {
-          imagesdir: `/api/cards/${key}/a`,
+          imagesdir: `/api/projects/${projectPrefix}/cards/${key}/a`,
           icons: 'font',
         },
       })
@@ -124,6 +129,7 @@ export async function getCardDetails(
           rawContent: cardDetailsResponse.content || '',
           parsedContent: htmlContent,
           attachments: cardDetailsResponse.attachments,
+          path: cardDetailsResponse.path,
         },
       };
     }
@@ -145,6 +151,7 @@ export async function getCardDetails(
         rawContent: cardDetailsResponse.content || '',
         parsedContent: htmlContent,
         attachments: cardDetailsResponse.attachments,
+        path: cardDetailsResponse.path,
       },
     };
   });

package/src/domain/cards/schema.ts

@@ -39,3 +39,12 @@ export const updateLinkSchema = z.object({
   previousDirection: linkDirection,
   previousDescription: z.string().optional(),
 });
+export const exportCardPdfSchema = z.object({
+  title: z.string().min(1),
+  name: z.string().min(1),
+  cardKey: z.string(),
+  exportChildCards: z.boolean(),
+  version: z.string().min(1).optional(),
+});
+
+export type ExportCardPdfRequestBody = z.infer<typeof exportCardPdfSchema>;

package/src/domain/cards/service.ts

@@ -12,9 +12,13 @@
 */
 
 import Processor from '@asciidoctor/core';
-import { type MetadataContent } from '@cyberismo/data-handler/interfaces/project-interfaces';
+import type {
+  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 { allCards } from './lib.js';
 import type { TreeOptions } from '../../types.js';
 
@@ -120,11 +124,19 @@ export async function uploadAttachments(
   };
 }
 
+function validateAttachmentFileName(filename: string): void {
+  const decoded = decodeURIComponent(filename);
+  if (/(^|[/\\])\.\.([/\\]|$)/.test(decoded)) {
+    throw new Error('Invalid attachment filename');
+  }
+}
+
 export async function removeAttachment(
   commands: CommandManager,
   key: string,
   filename: string,
 ) {
+  validateAttachmentFileName(filename);
   await commands.removeCmd.remove('attachment', key, filename);
   return { message: 'Attachment removed successfully' };
 }
@@ -134,6 +146,7 @@ export async function openAttachment(
   key: string,
   filename: string,
 ) {
+  validateAttachmentFileName(filename);
   await commands.showCmd.openAttachment(key, filename);
   return { message: 'Attachment opened successfully' };
 }
@@ -156,12 +169,16 @@ export async function parseContent(
       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);
+
     const processor = Processor();
+    const projectPrefix = commands.project.projectPrefix;
     const parsedContent = processor
       .convert(asciidocContent, {
         safe: 'safe',
         attributes: {
-          imagesdir: `/api/cards/${key}/a`,
+          imagesdir: `/api/projects/${projectPrefix}/cards/${key}/a`,
           icons: 'font',
         },
       })
@@ -259,6 +276,7 @@ export async function getAttachment(
   key: string,
   filename: string,
 ): Promise<attachmentPayload> {
+  validateAttachmentFileName(filename);
   return commands.showCmd.showAttachment(key, filename);
 }
 
@@ -298,3 +316,11 @@ export async function findRelevantAttachments(
       attachment: attachment.fileName,
     }));
 }
+
+export async function exportCard(
+  commands: CommandManager,
+  options: ExportPdfOptions,
+): Promise<Buffer> {
+  const result = await commands.exportCmd.exportPdfBuffer(options);
+  return result;
+}

package/src/domain/mcp/index.ts

@@ -14,19 +14,21 @@
 import { Hono } from 'hono';
 import { randomUUID } from 'node:crypto';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { createMcpServer } from '@cyberismo/mcp/server';
-import type { CommandManager } from '@cyberismo/data-handler';
+import { createMcpServer, type ProjectProvider } from '@cyberismo/mcp';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requireRole } from '../../middleware/auth.js';
+import { UserRole, type AppVars } from '../../types.js';
 
 const MAX_SESSIONS = 100;
+const MAX_SESSIONS_PER_USER = 5;
 const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 
 interface McpSession {
   transport: WebStandardStreamableHTTPServerTransport;
   server: McpServer;
-  commands: CommandManager;
   lastActivity: number;
+  userId: string;
 }
 
 const sessions = new Map<string, McpSession>();
@@ -71,89 +73,92 @@ const cleanupInterval = setInterval(() => {
 }, CLEANUP_INTERVAL_MS);
 cleanupInterval.unref();
 
-const router = new Hono();
-
 /**
- * MCP HTTP endpoint handler.
- * Supports GET (SSE streaming), POST (messages), and DELETE (session cleanup).
+ * Create an MCP HTTP router that serves all projects via the given provider.
  */
-router.all('/', async (c) => {
-  const commands = c.get('commands');
-  const sessionId = c.req.header('mcp-session-id');
-
-  // Handle DELETE before routing to existing session so it always runs cleanup
-  if (c.req.method === 'DELETE') {
-    if (sessionId) {
-      await destroySession(sessionId);
+export function createMcpRouter(
+  provider: ProjectProvider,
+): Hono<{ Variables: AppVars }> {
+  const router = new Hono<{ Variables: AppVars }>();
+
+  /**
+   * MCP HTTP endpoint handler.
+   * Supports POST (messages) and DELETE (session cleanup).
+   */
+  router.all('/', requireRole(UserRole.Editor), async (c) => {
+    const sessionId = c.req.header('mcp-session-id');
+
+    // Handle DELETE before routing to existing session so it always runs cleanup
+    if (c.req.method === 'DELETE') {
+      if (sessionId) {
+        await destroySession(sessionId);
+      }
+      return c.json({ message: 'Session closed' });
     }
-    return c.json({ message: 'Session closed' });
-  }
-
-  // Handle existing session
-  if (sessionId && sessions.has(sessionId)) {
-    const session = sessions.get(sessionId)!;
-    session.lastActivity = Date.now();
-    const response = await session.transport.handleRequest(c.req.raw);
-    return response;
-  }
-
-  // Only allow POST to create new sessions (initialize)
-  if (c.req.method !== 'POST') {
-    return c.json(
-      { error: 'Method not allowed. Use POST to initialize a session.' },
-      405,
-    );
-  }
-
-  // Reject new sessions when at capacity
-  if (sessions.size >= MAX_SESSIONS) {
-    return c.json({ error: 'Too many active sessions' }, 503);
-  }
-
-  // Create new session for initialization
-  const transport = new WebStandardStreamableHTTPServerTransport({
-    sessionIdGenerator: () => randomUUID(),
-    onsessioninitialized: (newSessionId: string) => {
-      sessions.set(newSessionId, {
-        transport,
-        server,
-        commands,
-        lastActivity: Date.now(),
-      });
-    },
-    onsessionclosed: (closedSessionId: string) => {
-      void destroySession(closedSessionId, true);
-    },
-  });
 
-  transport.onclose = () => {
-    const sid = transport.sessionId;
-    if (sid) {
-      void destroySession(sid, true);
+    // Handle existing session
+    if (sessionId && sessions.has(sessionId)) {
+      const session = sessions.get(sessionId)!;
+      session.lastActivity = Date.now();
+      const response = await session.transport.handleRequest(c.req.raw);
+      return response;
     }
-  };
 
-  const server = createMcpServer(commands);
-  await server.connect(transport);
+    // Reject requests with an unknown session ID (e.g. after server restart)
+    if (sessionId) {
+      return c.json({ error: 'Unknown session ID' }, 404);
+    }
 
-  const response = await transport.handleRequest(c.req.raw);
-  return response;
-});
+    // Only allow POST to create new sessions (initialize)
+    if (c.req.method !== 'POST') {
+      return c.json(
+        { error: 'Method not allowed. Use POST to initialize a session.' },
+        405,
+      );
+    }
 
-/**
- * SSE endpoint for server-to-client messages
- */
-router.get('/sse', async (c) => {
-  const sessionId = c.req.header('mcp-session-id');
+    // Reject new sessions when at capacity
+    if (sessions.size >= MAX_SESSIONS) {
+      return c.json({ error: 'Too many active sessions' }, 503);
+    }
 
-  if (!sessionId || !sessions.has(sessionId)) {
-    return c.json({ error: 'Invalid or missing session ID' }, 400);
-  }
+    const user = c.get('user')!;
+    const userSessionCount = [...sessions.values()].filter(
+      (s) => s.userId === user.id,
+    ).length;
+    if (userSessionCount >= MAX_SESSIONS_PER_USER) {
+      return c.json({ error: 'Too many active sessions for this user' }, 503);
+    }
 
-  const session = sessions.get(sessionId)!;
-  session.lastActivity = Date.now();
-  const response = await session.transport.handleRequest(c.req.raw);
-  return response;
-});
+    // Create new session for initialization
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (newSessionId: string) => {
+        sessions.set(newSessionId, {
+          transport,
+          server,
+          lastActivity: Date.now(),
+          userId: user.id,
+        });
+      },
+      onsessionclosed: (closedSessionId: string) => {
+        void destroySession(closedSessionId, true);
+      },
+    });
+
+    transport.onclose = () => {
+      const sid = transport.sessionId;
+      if (sid) {
+        void destroySession(sid, true);
+      }
+    };
+
+    const server = createMcpServer(provider);
+    await server.connect(transport);
+
+    const response = await transport.handleRequest(c.req.raw);
+    return response;
+  });
 
-export default router;
+  return router;
+}

package/src/domain/project/service.ts

@@ -57,7 +57,7 @@ export async function getProject(
     const project = await commands.showCmd.showProject();
     const modules = await commands.showCmd.showModules();
     const moduleDetails = await Promise.all(
-      modules.map((mod) => toModuleInfo(commands, mod)),
+      modules.map((mod) => toModuleInfo(commands, mod.name)),
     );
 
     return {

package/src/domain/projects/index.ts

@@ -0,0 +1,39 @@
+/**
+  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 { Hono } from 'hono';
+import type { ProjectRegistry } from '../../project-registry.js';
+import { requireRole } from '../../middleware/auth.js';
+import { UserRole } from '../../types.js';
+
+export function createProjectsRouter(registry: ProjectRegistry) {
+  const router = new Hono();
+
+  /**
+   * @swagger
+   * /api/projects:
+   *   get:
+   *     summary: List available projects
+   *     description: Returns a list of all available projects
+   *     responses:
+   *       200:
+   *         description: List of projects
+   *       401:
+   *         description: Unauthorized
+   */
+  router.get('/', requireRole(UserRole.Reader), (c) => {
+    return c.json(registry.list());
+  });
+
+  return router;
+}

package/src/domain/resources/index.ts

@@ -20,6 +20,8 @@ import { zValidator } from '../../middleware/zvalidator.js';
 import {
   validateResourceParamsSchema,
   updateOperationBodySchema,
+  workflowGraphParamsSchema,
+  workflowGraphQuerySchema,
 } from './schema.js';
 import { requireRole } from '../../middleware/auth.js';
 
@@ -132,6 +134,78 @@ router.delete(
   },
 );
 
+/**
+ * @swagger
+ * /api/resources/{prefix}/workflows/{identifier}/graph:
+ *   get:
+ *     summary: Render the state-machine graph for a workflow
+ *     description: Returns a base64-encoded sanitized SVG of the workflow's
+ *                  state-machine diagram, rendered with the built-in
+ *                  workflow graph model and view. When the optional `card`
+ *                  query parameter is provided, the diagram highlights
+ *                  that card's current workflowState.
+ *     parameters:
+ *       - in: path
+ *         name: prefix
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - in: path
+ *         name: identifier
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - in: query
+ *         name: card
+ *         required: false
+ *         schema:
+ *           type: string
+ *         description: Card key whose current workflowState should be
+ *                      highlighted in the rendered diagram.
+ *     responses:
+ *       200:
+ *         description: Rendered diagram
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 svg:
+ *                   type: string
+ *                   description: Base64-encoded SVG document.
+ *       400:
+ *         description: Invalid path parameters
+ *       404:
+ *         description: Workflow or card not found
+ *       500:
+ *         description: Server error
+ */
+router.get(
+  '/:prefix/workflows/:identifier/graph',
+  requireRole(UserRole.Reader),
+  zValidator('param', workflowGraphParamsSchema),
+  zValidator('query', workflowGraphQuerySchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { prefix, identifier } = c.req.valid('param');
+    const { card } = c.req.valid('query');
+    const workflowName = `${prefix}/workflows/${identifier}`;
+    try {
+      const svg = await resourceService.getWorkflowGraph(
+        commands,
+        workflowName,
+        card,
+      );
+      return c.json({ svg });
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('not found')) {
+        return c.json({ error: error.message }, 404);
+      }
+      throw error;
+    }
+  },
+);
+
 router.post(
   '/:prefix/:type/:identifier/operation',
   requireRole(UserRole.Admin),

package/src/domain/resources/schema.ts

@@ -1,9 +1,23 @@
 import { z } from 'zod';
 import {
+  identifierSchema,
   resourceParamsSchema,
   resourceTypes,
 } from '../../common/validationSchemas.js';
 
+export const workflowGraphParamsSchema = z.object({
+  prefix: z.string(),
+  identifier: identifierSchema,
+});
+
+export type WorkflowGraphParams = z.infer<typeof workflowGraphParamsSchema>;
+
+export const workflowGraphQuerySchema = z.object({
+  card: z.string().optional(),
+});
+
+export type WorkflowGraphQuery = z.infer<typeof workflowGraphQuerySchema>;
+
 export const resourceFileParamsSchema = resourceParamsSchema.extend({
   file: z.string(),
 });

package/src/domain/resources/service.ts

@@ -42,14 +42,14 @@ const resourceTypes: ResourceFolderType[] = [
 
 async function getModules(commands: CommandManager) {
   try {
-    const moduleNames = await commands.showCmd.showModules();
+    const modules = await commands.showCmd.showModules();
     return Promise.all(
-      moduleNames.map(async (moduleName) => {
+      modules.map(async (mod) => {
         try {
-          const module = await commands.showCmd.showModule(moduleName);
+          const module = await commands.showCmd.showModule(mod.name);
           return { name: module.name, cardKeyPrefix: module.cardKeyPrefix };
         } catch {
-          return { name: moduleName, cardKeyPrefix: moduleName };
+          return { name: mod.name, cardKeyPrefix: mod.name };
         }
       }),
     );
@@ -372,6 +372,7 @@ async function processTemplates(
             'templates',
             template,
             projectPrefix,
+            [],
           ),
         );
       }
@@ -390,6 +391,7 @@ async function processTemplates(
             'templates',
             template,
             projectPrefix,
+            [],
           ),
         );
       }
@@ -467,6 +469,52 @@ export async function validateResource(
   };
 }
 
+/**
+ * Renders the built-in state-machine graph for a single workflow.
+ * When `cardKey` is provided, the card's current workflowState is
+ * highlighted in the diagram. The workflow lookup, card lookup and
+ * graph rendering all run inside the same consistency window so the
+ * highlighted state matches the diagram even if the card is being
+ * transitioned concurrently.
+ * @returns base64-encoded sanitized SVG.
+ * @throws Error with 'not found' in the message when the workflow or
+ *   card cannot be resolved.
+ */
+export async function getWorkflowGraph(
+  commands: CommandManager,
+  workflowName: string,
+  cardKey?: string,
+): Promise<string> {
+  return commands.consistent(async () => {
+    try {
+      await commands.showCmd.showResource(workflowName, 'workflows');
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('does not exist')) {
+        throw new Error(`Workflow '${workflowName}' not found`, {
+          cause: error,
+        });
+      }
+      throw error;
+    }
+    let currentState: string | undefined;
+    if (cardKey) {
+      let card;
+      try {
+        card = await commands.showCmd.showCardDetails(cardKey);
+      } catch (error) {
+        throw new Error(`Card '${cardKey}' not found`, { cause: error });
+      }
+      if (!card?.metadata) {
+        throw new Error(`Card '${cardKey}' not found`);
+      }
+      currentState = card.metadata.workflowState;
+    }
+    return commands.calculateCmd.runWorkflowGraph(workflowName, {
+      currentState,
+    });
+  });
+}
+
 /**
  * Perform an updateOperation on a resource key.
  * This delegates to data-handler Update.applyResourceOperation.