Skip to content

feat: guided web installer wizard (issue #191)#193

Open
evanoseen wants to merge 3 commits into
mainfrom
191-guided-installer-wizard
Open

feat: guided web installer wizard (issue #191)#193
evanoseen wants to merge 3 commits into
mainfrom
191-guided-installer-wizard

Conversation

@evanoseen

Copy link
Copy Markdown
Collaborator

Summary

Implements the guided web installer wizard described in issue #191. Replaces the manual setup flow (git clone → npm install → set env vars → npm start) with a single-command bootstrap that opens a styled 7-step browser wizard on localhost:31338.

  • install.sh — POSIX-compatible bootstrap for macOS + Linux; checks Node 18+ and Git, runs npm install, spawns installer server, opens browser
  • install.ps1 — Windows PowerShell equivalent
  • installer/server.js — Local HTTP server binding only to 127.0.0.1:31338; uses only Node built-ins (no new npm deps); serves the wizard and exposes 6 API endpoints
  • installer/wizard.html — Self-contained dark-themed 7-step wizard (no external JS runtime deps)

What the user types

# Already have the repo:
./install.sh

# Fresh machine (inspect before running):
curl -sSL https://raw.githubusercontent.com/CPAtoCybersecurity/csf_profile/main/install.sh | bash

Wizard steps

Step Description
1 System Detection — Node version, Git, existing .env.local
2 Prerequisites — npm deps, server status
3 Atlassian Credentials (optional) — Jira + Confluence URL/token with Test Connection
4 Demo Data — Alma Security demo or start blank
5 Encryption Setup (optional) — password or skip
6 Launch — kicks off npm start, polls until port 3000 responds
7 Done — link to http://localhost:3000, auto-opens browser

Security

  • Server binds only to 127.0.0.1 — never 0.0.0.0
  • Atlassian credential test proxied server-side (no CORS leakage)
  • Existing .env.local backed up to .env.local.backup-{ISO_TIMESTAMP} before any overwrite
  • Zero new npm packages added to package.json

Test plan

  • Run bash install.sh from repo root on macOS — verify wizard opens at localhost:31338
  • Run bash install.sh from repo root on Linux/Kali — verify wizard opens
  • Run .\install.ps1 on Windows — verify wizard opens
  • Walk all 7 wizard steps with valid Atlassian credentials
  • Walk all 7 wizard steps skipping credentials (blank config)
  • Confirm npm start stays running after wizard closes
  • Confirm .env.local.backup-* created when overwriting existing .env.local
  • Confirm no outbound connections from installer server (Wireshark/Charles)

Closes #191

🤖 Generated with Claude Code

evanoseen and others added 2 commits April 28, 2026 11:42
Replaces manual setup steps with a single-command bootstrap that
opens a 7-step browser wizard on localhost:31338.

- install.sh: bash bootstrap for macOS/Linux (102 lines, auditable)
- install.ps1: PowerShell bootstrap for Windows
- installer/server.js: local Node HTTP server (built-ins only, binds
  to 127.0.0.1 only, never transmits credentials externally)
- installer/wizard.html: dark-themed 7-step setup wizard
  - Step 1: System Detection (Node 18+, Git, .env.local)
  - Step 2: Prerequisites confirmation
  - Step 3: Atlassian credentials (optional, skippable, Test Connection)
  - Step 4: Demo data choice (Alma Security / blank)
  - Step 5: Encryption password setup (optional)
  - Step 6: App launch + readiness polling
  - Step 7: Done with direct link to localhost:3000

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Bash 3.2 on macOS (arm64) treats the multi-byte UTF-8 bytes of the
horizontal ellipsis (U+2026, \xE2\x80\xA6) as part of variable names
when they immediately follow a $VAR reference. This caused
"INSTALLER_PORT?: unbound variable" at line 70 despite the variable
being set. Replaced all four instances with ASCII "..." to fix.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@CPAtoCybersecurity

Copy link
Copy Markdown
Owner

Hey @evanoseen, please resolve the conflicts on this one too — but hold off until #187 is merged. This branch carries the same store-file edits as #187, so once #187 lands, most of the overlap here should go away.

After #187 is in:

git fetch origin
git checkout 191-guided-installer-wizard
git rebase origin/main
# resolve any remaining conflicts → git add → git rebase --continue
git push --force-with-lease

Once the rebase is clean, please re-walk the wizard test plan locally — CodeQL passed before, but a bad merge can break runtime even when the code still compiles. Keep the three commits intact (no squash) so the work stays reviewable. Note: comprehensiveAssessmentData.js (10k lines, brand new on main) isn't part of this branch and shouldn't show up as a conflict — if it does, flag it here before continuing.

@evanoseen evanoseen self-assigned this May 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Guided web-based installer wizard

2 participants