@geekmidas/cli 2.0.2 → 10.0.0-alpha.0

package/dist/{index-Bw548Bta.d.mts → types-C-arnQ1r.d.mts}

@@ -1,4 +1,4 @@
-import { EventsBackend, GkmConfig, HooksConfig, OpenApiConfig, ProvidersConfig, Routes, Runtime, StudioConfig, TelescopeConfig } from "./types-B3GQUg3k.mjs";
+import { ConstructManifest } from "@geekmidas/manifest";
 import { z } from "zod/v4";
 
 //#region src/deploy/state.d.ts
@@ -227,7 +227,28 @@ type FrontendFramework = z.infer<typeof FrontendFrameworkSchema>;
 /**
  * Mobile framework schema.
  */
-
+declare const MobileFrameworkSchema: z.ZodEnum<{
+  expo: "expo";
+}>;
+/**
+ * Mobile framework types. Derived from {@link MobileFrameworkSchema}.
+ *
+ * Mobile apps deploy via their own toolchain (e.g. EAS Build for Expo)
+ * rather than Docker/Dokploy. Only build-time public env vars
+ * (e.g. `EXPO_PUBLIC_*`) reach the device — server secrets are dropped.
+ *
+ * @example
+ * ```ts
+ * {
+ *   type: 'mobile',
+ *   framework: 'expo',
+ *   path: 'apps/mobile',
+ *   port: 8081,
+ *   dependencies: ['api'],
+ * }
+ * ```
+ */
+type MobileFramework = z.infer<typeof MobileFrameworkSchema>;
 /**
  * Combined framework schema (backend, frontend, or mobile).
  */
@@ -436,7 +457,11 @@ type BackupsConfig = z.infer<typeof BackupsConfigSchema>;
  */
 declare const WorkspaceConfigSchema: z.ZodObject<{
   name: z.ZodOptional<z.ZodString>;
-  apps: z.ZodRecord<z.ZodString, z.ZodObject<{
+  constructs: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+    paths: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    partition: z.ZodCustom<(filepath: string) => string, (filepath: string) => string>;
+  }, z.core.$strip>]>>;
+  apps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
     type: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
       backend: "backend";
       web: "web";
@@ -450,6 +475,10 @@ declare const WorkspaceConfigSchema: z.ZodObject<{
       vercel: "vercel";
       cloudflare: "cloudflare";
     }>>;
+    constructs: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+      paths: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+      partition: z.ZodCustom<(filepath: string) => string, (filepath: string) => string>;
+    }, z.core.$strip>]>>;
     routes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
       paths: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
       partition: z.ZodCustom<(filepath: string) => string, (filepath: string) => string>;
@@ -462,6 +491,14 @@ declare const WorkspaceConfigSchema: z.ZodObject<{
       paths: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
       partition: z.ZodCustom<(filepath: string) => string, (filepath: string) => string>;
     }, z.core.$strip>]>>;
+    queues: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+      paths: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+      partition: z.ZodCustom<(filepath: string) => string, (filepath: string) => string>;
+    }, z.core.$strip>]>>;
+    topics: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+      paths: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+      partition: z.ZodCustom<(filepath: string) => string, (filepath: string) => string>;
+    }, z.core.$strip>]>>;
     subscribers: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
       paths: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
       partition: z.ZodCustom<(filepath: string) => string, (filepath: string) => string>;
@@ -514,7 +551,7 @@ declare const WorkspaceConfigSchema: z.ZodObject<{
       client: z.ZodOptional<z.ZodString>;
       server: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-  }, z.core.$strip>>;
+  }, z.core.$strip>>>;
   shared: z.ZodOptional<z.ZodObject<{
     packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
     models: z.ZodOptional<z.ZodObject<{
@@ -693,7 +730,11 @@ declare const WorkspaceConfigSchema: z.ZodObject<{
     cache: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
       version: z.ZodOptional<z.ZodString>;
       image: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>>;
+    }, z.core.$strip>, z.ZodEnum<{
+      upstash: "upstash";
+      elasticache: "elasticache";
+      db: "db";
+    }>]>>;
     mail: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
       version: z.ZodOptional<z.ZodString>;
       image: z.ZodOptional<z.ZodString>;
@@ -703,7 +744,25 @@ declare const WorkspaceConfigSchema: z.ZodObject<{
         user: z.ZodOptional<z.ZodString>;
         pass: z.ZodOptional<z.ZodString>;
       }, z.core.$strip>>;
-    }, z.core.$strip>]>>;
+    }, z.core.$strip>, z.ZodEnum<{
+      resend: "resend";
+      ses: "ses";
+      smtp: "smtp";
+    }>]>>;
+    storage: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+      version: z.ZodOptional<z.ZodString>;
+      image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodEnum<{
+      minio: "minio";
+      s3: "s3";
+      r2: "r2";
+    }>]>>;
+    events: z.ZodOptional<z.ZodEnum<{
+      pgboss: "pgboss";
+      sns: "sns";
+      rabbitmq: "rabbitmq";
+    }>>;
+    trustLocalCa: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$strip>>;
   secrets: z.ZodOptional<z.ZodObject<{
     enabled: z.ZodOptional<z.ZodBoolean>;
@@ -882,16 +941,62 @@ interface MailServiceConfig extends ServiceImageConfig {
  * ```
  */
 interface ServicesConfig {
-  /** PostgreSQL database (default: postgres:18-alpine) */
-  db?: boolean | ServiceImageConfig;
-  /** Redis cache (default: redis:8-alpine) */
-  cache?: boolean | ServiceImageConfig;
-  /** Mail service (mailpit for dev) */
-  mail?: boolean | MailServiceConfig;
-  /** MinIO S3-compatible object storage (default: minio/minio:latest) */
-  storage?: boolean | ServiceImageConfig;
-  /** Event backend: pgboss (reuses postgres), sns (LocalStack), or rabbitmq */
+  /**
+   * Whether to install the local edge's certificate authority automatically.
+   *
+   * A declared `file-server` answers on `https://` locally, which needs a
+   * certificate, which needs an authority this machine trusts. Everything gkm
+   * starts trusts it already — reconcile injects `NODE_EXTRA_CA_CERTS` — but a
+   * *browser* asks the operating system, and until the root is in its store a
+   * local address reads as "not secure".
+   *
+   * Installing it needs `sudo`, so it is never silent by default:
+   *
+   * - unset — `gkm setup` asks once, on a machine that does not trust it yet,
+   *   and remembers a "no" so it stops asking.
+   * - `true` — install without asking. For a team that has decided, and for
+   *   any machine where a prompt has nobody to answer it.
+   * - `false` — never. Correct for CI, and for anyone who only ever reaches
+   *   these addresses from code, which trusts the root without any of this.
+   */
+  trustLocalCa?: boolean;
+  /**
+   * Where a declared cache lives — `'upstash'`, `'elasticache'` or `'db'`.
+   *
+   * A backend name and nothing else. Whether there *is* a cache comes from the
+   * manifest: declaring one implies its container the way declaring a database
+   * implies Postgres, so this only ever answers the second question.
+   *
+   * Defaults by target — see `DEFAULT_CACHE`.
+   */
+  cache?: CacheBackend;
+  /**
+   * Who delivers a declared app's mail — `'ses'`, `'resend'` or `'smtp'`.
+   *
+   * Locally every one of them is Mailpit, because every one speaks SMTP.
+   */
+  mail?: EmailBackend;
+  /** Where a declared bucket lives — `'minio'`, `'s3'` or `'r2'`. */
+  storage?: StorageBackend;
+  /** What carries a declared queue or topic — pgboss, sns or rabbitmq. */
   events?: EventsBackend;
+  /**
+   * Image pins for the containers the manifest derives.
+   *
+   * Separate from the backend names above, because they answer unrelated
+   * questions: a backend says where a thing lives, a pin says which image runs
+   * locally. They shared one key until `cache: true` meant "start a Redis" —
+   * which was the last way a container could exist because config asked for
+   * it rather than because something declared it.
+   *
+   * ```ts
+   * services: { cache: 'elasticache', images: { redis: 'redis:6-alpine' } }
+   * ```
+   *
+   * Pinning an image for a container nothing declares is a no-op, not an
+   * error: it says which image *would* run, and nothing runs.
+   */
+  images?: Partial<Record<ComposeServiceName, string>>;
 }
 /**
  * Stage-based domain configuration.
@@ -1163,6 +1268,16 @@ interface AppConfigBase {
    * @example 'dokploy', 'vercel'
    */
   deploy?: DeployTarget;
+  /**
+   * Constructs glob pattern — one glob, every kind.
+   *
+   * A glob per kind cannot find a resource, because a declared `ObjectStorage`
+   * has no kind to be listed under. This one is what reconcile reads to derive
+   * the containers a stage needs, and it replaces the per-kind globs below.
+   *
+   * @example './src/**\/*.ts'
+   */
+  constructs?: Routes;
   /**
    * Routes glob pattern for gkm endpoints.
    * @example './src/endpoints/**\/*.ts'
@@ -1178,6 +1293,16 @@ interface AppConfigBase {
    * @example './src/crons/**\/*.ts'
    */
   crons?: Routes;
+  /**
+   * Queues glob pattern for point-to-point workers.
+   * @example './src/queues/**\/*.ts'
+   */
+  queues?: Routes;
+  /**
+   * Topics glob pattern for the topics subscribers bind to.
+   * @example './src/topics/**\/*.ts'
+   */
+  topics?: Routes;
   /**
    * Subscribers glob pattern for event handlers.
    * @example './src/subscribers/**\/*.ts'
@@ -1388,10 +1513,23 @@ type ConstrainedApps<TApps extends AppsRecord> = { [K in keyof TApps]: Omit<TApp
  * ```
  */
 type WorkspaceInput<TApps extends AppsRecord> = {
+  /**
+   * Where the workspace's own constructs live, relative to its root.
+   *
+   * The product's infrastructure, declared once for every app that consumes
+   * it. Additive with an app's own glob rather than replacing it.
+   */
+  constructs?: Routes;
   /** Workspace name (defaults to root package.json name) */
   name?: string;
-  /** App definitions */
-  apps: ConstrainedApps<TApps>;
+  /**
+   * Apps that nothing declares.
+   *
+   * Normally absent: a `site` is an app and so is a `rest-api` that named
+   * one, so the list is read off the graph. This is the escape hatch for what
+   * no construct describes.
+   */
+  apps?: ConstrainedApps<TApps>;
   /** Shared packages configuration */
   shared?: SharedConfig;
   /** Deployment configuration */
@@ -1411,8 +1549,15 @@ type InferAppNames<TApps extends AppsRecord> = keyof TApps & string;
  * Inferred workspace config with proper app name types.
  */
 type InferredWorkspaceConfig<TApps extends AppsRecord> = {
+  /**
+   * Where the workspace's own constructs live, relative to its root.
+   *
+   * The product's infrastructure, declared once for every app that consumes
+   * it. Additive with an app's own glob rather than replacing it.
+   */
+  constructs?: Routes;
   name?: string;
-  apps: { [K in keyof TApps]: Omit<TApps[K], 'dependencies'> & {
+  apps?: { [K in keyof TApps]: Omit<TApps[K], 'dependencies'> & {
     dependencies?: InferAppNames<TApps>[];
   } };
   shared?: SharedConfig;
@@ -1499,10 +1644,17 @@ type InferredWorkspaceConfig<TApps extends AppsRecord> = {
  * @deprecated Use WorkspaceInput with defineWorkspace for type inference
  */
 interface WorkspaceConfig {
+  /**
+   * Where the workspace's own constructs live, relative to its root.
+   *
+   * The product's infrastructure, declared once for every app that consumes
+   * it. Additive with an app's own glob rather than replacing it.
+   */
+  constructs?: Routes;
   /** Workspace name (defaults to root package.json name) */
   name?: string;
-  /** App definitions */
-  apps: Record<string, AppConfig>;
+  /** Apps that nothing declares. Normally absent — see `WorkspaceInput`. */
+  apps?: Record<string, AppConfig>;
   /** Shared packages configuration */
   shared?: SharedConfig;
   /** Default deployment configuration */
@@ -1521,6 +1673,14 @@ interface WorkspaceConfig {
  * All optional fields have been resolved to their defaults.
  */
 interface NormalizedAppConfig extends Omit<AppConfigBase, 'type'> {
+  /**
+   * Whether the base domain points at this site.
+   *
+   * Carried from the `site` declaration rather than configured, because which
+   * site is primary is structural — its *hostname* is what varies by stage,
+   * and that is `domain`.
+   */
+  root?: boolean;
   /** App type (always defined after normalization) */
   type: 'backend' | 'web' | 'mobile';
   /** Path to the app */
@@ -1551,6 +1711,13 @@ interface NormalizedWorkspace {
   name: string;
   /** Absolute path to workspace root */
   root: string;
+  /**
+   * The workspace's own constructs glob, relative to `root`.
+   *
+   * Where the product's shared infrastructure is declared. Additive with each
+   * app's glob, so an app can still declare something only it uses.
+   */
+  constructs?: Routes;
   /** Normalized app configurations */
   apps: Record<string, NormalizedAppConfig>;
   /** Services configuration (empty object if not specified) */
@@ -1574,6 +1741,14 @@ interface LoadedConfig {
   raw: GkmConfig | WorkspaceConfig;
   /** Normalized workspace (always available) */
   workspace: NormalizedWorkspace;
+  /**
+   * What the workspace's constructs declared, when it has any.
+   *
+   * Read once at load, because the apps above are derived from it and a
+   * caller that re-discovers would be answering the same question twice with
+   * two chances to disagree. Absent when the workspace declares no constructs.
+   */
+  manifest?: ConstructManifest;
 }
 /**
  * Type guard to check if a config is a WorkspaceConfig.
@@ -1590,148 +1765,420 @@ interface LoadedConfig {
 declare function isWorkspaceConfig(config: GkmConfig | WorkspaceConfig): config is WorkspaceConfig;
 //# sourceMappingURL=types.d.ts.map
 //#endregion
-//#region src/workspace/publicEnv.d.ts
+//#region src/types.d.ts
+interface PartitionedRoutes {
+  paths: string | string[];
+  partition: (filepath: string) => string;
+}
+type Routes = string | string[] | PartitionedRoutes;
+interface ProviderConfig {
+  enabled?: boolean;
+  outputDir?: string;
+}
+interface AWSApiGatewayConfig extends ProviderConfig {}
+interface AWSLambdaConfig extends ProviderConfig {}
+interface ProductionConfig {
+  /** Enable production mode (default: false) */
+  enabled?: boolean;
+  /** Bundle server into single file (default: true) */
+  bundle?: boolean;
+  /** Minify bundled output (default: true) */
+  minify?: boolean;
+  /** Health check endpoint path (default: '/health') */
+  healthCheck?: string;
+  /** Enable graceful shutdown handling (default: true) */
+  gracefulShutdown?: boolean;
+  /** Packages to exclude from bundling (default: []) */
+  external?: string[];
+  /** Include subscribers in production build (default: 'exclude' for serverless) */
+  subscribers?: 'include' | 'exclude';
+  /** Include OpenAPI spec in production (default: false) */
+  openapi?: boolean;
+  /**
+   * Enable build-time optimized handler generation (default: true)
+   * Generates specialized handlers based on endpoint tier:
+   * - minimal: Near-raw-Hono performance for simple endpoints
+   * - standard: Optimized handlers for auth/services
+   * - full: Uses HonoEndpoint.addRoutes for complex endpoints
+   */
+  optimizedHandlers?: boolean;
+}
+/** Service-specific configuration for docker-compose */
+interface ServiceConfig {
+  /**
+   * Full Docker image reference (e.g., 'postgis/postgis:16-3.4-alpine').
+   * When specified, overrides the default image entirely.
+   */
+  image?: string;
+  /**
+   * Docker image version/tag (e.g., '15-alpine' for postgres).
+   * Only used when `image` is not specified.
+   */
+  version?: string;
+}
 /**
- * All public env-var prefixes the toolbox understands.
+ * Supported event backend types.
  *
- * Used when resolving incoming var names back to a dependency
- * (e.g. `VITE_AUTH_URL` → `auth`). A var matching any of these
- * is considered safe to inline into a client bundle.
+ * - `pgboss`: Reuses PostgreSQL with a dedicated user/schema. Auto-enables db service.
+ * - `sns`: Adds LocalStack container with SNS+SQS services.
+ * - `rabbitmq`: Adds RabbitMQ container.
+ *
+ * All backends generate EVENT_PUBLISHER_CONNECTION_STRING and EVENT_SUBSCRIBER_CONNECTION_STRING.
  */
-declare const PUBLIC_ENV_PREFIXES: readonly ["NEXT_PUBLIC_", "VITE_", "EXPO_PUBLIC_"];
+type EventsBackend = 'pgboss' | 'sns' | 'rabbitmq';
 /**
- * Resolve the public env-var prefix that a frontend framework's bundler
- * inlines into client code at build time:
+ * Where a declared cache actually lives.
  *
- *  - `nextjs`         → `NEXT_PUBLIC_`
- *  - `vite`           → `VITE_`
- *  - `tanstack-start` → `VITE_` (uses Vite under the hood)
- *  - `expo`           → `EXPO_PUBLIC_`
- *  - `remix`          → `''` (Remix exposes via loaders, no prefix convention)
+ * A deployment choice, not an application one — the same code caches into any
+ * of these — so it is config here beside `events` rather than a field on the
+ * construct. Each backend is consistent between local and deployed, which is
+ * the property worth having: a cache that behaves differently in the two places
+ * is worse than a slower one.
  *
- * For backend frameworks or unspecified, falls back to `NEXT_PUBLIC_` to
- * preserve the historical default. Backend apps never read these vars
- * from a bundle, so the prefix only affects scaffolding/symmetry.
+ * - `upstash` (default) — HTTP with a token. Reachable from a Lambda with no
+ *   VPC and no connection pool, which is why it is the default; locally the
+ *   `serverless-redis-http` proxy in front of Redis speaks the same protocol.
+ * - `elasticache` — the Redis wire protocol, inside a VPC. Locally, plain Redis.
+ * - `db` — a table in the database the app already declared. No infrastructure
+ *   at all, and the same relationship pg-boss has to Postgres: it creates its
+ *   own table on first use and needs a declared database to live in.
  */
-declare function getPublicEnvPrefix(framework?: Framework): string;
+type CacheBackend = 'upstash' | 'elasticache' | 'db';
 /**
- * Strip a known public prefix from a var name.
- * Returns the un-prefixed name, or `null` if no prefix matched.
- */
-declare function stripPublicPrefix(name: string): string | null;
-//# sourceMappingURL=publicEnv.d.ts.map
-
-//#endregion
-//#region src/workspace/index.d.ts
-/**
- * Define workspace configuration with full TypeScript support and type inference.
+ * Where a declared bucket actually lives.
  *
- * Uses `const` type parameter to infer literal app names, providing:
- * - Autocomplete for app names in dependencies
- * - Type errors for invalid dependency references
- * - Full type inference for the returned config
+ * The fourth of these selectors and the last to arrive, which is why
+ * `UPLOADS_URL` had no answer on a container target: there was nothing to
+ * choose with. Like the others it changes no application code — the `s3://`
+ * scheme picks the driver, and every one of these speaks it.
  *
- * @example
- * ```ts
- * // gkm.config.ts
- * import { defineWorkspace } from '@geekmidas/cli';
- *
- * export default defineWorkspace({
- *   name: 'my-saas',
- *   apps: {
- *     api: {
- *       type: 'backend',
- *       path: 'apps/api',
- *       port: 3000,
- *       routes: './src/endpoints/**\/*.ts',
- *       envParser: './src/config/env',
- *       logger: './src/logger',
- *     },
- *     web: {
- *       type: 'web',
- *       framework: 'nextjs',
- *       path: 'apps/web',
- *       port: 3001,
- *       dependencies: ['api'], // <- autocomplete shows 'api' | 'web'
- *     },
- *   },
- *   services: {
- *     db: true,
- *     cache: true,
- *   },
- * });
- *
- * // config.apps.api <- full type inference
- * // config.apps.foo <- TypeScript error
- * ```
- */
-declare function defineWorkspace<const TApps extends AppsRecord>(config: WorkspaceInput<TApps>): InferredWorkspaceConfig<TApps>;
-/**
- * Normalize a workspace configuration with resolved defaults.
- */
-declare function normalizeWorkspace(config: WorkspaceConfig, cwd: string): NormalizedWorkspace;
-/**
- * Wrap a single-app GkmConfig as a workspace.
- * This allows existing single-app configs to work seamlessly.
- */
-declare function wrapSingleAppAsWorkspace(config: GkmConfig, cwd: string): NormalizedWorkspace;
-/**
- * Process a loaded configuration (either single-app or workspace).
- * Returns a normalized workspace in both cases.
- */
-declare function processConfig(config: GkmConfig | WorkspaceConfig, cwd: string): LoadedConfig;
-/**
- * Get the GkmConfig for a specific app in a workspace.
- * Useful for running existing single-app commands on a specific app.
- */
-declare function getAppGkmConfig(workspace: NormalizedWorkspace, appName: string): GkmConfig | undefined;
-/**
- * Get topologically sorted app names based on dependencies.
- * Apps with no dependencies come first, then apps that depend on them.
+ * - `s3` — a real bucket. Nothing is created on the host; the URL is composed
+ *   against credentials you already hold, the same way `resend` is an API key
+ *   rather than infrastructure.
+ * - `r2` — Cloudflare's, reached through the same S3 API and differing only in
+ *   its endpoint.
+ * - `minio` — a container. Everything the app declares lives on the box, which
+ *   is what makes a single-host deploy self-contained, and what makes it a
+ *   single disk with no replication. Locally this is what every backend is.
  */
-declare function getAppBuildOrder(workspace: NormalizedWorkspace): string[];
+type StorageBackend = 'minio' | 's3' | 'r2';
 /**
- * Generate environment variables for app dependencies.
+ * The backend a project gets when it says nothing, by where it deploys.
+ *
+ * Flat defaults could not be right for both: `upstash` on a single box means a
+ * SaaS round-trip for a cache the database could have held, and `minio` on AWS
+ * means running a bucket beside S3. So the default is a function of the target,
+ * and an app that says nothing gets the obvious answer in both places — which
+ * is the whole of what "zero config" can mean once there is more than one
+ * target.
  *
- * Each dependency gets the un-prefixed `{DEP}_URL` (for server-side use) and,
- * when the consuming app's framework supports a public-var prefix, also the
- * prefixed form (e.g. `NEXT_PUBLIC_{DEP}_URL` for Next.js, `VITE_{DEP}_URL`
- * for Vite/TanStack Start). The prefixed form is what gets bundled into the
- * client at build time.
+ * `server` covers Dokploy and a bare host alike: the question these answer is
+ * whether the app is next to a managed cloud or next to its own containers, and
+ * on that question the two are the same.
+ *
+ * A per-construct, per-stage override is the layer above this — see
+ * `constructs-outstanding.md` — so two buckets in one app can differ. This is
+ * only what happens when nobody has said anything at all.
  */
-declare function getDependencyEnvVars(workspace: NormalizedWorkspace, appName: string, urlPrefix?: string): Record<string, string>;
+
 /**
- * Resolve the Dokploy endpoint for a specific stage.
+ * Who delivers a declared app's mail.
  *
- * Uses per-stage endpoint from `endpoints` if available,
- * otherwise falls back to the global `endpoint`.
+ * Unlike a cache, this changes *nothing* about the client. Every backend speaks
+ * SMTP, so the declaration's `smtp://` URL is true of all of them and only the
+ * provisioner differs — which is the same reason the declaration has no
+ * `provider` field and there is no `ses://` scheme.
  *
- * @param dokployConfig - Dokploy workspace configuration
- * @param stage - Deployment stage (e.g., 'development', 'production')
- * @returns The endpoint URL for the stage, or undefined if not configured
+ * - `ses` (default) — the only backend that can be a *chain* of resources: an
+ *   identity, a user, an access key, and an SMTP password derived from it,
+ *   because SES issues IAM credentials rather than SMTP ones. Hand it a URL and
+ *   it uses that instead, which is what you want when the credentials already
+ *   exist — provisioning a second set of sending credentials for an identity
+ *   that already has them is not a thing to do by default.
+ * - `resend` — an API key you hold, composed into an SMTP URL. Nothing to
+ *   provision: a SaaS account is not infrastructure.
+ * - `smtp` — a URL supplied whole, for a relay somebody else runs.
  *
- * @example
- * ```ts
- * // With per-stage endpoints
- * const config = {
- *   endpoints: {
- *     development: 'https://dev.dokploy.example.com:3000',
- *     production: 'https://prod.dokploy.example.com:3000',
- *   },
- * };
- * getEndpointForStage(config, 'production'); // => 'https://prod.dokploy.example.com:3000'
+ * Locally every one of them is Mailpit, because locally none of it matters.
+ */
+type EmailBackend = 'resend' | 'ses' | 'smtp';
+/**
+ * Who delivers mail when nobody said.
  *
- * // With single endpoint
- * const config = { endpoint: 'https://dokploy.example.com:3000' };
- * getEndpointForStage(config, 'production'); // => 'https://dokploy.example.com:3000'
- * ```
+ * Flat, unlike the others, and deliberately: mail is a SaaS on every target.
+ * There is no self-hosted preset to default a container deploy to — Mailpit is
+ * a development inbox, not a sender — so `server` has no answer of its own to
+ * give and would only be `ses` written twice.
  */
-declare function getEndpointForStage(dokployConfig: {
-  endpoint?: string;
-  endpoints?: Record<string, string>;
-} | undefined, stage: string): string | undefined;
-//# sourceMappingURL=index.d.ts.map
 
+/** Supported docker-compose service names */
+type ComposeServiceName = 'postgres' | 'redis' | 'rabbitmq' | 'minio' | 'mailpit' | 'localstack';
+/** Services configuration - can be boolean (use defaults) or object with version */
+type ComposeServicesConfig = { [K in ComposeServiceName]?: boolean | ServiceConfig };
+interface DockerConfig {
+  /** Container registry URL (e.g., 'ghcr.io/myorg') */
+  registry?: string;
+  /** Docker image name (default: derived from package.json name) */
+  imageName?: string;
+  /** Base Docker image (default: 'node:22-alpine') */
+  baseImage?: string;
+  /** Container port (default: 3000) */
+  port?: number;
+  /** docker-compose services to include */
+  compose?: {
+    /**
+     * Services to include in docker-compose.
+     * Can be an object with service configs or an array of service names (legacy).
+     *
+     * @example Object format (recommended)
+     * services: {
+     *   postgres: { version: '15-alpine' },
+     *   redis: true,  // use default version
+     * }
+     *
+     * @example Array format (legacy, uses default versions)
+     * services: ['postgres', 'redis']
+     */
+    services?: ComposeServicesConfig | ComposeServiceName[];
+  };
+}
+interface ServerConfig extends ProviderConfig {
+  enableOpenApi?: boolean;
+  port?: number;
+  /** Production build configuration */
+  production?: ProductionConfig;
+}
+type Runtime = 'node' | 'bun';
+interface TelescopeConfig {
+  /** Enable/disable telescope (default: true in development) */
+  enabled?: boolean;
+  /** Port for telescope to use (defaults to server port) */
+  port?: number;
+  /** Path prefix for telescope UI (default: /__telescope) */
+  path?: string;
+  /** Ignore patterns for telescope (e.g., ['/health', '/metrics']) */
+  ignore?: string[];
+  /** Record request/response bodies (default: true) */
+  recordBody?: boolean;
+  /** Maximum entries to keep in memory (default: 1000) */
+  maxEntries?: number;
+  /** Enable WebSocket for real-time updates (default: true, requires @hono/node-ws for Node.js) */
+  websocket?: boolean;
+}
+interface StudioConfig {
+  /** Enable/disable studio (default: true in development) */
+  enabled?: boolean;
+  /** Path prefix for studio UI (default: /__studio) */
+  path?: string;
+  /** Schema to introspect (default: 'public') */
+  schema?: string;
+}
+interface OpenApiConfig {
+  /** Enable OpenAPI generation (default: true) */
+  enabled?: boolean;
+  /** API title */
+  title?: string;
+  /** API version */
+  version?: string;
+  /** API description */
+  description?: string;
+}
+interface HooksConfig {
+  /**
+   * Path to a module exporting server lifecycle hooks.
+   * The module should export `beforeSetup` and/or `afterSetup` functions.
+   *
+   * @example
+   * ```typescript
+   * // src/config/hooks.ts
+   * import type { Hono } from 'hono';
+   * import type { Logger } from '@geekmidas/logger';
+   * import type { EnvironmentParser } from '@geekmidas/envkit';
+   *
+   * // Called BEFORE gkm endpoints are registered
+   * export function beforeSetup(app: Hono, ctx: { envParser: EnvironmentParser; logger: Logger }) {
+   *   app.use('*', cors());
+   *   app.get('/custom/health', (c) => c.json({ status: 'ok' }));
+   * }
+   *
+   * // Called AFTER gkm endpoints are registered
+   * export function afterSetup(app: Hono, ctx: { envParser: EnvironmentParser; logger: Logger }) {
+   *   app.notFound((c) => c.json({ error: 'Not found' }, 404));
+   *   app.onError((err, c) => c.json({ error: err.message }, 500));
+   * }
+   * ```
+   */
+  server?: string;
+}
+/** Dokploy deployment configuration */
+interface DokployProviderConfig {
+  /** Dokploy API endpoint (e.g., 'https://dokploy.example.com') */
+  endpoint: string;
+  /** Project ID in Dokploy */
+  projectId: string;
+  /** Application ID in Dokploy */
+  applicationId: string;
+  /** Container registry (overrides docker.registry if set) */
+  registry?: string;
+  /** Registry ID in Dokploy (recommended for private registries) */
+  registryId?: string;
+}
+interface ProvidersConfig {
+  aws?: {
+    apiGateway?: {
+      v1?: boolean | AWSApiGatewayConfig;
+      v2?: boolean | AWSApiGatewayConfig;
+    };
+    lambda?: {
+      functions?: boolean | AWSLambdaConfig;
+      crons?: boolean | AWSLambdaConfig;
+    };
+  };
+  server?: boolean | ServerConfig;
+  /** Dokploy deployment configuration */
+  dokploy?: boolean | DokployProviderConfig;
+}
+interface GkmConfig {
+  /**
+   * What this app is called, and therefore how everything it declares is named.
+   *
+   * The same field `sst.config.ts` carries, doing the same job: every physical
+   * name is `{stage}-{name}-{construct}`, so `Database` in the `production`
+   * stage of `kitchen-sink` is `production-kitchen-sink-database` on AWS and on
+   * Dokploy alike. One statement, in the config, rather than a rule each
+   * provider restates.
+   *
+   * `defineWorkspace` has always had this. A single-app config did not, so its
+   * names fell back to whatever the directory happened to be called — the
+   * monorepo's package name for the project and the app's for the application,
+   * two accidents of layout standing in for a decision.
+   *
+   * Defaults to the package.json name with any scope stripped, then the
+   * directory name.
+   */
+  name?: string;
+  /**
+   * Where the things no construct implies live.
+   *
+   * The same block a workspace config carries, and the same split: `db` and
+   * `storage` are derived from the declared `KyselyDatabase` and
+   * `ObjectStorage` and are ignored here, while `cache`, `mail`, and `events`
+   * name a *backend* — where the cache lives, who delivers the mail, which
+   * broker carries events. A single-app project had no way to say any of that
+   * before, so its event backend could only be guessed.
+   */
+  services?: ServicesConfig;
+  /**
+   * Constructs glob pattern — one glob, every kind.
+   *
+   * What reconcile reads to derive the containers a stage needs: a database
+   * implies Postgres, objects imply MinIO, mail implies Mailpit. A glob per
+   * kind cannot find a resource, because a declared `ObjectStorage` has no
+   * kind to be listed under.
+   *
+   * @example './src/**\/*.ts'
+   */
+  constructs?: Routes;
+  routes: Routes;
+  functions?: Routes;
+  crons?: Routes;
+  subscribers?: Routes;
+  queues?: Routes;
+  topics?: Routes;
+  envParser: string;
+  logger: string;
+  providers?: ProvidersConfig;
+  /**
+   * Server lifecycle hooks for customizing the Hono app.
+   * Allows adding custom routes, middleware, error handlers, etc.
+   *
+   * @example
+   * hooks: {
+   *   server: './src/config/hooks'
+   * }
+   */
+  hooks?: HooksConfig;
+  /**
+   * Telescope configuration for debugging/monitoring.
+   * Can be:
+   * - A string path to a module that exports a Telescope instance (recommended)
+   * - A boolean to enable/disable with defaults
+   * - A TelescopeConfig object for inline configuration
+   */
+  telescope?: string | boolean | TelescopeConfig;
+  /**
+   * Studio configuration for database browsing.
+   * Can be:
+   * - A string path to a module that exports a Studio instance (recommended)
+   * - A boolean to enable/disable with defaults
+   * - A StudioConfig object for inline configuration
+   *
+   * Requires a database connection configured via services.
+   */
+  studio?: string | boolean | StudioConfig;
+  /**
+   * OpenAPI generation configuration.
+   * Can be:
+   * - A boolean to enable/disable with defaults (output: ./src/api/openapi.ts)
+   * - An OpenApiConfig object for customization
+   *
+   * When enabled, OpenAPI spec is generated on startup and regenerated on route changes.
+   *
+   * @example
+   * openapi: true
+   *
+   * @example
+   * openapi: {
+   *   output: './src/api/openapi.ts',
+   *   title: 'My API',
+   *   version: '1.0.0',
+   * }
+   */
+  openapi?: boolean | OpenApiConfig;
+  /** Runtime to use for dev server (default: 'node') */
+  runtime?: Runtime;
+  /**
+   * Environment file(s) to load for development.
+   * Can be:
+   * - A string path to a single env file (e.g., '.env.local')
+   * - An array of paths to load in order (later files override earlier)
+   * - Defaults to '.env' if not specified
+   *
+   * @example
+   * env: '.env.local'
+   *
+   * @example
+   * env: ['.env', '.env.local']
+   */
+  env?: string | string[];
+  /**
+   * Docker deployment configuration.
+   * Used by `gkm docker` and `gkm prepack` commands.
+   *
+   * @example
+   * docker: {
+   *   registry: 'ghcr.io/myorg',
+   *   imageName: 'my-api',
+   *   compose: {
+   *     services: ['postgres', 'redis']
+   *   }
+   * }
+   */
+  docker?: DockerConfig;
+  /**
+   * Where this app deploys, and what the target needs to know.
+   *
+   * Absent until now, which meant a single-app project could not configure a
+   * Dokploy deploy at all: the wrap that turns one into a workspace hardcoded
+   * `{ default: 'dokploy' }` and dropped everything else, so there was no
+   * endpoint, no registry and no domain — and `resolveHost` failed with "no
+   * domain configured for stage" on a config that had nowhere to put one.
+   *
+   * The same shape a workspace config uses, so moving from one to the other is
+   * a rename rather than a rewrite.
+   */
+  deploy?: DeployConfig;
+}
 //#endregion
-export { AppConfig, AppConfigInput, AppInput, AppsRecord, BackendFramework, ConstrainedApps, DeployConfig, DeployTarget, DokployWorkspaceConfig, FrontendFramework, InferAppNames, InferredWorkspaceConfig, LoadedConfig, MailServiceConfig, ModelsConfig, NormalizedAppConfig, NormalizedWorkspace, PHASE_2_DEPLOY_TARGETS, PUBLIC_ENV_PREFIXES, SUPPORTED_DEPLOY_TARGETS, SecretsConfig, ServiceImageConfig, ServicesConfig, SharedConfig, WorkspaceConfig, WorkspaceConfigSchema, WorkspaceInput, defineWorkspace, formatValidationErrors, getAppBuildOrder, getAppGkmConfig, getDependencyEnvVars, getDeployTargetError, getEndpointForStage, getPublicEnvPrefix, isDeployTargetSupported, isPhase2DeployTarget, isWorkspaceConfig, normalizeWorkspace, processConfig, safeValidateWorkspaceConfig, stripPublicPrefix, validateWorkspaceConfig, wrapSingleAppAsWorkspace };
-//# sourceMappingURL=index-Bw548Bta.d.mts.map
+export { AppConfig, AppConfigInput, AppInput, AppsRecord, BackendFramework, CacheBackend, ConstrainedApps, DeployConfig, DeployTarget, DokployWorkspaceConfig, EmailBackend, Framework, FrontendFramework, GkmConfig, InferAppNames, InferredWorkspaceConfig, LoadedConfig, MailServiceConfig, MobileFramework, ModelsConfig, NormalizedAppConfig, NormalizedWorkspace, OpenApiConfig, PHASE_2_DEPLOY_TARGETS, Routes, SUPPORTED_DEPLOY_TARGETS, SecretsConfig, ServiceImageConfig, ServicesConfig, SharedConfig, WorkspaceConfig, WorkspaceConfigSchema, WorkspaceInput, formatValidationErrors, getDeployTargetError, isDeployTargetSupported, isPhase2DeployTarget, isWorkspaceConfig, safeValidateWorkspaceConfig, validateWorkspaceConfig };
+//# sourceMappingURL=types-C-arnQ1r.d.mts.map