55 lines
2.5 KiB
Markdown
55 lines
2.5 KiB
Markdown
# Interactive Area Build CLI Design
|
|
|
|
## Scope
|
|
|
|
Add a zero-dependency terminal interface for choosing an area configuration and one or more existing
|
|
pipeline stages. It delegates execution to the existing `build-area.js` entry point and does not change
|
|
the pipeline's stage implementations or generated artifacts.
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
npm run build
|
|
-> scripts/interactive-build.js
|
|
-> terminal menus (TTY only)
|
|
-> node scripts/build-area.js --config <area> --stages <canonical-list>
|
|
-> existing build pipeline
|
|
```
|
|
|
|
Extract the stage metadata, aliases, canonical execution order, and mutual-exclusion validation from
|
|
`build-area.js` into a CommonJS module under `scripts/lib/`. Both the interactive script and
|
|
`build-area.js` consume this module, making the menu's options the same source of truth as execution.
|
|
|
|
## Interaction
|
|
|
|
1. Discover and sort `config/areas/*.json`; present a single-select area menu.
|
|
2. Present a multi-select stage menu with descriptions and selection markers.
|
|
3. Arrow keys move focus, space toggles, enter confirms, and Ctrl-C/Escape cancels.
|
|
4. The menu prevents or reports the `intermediates`/`reimport` conflict before spawning a build.
|
|
5. The selected stages are normalized to canonical pipeline order and passed to `build-area.js`.
|
|
|
|
The interactive entry requires both stdin and stdout to be TTYs. Otherwise it exits non-zero with an
|
|
instruction to use `npm run build:area -- --config ... --stages ...`; it never falls back to defaults.
|
|
|
|
## Compatibility
|
|
|
|
- `build-area.js` remains the execution owner and keeps its CLI flags and defaults.
|
|
- `npm run build:area` continues to invoke it directly.
|
|
- `npm run build` changes only from the former default build alias to the interactive wrapper.
|
|
- A successful `cesium` selection continues to generate preview output through the existing behavior;
|
|
selecting `preview` explicitly remains valid for a standalone preview refresh.
|
|
|
|
## Validation
|
|
|
|
- Unit-test stage normalization, alias expansion, ordering, and mutual exclusion.
|
|
- Unit-test config discovery and non-TTY refusal without launching a build.
|
|
- Syntax-check both CLI entry scripts.
|
|
- Manually exercise the menu in a TTY: select an area, select unordered stages, confirm the canonical
|
|
command preview, and cancel before execution.
|
|
|
|
## Risks And Rollback
|
|
|
|
Raw terminal input must always restore raw mode and cursor state on confirmation, cancellation, and
|
|
errors. The wrapper only spawns the unchanged existing build script, so rollback is deleting the new
|
|
interactive entry and restoring the `build` package script.
|