@harmonyos-arkts/d2h 0.1.3 → 0.1.6

package/skills/d2h-utg-static-generate/tests/test_static.py

@@ -0,0 +1,335 @@
+import copy
+import importlib.util
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPT = Path(__file__).resolve().parents[1] / 'scripts' / 'generate.py'
+spec = importlib.util.spec_from_file_location('static_generate', SCRIPT)
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+
+class StaticTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name) / 'source'
+        self.root.mkdir()
+        (self.root / 'Screen.kt').write_text('fun home() {}\nfun detail() {}\nfun dialog() {}\n', encoding='utf-8')
+        self.ref = {'file': 'Screen.kt', 'line': 1}
+        self.graph = {'schemaVersion': 1, 'platform': 'android', 'app': {'name': 'Demo', 'packageName': 'demo'},
+            'nodes': [{'id': identity, 'kind': 'Screen', 'name': 'SameName', 'platform': 'android',
+                       'subtype': kind, 'platformRef': self.ref}
+                      for identity, kind in [('home', 'activity'), ('detail', 'compose'), ('dialog', 'dialog'), ('fragment', 'fragment')]],
+            'edges': [{'id': identity, 'kind': 'navigates_to', 'from': source, 'to': target,
+                       'attrs': {'evidence': [self.ref]}, 'confidence': 1}
+                      for identity, source, target in [('nav1', 'home', 'detail'), ('nav2', 'home', 'detail'),
+                                                        ('back', 'detail', 'home'), ('external', 'home', 'outside')]],
+            'entryPoints': [{'id': 'launch', 'kind': 'app-launch', 'sourceRef': 'home', 'resolution': 'resolved'},
+                            {'id': 'click', 'kind': 'ui-action', 'sourceRef': 'button', 'ownerRef': 'home', 'resolution': 'resolved'}],
+            'uiComponents': {'nodes': [{'id': 'button', 'kind': 'control', 'name': 'Button', 'evidence': [self.ref]}],
+                             'edges': [{'id': 'owns', 'kind': 'contains', 'from': 'home', 'to': 'button'}]},
+            'callTraces': [{'id': 'trace', 'entryPointId': 'click', 'effects': [
+                {'id': 'effect', 'kind': 'navigation', 'targetRefs': ['dialog'], 'origin': self.ref}]}]}
+        self.base = module.project(self.graph, self.root)
+        self.fingerprint = module.digest({'appgraph': self.graph, 'source': module.source_digest(self.root)})
+
+    def discoveries(self, operations=None):
+        return {'schema_version': 'd2h-utg-discoveries/v1', 'input_fingerprint': self.fingerprint,
+                'operations': operations or [], 'unresolved': []}
+
+    def operation(self, kind, op, identity, value=None):
+        return {'kind': kind, 'op': op, 'id': identity, 'reason': 'source verified',
+                'evidence': 'Screen.kt:1', 'value': value}
+
+    def test_projection(self):
+        self.assertEqual(len(self.base['nodes']), 4)
+        self.assertEqual(len(self.base['edges']), 4)
+        self.assertEqual(self.base['graph']['root'], 'home')
+        home = next(n for n in self.base['nodes'] if n['id'] == 'home')
+        self.assertEqual(home['widgets'][0]['id'], 'button')
+        self.assertTrue(any(x['subject'] == 'external' for x in self.base['unresolved']))
+
+    def test_source_page_coalesces_manifest_and_synthetic_compose_screen(self):
+        graph = {'schemaVersion': 1, 'platform': 'android', 'app': {'name': 'Demo'},
+            'nodes': [
+                {'id': 'manifest', 'kind': 'Screen', 'name': 'MainActivity', 'subtype': 'activity',
+                 'platformRef': {'file': 'missing.xml', 'symbol': '.MainActivity'}},
+                {'id': 'entry', 'kind': 'AppEntry', 'subtype': 'launcher-activity',
+                 'attrs': {'screen': 'manifest'}},
+                {'id': 'route', 'kind': 'Screen', 'name': 'SplashRoute', 'subtype': 'compose',
+                 'matchKey': 'screen:splashroute', 'platformRef': {'file': 'Screen.kt'}},
+                {'id': 'synthetic', 'kind': 'Screen', 'name': 'SplashRoute', 'subtype': 'compose',
+                 'matchKey': 'screen:splashroute:compose', 'platformRef': self.ref,
+                 'attrs': {'classificationRule': 'compose.destination.register'}}],
+            'uiComponents': {'nodes': [
+                {'id': 'activity-page', 'kind': 'page', 'name': 'MainActivity', 'subtype': 'activity',
+                 'evidence': [self.ref], 'attrs': {'screenId': 'manifest'}},
+                {'id': 'route-page', 'kind': 'page', 'name': 'SplashRoute', 'subtype': 'compose',
+                 'evidence': [self.ref], 'attrs': {'screenId': 'route',
+                     'screenMatchKey': 'screen:splashroute', 'classificationRule': 'COMPOSE-SCREEN-AST'}}],
+                'edges': []}, 'edges': [{'id': 'nav', 'kind': 'navigates_to',
+                    'from': 'manifest', 'to': 'synthetic', 'attrs': {'evidence': [self.ref]}}],
+            'entryPoints': [], 'callTraces': []}
+        base = module.project(graph, self.root)
+        self.assertEqual({n['id'] for n in base['nodes']}, {'activity-page', 'route-page'})
+        self.assertEqual(base['graph']['root'], 'activity-page')
+        self.assertEqual([(e['source'], e['target']) for e in base['edges']],
+                         [('activity-page', 'route-page')])
+
+    def test_interaction_projection_preserves_stable_ids_and_alignment(self):
+        self.graph['interactionGraph'] = {'schemaVersion': 1,
+            'surfaces': [{'id': identity, 'name': identity, 'kind': kind, 'sourceRefs': [identity, 'ui:' + identity],
+                          'hostSurfaceIds': [], 'evidence': [self.ref], 'presentation': 'screen'}
+                         for identity, kind in [('home', 'activity'), ('detail', 'compose')]],
+            'controlBindings': [{'id': 'binding:button:home', 'controlRef': 'button', 'surfaceId': 'home',
+                                 'evidence': [self.ref], 'selectorCandidates': []}],
+            'entries': [{'id': 'launch', 'kind': 'app-launch', 'surfaceIds': ['home'], 'resolution': 'resolved'}],
+            'transitions': [{'id': 'transition:stable', 'sourceSurfaceId': 'home',
+                             'target': {'kind': 'internal', 'surfaceId': 'detail'}, 'operation': 'navigate',
+                             'resolution': 'resolved', 'evidence': [self.ref], 'supportingRefs': ['edge', 'trace', 'effect'],
+                             'actionRef': 'click', 'conditions': []}], 'unresolved': []}
+        base = module.project(self.graph, self.root)
+        self.assertEqual(len(base['edges']), 1)  # Legacy edges must not be appended a second time.
+        self.assertEqual(base['graph']['root'], 'home')
+        self.assertEqual(base['alignment']['edges'][0]['source_refs'], ['edge', 'trace', 'effect'])
+        self.assertEqual(base['nodes'][1]['extra']['source_refs'], ['home', 'ui:home'])
+        utg, _, _ = module.normalize_facts(base, self.root)
+        self.assertEqual(utg['links'][0]['id'], 'transition:stable')
+        self.assertEqual(utg['links'][0]['status'], 'static-only')
+        self.graph['interactionGraph']['transitions'][0]['conditions'] = [
+            {'expression': 'loggedIn', 'branch': 'else', 'group': 'login'}]
+        guarded = module.project(self.graph, self.root)
+        self.assertEqual(guarded['edges'][0]['guard']['text'], '!(loggedIn)')
+        self.assertEqual(guarded['edges'][0]['guard']['conditions'][0]['branch'], 'else')
+        self.graph['interactionGraph']['transitions'][0]['conditions'] = []
+        from build_page_json import build_page_plan
+        plan = build_page_plan(utg, module.build_click_paths(utg), utg_path='utg.json', click_paths_path='click_paths.json')
+        self.assertFalse(any(p['capture'] for p in plan['pages']))
+        # Multiple declared launch pages use a non-capturable logical boundary.
+        self.graph['interactionGraph']['entries'].append({'id': 'second-launch', 'kind': 'app-launch',
+            'surfaceIds': ['detail'], 'resolution': 'resolved', 'launch': {'action': 'start-activity', 'component': 'demo/demo.DetailActivity'}})
+        base = module.project(self.graph, self.root)
+        self.assertEqual(base['graph']['root'], 'utg:entry-root')
+        detail = next(n for n in base['nodes'] if n['id'] == 'detail')
+        detail['expected'] = {'text_any': ['Detail']}
+        utg, _, _ = module.normalize_facts(base, self.root)
+        paths = module.build_click_paths(utg)
+        plan = build_page_plan(utg, paths, utg_path='utg.json', click_paths_path='click_paths.json')
+        self.assertFalse(next(p for p in plan['pages'] if p['node_id'] == 'utg:entry-root')['capture'])
+        page = next(p for p in plan['pages'] if p['node_id'] == 'detail')
+        self.assertTrue(page['capture'])
+        self.assertEqual(page['steps'][-1]['component'], 'demo/demo.DetailActivity')
+        self.graph['interactionGraph']['entries'][-1].pop('launch')
+        utg, _, _ = module.normalize_facts(module.project(self.graph, self.root), self.root)
+        plan = build_page_plan(utg, module.build_click_paths(utg), utg_path='utg.json', click_paths_path='click_paths.json')
+        self.assertFalse(next(p for p in plan['pages'] if p['node_id'] == 'detail')['capture'])
+        self.graph['interactionGraph']['entries'][-1].update(kind='deep-link', launch={'action': 'deep-link', 'uri': 'demo://app/detail'})
+        base = module.project(self.graph, self.root)
+        next(n for n in base['nodes'] if n['id'] == 'detail')['expected'] = {'text_any': ['Detail']}
+        # Retain every source-proven edge: the executable entry must win over
+        # the ordinary navigation whose control lacks a replay selector.
+        self.assertTrue(any(e['id'] == 'transition:stable' for e in base['edges']))
+        utg, _, _ = module.normalize_facts(base, self.root)
+        plan = build_page_plan(utg, module.build_click_paths(utg), utg_path='utg.json', click_paths_path='click_paths.json')
+        page = next(p for p in plan['pages'] if p['node_id'] == 'detail')
+        self.assertTrue(page['capture'])
+        self.assertEqual(page['steps'][-1]['action'], 'deep-link')
+        self.assertEqual(page['steps'][-1]['label'], 'demo://app/detail')
+
+    def test_source_selector_candidates_do_not_guess_test_tag_resource_ids(self):
+        self.graph['interactionGraph'] = {'schemaVersion': 1,
+            'surfaces': [{'id': identity, 'name': identity, 'kind': kind, 'sourceRefs': [identity],
+                          'hostSurfaceIds': [], 'evidence': [self.ref], 'presentation': 'screen'}
+                         for identity, kind in [('home', 'activity'), ('detail', 'compose')]],
+            'controlBindings': [{'id': 'binding', 'controlRef': 'button', 'surfaceId': 'home',
+                                 'evidence': [self.ref], 'selectorCandidates': []}],
+            'entries': [{'id': 'launch', 'kind': 'app-launch', 'surfaceIds': ['home'], 'resolution': 'resolved'},
+                        {'id': 'click', 'kind': 'ui-action', 'sourceRef': 'button', 'surfaceIds': ['home'],
+                         'event': 'onClick', 'resolution': 'resolved'}],
+            'transitions': [{'id': 'navigate', 'sourceSurfaceId': 'home', 'actionRef': 'click',
+                             'target': {'kind': 'internal', 'surfaceId': 'detail'}, 'operation': 'navigate',
+                             'resolution': 'resolved', 'evidence': [self.ref], 'supportingRefs': ['click']}],
+            'unresolved': []}
+        binding = self.graph['interactionGraph']['controlBindings'][0]
+        from build_page_json import build_page_plan
+        for kind, ready in [('resource-id', True), ('test-tag', False)]:
+            binding['selectorCandidates'] = [{'kind': kind, 'value': 'demo:id/open', 'evidence': [self.ref]}]
+            base = module.project(self.graph, self.root)
+            next(node for node in base['nodes'] if node['id'] == 'detail')['expected'] = {'text_any': ['Detail']}
+            utg, _, _ = module.normalize_facts(base, self.root)
+            page = next(page for page in build_page_plan(utg, module.build_click_paths(utg),
+                utg_path='utg.json', click_paths_path='click_paths.json')['pages'] if page['node_id'] == 'detail')
+            self.assertEqual(page['capture'], ready)
+            if ready:
+                self.assertEqual(page['steps'][-1]['selector'], {'resource_id': 'demo:id/open'})
+            else:
+                self.assertNotIn('selector', page['steps'][-1])
+
+    def test_sheet_projection_and_external_entry_operand_boundary(self):
+        self.graph['interactionGraph'] = {'schemaVersion': 1,
+            'surfaces': [{'id': 'home', 'name': 'Home', 'kind': 'activity', 'sourceRefs': ['home'],
+                          'hostSurfaceIds': [], 'evidence': [self.ref], 'presentation': 'screen'},
+                         {'id': 'sheet', 'name': 'Sheet', 'kind': 'bottom-sheet', 'sourceRefs': ['sheet'],
+                          'hostSurfaceIds': ['home'], 'evidence': [self.ref], 'presentation': 'overlay'}],
+            'controlBindings': [],
+            'entries': [{'id': 'launch', 'kind': 'app-launch', 'surfaceIds': ['home'], 'resolution': 'resolved',
+                         'launch': {'action': 'start-activity', 'component': 'demo/demo.Home'}},
+                        {'id': 'share', 'kind': 'external-entry', 'surfaceIds': ['sheet'],
+                         'resolution': 'resolved', 'evidence': [self.ref]}],
+            'transitions': [{'id': 'show-sheet', 'sourceSurfaceId': 'home',
+                             'target': {'kind': 'internal', 'surfaceId': 'sheet'}, 'operation': 'show',
+                             'resolution': 'resolved', 'evidence': [self.ref], 'supportingRefs': ['trigger']}],
+            'unresolved': []}
+        base = module.project(self.graph, self.root)
+        sheet = next(node for node in base['nodes'] if node['id'] == 'sheet')
+        self.assertEqual(sheet['kind'], 'sheet')
+        self.assertEqual(sheet['extra']['host_surface_ids'], ['home'])
+        self.assertTrue(any(issue['subject'] == 'share' and 'operands' in issue['reason'] for issue in base['unresolved']))
+        sheet['expected'] = {'text_any': ['Sheet']}
+        utg, _, _ = module.normalize_facts(base, self.root)
+        from build_page_json import build_page_plan
+        plan = build_page_plan(utg, module.build_click_paths(utg), utg_path='utg.json', click_paths_path='click_paths.json')
+        self.assertFalse(next(page for page in plan['pages'] if page['node_id'] == 'sheet')['capture'])
+        self.assertTrue(any(edge['id'] == 'show-sheet' for edge in utg['links']))
+
+    def test_manifest_exact_declaration_and_entry(self):
+        (self.root / 'AndroidManifest.xml').write_text(
+            '<manifest xmlns:android="http://schemas.android.com/apk/res/android">\n'
+            '<application><activity android:name=".MainActivity"/></application>\n</manifest>', encoding='utf-8')
+        self.graph['nodes'][0]['platformRef'] = {'file': 'AndroidManifest.xml', 'symbol': '.MainActivity'}
+        self.graph['nodes'].append({'id': 'manifest-entry', 'kind': 'AppEntry',
+                                    'subtype': 'launcher-activity', 'attrs': {'screen': 'home'}})
+        self.graph['entryPoints'] = []
+        self.graph['edges'][0]['attrs']['evidence'] = self.ref  # Actual producer also emits a single ref.
+        base = module.project(self.graph, self.root)
+        self.assertEqual(base['graph']['root'], 'home')
+        self.assertEqual(next(n for n in base['nodes'] if n['id'] == 'home')['declared_at'], 'AndroidManifest.xml:2')
+
+    def test_ai_edge_guard_and_capture_readiness(self):
+        node = copy.deepcopy(next(n for n in self.base['nodes'] if n['id'] == 'fragment'))
+        node['expected'] = {'text_any': ['Fragment']}
+        edge = {'id': 'ai:fragment', 'source': 'home', 'target': 'fragment',
+                'mechanism': 'fragment-transaction', 'trigger': 'Screen.kt:1', 'confidence': 0.9,
+                'guard': {'kind': 'login', 'text': 'requires login'},
+                'args': {'action': 'tap', 'selector': {'text': 'Fragment'}}}
+        merged = module.apply_discoveries(self.base, self.discoveries([
+            self.operation('node', 'replace', 'fragment', node),
+            self.operation('edge', 'add', 'ai:fragment', edge)]), self.root, self.fingerprint)
+        utg, _, _ = module.normalize_facts(merged, self.root)
+        paths = module.build_click_paths(utg)
+        from build_page_json import build_page_plan
+        plan = build_page_plan(utg, paths, utg_path='utg.json', click_paths_path='click_paths.json')
+        page = next(n for n in plan['pages'] if n['node_id'] == 'fragment')
+        self.assertTrue(page['capture'])
+        self.assertEqual(page['steps'][-1]['guard']['kind'], 'login')
+        next(e for e in merged['edges'] if e['id'] == 'ai:fragment')['args'] = {'nl_hint': 'click Fragment'}
+        utg, _, _ = module.normalize_facts(merged, self.root)
+        plan = build_page_plan(utg, module.build_click_paths(utg), utg_path='utg.json', click_paths_path='click_paths.json')
+        self.assertFalse(next(n for n in plan['pages'] if n['node_id'] == 'fragment')['capture'])
+
+    def test_add_replace_exclude_audit(self):
+        node = copy.deepcopy(self.base['nodes'][0])
+        node.update(id='ai:new', label='New')
+        detail = copy.deepcopy(next(n for n in self.base['nodes'] if n['id'] == 'detail'))
+        detail['expected'] = {'text_any': ['Details']}
+        operations = [self.operation('node', 'add', 'ai:new', node),
+                      self.operation('node', 'replace', 'detail', detail),
+                      self.operation('edge', 'exclude', 'nav2')]
+        merged = module.apply_discoveries(self.base, self.discoveries(operations), self.root, self.fingerprint)
+        self.assertEqual(len(merged['graph']['discovery_audit']), 3)
+        self.assertEqual(len(self.base['edges']), 4)
+        self.assertEqual(next(n for n in merged['nodes'] if n['id'] == 'detail')['provenance'], 'ai-source-review')
+
+    def test_source_review_cannot_claim_runtime_verification(self):
+        node = copy.deepcopy(next(n for n in self.base['nodes'] if n['id'] == 'detail'))
+        node.update(status='runtime-verified', reached=True, screenshot='fake.png')
+        edge = copy.deepcopy(next(e for e in self.base['edges'] if e['id'] == 'nav2'))
+        edge.update(status='runtime-verified', reached=True)
+        merged = module.apply_discoveries(self.base, self.discoveries([
+            self.operation('node', 'replace', 'detail', node),
+            self.operation('edge', 'replace', 'nav2', edge)]), self.root, self.fingerprint)
+        utg, _, _ = module.normalize_facts(merged, self.root)
+        reviewed = [next(n for n in utg['nodes'] if n['id'] == 'detail'),
+                    next(e for e in utg['links'] if e['id'] == 'nav2')]
+        for item in reviewed:
+            self.assertEqual(item['status'], 'static-only')
+            self.assertEqual(item['provenance'], 'ai-source-review')
+            self.assertNotIn('reached', item)
+            self.assertNotIn('screenshot', item)
+        self.assertEqual(next(n for n in self.base['nodes'] if n['id'] == 'detail')['status'], 'static-only')
+
+    def test_resolved_findings_preserve_audit(self):
+        discoveries = self.discoveries()
+        discoveries['resolved_findings'] = [{'id': self.base['unresolved'][0]['id'],
+                                            'reason': 'verified boundary', 'evidence': 'Screen.kt:1'}]
+        merged = module.apply_discoveries(self.base, discoveries, self.root, self.fingerprint)
+        self.assertEqual(len(merged['unresolved']), len(self.base['unresolved']) - 1)
+        self.assertEqual(merged['graph']['resolved_findings'], discoveries['resolved_findings'])
+        discoveries['resolved_findings'][0]['id'] = 'unknown'
+        with self.assertRaises(module.UtgError):
+            module.apply_discoveries(self.base, discoveries, self.root, self.fingerprint)
+
+    def test_reject_invalid_stale_duplicate_and_dangling(self):
+        bad = self.discoveries()
+        bad['input_fingerprint'] = 'old'
+        with self.assertRaises(module.UtgError):
+            module.apply_discoveries(self.base, bad, self.root, self.fingerprint)
+        for operations in [[self.operation('node', 'exclude', 'home')],
+                           [self.operation('edge', 'exclude', 'nav1')] * 2,
+                           [self.operation('node', 'add', 'home', self.base['nodes'][0])]]:
+            with self.assertRaises(module.UtgError):
+                module.apply_discoveries(self.base, self.discoveries(operations), self.root, self.fingerprint)
+        op = self.operation('edge', 'exclude', 'nav1')
+        op['evidence'] = 'Screen.kt:99'
+        with self.assertRaises(module.UtgError):
+            module.apply_discoveries(self.base, self.discoveries([op]), self.root, self.fingerprint)
+        old = module.source_digest(self.root)
+        (self.root / 'Screen.kt').write_text('changed\n')
+        self.assertNotEqual(old, module.source_digest(self.root))
+
+    def test_ambiguous_root_not_guessed(self):
+        self.graph['entryPoints'].append({'id': 'launch2', 'kind': 'app-launch', 'sourceRef': 'detail', 'resolution': 'resolved'})
+        self.assertEqual(module.project(self.graph, self.root)['graph']['root'], '')
+
+    def test_end_to_end_determinism_offline_and_readonly(self):
+        graph_path = Path(self.temp.name) / 'graph.json'
+        graph_path.write_text(json.dumps(self.graph), encoding='utf-8')
+        original = graph_path.read_bytes()
+        ws = Path(self.temp.name) / 'utg'
+        command = [sys.executable, str(SCRIPT), '--project-root', str(self.root), '--appgraph', str(graph_path), '--workspace', str(ws)]
+        subprocess.run(command, check=True, capture_output=True)
+        review = json.loads((ws / 'review-worklist.json').read_text(encoding='utf-8'))
+        self.assertEqual(review['navigation_review']['status'], 'pending')
+        self.assertEqual(review['navigation_review']['total_findings'], 1)
+        self.assertEqual(len(review['navigation_candidates']), 4)
+        outputs = ['utg.json', 'click_paths.json', 'page.json', 'utg.html']
+        before = {n: (ws / n).read_bytes() for n in outputs}
+        subprocess.run(command + ['--force'], check=True, capture_output=True)
+        self.assertEqual(before, {n: (ws / n).read_bytes() for n in outputs})
+        self.assertEqual(graph_path.read_bytes(), original)
+        plan = json.loads((ws / 'page.json').read_text())
+        self.assertFalse(any(n['capture'] for n in plan['pages']))
+        html = (ws / 'utg.html').read_text(encoding='utf-8')
+        self.assertNotIn('<script src=', html)
+        self.assertIn('source-filter', html)
+        for i, script in enumerate(re.findall(r'<script>(.*?)</script>', html, re.S)):
+            js = Path(self.temp.name) / f'html-{i}.js'
+            js.write_text(script, encoding='utf-8')
+            result = subprocess.run(['node', '--check', str(js)], capture_output=True, text=True)
+            self.assertEqual(result.returncode, 0, result.stderr)
+        # The existing TS consumer validates this static plan without ADB.
+        result = subprocess.run(['node', str(module.SHARED / 'capture_from_page_json.ts'),
+            '--page-json', str(ws / 'page.json'), '--output-workspace', str(ws / 'captures'), '--dry-run'],
+            capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertFalse((ws / 'captures').exists())
+
+
+if __name__ == '__main__':
+    unittest.main()

package/skills/d2h-utg-static-generate/tests/verify-offline-html.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Exercise a generated offline UTG in a local Chromium browser; no devices."""
+import argparse
+import json
+from pathlib import Path
+import re
+import subprocess
+import tempfile
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--html', required=True, type=Path)
+    parser.add_argument('--browser', required=True, type=Path)
+    args = parser.parse_args()
+    original = args.html.read_bytes()
+    html = original.decode('utf-8')
+    # Add a test-only self-edge to the in-memory visualization, leaving facts intact.
+    html = html.replace('const REVIEW =', "GRAPH.links.push({...GRAPH.links[0], id:'visual-self-loop', source:GRAPH.nodes[1].id, target:GRAPH.nodes[1].id});\nconst REVIEW =", 1)
+    probe = r"""<script>
+setTimeout(() => {
+  const checks = {};
+  const links = [...document.querySelectorAll('path.link')];
+  checks.distinctPaths = links.length > 1 && new Set(links.map(link => link.getAttribute('d'))).size === links.length;
+  checks.selfLoop = links.some(link => link.getAttribute('d').includes(' C'));
+  checks.logicalEntry = document.getElementById('legend-items').textContent.includes('逻辑入口');
+  document.querySelector('path.link-hit').dispatchEvent(new MouseEvent('click', {bubbles:true}));
+  checks.edgeDetail = document.getElementById('detail-content').style.display !== 'none';
+  checks.edgeEvidence = document.getElementById('detail-content').textContent.includes('appgraph');
+  const filter = document.getElementById('source-filter');
+  for (const source of ['ai-source-review', 'appgraph']) {
+    filter.value = source; filter.dispatchEvent(new Event('change'));
+    checks[source] = [...document.querySelectorAll('g.node')].every(node =>
+      (node.style.display !== 'none') === (node.__data__.provenance === source));
+  }
+  const result = document.createElement('pre'); result.id='utg-qa-result'; result.textContent=JSON.stringify(checks); document.body.appendChild(result);
+}, 1500);
+</script>"""
+    html = html.replace('</body>', probe + '</body>', 1)
+    with tempfile.TemporaryDirectory(prefix='d2h-offline-html-') as directory:
+        folder = Path(directory).resolve()
+        test_html = folder / 'utg.html'
+        test_html.write_text(html, encoding='utf-8')
+        result = subprocess.run([str(args.browser.resolve()), '--headless', '--disable-gpu',
+            '--no-first-run', '--no-default-browser-check', '--disable-background-networking',
+            '--disable-component-update', '--disable-extensions', '--proxy-server=127.0.0.1:9',
+            f'--user-data-dir={folder / "profile"}', '--virtual-time-budget=2500',
+            '--dump-dom', test_html.as_uri()], capture_output=True, timeout=45, check=True)
+        match = re.search(r'<pre id="utg-qa-result">(.*?)</pre>', result.stdout.decode('utf-8', errors='replace'))
+        if not match:
+            raise AssertionError('Offline renderer or browser probe did not execute')
+        checks = json.loads(match.group(1))
+        if not all(checks.values()):
+            raise AssertionError(checks)
+    assert args.html.read_bytes() == original, 'Browser verification must not alter the input HTML'
+    print(json.dumps({'status': 'passed', 'checks': checks}, ensure_ascii=False))
+
+
+if __name__ == '__main__':
+    main()

package/skills/d2h-utg-static-generate/tests/verify-produced-fixture.py

@@ -0,0 +1,131 @@
+"""Explicit local AppGraph CLI -> UTG integration; never clones or updates repositories."""
+import argparse
+import hashlib
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def sha(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--appgraph-repo', required=True, type=Path)
+    args = parser.parse_args()
+    repo = args.appgraph_repo.resolve()
+    cli = repo / 'dist/appgraph/cli.js'
+    fixture = repo / '__tests__/appgraph/interaction-fixtures'
+    if not cli.is_file() or not fixture.is_dir():
+        raise RuntimeError('explicit AppGraph checkout must be built and contain the alignment fixture')
+    commit = subprocess.check_output(['git', '-C', str(repo), 'rev-parse', 'HEAD'], text=True).strip()
+    generate = Path(__file__).resolve().parents[1] / 'scripts/generate.py'
+    with tempfile.TemporaryDirectory(prefix='d2h-produced-fixture-') as temporary:
+        folder = Path(temporary)
+        source = folder / 'interaction-fixtures'
+        shutil.copytree(fixture, source, ignore=shutil.ignore_patterns('.codegraph*', '.migration', '.appgraph', 'build'))
+        source_files = [p for p in source.rglob('*') if p.is_file()]
+        source_before = {str(p.relative_to(source)): sha(p) for p in source_files}
+        graph_file = folder / 'app-graph.json'
+        workspace = folder / 'utg'
+        build = ['node', str(cli), 'build', str(source), '--platform', 'android', '--out', str(graph_file)]
+        subprocess.run(build, cwd=repo, check=True, capture_output=True)
+        graph_before = sha(graph_file)
+        graph = json.loads(graph_file.read_text(encoding='utf-8'))
+        interaction = graph['interactionGraph']
+        assert len(interaction['surfaces']) == 4, 'coarse/fine Activity and Compose identities must align'
+        navigation = [t for t in interaction['transitions'] if t['operation'] == 'navigate' and t['resolution'] == 'resolved']
+        assert len(navigation) == 2, 'two controls must retain two transitions without duplicate trace edges'
+        assert len({t['actionRef'] for t in navigation}) == 2
+        assert any(t['operation'] == 'back' and t['target']['kind'] == 'back' for t in interaction['transitions'])
+        assert any(t['operation'] == 'navhost-start' for t in interaction['transitions'])
+        command = [sys.executable, str(generate), '--project-root', str(source), '--appgraph', str(graph_file), '--workspace', str(workspace)]
+        subprocess.run(command, check=True, capture_output=True)
+        outputs = {p.name: sha(p) for p in workspace.iterdir() if p.is_file()}
+        subprocess.run(command + ['--force'], check=True, capture_output=True)
+        assert outputs == {p.name: sha(p) for p in workspace.iterdir() if p.is_file()}, 'derived outputs must be byte deterministic'
+        assert sha(graph_file) == graph_before, 'UTG must not modify AppGraph input'
+        assert source_before == {str(p.relative_to(source)): sha(p) for p in source_files}, 'source files must remain unchanged'
+        utg = json.loads((workspace / 'utg.json').read_text(encoding='utf-8'))
+        plan = json.loads((workspace / 'page.json').read_text(encoding='utf-8'))
+        assert utg['graph']['root'] == 'utg:entry-root'
+        assert len(utg['nodes']) == 5 and len(utg['links']) == 5
+        assert all(link.get('id') and link['status'] == 'static-only' for link in utg['links'])
+        assert plan['summary']['capture_planned'] == 0, 'missing arrival/selectors cannot become executable'
+        capture = generate.parents[2] / 'd2h-utg-ai-generate/scripts/capture_from_page_json.ts'
+        dry_run = subprocess.run(['node', str(capture), '--page-json', str(workspace / 'page.json'),
+                                  '--output-workspace', str(folder / 'captures'), '--dry-run'],
+                                 check=True, capture_output=True, text=True)
+        assert not (folder / 'captures').exists(), 'dry-run must not create runtime artifacts'
+        preview = json.loads(dry_run.stdout)
+        assert preview['selected_count'] == 0 and preview['nodes'] == [], 'capture CLI must agree on the non-executable plan'
+        assert 'boundary_transitions' in (workspace / 'utg.html').read_text(encoding='utf-8')
+        subprocess.run(build, cwd=repo, check=True, capture_output=True)
+        assert sha(graph_file) == graph_before, 'AppGraph repeated analysis must be deterministic'
+        # Coordinate-only edits must not change the interaction identity sets.
+        main_source = source / 'app/src/main/java/fixture/alignment/MainActivity.kt'
+        main_source.write_text('\n\n' + main_source.read_text(encoding='utf-8'), encoding='utf-8')
+        subprocess.run(build, cwd=repo, check=True, capture_output=True)
+        moved = json.loads(graph_file.read_text(encoding='utf-8'))['interactionGraph']
+        for collection in ('surfaces', 'controlBindings', 'entries', 'transitions'):
+            assert {o['id'] for o in interaction[collection]} == {o['id'] for o in moved[collection]}, json.dumps({
+                'collection': collection, 'before': interaction[collection], 'after': moved[collection],
+                'original_screens': [(n['id'], n.get('attrs')) for n in graph['nodes'] if n['kind'] == 'Screen'],
+                'changed_screens': [(n['id'], n.get('attrs')) for n in json.loads(graph_file.read_text(encoding='utf-8'))['nodes'] if n['kind'] == 'Screen'],
+            })
+
+        # Prove AST branch facts survive rule execution, lifting and the UTG consumer.
+        guarded_source = main_source.read_text(encoding='utf-8').replace(
+            'onClick = { nav.navigate("details") }', 'onClick = { if (allowed) nav.navigate("details") }', 1)
+        main_source.write_text(guarded_source, encoding='utf-8')
+        subprocess.run(build, cwd=repo, check=True, capture_output=True)
+        guarded_graph = json.loads(graph_file.read_text(encoding='utf-8'))['interactionGraph']
+        guarded_navigation = [t for t in guarded_graph['transitions']
+                              if t['operation'] == 'navigate' and t['resolution'] == 'resolved']
+        assert len(guarded_navigation) == 2, 'guard reconciliation cannot duplicate or erase navigation facts'
+        assert any(t['conditions'] and t['conditions'][0]['expression'] == 'allowed' for t in guarded_navigation)
+        guarded_workspace = folder / 'utg-guarded'
+        guarded_command = [sys.executable, str(generate), '--project-root', str(source), '--appgraph', str(graph_file), '--workspace', str(guarded_workspace)]
+        subprocess.run(guarded_command, check=True, capture_output=True)
+        guarded_utg = json.loads((guarded_workspace / 'utg.json').read_text(encoding='utf-8'))
+        assert any(link.get('guard', {}).get('text') == '(allowed)' for link in guarded_utg['links'] if link.get('guard'))
+
+        # Source-derived overlay facts must become actual interaction and UTG edges.
+        overlay_source = guarded_source.replace('import androidx.compose.material3.Button',
+            'import androidx.compose.material3.Button\nimport androidx.compose.material3.AlertDialog\nimport androidx.compose.material3.ModalBottomSheet')
+        overlay_source = overlay_source.replace('@Composable fun HomePage(nav: NavController) {',
+            '@Composable fun HomePage(nav: NavController) {\n'
+            '  Button(onClick = { if (allowed) uiState = uiState.copy(showDialog = true) }) {}\n'
+            '  Button(onClick = { uiState = uiState.copy(showSheet = true) }) {}\n'
+            '  if (uiState.showDialog) ConfirmDialog()\n'
+            '  if (uiState.showSheet) DetailsBottomSheet()')
+        overlay_source += '\n@Composable fun ConfirmDialog() { AlertDialog(onDismissRequest = {}, confirmButton = {}) }\n'
+        overlay_source += '@Composable fun DetailsBottomSheet() { ModalBottomSheet(onDismissRequest = {}) {} }\n'
+        main_source.write_text(overlay_source, encoding='utf-8')
+        subprocess.run(build, cwd=repo, check=True, capture_output=True)
+        overlay_graph = json.loads(graph_file.read_text(encoding='utf-8'))['interactionGraph']
+        shown = [t for t in overlay_graph['transitions'] if t['operation'] == 'show' and t['resolution'] == 'resolved']
+        overlay_kinds = {surface['id']: surface['kind'] for surface in overlay_graph['surfaces']}
+        assert {'dialog', 'bottom-sheet'} <= {overlay_kinds[t['target']['surfaceId']] for t in shown}
+        assert any(t['conditions'] and t['conditions'][0]['expression'] == 'allowed' for t in shown)
+        overlay_workspace = folder / 'utg-overlays'
+        subprocess.run([sys.executable, str(generate), '--project-root', str(source), '--appgraph', str(graph_file),
+                        '--workspace', str(overlay_workspace)], check=True, capture_output=True)
+        overlay_utg = json.loads((overlay_workspace / 'utg.json').read_text(encoding='utf-8'))
+        assert {t['id'] for t in shown} <= {link['id'] for link in overlay_utg['links']}
+        main_source.write_text('\n\n' + overlay_source, encoding='utf-8')
+        subprocess.run(build, cwd=repo, check=True, capture_output=True)
+        moved_overlays = json.loads(graph_file.read_text(encoding='utf-8'))['interactionGraph']
+        for collection in ('surfaces', 'controlBindings', 'entries', 'transitions'):
+            assert {fact['id'] for fact in overlay_graph[collection]} == {fact['id'] for fact in moved_overlays[collection]}, collection + ' overlay coordinate stability'
+        print(json.dumps({'status': 'passed', 'appgraph_commit': commit, 'appgraph_input_sha256': graph_before,
+                          'surfaces': 4, 'parallel_navigation': 2, 'utg_nodes': 5, 'utg_edges': 5,
+                          'deterministic': True, 'readonly': True, 'coordinate_stability': True, 'guarded_navigation': True, 'overlay_projection': True}))
+
+
+if __name__ == '__main__':
+    main()

package/skills/harmonyos-migration-playbook/references/ui-automation.md

@@ -13,13 +13,12 @@ Use device automation as evidence, not as a substitute for understanding the UI.
 Use the managed evidence commands for collection and packaging:
 
 ```text
-droid2hmos evidence capture <android|harmony> <android-project> --name <name> [--target <id>]
-droid2hmos evidence flow android <android-project> --name <name> [--task <task>]
+droid2hmos evidence capture harmony <android-project> --name <name> [--target <id>]
 droid2hmos evidence flow harmony <android-project> --name <name> (--class <class> [--case <case>] | --all)
 droid2hmos evidence compare <android-project> --name <name> --android <android-evidence-dir> --harmony <harmony-evidence-dir>
 ```
 
-`capture` collects the screenshot, UI tree/`dumpLayout`, and device logs. `flow` creates before/after captures around a configured Android test or HarmonyOS Hypium test. `compare` creates a dual-platform evidence record; it supports human review but does not by itself prove semantic equivalence. Preserve command output paths as report evidence.
+`capture` collects the screenshot, UI tree/`dumpLayout`, and device logs. `flow` creates before/after captures around a HarmonyOS Hypium test (Android-side flow has been removed with the Android runtime dependency). `compare` creates a dual-platform evidence record from existing evidence directories; it supports human review but does not by itself prove semantic equivalence. Preserve command output paths as report evidence.
 
 For text input, verify focus and current value after each operation. A click can hit an input field or IME candidate and inject unintended text. Close the IME only with a method proven in the current environment.
 
@@ -39,6 +38,8 @@ White/non-white screenshot heuristics only detect gross rendering failures. They
 
 ## Prefer semantic Hypium UI tests over coordinate injection
 
+> Update (2026-10): migration-flow Hypium test case creation and execution are now standardized on the Python-based `d2h-hypium-forge` pipeline (`.hypium_forge/` assets; iteration via its `run_direct.py`, managed acceptance via `droid2hmos test harmony --runner python --test-list ...`). The ArkTS `entry_test` module workflow below remains valid only as a project-verified lesson for existing ArkTS assets; the principle "semantic location over coordinate injection" and the exception boundaries continue to apply.
+
 - **Evidence level:** project-validated
 - **Applies when:** HarmonyOS user flows need repeatable device-side verification and the relevant ArkUI controls can expose semantic nodes. Verified with DevEco SDK 6.0.2(22) and `@ohos/hypium` 1.0.25; recheck APIs on other versions.
 - **Symptom:** a migration relies on repeated coordinate-based device injection, requiring layout dumps and manual coordinate calculation at every step. Scrolling or layout changes cause misclicks, stale-frame dumps and evidence that cannot be replayed reliably.

package/skills/harmonyos-migration-playbook/references/windows-environment.md

@@ -2,7 +2,7 @@
 
 Check actual paths rather than trusting environment variables:
 
-- Android SDK/JDK/DevEco SDK directories exist and match the invoked tool.
+- JDK/DevEco SDK directories exist and match the invoked tool.
 - Included Gradle builds have the local configuration they require.
 - Proxy settings apply to Gradle/Node and do not unexpectedly intercept device or mail ports.
 - Node/npm pairs come from compatible installations.

package/skills/managing-d2h-toolchain/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: managing-d2h-toolchain
+description: 安装、检查或升级 D2H 所依赖的 AppGraph 与 droid2hmos CLI 时使用。统一读取 D2H 包内的精确版本锁，保留本地 npm link，并把安装结果交还迁移主流程；其他 Skill 不执行工具安装。
+---
+
+# 管理 D2H 工具链
+
+本 Skill 是 AppGraph、droid2hmos 依赖声明、版本维护和安装的唯一流程入口。**依赖包、精确版本及命令能力只在本目录的 `toolchain.json` 声明**；`environment-requirements.json` 提供对应的主机检查边界。其他 Agent/Skill 不声明这些依赖或版本，也不执行 npm 安装或升级。`d2h` CLI 只解析本 Skill 的清单并实现确定性的探测、安装和校验；本 Skill 负责选择时机、目标 Agent 和失败分流。
+
+## 选择 D2H 版本
+
+- 已安装的 OpenCode/DevEco 定义读取配置根目录的 `.d2h-installation.json`；VS Code 定义读取扩展 `resources/opencode/plugin/d2h/.d2h-installation.json`。其中的 `packageVersion` 是本次调用 D2H CLI 的精确版本。
+- `d2h` 命令可用时先执行 `d2h --help`，确认支持 `install`、`upgrade`、`doctor`。需要通过 npx 调用时使用 `npx --yes @harmonyos-arkts/d2h@<packageVersion>`；Windows 使用 `npx.cmd`。不可用或记录缺失时，请调用方提供已批准的**精确 D2H 版本**完成首次安装，不猜测 `latest`。
+- 源码开发使用当前仓库构建出的 `node dist/bin/install-opencode.js`，不要把 npm 上同版本的旧包误当成本地源码。修改 D2H 依赖版本时只改包内 `skills/managing-d2h-toolchain/toolchain.json`，同时更新环境约束、兼容性测试和发布版本。
+
+## 检查与执行
+
+1. 确定目标 `--agent opencode|deveco|vscode`；VS Code 可通过 `--extension-dir` 指定扩展根目录。先运行 `d2h upgrade --check --agent <agent>` 只读预览，再运行 `d2h doctor --agent <agent>` 检查定义完整性、精确版本、命令能力与主机环境。
+2. 若缺少定义或受管 CLI，运行 `d2h install --agent <agent>`；已安装但需要应用当前锁定组合时运行 `d2h upgrade --agent <agent>`。默认保留开发者的 npm link；只有调用方明确指定 `--force` 时，才重新安装清单中的所有精确版本并替换全局 link，链接指向的源码目录保持不变。
+3. 安装后重新运行 `doctor`，核对 `.d2h-installation.json`、AppGraph/droid2hmos 的版本及能力，再把状态交给 `preparing-migration-workspace`。项目级 `droid2hmos preflight` 仍由准备 Skill 执行。
+4. 只想检查主机工具时使用 `d2h --check-env --output-dir <目录>`；读取生成的 JSON/Markdown 报告，不把 DevEco 登录、SDK 或设备缺失误判为需要升级 AppGraph/droid2hmos。
+
+安装失败时保留命令输出和失败阶段。包不可达、版本不匹配、能力不符分别报告；不得把失败掩盖成“使用已安装版本继续”。不允许在其他 Skill 中直接执行 `npm install -g`、`npm update` 或以浮动版本重新安装这两个 CLI。

package/skills/managing-d2h-toolchain/environment-requirements.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "tools": {
+    "node": { "minimum": "22.5.0", "maximumExclusive": "25.0.0" },
+    "python": { "minimum": "3.10.0" },
+    "git": null,
+    "npm": null,
+    "java": null,
+    "python-json5": null,
+    "appgraph": { "minimum": "0.0.10", "maximumExclusive": "0.0.11" },
+    "droid2hmos": { "minimum": "0.0.11", "maximumExclusive": "0.0.12" },
+    "hvigor": null,
+    "ohpm": null,
+    "devecocli": null
+  }
+}