feat(compose): consume network config, preserve source networks, validate refs, and support multi-file encrypted discovery (#66)

- Thread stack.network into GenerateOptions as required networkName; remove hardcoded NETWORK_NAME constant
- Preserve non-default merged source networks; config wins for logical default key
- Add collectAllServiceNetworkRefs for list and map syntax validation
- Reject dangling network references and network_mode plus networks coexistence
- Invalid stacks excluded from generated output, disk, render, and deploy
- Use Stack "name": reason error format for reload.ts compatibility
- Fix stackctl init to write traefik-public default instead of empty string
- Change secrets.encryptedFileName to string | string[] for multi-file discovery
- Add normalizeEncryptedFileNames with typed result object
- Update findEncryptedEnvFiles to accept filename list
- Resolve config before discovery in deployPipeline
- No-config fallback to [.env.enc] for encrypt/decrypt/clean/check
- No-argument encrypt derives plaintext names from configured encrypted names
- Fix secrets CLI dispatch to use new Command() pattern for Cliffy compatibility
- Map secrets config failures to ExitCode.UserConfigError
- Update README, migration.md, codemaps, and AGENTS.md for all behavior changes
- 427 tests pass, fmt:check, lint, and type-check clean

Closes #65

Author: wax911

AGENTS.md

@@ -45,7 +45,7 @@ These are enforced by CI. Match the repo style; the formatter is the authority.
 src/
   cli/mod.ts         — All CLI commands (one large file, ~1600 lines). Uses @cliffy/command.
   config/            — Config loading, merging, validation, init. Exports from mod.ts.
-  compose/           — Docker Compose discovery, generation, merging, transform, reload, sync, plan.
+  compose/           — Docker Compose discovery, generation, merging, transform, network validation, reload, sync, plan.
   render/            — ${VAR} interpolation in compose YAML.
   docker/            — Docker / Swarm CLI wrappers (stack deploy, rm, ps, services, swarm status, etc.).
   secrets/           — SOPS + age integration for encrypting .env files.

README.md

@@ -150,7 +150,17 @@ stack:
 
 With `--profile production`, the resolved config is built from all five files above: `names`
 becomes `[web, worker, cron]` (the profile's list replaces the base list, so any base-only
-entries are dropped) and `network` ends up as `acme-prod-network` (later layers win).
+entries are dropped) and `network` ends up as `acme-prod-network` (later layers win). The resolved
+`stack.network` value is consumed by generation as the physical name of the external logical
+`default` network. Source-defined non-default networks are preserved, while the config value wins
+if a source defines the logical `default` network. `stack.networkDriver` is reserved for future use
+and does not affect generated output in this release.
+
+Generation validates service network references against the final top-level declarations. A service
+that references an undeclared network produces an error and the stack is not generated, written, or
+deployed. A service that declares both `network_mode` (e.g. `host`) and explicit `networks` produces
+an error because Docker Compose considers these mutually exclusive. Services using `network_mode`
+without explicit `networks` are allowed and skip network validation.
 
 ### Precedence
 
@@ -173,9 +183,10 @@ invocation resolves to.
 ### Ignoring directories (stack.skipDirectories)
 
 `stack.skipDirectories` is the supported project ignore mechanism. Compose discovery walks the
-repository for `docker-compose.yml`/`docker-compose.yaml` files that declare `x-stack` metadata;
-any compose file found under a directory whose name is listed here is filtered out of the
-discovery result, so it is never generated or deployed:
+repository recursively, but only considers files named exactly `docker-compose.yml` or
+`docker-compose.yaml`, and only when they declare `x-stack` metadata. Any matching compose file
+found under a directory whose name is listed here is filtered out of the discovery result, so it
+is never generated or deployed:
 
 ```yaml
 # .stackctl
@@ -193,6 +204,26 @@ performs discovery (`generate`, `render`, `up`, `down`, `status`, `health`, `log
 `reload`, `plan`, `secrets`) honors the setting; `stackctl plan` prints the configured skip
 list when one is set.
 
+`stack.directory` is used by `doctor` and `sync` to locate generated stack files. It is not the
+generation destination: `generate` writes to `<repoRoot>/stacks` by default, or to the directory
+provided with `--output-dir`.
+
+`secrets.encryptedFileName` accepts one encrypted dotenv filename or a list of filenames. Secrets
+commands discover all configured filenames recursively, subject to their usual skipped directories.
+When no `.stackctl` config file exists, encrypt, decrypt, clean, and check fall back to the default
+`[".env.enc"]` list. `secrets deploy` requires a valid `.stackctl` config. When `secrets encrypt`
+is run without explicit file arguments, it derives plaintext filenames by stripping `.enc` from
+each configured encrypted name (e.g. `.env.enc` -> `.env`, `laravel.env.enc` -> `laravel.env`),
+walks for those plaintext files, and encrypts only the ones that do not already have an encrypted
+counterpart.
+
+Env status, env audit, and `doctor` encrypted-file checks currently support only `.env.enc` and do
+not discover multiple configured encrypted filenames. This is a known limitation planned for a
+future release.
+
+The `doctor --fix-volumes` option is currently a stub. It reports that external volume handling is
+not yet implemented and does not create missing volumes.
+
 ### Override files (--override)
 
 The `--override` flag applies Docker Compose override files to the generated stack data after

codemap.md

@@ -60,7 +60,8 @@ point.
    local overlays, and explicit override files into a validated `ResolvedConfig`.
 4. Compose workflows discover source compose files with `x-stack` metadata, load stack fragments,
    merge compose data, apply override files, transform service definitions for Swarm compatibility,
-   collect named volumes, and serialize stack YAML.
+   preserve non-default source networks while injecting the configured default network, validate
+   service network references, collect named volumes, and serialize stack YAML.
 5. Render workflows parse generated stack YAML, build service-specific interpolation scopes from the
    shell environment, `env_file` values, and inline service environment values, then substitute
    `${VAR}` and `$VAR` references.

docs/migration.md

@@ -78,31 +78,58 @@ Create a `.stackctl` file (generated via `stackctl init`):
 project: myproject
 
 stack:
-  # Root directory for service compose files (each must declare x-stack metadata)
+  # Directory used by doctor and sync to locate generated stack files
+  # (generate defaults to <repoRoot>/stacks instead)
   directory: ./stack
-  # Stack names to manage (empty = all discovered)
-  names: []
+  # Stack names to manage (must contain at least one name)
+  names:
+    - app
   # Default Docker network
   network: myproject_default
-  # Override files (profile or explicit)
-  overrides: []
+  # Reserved for future use; currently does not affect generated output
+  networkDriver: overlay
 
 render:
   # Output directory for rendered YAML
   outputDirectory: ./.rendered
-  # Fail on unresolved variables
-  strict: false
+
+secrets:
+  # One encrypted dotenv filename, or multiple filenames to discover
+  encryptedFileName: [".env.enc", ".env.production.enc"]
 ```
 
 ### Converting Environment Variables
 
-| Old Environment Variable | New Config Field                           | Example            |
-| ------------------------ | ------------------------------------------ | ------------------ |
-| `COMPOSE_DIR`            | `stack.directory`                          | `./docker-compose` |
-| `RENDER_DIR`             | `render.outputDirectory`                   | `./.rendered`      |
-| `STACKS_DIR`             | No equivalent (generated to `stacks/`)     | —                  |
-| `STACK_PREFIX`           | `project`                                  | `mystack`          |
-| `STACKCTL_PROFILE`       | `--profile` flag or `STACKCTL_PROFILE` env | `dev`              |
+| Old Environment Variable | New Config Field                           | Example               |
+| ------------------------ | ------------------------------------------ | --------------------- |
+| `COMPOSE_DIR`            | No direct equivalent                        | Repository-root scan |
+| `RENDER_DIR`             | `render.outputDirectory`                   | `./.rendered`         |
+| `STACKS_DIR`             | No equivalent (generated to `stacks/`)     | N/A                   |
+| `STACK_PREFIX`           | `project`                                  | `mystack`             |
+| `STACKCTL_PROFILE`       | `--profile` flag or `STACKCTL_PROFILE` env | `dev`                 |
+
+`stack.directory` is not the source directory for generation. The `generate` command recursively
+discovers exact `docker-compose.yml` and `docker-compose.yaml` files from the repository root and
+writes generated files to `<repoRoot>/stacks` by default, unless `--output-dir` is provided. The
+configured `stack.directory` is used by `doctor` and `sync` when locating generated stack files.
+
+The `secrets.encryptedFileName` field accepts either one encrypted dotenv filename or a list of
+filenames. When a list is configured, secrets commands discover all matching files recursively,
+subject to the usual skipped directories. When no `.stackctl` config file exists, encrypt, decrypt,
+clean, and check fall back to the default `[".env.enc"]` list. `secrets deploy` requires a valid
+`.stackctl` config. When `secrets encrypt` is run without explicit file arguments, it derives
+plaintext filenames by stripping `.enc` from each configured encrypted name, walks for those
+plaintext files, and encrypts only the ones without an existing encrypted counterpart.
+
+Env status, env audit, and `doctor` encrypted-file checks currently support only `.env.enc` and do
+not discover multiple configured encrypted filenames. This is a known limitation planned for a
+future release.
+
+Generation validates service network references against the final top-level declarations. A service
+referencing an undeclared network produces an error and the stack is not generated or deployed. A
+service declaring both `network_mode` and explicit `networks` produces an error because Docker
+Compose considers these mutually exclusive. Services using `network_mode` without explicit
+`networks` are allowed and skip network validation.
 
 ## Command Parity
 
@@ -148,11 +175,11 @@ echo "STACKCTL_PROFILE=${STACKCTL_PROFILE:-dev}"
 ### Step 2: Run `stackctl init`
 
 ```bash
-# Interactive detection (scans for docker-compose files)
-stackctl init
+# Detect repository layout (scans for compose files)
+stackctl init --detect
 
 # Or with explicit values
-stackctl init --project myproject --preset standard
+stackctl init --preset standard
 ```
 
 This creates `.stackctl` in your project root. Edit it to match your recorded configuration from
@@ -171,6 +198,9 @@ Fixes any issues reported:
 - Missing override files
 - Missing stack directories
 
+The `doctor --fix-volumes` option is exposed but not yet implemented. It reports this status and
+does not create missing external volumes.
+
 ### Step 4: Dry-Run a Deployment
 
 ```bash
@@ -251,6 +281,11 @@ Override files are applied _after_ profile merging but _before_ render.
 named stacks during discovery and generation. Every compose file must declare which
 stack it belongs to.
 
+Discovery recursively scans the repository root only for files named exactly
+`docker-compose.yml` or `docker-compose.yaml`. Files named `compose.yml`, `compose.yaml`, or
+other variants such as `docker-compose.dev.yml` are not discovered by generation. Matching files
+must also declare `x-stack` metadata.
+
 ### Supported Forms
 
 Two forms are supported:
@@ -364,9 +399,10 @@ docker swarm init
 ✗ Stack "myapp" not found in /path/to/project
 ```
 
-Check that your compose files declare `x-stack` metadata and are located within the
-configured `stack.directory`. See [Compose Metadata (`x-stack`)](#compose-metadata-x-stack)
-for supported forms.
+Check that your compose files use the exact names `docker-compose.yml` or `docker-compose.yaml`,
+declare `x-stack` metadata, and are located under the repository root. `stack.directory` is used by
+`doctor` and `sync` for generated stack files, not as the generation source directory. See
+[Compose Metadata (`x-stack`)](#compose-metadata-x-stack) for supported forms.
 
 ```yaml
 # docker-compose.yml -- either form works:
@@ -386,18 +422,16 @@ Common issues:
 
 - **Missing `project`**: Set the project name in `.stackctl`
 - **Missing `stack.network`**: Set the Docker network name
-- **Empty `stack.names`**: Leave as `[]` to discover all stacks, or list specific stack names
+- **Empty `stack.names`**: Provide at least one stack name; an empty list is rejected
 - **Invalid `render.outputDirectory`**: Must be a valid path
 
 ### Unresolved Environment Variables
 
-In strict mode (`render.strict: true`), unused variables cause failure. Switch to non-strict mode or
-provide the variables:
+In strict mode (`stackctl render --strict`), unresolved variables cause failure. Strictness is a
+CLI option, not a config field. Run without `--strict` for non-strict mode or provide the
+variables:
 
 ```bash
-# Non-strict mode
-echo 'render:\n  strict: false' >> .stackctl
-
 # Provide variable
 export MY_VAR=value
 stackctl up
@@ -452,7 +486,10 @@ This enables drift detection in CI.
 ### Signal Handling
 
 - **Old**: Ctrl-C may leave processes running
-- **New**: SIGINT is forwarded to child processes; `secrets deploy` runs cleanup on interruption
+- **New**: Commands that stream child process output (e.g. `up --logs`, `logs`) forward SIGINT
+  to the child. Most commands use non-streaming execution and do not forward signals. Secrets
+  cleanup is not automatic after an interrupted deployment; run `stackctl secrets clean` when
+  needed.
 
 ## Using stackctl in GitHub Actions