@geekmidas/cli 0.45.0 → 0.47.0

package/dist/{index-CXa3odEw.d.mts → index-A70abJ1m.d.mts}

@@ -5,20 +5,75 @@ import { z } from "zod/v4";
 
 /**
  * Deploy target for an app.
- * Currently only 'dokploy' is supported.
- * Future: 'vercel' | 'cloudflare'
+ *
+ * Specifies where the app will be deployed.
+ *
+ * @example
+ * ```ts
+ * // Currently supported
+ * deploy: 'dokploy'
+ *
+ * // Future support (not yet implemented)
+ * deploy: 'vercel'
+ * deploy: 'cloudflare'
+ * ```
  */
 type DeployTarget = 'dokploy' | 'vercel' | 'cloudflare';
 /**
  * Backend framework types for apps that don't use gkm routes.
+ *
+ * Used with `entry` to specify the framework for proper Docker builds.
+ *
+ * @example
+ * ```ts
+ * // Better Auth server
+ * {
+ *   entry: './src/index.ts',
+ *   framework: 'better-auth',
+ *   port: 3001,
+ * }
+ *
+ * // Hono app without gkm routes
+ * {
+ *   entry: './src/server.ts',
+ *   framework: 'hono',
+ *   port: 3000,
+ * }
+ * ```
  */
 type BackendFramework = 'hono' | 'better-auth' | 'express' | 'fastify';
 /**
  * Frontend framework types.
+ *
+ * @example
+ * ```ts
+ * // Next.js app
+ * {
+ *   type: 'frontend',
+ *   framework: 'nextjs',
+ *   port: 3000,
+ * }
+ *
+ * // Vite SPA
+ * {
+ *   type: 'frontend',
+ *   framework: 'vite',
+ *   port: 5173,
+ * }
+ * ```
  */
 type FrontendFramework = 'nextjs' | 'remix' | 'vite';
 /**
  * Service image configuration for custom Docker images.
+ *
+ * @example
+ * ```ts
+ * // Use specific version
+ * db: { version: '16-alpine' }
+ *
+ * // Use custom image
+ * db: { image: 'timescale/timescaledb:latest-pg16' }
+ * ```
  */
 interface ServiceImageConfig {
   /** Docker image version/tag (e.g., '18-alpine') */
@@ -28,6 +83,23 @@ interface ServiceImageConfig {
 }
 /**
  * Mail service configuration.
+ *
+ * In development, uses Mailpit for email testing.
+ * In production, uses SMTP configuration.
+ *
+ * @example
+ * ```ts
+ * services: {
+ *   mail: {
+ *     smtp: {
+ *       host: 'smtp.sendgrid.net',
+ *       port: 587,
+ *       user: 'apikey',
+ *       pass: process.env.SENDGRID_API_KEY,
+ *     }
+ *   }
+ * }
+ * ```
  */
 interface MailServiceConfig extends ServiceImageConfig {
   /** SMTP configuration for production */
@@ -40,6 +112,36 @@ interface MailServiceConfig extends ServiceImageConfig {
 }
 /**
  * Development services configuration.
+ *
+ * Configures shared infrastructure services like databases and caches.
+ * These are automatically provisioned in Dokploy during deployment.
+ *
+ * @example
+ * ```ts
+ * // Enable with defaults
+ * services: {
+ *   db: true,      // postgres:18-alpine
+ *   cache: true,   // redis:8-alpine
+ * }
+ *
+ * // Custom versions
+ * services: {
+ *   db: { version: '16-alpine' },
+ *   cache: { version: '7-alpine' },
+ * }
+ *
+ * // Custom images
+ * services: {
+ *   db: { image: 'timescale/timescaledb:latest-pg16' },
+ * }
+ *
+ * // With mail service
+ * services: {
+ *   db: true,
+ *   cache: true,
+ *   mail: true,  // Mailpit in dev
+ * }
+ * ```
  */
 interface ServicesConfig {
   /** PostgreSQL database (default: postgres:18-alpine) */
@@ -51,53 +153,192 @@ interface ServicesConfig {
 }
 /**
  * Stage-based domain configuration.
- * Maps deployment stages to base domains.
- * @example { development: 'dev.myapp.com', production: 'myapp.com' }
+ *
+ * Maps deployment stages to base domains. The main frontend app
+ * gets the base domain, other apps get `{appName}.{baseDomain}`.
+ *
+ * @example
+ * ```ts
+ * domains: {
+ *   development: 'dev.myapp.com',
+ *   staging: 'staging.myapp.com',
+ *   production: 'myapp.com',
+ * }
+ *
+ * // Result for production stage:
+ * // - web (main frontend): myapp.com
+ * // - api: api.myapp.com
+ * // - auth: auth.myapp.com
+ * ```
  */
 type DokployDomainsConfig = Record<string, string>;
 /**
  * Per-app domain override configuration.
- * Can be a single domain string or stage-specific domains.
- * @example 'api.custom.com' or { production: 'api.custom.com', staging: 'api.staging.com' }
+ *
+ * Can be a single domain string (used for all stages) or
+ * stage-specific domains.
+ *
+ * @example
+ * ```ts
+ * // Single domain for all stages
+ * domain: 'api.custom.com'
+ *
+ * // Stage-specific domains
+ * domain: {
+ *   development: 'api.dev.custom.com',
+ *   staging: 'api.staging.custom.com',
+ *   production: 'api.custom.com',
+ * }
+ * ```
  */
 type AppDomainConfig = string | Record<string, string>;
 /**
  * Dokploy workspace deployment configuration.
+ *
+ * Configures how the workspace is deployed to a Dokploy server.
+ * One workspace maps to one Dokploy project with stage-based environments.
+ *
+ * @example
+ * ```ts
+ * deploy: {
+ *   default: 'dokploy',
+ *   dokploy: {
+ *     endpoint: 'https://dokploy.myserver.com',
+ *     projectId: 'proj_abc123',
+ *     registry: 'ghcr.io/myorg',
+ *     domains: {
+ *       development: 'dev.myapp.com',
+ *       production: 'myapp.com',
+ *     },
+ *   },
+ * }
+ * ```
  */
 interface DokployWorkspaceConfig {
-  /** Dokploy API endpoint */
+  /** Dokploy API endpoint (e.g., 'https://dokploy.myserver.com') */
   endpoint: string;
-  /** Project ID (1 workspace = 1 project) */
+  /** Project ID in Dokploy (auto-created on first deploy) */
   projectId: string;
-  /** Container registry for images */
+  /** Container registry for Docker images (e.g., 'ghcr.io/myorg') */
   registry?: string;
-  /** Registry ID in Dokploy */
+  /** Registry ID in Dokploy (auto-configured) */
   registryId?: string;
   /**
    * Stage-based domain configuration.
    * The main frontend app gets the base domain.
    * Other apps get {appName}.{baseDomain} by default.
-   * @example { development: 'dev.myapp.com', production: 'myapp.com' }
    */
   domains?: DokployDomainsConfig;
 }
+/**
+ * DNS provider types for automatic DNS record creation.
+ */
+type DnsProvider = 'hostinger' | 'cloudflare' | 'manual';
+/**
+ * DNS configuration for automatic record creation during deployment.
+ *
+ * When configured, the deploy command will automatically create DNS
+ * A records pointing to your Dokploy server for each app's domain.
+ *
+ * @example
+ * ```ts
+ * // Auto-create DNS records at Hostinger
+ * dns: {
+ *   provider: 'hostinger',
+ *   domain: 'traflabs.io',
+ *   autoCreate: true,
+ * }
+ *
+ * // Manual mode - just print required records
+ * dns: {
+ *   provider: 'manual',
+ *   domain: 'traflabs.io',
+ * }
+ * ```
+ */
+interface DnsConfig {
+  /**
+   * DNS provider for automatic record creation.
+   * - 'hostinger': Use Hostinger DNS API
+   * - 'cloudflare': Use Cloudflare DNS API (future)
+   * - 'manual': Don't create records, just print required records
+   */
+  provider: DnsProvider;
+  /**
+   * Root domain where records will be created.
+   * @example 'traflabs.io', 'example.com'
+   */
+  domain: string;
+  /**
+   * Automatically create DNS records during deploy.
+   * If false, only prints required records for manual setup.
+   * @default true
+   */
+  autoCreate?: boolean;
+  /**
+   * TTL for created DNS records in seconds.
+   * @default 300 (5 minutes)
+   */
+  ttl?: number;
+}
 /**
  * Deployment configuration for the workspace.
+ *
+ * @example
+ * ```ts
+ * // Minimal - just set default target
+ * deploy: {
+ *   default: 'dokploy',
+ * }
+ *
+ * // Full configuration with DNS
+ * deploy: {
+ *   default: 'dokploy',
+ *   dokploy: {
+ *     endpoint: 'https://dokploy.myserver.com',
+ *     projectId: 'proj_abc123',
+ *     registry: 'ghcr.io/myorg',
+ *     domains: {
+ *       production: 'myapp.com',
+ *     },
+ *   },
+ *   dns: {
+ *     provider: 'hostinger',
+ *     domain: 'myapp.com',
+ *     autoCreate: true,
+ *   },
+ * }
+ * ```
  */
 interface DeployConfig {
-  /** Default deploy target for all apps */
+  /** Default deploy target for all apps (default: 'dokploy') */
   default?: DeployTarget;
   /** Dokploy-specific configuration */
   dokploy?: DokployWorkspaceConfig;
+  /** DNS configuration for automatic record creation */
+  dns?: DnsConfig;
 }
 /**
  * Models package configuration for shared schemas.
+ *
+ * Configures a shared models package containing Zod schemas
+ * that can be used across backend and frontend apps.
+ *
+ * @example
+ * ```ts
+ * shared: {
+ *   models: {
+ *     path: 'packages/models',
+ *     schema: 'zod',
+ *   },
+ * }
+ * ```
  */
 interface ModelsConfig {
-  /** Path to models package (default: packages/models) */
+  /** Path to models package relative to workspace root (default: 'packages/models') */
   path?: string;
   /**
-   * Schema library to use.
+   * Schema library to use (default: 'zod').
    * Currently only 'zod' is supported.
    * Future: any StandardSchema-compatible library
    */
@@ -105,6 +346,20 @@ interface ModelsConfig {
 }
 /**
  * Shared packages configuration.
+ *
+ * Configures shared packages in the monorepo that are
+ * used by multiple apps.
+ *
+ * @example
+ * ```ts
+ * shared: {
+ *   packages: ['packages/*', 'libs/*'],
+ *   models: {
+ *     path: 'packages/models',
+ *     schema: 'zod',
+ *   },
+ * }
+ * ```
  */
 interface SharedConfig {
   /** Glob patterns for shared packages (default: ['packages/*']) */
@@ -114,17 +369,45 @@ interface SharedConfig {
 }
 /**
  * Secrets encryption configuration.
+ *
+ * Configures how secrets are encrypted for deployment.
+ * Secrets are stored encrypted in `.gkm/secrets/{stage}.json`
+ * with keys stored separately in `~/.gkm/{project}/{stage}.key`.
+ *
+ * @example
+ * ```ts
+ * secrets: {
+ *   enabled: true,
+ *   algorithm: 'aes-256-gcm',
+ *   kdf: 'scrypt',
+ * }
+ * ```
  */
 interface SecretsConfig {
-  /** Enable encrypted secrets */
+  /** Enable encrypted secrets (default: true) */
   enabled?: boolean;
-  /** Encryption algorithm (default: aes-256-gcm) */
+  /** Encryption algorithm (default: 'aes-256-gcm') */
   algorithm?: string;
-  /** Key derivation function (default: scrypt) */
+  /** Key derivation function (default: 'scrypt') */
   kdf?: 'scrypt' | 'pbkdf2';
 }
 /**
  * Client generation configuration for frontend apps.
+ *
+ * Configures automatic API client generation from OpenAPI specs.
+ *
+ * @example
+ * ```ts
+ * // In a frontend app config
+ * {
+ *   type: 'frontend',
+ *   framework: 'nextjs',
+ *   dependencies: ['api'],
+ *   client: {
+ *     output: './src/lib/api',
+ *   },
+ * }
+ * ```
  */
 interface ClientConfig {
   /** Output directory for generated client (relative to app path) */
@@ -132,68 +415,204 @@ interface ClientConfig {
 }
 /**
  * Base app configuration properties (shared between input and normalized).
+ *
+ * @example
+ * ```ts
+ * // Backend app with gkm routes
+ * api: {
+ *   type: 'backend',
+ *   path: 'apps/api',
+ *   port: 3000,
+ *   routes: './src/endpoints/**\/*.ts',
+ *   envParser: './src/config/env',
+ *   logger: './src/config/logger',
+ * }
+ *
+ * // Backend app with entry point (e.g., Better Auth)
+ * auth: {
+ *   type: 'backend',
+ *   path: 'apps/auth',
+ *   port: 3001,
+ *   entry: './src/index.ts',
+ *   framework: 'better-auth',
+ *   requiredEnv: ['DATABASE_URL', 'BETTER_AUTH_SECRET'],
+ * }
+ *
+ * // Frontend app
+ * web: {
+ *   type: 'frontend',
+ *   path: 'apps/web',
+ *   port: 3002,
+ *   framework: 'nextjs',
+ *   dependencies: ['api', 'auth'],
+ * }
+ * ```
  */
 interface AppConfigBase {
-  /** App type (default: 'backend') */
+  /**
+   * App type.
+   * - 'backend': Server-side app (API, auth service, etc.)
+   * - 'frontend': Client-side app (Next.js, Vite, etc.)
+   * @default 'backend'
+   */
   type?: 'backend' | 'frontend';
-  /** Path relative to workspace root */
+  /**
+   * Path to the app relative to workspace root.
+   * @example 'apps/api', 'apps/web', 'services/auth'
+   */
   path: string;
-  /** Dev server port */
+  /**
+   * Development server port.
+   * Must be unique across all apps in the workspace.
+   * @example 3000, 3001, 3002
+   */
   port: number;
-  /** Per-app deploy target override */
+  /**
+   * Per-app deploy target override.
+   * Overrides `deploy.default` for this specific app.
+   * @example 'dokploy', 'vercel'
+   */
   deploy?: DeployTarget;
-  /** Routes glob pattern */
+  /**
+   * Routes glob pattern for gkm endpoints.
+   * @example './src/endpoints/**\/*.ts'
+   */
   routes?: Routes;
-  /** Functions glob pattern */
+  /**
+   * Functions glob pattern for Lambda functions.
+   * @example './src/functions/**\/*.ts'
+   */
   functions?: Routes;
-  /** Crons glob pattern */
+  /**
+   * Crons glob pattern for scheduled tasks.
+   * @example './src/crons/**\/*.ts'
+   */
   crons?: Routes;
-  /** Subscribers glob pattern */
+  /**
+   * Subscribers glob pattern for event handlers.
+   * @example './src/subscribers/**\/*.ts'
+   */
   subscribers?: Routes;
-  /** Path to environment parser module */
+  /**
+   * Path to environment parser module.
+   * @example './src/config/env'
+   */
   envParser?: string;
-  /** Path to logger module */
+  /**
+   * Path to logger module.
+   * @example './src/config/logger'
+   */
   logger?: string;
-  /** Provider configuration */
+  /** Provider configuration (AWS, Docker, etc.) */
   providers?: ProvidersConfig;
-  /** Server lifecycle hooks */
+  /**
+   * Server lifecycle hooks.
+   * @example { beforeSetup: './src/hooks/setup.ts' }
+   */
   hooks?: HooksConfig;
-  /** Telescope configuration */
+  /**
+   * Telescope debugging dashboard configuration.
+   * @example true, './src/config/telescope', { enabled: true, path: '/__telescope' }
+   */
   telescope?: string | boolean | TelescopeConfig;
-  /** Studio configuration */
+  /**
+   * Studio admin panel configuration.
+   * @example true, './src/config/studio'
+   */
   studio?: string | boolean | StudioConfig;
-  /** OpenAPI configuration */
+  /**
+   * OpenAPI documentation configuration.
+   * @example true, { output: './src/openapi.ts' }
+   */
   openapi?: boolean | OpenApiConfig;
-  /** Runtime (node or bun) */
+  /**
+   * Runtime environment.
+   * @default 'node'
+   */
   runtime?: Runtime;
-  /** Environment file(s) to load */
+  /**
+   * Environment file(s) to load during development.
+   * @example '.env', ['.env', '.env.local']
+   */
   env?: string | string[];
   /**
    * Entry file path for apps that don't use gkm routes.
-   * Used by both `gkm dev` (runs with tsx) and Docker builds (bundles with tsdown).
-   * @example './src/index.ts'
+   *
+   * When specified, the app is run directly with tsx in development
+   * and bundled with esbuild for production Docker builds.
+   *
+   * Use this for:
+   * - Better Auth servers
+   * - Custom Hono/Express apps
+   * - Any backend that doesn't use gkm's endpoint builder
+   *
+   * @example './src/index.ts', './src/server.ts'
    */
   entry?: string;
-  /** Framework for the app (frontend or backend without gkm routes) */
+  /**
+   * Framework for the app.
+   *
+   * Backend frameworks: 'hono', 'better-auth', 'express', 'fastify'
+   * Frontend frameworks: 'nextjs', 'remix', 'vite'
+   *
+   * @example 'nextjs', 'better-auth', 'hono'
+   */
   framework?: BackendFramework | FrontendFramework;
-  /** Client generation configuration */
+  /**
+   * Client generation configuration.
+   * Generates typed API client from backend dependencies.
+   */
   client?: ClientConfig;
   /**
-   * Override domain for this app (per-stage or single value).
-   * @example 'api.custom.com' or { production: 'api.custom.com', staging: 'api.staging.com' }
+   * Override domain for this app.
+   *
+   * By default, apps get `{appName}.{baseDomain}` (or just `{baseDomain}`
+   * for the main frontend). Use this to specify a custom domain.
+   *
+   * @example
+   * ```ts
+   * // Single domain for all stages
+   * domain: 'api.custom.com'
+   *
+   * // Stage-specific domains
+   * domain: {
+   *   production: 'api.custom.com',
+   *   staging: 'api.staging.custom.com',
+   * }
+   * ```
    */
   domain?: AppDomainConfig;
   /**
    * Required environment variables for entry-based apps.
+   *
    * Use this instead of envParser for apps that don't use gkm routes.
-   * The deploy command uses this to filter which secrets to embed.
-   * @example ['DATABASE_URL', 'BETTER_AUTH_SECRET']
+   * The deploy command uses this list to filter which secrets to embed
+   * in the Docker image.
+   *
+   * @example ['DATABASE_URL', 'BETTER_AUTH_SECRET', 'REDIS_URL']
    */
   requiredEnv?: string[];
 }
 /**
  * App configuration input with type-safe dependencies.
- * @template TAppNames - Union of valid app names in the workspace
+ *
+ * @template TAppNames - Union of valid app names in the workspace (auto-inferred)
+ *
+ * @example
+ * ```ts
+ * // Dependencies are type-checked against app names
+ * apps: {
+ *   api: { path: 'apps/api', port: 3000 },
+ *   auth: { path: 'apps/auth', port: 3001 },
+ *   web: {
+ *     path: 'apps/web',
+ *     port: 3002,
+ *     type: 'frontend',
+ *     dependencies: ['api', 'auth'],  // ✓ Valid
+ *     // dependencies: ['invalid'],   // ✗ Type error
+ *   },
+ * }
+ * ```
  */
 interface AppConfigInput<TAppNames extends string = string> extends AppConfigBase {
   /** Dependencies on other apps in the workspace (type-safe) */
@@ -226,13 +645,49 @@ type ConstrainedApps<TApps extends AppsRecord> = { [K in keyof TApps]: Omit<TApp
 } };
 /**
  * Full workspace input type with constrained dependencies.
+ *
+ * @example
+ * ```ts
+ * import { defineWorkspace } from '@geekmidas/cli';
+ *
+ * export default defineWorkspace({
+ *   name: 'my-app',
+ *   apps: {
+ *     api: {
+ *       path: 'apps/api',
+ *       port: 3000,
+ *       routes: './src/endpoints/**\/*.ts',
+ *     },
+ *     web: {
+ *       type: 'frontend',
+ *       path: 'apps/web',
+ *       port: 3001,
+ *       framework: 'nextjs',
+ *       dependencies: ['api'],
+ *     },
+ *   },
+ *   services: {
+ *     db: true,
+ *     cache: true,
+ *   },
+ *   deploy: {
+ *     default: 'dokploy',
+ *   },
+ * });
+ * ```
  */
 type WorkspaceInput<TApps extends AppsRecord> = {
+  /** Workspace name (defaults to root package.json name) */
   name?: string;
+  /** App definitions */
   apps: ConstrainedApps<TApps>;
+  /** Shared packages configuration */
   shared?: SharedConfig;
+  /** Deployment configuration */
   deploy?: DeployConfig;
+  /** Development services (db, cache, mail) */
   services?: ServicesConfig;
+  /** Encrypted secrets configuration */
   secrets?: SecretsConfig;
 };
 /**
@@ -255,8 +710,79 @@ type InferredWorkspaceConfig<TApps extends AppsRecord> = {
 /** @deprecated Use WorkspaceInput */
 
 /**
- * Workspace configuration for multi-app monorepos (legacy).
- * @deprecated Use WorkspaceConfigInput with defineWorkspace for type inference
+ * Workspace configuration for multi-app monorepos.
+ *
+ * Use `defineWorkspace()` helper for type-safe configuration with
+ * auto-completion and dependency validation.
+ *
+ * @example
+ * ```ts
+ * // gkm.config.ts
+ * import { defineWorkspace } from '@geekmidas/cli';
+ *
+ * export default defineWorkspace({
+ *   name: 'my-saas',
+ *
+ *   // App definitions
+ *   apps: {
+ *     // Backend API with gkm routes
+ *     api: {
+ *       path: 'apps/api',
+ *       port: 3000,
+ *       routes: './src/endpoints/**\/*.ts',
+ *       envParser: './src/config/env',
+ *       logger: './src/config/logger',
+ *       telescope: true,
+ *     },
+ *
+ *     // Better Auth service
+ *     auth: {
+ *       path: 'apps/auth',
+ *       port: 3001,
+ *       entry: './src/index.ts',
+ *       framework: 'better-auth',
+ *       requiredEnv: ['DATABASE_URL', 'BETTER_AUTH_SECRET'],
+ *     },
+ *
+ *     // Next.js frontend
+ *     web: {
+ *       type: 'frontend',
+ *       path: 'apps/web',
+ *       port: 3002,
+ *       framework: 'nextjs',
+ *       dependencies: ['api', 'auth'],
+ *     },
+ *   },
+ *
+ *   // Infrastructure services
+ *   services: {
+ *     db: true,      // PostgreSQL
+ *     cache: true,   // Redis
+ *   },
+ *
+ *   // Deployment configuration
+ *   deploy: {
+ *     default: 'dokploy',
+ *     dokploy: {
+ *       endpoint: 'https://dokploy.myserver.com',
+ *       projectId: 'proj_abc123',
+ *       registry: 'ghcr.io/myorg',
+ *       domains: {
+ *         production: 'myapp.com',
+ *         staging: 'staging.myapp.com',
+ *       },
+ *     },
+ *   },
+ *
+ *   // Shared packages
+ *   shared: {
+ *     packages: ['packages/*'],
+ *     models: { path: 'packages/models' },
+ *   },
+ * });
+ * ```
+ *
+ * @deprecated Use WorkspaceInput with defineWorkspace for type inference
  */
 interface WorkspaceConfig {
   /** Workspace name (defaults to root package.json name) */
@@ -274,11 +800,18 @@ interface WorkspaceConfig {
 }
 /**
  * Normalized app configuration with resolved defaults.
+ *
+ * This is the internal representation after processing user input.
+ * All optional fields have been resolved to their defaults.
  */
 interface NormalizedAppConfig extends Omit<AppConfigBase, 'type'> {
+  /** App type (always defined after normalization) */
   type: 'backend' | 'frontend';
+  /** Path to the app */
   path: string;
+  /** Development server port */
   port: number;
+  /** Resolved dependencies array (empty array if none) */
   dependencies: string[];
   /** Resolved deploy target (app.deploy > deploy.default > 'dokploy') */
   resolvedDeployTarget: DeployTarget;
@@ -293,14 +826,24 @@ interface NormalizedAppConfig extends Omit<AppConfigBase, 'type'> {
 }
 /**
  * Normalized workspace configuration with resolved defaults.
+ *
+ * This is the internal representation after processing user input.
+ * All optional fields have been resolved to their defaults.
  */
 interface NormalizedWorkspace {
+  /** Workspace name (resolved from package.json if not specified) */
   name: string;
+  /** Absolute path to workspace root */
   root: string;
+  /** Normalized app configurations */
   apps: Record<string, NormalizedAppConfig>;
+  /** Services configuration (empty object if not specified) */
   services: ServicesConfig;
+  /** Deploy configuration (empty object if not specified) */
   deploy: DeployConfig;
+  /** Shared packages configuration (empty object if not specified) */
   shared: SharedConfig;
+  /** Secrets configuration (empty object if not specified) */
   secrets: SecretsConfig;
 }
 /**
@@ -316,6 +859,15 @@ interface LoadedConfig {
 }
 /**
  * Type guard to check if a config is a WorkspaceConfig.
+ *
+ * @example
+ * ```ts
+ * const config = await loadConfig();
+ * if (isWorkspaceConfig(config)) {
+ *   // config.apps is available
+ *   console.log(Object.keys(config.apps));
+ * }
+ * ```
  */
 declare function isWorkspaceConfig(config: GkmConfig | WorkspaceConfig): config is WorkspaceConfig;
 //#endregion
@@ -557,4 +1109,4 @@ declare function getDependencyEnvVars(workspace: NormalizedWorkspace, appName: s
 
 //#endregion
 export { AppConfig, AppConfigInput, AppInput, AppsRecord, BackendFramework, ClientConfig, ConstrainedApps, DeployConfig, DeployTarget, DokployWorkspaceConfig, FrontendFramework, InferAppNames, InferredWorkspaceConfig, LoadedConfig, MailServiceConfig, ModelsConfig, NormalizedAppConfig, NormalizedWorkspace, PHASE_2_DEPLOY_TARGETS, SUPPORTED_DEPLOY_TARGETS, SecretsConfig, ServiceImageConfig, ServicesConfig, SharedConfig, WorkspaceConfig, WorkspaceConfigSchema, WorkspaceInput, defineWorkspace, formatValidationErrors, getAppBuildOrder, getAppGkmConfig, getDependencyEnvVars, getDeployTargetError, isDeployTargetSupported, isPhase2DeployTarget, isWorkspaceConfig, normalizeWorkspace, processConfig, safeValidateWorkspaceConfig, validateWorkspaceConfig, wrapSingleAppAsWorkspace };
-//# sourceMappingURL=index-CXa3odEw.d.mts.map
+//# sourceMappingURL=index-A70abJ1m.d.mts.map