@cyberismo/data-handler 0.0.20 → 0.0.22

package/src/commands/show.ts

@@ -48,6 +48,7 @@ import type { ResourceName } from '../utils/resource-utils.js';
 import type { ResourceMap } from '../containers/project/resource-cache.js';
 
 import { UserPreferences } from '../utils/user-preferences.js';
+import { read, write } from '../utils/rw-lock.js';
 import ReportMacro from '../macros/report/index.js';
 import TaskQueue from '../macros/task-queue.js';
 import { evaluateMacros } from '../macros/index.js';
@@ -146,10 +147,13 @@ export class Show {
    * Shows all template cards in a project.
    * @returns all template cards in a project.
    */
-  public showAllTemplateCards(): {
-    name: string;
-    cards: CardWithChildrenCards[];
-  }[] {
+  @read
+  public async showAllTemplateCards(): Promise<
+    {
+      name: string;
+      cards: CardWithChildrenCards[];
+    }[]
+  > {
     return this.project.resources.templates().map((template) => {
       const cards = template.templateObject().listCards();
       const buildCards = buildCardHierarchy(cards);
@@ -165,6 +169,7 @@ export class Show {
    * Shows all attachments (either template or project attachments) from a project.
    * @returns array of card attachments
    */
+  @read
   public async showAttachments(): Promise<CardAttachment[]> {
     const attachments = this.project.attachments();
     const templateAttachments = await this.attachmentsFromTemplates();
@@ -178,7 +183,11 @@ export class Show {
    * @param filename attachment filename
    * @returns attachment details
    */
-  public showAttachment(cardKey: string, filename: string): attachmentPayload {
+  @read
+  public async showAttachment(
+    cardKey: string,
+    filename: string,
+  ): Promise<attachmentPayload> {
     if (!cardKey) {
       throw new Error(`Mandatory parameter 'cardKey' missing`);
     }
@@ -203,6 +212,7 @@ export class Show {
    * @param waitDelay amount of time to wait for the application to open the attachment
    * @todo: Move away from Show.
    */
+  @read
   public async openAttachment(
     cardKey: string,
     filename: string,
@@ -259,10 +269,11 @@ export class Show {
    * @param contentType Content format in which content is to be shown
    * @returns card details
    */
-  public showCardDetails(
+  @read
+  public async showCardDetails(
     cardKey?: string,
     contentType?: FileContentType,
-  ): Card {
+  ): Promise<Card> {
     if (!cardKey) {
       throw new Error(`Mandatory parameter 'cardKey' missing`);
     }
@@ -285,6 +296,7 @@ export class Show {
    * @param cardsFrom - The location from which to look for cards. Either from the project, templates or both.
    * @returns cards list array
    */
+  @read
   public async showCards(
     cardsFrom?: CardLocation,
   ): Promise<CardListContainer[]> {
@@ -296,6 +308,7 @@ export class Show {
    * @param cardKey The key of the card.
    * @returns the content of the logic program.
    */
+  @read
   public async showCardLogicProgram(cardKey: string) {
     return this.project.calculationEngine.cardLogicProgram(cardKey);
   }
@@ -304,6 +317,7 @@ export class Show {
    * Shows all card types in a project.
    * @returns array of card type details
    */
+  @read
   public async showCardTypesWithDetails(): Promise<(CardType | undefined)[]> {
     const container = [];
     for (const cardType of this.project.resources.cardTypes()) {
@@ -324,6 +338,7 @@ export class Show {
    *          with 'showAll' true, the list consists of all modules in the hubs, even if they have already been imported
    *          Note that the two boolean options can be combined.
    */
+  @write()
   public async showImportableModules(
     showAll?: boolean,
     showDetails?: boolean,
@@ -368,7 +383,8 @@ export class Show {
    * Returns all unique labels in a project
    * @returns labels in a list
    */
-  public showLabels(): string[] {
+  @read
+  public async showLabels(): Promise<string[]> {
     const cards = flattenCardArray(
       this.project.showProjectCards(),
       this.project,
@@ -384,6 +400,7 @@ export class Show {
    * @param resource Name of the resource.
    * @returns the content of the logic program.
    */
+  @read
   public async showLogicProgram(resource: ResourceName) {
     return this.project.calculationEngine.resourceLogicProgram(resource);
   }
@@ -393,6 +410,7 @@ export class Show {
    * @param moduleName name of a module
    * @returns details of a module.
    */
+  @read
   public async showModule(moduleName: string): Promise<ModuleContent> {
     const moduleDetails = await this.project.module(moduleName);
     if (!moduleDetails) {
@@ -405,6 +423,7 @@ export class Show {
    * Shows hubs of the project.
    * @returns list of hubs.
    */
+  @write()
   public async showHubs(): Promise<HubSetting[]> {
     // Ensure module list is up to date before showing
     await this.fetchCmd.ensureModuleListUpToDate();
@@ -415,7 +434,8 @@ export class Show {
    * Returns all project cards in the project. Cards don't have content and nor metadata.
    * @returns array of cards
    */
-  public showProjectCards(): Card[] {
+  @read
+  public async showProjectCards(): Promise<Card[]> {
     return this.project.showProjectCards();
   }
 
@@ -423,7 +443,8 @@ export class Show {
    * Shows all modules (if any) in a project.
    * @returns all modules in a project.
    */
-  public showModules(): string[] {
+  @read
+  public async showModules(): Promise<string[]> {
     return this.project.resources.moduleNames().sort();
   }
 
@@ -431,6 +452,7 @@ export class Show {
    * Shows details of a particular project.
    * @returns project information
    */
+  @read
   public async showProject(): Promise<ProjectMetadata> {
     return this.project.show();
   }
@@ -445,6 +467,7 @@ export class Show {
    * @returns Report results as a string
    * @throws Error if the report does not exist
    */
+  @read
   public async showReportResults(
     reportName: string,
     cardKey: string,
@@ -487,6 +510,7 @@ export class Show {
         if (error instanceof Error) {
           throw new Error(
             `Failed to write report to ${outputPath}: ${error.message}`,
+            { cause: error },
           );
         }
       }
@@ -515,29 +539,31 @@ export class Show {
     arg2?: boolean | ResourceType,
     arg3?: boolean,
   ): Promise<AnyResourceContent> {
-    const hasResourceType = typeof arg2 === 'string';
-    const resourceType = hasResourceType ? arg2 : null;
-    const showUse = hasResourceType ? arg3 : arg2;
-
-    const type = this.project.resources.extractType(name);
-    if (resourceType !== null && resourceType !== type) {
-      throw new Error(
-        `While fetching '${name}': Expected type '${resourceType}', but got '${type}' instead`,
-      );
-    }
-    const resource = this.project.resources.byType(name, type);
-    const [details, usage] = await Promise.all([
-      resource?.show(),
-      showUse ? resource?.usage() : [],
-    ]);
-    if (showUse) {
-      return {
-        ...details,
-        usedIn: [...usage],
-      };
-    } else {
-      return details;
-    }
+    return this.project.lock.read(async () => {
+      const hasResourceType = typeof arg2 === 'string';
+      const resourceType = hasResourceType ? arg2 : null;
+      const showUse = hasResourceType ? arg3 : arg2;
+
+      const type = this.project.resources.extractType(name);
+      if (resourceType !== null && resourceType !== type) {
+        throw new Error(
+          `While fetching '${name}': Expected type '${resourceType}', but got '${type}' instead`,
+        );
+      }
+      const resource = this.project.resources.byType(name, type);
+      const [details, usage] = await Promise.all([
+        resource?.show(),
+        showUse ? resource?.usage() : [],
+      ]);
+      if (showUse) {
+        return {
+          ...details,
+          usedIn: [...usage],
+        };
+      } else {
+        return details;
+      }
+    });
   }
 
   /**
@@ -545,6 +571,7 @@ export class Show {
    * @param type Name of resources to return (in plural form, e.g. 'templates')
    * @returns sorted array of resources
    */
+  @read
   public async showResources(type: string): Promise<string[]> {
     const func = this.resourceFunctions[type];
     if (!func) return [];
@@ -555,6 +582,7 @@ export class Show {
    * Shows all templates with full details in a project.
    * @returns all templates in a project.
    */
+  @read
   public async showTemplatesWithDetails(): Promise<TemplateConfiguration[]> {
     const templates = [];
     for (const template of this.project.resources.templates()) {
@@ -567,7 +595,8 @@ export class Show {
    * Shows all workflows with full details in a project.
    * @returns workflows with full details
    */
-  public showWorkflowsWithDetails(): (Workflow | undefined)[] {
+  @read
+  public async showWorkflowsWithDetails(): Promise<(Workflow | undefined)[]> {
     const workflows = [];
     for (const workflow of this.project.resources.workflows()) {
       workflows.push(workflow.data);

package/src/commands/transition.ts

@@ -15,6 +15,7 @@ import { ActionGuard } from '../permissions/action-guard.js';
 import { CardMetadataUpdater } from '../card-metadata-updater.js';
 import type { Project } from '../containers/project.js';
 import type { WorkflowState } from '../interfaces/resource-interfaces.js';
+import { write } from '../utils/rw-lock.js';
 
 /**
  * Handles transitions.
@@ -40,6 +41,7 @@ export class Transition {
    * @param cardKey card key
    * @param transition which transition to do
    */
+  @write((cardKey) => `Transition card ${cardKey}`)
   public async cardTransition(cardKey: string, transition: WorkflowState) {
     const card = this.project.findCard(cardKey);
 

package/src/commands/update.ts

@@ -21,6 +21,7 @@ import type {
 } from '../resources/resource-object.js';
 import type { Project } from '../containers/project.js';
 import type { UpdateKey } from '../interfaces/resource-interfaces.js';
+import { runWithDefaultCommitMessage } from '../utils/commit-context.js';
 
 /**
  * Class that handles 'update' commands.
@@ -47,9 +48,13 @@ export class Update {
     T extends UpdateOperations,
     K extends string,
   >(name: string, updateKey: UpdateKey<K>, operation: OperationFor<Type, T>) {
-    const type = this.project.resources.extractType(name);
-    const resource = this.project.resources.byType(name, type);
-    await resource?.update(updateKey, operation);
+    const run = () =>
+      this.project.lock.write(async () => {
+        const type = this.project.resources.extractType(name);
+        const resource = this.project.resources.byType(name, type);
+        await resource?.update(updateKey, operation);
+      });
+    return runWithDefaultCommitMessage('Apply resource operation', run);
   }
 
   /**
@@ -69,6 +74,7 @@ export class Update {
     optionalDetail?: Type, // todo: for 'rank' it might be reasonable to accept also 'number'
     mappingTable?: { stateMapping: Record<string, string> },
   ) {
+    // Safe to not have lock here, this is just a wrapper to applyResourceOperation
     const op: Operation<Type> = {
       name: operation,
       target: '' as Type,

package/src/commands/validate.ts

@@ -240,7 +240,7 @@ export class Validate {
       const result = await Promise.all(promises);
       message.push(...result.flat(1));
     } catch (error) {
-      throw new Error(errorFunction(error));
+      throw new Error(errorFunction(error), { cause: error });
     }
     return message;
   }

package/src/containers/project/calculation-engine.ts

@@ -476,7 +476,6 @@ export class CalculationEngine {
         model: model,
         view: view,
       },
-      graph: true,
       context,
     });
     let graph = (await instance()).renderString(result, {

package/src/containers/project/card-cache.ts

@@ -174,6 +174,7 @@ export class CardCache {
         if (error instanceof Error) {
           throw new Error(
             `Invalid JSON in file '${metadataPath}': ${error.message}`,
+            { cause: error },
           );
         }
         throw error;

package/src/containers/project.ts

@@ -56,6 +56,9 @@ import { Validate } from '../commands/validate.js';
 import { ContentWatcher } from './project/project-content-watcher.js';
 import { getChildLogger } from '../utils/log-utils.js';
 import { MigrationExecutor } from '../migrations/migration-executor.js';
+import { RWLock } from '../utils/rw-lock.js';
+import { GitManager } from '../utils/git-manager.js';
+import { getCommitContext } from '../utils/commit-context.js';
 
 import type { MigrationResult } from '@cyberismo/migrations';
 import type { Template } from './template.js';
@@ -78,13 +81,16 @@ export { ResourcesFrom };
 export interface ProjectOptions {
   autoSave?: boolean;
   watchResourceChanges?: boolean;
+  autocommit?: boolean;
 }
 
 /**
  * Represents project folder.
  */
 export class Project extends CardContainer {
+  public readonly lock = new RWLock();
   public calculationEngine: CalculationEngine;
+  private gitManager?: GitManager;
   private logger = getChildLogger({ module: 'Project' });
   private projectPaths: ProjectPaths;
   private resourceHandler: ResourceHandler;
@@ -140,6 +146,28 @@ export class Project extends CardContainer {
         },
       );
     }
+
+    if (this.options.autocommit) {
+      this.gitManager = new GitManager(path);
+
+      // Commit after successful writes
+      this.lock.onAfterWrite(async () => {
+        const context = getCommitContext();
+        await this.gitManager!.commit(
+          context.message ?? 'Autocommit',
+          context.author,
+        );
+      });
+
+      // Rollback on failed writes
+      this.lock.onWriteError(async () => {
+        await this.gitManager!.rollback();
+        // Invalidate caches after rollback since filesystem state changed
+        this.cardCache.clear();
+        await this.populateCardsCache();
+        this.resources.changed();
+      });
+    }
   }
 
   // Changes a card's parent in the cache and updates all relationships.
@@ -868,6 +896,15 @@ export class Project extends CardContainer {
     return this.projectPaths;
   }
 
+  /**
+   * Initialize git repo for autocommit mode. No-op if autocommit is disabled.
+   */
+  public async initializeGit(): Promise<void> {
+    if (this.gitManager) {
+      await this.gitManager.initialize(getCommitContext().author);
+    }
+  }
+
   /**
    * Populates the card cache, if it has not been populated.
    */
@@ -939,7 +976,7 @@ export class Project extends CardContainer {
       await unlink(attachmentPath);
     } catch (error) {
       this.logger.error({ error }, 'Removing card attachment');
-      throw new Error(`Attachment not found: ${fileName}`);
+      throw new Error(`Attachment not found: ${fileName}`, { cause: error });
     }
     await this.handleAttachmentChange(cardKey, 'removed', fileName);
   }
@@ -1134,6 +1171,43 @@ export class Project extends CardContainer {
     }
   }
 
+  /**
+   * Updates descendant card paths in the cache after a parent card has been moved.
+   * This ensures cached paths reflect the actual filesystem locations.
+   * @param cardKey The card whose descendants need path updates
+   * @param oldBasePath The old base path before the move
+   * @param newBasePath The new base path after the move
+   */
+  public updateDescendantPathsAfterMove(
+    cardKey: string,
+    oldBasePath: string,
+    newBasePath: string,
+  ): void {
+    const card = this.cardCache.getCard(cardKey);
+    if (!card) return;
+
+    if (card.path.startsWith(oldBasePath)) {
+      card.path = card.path.replace(oldBasePath, newBasePath);
+
+      if (card.attachments && card.attachments.length > 0) {
+        for (const attachment of card.attachments) {
+          if (attachment.path.startsWith(oldBasePath)) {
+            attachment.path = attachment.path.replace(oldBasePath, newBasePath);
+          }
+        }
+      }
+
+      this.cardCache.updateCard(card.key, card);
+    }
+
+    // Recursively update children
+    if (card.children && card.children.length > 0) {
+      for (const childKey of card.children) {
+        this.updateDescendantPathsAfterMove(childKey, oldBasePath, newBasePath);
+      }
+    }
+  }
+
   /**
    * Updates the entire card in the card cache and handles any path/parent changes.
    * Also persists changes to content and metadata files.

package/src/containers/template.ts

@@ -399,7 +399,7 @@ export class Template extends CardContainer {
     const destinationCardPath = parentCard
       ? join(this.cardFolder(parentCard.key), 'c')
       : this.templateCardsPath;
-    let newCardKey = '';
+    let newCardKey: string;
 
     try {
       // todo: to use cache instead of file access

package/src/interfaces/command-options.ts

@@ -92,6 +92,7 @@ export interface ShowCommandOptions extends BaseCommandOptions {
 export interface StartCommandOptions extends BaseCommandOptions {
   forceStart?: boolean;
   watchResourceChanges?: boolean;
+  autocommit?: boolean;
 }
 
 // Options for 'transition' command

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/include/index.ts

@@ -19,6 +19,8 @@ import macroMetadata from './metadata.js';
 import BaseMacro from '../base-macro.js';
 import type TaskQueue from '../task-queue.js';
 import { MAX_LEVEL_OFFSET } from '../../utils/constants.js';
+import { escapeCsvField } from '../../utils/csv.js';
+import { escapeJsonString } from '../../utils/json.js';
 
 export default class IncludeMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
@@ -40,6 +42,14 @@ export default class IncludeMacro extends BaseMacro {
     if (!options.pageTitles) {
       options.pageTitles = 'normal';
     }
+
+    // Validate incompatible option combinations
+    if (options.escape && options.title !== 'exclude') {
+      throw new Error(
+        'The "escape" option can only be used with "title": "exclude". ' +
+          'Escaping is meant for embedding raw content in JSON/CSV documents, not for generating AsciiDoc output.',
+      );
+    }
     const newContext = {
       ...context,
       cardKey: options.cardKey,
@@ -52,6 +62,8 @@ export default class IncludeMacro extends BaseMacro {
       card.content,
       newContext,
     );
+
+    // Skip the leading newlines if trim is enabled
     const content = `\n\n${anchor}${title}${cardContent}`;
 
     let levelOffset = 0;
@@ -102,7 +114,13 @@ export default class IncludeMacro extends BaseMacro {
     context: MacroGenerationContext,
   ): Promise<string> {
     if (options.title !== 'only') {
-      return await evaluateMacros(cardContent ?? '', context, true);
+      let content = await evaluateMacros(cardContent ?? '', context, true);
+      if (options.escape === 'json') {
+        content = escapeJsonString(content);
+      } else if (options.escape === 'csv') {
+        content = escapeCsvField(content);
+      }
+      return content;
     }
     return '';
   }

package/src/macros/include/types.ts

@@ -12,21 +12,23 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+/**
+ * Include macro options.
+ * @param cardKey Card key of the card being included
+ * @param levelOffset A positive number will increase the level of headings.
+ *                    A negative value will decrease the level of headings in the included content.
+ * @param title Determines behaviour with the title that is in card metadata
+ *              include --> includes the title
+ *              exclude --> excludes the title
+ *              only --> includes title but does not import content
+ * @param whitespace Whether to trim leading and trailing whitespace
+ * @param escape Type of escaping to apply to the included content
+ *               json --> escapes for JSON strings
+ *               csv --> escapes for CSV fields
+ */
 export interface IncludeMacroOptions {
-  /**
-   * Card key of the card being included
-   */
   cardKey: string;
-  /**
-   * A positive number wil increase the level of headings and a negative alue will the level of headings in the included content
-   */
   levelOffset?: string;
-  /**
-   * Determines behaviour with the title that is in card metadata
-   * include --> includes the title
-   * exclude --> excludes the title
-   * only --> includes title but does not import content
-   */
   title?: 'include' | 'exclude' | 'only';
   pageTitles?: 'normal' | 'discrete';
   /**
@@ -35,4 +37,5 @@ export interface IncludeMacroOptions {
    * Default is 'keep'.
    */
   whitespace?: 'keep' | 'trim';
+  escape?: 'json' | 'csv';
 }

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,
+    });
   }
 }
 
@@ -249,6 +251,7 @@ export async function evaluateMacros(
     try {
       const compiled = handlebars.compile(preprocessRawBlocks(result), {
         strict: true,
+        ignoreStandalone: true,
       });
       result = compiled({ cardKey: context.cardKey });
 

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;