@elumixor/devkit 0.4.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +40 -0
- package/package.json +1 -1
- package/src/bin/devkit.ts +8 -0
- package/src/config.ts +20 -3
- package/src/deploy.ts +254 -0
- package/src/dev.ts +1 -0
package/README.md
CHANGED
|
@@ -40,6 +40,46 @@ Each app runs `bun --filter <name> dev` by default. Override with:
|
|
|
40
40
|
| `color` | prefix color (blue, magenta, green, yellow, cyan, red) |
|
|
41
41
|
| `open` | with `--open`, open this app's URL when its port comes up |
|
|
42
42
|
|
|
43
|
+
## Deploy
|
|
44
|
+
|
|
45
|
+
`devkit deploy` runs the release steps of a repo the same way `devkit` runs its dev processes:
|
|
46
|
+
side by side, with one line each.
|
|
47
|
+
|
|
48
|
+
```jsonc
|
|
49
|
+
{
|
|
50
|
+
"scripts": { "deploy": "devkit deploy" },
|
|
51
|
+
"devkit": {
|
|
52
|
+
"deploy": [
|
|
53
|
+
{ "name": "desktop", "command": "bun scripts/deploy-desktop.ts", "color": "yellow" },
|
|
54
|
+
{ "name": "vercel", "command": "bun scripts/deploy-vercel.ts", "needs": ["desktop"] },
|
|
55
|
+
{ "name": "ios", "command": "bun scripts/deploy-ios.ts" }
|
|
56
|
+
]
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
bun run deploy # every target
|
|
63
|
+
bun run deploy ios # one target, plus whatever it needs
|
|
64
|
+
devkit deploy --dry # print the plan
|
|
65
|
+
devkit deploy --verbose # stream every line instead of the live board
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Targets with no `needs` start together; one with `needs` waits for those, so a build that another
|
|
69
|
+
target packages up can run first without serialising the whole release.
|
|
70
|
+
|
|
71
|
+
Each target shows a spinner, how long it has been running and the last line it printed. The full
|
|
72
|
+
output goes to `.devkit/deploy/<name>.log`, and the tail of whichever target failed is printed at
|
|
73
|
+
the end — a release prints tens of thousands of lines, and interleaving all of them is unreadable.
|
|
74
|
+
Piped output (CI, a log file) gets prefixed streaming lines instead of the board.
|
|
75
|
+
|
|
76
|
+
| field | meaning |
|
|
77
|
+
| --------- | -------------------------------------------------- |
|
|
78
|
+
| `name` | display name, and how it's named on the command line |
|
|
79
|
+
| `command` | shell command that performs this deploy |
|
|
80
|
+
| `needs` | targets that must finish first |
|
|
81
|
+
| `color` | colour of this target's line |
|
|
82
|
+
|
|
43
83
|
## Setting up a machine
|
|
44
84
|
|
|
45
85
|
A repo usually needs a couple of gitignored files before it will run — `.env`, `infra/terraform.tfvars` — and those cannot be fetched back from a host. Vercel, for one, stores Terraform-managed variables write-only and hands them back from `vercel env pull` as *empty strings*, which looks like it worked and quietly leaves you with a `.env` full of blanks.
|
package/package.json
CHANGED
package/src/bin/devkit.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env bun
|
|
2
2
|
import { parseArgs } from "node:util";
|
|
3
3
|
import { resolve } from "node:path";
|
|
4
|
+
import { runDeploy } from "../deploy.ts";
|
|
4
5
|
import { runDev } from "../dev.ts";
|
|
5
6
|
import { runSetup } from "../setup.ts";
|
|
6
7
|
import { runClone } from "../clone.ts";
|
|
@@ -11,6 +12,7 @@ const { values, positionals } = parseArgs({
|
|
|
11
12
|
options: {
|
|
12
13
|
open: { type: "boolean", default: false },
|
|
13
14
|
dry: { type: "boolean", default: false },
|
|
15
|
+
verbose: { type: "boolean", default: false },
|
|
14
16
|
version: { type: "boolean", short: "v", default: false },
|
|
15
17
|
help: { type: "boolean", short: "h", default: false },
|
|
16
18
|
},
|
|
@@ -25,11 +27,13 @@ if (values.version) {
|
|
|
25
27
|
const usage = `usage: devkit [root] [--open] [--dry] run the dev processes (default)
|
|
26
28
|
devkit clone <owner/repo> [dir] clone, decrypt secrets, set up
|
|
27
29
|
devkit setup [root] [--dry] validate secrets, install, terraform init, run steps
|
|
30
|
+
devkit deploy [targets...] run the configured deploys, in parallel
|
|
28
31
|
devkit secrets push|pull [root] sync age-encrypted secrets
|
|
29
32
|
|
|
30
33
|
root path to the folder holding the devkit config (default: cwd)
|
|
31
34
|
--open open each app's URL in the browser once its port is live
|
|
32
35
|
--dry print what would run without running it
|
|
36
|
+
--verbose stream every line instead of drawing the live board (deploy)
|
|
33
37
|
--version print the devkit version`;
|
|
34
38
|
|
|
35
39
|
if (values.help) {
|
|
@@ -56,6 +60,10 @@ try {
|
|
|
56
60
|
await runSetup(values.dry);
|
|
57
61
|
break;
|
|
58
62
|
}
|
|
63
|
+
case "deploy": {
|
|
64
|
+
await runDeploy(rest, { dry: values.dry, verbose: values.verbose });
|
|
65
|
+
break;
|
|
66
|
+
}
|
|
59
67
|
case "secrets": {
|
|
60
68
|
const [action, dir] = rest;
|
|
61
69
|
chdirTo(dir);
|
package/src/config.ts
CHANGED
|
@@ -53,9 +53,26 @@ export interface SetupConfig {
|
|
|
53
53
|
steps?: string[];
|
|
54
54
|
}
|
|
55
55
|
|
|
56
|
+
/**
|
|
57
|
+
* One deploy step. Targets with no `needs` all start at once; a target with `needs` waits for
|
|
58
|
+
* those, which is what lets a build that another one packages up run first without serialising
|
|
59
|
+
* the whole release.
|
|
60
|
+
*/
|
|
61
|
+
export interface DeployTarget {
|
|
62
|
+
/** Display name, and the name used on the command line and in `needs`. */
|
|
63
|
+
name: string;
|
|
64
|
+
/** Shell command that performs this deploy. */
|
|
65
|
+
command: string;
|
|
66
|
+
/** Targets that must finish first. */
|
|
67
|
+
needs?: string[];
|
|
68
|
+
/** Colour for this target's line on the board. */
|
|
69
|
+
color?: string;
|
|
70
|
+
}
|
|
71
|
+
|
|
56
72
|
export interface DevkitConfig {
|
|
57
73
|
apps: DevApp[];
|
|
58
74
|
setup?: SetupConfig;
|
|
75
|
+
deploy?: DeployTarget[];
|
|
59
76
|
}
|
|
60
77
|
|
|
61
78
|
/** Read the `devkit` config from the nearest package.json. */
|
|
@@ -63,8 +80,8 @@ export function loadConfig(dir: string = process.cwd()): DevkitConfig {
|
|
|
63
80
|
const pkgPath = resolve(dir, "package.json");
|
|
64
81
|
const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { devkit?: DevkitConfig };
|
|
65
82
|
const cfg = pkg.devkit;
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
}
|
|
83
|
+
// `devkit deploy` is useful in a repo that runs nothing locally, so only the dev command
|
|
84
|
+
// insists on apps — see {@link requireApps}.
|
|
85
|
+
if (!cfg) throw new Error(`No "devkit" config found in ${pkgPath}`);
|
|
69
86
|
return cfg;
|
|
70
87
|
}
|
package/src/deploy.ts
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { mkdirSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { resolve } from "node:path";
|
|
4
|
+
import { type DeployTarget, loadConfig } from "./config.ts";
|
|
5
|
+
|
|
6
|
+
const PALETTE: readonly string[] = ["magenta", "cyan", "yellow", "green", "blue", "red"];
|
|
7
|
+
const COLORS: Record<string, string> = {
|
|
8
|
+
black: "30",
|
|
9
|
+
red: "31",
|
|
10
|
+
green: "32",
|
|
11
|
+
yellow: "33",
|
|
12
|
+
blue: "34",
|
|
13
|
+
magenta: "35",
|
|
14
|
+
cyan: "36",
|
|
15
|
+
white: "37",
|
|
16
|
+
gray: "90",
|
|
17
|
+
};
|
|
18
|
+
const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
|
|
19
|
+
const FRAME_MS = 80;
|
|
20
|
+
const TAIL_ON_FAILURE = 25;
|
|
21
|
+
|
|
22
|
+
const paint = (text: string, color: string) => `\x1b[${COLORS[color] ?? "37"}m${text}\x1b[0m`;
|
|
23
|
+
const dim = (text: string) => `\x1b[2m${text}\x1b[0m`;
|
|
24
|
+
const bold = (text: string) => `\x1b[1m${text}\x1b[0m`;
|
|
25
|
+
|
|
26
|
+
type Status = "waiting" | "running" | "done" | "failed" | "skipped";
|
|
27
|
+
|
|
28
|
+
/** One target's progress, and everything the board needs to draw its line. */
|
|
29
|
+
interface Job {
|
|
30
|
+
target: DeployTarget;
|
|
31
|
+
label: string;
|
|
32
|
+
color: string;
|
|
33
|
+
status: Status;
|
|
34
|
+
note: string;
|
|
35
|
+
startedAt?: number;
|
|
36
|
+
endedAt?: number;
|
|
37
|
+
lines: string[];
|
|
38
|
+
logPath: string;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Run the configured deploys, in parallel where they don't depend on each other.
|
|
43
|
+
*
|
|
44
|
+
* A deploy is several long builds that each print thousands of lines, and interleaving all of it
|
|
45
|
+
* is unreadable — so on a terminal this draws one line per target (what it's doing, for how long)
|
|
46
|
+
* and keeps the full output in `.devkit/deploy/<name>.log`, printing the tail of whichever target
|
|
47
|
+
* failed. Anywhere else — CI, a pipe, a log file — it falls back to prefixed streaming, because a
|
|
48
|
+
* redrawing board in a file is worse than useless.
|
|
49
|
+
*/
|
|
50
|
+
export async function runDeploy(only: string[], options: { dry?: boolean; verbose?: boolean } = {}) {
|
|
51
|
+
const { deploy } = loadConfig();
|
|
52
|
+
if (!deploy?.length) throw new Error('No "devkit.deploy" targets in package.json');
|
|
53
|
+
|
|
54
|
+
const unknown = only.filter((name) => !deploy.some((target) => target.name === name));
|
|
55
|
+
if (unknown.length) {
|
|
56
|
+
throw new Error(`Unknown target${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}`);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
for (const target of deploy) {
|
|
60
|
+
const missing = (target.needs ?? []).filter((need) => !deploy.some((other) => other.name === need));
|
|
61
|
+
if (missing.length) throw new Error(`${target.name} needs unknown target${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}`);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const jobs = selected(deploy, only).map(toJob);
|
|
65
|
+
if (options.dry) return printPlan(jobs);
|
|
66
|
+
|
|
67
|
+
const logDir = resolve(process.cwd(), ".devkit/deploy");
|
|
68
|
+
mkdirSync(logDir, { recursive: true });
|
|
69
|
+
|
|
70
|
+
const live = Boolean(process.stdout.isTTY) && !options.verbose;
|
|
71
|
+
console.log(bold(`\ndeploying ${jobs.map((job) => job.label).join(", ")}`) + dim(live ? ` · logs in ${"./.devkit/deploy"}` : ""));
|
|
72
|
+
console.log();
|
|
73
|
+
const board = live ? startBoard(jobs) : null;
|
|
74
|
+
|
|
75
|
+
// Each target waits on the gates of the targets it needs, so the graph runs itself: independent
|
|
76
|
+
// targets start together, dependents start the moment their last dependency lands.
|
|
77
|
+
const gates = new Map(jobs.map((job) => [job.label, gate()]));
|
|
78
|
+
|
|
79
|
+
const started = Date.now();
|
|
80
|
+
await Promise.all(
|
|
81
|
+
jobs.map(async (job) => {
|
|
82
|
+
const needs = (job.target.needs ?? []).map((name) => jobs.find((other) => other.label === name)) as Job[];
|
|
83
|
+
await Promise.all(needs.map((need) => gates.get(need.label)?.promise));
|
|
84
|
+
await runJob(job, needs, live);
|
|
85
|
+
gates.get(job.label)?.open();
|
|
86
|
+
}),
|
|
87
|
+
);
|
|
88
|
+
board?.stop();
|
|
89
|
+
|
|
90
|
+
report(jobs, Date.now() - started);
|
|
91
|
+
if (jobs.some((job) => job.status !== "done")) process.exitCode = 1;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The targets asked for, plus whatever they depend on — a target can't run without its needs. */
|
|
95
|
+
function selected(targets: DeployTarget[], only: string[]) {
|
|
96
|
+
if (!only.length) return targets;
|
|
97
|
+
const wanted = new Set(only);
|
|
98
|
+
let grew = true;
|
|
99
|
+
while (grew) {
|
|
100
|
+
grew = false;
|
|
101
|
+
for (const target of targets) {
|
|
102
|
+
if (!wanted.has(target.name)) continue;
|
|
103
|
+
for (const need of target.needs ?? []) {
|
|
104
|
+
if (!wanted.has(need)) {
|
|
105
|
+
wanted.add(need);
|
|
106
|
+
grew = true;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return targets.filter((target) => wanted.has(target.name));
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function toJob(target: DeployTarget, index: number): Job {
|
|
115
|
+
return {
|
|
116
|
+
target,
|
|
117
|
+
label: target.name,
|
|
118
|
+
color: target.color ?? (PALETTE[index % PALETTE.length] as string),
|
|
119
|
+
status: "waiting",
|
|
120
|
+
note: target.needs?.length ? `waiting for ${target.needs.join(", ")}` : "",
|
|
121
|
+
lines: [],
|
|
122
|
+
logPath: resolve(process.cwd(), ".devkit/deploy", `${target.name}.log`),
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** Runs one target's command to completion, unless something it needed didn't get there. */
|
|
127
|
+
async function runJob(job: Job, needs: Job[], live: boolean) {
|
|
128
|
+
const blocker = needs.find((need) => need.status !== "done");
|
|
129
|
+
if (blocker) {
|
|
130
|
+
job.status = "skipped";
|
|
131
|
+
job.note = `skipped — ${blocker.label} ${blocker.status === "failed" ? "failed" : "never ran"}`;
|
|
132
|
+
return;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
job.status = "running";
|
|
136
|
+
job.startedAt = Date.now();
|
|
137
|
+
job.note = job.target.command;
|
|
138
|
+
|
|
139
|
+
const code = await new Promise<number>((done) => {
|
|
140
|
+
const child = spawn(job.target.command, { shell: true, stdio: ["ignore", "pipe", "pipe"] });
|
|
141
|
+
for (const stream of [child.stdout, child.stderr]) {
|
|
142
|
+
let rest = "";
|
|
143
|
+
stream.on("data", (chunk: Buffer) => {
|
|
144
|
+
const parts = (rest + chunk.toString()).split("\n");
|
|
145
|
+
rest = parts.pop() ?? "";
|
|
146
|
+
for (const line of parts) {
|
|
147
|
+
job.lines.push(line);
|
|
148
|
+
job.note = line.trim() || job.note;
|
|
149
|
+
if (!live) console.log(`${paint(`[${job.label}]`, job.color)} ${line}`);
|
|
150
|
+
}
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
child.on("close", (status) => done(status ?? 1));
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
job.endedAt = Date.now();
|
|
157
|
+
job.status = code === 0 ? "done" : "failed";
|
|
158
|
+
job.note = code === 0 ? "done" : `exit ${code}`;
|
|
159
|
+
writeFileSync(job.logPath, `${job.lines.join("\n")}\n`);
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Redraws the board until stopped. One line per target, in the order they were configured. */
|
|
163
|
+
function startBoard(jobs: Job[]) {
|
|
164
|
+
let drawn = 0;
|
|
165
|
+
let frame = 0;
|
|
166
|
+
|
|
167
|
+
const draw = () => {
|
|
168
|
+
// A pty with no window size reports 0 — treat that as a sane default rather than clipping to nothing.
|
|
169
|
+
const width = process.stdout.columns || 100;
|
|
170
|
+
const pad = Math.max(...jobs.map((job) => job.label.length));
|
|
171
|
+
const lines = jobs.map((job) => {
|
|
172
|
+
const mark =
|
|
173
|
+
job.status === "running"
|
|
174
|
+
? paint(SPINNER[frame % SPINNER.length] as string, job.color)
|
|
175
|
+
: job.status === "done"
|
|
176
|
+
? paint("✓", "green")
|
|
177
|
+
: job.status === "failed"
|
|
178
|
+
? paint("✗", "red")
|
|
179
|
+
: job.status === "skipped"
|
|
180
|
+
? dim("–")
|
|
181
|
+
: dim("·");
|
|
182
|
+
const time = job.startedAt ? dim(` ${elapsed(job)}`) : "";
|
|
183
|
+
const head = `${mark} ${paint(job.label.padEnd(pad), job.color)}${time} `;
|
|
184
|
+
// The note is whatever the target last printed, so it has to be cut to the terminal rather
|
|
185
|
+
// than wrapped — a wrapped line breaks the cursor arithmetic that redraws this block.
|
|
186
|
+
const room = Math.max(10, width - visibleLength(head) - 1);
|
|
187
|
+
return head + dim(clip(job.note, room));
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
process.stdout.write(`${drawn ? `\x1b[${drawn}A` : ""}${lines.map((line) => `\x1b[2K${line}`).join("\n")}\n`);
|
|
191
|
+
drawn = lines.length;
|
|
192
|
+
frame++;
|
|
193
|
+
};
|
|
194
|
+
|
|
195
|
+
process.stdout.write("\x1b[?25l");
|
|
196
|
+
draw();
|
|
197
|
+
const timer = setInterval(draw, FRAME_MS);
|
|
198
|
+
|
|
199
|
+
return {
|
|
200
|
+
stop() {
|
|
201
|
+
clearInterval(timer);
|
|
202
|
+
draw();
|
|
203
|
+
process.stdout.write("\x1b[?25h");
|
|
204
|
+
},
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
function report(jobs: Job[], total: number) {
|
|
209
|
+
const failed = jobs.filter((job) => job.status === "failed");
|
|
210
|
+
for (const job of failed) {
|
|
211
|
+
console.log(`\n${paint(`── ${job.label} failed`, "red")} ${dim(job.logPath)}`);
|
|
212
|
+
for (const line of job.lines.slice(-TAIL_ON_FAILURE)) console.log(dim(` ${line}`));
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
const done = jobs.filter((job) => job.status === "done").length;
|
|
216
|
+
const skipped = jobs.filter((job) => job.status === "skipped").length;
|
|
217
|
+
const parts = [
|
|
218
|
+
failed.length ? paint(`${failed.length} failed`, "red") : paint("all good", "green"),
|
|
219
|
+
skipped ? dim(`${skipped} skipped`) : "",
|
|
220
|
+
dim(duration(total)),
|
|
221
|
+
].filter(Boolean);
|
|
222
|
+
console.log(`\n${bold(`${done}/${jobs.length} deployed`)} · ${parts.join(" · ")}\n`);
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
function printPlan(jobs: Job[]) {
|
|
226
|
+
console.log(bold("\ndeploy plan\n"));
|
|
227
|
+
for (const job of jobs) {
|
|
228
|
+
const after = job.target.needs?.length ? dim(` after ${job.target.needs.join(", ")}`) : "";
|
|
229
|
+
console.log(` ${paint(job.label, job.color)}${after}\n ${dim(job.target.command)}`);
|
|
230
|
+
}
|
|
231
|
+
console.log();
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/** A promise plus the handle that settles it — one per target, opened when that target ends. */
|
|
235
|
+
function gate() {
|
|
236
|
+
let open!: () => void;
|
|
237
|
+
const promise = new Promise<void>((resolve) => {
|
|
238
|
+
open = resolve;
|
|
239
|
+
});
|
|
240
|
+
return { promise, open };
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
const elapsed = (job: Job) => duration((job.endedAt ?? Date.now()) - (job.startedAt ?? Date.now()));
|
|
244
|
+
|
|
245
|
+
function duration(ms: number) {
|
|
246
|
+
const seconds = Math.round(ms / 1000);
|
|
247
|
+
return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
// Colour codes take no space on screen, so the board has to measure what a reader would see.
|
|
251
|
+
// biome-ignore lint/suspicious/noControlCharactersInRegex: an escape sequence is the thing being matched
|
|
252
|
+
const ANSI = /\x1b\[[0-9;]*m/g;
|
|
253
|
+
const visibleLength = (text: string) => text.replace(ANSI, "").length;
|
|
254
|
+
const clip = (text: string, room: number) => (text.length <= room ? text : `${text.slice(0, room - 1)}…`);
|
package/src/dev.ts
CHANGED
|
@@ -20,6 +20,7 @@ function labelFor(app: DevApp, index: number): string {
|
|
|
20
20
|
/** Free ports, print URLs, run every app side-by-side, optionally open the browser. */
|
|
21
21
|
export async function runDev(open: boolean, dry = false): Promise<void> {
|
|
22
22
|
const { apps } = loadConfig();
|
|
23
|
+
if (!apps?.length) throw new Error('No "devkit.apps" to run');
|
|
23
24
|
const withPort = apps.filter((app) => app.port != null);
|
|
24
25
|
|
|
25
26
|
if (dry) {
|