@linked365/pptb-mockaroo-data-munger 0.3.1 → 0.4.0

package/IMPLEMENTATION.md

@@ -0,0 +1,75 @@
+# Implementation Notes
+
+This React/Vite tool runs inside Power Platform ToolBox. `App.tsx` composes the active connection, ToolBox APIs, Dataverse service, and UI. Dataverse metadata and record creation are isolated in `src/utils/dataverse.tsx`; Mockaroo generation is in `src/utils/mockaroo.tsx`; shared record-count and batch logic is in `src/utils/bulkOperations.ts`.
+
+The manifest requires Power Platform ToolBox 1.2.7 or later through `features.minAPI`.
+
+## Data-write safety
+
+- Both direct table creation and dataset execution require explicit confirmation that names the active environment and target table(s), scope, and record counts.
+- The dataset review captures the selected connection, dataset order, configuration contents, and per-table row counts. Applying the review checks that the active connection and saved dataset/configurations have not changed.
+- Record generation and creation are capped at 1,000 records per table/step. Dataverse requests are sent in batches of 100, with at most three batches in flight.
+- Successful record IDs are retained for counting. Failures report confirmed successful batches; there is no automatic rollback.
+- Each batch rechecks the active connection before it is sent.
+
+## External service and privacy
+
+Mockaroo generation uses `https://api.mockaroo.com` and is declared as a `connect-src` CSP exception in `package.json`. The API key and generation schema/configuration are sent to that endpoint. Existing Dataverse records and generated values are not logged by the tool.
+
+## Tests
+
+- `tests/model/*.test.ts` covers model initialization, configuration serialization, and saved-setting keys.
+- `tests/utils/*.test.ts` covers record limits, bounded batch execution and partial failures, Dataverse payload conversion/connection checks, Mockaroo requests and response handling, and notifications.
+- `tests/hooks/*.test.ts` covers ToolBox connection/event/log hook behavior with mocked host APIs.
+- `tests/components/DatasetTab.test.tsx` covers saved-config rendering with light and dark Fluent themes.
+- `tests/components/MockarooMain.test.tsx` covers the dataset creation review warning message and the header's record total, alignment, and matching text size.
+- `tests/testHelpers.ts` contains shared mocked ToolBox API setup.
+- UI interaction and live Dataverse acceptance remain manual checks inside Power Platform ToolBox; this repository does not launch the tool in a standalone browser for those checks.
+
+Commands:
+
+- `npm test` — run all automated tests.
+- `npm test -- tests/components/DatasetTab.test.tsx` — run saved-config theme regression tests.
+- `npm test -- tests/components/MockarooMain.test.tsx` — run dataset review header and warning tests.
+- `npm test -- tests/utils/bulkOperations.test.ts` — run the batch and record-limit tests.
+- `npm run build` — type-check and create the production bundle.
+- `npx pptb-validate` — validate the package manifest and distribution metadata.
+
+## Manual testing checklist
+
+Run these checks inside Power Platform ToolBox against a disposable development or sandbox Dataverse environment, not production. Use synthetic data, check for plug-ins or flows triggered by record creation, and plan cleanup: the tool has no automatic rollback. Leave items unchecked until a person has verified the result; automated tests and screenshots alone do not complete this checklist.
+
+### Setup and appearance
+
+- [x] Load the final packaged build in PPTB 1.2.2 or later; record the tool version, PPTB version, tester, date, and test environment.
+- [x] Verify light and dark themes, including switching themes while the tool is open. Confirm readable grids, saved-config lists, dataset order, dropdowns, and dialogs.
+- [x] Check keyboard navigation, visible focus, scrolling, and dialog actions at typical and narrow window sizes.
+- [x] Confirm opening the tool, selecting a table, generating a preview, and cancelling confirmation do not create Dataverse records.
+
+### Configuration and generation
+
+- [x] Save and reload configurations and datasets, including after closing and reopening the tool; verify field settings, row counts, and dataset order are preserved.
+- [x] Verify generated text, numeric, date, boolean, choice, and lookup fields, plus fixed-value-only configurations without a Mockaroo key.
+- [x] Test missing/invalid API keys, Mockaroo request failures, and missing required choice/lookup selections. Confirm actionable errors and no unintended writes.
+- [x] Test lookup searches with matches, empty results, and apostrophes; verify the selected record is used.
+- [x] Test row counts of 1 and 1,000, and confirm invalid counts (0, negative, fractional, or above 1,000) are rejected.
+- [x] Verify generated row counts match the request. Confirm an empty, malformed, or count-mismatched Mockaroo response prevents dataset writes; mark this blocked if it cannot be safely exercised.
+
+### Record creation and datasets
+
+- [x] Review and cancel direct creation, then confirm a small run. Verify the displayed environment, table, and count match the actual created records and field values.
+- [x] Run an ordered dataset across multiple tables. Verify review totals, the right-aligned header total, yellow warning box, execution order, and per-table results.
+- [x] Review a dataset with missing configurations or unavailable tables; confirm skipped-step warnings and that a dataset with no runnable steps cannot proceed.
+- [x] Change a saved configuration or dataset after review; verify creation is blocked until reviewed again.
+- [x] Change or remove the active connection after review; verify writes are blocked rather than sent to the wrong environment.
+- [x] Exercise a 1,000-record step and a realistic multi-step dataset; verify responsiveness and successful counts against Dataverse.
+- [x] Safely induce a later batch or step failure; verify confirmed successful counts, explicit partial-failure reporting, and that previously created records remain.
+- [x] Test missing read/create permissions and an expired or disconnected session. Confirm errors are surfaced without reporting success.
+
+### Privacy and completion
+
+- [ ] Inspect requests and logs using synthetic inputs: confirm external requests only use the declared Mockaroo endpoint, lookup GUID handling matches the privacy disclosure, and API keys/generated values are not written to application logs.
+- [ ] Verify failures to save settings are reported accurately and do not falsely claim that an API key, configuration, or dataset was saved.
+- [ ] Inspect created records and any triggered automation, clean up test data, and record pass/fail/blocked results with redacted evidence. Resolve failures before submission.
+
+See the [user guide](./README.md).

package/README.md

@@ -1,17 +1,70 @@
+![Mockaroo Data Munger banner](./assets/mockaroo-data-munger-banner.png)
+
 # Mockaroo Data Munger
 
-A tool to mock data from Mockaroo into your Dataverse tables
+Generate synthetic records with Mockaroo and create them in Dataverse. Configure fields for a table, preview the generated rows, and explicitly confirm before writing. Saved configurations can also be run as ordered datasets across multiple tables.
+
+## Requirements
+
+- Power Platform ToolBox 1.2.7 or later with an active Dataverse connection.
+- A Mockaroo API key for configurations that use Mockaroo-generated fields. Fixed-value-only configurations do not need a key.
+- Permission in the connected environment to create records in the selected tables.
+
+## Use the tool
+
+1. Select a Dataverse table and configure which columns to include and how to generate their values.
+2. Enter your Mockaroo API key if the configuration uses Mockaroo fields, and choose a row count from 1 to 1,000.
+3. Generate the data and review the resulting rows in the Data tab.
+4. Choose **Create Data** and review the target environment, table, and record count. Confirm only if the target is correct.
+5. To create data across several tables, save configurations, arrange them in a dataset, then choose **Review Dataset**. Review the environment, table-by-table counts, and any skipped steps before confirming.
+
+Dataverse record creation has no automatic rollback. If a multi-batch or multi-step run fails, previously successful batches or steps may remain in Dataverse. The tool reports confirmed successful record counts; inspect the target environment before retrying.
+
+## What this tool changes
+
+- Reads table and column metadata and lookup/choice values from the active Dataverse connection.
+- Creates new records only after an explicit confirmation. A dataset can create records in each configured table; each step is limited to 1,000 records.
+- Saves the Mockaroo API key, saved configurations, and datasets in Power Platform ToolBox tool settings.
+- Does not update or delete existing Dataverse records.
+- Does not automatically roll back records created by a successful batch or dataset step if a later operation fails.
+
+## Privacy and network access
+
+When Mockaroo-generated fields are used, the tool sends the Mockaroo API key and generation schema/configuration to `https://api.mockaroo.com` over HTTPS to request synthetic data. Existing Dataverse records are not sent to Mockaroo. The API key is saved in ToolBox tool settings and is included in the Mockaroo API request. Use a key appropriate for your account and review Mockaroo's terms and privacy practices.
 
-## Features
+Mockaroo requests include configured field names, generation parameters, and selected choice values. Random lookup fields also send the selected existing Dataverse record IDs to Mockaroo. Lookup display names and full record contents are not included by this lookup-generation path.
 
-- ✅ Select a table and map mock options to each column
-- ✅ Use your own key to get data from Mockaroo
-- ✅ Create rows as you need
+The Content Security Policy exception for `https://api.mockaroo.com` is required for that request. No publisher-controlled telemetry endpoint is used by the tool.
 
-## Note you need a Mockaroo License
-Please get a free one here https://www.mockaroo.com/ 
-It is limited but will be more than enough for most cases. Subscription keys also capable.
+## Screenshot
+
+The screenshot below shows the tool running in Power Platform ToolBox. The Mockaroo API key and environment label have been redacted.
+
+![Mockaroo Data Munger running in Power Platform ToolBox](./assets/mockaroo-data-munger-screenshot.png)
+
+## Implementation and testing
+
+See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for technical notes, test responsibilities, and developer commands. The [manual testing checklist](./IMPLEMENTATION.md#manual-testing-checklist) documents the live PPTB and Dataverse checks required before submission.
+
+## AI assistance
+
+AI coding assistants contributed to this tool's implementation, tests, and documentation. The maintainer is responsible for reviewing the code, validating its behavior against a real environment, and maintaining the published tool.
 
 ## License
 
 MIT
+
+## Updates
+
+### 2026-10-25
+
+- Added explicit target and scope confirmations for record creation, bounded bulk writes, and clearer partial-failure reporting.
+- Documented data handling and the required Mockaroo CSP access; added a tool-oriented marketplace icon.
+- Added a redacted screenshot of the tool running in Power Platform ToolBox.
+- Updated saved configuration and dataset-order lists to use Fluent theme colors in light and dark mode.
+- Added a save icon to the Save Dataset button.
+- Highlighted dataset creation rollback and skipped-step warnings in a warning message box.
+- Moved the dataset review record total into the header, right-aligned at the same text size as the title.
+- Set the minimum supported Power Platform ToolBox version to 1.2.7.
+- Added an AI assistance disclosure and clarified maintainer responsibility.
+- Added a manual acceptance checklist in IMPLEMENTATION.md for live PPTB and Dataverse testing before submission.