@cyberismo/backend 1.0.0 → 1.1.0

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

@@ -30,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;
@@ -38,6 +42,20 @@ export interface ProjectUpdatePayload {
   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,
@@ -119,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);
 }
 
@@ -131,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/resources/index.ts

@@ -213,7 +213,7 @@ router.get(
 
 router.post(
   '/:prefix/:type/:identifier/operation',
-  requireRole(UserRole.Admin),
+  requireRole(UserRole.Admin, [UserRole.Connector]),
   zValidator('param', resourceParamsSchema),
   zValidator('json', updateOperationBodySchema),
   async (c) => {

package/src/domain/resources/schema.ts

@@ -25,7 +25,7 @@ export const resourceFileParamsSchema = resourceParamsSchema.extend({
 export type ResourceFileParams = z.infer<typeof resourceFileParamsSchema>;
 
 export const validateResourceParamsSchema = resourceParamsSchema.extend({
-  type: z.enum(resourceTypes.filter((type) => type !== 'calculations')),
+  type: z.enum(resourceTypes),
 });
 
 export type ValidateResourceParams = z.infer<
@@ -54,7 +54,9 @@ export const updateOperationBodySchema = z.object({
     }),
     z.object({
       name: z.literal('change'),
-      target: z.unknown(),
+      // The old value; scalar changes have none, and clients drop the key
+      // entirely when it is undefined (JSON.stringify omits undefined).
+      target: z.unknown().optional(),
       to: z.unknown(),
       mappingTable: z
         .object({

package/src/domain/resources/service.ts

@@ -532,7 +532,7 @@ export async function getWorkflowGraph(
 
 /**
  * Perform an updateOperation on a resource key.
- * This delegates to data-handler Update.applyResourceOperation.
+ * This delegates to the data-handler mutation engine.
  */
 export async function updateResourceWithOperation(
   commands: CommandManager,
@@ -542,11 +542,12 @@ export async function updateResourceWithOperation(
   const { updateKey, operation } = body;
   await commands.atomic(
     () =>
-      commands.updateCmd.applyResourceOperation(
-        resourceNameToString(resource),
+      commands.updateCmd.apply({
+        kind: 'edit',
+        target: resource,
         updateKey,
         operation,
-      ),
+      }),
     `Update ${resource.type} ${resource.identifier}`,
   );
 }

package/src/index.ts

@@ -37,13 +37,12 @@ const DEFAULT_MAX_PORT = DEFAULT_PORT + 100;
 export async function previewSite(dir: string, findPort: boolean = true) {
   const app = new Hono();
   app.use(serveStatic({ root: dir }));
-  app.get('*', (c) => {
+  app.get('*', async (c) => {
     if (c.req.path.startsWith('/api/')) {
       return c.json({ error: 'Resource not found' }, 404);
     }
-    return c.html(
-      readFile(path.join(dir, 'index.html')).then((file) => file.toString()),
-    );
+    const file = await readFile(path.join(dir, 'index.html'));
+    return c.html(file.toString());
   });
 
   let port = parseInt(process.env.PORT || DEFAULT_PORT.toString(), 10);

package/src/middleware/auth.ts

@@ -24,6 +24,7 @@ declare module 'hono' {
 }
 
 const roleLevel: Record<UserRole, number> = {
+  [UserRole.Connector]: -1,
   [UserRole.Reader]: 0,
   [UserRole.Editor]: 1,
   [UserRole.Admin]: 2,
@@ -72,10 +73,15 @@ export function hasRole(c: Context, minimumRole: UserRole): boolean {
 }
 
 /**
- * Require minimum role middleware factory
- * Returns a middleware that checks if the user has at least the required role
+ * Require minimum role middleware factory.
+ * Optional exactRoles allows orthogonal roles (e.g. Connector) that bypass
+ * the hierarchy with an exact match.
+ * e.g. requireRole(Admin, [Connector]) → Admin ✓, Editor ✗, Connector ✓
  */
-export function requireRole(minimumRole: UserRole): MiddlewareHandler {
+export function requireRole(
+  minimumRole: UserRole,
+  exactRoles?: UserRole[],
+): MiddlewareHandler {
   return async (c, next) => {
     const user = c.get('user');
 
@@ -83,7 +89,7 @@ export function requireRole(minimumRole: UserRole): MiddlewareHandler {
       return c.json({ error: 'Unauthorized' }, 401);
     }
 
-    if (!hasRole(c, minimumRole)) {
+    if (!hasRole(c, minimumRole) && !exactRoles?.includes(user.role)) {
       return c.json({ error: 'Forbidden' }, 403);
     }
 

package/src/types.ts

@@ -32,11 +32,14 @@ export interface TreeOptions {
  * - Admin: All operations including configuration
  * - Editor: Can create, edit, and manage content but not config
  * - Reader: Can only view content
+ * Orthogonal role (outside hierarchy):
+ * - Connector: Service accounts that can only create/update calculations
  */
 export enum UserRole {
   Admin = 'admin',
   Editor = 'editor',
   Reader = 'reader',
+  Connector = 'connector',
 }
 
 /**

package/dist/public/assets/architecture-7EHR7CIX-CHU1xuYF.js

@@ -1 +0,0 @@
-import"./chunk-NNHCCRGN-DlpIbxXb.js";import{x as e}from"./mermaid-parser.core-DFZGVidJ.js";export{e as createArchitectureServices};