android2harmony 0.1.4 → 0.1.6

package/skills/hmos-integration-test/scripts/testcases-tool.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * Generate or validate testcases.json for the Self-Testing Agent.
+ *
+ * CLI (no subcommands — positional args + flags):
+ *   testcases-tool.mjs <input-json> <output-json> [--validate]
+ *       Read `_extracted.json` ({bundle_name, app_name, cases[]}) and write
+ *       `testcases.json` (array of {case_name, bundle_name, app_name, test_steps}),
+ *       composing test_steps strictly as "动作：..." / "预期结果：..." and
+ *       rewriting app_name → bundle_name. With --validate, re-check the output.
+ *
+ *   testcases-tool.mjs --check-only <testcases-json>
+ *       Validate an existing testcases.json (array of cases) against the
+ *       in-file rules (FORBIDDEN_STRINGS / REQUIRED_LINES / TEST_STEPS_TEMPLATE).
+ *       Exit 0 = PASSED, exit 1 = FAILED.
+ *
+ * The forbidden-strings and section-header rules live in this file as the
+ * single source of truth — generation enforces them at write time, validation
+ * re-checks them on existing files.
+ */
+import fs from 'node:fs';
+const FORBIDDEN_STRINGS = [
+    '前置条件',
+    'Spec:',
+    'Scenario:',
+    'ability_name:',
+    'module_name:',
+];
+const SECTION_HEADER_RE = /【(.+?)】/;
+const REQUIRED_LINES = ['动作：', '预期结果：'];
+const TEST_STEPS_TEMPLATE = '动作：{actions}\n预期结果：{expected_results}';
+/** Safety net: replace remaining app_name references with bundle_name. */
+function rewriteAppName(text, appName, bundleName) {
+    if (appName && text.includes(appName)) {
+        return text.replaceAll(appName, bundleName);
+    }
+    return text;
+}
+/** Compose a compliant test_steps string with only 动作 and 预期结果. */
+function composeTestSteps(appName, bundleName, actions, expectedResults) {
+    const rewrittenActions = rewriteAppName(actions, appName, bundleName);
+    const rewrittenExpected = rewriteAppName(expectedResults, appName, bundleName);
+    // Use function replacements so '$' sequences ($&, $$, $1, ...) in the action /
+    // expected text are inserted literally — String.replace with a STRING argument
+    // would interpret them.
+    let testSteps = TEST_STEPS_TEMPLATE.replace('{actions}', () => rewrittenActions).replace('{expected_results}', () => rewrittenExpected);
+    // Final safety: rewrite once more in case app_name only became visible after composition.
+    testSteps = rewriteAppName(testSteps, appName, bundleName);
+    for (const forbidden of FORBIDDEN_STRINGS) {
+        if (testSteps.includes(forbidden)) {
+            throw new Error(`FATAL: forbidden string '${forbidden}' found in generated test_steps. ` +
+                `This is a bug in testcases-tool.`);
+        }
+    }
+    const sectionMatch = SECTION_HEADER_RE.exec(testSteps);
+    if (sectionMatch) {
+        throw new Error(`FATAL: unexpected section header 【${sectionMatch[1]}】 in generated test_steps. ` +
+            `test_steps should only contain 动作 and 预期结果.`);
+    }
+    return testSteps;
+}
+/** Generate compliant testcases array from input data. */
+export function generate(inputData) {
+    const { bundle_name: bundleName, app_name: appName, cases } = inputData;
+    // Fail loudly on malformed extractor input instead of silently writing
+    // `undefined`/dropped keys.
+    const missingTop = ['bundle_name', 'app_name', 'cases'].filter((k) => inputData[k] === undefined);
+    if (missingTop.length > 0) {
+        throw new Error(`FATAL: input is missing required key(s): ${missingTop.join(', ')}.`);
+    }
+    const result = [];
+    for (const [i, c] of cases.entries()) {
+        const missingCase = ['case_name', 'actions', 'expected_results'].filter((k) => c[k] === undefined);
+        if (missingCase.length > 0) {
+            throw new Error(`FATAL: case ${i} (${c.case_name ?? '<no case_name>'}) is missing required key(s): ` +
+                `${missingCase.join(', ')}.`);
+        }
+        const testSteps = composeTestSteps(appName, bundleName, c.actions, c.expected_results);
+        result.push({
+            case_name: c.case_name,
+            bundle_name: bundleName,
+            app_name: appName,
+            test_steps: testSteps,
+        });
+    }
+    return result;
+}
+/** Return a list of validation error messages. Empty list means PASSED. */
+export function validateTestcases(filepath) {
+    let raw = fs.readFileSync(filepath, 'utf-8');
+    if (raw.charCodeAt(0) === 0xfeff)
+        raw = raw.slice(1);
+    const cases = JSON.parse(raw);
+    if (!Array.isArray(cases))
+        return ['Root element is not a JSON array'];
+    const errors = [];
+    const globalSectionRe = new RegExp(SECTION_HEADER_RE.source, 'g');
+    cases.forEach((c, i) => {
+        const ts = c?.test_steps ?? '';
+        const name = c?.case_name ?? `case_${i}`;
+        const appName = c?.app_name ?? '';
+        const bundleName = c?.bundle_name ?? '';
+        const prefix = `Case ${i + 1} [${name}]`;
+        for (const required of REQUIRED_LINES) {
+            if (!ts.includes(required))
+                errors.push(`${prefix}: MISSING ${required} line`);
+        }
+        for (const forbidden of FORBIDDEN_STRINGS) {
+            if (ts.includes(forbidden)) {
+                errors.push(`${prefix}: CONTAINS ${forbidden} (must be excluded)`);
+            }
+        }
+        let m;
+        while ((m = globalSectionRe.exec(ts)) !== null) {
+            errors.push(`${prefix}: CONTAINS unexpected section header 【${m[1]}】 ` +
+                `(test_steps should only contain 动作 and 预期结果)`);
+        }
+        if (appName && bundleName && appName !== bundleName && ts.includes(appName)) {
+            errors.push(`${prefix}: test_steps contains app_name '${appName}' instead of bundle_name ` +
+                `'${bundleName}'. All app name references in test_steps must use bundle_name.`);
+        }
+    });
+    return errors;
+}
+function cmdGenerate(input, output, doValidate) {
+    let raw = fs.readFileSync(input, 'utf-8');
+    if (raw.charCodeAt(0) === 0xfeff)
+        raw = raw.slice(1);
+    const inputData = JSON.parse(raw);
+    const testcases = generate(inputData);
+    fs.writeFileSync(output, JSON.stringify(testcases, null, 2), 'utf-8');
+    console.log(`Generated ${testcases.length} test cases -> ${output}`);
+    if (doValidate) {
+        const errors = validateTestcases(output);
+        if (errors.length > 0) {
+            console.log('VALIDATION FAILED:');
+            for (const e of errors)
+                console.log(`  [FAIL] ${e}`);
+            process.exit(1);
+        }
+        console.log(`VALIDATION PASSED: all ${testcases.length} cases conform to the schema`);
+    }
+}
+function cmdValidate(filepath) {
+    const errors = validateTestcases(filepath);
+    if (errors.length > 0) {
+        console.log('VALIDATION FAILED:');
+        for (const e of errors)
+            console.log(`  [FAIL] ${e}`);
+        process.exit(1);
+    }
+    const cases = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+    console.log(`VALIDATION PASSED: all ${cases.length} cases have correct test_steps format`);
+}
+// ---- CLI ----
+const args = process.argv.slice(2);
+if (args.includes('-h') || args.includes('--help')) {
+    console.log(`Usage: testcases-tool.mjs <input> <output> [--validate]
+
+Arguments:
+  <input>    Path to the extracted input JSON (_extracted.json)
+  <output>   Path to write testcases.json
+
+Options:
+  --validate    After writing, re-validate the output
+  --check-only <path>    Validate an existing testcases.json without generating
+`);
+    process.exit(0);
+}
+if (args.includes('--check-only')) {
+    // Validate mode
+    const idx = args.indexOf('--check-only');
+    const filepath = args[idx + 1];
+    if (!filepath) {
+        console.error('Usage: testcases-tool.mjs --check-only <path>');
+        process.exit(1);
+    }
+    cmdValidate(filepath);
+}
+else {
+    // Generate mode (default)
+    const input = args.find((a) => !a.startsWith('-'));
+    const output = args.filter((a) => !a.startsWith('-')).find((a) => a !== input);
+    if (!input || !output) {
+        console.error('Usage: testcases-tool.mjs <input> <output> [--validate]');
+        process.exit(1);
+    }
+    cmdGenerate(input, output, args.includes('--validate'));
+}

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

@@ -1,6 +1,6 @@
 ---
 name: hmos-spec-generate
-description: "Generate requirement specification (spec) documents for Android-to-HarmonyOS migration. For each .txt requirement file in a folder, explore the Android codebase via homegraph and decompose the requirement into atomic user scenarios, emitting one markdown spec per file. Use when generating spec docs from a folder of raw requirement descriptions, decomposing requirements into atomic scenarios, or preparing scenario-based specs for HarmonyOS migration. Triggers: spec generation, 生成spec, requirement to spec, atomic scenarios, 拆分场景, scenario decomposition, 需求转spec."
+description: "Generate requirement specification (spec) documents for Android-to-HarmonyOS migration. Read a requirement description file containing multiple requirements, split it into individual requirements, then for each one explore the Android codebase via homegraph and decompose it into atomic user scenarios, emitting one markdown spec per requirement. Use when generating spec docs from raw requirement descriptions, decomposing requirements into atomic scenarios, or preparing scenario-based specs for HarmonyOS migration. Triggers: hmos-spec-generate, spec generation, 生成spec, requirement to spec, atomic scenarios, 拆分场景, scenario decomposition, 需求转spec."
 license: MIT
 allowed-tools:
   - Read
@@ -17,26 +17,26 @@ allowed-tools:
 
 # Spec Generator Skill
 
-You are a **Spec Generator** that produces high-quality requirement specification (spec) documents for Android-to-HarmonyOS migration projects. Given a folder of raw requirement `.txt` files, explore the corresponding Android codebase via homegraph and emit a clean, atomic-scenario-based spec markdown for every requirement.
+You are a **Spec Generator** that produces high-quality requirement specification (spec) documents for Android-to-HarmonyOS migration projects. Given a requirement description file containing multiple requirements, split it into individual requirements, explore the corresponding Android codebase via homegraph and emit a clean, atomic-scenario-based spec markdown for every requirement.
 
 ## Quick Reference
 
 | Item | Value |
 |------|-------|
-| **Input** | `requirement-description-dir` + `android-project-path` + `spec-output-dir` |
-| **Output** | One `<source_filename_without_ext>.md` per input `.txt` under `spec-output-dir` |
+| **Input** | `requirement_description_file` + `android_project_dir` + `spec_output_dir` |
+| **Output** | One `<feature>-SPEC.md` per requirement under `spec_output_dir` |
 | **homegraph** | `npx --yes homegraph <command>` CLI via `Bash` (index management + code queries) |
-| **Processing Mode** | Per-file end-to-end loop (no batch pre-read) |
+| **Processing Mode** | Per-requirement end-to-end loop (split first, then one requirement at a time) |
 
 ## Expected Input
 
-- `requirement-description-dir`: Absolute path to a directory containing one or more `.txt` files. Each `.txt` file's content is the raw requirement description of a single requirement (required).
-- `android-project-path`: Absolute path to the Android project root (required).
-- `spec-output-dir`: Absolute path to the directory where the generated spec files (`xxx.md`) will be written (required).
+- `requirement_description_file`: Absolute path to a requirement description file whose content contains multiple requirements (required). Supported types: Excel (`.xlsx` / `.xlsm` / `.csv`, one row = one requirement) and text (`.txt` / `.md`, one blank-line-separated paragraph = one requirement). See `template/REQ.xlsx` and `template/REQ.txt` for equivalent examples.
+- `android_project_dir`: Absolute path to the Android project root (required).
+- `spec_output_dir`: Absolute path to the directory where the generated spec files (`<feature>-SPEC.md`) will be written (required).
 
 ## Expected Output
 
-- One markdown spec file per input `.txt` requirement file, written under `spec-output-dir`. The spec filename mirrors the source filename with `.md` extension (e.g. `create_playlist.txt` → `create_playlist.md`).
+- 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.
 
 ---
 
@@ -362,41 +362,43 @@ These are the authoring rules the final spec MUST follow:
 
 ## Workflow
 
-### Step 0 — Validate inputs
+### Step 0 — Validate inputs and split requirements
 
-1. Verify `requirement-description-dir` exists and is a directory. List all `.txt` files directly under it (collect the list of filenames only — do NOT read their contents yet). If there are no `.txt` files, stop and report the error.
-2. Verify `android-project-path` exists and is a directory.
-3. Ensure `spec-output-dir` exists (create it if it does not).
+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.
+   - **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).
 
 ### Step 1 — Ensure homegraph has a fresh index for the project
 
-homegraph is invoked exclusively through its CLI via `Bash`. Always prefix commands with `npx` (e.g. `npx --yes homegraph status <android-project-path>`); `npx` resolves the binary without requiring a global install. All index management and code query commands share the same CLI — there is no MCP surface in this skill.
+homegraph is invoked exclusively through its CLI via `Bash`. Always prefix commands with `npx` (e.g. `npx --yes homegraph status <android_project_dir>`); `npx` resolves the binary without requiring a global install. All index management and code query commands share the same CLI — there is no MCP surface in this skill.
 
 homegraph indexes per-project into a local `.homegraph/` directory; there is no central repo registry. Always pass the Android project path as the positional `[path]` argument to scope the command to the Android project (this skill's working directory is the spec project, NOT the Android project, so omitting the path queries the wrong project).
 
 Procedure:
 
-1. Run `npx --yes homegraph status <android-project-path>` to inspect the index state.
+1. Run `npx --yes homegraph status <android_project_dir>` to inspect the index state.
 2. Decide based on the output:
-   - **Not indexed** (no `.homegraph/`) → run `npx --yes homegraph init -i <android-project-path>`, wait for completion.
-   - **Stale** (`npx --yes homegraph status` output does NOT contain `[OK] Index is up to date`) → run `npx --yes homegraph sync <android-project-path>` (incremental; use `npx --yes homegraph index <android-project-path> --force` for a full rebuild), wait for completion.
+   - **Not indexed** (no `.homegraph/`) → run `npx --yes homegraph init -i <android_project_dir>`, wait for completion.
+   - **Stale** (`npx --yes homegraph status` output does NOT contain `[OK] Index is up to date`) → run `npx --yes homegraph sync <android_project_dir>` (incremental; use `npx --yes homegraph index <android_project_dir> --force` for a full rebuild), wait for completion.
    - **Fresh** → proceed to Step 2.
 
 **Hard fail policy** — any of the following stops the skill and surfaces the error to the user; do NOT degrade to `Read` + `Grep`:
 
 - `homegraph` CLI is not reachable via `npx` → ask the user to install it (`npm install -g homegraph` or `npx --yes homegraph install`).
 - `npx --yes homegraph status`, `init`, `sync`, or `index` returns an error → surface the error verbatim and stop. Do not attempt spec generation without an index — the resulting spec would miss code-grounded scenarios.
-- Any `npx --yes homegraph` query reports the project is not indexed → verify `init -i` ran against `android-project-path`.
+- Any `npx --yes homegraph` query reports the project is not indexed → verify `init -i` ran against `android_project_dir`.
 
-### Step 2 — Process each requirement file independently, one at a time
+### Step 2 — Process each requirement independently, one at a time
 
-For each `.txt` filename collected in Step 0, in order, run 2.1 → 2.4 end-to-end before moving to the next file. Do NOT pre-read all `.txt` files.
+For each requirement split out in Step 0, in order, run 2.1 → 2.4 end-to-end before moving to the next requirement.
 
-- **2.1 Read**: Read this file's content verbatim. If empty, warn and skip to the next file.
-- **2.2 Analyze**: Explore the Android codebase for this requirement using the `npx --yes homegraph` CLI (via `Bash`) to retrieve the complete code implementation (entry points, end-to-end call chains, state writes / persistence keys, manifest declarations). Query commands (`query` / `explore` / `node` / `callers` / `callees` / `impact` / `files`) resolve their target project from the current working directory's nearest `.homegraph/` index, so run them from within the Android project root using a subshell — e.g. `cd <android-project-path> && npx --yes homegraph explore "<query>"` (the index commands `status` / `init` / `sync` / `index` accept an explicit path argument, see Step 1). Use `npx --yes homegraph query "<keyword>"` / `npx --yes homegraph explore "<query>"` to locate symbols and read their line-numbered source; `npx --yes homegraph node "<symbol|file>"` to read a single symbol or whole file; `npx --yes homegraph callers "<symbol>"` / `npx --yes homegraph callees "<symbol>"` to walk call chains up and down; `npx --yes homegraph impact "<symbol>"` for change blast radius; `npx --yes homegraph files` to enumerate indexed files; and `Grep` for exact literals (settings keys, DAO columns, `android:key`) that live outside the code graph. Always run query commands from `<android-project-path>` — this skill's working directory is the spec project, NOT the Android project, so running them from elsewhere queries the wrong project (or none). Use the CLI directly — do NOT invoke any MCP tool or nested exploration skill. If any `npx --yes homegraph` call fails unexpectedly, surface the error and stop.
+- **2.1 Scope**: Take this requirement's title + description verbatim as the raw requirement under analysis. If it is empty, warn and skip to the next requirement.
+- **2.2 Analyze**: Explore the Android codebase for this requirement using the `npx --yes homegraph` CLI (via `Bash`) to retrieve the complete code implementation (entry points, end-to-end call chains, state writes / persistence keys, manifest declarations). Query commands (`query` / `explore` / `node` / `callers` / `callees` / `impact` / `files`) resolve their target project from the current working directory's nearest `.homegraph/` index, so run them from within the Android project root using a subshell — e.g. `cd <android_project_dir> && npx --yes homegraph explore "<query>"` (the index commands `status` / `init` / `sync` / `index` accept an explicit path argument, see Step 1). Use `npx --yes homegraph query "<keyword>"` / `npx --yes homegraph explore "<query>"` to locate symbols and read their line-numbered source; `npx --yes homegraph node "<symbol|file>"` to read a single symbol or whole file; `npx --yes homegraph callers "<symbol>"` / `npx --yes homegraph callees "<symbol>"` to walk call chains up and down; `npx --yes homegraph impact "<symbol>"` for change blast radius; `npx --yes homegraph files` to enumerate indexed files; and `Grep` for exact literals (settings keys, DAO columns, `android:key`) that live outside the code graph. Always run query commands from `<android_project_dir>` — this skill's working directory is the spec project, NOT the Android project, so running them from elsewhere queries the wrong project (or none). Use the CLI directly — do NOT invoke any MCP tool or nested exploration skill. If any `npx --yes homegraph` call fails unexpectedly, surface the error and stop.
 - **2.3 Decompose**: Using the raw requirement + code from 2.2, generate the spec per `## Principles` and `## Spec Few-shot Samples`.
-- **2.4 Write**: Write the spec to `<spec-output-dir>/<source_filename_without_ext>.md` (overwrite if exists), then move on to the next file.
+- **2.4 Write**: Write the spec to `<spec_output_dir>/<feature>-SPEC.md` (overwrite if exists), then move on to the next requirement.
 
 ### Step 3 — Report
 
-After all requirement files have been processed (or skipped with a warning), report a brief summary listing each generated spec file path and any files that were skipped.
+After all requirements have been processed (or skipped with a warning), report a brief summary listing each generated spec file path and any requirements that were skipped.