add-sample-data

> **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](${PLUGIN_ROOT}/shared/shared-instructions.md)** — read first. # Add Sample Data **App root:** before any project read or command, execute [app-working-directory.md](${PLUGIN_ROOT}/shared/references/app-working-directory.md). Use its resolved absolute `working_dir` for every shell call and file tool, including media paths and retries; never inherit a prior `cd`. Populate Dataverse tables with realistic sample records so a freshly-scaffolded code app shows real-looking data on first launch. Generates rows from each table's schema and inserts them in dependency order. Use after `/add-dataverse` (or `/setup-datamodel`) has created the tables. ## Core principles - **Coverage within approved scope, not the entire manifest.** Cover each eligible approved table with a small useful dataset. The manifest is verified app inventory and can include retiring or unrelated tables; its presence is not permission to seed them. Scope and retirement exclusions override every coverage, fanout, prototype-reuse, media, and retry rule below. - **Insertion order matters.** Parent / referenced tables must be inserted before child / referencing tables so lookup IDs are available. - **Contextual data, not Lorem Ipsum.** Generate values that match column names + types. A `cr3e9_sitename` column in an inspection app gets "Westside Construction Site", not "Sample Name 1". - **Scenario-aware rows.** Read `native-app-plan.md` when present, especially `### Shared Conventions` and per-screen `Operational pattern` values defined in [screen-templates.md](${PLUGIN_ROOT}/shared/references/screen-templates.md); otherwise use the current data request and verified schema. Seed rows should exercise the app's actual workflow: statuses, dates, relationships, priority/severity, media metadata, and edge cases that make the planned first viewport light up. - **Fail gracefully.** On insertion failure, log the error and continue with remaining records — never auto-rollback. The user can re-run after fixing the issue. - **Idempotent re-runs.** If a previous run partially completed, the second run reads `memory-bank.md`'s seeded-data table and skips records already inserted. - **Solution-scoped inserts.** Always pass `--solution <uniqueName>` so records land in our solution, not the default. ## Workflow 0. Resolve approved seed scope → 1. Verify project + auth → 2. Discover scoped tables → 3. Select tables + count → 4. Generate + preview → 5. Insert → 6. Summary ### Step 0 — Resolve approved seed scope Inputs are skill arguments, not flags for `dataverse-request.js`: - `--working-dir <absolute-root>`: inherit the caller's root; reject conflicting explicit/inherited roots. Never default to shell cwd in a nested invocation. - `--tables <comma-separated-logical-names>`: the exact approved seed-table allowlist. Required for every orchestrated call, including fresh creation. - `--exclude-tables <comma-separated-logical-names>`: retiring table names from the approved edit; omit or pass an explicit empty string only when none retire. For an orchestrated call, require the scoped handoff and matching `--tables` before auth, record-count queries, or generation. A missing or malformed allowlist returns `NEEDS_CONTEXT`; never fall back to all manifest tables. An explicitly empty allowlist is a no-op: report no approved seed tables and return without cloud calls or writes. Validate logical names against the manifest and the approved plan/caller scope. Build `retiringTables` from the caller's retirement set plus any pending removals recorded in the current plan/history; include these in `--exclude-tables`. If an allowlisted name is absent/unverified or overlaps `retiringTables`, stop before insertion and return the scope mismatch. Do not silently drop unknown names or infer permission from a transitional manifest entry. For a standalone request, honor explicit `--tables` and exclusions. If no table list was supplied, discover candidates in Step 2 and ask the user to approve the specific table set/counts before Step 5, then freeze that selection as `seedTables`. For this standalone discovery path, validate against verified metadata when the local manifest is absent; never treat the discovery result itself as approval. Pending retirement always excludes a candidate; if that state is unclear, ask rather than treating the manifest as approval. Read-only fallback discovery is not permission to seed the environment. Keep a fixed `seedTables` allowlist throughout the invocation. All later selection, batches, media jobs, and resume operations must remain within it. Do not edit `.datamodel-manifest.json` or the app plan to make an excluded table eligible. Expanding scope requires returning to the owning approval gate. For `--plan-only` or a planning-phase handoff, use the supplied proposed table scope for read-only checks and return the proposed counts, dependency needs, and media policy before Step 5. Planning approval is not insertion approval. Do not generate media files, insert/update/upload records, or change the app plan, manifest, or seeded-data history on this path. ## Prototype Seed Reuse `--from-seed` is used by `/prototype-to-real-app` after a mock prototype is converted to Dataverse. In this mode, prefer existing prototype seed files before generating new rows: ```text src/generated/services/*/*.seed.json src/generated/services/*.seed.json ``` Map only `seedTables` objects to Dataverse payloads using `.datamodel-manifest.json`; prototype seed files cannot widen the approved set: - Keep values only for real manifest columns. - Translate lookup references into exact `<schemaName>@odata.bind` keys from the manifest. - Keep picklist integers from the manifest; do not invent values from labels. - Skip local-only prototype fields that have no Dataverse column. - Preserve dependency-tier insertion order. If a seed file cannot be mapped safely, fall back to generated contextual sample rows for that table and record `DONE_WITH_CONCERNS` in the summary. `--from-seed` is a preference, not permission to insert malformed data. --- ### Step 1 — Verify project & auth Run app-local commands from the resolved `working_dir` in each shell call. ```bash 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 environment_id="$(node -p "require('./power.config.json').environmentId || ''")" || exit 1 if [ -z "$environment_id" ]; then printf '%s\n' 'ERROR: selected app has no environmentId' >&2 exit 1 fi node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$environment_id" --no-cache --require-tenant ``` Capture the **environment URL**, **environment ID**, and **tenant ID** for subsequent script calls; require a match with the selected app and any supplied owner context. Incomplete or conflicting identity returns `NEEDS_CONTEXT` after bounded read-only recovery. Do not remove the safety flags, select another environment, or persist resolver output to recover. Bind every subsequent Dataverse read, batch, PATCH, media upload, token refresh, and retry to that exact environment URL and tenant ID. For each `dataverse-request.js` invocation, pass `--tenant-id '<tenantId-from-resolve-environment>'` explicitly; substitute the validated Step 1 value again in every fresh shell call. Do not depend on a previous shell export, challenge discovery, or the active Azure CLI tenant. Missing or conflicting tenant context returns `NEEDS_CONTEXT` before the call. Verify Azure CLI auth (the script needs an Azure CLI token): ```bash cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } az account show --query "user.name" -o tsv ``` If empty, instruct `az login` and stop. ### Step 2 — Discover tables **Telemetry checkpoint: `discover_dataverse_tables`** #### Step 2a — Path A: read `.datamodel-manifest.json` (preferred) ```bash cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } test -f .datamodel-manifest.json ``` If present, parse the JSON. It contains `logicalName`, `displayName`, `status` (`new` / `extended` / `reused`), and `columns` for the verified app inventory. **This is the preferred path** -- fast, no API calls. For scoped calls, take only the validated `seedTables` entries before any per-table metadata/count query. For standalone discovery, exclude retiring tables from the candidate list. Keep unrelated manifest entries as inventory only; do not pass them to the record-count, generation, or insertion loops. Skip Step 2b. #### Step 2b — Path B: query OData (fallback) If `.datamodel-manifest.json` is missing in an orchestrated call, return `BLOCKED` to the owner for verified inventory recovery; do not broaden discovery or invent schema facts. For a standalone request with an explicit allowlist, fetch metadata only for those logical names. The following broad discovery is for a standalone request without a table list, to propose candidates for approval: ```bash cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \ "EntityDefinitions?\$select=LogicalName,DisplayName,EntitySetName&\$filter=IsCustomEntity eq true" \ --tenant-id '<tenantId-from-resolve-environment>' ``` For each candidate that the project uses (or each explicitly scoped table), fetch its custom columns: ```bash cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \ "EntityDefinitions(LogicalName='<table>')/Attributes?\$select=LogicalName,DisplayName,AttributeType,RequiredLevel&\$filter=IsCustomAttribute eq true" \ --tenant-id '<tenantId-from-resolve-environment>' ``` Build the same `{ logicalName, displayName, columns: [...] }` shape the manifest provides. ### Step 3 — Select tables + count Evaluate only the validated seed allowlist, including reused tables only when they are explicitly in that set. For standalone discovery, use only the proposed non-retiring candidates and obtain the selection approval before insertion. Never seed standard system tables (e.g. `contact`, `account`, `systemuser`) without the additional explicit shared-environment confirmation below. **Pre-seeding row-count check (HARD — runs for every table before generating any rows):** For each scoped table, query its current record count using the verified entity set name from the manifest, or fetch that name from metadata as in Step 5a. Never derive it by appending `s` to a logical name. ```bash cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \ "<entitySetName>?\$top=5&\$select=<primaryKeyColumn>" \ --tenant-id '<tenantId-from-resolve-environment>' ``` Count the rows returned in the `value` array. | Existing record count | Action | |---|---| | **≥5** | **Skip this table entirely.** Log: `↷ <table> (≥5 records exist, skipping)`. Do not generate or insert any rows. | | **<5** | Seed enough new rows to reach the per-class target count. If some records already exist (e.g. 2), generate only the gap (e.g. 3 more to reach 5). | If all eligible selected tables already have ≥5 records, report that nothing in the approved seed scope needs seeding and stop. **Per-table count by class** (classify each table from manifest signals before generating; this beats a uniform `5` because reference tables don't need volume and transactional tables need state spread): | Class | Heuristic | Default count | Rationale | |---|---|---|---| | **Reference** | No `status` / `state` column; columns are descriptive (name, address, phone). Often Tier 0. | **3** | Stores, customers, sites, products. Small stable set. | | **Junction** | Two-or-more lookups, no other meaningful columns. Often Tier 1. | **3 × parent count, capped at 9** | Store-Assignment, Project-User. Needs to span the join. | | **Transactional** | Has a `status` / `state` / `phase` choice column AND a date column (`createdon`, `submittedat`, `completedat`). | **5** | Audits, inspections, orders, tickets. Need state mix to make tiles light up. | | **Detail / line-item** | Lookup back to a transactional parent, no own state column. | **2-3 per parent** | Audit zones, order line items, inspection findings. | | **Issue / finding** | Lookup back to a transactional parent + has `status` (Open / Resolved) AND severity (Critical / Moderate / Minor). | **3-4 per transactional parent** | Issues, defects, observations. Mix severities + statuses (see Step 4a). | | **Evidence / attachment** | Has a File / Image column + lookup to issue/inspection. | **1 per ~30% of parents** | Photo evidence, document uploads. Seed metadata rows by default; seed file/image bytes only when `brand/media-policy.md` or the user's request says sample media is needed. | | **Log / event / audit-trail** | Append-only with `eventtype` enum + timestamp + actor lookup. | **2 per transactional parent** | Audit log events, activity stream. Mix at least 2 event types per parent. | | **Override / approval** | Lookup to transactional parent + status (Pending / Approved / Rejected). | **1 per ~20% of parents** | Override requests, approval queue. At least 1 row in `Pending` so queue tab shows content. | Counts are intentionally minimal. Goal: every screen has SOMETHING to render, not a demo dataset. Print a one-line summary and continue: > `→ Seeding <total> records into <N> tables (coverage-first; counts auto-tuned per class).` #### Step 3b — Determine insertion order For the selected tables, build a dependency graph from lookup columns: 1. Tables with no lookups out → Tier 0 (insert first) 2. Tables with lookups only to Tier 0 → Tier 1 3. Continue until all selected tables are tiered If a selected table references an UNSELECTED parent, reuse a verified existing parent record through a bounded read when that lookup is within the approved feature. Reading a lookup parent is not permission to insert/update it. If no suitable record exists, return `NEEDS_CONTEXT` to the owner (or ask standalone) to extend the seed scope or explicitly omit an optional lookup. Never auto-add a parent to `seedTables`, create a retiring parent, or omit a required lookup. Retiring lookup targets block that dependent seed until the plan is reconciled. ### Step 4 — Generate sample data + preview **Telemetry checkpoint: `generate_and_review_sample_records`** #### Step 4a — Generate contextual rows For each selected table, generate N rows. Match values to column names + types: | Column type | Generation approach | |---|---| | **String** | Match the column name's semantic. `*name`, `*title` → realistic names from the requirements brief context. `*email` → `firstname.lastname@example.com`. `*phone` → `(555) 123-NNNN`. `*address` → realistic street + city. Otherwise: short context-appropriate text. | | **Memo (multi-line text)** | 1-3 sentences relevant to the column name (e.g. `*notes`, `*description`). | | **Integer / Decimal / Currency** | Reasonable range based on column name. `*amount`, `*price` → realistic dollars. `*count`, `*quantity` → small integers (1-100). | | **DateTime / DateOnly** | Recent ISO dates spanning past 30 days to next 14 days. Vary across rows. | | **Boolean** | Mix true/false (~70/30 favoring true for `is_active` style names). | | **Choice (Picklist)** | **Query options first** (Step 4b), then pick from valid integer values. | | **MultiSelect Choice** | Pick 1-3 valid values per row from the option set. | | **Lookup** | Reference a verified existing parent or one inserted within the approved seed scope. Track live parent GUIDs; never seed an unapproved parent just to satisfy a child. | | **Image / File** | Default: skip — leave null. If media seeding is enabled and the column is business data (product image, inspection evidence, NC proof), use generated/synthetic local files from `assets/sample-*` and record provenance. Never upload decorative UI hero assets to Dataverse. | **Media seeding policy (business data only, only if needed):** - Default: do not seed binary media. Seed metadata rows and leave Image/File columns null unless the screen plan or user request requires visible sample media. - Seed Dataverse images/files only when the image belongs to a record users inspect in list/detail screens: product photos, evidence, attachments, signatures, issue proof. Do NOT seed Home hero, splash, app icon, empty-state art, or decorative detail backgrounds. - Prefer generated/synthetic assets with no logos, no real product labels, no faces, no watermarks, and no competitor branding. If the user supplies approved assets, use those and record their source. - CDN URLs are valid only for explicit URL/Text columns (e.g. `imageurl`, `photourl`). Do not put CDN URLs into File/Image columns. - Dataverse Image columns receive base64 in the row payload or generated service shape. Dataverse File columns require a second upload step after the metadata row exists. - For product/channel apps, product images are core sample data when product list/detail screens are visual, but they are capped. Generate and upload only a representative subset; use local placeholders or null image fields for the rest. - Maintain `assets/images/asset-manifest.json` or `assets/sample-media/asset-manifest.json` with file, purpose, source/license, and safety notes. **Media volume limits (HARD):**