Test Native Extension

/test-native-extension

Runs the 4-layer validation ladder for a third-party control repo — the one that ships as a .ppmplugin binary bundle, not as a TypeScript extension. Layers 1–4 are automated; Layer 5 is interactive (requires a real device or simulator and the Companion PCF deployed to a test environment).

Run order is layer-by-layer for Layers 1–4. Stop on the first failure in the automated layers. Layer 5 is not gated by the skill — it prints the device recipe and exits; the user runs it on their own time and updates .extension-state.md manually.

What this skill does NOT validate: native code compilation into a loadable DEX / framework. That's the job of /build-android-binary and /build-ios-binary — they run the real Gradle / xcodebuild toolchain against the pinned RN version and surface the real compiler error. Standalone pod lib lint and ./gradlew assembleDebug from this skill would give false-confidence (they resolve dependencies from public CDN/maven, not against the wrap host's pinned versions). This skill is the structural pre-flight that runs in seconds with no toolchain — it asserts the native source is shaped correctly (right base class, right symbols, the Android getName() ↔ iOS +moduleName ↔ manifest agreement) so the build skills don't fail late on a fixable-in-seconds mistake. There is no TypeScript / INativeExtension layer in this track to type-check — a native-only .ppmplugin bundle dispatches straight to NativeModules.<nativeModule>.<method> (ppmplugin-format §2 — Runtime dispatch contract).

Step 1 — Read the shared docs and PRD

1. Read shared/shared-instructions.md, shared/naming-conventions.md, shared/ppmplugin-format.md.

2. Apply the per-skill minimal prereq policy (shared-instructions.md §1.5). Layers 1–3 need no toolchain (pure read + grep + validate against the working tree). Layer 4 needs Node + npm only when a PCF is present — and only for the first run (to npm install the PCF's own deps from the public npm registry). This track is self-contained and requires no package-feed or source-control authentication (shared-instructions §0a). Run the /test-native-extension check from prereq-check.md (Layers 0–3 need nothing; Node + npm only if a PCF is present for Layer 4 — there is no "baseline" check in this self-contained track).

   Print the prereq status as a visible block per shared-instructions.md §9.2 before continuing:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Prereq check — /test-native-extension
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
    🟢 ✓ git installed
    🟢 ✓ Node 20+ installed            (only needed for Layer 4 — PCF compile)
    🟢 ✓ npm installed                 (only needed for Layer 4 — PCF compile)
   
    🟢 3 checks passed. Ready to proceed.
   

   If no pcf/ is present, Node/npm aren't needed at all — note them as n/a (no PCF) rather than failing. Layers 1–3 always run regardless. If any check fails, print the → Fix: line for that check and STOP.

3. Read ./PRD.md. If missing, the Layer 3 contract asserts fall back to the native source itself as source-of-truth (it's still useful) — note it and continue rather than STOP.

4. Read ./.extension-state.md. If Phase is below manifest (no native module on disk yet), STOP — there's nothing scaffolded to test.

OS-neutral — run these checks with the built-in Read/Grep tools, not a shell. Every extraction/assert in this skill (the find / grep / sed / awk snippets below) is shown in bash for readability only — it describes what to match, not a shell to execute. RUN them with the agent's built-in Read and Grep tools (plus your own parsing), which behave identically on macOS, Linux, and Windows PowerShell. Do NOT shell out to grep/sed/awk/sort/find — they aren't on a stock Windows box, and Layers 0–3 are deliberately pure read+parse (no toolchain) so they run everywhere. Layer 4's npm run build is the only real command, and npm is cross-platform.

Step 2 — Confirm scope with the user

First, auto-detect whether the PCF companion is on disk — use the Grep tool (glob: pcf/**/ControlManifest.Input.xml) so case differences and minor layout variations don't trip the check. (Illustrative bash — don't run it verbatim on Windows):

PCF_MANIFEST=$(find pcf -type f -name "ControlManifest.Input.xml" 2>/dev/null | head -1)
[ -n "$PCF_MANIFEST" ] && PCF_PROJECT_ROOT=$(dirname $(dirname "$PCF_MANIFEST"))

If $PCF_MANIFEST is set, the PCF is scaffolded; use $PCF_PROJECT_ROOT (e.g. pcf/<Pascal>PCF) for Layer 4's build step. If empty, distinguish: no pcf/ at all → "not yet scaffolded"; pcf/ exists but no manifest → "scaffold appears incomplete; re-run /generate-pcf-companion or inspect the folder."

Also detect the manifest that drives Layer 2. Prefer the committed ./manifest.json (the source of truth /generate-native-extension writes at scaffold time, so it normally exists here, right after scaffold) and fall back to the staged build copy:

MANIFEST=$( [ -f ./manifest.json ] && echo ./manifest.json || ls ppmplugin/staging/manifest.json 2>/dev/null )

If $MANIFEST is empty, Layer 2 is skipped (no manifest on disk yet — a hand-authored module that hasn't run /generate-ppmplugin-manifest; with the scaffold, ./manifest.json is present from the start).

This drives Layer 4 (PCF compile) and Layer 5 (manual recipe — both require the PCF to exist).

Print:

Test plan
─────────
Repo: <cwd>
Extension: @powerapps/extension-<kebab>  (class <Pascal>Extension, module <Pascal>Module)
PCF companion: <found pcf/<Pascal>PCF/ | NOT yet scaffolded>
Manifest: <found ./manifest.json (committed) | ppmplugin/staging/manifest.json (staged) | NONE>

Automated layers (skill runs these and reports pass/fail):
  0. Holistic contract check — native ↔ manifest ↔ PCF cross-grep (warn-only)
  1. Native-source structure — getName()/+moduleName/@ReactMethod asserts + load/init readiness (no-arg package ctor, iOS [cls new]/requiresMainQueueSetup, non-throwing construction)
  2. Manifest validation     — <ppmplugin-format §4 rules | SKIPPED — no manifest>
  3. Native-source contract  — request/response/error grep cross-check
  4. PCF compile             — <npm run build in pcf/<Pascal>PCF | DEFERRED>

Manual layer (skill prints a recipe; you run it on a device on your own time):
  5. Device end-to-end       — <print recipe | DEFERRED>

Not validated by this skill: native iOS / Android compile into a loadable DEX / framework (run /build-android-binary // /build-ios-binary for that).

Stop on first failure: <yes by default>

Use AskUserQuestion:

Run the test plan?

• Run the default set above (recommended)
• Run only Layers 1–3 (skip PCF compile; skip the Layer 5 recipe)
• Run a single layer (specify which)
• Cancel

If the user picks a single layer, validate dependencies — e.g. "Layer 3 (contract asserts) is more useful after Layer 1 (structure asserts) has passed in this run or a recent run; do you want to skip the check and run anyway?". Don't enforce strictly; surface the implication and let the user decide.

Step 2.5 — Layer 0: Holistic contract consistency

Diagnostic layer, not a hard gate. Reports findings; downgrades to warnings rather than blocking. Useful for catching drift between native modules ↔ manifest.json ↔ PCF before the harder-to-debug runtime symptoms surface in Layer 5.

This layer cross-checks the contracts that flow across the native modules, the staged manifest.json, and the PCF. None of these checks compile or run code — they're all grep/parse-based. If any check finds a mismatch, the skill prints a numbered warning with the mismatched values + suggested fix, but continues to Layer 1 unless the user opts to stop. The point is to surface inconsistencies early; the engineer decides which ones matter.

What's checked

How it runs

For each check, the skill does a series of grep / read / compare ops:

# Example for check #1 (routing key)
PRD_CLASS=$(grep -oE "Class name \(Pascal\) \| .+" PRD.md | sed 's/.* | //')
MANIFEST_KEY=$(grep -oE '"name"\s*:\s*"[^"]+"' "$MANIFEST" | head -1)  # first receiver name ($MANIFEST = ./manifest.json or staged copy)
PCF_KEY=$(grep -oE 'ROUTING_KEY = "[^"]+"' pcf/${PRD_CLASS}PCF/${PRD_CLASS}PCF/index.ts)
# Compare; if mismatch, print:
#   ⚠️  Layer 0 check 1 (Routing key): manifest says '<X>', PCF says '<Z>'
#       Fix: align both to '<expected>'

For check #10 (unresolved native references), a heuristic grep flow:

# For each .kt file in android/, build the set of in-file definitions + imports,
# then for each call site, check membership.
for kt in $(find android/src -name "*.kt"); do
  IN_FILE_FUNS=$(grep -oE 'fun\s+[a-zA-Z_][a-zA-Z0-9_]*' "$kt" | awk '{print $2}' | sort -u)
  IMPORTS=$(grep -oE '^import\s+[a-zA-Z0-9_.]+(\.[a-zA-Z0-9_*]+)?$' "$kt" | awk '{print $2}' | awk -F. '{print $NF}' | sort -u)
  # Call sites: identifiers followed by `(`, excluding keywords + same-line definitions
  CALL_SITES=$(grep -oE '\b[a-zA-Z_][a-zA-Z0-9_]*\(' "$kt" \
               | sed 's/($//' \
               | grep -vE '^(if|when|while|for|return|require|listOf|arrayOf|mapOf|setOf|Pair|Triple|let|run|with|apply|also|takeIf|takeUnless)$' \
               | sort -u)
  # Flag any call site not in IN_FILE_FUNS or IMPORTS or known Android/Kotlin builtins
  ...
done

(Same pattern for .m / .swift with adjusted regexes for Obj-C selectors / Swift function declarations.) This is heuristic — won't perfectly distinguish member calls on imported types from undefined function calls — but catches the headline case (createTopNavBar() invoked with no fun createTopNavBar anywhere and no import that could provide it).

The skill runs all seventeen checks; aggregates findings; prints them as a numbered list at the end of the layer.

Pass

All checks agree across the native modules, the manifest, and the PCF. Print ✓ Layer 0 (contract consistency): pass — <ISO time>.

Warn (continues to Layer 1, doesn't fail the run)

One or more checks found mismatches. Print:

⚠️  Layer 0 (contract consistency): <N> warning(s)

1. Routing key mismatch:
   - manifest receivers[].name: '<Pascal>Extension'  ✓
   - pcf/.../index.ts uses: '<Pascal>'                ✗ — fix this
   Suggested fix: in pcf/<Pascal>PCF/<Pascal>PCF/index.ts line N, change ROUTING_KEY to "<Pascal>Extension"

2. Response field name mismatch:
   - ARCHITECTURE §4.2 expects: 'signatureBase64'
   - ios/.../Module.m emits key: 'result'  ✗ — should be 'signatureBase64'
   - android/.../Module.kt emits key: 'result'  ✗
   - pcf/.../index.ts reads: response.result.signatureBase64
   Suggested fix: ARCHITECTURE §4.2 and the native emit sites disagree. Either update the native modules to emit 'signatureBase64', or update ARCHITECTURE §4.2 + the PCF read to use 'result'.

...

The user decides whether to fix before continuing (re-run after fixing) or proceed to Layer 1 (acknowledging the drift). Use AskUserQuestion:

Layer 0 found contract inconsistencies. Proceed?

• Continue to Layer 1 — warnings recorded in .extension-state.md but don't block
• Stop here, fix the warnings first — exit; user re-runs after fixing

Fail (stops the run)

The hard-fail case is when a source file referenced by the check is missing entirely (e.g. no <Pascal>Module.kt under android/, no RCT<Pascal>Module.m under ios/). That's not contract drift — that's a missing artifact. Print ❌ Layer 0 (contract consistency): cannot proceed — <missing file> and STOP.

Step 3 — Layer 1: Native-source structure asserts

No tsc to run in this track — the control ships as a native binary, not a TS extension. Instead, grep/parse the native module source and assert it is shaped for the wrap runtime and the plugin's upload-compatibility checks. These are the same conformance asserts /build-android-binary and /build-ios-binary run before they compile (ppmplugin-format §5, §5b) — running them here surfaces a fixable-in-seconds mistake before a minutes-long build.

For Android (android/.../<Pascal>Module.kt):

• the module class extends ReactContextBaseJavaModule (the host loads it as a React Native module).
• override fun getName() returns the canonical-prefixed '<Pascal>Module' (ppmplugin-format §3) — and it MUST equal the manifest receivers[].nativeModule if a manifest is staged.
• at least one @ReactMethod fun <m>(...) is declared (a module with no @ReactMethod dispatches nothing).
• a ReactPackage is present (the createNativeModules registration the DEX needs — its FQN becomes entrypoints.android.packageClass).
• no @ReactModule annotation (that's the SDK-era registration path; the wrap host registers via the ReactPackage, not the annotation — its presence is SDK leakage that /audit-ppmplugin rejects).

For iOS (ios/RCT<Pascal>Module.h / .m):

• the header class declares <RCTBridgeModule>.
• No RCT_EXPORT_MODULE(...) macro is present; the .m declares + (NSString *)moduleName and its return string equals Android getName() and the manifest receivers[].nativeModule. The Obj-C class name equals entrypoints.ios.moduleClass.
• at least one RCT_EXPORT_METHOD(<m>:...) is declared, and the method names are a subset of the manifest receivers[].methods[].

Load & initialization readiness (crash-at-launch / won't-load asserts) — HARD gate

The single most-reported field failure is "the app doesn't install or crashes on launch" — and its root cause is almost always the plugin failing to load or the module throwing during eager construction, before any UI. Those are knowable from the source, so assert them here (Layer 1 stops on failure) rather than leaving them to the warn-only Layer 0 sweep or the post-build audit. Grounded in ppmplugin-format §5 (Android DEX load + eager construction) and §5b (iOS dlopen + [cls new]).

Android (android/.../<Pascal>Package.kt + the module):

• the ReactPackage class has a public no-arg constructor — NOT class <Pascal>Package(...) with a parameter list. The wrap runtime instantiates it via getDeclaredConstructor().newInstance(); an arg-ed constructor throws NoSuchMethodException and the plugin silently fails to load (Loaded 0 plugin package(s)). (The module itself may take ReactApplicationContext; the package must be no-arg.)
• the construction closure does not throw — scan the module constructor(s), init{} block(s), and property initializers (plus one level of private fns they call) for the definitive crash triggers: a bare Handler() / register*Callback(…, null) on a possibly Looper-less thread, or uncaught I/O / hardware acquisition. A throw here crashes the host at launch. (This is the elevated, hard-gated form of the Layer 0 #12 heuristic — Layer 0 warns broadly; Layer 1 blocks on the clear triggers.)

iOS (ios/RCT<Pascal>Module.{h,m}):

• the module class instantiates via [cls new] — no custom initializer that takes arguments (the player does NSClassFromString(moduleClass) → [cls new]; an arg-ed-only initializer means the module is skipped at load).
• + (BOOL)requiresMainQueueSetup returns NO (if declared). Returning YES forces main-thread setup at launch and, combined with any heavy/throwing init, stalls or crashes startup.
• init / +load do no throwing or heavy work — same eager-construction rule as Android; defer hardware/listeners to the first method call.

Pass

Print 🟢 ✓ Layer 1 (native-source structure): pass — <ISO time>. Continue to Layer 2.

Fail

An assert above fails. Surface the first 3 mismatches — each as <file>:<line> — <what's wrong>. Common classes + fixes:

1. Capture the relevant grep hits / misses.
2. Print the first 3 mismatches (most relevant) — not every grep line.
3. Suggest a fix per class:
   • Android getName() returns '<X>' but iOS +moduleName / manifest nativeModule is '<Y>' → the runtime symbols disagree. Align all three to the canonical-prefixed '<Pascal>Module' (ppmplugin-format §3). When the derived name hits a reserved prefix / denylist, rename per ppmplugin-format §4. If the Obj-C class name differs from entrypoints.ios.moduleClass, align the class or manifest entrypoint separately.
   • module does not extends ReactContextBaseJavaModule (Android) / does not declare <RCTBridgeModule> (iOS) → it won't register as a native module. Fix the class declaration.
   • no @ReactMethod / RCT_EXPORT_METHOD found → the module exposes nothing the host can call. Add the operation method(s) per ARCHITECTURE §4.
   • a @ReactModule annotation is present on the Android module → SDK-era leakage; remove it (the wrap host registers via the ReactPackage). This is a hard CRITICAL at /audit-ppmplugin time.
   • ReactPackage has an arg-ed constructor (class <Pascal>Package(...)) → the plugin loads 0 packages on device. Give it a public no-arg constructor (ppmplugin-format §5).
   • construction closure throws (Looper-less Handler(), register*(…, null), uncaught I/O in the ctor / init{}) → crashes the host at launch. Defer to lazy first-call init, pass Handler(Looper.getMainLooper()), wrap unavoidable init in try/catch.
   • iOS module has no no-arg init / requiresMainQueueSetup returns YES / init does heavy or throwing work → the module is skipped at dlopen load or stalls launch. Instantiate via [cls new], return NO from +requiresMainQueueSetup, and keep init cheap (ppmplugin-format §5b).
4. Update .extension-state.md: Native-source structure (Layer 1): fail — <timestamp>; Status: blocked; Blocked reason: <first mismatch>.
5. STOP. Do not run subsequent layers.

Step 4 — Layer 2: Manifest validation

Auto-skip only if no manifest was found ($MANIFEST empty per the detection in Step 2 — neither ./manifest.json nor a staged copy). Print ⊝ Layer 2 (manifest validation): SKIPPED — no manifest on disk (hand-authored module). Run /generate-ppmplugin-manifest first. Mark state as n/a. Continue to Layer 3. (With the scaffold, ./manifest.json exists from native-gen, so this layer normally runs right here.)

When a manifest is on disk ($MANIFEST — the committed ./manifest.json or the staged copy), re-run the plugin-maintained upload-compatibility checks locally against it — the same checks /generate-ppmplugin-manifest runs (ppmplugin-format §4). This cheap pre-flight catches common upload failures such as a mis-shaped name or nativeModule before any build. This layer defers to /generate-ppmplugin-manifest as the source of the rule set — it does not re-author the manifest, only validates the one on disk and points back at that skill to fix.

Pass

Print ✓ Layer 2 (manifest validation): pass — <ISO time>. Continue to Layer 3.

Fail

A rule in ppmplugin-format §4 is violated. Common classes + fixes:

Update state: Manifest validation (Layer 2): fail — <timestamp>; Status: blocked. STOP.

Scope note: this layer validates manifest.json only. The native source's shape is Layer 1; whether the binary it declares actually exists is /assemble-ppmplugin's reconcile gate; whether the built .ppmplugin loads on device is /audit-ppmplugin.

Step 5 — Layer 3: Native-source contract asserts

No tsc --noEmit fixtures to run in this track — there's no TS src/ and no src/types.ts whose shape a type-fixture could pin. Instead, this layer grep-cross-checks the request / response / error-code contract between the two native parsers (iOS .m, Android .kt) and the PCF, deriving the expected field set from ARCHITECTURE §4 (or, if no PRD, treating the native source as the source-of-truth). It's the deeper sibling of Layer 0's checks 4–6 — Layer 0 surfaces them warn-only as part of the holistic sweep; Layer 3 gates on them.

For each operation:

• request fields — the NSDictionary key reads in the iOS parser, the ReadableMap key reads in the Android parser, and the PCF's request.<field> build must reference the same field names (ARCHITECTURE §4.1). A field read on one platform but not the other = platform-specific INVALID_INPUT.
• response fields — the keys in the iOS successJsonWith: build, the Android successJson build, and the PCF's response.result.<field> reads must match (ARCHITECTURE §4.2).
• error codes — every code in ARCHITECTURE §5 must be emitted by at least one native site (iOS errorJsonWithCode:message:, Android errorJson(code, message)) and handled by the PCF setError (case or default).
• error message plumbing — the native error helpers must carry a message argument, the PCF's setError(code, message) must be two-arg and assign this.errorMessage, and the ControlManifest must declare the three standard diagnostic outputs (Status, ErrorCode, ErrorMessage) with getOutputs() returning them. This is what makes a field failure debuggable from Power Fx with no native console.

Pass

Print ✓ Layer 3 (native-source contract): pass — <ISO time>. Continue to Layer 4 (if running).

Fail

The most common failures here are a field read/emitted on one platform but not the other, or an error code declared in §5 that no native site emits.

Update state: Native-source contract (Layer 3): fail — <timestamp>; Status: blocked. STOP. Do not run Layer 4.

Step 5.5 — Layer 3.5: Mock-context runtime contract

No analogue in this track — always n/a. The mock-context runtime layer instantiated the TS extension class (new <Pascal>Extension(ctx)) and drove handleMessageAsync against minimal/full host-context shapes. The .ppmplugin ships no TS extension class, no handleMessageAsync, and no host INativeExtensionContext — dispatch goes straight to NativeModules.<nativeModule>.<method> over the wrap bridge (ppmplugin-format §2, §6). There is nothing to instantiate off-device.

The equivalent "does it actually run?" assurance for a native-only bundle lives in two places, neither of which this skill can do off-toolchain:

• does the native code compile into a loadable binary → /build-android-binary // /build-ios-binary (real Gradle / xcodebuild).
• does the built .ppmplugin load + dispatch on the wrap runtime → /audit-ppmplugin (the byte-scan + structure gate) and the Layer 5 device recipe.

Print ⊝ Layer 3.5 (mock-context runtime): n/a — native-only track has no TS extension class to instantiate (see /audit-ppmplugin + Layer 5). and continue to Layer 4.

Step 6 — Layer 4: PCF compile

Auto-skip if no ControlManifest.Input.xml was found under pcf/ (per the find-based detection in Step 2). Print ⊝ Layer 4 (PCF compile): SKIPPED — PCF not yet scaffolded. Run /generate-pcf-companion first. Mark state as n/a. Continue to Layer 5.

This layer compiles the Companion PCF — manifest XML + index.ts + any engineer customizations. Catches:

• TS errors in index.ts (introduced by hand-edits after scaffold)
• Property name mismatches between ControlManifest.Input.xml and index.ts (e.g. manifest declares PenColor but the code references p.penColor)
• Missing output property declarations (e.g. §8.3 was edited but the PCF wasn't regenerated)
• Broken pcf-scripts deps

The PCF tooling uses npm, not pnpm — this is a PCF ecosystem convention. Do not unify.

Run

From the repo root:

macOS / Linux / Windows (same command):

cd "$PCF_PROJECT_ROOT"   # from the find-based detection in Step 2
[ -d node_modules ] || npm install --no-audit --no-fund   # first time only; ~30s
npm run build --silent

Notes:

• npm install only runs on first invocation (or if node_modules/ was wiped). Subsequent runs are seconds because pcf-scripts build is fast on warm caches.
• --silent keeps the output tight; errors still print.
• npm run build runs pcf-scripts build, which:
  1. Regenerates pcf/<Pascal>PCF/<Pascal>PCF/generated/ManifestTypes.d.ts from the manifest XML.
  2. Type-checks index.ts against the regenerated ManifestTypes.d.ts.
  3. Bundles output to pcf/<Pascal>PCF/out/.

Pass

npm run build exits 0 and emits out/ artifacts. Print ✓ Layer 4 (PCF compile): pass — <ISO time>.

Fail

npm run build exits non-zero. Common error classes:

Update state: PCF build (Layer 4): fail — <timestamp>; Status: blocked. STOP. Do not run Layer 5.

Step 6.5 — Layer 4.5: Android lint

Catches the "the Android build rejects this module on lint" class of bug locally. Real cost on pen-input: 8 Android lint warnings surfaced only when the integration build ran, forcing a patch round-trip.

…(truncated)