@cyberismo/backend 0.0.27 → 1.1.0

package/src/auth/mock.ts

@@ -11,6 +11,8 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+import type { MiddlewareHandler } from 'hono';
+import { setCookie } from 'hono/cookie';
 import { UserRole } from '../types.js';
 import type { UserInfo } from '../types.js';
 import type { AuthProvider } from './types.js';
@@ -20,6 +22,32 @@ export interface MockUserConfig {
   email?: string;
 }
 
+export const MOCK_ROLE_COOKIE = 'mock-role';
+const ROLE_RESET_VALUE = 'default';
+
+const ROLE_ALIASES: Record<string, UserRole> = {
+  reader: UserRole.Reader,
+  editor: UserRole.Editor,
+  admin: UserRole.Admin,
+  connector: UserRole.Connector,
+};
+
+function parseRole(value: string | null | undefined): UserRole | null {
+  if (!value) return null;
+  return ROLE_ALIASES[value.toLowerCase()] ?? null;
+}
+
+function readCookie(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() !== name) continue;
+    return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return undefined;
+}
+
 export class MockAuthProvider implements AuthProvider {
   private readonly userConfig: MockUserConfig;
 
@@ -27,12 +55,36 @@ export class MockAuthProvider implements AuthProvider {
     this.userConfig = config ?? {};
   }
 
-  async authenticate(): Promise<UserInfo> {
+  async authenticate(req: Request): Promise<UserInfo> {
+    const cookieRole = parseRole(
+      readCookie(req.headers.get('cookie'), MOCK_ROLE_COOKIE),
+    );
     return {
       id: 'mock-user',
       email: this.userConfig.email ?? 'admin@cyberismo.local',
       name: this.userConfig.name ?? 'Local Admin',
-      role: UserRole.Admin,
+      role: cookieRole ?? UserRole.Admin,
     };
   }
 }
+
+/**
+ * Dev-only middleware that turns `?role=<reader|editor|admin>` into a persistent
+ * `mock-role` cookie, and clears it on `?role=default`.
+ */
+export function mockRoleCookieMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    const override = new URL(c.req.url).searchParams.get('role');
+    if (override) {
+      if (override.toLowerCase() === ROLE_RESET_VALUE) {
+        setCookie(c, MOCK_ROLE_COOKIE, '', { path: '/', maxAge: 0 });
+      } else if (parseRole(override)) {
+        setCookie(c, MOCK_ROLE_COOKIE, override.toLowerCase(), {
+          path: '/',
+          sameSite: 'Lax',
+        });
+      }
+    }
+    await next();
+  };
+}

package/src/common/validationSchemas.ts

@@ -21,6 +21,7 @@ export const resourceTypes = [
   'graphViews',
   'linkTypes',
   'reports',
+  'skills',
   'templates',
   'workflows',
 ] as const;

package/src/domain/calculations/index.ts

@@ -47,7 +47,7 @@ const router = new Hono();
  */
 router.post(
   '/',
-  requireRole(UserRole.Admin),
+  requireRole(UserRole.Admin, [UserRole.Connector]),
   zValidator('json', createCalculationSchema),
   async (c) => {
     const commands = c.get('commands');

package/src/domain/cardTypes/service.ts

@@ -11,7 +11,7 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import type { CommandManager } from '@cyberismo/data-handler';
+import { resourceName, type CommandManager } from '@cyberismo/data-handler';
 import type { VisibilityGroup, FieldVisibilityBody } from './schema.js';
 
 export async function getCardTypes(commands: CommandManager) {
@@ -53,6 +53,7 @@ export async function updateFieldVisibility(
   body: FieldVisibilityBody,
 ): Promise<void> {
   const { fieldName, group: targetGroup, index: targetIndex } = body;
+  const target = resourceName(cardTypeName);
 
   await commands.atomic(async () => {
     // Read is now inside the write lock
@@ -87,38 +88,42 @@ export async function updateFieldVisibility(
     // If same group, just handle reordering
     if (currentGroup === targetGroup) {
       if (targetGroup !== 'hidden' && targetIndex !== undefined) {
-        await commands.updateCmd.applyResourceOperation(
-          cardTypeName,
-          { key: groupToKey[targetGroup] },
-          { name: 'rank', target: fieldName, newIndex: targetIndex },
-        );
+        await commands.updateCmd.apply({
+          kind: 'edit',
+          target,
+          updateKey: { key: groupToKey[targetGroup] },
+          operation: { name: 'rank', target: fieldName, newIndex: targetIndex },
+        });
       }
       return;
     }
 
     // Remove from current group (if not hidden)
     if (currentGroup !== 'hidden') {
-      await commands.updateCmd.applyResourceOperation(
-        cardTypeName,
-        { key: groupToKey[currentGroup] },
-        { name: 'remove', target: fieldName },
-      );
+      await commands.updateCmd.apply({
+        kind: 'edit',
+        target,
+        updateKey: { key: groupToKey[currentGroup] },
+        operation: { name: 'remove', target: fieldName },
+      });
     }
 
     // Add to new group (if not hidden)
     if (targetGroup !== 'hidden') {
-      await commands.updateCmd.applyResourceOperation(
-        cardTypeName,
-        { key: groupToKey[targetGroup] },
-        { name: 'add', target: fieldName },
-      );
+      await commands.updateCmd.apply({
+        kind: 'edit',
+        target,
+        updateKey: { key: groupToKey[targetGroup] },
+        operation: { name: 'add', target: fieldName },
+      });
 
       if (targetIndex !== undefined) {
-        await commands.updateCmd.applyResourceOperation(
-          cardTypeName,
-          { key: groupToKey[targetGroup] },
-          { name: 'rank', target: fieldName, newIndex: targetIndex },
-        );
+        await commands.updateCmd.apply({
+          kind: 'edit',
+          target,
+          updateKey: { key: groupToKey[targetGroup] },
+          operation: { name: 'rank', target: fieldName, newIndex: targetIndex },
+        });
       }
     }
   }, `Update field visibility for ${cardTypeName}`);

package/src/domain/cards/lib.ts

@@ -11,7 +11,7 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import Processor from '@asciidoctor/core';
+import { convert } 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';
@@ -71,15 +71,15 @@ export async function getCardDetails(
     );
 
     const projectPrefix = commands.project.projectPrefix;
-    const htmlContent = Processor()
-      .convert(asciidocContent, {
+    const htmlContent = (
+      await convert(asciidocContent, {
         safe: 'safe',
         attributes: {
           imagesdir: `/api/projects/${projectPrefix}/cards/${key}/a`,
           icons: 'font',
         },
       })
-      .toString();
+    ).toString();
 
     if (raw) {
       if (!cardDetailsResponse.metadata) {
@@ -105,6 +105,13 @@ export async function getCardDetails(
           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 ?? [],
         });

package/src/domain/cards/service.ts

@@ -11,7 +11,7 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import Processor from '@asciidoctor/core';
+import { convert } from '@asciidoctor/core';
 import type {
   ExportPdfOptions,
   MetadataContent,
@@ -181,17 +181,16 @@ export async function parseContent(
       'inject',
     );
 
-    const processor = Processor();
     const projectPrefix = commands.project.projectPrefix;
-    const parsedContent = processor
-      .convert(asciidocContent, {
+    const parsedContent = (
+      await convert(asciidocContent, {
         safe: 'safe',
         attributes: {
           imagesdir: `/api/projects/${projectPrefix}/cards/${key}/a`,
           icons: 'font',
         },
       })
-      .toString();
+    ).toString();
 
     return { parsedContent };
   });

package/src/domain/project/index.ts

@@ -14,8 +14,11 @@
 import { Hono } from 'hono';
 import { zValidator } from '../../middleware/zvalidator.js';
 import {
+  addHubSchema,
+  cleanSchema,
   importModuleSchema,
   moduleParamSchema,
+  removeHubSchema,
   updateProjectSchema,
 } from './schema.js';
 import * as projectService from './service.js';
@@ -92,4 +95,55 @@ router.delete(
   },
 );
 
+router.get('/hubs', requireRole(UserRole.Reader), async (c) => {
+  const commands = c.get('commands');
+  const hubs = await projectService.getHubs(commands);
+  return c.json(hubs);
+});
+
+router.post(
+  '/hubs',
+  requireRole(UserRole.Admin),
+  zValidator('json', addHubSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { location } = c.req.valid('json');
+    const unreachable = await projectService.addHub(commands, location);
+    return c.json({ message: 'Hub added', unreachable });
+  },
+);
+
+router.delete(
+  '/hubs',
+  requireRole(UserRole.Admin),
+  zValidator('query', removeHubSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { location } = c.req.valid('query');
+    await projectService.removeHub(commands, location);
+    return c.json({ message: 'Hub removed' });
+  },
+);
+
+router.post('/hubs/fetch', requireRole(UserRole.Admin), async (c) => {
+  const commands = c.get('commands');
+  const unreachable = await projectService.fetchHubs(commands);
+  return c.json({ message: 'Hubs fetched', unreachable });
+});
+
+// A non-empty 'failedCards' in the response is a partial success, not an error:
+// the command collects per-card failures instead of throwing, so the report of
+// what was and was not removed is returned with 200.
+router.post(
+  '/clean',
+  requireRole(UserRole.Admin),
+  zValidator('json', cleanSchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const { dryRun } = c.req.valid('json');
+    const result = await projectService.cleanProject(commands, dryRun);
+    return c.json(result);
+  },
+);
+
 export default router;

package/src/domain/project/schema.ts

@@ -20,6 +20,8 @@ export const moduleParamSchema = z.object({
 export const updateProjectSchema = z.object({
   name: z.string().optional(),
   cardKeyPrefix: z.string().optional(),
+  description: z.string().optional(),
+  category: z.string().optional(),
   gitRemoteUrl: z
     .string()
     .refine((s) => s.startsWith('https://') || s.startsWith('git@'), {
@@ -28,6 +30,27 @@ export const updateProjectSchema = z.object({
     .optional(),
 });
 
+export const addHubSchema = z.object({
+  location: z.url({
+    protocol: /^https?$/,
+    error: 'Hub location must be a valid HTTP or HTTPS URL',
+  }),
+});
+
+// Removal accepts any stored location: configurations written before locations
+// were validated may hold entries this schema would otherwise refuse, and those
+// have to stay removable.
+export const removeHubSchema = z.object({
+  location: z.string().min(1),
+});
+
+// 'dryRun' is required so that a request whose body did not arrive fails with
+// 400 instead of defaulting into the destructive real clean. The command's
+// 'cardType' narrowing is deliberately not exposed yet.
+export const cleanSchema = z.object({
+  dryRun: z.boolean(),
+});
+
 export const importModuleSchema = z.object({
   source: z
     .string()

package/src/domain/project/service.ts

@@ -12,10 +12,14 @@
 */
 
 import {
+  type CleanResult,
   type CommandManager,
+  type HubFetchFailure,
   type ModuleSettingFromHub,
 } from '@cyberismo/data-handler';
 
+export type { CleanResult } from '@cyberismo/data-handler';
+
 export interface ProjectModule {
   name: string;
   cardKeyPrefix: string;
@@ -24,6 +28,8 @@ export interface ProjectModule {
 export interface ProjectInfo {
   name: string;
   cardKeyPrefix: string;
+  description: string;
+  category: string;
   modules: ProjectModule[];
   gitRemoteUrl: string | null;
 }
@@ -31,9 +37,25 @@ export interface ProjectInfo {
 export interface ProjectUpdatePayload {
   name?: string;
   cardKeyPrefix?: string;
+  description?: string;
+  category?: string;
   gitRemoteUrl?: string;
 }
 
+export interface HubModuleInfo {
+  name: string;
+  displayName?: string;
+  location: string;
+  imported: boolean;
+}
+
+export interface HubInfo {
+  location: string;
+  displayName?: string;
+  description?: string;
+  modules: HubModuleInfo[];
+}
+
 async function toModuleInfo(
   commands: CommandManager,
   moduleName: string,
@@ -67,6 +89,8 @@ export async function getProject(
     return {
       name: project.name,
       cardKeyPrefix: project.prefix,
+      description: project.description ?? '',
+      category: project.category ?? '',
       modules: moduleDetails,
       gitRemoteUrl,
     };
@@ -77,7 +101,7 @@ export async function updateProject(
   commands: CommandManager,
   updates: ProjectUpdatePayload,
 ): Promise<ProjectInfo> {
-  const { name, cardKeyPrefix, gitRemoteUrl } = updates;
+  const { name, cardKeyPrefix, description, category, gitRemoteUrl } = updates;
 
   await commands.atomic(async () => {
     if (cardKeyPrefix) {
@@ -86,6 +110,12 @@ export async function updateProject(
     if (name) {
       await commands.project.configuration.setProjectName(name);
     }
+    if (description !== undefined) {
+      await commands.project.configuration.setDescription(description);
+    }
+    if (category !== undefined) {
+      await commands.project.configuration.setCategory(category);
+    }
   }, 'Update project settings');
 
   if (gitRemoteUrl !== undefined) {
@@ -107,9 +137,21 @@ export async function deleteModule(commands: CommandManager, module: string) {
   await commands.removeCmd.remove('module', module);
 }
 
+// Hub data is only refreshed on demand, so a project that has never fetched
+// would otherwise show an empty catalogue until the user asks for a refresh.
+async function populateHubCache(commands: CommandManager) {
+  try {
+    await commands.fetchCmd.ensureModuleListExists();
+  } catch (error) {
+    // An unreachable hub must not fail listing the hubs we already know about.
+    console.warn('Failed to populate the hub cache', error);
+  }
+}
+
 export async function getImportableModules(
   commands: CommandManager,
 ): Promise<ModuleSettingFromHub[]> {
+  await populateHubCache(commands);
   return commands.showCmd.showImportableModules(false, true);
 }
 
@@ -119,3 +161,49 @@ export async function importModule(
 ): Promise<void> {
   await commands.importCmd.importModule(source);
 }
+
+export async function getHubs(commands: CommandManager): Promise<HubInfo[]> {
+  await populateHubCache(commands);
+  const hubs = await commands.showCmd.showHubDetails();
+  const importedModules = new Set(
+    (await commands.showCmd.showModules()).map((mod) => mod.name),
+  );
+  return hubs.map((hub) => ({
+    location: hub.location,
+    displayName: hub.displayName,
+    description: hub.description,
+    modules: hub.modules.map((mod) => ({
+      name: mod.name,
+      displayName: mod.displayName,
+      location: mod.location,
+      imported: importedModules.has(mod.name),
+    })),
+  }));
+}
+
+export async function addHub(
+  commands: CommandManager,
+  location: string,
+): Promise<HubFetchFailure[]> {
+  await commands.createCmd.addHubLocation(location);
+  // The hub is configured even when it cannot be reached right now; its
+  // modules appear once a later refresh succeeds.
+  return commands.fetchCmd.fetchHubs(true);
+}
+
+export async function removeHub(commands: CommandManager, location: string) {
+  await commands.removeCmd.remove('hub', location);
+}
+
+export async function fetchHubs(
+  commands: CommandManager,
+): Promise<HubFetchFailure[]> {
+  return commands.fetchCmd.fetchHubs(true);
+}
+
+export async function cleanProject(
+  commands: CommandManager,
+  dryRun: boolean,
+): Promise<CleanResult> {
+  return commands.cleanCmd.clean(dryRun);
+}

package/src/domain/projects/index.ts

@@ -12,11 +12,17 @@
 */
 
 import { Hono } from 'hono';
+import { zValidator } from '../../middleware/zvalidator.js';
 import type { ProjectRegistry } from '../../project-registry.js';
-import { requireRole } from '../../middleware/auth.js';
+import { requireRole, getCurrentUser } from '../../middleware/auth.js';
 import { UserRole } from '../../types.js';
+import { createProjectSchema, cloneProjectSchema } from './schema.js';
+import * as projectsService from './service.js';
 
-export function createProjectsRouter(registry: ProjectRegistry) {
+export function createProjectsRouter(
+  registry: ProjectRegistry,
+  multiProjectRoot?: string,
+) {
   const router = new Hono();
 
   /**
@@ -32,8 +38,114 @@ export function createProjectsRouter(registry: ProjectRegistry) {
    *         description: Unauthorized
    */
   router.get('/', requireRole(UserRole.Reader), (c) => {
-    return c.json(registry.list());
+    return c.json({
+      projects: registry.list(),
+      canCreateProjects: !!multiProjectRoot,
+    });
   });
 
+  /**
+   * @swagger
+   * /api/projects:
+   *   post:
+   *     summary: Create a new project
+   *     description: Creates a new project on disk, initializes git, adds default hub
+   */
+  router.post(
+    '/',
+    requireRole(UserRole.Editor),
+    zValidator('json', createProjectSchema),
+    async (c) => {
+      if (!multiProjectRoot) {
+        return c.json(
+          { error: 'Project creation is not available in single-project mode' },
+          403,
+        );
+      }
+
+      const params = c.req.valid('json');
+
+      if (registry.has(params.prefix)) {
+        return c.json(
+          { error: `Project with prefix '${params.prefix}' already exists` },
+          409,
+        );
+      }
+
+      try {
+        const result = await projectsService.createProject(
+          registry,
+          multiProjectRoot,
+          params,
+          getCurrentUser(c),
+        );
+        return c.json(result, 201);
+      } catch (error) {
+        return c.json(
+          {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Failed to create project',
+          },
+          500,
+        );
+      }
+    },
+  );
+
+  /**
+   * @swagger
+   * /api/projects/clone:
+   *   post:
+   *     summary: Clone a project from a git repository
+   *     description: Clones a git repo and registers discovered projects
+   */
+  router.post(
+    '/clone',
+    requireRole(UserRole.Editor),
+    zValidator('json', cloneProjectSchema),
+    async (c) => {
+      if (!multiProjectRoot) {
+        return c.json(
+          { error: 'Project cloning is not available in single-project mode' },
+          403,
+        );
+      }
+
+      const { url } = c.req.valid('json');
+
+      try {
+        const result = await projectsService.cloneProject(
+          registry,
+          multiProjectRoot,
+          url,
+        );
+
+        if (result.projects.length === 0) {
+          return c.json(
+            {
+              error: 'All projects in the cloned repository already exist',
+              skippedDuplicates: result.skippedDuplicates,
+            },
+            409,
+          );
+        }
+
+        return c.json(result, 201);
+      } catch (error) {
+        return c.json(
+          {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Failed to clone repository',
+          },
+          500,
+        );
+      }
+    },
+  );
+
   return router;
 }

package/src/domain/projects/schema.ts

@@ -0,0 +1,42 @@
+/**
+  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 { Validate } from '@cyberismo/data-handler';
+
+export const createProjectSchema = z.object({
+  name: z
+    .string()
+    .min(1, 'Project name is required')
+    .refine((s) => Validate.isValidProjectName(s), {
+      message: 'Invalid project name',
+    }),
+  prefix: z
+    .string()
+    .min(3, 'Prefix must be at least 3 characters')
+    .max(10, 'Prefix must be at most 10 characters')
+    .refine((s) => Validate.validatePrefix(s), {
+      message: 'Prefix must contain only lowercase letters',
+    }),
+  category: z.string().optional().default(''),
+  description: z.string().optional().default(''),
+});
+
+export const cloneProjectSchema = z.object({
+  url: z
+    .string()
+    .min(1, 'Repository URL is required')
+    .refine((s) => s.startsWith('https://') || s.startsWith('git@'), {
+      message: 'URL must start with https:// or git@',
+    }),
+});