android2harmony 0.1.7 → 0.1.8

package/skills/a2h-spec-implement/scripts/utils/ensure_app.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// ensure_app.mjs — guarantee the project's app is installed on a device (Phase 1 grounding gate).
+//
+//   node scripts/utils/ensure_app.mjs --project <harmonyos-project-path> --device <serial> [--bundle <name>]
+//
+// Deterministic, idempotent: probe installed → done; absent → devecocli build (release, signed
+// per rules/pipeline/build/build.md) → hdc install -r (cd + basename, per testing/test-core.md
+// § Device channel & install) → re-probe. Never uninstalls, never reinstalls an installed app
+// (an app-HAP reinstall re-signs and drops persisted URI grants — measured).
+//
+// stdout contract: exactly ONE line —
+//   ENSURE_APP: installed bundle=<b> device=<d>
+//   ENSURE_APP: built+installed bundle=<b> device=<d> haps=<n>
+//   ENSURE_APP: FAILED <stage>: <reason>
+// Diagnostics (build-log tail etc.) go to stderr. Exit 0 on installed/built+installed, 1 on FAILED.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureHdcOnPath, hdcRun } from "../device_ui_core.mjs";
+
+// ---------- args ----------
+function parseArgs(argv) {
+  const a = { project: "", device: "", bundle: "" };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--project") a.project = argv[++i];
+    else if (t === "--device") a.device = argv[++i];
+    else if (t === "--bundle") a.bundle = argv[++i];
+    else if (t === "-h" || t === "--help") a.help = true;
+  }
+  return a;
+}
+const args = parseArgs(process.argv.slice(2));
+if (args.help || !args.project || !args.device) {
+  console.error("Usage: node scripts/utils/ensure_app.mjs --project <harmonyos-project-path> --device <serial> [--bundle <name>]");
+  process.exit(args.help ? 0 : 1);
+}
+
+function ok(line) { console.log(line); process.exit(0); }
+function fail(stage, reason) { console.log(`ENSURE_APP: FAILED ${stage}: ${reason}`); process.exit(1); }
+
+const project = path.resolve(args.project);
+if (!fs.existsSync(project)) fail("args", `project not found: ${project}`);
+
+// ---------- bundle name (AppScope/app.json5) ----------
+let bundle = args.bundle;
+if (!bundle) {
+  const appJson = path.join(project, "AppScope", "app.json5");
+  try {
+    const m = fs.readFileSync(appJson, "utf8").match(/"bundleName"\s*:\s*"([^"]+)"/);
+    if (m) bundle = m[1];
+  } catch { /* fall through */ }
+  if (!bundle) fail("args", `bundleName not resolvable from ${appJson} (pass --bundle)`);
+}
+
+// ---------- probe installed ----------
+if (!ensureHdcOnPath()) fail("probe", "hdc not on PATH and not locatable via conf.yaml DEVECO_PATH/DEVECO_SDK_HOME");
+// hdc exits 0 even on an unreachable device (error text on stdout) — verify the target is
+// actually connected before trusting any shell output.
+const targets = hdcRun(null, ["list", "targets"], 15000);
+if (targets.error || !(targets.stdout || "").split(/\r?\n/).some((l) => l.trim() === args.device)) {
+  fail("probe", `device ${args.device} not in \`hdc list targets\`: ${((targets.stdout || targets.stderr || "") + "").trim().slice(0, 200)}`);
+}
+function isInstalled() {
+  const p = hdcRun(args.device, ["shell", "bm", "dump", "-a"], 30000);
+  const out = p.stdout || "";
+  if (p.error || p.status !== 0 || /\[Fail\]/i.test(out)) {
+    fail("probe", `bm dump failed on ${args.device}: ${((p.stderr || out || String(p.error)) + "").trim().slice(0, 200)}`);
+  }
+  // `bm dump -a` lists bundle names one per line; exact-token match (avoid prefix collisions).
+  return out.split(/\r?\n/).some((l) => l.trim() === bundle);
+}
+if (isInstalled()) ok(`ENSURE_APP: installed bundle=${bundle} device=${args.device}`);
+
+// ---------- build (release = signed output; debug is compile-check only per build.md) ----------
+console.error(`[ensure_app] ${bundle} not installed on ${args.device} — building current code (devecocli build, release)…`);
+const build = spawnSync("devecocli build", {
+  cwd: project, shell: true, encoding: "utf8", timeout: 600000,
+  windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+});
+const buildLog = (build.stdout || "") + (build.stderr || "");
+if (build.error || build.status !== 0 || !/BUILD SUCCESSFUL/i.test(buildLog)) {
+  console.error(buildLog.split(/\r?\n/).slice(-30).join("\n"));
+  fail("build", `devecocli build rc=${build.status ?? build.error} (log tail on stderr)`);
+}
+
+// ---------- collect package set (per-module <mod>/build/default/outputs/default) ----------
+// Signing mode follows the project: a product referencing a signingConfig emits *-signed.hap,
+// `app.signingConfigs: []` emits *-unsigned.hap and cannot emit anything else. Take signed when
+// present, else unsigned — rejecting the unsigned variant yields no package set at all, which
+// disables the device layer and misreports a build-config fact as a missing artifact.
+const outDirs = [];
+for (const mod of fs.readdirSync(project, { withFileTypes: true })) {
+  if (!mod.isDirectory()) continue;
+  const out = path.join(project, mod.name, "build", "default", "outputs", "default");
+  if (fs.existsSync(out)) outDirs.push(out);
+}
+const collect = (suffix) => {
+  const acc = []; // { dir, name }
+  for (const dir of outDirs) {
+    for (const f of fs.readdirSync(dir)) {
+      if (f.endsWith(`-${suffix}.hap`) || f.endsWith(".hsp")) acc.push({ dir, name: f });
+    }
+  }
+  return acc;
+};
+let mode = "signed";
+let pkgs = collect("signed");
+if (!pkgs.some((p) => p.name.endsWith(".hap"))) {
+  const unsignedPkgs = collect("unsigned");
+  if (unsignedPkgs.some((p) => p.name.endsWith(".hap"))) {
+    mode = "unsigned";
+    pkgs = unsignedPkgs;
+    console.error("[ensure_app] no signed HAP — installing the unsigned package set; a device that refuses it is an environment result, not a code defect");
+  }
+}
+if (!pkgs.length) fail("install", "build produced no *-signed.hap and no *-unsigned.hap (see build.md § Pinned command)");
+
+// ---------- install (one transaction; cd + basename — hdc mangles non-Windows paths) ----------
+const byDir = new Map();
+for (const p of pkgs) { if (!byDir.has(p.dir)) byDir.set(p.dir, []); byDir.get(p.dir).push(p.name); }
+for (const [dir, names] of byDir) {
+  const p = spawnSync("hdc", ["-t", args.device, "install", "-r", ...names], {
+    cwd: dir, encoding: "utf8", timeout: 120000, windowsHide: true,
+  });
+  const outText = ((p.stdout || "") + (p.stderr || "")).trim();
+  if (p.error || p.status !== 0 || /error|fail/i.test(outText)) {
+    fail("install", `hdc install -r ${names.join(" ")}: ${outText.slice(0, 300)}`);
+  }
+}
+
+// ---------- re-probe ----------
+if (!isInstalled()) fail("install", `install reported success but ${bundle} still absent in bm dump -a`);
+ok(`ENSURE_APP: built+installed bundle=${bundle} device=${args.device} haps=${pkgs.length} mode=${mode}`);

package/skills/a2h-ui-transfer/SKILL.md

@@ -59,7 +59,7 @@ This skill batch-converts Android resources (strings, colors, drawables, images,
 **Resource-fidelity gate before Step 5.** When that skill's report contains a **Vector Fidelity Issues** section with `error`-severity rows, fix the resources before starting per-page conversion. A drawable whose `clip-path` was dropped, or whose stroke-only path was given a solid `fill`, still has the correct file name — so every page that references it will pass Phase 5's reference checks and compile cleanly while rendering wrong. Fixing it after the pages are written means re-verifying every page that consumed it. If resources were converted in an earlier session (so no fresh report exists), you can run that skill's checker directly — it is static and needs no device:
 
 ```
-node <a2h-resource-convert-skill>/scripts/svg_fidelity_check.js \
+node <a2h-resource-convert>/scripts/svg_fidelity_check.js \
     --android-res <android_project_dir>/<app_module>/src/main/res \
     --harmony-media <harmony_project_dir>/<ui_module>/src/main/resources/base/media
 ```
@@ -67,7 +67,7 @@ node <a2h-resource-convert-skill>/scripts/svg_fidelity_check.js \
 **App-identity gate — also before Step 5.** That skill's Toolchain step 2 points `AppScope/app.json5` and `abilities[0]` at the Android launcher icon and app name. Confirm it passed; nothing in Steps 5-7 covers it, and the failure is invisible to every check here — the pages compile and render fine while the app shows the DevEco default icon and is named `label` on the desktop. If resources were converted in an earlier session, run the gate directly (static, no device):
 
 ```
-node <a2h-resource-convert-skill>/scripts/app_identity.js --check --json <work_dir>/app_identity.json
+node <a2h-resource-convert>/scripts/app_identity.js --check --json <work_dir>/app_identity.json
 ```
 
 `GATE: FAIL`, or a missing `app_identity.json` (the step never ran), means re-running that skill's Toolchain step 2 before continuing.

package/skills/hmos-convert-pipeline/SKILL.md

@@ -58,6 +58,8 @@ The pipeline's sub-agents resolve each setting from the **OS environment variabl
 
 For each value, if the env var is unset, **ask the user**: for the DevEco path / model api_key, **ask the user** (for the api_key they may instead pass `skip_test=true`). Suggest setting the corresponding machine environment variable directly (`DEVECO_SDK_HOME` / `HOMETRANS_MODEL_API_KEY` / `HOMETRANS_TOOL_PATH`).
 
+**External skill dependency.** Stage 2, 3b, and 4b delegate the signed build to the `a2h-fix-build-errors` skill, which is **not bundled in this plugin edition** — it ships with the broader HomeTrans distribution. Verify it is available in the same upfront pass; if it is not, stop and tell the user rather than substituting a guessed `hvigor` invocation. Every build gate in this pipeline (and the `AUTHORITATIVE_ENTRY` / `CURRENT_HAP` handoffs that depend on it) assumes a real signed build actually ran.
+
 ---
 
 ## Progress Tracking
@@ -163,10 +165,10 @@ For the Stage 4 loop, combine test and fix results into one row per round plus o
 Several stages below need the **full signed package set** — the entry HAP plus any in-app HSPs (and any feature HAP the build freshly produced) — so the self-tester installs them in one `hdc install -r` transaction (in-app HSPs cannot install standalone). Those stages call this procedure.
 
 **Inputs:**
-- `BUILD_ROOT` — the project root rebuilt by `hmos-fix-build-errors` (= `HMOS`).
+- `BUILD_ROOT` — the project root rebuilt by `a2h-fix-build-errors` (= `HMOS`).
 - `DEST` — a dedicated `package-set/` directory to populate; **must never be the directory where you mirror the authoritative entry HAP** (step 1 clears `DEST`).
 - `BUILD_START` — a marker captured **immediately before** invoking the build stage, e.g. `touch "<DEST>/../.build_start_marker"` (or record a timestamp). Used to tell freshly-rebuilt artifacts from stale ones. A touched marker + `find -newer` avoids clock-skew between the build stage and the host.
-- `AUTHORITATIVE_ENTRY` — the authoritative signed entry HAP resolved directly from `HMOS/entry/build/default/outputs/default/` after `hmos-fix-build-errors` succeeds. Once resolved for the stage, treat it as authoritative regardless of mtime.
+- `AUTHORITATIVE_ENTRY` — the authoritative signed entry HAP resolved directly from `HMOS/entry/build/default/outputs/default/` after `a2h-fix-build-errors` succeeds. Once resolved for the stage, treat it as authoritative regardless of mtime.
 
 **Procedure:**
 1. **Clear/create `DEST`** (remove prior contents, recreate) so stale packages never leak forward. `DEST` is a dedicated `package-set/` subdir, distinct from the location where you mirror the authoritative entry for this stage.
@@ -216,7 +218,7 @@ Prompt format (applies to both Stage 1 and Stage 1a): ONLY the key-value lines b
 
 ### Stage 2 — Compilation and Build
 
-1. Invoke the `hmos-fix-build-errors` skill for a signed build of `HMOS`.
+1. Invoke the `a2h-fix-build-errors` skill for a signed build of `HMOS`.
 2. Capture `BUILD_START` just before invoking the skill.
 3. Treat the build stage as a compile/fix gate only — do **not** expect build-stage report or commit-info artifacts.
 4. After a successful build, resolve `AUTHORITATIVE_ENTRY` directly from `HMOS/entry/build/default/outputs/default/` (prefer `entry-default-signed.hap`, else the first `*-signed.hap`) and note it in the manifest.
@@ -267,7 +269,7 @@ For each `review_round` from `1..MAX_ROUNDS_REVIEW`, set `REVIEW_ROUND_DIR = OUT
 ##### Review Round Step B — Stage 3b Rebuild after Review Fix
 
 1. Mark Stage 3b `in_progress` when the first Stage 3b round begins.
-2. Capture `BUILD_START` (touch a marker), then invoke the `hmos-fix-build-errors` skill for a signed rebuild of `HMOS`.
+2. Capture `BUILD_START` (touch a marker), then invoke the `a2h-fix-build-errors` skill for a signed rebuild of `HMOS`.
 3. Treat this as a compile/fix gate only — do **not** expect a rebuild report artifact in `REVIEW_ROUND_DIR`.
 4. If the build succeeds, resolve `AUTHORITATIVE_ENTRY` directly from `HMOS/entry/build/default/outputs/default/` (prefer `entry-default-signed.hap`, else the first `*-signed.hap`), note it in the manifest, and **then run Package-Set Collection** with `BUILD_ROOT = HMOS`, `DEST = REVIEW_ROUND_DIR/package-set/`, the resolved `AUTHORITATIVE_ENTRY`, and the captured `BUILD_START`; on success set `LAST_GOOD_REVIEW_SET = REVIEW_ROUND_DIR/package-set/`. **If the 3b build failed, do NOT run collection and keep the previous `LAST_GOOD_REVIEW_SET`** (a failed rebuild leaves stale sibling-module outputs on disk; the mtime gate already prevents harvesting them, and skipping collection avoids re-touching `LAST_GOOD_REVIEW_SET` with an entry-less set).
 5. Append one Defect Summary row for this round using the parsed Stage 3 stats, labeled `3 Loop - Round {review_round}`.
@@ -374,7 +376,7 @@ For each `round` from `1..MAX_ROUNDS_TEST`, set `ROUND_DIR = OUTPUT/round-{round
 ##### Round Step C — Stage 4b Rebuild after Self-Test Fix
 
 1. Mark Stage 4b `in_progress` when the first Stage 4b round begins.
-2. Capture `BUILD_START` (touch a marker), then invoke the `hmos-fix-build-errors` skill for a signed rebuild of `HMOS`.
+2. Capture `BUILD_START` (touch a marker), then invoke the `a2h-fix-build-errors` skill for a signed rebuild of `HMOS`.
 3. Treat this as a compile/fix gate only — do **not** expect rebuild-stage report or commit-info artifacts in `ROUND_DIR`.
 4. ⚠️ **CRITICAL — Update `CURRENT_HAP` for the next round**: If the build succeeds, resolve `AUTHORITATIVE_ENTRY` directly from `HMOS/entry/build/default/outputs/default/` (prefer `entry-default-signed.hap`, else the first `*-signed.hap`), **run Package-Set Collection** with `BUILD_ROOT = HMOS`, `DEST = ROUND_DIR/package-set/`, that resolved `AUTHORITATIVE_ENTRY`, and the captured `BUILD_START`, and then set `CURRENT_HAP = ROUND_DIR/package-set/` so the next round's Stage 4 self-tester uses the freshly built set. If collection **fails** or yields zero HAPs, **keep the previous `CURRENT_HAP`** (the prior round's full set — fresher than any legacy single-file resolution) and record that this round produced no fresh package set.
 5. Append one Defect Summary row for this round by combining the parsed Stage 4 and Stage 4a results into a single row labeled `4 Loop - Round {round}`.

package/skills/hmos-incremental-ui-align/README.md

@@ -1,4 +1,4 @@
-# hmos-ui-align
+# hmos-incremental-ui-align
 
 HarmonyOS-Android UI 自动对齐流水线。
 
@@ -73,7 +73,7 @@ HarmonyOS-Android UI 自动对齐流水线。
 在 Claude Code 里直接调用 skill，**把两个工程目录附在需求里**（可作为命名参数，也可在自然语言里说明）：
 
 ```
-/hmos-ui-align android_project_dir: <安卓工程绝对路径> harmony_project_dir: <鸿蒙工程绝对路径>
+/hmos-incremental-ui-align android_project_dir: <安卓工程绝对路径> harmony_project_dir: <鸿蒙工程绝对路径>
 <自然语言需求，描述要对齐的页面+点击路径>
 ```
 
@@ -92,20 +92,20 @@ HarmonyOS-Android UI 自动对齐流水线。
 
 **例 1（单个弹窗对齐）**
 ```
-/hmos-ui-align 鸿蒙版本app(登录状态下，进入首页-点击"AI智能填报"-点击"专业"筛选按钮)
+/hmos-incremental-ui-align 鸿蒙版本app(登录状态下，进入首页-点击"AI智能填报"-点击"专业"筛选按钮)
 得到的弹窗样式和安卓同样路径得到的页面不一致，请修改鸿蒙源码将上述页面与安卓版本完全对齐
 ```
 
 **例 2（补齐缺失页面 + 调真实后台）**
 ```
-/hmos-ui-align 鸿蒙版本app(点击我的-超级会员组件)显示与安卓不一致，且安卓版本在超级会员
+/hmos-incremental-ui-align 鸿蒙版本app(点击我的-超级会员组件)显示与安卓不一致，且安卓版本在超级会员
 上点击"会员中心"会跳到超级会员弹窗页，鸿蒙也没有这页。请修改鸿蒙源码将这些页面与安卓版本
 完全对齐，不要mock数据，调用真实后台数据
 ```
 
 **例 3（多级路径 + 多个页面）**
 ```
-/hmos-ui-align 鸿蒙版本（点击底部高考按钮 -> 带年纪查专业 -> 点击某一具体专业(如临床医学)
+/hmos-incremental-ui-align 鸿蒙版本（点击底部高考按钮 -> 带年纪查专业 -> 点击某一具体专业(如临床医学)
 -> 点击就业分析，到达"专业就业健康度"展示页面）以及在"专业就业健康度"页面上点击"完整数
 据指标"到达的就业健康度详情页都和安卓同一路径的不一致。比较这些页面的差别并将他们在视觉
 效果上完全对齐，不要用mock数据，调用后台真实逻辑
@@ -164,7 +164,7 @@ skill 会严格按 `SKILL.md` 里的流水线跑：
 - 每个尺寸 / icon / alignment 都要回溯到安卓源码的 XML 或资源值，不允许"看起来差不多"
 
 ### Step 4 · 编译校验
-若可用，调 `hmos-fix-build-errors` skill 确保工程能编过。**不会自动部署**。
+若可用，调 `a2h-fix-build-errors` skill 确保工程能编过。**不会自动部署**。
 
 ---
 
@@ -230,7 +230,7 @@ A: 可以。Step 2.2 会改从鸿蒙源码读，Step 3 会按安卓的实现规
 A: Step 1.3 默认扫描交互元素（tab / 弹窗 / 展开收起等）并递归采集。想关掉请在需求里写「只对齐主页面」。
 
 **Q: 改完会自动部署吗？**
-A: 不会。Step 4 只跑编译验证（如果 `hmos-fix-build-errors` skill 可用）。部署自己来。
+A: 不会。Step 4 只跑编译验证（如果 `a2h-fix-build-errors` skill 可用）。部署自己来。
 
 **Q: 能不能只做差异分析、不改码？**
 A: 目前流水线是端到端的。如果只想要分析产物，跑完 Step 2 后手动中断即可，所有 `UI_Analysis.md` 和 `UI_comparison.md` 都会落盘在 `{capture_output_dir}/task_{timestamp}/` 下。

package/skills/hmos-incremental-ui-align/SKILL.md

@@ -351,7 +351,7 @@ Read `fix_checklist.md` and verify every item is marked `[x]`. If any items rema
 **Coverage re-check**: For each page, the `<!-- source: ... | items=N -->` comment records how many items the script extracted. Confirm the number of `- [x]`/`- [~]` lines under each page heading still matches that `items=N` count — if fewer, items were silently dropped during the review pass; recover them from the page's `UI_comparison.md`.
 
 ## Step 4 validate and build (Main Agent)
-if available, use `hmos-fix-build-errors` skill to verify the project is compilable, do not deploy.
+if available, use `a2h-fix-build-errors` skill to verify the project is compilable, do not deploy.
 
 ## Guidelines
 - **Preserve existing code**: When editing existing files, make targeted edits — never rewrite an entire file from scratch. Respect the existing code structure, variable names, and patterns.

package/skills/hmos-incremental-ui-align/page_align.md

@@ -28,7 +28,7 @@ Based on the diff analysis, flexibly combine editing and creation as needed —
 
 **Resource Conversion:**
 - For each resource referenced by the Android UI, find the corresponding mapping in `{harmony_project_dir}/entry/src/main/resources`
-- If a needed resource does not exist, use the **`hmos-resources-convert`** skill to convert it
+- If a needed resource does not exist, use the **`a2h-resource-convert`** skill to convert it
 
 **Layout Conversion:**
 - Consult `./references/android-to-harmonyOS-ui-layout-mapping-reference.md` for all layout container mappings and layout attribute mappings

package/skills/hmos-spec-generate/SKILL.md

@@ -36,7 +36,7 @@ You are a **Spec Generator** that produces high-quality requirement specificatio
 
 ## Expected Output
 
-- One markdown spec file per requirement split out of `requirement_description_file`, written under `spec_output_dir` as **`<feature>-SPEC.md`**, where `<feature>` is the requirement title. The `-SPEC.md` suffix is required by the downstream `hmos-test-case-generation` skill, which only accepts a `spec-path` ending in it.
+- One markdown spec file per requirement split out of `requirement_description_file`, written under `spec_output_dir` as **`<feature>-SPEC.md`**, where `<feature>` is the requirement title. The `-SPEC.md` suffix is required by the downstream `a2h-test-case-generation` skill, which only accepts a `spec-path` ending in it.
 
 ---
 
@@ -365,7 +365,7 @@ These are the authoring rules the final spec MUST follow:
 ### Step 0 — Validate inputs and split requirements
 
 1. Verify `requirement_description_file` exists and is a readable file, then split its content into individual requirements by input type. Keep each requirement's text verbatim and record them in order; do NOT analyze them yet. If no requirement can be extracted, stop and report the error.
-   - **Excel type (`.xlsx` / `.xlsm` / `.csv`)**: run `node <skill-dir>/scripts/parse_requirements.ts --input <requirement_description_file> --json` via `Bash` to read the file content. Each item of the returned JSON array is one raw requirement: `uiPath` is the title, `description` is the requirement body. If the script errors, surface it verbatim and stop.
+   - **Excel type (`.xlsx` / `.xlsm` / `.csv`)**: run `node <skill-dir>/scripts/parse_requirements.mjs --input <requirement_description_file> --json` via `Bash` to read the file content. Each item of the returned JSON array is one raw requirement: `uiPath` is the title, `description` is the requirement body. If the script errors, surface it verbatim and stop.
    - **Text type (`.txt` / `.md`)**: read the content directly and split it into individual requirements (each requirement starts with a title line followed by its description; requirements are separated by blank lines).
 2. Verify `android_project_dir` exists and is a directory.
 3. Ensure `spec_output_dir` exists (create it if it does not).