@stjoseph/prumo 0.0.3 → 0.0.6

package/dist/output.js

@@ -0,0 +1,24 @@
+export class CliError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+export function errorEnvelope(command, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof CliError ? error.code : isParseArgsError(error) ? 'usage' : 'failed';
+    const data = error instanceof CliError ? error.data : undefined;
+    return data === undefined
+        ? { ok: false, command, error: { code, message } }
+        : { ok: false, command, error: { code, message }, data };
+}
+function isParseArgsError(error) {
+    const code = error?.code;
+    return typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_');
+}
+export function writeEnvelope(envelope) {
+    process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}

package/dist/questions.js

@@ -1,28 +1,29 @@
 import { validateProjectName } from "./names.js";
+import { CliError } from "./output.js";
 const TYPES = ['api', 'web', 'mobile', 'site'];
 const TENANT_AWARE = ['api', 'web', 'mobile'];
 function missing(flag) {
-    throw new Error(`Missing ${flag}. Outside an interactive terminal every answer must come from a flag.`);
+    throw new CliError('needs_input', `Missing ${flag}. Outside an interactive terminal every answer must come from a flag.`);
 }
 function parseTypes(value) {
     const types = value.split(',').map((type) => type.trim());
     const unknown = types.filter((type) => !TYPES.includes(type));
     if (unknown.length > 0 || types.length === 0) {
-        throw new Error(`Unknown type: ${unknown.join(', ')}. Choose from ${TYPES.join(', ')}.`);
+        throw new CliError('invalid_input', `Unknown type: ${unknown.join(', ')}. Choose from ${TYPES.join(', ')}.`);
     }
     return [...new Set(types)];
 }
 export async function resolveAnswers(flags, asker) {
     if (flags.alone && flags.monorepo) {
-        throw new Error('Choose --alone or --monorepo, not both.');
+        throw new CliError('invalid_input', 'Choose --alone or --monorepo, not both.');
     }
     if (flags.multiTenant && flags.singleTenant) {
-        throw new Error('Choose --multi-tenant or --single-tenant, not both.');
+        throw new CliError('invalid_input', 'Choose --multi-tenant or --single-tenant, not both.');
     }
     const name = flags.name ?? (asker === undefined ? missing('the project name') : await asker.name());
     const invalid = validateProjectName(name);
     if (invalid !== undefined) {
-        throw new Error(`Invalid project name "${name}". ${invalid}`);
+        throw new CliError('invalid_input', `Invalid project name "${name}". ${invalid}`);
     }
     let types;
     if (flags.types !== undefined) {
@@ -37,7 +38,7 @@ export async function resolveAnswers(flags, asker) {
     let architecture = 'alone';
     if (types.length > 1) {
         if (flags.alone) {
-            throw new Error('--alone holds a single type; several types make a workspace.');
+            throw new CliError('invalid_input', '--alone holds a single type; several types make a workspace.');
         }
         architecture = 'monorepo';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",

package/templates/api/.env.example

@@ -2,8 +2,11 @@ NODE_ENV=development
 PORT=3000
 LOG_LEVEL=info
 
-DATABASE_URL=postgresql://app:app@localhost:5432/app
-AUTH_DATABASE_URL=postgresql://app:app@localhost:5432/app
+# MISSING until `pnpm db:setup` creates a database; `pnpm dev` offers to run it.
+DATABASE_URL=MISSING
+AUTH_DATABASE_URL=MISSING
+# Read by docker-compose.yml, not by the API: the port Postgres is published on.
+POSTGRES_PORT=5432
 
 BETTER_AUTH_SECRET=replace-this-with-at-least-32-characters
 BETTER_AUTH_URL=http://localhost:3000

package/templates/api/README.md

@@ -2,21 +2,33 @@
 
 ## Requirements
 
-Node 22.17 or later, pnpm, and Docker.
+Node 22.17 or later, pnpm, and Docker Desktop running: the database and the tests both run in it.
 
 ## Running it
 
 ```sh
 pnpm install
-docker compose up -d --wait
-pnpm db:migrate
 pnpm dev
 ```
 
 `.env` comes with the generated project, copied from `.env.example` with a random `BETTER_AUTH_SECRET`. It is not
 committed, so on a fresh clone run `cp .env.example .env` and replace the secret with 32 or more random characters.
 
-The API listens on `http://localhost:3000`. Outside production, its documentation is at `/api/docs`.
+`DATABASE_URL` starts as `MISSING`. While it is, `pnpm dev` offers to create the database first: it asks for a name,
+starts Postgres from `docker-compose.yml` on port 5432 or the next free one (kept in `POSTGRES_PORT`), writes the URL
+into `.env`, and migrates. `pnpm db:setup` does the same at any time. Without a terminal every answer comes from a
+flag: `--name`, `--port`, `--skip-migrate`, and `--json` for one JSON result on stdout.
+
+The API listens on the port in `PORT`, `http://localhost:3000` by default. Outside production, its documentation is
+at `/api/docs`.
+
+Before it starts, `pnpm dev` checks that the port is free. When something else holds it, it says what does, by
+name and pid, and asks whether to stop that process or to move this app to the next free port. Moving it writes the
+new port to `.env`, along with every URL that pointed at the old one. Without a terminal, pass `--kill` or
+`--change` to `scripts/ports.mjs`, or the command stops rather than choosing for you.
+
+Ctrl+C stops everything `pnpm dev` started, not only what the terminal signals: the script remembers the processes
+it spawned, stops them, and frees the port. Anything it did not start is named and left alone.
 
 `pnpm db:migrate` builds first, then runs Better Auth's migrations and then the application's. Before
 migrating, Better Auth logs `Database schema mismatch` because its tables do not exist yet; the migration
@@ -29,6 +41,8 @@ still completes.
 | `pnpm test` | Runs the suite against a throwaway Postgres; Docker must be running |
 | `pnpm lint` | Biome |
 | `pnpm typecheck` | `tsc --noEmit`, also run before every push |
+| `pnpm db:setup` | Creates a development database in Docker, writes its URL into `.env`, and migrates |
+| `pnpm db:migrate` | Builds, then runs Better Auth's migrations and the application's |
 | `pnpm db:migration:create` | Generates a migration from the entity diff, to be read and edited before committing |
 
 ## Conventions

package/templates/api/docker-compose.yml

@@ -1,3 +1,6 @@
+# The Compose project, and so the names of the container and its volume. `prumo new` sets it to the project's name.
+name: api
+
 services:
   postgres:
     image: postgres:18-alpine
@@ -6,7 +9,7 @@ services:
       POSTGRES_PASSWORD: app
       POSTGRES_DB: app
     ports:
-      - '5432:5432'
+      - '${POSTGRES_PORT:-5432}:5432'
     volumes:
       - postgres:/var/lib/postgresql
       - ./docker/init:/docker-entrypoint-initdb.d:ro

package/templates/api/package.json

@@ -6,13 +6,14 @@
     "build": "nest build",
     "start": "nest start",
     "start:dev": "nest start --watch",
-    "dev": "pnpm start:dev",
+    "dev": "node scripts/database.mjs --check && node scripts/ports.mjs -- pnpm start:dev",
     "start:prod": "node dist/main",
     "lint": "biome check",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
+    "db:setup": "node scripts/database.mjs",
     "db:migrate": "nest build && auth migrate --config dist/auth/auth.js --yes && mikro-orm migration:up",
     "db:migration:create": "mikro-orm migration:create",
     "prepare": "node .githooks/install.mjs"

package/templates/api/scripts/database.mjs

@@ -0,0 +1,307 @@
+// Creates the development database in Docker and writes its URL into .env.
+//
+//   node scripts/database.mjs            creates a database, whatever .env holds
+//   node scripts/database.mjs --check    does nothing unless DATABASE_URL is still MISSING; `pnpm dev` runs this
+//
+// The server is always the one in docker-compose.yml, published on 5432 or, when that port is taken, the next free
+// one, kept in POSTGRES_PORT. It needs no dependency, so it runs before `pnpm install` has installed anything.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { connect } from 'node:net'
+import { basename, dirname, join, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { parseArgs } from 'node:util'
+
+const MISSING = 'MISSING'
+const USER = 'app'
+const PASSWORD = 'app'
+const DEFAULT_PORT = 5432
+const PORTS_TRIED = 20
+const NAME = /^[a-z_][a-z0-9_]{0,62}$/
+
+const api = resolve(import.meta.dirname, '..')
+const envPath = join(api, '.env')
+
+const { values } = parseArgs({
+  options: {
+    check: { type: 'boolean', default: false },
+    name: { type: 'string' },
+    port: { type: 'string' },
+    'skip-migrate': { type: 'boolean', default: false },
+    json: { type: 'boolean', default: false },
+  },
+})
+
+const json = values.json
+const interactive = !json && process.stdin.isTTY === true && process.stdout.isTTY === true
+// Under --json, stdout belongs to the result document.
+const childStdio = ['ignore', json ? 2 : 'inherit', 'inherit']
+
+class Failure extends Error {
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}
+
+function say(message) {
+  ;(json ? process.stderr : process.stdout).write(`${message}\n`)
+}
+
+async function ask(question, fallback) {
+  const readline = createInterface({ input: process.stdin, output: process.stdout })
+  const suffix = fallback === undefined ? '' : ` (${fallback})`
+  const answer = (await readline.question(`${question}${suffix}: `)).trim()
+  readline.close()
+  return answer === '' ? fallback : answer
+}
+
+async function confirm(question) {
+  const answer = await ask(`${question} [Y/n]`)
+  return answer === undefined || /^y(es)?$/i.test(answer)
+}
+
+function readEnv() {
+  return existsSync(envPath) ? readFileSync(envPath, 'utf8') : undefined
+}
+
+function envValue(env, key) {
+  return new RegExp(`^${key}=(.*)$`, 'm').exec(env)?.[1]?.trim()
+}
+
+function withEnvValue(env, key, value) {
+  const line = new RegExp(`^${key}=.*$`, 'm')
+  return line.test(env)
+    ? env.replace(line, `${key}=${value}`)
+    : `${env.replace(/\n?$/, '\n')}${key}=${value}\n`
+}
+
+function writeEnv(entries) {
+  let env = readEnv() ?? ''
+  for (const [key, value] of Object.entries(entries)) {
+    env = withEnvValue(env, key, value)
+  }
+  writeFileSync(envPath, env)
+}
+
+function defaultName() {
+  let directory = api
+
+  // The project root is where .prumo/ lives: the api itself when alone, two levels up in a workspace.
+  while (!existsSync(join(directory, '.prumo')) && dirname(directory) !== directory) {
+    directory = dirname(directory)
+  }
+
+  const root = existsSync(join(directory, '.prumo')) ? directory : api
+  const name = basename(root)
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_')
+
+  return NAME.test(name) ? name : `app_${name}`.slice(0, 63)
+}
+
+function docker(args, options = {}) {
+  return spawnSync('docker', args, { cwd: api, encoding: 'utf8', ...options })
+}
+
+function listening(host, port) {
+  return new Promise((done) => {
+    const socket = connect({ host, port, timeout: 1000 })
+    const finish = (open) => {
+      socket.destroy()
+      done(open)
+    }
+    socket.once('connect', () => finish(true))
+    socket.once('timeout', () => finish(false))
+    socket.once('error', () => finish(false))
+  })
+}
+
+async function portTaken(port) {
+  // A server on this machine may listen on only one of the two loopback addresses.
+  return (await listening('127.0.0.1', port)) || (await listening('::1', port))
+}
+
+function requireDocker() {
+  if (docker(['--version']).error !== undefined) {
+    throw new Failure(
+      'docker_missing',
+      'Docker is not installed. Install Docker Desktop from https://www.docker.com/products/docker-desktop/ and run this again.',
+    )
+  }
+  if (docker(['info']).status !== 0) {
+    throw new Failure(
+      'docker_not_running',
+      'Docker is installed but not running. Open Docker Desktop, wait until it says it is running, and run this again.',
+    )
+  }
+}
+
+// The port the service already publishes, when it is up: moving it would only restart it for nothing.
+function publishedPort() {
+  const result = docker(['compose', 'port', 'postgres', '5432'])
+  const port = /:(\d+)\s*$/.exec(result.stdout ?? '')?.[1]
+
+  return result.status === 0 && port !== undefined ? Number(port) : undefined
+}
+
+async function choosePort(env) {
+  const running = publishedPort()
+
+  if (running !== undefined) {
+    return running
+  }
+
+  if (values.port !== undefined) {
+    const port = Number(values.port)
+    if (await portTaken(port)) {
+      throw new Failure('port_busy', `Port ${port} is already in use.`)
+    }
+    return port
+  }
+
+  const start = Number(envValue(env, 'POSTGRES_PORT') ?? DEFAULT_PORT)
+
+  for (let port = start; port < start + PORTS_TRIED; port += 1) {
+    if (!(await portTaken(port))) {
+      if (port !== start) {
+        say(`Port ${start} is in use; Postgres will listen on ${port}.`)
+      }
+      return port
+    }
+  }
+
+  throw new Failure(
+    'port_busy',
+    `Ports ${start} to ${start + PORTS_TRIED - 1} are all in use. Pass --port with a free one.`,
+  )
+}
+
+function startPostgres(port) {
+  // docker-compose.yml reads POSTGRES_PORT from this .env, so the file is written before the service starts.
+  writeEnv({ POSTGRES_PORT: port })
+  say('Starting Postgres in Docker…')
+
+  if (docker(['compose', 'up', '-d', '--wait'], { stdio: childStdio }).status !== 0) {
+    throw new Failure('docker_failed', '`docker compose up -d --wait` failed; its output is above.')
+  }
+}
+
+// Stop at the first error, print bare values, and read the SQL from stdin.
+const PSQL_SCRIPT = ['-v', 'ON_ERROR_STOP=1', '-tAq', '-f', '-']
+
+function sql(database, text) {
+  const result = docker(
+    ['compose', 'exec', '-T', 'postgres', 'psql', '-U', USER, '-d', database, ...PSQL_SCRIPT],
+    { input: text },
+  )
+
+  if (result.error !== undefined || result.status !== 0) {
+    throw new Failure(
+      'postgres_error',
+      result.stderr?.trim() || result.error?.message || 'psql failed',
+    )
+  }
+
+  return result.stdout.trim()
+}
+
+async function main() {
+  const env = readEnv()
+
+  if (values.check) {
+    // No .env, or a URL someone already chose: the API's own validation has the last word.
+    if (env === undefined || envValue(env, 'DATABASE_URL') !== MISSING) {
+      return undefined
+    }
+    if (!interactive) {
+      throw new Failure(
+        'database_missing',
+        'DATABASE_URL is MISSING in .env. Run `pnpm db:setup` first.',
+      )
+    }
+    say('DATABASE_URL in .env is still MISSING.')
+    if (!(await confirm('Create a development database in Docker now?'))) {
+      throw new Failure('declined', 'DATABASE_URL is MISSING. Run `pnpm db:setup` when ready.')
+    }
+  }
+
+  if (env === undefined) {
+    throw new Failure('env_missing', `${envPath} does not exist. Copy .env.example to .env first.`)
+  }
+
+  const name = values.name ?? (interactive ? await ask('Database name', defaultName()) : undefined)
+
+  if (name === undefined) {
+    throw new Failure(
+      'needs_input',
+      'The database name is required. Outside an interactive terminal, pass --name.',
+    )
+  }
+  if (!NAME.test(name)) {
+    throw new Failure(
+      'invalid_name',
+      `"${name}" is not a valid name: lowercase letters, digits and _, not starting with a digit.`,
+    )
+  }
+
+  requireDocker()
+
+  const port = await choosePort(env)
+  startPostgres(port)
+
+  const exists = sql('postgres', `SELECT 1 FROM pg_database WHERE datname = '${name}'`) === '1'
+
+  if (exists) {
+    say(`Database ${name} already exists; using it.`)
+  } else {
+    sql('postgres', `CREATE DATABASE "${name}"`)
+    say(`Created database ${name}.`)
+  }
+
+  // The image runs docker/init only for the database it creates on first start; every other one needs them too.
+  const init = join(api, 'docker', 'init')
+  for (const file of readdirSync(init)
+    .filter((entry) => entry.endsWith('.sql'))
+    .sort()) {
+    sql(name, readFileSync(join(init, file), 'utf8'))
+  }
+
+  const url = `postgresql://${USER}:${PASSWORD}@localhost:${port}/${name}`
+  writeEnv({ DATABASE_URL: url, AUTH_DATABASE_URL: url })
+  say('Wrote DATABASE_URL and AUTH_DATABASE_URL to .env.')
+
+  let migrated = false
+
+  if (!values['skip-migrate']) {
+    say('Migrating…')
+    if (spawnSync('pnpm', ['db:migrate'], { cwd: api, stdio: childStdio }).status !== 0) {
+      throw new Failure(
+        'migrate_failed',
+        '`pnpm db:migrate` failed. The database exists and .env points at it.',
+      )
+    }
+    migrated = true
+  }
+
+  return { database: name, port, created: !exists, migrated }
+}
+
+try {
+  const data = await main()
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok: true, command: 'db', data: data ?? null })}\n`)
+  }
+} catch (error) {
+  const code = error instanceof Failure ? error.code : 'unexpected'
+  const message = error instanceof Error ? error.message : String(error)
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: false, command: 'db', error: { code, message } })}\n`,
+    )
+  } else {
+    process.stderr.write(`${message}\n`)
+  }
+  process.exitCode = 1
+}