@geekmidas/cli 10.0.0-alpha.6 → 10.0.0-alpha.60

package/README.md

@@ -7,7 +7,7 @@ A powerful CLI tool for building and managing TypeScript-based backend APIs with
 - **Project Scaffolding**: Interactive `init` command to bootstrap new projects with templates
 - **Multi-Provider Support**: Generate handlers for AWS Lambda (API Gateway v1/v2) and server applications
 - **Development Server**: Hot-reload development server with file watching
-- **Telescope Integration**: Laravel-style debugging dashboard for inspecting requests, logs, and exceptions
+- **Telescope Integration**: Laravel-style recording of requests, logs and exceptions, served as JSON
 - **OpenAPI Generation**: Auto-generate OpenAPI 3.0 specifications from your endpoints
 - **Docker Support**: Generate optimized Dockerfiles with multi-stage builds, turbo prune for monorepos
 - **Secrets Management**: Secure credential generation, encryption, and stage-based secrets storage
@@ -54,6 +54,7 @@ Create a `gkm.config.ts` file in your project root:
 import { defineConfig } from '@geekmidas/cli/config';
 
 export default defineConfig({
+  stages: { local: 'dev', deployed: ['prod'] },
   // Glob pattern to find endpoint files
   routes: 'src/routes/**/*.ts',
 
@@ -72,7 +73,7 @@ export default defineConfig({
   // Logger configuration
   logger: './src/logger.ts#logger',
 
-  // Optional: Telescope debugging dashboard (enabled by default in dev)
+  // Optional: Telescope request recording (enabled by default in dev)
   telescope: {
     enabled: true,
     path: '/__telescope',
@@ -142,36 +143,32 @@ export const createUser = api
 
 ### 5. Create Subscribers (Optional)
 
-Create event subscribers in `src/subscribers/`:
+Declare the topic once, and a worker to run what has no port; a subscriber is
+built from the worker and binds to the topic:
 
 ```typescript
+// src/constructs/topics.ts
+import { Topic } from '@geekmidas/constructs/topic';
+import { z } from 'zod';
+
+export const users = new Topic('Users', {
+  events: {
+    'user.created': z.object({ userId: z.string(), email: z.email() }),
+    'user.updated': z.object({ userId: z.string() }),
+  },
+});
+
+// src/constructs/worker.ts
+import { Worker } from '@geekmidas/constructs/worker';
+
+export const worker = new Worker('Jobs', { logger });
+
 // src/subscribers/userSubscriber.ts
-import { SubscriberBuilder } from '@geekmidas/constructs/subscribers';
-import type { Service } from '@geekmidas/services';
-import type { EventPublisher, PublishableMessage } from '@geekmidas/events';
-import type { EnvironmentParser } from '@geekmidas/envkit';
-
-// Define event types
-type UserEvents =
-  | PublishableMessage<'user.created', { userId: string; email: string }>
-  | PublishableMessage<'user.updated', { userId: string }>;
-
-// Create event publisher service
-const userEventPublisher = {
-  serviceName: 'userEventPublisher' as const,
-  async register(envParser: EnvironmentParser<{}>) {
-    const config = envParser.create((get) => ({
-      publisherUrl: get('EVENT_PUBLISHER_URL').string()
-    })).parse();
-
-    const { Publisher } = await import('@geekmidas/events');
-    return Publisher.fromConnectionString<UserEvents>(config.publisherUrl);
-  }
-} satisfies Service<'userEventPublisher', EventPublisher<UserEvents>>;
+import { users } from '../constructs/topics';
+import { worker } from '../constructs/worker';
 
-// Create subscriber
-export const userCreatedSubscriber = new SubscriberBuilder()
-  .publisher(userEventPublisher)
+export const userCreatedSubscriber = worker
+  .topic(users)
   .subscribe(['user.created'])
   .handle(async ({ events, logger }) => {
     for (const event of events) {
@@ -181,11 +178,16 @@ export const userCreatedSubscriber = new SubscriberBuilder()
   });
 ```
 
+An endpoint publishes to the topic with `.event(users, { type: 'user.created',
+payload: (user) => ({ userId: user.id, email: user.email }) })`. Declaring the
+topic is what puts a broker in the local plan and resolves
+`USERS_PUBLISHER_CONNECTION_STRING` for whatever publishes to it.
+
 ### 6. Build Handlers
 
 ```bash
-# Generate AWS Lambda handlers
-npx gkm build --provider aws-apigatewayv1
+# Build for where gkm.config.ts deploys (AWS for `deploy: { default: 'sst' }`)
+npx gkm build
 
 # Generate server application
 npx gkm build --provider server
@@ -224,7 +226,7 @@ When run without `--yes`, the command will ask:
    - `api` - Full API with auth, database, services
    - `serverless` - AWS Lambda handlers
    - `worker` - Background job processing
-3. **Telescope** - Include debugging dashboard (default: yes)
+3. **Telescope** - Include request, exception and log recording (default: yes)
 4. **Database** - Include Kysely database support (default: yes)
 5. **Logger** - Choose logger implementation:
    - `pino` - Fast JSON logger for production (recommended)
@@ -309,17 +311,20 @@ Generate handlers from your endpoints.
 gkm build [options]
 ```
 
+By default it builds for where the project deploys: `deploy: { default: 'sst' }`
+builds for AWS, one Lambda per construct; `dokploy` (the default when nothing
+is declared) builds a server.
+
 **Options:**
-- `--provider <provider>`: Target provider (default: `aws-apigatewayv1`)
-  - `aws-apigatewayv1`: AWS API Gateway v1 Lambda handlers
-  - `aws-apigatewayv2`: AWS API Gateway v2 Lambda handlers
+- `--provider <provider>`: Override the deploy target
+  - `aws`: One Lambda handler per construct (API Gateway v2 for endpoints)
   - `server`: Server application with Hono
 - `--production`: Generate production-optimized bundle (server provider only)
 
 **Example:**
 ```bash
-# Generate AWS Lambda handlers
-gkm build --provider aws-apigatewayv1
+# Build for where gkm.config.ts deploys
+gkm build
 
 # Generate server application
 gkm build --provider server
@@ -443,7 +448,7 @@ gkm docker [options]
 
 **Generated Files:**
 - `.gkm/docker/Dockerfile` - Multi-stage or slim Dockerfile
-- `.gkm/docker/docker-compose.yml` - Docker Compose configuration
+- `docker-compose.constructs.yml` - the containers the constructs imply, and the app (project root)
 - `.gkm/docker/docker-entrypoint.sh` - Entrypoint script
 - `.dockerignore` - Docker ignore file (project root)
 
@@ -490,6 +495,7 @@ Configure Docker settings in `gkm.config.ts`:
 import { defineConfig } from '@geekmidas/cli/config';
 
 export default defineConfig({
+  stages: { local: 'dev', deployed: ['prod'] },
   routes: 'src/routes/**/*.ts',
   envParser: './src/env.ts',
   logger: './src/logger.ts',
@@ -503,38 +509,20 @@ export default defineConfig({
     baseImage: 'node:22-alpine',
     // Port to expose (default: 3000)
     port: 3000,
-    // Docker Compose services
-    compose: {
-      services: {
-        postgres: { image: 'postgis/postgis:16-3.4-alpine' },  // Custom image
-        redis: true,                                            // Default version
-        rabbitmq: { version: '3.12-management-alpine' },        // Custom version
-      },
-    },
   },
 });
 ```
 
-**Docker Compose Services:**
-
-Services can be configured with custom versions, custom images, or use defaults:
-
-```typescript
-// Object format (recommended)
-services: {
-  postgres: { version: '15-alpine' },              // Custom version
-  redis: true,                                      // Default: redis:7-alpine
-  rabbitmq: { version: '3.12-management-alpine' },
-}
-
-// Custom images (e.g., PostGIS, Redis Stack)
-services: {
-  postgres: { image: 'postgis/postgis:16-3.4-alpine' },  // Full image reference
-  redis: { image: 'redis/redis-stack:latest' },
-}
+**Compose:** there is no `compose` option. `gkm docker` writes
+`docker-compose.constructs.yml` at the project root from the declared
+constructs; an image pin or an extra service goes in your own
+`docker-compose.yml`, which is merged over it:
 
-// Legacy array format - uses default versions
-services: ['postgres', 'redis', 'rabbitmq']
+```yaml
+# docker-compose.yml
+services:
+  postgres:
+    image: postgis/postgis:16-3.4-alpine
 ```
 
 **Service Configuration Options:**
@@ -557,7 +545,7 @@ services: ['postgres', 'redis', 'rabbitmq']
 
 ### `gkm dev`
 
-Start a development server with hot-reload and optional Telescope debugging dashboard.
+Start a development server with hot-reload and optional Telescope recording.
 
 ```bash
 gkm dev [options]
@@ -569,7 +557,8 @@ gkm dev [options]
 **Features:**
 - Hot-reload on file changes (endpoints, functions, crons, subscribers)
 - Automatic port switching if requested port is in use
-- Telescope debugging dashboard (enabled by default)
+- Telescope JSON API at `/__telescope/api` (enabled by default)
+- The declared database, read-only, as JSON at `/__gkm/db`
 - Real-time WebSocket updates in Telescope
 
 **Example:**
@@ -682,8 +671,8 @@ gkm secrets:init --stage production --force
 ```
 
 **Generated:**
-- Secure passwords for postgres, redis, rabbitmq (based on `docker.compose.services` config)
-- Connection URLs (`DATABASE_URL`, `REDIS_URL`, `RABBITMQ_URL`)
+- Custom secrets for the stage; the containers' credentials are provisioned by
+  reconcile from the declared constructs, not stored here
 - Stored in `.gkm/secrets/<stage>.json` (gitignored)
 
 ### `gkm secrets:set`
@@ -797,7 +786,7 @@ Store credentials locally to avoid setting environment variables for every comma
 
 ### `gkm login`
 
-Authenticate with a deployment service. Credentials are stored in `~/.gkm/credentials.json`.
+Authenticate with a deployment service. Credentials are stored in `~/.gkm/credentials.json` (`$GKM_HOME/credentials.json` when `GKM_HOME` is set).
 
 ```bash
 gkm login [options]
@@ -883,6 +872,20 @@ gkm deploy --provider <provider> --stage <stage> [options]
 - `--tag <tag>`: Image tag (default: `stage-timestamp`)
 - `--skip-push`: Skip pushing image to registry
 - `--skip-build`: Skip build step (use existing build)
+- `--json`: Write the deploy's events as JSON lines on stdout instead of progress; never prompts
+- `--dry-run`: Show what would be created or reused, and change, build and push nothing
+
+At a terminal a missing Dokploy or registry login is asked for (and the Dokploy one stored). With `--json` or without a terminal nothing is asked: the deploy stops with `MissingCredential` and exits 1.
+
+**From a program:** the same deploy is `deploy()` from `@geekmidas/cli/deploy` — explicit `cwd`, an injected `CredentialProvider`, a logger and an `AbortSignal`; it returns a run you iterate for JSON events, plus a `result` promise. It never prompts, prints or exits.
+
+```typescript
+import { deploy } from '@geekmidas/cli/deploy';
+
+const run = deploy({ cwd: '/srv/shop', stage: 'production', signal });
+for await (const event of run) console.log(event.type);
+const result = await run.result;
+```
 
 **Examples:**
 ```bash
@@ -929,6 +932,7 @@ This allows the CLI to validate that all required secrets are configured before
 ```typescript
 // gkm.config.ts
 export default defineConfig({
+  stages: { local: 'dev', deployed: ['prod'] },
   routes: 'src/endpoints/**/*.ts',
   envParser: './src/env.ts',
   logger: './src/logger.ts',
@@ -937,25 +941,19 @@ export default defineConfig({
     registry: 'ghcr.io/myorg',
     imageName: 'my-api',
   },
-
-  // For Dokploy deployments
-  providers: {
-    dokploy: {
-      endpoint: 'https://dokploy.example.com',
-      projectId: 'proj_xxx',
-      applicationId: 'app_xxx',
-    },
-  },
 });
 ```
 
 **Environment Variables:**
 - `DOKPLOY_API_TOKEN`: API token for Dokploy (not needed if logged in via `gkm login`)
-- `GKM_MASTER_KEY`: Automatically set by Dokploy, or manually for Docker deployments
+- `DOKPLOY_ENDPOINT`: Dokploy URL, if neither the stored login nor `deploy.dokploy.endpoint` gives one
+- `DOCKER_REGISTRY_USERNAME` / `DOCKER_REGISTRY_PASSWORD`: a registry login, used only when Dokploy has no registry for `deploy.dokploy.registry` and one has to be created
+- `GKM_HOME`: where stage keys and stored logins live (default `~/.gkm`)
+- `GKM_MASTER_KEY`: Automatically set by Dokploy, or manually for Docker deployments — from `.gkm/server/master.key`, which `gkm build --stage` writes (the key is never printed; output shows its fingerprint)
 
 ### `gkm deploy:init`
 
-Initialize a new Dokploy deployment by creating a project and application via the Dokploy API. Automatically updates `gkm.config.ts` with the configuration.
+Initialize a new Dokploy deployment by creating a project and application via the Dokploy API. Nothing is written to `gkm.config.ts`: the ids are rediscovered by name on each run and kept in the deploy state file.
 
 ```bash
 gkm deploy:init --project <name> --app <name> [options]
@@ -990,8 +988,7 @@ gkm deploy:init \
 1. Searches for existing project by name, or creates a new one
 2. Creates a new application in the project
 3. Configures registry if `--registry-id` is provided
-4. Updates `gkm.config.ts` with the Dokploy configuration
-5. Shows next steps for secrets and deployment
+4. Shows next steps for secrets and deployment
 
 ### `gkm deploy:list`
 
@@ -1040,7 +1037,7 @@ export const envParser = new EnvironmentParser({...process.env, ...Credentials})
 
 **How it works:**
 - At build time, secrets are encrypted with AES-256-GCM and embedded in the bundle
-- An ephemeral master key is generated per build
+- An ephemeral master key is generated per build and written to `.gkm/server/master.key` (mode `0600`); the build prints its path and fingerprint, never the key
 - At runtime, `Credentials` decrypts using `GKM_MASTER_KEY` environment variable
 - In development (no embedded secrets), `Credentials` returns `{}`
 
@@ -1059,28 +1056,23 @@ The following commands are planned for future releases:
 The `gkm.config.ts` file defines how the CLI discovers and processes your endpoints:
 
 ```typescript
-// Construct types accept a string, string[], or partitioned config
-type Routes = string | string[] | PartitionedRoutes;
-
-interface PartitionedRoutes {
-  paths: string | string[];
-  partition: (filepath: string) => string;
-}
+// Construct types accept a glob string or an array of them
+type Routes = string | string[];
 
 interface GkmConfig {
-  routes: Routes;                // Glob patterns or partitioned config
+  routes: Routes;                // Glob patterns
   envParser: string;             // Path to environment parser
   logger: string;                // Path to logger configuration
-  functions?: Routes;            // Glob patterns or partitioned config
-  crons?: Routes;                // Glob patterns or partitioned config
-  subscribers?: Routes;          // Glob patterns or partitioned config
+  functions?: Routes;            // Glob patterns
+  crons?: Routes;                // Glob patterns
+  subscribers?: Routes;          // Glob patterns
   runtime?: 'node' | 'bun';     // Runtime environment (default: 'node')
   telescope?: boolean | TelescopeConfig; // Telescope debugging config
 }
 
 interface TelescopeConfig {
   enabled?: boolean;       // Enable/disable (default: true in dev)
-  path?: string;           // Dashboard path (default: '/__telescope')
+  path?: string;           // Where the JSON API is mounted (default: '/__telescope')
   ignore?: string[];       // URL patterns to ignore
   recordBody?: boolean;    // Record request/response bodies (default: true)
   maxEntries?: number;     // Max entries to keep (default: 1000)
@@ -1092,7 +1084,7 @@ interface TelescopeConfig {
 
 #### `routes`
 
-Glob pattern(s) to discover endpoint files. Can be a single pattern, array of patterns, or a partitioned config:
+Glob pattern(s) to discover endpoint files. Can be a single pattern or an array of patterns:
 
 ```typescript
 // Single pattern
@@ -1104,19 +1096,8 @@ routes: [
   'src/api/**/*.ts',
   'src/handlers/**/*.ts'
 ]
-
-// Partitioned — groups constructs in the generated manifest
-routes: {
-  paths: './src/endpoints/**/*.ts',
-  partition: (filepath) => {
-    const match = filepath.match(/endpoints\/([^/]+)\//);
-    return match?.[1] ?? 'default';
-  },
-}
 ```
 
-The same partitioned format works for `functions`, `crons`, and `subscribers`. When a `partition` callback is provided, the generated manifest groups constructs by partition name (e.g., `manifest.routes.admin`). Without it, manifest fields remain flat arrays.
-
 #### `envParser`
 
 Path to your environment parser configuration. Supports both default and named exports.
@@ -1149,7 +1130,7 @@ logger: './src/utils.ts#appLogger'
 
 #### `telescope`
 
-Configuration for the Telescope debugging dashboard. Telescope is enabled by default when using `gkm dev`.
+Configuration for Telescope, which records requests, logs and exceptions and serves them as JSON. Telescope is enabled by default when using `gkm dev`.
 
 ```typescript
 // Disable telescope
@@ -1174,7 +1155,7 @@ telescope: {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `enabled` | `boolean` | `true` | Enable/disable Telescope |
-| `path` | `string` | `/__telescope` | Dashboard URL path |
+| `path` | `string` | `/__telescope` | Where the JSON API is mounted |
 | `ignore` | `string[]` | `[]` | URL patterns to exclude from recording |
 | `recordBody` | `boolean` | `true` | Record request/response bodies |
 | `maxEntries` | `number` | `1000` | Maximum entries per type to keep |
@@ -1216,6 +1197,7 @@ import { defineWorkspace } from '@geekmidas/cli/config';
 
 export default defineWorkspace({
   name: 'my-project',
+  stages: { local: 'dev', deployed: ['prod'] },
   constructs: './constructs/**/*.ts',
   shared: {
     packages: ['packages/*'],
@@ -1239,7 +1221,7 @@ them out of the manifest; none of them is listed in config.
 
 ```typescript
 // constructs/api.ts
-export const api = new RestApi('Api', { defaultAuthorizer: 'none', logger });
+export const api = new RestApi('Api', { path: 'apps/api', defaultAuthorizer: 'none', logger });
 ```
 
 `gkm build --provider server` generates a Hono server from the endpoints built
@@ -1253,6 +1235,7 @@ An auth server mounts a wildcard, so there is nothing for a glob to find:
 ```typescript
 // constructs/auth.ts
 export const auth = new BetterAuth('Auth', {
+  path: 'apps/auth',
   database: authDb,
   basePath: '/api/auth',
 });
@@ -1271,8 +1254,8 @@ from being read by it.
 
 ```typescript
 // constructs/site.ts
-export const web = new StaticSite('Web').dependsOn([api, auth]);
-export const admin = new StaticSite('Admin', { variant: 'next' }).dependsOn([api]);
+export const web = new StaticSite('Web', { path: 'apps/web' }).dependsOn([api, auth]);
+export const admin = new StaticSite('Admin', { path: 'apps/admin', variant: 'next' }).dependsOn([api]);
 ```
 
 `.dependsOn()` is the single fact behind four things that are hand-maintained
@@ -1291,7 +1274,7 @@ gkm docker
 - `.gkm/docker/Dockerfile.api` - Routes-based backend (uses `gkm build`)
 - `.gkm/docker/Dockerfile.auth` - Entry-based backend (uses esbuild bundling)
 - `.gkm/docker/Dockerfile.web` - Next.js standalone output
-- `.gkm/docker/docker-compose.yml` - Full stack with all apps and services
+- `docker-compose.constructs.yml` - every container the constructs imply, and each app behind the `apps` profile (project root)
 - `.dockerignore` - Optimized ignore patterns
 
 **Dockerfile types by app:**
@@ -1358,12 +1341,10 @@ interface WorkspaceConfig {
 What an app is comes from the declaration, not from here:
 
 ```typescript
-/** Overrides, all optional. A surface normally has none. */
+/** How a site is built and run. A surface declares only its `path`. */
 interface AppSpec {
-  /** Default: `apps/<kebab-id>` if present, else the project root. */
-  path?: string;
-  /** Default: the conventional directories under `path`. */
-  code?: string;
+  /** Required: where the app lives, relative to the workspace root. */
+  path: string;
   /** Default: assigned in a stable order, so adding an app renumbers nothing. */
   port?: number;
   entry?: string;
@@ -1371,42 +1352,24 @@ interface AppSpec {
 }
 ```
 
-## Providers
-
-### AWS API Gateway v1
-
-Generates Lambda handlers compatible with AWS API Gateway v1 (REST API).
-
-```bash
-gkm build --provider aws-apigatewayv1
-```
-
-**Generated Handler:**
-```typescript
-import { AmazonApiGatewayV1Endpoint } from '@geekmidas/constructs/aws';
-import { myEndpoint } from '../src/routes/example.js';
-import { envParser } from '../src/env.js';
+## Build Targets
 
-const adapter = new AmazonApiGatewayV1Endpoint(envParser, myEndpoint);
-
-export const handler = adapter.handler;
-```
+### AWS
 
-### AWS API Gateway v2
-
-Generates Lambda handlers compatible with AWS API Gateway v2 (HTTP API).
+Generates one Lambda handler per construct. Endpoints get an API Gateway v2
+(HTTP API) adapter.
 
 ```bash
-gkm build --provider aws-apigatewayv2
+gkm build                  # with deploy: { default: 'sst' }
+gkm build --provider aws   # whatever the deploy target
 ```
 
 **Generated Handler:**
 ```typescript
 import { AmazonApiGatewayV2Endpoint } from '@geekmidas/constructs/aws';
-import { myEndpoint } from '../src/routes/example.js';
-import { envParser } from '../src/env.js';
+import { myEndpoint } from '../../../src/routes/example.js';
 
-const adapter = new AmazonApiGatewayV2Endpoint(envParser, myEndpoint);
+const adapter = new AmazonApiGatewayV2Endpoint(myEndpoint);
 
 export const handler = adapter.handler;
 ```
@@ -1448,139 +1411,141 @@ export default createApp;
 
 ## Output Structure
 
-The CLI generates files in the `.gkm/<provider>` directory:
+Handlers are generated beside the app, in `<app>/.gkm/<target>`; the manifest
+at the workspace root, where `sst.config.ts` runs:
 
 ```
-.gkm/
-├── aws-apigatewayv1/
-│   ├── getUsers.ts          # Individual Lambda handler
-│   ├── createUser.ts        # Individual Lambda handler
-├── server/
-│   ├── app.ts               # Server application
-│   ├── endpoints.ts         # Endpoint exports
-├── manifest/
-│   ├── aws.ts               # AWS manifest with types
-│   └── server.ts            # Server manifest with types
-└── openapi.json             # OpenAPI specification
+<root>/
+├── .gkm/manifest/
+│   ├── aws.ts                   # AWS manifest with types
+│   └── server.ts                # Server manifest with types
+└── apps/api/.gkm/
+    ├── aws/
+    │   ├── routes/getUsers.ts   # One Lambda handler per endpoint
+    │   ├── functions/
+    │   ├── crons/
+    │   ├── queues/
+    │   └── subscribers/
+    └── server/
+        ├── app.ts               # Server application
+        └── endpoints.ts         # Endpoint exports
 ```
 
 ### Build Manifest
 
-The CLI generates TypeScript manifests with full type information in the `.gkm/manifest/` directory. These manifests export both the data and derived types for type-safe usage.
+The manifest is the application's, not an app's: the root `gkm build` builds
+every backend and writes it once, to `.gkm/manifest/aws.ts` or
+`.gkm/manifest/server.ts` at the workspace root. An app's own build writes no
+manifest. Every handler path in it is relative to the workspace root. `gkm init`
+adds a root tsconfig alias for the manifest, `@<project>/manifest`.
 
-#### AWS Manifest (`.gkm/manifest/aws.ts`)
+It exports two values — every declared construct keyed by id, and the backends
+the build resolved — and the types derived from them:
 
 ```typescript
-export const manifest = {
-  routes: [
-    {
-      path: '/users',
-      method: 'GET',
-      handler: '.gkm/aws-apigatewayv1/getUsers.handler',
-      authorizer: 'jwt',
-    },
-    {
-      path: '/users',
-      method: 'POST',
-      handler: '.gkm/aws-apigatewayv1/createUser.handler',
-      authorizer: 'jwt',
-    },
-  ],
-  functions: [
-    {
-      name: 'processData',
-      handler: '.gkm/aws-lambda/functions/processData.handler',
-      timeout: 60,
-      memorySize: 256,
-    },
-  ],
-  crons: [
-    {
-      name: 'dailyCleanup',
-      handler: '.gkm/aws-lambda/crons/dailyCleanup.handler',
-      schedule: 'rate(1 day)',
-      timeout: 300,
-      memorySize: 512,
+export const constructs = {
+  Database: { id: 'Database', kind: 'database' },
+  Api: {
+    id: 'Api',
+    kind: 'rest-api',
+    path: 'apps/api',
+    endpoints: [
+      {
+        id: 'ApiGET/users',
+        method: 'GET',
+        path: '/users',
+        handler: 'apps/api/.gkm/aws/routes/getUsers.handler',
+        dependencies: [{ target: 'Database', kind: 'database' }],
+        authorizer: 'iam',
+      },
+    ],
+  },
+  ProcessData: {
+    id: 'ProcessData',
+    kind: 'function',
+    handler: 'apps/api/.gkm/aws/functions/processData.handler',
+    dependencies: [],
+  },
+  DailyCleanup: {
+    id: 'DailyCleanup',
+    kind: 'cron',
+    handler: 'apps/api/.gkm/aws/crons/dailyCleanup.handler',
+    schedule: 'rate(1 day)',
+    dependencies: [{ target: 'Database', kind: 'database' }],
+  },
+  Emails: {
+    id: 'Emails',
+    kind: 'queue',
+    // The queue's consumer is nested in it
+    worker: {
+      id: 'emails',
+      handler: 'apps/api/.gkm/aws/queues/emails.handler',
+      dependencies: [],
     },
-  ],
-  subscribers: [],
-} as const;
+  },
+  Users: {
+    id: 'Users',
+    kind: 'topic',
+    events: ['user.created'],
+    // As are a topic's subscribers
+    subscribers: [
+      {
+        id: 'onUser',
+        handler: 'apps/api/.gkm/aws/subscribers/onUser.handler',
+        events: ['user.created'],
+        dependencies: [],
+      },
+    ],
+  },
+} as const satisfies ConstructManifest;
+
+export const backends = { cache: 'upstash', email: 'ses' } as const;
 
 // Derived types
-export type Route = (typeof manifest.routes)[number];
-export type Function = (typeof manifest.functions)[number];
-export type Cron = (typeof manifest.crons)[number];
-export type Subscriber = (typeof manifest.subscribers)[number];
+export type Ids = IdsOf<typeof constructs>;
+export type Construct<Id extends Ids> = DeclarationOf<typeof constructs, Id>;
+export type Kind = Construct<Ids>['kind'];
 
 // Useful union types
-export type Authorizer = Route['authorizer'];
-export type HttpMethod = Route['method'];
-export type RoutePath = Route['path'];
+export type ProvidedKeys = AllProvidedKeys<typeof constructs>;
+export type Surfaces = IdsOfKind<typeof constructs, 'rest-api'>;
+export type CacheBackend = (typeof backends)['cache'];
+export type EmailBackend = (typeof backends)['email'];
 ```
 
-When routes are partitioned, the manifest groups them by partition name and generates partition-aware types:
+A `RestApi` carries its endpoints, each with its method, path, handler, the
+dependencies it declared and its authorizer. On AWS the handler is the
+endpoint's own Lambda (`apps/api/.gkm/aws/routes/<export>.handler`); in the
+server manifest every endpoint's handler is the app entry
+(`apps/api/.gkm/server/app.ts`). Functions and crons are top-level
+declarations; a queue's worker and a topic's subscribers are nested in the
+queue or topic.
 
-```typescript
-export const manifest = {
-  routes: {
-    "admin": [{ path: '/admin/users', method: 'GET', handler: '...', authorizer: 'jwt' }],
-    "default": [{ path: '/users', method: 'GET', handler: '...', authorizer: 'jwt' }],
-  },
-  functions: [...], // flat if not partitioned
-} as const;
+#### Using the Manifest
 
-// Partition-aware derived types
-export type RoutePartition = keyof typeof manifest.routes;
-export type Route<P extends RoutePartition = RoutePartition> =
-  (typeof manifest.routes)[P][number];
-```
-
-#### Server Manifest (`.gkm/manifest/server.ts`)
+On AWS, `fromManifest` from `@geekmidas/cloud/sst` provisions all of it —
+resources, each API's endpoints, queue consumers, functions and crons:
 
 ```typescript
-export const manifest = {
-  app: {
-    handler: '.gkm/server/app.ts',
-    endpoints: '.gkm/server/endpoints.ts',
-  },
-  routes: [
-    { path: '/users', method: 'GET', authorizer: 'jwt' },
-    { path: '/users', method: 'POST', authorizer: 'jwt' },
-  ],
-  subscribers: [
-    { name: 'orderHandler', subscribedEvents: ['order.created'] },
-  ],
-} as const;
+// sst.config.ts
+const { App, fromManifest, Stack } = await import('@geekmidas/cloud/sst');
+const { backends, constructs } = await import('./.gkm/manifest/aws.js');
 
-// Derived types
-export type Route = (typeof manifest.routes)[number];
-export type Subscriber = (typeof manifest.subscribers)[number];
-
-// Useful union types
-export type Authorizer = Route['authorizer'];
-export type HttpMethod = Route['method'];
-export type RoutePath = Route['path'];
+fromManifest(new Stack(app, 'Shop'), constructs, { Database: { vpc } }, backends);
 ```
 
-#### Using Manifest Types
-
-Import the manifest types for type-safe infrastructure configuration:
+The types narrow to what was declared:
 
 ```typescript
-import { manifest, type Route, type Authorizer } from './.gkm/manifest/aws';
+import { constructs, type Construct, type Surfaces } from './.gkm/manifest/aws';
 
-// Type-safe route iteration
-for (const route of manifest.routes) {
-  console.log(`${route.method} ${route.path} -> ${route.handler}`);
-}
+const api: Construct<'Api'> = constructs.Api;
 
-// Use union types for validation
-function isValidMethod(method: string): method is HttpMethod {
-  return manifest.routes.some((r) => r.method === method);
+for (const endpoint of api.endpoints) {
+  console.log(`${endpoint.method} ${endpoint.path} -> ${endpoint.handler}`);
 }
 
-// Access authorizer names
-const authorizers = new Set(manifest.routes.map((r) => r.authorizer));
+const surface: Surfaces = 'Api'; // any other id is a type error
 ```
 
 ## OpenAPI Generation
@@ -1675,17 +1640,17 @@ provider:
 
 functions:
   getUsers:
-    handler: .gkm/aws-apigatewayv1/getUsers.handler
+    handler: .gkm/aws/routes/getUsers.handler
     events:
-      - http:
-          path: users
+      - httpApi:
+          path: /users
           method: get
-  
+
   createUser:
-    handler: .gkm/aws-apigatewayv1/createUser.handler
+    handler: .gkm/aws/routes/createUser.handler
     events:
-      - http:
-          path: users
+      - httpApi:
+          path: /users
           method: post
 ```
 
@@ -1883,6 +1848,7 @@ Configure multiple patterns for complex project structures:
 import { defineConfig } from '@geekmidas/cli/config';
 
 export default defineConfig({
+  stages: { local: 'dev', deployed: ['prod'] },
   routes: [
     'src/routes/**/*.ts',
     'src/api/v1/**/*.ts',
@@ -1935,7 +1901,7 @@ Error: OpenAPI generation failed: Invalid endpoint schema
     "dev": "gkm dev",
     "dev:port": "gkm dev --port 8080",
     "build": "gkm build",
-    "build:lambda": "gkm build --provider aws-apigatewayv1",
+    "build:lambda": "gkm build --provider aws",
     "build:server": "gkm build --provider server",
     "docs": "gkm openapi --output src/api.ts"
   }
@@ -2029,8 +1995,8 @@ DEBUG=gkm:* npx gkm build
 ### Types
 
 ```typescript
-// Provider options
-type Provider = 'server' | 'aws-apigatewayv1' | 'aws-apigatewayv2';
+// Build targets
+type Provider = 'aws' | 'server';
 
 // Runtime options
 type Runtime = 'node' | 'bun';
@@ -2054,17 +2020,8 @@ interface DockerConfig {
   imageName?: string;       // Image name (defaults to package.json name)
   baseImage?: string;       // Base image (default: node:22-alpine)
   port?: number;            // Port to expose (default: 3000)
-  compose?: {
-    services?: ComposeServicesConfig | ComposeServiceName[];
-  };
 }
 
-// Service configuration for docker-compose
-type ComposeServiceName = 'postgres' | 'redis' | 'rabbitmq';
-type ComposeServicesConfig = {
-  [K in ComposeServiceName]?: boolean | { version?: string };
-};
-
 // Telescope configuration
 interface TelescopeConfig {
   enabled?: boolean;
@@ -2077,7 +2034,7 @@ interface TelescopeConfig {
 
 // Build options
 interface BuildOptions {
-  provider: Provider;
+  provider?: Provider; // default: where gkm.config.ts deploys
 }
 
 // Dev options