@c9up/ream 0.2.24 → 0.2.26

package/src/console/make/generators.ts

@@ -0,0 +1,176 @@
+/**
+ * What each `make:` command generates.
+ *
+ * One table rather than ten near-identical commands: every generator is a
+ * name, a stub and the variables that stub reads. The differences that matter
+ * — which suffix a class carries, whether the name is snake_cased for the file
+ * — live here, in one place, instead of being spread across ten files that
+ * drift.
+ *
+ * The DESTINATION is not here. It is in the stub's own front matter, so an
+ * application that publishes `stubs/make/controller.stub` can move the file as
+ * well as change its contents.
+ */
+
+import type { StubState } from '../../stubs/template.js'
+import { ensureSuffix, stripSuffixInsensitive, toPascalCase, toSnakeCase } from './naming.js'
+
+/** Extra input a generator takes beyond the name. */
+export interface GeneratorInput {
+  /** `app/<module>/…` — where a module-scoped file lands. */
+  module?: string
+  /** `make:middleware --stack server|router|named`. */
+  stack?: string
+  /** `make:listener --event OrderShipped`. */
+  event?: string
+}
+
+export interface Generator {
+  /** The stub, under `stubs/make/`. */
+  kind: string
+  commandName: string
+  description: string
+  /** Does it take `--module`? */
+  moduleScoped: boolean
+  /** The variables its stub reads. */
+  state(name: string, input: GeneratorInput): StubState
+}
+
+/** The shared trio every stub may read. */
+function base(name: string, className: string, module: string): StubState {
+  return { className, module, name }
+}
+
+export const GENERATORS: readonly Generator[] = [
+  {
+    kind: 'controller',
+    commandName: 'make:controller',
+    description: 'Generate an HTTP controller',
+    moduleScoped: true,
+    state: (name, input) =>
+      base(name, ensureSuffix(name, 'Controller'), input.module ?? 'controllers'),
+  },
+  {
+    kind: 'service',
+    commandName: 'make:service',
+    description: 'Generate a service class',
+    moduleScoped: true,
+    state: (name, input) => base(name, ensureSuffix(name, 'Service'), input.module ?? 'services'),
+  },
+  {
+    kind: 'entity',
+    commandName: 'make:entity',
+    description: 'Generate an Atlas entity',
+    moduleScoped: true,
+    state: (name, input) => ({
+      // No suffix: an entity is `User`, not `UserEntity`.
+      ...base(name, toPascalCase(name), input.module ?? 'entities'),
+      tableName: `${toSnakeCase(name)}s`,
+    }),
+  },
+  {
+    kind: 'validator',
+    commandName: 'make:validator',
+    description: 'Generate a Rune validator',
+    moduleScoped: true,
+    state: (name, input) =>
+      base(name, ensureSuffix(name, 'Validator'), input.module ?? 'validators'),
+  },
+  {
+    kind: 'provider',
+    commandName: 'make:provider',
+    description: 'Generate a service provider',
+    moduleScoped: false,
+    state: (name) => base(name, ensureSuffix(name, 'Provider'), ''),
+  },
+  {
+    kind: 'command',
+    commandName: 'make:command',
+    description: 'Generate a console command',
+    moduleScoped: false,
+    state: (name) => {
+      // `app:provision` is the command NAME; the class and the file come from
+      // its last segment, or the published stub would generate a command
+      // unreachable under the name it was asked for.
+      const segments = name.split(':')
+      const last = segments[segments.length - 1] ?? name
+      return {
+        className: toPascalCase(toSnakeCase(last)),
+        fileName: toSnakeCase(last),
+        name,
+      }
+    },
+  },
+  {
+    kind: 'middleware',
+    commandName: 'make:middleware',
+    description: 'Generate an HTTP middleware',
+    moduleScoped: false,
+    state: (name, input) => {
+      const fileName = toSnakeCase(stripSuffixInsensitive(name, 'middleware'))
+      const stack = input.stack ?? 'router'
+      const importer = `() => import('#middleware/${fileName}_middleware.js')`
+      // The line the user pastes into their kernel — different per stack, and
+      // wrong in a way that is hard to spot if it is guessed.
+      const registration =
+        stack === 'server'
+          ? `server.use([${importer}])`
+          : stack === 'named'
+            ? `router.named({ ${fileName}: ${importer} })`
+            : `router.use([${importer}])`
+      return {
+        className: `${toPascalCase(fileName)}Middleware`,
+        fileName,
+        name,
+        registration,
+        stack,
+      }
+    },
+  },
+  {
+    kind: 'event',
+    commandName: 'make:event',
+    description: 'Generate an event class',
+    moduleScoped: false,
+    state: (name) => {
+      const fileName = toSnakeCase(name)
+      return { className: toPascalCase(fileName), fileName, name }
+    },
+  },
+  {
+    kind: 'listener',
+    commandName: 'make:listener',
+    description: 'Generate an event listener',
+    moduleScoped: false,
+    state: (name, input) => {
+      const fileName = toSnakeCase(name)
+      const className = toPascalCase(fileName)
+      if (input.event === undefined) {
+        // Without `--event` there is nothing to type the handler with, and
+        // inventing an import would point at a file that does not exist.
+        return {
+          className,
+          fileName,
+          name,
+          importLine: '',
+          eventType: 'unknown',
+          registration: `emitter.on(SomeEvent, ${className})`,
+        }
+      }
+      const eventFile = toSnakeCase(input.event)
+      const eventClass = toPascalCase(eventFile)
+      return {
+        className,
+        fileName,
+        name,
+        importLine: `import type ${eventClass} from '#app/events/${eventFile}.js'\n\n`,
+        eventType: eventClass,
+        registration: `emitter.on(${eventClass}, ${className})`,
+      }
+    },
+  },
+]
+
+export function generatorFor(kind: string): Generator | undefined {
+  return GENERATORS.find((generator) => generator.kind === kind)
+}

package/src/console/make/naming.ts

@@ -0,0 +1,85 @@
+/**
+ * The naming conventions the generators follow.
+ *
+ * Ported from the Rust generator they replace, case for case: a rename here
+ * changes what `make:controller user` produces, so the rules are written out
+ * rather than approximated.
+ */
+
+/** Add the suffix unless the name already carries it. */
+export function ensureSuffix(name: string, suffix: string): string {
+  return name.endsWith(suffix) ? name : `${name}${suffix}`
+}
+
+/** `user_profile` / `user-profile` / `user profile` → `UserProfile`. */
+export function toPascalCase(name: string): string {
+  return name
+    .split(/[_\-\s]/)
+    .filter((part) => part !== '')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+/**
+ * `UserProfile` → `user_profile`, `HTTPServer` → `http_server`.
+ *
+ * The acronym case is why this is not a one-line regex: an underscore goes
+ * before a capital that FOLLOWS a lowercase, or that follows a capital and is
+ * followed by a lowercase — which is where `HTTPServer` splits.
+ */
+export function toSnakeCase(name: string): string {
+  const chars = [...name]
+  let out = ''
+  for (const [index, char] of chars.entries()) {
+    if (char.toUpperCase() === char && char.toLowerCase() !== char) {
+      const previous = chars[index - 1]
+      const next = chars[index + 1]
+      const previousLower =
+        previous !== undefined &&
+        previous === previous.toLowerCase() &&
+        previous !== previous.toUpperCase()
+      const nextLower =
+        next !== undefined && next === next.toLowerCase() && next !== next.toUpperCase()
+      const previousUpper =
+        previous !== undefined &&
+        previous === previous.toUpperCase() &&
+        previous !== previous.toLowerCase()
+      if (index > 0 && (previousLower || (nextLower && previousUpper))) out += '_'
+      out += char.toLowerCase()
+      continue
+    }
+    out += char
+  }
+  return out
+}
+
+/** Drop a trailing `Middleware` / `middleware` / `_middleware`, whatever the case. */
+export function stripSuffixInsensitive(name: string, suffix: string): string {
+  const lower = name.toLowerCase()
+  const suffixLower = suffix.toLowerCase()
+  if (lower.length > suffixLower.length && lower.endsWith(suffixLower)) {
+    return name.slice(0, name.length - suffix.length).replace(/[_-]+$/, '')
+  }
+  return name
+}
+
+/** Longer than this is not a name, it is a paste accident. */
+export const MAX_NAME_LENGTH = 128
+
+/**
+ * Is this a name a generator may build a path from?
+ *
+ * Refused rather than sanitised: a name with a separator in it is either a
+ * mistake or an attempt to write outside the project, and quietly rewriting it
+ * would produce a file somewhere the user did not ask for.
+ */
+export function nameProblem(name: string): string | undefined {
+  if (name.trim() === '') return 'the name is empty'
+  if (name.length > MAX_NAME_LENGTH) return `the name is longer than ${MAX_NAME_LENGTH} characters`
+  if (/[/\\]/.test(name)) return 'a name may not contain a path separator'
+  if (name.includes('..')) return 'a name may not contain ".."'
+  if (!/^[A-Za-z][A-Za-z0-9_\-:]*$/.test(name)) {
+    return 'a name starts with a letter and holds letters, digits, "_", "-" or ":"'
+  }
+  return undefined
+}

package/src/console/make/resolve.ts

@@ -0,0 +1,134 @@
+/**
+ * Finding a stub, rendering it, and knowing where it goes.
+ *
+ * A stub is addressed the way `codemods.makeUsingStub` addresses one — a
+ * package's `stubsRoot` plus a path inside it, `make/controller.stub` — so a
+ * generator and a package's `configure()` hook read the same file through the
+ * same rule. The application's own copy under `stubs/` wins over the shipped
+ * one, which is what `ream eject` is for.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { render, type StubState } from '../../stubs/template.js'
+
+/** Where an application keeps its own copies — Adonis' `stubs/` root. */
+export const PUBLISHED_ROOT = 'stubs'
+
+/** The stubs this package ships. */
+export const REAM_STUBS_ROOT = path.join(import.meta.dirname, '..', '..', '..', 'stubs')
+
+export interface RenderedStub {
+  /** Relative to the project root, as the stub's front matter declares it. */
+  path: string
+  contents: string
+  /** Did the application's own copy win? */
+  published: boolean
+}
+
+/**
+ * A stub path that could escape its root never reaches the filesystem.
+ *
+ * `eject` takes one from the command line, so this is the boundary: no
+ * absolute path, no `..`, and a `.stub` file at the end of it.
+ */
+export function isSafeStubPath(stubPath: string): boolean {
+  if (stubPath === '' || stubPath.length > 256) return false
+  if (path.isAbsolute(stubPath)) return false
+  const segments = stubPath.split(/[/\\]/)
+  if (segments.includes('..') || segments.includes('')) return false
+  return segments.every((segment) => /^[\w.-]+$/.test(segment))
+}
+
+/** Where the application's copy of `stubPath` would live. */
+export function publishedPath(stubPath: string, cwd: string): string | undefined {
+  if (!isSafeStubPath(stubPath)) return undefined
+  return path.join(cwd, PUBLISHED_ROOT, stubPath)
+}
+
+/** Read `stubPath` — the application's copy when there is one. */
+export function readStub(
+  stubsRoot: string,
+  stubPath: string,
+  cwd: string,
+): { source: string; published: boolean } {
+  const published = publishedPath(stubPath, cwd)
+  if (published !== undefined && fs.existsSync(published)) {
+    return { source: fs.readFileSync(published, 'utf8'), published: true }
+  }
+  if (!isSafeStubPath(stubPath)) {
+    throw new Error(`[make] unusable stub path: ${stubPath}`)
+  }
+  const shipped = path.join(stubsRoot, stubPath)
+  if (!fs.existsSync(shipped)) {
+    throw new Error(`[make] no stub at "${stubPath}" (looked in ${stubsRoot})`)
+  }
+  return { source: fs.readFileSync(shipped, 'utf8'), published: false }
+}
+
+/** Split `---\nto: …\n---\n<body>`; the front matter names the destination. */
+export function splitFrontMatter(template: string): { to?: string; body: string } {
+  const trimmed = template.replace(/^[\r\n]+/, '')
+  if (!trimmed.startsWith('---')) return { body: template }
+  const after = trimmed.slice(3).replace(/^\r?\n/, '')
+  const end = after.indexOf('\n---')
+  if (end === -1) {
+    throw new Error('[make] a stub opened its front matter with `---` and never closed it')
+  }
+  const block = after.slice(0, end)
+  const body = after.slice(end + 4).replace(/^\r?\n/, '')
+  let to: string | undefined
+  for (const rawLine of block.split('\n')) {
+    const line = rawLine.trim()
+    if (line === '' || line.startsWith('#')) continue
+    const at = line.indexOf(':')
+    if (at === -1) throw new Error(`[make] unreadable stub front-matter line: \`${line}\``)
+    if (line.slice(0, at).trim() === 'to') to = line.slice(at + 1).trim()
+  }
+  return to === undefined ? { body } : { to, body }
+}
+
+/**
+ * The destination a stub declares, checked.
+ *
+ * Absolute paths and `..` are refused rather than normalised: a published stub
+ * is a file in the project, and a generator is not a way to write outside it.
+ */
+function assertInsideProject(destination: string): void {
+  if (destination === '') throw new Error('[make] the stub declares an empty destination')
+  if (path.isAbsolute(destination)) {
+    throw new Error(`[make] a stub may not write to an absolute path: ${destination}`)
+  }
+  if (destination.split(/[/\\]/).includes('..')) {
+    throw new Error(`[make] a stub may not write outside the project: ${destination}`)
+  }
+}
+
+export function renderStub(
+  stubsRoot: string,
+  stubPath: string,
+  state: StubState,
+  cwd: string,
+  fallbackPath?: string,
+): RenderedStub {
+  const { source, published } = readStub(stubsRoot, stubPath, cwd)
+  const { to, body } = splitFrontMatter(source)
+  const destination = to === undefined ? fallbackPath : render(to, state)
+  if (destination === undefined) {
+    throw new Error(
+      `[make] the stub at "${stubPath}" declares no destination — add a \`to:\` front-matter line.`,
+    )
+  }
+  assertInsideProject(destination)
+  return { path: destination, contents: render(body, state), published }
+}
+
+/** `make/controller.stub` — the stub a generator of that kind reads. */
+export function stubPathFor(kind: string): string {
+  return `make/${kind}.stub`
+}
+
+/** Render one of this package's own generator stubs. */
+export function renderStubFor(kind: string, state: StubState, cwd: string): RenderedStub {
+  return renderStub(REAM_STUBS_ROOT, stubPathFor(kind), state, cwd)
+}

package/src/console/ui.ts

@@ -1,37 +1,25 @@
 /**
- * Console UI — `this.logger` and `this.prompt` on every command (Console parity).
+ * The one colour helper the Kernel's help and the prompts use.
  *
- * Kept dependency-free: the framework ships no colour or prompt library, and
- * pulling one in for the CLI surface alone is not worth the install weight.
+ * It is a thin call into `@c9up/lumen` rather than a second palette: two
+ * tables of escape codes in one package is how `[ warn ]` ends up yellow in
+ * one command and plain in another.
+ *
+ * The environment is read on EVERY call, not cached, because a command can be
+ * run in-process with the environment changed around it — which is exactly
+ * what the tests covering `FORCE_COLOR` do.
  */
 
 import { stdout } from 'node:process'
+import { ansiColors, type Colors, silentColors, supportsColor } from '@c9up/lumen'
 
-/** Colour is opt-out via NO_COLOR and skipped when piped to a file. */
-function supportsColour(stream: NodeJS.WriteStream): boolean {
-  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
-  if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '') return true
-  return Boolean(stream.isTTY)
-}
-
-const CODES = {
-  reset: '\u001B[0m',
-  dim: '\u001B[2m',
-  red: '\u001B[31m',
-  green: '\u001B[32m',
-  yellow: '\u001B[33m',
-  blue: '\u001B[34m',
-  magenta: '\u001B[35m',
-  cyan: '\u001B[36m',
-} as const
-
-export type Colour = keyof Omit<typeof CODES, 'reset'>
+export type Colour = 'dim' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan'
 
 export function colourise(
   text: string,
   colour: Colour,
   stream: NodeJS.WriteStream = stdout,
 ): string {
-  if (!supportsColour(stream)) return text
-  return `${CODES[colour]}${text}${CODES.reset}`
+  const colors: Colors = supportsColor(stream) ? ansiColors() : silentColors()
+  return colors[colour](text)
 }

package/src/dev/hmr.ts

@@ -45,6 +45,90 @@ function holder(): CounterHolder {
 export function hotReloadHappened(): void {
   const store = holder()
   store[COUNTER] = (store[COUNTER] ?? 0) + 1
+  notifyClients()
+}
+
+/**
+ * The dev clients currently listening.
+ *
+ * A `Set` and not a count: each entry is pushed to on a swap, and dropped when
+ * the tab closes. `unknown`-typed on purpose — this module must not import the
+ * HTTP layer, which imports it back.
+ */
+interface DevClient {
+  send: (event: string, data: unknown) => Promise<boolean>
+  onClose: (callback: () => void) => void
+}
+
+const clients = new Set<DevClient>()
+
+/** The event name the injected script listens for. */
+const HMR_EVENT = 'ream:hmr'
+
+/**
+ * Answer the dev client BEFORE any application middleware runs, and PUSH.
+ *
+ * Two problems, one change.
+ *
+ * It used to be an ordinary route polled once a second, per open tab, and a
+ * route runs the whole middleware stack. An application that resolves a user
+ * from a session cookie therefore ran `SELECT * FROM users` once a second for
+ * a response whose entire content is a process id and a counter, and which
+ * depends on no user, no session and no body.
+ *
+ * It is a stream now, so the cost is paid ONCE per tab instead of once a
+ * second, and a change reaches the browser immediately rather than up to a
+ * second later. Upstream gets the same thing from Vite's websocket; this needs
+ * no bundler, because the server already speaks SSE.
+ *
+ * Registered FIRST rather than merely outside the router: middleware that
+ * authenticates lives at either tier, and an application is free to put it in
+ * `server.use([...])` — many do, because it must run before routing.
+ *
+ * Development only. In production nothing injects the script and nothing
+ * registers this.
+ */
+export function hmrEndpoint(): (
+  ctx: {
+    request: { url: () => string }
+    response: { sse: () => Promise<DevClient> }
+  },
+  next: () => Promise<void>,
+) => Promise<void> {
+  return async (ctx, next) => {
+    // `url()` carries the query string; a client may append a cache-buster.
+    const path = ctx.request.url().split('?')[0]
+    if (path !== HMR_PATH) {
+      await next()
+      return
+    }
+
+    let stream: DevClient
+    try {
+      stream = await ctx.response.sse()
+    } catch {
+      // A host without the streaming NAPI — a mock server in a test, say.
+      // Losing the reload is fine; failing the request is not.
+      await next()
+      return
+    }
+
+    clients.add(stream)
+    stream.onClose(() => clients.delete(stream))
+    // Immediately, so a tab that connects after a restart compares against the
+    // CURRENT token rather than waiting for the next swap to learn anything.
+    await stream.send(HMR_EVENT, hmrToken())
+  }
+}
+
+/** Tell every open tab the token moved. */
+function notifyClients(): void {
+  const token = hmrToken()
+  for (const client of clients) {
+    // Detached: a swap must not wait on a socket, and a dead one is dropped by
+    // its own close handler.
+    void client.send(HMR_EVENT, token).catch(() => clients.delete(client))
+  }
 }
 
 /** How many hot swaps this process has seen. */
@@ -63,10 +147,15 @@ export function hmrToken(): string {
 /**
  * The script injected into HTML pages in dev.
  *
- * It reloads when the token changes, NOT when the request fails: a server that
- * is restarting is unreachable for a moment, and reloading then would only show
- * the browser's error page. It waits for an answer, and the answer carries a
- * new boot id.
+ * An `EventSource`, not a poll. The server pushes the token, so a change
+ * reaches the page immediately and an idle tab costs one open connection
+ * rather than a request per second through the whole middleware stack.
+ *
+ * It reloads when the token CHANGES, never when the connection fails: a
+ * restarting server is unreachable for a moment, and reloading then would only
+ * show the browser's error page. `EventSource` reconnects on its own, and the
+ * server greets the new connection with its token — which after a restart is a
+ * different boot id, so the reload happens then, once the server can serve it.
  */
 export function hmrClientScript(nonce?: string): string {
   // A nonce-based CSP — which the scaffold ships, via `@c9up/blackhole` —
@@ -75,9 +164,13 @@ export function hmrClientScript(nonce?: string): string {
   // are escaped because a nonce is generated, not user input, but a broken
   // attribute would silently disable the tag rather than fail loudly.
   const attribute = nonce === undefined ? '' : ` nonce="${nonce.replace(/"/g, '&quot;')}"`
-  // A failed poll RETRIES. Returning on `!r.ok` stopped the loop for good, so a
-  // page opened in the window before the endpoint is mounted — or during any
-  // blip — never reloaded again for the life of that tab, which looks exactly
-  // like the feature not working.
-  return `<script${attribute}>(()=>{let t=null;const p=${JSON.stringify(HMR_PATH)};const tick=async()=>{try{const r=await fetch(p,{cache:'no-store'});if(r.ok){const n=(await r.text()).trim();if(t===null){t=n}else if(n!==t){location.reload();return}}}catch(e){}setTimeout(tick,1000)};tick()})()</script>`
+  // `addEventListener(HMR_EVENT)`, NOT `onmessage`: the stream names its
+  // events, and `onmessage` fires only for unnamed ones — a client wired that
+  // way receives nothing at all, silently, which is a mistake this codebase
+  // has already made once with relay.
+  return `<script${attribute}>(()=>{let t=null;const s=new EventSource(${JSON.stringify(
+    HMR_PATH,
+  )});s.addEventListener(${JSON.stringify(
+    HMR_EVENT,
+  )},e=>{let n;try{n=JSON.parse(e.data)}catch(_){n=e.data}if(t===null){t=n}else if(n!==t){s.close();location.reload()}})})()</script>`
 }

package/src/dev/hotGlob.ts

@@ -7,9 +7,16 @@
  * what they need is to be right, not fast.
  *
  * The dialect is the one those files already use:
- *   *   any run of characters inside one path segment
- *   **  any number of segments, including none
- *   ?   exactly one character inside a segment
+ *   *      any run of characters inside one path segment
+ *   **     any number of segments, including none
+ *   ?      exactly one character inside a segment
+ *   {a,b}  either alternative
+ *
+ * The brace form is the one a `metaFiles` entry uses —
+ * `resources/lang/**\/*.{json,yaml,yml}` — and it has to be understood on this
+ * side too: the CLI matches the same pattern when it copies those files into
+ * the build, and a dialect that differed between the two would let an entry
+ * copy at build time and never fire in development, or the reverse.
  *
  * A leading `./` is optional, and matching is done on POSIX-shaped paths
  * relative to the project root, so a Windows checkout and a Linux one read the
@@ -42,6 +49,24 @@ export function globToRegExp(pattern: string): RegExp {
       out += '[^/]'
       continue
     }
+    if (char === '{') {
+      const close = cleaned.indexOf('}', i)
+      if (close !== -1) {
+        // Alternatives are literal text, never nested globs: that is the whole
+        // of the form these patterns use, and a recursive reading would accept
+        // shapes the CLI's matcher does not.
+        const options = cleaned
+          .slice(i + 1, close)
+          .split(',')
+          .map((option) => option.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        out += `(?:${options.join('|')})`
+        i = close
+        continue
+      }
+      // Unclosed: read literally rather than throwing. A pattern is a string in
+      // a config file, and a malformed one should match nothing, not take the
+      // dev server down at boot.
+    }
     // Everything else is literal, including the characters a regular
     // expression would otherwise read as syntax.
     out += (char ?? '').replace(/[.+^${}()|[\]\\]/g, '\\$&')