tirtc-device-builder 0.2.0 → 0.3.0

package/bin/tirtc-device-builder.js

@@ -12,6 +12,7 @@ import {
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { runEsp32Setup } from "./setup-esp32.js";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PACKAGE = JSON.parse(
@@ -35,6 +36,7 @@ function printHelp() {
 Usage:
   tirtc-device-builder list
   tirtc-device-builder install <platform> [--skills-dir <path>] [--force]
+  tirtc-device-builder setup <platform> [setup options]
   tirtc-device-builder doctor <platform> [doctor options]
   tirtc-device-builder --version
 
@@ -43,11 +45,14 @@ Platforms:
 
 Examples:
   npx tirtc-device-builder install esp32
+  npx tirtc-device-builder setup esp32
+  npx tirtc-device-builder setup esp32 --install
   npx tirtc-device-builder install esp32 --skills-dir /absolute/path/skills
   npx tirtc-device-builder doctor esp32 --project /absolute/path/project
 
 Install defaults to ${"$"}{CODEX_HOME:-~/.codex}/skills. Existing skills are
-preserved unless --force is explicitly supplied.`);
+preserved unless --force is explicitly supplied. Setup checks are read-only;
+setup --install installs missing user-space components without running sudo.`);
 }
 
 function fail(message) {
@@ -187,7 +192,7 @@ function main(args) {
   }
 
   const [command, identifier, ...rest] = args;
-  if (command !== "install" && command !== "doctor") {
+  if (command !== "install" && command !== "doctor" && command !== "setup") {
     return fail(`unknown command: ${command}; run with --help`);
   }
   if (!identifier) {
@@ -201,6 +206,18 @@ function main(args) {
   if (command === "doctor") {
     return runDoctor(platform, rest);
   }
+  if (command === "setup") {
+    if (platform.name !== "esp32") {
+      return fail(`setup is not available for platform: ${platform.name}`);
+    }
+    return runEsp32Setup(rest, {
+      cliPath: fileURLToPath(import.meta.url),
+      defaultSkillsDir: defaultSkillsDir(),
+      packageRoot: PACKAGE_ROOT,
+      packageVersion: PACKAGE.version,
+      platform,
+    });
+  }
 
   try {
     const options = parseInstallOptions(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Install and run TiRTC device-development skills for Codex.",
   "license": "MIT",
   "author": {
@@ -45,6 +45,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
+    "pack:esp32-kit": "node scripts/pack-esp32-kit.js",
     "test": "npm run test:node && npm run test:python && npm run validate && npm run validate:tarball && npm run test:package",
     "test:node": "node --test test/*.test.js",
     "test:python": "python3 -m unittest discover -s skills/tirtc-esp32-builder/scripts -p 'test_*.py'",

package/skills/tirtc-esp32-builder/SKILL.md

@@ -9,15 +9,16 @@ Turn board evidence into an evidence-backed ESP-IDF project. Treat the Hardware
 
 ## Start
 
-1. Locate the ThingConnect root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, or workspace discovery. Read its applicable `AGENTS.md` and preserve its public protocol contracts.
-2. Read [environment.md](references/environment.md) and run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--require-workspace` when generation or repository reference documents are needed; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness. Installation, cloning, or shell-profile changes require an explicit destination and the applicable authorization.
-3. Read [workflow.md](references/workflow.md). Select the registered-board, new-board intake, or existing-project branch. The branch is selected when every supplied artifact has been accounted for and the exact board revision is known or explicitly unresolved.
-4. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. Record a source and verification level for every hardware fact that affects a requested feature.
-5. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --strict`. Generation may proceed for a requested feature only when it is `READY_TO_PORT` or `HIL_VERIFIED`; otherwise report the exact missing evidence and continue with safe discovery or scaffolding only.
+1. Read [environment.md](references/environment.md). For a first-time setup or a request to check/install prerequisites, prefer `npx tirtc-device-builder@latest setup esp32`. Run its `--install` mode only when the user explicitly authorizes installation at the displayed destinations. The installer may create user-space files but never grants permission for `sudo` or persistent shell-profile edits.
+2. Locate the versioned ESP32 Device Kit root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, the managed setup configuration, or workspace discovery. Treat its manifest and packaged protocol documents as the generation facts. If the user explicitly supplies a full ThingConnect source workspace, also read its applicable `AGENTS.md`.
+3. Run the Doctor through the managed environment helper when one exists; otherwise run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--require-workspace` when generation or repository reference documents are needed; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness.
+4. Read [workflow.md](references/workflow.md). Select the registered-board, new-board intake, or existing-project branch. The branch is selected when every supplied artifact has been accounted for and the exact board revision is known or explicitly unresolved.
+5. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. Record a source and verification level for every hardware fact that affects a requested feature.
+6. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --strict`. Generation may proceed for a requested feature only when it is `READY_TO_PORT` or `HIL_VERIFIED`; otherwise report the exact missing evidence and continue with safe discovery or scaffolding only.
 
 ## Build the project
 
-Run `<thing-connect-root>/device-sim/scripts/create_esp32_project.py` for the current ESP32-S3 H5/AI starter. Keep ThingConnect onboarding, H5, AI, TiRTC lifecycle, callback, stream, and generation behavior in the existing deep modules. Put board-specific camera, microphone, encoder, codec, amplifier, GPIO, DMA, and task behavior behind the `starter_media` seam or a board media adapter owned by it.
+Run `<device-kit-root>/device-sim/scripts/create_esp32_project.py` for the current ESP32-S3 H5/AI starter. Keep ThingConnect onboarding, H5, AI, TiRTC lifecycle, callback, stream, and generation behavior in the existing deep modules. Put board-specific camera, microphone, encoder, codec, amplifier, GPIO, DMA, and task behavior behind the `starter_media` seam or a board media adapter owned by it.
 
 Before changing media code, read [capability-rules.md](references/capability-rules.md) and the repository documents it routes to. A camera sensor alone does not establish H5 video support; the complete H.264 Annex-B and key-frame path must be evidenced. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
 

package/skills/tirtc-esp32-builder/USAGE.md

@@ -1,5 +1,14 @@
 # TiRTC ESP32 Builder 使用说明
 
+## 一键准备
+
+```bash
+npx tirtc-device-builder@latest setup esp32
+npx tirtc-device-builder@latest setup esp32 --install
+```
+
+第一条命令只检查；第二条命令自动安装用户目录内缺失的 Skill、带校验的 ESP32 Device Kit、ESP-IDF 5.5.4 和 ESP32-S3 工具链，最后复跑 Doctor。它不执行 `sudo`，也不修改 shell 配置。安装完成后新开 Codex 会话即可调用 Skill。
+
 安装后可在 Codex 中显式调用：
 
 ```text
@@ -14,25 +23,21 @@ $tirtc-esp32-builder
 - 产品页或资料链接：...
 - 原理图：/absolute/path/board-schematic.pdf
 - BSP 或示例工程：/absolute/path/vendor-bsp
-- ThingConnect：/absolute/path/tirtc-server-example/thing-connect
 - 输出目录：/absolute/path/my-tirtc-device
 
 先完成能力分析；具备条件后生成并编译。只有我明确指定串口时才烧录。
 ```
 
-## ThingConnect 工作区
+## ESP32 Device Kit
 
-这个 Skill 不复制 ThingConnect 源码和 TiRTC 静态库。首次使用可以准备公开仓库：
+一键安装会下载固定版本的最小资源包并校验 SHA-256，不需要克隆 ThingConnect 服务端仓库。安装路径由下面的文件记录：
 
 ```bash
-git clone https://github.com/tangeai/tirtc-server-example.git \
-  /absolute/path/tirtc-server-example
-
-export TIRTC_THING_CONNECT_ROOT=\
-/absolute/path/tirtc-server-example/thing-connect
+source ~/.tirtc-device-builder/env.sh
+printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 ```
 
-也可以在调用 Skill 时直接给出 ThingConnect 绝对路径，不需要设置持久环境变量。
+已有完整 ThingConnect 工作区仍可通过 `--thing-connect-root` 显式复用，主要用于维护模板或协议时的开发场景。
 
 ## 常见输入方式
 
@@ -45,7 +50,7 @@ $tirtc-esp32-builder 分析 <厂商> <型号> <硬件版本>，目标是 H5 实
 提供本地资料：
 
 ```text
-$tirtc-esp32-builder 使用原理图 /path/board.pdf、BSP /path/vendor-project 和 ThingConnect /path/tirtc-server-example/thing-connect，为该板生成 TiRTC H5/AI ESP-IDF 工程并编译。
+$tirtc-esp32-builder 使用原理图 /path/board.pdf、BSP /path/vendor-project 和一键安装的 Device Kit，为该板生成 TiRTC H5/AI ESP-IDF 工程并编译。
 ```
 
 完整实机流程：
@@ -64,7 +69,7 @@ $tirtc-esp32-builder 使用 /path/hardware-ir.json 生成工程，编译后烧
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --thing-connect-root /absolute/path/tirtc-server-example/thing-connect \
+  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.0.0 \
   --require-workspace
 ```
 

package/skills/tirtc-esp32-builder/references/environment.md

@@ -1,5 +1,26 @@
 # ESP-IDF environment
 
+## Managed one-command setup
+
+Prefer the packaged setup entrypoint for a new machine:
+
+```bash
+npx tirtc-device-builder@latest setup esp32
+npx tirtc-device-builder@latest setup esp32 --install
+```
+
+The first command is read-only. The second command is explicit authorization to install missing user-space components at the printed destinations. Its default root is `~/.tirtc-device-builder`; it downloads and verifies the pinned ESP32 Device Kit, installs the Skill, clones or reuses ESP-IDF 5.5.4, runs Espressif's `install.sh esp32s3`, writes `config.json` and `env.sh`, and reruns the Doctor inside the activated environment.
+
+The automatic branch never runs `sudo` or modifies a persistent shell profile. When system dependencies are missing, report its exact blocker and let the user perform the displayed system action. Existing incomplete directories are preserved as blockers. Rerunning the same command resumes completed stages.
+
+When `<setup-root>/env.sh` exists, use it only as an activation prefix for the current command:
+
+```bash
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --target esp32s3 --require-workspace'
+```
+
+The helper contains paths, not device or network credentials. Read `<setup-root>/config.json` when exact managed paths are needed; the environment helper does not authorize unrelated downloads, shell-profile changes, flashing, or credential writes.
+
 Run the doctor before generation, build, flash, or monitor:
 
 ```bash
@@ -11,18 +32,18 @@ python3 <skill-dir>/scripts/doctor.py \
 
 Add `--project <generated-project>` after generation so the doctor can compare `sdkconfig` or `sdkconfig.defaults` with the TiRTC SDK build contract. Use `--json` when the result will be included in another report.
 
-## ThingConnect workspace
+## ESP32 Device Kit
 
-This distributable skill does not bundle the ThingConnect source tree or TiRTC static library. Resolve the public ThingConnect workspace in this order:
+The automatic setup downloads a versioned minimal Kit instead of cloning the ThingConnect server repository. Resolve the generation root in this order:
 
 1. an explicit `--thing-connect-root <path>`;
 2. `TIRTC_THING_CONNECT_ROOT`;
 3. an ancestor of the project or current directory containing `device-sim/scripts/create_esp32_project.py`;
 4. an ancestor whose `thing-connect/` child contains that generator.
 
-The public source is `https://github.com/tangeai/tirtc-server-example`. Clone it only into an explicit destination. The root accepted by the doctor may be either the repository root or its `thing-connect/` child.
+The default managed root is `<setup-root>/kits/esp32s3/<kit-version>`. The public ThingConnect workspace remains an optional legacy/development input; the doctor accepts either a Device Kit root, a repository root, or its `thing-connect/` child.
 
-SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved ThingConnect workspace. The generated project path therefore remains diagnosable after it is moved away from the source repository.
+SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved Device Kit or legacy workspace. The generated project remains diagnosable after it is moved away from the Kit.
 
 ## Required checks
 

package/skills/tirtc-esp32-builder/scripts/doctor.py

@@ -204,7 +204,7 @@ def resolve_sdk_dir(
         if bundled.is_dir():
             return bundled, "generated project"
     if thing_connect_root is not None:
-        return thing_connect_root / DEFAULT_SDK_RELATIVE_PATH, "ThingConnect workspace"
+        return thing_connect_root / DEFAULT_SDK_RELATIVE_PATH, "Device Kit or legacy workspace"
     return None, "not found"
 
 
@@ -272,7 +272,7 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
     )
     checks.append(
         check(
-            "ThingConnect workspace",
+            "ESP32 Device Kit",
             workspace_status,
             (
                 f"{thing_connect_root} ({thing_connect_source})"
@@ -286,7 +286,7 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
     )
     if args.require_workspace and thing_connect_root is None:
         next_actions.append(
-            "Clone the public ThingConnect repository or pass its absolute path with "
+            "Run setup esp32 --install or pass an existing Device Kit path with "
             "--thing-connect-root."
         )
 
@@ -414,7 +414,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--require-workspace",
         action="store_true",
-        help="fail when a ThingConnect workspace with the ESP32 generator is unavailable",
+        help="fail when a Device Kit or legacy workspace with the ESP32 generator is unavailable",
     )
     parser.add_argument("--sdk-dir", type=Path)
     parser.add_argument("--project", type=Path)