container-superposition 0.1.1

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 (327) hide show
  1. package/README.md +843 -0
  2. package/dist/scripts/init.d.ts +3 -0
  3. package/dist/scripts/init.d.ts.map +1 -0
  4. package/dist/scripts/init.js +1190 -0
  5. package/dist/scripts/init.js.map +1 -0
  6. package/dist/scripts/migrate-to-manifests.d.ts +12 -0
  7. package/dist/scripts/migrate-to-manifests.d.ts.map +1 -0
  8. package/dist/scripts/migrate-to-manifests.js +230 -0
  9. package/dist/scripts/migrate-to-manifests.js.map +1 -0
  10. package/dist/tool/questionnaire/composer.d.ts +6 -0
  11. package/dist/tool/questionnaire/composer.d.ts.map +1 -0
  12. package/dist/tool/questionnaire/composer.js +1232 -0
  13. package/dist/tool/questionnaire/composer.js.map +1 -0
  14. package/dist/tool/readme/markdown-parser.d.ts +30 -0
  15. package/dist/tool/readme/markdown-parser.d.ts.map +1 -0
  16. package/dist/tool/readme/markdown-parser.js +139 -0
  17. package/dist/tool/readme/markdown-parser.js.map +1 -0
  18. package/dist/tool/readme/readme-generator.d.ts +9 -0
  19. package/dist/tool/readme/readme-generator.d.ts.map +1 -0
  20. package/dist/tool/readme/readme-generator.js +422 -0
  21. package/dist/tool/readme/readme-generator.js.map +1 -0
  22. package/dist/tool/schema/custom-loader.d.ts +17 -0
  23. package/dist/tool/schema/custom-loader.d.ts.map +1 -0
  24. package/dist/tool/schema/custom-loader.js +149 -0
  25. package/dist/tool/schema/custom-loader.js.map +1 -0
  26. package/dist/tool/schema/overlay-loader.d.ts +47 -0
  27. package/dist/tool/schema/overlay-loader.d.ts.map +1 -0
  28. package/dist/tool/schema/overlay-loader.js +252 -0
  29. package/dist/tool/schema/overlay-loader.js.map +1 -0
  30. package/dist/tool/schema/types.d.ts +212 -0
  31. package/dist/tool/schema/types.d.ts.map +1 -0
  32. package/dist/tool/schema/types.js +5 -0
  33. package/dist/tool/schema/types.js.map +1 -0
  34. package/docs/README.md +308 -0
  35. package/docs/architecture.md +233 -0
  36. package/docs/creating-overlays.md +549 -0
  37. package/docs/custom-patches.md +540 -0
  38. package/docs/dependencies.md +279 -0
  39. package/docs/examples/custom-patches-example.md +85 -0
  40. package/docs/examples.md +576 -0
  41. package/docs/messaging-comparison.md +265 -0
  42. package/docs/messaging-quick-start.md +385 -0
  43. package/docs/observability-workflow.md +537 -0
  44. package/docs/overlay-manifest-refactoring.md +214 -0
  45. package/docs/overlay-metadata-archive.md +54 -0
  46. package/docs/overlays.md +523 -0
  47. package/docs/presets-architecture.md +498 -0
  48. package/docs/presets.md +366 -0
  49. package/docs/publishing.md +476 -0
  50. package/docs/quick-reference.md +326 -0
  51. package/docs/ux.md +170 -0
  52. package/features/README.md +85 -0
  53. package/features/cross-distro-packages/README.md +146 -0
  54. package/features/cross-distro-packages/devcontainer-feature.json +20 -0
  55. package/features/cross-distro-packages/install.sh +58 -0
  56. package/features/local-secrets-manager/devcontainer-feature.json +18 -0
  57. package/features/local-secrets-manager/install.sh +127 -0
  58. package/features/project-scaffolder/devcontainer-feature.json +24 -0
  59. package/features/project-scaffolder/install.sh +100 -0
  60. package/features/team-conventions/devcontainer-feature.json +24 -0
  61. package/features/team-conventions/install.sh +93 -0
  62. package/overlays/.registry/README.md +14 -0
  63. package/overlays/.registry/base-images.yml +26 -0
  64. package/overlays/.registry/base-templates.yml +7 -0
  65. package/overlays/README.md +155 -0
  66. package/overlays/alertmanager/.env.example +5 -0
  67. package/overlays/alertmanager/README.md +465 -0
  68. package/overlays/alertmanager/alert-rules.yml +56 -0
  69. package/overlays/alertmanager/alertmanager.yml +42 -0
  70. package/overlays/alertmanager/devcontainer.patch.json +12 -0
  71. package/overlays/alertmanager/docker-compose.yml +20 -0
  72. package/overlays/alertmanager/overlay.yml +17 -0
  73. package/overlays/alertmanager/setup.sh +53 -0
  74. package/overlays/alertmanager/verify.sh +31 -0
  75. package/overlays/aws-cli/README.md +473 -0
  76. package/overlays/aws-cli/devcontainer.patch.json +13 -0
  77. package/overlays/aws-cli/overlay.yml +13 -0
  78. package/overlays/azure-cli/README.md +551 -0
  79. package/overlays/azure-cli/devcontainer.patch.json +8 -0
  80. package/overlays/azure-cli/overlay.yml +13 -0
  81. package/overlays/bun/README.md +312 -0
  82. package/overlays/bun/devcontainer.patch.json +41 -0
  83. package/overlays/bun/overlay.yml +16 -0
  84. package/overlays/bun/setup.sh +79 -0
  85. package/overlays/bun/verify.sh +30 -0
  86. package/overlays/codex/README.md +128 -0
  87. package/overlays/codex/devcontainer.patch.json +3 -0
  88. package/overlays/codex/overlay.yml +14 -0
  89. package/overlays/codex/setup.sh +24 -0
  90. package/overlays/codex/verify.sh +30 -0
  91. package/overlays/commitlint/README.md +333 -0
  92. package/overlays/commitlint/devcontainer.patch.json +8 -0
  93. package/overlays/commitlint/overlay.yml +16 -0
  94. package/overlays/commitlint/setup.sh +234 -0
  95. package/overlays/direnv/README.md +504 -0
  96. package/overlays/direnv/devcontainer.patch.json +6 -0
  97. package/overlays/direnv/overlay.yml +13 -0
  98. package/overlays/direnv/setup.sh +139 -0
  99. package/overlays/docker-in-docker/README.md +534 -0
  100. package/overlays/docker-in-docker/devcontainer.patch.json +10 -0
  101. package/overlays/docker-in-docker/overlay.yml +13 -0
  102. package/overlays/docker-sock/README.md +256 -0
  103. package/overlays/docker-sock/devcontainer.patch.json +9 -0
  104. package/overlays/docker-sock/docker-compose.yml +8 -0
  105. package/overlays/docker-sock/overlay.yml +13 -0
  106. package/overlays/dotnet/README.md +147 -0
  107. package/overlays/dotnet/devcontainer.patch.json +51 -0
  108. package/overlays/dotnet/global-tools.txt +24 -0
  109. package/overlays/dotnet/overlay.yml +13 -0
  110. package/overlays/dotnet/setup.sh +51 -0
  111. package/overlays/dotnet/verify.sh +26 -0
  112. package/overlays/gcloud/README.md +269 -0
  113. package/overlays/gcloud/devcontainer.patch.json +14 -0
  114. package/overlays/gcloud/overlay.yml +14 -0
  115. package/overlays/gcloud/verify.sh +52 -0
  116. package/overlays/git-helpers/README.md +168 -0
  117. package/overlays/git-helpers/devcontainer.patch.json +33 -0
  118. package/overlays/git-helpers/overlay.yml +15 -0
  119. package/overlays/git-helpers/setup.sh +91 -0
  120. package/overlays/go/README.md +293 -0
  121. package/overlays/go/devcontainer.patch.json +43 -0
  122. package/overlays/go/overlay.yml +15 -0
  123. package/overlays/go/setup.sh +33 -0
  124. package/overlays/go/verify.sh +40 -0
  125. package/overlays/grafana/.env.example +9 -0
  126. package/overlays/grafana/README.md +462 -0
  127. package/overlays/grafana/dashboard-provider.yml +11 -0
  128. package/overlays/grafana/dashboards/observability-overview.json +263 -0
  129. package/overlays/grafana/devcontainer.patch.json +12 -0
  130. package/overlays/grafana/docker-compose.yml +27 -0
  131. package/overlays/grafana/grafana-datasources.yml +57 -0
  132. package/overlays/grafana/overlay.yml +21 -0
  133. package/overlays/grafana/verify.sh +34 -0
  134. package/overlays/jaeger/.env.example +7 -0
  135. package/overlays/jaeger/README.md +867 -0
  136. package/overlays/jaeger/devcontainer.patch.json +12 -0
  137. package/overlays/jaeger/docker-compose.yml +17 -0
  138. package/overlays/jaeger/overlay.yml +19 -0
  139. package/overlays/java/README.md +267 -0
  140. package/overlays/java/devcontainer.patch.json +44 -0
  141. package/overlays/java/overlay.yml +16 -0
  142. package/overlays/java/setup.sh +41 -0
  143. package/overlays/java/verify.sh +42 -0
  144. package/overlays/just/README.md +443 -0
  145. package/overlays/just/devcontainer.patch.json +3 -0
  146. package/overlays/just/overlay.yml +13 -0
  147. package/overlays/just/setup.sh +182 -0
  148. package/overlays/kubectl-helm/README.md +660 -0
  149. package/overlays/kubectl-helm/devcontainer.patch.json +10 -0
  150. package/overlays/kubectl-helm/overlay.yml +13 -0
  151. package/overlays/loki/.env.example +5 -0
  152. package/overlays/loki/README.md +1156 -0
  153. package/overlays/loki/devcontainer.patch.json +12 -0
  154. package/overlays/loki/docker-compose.yml +18 -0
  155. package/overlays/loki/loki-config.yaml +45 -0
  156. package/overlays/loki/overlay.yml +17 -0
  157. package/overlays/minio/.env.example +9 -0
  158. package/overlays/minio/README.md +639 -0
  159. package/overlays/minio/devcontainer.patch.json +30 -0
  160. package/overlays/minio/docker-compose.yml +28 -0
  161. package/overlays/minio/overlay.yml +18 -0
  162. package/overlays/minio/setup.sh +61 -0
  163. package/overlays/minio/verify.sh +64 -0
  164. package/overlays/mkdocs/README.md +309 -0
  165. package/overlays/mkdocs/devcontainer.patch.json +24 -0
  166. package/overlays/mkdocs/overlay.yml +15 -0
  167. package/overlays/modern-cli-tools/README.md +556 -0
  168. package/overlays/modern-cli-tools/devcontainer.patch.json +3 -0
  169. package/overlays/modern-cli-tools/overlay.yml +13 -0
  170. package/overlays/modern-cli-tools/setup.sh +153 -0
  171. package/overlays/mongodb/.env.example +9 -0
  172. package/overlays/mongodb/README.md +481 -0
  173. package/overlays/mongodb/devcontainer.patch.json +32 -0
  174. package/overlays/mongodb/docker-compose.yml +44 -0
  175. package/overlays/mongodb/overlay.yml +17 -0
  176. package/overlays/mongodb/verify.sh +48 -0
  177. package/overlays/mysql/.env.example +11 -0
  178. package/overlays/mysql/README.md +542 -0
  179. package/overlays/mysql/devcontainer.patch.json +34 -0
  180. package/overlays/mysql/docker-compose.yml +55 -0
  181. package/overlays/mysql/overlay.yml +16 -0
  182. package/overlays/mysql/verify.sh +48 -0
  183. package/overlays/nats/.env.example +5 -0
  184. package/overlays/nats/README.md +762 -0
  185. package/overlays/nats/devcontainer.patch.json +24 -0
  186. package/overlays/nats/docker-compose.yml +31 -0
  187. package/overlays/nats/overlay.yml +18 -0
  188. package/overlays/nats/verify.sh +50 -0
  189. package/overlays/ngrok/README.md +503 -0
  190. package/overlays/ngrok/devcontainer.patch.json +3 -0
  191. package/overlays/ngrok/overlay.yml +14 -0
  192. package/overlays/ngrok/setup.sh +125 -0
  193. package/overlays/nodejs/README.md +192 -0
  194. package/overlays/nodejs/devcontainer.patch.json +49 -0
  195. package/overlays/nodejs/global-packages.txt +16 -0
  196. package/overlays/nodejs/overlay.yml +14 -0
  197. package/overlays/nodejs/setup.sh +46 -0
  198. package/overlays/nodejs/verify.sh +32 -0
  199. package/overlays/otel-collector/.env.example +9 -0
  200. package/overlays/otel-collector/README.md +1257 -0
  201. package/overlays/otel-collector/devcontainer.patch.json +28 -0
  202. package/overlays/otel-collector/docker-compose.yml +22 -0
  203. package/overlays/otel-collector/otel-collector-config.yaml +68 -0
  204. package/overlays/otel-collector/overlay.yml +21 -0
  205. package/overlays/otel-collector/setup.sh +49 -0
  206. package/overlays/otel-demo-nodejs/.env.example +2 -0
  207. package/overlays/otel-demo-nodejs/Dockerfile-otel-demo-nodejs +17 -0
  208. package/overlays/otel-demo-nodejs/README.md +409 -0
  209. package/overlays/otel-demo-nodejs/devcontainer.patch.json +12 -0
  210. package/overlays/otel-demo-nodejs/docker-compose.yml +19 -0
  211. package/overlays/otel-demo-nodejs/overlay.yml +23 -0
  212. package/overlays/otel-demo-nodejs/package-otel-demo-nodejs.json +20 -0
  213. package/overlays/otel-demo-nodejs/server-otel-demo-nodejs.js +259 -0
  214. package/overlays/otel-demo-nodejs/tracing-otel-demo-nodejs.js +57 -0
  215. package/overlays/otel-demo-nodejs/verify.sh +31 -0
  216. package/overlays/otel-demo-python/.env.example +2 -0
  217. package/overlays/otel-demo-python/Dockerfile-otel-demo-python +16 -0
  218. package/overlays/otel-demo-python/README.md +82 -0
  219. package/overlays/otel-demo-python/app-otel-demo-python.py +208 -0
  220. package/overlays/otel-demo-python/devcontainer.patch.json +12 -0
  221. package/overlays/otel-demo-python/docker-compose.yml +19 -0
  222. package/overlays/otel-demo-python/overlay.yml +23 -0
  223. package/overlays/otel-demo-python/requirements-otel-demo-python.txt +4 -0
  224. package/overlays/otel-demo-python/verify.sh +31 -0
  225. package/overlays/playwright/README.md +629 -0
  226. package/overlays/playwright/devcontainer.patch.json +9 -0
  227. package/overlays/playwright/overlay.yml +13 -0
  228. package/overlays/postgres/.env.example +6 -0
  229. package/overlays/postgres/README.md +602 -0
  230. package/overlays/postgres/devcontainer.patch.json +21 -0
  231. package/overlays/postgres/docker-compose.yml +22 -0
  232. package/overlays/postgres/overlay.yml +15 -0
  233. package/overlays/postgres/verify.sh +45 -0
  234. package/overlays/powershell/README.md +314 -0
  235. package/overlays/powershell/devcontainer.patch.json +22 -0
  236. package/overlays/powershell/overlay.yml +13 -0
  237. package/overlays/powershell/setup.sh +29 -0
  238. package/overlays/powershell/verify.sh +38 -0
  239. package/overlays/pre-commit/README.md +263 -0
  240. package/overlays/pre-commit/devcontainer.patch.json +9 -0
  241. package/overlays/pre-commit/overlay.yml +16 -0
  242. package/overlays/pre-commit/setup.sh +129 -0
  243. package/overlays/presets/docs-site.yml +118 -0
  244. package/overlays/presets/fullstack.yml +181 -0
  245. package/overlays/presets/microservice.yml +118 -0
  246. package/overlays/presets/web-api.yml +109 -0
  247. package/overlays/prometheus/.env.example +5 -0
  248. package/overlays/prometheus/README.md +1246 -0
  249. package/overlays/prometheus/devcontainer.patch.json +12 -0
  250. package/overlays/prometheus/docker-compose.yml +22 -0
  251. package/overlays/prometheus/overlay.yml +17 -0
  252. package/overlays/prometheus/prometheus.yml +12 -0
  253. package/overlays/prometheus/verify.sh +34 -0
  254. package/overlays/promtail/.env.example +2 -0
  255. package/overlays/promtail/README.md +357 -0
  256. package/overlays/promtail/devcontainer.patch.json +5 -0
  257. package/overlays/promtail/docker-compose.yml +16 -0
  258. package/overlays/promtail/overlay.yml +17 -0
  259. package/overlays/promtail/promtail-config.yaml +60 -0
  260. package/overlays/promtail/verify.sh +31 -0
  261. package/overlays/pulumi/README.md +472 -0
  262. package/overlays/pulumi/devcontainer.patch.json +13 -0
  263. package/overlays/pulumi/overlay.yml +14 -0
  264. package/overlays/pulumi/verify.sh +31 -0
  265. package/overlays/python/README.md +919 -0
  266. package/overlays/python/devcontainer.patch.json +41 -0
  267. package/overlays/python/overlay.yml +12 -0
  268. package/overlays/python/requirements-overlay.txt +13 -0
  269. package/overlays/python/setup.sh +47 -0
  270. package/overlays/python/verify.sh +32 -0
  271. package/overlays/rabbitmq/.env.example +7 -0
  272. package/overlays/rabbitmq/README.md +680 -0
  273. package/overlays/rabbitmq/devcontainer.patch.json +28 -0
  274. package/overlays/rabbitmq/docker-compose.yml +30 -0
  275. package/overlays/rabbitmq/overlay.yml +18 -0
  276. package/overlays/rabbitmq/verify.sh +41 -0
  277. package/overlays/redis/.env.example +4 -0
  278. package/overlays/redis/README.md +776 -0
  279. package/overlays/redis/devcontainer.patch.json +21 -0
  280. package/overlays/redis/docker-compose.yml +21 -0
  281. package/overlays/redis/overlay.yml +15 -0
  282. package/overlays/redis/verify.sh +41 -0
  283. package/overlays/redpanda/.env.example +10 -0
  284. package/overlays/redpanda/README.md +703 -0
  285. package/overlays/redpanda/devcontainer.patch.json +37 -0
  286. package/overlays/redpanda/docker-compose.yml +67 -0
  287. package/overlays/redpanda/overlay.yml +21 -0
  288. package/overlays/redpanda/verify.sh +48 -0
  289. package/overlays/rust/README.md +299 -0
  290. package/overlays/rust/devcontainer.patch.json +39 -0
  291. package/overlays/rust/overlay.yml +15 -0
  292. package/overlays/rust/setup.sh +36 -0
  293. package/overlays/rust/verify.sh +51 -0
  294. package/overlays/sqlite/README.md +584 -0
  295. package/overlays/sqlite/devcontainer.patch.json +14 -0
  296. package/overlays/sqlite/overlay.yml +15 -0
  297. package/overlays/sqlite/setup.sh +27 -0
  298. package/overlays/sqlite/verify.sh +43 -0
  299. package/overlays/sqlserver/.env.example +6 -0
  300. package/overlays/sqlserver/README.md +592 -0
  301. package/overlays/sqlserver/devcontainer.patch.json +22 -0
  302. package/overlays/sqlserver/docker-compose.yml +32 -0
  303. package/overlays/sqlserver/overlay.yml +17 -0
  304. package/overlays/sqlserver/verify.sh +30 -0
  305. package/overlays/tempo/.env.example +5 -0
  306. package/overlays/tempo/README.md +273 -0
  307. package/overlays/tempo/devcontainer.patch.json +12 -0
  308. package/overlays/tempo/docker-compose.yml +20 -0
  309. package/overlays/tempo/overlay.yml +20 -0
  310. package/overlays/tempo/tempo-config.yaml +32 -0
  311. package/overlays/tempo/verify.sh +31 -0
  312. package/overlays/terraform/README.md +389 -0
  313. package/overlays/terraform/devcontainer.patch.json +15 -0
  314. package/overlays/terraform/overlay.yml +14 -0
  315. package/overlays/terraform/verify.sh +63 -0
  316. package/package.json +74 -0
  317. package/templates/README.md +285 -0
  318. package/templates/compose/.devcontainer/devcontainer.json +46 -0
  319. package/templates/compose/.devcontainer/docker-compose.yml +12 -0
  320. package/templates/compose/README.md +20 -0
  321. package/templates/plain/.devcontainer/devcontainer.json +35 -0
  322. package/templates/plain/README.md +21 -0
  323. package/tool/README.md +281 -0
  324. package/tool/schema/base-images.schema.json +43 -0
  325. package/tool/schema/base-templates.schema.json +34 -0
  326. package/tool/schema/config.schema.json +71 -0
  327. package/tool/schema/overlay-manifest.schema.json +86 -0
package/overlays/commitlint/README.md ADDED
@@ -0,0 +1,333 @@
1
+ # Commitlint Overlay
2
+
3
+ Enforce conventional commit messages for automated releases and changelogs.
4
+
5
+ ## What's Included
6
+
7
+ - **@commitlint/cli** - Commit message linter
8
+ - **@commitlint/config-conventional** - Conventional commits standard
9
+ - **commit-msg hook** - Automatic validation on commit
10
+ - **Sample configuration** - Ready-to-use commitlint.config.js
11
+
12
+ ## Conventional Commits Format
13
+
14
+ ```
15
+ <type>(<scope>): <subject>
16
+
17
+ <body>
18
+
19
+ <footer>
20
+ ```
21
+
22
+ ### Type (required)
23
+
24
+ - `feat` - New feature
25
+ - `fix` - Bug fix
26
+ - `docs` - Documentation changes
27
+ - `style` - Code style (formatting, semicolons)
28
+ - `refactor` - Code refactoring
29
+ - `perf` - Performance improvements
30
+ - `test` - Adding/updating tests
31
+ - `build` - Build system changes
32
+ - `ci` - CI/CD changes
33
+ - `chore` - Maintenance tasks
34
+ - `revert` - Revert previous commit
35
+
36
+ ### Scope (optional)
37
+
38
+ Component or module affected by the change:
39
+
40
+ ```
41
+ feat(auth): add OAuth2 support
42
+ fix(api): handle null responses
43
+ ```
44
+
45
+ ### Subject (required)
46
+
47
+ Short description (โ‰ค100 chars):
48
+
49
+ - Use imperative mood ("add" not "added")
50
+ - No period at the end
51
+ - Lowercase (conventional commits standard)
52
+
53
+ ### Body (optional)
54
+
55
+ Detailed explanation of the change:
56
+
57
+ ```
58
+ feat(auth): add OAuth2 authentication
59
+
60
+ Implements OAuth2 flow with support for GitHub, Google, and custom
61
+ providers. Includes token refresh and automatic retry logic.
62
+ ```
63
+
64
+ ### Footer (optional)
65
+
66
+ Breaking changes or issue references:
67
+
68
+ ```
69
+ feat(api): redesign authentication API
70
+
71
+ BREAKING CHANGE: Auth endpoints now require OAuth2 tokens instead of
72
+ API keys. Update client code to use new authentication flow.
73
+
74
+ Fixes #123
75
+ Closes #456
76
+ ```
77
+
78
+ ## Usage
79
+
80
+ ### Committing with Validation
81
+
82
+ The commit-msg hook automatically validates:
83
+
84
+ ```bash
85
+ git commit -m "feat: Add new feature"
86
+ # โœ“ Passes validation
87
+
88
+ git commit -m "Added new feature"
89
+ # โœ— Fails - missing type
90
+ ```
91
+
92
+ ### Test Commit Messages
93
+
94
+ Before committing:
95
+
96
+ ```bash
97
+ echo "feat(auth): add OAuth2" | commitlint
98
+ # โœ“ Valid
99
+
100
+ echo "Added OAuth2" | commitlint
101
+ # โœ— Invalid
102
+ ```
103
+
104
+ ### Interactive Commits (Commitizen)
105
+
106
+ Install commitizen for guided commit creation:
107
+
108
+ ```bash
109
+ npm install -g commitizen cz-conventional-changelog
110
+
111
+ # Configure
112
+ echo '{ "path": "cz-conventional-changelog" }' > .czrc
113
+
114
+ # Use instead of git commit
115
+ git cz
116
+ ```
117
+
118
+ ### Skip Validation
119
+
120
+ For exceptional cases:
121
+
122
+ ```bash
123
+ git commit --no-verify -m "WIP: temporary commit"
124
+ ```
125
+
126
+ ## Configuration
127
+
128
+ ### commitlint.config.js
129
+
130
+ The overlay creates a comprehensive configuration:
131
+
132
+ ```javascript
133
+ module.exports = {
134
+ extends: ['@commitlint/config-conventional'],
135
+ rules: {
136
+ 'type-enum': [2, 'always', ['feat', 'fix', 'docs', ...]],
137
+ 'subject-case': [2, 'always', 'lower-case'],
138
+ 'subject-max-length': [2, 'always', 100],
139
+ }
140
+ };
141
+ ```
142
+
143
+ ### Customizing Rules
144
+
145
+ Edit `commitlint.config.js`:
146
+
147
+ ```javascript
148
+ module.exports = {
149
+ extends: ['@commitlint/config-conventional'],
150
+ rules: {
151
+ // Custom types
152
+ 'type-enum': [
153
+ 2,
154
+ 'always',
155
+ [
156
+ 'feat',
157
+ 'fix',
158
+ 'docs',
159
+ 'custom-type', // Add your type
160
+ ],
161
+ ],
162
+
163
+ // Allow longer subjects
164
+ 'subject-max-length': [2, 'always', 150],
165
+
166
+ // Disable scope requirement
167
+ 'scope-empty': [0],
168
+ },
169
+ };
170
+ ```
171
+
172
+ ### Scopes
173
+
174
+ Define allowed scopes:
175
+
176
+ ```javascript
177
+ module.exports = {
178
+ extends: ['@commitlint/config-conventional'],
179
+ rules: {
180
+ 'scope-enum': [2, 'always', ['core', 'ui', 'api', 'auth', 'tests']],
181
+ },
182
+ };
183
+ ```
184
+
185
+ ## Integration with Semantic Release
186
+
187
+ Commitlint works seamlessly with semantic-release:
188
+
189
+ 1. Install semantic-release:
190
+
191
+ ```bash
192
+ npm install --save-dev semantic-release
193
+ ```
194
+
195
+ 2. Configure `.releaserc.json`:
196
+
197
+ ```json
198
+ {
199
+ "branches": ["main"],
200
+ "plugins": [
201
+ "@semantic-release/commit-analyzer",
202
+ "@semantic-release/release-notes-generator",
203
+ "@semantic-release/changelog",
204
+ "@semantic-release/npm",
205
+ "@semantic-release/github"
206
+ ]
207
+ }
208
+ ```
209
+
210
+ 3. Commits generate versions:
211
+ - `feat:` โ†’ Minor version (1.0.0 โ†’ 1.1.0)
212
+ - `fix:` โ†’ Patch version (1.0.0 โ†’ 1.0.1)
213
+ - `BREAKING CHANGE:` โ†’ Major version (1.0.0 โ†’ 2.0.0)
214
+
215
+ ## Integration with Pre-commit
216
+
217
+ Combine with pre-commit framework:
218
+
219
+ ```yaml
220
+ # .pre-commit-config.yaml
221
+ repos:
222
+ - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
223
+ rev: v9.11.0
224
+ hooks:
225
+ - id: commitlint
226
+ stages: [commit-msg]
227
+ additional_dependencies: ['@commitlint/config-conventional']
228
+ ```
229
+
230
+ ## Examples
231
+
232
+ ### Good Commit Messages
233
+
234
+ ```
235
+ feat(auth): add Google OAuth2 provider
236
+
237
+ fix(api): handle null responses in user endpoint
238
+ Fixes #123
239
+
240
+ docs: update installation guide
241
+
242
+ refactor(core): simplify error handling
243
+
244
+ perf(query): optimize database queries
245
+ Reduces query time by 50%
246
+
247
+ test(api): add integration tests for auth endpoints
248
+
249
+ build(deps): bump axios to v1.6.0
250
+
251
+ ci: add automated release workflow
252
+
253
+ chore: update .gitignore
254
+ ```
255
+
256
+ ### Bad Commit Messages
257
+
258
+ ```
259
+ Added OAuth2
260
+ โŒ Missing type
261
+
262
+ feat: added oauth2
263
+ โŒ Wrong tense (should be "add")
264
+
265
+ Feat(Auth): add OAuth2
266
+ โŒ Type should be lowercase, scope should be lowercase
267
+
268
+ feat(auth): add OAuth2.
269
+ โŒ Subject should not end with period
270
+
271
+ feat(auth): added oauth2 support for google and github providers
272
+ โŒ Subject too long, wrong tense
273
+ ```
274
+
275
+ ## Troubleshooting
276
+
277
+ ### Hook Not Running
278
+
279
+ Ensure hook is executable:
280
+
281
+ ```bash
282
+ chmod +x .git/hooks/commit-msg
283
+ ```
284
+
285
+ Reinstall hook:
286
+
287
+ ```bash
288
+ bash .devcontainer/commitlint-setup.sh
289
+ ```
290
+
291
+ ### Validation Fails
292
+
293
+ Check your message:
294
+
295
+ ```bash
296
+ echo "your message" | commitlint
297
+ ```
298
+
299
+ View rules:
300
+
301
+ ```bash
302
+ commitlint --print-config
303
+ ```
304
+
305
+ ### Skip Validation (Emergency)
306
+
307
+ ```bash
308
+ git commit --no-verify -m "emergency fix"
309
+ ```
310
+
311
+ ## Best Practices
312
+
313
+ 1. **Write meaningful subjects** - Clear, concise descriptions
314
+ 2. **Use imperative mood** - "Add feature" not "Added feature"
315
+ 3. **Reference issues** - Include "Fixes #123" in footer
316
+ 4. **Document breaking changes** - Use BREAKING CHANGE: prefix
317
+ 5. **Keep scope consistent** - Define scopes in config
318
+ 6. **Use body for context** - Explain the "why" not the "what"
319
+
320
+ ## Team Guidelines
321
+
322
+ 1. **Commit early and often** - Small, focused commits
323
+ 2. **One change per commit** - Easier to review and revert
324
+ 3. **Link to issues** - Traceability
325
+ 4. **Review before merge** - Validate commit messages in PRs
326
+ 5. **Automate releases** - Use semantic-release for changelog generation
327
+
328
+ ## Additional Resources
329
+
330
+ - [Conventional Commits Specification](https://www.conventionalcommits.org/)
331
+ - [Commitlint Documentation](https://commitlint.js.org/)
332
+ - [Semantic Release](https://semantic-release.gitbook.io/)
333
+ - [Commitizen](https://github.com/commitizen/cz-cli)
package/overlays/commitlint/devcontainer.patch.json ADDED
@@ -0,0 +1,8 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
3
+ "features": {
4
+ "ghcr.io/devcontainers/features/node:1": {
5
+ "version": "lts"
6
+ }
7
+ }
8
+ }
package/overlays/commitlint/overlay.yml ADDED
@@ -0,0 +1,16 @@
1
+ id: commitlint
2
+ name: Commitlint
3
+ description: Conventional commits validation for automated releases
4
+ category: dev
5
+ supports: []
6
+ requires:
7
+ - nodejs
8
+ suggests:
9
+ - pre-commit
10
+ conflicts: []
11
+ tags:
12
+ - dev
13
+ - git
14
+ - commits
15
+ - semantic-release
16
+ ports: []
package/overlays/commitlint/setup.sh ADDED
@@ -0,0 +1,234 @@
1
+ #!/bin/bash
2
+ # Commitlint setup script
3
+
4
+ set -e
5
+
6
+ echo "๐Ÿ“ Setting up commitlint..."
7
+
8
+ # Install commitlint and conventional commits config globally
9
+ npm install -g @commitlint/cli @commitlint/config-conventional
10
+
11
+ # Verify installation
12
+ if command -v commitlint &> /dev/null; then
13
+ echo "โœ“ commitlint installed: $(commitlint --version)"
14
+ else
15
+ echo "โœ— commitlint installation failed"
16
+ exit 1
17
+ fi
18
+
19
+ # Create commitlint.config.js if it doesn't exist
20
+ if [ ! -f commitlint.config.js ]; then
21
+ cat > commitlint.config.js << 'EOF'
22
+ // Commitlint configuration
23
+ // See https://commitlint.js.org for more information
24
+
25
+ module.exports = {
26
+ extends: ['@commitlint/config-conventional'],
27
+
28
+ // Custom rules
29
+ rules: {
30
+ // Type enum
31
+ 'type-enum': [
32
+ 2,
33
+ 'always',
34
+ [
35
+ 'feat', // New feature
36
+ 'fix', // Bug fix
37
+ 'docs', // Documentation changes
38
+ 'style', // Code style changes (formatting, semicolons, etc)
39
+ 'refactor', // Code refactoring
40
+ 'perf', // Performance improvements
41
+ 'test', // Adding or updating tests
42
+ 'build', // Build system changes
43
+ 'ci', // CI/CD changes
44
+ 'chore', // Other changes (dependencies, etc)
45
+ 'revert', // Revert previous commit
46
+ ],
47
+ ],
48
+
49
+ // Subject line requirements
50
+ 'subject-case': [2, 'always', 'lower-case'],
51
+ 'subject-empty': [2, 'never'],
52
+ 'subject-full-stop': [2, 'never', '.'],
53
+ 'subject-max-length': [2, 'always', 100],
54
+
55
+ // Body requirements
56
+ 'body-leading-blank': [2, 'always'],
57
+ 'body-max-line-length': [2, 'always', 100],
58
+
59
+ // Footer requirements
60
+ 'footer-leading-blank': [2, 'always'],
61
+
62
+ // Scope requirements (optional)
63
+ 'scope-case': [2, 'always', 'lower-case'],
64
+ },
65
+
66
+ // Prompt settings (for interactive commits)
67
+ prompt: {
68
+ settings: {},
69
+ messages: {
70
+ skip: ': skip',
71
+ max: 'upper %d chars',
72
+ min: '%d chars at least',
73
+ emptyWarning: 'can not be empty',
74
+ upperLimitWarning: 'over limit',
75
+ lowerLimitWarning: 'below limit',
76
+ },
77
+ questions: {
78
+ type: {
79
+ description: "Select the type of change that you're committing:",
80
+ enum: {
81
+ feat: {
82
+ description: 'A new feature',
83
+ title: 'Features',
84
+ emoji: 'โœจ',
85
+ },
86
+ fix: {
87
+ description: 'A bug fix',
88
+ title: 'Bug Fixes',
89
+ emoji: '๐Ÿ›',
90
+ },
91
+ docs: {
92
+ description: 'Documentation only changes',
93
+ title: 'Documentation',
94
+ emoji: '๐Ÿ“š',
95
+ },
96
+ style: {
97
+ description: 'Changes that do not affect the meaning of the code',
98
+ title: 'Styles',
99
+ emoji: '๐Ÿ’Ž',
100
+ },
101
+ refactor: {
102
+ description: 'A code change that neither fixes a bug nor adds a feature',
103
+ title: 'Code Refactoring',
104
+ emoji: 'โ™ป๏ธ',
105
+ },
106
+ perf: {
107
+ description: 'A code change that improves performance',
108
+ title: 'Performance Improvements',
109
+ emoji: '๐Ÿš€',
110
+ },
111
+ test: {
112
+ description: 'Adding missing tests or correcting existing tests',
113
+ title: 'Tests',
114
+ emoji: '๐Ÿงช',
115
+ },
116
+ build: {
117
+ description: 'Changes that affect the build system or external dependencies',
118
+ title: 'Builds',
119
+ emoji: '๐Ÿ› ',
120
+ },
121
+ ci: {
122
+ description: 'Changes to our CI configuration files and scripts',
123
+ title: 'Continuous Integrations',
124
+ emoji: 'โš™๏ธ',
125
+ },
126
+ chore: {
127
+ description: "Other changes that don't modify src or test files",
128
+ title: 'Chores',
129
+ emoji: 'โ™ป๏ธ',
130
+ },
131
+ revert: {
132
+ description: 'Reverts a previous commit',
133
+ title: 'Reverts',
134
+ emoji: '๐Ÿ—‘',
135
+ },
136
+ },
137
+ },
138
+ scope: {
139
+ description: 'What is the scope of this change (e.g. component or file name)',
140
+ },
141
+ subject: {
142
+ description: 'Write a short, imperative tense description of the change',
143
+ },
144
+ body: {
145
+ description: 'Provide a longer description of the change',
146
+ },
147
+ isBreaking: {
148
+ description: 'Are there any breaking changes?',
149
+ },
150
+ breakingBody: {
151
+ description: 'A BREAKING CHANGE commit requires a body. Please enter a longer description',
152
+ },
153
+ breaking: {
154
+ description: 'Describe the breaking changes',
155
+ },
156
+ isIssueAffected: {
157
+ description: 'Does this change affect any open issues?',
158
+ },
159
+ issuesBody: {
160
+ description: 'If issues are closed, the commit requires a body. Please enter a longer description',
161
+ },
162
+ issues: {
163
+ description: 'Add issue references (e.g. "fix #123", "re #123")',
164
+ },
165
+ },
166
+ },
167
+ };
168
+ EOF
169
+ echo "โœ“ commitlint.config.js created"
170
+ fi
171
+
172
+ # Create .commitlintrc.json if user prefers JSON format
173
+ if [ ! -f .commitlintrc.json ] && [ ! -f commitlint.config.js ]; then
174
+ cat > .commitlintrc.json << 'EOF'
175
+ {
176
+ "extends": ["@commitlint/config-conventional"],
177
+ "rules": {
178
+ "type-enum": [
179
+ 2,
180
+ "always",
181
+ [
182
+ "feat",
183
+ "fix",
184
+ "docs",
185
+ "style",
186
+ "refactor",
187
+ "perf",
188
+ "test",
189
+ "build",
190
+ "ci",
191
+ "chore",
192
+ "revert"
193
+ ]
194
+ ],
195
+ "subject-case": [2, "always", "lower-case"],
196
+ "subject-max-length": [2, "always", 100]
197
+ }
198
+ }
199
+ EOF
200
+ fi
201
+
202
+ # Install commit-msg hook
203
+ if [ -d .git ]; then
204
+ cat > .git/hooks/commit-msg << 'EOF'
205
+ #!/bin/bash
206
+ # Commitlint hook - validates commit messages
207
+
208
+ # Check if commitlint is available
209
+ if ! command -v commitlint &> /dev/null; then
210
+ echo "โš ๏ธ commitlint not found, skipping validation"
211
+ exit 0
212
+ fi
213
+
214
+ # Run commitlint
215
+ commitlint --edit "$1"
216
+ EOF
217
+ chmod +x .git/hooks/commit-msg
218
+ echo "โœ“ commit-msg hook installed"
219
+ else
220
+ echo "โš ๏ธ Not a git repository - skipping hook installation"
221
+ echo " Run the following command manually after git init:"
222
+ echo " echo '#!/bin/bash' > .git/hooks/commit-msg"
223
+ echo " echo 'commitlint --edit \$1' >> .git/hooks/commit-msg"
224
+ echo " chmod +x .git/hooks/commit-msg"
225
+ fi
226
+
227
+ echo "โœ“ Commitlint setup complete"
228
+ echo ""
229
+ echo "๐Ÿ’ก Usage:"
230
+ echo " - Commit messages must follow conventional commits format"
231
+ echo " - Format: type(scope): subject"
232
+ echo " - Example: feat(auth): Add OAuth2 authentication"
233
+ echo " - Test your message: echo 'feat: test' | commitlint"
234
+ echo " - Interactive commit: npx commitizen"