@cyberismo/data-handler 0.0.2

package/dist/card-metadata-updater.d.ts

@@ -0,0 +1,33 @@
+/**
+  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 { Project } from './containers/project.js';
+import type { UpdateField } from './types/queries.js';
+/**
+ * Handles the updating of card metadata from clingo query result.
+ *
+ * todo: Once 'Card' class is created, the functionality in this class
+ *       can be incorporated there and this class can be removed.
+ */
+export declare class CardMetadataUpdater {
+    /**
+     * Applies a given array of changes to card(s).
+     * @param project Current project.
+     * @param fieldsToUpdate Array of field updates. Each update consists of cardKey, fieldName and new value.
+     */
+    static apply(project: Project, fieldsToUpdate: UpdateField[]): Promise<void>;
+    private static applyFieldChange;
+    private static groupChangesByCard;
+    private static reportErrors;
+    private static updateCardMetadata;
+}

package/dist/card-metadata-updater.js

@@ -0,0 +1,121 @@
+/**
+  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 { FieldTypeResource } from './resources/field-type-resource.js';
+import { logger } from './utils/log-utils.js';
+/**
+ * Handles the updating of card metadata from clingo query result.
+ *
+ * todo: Once 'Card' class is created, the functionality in this class
+ *       can be incorporated there and this class can be removed.
+ */
+export class CardMetadataUpdater {
+    /**
+     * Applies a given array of changes to card(s).
+     * @param project Current project.
+     * @param fieldsToUpdate Array of field updates. Each update consists of cardKey, fieldName and new value.
+     */
+    static async apply(project, fieldsToUpdate) {
+        if (!fieldsToUpdate || fieldsToUpdate.length === 0) {
+            return;
+        }
+        const updates = CardMetadataUpdater.groupChangesByCard(fieldsToUpdate);
+        const updatePromises = [];
+        for (const [cardKey, changes] of updates.entries()) {
+            updatePromises.push(CardMetadataUpdater.updateCardMetadata(project, cardKey, changes));
+        }
+        const results = await Promise.all(updatePromises);
+        CardMetadataUpdater.reportErrors(results);
+    }
+    // Applies a single field change to a card's metadata.
+    static async applyFieldChange(project, metadata, change) {
+        const result = {
+            success: true,
+            errors: [],
+        };
+        if (change.field === 'title' || change.field === 'workflowState') {
+            metadata[change.field] = FieldTypeResource.fromClingoResult(change.newValue, 'shortText');
+            return result;
+        }
+        if (change.field === 'cardType' || change.field === 'rank') {
+            result.success = false;
+            result.errors.push(`For card ${change.card} cannot change card's ${change.field}.`);
+            return result;
+        }
+        const fieldType = await project.resource(change.field);
+        if (!fieldType) {
+            result.success = false;
+            result.errors.push(`Field type '${change.field}' from transition change does not exist in the project.`);
+            return result;
+        }
+        metadata[change.field] = FieldTypeResource.fromClingoResult(change.newValue, fieldType.dataType);
+        return result;
+    }
+    // Groups changes by card key. Returns grouped map. Mapping is by cardKey.
+    static groupChangesByCard(fieldsToUpdate) {
+        const updatesByCardKey = new Map();
+        fieldsToUpdate.forEach((change) => {
+            const cardKey = change.card;
+            if (!updatesByCardKey.has(cardKey)) {
+                updatesByCardKey.set(cardKey, []);
+            }
+            const cardChanges = updatesByCardKey.get(cardKey);
+            if (cardChanges) {
+                cardChanges.push({
+                    field: change.field,
+                    card: change.card,
+                    newValue: change.newValue,
+                });
+            }
+        });
+        return updatesByCardKey;
+    }
+    // Reports errors from update operations to the logger.
+    static reportErrors(results) {
+        const allErrors = results
+            .filter((result) => !result.success)
+            .flatMap((result) => result.errors);
+        if (allErrors.length > 0) {
+            allErrors.push('On transition change to card(s) can not be applied.');
+            logger.error(allErrors.join('\n'));
+        }
+    }
+    // Updates a single card's metadata with the provided changes.
+    static async updateCardMetadata(project, cardKey, changes) {
+        const result = {
+            success: true,
+            errors: [],
+        };
+        const card = await project.findSpecificCard(cardKey, {
+            metadata: true,
+        });
+        if (!card || !card.metadata) {
+            result.success = false;
+            result.errors.push(`Card ${cardKey} does not exist in the project. Changes cannot be applied.`);
+            return result;
+        }
+        const updatePromises = changes.map((change) => CardMetadataUpdater.applyFieldChange(project, card.metadata, change));
+        const updateResults = await Promise.all(updatePromises);
+        for (const updateResult of updateResults) {
+            if (!updateResult.success) {
+                result.success = false;
+                result.errors.push(...updateResult.errors);
+            }
+        }
+        if (result.success) {
+            project.updateCardMetadata(card, card.metadata);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=card-metadata-updater.js.map

package/dist/card-metadata-updater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-metadata-updater.js","sourceRoot":"","sources":["../src/card-metadata-updater.ts"],"names":[],"mappings":"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"}

package/dist/command-handler.d.ts

@@ -0,0 +1,96 @@
+/**
+  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/>.
+*/
+import type { requestStatus } from './interfaces/request-status-interfaces.js';
+export interface CardsOptions {
+    details?: boolean;
+    forceStart?: boolean;
+    projectPath?: string;
+    repeat?: number;
+    showUse?: boolean;
+}
+export declare enum Cmd {
+    add = "add",
+    calc = "calc",
+    create = "create",
+    edit = "edit",
+    export = "export",
+    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 declare enum ExportFormats {
+    adoc = "adoc",
+    html = "html",
+    site = "site"
+}
+export { CommandManager } from './command-manager.js';
+/**
+ * Class that handles all CLI commands.
+ */
+export declare class Commands {
+    private commands?;
+    private projectPath;
+    private validateCmd;
+    constructor();
+    /**
+     * Executes one command for CLI.
+     *
+     * @note internal functions that this method calls, should return a Promise and throw on error.
+     * No internal trap harnesses; all exceptions from internal methods should be caught by this methods trap handler.
+     * If internal method has payload, the method should return requestStatus that can be directly returned from calling that function.
+     *
+     * @param command command to execute
+     * @param args arguments for the command
+     * @param options options for the command
+     * @returns request status; 200 if success; 400 in handled error; 500 in unknown error
+     */
+    command(command: Cmd, args: string[], options: CardsOptions): Promise<requestStatus>;
+    private commandType;
+    private commandTarget;
+    private doSetProject;
+    private doHandleCommand;
+    /**
+     * Returns project path, if running operation within project folder.
+     * @param path Initial path from where the project path search is started.
+     */
+    getProjectPath(path?: string): Promise<string>;
+    /**
+     * Returns project path, if running operation within project folder.
+     * Implementation will automatically look for valid project path starting from 'path' and moving upwards in the
+     * path until 'root' is reached.
+     * @param path Initial path from where the project path search is started.
+     * Returns valid project path (contains both .cards and cardRoot subfolders).
+     */
+    setProjectPath(path?: string): Promise<string>;
+    private addCard;
+    private createCard;
+    private export;
+    private generateLogicProgram;
+    private import;
+    private importCsv;
+    private remove;
+    private runLogicProgram;
+    private runReport;
+    private show;
+    private startApp;
+    private validate;
+}