super-engineer-workflow 0.1.2 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.5
+
+- 修复重复执行 `/se:plan` 会创建多个 session 的问题：计划阶段复用当前 session，交付中重复 plan 会被拒绝。
+- 增加 E2E 测试，覆盖模板 CLI、OpenSpec 状态机与桥接、todo auto 会话、verify 长日志截断。
+- 增加 `se templates`、`se template show`、`se template copy`，支持复制内置 `workspace.yml` 模板。
+- 增加 OpenSpec、todo、Java 微服务、前端、多仓库等工作区模板。
+- 增加模板使用指南，并在 README 和快速初始化文档中补充模板入口。
+
+## 0.1.4
+
+- Review 阶段优先读取 `plan-summary.json`，仅在缺失时回退到 `plan.json`。
+- Self-check、verify、OpenSpec writeback 阶段优先读取轻量计划摘要，减少重复加载完整计划。
+- Review 阶段默认压缩过长 diff 摘要，避免对话和报告带入大量无效上下文。
+- Verify 阶段增加命令输出压缩工具，为长日志截断和摘要化提供统一入口。
+
+## 0.1.3
+
+- 压缩 `SKILL.md` 为轻量入口，详细规则改为按需读取 references，降低每次 `/se:*` 固定上下文消耗。
+- 快捷命令模板改为极简形式，减少 Claude / Codex slash command 触发时的重复提示词。
+- `/se:propose` 不再把 `reference_files` 全文复制进 `propose-input.json` / `propose-input.md`，改为路径、sha256、标题和摘要片段。
+- 大型 Markdown 参考文档自动摘要，保留按需读取全文能力。
+- OpenSpec bridge context 增加 proposal/design 摘要片段，避免后续阶段重复读取全文。
+- `plan` 阶段新增 `plan-summary.json`，供后续阶段优先读取轻量计划摘要。
+- 收紧脚本最终回复约束文案，默认输出更 compact。
+
 ## 0.1.2
 
 - `se init` 在 `openspec` 模式下默认尝试执行 `openspec init . --tools codex,claude`。

package/README.md

@@ -111,12 +111,23 @@ se init
 ```bash
 se init      # 交互式安装 skill 并初始化工作区
 se doctor    # 检查本机环境和 workspace.yml
+se templates # 查看内置 workspace.yml 模板
 se install   # 安装 skill 到 Codex / Claude
 se sync      # 强制同步最新 skill 到 Codex / Claude
 se migrate   # 补齐旧工作区缺失配置
 se version   # 查看版本
 ```
 
+模板入口：
+
+```bash
+se templates
+se template show openspec-auto
+se template copy openspec-auto --workspace /path/to/ai-workspace --demand-name 13-your-demand --code-path ../code
+```
+
+模板说明见 [docs/模板使用指南.md](/Users/muke/Documents/personal/codex/super-engineer/docs/模板使用指南.md)。
+
 本地源码开发时，也可以直接使用引导脚本。默认是一步一步的交互式向导：
 
 ```bash

package/docs//345/277/253/351/200/237/345/210/235/345/247/213/345/214/226/345/267/245/344/275/234/345/214/272.md

@@ -176,12 +176,25 @@ se init
 ```bash
 se init      # 交互式安装 skill 并初始化工作区
 se doctor    # 检查本机环境和 workspace.yml
+se templates # 查看内置 workspace.yml 模板
 se install   # 安装 skill 到 Codex / Claude
 se sync      # 强制同步最新 skill 到 Codex / Claude
 se migrate   # 补齐旧工作区缺失配置
 se version   # 查看版本
 ```
 
+如果你不想从零写 `workspace.yml`，可以先复制内置模板：
+
+```bash
+se templates
+se template copy openspec-auto \
+  --workspace /path/to/ai-workspace \
+  --demand-name 10-your-demand \
+  --code-path ../code
+```
+
+模板不会覆盖已有 `workspace.yml`，除非显式增加 `--force`。模板说明见 `docs/模板使用指南.md`。
+
 npm 安装的核心要求：
 
 - `package.json` 声明 `bin.super-engineer` 和 `bin.se`。

package/docs//346/250/241/346/235/277/344/275/277/347/224/250/346/214/207/345/215/227.md

@@ -0,0 +1,55 @@
+# 模板使用指南
+
+`super-engineer` 内置了一组 `workspace.yml` 模板，用于减少团队初始化成本，并让不同项目按统一结构接入工作流。
+
+## 查看模板
+
+```bash
+se templates
+se template show openspec-auto
+```
+
+## 复制模板到工作区
+
+```bash
+se template copy openspec-auto \
+  --workspace /path/to/ai-workspace \
+  --demand-name 13-your-demand \
+  --code-path ../code
+```
+
+默认不会覆盖已有 `workspace.yml`。确实需要覆盖时加：
+
+```bash
+se template copy openspec-auto --workspace /path/to/ai-workspace --force
+```
+
+## 模板选择
+
+| 模板 | 适用场景 |
+| --- | --- |
+| `openspec-auto` | 推荐默认模板。先生成 OpenSpec change，再桥接 todo，审核后自动交付。 |
+| `openspec-manual` | 高风险需求。每个关键阶段都需要人工确认。 |
+| `todo-auto` | 小需求、任务已经明确、不需要规格沉淀。 |
+| `todo-manual` | 首次接入、培训、新手熟悉工作流。 |
+| `java-microservice` | Java / Spring 微服务，默认使用 Maven 验证。 |
+| `frontend` | Vue / React 前端项目，默认使用 pnpm 验证。 |
+| `multi-repo` | 多仓库聚合目录，适合中台系统跨服务需求。 |
+
+## 初始化后需要补齐什么
+
+模板只负责生成配置骨架。使用前还需要确认：
+
+- `code_path` 指向真实代码目录。
+- `vars.demand_name` 是当前需求目录名。
+- `demand_file` 或 `todo_file` 对应文件已经存在。
+- `reference_files` 中的文档存在且与当前项目相关。
+- `verify_commands` 与团队实际构建命令一致。
+
+## 推荐实践
+
+存量中台系统优先使用 `openspec-auto` 或 `multi-repo`。
+
+小范围试点时使用 `openspec-manual`，确认流程稳定后再切换到 `openspec-auto`。
+
+如果需求本身已经拆成明确任务，不需要长期规格沉淀，可以使用 `todo-auto`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-engineer-workflow",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Super Engineer workflow skill and CLI for demand-driven AI delivery with OpenSpec bridge support.",
   "license": "MIT",
   "author": "Gary-Coding",
@@ -31,6 +31,7 @@
     "super-engineer-workflow/",
     "!super-engineer-workflow/scripts/__pycache__/",
     "!super-engineer-workflow/scripts/**/*.pyc",
+    "templates/",
     "docs/",
     "README.md",
     "LICENSE",
@@ -40,8 +41,9 @@
   ],
   "scripts": {
     "setup": "python3 scripts/se-setup.py",
-    "check": "python3 -m py_compile scripts/se-cli.py scripts/se-setup.py scripts/se-smoke-test.py super-engineer-workflow/scripts/*.py",
+    "check": "python3 -m py_compile scripts/se-cli.py scripts/se-setup.py scripts/se-smoke-test.py scripts/se-e2e-test.py super-engineer-workflow/scripts/*.py",
     "smoke": "python3 scripts/se-smoke-test.py",
+    "e2e": "python3 scripts/se-e2e-test.py",
     "pack:check": "npm pack --dry-run"
   },
   "keywords": [

package/scripts/se-cli.py

@@ -14,6 +14,18 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parents[1]
 SKILL_DIR = REPO_ROOT / "super-engineer-workflow"
 PACKAGE_JSON = REPO_ROOT / "package.json"
+TEMPLATE_DIR = REPO_ROOT / "templates" / "workspaces"
+
+
+WORKSPACE_TEMPLATES: dict[str, str] = {
+    "openspec-auto": "OpenSpec 规格先行 + 自动交付，推荐用于需求迭代主流程。",
+    "openspec-manual": "OpenSpec 规格先行 + 分阶段人工确认，推荐用于高风险变更。",
+    "todo-auto": "todo.md 直接驱动 + 自动交付，推荐用于小需求或已有明确任务清单。",
+    "todo-manual": "todo.md 直接驱动 + 分阶段人工确认，推荐用于首次接入或新手练习。",
+    "java-microservice": "Java / Spring 微服务模板，内置 Maven 验证命令示例。",
+    "frontend": "Vue / React 前端模板，内置 pnpm/npm 验证命令示例。",
+    "multi-repo": "多仓库聚合目录模板，适用于中台或跨服务需求。",
+}
 
 
 def main() -> None:
@@ -49,6 +61,19 @@ def main() -> None:
     migrate_parser.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
     migrate_parser.add_argument("--dry-run", action="store_true", help="只展示计划，不写入文件。")
 
+    subparsers.add_parser("templates", help="列出内置 workspace.yml 模板。")
+
+    template_parser = subparsers.add_parser("template", help="查看或复制内置 workspace.yml 模板。")
+    template_subparsers = template_parser.add_subparsers(dest="template_action")
+    template_show = template_subparsers.add_parser("show", help="打印指定模板内容。")
+    template_show.add_argument("name", choices=sorted(WORKSPACE_TEMPLATES))
+    template_copy = template_subparsers.add_parser("copy", help="复制指定模板到工作区 workspace.yml。")
+    template_copy.add_argument("name", choices=sorted(WORKSPACE_TEMPLATES))
+    template_copy.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
+    template_copy.add_argument("--demand-name", default="1-your-demand", help="写入 vars.demand_name 的需求目录名。")
+    template_copy.add_argument("--code-path", default="../code", help="写入 code_path 的代码目录。")
+    template_copy.add_argument("--force", action="store_true", help="允许覆盖已有 workspace.yml。")
+
     subparsers.add_parser("version", help="显示版本号。")
 
     args = parser.parse_args()
@@ -67,6 +92,24 @@ def main() -> None:
     if args.command == "migrate":
         exit_code = migrate(Path(args.workspace).expanduser().resolve(), dry_run=args.dry_run)
         raise SystemExit(exit_code)
+    if args.command == "templates":
+        list_templates()
+        return
+    if args.command == "template":
+        if args.template_action == "show":
+            show_template(args.name)
+            return
+        if args.template_action == "copy":
+            copy_template(
+                args.name,
+                Path(args.workspace).expanduser().resolve(),
+                demand_name=args.demand_name,
+                code_path=args.code_path,
+                force=args.force,
+            )
+            return
+        template_parser.print_help()
+        return
 
     parser.print_help()
 
@@ -119,6 +162,40 @@ def install_skill(target: Path, force: bool) -> None:
     print(f"✓ 已同步 skill: {target}")
 
 
+def template_path(name: str) -> Path:
+    path = TEMPLATE_DIR / f"{name}.yml"
+    if not path.exists():
+        raise SystemExit(f"模板不存在：{name}")
+    return path
+
+
+def list_templates() -> None:
+    print("内置 workspace.yml 模板：")
+    for name in sorted(WORKSPACE_TEMPLATES):
+        marker = "✓" if template_path(name).exists() else "!"
+        print(f"{marker} {name}: {WORKSPACE_TEMPLATES[name]}")
+
+
+def render_template(name: str, demand_name: str, code_path: str) -> str:
+    text = template_path(name).read_text(encoding="utf-8")
+    return text.replace("__DEMAND_NAME__", demand_name).replace("__CODE_PATH__", code_path)
+
+
+def show_template(name: str) -> None:
+    print(render_template(name, demand_name="1-your-demand", code_path="../code"))
+
+
+def copy_template(name: str, workspace: Path, demand_name: str, code_path: str, force: bool) -> None:
+    workspace.mkdir(parents=True, exist_ok=True)
+    target = workspace / "workspace.yml"
+    if target.exists() and not force:
+        raise SystemExit(f"workspace.yml 已存在：{target}。如需覆盖请加 --force。")
+    target.write_text(render_template(name, demand_name=demand_name, code_path=code_path), encoding="utf-8")
+    (workspace / "docs").mkdir(parents=True, exist_ok=True)
+    (workspace / "superengineer" / demand_name).mkdir(parents=True, exist_ok=True)
+    print(f"✓ 已写入模板：{target}")
+
+
 def doctor(workspace: Path, output_json: bool) -> int:
     checks: list[dict[str, str]] = []
     add_check(checks, "python", "ok", sys.version.split()[0])

package/scripts/se-e2e-test.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+RUN_WORKFLOW = REPO_ROOT / "super-engineer-workflow" / "scripts" / "run-workflow.py"
+CLI = REPO_ROOT / "bin" / "super-engineer.js"
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory(prefix="se-e2e-") as tmp:
+        root = Path(tmp)
+        home = root / "home"
+        home.mkdir()
+        os.environ["HOME"] = str(home)
+        os.environ["USERPROFILE"] = str(home)
+        test_templates_cli(root)
+        test_openspec_state_and_bridge(root)
+        test_todo_auto_session_and_verify_compaction(root)
+    print("e2e_test=ok")
+
+
+def test_templates_cli(root: Path) -> None:
+    workspace = root / "template-workspace"
+    output = run(["node", str(CLI), "templates"])
+    if "openspec-auto" not in output or "todo-auto" not in output:
+        raise AssertionError("templates list did not include expected templates")
+
+    show_output = run(["node", str(CLI), "template", "show", "openspec-auto"])
+    if "workflow_source: openspec" not in show_output or "mode: auto" not in show_output:
+        raise AssertionError("template show returned unexpected content")
+
+    run(
+        [
+            "node",
+            str(CLI),
+            "template",
+            "copy",
+            "todo-auto",
+            "--workspace",
+            str(workspace),
+            "--demand-name",
+            "9-e2e-template",
+            "--code-path",
+            "../code",
+        ]
+    )
+    workspace_yml = read_text(workspace / "workspace.yml")
+    if "workflow_source: todo" not in workspace_yml or "9-e2e-template" not in workspace_yml:
+        raise AssertionError("template copy did not render workspace.yml")
+
+
+def test_openspec_state_and_bridge(root: Path) -> None:
+    workspace = root / "openspec-workspace"
+    code = root / "code" / "demo-service"
+    demand_dir = workspace / "superengineer" / "8-demo"
+    demand_dir.mkdir(parents=True)
+    code.mkdir(parents=True)
+    (code / "package.json").write_text(
+        json.dumps(
+            {
+                "name": "demo-service",
+                "version": "1.0.0",
+                "scripts": {"test": "node -e \"process.exit(0)\""},
+            },
+            ensure_ascii=False,
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    (workspace / "docs").mkdir(parents=True)
+    (workspace / "openspec" / "changes").mkdir(parents=True)
+    (workspace / "openspec" / "specs").mkdir(parents=True)
+    (demand_dir / "需求.md").write_text(
+        "# 需求\n\n为 demo-service 增加状态查询接口。\n\n## 验收\n\n- 查询接口返回 ok。\n",
+        encoding="utf-8",
+    )
+    (workspace / "workspace.yml").write_text(
+        "\n".join(
+            [
+                "version: 1",
+                "mode: auto",
+                "workflow_source: openspec",
+                "vars:",
+                "  demand_name: 8-demo",
+                "demand_file: superengineer/${demand_name}/需求.md",
+                "todo_file: superengineer/${demand_name}/todo.md",
+                "reference_files: []",
+                "code_path: ../code/demo-service",
+                "output_dir: superengineer/${demand_name}/output",
+                "openspec:",
+                "  changes_dir: openspec/changes",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    invalid = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:bridge",
+        ],
+        check=False,
+    )
+    if invalid.returncode == 0 or "请先执行 /se:propose" not in invalid.output:
+        raise AssertionError("/se:bridge before /se:propose should be rejected")
+
+    env_without_openspec = os.environ.copy()
+    env_without_openspec["PATH"] = ""
+    propose = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:propose demo-change",
+        ],
+        env=env_without_openspec,
+    )
+    if "final_reply_must=代码未修改。下一步只能执行 /se:bridge。" not in propose:
+        raise AssertionError("/se:propose did not print strict next-step constraint")
+
+    change_dir = workspace / "openspec" / "changes" / "demo-change"
+    (change_dir / "specs").mkdir(parents=True, exist_ok=True)
+    (change_dir / "proposal.md").write_text("# Proposal\n\n增加状态查询接口。\n", encoding="utf-8")
+    (change_dir / "design.md").write_text("# Design\n\n目标服务 demo-service。\n", encoding="utf-8")
+    (change_dir / "tasks.md").write_text(
+        "# Tasks\n\n"
+        "- [ ] 修改 demo-service controller 增加状态查询接口\n"
+        "- [ ] 补充验证，确认接口返回 ok\n",
+        encoding="utf-8",
+    )
+
+    bridge = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:bridge",
+        ]
+    )
+    if "bridge_generated=true" not in bridge:
+        raise AssertionError("/se:bridge did not generate todo.md")
+    todo = read_text(workspace / "superengineer" / "8-demo" / "todo.md")
+    if "demo-change" not in todo or "demo-service" not in todo:
+        raise AssertionError("bridged todo.md missing expected OpenSpec context")
+
+    first_plan = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:plan",
+        ]
+    )
+    if "session_action=created" not in first_plan:
+        raise AssertionError("first /se:plan should create a session")
+    first_session = read_json(workspace / ".super-engineer" / "current-session.json")
+    first_session_id = first_session["session_id"]
+
+    second_plan = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:plan",
+        ]
+    )
+    second_session = read_json(workspace / ".super-engineer" / "current-session.json")
+    if "session_action=reused" not in second_plan or second_session["session_id"] != first_session_id:
+        raise AssertionError("second /se:plan should reuse the existing planning session")
+    if len(list((workspace / ".super-engineer" / "sessions").iterdir())) != 1:
+        raise AssertionError("repeated /se:plan created an extra session")
+
+    apply_output = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ]
+    )
+    if "apply_phase=implementing" not in apply_output:
+        raise AssertionError("/se:apply should enter implementing after planned session")
+    blocked_plan = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:plan",
+        ],
+        check=False,
+    )
+    final_session = read_json(workspace / ".super-engineer" / "current-session.json")
+    if blocked_plan.returncode == 0 or "不能重新执行 /se:plan" not in blocked_plan.output:
+        raise AssertionError("/se:plan during active delivery should be rejected")
+    if final_session["session_id"] != first_session_id or len(list((workspace / ".super-engineer" / "sessions").iterdir())) != 1:
+        raise AssertionError("rejected /se:plan should not create or switch sessions")
+
+
+def test_todo_auto_session_and_verify_compaction(root: Path) -> None:
+    workspace = root / "todo-workspace"
+    code = root / "todo-code" / "demo-service"
+    demand_dir = workspace / "superengineer" / "9-demo"
+    demand_dir.mkdir(parents=True)
+    code.mkdir(parents=True)
+    (workspace / "docs").mkdir(parents=True)
+    (code / "verify.py").write_text(
+        "print('A' * 13000)\n"
+        "import sys\n"
+        "print('B' * 13000, file=sys.stderr)\n",
+        encoding="utf-8",
+    )
+    (code / "package.json").write_text(
+        json.dumps(
+            {
+                "name": "demo-service",
+                "version": "1.0.0",
+                "scripts": {"test": "node -e \"process.exit(0)\""},
+            },
+            ensure_ascii=False,
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    verify_command = f'"{sys.executable}" verify.py'
+    (workspace / "workspace.yml").write_text(
+        "\n".join(
+            [
+                "version: 1",
+                "mode: auto",
+                "workflow_source: todo",
+                "vars:",
+                "  demand_name: 9-demo",
+                "todo_file: superengineer/${demand_name}/todo.md",
+                "reference_files: []",
+                "code_path: ../todo-code/demo-service",
+                "output_dir: superengineer/${demand_name}/output",
+                "verify_commands:",
+                f"  default: {verify_command}",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    (demand_dir / "todo.md").write_text(
+        "# 限制条件\n"
+        "- 修改的服务是 demo-service\n\n"
+        "# 待办事项\n\n"
+        "- [ ] 增加状态查询接口\n"
+        "1. 返回 ok\n\n"
+        "## 验收补充\n"
+        "- [ ] 执行验证命令\n",
+        encoding="utf-8",
+    )
+
+    apply_output = run(
+        [
+            sys.executable,
+            str(RUN_WORKFLOW),
+            "route-se",
+            "--workspace",
+            str(workspace),
+            "--command-text",
+            "/se:apply",
+        ]
+    )
+    if "apply_phase=implementing" not in apply_output:
+        raise AssertionError("/se:apply did not enter implementing phase")
+
+    run([sys.executable, str(RUN_WORKFLOW), "finish-implement", "--workspace", str(workspace)])
+    session = read_json(workspace / ".super-engineer" / "current-session.json")
+    data_dir = Path(session["data_dir"])
+    plan_summary = read_json(data_dir / "plan-summary.json")
+    verify = read_json(data_dir / "verify.json")
+    status = read_json(data_dir / "status.json")
+    notification = read_json(data_dir / "notification.json")
+
+    if not plan_summary.get("target_codebases"):
+        raise AssertionError("plan-summary.json missing target_codebases")
+    if verify.get("result") != "通过":
+        raise AssertionError("verify did not pass")
+    stdout = verify["sections"][0]["stdout"]
+    stderr = verify["sections"][0]["stderr"]
+    if "已省略" not in stdout or "已省略" not in stderr:
+        raise AssertionError("verify stdout/stderr were not compacted")
+    if len(stdout) > 12200 or len(stderr) > 12200:
+        raise AssertionError("verify stdout/stderr compaction exceeded expected size")
+    if status.get("phase") != "done":
+        raise AssertionError("todo auto session did not finish with done status")
+    if notification.get("status") != "skipped":
+        raise AssertionError("notification should be marked skipped when no provider is configured")
+
+
+def run(command: list[str], check: bool = True, env: dict[str, str] | None = None):
+    result = subprocess.run(
+        command,
+        cwd=REPO_ROOT,
+        env=env,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    if check:
+        if result.returncode != 0:
+            print(result.stdout)
+            raise SystemExit(result.returncode)
+        return result.stdout
+    return CommandResult(result.returncode, result.stdout)
+
+
+class CommandResult:
+    def __init__(self, returncode: int, output: str) -> None:
+        self.returncode = returncode
+        self.output = output
+
+
+def read_text(path: Path) -> str:
+    if not path.is_file():
+        raise AssertionError(f"missing file: {path}")
+    return path.read_text(encoding="utf-8")
+
+
+def read_json(path: Path) -> dict:
+    if not path.is_file():
+        raise AssertionError(f"missing file: {path}")
+    with path.open(encoding="utf-8") as handle:
+        data = json.load(handle)
+    if not isinstance(data, dict):
+        raise AssertionError(f"json root is not object: {path}")
+    return data
+
+
+if __name__ == "__main__":
+    if shutil.which("node") is None:
+        raise SystemExit("node is required")
+    main()