@stjoseph/prumo 0.0.5 → 0.0.6

package/README.md

@@ -120,6 +120,12 @@ Once written, those documents belong to the team. Prumo does not come back and r
 | [`docs/DECISIONS.md`](https://github.com/stjosephworks/prumo/blob/main/docs/DECISIONS.md) | Every decision, why it won, and what it costs |
 | [`docs/OPEN-QUESTIONS.md`](https://github.com/stjosephworks/prumo/blob/main/docs/OPEN-QUESTIONS.md) | What has been raised and is still unresolved |
 
+## Releasing
+
+`main` publishes itself. A push to `main` runs the whole CI, and when `cli/package.json` carries a version the
+registry does not have yet, the `publish` job sends it to npm through npm's trusted publishing, with provenance and
+without a token in the repository. Any other push to `main` publishes nothing.
+
 ## Status
 
 Prumo is in beta. `0.0.1` is the first published version: every template runs and every generated

package/dist/clean.js

@@ -17,7 +17,7 @@ export const README_PARAGRAPH = '`DATABASE_URL` starts as `MISSING`. While it is
 const README_REPLACEMENT = 'Before the first `pnpm dev`, start Postgres with `docker compose up -d --wait` and run `pnpm db:migrate`.\n' +
     '`.env.example` points at that service on port 5432; when `POSTGRES_PORT` changes, change both URLs with it.\n';
 export const README_ROW = '| `pnpm db:setup` | Creates a development database in Docker, writes its URL into `.env`, and migrates |\n';
-export const WORKSPACE_SENTENCE = 'If the workspace holds `api` and its database is not set up yet, it offers to create one first. ';
+export const WORKSPACE_SENTENCE = 'If the workspace holds `api` and its database is not set up yet, `pnpm dev` offers to create the database first.\n\n';
 function textRule(id, file, description, from, to, marker) {
     return {
         id,
@@ -55,7 +55,7 @@ function rulesFor(root, api, templates) {
         textRule('api-readme-row', at('README.md'), 'Remove `db:setup` from the README', README_ROW, '', '`pnpm db:setup`'),
     ];
     if (api !== root) {
-        rules.push(devRule('root-dev-check', 'package.json', ROOT_DEV_PREFIX), textRule('root-readme', 'README.md', 'Remove the database offer from the README', WORKSPACE_SENTENCE, '', 'offers to create one'));
+        rules.push(devRule('root-dev-check', 'package.json', ROOT_DEV_PREFIX), textRule('root-readme', 'README.md', 'Remove the database offer from the README', WORKSPACE_SENTENCE, '', 'offers to create the database'));
     }
     return { rules, script: join(templates, 'api', 'scripts', 'database.mjs') };
 }

package/dist/compose.js

@@ -204,12 +204,12 @@ export async function composeWorkspace({ templates, target, types, mobileScheme
         });
     }
     // One command for everything and one per app. Each app answers to `dev`, so the root never needs to know how.
-    // The API's database check is the exception: it may ask a question, which the interleaved output of a parallel
-    // run would bury, so the root asks it first and the API's own check then finds nothing to do.
-    const parallelDev = 'pnpm -r --parallel dev';
-    const dev = types.includes('api')
-        ? `node apps/api/scripts/database.mjs --check && ${parallelDev}`
-        : parallelDev;
+    // The database and the ports are the exception: both may ask a question, which the interleaved output of a
+    // parallel run would bury, so the root asks first and each app's own check then finds nothing to do.
+    // `pnpm -r --parallel` starts each app in its own process group, so Ctrl+C reaches pnpm and leaves the apps
+    // running. The ports script wraps the run, remembers what it started, and stops all of it on the way out.
+    const database = types.includes('api') ? 'node apps/api/scripts/database.mjs --check && ' : '';
+    const dev = `${database}node scripts/ports.mjs --all -- pnpm -r --parallel dev`;
     await rewriteText(join(target, 'package.json'), (text) => types.reduce((pkg, type) => setJsonc(pkg, ['scripts', type], `pnpm --filter ${type} dev`), setJsonc(text, ['scripts', 'dev'], dev)));
     const manifests = await Promise.all(apps.map(async (app) => readJsonc(await readFile(join(app, 'package.json'), 'utf8'))));
     const catalogs = collectCatalog(manifests);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.0.5",
+  "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/README.md

@@ -19,7 +19,16 @@ starts Postgres from `docker-compose.yml` on port 5432 or the next free one (kep
 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 `http://localhost:3000`. Outside production, its documentation is at `/api/docs`.
+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

package/templates/api/package.json

@@ -6,7 +6,7 @@
     "build": "nest build",
     "start": "nest start",
     "start:dev": "nest start --watch",
-    "dev": "node scripts/database.mjs --check && 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",

package/templates/api/scripts/ports.mjs

@@ -0,0 +1,508 @@
+// Makes sure the ports the apps need are free before anything starts, and runs the dev command with the port it
+// resolved. The same file ships in every app and at a workspace root; the copies are identical on purpose.
+//
+//   node scripts/ports.mjs --all              every app of a workspace, before its parallel run
+//   node scripts/ports.mjs -- vite            this app: free its port, run the command, and stop its tree at the end
+//   node scripts/ports.mjs --check            this app: free its port and stop
+//
+// A port in use is a question, never a silent choice: stop what holds it, or move this app to the next free port.
+// Moving it rewrites the port in .env, and with it every URL that pointed at the old one.
+import { spawn, spawnSync } from 'node:child_process'
+import { existsSync, 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'
+
+// Where each app keeps its port, what it falls back to, and how its dev command is told about it.
+const APPS = {
+  api: { key: 'PORT', fallback: 3000, flag: [] },
+  web: { key: 'WEB_PORT', fallback: 5173, flag: ['--port', '--strictPort'] },
+  site: { key: 'SITE_PORT', fallback: 3200, flag: ['--port'] },
+  mobile: { key: 'METRO_PORT', fallback: 8081, flag: ['--port'] },
+}
+
+// A port that moves takes these with it: the key to write, in which app, from which app's port.
+const FOLLOWERS = {
+  api: [
+    { app: 'api', key: 'BETTER_AUTH_URL' },
+    { app: 'web', key: 'VITE_API_URL' },
+    { app: 'mobile', key: 'EXPO_PUBLIC_API_URL' },
+  ],
+  web: [{ app: 'api', key: 'WEB_ORIGIN' }],
+  site: [],
+  mobile: [],
+}
+
+const PORTS_TRIED = 20
+const windows = process.platform === 'win32'
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    all: { type: 'boolean', default: false },
+    check: { type: 'boolean', default: false },
+    kill: { type: 'boolean', default: false },
+    change: { type: 'boolean', default: false },
+    json: { type: 'boolean', default: false },
+  },
+})
+
+const json = values.json
+const interactive = !json && process.stdin.isTTY === true && process.stdout.isTTY === true
+const here = resolve(import.meta.dirname, '..')
+
+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 choose(question, answers) {
+  const readline = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = (await readline.question(`${question} [${answers.join('/')}]: `))
+    .trim()
+    .toLowerCase()
+  readline.close()
+
+  return answers.find((option) => option.startsWith(answer === '' ? answers[0] : answer))
+}
+
+function envPath(directory) {
+  return join(directory, '.env')
+}
+
+function readEnv(directory) {
+  const path = envPath(directory)
+
+  return existsSync(path) ? readFileSync(path, 'utf8') : undefined
+}
+
+function envValue(env, key) {
+  return new RegExp(`^${key}=(.*)$`, 'm').exec(env ?? '')?.[1]?.trim()
+}
+
+function writeEnvValue(directory, key, value) {
+  const env = readEnv(directory)
+
+  if (env === undefined) {
+    return
+  }
+
+  const line = new RegExp(`^${key}=.*$`, 'm')
+  writeFileSync(
+    envPath(directory),
+    line.test(env)
+      ? env.replace(line, `${key}=${value}`)
+      : `${env.replace(/\n?$/, '\n')}${key}=${value}\n`,
+  )
+}
+
+// The project root holds .prumo/; an app of a workspace sits two levels below it.
+function projectRoot() {
+  let directory = here
+
+  while (!existsSync(join(directory, '.prumo')) && dirname(directory) !== directory) {
+    directory = dirname(directory)
+  }
+
+  return existsSync(join(directory, '.prumo')) ? directory : here
+}
+
+const root = projectRoot()
+const workspace = existsSync(join(root, 'apps'))
+
+function directoryOf(type) {
+  return workspace ? join(root, 'apps', type) : root
+}
+
+function typeOf(directory) {
+  const name = basename(directory)
+
+  if (APPS[name] !== undefined) {
+    return name
+  }
+
+  // An alone project is named by its author, so only .prumo/config.json says what it is.
+  const config = join(root, '.prumo', 'config.json')
+  const types = existsSync(config) ? JSON.parse(readFileSync(config, 'utf8')).types : []
+
+  return types[0]
+}
+
+function typesToCheck() {
+  if (!values.all) {
+    return [typeOf(here)]
+  }
+
+  return Object.keys(APPS).filter((type) => existsSync(join(directoryOf(type), 'package.json')))
+}
+
+function portOf(type) {
+  const app = APPS[type]
+
+  return Number(envValue(readEnv(directoryOf(type)), app.key) ?? app.fallback)
+}
+
+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 taken(port) {
+  // A server may be bound to only one of the two loopback addresses.
+  return (await listening('127.0.0.1', port)) || (await listening('::1', port))
+}
+
+// Who holds the port, as pid and command, so that nothing is ever killed unnamed.
+function holders(port) {
+  if (windows) {
+    const lines = spawnSync('netstat', ['-ano'], { encoding: 'utf8' }).stdout ?? ''
+    const pids = new Set(
+      lines
+        .split('\n')
+        .filter((line) => /LISTENING/.test(line) && new RegExp(`[:.]${port}\\s`).test(line))
+        .map((line) => line.trim().split(/\s+/).at(-1))
+        .filter((pid) => pid !== undefined && pid !== '0'),
+    )
+
+    return [...pids].map((pid) => ({ pid: Number(pid), command: commandOf(pid) }))
+  }
+
+  const found = spawnSync('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN'], { encoding: 'utf8' })
+  const pids = new Set((found.stdout ?? '').split('\n').filter(Boolean))
+
+  return [...pids].map((pid) => ({ pid: Number(pid), command: commandOf(pid) }))
+}
+
+function commandOf(pid) {
+  const result = windows
+    ? spawnSync('tasklist', ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'], { encoding: 'utf8' })
+    : spawnSync('ps', ['-p', String(pid), '-o', 'comm='], { encoding: 'utf8' })
+  const output = (result.stdout ?? '').trim()
+
+  return windows
+    ? (output.split(',')[0]?.replaceAll('"', '') ?? 'unknown')
+    : basename(output || 'unknown')
+}
+
+async function freed(port) {
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    if (!(await taken(port))) {
+      return true
+    }
+    await new Promise((done) => setTimeout(done, 100))
+  }
+
+  return false
+}
+
+async function stopHolders(port, found) {
+  for (const { pid } of found) {
+    if (windows) {
+      spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' })
+    } else {
+      // The whole group, so that a shell's children go with it; a lone process when it leads no group.
+      try {
+        process.kill(-pid, 'SIGTERM')
+      } catch {
+        try {
+          process.kill(pid, 'SIGTERM')
+        } catch {}
+      }
+    }
+  }
+
+  if (await freed(port)) {
+    say(`Port ${port} is free.`)
+    return
+  }
+
+  for (const { pid } of found) {
+    try {
+      process.kill(windows ? pid : -pid, 'SIGKILL')
+    } catch {}
+  }
+
+  if (!(await freed(port))) {
+    throw new Failure('port_busy', `Port ${port} is still in use by ${describe(found)}.`)
+  }
+
+  say(`Port ${port} is free.`)
+}
+
+function describe(found) {
+  return (
+    found.map(({ pid, command }) => `${command} (pid ${pid})`).join(', ') || 'an unknown process'
+  )
+}
+
+async function nextFree(from) {
+  for (let port = from + 1; port < from + PORTS_TRIED; port += 1) {
+    if (!(await taken(port))) {
+      return port
+    }
+  }
+
+  throw new Failure('port_busy', `No free port between ${from + 1} and ${from + PORTS_TRIED - 1}.`)
+}
+
+function movePort(type, port) {
+  const app = APPS[type]
+
+  writeEnvValue(directoryOf(type), app.key, port)
+
+  for (const follower of FOLLOWERS[type]) {
+    const directory = directoryOf(follower.app)
+
+    if (existsSync(join(directory, 'package.json'))) {
+      writeEnvValue(directory, follower.key, `http://localhost:${port}`)
+    }
+  }
+}
+
+async function settle(type) {
+  const port = portOf(type)
+
+  if (!(await taken(port))) {
+    return port
+  }
+
+  const found = holders(port)
+
+  say(`${type} wants port ${port}, held by ${describe(found)}.`)
+
+  const moved = async () => {
+    const free = await nextFree(port)
+    movePort(type, free)
+    say(`${type} moved to port ${free}, written to .env.`)
+    return free
+  }
+
+  if (values.kill) {
+    await stopHolders(port, found)
+    return port
+  }
+  if (values.change) {
+    return moved()
+  }
+  if (!interactive) {
+    throw new Failure(
+      'port_busy',
+      `Port ${port} is in use by ${describe(found)}. Pass --kill to stop it, or --change to move ${type} to the next free port.`,
+    )
+  }
+
+  const answer = await choose('Stop that process, or move this app?', ['stop', 'move', 'cancel'])
+
+  if (answer === 'stop') {
+    await stopHolders(port, found)
+    return port
+  }
+  if (answer === 'move') {
+    return moved()
+  }
+
+  throw new Failure('declined', 'Nothing was started.')
+}
+
+// Every process below one, as the system sees them right now.
+function processTree(pid) {
+  const listed = windows
+    ? spawnSync(
+        'powershell',
+        [
+          '-NoProfile',
+          '-Command',
+          'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId)" }',
+        ],
+        { encoding: 'utf8' },
+      )
+    : spawnSync('ps', ['-eo', 'pid=,ppid='], { encoding: 'utf8' })
+  const children = new Map()
+
+  for (const line of (listed.stdout ?? '').split('\n')) {
+    const [child, parent] = line.trim().split(/\s+/).map(Number)
+
+    if (Number.isInteger(child) && Number.isInteger(parent)) {
+      children.set(parent, [...(children.get(parent) ?? []), child])
+    }
+  }
+
+  const tree = []
+  const pending = [pid]
+
+  while (pending.length > 0) {
+    const current = pending.shift()
+
+    tree.push(current)
+    pending.push(...(children.get(current) ?? []))
+  }
+
+  // Deepest first, so a parent does not restart what was just stopped.
+  return tree.reverse()
+}
+
+function signal(pid, sign) {
+  try {
+    process.kill(pid, sign)
+  } catch {}
+}
+
+// `pnpm -r --parallel` starts each app in a process group of its own, so the terminal's Ctrl+C reaches pnpm and
+// nothing below it. Whatever was started here is therefore stopped from here, and never anything else: the tree is
+// read before the first signal, while the processes still point at their parents.
+async function shutdown(child, ports, known) {
+  const tree = [...new Set([...processTree(child.pid), ...known])].reverse()
+  const stopped = []
+
+  if (windows) {
+    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+  } else {
+    for (const pid of tree) {
+      signal(pid, 'SIGTERM')
+    }
+  }
+
+  for (const port of ports) {
+    if (!(await freed(port))) {
+      const ours = holders(port).filter((holder) => tree.includes(holder.pid))
+      const theirs = holders(port).filter((holder) => !tree.includes(holder.pid))
+
+      for (const { pid, command } of ours) {
+        signal(pid, 'SIGKILL')
+        stopped.push(`${command} (pid ${pid}) on port ${port}`)
+      }
+
+      if (theirs.length > 0) {
+        say(`Port ${port} is still held by ${describe(theirs)}, which this project did not start.`)
+      }
+    }
+  }
+
+  if (stopped.length > 0) {
+    say(`Stopped what was left behind: ${stopped.join(', ')}.`)
+  }
+
+  return stopped
+}
+
+async function supervise(child, ports) {
+  // Ctrl+C reaches the child through the terminal; this process only waits, and then makes sure nothing survived.
+  // Once the child is gone, its own children answer to the system and no longer to it, so who they were is
+  // remembered while they are still running: on a schedule, and again the moment the signal arrives.
+  const known = new Set([child.pid])
+  const remember = () => {
+    for (const pid of processTree(child.pid)) {
+      known.add(pid)
+    }
+  }
+
+  let interrupted = false
+  const interrupt = (sign) => {
+    interrupted = true
+    remember()
+
+    // The terminal signals the whole group, but a parent that signals this process alone would leave the child
+    // running and this one waiting on it forever.
+    for (const pid of [...known].reverse()) {
+      signal(pid, sign)
+    }
+  }
+
+  const onInterrupt = () => interrupt('SIGINT')
+  const onTerminate = () => interrupt('SIGTERM')
+
+  process.on('SIGINT', onInterrupt)
+  process.on('SIGTERM', onTerminate)
+
+  remember()
+  const watch = setInterval(remember, 2000)
+
+  let patience
+  const code = await new Promise((done) => {
+    child.once('error', () => done(1))
+    child.once('exit', (status, sign) => done(sign === null ? (status ?? 1) : 0))
+
+    // A child that will not go after being asked does not hold this process hostage; shutdown kills it.
+    patience = setInterval(() => {
+      if (interrupted) {
+        clearInterval(patience)
+        patience = setTimeout(() => done(130), 10_000)
+      }
+    }, 200)
+  })
+
+  clearInterval(patience)
+  clearTimeout(patience)
+  clearInterval(watch)
+
+  const stopped = await shutdown(child, ports, known)
+
+  process.off('SIGINT', onInterrupt)
+  process.off('SIGTERM', onTerminate)
+  process.exitCode = interrupted ? 0 : code
+
+  return stopped
+}
+
+async function main() {
+  const ports = {}
+
+  for (const type of typesToCheck()) {
+    if (type !== undefined) {
+      ports[type] = await settle(type)
+    }
+  }
+
+  const [command, ...args] = positionals
+
+  if (command === undefined) {
+    return { ports }
+  }
+
+  // Only an app tells its command which port to use. A workspace root wraps `pnpm`, which would pass a stray
+  // `--port` on to every app it runs.
+  const [type] = values.all ? [] : Object.keys(ports)
+  const flag = APPS[type ?? '']?.flag ?? []
+  const withPort = flag.flatMap((entry) =>
+    entry === '--port' ? ['--port', String(ports[type])] : [entry],
+  )
+  const child = spawn(command, [...args, ...withPort], { stdio: 'inherit', shell: windows })
+  const stopped = await supervise(child, Object.values(ports))
+
+  return { ports, ran: [command, ...args, ...withPort].join(' '), stopped }
+}
+
+try {
+  const data = await main()
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok: true, command: 'ports', data })}\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: 'ports', error: { code, message } })}\n`,
+    )
+  } else {
+    process.stderr.write(`${message}\n`)
+  }
+  process.exitCode = 1
+}

package/templates/mobile/.env.example

@@ -1 +1,4 @@
+# The port Metro serves on; `pnpm dev` moves it when it is taken.
+METRO_PORT=8081
+
 EXPO_PUBLIC_API_URL=http://localhost:3000

package/templates/mobile/README.md

@@ -15,6 +15,16 @@ pnpm dev
 `.env` comes with the generated project, copied from `.env.example`; `EXPO_PUBLIC_API_URL` points at the API. It is
 not committed, so on a fresh clone run `cp .env.example .env`.
 
+Metro serves on the port in `METRO_PORT`, 8081 by default.
+
+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.
+
 On an Android emulator `localhost` is the emulator itself; point `EXPO_PUBLIC_API_URL` at your machine's address.
 
 ## Everyday commands

package/templates/mobile/jest.config.js

@@ -12,6 +12,10 @@ if (!nodeModules.includes('(?!(') || babel === undefined) {
 module.exports = {
   preset: 'jest-expo',
   moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1' },
+  // A first render brings React Native and Babel's transform with it, which costs seconds on a cold cache: inside a
+  // workspace the contract is a package to transform too, and Jest's 5s default was crossed in CI while the same
+  // suite passed alone. The budget is the machine's slowness, not the test's.
+  testTimeout: 30_000,
   // Better Auth ships ESM only, partly as .mjs, so it joins the packages jest-expo transforms, with the same Babel.
   transform: { '\\.mjs$': babel },
   transformIgnorePatterns: [

package/templates/mobile/package.json

@@ -5,7 +5,7 @@
   "main": "expo-router/entry",
   "scripts": {
     "start": "expo start",
-    "dev": "pnpm start",
+    "dev": "node scripts/ports.mjs -- expo start",
     "ios": "expo start --ios",
     "android": "expo start --android",
     "bundle": "expo export --platform ios --platform android",