@cyberismo/data-handler 0.0.21 → 0.0.22

package/src/commands/move.ts

@@ -18,6 +18,7 @@ import { ActionGuard } from '../permissions/action-guard.js';
 import { copyDir, deleteDir } from '../utils/file-utils.js';
 import type { Card } from '../interfaces/project-interfaces.js';
 import type { Project } from '../containers/project.js';
+import { write } from '../utils/rw-lock.js';
 import {
   EMPTY_RANK,
   FIRST_RANK,
@@ -100,6 +101,7 @@ export class Move {
    * @param source source card to move
    * @param destination destination card where source card will be moved to; or to root
    */
+  @write((source, destination) => `Move card ${source} to ${destination}`)
   public async moveCard(source: string, destination: string) {
     if (source === ROOT) {
       throw new Error('Cannot move "root"');
@@ -188,6 +190,9 @@ export class Move {
         ? getRankAfter(lastChild.metadata.rank)
         : FIRST_RANK;
 
+    // Save old path before moving (needed to update descendant paths)
+    const oldPath = sourceCard.path;
+
     // First do the file operations, then update metadata
     await copyDir(sourceCard.path, destinationPath);
     await deleteDir(sourceCard.path);
@@ -199,8 +204,32 @@ export class Move {
       sourceCard.metadata.rank = rank;
     }
 
+    // Update attachment paths for the moved card
+    if (sourceCard.attachments && sourceCard.attachments.length > 0) {
+      for (const attachment of sourceCard.attachments) {
+        if (attachment.path.startsWith(oldPath)) {
+          attachment.path = attachment.path.replace(oldPath, destinationPath);
+        }
+      }
+    }
+
     // Handle cache update and persistence
     await this.project.updateCard(sourceCard);
+
+    // Update all descendant card paths in the cache to reflect the new filesystem location.
+    // This is critical: files have been moved on disk, but children's cached paths
+    // still point to the old location. Without this, operations on children
+    // (like edit or delete) would target non-existent paths, leaving orphaned files.
+    if (sourceCard.children && sourceCard.children.length > 0) {
+      for (const childKey of sourceCard.children) {
+        this.project.updateDescendantPathsAfterMove(
+          childKey,
+          oldPath,
+          destinationPath,
+        );
+      }
+    }
+
     const updatedCard: Card = {
       ...sourceCard,
       path: destinationPath,
@@ -238,6 +267,7 @@ export class Move {
    * @param cardKey card key
    * @param index to which position should card be ranked to
    */
+  @write((cardKey) => `Reorder card ${cardKey}`)
   public async rankByIndex(cardKey: string, index: number) {
     if (index < 0) {
       throw new Error(`Index must be greater than 0`);
@@ -272,6 +302,7 @@ export class Move {
    * @param cardKey Card to rank
    * @param beforeCardKey Card key after which the card will be ranked
    */
+  @write((cardKey) => `Reorder card ${cardKey}`)
   public async rankCard(cardKey: string, beforeCardKey: string) {
     const card = this.project.findCard(cardKey);
     const beforeCard = this.project.findCard(beforeCardKey);
@@ -325,6 +356,7 @@ export class Move {
    * Ranks card first.
    * @param cardKey card key
    */
+  @write((cardKey) => `Rank card ${cardKey} first`)
   public async rankFirst(cardKey: string) {
     const card = this.project.findCard(cardKey);
     const children = sortItems(
@@ -370,6 +402,7 @@ export class Move {
    *  Rebalances the ranks of the children of a card.
    * @param parentCardKey parent card key
    */
+  @write((parentCardKey) => `Rebalance children of ${parentCardKey}`)
   public async rebalanceChildren(parentCardKey: string) {
     const parentCard = this.project.findCard(parentCardKey);
     if (!parentCard || !parentCard.children) {
@@ -384,6 +417,7 @@ export class Move {
    * Rebalances the ranks of the cards in the whole project, including templates
    * Can be used even if the ranks do not exist
    */
+  @write(() => 'Rebalance project')
   public async rebalanceProject() {
     const cards = this.project.showProjectCards();
 

package/src/commands/remove.ts

@@ -13,16 +13,21 @@
 
 import { ActionGuard } from '../permissions/action-guard.js';
 import { isModuleCard } from '../utils/card-utils.js';
+import { getChildLogger } from '../utils/log-utils.js';
 import { ModuleManager } from '../module-manager.js';
 import type { Fetch } from './fetch.js';
 import type { Project } from '../containers/project.js';
 import type { RemovableResourceTypes } from '../interfaces/project-interfaces.js';
+import { write } from '../utils/rw-lock.js';
 
 /**
  * Remove command.
  */
 export class Remove {
   private moduleManager: ModuleManager;
+  private get logger() {
+    return getChildLogger({ module: 'remove' });
+  }
   /**
    * Creates a new instance of Remove command.
    * @param project Project instance to use
@@ -73,14 +78,30 @@ export class Remove {
       await actionGuard.checkPermission('delete', cardKey);
     }
 
-    // If card is destination of a link, remove the link.
+    // Collect all card keys that will be deleted (the card itself and all descendants).
+    const cardsToDelete = new Set<string>();
+    const collectDescendants = (c: typeof card) => {
+      cardsToDelete.add(c.key);
+      for (const childKey of c.children) {
+        try {
+          const childCard = this.project.findCard(childKey);
+          collectDescendants(childCard);
+        } catch {
+          this.logger.debug({ childKey }, 'Child card not found, skipping');
+        }
+      }
+    };
+    collectDescendants(card);
+
+    // If any of the cards to be deleted is a destination of a link, remove the link.
     const allCards = this.project.cards(this.project.paths.cardRootFolder);
     const promiseContainer: Promise<void>[] = [];
 
     for (const item of allCards) {
+      if (cardsToDelete.has(item.key)) continue;
       const links = item.metadata?.links ?? [];
       for (const link of links) {
-        if (link.cardKey === cardKey) {
+        if (cardsToDelete.has(link.cardKey)) {
           promiseContainer.push(this.removeLink(item.key, link.cardKey));
         }
       }
@@ -163,6 +184,7 @@ export class Remove {
    *         when removing link, some of the mandatory parameters are missing, or
    *         when trying to remove unknown type
    */
+  @write((type, targetName) => `Remove ${type} ${targetName}`)
   public async remove(
     type: RemovableResourceTypes,
     targetName: string,

package/src/commands/rename.ts

@@ -24,6 +24,7 @@ import {
 import { isTemplateCard } from '../utils/card-utils.js';
 import { type Project, ResourcesFrom } from '../containers/project.js';
 import { resourceName } from '../utils/resource-utils.js';
+import { write } from '../utils/rw-lock.js';
 
 const FILE_TYPES_WITH_PREFIX_REFERENCES = ['adoc', 'hbs', 'json', 'lp'];
 
@@ -186,6 +187,7 @@ export class Rename {
    * @throws if trying to rename with current name
    * @param to Card id, or template name
    */
+  @write((to) => `Rename project prefix to ${to}`)
   public async rename(to: string) {
     if (!to) {
       throw new Error(`Input validation error: empty 'to' is not allowed`);

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