auth0-deploy-cli 9.0.0-beta.2 → 9.1.0

package/references/pitfalls.md

@@ -0,0 +1,62 @@
+# Common Pitfalls — auth0-deploy-cli
+
+## 1. Dry-run must never mutate
+
+`processChanges()` is called in both live and dry-run mode. The dry-run guard lives higher up the call stack — any code path that bypasses it (e.g. a direct API call outside `processChanges`) silently mutates tenant state. Always verify the full call graph, not just the handler method.
+
+## 2. Both YAML and directory formats must work
+
+New fields, handlers, and schema changes must work in both context formats. The YAML context uses a single `tenant.yaml`; the directory context uses nested JSON files. Test with both. Failing one format is a silent breakage users hit in production.
+
+## 3. @@KEY@@ vs ##KEY## — use the right pattern
+
+- `@@KEY@@` — JSON-stringified. Use for arrays, objects, booleans, numbers. If the replacement is a JSON array, `@@KEY@@` produces valid YAML/JSON inline.
+- `##KEY##` — literal string substitution. Use only for plain string values.
+
+Mixing them up causes silent corruption: a `##KEY##` wrapping a JSON array produces invalid YAML.
+
+## 4. "Code path confirmed correct" ≠ "tested end-to-end"
+
+For EA / entitlement-gated features, code review cannot substitute for a real API call. The API may return fields the code doesn't expect, or omit fields the code reads from `this.existing`. Always document what you could not test and create a follow-up ticket.
+
+## 5. additionalProperties: false on EA objects
+
+If a schema uses `additionalProperties: false` and the API later returns a new field on that object, every deploy will fail schema validation. Only use `additionalProperties: false` after confirming the exact API response shape from a real tenant response — not API docs alone.
+
+## 6. identifiers must include name
+
+`identifiers = ['id']` uses the auto-generated API ID for cross-tenant matching. This breaks portability — the ID is tenant-specific. Always include `name` (or a stable name-like field) as the primary matching key.
+
+## 7. Export → re-deploy roundtrip must be idempotent
+
+After an export, re-deploying the same config with no manual changes must produce zero diffs. Any field that gets transformed on export and then looks different on the next import/export cycle is a bug. Test this explicitly for new fields.
+
+## 8. @order() placement
+
+Handlers run in dependency order defined by `@order()`. A handler that creates resources another depends on (e.g. Connections before Clients) must have a lower order number. Wrong order → 404s or constraint errors during deploy.
+
+---
+
+## Debugging
+
+### Enable verbose logging
+
+```bash
+AUTH0_DEBUG=true node lib/index.js import -c config.json -i ./local/tenant.json
+```
+
+### Common issues
+
+| Symptom                                              | Likely cause                        | Fix                                                                               |
+| ---------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
+| Build errors / import not found                      | `tsconfig.json` path mismatch       | Check `tsconfig.json` and ensure all imports resolve                              |
+| "Handler not found" / resource skipped silently      | Resource type not registered        | Verify it's added to `src/tools/constants.ts`                                     |
+| Schema validation fails on deploy                    | Schema too strict or missing fields | Check schema definition in the handler file; confirm against a real API response  |
+| Keyword replacement produces raw `@@KEY@@` in output | Mapping missing or wrong pattern    | Verify `AUTH0_KEYWORD_REPLACE_MAPPINGS` config and confirm `@@KEY@@` vs `##KEY##` |
+| E2E fails with auth errors                           | Missing or wrong credentials        | Check `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`                    |
+
+### Key files for debugging
+
+- `src/tools/deploy.ts` — deployment orchestration; check here first if a resource is silently skipped
+- `src/tools/calculateChanges.ts` — change detection; check here for unexpected create/update/delete
+- `test/utils.js` — `mockPagedData()` and other test helpers

package/references/testing.md

@@ -0,0 +1,118 @@
+# Testing Reference — auth0-deploy-cli
+
+## Framework and Tools
+
+- **Test runner**: Mocha 10.x (`ts-mocha` for TypeScript)
+- **Stubs / spies**: sinon
+- **Coverage**: nyc (Istanbul)
+- **Test location**: `test/` (mirrors `src/` structure)
+- **File pattern**: `test/**/*.test*` (excludes `test/e2e/`)
+- **Timeout**: 20 000 ms per test
+
+## Running Tests
+
+```bash
+# All unit tests (safe — no credentials)
+npm test
+
+# Single file
+npx ts-mocha -p tsconfig.json test/tools/auth0/handlers/clients.test.js
+
+# Pattern match
+npm test -- --grep "should create client"
+
+# With coverage report
+npm run test:coverage
+```
+
+## Handler Test Scaffolding
+
+```javascript
+const mockClient = {
+  clients: {
+    getAll: sinon.stub().returns(
+      mockPagedData([
+        /* existing resources */
+      ])
+    ),
+    create: sinon.stub().resolves({ client_id: 'abc', name: 'my-app' }),
+    update: sinon.stub().resolves({}),
+    delete: sinon.stub().resolves({}),
+  },
+};
+
+const mockConfig = (key) => {
+  const config = {
+    AUTH0_ALLOW_DELETE: false,
+    AUTH0_EXCLUDED_CLIENTS: [],
+  };
+  return config[key];
+};
+```
+
+## Test Naming Convention
+
+```javascript
+describe('ClientsHandler', () => {
+  it('should create a client when it does not exist', async () => { ... });
+  it('should update a client when it already exists', async () => { ... });
+  it('should not delete when AUTH0_ALLOW_DELETE is false', async () => { ... });
+  it('should delete when AUTH0_ALLOW_DELETE is true', async () => { ... });
+});
+```
+
+## Key Test Utilities
+
+- `test/utils.js` — `mockPagedData()`, `buildStateObject()`, and other shared helpers
+- `sinon.stub().resolves(value)` — async stubs
+- `sinon.stub().returns(value)` — synchronous stubs (e.g. paged data iterators)
+
+## What to Cover in Every Handler Test
+
+- **Happy path**: normal create, update, delete with `AUTH0_ALLOW_DELETE=true`
+- **No-delete guard**: `AUTH0_ALLOW_DELETE=false` produces zero deletes
+- **Empty input**: empty asset arrays produce zero API calls
+- **Idempotency**: deploy with unchanged config produces zero create/update/delete calls
+- **Error path**: API call failure is surfaced (not swallowed)
+- **Regression**: if fixing a bug, a test that would have caught the original bug
+
+## Verifying Mocks
+
+Always confirm the stub shape matches what the real API returns. A test named "should not delete" can pass silently for the wrong reason if the mock is wrong — verify the `sinon.stub()` is actually being called (or not called) via `sinon.assert`.
+
+## E2E Test Requirements
+
+> ⚠️ Ask before running — these mutate real tenant state.
+
+```bash
+# Node module E2E (uses HTTP recordings)
+AUTH0_HTTP_RECORDINGS=lockdown npm run test:e2e:node-module
+
+# CLI E2E (requires real tenant)
+AUTH0_DOMAIN=<tenant> AUTH0_CLIENT_ID=<id> AUTH0_CLIENT_SECRET=<secret> npm run test:e2e:cli
+```
+
+Use a dedicated development tenant. Never run E2E against a production tenant.
+
+## Configuration Testing
+
+When testing resource exclusion and property filtering:
+
+```javascript
+const mockConfig = (key) => {
+  const config = {
+    AUTH0_ALLOW_DELETE: false,
+    AUTH0_EXCLUDED: [], // resource types excluded entirely
+    AUTH0_EXCLUDED_CLIENTS: ['my-app'], // named exclusion per resource type
+    EXCLUDED_PROPS: { clients: ['description'] }, // properties excluded from comparison
+    INCLUDED_PROPS: { clients: ['name', 'app_type'] }, // properties included in comparison
+  };
+  return config[key];
+};
+```
+
+- `AUTH0_EXCLUDED` — array of resource type strings to skip entirely
+- `AUTH0_EXCLUDED_<TYPE>` — array of resource names to skip within a type
+- `EXCLUDED_PROPS` — per-type list of properties to ignore during diff
+- `INCLUDED_PROPS` — per-type allowlist; when set, only listed properties are compared
+- Test keyword replacement by passing `AUTH0_KEYWORD_REPLACE_MAPPINGS` with a sample mapping and verifying the resolved value in the exported/imported asset