@cyberismo/data-handler 0.0.21 → 0.0.22

package/src/interfaces/resource-interfaces.ts

@@ -83,18 +83,14 @@ export interface FieldType extends ResourceBaseMetadata {
 }
 
 // Graph model content.
-export interface GraphModelMetadata extends ResourceBaseMetadata {
-  category?: string;
-}
+export type GraphModelMetadata = ResourceBaseMetadata;
 export interface GraphModel extends GraphModelMetadata {
   content: GraphModelContent;
 }
 export type GraphModelContentPropertyName = 'model';
 
 // Graph view content.
-export interface GraphViewMetadata extends ResourceBaseMetadata {
-  category?: string;
-}
+export type GraphViewMetadata = ResourceBaseMetadata;
 export type GraphViewContentPropertyName = 'viewTemplate';
 export interface GraphView extends GraphViewMetadata {
   content: GraphViewContent;
@@ -128,13 +124,12 @@ export type ReportContentPropertyName =
   | 'schema';
 
 // Metadata for report
-export interface ReportMetadata extends ResourceBaseMetadata {
-  category: string;
-}
+export type ReportMetadata = ResourceBaseMetadata;
 
 // Base interface for all resources.
 export interface ResourceBaseMetadata {
   name: string;
+  category?: string;
   description?: string;
   displayName: string;
   usedIn?: string[];
@@ -173,9 +168,7 @@ export interface TemplateConfiguration extends TemplateMetadata {
 }
 
 // Template configuration content details.
-export interface TemplateMetadata extends ResourceBaseMetadata {
-  category?: string;
-}
+export type TemplateMetadata = ResourceBaseMetadata;
 type ContentUpdateKey = { key: 'content'; subKey: string };
 type PropertyUpdateKey<K extends string = string> = {
   key: Exclude<K, 'content'>;

package/src/macros/base-macro.ts

@@ -134,7 +134,7 @@ abstract class BaseMacro {
       } catch (error) {
         if (error instanceof Error) {
           const errorMessage = `From card '${context.cardKey}' a macro validation error:\n\n${error.message}.\n\nCard content:\n ${input}`;
-          throw new Error(errorMessage);
+          throw new Error(errorMessage, { cause: error });
         }
         throw error;
       }

package/src/macros/graph/index.ts

@@ -13,6 +13,7 @@
 
 import BaseMacro from '../base-macro.js';
 import { createImage, validateMacroContent } from '../index.js';
+import { registerComparisonHelpers } from '../../utils/handlebars-helpers.js';
 import Handlebars from 'handlebars';
 import macroMetadata from './metadata.js';
 import { ClingoError } from '@cyberismo/node-clingo';
@@ -54,6 +55,7 @@ class GraphMacro extends BaseMacro {
     };
 
     const handlebars = Handlebars.create();
+    registerComparisonHelpers(handlebars);
     const view = handlebars.compile(viewContent.viewTemplate)(
       handlebarsContext,
     );
@@ -69,6 +71,7 @@ class GraphMacro extends BaseMacro {
       if (error instanceof ClingoError) {
         throw new Error(
           `Error running graph in view '${options.view}' in model '${options.model}': ${error.details.errors.join('\n')}`,
+          { cause: error },
         );
       }
       throw error;

package/src/macros/index.ts

@@ -175,7 +175,9 @@ export function validateMacroContent<T>(
     if (error instanceof DHValidationError) {
       message = `${error.errors?.map((e) => e.message).join(', ')}`;
     }
-    throw new Error(`${macro.name} macro JSON validation error: ${message}`);
+    throw new Error(`${macro.name} macro JSON validation error: ${message}`, {
+      cause: error,
+    });
   }
 }
 

package/src/macros/report/index.ts

@@ -56,6 +56,7 @@ class ReportMacro extends BaseMacro {
       if (error instanceof ClingoError) {
         throw new Error(
           `Error running logic program in report '${options.name}':${error.details.errors.join('\n')}`,
+          { cause: error },
         );
       }
       throw error;

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

@@ -281,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;

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/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');
+  }
+}