@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 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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elumixor/devkit",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
4
4
  "description": "Dev orchestrator for bun monorepos — free ports, run apps side-by-side, open the browser when ready",
5
5
  "author": "elumixor",
6
6
  "license": "ISC",
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
- if (!cfg?.apps?.length) {
67
- throw new Error(`No "devkit.apps" found in ${pkgPath}`);
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) {