@c9up/ream 0.2.3 → 0.2.5

package/dist/types/index.d.ts

@@ -1,10 +1,93 @@
 /**
- * The interfaces an application or a package augments.
+ * The interfaces an application or a package augments — `@c9up/ream/types`.
  *
  * Resolving from the container and picking an auth guard are both string
- * lookups; without a shared interface to augment, every call site casts. This
- * is the module those interfaces live in — `@c9up/ream/types`.
+ * lookups; without a shared interface to augment, every call site casts.
+ *
+ * The augmentable interfaces are DECLARED here rather than re-exported from a
+ * neighbouring file, and that is load-bearing: TypeScript augments the module
+ * that declares an interface, so a re-export makes
+ * `declare module '@c9up/ream/types' { interface Authenticators { … } }` a
+ * duplicate declaration instead of an augmentation. warden hit exactly that.
+ */
+import type { Application } from '../Application.js';
+import type { ConfigStore } from '../ConfigLoader.js';
+import type { Console } from '../console/Console.js';
+import type { Kernel } from '../console/Kernel.js';
+import type { Emitter } from '../events/Emitter.js';
+import type { HttpContext } from '../http/HttpContext.js';
+import type { MiddlewareRegistry } from '../middleware/Pipeline.js';
+import type { MigrationRegistry } from '../migrations/MigrationRegistry.js';
+import type { Router } from '../router/Router.js';
+import type { CookieSigner } from '../security/CookieSigner.js';
+import type { SignedUrl } from '../security/SignedUrl.js';
+import type { Server } from '../server/Server.js';
+/**
+ * Guard name → what `auth.use(name)` hands back.
+ *
+ * Empty here, and deliberately: ream owns no auth package, so it cannot know
+ * the guards an app configured. The auth package fills it in:
+ *
+ * ```ts
+ * declare module '@c9up/ream/types' {
+ *   interface Authenticators {
+ *     session: SessionGuard
+ *   }
+ * }
+ * ```
+ *
+ * Until something augments it, `keyof Authenticators` is `never` and `use()`
+ * falls through to its `unknown` signature — the previous behaviour kept as
+ * the floor rather than the ceiling.
+ */
+/**
+ * An EMPTY INTERFACE is the whole mechanism here, not an oversight. Rewritten
+ * as `type Authenticators = {}` the declaration stops being augmentable:
+ * `declare module '@c9up/ream/types' { interface Authenticators { … } }`
+ * becomes a duplicate identifier instead of a merge, and warden cannot type
+ * `ctx.auth.use()`. That is exactly what shipped in 0.2.3, where the formatter
+ * had rewritten it.
+ */
+export interface Authenticators {
+}
+/** A guard name this application knows about. */
+export type AuthenticatorName = keyof Authenticators;
+/**
+ * The container's known bindings.
+ *
+ * Ream core registers the entries below; anything else — `auth` (warden),
+ * `logger` (spectrum), `db` (atlas) — reaches this interface by augmentation
+ * from the package that owns it, which is why it is open rather than a closed
+ * union.
  */
-export type { AuthenticatorName, Authenticators } from './authenticators.js';
-export type { ContainerBinding, ContainerBindings } from './container.js';
+export interface ContainerBindings {
+    /** The application instance. */
+    app: Application;
+    /** Absolute path to the application root. */
+    appRoot: string;
+    /** The config store built from `config/*.ts`. */
+    config: ConfigStore;
+    /** The console application (AdonisJS calls its equivalent `ace`). */
+    console: Console;
+    /** The console kernel that dispatches commands. */
+    consoleKernel: Kernel;
+    /** The event emitter. */
+    emitter: Emitter;
+    /** Cookie/value signing and encryption, backed by `APP_KEY`. */
+    encryption: CookieSigner;
+    /** The `HttpContext` class itself — for `HttpContext.getOrFail()` style access. */
+    HttpContext: typeof HttpContext;
+    /** Named middleware registered by the app kernel. */
+    middleware: MiddlewareRegistry;
+    /** Migration sources contributed by data packages (atlas, eon, ...). */
+    migrations: MigrationRegistry;
+    /** The HTTP router. */
+    router: Router;
+    /** The HTTP server. */
+    server: Server;
+    /** Signed-URL generation and verification. */
+    signedUrl: SignedUrl;
+}
+/** A token this container knows how to resolve. */
+export type ContainerBinding = keyof ContainerBindings;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC5E,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAA;AAC3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;;;GAOG;AAEH,MAAM,WAAW,cAAc;CAAG;AAElC,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GAAG,MAAM,cAAc,CAAA;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,GAAG,EAAE,WAAW,CAAA;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,MAAM,EAAE,WAAW,CAAA;IACnB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAA;IAChB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAA;IACrB,yBAAyB;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,gEAAgE;IAChE,UAAU,EAAE,YAAY,CAAA;IACxB,mFAAmF;IACnF,WAAW,EAAE,OAAO,WAAW,CAAA;IAC/B,qDAAqD;IACrD,UAAU,EAAE,kBAAkB,CAAA;IAC9B,wEAAwE;IACxE,UAAU,EAAE,iBAAiB,CAAA;IAC7B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,MAAM,iBAAiB,CAAA"}

package/dist/types/index.js

@@ -1,9 +1,14 @@
 /**
- * The interfaces an application or a package augments.
+ * The interfaces an application or a package augments — `@c9up/ream/types`.
  *
  * Resolving from the container and picking an auth guard are both string
- * lookups; without a shared interface to augment, every call site casts. This
- * is the module those interfaces live in — `@c9up/ream/types`.
+ * lookups; without a shared interface to augment, every call site casts.
+ *
+ * The augmentable interfaces are DECLARED here rather than re-exported from a
+ * neighbouring file, and that is load-bearing: TypeScript augments the module
+ * that declares an interface, so a re-export makes
+ * `declare module '@c9up/ream/types' { interface Authenticators { … } }` a
+ * duplicate declaration instead of an augmentation. warden hit exactly that.
  */
 export {};
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -208,7 +208,8 @@
     "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsc -p tsconfig.build.json",
     "build:rust": "cargo build --release -p ream-http-napi -p ream-scheduler-napi -p ream-events-napi",
-    "build:napi": "pnpm build:rust && node scripts/copy-napi.mjs",
+    "build:napi-types": "node scripts/build-napi-types.mjs",
+    "build:napi": "pnpm build:rust && pnpm build:napi-types && node scripts/copy-napi.mjs",
     "test": "vitest run",
     "test:rust": "cargo test --all",
     "lint": "biome check src/",

package/scripts/build-napi-types.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Regenerate `src/native/generated.ts` from the Rust.
+ *
+ * Node rather than a shell script because this runs inside `build:napi`, and
+ * that runs on the Windows prebuild runner too: a bash `mktemp` there hands
+ * cargo a `/tmp/...` path the native proc-macro cannot write to, so the
+ * type-def file comes back empty and the build fails for no visible reason.
+ *
+ * One crate at a time on purpose: napi-derive APPENDS to `TYPE_DEF_TMP_PATH`
+ * while cargo compiles, and a parallel build interleaves the writes —
+ * definitions go missing, silently, and the generated file comes out short.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const CRATES = ['ream-events-napi', 'ream-http-napi', 'ream-scheduler-napi']
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const output = join('src', 'native', 'generated.ts')
+const scratch = mkdtempSync(join(tmpdir(), 'napi-types-'))
+
+try {
+  const lines = []
+  for (const crate of CRATES) {
+    const perCrate = join(scratch, `${crate}.jsonl`)
+    writeFileSync(perCrate, '')
+    execFileSync('cargo', ['build', '-p', crate], {
+      cwd: packageRoot,
+      env: { ...process.env, TYPE_DEF_TMP_PATH: perCrate },
+      stdio: ['ignore', 'ignore', 'inherit'],
+    })
+    const emitted = readFileSync(perCrate, 'utf8').split('\n').filter(Boolean)
+    if (emitted.length === 0) {
+      throw new Error(
+        `[napi-types] ${crate} emitted nothing — is napi-derive's "type-def" feature on?`,
+      )
+    }
+    lines.push(...emitted)
+  }
+
+  const combined = join(scratch, 'combined.jsonl')
+  writeFileSync(combined, `${lines.join('\n')}\n`)
+
+  execFileSync(
+    process.execPath,
+    [join('scripts', 'generate-napi-types.mjs'), combined, output],
+    { cwd: packageRoot, stdio: 'inherit' },
+  )
+
+  // Formatted here rather than excluded from the linter: the file is checked
+  // in, so it should read like the rest of the tree — and formatting it at
+  // generation means it never shows up as a diff someone has to fix by hand.
+  // Resolved through the package entry rather than `node_modules/.bin`, whose
+  // shim is a shell script the Windows runner cannot execute directly.
+  const biome = createRequire(import.meta.url).resolve('@biomejs/biome/bin/biome')
+  execFileSync(process.execPath, [biome, 'format', '--write', output], {
+    cwd: packageRoot,
+    stdio: ['ignore', 'ignore', 'inherit'],
+  })
+} finally {
+  rmSync(scratch, { recursive: true, force: true })
+}

package/scripts/generate-napi-types.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Generate the TypeScript surface of the native modules FROM the Rust.
+ *
+ * `napi-derive`'s `type-def` feature emits one JSON line per exported item
+ * while cargo compiles. Those lines are the source of truth: they are derived
+ * from the `#[napi]` items themselves, so a signature cannot drift from the
+ * Rust without this file changing.
+ *
+ * Hand-written interfaces are what we had before, and they DID drift — making
+ * `Bus::on_request` synchronous changed the Rust with nothing on the TypeScript
+ * side to notice.
+ *
+ * One thing napi-rs cannot infer: the shape of a `JsFunction` callback. It
+ * emits `(...args: any[]) => any`. Those few are refined below, by name, and
+ * the script fails if a refinement no longer matches anything — so the table
+ * cannot rot either.
+ *
+ *   TYPE_DEF_TMP_PATH=<file> cargo build -p <crates…>
+ *   node scripts/generate-napi-types.mjs <file> <out.d.ts>
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+
+/**
+ * Callback signatures napi-rs erases to `any`, restored here.
+ *
+ * Keyed by `<owner>.<method>`; the value replaces the whole parameter. Every
+ * entry must match, or the script fails: a stale refinement is how a hand
+ * annotation quietly stops describing the Rust.
+ */
+const CALLBACK_REFINEMENTS = {
+  'EventBus.subscribe': {
+    from: 'callback: (...args: any[]) => any',
+    to: 'callback: (eventJson: string) => void',
+  },
+  'EventBus.onRequest': {
+    from: 'callback: (...args: any[]) => any',
+    to: 'callback: (eventJson: string, reply: (response: string) => void) => void',
+  },
+  'HyperServer.onRequest': {
+    from: 'callback: (...args: any[]) => any',
+    to: 'callback: (request: string) => Promise<string> | string',
+  },
+  'HyperServer.onStreamDisconnect': {
+    from: 'callback: (...args: any[]) => any',
+    to: 'callback: (streamId: string) => void',
+  },
+  // The Rust hands over a serialised JsTaskPayload — `{ task_name,
+  // scheduled_for_ms }` renamed to camelCase by serde.
+  'RustScheduler.register': {
+    from: 'callback: (...args: any[]) => any',
+    to: 'callback: (invocation: { taskName: string; scheduledForMs: number }) => void',
+  },
+}
+
+const [input, output] = process.argv.slice(2)
+if (!input || !output) {
+  console.error('usage: generate-napi-types.mjs <type-def file> <out.d.ts>')
+  process.exit(2)
+}
+
+const entries = readFileSync(input, 'utf8')
+  .split('\n')
+  .map((l) => l.trim())
+  .filter(Boolean)
+  .map((l) => JSON.parse(l))
+
+const used = new Set()
+
+/** Apply the refinements that belong to `owner`, tracking which ones matched. */
+function refine(owner, body) {
+  let out = body
+  for (const [key, { from, to }] of Object.entries(CALLBACK_REFINEMENTS)) {
+    const [entryOwner] = key.split('.')
+    if (entryOwner !== owner) continue
+    if (out.includes(from)) {
+      out = out.replace(from, to)
+      used.add(key)
+    }
+  }
+  return out
+}
+
+/**
+ * JSDoc as emitted by napi-derive, indented to sit above its member.
+ *
+ * `*` followed by `/` inside the text closes the comment early — a Rust doc
+ * example holding a cron expression (`0 *​/5 * * *`) is enough to do it, and
+ * the generated file then fails to parse. Escaped rather than stripped, so the
+ * example still reads correctly.
+ */
+function docBlock(doc, indent = '') {
+  if (!doc) return ''
+  // Escape every `*/` EXCEPT the one that closes the block. A Rust doc example
+  // holding a cron expression (`0 */5 * * *`) closes the comment early
+  // otherwise, and the generated file stops parsing — but escaping the closer
+  // too breaks it just as thoroughly, whether the block spans one line or many.
+  const closer = doc.lastIndexOf('*/')
+  const escaped =
+    closer === -1
+      ? doc
+      : doc.slice(0, closer).replaceAll('*/', '*\\/') + doc.slice(closer)
+  return (
+    escaped
+      .split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => `${indent}${l}`)
+      .join('\n') + '\n'
+  )
+}
+
+const interfaces = entries.filter((e) => e.kind === 'interface')
+const structs = entries.filter((e) => e.kind === 'struct')
+const impls = new Map(entries.filter((e) => e.kind === 'impl').map((e) => [e.name, e]))
+const fns = entries.filter((e) => e.kind === 'fn')
+
+const out = [
+  '// GENERATED FROM THE RUST — do not edit.',
+  '//',
+  '// Produced by scripts/generate-napi-types.mjs from napi-derive\'s type-def',
+  '// output. Editing this file by hand puts it back where it started: a',
+  '// description that can disagree with the code it describes.',
+  '',
+]
+
+for (const iface of interfaces) {
+  out.push(docBlock(iface.js_doc))
+  out.push(`export interface ${iface.name} {`)
+  for (const line of iface.def.split('\n')) {
+    out.push(line ? `  ${line.trim()}` : '')
+  }
+  out.push('}', '')
+}
+
+for (const struct of structs) {
+  const impl = impls.get(struct.name)
+  out.push(docBlock(struct.js_doc))
+  out.push(`export declare class ${struct.name} {`)
+  if (impl) {
+    for (const line of refine(struct.name, impl.def).split('\n')) {
+      out.push(line ? `  ${line.trim()}` : '')
+    }
+  }
+  out.push('}', '')
+}
+
+for (const fn of fns) {
+  out.push(docBlock(fn.js_doc))
+  // napi-derive emits the whole declaration for a function, unlike a struct
+  // where `def` holds only the members.
+  const declaration = fn.def.trim()
+  out.push(
+    declaration.startsWith('export declare function')
+      ? `${declaration};`
+      : `export declare function ${fn.name}${declaration};`,
+    '',
+  )
+}
+
+const stale = Object.keys(CALLBACK_REFINEMENTS).filter((k) => !used.has(k))
+if (stale.length > 0) {
+  console.error(
+    `[napi-types] refinement(s) that matched nothing: ${stale.join(', ')}\n` +
+      '[napi-types] the Rust changed under them — update or remove the entry.',
+  )
+  process.exit(1)
+}
+
+writeFileSync(output, out.join('\n'))
+console.log(`[napi-types] ${output} — ${interfaces.length} interface(s), ${structs.length} class(es), ${fns.length} function(s)`)