Deploy

Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" - if it outputs a message, show it to the user before proceeding.

📋 Shared instructions: shared-instructions.md — read first.

Deploy

Builds the mobile app in the current directory and pushes it to the Power Platform environment recorded in power.config.json.

This skill uses the standard 4-step deployment flow for this plugin: check memory bank, build, deploy, then update memory bank.

Out of scope (deliberately)

• expo run:ios / expo run:android — local native compile is the user's choice; run your platform-specific native command directly when ready.
• OTA updates and store distribution — out of scope for v0.
• Starting Metro for local dev — created apps use npm run dev; template Metro config writes .powernative logs for /debug-app.

Workflow

1. Check memory bank → 1.5 App ID preflight → 2. Build → 2.4 Native package → 2.5 Offline profile coverage gate → 3. Deploy → 4. Update memory bank

Step 1 — Check memory bank

Read memory-bank.md from the project root if present. Capture:

• Project name
• Environment (id + display name)
• Current version

If absent, continue — the project may have been created without the plugin. Re-derive env from power.config.json if needed.

Step 1.5 — App ID preflight (first-deploy gate)

Read power.config.json before building anything:

node -e "const c=require('./power.config.json');console.log(c.appId||'MISSING')"

• Prints a GUID → normal path. Continue to Step 2.

• Prints MISSING (null, absent, or empty) → this is a first deploy. Say so plainly before doing any work:

  "⚠️ First deploy detected — power.config.json has no appId yet. The app ID is minted by the first push, but it is compiled into the native bundle at build time. So two full build+push cycles are required. I'll run both; the second is not optional."

  Then run Steps 2 → 2.4 → 2.5 → 3 twice. In cycle 2, npm run build and the Step 2.4 native packaging commands must all re-run — the Hermes bundles from cycle 1 have an empty app ID compiled in. Step 2.5 (offline profile gate) may be skipped on cycle 2 only if no schema or profile file changed between the two cycles; if in doubt, re-run it — it is a local, no-network check.

Why two cycles are unavoidable. power-apps push mints the app ID and writes it back to power.config.json, but it refuses to run at all without an existing build — it fails immediately if the configured buildPath (./dist) is absent. So the ID cannot be minted before the first build, and the first build cannot contain the ID.

Why this is so easy to miss. The runtime guard is:

Platform.OS !== 'web' && !isDevPlayer && !hasConfiguredValue(powerConfig.appId)

Web is exempt, and so is Dev Player. The Code App, npm run dev, and the browser preview all look perfectly healthy. The failure appears only in the wrapped native app, as a full-screen red "App ID is missing — Push the mobile app to the Power Platform environment, rebuild it, and try again." That is after a base-package wrap, a signed build, and a device install — the most expensive possible place to discover a one-line config gap.

Step 2 — Build

Telemetry checkpoint: build_power_apps_bundle

Print before starting:

"→ Building production web bundle via npm run build (= expo export --platform web). ~30–90 seconds."

First regenerate connectorSchemas.ts so app/_layout.tsx's schemaMap import reflects every connector currently in .power/schemas/. The npm prestart/preandroid/preios hooks cover dev runs, but npm run build does not — if a connector was added since the last npm run dev, the bundled JS would ship a stale schema map. Always regenerate before build:

npm run generate-schemas
npm run build

If package.json has no build script, fall back to:

npx expo export --platform web

(The current template does not define a build script, so this fallback is the normal path for freshly scaffolded apps. Both forms produce the same dist/ web output.)

Known issue — expo export --platform web never exits. The export finishes its work (writes dist/, prints Exported: dist and the asset count) and then hangs indefinitely. Reproduced deterministically across separate runs; observed still alive 2h34m after completing. dist/ is complete and correct when this happens. Suspected cause: the Metro config returned by createPowerAppsMetroConfig (metro.config.js) installs a dev-server middleware internally, which appears to hold an open handle — a web export should not need a dev server. Note the template itself only calls createPowerAppsMetroConfig; the middleware is applied inside @microsoft/power-apps-native-host, not in app code. Not yet root-caused.

Do not wait on the process. Run it detached and poll for the artifact. Per shared-instructions, scratch files stay project-local in .tmp/ — a fixed /tmp/ path would collide across concurrent projects, and a stale log there could satisfy the grep below and falsely report success:

mkdir -p .tmp
rm -f .tmp/expo-web-export.log
npx expo export --platform web > .tmp/expo-web-export.log 2>&1 &
EXPORT_PID=$!
for _ in $(seq 1 90); do
  grep -q "Exported: dist" .tmp/expo-web-export.log 2>/dev/null && break
  sleep 2
done
if ! grep -q "Exported: dist" .tmp/expo-web-export.log 2>/dev/null; then
  echo "web export did not complete in 180s"; tail -30 .tmp/expo-web-export.log; exit 1
fi
test -f dist/index.html || { echo "dist/index.html missing"; exit 1; }
kill "$EXPORT_PID" 2>/dev/null || true
echo "✓ web export complete (process terminated manually — known hang)"

Treat a completed dist/ as success even though the process had to be killed. The Step 2.4 native packaging commands are not affected — both exit 0 cleanly and stage into dist/ via a temp dir, so they do not clear the web build.

If the build fails:

• TS6133 (unused import) → remove the import and retry once.
• Other TypeScript errors → report file + line and STOP. Don't deploy a broken build.
• Metro bundler errors → surface the full stack and STOP.

Verify dist/ exists with index.html before continuing.

Step 2.4 — Native package (Hermes bundle + customer assets)

Print before starting:

"→ Compiling the native Hermes bundle and hash-addressed asset package for iOS and Android. No JavaScript is compiled inside the wrap pipeline — it only consumes these prebuilt files. ~1–3 minutes."

Node version gate (required). The native export crashes on Node < 20.19.4 — it hits util.styleText(['yellow','inverse','bold'], …), which older Node rejects, failing the Metro bundle with a cryptic ERR_INVALID_ARG_VALUE. Check first:

node -e 'const [M,m,p]=process.versions.node.split(".").map(Number); const ok = M>20 || (M===20 && (m>19 || (m===19 && p>=4))); if (!ok) { console.error(`Node ${process.versions.node} is too old; need >= 20.19.4`); process.exit(1); } console.log(`✓ Node ${process.versions.node}`);'

If it exits non-zero, STOP and tell the user to switch (nvm use 20.19.4, or install Node ≥ 20.19.4) and rerun. Do not run the native packaging commands on older Node.

The web build above produces dist/index.html (the hosted Code App). Native wrapped apps additionally need a precompiled Hermes bundle and the customer's images/fonts as hash-addressed asset files, so the wrap pipeline never compiles or downloads JavaScript. Produce both platforms:

npm run bundle:android
npm run bundle:ios

Each command produces that platform's native Hermes bundle and its customer asset package, writing next to dist/index.html:

• Android: dist/index.android.bundle.hbc (Hermes bytecode) + dist/powerapps-customer-assets-android/ (manifest.json + assets/<fileHash>.<type>)
• iOS: dist/main.jsbundle.hbc (Hermes bytecode) + dist/powerapps-customer-assets-ios/ (manifest.json + assets/<fileHash>.<type>)

Both platforms are required — the verification below fails if either bundle or either manifest is missing.

These sit alongside index.html under the same container SAS, so the wrap pipeline fetches them as siblings — no RP or connector change is required.

Verify before continuing — STOP on any failure (never push a web-only build for a native-wrapped app):

# Hermes magic bytes on both bundles (expect c61fbc03)
for f in dist/index.android.bundle.hbc dist/main.jsbundle.hbc; do
  test -f "$f" || { echo "MISSING $f"; exit 1; }
  node -e 'const fs=require("fs"),b=Buffer.alloc(4),fd=fs.openSync(process.argv[1],"r");fs.readSync(fd,b,0,4,0);fs.closeSync(fd);process.exit(b.toString("hex")==="c61fbc03"?0:1)' "$f" || { echo "$f is not Hermes bytecode"; exit 1; }
done
# both asset manifests present
test -f dist/powerapps-customer-assets-android/manifest.json || { echo "MISSING android manifest"; exit 1; }
test -f dist/powerapps-customer-assets-ios/manifest.json     || { echo "MISSING ios manifest"; exit 1; }
echo "✓ native package + asset manifests present"

If a native packaging step fails, surface the error and STOP. If the app renders bundled images/fonts, also confirm each manifest.json assets array is non-empty (an empty array means the app doesn't require() any static asset yet).