cve-dashboard/.kiro/specs/config-wizard/requirements.md

Requirements Document

Introduction

The CVE Dashboard requires a number of environment variables to be configured before the backend and frontend can operate correctly. Currently, users must manually create .env files by referencing .env.example and inline code comments, which is error-prone and provides no validation feedback. This feature introduces an interactive CLI configuration wizard that guides users through entering all required and optional environment variables at deployment time, providing descriptions, documentation references, default values, and input validation.

Glossary

• Config_Wizard: A Node.js CLI script that interactively prompts the user to enter environment variable values and writes the resulting configuration to .env files
• Variable_Group: A logical grouping of related environment variables presented together during the wizard flow (e.g., "Core Settings", "Ivanti Integration", "Jira Integration")
• Required_Variable: An environment variable that must have a non-empty value for the application to start or for a core feature to function
• Optional_Variable: An environment variable that enhances functionality but is not required for the application to start
• Variable_Descriptor: The metadata associated with each environment variable, including its name, description, default value, required/optional status, and documentation reference
• Backend_Env_File: The file at backend/.env containing backend server configuration
• Frontend_Env_File: The file at frontend/.env containing frontend build-time configuration
• Validation_Rule: A check applied to user input for a variable to verify it meets format or content requirements before writing to the env file
• Deploy_Script: The shell script at scripts/deploy-postgres.sh that provisions the Docker Postgres container with known credentials and port mappings
• Docker_Compose_Config: The docker-compose.yml file at the project root that defines the Postgres container name, user, password, database, and port mapping

Requirements

Requirement 1: Interactive CLI Execution

User Story: As a deployer, I want to run a single command to start the configuration wizard, so that I can set up the dashboard without manually editing env files.

Acceptance Criteria

1. THE Config_Wizard SHALL be executable via node configure.js from the project root directory
2. WHEN the Config_Wizard starts, THE Config_Wizard SHALL display a welcome message explaining its purpose and that it will guide the user through configuring backend and frontend environment variables
3. THE Config_Wizard SHALL use Node.js built-in readline module for interactive prompts without requiring additional npm dependencies
4. WHEN the user presses Ctrl+C at any prompt, THE Config_Wizard SHALL exit without writing any configuration files, display a cancellation message to stdout, and terminate with exit code 1
5. IF the Config_Wizard is executed from a directory that does not contain both a backend/ and a frontend/ subdirectory, THEN THE Config_Wizard SHALL display an error message indicating it must be run from the project root and terminate with exit code 1
6. WHEN the Config_Wizard completes successfully after writing all env files, THE Config_Wizard SHALL terminate with exit code 0

Requirement 2: Variable Grouping and Ordering

User Story: As a deployer, I want variables presented in logical groups, so that I can understand which variables relate to which integration and configure them together.

Acceptance Criteria

1. THE Config_Wizard SHALL present backend variables organized into the following Variable_Groups in order: Core Settings, Database, Session, NVD API, Ivanti Integration, Atlas Integration, Jira Integration, CARD Integration, GitLab Integration
2. THE Config_Wizard SHALL present frontend variables as a separate Variable_Group named "Frontend Settings" after all backend groups
3. WHEN entering a new Variable_Group, THE Config_Wizard SHALL display the group name as a section header followed by a one-sentence description (maximum 120 characters) of what the group configures
4. THE Config_Wizard SHALL present Required_Variables before Optional_Variables within each Variable_Group
5. THE Config_Wizard SHALL assign each environment variable to exactly one Variable_Group such that no variable appears in more than one group during the wizard flow

Requirement 3: Variable Descriptions and Documentation References

User Story: As a deployer, I want each variable to have a short description and a pointer to further documentation, so that I can understand what each variable controls without leaving the terminal.

Acceptance Criteria

1. WHEN prompting for a variable, THE Config_Wizard SHALL display the following elements in order: the "[REQUIRED]" or "[OPTIONAL]" label, the variable name, a description of no more than 120 characters explaining what the variable controls, and the default value if one exists
2. WHEN a variable has a default value, THE Config_Wizard SHALL display the default value in the prompt enclosed in parentheses and accept an empty input to use that default
3. WHERE a variable belongs to an external-service Variable_Group (NVD API, Ivanti Integration, Atlas Integration, Jira Integration, CARD Integration, or GitLab Integration), THE Config_Wizard SHALL display a documentation URL or instruction for obtaining the value alongside the prompt
4. WHEN a variable is classified as sensitive (containing passwords, secrets, API keys, or tokens), THE Config_Wizard SHALL mask the default value display by showing only the first 4 and last 4 characters with asterisks in between, or show the full value if it is 8 characters or fewer
5. IF a variable has both a default value and a documentation reference, THEN THE Config_Wizard SHALL display both the default value and the documentation reference in the same prompt

Requirement 4: Deploy-Aware Defaults

User Story: As a deployer, I want the wizard to automatically derive sensible defaults from the deploy infrastructure (docker-compose.yml, deploy scripts), so that I do not need to manually construct values like DATABASE_URL.

Acceptance Criteria

1. WHEN the Docker_Compose_Config file exists at the project root, THE Config_Wizard SHALL parse it to extract the Postgres user, password, database name, and host port mapping, resolving any shell variable substitution syntax (${VAR:-default}) by using the specified default value
2. WHEN Postgres credentials are available from Docker_Compose_Config, THE Config_Wizard SHALL construct a default DATABASE_URL in the format postgresql://user:password@localhost:port/database using the host port from the port mapping (the first value in a "host:container" pair) and present it as the default value
3. IF the Docker_Compose_Config file exists but does not contain a Postgres service definition or cannot be parsed, THEN THE Config_Wizard SHALL fall back to the hardcoded default from the Deploy_Script (postgresql://steam:sV4xmC9xAUCFop0ypxMVS056QgPqGrX@localhost:5433/cve_dashboard) and display a message indicating that the compose file could not be used
4. WHEN the Docker_Compose_Config file does not exist, THE Config_Wizard SHALL fall back to the hardcoded default from the Deploy_Script (postgresql://steam:sV4xmC9xAUCFop0ypxMVS056QgPqGrX@localhost:5433/cve_dashboard)
5. WHEN presenting the DATABASE_URL prompt, THE Config_Wizard SHALL display a message indicating whether the default was auto-derived from Docker_Compose_Config or from the Deploy_Script fallback, and allow the user to override it
6. WHEN the user confirms a PORT value for the backend (whether accepting the default of 3001 or providing a custom value), THE Config_Wizard SHALL use that PORT value to construct the default REACT_APP_API_BASE as http://localhost:{PORT}/api and use the hardcoded frontend port 3000 to construct the default CORS_ORIGINS as http://localhost:3000 for subsequent prompts

Requirement 5: Input Validation

User Story: As a deployer, I want the wizard to validate my input before saving, so that I do not end up with a broken configuration due to typos or formatting errors.

Acceptance Criteria

1. WHEN the user provides an empty or whitespace-only value for a Required_Variable that has no default, THE Config_Wizard SHALL display an error message indicating the variable is required and re-prompt for the value
2. WHEN the user provides a PORT value, THE Config_Wizard SHALL trim leading and trailing whitespace, then validate that the trimmed value is an integer between 1 and 65535
3. WHEN the user provides a CORS_ORIGINS value, THE Config_Wizard SHALL trim whitespace from each comma-separated entry and validate that each trimmed entry starts with http:// or https://
4. WHEN the user provides a DATABASE_URL value that overrides the derived default, THE Config_Wizard SHALL validate that it starts with postgresql:// or is the literal string sqlite (for SQLite mode)
5. IF validation fails for any input, THEN THE Config_Wizard SHALL display an error message indicating the expected format and re-prompt for the same variable without losing previously entered values, repeating until the user provides valid input or exits via Ctrl+C
6. WHEN the user provides a SESSION_SECRET value, THE Config_Wizard SHALL validate that it is at least 16 characters long

Requirement 6: Env File Generation

User Story: As a deployer, I want the wizard to write properly formatted .env files, so that the application can read them without manual editing.

Acceptance Criteria

1. WHEN the user completes all prompts, THE Config_Wizard SHALL write the backend configuration to the Backend_Env_File path
2. WHEN the user completes all prompts, THE Config_Wizard SHALL write the frontend configuration to the Frontend_Env_File path
3. THE Config_Wizard SHALL write each variable in KEY=value format with #-prefixed comment headers separating Variable_Groups, and SHALL wrap any value containing spaces, #, or quote characters in double quotes
4. THE Config_Wizard SHALL omit Optional_Variables from the output file when the user provides no value and no default exists
5. IF a Backend_Env_File or Frontend_Env_File already exists, THEN THE Config_Wizard SHALL prompt the user to confirm overwrite before writing, offer to create a backup copy named {original_filename}.backup.{YYYYMMDD_HHmmss} in the same directory, and abort writing that file without affecting other files if the user declines both overwrite and backup
6. IF writing to the Backend_Env_File or Frontend_Env_File fails due to a filesystem error, THEN THE Config_Wizard SHALL display an error message indicating the file path and the reason for failure, and SHALL exit without writing any remaining files

Requirement 7: Skip Optional Integration Groups

User Story: As a deployer, I want to skip entire optional integration groups that I do not use, so that I can complete the wizard quickly without answering irrelevant prompts.

Acceptance Criteria

1. WHEN entering an optional Variable_Group (Ivanti, Atlas, Jira, CARD, GitLab, NVD), THE Config_Wizard SHALL prompt the user with a yes/no question asking whether they want to configure that integration, defaulting to "no" if the user presses Enter without input
2. WHEN the user declines to configure an optional Variable_Group by entering "n", "no", or pressing Enter to accept the default, THE Config_Wizard SHALL skip all variables in that group and proceed to the next group
3. WHEN the user declines an optional Variable_Group, THE Config_Wizard SHALL not write any variables from that group to the env file
4. WHEN displaying the summary (per Requirement 8), THE Config_Wizard SHALL list each skipped Variable_Group by name with an indication that it was skipped

Requirement 8: Summary and Confirmation

User Story: As a deployer, I want to review my configuration before it is written to disk, so that I can catch mistakes before they are persisted.

Acceptance Criteria

1. WHEN all prompts are complete, THE Config_Wizard SHALL display a summary table organized by Variable_Group showing all configured variables with their values, masking the following variables with asterisks (********): SESSION_SECRET, NVD_API_KEY, IVANTI_API_KEY, ATLAS_API_PASS, JIRA_API_TOKEN, JIRA_PAT, CARD_API_PASS, GITLAB_PAT, DATABASE_URL
2. WHEN all prompts are complete, THE Config_Wizard SHALL exclude skipped Variable_Groups from the summary table and display only variables that will be written to the env files
3. WHEN displaying the summary, THE Config_Wizard SHALL show the target file paths (backend/.env and frontend/.env) and indicate whether each file already exists and will be overwritten
4. WHEN the user confirms the summary, THE Config_Wizard SHALL write the env files and display a success message followed by next steps instructing the user to run node backend/setup.js to initialize the database and to start the servers
5. WHEN the user rejects the summary, THE Config_Wizard SHALL prompt the user to choose between restarting the wizard from the beginning with all previously entered values cleared, or exiting without writing any files

Requirement 9: Reconfigure Existing Installation

User Story: As a deployer, I want to re-run the wizard on an existing installation and have it pre-fill current values, so that I can update specific variables without re-entering everything.

Acceptance Criteria

1. WHEN the Config_Wizard starts and a Backend_Env_File already exists, THE Config_Wizard SHALL parse the existing file by splitting each non-comment, non-empty line on the first = character, use the parsed current values as defaults in place of factory defaults for each corresponding prompt, and fall back to factory defaults for any managed variables not present in the file
2. WHEN the Config_Wizard starts and a Frontend_Env_File already exists, THE Config_Wizard SHALL parse the existing file by splitting each non-comment, non-empty line on the first = character, use the parsed current values as defaults in place of factory defaults for each corresponding prompt, and fall back to factory defaults for any managed variables not present in the file
3. WHEN displaying a prompt with a pre-filled value from an existing env file, THE Config_Wizard SHALL label the default as "[current]" to distinguish it from a factory default
4. THE Config_Wizard SHALL preserve any variables and comment lines in existing env files whose keys are not in the wizard's managed variable list (PORT, API_HOST, CORS_ORIGINS, SESSION_SECRET, DATABASE_URL, NVD_API_KEY, IVANTI_, ATLAS_, JIRA_, CARD_, GITLAB_, REACT_APP_), appending them in a "Custom Variables" section at the end of the generated file
5. IF an existing env file contains a key that matches a managed variable name but appears in a custom or unrecognized section, THEN THE Config_Wizard SHALL use the wizard-entered value for that key and discard the duplicate from the custom variables section
6. IF an existing env file cannot be parsed due to file read errors or contains no valid KEY=value lines, THEN THE Config_Wizard SHALL display a warning message indicating the file could not be loaded, proceed using factory defaults, and preserve the unparseable file as a backup before writing the new configuration