@theholocron/astromech 5.0.0-alpha.155 → 5.0.0-alpha.156
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.
- package/README.md +2 -2
- package/dist/config/index.d.mts +17 -17
- package/dist/config/index.mjs +3 -3
- package/dist/index.d.mts +455 -455
- package/dist/index.mjs +381 -369
- package/dist/lint/index.d.mts +11 -11
- package/dist/lint/index.mjs +7 -7
- package/dist/{load-ToVjaKPr.mjs → load-DdHEVFlG.mjs} +3 -3
- package/dist/{schema.type-BUiSrwS5.d.mts → schema.type-B9k8EoOb.d.mts} +1 -1
- package/package.json +2 -2
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,72 @@
|
|
|
1
|
-
import { r as TasksConfig } from "./schema.type-
|
|
2
|
-
//#region src/generators/
|
|
1
|
+
import { r as TasksConfig } from "./schema.type-B9k8EoOb.mjs";
|
|
2
|
+
//#region src/generators/codecov/codecov.type.d.ts
|
|
3
|
+
interface WorkspacePackage {
|
|
4
|
+
slug: string;
|
|
5
|
+
name: string;
|
|
6
|
+
/** Which workspace root the package was discovered under. Defaults to `"packages"`. */
|
|
7
|
+
dir?: "packages" | "apps" | "plugins";
|
|
8
|
+
}
|
|
9
|
+
//#endregion
|
|
10
|
+
//#region src/generators/codecov/codecov.d.ts
|
|
11
|
+
declare function codecovComponentBlock(packages: WorkspacePackage[]): string;
|
|
12
|
+
/**
|
|
13
|
+
* Ensure every codecov status default carries `if_not_found: success`, so an
|
|
14
|
+
* infra-only PR (dep bump, config, lockfile — no coverable change) passes
|
|
15
|
+
* instead of hanging forever on a required check codecov never posts.
|
|
16
|
+
*
|
|
17
|
+
* Injects the key on the line after each `target:` that sits inside a status
|
|
18
|
+
* block (`coverage.status.*.default` or a `statuses:` list item — indent ≥ 8,
|
|
19
|
+
* or ≥ 8 for a `- type:` list entry), when the immediate sibling lines do not
|
|
20
|
+
* already declare it.
|
|
21
|
+
*/
|
|
22
|
+
declare function ensureIfNotFound(yaml: string): string;
|
|
23
|
+
declare function mergeCodecovComponents(existing: string, packages: WorkspacePackage[]): string;
|
|
24
|
+
/**
|
|
25
|
+
* Every public `packages/*`, `apps/*`, and `plugins/*` workspace, sorted by
|
|
26
|
+
* slug. `[]` when none of the three directories exist. Monorepo templates
|
|
27
|
+
* (Next.js, React, …) ship user-facing code under `apps/` alongside library
|
|
28
|
+
* code under `packages/`; `holocron` itself splits vendor plugin packages
|
|
29
|
+
* into their own `plugins/*` root — every recognized root needs a codecov
|
|
30
|
+
* component so `codecov/patch/<slug>` actually posts for each.
|
|
31
|
+
*/
|
|
32
|
+
declare function readWorkspacePackages(repoRoot: string): WorkspacePackage[];
|
|
33
|
+
/** A brand-new `codecov.yml` — the scaffold header + the base template + this repo's component list. */
|
|
34
|
+
declare function createCodecovConfig(packages: WorkspacePackage[]): string;
|
|
35
|
+
/**
|
|
36
|
+
* The full pipeline `holocron repo setup` needs: read this repo's public
|
|
37
|
+
* `packages/*`, then either merge them into an `existing` `codecov.yml` or
|
|
38
|
+
* scaffold a new one.
|
|
39
|
+
*/
|
|
40
|
+
declare function codecovConfig(repoRoot: string, existing: string | null): string;
|
|
41
|
+
//#endregion
|
|
42
|
+
//#region src/generators/github-action-reusable-workflows/github-action-reusable-workflows.d.ts
|
|
43
|
+
/**
|
|
44
|
+
* The **reusable** GitHub Actions surface pushed to `theholocron/.github` by
|
|
45
|
+
* `holocron sync github` — the `workflow_call` implementations and composite
|
|
46
|
+
* actions that every repo's thin callers delegate to.
|
|
47
|
+
*
|
|
48
|
+
* `theholocron/.github` is a **pure sync target**: `.github/workflows/*`,
|
|
49
|
+
* `.github/actions/*` and `workflow-templates/*` there are generated from the
|
|
50
|
+
* `.yml` files in `src/templates/reusable/` and pushed verbatim (with a
|
|
51
|
+
* "do not edit" header). Never hand-edit them in `.github`.
|
|
52
|
+
*
|
|
53
|
+
* Not to be confused with `WORKFLOW_TEMPLATES` in `github-action-thin-callers.ts` — those are
|
|
54
|
+
* the *thin-caller bases* written into each consumer repo's `.github/workflows/`.
|
|
55
|
+
*/
|
|
56
|
+
/** `workflow_call` implementations → `.github/workflows/<name>.yml`. */
|
|
57
|
+
declare const REUSABLE_WORKFLOWS: Record<string, string>;
|
|
58
|
+
/** Composite actions → `.github/actions/<name>/action.yml` (key includes `/action`). */
|
|
59
|
+
declare const REUSABLE_ACTIONS: Record<string, string>;
|
|
60
|
+
/** GitHub starter-workflow metadata → `workflow-templates/<name>.properties.json`. */
|
|
61
|
+
declare const WORKFLOW_TEMPLATE_PROPERTIES: Record<string, string>;
|
|
62
|
+
/**
|
|
63
|
+
* The complete file batch `holocron sync github` pushes to `theholocron/.github`:
|
|
64
|
+
* path → content. YAML gets the "do not edit" header; the starter-workflow
|
|
65
|
+
* `.properties.json` files are left bare (native JSON, not a commented file).
|
|
66
|
+
*/
|
|
67
|
+
declare function reusableTemplates(): Map<string, string>;
|
|
68
|
+
//#endregion
|
|
69
|
+
//#region src/generators/github-action-thin-callers/github-action-thin-callers.type.d.ts
|
|
3
70
|
interface PreviewConfig {
|
|
4
71
|
/** Cloudflare Pages project name shared across all repos for previews. */
|
|
5
72
|
project: string;
|
|
@@ -23,7 +90,124 @@ interface OrgContext {
|
|
|
23
90
|
repoName?: string;
|
|
24
91
|
}
|
|
25
92
|
//#endregion
|
|
26
|
-
//#region src/generators/
|
|
93
|
+
//#region src/generators/github-action-thin-callers/github-action-thin-callers.d.ts
|
|
94
|
+
declare const WORKFLOW_TEMPLATES: Record<string, string>;
|
|
95
|
+
declare const KNOWN_WORKFLOWS: Set<string>;
|
|
96
|
+
/**
|
|
97
|
+
* The GitHub status-check context a `required` task contributes to branch
|
|
98
|
+
* protection. Format: `"{workflow name} / {job name}"`.
|
|
99
|
+
*
|
|
100
|
+
* Most of these are single-job workflows now (D3's decomposition split what
|
|
101
|
+
* used to be multi-job `lint`/`audit` into one task per concern) — the
|
|
102
|
+
* context names that job directly, no `Conclusion` aggregator needed; a
|
|
103
|
+
* single job's own conclusion already *is* the workflow's conclusion.
|
|
104
|
+
* `Conclusion` fan-in jobs are kept only where a task genuinely has several
|
|
105
|
+
* conditionally-run jobs feeding one required check:
|
|
106
|
+
* `verification.unitTests` (unit / Storybook / Chromatic / interaction /
|
|
107
|
+
* user-flow, each gated by its own `run-*` input) and
|
|
108
|
+
* `platform.repoValidation` (its three script jobs all must pass). Only
|
|
109
|
+
* merge-gating workflows are listed. `astromech.requiredChecks()` reads this
|
|
110
|
+
* for every `required` task.
|
|
111
|
+
*/
|
|
112
|
+
declare const WORKFLOW_CHECK_CONTEXTS: Partial<Record<string, string>>;
|
|
113
|
+
/**
|
|
114
|
+
* Generate the thin caller content for a workflow, optionally injecting or
|
|
115
|
+
* merging `with:` overrides into the jobs block.
|
|
116
|
+
*
|
|
117
|
+
* Two strategies are used depending on the template:
|
|
118
|
+
* - Templates that already have a `with:` block (e.g. lint):
|
|
119
|
+
* the override entries are merged in, replacing existing keys and appending
|
|
120
|
+
* new ones.
|
|
121
|
+
* - Templates that end with ` secrets: inherit`: a new `with:` block is
|
|
122
|
+
* injected immediately before `secrets: inherit`.
|
|
123
|
+
* If neither pattern matches the template, a warning is emitted and the
|
|
124
|
+
* base template is returned unchanged.
|
|
125
|
+
*/
|
|
126
|
+
declare function generateThinCallerContent(name: string, withOverrides?: Record<string, unknown>, additionalPaths?: string[],
|
|
127
|
+
/** Optional sink for the "could not inject `with:`" warning. */
|
|
128
|
+
logger?: {
|
|
129
|
+
warn(obj: Record<string, unknown>, msg: string): void;
|
|
130
|
+
},
|
|
131
|
+
/**
|
|
132
|
+
* `with:` key → a `# comment` line rendered immediately above that entry.
|
|
133
|
+
* Only honored when injecting a fresh `with:` block (no template today
|
|
134
|
+
* ships one), which is the path `lint` takes.
|
|
135
|
+
*/
|
|
136
|
+
comments?: Record<string, string>): string;
|
|
137
|
+
/**
|
|
138
|
+
* Extract the Cloudflare Pages preview config from a deploy workflow's `with:` object.
|
|
139
|
+
*
|
|
140
|
+
* Accepts three forms:
|
|
141
|
+
* - `preview: true` — derive both project and domain from org context
|
|
142
|
+
* - `preview: { project: "..." }` — explicit project; domain derived from context if omitted
|
|
143
|
+
* - `preview: { project: "...", domain: "..." }` — fully explicit
|
|
144
|
+
*
|
|
145
|
+
* Returns null when `preview:` is absent, false, or can't be resolved.
|
|
146
|
+
*/
|
|
147
|
+
declare function extractPreviewConfig(raw: Record<string, unknown>, ctx?: OrgContext): PreviewConfig | null;
|
|
148
|
+
/**
|
|
149
|
+
* Generate the full thin-caller YAML for a `deploy.yml` that handles both
|
|
150
|
+
* production (push to main → GitHub Pages) and preview (pull_request →
|
|
151
|
+
* Cloudflare Pages) in a single file.
|
|
152
|
+
*
|
|
153
|
+
* Both jobs receive the same docs/storybook `with:` inputs. If the per-repo
|
|
154
|
+
* config supplies `cloudflare-project` it is forwarded; otherwise the reusable
|
|
155
|
+
* falls back to the `CLOUDFLARE_PAGES_PROJECT` org variable — set that once and
|
|
156
|
+
* all repos with a `deploy` workflow get previews without per-repo config.
|
|
157
|
+
*/
|
|
158
|
+
declare function generateCombinedDeployContent(deployWith: Record<string, unknown>, paths: string[], preview: Pick<PreviewConfig, "project">): string;
|
|
159
|
+
/**
|
|
160
|
+
* Expand structured with-values to flat GitHub Actions inputs before
|
|
161
|
+
* generating the thin caller. Handles:
|
|
162
|
+
* - deploy shorthand: docs/storybook → type + storybook-projects
|
|
163
|
+
* - preview: stripped (handled separately via extractPreviewConfig)
|
|
164
|
+
* - run-chromatic object → run-chromatic: true + chromatic-projects
|
|
165
|
+
* - plain arrays → JSON-stringified for YAML scalar quoting
|
|
166
|
+
*
|
|
167
|
+
* Used by both `holocron repo setup` and `sync-workflow-templates`.
|
|
168
|
+
*/
|
|
169
|
+
declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<string, unknown>;
|
|
170
|
+
/**
|
|
171
|
+
* Derive on.push.paths entries from the deploy with: shorthand.
|
|
172
|
+
* Used by both `holocron repo setup` and `sync-workflow-templates`.
|
|
173
|
+
*/
|
|
174
|
+
declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
|
|
175
|
+
//#endregion
|
|
176
|
+
//#region src/generators/required-checks/required-checks.d.ts
|
|
177
|
+
/** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
|
|
178
|
+
declare function requiredChecks(config: TasksConfig): string[];
|
|
179
|
+
//#endregion
|
|
180
|
+
//#region src/generators/tsconfig/tsconfig.type.d.ts
|
|
181
|
+
interface TsconfigOptions {
|
|
182
|
+
/** Human-readable name for the `display` field — the package's own name is the usual choice. */
|
|
183
|
+
display: string;
|
|
184
|
+
/**
|
|
185
|
+
* `@theholocron/tsconfig` variant. Defaults to `"node-lts"` — every
|
|
186
|
+
* checked package uses it; the other three (`astro`, `nextjs`, `react`)
|
|
187
|
+
* exist for a template repo's app-shaped packages, not the plain
|
|
188
|
+
* Node.js library packages this org's currently-migrated repos ship.
|
|
189
|
+
*/
|
|
190
|
+
variant?: "astro" | "nextjs" | "node-lts" | "react";
|
|
191
|
+
/**
|
|
192
|
+
* Add a `@/*` → `./src/*` path alias. A real per-package choice, not a
|
|
193
|
+
* default — roughly 40% of packages checked use one, the rest don't.
|
|
194
|
+
*/
|
|
195
|
+
paths?: boolean;
|
|
196
|
+
}
|
|
197
|
+
//#endregion
|
|
198
|
+
//#region src/generators/tsconfig/tsconfig.d.ts
|
|
199
|
+
/**
|
|
200
|
+
* A package-level `tsconfig.json` — the uniform shape confirmed across
|
|
201
|
+
* every package checked, parameterized only by the two fields that
|
|
202
|
+
* genuinely vary (`display`, `paths`). No scaffold/workflow header (matches
|
|
203
|
+
* `.alexrc.json`'s existing precedent for a strict-JSON Bucket B file —
|
|
204
|
+
* JSON has no comment syntax to carry one, and TypeScript's own tolerance
|
|
205
|
+
* for JSONC comments in `tsconfig.json` isn't worth relying on for a file
|
|
206
|
+
* this thin).
|
|
207
|
+
*/
|
|
208
|
+
declare function createTsconfig(options: TsconfigOptions): string;
|
|
209
|
+
//#endregion
|
|
210
|
+
//#region src/generators/turbo/turbo.type.d.ts
|
|
27
211
|
interface EnsureRootWorkspaceMemberResult {
|
|
28
212
|
content: string;
|
|
29
213
|
changed: boolean;
|
|
@@ -86,7 +270,10 @@ interface RunTaskReport {
|
|
|
86
270
|
message?: string;
|
|
87
271
|
}
|
|
88
272
|
//#endregion
|
|
89
|
-
//#region src/tasks/
|
|
273
|
+
//#region src/tasks/run/run.d.ts
|
|
274
|
+
declare function runTask(input: RunTaskInput): RunTaskReport;
|
|
275
|
+
//#endregion
|
|
276
|
+
//#region src/tasks/ci/ci.type.d.ts
|
|
90
277
|
interface CiOptions {
|
|
91
278
|
/** Print the plan without running anything. */
|
|
92
279
|
dryRun?: boolean;
|
|
@@ -112,356 +299,295 @@ interface CiInput extends RunDeps, CiOptions {
|
|
|
112
299
|
config: TasksConfig;
|
|
113
300
|
}
|
|
114
301
|
//#endregion
|
|
115
|
-
//#region src/tasks/
|
|
116
|
-
|
|
117
|
-
/** Print the resolved commands without running anything. */
|
|
118
|
-
dryRun?: boolean;
|
|
119
|
-
/** `turbo --filter=<pkg>` passthrough (monorepo). */
|
|
120
|
-
filter?: string;
|
|
121
|
-
}
|
|
122
|
-
interface GroupJobReport {
|
|
123
|
-
task: string;
|
|
124
|
-
status: "ok" | "fail" | "skip" | "dry-run";
|
|
125
|
-
command?: string;
|
|
126
|
-
message?: string;
|
|
127
|
-
}
|
|
128
|
-
interface GroupReport {
|
|
129
|
-
/** `"unknown"` when the namespace matches zero configured tasks. */
|
|
130
|
-
status: "ok" | "fail" | "dry-run" | "unknown";
|
|
131
|
-
jobs: GroupJobReport[];
|
|
132
|
-
}
|
|
133
|
-
interface GroupInput extends RunDeps, GroupOptions {
|
|
134
|
-
cwd: string;
|
|
135
|
-
config: TasksConfig;
|
|
136
|
-
/** The bare namespace, e.g. `"sourceQuality"` — matched against `"sourceQuality."`-prefixed task names. */
|
|
137
|
-
namespace: string;
|
|
138
|
-
}
|
|
302
|
+
//#region src/tasks/ci/ci.d.ts
|
|
303
|
+
declare function runCi(input: CiInput): CiReport;
|
|
139
304
|
//#endregion
|
|
140
|
-
//#region src/
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
305
|
+
//#region src/utils/create-header/create-header.type.d.ts
|
|
306
|
+
/** Comment style produced by workflowHeader. */
|
|
307
|
+
type WorkflowHeaderFormat = "yaml" | "cjs" | "shebang";
|
|
308
|
+
interface CreateHeaderOptions {
|
|
309
|
+
/** Path within theholocron/holocron that owns the file being generated. */
|
|
310
|
+
source: string;
|
|
311
|
+
/** CLI command that produces the file. Defaults to "holocron repo setup". */
|
|
312
|
+
tool?: string;
|
|
313
|
+
/** Set true only when writing to theholocron/.github itself. */
|
|
314
|
+
forPrimary?: boolean;
|
|
315
|
+
}
|
|
316
|
+
interface HeaderFunctions {
|
|
144
317
|
/**
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
318
|
+
* "AUTO-GENERATED — do not edit" header for files managed on every run.
|
|
319
|
+
*
|
|
320
|
+
* format:
|
|
321
|
+
* "yaml" — `# …` comment lines (YAML, text, ignore files)
|
|
322
|
+
* "cjs" — `/* … *\/` block comment (CommonJS modules)
|
|
323
|
+
* "shebang" — `#!/bin/sh` on line 1, then yaml header (shell scripts)
|
|
148
324
|
*/
|
|
149
|
-
|
|
325
|
+
workflowHeader(format?: WorkflowHeaderFormat): string;
|
|
150
326
|
/**
|
|
151
|
-
*
|
|
152
|
-
*
|
|
327
|
+
* "Scaffolded — edit this file freely" header for one-time generated files
|
|
328
|
+
* that the user is expected to take over (e.g. codecov.yml).
|
|
153
329
|
*/
|
|
154
|
-
|
|
155
|
-
/** Structured-logging sink. Defaults to a no-op. */
|
|
156
|
-
logger?: RunLogger;
|
|
157
|
-
/** User-facing line printer. Defaults to `console.log`. */
|
|
158
|
-
print?: (line: string) => void;
|
|
159
|
-
/** Injectable subprocess runner (tests). Defaults to `spawnSync` (stdio inherit). */
|
|
160
|
-
exec?: ExecFn;
|
|
161
|
-
/** Injectable fs (tests). Default to `node:fs`. */
|
|
162
|
-
readFile?: (path: string) => string;
|
|
163
|
-
fileExists?: (path: string) => boolean;
|
|
164
|
-
listDir?: (path: string) => string[];
|
|
165
|
-
/** Injectable binary lookup (tests). Default checks `node_modules/.bin` then `PATH`. */
|
|
166
|
-
lookPath?: (cwd: string, bin: string) => string | null;
|
|
167
|
-
}
|
|
168
|
-
interface RunOptions {
|
|
169
|
-
/**
|
|
170
|
-
* Sub-job within the task — `performance` in `holocron run audit
|
|
171
|
-
* performance`. Only meaningful for tasks that declare `jobs` (`audit`);
|
|
172
|
-
* ignored otherwise. Omit to run every job the task has.
|
|
173
|
-
*/
|
|
174
|
-
job?: string;
|
|
175
|
-
/** Args after `--`, forwarded to the tool / turbo / script. */
|
|
176
|
-
passthrough?: string[];
|
|
177
|
-
/** Print the resolved command without running it. */
|
|
178
|
-
dryRun?: boolean;
|
|
179
|
-
/** Fail (exit 1) instead of skipping when the repo has no such task. */
|
|
180
|
-
required?: boolean;
|
|
181
|
-
/** `turbo --filter=<pkg>` passthrough (monorepo). */
|
|
182
|
-
filter?: string;
|
|
183
|
-
}
|
|
184
|
-
interface Astromech {
|
|
185
|
-
/**
|
|
186
|
-
* Run one task — or one of its sub-jobs (`opts.job`) — locally. When
|
|
187
|
-
* `task` isn't an exact registry task but matches the prefix of one or
|
|
188
|
-
* more configured tasks (`"sourceQuality"` against `sourceQuality.*`),
|
|
189
|
-
* runs every matching task in sequence instead ({@link GroupReport}) —
|
|
190
|
-
* `opts.job` is ignored for a namespace match, since a job belongs to
|
|
191
|
-
* one task, not a namespace.
|
|
192
|
-
*/
|
|
193
|
-
run(task: string, opts?: RunOptions): RunTaskReport | GroupReport;
|
|
194
|
-
/**
|
|
195
|
-
* Run the merge-gating checks locally, in CI order — "will CI pass?".
|
|
196
|
-
* Default scope: `required: true` tasks (falls back to every `ci: true`
|
|
197
|
-
* task when nothing is marked required). Exit non-zero on any failure.
|
|
198
|
-
*/
|
|
199
|
-
ci(opts?: CiOptions): CiReport;
|
|
200
|
-
/**
|
|
201
|
-
* The `.github/workflows/*.yml` thin callers for this repo's manifest —
|
|
202
|
-
* `filename` → YAML content (no generated-by header; the caller adds it).
|
|
203
|
-
* One entry per `config.tasks` item that has a workflow template and is
|
|
204
|
-
* not `ci: false`.
|
|
205
|
-
*/
|
|
206
|
-
thinCallers(): Map<string, string>;
|
|
207
|
-
/**
|
|
208
|
-
* The complete reusable-workflow batch `holocron sync github` pushes to
|
|
209
|
-
* `theholocron/.github` — repo-relative path → content, "do not edit" header
|
|
210
|
-
* already applied to the YAML. Config-independent (the same for every repo).
|
|
211
|
-
*/
|
|
212
|
-
reusableTemplates(): Map<string, string>;
|
|
213
|
-
/**
|
|
214
|
-
* `package.json` scripts for this repo's manifest — the `"holocron"` entry
|
|
215
|
-
* (`config.holocronScript ?? "holocron"`) plus `"<task>": "holocron run
|
|
216
|
-
* <task>"` for every `config.tasks` item that is a runnable registry task
|
|
217
|
-
* and not `local: false`. Merge into `package.json`; never clobber. Empty
|
|
218
|
-
* when there is no config or `syncScripts: false`.
|
|
219
|
-
*/
|
|
220
|
-
packageScripts(): Record<string, string>;
|
|
221
|
-
/**
|
|
222
|
-
* Task names this repo's manifest can actually run locally — the same
|
|
223
|
-
* filter {@link packageScripts} applies (skips `local: false` and tasks
|
|
224
|
-
* with no local runner at all), but independent of `syncScripts`: a repo
|
|
225
|
-
* that opts out of generated `package.json` scripts still has real
|
|
226
|
-
* runnable tasks. Empty when there is no config. Backs `holocron`'s own
|
|
227
|
-
* interactive task picker (`run` with no task given).
|
|
228
|
-
*/
|
|
229
|
-
runnableTasks(): string[];
|
|
230
|
-
/**
|
|
231
|
-
* The branch-protection required-status-check contexts for this repo —
|
|
232
|
-
* every `required: true` task's check context plus `extraRequiredChecks`,
|
|
233
|
-
* ordered and de-duplicated. `holocron repo setup` prepends `"DCO"` and applies
|
|
234
|
-
* the list; this method is policy-free (manifest only).
|
|
235
|
-
*/
|
|
236
|
-
requiredChecks(): string[];
|
|
237
|
-
/**
|
|
238
|
-
* This repo's `codecov.yml` — component `paths` derived from `packages/*`.
|
|
239
|
-
* Pass the current file's content (`null` if none exists yet) to either
|
|
240
|
-
* merge the component list in or scaffold a fresh file. Policy-free same
|
|
241
|
-
* as {@link requiredChecks} — `holocron repo setup` owns writing the result.
|
|
242
|
-
*/
|
|
243
|
-
codecovConfig(existing: string | null): string;
|
|
244
|
-
/**
|
|
245
|
-
* The generated `turbo.json` for this repo's manifest, pretty-printed —
|
|
246
|
-
* write directly, no merge. `null` when no manifest task has turbo fan-out
|
|
247
|
-
* config (nothing to write). See {@link TurboTaskConfig} in `registry.ts`.
|
|
248
|
-
*/
|
|
249
|
-
turboConfig(): string | null;
|
|
250
|
-
/**
|
|
251
|
-
* Fixes #692: whenever {@link turboConfig} isn't `null`, this repo's root
|
|
252
|
-
* package needs to actually be a workspace member for the tasks it fans
|
|
253
|
-
* out — otherwise a root that's genuinely a directly-buildable package
|
|
254
|
-
* (not just an orchestrator) silently vanishes from `turbo run <task>`.
|
|
255
|
-
* Pass `pnpm-workspace.yaml`'s current content (or `""` if none exists —
|
|
256
|
-
* a no-op either way, since no `packages:` key means single-package mode
|
|
257
|
-
* already) and root `package.json`'s own `scripts` object — values and
|
|
258
|
-
* all, not just keys, so a task-name-matching script that's already the
|
|
259
|
-
* generated `holocron run <task> --` wrapper (predating this call, not
|
|
260
|
-
* written by it) is correctly excluded rather than treated as proof root
|
|
261
|
-
* is directly buildable (#846). `changed: false` means don't write
|
|
262
|
-
* anything — the file is already correct.
|
|
263
|
-
*/
|
|
264
|
-
ensureRootWorkspaceMember(workspaceYaml: string, rootScripts: Readonly<Record<string, string>>): EnsureRootWorkspaceMemberResult;
|
|
265
|
-
/**
|
|
266
|
-
* `turboConfig()` writes a `turbo.json` but never touches `package.json`
|
|
267
|
-
* — a repo with no local `turbo` devDependency falls back to whatever
|
|
268
|
-
* (if anything) is globally on `PATH`, per `run.ts`'s `resolveBin()`.
|
|
269
|
-
* Pass root `package.json`'s raw content and `pnpm-workspace.yaml`'s
|
|
270
|
-
* current content (checked for an existing `turbo` catalog entry, which
|
|
271
|
-
* takes precedence over the hardcoded fallback version). `changed: false`
|
|
272
|
-
* means don't write anything — `devDependencies.turbo` already exists.
|
|
273
|
-
*/
|
|
274
|
-
ensureTurboDependency(packageJson: string, workspaceYaml: string): EnsureTurboDependencyResult;
|
|
330
|
+
scaffoldHeader(): string;
|
|
275
331
|
}
|
|
276
332
|
//#endregion
|
|
277
|
-
//#region src/
|
|
278
|
-
declare function createAstromech(options: AstromechOptions): Astromech;
|
|
279
|
-
//#endregion
|
|
280
|
-
//#region src/generators/codecov.type.d.ts
|
|
281
|
-
interface WorkspacePackage {
|
|
282
|
-
slug: string;
|
|
283
|
-
name: string;
|
|
284
|
-
/** Which workspace root the package was discovered under. Defaults to `"packages"`. */
|
|
285
|
-
dir?: "packages" | "apps" | "plugins";
|
|
286
|
-
}
|
|
287
|
-
//#endregion
|
|
288
|
-
//#region src/generators/codecov.d.ts
|
|
289
|
-
declare function codecovComponentBlock(packages: WorkspacePackage[]): string;
|
|
290
|
-
/**
|
|
291
|
-
* Ensure every codecov status default carries `if_not_found: success`, so an
|
|
292
|
-
* infra-only PR (dep bump, config, lockfile — no coverable change) passes
|
|
293
|
-
* instead of hanging forever on a required check codecov never posts.
|
|
294
|
-
*
|
|
295
|
-
* Injects the key on the line after each `target:` that sits inside a status
|
|
296
|
-
* block (`coverage.status.*.default` or a `statuses:` list item — indent ≥ 8,
|
|
297
|
-
* or ≥ 8 for a `- type:` list entry), when the immediate sibling lines do not
|
|
298
|
-
* already declare it.
|
|
299
|
-
*/
|
|
300
|
-
declare function ensureIfNotFound(yaml: string): string;
|
|
301
|
-
declare function mergeCodecovComponents(existing: string, packages: WorkspacePackage[]): string;
|
|
302
|
-
/**
|
|
303
|
-
* Every public `packages/*`, `apps/*`, and `plugins/*` workspace, sorted by
|
|
304
|
-
* slug. `[]` when none of the three directories exist. Monorepo templates
|
|
305
|
-
* (Next.js, React, …) ship user-facing code under `apps/` alongside library
|
|
306
|
-
* code under `packages/`; `holocron` itself splits vendor plugin packages
|
|
307
|
-
* into their own `plugins/*` root — every recognized root needs a codecov
|
|
308
|
-
* component so `codecov/patch/<slug>` actually posts for each.
|
|
309
|
-
*/
|
|
310
|
-
declare function readWorkspacePackages(repoRoot: string): WorkspacePackage[];
|
|
311
|
-
/** A brand-new `codecov.yml` — the scaffold header + the base template + this repo's component list. */
|
|
312
|
-
declare function createCodecovConfig(packages: WorkspacePackage[]): string;
|
|
333
|
+
//#region src/utils/create-header/create-header.d.ts
|
|
313
334
|
/**
|
|
314
|
-
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
*/
|
|
318
|
-
declare function codecovConfig(repoRoot: string, existing: string | null): string;
|
|
319
|
-
//#endregion
|
|
320
|
-
//#region src/generators/github-action-reusable-workflows.d.ts
|
|
321
|
-
/**
|
|
322
|
-
* The **reusable** GitHub Actions surface pushed to `theholocron/.github` by
|
|
323
|
-
* `holocron sync github` — the `workflow_call` implementations and composite
|
|
324
|
-
* actions that every repo's thin callers delegate to.
|
|
325
|
-
*
|
|
326
|
-
* `theholocron/.github` is a **pure sync target**: `.github/workflows/*`,
|
|
327
|
-
* `.github/actions/*` and `workflow-templates/*` there are generated from the
|
|
328
|
-
* `.yml` files in `src/templates/reusable/` and pushed verbatim (with a
|
|
329
|
-
* "do not edit" header). Never hand-edit them in `.github`.
|
|
330
|
-
*
|
|
331
|
-
* Not to be confused with `WORKFLOW_TEMPLATES` in `github-action-thin-callers.ts` — those are
|
|
332
|
-
* the *thin-caller bases* written into each consumer repo's `.github/workflows/`.
|
|
333
|
-
*/
|
|
334
|
-
/** `workflow_call` implementations → `.github/workflows/<name>.yml`. */
|
|
335
|
-
declare const REUSABLE_WORKFLOWS: Record<string, string>;
|
|
336
|
-
/** Composite actions → `.github/actions/<name>/action.yml` (key includes `/action`). */
|
|
337
|
-
declare const REUSABLE_ACTIONS: Record<string, string>;
|
|
338
|
-
/** GitHub starter-workflow metadata → `workflow-templates/<name>.properties.json`. */
|
|
339
|
-
declare const WORKFLOW_TEMPLATE_PROPERTIES: Record<string, string>;
|
|
340
|
-
/**
|
|
341
|
-
* The complete file batch `holocron sync github` pushes to `theholocron/.github`:
|
|
342
|
-
* path → content. YAML gets the "do not edit" header; the starter-workflow
|
|
343
|
-
* `.properties.json` files are left bare (native JSON, not a commented file).
|
|
344
|
-
*/
|
|
345
|
-
declare function reusableTemplates(): Map<string, string>;
|
|
346
|
-
//#endregion
|
|
347
|
-
//#region src/generators/github-action-thin-callers.d.ts
|
|
348
|
-
declare const WORKFLOW_TEMPLATES: Record<string, string>;
|
|
349
|
-
declare const KNOWN_WORKFLOWS: Set<string>;
|
|
350
|
-
/**
|
|
351
|
-
* The GitHub status-check context a `required` task contributes to branch
|
|
352
|
-
* protection. Format: `"{workflow name} / {job name}"`.
|
|
335
|
+
* Factory that binds `source` and `tool` once and returns all header
|
|
336
|
+
* constructors for auto-generated files. Prefer this over passing source
|
|
337
|
+
* as a positional argument at every call site.
|
|
353
338
|
*
|
|
354
|
-
*
|
|
355
|
-
*
|
|
356
|
-
*
|
|
357
|
-
*
|
|
358
|
-
* `Conclusion` fan-in jobs are kept only where a task genuinely has several
|
|
359
|
-
* conditionally-run jobs feeding one required check:
|
|
360
|
-
* `verification.unitTests` (unit / Storybook / Chromatic / interaction /
|
|
361
|
-
* user-flow, each gated by its own `run-*` input) and
|
|
362
|
-
* `platform.repoValidation` (its three script jobs all must pass). Only
|
|
363
|
-
* merge-gating workflows are listed. `astromech.requiredChecks()` reads this
|
|
364
|
-
* for every `required` task.
|
|
365
|
-
*/
|
|
366
|
-
declare const WORKFLOW_CHECK_CONTEXTS: Partial<Record<string, string>>;
|
|
367
|
-
/**
|
|
368
|
-
* Generate the thin caller content for a workflow, optionally injecting or
|
|
369
|
-
* merging `with:` overrides into the jobs block.
|
|
339
|
+
* @example
|
|
340
|
+
* const { workflowHeader, scaffoldHeader } = createHeader({
|
|
341
|
+
* source: "packages/astromech/src/templates/configs/editorconfig/create-config.ts",
|
|
342
|
+
* });
|
|
370
343
|
*
|
|
371
|
-
*
|
|
372
|
-
*
|
|
373
|
-
*
|
|
374
|
-
* new ones.
|
|
375
|
-
* - Templates that end with ` secrets: inherit`: a new `with:` block is
|
|
376
|
-
* injected immediately before `secrets: inherit`.
|
|
377
|
-
* If neither pattern matches the template, a warning is emitted and the
|
|
378
|
-
* base template is returned unchanged.
|
|
379
|
-
*/
|
|
380
|
-
declare function generateThinCallerContent(name: string, withOverrides?: Record<string, unknown>, additionalPaths?: string[],
|
|
381
|
-
/** Optional sink for the "could not inject `with:`" warning. */
|
|
382
|
-
logger?: {
|
|
383
|
-
warn(obj: Record<string, unknown>, msg: string): void;
|
|
384
|
-
},
|
|
385
|
-
/**
|
|
386
|
-
* `with:` key → a `# comment` line rendered immediately above that entry.
|
|
387
|
-
* Only honored when injecting a fresh `with:` block (no template today
|
|
388
|
-
* ships one), which is the path `lint` takes.
|
|
389
|
-
*/
|
|
390
|
-
comments?: Record<string, string>): string;
|
|
391
|
-
/**
|
|
392
|
-
* Extract the Cloudflare Pages preview config from a deploy workflow's `with:` object.
|
|
344
|
+
* export function createConfig(): string {
|
|
345
|
+
* return `${workflowHeader()}${body}`;
|
|
346
|
+
* }
|
|
393
347
|
*
|
|
394
|
-
*
|
|
395
|
-
* - `preview: true` — derive both project and domain from org context
|
|
396
|
-
* - `preview: { project: "..." }` — explicit project; domain derived from context if omitted
|
|
397
|
-
* - `preview: { project: "...", domain: "..." }` — fully explicit
|
|
348
|
+
* ## Which header to use
|
|
398
349
|
*
|
|
399
|
-
*
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
* Generate the full thin-caller YAML for a `deploy.yml` that handles both
|
|
404
|
-
* production (push to main → GitHub Pages) and preview (pull_request →
|
|
405
|
-
* Cloudflare Pages) in a single file.
|
|
350
|
+
* | Function | When to use | User can edit? |
|
|
351
|
+
* |-------------------|----------------------------------------------------|----------------|
|
|
352
|
+
* | `workflowHeader` | Files overwritten on every setup / sync-github run | No — "AUTO-GENERATED — do not edit" |
|
|
353
|
+
* | `scaffoldHeader` | Files written once; user takes ownership after | Yes — "Scaffolded — edit this file freely" |
|
|
406
354
|
*
|
|
407
|
-
*
|
|
408
|
-
* config supplies `cloudflare-project` it is forwarded; otherwise the reusable
|
|
409
|
-
* falls back to the `CLOUDFLARE_PAGES_PROJECT` org variable — set that once and
|
|
410
|
-
* all repos with a `deploy` workflow get previews without per-repo config.
|
|
411
|
-
*/
|
|
412
|
-
declare function generateCombinedDeployContent(deployWith: Record<string, unknown>, paths: string[], preview: Pick<PreviewConfig, "project">): string;
|
|
413
|
-
/**
|
|
414
|
-
* Expand structured with-values to flat GitHub Actions inputs before
|
|
415
|
-
* generating the thin caller. Handles:
|
|
416
|
-
* - deploy shorthand: docs/storybook → type + storybook-projects
|
|
417
|
-
* - preview: stripped (handled separately via extractPreviewConfig)
|
|
418
|
-
* - run-chromatic object → run-chromatic: true + chromatic-projects
|
|
419
|
-
* - plain arrays → JSON-stringified for YAML scalar quoting
|
|
355
|
+
* ## `workflowHeader` formats
|
|
420
356
|
*
|
|
421
|
-
*
|
|
357
|
+
* | Format | Comment style | Used for |
|
|
358
|
+
* |---------------------|------------------------|-------------------------------------------------------|
|
|
359
|
+
* | `"yaml"` (default) | `# …` lines | YAML workflows, ignore files, `.editorconfig`, labeler|
|
|
360
|
+
* | `"cjs"` | `/* … *\/` block | CommonJS config files (`.cjs`) |
|
|
361
|
+
* | `"shebang"` | `#!/bin/sh` + `# …` | Shell scripts (`prepare-commit-msg`, hooks) |
|
|
422
362
|
*/
|
|
423
|
-
declare function
|
|
363
|
+
declare function createHeader(options: CreateHeaderOptions): HeaderFunctions;
|
|
364
|
+
//#endregion
|
|
365
|
+
//#region src/utils/default-run/default-run.type.d.ts
|
|
366
|
+
interface SpawnResult {
|
|
367
|
+
status: number | null;
|
|
368
|
+
stdout: string;
|
|
369
|
+
stderr: string;
|
|
370
|
+
}
|
|
371
|
+
type Run = (command: string, args: string[], options: Record<string, unknown>) => SpawnResult;
|
|
372
|
+
//#endregion
|
|
373
|
+
//#region src/tasks/deploy-on-release/workspace-packages/workspace-packages.type.d.ts
|
|
374
|
+
interface Tree {
|
|
375
|
+
readJson: (path: string) => unknown;
|
|
376
|
+
listDirs: (path: string) => string[];
|
|
377
|
+
}
|
|
378
|
+
//#endregion
|
|
379
|
+
//#region src/tasks/deploy-on-release/deploy-on-release.type.d.ts
|
|
380
|
+
interface DeployOnReleaseOptions {
|
|
381
|
+
cwd: string;
|
|
382
|
+
/** The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release. */
|
|
383
|
+
channel: string;
|
|
384
|
+
/** The previous release's commit; omitted when there is none, so every deploying channel match deploys. */
|
|
385
|
+
from?: string;
|
|
386
|
+
/** The release commit. Default `HEAD`. */
|
|
387
|
+
to?: string;
|
|
388
|
+
/** Where progress lines go (stdout in the CLI). */
|
|
389
|
+
print: (line: string) => void;
|
|
390
|
+
dryRun?: boolean;
|
|
391
|
+
}
|
|
392
|
+
interface DeployOnReleaseDeps extends Partial<Tree> {
|
|
393
|
+
run?: Run;
|
|
394
|
+
sleep?: (ms: number) => Promise<void>;
|
|
395
|
+
now?: () => number;
|
|
396
|
+
/** Reads a package folder's task manifest; `loadTasksConfig` by default. */
|
|
397
|
+
loadTasks?: (dir: string) => Promise<TasksConfig>;
|
|
398
|
+
}
|
|
399
|
+
interface DeployOnReleaseResult {
|
|
400
|
+
pkg: string;
|
|
401
|
+
status: "ok" | "fail" | "skip" | "dry-run";
|
|
402
|
+
message: string;
|
|
403
|
+
}
|
|
404
|
+
interface DeployOnReleaseReport {
|
|
405
|
+
/** `fail` if any package's deploy failed; `skip` if none applied to this release; else `ok`. */
|
|
406
|
+
status: "ok" | "fail" | "skip";
|
|
407
|
+
results: DeployOnReleaseResult[];
|
|
408
|
+
}
|
|
409
|
+
//#endregion
|
|
410
|
+
//#region src/tasks/deploy-on-release/deploy-on-release.d.ts
|
|
424
411
|
/**
|
|
425
|
-
*
|
|
426
|
-
*
|
|
412
|
+
* Deploys every package whose manifest declares a release-time deploy that
|
|
413
|
+
* applies to this release. Never throws for a deploy problem: each package's
|
|
414
|
+
* outcome is in the report, and `status: "fail"` is the caller's exit code.
|
|
427
415
|
*/
|
|
428
|
-
declare function
|
|
416
|
+
declare function deployOnRelease(options: DeployOnReleaseOptions, { run, readJson, listDirs, sleep, now, loadTasks }?: DeployOnReleaseDeps): Promise<DeployOnReleaseReport>;
|
|
429
417
|
//#endregion
|
|
430
|
-
//#region src/
|
|
431
|
-
|
|
432
|
-
|
|
418
|
+
//#region src/tasks/group/group.type.d.ts
|
|
419
|
+
interface GroupOptions {
|
|
420
|
+
/** Print the resolved commands without running anything. */
|
|
421
|
+
dryRun?: boolean;
|
|
422
|
+
/** `turbo --filter=<pkg>` passthrough (monorepo). */
|
|
423
|
+
filter?: string;
|
|
424
|
+
}
|
|
425
|
+
interface GroupJobReport {
|
|
426
|
+
task: string;
|
|
427
|
+
status: "ok" | "fail" | "skip" | "dry-run";
|
|
428
|
+
command?: string;
|
|
429
|
+
message?: string;
|
|
430
|
+
}
|
|
431
|
+
interface GroupReport {
|
|
432
|
+
/** `"unknown"` when the namespace matches zero configured tasks. */
|
|
433
|
+
status: "ok" | "fail" | "dry-run" | "unknown";
|
|
434
|
+
jobs: GroupJobReport[];
|
|
435
|
+
}
|
|
436
|
+
interface GroupInput extends RunDeps, GroupOptions {
|
|
437
|
+
cwd: string;
|
|
438
|
+
config: TasksConfig;
|
|
439
|
+
/** The bare namespace, e.g. `"sourceQuality"` — matched against `"sourceQuality."`-prefixed task names. */
|
|
440
|
+
namespace: string;
|
|
441
|
+
}
|
|
433
442
|
//#endregion
|
|
434
|
-
//#region src/
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
443
|
+
//#region src/tasks/group/group.d.ts
|
|
444
|
+
declare function runGroup(input: GroupInput): GroupReport;
|
|
445
|
+
//#endregion
|
|
446
|
+
//#region src/tasks/match-namespace/match-namespace.d.ts
|
|
447
|
+
/** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
|
|
448
|
+
declare function matchNamespace(config: TasksConfig, namespace: string): string[];
|
|
449
|
+
//#endregion
|
|
450
|
+
//#region src/astromech.type.d.ts
|
|
451
|
+
interface AstromechOptions {
|
|
452
|
+
/** Repo root. */
|
|
453
|
+
cwd: string;
|
|
454
|
+
/**
|
|
455
|
+
* The resolved task manifest. Optional for `run` (which is
|
|
456
|
+
* filesystem-driven); `thinCallers` / `packageScripts` / `ci` need it.
|
|
457
|
+
* Load it with `loadTasksConfig` from `@theholocron/astromech/config`.
|
|
458
|
+
*/
|
|
459
|
+
config?: TasksConfig;
|
|
460
|
+
/**
|
|
461
|
+
* Org context for the `deploy` workflow's `preview:` shorthand — used to
|
|
462
|
+
* derive the Cloudflare Pages project / domain when they are not spelt out.
|
|
463
|
+
*/
|
|
464
|
+
orgContext?: OrgContext;
|
|
465
|
+
/** Structured-logging sink. Defaults to a no-op. */
|
|
466
|
+
logger?: RunLogger;
|
|
467
|
+
/** User-facing line printer. Defaults to `console.log`. */
|
|
468
|
+
print?: (line: string) => void;
|
|
469
|
+
/** Injectable subprocess runner (tests). Defaults to `spawnSync` (stdio inherit). */
|
|
470
|
+
exec?: ExecFn;
|
|
471
|
+
/** Injectable fs (tests). Default to `node:fs`. */
|
|
472
|
+
readFile?: (path: string) => string;
|
|
473
|
+
fileExists?: (path: string) => boolean;
|
|
474
|
+
listDir?: (path: string) => string[];
|
|
475
|
+
/** Injectable binary lookup (tests). Default checks `node_modules/.bin` then `PATH`. */
|
|
476
|
+
lookPath?: (cwd: string, bin: string) => string | null;
|
|
477
|
+
}
|
|
478
|
+
interface RunOptions {
|
|
438
479
|
/**
|
|
439
|
-
*
|
|
440
|
-
*
|
|
441
|
-
*
|
|
442
|
-
* Node.js library packages this org's currently-migrated repos ship.
|
|
480
|
+
* Sub-job within the task — `performance` in `holocron run audit
|
|
481
|
+
* performance`. Only meaningful for tasks that declare `jobs` (`audit`);
|
|
482
|
+
* ignored otherwise. Omit to run every job the task has.
|
|
443
483
|
*/
|
|
444
|
-
|
|
484
|
+
job?: string;
|
|
485
|
+
/** Args after `--`, forwarded to the tool / turbo / script. */
|
|
486
|
+
passthrough?: string[];
|
|
487
|
+
/** Print the resolved command without running it. */
|
|
488
|
+
dryRun?: boolean;
|
|
489
|
+
/** Fail (exit 1) instead of skipping when the repo has no such task. */
|
|
490
|
+
required?: boolean;
|
|
491
|
+
/** `turbo --filter=<pkg>` passthrough (monorepo). */
|
|
492
|
+
filter?: string;
|
|
493
|
+
}
|
|
494
|
+
interface Astromech {
|
|
445
495
|
/**
|
|
446
|
-
*
|
|
447
|
-
*
|
|
496
|
+
* Run one task — or one of its sub-jobs (`opts.job`) — locally. When
|
|
497
|
+
* `task` isn't an exact registry task but matches the prefix of one or
|
|
498
|
+
* more configured tasks (`"sourceQuality"` against `sourceQuality.*`),
|
|
499
|
+
* runs every matching task in sequence instead ({@link GroupReport}) —
|
|
500
|
+
* `opts.job` is ignored for a namespace match, since a job belongs to
|
|
501
|
+
* one task, not a namespace.
|
|
448
502
|
*/
|
|
449
|
-
|
|
503
|
+
run(task: string, opts?: RunOptions): RunTaskReport | GroupReport;
|
|
504
|
+
/**
|
|
505
|
+
* Run the merge-gating checks locally, in CI order — "will CI pass?".
|
|
506
|
+
* Default scope: `required: true` tasks (falls back to every `ci: true`
|
|
507
|
+
* task when nothing is marked required). Exit non-zero on any failure.
|
|
508
|
+
*/
|
|
509
|
+
ci(opts?: CiOptions): CiReport;
|
|
510
|
+
/**
|
|
511
|
+
* The `.github/workflows/*.yml` thin callers for this repo's manifest —
|
|
512
|
+
* `filename` → YAML content (no generated-by header; the caller adds it).
|
|
513
|
+
* One entry per `config.tasks` item that has a workflow template and is
|
|
514
|
+
* not `ci: false`.
|
|
515
|
+
*/
|
|
516
|
+
thinCallers(): Map<string, string>;
|
|
517
|
+
/**
|
|
518
|
+
* The complete reusable-workflow batch `holocron sync github` pushes to
|
|
519
|
+
* `theholocron/.github` — repo-relative path → content, "do not edit" header
|
|
520
|
+
* already applied to the YAML. Config-independent (the same for every repo).
|
|
521
|
+
*/
|
|
522
|
+
reusableTemplates(): Map<string, string>;
|
|
523
|
+
/**
|
|
524
|
+
* `package.json` scripts for this repo's manifest — the `"holocron"` entry
|
|
525
|
+
* (`config.holocronScript ?? "holocron"`) plus `"<task>": "holocron run
|
|
526
|
+
* <task>"` for every `config.tasks` item that is a runnable registry task
|
|
527
|
+
* and not `local: false`. Merge into `package.json`; never clobber. Empty
|
|
528
|
+
* when there is no config or `syncScripts: false`.
|
|
529
|
+
*/
|
|
530
|
+
packageScripts(): Record<string, string>;
|
|
531
|
+
/**
|
|
532
|
+
* Task names this repo's manifest can actually run locally — the same
|
|
533
|
+
* filter {@link packageScripts} applies (skips `local: false` and tasks
|
|
534
|
+
* with no local runner at all), but independent of `syncScripts`: a repo
|
|
535
|
+
* that opts out of generated `package.json` scripts still has real
|
|
536
|
+
* runnable tasks. Empty when there is no config. Backs `holocron`'s own
|
|
537
|
+
* interactive task picker (`run` with no task given).
|
|
538
|
+
*/
|
|
539
|
+
runnableTasks(): string[];
|
|
540
|
+
/**
|
|
541
|
+
* The branch-protection required-status-check contexts for this repo —
|
|
542
|
+
* every `required: true` task's check context plus `extraRequiredChecks`,
|
|
543
|
+
* ordered and de-duplicated. `holocron repo setup` prepends `"DCO"` and applies
|
|
544
|
+
* the list; this method is policy-free (manifest only).
|
|
545
|
+
*/
|
|
546
|
+
requiredChecks(): string[];
|
|
547
|
+
/**
|
|
548
|
+
* This repo's `codecov.yml` — component `paths` derived from `packages/*`.
|
|
549
|
+
* Pass the current file's content (`null` if none exists yet) to either
|
|
550
|
+
* merge the component list in or scaffold a fresh file. Policy-free same
|
|
551
|
+
* as {@link requiredChecks} — `holocron repo setup` owns writing the result.
|
|
552
|
+
*/
|
|
553
|
+
codecovConfig(existing: string | null): string;
|
|
554
|
+
/**
|
|
555
|
+
* The generated `turbo.json` for this repo's manifest, pretty-printed —
|
|
556
|
+
* write directly, no merge. `null` when no manifest task has turbo fan-out
|
|
557
|
+
* config (nothing to write). See {@link TurboTaskConfig} in `registry.ts`.
|
|
558
|
+
*/
|
|
559
|
+
turboConfig(): string | null;
|
|
560
|
+
/**
|
|
561
|
+
* Fixes #692: whenever {@link turboConfig} isn't `null`, this repo's root
|
|
562
|
+
* package needs to actually be a workspace member for the tasks it fans
|
|
563
|
+
* out — otherwise a root that's genuinely a directly-buildable package
|
|
564
|
+
* (not just an orchestrator) silently vanishes from `turbo run <task>`.
|
|
565
|
+
* Pass `pnpm-workspace.yaml`'s current content (or `""` if none exists —
|
|
566
|
+
* a no-op either way, since no `packages:` key means single-package mode
|
|
567
|
+
* already) and root `package.json`'s own `scripts` object — values and
|
|
568
|
+
* all, not just keys, so a task-name-matching script that's already the
|
|
569
|
+
* generated `holocron run <task> --` wrapper (predating this call, not
|
|
570
|
+
* written by it) is correctly excluded rather than treated as proof root
|
|
571
|
+
* is directly buildable (#846). `changed: false` means don't write
|
|
572
|
+
* anything — the file is already correct.
|
|
573
|
+
*/
|
|
574
|
+
ensureRootWorkspaceMember(workspaceYaml: string, rootScripts: Readonly<Record<string, string>>): EnsureRootWorkspaceMemberResult;
|
|
575
|
+
/**
|
|
576
|
+
* `turboConfig()` writes a `turbo.json` but never touches `package.json`
|
|
577
|
+
* — a repo with no local `turbo` devDependency falls back to whatever
|
|
578
|
+
* (if anything) is globally on `PATH`, per `run.ts`'s `resolveBin()`.
|
|
579
|
+
* Pass root `package.json`'s raw content and `pnpm-workspace.yaml`'s
|
|
580
|
+
* current content (checked for an existing `turbo` catalog entry, which
|
|
581
|
+
* takes precedence over the hardcoded fallback version). `changed: false`
|
|
582
|
+
* means don't write anything — `devDependencies.turbo` already exists.
|
|
583
|
+
*/
|
|
584
|
+
ensureTurboDependency(packageJson: string, workspaceYaml: string): EnsureTurboDependencyResult;
|
|
450
585
|
}
|
|
451
586
|
//#endregion
|
|
452
|
-
//#region src/
|
|
453
|
-
|
|
454
|
-
* A package-level `tsconfig.json` — the uniform shape confirmed across
|
|
455
|
-
* every package checked, parameterized only by the two fields that
|
|
456
|
-
* genuinely vary (`display`, `paths`). No scaffold/workflow header (matches
|
|
457
|
-
* `.alexrc.json`'s existing precedent for a strict-JSON Bucket B file —
|
|
458
|
-
* JSON has no comment syntax to carry one, and TypeScript's own tolerance
|
|
459
|
-
* for JSONC comments in `tsconfig.json` isn't worth relying on for a file
|
|
460
|
-
* this thin).
|
|
461
|
-
*/
|
|
462
|
-
declare function createTsconfig(options: TsconfigOptions): string;
|
|
587
|
+
//#region src/astromech.d.ts
|
|
588
|
+
declare function createAstromech(options: AstromechOptions): Astromech;
|
|
463
589
|
//#endregion
|
|
464
|
-
//#region src/registry.type.d.ts
|
|
590
|
+
//#region src/registry/registry.type.d.ts
|
|
465
591
|
/** How to run one task (or job) locally. */
|
|
466
592
|
interface LocalRunner {
|
|
467
593
|
/** Binary to invoke — resolved from `node_modules/.bin` then PATH. */
|
|
@@ -538,7 +664,7 @@ interface TaskDef {
|
|
|
538
664
|
turbo?: TurboTaskConfig;
|
|
539
665
|
}
|
|
540
666
|
//#endregion
|
|
541
|
-
//#region src/registry.d.ts
|
|
667
|
+
//#region src/registry/registry.d.ts
|
|
542
668
|
/**
|
|
543
669
|
* The task registry — how each task runs *locally*, without GitHub
|
|
544
670
|
* Actions. `holocron run <task>` and `holocron run ci` resolve against this;
|
|
@@ -571,72 +697,6 @@ declare const KNOWN_TASKS: Set<string>;
|
|
|
571
697
|
*/
|
|
572
698
|
declare const CI_ORDER: string[];
|
|
573
699
|
//#endregion
|
|
574
|
-
//#region src/tasks/ci.d.ts
|
|
575
|
-
declare function runCi(input: CiInput): CiReport;
|
|
576
|
-
//#endregion
|
|
577
|
-
//#region src/utils/default-run.type.d.ts
|
|
578
|
-
interface SpawnResult {
|
|
579
|
-
status: number | null;
|
|
580
|
-
stdout: string;
|
|
581
|
-
stderr: string;
|
|
582
|
-
}
|
|
583
|
-
type Run = (command: string, args: string[], options: Record<string, unknown>) => SpawnResult;
|
|
584
|
-
//#endregion
|
|
585
|
-
//#region src/tasks/deploy-on-release/workspace-packages.type.d.ts
|
|
586
|
-
interface Tree {
|
|
587
|
-
readJson: (path: string) => unknown;
|
|
588
|
-
listDirs: (path: string) => string[];
|
|
589
|
-
}
|
|
590
|
-
//#endregion
|
|
591
|
-
//#region src/tasks/deploy-on-release/deploy-on-release.type.d.ts
|
|
592
|
-
interface DeployOnReleaseOptions {
|
|
593
|
-
cwd: string;
|
|
594
|
-
/** The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release. */
|
|
595
|
-
channel: string;
|
|
596
|
-
/** The previous release's commit; omitted when there is none, so every deploying channel match deploys. */
|
|
597
|
-
from?: string;
|
|
598
|
-
/** The release commit. Default `HEAD`. */
|
|
599
|
-
to?: string;
|
|
600
|
-
/** Where progress lines go (stdout in the CLI). */
|
|
601
|
-
print: (line: string) => void;
|
|
602
|
-
dryRun?: boolean;
|
|
603
|
-
}
|
|
604
|
-
interface DeployOnReleaseDeps extends Partial<Tree> {
|
|
605
|
-
run?: Run;
|
|
606
|
-
sleep?: (ms: number) => Promise<void>;
|
|
607
|
-
now?: () => number;
|
|
608
|
-
/** Reads a package folder's task manifest; `loadTasksConfig` by default. */
|
|
609
|
-
loadTasks?: (dir: string) => Promise<TasksConfig>;
|
|
610
|
-
}
|
|
611
|
-
interface DeployOnReleaseResult {
|
|
612
|
-
pkg: string;
|
|
613
|
-
status: "ok" | "fail" | "skip" | "dry-run";
|
|
614
|
-
message: string;
|
|
615
|
-
}
|
|
616
|
-
interface DeployOnReleaseReport {
|
|
617
|
-
/** `fail` if any package's deploy failed; `skip` if none applied to this release; else `ok`. */
|
|
618
|
-
status: "ok" | "fail" | "skip";
|
|
619
|
-
results: DeployOnReleaseResult[];
|
|
620
|
-
}
|
|
621
|
-
//#endregion
|
|
622
|
-
//#region src/tasks/deploy-on-release/deploy-on-release.d.ts
|
|
623
|
-
/**
|
|
624
|
-
* Deploys every package whose manifest declares a release-time deploy that
|
|
625
|
-
* applies to this release. Never throws for a deploy problem: each package's
|
|
626
|
-
* outcome is in the report, and `status: "fail"` is the caller's exit code.
|
|
627
|
-
*/
|
|
628
|
-
declare function deployOnRelease(options: DeployOnReleaseOptions, { run, readJson, listDirs, sleep, now, loadTasks }?: DeployOnReleaseDeps): Promise<DeployOnReleaseReport>;
|
|
629
|
-
//#endregion
|
|
630
|
-
//#region src/tasks/group.d.ts
|
|
631
|
-
declare function runGroup(input: GroupInput): GroupReport;
|
|
632
|
-
//#endregion
|
|
633
|
-
//#region src/tasks/match-namespace.d.ts
|
|
634
|
-
/** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
|
|
635
|
-
declare function matchNamespace(config: TasksConfig, namespace: string): string[];
|
|
636
|
-
//#endregion
|
|
637
|
-
//#region src/tasks/run/run.d.ts
|
|
638
|
-
declare function runTask(input: RunTaskInput): RunTaskReport;
|
|
639
|
-
//#endregion
|
|
640
700
|
//#region src/templates/configs/alexjs/create-config.d.ts
|
|
641
701
|
declare function createRcConfig(): string;
|
|
642
702
|
declare function createIgnoreConfig(): string;
|
|
@@ -712,64 +772,4 @@ declare function createConfig$8(): string;
|
|
|
712
772
|
declare function createConfig$9(): string;
|
|
713
773
|
declare function createIgnoreConfig$1(): string;
|
|
714
774
|
//#endregion
|
|
715
|
-
//#region src/utils/create-header.type.d.ts
|
|
716
|
-
/** Comment style produced by workflowHeader. */
|
|
717
|
-
type WorkflowHeaderFormat = "yaml" | "cjs" | "shebang";
|
|
718
|
-
interface CreateHeaderOptions {
|
|
719
|
-
/** Path within theholocron/holocron that owns the file being generated. */
|
|
720
|
-
source: string;
|
|
721
|
-
/** CLI command that produces the file. Defaults to "holocron repo setup". */
|
|
722
|
-
tool?: string;
|
|
723
|
-
/** Set true only when writing to theholocron/.github itself. */
|
|
724
|
-
forPrimary?: boolean;
|
|
725
|
-
}
|
|
726
|
-
interface HeaderFunctions {
|
|
727
|
-
/**
|
|
728
|
-
* "AUTO-GENERATED — do not edit" header for files managed on every run.
|
|
729
|
-
*
|
|
730
|
-
* format:
|
|
731
|
-
* "yaml" — `# …` comment lines (YAML, text, ignore files)
|
|
732
|
-
* "cjs" — `/* … *\/` block comment (CommonJS modules)
|
|
733
|
-
* "shebang" — `#!/bin/sh` on line 1, then yaml header (shell scripts)
|
|
734
|
-
*/
|
|
735
|
-
workflowHeader(format?: WorkflowHeaderFormat): string;
|
|
736
|
-
/**
|
|
737
|
-
* "Scaffolded — edit this file freely" header for one-time generated files
|
|
738
|
-
* that the user is expected to take over (e.g. codecov.yml).
|
|
739
|
-
*/
|
|
740
|
-
scaffoldHeader(): string;
|
|
741
|
-
}
|
|
742
|
-
//#endregion
|
|
743
|
-
//#region src/utils/create-header.d.ts
|
|
744
|
-
/**
|
|
745
|
-
* Factory that binds `source` and `tool` once and returns all header
|
|
746
|
-
* constructors for auto-generated files. Prefer this over passing source
|
|
747
|
-
* as a positional argument at every call site.
|
|
748
|
-
*
|
|
749
|
-
* @example
|
|
750
|
-
* const { workflowHeader, scaffoldHeader } = createHeader({
|
|
751
|
-
* source: "packages/astromech/src/templates/configs/editorconfig/create-config.ts",
|
|
752
|
-
* });
|
|
753
|
-
*
|
|
754
|
-
* export function createConfig(): string {
|
|
755
|
-
* return `${workflowHeader()}${body}`;
|
|
756
|
-
* }
|
|
757
|
-
*
|
|
758
|
-
* ## Which header to use
|
|
759
|
-
*
|
|
760
|
-
* | Function | When to use | User can edit? |
|
|
761
|
-
* |-------------------|----------------------------------------------------|----------------|
|
|
762
|
-
* | `workflowHeader` | Files overwritten on every setup / sync-github run | No — "AUTO-GENERATED — do not edit" |
|
|
763
|
-
* | `scaffoldHeader` | Files written once; user takes ownership after | Yes — "Scaffolded — edit this file freely" |
|
|
764
|
-
*
|
|
765
|
-
* ## `workflowHeader` formats
|
|
766
|
-
*
|
|
767
|
-
* | Format | Comment style | Used for |
|
|
768
|
-
* |---------------------|------------------------|-------------------------------------------------------|
|
|
769
|
-
* | `"yaml"` (default) | `# …` lines | YAML workflows, ignore files, `.editorconfig`, labeler|
|
|
770
|
-
* | `"cjs"` | `/* … *\/` block | CommonJS config files (`.cjs`) |
|
|
771
|
-
* | `"shebang"` | `#!/bin/sh` + `# …` | Shell scripts (`prepare-commit-msg`, hooks) |
|
|
772
|
-
*/
|
|
773
|
-
declare function createHeader(options: CreateHeaderOptions): HeaderFunctions;
|
|
774
|
-
//#endregion
|
|
775
775
|
export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type CreateHeaderOptions, type DeployOnReleaseOptions, type DeployOnReleaseReport, type DeployOnReleaseResult, type ExecFn, type GroupJobReport, type GroupOptions, type GroupReport, type HeaderFunctions, type JobDef, KNOWN_TASKS, KNOWN_WORKFLOWS, type LocalRunner, type OrgContext, type PreviewConfig, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, type TsconfigOptions, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, type WorkflowHeaderFormat, type WorkspacePackage, codecovComponentBlock, codecovConfig, createIgnoreConfig as createAlexignore, createRcConfig as createAlexrc, createAstromech, createCodecovConfig, createConfig as createCommitMsg, createConfig$1 as createDependabot, createConfig$2 as createDevmoji, createConfig$3 as createEditorconfig, createConfig$4 as createEditorconfigChecker, createHeader, createConfig$5 as createLabeler, createConfig$6 as createPreCommit, createConfig$7 as createPrePush, createConfig$8 as createPrepareCommitMsg, createTsconfig, createIgnoreConfig$1 as createYamlignore, createConfig$9 as createYamllint, deployOnRelease, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, matchNamespace, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, reusableTemplates, runCi, runGroup, runTask };
|