Merge v1.3.0 polish: validate command, snapshot safety, dry-run/validate-only, bug fixes

Author: nazarli-shabnam

.dev-env.example.yml

@@ -26,6 +26,7 @@ databases:
         command: npm run migrate
     seed:
       command: npm run seed
+      path: .  # optional: directory to run the seed command in (default ".")
 
   # - type: redis
   #   version: "7"
@@ -53,6 +54,13 @@ health_checks:
   # - name: redis
   #   type: redis
   #   url: redis://localhost:6379
+  # Generic (non-database) services can define a raw healthcheck command with `test`:
+  # - name: rabbitmq_1        # matches the generated service name, or use type
+  #   type: rabbitmq
+  #   test: rabbitmq-diagnostics -q ping
+  #   interval: 30s
+  #   timeout: 10s
+  #   retries: 5
 
 # Snapshot configuration
 snapshot:

.github/workflows/ci.yml

@@ -31,4 +31,12 @@ jobs:
         run: npm run build
 
       - name: Test
-        run: npm test
+        run: npm test -- --coverage
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-node-${{ matrix.node-version }}
+          path: coverage/
+          if-no-files-found: ignore

README.md

@@ -73,17 +73,35 @@ This installs dependencies, runs database migrations, and runs seed commands acc
 | `--skip-db`   | Skip database migrations and seed    |
 | `--dry-run`   | Show what would run, without running |
 
-### 3. Generate Docker Compose
+### 3. Validate your config
+
+Check that `.dev-env.yml` (and any `.env`) is well-formed without running setup or generate — handy for CI and pre-commit hooks:
+
+```bash
+envkit validate
+```
+
+It exits non-zero on a missing or invalid config. Add `--strict` to also fail on warnings (e.g. hardcoded passwords, port conflicts) and unresolved `${VAR}` references:
+
+```bash
+envkit validate --strict
+```
+
+### 4. Generate Docker Compose
 
 When `docker.enabled` is set in your config, you can generate a Compose file from it:
 
 ```bash
 envkit generate
 ```
 
-Output goes to `docker-compose.yml` by default. Use `-o <file>` to write elsewhere, e.g. `envkit generate -o docker-compose.dev.yml`.
+Output goes to `docker-compose.yml` by default. Use `-o <file>` to write elsewhere, e.g. `envkit generate -o docker-compose.dev.yml`. To preview the generated Compose without writing a file (e.g. to pipe or inspect it), use `--dry-run`:
 
-### 4. Snapshots
+```bash
+envkit generate --dry-run
+```
+
+### 5. Snapshots
 
 Save the current config as a named snapshot under `.devkit/snapshots/`:
 
@@ -97,13 +115,19 @@ If you omit the name, a timestamp-based name is used. List existing snapshots:
 envkit snapshot list
 ```
 
-Restore a snapshot (overwrites `.dev-env.yml`):
+Restore a snapshot. This overwrites `.dev-env.yml`, but your current config is automatically backed up to a `pre-restore-<timestamp>` snapshot first, and you'll be asked to confirm in an interactive terminal (use `--yes` to skip the prompt in scripts):
 
 ```bash
 envkit snapshot restore <name>
 ```
 
-### 5. Share config (export / import)
+Delete a snapshot you no longer need:
+
+```bash
+envkit snapshot delete <name>
+```
+
+### 6. Share config (export / import)
 
 Export a safe-to-share copy of your config (passwords and secrets become placeholders like `${DB_PASSWORD}`):
 
@@ -119,7 +143,11 @@ Import a shared config file (it is validated and then written to `.dev-env.yml`
 envkit share import path/to/dev-env.shared.yml
 ```
 
-Use `-o <file>` to write to a different path (also relative to the current directory unless you pass an absolute path).
+Use `-o <file>` to write to a different path (also relative to the current directory unless you pass an absolute path). To check a shared file is valid without writing anything (useful in CI), pass `--validate-only`:
+
+```bash
+envkit share import path/to/dev-env.shared.yml --validate-only
+```
 
 ### Global options
 
@@ -136,12 +164,14 @@ Example: `envkit -q setup`
 |--------|-------------|
 | `envkit init` | Create `.dev-env.yml` interactively (wizard). Run from a project folder when you don’t have a config yet. |
 | `envkit setup` | Install dependencies, run database migrations, and run seed commands from your config. Use `--skip-deps`, `--skip-db`, or `--dry-run` to limit what runs. |
-| `envkit generate` | Generate `docker-compose.yml` from your config (requires `docker.enabled` in config). Use `-o <file>` to set the output path. |
+| `envkit validate` | Validate `.dev-env.yml` (and `.env`) without running setup or generate. Add `--strict` to fail on warnings and unresolved `${VAR}` references. CI/pre-commit friendly. |
+| `envkit generate` | Generate `docker-compose.yml` from your config (requires `docker.enabled` in config). Use `-o <file>` to set the output path, or `--dry-run` to print without writing. |
 | `envkit snapshot create [name]` | Save the current `.dev-env.yml` as a snapshot under `.devkit/snapshots/`. Omit `name` to use a timestamp. |
 | `envkit snapshot list` | List all saved snapshots. |
-| `envkit snapshot restore <name>` | Restore a snapshot; overwrites `.dev-env.yml`. |
+| `envkit snapshot restore <name>` | Restore a snapshot; overwrites `.dev-env.yml` (current config is backed up first). Use `--yes` to skip the confirmation prompt. |
+| `envkit snapshot delete <name>` | Delete a saved snapshot. |
 | `envkit share export` | Export a sanitized config (secrets → placeholders) to share safely. Default output: `dev-env.shared.yml`; use `-o <file>` to override. |
-| `envkit share import <file>` | Import a shared config file; writes to `.dev-env.yml` by default. Use `-o <file>` to write elsewhere. |
+| `envkit share import <file>` | Import a shared config file; writes to `.dev-env.yml` by default. Use `-o <file>` to write elsewhere, or `--validate-only` to validate without writing. |
 | `envkit path-setup` or `envkit pathsetup` | Add the npm global bin folder to your PATH so `envkit` works from any directory. Use if the shell says “envkit” is not recognized after a global install. |
 
 For more detail: `envkit --help` or `envkit <command> --help`.

jest.config.js

@@ -11,6 +11,14 @@ module.exports = {
   ],
   coverageDirectory: 'coverage',
   coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      statements: 80,
+      branches: 55,
+      functions: 72,
+      lines: 80,
+    },
+  },
   verbose: true,
   clearMocks: true,
   restoreMocks: true,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-env-kit",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "One-command project setup, environment snapshots, and Docker Compose generation for local development",
   "main": "dist/cli/index.js",
   "bin": {

src/cli/index.ts

@@ -17,8 +17,9 @@ try {
 
 import { runSetup } from '../commands/setup';
 import { runGenerate } from '../commands/generate';
+import { runValidate } from '../commands/validate';
 import { runInit, isInteractive } from '../commands/init';
-import { runSnapshotCreate, runSnapshotList, runSnapshotRestore } from '../commands/snapshot';
+import { runSnapshotCreate, runSnapshotList, runSnapshotRestore, runSnapshotDelete } from '../commands/snapshot';
 import { runShareExport, runShareImport } from '../commands/share';
 import { runPathSetup } from '../commands/path-setup';
 import { findProjectRoot } from '../core/config/loader';
@@ -80,6 +81,19 @@ program
     }
   });
 
+program
+  .command('validate')
+  .description('Validate .dev-env.yml (and .env) without running setup or generate')
+  .option('--strict', 'Fail on warnings or unresolved ${VAR} references')
+  .action(async (options) => {
+    try {
+      await runValidate({ strict: options.strict });
+    } catch (err: unknown) {
+      logger.error((err as Error).message ?? 'Validation failed');
+      process.exit(1);
+    }
+  });
+
 const snapshotCommand = program
   .command('snapshot')
   .description('Manage environment snapshots');
@@ -111,24 +125,39 @@ snapshotCommand
 
 snapshotCommand
   .command('restore')
-  .description('Restore .dev-env.yml from a snapshot')
+  .description('Restore .dev-env.yml from a snapshot (backs up current config first)')
   .argument('<name>', 'Snapshot name')
-  .action(async (name) => {
+  .option('-y, --yes', 'Skip the overwrite confirmation prompt')
+  .action(async (name, options) => {
     try {
-      await runSnapshotRestore(name);
+      await runSnapshotRestore(name, { yes: options.yes });
     } catch (err: unknown) {
       logger.error((err as Error).message ?? 'Snapshot restore failed');
       process.exit(1);
     }
   });
 
+snapshotCommand
+  .command('delete')
+  .description('Delete a snapshot')
+  .argument('<name>', 'Snapshot name')
+  .action(async (name) => {
+    try {
+      await runSnapshotDelete(name);
+    } catch (err: unknown) {
+      logger.error((err as Error).message ?? 'Snapshot delete failed');
+      process.exit(1);
+    }
+  });
+
 program
   .command('generate')
   .description('Generate docker-compose.yml from configuration')
   .option('-o, --output <file>', 'Output file path', 'docker-compose.yml')
+  .option('--dry-run', 'Print the generated compose to stdout without writing a file')
   .action(async (options) => {
     try {
-      await runGenerate({ output: options.output });
+      await runGenerate({ output: options.output, dryRun: options.dryRun });
     } catch (err: any) {
       logger.error(err.message ?? 'Generate failed');
       process.exit(1);
@@ -157,9 +186,10 @@ shareCommand
   .description('Import shared configuration into project')
   .argument('<file>', 'Configuration file to import')
   .option('-o, --output <file>', 'Output file path', '.dev-env.yml')
+  .option('--validate-only', 'Validate the file without writing it')
   .action(async (file, options) => {
     try {
-      await runShareImport(file, { output: options.output });
+      await runShareImport(file, { output: options.output, validateOnly: options.validateOnly });
     } catch (err: unknown) {
       logger.error((err as Error).message ?? 'Share import failed');
       process.exit(1);

src/commands/generate.ts

@@ -7,6 +7,7 @@ import { writeFile } from '../utils/file-ops';
 
 export interface GenerateOptions {
   output?: string;
+  dryRun?: boolean;
 }
 
 function getTemplatesDir(): string {
@@ -36,6 +37,13 @@ export async function runGenerate(options: GenerateOptions = {}): Promise<void>
 
   const templatesDir = getTemplatesDir();
   const content = generateComposeContent(config, templatesDir);
+
+  if (options.dryRun) {
+    // Print to stdout without writing, so it can be inspected or piped.
+    process.stdout.write(content.endsWith('\n') ? content : content + '\n');
+    return;
+  }
+
   const outPath = path.isAbsolute(outputFile) ? outputFile : path.join(process.cwd(), outputFile);
 
   await writeFile(outPath, content);

src/commands/init.ts

@@ -184,10 +184,13 @@ async function runWizard(projectRoot: string): Promise<DevEnvConfig> {
     );
     if (addSeed.value) {
       const seedCmd = await prompts(
-        { type: 'text', name: 'command', message: 'Seed command', initial: 'npm run seed' },
+        [
+          { type: 'text', name: 'command', message: 'Seed command', initial: 'npm run seed' },
+          { type: 'text', name: 'path', message: 'Seed path', initial: '.' },
+        ],
         { onCancel: () => process.exit(0) }
       );
-      db.seed = { command: seedCmd.command || 'npm run seed' };
+      db.seed = { command: seedCmd.command || 'npm run seed', path: seedCmd.path?.trim() || '.' };
     }
     databases.push(db);
   }

src/commands/setup.ts

@@ -109,15 +109,17 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
         }
       }
       if (db.seed && !dryRun) {
+        const seedPath = db.seed.path ?? '.';
+        const cwd = path.resolve(projectRoot, seedPath);
         const { cmd, args } = parseCommand(db.seed.command);
-        logger.step(`Running seed (${db.type})...`);
+        logger.step(`Running seed (${db.type}) in ${seedPath}...`);
         await exec(cmd, args, {
-          cwd: projectRoot,
+          cwd,
           env: { ...process.env, ...env } as Record<string, string>,
           silent: false,
         });
       } else if (db.seed && dryRun) {
-        logger.info(`[dry-run] Would run seed: ${db.seed.command}`);
+        logger.info(`[dry-run] Would run seed in ${db.seed.path ?? '.'}: ${db.seed.command}`);
       }
     }
   } else if (skipDb) {

src/commands/share.ts

@@ -86,6 +86,7 @@ export async function runShareExport(options: ShareExportOptions = {}): Promise<
 
 export interface ShareImportOptions {
   output?: string;
+  validateOnly?: boolean;
 }
 
 export async function runShareImport(filePath: string, options: ShareImportOptions = {}): Promise<void> {
@@ -110,6 +111,11 @@ export async function runShareImport(filePath: string, options: ShareImportOptio
     throw new Error(`Invalid dev-env config in ${filePath}:\n${issues}`);
   }
 
+  if (options.validateOnly) {
+    logger.success(`${filePath} is a valid dev-env config.`);
+    return;
+  }
+
   const outputFile = (options.output?.trim() || '.dev-env.yml');
   const outPath = path.isAbsolute(outputFile) ? outputFile : path.join(process.cwd(), outputFile);