From e0cdf9e00b9c301bbe5db27afa090b19e6ebd692 Mon Sep 17 00:00:00 2001 From: que01 Date: Tue, 11 Aug 2026 15:31:34 +0800 Subject: [PATCH] chore(task): archive 08-11-interactive-area-cli --- .../08-11-interactive-area-cli/check.jsonl | 1 + .../08-11-interactive-area-cli/design.md | 54 +++++++++++++++++++ .../implement.jsonl | 1 + .../08-11-interactive-area-cli/implement.md | 13 +++++ .../2026-08/08-11-interactive-area-cli/prd.md | 53 ++++++++++++++++++ .../08-11-interactive-area-cli/task.json | 26 +++++++++ 6 files changed, 148 insertions(+) create mode 100644 .trellis/tasks/archive/2026-08/08-11-interactive-area-cli/check.jsonl create mode 100644 .trellis/tasks/archive/2026-08/08-11-interactive-area-cli/design.md create mode 100644 .trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.jsonl create mode 100644 .trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.md create mode 100644 .trellis/tasks/archive/2026-08/08-11-interactive-area-cli/prd.md create mode 100644 .trellis/tasks/archive/2026-08/08-11-interactive-area-cli/task.json diff --git a/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/check.jsonl b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/check.jsonl new file mode 100644 index 0000000..9dd3234 --- /dev/null +++ b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/check.jsonl @@ -0,0 +1 @@ +{"_example": "Fill with {\"file\": \"\", \"reason\": \"\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."} diff --git a/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/design.md b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/design.md new file mode 100644 index 0000000..9feb72c --- /dev/null +++ b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/design.md @@ -0,0 +1,54 @@ +# 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 --stages + -> 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. diff --git a/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.jsonl b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.jsonl new file mode 100644 index 0000000..9dd3234 --- /dev/null +++ b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.jsonl @@ -0,0 +1 @@ +{"_example": "Fill with {\"file\": \"\", \"reason\": \"\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."} diff --git a/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.md b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.md new file mode 100644 index 0000000..1022c3c --- /dev/null +++ b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/implement.md @@ -0,0 +1,13 @@ +# Interactive Area Build CLI Implementation Plan + +1. Extract stage definitions, aliases, canonical ordering, and conflict validation from + `scripts/build-area.js` into a shared CommonJS module. +2. Update `build-area.js` to consume the shared resolver without changing non-interactive semantics. +3. Add `scripts/interactive-build.js` with TTY detection, area discovery, raw-mode selection menus, + cancellation handling, and child-process delegation to `build-area.js`. +4. Change `package.json` so `npm run build` calls the new interactive script while `build:area` remains + unchanged. +5. Add focused Node tests for stage planning and non-TTY behavior; do not invoke Blender, QGIS, or a + real area build in tests. +6. Run syntax checks, the focused tests, existing preflight/preview tests, and manually exercise the + interactive flow in a TTY. diff --git a/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/prd.md b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/prd.md new file mode 100644 index 0000000..2370c59 --- /dev/null +++ b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/prd.md @@ -0,0 +1,53 @@ +# Interactive area build CLI + +## Goal + +提供一个交互式区域构建入口，减少手写 `npm run build:area -- --config ... --stages ...` +的频率；用户可选择区域和一个或多个构建阶段，CLI 按既有阶段约束执行。 + +## Confirmed Facts + +- 当前 `scripts/build-area.js` 支持 `intermediates`、`reimport`、`blender`、`cesium`、 + `preview` 与 `compress` 六个阶段，并接受逗号分隔的 `--stages`。 +- `intermediates` 与 `reimport` 互斥：前者会从 OSM 重建 GeoPackage，后者回导 QGIS 编辑。 +- 执行顺序固定为 `intermediates/reimport -> blender -> cesium -> preview -> compress`； + `cesium` 当前会自动写入 preview 产物。 +- 项目没有终端交互依赖；现有命令行调用必须继续可用于脚本和自动化。 + +## Requirements + +- R1：提供交互式入口，列出可用区域配置并允许用户选择目标区域。 +- R2：交互式入口允许一次选择多个阶段，并清晰展示阶段名称与用途。 +- R3：选择互斥阶段时必须阻止执行并解释原因；不得静默选择其中之一。 +- R4：执行多个阶段时必须使用既有依赖顺序，而非用户勾选顺序。 +- R5：保留 `npm run build:area -- --config ... --stages ...` 的现有非交互行为与语义。 +- R6：无 TTY、取消输入或无效输入时必须安全退出，不启动任何构建。 +- R7：TTY 交互使用方向键移动、空格多选、回车确认；菜单应显示当前选择状态。 +- R8：`npm run build` 启动交互式入口；`npm run build:area` 继续保留为非交互入口。 + +## Acceptance Criteria + +- [ ] 用户可从终端选择区域和多项阶段，无需手写配置路径或逗号分隔阶段名。 +- [ ] 选择 `intermediates` 与 `reimport` 时，CLI 明确报互斥错误且不运行构建。 +- [ ] 选择乱序的多个阶段时，实际执行顺序仍遵循既有管线顺序。 +- [ ] 既有非交互 `build:area` 调用保持兼容。 +- [ ] 取消或在非交互环境调用不会触发构建。 +- [ ] 用户可用方向键、空格和回车完成区域及阶段选择。 +- [ ] `npm run build` 启动交互菜单，`npm run build:area` 的现有调用保持不变。 + +## Key Decisions + +- 采用终端原生多选菜单，而非输入逗号分隔编号；避免引入运行时依赖。 +- `npm run build` 作为日常交互入口；`npm run build:area` 继续服务自动化和精确调用。 + +## Out Of Scope + +- 修改各 stage 的构建业务逻辑、依赖关系或产物格式。 +- 将巡航路线、QGIS 图层编辑或区域配置编辑纳入本次交互流程。 +- GUI 或浏览器界面的构建控制台。 + +## Notes + +- Keep `prd.md` focused on requirements, constraints, and acceptance criteria. +- Lightweight tasks can remain PRD-only. +- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`. diff --git a/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/task.json b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/task.json new file mode 100644 index 0000000..c35c3e4 --- /dev/null +++ b/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/task.json @@ -0,0 +1,26 @@ +{ + "id": "interactive-area-cli", + "name": "interactive-area-cli", + "title": "Interactive area build CLI", + "description": "", + "status": "completed", + "dev_type": null, + "scope": null, + "package": null, + "priority": "P2", + "creator": "dingkang", + "assignee": "dingkang", + "createdAt": "2026-08-11", + "completedAt": "2026-08-11", + "branch": null, + "base_branch": "main", + "worktree_path": null, + "commit": null, + "pr_url": null, + "subtasks": [], + "children": [], + "parent": null, + "relatedFiles": [], + "notes": "", + "meta": {} +} \ No newline at end of file