Add Table To Offline Profile

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

References:

• dataverse-offline-api.md §4 + §7 — POST item + PATCH selectedcolumns
• offline-profile-reconciliation.md — the schemaColumns baseline written in Step 7

Add Table to Offline Profile

Add a single table to an existing Mobile Offline Profile. Most common flow: user ran /add-dataverse to add a new table to their app, now wants that table available offline too.

Equivalent to running /setup-offline-profile and seeing the existing profile (extend-mode), but skips the per-table questionnaire for the tables already in the profile — only configures the new one.

Invocation context and root binding

This internal helper is always a child invocation. Before any project read or command, execute app-working-directory.md. Require the owner's absolute working_dir; --working-dir, when supplied, must identify that same native-canonical root. Missing, relative, or conflicting root context returns NEEDS_CONTEXT before project access; an inaccessible directory is BLOCKED. Never use the launch cwd or introduce another root resolver.

Receive MOBILE_APP_ORCHESTRATING=1, orchestrator, working_dir, phase, approved_scope, and supplied answers from the owner. Keep the selected environment ID/URL/tenant, profile ID, exact table allowlist, and approved operations unchanged. Missing or conflicting scope returns NEEDS_CONTEXT; do not substitute another environment, profile, or table. The marker is not approval: schema approval alone does not authorize offline prerequisite changes, profile items, relationships, columns, publication, deletion, or membership edits. Reuse only the same current offline approvals; otherwise retain Steps 3–4's gates. For --plan-only or a planning-phase handoff, return a proposal after permitted read-only discovery, before any prerequisite update, profile mutation, publish, or artifact write. A gate response cannot lift proposal-only mode.

Apply the canonical contract to every shell call and file tool, including version/auth checks, row counts, screen greps, commands copied from references, verification, recovery, and retries. Re-supply the absolute PLUGIN_ROOT and required context on each call; no prior cd, export, or shell variable persists. Use the canonical Bash guard below or its PowerShell equivalent. Replace placeholders with validated, shell-quoted invocation values; missing values return NEEDS_CONTEXT, never execute an unresolved placeholder. File tools use absolute <working_dir>/... paths; plugin reads/scripts use ${PLUGIN_ROOT}/.... Resolve manifest location once within this root and keep that absolute path; never search another app when a file is absent.

Workflow

1. Verify project + locate profile → 2. Resolve target table → 3. Prereq check (auto-enable if needed) → 4. Scope picker (single question) → 5. POST item + PATCH selectedcolumns → 6. Publish → 7. Update artifacts → 8. Summary

Step 1 — Verify project + locate profile

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
if [ ! -f power.config.json ] || [ ! -f app.config.js ]; then
  echo "BLOCKED: working_dir is not an initialized app" >&2
  exit 1
fi

Read <working_dir>/power.config.json and require a nonempty environmentId matching the owner's selected environment. Reuse matching complete environment context, or perform this non-persisting lookup from the bound root:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
environment_id=$(node -p "require('./power.config.json').environmentId || ''") || {
  echo "BLOCKED: unreadable power.config.json" >&2; exit 1;
}
if [ -z "$environment_id" ] || [ "$environment_id" != "<selected-environment-id>" ]; then
  echo "NEEDS_CONTEXT: selected environment does not match working_dir" >&2
  exit 1
fi
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$environment_id" --no-cache --require-tenant

Require the returned environment ID, HTTPS URL, and tenant to match the owner; incomplete or conflicting context returns NEEDS_CONTEXT. Never drop --no-cache --require-tenant, change configuration, or switch auth/environment to recover a failure. Use that exact <envUrl> and <tenantId> for every request.

Manifest path (dual-location, both within the bound root):

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
if [ -f .datamodel-manifest.json ]; then
  printf '%s\n' '<working_dir>/.datamodel-manifest.json'
elif [ -f docs/plan-artifacts/.datamodel-manifest.json ]; then
  printf '%s\n' '<working_dir>/docs/plan-artifacts/.datamodel-manifest.json'
else
  echo "NEEDS_CONTEXT: no manifest in working_dir" >&2
  exit 1
fi

Read the profile from <working_dir>/offline-profile.json or the owner's explicit --profile-id, using /edit-offline-profile's resolution rules inline. Verify it matches the owner's profile and the live profile in the selected environment. A conflicting snapshot/argument, 404, or permission failure is not permission to pick a different profile; return NEEDS_CONTEXT for conflict or BLOCKED for access failure. Do not execute the edit workflow just to locate a profile.

STOP if no profile exists. Recommend: Run /setup-offline-profile first to create the profile.

Step 2 — Resolve target table

$ARGUMENTS parsing:

An explicit --table must match the owner's allowlist. Conflicting selection returns NEEDS_CONTEXT. For bulk --all-new mode, loop through Steps 3–7 for each approved missing table; each runs sequentially because Dataverse profile-item POSTs serialize. Every iteration keeps the same root/environment/profile context.

Step 3 — Prereq check (auto-enable if needed)

Query the target table's EntityMetadata:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "<envUrl>" GET \
  "EntityDefinitions(LogicalName='<table>')?\$select=IsAvailableOffline,ChangeTrackingEnabled,OwnershipType,IsCustomizable" \
  --tenant-id "<tenantId>"

After approval, execute the helper for this table only with the resolved tenant. --tenant-id binds both initial authentication and 401 refresh; never rely on ambient tenant variables for this prerequisite mutation.

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/update-entity-offline-flags.js" "<envUrl>" \
  --table "<table>" --offline true --tracking true --tenant-id "<tenantId>"

Check the returned HTTP status, not just process exit. A 403/PrivilegeCheckFailed is BLOCKED; do not change identity or profile to bypass permissions. After a successful change, issue the approved prerequisite publication:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "<envUrl>" POST \
  "PublishXml" --tenant-id "<tenantId>" --body '{
    "ParameterXml": "<importexportxml><entities><entity><table></entity></entities></importexportxml>"
  }'

Publish only this helper's changed prerequisite table. Do not use PublishAllXml unless the owner separately approves publishing all pending environment customizations; table-only approval does not cover that fallback.

No prerequisite mutation or publication is allowed in proposal-only mode.