@cyberismo/data-handler 0.0.15 → 0.0.16

package/src/command-handler.ts

@@ -15,6 +15,7 @@ import { join, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 
+import { SCHEMA_VERSION } from '@cyberismo/assets';
 import type {
   Card,
   CardAttachment,
@@ -28,7 +29,7 @@ import type {
 } from './interfaces/project-interfaces.js';
 import type {
   DataType,
-  ResourceContent,
+  AnyResourceContent,
 } from './interfaces/resource-interfaces.js';
 import type {
   AddCommandOptions,
@@ -43,7 +44,8 @@ import type {
 
 import type { requestStatus } from './interfaces/request-status-interfaces.js';
 
-import { Create, Validate } from './commands/index.js';
+import { Create } from './commands/create.js';
+import { Validate } from './commands/validate.js';
 import { CommandManager } from './command-manager.js';
 import type { UpdateOperations } from './resources/resource-object.js';
 import { Project } from './containers/project.js';
@@ -178,6 +180,12 @@ export class Commands {
     if (!this.commands) {
       throw new Error('Cannot get instance of CommandManager');
     }
+
+    // Check schema version and log warning if there's a mismatch
+    const versionCheck = this.commands.checkSchemaVersion();
+    if (!versionCheck.isCompatible) {
+      console.error(versionCheck.message);
+    }
   }
 
   // Handles actual command. Sets returns values correctly.
@@ -439,6 +447,13 @@ export class Commands {
     return { statusCode: 200 };
   }
 
+  /**
+   * Returns the current schema version.
+   */
+  public getSchemaVersion(): number {
+    return SCHEMA_VERSION;
+  }
+
   /**
    * Returns project path, if running operation within project folder.
    * @param path Initial path from where the project path search is started.
@@ -709,7 +724,7 @@ export class Commands {
       | ModuleContent
       | ModuleSettingFromHub[]
       | ProjectMetadata
-      | ResourceContent
+      | AnyResourceContent
       | string[]
       | undefined
     >;
@@ -769,7 +784,10 @@ export class Commands {
           payload: this.commands!.showCmd.showHubs(),
         };
       case 'modules':
-        promise = this.commands!.showCmd.showModules();
+        return {
+          statusCode: 200,
+          payload: this.commands!.showCmd.showModules(),
+        };
         break;
       case 'project':
         promise = this.commands!.showCmd.showProject();
@@ -787,7 +805,8 @@ export class Commands {
   // Starts the Cyberismo app by running npm start in the app project folder
   private async startApp(forceStart: boolean = false): Promise<requestStatus> {
     // __dirname when running cards ends with /tools/data-handler/dist - use that to navigate to app path
-    const baseDir = import.meta.dirname;
+    const baseDir =
+      import.meta.dirname ?? new URL('.', import.meta.url).pathname;
     const appPath = resolve(baseDir, '../../app');
 
     // since current working directory changes, we need to resolve the project path

package/src/command-manager.ts

@@ -10,21 +10,19 @@
     License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import {
-  Calculate,
-  Create,
-  Edit,
-  Export,
-  Fetch,
-  Import,
-  Move,
-  Remove,
-  Rename,
-  Show,
-  Transition,
-  Update,
-  Validate,
-} from './commands/index.js';
+import { Calculate } from './commands/calculate.js';
+import { Create } from './commands/create.js';
+import { Edit } from './commands/edit.js';
+import { Export } from './commands/export.js';
+import { Fetch } from './commands/fetch.js';
+import { Import } from './commands/import.js';
+import { Move } from './commands/move.js';
+import { Remove } from './commands/remove.js';
+import { Rename } from './commands/rename.js';
+import { Show } from './commands/show.js';
+import { Transition } from './commands/transition.js';
+import { Update } from './commands/update.js';
+import { Validate } from './commands/validate.js';
 import { Project } from './containers/project.js';
 import { ProjectPaths } from './containers/project/project-paths.js';
 import pino, { type Level, type TransportTargetOptions } from 'pino';
@@ -32,6 +30,7 @@ import { setLogger } from './utils/log-utils.js';
 
 export interface CommandManagerOptions {
   watchResourceChanges?: boolean;
+  autoSaveConfiguration?: boolean;
   logLevel?: Level;
 }
 
@@ -57,7 +56,10 @@ export class CommandManager {
   private pathHandler: ProjectPaths;
 
   constructor(path: string, options?: CommandManagerOptions) {
-    this.project = new Project(path, options?.watchResourceChanges);
+    this.project = new Project(path, {
+      autoSave: options?.autoSaveConfiguration,
+      watchResourceChanges: options?.watchResourceChanges,
+    });
     this.validateCmd = Validate.getInstance();
 
     this.calculateCmd = new Calculate(this.project);
@@ -75,12 +77,22 @@ export class CommandManager {
     this.pathHandler = new ProjectPaths(path);
   }
 
+  /**
+   * Checks the schema version compatibility.
+   * @returns
+   *    isCompatible - true if compatible; false otherwise
+   *    message - optional message related to compatibility.
+   */
+  public checkSchemaVersion(): { isCompatible: boolean; message?: string } {
+    return this.project.configuration.checkSchemaVersion();
+  }
+
   /**
    * Some commands needs initialization that cannot be performed inside constructor.
    * Add such calls here.
    */
   public async initialize() {
-    this.project.collectModuleResources();
+    this.project.resources.changedModules();
     await this.project.populateCaches();
   }
 

package/src/commands/create.ts

@@ -15,31 +15,18 @@
 import { join, resolve } from 'node:path';
 import { mkdir, writeFile } from 'node:fs/promises';
 
+import { SCHEMA_VERSION } from '@cyberismo/assets';
 import { errorFunction } from '../utils/error-utils.js';
 import { Project } from '../containers/project.js';
-import { Validate } from './index.js';
+import { Validate } from './validate.js';
 
 import { EMPTY_RANK, sortItems } from '../utils/lexorank.js';
 import { isModulePath } from '../utils/card-utils.js';
-import type {
-  DataType,
-  Link,
-  LinkType,
-} from '../interfaces/resource-interfaces.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 { writeJsonFile } from '../utils/json.js';
 
-import { CalculationResource } from '../resources/calculation-resource.js';
-import { CardTypeResource } from '../resources/card-type-resource.js';
-import { FieldTypeResource } from '../resources/field-type-resource.js';
-import { GraphModelResource } from '../resources/graph-model-resource.js';
-import { GraphViewResource } from '../resources/graph-view-resource.js';
-import { LinkTypeResource } from '../resources/link-type-resource.js';
-import { ReportResource } from '../resources/report-resource.js';
-import { TemplateResource } from '../resources/template-resource.js';
-import { WorkflowResource } from '../resources/workflow-resource.js';
-
 // todo: Is there a easy to way to make JSON schema into a TypeScript interface/type?
 //       Check this out: https://www.npmjs.com/package/json-schema-to-ts
 
@@ -58,6 +45,7 @@ export class Create {
     {
       path: '.cards/local',
       content: {
+        schemaVersion: SCHEMA_VERSION,
         cardKeyPrefix: '$PROJECT-PREFIX',
         name: '$PROJECT-NAME',
         modules: [],
@@ -107,9 +95,9 @@ export class Create {
     if (cardTypeName === undefined) {
       throw new Error(`Input validation error: card type cannot be empty`);
     }
-    const templateResource = new TemplateResource(
-      this.project,
-      resourceName(templateName),
+    const templateResource = this.project.resources.byType(
+      templateName,
+      'templates',
     );
     const templateObject = templateResource.templateObject();
     const specificCard = card ? templateObject.findCard(card) : undefined;
@@ -181,11 +169,9 @@ export class Create {
    * @param calculationName name for the calculation resource
    */
   public async createCalculation(calculationName: string) {
-    const calculation = new CalculationResource(
-      this.project,
-      resourceName(calculationName),
-    );
-    await calculation.create();
+    return this.project.resources
+      .byType(calculationName, 'calculations')
+      .create();
   }
 
   /**
@@ -198,15 +184,15 @@ export class Create {
     templateName: string,
     parentCardKey?: string,
   ): Promise<Card[]> {
-    const templateResource = new TemplateResource(
-      this.project,
-      resourceName(templateName),
+    const templateResource = this.project.resources.byType(
+      templateName,
+      'templates',
     );
 
     Validate.getInstance().validResourceName(
       'templates',
       resourceNameToString(resourceName(templateName)),
-      await this.project.projectPrefixes(),
+      this.project.projectPrefixes(),
     );
 
     await templateResource.validate();
@@ -236,12 +222,9 @@ export class Create {
    * @param workflowName workflow name to use in the card type.
    */
   public async createCardType(cardTypeName: string, workflowName: string) {
-    const cardType = new CardTypeResource(
-      this.project,
-      resourceName(cardTypeName),
-    );
-
-    await cardType.createCardType(workflowName);
+    return this.project.resources
+      .byType(cardTypeName, 'cardTypes')
+      .createCardType(workflowName);
   }
 
   /**
@@ -250,11 +233,9 @@ export class Create {
    * @param dataType data type for the field type
    */
   public async createFieldType(fieldTypeName: string, dataType: DataType) {
-    const fieldType = new FieldTypeResource(
-      this.project,
-      resourceName(fieldTypeName),
-    );
-    await fieldType.createFieldType(dataType);
+    return this.project.resources
+      .byType(fieldTypeName, 'fieldTypes')
+      .createFieldType(dataType);
   }
 
   /**
@@ -262,23 +243,17 @@ export class Create {
    * @param graphModelName name for the graph model.
    */
   public async createGraphModel(graphModelName: string) {
-    const graphModel = new GraphModelResource(
-      this.project,
-      resourceName(graphModelName),
-    );
-    await graphModel.create();
+    return this.project.resources
+      .byType(graphModelName, 'graphModels')
+      .create();
   }
 
   /**
    * Creates a new graph view.
-   * @param graphModelName name for the graph view.
+   * @param graphViewName name for the graph view.
    */
   public async createGraphView(graphViewName: string) {
-    const graphView = new GraphViewResource(
-      this.project,
-      resourceName(graphViewName),
-    );
-    await graphView.create();
+    return this.project.resources.byType(graphViewName, 'graphViews').create();
   }
 
   /**
@@ -307,11 +282,7 @@ export class Create {
    * @param linkTypeName name for the link type.
    */
   public async createLinkType(linkTypeName: string) {
-    const linkType = new LinkTypeResource(
-      this.project,
-      resourceName(linkTypeName),
-    );
-    await linkType.create();
+    return this.project.resources.byType(linkTypeName, 'linkTypes').create();
   }
 
   /**
@@ -335,10 +306,9 @@ export class Create {
     const card = this.project.findCard(cardKey);
     const destinationCard = this.project.findCard(destinationCardKey);
     // make sure the link type exists
-    const linkTypeObject = this.project.resource<LinkType>(linkType);
-    if (!linkTypeObject) {
-      throw new Error(`Link type '${linkType}' does not exist in the project`);
-    }
+    const linkTypeObject = this.project.resources
+      .byType(linkType, 'linkTypes')
+      .show();
 
     // make sure that if linkDescription is not enabled, linkDescription is not provided
     if (
@@ -387,7 +357,7 @@ export class Create {
       );
     }
 
-    const links: Link[] = card.metadata?.links || [];
+    const links = card.metadata?.links || [];
     links.push({
       linkType,
       cardKey: destinationCardKey,
@@ -416,6 +386,12 @@ export class Create {
 
     const projectFolders: string[] = ['.cards/local', 'cardRoot'];
 
+    if (!Validate.validateFolder(projectPath)) {
+      throw new Error(
+        `Input validation error: folder name '${projectPath}' is invalid`,
+      );
+    }
+
     if (
       projectPrefix === undefined ||
       projectPrefix.length < 3 ||
@@ -486,8 +462,7 @@ export class Create {
    * @param name name of the report
    */
   public async createReport(name: string) {
-    const report = new ReportResource(this.project, resourceName(name));
-    await report.createReport();
+    return this.project.resources.byType(name, 'reports').createReport();
   }
 
   /**
@@ -496,14 +471,9 @@ export class Create {
    * @param templateContent JSON content for the template file.
    */
   public async createTemplate(templateName: string, templateContent: string) {
-    const template = new TemplateResource(
-      this.project,
-      resourceName(templateName),
-    );
-
-    await template.create(
-      templateContent ? JSON.parse(templateContent) : undefined,
-    );
+    return this.project.resources
+      .byType(templateName, 'templates')
+      .create(templateContent ? JSON.parse(templateContent) : undefined);
   }
 
   /**
@@ -512,13 +482,8 @@ export class Create {
    * @param workflowContent workflow content JSON
    */
   public async createWorkflow(workflowName: string, workflowContent: string) {
-    const workflow = new WorkflowResource(
-      this.project,
-      resourceName(workflowName),
-    );
-
-    await workflow.create(
-      workflowContent ? JSON.parse(workflowContent) : undefined,
-    );
+    return this.project.resources
+      .byType(workflowName, 'workflows')
+      .create(workflowContent ? JSON.parse(workflowContent) : undefined);
   }
 }

package/src/commands/export.ts

@@ -31,12 +31,20 @@ 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 type { Show } from './index.js';
+import type { Show } from './show.js';
 import { sortItems } from '../utils/lexorank.js';
 
 const attachmentFolder: string = 'a';
 
+/**
+ * Handles all export commands.
+ */
 export class Export {
+  /**
+   * Creates an instance of export.
+   * @param project Project to use
+   * @param showCmd Instance of Export command to use.
+   */
   constructor(
     protected project: Project,
     protected showCmd: Show,
@@ -97,6 +105,56 @@ export class Export {
     return content;
   }
 
+  // Runs Ascii Doctor converter --> to PDF
+  private async runAsciidoctorPdf(content: string): Promise<Buffer> {
+    const staticRootDir = await getStaticDirectoryPath();
+    const proc = spawn(
+      'asciidoctor-pdf',
+      [
+        '-a',
+        'pdf-theme=cyberismo',
+        '-a',
+        `pdf-themesdir=${join(staticRootDir, 'pdf-themes')}`,
+        '-a',
+        `pdf-fontsdir=${join(staticRootDir, 'pdf-themes', 'fonts')};GEM_FONTS_DIR`,
+        '-',
+      ],
+      {
+        timeout: 100000,
+        shell: process.platform === 'win32',
+      },
+    );
+    proc.stdin.end(content);
+    const result = await new Promise<Buffer>((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      proc.stdout.on('data', (chunk) => {
+        chunks.push(chunk);
+      });
+      proc.stderr.on('data', (chunk) => {
+        process.stderr.write(chunk);
+      });
+      proc.on('error', (error) => {
+        if ('code' in error && error.code === 'ENOENT') {
+          reject(
+            new Error(
+              'Asciidoctor-pdf not found. Please install asciidoctor-pdf to use this feature.',
+            ),
+          );
+        }
+        reject(error);
+      });
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve(Buffer.concat(chunks));
+        } else {
+          reject(new Error(`Asciidoctor-pdf failed with code ${code}`));
+        }
+      });
+    });
+    return result;
+  }
+
+  // Adds cards to an ADOC file as additional content.
   private async toAdocFileAsContent(path: string, cards: Card[]) {
     for (const card of cards) {
       let fileContent = '';
@@ -108,9 +166,9 @@ export class Export {
       }
 
       if (card.metadata) {
-        const cardTypeForCard = await this.project.resource<CardType>(
-          card.metadata?.cardType,
-        );
+        const cardTypeForCard = this.project.resources
+          .byType(card.metadata?.cardType, 'cardTypes')
+          .show();
         const metaDataContent = this.metaToAdoc(card, cardTypeForCard);
         fileContent += metaDataContent;
       }
@@ -177,6 +235,7 @@ export class Export {
    * Convert treeQueryResult object into a Card object and add content, metadata & attachments
    * Handles card children recursively
    * @param treeQueryResult tree query result object
+   * @returns Tree query result as a Card.
    */
   protected async treeQueryResultToCard(
     treeQueryResult: QueryResult<'tree'>,
@@ -218,54 +277,6 @@ export class Export {
     return card;
   }
 
-  private async runAsciidoctorPdf(content: string): Promise<Buffer> {
-    const staticRootDir = await getStaticDirectoryPath();
-    const proc = spawn(
-      'asciidoctor-pdf',
-      [
-        '-a',
-        'pdf-theme=cyberismo',
-        '-a',
-        `pdf-themesdir=${join(staticRootDir, 'pdf-themes')}`,
-        '-a',
-        `pdf-fontsdir=${join(staticRootDir, 'pdf-themes', 'fonts')};GEM_FONTS_DIR`,
-        '-',
-      ],
-      {
-        timeout: 100000,
-        shell: process.platform === 'win32',
-      },
-    );
-    proc.stdin.end(content);
-    const result = await new Promise<Buffer>((resolve, reject) => {
-      const chunks: Buffer[] = [];
-      proc.stdout.on('data', (chunk) => {
-        chunks.push(chunk);
-      });
-      proc.stderr.on('data', (chunk) => {
-        process.stderr.write(chunk);
-      });
-      proc.on('error', (error) => {
-        if ('code' in error && error.code === 'ENOENT') {
-          reject(
-            new Error(
-              'Asciidoctor-pdf not found. Please install asciidoctor-pdf to use this feature.',
-            ),
-          );
-        }
-        reject(error);
-      });
-      proc.on('close', (code) => {
-        if (code === 0) {
-          resolve(Buffer.concat(chunks));
-        } else {
-          reject(new Error(`Asciidoctor-pdf failed with code ${code}`));
-        }
-      });
-    });
-    return result;
-  }
-
   /**
    * Exports the card(s) to pdf.
    * @param destination Path to where the resulting file(s) will be created.

package/src/commands/import.ts

@@ -11,20 +11,28 @@
   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 { readCsvFile } from '../utils/csv.js';
+import { Validate } from './validate.js';
+
+import type { Create } from './create.js';
 import type {
   Credentials,
   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';
 
+/**
+ * Handles all import commands.
+ */
 export class Import {
   private moduleManager: ModuleManager;
+
+  /**
+   * Creates an instance of Import.
+   * @param project Project to use.
+   * @param createCmd Instance of Create to use.
+   */
   constructor(
     private project: Project,
     private createCmd: Create,
@@ -53,9 +61,9 @@ export class Import {
 
     for (const row of csv) {
       const { title, template, description, labels, ...customFields } = row;
-      const templateResource = new TemplateResource(
-        this.project,
-        resourceName(template),
+      const templateResource = this.project.resources.byType(
+        template,
+        'templates',
       );
       const templateObject = templateResource.templateObject();
       if (!templateObject) {
@@ -78,13 +86,12 @@ export class Import {
       }
       const cardKey = cards[0].key;
       const card = this.project.findCard(cardKey);
-      const cardType = this.project.resource<CardType>(
-        card.metadata?.cardType || '',
-      );
-
-      if (!cardType) {
+      if (!card.metadata?.cardType) {
         throw new Error(`Card type not found for card ${cardKey}`);
       }
+      const cardType = this.project.resources
+        .byType(card.metadata?.cardType, 'cardTypes')
+        .show();
 
       if (description) {
         await this.project.updateCardContent(cardKey, description);
@@ -155,7 +162,10 @@ export class Import {
     };
 
     // Fetch module dependencies.
-    await this.moduleManager.updateModule(moduleSettings, options?.credentials);
+    await this.moduleManager.updateDependencies(
+      moduleSettings,
+      options?.credentials,
+    );
 
     // Add module as a dependency.
     await this.project.importModule(moduleSettings);

package/src/commands/move.ts

@@ -197,7 +197,6 @@ export class Move {
     sourceCard.parent = movingToRoot ? ROOT : destination;
     if (sourceCard.metadata) {
       sourceCard.metadata.rank = rank;
-      sourceCard.metadata.parent = movingToRoot ? ROOT : destination;
     }
 
     // Handle cache update and persistence