@cyberismo/backend 1.1.2 → 1.3.0

package/src/domain/project/service.ts

@@ -1,27 +1,17 @@
-/**
-  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 { type ProjectDirectory, type Workspace } from '@cyberismo/data-handler';
 import {
   type CleanResult,
-  type CommandManager,
   type HubFetchFailure,
   type ModuleSettingFromHub,
-} from '@cyberismo/data-handler';
+  type ProjectModuleInfo,
+  type UpdatePlan,
+} from '@cyberismo/model';
 
-export type { CleanResult } from '@cyberismo/data-handler';
-
-export interface ProjectModule {
-  name: string;
+// Never carries the module's source location.
+export interface ProjectModule extends ProjectModuleInfo {
   cardKeyPrefix: string;
 }
 
@@ -57,34 +47,30 @@ export interface HubInfo {
 }
 
 async function toModuleInfo(
-  commands: CommandManager,
-  moduleName: string,
+  ws: Workspace,
+  row: ProjectModuleInfo,
 ): Promise<ProjectModule> {
   try {
-    const data = await commands.showCmd.showModule(moduleName);
+    const data = await ws.modules.show(row.name);
     return {
-      name: data.name || moduleName,
-      cardKeyPrefix: data.cardKeyPrefix || moduleName,
+      ...row,
+      name: data.name || row.name,
+      cardKeyPrefix: data.cardKeyPrefix || row.name,
     };
   } catch {
-    return {
-      name: moduleName,
-      cardKeyPrefix: moduleName,
-    };
+    return { ...row, cardKeyPrefix: row.name };
   }
 }
 
-export async function getProject(
-  commands: CommandManager,
-): Promise<ProjectInfo> {
-  return commands.consistent(async () => {
-    const project = await commands.showCmd.showProject();
-    const modules = await commands.showCmd.showModules();
+export async function getProject(ws: Workspace): Promise<ProjectInfo> {
+  return ws.consistent(async () => {
+    const project = await ws.settings.info();
+    const modules = await ws.modules.inventory();
     const moduleDetails = await Promise.all(
-      modules.map((mod) => toModuleInfo(commands, mod.name)),
+      modules.map((row) => toModuleInfo(ws, row)),
     );
 
-    const gitRemoteUrl = (await commands.showCmd.showGitRemoteUrl()) ?? null;
+    const gitRemoteUrl = (await ws.settings.gitRemoteUrl()) ?? null;
 
     return {
       name: project.name,
@@ -98,50 +84,75 @@ export async function getProject(
 }
 
 export async function updateProject(
-  commands: CommandManager,
+  ws: Workspace,
+  directory: ProjectDirectory,
   updates: ProjectUpdatePayload,
 ): Promise<ProjectInfo> {
   const { name, cardKeyPrefix, description, category, gitRemoteUrl } = updates;
 
-  await commands.atomic(async () => {
+  await ws.atomic(async () => {
     if (cardKeyPrefix) {
-      await commands.renameCmd.rename(cardKeyPrefix);
+      await directory.rename(
+        ws.settings.prefix,
+        cardKeyPrefix,
+        ws.actor,
+        ws.identity,
+      );
     }
     if (name) {
-      await commands.project.configuration.setProjectName(name);
+      await ws.settings.setName(name);
     }
     if (description !== undefined) {
-      await commands.project.configuration.setDescription(description);
+      await ws.settings.setDescription(description);
     }
     if (category !== undefined) {
-      await commands.project.configuration.setCategory(category);
+      await ws.settings.setCategory(category);
     }
   }, 'Update project settings');
 
   if (gitRemoteUrl !== undefined) {
-    await commands.editCmd.setGitRemoteUrl(gitRemoteUrl);
+    await ws.settings.setGitRemoteUrl(gitRemoteUrl);
   }
 
-  return getProject(commands);
+  return getProject(ws);
 }
 
-export async function updateModule(commands: CommandManager, module: string) {
-  await commands.importCmd.updateModule(module);
+export async function updateModule(
+  ws: Workspace,
+  module: string,
+  range?: string,
+) {
+  await ws.modules.update(range ? { module, range } : { module });
 }
 
-export async function updateAllModules(commands: CommandManager) {
-  await commands.importCmd.updateAllModules();
+export async function updateAllModules(ws: Workspace) {
+  await ws.modules.update({});
 }
 
-export async function deleteModule(commands: CommandManager, module: string) {
-  await commands.removeCmd.remove('module', module);
+export async function getUpdatePlan(ws: Workspace): Promise<UpdatePlan> {
+  return ws.modules.planUpdate({});
+}
+
+export async function listModuleVersions(
+  ws: Workspace,
+  target: { module?: string; source?: string },
+): Promise<string[]> {
+  return ws.modules.listVersions(
+    target.source !== undefined
+      ? { source: target.source }
+      : { module: target.module! },
+  );
+}
+
+export async function deleteModule(ws: Workspace, module: string) {
+  await ws.modules.remove(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) {
+async function populateHubCache(ws: Workspace) {
   try {
-    await commands.fetchCmd.ensureModuleListExists();
+    await ws.modules.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);
@@ -149,24 +160,25 @@ async function populateHubCache(commands: CommandManager) {
 }
 
 export async function getImportableModules(
-  commands: CommandManager,
+  ws: Workspace,
 ): Promise<ModuleSettingFromHub[]> {
-  await populateHubCache(commands);
-  return commands.showCmd.showImportableModules(false, true);
+  await populateHubCache(ws);
+  return ws.modules.importable(false, true);
 }
 
 export async function importModule(
-  commands: CommandManager,
+  ws: Workspace,
   source: string,
+  range?: string,
 ): Promise<void> {
-  await commands.importCmd.importModule(source);
+  await ws.modules.install(source, range ? { version: range } : undefined);
 }
 
-export async function getHubs(commands: CommandManager): Promise<HubInfo[]> {
-  await populateHubCache(commands);
-  const hubs = await commands.showCmd.showHubDetails();
+export async function getHubs(ws: Workspace): Promise<HubInfo[]> {
+  await populateHubCache(ws);
+  const hubs = await ws.modules.hubDetails();
   const importedModules = new Set(
-    (await commands.showCmd.showModules()).map((mod) => mod.name),
+    (await ws.modules.list()).map((mod) => mod.name),
   );
   return hubs.map((hub) => ({
     location: hub.location,
@@ -182,28 +194,26 @@ export async function getHubs(commands: CommandManager): Promise<HubInfo[]> {
 }
 
 export async function addHub(
-  commands: CommandManager,
+  ws: Workspace,
   location: string,
 ): Promise<HubFetchFailure[]> {
-  await commands.createCmd.addHubLocation(location);
+  await ws.settings.hubs.add(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);
+  return ws.modules.fetchHubs(true);
 }
 
-export async function removeHub(commands: CommandManager, location: string) {
-  await commands.removeCmd.remove('hub', location);
+export async function removeHub(ws: Workspace, location: string) {
+  await ws.settings.hubs.remove(location);
 }
 
-export async function fetchHubs(
-  commands: CommandManager,
-): Promise<HubFetchFailure[]> {
-  return commands.fetchCmd.fetchHubs(true);
+export async function fetchHubs(ws: Workspace): Promise<HubFetchFailure[]> {
+  return ws.modules.fetchHubs(true);
 }
 
 export async function cleanProject(
-  commands: CommandManager,
+  ws: Workspace,
   dryRun: boolean,
 ): Promise<CleanResult> {
-  return commands.cleanCmd.clean(dryRun);
+  return ws.clean.run(dryRun);
 }

package/src/domain/projects/index.ts

@@ -1,26 +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/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import { Hono } from 'hono';
 import { zValidator } from '../../middleware/zvalidator.js';
-import type { ProjectRegistry } from '../../project-registry.js';
+import type { ProjectDirectory } from '@cyberismo/data-handler';
+import { errorBody, errorResponse } from '../../common/errors.js';
 import { requireRole, getCurrentUser } from '../../middleware/auth.js';
+import { isProjectReadOnly } from '../../overlay.js';
 import { UserRole } from '../../types.js';
 import { createProjectSchema, cloneProjectSchema } from './schema.js';
 import * as projectsService from './service.js';
 
 export function createProjectsRouter(
-  registry: ProjectRegistry,
+  directory: ProjectDirectory,
   multiProjectRoot?: string,
 ) {
   const router = new Hono();
@@ -37,9 +29,12 @@ export function createProjectsRouter(
    *       401:
    *         description: Unauthorized
    */
-  router.get('/', requireRole(UserRole.Reader), (c) => {
+  router.get('/', requireRole(UserRole.Reader), async (c) => {
     return c.json({
-      projects: registry.list(),
+      projects: (await directory.list()).map((project) => ({
+        ...project,
+        readOnly: isProjectReadOnly(project.prefix),
+      })),
       canCreateProjects: !!multiProjectRoot,
     });
   });
@@ -58,38 +53,31 @@ export function createProjectsRouter(
     async (c) => {
       if (!multiProjectRoot) {
         return c.json(
-          { error: 'Project creation is not available in single-project mode' },
+          errorBody(
+            'permission-denied',
+            '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,
+          directory,
           params,
           getCurrentUser(c),
         );
         return c.json(result, 201);
       } catch (error) {
-        return c.json(
-          {
-            error:
-              error instanceof Error
-                ? error.message
-                : 'Failed to create project',
-          },
-          500,
+        // A taken prefix is the directory's ProjectExistsError: a 409.
+        const { status, body } = errorResponse(
+          error instanceof Error
+            ? error
+            : new Error('Failed to create project'),
         );
+        return c.json(body, status);
       }
     },
   );
@@ -108,7 +96,10 @@ export function createProjectsRouter(
     async (c) => {
       if (!multiProjectRoot) {
         return c.json(
-          { error: 'Project cloning is not available in single-project mode' },
+          errorBody(
+            'permission-denied',
+            'Project cloning is not available in single-project mode',
+          ),
           403,
         );
       }
@@ -116,18 +107,15 @@ export function createProjectsRouter(
       const { url } = c.req.valid('json');
 
       try {
-        const result = await projectsService.cloneProject(
-          registry,
-          multiProjectRoot,
-          url,
-        );
+        const result = await directory.clone(url);
 
         if (result.projects.length === 0) {
           return c.json(
-            {
-              error: 'All projects in the cloned repository already exist',
-              skippedDuplicates: result.skippedDuplicates,
-            },
+            errorBody(
+              'conflict',
+              'All projects in the cloned repository already exist',
+              { skippedDuplicates: result.skippedDuplicates },
+            ),
             409,
           );
         }
@@ -135,12 +123,12 @@ export function createProjectsRouter(
         return c.json(result, 201);
       } catch (error) {
         return c.json(
-          {
-            error:
-              error instanceof Error
-                ? error.message
-                : 'Failed to clone repository',
-          },
+          errorBody(
+            'internal',
+            error instanceof Error
+              ? error.message
+              : 'Failed to clone repository',
+          ),
           500,
         );
       }

package/src/domain/projects/schema.ts

@@ -1,15 +1,5 @@
-/**
-  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/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import { z } from 'zod';
 import { Validate } from '@cyberismo/data-handler';
@@ -30,6 +20,7 @@ export const createProjectSchema = z.object({
     }),
   category: z.string().optional().default(''),
   description: z.string().optional().default(''),
+  skipDefaultHub: z.boolean().optional(),
 });
 
 export const cloneProjectSchema = z.object({

package/src/domain/projects/service.ts

@@ -1,98 +1,28 @@
-/**
-  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/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
-import { join } from 'node:path';
-import {
-  CommandManager,
-  Create,
-  scanForProjects,
-} from '@cyberismo/data-handler';
-import type { ProjectRegistry } from '../../project-registry.js';
-
-export interface CreateProjectParams {
-  name: string;
-  prefix: string;
-  category?: string;
-  description?: string;
-}
-
-export interface CreateProjectResult {
-  prefix: string;
-  name: string;
-  category?: string;
-  description?: string;
-}
+import { SYSTEM_ACTOR, type ProjectDirectory } from '@cyberismo/data-handler';
+import type { CreateProjectParams } from '@cyberismo/model';
+import { actorOf } from '../../middleware/commandManager.js';
+import type { UserInfo } from '../../types.js';
 
 export async function createProject(
-  registry: ProjectRegistry,
-  rootPath: string,
+  directory: ProjectDirectory,
   params: CreateProjectParams,
-  user?: { name: string; email: string } | null,
-): Promise<CreateProjectResult> {
-  const { name, prefix, category, description } = params;
-  const projectPath = join(rootPath, prefix);
-
-  const commands = await CommandManager.createProjectWithDefaults(
-    projectPath,
+  user?: UserInfo | null,
+) {
+  const { prefix, failures, warnings } = await directory.create(
     params,
-    {
-      ...registry.options,
-      gitUser: user ?? undefined,
-    },
+    user ? actorOf(user) : SYSTEM_ACTOR,
+    user ? { name: user.name, email: user.email } : undefined,
   );
-
-  registry.add(prefix, commands);
-
+  // The project's path stays on the server.
   return {
     prefix,
-    name,
-    category: category || undefined,
-    description: description || undefined,
-  };
-}
-
-export interface CloneProjectResult {
-  projects: { prefix: string; name: string }[];
-  skippedDuplicates?: string[];
-}
-
-export async function cloneProject(
-  registry: ProjectRegistry,
-  rootPath: string,
-  url: string,
-): Promise<CloneProjectResult> {
-  const clonedPath = await Create.cloneProject(url, rootPath);
-  const scanned = await scanForProjects(clonedPath);
-
-  const registered: { prefix: string; name: string }[] = [];
-  const skippedDuplicates: string[] = [];
-
-  for (const project of scanned) {
-    if (registry.has(project.prefix)) {
-      skippedDuplicates.push(project.prefix);
-      continue;
-    }
-    const commands = new CommandManager(project.path, registry.options);
-    await commands.initialize();
-    registry.add(project.prefix, commands);
-    registered.push({
-      prefix: project.prefix,
-      name: project.name,
-    });
-  }
-
-  return {
-    projects: registered,
-    ...(skippedDuplicates.length > 0 && { skippedDuplicates }),
+    name: params.name,
+    category: params.category || undefined,
+    description: params.description || undefined,
+    failures,
+    warnings,
   };
 }

package/src/domain/reports/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 * as reportService from './service.js';
@@ -50,10 +40,10 @@ router.post(
   requireRole(UserRole.Admin),
   zValidator('json', createReportSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const { identifier } = c.req.valid('json');
 
-    await reportService.createReport(commands, identifier);
+    await reportService.createReport(ws, identifier);
     return c.json({ message: 'Report created successfully' });
   },
 );

package/src/domain/reports/schema.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 { z } from 'zod';
 import { identifierSchema } from '../../common/validationSchemas.js';

package/src/domain/reports/service.ts

@@ -1,21 +1,8 @@
-/**
-  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 type { CommandManager } from '@cyberismo/data-handler';
+import type { Workspace } from '@cyberismo/data-handler';
 
-export async function createReport(
-  commands: CommandManager,
-  reportName: string,
-) {
-  await commands.createCmd.createReport(reportName);
+export async function createReport(ws: Workspace, reportName: string) {
+  await ws.resources.create(reportName, 'reports', {});
 }