@cyberismo/backend 0.0.21 → 0.0.22

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,30 +143,32 @@ 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();
-
-  return { parsedContent };
+    const processor = Processor();
+    const parsedContent = processor
+      .convert(asciidocContent, {
+        safe: 'safe',
+        attributes: {
+          imagesdir: `/api/cards/${key}/a`,
+          icons: 'font',
+        },
+      })
+      .toString();
+
+    return { parsedContent };
+  });
 }
 
 export async function createLink(
@@ -209,11 +193,11 @@ export async function removeLink(
   return { message: 'Link removed successfully' };
 }
 
-export function getAttachment(
+export async function getAttachment(
   commands: CommandManager,
   key: string,
   filename: string,
-) {
+): Promise<attachmentPayload> {
   return commands.showCmd.showAttachment(key, filename);
 }
 

package/src/domain/fieldTypes/index.ts

@@ -15,6 +15,8 @@ import { Hono } from 'hono';
 import * as fieldTypeService from './service.js';
 import { createFieldTypeSchema } from './schema.js';
 import { zValidator } from '../../middleware/zvalidator.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
 
 const router = new Hono();
 
@@ -32,7 +34,7 @@ const router = new Hono();
  *       500:
  *         description: project_path not set or other internal error
  */
-router.get('/', async (c) => {
+router.get('/', requireRole(UserRole.Reader), async (c) => {
   const commands = c.get('commands');
 
   try {
@@ -77,21 +79,26 @@ router.get('/', async (c) => {
  *       500:
  *         description: Server error
  */
-router.post('/', zValidator('json', createFieldTypeSchema), async (c) => {
-  const commands = c.get('commands');
-  const { identifier, dataType } = c.req.valid('json');
+router.post(
+  '/',
+  requireRole(UserRole.Admin),
+  zValidator('json', createFieldTypeSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { identifier, dataType } = c.req.valid('json');
 
-  try {
-    await fieldTypeService.createFieldType(commands, identifier, dataType);
-    return c.json({ message: 'Field type created successfully' });
-  } catch (error) {
-    return c.json(
-      {
-        error: `${error instanceof Error ? error.message : 'Unknown error'}`,
-      },
-      500,
-    );
-  }
-});
+    try {
+      await fieldTypeService.createFieldType(commands, identifier, dataType);
+      return c.json({ message: 'Field type created successfully' });
+    } catch (error) {
+      return c.json(
+        {
+          error: `${error instanceof Error ? error.message : 'Unknown error'}`,
+        },
+        500,
+      );
+    }
+  },
+);
 
 export default router;

package/src/domain/graphModels/index.ts

@@ -15,6 +15,8 @@ import { Hono } from 'hono';
 import * as graphModelService from './service.js';
 import { createGraphModelSchema } from './schema.js';
 import { zValidator } from '../../middleware/zvalidator.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
 
 const router = new Hono();
 
@@ -43,12 +45,17 @@ const router = new Hono();
  *       500:
  *         description: Server error
  */
-router.post('/', zValidator('json', createGraphModelSchema), async (c) => {
-  const commands = c.get('commands');
-  const { identifier } = c.req.valid('json');
+router.post(
+  '/',
+  requireRole(UserRole.Admin),
+  zValidator('json', createGraphModelSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { identifier } = c.req.valid('json');
 
-  await graphModelService.createGraphModel(commands, identifier);
-  return c.json({ message: 'Graph model created successfully' });
-});
+    await graphModelService.createGraphModel(commands, identifier);
+    return c.json({ message: 'Graph model created successfully' });
+  },
+);
 
 export default router;

package/src/domain/graphViews/index.ts

@@ -15,6 +15,8 @@ import { Hono } from 'hono';
 import * as graphViewService from './service.js';
 import { createGraphViewSchema } from './schema.js';
 import { zValidator } from '../../middleware/zvalidator.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
 
 const router = new Hono();
 
@@ -43,11 +45,16 @@ const router = new Hono();
  *       500:
  *         description: Server error
  */
-router.post('/', zValidator('json', createGraphViewSchema), async (c) => {
-  const commands = c.get('commands');
-  const { identifier } = c.req.valid('json');
-  await graphViewService.createGraphView(commands, identifier);
-  return c.json({ message: 'Graph view created successfully' });
-});
+router.post(
+  '/',
+  requireRole(UserRole.Admin),
+  zValidator('json', createGraphViewSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { identifier } = c.req.valid('json');
+    await graphViewService.createGraphView(commands, identifier);
+    return c.json({ message: 'Graph view created successfully' });
+  },
+);
 
 export default router;

package/src/domain/labels/index.ts

@@ -13,6 +13,8 @@
 
 import { Hono } from 'hono';
 import * as labelsService from './service.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
 
 const router = new Hono();
 
@@ -27,9 +29,10 @@ const router = new Hono();
  *       500:
  *         description: Internal server error
  */
-router.get('/', (c) => {
+
+router.get('/', requireRole(UserRole.Reader), async (c) => {
   const commands = c.get('commands');
-  const labels = labelsService.getLabels(commands);
+  const labels = await labelsService.getLabels(commands);
   return c.json(labels);
 });
 

package/src/domain/labels/service.ts

@@ -18,6 +18,6 @@ import type { CommandManager } from '@cyberismo/data-handler';
  * @param commands command manager used for the query
  * @returns a list of labels
  */
-export function getLabels(commands: CommandManager): string[] {
-  return commands.showCmd.showLabels().sort();
+export async function getLabels(commands: CommandManager): Promise<string[]> {
+  return (await commands.showCmd.showLabels()).sort();
 }

package/src/domain/linkTypes/index.ts

@@ -15,6 +15,8 @@ import { Hono } from 'hono';
 import * as linkTypeService from './service.js';
 import { createLinkTypeSchema } from './schema.js';
 import { zValidator } from '../../middleware/zvalidator.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
 
 const router = new Hono();
 
@@ -32,7 +34,7 @@ const router = new Hono();
  *       500:
  *         description: project_path not set or other internal error
  */
-router.get('/', async (c) => {
+router.get('/', requireRole(UserRole.Reader), async (c) => {
   const commands = c.get('commands');
 
   try {
@@ -73,12 +75,17 @@ router.get('/', async (c) => {
  *       500:
  *         description: Server error
  */
-router.post('/', zValidator('json', createLinkTypeSchema), async (c) => {
-  const commands = c.get('commands');
-  const { identifier } = c.req.valid('json');
+router.post(
+  '/',
+  requireRole(UserRole.Admin),
+  zValidator('json', createLinkTypeSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { identifier } = c.req.valid('json');
 
-  await linkTypeService.createLinkType(commands, identifier);
-  return c.json({ message: 'Link type created successfully' });
-});
+    await linkTypeService.createLinkType(commands, identifier);
+    return c.json({ message: 'Link type created successfully' });
+  },
+);
 
 export default router;

package/src/domain/logicPrograms/index.ts

@@ -15,11 +15,14 @@ import { Hono } from 'hono';
 import { zValidator } from '../../middleware/zvalidator.js';
 import { resourceParamsWithCard } from '../../common/validationSchemas.js';
 import * as logicProgramService from './service.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
 
 const router = new Hono();
 
 router.get(
   '/:prefix/:type/:identifier',
+  requireRole(UserRole.Reader),
   zValidator('param', resourceParamsWithCard),
   async (c) => {
     const commands = c.get('commands');

package/src/domain/mcp/index.ts

@@ -0,0 +1,159 @@
+/**
+  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 { 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 type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+const MAX_SESSIONS = 100;
+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;
+}
+
+const sessions = new Map<string, McpSession>();
+
+/**
+ * Close and remove a session, shutting down both server and transport.
+ * Safe to call multiple times for the same id.
+ * When `skipTransportClose` is true the transport is already closing
+ * (called from onsessionclosed / onclose callbacks).
+ */
+async function destroySession(
+  id: string,
+  skipTransportClose = false,
+): Promise<void> {
+  const session = sessions.get(id);
+  if (!session) return;
+  sessions.delete(id);
+
+  try {
+    await session.server.close();
+  } catch {
+    // Ignore close errors during cleanup
+  }
+
+  if (!skipTransportClose && session.transport.close) {
+    try {
+      await session.transport.close();
+    } catch {
+      // Ignore close errors during cleanup
+    }
+  }
+}
+
+// Periodic cleanup of expired sessions
+const cleanupInterval = setInterval(() => {
+  const now = Date.now();
+  for (const [id, session] of sessions) {
+    if (now - session.lastActivity > SESSION_TIMEOUT_MS) {
+      void destroySession(id);
+    }
+  }
+}, CLEANUP_INTERVAL_MS);
+cleanupInterval.unref();
+
+const router = new Hono();
+
+/**
+ * MCP HTTP endpoint handler.
+ * Supports GET (SSE streaming), POST (messages), and DELETE (session cleanup).
+ */
+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);
+    }
+    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);
+    }
+  };
+
+  const server = createMcpServer(commands);
+  await server.connect(transport);
+
+  const response = await transport.handleRequest(c.req.raw);
+  return response;
+});
+
+/**
+ * SSE endpoint for server-to-client messages
+ */
+router.get('/sse', async (c) => {
+  const sessionId = c.req.header('mcp-session-id');
+
+  if (!sessionId || !sessions.has(sessionId)) {
+    return c.json({ error: 'Invalid or missing session ID' }, 400);
+  }
+
+  const session = sessions.get(sessionId)!;
+  session.lastActivity = Date.now();
+  const response = await session.transport.handleRequest(c.req.raw);
+  return response;
+});
+
+export default router;

package/src/domain/project/index.ts

@@ -15,25 +15,32 @@ import { Hono } from 'hono';
 import { zValidator } from '../../middleware/zvalidator.js';
 import { moduleParamSchema, updateProjectSchema } from './schema.js';
 import * as projectService from './service.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
 
 const router = new Hono();
 
-router.get('/', async (c) => {
+router.get('/', requireRole(UserRole.Reader), async (c) => {
   const commands = c.get('commands');
 
   const project = await projectService.getProject(commands);
   return c.json(project);
 });
 
-router.patch('/', zValidator('json', updateProjectSchema), async (c) => {
-  const commands = c.get('commands');
-  const updates = c.req.valid('json');
+router.patch(
+  '/',
+  requireRole(UserRole.Admin),
+  zValidator('json', updateProjectSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const updates = c.req.valid('json');
 
-  const project = await projectService.updateProject(commands, updates);
-  return c.json(project);
-});
+    const project = await projectService.updateProject(commands, updates);
+    return c.json(project);
+  },
+);
 
-router.post('/modules/update', async (c) => {
+router.post('/modules/update', requireRole(UserRole.Admin), async (c) => {
   const commands = c.get('commands');
   await projectService.updateAllModules(commands);
   return c.json({ message: 'All modules updated' });
@@ -41,6 +48,7 @@ router.post('/modules/update', async (c) => {
 
 router.post(
   '/modules/:module/update',
+  requireRole(UserRole.Admin),
   zValidator('param', moduleParamSchema),
   async (c) => {
     const commands = c.get('commands');
@@ -52,6 +60,7 @@ router.post(
 
 router.delete(
   '/modules/:module',
+  requireRole(UserRole.Admin),
   zValidator('param', moduleParamSchema),
   async (c) => {
     const commands = c.get('commands');