@c9up/ream 0.1.25 → 0.1.27

package/src/env/loadEnvFiles.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { parseEnv } from 'node:util'
+import { interpolate } from './interpolate.js'
 
 /**
  * Load `.env` files into `process.env` — the shared primitive behind both the
@@ -31,10 +32,17 @@ export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } =
     } catch {
       continue // file absent — nothing to load
     }
-    for (const [key, value] of Object.entries(parseEnv(contents))) {
-      if (typeof value === 'string' && process.env[key] === undefined) {
-        process.env[key] = value
-      }
+    const parsed = parseEnv(contents)
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value !== 'string' || process.env[key] !== undefined) continue
+      // Interpolate `$VAR`/`${VAR}` against process.env then this file's own
+      // (already-loaded) values, and apply any `identifier:` resolver.
+      process.env[key] = interpolate(value, (name) => {
+        const fromProcess = process.env[name]
+        if (fromProcess !== undefined) return fromProcess
+        const fromFile = parsed[name]
+        return typeof fromFile === 'string' ? fromFile : undefined
+      })
     }
   }
 }

package/src/env/schema.ts

@@ -13,6 +13,8 @@
  * value as `undefined`.
  */
 
+import { Secret } from './Secret.js'
+
 /** A single failed-variable validation — collected by `Env.create`. */
 export class EnvVarError extends Error {
   constructor(message: string) {
@@ -26,14 +28,27 @@ export interface SchemaNode<T> {
   validate(name: string, value: string | undefined): T
 }
 
-/** A required node that can be turned optional — `.optional()` widens `T` to `T | undefined`. */
+/** Condition deciding whether a variable is optional (AdonisJS `optionalWhen`). */
+export type OptionalCondition = boolean | ((name: string, value: string | undefined) => boolean)
+
+/**
+ * A required node that can be turned optional — `.optional()` widens `T` to
+ * `T | undefined`; `.optionalWhen(cond)` does so only when `cond` holds.
+ */
 export interface RequiredNode<T> extends SchemaNode<T> {
   optional(): SchemaNode<T | undefined>
+  optionalWhen(condition: OptionalCondition): SchemaNode<T | undefined>
 }
 
-export interface StringOptions {
+/** Options common to every schema function (AdonisJS `SchemaFnOptions`). */
+export interface SchemaFnOptions {
+  /** Custom error message, replacing the default when validation fails. */
+  message?: string
+}
+
+export interface StringOptions extends SchemaFnOptions {
   /** Validate the string against a known format. */
-  format?: 'host' | 'url' | 'email'
+  format?: 'host' | 'url' | 'email' | 'uuid'
   /** For `format: 'url'` — require a TLD (default true). */
   tld?: boolean
   /** For `format: 'url'` — require a protocol (default true). */
@@ -45,24 +60,30 @@ const FALSE_VALUES = new Set(['false', '0'])
 
 /**
  * Build a node from a `parse` that only ever sees a present, non-empty string.
- * Required `validate` throws on absent/empty; `.optional()` returns `undefined`.
+ * Required `validate` throws on absent/empty (using `message` when given);
+ * `.optional()` returns `undefined`; `.optionalWhen(cond)` is optional only
+ * when the condition holds.
  */
-function makeNode<T>(parse: (name: string, raw: string) => T): RequiredNode<T> {
+function makeNode<T>(parse: (name: string, raw: string) => T, message?: string): RequiredNode<T> {
+  const required = (name: string, value: string | undefined): T => {
+    if (value === undefined || value === '') {
+      throw new EnvVarError(message ?? `Missing required environment variable "${name}"`)
+    }
+    return parse(name, value)
+  }
+  const optional = (name: string, value: string | undefined): T | undefined => {
+    if (value === undefined || value === '') return undefined
+    return parse(name, value)
+  }
   return {
-    validate(name, value) {
-      if (value === undefined || value === '') {
-        throw new EnvVarError(`Missing required environment variable "${name}"`)
-      }
-      return parse(name, value)
-    },
-    optional() {
-      return {
-        validate(name, value) {
-          if (value === undefined || value === '') return undefined
-          return parse(name, value)
-        },
-      }
-    },
+    validate: required,
+    optional: () => ({ validate: optional }),
+    optionalWhen: (condition) => ({
+      validate(name, value) {
+        const skip = typeof condition === 'function' ? condition(name, value) : condition
+        return skip ? optional(name, value) : required(name, value)
+      },
+    }),
   }
 }
 
@@ -93,6 +114,10 @@ function isEmail(value: string): boolean {
   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
 }
 
+function isUuid(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+}
+
 function checkFormat(name: string, value: string, options?: StringOptions): void {
   if (!options?.format) return
   const ok =
@@ -100,10 +125,13 @@ function checkFormat(name: string, value: string, options?: StringOptions): void
       ? isHost(value)
       : options.format === 'url'
         ? isUrl(value, options)
-        : isEmail(value)
+        : options.format === 'uuid'
+          ? isUuid(value)
+          : isEmail(value)
   if (!ok) {
     throw new EnvVarError(
-      `Environment variable "${name}" must be a valid ${options.format}, got "${value}"`,
+      options.message ??
+        `Environment variable "${name}" must be a valid ${options.format}, got "${value}"`,
     )
   }
 }
@@ -115,49 +143,95 @@ function stringParse(options?: StringOptions): (name: string, raw: string) => st
   }
 }
 
-/** `string(opts?)` is callable AND exposes `.optional(opts?)` — both Adonis forms. */
+/**
+ * `string(opts?)` is callable AND exposes `.optional(opts?)` / `.optionalWhen()`
+ * shortcuts — all AdonisJS forms.
+ */
 const string: ((options?: StringOptions) => RequiredNode<string>) & {
   optional(options?: StringOptions): SchemaNode<string | undefined>
-} = Object.assign((options?: StringOptions) => makeNode(stringParse(options)), {
-  optional: (options?: StringOptions) => makeNode(stringParse(options)).optional(),
+  optionalWhen(
+    condition: OptionalCondition,
+    options?: StringOptions,
+  ): SchemaNode<string | undefined>
+} = Object.assign((options?: StringOptions) => makeNode(stringParse(options), options?.message), {
+  optional: (options?: StringOptions) =>
+    makeNode(stringParse(options), options?.message).optional(),
+  optionalWhen: (condition: OptionalCondition, options?: StringOptions) =>
+    makeNode(stringParse(options), options?.message).optionalWhen(condition),
 })
 
-function number(): RequiredNode<number> {
-  return makeNode((name, raw) => {
+function numberParse(options?: SchemaFnOptions): (name: string, raw: string) => number {
+  return (name, raw) => {
     const parsed = Number(raw)
     if (Number.isNaN(parsed)) {
-      throw new EnvVarError(`Environment variable "${name}" must be a number, got "${raw}"`)
+      throw new EnvVarError(
+        options?.message ?? `Environment variable "${name}" must be a number, got "${raw}"`,
+      )
     }
     return parsed
-  })
+  }
 }
 
-function boolean(): RequiredNode<boolean> {
-  return makeNode((name, raw) => {
+function number(options?: SchemaFnOptions): RequiredNode<number> {
+  return makeNode(numberParse(options), options?.message)
+}
+
+function booleanParse(options?: SchemaFnOptions): (name: string, raw: string) => boolean {
+  return (name, raw) => {
     if (TRUE_VALUES.has(raw)) return true
     if (FALSE_VALUES.has(raw)) return false
     throw new EnvVarError(
-      `Environment variable "${name}" must be a boolean (true/false/1/0), got "${raw}"`,
+      options?.message ??
+        `Environment variable "${name}" must be a boolean (true/false/1/0), got "${raw}"`,
     )
-  })
+  }
+}
+
+function boolean(options?: SchemaFnOptions): RequiredNode<boolean> {
+  return makeNode(booleanParse(options), options?.message)
 }
 
-function enumNode<V extends readonly string[]>(values: V): RequiredNode<V[number]> {
+function enumNode<V extends readonly string[]>(
+  values: V,
+  options?: SchemaFnOptions,
+): RequiredNode<V[number]> {
   return makeNode((name, raw) => {
     const match = values.find((candidate) => candidate === raw)
     if (match === undefined) {
       throw new EnvVarError(
-        `Environment variable "${name}" must be one of [${values.join(', ')}], got "${raw}"`,
+        options?.message ??
+          `Environment variable "${name}" must be one of [${values.join(', ')}], got "${raw}"`,
       )
     }
     return match
-  })
+  }, options?.message)
 }
 
+/**
+ * `secret(opts?)` wraps the value in a {@link Secret} so it never leaks through
+ * logs/JSON (AdonisJS `Env.schema.secret`). Read it with `.release()`.
+ */
+const secret: ((options?: SchemaFnOptions) => RequiredNode<Secret<string>>) & {
+  optional(options?: SchemaFnOptions): SchemaNode<Secret<string> | undefined>
+  optionalWhen(
+    condition: OptionalCondition,
+    options?: SchemaFnOptions,
+  ): SchemaNode<Secret<string> | undefined>
+} = Object.assign(
+  (options?: SchemaFnOptions) => makeNode((_name, raw) => new Secret(raw), options?.message),
+  {
+    optional: (options?: SchemaFnOptions) =>
+      makeNode((_name, raw) => new Secret(raw), options?.message).optional(),
+    optionalWhen: (condition: OptionalCondition, options?: SchemaFnOptions) =>
+      makeNode((_name, raw) => new Secret(raw), options?.message).optionalWhen(condition),
+  },
+)
+
 /** The `Env.schema` surface. */
 export const schema = {
   string,
   number,
   boolean,
   enum: enumNode,
+  secret,
 }

package/src/errors/ReamError.ts

@@ -7,6 +7,37 @@
  * @implements FR71, FR72, FR73, FR77
  */
 
+/**
+ * Is this a Ream error, and one of these codes?
+ *
+ * The framework carries ONE error type with a `code`, because an error can be
+ * raised in Rust and rebuilt in TypeScript across the NAPI boundary — see
+ * {@link ReamError.fromNapi}. A class per code cannot cross that line, so the
+ * check that replaces `instanceof MyError` is this one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await consoleApp.exec('provision')
+ * } catch (error) {
+ *   if (isReamError(error, 'E_CONSOLE_MISSING_FLAG', 'E_CONSOLE_MISSING_ARGUMENT')) {
+ *     console.error(error.hint)   // narrowed: `error` IS a ReamError here
+ *     return
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export function isReamError(error: unknown): error is ReamError
+export function isReamError<const Code extends string>(
+  error: unknown,
+  ...codes: [Code, ...Code[]]
+): error is ReamError & { code: Code }
+export function isReamError(error: unknown, ...codes: string[]): boolean {
+  if (!(error instanceof ReamError)) return false
+  return codes.length === 0 || codes.includes(error.code)
+}
+
 export class ReamError extends Error {
   /** Error code (e.g., "ATLAS_QUERY_ERROR", "CONTAINER_NOT_FOUND") */
   readonly code: string

package/src/errors/prettyPrintError.ts

@@ -0,0 +1,20 @@
+/**
+ * Render an error for a human reading a terminal (AdonisJS `prettyPrintError`).
+ *
+ * Its own module rather than a helper inside `Ignitor.ts`: the console kernel
+ * renders the failures of the command it ran, and reaching into the Ignitor for
+ * that would make the two import each other.
+ */
+
+import { ReamError } from './ReamError.js'
+
+export function prettyPrintError(error: unknown): void {
+  if (error instanceof ReamError) {
+    console.error(error.toDevString())
+  } else if (error instanceof Error) {
+    console.error(`\n  ${error.message}\n`)
+    if (error.stack) console.error(error.stack)
+  } else {
+    console.error(error)
+  }
+}

package/src/events/Emitter.ts

@@ -35,7 +35,7 @@ type Listener<T = unknown> = ListenerFn<T> | ListenerConstructor<T>
 
 /** Resolver for instantiating listener classes with DI. */
 export interface ContainerResolver {
-  make<T>(target: new (...args: never[]) => T): T
+  make<T>(target: new (...args: never[]) => T): Promise<T>
 }
 
 export class Emitter {
@@ -135,7 +135,7 @@ export class Emitter {
         if (isListenerClass(listener)) {
           // Listener class — resolve via container for @inject() support
           const instance = this.resolver
-            ? this.resolver.make(listener as ListenerConstructor<T>)
+            ? await this.resolver.make(listener as ListenerConstructor<T>)
             : new (listener as ListenerConstructor<T>)()
           await instance.handle(event)
         } else {

package/src/events/EventsProvider.ts

@@ -15,8 +15,8 @@ import { setEmitter } from './services/main.js'
  */
 interface EventsContainer {
   singleton(token: unknown, factory: () => unknown): void
-  resolve<T = unknown>(token: unknown): T
-  make?<T>(target: new (...args: never[]) => T): T
+  resolve<T = unknown>(token: unknown): Promise<T>
+  make?<T>(target: new (...args: never[]) => T): Promise<T>
 }
 export interface EventsAppContext {
   container: EventsContainer
@@ -31,8 +31,8 @@ export default class EventsProvider {
     this.app.container.singleton(EventBus, () => new EventBus())
     this.app.container.singleton('bus', () => this.app.container.resolve<EventBus>(EventBus))
 
-    this.app.container.singleton(Emitter, () => {
-      const bus = this.app.container.resolve<EventBus>(EventBus)
+    this.app.container.singleton(Emitter, async () => {
+      const bus = await this.app.container.resolve<EventBus>(EventBus)
       // Forward `make` only when the host actually exposes it.
       // Emitter falls back to direct `new Listener()` instantiation
       // otherwise, which keeps zero-arg listener classes working
@@ -49,7 +49,7 @@ export default class EventsProvider {
   }
 
   async boot() {
-    this.#emitter = this.app.container.resolve<Emitter>(Emitter)
+    this.#emitter = await this.app.container.resolve<Emitter>(Emitter)
     BaseEvent.useEmitter(this.#emitter)
     setEmitter(this.#emitter)
   }

package/src/graphql/GraphQLEngine.ts

@@ -203,7 +203,7 @@ export interface SelectionField {
 export class GraphQLEngine {
   #schemaSource: string
   #resolvers: Map<string, ResolverEntry> = new Map()
-  #container?: { make<T>(target: new (...args: unknown[]) => T): T }
+  #container?: { make<T>(target: new (...args: unknown[]) => T): Promise<T> }
   readonly path: string
   #playground: boolean
   #maxQueryBytes: number
@@ -238,7 +238,7 @@ export class GraphQLEngine {
   }
 
   /** Set IoC container for resolver instantiation. */
-  useContainer(container: { make<T>(target: new (...args: unknown[]) => T): T }): void {
+  useContainer(container: { make<T>(target: new (...args: unknown[]) => T): Promise<T> }): void {
     this.#container = container
   }
 
@@ -369,7 +369,7 @@ export class GraphQLEngine {
     try {
       // Resolve handler via IoC or direct instantiation.
       const instance = this.#container
-        ? this.#container.make(entry.handlerClass)
+        ? await this.#container.make(entry.handlerClass)
         : new entry.handlerClass()
 
       const handler = instance[entry.methodName]
@@ -436,7 +436,7 @@ export class GraphQLEngine {
     const permissions = options.permissions ?? []
 
     const needsAuth = guards.length > 0 || roles.length > 0 || permissions.length > 0
-    if (needsAuth && !ctx.auth?.authenticated) {
+    if (needsAuth && !ctx.auth?.isAuthenticated) {
       return 'Unauthorized'
     }
 

package/src/graphql/GraphQLProvider.ts

@@ -28,6 +28,7 @@ export interface GraphQLProviderOptions {
 
 export class GraphQLProvider extends Provider {
   #engine?: GraphQLEngine
+  #registered = false
 
   constructor(app: AppContext, options: GraphQLProviderOptions = {}) {
     super(app)
@@ -45,9 +46,11 @@ export class GraphQLProvider extends Provider {
     if (!engine) return // GraphQL not configured — opt-out.
     const container = this.app.container
     if (container.has('graphql')) {
-      if (container.resolve('graphql') === engine) {
+      // Idempotent re-register: tracked with a flag rather than
+      // `container.resolve('graphql')` because resolution is now async.
+      if (this.#registered) {
         this.#engine = engine
-        return // re-register is idempotent
+        return
       }
       throw new ReamError(
         'GRAPHQL_PROVIDER_ALREADY_REGISTERED',
@@ -60,12 +63,13 @@ export class GraphQLProvider extends Provider {
     engine.useContainer(container)
     this.#engine = engine
     container.singleton('graphql', () => engine)
+    this.#registered = true
   }
 
   override async boot(): Promise<void> {
     const engine = this.#engine
     if (!engine) return
-    const router = this.app.container.make<Router>('router')
+    const router = await this.app.container.make<Router>('router')
     // GraphQLEngine.handle() serves the playground on GET and executes queries
     // on POST, so mount the same path for both verbs.
     router.get(engine.path, (ctx) => engine.handle(ctx))