@c9up/ream 0.2.25 → 0.2.27

package/src/console/make/commands.ts

@@ -0,0 +1,270 @@
+/**
+ * The `make:` commands.
+ *
+ * They used to live in the `ream` binary, which meant Rust had to render their
+ * stubs — and rendering a stub means evaluating `{{#if resourceful}}`, which is
+ * JavaScript. Two renderers is two behaviours waiting to drift, so the
+ * generators moved to where the engine already is, the way `make:migration`
+ * moved to atlas.
+ *
+ * One class per command, built from the generator table: Adonis ships a class
+ * per command too, and the table is what keeps ten of them from being ten
+ * copies. `--force` and the skip-rather-than-clobber rule are Adonis'.
+ * `--dry-run` and `--json` are ours, and they are why `@c9up/ream-mcp` can
+ * show a plan before anything is written.
+ */
+
+import { BaseCommand } from '../BaseCommand.js'
+import { args, flags } from '../decorators.js'
+import type { CommandClass } from '../types.js'
+import Eject from './eject.js'
+import { flush, outcomePayload, type PlannedFile, plannedFile } from './flush.js'
+import { GENERATORS, type Generator, generatorFor } from './generators.js'
+import { nameProblem } from './naming.js'
+import { renderStubFor } from './resolve.js'
+
+/** A generator's output, or the message explaining why there is none. */
+type Prepared = { file: PlannedFile; published: boolean } | { error: string }
+
+/**
+ * Validate the names and render the stub. Shared by the single-kind commands
+ * and by `make:module`, so all four files are checked before the first write.
+ */
+function prepare(
+  generator: Generator,
+  module: string | undefined,
+  name: string,
+  extra: { stack?: string; event?: string },
+  cwd: string,
+): Prepared {
+  for (const [label, value] of [
+    ['module', module],
+    ['name', name],
+  ] as const) {
+    if (value === undefined) continue
+    const problem = nameProblem(value)
+    if (problem !== undefined) return { error: `${label} "${value}": ${problem}` }
+  }
+
+  const state = generator.state(name, {
+    ...(module === undefined ? {} : { module }),
+    ...(extra.stack === undefined ? {} : { stack: extra.stack }),
+    ...(extra.event === undefined ? {} : { event: extra.event }),
+  })
+
+  try {
+    const rendered = renderStubFor(generator.kind, state, cwd)
+    return {
+      file: plannedFile(rendered.path, rendered.contents, cwd),
+      published: rendered.published,
+    }
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/**
+ * Write the plan and report it — as JSON when asked, as Adonis' action lines
+ * otherwise. `--json` prints nothing else: its whole contract is that the last
+ * line of stdout is the payload, and a stray warning above it is how that
+ * breaks.
+ */
+function report(
+  command: BaseCommand,
+  entries: readonly PlannedFile[],
+  warnings: readonly string[],
+  options: { cwd: string; dryRun: boolean; force: boolean; json: boolean },
+): void {
+  const outcome = flush(entries, warnings, options)
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(outcomePayload(outcome))}\n`)
+    return
+  }
+
+  if (outcome.status === 'planned') {
+    for (const file of outcome.files) {
+      // The path AND the contents: a dry run that showed only the path would
+      // not answer the question it is asked.
+      command.logger.info(`${file.path}${file.exists ? ' (exists)' : ''} — dry run`)
+      command.logger.log(file.content)
+    }
+  } else {
+    for (const file of [...outcome.createdFiles, ...outcome.modifiedFiles]) {
+      command.logger.action(`create ${file}`).succeeded()
+    }
+    for (const file of outcome.skippedFiles) {
+      command.logger.action(`create ${file}`).skipped('file already exists, use --force')
+    }
+  }
+
+  for (const warning of warnings) command.logger.warning(warning)
+}
+
+/** Build the command class for one generator. */
+function makeCommand(generator: Generator): CommandClass {
+  class MakeCommand extends BaseCommand {
+    static override commandName = generator.commandName
+    static override description = generator.description
+    // Filesystem only: scaffolding a file must not need a booted application,
+    // let alone a reachable database.
+    static override options = { startApp: false }
+
+    // `make:controller billing Invoice` — the module comes first, as the
+    // binary took it. Declared on the module-scoped commands only, so the
+    // others keep a single argument.
+    @args.string({
+      description: 'Module directory under app/',
+      required: generator.moduleScoped,
+    })
+    declare first: string
+
+    @args.string({ description: 'Name of the generated file', required: false })
+    declare second?: string
+
+    @flags.boolean({
+      description: 'Forcefully overwrite an existing file',
+      alias: 'f',
+    })
+    declare force?: boolean
+
+    @flags.boolean({
+      description: 'Print what would be written, without writing it',
+    })
+    declare dryRun?: boolean
+
+    @flags.boolean({ description: 'Report the outcome as a single JSON object' })
+    declare json?: boolean
+
+    @flags.string({
+      description: 'Which stack a middleware registers on: router, server or named',
+    })
+    declare stack?: string
+
+    @flags.string({ description: 'Event class this listener handles' })
+    declare event?: string
+
+    async run(): Promise<void> {
+      // Two positionals for a module-scoped generator, one for the rest.
+      const module = generator.moduleScoped ? this.first : undefined
+      const name = generator.moduleScoped ? (this.second ?? '') : this.first
+
+      if (generator.moduleScoped && this.second === undefined) {
+        this.logger.error(`${generator.commandName} takes a module and a name`)
+        this.exitCode = 1
+        return
+      }
+
+      const cwd = process.cwd()
+      const prepared = prepare(
+        generator,
+        module,
+        name,
+        {
+          ...(this.stack === undefined ? {} : { stack: this.stack }),
+          ...(this.event === undefined ? {} : { event: this.event }),
+        },
+        cwd,
+      )
+      if ('error' in prepared) {
+        this.logger.error(prepared.error)
+        this.exitCode = 1
+        return
+      }
+
+      report(this, [prepared.file], [], {
+        cwd,
+        dryRun: this.dryRun === true,
+        force: this.force === true,
+        json: this.json === true,
+      })
+
+      if (prepared.published && this.json !== true) {
+        // Worth saying: the output came from the project's own stub, so a
+        // surprise in it is not a bug in ream.
+        this.logger.info(`rendered from stubs/make/${generator.kind}.stub`)
+      }
+    }
+  }
+
+  // The class is anonymous to the debugger otherwise, and a stack trace
+  // naming `MakeCommand` ten times helps nobody.
+  Object.defineProperty(MakeCommand, 'name', {
+    value: `Make${generator.kind.charAt(0).toUpperCase()}${generator.kind.slice(1)}`,
+  })
+  return MakeCommand
+}
+
+/**
+ * `make:module` — an entity, a controller and a validator in one go.
+ *
+ * NOT the migration the binary also emitted: a migration is atlas' format and
+ * atlas' directory, and ream inventing one would produce a file its own
+ * `migration:run` never reads. `make:migration` is atlas' command, and this
+ * says so rather than guessing.
+ *
+ * The three are rendered before any is written, so a stub that fails to render
+ * leaves nothing half-generated behind.
+ */
+class MakeModule extends BaseCommand {
+  static override commandName = 'make:module'
+  static override description = 'Generate an entity, a controller and a validator'
+  static override options = { startApp: false }
+
+  @args.string({ description: 'Module directory under app/' })
+  declare module: string
+
+  @args.string({ description: 'Name shared by the generated files' })
+  declare name: string
+
+  @flags.boolean({ description: 'Forcefully overwrite existing files', alias: 'f' })
+  declare force?: boolean
+
+  @flags.boolean({ description: 'Print what would be written, without writing it' })
+  declare dryRun?: boolean
+
+  @flags.boolean({ description: 'Report the outcome as a single JSON object' })
+  declare json?: boolean
+
+  async run(): Promise<void> {
+    const cwd = process.cwd()
+    const entries: PlannedFile[] = []
+
+    for (const kind of ['entity', 'controller', 'validator'] as const) {
+      const generator = generatorFor(kind)
+      if (generator === undefined) {
+        this.logger.error(`no generator for "${kind}"`)
+        this.exitCode = 1
+        return
+      }
+      const prepared = prepare(generator, this.module, this.name, {}, cwd)
+      if ('error' in prepared) {
+        this.logger.error(prepared.error)
+        this.exitCode = 1
+        return
+      }
+      entries.push(prepared.file)
+    }
+
+    const warnings = [
+      // Said, not done: a barrel is the application's file, and appending to it
+      // blindly is how an export ends up duplicated.
+      `if app/${this.module}/index.ts exists, add the new exports to it yourself`,
+      "no migration was generated — that one is atlas': run `ream make:migration`",
+    ]
+
+    report(this, entries, warnings, {
+      cwd,
+      dryRun: this.dryRun === true,
+      force: this.force === true,
+      json: this.json === true,
+    })
+  }
+}
+
+/** Every `make:` command, built once. */
+export const MAKE_COMMANDS: readonly CommandClass[] = [
+  ...GENERATORS.map(makeCommand),
+  MakeModule,
+  Eject,
+]

package/src/console/make/eject.ts

@@ -0,0 +1,163 @@
+/**
+ * `eject` — copy a package's stub into the application so it can be edited.
+ *
+ * The other half of the override rule: `renderStub` prefers `stubs/<path>`
+ * when the application has one, and this is how it gets there. Copied
+ * verbatim, front matter included, because the `to:` line is part of what a
+ * project may want to change.
+ *
+ * Adonis' command, name and argument included — `node ace eject make/controller
+ * --pkg=@adonisjs/lucid`. `--pkg` reads the package's own `stubsRoot`, which
+ * every Ream package exports from its `./stubs` subpath, so ejecting atlas' or
+ * warden's templates needs nothing added here.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { BaseCommand } from '../BaseCommand.js'
+import { args, flags } from '../decorators.js'
+import { GENERATORS } from './generators.js'
+import {
+  isSafeStubPath,
+  PUBLISHED_ROOT,
+  REAM_STUBS_ROOT,
+  readStub,
+  splitFrontMatter,
+  stubPathFor,
+} from './resolve.js'
+
+/** Every `{{ name }}` a stub reads, so the listing cannot advertise a wrong one. */
+function variablesOf(source: string): string[] {
+  const found = new Set<string>()
+  for (const match of source.matchAll(/\{\{\{?\s*([\w.]+)\s*\}?\}\}/g)) {
+    const name = match[1]
+    if (name !== undefined) found.add(name)
+  }
+  return [...found].sort()
+}
+
+/** The `stubsRoot` a module exports, when it exports one. */
+async function stubsRootFrom(specifier: string): Promise<string | undefined> {
+  try {
+    const loaded: unknown = await import(specifier)
+    if (typeof loaded !== 'object' || loaded === null) return undefined
+    const root = (loaded as { stubsRoot?: unknown }).stubsRoot
+    return typeof root === 'string' ? root : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The `stubsRoot` a package exports, or nothing when it exports none.
+ *
+ * Read from the package rather than guessed from `node_modules/<pkg>/stubs`:
+ * a package is free to keep them elsewhere, and only its own export says
+ * where. Adonis reads the entrypoint, so that is tried first; the `./stubs`
+ * subpath is tried after, because a barrel that also runs in a browser cannot
+ * export a filesystem path — which is why Ream packages put it on a subpath.
+ */
+async function stubsRootOf(pkg: string): Promise<string | undefined> {
+  if (pkg === '@c9up/ream') return REAM_STUBS_ROOT
+  return (await stubsRootFrom(pkg)) ?? (await stubsRootFrom(`${pkg}/stubs`))
+}
+
+/** Every `.stub` under `root`, as paths relative to it. */
+function stubsUnder(root: string, prefix = ''): string[] {
+  const found: string[] = []
+  for (const entry of fs.readdirSync(path.join(root, prefix), { withFileTypes: true })) {
+    const relative = prefix === '' ? entry.name : `${prefix}/${entry.name}`
+    if (entry.isDirectory()) found.push(...stubsUnder(root, relative))
+    else if (entry.name.endsWith('.stub')) found.push(relative)
+  }
+  return found.sort()
+}
+
+export default class Eject extends BaseCommand {
+  static override commandName = 'eject'
+  static override description =
+    'Copy a package stub into stubs/ so the project can customise what make: generates'
+  static override options = { startApp: false }
+
+  @args.string({
+    description: 'The stub to copy, e.g. make/controller.stub — omit for a directory or all',
+    required: false,
+  })
+  declare stubPath?: string
+
+  @flags.string({ description: 'Which package to read the stub from' })
+  declare pkg?: string
+
+  @flags.boolean({ description: 'List what can be ejected, and the variables each stub reads' })
+  declare list?: boolean
+
+  @flags.boolean({ description: 'Overwrite a stub the project already ejected' })
+  declare force?: boolean
+
+  async run(): Promise<void> {
+    const pkg = this.pkg ?? '@c9up/ream'
+    const stubsRoot = await stubsRootOf(pkg)
+    if (stubsRoot === undefined || !fs.existsSync(stubsRoot)) {
+      this.logger.error(`"${pkg}" ships no stubs (no \`stubsRoot\` on its ./stubs subpath)`)
+      this.exitCode = 1
+      return
+    }
+
+    if (this.list === true) {
+      this.#printList(stubsRoot)
+      return
+    }
+
+    const requested = this.stubPath
+    if (requested !== undefined && !isSafeStubPath(requested)) {
+      this.logger.error(`unusable stub path: ${requested}`)
+      this.exitCode = 1
+      return
+    }
+
+    // A path with no `.stub` suffix names a directory — `eject make` takes the
+    // lot, which is what makes ejecting every generator one command.
+    const available = stubsUnder(stubsRoot)
+    const selected =
+      requested === undefined
+        ? available
+        : requested.endsWith('.stub')
+          ? available.filter((candidate) => candidate === requested)
+          : available.filter((candidate) => candidate.startsWith(`${requested}/`))
+
+    if (selected.length === 0) {
+      this.logger.error(`"${pkg}" ships no stub matching "${requested ?? ''}"`)
+      this.exitCode = 1
+      return
+    }
+
+    for (const stub of selected) {
+      const destination = path.join(process.cwd(), PUBLISHED_ROOT, stub)
+      if (fs.existsSync(destination) && this.force !== true) {
+        this.logger
+          .action(`eject ${PUBLISHED_ROOT}/${stub}`)
+          .skipped('already ejected, use --force')
+        continue
+      }
+      fs.mkdirSync(path.dirname(destination), { recursive: true })
+      // The shipped one, never the project's copy: ejecting over your own edit
+      // with your own edit is a no-op that reads as success.
+      fs.writeFileSync(destination, fs.readFileSync(path.join(stubsRoot, stub)))
+      this.logger.action(`eject ${PUBLISHED_ROOT}/${stub}`).succeeded()
+    }
+  }
+
+  /** What each generator reads, taken from the stub rather than a kept list. */
+  #printList(stubsRoot: string): void {
+    const table = this.ui.table().head(['Stub', 'Variables'])
+    const generatorStubs = new Set(GENERATORS.map((generator) => stubPathFor(generator.kind)))
+    for (const stub of stubsUnder(stubsRoot)) {
+      const { source } = readStub(stubsRoot, stub, path.join(process.cwd(), '__none__'))
+      const variables = generatorStubs.has(stub)
+        ? variablesOf(splitFrontMatter(source).body).join(', ')
+        : ''
+      table.row([stub, variables])
+    }
+    table.render()
+  }
+}

package/src/console/make/flush.ts

@@ -0,0 +1,125 @@
+/**
+ * Turning rendered stubs into files on disk.
+ *
+ * Split from the commands because the rules are the same for one file and for
+ * the three `make:module` emits, and they are not the obvious ones:
+ *
+ *   - A file that is already there is SKIPPED, not overwritten and not an
+ *     error — Adonis' generators answer `SKIPPED:` and carry on, and `--force`
+ *     is how one asks for the overwrite.
+ *   - With `--force`, a failure half-way through puts back what the same run
+ *     had already written. A generator that leaves a clobbered entity behind
+ *     after failing on the controller is worse than one that writes nothing.
+ *     That rollback is ours, not Adonis': its generators never overwrite more
+ *     than one file per command.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+/** One file a generator intends to write. */
+export interface PlannedFile {
+  path: string
+  content: string
+  /** Was something already there? Answered while planning, not after. */
+  exists: boolean
+}
+
+export interface FlushOptions {
+  cwd: string
+  dryRun: boolean
+  force: boolean
+}
+
+/**
+ * What a run did, in the shapes `--json` prints — see {@link outcomePayload}.
+ */
+export type FlushOutcome =
+  | { status: 'planned'; files: PlannedFile[]; warnings: string[] }
+  | {
+      status: 'written'
+      createdFiles: string[]
+      modifiedFiles: string[]
+      skippedFiles: string[]
+      warnings: string[]
+    }
+
+/** `exists` is read now, not at write time: a plan describes one moment. */
+export function plannedFile(destination: string, content: string, cwd: string): PlannedFile {
+  return {
+    path: destination,
+    content,
+    exists: fs.existsSync(path.resolve(cwd, destination)),
+  }
+}
+
+export function flush(
+  entries: readonly PlannedFile[],
+  warnings: readonly string[],
+  options: FlushOptions,
+): FlushOutcome {
+  if (options.dryRun) {
+    return { status: 'planned', files: [...entries], warnings: [...warnings] }
+  }
+
+  const createdFiles: string[] = []
+  const modifiedFiles: string[] = []
+  const skippedFiles: string[] = []
+  /** What each written path held before, so a later failure can put it back. */
+  const rollbacks: Array<{ path: string; prior: Buffer | undefined }> = []
+
+  try {
+    for (const entry of entries) {
+      if (entry.exists && !options.force) {
+        skippedFiles.push(entry.path)
+        continue
+      }
+      const target = path.resolve(options.cwd, entry.path)
+      const prior = entry.exists ? fs.readFileSync(target) : undefined
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.writeFileSync(target, entry.content)
+      rollbacks.push({ path: target, prior })
+      if (entry.exists) modifiedFiles.push(entry.path)
+      else createdFiles.push(entry.path)
+    }
+  } catch (error) {
+    rollback(rollbacks)
+    throw error
+  }
+
+  return { status: 'written', createdFiles, modifiedFiles, skippedFiles, warnings: [...warnings] }
+}
+
+/**
+ * Undo in reverse, and never throw: the caller is already reporting a failure,
+ * and a rollback error on top of it buries the one that matters. What could not
+ * be undone is named on stderr instead.
+ */
+function rollback(rollbacks: readonly { path: string; prior: Buffer | undefined }[]): void {
+  for (const entry of [...rollbacks].reverse()) {
+    try {
+      if (entry.prior === undefined) fs.rmSync(entry.path, { force: true })
+      else fs.writeFileSync(entry.path, entry.prior)
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      process.stderr.write(`  rollback: failed to restore ${entry.path}: ${detail}\n`)
+    }
+  }
+}
+
+/**
+ * The outcome as the JSON object `--json` prints, kept in one place because it
+ * is a contract with another package rather than a debug dump: `ream-mcp` reads
+ * the last line of stdout and dispatches on which shape it is.
+ */
+export function outcomePayload(outcome: FlushOutcome): Record<string, unknown> {
+  if (outcome.status === 'planned') {
+    return { files: outcome.files, warnings: outcome.warnings }
+  }
+  return {
+    createdFiles: outcome.createdFiles,
+    modifiedFiles: outcome.modifiedFiles,
+    skippedFiles: outcome.skippedFiles,
+    warnings: outcome.warnings,
+  }
+}