@c9up/ream 0.2.25 → 0.2.27

package/src/Codemods.ts

@@ -1,15 +1,77 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import { render as renderTemplate, type StubState } from './stubs/template.js'
+
+export type { StubState }
 
 export interface Codemods {
   addProvider(importPath: string): Promise<void>
   addMetaFile(pattern: string, reloadServer?: boolean): Promise<void>
   addEnvVars(vars: Record<string, string>): Promise<void>
   writeFile(filePath: string, content: string, options?: { force?: boolean }): Promise<void>
+  makeUsingStub(
+    stubsRoot: string,
+    stubPath: string,
+    state?: StubState,
+    options?: { force?: boolean },
+  ): Promise<GeneratedStub>
   registerCommand(importPath: string): Promise<void>
   registerMiddleware(importPath: string, options?: { tier?: 'server' | 'router' }): Promise<void>
 }
 
+/** What a stub may interpolate. Scalars only — a stub is text, not a program. */
+
+/** Where a stub landed, and what it wrote there. */
+export interface GeneratedStub {
+  /** Relative to the project root. */
+  path: string
+  contents: string
+}
+
+/**
+ * A stub, split into the destination it declares and the body it renders.
+ *
+ * The format is the one `ream-cli`'s generators already read, deliberately:
+ * two stub dialects in one framework is a worse tax than the feature is worth.
+ *
+ *     ---
+ *     to: config/visa.ts
+ *     ---
+ *     export default defineConfig({ ... })
+ *
+ * Adonis declares the same thing with `{{{ exports({ to: … }) }}}`, which is
+ * JavaScript we cannot evaluate here — the front matter is that line, written
+ * so a text substitution can read it.
+ */
+function splitFrontMatter(template: string): { to?: string; body: string } {
+  const trimmed = template.replace(/^[\uFEFF\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('[configure] stub front matter opened with `---` but never closed')
+  }
+  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 separator = line.indexOf(':')
+    if (separator === -1) {
+      throw new Error(`[configure] unreadable stub front-matter line: \`${line}\``)
+    }
+    const key = line.slice(0, separator).trim()
+    const value = line.slice(separator + 1).trim()
+    if (key === 'to') to = value
+    // Any other key is ignored rather than refused: a stub written for a
+    // later version of this loader must not break the current one.
+  }
+  return to === undefined ? { body } : { to, body }
+}
+
 type MiddlewareTier = 'server' | 'router'
 
 function isMiddlewareTier(value: unknown): value is MiddlewareTier {
@@ -70,6 +132,55 @@ export function createCodemods(options?: { force?: boolean; cwd?: string }): Cod
   const force = options?.force ?? false
   const root = path.resolve(options?.cwd ?? process.cwd())
 
+  /**
+   * The one place a file reaches the disk.
+   *
+   * Shared by `writeFile` and `makeUsingStub` rather than copied, because what
+   * it does is not writing — it is refusing to write outside the project, to
+   * follow a symlink out of it, or over something that already exists.
+   */
+  async function writeGuarded(
+    filePath: string,
+    content: string,
+    shouldOverwrite: boolean,
+  ): Promise<void> {
+    if (path.isAbsolute(filePath)) {
+      throw new Error(`[configure] Absolute paths not allowed: ${filePath}`)
+    }
+    const resolved = path.resolve(root, filePath)
+    if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+      throw new Error(`[configure] Refusing to write outside project root: ${filePath}`)
+    }
+
+    const shouldForce = shouldOverwrite
+    if (fs.existsSync(resolved) && !shouldForce) return
+
+    const dir = path.dirname(resolved)
+    fs.mkdirSync(dir, { recursive: true })
+
+    const canonRoot = fs.realpathSync(root)
+
+    if (fs.existsSync(dir)) {
+      const canonDir = fs.realpathSync(dir)
+      if (!canonDir.startsWith(canonRoot + path.sep) && canonDir !== canonRoot) {
+        throw new Error(
+          `[configure] Symlink escape detected: ${filePath} — directory resolves outside project root`,
+        )
+      }
+    }
+
+    if (fs.existsSync(resolved)) {
+      const canonFile = fs.realpathSync(resolved)
+      if (!canonFile.startsWith(canonRoot + path.sep)) {
+        throw new Error(
+          `[configure] Symlink escape detected: ${filePath} — file resolves outside project root`,
+        )
+      }
+    }
+
+    fs.writeFileSync(resolved, content)
+  }
+
   return {
     /**
      * Insert a provider import into `reamrc.ts` by string manipulation.
@@ -192,41 +303,54 @@ export function createCodemods(options?: { force?: boolean; cwd?: string }): Cod
     },
 
     async writeFile(filePath: string, content: string, opts?: { force?: boolean }): Promise<void> {
-      if (path.isAbsolute(filePath)) {
-        throw new Error(`[configure] Absolute paths not allowed: ${filePath}`)
-      }
-      const resolved = path.resolve(root, filePath)
-      if (!resolved.startsWith(root + path.sep) && resolved !== root) {
-        throw new Error(`[configure] Refusing to write outside project root: ${filePath}`)
-      }
-
-      const shouldForce = opts?.force ?? force
-      if (fs.existsSync(resolved) && !shouldForce) return
-
-      const dir = path.dirname(resolved)
-      fs.mkdirSync(dir, { recursive: true })
+      return writeGuarded(filePath, content, opts?.force ?? force)
+    },
 
-      const canonRoot = fs.realpathSync(root)
+    /**
+     * Render a stub and write it where the stub says.
+     *
+     * The application's own copy wins: a stub published to `stubs/<stubPath>`
+     * is used instead of the package's, which is what lets someone change the
+     * config a package generates without forking it. Adonis calls the same
+     * thing "searches in publishTarget first"; `ream-cli` already does it for
+     * the `make:` generators, and this is the same rule on the configure side.
+     *
+     * A package therefore names its stub after itself — `config/visa.stub`,
+     * not `config.stub` — or two packages would publish to the same path.
+     */
+    async makeUsingStub(
+      stubsRoot: string,
+      stubPath: string,
+      state: StubState = {},
+      opts?: { force?: boolean },
+    ): Promise<GeneratedStub> {
+      if (stubPath.includes('..') || path.isAbsolute(stubPath)) {
+        throw new Error(`[configure] Unsafe stub path: ${stubPath}`)
+      }
 
-      if (fs.existsSync(dir)) {
-        const canonDir = fs.realpathSync(dir)
-        if (!canonDir.startsWith(canonRoot + path.sep) && canonDir !== canonRoot) {
-          throw new Error(
-            `[configure] Symlink escape detected: ${filePath} — directory resolves outside project root`,
-          )
-        }
+      const published = path.resolve(root, 'stubs', stubPath)
+      const shipped = path.resolve(stubsRoot, stubPath)
+      const source = fs.existsSync(published) ? published : shipped
+      if (!fs.existsSync(source)) {
+        throw new Error(`[configure] Stub not found: ${stubPath} (looked in ${stubsRoot})`)
       }
 
-      if (fs.existsSync(resolved)) {
-        const canonFile = fs.realpathSync(resolved)
-        if (!canonFile.startsWith(canonRoot + path.sep)) {
-          throw new Error(
-            `[configure] Symlink escape detected: ${filePath} — file resolves outside project root`,
-          )
-        }
+      const raw = fs.readFileSync(source, 'utf8')
+      const { to, body } = splitFrontMatter(raw)
+      if (to === undefined) {
+        // Without it there is nowhere to put the file, and guessing from the
+        // stub's own name would put a package's config wherever it was named.
+        throw new Error(
+          `[configure] Stub ${stubPath} declares no destination — add a \`to:\` front matter line.`,
+        )
       }
 
-      fs.writeFileSync(resolved, content)
+      // The destination goes through the engine too: `to: config/{{ name }}.ts`
+      // is the reason a single stub can serve several outputs.
+      const destination = renderTemplate(to, state)
+      const contents = renderTemplate(body, state)
+      await writeGuarded(destination, contents, opts?.force ?? force)
+      return { path: destination, contents }
     },
 
     /**

package/src/HttpKernel.ts

@@ -41,8 +41,12 @@ export interface HttpKernelConfig {
    * handler produced. It lives here rather than in a middleware because this
    * is the one place every response passes through on its way out, whichever
    * route or error handler produced it.
+   *
+   * It is handed the whole context, not just the nonce: the debug toolbar
+   * carries the profile token inline, and that token is only on the response
+   * by the time the body is serialised.
    */
-  devReloadScript?: (nonce?: string) => string
+  devScript?: (ctx: HttpContext) => string
   routerMiddleware?: MiddlewareFunction[]
   onError?: (error: unknown, ctx: HttpContext) => void
   debug?: boolean
@@ -375,7 +379,7 @@ export function createHttpKernel(
           correlationId,
         )
       }
-      const serialized = await serializeResponse(ctx, config.devReloadScript)
+      const serialized = await serializeResponse(ctx, config.devScript)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.
       ctx.response.runFinishCallbacks()
@@ -431,7 +435,7 @@ export function createHttpKernel(
           correlationId,
         )
       }
-      const serialized = await serializeResponse(ctx, config.devReloadScript)
+      const serialized = await serializeResponse(ctx, config.devScript)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.
       ctx.response.runFinishCallbacks()
@@ -484,18 +488,18 @@ function readControllerGuardMetadata(
 
 async function serializeResponse(
   ctx: HttpContext,
-  devReloadScript?: (nonce?: string) => string,
+  devScript?: (ctx: HttpContext) => string,
 ): Promise<HttpKernelResponse> {
   // The terminal step, as AdonisJS' server calls `response.finish()`: it
   // stamps the request id and waits for a body still being produced.
   await ctx.response.finish()
   const streamId = ctx.response.getStreamId()
   const headers = ctx.response.getHeaders()
-  const body = withDevReloadScript(
+  const body = withDevScript(
     ctx.response.getBody(),
     headers,
     streamId,
-    devReloadScript === undefined ? undefined : devReloadScript(ctx.response.nonce),
+    devScript === undefined ? undefined : devScript(ctx),
   )
   return {
     status: ctx.response.getStatus(),
@@ -548,14 +552,14 @@ function reconcileRepresentation(
 }
 
 /**
- * Append the dev reload script to an HTML body.
+ * Append the development script to an HTML body.
  *
  * Only HTML, and never a stream: appending to an SSE or a download would
  * corrupt it, and a page is the only thing that can act on the script anyway.
  * Before `</body>` when there is one, so the script is inside the document
  * rather than trailing after it.
  */
-function withDevReloadScript(
+function withDevScript(
   body: string,
   headers: Record<string, string>,
   streamId: string | undefined,

package/src/Ignitor.ts

@@ -18,6 +18,8 @@ import type { Console } from './console/Console.js'
 import type { CommandLoader, Kernel as ConsoleKernelInstance } from './console/Kernel.js'
 import { type CommandClass, isCommandClass } from './console/types.js'
 import { hmrClientScript, hmrEndpoint } from './dev/hmr.js'
+import { devServerUrl, inDevServer, printReadyBanner } from './dev/readyBanner.js'
+import { installShortcuts } from './dev/shortcuts.js'
 import type { DirectoriesNode } from './directories.js'
 import type { ErrorEvent } from './ErrorBoundary.js'
 import { ErrorBoundary } from './ErrorBoundary.js'
@@ -38,6 +40,14 @@ import { MiddlewareRegistry } from './middleware/Pipeline.js'
 import { MigrationRegistry } from './migrations/MigrationRegistry.js'
 import type { AppContext, ProviderContract } from './Provider.js'
 import { callProviderPhase } from './Provider.js'
+import {
+  createProfiler,
+  PROFILER_TOKEN_HEADER,
+  type Profiler,
+  profileRequest,
+  profilerEndpoint,
+  toolbarScript,
+} from './profiler/index.js'
 import { Router } from './router/Router.js'
 import { CookieSigner } from './security/CookieSigner.js'
 import { SignedUrl } from './security/SignedUrl.js'
@@ -345,6 +355,13 @@ export class Ignitor {
   #hotReloadCleanup?: () => void
   #shutdownHandle?: ShutdownHandle
   #host?: string
+  /**
+   * Stops listening for the dev-server keys. Only ever set under `ream dev`.
+   *
+   * Removed on shutdown, or a terminal left in raw mode would swallow the
+   * next command you type after the server exits.
+   */
+  #removeShortcuts?: () => void
   #console?: Console
 
   // Inline configuration (for simple use or testing)
@@ -812,6 +829,10 @@ export class Ignitor {
     // Boot the Server (resolves lazy error handler etc.)
     await this.#server.boot()
 
+    // Before the kernel: the kernel's server middleware and its dev script
+    // both read it.
+    await this.#startProfiler()
+
     // Start HTTP server if this process serves one
     if (this.#servesHttp() && this.#config.serverFactory) {
       // Build the HttpKernel with server middleware + router middleware.
@@ -830,7 +851,7 @@ export class Ignitor {
           ...this.#server.getServerMiddleware(),
         ],
         routerMiddleware: this.#router.getRouterMiddleware(),
-        devReloadScript: this.#devReloadScript(),
+        devScript: this.#devScript(),
         onError: (error, ctx) => {
           this.#errorBoundary.serviceError('HttpKernel', error, ctx.id)
         },
@@ -992,6 +1013,23 @@ export class Ignitor {
     // balancer at a process that cannot answer.
     this.#app.markReady()
     this.#phase = 'ready'
+
+    // The address, once there is one to print. Upstream's dev server prints
+    // this sticker when the child reports ready; here the child prints it,
+    // because a port found by scanning past a taken 3000 is known only to the
+    // process that bound it.
+    if (inDevServer() && this.#host !== undefined && this.#_httpServer !== undefined) {
+      const port = await this.#_httpServer.port()
+      printReadyBanner({
+        host: this.#host,
+        port,
+        mode: 'HMR',
+        bootMs: performance.now(),
+      })
+      // The keys upstream's dev server answers to. Installed here for the same
+      // reason the sticker is printed here: `o` needs the address.
+      this.#removeShortcuts = installShortcuts({ url: devServerUrl(this.#host, port) })
+    }
   }
 
   /**
@@ -1154,6 +1192,11 @@ export class Ignitor {
   async stop(): Promise<void> {
     const errors: unknown[] = []
 
+    // First: a terminal left in raw mode swallows the next command you type
+    // after the server exits, and that outlives the process.
+    this.#removeShortcuts?.()
+    this.#removeShortcuts = undefined
+
     // Release the consoleApp locator first — ownership-guarded, so a second Ignitor
     // having rebound it is left alone.
     if (this.#console !== undefined) {
@@ -1296,7 +1339,7 @@ export class Ignitor {
         this.#server.getErrorHandler() ?? new ExceptionHandler(!this.#app.inProduction),
       serverMiddleware: this.#server.getServerMiddleware(),
       routerMiddleware: this.#router.getRouterMiddleware(),
-      devReloadScript: this.#devReloadScript(),
+      devScript: this.#devScript(),
     })
     return this.#kernel
   }
@@ -1308,29 +1351,67 @@ export class Ignitor {
   }
 
   /**
-   * The reload script, in development only.
+   * What development appends to an HTML page: the reload client, and the
+   * debug toolbar once a profile exists for the request.
    *
    * Gated on the environment rather than on `hot-hook` being present: the
-   * script is just as useful without it, since a restart is exactly what it
-   * detects. In production it is `undefined` and the response is untouched.
+   * reload script is just as useful without it, since a restart is exactly
+   * what it detects. In production this is `undefined` and the response is
+   * untouched.
+   *
+   * The token is read back off the response rather than passed along a side
+   * channel — the profiling middleware has already stamped it there, which is
+   * also where a client outside the page reads it (Symfony's `X-Debug-Token`).
    */
-  #devReloadScript(): ((nonce?: string) => string) | undefined {
-    return this.isDevMode() ? hmrClientScript : undefined
+  #devScript(): ((ctx: HttpContext) => string) | undefined {
+    if (!this.isDevMode()) return undefined
+    return (ctx) => {
+      const nonce = ctx.response.nonce
+      const reload = hmrClientScript(nonce)
+      const token = ctx.response.getHeader(PROFILER_TOKEN_HEADER)
+      return token === undefined ? reload : reload + toolbarScript(token, nonce)
+    }
+  }
+
+  /**
+   * The profiler, in development only.
+   *
+   * It needs the application's emitter — `db:query` is where the database
+   * panel comes from — so it is built here rather than in a field initialiser,
+   * once the container has one. An application without an event bus still gets
+   * every other panel.
+   */
+  async #startProfiler(): Promise<void> {
+    if (!this.isDevMode() || this.#profiler !== undefined) return
+    const events = this.#app.container.has('events')
+      ? await this.#app.container.resolve<Emitter>('events')
+      : { on: () => undefined }
+    this.#profiler = createProfiler(events)
   }
 
+  #profiler?: Profiler
+
   /**
    * The server middleware the framework itself contributes, ahead of the
    * application's.
    *
-   * Only the hot-reload token, and only in development. It answers first
-   * because the poll arrives once a second per open tab and its content
-   * depends on nothing — no user, no session, no body. Behind an application's
-   * middleware it paid for the whole stack each time, which for anything that
-   * resolves a user from a cookie meant a `SELECT` per second for a string
-   * holding a process id and a counter.
+   * Development only, and the order is the point:
+   *
+   *  1. the profiler's own pages, which must not appear in their own history;
+   *  2. the hot-reload stream, which answers first because it arrives once a
+   *     second per open tab and its content depends on nothing — no user, no
+   *     session, no body. Behind an application's middleware it paid for the
+   *     whole stack each time, which for anything that resolves a user from a
+   *     cookie meant a `SELECT` per second for a string holding a process id
+   *     and a counter. It is also open for as long as the tab is, so profiling
+   *     it would leave one profile unfinished forever;
+   *  3. everything else, wrapped in a profile.
    */
   #frameworkServerMiddleware(): MiddlewareFunction[] {
-    return this.isDevMode() ? [hmrEndpoint()] : []
+    if (!this.isDevMode()) return []
+    const profiler = this.#profiler
+    if (profiler === undefined) return [hmrEndpoint()]
+    return [profilerEndpoint(profiler), hmrEndpoint(), profileRequest(profiler)]
   }
 
   getPhase(): string {

package/src/console/Kernel.ts

@@ -18,6 +18,7 @@ import { buildFlag } from './decorators.js'
 import { ExceptionHandler } from './ExceptionHandler.js'
 import HelpCommand from './HelpCommand.js'
 import ListCommand from './ListCommand.js'
+import { MAKE_COMMANDS } from './make/commands.js'
 import { assignParsedValues, parseArgv, validateParsed } from './parser.js'
 import { Prompt } from './prompts.js'
 import { commandExec } from './tracing.js'
@@ -229,6 +230,14 @@ export class Kernel {
     this.register(HelpCommand)
     this.#defaults.add(HelpCommand.commandName)
 
+    // The generators. Registered as defaults, so an application that defines
+    // its own `make:controller` replaces this one rather than colliding with
+    // it — the same standing an app has over `list` and `help`.
+    for (const command of MAKE_COMMANDS) {
+      this.register(command)
+      this.#defaults.add(command.commandName)
+    }
+
     // Console's `--help`, a global flag whose listener runs the help command.
     this.defineFlag('help', {
       type: 'boolean',
@@ -460,7 +469,18 @@ export class Kernel {
       for (const metadata of await loader.getMetaData()) {
         // Metadata only — the class is imported by `find()`, when someone asks
         // for the command. `loading` / `loaded` belong there too.
-        if (!this.#commands.has(metadata.commandName)) {
+        //
+        // A name the kernel registered ITSELF gives way: `list`, `help` and
+        // the generators are defaults, and an application that ships its own
+        // `make:controller` must get it. Without this the application declared
+        // a command that silently never ran — the same rule `register()`
+        // applies, applied on the path an application actually uses.
+        const isDefault = this.#defaults.has(metadata.commandName)
+        if (!this.#commands.has(metadata.commandName) || isDefault) {
+          if (isDefault) {
+            this.#commands.delete(metadata.commandName)
+            this.#defaults.delete(metadata.commandName)
+          }
           this.#pending.set(metadata.commandName, { metadata, loader })
         }
         // The metadata is what a manifest-style loader publishes; its aliases