@harmonyos-arkts/d2h 0.1.2 → 0.1.5

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/SKILL.md

@@ -1,20 +1,46 @@
 ---
 name: harmonyos-migration-playbook
-description: Diagnose and reuse verified Android-to-HarmonyOS migration lessons for ArkTS compilation, HarmonyOS runtime, UI automation, protocol E2E, and Windows toolchains. Use during migration implementation, failure recovery, validation, or post-commit retrospectives; do not treat project-specific observations as universal platform rules.
+description: Diagnose Android-to-HarmonyOS migration failures, check whether verified lessons apply, and return the smallest scoped fix or recommendation for ArkTS compilation, HarmonyOS runtime, UI automation, protocol E2E, and Windows toolchains. Use during implementation, failure recovery, validation, or retrospectives; do not control checkpoints or outer workflow state.
 ---
 
 # HarmonyOS migration playbook
 
 Use verified experience to shorten diagnosis without replacing current-project evidence.
 
+## Inputs and domain result
+
+Accept the current symptom, in-scope files, SDK/tool versions, relevant logs or managed evidence, and any project lesson candidates. Do not infer success from an earlier project.
+
+Return the same result shape whether called directly or from an orchestrator:
+
+```json
+{
+  "status": "completed | partial | failed",
+  "changedFiles": [],
+  "sourceFiles": [],
+  "evidence": [],
+  "domainChecks": [],
+  "unresolved": [],
+  "verificationRequests": [],
+  "suggestedRemediation": [],
+  "details": {
+    "validatedRootCause": null,
+    "applicability": {},
+    "lessonCandidates": []
+  }
+}
+```
+
+`status` describes diagnosis and any in-scope fix only. `validatedRootCause` requires current-project evidence. Put repository-level build, test, device, or review needs in `verificationRequests`; do not choose the caller's checkpoint or workflow transition.
+
 ## Required operating loop
 
 1. Identify the current symptom and task boundary.
 2. Read only the relevant reference below.
 3. Check that the recorded applicability conditions match the current SDK, UI stack, runtime and code path.
 4. Reproduce or inspect evidence before applying a fix. Historical experience is a hypothesis until confirmed in the current project.
-5. Apply the smallest in-scope fix and run the stated verification.
-6. After validation, create an explicit Git checkpoint with `droid2hmos checkpoint create`; record a reusable lesson only when the root cause and fix are proven.
+5. If the request authorizes a change, apply the smallest in-scope fix; otherwise return the smallest concrete recommendation.
+6. Perform only domain-local checks available within scope. Return repository-level verification as `verificationRequests` and a reusable `lessonCandidates` entry only when the root cause and fix are supported by current-project evidence.
 
 ## Reference routing
 
@@ -42,6 +68,7 @@ Prefer narrower classifications. Public does not mean universal: a project-valid
 - Do not convert implementation defects into platform limitations or external blockers.
 - Do not claim a lesson is verified from a report, comment, code existence or compile success alone when runtime behavior is relevant.
 - Do not modify the public playbook from every task. First record the lesson in the current project; a reviewed, non-obvious and well-verified single-project lesson may be promoted as `project-validated` under `lesson-lifecycle.md` instead of waiting invisibly for another project.
+- Do not stage or commit files, create a checkpoint, update the migration report, call `complete`, schedule full regression, or decide an outer workflow state. The caller owns those actions.
 
 ## Quick triage
 

package/skills/harmonyos-migration-playbook/references/lesson-lifecycle.md

@@ -6,7 +6,7 @@ Read `.migration/experience/lessons.md` when it exists. Select lessons by task t
 
 ## Record after validation and commit
 
-The orchestrator records a lesson only after the implementation is validated and committed through an explicit checkpoint. Before recording, confirm the repository state with `droid2hmos checkpoint status <android-project>`. Use this structure:
+The playbook returns a lesson candidate only after the root cause and fix are supported by current-project evidence. The caller decides whether validation and checkpoint requirements are satisfied and whether to persist or promote the candidate. Use this structure:
 
 ```markdown
 ## <short title>
@@ -22,13 +22,13 @@ The orchestrator records a lesson only after the implementation is validated and
 
 Skip routine success, generic coding advice, speculative causes, duplicate lessons and details recoverable from the commit alone.
 
-If the project tracks `.migration/experience/lessons.md`, record the lesson there. The migration workspace `<android-project>-migration/` lives outside the Android Git repository, so `droid2hmos checkpoint create` (which commits inside the Android repo) can no longer include it; keep lessons as workspace-local run memory, or version the `<android-project>-migration/` directory independently if the project wants lesson history.
+If the project tracks `.migration/experience/lessons.md`, the caller may persist an accepted candidate there. The migration workspace `<android-project>-migration/` lives outside the Android Git repository, so the lesson remains workspace-local run memory unless that workspace is versioned independently.
 
-In either case, use `droid2hmos checkpoint status <android-project>` to ensure the next migration unit does not inherit an unexplained dirty worktree. Do not use `--all` merely to capture the lesson.
+This reference does not inspect, create, or time checkpoints and never recommends broad staging merely to capture a lesson.
 
 ## Promote to the public playbook
 
-`.migration/experience/lessons.md` is the source-project evidence log, not the cross-project knowledge base. Review a lesson after it is committed. If it is non-obvious, reproducible, useful beyond one task, bounded by explicit applicability conditions, and backed by real verification evidence, add its generalized form to the relevant public Playbook reference immediately as `project-validated`.
+`.migration/experience/lessons.md` is the source-project evidence log, not the cross-project knowledge base. After the caller confirms acceptance, review whether a lesson is non-obvious, reproducible, useful beyond one task, bounded by explicit applicability conditions, and backed by real verification evidence. Only then may its generalized form enter the relevant public Playbook reference as `project-validated`.
 
 Public entries must contain: