@cyberismo/data-handler 0.0.16 → 0.0.17

package/src/containers/project.ts

@@ -21,6 +21,7 @@ import {
   unlink,
   writeFile,
 } from 'node:fs/promises';
+import { readdirSync } from 'node:fs';
 
 // base class
 import { CardContainer } from './card-container.js';
@@ -59,6 +60,11 @@ import type { Template } from './template.js';
 
 import { ROOT } from '../utils/constants.js';
 
+import {
+  ConfigurationLogger,
+  ConfigurationOperation,
+} from '../utils/configuration-logger.js';
+
 // Re-export this, so that classes that use Project do not need to have separate import.
 export { ResourcesFrom };
 
@@ -83,6 +89,7 @@ export class Project extends CardContainer {
   private resourceWatcher: ContentWatcher | undefined;
   private settings: ProjectConfiguration;
   private validator: Validate;
+  private cachedAllModulePrefixes: string[] = [];
 
   constructor(
     path: string,
@@ -95,7 +102,7 @@ export class Project extends CardContainer {
       join(path, '.cards', 'local', Project.projectConfigFileName),
       options.autoSave ?? true,
     );
-    super(path, settings.cardKeyPrefix, '');
+    super(path, settings.cardKeyPrefix);
     this.settings = settings;
 
     this.logger.info({ path }, 'Initializing project');
@@ -103,16 +110,16 @@ export class Project extends CardContainer {
     this.calculationEngine = new CalculationEngine(this);
     this.projectPaths = new ProjectPaths(path);
     this.resourceHandler = new ResourceHandler(this);
-
-    this.containerName = this.settings.name;
     // todo: implement project validation
     this.validator = Validate.getInstance();
 
     this.logger.info(
-      { name: this.containerName },
+      { name: this.settings.name },
       'Project initialization complete',
     );
 
+    this.refreshAllModulePrefixes();
+
     const ignoreRenameFileChanges = true;
 
     // Watch changes in .cards if there are multiple instances of Project being
@@ -217,12 +224,34 @@ export class Project extends CardContainer {
     }
   }
 
+  // Refreshes the cached list of all module prefixes.
+  // This includes both direct and transient module dependencies.
+  private refreshAllModulePrefixes(): void {
+    const prefixes: string[] = [this.projectPrefix];
+
+    try {
+      const modules = readdirSync(this.paths.modulesFolder, {
+        withFileTypes: true,
+      })
+        .filter((item) => item.isDirectory())
+        .map((item) => item.name);
+
+      prefixes.push(...modules);
+    } catch {
+      // If modules folder doesn't exist, fall back to configuration modules only
+      const moduleNames = this.configuration.modules.map((item) => item.name);
+      prefixes.push(...moduleNames);
+    }
+
+    this.cachedAllModulePrefixes = prefixes;
+  }
+
   // Validates that card's data is valid.
   private async validateCard(card: Card): Promise<string> {
     const invalidCustomData = await this.validator.validateCustomFields(
       this,
       card,
-      this.projectPrefixes(),
+      this.allModulePrefixes(),
     );
     const invalidWorkFlow = await this.validator.validateWorkflowState(
       this,
@@ -256,7 +285,7 @@ export class Project extends CardContainer {
   protected async populateTemplateCards(): Promise<void> {
     try {
       const templateResources = this.resources.templates();
-      const prefixes = this.projectPrefixes();
+      const prefixes = this.allModulePrefixes();
       const loadPromises = templateResources.map(async (template) => {
         try {
           this.validator.validResourceName(
@@ -609,12 +638,30 @@ export class Project extends CardContainer {
   /**
    * Adds a module from project.
    * @param module Module to add
+   * @param skipMigrationLog If true, skip logging to migration log. Used during project creation.
    */
-  public async importModule(module: ModuleSetting) {
+  public async importModule(module: ModuleSetting, skipMigrationLog = false) {
     // Add module as a dependency.
     await this.configuration.addModule(module);
     this.resources.changedModules();
+    this.refreshAllModulePrefixes();
     await this.populateTemplateCards();
+
+    // Log configuration change
+    if (!skipMigrationLog) {
+      await ConfigurationLogger.log(
+        this.basePath,
+        ConfigurationOperation.MODULE_ADD,
+        module.name,
+        {
+          parameters: {
+            location: module.location,
+            branch: module.branch,
+            private: module.private,
+          },
+        },
+      );
+    }
     this.logger.info(`Imported module '${module.name}'`);
   }
 
@@ -831,9 +878,18 @@ export class Project extends CardContainer {
   }
 
   /**
-   * Returns all prefixes used in the project (project's own plus all from imported modules).
+   * Returns all prefixes used in the project.
+   * This includes both direct dependencies and transient dependencies.
    * @returns all prefixes used in the project.
    */
+  public allModulePrefixes(): string[] {
+    return this.cachedAllModulePrefixes;
+  }
+
+  /**
+   * Returns prefixes for direct module dependencies only (from cardsConfig.json).
+   * @returns prefixes for direct module dependencies.
+   */
   public projectPrefixes(): string[] {
     const prefixes: string[] = [this.projectPrefix];
     const moduleNames = this.configuration.modules.map((item) => item.name);
@@ -892,6 +948,17 @@ export class Project extends CardContainer {
     // Finally, remove module from project configuration
     await this.configuration.removeModule(moduleName);
 
+    // Refresh cached module prefixes after removal
+    this.refreshAllModulePrefixes();
+
+    // Log configuration change
+    await ConfigurationLogger.log(
+      this.basePath,
+      ConfigurationOperation.MODULE_REMOVE,
+      moduleName,
+      {},
+    );
+
     this.logger.info(`Removed module '${moduleName}'`);
   }
 
@@ -909,7 +976,7 @@ export class Project extends CardContainer {
    */
   public async show(): Promise<ProjectMetadata> {
     return {
-      name: this.containerName,
+      name: this.settings.name,
       path: this.basePath,
       prefix: this.projectPrefix,
       hubs: this.configuration.hubs,

package/src/containers/template.ts

@@ -65,7 +65,7 @@ export class Template extends CardContainer {
   constructor(project: Project, template: Resource) {
     // Templates might come from modules. Remove module name from template name.
     const templateName = stripExtension(basename(template.name));
-    super(template.path, project.projectPrefix, templateName);
+    super(template.path, project.projectPrefix);
     this.templateName = templateName;
     this.fullTemplateName = template.name;
 
@@ -399,7 +399,7 @@ export class Template extends CardContainer {
     try {
       // todo: to use cache instead of file access
       if (!pathExists(this.templateFolder())) {
-        throw new Error(`Template '${this.containerName}' does not exist`);
+        throw new Error(`Template '${this.templateName}' does not exist`);
       }
       const cardType = this.project.resources
         .byType(cardTypeName, 'cardTypes')
@@ -407,7 +407,7 @@ export class Template extends CardContainer {
 
       if (parentCard && !this.hasTemplateCard(parentCard.key)) {
         throw new Error(
-          `Card '${parentCard.key}' does not exist in template '${this.containerName}'`,
+          `Card '${parentCard.key}' does not exist in template '${this.templateName}'`,
         );
       }
 
@@ -496,7 +496,7 @@ export class Template extends CardContainer {
     const cards = this.cards();
     if (cards.length === 0) {
       throw new Error(
-        `No cards in template '${this.containerName}'. Please add template cards with 'add' command first.`,
+        `No cards in template '${this.templateName}'. Please add template cards with 'add' command first.`,
       );
     }
     return this.doCreateCards(cards, parentCard);

package/src/interfaces/command-options.ts

@@ -56,7 +56,9 @@ export interface ExportCommandOptions extends BaseCommandOptions {
 export type FetchCommandOptions = BaseCommandOptions;
 
 // Options for 'import' command
-export type ImportCommandOptions = BaseCommandOptions;
+export interface ImportCommandOptions extends BaseCommandOptions {
+  skipMigrationLog?: boolean;
+}
 
 // Options for 'move' command
 export type MoveCommandOptions = BaseCommandOptions;

package/src/interfaces/project-interfaces.ts

@@ -47,13 +47,15 @@ export interface CardListContainer {
 }
 // Remember to add all these keys to utils/constants.ts
 export interface PredefinedCardMetadata {
-  title: string;
   cardType: string;
-  workflowState: string;
-  rank: string;
+  labels?: string[];
   lastTransitioned?: string;
   lastUpdated?: string;
+  links: Link[];
+  rank: string;
   templateCardKey?: string;
+  title: string;
+  workflowState: string;
 }
 
 // todo: do we need in the future separation between module-template-cards and local template-cards
@@ -65,8 +67,6 @@ export enum CardLocation {
 
 // Card's index.json file content.
 export interface CardMetadata extends PredefinedCardMetadata {
-  labels?: string[];
-  links: Link[];
   [key: string]: MetadataContent;
 }
 

package/src/project-settings.ts

@@ -265,4 +265,17 @@ export class ProjectConfiguration implements ProjectSettings {
       `Prefix '${newPrefix}' is not valid prefix. Prefix should be in lowercase and contain letters from a to z (max length 10).`,
     );
   }
+
+  /**
+   * Changes project name.
+   * @param newName New project name
+   */
+  public async setProjectName(newName: string) {
+    const isValid = Validate.isValidProjectName(newName);
+    if (isValid) {
+      this.name = newName;
+      return this.save();
+    }
+    throw new Error(`Project name '${newName}' is not valid.`);
+  }
 }

package/src/resources/resource-object.ts

@@ -44,6 +44,11 @@ import type {
 } from '../interfaces/resource-interfaces.js';
 import type { Validate } from '../commands/validate.js';
 
+import {
+  ConfigurationLogger,
+  ConfigurationOperation,
+} from '../utils/configuration-logger.js';
+
 // Possible operations to perform when doing "update"
 export type UpdateOperations = 'add' | 'change' | 'rank' | 'remove';
 
@@ -308,6 +313,9 @@ export abstract class ResourceObject<
 
     const resourceString = resourceNameToString(this.resourceName);
     this.project.resources.add(resourceString, this);
+
+    // Log resource creation to migration log
+    await this.logResourceOperation('create');
   }
 
   /**
@@ -408,6 +416,56 @@ export abstract class ResourceObject<
     }
   }
 
+  // Log details
+  protected async logResourceOperation<Type>(
+    operationType: 'create' | 'delete' | 'update' | 'rename',
+    op?: Operation<Type>,
+    key?: string,
+  ): Promise<void> {
+    let configOperation: ConfigurationOperation;
+    const target = resourceNameToString(this.resourceName);
+    const parameters: Record<string, unknown> = { type: this.type };
+
+    switch (operationType) {
+      case 'create':
+        configOperation = ConfigurationOperation.RESOURCE_CREATE;
+        break;
+      case 'delete':
+        configOperation = ConfigurationOperation.RESOURCE_DELETE;
+        break;
+      case 'update':
+        configOperation = ConfigurationOperation.RESOURCE_UPDATE;
+        if (op) {
+          parameters.operation = op.name;
+        }
+        if (key) {
+          parameters.key = key;
+        }
+        break;
+      case 'rename':
+        configOperation = ConfigurationOperation.RESOURCE_RENAME;
+        if (op && op.name === 'change') {
+          const changeOp = op as ChangeOperation<string>;
+          parameters.oldName = changeOp.target;
+          parameters.newName = changeOp.to;
+        }
+        break;
+      default:
+        throw new Error(`Unknown operation type: ${operationType}`);
+    }
+
+    await ConfigurationLogger.log(
+      this.project.basePath,
+      configOperation,
+      target,
+      {
+        parameters,
+      },
+    );
+
+    this.logger.info(`Configuration: ${configOperation} - ${target}`);
+  }
+
   /**
    * Called after inherited class has finished 'update' operation.
    * @param content New content for resource
@@ -449,6 +507,9 @@ export abstract class ResourceObject<
 
     this.content = content;
     await this.write();
+
+    // Log resource update to migration log
+    await this.logResourceOperation('update', op, updateKey.key);
   }
 
   /**
@@ -496,9 +557,17 @@ export abstract class ResourceObject<
 
     this.fileName = newFilename;
     this.content.name = resourceNameToString(newName);
+    const newNameString = this.content.name;
     this.resourceName = newName;
 
-    this.project.resources.rename(oldName, this.content.name);
+    this.project.resources.rename(oldName, newNameString);
+
+    // Log resource rename to migration log
+    await this.logResourceOperation('rename', {
+      name: 'change',
+      target: oldName,
+      to: newNameString,
+    } as ChangeOperation<string>);
   }
 
   /**
@@ -712,6 +781,9 @@ export abstract class ResourceObject<
     await deleteFile(this.fileName);
     this.project.resources.remove(resourceNameToString(this.resourceName));
     this.fileName = '';
+
+    // Log resource deletion to migration log
+    await this.logResourceOperation('delete');
   }
 
   /**

package/src/utils/configuration-logger.ts

@@ -0,0 +1,206 @@
+/**
+  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 { readFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getChildLogger } from './log-utils.js';
+import { ProjectPaths } from '../containers/project/project-paths.js';
+import { writeFileSafe, pathExists } from './file-utils.js';
+
+/**
+ * Enum for configuration change operation types.
+ */
+export enum ConfigurationOperation {
+  MODULE_ADD = 'module_add',
+  MODULE_REMOVE = 'module_remove',
+  PROJECT_RENAME = 'project_rename',
+  RESOURCE_CREATE = 'resource_create',
+  RESOURCE_DELETE = 'resource_delete',
+  RESOURCE_RENAME = 'resource_rename',
+  RESOURCE_UPDATE = 'resource_update',
+}
+
+/**
+ * Individual log entry representing a single configuration change.
+ * @param timestamp Timestamp when the operation occurred (ISO string)
+ * @param operation Type of operation performed
+ * @param target Target of the operation
+ * @param parameters Additional parameters specific to the operation
+ */
+export interface ConfigurationLogEntry {
+  timestamp: string;
+  operation: ConfigurationOperation;
+  target: string;
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * Options for logging configuration changes.
+ * @param parameters  Additional parameters to store with the operation
+ */
+export interface ConfigurationLogOptions {
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * Logger for tracking configuration changes that affect project structure.
+ */
+export class ConfigurationLogger {
+  /**
+   * Path to the configuration log file.
+   * @param projectPath Path to the project root
+   * @returns Path to the log file
+   */
+  public static logFile(projectPath: string): string {
+    const paths = new ProjectPaths(projectPath);
+    return paths.configurationChangesLog;
+  }
+
+  /**
+   * Clears all log entries.
+   * @param projectPath Path to the project root
+   * @note Use with caution.
+   */
+  public static async clearLog(projectPath: string): Promise<void> {
+    const logFile = ConfigurationLogger.logFile(projectPath);
+    await writeFileSafe(logFile, '', 'utf-8');
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+    logger.info('Configuration log cleared');
+  }
+
+  /**
+   * Create a versioned snapshot of the current migration log.
+   * Renames current migrationLog.jsonl to migrationLog_<version>.jsonl
+   * @param projectPath Path to the project root
+   * @param version Version identifier (e.g., "1.0.0", "v2")
+   * @returns Path to the versioned log file
+   */
+  public static async createVersion(
+    projectPath: string,
+    version: string,
+  ): Promise<string> {
+    const paths = new ProjectPaths(projectPath);
+    const currentLogPath = paths.configurationChangesLog;
+    const versionedLogPath = join(
+      paths.migrationLogFolder,
+      `migrationLog_${version}.jsonl`,
+    );
+
+    // Only create version if current log exists and has content
+    if (!pathExists(currentLogPath)) {
+      throw new Error('No current migration log exists to version');
+    }
+
+    const content = await readFile(currentLogPath, 'utf-8');
+    if (!content.trim()) {
+      throw new Error('Current migration log is empty');
+    }
+
+    // Rename current to versioned
+    await rename(currentLogPath, versionedLogPath);
+
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+    logger.info(
+      `Created migration to version: ${version} at ${versionedLogPath}`,
+    );
+
+    return versionedLogPath;
+  }
+
+  /**
+   * Reads all configuration log entries using JSON Lines format.
+   * @param projectPath Path to the project root
+   * @returns Array of log entries
+   */
+  public static async entries(
+    projectPath: string,
+  ): Promise<ConfigurationLogEntry[]> {
+    const logFile = ConfigurationLogger.logFile(projectPath);
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+
+    try {
+      const content = await readFile(logFile, 'utf-8');
+      const lines = content
+        .trim()
+        .split('\n')
+        .filter((line) => line.trim());
+
+      const entries: ConfigurationLogEntry[] = [];
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line) as ConfigurationLogEntry;
+          if (entry.timestamp && entry.operation && entry.target) {
+            entries.push(entry);
+          }
+        } catch {
+          logger.error(`Invalid configuration line: ${line}`);
+        }
+      }
+
+      return entries;
+    } catch (error) {
+      logger.error({ error }, `Failed to read configuration log`);
+      return [];
+    }
+  }
+
+  /**
+   * Check if a configuration log exists for the given project path.
+   * @param projectPath Path to the project root
+   * @returns True if log file exists
+   */
+  public static hasLog(projectPath: string): boolean {
+    const logPath = new ProjectPaths(projectPath).configurationChangesLog;
+    return pathExists(logPath);
+  }
+
+  /**
+   * Log a configuration change operation.
+   * @note This is designed to be called AFTER the operation succeeds.
+   * @param projectPath Path to the project root
+   * @param operation The type of operation
+   * @param target The target of the operation
+   * @param options Additional options for the log entry
+   */
+  public static async log(
+    projectPath: string,
+    operation: ConfigurationOperation,
+    target: string,
+    options?: ConfigurationLogOptions,
+  ): Promise<void> {
+    const logFile = ConfigurationLogger.logFile(projectPath);
+    const logger = getChildLogger({ module: 'ConfigurationLogger' });
+
+    try {
+      const entry: ConfigurationLogEntry = {
+        timestamp: new Date().toISOString(),
+        operation,
+        target,
+        parameters: options?.parameters,
+      };
+
+      await writeFileSafe(logFile, JSON.stringify(entry) + '\n', {
+        flag: 'a',
+      });
+
+      logger.debug(`Logged ${operation} operation for target: ${target}`);
+    } catch (error) {
+      logger.error(
+        { error, operation, target },
+        `Configuration logging failed`,
+      );
+    }
+  }
+}

package/src/utils/constants.ts

@@ -42,13 +42,15 @@ export const VALID_FOLDER_RESOURCE_FILES = [
  * These are field names that are non-custom fields that present in metadata
  */
 export const PREDEFINED_FIELDS = [
-  'rank',
   'cardType',
-  'title',
-  'workflowState',
+  'labels',
   'lastUpdated',
   'lastTransitioned',
+  'links',
+  'rank',
   'templateCardKey',
+  'title',
+  'workflowState',
 ] satisfies (keyof PredefinedCardMetadata)[];
 
 /**