Feature: Guided web-based installer wizard

[CPAtoCybersecurity]

Summary

Replace the current manual setup flow (install Node → clone repo → npm install → set REACT_APP_* env vars → npm start) with a single-command installer that launches a styled web wizard in the user's browser to handle the whole first-run experience.

Why

Right now, getting up and running requires the user to:

1. Confirm Git + Node 18+ are installed
2. Clone the repo
3. Run npm install
4. Manually set four REACT_APP_* environment variables for Jira and Confluence
5. Decide whether to load the Alma Security demo data or start clean
6. Run npm start

For the GRC / CPA-pivoting-into-cyber audience this tool is built for, steps 4–5 are the highest-friction points — a lot of those users are not comfortable in a terminal setting environment variables. A guided installer would meaningfully widen the on-ramp without changing what the tool is.

Proposed Architecture

1. Bootstrap script (install.sh / install.ps1)

• Verifies Node 18+ and Git
• Clones the repo to a chosen directory (or uses CWD if already cloned)
• Runs npm install
• Spawns a small local Node HTTP server on a fixed port (e.g. localhost:31338)
• Opens the user's default browser to that URL

2. Local installer server (Node, no extra runtime)

• Serves the wizard's HTML/CSS/JS
• Exposes a few JSON endpoints the wizard calls:
  • GET /api/system — Node version, Git presence, existing .env detection
  • POST /api/credentials — writes Jira/Confluence values to .env.local
  • POST /api/seed — loads or skips the Alma Security demo dataset
  • POST /api/launch — kicks off npm start and reports the dev server URL
• Shuts itself down after the wizard finishes

3. Wizard UI (HTML + minimal JS, styled to look like a desktop installer)
Steps, modeled on a typical left-rail installer pattern:

1. System Detection — Node version, Git, existing install detection ("Found existing .env.local — reuse, overwrite, or back up?")
2. Prerequisites — install missing dependencies, surface errors clearly
3. Atlassian Credentials (optional, skippable) — Jira instance URL + token, Confluence instance URL + token, with a "Test connection" button per pair
4. Demo Data — load Alma Security case study, start blank, or import an existing assessment export (CSV / encrypted backup)
5. Encryption Setup (optional) — set a default password for encrypted exports, or skip
6. Validation — confirm the dev server starts, all endpoints respond, credentials work
7. Done — auto-opens http://localhost:3000 and prints next steps

Existing .env.local should auto-back-up to .env.local.backup-{ISO_TIMESTAMP} before being overwritten.

What the user types

curl -sSL https://csf-profile.example.com/install.sh | bash

…or, for users who want to inspect the script first:

git clone https://github.com/CPAtoCybersecurity/csf_profile.git
cd csf_profile && ./install.sh

Both end at the same wizard.

Why this approach over alternatives

• vs. Electron / Tauri desktop app: no notarization, no signing, no per-OS binaries, no ~100MB download. Reuses the Node toolchain the project already requires.
• vs. CLI prompts (inquirer-style): much friendlier for non-terminal-native GRC users, supports validation/test-connection buttons, easier to add screenshots and inline help.
• vs. Docker: Docker is already noted as planned for _future/ — a web installer is complementary, not a replacement, and unblocks users who don't want to run Docker locally.

Scope / non-goals for v1

• ✅ macOS + Linux bash bootstrap
• ✅ Windows PowerShell bootstrap
• ✅ Atlassian credentials, demo data seeding, encryption password
• ✅ .env.local backup-before-overwrite
• ❌ Auto-installing Node (instruct + link to nodejs.org if missing — same as current README)
• ❌ Continuous-monitoring / GRC platform features (out of scope for the assessment tool itself)
• ❌ Hosted / multi-user installer (this is local-only)

Acceptance criteria

• One-liner install works on macOS, Linux, and Windows (PowerShell variant)
• Wizard runs entirely on localhost, never sends credentials anywhere
• All four REACT_APP_* variables can be configured through the UI and written to .env.local
• Existing .env.local is backed up with timestamp before overwrite
• Alma Security demo data can be loaded or skipped from the wizard
• Test connection works for both Jira and Confluence credentials
• Wizard exits cleanly and npm start is running when the user lands on the app
• install.sh is auditable (single file, readable, no obfuscation) — users can curl and read it before piping to bash

References

• Current manual setup section in this repo's README

Related / follow-ups

• Could share the same installer scaffolding with the planned Docker setup (_future/docker/) — wizard could offer "local Node" or "Docker" as an install mode in a later version.
• A --headless flag on install.sh for power users who want to skip the wizard and pass everything as env vars / CLI args (useful for CI and reproducible setups).

[evanoseen]

✅ Guided Installer Wizard — Implemented

PR #193 implements everything described in this issue.

What was built

File	Purpose
install.sh	POSIX bootstrap (macOS + Linux + WSL); ~102 lines, readable
install.ps1	Windows PowerShell equivalent
installer/server.js	Local HTTP server — 127.0.0.1:31338 only, Node built-ins only
installer/wizard.html	Self-contained 7-step dark-themed wizard, no external JS deps

All acceptance criteria met

• ✅ One-liner install works on macOS, Linux (and PowerShell on Windows)
• ✅ Wizard runs entirely on localhost — server binds to 127.0.0.1 only
• ✅ All four REACT_APP_* variables configurable through the UI and written to .env.local
• ✅ Existing .env.local backed up to .env.local.backup-{ISO_TIMESTAMP} before overwrite
• ✅ Alma Security demo data can be loaded or skipped from the wizard
• ✅ Test Connection works for Jira and Confluence (proxied server-side to avoid CORS)
• ✅ Wizard exits cleanly and npm start runs as detached process when the user reaches Done
• ✅ install.sh is fully auditable (single file, readable, no obfuscation)
• ✅ Zero new npm packages added

Usage

# Already cloned:
./install.sh

# Or pipe-to-bash:
curl -sSL https://raw.githubusercontent.com/CPAtoCybersecurity/csf_profile/main/install.sh | bash

→ PR #193: #193