android2harmony 0.1.1 → 0.1.3

package/tools/autotest/engine/testcases-tool.ts

@@ -0,0 +1,246 @@
+/**
+ * Generate or validate testcases.json for the Self-Testing Agent.
+ *
+ * TS port of `tools/test-tools/autotest/testcases_tool.py`.
+ *
+ * Subcommands:
+ *   generate <input-json> <output-json> [--validate]
+ *       Rewrite app_name → bundle_name and compose `test_steps` strictly
+ *       ("动作：..." / "预期结果：..."). Optionally re-validate the output.
+ *
+ *   validate <testcases-json>
+ *       Check a `testcases.json` (array of cases) against the schema in
+ *       `testcases_schema.md`. Exit 0 = PASSED, exit 1 = FAILED.
+ *
+ * The forbidden-strings and section-header rules live in this file as the
+ * single source of truth — generate enforces them at write time, validate
+ * re-checks them on existing files.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+
+const FORBIDDEN_STRINGS = [
+  '前置条件',
+  'Spec:',
+  'Scenario:',
+  'ability_name:',
+  'module_name:',
+] as const;
+
+const SECTION_HEADER_RE = /【(.+?)】/;
+
+const REQUIRED_LINES = ['动作：', '预期结果：'] as const;
+
+const TEST_STEPS_TEMPLATE = '动作：{actions}\n预期结果：{expected_results}';
+
+/** Input case shape from the extractor. */
+interface InputCase {
+  case_name: string;
+  actions: string;
+  expected_results: string;
+}
+
+/** Input document: extractor output consumed by `generate`. */
+interface InputData {
+  bundle_name: string;
+  app_name: string;
+  cases: InputCase[];
+}
+
+/** Output case shape: what we write to testcases.json. */
+interface OutputCase {
+  case_name: string;
+  bundle_name: string;
+  app_name: string;
+  test_steps: string;
+}
+
+/** Safety net: replace remaining app_name references with bundle_name. */
+function rewriteAppName(text: string, appName: string, bundleName: string): string {
+  if (appName && text.includes(appName)) {
+    return text.replaceAll(appName, bundleName);
+  }
+  return text;
+}
+
+/** Compose a compliant test_steps string with only 动作 and 预期结果. */
+function composeTestSteps(
+  appName: string,
+  bundleName: string,
+  actions: string,
+  expectedResults: string,
+): string {
+  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, diverging from Python str.format().
+  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: InputData): OutputCase[] {
+  const { bundle_name: bundleName, app_name: appName, cases } = inputData;
+  // Fail loudly on malformed extractor input instead of silently writing
+  // `undefined`/dropped keys (Python indexed with [] and raised KeyError).
+  const missingTop = (['bundle_name', 'app_name', 'cases'] as const).filter(
+    (k) => inputData[k] === undefined,
+  );
+  if (missingTop.length > 0) {
+    throw new Error(`FATAL: input is missing required key(s): ${missingTop.join(', ')}.`);
+  }
+  const result: OutputCase[] = [];
+  for (const [i, c] of cases.entries()) {
+    const missingCase = (['case_name', 'actions', 'expected_results'] as const).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: string): string[] {
+  const raw = fs.readFileSync(filepath, 'utf-8');
+  const cases: unknown = JSON.parse(raw);
+
+  if (!Array.isArray(cases)) return ['Root element is not a JSON array'];
+
+  const errors: string[] = [];
+  const globalSectionRe = new RegExp(SECTION_HEADER_RE.source, 'g');
+  cases.forEach((c: any, i: number) => {
+    const ts: string = c?.test_steps ?? '';
+    const name: string = c?.case_name ?? `case_${i}`;
+    const appName: string = c?.app_name ?? '';
+    const bundleName: string = 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: RegExpExecArray | null;
+    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: string, output: string, doValidate: boolean): void {
+  const inputData = JSON.parse(fs.readFileSync(input, 'utf-8')) as InputData;
+  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: string): void {
+  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')) as unknown[];
+  console.log(`VALIDATION PASSED: all ${cases.length} cases have correct test_steps format`);
+}
+
+/** CLI entry — wires up commander with `generate` and `validate` subcommands. */
+export function main(): void {
+  const program = new Command();
+  program.description(
+    'Generate or validate testcases.json for the Self-Testing Agent.',
+  );
+
+  program
+    .command('generate')
+    .description('Generate compliant testcases.json from an extracted input')
+    .argument('<input>', 'Path to the extracted input JSON')
+    .argument('<output>', 'Path to write the compliant testcases.json')
+    .option('--validate', 'After writing, re-validate the output against the schema')
+    .action((input: string, output: string, opts: { validate?: boolean }) => {
+      cmdGenerate(input, output, !!opts.validate);
+    });
+
+  program
+    .command('validate')
+    .description('Validate an existing testcases.json against the schema')
+    .argument('<path>', 'Path to the testcases.json to validate')
+    .action((filepath: string) => {
+      cmdValidate(filepath);
+    });
+
+  program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const isMainEntry =
+  !!process.argv[1] && path.resolve(process.argv[1]) === __filename;
+if (isMainEntry) {
+  main();
+}

package/tools/autotest/resolve-metadata-tool.ts

@@ -0,0 +1,143 @@
+/**
+ * Resolve App Metadata — discover `bundle_name` / `app_name` from a HarmonyOS
+ * project and write `app-metadata.json`.
+ *
+ * Subcommand:
+ *   resolve-metadata --project-dir <dir> --output <path>
+ *       Reads `<project-dir>/AppScope/app.json5` (JSON5 via jsonc-parser),
+ *       extracts `app.bundleName` and `app.label` (resolving `$string:xxx`
+ *       references from the base-qualifier string.json), writes
+ *       `{bundle_name, app_name, project_root}` to `--output`, and emits the
+ *       same JSON to stdout.
+ *
+ * Exit codes: 0 = success (JSON emitted + file written), 1 = any failure
+ * (invalid project root, JSON5 parse failure, missing bundleName, write
+ * failure). Errors go to stderr; stdout carries exactly one JSON line on
+ * success. This is the deterministic replacement for the LLM-driven discovery
+ * that previously lived in the self-tester agent prompt (S2/S3).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { parse as parseJsonc, printParseErrorCode, type ParseError } from 'jsonc-parser';
+
+/**
+ * Resolve a `$string:<key>` reference from `AppScope/resources/base/element/string.json`
+ * (the HarmonyOS base-qualifier string resource file). Returns the value, or null
+ * when the file is missing / unparseable / the key is absent. The caller falls back
+ * to the literal `$string:xxx` text on null — app_name is a display name, not
+ * load-bearing, so a missing resource must not fail the run.
+ */
+function resolveStringResource(projectRoot: string, key: string): string | null {
+  const stringJson = path.join(
+    projectRoot, 'AppScope', 'resources', 'base', 'element', 'string.json',
+  );
+  if (!fs.existsSync(stringJson)) return null;
+  let doc: unknown;
+  try {
+    doc = parseJsonc(fs.readFileSync(stringJson, 'utf-8'));
+  } catch {
+    return null;
+  }
+  const arr = (doc as { string?: unknown })?.string;
+  if (!Array.isArray(arr)) return null;
+  const entry = arr.find((e) => (e as { name?: unknown })?.name === key);
+  const value = (entry as { value?: unknown } | undefined)?.value;
+  return typeof value === 'string' && value ? value : null;
+}
+
+export interface ResolveMetadataArgs {
+  projectDir: string;
+  output: string;
+}
+
+export function cmdResolveMetadata(args: ResolveMetadataArgs): void {
+  const projectRoot = path.resolve(args.projectDir);
+
+  const appJson5 = path.join(projectRoot, 'AppScope', 'app.json5');
+  if (!fs.existsSync(appJson5)) {
+    console.error(`not a HarmonyOS project root (no AppScope/app.json5): ${projectRoot}`);
+    process.exit(1);
+  }
+
+  let doc: unknown;
+  const errs: ParseError[] = [];
+  try {
+    doc = parseJsonc(fs.readFileSync(appJson5, 'utf-8'), errs, { allowTrailingComma: true });
+  } catch (e) {
+    console.error(`failed to parse ${appJson5}: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+  }
+  if (errs.length > 0) {
+    console.error(
+      `failed to parse ${appJson5}: ${errs.map((e) => printParseErrorCode(e.error)).join('; ')}`,
+    );
+    process.exit(1);
+  }
+
+  const app = (doc as { app?: Record<string, unknown> })?.app;
+  const bundleName = app?.bundleName;
+  if (typeof bundleName !== 'string' || !bundleName) {
+    console.error(`missing app.bundleName (string) in ${appJson5}`);
+    process.exit(1);
+  }
+
+  const label = app?.label;
+  let appName: string;
+  if (typeof label === 'string' && label.startsWith('$string:')) {
+    const key = label.slice('$string:'.length);
+    const resolved = resolveStringResource(projectRoot, key);
+    if (resolved) {
+      appName = resolved;
+    } else {
+      console.error(
+        `warning: string resource '${key}' not found in AppScope/resources/base/element/string.json — ` +
+          `using literal '${label}' as app_name`,
+      );
+      appName = label;
+    }
+  } else if (typeof label === 'string' && label) {
+    appName = label;
+  } else {
+    // ponytail: label missing/empty — bundleName is a valid non-empty string, reuse it.
+    // app_name is display-only; failing the whole run over it would be over-strict.
+    console.error(`warning: missing app.label in ${appJson5} — using bundleName as app_name`);
+    appName = bundleName;
+  }
+
+  const meta = { bundle_name: bundleName, app_name: appName, project_root: projectRoot };
+
+  try {
+    fs.mkdirSync(path.dirname(path.resolve(args.output)), { recursive: true });
+    fs.writeFileSync(path.resolve(args.output), JSON.stringify(meta) + '\n', 'utf-8');
+  } catch (e) {
+    console.error(`failed to write ${args.output}: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify(meta));
+}
+
+/** CLI entry — wires up the `resolve-metadata` subcommand. */
+export function main(): void {
+  const program = new Command();
+  program
+    .description('从 HarmonyOS 工程解析 bundle_name/app_name 并写 app-metadata.json')
+    .requiredOption('--project-dir <dir>', 'HarmonyOS 工程根目录（含 AppScope/app.json5）')
+    .requiredOption('--output <path>', 'app-metadata.json 输出路径')
+    .action((opts: ResolveMetadataArgs) => {
+      cmdResolveMetadata({ projectDir: opts.projectDir, output: opts.output });
+    });
+
+  program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const isMainEntry = !!process.argv[1] && path.resolve(process.argv[1]) === __filename;
+if (isMainEntry) {
+  main();
+}

package/tools/autotest/runner/logger.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal logger for the self-test runner. Writes `[timestamp] LEVEL msg` to an
+ * optional file stream and to stderr — never stdout, which carries the strict
+ * JSON the orchestrator parses.
+ */
+import fs from 'node:fs';
+
+/** Format a Date as `YYYY-MM-DD HH:MM:SS`. Shared with self-test-runner's status log. */
+export function formatLogTimestamp(d: Date): string {
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+    `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+  );
+}
+
+export interface Logger {
+  info(msg: string): void;
+  warning(msg: string): void;
+  error(msg: string): void;
+  debug(msg: string): void;
+}
+
+type Level = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR';
+const LEVEL_RANK: Record<Level, number> = { DEBUG: 0, INFO: 1, WARNING: 2, ERROR: 3 };
+
+/** Logger writing to `stream` (if non-null) and stderr; drops messages below `minLevel`. */
+export function createLogger(
+  stream: fs.WriteStream | null,
+  minLevel: 'DEBUG' | 'INFO' = 'DEBUG',
+): Logger {
+  const rank = LEVEL_RANK[minLevel];
+  const write = (level: Level, msg: string): void => {
+    if (LEVEL_RANK[level] < rank) return;
+    const line = `[${formatLogTimestamp(new Date())}] ${level} ${msg}`;
+    if (stream) stream.write(line + '\n');
+    process.stderr.write(line + '\n');
+  };
+  return {
+    info: (m) => write('INFO', m),
+    warning: (m) => write('WARNING', m),
+    error: (m) => write('ERROR', m),
+    debug: (m) => write('DEBUG', m),
+  };
+}

package/tools/autotest/runner/process-utils.ts

@@ -0,0 +1,41 @@
+/**
+ * Process helpers for the self-test runner: native liveness + tree-kill.
+ */
+import { execFileSync } from 'node:child_process';
+
+const IS_WIN = process.platform === 'win32';
+
+/** Whether `pid` is alive, via `kill(pid, 0)`: ESRCH = dead, EPERM = alive. */
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** Kill `pid` + descendants. Windows: `taskkill /F /T`; POSIX: SIGKILL the group then the pid. Best-effort. */
+export function killProcessTree(pid: number): void {
+  if (IS_WIN) {
+    try {
+      execFileSync('taskkill', ['/F', '/T', '/PID', String(pid)], {
+        timeout: 10000,
+        windowsHide: true,
+        stdio: 'ignore',
+      });
+    } catch {
+      // best effort
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // best effort
+    }
+  }
+}

package/tools/autotest/validate.ts

@@ -0,0 +1,115 @@
+/**
+ * Self-test input validation gates — TS ports of the `uv run python -c "..."`
+ * one-liners that previously lived inline in `agents/self-tester.md`.
+ *
+ * Folding them here removes a cold Python+uv start per check and gives the
+ * logic a single, typed, testable home. Each function is pure and returns
+ * `{ ok, message }`; the CLI layer prints `message` to stdout on success or
+ * stderr+exit(1) on failure, matching the prompt's `… && echo OK`
+ * expectation. No stdout-JSON contract applies to these gates (unlike
+ * run/status/kill) — they are simple human-readable pass/fail checks.
+ *
+ * a2h edition: the config-dependent gates (`checkConfig`, `resolveDir`) were
+ * dropped — a2h has no `~/.hometrans/config.json`; model params are injected
+ * by the plugin tool via stdin. Only the pure file-shape checks remain.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface CheckResult {
+  ok: boolean;
+  message: string;
+}
+
+/**
+ * `hap_path` is a comma-separated list of files/dirs — each entry a
+ * `.hap`/`.hsp` file or a directory. Every entry must exist and, across all
+ * entries, at least one `.hap` (the entry package) must be present.
+ */
+export function checkHap(hapArg: string): CheckResult {
+  const parts = hapArg
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return { ok: false, message: 'hap_path empty' };
+
+  for (const p of parts) {
+    if (!fs.existsSync(p)) return { ok: false, message: `path not found: ${p}` };
+  }
+
+  const haps: string[] = [];
+  for (const p of parts) {
+    const names = fs.statSync(p).isDirectory() ? fs.readdirSync(p) : [path.basename(p)];
+    for (const n of names) {
+      if (n.toLowerCase().endsWith('.hap')) haps.push(n);
+    }
+  }
+  if (haps.length === 0) {
+    return { ok: false, message: 'no entry .hap found across hap_path entries' };
+  }
+  return { ok: true, message: 'OK' };
+}
+
+/**
+ * `setup=false` precondition: both JSONs must parse, `testcases.json` must be a
+ * non-empty array, and `app-metadata.json` must carry the required keys.
+ */
+export function checkInputs(testcasesPath: string, metadataPath: string): CheckResult {
+  let t: unknown;
+  try {
+    t = JSON.parse(fs.readFileSync(testcasesPath, 'utf-8'));
+  } catch (e) {
+    return { ok: false, message: `testcases.json failed to parse: ${(e as Error).message}` };
+  }
+  if (!Array.isArray(t) || t.length === 0) {
+    return { ok: false, message: 'testcases.json empty or not a list' };
+  }
+
+  let m: unknown;
+  try {
+    m = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+  } catch (e) {
+    return { ok: false, message: `app-metadata.json failed to parse: ${(e as Error).message}` };
+  }
+  // A JSON primitive/array has no keys → treat as missing fields (avoids the
+  // `in` operator throwing a TypeError on a non-object).
+  if (typeof m !== 'object' || m === null || Array.isArray(m)) {
+    return { ok: false, message: 'app-metadata.json missing required fields' };
+  }
+  const mo = m as Record<string, unknown>;
+  for (const k of ['bundle_name', 'app_name', 'project_root']) {
+    if (!(k in mo)) return { ok: false, message: 'app-metadata.json missing required fields' };
+  }
+  return { ok: true, message: 'OK' };
+}
+
+/**
+ * `[PRE]` cases must occupy a contiguous block starting at index 0 in
+ * `testcases.json`. Run only when pre-cases were extracted.
+ */
+export function checkPre(testcasesPath: string): CheckResult {
+  let d: unknown;
+  try {
+    d = JSON.parse(fs.readFileSync(testcasesPath, 'utf-8'));
+  } catch (e) {
+    return { ok: false, message: `testcases.json failed to parse: ${(e as Error).message}` };
+  }
+  if (!Array.isArray(d)) return { ok: false, message: 'testcases.json not a list' };
+
+  const pre: number[] = [];
+  for (let i = 0; i < d.length; i++) {
+    const name = (d[i] as { case_name?: unknown })?.case_name;
+    if (typeof name !== 'string') {
+      return { ok: false, message: `testcases.json entry at index ${i} missing string case_name` };
+    }
+    if (name.startsWith('[PRE] ')) pre.push(i);
+  }
+  const contiguous = pre.every((v, idx) => v === idx);
+  if (!contiguous) {
+    return {
+      ok: false,
+      message: `[PRE] entries must be contiguous from index 0, got ${JSON.stringify(pre)}`,
+    };
+  }
+  return { ok: true, message: `OK: ${pre.length} [PRE] entries at front` };
+}