@cyberismo/backend 1.1.2 → 1.2.0

package/src/domain/resources/schema.ts

@@ -5,12 +5,14 @@ import {
   resourceTypes,
 } from '../../common/validationSchemas.js';
 
-export const workflowGraphParamsSchema = z.object({
+export const prefixIdentifierParamsSchema = z.object({
   prefix: z.string(),
   identifier: identifierSchema,
 });
 
-export type WorkflowGraphParams = z.infer<typeof workflowGraphParamsSchema>;
+export type PrefixIdentifierParams = z.infer<
+  typeof prefixIdentifierParamsSchema
+>;
 
 export const workflowGraphQuerySchema = z.object({
   card: z.string().optional(),
@@ -18,6 +20,14 @@ export const workflowGraphQuerySchema = z.object({
 
 export type WorkflowGraphQuery = z.infer<typeof workflowGraphQuerySchema>;
 
+export const skillPreviewBodySchema = z.object({
+  skillContent: z.string().optional(),
+  skillQuery: z.string().optional(),
+  cardKey: z.string().optional(),
+});
+
+export type SkillPreviewBody = z.infer<typeof skillPreviewBodySchema>;
+
 export const resourceFileParamsSchema = resourceParamsSchema.extend({
   file: z.string(),
 });

package/src/domain/resources/service.ts

@@ -26,7 +26,11 @@ import {
   resourceNameToString,
 } from '@cyberismo/data-handler';
 import type { ResourceParams } from '../../common/validationSchemas.js';
-import type { ValidateResourceParams, UpdateOperationBody } from './schema.js';
+import type {
+  SkillPreviewBody,
+  UpdateOperationBody,
+  ValidateResourceParams,
+} from './schema.js';
 
 const resourceTypes: ResourceFolderType[] = [
   'calculations',
@@ -36,17 +40,18 @@ const resourceTypes: ResourceFolderType[] = [
   'graphViews',
   'linkTypes',
   'reports',
+  'skills',
   'templates',
   'workflows',
 ];
 
 async function getModules(commands: CommandManager) {
   try {
-    const modules = await commands.showCmd.showModules();
+    const modules = await commands.modulesCmd.list();
     return Promise.all(
       modules.map(async (mod) => {
         try {
-          const module = await commands.showCmd.showModule(mod.name);
+          const module = await commands.modulesCmd.show(mod.name);
           return { name: module.name, cardKeyPrefix: module.cardKeyPrefix };
         } catch {
           return { name: mod.name, cardKeyPrefix: mod.name };
@@ -530,6 +535,53 @@ export async function getWorkflowGraph(
   });
 }
 
+/**
+ * Renders a skill's instructions for the configuration editor preview.
+ * Unlike the MCP `get_skill` tool, this does not require the skill to be
+ * enabled by the logic programs — the author is still working on it. When
+ * `skillContent` or `skillQuery` is given, that unsaved editor content is
+ * rendered instead of what is stored on disk. The lookups and the rendering
+ * share one consistency window so the preview matches a single project state.
+ * @returns the rendered instructions as markdown.
+ * @throws Error with 'not found' in the message when the skill or card cannot
+ *   be resolved; any other error means the template or query failed to render.
+ */
+export async function previewSkill(
+  commands: CommandManager,
+  skillName: string,
+  body: SkillPreviewBody,
+): Promise<string> {
+  const { cardKey, skillContent, skillQuery } = body;
+  return commands.consistent(async () => {
+    try {
+      await commands.showCmd.showResource(skillName, 'skills');
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('does not exist')) {
+        throw new Error(`Skill '${skillName}' not found`, { cause: error });
+      }
+      throw error;
+    }
+    if (cardKey) {
+      try {
+        await commands.showCmd.showCardDetails(cardKey);
+      } catch (error) {
+        if (
+          error instanceof Error &&
+          error.message.includes('does not exist')
+        ) {
+          throw new Error(`Card '${cardKey}' not found`, { cause: error });
+        }
+        throw error;
+      }
+    }
+    return commands.showCmd.renderSkill(skillName, {
+      cardKey,
+      skillContent,
+      skillQuery,
+    });
+  });
+}
+
 /**
  * Perform an updateOperation on a resource key.
  * This delegates to the data-handler mutation engine.

package/src/domain/skills/index.ts

@@ -0,0 +1,61 @@
+/**
+  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 * as skillService from './service.js';
+import { createSkillSchema } from './schema.js';
+import { zValidator } from '../../middleware/zvalidator.js';
+import { UserRole } from '../../types.js';
+import { requireRole } from '../../middleware/auth.js';
+
+const router = new Hono();
+
+/**
+ * @swagger
+ * /api/skills:
+ *   post:
+ *     summary: Create a new skill
+ *     description: Creates a new skill with the specified identifier
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               identifier:
+ *                 type: string
+ *             required:
+ *               - identifier
+ *     responses:
+ *       200:
+ *         description: Skill created successfully
+ *       400:
+ *         description: Invalid request body
+ *       500:
+ *         description: Server error
+ */
+router.post(
+  '/',
+  requireRole(UserRole.Admin),
+  zValidator('json', createSkillSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { identifier } = c.req.valid('json');
+
+    await skillService.createSkill(commands, identifier);
+    return c.json({ message: 'Skill created successfully' });
+  },
+);
+
+export default router;

package/src/domain/skills/schema.ts

@@ -0,0 +1,19 @@
+/**
+  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';
+import { identifierSchema } from '../../common/validationSchemas.js';
+
+export const createSkillSchema = z.object({
+  identifier: identifierSchema,
+});

package/src/domain/skills/service.ts

@@ -0,0 +1,18 @@
+/**
+  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 { CommandManager } from '@cyberismo/data-handler';
+
+export async function createSkill(commands: CommandManager, skillName: string) {
+  await commands.createCmd.createSkill(skillName);
+}

package/src/export.ts

@@ -22,6 +22,7 @@ import { staticFrontendDirRelative } from './utils.js';
 import type { QueryResult } from '@cyberismo/data-handler/types/queries';
 import { toSSG } from 'hono/ssg';
 import type { TreeOptions } from './types.js';
+import type { ProjectErrors } from './project-errors.js';
 import {
   findAllCards,
   findRelevantAttachments,
@@ -32,6 +33,8 @@ export interface ExportSiteOptions extends TreeOptions {
 }
 
 const _cardQueryCache = new Map<string, Promise<QueryResult<'card'>[]>>();
+/** Label for errors from routes that belong to no project. */
+const SHARED_ROUTES = '(shared)';
 const OVERHEAD_CALLS = 6; // estimated number of overhead calls during export in addition to card exports
 
 /**
@@ -82,14 +85,14 @@ export async function getCardQueryResult(
  * @param options.cardKey - Key of the card to export. If not provided, all cards will be exported.
  * @param options.defaultProject - Default project prefix to write into config.json.
  * @param onProgress - Optional progress callback function.
- * @returns An object containing any errors that occurred during export.
+ * @returns Errors that occurred during export, grouped by project.
  */
 export async function exportSite(
   registry: ProjectRegistry,
   exportDir?: string,
   options?: ExportSiteOptions,
   onProgress?: (current: number, total: number) => void,
-): Promise<{ errors: string[] }> {
+): Promise<{ errors: ProjectErrors[] }> {
   exportDir = exportDir || 'static';
   const { defaultProject, ...treeOpts } = options ?? {};
   const opts: TreeOptions = {
@@ -125,50 +128,65 @@ export async function exportSite(
     total += cards.length + attachments.length;
   }
 
-  // Actual export with progress reporting
+  // One pass per project so an error is attributed to the project whose route
+  // produced it (the response itself carries no project). Shared routes get
+  // their own pass so each route is emitted exactly once.
+  const prefixes = registry.list().map((p) => p.prefix);
+  const projectOf = (pathname: string) =>
+    prefixes.find((p) => {
+      const base = `/api/projects/${p}`;
+      return pathname === base || pathname.startsWith(`${base}/`);
+    });
+
   let done = 0;
   onProgress?.(done, total);
-  const errors: string[] = [];
-  await toSSG(app, fs, {
-    dir: exportDir,
-    concurrency: 5,
-    plugins: [
-      {
-        beforeRequestHook: (req) => {
-          const url = new URL(req.url);
-          // Skip MCP routes — they require session state and are not part of the static site
-          if (url.pathname.startsWith('/mcp')) {
-            return false;
-          }
-          // Skip OIDC/well-known routes — not relevant for static export
-          if (url.pathname.startsWith('/.well-known')) {
-            return false;
-          }
-          return req;
-        },
-        afterResponseHook: async (response) => {
-          if (![200, 201, 204].includes(response.status)) {
-            const error = await response.json();
-            if (
-              typeof error === 'object' &&
-              error != null &&
-              'error' in error &&
-              typeof error.error === 'string'
-            ) {
-              errors.push(error.error);
+  const errors: ProjectErrors[] = [];
+  for (const scope of [undefined, ...prefixes]) {
+    const scopeErrors: string[] = [];
+    await toSSG(app, fs, {
+      dir: exportDir,
+      concurrency: 5,
+      plugins: [
+        {
+          beforeRequestHook: (req) => {
+            const url = new URL(req.url);
+            // Skip MCP routes — they require session state and are not part of the static site
+            if (url.pathname.startsWith('/mcp')) {
+              return false;
+            }
+            // Skip OIDC/well-known routes — not relevant for static export
+            if (url.pathname.startsWith('/.well-known')) {
+              return false;
+            }
+            return projectOf(url.pathname) === scope ? req : false;
+          },
+          afterResponseHook: async (response) => {
+            if (![200, 201, 204].includes(response.status)) {
+              const error = await response.json();
+              if (
+                typeof error === 'object' &&
+                error != null &&
+                'error' in error &&
+                typeof error.error === 'string'
+              ) {
+                scopeErrors.push(error.error);
+              }
+              return false; // ignore route
             }
-            return false; // ignore route
-          }
-          done++;
-          if (done > total) {
-            total = done; // adjust total if underestimated
-          }
-          onProgress?.(done, total);
-          return response;
+            done++;
+            if (done > total) {
+              total = done; // adjust total if underestimated
+            }
+            onProgress?.(done, total);
+            return response;
+          },
         },
-      },
-    ],
-  });
+      ],
+    });
+    if (scopeErrors.length > 0) {
+      errors.push({ prefix: scope ?? SHARED_ROUTES, errors: scopeErrors });
+    }
+  }
   return {
     errors,
   };

package/src/index.ts

@@ -17,6 +17,7 @@ import { serveStatic } from '@hono/node-server/serve-static';
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { findFreePort } from './utils.js';
+import { startPolicyPolling } from './overlay.js';
 import { createApp } from './app.js';
 import type { AuthProvider } from './auth/types.js';
 import type { ProjectRegistry } from './project-registry.js';
@@ -25,6 +26,7 @@ export type { MockUserConfig } from './auth/mock.js';
 export type { AuthProvider } from './auth/types.js';
 export { exportSite, type ExportSiteOptions } from './export.js';
 export { ProjectRegistry } from './project-registry.js';
+export { formatProjectErrors, type ProjectErrors } from './project-errors.js';
 
 const DEFAULT_PORT = 3000;
 const DEFAULT_MAX_PORT = DEFAULT_PORT + 100;
@@ -72,6 +74,7 @@ export async function startServer(
   if (findPort && !useOsAssigned) {
     port = await findFreePort(port, DEFAULT_MAX_PORT);
   }
+  startPolicyPolling(() => registry.list().map((p) => ({ prefix: p.prefix })));
   const app = createApp(
     authProvider,
     registry,

package/src/main.ts

@@ -17,6 +17,7 @@ import { MockAuthProvider } from './auth/mock.js';
 import { KeycloakAuthProvider } from './auth/keycloak.js';
 import type { AuthProvider } from './auth/types.js';
 import { ProjectRegistry } from './project-registry.js';
+import { formatProjectErrors } from './project-errors.js';
 import { gitOptionsFromEnv } from './utils.js';
 import { parseArgs } from 'node:util';
 import dotenv from 'dotenv';
@@ -35,7 +36,7 @@ function createAuthProvider(): AuthProvider {
   }
 
   if (authMode === 'mock') {
-    return new MockAuthProvider();
+    return new MockAuthProvider({ roster: true });
   }
 
   if (authMode === 'idp') {
@@ -84,18 +85,35 @@ if (args.export) {
     console.error('No projects found to export.');
     process.exit(1);
   }
-  const registry = await ProjectRegistry.fromScannedProjects(projects);
-  await exportSite(registry, undefined, {
-    defaultProject:
-      typeof args['default-project'] === 'string'
-        ? args['default-project']
-        : undefined,
+  const defaultProject =
+    typeof args['default-project'] === 'string'
+      ? args['default-project']
+      : undefined;
+  const { registry, failed } =
+    await ProjectRegistry.fromScannedProjects(projects);
+  if (
+    registry.list().length === 0 ||
+    failed.some((f) => f.prefix === defaultProject)
+  ) {
+    console.error(formatProjectErrors(failed));
+    process.exit(1);
+  }
+  const { errors: exportErrors } = await exportSite(registry, undefined, {
+    defaultProject,
   });
+  const errors = [...failed, ...exportErrors];
+  if (errors.length > 0) {
+    console.error(formatProjectErrors(errors));
+    process.exit(1);
+  }
 } else {
-  const registry = await ProjectRegistry.fromScannedProjects(
+  const { registry, failed } = await ProjectRegistry.fromScannedProjects(
     projects,
     gitOptionsFromEnv(),
   );
+  if (failed.length > 0) {
+    console.error(formatProjectErrors(failed));
+  }
   const authProvider = createAuthProvider();
   await startServer(authProvider, registry, true, projectPath);
 }

package/src/middleware/auth.ts

@@ -15,11 +15,13 @@ import type { Context, MiddlewareHandler } from 'hono';
 import type { UserInfo } from '../types.js';
 import { UserRole } from '../types.js';
 import type { AuthProvider } from '../auth/types.js';
+import { isReadOnly } from '../overlay.js';
 
 // Extend Hono Context type to include our custom properties
 declare module 'hono' {
   interface ContextVariableMap {
     user: UserInfo;
+    tokenExp: number;
   }
 }
 
@@ -30,6 +32,14 @@ const roleLevel: Record<UserRole, number> = {
   [UserRole.Admin]: 2,
 };
 
+/** Everyone below administrator is a reader; lifting read-only is their job. */
+function applyReadOnly(user: UserInfo): UserInfo {
+  if (user.role === UserRole.Admin) {
+    return user;
+  }
+  return { ...user, role: UserRole.Reader };
+}
+
 /**
  * Create authentication middleware from an AuthProvider.
  * Validates the user and attaches user info to the context.
@@ -38,10 +48,12 @@ export function createAuthMiddleware(
   provider: AuthProvider,
 ): MiddlewareHandler {
   return async (c, next) => {
-    const user = await provider.authenticate(c.req.raw);
+    const result = await provider.authenticate(c.req.raw);
 
-    if (user) {
-      c.set('user', user);
+    if (result) {
+      const { exp, ...user } = result;
+      c.set('user', isReadOnly(c.req.path) ? applyReadOnly(user) : user);
+      c.set('tokenExp', exp);
     } else {
       // RFC 9728 §5.1: include resource_metadata in WWW-Authenticate
       // only for MCP routes, where the metadata document applies.
@@ -60,6 +72,13 @@ export function createAuthMiddleware(
   };
 }
 
+/**
+ * Check if a role meets or exceeds a minimum role in the hierarchy.
+ */
+export function isAtLeastRole(role: UserRole, minimumRole: UserRole): boolean {
+  return roleLevel[role] >= roleLevel[minimumRole];
+}
+
 /**
  * Check if the current user has at least the required role
  */
@@ -69,7 +88,7 @@ export function hasRole(c: Context, minimumRole: UserRole): boolean {
     return false;
   }
 
-  return roleLevel[user.role] >= roleLevel[minimumRole];
+  return isAtLeastRole(user.role, minimumRole);
 }
 
 /**

package/src/middleware/commandManager.ts

@@ -14,11 +14,13 @@ import type { Context, MiddlewareHandler } from 'hono';
 import type { CommandManager } from '@cyberismo/data-handler';
 import { getCurrentUser } from './auth.js';
 import type { ProjectRegistry } from '../project-registry.js';
+import type { ProjectEvents } from '../domain/events/project-events.js';
 
 // Extend Hono Context type to include our custom properties
 declare module 'hono' {
   interface ContextVariableMap {
     commands: CommandManager;
+    events: ProjectEvents;
     projectPath: string;
     registry: ProjectRegistry;
   }
@@ -73,6 +75,7 @@ export const attachProjectRegistry = (
     if (!commands) {
       return c.json({ error: `Project '${prefix}' not found` }, 404);
     }
+    c.set('events', registry.eventsFor(commands));
     return runWithCommands(c, commands, next);
   };
 };