/add-geolocation

name: add-geolocation
description: Internal implementation skill invoked by /add-native for native background GPS tracking with durable storage and Dataverse sync using @microsoft/power-apps-native-bglocation.
user-invocable: false
disable-model-invocation: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion
model: sonnet

**Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** - read first.

**Working directory:** before any project read or command, execute [native-artifact-compatibility.md Step 0](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md#0-bind-every-operation-to-the-app-root). Inherit `/add-native`'s resolved absolute `working_dir`; bind every shell call and file tool to it, even when this helper starts from another directory.

Add Geolocation

Internal helper for `/add-native geolocation`, `/add-native location-tracking`, `/add-native background-location`, `/add-native gps-tracking`, and `/add-native @microsoft/power-apps-native-bglocation`.

Use this only for continuous/background GPS tracking with native durable storage and inline Dataverse upload. For a single foreground coordinate read, use `/add-native location` (`expo-location`) instead.

Hard rules:

• Auth is MSAL-only. Do not expose OneAuth or an auth selector.
• Use `geoService(dataSource, app_id)` and `BgLocationClient`.
• Do not use `GeolocationExtension`, HostingSDK, PCF, Launch URI, or CordovaV2 bridge paths.
• Do not install packages or edit native config.
• The control is not usable until its Dataverse target table and mapped columns are verified.

1. Verify app and package

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f app.config.js && test -f power.config.json && test -f package.json && test -d src || { echo "BLOCKED: working_dir is not an initialized app" >&2; exit 1; }
node -e "const p=require('./package.json'); const m='@microsoft/power-apps-native-bglocation'; if (!p.dependencies?.[m]) { console.error('MISSING: ' + m); process.exit(1); } console.log('OK: geolocation package present');"

If either check fails, stop. The template/app must already ship the native package.

2. Verify the Dataverse target table first

This control uses the package default Dataverse entity set:

msdyn_locationrecords

Do not ask the user for a table name and do not invent a custom table. `msdyn_locationrecords` must already exist before the control can be used.

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
ENV_JSON=$(node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$(node -e "console.log(require('./power.config.json').environmentId)")")
ENV_URL=$(node -e "const j=JSON.parse(process.argv[1]); process.stdout.write(j.environmentUrl || '')" "$ENV_JSON")

TABLE="msdyn_locationrecords"
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "$ENV_URL" GET \
  "EntityDefinitions?\$filter=EntitySetName eq '$TABLE'&\$select=LogicalName,EntitySetName"

Required result:

• One row returned: capture `LogicalName` and verify columns.
• Empty `value: []`: stop. Mark `BLOCKED (target table missing)`. Do not create the table, do not route to `/add-dataverse`, and do not report the control as usable. Tell the user to run the geolocation-control table provisioning/setup mechanism, then re-run `/add-native geolocation`.
• Auth/environment error: stop. Mark `UNVERIFIED (target table not checked)`. Do not report the control as usable.

When the table exists, verify every mapped column exists:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "$ENV_URL" GET \
  "EntityDefinitions(LogicalName='<logicalName>')/Attributes?\$select=LogicalName,AttributeType"

Required default `fieldMap` columns from the package README:

msdyn_locationrecordid, msdyn_appid, msdyn_latitude, msdyn_longitude,
msdyn_altitude, msdyn_accuracy, msdyn_heading, msdyn_speed, msdyn_timestamp

If any active `fieldMap` column is missing, stop. Mark `BLOCKED (target columns missing)` and tell the user to fix the control table through the geolocation-control table provisioning/setup mechanism.

2a. Reconcile requested artifacts

Read and execute [native-artifact-compatibility.md](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md) Steps 1–3 for the geolocation row before any writes or reuse. Inherit the current approval/mode from `/add-native`; do not repeat a valid scoped approval. Inspect `src/native/geolocation.ts` for all requested tracking/status/location exports, `GeoTrackingTarget`, MSAL-only `geoService`/`BgLocationClient`, required `connectionUrl`/`trackInBackground`/`persistAcrossRestarts`, durable storage, and Dataverse sync. Reuse Step 2's verified `msdyn_locationrecords` columns; one-shot location or a wrapper targeting another table is not compatible. An incompatible artifact outside approval returns `NEEDS_CONTEXT` to the owner, or asks standalone; missing table/columns remain `BLOCKED`, never a usable-control success.

3. Write `src/native/geolocation.ts`

Apply Step 2a's decision for `src/native/geolocation.ts`: create when requested and missing, reuse unchanged only if compatible, or make only the approved scoped update. Preserve custom code, exports, and callers; do not overwrite from the example. Screens import this wrapper, not the package directly.

The target config must require the README's two tracking flags:

• `trackInBackground: boolean`
• `persistAcrossRestarts: boolean`

// src/native/geolocation.ts
import {
  geoService,
  BgLocationClient,
  AuthMethod,
  ConnectionType,
} from '@microsoft/power-apps-native-bglocation';
import type {
  DataverseDataSource,
  LocationData,
  PermissionStatus,
} from '@microsoft/power-apps-native-bglocation';

export type { LocationData, PermissionStatus } from '@microsoft/power-app