@cyberismo/data-handler 0.0.17 → 0.0.19

package/src/command-manager.ts

@@ -16,6 +16,7 @@ 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 { Migrate } from './commands/migrate.js';
 import { Move } from './commands/move.js';
 import { Remove } from './commands/remove.js';
 import { Rename } from './commands/rename.js';
@@ -45,6 +46,7 @@ export class CommandManager {
   public exportCmd: Export;
   public fetchCmd: Fetch;
   public importCmd: Import;
+  public migrateCmd: Migrate;
   public moveCmd: Move;
   public removeCmd: Remove;
   public renameCmd: Rename;
@@ -69,6 +71,7 @@ export class CommandManager {
     this.editCmd = new Edit(this.project);
     this.exportCmd = new Export(this.project, this.showCmd);
     this.importCmd = new Import(this.project, this.createCmd, this.fetchCmd);
+    this.migrateCmd = new Migrate(this.project);
     this.moveCmd = new Move(this.project);
     this.removeCmd = new Remove(this.project, this.fetchCmd);
     this.renameCmd = new Rename(this.project);

package/src/commands/create.ts

@@ -48,6 +48,7 @@ export class Create {
         schemaVersion: SCHEMA_VERSION,
         cardKeyPrefix: '$PROJECT-PREFIX',
         name: '$PROJECT-NAME',
+        description: '',
         modules: [],
         hubs: [],
       },
@@ -372,11 +373,15 @@ export class Create {
    * @param projectPath where to create the project.
    * @param projectPrefix prefix for the project.
    * @param projectName name for the project.
+   * @param projectCategory category for the project (empty string if not provided).
+   * @param projectDescription description for the project (empty string if not provided).
    */
   public static async createProject(
     projectPath: string,
     projectPrefix: string,
     projectName: string,
+    projectCategory: string,
+    projectDescription: string,
   ) {
     projectPath = resolve(projectPath);
 
@@ -439,6 +444,12 @@ export class Create {
           if (entry.content.name.includes('$PROJECT-NAME')) {
             entry.content.name = projectName;
           }
+          if (projectCategory) {
+            entry.content.category = projectCategory;
+          }
+          if (projectDescription) {
+            entry.content.description = projectDescription;
+          }
         }
         await writeJsonFile(
           join(projectPath, entry.path, entry.name),

package/src/commands/migrate.ts

@@ -0,0 +1,88 @@
+/**
+  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 { SCHEMA_VERSION } from '@cyberismo/assets';
+import type { MigrationResult } from '@cyberismo/migrations';
+import type { Project } from '../containers/project.js';
+
+/**
+ * Command that handles schema migration operations.
+ */
+export class Migrate {
+  /**
+   * Constructs instance of Migrate command.
+   * @param project Project instance to use.
+   */
+  constructor(private project: Project) {}
+
+  /**
+   * Run migrations to bring project to target schema version.
+   * @param toVersion Target version (defaults to latest)
+   * @param backupDir Optional directory for backups
+   * @param timeoutMilliSeconds Optional timeout in milliseconds (defaults to 2 minutes)
+   * @returns Migration result
+   */
+  public async migrate(
+    toVersion?: number,
+    backupDir?: string,
+    timeoutMilliSeconds?: number,
+  ): Promise<MigrationResult> {
+    const currentVersion = this.project.configuration.schemaVersion;
+    if (currentVersion === undefined) {
+      throw new Error('Project has no schema version set');
+    }
+
+    const targetVersion = toVersion ?? SCHEMA_VERSION;
+
+    // Prevent downgrading
+    if (targetVersion < currentVersion) {
+      throw new Error(
+        `Cannot downgrade from version ${currentVersion} to ${targetVersion}. Downgrading is not supported.`,
+      );
+    }
+
+    // Cannot migrate beyond current application schema
+    if (targetVersion > SCHEMA_VERSION) {
+      throw new Error(
+        `Cannot migrate to version ${targetVersion}. Current application supports up to version ${SCHEMA_VERSION}.`,
+      );
+    }
+
+    // No migration needed
+    if (currentVersion === targetVersion) {
+      return {
+        success: true,
+        message: `Project is already at version ${currentVersion}. No migration needed.`,
+        stepsExecuted: [],
+      };
+    }
+
+    // Prevent skipping migrations when a specific target version is provided
+    // If no version specified, migrate to the latest
+    if (toVersion !== undefined && toVersion !== SCHEMA_VERSION) {
+      // Only allow next sequential version
+      if (targetVersion !== currentVersion + 1) {
+        throw new Error(
+          `Cannot skip to version ${targetVersion}. Project is at version ${currentVersion}, next version is ${currentVersion + 1}. Migrate one version at a time with 'cyberismo migrate ${currentVersion + 1}', or use 'cyberismo migrate' (without a version) to migrate to the latest version.`,
+        );
+      }
+    }
+
+    return await this.project.runMigrations(
+      currentVersion,
+      targetVersion,
+      backupDir,
+      timeoutMilliSeconds,
+    );
+  }
+}

package/src/containers/project/card-cache.ts

@@ -162,13 +162,30 @@ export class CardCache {
         this.fetchAttachments(currentPath),
       ]);
 
+      let metadata;
+      try {
+        metadata = JSON.parse(cardMetadata);
+      } catch (error) {
+        const metadataPath = join(currentPath, cardMetadataFile);
+        CardCache.logger.error(
+          { error, metadataPath },
+          `Incorrect card metadata file`,
+        );
+        if (error instanceof Error) {
+          throw new Error(
+            `Invalid JSON in file '${metadataPath}': ${error.message}`,
+          );
+        }
+        throw error;
+      }
+
       return {
         key: entry.name,
         path: currentPath,
         children: [],
         attachments: Array.isArray(cardAttachments) ? cardAttachments : [],
         content: typeof cardContent === 'string' ? cardContent : '',
-        metadata: JSON.parse(cardMetadata),
+        metadata: metadata,
         parent: parentCard(currentPath),
         location: location,
       };

package/src/containers/project/project-paths.ts

@@ -80,6 +80,10 @@ export class ProjectPaths {
     return join(this.resourcesFolder, 'graphViews');
   }
 
+  public get internalRootFolder(): string {
+    return join(this.path, '.cards');
+  }
+
   public get linkTypesFolder(): string {
     return join(this.resourcesFolder, 'linkTypes');
   }
@@ -93,7 +97,7 @@ export class ProjectPaths {
   }
 
   public get modulesFolder(): string {
-    return join(this.path, '.cards', 'modules');
+    return join(this.internalRootFolder, 'modules');
   }
 
   public moduleResourcePath(
@@ -105,7 +109,7 @@ export class ProjectPaths {
   }
 
   public get resourcesFolder(): string {
-    return join(this.path, '.cards', 'local');
+    return join(this.internalRootFolder, 'local');
   }
 
   public get reportsFolder(): string {

package/src/containers/project.ts

@@ -55,7 +55,9 @@ import { ResourceHandler } from './project/resource-handler.js';
 import { Validate } from '../commands/validate.js';
 import { ContentWatcher } from './project/project-content-watcher.js';
 import { getChildLogger } from '../utils/log-utils.js';
+import { MigrationExecutor } from '../migrations/migration-executor.js';
 
+import type { MigrationResult } from '@cyberismo/migrations';
 import type { Template } from './template.js';
 
 import { ROOT } from '../utils/constants.js';
@@ -572,12 +574,27 @@ export class Project extends CardContainer {
   public async handleCardDeleted(deletedCard: Card) {
     // Delete children from the cache first
     if (deletedCard.children && deletedCard.children.length > 0) {
+      const parentCachedCard = this.cardCache.getCard(deletedCard.key);
+      const parentLocation = parentCachedCard?.location || 'project';
+
       for (const child of deletedCard.children) {
         try {
           const childCard = this.findCard(child);
+          const childCachedCard = this.cardCache.getCard(child);
+
+          // Safety check: only delete children from the same location (project or template)
+          if (childCachedCard && childCachedCard.location !== parentLocation) {
+            const errorMessage =
+              `Cannot delete child card '${child}' from different location '${childCachedCard.location}' ` +
+              `than parent card '${deletedCard.key}' from '${parentLocation}'`;
+            this.logger.error(errorMessage);
+            throw new Error(errorMessage);
+          }
+
           await this.handleCardDeleted(childCard);
-        } catch {
+        } catch (error) {
           this.logger.warn(
+            { error },
             `Accessing child '${child}' of '${deletedCard.key}' when deleting cards caused an exception`,
           );
           continue;
@@ -753,6 +770,7 @@ export class Project extends CardContainer {
       );
       return {
         name: moduleConfig.name,
+        description: moduleConfig.description || '',
         modules: moduleConfig.modules,
         hubs: moduleConfig.hubs,
         path: modulePath,
@@ -970,6 +988,51 @@ export class Project extends CardContainer {
     return this.resourceHandler;
   }
 
+  /**
+   * Run migrations to bring project schema to target version.
+   * @param fromVersion Current schema version
+   * @param toVersion Target schema version
+   * @param backupDir Optional directory for backups. If undefined, no backup is created.
+   * @param timeoutMilliSeconds Optional timeout in milliseconds. If undefined, uses default (2 minutes).
+   * @returns Migration result
+   */
+  public async runMigrations(
+    fromVersion: number,
+    toVersion: number,
+    backupDir?: string,
+    timeoutMilliSeconds?: number,
+  ): Promise<MigrationResult> {
+    this.logger.info({ fromVersion, toVersion }, 'Starting schema migration');
+
+    const executor = new MigrationExecutor(
+      this,
+      backupDir,
+      timeoutMilliSeconds,
+    );
+    const result = await executor.migrate(
+      fromVersion,
+      toVersion,
+      async (version: number) => {
+        this.settings.schemaVersion = version;
+        await this.settings.save();
+      },
+    );
+
+    if (result.success) {
+      this.logger.info(
+        { fromVersion, toVersion },
+        'Migration completed successfully',
+      );
+    } else {
+      this.logger.error(
+        { error: result.error, message: result.message },
+        'Migration failed',
+      );
+    }
+
+    return result;
+  }
+
   /**
    * Shows details of a project.
    * @returns details of a project.
@@ -979,6 +1042,8 @@ export class Project extends CardContainer {
       name: this.settings.name,
       path: this.basePath,
       prefix: this.projectPrefix,
+      category: this.configuration.category,
+      description: this.configuration.description,
       hubs: this.configuration.hubs,
       modules: this.resources.moduleNames(),
       numberOfCards: (await this.listCards(CardLocation.projectOnly))[0].cards

package/src/containers/template.ts

@@ -152,6 +152,11 @@ export class Template extends CardContainer {
 
       card.key = templateIDMap.get(card.key) || card.key;
 
+      // Remap children keys from template keys to new project card keys
+      card.children = card.children.map(
+        (childKey) => templateIDMap.get(childKey) || childKey,
+      );
+
       // Set parent field based on template hierarchy and creation location
       // Store the original template parent before key remapping
       const originalParentKey = card.parent;

package/src/interfaces/command-options.ts

@@ -60,6 +60,12 @@ export interface ImportCommandOptions extends BaseCommandOptions {
   skipMigrationLog?: boolean;
 }
 
+// Options for 'migrate' command
+export interface MigrateCommandOptions extends BaseCommandOptions {
+  backup?: string;
+  timeout?: number;
+}
+
 // Options for 'move' command
 export type MoveCommandOptions = BaseCommandOptions;
 
@@ -111,6 +117,7 @@ export type AllCommandOptions =
   | ExportCommandOptions
   | FetchCommandOptions
   | ImportCommandOptions
+  | MigrateCommandOptions
   | MoveCommandOptions
   | RankCommandOptions
   | RemoveCommandOptions
@@ -132,6 +139,7 @@ export type CommandOptions<T extends CmdKey> = {
   export: ExportCommandOptions;
   fetch: FetchCommandOptions;
   import: ImportCommandOptions;
+  migrate: MigrateCommandOptions;
   move: MoveCommandOptions;
   rank: RankCommandOptions;
   remove: RemoveCommandOptions;

package/src/interfaces/project-interfaces.ts

@@ -171,6 +171,8 @@ export interface ProjectMetadata {
   name: string;
   path: string;
   prefix: string;
+  category?: string;
+  description?: string;
   modules: string[];
   hubs: HubSetting[];
   numberOfCards: number;
@@ -181,6 +183,8 @@ export interface ProjectSettings {
   schemaVersion?: number;
   cardKeyPrefix: string;
   name: string;
+  category?: string;
+  description: string;
   modules: ModuleSetting[];
   hubs: HubSetting[];
 }

package/src/migrations/index.ts

@@ -0,0 +1,20 @@
+/**
+  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/>.
+*/
+
+export { MigrationExecutor } from './migration-executor.js';
+export type {
+  Migration,
+  MigrationContext,
+  MigrationResult,
+  MigrationStepResult,
+} from '@cyberismo/migrations';