auth-yes/tasks/complete/2026-0821.02.jul.arch.setup-ts.shared-cli-architecture-1857.md

TASK METADATA

• Target Files: infra/setup.ts, auth-yes/infra/setup.ts
• Core Objective: Design a standardized 4-Layer CLI architecture to split the monolithic setup.ts into discrete, context-specific scripts for ed-droid and auth-yes while ensuring identical dual-mode ergonomics and adopting the concise infra/ directory standard.
• Dependencies: None.
• Additional Important Notes:
  • Standardize directory name to infra/ (replacing infra/).
  • Podman compose commands must explicitly specify --project-name (e.g., --project-name auth-yes, --project-name ed-droid).
  • Recommend a template approach over a shared library initially to avoid external bootstrap dependencies during local dev.
  • Maintain existing UX conventions via @cliffy and @std/fmt/colors.

---

Architectural Considerations & Risks

• Risks:
  • Divergence: Splitting into two scripts introduces the risk of the architectures drifting apart over time if the 4-layer template is not strictly adhered to.
  • Duplication: While mitigating external dependencies, the template approach inherently requires code duplication of standard patterns (e.g., config loading, command trees, TUI loops).
  • Bootstrap Failure: If an external library (e.g., from JSR) is used immediately, offline environments or initial setups might fail to run the script.
• Alternatives:
  • Shared Micro-Library: Extracting the common CLI framework into a standalone package like @atyg/setup-cli on JSR. This provides maximum DRYness but introduces external dependency risks during local bootstrapping. Recommended as a future phase once more standalone services exist.
  • Unified Monolith (Current State): Keep the unified infra/setup.ts. While simple for a single repo, it violates separation of concerns since auth-yes is treated as a standalone workspace/repository.

Proposed Implementation

1. Define the 4-Layer Architectural Template

Both the ed-droid and auth-yes CLI scripts (infra/setup.ts) must strictly implement this pattern:

1. Config/Dotenv Layer: Functions handling purely I/O reads/writes (e.g., readEnv(), generateEnv()).
2. Cliffy Command Tree (Headless/Scriptable): Definition of the CLI structure with standard subcommand verbs:
   • config: Generates/reviews .env and compose files non-interactively.
   • build: Executes podman build and pushes to registry.
   • test: Verifies health checks and service connectivity.
   • deploy: Runs podman-compose --project-name <name> --env-file <env> -f <compose> up -d.
   • Context-specific subcommands (spire, compile_proto for auth-yes; modules, handshake for ed-droid).
3. Interactive TUI Loop: The fallback wizard for human operators, using @cliffy/prompt to guide users if no subcommands/flags are passed.
4. Execution Engine: The core logic driving side effects like generating files, running container commands with explicit --project-name, or network requests.

2. Standardize on infra/ Directory & Split setup.ts

• Directory Naming: Adopt the concise infra/ convention across all repositories (e.g., infra/setup.ts, infra/compose.yml, infra/.env.example).
• auth-yes/infra/setup.ts:
  • Exclusively manages Auth-Yes, Spire/SPIFFE mTLS, Valkey/Postgres stack, and protobuf compilation.
  • Uses --project-name auth-yes for all compose lifecycle commands.
• ed-droid/infra/setup.ts:
  • Exclusively manages the Central Hub, UI modules, edge client handshake, and hub images.
  • Uses --project-name ed-droid for all compose lifecycle commands.

3. Standardize Ergonomics, UX & Deno Tasks

Ensure both target files share identical ergonomics:

• Utilize @std/fmt/colors consistently for logging and prompts.
• Maintain dual-mode behavior: Fail fast with clear errors in non-interactive environments unless explicit subcommands are passed.
• Add standard Deno task in both deno.json files:

  "tasks": {
    "setup": "deno run -A infra/setup.ts"
  }
  

4. Future Phase Consideration

Document within the repository the migration path to an @atyg/setup-cli JSR package once the ecosystem scales to additional standalone repositories.