@synergenius/flowweaver-pack-gitlab-ci 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,63 @@
+# @synergenius/flowweaver-pack-gitlab-ci
+
+GitLab CI/CD export target for [Flow Weaver](https://github.com/synergenius-fw/flow-weaver).
+
+Generates native `.gitlab-ci.yml` files from Flow Weaver CI/CD workflows. No runtime dependency — outputs pure GitLab CI YAML.
+
+## Installation
+
+```bash
+npm install @synergenius/flowweaver-pack-gitlab-ci
+```
+
+This package is a **marketplace pack** — once installed, Flow Weaver automatically discovers it via `createTargetRegistry()`.
+
+## Usage
+
+### CLI
+
+```bash
+# Export a CI/CD workflow as GitLab CI YAML
+npx flow-weaver export my-pipeline.ts --target gitlab-ci
+```
+
+### Programmatic
+
+```typescript
+import { createTargetRegistry } from '@synergenius/flow-weaver/deployment';
+
+const registry = await createTargetRegistry(process.cwd());
+const gitlab = registry.get('gitlab-ci');
+
+const artifacts = await gitlab.generate({
+  sourceFile: 'my-pipeline.ts',
+  workflowName: 'myPipeline',
+  displayName: 'my-pipeline',
+  outputDir: './dist/gitlab-ci',
+});
+```
+
+## What it generates
+
+- `.gitlab-ci.yml` — Native GitLab CI configuration
+- `SECRETS_SETUP.md` — Documentation for required CI/CD variables
+
+### Mapping
+
+| Flow Weaver | GitLab CI |
+|-------------|-----------|
+| `[job: "name"]` annotation | Job with `stage:` |
+| `@path` dependencies | Stage ordering |
+| `@secret NAME` | `$NAME` variable |
+| `@cache` | Native `cache:` keyword |
+| `@artifact` | Native `artifacts:` keyword |
+| `@trigger push` | `rules:` conditions |
+| `@environment` | `environment:` with optional `when: manual` |
+
+## Requirements
+
+- `@synergenius/flow-weaver` >= 0.14.0
+
+## License
+
+See [LICENSE](./LICENSE).

package/dist/target.d.ts

@@ -42,8 +42,15 @@ export declare class GitLabCITarget extends BaseCICDTarget {
     getDeployInstructions(_artifacts: ExportArtifacts): DeployInstructions;
     private renderPipelineYAML;
     /**
-     * Derive stages from job dependency order.
-     * Jobs with no deps → stage 1, jobs depending on stage 1 → stage 2, etc.
+     * Derive stages from @stage annotations or job dependency depth.
+     *
+     * When @stage annotations exist, jobs are grouped into named stages:
+     * - Jobs with an explicit `stage` field (set by buildJobGraph from @stage/@job)
+     *   use that stage name directly.
+     * - The returned list preserves @stage declaration order.
+     *
+     * Without @stage annotations, falls back to using each job ID as its own stage
+     * (ordered by dependency).
      */
     private deriveStages;
     /**

package/dist/target.js

@@ -99,14 +99,40 @@ export class GitLabCITarget extends BaseCICDTarget {
     // ---------------------------------------------------------------------------
     renderPipelineYAML(ast, jobs) {
         const doc = {};
-        // stages (derived from job dependency order)
-        const stages = this.deriveStages(jobs);
+        // include: directive (from @includes)
+        const includes = ast.options?.cicd?.includes;
+        if (includes && includes.length > 0) {
+            doc.include = includes.map(inc => {
+                switch (inc.type) {
+                    case 'local': return { local: inc.file };
+                    case 'template': return { template: inc.file };
+                    case 'remote': return { remote: inc.file };
+                    case 'project': {
+                        const obj = { project: inc.project || '', file: inc.file };
+                        if (inc.ref)
+                            obj.ref = inc.ref;
+                        return obj;
+                    }
+                    default: return { local: inc.file };
+                }
+            });
+        }
+        // stages (from @stage annotations or derived from dependency depth)
+        const stages = this.deriveStages(jobs, ast);
         doc.stages = stages;
         // Default image
         const defaultImage = this.deriveDefaultImage(ast, jobs);
         if (defaultImage) {
             doc.default = { image: defaultImage };
         }
+        // Workflow-level variables
+        if (ast.options?.cicd?.variables && Object.keys(ast.options.cicd.variables).length > 0) {
+            doc.variables = { ...ast.options.cicd.variables };
+        }
+        // Workflow-level before_script
+        if (ast.options?.cicd?.beforeScript && ast.options.cicd.beforeScript.length > 0) {
+            doc.before_script = ast.options.cicd.beforeScript;
+        }
         // Workflow-level rules (from triggers)
         const rules = this.renderWorkflowRules(ast.options?.cicd?.triggers || []);
         if (rules.length > 0) {
@@ -123,29 +149,32 @@ export class GitLabCITarget extends BaseCICDTarget {
         });
     }
     /**
-     * Derive stages from job dependency order.
-     * Jobs with no deps → stage 1, jobs depending on stage 1 → stage 2, etc.
+     * Derive stages from @stage annotations or job dependency depth.
+     *
+     * When @stage annotations exist, jobs are grouped into named stages:
+     * - Jobs with an explicit `stage` field (set by buildJobGraph from @stage/@job)
+     *   use that stage name directly.
+     * - The returned list preserves @stage declaration order.
+     *
+     * Without @stage annotations, falls back to using each job ID as its own stage
+     * (ordered by dependency).
      */
-    deriveStages(jobs) {
-        const stages = [];
-        const assigned = new Map();
-        // Assign stages based on dependency depth
-        function getStage(jobId, jobs) {
-            if (assigned.has(jobId))
-                return assigned.get(jobId);
-            const job = jobs.find((j) => j.id === jobId);
-            if (!job || job.needs.length === 0) {
-                assigned.set(jobId, jobId);
-                return jobId;
+    deriveStages(jobs, ast) {
+        const declaredStages = ast?.options?.cicd?.stages;
+        // If @stage annotations exist, use them
+        if (declaredStages && declaredStages.length > 0) {
+            const stageNames = declaredStages.map(s => s.name);
+            // Collect any stages referenced by jobs that aren't in the declared list
+            for (const job of jobs) {
+                if (job.stage && !stageNames.includes(job.stage)) {
+                    stageNames.push(job.stage);
+                }
             }
-            // Stage is one after the latest dependency
-            const depStages = job.needs.map((dep) => getStage(dep, jobs));
-            assigned.set(jobId, jobId);
-            return jobId;
+            return stageNames;
         }
-        // Simple: use job IDs as stage names, ordered by dependency
+        // Fallback: use job IDs as stage names, ordered by dependency
+        const stages = [];
         for (const job of jobs) {
-            getStage(job.id, jobs);
             if (!stages.includes(job.id)) {
                 stages.push(job.id);
             }
@@ -215,12 +244,14 @@ export class GitLabCITarget extends BaseCICDTarget {
     }
     renderJob(job, ast, stages) {
         const jobObj = {};
-        // stage
-        jobObj.stage = job.id;
+        // extends (from @job extends=".template-name")
+        if (job.extends) {
+            jobObj.extends = job.extends;
+        }
+        // stage (use explicit stage from @stage assignment, or fall back to job ID)
+        jobObj.stage = job.stage || job.id;
         // image (from runner or default)
         if (job.runner && job.runner !== 'ubuntu-latest') {
-            // GitLab uses Docker images, not runner labels
-            // Map common GitHub runners to Docker images
             const imageMap = {
                 'ubuntu-latest': 'ubuntu:latest',
                 'ubuntu-22.04': 'ubuntu:22.04',
@@ -229,10 +260,47 @@ export class GitLabCITarget extends BaseCICDTarget {
             const image = imageMap[job.runner] || job.runner;
             jobObj.image = image;
         }
+        // tags (from @job tags or @tags)
+        if (job.tags && job.tags.length > 0) {
+            jobObj.tags = job.tags;
+        }
         // needs (for DAG mode instead of stage-based ordering)
         if (job.needs.length > 0) {
             jobObj.needs = job.needs;
         }
+        // retry (from @job retry)
+        if (job.retry !== undefined) {
+            jobObj.retry = { max: job.retry };
+        }
+        // allow_failure (from @job allow_failure)
+        if (job.allowFailure) {
+            jobObj.allow_failure = true;
+        }
+        // timeout (from @job timeout)
+        if (job.timeout) {
+            jobObj.timeout = job.timeout;
+        }
+        // rules (from @job rules)
+        if (job.rules && job.rules.length > 0) {
+            jobObj.rules = job.rules.map(rule => {
+                const ruleObj = {};
+                if (rule.if)
+                    ruleObj.if = rule.if;
+                if (rule.when)
+                    ruleObj.when = rule.when;
+                if (rule.allowFailure)
+                    ruleObj.allow_failure = true;
+                if (rule.changes)
+                    ruleObj.changes = rule.changes;
+                if (rule.variables)
+                    ruleObj.variables = rule.variables;
+                return ruleObj;
+            });
+        }
+        // coverage (from @job coverage)
+        if (job.coverage) {
+            jobObj.coverage = job.coverage;
+        }
         // environment
         if (job.environment) {
             const envConfig = ast.options?.cicd?.environments?.find((e) => e.name === job.environment);
@@ -242,7 +310,6 @@ export class GitLabCITarget extends BaseCICDTarget {
             if (envConfig?.reviewers)
                 envObj.deployment_tier = 'production';
             jobObj.environment = envObj;
-            // Protected environments require manual approval in GitLab
             if (envConfig?.reviewers) {
                 jobObj.when = 'manual';
             }
@@ -251,46 +318,54 @@ export class GitLabCITarget extends BaseCICDTarget {
         if (job.services && job.services.length > 0) {
             jobObj.services = job.services.map((svc) => {
                 const svcObj = { name: svc.image };
-                if (svc.ports) {
-                    // GitLab services expose the first port automatically
-                    // Additional port mapping needs alias
-                }
                 return svcObj;
             });
         }
-        // variables (from secrets)
+        // variables (merge secrets + job-level variables)
+        const variables = {};
         if (job.secrets.length > 0) {
-            // In GitLab, CI/CD variables are automatically available
-            // But we document them for clarity
-            const variables = {};
             for (const secret of job.secrets) {
                 variables[secret] = `$${secret}`;
             }
+        }
+        if (job.variables) {
+            Object.assign(variables, job.variables);
+        }
+        if (Object.keys(variables).length > 0) {
             jobObj.variables = variables;
         }
+        // before_script (from @job or @before_script)
+        if (job.beforeScript && job.beforeScript.length > 0) {
+            jobObj.before_script = job.beforeScript;
+        }
         // cache
         if (job.cache) {
             jobObj.cache = this.renderCache(job.cache);
         }
-        // artifacts (upload)
+        // artifacts (upload + reports)
+        const artifactsObj = {};
         if (job.uploadArtifacts && job.uploadArtifacts.length > 0) {
-            const paths = job.uploadArtifacts.map((a) => a.path);
+            artifactsObj.paths = job.uploadArtifacts.map((a) => a.path);
             const expiry = job.uploadArtifacts[0].retention
                 ? `${job.uploadArtifacts[0].retention} days`
                 : '1 week';
-            jobObj.artifacts = {
-                paths,
-                expire_in: expiry,
-            };
+            artifactsObj.expire_in = expiry;
+        }
+        if (job.reports && job.reports.length > 0) {
+            const reports = {};
+            for (const report of job.reports) {
+                reports[report.type] = report.path;
+            }
+            artifactsObj.reports = reports;
+        }
+        if (Object.keys(artifactsObj).length > 0) {
+            jobObj.artifacts = artifactsObj;
         }
         // script (the actual steps)
         const script = [];
-        // Download artifacts (GitLab handles this automatically via `needs:`)
-        // but we add a comment for clarity if explicit artifacts are expected
         if (job.downloadArtifacts && job.downloadArtifacts.length > 0) {
             script.push(`# Artifacts from: ${job.downloadArtifacts.join(', ')} (downloaded automatically via needs:)`);
         }
-        // Step scripts
         for (const step of job.steps) {
             const stepScript = this.renderStepScript(step);
             script.push(...stepScript);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flowweaver-pack-gitlab-ci",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "GitLab CI/CD export target for Flow Weaver",
   "keywords": [
     "flowweaver-marketplace-pack",
@@ -36,7 +36,7 @@
   },
   "devDependencies": {
     "typescript": "^5.0.0",
-    "@synergenius/flow-weaver": "^0.14.2",
+    "@synergenius/flow-weaver": "^0.17.3",
     "@types/node": "^20.0.0"
   },
   "license": "SEE LICENSE IN LICENSE",