@cyberismo/data-handler 0.0.20 → 0.0.22

package/dist/utils/rw-lock.d.ts

@@ -0,0 +1,71 @@
+/**
+  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/>.
+*/
+/**
+ * Promise-based read-write lock with writer priority and reentrancy.
+ *
+ * - Multiple concurrent readers are allowed.
+ * - Writers get exclusive access.
+ * - Writer-priority: new readers block when a writer is waiting.
+ * - Reentrancy via AsyncLocalStorage: nested lock calls within the same
+ *   async context are no-ops.
+ * - After-write hooks fire after the outermost write completes successfully.
+ */
+export declare class RWLock {
+    private readonly name;
+    private readers;
+    private writer;
+    private readerQueue;
+    private writerQueue;
+    private context;
+    private afterWriteHooks;
+    private writeErrorHooks;
+    private readonly logger;
+    constructor(name?: string);
+    /**
+     * Register a callback that fires after the outermost write completes
+     * successfully. Hooks run while still holding the write lock.
+     */
+    onAfterWrite(hook: () => Promise<void>): void;
+    /**
+     * Register a callback that fires when the outermost write fails.
+     * Hooks run while still holding the write lock.
+     */
+    onWriteError(hook: (error: unknown) => Promise<void>): void;
+    /**
+     * Execute `fn` under a read lock. Concurrent readers are allowed.
+     * If already inside a read or write context, just runs fn directly.
+     */
+    read<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute `fn` under an exclusive write lock.
+     * If already inside a write context, just runs fn directly (no hooks).
+     */
+    write<T>(fn: () => Promise<T>): Promise<T>;
+    private acquireRead;
+    private releaseRead;
+    private acquireWrite;
+    private releaseWrite;
+}
+/**
+ * A Helper decorator built for commands that automatically handles using a read lock
+ */
+export declare function read<This extends object, Args extends unknown[], Return>(target: (this: This, ...args: Args) => Promise<Return>): (this: This, ...args: Args) => Promise<Return>;
+/**
+ * A Helper decorator built for commands that automatically handles using a write lock.
+ *
+ * Two forms:
+ * - `@write()`: just acquires the write lock, no commit message (for wrapper methods)
+ * - `@write((param) => \`Do ${param}\`)`: acquires the write lock and sets a default commit message
+ */
+export declare function write<This extends object, Args extends unknown[], Return>(): (target: (this: This, ...args: Args) => Promise<Return>) => (this: This, ...args: Args) => Promise<Return>;
+export declare function write<This extends object, Args extends unknown[], Return>(message: (...args: any[]) => string): (target: (this: This, ...args: Args) => Promise<Return>) => (this: This, ...args: Args) => Promise<Return>;

package/dist/utils/rw-lock.js

@@ -0,0 +1,220 @@
+/**
+  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 { AsyncLocalStorage } from 'node:async_hooks';
+import { runWithDefaultCommitMessage } from './commit-context.js';
+import { getChildLogger } from './log-utils.js';
+/**
+ * Promise-based read-write lock with writer priority and reentrancy.
+ *
+ * - Multiple concurrent readers are allowed.
+ * - Writers get exclusive access.
+ * - Writer-priority: new readers block when a writer is waiting.
+ * - Reentrancy via AsyncLocalStorage: nested lock calls within the same
+ *   async context are no-ops.
+ * - After-write hooks fire after the outermost write completes successfully.
+ */
+export class RWLock {
+    name;
+    readers = 0;
+    writer = false;
+    readerQueue = [];
+    writerQueue = [];
+    context = new AsyncLocalStorage();
+    afterWriteHooks = [];
+    writeErrorHooks = [];
+    logger;
+    constructor(name = 'RWLock') {
+        this.name = name;
+        this.logger = getChildLogger({ module: 'RWLock', name });
+    }
+    /**
+     * Register a callback that fires after the outermost write completes
+     * successfully. Hooks run while still holding the write lock.
+     */
+    onAfterWrite(hook) {
+        this.afterWriteHooks.push(hook);
+    }
+    /**
+     * Register a callback that fires when the outermost write fails.
+     * Hooks run while still holding the write lock.
+     */
+    onWriteError(hook) {
+        this.writeErrorHooks.push(hook);
+    }
+    /**
+     * Execute `fn` under a read lock. Concurrent readers are allowed.
+     * If already inside a read or write context, just runs fn directly.
+     */
+    async read(fn) {
+        const current = this.context.getStore();
+        if (current?.active) {
+            return fn();
+        }
+        await this.acquireRead();
+        const ctx = { mode: 'read', active: true };
+        try {
+            return await this.context.run(ctx, fn);
+        }
+        finally {
+            ctx.active = false;
+            this.releaseRead();
+        }
+    }
+    /**
+     * Execute `fn` under an exclusive write lock.
+     * If already inside a write context, just runs fn directly (no hooks).
+     */
+    async write(fn) {
+        const current = this.context.getStore();
+        if (current?.active && current.mode === 'write') {
+            return fn();
+        }
+        if (current?.active && current.mode === 'read') {
+            throw new Error('Cannot acquire write lock while holding read lock');
+        }
+        await this.acquireWrite();
+        const ctx = { mode: 'write', active: true };
+        try {
+            const result = await this.context.run(ctx, fn);
+            // Fire after-write hooks while still holding the lock
+            for (const hook of this.afterWriteHooks) {
+                await this.context.run(ctx, hook);
+            }
+            return result;
+        }
+        catch (error) {
+            // Run rollback hooks on error (outermost write only)
+            for (const hook of this.writeErrorHooks) {
+                await this.context.run(ctx, () => hook(error));
+            }
+            throw error;
+        }
+        finally {
+            ctx.active = false;
+            this.releaseWrite();
+        }
+    }
+    acquireRead() {
+        if (!this.writer && this.writerQueue.length === 0) {
+            this.readers++;
+            this.logger.trace({ readers: this.readers }, 'read lock acquired');
+            return Promise.resolve();
+        }
+        this.logger.debug({
+            readers: this.readers,
+            writer: this.writer,
+            writerQueueDepth: this.writerQueue.length,
+            readerQueueDepth: this.readerQueue.length,
+        }, 'read lock queued (writer active or pending)');
+        return new Promise((resolve) => {
+            this.readerQueue.push(() => {
+                this.readers++;
+                this.logger.debug({
+                    readers: this.readers,
+                    writerQueueDepth: this.writerQueue.length,
+                    readerQueueDepth: this.readerQueue.length,
+                }, 'read lock acquired after wait');
+                resolve();
+            });
+        });
+    }
+    releaseRead() {
+        this.readers--;
+        this.logger.trace({
+            readers: this.readers,
+            writerQueueDepth: this.writerQueue.length,
+            readerQueueDepth: this.readerQueue.length,
+        }, 'read lock released');
+        if (this.readers === 0 && this.writerQueue.length > 0) {
+            const next = this.writerQueue.shift();
+            next();
+        }
+    }
+    acquireWrite() {
+        if (!this.writer && this.readers === 0) {
+            this.writer = true;
+            this.logger.trace({
+                readers: this.readers,
+                writerQueueDepth: this.writerQueue.length,
+                readerQueueDepth: this.readerQueue.length,
+            }, 'write lock acquired');
+            return Promise.resolve();
+        }
+        this.logger.debug({
+            readers: this.readers,
+            writer: this.writer,
+            writerQueueDepth: this.writerQueue.length,
+            readerQueueDepth: this.readerQueue.length,
+        }, `write lock queued (readers: ${this.readers}, writer active: ${this.writer})`);
+        return new Promise((resolve) => {
+            this.writerQueue.push(() => {
+                this.writer = true;
+                this.logger.debug({
+                    readers: this.readers,
+                    writerQueueDepth: this.writerQueue.length,
+                    readerQueueDepth: this.readerQueue.length,
+                }, 'write lock acquired after wait');
+                resolve();
+            });
+        });
+    }
+    releaseWrite() {
+        this.writer = false;
+        this.logger.trace({
+            readers: this.readers,
+            writerQueueDepth: this.writerQueue.length,
+            readerQueueDepth: this.readerQueue.length,
+        }, 'write lock released');
+        if (this.writerQueue.length > 0) {
+            const next = this.writerQueue.shift();
+            next();
+        }
+        else {
+            // Wake ALL waiting readers
+            const readers = this.readerQueue.splice(0);
+            for (const wake of readers) {
+                wake();
+            }
+        }
+    }
+}
+// Helper to access the lock from a command instance via its `project` property.
+function getLock(instance) {
+    const lock = instance.project?.lock;
+    if (!lock) {
+        throw new Error('@read/@write decorator: instance.project.lock is not defined. ' +
+            'Ensure the class has a `project` property with `lock: RWLock`.');
+    }
+    return lock;
+}
+/**
+ * A Helper decorator built for commands that automatically handles using a read lock
+ */
+export function read(target) {
+    return function (...args) {
+        return getLock(this).read(() => target.call(this, ...args));
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function write(message) {
+    return function (target) {
+        return function (...args) {
+            if (!message) {
+                return getLock(this).write(() => target.call(this, ...args));
+            }
+            const label = message(...args);
+            return runWithDefaultCommitMessage(label, () => getLock(this).write(() => target.call(this, ...args)));
+        };
+    };
+}
+//# sourceMappingURL=rw-lock.js.map

package/dist/utils/rw-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rw-lock.js","sourceRoot":"","sources":["../../src/utils/rw-lock.ts"],"names":[],"mappings":"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"}

package/dist/utils/user-preferences.js

@@ -97,14 +97,14 @@ export class UserPreferences {
             if (hasCode(error)) {
                 // If file already exists (EEXIST), that's fine - we'll use the existing file
                 if (error.code !== 'EEXIST') {
-                    throw new Error(`Error creating preferences file '${this.prefsFilePath}': ${error}`);
+                    throw new Error(`Error creating preferences file '${this.prefsFilePath}': ${error}`, { cause: error });
                 }
                 else {
                     this.logger.warn('Preferences file already exists');
                 }
             }
             else {
-                throw new Error(`Error creating preferences file '${this.prefsFilePath}': ${error}`);
+                throw new Error(`Error creating preferences file '${this.prefsFilePath}': ${error}`, { cause: error });
             }
         }
     }
@@ -119,7 +119,7 @@ export class UserPreferences {
             return JSON.parse(readFileSync(this.prefsFilePath, 'utf8'));
         }
         catch (error) {
-            throw new Error(`Error reading preferences file '${this.prefsFilePath}': ${error}`);
+            throw new Error(`Error reading preferences file '${this.prefsFilePath}': ${error}`, { cause: error });
         }
     }
 }

package/dist/utils/user-preferences.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-preferences.js","sourceRoot":"","sources":["../../src/utils/user-preferences.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"user-preferences.js","sourceRoot":"","sources":["../../src/utils/user-preferences.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cyberismo/data-handler",
   "description": "Command handler for cards and web service",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "author": "sami.merila@cyberismo.com",
   "license": "AGPL-3.0",
   "homepage": "https://github.com/CyberismoCom/cyberismo",
@@ -21,14 +21,14 @@
     "@types/jsdom": "^21.1.7",
     "@types/json-schema": "^7.0.15",
     "@types/sinon": "^21.0.0",
-    "c8": "^10.1.3",
+    "c8": "^11.0.0",
     "pino-pretty": "^13.1.3",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.1"
   },
   "dependencies": {
     "@asciidoctor/core": "^3.0.4",
     "@types/mime-types": "^3.0.1",
-    "@viz-js/viz": "^3.20.0",
+    "@viz-js/viz": "^3.24.0",
     "async-mutex": "^0.5.0",
     "csv-parse": "^6.1.0",
     "directory-schema-validator": "^1.0.17",
@@ -39,16 +39,16 @@
     "json-schema": "^0.4.0",
     "jsonschema": "^1.5.0",
     "mime-types": "^3.0.2",
-    "pino": "^10.1.0",
-    "simple-git": "^3.29.0",
+    "pino": "^10.3.0",
+    "simple-git": "^3.30.0",
     "string-pixel-width": "^1.11.0",
     "tslib": "^2.6.2",
     "vega": "^6.2.0",
-    "vega-lite": "^6.4.1",
+    "vega-lite": "^6.4.2",
     "write-json-file": "^7.0.0",
-    "@cyberismo/assets": "0.0.20",
-    "@cyberismo/migrations": "0.0.20",
-    "@cyberismo/node-clingo": "1.3.4"
+    "@cyberismo/migrations": "0.0.22",
+    "@cyberismo/node-clingo": "1.3.4",
+    "@cyberismo/assets": "0.0.22"
   },
   "type": "module",
   "files": [

package/src/command-handler.ts

@@ -163,12 +163,10 @@ export class Commands {
     const path = options.projectPath || '';
     this.projectPath = resolveTilde(await this.setProjectPath(path));
     if (!Validate.validateFolder(this.projectPath)) {
-      let errorMessage = '';
-      if (path === '' || path === undefined) {
-        errorMessage = `No 'cardRoot' in the current folder`;
-      } else {
-        errorMessage = `Input validation error: folder name '${path}' is invalid`;
-      }
+      const errorMessage =
+        path === '' || path === undefined
+          ? `No 'cardRoot' in the current folder`
+          : `Input validation error: folder name '${path}' is invalid`;
       throw new Error(errorMessage);
     }
 
@@ -180,6 +178,7 @@ export class Commands {
       logLevel: options.logLevel,
       watchResourceChanges: (options as StartCommandOptions)
         .watchResourceChanges,
+      autocommit: (options as StartCommandOptions).autocommit,
     });
     if (!this.commands) {
       throw new Error('Cannot get instance of CommandManager');
@@ -426,6 +425,7 @@ export class Commands {
           } catch (error) {
             throw new Error(
               `Failed to read mapping file: ${errorFunction(error)}`,
+              { cause: error },
             );
           }
         }
@@ -574,7 +574,7 @@ export class Commands {
       return { statusCode: 500 };
     }
     process.env.EXPORT_FORMAT = format;
-    let message = '';
+    let message: string;
     if (format === 'pdf') {
       const options = {
         title: pdfOptions?.title || 'Title',
@@ -717,7 +717,7 @@ export class Commands {
     }
 
     const { name, parameters } = parametersFile;
-    let result: string | undefined = '';
+    let result: string | undefined;
     try {
       result = await this.commands?.showCmd.showReportResults(
         name,
@@ -758,12 +758,9 @@ export class Commands {
       case 'attachments':
         promise = this.commands!.showCmd.showAttachments();
         break;
-      case 'card': {
-        return {
-          statusCode: 200,
-          payload: this.commands!.showCmd.showCardDetails(detail),
-        };
-      }
+      case 'card':
+        promise = this.commands!.showCmd.showCardDetails(detail);
+        break;
       case 'cards':
         promise = this.commands!.showCmd.showCards();
         break;
@@ -796,10 +793,8 @@ export class Commands {
         );
         break;
       case 'labels':
-        return {
-          statusCode: 200,
-          payload: this.commands!.showCmd.showLabels(),
-        };
+        promise = this.commands!.showCmd.showLabels();
+        break;
       case 'module':
         promise = this.commands!.showCmd.showModule(detail);
         break;
@@ -807,10 +802,7 @@ export class Commands {
         promise = this.commands!.showCmd.showHubs();
         break;
       case 'modules':
-        return {
-          statusCode: 200,
-          payload: this.commands!.showCmd.showModules(),
-        };
+        promise = this.commands!.showCmd.showModules();
         break;
       case 'project':
         promise = this.commands!.showCmd.showProject();

package/src/command-manager.ts

@@ -25,14 +25,16 @@ import { Transition } from './commands/transition.js';
 import { Update } from './commands/update.js';
 import { Validate } from './commands/validate.js';
 import { Project } from './containers/project.js';
-import { ProjectPaths } from './containers/project/project-paths.js';
-import pino, { type Level, type TransportTargetOptions } from 'pino';
-import { setLogger } from './utils/log-utils.js';
+import { runWithCommitContext } from './utils/commit-context.js';
+import { type Level } from 'pino';
+import { join } from 'node:path';
+import { initLogger } from './utils/log-utils.js';
 
 export interface CommandManagerOptions {
   watchResourceChanges?: boolean;
   autoSaveConfiguration?: boolean;
   logLevel?: Level;
+  autocommit?: boolean;
 }
 
 // Handles commands and ensures that no extra instances are created.
@@ -55,12 +57,11 @@ export class CommandManager {
   public updateCmd: Update;
   public validateCmd: Validate;
 
-  private pathHandler: ProjectPaths;
-
   constructor(path: string, options?: CommandManagerOptions) {
     this.project = new Project(path, {
       autoSave: options?.autoSaveConfiguration,
       watchResourceChanges: options?.watchResourceChanges,
+      autocommit: options?.autocommit,
     });
     this.validateCmd = Validate.getInstance();
 
@@ -77,7 +78,6 @@ export class CommandManager {
     this.renameCmd = new Rename(this.project);
     this.transitionCmd = new Transition(this.project);
     this.updateCmd = new Update(this.project);
-    this.pathHandler = new ProjectPaths(path);
   }
 
   /**
@@ -90,6 +90,36 @@ export class CommandManager {
     return this.project.configuration.checkSchemaVersion();
   }
 
+  /**
+   * Run a function with the given author set in async-local context.
+   * Git commits made during the function will use this author.
+   */
+  public runAsAuthor<T>(
+    author: { name: string; email: string },
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    return runWithCommitContext({ author }, fn);
+  }
+
+  /**
+   * Execute multiple commands as a single atomic write transaction.
+   * All inner @write/@read calls reuse the same lock context.
+   * Git commit fires once on success; rollback on any error.
+   */
+  public async atomic<T>(fn: () => Promise<T>, message: string): Promise<T> {
+    const run = () => this.project.lock.write(fn);
+    return runWithCommitContext({ message }, run);
+  }
+
+  /**
+   * Execute multiple commands under a consistent read snapshot.
+   * All inner @read calls reuse the same lock context.
+   * Writers are blocked for the duration.
+   */
+  public async consistent<T>(fn: () => Promise<T>): Promise<T> {
+    return this.project.lock.read(fn);
+  }
+
   /**
    * Some commands needs initialization that cannot be performed inside constructor.
    * Add such calls here.
@@ -97,34 +127,7 @@ export class CommandManager {
   public async initialize() {
     this.project.resources.changedModules();
     await this.project.populateCaches();
-  }
-
-  /**
-   * Sets the logger for the command manager.
-   * @param level Log level.
-   */
-  public setLogger(level: Level) {
-    const all: TransportTargetOptions[] = [
-      {
-        target: 'pino/file',
-        level: 'trace',
-        options: { destination: this.pathHandler.logPath, mkdir: true },
-      },
-      {
-        target: 'pino/file',
-        level: level,
-        options: { destination: 1 }, // stdout
-      },
-    ];
-
-    setLogger(
-      pino({
-        level: 'trace',
-        transport: {
-          targets: all,
-        },
-      }),
-    );
+    await this.project.initializeGit();
   }
 
   /**
@@ -138,6 +141,12 @@ export class CommandManager {
     path: string,
     options?: CommandManagerOptions,
   ): Promise<CommandManager> {
+    // Set up logger before constructing anything so eager child loggers work
+    if (options?.logLevel) {
+      const logPath = join(path, '.logs', 'cyberismo_data-handler.log');
+      initLogger(options.logLevel, logPath);
+    }
+
     if (
       CommandManager.instance &&
       CommandManager.instance.project.basePath !== path
@@ -151,9 +160,6 @@ export class CommandManager {
       await CommandManager.instance.initialize();
     }
 
-    if (options?.logLevel) {
-      CommandManager.instance.setLogger(options?.logLevel);
-    }
     return CommandManager.instance;
   }
 }

package/src/commands/calculate.ts

@@ -14,6 +14,7 @@
 import type { Context } from '../interfaces/project-interfaces.js';
 import type { Project } from '../containers/project.js';
 import type { QueryName, QueryResult } from '../types/queries.js';
+import { read } from '../utils/rw-lock.js';
 
 // Class that calculates with logic program card / project level calculations.
 export class Calculate {
@@ -25,6 +26,7 @@ export class Calculate {
    * @param programs Programs or categories to export
    * @param query Query to export, if not provided, all programs will be exported
    */
+  @read
   public async exportLogicProgram(
     destination: string,
     programs: string[] = ['all'],
@@ -40,6 +42,7 @@ export class Calculate {
   /**
    * Generates a logic program.
    */
+  @read
   public async generate() {
     return this.project.calculationEngine.generate();
   }
@@ -50,6 +53,7 @@ export class Calculate {
    * @param timeout Maximum amount of milliseconds clingraph is allowed to run
    * @returns a base64 encoded image as a string
    */
+  @read
   public async runGraph(model: string, view: string, context: Context) {
     return this.project.calculationEngine.runGraph(model, view, context);
   }
@@ -59,6 +63,7 @@ export class Calculate {
    * @param query Logic program to be run
    * @returns parsed program output
    */
+  @read
   public async runLogicProgram(query: string, context: Context = 'localApp') {
     return this.project.calculationEngine.runLogicProgram(query, context);
   }
@@ -74,6 +79,8 @@ export class Calculate {
     context: Context = 'localApp',
     options?: unknown,
   ): Promise<QueryResult<T>[]> {
-    return this.project.calculationEngine.runQuery(queryName, context, options);
+    return this.project.lock.read(async () =>
+      this.project.calculationEngine.runQuery(queryName, context, options),
+    );
   }
 }