@kodentuzo/spotcraft 0.0.0-stage → 0.6.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/dist/stack.js ADDED
@@ -0,0 +1,297 @@
1
+ import { spawn } from 'node:child_process';
2
+ import { randomBytes } from 'node:crypto';
3
+ import { mkdir, readFile, writeFile } from 'node:fs/promises';
4
+ import { createServer } from 'node:net';
5
+ import { join } from 'node:path';
6
+ import { appRoleName, INSTANCE } from "./provision.js";
7
+ /**
8
+ * The local stack of one repository (ADR 0037): Postgres set up like the Spotcraft server's,
9
+ * the user pool, and Mailpit to catch email, as the Compose project `spotcraft-dev-<repo>`.
10
+ * Tests keep the values below equal to the server's files.
11
+ */
12
+ export const PROJECT_PREFIX = 'spotcraft-dev-';
13
+ /** The server's Postgres image (infra/server/compose.yaml). */
14
+ export const POSTGRES_IMAGE = 'postgres:18.7-trixie@sha256:2ea8630df176ad090ec92136dee850397c5af8781e4bcf2e4162593691c61bbc';
15
+ /** Catches every email apps send (SMTP), with a web inbox. */
16
+ export const MAILPIT_IMAGE = 'axllent/mailpit:v1.33.1@sha256:aef2aacc11f075ec0fb6874275ee4a421e688e11a96ebb296134d1735c7761ce';
17
+ /** The user pool runs from the Spotcraft image of the same version as this CLI. */
18
+ export const SPOTCRAFT_IMAGE = 'vindotski/spotcraft';
19
+ /** The local pool's `iss`; it names the pool, it is not an address. */
20
+ export const LOCAL_ISSUER = 'http://localhost/pools/main';
21
+ /** The server's Postgres login rules (infra/server/pg_hba.conf). */
22
+ export const PG_HBA = `# TYPE DATABASE USER ADDRESS METHOD
23
+ local all postgres peer
24
+ local all all reject
25
+ host all postgres all reject
26
+ host all all all scram-sha-256
27
+ `;
28
+ /** The agent's role, exactly as the deploy script sets it up (infra/remote-deploy.sh). */
29
+ export const ADMIN_SQL = `SELECT NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'spotcraft_agent') AS missing \\gset
30
+ \\if :missing
31
+ CREATE ROLE spotcraft_agent LOGIN CREATEDB CREATEROLE PASSWORD :'pw';
32
+ \\else
33
+ ALTER ROLE spotcraft_agent LOGIN CREATEDB CREATEROLE NOSUPERUSER PASSWORD :'pw';
34
+ \\endif
35
+ -- Roles the agent creates (one per app) are ones it may SET ROLE to, which Postgres requires
36
+ -- to make them a database's owner; it doesn't inherit their rights.
37
+ ALTER ROLE spotcraft_agent SET createrole_self_grant = 'set';
38
+ -- Apps get CONNECT on their own database only; the built-in ones are the agent's.
39
+ REVOKE CONNECT ON DATABASE postgres, template1 FROM PUBLIC;
40
+ GRANT CONNECT ON DATABASE postgres TO spotcraft_agent;
41
+ -- The database apps share (ADR 0034), owned by the agent, and the group every app role joins.
42
+ -- The agent may grant the group to the app roles it makes, without inheriting its rights.
43
+ SELECT NOT EXISTS (SELECT FROM pg_database WHERE datname = 'apps') AS missing \\gset
44
+ \\if :missing
45
+ CREATE DATABASE apps OWNER spotcraft_agent;
46
+ \\endif
47
+ REVOKE ALL ON DATABASE apps FROM PUBLIC;
48
+ SELECT NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'spotcraft_app') AS missing \\gset
49
+ \\if :missing
50
+ CREATE ROLE spotcraft_app NOLOGIN;
51
+ \\endif
52
+ GRANT spotcraft_app TO spotcraft_agent WITH ADMIN OPTION, INHERIT FALSE;
53
+ -- The user pool's role (ADR 0035): it owns the auth schema in apps, and nothing else.
54
+ SELECT NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'spotcraft_auth') AS missing \\gset
55
+ \\if :missing
56
+ CREATE ROLE spotcraft_auth LOGIN PASSWORD :'auth_pw';
57
+ \\else
58
+ ALTER ROLE spotcraft_auth LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE PASSWORD :'auth_pw';
59
+ \\endif
60
+ GRANT CONNECT ON DATABASE apps TO spotcraft_auth;
61
+ \\c apps
62
+ REVOKE ALL ON SCHEMA public FROM PUBLIC;
63
+ CREATE SCHEMA IF NOT EXISTS auth AUTHORIZATION spotcraft_auth;
64
+ `;
65
+ // Fixed local passwords keep DATABASE_URL the same across runs (and in .env). Acceptable only
66
+ // because every port is bound to 127.0.0.1 and the data is throwaway.
67
+ const SUPERUSER_PASSWORD = 'spotcraft-dev-superuser';
68
+ const ADMIN_PASSWORD = 'spotcraft-dev-admin-password';
69
+ const AUTH_PASSWORD = 'spotcraft-dev-auth-password';
70
+ export const appPassword = (name) => `local-${name}-password`;
71
+ /** A free port on 127.0.0.1, as the system hands one out. */
72
+ function freePort() {
73
+ return new Promise((resolve, reject) => {
74
+ const server = createServer();
75
+ server.once('error', reject);
76
+ server.listen(0, '127.0.0.1', () => {
77
+ const address = server.address();
78
+ server.close(() => typeof address === 'object' && address
79
+ ? resolve(address.port)
80
+ : reject(new Error('no port')));
81
+ });
82
+ });
83
+ }
84
+ /**
85
+ * The repository's stack, from `.spotcraft/dev.json`, or a new one: free ports picked once and
86
+ * kept, so URLs in `.env` stay the same. `.spotcraft/` ignores itself in git.
87
+ */
88
+ export async function loadStack(root, slug, ports = freePort) {
89
+ const stateDir = join(root, '.spotcraft');
90
+ const file = join(stateDir, 'dev.json');
91
+ const project = `${PROJECT_PREFIX}${slug}`;
92
+ try {
93
+ const saved = JSON.parse(await readFile(file, 'utf8'));
94
+ if (saved.ports && saved.authSecret)
95
+ return { project, stateDir, ...saved };
96
+ }
97
+ catch (error) {
98
+ if (error.code !== 'ENOENT' && !(error instanceof SyntaxError))
99
+ throw error;
100
+ }
101
+ const picked = new Set();
102
+ const next = async () => {
103
+ for (;;) {
104
+ const port = await ports();
105
+ if (!picked.has(port)) {
106
+ picked.add(port);
107
+ return port;
108
+ }
109
+ }
110
+ };
111
+ const stack = {
112
+ project,
113
+ stateDir,
114
+ ports: { postgres: await next(), auth: await next(), smtp: await next(), mail: await next() },
115
+ authSecret: randomBytes(32).toString('hex'),
116
+ };
117
+ await mkdir(stateDir, { recursive: true });
118
+ await writeFile(join(stateDir, '.gitignore'), '*\n');
119
+ const { project: _, stateDir: __, ...saved } = stack;
120
+ await writeFile(file, `${JSON.stringify(saved, null, 2)}\n`);
121
+ return stack;
122
+ }
123
+ export const adminUrl = (stack) => `postgres://spotcraft_agent:${ADMIN_PASSWORD}@127.0.0.1:${stack.ports.postgres}/postgres`;
124
+ /**
125
+ * What the app gets, as on the server but on localhost: the instance database, or the app's own
126
+ * one if it still has it (from before ADR 0034).
127
+ */
128
+ export function databaseUrl(stack, name, database = INSTANCE.database) {
129
+ return `postgres://${appRoleName(name)}:${appPassword(name)}@127.0.0.1:${stack.ports.postgres}/${database}`;
130
+ }
131
+ /** Where apps reach the local pool, mail and its inbox. */
132
+ export const poolUrl = (stack) => `http://localhost:${stack.ports.auth}/_spotcraft/auth`;
133
+ export const smtpUrl = (stack) => `smtp://localhost:${stack.ports.smtp}`;
134
+ export const mailUrl = (stack) => `http://localhost:${stack.ports.mail}`;
135
+ const container = (stack, service) => `${stack.project}-${service}-1`;
136
+ /** The pool's image: SPOTCRAFT_DEV_IMAGE (e.g. a local build), else this CLI's version. */
137
+ export function poolImage(version, env = process.env) {
138
+ return env.SPOTCRAFT_DEV_IMAGE?.trim() || `${SPOTCRAFT_IMAGE}:${version}`;
139
+ }
140
+ /** The Compose file, as JSON (valid YAML), passed to Docker on stdin. */
141
+ export function composeFile(stack, image) {
142
+ const local = (port, inside) => `127.0.0.1:${port}:${inside}`;
143
+ return JSON.stringify({
144
+ name: stack.project,
145
+ services: {
146
+ postgres: {
147
+ image: POSTGRES_IMAGE,
148
+ restart: 'unless-stopped',
149
+ environment: { POSTGRES_PASSWORD: SUPERUSER_PASSWORD },
150
+ command: [
151
+ 'postgres',
152
+ '-c',
153
+ 'hba_file=/etc/postgresql/pg_hba.conf',
154
+ '-c',
155
+ 'password_encryption=scram-sha-256',
156
+ ],
157
+ configs: [{ source: 'pg_hba', target: '/etc/postgresql/pg_hba.conf' }],
158
+ ports: [local(stack.ports.postgres, 5432)],
159
+ volumes: ['data:/var/lib/postgresql'],
160
+ healthcheck: {
161
+ test: ['CMD', 'pg_isready', '-q', '-h', '/var/run/postgresql', '-U', 'postgres'],
162
+ interval: '2s',
163
+ timeout: '5s',
164
+ retries: 30,
165
+ },
166
+ },
167
+ // The user pool, as on the server, with plain HTTP and apps' dev servers trusted.
168
+ auth: {
169
+ image,
170
+ restart: 'unless-stopped',
171
+ working_dir: '/app/auth',
172
+ command: ['src/index.ts'],
173
+ environment: {
174
+ PORT: '3000',
175
+ AUTH_DATABASE_URL: `postgres://spotcraft_auth:${AUTH_PASSWORD}@postgres:5432/${INSTANCE.database}`,
176
+ AUTH_SECRET: stack.authSecret,
177
+ AUTH_ISSUER: LOCAL_ISSUER,
178
+ AUTH_PROTOCOL: 'http',
179
+ AUTH_LOCAL_ORIGINS: '1',
180
+ },
181
+ ports: [local(stack.ports.auth, 3000)],
182
+ depends_on: { postgres: { condition: 'service_healthy' } },
183
+ healthcheck: {
184
+ test: [
185
+ 'CMD',
186
+ '/nodejs/bin/node',
187
+ '-e',
188
+ "fetch('http://127.0.0.1:3000/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))",
189
+ ],
190
+ interval: '2s',
191
+ timeout: '3s',
192
+ retries: 60,
193
+ },
194
+ },
195
+ mailpit: {
196
+ image: MAILPIT_IMAGE,
197
+ restart: 'unless-stopped',
198
+ ports: [local(stack.ports.smtp, 1025), local(stack.ports.mail, 8025)],
199
+ healthcheck: {
200
+ test: ['CMD', '/mailpit', 'readyz'],
201
+ interval: '2s',
202
+ timeout: '3s',
203
+ retries: 30,
204
+ },
205
+ },
206
+ },
207
+ volumes: { data: {} },
208
+ configs: { pg_hba: { content: PG_HBA } },
209
+ });
210
+ }
211
+ /** Runs a command without a shell, optionally feeding `input` on stdin. */
212
+ export function run(file, args, input) {
213
+ return new Promise((resolve) => {
214
+ const child = spawn(file, args, { stdio: ['pipe', 'pipe', 'pipe'] });
215
+ let stdout = '';
216
+ let stderr = '';
217
+ child.stdout.on('data', (chunk) => {
218
+ stdout += chunk;
219
+ });
220
+ child.stderr.on('data', (chunk) => {
221
+ stderr += chunk;
222
+ });
223
+ child.on('error', (error) => resolve({ code: 127, stdout, stderr: error.message }));
224
+ child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
225
+ child.stdin.end(input ?? '');
226
+ });
227
+ }
228
+ export class StackError extends Error {
229
+ }
230
+ /** Docker Compose for the stack; the file comes on stdin. */
231
+ function compose(stack, image, runner, args) {
232
+ return runner('docker', ['compose', '-p', stack.project, '-f', '-', ...args], composeFile(stack, image));
233
+ }
234
+ function fail(what, result) {
235
+ throw new StackError(`${what}\n${`${result.stderr}${result.stdout}`.trim()}`);
236
+ }
237
+ /**
238
+ * Starts the stack (what isn't running yet): Postgres first, then the roles and schemas the
239
+ * deploy script makes on a server, then the user pool and Mailpit, waiting until all are healthy.
240
+ */
241
+ export async function up(stack, image, runner = run) {
242
+ const docker = await runner('docker', ['version', '--format', '{{.Server.Version}}']);
243
+ if (docker.code !== 0)
244
+ fail('Docker is not running (the local stack needs it).', docker);
245
+ const wait = ['up', '-d', '--wait', '--wait-timeout', '180'];
246
+ const postgres = await compose(stack, image, runner, [...wait, 'postgres']);
247
+ if (postgres.code !== 0)
248
+ fail('Could not start the local Postgres.', postgres);
249
+ // As the OS user `postgres`: the superuser only logs in over the socket with `peer`.
250
+ const roles = await runner('docker', [
251
+ 'exec',
252
+ '-i',
253
+ '-u',
254
+ 'postgres',
255
+ container(stack, 'postgres'),
256
+ 'psql',
257
+ '-q',
258
+ '-v',
259
+ 'ON_ERROR_STOP=1',
260
+ '-U',
261
+ 'postgres',
262
+ '-d',
263
+ 'postgres',
264
+ ], `\\set pw ${ADMIN_PASSWORD}\n\\set auth_pw ${AUTH_PASSWORD}\n${ADMIN_SQL}`);
265
+ if (roles.code !== 0)
266
+ fail("Could not set up the agent's and the user pool's roles.", roles);
267
+ const rest = await compose(stack, image, runner, wait);
268
+ if (rest.code !== 0) {
269
+ fail(`Could not start the user pool or Mailpit (the pool's image is ${image}).`, rest);
270
+ }
271
+ }
272
+ /** Stops the stack; the data stays in its volume. */
273
+ export async function down(stack, image, runner = run) {
274
+ const stopped = await compose(stack, image, runner, ['stop']);
275
+ if (stopped.code !== 0)
276
+ fail('Could not stop the local stack.', stopped);
277
+ }
278
+ /** Whether the stack's Postgres is running. */
279
+ export async function isRunning(stack, runner = run) {
280
+ const state = await runner('docker', [
281
+ 'inspect',
282
+ '--format',
283
+ '{{.State.Running}}',
284
+ container(stack, 'postgres'),
285
+ ]);
286
+ return state.code === 0 && state.stdout.trim() === 'true';
287
+ }
288
+ /** Every repository's stack on this machine, running or not, with its state. */
289
+ export async function listStacks(runner = run) {
290
+ const listed = await runner('docker', ['compose', 'ls', '--all', '--format', 'json']);
291
+ if (listed.code !== 0)
292
+ fail('Could not list the local stacks.', listed);
293
+ const projects = JSON.parse(listed.stdout || '[]');
294
+ return projects
295
+ .filter((p) => p.Name.startsWith(PROJECT_PREFIX))
296
+ .map((p) => ({ name: p.Name.slice(PROJECT_PREFIX.length), status: p.Status }));
297
+ }
package/package.json CHANGED
@@ -1,6 +1,58 @@
1
1
  {
2
2
  "name": "@kodentuzo/spotcraft",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.6.0",
4
+ "description": "The spotcraft command: a local stack that matches a Spotcraft server, per repository",
5
+ "keywords": [
6
+ "spotcraft",
7
+ "cli",
8
+ "postgres",
9
+ "local-development"
10
+ ],
11
+ "homepage": "https://spotcraft.dev",
12
+ "bugs": {
13
+ "url": "https://github.com/kodentuzo/spotcraft/issues"
14
+ },
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/kodentuzo/spotcraft.git",
18
+ "directory": "packages/cli"
19
+ },
20
+ "license": "Apache-2.0",
21
+ "type": "module",
22
+ "engines": {
23
+ "node": ">=24"
24
+ },
25
+ "files": [
26
+ "LICENSE",
27
+ "NOTICE",
28
+ "dist"
29
+ ],
30
+ "bin": {
31
+ "spotcraft": "./dist/cli.js"
32
+ },
33
+ "exports": {
34
+ "./provision": {
35
+ "spotcraft-source": "./src/provision.ts",
36
+ "types": "./dist/provision.d.ts",
37
+ "default": "./dist/provision.js"
38
+ }
39
+ },
40
+ "publishConfig": {
41
+ "access": "public"
42
+ },
43
+ "scripts": {
44
+ "build": "tsc -p tsconfig.build.json",
45
+ "typecheck": "tsc",
46
+ "test": "node --conditions=spotcraft-source --test 'test/**/*.test.ts'",
47
+ "spotcraft": "node --conditions=spotcraft-source src/cli.ts",
48
+ "prepack": "node -e \"const fs = require('node:fs'); if (!fs.existsSync('dist')) throw new Error('Build first: pnpm --recursive run build'); for (const f of ['LICENSE', 'NOTICE']) fs.copyFileSync('../../' + f, f)\""
49
+ },
50
+ "dependencies": {
51
+ "pg": "^8.23.1"
52
+ },
53
+ "devDependencies": {
54
+ "@types/node": "catalog:",
55
+ "@types/pg": "^8.23.1",
56
+ "typescript": "catalog:"
57
+ }
58
+ }