@geekmidas/cli 0.44.0 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/dist/{config-C0b0jdmU.mjs → config-C3LSBNSl.mjs} +2 -2
  2. package/dist/{config-C0b0jdmU.mjs.map → config-C3LSBNSl.mjs.map} +1 -1
  3. package/dist/{config-xVZsRjN7.cjs → config-HYiM3iQJ.cjs} +2 -2
  4. package/dist/{config-xVZsRjN7.cjs.map → config-HYiM3iQJ.cjs.map} +1 -1
  5. package/dist/config.cjs +2 -2
  6. package/dist/config.d.cts +1 -1
  7. package/dist/config.d.mts +1 -1
  8. package/dist/config.mjs +2 -2
  9. package/dist/dokploy-api-C1JgU9Vr.mjs +3 -0
  10. package/dist/dokploy-api-Cpq_tLSz.cjs +3 -0
  11. package/dist/{dokploy-api-BdxOMH_V.cjs → dokploy-api-D8a0eQQB.cjs} +110 -1
  12. package/dist/dokploy-api-D8a0eQQB.cjs.map +1 -0
  13. package/dist/{dokploy-api-DWsqNjwP.mjs → dokploy-api-b6usLLKk.mjs} +110 -1
  14. package/dist/dokploy-api-b6usLLKk.mjs.map +1 -0
  15. package/dist/{index-CXa3odEw.d.mts → index-BtnjoghR.d.mts} +540 -46
  16. package/dist/index-BtnjoghR.d.mts.map +1 -0
  17. package/dist/{index-E8Nu2Rxl.d.cts → index-c89X2mi2.d.cts} +540 -46
  18. package/dist/index-c89X2mi2.d.cts.map +1 -0
  19. package/dist/index.cjs +254 -131
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.mjs +254 -131
  22. package/dist/index.mjs.map +1 -1
  23. package/dist/{openapi-D3pA6FfZ.mjs → openapi-C3C-BzIZ.mjs} +2 -2
  24. package/dist/{openapi-D3pA6FfZ.mjs.map → openapi-C3C-BzIZ.mjs.map} +1 -1
  25. package/dist/{openapi-DhcCtKzM.cjs → openapi-D7WwlpPF.cjs} +2 -2
  26. package/dist/{openapi-DhcCtKzM.cjs.map → openapi-D7WwlpPF.cjs.map} +1 -1
  27. package/dist/openapi.cjs +3 -3
  28. package/dist/openapi.mjs +3 -3
  29. package/dist/workspace/index.cjs +1 -1
  30. package/dist/workspace/index.d.cts +1 -1
  31. package/dist/workspace/index.d.mts +1 -1
  32. package/dist/workspace/index.mjs +1 -1
  33. package/dist/{workspace-BDAhr6Kb.cjs → workspace-CaVW6j2q.cjs} +10 -1
  34. package/dist/{workspace-BDAhr6Kb.cjs.map → workspace-CaVW6j2q.cjs.map} +1 -1
  35. package/dist/{workspace-D_6ZCaR_.mjs → workspace-DLFRaDc-.mjs} +10 -1
  36. package/dist/{workspace-D_6ZCaR_.mjs.map → workspace-DLFRaDc-.mjs.map} +1 -1
  37. package/package.json +4 -4
  38. package/src/deploy/dokploy-api.ts +163 -0
  39. package/src/deploy/index.ts +313 -225
  40. package/src/deploy/state.ts +146 -0
  41. package/src/workspace/types.ts +566 -47
  42. package/tsconfig.tsbuildinfo +1 -1
  43. package/dist/dokploy-api-Bdmk5ImW.cjs +0 -3
  44. package/dist/dokploy-api-BdxOMH_V.cjs.map +0 -1
  45. package/dist/dokploy-api-DWsqNjwP.mjs.map +0 -1
  46. package/dist/dokploy-api-tZSZaHd9.mjs +0 -3
  47. package/dist/index-CXa3odEw.d.mts.map +0 -1
  48. package/dist/index-E8Nu2Rxl.d.cts.map +0 -1
@@ -5,20 +5,75 @@ import { z } from "zod/v4";
5
5
 
6
6
  /**
7
7
  * Deploy target for an app.
8
- * Currently only 'dokploy' is supported.
9
- * Future: 'vercel' | 'cloudflare'
8
+ *
9
+ * Specifies where the app will be deployed.
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * // Currently supported
14
+ * deploy: 'dokploy'
15
+ *
16
+ * // Future support (not yet implemented)
17
+ * deploy: 'vercel'
18
+ * deploy: 'cloudflare'
19
+ * ```
10
20
  */
11
21
  type DeployTarget = 'dokploy' | 'vercel' | 'cloudflare';
12
22
  /**
13
23
  * Backend framework types for apps that don't use gkm routes.
24
+ *
25
+ * Used with `entry` to specify the framework for proper Docker builds.
26
+ *
27
+ * @example
28
+ * ```ts
29
+ * // Better Auth server
30
+ * {
31
+ * entry: './src/index.ts',
32
+ * framework: 'better-auth',
33
+ * port: 3001,
34
+ * }
35
+ *
36
+ * // Hono app without gkm routes
37
+ * {
38
+ * entry: './src/server.ts',
39
+ * framework: 'hono',
40
+ * port: 3000,
41
+ * }
42
+ * ```
14
43
  */
15
44
  type BackendFramework = 'hono' | 'better-auth' | 'express' | 'fastify';
16
45
  /**
17
46
  * Frontend framework types.
47
+ *
48
+ * @example
49
+ * ```ts
50
+ * // Next.js app
51
+ * {
52
+ * type: 'frontend',
53
+ * framework: 'nextjs',
54
+ * port: 3000,
55
+ * }
56
+ *
57
+ * // Vite SPA
58
+ * {
59
+ * type: 'frontend',
60
+ * framework: 'vite',
61
+ * port: 5173,
62
+ * }
63
+ * ```
18
64
  */
19
65
  type FrontendFramework = 'nextjs' | 'remix' | 'vite';
20
66
  /**
21
67
  * Service image configuration for custom Docker images.
68
+ *
69
+ * @example
70
+ * ```ts
71
+ * // Use specific version
72
+ * db: { version: '16-alpine' }
73
+ *
74
+ * // Use custom image
75
+ * db: { image: 'timescale/timescaledb:latest-pg16' }
76
+ * ```
22
77
  */
23
78
  interface ServiceImageConfig {
24
79
  /** Docker image version/tag (e.g., '18-alpine') */
@@ -28,6 +83,23 @@ interface ServiceImageConfig {
28
83
  }
29
84
  /**
30
85
  * Mail service configuration.
86
+ *
87
+ * In development, uses Mailpit for email testing.
88
+ * In production, uses SMTP configuration.
89
+ *
90
+ * @example
91
+ * ```ts
92
+ * services: {
93
+ * mail: {
94
+ * smtp: {
95
+ * host: 'smtp.sendgrid.net',
96
+ * port: 587,
97
+ * user: 'apikey',
98
+ * pass: process.env.SENDGRID_API_KEY,
99
+ * }
100
+ * }
101
+ * }
102
+ * ```
31
103
  */
32
104
  interface MailServiceConfig extends ServiceImageConfig {
33
105
  /** SMTP configuration for production */
@@ -40,6 +112,36 @@ interface MailServiceConfig extends ServiceImageConfig {
40
112
  }
41
113
  /**
42
114
  * Development services configuration.
115
+ *
116
+ * Configures shared infrastructure services like databases and caches.
117
+ * These are automatically provisioned in Dokploy during deployment.
118
+ *
119
+ * @example
120
+ * ```ts
121
+ * // Enable with defaults
122
+ * services: {
123
+ * db: true, // postgres:18-alpine
124
+ * cache: true, // redis:8-alpine
125
+ * }
126
+ *
127
+ * // Custom versions
128
+ * services: {
129
+ * db: { version: '16-alpine' },
130
+ * cache: { version: '7-alpine' },
131
+ * }
132
+ *
133
+ * // Custom images
134
+ * services: {
135
+ * db: { image: 'timescale/timescaledb:latest-pg16' },
136
+ * }
137
+ *
138
+ * // With mail service
139
+ * services: {
140
+ * db: true,
141
+ * cache: true,
142
+ * mail: true, // Mailpit in dev
143
+ * }
144
+ * ```
43
145
  */
44
146
  interface ServicesConfig {
45
147
  /** PostgreSQL database (default: postgres:18-alpine) */
@@ -51,53 +153,134 @@ interface ServicesConfig {
51
153
  }
52
154
  /**
53
155
  * Stage-based domain configuration.
54
- * Maps deployment stages to base domains.
55
- * @example { development: 'dev.myapp.com', production: 'myapp.com' }
156
+ *
157
+ * Maps deployment stages to base domains. The main frontend app
158
+ * gets the base domain, other apps get `{appName}.{baseDomain}`.
159
+ *
160
+ * @example
161
+ * ```ts
162
+ * domains: {
163
+ * development: 'dev.myapp.com',
164
+ * staging: 'staging.myapp.com',
165
+ * production: 'myapp.com',
166
+ * }
167
+ *
168
+ * // Result for production stage:
169
+ * // - web (main frontend): myapp.com
170
+ * // - api: api.myapp.com
171
+ * // - auth: auth.myapp.com
172
+ * ```
56
173
  */
57
174
  type DokployDomainsConfig = Record<string, string>;
58
175
  /**
59
176
  * Per-app domain override configuration.
60
- * Can be a single domain string or stage-specific domains.
61
- * @example 'api.custom.com' or { production: 'api.custom.com', staging: 'api.staging.com' }
177
+ *
178
+ * Can be a single domain string (used for all stages) or
179
+ * stage-specific domains.
180
+ *
181
+ * @example
182
+ * ```ts
183
+ * // Single domain for all stages
184
+ * domain: 'api.custom.com'
185
+ *
186
+ * // Stage-specific domains
187
+ * domain: {
188
+ * development: 'api.dev.custom.com',
189
+ * staging: 'api.staging.custom.com',
190
+ * production: 'api.custom.com',
191
+ * }
192
+ * ```
62
193
  */
63
194
  type AppDomainConfig = string | Record<string, string>;
64
195
  /**
65
196
  * Dokploy workspace deployment configuration.
197
+ *
198
+ * Configures how the workspace is deployed to a Dokploy server.
199
+ * One workspace maps to one Dokploy project with stage-based environments.
200
+ *
201
+ * @example
202
+ * ```ts
203
+ * deploy: {
204
+ * default: 'dokploy',
205
+ * dokploy: {
206
+ * endpoint: 'https://dokploy.myserver.com',
207
+ * projectId: 'proj_abc123',
208
+ * registry: 'ghcr.io/myorg',
209
+ * domains: {
210
+ * development: 'dev.myapp.com',
211
+ * production: 'myapp.com',
212
+ * },
213
+ * },
214
+ * }
215
+ * ```
66
216
  */
67
217
  interface DokployWorkspaceConfig {
68
- /** Dokploy API endpoint */
218
+ /** Dokploy API endpoint (e.g., 'https://dokploy.myserver.com') */
69
219
  endpoint: string;
70
- /** Project ID (1 workspace = 1 project) */
220
+ /** Project ID in Dokploy (auto-created on first deploy) */
71
221
  projectId: string;
72
- /** Container registry for images */
222
+ /** Container registry for Docker images (e.g., 'ghcr.io/myorg') */
73
223
  registry?: string;
74
- /** Registry ID in Dokploy */
224
+ /** Registry ID in Dokploy (auto-configured) */
75
225
  registryId?: string;
76
226
  /**
77
227
  * Stage-based domain configuration.
78
228
  * The main frontend app gets the base domain.
79
229
  * Other apps get {appName}.{baseDomain} by default.
80
- * @example { development: 'dev.myapp.com', production: 'myapp.com' }
81
230
  */
82
231
  domains?: DokployDomainsConfig;
83
232
  }
84
233
  /**
85
234
  * Deployment configuration for the workspace.
235
+ *
236
+ * @example
237
+ * ```ts
238
+ * // Minimal - just set default target
239
+ * deploy: {
240
+ * default: 'dokploy',
241
+ * }
242
+ *
243
+ * // Full Dokploy configuration
244
+ * deploy: {
245
+ * default: 'dokploy',
246
+ * dokploy: {
247
+ * endpoint: 'https://dokploy.myserver.com',
248
+ * projectId: 'proj_abc123',
249
+ * registry: 'ghcr.io/myorg',
250
+ * domains: {
251
+ * production: 'myapp.com',
252
+ * },
253
+ * },
254
+ * }
255
+ * ```
86
256
  */
87
257
  interface DeployConfig {
88
- /** Default deploy target for all apps */
258
+ /** Default deploy target for all apps (default: 'dokploy') */
89
259
  default?: DeployTarget;
90
260
  /** Dokploy-specific configuration */
91
261
  dokploy?: DokployWorkspaceConfig;
92
262
  }
93
263
  /**
94
264
  * Models package configuration for shared schemas.
265
+ *
266
+ * Configures a shared models package containing Zod schemas
267
+ * that can be used across backend and frontend apps.
268
+ *
269
+ * @example
270
+ * ```ts
271
+ * shared: {
272
+ * models: {
273
+ * path: 'packages/models',
274
+ * schema: 'zod',
275
+ * },
276
+ * }
277
+ * ```
95
278
  */
96
279
  interface ModelsConfig {
97
- /** Path to models package (default: packages/models) */
280
+ /** Path to models package relative to workspace root (default: 'packages/models') */
98
281
  path?: string;
99
282
  /**
100
- * Schema library to use.
283
+ * Schema library to use (default: 'zod').
101
284
  * Currently only 'zod' is supported.
102
285
  * Future: any StandardSchema-compatible library
103
286
  */
@@ -105,6 +288,20 @@ interface ModelsConfig {
105
288
  }
106
289
  /**
107
290
  * Shared packages configuration.
291
+ *
292
+ * Configures shared packages in the monorepo that are
293
+ * used by multiple apps.
294
+ *
295
+ * @example
296
+ * ```ts
297
+ * shared: {
298
+ * packages: ['packages/*', 'libs/*'],
299
+ * models: {
300
+ * path: 'packages/models',
301
+ * schema: 'zod',
302
+ * },
303
+ * }
304
+ * ```
108
305
  */
109
306
  interface SharedConfig {
110
307
  /** Glob patterns for shared packages (default: ['packages/*']) */
@@ -114,17 +311,45 @@ interface SharedConfig {
114
311
  }
115
312
  /**
116
313
  * Secrets encryption configuration.
314
+ *
315
+ * Configures how secrets are encrypted for deployment.
316
+ * Secrets are stored encrypted in `.gkm/secrets/{stage}.json`
317
+ * with keys stored separately in `~/.gkm/{project}/{stage}.key`.
318
+ *
319
+ * @example
320
+ * ```ts
321
+ * secrets: {
322
+ * enabled: true,
323
+ * algorithm: 'aes-256-gcm',
324
+ * kdf: 'scrypt',
325
+ * }
326
+ * ```
117
327
  */
118
328
  interface SecretsConfig {
119
- /** Enable encrypted secrets */
329
+ /** Enable encrypted secrets (default: true) */
120
330
  enabled?: boolean;
121
- /** Encryption algorithm (default: aes-256-gcm) */
331
+ /** Encryption algorithm (default: 'aes-256-gcm') */
122
332
  algorithm?: string;
123
- /** Key derivation function (default: scrypt) */
333
+ /** Key derivation function (default: 'scrypt') */
124
334
  kdf?: 'scrypt' | 'pbkdf2';
125
335
  }
126
336
  /**
127
337
  * Client generation configuration for frontend apps.
338
+ *
339
+ * Configures automatic API client generation from OpenAPI specs.
340
+ *
341
+ * @example
342
+ * ```ts
343
+ * // In a frontend app config
344
+ * {
345
+ * type: 'frontend',
346
+ * framework: 'nextjs',
347
+ * dependencies: ['api'],
348
+ * client: {
349
+ * output: './src/lib/api',
350
+ * },
351
+ * }
352
+ * ```
128
353
  */
129
354
  interface ClientConfig {
130
355
  /** Output directory for generated client (relative to app path) */
@@ -132,68 +357,204 @@ interface ClientConfig {
132
357
  }
133
358
  /**
134
359
  * Base app configuration properties (shared between input and normalized).
360
+ *
361
+ * @example
362
+ * ```ts
363
+ * // Backend app with gkm routes
364
+ * api: {
365
+ * type: 'backend',
366
+ * path: 'apps/api',
367
+ * port: 3000,
368
+ * routes: './src/endpoints/**\/*.ts',
369
+ * envParser: './src/config/env',
370
+ * logger: './src/config/logger',
371
+ * }
372
+ *
373
+ * // Backend app with entry point (e.g., Better Auth)
374
+ * auth: {
375
+ * type: 'backend',
376
+ * path: 'apps/auth',
377
+ * port: 3001,
378
+ * entry: './src/index.ts',
379
+ * framework: 'better-auth',
380
+ * requiredEnv: ['DATABASE_URL', 'BETTER_AUTH_SECRET'],
381
+ * }
382
+ *
383
+ * // Frontend app
384
+ * web: {
385
+ * type: 'frontend',
386
+ * path: 'apps/web',
387
+ * port: 3002,
388
+ * framework: 'nextjs',
389
+ * dependencies: ['api', 'auth'],
390
+ * }
391
+ * ```
135
392
  */
136
393
  interface AppConfigBase {
137
- /** App type (default: 'backend') */
394
+ /**
395
+ * App type.
396
+ * - 'backend': Server-side app (API, auth service, etc.)
397
+ * - 'frontend': Client-side app (Next.js, Vite, etc.)
398
+ * @default 'backend'
399
+ */
138
400
  type?: 'backend' | 'frontend';
139
- /** Path relative to workspace root */
401
+ /**
402
+ * Path to the app relative to workspace root.
403
+ * @example 'apps/api', 'apps/web', 'services/auth'
404
+ */
140
405
  path: string;
141
- /** Dev server port */
406
+ /**
407
+ * Development server port.
408
+ * Must be unique across all apps in the workspace.
409
+ * @example 3000, 3001, 3002
410
+ */
142
411
  port: number;
143
- /** Per-app deploy target override */
412
+ /**
413
+ * Per-app deploy target override.
414
+ * Overrides `deploy.default` for this specific app.
415
+ * @example 'dokploy', 'vercel'
416
+ */
144
417
  deploy?: DeployTarget;
145
- /** Routes glob pattern */
418
+ /**
419
+ * Routes glob pattern for gkm endpoints.
420
+ * @example './src/endpoints/**\/*.ts'
421
+ */
146
422
  routes?: Routes;
147
- /** Functions glob pattern */
423
+ /**
424
+ * Functions glob pattern for Lambda functions.
425
+ * @example './src/functions/**\/*.ts'
426
+ */
148
427
  functions?: Routes;
149
- /** Crons glob pattern */
428
+ /**
429
+ * Crons glob pattern for scheduled tasks.
430
+ * @example './src/crons/**\/*.ts'
431
+ */
150
432
  crons?: Routes;
151
- /** Subscribers glob pattern */
433
+ /**
434
+ * Subscribers glob pattern for event handlers.
435
+ * @example './src/subscribers/**\/*.ts'
436
+ */
152
437
  subscribers?: Routes;
153
- /** Path to environment parser module */
438
+ /**
439
+ * Path to environment parser module.
440
+ * @example './src/config/env'
441
+ */
154
442
  envParser?: string;
155
- /** Path to logger module */
443
+ /**
444
+ * Path to logger module.
445
+ * @example './src/config/logger'
446
+ */
156
447
  logger?: string;
157
- /** Provider configuration */
448
+ /** Provider configuration (AWS, Docker, etc.) */
158
449
  providers?: ProvidersConfig;
159
- /** Server lifecycle hooks */
450
+ /**
451
+ * Server lifecycle hooks.
452
+ * @example { beforeSetup: './src/hooks/setup.ts' }
453
+ */
160
454
  hooks?: HooksConfig;
161
- /** Telescope configuration */
455
+ /**
456
+ * Telescope debugging dashboard configuration.
457
+ * @example true, './src/config/telescope', { enabled: true, path: '/__telescope' }
458
+ */
162
459
  telescope?: string | boolean | TelescopeConfig;
163
- /** Studio configuration */
460
+ /**
461
+ * Studio admin panel configuration.
462
+ * @example true, './src/config/studio'
463
+ */
164
464
  studio?: string | boolean | StudioConfig;
165
- /** OpenAPI configuration */
465
+ /**
466
+ * OpenAPI documentation configuration.
467
+ * @example true, { output: './src/openapi.ts' }
468
+ */
166
469
  openapi?: boolean | OpenApiConfig;
167
- /** Runtime (node or bun) */
470
+ /**
471
+ * Runtime environment.
472
+ * @default 'node'
473
+ */
168
474
  runtime?: Runtime;
169
- /** Environment file(s) to load */
475
+ /**
476
+ * Environment file(s) to load during development.
477
+ * @example '.env', ['.env', '.env.local']
478
+ */
170
479
  env?: string | string[];
171
480
  /**
172
481
  * Entry file path for apps that don't use gkm routes.
173
- * Used by both `gkm dev` (runs with tsx) and Docker builds (bundles with tsdown).
174
- * @example './src/index.ts'
482
+ *
483
+ * When specified, the app is run directly with tsx in development
484
+ * and bundled with esbuild for production Docker builds.
485
+ *
486
+ * Use this for:
487
+ * - Better Auth servers
488
+ * - Custom Hono/Express apps
489
+ * - Any backend that doesn't use gkm's endpoint builder
490
+ *
491
+ * @example './src/index.ts', './src/server.ts'
175
492
  */
176
493
  entry?: string;
177
- /** Framework for the app (frontend or backend without gkm routes) */
494
+ /**
495
+ * Framework for the app.
496
+ *
497
+ * Backend frameworks: 'hono', 'better-auth', 'express', 'fastify'
498
+ * Frontend frameworks: 'nextjs', 'remix', 'vite'
499
+ *
500
+ * @example 'nextjs', 'better-auth', 'hono'
501
+ */
178
502
  framework?: BackendFramework | FrontendFramework;
179
- /** Client generation configuration */
503
+ /**
504
+ * Client generation configuration.
505
+ * Generates typed API client from backend dependencies.
506
+ */
180
507
  client?: ClientConfig;
181
508
  /**
182
- * Override domain for this app (per-stage or single value).
183
- * @example 'api.custom.com' or { production: 'api.custom.com', staging: 'api.staging.com' }
509
+ * Override domain for this app.
510
+ *
511
+ * By default, apps get `{appName}.{baseDomain}` (or just `{baseDomain}`
512
+ * for the main frontend). Use this to specify a custom domain.
513
+ *
514
+ * @example
515
+ * ```ts
516
+ * // Single domain for all stages
517
+ * domain: 'api.custom.com'
518
+ *
519
+ * // Stage-specific domains
520
+ * domain: {
521
+ * production: 'api.custom.com',
522
+ * staging: 'api.staging.custom.com',
523
+ * }
524
+ * ```
184
525
  */
185
526
  domain?: AppDomainConfig;
186
527
  /**
187
528
  * Required environment variables for entry-based apps.
529
+ *
188
530
  * Use this instead of envParser for apps that don't use gkm routes.
189
- * The deploy command uses this to filter which secrets to embed.
190
- * @example ['DATABASE_URL', 'BETTER_AUTH_SECRET']
531
+ * The deploy command uses this list to filter which secrets to embed
532
+ * in the Docker image.
533
+ *
534
+ * @example ['DATABASE_URL', 'BETTER_AUTH_SECRET', 'REDIS_URL']
191
535
  */
192
536
  requiredEnv?: string[];
193
537
  }
194
538
  /**
195
539
  * App configuration input with type-safe dependencies.
196
- * @template TAppNames - Union of valid app names in the workspace
540
+ *
541
+ * @template TAppNames - Union of valid app names in the workspace (auto-inferred)
542
+ *
543
+ * @example
544
+ * ```ts
545
+ * // Dependencies are type-checked against app names
546
+ * apps: {
547
+ * api: { path: 'apps/api', port: 3000 },
548
+ * auth: { path: 'apps/auth', port: 3001 },
549
+ * web: {
550
+ * path: 'apps/web',
551
+ * port: 3002,
552
+ * type: 'frontend',
553
+ * dependencies: ['api', 'auth'], // ✓ Valid
554
+ * // dependencies: ['invalid'], // ✗ Type error
555
+ * },
556
+ * }
557
+ * ```
197
558
  */
198
559
  interface AppConfigInput<TAppNames extends string = string> extends AppConfigBase {
199
560
  /** Dependencies on other apps in the workspace (type-safe) */
@@ -226,13 +587,49 @@ type ConstrainedApps<TApps extends AppsRecord> = { [K in keyof TApps]: Omit<TApp
226
587
  } };
227
588
  /**
228
589
  * Full workspace input type with constrained dependencies.
590
+ *
591
+ * @example
592
+ * ```ts
593
+ * import { defineWorkspace } from '@geekmidas/cli';
594
+ *
595
+ * export default defineWorkspace({
596
+ * name: 'my-app',
597
+ * apps: {
598
+ * api: {
599
+ * path: 'apps/api',
600
+ * port: 3000,
601
+ * routes: './src/endpoints/**\/*.ts',
602
+ * },
603
+ * web: {
604
+ * type: 'frontend',
605
+ * path: 'apps/web',
606
+ * port: 3001,
607
+ * framework: 'nextjs',
608
+ * dependencies: ['api'],
609
+ * },
610
+ * },
611
+ * services: {
612
+ * db: true,
613
+ * cache: true,
614
+ * },
615
+ * deploy: {
616
+ * default: 'dokploy',
617
+ * },
618
+ * });
619
+ * ```
229
620
  */
230
621
  type WorkspaceInput<TApps extends AppsRecord> = {
622
+ /** Workspace name (defaults to root package.json name) */
231
623
  name?: string;
624
+ /** App definitions */
232
625
  apps: ConstrainedApps<TApps>;
626
+ /** Shared packages configuration */
233
627
  shared?: SharedConfig;
628
+ /** Deployment configuration */
234
629
  deploy?: DeployConfig;
630
+ /** Development services (db, cache, mail) */
235
631
  services?: ServicesConfig;
632
+ /** Encrypted secrets configuration */
236
633
  secrets?: SecretsConfig;
237
634
  };
238
635
  /**
@@ -255,8 +652,79 @@ type InferredWorkspaceConfig<TApps extends AppsRecord> = {
255
652
  /** @deprecated Use WorkspaceInput */
256
653
 
257
654
  /**
258
- * Workspace configuration for multi-app monorepos (legacy).
259
- * @deprecated Use WorkspaceConfigInput with defineWorkspace for type inference
655
+ * Workspace configuration for multi-app monorepos.
656
+ *
657
+ * Use `defineWorkspace()` helper for type-safe configuration with
658
+ * auto-completion and dependency validation.
659
+ *
660
+ * @example
661
+ * ```ts
662
+ * // gkm.config.ts
663
+ * import { defineWorkspace } from '@geekmidas/cli';
664
+ *
665
+ * export default defineWorkspace({
666
+ * name: 'my-saas',
667
+ *
668
+ * // App definitions
669
+ * apps: {
670
+ * // Backend API with gkm routes
671
+ * api: {
672
+ * path: 'apps/api',
673
+ * port: 3000,
674
+ * routes: './src/endpoints/**\/*.ts',
675
+ * envParser: './src/config/env',
676
+ * logger: './src/config/logger',
677
+ * telescope: true,
678
+ * },
679
+ *
680
+ * // Better Auth service
681
+ * auth: {
682
+ * path: 'apps/auth',
683
+ * port: 3001,
684
+ * entry: './src/index.ts',
685
+ * framework: 'better-auth',
686
+ * requiredEnv: ['DATABASE_URL', 'BETTER_AUTH_SECRET'],
687
+ * },
688
+ *
689
+ * // Next.js frontend
690
+ * web: {
691
+ * type: 'frontend',
692
+ * path: 'apps/web',
693
+ * port: 3002,
694
+ * framework: 'nextjs',
695
+ * dependencies: ['api', 'auth'],
696
+ * },
697
+ * },
698
+ *
699
+ * // Infrastructure services
700
+ * services: {
701
+ * db: true, // PostgreSQL
702
+ * cache: true, // Redis
703
+ * },
704
+ *
705
+ * // Deployment configuration
706
+ * deploy: {
707
+ * default: 'dokploy',
708
+ * dokploy: {
709
+ * endpoint: 'https://dokploy.myserver.com',
710
+ * projectId: 'proj_abc123',
711
+ * registry: 'ghcr.io/myorg',
712
+ * domains: {
713
+ * production: 'myapp.com',
714
+ * staging: 'staging.myapp.com',
715
+ * },
716
+ * },
717
+ * },
718
+ *
719
+ * // Shared packages
720
+ * shared: {
721
+ * packages: ['packages/*'],
722
+ * models: { path: 'packages/models' },
723
+ * },
724
+ * });
725
+ * ```
726
+ *
727
+ * @deprecated Use WorkspaceInput with defineWorkspace for type inference
260
728
  */
261
729
  interface WorkspaceConfig {
262
730
  /** Workspace name (defaults to root package.json name) */
@@ -274,11 +742,18 @@ interface WorkspaceConfig {
274
742
  }
275
743
  /**
276
744
  * Normalized app configuration with resolved defaults.
745
+ *
746
+ * This is the internal representation after processing user input.
747
+ * All optional fields have been resolved to their defaults.
277
748
  */
278
749
  interface NormalizedAppConfig extends Omit<AppConfigBase, 'type'> {
750
+ /** App type (always defined after normalization) */
279
751
  type: 'backend' | 'frontend';
752
+ /** Path to the app */
280
753
  path: string;
754
+ /** Development server port */
281
755
  port: number;
756
+ /** Resolved dependencies array (empty array if none) */
282
757
  dependencies: string[];
283
758
  /** Resolved deploy target (app.deploy > deploy.default > 'dokploy') */
284
759
  resolvedDeployTarget: DeployTarget;
@@ -293,14 +768,24 @@ interface NormalizedAppConfig extends Omit<AppConfigBase, 'type'> {
293
768
  }
294
769
  /**
295
770
  * Normalized workspace configuration with resolved defaults.
771
+ *
772
+ * This is the internal representation after processing user input.
773
+ * All optional fields have been resolved to their defaults.
296
774
  */
297
775
  interface NormalizedWorkspace {
776
+ /** Workspace name (resolved from package.json if not specified) */
298
777
  name: string;
778
+ /** Absolute path to workspace root */
299
779
  root: string;
780
+ /** Normalized app configurations */
300
781
  apps: Record<string, NormalizedAppConfig>;
782
+ /** Services configuration (empty object if not specified) */
301
783
  services: ServicesConfig;
784
+ /** Deploy configuration (empty object if not specified) */
302
785
  deploy: DeployConfig;
786
+ /** Shared packages configuration (empty object if not specified) */
303
787
  shared: SharedConfig;
788
+ /** Secrets configuration (empty object if not specified) */
304
789
  secrets: SecretsConfig;
305
790
  }
306
791
  /**
@@ -316,6 +801,15 @@ interface LoadedConfig {
316
801
  }
317
802
  /**
318
803
  * Type guard to check if a config is a WorkspaceConfig.
804
+ *
805
+ * @example
806
+ * ```ts
807
+ * const config = await loadConfig();
808
+ * if (isWorkspaceConfig(config)) {
809
+ * // config.apps is available
810
+ * console.log(Object.keys(config.apps));
811
+ * }
812
+ * ```
319
813
  */
320
814
  declare function isWorkspaceConfig(config: GkmConfig | WorkspaceConfig): config is WorkspaceConfig;
321
815
  //#endregion
@@ -557,4 +1051,4 @@ declare function getDependencyEnvVars(workspace: NormalizedWorkspace, appName: s
557
1051
 
558
1052
  //#endregion
559
1053
  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 };
560
- //# sourceMappingURL=index-E8Nu2Rxl.d.cts.map
1054
+ //# sourceMappingURL=index-c89X2mi2.d.cts.map