@galaxy-stack/blackhole-cli 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -51,7 +51,14 @@ npm run dev -- web doctor
51
51
  `blackhole web` boots the Galaxy Blackhole web GUI with the overlay in `web/`:
52
52
  patches under `web/patches` add the Galaxy route/UI, and the client
53
53
  package in `web/brand` supplies the Galaxy Blackhole brand, Vietnamese locale,
54
- key dialog, and reasoning-effort control. The Galaxy key comes from
54
+ key dialog, session tools (delete from the session header or from the sidebar row
55
+ menu, with a trash copy and a checkpointed tombstone), the **Journey** panel (an
56
+ n8n-style canvas over `<workspace>/journey.json` that the agent edits in the same
57
+ file, with a run engine whose `journey_get`/`journey_set`/`journey_run` tools and
58
+ `/journey` command share one validator and one revision rule), a feedback entry that mails a remark to the Galaxy
59
+ maintainer, and reasoning-effort control. The bundled patch also disables the
60
+ stock OpenTelemetry feedback upload, so a remark never leaves the machine unless
61
+ you send it yourself. The Galaxy key comes from
55
62
  `GBH_GALAXY_API_KEY` or the DSH credential store `~/.galaxy/gbh/.credentials.yaml`
56
63
  (written by the in-app dialog). `blackhole web --help` lists its flags.
57
64
 
@@ -150,6 +157,30 @@ Every command writes JSON lines to `<state-dir>/logs/cli-<date>.ndjson` (0600, r
150
157
 
151
158
  Session history resumes with `--session`; simultaneous writers to the same session are rejected. This restores user/final-answer text; the detailed thinking/tool timeline currently lasts for the open TUI session. It does not resume a paused runtime checkpoint. Runtime checkpoints remain in the host store; crash-resume for production CLI is a future extension. Lab checkpoint/crash-resume testing remains available in core/testing.
152
159
 
160
+ ## End-to-end verification
161
+
162
+ `blackhole flow <file.json>` runs the prompts of a flow sequentially in one session and
163
+ one workspace, which is how this release was verified: the 25-prompt
164
+ [flows/gymflow.json](flows/gymflow.json) flow (Orbit backend plus a React/Vite/Galaxy UI
165
+ frontend) completed every step on `@galaxy-stack/ai-coder-core@0.3.0`. The failures found
166
+ along the way, with their evidence and root causes, are journalled in
167
+ [docs/TEST_FAILURE_ANALYSIS.md](docs/TEST_FAILURE_ANALYSIS.md).
168
+
169
+ - Every step streams to `step-NN-<id>.ndjson` as it happens, plus a compact
170
+ `progress.log` (bounded, secret-free tool arguments), so a multi-hour run can be tailed
171
+ and diagnosed without waiting for the step to end.
172
+ - `scripts/e2e-report.mjs <run-root>` summarises a run and flags what a passing step can
173
+ hide: a step that never called its expected tool, component-library files written with
174
+ no scaffold call, a whole-project check run through the shell, long-running servers in a
175
+ headless run, evidence ordered after the last write, duplicate calls inside one turn.
176
+ - `--flow-from <step-id>` and `--flow-until <step-id>` resume or bound a run in the same
177
+ session, workspace and state; `--flow-step-retries <n>` retries a step that hit a
178
+ transport outage or the host deadline before calling it failed. The report is written
179
+ even when the run dies and records `fatal`, `resumedFrom`, `stoppedAfter`,
180
+ `skippedSteps` and `retriedSteps`, so a crash can never read as a pass.
181
+ - `--max-turns <n>` and `--run-minutes <n>` raise the per-run budget (48 model turns and
182
+ 15 minutes by default) for steps that legitimately need more.
183
+
153
184
  ## Testing and migration
154
185
 
155
186
  ```sh
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@galaxy-stack/blackhole-cli",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "private": false,
5
5
  "description": "Galaxy Code CLI and terminal UI for the Galaxy agent runtime",
6
6
  "license": "MIT",
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "dependencies": {
30
30
  "@assistant-ui/react-ink": "^0.0.44",
31
- "@galaxy-stack/ai-coder-core": "0.3.0",
31
+ "@galaxy-stack/ai-coder-core": "0.3.1",
32
32
  "@modelcontextprotocol/sdk": "^1.30.1",
33
33
  "ink": "7.1.1",
34
34
  "react": "^19.3.0",
@@ -26,6 +26,295 @@ Orbit is a NestJS-style backend framework for Bun. Concept mapping from NestJS:
26
26
  5. Validate all external input with Zod schemas through ValidationPipe.
27
27
  6. Tests run with `bun test`; e2e tests boot a real HTTP server: `OrbitFactory.create(AppModule, { port: 0 })` → `app.listen(0)` → `fetch(\`http://127.0.0.1:${app.port}/…\`)` — `OrbitApplication` has no public `handle()`.
28
28
 
29
+ ## API map (what each package exports)
30
+
31
+ This map is the surface agents used to re-derive by opening `node_modules/**/*.d.ts`.
32
+ Read it first; if something is missing here, say so in the final report instead of
33
+ silently re-reading declarations.
34
+
35
+ **`@galaxy-stack/orbit-core`**
36
+ - App: `OrbitFactory.create(AppModule, options?)` → `OrbitApplication` (`app.listen()`,
37
+ `app.port`). `OrbitApplicationOptions`: `port`, `hostname`, `logger`, `cors`,
38
+ `security` (secure response headers **on by default**; `false` disables).
39
+ Aliases `BunFactory`/`GalaxyFactory`.
40
+ - DI/modules: `Module`, `Injectable`, `Inject`, `Optional`, `forwardRef`, `Container`,
41
+ `Scope`, provider shapes (`ClassProvider`, `ValueProvider`, `FactoryProvider`).
42
+ - Controllers: `Controller`, `Get|Post|Put|Patch|Delete|Head|Options|All`, `HttpMethod`.
43
+ - Versioning: `versioningManager.configure({ type: 'uri'|'header'|'media'|'custom', … })`,
44
+ `Version`, `VERSION_NEUTRAL`. There is no `app.setGlobalPrefix`.
45
+ - Config: `ConfigModule`, `registerAs`, `ConfigService`, tokens `CONFIG_OPTIONS`,
46
+ `CONFIGURATION_TOKEN`, `CONFIGURATION_SERVICE_TOKEN`.
47
+ - Cluster/telemetry: `ClusterManager`, `isPrimaryProcess`, `isWorkerProcess`,
48
+ `notifyReady`, `onShutdown`; `onRequestTelemetry`, `emitRequestTelemetry`.
49
+
50
+ **`@galaxy-stack/orbit-common`**
51
+ - Parameters: `Body`, `Query`, `Param`, `Headers`, `Req`/`Request`, `Res`/`Response`,
52
+ `Ip`, `Session`, `UploadedFile`, `UploadedFiles`.
53
+ - Guards/pipes/interceptors/filters: `UseGuards`, `UsePipes`, `UseInterceptors`,
54
+ `CanActivate`, `PipeTransform`, `CallHandler`, `OrbitInterceptor`, `Catch`,
55
+ `UseFilters`, `ExceptionFilter`, `ArgumentsHost`.
56
+ - Response: `HttpCode`, `Header`, `Redirect`, `Render`.
57
+ - Transforms: `Transform`, `ToInt`, `ToFloat`, `ToBoolean`, `ToDate`, `ToLowerCase`,
58
+ `ToUpperCase`, `Trim`, `ToArray`, `DefaultValue`.
59
+ - Exceptions: `HttpException` plus `BadRequest|Unauthorized|Forbidden|NotFound|
60
+ MethodNotAllowed|NotAcceptable|Conflict|Gone|PayloadTooLarge|UnsupportedMediaType|
61
+ UnprocessableEntity|InternalServerError|NotImplemented|BadGateway|ServiceUnavailable|
62
+ GatewayTimeout` + `Exception`.
63
+ - Secure headers: `buildSecureHeaders`, `applySecureHeaderRecord`, `withSecureHeaders`.
64
+
65
+ **`@galaxy-stack/orbit-database`**
66
+ - `DatabaseModule.forRoot({ type: 'sqlite'|'postgres'|'mysql'|'libsql'|'mongodb', url?, host?,
67
+ port?, database?, pool?, logging?, isGlobal? })`, `forRootAsync({ useFactory, inject,
68
+ imports, isGlobal })`, and `forFeature(entities, tableMapping: Map<entity, table>)` —
69
+ note the second argument.
70
+ - Decorators: `Entity(options|'table')`, `Column(options)`, `PrimaryKey`,
71
+ `PrimaryGeneratedColumn('increment'|'uuid')`, `InjectRepository(Entity)`, `Transactional`.
72
+ - Data source: `createDataSource(options)` / `BunDataSource`; tokens `DATABASE_OPTIONS`,
73
+ `DATA_SOURCE`.
74
+ - Repositories: extend `BaseRepository<T>` (or `DrizzleRepository`) and provide
75
+ `db`/`table`; implement `findAll/findOne(id)/findBy(where)/create/update(id, patch)/
76
+ delete(id)`; helpers `getTableName/getPrimaryKey/getColumns`.
77
+
78
+ **`@galaxy-stack/orbit-security`**
79
+ - `SecurityModule.forRoot({ helmet?, csrf?, isGlobal? })` / `forRootAsync({ useFactory,
80
+ inject, imports, isGlobal })`; tokens `HELMET_MIDDLEWARE`, `CSRF_MIDDLEWARE`,
81
+ `CRYPTO_UTILS`, `SECURITY_MODULE_OPTIONS`.
82
+ - Rate limiting: `rateLimit(options?)` (sliding window), `tokenBucket(options?)`.
83
+ - Sanitizing: `escapeHtml`, `sanitizeHtml`, `detectSqlInjection`, `detectXss`,
84
+ `sanitizeString`, `sanitizeObject`, `SanitizationPipe`, `XssPipe`, `SqlInjectionPipe`.
85
+ - API keys: `ApiKeyManager`, `createApiKeyManager({ prefix, length, charset, expiresIn,
86
+ hashAlgorithm })`, `ApiKeyRotationScheduler`. Crypto helpers: `CryptoUtils`.
87
+
88
+ **`@galaxy-stack/orbit-throttler`**
89
+ - `ThrottlerModule.forRoot(options)` / `forRootAsync`; tokens `THROTTLER_OPTIONS`,
90
+ `THROTTLER_GUARD`, `THROTTLER_STORAGE`; `ThrottlerGuard` rejects with
91
+ `ThrottlerException`; storage `ThrottlerMemoryStorage` / `ThrottlerRedisStorage`;
92
+ decorators `Throttle(limit, ttl)` and `SkipThrottle(skip?)`.
93
+
94
+ ### Request pipeline contracts (guards, pipes, interceptors, filters)
95
+
96
+ These are the exact interfaces the pipeline passes around (from
97
+ `orbit-core/dist/pipeline/execution-pipeline.d.ts`, re-exported by `orbit-common`):
98
+
99
+ ```ts
100
+ interface ExecutionContext {
101
+ getRequest<T = any>(): T;
102
+ getResponse<T = any>(): T;
103
+ getHandler(): Function;
104
+ getClass(): Type;
105
+ switchToHttp(): HttpArgumentsHost; // { getRequest<T>(): T; getResponse<T>(): T }
106
+ }
107
+ interface CanActivate { canActivate(context: ExecutionContext): boolean | Promise<boolean>; }
108
+ interface PipeTransform<T = any, R = any> { transform(value: T, metadata: ArgumentMetadata): R | Promise<R>; }
109
+ interface CallHandler<T = any> { handle(): Promise<T>; }
110
+ interface GalaxyInterceptor<T = any, R = any> { intercept(context: ExecutionContext, next: CallHandler<T>): Promise<R> | R; }
111
+ interface ExceptionFilter<T = any> { catch(exception: T, context: ExecutionContext): any; }
112
+ interface ArgumentMetadata { type: 'body' | 'query' | 'param' | 'custom'; metatype?: Type; data?: string; }
113
+ ```
114
+
115
+ - The pipeline hands an **`ExecutionContext`** to guards, interceptors and filters — not a
116
+ Nest `ArgumentsHost`. There is **no `getArgs()`, `getArgByIndex()` or `switchToRpc()`**; read the
117
+ request/response with `context.getRequest()` / `context.getResponse()` (or
118
+ `context.switchToHttp().getResponse()`), and the handler/class with `getHandler()` / `getClass()`.
119
+ - A filter's `catch(exception, context)` **returns whatever becomes the response** (status/body are
120
+ derived from what you return, e.g. `new Response(JSON.stringify({ error }), { status: 429 })` for a
121
+ `ThrottlerException`).
122
+ - Registration: `@UseGuards/@UsePipes/@UseInterceptors/@UseFilters` on the handler or controller, or
123
+ provider-level classes; `ExecutionPipeline` resolves them per controller and caches the metadata.
124
+
125
+ ### Installing and wiring the database layer
126
+
127
+ `orbit new` does **not** install a database layer. When a task needs one, add both
128
+ packages — `drizzle-orm` is a **peer dependency** (>=0.29) of `orbit-database@0.1.x` and
129
+ nothing works without it:
130
+
131
+ ```sh
132
+ bun add @galaxy-stack/orbit-database drizzle-orm
133
+ ```
134
+
135
+ Two legitimate shapes:
136
+
137
+ - **orbit-database + Drizzle** — `@Entity`/`@Column`, `DatabaseModule.forRoot/forFeature`,
138
+ `DrizzleRepository`, `@Transactional`.
139
+ - **Plain `bun:sqlite`** — `import { Database } from 'bun:sqlite'` behind a token provider
140
+ plus SQL migrations; no peer dependency. Pick one deliberately and say which in the report.
141
+
142
+ Complete orbit-database wiring, matching the declarations:
143
+
144
+ ```ts
145
+ // tables.ts — Drizzle tables come from drizzle-orm; the entity decorators point at them
146
+ import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';
147
+ export const membersTable = sqliteTable('members', {
148
+ id: integer('id').primaryKey({ autoIncrement: true }),
149
+ name: text('name').notNull(),
150
+ });
151
+
152
+ // member.entity.ts
153
+ @Entity('members')
154
+ export class Member {
155
+ @PrimaryGeneratedColumn('increment') id!: number;
156
+ @Column() name!: string;
157
+ }
158
+
159
+ // members.module.ts
160
+ @Module({
161
+ imports: [DatabaseModule.forFeature([Member], new Map([[Member, membersTable]]))],
162
+ controllers: [MembersController],
163
+ providers: [
164
+ MembersService,
165
+ { provide: MemberRepository, useFactory: (db: any) => new MemberRepository(db, membersTable), inject: [DATA_SOURCE] },
166
+ ],
167
+ })
168
+ export class MembersModule {}
169
+
170
+ // member.repository.ts — DrizzleRepository(db, table, entityClass)
171
+ export class MemberRepository extends DrizzleRepository<Member> {
172
+ constructor(db: any, table: any) { super(db, table, Member); }
173
+ }
174
+ ```
175
+
176
+ App module: `DatabaseModule.forRoot({ type: 'sqlite', database: './app.db' })` (`database`, not
177
+ `url`, for SQLite; `:memory:` works for tests).
178
+
179
+ ### Compiled against
180
+
181
+ This map was compiled from the declarations of the versions these projects install:
182
+ orbit-core@0.2.3, orbit-common@0.1.15, orbit-database@0.1.10, orbit-security@0.1.10,
183
+ orbit-throttler@0.1.10. `read_file` on a package's `package.json` is still how the
184
+ installed version is confirmed; if it differs from that list, trust the installed
185
+ declarations for the delta and say so in the final report instead of re-reading
186
+ everything.
187
+
188
+ ### Rate limiting and throttling recipes
189
+
190
+ - App-level limiter (no guard): `const limiter = rateLimit({ windowMs: 60_000, maxRequests: 100 })`
191
+ then mount `limiter.createMiddleware()` through the middleware machinery
192
+ (`consumer.apply(limiter.createMiddleware()).forRoutes('*')` or `app.use(...)`).
193
+ `SlidingWindowRateLimiter` exposes `increment(key): boolean`, `getInfo(key)`, `reset(key)`,
194
+ `destroy()`; `tokenBucket()` returns a `TokenBucketRateLimiter` with `consume(key, tokens?)`.
195
+ - Route-level throttling: `ThrottlerModule.forRoot({ ttl: 60, limit: 100 })` (`ttl` and `limit`
196
+ are required) plus `@UseGuards(ThrottlerGuard)` on the controller and `@Throttle(limit, ttl)` /
197
+ `@SkipThrottle()` per handler.
198
+ - `ThrottlerGuard` rejects with `ThrottlerException`, a plain `Error`: add a
199
+ `@Catch(ThrottlerException)` filter that returns **429**, or the client sees a 500.
200
+ - Custom throttler storage implements `ThrottlerStorage { increment(key, ttl), get(key), reset(key) }`;
201
+ memory storage is the default and `ThrottlerRedisStorage` targets Redis.
202
+
203
+ ### Signatures agents used to need a `.d.ts` read for
204
+
205
+ - Exceptions (`orbit-common`): `new BadRequestException(message?: string | Record<string, unknown>)`
206
+ and the same shape for the other `*Exception` subclasses; base `HttpException(response, status)`.
207
+ - Validation: `ValidationPipe` and `ZodValidationPipe` implement `PipeTransform`; a custom pipe
208
+ receives `ArgumentMetadata = { type: 'body' | 'query' | 'param' | 'custom', metatype?: Type, data?: string }`.
209
+ - Parameter decorators (`orbit-common/decorators/params.decorator`): `@Body()`, `@Query('key'?)`,
210
+ `@Param('key'?)`, `@Headers('key'?)`, `@Req()`/`@Res()`, `@Ip()`, `@Session()`,
211
+ `@UploadedFile()`/`@UploadedFiles()`; metadata via `getParamMetadata`.
212
+ - Transforms: `Transform(fn, { toClassOnly?, toPlainOnly?, groups? })`, `ToInt()`, `ToFloat()`,
213
+ `ToBoolean()`, `ToDate()`, `Trim()`, `ToArray()`, `DefaultValue(value)`, `ToLowerCase()`, `ToUpperCase()`.
214
+ - Security: `SecurityModule.forRoot({ helmet?: HelmetOptions | false, csrf?: CsrfOptions | false, isGlobal? })`;
215
+ `CsrfOptions = { cookie?, ignoreMethods?, getToken?, sessionKey? }` — give `getToken(req)` when API
216
+ clients cannot carry cookies; `HelmetOptions.contentSecurityPolicy` and `crossOriginEmbedderPolicy`
217
+ accept `boolean | options`.
218
+ - Rate limiting: `rateLimit({ windowMs?, maxRequests?, keyGenerator?, message?, statusCode?, headers?,
219
+ skipFailedRequests?, skipSuccessfulRequests?, onLimitReached? })`; `tokenBucket(...)` takes the same
220
+ options with burst semantics.
221
+ - Throttler: `ThrottlerModule.forRoot({ ttl, limit, ignoreUserAgents?, skipIf?, getTracker? })` — `ttl` and
222
+ `limit` are **required**; `Throttle(limit, ttl)`, `SkipThrottle(skip?)`, `ThrottleOptions = { limit?, ttl? }`;
223
+ storage record `{ totalHits, expiresAt, isBlocked, timeToExpire }`; `ThrottlerGuard` rejects with
224
+ `ThrottlerException`, which is a plain `Error` — map it to **429** with a `@Catch(ThrottlerException)`
225
+ filter or the client sees a 500.
226
+ ### Database wiring — the concrete pattern (this is why `orbit-database` was read 7× per step)
227
+
228
+ - SQLite lives in `database`, not `url`: `DatabaseModule.forRoot({ type: 'sqlite', database: './app.db' })`
229
+ (`':memory:'` is accepted). `url` is for postgres/mysql/libsql/mongodb.
230
+ - Feature module: `DatabaseModule.forFeature([Member], new Map([[Member, 'members']]))` — entities
231
+ plus the entity→table map; the second argument is required.
232
+ - Entities: `@Entity('members')`, `@PrimaryGeneratedColumn('increment' | 'uuid')`, `@Column({ nullable?: boolean, ... })`.
233
+ - Repositories: prefer the concrete `DrizzleRepository<T>` — `new DrizzleRepository(db, table, Member)` —
234
+ over hand-implementing `BaseRepository<T>`. The base declares `findAll()`, `findOne(id)`,
235
+ `findBy(where)`, `create(entity)`, `update(id, patch)`, `delete(id)` **and `count(where?)`** as abstract;
236
+ `DrizzleRepository` also exposes `getQueryBuilder()`, `getRawDb()` and `getTable()`.
237
+ - Transactions: `@Transactional()` on a service method wraps the repository calls inside it.
238
+ - Data source: `createDataSource(options)` / `BunDataSource`; inject it with the `DATA_SOURCE` token
239
+ when you need the raw handle instead of a repository.
240
+ ### Security and throttling wiring — trust the declarations, not the package READMEs
241
+
242
+ Two shipped READMEs contradict their own exported types (verified against the installed
243
+ `orbit-security` / `orbit-throttler` on 2026-09-29), which is what made agent runs read both the
244
+ README and the declarations and still stay unsure:
245
+
246
+ - `orbit-security/README.md` shows `csrf: { enabled, tokenKey, cookieName }`, but `CsrfOptions` is
247
+ `{ cookie?: { name?, path?, httpOnly?, secure?, sameSite?, maxAge? }, ignoreMethods?, getToken?, sessionKey? }`.
248
+ There is no `enabled` flag — omit `csrf` to disable it — and the cookie name lives in `cookie.name`.
249
+ Use `getToken(req)` when API clients cannot carry cookies.
250
+ - `orbit-throttler/README.md` shows `new RedisThrottlerStorage(...)` (the class is `ThrottlerRedisStorage`)
251
+ and a `throttlers: [...]` list, but `ThrottlerModuleOptions` extends `ThrottlerOptions` with only
252
+ `storage?` and `errorMessage?`, and `ttl`/`limit` are required. Custom storage implements
253
+ `ThrottlerStorage { increment(key, ttl), get(key), reset(key) }`.
254
+
255
+ ```ts
256
+ @Module({
257
+ imports: [
258
+ SecurityModule.forRoot({
259
+ helmet: { contentSecurityPolicy: { directives: { defaultSrc: ["'self'"] } }, frameguard: { action: 'deny' } },
260
+ csrf: { cookie: { name: 'XSRF-TOKEN', httpOnly: true, sameSite: 'lax' }, ignoreMethods: ['GET', 'HEAD'] },
261
+ }),
262
+ ThrottlerModule.forRoot({ ttl: 60, limit: 100, storage: new ThrottlerMemoryStorage() }),
263
+ ],
264
+ })
265
+ export class AppModule {}
266
+
267
+ export class ApiKeyGuard implements CanActivate {
268
+ canActivate(context: any): boolean | Promise<boolean> { /* read the header, compare, throw UnauthorizedException */ }
269
+ }
270
+
271
+ @Catch(ThrottlerException)
272
+ export class ThrottleFilter implements ExceptionFilter<ThrottlerException> {
273
+ catch(exception: ThrottlerException, host: ArgumentsHost) { /* respond 429 */ }
274
+ }
275
+ ```
276
+
277
+ - Guards: `@UseGuards(ApiKeyGuard)` (class or instance); `CanActivate.canActivate(context)` returns
278
+ `boolean | Promise<boolean>`; filters: `@UseFilters(ThrottleFilter)` with `ExceptionFilter.catch`.
279
+ Mapping `ThrottlerException` (a plain `Error`) to 429 needs exactly this filter, otherwise the
280
+ client sees a 500.
281
+ - Middleware: a module class implements `configure(consumer: MiddlewareConsumer)`; then
282
+ `consumer.apply(HelmetMiddleware).forRoutes('*')`, narrowed with `.exclude(...)`.
283
+ `RouteInfoOrController = string | { path, method? } | Type | (...)`.
284
+ ### Middleware, CORS and static serving
285
+
286
+ - A module registers middleware by implementing `NestModule`:
287
+ `configure(consumer: MiddlewareConsumer): void | Promise<void>` then
288
+ `consumer.apply(HelmetMiddleware).forRoutes('*')`, narrowed with `.exclude(...)`. `apply` accepts
289
+ `Middleware = MiddlewareFunction | MiddlewareClass | GalaxyMiddleware`.
290
+ - A middleware class implements `GalaxyMiddleware` (alias `OrbitMiddleware`):
291
+ `use(request: Request, next: () => Promise<Response>): Promise<Response>`; a plain function of the
292
+ same shape works too.
293
+ - `CorsOptions = { origin?: string | string[] | boolean | ((origin: string) => boolean), methods?,
294
+ allowedHeaders?, exposedHeaders?, credentials?, maxAge?, preflightContinue?, optionsSuccessStatus? }`,
295
+ passed through `OrbitFactory.create(AppModule, { cors: { ... } })` (`cors: true` uses defaults).
296
+ - `StaticServeOptions = { root, prefix?, index?, dotFiles?: 'allow' | 'deny' | 'ignore', maxAge?,
297
+ immutable?, etag?, lastModified?, cacheMaxSize?, cacheTtl?, cacheDebug? }`.
298
+ ### Application API and global registration
299
+
300
+ `OrbitApplication` (returned by `OrbitFactory.create`) exposes exactly this public surface:
301
+ `use(middleware, { forRoutes?, exclude? })`, `enableCors(options?: CorsOptions)`,
302
+ `useStaticAssets(options: Partial<StaticServeOptions>)`, `listen(port?)`, `close(signal?)`,
303
+ `enableShutdownHooks()`, `onShutdown(callback)`, `getContainer()`, `getServer()`, `getRoutes()`,
304
+ `setRoutes()`, `setModules()`, `setMiddlewareConfigurations()`.
305
+
306
+ There is **no** `useGlobalPipes`, `useGlobalGuards` or `useGlobalFilters` — do not go looking for one.
307
+ Apply `@UsePipes` / `@UseGuards` / `@UseFilters` on the controller (or a shared base controller),
308
+ or register the pipe/guard/filter class in the module's `providers`. CORS and static assets are
309
+ app-level calls (`enableCors`, `useStaticAssets`) rather than module imports.
310
+ **Versions, not APIs.** To confirm which version is installed, `read_file` on that
311
+ package's `package.json` is allowed and cheap. The map above was compiled from the installed
312
+ declarations of orbit-core, orbit-common, orbit-database, orbit-security and orbit-throttler,
313
+ plus the application surface — treat it as ground truth rather than re-reading `node_modules/**/*.d.ts`
314
+ to double-check it. Reading a package's `index.d.ts` should be unnecessary now. If a signature looks
315
+ wrong or is missing, note it in the final report (one line) so the map can be corrected; that is
316
+ cheaper and more useful than re-deriving the declarations on every run.
317
+
29
318
  ## Validation (Zod)
30
319
 
31
320
  `@galaxy-stack/orbit-validation` re-exports the pipe types that `orbit-core`