pipecraft 0.0.0-releaseit → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/README.md +126 -108
  2. package/dist/cli/index.d.ts +69 -0
  3. package/dist/cli/index.d.ts.map +1 -1
  4. package/dist/cli/index.js +94 -22
  5. package/dist/cli/index.js.map +1 -1
  6. package/dist/generators/init.tpl.d.ts +70 -0
  7. package/dist/generators/init.tpl.d.ts.map +1 -1
  8. package/dist/generators/init.tpl.js +100 -8
  9. package/dist/generators/init.tpl.js.map +1 -1
  10. package/dist/generators/workflows.tpl.d.ts +86 -0
  11. package/dist/generators/workflows.tpl.d.ts.map +1 -1
  12. package/dist/generators/workflows.tpl.js +101 -9
  13. package/dist/generators/workflows.tpl.js.map +1 -1
  14. package/dist/templates/actions/calculate-version.yml.tpl.d.ts +47 -0
  15. package/dist/templates/actions/calculate-version.yml.tpl.d.ts.map +1 -1
  16. package/dist/templates/actions/calculate-version.yml.tpl.js +72 -3
  17. package/dist/templates/actions/calculate-version.yml.tpl.js.map +1 -1
  18. package/dist/templates/actions/create-pr.yml.tpl.d.ts +14 -0
  19. package/dist/templates/actions/create-pr.yml.tpl.d.ts.map +1 -1
  20. package/dist/templates/actions/create-pr.yml.tpl.js +22 -2
  21. package/dist/templates/actions/create-pr.yml.tpl.js.map +1 -1
  22. package/dist/templates/actions/create-release.yml.tpl.d.ts +18 -0
  23. package/dist/templates/actions/create-release.yml.tpl.d.ts.map +1 -0
  24. package/dist/templates/actions/create-release.yml.tpl.js +141 -0
  25. package/dist/templates/actions/create-release.yml.tpl.js.map +1 -0
  26. package/dist/templates/actions/create-tag.yml.tpl.d.ts +14 -0
  27. package/dist/templates/actions/create-tag.yml.tpl.d.ts.map +1 -1
  28. package/dist/templates/actions/create-tag.yml.tpl.js +22 -2
  29. package/dist/templates/actions/create-tag.yml.tpl.js.map +1 -1
  30. package/dist/templates/actions/detect-changes.yml.tpl.d.ts +70 -0
  31. package/dist/templates/actions/detect-changes.yml.tpl.d.ts.map +1 -1
  32. package/dist/templates/actions/detect-changes.yml.tpl.js +98 -2
  33. package/dist/templates/actions/detect-changes.yml.tpl.js.map +1 -1
  34. package/dist/templates/actions/manage-branch.yml.tpl.d.ts +14 -0
  35. package/dist/templates/actions/manage-branch.yml.tpl.d.ts.map +1 -1
  36. package/dist/templates/actions/manage-branch.yml.tpl.js +22 -2
  37. package/dist/templates/actions/manage-branch.yml.tpl.js.map +1 -1
  38. package/dist/templates/actions/promote-branch.yml.tpl.d.ts +14 -0
  39. package/dist/templates/actions/promote-branch.yml.tpl.d.ts.map +1 -1
  40. package/dist/templates/actions/promote-branch.yml.tpl.js +50 -7
  41. package/dist/templates/actions/promote-branch.yml.tpl.js.map +1 -1
  42. package/dist/templates/workflows/pipeline-path-based.yml.tpl.d.ts +114 -1
  43. package/dist/templates/workflows/pipeline-path-based.yml.tpl.d.ts.map +1 -1
  44. package/dist/templates/workflows/pipeline-path-based.yml.tpl.js +479 -74
  45. package/dist/templates/workflows/pipeline-path-based.yml.tpl.js.map +1 -1
  46. package/dist/types/index.d.ts +231 -8
  47. package/dist/types/index.d.ts.map +1 -1
  48. package/dist/types/index.js +9 -0
  49. package/dist/types/index.js.map +1 -1
  50. package/dist/utils/ast-path-operations.d.ts.map +1 -1
  51. package/dist/utils/ast-path-operations.js +24 -11
  52. package/dist/utils/ast-path-operations.js.map +1 -1
  53. package/dist/utils/config.d.ts +63 -0
  54. package/dist/utils/config.d.ts.map +1 -1
  55. package/dist/utils/config.js +71 -0
  56. package/dist/utils/config.js.map +1 -1
  57. package/dist/utils/github-setup.d.ts +323 -2
  58. package/dist/utils/github-setup.d.ts.map +1 -1
  59. package/dist/utils/github-setup.js +551 -23
  60. package/dist/utils/github-setup.js.map +1 -1
  61. package/dist/utils/idempotency.d.ts +147 -7
  62. package/dist/utils/idempotency.d.ts.map +1 -1
  63. package/dist/utils/idempotency.js +143 -15
  64. package/dist/utils/idempotency.js.map +1 -1
  65. package/dist/utils/logger.d.ts +134 -0
  66. package/dist/utils/logger.d.ts.map +1 -0
  67. package/dist/utils/logger.js +153 -0
  68. package/dist/utils/logger.js.map +1 -0
  69. package/dist/utils/preflight.d.ts +223 -12
  70. package/dist/utils/preflight.d.ts.map +1 -1
  71. package/dist/utils/preflight.js +216 -16
  72. package/dist/utils/preflight.js.map +1 -1
  73. package/dist/utils/versioning.d.ts +160 -8
  74. package/dist/utils/versioning.d.ts.map +1 -1
  75. package/dist/utils/versioning.js +179 -15
  76. package/dist/utils/versioning.js.map +1 -1
  77. package/package.json +26 -5
  78. package/.claude/settings.local.json +0 -35
  79. package/.github/actions/calculate-version/action.yml +0 -106
  80. package/.github/actions/create-pr/action.yml +0 -122
  81. package/.github/actions/create-release/action.yml +0 -74
  82. package/.github/actions/create-tag/action.yml +0 -94
  83. package/.github/actions/detect-changes/action.yml +0 -62
  84. package/.github/actions/manage-branch/action.yml +0 -113
  85. package/.github/actions/promote-branch/action.yml +0 -352
  86. package/.github/example/workflows/job.analyze.code.yml +0 -26
  87. package/.github/example/workflows/job.analyze.docker.yml +0 -32
  88. package/.github/example/workflows/job.app.api.deploy.yml +0 -127
  89. package/.github/example/workflows/job.app.api.test.yml +0 -102
  90. package/.github/example/workflows/job.app.docs.deploy.yml +0 -40
  91. package/.github/example/workflows/job.app.docs.test.yml +0 -50
  92. package/.github/example/workflows/job.app.web.deploy.yml +0 -96
  93. package/.github/example/workflows/job.app.web.test.yml +0 -49
  94. package/.github/example/workflows/job.changes.yml +0 -82
  95. package/.github/example/workflows/job.create-pr.yml +0 -96
  96. package/.github/example/workflows/job.env-check.yml +0 -43
  97. package/.github/example/workflows/job.fast-forward.yml +0 -103
  98. package/.github/example/workflows/job.lint.yml +0 -64
  99. package/.github/example/workflows/job.pr-name.yml +0 -70
  100. package/.github/example/workflows/job.pr-squash-name.yml +0 -27
  101. package/.github/example/workflows/job.tag.yml +0 -38
  102. package/.github/example/workflows/job.version.yml +0 -99
  103. package/.github/example/workflows/lib.plugin-base.publish.yml +0 -59
  104. package/.github/example/workflows/pipe.yml +0 -178
  105. package/.github/example/workflows/scripts/fastforward.sh +0 -51
  106. package/.github/example/workflows/scripts/pipe-cleaner.sh +0 -70
  107. package/.github/scripts/fastforward.sh +0 -51
  108. package/.github/scripts/pipe-cleaner.sh +0 -70
  109. package/.github/workflows/pipeline.yml +0 -220
  110. package/.github/workflows/pr-title-check.yml +0 -70
  111. package/.github/workflows/publish.yml +0 -39
  112. package/.pipecraftrc.json +0 -78
  113. package/.release-it.cjs +0 -71
  114. package/PIPELINE_TESTING_PLAN.md +0 -499
  115. package/TRUNK_FLOW_PLAN.md +0 -401
  116. package/assets/logo_banner.png +0 -0
  117. package/assets/logo_banner.webp +0 -0
  118. package/docs/USER_JOURNEY_ERRORS.md +0 -352
  119. package/eslint.config.js +0 -77
  120. package/examples/basic-config.json +0 -41
  121. package/examples/monorepo-config.json +0 -49
  122. package/examples/usage.md +0 -289
  123. package/scripts/debug-workflows.sh +0 -339
  124. package/scripts/parse-pipeline.js +0 -29
  125. package/scripts/test-job-order.cjs +0 -140
  126. package/scripts/validate-pipeline.cjs +0 -379
  127. package/scripts/verify-job-order.sh +0 -30
  128. package/src/cli/index.ts +0 -414
  129. package/src/generators/init.tpl.ts +0 -126
  130. package/src/generators/workflows.tpl.ts +0 -80
  131. package/src/templates/actions/calculate-version.yml.tpl.ts +0 -124
  132. package/src/templates/actions/create-pr.yml.tpl.ts +0 -147
  133. package/src/templates/actions/create-tag.yml.tpl.ts +0 -112
  134. package/src/templates/actions/detect-changes.yml.tpl.ts +0 -87
  135. package/src/templates/actions/manage-branch.yml.tpl.ts +0 -132
  136. package/src/templates/actions/promote-branch.yml.tpl.ts +0 -364
  137. package/src/templates/workflows/pipeline-path-based.yml.tpl.ts +0 -706
  138. package/src/types/index.ts +0 -64
  139. package/src/utils/README-ast-path-operations.md +0 -390
  140. package/src/utils/ast-path-operations.ts +0 -581
  141. package/src/utils/config.ts +0 -64
  142. package/src/utils/github-setup.ts +0 -558
  143. package/src/utils/idempotency.ts +0 -215
  144. package/src/utils/preflight.ts +0 -306
  145. package/src/utils/versioning.ts +0 -244
  146. package/tests/README.md +0 -229
  147. package/tests/TEST_STRUCTURE.md +0 -256
  148. package/tests/act/run-act-tests.sh +0 -345
  149. package/tests/debugging/debug-utils.ts +0 -538
  150. package/tests/debugging/debug-workflow.test.ts +0 -339
  151. package/tests/debugging/debug-workflows.sh +0 -339
  152. package/tests/debugging/iterative-debug.ts +0 -652
  153. package/tests/debugging/run-debug-tests.sh +0 -431
  154. package/tests/fixtures/basic-config.json +0 -51
  155. package/tests/fixtures/invalid-config.json +0 -9
  156. package/tests/fixtures/pipeline-generated.yml +0 -235
  157. package/tests/fixtures/pipeline-preserve-comments.yml +0 -245
  158. package/tests/fixtures/pipeline-user-modified.yml +0 -245
  159. package/tests/fixtures/test-config.json +0 -58
  160. package/tests/github-live/README.md +0 -250
  161. package/tests/github-local/JOB_WORKFLOW_TESTS.md +0 -296
  162. package/tests/github-local/README.md +0 -240
  163. package/tests/github-local/run-all-tests.sh +0 -422
  164. package/tests/github-local/test-job-workflows.sh +0 -631
  165. package/tests/github-local/test-pipeline-workflow.sh +0 -440
  166. package/tests/integration/generators.test.ts +0 -578
  167. package/tests/integration/path-based-template.test.ts +0 -510
  168. package/tests/integration/simple-path-based.test.ts +0 -415
  169. package/tests/setup.ts +0 -56
  170. package/tests/unit/ast-path-operations-extended.test.ts +0 -302
  171. package/tests/unit/cli.test.ts +0 -541
  172. package/tests/unit/config-extended.test.ts +0 -412
  173. package/tests/unit/config.test.ts +0 -152
  174. package/tests/unit/github-setup.test.ts +0 -189
  175. package/tests/unit/idempotency-isolated.test.ts +0 -297
  176. package/tests/unit/job-order.test.ts +0 -157
  177. package/tests/unit/pipeline-path-based.test.ts +0 -511
  178. package/tests/unit/validate-pipeline.test.ts +0 -384
  179. package/tests/unit/versioning-extended.test.ts +0 -279
  180. package/tests/unit/versioning.test.ts +0 -241
  181. package/tsconfig.debug.json +0 -17
  182. package/tsconfig.json +0 -28
  183. package/vitest.config.ts +0 -51
@@ -0,0 +1,134 @@
1
+ /**
2
+ * Logging Utility with Configurable Verbosity
3
+ *
4
+ * This module provides a singleton logger instance with multiple verbosity levels
5
+ * to control console output. The logger supports four levels:
6
+ * - silent: No output (useful for programmatic usage or CI environments)
7
+ * - normal: Standard output (info, success, warn, error)
8
+ * - verbose: Normal + verbose messages (detailed operation info)
9
+ * - debug: Verbose + debug messages (maximum detail for troubleshooting)
10
+ *
11
+ * Note: This is a test change to verify Codecov integration
12
+ *
13
+ * The log level can be changed at runtime using --verbose or --debug flags
14
+ * passed to the CLI commands.
15
+ *
16
+ * @module utils/logger
17
+ */
18
+ /**
19
+ * Available log verbosity levels in ascending order of detail.
20
+ * - silent: No console output
21
+ * - normal: Standard operational messages
22
+ * - verbose: Detailed operational messages
23
+ * - debug: Maximum detail including internal state
24
+ */
25
+ export type LogLevel = 'silent' | 'normal' | 'verbose' | 'debug';
26
+ /**
27
+ * Logger class providing level-based console output control.
28
+ *
29
+ * This is a singleton class that manages console output throughout the application.
30
+ * Different methods are shown based on the current log level setting.
31
+ */
32
+ declare class Logger {
33
+ private level;
34
+ /**
35
+ * Set the current log level.
36
+ *
37
+ * Changes take effect immediately for all subsequent log calls.
38
+ * Typically called once at application startup based on CLI flags.
39
+ *
40
+ * @param level - The log level to set
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * import { logger } from './logger'
45
+ *
46
+ * // Set from CLI options
47
+ * if (options.debug) logger.setLevel('debug')
48
+ * else if (options.verbose) logger.setLevel('verbose')
49
+ * ```
50
+ */
51
+ setLevel(level: LogLevel): void;
52
+ /**
53
+ * Get the current log level.
54
+ *
55
+ * @returns The current log level
56
+ */
57
+ getLevel(): LogLevel;
58
+ /**
59
+ * Log an informational message.
60
+ *
61
+ * Shown at normal, verbose, and debug levels.
62
+ * Use for standard operational messages that users should see.
63
+ *
64
+ * @param args - Arguments to log (same as console.log)
65
+ */
66
+ info(...args: any[]): void;
67
+ /**
68
+ * Log a success message.
69
+ *
70
+ * Shown at normal, verbose, and debug levels.
71
+ * Use for successful completion of operations or validation passes.
72
+ *
73
+ * @param args - Arguments to log (same as console.log)
74
+ */
75
+ success(...args: any[]): void;
76
+ /**
77
+ * Log a warning message.
78
+ *
79
+ * Shown at normal, verbose, and debug levels.
80
+ * Use for non-fatal issues that users should be aware of.
81
+ * Outputs to stderr via console.warn.
82
+ *
83
+ * @param args - Arguments to log (same as console.warn)
84
+ */
85
+ warn(...args: any[]): void;
86
+ /**
87
+ * Log an error message.
88
+ *
89
+ * Shown at normal, verbose, and debug levels.
90
+ * Use for fatal errors or validation failures.
91
+ * Outputs to stderr via console.error.
92
+ *
93
+ * @param args - Arguments to log (same as console.error)
94
+ */
95
+ error(...args: any[]): void;
96
+ /**
97
+ * Log a verbose message.
98
+ *
99
+ * Only shown in verbose or debug mode.
100
+ * Use for detailed operational information like file paths,
101
+ * intermediate results, or configuration details.
102
+ *
103
+ * @param args - Arguments to log (same as console.log)
104
+ */
105
+ verbose(...args: any[]): void;
106
+ /**
107
+ * Log a debug message.
108
+ *
109
+ * Only shown in debug mode.
110
+ * Use for maximum detail including internal state, variable values,
111
+ * and step-by-step execution flow. Helpful for troubleshooting.
112
+ *
113
+ * @param args - Arguments to log (same as console.log)
114
+ */
115
+ debug(...args: any[]): void;
116
+ }
117
+ /**
118
+ * Singleton logger instance exported for use throughout the application.
119
+ *
120
+ * @example
121
+ * ```typescript
122
+ * import { logger } from '@/utils/logger'
123
+ *
124
+ * logger.info('Starting workflow generation...')
125
+ * logger.verbose('Loading config from:', configPath)
126
+ * logger.debug('Config object:', config)
127
+ * logger.success('✓ Workflows generated successfully')
128
+ * logger.warn('⚠ No git remote found')
129
+ * logger.error('✗ Validation failed:', error.message)
130
+ * ```
131
+ */
132
+ export declare const logger: Logger;
133
+ export {};
134
+ //# sourceMappingURL=logger.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE;;;;;GAKG;AACH,cAAM,MAAM;IACV,OAAO,CAAC,KAAK,CAAsB;IAEnC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;OAIG;IACH,QAAQ,IAAI,QAAQ;IAIpB;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM1B;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM7B;;;;;;;;OAQG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM1B;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM3B;;;;;;;;OAQG;IACH,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM7B;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;CAK5B;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC"}
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Logging Utility with Configurable Verbosity
3
+ *
4
+ * This module provides a singleton logger instance with multiple verbosity levels
5
+ * to control console output. The logger supports four levels:
6
+ * - silent: No output (useful for programmatic usage or CI environments)
7
+ * - normal: Standard output (info, success, warn, error)
8
+ * - verbose: Normal + verbose messages (detailed operation info)
9
+ * - debug: Verbose + debug messages (maximum detail for troubleshooting)
10
+ *
11
+ * Note: This is a test change to verify Codecov integration
12
+ *
13
+ * The log level can be changed at runtime using --verbose or --debug flags
14
+ * passed to the CLI commands.
15
+ *
16
+ * @module utils/logger
17
+ */
18
+ /**
19
+ * Logger class providing level-based console output control.
20
+ *
21
+ * This is a singleton class that manages console output throughout the application.
22
+ * Different methods are shown based on the current log level setting.
23
+ */
24
+ class Logger {
25
+ level = 'normal';
26
+ /**
27
+ * Set the current log level.
28
+ *
29
+ * Changes take effect immediately for all subsequent log calls.
30
+ * Typically called once at application startup based on CLI flags.
31
+ *
32
+ * @param level - The log level to set
33
+ *
34
+ * @example
35
+ * ```typescript
36
+ * import { logger } from './logger'
37
+ *
38
+ * // Set from CLI options
39
+ * if (options.debug) logger.setLevel('debug')
40
+ * else if (options.verbose) logger.setLevel('verbose')
41
+ * ```
42
+ */
43
+ setLevel(level) {
44
+ this.level = level;
45
+ }
46
+ /**
47
+ * Get the current log level.
48
+ *
49
+ * @returns The current log level
50
+ */
51
+ getLevel() {
52
+ return this.level;
53
+ }
54
+ /**
55
+ * Log an informational message.
56
+ *
57
+ * Shown at normal, verbose, and debug levels.
58
+ * Use for standard operational messages that users should see.
59
+ *
60
+ * @param args - Arguments to log (same as console.log)
61
+ */
62
+ info(...args) {
63
+ if (this.level !== 'silent') {
64
+ console.log(...args);
65
+ }
66
+ }
67
+ /**
68
+ * Log a success message.
69
+ *
70
+ * Shown at normal, verbose, and debug levels.
71
+ * Use for successful completion of operations or validation passes.
72
+ *
73
+ * @param args - Arguments to log (same as console.log)
74
+ */
75
+ success(...args) {
76
+ if (this.level !== 'silent') {
77
+ console.log(...args);
78
+ }
79
+ }
80
+ /**
81
+ * Log a warning message.
82
+ *
83
+ * Shown at normal, verbose, and debug levels.
84
+ * Use for non-fatal issues that users should be aware of.
85
+ * Outputs to stderr via console.warn.
86
+ *
87
+ * @param args - Arguments to log (same as console.warn)
88
+ */
89
+ warn(...args) {
90
+ if (this.level !== 'silent') {
91
+ console.warn(...args);
92
+ }
93
+ }
94
+ /**
95
+ * Log an error message.
96
+ *
97
+ * Shown at normal, verbose, and debug levels.
98
+ * Use for fatal errors or validation failures.
99
+ * Outputs to stderr via console.error.
100
+ *
101
+ * @param args - Arguments to log (same as console.error)
102
+ */
103
+ error(...args) {
104
+ if (this.level !== 'silent') {
105
+ console.error(...args);
106
+ }
107
+ }
108
+ /**
109
+ * Log a verbose message.
110
+ *
111
+ * Only shown in verbose or debug mode.
112
+ * Use for detailed operational information like file paths,
113
+ * intermediate results, or configuration details.
114
+ *
115
+ * @param args - Arguments to log (same as console.log)
116
+ */
117
+ verbose(...args) {
118
+ if (this.level === 'verbose' || this.level === 'debug') {
119
+ console.log(...args);
120
+ }
121
+ }
122
+ /**
123
+ * Log a debug message.
124
+ *
125
+ * Only shown in debug mode.
126
+ * Use for maximum detail including internal state, variable values,
127
+ * and step-by-step execution flow. Helpful for troubleshooting.
128
+ *
129
+ * @param args - Arguments to log (same as console.log)
130
+ */
131
+ debug(...args) {
132
+ if (this.level === 'debug') {
133
+ console.log(...args);
134
+ }
135
+ }
136
+ }
137
+ /**
138
+ * Singleton logger instance exported for use throughout the application.
139
+ *
140
+ * @example
141
+ * ```typescript
142
+ * import { logger } from '@/utils/logger'
143
+ *
144
+ * logger.info('Starting workflow generation...')
145
+ * logger.verbose('Loading config from:', configPath)
146
+ * logger.debug('Config object:', config)
147
+ * logger.success('✓ Workflows generated successfully')
148
+ * logger.warn('⚠ No git remote found')
149
+ * logger.error('✗ Validation failed:', error.message)
150
+ * ```
151
+ */
152
+ export const logger = new Logger();
153
+ //# sourceMappingURL=logger.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH;;;;;GAKG;AACH,MAAM,MAAM;IACF,KAAK,GAAa,QAAQ,CAAC;IAEnC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAe;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,IAAW;QACjB,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG,IAAW;QACpB,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CAAC,GAAG,IAAW;QACjB,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,IAAW;QAClB,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,GAAG,IAAW;QACpB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;YACvD,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,IAAW;QAClB,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;YAC3B,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC"}
@@ -1,51 +1,262 @@
1
1
  /**
2
- * Pre-flight checks for PipeCraft commands
3
- * Validates environment and prerequisites before executing commands
2
+ * Pre-Flight Validation Checks
3
+ *
4
+ * This module implements comprehensive environment validation before workflow generation.
5
+ * Pre-flight checks prevent common failures by validating:
6
+ * - PipeCraft configuration exists and is valid
7
+ * - Git repository is properly initialized
8
+ * - Git remote is configured
9
+ * - Workflow directories are writable
10
+ * - Node.js version meets minimum requirements
11
+ *
12
+ * All checks return structured results with actionable error messages and suggestions.
13
+ * This provides a better user experience by catching issues early with clear guidance
14
+ * on how to resolve them.
15
+ *
16
+ * @module utils/preflight
17
+ */
18
+ /**
19
+ * Result of a single pre-flight check.
20
+ *
21
+ * Contains pass/fail status, descriptive message, and optional suggestion
22
+ * for resolving failures.
4
23
  */
5
24
  export interface PreflightResult {
25
+ /** Whether the check passed */
6
26
  passed: boolean;
27
+ /** Human-readable description of the check result */
7
28
  message: string;
29
+ /** Optional suggestion for resolving failures */
8
30
  suggestion?: string;
9
31
  }
32
+ /**
33
+ * Collection of all pre-flight check results.
34
+ *
35
+ * Each field represents a specific environment check that must pass
36
+ * before workflows can be generated.
37
+ */
10
38
  export interface PreflightChecks {
39
+ /** Configuration file exists and is discoverable */
11
40
  configExists: PreflightResult;
41
+ /** Configuration file is valid and has required fields */
12
42
  configValid: PreflightResult;
43
+ /** Current directory is a git repository */
13
44
  inGitRepo: PreflightResult;
45
+ /** Git remote (origin) is configured */
14
46
  hasGitRemote: PreflightResult;
47
+ /** .github/workflows directory is writable */
15
48
  canWriteGithubDir: PreflightResult;
16
49
  }
17
50
  /**
18
- * Check if config file exists using cosmiconfig
19
- * Searches for .pipecraftrc.json, .pipecraftrc, or package.json pipecraft key
51
+ * Check if PipeCraft configuration file exists.
52
+ *
53
+ * Uses cosmiconfig to search for configuration files in standard locations:
54
+ * - .pipecraftrc.json
55
+ * - .pipecraftrc (JSON or YAML)
56
+ * - pipecraft.config.js
57
+ * - package.json (pipecraft key)
58
+ *
59
+ * Searches current directory and all parent directories.
60
+ *
61
+ * @returns Check result with pass/fail status and file location if found
62
+ *
63
+ * @example
64
+ * ```typescript
65
+ * const result = checkConfigExists()
66
+ * if (!result.passed) {
67
+ * console.error(result.message)
68
+ * console.log(result.suggestion) // "Run 'pipecraft init' to create..."
69
+ * }
70
+ * ```
20
71
  */
21
72
  export declare function checkConfigExists(): PreflightResult;
22
73
  /**
23
- * Check if config file is valid and has required fields
74
+ * Check if configuration file is valid and contains required fields.
75
+ *
76
+ * Validates:
77
+ * - File can be parsed (valid JSON/YAML)
78
+ * - Required fields are present (ciProvider, branchFlow, domains)
79
+ * - At least one domain is configured
80
+ *
81
+ * @returns Check result with validation status and specific error if invalid
82
+ *
83
+ * @example
84
+ * ```typescript
85
+ * const result = checkConfigValid()
86
+ * if (!result.passed) {
87
+ * if (result.message.includes('missing required fields')) {
88
+ * // Config exists but incomplete
89
+ * } else if (result.message.includes('Invalid JSON')) {
90
+ * // Syntax error in config file
91
+ * }
92
+ * }
93
+ * ```
24
94
  */
25
95
  export declare function checkConfigValid(): PreflightResult;
26
96
  /**
27
- * Check if current directory is a git repository
97
+ * Check if current directory is inside a git repository.
98
+ *
99
+ * PipeCraft requires a git repository to:
100
+ * - Generate GitHub Actions workflows
101
+ * - Track version history
102
+ * - Enable version management features
103
+ *
104
+ * Uses `git rev-parse --is-inside-work-tree` to detect git repository.
105
+ * Suppresses stderr to avoid noise when git is not initialized.
106
+ *
107
+ * @returns Check result indicating if directory is in a git repository
108
+ *
109
+ * @example
110
+ * ```typescript
111
+ * const result = checkInGitRepo()
112
+ * if (!result.passed) {
113
+ * console.log('Please initialize git first')
114
+ * execSync('git init')
115
+ * }
116
+ * ```
28
117
  */
29
118
  export declare function checkInGitRepo(): PreflightResult;
30
119
  /**
31
- * Check if git remote is configured
120
+ * Check if git remote named 'origin' is configured.
121
+ *
122
+ * A git remote is required for:
123
+ * - Pushing generated workflows to GitHub
124
+ * - Repository information extraction
125
+ * - GitHub API integration
126
+ *
127
+ * Checks specifically for the 'origin' remote, which is the standard
128
+ * default remote name. Also detects if the remote is GitHub vs. GitLab
129
+ * and provides appropriate messaging.
130
+ *
131
+ * @returns Check result with remote URL if configured
132
+ *
133
+ * @example
134
+ * ```typescript
135
+ * const result = checkHasGitRemote()
136
+ * if (!result.passed) {
137
+ * console.log('No git remote found')
138
+ * execSync('git remote add origin https://github.com/user/repo.git')
139
+ * } else if (result.suggestion) {
140
+ * // GitLab detected - show warning about experimental support
141
+ * console.warn(result.suggestion)
142
+ * }
143
+ * ```
32
144
  */
33
145
  export declare function checkHasGitRemote(): PreflightResult;
34
146
  /**
35
- * Check if .github directory is writable
147
+ * Check if .github/workflows directory exists and is writable.
148
+ *
149
+ * Workflows are written to .github/workflows/, so this directory must:
150
+ * - Exist or be creatable
151
+ * - Be writable by the current user
152
+ *
153
+ * This check attempts to:
154
+ * 1. Create .github/workflows/ if it doesn't exist
155
+ * 2. Write a test file to verify write permissions
156
+ * 3. Clean up the test file
157
+ *
158
+ * @returns Check result indicating if directory is writable
159
+ *
160
+ * @example
161
+ * ```typescript
162
+ * const result = checkCanWriteGithubDir()
163
+ * if (!result.passed) {
164
+ * if (result.message.includes('permission')) {
165
+ * // Fix permissions
166
+ * execSync('chmod +w .github/workflows/')
167
+ * }
168
+ * }
169
+ * ```
36
170
  */
37
171
  export declare function checkCanWriteGithubDir(): PreflightResult;
38
172
  /**
39
- * Check Node.js version
173
+ * Check if Node.js version meets minimum requirement.
174
+ *
175
+ * PipeCraft requires Node.js 18.0.0 or higher because it uses:
176
+ * - Modern ES modules
177
+ * - Latest TypeScript features
178
+ * - Current GitHub Actions syntax
179
+ *
180
+ * Only checks major version for simplicity. Minor/patch versions
181
+ * within the same major release are considered compatible.
182
+ *
183
+ * @param minVersion - Minimum required version (default: '18.0.0')
184
+ * @returns Check result with current and minimum versions
185
+ *
186
+ * @example
187
+ * ```typescript
188
+ * const result = checkNodeVersion('18.0.0')
189
+ * if (!result.passed) {
190
+ * console.error('Please upgrade Node.js')
191
+ * console.log('Current:', process.version)
192
+ * console.log('Required: >= 18.0.0')
193
+ * }
194
+ * ```
40
195
  */
41
196
  export declare function checkNodeVersion(minVersion?: string): PreflightResult;
42
197
  /**
43
- * Run all pre-flight checks for generate command
44
- * Note: No longer needs configPath - uses cosmiconfig to search automatically
198
+ * Run all pre-flight checks for workflow generation.
199
+ *
200
+ * Executes comprehensive environment validation to ensure all prerequisites
201
+ * are met before attempting to generate workflows. This prevents partial
202
+ * failures and provides clear error messages upfront.
203
+ *
204
+ * Checks performed:
205
+ * - Configuration file exists
206
+ * - Configuration is valid
207
+ * - Inside git repository
208
+ * - Git remote configured
209
+ * - Workflow directory writable
210
+ *
211
+ * Note: Node version check is optional and not included by default since
212
+ * if Node is too old, the code wouldn't run at all.
213
+ *
214
+ * @returns Collection of all check results
215
+ *
216
+ * @example
217
+ * ```typescript
218
+ * const checks = runPreflightChecks()
219
+ * const { allPassed, output } = formatPreflightResults(checks)
220
+ *
221
+ * if (!allPassed) {
222
+ * console.error('Pre-flight checks failed:')
223
+ * console.log(output)
224
+ * process.exit(1)
225
+ * }
226
+ *
227
+ * // Proceed with workflow generation
228
+ * await generateWorkflows()
229
+ * ```
45
230
  */
46
231
  export declare function runPreflightChecks(): PreflightChecks;
47
232
  /**
48
- * Format preflight results for display
233
+ * Format pre-flight check results for human-readable display.
234
+ *
235
+ * Converts structured check results into formatted output with:
236
+ * - ✅/❌ icons for visual scanning
237
+ * - Error messages and suggestions
238
+ * - Next steps if all checks passed
239
+ * - Helpful guidance for getting started
240
+ *
241
+ * The output is designed to be printed directly to the console.
242
+ *
243
+ * @param checks - Collection of check results from runPreflightChecks()
244
+ * @returns Formatted output object with overall status and display string
245
+ *
246
+ * @example
247
+ * ```typescript
248
+ * const checks = runPreflightChecks()
249
+ * const { allPassed, output, nextSteps } = formatPreflightResults(checks)
250
+ *
251
+ * console.log(output)
252
+ *
253
+ * if (allPassed && nextSteps) {
254
+ * console.log('\n' + nextSteps.join('\n'))
255
+ * } else {
256
+ * console.error('\n⚠ Fix the above issues and try again')
257
+ * process.exit(1)
258
+ * }
259
+ * ```
49
260
  */
50
261
  export declare function formatPreflightResults(checks: PreflightChecks): {
51
262
  allPassed: boolean;
@@ -1 +1 @@
1
- {"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/utils/preflight.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,eAAe,CAAA;IAC7B,WAAW,EAAE,eAAe,CAAA;IAC5B,SAAS,EAAE,eAAe,CAAA;IAC1B,YAAY,EAAE,eAAe,CAAA;IAC7B,iBAAiB,EAAE,eAAe,CAAA;CACnC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,eAAe,CAgBnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,eAAe,CAuDlD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,eAAe,CAkBhD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,eAAe,CAgCnD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAyCxD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,GAAE,MAAiB,GAAG,eAAe,CAkB/E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAQpD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG;IAC/D,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB,CAkCA"}
1
+ {"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/utils/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAA;IAEf,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IAEf,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,YAAY,EAAE,eAAe,CAAA;IAE7B,0DAA0D;IAC1D,WAAW,EAAE,eAAe,CAAA;IAE5B,4CAA4C;IAC5C,SAAS,EAAE,eAAe,CAAA;IAE1B,wCAAwC;IACxC,YAAY,EAAE,eAAe,CAAA;IAE7B,8CAA8C;IAC9C,iBAAiB,EAAE,eAAe,CAAA;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,IAAI,eAAe,CAgBnD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,IAAI,eAAe,CAuDlD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,IAAI,eAAe,CAkBhD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,IAAI,eAAe,CAgCnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAyCxD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,GAAE,MAAiB,GAAG,eAAe,CAkB/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAQpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG;IAC/D,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB,CAkCA"}