@cyberismo/data-handler 0.0.2

package/dist/commands/export-site.d.ts

@@ -0,0 +1,45 @@
+/**
+  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 Calculate, type Show } from './index.js';
+import { Export } from './export.js';
+import type { Project } from '../containers/project.js';
+interface ExportOptions {
+    silent: boolean;
+}
+export declare class ExportSite extends Export {
+    private tmpDir;
+    private moduleDir;
+    private pagesDir;
+    private imagesDir;
+    private playbookDir;
+    private playbookFile;
+    private navFile;
+    private options;
+    constructor(project: Project, calculateCmd: Calculate, showCmd: Show);
+    private createCardsIndex;
+    private initDirectories;
+    private generate;
+    private createPlaybook;
+    private createDescriptor;
+    private initRepo;
+    private toAdocDirectoryAsContent;
+    private export;
+    /**
+     * Export the card tree as an Antora site
+     * @param destination Path where the site is generated
+     * @param cardKey Optional; If defined exports the card tree from underneath this card.
+     */
+    exportToSite(destination: string, cardKey?: string, options?: ExportOptions): Promise<string>;
+}
+export {};

package/dist/commands/export-site.js

@@ -0,0 +1,301 @@
+/**
+  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
+import fs from 'node:fs';
+import { platform, tmpdir } from 'node:os';
+import { appendFile, copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import git from 'isomorphic-git';
+import { dump } from 'js-yaml';
+import { Export } from './export.js';
+import { errorFunction } from '../utils/log-utils.js';
+import { sortItems } from '../utils/lexorank.js';
+import { getStaticDirectoryPath } from '@cyberismocom/resources';
+export class ExportSite extends Export {
+    tmpDir = '';
+    moduleDir = '';
+    pagesDir = '';
+    imagesDir = '';
+    playbookDir = '';
+    playbookFile = '';
+    navFile = '';
+    options;
+    constructor(project, calculateCmd, showCmd) {
+        super(project, calculateCmd, showCmd);
+    }
+    // Writes index.html file into cards folder that just redirects to the first card.
+    createCardsIndex(destination, cardKey) {
+        const indexFile = join(destination, 'cards', 'index.html');
+        const indexContent = `<meta http-equiv="refresh" content="0; url=${cardKey}.html">`;
+        try {
+            fs.writeFileSync(indexFile, indexContent);
+        }
+        catch (error) {
+            throw new Error(errorFunction(error));
+        }
+    }
+    // todo: change this so that split temp folder creation to its own method.
+    // then parallelize this and export() as much as you can.
+    async initDirectories() {
+        // Create temporary adoc output directory
+        try {
+            this.tmpDir = mkdtempSync(join(tmpdir(), 'cards-'));
+        }
+        catch (error) {
+            throw new Error(errorFunction(error));
+        }
+        // Antora requires the content directory to be a Git repository
+        await this.initRepo();
+        // Create the pages and images directories
+        this.moduleDir = join(this.tmpDir, 'modules', 'ROOT');
+        this.pagesDir = join(this.moduleDir, 'pages');
+        this.imagesDir = join(this.moduleDir, 'assets', 'images');
+        this.navFile = join(this.moduleDir, 'nav.adoc');
+        const promiseContainer = [];
+        promiseContainer.push(mkdir(this.pagesDir, { recursive: true }));
+        promiseContainer.push(mkdir(this.imagesDir, { recursive: true }));
+        await Promise.all(promiseContainer);
+        // Create the playbook directory
+        this.playbookDir = mkdtempSync(join(tmpdir(), 'cards-playbook-'));
+    }
+    // Generate the site from the source files using Antora.
+    generate(outputPath) {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = dirname(__filename);
+        const absoluteOutputPath = resolve(process.cwd(), outputPath);
+        const additionalArguments = [
+            '--to-dir',
+            absoluteOutputPath,
+            this.playbookFile,
+        ];
+        if (this.options && this.options?.silent) {
+            additionalArguments.unshift('--silent');
+        }
+        // Use spawnsync to npx execute the program "antora"
+        try {
+            // Allthough we use pnpm as the package manager, we rather use npx at runtime, because it is shipped with node
+            spawnSync('npx', ['antora', ...additionalArguments], {
+                stdio: 'inherit',
+                shell: platform() === 'win32',
+                cwd: __dirname,
+            });
+        }
+        catch (error) {
+            throw new Error(errorFunction(error));
+        }
+    }
+    // Create the Antora playbook.
+    async createPlaybook(cards) {
+        let startPage = '';
+        if (cards[0]) {
+            startPage = cards[0].key + '.adoc';
+        }
+        else {
+            throw new Error('Cannot create a playbook for an empty card set');
+        }
+        const playbook = {
+            site: {
+                title: this.project.configuration.name,
+                start_page: `cards:ROOT:${startPage}`,
+            },
+            content: {
+                sources: [
+                    {
+                        url: this.tmpDir,
+                        branches: 'HEAD',
+                    },
+                ],
+            },
+            urls: {
+                html_extension_style: 'default',
+            },
+            ui: {
+                bundle: {
+                    url: join(await getStaticDirectoryPath(), 'ui-bundle'),
+                    snapshot: true,
+                },
+            },
+        };
+        this.playbookFile = join(this.playbookDir, 'antora-playbook.yml');
+        writeFileSync(this.playbookFile, dump(playbook));
+    }
+    // Create the Antora site descriptor.
+    createDescriptor() {
+        const projectName = this.project.configuration.name;
+        const descriptor = {
+            name: 'cards',
+            title: projectName,
+            version: null,
+            nav: ['modules/ROOT/nav.adoc'],
+        };
+        const descriptorPath = join(this.tmpDir, 'antora.yml');
+        try {
+            writeFileSync(descriptorPath, dump(descriptor));
+        }
+        catch (error) {
+            throw new Error(errorFunction(error));
+        }
+    }
+    // Initialise the temporary directory as a temporary Git repository.
+    async initRepo() {
+        try {
+            await git.init({ fs, dir: this.tmpDir });
+            writeFileSync(join(this.tmpDir, '.gitkeep'), '');
+            await git.add({ fs, dir: this.tmpDir, filepath: '.gitkeep' });
+        }
+        catch (error) {
+            throw new Error(errorFunction(error));
+        }
+        try {
+            await git.commit({
+                fs,
+                dir: this.tmpDir,
+                author: {
+                    name: 'Cyberismo Cards',
+                    email: 'info@cyberismo.com',
+                },
+                message: 'Add .gitkeep',
+            });
+        }
+        catch (error) {
+            throw new Error(errorFunction(error));
+        }
+    }
+    // Write cards as Antora-compatible AsciiDoc to the given location
+    // @param path Directory where the cards should be written
+    // @param cards Array of Cards
+    // @param depth Navigation depth - this is used in recursion to format the hierarchical menu
+    async toAdocDirectoryAsContent(path, cards, depth) {
+        depth++;
+        // Sort the cards by rank
+        cards = sortItems(cards, function (card) {
+            return card.metadata?.rank || '1|z';
+        });
+        // Ensure the target path exists
+        await mkdir(path, { recursive: true });
+        for (const card of cards) {
+            // Construct path for individual card file
+            const cardPath = join(path, card.key + '.adoc');
+            const cardXRef = cardPath.slice(this.pagesDir.length);
+            let navFileContent = '';
+            if (card.metadata?.progress) {
+                navFileContent =
+                    '*'.repeat(depth) +
+                        ` xref:${cardXRef}[${card.metadata?.title} (${card.metadata?.progress}%)]\n`;
+            }
+            else {
+                navFileContent =
+                    '*'.repeat(depth) + ` xref:${cardXRef}[${card.metadata?.title}]\n`;
+            }
+            await appendFile(this.navFile, navFileContent);
+            let tempContent = '';
+            if (card.metadata) {
+                const cardTypeForCard = await this.project.resource(card.metadata?.cardType);
+                tempContent = '\n= ';
+                tempContent += card.metadata?.title
+                    ? `${card.metadata.title}\n\n`
+                    : 'Untitled\n\n';
+                tempContent += super.metaToAdoc(card, cardTypeForCard);
+            }
+            if (card.content) {
+                tempContent += '\n' + card.content;
+            }
+            if (tempContent !== '') {
+                await writeFile(cardPath, tempContent);
+            }
+            if (card.children && card.children.length > 0) {
+                // Recurse into the child cards
+                await this.toAdocDirectoryAsContent(path, card.children, depth);
+            }
+            if (card.attachments) {
+                const promiseContainer = [];
+                for (const attachment of card.attachments) {
+                    const source = join(attachment.path, attachment.fileName);
+                    const destination = join(this.imagesDir, `${attachment.fileName}`);
+                    promiseContainer.push(copyFile(source, destination));
+                }
+                await Promise.all(promiseContainer);
+            }
+        }
+        --depth;
+    }
+    // Export the cards to the temporary directory as a full HTML site generated by Antora.
+    async export(destination, cards) {
+        await this.initDirectories();
+        this.createDescriptor();
+        await this.toAdocDirectoryAsContent(this.pagesDir, cards, 0);
+        await this.createPlaybook(cards);
+        this.generate(destination);
+    }
+    /**
+     * Export the card tree as an Antora site
+     * @param destination Path where the site is generated
+     * @param cardKey Optional; If defined exports the card tree from underneath this card.
+     */
+    async exportToSite(destination, cardKey, options) {
+        this.options = options;
+        const sourcePath = cardKey
+            ? join(this.project.paths.cardRootFolder, this.project.pathToCard(cardKey))
+            : this.project.paths.cardRootFolder;
+        let cards = [];
+        // If doing a partial tree export, put the parent information as it would have already been gathered.
+        if (cardKey) {
+            const card = await this.project.findSpecificCard(cardKey);
+            if (!card) {
+                throw new Error(`Input validation error: cannot find card '${cardKey}'`);
+            }
+            cards.push({
+                key: cardKey,
+                path: sourcePath,
+                children: [],
+                attachments: [],
+            });
+        }
+        await this.calculateCmd.generate();
+        const tree = await this.calculateCmd.runQuery('tree');
+        if (cardKey) {
+            const targetCard = this.findCardInTree(tree, cardKey);
+            if (!targetCard) {
+                throw new Error(`Cannot find card '${cardKey}' in the tree hierarchy`);
+            }
+            cards = [await this.treeQueryResultToCard(targetCard)];
+        }
+        else {
+            for (const treeQueryResult of tree) {
+                cards.push(await this.treeQueryResultToCard(treeQueryResult));
+            }
+        }
+        if (!cards.length) {
+            throw new Error('No cards found');
+        }
+        if (cards.length > 3000) {
+            throw new Error(`There are ${cards.length} cards in the project. Exporting to a site only supports maximum of 3000 cards.`);
+        }
+        if (cards.length > 1000 && cards.length < 3000) {
+            console.warn(`Warning: There are ${cards.length} cards in the project. There is a hard limit of 3000 cards that can be exported as a site.`);
+        }
+        await this.export(destination, cards);
+        if (cards.length > 0 && cards.at(0)) {
+            const firstCard = cards.at(0);
+            if (firstCard && firstCard.key) {
+                this.createCardsIndex(destination, firstCard.key);
+            }
+        }
+        return '';
+    }
+}
+//# sourceMappingURL=export-site.js.map

package/dist/commands/export-site.js.map

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

package/dist/commands/export.d.ts

@@ -0,0 +1,53 @@
+/**
+  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 { Calculate, Show } from './index.js';
+import type { Card } from '../interfaces/project-interfaces.js';
+import type { CardType } from '../interfaces/resource-interfaces.js';
+import { Project } from '../containers/project.js';
+import type { QueryResult } from '../types/queries.js';
+export declare class Export {
+    protected project: Project;
+    protected calculateCmd: Calculate;
+    protected showCmd: Show;
+    constructor(project: Project, calculateCmd: Calculate, showCmd: Show);
+    private toAdocFile;
+    protected metaToAdoc(card: Card, cardType: CardType | undefined): string;
+    private toAdocFileAsContent;
+    /**
+     * Recursively searches for a card with the specified key in the tree hierarchy.
+     * @param treeItems Array of tree query results to search through
+     * @param targetKey The key of the card to find
+     * @returns The found tree item or null if not found
+     */
+    protected findCardInTree(treeItems: QueryResult<'tree'>[], targetKey: string): QueryResult<'tree'> | null;
+    /**
+     * Convert treeQueryResult object into a Card object and add content, metadata & attachments
+     * Handles card children recursively
+     * @param treeQueryResult tree query result object
+     */
+    protected treeQueryResultToCard(treeQueryResult: QueryResult<'tree'>): Promise<Card>;
+    /**
+     * Exports the card(s) to ascii doc.
+     * @param destination Path to where the resulting file(s) will be created.
+     * @param cardKey If not exporting the whole card tree, card key of parent card.
+     * @returns status message
+     */
+    exportToADoc(destination: string, cardKey?: string): Promise<string>;
+    /**
+     * Exports the card(s) to HTML and opens the browser.
+     * @param destination Path to where the resulting file(s) will be created.
+     * @param cardKey Optional; If not exporting the whole card tree, card key of parent card.
+     */
+    exportToHTML(destination: string, cardKey?: string): Promise<string>;
+}

package/dist/commands/export.js

@@ -0,0 +1,251 @@
+/**
+  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
+import { appendFile, copyFile, mkdir, truncate } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+// asciidoctor
+import Processor from '@asciidoctor/core';
+import { Project } from '../containers/project.js';
+import { sortItems } from '../utils/lexorank.js';
+const attachmentFolder = 'a';
+export class Export {
+    project;
+    calculateCmd;
+    showCmd;
+    constructor(project, calculateCmd, showCmd) {
+        this.project = project;
+        this.calculateCmd = calculateCmd;
+        this.showCmd = showCmd;
+    }
+    // This file should set the top level items to the adoc.
+    async toAdocFile(path, cards) {
+        await appendFile(path, `:imagesdir: ./${attachmentFolder}/\n`);
+        await this.toAdocFileAsContent(path, cards);
+    }
+    // Format card metadata to an AsciiDoc table.
+    metaToAdoc(card, cardType) {
+        let content = '';
+        if (card.metadata) {
+            content += `[.cyberismo-meta-wrapper]\n`;
+            content += '--\n';
+            content += `[.cyberismo-meta]\n`;
+            content += '[cols="1,1"]\n';
+            content += '[frame=none]\n';
+            content += '[grid=none]\n';
+            content += '|===\n';
+            content += `|Card key|${card.key}\n`;
+            content += `|Status|${card.metadata.workflowState}\n`;
+            content += `|Card type|${card.metadata.cardType}\n`;
+            content += `|Labels|${card.metadata.labels?.join(', ') || ''}`;
+            for (const [key, value] of Object.entries(card.metadata)) {
+                if (cardType?.alwaysVisibleFields.includes(key) ||
+                    cardType?.optionallyVisibleFields?.includes(key)) {
+                    const displayName = cardType?.customFields.find((item) => item.name === key)?.displayName;
+                    let nameToShow = displayName
+                        ? displayName
+                        : key[0].toUpperCase() + key.slice(1);
+                    if (nameToShow === 'WorkflowState') {
+                        nameToShow = 'Workflow state';
+                    }
+                    else if (nameToShow === 'Cardtype') {
+                        nameToShow = 'Card type';
+                    }
+                    // Escape pipe character in cell values
+                    let escapedValue = 'N/A';
+                    if (value) {
+                        escapedValue = value.toString().replaceAll('|', '\\|');
+                    }
+                    content += `|${nameToShow}|${escapedValue}\n`;
+                }
+            }
+            content += '|===\n';
+            content += '--\n';
+        }
+        return content;
+    }
+    async toAdocFileAsContent(path, cards) {
+        for (const card of cards) {
+            let fileContent = '';
+            if (card.metadata?.title) {
+                fileContent += `== ${card.metadata.title}\n\n`;
+            }
+            else {
+                fileContent += `== ${card.key}\n\n`;
+            }
+            if (card.metadata) {
+                const cardTypeForCard = await this.project.resource(card.metadata?.cardType);
+                const metaDataContent = this.metaToAdoc(card, cardTypeForCard);
+                fileContent += metaDataContent;
+            }
+            if (card.content) {
+                fileContent += card.content;
+            }
+            if (card.attachments) {
+                const promiseContainer = [];
+                for (const attachment of card.attachments) {
+                    const destination = join(dirname(path), attachmentFolder, attachment.fileName);
+                    const source = join(attachment.path, attachment.fileName);
+                    promiseContainer.push(copyFile(source, destination));
+                }
+                await Promise.all(promiseContainer);
+            }
+            // Add separator between cards
+            fileContent += '\n\n';
+            if (fileContent) {
+                await appendFile(path, fileContent);
+            }
+            if (card.children) {
+                await this.toAdocFileAsContent(path, card.children);
+            }
+        }
+    }
+    /**
+     * Recursively searches for a card with the specified key in the tree hierarchy.
+     * @param treeItems Array of tree query results to search through
+     * @param targetKey The key of the card to find
+     * @returns The found tree item or null if not found
+     */
+    findCardInTree(treeItems, targetKey) {
+        for (const item of treeItems) {
+            if (item.key === targetKey) {
+                return item;
+            }
+            if (item.children && item.children.length > 0) {
+                const foundInChildren = this.findCardInTree(item.children, targetKey);
+                if (foundInChildren) {
+                    return foundInChildren;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Convert treeQueryResult object into a Card object and add content, metadata & attachments
+     * Handles card children recursively
+     * @param treeQueryResult tree query result object
+     */
+    async treeQueryResultToCard(treeQueryResult) {
+        const card = {
+            key: treeQueryResult.key,
+            path: '',
+            children: [],
+            attachments: [],
+        };
+        // Get content and attachments separately, not included in queries
+        const fetchCardDetails = {
+            attachments: true,
+            children: false,
+            content: true,
+            contentType: 'adoc',
+            metadata: true,
+            parent: false,
+        };
+        const cardDetailsResponse = await this.showCmd.showCardDetails(fetchCardDetails, card.key);
+        let asciiDocContent = '';
+        const projectPath = this.project.basePath;
+        try {
+            const { evaluateMacros } = await import('../macros/index.js');
+            asciiDocContent = await evaluateMacros(cardDetailsResponse.content || '', {
+                mode: 'static',
+                projectPath,
+                cardKey: card.key,
+            });
+        }
+        catch (error) {
+            asciiDocContent = `Macro error: ${error instanceof Error ? error.message : 'Unknown error'}\n\n${asciiDocContent}`;
+        }
+        card.path = cardDetailsResponse.path;
+        card.metadata = cardDetailsResponse.metadata;
+        card.metadata.progress = treeQueryResult.progress;
+        card.content = asciiDocContent;
+        card.attachments = cardDetailsResponse.attachments;
+        for (const result of treeQueryResult.children ?? []) {
+            card.children.push(await this.treeQueryResultToCard(result));
+        }
+        return card;
+    }
+    /**
+     * Exports the card(s) to ascii doc.
+     * @param destination Path to where the resulting file(s) will be created.
+     * @param cardKey If not exporting the whole card tree, card key of parent card.
+     * @returns status message
+     */
+    async exportToADoc(destination, cardKey) {
+        const sourcePath = this.project.paths.cardRootFolder;
+        let cards = [];
+        // If doing a partial tree export, put the parent information as it would have already been gathered.
+        if (cardKey) {
+            const card = await this.project.findSpecificCard(cardKey);
+            if (!card) {
+                throw new Error(`Input validation error: cannot find card '${cardKey}'`);
+            }
+            cards.push({
+                key: cardKey,
+                path: sourcePath,
+                children: [],
+                attachments: [],
+            });
+        }
+        await this.calculateCmd.generate();
+        const tree = await this.calculateCmd.runQuery('tree');
+        if (cardKey) {
+            const targetCard = this.findCardInTree(tree, cardKey);
+            if (!targetCard) {
+                throw new Error(`Cannot find card '${cardKey}' in the tree hierarchy`);
+            }
+            cards = [await this.treeQueryResultToCard(targetCard)];
+        }
+        else {
+            for (const treeQueryResult of tree) {
+                cards.push(await this.treeQueryResultToCard(treeQueryResult));
+            }
+        }
+        // Sort the cards by rank
+        cards = sortItems(cards, function (card) {
+            return card.metadata?.rank || '1|z';
+        });
+        await mkdir(join(destination, attachmentFolder), { recursive: true });
+        const resultDocumentPath = join(destination, Project.cardContentFile);
+        let message = '';
+        try {
+            await truncate(resultDocumentPath, 0);
+            message = `Using existing output file '${resultDocumentPath}'`;
+        }
+        catch {
+            message = `Creating output file '${resultDocumentPath}'`;
+        }
+        await this.toAdocFile(resultDocumentPath, cards);
+        return message;
+    }
+    /**
+     * Exports the card(s) to HTML and opens the browser.
+     * @param destination Path to where the resulting file(s) will be created.
+     * @param cardKey Optional; If not exporting the whole card tree, card key of parent card.
+     */
+    async exportToHTML(destination, cardKey) {
+        let message = '';
+        await this.exportToADoc(destination, cardKey).then((msg) => {
+            message = msg;
+            const asciiDocProcessor = Processor();
+            const adocFile = join(destination, Project.cardContentFile);
+            asciiDocProcessor.convertFile(adocFile, {
+                safe: 'safe',
+                base_dir: '/',
+                standalone: true,
+            });
+        });
+        return message;
+    }
+}
+//# sourceMappingURL=export.js.map