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

package/references/commands.md

@@ -0,0 +1,98 @@
+# Commands Reference — auth0-deploy-cli
+
+## Setup
+
+```bash
+# Install dependencies (first-time setup)
+npm install
+```
+
+## Build
+
+```bash
+# Compile TypeScript → lib/ (cleans lib/ first via rimraf)
+npm run build
+
+# Compile and watch (development)
+npm run dev
+
+# Type check only (no output)
+npx tsc --noEmit
+```
+
+## Unit Tests
+
+```bash
+# Run all unit tests (safe — no credentials required)
+npm test
+
+# Run a specific test file
+npx ts-mocha -p tsconfig.json test/tools/auth0/handlers/clients.test.js
+
+# Run tests matching a pattern
+npm test -- --grep "should create client"
+
+# Run with coverage
+npm run test:coverage
+```
+
+## Lint
+
+```bash
+# ESLint + kacl changelog lint
+npm run lint
+
+# Auto-fix ESLint issues
+npm run lint:fix
+```
+
+## E2E Tests
+
+> ⚠️ These tests hit a real Auth0 tenant. Ask before running — see [Boundaries](../CLAUDE.md#boundaries).
+
+```bash
+# E2E as Node module (uses HTTP recordings)
+AUTH0_HTTP_RECORDINGS=lockdown npm run test:e2e:node-module
+
+# E2E as CLI (requires real tenant credentials)
+npm run test:e2e:cli
+```
+
+Required environment variables for E2E:
+
+- `AUTH0_DOMAIN`
+- `AUTH0_CLIENT_ID`
+- `AUTH0_CLIENT_SECRET`
+- `AUTH0_HTTP_RECORDINGS=lockdown` (for node-module recording replay)
+
+## Running the CLI Directly
+
+```bash
+# Always build first
+npm run build
+
+# Export tenant configuration
+node lib/index.js export -c config.json -f directory -o ./local/
+node lib/index.js export -c config.json -f yaml -o ./local-yaml/
+
+# Import (deploy) configuration
+node lib/index.js import -c config.json -i ./local/tenant.json
+node lib/index.js import -c config.json -i ./local-yaml/tenant.yaml
+
+# Enable debug logging
+AUTH0_DEBUG=true node lib/index.js import -c config.json -i ./local/tenant.json
+```
+
+## Environment Variables Reference
+
+```bash
+AUTH0_DOMAIN                        # Tenant domain (e.g. my-tenant.auth0.com)
+AUTH0_CLIENT_ID                     # Client ID for M2M application
+AUTH0_CLIENT_SECRET                 # Client secret
+AUTH0_ALLOW_DELETE=true             # Enable delete operations (default: false)
+AUTH0_KEYWORD_REPLACE_MAPPINGS      # JSON object for @@KEY@@/##KEY## substitution
+AUTH0_EXCLUDED                      # JSON array of resource types to skip
+AUTH0_EXCLUDED_<TYPE>               # Exclude specific resources by name, e.g. AUTH0_EXCLUDED_CLIENTS
+AUTH0_DEBUG=true                    # Enable verbose debug logging
+AUTH0_HTTP_RECORDINGS=lockdown      # Replay HTTP recordings in E2E node-module tests
+```

package/references/docs-update.md

@@ -0,0 +1,34 @@
+# Docs Update Rules — auth0-deploy-cli
+
+## Tracked Docs Inventory
+
+| Doc                   | Status     | Covers                                                                                                          |
+| --------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
+| `README.md`           | present    | Installation, quick-start, prerequisites, CLI usage, configuration options, environment variables, contributing |
+| `EXAMPLES.md`         | ❌ missing | Create when adding a new integration pattern or command example                                                 |
+| `examples/yaml/`      | present    | Sample YAML-format tenant configuration                                                                         |
+| `examples/directory/` | present    | Sample directory-format tenant configuration                                                                    |
+
+## Code-to-Docs Mapping (CLI tool)
+
+This is a CLI tool. The public surface is **commands, subcommands, and flags** — not exported functions.
+
+| When this changes                                                  | Update these docs                                                                                         |
+| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| A command or subcommand added, removed, or renamed                 | `README.md` (command reference / usage)                                                                   |
+| A flag or argument added, removed, renamed, or its default changed | `README.md` (command reference), `examples/` (affected invocations)                                       |
+| Output format or exit-code behavior changed                        | `README.md` (usage), `examples/`                                                                          |
+| A new resource type added or removed                               | `README.md` (supported resources section), `examples/yaml/` and `examples/directory/` (add sample config) |
+| A new config field or env var added                                | `README.md` (configuration / environment variables section)                                               |
+| A new keyword replacement pattern or behavior                      | `README.md` (keyword replacement section)                                                                 |
+
+> When you touch code that maps to a doc above, update that doc **in the same PR** — do not defer.
+
+> `CHANGELOG.md` is maintained as part of the release flow — do not add changelog entries during feature development; they are cut at release time via the release process.
+
+## Additional Reference Docs
+
+- `docs/` — extended documentation including resource-specific docs; update `docs/resource-specific-documentation.md` when adding a new handler
+- `docs/v8_MIGRATION_GUIDE.md` — v8 migration context; when making a breaking change, consult this pattern to author a versioned migration guide (filename inferred from the target major at the time of the change)
+- `CONTRIBUTING.md` — contribution guidelines
+- `.github/ISSUE_TEMPLATE/` — issue templates for bug reports and feature requests

package/references/git-workflow.md

@@ -0,0 +1,135 @@
+# Git Workflow Reference — auth0-deploy-cli
+
+## Branch Naming
+
+`DXCDT-XXXX` (Jira ticket number) for feature and fix branches.
+
+Examples: `DXCDT-2268`, `SDK-10176`
+
+## Commit Messages
+
+Conventional Commits format:
+
+- `feat: add support for new resource type`
+- `fix: resolve table formatting issue`
+- `docs: update handler implementation guide`
+- `test: add coverage for keyword replacement`
+- `refactor: simplify change calculation logic`
+
+## Pull Request Conventions
+
+PR template is at `.github/PULL_REQUEST_TEMPLATE.md`. Sections:
+
+- **Changes** — what was changed and why
+- **References** — linked Jira ticket or GitHub issue
+- **Testing** — what was tested, and any scenarios that could not be tested (EA / entitlement-gated)
+- **Checklist** — tests pass, lint passes, docs updated, backward compatibility checked
+
+## PR Review Checklist
+
+> This is a living document. Add a new section, checklist item, or Lesson Learned whenever a real review surfaces a pattern worth capturing.
+
+Work through every section in order. Do not skip sections because they seem irrelevant. Give a structured summary after all areas: issues found (grouped by severity), items that look good, and questions for the author.
+
+### 1. Context & Purpose
+
+- Does the PR description explain **why** this change is needed, not just what it does?
+- Is there a linked issue? Does the PR actually close it?
+- Is the scope reasonable — one thing, not many things?
+
+### 2. Correctness
+
+- Does the logic do what the description claims?
+- Are early exits and guard clauses correct — not too broad, not too narrow?
+- Are error paths handled? Does a failure in one step leave state inconsistent?
+- Are there silent failures (swallowed errors, empty catch blocks)?
+- Does the ordering of operations matter? Is it correct? (e.g. create before delete)
+
+### 3. Edge Cases
+
+- What happens with empty input / null / undefined?
+- What happens when the resource already exists (idempotency)?
+- What happens when a partial failure occurs mid-operation?
+- Are there race conditions or ordering dependencies across handlers?
+
+### 4. Backward Compatibility
+
+- Does this break any existing config formats or file structures?
+- Will existing users' export → deploy workflows still work unchanged?
+- Are old config shapes (from before this PR) still handled gracefully?
+- Does any new export format, when re-deployed unchanged, produce unintended side effects?
+
+### 5. Safety & Destructive Operations
+
+- Are destructive operations (delete, overwrite) gated by `ALLOW_DELETE`?
+- Is the safety contract enforced in code on **all** paths — not just the obvious ones?
+- Could a no-op deploy (nothing changed) still cause mutations?
+
+### 6. Tests
+
+- Are unit tests present for new logic?
+- Do tests actually test what their names claim? Verify the mock matches the test name.
+- Are critical/risky paths covered — not just the happy path?
+- Are E2E tests present or updated? If not, is there a documented reason?
+- Is there a regression test for the exact failure scenario the PR is fixing?
+- Are there idempotency tests — running the same operation twice produces no extra changes?
+
+### 7. Docs & Examples
+
+- Is there a new config shape or feature? Are examples updated?
+- Are example files (`examples/`, `tenant.yaml`) updated to demonstrate new functionality?
+- Is the README or relevant documentation updated?
+- Are new config fields, env vars, or flags documented?
+
+### 8. Code Quality
+
+- Is the code readable and does it follow existing patterns?
+- Are there unnecessary type casts (`as any`, `as Function`) that bypass type safety?
+- Is there dead code, unused imports, or leftover debug statements?
+- Is mutation of shared state (e.g. assets objects) clearly intentional and safe?
+
+### 9. Performance
+
+- Are there N+1 patterns (API calls inside loops)?
+- Could this cause rate limiting for large tenants?
+
+### 10. Security
+
+- Are sensitive values (secrets, PEM keys, tokens) ever logged or exported?
+- Is user-controlled input validated before use?
+
+### 11. deploy-cli Specific — verify all of these
+
+- Does the change work in **both** YAML and directory formats?
+- Is the dry-run path correct? Dry-run must never mutate state on any affected path.
+- Is keyword replacement (`@@KEY@@` / `##KEY##`) preserved correctly for new fields?
+- Are write-only fields (secrets, key material) stripped on export and never written to disk?
+- Are read-only/API-generated fields (`created_at`, `updated_at`, `id`, `fingerprint`) stripped on export and excluded from create/update payloads?
+- Does a new handler implement all required methods: `getType`, `calcChanges`, `processChanges`, `validate`?
+- Does the `identifiers` array include `name` (or a stable name-like field) as the primary key — not solely an auto-generated UUID `id`?
+- Is handler `@order()` placed correctly relative to its dependencies?
+- Is the JSON schema complete and accurate without being so permissive it passes invalid configs?
+- Is sorted-key output stable? No unintended order changes introduced in exported configs.
+
+### 12. EA / Entitlement-Gated (apply if feature requires a flag or entitlement to test)
+
+- Which scenarios could not be tested? Are they explicitly listed in the PR description?
+- For each untested scenario, are the API assumptions spelled out — not buried under "code path confirmed correct"?
+- If a field is read from `this.existing` (populated via list) and used in a guard: has the list endpoint been verified to return that field?
+- If schema uses `additionalProperties: false` on an EA object: has the full read shape been confirmed from a real API response?
+- Is there a follow-up ticket to re-verify untested scenarios once entitlement is available?
+
+### Final Gate — answer all four before approving
+
+1. If I export and immediately re-deploy with no changes, is anything mutated?
+2. If a mid-operation step fails, is the system left in a recoverable state?
+3. Has the safety contract been verified in code for every path — not just described in the PR?
+4. Are docs and examples updated so another engineer can use this feature without reading the code?
+
+### Lessons Learned
+
+- **Safety claim ≠ safety in code.** "Deletes are gated" in a PR description doesn't mean the code gates deletes on every path. Verify line by line.
+- **Early-exit logic is subtle.** `A && B` vs `A` in a guard clause can be the difference between a no-op and data loss.
+- **Mocks can lie.** A test named "should not delete when flag is off" may pass for the wrong reason. Always verify the stub is called (or not called) with `sinon.assert`.
+- **Export format drift breaks imports.** A richer export shape can silently break the import path if the importer doesn't handle it. Check both sides.
+- **"Code path confirmed correct" ≠ tested end-to-end.** If an entitlement blocked a scenario, say so explicitly and enumerate the unverified assumptions.

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