Merge remote-tracking branch into fix/mobile-metro-session-portability

Author: Shubham Agarwal

.github/workflows/mobile-apps-script-tests.yml

@@ -9,6 +9,8 @@ on:
             - "plugins/mobile-apps/scripts/**"
             - "plugins/mobile-apps/skills/create-mobile-app/SKILL.md"
             - "plugins/mobile-apps/skills/debug-app/SKILL.md"
+            - "plugins/mobile-apps/template/metro.config.js"
+            - "plugins/mobile-apps/template/package.json"
             - ".github/workflows/mobile-apps-script-tests.yml"
 
 jobs:

plugins/mobile-apps/README.md

@@ -92,7 +92,7 @@ connector wiring.
 
 5. Start mobile app:
 
-	`/create-mobile-app` starts Metro with the app's normal `npm run dev` command.
+	`/create-mobile-app` starts Metro after its explicit schema and type-check gates.
     The template's Metro config delegates sanitized logging to the native host package, which writes `.powernative/metro-logs/`,
     so `/debug-app` works after switching between VS Code, Copilot CLI, and
     Claude Code without asking for a terminal ID.

plugins/mobile-apps/scripts/tests/metro-logging-contract.test.js

@@ -5,16 +5,25 @@ const fs = require('node:fs');
 const path = require('node:path');
 const test = require('node:test');
 
-test('template delegates Metro logging to the host helper and fails open', () => {
+test('template imports the host Metro logger at config startup', () => {
   const pluginRoot = path.resolve(__dirname, '..', '..');
+  const workflow = fs.readFileSync(
+    path.resolve(pluginRoot, '..', '..', '.github', 'workflows', 'mobile-apps-script-tests.yml'),
+    'utf8',
+  );
   const metroConfig = fs.readFileSync(path.join(pluginRoot, 'template', 'metro.config.js'), 'utf8');
   const gitignore = fs.readFileSync(path.join(pluginRoot, 'template', '.gitignore'), 'utf8');
+  const packageJson = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'template', 'package.json'), 'utf8'));
 
-  assert.match(metroConfig, /@microsoft\/power-apps-native-host\/metro-logger/);
-  assert.match(metroConfig, /withPowerNativeMetroLogging/);
-  assert.match(metroConfig, /catch \{/);
+  assert.match(
+    metroConfig,
+    /const \{ withPowerNativeMetroLogging \} = require\('@microsoft\/power-apps-native-host\/metro-logger'\);/,
+  );
   assert.doesNotMatch(metroConfig, /SENSITIVE_LINE_PATTERN|appendMetroLog|process\.stdout\.write/);
+  assert.equal(packageJson.dependencies['@microsoft/power-apps-native-host'], '^0.2.26');
   assert.match(gitignore, /^\.powernative\//m);
+  assert.match(workflow, /plugins\/mobile-apps\/template\/metro\.config\.js/);
+  assert.match(workflow, /plugins\/mobile-apps\/template\/package\.json/);
 });
 
 test('skill contracts read .powernative logs directly', () => {
@@ -27,9 +36,16 @@ test('skill contracts read .powernative logs directly', () => {
   assert.match(createFrontmatter, /allowed-tools:.*\bSkill\b/);
   assert.match(createSkill, /\.powernative\/metro-logs/);
   assert.match(createSkill, /npm run dev/);
+  assert.match(createSkill, /npx expo start/);
+  assert.match(createSkill, /without rerunning the `predev` schema hook/);
   assert.doesNotMatch(createSkill, /scripts\/metro-session\.js|dev:expo|copy the plugin wrapper/i);
   assert.match(debugSkill, /\.powernative\/metro-logs/);
   assert.match(debugSkill, /latest .*\.powernative/i);
+  assert.match(debugSkill, /"logPath":/);
+  assert.match(debugSkill, /"pid":/);
+  assert.match(debugSkill, /predates project-local Metro logging/);
+  assert.match(debugSkill, /\^0\.2\.26/);
+  assert.doesNotMatch(debugSkill, /tail -n 500 "\$LOG_PATH"/);
   assert.doesNotMatch(debugSkill, /BashOutput|METRO_TERMINAL_ID|metro-session\.js|start --project-root/);
   assert.match(deploySkill, /\.powernative/);
 });

plugins/mobile-apps/skills/create-mobile-app/SKILL.md

@@ -1899,7 +1899,7 @@ After `tsc` passes, offer a static HTML preview. The dev server starts next (Ste
 **Print before starting:**
 > "→ [Step 12/13] Launching Metro so you can scan the QR; logs will be written under .powernative/."
 
-This skill launches the template's normal `npm run dev` command so:
+This skill runs the schema/typecheck gates explicitly, then launches `npx expo start`. Manual `npm run dev` remains the template's normal entry point and produces the same project-local log because logging is configured in `metro.config.js`.
 
 1. The native Metro URL is printed by Expo — the user can scan it immediately.
 2. Hot-reload works on file edits — no restart needed for screen tweaks.
@@ -1921,15 +1921,15 @@ npm run generate-schemas    # refresh schema map for any data sources added sinc
 npx tsc --noEmit            # final gate — dev server starts only from a clean TypeScript state
 ```
 
-Run the schema regen and final `tsc` synchronously and check both exits. If either fails, do not launch Metro. Capture the full output once, batch-fix by root cause, rerun the final gate, and continue only when clean. Then start the dev server:
+Run the schema regen and final `tsc` synchronously and check both exits. If either fails, do not launch Metro. Capture the full output once, batch-fix by root cause, rerun the final gate, and continue only when clean. Then start the dev server without rerunning the `predev` schema hook:
 
 ```bash
-npm run dev
+npx expo start
 ```
 
 This is a long-running dev server. In hosts that support background terminals, run it as a background/async terminal only for process lifetime; do not persist or depend on the terminal ID. `/debug-app` discovers logs from `.powernative/metro-logs/`, not from terminal output.
 
-The orchestrator already ran `npm run generate-schemas` for the final gate; `predev` remains a safety net for manual starts.
+The orchestrator already ran `npm run generate-schemas` for the final gate; `predev` remains a safety net for manual `npm run dev` starts.
 
 Read the initial terminal output and locate the generated `.powernative` log directly:
 

plugins/mobile-apps/skills/debug-app/SKILL.md

@@ -83,7 +83,8 @@ Branch as follows:
 | Log exists and PID still owns the logged port | Treat as live. Capture `port`, `pid`, `logPath`, and continue. |
 | Log exists, PID is gone, and another process owns the logged port | Do NOT diagnose from this log. Tell the user which PID holds the port and ask them to restart `npm run dev`. |
 | Log exists but PID/port contradict each other | The device may be talking to the wrong server. Ask the user to stop stale Metro processes and rerun `npm run dev`. |
-| No log exists | Tell the user Metro is not running or has not emitted `.powernative` logs. Ask them to run `npm run dev`, open the native app, then rerun `/debug-app`. |
+| No log exists and `metro.config.js` does not directly import `@microsoft/power-apps-native-host/metro-logger`, or `package.json` does not require `@microsoft/power-apps-native-host` `^0.2.26` or newer | This project predates project-local Metro logging. Stop and report both missing contract pieces. Do not enter a restart loop or edit customer-owned config from `/debug-app`; the user must adopt the current template's Metro config and host dependency first. |
+| No log exists and the Metro config/dependency contract is current | Tell the user Metro is not running or has not emitted `.powernative` logs. Ask them to run `npm run dev`, open the native app, then rerun `/debug-app`. |
 
 The port check prevents stale-log diagnosis: a log file can outlive its Metro process, so only the socket probe reveals that the log stopped belonging to the app under test.
 
@@ -114,13 +115,29 @@ If `fixes.md` is empty, write a session header:
 
 ### 0.2 Verify Metro bundled and the app is running
 
-Read the latest sanitized log window:
+Read a bounded baseline window and return a real byte cursor:
 
 ```bash
-tail -n 500 "$LOG_PATH"
+node - "$LOG_PATH" 262144 <<'NODE'
+const fs = require('node:fs');
+const [file, maxText] = process.argv.slice(2);
+const maxBytes = Number(maxText);
+const size = fs.statSync(file).size;
+const start = Math.max(0, size - maxBytes);
+const fd = fs.openSync(file, 'r');
+const buffer = Buffer.alloc(size - start);
+const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, start);
+fs.closeSync(fd);
+process.stdout.write(JSON.stringify({
+   cursor: start,
+   nextCursor: start + bytesRead,
+   truncated: start > 0,
+   output: buffer.subarray(0, bytesRead).toString('utf8')
+}, null, 2));
+NODE
 ```
 
-Parse `output`, `port`, and `nextCursor`. Scan `output`:
+Parse `output`, `cursor`, `nextCursor`, and `truncated`; use the `pid`, `port`, and `logPath` resolved in Phase 0.0. Scan `output`:
 
 - Most recent error-class line is `SyntaxError`, `Unable to resolve module`, `transform failed`, or `error: Bundling failed` → bundle is broken. Treat as a Step B "Import / Bundle" critical error and route through Step D immediately. Do NOT enter the steady-state loop until the bundle is healthy.
 - Output contains `Bundling complete` / `iOS Bundled` / `Android Bundled` with no later error-class line → Metro is healthy. Proceed.
@@ -129,6 +146,8 @@ Parse `output`, `port`, and `nextCursor`. Scan `output`:
   Stop here.
 - Output is empty despite `status.running: true` → Metro has not emitted enough state yet. Tell the user to wait for the native URL, then re-run `/debug-app`; do not guess readiness.
 
+If `truncated: true`, the baseline covers only the latest 256 KiB. Record that older history was omitted; do not claim the full session history was inspected.
+
 Before initializing the cursor, pass **all** classifiable entries in this initial
 window through Step B, including JS runtime errors, React warnings, network/API
 failures, native errors, and host diagnostics. Do not advance past a prior error
@@ -183,17 +202,19 @@ Write `.claude/debug-app/metro-cursor.json` using structured JSON:
 
 ```json
 {
+   "logPath": "/absolute/project/.powernative/metro-logs/metro-<timestamp>-pid-12345-port-8081.log",
+   "pid": 12345,
    "port": 8081,
    "cursor": 12345,
    "updatedAt": "<ISO timestamp>"
 }
 ```
 
-Set `cursor` to `nextCursor` from Phase 0.2. On later invocations:
+Set `logPath`, `pid`, and `port` from Phase 0.0, and set `cursor` to `nextCursor` from Phase 0.2. On later invocations:
 
-- Same `port` and `running: true` → reuse the saved cursor so old errors are not processed again.
-- Different `port` → a new Metro session is in play. Discard the old cursor and initialize from the latest log window.
-- `tail.rotationLost: true` (the saved cursor is past end-of-file, which can only happen when the log rotated) → accept the returned reset cursor and record the rotation in `fixes.md`.
+- Same `logPath`, `pid`, and `port`, with the process still owning the port → reuse the saved cursor so old errors are not processed again.
+- Different `logPath`, `pid`, or `port` → a new Metro session is in play. Discard the old cursor and initialize from the latest log window.
+- `rotationLost: true` from Step A → accept the returned reset cursor and record the file shrink/replacement in `fixes.md`.
 
 ---
 
@@ -341,7 +362,7 @@ Repeat until **3 consecutive clean cycles**, OR the user types `stop`, OR the es
 
 ### Step A — Collect logs
 
-Read `.claude/debug-app/metro-cursor.json`, confirm its `logPath` still points at the latest live `.powernative` log, then read newly appended bytes:
+Read `.claude/debug-app/metro-cursor.json`, rediscover the latest live `.powernative` log using Phase 0.0, and confirm the saved `logPath`, `pid`, and `port` still match. If any differ, return to Phase 0.2 and initialize a new baseline. Otherwise read newly appended bytes:
 
 ```bash
 node - "$LOG_PATH" <saved-cursor> 262144 <<'NODE'
@@ -365,7 +386,7 @@ process.stdout.write(JSON.stringify({
 NODE
 ```
 
-Use only the returned `output` for this cycle. Immediately persist `nextCursor` and the current `port` to `metro-cursor.json`, even when `output` is empty or contains an error; this prevents duplicate processing after interruption and handles log rotation safely.
+Use only the returned `output` for this cycle. Immediately persist the current `logPath`, `pid`, `port`, `nextCursor`, and a new `updatedAt` to `metro-cursor.json`, even when `output` is empty or contains an error; this prevents duplicate processing after interruption and handles file replacement safely.
 
 Count a clean cycle only after observing a full 5-second interval with empty or non-error new output. If the log file changes, the PID/port check becomes contradictory, or the cursor resets because the file shrank/rotated, never count that cycle as clean.
 

plugins/mobile-apps/template/README.md

@@ -97,7 +97,7 @@ connector wiring.
 
 5. Start mobile app:
 
-	`/create-mobile-app` starts Metro with the app's normal `npm run dev` command.
+	`/create-mobile-app` starts Metro after its explicit schema and type-check gates.
 	The template's Metro config delegates sanitized logging to the native host package, which writes `.powernative/metro-logs/`,
 	allowing `/debug-app` to work across VS Code, Copilot CLI, and Claude Code
 	without a terminal ID.

plugins/mobile-apps/template/metro.config.js

@@ -1,13 +1,5 @@
 const { getDefaultConfig } = require('expo/metro-config');
-
-function withPowerNativeMetroLogging(middleware) {
-  try {
-    return require('@microsoft/power-apps-native-host/metro-logger')
-      .withPowerNativeMetroLogging(middleware, { projectRoot: __dirname });
-  } catch {
-    return middleware;
-  }
-}
+const { withPowerNativeMetroLogging } = require('@microsoft/power-apps-native-host/metro-logger');
 
 // CUSTOMIZATION START - DO NOT REMOVE OR RENAME THE COMMENT
 // Add Metro config changes in this function only.
@@ -21,15 +13,18 @@ const config = getDefaultConfig(__dirname);
 config.resolver.sourceExts = [...config.resolver.sourceExts, 'mjs'];
 config.server = {
   ...config.server,
-  enhanceMiddleware: (middleware) => withPowerNativeMetroLogging((req, res, next) => {
-    if (req.url === '/__pawrap_verify') {
-      res.setHeader('Content-Type', 'application/json');
-      res.setHeader('Access-Control-Allow-Origin', '*');
-      res.end(JSON.stringify({ type: 'pawrap-app', version: '1' }));
-      return;
-    }
-    middleware(req, res, next);
-  }),
+  enhanceMiddleware: (middleware) => withPowerNativeMetroLogging(
+    (req, res, next) => {
+      if (req.url === '/__pawrap_verify') {
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.end(JSON.stringify({ type: 'pawrap-app', version: '1' }));
+        return;
+      }
+      middleware(req, res, next);
+    },
+    { projectRoot: __dirname },
+  ),
 };
 
 // Force a single copy of these regardless of where the importing module lives.