Redesign setup.sh: interactive wizard with guided key entry & live health dashboard#89
Merged
Merged
Conversation
Make the setup experience interactive, transparent, and easy to follow. Live progress & health - Stop piping `docker compose pull`/`up` through `tail` — that forced Docker's silent/plain mode and hid the per-layer download bars. Stream the output so the native progress UI renders in real time. - Add a colorized, in-place live service-health dashboard that polls `docker compose ps` and refreshes until services report healthy. Interactive AI client choice (with sub-choices) - Provider menu (Claude / ChatGPT / DeepSeek); Claude expands to Claude Code (Docker), Claude Code (Web), or Claude Desktop. The choice drives which profile starts, whether the MCP Gateway is enabled, and which key (if any) is requested. Guided API keys - For each key, explain what it's for, where it's used, and the exact steps to obtain it; every key is optional and skippable. Secrets are read hidden and never echoed. Neo4j: none / local / Aura - Local starts the neo4j Docker profile; Aura walks through console.neo4j.io and stores the cloud connection details in .env without starting a local container. Safety/robustness - New set_env helper removes prior (commented or active) definitions and appends the value verbatim — never passing user values through sed (injection-safe; handles passwords with | & \). - Detect non-interactive stdin and fall back to flag-driven defaults; all existing flags preserved. up -d guarded so the health dashboard always renders. Docs: sync README install steps and DOCKER.md wizard description. https://claude.ai/code/session_0111sKEqbgpbAZKAYDuQmcHa
Layered, opt-out-safe UX improvements on top of the guided wizard. No change to existing logic or contracts; all additions degrade gracefully. - Pre-flight confirmation: before pulling images or starting containers, show a review of every selection (AI client, knowledge graph, gateway) and the exact actions about to run, then ask "Proceed?". Declining exits cleanly with .env saved. Skipped in non-interactive runs. - Missing-key warning: if the chosen containerized client's key was skipped, the summary now says so prominently with the one-line fix, instead of pointing at a launch command that would fail to start. - Secret-file hardening: chmod 600 on .env (it holds live secrets). - Non-blocking input validation: warn on unexpected API-key prefixes (offer to save anyway) and loop until a Neo4j password is >=8 chars (Neo4j 5 rejects shorter ones and won't start). - Modern terminal output: honor NO_COLOR and auto-disable color when stdout isn't a TTY (clean piped/CI logs); render URLs as OSC 8 hyperlinks with a plain-text fallback for terminals without support. https://claude.ai/code/session_0111sKEqbgpbAZKAYDuQmcHa
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
2 participants
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.
Summary
Completely redesigns
setup.shfrom a minimal one-command setup into a professional, guided interactive wizard that walks users through AI client selection, knowledge graph configuration, API key entry (with step-by-step help for each), and live service health monitoring. The wizard is fully non-interactive-friendly for CI/scripted runs while remaining user-friendly for interactive terminal sessions.Key Changes
Interactive Wizard Flow
Terminal & Color Handling
NO_COLORconventionNO_COLORis unsetLive Health Dashboard
render_status()function redraws service health table in place on TTYwait_for_health()API Key Entry with Validation
prompt_secret()reads keys without echoing, never prints values backkey_format_ok()soft-validates key prefixes (sk-ant-, sk-*) non-blockinglyset_env()safely writes KEY=VALUE to .env without sed escaping pitfallsNon-Interactive Mode
--api-keyand--deepseek-keyflags still work for scripted runs--minimaldisables all prompts and optional profiles--with-neo4jand--with-gatewayflags preservedHelper Functions
add_profile()appends compose profiles without duplicatesask_yes_no()reads yes/no with default, respects non-TTY stdinread_choice()numeric menu reader with bounds checkinglink()renders OSC 8 terminal hyperlinks when color is enabledenv_has_value()checks if a key is set in .envOutput & Messaging
print_launch_hint()tailors next steps to the chosen AI clientDocumentation Updates
Notable Implementation Details
prompt_secret()writes to stderr for prompts, stdout for the value only (safe for command substitution). Values are never echoed back or logged.[ -t 0 ]for stdin,[ -t 1 ]for stdout; used to gate prompts and color codes independently.add_profile()uses case/pattern matching to avoid--profile neo4j --profile neo4jduplicates.https://claude.ai/code/session_0111sKEqbgpbAZKAYDuQmcHa