Tyler Gillispie
474cc177ce
- Add LICENSE-MIT and LICENSE-APACHE for dual MIT / Apache-2.0 distribution - Update root LICENSE pointer, README.md, Deno workspace manifests, and Cargo.toml - Add deno.lock dependency lockfile - Format AGENTS.md system guidelines - Import task lifecycle scaffolding and historical story specifications (extract-auth-yes, setup-ts architecture, modular workspace)
96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# 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:
|
|
```json
|
|
"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.
|