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

package/lib/tools/utils.d.ts

@@ -27,6 +27,7 @@ export declare function areArraysEquals(x: any[], y: any[]): boolean;
 export declare const obfuscateSensitiveValues: (data: Asset | Asset[] | null, sensitiveFieldsToObfuscate: string[]) => Asset | Asset[] | null;
 export declare const validateNoUnresolvedPlaceholders: (data: Asset | null, resourceType: string, resourceName: string) => Asset | null;
 export declare const stripObfuscatedFieldsFromPayload: (data: Asset | Asset[] | null, obfuscatedFields: string[]) => Asset | Asset[] | null;
+export declare const stripUnresolvedPlaceholders: (data: Asset | null, resourceType: string, resourceName: string) => Asset | null;
 export declare const detectInsufficientScopeError: <T>(fn: Function) => Promise<{
     hadSufficientScopes: true;
     data: T;
@@ -41,6 +42,8 @@ export declare const isDeprecatedError: (err: {
     message: string;
     statusCode: number;
 }) => boolean;
+export declare const isFeatureUnavailableError: (err: any) => boolean;
+export declare const isInsufficientEntitlementError: (err: unknown) => boolean;
 export declare const isForbiddenFeatureError: (err: any, type: any) => boolean;
 export declare function maskSecretAtPath({ resourceTypeName, maskedKeyName, maskOnObj, keyJsonPath, }: {
     resourceTypeName: string;

package/lib/tools/utils.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldExcludeThirdPartyClients = exports.isForbiddenFeatureError = exports.isDeprecatedError = exports.detectInsufficientScopeError = exports.stripObfuscatedFieldsFromPayload = exports.validateNoUnresolvedPlaceholders = exports.obfuscateSensitiveValues = exports.keywordReplaceStringRegExp = exports.keywordReplaceArrayRegExp = void 0;
+exports.shouldExcludeThirdPartyClients = exports.isForbiddenFeatureError = exports.isInsufficientEntitlementError = exports.isFeatureUnavailableError = exports.isDeprecatedError = exports.detectInsufficientScopeError = exports.stripUnresolvedPlaceholders = exports.stripObfuscatedFieldsFromPayload = exports.validateNoUnresolvedPlaceholders = exports.obfuscateSensitiveValues = exports.keywordReplaceStringRegExp = exports.keywordReplaceArrayRegExp = void 0;
 exports.keywordArrayReplace = keywordArrayReplace;
 exports.keywordStringReplace = keywordStringReplace;
 exports.keywordReplace = keywordReplace;
@@ -309,6 +309,24 @@ const stripObfuscatedFieldsFromPayload = (data, obfuscatedFields) => {
     return newAsset;
 };
 exports.stripObfuscatedFieldsFromPayload = stripObfuscatedFieldsFromPayload;
+// Strips unresolved ##...## / @@...@@ placeholders before sending to Auth0.
+// Keyword replacement runs first; any remaining placeholder means no mapping was
+// provided. The field is dropped so Auth0 preserves its existing value.
+const stripUnresolvedPlaceholders = (data, resourceType, resourceName) => {
+    if (data === null)
+        return data;
+    const unresolved = collectUnresolvedPlaceholders(data);
+    if (unresolved.length === 0)
+        return data;
+    const newAsset = { ...data };
+    unresolved.forEach(({ path, value }) => {
+        logger_1.default.warn(`Stripping unresolved placeholder for ${resourceType} "${resourceName}" field "${path}": ${value}. ` +
+            `To use this value, define ${value.replace(/^##|##$|^@@|@@$/g, '')} in AUTH0_KEYWORD_REPLACE_MAPPINGS. The existing value on Auth0 will be preserved.`);
+        dot_prop_1.default.delete(newAsset, path);
+    });
+    return newAsset;
+};
+exports.stripUnresolvedPlaceholders = stripUnresolvedPlaceholders;
 const detectInsufficientScopeError = async (fn) => {
     try {
         const data = await fn();
@@ -340,9 +358,30 @@ const isDeprecatedError = (err) => {
     return !!(err.statusCode === 403 || err.message?.includes('deprecated feature'));
 };
 exports.isDeprecatedError = isDeprecatedError;
+const isFeatureUnavailableError = (err) => {
+    // A 404 indicates an older Management API version where the endpoint is not available.
+    // 403s (feature explicitly disabled) are handled by isForbiddenFeatureError.
+    return err.statusCode === 404;
+};
+exports.isFeatureUnavailableError = isFeatureUnavailableError;
+const isInsufficientEntitlementError = (err) => {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.statusCode !== 403)
+        return false;
+    const body = e.body;
+    return body?.errorCode === 'insufficient_entitlement';
+};
+exports.isInsufficientEntitlementError = isInsufficientEntitlementError;
 const isForbiddenFeatureError = (err, type) => {
     if (err.statusCode === 403) {
-        logger_1.default.warn(`${err.message};${err.errorCode ?? ''} - Skipping ${type}`);
+        // The SDK error's top-level `message` is the full serialized response body; the clean,
+        // human-readable message and errorCode live on the response body itself.
+        const body = err.originalError?.response?.body ?? {};
+        const message = body.message ?? err.message;
+        const errorCode = body.errorCode ?? err.errorCode ?? '';
+        logger_1.default.warn(`${message}${errorCode ? ` (${errorCode})` : ''} - Skipping ${type}`);
         return true;
     }
     return false;

package/lib/types.d.ts

@@ -16,11 +16,13 @@ import { SsProfileWithCustomText } from './tools/auth0/handlers/selfServiceProfi
 import { PhoneProvider } from './tools/auth0/handlers/phoneProvider';
 import { PhoneTemplate } from './tools/auth0/handlers/phoneTemplates';
 import { NetworkACL } from './tools/auth0/handlers/networkACLs';
+import { NetworkAclKey } from './tools/auth0/handlers/networkACLKeys';
 import { UserAttributeProfile } from './tools/auth0/handlers/userAttributeProfiles';
 import { AttackProtection } from './tools/auth0/handlers/attackProtection';
 import { TokenExchangeProfile } from './tools/auth0/handlers/tokenExchangeProfiles';
 import { RiskAssessment } from './tools/auth0/handlers/riskAssessment';
 import { SupplementalSignals } from './tools/auth0/handlers/supplementalSignals';
+import { RateLimitPolicy } from './tools/auth0/handlers/rateLimitPolicies';
 import { EventStream } from './tools/auth0/handlers/eventStreams';
 type SharedPaginationParams = {
     checkpoint?: boolean;
@@ -30,6 +32,7 @@ type SharedPaginationParams = {
     include_totals?: boolean;
     id?: string;
     strategy?: Management.ConnectionStrategyEnum[];
+    type?: Management.RoleTypeEnum;
 };
 export type CheckpointPaginationParams = SharedPaginationParams & {
     from?: string;
@@ -74,6 +77,7 @@ export type Config = {
     AUTH0_EXPORT_IDENTIFIERS?: boolean;
     AUTH0_EXPORT_ORDERED?: boolean;
     AUTH0_EXPORT_SECRETS?: boolean;
+    AUTH0_EXPORT_CUSTOM_TEXT_LANGUAGES?: string[];
     AUTH0_CONNECTIONS_DIRECTORY?: string;
     AUTH0_DRY_RUN?: boolean | 'preview';
     AUTH0_DRY_RUN_INTERACTIVE?: boolean;
@@ -127,6 +131,9 @@ export type Assets = Partial<{
         message_types: Asset[];
     } | null;
     guardianPhoneFactorSelectedProvider: Asset | null;
+    guardianPhoneFactorSettings: Asset | null;
+    guardianEmailFactorSettings: Asset | null;
+    guardianSettings: Asset | null;
     guardianPolicies: {
         policies: string[];
     } | null;
@@ -154,11 +161,13 @@ export type Assets = Partial<{
     flows: Flow[] | null;
     flowVaultConnections: FlowVaultConnection[] | null;
     selfServiceProfiles: SsProfileWithCustomText[] | null;
+    networkACLKeys: NetworkAclKey[] | null;
     networkACLs: NetworkACL[] | null;
     userAttributeProfiles: UserAttributeProfile[] | null;
     userAttributeProfilesWithId: UserAttributeProfile[] | null;
     connectionProfiles: Asset[] | null;
     tokenExchangeProfiles: TokenExchangeProfile[] | null;
+    rateLimitPolicies: RateLimitPolicy[] | null;
     eventStreams: EventStream[] | null;
 }>;
 export type CalculatedChanges = {
@@ -180,7 +189,7 @@ export type DetailedDryRunChanges = {
         changes: DetailedDryRunChange[];
     };
 };
-export type AssetTypes = 'rules' | 'rulesConfigs' | 'hooks' | 'pages' | 'databases' | 'clientGrants' | 'resourceServers' | 'clients' | 'connections' | 'tenant' | 'emailProvider' | 'emailTemplates' | 'guardianFactors' | 'guardianFactorProviders' | 'guardianFactorTemplates' | 'guardianPhoneFactorMessageTypes' | 'guardianPhoneFactorSelectedProvider' | 'guardianPolicies' | 'roles' | 'actions' | 'actionModules' | 'organizations' | 'triggers' | 'attackProtection' | 'riskAssessment' | 'branding' | 'phoneProviders' | 'phoneTemplates' | 'logStreams' | 'prompts' | 'customDomains' | 'themes' | 'forms' | 'flows' | 'flowVaultConnections' | 'selfServiceProfiles' | 'networkACLs' | 'userAttributeProfiles' | 'connectionProfiles' | 'tokenExchangeProfiles' | 'supplementalSignals' | 'eventStreams';
+export type AssetTypes = 'rules' | 'rulesConfigs' | 'hooks' | 'pages' | 'databases' | 'clientGrants' | 'resourceServers' | 'clients' | 'connections' | 'tenant' | 'emailProvider' | 'emailTemplates' | 'guardianFactors' | 'guardianFactorProviders' | 'guardianFactorTemplates' | 'guardianPhoneFactorMessageTypes' | 'guardianPhoneFactorSelectedProvider' | 'guardianPhoneFactorSettings' | 'guardianEmailFactorSettings' | 'guardianSettings' | 'guardianPolicies' | 'roles' | 'actions' | 'actionModules' | 'organizations' | 'triggers' | 'attackProtection' | 'riskAssessment' | 'branding' | 'phoneProviders' | 'phoneTemplates' | 'logStreams' | 'prompts' | 'customDomains' | 'themes' | 'forms' | 'flows' | 'flowVaultConnections' | 'selfServiceProfiles' | 'networkACLKeys' | 'networkACLs' | 'userAttributeProfiles' | 'connectionProfiles' | 'tokenExchangeProfiles' | 'supplementalSignals' | 'rateLimitPolicies' | 'eventStreams' | 'clientAuthCredentials';
 export type KeywordMappings = {
     [key: string]: (string | number)[] | string | number;
 };

package/lib/utils.d.ts

@@ -52,4 +52,10 @@ export declare const getFormattedOptions: (connection: any, clients: any) => {
 } | {
     options?: undefined;
 };
+/**
+ * Asserts that `resolvedPath` is inside `configRoot`.
+ * Throws a hard error on path traversal attempts so there is a single,
+ * canonical enforcement point across all handlers.
+ */
+export declare function assertInsideConfigRoot(input: string, resolvedPath: string, configRoot: string): void;
 export {};

package/lib/utils.js

@@ -23,6 +23,7 @@ exports.convertClientIdToName = convertClientIdToName;
 exports.hasKeywordMarkers = hasKeywordMarkers;
 exports.mapClientID2NameSorted = mapClientID2NameSorted;
 exports.nomalizedYAMLPath = nomalizedYAMLPath;
+exports.assertInsideConfigRoot = assertInsideConfigRoot;
 const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const nconf_1 = __importDefault(require("nconf"));
@@ -301,12 +302,15 @@ exports.decodeBase64ToCertString = decodeBase64ToCertString;
 // Format connection options by converting client IDs to client names for SAML connections
 const getFormattedOptions = (connection, clients) => {
     try {
+        const { idpinitiated } = connection.options;
         return {
             options: {
                 ...connection.options,
                 idpinitiated: {
-                    ...connection.options.idpinitiated,
-                    client_id: convertClientIdToName(connection.options.idpinitiated.client_id, clients),
+                    ...idpinitiated,
+                    ...(idpinitiated.client_id && {
+                        client_id: convertClientIdToName(idpinitiated.client_id, clients),
+                    }),
                 },
             },
         };
@@ -316,3 +320,14 @@ const getFormattedOptions = (connection, clients) => {
     }
 };
 exports.getFormattedOptions = getFormattedOptions;
+/**
+ * Asserts that `resolvedPath` is inside `configRoot`.
+ * Throws a hard error on path traversal attempts so there is a single,
+ * canonical enforcement point across all handlers.
+ */
+function assertInsideConfigRoot(input, resolvedPath, configRoot) {
+    if (!resolvedPath.startsWith(configRoot + path_1.default.sep)) {
+        throw new Error(`Path traversal blocked: "${input}" resolves to "${resolvedPath}" which is outside the config directory "${configRoot}". ` +
+            `Move the file inside your config directory.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auth0-deploy-cli",
-  "version": "9.0.0-beta.2",
+  "version": "9.1.0",
   "description": "A command line tool for deploying updates to your Auth0 tenant",
   "main": "lib/index.js",
   "bin": {
@@ -35,7 +35,7 @@
   "dependencies": {
     "@clack/prompts": "1.4.0",
     "ajv": "^6.12.6",
-    "auth0": "^5.13.0",
+    "auth0": "^7.3.0",
     "chalk": "5.6.2",
     "dot-prop": "^5.3.0",
     "fs-extra": "^10.1.0",

package/references/code-style.md

@@ -0,0 +1,133 @@
+# Code Style Reference — auth0-deploy-cli
+
+## Naming Conventions
+
+| Element              | Convention       | Example                             |
+| -------------------- | ---------------- | ----------------------------------- |
+| Source files         | camelCase        | `clients.ts`, `attackProtection.ts` |
+| Classes              | PascalCase       | `ClientsHandler`, `YAMLContext`     |
+| Methods / variables  | camelCase        | `processChanges`, `calcChanges`     |
+| Constants / env vars | UPPER_SNAKE_CASE | `AUTH0_ALLOW_DELETE`                |
+| Test files           | `<name>.test.js` | `clients.test.js`                   |
+
+## Handler Implementation Pattern
+
+Every resource handler in `src/tools/auth0/handlers/` must implement four methods:
+
+```typescript
+class ResourceHandler extends DefaultHandler {
+  // Fetch current state from Auth0 API
+  async getType(): Promise<Asset[]> { ... }
+
+  // Determine create / update / delete operations
+  async calcChanges(assets: Assets): Promise<Changes> { ... }
+
+  // Execute CRUD operations — must be a no-op in dry run
+  async processChanges(assets: Assets, changes: Changes): Promise<void> { ... }
+
+  // Validate assets before processing; base class provides a default
+  async validate(assets: Assets): Promise<void> { ... }
+}
+```
+
+> `dump()` / export formatting is handled by `YAMLContext` and `DirectoryContext`, not by handlers.
+
+Register the handler in `src/tools/constants.ts`. Handler schemas are defined inline in the handler file and aggregated by `src/tools/auth0/schema.ts`.
+
+## Identifiers
+
+```typescript
+// ✅ Stable name-based identifier (passed as constructor option to super())
+super({ ...options, identifiers: ['name'] });
+
+// ✅ ID alongside name (when the API uses both for matching)
+super({ ...options, identifiers: ['client_id', 'name'] });
+
+// 🚫 Never — sole auto-generated UUID breaks cross-tenant portability
+super({ ...options, identifiers: ['id'] });
+```
+
+## Keyword Replacement
+
+```yaml
+# @@KEY@@ — JSON-stringified (arrays, objects, booleans, numbers)
+allowed_clients: @@ALLOWED_CLIENTS@@
+
+# ##KEY## — literal string substitution (plain strings only)
+name: "##APP_NAME##"
+```
+
+Both patterns must be preserved in every new field that flows through export/import. Mixing them up causes silent corruption — a `##KEY##` around a JSON array produces invalid YAML.
+
+## Good vs Bad Handler Example
+
+**✅ Good — follows the pattern, respects dry-run and ALLOW_DELETE:**
+
+```typescript
+async processChanges(assets: Assets, changes: Changes): Promise<void> {
+  if (this.config('AUTH0_ALLOW_DELETE')) {
+    await Promise.all(changes.delete.map((r) => this.client.resource.delete({ id: r.id })));
+  }
+  await Promise.all(changes.create.map((r) => this.client.resource.create(r)));
+  await Promise.all(changes.update.map((r) => this.client.resource.update({ id: r.id }, r)));
+}
+```
+
+**❌ Bad — logs a secret, missing ALLOW_DELETE guard:**
+
+```typescript
+async processChanges(assets: Assets, changes: Changes): Promise<void> {
+  console.log('client_secret:', assets.clients[0].client_secret); // never log secrets
+  // missing AUTH0_ALLOW_DELETE check — deletes happen unconditionally
+  await Promise.all(changes.delete.map((r) => this.client.clients.delete({ client_id: r.client_id })));
+}
+```
+
+## @order() Decorator
+
+Handlers run in dependency order. Set `@order(N)` so that handlers whose resources are depended upon by others run first:
+
+```typescript
+@order(30)  // runs after Connections (20) and before Rules (40)
+export default class ClientsHandler extends DefaultHandler { ... }
+```
+
+Wrong order causes 404s or constraint errors mid-deploy.
+
+## Adding a New Resource Handler
+
+1. Create handler in `src/tools/auth0/handlers/<resource>.ts`
+2. Extend `DefaultHandler` and implement all four methods (`getType`, `calcChanges`, `processChanges`, `validate`)
+3. Add the resource type constant to `src/tools/constants.ts`
+4. Define the JSON schema inline in the handler; it is aggregated by `src/tools/auth0/schema.ts`
+5. Write unit tests in `test/tools/auth0/handlers/<resource>.test.js`
+6. Add E2E test coverage if applicable (or document why it's not possible)
+7. Update `docs/resource-specific-documentation.md` and `examples/` to demonstrate the new resource
+
+## Context Parser Details
+
+- **DirectoryContext** (`src/context/directory/`): loads each resource type from separate nested JSON files
+- **YAMLContext** (`src/context/yaml/`): parses a single `tenant.yaml` file with all resources inline
+- Both support `@@KEY@@` and `##KEY##` keyword substitution
+- Context tests use temporary directories with fixtures in `test/context/{directory,yaml}/`
+
+## Configuration and Error Handling
+
+**Config priority order:** CLI args → env vars → config files → defaults
+
+**Error handling conventions:**
+
+- Use `ValidationError` from `src/tools/validationError.ts` for all validation failures
+- Validate early, before making API calls
+- Preserve context when bubbling errors up the call stack
+- Provide clear, actionable error messages
+
+## Architecture: Request Flow
+
+```
+src/index.ts            CLI entry — routes export / import commands
+src/commands/           import.ts, export.ts — load config and context
+src/tools/deploy.ts     Orchestrate deployment across all handlers
+src/tools/auth0/handlers/*  Resource-specific getType / calcChanges / processChanges
+src/tools/auth0/client.ts   Management API calls via the auth0 npm SDK
+```

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.