@cyberismo/data-handler 0.0.20 → 0.0.22

package/src/commands/create.ts

@@ -21,10 +21,12 @@ import { Project } from '../containers/project.js';
 import { Validate } from './validate.js';
 
 import { EMPTY_RANK, sortItems } from '../utils/lexorank.js';
+import { ROOT } from '../utils/constants.js';
 import { isModulePath } from '../utils/card-utils.js';
 import type { DataType } from '../interfaces/resource-interfaces.js';
 import type { Card, ProjectFile } from '../interfaces/project-interfaces.js';
 import { resourceName, resourceNameToString } from '../utils/resource-utils.js';
+import { write } from '../utils/rw-lock.js';
 import { writeJsonFile } from '../utils/json.js';
 
 // todo: Is there a easy to way to make JSON schema into a TypeScript interface/type?
@@ -79,6 +81,10 @@ export class Create {
    * @param count How many cards to add. By default one.
    * @returns non-empty string array with ids of added cards
    */
+  @write(
+    (cardTypeName, templateName) =>
+      `Add cards of type ${cardTypeName} to template ${templateName}`,
+  )
   public async addCards(
     cardTypeName: string,
     templateName: string,
@@ -139,6 +145,7 @@ export class Create {
    * Adds a new hub location.
    * @param hubUrl URL of the hub
    */
+  @write((hubUrl) => `Add hub ${hubUrl}`)
   public async addHubLocation(hubUrl: string) {
     return this.project.configuration.addHub(hubUrl);
   }
@@ -149,6 +156,7 @@ export class Create {
    * @param attachment path to an attachment file or attachment name if buffer is defined
    * @param buffer (Optional) attachment buffer
    */
+  @write((cardKey, attachment) => `Add attachment ${attachment} to ${cardKey}`)
   public async createAttachment(
     cardKey: string,
     attachment: string,
@@ -161,7 +169,7 @@ export class Create {
         buffer || attachment,
       );
     } catch (error) {
-      throw new Error(errorFunction(error));
+      throw new Error(errorFunction(error), { cause: error });
     }
   }
 
@@ -169,6 +177,7 @@ export class Create {
    * Creates a calculation resource.
    * @param calculationName name for the calculation resource
    */
+  @write((calculationName) => `Create calculation ${calculationName}`)
   public async createCalculation(calculationName: string) {
     return this.project.resources
       .byType(calculationName, 'calculations')
@@ -181,6 +190,7 @@ export class Create {
    * @param parentCardKey (Optional) card-key of a parent card. If missing, cards are added to the card root.
    * @returns array of card keys that were created. Cards are sorted by their parent key and rank. Template root cards are first but the order between other card groups is not guaranteed. However, the order of cards within a group is guaranteed to be ordered by rank.
    */
+  @write((templateName) => `Create card from template ${templateName}`)
   public async createCard(
     templateName: string,
     parentCardKey?: string,
@@ -208,11 +218,20 @@ export class Create {
 
     const createdCards = await templateObject.createCards(specificCard);
     if (createdCards.length > 0) {
-      // Note: This assumes that parent keys will be ahead of 'a' in the sort order.
-      const sorted = sortItems(createdCards, (item) => {
-        return `${item.parent === 'root' ? 'a' : item.parent}${item.metadata?.rank || EMPTY_RANK}`;
-      });
-      return sorted;
+      const rootParent = specificCard?.key ?? ROOT;
+      const rootCards: Card[] = [];
+      const childCards: Card[] = [];
+      for (const card of createdCards) {
+        if (card.parent === rootParent) {
+          rootCards.push(card);
+        } else {
+          childCards.push(card);
+        }
+      }
+      return [
+        ...sortItems(rootCards, (item) => item.metadata?.rank || EMPTY_RANK),
+        ...childCards,
+      ];
     }
     return [];
   }
@@ -222,6 +241,7 @@ export class Create {
    * @param cardTypeName name for the card type.
    * @param workflowName workflow name to use in the card type.
    */
+  @write((cardTypeName) => `Create card type ${cardTypeName}`)
   public async createCardType(cardTypeName: string, workflowName: string) {
     return this.project.resources
       .byType(cardTypeName, 'cardTypes')
@@ -233,6 +253,7 @@ export class Create {
    * @param fieldTypeName name for the field type.
    * @param dataType data type for the field type
    */
+  @write((fieldTypeName) => `Create field type ${fieldTypeName}`)
   public async createFieldType(fieldTypeName: string, dataType: DataType) {
     return this.project.resources
       .byType(fieldTypeName, 'fieldTypes')
@@ -243,6 +264,7 @@ export class Create {
    * Creates a new graph model.
    * @param graphModelName name for the graph model.
    */
+  @write((graphModelName) => `Create graph model ${graphModelName}`)
   public async createGraphModel(graphModelName: string) {
     return this.project.resources
       .byType(graphModelName, 'graphModels')
@@ -253,6 +275,7 @@ export class Create {
    * Creates a new graph view.
    * @param graphViewName name for the graph view.
    */
+  @write((graphViewName) => `Create graph view ${graphViewName}`)
   public async createGraphView(graphViewName: string) {
     return this.project.resources.byType(graphViewName, 'graphViews').create();
   }
@@ -262,6 +285,7 @@ export class Create {
    * @param cardKey The card to which the label is added to
    * @param label The label being added
    */
+  @write((cardKey, label) => `Add label ${label} to ${cardKey}`)
   public async createLabel(cardKey: string, label: string) {
     if (!Validate.isValidLabelName(label)) {
       throw new Error(`Not a valid label name'`);
@@ -282,6 +306,7 @@ export class Create {
    * Creates a new link type.
    * @param linkTypeName name for the link type.
    */
+  @write((linkTypeName) => `Create link type ${linkTypeName}`)
   public async createLinkType(linkTypeName: string) {
     return this.project.resources.byType(linkTypeName, 'linkTypes').create();
   }
@@ -293,6 +318,10 @@ export class Create {
    * @param linkType The type of link to add
    * @param linkDescription Optional description of the link
    */
+  @write(
+    (cardKey, destinationCardKey, linkType) =>
+      `Create ${linkType} link from ${cardKey} to ${destinationCardKey}`,
+  )
   public async createLink(
     cardKey: string,
     destinationCardKey: string,
@@ -383,6 +412,7 @@ export class Create {
     projectCategory: string,
     projectDescription: string,
   ) {
+    // No lock required, since we are creating a new project
     projectPath = resolve(projectPath);
 
     if (!projectPath) {
@@ -472,6 +502,7 @@ export class Create {
    * Creates a report
    * @param name name of the report
    */
+  @write((name) => `Create report ${name}`)
   public async createReport(name: string) {
     return this.project.resources.byType(name, 'reports').createReport();
   }
@@ -481,6 +512,7 @@ export class Create {
    * @param templateName Name of the template.
    * @param templateContent JSON content for the template file.
    */
+  @write((templateName) => `Create template ${templateName}`)
   public async createTemplate(templateName: string, templateContent: string) {
     return this.project.resources
       .byType(templateName, 'templates')
@@ -492,6 +524,7 @@ export class Create {
    * @param workflowName workflow name
    * @param workflowContent workflow content JSON
    */
+  @write((workflowName) => `Create workflow ${workflowName}`)
   public async createWorkflow(workflowName: string, workflowContent: string) {
     return this.project.resources
       .byType(workflowName, 'workflows')

package/src/commands/edit.ts

@@ -19,6 +19,7 @@ import { spawnSync } from 'node:child_process';
 import { ActionGuard } from '../permissions/action-guard.js';
 import { Project } from '../containers/project.js';
 import { UserPreferences } from '../utils/user-preferences.js';
+import { write } from '../utils/rw-lock.js';
 
 import type { MetadataContent } from '../interfaces/project-interfaces.js';
 
@@ -76,6 +77,7 @@ export class Edit {
    * @param cardKey The card to update.
    * @param changedContent New content for the card.
    */
+  @write((cardKey) => `Edit content of ${cardKey}`)
   public async editCardContent(cardKey: string, changedContent: string) {
     if (this.project.hasTemplateCard(cardKey)) {
       return this.project.updateCardContent(cardKey, changedContent);
@@ -93,6 +95,7 @@ export class Edit {
    * @param changedKey Which metadata property was changed
    * @param newValue New value for the metadata property
    */
+  @write((cardKey) => `Edit metadata of ${cardKey}`)
   public async editCardMetadata(
     cardKey: string,
     changedKey: string,

package/src/commands/export.ts

@@ -31,6 +31,7 @@ import { generateReportContent } from '../utils/report.js';
 import { getStaticDirectoryPath, pdfReport } from '@cyberismo/assets';
 import { Project } from '../containers/project.js';
 import type { QueryResult } from '../types/queries.js';
+import { read } from '../utils/rw-lock.js';
 import type { Show } from './show.js';
 import { sortItems } from '../utils/lexorank.js';
 
@@ -246,7 +247,10 @@ export class Export {
       children: [],
       attachments: [],
     };
-    const cardDetailsResponse = this.showCmd.showCardDetails(card.key, 'adoc');
+    const cardDetailsResponse = await this.showCmd.showCardDetails(
+      card.key,
+      'adoc',
+    );
     let asciiDocContent = '';
     const project = this.project;
     try {
@@ -283,6 +287,7 @@ export class Export {
    * @param options Export options.
    * @returns status message
    */
+  @read
   public async exportPdf(
     destination: string,
     options: ExportPdfOptions,
@@ -320,6 +325,7 @@ export class Export {
    * @param cardKey If not exporting the whole card tree, card key of parent card.
    * @returns status message
    */
+  @read
   public async exportToADoc(
     destination: string,
     cardKey?: string,
@@ -365,7 +371,7 @@ export class Export {
       destination,
       Project.cardContentFile,
     );
-    let message = '';
+    let message: string;
     try {
       await truncate(resultDocumentPath, 0);
       message = `Using existing output file '${resultDocumentPath}'`;

package/src/commands/fetch.ts

@@ -17,6 +17,7 @@ import { resolve, sep } from 'node:path';
 import { getChildLogger } from '../utils/log-utils.js';
 import { readJsonFile, writeJsonFile } from '../utils/json.js';
 import { validateJson } from '../utils/validate.js';
+import { write } from '../utils/rw-lock.js';
 
 import type { ModuleSetting } from '../interfaces/project-interfaces.js';
 import type { Project } from '../containers/project.js';
@@ -203,6 +204,7 @@ export class Fetch {
   /**
    * Ensures the module list is up to date by fetching if needed.
    */
+  @write()
   public async ensureModuleListUpToDate() {
     await this.fetchHubs();
   }
@@ -211,6 +213,7 @@ export class Fetch {
    * Fetches modules from modules hub(s) and writes them to a file.
    * Only fetches if the remote version is newer than the local version.
    */
+  @write(() => 'Fetch hubs')
   public async fetchHubs() {
     const needsFetch = await this.fetchModuleList();
     if (!needsFetch) {

package/src/commands/import.ts

@@ -14,6 +14,7 @@
 import { ModuleManager } from '../module-manager.js';
 import { readCsvFile } from '../utils/csv.js';
 import { Validate } from './validate.js';
+import { write } from '../utils/rw-lock.js';
 
 import type { Create } from './create.js';
 import type {
@@ -48,6 +49,7 @@ export class Import {
    * @param parentCardKey the cards in the csv file will be created under this card
    * @returns card keys of the imported cards
    */
+  @write((csvFilePath) => `Import cards from CSV ${csvFilePath}`)
   public async importCsv(
     csvFilePath: string,
     parentCardKey?: string,
@@ -137,6 +139,7 @@ export class Import {
    *        private: If true, uses credentials to clone the repository
    * @param skipMigrationLog If true, skip logging to migration log (used during project creation)
    */
+  @write((source) => `Import module ${source}`)
   public async importModule(
     source: string,
     destination?: string,
@@ -195,6 +198,7 @@ export class Import {
    * @param credentials Optional credentials for a private module.
    * @throws if module is not part of the project
    */
+  @write((moduleName) => `Update module ${moduleName}`)
   public async updateModule(moduleName: string, credentials?: Credentials) {
     // Ensure module list is up to date before updating
     await this.fetchCmd.ensureModuleListUpToDate();
@@ -212,6 +216,7 @@ export class Import {
    * Updates all imported modules.
    * @param credentials Optional credentials for private modules.
    */
+  @write(() => 'Update all modules')
   public async updateAllModules(credentials?: Credentials) {
     // Ensure module list is up to date before updating all modules
     await this.fetchCmd.ensureModuleListUpToDate();

package/src/commands/migrate.ts

@@ -14,6 +14,7 @@
 import { SCHEMA_VERSION } from '@cyberismo/assets';
 import type { MigrationResult } from '@cyberismo/migrations';
 import type { Project } from '../containers/project.js';
+import { write } from '../utils/rw-lock.js';
 
 /**
  * Command that handles schema migration operations.
@@ -32,6 +33,7 @@ export class Migrate {
    * @param timeoutMilliSeconds Optional timeout in milliseconds (defaults to 2 minutes)
    * @returns Migration result
    */
+  @write(() => 'Migrate project')
   public async migrate(
     toVersion?: number,
     backupDir?: string,

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`);