feat(env): add .env scaffolding and profile preset support#23
Draft
wax911 wants to merge 17 commits into
Draft
Conversation
- Deno 2.x project structure with deno.json and task definitions - JSR dependencies: @cliffy/command, @std/assert, @std/testing, @std/yaml, @std/dotenv, @std/fs, @std/path - Full CLI command tree with stubs for all 15 issues - Shared interfaces (ProcessRunner, config types, ExitCode) for parallel work - FakeProcessRunner with recording, pre-programmed responses, and dry-run support - CI pipeline: fmt, lint, typecheck, test, coverage, and cross-platform build - .gitignore for generated and environment-specific files
- Default config values with sensible defaults - Deep merge for 5-layer config resolution (defaults -> base -> profile -> local -> local-profile) - Filesystem discovery (.stackctl, .stackctl.<profile>, .stackctl.local, .stackctl.local.<profile>) - Post-merge validation returning all errors at once - Template generation with inline comments, --detect, --preset, --profile, --force, --dry-run - STACKCTL_PROFILE env var support - 43 config tests + existing 15 = 58 passing - CLI init command wired to real implementation
Port of tools/generate_stacks.py from AniTrend/local-stack to idiomatic Deno TypeScript: - File discovery: walks repo root, finds docker-compose.yml/yaml files with x-stack metadata - Fragment loading: optional swarm.fragment.yml deep-merge per service - Compose deep merge (dict recursive, array replacement, scalar override) - Service transforms: strip compose-only keys (container_name, restart, build), inject logging defaults, rewrite env_file and bind-mount paths to repo-root relative - Named volume collection (external: true), default traefik-public overlay network - YAML output with header comment, --dry-run support - CLI generate command wired to real implementation - 60 compose tests + 58 existing = 118 passing
- composeOverrideMerge: scalars replace, maps merge, sequences append (distinct from fragment merge which replaces arrays) - loadOverrideFile: load YAML override from relative/absolute path - applyOverrides: load and apply chain of override files to base compose - Override integration in generateStacks via GenerateOptions.overrides - 26 tests covering all merge rules, file loading, edge cases - CLI generate command accepts --override flag
- Variable interpolation: ${VAR}, ${VAR-default}, ${VAR:-default}, $VAR, $$
- Variable scope resolution: shell env -> env_file(s) -> service.environment
- Deep interpolation through all string values in compose structures
- Path absolutization for env_file and bind-mount paths
- Strict mode (fail on unresolved) and non-strict mode (leave as-is with warnings)
- CLI pipeline: resolveConfig -> generateStacks -> renderStack -> output
- 49 comprehensive tests covering all interpolation forms and edge cases
Covers config migration, command mapping, profiles, overrides, rollback, troubleshooting, and behavior differences.
- Add composite action at .github/actions/setup-stackctl/action.yml - Support linux-x64, linux-arm64, macos-x64, macos-arm64 - Download from GitHub Releases, verify SHA256, cache in tool cache - Resolve latest version via GitHub API, accept explicit versions - Add PATH integration for subsequent workflow steps - Document CI usage in docs/migration.md Closes #11
- Add RealProcessRunner using Deno.Command with dry-run and signal forwarding - Add Docker CLI integration module (deploy, rm, services, ps, logs, info, swarm) - Add full sync pipeline: config -> discover -> generate -> render -> deploy - Wire CLI commands: up, down, status, logs, doctor, sync - Replace all issue #6 stubs with real implementations - Add 31 new tests (22 docker + 9 sync) all using FakeProcessRunner
- deno.json: add build:* tasks with Deno.compile for 4 targets - .github/workflows/release.yml: build matrix, SHA256 checksums, GitHub Releases - .github/workflows/ci.yml: update build stage to use renamed tasks
- Wire Cliffy CompletionsCommand for bash/zsh/fish/powershell completions - Add detailed descriptions to all CLI commands (2-3 sentences each) - Add .example() calls for every command with realistic usage patterns - Update deno.json import map with @cliffy/command/completions
Implements config-first, change-aware stack reload: - reloadStacks() in src/compose/reload.ts with SHA-256 checksum comparison - CLI wiring in src/cli/mod.ts with --skip-generate, --follow-logs, --dry-run - 19 unit tests covering dry-run, unchanged detection, deployment, error handling - Only deploys stacks whose rendered output has changed Ref: #9
- Add EnvExample, EnvDiff, CreateResult, BatchCreateResult types - Implement discoverEnvExamples with profile-driven discovery - Implement createEnvFromExample with dry-run and force support - Implement diffEnvFiles for key comparison - Add batchCreateEnvs helper for bulk operations - Wire env list, create, diff subcommands to CLI - Add 30 unit tests: discovery, creation, diff, batch ops Issue: #14
Implement encrypt, decrypt, deploy, clean, and check subcommands for managing SOPS-encrypted dotenv files with age keys. All operations go through the ProcessRunner interface enabling dry-run and test faking. - Add ToolingStatus, EncryptResult, DecryptResult, DeployResult, CleanResult types - Implement checkTooling() for sops/age availability detection - Implement resolveAgeKey() with config file, env var, and CLI flag resolution - Implement discoverEncryptedFiles() / discoverDecryptedFiles() for file discovery - Implement encryptFile() / decryptFile() with --dry-run support - Implement deploySecrets() for decrypting and creating Docker secrets - Implement cleanTempFiles() for removing .tmp and stray decrypted files - Add ageKeyFile and secretsDir to SecretsConfig - Wire all secrets subcommands in CLI with RealProcessRunner - Add 42 comprehensive tests using FakeProcessRunner Ref: #7
# Conflicts: # src/cli/mod.ts
wax911
commented
Jun 29, 2026
wax911
left a comment
wax911
left a comment
Member
Author
There was a problem hiding this comment.
Review notes against #14:
The PR body only claims discovery, listing missing files, recreate, force behavior, and non-secret scaffolding. The issue had several additional acceptance paths that need to be either implemented or explicitly deferred:
--pathsfiltering for explicit service directories/files.--profile dev --materialize/--from-profile devbehavior.env doctorwith sensitive plaintext warnings.- Status listing that distinguishes example files, active plaintext env files, encrypted env files, and profile variants.
- Backup behavior before forced overwrite.
- Dry-run coverage for every mutating path.
Please update the PR body and tests to prove these are covered, or narrow the issue/PR scope so it does not close #14 prematurely.
- Add baseConfigPath, profileConfigPath, localConfigPath fields to ResolvedConfig - Populate config path fields in resolveConfig / load.ts - Implement PlanJsonOutput interface with stable shape: operation, config (layers), stacks, steps, warnings, encryptedInputs, cleanupActions - plan never mutates files (all generation uses dryRun=true in-memory) - plan secrets deploy shows encryptedInputs and cleanupActions without decrypting - Report resolved config layers: base config path, profile overlay, local override - CLI plan command wired with human-readable and --json output - 16 tests covering structure, JSON shape, resolved layers, safety (never-mutate)
…mmands - Replace completions stubs with Cliffy CompletionsCommand for bash/zsh/fish - Add best-effort stack-name completion with graceful fallback on missing config - Add detailed help descriptions for down (destructive warning), secrets (sops/age dependency), sync (drift detection), reload (in-place redeploy) - Add stub exports for in-progress env features to unblock compilation - Add tests for completions shells and enhanced help text
wax911
commented
Jun 30, 2026
wax911
left a comment
wax911
left a comment
Member
Author
There was a problem hiding this comment.
Follow-up review after the push:
This PR is now draft, which is appropriate, but it is still not ready:
-
It still targets
mainand carries a cumulative diff. Retarget it to the correct predecessor branch once the stack order is settled. -
The PR body still only claims the smaller env subset and does not mention the previously missing acceptance paths:
--paths, profile materialization,env doctor, sensitive plaintext warnings, forced-overwrite backups, and dry-run coverage. -
Because the body still says
Closes #14, it currently overclaims completion unless those missing paths are implemented and tested.
Either broaden the implementation to fully close #14 or narrow the PR and split the remaining env requirements into follow-up issues.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #14