@harmonyos-arkts/d2h 0.1.5 → 0.1.7

package/skills/managing-d2h-toolchain/scripts/manage-toolchain.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const skillDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+export function loadManifest(file = path.join(skillDir, 'toolchain.json')) {
+  const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (manifest?.schemaVersion !== 1 || !manifest.tools || Array.isArray(manifest.tools) ||
+      !Object.keys(manifest.tools).length) throw new Error('invalid toolchain manifest');
+  for (const [name, tool] of Object.entries(manifest.tools)) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name) || tool?.package !== `@harmonyos-arkts/${name}` ||
+        !/^\d+\.\d+\.\d+$/.test(tool.version) || !tool.capabilities ||
+        !Object.keys(tool.capabilities).length || Object.values(tool.capabilities).some(args =>
+          !Array.isArray(args) || !args.length || args.some(arg => typeof arg !== 'string' || !arg))) {
+      throw new Error(`invalid toolchain entry: ${name}`);
+    }
+  }
+  return manifest;
+}
+
+export function run(command, args) {
+  let executable = command;
+  let parameters = args;
+  if (process.platform === 'win32') {
+    const quote = value => `'${value.replaceAll("'", "''")}'`;
+    const binary = /^(npm|appgraph|droid2hmos)$/.test(command) ? `${command}.cmd` : command;
+    const script = `& ${[binary, ...args].map(quote).join(' ')}; exit $LASTEXITCODE`;
+    executable = 'powershell.exe';
+    parameters = ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')];
+  }
+  const result = spawnSync(executable, parameters, { encoding: 'utf8', windowsHide: true, timeout: 300000 });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '', error: result.error };
+}
+
+export function inspect(name, tool, runner = run) {
+  const result = runner(name, ['--version']);
+  const installedVersion = result.status === 0 ? /\b\d+\.\d+\.\d+\b/.exec(`${result.stdout}\n${result.stderr}`)?.[0] ?? null : null;
+  const capabilities = Object.fromEntries(Object.entries(tool.capabilities).map(([capability, args]) => {
+    const probe = installedVersion ? runner(name, args) : null;
+    const command = capability === 'analyze-android' ? 'analyze' : capability === 'build-android' ? 'build' : capability;
+    return [capability, probe?.status === 0 && `${probe.stdout}\n${probe.stderr}`.includes(command)];
+  }));
+  return { name, package: tool.package, expectedVersion: tool.version, installedVersion,
+    status: installedVersion === tool.version && Object.values(capabilities).every(Boolean) ? 'passed' : 'failed', capabilities };
+}
+
+export function manage({ action = 'check', manifestFile, force = false, runner = run, log = console.log } = {}) {
+  if (!['check', 'install'].includes(action)) throw new Error(`unsupported action: ${action}`);
+  const manifest = loadManifest(manifestFile);
+  const results = Object.entries(manifest.tools).map(([name, tool]) => inspect(name, tool, runner));
+  for (const item of results) log(`${item.status}: ${item.package} expected ${item.expectedVersion}, installed ${item.installedVersion ?? 'missing'}; capabilities ${JSON.stringify(item.capabilities)}`);
+  if (action === 'check') return results.every(item => item.status === 'passed');
+  const targets = force ? results : results.filter(item => item.status !== 'passed');
+  if (!targets.length) return true;
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const root = runner(npm, ['root', '--global']);
+  if (root.status !== 0 || !root.stdout.trim()) throw new Error(`cannot inspect global npm installation: ${root.stderr || root.error?.message || 'empty root'}`);
+  // Check every target before making changes, so a protected npm link cannot cause a partial installation.
+  for (const item of targets) {
+    const target = path.join(root.stdout.trim(), ...item.package.split('/'));
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink() && !force) {
+      throw new Error(`${item.package} is an npm link at ${target}; rerun with --force to replace it`);
+    }
+  }
+  for (const item of targets) {
+    const coordinate = `${item.package}@${item.expectedVersion}`;
+    const target = path.join(root.stdout.trim(), ...item.package.split('/'));
+    const result = runner(npm, ['install', '--global', coordinate]);
+    if (result.status !== 0) throw new Error(`failed to install ${coordinate}: ${result.stderr || result.error?.message}`);
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) {
+      throw new Error(`${coordinate} installation completed but npm link remains at ${target}`);
+    }
+    const verified = inspect(item.name, manifest.tools[item.name], runner);
+    if (verified.status !== 'passed') throw new Error(`${coordinate} installed but CLI version or capabilities failed verification`);
+    log(`installed and verified ${coordinate}`);
+  }
+  return true;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [action = 'check', ...args] = process.argv.slice(2);
+    if (action === '--help' || action === '-h') {
+      console.log('Usage: node manage-toolchain.mjs check|install [--force]\nChecks exact AppGraph/droid2hmos versions and capabilities; install only changes missing or incompatible packages.');
+    } else {
+      if (args.some(arg => arg !== '--force') || args.filter(arg => arg === '--force').length > 1 || (action === 'check' && args.length)) {
+        throw new Error('usage: node manage-toolchain.mjs check|install [--force]');
+      }
+      if (!manage({ action, force: args.includes('--force') })) process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(`manage-toolchain: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}

package/skills/appgraph-rule-audit/SKILL.md

@@ -1,77 +0,0 @@
----
-name: appgraph-rule-audit
-description: Review fresh AppGraph and SPEC results after Android analysis, identify evidence-backed opportunities to improve page, ownership, and navigation rules, and write a local rule-opportunity report. Use after `droid2hmos analyze android` and before initializing the migration report; do not use it to edit analyzer output or implement rules.
----
-
-# Audit AppGraph rule opportunities
-
-Review the latest deterministic Android analysis and produce maintainable rule-improvement candidates. This is a read-only diagnostic step. Do not edit AppGraph, SPEC facts, Android source, rule packs, or analyzers.
-
-All `.migration/...` paths below live in the sibling migration workspace `<android-project>-migration/.migration/`. Never fall back to the legacy `<android-project>/.migration/`; if the sibling workspace or required artifacts are absent, return a structured unavailable/stale result.
-
-## Preconditions
-
-1. The caller must supply artifacts from a successful `droid2hmos analyze android <android-project>` run; this Skill does not run analysis itself.
-2. Locate `.migration/spec/index.json`, `.migration/spec/facts/`, and `.migration/appgraph/app-graph.json`.
-3. Check that the SPEC `generation.sourceRevision`, when present, matches the Android Git HEAD. Treat a mismatch or missing required artifact as stale analysis: write no recommendations and return the structured result below. Do not run analysis or ask the user whether to run it.
-4. Keep all source and generated data local. Network access is unnecessary.
-
-## Review workflow
-
-1. Read only the indexes and summaries first. Record page counts by type, navigation edges, ownership/host edges, unresolved counts, reachability gaps, coverage warnings, rule-pack versions, and rule contribution/drop/conflict counts.
-2. Group gaps by stable evidence shape rather than business page name:
-   - unresolved reason;
-   - framework/package/base type/annotation;
-   - receiver and method call shape;
-   - route declaration or factory pattern;
-   - missing host, target, caller, projection, or uniqueness evidence.
-3. Prioritize repeated or high-impact clusters. Inspect at most five representative samples per cluster initially. Read additional source only when it changes the diagnosis.
-4. Classify each candidate using [references/audit-contract.md](references/audit-contract.md). Determine whether evidence is missing in Analyzer, rejected by Judge, lost during Lift, omitted from SPEC, missing a host, or indicates a false positive.
-5. Establish a positive example and a similar negative or ambiguous example before proposing a generic or framework rule. If the target is dynamic, reflective, or non-unique, record it as an accepted limitation instead of proposing an unsafe rule.
-6. Compare with a previous report for the same source project when available. Treat newly added pages/edges, disappearing pages/edges, changed direction, and changed ownership as accuracy signals; raw count growth is not automatically an improvement.
-7. Rank opportunities by impact, recurrence, evidence strength, generality, false-positive risk, and implementation cost. Keep at most 20 active opportunities.
-8. Write the two outputs defined below. Follow [references/recommendation-schema.md](references/recommendation-schema.md) exactly.
-
-## Outputs
-
-When analysis is missing or stale, return without creating or replacing opportunity reports:
-
-```json
-{
-  "status": "stale",
-  "workspace": "<android-project>-migration/.migration/",
-  "staleReasons": [],
-  "requiredAction": "reanalyze-android",
-  "expectedArtifacts": [
-    ".migration/spec/index.json",
-    ".migration/spec/facts/",
-    ".migration/appgraph/app-graph.json"
-  ]
-}
-```
-
-The caller consumes `requiredAction` and decides the workflow transition. This Skill does not invoke `droid2hmos analyze android`, pause for a user choice, or continue against legacy/stale artifacts.
-
-When inputs are fresh, create or replace:
-
-```text
-.migration/rule-audit/rule-opportunities.json
-.migration/rule-audit/rule-opportunities.md
-```
-
-The JSON must conform to `schemas/rule-opportunities.schema.json` in this Skill. The Markdown is the human review view of the same findings; it must not add claims absent from JSON.
-
-Each opportunity must include evidence refs with Android source file and line, the affected AppGraph/SPEC entities, current and expected behavior, proposed change layer, scope, confidence, generality, risk, and a concrete test plan. Separate observations from inferred root causes and label uncertain causes as hypotheses.
-
-When no evidence-backed rule improvement exists, write valid outputs with an empty `opportunities` array and explain the reviewed limitations. Do not invent work to avoid an empty report.
-
-## Boundaries
-
-- Do not modify immutable `.migration/spec/facts/` or `app-graph.json`.
-- Do not write a project screen name into a generic rule proposal.
-- Do not call a suffix match, route-string similarity, or nearest-name guess sufficient evidence.
-- Do not turn host relationships into navigation edges.
-- Do not mark multiple targets as resolved.
-- Do not implement recommendations. A maintainer may later pass an accepted opportunity to the separate `appgraph-navigation-rules` Skill.
-- With fresh inputs, an audit execution failure is advisory: record the limitation and return it to the caller. Missing or stale analysis is not an audit failure; return `requiredAction: reanalyze-android` as defined above.
-- Do not advance an outer state, create a checkpoint, update the migration report, or invoke completion. Return findings or the stale result to the caller.

package/skills/appgraph-rule-audit/references/audit-contract.md

@@ -1,47 +0,0 @@
-# Rule audit contract
-
-Use this reference to classify a finding and decide whether it is actionable.
-
-## Layers
-
-### analyzer-gap
-
-The Android source contains stable syntax or type evidence, but `ruleEngine.contributions` has no corresponding facts. A proposal must name the API identity and facts an Analyzer should emit. JSON5 Judge conditions cannot repair this gap.
-
-### judge-gap
-
-Required facts exist, but no rule confirms them or the contribution is dropped. Cite the existing fact paths, matching/drop result, and the smallest condition change. Preserve ambiguity.
-
-### lift-gap
-
-The contribution is confirmed, but the expected Screen/host/navigation node or edge is absent from AppGraph. Cite the matched rule and expected graph projection.
-
-### spec-gap
-
-The AppGraph node or edge exists with valid provenance, but SPEC facts omit or misclassify it. Cite both the AppGraph entity and missing SPEC representation.
-
-### host-gap
-
-A page is recognized but lacks a deterministic owner or upstream host. Propose a rule only when the host chain follows a stable framework API, factory, entry point, or unique call relationship. Never infer a host from proximity or a single Activity fallback.
-
-### false-positive
-
-A recognized page, host, or transition is a component, preview, test fixture, factory, helper, or unrelated call. Cite the matched rule and a structural discriminator that excludes the bad result without naming the product entity.
-
-### performance
-
-A rule or analyzer has observed pathological cost. Cite timings, affected stage, input shape, and a bounded alternative. Do not infer performance problems from project size alone.
-
-## Scope
-
-- `builtin-generic`: supported Android or Jetpack API with evidence across unrelated projects or authoritative framework structure.
-- `framework-pack`: stable third-party or private framework identity such as package, base type, annotation, receiver type, or route registry.
-- `project-pack`: valid behavior tied to one project's local abstraction without enough evidence for broader scope.
-
-## Evidence minimum
-
-Every opportunity needs one positive source example and its current generated result. A `builtin-generic` or `framework-pack` opportunity also needs a negative, boundary, or ambiguous example demonstrating how false matches will be prevented. Evidence includes project-relative file, line when available, symbol/call shape, related entity refs, and related rule IDs.
-
-## Accepted limitations
-
-Use an accepted limitation for reflection, runtime-generated destinations, remote configuration, unresolved dependency types, multiple valid targets, or missing source. Explain what evidence would be required to resolve it. Do not propose a low-confidence guessing rule.

package/skills/appgraph-rule-audit/references/recommendation-schema.md

@@ -1,41 +0,0 @@
-# Rule opportunity output
-
-Write JSON matching `schemas/rule-opportunities.schema.json` in this Skill and a concise Chinese Markdown rendering.
-
-## Top-level fields
-
-- `schemaVersion`: `1.0.0`.
-- `skillVersion`: `1.0.0`.
-- `source`: Android project identity, source revision, `factsSha256`, and observed AppGraph/rule-pack versions.
-- `summary`: reviewed counts and a short conclusion.
-- `opportunities`: at most 20 ranked candidates.
-- `acceptedLimitations`: evidence-backed gaps that should remain unresolved.
-- `auditWarnings`: stale, incomplete, or unavailable inputs that limit confidence.
-
-## Opportunity fields
-
-- `id`: stable lowercase ID derived from category, framework identity, and evidence shape; never use list position.
-- `priority`: `P0`, `P1`, or `P2`. Use P0 only for systemic false results or a blocker affecting a large part of the page/navigation graph.
-- `category`: one audit layer from the contract.
-- `scope`: `builtin-generic`, `framework-pack`, or `project-pack`.
-- `title`: concise problem statement.
-- `frameworkIdentity`: stable package/type/annotation/receiver/call identity.
-- `observation`: directly observed current result.
-- `rootCause`: diagnosis plus `certainty` of `confirmed` or `hypothesis`.
-- `expectedBehavior`: required page, host, edge, projection, exclusion, or performance behavior.
-- `affectedEntities`: page/edge/contribution refs.
-- `evidence`: source locations, generated refs, rule IDs, and the evidence role (`positive`, `negative`, `boundary`, `ambiguous`).
-- `proposal`: target layer, proposed rule shape, and files or rule IDs likely to change; no executable patch.
-- `confidence`, `generality`, `risk`: `high`, `medium`, or `low`, each with a reason.
-- `testPlan`: positive, negative, boundary, ambiguity, Lift/SPEC, and project baseline checks as applicable.
-- `expectedMetricDelta`: directional expectation for pages, navigation, hosts, unresolved, and false positives; use `unknown` when unsupported.
-- `status`: always `proposed` in this Skill.
-
-## Markdown order
-
-1. Input freshness and coverage summary.
-2. Ranked opportunities with evidence and tests.
-3. Accepted limitations.
-4. Audit warnings.
-
-Do not reproduce the full page inventory or migration report.

package/skills/appgraph-rule-audit/schemas/rule-opportunities.schema.json

@@ -1,125 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://harmonyos-ai.dev/skills/appgraph-rule-audit/schemas/rule-opportunities.schema.json",
-  "title": "AppGraph rule improvement opportunities",
-  "type": "object",
-  "required": ["schemaVersion", "skillVersion", "source", "summary", "opportunities", "acceptedLimitations", "auditWarnings"],
-  "properties": {
-    "schemaVersion": { "const": "1.0.0" },
-    "skillVersion": { "const": "1.0.0" },
-    "source": {
-      "type": "object",
-      "required": ["project", "sourceRevision", "factsSha256", "appGraphVersion", "rulePacks"],
-      "properties": {
-        "project": { "type": "string", "minLength": 1 },
-        "sourceRevision": { "type": ["string", "null"] },
-        "factsSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
-        "appGraphVersion": { "type": ["string", "null"] },
-        "rulePacks": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
-      },
-      "additionalProperties": false
-    },
-    "summary": {
-      "type": "object",
-      "required": ["conclusion", "pages", "navigation", "hosts", "unresolved", "coverageWarnings"],
-      "properties": {
-        "conclusion": { "type": "string" },
-        "pages": { "type": "integer", "minimum": 0 },
-        "navigation": { "type": "integer", "minimum": 0 },
-        "hosts": { "type": "integer", "minimum": 0 },
-        "unresolved": { "type": "integer", "minimum": 0 },
-        "coverageWarnings": { "type": "integer", "minimum": 0 }
-      },
-      "additionalProperties": false
-    },
-    "opportunities": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/opportunity" } },
-    "acceptedLimitations": { "type": "array", "items": { "$ref": "#/$defs/limitation" } },
-    "auditWarnings": { "type": "array", "items": { "type": "string", "minLength": 1 } }
-  },
-  "$defs": {
-    "level": { "enum": ["high", "medium", "low"] },
-    "evidence": {
-      "type": "object",
-      "required": ["role", "file", "line", "symbol", "entityRefs", "ruleIds", "observation"],
-      "properties": {
-        "role": { "enum": ["positive", "negative", "boundary", "ambiguous"] },
-        "file": { "type": "string", "minLength": 1 },
-        "line": { "type": ["integer", "null"], "minimum": 1 },
-        "symbol": { "type": ["string", "null"] },
-        "entityRefs": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
-        "ruleIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
-        "observation": { "type": "string", "minLength": 1 }
-      },
-      "additionalProperties": false
-    },
-    "ratedReason": {
-      "type": "object",
-      "required": ["level", "reason"],
-      "properties": { "level": { "$ref": "#/$defs/level" }, "reason": { "type": "string", "minLength": 1 } },
-      "additionalProperties": false
-    },
-    "metricDelta": {
-      "type": "object",
-      "required": ["pages", "navigation", "hosts", "unresolved", "falsePositives"],
-      "properties": {
-        "pages": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
-        "navigation": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
-        "hosts": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
-        "unresolved": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
-        "falsePositives": { "enum": ["increase", "decrease", "unchanged", "unknown"] }
-      },
-      "additionalProperties": false
-    },
-    "opportunity": {
-      "type": "object",
-      "required": ["id", "priority", "category", "scope", "title", "frameworkIdentity", "observation", "rootCause", "expectedBehavior", "affectedEntities", "evidence", "proposal", "confidence", "generality", "risk", "testPlan", "expectedMetricDelta", "status"],
-      "properties": {
-        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]+$" },
-        "priority": { "enum": ["P0", "P1", "P2"] },
-        "category": { "enum": ["analyzer-gap", "judge-gap", "lift-gap", "spec-gap", "host-gap", "false-positive", "performance"] },
-        "scope": { "enum": ["builtin-generic", "framework-pack", "project-pack"] },
-        "title": { "type": "string", "minLength": 1 },
-        "frameworkIdentity": { "type": "string", "minLength": 1 },
-        "observation": { "type": "string", "minLength": 1 },
-        "rootCause": {
-          "type": "object",
-          "required": ["certainty", "description"],
-          "properties": { "certainty": { "enum": ["confirmed", "hypothesis"] }, "description": { "type": "string", "minLength": 1 } },
-          "additionalProperties": false
-        },
-        "expectedBehavior": { "type": "string", "minLength": 1 },
-        "affectedEntities": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
-        "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/evidence" } },
-        "proposal": {
-          "type": "object",
-          "required": ["layer", "ruleShape", "likelyFilesOrRules"],
-          "properties": {
-            "layer": { "enum": ["Analyzer", "Judge", "Lift", "SPEC", "Host", "Performance"] },
-            "ruleShape": { "type": "string", "minLength": 1 },
-            "likelyFilesOrRules": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
-          },
-          "additionalProperties": false
-        },
-        "confidence": { "$ref": "#/$defs/ratedReason" },
-        "generality": { "$ref": "#/$defs/ratedReason" },
-        "risk": { "$ref": "#/$defs/ratedReason" },
-        "testPlan": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
-        "expectedMetricDelta": { "$ref": "#/$defs/metricDelta" },
-        "status": { "const": "proposed" }
-      },
-      "additionalProperties": false
-    },
-    "limitation": {
-      "type": "object",
-      "required": ["id", "reason", "evidence", "requiredEvidence"],
-      "properties": {
-        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]+$" },
-        "reason": { "type": "string", "minLength": 1 },
-        "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/evidence" } },
-        "requiredEvidence": { "type": "string", "minLength": 1 }
-      },
-      "additionalProperties": false
-    }
-  },
-  "additionalProperties": false
-}