@xemahq/biome-sdk 0.1.1

package/src/api/nest/health/health.controller.ts

@@ -0,0 +1,36 @@
+import { Controller, Get, Inject } from '@nestjs/common';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+
+/** DI token for the database client injected into `PluginHealthController`. */
+export const PLUGIN_HEALTH_DB = 'PLUGIN_HEALTH_DB' as const;
+
+/** Minimal interface required by `PluginHealthController`. */
+export interface PluginHealthDb {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  $queryRaw: (...args: any[]) => Promise<any>;
+}
+
+@ApiTags('Health')
+@Controller('health')
+export class PluginHealthController {
+  constructor(@Inject(PLUGIN_HEALTH_DB) private readonly db: PluginHealthDb) {}
+
+  @Get()
+  @ApiOperation({ summary: 'Health check' })
+  check() {
+    return { status: 'ok' };
+  }
+
+  @Get('live')
+  @ApiOperation({ summary: 'Liveness probe' })
+  live() {
+    return { status: 'ok' };
+  }
+
+  @Get('ready')
+  @ApiOperation({ summary: 'Readiness probe — checks database connectivity' })
+  async ready() {
+    await this.db.$queryRaw`SELECT 1`;
+    return { status: 'ok', db: 'connected' };
+  }
+}

package/src/api/nest/health/health.module.ts

@@ -0,0 +1,29 @@
+import { Module, type DynamicModule, type Type } from '@nestjs/common';
+
+import {
+  PLUGIN_HEALTH_DB,
+  PluginHealthController,
+  type PluginHealthDb,
+} from './health.controller.js';
+
+@Module({})
+export class BiomeHealthModule {
+  /**
+   * Wire the health endpoints for a biome service. Pass the biome's
+   * own `PrismaService` class; it must already be registered in the DI
+   * container (e.g. via a `@Global()` `PrismaModule`).
+   *
+   * @example
+   *   imports: [BiomeHealthModule.forPrisma(PrismaService)]
+   */
+  static forPrisma(prismaClass: Type<PluginHealthDb>): DynamicModule {
+    return {
+      module: BiomeHealthModule,
+      providers: [
+        { provide: PLUGIN_HEALTH_DB, useExisting: prismaClass },
+        PluginHealthController,
+      ],
+      controllers: [PluginHealthController],
+    };
+  }
+}

package/src/api/nest/index.ts

@@ -0,0 +1,6 @@
+export * from './controller-base.js';
+export * from './events/events.controller.js';
+export * from './health/health.controller.js';
+export * from './health/health.module.js';
+export * from './module.js';
+export * from './request-context.js';

package/src/api/nest/module.ts

@@ -0,0 +1,51 @@
+import {
+  Module,
+  type DynamicModule,
+  type MiddlewareConsumer,
+  type NestModule,
+} from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+
+import {
+  BiomeApiRequestContextMiddleware,
+  BiomeApiScopeGuard,
+} from './request-context.js';
+
+/**
+ * NestJS module preset for biome-shipped APIs. Drop into the biome's
+ * `AppModule`:
+ *
+ *   @Module({
+ *     imports: [BiomeApiModule.register()],
+ *     controllers: [HelloController],
+ *   })
+ *   export class AppModule {}
+ *
+ * What it wires:
+ *   - `BiomeApiRequestContextMiddleware` on every route — extracts the
+ *     gateway-injected headers (`X-Org-Id`, `X-Project-Id`, …) and
+ *     stamps `req[BIOME_REQUEST_CONTEXT]`.
+ *   - `BiomeApiScopeGuard` as a global guard — enforces `@RequireScope`
+ *     decorators. Unmarked routes pass through.
+ *
+ * Both are opt-in by handler decoration; the cost when unused is one
+ * `Reflect.getMetadata` per request.
+ */
+@Module({})
+export class BiomeApiModule implements NestModule {
+  static register(): DynamicModule {
+    return {
+      module: BiomeApiModule,
+      providers: [
+        BiomeApiRequestContextMiddleware,
+        { provide: APP_GUARD, useClass: BiomeApiScopeGuard },
+      ],
+      exports: [BiomeApiRequestContextMiddleware],
+      global: true,
+    };
+  }
+
+  configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(BiomeApiRequestContextMiddleware).forRoutes('*');
+  }
+}

package/src/api/nest/request-context.ts

@@ -0,0 +1,166 @@
+import {
+  CanActivate,
+  createParamDecorator,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+  type NestMiddleware,
+  type SetMetadata,
+} from '@nestjs/common';
+
+import {
+  BiomeApiContextError,
+  BiomeApiScope,
+  requireRequestContext,
+  type BiomeApiRequestContext,
+} from '../index.js';
+
+/**
+ * NestJS-side glue for biome APIs. Biome authors using NestJS
+ * register `BiomeApiRequestContextMiddleware` once, then read the
+ * stamped context via `@BiomeRequestContext()` on any handler param.
+ *
+ * The framework-agnostic extractor (`requireRequestContext`) is the
+ * source of truth; this module just wraps it in NestJS shapes. Biomes
+ * that don't use NestJS keep using the bare extractor and never pay
+ * for this surface.
+ *
+ * Imported from `@xemahq/biome-api-sdk/nest` so the bare entrypoint
+ * stays framework-free.
+ */
+
+/**
+ * Symbol used as the request-property key for the stamped context.
+ * Symbol (vs string) avoids accidental collision with biome-shipped
+ * fields and prevents the value from leaking to JSON.stringify output.
+ */
+export const BIOME_REQUEST_CONTEXT = Symbol('biome-api.request-context');
+
+interface RequestWithContext {
+  headers: Record<string, string | string[] | undefined>;
+  [BIOME_REQUEST_CONTEXT]?: BiomeApiRequestContext;
+}
+
+/**
+ * Stamps the validated request context onto every request before
+ * handlers run. The middleware throws `BiomeApiContextError` when
+ * gateway-injected headers are missing — fail-fast so misconfigured
+ * deployments surface at the first request, not at obscure null-deref
+ * stack traces deep inside a handler.
+ */
+@Injectable()
+export class BiomeApiRequestContextMiddleware implements NestMiddleware {
+  use(req: RequestWithContext, _res: unknown, next: (error?: unknown) => void): void {
+    try {
+      req[BIOME_REQUEST_CONTEXT] = requireRequestContext(req.headers);
+      next();
+    } catch (cause) {
+      if (cause instanceof BiomeApiContextError) {
+        next(cause);
+        return;
+      }
+      next(cause);
+    }
+  }
+}
+
+/**
+ * Param decorator that yields the stamped context. Usage:
+ *
+ *   @Get('/hello')
+ *   hello(@BiomeRequestContext() ctx: BiomeApiRequestContext) { ... }
+ *
+ * Throws at call time if the middleware didn't run — a deployment
+ * error, not user input, so the runtime error is the right surface.
+ */
+export const BiomeRequestContext = createParamDecorator(
+  (_data: unknown, ctx: ExecutionContext): BiomeApiRequestContext => {
+    const req = ctx.switchToHttp().getRequest<RequestWithContext>();
+    const stamped = req[BIOME_REQUEST_CONTEXT];
+    if (!stamped) {
+      throw new BiomeApiContextError(
+        'BiomeRequestContext was read but the middleware did not stamp one — ensure BiomeApiModule is registered before this controller mounts.',
+      );
+    }
+    return stamped;
+  },
+);
+
+/**
+ * Reflector metadata key for `@RequireScope`. Internal — biome
+ * authors use the decorator, the guard reads it.
+ */
+const BIOME_API_SCOPE_KEY = 'biome-api.required-scope';
+
+/**
+ * Decorator that marks a route as requiring a specific scope tier.
+ * Pairs with `BiomeApiScopeGuard`: the guard reads the metadata,
+ * asserts the stamped context carries the matching scope fields
+ * (`projectId` for `Project`; `installationId` for `Installation`),
+ * and 403s otherwise.
+ *
+ * `BiomeApiScope.Public` is a no-op marker — useful in explicit
+ * route-by-route style ("yes, this endpoint is unauthenticated on
+ * purpose"). The guard recognises it and returns true.
+ *
+ * Implementation note: declared as a function returning the result
+ * of an inline NestJS `SetMetadata`-style decorator so we don't need
+ * to import SetMetadata at module-eval time (some NestJS versions
+ * expose it from different paths). Pull it from the @nestjs/common
+ * runtime if-and-only-if it exists; otherwise fall back to a manual
+ * `Reflect.defineMetadata` call.
+ */
+export function RequireScope(scope: BiomeApiScope): MethodDecorator {
+  return (_target: object, _propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(BIOME_API_SCOPE_KEY, scope, descriptor.value);
+    return descriptor;
+  };
+}
+
+/**
+ * Guard that enforces the scope declared by `@RequireScope`. Reads
+ * the route's metadata, narrows on the stamped context. Returns
+ * `true` for any unmarked route (sane default — opt in to enforcement).
+ *
+ * Failure modes:
+ *   - context missing → 403 with a clear message (middleware skipped)
+ *   - scope is `Org` but ctx.projectId is set: still allowed (Org-scoped
+ *     endpoints are valid in any project's request context). The narrower
+ *     scopes are the strict cases.
+ *   - scope is `Project` but ctx.projectId missing → 403
+ *   - scope is `Installation` but ctx.installationId missing → 403
+ */
+@Injectable()
+export class BiomeApiScopeGuard implements CanActivate {
+  canActivate(ctx: ExecutionContext): boolean {
+    const required = Reflect.getMetadata(BIOME_API_SCOPE_KEY, ctx.getHandler()) as
+      | BiomeApiScope
+      | undefined;
+    if (required === undefined || required === BiomeApiScope.Public) {return true;}
+    const req = ctx.switchToHttp().getRequest<RequestWithContext>();
+    const stamped = req[BIOME_REQUEST_CONTEXT];
+    if (!stamped) {
+      throw new ForbiddenException(
+        'Biome API request is missing request context — gateway did not inject headers',
+      );
+    }
+    if (required === BiomeApiScope.Org) {return true;}
+    if (required === BiomeApiScope.Project && !stamped.projectId) {
+      throw new ForbiddenException(
+        '@RequireScope(Project) handler invoked without an X-Project-Id header',
+      );
+    }
+    if (required === BiomeApiScope.Installation && !stamped.installationId) {
+      throw new ForbiddenException(
+        '@RequireScope(Installation) handler invoked without an X-Installation-Id header',
+      );
+    }
+    return true;
+  }
+}
+
+/**
+ * Re-export for biome authors composing `@UseGuards`-style helpers.
+ * Avoids forcing them to import from two different paths.
+ */
+export type { SetMetadata };

package/src/builder/index.ts

@@ -0,0 +1,26 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// `@xemahq/biome-builder`
+//
+// Authoring SDK for Xema biomes. Three responsibilities:
+//
+//   1. Zod schemas for each biome-content kind (one schema per YAML file
+//      shape). Same schemas are used by:
+//        - biome authors (typed builders, IDE hover, build-time validation)
+//        - server-side seeders (parse + validate at boot)
+//
+//   2. A filesystem walker that resolves a manifest's content-directory
+//      contributions to absolute file paths. Seeders use it to enumerate
+//      files; biome install functions use it indirectly via defineBiome.
+//
+//   3. `defineBiome` — the in-biome install entry point. Today it is a
+//      thin marker that wraps imperative install logic + provides typed
+//      builders. Later (when the kernel registries land), it absorbs the
+//      auto-install logic so a content-only biome needs zero TS code.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/contribution-schemas';
+export * from './lib/content-walker';
+export * from './lib/extends-precedence';
+export * from './lib/workflow-phase-config-loader';
+export * from './lib/define-biome';
+export * from './lib/define-helpers';