@cyberismo/backend 1.1.2 → 1.3.0

package/src/domain/resources/index.ts

@@ -1,15 +1,5 @@
-/**
-  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/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import { Hono } from 'hono';
 import { ssgParams } from 'hono/ssg';
@@ -20,8 +10,9 @@ import { resourceParamsSchema } from '../../common/validationSchemas.js';
 import { zValidator } from '../../middleware/zvalidator.js';
 import {
   validateResourceParamsSchema,
+  prefixIdentifierParamsSchema,
+  skillPreviewBodySchema,
   updateOperationBodySchema,
-  workflowGraphParamsSchema,
   workflowGraphQuerySchema,
 } from './schema.js';
 import { requireRole } from '../../middleware/auth.js';
@@ -41,10 +32,10 @@ const router = new Hono();
  *         description: project_path not set or other internal error
  */
 router.get('/tree', requireRole(UserRole.Reader), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
 
   try {
-    const tree = await resourceService.buildResourceTree(commands);
+    const tree = await resourceService.buildResourceTree(ws);
     return c.json(tree);
   } catch (error) {
     return c.json(
@@ -105,12 +96,12 @@ router.get(
   requireRole(UserRole.Reader),
   zValidator('param', validateResourceParamsSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const resourceParams = c.req.valid('param');
 
     try {
       const response: ResourceValidationResponse =
-        await resourceService.validateResource(commands, resourceParams);
+        await resourceService.validateResource(ws, resourceParams);
       return c.json(response);
     } catch (error) {
       if (error instanceof Error && error.message.includes('not found')) {
@@ -126,9 +117,9 @@ router.delete(
   requireRole(UserRole.Admin),
   zValidator('param', resourceParamsSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const resourceParams = c.req.valid('param');
-    await resourceService.deleteResource(commands, resourceParams);
+    await resourceService.deleteResource(ws, resourceParams);
     return c.json({
       message: 'Resource deleted',
     });
@@ -185,19 +176,19 @@ router.get(
   '/:prefix/workflows/:identifier/graph',
   requireRole(UserRole.Reader),
   ssgParams(async (c: AppContext) => {
-    const commands = c.get('commands');
-    return resourceService.listWorkflowGraphParams(commands);
+    const ws = c.get('ws');
+    return resourceService.listWorkflowGraphParams(ws);
   }),
-  zValidator('param', workflowGraphParamsSchema),
+  zValidator('param', prefixIdentifierParamsSchema),
   zValidator('query', workflowGraphQuerySchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     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,
+        ws,
         workflowName,
         card,
       );
@@ -211,21 +202,102 @@ router.get(
   },
 );
 
+/**
+ * @swagger
+ * /api/resources/{prefix}/skills/{identifier}/preview:
+ *   post:
+ *     summary: Render a skill's instructions for the configuration editor
+ *     description: Applies Handlebars templating to the skill content and
+ *                  returns the rendered markdown. For template skills the
+ *                  logic program in query.lp is executed first and its result
+ *                  is used as the template context. Unlike the MCP get_skill
+ *                  tool, the skill does not need to be enabled by the logic
+ *                  programs. Pass skillContent and/or skillQuery to render
+ *                  unsaved editor content instead of what is stored on disk.
+ *     parameters:
+ *       - in: path
+ *         name: prefix
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - in: path
+ *         name: identifier
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: false
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               skillContent:
+ *                 type: string
+ *                 description: Unsaved skill.md content to render.
+ *               skillQuery:
+ *                 type: string
+ *                 description: Unsaved query.lp content to run.
+ *               cardKey:
+ *                 type: string
+ *                 description: Card context for a card-specific skill.
+ *     responses:
+ *       200:
+ *         description: Rendered instructions
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 instructions:
+ *                   type: string
+ *                   description: The rendered skill content as markdown.
+ *       400:
+ *         description: Invalid path parameters, or the query or template failed
+ *       404:
+ *         description: Skill or card not found
+ */
+router.post(
+  '/:prefix/skills/:identifier/preview',
+  requireRole(UserRole.Admin),
+  zValidator('param', prefixIdentifierParamsSchema),
+  zValidator('json', skillPreviewBodySchema),
+  async (c) => {
+    const ws = c.get('ws');
+    const { prefix, identifier } = c.req.valid('param');
+    const body = c.req.valid('json');
+    const skillName = `${prefix}/skills/${identifier}`;
+    try {
+      const instructions = await resourceService.previewSkill(
+        ws,
+        skillName,
+        body,
+      );
+      return c.json({ instructions });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      if (message.includes('not found')) {
+        return c.json({ error: message }, 404);
+      }
+      return c.json({ error: message }, 400);
+    }
+  },
+);
+
 router.post(
   '/:prefix/:type/:identifier/operation',
   requireRole(UserRole.Admin, [UserRole.Connector]),
   zValidator('param', resourceParamsSchema),
   zValidator('json', updateOperationBodySchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const resourceParams = c.req.valid('param');
     const { updateKey, operation } = c.req.valid('json');
 
-    await resourceService.updateResourceWithOperation(
-      commands,
-      resourceParams,
-      { updateKey, operation },
-    );
+    await resourceService.updateResourceWithOperation(ws, resourceParams, {
+      updateKey,
+      operation,
+    });
     return c.json({ message: 'Updated' });
   },
 );

package/src/domain/resources/schema.ts

@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
 import { z } from 'zod';
 import {
   identifierSchema,
@@ -5,12 +8,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 +23,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

@@ -1,32 +1,27 @@
-/**
-  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 type { AnyResourceContent } from '@cyberismo/data-handler/interfaces/resource-interfaces';
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
 import type {
+  AnyResourceContent,
   Card,
   CardWithChildrenCards,
   ResourceFolderType,
-  RemovableResourceTypes,
-} from '@cyberismo/data-handler/interfaces/project-interfaces';
+} from '@cyberismo/model';
 import {
-  type CommandManager,
+  type Workspace,
+  CardNotFoundError,
   isResourceFolderType,
   moduleNameFromCardKey,
   resourceName,
   resourceNameToString,
+  ResourceNotFoundError,
 } 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 +31,18 @@ const resourceTypes: ResourceFolderType[] = [
   'graphViews',
   'linkTypes',
   'reports',
+  'skills',
   'templates',
   'workflows',
 ];
 
-async function getModules(commands: CommandManager) {
+async function getModules(ws: Workspace) {
   try {
-    const modules = await commands.showCmd.showModules();
+    const modules = await ws.modules.list();
     return Promise.all(
       modules.map(async (mod) => {
         try {
-          const module = await commands.showCmd.showModule(mod.name);
+          const module = await ws.modules.show(mod.name);
           return { name: module.name, cardKeyPrefix: module.cardKeyPrefix };
         } catch {
           return { name: mod.name, cardKeyPrefix: mod.name };
@@ -76,9 +72,9 @@ function sortTemplateCardsByRank(
     }));
 }
 
-export async function buildResourceTree(commands: CommandManager) {
-  return commands.consistent(async () => {
-    const project = await commands.showCmd.showProject();
+export async function buildResourceTree(ws: Workspace) {
+  return ws.consistent(async () => {
+    const project = await ws.settings.info();
     const tree: unknown[] = [];
 
     const sortByDisplayName = (
@@ -90,7 +86,7 @@ export async function buildResourceTree(commands: CommandManager) {
         ),
       );
 
-    const modules = await getModules(commands);
+    const modules = await getModules(ws);
 
     // General section first (single node with project + modules metadata)
     tree.push({
@@ -112,12 +108,12 @@ export async function buildResourceTree(commands: CommandManager) {
 
       if (resourceType === 'templates') {
         ({ rootResources, moduleResources } = await processTemplates(
-          commands,
+          ws,
           project.prefix,
         ));
       } else {
         ({ rootResources, moduleResources } = await groupResourcesByPrefix(
-          commands,
+          ws,
           resourceType,
           project.prefix,
         ));
@@ -195,7 +191,7 @@ function parseResourcePrefix(resource: string): {
 // Helper function to create resource node with all data from showResource
 // TODO: The types should be shared between backend and frontend
 async function createResourceNode(
-  commands: CommandManager,
+  ws: Workspace,
   resourceType: ResourceFolderType,
   name: string,
   projectPrefix: string,
@@ -208,7 +204,7 @@ async function createResourceNode(
   children?: unknown[];
   readOnly?: boolean;
 }> {
-  const resourceData = await commands.showCmd.showResource(name);
+  const resourceData = await ws.resources.show(name);
   const node: {
     id: string;
     type: ResourceFolderType;
@@ -297,12 +293,9 @@ function createCardNode(
 }
 
 // Helper function to process templates using templateTree query
-async function processTemplates(
-  commands: CommandManager,
-  projectPrefix: string,
-) {
-  const templates = await commands.showCmd.showResources('templates');
-  const templateTree = await commands.showCmd.showAllTemplateCards();
+async function processTemplates(ws: Workspace, projectPrefix: string) {
+  const templates = await ws.resources.list('templates');
+  const templateTree = await ws.cards.templateCards();
 
   const rootTemplates: { [templateName: string]: unknown[] } = {};
   const moduleTemplates: {
@@ -336,13 +329,7 @@ async function processTemplates(
 
   const rootResources = await Promise.all(
     Object.entries(rootTemplates).map(([templateName, cards]) =>
-      createResourceNode(
-        commands,
-        'templates',
-        templateName,
-        projectPrefix,
-        cards,
-      ),
+      createResourceNode(ws, 'templates', templateName, projectPrefix, cards),
     ),
   );
 
@@ -350,13 +337,7 @@ async function processTemplates(
   for (const [prefix, templates] of Object.entries(moduleTemplates)) {
     moduleResources[prefix] = await Promise.all(
       Object.entries(templates).map(([templateName, cards]) =>
-        createResourceNode(
-          commands,
-          'templates',
-          templateName,
-          projectPrefix,
-          cards,
-        ),
+        createResourceNode(ws, 'templates', templateName, projectPrefix, cards),
       ),
     );
   }
@@ -368,7 +349,7 @@ async function processTemplates(
       if (!rootResources.find((resource) => resource.name === template)) {
         rootResources.push(
           await createResourceNode(
-            commands,
+            ws,
             'templates',
             template,
             projectPrefix,
@@ -387,7 +368,7 @@ async function processTemplates(
       ) {
         moduleResources[prefix].push(
           await createResourceNode(
-            commands,
+            ws,
             'templates',
             template,
             projectPrefix,
@@ -403,14 +384,14 @@ async function processTemplates(
 
 // Helper function to group regular resources by prefix
 async function groupResourcesByPrefix(
-  commands: CommandManager,
+  ws: Workspace,
   resourceType: ResourceFolderType,
   projectPrefix: string,
 ) {
-  const resourceNames = await commands.showCmd.showResources(resourceType);
+  const resourceNames = await ws.resources.list(resourceType);
   const resources = await Promise.all(
     resourceNames.map((name: string) =>
-      createResourceNode(commands, resourceType, name, projectPrefix),
+      createResourceNode(ws, resourceType, name, projectPrefix),
     ),
   );
 
@@ -434,35 +415,27 @@ async function groupResourcesByPrefix(
 
 /**
  * Delete a resource.
- * @param commands Command manager.
+ * @param ws Command manager.
  * @param resource Resource to delete.
  */
-export async function deleteResource(
-  commands: CommandManager,
-  resource: ResourceParams,
-) {
-  return commands.removeCmd.remove(
-    resource.type.substring(
-      0,
-      resource.type.length - 1,
-    ) as RemovableResourceTypes,
+export async function deleteResource(ws: Workspace, resource: ResourceParams) {
+  return ws.resources.remove(
     resourceNameToString(resource),
+    resource.type.substring(0, resource.type.length - 1),
   );
 }
 
 /**
  * Validate a single resource.
- * @param commands Command manager.
+ * @param ws Command manager.
  * @param resource Resource to validate.
  * @returns Validation result with errors and validity status.
  */
 export async function validateResource(
-  commands: CommandManager,
+  ws: Workspace,
   resource: ValidateResourceParams,
 ) {
-  const errors = await commands.consistent(() =>
-    commands.validateCmd.validateResource(resource, commands.project),
-  );
+  const errors = await ws.resources.validate(resource);
 
   return {
     errors: errors.split('\n\n').filter((error) => error !== ''),
@@ -471,13 +444,13 @@ export async function validateResource(
 
 /**
  * Lists the path params for every workflow resource in the project.
- * @param commands Command manager.
+ * @param ws Command manager.
  * @returns One `{ prefix, identifier }` entry per workflow resource.
  */
 export async function listWorkflowGraphParams(
-  commands: CommandManager,
+  ws: Workspace,
 ): Promise<{ prefix: string; identifier: string }[]> {
-  const workflows = await commands.showCmd.showResources('workflows');
+  const workflows = await ws.resources.list('workflows');
   return workflows.map((name) => {
     const { prefix, identifier } = resourceName(name);
     return { prefix, identifier };
@@ -496,15 +469,15 @@ export async function listWorkflowGraphParams(
  *   card cannot be resolved.
  */
 export async function getWorkflowGraph(
-  commands: CommandManager,
+  ws: Workspace,
   workflowName: string,
   cardKey?: string,
 ): Promise<string> {
-  return commands.consistent(async () => {
+  return ws.consistent(async () => {
     try {
-      await commands.showCmd.showResource(workflowName, 'workflows');
+      await ws.resources.show(workflowName, 'workflows');
     } catch (error) {
-      if (error instanceof Error && error.message.includes('does not exist')) {
+      if (error instanceof ResourceNotFoundError) {
         throw new Error(`Workflow '${workflowName}' not found`, {
           cause: error,
         });
@@ -515,7 +488,7 @@ export async function getWorkflowGraph(
     if (cardKey) {
       let card;
       try {
-        card = await commands.showCmd.showCardDetails(cardKey);
+        card = await ws.cards.details(cardKey);
       } catch (error) {
         throw new Error(`Card '${cardKey}' not found`, { cause: error });
       }
@@ -524,25 +497,69 @@ export async function getWorkflowGraph(
       }
       currentState = card.metadata.workflowState;
     }
-    return commands.calculateCmd.runWorkflowGraph(workflowName, {
+    return ws.queries.runWorkflowGraph(workflowName, {
       currentState,
     });
   });
 }
 
+/**
+ * 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(
+  ws: Workspace,
+  skillName: string,
+  body: SkillPreviewBody,
+): Promise<string> {
+  const { cardKey, skillContent, skillQuery } = body;
+  return ws.consistent(async () => {
+    try {
+      await ws.resources.show(skillName, 'skills');
+    } catch (error) {
+      if (error instanceof ResourceNotFoundError) {
+        throw new Error(`Skill '${skillName}' not found`, { cause: error });
+      }
+      throw error;
+    }
+    if (cardKey) {
+      try {
+        await ws.cards.details(cardKey);
+      } catch (error) {
+        if (error instanceof CardNotFoundError) {
+          throw new Error(`Card '${cardKey}' not found`, { cause: error });
+        }
+        throw error;
+      }
+    }
+    return ws.resources.skillPreview(skillName, {
+      cardKey,
+      skillContent,
+      skillQuery,
+    });
+  });
+}
+
 /**
  * Perform an updateOperation on a resource key.
  * This delegates to the data-handler mutation engine.
  */
 export async function updateResourceWithOperation(
-  commands: CommandManager,
+  ws: Workspace,
   resource: ResourceParams,
   body: UpdateOperationBody,
 ) {
   const { updateKey, operation } = body;
-  await commands.atomic(
+  await ws.atomic(
     () =>
-      commands.updateCmd.apply({
+      ws.changes.apply({
         kind: 'edit',
         target: resource,
         updateKey,

package/src/domain/skills/index.ts

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+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 ws = c.get('ws');
+    const { identifier } = c.req.valid('json');
+
+    await skillService.createSkill(ws, identifier);
+    return c.json({ message: 'Skill created successfully' });
+  },
+);
+
+export default router;

package/src/domain/skills/schema.ts

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+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,8 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { Workspace } from '@cyberismo/data-handler';
+
+export async function createSkill(ws: Workspace, skillName: string) {
+  await ws.resources.create(skillName, 'skills', {});
+}