@elumixor/devkit 0.2.1 → 0.3.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/package.json +1 -1
- package/src/bin/devkit.ts +50 -9
- package/src/clone.ts +29 -0
- package/src/config.ts +33 -0
- package/src/secrets.ts +114 -0
- package/src/setup.ts +79 -0
package/package.json
CHANGED
package/src/bin/devkit.ts
CHANGED
|
@@ -2,6 +2,9 @@
|
|
|
2
2
|
import { parseArgs } from "node:util";
|
|
3
3
|
import { resolve } from "node:path";
|
|
4
4
|
import { runDev } from "../dev.ts";
|
|
5
|
+
import { runSetup } from "../setup.ts";
|
|
6
|
+
import { runClone } from "../clone.ts";
|
|
7
|
+
import { pullSecrets, pushSecrets } from "../secrets.ts";
|
|
5
8
|
import pkg from "../../package.json" with { type: "json" };
|
|
6
9
|
|
|
7
10
|
const { values, positionals } = parseArgs({
|
|
@@ -19,17 +22,55 @@ if (values.version) {
|
|
|
19
22
|
process.exit(0);
|
|
20
23
|
}
|
|
21
24
|
|
|
25
|
+
const usage = `usage: devkit [root] [--open] [--dry] run the dev processes (default)
|
|
26
|
+
devkit clone <owner/repo> [dir] clone, decrypt secrets, set up
|
|
27
|
+
devkit setup [root] [--dry] validate secrets, install, terraform init, run steps
|
|
28
|
+
devkit secrets push|pull [root] sync age-encrypted secrets
|
|
29
|
+
|
|
30
|
+
root path to the folder holding the devkit config (default: cwd)
|
|
31
|
+
--open open each app's URL in the browser once its port is live
|
|
32
|
+
--dry print what would run without running it
|
|
33
|
+
--version print the devkit version`;
|
|
34
|
+
|
|
22
35
|
if (values.help) {
|
|
23
|
-
console.log(
|
|
24
|
-
console.log(" root path to the folder holding the devkit config (default: cwd)");
|
|
25
|
-
console.log(" --open open each app's URL in the browser once its port is live");
|
|
26
|
-
console.log(" --dry print the resolved commands and URLs without running anything");
|
|
27
|
-
console.log(" --version print the devkit version");
|
|
36
|
+
console.log(usage);
|
|
28
37
|
process.exit(0);
|
|
29
38
|
}
|
|
30
39
|
|
|
31
|
-
|
|
32
|
-
const root = positionals[0];
|
|
33
|
-
if (root) process.chdir(resolve(root));
|
|
40
|
+
const [command, ...rest] = positionals;
|
|
34
41
|
|
|
35
|
-
|
|
42
|
+
function chdirTo(dir?: string) {
|
|
43
|
+
if (dir) process.chdir(resolve(dir));
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
try {
|
|
47
|
+
switch (command) {
|
|
48
|
+
case "clone": {
|
|
49
|
+
const [repo, dir] = rest;
|
|
50
|
+
if (!repo) throw new Error("usage: devkit clone <owner/repo> [dir]");
|
|
51
|
+
await runClone(repo, dir);
|
|
52
|
+
break;
|
|
53
|
+
}
|
|
54
|
+
case "setup": {
|
|
55
|
+
chdirTo(rest[0]);
|
|
56
|
+
await runSetup(values.dry);
|
|
57
|
+
break;
|
|
58
|
+
}
|
|
59
|
+
case "secrets": {
|
|
60
|
+
const [action, dir] = rest;
|
|
61
|
+
chdirTo(dir);
|
|
62
|
+
if (action === "push") await pushSecrets();
|
|
63
|
+
else if (action === "pull") await pullSecrets();
|
|
64
|
+
else throw new Error("usage: devkit secrets push|pull [root]");
|
|
65
|
+
break;
|
|
66
|
+
}
|
|
67
|
+
default: {
|
|
68
|
+
// No subcommand — the original `devkit [root]` behaviour.
|
|
69
|
+
chdirTo(command);
|
|
70
|
+
await runDev(values.open, values.dry);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
} catch (error) {
|
|
74
|
+
console.error(error instanceof Error ? error.message : error);
|
|
75
|
+
process.exit(1);
|
|
76
|
+
}
|
package/src/clone.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { $ } from "bun";
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { resolve } from "node:path";
|
|
4
|
+
import { pullSecrets } from "./secrets.ts";
|
|
5
|
+
import { runSetup } from "./setup.ts";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Clone a repo and make it runnable in one step: `gh repo clone`, decrypt its
|
|
9
|
+
* secrets, then run setup. The whole point is that a new machine needs nothing
|
|
10
|
+
* but `gh auth login` and the age identity.
|
|
11
|
+
*/
|
|
12
|
+
export async function runClone(repo: string, dir?: string) {
|
|
13
|
+
const target = resolve(dir ?? repo.split("/").pop() ?? repo);
|
|
14
|
+
|
|
15
|
+
if (existsSync(target)) {
|
|
16
|
+
console.log(`${target} already exists — skipping clone.`);
|
|
17
|
+
} else {
|
|
18
|
+
console.log(`Cloning ${repo}…`);
|
|
19
|
+
await $`gh repo clone ${repo} ${target}`;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
process.chdir(target);
|
|
23
|
+
|
|
24
|
+
console.log("\nFetching secrets…");
|
|
25
|
+
await pullSecrets(target);
|
|
26
|
+
|
|
27
|
+
console.log("");
|
|
28
|
+
await runSetup();
|
|
29
|
+
}
|
package/src/config.ts
CHANGED
|
@@ -21,8 +21,41 @@ export interface DevApp {
|
|
|
21
21
|
open?: boolean;
|
|
22
22
|
}
|
|
23
23
|
|
|
24
|
+
/** A gitignored env file that must be carried to a new machine, and the template listing its keys. */
|
|
25
|
+
export interface EnvFile {
|
|
26
|
+
/** Path to the env file, relative to the root (default `.env`). */
|
|
27
|
+
file?: string;
|
|
28
|
+
/** Committed template whose keys must all be present and non-empty (default `<file>.example`). */
|
|
29
|
+
example?: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* `devkit setup` config: what a fresh clone needs before it can run.
|
|
34
|
+
*
|
|
35
|
+
* Setup never writes secrets. Env files are validated, not generated — see the README
|
|
36
|
+
* for why fetching them back from a host (e.g. `vercel env pull`) is not safe.
|
|
37
|
+
*/
|
|
38
|
+
export interface SetupConfig {
|
|
39
|
+
/** Env files to validate. Defaults to a single `.env` / `.env.example` pair. */
|
|
40
|
+
env?: EnvFile[];
|
|
41
|
+
/**
|
|
42
|
+
* Gitignored files that cannot be regenerated from any host, synced age-encrypted
|
|
43
|
+
* via `devkit secrets push|pull` (e.g. `[".env", "infra/terraform.tfvars"]`).
|
|
44
|
+
*/
|
|
45
|
+
secrets?: string[];
|
|
46
|
+
/** Private repo holding the encrypted secrets (default `elumixor/secrets`). */
|
|
47
|
+
secretsRepo?: string;
|
|
48
|
+
/** Directory holding Terraform. Initialised only if it has a `terraform.tfvars`. */
|
|
49
|
+
terraform?: string;
|
|
50
|
+
/** Run `bun install` at the root (default true). */
|
|
51
|
+
install?: boolean;
|
|
52
|
+
/** Shell commands to run last, in order (e.g. `bun --filter backend prisma:generate`). */
|
|
53
|
+
steps?: string[];
|
|
54
|
+
}
|
|
55
|
+
|
|
24
56
|
export interface DevkitConfig {
|
|
25
57
|
apps: DevApp[];
|
|
58
|
+
setup?: SetupConfig;
|
|
26
59
|
}
|
|
27
60
|
|
|
28
61
|
/** Read the `devkit` config from the nearest package.json. */
|
package/src/secrets.ts
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import { $ } from "bun";
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { mkdir } from "node:fs/promises";
|
|
4
|
+
import { homedir } from "node:os";
|
|
5
|
+
import { dirname, join, resolve } from "node:path";
|
|
6
|
+
import { loadConfig } from "./config.ts";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Secrets that cannot be regenerated from any host (.env, terraform.tfvars) are
|
|
10
|
+
* age-encrypted into a private git repo, one directory per project.
|
|
11
|
+
*
|
|
12
|
+
* The only thing a new machine must carry is the age identity. Everything else
|
|
13
|
+
* follows from `gh auth login`.
|
|
14
|
+
*/
|
|
15
|
+
export const KEY_PATH = join(homedir(), ".config/age/key.txt");
|
|
16
|
+
const CACHE = join(homedir(), ".cache/devkit/secrets");
|
|
17
|
+
const DEFAULT_REPO = "elumixor/secrets";
|
|
18
|
+
|
|
19
|
+
/** `recipients.txt` lets any machine holding *a* key encrypt for *all* keys. */
|
|
20
|
+
const RECIPIENTS = "recipients.txt";
|
|
21
|
+
|
|
22
|
+
function requireKey() {
|
|
23
|
+
if (existsSync(KEY_PATH)) return;
|
|
24
|
+
throw new Error(
|
|
25
|
+
`No age identity at ${KEY_PATH}.\n\n` +
|
|
26
|
+
`It is the one thing that must be carried to a new machine — without it the\n` +
|
|
27
|
+
`encrypted secrets cannot be read. Copy it over, or create a new identity with\n` +
|
|
28
|
+
`\`age-keygen -o ${KEY_PATH}\` and re-encrypt from a machine that still has the old one.`,
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Clone the secrets repo on first use, otherwise fast-forward it. */
|
|
33
|
+
async function syncCache(repo: string) {
|
|
34
|
+
if (existsSync(join(CACHE, ".git"))) {
|
|
35
|
+
await $`git pull --quiet --ff-only`.cwd(CACHE);
|
|
36
|
+
} else {
|
|
37
|
+
await mkdir(dirname(CACHE), { recursive: true });
|
|
38
|
+
await $`gh repo clone ${repo} ${CACHE} -- --quiet`.quiet();
|
|
39
|
+
}
|
|
40
|
+
return CACHE;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Project directory inside the secrets repo — the repo name, so it matches `devkit clone`. */
|
|
44
|
+
async function projectName(root: string) {
|
|
45
|
+
const remote = await $`git -C ${root} remote get-url origin`.quiet().nothrow().text();
|
|
46
|
+
const name = remote.trim().replace(/\.git$/, "").split("/").pop();
|
|
47
|
+
if (name) return name;
|
|
48
|
+
const pkg = await Bun.file(resolve(root, "package.json")).json();
|
|
49
|
+
return pkg.name as string;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function config(root: string) {
|
|
53
|
+
const setup = loadConfig(root).setup ?? {};
|
|
54
|
+
const files = setup.secrets ?? [];
|
|
55
|
+
if (!files.length) throw new Error('No "devkit.setup.secrets" in package.json — nothing to sync.');
|
|
56
|
+
return { files, repo: setup.secretsRepo ?? DEFAULT_REPO };
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Encrypt the project's secret files into the secrets repo and push. */
|
|
60
|
+
export async function pushSecrets(root = process.cwd()) {
|
|
61
|
+
requireKey();
|
|
62
|
+
const { files, repo } = config(root);
|
|
63
|
+
const cache = await syncCache(repo);
|
|
64
|
+
const project = await projectName(root);
|
|
65
|
+
|
|
66
|
+
// Seed recipients.txt on first push so other machines can encrypt for this key too.
|
|
67
|
+
const recipientsPath = join(cache, RECIPIENTS);
|
|
68
|
+
if (!existsSync(recipientsPath)) {
|
|
69
|
+
await Bun.write(recipientsPath, `${(await $`age-keygen -y ${KEY_PATH}`.text()).trim()}\n`);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
let pushed = 0;
|
|
73
|
+
for (const file of files) {
|
|
74
|
+
const source = resolve(root, file);
|
|
75
|
+
if (!existsSync(source)) {
|
|
76
|
+
console.log(` skip ${file} (not present)`);
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
79
|
+
const target = join(cache, project, `${file}.age`);
|
|
80
|
+
await mkdir(dirname(target), { recursive: true });
|
|
81
|
+
await $`age --encrypt --recipients-file ${recipientsPath} --output ${target} ${source}`;
|
|
82
|
+
console.log(` encrypted ${file}`);
|
|
83
|
+
pushed++;
|
|
84
|
+
}
|
|
85
|
+
if (!pushed) return console.log("Nothing to push.");
|
|
86
|
+
|
|
87
|
+
await $`git add -A`.cwd(cache);
|
|
88
|
+
const clean = await $`git diff --cached --quiet`.cwd(cache).nothrow();
|
|
89
|
+
if (clean.exitCode === 0) return console.log("Already up to date.");
|
|
90
|
+
|
|
91
|
+
await $`git commit --quiet -m ${`secrets: update ${project}`}`.cwd(cache);
|
|
92
|
+
await $`git push --quiet`.cwd(cache);
|
|
93
|
+
console.log(`Pushed ${pushed} file(s) for ${project} to ${repo}.`);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Decrypt this project's secret files from the secrets repo into the working tree. */
|
|
97
|
+
export async function pullSecrets(root = process.cwd()) {
|
|
98
|
+
requireKey();
|
|
99
|
+
const { files, repo } = config(root);
|
|
100
|
+
const cache = await syncCache(repo);
|
|
101
|
+
const project = await projectName(root);
|
|
102
|
+
|
|
103
|
+
for (const file of files) {
|
|
104
|
+
const source = join(cache, project, `${file}.age`);
|
|
105
|
+
if (!existsSync(source)) {
|
|
106
|
+
console.log(` skip ${file} (not in ${repo}/${project})`);
|
|
107
|
+
continue;
|
|
108
|
+
}
|
|
109
|
+
const target = resolve(root, file);
|
|
110
|
+
await mkdir(dirname(target), { recursive: true });
|
|
111
|
+
await $`age --decrypt --identity ${KEY_PATH} --output ${target} ${source}`;
|
|
112
|
+
console.log(` decrypted ${file}`);
|
|
113
|
+
}
|
|
114
|
+
}
|
package/src/setup.ts
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { $ } from "bun";
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { resolve } from "node:path";
|
|
4
|
+
import { loadConfig, type EnvFile, type SetupConfig } from "./config.ts";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Parse `KEY=value` lines. Deliberately tolerant: blank lines, comments, quoted
|
|
8
|
+
* values and `export` prefixes all show up in real .env files.
|
|
9
|
+
*/
|
|
10
|
+
function parseEnv(text: string) {
|
|
11
|
+
const vars = new Map<string, string>();
|
|
12
|
+
for (const line of text.split("\n")) {
|
|
13
|
+
if (line.trimStart().startsWith("#")) continue;
|
|
14
|
+
const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
|
|
15
|
+
if (!match?.[1]) continue;
|
|
16
|
+
vars.set(match[1], (match[2] ?? "").replace(/^(["'])(.*)\1$/, "$2"));
|
|
17
|
+
}
|
|
18
|
+
return vars;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Validate one env file against its template. Collects every problem rather than
|
|
23
|
+
* failing on the first, so one run tells you everything that is wrong.
|
|
24
|
+
*/
|
|
25
|
+
async function checkEnv(root: string, entry: EnvFile) {
|
|
26
|
+
const file = entry.file ?? ".env";
|
|
27
|
+
const example = entry.example ?? `${file}.example`;
|
|
28
|
+
const path = resolve(root, file);
|
|
29
|
+
const examplePath = resolve(root, example);
|
|
30
|
+
|
|
31
|
+
if (!existsSync(path)) return [`${file} is missing`];
|
|
32
|
+
if (!existsSync(examplePath)) return [];
|
|
33
|
+
|
|
34
|
+
const actual = parseEnv(await Bun.file(path).text());
|
|
35
|
+
const required = parseEnv(await Bun.file(examplePath).text());
|
|
36
|
+
|
|
37
|
+
const missing = [...required.keys()].filter((key) => !actual.has(key));
|
|
38
|
+
const blank = [...required.keys()].filter((key) => actual.get(key) === "");
|
|
39
|
+
|
|
40
|
+
const problems: string[] = [];
|
|
41
|
+
if (missing.length) problems.push(`${file} is missing keys: ${missing.join(", ")}`);
|
|
42
|
+
// Blank values are the dangerous case: the app starts, then fails later in a way that
|
|
43
|
+
// looks like an unrelated bug. Hosts storing secrets write-only hand them back exactly so.
|
|
44
|
+
if (blank.length) problems.push(`${file} has empty values: ${blank.join(", ")}`);
|
|
45
|
+
if (!problems.length) console.log(` ${file} ok (${actual.size} vars)`);
|
|
46
|
+
return problems;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export async function runSetup(dry = false) {
|
|
50
|
+
const root = process.cwd();
|
|
51
|
+
const setup: SetupConfig = loadConfig(root).setup ?? {};
|
|
52
|
+
const envFiles = setup.env ?? [{ file: ".env" }];
|
|
53
|
+
|
|
54
|
+
const run = async (command: string, cwd = root) => {
|
|
55
|
+
if (dry) return console.log(` $ ${command}`);
|
|
56
|
+
await $`sh -c ${command}`.cwd(cwd);
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
console.log("Checking env files…");
|
|
60
|
+
const problems = (await Promise.all(envFiles.map((entry) => checkEnv(root, entry)))).flat();
|
|
61
|
+
|
|
62
|
+
if (problems.length) {
|
|
63
|
+
console.error(`\n${problems.map((problem) => ` ${problem}`).join("\n")}`);
|
|
64
|
+
console.error("\nRun `devkit secrets pull` to fetch them, or copy them from another machine.");
|
|
65
|
+
process.exit(1);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
if (setup.install !== false) await run("bun install");
|
|
69
|
+
|
|
70
|
+
if (setup.terraform) {
|
|
71
|
+
const dir = resolve(root, setup.terraform);
|
|
72
|
+
if (existsSync(resolve(dir, "terraform.tfvars"))) await run("terraform init -input=false", dir);
|
|
73
|
+
else console.log(`Skipping terraform init — no ${setup.terraform}/terraform.tfvars.`);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
for (const step of setup.steps ?? []) await run(step);
|
|
77
|
+
|
|
78
|
+
console.log(dry ? "\nDry run — nothing executed." : "\nSetup complete.");
|
|
79
|
+
}
|