@stjoseph/prumo 0.0.5 → 0.1.0

package/templates/workspace/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/.prumo-templates/api/modules.md

@@ -1,117 +0,0 @@
-# Modules
-
-## Rule
-
-Create one module per resource: `users`, `orders`, `invoices`.
-
-A module contains exactly what `nest g resource` produces: `*.module.ts`, `*.controller.ts`,
-`*.service.ts`, `dto/`, `entities/` and the co-located spec files. Add nothing to that set, **except further
-services**.
-
-Add a service to a module when a group of its methods has a name of its own that the resource's name does
-not cover: `order-refunds`, `order-shipping`. Generate it with `nest g service <name> <module> --flat`, beside
-the resource's service. Do not split by line count, and do not create a `services/` directory or one service
-per action.
-
-Two services in one module never inject each other in both directions.
-
-Export the service. Mark every method that serves only its own module `private`.
-
-Reach another module through `imports: [OtherModule]` and inject what it exports. Reference another
-module's entity when a relation requires it.
-
-Two modules never depend on each other. When they appear to, move the common part into a third
-module. Do not use `forwardRef`.
-
-Do not use barrel files inside a module.
-
-Anything serving more than one module becomes its own module, named for what it does:
-`notifications`, `pdf`, `storage`. There is no `SharedModule`.
-
-A pure function is a function in a file, imported directly. It gets no module.
-
-## Rationale
-
-Nest supplies the mechanism and decides none of this, so every rule above exists to remove a choice
-that would otherwise be made differently in each module and by each assistant.
-
-One module per resource is the shape `nest g resource` generates and the shape every Nest example
-already has, so the generator and the convention never disagree and a generated module needs no
-correction afterwards. Designing an anatomy instead is what previously cost thirteen files per
-feature, five of which carried no guarantee.
-
-`private` makes the compiler enforce the module's surface, at no cost. A cycle is refused because
-Nest's own guidance is to avoid one: `forwardRef` is its escape hatch, and its documented caveats
-include an indeterminate order of instantiation, the class of failure that appears once in
-production and does not reproduce. Barrel files are refused because Nest names them as a way to
-create a cycle nobody can see.
-
-**The extra service exists for the module that is large and still one thing.** Splitting into another
-module is right when a second responsibility has crept in, and wrong when it has not: two modules sharing the
-same entities and invariants end up wanting to call each other, which is the cycle refused above. Nest's own
-answer is several providers in one module, and `nest g service <name> <module>` both creates the file and
-registers it, so the generator and the convention still agree.
-
-The criterion is a name rather than a size because a line limit ages and invites gaming: somebody moves
-arbitrary methods out to pass the number, and the result is worse than the long file. `--flat` keeps the
-anatomy one level deep. One service per action is refused on evidence: it is what produced thirteen files
-per feature.
-
-**What this costs:** the split is a judgement, held by review. And a module with several services can form a
-cycle inside itself, which is why the cycle rule now reaches between services as well as between modules.
-
-A `SharedModule` has no admission criterion, so it only grows. Requiring a name forces the question
-*what is this*, and a module nobody can name should not exist.
-
-## Applies to
-
-Every module under `src/`. The rules about reaching across modules apply wherever one module's code
-refers to another's.
-
-## Examples
-
-Exporting the service, with internals closed:
-
-```
-✅  export class UsersService {
-      findById(id: string) {}
-      private normaliseEmail(v: string) {}
-    }
-
-❌  export class UsersService {
-      findById(id: string) {}
-      normaliseEmail(v: string) {}   // reachable from any module that injects this
-    }
-```
-
-Growing a module that is still one thing:
-
-```
-✅  orders/orders.service.ts
-    orders/order-refunds.service.ts     // nest g service order-refunds orders --flat
-❌  orders/services/cancel-order.service.ts
-❌  refunds/refunds.module.ts           // needs orders' entities, and orders needs it back
-```
-
-Reaching another module:
-
-```
-✅  @Module({ imports: [UsersModule] })
-❌  @Module({ imports: [forwardRef(() => UsersModule)] })
-```
-
-Importing inside a module:
-
-```
-✅  import { UsersService } from './users.service'
-❌  import { UsersService } from './index'
-```
-
-## Enforcement
-
-**Lint.** Barrel-file imports inside a module are verifiable and are caught by a lint rule.
-
-**Review only.** Everything else. Nothing checks that a module maps to a resource, that an extra service
-has a name of its own rather than an arbitrary slice, that a method that
-should be `private` is, or that a `SharedModule` has not been created; a reviewer does. `private`
-prevents accidental injection; it does not prevent someone widening the method next week to reach it.

package/templates/api/nest-cli.json

@@ -1,10 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/nest-cli",
-  "collection": "@nestjs/schematics",
-  "sourceRoot": "src",
-  "compilerOptions": {
-    "deleteOutDir": true,
-    "tsConfigPath": "tsconfig.build.json",
-    "plugins": ["@nestjs/swagger/plugin"]
-  }
-}

package/templates/api/src/app.module.ts

@@ -1,46 +0,0 @@
-import { MikroOrmModule } from '@mikro-orm/nestjs'
-import { PostgreSqlDriver } from '@mikro-orm/postgresql'
-import { type MiddlewareConsumer, Module, type NestModule } from '@nestjs/common'
-import { APP_FILTER } from '@nestjs/core'
-import { LoggerModule } from 'nestjs-pino'
-import { AuthModule } from '@/auth/auth.module'
-import { Env } from '@/config/env'
-import { EnvModule } from '@/config/env.module'
-import { ProblemDetailsFilter } from '@/errors/problem-details.filter'
-import { HealthModule } from '@/health/health.module'
-import { createOrmConfig } from '@/mikro-orm.factory'
-import { RequestContextModule } from '@/request-context/request-context.module'
-import { RequestIdMiddleware } from '@/request-context/request-id.middleware'
-import { UsersModule } from '@/users/users.module'
-
-@Module({
-  imports: [
-    EnvModule,
-    LoggerModule.forRootAsync({
-      inject: [Env],
-      useFactory: (env: Env) => ({
-        pinoHttp: {
-          level: env.LOG_LEVEL,
-          redact: ['req.headers.authorization', 'req.headers.cookie', 'res.headers["set-cookie"]'],
-          transport: env.NODE_ENV === 'development' ? { target: 'pino-pretty' } : undefined,
-          autoLogging: { ignore: (req) => req.url?.startsWith('/api/health') === true },
-        },
-      }),
-    }),
-    MikroOrmModule.forRootAsync({
-      inject: [Env],
-      driver: PostgreSqlDriver,
-      useFactory: (env: Env) => createOrmConfig(env),
-    }),
-    RequestContextModule,
-    AuthModule,
-    HealthModule,
-    UsersModule,
-  ],
-  providers: [{ provide: APP_FILTER, useClass: ProblemDetailsFilter }],
-})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer): void {
-    consumer.apply(RequestIdMiddleware).forRoutes('*path')
-  }
-}

package/templates/api/src/auth/auth.constants.ts

@@ -1,2 +0,0 @@
-export const AUTH = Symbol('AUTH')
-export const IS_PUBLIC = Symbol('IS_PUBLIC')

package/templates/api/src/auth/auth.controller.ts

@@ -1,19 +0,0 @@
-import { All, Controller, Inject, Req, Res, VERSION_NEUTRAL } from '@nestjs/common'
-import { ApiExcludeController } from '@nestjs/swagger'
-import { toNodeHandler } from 'better-auth/node'
-import type { Request, Response } from 'express'
-import { AUTH } from './auth.constants'
-import type { Auth } from './auth.factory'
-import { Public } from './public.decorator'
-
-@ApiExcludeController()
-@Controller({ path: 'auth', version: VERSION_NEUTRAL })
-export class AuthController {
-  constructor(@Inject(AUTH) private readonly auth: Auth) {}
-
-  @Public()
-  @All('*path')
-  handle(@Req() request: Request, @Res() response: Response): Promise<void> {
-    return toNodeHandler(this.auth)(request, response)
-  }
-}