@galaxy-stack/blackhole-cli 2.0.0-alpha.9 → 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.
Files changed (64) hide show
  1. package/README.md +74 -3
  2. package/dist/application.d.ts +42 -0
  3. package/dist/application.d.ts.map +1 -1
  4. package/dist/application.js +113 -8
  5. package/dist/application.js.map +1 -1
  6. package/dist/cli-meta.d.ts +15 -0
  7. package/dist/cli-meta.d.ts.map +1 -0
  8. package/dist/cli-meta.js +37 -0
  9. package/dist/cli-meta.js.map +1 -0
  10. package/dist/cli.js +14 -2
  11. package/dist/cli.js.map +1 -1
  12. package/dist/commands.d.ts +13 -0
  13. package/dist/commands.d.ts.map +1 -0
  14. package/dist/commands.js +40 -0
  15. package/dist/commands.js.map +1 -0
  16. package/dist/composer.d.ts +3 -1
  17. package/dist/composer.d.ts.map +1 -1
  18. package/dist/composer.js +15 -3
  19. package/dist/composer.js.map +1 -1
  20. package/dist/file-index.d.ts +20 -0
  21. package/dist/file-index.d.ts.map +1 -0
  22. package/dist/file-index.js +60 -0
  23. package/dist/file-index.js.map +1 -0
  24. package/dist/flow.d.ts +30 -0
  25. package/dist/flow.d.ts.map +1 -1
  26. package/dist/flow.js +172 -28
  27. package/dist/flow.js.map +1 -1
  28. package/dist/manual-config.d.ts +28 -0
  29. package/dist/manual-config.d.ts.map +1 -0
  30. package/dist/manual-config.js +67 -0
  31. package/dist/manual-config.js.map +1 -0
  32. package/dist/options.d.ts +10 -2
  33. package/dist/options.d.ts.map +1 -1
  34. package/dist/options.js +46 -7
  35. package/dist/options.js.map +1 -1
  36. package/dist/provider-display.d.ts +20 -0
  37. package/dist/provider-display.d.ts.map +1 -0
  38. package/dist/provider-display.js +26 -0
  39. package/dist/provider-display.js.map +1 -0
  40. package/dist/thinking-policy.d.ts +53 -0
  41. package/dist/thinking-policy.d.ts.map +1 -0
  42. package/dist/thinking-policy.js +135 -0
  43. package/dist/thinking-policy.js.map +1 -0
  44. package/dist/timeline.d.ts +52 -5
  45. package/dist/timeline.d.ts.map +1 -1
  46. package/dist/timeline.js +362 -32
  47. package/dist/timeline.js.map +1 -1
  48. package/dist/tui.d.ts +3 -1
  49. package/dist/tui.d.ts.map +1 -1
  50. package/dist/tui.js +353 -13
  51. package/dist/tui.js.map +1 -1
  52. package/dist/web/options.js +2 -2
  53. package/dist/web/options.js.map +1 -1
  54. package/package.json +2 -2
  55. package/skills/galaxy-ui/SKILL.md +13 -0
  56. package/skills/orbit-framework/SKILL.md +398 -4
  57. package/web/brand/client.template.js +184 -0
  58. package/web/brand/lib/client.js +212 -2
  59. package/web/brand/lib/index.d.ts +3 -0
  60. package/web/brand/lib/index.js +202 -0
  61. package/web/brand/lib/session-store.d.ts +54 -0
  62. package/web/brand/lib/session-store.js +288 -0
  63. package/web/brand/vi.locales.json +28 -2
  64. package/web/patches/gbh-brand.patch.yml +1 -1
@@ -18,13 +18,362 @@ Orbit is a NestJS-style backend framework for Bun. Concept mapping from NestJS:
18
18
  ## Project rules
19
19
 
20
20
  1. Runtime is Bun. Use `bun` instead of `node`/`npm`/`pnpm` for all commands:
21
- `bun install`, `bun run dev`, `bun test`.
21
+ `bun install`, `bun run dev` (a developer server for a human, never a check),
22
+ `bun test`.
22
23
  2. Entry point: `OrbitFactory.create(AppModule)` then `app.listen(3000)`.
23
24
  3. Every feature is a `@Module({ controllers, providers, exports })` class.
24
25
  4. Providers are `@Injectable()` classes injected via constructor.
25
26
  5. Validate all external input with Zod schemas through ValidationPipe.
26
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()`.
27
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
+
318
+ ## Validation (Zod)
319
+
320
+ `@galaxy-stack/orbit-validation` re-exports the pipe types that `orbit-core`
321
+ already ships. Zod v4 is what the CLI installs, and both pipes accept v4 and v3
322
+ error shapes.
323
+
324
+ - Simple single-parameter handler — bind the schema to the pipe:
325
+
326
+ ```ts
327
+ import { Controller, Post, ZodValidationPipe } from '@galaxy-stack/orbit-core';
328
+ import { Body, UsePipes } from '@galaxy-stack/orbit-common';
329
+ import { z } from 'zod';
330
+
331
+ const CreateMemberSchema = z.object({ name: z.string().min(2), email: z.string().email() });
332
+
333
+ @Controller('members')
334
+ export class MembersController {
335
+ @Post()
336
+ @UsePipes(new ZodValidationPipe(CreateMemberSchema))
337
+ create(@Body() dto: z.infer<typeof CreateMemberSchema>) { return this.members.create(dto); }
338
+ }
339
+ ```
340
+
341
+ - **Do not** write `@Body(new ZodValidationPipe(...))`: `@Body` only accepts a
342
+ field name (`@Body('name')`), not a pipe.
343
+ - `@UsePipes` is **method/class level** and runs for every argument of the
344
+ method. When a handler mixes a validated body with `@Param`/`@Query` strings,
345
+ write one small scoped pipe that checks `metadata.type`:
346
+
347
+ ```ts
348
+ import { BadRequestException, type PipeTransform } from '@galaxy-stack/orbit-core';
349
+ import { type ArgumentMetadata } from '@galaxy-stack/orbit-common';
350
+
351
+ class BodyOnlyPipe implements PipeTransform {
352
+ constructor(private readonly schema: { safeParse(v: unknown): any }) {}
353
+ transform(value: unknown, metadata: ArgumentMetadata) {
354
+ if (metadata.type !== 'body') return value; // leave params alone
355
+ const result = this.schema.safeParse(value);
356
+ if (!result.success) {
357
+ const issues = result.error?.issues ?? result.error?.errors ?? [];
358
+ throw new BadRequestException('Validation failed: ' +
359
+ issues.map((i: any) => `${i.path?.join('.') || 'value'}: ${i.message}`).join('; '));
360
+ }
361
+ return result.data;
362
+ }
363
+ }
364
+ ```
365
+
366
+ - `createZodDto(schema)` + a class-level `ValidationPipe` is **not reliable on
367
+ Bun**: it reads the parameter metatype from `design:paramtypes`, which Bun's
368
+ transpiler does not emit, so validation silently does not run. Prefer
369
+ `ZodValidationPipe` (or the scoped pipe above).
370
+ - Validation errors surface as `400 Bad Request`; unknown ids use
371
+ `NotFoundException` for `404`.
372
+
373
+ ## Editing files
374
+
375
+ Use `edit_file` with a unique `oldText`/`newText` pair; add surrounding lines when the match is ambiguous. The edit precondition hash is optional — omit it and rely on the oldText match. Never reuse a content hash from an earlier turn or from compacted context; re-read the file if you need its current state.
376
+
28
377
  ## Scaffolding and dependency wiring
29
378
 
30
379
  Use the Orbit CLI; do not hand-wire modules or add framework packages manually:
@@ -60,7 +409,8 @@ export class UserModule {}
60
409
  ## Controller template
61
410
 
62
411
  ```ts
63
- import { Controller, Get, Post, Body, Param, HttpCode, UseGuards } from '@galaxy-stack/orbit-core';
412
+ import { Controller, Get, Post } from '@galaxy-stack/orbit-core';
413
+ import { Body, Param, HttpCode, UseGuards } from '@galaxy-stack/orbit-common';
64
414
 
65
415
  @Controller('users')
66
416
  export class UserController {
@@ -76,6 +426,44 @@ export class UserController {
76
426
  }
77
427
  ```
78
428
 
429
+ > **Import sources matter.** Route/method decorators (`Controller`, `Get`, `Post`,
430
+ > `Put`, `Patch`, `Delete`, `Module`, `Injectable`) and the app factory
431
+ > (`OrbitFactory`) come from `@galaxy-stack/orbit-core`. Parameter decorators
432
+ > (`Body`, `Param`, `Query`, `Headers`, `Req`, `Res`), method decorators
433
+ > (`HttpCode`, `Header`, `UsePipes`, `UseGuards`, `UseInterceptors`, `Catch`) and
434
+ > the `Transform`/`ToInt`/`Trim` helpers come from `@galaxy-stack/orbit-common`.
435
+ > Importing a `Body`/`Param` from `orbit-core` throws
436
+ > `Export named 'Body' not found` at runtime.
437
+
438
+ ## Route prefixing and versioning
439
+
440
+ - A route prefix belongs to the controller path: `@Controller('api/v1/members')`.
441
+ Orbit has **no** `app.setGlobalPrefix(...)` — that API is NestJS, not Orbit.
442
+ Do not search `node_modules` for it; a missing global-prefix helper means the
443
+ prefix goes on each controller (or on a shared base path constant).
444
+ - Versioned APIs use the built-in manager, exported from `@galaxy-stack/orbit-core`
445
+ (root entry re-exports `./versioning/versioning`):
446
+
447
+ ```ts
448
+ import { Version, VERSION_NEUTRAL, versioningManager } from '@galaxy-stack/orbit-core';
449
+
450
+ // once at bootstrap, before app.listen()
451
+ versioningManager.configure({ type: 'uri', defaultVersion: '1', prefix: 'v' });
452
+
453
+ @Controller('members')
454
+ export class MemberController {
455
+ @Get() @Version('1') list() {}
456
+ @Get('health') @Version(VERSION_NEUTRAL) health() {}
457
+ }
458
+ ```
459
+
460
+ `type` is `'uri' | 'header' | 'media' | 'custom'`; `prefix: false` turns the URI
461
+ segment off; `header`/`key`/`extractor` tune the non-URI strategies.
462
+ - Checking the installed API version: `read_file` on a specific
463
+ `package.json`, `README.md` or `*.d.ts` inside `node_modules` is allowed.
464
+ Grep/glob across the whole dependency tree is refused by the host — read the one
465
+ declaration file instead of scanning the package.
466
+
79
467
  ## GraphQL template
80
468
 
81
469
  ```ts
@@ -106,8 +494,14 @@ GraphQLModule.forRoot({
106
494
 
107
495
  ## Verification checklist (run before declaring done)
108
496
 
109
- 1. `bun test` passes.
110
- 2. App boots: `bun run dev` shows no startup errors.
497
+ 1. `validate_project` passes for the packages you touched (it runs the declared
498
+ `bun test`/build scripts).
499
+ 2. A dev server is not a verification step. `bun run dev` never exits, produces no
500
+ completion evidence, and the logs or probe files it leaves behind are
501
+ unreviewed writes that invalidate the validation they were meant to support.
502
+ Start one only when the task explicitly asks to exercise a running app —
503
+ through the bounded session capability — and stop it before the final
504
+ validation.
111
505
  3. Mutating routes have validation + auth.
112
506
  4. GraphQL module has security limits when used.
113
507
  5. No secrets in source; config comes from ConfigModule/env.
@@ -6,6 +6,9 @@ window.__ModuleLoader__.load({
6
6
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
7
7
  let react_jsx_runtime = require("react/jsx-runtime");
8
8
  let react = require("react");
9
+ /* UI primitives come from the renderer bundle; a missing module only costs the icon. */
10
+ let primitives = null;
11
+ try { primitives = require("@deepseek-ai/dsh-client-ui-primitives"); } catch (error) { primitives = null; }
9
12
  const LOGO = __LOGO_DATA_URI__;
10
13
  const VI_LOCALES = __VI_LOCALES__;
11
14
  const EN_OVERRIDES = {
@@ -34,6 +37,39 @@ window.__ModuleLoader__.load({
34
37
  });
35
38
  }
36
39
 
40
+ /* The injected-context row prints its producer as a raw plugin id, so the
41
+ reader sees "@deepseek-ai/dsh-system-prompt". Rename the harness
42
+ producers to readable labels: "Chèn ngữ cảnh · System prompt". */
43
+ const CONTEXT_SOURCE_ID = /^@deepseek-ai\/dsh-([a-z0-9-]+)$/i;
44
+ function friendlyContextSource(raw) {
45
+ var match = CONTEXT_SOURCE_ID.exec(raw);
46
+ if (!match) return undefined;
47
+ var words = match[1].split("-");
48
+ for (var i = 0; i < words.length; i += 1) words[i] = words[i].charAt(0).toUpperCase() + words[i].slice(1);
49
+ var label = words.join(" ");
50
+ return label === "System Prompt" ? "System prompt" : label;
51
+ }
52
+ /** Rewrite every visible producer label; React re-renders are re-applied. */
53
+ function relabelContextSources() {
54
+ if (typeof document === "undefined") return;
55
+ var nodes = document.querySelectorAll("[data-context-source]");
56
+ for (var i = 0; i < nodes.length; i += 1) {
57
+ var node = nodes[i];
58
+ var label = friendlyContextSource((node.textContent || "").trim());
59
+ if (label !== undefined && node.textContent !== label) node.textContent = label;
60
+ }
61
+ }
62
+ function watchContextSources() {
63
+ if (typeof document === "undefined" || typeof MutationObserver === "undefined") return;
64
+ relabelContextSources();
65
+ var scheduled = false;
66
+ new MutationObserver(function () {
67
+ if (scheduled) return;
68
+ scheduled = true;
69
+ Promise.resolve().then(function () { scheduled = false; relabelContextSources(); });
70
+ }).observe(document.body, { childList: true, subtree: true, characterData: true });
71
+ }
72
+
37
73
  const GALAXY_KEY_REF = "GBH_GALAXY_API_KEY";
38
74
  /** Show a Galaxy-specific dialog when the Galaxy key is not configured. */
39
75
  function ensureGalaxyKey(ctx) {
@@ -147,6 +183,136 @@ window.__ModuleLoader__.load({
147
183
  style: { height: "28px", borderRadius: "14px", border: "1px solid var(--dsw-alias-border-l2, rgba(127,127,127,.35))", background: "transparent", color: "var(--dsw-alias-label-tertiary, inherit)", font: "inherit", fontSize: "12px", padding: "0 8px", cursor: "pointer" }
148
184
  }, options);
149
185
  }
186
+ /** Locale namespace owned by the Galaxy session tools. */
187
+ const GBH_SESSIONS_NS = "gbh.sessions";
188
+ /** English dictionary for the session tools; Vietnamese lives in vi.locales.json. */
189
+ const GBH_SESSIONS_EN = {
190
+ "action.delete": "Delete session",
191
+ "dialog.title": "Delete this session?",
192
+ "dialog.body": "The session log and its projection cache are removed from the DSH home. This cannot be undone.",
193
+ "dialog.trash": "Artifacts are moved to .trash/sessions first, so they can still be recovered by hand.",
194
+ "dialog.cascade": "This session has {count} descendant session(s). Deleting it also deletes them.",
195
+ "dialog.running": "This session is running. Stop it before deleting.",
196
+ "dialog.cancel": "Cancel",
197
+ "dialog.confirm": "Delete session",
198
+ "dialog.confirmCascade": "Delete {count} sessions",
199
+ "dialog.busy": "Deleting…",
200
+ "dialog.failed": "Could not delete the session.",
201
+ "dialog.done": "Session deleted. Reloading…"
202
+ };
203
+ /** Same-origin Host base with the connection carrier\u0027s null-origin fallback. */
204
+ function gbhHostBase() {
205
+ var origin = globalThis.location && globalThis.location.origin;
206
+ return origin !== undefined && origin !== null && origin !== "null" ? origin : "http://dsh.internal";
207
+ }
208
+ /** Delete one session through the Galaxy host route; resolves to the parsed JSON body. */
209
+ function gbhDeleteSession(sessionId, cascade) {
210
+ return fetch(gbhHostBase() + "/api/galaxy/session.delete", {
211
+ method: "POST",
212
+ headers: { "content-type": "application/json" },
213
+ credentials: "same-origin",
214
+ body: JSON.stringify({ sessionId: sessionId, cascade: cascade === true, trash: true })
215
+ }).then(function (response) {
216
+ return response.json().then(function (body) { return body || {}; }, function () { return {}; });
217
+ }).catch(function (error) { return { ok: false, code: "network", message: String(error) }; });
218
+ }
219
+ /** Modal confirmation built with plain DOM, matching the Galaxy key dialog style. */
220
+ function gbhConfirmDeleteSession(sessionId, t, onFinished) {
221
+ if (typeof document === "undefined") return;
222
+ if (document.getElementById("gbh-delete-session-dialog")) return;
223
+ var overlay = document.createElement("div");
224
+ overlay.id = "gbh-delete-session-dialog";
225
+ overlay.style.cssText = "position:fixed;inset:0;z-index:2147483647;background:rgba(0,0,0,.55);display:flex;align-items:center;justify-content:center;font-family:system-ui,-apple-system,Segoe UI,sans-serif";
226
+ var card = document.createElement("div");
227
+ card.style.cssText = "background:var(--dsw-alias-bg-module-platform,#1f1f24);color:var(--dsw-alias-label-primary,#f2f2f2);padding:22px;border-radius:14px;width:min(460px,92vw);box-shadow:0 18px 50px rgba(0,0,0,.45)";
228
+ var title = document.createElement("div");
229
+ title.textContent = t("dialog.title");
230
+ title.style.cssText = "font-size:17px;font-weight:600;margin-bottom:8px";
231
+ var body = document.createElement("div");
232
+ body.textContent = t("dialog.body");
233
+ body.style.cssText = "font-size:13px;line-height:20px;opacity:.82;margin-bottom:8px";
234
+ var note = document.createElement("div");
235
+ note.textContent = t("dialog.trash");
236
+ note.style.cssText = "font-size:12px;line-height:18px;opacity:.62;margin-bottom:14px";
237
+ var errorEl = document.createElement("div");
238
+ errorEl.style.cssText = "color:#ff6b6b;font-size:12px;line-height:18px;min-height:16px;margin-bottom:10px";
239
+ var actions = document.createElement("div");
240
+ actions.style.cssText = "display:flex;justify-content:flex-end;gap:10px";
241
+ var cancel = document.createElement("button");
242
+ cancel.type = "button";
243
+ cancel.textContent = t("dialog.cancel");
244
+ cancel.style.cssText = "height:34px;padding:0 14px;border-radius:9px;border:1px solid rgba(127,127,127,.4);background:transparent;color:inherit;cursor:pointer";
245
+ var confirm = document.createElement("button");
246
+ confirm.type = "button";
247
+ confirm.textContent = t("dialog.confirm");
248
+ confirm.style.cssText = "height:34px;padding:0 16px;border-radius:9px;border:none;background:#e5484d;color:#fff;cursor:pointer;font-weight:600";
249
+ cancel.onclick = function () { overlay.remove(); onFinished(); };
250
+ confirm.onclick = function () { run(false); };
251
+ function finish(body) {
252
+ confirm.disabled = true;
253
+ errorEl.style.color = "var(--dsw-alias-label-secondary,#9aa0a6)";
254
+ errorEl.textContent = t("dialog.done");
255
+ if (body && body.deleted && body.deleted.length > 0) {
256
+ setTimeout(function () { try { location.reload(); } catch (e) { overlay.remove(); onFinished(); } }, 600);
257
+ return;
258
+ }
259
+ overlay.remove();
260
+ onFinished();
261
+ }
262
+ function run(cascade) {
263
+ confirm.disabled = true;
264
+ cancel.disabled = true;
265
+ errorEl.style.color = "var(--dsw-alias-label-secondary,#9aa0a6)";
266
+ errorEl.textContent = t("dialog.busy");
267
+ gbhDeleteSession(sessionId, cascade).then(function (body) {
268
+ if (body && body.ok === true) { finish(body); return; }
269
+ var code = body && body.code ? body.code : "error";
270
+ confirm.disabled = false;
271
+ cancel.disabled = false;
272
+ errorEl.style.color = "#ff6b6b";
273
+ if (code === "session/has-children") {
274
+ var count = body && body.children ? body.children.length : 0;
275
+ note.textContent = t("dialog.cascade").split("{count}").join(String(count));
276
+ confirm.textContent = t("dialog.confirmCascade").split("{count}").join(String(count));
277
+ confirm.onclick = function () { run(true); };
278
+ errorEl.textContent = "";
279
+ return;
280
+ }
281
+ if (code === "session/running") { errorEl.textContent = t("dialog.running"); return; }
282
+ errorEl.textContent = (body && body.message) || t("dialog.failed");
283
+ });
284
+ }
285
+ actions.append(cancel, confirm);
286
+ card.append(title, body, note, errorEl, actions);
287
+ overlay.append(card);
288
+ document.body.append(overlay);
289
+ setTimeout(function () { try { confirm.focus(); } catch (e) { /* ignore */ } }, 30);
290
+ }
291
+ /** Trash button seated in the Session header utilities list. */
292
+ function GbhDeleteSessionAction(props) {
293
+ var sessionId = props.sessionId;
294
+ if (typeof sessionId !== "string" || sessionId.length === 0) return null;
295
+ var busyState = react.useState(false);
296
+ var busy = busyState[0];
297
+ var setBusy = busyState[1];
298
+ var t = props.t;
299
+ var label = t("action.delete");
300
+ var icon = null;
301
+ try { icon = primitives && primitives.IconTrashOutline16 ? react_jsx_runtime.jsx(primitives.IconTrashOutline16, {}) : null; } catch (e) { icon = null; }
302
+ return react_jsx_runtime.jsx("button", {
303
+ type: "button",
304
+ title: label,
305
+ "aria-label": label,
306
+ disabled: busy,
307
+ onClick: function () {
308
+ if (busy) return;
309
+ setBusy(true);
310
+ gbhConfirmDeleteSession(sessionId, t, function () { setBusy(false); });
311
+ },
312
+ style: { display: "inline-flex", alignItems: "center", justifyContent: "center", width: "28px", height: "28px", borderRadius: "8px", border: "1px solid var(--dsw-alias-border-l2, rgba(127,127,127,.35))", background: "transparent", color: "var(--dsw-alias-label-tertiary, inherit)", cursor: busy ? "default" : "pointer", padding: "0" },
313
+ children: icon === null ? label : icon
314
+ });
315
+ }
150
316
  const inject = ["slots", "locale", "remote", "remote.credentials", "modelDirectories", "sessions"];
151
317
  function apply(ctx) {
152
318
  ctx.slots.inject("sidebar.brand.mark", () => ctx.slots.inject("sidebar.brand.name", function* () {
@@ -154,6 +320,16 @@ window.__ModuleLoader__.load({
154
320
  yield ctx.slots.register({ name: "sidebar.brand.name" }, GbhBrandName);
155
321
  }));
156
322
  ctx.slots.inject("conversation.hero.brand.mark", () => ctx.slots.register({ name: "conversation.hero.brand.mark" }, GbhBrandMark));
323
+ /* Session tools: delete the open session through the Galaxy Host route. */
324
+ ctx.slots.inject("conversation.session.header.utilities", function () {
325
+ return ctx.slots.register({
326
+ name: "conversation.session.header.utilities",
327
+ id: "gbh-session-delete",
328
+ order: 50,
329
+ locale: GBH_SESSIONS_NS,
330
+ inject: function () { return {}; }
331
+ }, GbhDeleteSessionAction);
332
+ });
157
333
  try {
158
334
  ctx.locale.addLanguage({ id: "vi", label: "Tiếng Việt", fallback: "en" });
159
335
  } catch (error) {
@@ -162,12 +338,19 @@ window.__ModuleLoader__.load({
162
338
  const namespaces = Object.keys(VI_LOCALES);
163
339
  for (let i = 0; i < namespaces.length; i += 1) {
164
340
  const ns = namespaces[i];
341
+ /* The session tools namespace registers both dictionaries in one call below. */
342
+ if (ns === GBH_SESSIONS_NS) continue;
165
343
  try {
166
344
  ctx.locale.register(ns, "vi", VI_LOCALES[ns]);
167
345
  } catch (error) {
168
346
  /* a namespace may already carry vi on a reload */
169
347
  }
170
348
  }
349
+ try {
350
+ ctx.locale.register(GBH_SESSIONS_NS, { en: GBH_SESSIONS_EN, vi: VI_LOCALES[GBH_SESSIONS_NS] });
351
+ } catch (error) {
352
+ /* the namespace may already be registered on a plugin reload */
353
+ }
171
354
  /* Replace the shipped internal-testing notice with the Galaxy description,
172
355
  including the English copy, by editing the registered dictionaries. */
173
356
  try {
@@ -209,6 +392,7 @@ window.__ModuleLoader__.load({
209
392
  });
210
393
  });
211
394
  ensureGalaxyKey(ctx);
395
+ watchContextSources();
212
396
  }
213
397
  exports.apply = apply;
214
398
  exports.inject = inject;