@cyberismo/data-handler 0.0.12 → 0.0.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cyberismo/data-handler",
   "description": "Command handler for cards and web service",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "author": "sami.merila@cyberismo.com",
   "license": "AGPL-3.0",
   "homepage": "https://github.com/CyberismoCom/cyberismo",
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "@asciidoctor/core": "^3.0.4",
+    "@types/mime-types": "^3.0.1",
     "@viz-js/viz": "^3.17.0",
     "async-mutex": "^0.5.0",
     "csv-parse": "^6.1.0",
@@ -34,18 +35,19 @@
     "dompurify": "^3.2.6",
     "email-validator": "^2.0.4",
     "handlebars": "^4.7.8",
-    "jsdom": "^26.1.0",
+    "jsdom": "^27.0.0",
     "json-schema": "^0.4.0",
     "jsonschema": "^1.5.0",
-    "pino": "^9.9.4",
+    "mime-types": "^3.0.1",
+    "pino": "^9.9.5",
     "simple-git": "^3.28.0",
     "string-pixel-width": "^1.11.0",
     "tslib": "^2.6.2",
     "vega": "^6.1.2",
-    "vega-lite": "^6.2.0",
-    "write-json-file": "^6.0.0",
-    "@cyberismo/assets": "0.0.12",
-    "@cyberismo/node-clingo": "1.2.0"
+    "vega-lite": "^6.3.1",
+    "write-json-file": "^7.0.0",
+    "@cyberismo/assets": "0.0.13",
+    "@cyberismo/node-clingo": "1.3.0"
   },
   "type": "module",
   "files": [

package/src/command-handler.ts

@@ -31,6 +31,16 @@ import type {
   DataType,
   ResourceContent,
 } from './interfaces/resource-interfaces.js';
+import type {
+  AddCommandOptions,
+  AllCommandOptions,
+  CalcCommandOptions,
+  ExportCommandOptions,
+  ReportCommandOptions,
+  ShowCommandOptions,
+  StartCommandOptions,
+  UpdateCommandOptions,
+} from './interfaces/command-options.js';
 
 import type { requestStatus } from './interfaces/request-status-interfaces.js';
 
@@ -48,49 +58,30 @@ import { type Level } from 'pino';
 import { type Context } from './interfaces/project-interfaces.js';
 import { type QueryName } from './types/queries.js';
 
-// Generic options interface
-export interface CardsOptions {
-  context?: Context;
-  date?: string;
-  details?: boolean;
-  forceStart?: boolean;
-  logLevel?: Level;
-  mappingFile?: string;
-  name?: string;
-  projectPath?: string;
-  recursive?: boolean;
-  repeat?: number;
-  revremark?: string;
-  showAll?: boolean;
-  showUse?: boolean;
-  skipModuleImport?: boolean;
-  title?: string;
-  version?: string;
-  watchResourceChanges?: boolean;
-}
-
 // Commands that this class supports.
-// todo: Could be inside the `CommandHandler` ?
-export enum Cmd {
-  add = 'add',
-  calc = 'calc',
-  create = 'create',
-  edit = 'edit',
-  export = 'export',
-  fetch = 'fetch',
-  import = 'import',
-  move = 'move',
-  rank = 'rank',
-  remove = 'remove',
-  rename = 'rename',
-  report = 'report',
-  show = 'show',
-  start = 'start',
-  transition = 'transition',
-  update = 'update',
-  updateModules = 'update-modules',
-  validate = 'validate',
-}
+export const Cmd = {
+  add: 'add',
+  calc: 'calc',
+  create: 'create',
+  edit: 'edit',
+  export: 'export',
+  fetch: 'fetch',
+  import: 'import',
+  move: 'move',
+  rank: 'rank',
+  remove: 'remove',
+  rename: 'rename',
+  report: 'report',
+  show: 'show',
+  start: 'start',
+  transition: 'transition',
+  update: 'update',
+  updateModules: 'update-modules',
+  validate: 'validate',
+};
+
+export type CmdKey = keyof typeof Cmd;
+export type CmdValue = (typeof Cmd)[CmdKey];
 
 // To what format the content can be exported to.
 export enum ExportFormats {
@@ -128,9 +119,9 @@ export class Commands {
    * @returns request status; 200 if success; 400 in handled error; 500 in unknown error
    */
   public async command(
-    command: Cmd,
+    command: CmdValue,
     args: string[],
-    options: CardsOptions,
+    options: AllCommandOptions,
     credentials?: Credentials,
   ): Promise<requestStatus> {
     // Set project path and validate it.
@@ -163,7 +154,7 @@ export class Commands {
   }
 
   // Handles initializing the project so that it can be used in the class.
-  private async doSetProject(options: CardsOptions) {
+  private async doSetProject(options: AllCommandOptions) {
     const path = options.projectPath || '';
     this.projectPath = resolveTilde(await this.setProjectPath(path));
     if (!Validate.validateFolder(this.projectPath)) {
@@ -182,7 +173,8 @@ export class Commands {
 
     this.commands = await CommandManager.getInstance(this.projectPath, {
       logLevel: options.logLevel,
-      watchResourceChanges: options.watchResourceChanges,
+      watchResourceChanges: (options as StartCommandOptions)
+        .watchResourceChanges,
     });
     if (!this.commands) {
       throw new Error('Cannot get instance of CommandManager');
@@ -192,16 +184,21 @@ export class Commands {
 
   // Handles actual command. Sets returns values correctly.
   private async doHandleCommand(
-    command: Cmd,
+    command: CmdValue,
     args: string[],
-    options: CardsOptions,
+    options: AllCommandOptions,
     credentials?: Credentials,
   ) {
     try {
       if (command === Cmd.add) {
         const [type, target, cardType, cardKey] = args;
         if (type === 'card') {
-          return await this.addCard(target, cardType, cardKey, options.repeat);
+          return await this.addCard(
+            target,
+            cardType,
+            cardKey,
+            (options as AddCommandOptions).repeat,
+          );
         }
         if (type === 'hub') {
           return await this.addHub(target);
@@ -214,7 +211,10 @@ export class Commands {
             return { statusCode: 400, message: 'File path is missing' };
           }
           await this.generateLogicProgram();
-          return this.runLogicProgram(cardKey, options.context || 'localApp');
+          return this.runLogicProgram(
+            cardKey,
+            (options as CalcCommandOptions).context || 'localApp',
+          );
         }
         if (command === 'generate') {
           const [destination, query] = rest;
@@ -356,11 +356,11 @@ export class Commands {
         const [parameters, outputPath] = args;
         return this.runReport(
           parameters,
-          options.context || 'localApp',
+          (options as ReportCommandOptions).context || 'localApp',
           outputPath,
         );
       } else if (command === Cmd.start) {
-        return this.startApp(options.forceStart);
+        return this.startApp((options as StartCommandOptions).forceStart);
       } else if (command === Cmd.transition) {
         const [cardKey, state] = args;
         await this.commands?.transitionCmd.cardTransition(cardKey, {
@@ -378,13 +378,13 @@ export class Commands {
         // Handle mapping file for workflow changes
         let mappingTable: { stateMapping: Record<string, string> } | undefined;
         if (
-          options.mappingFile &&
+          (options as UpdateCommandOptions).mappingFile &&
           operation === 'change' &&
           key === 'workflow'
         ) {
           try {
             const mappingData = await readJsonFile(
-              resolveTilde(options.mappingFile),
+              resolveTilde((options as UpdateCommandOptions).mappingFile!),
             );
             if (
               mappingData &&
@@ -537,7 +537,7 @@ export class Commands {
     destination: string = 'output',
     format: ExportFormats,
     parentCardKey?: string,
-    pdfOptions?: CardsOptions,
+    pdfOptions?: ExportCommandOptions,
   ): Promise<requestStatus> {
     if (!this.commands) {
       return { statusCode: 500 };
@@ -701,7 +701,7 @@ export class Commands {
   private async show(
     type: ResourceTypes,
     typeDetail: string,
-    options: CardsOptions,
+    options: ShowCommandOptions,
   ): Promise<requestStatus> {
     const detail = typeDetail || '';
     let promise: Promise<
@@ -798,8 +798,15 @@ export class Commands {
     // since current working directory changes, we need to resolve the project path
     const projectPath = resolve(this.projectPath);
 
+    if (!this.commands) {
+      return { statusCode: 500, message: 'Commands not initialized' };
+    }
+
     if (!forceStart) {
-      const validationErrors = await this.validateCmd.validate(projectPath);
+      const validationErrors = await this.validateCmd.validate(
+        projectPath,
+        () => this.commands!.project,
+      );
       if (validationErrors) {
         return { statusCode: 400, message: validationErrors };
       }
@@ -821,7 +828,13 @@ export class Commands {
 
   // Validates that a given path conforms to schema. Validates both file/folder structure and file content.
   private async validate(): Promise<requestStatus> {
-    const result = await this.validateCmd.validate(this.projectPath);
+    if (!this.commands) {
+      return { statusCode: 500, message: 'Commands not initialized' };
+    }
+    const result = await this.validateCmd.validate(
+      this.projectPath,
+      () => this.commands!.project,
+    );
     return {
       statusCode: 200,
       message: result.length ? result : 'Project structure validated',

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/show.ts

@@ -332,6 +332,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 +362,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.
    */

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

@@ -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

@@ -466,9 +466,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/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];

package/src/interfaces/folder-content-interfaces.ts

@@ -0,0 +1,69 @@
+/**
+  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 { Schema } from 'jsonschema';
+
+// All file mappings for lookup (filename -> property name)
+export const ALL_FILE_MAPPINGS = {
+  'index.adoc.hbs': 'contentTemplate',
+  'query.lp.hbs': 'queryTemplate',
+  'parameterSchema.json': 'schema',
+  'model.lp': 'model',
+  'view.lp.hbs': 'viewTemplate',
+} as const;
+
+// Reverse mappings from property names to filenames
+export const REVERSE_FILE_MAPPINGS = {
+  contentTemplate: 'index.adoc.hbs',
+  queryTemplate: 'query.lp.hbs',
+  schema: 'parameterSchema.json',
+  model: 'model.lp',
+  viewTemplate: 'view.lp.hbs',
+} as const;
+
+// Content interface for Graph Model resources
+export interface GraphModelContent {
+  model?: string;
+}
+
+// Content interface for Graph View resources
+export interface GraphViewContent {
+  viewTemplate?: string;
+}
+
+// Content interface for Report resources
+export interface ReportContent {
+  contentTemplate: string;
+  queryTemplate: string;
+  schema?: Schema;
+}
+
+/**
+ * Get filename with property name
+ * @param propertyName Property name.
+ * @returns filename that matches property name
+ */
+export function filename(propertyName: string): string | undefined {
+  return REVERSE_FILE_MAPPINGS[
+    propertyName as keyof typeof REVERSE_FILE_MAPPINGS
+  ];
+}
+
+/**
+ * Get property name for a filename
+ * @param filename Filename.
+ * @returns property name that matches filename
+ */
+export function propertyName(filename: string): string | undefined {
+  return ALL_FILE_MAPPINGS[filename as keyof typeof ALL_FILE_MAPPINGS];
+}