pipecraft 0.0.0-releaseit → 0.26.0

package/dist/templates/actions/manage-branch.yml.tpl.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Manage Branch Action Template
+ *
+ * Generates a composite action for branch operations including fast-forward merges,
+ * branch creation, and deletion. Core utility for trunk-based development workflows.
+ *
+ * @module templates/actions/manage-branch.yml.tpl
+ */
 import { PinionContext } from '@featherscloud/pinion';
+/**
+ * Generator entry point for manage-branch composite action.
+ *
+ * @param {PinionContext} ctx - Pinion generator context
+ * @returns {Promise<PinionContext>} Updated context after file generation
+ */
 export declare const generate: (ctx: PinionContext) => Promise<any>;
 //# sourceMappingURL=manage-branch.yml.tpl.d.ts.map

package/dist/templates/actions/manage-branch.yml.tpl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manage-branch.yml.tpl.d.ts","sourceRoot":"","sources":["../../../src/templates/actions/manage-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA0B,MAAM,uBAAuB,CAAA;AAyH7E,eAAO,MAAM,QAAQ,GAAI,KAAK,aAAa,iBAUwD,CAAA"}
+{"version":3,"file":"manage-branch.yml.tpl.d.ts","sourceRoot":"","sources":["../../../src/templates/actions/manage-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAA0B,MAAM,uBAAuB,CAAA;AA+H7E;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,aAAa,iBAUwD,CAAA"}

package/dist/templates/actions/manage-branch.yml.tpl.js

@@ -1,7 +1,21 @@
+/**
+ * Manage Branch Action Template
+ *
+ * Generates a composite action for branch operations including fast-forward merges,
+ * branch creation, and deletion. Core utility for trunk-based development workflows.
+ *
+ * @module templates/actions/manage-branch.yml.tpl
+ */
 import { toFile, renderTemplate } from '@featherscloud/pinion';
 import fs from 'fs';
 import dedent from 'dedent';
-// Template for the Branch Management GitHub Action
+import { logger } from '../../utils/logger.js';
+/**
+ * Generates the manage-branch composite action YAML content.
+ *
+ * @param {any} ctx - Context (not currently used)
+ * @returns {string} YAML content for the composite action
+ */
 const branchActionTemplate = (ctx) => {
     return dedent `name: 'Branch Management'
     description: 'Manage branches (fast-forward, create, delete)'
@@ -117,13 +131,19 @@ const branchActionTemplate = (ctx) => {
               echo "❌ \${{ steps.branch-action.outputs.message }}"
             fi`;
 };
+/**
+ * Generator entry point for manage-branch composite action.
+ *
+ * @param {PinionContext} ctx - Pinion generator context
+ * @returns {Promise<PinionContext>} Updated context after file generation
+ */
 export const generate = (ctx) => Promise.resolve(ctx)
     .then((ctx) => {
     // Check if file exists to determine merge status
     const filePath = '.github/actions/manage-branch/action.yml';
     const exists = fs.existsSync(filePath);
     const status = exists ? '🔄 Merged with existing' : '📝 Created new';
-    console.log(`${status} ${filePath}`);
+    logger.verbose(`${status} ${filePath}`);
     return ctx;
 })
     .then(renderTemplate(branchActionTemplate, toFile('.github/actions/manage-branch/action.yml')));

package/dist/templates/actions/manage-branch.yml.tpl.js.map

@@ -1 +1 @@
-{"version":3,"file":"manage-branch.yml.tpl.js","sourceRoot":"","sources":["../../../src/templates/actions/manage-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,MAAM,MAAM,QAAQ,CAAA;AAE3B,mDAAmD;AACnD,MAAM,oBAAoB,GAAG,CAAC,GAAQ,EAAE,EAAE;IACxC,OAAO,MAAM,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAgHA,CAAA;AACf,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAkB,EAAE,EAAE,CAC7C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;KACjB,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;IACZ,iDAAiD;IACjD,MAAM,QAAQ,GAAG,0CAA0C,CAAA;IAC3D,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,gBAAgB,CAAA;IACpE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC,CAAA;IACpC,OAAO,GAAG,CAAA;AACZ,CAAC,CAAC;KACD,IAAI,CAAC,cAAc,CAAC,oBAAoB,EAAE,MAAM,CAAC,0CAA0C,CAAC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"manage-branch.yml.tpl.js","sourceRoot":"","sources":["../../../src/templates/actions/manage-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAiB,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,CAAC,GAAQ,EAAE,EAAE;IACxC,OAAO,MAAM,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAgHA,CAAA;AACf,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAkB,EAAE,EAAE,CAC7C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;KACjB,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;IACZ,iDAAiD;IACjD,MAAM,QAAQ,GAAG,0CAA0C,CAAA;IAC3D,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,gBAAgB,CAAA;IACpE,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC,CAAA;IACvC,OAAO,GAAG,CAAA;AACZ,CAAC,CAAC;KACD,IAAI,CAAC,cAAc,CAAC,oBAAoB,EAAE,MAAM,CAAC,0CAA0C,CAAC,CAAC,CAAC,CAAA"}

package/dist/templates/actions/promote-branch.yml.tpl.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Promote Branch Action Template
+ *
+ * Generates a composite action that promotes code from one branch to another via
+ * temporary branch and pull request. Handles auto-merge and cleanup for trunk flow.
+ *
+ * @module templates/actions/promote-branch.yml.tpl
+ */
 import { PinionContext } from '@featherscloud/pinion';
+/**
+ * Generator entry point for promote-branch composite action.
+ *
+ * @param {PinionContext} ctx - Pinion generator context
+ * @returns {Promise<PinionContext>} Updated context after file generation
+ */
 export declare const generate: (ctx: PinionContext) => Promise<any>;
 //# sourceMappingURL=promote-branch.yml.tpl.d.ts.map

package/dist/templates/actions/promote-branch.yml.tpl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promote-branch.yml.tpl.d.ts","sourceRoot":"","sources":["../../../src/templates/actions/promote-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA0B,MAAM,uBAAuB,CAAA;AAiW7E,eAAO,MAAM,QAAQ,GAAI,KAAK,aAAa,iBAUgE,CAAA"}
+{"version":3,"file":"promote-branch.yml.tpl.d.ts","sourceRoot":"","sources":["../../../src/templates/actions/promote-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAA0B,MAAM,uBAAuB,CAAA;AA8X7E;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,aAAa,iBAUgE,CAAA"}

package/dist/templates/actions/promote-branch.yml.tpl.js

@@ -1,8 +1,21 @@
+/**
+ * Promote Branch Action Template
+ *
+ * Generates a composite action that promotes code from one branch to another via
+ * temporary branch and pull request. Handles auto-merge and cleanup for trunk flow.
+ *
+ * @module templates/actions/promote-branch.yml.tpl
+ */
 import { toFile, renderTemplate } from '@featherscloud/pinion';
 import fs from 'fs';
 import dedent from 'dedent';
-// Template for the Promote Branch GitHub Action
-// This action handles branch promotions via temporary branches + PRs
+import { logger } from '../../utils/logger.js';
+/**
+ * Generates the promote-branch composite action YAML content.
+ *
+ * @param {any} ctx - Context (not currently used)
+ * @returns {string} YAML content for the composite action
+ */
 const promoteBranchActionTemplate = (ctx) => {
     return dedent `name: 'Promote Branch'
     description: 'Promote code from source to target branch via temporary branch + PR'
@@ -17,6 +30,10 @@ const promoteBranchActionTemplate = (ctx) => {
         description: 'Version being promoted (e.g., v1.2.3, auto-detected from git tags if not provided)'
         required: false
         default: ''
+      run_number:
+        description: 'The original run number from develop branch for traceability'
+        required: false
+        default: ''
       configPath:
         description: 'Path to .pipecraftrc.json config file'
         required: false
@@ -296,6 +313,14 @@ const promoteBranchActionTemplate = (ctx) => {
             echo "✅ Fast-forwarded \$TARGET to \$COMMIT_SHA"
             echo "📝 PR will be closed automatically for audit trail"
 
+        - name: Wait for Branch to Propagate
+          if: steps.read-config.outputs.autoMerge == 'true'
+          shell: bash
+          run: |
+            echo "⏳ Waiting 5 seconds for branch update to propagate..."
+            sleep 5
+            echo "✅ Branch should be fully propagated"
+
         - name: Trigger Pipeline Workflow on Target Branch
           if: steps.read-config.outputs.autoMerge == 'true'
           shell: bash
@@ -304,15 +329,27 @@ const promoteBranchActionTemplate = (ctx) => {
           run: |
             TARGET="\${{ steps.read-config.outputs.targetBranch }}"
             VERSION="\${{ steps.get-version.outputs.version }}"
+            RUN_NUMBER="\${{ inputs.run_number }}"
 
-            echo "🔄 Triggering pipeline workflow on \$TARGET branch with version \$VERSION"
+            # Get the exact commit SHA that was just pushed to target branch
+            COMMIT_SHA=$(git rev-parse \$TARGET)
+            echo "🔄 Triggering pipeline workflow on \$TARGET branch"
+            echo "   Version: \$VERSION"
+            echo "   Commit SHA: \$COMMIT_SHA"
 
             # Trigger the pipeline workflow on the target branch
             # This is necessary because GITHUB_TOKEN pushes don't trigger workflows by default
-            # Pass the version so the run name is descriptive
-            gh workflow run pipeline.yml --ref "\$TARGET" --field version="\$VERSION"
+            # Pass the exact commit SHA to ensure the workflow checks out the correct commit
+            # (avoids race conditions from GitHub's eventual consistency)
+            WORKFLOW_ARGS=(--ref "\$TARGET" --field version="\$VERSION" --field commitSha="\$COMMIT_SHA")
+            if [ -n "\$RUN_NUMBER" ]; then
+              WORKFLOW_ARGS+=(--field run_number="\$RUN_NUMBER")
+              echo "   Run number: \$RUN_NUMBER (for traceability)"
+            fi
+
+            gh workflow run pipeline.yml "\${WORKFLOW_ARGS[@]}"
 
-            echo "✅ Pipeline workflow triggered on \$TARGET with version \$VERSION"
+            echo "✅ Pipeline workflow triggered on \$TARGET with version \$VERSION at commit \$COMMIT_SHA"
 
         - name: Close PR and Delete Branch
           if: steps.read-config.outputs.autoMerge == 'true'
@@ -349,13 +386,19 @@ const promoteBranchActionTemplate = (ctx) => {
             # Note: Fast-forward merge happens in separate step if autoMerge is enabled
   `;
 };
+/**
+ * Generator entry point for promote-branch composite action.
+ *
+ * @param {PinionContext} ctx - Pinion generator context
+ * @returns {Promise<PinionContext>} Updated context after file generation
+ */
 export const generate = (ctx) => Promise.resolve(ctx)
     .then((ctx) => {
     // Check if file exists to determine merge status
     const filePath = '.github/actions/promote-branch/action.yml';
     const exists = fs.existsSync(filePath);
     const status = exists ? '🔄 Merged with existing' : '📝 Created new';
-    console.log(`${status} ${filePath}`);
+    logger.verbose(`${status} ${filePath}`);
     return ctx;
 })
     .then(renderTemplate(promoteBranchActionTemplate, toFile('.github/actions/promote-branch/action.yml')));

package/dist/templates/actions/promote-branch.yml.tpl.js.map

@@ -1 +1 @@
-{"version":3,"file":"promote-branch.yml.tpl.js","sourceRoot":"","sources":["../../../src/templates/actions/promote-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,MAAM,MAAM,QAAQ,CAAA;AAE3B,gDAAgD;AAChD,qEAAqE;AACrE,MAAM,2BAA2B,GAAG,CAAC,GAAQ,EAAE,EAAE;IAC/C,OAAO,MAAM,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuVZ,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAkB,EAAE,EAAE,CAC7C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;KACjB,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;IACZ,iDAAiD;IACjD,MAAM,QAAQ,GAAG,2CAA2C,CAAA;IAC5D,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,gBAAgB,CAAA;IACpE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC,CAAA;IACpC,OAAO,GAAG,CAAA;AACZ,CAAC,CAAC;KACD,IAAI,CAAC,cAAc,CAAC,2BAA2B,EAAE,MAAM,CAAC,2CAA2C,CAAC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"promote-branch.yml.tpl.js","sourceRoot":"","sources":["../../../src/templates/actions/promote-branch.yml.tpl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAiB,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,2BAA2B,GAAG,CAAC,GAAQ,EAAE,EAAE;IAC/C,OAAO,MAAM,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+WZ,CAAA;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAkB,EAAE,EAAE,CAC7C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;KACjB,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;IACZ,iDAAiD;IACjD,MAAM,QAAQ,GAAG,2CAA2C,CAAA;IAC5D,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,gBAAgB,CAAA;IACpE,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC,CAAA;IACvC,OAAO,GAAG,CAAA;AACZ,CAAC,CAAC;KACD,IAAI,CAAC,cAAc,CAAC,2BAA2B,EAAE,MAAM,CAAC,2CAA2C,CAAC,CAAC,CAAC,CAAA"}

package/dist/templates/workflows/pipeline-path-based.yml.tpl.d.ts

@@ -1,3 +1,67 @@
+/**
+ * Path-Based Pipeline Template Generator
+ *
+ * The core template that generates the main CI/CD pipeline workflow for PipeCraft.
+ * This is the most complex template in the system, responsible for creating a
+ * GitHub Actions workflow that orchestrates the entire trunk-based development flow.
+ *
+ * ## Key Responsibilities
+ *
+ * 1. **Change Detection**: Generates jobs to detect which domains (api, web, libs, etc.) changed
+ * 2. **Test Execution**: Creates domain-specific test jobs based on changes
+ * 3. **Version Management**: Integrates semantic versioning for staging/production branches
+ * 4. **Branch Promotion**: Auto-promotes code through branch flow (develop → staging → main)
+ * 5. **User Job Preservation**: Maintains user-added custom jobs during regeneration
+ * 6. **Comment Preservation**: Retains user comments when updating workflows
+ *
+ * ## Intelligent Merging
+ *
+ * The generator distinguishes between:
+ * - **Pipecraft-owned jobs**: `changes`, `version`, `tag`, `promote`, `release`, `test-*`, `deploy-*`
+ * - **User jobs**: Any jobs not owned by Pipecraft
+ *
+ * During regeneration:
+ * - Pipecraft jobs are completely replaced with template versions
+ * - User jobs are preserved exactly as-is
+ * - User comments are maintained
+ * - Job order is intelligently managed (Pipecraft jobs first, then user jobs)
+ *
+ * ## Architecture
+ *
+ * Uses AST-based path operations for surgical YAML manipulation:
+ * - Parse existing workflow into AST
+ * - Apply precise path-based operations
+ * - Preserve formatting and comments
+ * - Rebuild YAML maintaining structure
+ *
+ * @module templates/workflows/pipeline-path-based.yml.tpl
+ *
+ * @example
+ * ```typescript
+ * import { generate } from './templates/workflows/pipeline-path-based.yml.tpl.js'
+ *
+ * // Initial generation
+ * await generate({
+ *   cwd: '/path/to/project',
+ *   branchFlow: ['develop', 'staging', 'main'],
+ *   domains: {
+ *     api: { paths: ['src/api/**'], test: true },
+ *     web: { paths: ['src/web/**'], test: true }
+ *   }
+ * })
+ *
+ * // Incremental update (preserves user jobs)
+ * await generate({
+ *   cwd: '/path/to/project',
+ *   existingPipeline: parsedYAML,
+ *   existingPipelineContent: rawYAMLString,
+ *   branchFlow: ['develop', 'staging', 'main'],
+ *   domains: { ... }
+ * })
+ * ```
+ *
+ * @see {@link module:utils/ast-path-operations} for YAML manipulation details
+ */
 import { PinionContext } from '@featherscloud/pinion';
 /**
  * Create path-based pipeline content
@@ -7,7 +71,56 @@ export declare const createPathBasedPipeline: (ctx: any) => {
     mergeStatus: string;
 };
 /**
- * Main export - path-based pipeline generator
+ * Main pipeline generator entry point.
+ *
+ * Generates the complete GitHub Actions pipeline workflow with intelligent
+ * merging of existing user customizations.
+ *
+ * @param {PinionContext & { existingPipeline?: any, outputPipelinePath?: string }} ctx - Generator context
+ * @param {any} [ctx.existingPipeline] - Parsed existing pipeline YAML for merging
+ * @param {string} [ctx.existingPipelineContent] - Raw existing pipeline content for comment preservation
+ * @param {string} [ctx.outputPipelinePath] - Custom output path (default: .github/workflows/pipeline.yml)
+ * @param {string[]} ctx.branchFlow - Branch flow sequence (e.g., ['develop', 'staging', 'main'])
+ * @param {Record<string, DomainConfig>} ctx.domains - Domain configurations for change detection
+ * @param {string} [ctx.ciProvider] - CI provider ('github' or 'gitlab')
+ * @param {string} [ctx.mergeStrategy] - Merge strategy ('fast-forward' or 'merge')
+ * @returns {Promise<PinionContext>} Updated context with generated YAML
+ *
+ * @throws {Error} If pipeline file cannot be written
+ * @throws {Error} If existing pipeline cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * // Generate new pipeline
+ * await generate({
+ *   cwd: '/path/to/project',
+ *   branchFlow: ['develop', 'main'],
+ *   domains: {
+ *     api: { paths: ['src/api/**'], test: true }
+ *   }
+ * })
+ *
+ * // Update existing pipeline (preserves user jobs)
+ * const existing = parseDocument(readFileSync('pipeline.yml', 'utf8'))
+ * await generate({
+ *   cwd: '/path/to/project',
+ *   existingPipeline: existing,
+ *   existingPipelineContent: readFileSync('pipeline.yml', 'utf8'),
+ *   branchFlow: ['develop', 'staging', 'main'],
+ *   domains: { ... }
+ * })
+ * ```
+ *
+ * @note The generator performs these steps:
+ * 1. Calls `createPathBasedPipeline()` to build the workflow
+ * 2. Logs merge status (new vs. merged)
+ * 3. Writes the final YAML to the output path
+ *
+ * The heavy lifting is done by `createPathBasedPipeline()` which handles:
+ * - Job generation based on domains and branch flow
+ * - User job preservation and merging
+ * - Comment preservation from existing pipeline
+ * - Intelligent job ordering
  */
 export declare const generate: (ctx: PinionContext & {
     existingPipeline?: any;

package/dist/templates/workflows/pipeline-path-based.yml.tpl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-path-based.yml.tpl.d.ts","sourceRoot":"","sources":["../../../src/templates/workflows/pipeline-path-based.yml.tpl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA0B,MAAM,uBAAuB,CAAA;AA8D7E;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,GAAG;;;CA2lB/C,CAAA;AAcD;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,aAAa,GAAG;IAAE,gBAAgB,CAAC,EAAE,GAAG,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,iBAoB/F,CAAA"}
+{"version":3,"file":"pipeline-path-based.yml.tpl.d.ts","sourceRoot":"","sources":["../../../src/templates/workflows/pipeline-path-based.yml.tpl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,EAAE,aAAa,EAA0B,MAAM,uBAAuB,CAAA;AAsD7E;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,GAAG;;;CAm5B/C,CAAA;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,aAAa,GAAG;IAAE,gBAAgB,CAAC,EAAE,GAAG,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,iBAoB/F,CAAA"}