@catladder/cli 0.0.0-next-41642e39 → 0.0.0-next-a4361417
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.
|
@@ -75,6 +75,35 @@ Key concepts:
|
|
|
75
75
|
`.catladder-generated/gitlab/`, `.github/workflows/`) — but never
|
|
76
76
|
edit them.
|
|
77
77
|
|
|
78
|
+
## Escape hatches — last resort, and a signal to file an issue
|
|
79
|
+
|
|
80
|
+
catladder has two escape hatches for things it doesn't (yet) support
|
|
81
|
+
natively:
|
|
82
|
+
|
|
83
|
+
- **`customJobs`** (per component) — hand-written CI job specs injected
|
|
84
|
+
into the pipeline.
|
|
85
|
+
- **transform `hooks`** (top-level `hooks`) —
|
|
86
|
+
`transformFileBeforeWrite` / `transformYamlBeforeWrite` rewrite the
|
|
87
|
+
generated files just before they're written to disk.
|
|
88
|
+
|
|
89
|
+
Both work, but they are **fragile by design**: they depend on the exact
|
|
90
|
+
shape of catladder's generated output, so a catladder upgrade can break
|
|
91
|
+
them silently, and they sit outside everything the rest of the config
|
|
92
|
+
gives you (rules, caching, images, per-env logic, snapshots). Prefer a
|
|
93
|
+
first-class config option whenever one exists — check the `build`,
|
|
94
|
+
`deploy`, `releases`, and env/vars surfaces (and the sibling skills)
|
|
95
|
+
first.
|
|
96
|
+
|
|
97
|
+
**When you do reach for one, treat it as a missing-feature signal.** If
|
|
98
|
+
a dev needs `customJobs` or a transform hook, it almost always means
|
|
99
|
+
catladder is missing a capability that other projects will need too.
|
|
100
|
+
**Open an issue at
|
|
101
|
+
https://git.panter.ch/catladder/catladder/-/issues** describing the use
|
|
102
|
+
case (what you're trying to achieve and why the existing config can't
|
|
103
|
+
express it) so it can be generalized into a supported feature — and,
|
|
104
|
+
where possible, offer to help the dev write that issue. The goal is for
|
|
105
|
+
escape hatches to shrink over time, not accumulate.
|
|
106
|
+
|
|
78
107
|
## Related skills
|
|
79
108
|
|
|
80
109
|
- `catladder-builds` — the component `build` config (build types, Docker)
|
|
@@ -147,7 +147,11 @@ export type ComponentConfig<C extends ConfigProps = never> = {
|
|
|
147
147
|
* add custom jobs. Can be an array or a function that receives the context and returns an array of jobs.
|
|
148
148
|
* For convenience, all env vars are injectd as variables
|
|
149
149
|
*
|
|
150
|
-
*
|
|
150
|
+
* customJobs are a last-resort escape hatch. Prefer a first-class
|
|
151
|
+
* config option whenever one exists.
|
|
152
|
+
*
|
|
153
|
+
* Please raise an issue on
|
|
154
|
+
* https://git.panter.ch/catladder/catladder/-/issues
|
|
151
155
|
* to let us know about why you need to use custom jobs.
|
|
152
156
|
* This feedback will help us to generalize use cases
|
|
153
157
|
*/
|
|
@@ -22,6 +22,16 @@ export type FileHookContext = BaseHookContext & {
|
|
|
22
22
|
content: string;
|
|
23
23
|
};
|
|
24
24
|
type MaybePromise<T> = T | Promise<T>;
|
|
25
|
+
/**
|
|
26
|
+
* Transform hooks are a last-resort escape hatch: they rewrite the
|
|
27
|
+
* generated output right before it is written, so they depend on the
|
|
28
|
+
* exact shape of catladder's output and a catladder upgrade can break
|
|
29
|
+
* them silently. Prefer a first-class config option whenever one exists.
|
|
30
|
+
*
|
|
31
|
+
* If you need a hook, please raise an issue on
|
|
32
|
+
* https://git.panter.ch/catladder/catladder/-/issues describing the use
|
|
33
|
+
* case. This feedback helps us generalize it into a supported feature.
|
|
34
|
+
*/
|
|
25
35
|
export type Hooks = {
|
|
26
36
|
/**
|
|
27
37
|
* transform the file before it is written. If undefined is returned, the file is not modified
|
|
@@ -75,6 +75,35 @@ Key concepts:
|
|
|
75
75
|
`.catladder-generated/gitlab/`, `.github/workflows/`) — but never
|
|
76
76
|
edit them.
|
|
77
77
|
|
|
78
|
+
## Escape hatches — last resort, and a signal to file an issue
|
|
79
|
+
|
|
80
|
+
catladder has two escape hatches for things it doesn't (yet) support
|
|
81
|
+
natively:
|
|
82
|
+
|
|
83
|
+
- **`customJobs`** (per component) — hand-written CI job specs injected
|
|
84
|
+
into the pipeline.
|
|
85
|
+
- **transform `hooks`** (top-level `hooks`) —
|
|
86
|
+
`transformFileBeforeWrite` / `transformYamlBeforeWrite` rewrite the
|
|
87
|
+
generated files just before they're written to disk.
|
|
88
|
+
|
|
89
|
+
Both work, but they are **fragile by design**: they depend on the exact
|
|
90
|
+
shape of catladder's generated output, so a catladder upgrade can break
|
|
91
|
+
them silently, and they sit outside everything the rest of the config
|
|
92
|
+
gives you (rules, caching, images, per-env logic, snapshots). Prefer a
|
|
93
|
+
first-class config option whenever one exists — check the `build`,
|
|
94
|
+
`deploy`, `releases`, and env/vars surfaces (and the sibling skills)
|
|
95
|
+
first.
|
|
96
|
+
|
|
97
|
+
**When you do reach for one, treat it as a missing-feature signal.** If
|
|
98
|
+
a dev needs `customJobs` or a transform hook, it almost always means
|
|
99
|
+
catladder is missing a capability that other projects will need too.
|
|
100
|
+
**Open an issue at
|
|
101
|
+
https://git.panter.ch/catladder/catladder/-/issues** describing the use
|
|
102
|
+
case (what you're trying to achieve and why the existing config can't
|
|
103
|
+
express it) so it can be generalized into a supported feature — and,
|
|
104
|
+
where possible, offer to help the dev write that issue. The goal is for
|
|
105
|
+
escape hatches to shrink over time, not accumulate.
|
|
106
|
+
|
|
78
107
|
## Related skills
|
|
79
108
|
|
|
80
109
|
- `catladder-builds` — the component `build` config (build types, Docker)
|