@cyberismo/data-handler 0.0.20 → 0.0.22

package/src/module-manager.ts

@@ -157,6 +157,7 @@ export class ModuleManager {
       if (error instanceof Error)
         throw new Error(
           `Failed to clone module '${module.name}': ${error.message}`,
+          { cause: error },
         );
     }
 
@@ -245,7 +246,7 @@ export class ModuleManager {
     module: ModuleSetting,
     credentials?: Credentials,
   ) {
-    let moduleRoot = '';
+    let moduleRoot: string;
     if (this.isFileModule(module)) {
       const urlStart = FILE_PROTOCOL.length;
       // Remove 'file:' from location
@@ -350,7 +351,9 @@ export class ModuleManager {
         });
       }
     } catch (error) {
-      throw new Error(`Failed to prepare temporary directory: ${error}`);
+      throw new Error(`Failed to prepare temporary directory: ${error}`, {
+        cause: error,
+      });
     }
   }
 

package/src/project-settings.ts

@@ -150,6 +150,7 @@ export class ProjectConfiguration implements ProjectSettings {
       if (error instanceof TypeError) {
         throw new Error(
           `Invalid hub URL '${trimmedHub}'. Please provide a valid HTTP or HTTPS URL.`,
+          { cause: error },
         );
       }
       throw error;
@@ -195,7 +196,7 @@ export class ProjectConfiguration implements ProjectSettings {
     if (this.schemaVersion < SCHEMA_VERSION) {
       return {
         isCompatible: false,
-        message: `Schema version mismatch: Project schema version (${this.schemaVersion}) is older than the application schema version (${SCHEMA_VERSION}). A migration is needed.`,
+        message: `Schema version mismatch: Project schema version (${this.schemaVersion}) is older than the application schema version (${SCHEMA_VERSION}). A migration is needed. Run 'cyberismo migrate' to update the project schema.`,
       };
     }
 

package/src/resources/card-type-resource.ts

@@ -448,7 +448,7 @@ export class CardTypeResource extends FileResource<CardType> {
   ) {
     const { key } = updateKey;
 
-    if (key === 'name' || key === 'description' || key === 'displayName') {
+    if (this.isBaseProperty(key)) {
       await super.update(updateKey, op);
     } else {
       const content = structuredClone(this.content);

package/src/resources/create-defaults.ts

@@ -184,7 +184,6 @@ export abstract class DefaultContent {
     return {
       name: reportName,
       displayName: '',
-      category: 'Uncategorised report',
     };
   }
 

package/src/resources/field-type-resource.ts

@@ -408,16 +408,14 @@ export class FieldTypeResource extends FileResource<FieldType> {
   ) {
     const { key } = updateKey;
 
-    if (key === 'name' || key === 'description' || key === 'displayName') {
+    if (this.isBaseProperty(key)) {
       await super.update(updateKey, op);
     } else {
       const content = structuredClone(this.content);
       const typeChange = key === 'dataType';
       const enumChange = key === 'enumValues';
       const existingType = this.content.dataType;
-      if (key === 'name') {
-        content.name = super.handleScalar(op) as string;
-      } else if (key === 'dataType') {
+      if (key === 'dataType') {
         const toType = op as ChangeOperation<DataType>;
         if (!FieldTypeResource.fieldDataTypes().includes(toType.to)) {
           throw new Error(

package/src/resources/file-resource.ts

@@ -118,8 +118,10 @@ export abstract class FileResource<
       content.displayName = super.handleScalar(op) as string;
     } else if (key === 'description') {
       content.description = super.handleScalar(op) as string;
+    } else if (key === 'category') {
+      content.category = super.handleScalar(op) as string;
     } else {
-      throw new Error(`Unknown property '${key}' for folder resource`);
+      throw new Error(`Unknown property '${key}' for file resource`);
     }
 
     await super.postUpdate(content, updateKey, op);

package/src/resources/folder-resource.ts

@@ -62,7 +62,7 @@ export abstract class FolderResource<
    * Creates a new folder type object. Base class writes the object to disk automatically.
    * @param newContent Content for the type.
    */
-  protected async create(newContent?: T) {
+  public async create(newContent?: T) {
     // Validate resource identifier before creating on disk
     this.validateResourceIdentifier();
     await super.create(newContent);
@@ -154,7 +154,10 @@ export abstract class FolderResource<
       } catch (error) {
         const message =
           error instanceof Error ? error.message : 'Unknown error';
-        throw new Error(`Invalid JSON content for '${key}' update: ${message}`);
+        throw new Error(
+          `Invalid JSON content for '${key}' update: ${message}`,
+          { cause: error },
+        );
       }
     }
     const contentToWrite = isJson
@@ -252,6 +255,8 @@ export abstract class FolderResource<
       content.displayName = super.handleScalar(op) as string;
     } else if (key === 'description') {
       content.description = super.handleScalar(op) as string;
+    } else if (key === 'category') {
+      content.category = super.handleScalar(op) as string;
     } else {
       throw new Error(`Unknown property '${key}' for folder resource`);
     }

package/src/resources/graph-model-resource.ts

@@ -22,12 +22,8 @@ import { writeFileSafe } from '../utils/file-utils.js';
 import { CONTENT_FILES } from '../interfaces/folder-content-interfaces.js';
 
 import type { Card } from '../interfaces/project-interfaces.js';
-import type {
-  GraphModelMetadata,
-  UpdateKey,
-} from '../interfaces/resource-interfaces.js';
+import type { GraphModelMetadata } from '../interfaces/resource-interfaces.js';
 import type { GraphModelContent } from '../interfaces/folder-content-interfaces.js';
-import type { Operation } from './resource-object.js';
 import type { Project } from '../containers/project.js';
 import type { ResourceName } from '../utils/resource-utils.js';
 
@@ -103,26 +99,6 @@ export class GraphModelResource extends FolderResource<
     return this.onNameChange(existingName);
   }
 
-  /**
-   * Updates graph model resource.
-   * @param updateKey Key to modify
-   * @param op Operation to perform on 'key'
-   */
-  public async update<Type, K extends string>(
-    updateKey: UpdateKey<K>,
-    op: Operation<Type>,
-  ) {
-    if (updateKey.key === 'category') {
-      const content = structuredClone(this.content);
-      content.category = super.handleScalar(op) as string;
-
-      await super.postUpdate(content, updateKey, op);
-      return;
-    }
-
-    await super.update(updateKey, op);
-  }
-
   /**
    * List where this resource is used.
    * Always returns card key references first, then calculation references.

package/src/resources/graph-view-resource.ts

@@ -24,11 +24,7 @@ import { sortCards } from '../utils/card-utils.js';
 
 import type { Card } from '../interfaces/project-interfaces.js';
 import type { GraphViewContent } from '../interfaces/folder-content-interfaces.js';
-import type {
-  GraphViewMetadata,
-  UpdateKey,
-} from '../interfaces/resource-interfaces.js';
-import type { Operation } from './resource-object.js';
+import type { GraphViewMetadata } from '../interfaces/resource-interfaces.js';
 import type { Project } from '../containers/project.js';
 import type { ResourceName } from '../utils/resource-utils.js';
 
@@ -115,26 +111,6 @@ export class GraphViewResource extends FolderResource<
     return this.onNameChange(existingName);
   }
 
-  /**
-   * Updates graph view resource.
-   * @param updateKey Key to modify
-   * @param op Operation to perform on 'key'
-   */
-  public async update<Type, K extends string>(
-    updateKey: UpdateKey<K>,
-    op: Operation<Type>,
-  ) {
-    if (updateKey.key === 'category') {
-      const content = structuredClone(this.content) as GraphViewMetadata;
-      content.category = super.handleScalar(op) as string;
-
-      await super.postUpdate(content, updateKey, op);
-      return;
-    }
-
-    await super.update(updateKey, op);
-  }
-
   /**
    * List where this resource is used.
    * Always returns card key references first, then calculation references.

package/src/resources/link-type-resource.ts

@@ -127,7 +127,7 @@ export class LinkTypeResource extends FileResource<LinkType> {
   ) {
     const { key } = updateKey;
 
-    if (key === 'name' || key === 'displayName' || key === 'description') {
+    if (this.isBaseProperty(key)) {
       await super.update(updateKey, op);
     } else {
       const content = structuredClone(this.content);

package/src/resources/report-resource.ts

@@ -24,13 +24,9 @@ import { sortCards } from '../utils/card-utils.js';
 import { Validate } from '../commands/validate.js';
 
 import type { Card } from '../interfaces/project-interfaces.js';
-import type { Operation } from './resource-object.js';
 import type { Project } from '../containers/project.js';
 import type { ReportContent } from '../interfaces/folder-content-interfaces.js';
-import type {
-  ReportMetadata,
-  UpdateKey,
-} from '../interfaces/resource-interfaces.js';
+import type { ReportMetadata } from '../interfaces/resource-interfaces.js';
 import type { ResourceName } from '../utils/resource-utils.js';
 
 const PARAMETER_SCHEMA_ID = 'jsonSchema';
@@ -120,26 +116,6 @@ export class ReportResource extends FolderResource<
     return this.onNameChange(existingName);
   }
 
-  /**
-   * Updates report resource.
-   * @param updateKey Key to modify
-   * @param op Operation to perform on 'key'
-   */
-  public async update<Type, K extends string>(
-    updateKey: UpdateKey<K>,
-    op: Operation<Type>,
-  ) {
-    if (updateKey.key === 'category') {
-      const content = structuredClone(this.content);
-      content.category = super.handleScalar(op) as string;
-
-      await super.postUpdate(content, updateKey, op);
-      return;
-    }
-
-    await super.update(updateKey, op);
-  }
-
   /**
    * List where this resource is used.
    * Always returns card key references first, then calculation references.

package/src/resources/resource-object.ts

@@ -270,7 +270,7 @@ export abstract class ResourceObject<
    * @param newContent Content for resource.
    * @throws when resource already exists in the project.
    */
-  protected async create(newContent?: T) {
+  public async create(newContent?: T) {
     this.validateResourceIdentifier();
 
     if (this.exists()) {
@@ -357,6 +357,7 @@ export abstract class ResourceObject<
       if (error instanceof Error) {
         throw new Error(
           `Cannot perform operation on '${arrayName}'. ${error.message}`,
+          { cause: error },
         );
       }
     }
@@ -507,6 +508,7 @@ export abstract class ResourceObject<
         const errorValue = typeof op === 'object' ? toValue(op) : op;
         throw new Error(
           `Cannot ${op.name} '${updateKey.key}' --> '${errorValue}: ${error.message}'`,
+          { cause: error },
         );
       }
     }
@@ -576,6 +578,25 @@ export abstract class ResourceObject<
     } as ChangeOperation<string>);
   }
 
+  /**
+   * Base properties shared by all resources.
+   */
+  private static readonly BASE_PROPERTIES = [
+    'name',
+    'displayName',
+    'description',
+    'category',
+  ] as const;
+
+  /**
+   * Checks if the given key is a base property shared by all resources.
+   * @param key The property key to check
+   * @returns true if the key is a base property
+   */
+  protected isBaseProperty(key: string): boolean {
+    return (ResourceObject.BASE_PROPERTIES as readonly string[]).includes(key);
+  }
+
   /**
    * Update resource; the base class makes some checks only.
    * @template type Resource type

package/src/resources/template-resource.ts

@@ -22,13 +22,11 @@ import { Template } from '../containers/template.js';
 import { writeJsonFile } from '../utils/json.js';
 
 import type { Card } from '../interfaces/project-interfaces.js';
-import type { Operation } from './resource-object.js';
 import type { Project } from '../containers/project.js';
 import type { ResourceName } from '../utils/resource-utils.js';
 import type {
   TemplateConfiguration,
   TemplateMetadata,
-  UpdateKey,
 } from '../interfaces/resource-interfaces.js';
 
 /**
@@ -135,27 +133,6 @@ export class TemplateResource extends FolderResource<TemplateMetadata, never> {
     return this.cardContainer;
   }
 
-  /**
-   * Updates template resource.
-   * @param updateKey Key to modify
-   * @param op Operation to perform on 'key'
-   * @throws if key is unknown.
-   */
-  public async update<Type, K extends string>(
-    updateKey: UpdateKey<K>,
-    op: Operation<Type>,
-  ) {
-    if (updateKey.key === 'category') {
-      const content = structuredClone(this.content);
-      content.category = super.handleScalar(op) as string;
-
-      await super.postUpdate(content, updateKey, op);
-      return;
-    }
-
-    await super.update(updateKey, op);
-  }
-
   /**
    * List where template is used.
    * Always returns card key references first, then calculation references.

package/src/resources/workflow-resource.ts

@@ -78,16 +78,11 @@ export class WorkflowResource extends FileResource<Workflow> {
   }
 
   // Handle change of workflow state.
-  private async handleStateChange(op: ChangeOperation<WorkflowState>) {
-    const content = structuredClone(this.content);
+  private async handleStateChange(
+    content: Workflow,
+    op: ChangeOperation<WorkflowState>,
+  ) {
     const stateName = this.targetName(op) as string;
-    // Check that state can be changed to
-    content.transitions = content.transitions.filter(
-      (t) => t.toState !== stateName,
-    );
-    content.transitions.forEach((t) => {
-      t.fromState = t.fromState.filter((state) => state !== stateName);
-    });
     // validate that new state contains 'name' and 'category'
     if (op.to.name === undefined || op.to.category === undefined) {
       throw new Error(
@@ -95,16 +90,26 @@ export class WorkflowResource extends FileResource<Workflow> {
          Updated state must have 'name' and 'category' properties.`,
       );
     }
-    // Update all cards that use this state.
+    // Rename transitions to use the new state name
     const toStateName = op.to.name;
-
+    content.transitions.forEach((t) => {
+      if (t.toState === stateName) {
+        t.toState = toStateName;
+      }
+      t.fromState = t.fromState.map((state) =>
+        state === stateName ? toStateName : state,
+      );
+    });
+    // Update all cards that use this state.
     await this.updateCardStates(stateName, toStateName);
   }
 
   // Handle removal of workflow state.
   // State can be removed with or without replacement.
-  private async handleStateRemoval(op: RemoveOperation<WorkflowState>) {
-    const content = structuredClone(this.content);
+  private async handleStateRemoval(
+    content: Workflow,
+    op: RemoveOperation<WorkflowState>,
+  ) {
     const stateName = this.targetName(op) as string;
 
     // If there is no replacement value, remove all transitions "to" and "from" this state.
@@ -232,6 +237,28 @@ export class WorkflowResource extends FileResource<Workflow> {
     return super.create(newContent);
   }
 
+  /**
+   * Validates the content of the workflow resource.
+   * @param content Content to be validated.
+   * @throws if content is invalid.
+   */
+  public async validate(content?: Workflow) {
+    // Base class run basic schema checks
+    await super.validate(content);
+
+    const workflowContent = content ?? this.content;
+
+    const newCardTransitions = workflowContent.transitions.filter(
+      (t) => t.fromState.includes('') || t.fromState.length === 0,
+    );
+
+    if (newCardTransitions.length !== 1) {
+      throw new Error(
+        `Workflow '${workflowContent.name}' must have exactly one transition from "New Card" (empty fromState), found ${newCardTransitions.length}.`,
+      );
+    }
+  }
+
   /**
    * Renames the object and the file.
    * @param newName New name for the resource.
@@ -254,7 +281,7 @@ export class WorkflowResource extends FileResource<Workflow> {
   ) {
     const { key } = updateKey;
 
-    if (key === 'name' || key === 'displayName' || key === 'description') {
+    if (this.isBaseProperty(key)) {
       await super.update(updateKey, op);
     } else {
       const content = structuredClone(this.content) as Workflow;
@@ -329,11 +356,13 @@ export class WorkflowResource extends FileResource<Workflow> {
           removeOp = {
             name: 'remove',
             target: toBeRemovedState as WorkflowState,
+            replacementValue: (op as RemoveOperation<unknown>)
+              .replacementValue as WorkflowState,
           };
         } else {
           removeOp = op as RemoveOperation<WorkflowState>;
         }
-        await this.handleStateRemoval(removeOp);
+        await this.handleStateRemoval(content, removeOp);
       } else if (key === 'states' && op.name === 'change') {
         // If workflow state is renamed, replace all transitions "to" and "from" the old state with new state.
         let changeOp: ChangeOperation<WorkflowState>;
@@ -349,7 +378,7 @@ export class WorkflowResource extends FileResource<Workflow> {
         } else {
           changeOp = op as ChangeOperation<WorkflowState>;
         }
-        await this.handleStateChange(changeOp);
+        await this.handleStateChange(content, changeOp);
       }
 
       await super.postUpdate(content, updateKey, op);

package/src/utils/card-utils.ts

@@ -95,7 +95,7 @@ export const cardPathParts = (
   const cardKey = pathParts.at(pathParts.length - 1);
   const parents = [];
   let template = '';
-  let startIndex = -1;
+  let startIndex: number;
   let templatesNameIndex = -1;
 
   const cardRootIndex = pathParts.indexOf('cardRoot');

package/src/utils/commit-context.ts

@@ -0,0 +1,45 @@
+/**
+  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';
+
+export interface CommitContext {
+  message?: string;
+  author?: { name: string; email: string };
+}
+
+const context = new AsyncLocalStorage<CommitContext>();
+
+export function runWithCommitContext<T>(
+  ctx: CommitContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const current = context.getStore();
+  // Merge with any existing context (e.g. author set at middleware level, message set at decorator level)
+  const merged = { ...current, ...ctx };
+  return context.run(merged, fn);
+}
+
+export function getCommitContext(): CommitContext {
+  return context.getStore() ?? {};
+}
+
+export function runWithDefaultCommitMessage<T>(
+  message: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return getCommitContext().message !== undefined
+    ? fn()
+    : runWithCommitContext({ message }, fn);
+}

package/src/utils/csv.ts

@@ -14,6 +14,18 @@ import { readFile } from 'node:fs/promises';
 import { parse } from 'csv-parse/sync';
 import type { CSVRowRaw } from '../interfaces/project-interfaces.js';
 
+/**
+ * Escapes a string for use as a CSV field.
+ * Escapes double quotes by doubling them. The caller is responsible for
+ * wrapping the result in quotes.
+ * @param str The string to escape
+ * @returns The escaped string (without surrounding quotes)
+ */
+export function escapeCsvField(str: string): string {
+  // Escape double quotes by doubling them
+  return str.replace(/"/g, '""');
+}
+
 /**
  * Reads a CSV file and returns its content as an array of objects.
  * @param file Path to the CSV file.

package/src/utils/file-utils.ts

@@ -36,7 +36,9 @@ export async function availableSpace(path: string): Promise<number> {
     const stats = await statfs(path);
     return stats.bavail * stats.bsize;
   } catch (error) {
-    throw new Error(`Failed to check available disk space: ${error}`);
+    throw new Error(`Failed to check available disk space: ${error}`, {
+      cause: error,
+    });
   }
 }
 

package/src/utils/git-manager.ts

@@ -0,0 +1,87 @@
+/**
+  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 { simpleGit, type SimpleGit } from 'simple-git';
+import { getChildLogger } from './log-utils.js';
+
+export class GitManager {
+  private git: SimpleGit;
+  private logger = getChildLogger({ module: 'GitManager' });
+
+  constructor(projectPath: string) {
+    this.git = simpleGit(projectPath, {
+      config: ['user.name=Cyberismo Bot', 'user.email=bot@cyberismo.com'],
+    });
+  }
+
+  /** Ensure the project is a git repo. Idempotent. */
+  async initialize(author?: { name: string; email: string }): Promise<void> {
+    const isRepo = await this.git.checkIsRepo();
+    if (!isRepo) {
+      await this.git.init();
+      // Initial commit so rollback has a baseline
+      await this.git.add('.');
+      const commitOpts: Record<string, string | null> = {
+        '--allow-empty': null,
+      };
+      if (author) {
+        commitOpts['--author'] = `${author.name} <${author.email}>`;
+      }
+      await this.git.commit('Initial commit', undefined, commitOpts);
+      this.logger.info('New repo created with baseline commit');
+    } else {
+      this.logger.debug('Repo already exists');
+    }
+  }
+
+  /** Commit current changes (cardRoot + .cards). */
+  async commit(
+    message: string = 'Autocommit',
+    author?: { name: string; email: string },
+  ): Promise<void> {
+    // Stage only the directories we care about
+    this.logger.debug('Staging changes');
+    await this.git.add(['cardRoot', '.cards']);
+
+    // Check if there's anything to commit
+    const status = await this.git.status();
+    if (status.staged.length === 0) {
+      this.logger.debug('Nothing to commit, skipping');
+      return;
+    }
+
+    this.logger.info(
+      { message, stagedFiles: status.staged.length },
+      'Committing changes',
+    );
+    const commitOpts: Record<string, string> = {};
+    if (author) {
+      commitOpts['--author'] = `${author.name} <${author.email}>`;
+    }
+    await this.git.commit(message, undefined, commitOpts);
+  }
+
+  /** Rollback: restore cardRoot and .cards to last committed state. */
+  async rollback(): Promise<void> {
+    this.logger.info('Rollback starting');
+    // Restore modified tracked files (ignore errors if paths have no tracked content)
+    try {
+      await this.git.checkout(['--', 'cardRoot', '.cards']);
+    } catch {
+      this.logger.debug('No tracked files to restore');
+    }
+    // Remove new untracked files created during the failed write
+    await this.git.clean('f', ['-d', 'cardRoot', '.cards']);
+    this.logger.info('Rollback completed');
+  }
+}