@cyberismo/data-handler 0.0.14 → 0.0.15

package/src/containers/project.ts

@@ -13,8 +13,15 @@
 */
 
 // node
-import { dirname, join, resolve, sep } from 'node:path';
-import { readdir } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import {
+  constants as fsConstants,
+  copyFile,
+  mkdir,
+  readdir,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
 
 import { CardContainer } from './card-container.js'; // base class
 
@@ -35,13 +42,18 @@ import {
   type Resource,
   type ResourceFolderType,
 } from '../interfaces/project-interfaces.js';
-import { getFilesSync, pathExists } from '../utils/file-utils.js';
+import { pathExists } from '../utils/file-utils.js';
 import { generateRandomString } from '../utils/random.js';
-import { isTemplateCard } from '../utils/card-utils.js';
+import {
+  cardPathParts,
+  isModulePath,
+  isTemplateCard,
+} from '../utils/card-utils.js';
 import { ProjectConfiguration } from '../project-settings.js';
 import { ProjectPaths } from './project/project-paths.js';
 import { readJsonFile } from '../utils/json.js';
 import {
+  pathToResourceName,
   resourceName,
   type ResourceName,
   resourceNameToString,
@@ -64,7 +76,9 @@ import { TemplateResource } from '../resources/template-resource.js';
 import { WorkflowResource } from '../resources/workflow-resource.js';
 
 import { ContentWatcher } from './project/project-content-watcher.js';
-import { pathToResourceName } from '../utils/resource-utils.js';
+import { getChildLogger } from '../utils/log-utils.js';
+
+import { ROOT } from '../utils/constants.js';
 
 // Re-export this, so that classes that use Project do not need to have separate import.
 export { ResourcesFrom };
@@ -74,34 +88,44 @@ export { ResourcesFrom };
  */
 export class Project extends CardContainer {
   public calculationEngine: CalculationEngine;
-  private resources: ResourceCollector;
-  private projectPaths: ProjectPaths;
-  private settings: ProjectConfiguration;
-  private validator: Validate;
-  private resourceWatcher: ContentWatcher | undefined;
-
   // Created resources are held in a cache.
   // In the cache, key is resource name, and data is resource metadata (as JSON).
   private createdResources = new Map<string, JSON>();
+  private logger = getChildLogger({ module: 'Project' });
+  private projectPaths: ProjectPaths;
+  private resources: ResourceCollector;
+  private resourceWatcher: ContentWatcher | undefined;
+  private settings: ProjectConfiguration;
+  private validator: Validate;
 
   constructor(
     path: string,
     private watchResourceChanges?: boolean,
   ) {
-    super(path, '');
-
-    this.calculationEngine = new CalculationEngine(this);
-
-    this.settings = new ProjectConfiguration(
+    const settings = new ProjectConfiguration(
       join(path, '.cards', 'local', Project.projectConfigFileName),
     );
+    super(path, settings.cardKeyPrefix, '');
+    this.settings = settings;
+
+    this.logger.info({ path }, 'Initializing project');
+
+    this.calculationEngine = new CalculationEngine(this);
     this.projectPaths = new ProjectPaths(path);
     this.resources = new ResourceCollector(this);
 
     this.containerName = this.settings.name;
     // todo: implement project validation
     this.validator = Validate.getInstance();
+    this.logger.info(
+      { resourcesFolder: this.paths.resourcesFolder },
+      'Collecting local resources',
+    );
     this.resources.collectLocalResources();
+    this.logger.info(
+      { name: this.containerName },
+      'Project initialization complete',
+    );
 
     const ignoreRenameFileChanges = true;
 
@@ -135,17 +159,15 @@ export class Project extends CardContainer {
     }
   }
 
-  // Removes current version of resource from cache.
-  // Then re-creates the resource with current data and caches the value again.
-  // If the value wasn't in the cache before, it will be added.
-  private async replaceCacheValue(resourceName: string) {
-    if (this.createdResources.has(resourceName)) {
-      // First, remove the old version from cache
-      this.createdResources.delete(resourceName);
+  // Changes a card's parent in the cache and updates all relationships.
+  private changeParent(updatedCard: Card, previousParent?: string) {
+    if (previousParent && previousParent !== ROOT) {
+      this.removeCachedChildren(previousParent, updatedCard.key);
     }
-    const resourceData = await this.resource(resourceName);
-    if (!resourceData) return;
-    this.createdResources.set(resourceName, resourceData as JSON);
+    if (updatedCard.parent && updatedCard.parent !== ROOT) {
+      this.updateCachedChildren(updatedCard.parent, updatedCard);
+    }
+    this.cardCache.updateCard(updatedCard.key, updatedCard);
   }
 
   // Finds specific module.
@@ -155,8 +177,55 @@ export class Project extends CardContainer {
     );
   }
 
+  // Handles attachment changes after filesystem operations.
+  private async handleAttachmentChange(
+    cardKey: string,
+    operation: 'added' | 'removed' | 'refresh',
+    fileName: string,
+  ): Promise<void> {
+    if (operation === 'added') {
+      this.cardCache.addAttachment(cardKey, fileName);
+    } else if (operation === 'removed') {
+      this.cardCache.deleteAttachment(cardKey, fileName);
+    } else if (operation === 'refresh') {
+      const newAttachments = this.cardCache.getCardAttachments(cardKey);
+      if (newAttachments) {
+        this.cardCache.updateCardAttachments(cardKey, newAttachments);
+      }
+    }
+  }
+
+  // Determines the parent card key from a card's filesystem path.
+  private parentFromPath(cardPath: string): string {
+    return cardPathParts(this.projectPrefix, cardPath).parents.at(-1) || 'root';
+  }
+
+  // Remove children from a card in the card cache
+  private removeCachedChildren(parentKey: string, childKey: string) {
+    const parentCard = this.cardCache.getCard(parentKey);
+    if (parentCard && parentCard.children) {
+      parentCard.children = parentCard.children.filter(
+        (child) => child !== childKey,
+      );
+      this.cardCache.updateCard(parentCard.key, parentCard);
+    }
+  }
+
+  // Removes current version of a resource from the resource cache.
+  // Then re-creates the resource with current data and caches the value again.
+  // If the value wasn't in the cache before, it will be added.
+  private async replaceCacheValue(resourceName: string) {
+    if (this.createdResources.has(resourceName)) {
+      // First, remove the old version from cache
+      this.createdResources.delete(resourceName);
+    }
+    const resourceData = await this.resource(resourceName);
+    if (resourceData) {
+      this.createdResources.set(resourceName, resourceData as JSON);
+    }
+  }
+
   // Returns (local or all) resources of a given type.
-  // @todo: if this would be public, we could remove cardTypes(), fieldTypes(), ... and similar APIs
   private async resourcesOfType(
     type: ResourceFolderType,
     from: ResourcesFrom = ResourcesFrom.localOnly,
@@ -164,6 +233,81 @@ export class Project extends CardContainer {
     return this.resources.resources(type, from);
   }
 
+  // Updates children in the card cache
+  private updateCachedChildren(parentKey: string, newChild: Card) {
+    const parentCard = this.cardCache.getCard(parentKey);
+    if (parentCard) {
+      // Add or update the child in the parent's children array
+      const existingChildIndex = parentCard.children?.findIndex(
+        (child) => child === newChild.key,
+      );
+      if (existingChildIndex === -1) {
+        parentCard.children.push(newChild.key);
+      }
+      this.cardCache.updateCard(parentCard.key, parentCard);
+    }
+  }
+
+  /**
+   * Populate template cards into the card cache.
+   */
+  protected async populateTemplateCards(): Promise<void> {
+    try {
+      // Gets local & module templates
+      const templateResources = await this.templates();
+      const prefixes = await this.projectPrefixes();
+      const loadPromises = templateResources.map(async (template) => {
+        try {
+          this.validator.validResourceName(
+            'templates',
+            template.name,
+            prefixes,
+          );
+        } catch (error) {
+          this.logger.warn(
+            { templateName: template.name, error },
+            `Template name '${template.name}' does not follow required format, skipping`,
+          );
+          return;
+        }
+
+        const templateResource = new TemplateResource(
+          this,
+          resourceName(template.name),
+        );
+
+        const templateObject = templateResource.templateObject();
+        const isCreated = templateObject && templateObject.isCreated();
+        if (!templateObject || !isCreated) {
+          return;
+        }
+
+        await this.cardCache.populateFromPath(
+          templateObject.templateCardsFolder(),
+          false,
+        );
+      });
+
+      await Promise.all(loadPromises);
+
+      // Once all templates have been fetched, build child-parent relationships.
+      this.cardCache.populateChildrenRelationships();
+    } catch (error) {
+      this.logger.error(
+        { error },
+        'Failed to populate template cards into the card cache',
+      );
+    }
+  }
+
+  /**
+   * Populate both the project cards, and all template cards into card cache.
+   */
+  protected async populateCardsCache(): Promise<void> {
+    await this.cardCache.populateFromPath(this.paths.cardRootFolder);
+    await this.populateTemplateCards();
+  }
+
   /**
    * Add a given 'resource' to the local resource arrays.
    * @param resource Resource to add.
@@ -174,14 +318,52 @@ export class Project extends CardContainer {
     this.createdResources.set(resource.name, data);
   }
 
+  /**
+   * Returns all template cards from the project. This includes all module templates' cards.
+   * @returns all the template cards from the project
+   */
+  public allTemplateCards(): Card[] {
+    return this.cardCache.getAllTemplateCards();
+  }
+
   /**
    * Returns an array of all the attachments in the project card's (excluding ones in templates).
    * @returns all attachments in the project.
    */
-  public async attachments(): Promise<CardAttachment[]> {
+  public attachments(): CardAttachment[] {
     return super.attachments(this.paths.cardRootFolder);
   }
 
+  /**
+   * Returns attachments from cards at a specific path using the card cache.
+   * This method allows templates to access attachments from the shared cache.
+   * @param path The path to get attachments from
+   * @returns Array of attachments from cards at the specified path
+   */
+  public attachmentsByPath(path: string): CardAttachment[] {
+    return super.attachments(path);
+  }
+
+  /**
+   * Returns all the attachments in the template cards.
+   * @returns all the attachments in the template cards.
+   */
+  public async attachmentsFromTemplates() {
+    const templateAttachments: CardAttachment[] = [];
+    const templates = await this.templates();
+    for (const template of templates) {
+      const templateResource = new TemplateResource(
+        this,
+        resourceName(template.name),
+      );
+      const templateObject = templateResource.templateObject();
+      if (templateObject) {
+        templateAttachments.push(...templateObject.attachments());
+      }
+    }
+    return templateAttachments;
+  }
+
   /**
    * Returns an array of all the calculation files (*.lp) in the project.
    * @param from Defines where resources are collected from.
@@ -194,59 +376,111 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Returns path to card's attachment folder.
+   * Returns path to a card's attachment folder.
    * @param cardKey card key
-   * @returns path to card's attachment folder.
-   * @throws if card path cannot be found
+   * @returns path to a card's attachment folder.
+   */
+  public cardAttachmentFolder(cardKey: string): string {
+    const pathToCard = this.findCard(cardKey).path;
+    return join(pathToCard, 'a');
+  }
+
+  /**
+   * Creates an attachment for a card.
+   * @param cardKey The card to add attachment to
+   * @param attachmentName The name for the attachment file
+   * @param attachmentData The attachment data (file path or buffer)
+   * @throws If trying to add attachment to module card, or if attachment is not found
    */
-  public async cardAttachmentFolder(cardKey: string): Promise<string> {
-    // Check if it is a template card.
-    if (await this.isTemplateCard(cardKey)) {
-      const cardPath = await this.cardFolder(cardKey);
-      return join(cardPath, 'a');
+  public async createCardAttachment(
+    cardKey: string,
+    attachmentName: string,
+    attachmentData: string | Buffer,
+  ): Promise<void> {
+    const attachmentFolder = this.cardAttachmentFolder(cardKey);
+
+    // Check if this is a module template
+    if (isModulePath(attachmentFolder)) {
+      throw new Error(`Cannot modify imported module`);
     }
 
-    const pathToProjectCard = this.pathToCard(cardKey);
-    if (!pathToProjectCard) {
-      throw new Error(`Card '${cardKey}' not found`);
+    // Create the attachment folder if it doesn't exist
+    await mkdir(attachmentFolder, { recursive: true });
+
+    const attachmentPath = join(attachmentFolder, basename(attachmentName));
+
+    if (Buffer.isBuffer(attachmentData)) {
+      await writeFile(attachmentPath, attachmentData, { flag: 'wx' });
+    } else {
+      try {
+        await copyFile(
+          attachmentData,
+          attachmentPath,
+          fsConstants.COPYFILE_EXCL,
+        );
+      } catch {
+        throw new Error(`Attachment file not found: ${attachmentData}`);
+      }
     }
-    return join(this.paths.cardRootFolder, pathToProjectCard, 'a');
+
+    // Update cache
+    await this.handleAttachmentChange(
+      cardKey,
+      'added',
+      basename(attachmentName),
+    );
   }
 
   /**
-   * Returns details (as defined by cardDetails) of a card.
-   * @param cardKey card key (project prefix and a number, e.g. test_1)
-   * @param cardDetails which card details are returned.
-   * @returns Card details, or undefined if the card cannot be found.
+   * Removes an attachment from a card.
+   * @param cardKey The card to remove attachment from
+   * @param fileName The name of the attachment file to remove
+   * @throws if trying to remove module card attachment, or the attachment was not found.
    */
-  public async cardDetailsById(
+  public async removeCardAttachment(
     cardKey: string,
-    cardDetails: ProjectFetchCardDetails,
-  ): Promise<Card | undefined> {
-    return this.findSpecificCard(cardKey, cardDetails);
+    fileName: string,
+  ): Promise<void> {
+    const attachmentFolder = this.cardAttachmentFolder(cardKey);
+
+    // Modules cannot be modified.
+    if (isModulePath(attachmentFolder)) {
+      throw new Error(`Cannot modify imported module`);
+    }
+
+    const attachmentPath = join(attachmentFolder, fileName);
+
+    try {
+      await unlink(attachmentPath);
+    } catch (error) {
+      this.logger.error({ error }, 'Removing card attachment');
+      throw new Error(`Attachment not found: ${fileName}`);
+    }
+    await this.handleAttachmentChange(cardKey, 'removed', fileName);
   }
 
   /**
-   * Returns path to card's folder.
+   * Returns path to a card's folder.
    * @param cardKey card key
-   * @returns path to card's folder.
+   * @returns path to a card's folder.
    */
   public async cardFolder(cardKey: string): Promise<string> {
-    const found = await super.findCard(this.paths.cardRootFolder, cardKey);
+    const found = super.findCard(cardKey);
     if (found) {
       return found.path;
     }
 
     const templates = await this.templates();
-    const templatePromises = templates.map(async (template) => {
+    const templatePromises = templates.map((template) => {
       const templateObject = new TemplateResource(
         this,
         resourceName(template.name),
       ).templateObject();
       const templateCard = templateObject
-        ? await templateObject.findSpecificCard(cardKey)
+        ? templateObject.findCard(cardKey)
         : undefined;
-      return templateCard ? templateCard.path : '';
+      const path = templateCard ? templateCard.path : '';
+      return path;
     });
 
     const templatePaths = await Promise.all(templatePromises);
@@ -254,78 +488,41 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Splits card path to parts. Returns the parts.
-   * Returned parts are: prefix, card key, array of parents and template name. Template name is returned only for template cards.
-   * @param cardPath path to a card
-   * @returns card path logical parts
-   * @throws when called with wrong path, or wrong card owner
-   * todo: if prefix would be parameter; this could be static, or util method
+   * Fetches full Card data for given card keys
+   * @param cardIds array of card keys to fetch
+   * @returns Card data to the given card keys
    */
-  public cardPathParts(cardPath: string) {
-    const pathParts = cardPath.split(sep);
-    const cardKey = pathParts.at(pathParts.length - 1);
-    const parents = [];
-    let prefix = this.projectPrefix;
-    let template = '';
-    let startIndex = -1;
-    let templatesNameIndex = -1;
-
-    const cardRootIndex = pathParts.indexOf('cardRoot');
-    const projectInternalsIndex = pathParts.indexOf('.cards');
-
-    if (projectInternalsIndex === -1 && cardRootIndex >= 0) {
-      startIndex = projectInternalsIndex;
-    } else if (projectInternalsIndex >= 0 && cardRootIndex === -1) {
-      const templatesIndex = pathParts.indexOf('templates');
-      startIndex = templatesIndex;
-      if (templatesIndex === -1) {
-        throw new Error(
-          `Invalid card path. Template card must have 'templates' in path`,
-        );
-      }
-      const modulesIndex = pathParts.indexOf('modules');
-      if (modulesIndex !== -1) {
-        prefix = pathParts.at(modulesIndex + 1) || '';
-      }
-      templatesNameIndex = templatesIndex + 1;
-      template = `${prefix}/templates/${pathParts.at(templatesNameIndex)}`;
-    } else {
-      throw new Error(`Card must be either project card, or template card`);
-    }
-
-    // Look for parents in the path.
-    let previousWasParent = false;
-    for (let index = startIndex; index <= pathParts.length; index++) {
-      if (previousWasParent) {
-        previousWasParent = false;
-        parents.push(pathParts.at(index - 2));
-      }
-      const cardsSubFolder = pathParts.at(index) === 'c';
-      const ignoreOrNotTemplatesParent =
-        index - 1 !== templatesNameIndex || templatesNameIndex === -1;
-      if (cardsSubFolder && ignoreOrNotTemplatesParent) {
-        previousWasParent = true;
+  public cardKeysToCards(cardIds: string[]): Card[] {
+    const cards: Card[] = [];
+    for (const cardId of cardIds) {
+      const card = this.cardCache.getCard(cardId);
+      if (card) {
+        cards.push(card);
       }
     }
+    return cards;
+  }
 
-    return {
-      cardKey: cardKey,
-      parents: parents,
-      prefix: prefix,
-      template: template,
-    };
+  /**
+   * Accessor for cards cache.
+   * Used by template container (it needs to access project's cache, not their own instance).
+   * @note Should not be used directly (other than Template).
+   */
+  public get cardsCache() {
+    return this.cardCache;
   }
 
   /**
-   * Returns an array of all the cards in the project. Cards have content and metadata
-   * @param path Optional path from which to fetch the cards. Generally it is best to fetch from Project root, e.g. Project.cardRootFolder
-   * @param details Which details to include in the cards; by default only "content" and "metadata" are included.
+   * Returns an array of all the cards in the project.
+   * @note These are project cards only, by default (unless path dictates otherwise).
+   * @param path Path from which to fetch the cards. Generally it is best to fetch from Project root, e.g. Project.cardRootFolder
+   * @param details Which details to include in the cards; by default all details are included.
    * @returns all cards from the given path in the project.
    */
-  public async cards(
+  public cards(
     path: string = this.paths.cardRootFolder,
-    details: FetchCardDetails = { content: true, metadata: true },
-  ): Promise<Card[]> {
+    details?: FetchCardDetails,
+  ): Card[] {
     return super.cards(path, details);
   }
 
@@ -340,6 +537,22 @@ export class Project extends CardContainer {
     return this.resources.resources('cardTypes', from);
   }
 
+  /**
+   * Returns children of a given card; as Card array
+   * @param card Parent card to fetch children from
+   * @returns children of a given card; as Card array
+   */
+  public childrenCards(card: Card): Card[] {
+    const cards: Card[] = [];
+    for (const child of card.children) {
+      const card = this.cardCache.getCard(child);
+      if (card) {
+        cards.push(card);
+      }
+    }
+    return cards;
+  }
+
   /**
    * Updates all local resources.
    */
@@ -350,8 +563,8 @@ export class Project extends CardContainer {
   /**
    * Updates all imported module resources.
    */
-  public async collectModuleResources() {
-    await this.resources.moduleImported();
+  public collectModuleResources() {
+    this.resources.moduleImported();
   }
 
   /**
@@ -371,7 +584,7 @@ export class Project extends CardContainer {
     if (!card || !card.path || !isTemplateCard(card)) {
       return undefined;
     }
-    const { template } = this.cardPathParts(card.path);
+    const { template } = cardPathParts(this.projectPrefix, card.path);
     return new TemplateResource(this, resourceName(template)).templateObject();
   }
 
@@ -421,46 +634,8 @@ export class Project extends CardContainer {
    * @param details Defines which card details are included in the return values.
    * @returns specific card details, or undefined if card is not part of the project.
    */
-  public async findSpecificCard(
-    cardToFind: string,
-    details: ProjectFetchCardDetails = {},
-  ): Promise<Card | undefined> {
-    let card;
-
-    if (
-      details.location === CardLocation.projectOnly ||
-      details.location === CardLocation.all ||
-      !details.location
-    ) {
-      card = await super.findCard(
-        this.paths.cardRootFolder,
-        cardToFind,
-        details,
-      );
-    }
-
-    if (
-      !card &&
-      (details.location === CardLocation.templatesOnly ||
-        details.location === CardLocation.all ||
-        !details.location)
-    ) {
-      const templates = await this.templates();
-      for (const template of templates) {
-        const templateObject = new TemplateResource(
-          this,
-          resourceName(template.name),
-        ).templateObject();
-        if (!templateObject) continue;
-
-        // optimize: execute each find in template parallel
-        card = await templateObject.findSpecificCard(cardToFind, details);
-        if (card) {
-          break;
-        }
-      }
-    }
-    return card;
+  public findCard(cardToFind: string, details?: ProjectFetchCardDetails): Card {
+    return super.findCard(cardToFind, details);
   }
 
   /**
@@ -490,6 +665,7 @@ export class Project extends CardContainer {
    * @param changedCard Card that was changed.
    */
   public async handleCardChanged(changedCard: Card) {
+    // Notify the calculation engine about the change
     return this.calculationEngine.handleCardChanged(changedCard);
   }
 
@@ -497,39 +673,86 @@ export class Project extends CardContainer {
    * When cards are removed.
    * @param deletedCard Card that is to be removed.
    */
-  public async handleDeleteCard(deletedCard: Card) {
+  public async handleCardDeleted(deletedCard: Card) {
+    // Delete children from the cache first
+    if (deletedCard.children && deletedCard.children.length > 0) {
+      for (const child of deletedCard.children) {
+        try {
+          const childCard = this.findCard(child);
+          await this.handleCardDeleted(childCard);
+        } catch {
+          this.logger.warn(
+            `Accessing child '${child}' of '${deletedCard.key}' when deleting cards caused an exception`,
+          );
+          continue;
+        }
+      }
+    }
+    await super.removeCard(deletedCard.key);
     return this.calculationEngine.handleDeleteCard(deletedCard);
   }
 
   /**
-   * When new cards are added.
-   * @param cards Added cards.
+   * When card is moved.
+   * @param movedCard Card that moved
+   * @param newParentCard New parent for the 'movedCard'
+   * @param oldParentCard Previous parent of the 'movedCard'
    */
-  public async handleNewCards(cards: Card[]) {
-    return this.calculationEngine.handleNewCards(cards);
+  public async handleCardMoved(
+    movedCard: Card,
+    newParentCard?: Card,
+    oldParentCard?: Card,
+  ) {
+    if (newParentCard) {
+      this.cardCache.updateCard(newParentCard.key, newParentCard);
+    }
+    if (oldParentCard) {
+      this.cardCache.updateCard(oldParentCard.key, oldParentCard);
+    }
+    this.cardCache.updateCard(movedCard.key, movedCard);
+
+    // todo: it would be enough to just update parent, previous parent and changed card
+    this.cardCache.populateChildrenRelationships();
+    await this.handleCardChanged(movedCard);
+    await this.calculationEngine.handleCardMoved();
   }
 
   /**
-   * Checks if a given card is part of this project.
-   * @param cardKey card to check.
-   * @returns true if a given card is found from project, false otherwise.
+   * When new cards are added.
+   * @param cards Added cards.
    */
-  public hasCard(cardKey: string): boolean {
-    return super.hasCard(cardKey, this.paths.cardRootFolder);
+  public async handleNewCards(cards: Card[]) {
+    // Add new cards to the card cache
+    cards.forEach((card) => {
+      const cardWithParent = {
+        ...card,
+        parent: card.parent || this.parentFromPath(card.path),
+      };
+
+      this.cardCache.updateCard(cardWithParent.key, cardWithParent);
+
+      // Update the parent's children list in the cache
+      if (cardWithParent.parent && cardWithParent.parent !== ROOT) {
+        this.updateCachedChildren(cardWithParent.parent, cardWithParent);
+      }
+    });
+    return this.calculationEngine.handleNewCards(cards);
   }
 
   /**
    * Adds a module from project.
-   * @param module Name of the module
+   * @param module Module to add
    */
   public async importModule(module: ModuleSetting) {
     // Add module as a dependency.
     await this.configuration.addModule(module);
-    await this.collectModuleResources();
+    this.collectModuleResources();
+    await this.populateTemplateCards();
+    this.logger.info(`Imported module '${module.name}'`);
   }
 
   /**
-   * Checks if given path is a project.
+   * Checks if a given path is a project.
    * @param path Path to a project
    * @returns true, if in the given path there is a project; false otherwise
    */
@@ -537,17 +760,6 @@ export class Project extends CardContainer {
     return pathExists(join(path, 'cardRoot'));
   }
 
-  /**
-   * Returns whether card is a template card or not
-   * @param cardKey card to check.
-   * @todo: This is only used from 'remove'. Could it use the static checker?
-   * @returns true, if card is template card; false otherwise
-   */
-  public async isTemplateCard(cardKey: string): Promise<boolean> {
-    const templateCards = await this.allTemplateCards();
-    return templateCards.find((card) => card.key === cardKey) != null;
-  }
-
   /**
    * Returns an array of all the link types in the project.
    * @param from Defines where resources are collected from.
@@ -563,7 +775,7 @@ export class Project extends CardContainer {
    * Returns an array of cards in the project, in the templates or both.
    * Cards don't have content and nor metadata.
    * @param cardsFrom Where to return cards from (project, templates, or both)
-   * @returns all cards in the project.
+   * @returns all cards in the project per container.
    */
   public async listCards(
     cardsFrom: CardLocation = CardLocation.all,
@@ -573,9 +785,9 @@ export class Project extends CardContainer {
       cardsFrom === CardLocation.all ||
       cardsFrom === CardLocation.projectOnly
     ) {
-      const projectCards = (await super.cards(this.paths.cardRootFolder)).map(
-        (item) => item.key,
-      );
+      const projectCards = super
+        .cards(this.paths.cardRootFolder)
+        .map((item) => item.key);
       cardListContainer.push({
         name: this.projectName,
         type: 'project',
@@ -595,8 +807,8 @@ export class Project extends CardContainer {
         ).templateObject();
         if (templateObject) {
           // todo: optimization - do all this in parallel
-          const templateCards = await templateObject.listCards();
-          if (templateCards) {
+          const templateCards = templateObject.listCards();
+          if (templateCards.length) {
             cardListContainer.push({
               name: template.name,
               type: 'template',
@@ -618,69 +830,27 @@ export class Project extends CardContainer {
   public async listCardIds(
     cardsFrom: CardLocation = CardLocation.all,
   ): Promise<Set<string>> {
-    const promises: Promise<Set<string>>[] = [];
-    if (
-      cardsFrom === CardLocation.all ||
-      cardsFrom === CardLocation.projectOnly
-    ) {
-      promises.push(
-        super
-          .cards(this.paths.cardRootFolder)
-          .then((cards) => new Set(cards.map((card) => card.key))),
-      );
+    const cardContainers = await this.listCards(cardsFrom);
+    const allCardIDs = new Set<string>();
+    for (const container of cardContainers) {
+      const cards = container.cards;
+      cards.forEach((card) => allCardIDs.add(card));
     }
-    if (
-      cardsFrom === CardLocation.all ||
-      cardsFrom === CardLocation.templatesOnly
-    ) {
-      promises.push(
-        (async () => {
-          const templates = await this.templates();
-          const templateResources = templates.map(
-            (template) =>
-              new TemplateResource(this, resourceName(template.name)),
-          );
-          const templateObjectsResults =
-            await Promise.allSettled(templateResources);
-          const templateObjects = templateObjectsResults
-            .filter(
-              (result): result is PromiseFulfilledResult<TemplateResource> =>
-                result.status === 'fulfilled' && result.value !== null,
-            )
-            .map((result) => result.value);
-
-          const listCardsResults = await Promise.allSettled(
-            templateObjects.map((obj) => obj.templateObject().listCards()),
-          );
-          const templateCardIds = new Set<string>();
-          listCardsResults
-            .filter(
-              (result): result is PromiseFulfilledResult<Card[]> =>
-                result.status === 'fulfilled',
-            )
-            .forEach((result) => {
-              result.value.forEach((card) => templateCardIds.add(card.key));
-            });
-          return templateCardIds;
-        })(),
-      );
-    }
-    const allCardIdSets = await Promise.all(promises);
-    return new Set(allCardIdSets.flatMap((set) => [...set]));
+    return allCardIDs;
   }
 
   /**
    * Returns details of a certain module.
    * @param moduleName Name of the module.
-   * @returns module details, or undefined if workflow cannot be found.
+   * @returns module details, or undefined if module cannot be found.
    */
   public async module(moduleName: string): Promise<ModuleContent | undefined> {
     const module = await this.findModule(moduleName);
     if (module && module.path) {
       const modulePath = join(module.path, module.name);
-      const moduleConfig = (await readJsonFile(
+      const moduleConfig = await readJsonFile(
         join(modulePath, Project.projectConfigFileName),
-      )) as ModuleContent;
+      );
       return {
         name: moduleConfig.name,
         modules: moduleConfig.modules,
@@ -822,15 +992,12 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Returns full path to a given card.
-   * @param cardKey card to check path for.
-   * @returns path to a given card.
+   * Populates the card cache, if it has not been populated.
    */
-  public pathToCard(cardKey: string): string {
-    const allFiles = getFilesSync(this.paths.cardRootFolder);
-    const cardIndexJsonFile = join(cardKey, Project.cardMetadataFile);
-    const foundFile = allFiles.find((file) => file.includes(cardIndexJsonFile));
-    return foundFile ? dirname(foundFile) : '';
+  public async populateCaches() {
+    if (!this.cardCache.isPopulated) {
+      await this.populateCardsCache();
+    }
   }
 
   /**
@@ -857,6 +1024,7 @@ export class Project extends CardContainer {
     const prefixes: string[] = [this.projectPrefix];
     let files;
     try {
+      // TODO: Could be optimized so that prefixes are stored once fetched.
       files = await readdir(this.paths.modulesFolder, {
         withFileTypes: true,
         recursive: true,
@@ -874,13 +1042,48 @@ export class Project extends CardContainer {
 
       const configurationPrefixes = await Promise.all(configurationPromises);
       prefixes.push(...configurationPrefixes);
-    } catch {
-      // do nothing if readdir throws // TODO: Log it
+    } catch (error) {
+      this.logger.error({ error }, 'Failed to collect prefixes in use');
     }
 
     return prefixes;
   }
 
+  /**
+   * Removes a module from the project
+   * @param module Module (name) to remove.
+   */
+  public async removeModule(moduleName: string) {
+    const toBeRemovedTemplates = this.resources.moduleResources.resourceArray(
+      'templates',
+      moduleName,
+    );
+    // First, remove cards from the cache
+    for (const template of toBeRemovedTemplates) {
+      this.cardCache.deleteCardsFromTemplate(template.name);
+    }
+
+    // Then, remove module from project configuration
+    await this.configuration.removeModule(moduleName);
+    this.collectModuleResources();
+
+    this.logger.info(`Removed module '${moduleName}'`);
+  }
+
+  /**
+   * Removes a resource from Project.
+   * @param resource Resource to remove.
+   */
+  public removeResource(resource: Resource) {
+    // Template cards must be removed from the cache when resource is removed.
+    if (resource.path.includes('templates')) {
+      const templateName = resourceNameToString(resourceName(resource.name));
+      this.cardCache.deleteCardsFromTemplate(templateName);
+    }
+    this.resources.remove(resource);
+    this.createdResources.delete(resource.name);
+  }
+
   /**
    * Array of reports in the project.
    * @param from Defines where resources are collected from.
@@ -908,21 +1111,12 @@ export class Project extends CardContainer {
     return handleBarFiles;
   }
 
-  /**
-   * Removes a resource from Project.
-   * @param resource Resource to remove.
-   */
-  public removeResource(resource: Resource) {
-    this.resources.remove(resource);
-    this.createdResources.delete(resource.name);
-  }
-
   /**
    * Returns metadata from a given resource
    * @param name Name of a resource
    * @returns Metadata from the resource.
    */
-  public async resource<Type>(name: string): Promise<Type | undefined> {
+  public resource<Type>(name: string): Type | undefined {
     const resName = resourceName(name);
     if (this.createdResources.has(resourceNameToString(resName))) {
       const value = this.createdResources.get(
@@ -1022,45 +1216,23 @@ export class Project extends CardContainer {
    * Show cards of a project.
    * @returns an array of all project cards in the project.
    */
-  public async showProjectCards(): Promise<Card[]> {
+  public showProjectCards(): Card[] {
     return this.showCards(this.paths.cardRootFolder);
   }
 
-  /**
-   * Returns all template cards from the project. This includes all module templates' cards.
-   * @param cardDetails which details to fetch. Optional.
-   * @returns all the template cards from the project
-   */
-  public async allTemplateCards(
-    cardDetails?: FetchCardDetails,
-  ): Promise<Card[]> {
-    const templates = await this.templates();
-    const cards: Card[] = [];
-    for (const template of templates) {
-      const templateCards = await this.templateCards(
-        template.name,
-        cardDetails,
-      );
-      if (templateCards) cards.push(...templateCards);
-    }
-    return cards;
-  }
-
   /**
    * Returns cards from single template.
-   * @param templateName Name of the template
-   * @param cardDetails Card information
+   * @param templateName Name of the template (supports both full names like 'decision/templates/decision' and short names like 'decision')
    * @returns List of cards from template.
    */
-  public async templateCards(
-    templateName: string,
-    cardDetails?: FetchCardDetails,
-  ): Promise<Card[]> {
-    const templateObject = new TemplateResource(
-      this,
-      resourceName(templateName),
-    ).templateObject();
-    return await templateObject?.cards('', cardDetails);
+  public templateCards(templateName: string): Card[] {
+    const templateCards = this.cardCache.getAllTemplateCards();
+    return templateCards.filter((cachedCard) => {
+      if (cachedCard.location === 'project') {
+        return false;
+      }
+      return cachedCard.location === templateName;
+    });
   }
 
   /**
@@ -1075,20 +1247,21 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Update card content.
-   * @param cardKey card's ID that is updated.
+   * Update a card's content.
+   * @param cardKey card key to update.
    * @param content changed content
    */
   public async updateCardContent(cardKey: string, content: string) {
-    const card = await this.findCard(this.basePath, cardKey, {
-      metadata: true,
-      content: true,
-    });
-    if (!card) {
-      throw new Error(`Card '${cardKey}' does not exist in the project`);
-    }
+    const card = this.findCard(cardKey);
     card.content = content;
+
+    // Update lastUpdated timestamp in metadata
+    if (card.metadata) {
+      card.metadata.lastUpdated = new Date().toISOString();
+    }
+
     await this.saveCard(card);
+    await this.handleCardChanged(card);
   }
 
   /**
@@ -1102,21 +1275,15 @@ export class Project extends CardContainer {
     changedKey: string,
     newValue: MetadataContent,
   ) {
-    const templateCard = await this.isTemplateCard(cardKey);
-    const card = await this.findCard(
-      templateCard ? this.paths.templatesFolder : this.paths.cardRootFolder,
-      cardKey,
-      {
-        metadata: true,
-      },
-    );
-    if (!card) {
-      throw new Error(`Card '${cardKey}' does not exist in the project`);
-    }
-
+    const card = this.findCard(cardKey);
     if (!card.metadata || card.metadata[changedKey] === newValue) {
       return;
     }
+
+    const isRankChange = changedKey === 'rank';
+    const previousPath = isRankChange ? card.path : undefined;
+    const previousParent = isRankChange ? card.parent : undefined;
+
     const cardAsRecord: Record<string, MetadataContent> = card.metadata;
     cardAsRecord[changedKey] = newValue;
 
@@ -1127,35 +1294,70 @@ export class Project extends CardContainer {
       throw new Error(invalidCard);
     }
 
-    await this.saveCardMetadata(card);
+    const updated = await this.saveCardMetadata(card);
+    if (!updated) return;
+
+    // For rank changes, check if path changed (indicating a move)
+    if (isRankChange) {
+      const updatedCard = this.findCard(cardKey);
+      if (updatedCard.path !== previousPath) {
+        this.changeParent(updatedCard, previousParent);
+      }
+    }
   }
 
   /**
-   * Updates card metadata.
+   * Updates the entire card in the card cache and handles any path/parent changes.
+   * Also persists changes to content and metadata files.
+   * @param card The card with updated information (path, parent, metadata, etc.)
+   */
+  public async updateCard(card: Card) {
+    const cachedCard = this.cardCache.getCard(card.key);
+    const pathChange = cachedCard && cachedCard.path !== card.path;
+
+    if (pathChange) {
+      this.changeParent(card, cachedCard.parent);
+    }
+
+    const metadataChanged =
+      cachedCard &&
+      JSON.stringify(cachedCard.metadata) !== JSON.stringify(card.metadata);
+    if (metadataChanged) {
+      await this.saveCardMetadata(card);
+    }
+
+    const contentChanged = cachedCard && cachedCard.content !== card.content;
+    if (contentChanged) {
+      await this.saveCardContent(card);
+    }
+
+    this.cardCache.updateCard(card.key, card);
+    if (metadataChanged || contentChanged || pathChange) {
+      await this.handleCardChanged(card);
+    }
+  }
+
+  /**
+   * Updates a card's metadata.
    * @param card affected card
    * @param changedMetadata changed content for the card
    */
   public async updateCardMetadata(card: Card, changedMetadata: CardMetadata) {
     card.metadata = changedMetadata;
-    return this.saveCardMetadata(card);
+    if (await this.saveCardMetadata(card)) {
+      await this.handleCardChanged(card);
+    }
   }
 
-  /**
-   * Validates that card's data is valid.
-   * @param card Card to validate.
-   * @returns validation errors, if any
-   */
-  public async validateCard(card: Card): Promise<string> {
+  // Validates that card's data is valid.
+  private async validateCard(card: Card): Promise<string> {
     const invalidCustomData = await this.validator.validateCustomFields(
       this,
       card,
     );
-    const invalidWorkFlow = await this.validator.validateWorkflowState(
-      this,
-      card,
-    );
+    const invalidWorkFlow = this.validator.validateWorkflowState(this, card);
 
-    const invalidLabels = await this.validator.validateCardLabels(card);
+    const invalidLabels = this.validator.validateCardLabels(card);
     if (
       invalidCustomData.length === 0 &&
       invalidWorkFlow.length === 0 &&