@cyberismo/data-handler 0.0.2

package/src/commands/import.ts

@@ -0,0 +1,169 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+  details. You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import type { CardType } from '../interfaces/resource-interfaces.js';
+import { type Create, Validate } from './index.js';
+import { ModuleManager } from '../module-manager.js';
+import type { ModuleSettingOptions } from '../interfaces/project-interfaces.js';
+import type { Project } from '../containers/project.js';
+import { readCsvFile } from '../utils/csv.js';
+import { resourceName } from '../utils/resource-utils.js';
+import { TemplateResource } from '../resources/template-resource.js';
+
+export class Import {
+  private moduleManager: ModuleManager;
+  constructor(
+    private project: Project,
+    private createCmd: Create,
+  ) {
+    this.moduleManager = new ModuleManager(this.project, this);
+  }
+
+  /**
+   * Imports cards based on a csv file
+   * @param csvFilePath path to the csv file
+   * @param parentCardKey the cards in the csv file will be created under this card
+   * @returns card keys of the imported cards
+   */
+  public async importCsv(
+    csvFilePath: string,
+    parentCardKey?: string,
+  ): Promise<string[]> {
+    const csv = await readCsvFile(csvFilePath);
+
+    const isValid = Validate.getInstance().validateJson(csv, 'csvSchema');
+    if (isValid.length !== 0) {
+      throw new Error(isValid);
+    }
+
+    const importedCards = [];
+
+    for (const row of csv) {
+      const { title, template, description, labels, ...customFields } = row;
+      const templateResource = new TemplateResource(
+        this.project,
+        resourceName(template),
+      );
+      const templateObject = templateResource.templateObject();
+      if (!templateObject) {
+        throw new Error(`Template '${template}' not found`);
+      }
+
+      const templateCards = await templateObject.cards();
+      if (templateCards.length !== 1) {
+        console.warn(
+          `Template '${template}' for card '${title}' does not have exactly one card. Skipping row.`,
+        );
+        continue;
+      }
+
+      // Create card
+      const cards = await this.createCmd.createCard(template, parentCardKey);
+
+      if (cards.length !== 1) {
+        throw new Error('Card not created');
+      }
+      const cardKey = cards[0].key;
+      const card = await this.project.findSpecificCard(cardKey, {
+        metadata: true,
+      });
+      const cardType = await this.project.resource<CardType>(
+        card?.metadata?.cardType || '',
+      );
+
+      if (!cardType) {
+        throw new Error(`Card type not found for card ${cardKey}`);
+      }
+
+      if (description) {
+        await this.project.updateCardContent(cardKey, description);
+      }
+
+      if (labels) {
+        for (const label of labels.split(' ')) {
+          try {
+            await this.createCmd.createLabel(cardKey, label);
+          } catch (e) {
+            console.error(
+              `Failed to create label ${label}: ${e instanceof Error ? e.message : 'Unknown error'}`,
+            );
+          }
+        }
+      }
+
+      await this.project.updateCardMetadataKey(cardKey, 'title', title);
+      for (const [key, value] of Object.entries(customFields)) {
+        if (cardType.customFields.find((field) => field.name === key)) {
+          await this.project.updateCardMetadataKey(cardKey, key, value);
+        }
+      }
+      importedCards.push(cardKey);
+    }
+    return importedCards;
+  }
+
+  /**
+   * Imports a module to a project. Copies resources to the project.
+   * Resources will be added to a new directory under '.cards/modules'.
+   * The name of the new folder will be module's prefix.
+   *
+   * Note that file references are relative, and thus URI must be
+   * 'file:<relative path>', instead of 'file://<relative path>'.
+   *
+   * @param source Path to module that will be imported
+   * @param destination Path to project that will receive the imported module
+   * @param options Additional options for module import. Optional.
+   *        branch: Git branch for module from Git.
+   *        private: If true, uses credentials to clone the repository
+   */
+  public async importModule(
+    source: string,
+    destination?: string,
+    options?: ModuleSettingOptions,
+  ) {
+    const gitModule = source.startsWith('https');
+    const modulePrefix = gitModule
+      ? await this.moduleManager.importGitModule(source, options)
+      : await this.moduleManager.importFileModule(source, destination);
+
+    if (!modulePrefix) {
+      throw new Error(
+        `Cannot find prefix for imported module '${source}'. Import cancelled.`,
+      );
+    }
+
+    // Add module as a dependency.
+    return this.project.importModule({
+      name: modulePrefix,
+      branch: options ? options.branch : undefined,
+      private: options ? options.private : undefined,
+      location: gitModule ? source : `file:${source}`,
+    });
+  }
+
+  /**
+   * Updates all imported modules.
+   */
+  public async updateAllModules() {
+    return this.moduleManager.update();
+  }
+
+  /**
+   * Updates 'moduleName' module from its source.
+   * Modules using gitUrl, are first copied to .temp
+   * @param moduleName module name (prefix) to update
+   */
+  public async updateExistingModule(moduleName: string) {
+    await this.moduleManager.importFileModule(moduleName);
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,42 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero
+  General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { Calculate } from './calculate.js';
+import { Create } from './create.js';
+import { Edit } from './edit.js';
+import { Export } from './export.js';
+import { ExportSite } from './export-site.js';
+import { Import } from './import.js';
+import { Move } from './move.js';
+import { Remove } from './remove.js';
+import { Rename } from './rename.js';
+import { Show } from './show.js';
+import { Transition } from './transition.js';
+import { Update } from './update.js';
+import { Validate } from './validate.js';
+
+export {
+  Calculate,
+  Create,
+  Edit,
+  Export,
+  ExportSite,
+  Import,
+  Move,
+  Remove,
+  Rename,
+  Show,
+  Transition,
+  Update,
+  Validate,
+};

package/src/commands/move.ts

@@ -0,0 +1,451 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// node
+import { join, sep } from 'node:path';
+
+import { ActionGuard } from '../permissions/action-guard.js';
+import { copyDir, deleteDir } from '../utils/file-utils.js';
+import type { Calculate } from './index.js';
+import type {
+  Card,
+  FetchCardDetails,
+} from '../interfaces/project-interfaces.js';
+import { type Project, ResourcesFrom } from '../containers/project.js';
+import {
+  EMPTY_RANK,
+  FIRST_RANK,
+  getRankAfter,
+  getRankBetween,
+  rebalanceRanks,
+  sortItems,
+} from '../utils/lexorank.js';
+import { isTemplateCard } from '../utils/card-utils.js';
+import { resourceName } from '../utils/resource-utils.js';
+import { TemplateResource } from '../resources/template-resource.js';
+
+// @todo - we should have project wide constants, so that if we need them, only the const value needs to be changed.
+const ROOT: string = 'root';
+
+export class Move {
+  constructor(
+    private project: Project,
+    private calculateCmd: Calculate,
+  ) {}
+
+  // Fetches a card (either template or project card).
+  private async getCard(cardKey: string, options: FetchCardDetails) {
+    let card: Card | undefined;
+    const templateCard = await this.project.isTemplateCard(cardKey);
+    if (templateCard) {
+      card = (await this.project.allTemplateCards(options)).find(
+        (card) => card.key === cardKey,
+      );
+    } else {
+      card = await this.project.findSpecificCard(cardKey, options);
+    }
+    if (!card) {
+      throw new Error('Card was not found from the project');
+    }
+    return card;
+  }
+
+  // Returns children of a parent card or root cards
+  private async getSiblings(card: Card) {
+    const parentCardKey = card.parent || ROOT;
+
+    // since we don't know if 'root' is templateRoot or cardRoot, we need to check the card
+    if (parentCardKey === ROOT) {
+      if (isTemplateCard(card)) {
+        const template = this.project.createTemplateObjectFromCard(card);
+        if (!template) {
+          throw new Error(
+            `Cannot find template for the template card '${card.key}'`,
+          );
+        }
+        if (card?.path.includes(`${sep}modules${sep}`)) {
+          throw new Error(`Cannot rank module cards`);
+        }
+        return template.cards();
+      }
+    }
+
+    let parentCard;
+    if (parentCardKey !== ROOT) {
+      parentCard = await this.project.findSpecificCard(parentCardKey, {
+        children: true,
+        metadata: true,
+      });
+      if (!parentCard) {
+        throw new Error(`Card ${parentCardKey} not found from project`);
+      }
+    }
+
+    if (parentCard) {
+      return parentCard.children || [];
+    }
+
+    return this.project.showProjectCards();
+  }
+
+  //
+  private async rebalanceCards(cards: Card[]) {
+    const ranks = rebalanceRanks(cards.length);
+
+    cards = sortItems(cards, (item) => item.metadata?.rank || 'z');
+
+    for (let i = 0; i < cards.length; i++) {
+      const card = cards[i];
+      await this.project.updateCardMetadataKey(card.key, 'rank', ranks[i]);
+    }
+  }
+
+  // Rebalances the project recursively.
+  private async rebalanceProjectRecursively(cards: Card[]) {
+    const ranks = rebalanceRanks(cards.length);
+
+    cards = sortItems(cards, (item) => item.metadata?.rank || 'z');
+
+    for (let i = 0; i < cards.length; i++) {
+      const card = cards[i];
+      await this.project.updateCardMetadataKey(card.key, 'rank', ranks[i]);
+      if (card.children && card.children.length > 0) {
+        await this.rebalanceProjectRecursively(card.children);
+      }
+    }
+  }
+
+  /**
+   * Moves card from 'destination' to 'source'.
+   * @param source source card to move
+   * @param destination destination card where source card will be moved to; or to root
+   */
+  public async moveCard(source: string, destination: string) {
+    if (source === ROOT) {
+      throw new Error('Cannot move "root"');
+    }
+    if (source === destination) {
+      throw new Error(`Card cannot be moved to itself`);
+    }
+    const promiseContainer = [];
+    promiseContainer.push(this.project.findSpecificCard(source));
+    if (destination !== ROOT) {
+      promiseContainer.push(this.project.findSpecificCard(destination));
+    } else {
+      const returnObject: Card = {
+        key: '',
+        path: this.project.paths.cardRootFolder,
+        children: [],
+        attachments: [],
+      };
+      promiseContainer.push(Promise.resolve(returnObject));
+    }
+    const [sourceCard, destinationCard] = await Promise.all(promiseContainer);
+
+    if (!sourceCard) {
+      throw new Error(`Card ${source} not found from project`);
+    }
+    if (!destinationCard) {
+      throw new Error(`Card ${destination} not found from project`);
+    }
+
+    if (destinationCard.path.includes(source)) {
+      throw new Error(`Card cannot be moved to inside itself`);
+    }
+
+    // Imported templates cannot be modified.
+    if (
+      destinationCard.path.includes(`${sep}modules`) ||
+      sourceCard.path.includes(`${sep}modules${sep}`)
+    ) {
+      throw new Error(`Cannot modify imported module templates`);
+    }
+
+    const bothTemplateCards =
+      isTemplateCard(sourceCard) && isTemplateCard(destinationCard);
+    const bothProjectCards =
+      this.project.hasCard(sourceCard.key) &&
+      this.project.hasCard(destinationCard.key);
+    if (!(bothTemplateCards || bothProjectCards)) {
+      throw new Error(
+        `Cards cannot be moved from project to template or vice versa`,
+      );
+    }
+
+    const destinationPath =
+      destination === ROOT
+        ? join(this.project.paths.cardRootFolder, sourceCard.key)
+        : join(destinationCard.path, 'c', sourceCard.key);
+
+    // if the card is already in the destination, do nothing
+    if (sourceCard.path === destinationPath) {
+      return;
+    }
+
+    // if both are project cards, make sure source card can be moved
+    const actionGuard = new ActionGuard(this.calculateCmd);
+    await actionGuard.checkPermission('move', source);
+
+    // rerank the card in the new location
+    // it will be the last one in the new location
+    let children;
+    if (destination !== ROOT) {
+      const parent = await this.project.findSpecificCard(destination, {
+        children: true,
+        metadata: true,
+      });
+      if (!parent) {
+        throw new Error(`Parent card ${destination} not found from project`);
+      }
+      children = parent.children;
+    } else {
+      children = await this.project.showProjectCards();
+    }
+
+    if (!children) {
+      throw new Error(`Children not found from card ${destination}`);
+    }
+
+    children = sortItems(children, (item) => item?.metadata?.rank || '1|z');
+    const lastChild = children[children.length - 1];
+
+    const rank =
+      lastChild && lastChild.metadata
+        ? getRankAfter(lastChild.metadata.rank)
+        : FIRST_RANK;
+    await this.project.updateCardMetadataKey(sourceCard.key, 'rank', rank);
+    await copyDir(sourceCard.path, destinationPath);
+    await deleteDir(sourceCard.path);
+  }
+
+  /**
+   * Ranks card using position given as 'index'.
+   * @param cardKey card key
+   * @param index to which position should card be ranked to
+   */
+  public async rankByIndex(cardKey: string, index: number) {
+    if (index < 0) {
+      throw new Error(`Index must be greater than 0`);
+    }
+    if (index === 0) {
+      await this.rankFirst(cardKey);
+      return;
+    }
+
+    const card = await this.project.findSpecificCard(cardKey, {
+      metadata: true,
+      parent: true,
+    });
+
+    if (!card || !card.parent) {
+      throw new Error(`Card ${cardKey} not found from project`);
+    }
+
+    const children = sortItems(
+      await this.getSiblings(card),
+      (item) => item.metadata?.rank || EMPTY_RANK,
+    );
+
+    if (!children || children.length === 0) {
+      throw new Error(`Children not found from card ${card.parent}`);
+    }
+
+    if (children.length < index) {
+      throw new Error(`Index ${index} is out of bounds`);
+    }
+    await this.rankCard(cardKey, children[index - 1].key);
+  }
+
+  /**
+   * Sets the rank of a card to be after another card.
+   * @param cardKey Card to rank
+   * @param beforeCardKey Card key after which the card will be ranked
+   */
+  public async rankCard(cardKey: string, beforeCardKey: string) {
+    const card = await this.project.findSpecificCard(cardKey, {
+      metadata: true,
+      parent: true,
+    });
+    if (!card) {
+      throw new Error(`Card ${cardKey} not found from project`);
+    }
+
+    const beforeCard = await this.project.findSpecificCard(beforeCardKey, {
+      metadata: true,
+      parent: true,
+    });
+
+    if (!beforeCard) {
+      throw new Error(`Card ${beforeCardKey} not found from project`);
+    }
+
+    if (beforeCard.parent !== card.parent) {
+      throw new Error(`Cards must be from the same parent`);
+    }
+
+    const children = sortItems(
+      await this.getSiblings(beforeCard),
+      (item) => item.metadata?.rank || EMPTY_RANK,
+    );
+
+    if (!children) {
+      throw new Error(`Children not found from card ${beforeCard.parent}`);
+    }
+
+    const beforeCardIndex = children.findIndex(
+      (child) => child.key === beforeCard.key,
+    );
+
+    if (beforeCardIndex === -1) {
+      throw new Error(
+        `Card ${beforeCardKey} is not a child of ${beforeCard.parent}`,
+      );
+    }
+
+    if (
+      children[beforeCardIndex].key === cardKey ||
+      children[beforeCardIndex + 1]?.key === cardKey
+    ) {
+      throw new Error(`Card ${cardKey} is already in the correct position`);
+    }
+
+    if (beforeCardIndex === children.length - 1) {
+      await this.project.updateCardMetadataKey(
+        cardKey,
+        'rank',
+        getRankAfter(beforeCard.metadata?.rank as string),
+      );
+    } else {
+      await this.project.updateCardMetadataKey(
+        cardKey,
+        'rank',
+        getRankBetween(
+          beforeCard.metadata?.rank as string,
+          children[beforeCardIndex + 1].metadata?.rank as string,
+        ),
+      );
+    }
+  }
+
+  /**
+   * Ranks card first.
+   * @param cardKey card key
+   */
+  public async rankFirst(cardKey: string) {
+    const card = await this.getCard(cardKey, {
+      metadata: true,
+      parent: true,
+    });
+
+    const children = sortItems(
+      await this.getSiblings(card),
+      (item) => item.metadata?.rank || EMPTY_RANK,
+    );
+
+    if (!children || children.length === 0) {
+      throw new Error(`Children not found from card ${card.parent}`);
+    }
+
+    if (children[0].key === cardKey && children[0].metadata?.rank) {
+      return;
+    }
+
+    const firstRank = children[0].metadata?.rank;
+    if (!firstRank) {
+      await this.project.updateCardMetadataKey(cardKey, 'rank', FIRST_RANK);
+      return;
+    }
+
+    // Set the rank to be the first one
+    if (firstRank === FIRST_RANK) {
+      // if the first card is already at the first rank, we need to move the card to the next one
+      const secondRank = children[1].metadata?.rank;
+      if (!secondRank) {
+        throw new Error(`Second rank not found`);
+      }
+      const rankBetween = getRankBetween(firstRank, secondRank);
+      await this.project.updateCardMetadataKey(
+        children[0].key,
+        'rank',
+        rankBetween,
+      );
+      await this.project.updateCardMetadataKey(cardKey, 'rank', firstRank);
+    } else {
+      // if the card is not at the first rank, we just use the first rank
+      await this.project.updateCardMetadataKey(cardKey, 'rank', FIRST_RANK);
+    }
+  }
+
+  /**
+   *  Rebalances the ranks of the children of a card.
+   * @param parentCardKey parent card key
+   */
+  public async rebalanceChildren(parentCardKey: string) {
+    const parentCard = await this.project.findSpecificCard(parentCardKey, {
+      children: true,
+      metadata: true,
+    });
+    if (!parentCard || !parentCard.children) {
+      throw new Error(`Card ${parentCardKey} not found from project`);
+    }
+    await this.rebalanceCards(parentCard.children);
+  }
+
+  /**
+   * Rebalances the ranks of the cards in the whole project, including templates
+   * Can be used even if the ranks do not exist
+   */
+  public async rebalanceProject() {
+    const cards = await this.project.showProjectCards();
+
+    await this.rebalanceProjectRecursively(cards);
+
+    // rebalance templates
+    const templates = await this.project.templates(ResourcesFrom.localOnly);
+    for (const template of templates) {
+      const templateResource = new TemplateResource(
+        this.project,
+        resourceName(template.name),
+      );
+      const templateObject = templateResource.templateObject();
+
+      if (!templateObject) {
+        throw new Error(`Template '${template.name}' not found`);
+      }
+
+      const templateCards = await templateObject.cards('', {
+        parent: true,
+        metadata: true,
+      });
+
+      const cardGroups = templateCards.reduce(
+        (result, card) => {
+          // template card root cards have a parent(the template itself) so this shouldn't happen
+          if (!card.parent) {
+            return result;
+          }
+          // if the parent does not exist yet in the result, we create it
+          if (!result[card.parent]) {
+            result[card.parent] = [];
+          }
+          result[card.parent].push(card);
+          return result;
+        },
+        {} as Record<string, Card[]>,
+      );
+
+      for (const [, cards] of Object.entries(cardGroups)) {
+        await this.rebalanceCards(cards);
+      }
+    }
+  }
+}