@cyberismo/backend 1.1.1 → 1.2.0

package/src/domain/events/lifetime.ts

@@ -0,0 +1,27 @@
+/**
+  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/>.
+*/
+
+const MAX_LIFETIME_MS = 30 * 60_000;
+const ROTATION_MARGIN_MS = 30_000;
+
+/** Rotation deadline in ms from now. */
+export function computeLifetimeMs(exp: number, now = Date.now()): number {
+  const jittered = MAX_LIFETIME_MS * (0.6 + Math.random() * 0.4);
+  const remaining = exp * 1000 - now;
+  // Jitter may only shorten: the token `exp` clamp is hard.
+  const untilExpiry =
+    remaining > ROTATION_MARGIN_MS
+      ? remaining - ROTATION_MARGIN_MS
+      : Math.max(remaining, 0);
+  return Math.min(untilExpiry, jittered);
+}

package/src/domain/events/project-events.ts

@@ -0,0 +1,254 @@
+/**
+  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 { randomUUID } from 'node:crypto';
+import type { SSEMessage } from 'hono/streaming';
+
+const LEASE_MS = 90_000;
+const EXPIRY_INTERVAL_MS = 30_000;
+const RETIRED_LEASE_MS = 15_000;
+
+export interface PresenceEntry {
+  userId: string;
+  userName: string;
+  mode: 'viewing' | 'editing';
+}
+
+export interface Capabilities {
+  canSeeIdentity: boolean;
+  canDeclareEditing: boolean;
+  canSeePresence: boolean;
+}
+
+/** The socket one connection's client is written to. A retired connection
+ * must not be written to at all; `deliver` and `closeQuietly` enforce that,
+ * since the route has already ended the stream by then. */
+export interface Delivery {
+  send(message: SSEMessage): void;
+  close(): void;
+  terminate(message: SSEMessage): void;
+}
+
+interface Connection {
+  user: { id: string; name: string };
+  capabilities: Capabilities;
+  delivery: Delivery;
+  cardKey: string | null;
+  mode: PresenceEntry['mode'];
+  sequence: number;
+  expiresAt: number;
+  retired: boolean;
+  /** Last presence list serialized to this connection, for per-recipient dedup. */
+  lastSent: string | null;
+}
+
+/** The open subscriptions of one project and the presence leases they hold. */
+export class ProjectEvents {
+  private connections = new Map<string, Connection>();
+  private expiryTimer: ReturnType<typeof setInterval>;
+
+  constructor() {
+    this.expiryTimer = setInterval(() => this.expire(), EXPIRY_INTERVAL_MS);
+    this.expiryTimer.unref();
+  }
+
+  connect(
+    user: Connection['user'],
+    capabilities: Capabilities,
+    delivery: Delivery,
+  ): string {
+    const connectionId = randomUUID();
+    this.connections.set(connectionId, {
+      user,
+      capabilities,
+      delivery,
+      cardKey: null,
+      mode: 'viewing',
+      sequence: -1,
+      expiresAt: 0,
+      retired: false,
+      lastSent: null,
+    });
+    // EventSource cannot read response headers, so the stream is the only
+    // way back with a connection handle.
+    this.deliver(connectionId, {
+      event: 'ready',
+      data: JSON.stringify({ connectionId }),
+    });
+    return connectionId;
+  }
+
+  update(
+    connectionId: string,
+    userId: string,
+    sequence: number,
+    cardKey: string | null,
+    mode: PresenceEntry['mode'],
+  ): boolean {
+    const connection = this.connections.get(connectionId);
+    if (!connection || connection.retired || connection.user.id !== userId) {
+      return false;
+    }
+    // Monotonic per connection, so a delayed request cannot undo a newer one.
+    if (sequence <= connection.sequence) return true;
+    // Coerced rather than rejected: a fake editing warning deters others from editing.
+    if (!connection.capabilities.canDeclareEditing) mode = 'viewing';
+    if (connection.cardKey === cardKey && connection.mode === mode) {
+      connection.sequence = sequence;
+      connection.expiresAt = Date.now() + LEASE_MS;
+      return true;
+    }
+    this.applyMove(connection, sequence, cardKey, mode, Date.now());
+    return true;
+  }
+
+  private applyMove(
+    connection: Connection,
+    sequence: number,
+    cardKey: string | null,
+    mode: PresenceEntry['mode'],
+    now: number,
+  ): void {
+    const previous = connection.cardKey;
+    if (previous !== cardKey) connection.lastSent = null;
+    Object.assign(connection, {
+      sequence,
+      cardKey,
+      mode,
+      expiresAt: now + LEASE_MS,
+    });
+    if (previous) this.presenceUpdated(previous);
+    if (cardKey && cardKey !== previous) this.presenceUpdated(cardKey);
+  }
+
+  disconnect(connectionId: string): void {
+    const connection = this.connections.get(connectionId);
+    if (!connection) return;
+    this.connections.delete(connectionId);
+    this.closeQuietly(connection);
+    if (connection.cardKey) this.presenceUpdated(connection.cardKey);
+  }
+
+  // `users()` dedups by user id, so a retiring connection's entry can outlive
+  // its socket without observers seeing a change.
+  retire(connectionId: string): void {
+    const connection = this.connections.get(connectionId);
+    if (!connection) return;
+    connection.retired = true;
+    // The entry only has to bridge the client's reconnect. Left on its full
+    // lease it would go on reporting the card and mode held at retirement,
+    // and `editing` wins in users(), so it would mask the live entry the
+    // replacement declares.
+    connection.expiresAt = Math.min(
+      connection.expiresAt,
+      Date.now() + RETIRED_LEASE_MS,
+    );
+  }
+
+  cardsUpdated(cardKeys: string[], user: Connection['user']): void {
+    for (const cardKey of new Set(cardKeys)) {
+      const withIdentity = this.encode('card.updated', {
+        cardKey,
+        userId: user.id,
+        userName: user.name,
+      });
+      const withoutIdentity = this.encode('card.updated', { cardKey });
+      for (const [connectionId, connection] of this.onCard(cardKey)) {
+        this.deliver(
+          connectionId,
+          connection.capabilities.canSeeIdentity
+            ? withIdentity
+            : withoutIdentity,
+        );
+      }
+    }
+  }
+
+  dispose(): void {
+    clearInterval(this.expiryTimer);
+    const connections = [...this.connections.values()];
+    this.connections.clear();
+    for (const connection of connections) {
+      this.closeQuietly(connection);
+    }
+  }
+
+  private users(cardKey: string): PresenceEntry[] {
+    const users = new Map<string, PresenceEntry>();
+    for (const { user, cardKey: key, mode } of this.connections.values()) {
+      if (key !== cardKey) continue;
+      if (!users.has(user.id) || mode === 'editing') {
+        users.set(user.id, { userId: user.id, userName: user.name, mode });
+      }
+    }
+    // Sorted so identical occupancy always serializes the same way, which
+    // the per-recipient dedup in presenceUpdated() depends on.
+    return [...users.values()].sort((a, b) => a.userId.localeCompare(b.userId));
+  }
+
+  private presenceUpdated(cardKey: string): void {
+    const users = this.users(cardKey);
+    const serialized = JSON.stringify(users);
+    const message = this.encode('presence.updated', { cardKey, users });
+    for (const [connectionId, connection] of this.onCard(cardKey)) {
+      // Presence exists to keep editors from colliding, so a reader has no use
+      // for it and is not told who else is here. Readers still declare their
+      // own presence, which is why users() keeps them: editors see readers.
+      if (!connection.capabilities.canSeePresence) continue;
+      if (connection.lastSent === serialized) continue;
+      this.deliver(connectionId, message);
+      connection.lastSent = serialized;
+    }
+  }
+
+  // Subscription governs delivery.
+  private onCard(cardKey: string): [string, Connection][] {
+    return [...this.connections].filter(([, c]) => c.cardKey === cardKey);
+  }
+
+  private encode(event: string, data: unknown): SSEMessage {
+    return { event, data: JSON.stringify(data) };
+  }
+
+  private deliver(connectionId: string, message: SSEMessage): void {
+    const connection = this.connections.get(connectionId);
+    // onCard() still yields a retired connection: it keeps its cardKey so the
+    // occupant list does not change while its replacement connects.
+    if (!connection || connection.retired) return;
+    try {
+      connection.delivery.send(message);
+    } catch {
+      this.disconnect(connectionId);
+    }
+  }
+
+  private expire(): void {
+    for (const [connectionId, connection] of this.connections) {
+      if (connection.expiresAt > Date.now()) continue;
+      if (!connection.retired && !connection.cardKey) continue;
+      const cardKey = connection.cardKey;
+      if (connection.retired) this.connections.delete(connectionId);
+      else connection.cardKey = null;
+      if (cardKey) this.presenceUpdated(cardKey);
+    }
+  }
+
+  private closeQuietly(connection: Connection): void {
+    if (connection.retired) return;
+    try {
+      connection.delivery.close();
+    } catch {
+      /* already closed */
+    }
+  }
+}

package/src/domain/events/schema.ts

@@ -0,0 +1,21 @@
+/**
+  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';
+
+export const presenceSchema = z.object({
+  connectionId: z.uuid(),
+  sequence: z.number().int().nonnegative(),
+  cardKey: z.string().min(1).nullable(),
+  mode: z.enum(['viewing', 'editing']),
+});

package/src/domain/project/index.ts

@@ -12,13 +12,16 @@
 */
 
 import { Hono } from 'hono';
+import { disableSSG } from 'hono/ssg';
 import { zValidator } from '../../middleware/zvalidator.js';
 import {
   addHubSchema,
   cleanSchema,
   importModuleSchema,
   moduleParamSchema,
+  moduleVersionsQuerySchema,
   removeHubSchema,
+  updateModuleSchema,
   updateProjectSchema,
 } from './schema.js';
 import * as projectService from './service.js';
@@ -57,14 +60,39 @@ router.post(
   '/modules/:module/update',
   requireRole(UserRole.Admin),
   zValidator('param', moduleParamSchema),
+  zValidator('json', updateModuleSchema),
   async (c) => {
     const commands = c.get('commands');
     const { module } = c.req.valid('param');
-    await projectService.updateModule(commands, module);
+    const { range } = c.req.valid('json');
+    await projectService.updateModule(commands, module, range);
     return c.json({ message: 'Module updated' });
   },
 );
 
+// These reach the module sources over the network, which an export must not do.
+router.get(
+  '/modules/versions',
+  disableSSG(),
+  requireRole(UserRole.Admin),
+  zValidator('query', moduleVersionsQuerySchema),
+  async (c) => {
+    const commands = c.get('commands');
+    const target = c.req.valid('query');
+    return c.json(await projectService.listModuleVersions(commands, target));
+  },
+);
+
+router.get(
+  '/modules/update-plan',
+  disableSSG(),
+  requireRole(UserRole.Admin),
+  async (c) => {
+    const commands = c.get('commands');
+    return c.json(await projectService.getUpdatePlan(commands));
+  },
+);
+
 router.get('/modules/importable', requireRole(UserRole.Reader), async (c) => {
   const commands = c.get('commands');
   const modules = await projectService.getImportableModules(commands);
@@ -77,8 +105,8 @@ router.post(
   zValidator('json', importModuleSchema),
   async (c) => {
     const commands = c.get('commands');
-    const { source } = c.req.valid('json');
-    await projectService.importModule(commands, source);
+    const { source, range } = c.req.valid('json');
+    await projectService.importModule(commands, source, range);
     return c.json({ message: 'Module imported successfully' });
   },
 );

package/src/domain/project/schema.ts

@@ -51,11 +51,44 @@ export const cleanSchema = z.object({
   dryRun: z.boolean(),
 });
 
+// Credentials in a source would be stored in cardsConfig.json and echoed in
+// query strings, logs and errors.
+const gitSourceSchema = z
+  .string()
+  .min(1)
+  .refine((s) => s.startsWith('https://') || s.startsWith('git@'), {
+    message: 'Source must be a git URL (https:// or git@)',
+  })
+  .refine(
+    (s) => {
+      if (!s.startsWith('https://')) return true;
+      try {
+        const { username, password } = new URL(s);
+        return username === '' && password === '';
+      } catch {
+        return false;
+      }
+    },
+    { message: 'Source must be a valid URL without credentials' },
+  );
+
+// A blank range is a valid semver range meaning '*', which would unpin.
+const rangeSchema = z.string().trim().min(1);
+
 export const importModuleSchema = z.object({
-  source: z
-    .string()
-    .min(1)
-    .refine((s) => s.startsWith('https://') || s.startsWith('git@'), {
-      message: 'Source must be a git URL (https:// or git@)',
-    }),
+  source: gitSourceSchema,
+  range: rangeSchema.optional(),
 });
+
+export const updateModuleSchema = z.object({
+  range: rangeSchema.optional(),
+});
+
+export const moduleVersionsQuerySchema = z
+  .object({
+    module: z.string().min(1).optional(),
+    source: gitSourceSchema.optional(),
+  })
+  .refine((q) => (q.module === undefined) !== (q.source === undefined), {
+    message: 'Provide exactly one of module or source',
+  });

package/src/domain/project/service.ts

@@ -16,12 +16,14 @@ import {
   type CommandManager,
   type HubFetchFailure,
   type ModuleSettingFromHub,
+  type ProjectModuleInfo,
+  type UpdatePlan,
 } from '@cyberismo/data-handler';
 
 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;
 }
 
@@ -58,19 +60,17 @@ export interface HubInfo {
 
 async function toModuleInfo(
   commands: CommandManager,
-  moduleName: string,
+  row: ProjectModuleInfo,
 ): Promise<ProjectModule> {
   try {
-    const data = await commands.showCmd.showModule(moduleName);
+    const data = await commands.modulesCmd.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 };
   }
 }
 
@@ -79,9 +79,9 @@ export async function getProject(
 ): Promise<ProjectInfo> {
   return commands.consistent(async () => {
     const project = await commands.showCmd.showProject();
-    const modules = await commands.showCmd.showModules();
+    const modules = await commands.modulesCmd.inventory();
     const moduleDetails = await Promise.all(
-      modules.map((mod) => toModuleInfo(commands, mod.name)),
+      modules.map((row) => toModuleInfo(commands, row)),
     );
 
     const gitRemoteUrl = (await commands.showCmd.showGitRemoteUrl()) ?? null;
@@ -125,12 +125,33 @@ export async function updateProject(
   return getProject(commands);
 }
 
-export async function updateModule(commands: CommandManager, module: string) {
-  await commands.importCmd.updateModule(module);
+export async function updateModule(
+  commands: CommandManager,
+  module: string,
+  range?: string,
+) {
+  await commands.modulesCmd.update(range ? { module, range } : { module });
 }
 
 export async function updateAllModules(commands: CommandManager) {
-  await commands.importCmd.updateAllModules();
+  await commands.modulesCmd.update({});
+}
+
+export async function getUpdatePlan(
+  commands: CommandManager,
+): Promise<UpdatePlan> {
+  return commands.modulesCmd.planUpdate({});
+}
+
+export async function listModuleVersions(
+  commands: CommandManager,
+  target: { module?: string; source?: string },
+): Promise<string[]> {
+  return commands.modulesCmd.listVersions(
+    target.source !== undefined
+      ? { source: target.source }
+      : { module: target.module! },
+  );
 }
 
 export async function deleteModule(commands: CommandManager, module: string) {
@@ -158,15 +179,19 @@ export async function getImportableModules(
 export async function importModule(
   commands: CommandManager,
   source: string,
+  range?: string,
 ): Promise<void> {
-  await commands.importCmd.importModule(source);
+  await commands.modulesCmd.install(
+    source,
+    range ? { version: range } : undefined,
+  );
 }
 
 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),
+    (await commands.modulesCmd.list()).map((mod) => mod.name),
   );
   return hubs.map((hub) => ({
     location: hub.location,

package/src/domain/projects/index.ts

@@ -15,6 +15,7 @@ import { Hono } from 'hono';
 import { zValidator } from '../../middleware/zvalidator.js';
 import type { ProjectRegistry } from '../../project-registry.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';
@@ -39,7 +40,10 @@ export function createProjectsRouter(
    */
   router.get('/', requireRole(UserRole.Reader), (c) => {
     return c.json({
-      projects: registry.list(),
+      projects: registry.list().map((project) => ({
+        ...project,
+        readOnly: isProjectReadOnly(project.prefix),
+      })),
       canCreateProjects: !!multiProjectRoot,
     });
   });

package/src/domain/resources/index.ts

@@ -20,8 +20,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';
@@ -188,7 +189,7 @@ router.get(
     const commands = c.get('commands');
     return resourceService.listWorkflowGraphParams(commands);
   }),
-  zValidator('param', workflowGraphParamsSchema),
+  zValidator('param', prefixIdentifierParamsSchema),
   zValidator('query', workflowGraphQuerySchema),
   async (c) => {
     const commands = c.get('commands');
@@ -211,6 +212,88 @@ 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 commands = c.get('commands');
+    const { prefix, identifier } = c.req.valid('param');
+    const body = c.req.valid('json');
+    const skillName = `${prefix}/skills/${identifier}`;
+    try {
+      const instructions = await resourceService.previewSkill(
+        commands,
+        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]),