@c9up/ream 0.2.24 → 0.2.26

package/dist/stubs/template.js

@@ -0,0 +1,209 @@
+/**
+ * The stub template engine.
+ *
+ * A port of the one upstream uses (tempura), grammar for grammar: comments,
+ * declared props, inline variables, conditionals, loops, custom blocks, and
+ * the two interpolation forms. A template is compiled into a JavaScript
+ * function once and then called — the same design, for the same reason: a
+ * tree-walking interpreter re-reads the template on every render, and a stub
+ * is rendered in a loop by the generators.
+ *
+ *     {{! a comment }}
+ *     {{#expect name, entity }}
+ *     {{#var plural = name + 's' }}
+ *     {{#if entity.isModel }}…{{#elif entity.isView }}…{{#else}}…{{/if}}
+ *     {{#each items as item, index }}…{{/each}}
+ *     {{ name }}      the value
+ *     {{{ name }}}    the value, unescaped
+ *
+ * NAMED DEVIATION — upstream escapes HTML in `{{ }}` and leaves `{{{ }}}`
+ * raw, because its templates are web pages. Ours are SOURCE FILES: escaping
+ * `"` into `"` there produces code that does not parse, and the mistake
+ * is silent. So `{{ }}` does not escape by default, `{{{ }}}` is accepted as
+ * the same thing (a stub written for upstream keeps working), and an `escape`
+ * option turns it back on for anyone templating markup.
+ *
+ * `new Function` compiles the result. That is how upstream does it too, and
+ * the trust boundary is the same: a stub ships inside a package whose
+ * `configure` hook is already executing.
+ */
+/** Raised when a template cannot be read, naming what is wrong with it. */
+export class StubSyntaxError extends Error {
+    code = 'E_REAM_STUB_SYNTAX';
+    constructor(message) {
+        super(message);
+        this.name = 'StubSyntaxError';
+    }
+}
+/** HTML escaping, for a stub that does template markup. */
+export function escapeHtml(value) {
+    const text = value === null || value === undefined ? '' : String(value);
+    return text.replace(/[&"<>]/g, (char) => {
+        if (char === '&')
+            return '&amp;';
+        if (char === '"')
+            return '&quot;';
+        if (char === '<')
+            return '&lt;';
+        return '&gt;';
+    });
+}
+/** The default: a source file wants its quotes and its angle brackets back. */
+function asIs(value) {
+    return value === null || value === undefined ? '' : String(value);
+}
+const CURLY = /{{{?\s*([\s\S]*?)\s*}}}?/g;
+const BLOCK = /^#\s*(\w[\w\d]*)\s*([\s\S]*)/;
+const ARGS = /([a-zA-Z$_][^\s=]*)\s*=\s*((["`'])(?:(?=(\\?))\4.)*?\3|{[^}]*}|\[[^\]]*]|\S+)/g;
+/**
+ * Compile a template into the body of a function.
+ *
+ * Kept separate from `compile` so a test can read what a template became —
+ * the generated source is the only place a subtle mistake shows itself.
+ */
+export function generate(input, options = {}) {
+    const blocks = options.blocks ?? {};
+    const declared = new Set(options.props ?? []);
+    const stack = [];
+    let body = '';
+    let literal = '';
+    let last = 0;
+    CURLY.lastIndex = 0;
+    /** Flush the literal text collected since the last tag. */
+    const flush = () => {
+        if (literal.length > 0) {
+            body += `${body ? 'x+=' : '='}\`${literal}\`;`;
+        }
+        else if (body.length === 0) {
+            body = '="";';
+        }
+        literal = '';
+    };
+    let match = CURLY.exec(input);
+    while (match !== null) {
+        literal += escapeForTemplate(input.slice(last, match.index));
+        last = match.index + match[0].length;
+        const inner = (match[1] ?? '').trim();
+        const first = inner.charAt(0);
+        if (first === '!') {
+            // A comment. It leaves no trace in the output.
+        }
+        else if (first === '#') {
+            flush();
+            const parsed = BLOCK.exec(inner);
+            if (parsed === null) {
+                throw new StubSyntaxError(`Unreadable block: {{${inner}}}`);
+            }
+            const action = parsed[1] ?? '';
+            const rest = (parsed[2] ?? '').trim();
+            body += openBlock(action, rest, stack, declared, blocks);
+        }
+        else if (first === '/') {
+            const closing = inner.slice(1).trim();
+            const opened = stack.pop();
+            flush();
+            if (opened === undefined) {
+                throw new StubSyntaxError(`Closed "${closing}" with nothing open.`);
+            }
+            if (opened !== closing) {
+                throw new StubSyntaxError(`Expected to close "${opened}"; closed "${closing}" instead.`);
+            }
+            body += '}';
+        }
+        else {
+            // Both forms interpolate the same way — see the header.
+            literal += `\${$$e(${inner})}`;
+        }
+        match = CURLY.exec(input);
+    }
+    if (stack.length > 0) {
+        throw new StubSyntaxError(`Unterminated "${stack.pop()}" block.`);
+    }
+    if (last < input.length) {
+        literal += escapeForTemplate(input.slice(last));
+    }
+    flush();
+    const bindings = declared.size > 0 ? `{${[...declared].join()}}=$$s,x` : ' x';
+    return `var${bindings}${body}return x`;
+}
+function openBlock(action, rest, stack, declared, blocks) {
+    if (action === 'expect') {
+        // Names the template reads. Declaring them is what lets an unknown one
+        // fail as `x is not defined` rather than as `undefined` in the output.
+        for (const key of rest.split(/[\n\r\s\t]*,[\n\r\s\t]*/g)) {
+            if (key !== '')
+                declared.add(key);
+        }
+        return '';
+    }
+    if (action === 'var') {
+        const at = rest.indexOf('=');
+        if (at === -1) {
+            throw new StubSyntaxError(`{{#var}} needs an assignment: {{#var ${rest}}}`);
+        }
+        const name = rest.slice(0, at).trim();
+        const value = rest
+            .slice(at + 1)
+            .trim()
+            .replace(/;$/, '');
+        return `var ${name}=${value};`;
+    }
+    if (action === 'each') {
+        stack.push(action);
+        const at = rest.indexOf(' as ');
+        if (at === -1) {
+            return `for(var i=0,$$a=${rest};i<$$a.length;i++){`;
+        }
+        const list = rest.slice(0, at).trim();
+        const [item = 'item', index = 'i'] = rest
+            .slice(at + 4)
+            .trim()
+            .replace(/[()\s]/g, '')
+            .split(',');
+        return `for(var ${index}=0,${item},$$a=${list};${index}<$$a.length;${index}++){${item}=$$a[${index}];`;
+    }
+    if (action === 'if') {
+        stack.push(action);
+        return `if(${rest}){`;
+    }
+    if (action === 'elif')
+        return `}else if(${rest}){`;
+    if (action === 'else')
+        return '}else{';
+    if (action in blocks) {
+        // `{{#note tone="warn" }}` — the arguments become one object.
+        const args = [];
+        let found = ARGS.exec(rest);
+        while (found !== null) {
+            args.push(`${found[1]}:${found[2]}`);
+            found = ARGS.exec(rest);
+        }
+        ARGS.lastIndex = 0;
+        return `x+=$$b.${action}(${args.length > 0 ? `{${args.join()}}` : '{}'});`;
+    }
+    throw new StubSyntaxError(`Unknown "${action}" block. Known: expect, var, if, elif, else, each${Object.keys(blocks).length > 0 ? `, ${Object.keys(blocks).join(', ')}` : ''}.`);
+}
+/** Protect the literal text from the template literal it is about to live in. */
+function escapeForTemplate(text) {
+    return text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+/** Compile a template into a render function. */
+export function compile(input, options = {}) {
+    const source = generate(input, options);
+    let render;
+    try {
+        // eslint-disable-next-line no-new-func -- the whole point of a compiler
+        render = new Function('$$e', '$$b', '$$s', source);
+    }
+    catch (error) {
+        throw new StubSyntaxError(`This stub does not compile: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const escaper = options.escape ?? asIs;
+    const blocks = options.blocks ?? {};
+    return (state) => render(escaper, blocks, state);
+}
+/** Compile and render in one go. */
+export function render(input, state = {}, options = {}) {
+    return compile(input, { props: Object.keys(state), ...options })(state);
+}
+//# sourceMappingURL=template.js.map

package/dist/stubs/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/stubs/template.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -111,6 +111,10 @@
       "types": "./dist/helpers/fs.d.ts",
       "import": "./dist/helpers/fs.js"
     },
+    "./stubs": {
+      "types": "./dist/stubs/index.d.ts",
+      "import": "./dist/stubs/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/TestClient.d.ts",
       "import": "./dist/testing/TestClient.js"
@@ -216,6 +220,7 @@
     "LICENSE",
     "README.md",
     "dist",
+    "stubs",
     "index.*.node",
     "scheduler.*.node",
     "events.*.node",
@@ -228,6 +233,7 @@
     "tsconfig.client.json"
   ],
   "dependencies": {
+    "@c9up/lumen": "^0.1.0",
     "file-type": "^22.0.2",
     "reflect-metadata": "^0.2.2"
   },

package/src/Codemods.ts

@@ -1,14 +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 {
@@ -69,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.
@@ -120,6 +232,58 @@ export function createCodemods(options?: { force?: boolean; cwd?: string }): Cod
       fs.writeFileSync(rcPath, content)
     },
 
+    /**
+     * Record a non-module file the application owns.
+     *
+     * A package calls this from `configure()` so its files reach the build:
+     * `addMetaFile('resources/lang/**\/*.json', false)`. The second argument
+     * is DELIBERATELY explicit at every call site — whether an edit costs a
+     * development restart is the decision the entry exists to record.
+     *
+     * Same regex codemod as `addProvider`, and the same limits: a `metaFiles`
+     * assembled by a spread or extracted into a `const` above the config is not
+     * rewritten. The block is created when absent, which `addProvider` cannot
+     * do — `providers` is always there, `metaFiles` usually is not.
+     */
+    async addMetaFile(pattern: string, reloadServer = false): Promise<void> {
+      const rcPath = path.join(root, 'reamrc.ts')
+      if (!fs.existsSync(rcPath)) {
+        throw new Error(
+          `[configure] reamrc.ts not found — cannot register meta file ${pattern}. Run 'ream new' first.`,
+        )
+      }
+      assertCanonicallyInside(root, rcPath, 'reamrc.ts')
+
+      let content = fs.readFileSync(rcPath, 'utf8')
+      // Dedup on the PATTERN alone: the same glob registered twice with
+      // different flags is a contradiction, and the first one wins rather than
+      // both being written.
+      if (content.includes(`'${pattern}'`) || content.includes(`"${pattern}"`)) return
+
+      const eol = detectLineEnding(content)
+      const entry = `    { pattern: '${pattern}', reloadServer: ${reloadServer} },`
+
+      const existing = /metaFiles\s*:\s*(?:\/\*[\s\S]*?\*\/\s*)?\[/.exec(content)
+      if (existing !== null) {
+        const insertAt = existing.index + existing[0].length
+        content = `${content.slice(0, insertAt)}${eol}${entry}${content.slice(insertAt)}`
+        fs.writeFileSync(rcPath, content)
+        return
+      }
+
+      // No block yet — open one beside `providers`, which every rc file has.
+      const providers = /providers\s*:\s*(?:\/\*[\s\S]*?\*\/\s*)?\[/.exec(content)
+      if (providers === null) {
+        throw new Error(
+          `[configure] Could not find 'providers: [' in reamrc.ts — meta file ${pattern} not added. Check your reamrc.ts format.`,
+        )
+      }
+      const blockAt = providers.index
+      const block = `metaFiles: [${eol}${entry}${eol}  ],${eol}  `
+      content = `${content.slice(0, blockAt)}${block}${content.slice(blockAt)}`
+      fs.writeFileSync(rcPath, content)
+    },
+
     async addEnvVars(vars: Record<string, string>): Promise<void> {
       const envPath = path.join(root, '.env')
       // A symlinked .env must not redirect the write outside the root.
@@ -139,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/Ignitor.ts

@@ -17,7 +17,7 @@ import { Application } from './Application.js'
 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 { HMR_PATH, hmrClientScript, hmrToken } from './dev/hmr.js'
+import { hmrClientScript, hmrEndpoint } from './dev/hmr.js'
 import type { DirectoriesNode } from './directories.js'
 import type { ErrorEvent } from './ErrorBoundary.js'
 import { ErrorBoundary } from './ErrorBoundary.js'
@@ -137,6 +137,35 @@ export interface ReamrcConfig {
    * `defineConfig`, which is a strange way to learn that the option exists.
    */
   assets?: AssetsConfig
+  /**
+   * Files that are not modules but belong to the application.
+   *
+   * Translations, view templates, a mail signature: the build has no reason to
+   * know about them, and without being told it ships a `dist/` that boots and
+   * then cannot find them. Every pattern here is copied into the build output,
+   * keeping its path relative to the project root.
+   *
+   * `reloadServer` decides what a change does in DEVELOPMENT, and the default
+   * is the interesting half. Upstream registers translations with `false` —
+   * the files are watched so the build copies them, and an edit does NOT
+   * restart the server. A package that genuinely needs a restart asks for one
+   * by passing `true`.
+   */
+  metaFiles?: MetaFileConfig[]
+}
+
+/**
+ * One `metaFiles` entry.
+ *
+ * `reloadServer` is required rather than defaulted: whether an edit costs a
+ * restart is the whole decision this entry exists to record, and a default
+ * would let it be made by accident.
+ */
+export interface MetaFileConfig {
+  /** Glob, relative to the project root — `resources/lang/**\/*.json`. */
+  pattern: string
+  /** Restart the development server when a matching file changes. */
+  reloadServer: boolean
 }
 
 /** One test suite, as declared in the rc file (AdonisJS `tests.suites[]`). */
@@ -709,7 +738,6 @@ export class Ignitor {
     // anything. Registered in `ready()` it came up after the server was already
     // serving, so a page loaded in that window polled a route that did not
     // exist yet.
-    this.#registerDevReloadRoute()
 
     // Providers start BEFORE the preload files, matching upstream's warm-up
     // order (`providers.start()` → `starting` hooks → preloads). A preload is
@@ -797,7 +825,10 @@ export class Ignitor {
         container: this.#app.container,
         exceptionHandler:
           this.#server.getErrorHandler() ?? new ExceptionHandler(!this.#app.inProduction),
-        serverMiddleware: this.#server.getServerMiddleware(),
+        serverMiddleware: [
+          ...this.#frameworkServerMiddleware(),
+          ...this.#server.getServerMiddleware(),
+        ],
         routerMiddleware: this.#router.getRouterMiddleware(),
         devReloadScript: this.#devReloadScript(),
         onError: (error, ctx) => {
@@ -1288,19 +1319,18 @@ export class Ignitor {
   }
 
   /**
-   * Serve the token the injected script polls.
+   * The server middleware the framework itself contributes, ahead of the
+   * application's.
    *
-   * Registered on the router in development, next to the application's own
-   * routes, so it goes through the same server as everything else. Plain text
-   * and uncached: it is read once a second and its whole content is the answer.
+   * 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.
    */
-  #registerDevReloadRoute(): void {
-    if (!this.isDevMode()) return
-    this.#router.get(HMR_PATH, ({ response }) => {
-      response.header('cache-control', 'no-store')
-      response.header('content-type', 'text/plain; charset=utf-8')
-      response.send(hmrToken())
-    })
+  #frameworkServerMiddleware(): MiddlewareFunction[] {
+    return this.isDevMode() ? [hmrEndpoint()] : []
   }
 
   getPhase(): string {