@c9up/ream 0.2.8 → 0.2.10

package/src/bodyparser/MultipartFile.ts

@@ -110,6 +110,8 @@ export class MultipartFile {
 
   /** Magic-byte fingerprint — set by {@link detectType}; absent for content `file-type` can't detect (text: txt/csv/svg/json). */
   #detected?: { ext: string; mime: string }
+  /** Whether the magic-byte pass has run, however it turned out. */
+  #detectionRan = false
 
   constructor(options: {
     fieldName: string
@@ -136,9 +138,22 @@ export class MultipartFile {
    * extension in force — same fallback AdonisJS uses.
    */
   async detectType(): Promise<void> {
-    const { fileTypeFromBuffer } = await import('file-type')
+    const { fileTypeFromBuffer, supportedExtensions } = await import('file-type')
+    detectableExtensions = supportedExtensions
     const result = await fileTypeFromBuffer(this.content)
     if (result) this.#detected = { ext: result.ext, mime: result.mime }
+    this.#detectionRan = true
+  }
+
+  /**
+   * Where {@link mime} and {@link extname} came from.
+   *
+   * `'detected'` means the bytes said so. `'claimed'` means they did not, and
+   * what is reported is the filename and the header the client sent — which
+   * the client chose.
+   */
+  get typeSource(): 'detected' | 'claimed' {
+    return this.#detected ? 'detected' : 'claimed'
   }
 
   /**
@@ -201,11 +216,35 @@ export class MultipartFile {
         this.errors.push(
           `Extension '${this.extname}' not allowed. Allowed: ${options.extnames.join(', ')}`,
         )
+      } else if (this.#claimsATypeItCannotBe(options.extnames)) {
+        // Every allowed format carries a signature, and none was found — so the
+        // bytes are definitively not one of them, whatever the name says. A
+        // shell script uploaded as `avatar.png` with `Content-Type: image/png`
+        // otherwise passes an image allowlist, because both halves of what was
+        // checked came from the client.
+        this.errors.push(
+          `Extension '${this.extname}' is claimed by the upload, not found in its content. ` +
+            `Every allowed format (${options.extnames.join(', ')}) has a signature, and this file carries none.`,
+        )
       }
     }
     return this.errors.length === 0
   }
 
+  /**
+   * Whether refusing this upload is warranted on the strength of the allowlist
+   * alone.
+   *
+   * Only when the magic-byte pass actually ran and found nothing, AND every
+   * allowed extension is one it would have recognised. For a list that allows
+   * `csv` or `txt`, finding nothing is the normal case and says nothing.
+   */
+  #claimsATypeItCannotBe(extnames: string[]): boolean {
+    if (this.#detected || !this.#detectionRan) return false
+    if (!detectableExtensions) return false
+    return extnames.every((extension) => detectableExtensions?.has(extension))
+  }
+
   get isValid(): boolean {
     return this.errors.length === 0
   }
@@ -363,3 +402,11 @@ export function hydrateMultipartPayload(payload: {
   )
   return { fields, files }
 }
+
+/**
+ * The extensions `file-type` can recognise, captured on the first detection.
+ *
+ * Module-level because it is a property of the library, not of a file, and
+ * because `validate()` is synchronous while reading it is not.
+ */
+let detectableExtensions: ReadonlySet<string> | undefined

package/src/commands/Migrate.ts

@@ -0,0 +1,18 @@
+/** `migrate` — apply every pending migration, in every registered store. */
+
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+import { MigrateBase } from './MigrateBase.js'
+
+export default class Migrate extends MigrateBase {
+  static override commandName = 'migrate'
+  static override description = 'Run pending migrations for every registered migration source'
+
+  protected async migrateSource(source: RegisteredMigrationSource): Promise<void> {
+    const executed = await source.runner.migrate()
+    if (executed.length === 0) {
+      this.report(source, 'nothing to migrate.')
+      return
+    }
+    for (const name of executed) this.report(source, `migrated: ${name}`)
+  }
+}

package/src/commands/MigrateBase.ts

@@ -0,0 +1,81 @@
+/**
+ * What `migrate`, `migrate:rollback` and `migrate:status` share.
+ *
+ * All three drive the SAME thing — the `migrations` registry, where each data
+ * package puts its runner — and differ only in which method they call and how
+ * they print the result. A ream particularity, deliberate: AdonisJS has one
+ * store and can name it, while an application here may hold a relational store
+ * and a time-series one at once, so the command names none of them.
+ *
+ * Sequentially, never in parallel: two stores on one database server would
+ * contend on locks, and interleaved output makes a failure impossible to
+ * attribute to the store that caused it.
+ */
+
+import { BaseCommand } from '../console/BaseCommand.js'
+import { flags } from '../console/decorators.js'
+import type { CommandOptions } from '../console/types.js'
+import type { MigrationRegistry } from '../migrations/MigrationRegistry.js'
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+
+export abstract class MigrateBase extends BaseCommand {
+  static override options: CommandOptions = { startApp: true }
+
+  @flags.string({
+    description: 'Only this migration source, by the name its package registered',
+  })
+  declare only?: string
+
+  /** What to do with one store. Implemented by each command. */
+  protected abstract migrateSource(source: RegisteredMigrationSource): Promise<void>
+
+  async run(): Promise<void> {
+    const sources = await this.#resolveSources()
+    if (sources === undefined) return
+
+    for (const source of sources) {
+      await this.migrateSource(source)
+    }
+  }
+
+  /** The line every message is prefixed with, so multi-store output stays legible. */
+  protected report(source: RegisteredMigrationSource, message: string): void {
+    this.logger.log(`  [${source.name}] ${message}`)
+  }
+
+  /**
+   * The sources this run covers, or `undefined` when the run should stop —
+   * having said why.
+   *
+   * An empty registry is NOT a failure: an application may legitimately have no
+   * data package yet. Naming which thing is missing beats exiting non-zero on a
+   * state the user may have chosen.
+   */
+  async #resolveSources(): Promise<RegisteredMigrationSource[] | undefined> {
+    const registry = await this.app.container.resolve<MigrationRegistry>('migrations')
+
+    if (this.only !== undefined) {
+      const picked = registry.get(this.only)
+      if (picked === undefined) {
+        const names = registry.names()
+        this.logger.error(`No migration source named "${this.only}".`)
+        this.logger.error(
+          names.length > 0
+            ? `  Registered: ${names.join(', ')}`
+            : '  No data package registered one. Is its provider in reamrc.ts?',
+        )
+        this.exitCode = 1
+        return undefined
+      }
+      return [picked]
+    }
+
+    const sources = registry.all()
+    if (sources.length === 0) {
+      this.logger.info('No migration source registered.')
+      this.logger.info('  A data package registers one from its provider — check reamrc.ts.')
+      return undefined
+    }
+    return sources
+  }
+}

package/src/commands/MigrateRollback.ts

@@ -0,0 +1,18 @@
+/** `migrate:rollback` — undo the last batch, in every registered store. */
+
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+import { MigrateBase } from './MigrateBase.js'
+
+export default class MigrateRollback extends MigrateBase {
+  static override commandName = 'migrate:rollback'
+  static override description = 'Roll back the last batch for every registered migration source'
+
+  protected async migrateSource(source: RegisteredMigrationSource): Promise<void> {
+    const rolled = await source.runner.rollback()
+    if (rolled.length === 0) {
+      this.report(source, 'nothing to rollback.')
+      return
+    }
+    for (const name of rolled) this.report(source, `rolled back: ${name}`)
+  }
+}

package/src/commands/MigrateStatus.ts

@@ -0,0 +1,22 @@
+/** `migrate:status` — what has run and what has not, in every registered store. */
+
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+import { MigrateBase } from './MigrateBase.js'
+
+export default class MigrateStatus extends MigrateBase {
+  static override commandName = 'migrate:status'
+  static override description = 'Show applied and pending migrations for every source'
+
+  protected async migrateSource(source: RegisteredMigrationSource): Promise<void> {
+    const statuses = await source.runner.status()
+    if (statuses.length === 0) {
+      this.report(source, 'no migrations found.')
+      return
+    }
+    for (const node of statuses) {
+      const mark = node.status === 'applied' ? '✓' : '○'
+      const batch = node.batch === undefined ? '' : ` (batch ${node.batch})`
+      this.report(source, `${mark} ${node.name}${batch}`)
+    }
+  }
+}

package/src/commands/ScheduleList.ts

@@ -0,0 +1,66 @@
+/**
+ * `schedule:list` — every registered task, when it next fires, and how its past
+ * runs went.
+ *
+ * The columns are the operator's questions in order: is my task registered at
+ * all, on what schedule, when does it fire next, when did it last fire, and is
+ * it failing. Stats come from the scheduler's own tracker, so a task that has
+ * never run reads as `—` rather than a zero that looks like a result.
+ */
+
+import { BaseCommand } from '../console/BaseCommand.js'
+import type { CommandOptions } from '../console/types.js'
+import { resolveScheduler } from './scheduler_resolver.js'
+
+/** Over-long names and cron expressions are truncated so the table stays a table. */
+function truncate(value: string, width: number): string {
+  return value.length > width ? `${value.slice(0, width - 1)}…` : value
+}
+
+function asDate(ms: number | null): string {
+  return ms === null ? '—' : new Date(ms).toISOString()
+}
+
+export default class ScheduleList extends BaseCommand {
+  static override commandName = 'schedule:list'
+  static override description = 'List every registered scheduled task, its next run and its stats'
+  static override options: CommandOptions = { startApp: true }
+
+  async run(): Promise<void> {
+    const scheduler = await resolveScheduler(this)
+    if (!scheduler) return
+
+    const tasks = scheduler.listTasks()
+    if (tasks.length === 0) {
+      this.logger.info('No scheduled tasks registered.')
+      return
+    }
+
+    this.logger.log(
+      [
+        'NAME'.padEnd(32),
+        'CRON'.padEnd(18),
+        'NEXT RUN'.padEnd(22),
+        'LAST RUN'.padEnd(22),
+        'RUNS'.padStart(6),
+        'ERR'.padStart(5),
+        'AVG(ms)'.padStart(9),
+      ].join(' '),
+    )
+
+    for (const task of tasks) {
+      const stats = scheduler.getStats(task.name)
+      this.logger.log(
+        [
+          truncate(task.name, 32).padEnd(32),
+          truncate(task.cronExpr, 18).padEnd(18),
+          asDate(task.nextRun).padEnd(22),
+          asDate(stats.lastRunMs).padEnd(22),
+          String(stats.runCount).padStart(6),
+          String(stats.errorCount).padStart(5),
+          String(Math.round(stats.avgDurationMs)).padStart(9),
+        ].join(' '),
+      )
+    }
+  }
+}

package/src/commands/ScheduleRun.ts

@@ -0,0 +1,65 @@
+/**
+ * `schedule:run <name>` — run one registered task immediately.
+ *
+ * An admin override: it calls the task body directly, so it bypasses both the
+ * cron schedule and the distributed lock. That is the point — you reach for it
+ * when a task must run now, or to see it fail with your own eyes — and it is
+ * also why the exit codes are distinct: `1` the task failed, `2` no such task,
+ * `3` an invocation of it is already in flight.
+ */
+
+import { BaseCommand } from '../console/BaseCommand.js'
+import { args } from '../console/decorators.js'
+import type { CommandOptions } from '../console/types.js'
+import { resolveScheduler } from './scheduler_resolver.js'
+
+export default class ScheduleRun extends BaseCommand {
+  static override commandName = 'schedule:run'
+  static override description = 'Run a registered scheduled task once, now (bypasses the lock)'
+  static override options: CommandOptions = { startApp: true }
+
+  @args.string({ description: 'Task name, as `schedule:list` prints it' })
+  declare name: string
+
+  async run(): Promise<void> {
+    // Rejected here rather than in the scheduler so the message arrives without
+    // the operator first paying for a boot.
+    if (this.name.trim() === '') {
+      this.logger.error('Task name cannot be empty. Usage: schedule:run <name>')
+      this.exitCode = 1
+      return
+    }
+
+    const scheduler = await resolveScheduler(this)
+    if (!scheduler) return
+
+    const result = await scheduler.runTaskNow(this.name)
+    const duration = Math.round(result.durationMs)
+
+    if (result.outcome === 'unknown') {
+      this.logger.error(
+        `Unknown task: ${this.name}. Run "schedule:list" to see the registered tasks.`,
+      )
+      this.exitCode = 2
+      return
+    }
+
+    if (result.outcome === 'already-running') {
+      this.logger.error(
+        `Task ${this.name} is already running in this process — skipped. Try again once it completes.`,
+      )
+      this.exitCode = 3
+      return
+    }
+
+    if (result.outcome === 'completed') {
+      this.logger.success(`${this.name} completed in ${duration} ms`)
+      return
+    }
+
+    this.logger.error(
+      `${this.name} failed after ${duration} ms: ${result.error?.message || 'unknown error'}`,
+    )
+    this.exitCode = 1
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,73 @@
+/**
+ * `@c9up/ream/commands` — the commands the framework itself ships.
+ *
+ * The shape AdonisJS uses for `@adonisjs/core/commands`: a module answering
+ * `getMetaData()` then `getCommand()`, so listing a command does not import it.
+ *
+ * The kernel registers this loader on its own rather than waiting for an entry
+ * in `reamrc.commands` — the deviation from AdonisJS, where the starter kit
+ * lists it. These commands were part of the `ream` binary before they were
+ * classes, and an application that upgrades must not silently lose them.
+ */
+
+import type { CommandClass, SerializedCommand } from '../console/types.js'
+
+interface Entry {
+  commandName: string
+  description: string
+  load: () => Promise<{ default: CommandClass }>
+}
+
+const COMMANDS: readonly Entry[] = [
+  // The registry commands first: a data package registers its runner, and
+  // these drive whatever registered — they name no store.
+  {
+    commandName: 'migrate',
+    description: 'Run pending migrations for every registered migration source',
+    load: () => import('./Migrate.js'),
+  },
+  {
+    commandName: 'migrate:rollback',
+    description: 'Roll back the last batch for every registered migration source',
+    load: () => import('./MigrateRollback.js'),
+  },
+  {
+    commandName: 'migrate:status',
+    description: 'Show applied and pending migrations for every source',
+    load: () => import('./MigrateStatus.js'),
+  },
+  {
+    commandName: 'schedule:list',
+    description: 'List every registered scheduled task, its next run and its stats',
+    load: () => import('./ScheduleList.js'),
+  },
+  {
+    commandName: 'schedule:run',
+    description: 'Run a registered scheduled task once, now (bypasses the lock)',
+    load: () => import('./ScheduleRun.js'),
+  },
+]
+
+/** `migrate:status` → `migrate`; a name without a colon has no namespace. */
+function namespaceOf(commandName: string): string | null {
+  const colon = commandName.indexOf(':')
+  return colon === -1 ? null : commandName.slice(0, colon)
+}
+
+export async function getMetaData(): Promise<SerializedCommand[]> {
+  return COMMANDS.map((entry) => ({
+    commandName: entry.commandName,
+    namespace: namespaceOf(entry.commandName),
+    description: entry.description,
+    aliases: [],
+    options: { startApp: true },
+    args: [],
+    flags: [],
+  }))
+}
+
+export async function getCommand(metadata: SerializedCommand): Promise<CommandClass | null> {
+  const entry = COMMANDS.find((command) => command.commandName === metadata.commandName)
+  if (!entry) return null
+  return (await entry.load()).default
+}

package/src/commands/scheduler_resolver.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve the scheduler for the `schedule:*` commands.
+ *
+ * Shared because the failure is the same one on both, and it is a
+ * configuration mistake rather than a crash: the provider is simply not in the
+ * list, and the message has to say so — a container error mentioning an
+ * unbound `scheduler` binding tells an operator nothing.
+ */
+
+import type { BaseCommand } from '../console/BaseCommand.js'
+import type { Scheduler } from '../scheduler/Scheduler.js'
+
+export async function resolveScheduler(command: BaseCommand): Promise<Scheduler | undefined> {
+  try {
+    return await command.app.container.resolve<Scheduler>('scheduler')
+  } catch {
+    command.logger.error(
+      'No ScheduleProvider is registered. Add ScheduleProvider to the providers list in reamrc.ts.',
+    )
+    command.exitCode = 2
+    return undefined
+  }
+}

package/src/env/Env.ts

@@ -5,6 +5,7 @@ import {
   removeIdentifier,
 } from './interpolate.js'
 import { loadEnvFiles } from './loadEnvFiles.js'
+import { normalizeNodeEnv } from './nodeEnv.js'
 import { type SchemaNode, schema } from './schema.js'
 
 /**
@@ -87,7 +88,7 @@ export class Env<Values extends Record<string, unknown>> {
     appRoot: URL,
     schema: S,
   ): Promise<Env<EnvRecord<S>>> {
-    loadEnvFiles(appRoot, { skipEnvLocal: process.env.NODE_ENV === 'test' })
+    loadEnvFiles(appRoot, { skipEnvLocal: normalizeNodeEnv(process.env.NODE_ENV) === 'test' })
 
     return new Env(Env.rules(schema).validate(process.env))
   }

package/src/env/loadEnvFiles.ts

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { parseEnv } from 'node:util'
 import { interpolate } from './interpolate.js'
+import { normalizeNodeEnv } from './nodeEnv.js'
 
 /**
  * Load `.env` files into `process.env` — the shared primitive behind both the
@@ -17,7 +18,10 @@ import { interpolate } from './interpolate.js'
  *   developer's local overrides don't leak into tests).
  */
 export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
-  const nodeEnv = process.env.NODE_ENV
+  // Normalised, so `NODE_ENV=prod` loads `.env.production` — the file the
+  // deployment actually wrote — instead of looking for `.env.prod`.
+  const raw = normalizeNodeEnv(process.env.NODE_ENV)
+  const nodeEnv = raw === 'unknown' ? undefined : raw
   const files = [
     nodeEnv ? `.env.${nodeEnv}.local` : null,
     options.skipEnvLocal ? null : '.env.local',

package/src/env/nodeEnv.ts

@@ -0,0 +1,38 @@
+/**
+ * Reading `NODE_ENV`, with the aliases people actually set.
+ *
+ * `NODE_ENV=prod` is a normal thing to find in a Dockerfile or a platform's
+ * dashboard, and a bare `=== 'production'` reads it as "not production": the
+ * app then serves without Secure cookies, with development error pages, and
+ * loads the wrong `.env` file. Normalising once, here, is what stops that
+ * spelling from deciding how an application behaves.
+ *
+ * The tables mirror upstream exactly. Anything outside them is handed back
+ * lowercased rather than forced into a bucket — `staging` stays `staging`, so
+ * `.env.staging` still resolves.
+ */
+
+const DEV_ENVS = ['dev', 'develop', 'development']
+const PROD_ENVS = ['prod', 'production']
+const TEST_ENVS = ['test', 'testing']
+
+/**
+ * The canonical name for whatever `NODE_ENV` holds.
+ *
+ * Returns `'unknown'` when it is unset — an absent environment is not the
+ * development one, and pretending otherwise turns a misconfigured deploy into
+ * a silently permissive one.
+ */
+export function normalizeNodeEnv(value: string | undefined): string {
+  if (!value || typeof value !== 'string') return 'unknown'
+  const env = value.toLowerCase()
+  if (DEV_ENVS.includes(env)) return 'development'
+  if (PROD_ENVS.includes(env)) return 'production'
+  if (TEST_ENVS.includes(env)) return 'test'
+  return env
+}
+
+/** The current environment, normalised. */
+export function currentNodeEnv(): string {
+  return normalizeNodeEnv(process.env.NODE_ENV)
+}

package/src/errors/ReamError.ts

@@ -7,6 +7,8 @@
  * @implements FR71, FR72, FR73, FR77
  */
 
+import { currentNodeEnv } from '../env/nodeEnv.js'
+
 /**
  * Is this a Ream error, and one of these codes?
  *
@@ -39,7 +41,12 @@ export function isReamError(error: unknown, ...codes: string[]): boolean {
 }
 
 export class ReamError extends Error {
-  /** Error code (e.g., "ATLAS_QUERY_ERROR", "CONTAINER_NOT_FOUND") */
+  /**
+   * Error code, `E_`-prefixed as every framework code is — an application
+   * matching on one should never have to remember which convention a
+   * particular package followed (e.g. "E_ATLAS_QUERY_ERROR",
+   * "E_CONTAINER_NOT_FOUND").
+   */
   readonly code: string
 
   /** Additional context key-value pairs */
@@ -164,6 +171,6 @@ export class ReamError extends Error {
    * Auto-format based on NODE_ENV.
    */
   toFormattedString(): string {
-    return process.env.NODE_ENV === 'production' ? this.toProdString() : this.toDevString()
+    return currentNodeEnv() === 'production' ? this.toProdString() : this.toDevString()
   }
 }

package/src/graphql/GraphQLEngine.ts

@@ -22,6 +22,7 @@
  */
 
 import * as fs from 'node:fs'
+import { currentNodeEnv } from '../env/nodeEnv.js'
 import { loadNapi } from '../helpers/napi-loader.js'
 import type { HttpContext } from '../http/HttpContext.js'
 
@@ -231,7 +232,7 @@ export class GraphQLEngine {
     }
     this.#schemaSource = fs.readFileSync(config.schemaPath, 'utf8')
     this.path = config.path ?? '/graphql'
-    this.#playground = config.playground ?? process.env.NODE_ENV !== 'production'
+    this.#playground = config.playground ?? currentNodeEnv() !== 'production'
     this.#maxQueryBytes = config.maxQueryBytes ?? 100_000
     this.#maxDepth = config.maxDepth ?? 12
     this.#maxComplexity = config.maxComplexity ?? 1000
@@ -288,7 +289,7 @@ export class GraphQLEngine {
       ctx.response.status(200).json(result)
     } catch (err) {
       const message =
-        process.env.NODE_ENV !== 'production' && err instanceof Error
+        currentNodeEnv() !== 'production' && err instanceof Error
           ? err.message
           : 'Internal server error'
       ctx.response.status(500).json({ errors: [{ message }] })

package/src/http/Exception.ts

@@ -7,6 +7,7 @@
  */
 
 import { format } from 'node:util'
+import { currentNodeEnv } from '../env/nodeEnv.js'
 import { Macroable } from '../utils/Macroable.js'
 import type { HttpContext } from './HttpContext.js'
 
@@ -272,7 +273,7 @@ type LogLevel = 'error' | 'warn' | 'info'
 export class ExceptionHandler extends Macroable {
   protected debug: boolean
   /** Render `statusPages` (browser HTML). Defaults to production only (AdonisJS). */
-  protected renderStatusPages: boolean = process.env.NODE_ENV === 'production'
+  protected renderStatusPages: boolean = currentNodeEnv() === 'production'
   /** Status → HTML renderer, keys may be single codes or `'500..599'` ranges. */
   protected statusPages: Record<string, StatusPageRenderer> = {}
   /** Master reporting switch (AdonisJS `reportErrors`). */