@synergenius/flowweaver-pack-github-actions 0.1.1

package/LICENSE

@@ -0,0 +1,204 @@
+Flow Weaver Library License
+
+Version 2.0, February 2026
+
+## Quick Reference (non-binding summary)
+
+This table is provided for convenience only. In case of any conflict between
+this summary and the license terms below, the license terms control.
+
+Permitted:
+
+  Use                                       Who               Notes
+  ----------------------------------------  ----------------  ----------------------------------
+  Install and run locally                   Anyone            No restrictions on local use
+  Compile workflows                         Anyone            CLI, programmatic, scripts
+  Use generated output (code, artifacts)    Anyone            Output is unrestricted
+  Run in CI/CD pipelines and build systems  Anyone, any size  Not considered "hosting"
+  Distribute copies with license notices    Anyone            Must include license, mark changes
+  Create derivative works                   Anyone            Must retain license key checks
+  Host internally                           Orgs <= 15        All members count toward limit
+  Embed in internal toolchains              Anyone            No visual workflow authoring UI
+  Use inside a larger product                Anyone            If flow-weaver is not the primary value
+
+Requires commercial license:
+
+  Use                                       Notes
+  ----------------------------------------  ----------------------------------
+  Host internally                           Orgs > 15 people
+  Build visual workflow authoring tools     Standalone products for workflow authoring
+  Offer as a hosted or managed service      To third parties, at any scale
+  Sell products built on the software       Where flow-weaver is the primary value
+
+Never permitted:
+
+  Use                                       Notes
+  ----------------------------------------  ----------------------------------
+  Remove or circumvent license keys         Applies to software and derivatives
+  Remove licensing or copyright notices     Must always be retained
+  Strip license key checks from forks       Derivatives must retain protections
+
+---
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any of the features or
+functionality of the software.
+
+You may not use the software to build, distribute, or offer any standalone
+product or service whose primary purpose is providing a graphical or visual
+interface for creating, editing, designing, or composing workflows. This
+restriction applies whether the product is hosted, distributed, sold, or offered
+free of charge. It does not apply to products that use the software internally
+without exposing its workflow authoring capabilities to end users through a
+graphical interface.
+
+You may not sell the software or any product that provides, as its primary
+function, capabilities supplied by the software (including workflow compilation,
+parsing, validation, code generation, or diagram generation), without a separate
+commercial license from the licensor. This does not restrict the sale of products
+that merely incorporate the software as one component among many, where the
+product's primary value comes from functionality independent of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+Derivative works must retain all license key functionality, license verification
+mechanisms, and licensing notices present in the original software. Distributing
+derivative works with license key protections removed, disabled, or bypassed
+constitutes a violation of this license.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to the
+software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate immediately.
+
+You may request a review of any termination by contacting the licensor in
+writing within 15 days of termination. The licensor will respond within 30 days.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Governing Law
+
+This license is governed by the laws of Portugal. Any disputes arising from or
+related to this license will be submitted to the exclusive jurisdiction of the
+courts of Lisbon, Portugal.
+
+## Definitions
+
+The "licensor" is Ricardo Jose Horta Morais (Synergenius), and the "software"
+is the software the licensor makes available under these terms.
+
+"You" refers to the individual or entity agreeing to these terms. "Your company"
+is any legal entity, sole proprietorship, or other kind of organization that you
+work for, plus all organizations that have control over, are under the control
+of, or are under common control with that organization. "Control" means
+ownership of substantially all the assets of an entity, or the power to direct
+its management and policies by vote, contract, or otherwise. Control can be
+direct or indirect.
+
+"Third parties" means any individual or entity that is not you or your company
+as defined in these terms.
+
+"Your licenses" are all the licenses granted to you for the software under these
+terms. "Use" means anything you do with the software requiring one of your
+licenses.
+
+"Hosting the software" means making the software's functionality available to
+users over a network as a service. Running the software in automated build
+pipelines, continuous integration systems, command-line interfaces, or
+development toolchains does not constitute hosting, regardless of organization
+size.
+
+---
+
+ADDITIONAL NOTICES
+
+1. Output of the Software
+
+The output of the software, including but not limited to compiled workflows,
+generated code, deployment artifacts, and any other files produced by the
+software's compilation, code generation, or export features, is not considered
+part of the software and may be used, copied, modified, distributed, and
+sublicensed for any purpose without restriction under this license.
+
+2. Internal Hosting Threshold
+
+Organizations with 15 or fewer individuals, including employees, contractors,
+and affiliates, may host the software on internal infrastructure for use by
+their members without restriction under this license. The count includes all
+individuals in the organization, not only those who directly use the software.
+
+Organizations with more than 15 individuals that wish to host the software,
+whether on internal infrastructure or as a service, require a commercial
+license.
+
+3. Unrestricted Use
+
+Using the software locally, including installing, running, compiling workflows,
+generating code, and producing deployment artifacts, is permitted for any
+individual or organization regardless of size, subject to the Limitations above.
+
+4. Export Compliance
+
+You are responsible for compliance with all applicable export and import laws
+and regulations in your jurisdiction when using, distributing, or making the
+software available.
+
+5. Commercial Licensing
+
+For commercial licensing inquiries, partnership arrangements, or questions
+about permitted use, contact support@synergenius.pt.

package/dist/target.d.ts

@@ -0,0 +1,54 @@
+/**
+ * GitHub Actions Export Target
+ *
+ * Generates .github/workflows/<name>.yml from a Flow Weaver CI/CD workflow.
+ * No FW runtime dependency — outputs native GitHub Actions YAML.
+ *
+ * Mapping:
+ * - FW Node → GitHub Actions step (uses: or run:)
+ * - FW [job: "name"] → GitHub Actions job
+ * - FW @path → job `needs:` dependencies
+ * - FW @secret → ${{ secrets.NAME }}
+ * - FW @cache → actions/cache@v4
+ * - FW @artifact → actions/upload-artifact@v4 / actions/download-artifact@v4
+ * - FW @trigger → `on:` event configuration
+ */
+import { BaseCICDTarget } from '@synergenius/flow-weaver/deployment';
+import type { ExportOptions, ExportArtifacts, DeployInstructions } from '@synergenius/flow-weaver/deployment';
+export declare class GitHubActionsTarget extends BaseCICDTarget {
+    readonly name = "github-actions";
+    readonly description = "GitHub Actions workflow YAML (.github/workflows/)";
+    readonly deploySchema: {
+        runner: {
+            type: "string";
+            description: string;
+            default: string;
+        };
+    };
+    readonly nodeTypeDeploySchema: {
+        action: {
+            type: "string";
+            description: string;
+        };
+        with: {
+            type: "string";
+            description: string;
+        };
+        label: {
+            type: "string";
+            description: string;
+        };
+    };
+    generate(options: ExportOptions): Promise<ExportArtifacts>;
+    getDeployInstructions(_artifacts: ExportArtifacts): DeployInstructions;
+    private renderWorkflowYAML;
+    private renderTriggers;
+    private renderJob;
+    private renderStep;
+    private renderCacheStep;
+    /**
+     * Apply workflow-level options (cache, services, matrix) to jobs.
+     */
+    private applyWorkflowOptions;
+}
+export default GitHubActionsTarget;

package/dist/target.js

@@ -0,0 +1,366 @@
+/**
+ * GitHub Actions Export Target
+ *
+ * Generates .github/workflows/<name>.yml from a Flow Weaver CI/CD workflow.
+ * No FW runtime dependency — outputs native GitHub Actions YAML.
+ *
+ * Mapping:
+ * - FW Node → GitHub Actions step (uses: or run:)
+ * - FW [job: "name"] → GitHub Actions job
+ * - FW @path → job `needs:` dependencies
+ * - FW @secret → ${{ secrets.NAME }}
+ * - FW @cache → actions/cache@v4
+ * - FW @artifact → actions/upload-artifact@v4 / actions/download-artifact@v4
+ * - FW @trigger → `on:` event configuration
+ */
+import { stringify as yamlStringify } from 'yaml';
+import { isCICDWorkflow } from '@synergenius/flow-weaver/deployment';
+import { BaseCICDTarget, } from '@synergenius/flow-weaver/deployment';
+import { parseWorkflow } from '@synergenius/flow-weaver/api';
+import * as path from 'path';
+export class GitHubActionsTarget extends BaseCICDTarget {
+    name = 'github-actions';
+    description = 'GitHub Actions workflow YAML (.github/workflows/)';
+    deploySchema = {
+        runner: { type: 'string', description: 'GitHub runner label', default: 'ubuntu-latest' },
+    };
+    nodeTypeDeploySchema = {
+        action: { type: 'string', description: 'GitHub Action uses: value (e.g. actions/checkout@v4)' },
+        with: { type: 'string', description: 'JSON object for with: parameters' },
+        label: { type: 'string', description: 'Step display name' },
+    };
+    async generate(options) {
+        const filePath = path.resolve(options.sourceFile);
+        const outputDir = path.resolve(options.outputDir);
+        // Parse the workflow file to get AST
+        const parseResult = await parseWorkflow(filePath, { nodeTypesOnly: false });
+        if (parseResult.errors.length > 0) {
+            throw new Error(`Parse errors: ${parseResult.errors.join('; ')}`);
+        }
+        const allWorkflows = parseResult.allWorkflows || [];
+        const targetWorkflows = options.workflowName
+            ? allWorkflows.filter((w) => w.name === options.workflowName || w.functionName === options.workflowName)
+            : allWorkflows.filter((w) => isCICDWorkflow(w));
+        if (targetWorkflows.length === 0) {
+            throw new Error('No CI/CD workflows found. Ensure workflow has CI/CD annotations (@secret, @runner, @trigger, [job:], etc.)');
+        }
+        const files = [];
+        for (const ast of targetWorkflows) {
+            // Build job graph
+            const jobs = this.buildJobGraph(ast);
+            // Resolve secrets
+            this.resolveJobSecrets(jobs, ast, (name) => `\${{ secrets.${name} }}`);
+            // Inject artifacts
+            const artifacts = ast.options?.cicd?.artifacts || [];
+            this.injectArtifactSteps(jobs, artifacts);
+            // Apply cache, services, matrix from workflow options
+            this.applyWorkflowOptions(jobs, ast);
+            // Generate YAML
+            const yamlContent = this.renderWorkflowYAML(ast, jobs);
+            // Output path: .github/workflows/<name>.yml
+            const yamlFileName = `.github/workflows/${ast.functionName}.yml`;
+            files.push(this.createFile(outputDir, yamlFileName, yamlContent, 'config'));
+            // Generate secrets doc if secrets exist
+            const secrets = ast.options?.cicd?.secrets || [];
+            if (secrets.length > 0) {
+                const secretsDoc = this.generateSecretsDoc(secrets, 'github-actions');
+                files.push(this.createFile(outputDir, 'SECRETS_SETUP.md', secretsDoc, 'other'));
+            }
+        }
+        return {
+            files,
+            target: this.name,
+            workflowName: options.displayName || targetWorkflows[0].name,
+            entryPoint: files[0].relativePath,
+        };
+    }
+    getDeployInstructions(_artifacts) {
+        return {
+            title: 'Deploy GitHub Actions Workflow',
+            prerequisites: [
+                'GitHub repository',
+                'Repository secrets configured (see SECRETS_SETUP.md)',
+            ],
+            steps: [
+                'Copy the .github/workflows/ directory to your repository root',
+                'Configure required secrets in GitHub (Settings > Secrets > Actions)',
+                'Push to trigger the workflow',
+            ],
+            localTestSteps: [
+                'Install act: brew install act (or see https://github.com/nektos/act)',
+                'Run locally: act push',
+            ],
+            links: [
+                { label: 'GitHub Actions Docs', url: 'https://docs.github.com/en/actions' },
+                { label: 'act - Local Testing', url: 'https://github.com/nektos/act' },
+            ],
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private: YAML Rendering
+    // ---------------------------------------------------------------------------
+    renderWorkflowYAML(ast, jobs) {
+        const doc = {};
+        // name
+        doc.name = ast.name;
+        // on: triggers
+        doc.on = this.renderTriggers(ast.options?.cicd?.triggers || []);
+        // concurrency
+        if (ast.options?.cicd?.concurrency) {
+            doc.concurrency = {
+                group: ast.options.cicd.concurrency.group,
+                'cancel-in-progress': ast.options.cicd.concurrency.cancelInProgress ?? false,
+            };
+        }
+        // jobs
+        const jobsObj = {};
+        for (const job of jobs) {
+            jobsObj[job.id] = this.renderJob(job, ast);
+        }
+        doc.jobs = jobsObj;
+        return yamlStringify(doc, {
+            lineWidth: 120,
+            defaultStringType: 'PLAIN',
+            defaultKeyType: 'PLAIN',
+        });
+    }
+    renderTriggers(triggers) {
+        if (triggers.length === 0) {
+            // Default: manual dispatch
+            return { workflow_dispatch: {} };
+        }
+        const on = {};
+        for (const trigger of triggers) {
+            switch (trigger.type) {
+                case 'push': {
+                    const pushConfig = {};
+                    if (trigger.branches)
+                        pushConfig.branches = trigger.branches;
+                    if (trigger.paths)
+                        pushConfig.paths = trigger.paths;
+                    if (trigger.pathsIgnore)
+                        pushConfig['paths-ignore'] = trigger.pathsIgnore;
+                    on.push = Object.keys(pushConfig).length > 0 ? pushConfig : null;
+                    break;
+                }
+                case 'pull_request': {
+                    const prConfig = {};
+                    if (trigger.branches)
+                        prConfig.branches = trigger.branches;
+                    if (trigger.types)
+                        prConfig.types = trigger.types;
+                    if (trigger.paths)
+                        prConfig.paths = trigger.paths;
+                    if (trigger.pathsIgnore)
+                        prConfig['paths-ignore'] = trigger.pathsIgnore;
+                    on.pull_request = Object.keys(prConfig).length > 0 ? prConfig : null;
+                    break;
+                }
+                case 'schedule':
+                    on.schedule = on.schedule || [];
+                    if (trigger.cron) {
+                        on.schedule.push({ cron: trigger.cron });
+                    }
+                    break;
+                case 'dispatch':
+                    on.workflow_dispatch = trigger.inputs
+                        ? { inputs: trigger.inputs }
+                        : {};
+                    break;
+                case 'tag': {
+                    // Tags are a filter on push
+                    if (!on.push)
+                        on.push = {};
+                    on.push.tags = trigger.pattern
+                        ? [trigger.pattern]
+                        : ['*'];
+                    break;
+                }
+            }
+        }
+        return on;
+    }
+    renderJob(job, ast) {
+        const jobObj = {};
+        // runs-on
+        jobObj['runs-on'] = job.runner || 'ubuntu-latest';
+        // needs
+        if (job.needs.length > 0) {
+            jobObj.needs = job.needs;
+        }
+        // environment
+        if (job.environment) {
+            const envConfig = ast.options?.cicd?.environments?.find((e) => e.name === job.environment);
+            if (envConfig?.url) {
+                jobObj.environment = { name: job.environment, url: envConfig.url };
+            }
+            else {
+                jobObj.environment = job.environment;
+            }
+        }
+        // matrix strategy
+        if (job.matrix) {
+            const strategy = {};
+            if (job.matrix.dimensions) {
+                strategy.matrix = { ...job.matrix.dimensions };
+            }
+            if (job.matrix.include) {
+                strategy.matrix = strategy.matrix || {};
+                strategy.matrix.include = job.matrix.include;
+            }
+            if (job.matrix.exclude) {
+                strategy.matrix = strategy.matrix || {};
+                strategy.matrix.exclude = job.matrix.exclude;
+            }
+            jobObj.strategy = strategy;
+        }
+        // services
+        if (job.services && job.services.length > 0) {
+            const services = {};
+            for (const svc of job.services) {
+                const svcObj = { image: svc.image };
+                if (svc.ports)
+                    svcObj.ports = svc.ports;
+                if (svc.env)
+                    svcObj.env = svc.env;
+                services[svc.name] = svcObj;
+            }
+            jobObj.services = services;
+        }
+        // steps
+        const steps = [];
+        // Download artifacts first
+        if (job.downloadArtifacts && job.downloadArtifacts.length > 0) {
+            for (const artifactName of job.downloadArtifacts) {
+                const artifact = ast.options?.cicd?.artifacts?.find((a) => a.name === artifactName);
+                steps.push({
+                    uses: 'actions/download-artifact@v4',
+                    with: {
+                        name: artifactName,
+                        ...(artifact?.path && { path: artifact.path }),
+                    },
+                });
+            }
+        }
+        // Cache step
+        if (job.cache) {
+            steps.push(this.renderCacheStep(job.cache));
+        }
+        // Node steps
+        for (const step of job.steps) {
+            steps.push(this.renderStep(step));
+        }
+        // Upload artifacts last
+        if (job.uploadArtifacts && job.uploadArtifacts.length > 0) {
+            for (const artifact of job.uploadArtifacts) {
+                const uploadStep = {
+                    uses: 'actions/upload-artifact@v4',
+                    with: {
+                        name: artifact.name,
+                        path: artifact.path,
+                    },
+                };
+                if (artifact.retention) {
+                    uploadStep.with['retention-days'] = artifact.retention;
+                }
+                steps.push(uploadStep);
+            }
+        }
+        jobObj.steps = steps;
+        return jobObj;
+    }
+    renderStep(step) {
+        const mapping = this.resolveActionMapping(step, 'github-actions');
+        if (mapping?.githubAction) {
+            // Use a pre-built action
+            const stepObj = {
+                name: mapping.label || step.name,
+                uses: mapping.githubAction,
+            };
+            if (mapping.githubWith) {
+                stepObj.with = { ...mapping.githubWith };
+            }
+            if (step.env && Object.keys(step.env).length > 0) {
+                stepObj.env = step.env;
+            }
+            return stepObj;
+        }
+        if (mapping?.gitlabScript) {
+            // Known node type but no GitHub action — use run:
+            const stepObj = {
+                name: mapping.label || step.name,
+                run: mapping.gitlabScript.join('\n'),
+            };
+            if (step.env && Object.keys(step.env).length > 0) {
+                stepObj.env = step.env;
+            }
+            return stepObj;
+        }
+        // Unknown node type — generate TODO placeholder
+        const stepObj = {
+            name: step.name,
+            run: `echo "TODO: Implement step '${step.id}' (node type: ${step.nodeType})"`,
+        };
+        if (step.env && Object.keys(step.env).length > 0) {
+            stepObj.env = step.env;
+        }
+        return stepObj;
+    }
+    renderCacheStep(cache) {
+        const cacheConfig = {};
+        switch (cache.strategy) {
+            case 'npm':
+                cacheConfig.path = cache.path || '~/.npm';
+                cacheConfig.key = cache.key
+                    ? `npm-\${{ hashFiles('${cache.key}') }}`
+                    : "npm-${{ hashFiles('**/package-lock.json') }}";
+                break;
+            case 'pip':
+                cacheConfig.path = cache.path || '~/.cache/pip';
+                cacheConfig.key = cache.key
+                    ? `pip-\${{ hashFiles('${cache.key}') }}`
+                    : "pip-${{ hashFiles('**/requirements.txt') }}";
+                break;
+            default:
+                cacheConfig.path = cache.path || '.cache';
+                cacheConfig.key = cache.key
+                    ? `${cache.strategy}-\${{ hashFiles('${cache.key}') }}`
+                    : `${cache.strategy}-\${{ github.sha }}`;
+        }
+        return {
+            name: `Cache ${cache.strategy}`,
+            uses: 'actions/cache@v4',
+            with: cacheConfig,
+        };
+    }
+    /**
+     * Apply workflow-level options (cache, services, matrix) to jobs.
+     */
+    applyWorkflowOptions(jobs, ast) {
+        const cicd = ast.options?.cicd;
+        if (!cicd)
+            return;
+        // Apply cache to all jobs (or first job if only one)
+        if (cicd.caches && cicd.caches.length > 0) {
+            const targetJobs = jobs.length === 1 ? jobs : jobs.filter((j) => j.needs.length === 0);
+            for (const job of targetJobs) {
+                job.cache = cicd.caches[0]; // Primary cache
+            }
+        }
+        // Apply services to all jobs
+        if (cicd.services && cicd.services.length > 0) {
+            for (const job of jobs) {
+                job.services = cicd.services;
+            }
+        }
+        // Apply matrix to first job (or specific jobs based on convention)
+        if (cicd.matrix) {
+            // Apply to all jobs that don't have dependencies (root jobs)
+            const rootJobs = jobs.filter((j) => j.needs.length === 0);
+            for (const job of rootJobs) {
+                job.matrix = cicd.matrix;
+            }
+        }
+    }
+}
+export default GitHubActionsTarget;

package/flowweaver.manifest.json

@@ -0,0 +1,15 @@
+{
+  "manifestVersion": 1,
+  "name": "@synergenius/flowweaver-pack-github-actions",
+  "version": "0.1.1",
+  "nodeTypes": [],
+  "workflows": [],
+  "patterns": [],
+  "exportTargets": [
+    {
+      "name": "github-actions",
+      "description": "GitHub Actions CI/CD pipeline generation",
+      "file": "dist/target.js"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@synergenius/flowweaver-pack-github-actions",
+  "version": "0.1.1",
+  "description": "GitHub Actions CI/CD export target for Flow Weaver",
+  "keywords": [
+    "flowweaver-marketplace-pack",
+    "flow-weaver",
+    "github-actions",
+    "cicd"
+  ],
+  "flowWeaver": {
+    "type": "marketplace-pack",
+    "engineVersion": ">=0.14.0",
+    "categories": [
+      "deployment",
+      "cicd"
+    ]
+  },
+  "peerDependencies": {
+    "@synergenius/flow-weaver": ">=0.14.0"
+  },
+  "dependencies": {
+    "yaml": "^2.8.0"
+  },
+  "main": "./dist/target.js",
+  "types": "./dist/target.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "flowweaver.manifest.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@synergenius/flow-weaver": "^0.14.2",
+    "@types/node": "^20.0.0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/synergenius-fw/flowweaver-pack-github-actions.git"
+  }
+}