diff --git a/.trellis/tasks/archive/2026-09/09-17-local-build-console/check.jsonl b/.trellis/tasks/archive/2026-09/09-17-local-build-console/check.jsonl new file mode 100644 index 0000000..9dd3234 --- /dev/null +++ b/.trellis/tasks/archive/2026-09/09-17-local-build-console/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-09/09-17-local-build-console/design.md b/.trellis/tasks/archive/2026-09/09-17-local-build-console/design.md new file mode 100644 index 0000000..6c9ebe6 --- /dev/null +++ b/.trellis/tasks/archive/2026-09/09-17-local-build-console/design.md @@ -0,0 +1,60 @@ +# 本地构建控制台设计 + +## Architecture + +新增 `npm run console` 启动的本机控制服务。服务只绑定 `127.0.0.1`,启动后打开默认浏览器;它以 Node 内置 `http` 提供 JSON API、Server-Sent Events(SSE)和无构建的静态 HTML/CSS/JS。首版不引入 React、Vite、Electron 或数据库。 + +```text +browser UI + │ HTTP / SSE, localhost only + ▼ +scripts/build-console.js + ├─ configs + diagnostics + stage manifests → area/history cards + ├─ import OSM/ZIP → inputs/console// + ownership record + ├─ spawn node scripts/build-area.js → streamed build log/job state + ├─ serve outputs// as read-only preview assets + └─ validated cleanup target → macOS Trash +``` + +`build-area.js` continues to own all pipeline stages. The console does not import it in-process or duplicate its business logic; it starts it as a child process with `--config` and optional `--stages`, collecting stdout/stderr for the UI. + +## Data and ownership + +At startup the service enumerates `config/areas/*.json`, calls the existing `readAreaConfig()` / diagnostics APIs, and reads stage manifests. Those files are the history source of truth. + +The import form copies selected OSM and ZIP files into `inputs/console//`. A local ignored ownership record under `.build-console/areas/.json` records the configuration filename, managed input paths, ZIP hash, and output directory. It exists only to prove which files the console may clean; ordinary historical configs with external paths remain usable but do not grant deletion authority over those sources. + +The ZIP `areaId` is immutable and becomes configuration `id`. Because an explicit Save As must not collide with its source config or generated output, the user-facing configuration key is a separate filesystem-safe slug; a saved copy gets a distinct config filename and explicit `outputs.areaDir` / `fileStem` derived from that key. The package contract keeps the original ZIP `areaId`. + +## User flow + +1. **Welcome / readiness**: display a short three-step guide and checks for Node, Blender, writable managed input directory, and existing areas. Explain that OSM supplies buildings/landscape while ZIP supplies authoritative roads. +2. **History**: show every `config/areas/*.json` as a card with input locations, tree style, output health, last successful stage and links to preview/package when present. +3. **Import / Save As**: choose OSM and ZIP, inspect ZIP contract and locked `areaId`, choose tree style, select a config key, then copy inputs and atomically write a new config. Existing config edits default to Save As; overwrite requires a typed/explicit confirmation. +4. **Build**: choose standard full build or individual existing stages. At most one build job may run; SSE reports stdout/stderr, named stage progression, completion marker and a concise actionable error summary. +5. **Preview**: link to a read-only `/artifacts//...` route that serves the generated preview HTML and its package-relative assets. Vehicle selection stays in the existing preview runtime, rather than changing build artifacts. +6. **Cleanup**: cards and multi-select provide (a) Clear build outputs and (b) Remove area. A confirmation screen lists regions, file counts and byte totals. Targets must be canonically located under allowed project roots. macOS Finder moves them to Trash; it never calls recursive shell deletion. + +## API boundary + +- `GET /api/health`, `/api/areas`, `/api/options`: readiness, history cards and supported tree styles. +- `POST /api/import/inspect`: multipart/selected file validation without promoting files; verifies ZIP root/contract/areaId via the shared native package validator. +- `POST /api/areas`: copy managed inputs, write ownership record and new config atomically. +- `POST /api/areas/:key/build`: create one build job; `GET /api/jobs/:id/events` streams SSE logs and terminal state. +- `POST /api/cleanup/preview` and `/api/cleanup/confirm`: separate target computation from confirmation, avoiding a stale/hidden destructive scope. +- `GET /artifacts/:key/*`: safely serve only the selected area output root; reject traversal and arbitrary filesystem paths. + +Requests are same-origin, localhost-only and JSON validated. File names are normalized to generated safe names; filesystem writes use staging plus rename. Cleanup uses `realpath` containment checks immediately before moving targets to Trash. + +## Compatibility and rollout + +- Existing commands and hand-authored configurations remain unchanged. +- Existing configs are visible even when their input paths are external; they are never copied or marked owned until a user explicitly imports/saves a console-managed version. +- The console's new local state and managed imports are gitignored. Normal area config files remain reviewable JSON. +- Rollback is deleting the new console-specific files and npm script; it never changes pipeline output contracts. + +## Validation strategy + +- Unit tests for config/history discovery, ZIP inspection, ownership classification, safe path rejection, Save As collision handling, cleanup plan creation and destructive-target containment. +- HTTP tests for localhost binding, API validation, SSE job lifecycle and artifact traversal rejection. +- Manual smoke test: import OSM+ZIP, save, full build, preview, clear outputs, rebuild, remove area, restore from Trash if needed. diff --git a/.trellis/tasks/archive/2026-09/09-17-local-build-console/implement.jsonl b/.trellis/tasks/archive/2026-09/09-17-local-build-console/implement.jsonl new file mode 100644 index 0000000..9dd3234 --- /dev/null +++ b/.trellis/tasks/archive/2026-09/09-17-local-build-console/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-09/09-17-local-build-console/implement.md b/.trellis/tasks/archive/2026-09/09-17-local-build-console/implement.md new file mode 100644 index 0000000..4fb9af5 --- /dev/null +++ b/.trellis/tasks/archive/2026-09/09-17-local-build-console/implement.md @@ -0,0 +1,22 @@ +# 本地构建控制台实施计划 + +1. Create a dependency-free console server and static UI shell; add `npm run console`, localhost-only binding, automatic browser launch and environment/readiness endpoint. +2. Extract/reuse small pipeline-facing helpers for area discovery, diagnostics summary, native ZIP inspection and supported tree-style options. Do not import `build-area.js` as a module. +3. Implement history cards and onboarding: config scanning, manifest/status summary, input descriptions, package/preview links and model option selection. +4. Implement safe import and Save As: upload/copy OSM+ZIP into ignored managed storage, inspect ZIP contract/areaId, atomically write a config with collision-safe output overrides, and record ownership. +5. Implement serialized build jobs with child-process log capture, SSE progress, completion/failure states, and links to the existing generated preview. +6. Implement cleanup planning and confirmation. Validate canonical paths, move only allowed targets to macOS Trash, and cover single/batch clear-output versus remove-area paths. +7. Add focused Node HTTP/unit tests, update README with launch/use/troubleshooting guidance, then manually run the actual imported-area build and preview flow. + +## Validation commands + +- `node --check` for each new Node entry/helper. +- focused console test command added to `package.json`. +- existing `npm run test:native-road-package`, `npm run test:build-stages`, `npm run test:preview-assets`, and `npm run test:package-contract`. +- `npm run console`, import a valid OSM/ZIP fixture, run a full build, open preview, and exercise both cleanup scopes. + +## Risk controls and rollback + +- Never bind beyond loopback; do not serve arbitrary paths or allow parallel builds. +- Validate cleanup targets after confirmation and immediately before Trash movement; no `rm -rf` implementation. +- If the UI path fails, existing CLI remains the supported fallback. Removing console files/script rolls back the feature without changing existing area data or output contracts. diff --git a/.trellis/tasks/archive/2026-09/09-17-local-build-console/prd.md b/.trellis/tasks/archive/2026-09/09-17-local-build-console/prd.md new file mode 100644 index 0000000..845567a --- /dev/null +++ b/.trellis/tasks/archive/2026-09/09-17-local-build-console/prd.md @@ -0,0 +1,45 @@ +# 本地构建控制台 + +## Goal + +提供一个在本机 localhost 运行的图形控制台,使用户无需记忆命令行即可选择或导入道路构建输入、执行现有构建管线、查看进度并打开 Cesium 预览。 + +## Confirmed facts + +- 当前唯一的交互入口是 `scripts/interactive-build.js`:它枚举 `config/areas/*.json`、选择阶段后调用 `scripts/build-area.js`。 +- `build-area.js` 是构建、Blender/Cesium 子进程、package 发布和 preview 写入的唯一所有者;控制台必须调用它,不能复制阶段实现。 +- native 区域配置通过 `nativeRoadPackage` 引用 `native-road-package/v1.1` ZIP;导入器会验证 ZIP 契约和 `areaId`,并将其安全解压到私有 pipeline cache。 +- Blender 与本地文件系统不能由纯静态浏览器页面直接访问,因此入口必须由本机服务配合浏览器 UI 组成。 +- 现有配置及其 `outputs//_pipeline/stages/*.manifest.json` 是历史输入和构建历史的可读取事实源,不能另建会漂移的重复数据库。 + +## Requirements + +- R1: 以 localhost 页面作为首版交付方式;命令行入口继续可用。 +- R2: 首页自动枚举并导入 `config/areas/*.json`,以区域卡片呈现可复用配置、输入摘要、最近构建状态、预览与发布包入口。 +- R3: 用户可从界面选择 OSM 与 native-road ZIP,读取 ZIP 的 `areaId` 和契约信息,并在构建前给出 OSM/ZIP/区域 ID 的明确校验反馈。 +- R3.1: 成功导入的 OSM 与道路 ZIP 复制到项目托管输入目录;新配置引用托管副本,保证可复现且不依赖 `/tmp` 或用户外部路径。 +- R4: 保持首版简单:构建前仅可选择项目已有的植被/树木风格;Cesium 预览中可选择车辆模型。两者分别影响静态场景与演示运行时。 +- R5: 用户可选构建阶段并启动现有 build-area 管线,看到实时阶段状态、日志、产物链接与可行动的失败说明。 +- R6: 对历史配置的修改默认另存为新配置;覆盖已有配置必须是显式确认操作。 +- R6.1: 控制台提供单项清理与批量清理,仅处理它创建的托管输入和本项目生成的区域输出;绝不删除用户在项目外选择的原始文件。首版清理统一移入系统废纸篓,保留恢复机会。 +- R6.2: 清理范围分为两级,且单项、批量均适用:`清理构建产物` 仅移除区域输出并保留配置和托管输入;`移除区域` 将区域配置、控制台托管输入和区域输出一并移入废纸篓。批量操作必须先展示受影响区域和文件数,再允许确认。 +- R7: 产品内置首次使用引导:说明 OSM、道路 ZIP、模型选项、构建阶段、预览入口和 Blender/Node 环境检查,不以外部 README 代替。 + +## Out of scope + +- 改写道路编译器、ZIP 契约、Blender 几何或 Cesium 预览运行时。 +- 远程部署、多用户协作、云端构建或将本机文件上传到第三方服务。 +- 第一阶段打包为 macOS `.app`;待 localhost 工作流验证后再评估。 + +## Acceptance criteria + +- [ ] 用户可在浏览器中启动、选择历史区域并重新执行一次已有构建,无需手写 CLI 参数。 +- [ ] 用户可导入 OSM 与有效道路 ZIP,且在启动 Blender 前看到 ZIP contract / areaId / 文件缺失的校验结果。 +- [ ] 用户可保存为新的区域配置而不改变原配置;显式覆盖有确认保护。 +- [ ] 页面可展示构建阶段、实时日志、成功后的 preview URL 与 `package/manifest.json`。 +- [ ] 首次使用者可仅依照页面引导完成一次输入、构建和预览,并理解失败时下一步怎么做。 + +## Technical notes + +- native-road ZIP 的 `areaId` 与区域配置 `id` 必须相等;控制台应从 ZIP 读取并锁定该 ID,避免提供必然失败的可编辑字段。 +- 控制台管理的输入需要有可判定 ownership 的目录/记录,才能安全实施区域级清理;历史配置引用的外部路径始终视为只读、非托管输入。 diff --git a/.trellis/tasks/archive/2026-09/09-17-local-build-console/task.json b/.trellis/tasks/archive/2026-09/09-17-local-build-console/task.json new file mode 100644 index 0000000..27c32b3 --- /dev/null +++ b/.trellis/tasks/archive/2026-09/09-17-local-build-console/task.json @@ -0,0 +1,26 @@ +{ + "id": "local-build-console", + "name": "local-build-console", + "title": "本地构建控制台", + "description": "", + "status": "completed", + "dev_type": null, + "scope": null, + "package": null, + "priority": "P2", + "creator": "dingkang", + "assignee": "dingkang", + "createdAt": "2026-09-17", + "completedAt": "2026-09-22", + "branch": null, + "base_branch": "experiment/road-compiler-rethink", + "worktree_path": null, + "commit": null, + "pr_url": null, + "subtasks": [], + "children": [], + "parent": null, + "relatedFiles": [], + "notes": "", + "meta": {} +} \ No newline at end of file