@c9up/ream 0.2.26 → 0.2.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",

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,10 +40,18 @@ 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'
-import { Server } from './server/Server.js'
+import { type GrpcHandler, Server } from './server/Server.js'
 import { clearApp, setApp } from './services/app.js'
 import { clearEncryption, setEncryption } from './services/encryption.js'
 import { clearLogger, setLogger } from './services/logger.js'
@@ -258,6 +268,8 @@ export function defineConfig(config: ReamrcConfig): ReamrcConfig {
 /** Minimal interface for the HTTP server (NAPI or mock). */
 export interface HyperServerLike {
   onRequest(callback: (request: HttpKernelRequest) => Promise<HttpKernelResponse>): void
+  /** Optional — present on the real `HyperServer`; required once `server.grpc()` is used. */
+  onGrpc?(callback: GrpcHandler): void
   /**
    * Optional — present on the real `HyperServer` (Rust-backed), absent on
    * trivial test mocks. Ignitor only calls it when a shield config is set.
@@ -345,6 +357,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 +831,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 +853,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)
         },
@@ -882,6 +905,17 @@ export class Ignitor {
         this.#config.host ?? process.env.HOST ?? (this.#app.inProduction ? '0.0.0.0' : 'localhost')
       this.#_httpServer = this.#config.serverFactory(availablePort, this.#host)
       this.#_httpServer.onRequest(kernel)
+      const grpc = this.#server.getGrpcHandler()
+      if (grpc) {
+        if (typeof this.#_httpServer.onGrpc !== 'function') {
+          throw new ReamError(
+            'E_IGNITOR_GRPC_UNSUPPORTED',
+            'A gRPC handler is registered, but this server cannot serve gRPC.',
+            { hint: 'Use the native HyperServer, or a test server that implements onGrpc().' },
+          )
+        }
+        this.#_httpServer.onGrpc(grpc)
+      }
       // Pre-resolve client IPs in Rust from the trusted-proxy CIDRs before
       // listen. Security filtering itself lives in @c9up/blackhole.
       const trustedProxies = this.#server.getTrustedProxies()
@@ -992,6 +1026,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 +1205,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 +1352,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 +1364,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/prompts.ts

@@ -12,6 +12,7 @@
 import { stdin, stdout } from 'node:process'
 import { clearLine, createInterface, cursorTo } from 'node:readline'
 import { ReamError } from '../errors/ReamError.js'
+import { runSelection } from './selection.js'
 import { colourise } from './ui.js'
 
 /** A selectable option — a bare string, or a value with its display text. */
@@ -246,31 +247,18 @@ export class Prompt {
       return this.#applyResult(picked[0], options)
     }
 
-    const limit = options.limit ?? 10
-    for (;;) {
-      const typed = await this.readLine(this.#label(message, options, '(type to filter)'))
-      const matches = choices.filter((choice) =>
-        nameOf(choice).toLowerCase().includes(typed.toLowerCase()),
-      )
-
-      if (matches.length === 0) {
-        stdout.write(`${colourise('No match.', 'yellow')}\n`)
-        continue
-      }
-
-      const first = matches[0]
-      if (matches.length === 1 && first !== undefined) {
-        return this.#finish(nameOf(first), options)
-      }
-
-      const picked = await this.#select(
-        message,
-        matches.slice(0, limit),
-        { ...options, name: undefined },
-        false,
-      )
-      return picked[0]
-    }
+    // One list that narrows as you type, rather than a filter question
+    // followed by a list: upstream's autocomplete is a single prompt, and
+    // answering twice for one value is a different thing wearing its name.
+    const picked = await this.#select(
+      message,
+      choices,
+      { ...options, name: undefined },
+      false,
+      true,
+      options.limit ?? 10,
+    )
+    return picked[0]
   }
 
   // ─── internals ──────────────────────────────────────────────
@@ -299,6 +287,8 @@ export class Prompt {
     choices: readonly PromptChoice[],
     options: SelectPromptOptions | MultiplePromptOptions,
     many: boolean,
+    filter?: boolean,
+    limit?: number,
   ): Promise<unknown[]> {
     if (choices.length === 0) {
       throw new ReamError('E_CONSOLE_EMPTY_CHOICES', `"${message}" was asked with no options.`)
@@ -313,50 +303,41 @@ export class Prompt {
       return many ? picked : picked.map((value) => this.#applyResult(value, options))
     }
 
-    const defaultLabel =
-      options.default === undefined
-        ? undefined
-        : [options.default]
-            .flat()
-            .map((index) => {
-              const choice = choices[index]
-              return choice === undefined ? String(index) : displayOf(choice)
-            })
-            .join(', ')
-
+    // Arrow keys, as upstream's prompts navigate. The list redraws in place
+    // until the user answers; a cancel is no answer, not an empty one.
     for (;;) {
-      stdout.write(`${this.#label(message, { ...options, default: defaultLabel }).trimEnd()}\n`)
-      choices.forEach((choice, index) => {
-        const hint = typeof choice === 'string' ? undefined : choice.hint
-        stdout.write(
-          `  ${colourise(String(index + 1), 'cyan')}) ${displayOf(choice)}` +
-            `${hint === undefined ? '' : colourise(` — ${hint}`, 'dim')}\n`,
-        )
+      const outcome = await runSelection({
+        title: this.#label(message, { ...options, default: undefined }).trimEnd(),
+        items: choices.map((choice) => {
+          const hint = typeof choice === 'string' ? undefined : choice.hint
+          return hint === undefined
+            ? { label: displayOf(choice) }
+            : { label: displayOf(choice), hint }
+        }),
+        many,
+        ...(options.default === undefined
+          ? {}
+          : {
+              selected: [options.default]
+                .flat()
+                .filter(
+                  (index): index is number =>
+                    Number.isInteger(index) && index >= 0 && index < choices.length,
+                ),
+            }),
+        ...(filter === true ? { filter: true } : {}),
+        ...(limit === undefined ? {} : { limit }),
       })
 
-      const answer = await this.readLine(
-        many ? `Select (e.g. 1,3) from 1-${choices.length}: ` : `Select (1-${choices.length}): `,
-      )
-
-      // An empty answer takes the default — which for a selection prompt is an
-      // index, as Adonis spells it. Without this the default was shown in the
-      // label and then rejected as an invalid selection.
-      const indexes =
-        answer === '' && options.default !== undefined
-          ? [options.default]
-              .flat()
-              .filter((index) => Number.isInteger(index) && index >= 0 && index < choices.length)
-          : answer
-              .split(',')
-              .map((part) => Number(part.trim()) - 1)
-              .filter((index) => Number.isInteger(index) && index >= 0 && index < choices.length)
-
-      if (indexes.length === 0 || (!many && indexes.length !== 1)) {
-        stdout.write(`${colourise('Invalid selection.', 'yellow')}\n`)
-        continue
+      if (outcome.kind === 'cancelled') {
+        throw new ReamError('E_CONSOLE_PROMPT_CANCELLED', `"${message}" was cancelled.`, {
+          hint: 'Answer the prompt, or pass the value as a flag.',
+        })
       }
 
-      const picked = indexes.map((index) => nameOf(choices[index] as PromptChoice))
+      // A multiple with nothing ticked is an answer of none, which is only
+      // valid if the command says so — `validate` is where that is decided.
+      const picked = outcome.indexes.map((index) => nameOf(choices[index] as PromptChoice))
       const problem = await this.#selectionProblem(picked, options, many)
       if (problem !== undefined) {
         stdout.write(`${colourise(problem, 'yellow')}\n`)