@c9up/ream 0.2.25 → 0.2.27

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/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`)