Mcr/kickstart apply#44
Open
mark-robustelli wants to merge 35 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new apply CLI command which reads a kickstart.json, resolves variables (including dynamic lookups and file inclusions), validates the config, and executes the described FusionAuth API requests. It also adds unit + integration tests and CI workflow support for running the integration suite.
Changes:
- Added apply execution pipeline: validation, variable substitution (UUID/ENV/default tenant lookup + file includes), HTTP execution, and reporting/metrics.
- Added unit tests for the validator and variable substitution engine, plus Docker-based integration tests and a GitHub Actions workflow.
- Updated docs and project config (tsconfig sourcemaps, README command listing).
Reviewed changes
Copilot reviewed 55 out of 56 changed files in this pull request and generated 15 comments.
Show a summary per file
| File | Description |
|---|---|
| tsconfig.json | Enable source maps in build output. |
| src/utilities/kickstart/variable-substitution.ts | Variable substitution engine (UUID/ENV/default tenant lookup, file inclusion). |
| src/utilities/kickstart/validator.ts | Kickstart config schema + variable reference validation. |
| src/utilities/apply/types.ts | New types/enums for apply execution, results, and validation. |
| src/utilities/apply/prompts.ts | Interactive prompting (including hidden input) for variables. |
| src/utilities/apply/line-tracker.ts | Attempts to map request indices to JSON source line numbers. |
| src/utilities/apply/http-client.ts | Fetch-based HTTP client + step executor + error extraction. |
| src/index.ts | Adds unhandled rejection handler and filters command exports before adding to Commander. |
| src/commands/index.ts | Exports the new apply command module. |
| src/commands/apply.ts | Implements fusionauth apply command and execution flow. |
| README.md | Documents new apply command and substitution patterns. |
| .github/workflows/integration-tests.yml | Workflow for running integration tests on demand. |
| tests/test.js | Test harness updated to run unit tests and optionally integration tests. |
| tests/utilities/kickstart/variable-substitution.test.js | Unit tests for variable substitution behaviors. |
| tests/utilities/kickstart/validator.test.js | Unit tests for config validation + variable reference checks. |
| tests/telemetry/index.js | Refactors telemetry tests to properly manage mock-fs lifecycle. |
| tests/postInstall/index.js | Refactors postInstall tests to manage mock-fs lifecycle. |
| tests/integration/setup.js | Docker Compose lifecycle + FusionAuth readiness helpers for integration tests. |
| tests/integration/README.md | Documentation for running/debugging integration tests. |
| tests/integration/apply/apply.integration.test.js | End-to-end test covering apply execution against a running FusionAuth instance. |
| tests/integration/fixtures/kickstarts/poc/kickstart.json | POC kickstart fixture applied by integration tests. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/voice-two-factor-request.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/phone-verification.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/phone-two-factor-remove.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/phone-two-factor-add.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/phone-threat-detected.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/phone-setup-password.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/phone-passwordless-login.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/messages/phone-forgot-password.txt.ftl | POC message template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/two-factor-remove.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/two-factor-remove.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/two-factor-login.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/two-factor-login.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/two-factor-add.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/two-factor-add.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/setup-password.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/setup-password.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/registration-verification.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/registration-verification.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/passwordless-login.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/passwordless-login.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/email-verification.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/email-verification.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/coppa-notice.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/coppa-notice.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/coppa-email-plus-notice.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/coppa-email-plus-notice.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/change-password.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/change-password.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/breached-password.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/breached-password.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/2fa.txt.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/poc/templates/emails/2fa.html.ftl | POC email template fixture. |
| tests/integration/fixtures/kickstarts/fusionauth-integration-test-base/kickstart.json | Base kickstart for standing up the integration test instance (API key/user). |
| tests/integration/fixtures/kickstarts/fusionauth-integration-test-base/docker-compose.yml | Docker Compose stack for FusionAuth integration testing. |
| tests/integration/fixtures/kickstarts/fusionauth-integration-test-base/.env.test | Compose env file (currently committed). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+313
to
+321
| private extractVariableReferences(request: KickstartRequest): string[] { | ||
| const refs = new Set<string>(); | ||
|
|
||
| // Check URL | ||
| refs.forEach((ref) => { | ||
| this.extractVariableReferencesFromString(request.url).forEach((r) => | ||
| refs.add(r) | ||
| ); | ||
| }); |
Comment on lines
+288
to
+296
| variableRefs.forEach((varRef) => { | ||
| // UUID() is a special pattern | ||
| if (varRef === 'UUID()') { | ||
| return; | ||
| } | ||
|
|
||
| if (!definedVariables.has(varRef)) { | ||
| errors.push({ | ||
| field: `requests[${index + 1}]`, |
Comment on lines
+295
to
+301
| errors.push({ | ||
| field: `requests[${index + 1}]`, | ||
| stepId: `step-${String(index + 1).padStart(5, '0')}`, | ||
| lineNumber: index, | ||
| message: `Undefined variable: #{${varRef}}`, | ||
| category: ErrorCategory.VARIABLE_NOT_DEFINED, | ||
| }); |
Comment on lines
+234
to
+241
| // Validate body (optional but should be object if present) | ||
| if (req.body !== undefined && typeof req.body !== 'object') { | ||
| errors.push({ | ||
| field: `requests[${index + 1}].body`, | ||
| message: 'Body must be an object if provided', | ||
| category: ErrorCategory.SCHEMA_INVALID, | ||
| }); | ||
| } |
Comment on lines
+513
to
+521
| // Security: prevent directory traversal attacks | ||
| const resolvedPath = path.resolve(fullPath); | ||
| const kickstartDirResolved = path.resolve(this.kickstartDir); | ||
|
|
||
| if (!resolvedPath.startsWith(kickstartDirResolved)) { | ||
| throw new Error( | ||
| `Invalid file path: ${filePath} (directory traversal not allowed)` | ||
| ); | ||
| } |
Comment on lines
+8
to
+10
| FUSIONAUTH_APP_KICKSTART_FILE=/usr/local/fusionauth/kickstart/kickstart.json | ||
| KICKSTART_FILE_PATH=/Users/mark.robustelli/Projects/fusionauth-node-cli/__tests__/integration/fixtures/kickstarts/fusionauth-integration-test-base/kickstart.json | ||
| OPENSEARCH_JAVA_OPTS=-Xms256m -Xmx256m No newline at end of file |
Comment on lines
+21
to
+25
| console.log('\n📋 Kickstart execution details:') | ||
| for (const step of result.results.steps) { | ||
| if (step.status === 'error' || step.status === 'warning') { | ||
| console.log(`\n Step: ${step.id} (${step.action} ${step.request?.url})`) | ||
| console.log(` Status: ${step.status.toUpperCase()}`) |
making obvious fixes from co-pilot review. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
making obvious fixes from co-pilot review. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
making obvious fixes from co-pilot review. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
making obvious fixes from co-pilot review. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
making obvious fixes from co-pilot review. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add apply and tests.