chore(task): archive 08-04-add-full-stage-manifests
This commit is contained in:
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. 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."}
|
||||
@@ -0,0 +1,77 @@
|
||||
# Design
|
||||
|
||||
## Scope
|
||||
|
||||
The existing manifest infrastructure already supports file records, atomic JSON
|
||||
write, digest summaries, and diagnostics-side freshness checks. This task
|
||||
extends that same contract to the earlier and read-only/patched stages without
|
||||
adding a new manifest format.
|
||||
|
||||
## Stage Boundaries
|
||||
|
||||
`intermediates`
|
||||
|
||||
- Written by `build-area.js` after `build-osm2streets-qgis.js` succeeds.
|
||||
- Inputs: area config, source OSM XML.
|
||||
- Outputs: derived config, GeoJSON directory, all scene-layer GeoJSON files,
|
||||
merged scene/style files, GeoPackage, QGIS project, QGIS preview if present.
|
||||
- Summary: GeoJSON feature counts by file.
|
||||
|
||||
`reimport`
|
||||
|
||||
- Written by `build-area.js` after `reimport-gpkg.js` succeeds.
|
||||
- Inputs: area config, GeoPackage.
|
||||
- Outputs: GeoJSON directory, all scene-layer GeoJSON files, merged scene/style
|
||||
files.
|
||||
- Summary: GeoJSON feature counts by file.
|
||||
|
||||
`blender`
|
||||
|
||||
- Written by `build-area.js` after Blender scene generation succeeds.
|
||||
- Inputs: area config, source OSM XML, GeoJSON directory, all scene-layer
|
||||
GeoJSON files, merged scene/style files.
|
||||
- Outputs: `.blend`, render PNG.
|
||||
- Summary: parsed `SCENE_DONE` payload when available, plus blend/render bytes.
|
||||
|
||||
`preview`
|
||||
|
||||
- Written by `build-area.js` after preview generation succeeds. Since `cesium`
|
||||
automatically calls preview generation, this manifest should also be written
|
||||
during `--stages cesium`.
|
||||
- Inputs: area config, source OSM XML, GLB, metadata, preview runtime JS/CSS.
|
||||
- Outputs: Cesium preview HTML, vehicle route JSON, vehicle model glTF.
|
||||
- Summary: vehicle route count and asset filenames.
|
||||
|
||||
## Diagnostics
|
||||
|
||||
`scripts/lib/area-diagnostics.js` will extend `stageManifestStatus()` from two
|
||||
hard-coded GLB stages to the full ordered stage list. Expected status should
|
||||
derive from stage outputs:
|
||||
|
||||
- `intermediates`: expected when GeoJSON dir, GeoPackage, or QGIS project exists.
|
||||
- `reimport`: expected when GeoJSON dir exists and `reimport.manifest.json`
|
||||
already exists; it is an alternate path and should not be required for normal
|
||||
intermediates builds.
|
||||
- `blender`: expected when blend exists.
|
||||
- `cesium`: expected when baseline GLB exists.
|
||||
- `preview`: expected when Cesium preview exists.
|
||||
- `compress`: expected when compressed GLB exists.
|
||||
|
||||
Only expected manifests are fatal in `check:area`. Optional absent manifests
|
||||
remain ignored.
|
||||
|
||||
## Compatibility
|
||||
|
||||
- Existing `cesium.manifest.json` and `compress.manifest.json` remain valid.
|
||||
- Existing outputs without new manifests will show missing expected manifests
|
||||
until their stages are rerun.
|
||||
- No stage should overwrite its primary outputs differently just to write a
|
||||
manifest.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
- Manifest writing lives in `build-area.js` for this task because it already
|
||||
owns normalized area paths and stage timing. Moving preview generation and
|
||||
vehicle assets out of `build-area.js` is a later refactor.
|
||||
- Reimport remains optional/alternate to avoid making normal `check:area` fail
|
||||
for users who never use the reimport workflow.
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. 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."}
|
||||
@@ -0,0 +1,30 @@
|
||||
# Implementation Plan
|
||||
|
||||
1. Read current manifest and stage code.
|
||||
2. Add reusable helpers in `build-area.js` for:
|
||||
- file record collection
|
||||
- GeoJSON feature-count summaries
|
||||
- manifest duration/timestamps
|
||||
- writing `intermediates`, `reimport`, `blender`, and `preview` manifests
|
||||
3. Wire manifest writes after successful stage functions only.
|
||||
4. Extend `area-diagnostics.js` manifest expected/input/output definitions to
|
||||
cover all stages.
|
||||
5. Update README, changelog, and `.trellis/spec/pipeline/*`.
|
||||
6. Validate with:
|
||||
- `node --check scripts/build-area.js`
|
||||
- `node --check scripts/lib/area-diagnostics.js`
|
||||
- `node --check scripts/check-area.js`
|
||||
- `node --check scripts/diagnose-area.js`
|
||||
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages preview`
|
||||
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender`
|
||||
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages intermediates`
|
||||
- `npm run diagnose:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
|
||||
- `npm run check:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
|
||||
- controlled stale/missing manifest failure
|
||||
- `git diff --check`
|
||||
|
||||
## Rollback
|
||||
|
||||
- Remove added manifest write calls and diagnostics stage definitions.
|
||||
- Delete generated `_pipeline/stages/{intermediates,reimport,blender,preview}.manifest.json`
|
||||
from outputs if needed; outputs are ignored and not committed.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Add full stage manifests
|
||||
|
||||
## Goal
|
||||
|
||||
Extend the stage manifest contract from GLB-only stages to the full area
|
||||
pipeline so `diagnose:area` and `check:area` can reason about stage freshness
|
||||
across intermediates, reimport, blender, preview, cesium, and compress.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Write stage manifests for:
|
||||
- `intermediates`
|
||||
- `reimport`
|
||||
- `blender`
|
||||
- `preview`
|
||||
- Preserve existing `cesium` and `compress` manifest behavior.
|
||||
- Do not change default build outputs except for adding/updating manifest files
|
||||
under `<areaDir>/_pipeline/stages/`.
|
||||
- Stage manifests must record enough inputs and outputs to detect stale files
|
||||
using the existing bytes/sha freshness logic.
|
||||
- `diagnose:area` must display these additional manifests.
|
||||
- `check:area` must fail when an expected full-pipeline manifest is missing,
|
||||
invalid, or stale.
|
||||
- `reimport` and `intermediates` remain mutually exclusive.
|
||||
- Missing optional `compress` artifacts still must not make `check:area` fail.
|
||||
- README, changelog, and Trellis pipeline spec must document the expanded
|
||||
manifest coverage.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Running `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages preview`
|
||||
writes a fresh `preview.manifest.json`.
|
||||
- [x] Running `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender`
|
||||
writes a fresh `blender.manifest.json`.
|
||||
- [x] Running `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages intermediates`
|
||||
writes a fresh `intermediates.manifest.json`.
|
||||
- [x] `diagnose:area` shows `intermediates`, `blender`, `cesium`, `preview`, and
|
||||
optional `compress` manifest status.
|
||||
- [x] `check:area` passes for current nantaizi outputs after the required
|
||||
manifests are generated.
|
||||
- [x] A controlled stale/missing manifest case makes `check:area` exit non-zero.
|
||||
- [x] Syntax checks pass for changed Node scripts.
|
||||
- [x] README, changelog, and pipeline spec describe full stage manifest coverage.
|
||||
|
||||
## Notes
|
||||
|
||||
- Validate only `nantaizi-lake-innovation-valley` unless explicitly asked.
|
||||
- Ignore `hanyang-block`.
|
||||
- This task is about pipeline contracts and diagnostics, not lane-arrow visual
|
||||
behavior.
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "add-full-stage-manifests",
|
||||
"name": "add-full-stage-manifests",
|
||||
"title": "Add full stage manifests",
|
||||
"description": "Add read-only/verifiable stage manifests for intermediates, reimport, blender, and preview so diagnose/check can reason about full area pipeline freshness.",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-04",
|
||||
"completedAt": "2026-08-04",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in New Issue
Block a user