@cyberismo/data-handler 0.0.12 → 0.0.14

package/src/commands/edit.ts

@@ -1,13 +1,14 @@
 /**
-    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/>.
+  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
@@ -16,18 +17,19 @@ import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 
 import { ActionGuard } from '../permissions/action-guard.js';
+import { CalculationResource } from '../resources/calculation-resource.js';
+import { FolderResource } from '../resources/folder-resource.js';
+import { Project } from '../containers/project.js';
+import { propertyName } from '../interfaces/folder-content-interfaces.js';
+import { resourceNameToString } from '../utils/resource-utils.js';
+import { UserPreferences } from '../utils/user-preferences.js';
+
+import type { ContentPropertyName } from '../interfaces/folder-content-interfaces.js';
 import type {
   MetadataContent,
   ResourceFolderType,
 } from '../interfaces/project-interfaces.js';
-import { Project } from '../containers/project.js';
-import { UserPreferences } from '../utils/user-preferences.js';
-import {
-  type ResourceName,
-  resourceNameToString,
-} from '../utils/resource-utils.js';
-import { FolderResource } from '../resources/folder-resource.js';
-import { writeFile } from 'node:fs/promises';
+import type { ResourceName } from '../utils/resource-utils.js';
 
 export class Edit {
   private project: Project;
@@ -61,15 +63,21 @@ export class Edit {
         `Resource '${resourceNameString}' does not exist in the project`,
       );
     }
-    await writeFile(
-      join(
-        this.project.paths.calculationProjectFolder,
-        resourceName.identifier + '.lp',
-      ),
-      changedContent,
+    const calculationResource = new CalculationResource(
+      this.project,
+      resourceName,
+    );
+    const contentUpdateKey = {
+      key: 'content',
+      subKey: 'calculation',
+    };
+    await calculationResource.update(
+      // TODO: Let's fix this while we get rid of updating filenames directly a bit later.
+      contentUpdateKey as unknown as ContentPropertyName,
       {
-        encoding: 'utf-8',
-        flag: 'r+',
+        name: 'change',
+        target: resourceNameString,
+        to: changedContent,
       },
     );
   }
@@ -201,6 +209,23 @@ export class Edit {
         `Resource '${resourceNameString}' is not a folder resource`,
       );
     }
-    return resource.updateFile(fileName, changedContent);
+
+    // TODO: The caller should not pass filename, but content type
+    // Once that is in place, this check can be removed
+    const propName: ContentPropertyName | undefined = propertyName(fileName);
+    if (!propName) {
+      throw new Error(`File '${fileName}' is not allowed`);
+    }
+
+    const contentUpdateKey = {
+      key: 'content',
+      subKey: propName,
+    };
+    // TODO: Let's fix this while we get rid of updating filenames directly a bit later.
+    return resource.update(contentUpdateKey as unknown as ContentPropertyName, {
+      name: 'change',
+      target: '',
+      to: changedContent,
+    });
   }
 }

package/src/commands/fetch.ts

@@ -18,7 +18,8 @@ import type { Project } from '../containers/project.js';
 import { writeJsonFile } from '../utils/json.js';
 import { validateJson } from '../utils/validate.js';
 import { type ModuleSetting } from '../interfaces/project-interfaces.js';
-import { errorFunction, getChildLogger } from '../utils/log-utils.js';
+import { errorFunction } from '../utils/error-utils.js';
+import { getChildLogger } from '../utils/log-utils.js';
 
 const FETCH_TIMEOUT = 30000; // 30s timeout for fetching a hub file.
 const MAX_RESPONSE_SIZE = 1024 * 1024; // 1MB limit for safety

package/src/commands/import.ts

@@ -136,6 +136,7 @@ export class Import {
   ) {
     const beforeImportValidateErrors = await Validate.getInstance().validate(
       this.project.basePath,
+      () => this.project,
     );
     const gitModule = source.startsWith('https') || source.startsWith('git@');
     const modulePrefix = gitModule
@@ -164,6 +165,7 @@ export class Import {
     // Validate the project after module has been imported
     const afterImportValidateErrors = await Validate.getInstance().validate(
       this.project.basePath,
+      () => this.project,
     );
     if (afterImportValidateErrors.length > beforeImportValidateErrors.length) {
       console.error(

package/src/commands/remove.ts

@@ -35,6 +35,7 @@ export class Remove {
   // True, if resource is a project resource
   private projectResource(type: RemovableResourceTypes): boolean {
     return (
+      type === 'calculation' ||
       type === 'cardType' ||
       type === 'fieldType' ||
       type === 'graphModel' ||
@@ -229,12 +230,12 @@ export class Remove {
       if (type === 'attachment')
         return this.removeAttachment(targetName, rest[0]);
       else if (type === 'card') return this.removeCard(targetName);
+      else if (type === 'hub') return this.removeHubLocation(targetName);
+      else if (type === 'label') return this.removeLabel(targetName, rest[0]);
       else if (type === 'link')
         return this.removeLink(targetName, rest[0], rest[1], rest.at(2));
       else if (type === 'module')
         return this.moduleManager.removeModule(targetName);
-      else if (type === 'label') return this.removeLabel(targetName, rest[0]);
-      else if (type === 'hub') return this.removeHubLocation(targetName);
     }
     throw new Error(`Unknown resource type '${type}'`);
   }

package/src/commands/rename.ts

@@ -22,6 +22,7 @@ import { type Project, ResourcesFrom } from '../containers/project.js';
 import { resourceName } from '../utils/resource-utils.js';
 import { Template } from '../containers/template.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';
@@ -192,6 +193,17 @@ export class Rename {
     return cardType.rename(resourceName(this.updateResourceName(cardTypeName)));
   }
 
+  // Rename calculations.
+  private async updateCalculation(calculationName: string) {
+    const calculation = new CalculationResource(
+      this.project,
+      resourceName(calculationName),
+    );
+    return calculation.rename(
+      resourceName(this.updateResourceName(calculationName)),
+    );
+  }
+
   // Updates field type's metadata.
   private async updateFieldTypeMetadata(fieldTypeName: string) {
     const fieldType = new FieldTypeResource(
@@ -341,6 +353,14 @@ export class Rename {
     }
     console.info('Updated templates');
 
+    const calculations = await this.project.calculations(
+      ResourcesFrom.localOnly,
+    );
+    for (const calculation of calculations) {
+      await this.updateCalculation(calculation.name);
+    }
+    console.info('Updated calculations');
+
     // Rename all local template cards.
     templates = await this.project.templates(ResourcesFrom.localOnly);
     for (const template of templates) {

package/src/commands/show.ts

@@ -16,7 +16,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
-import { readFile, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 
 import { MODULE_LIST_FULL_PATH } from './fetch.js';
 
@@ -47,7 +47,6 @@ import { Project, type ResourcesFrom } from '../containers/project.js';
 import {
   type ResourceName,
   resourceName,
-  resourceNameToPath,
   resourceNameToString,
 } from '../utils/resource-utils.js';
 import { TemplateResource } from '../resources/template-resource.js';
@@ -332,6 +331,8 @@ export class Show {
 
   /**
    * Shows the content of a file in a resource.
+   * TODO: To be removed
+   * @deprecated
    * @param resourceName Name of the resource.
    * @param fileName Name of the file to show.
    * @returns the content of the file.
@@ -360,6 +361,8 @@ export class Show {
 
   /**
    * Shows all file names in a folder resource.
+   * TODO: To be removed
+   * @deprecated
    * @param resourceName Name of the resource.
    * @returns all file names in the resource.
    */
@@ -567,17 +570,6 @@ export class Show {
     name: string,
     showUse: boolean = false,
   ): Promise<ResourceContent | undefined> {
-    // TODO: remove this workaround once calculations are implemented as a resource class
-    if (resourceName(name).type === 'calculations') {
-      const nameObj = resourceName(name);
-      const path = resourceNameToPath(this.project, nameObj, '.lp');
-      return {
-        name,
-        displayName: nameObj.identifier,
-        calculation: await readFile(path, 'utf-8'),
-      };
-    }
-
     const strictNameCheck = true;
     const resource = Project.resourceObject(
       this.project,

package/src/commands/update.ts

@@ -14,6 +14,7 @@ import type {
   AddOperation,
   ChangeOperation,
   Operation,
+  OperationFor,
   RankOperation,
   RemoveOperation,
   UpdateOperations,
@@ -44,7 +45,6 @@ export class Update {
     optionalDetail?: Type, // todo: for 'rank' it might be reasonable to accept also 'number'
     mappingTable?: { stateMapping: Record<string, string> },
   ) {
-    const resource = Project.resourceObject(this.project, resourceName(name));
     const op: Operation<Type> = {
       name: operation,
       target: '' as Type,
@@ -76,7 +76,25 @@ export class Update {
         : undefined;
     }
 
-    await resource?.update(key, op);
+    await this.applyResourceOperation(name, key, op);
+  }
+
+  /**
+   * Update single resource property
+   * This is similar to updateValue, but allows the operation to be fully specified
+   * @param name Name of the resource to operate on.
+   * @param key Property to change in resource JSON
+   * @param operation The full operation object
+   * @template Type Type of the target of the operation
+   * @template T Type of operation ('add', 'remove', 'change', 'rank')
+   */
+  public async applyResourceOperation<Type, T extends UpdateOperations>(
+    name: string,
+    key: string,
+    operation: OperationFor<Type, T>,
+  ) {
+    const resource = Project.resourceObject(this.project, resourceName(name));
+    await resource?.update(key, operation);
     this.project.collectLocalResources();
   }
 }

package/src/commands/validate.ts

@@ -36,7 +36,7 @@ import type {
   ResourceContent,
   Workflow,
 } from '../interfaces/resource-interfaces.js';
-import { errorFunction } from '../utils/log-utils.js';
+import { errorFunction } from '../utils/error-utils.js';
 import { isTemplateCard } from '../utils/card-utils.js';
 import { pathExists } from '../utils/file-utils.js';
 import { Project } from '../containers/project.js';
@@ -521,9 +521,13 @@ export class Validate {
    * Validates that a given directory path (and its children) conform to a JSON schema.
    * @note Validates also content in the directory tree, if .schema file is found.
    * @param projectPath path to validate.
+   * @param projectFn function that returns a Project instance.
    * @returns string containing all validation errors
    */
-  public async validate(projectPath: string): Promise<string> {
+  public async validate(
+    projectPath: string,
+    projectFn: () => Project,
+  ): Promise<string> {
     let validationErrors = '';
     this.validatedFieldTypes.clear();
     this.validatedWorkflows.clear();
@@ -545,7 +549,7 @@ export class Validate {
         return validationErrors;
       } else {
         const errorMsg: string[] = [];
-        const project = new Project(projectPath);
+        const project = projectFn();
 
         // Then, validate that each 'contentSchema' children as well.
         const result = await this.readAndValidateContentFiles(

package/src/containers/card-container.ts

@@ -18,9 +18,9 @@ import type { Dirent } from 'node:fs';
 import { readdir, readFile, writeFile } from 'node:fs/promises';
 
 import { findParentPath } from '../utils/card-utils.js';
+import { getFilesSync } from '../utils/file-utils.js';
 import { readJsonFile } from '../utils/json.js';
 import { writeJsonFile } from '../utils/json.js';
-import { getFilesSync } from '../utils/file-utils.js';
 
 // interfaces
 import {

package/src/containers/project/calculation-engine.ts

@@ -12,8 +12,7 @@
 */
 
 // node
-import { basename, join, resolve } from 'node:path';
-import { readFile, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 
 import { sanitizeSvgBase64 } from '../../utils/sanitize-svg.js';
 import { instance } from '@viz-js/viz';
@@ -26,7 +25,6 @@ import type {
 } from '../../types/queries.js';
 import type { Card, Context } from '../../interfaces/project-interfaces.js';
 import ClingoParser from '../../utils/clingo-parser.js';
-import { pathExists } from '../../utils/file-utils.js';
 import { Mutex } from 'async-mutex';
 import Handlebars from 'handlebars';
 import { type Project, ResourcesFrom } from '../../containers/project.js';
@@ -52,6 +50,7 @@ import type {
   TemplateMetadata,
   Workflow,
 } from '../../interfaces/resource-interfaces.js';
+import { CalculationResource } from '../../resources/calculation-resource.js';
 import {
   removeAllPrograms,
   solve,
@@ -62,6 +61,7 @@ import {
 import { generateReportContent } from '../../utils/report.js';
 import { lpFiles, graphvizReport } from '@cyberismo/assets';
 import {
+  resourceName,
   type ResourceName,
   resourceNameToString,
 } from '../../utils/resource-utils.js';
@@ -123,7 +123,7 @@ export class CalculationEngine {
     query?: QueryName,
   ) {
     let logicProgram = query ? this.queryContent(query) : '';
-    logicProgram += await buildProgram('', programs);
+    logicProgram += buildProgram('', programs);
     await writeFile(destination, logicProgram);
   }
 
@@ -259,26 +259,28 @@ export class CalculationEngine {
     const calculations = await this.project.calculations(ResourcesFrom.all);
 
     for (const calculationFile of calculations) {
-      if (calculationFile.path) {
-        const moduleLogicFile = resolve(
-          join(calculationFile.path, basename(calculationFile.name)),
+      try {
+        const calculationResource = new CalculationResource(
+          this.project,
+          resourceName(calculationFile.name),
         );
-
-        const filePath = moduleLogicFile.endsWith('.lp')
-          ? moduleLogicFile
-          : moduleLogicFile + '.lp';
-
-        if (pathExists(filePath)) {
-          try {
-            const moduleContent = await readFile(filePath, 'utf-8');
-            setProgram(calculationFile.name, moduleContent, [ALL_CATEGORY]);
-          } catch (error) {
-            this.logger.warn(
-              error,
-              `Failed to read calculation ${calculationFile.name}`,
+        if (calculationResource) {
+          const resource = await calculationResource.show();
+          if (!resource?.content.calculation) {
+            this.logger.info(
+              `Calculation resource '${resource.name}' does not have calculation file`,
             );
+            continue;
           }
+          setProgram(calculationFile.name, resource.content.calculation, [
+            ALL_CATEGORY,
+          ]);
         }
+      } catch (error) {
+        this.logger.warn(
+          error,
+          `Failed to read calculation ${calculationFile.name}`,
+        );
       }
     }
   }
@@ -466,9 +468,7 @@ export class CalculationEngine {
       case 'templates':
         return createTemplateFacts(resource as TemplateMetadata);
       default:
-        throw new Error(
-          `Resource ${resourceNameToString(resourceName)} does not have a logic program`,
-        );
+        return '';
     }
   }
 

package/src/containers/project.ts

@@ -53,6 +53,7 @@ import {
 import type { Template } from './template.js';
 import { Validate } from '../commands/validate.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';
@@ -977,7 +978,9 @@ export class Project extends CardContainer {
    * @returns Created resource.
    */
   public static resourceObject(project: Project, name: ResourceName) {
-    if (name.type === 'cardTypes') {
+    if (name.type === 'calculations') {
+      return new CalculationResource(project, name);
+    } else if (name.type === 'cardTypes') {
       return new CardTypeResource(project, name);
     } else if (name.type === 'fieldTypes') {
       return new FieldTypeResource(project, name);

package/src/index.ts

@@ -11,8 +11,9 @@
 */
 
 import {
-  CardsOptions,
   Cmd,
+  CmdKey,
+  CmdValue,
   Commands,
   CommandManager,
   ExportFormats,
@@ -21,6 +22,14 @@ import { Validate } from './commands/validate.js';
 export * from './interfaces/project-interfaces.js';
 import { requestStatus } from './interfaces/request-status-interfaces.js';
 import { UpdateOperations } from './resources/resource-object.js';
+export type {
+  Operation,
+  OperationFor,
+  AddOperation,
+  ChangeOperation,
+  RankOperation,
+  RemoveOperation,
+} from './resources/resource-object.js';
 import { evaluateMacros } from './macros/index.js';
 import {
   isResourceFolderType,
@@ -30,8 +39,9 @@ import {
 import { moduleNameFromCardKey } from './utils/card-utils.js';
 
 export {
-  CardsOptions,
   Cmd,
+  CmdKey,
+  CmdValue,
   CommandManager,
   Commands,
   ExportFormats,
@@ -44,3 +54,27 @@ export {
   Validate,
   evaluateMacros,
 };
+
+// Export command-specific option interfaces
+export type {
+  CommandOptions,
+  AllCommandOptions,
+  AddCommandOptions,
+  CalcCommandOptions,
+  CreateCommandOptions,
+  EditCommandOptions,
+  ExportCommandOptions,
+  FetchCommandOptions,
+  ImportCommandOptions,
+  MoveCommandOptions,
+  RankCommandOptions,
+  RemoveCommandOptions,
+  RenameCommandOptions,
+  ReportCommandOptions,
+  ShowCommandOptions,
+  StartCommandOptions,
+  TransitionCommandOptions,
+  UpdateCommandOptions,
+  UpdateModulesCommandOptions,
+  ValidateCommandOptions,
+} from './interfaces/command-options.js';

package/src/interfaces/command-options.ts

@@ -0,0 +1,144 @@
+/**
+  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 type { Level } from 'pino';
+import type { Context } from './project-interfaces.js';
+import type { CmdKey } from '../command-handler.js';
+
+// Base options shared across multiple commands
+export interface BaseCommandOptions {
+  projectPath?: string;
+  logLevel?: Level;
+}
+
+// Options for commands that need context
+export interface ContextualCommandOptions extends BaseCommandOptions {
+  context?: Context;
+}
+
+// Options for 'add' command
+export interface AddCommandOptions extends BaseCommandOptions {
+  repeat?: number;
+}
+
+// Options for 'calc' command
+export type CalcCommandOptions = ContextualCommandOptions;
+
+// Options for 'create' command
+export interface CreateCommandOptions extends BaseCommandOptions {
+  skipModuleImport?: boolean;
+}
+
+// Options for 'edit' command
+export type EditCommandOptions = BaseCommandOptions;
+
+// Options for the 'export' command
+export interface ExportCommandOptions extends BaseCommandOptions {
+  recursive?: boolean;
+  title?: string;
+  name?: string;
+  version?: string;
+  date?: string;
+  revremark?: string;
+}
+
+// Options for 'fetch' command
+export type FetchCommandOptions = BaseCommandOptions;
+
+// Options for 'import' command
+export type ImportCommandOptions = BaseCommandOptions;
+
+// Options for 'move' command
+export type MoveCommandOptions = BaseCommandOptions;
+
+// Options for 'rank' command
+export type RankCommandOptions = BaseCommandOptions;
+
+// Options for 'remove' command
+export type RemoveCommandOptions = BaseCommandOptions;
+
+// Options for 'rename' command
+export type RenameCommandOptions = BaseCommandOptions;
+
+// Options for 'report' command
+export type ReportCommandOptions = ContextualCommandOptions;
+
+// Options for 'show' command
+export interface ShowCommandOptions extends BaseCommandOptions {
+  details?: boolean;
+  showAll?: boolean;
+  showUse?: boolean;
+}
+
+// Options for 'start' command
+export interface StartCommandOptions extends BaseCommandOptions {
+  forceStart?: boolean;
+  watchResourceChanges?: boolean;
+}
+
+// Options for 'transition' command
+export type TransitionCommandOptions = BaseCommandOptions;
+
+// Options for 'update' command
+export interface UpdateCommandOptions extends BaseCommandOptions {
+  mappingFile?: string;
+}
+
+// Options for 'updateModules' command
+export type UpdateModulesCommandOptions = BaseCommandOptions;
+
+// Options for 'validate' command
+export type ValidateCommandOptions = BaseCommandOptions;
+
+// All possible command options
+export type AllCommandOptions =
+  | AddCommandOptions
+  | CalcCommandOptions
+  | CreateCommandOptions
+  | EditCommandOptions
+  | ExportCommandOptions
+  | FetchCommandOptions
+  | ImportCommandOptions
+  | MoveCommandOptions
+  | RankCommandOptions
+  | RemoveCommandOptions
+  | RenameCommandOptions
+  | ReportCommandOptions
+  | ShowCommandOptions
+  | StartCommandOptions
+  | TransitionCommandOptions
+  | UpdateCommandOptions
+  | UpdateModulesCommandOptions
+  | ValidateCommandOptions;
+
+// Map command keys to their option types
+export type CommandOptions<T extends CmdKey> = {
+  add: AddCommandOptions;
+  calc: CalcCommandOptions;
+  create: CreateCommandOptions;
+  edit: EditCommandOptions;
+  export: ExportCommandOptions;
+  fetch: FetchCommandOptions;
+  import: ImportCommandOptions;
+  move: MoveCommandOptions;
+  rank: RankCommandOptions;
+  remove: RemoveCommandOptions;
+  rename: RenameCommandOptions;
+  report: ReportCommandOptions;
+  show: ShowCommandOptions;
+  start: StartCommandOptions;
+  transition: TransitionCommandOptions;
+  update: UpdateCommandOptions;
+  updateModules: UpdateModulesCommandOptions;
+  validate: ValidateCommandOptions;
+}[T];