@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 +32 -1
- package/package.json +2 -2
- package/skills/orbit-framework/SKILL.md +289 -0
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,
|
|
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.
|
|
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.
|
|
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`
|