deveco_hmigbot 0.21.5

package/skills/migrate-core/scripts/wire/wire-routes.mjs

@@ -0,0 +1,507 @@
+#!/usr/bin/env node
+/**
+ * wire-routes.mjs — 路由预接线生成器（静态前场件）。
+ *
+ * 从 AndroidManifest 提取 activity 全集 → 生成鸿蒙侧路由基建：
+ *   common/Router.ets（Routes 枚举 + AppRouter 包装器，goHome 指向 launcher，pushName 供冒烟直达）
+ *   pages/Index.ets（@Entry Navigation 壳 + 自动入栈 launcher + smokeRoute 直达钩子 + hmigSmoke 着陆日志）
+ *   pages/<X>Page.ets（每路由骨架：Builder + NavDestination + 源锚点注释；注册页文件 = 切片交付文件）
+ *   resources/base/profile/route_map.json（systemRouterMap，**唯一注册真源**）+ module.json5 routerMap 引用
+ *   entryability/EntryAbility.ets 幂等补丁（onCreate 透传 smokeRoute）
+ *   main_pages.json + wiring-report.json
+ *
+ * 效果："页面可达"由构造保证——注册表生成即闭合（零 ghost），切片阶段只填行为不碰壳。
+ * 纪律：绝不覆盖已存在文件（跳过并记 report；Index 样板壳与 EntryAbility 透传除外，见各处注释）；
+ * 写法采用已被 check-routes 实证解析的枚举+包装器模式（与基准靶同构）。
+ *
+ * 路由真源三轨（形态自适应，--src 模式全跑合并）：
+ *   ① AndroidManifest activity（多 Activity 应用）
+ *   ② res/navigation/*.xml（Jetpack Navigation 配置）
+ *   ③ Compose NavHost composable()（单 Activity Compose——manifest 只见得到壳，实证 1 vs 11）
+ * 单 Activity 壳让位规则：manifest 仅 1 activity 且②/③提出多路由时，壳不成页（壳=鸿蒙 Index 容器）。
+ * 目标注册单轨：resources/.../route_map.json（官方 systemRouterMap）是唯一真源——首跑全集、
+ * `--from-ledger spec/ledger/ledger.json` 二跑按页面账补漏（Routes 枚举/route_map 增量合并），
+ * 新页只经 route_map 注册即可被 pushPathByName 加载，切片阶段零共享文件接触。
+ *
+ * 用法：node wire-routes.mjs (--manifest <xml> | --src <android根>) --out <ets根>
+ *       [--from-ledger <ledger.json>] [--launcher <路由名>] [--json report]
+ * 首页判不了（报告 launcherResolved=false）时用 --launcher 显式校正重跑，脚本不硬猜。
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve, relative, sep } from 'node:path';
+import { extractNavGraph, extractComposeProject, findComposeHostFiles, normalizeRoute, extractAppInit } from './extractors.mjs';
+
+const argv = process.argv.slice(2);
+const argOf = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+let MANIFEST = argOf('--manifest', null);
+const SRC = argOf('--src', null);
+const OUT = argOf('--out', null);
+const JSON_OUT = argOf('--json', null);
+const APP_CLASS = argOf('--app-class', null); // 多产品仓有多个 Application 候选时按所选产品显式指定（与 --launcher 同一套"脚本如实报、参数校正"）
+let manifestCandidates = []; // 全部候选 manifest（多模块）：应用级初始化提取要查未被选中的模块（Application 类常不在承载 LAUNCHER 的模块里）
+if (!MANIFEST && SRC) {
+  const stack = [resolve(SRC)];
+  // 收齐候选再选，不取第一个命中——多模块工程（wear/tv/lib 各有 manifest）按遍历序抓会错定
+  // launcher 模块（实证：误抓 wearOS manifest，launcher 定成手表端 Activity）。
+  const candidates = [];
+  while (stack.length) {
+    const d = stack.pop();
+    let entries; try { entries = readdirSync(d); } catch { continue; }
+    for (const e of entries) {
+      if (['build', '.git', 'node_modules', 'test', 'androidTest'].includes(e)) continue;
+      const p = join(d, e);
+      let st; try { st = statSync(p); } catch { continue; } // 坏符号链接不崩
+      if (st.isDirectory()) stack.push(p);
+      // 不要求 src/main/ 路径：Gradle 允许 manifest.srcFile 指到模块根（老布局工程实证），候选交给下面按内容排序
+      else if (e === 'AndroidManifest.xml' && !/[\\/](androidTest|test|debug|release)[\\/]/.test(p)) candidates.push(p);
+    }
+  }
+  if (candidates.length) {
+    // 内容语义选主模块 manifest（不靠目录名约定——app/ 可叫任何名）：MAIN+LAUNCHER 且非
+    // 手表/TV 形态优先（wear 模块也声明 LAUNCHER，须按 uses-feature/类别再判）；多个同级取
+    // activity 数最多，再同取路径最短（确定性）。选择理由打印，操作者可核。
+    const meta = candidates.map(p => {
+      let x = ''; try { x = readFileSync(p, 'utf8').replace(/<!--[\s\S]*?-->/g, ''); } catch { /* 读失败按空 */ }
+      const hasLauncher = /android\.intent\.category\.LAUNCHER/.test(x) && /android\.intent\.action\.MAIN/.test(x);
+      return {
+        p,
+        launcher: hasLauncher,
+        watch: /android\.hardware\.type\.watch/.test(x),
+        // TV 形态 = 只有 leanback 入口（同一入口同时声明 LAUNCHER 与 LEANBACK_LAUNCHER 的是手机+TV 通用端，不算 TV）
+        tv: /android\.software\.leanback[^>]*required\s*=\s*["']true["']/.test(x) || (/LEANBACK_LAUNCHER/.test(x) && !hasLauncher),
+        acts: (x.match(/<activity[\s>]/g) || []).length,
+      };
+    });
+    const rank = (m) => (m.launcher && !m.watch && !m.tv ? 2 : m.launcher ? 1 : 0);
+    meta.sort((a, b) => rank(b) - rank(a) || b.acts - a.acts || a.p.length - b.p.length);
+    MANIFEST = meta[0].p;
+    manifestCandidates = meta.map(m => ({ path: m.p, watch: m.watch, tv: m.tv }));
+    if (candidates.length > 1) console.log(`[wire-routes] 多模块 manifest ×${candidates.length}，选用 ${MANIFEST}（launcher:${meta[0].launcher ? '有' : '无'}·watch:${meta[0].watch ? '是' : '否'}·activities:${meta[0].acts}）；未选：${meta.slice(1).map(m => m.p).join(' , ')}`);
+  }
+}
+if (!MANIFEST || !OUT) { console.error('usage: wire-routes.mjs (--manifest m.xml | --src root) --out <ets根> [--json report]'); process.exit(2); }
+
+const xml = readFileSync(MANIFEST, 'utf8').replace(/<!--[\s\S]*?-->/g, '');
+const routes = [];
+// 整元素解析：开标签属性段只在引号外找 '>'（子标签的 `/>` 不再截断元素——旧写法使
+// LAUNCHER 检测对标准 manifest 恒为假、静默回退 routes[0]）；(?![-\w]) 排除 <activity-alias>；
+// 属性支持单/双引号。
+for (const m of xml.matchAll(/<activity(?![-\w])((?:"[^"]*"|'[^']*'|[^>"'])*)(\/>|>)/g)) {
+  const attrs = m[1];
+  const name = (attrs.match(/android:name\s*=\s*["']([^"']+)["']/) || [])[1];
+  if (!name) continue;
+  // 自闭合判定：属性段字符类会把结尾 '/' 吞进 attrs（m[2] 永远是 '>'），须回看 attrs 尾部
+  const selfClosing = m[2] === '/>' || /\/\s*$/.test(attrs);
+  let inner = '';
+  if (!selfClosing) {
+    const close = xml.indexOf('</activity>', m.index + m[0].length);
+    inner = close >= 0 ? xml.slice(m.index + m[0].length, close) : '';
+  }
+  const cls = name.split('.').pop().replace(/\$/g, '_'); // 内部类 $ 对文件名/工具链不安全
+  const route = cls.replace(/Activity$/, '') || cls;
+  const launcher = /android\.intent\.action\.MAIN\b/.test(inner) && /android\.intent\.category\.LAUNCHER\b/.test(inner);
+  const enabled = !/android:enabled\s*=\s*["']false["']/.test(attrs);
+  routes.push({ route, cls, fqcn: name, launcher, enabled });
+}
+// <activity-alias> 承载 MAIN+LAUNCHER（换启动图标/多入口的标准写法）：首页 = 别名的 targetActivity。
+// 只在没有 Activity 直接声明 LAUNCHER 时生效（实证：有应用把全部 LAUNCHER 都放在别名上，manifest 轨无首页，
+// 被 Compose 子图的 startDestination 顶了位）。
+if (!routes.some(r => r.launcher)) {
+  for (const m of xml.matchAll(/<activity-alias((?:"[^"]*"|'[^']*'|[^>"'])*)(\/>|>)/g)) {
+    const attrs = m[1];
+    if (m[2] === '/>' || /\/\s*$/.test(attrs)) continue;
+    const close = xml.indexOf('</activity-alias>', m.index + m[0].length);
+    const inner = close >= 0 ? xml.slice(m.index + m[0].length, close) : '';
+    if (!(/android\.intent\.action\.MAIN\b/.test(inner) && /android\.intent\.category\.LAUNCHER\b/.test(inner))) continue;
+    const target = (attrs.match(/android:targetActivity\s*=\s*["']([^"']+)["']/) || [])[1];
+    if (!target) continue;
+    const simple = target.split('.').pop().replace(/\$/g, '_');
+    const hit = routes.find(r => r.fqcn === target || r.cls === simple);
+    if (hit) { hit.launcher = true; console.log(`[wire-routes] LAUNCHER 声明在 activity-alias 上，首页取其 targetActivity：${hit.route}`); break; }
+  }
+}
+// ---- 三轨合并：navGraph + Compose（--src 时）----
+const sourcesStat = { manifest: routes.length, navgraph: 0, compose: 0, ledger: 0 };
+let appInit = null; // 应用级初始化真源（--src 时提取；见 extractors.extractAppInit）
+if (SRC) {
+  const navXmls = [], kts = [], javas = [];
+  const st2 = [resolve(SRC)];
+  while (st2.length) {
+    const d = st2.pop();
+    let es; try { es = readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of es) {
+      if (['build', '.git', 'node_modules', 'test', 'androidTest'].includes(e.name) || e.name.startsWith('.')) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) { st2.push(p); continue; }
+      if (/[\\/]res[\\/]navigation[\\/][^\\/]+\.xml$/.test(p)) navXmls.push(p);
+      else if (p.endsWith('.kt')) kts.push(p);
+      else if (p.endsWith('.java')) javas.push(p);
+    }
+  }
+  const have = new Set(routes.map(r => r.route));
+  const add = (r, src) => {
+    if (have.has(r.route)) return;
+    have.add(r.route);
+    routes.push({ route: r.route, cls: r.route, fqcn: r.fqcn, launcher: r.launcher, enabled: true, source: src });
+    sourcesStat[src]++;
+  };
+  for (const nx of navXmls) for (const r of extractNavGraph(readFileSync(nx, 'utf8'))) add(r, 'navgraph');
+  const ktFiles = kts.map(p => { try { return { path: p, text: readFileSync(p, 'utf8') }; } catch { return { path: p, text: '' }; } });
+  // 应用级初始化真源（Application.onCreate / ContentProvider / androidx.startup）→ 报告 appInit：2b 装账据此生成 INIT 卡，
+  // 由一个地基单元认领接进 EntryAbility.onCreate。提取失败不影响路由（如实报）。
+  try {
+    const javaFiles = javas.map(p => { try { return { path: p, text: readFileSync(p, 'utf8') }; } catch { return { path: p, text: '' }; } });
+    const relCwd = (p) => relative(process.cwd(), resolve(p)).replace(/\\/g, '/');
+    const extras = manifestCandidates.filter(c => resolve(c.path) !== resolve(MANIFEST) && !c.watch && !c.tv)
+      .map(c => { try { return { path: relCwd(c.path), text: readFileSync(c.path, 'utf8').replace(/<!--[\s\S]*?-->/g, '') }; } catch { return null; } });
+    const ai = extractAppInit(xml, [...ktFiles, ...javaFiles], { manifest: relCwd(MANIFEST), extras, preferClass: APP_CLASS });
+    const relSrc = (p) => p ? relative(resolve(SRC), p).replace(/\\/g, '/') : null;
+    if (ai) appInit = { ...ai, file: relSrc(ai.file), onCreateSites: ai.onCreateSites.map(c => ({ ...c, file: relSrc(c.file) })) };
+  } catch (e) { console.log(`[wire-routes] ▲ 应用级初始化提取失败（不影响路由）：${e.message}`); }
+  // 顶层 NavHost 宿主（两跳）：launcher activity 文件 → 它调用的 @Composable → 定义文件；决定 ①Compose 起点取自哪个 NavHost
+  // ②单 Activity 是否真是壳。多模块工程各特性都有自己的 NavHost，不定位宿主就会把某个子流程的起点当首页（实测）。
+  let hostFiles = [];
+  {
+    const ml = routes.find(r => r.launcher);
+    if (ml) {
+      const simple = ml.fqcn.split('.').pop().replace(/\$/g, '_');
+      const moduleRoot = resolve(dirname(MANIFEST), '..', '..');
+      const cands = kts.filter(p => p.endsWith(`${sep}${simple}.kt`));
+      const actFile = cands.find(p => p.startsWith(moduleRoot)) || cands[0];
+      if (actFile) hostFiles = findComposeHostFiles(ktFiles, actFile);
+    }
+  }
+  if (ktFiles.some(f => /\bNavHost\s*\(|\bNavDisplay\b|EntryProviderScope|entryProvider/.test(f.text))) {
+    for (const r of extractComposeProject(ktFiles, { hostFiles })) add(r, 'compose');
+  }
+  // 壳让位两则：
+  // ① 单 Activity 壳：整壳不成页（→ Index 容器），真首页取②/③的 launcher——须有宿主证据（activity 两跳内有 NavHost）；
+  //    单 Activity 但无宿主 = 经典多屏 Activity 内嵌特性级 NavHost，首页保留为该 activity，Compose 路由作页内子路由。
+  const extra = routes.filter(r => r.source);
+  if (sourcesStat.manifest === 1 && extra.length >= 2 && (hostFiles.length || !extra.some(r => r.source === 'compose'))) {
+    const shell = routes.find(r => !r.source);
+    routes.splice(routes.indexOf(shell), 1);
+    console.log(`[wire-routes] 单 Activity 壳 ${shell.route} 让位（→ Index 容器）；路由真源=${extra.some(r => r.source === 'compose') ? 'Compose NavHost' : 'navGraph'} ×${extra.length}`);
+    if (extra.some(r => r.launcher)) for (const r of routes) if (!r.source) r.launcher = false;
+  } else if (sourcesStat.manifest === 1 && extra.length >= 2) {
+    for (const r of extra) r.launcher = false;
+    console.log(`[wire-routes] 单 Activity 但非 Compose 壳（activity 两跳内无 NavHost/NavDisplay）：首页保留 ${routes.find(r => !r.source)?.route}，${extra.length} 条 Compose 路由作页内子路由`);
+  }
+  // ② 混合形态 launcher 让位（需壳证据，不靠假设）：导航图有 startDestination 时，仅当
+  //    manifest launcher activity **确证为装 NavHost 的壳**（其类源码或 setContentView 布局含
+  //    NavHost 标记）才让位；无证据（闪屏/登录等真实首屏，自身实现转发链）→ 保留不动。
+  else if (extra.some(r => r.launcher) && SRC) {
+    const shellLauncher = routes.find(r => !r.source && r.launcher);
+    if (shellLauncher) {
+      const simple = shellLauncher.fqcn.split('.').pop();
+      let evidence = hostFiles.length > 0; // Compose 宿主两跳定位已证 launcher activity 是壳
+      const HOST_RE = /NavHostFragment|setupWithNavController|FragmentContainerView[\s\S]{0,400}?navGraph|\bNavHost\s*\(/;
+      const stk = [resolve(SRC)];
+      let clsText = '';
+      while (stk.length && !evidence) {
+        const d = stk.pop();
+        let es; try { es = readdirSync(d, { withFileTypes: true }); } catch { continue; }
+        for (const e of es) {
+          if (['build', '.git', 'node_modules', 'test', 'androidTest'].includes(e.name) || e.name.startsWith('.')) continue;
+          const p = join(d, e.name);
+          if (e.isDirectory()) { stk.push(p); continue; }
+          if (e.name === `${simple}.kt` || e.name === `${simple}.java`) {
+            try { clsText = readFileSync(p, 'utf8'); } catch { }
+            if (HOST_RE.test(clsText)) evidence = true;
+          }
+        }
+      }
+      if (!evidence && clsText) {
+        // 二跳：setContentView(R.layout.X) → res/layout/X.xml 含 NavHost 标记
+        const lay = (clsText.match(/setContentView\s*\(\s*R\.layout\.(\w+)/) || [])[1];
+        if (lay) {
+          const stk2 = [resolve(SRC)];
+          while (stk2.length && !evidence) {
+            const d = stk2.pop();
+            let es; try { es = readdirSync(d, { withFileTypes: true }); } catch { continue; }
+            for (const e of es) {
+              if (['build', '.git', 'node_modules'].includes(e.name) || e.name.startsWith('.')) continue;
+              const p = join(d, e.name);
+              if (e.isDirectory()) { stk2.push(p); continue; }
+              if (e.name === `${lay}.xml` && p.includes(`${sep}layout`)) {
+                try { if (/NavHostFragment|app:navGraph|FragmentContainerView/.test(readFileSync(p, 'utf8'))) evidence = true; } catch { }
+              }
+            }
+          }
+        }
+      }
+      if (evidence) {
+        shellLauncher.launcher = false;
+        console.log(`[wire-routes] 混合形态：manifest launcher ${shellLauncher.route} 确证为 NavHost 壳，首页让位给导航图 startDestination（${extra.find(r => r.launcher)?.route}）`);
+      } else {
+        for (const r of extra) r.launcher = false;
+        console.log(`[wire-routes] 混合形态：manifest launcher ${shellLauncher.route} 无 NavHost 壳证据（闪屏/登录类真实首屏）——保留为首页，导航图 startDestination 由其转发链到达`);
+      }
+    }
+  }
+}
+// ---- 台账补漏（2b 装账后二跑）：页面账里有而三轨没提到的，兜底成页 ----
+const FROM_LEDGER = argOf('--from-ledger', null);
+if (FROM_LEDGER && existsSync(FROM_LEDGER)) {
+  const l = JSON.parse(readFileSync(FROM_LEDGER, 'utf8'));
+  const have = new Set(routes.map(r => r.route));
+  for (const p of (l.pages || [])) {
+    const route = normalizeRoute(p.id || p.name || '');
+    if (!route || have.has(route)) continue;
+    have.add(route);
+    routes.push({ route, cls: route, fqcn: `ledger:${p.id}`, launcher: false, enabled: true, source: 'ledger' });
+    sourcesStat.ledger++;
+  }
+}
+// 跨包同 simple name 去重：枚举成员/文件名会冲突 → 后者追加序号并记入报告
+const seenRoute = new Map();
+for (const r of routes) {
+  const n = (seenRoute.get(r.route) || 0) + 1;
+  seenRoute.set(r.route, n);
+  if (n > 1) { r.dedupedFrom = r.route; r.route = `${r.route}${n}`; r.cls = `${r.cls}${n}`; }
+}
+if (!routes.length) { console.error('manifest 未解析出任何 activity'); process.exit(2); }
+// 首页判定：三轨真源 > --launcher 显式指定 > 未判定（取首条并大声报，报告 launcherResolved=false）。
+// 不为个别形态硬猜（如 Navigation 3 经自定义包装 rememberNavigationState(startKey=…) 起栈，静态解析不到初始键）——
+// 判不了就如实报，由流程用 --launcher <路由名> 重跑校正，别让首页错在静默里。
+const LAUNCHER_ARG = argOf('--launcher', null);
+if (LAUNCHER_ARG) { for (const r of routes) r.launcher = r.route === LAUNCHER_ARG; if (!routes.some(r => r.launcher)) { console.error(`--launcher ${LAUNCHER_ARG} 不在路由集：${routes.map(r => r.route).join(', ')}`); process.exit(2); } }
+const launcherResolved = routes.some(r => r.launcher);
+const launcher = routes.find(r => r.launcher) || routes[0];
+if (!launcherResolved) console.log(`[wire-routes] ▲ 首页未能从路由真源判定（无 LAUNCHER/startDestination/rememberNavBackStack 可解），暂取 ${launcher.route}；确认后 --launcher <路由名> 重跑校正`);
+const CONST = r => r.route.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+
+const files = [];
+function emit(relPath, content) {
+  const p = join(OUT, relPath);
+  // Index 壳特例：脚手架（create-project）必然先建 Hello World 样板 Index——"绝不覆盖"在此失效
+  // 会让 Navigation 壳永远生成不出来（真机只见样板页实证）。判定：现存 Index 无 Navigation(
+  // = 脚手架样板/非壳 → 备份后覆盖；已是壳（含 Navigation）则维持不覆盖。
+  if (relPath === 'pages/Index.ets' && existsSync(p)) {
+    const cur = readFileSync(p, 'utf8');
+    if (!/Navigation\s*\(/.test(cur)) {
+      writeFileSync(p + '.scaffold.bak', cur);
+      writeFileSync(p, content);
+      files.push({ file: relPath, action: 'overwrite(脚手架样板→Navigation 壳，原件 .scaffold.bak)' });
+      return;
+    }
+  }
+  if (existsSync(p)) { files.push({ file: relPath, action: 'skip(已存在，绝不覆盖)' }); return; }
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+  files.push({ file: relPath, action: 'generated' });
+}
+
+// ---- Router.ets ----
+emit('common/Router.ets', `/**
+ * Router.ets —— 由 wire-routes 生成（源：${MANIFEST.split(sep).slice(-3).join('/')}）。
+ * 路由注册与跳转唯一通道：页面只准 import AppRouter，禁散落 pushPathByName。
+ * 本文件归静态前场独占；切片阶段只填页面行为，不碰壳。
+ */
+export class NoParam {
+}
+
+export const enum Routes {
+${routes.map(r => `  ${CONST(r)} = '${r.route}',`).join('\n')}
+}
+
+export class AppRouter {
+  static readonly stack: NavPathStack = new NavPathStack();
+
+  static push(route: Routes, params?: Object, onPop?: (pop: PopInfo) => void): void {
+    const param: Object = params !== undefined ? params : new NoParam();
+    if (onPop !== undefined) {
+      AppRouter.stack.pushPathByName(route, param, onPop);
+    } else {
+      AppRouter.stack.pushPathByName(route, param);
+    }
+  }
+
+  /** 按运行期路由名跳转（冒烟直达钩子/深链用；业务代码一律走 push(Routes.X)） */
+  static pushName(name: string, params?: Object): void {
+    AppRouter.stack.pushPathByName(name, params !== undefined ? params : new NoParam());
+  }
+
+  static back(): void {
+    AppRouter.stack.pop();
+  }
+
+  static backWithResult(result: Object): void {
+    AppRouter.stack.pop(result);
+  }
+
+  static replace(route: Routes, params?: Object): void {
+    AppRouter.stack.replacePathByName(route, params !== undefined ? params : new NoParam());
+  }
+
+  static goHome(): void {
+    const names: Array<string> = AppRouter.stack.getAllPathName();
+    if (names.indexOf(Routes.${CONST(launcher)}) >= 0) {
+      AppRouter.stack.popToName(Routes.${CONST(launcher)});
+      return;
+    }
+    AppRouter.stack.clear();
+    AppRouter.stack.pushPathByName(Routes.${CONST(launcher)}, new NoParam());
+  }
+}
+`);
+
+// ---- 每页骨架 ----
+for (const r of routes) {
+  emit(`pages/${r.route}Page.ets`, `/**
+ * ${r.route}Page —— 骨架由 wire-routes 生成。源 activity：${r.fqcn}
+ * TODO(切片)：迁移该页行为与布局（布局骨架由 transpile-layout 产出后并入此处）。
+ */
+import { AppRouter } from '../common/Router';
+
+@Builder
+export function ${r.route}PageBuilder() {
+  ${r.route}Page()
+}
+
+@ComponentV2
+struct ${r.route}Page {
+  build() {
+    NavDestination() {
+      Column() {
+        Text('${r.route}')
+        // TODO(切片): 页面内容。返回语义：AppRouter.back() / backWithResult(...)
+      }
+      .width('100%')
+      .height('100%')
+    }
+    .hideTitleBar(true)
+  }
+}
+`);
+}
+
+// ---- Index 壳（单一注册：路由真源只有 route_map.json；壳只管栈与冒烟钩子）----
+// 不再生成 pageMap 比较分支：双注册=两份真源要模型同步维护（实测模型重写 Index 后 pageMap 丢失/只剩首页），
+// 且 route_map-only 页在 navDestination 存在时是否可达官方未写明。单一注册下 hvigor 的
+// ProcessRouterMap（pageSourceFile/buildFunction 缺失即构建失败）成为免费的注册门。
+emit('pages/Index.ets', `/**
+ * Index —— Navigation 壳，由 wire-routes 生成。路由注册唯一真源 = resources/base/profile/route_map.json
+ * （systemRouterMap，${routes.length} 条），冷启自动入栈 launcher（${launcher.route}）。
+ * 本文件归静态前场独占（冻结件）：smokeRoute 直达钩子 + hmigSmoke 着陆日志供波级冒烟核证，勿删勿改。
+ */
+import { hilog } from '@kit.PerformanceAnalysisKit';
+import { AppRouter, Routes } from '../common/Router';
+
+@Entry
+@ComponentV2
+struct Index {
+  navStack: NavPathStack = AppRouter.stack;
+
+  aboutToAppear(): void {
+    // hmig:smokeLanding 着陆证据：每次页面显示打一条 hilog（smoke.mjs 经 hilog -x -T hmigSmoke 核对着陆页名）
+    AppRouter.stack.setInterception({
+      didShow: (from: NavDestinationContext | NavBar, to: NavDestinationContext | NavBar,
+        operation: NavigationOperation, isAnimated: boolean): void => {
+        let shown: string = 'navBar';
+        if (typeof to !== 'string') {
+          shown = (to as NavDestinationContext).pathInfo.name;
+        }
+        hilog.info(0x0000, 'hmigSmoke', 'didShow %{public}s', shown);
+      }
+    });
+    if (AppRouter.stack.size() === 0) {
+      // smokeRoute：波级冒烟直达钩子（aa start --ps smokeRoute <名>，EntryAbility 透传；正常启动为空走首页链）
+      // 两个独立 push（勿并三元）：首页跳转保持静态常量形态，check-routes 首屏链路门才可解析
+      const smokeRoute = AppStorage.get<string>('smokeRoute') ?? '';
+      if (smokeRoute.length) {
+        AppRouter.pushName(smokeRoute);
+      } else {
+        AppRouter.push(Routes.${CONST(launcher)}, undefined);
+      }
+    }
+  }
+
+  build() {
+    Navigation(this.navStack) {
+    }
+    .mode(NavigationMode.Stack)
+    .hideTitleBar(true)
+  }
+}
+`);
+emit('main_pages.json.generated', JSON.stringify({ src: ['pages/Index'] }, null, 2) + '\n');
+
+// ---- EntryAbility 直达透传（幂等补丁）：不管工程怎么建（create-project 华为模板 / 手工 scaffold），
+// 都由本脚本自己打补丁——实测 create-project 工程无透传，Index 钩子读空静默落首页，波级冒烟 100% 假绿。
+{
+  const eaPath = join(OUT, 'entryability', 'EntryAbility.ets');
+  if (!existsSync(eaPath)) {
+    files.push({ file: 'entryability/EntryAbility.ets', action: 'skip(不存在——建工程后重跑 wire-routes 打透传补丁)' });
+  } else {
+    const t = readFileSync(eaPath, 'utf8');
+    if (/smokeRoute/.test(t)) {
+      files.push({ file: 'entryability/EntryAbility.ets', action: 'skip(透传已在)' });
+    } else {
+      const m = t.match(/onCreate\s*\(\s*([A-Za-z_$][\w$]*)\s*:\s*Want\b[^)]*\)\s*(?::\s*void)?\s*\{/);
+      if (!m) {
+        files.push({ file: 'entryability/EntryAbility.ets', action: 'skip(未找到 onCreate(want: Want…)——手动加透传，写法见 Index 钩子注释)' });
+      } else {
+        const want = m[1];
+        const patch = `\n    // hmig:smokeRoute 波级冒烟直达透传（smoke.mjs 经 aa start --ps smokeRoute 传入；正常启动无此参数）——冻结件，勿删\n` +
+          `    const hmigSmokeRoute: Object | undefined = ${want}.parameters?.['smokeRoute'];\n` +
+          `    if (typeof hmigSmokeRoute === 'string' && hmigSmokeRoute.length > 0) {\n` +
+          `      AppStorage.setOrCreate('smokeRoute', hmigSmokeRoute);\n` +
+          `    }`;
+        const at = m.index + m[0].length;
+        writeFileSync(eaPath, t.slice(0, at) + patch + t.slice(at));
+        files.push({ file: 'entryability/EntryAbility.ets', action: 'patch(onCreate 插入 smokeRoute 透传)' });
+      }
+    }
+  }
+}
+
+// ---- systemRouterMap（官方配置化注册，唯一真源）：route_map.json 按 name 合并更新 ----
+// --from-ledger 二跑新增页也只经此注册（无需动 Router/Index 共享文件——切片阶段零共享接触的关键）。
+{
+  const rmPath = join(OUT, '..', 'resources', 'base', 'profile', 'route_map.json');
+  let rm = { routerMap: [] };
+  if (existsSync(rmPath)) { try { rm = JSON.parse(readFileSync(rmPath, 'utf8')); } catch { /* 坏文件重建 */ } }
+  const haveRm = new Set((rm.routerMap || []).map(e => e.name));
+  let added = 0;
+  for (const r of routes) {
+    if (haveRm.has(r.route)) continue;
+    rm.routerMap.push({ name: r.route, pageSourceFile: `src/main/ets/pages/${r.route}Page.ets`, buildFunction: `${r.route}PageBuilder` });
+    added++;
+  }
+  mkdirSync(dirname(rmPath), { recursive: true });
+  writeFileSync(rmPath, JSON.stringify(rm, null, 2) + '\n');
+  files.push({ file: '../resources/base/profile/route_map.json', action: added ? `merge(+${added})` : 'merge(无新增)' });
+  // module.json5 幂等插入 routerMap 引用
+  const modPath = join(OUT, '..', 'module.json5');
+  if (existsSync(modPath)) {
+    const t = readFileSync(modPath, 'utf8');
+    if (!/"routerMap"/.test(t)) {
+      const t2 = t.replace(/("module"\s*:\s*\{)/, `$1\n    "routerMap": "$profile:route_map",`);
+      if (t2 !== t) { writeFileSync(modPath, t2); files.push({ file: '../module.json5', action: 'routerMap 引用已插入' }); }
+    }
+  } else files.push({ file: '../module.json5', action: 'skip(不存在——建工程后重跑或手动加 "routerMap": "$profile:route_map")' });
+}
+// ---- Router.ets 增量合并：二跑新增路由把缺失的 Routes 常量插入既有枚举（不覆盖既有内容）----
+{
+  const routerPath = join(OUT, 'common', 'Router.ets');
+  if (existsSync(routerPath)) {
+    let t = readFileSync(routerPath, 'utf8');
+    const missing = routes.filter(r => !new RegExp(`\\b${CONST(r)}\\s*=`).test(t));
+    if (missing.length && /export const enum Routes \{/.test(t)) {
+      t = t.replace(/(export const enum Routes \{[\s\S]*?)(\n\})/, (_m, head, tail) =>
+        head + '\n' + missing.map(r => `  ${CONST(r)} = '${r.route}',`).join('\n') + tail);
+      writeFileSync(routerPath, t);
+      files.push({ file: 'common/Router.ets', action: `merge(+${missing.length} Routes 常量)` });
+    }
+  }
+}
+
+const report = { manifest: relative(process.cwd(), resolve(MANIFEST)), out: relative(process.cwd(), resolve(OUT)) || '.', launcher: launcher.route, launcherResolved, sources: sourcesStat, routes: routes.map(r => ({ route: r.route, from: r.fqcn, source: r.source || 'manifest', launcher: !!r.launcher, enabled: r.enabled !== false, ...(r.dedupedFrom ? { dedupedFrom: r.dedupedFrom, note: '跨包同 simple name，已追加序号防枚举/文件名冲突' } : {}) })), files, appInitScanned: !!SRC, appInit };
+if (JSON_OUT) { mkdirSync(dirname(resolve(JSON_OUT)), { recursive: true }); writeFileSync(JSON_OUT, JSON.stringify(report, null, 2)); }
+console.log(`[wire-routes] ${routes.length} 条路由（launcher=${launcher.route}）→ ${OUT}`);
+if (SRC) {
+  if (appInit) console.log(`[wire-routes] 应用级初始化：${appInit.applicationClass || '（无 Application 类，仅 provider/startup）'}${appInit.applicationClass && !appInit.classFound ? '（类文件未找到，按 manifest 如实报）' : ''} · onCreate 位点 ${appInit.onCreateSites.length}（${appInit.onCreateSites.map(s => `${s.cls}:${s.bodyLines} 行`).join('、') || '无'}） · provider ${appInit.providers.length} · startup 初始化器 ${appInit.startupInitializers.length}${appInit.di ? ` · DI=${appInit.di}` : ''}${appInit.ambiguous ? ` · ▲ 多产品仓：${appInit.applicationCandidates.length} 个 Application 候选（${appInit.applicationCandidates.map(c => c.applicationClass.split('.').pop()).join('/')}），取首个；按所选产品用 --app-class <类名> 重跑校正` : ''}——2b 装账 parse-cards --wiring 生成 INIT 卡，由地基单元读锚定源码逐项接进 EntryAbility.onCreate`);
+  else console.log('[wire-routes] 无自定义 Application / provider / startup 初始化器（无需 INIT 单元）');
+}
+for (const f of files) console.log(`  ${f.action === 'generated' ? '＋' : '⊘'} ${f.file}${f.action.startsWith('skip') ? ' ' + f.action : ''}`);