-
-
Notifications
You must be signed in to change notification settings - Fork 75
Complete Phase 2: Setup Automation & Dependency Checking #7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
74ab2da
feat(02-01): rewrite setup.sh with dependency checker, OS detection, …
claude f0c0b39
docs(02-01): complete dependency checker plan
claude f01f48e
feat(02-02): add directory creation, config scaffolding, progress tra…
claude 1ef6a53
test(02-02): rewrite integration test for new setup.sh behavior
claude fd9df8c
docs(02-02): complete directory creation and config scaffolding plan
claude 0f3492d
docs(02): complete setup automation phase
claude 9fc2102
Update tests/integration/test_setup_onboarding_integration.sh
AojdevStudio 1fd7939
fix(02): address PR review comments from CodeRabbit
AojdevStudio 404a932
docs(11): capture phase context for Self-Assessment & Persistence
AojdevStudio 13b85a8
Background task: /gsd:plan-phase 11
AojdevStudio 8e3857b
fix(02): guard eval against non-executable install strings
AojdevStudio 1c01e0a
🔀 chore: merge origin/main into claude/execute-phase-2-cKSy5
AojdevStudio 11997f0
docs: update CLAUDE.md with session learnings
AojdevStudio File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| --- | ||
| phase: 02-setup-automation | ||
| plan: 01 | ||
| subsystem: infra | ||
| tags: [bash, setup, dependency-checker, os-detection, cli, color-output] | ||
|
|
||
| # Dependency graph | ||
| requires: | ||
| - phase: none | ||
| provides: "First plan in phase 2, no prior phase dependency" | ||
| provides: | ||
| - "setup.sh dependency checker with OS detection and version comparison" | ||
| - "--check-deps-only dry-run flag" | ||
| - "--help usage flag" | ||
| - "Auto-install prompts for missing dependencies" | ||
| - "Placeholder section for Plan 02 directory creation and config scaffolding" | ||
| affects: [02-02-PLAN, 03-onboarding-wizard] | ||
|
|
||
| # Tech tracking | ||
| tech-stack: | ||
| added: [] | ||
| patterns: | ||
| - "sort -V for version comparison (avoids arithmetic pitfall)" | ||
| - "check-all-then-fail with set -e + || guards" | ||
| - "Terminal color detection with tty + TERM fallback" | ||
| - "printf for all colored output (not echo -e)" | ||
| - "command -v for dependency detection (not which)" | ||
| - "grep -oE for version extraction (not grep -oP for macOS compat)" | ||
|
|
||
| key-files: | ||
| created: [] | ||
| modified: | ||
| - "setup.sh" | ||
|
|
||
| key-decisions: | ||
| - "Used sort -V for version comparison instead of arithmetic (avoids Python 4.x false negative)" | ||
| - "Used ${TERM:-dumb} default for unset TERM in CI/cron environments" | ||
| - "Check all deps before failing (accumulate with || guards under set -e)" | ||
| - "Auto-install prompt only in interactive mode ([ -t 0 ] guard)" | ||
| - "OS-specific install commands: brew for macOS, apt for Linux/WSL, curl for uv/Bun" | ||
|
|
||
| patterns-established: | ||
| - "setup.sh section structure: color detection -> helpers -> OS detection -> version comparison -> dep checking -> CLI parsing -> main flow" | ||
| - "check-all-then-fail accumulator pattern for set -e scripts" | ||
|
|
||
| # Metrics | ||
| duration: 6min | ||
| completed: 2026-02-04 | ||
| --- | ||
|
|
||
| # Phase 2 Plan 1: Dependency Checker Summary | ||
|
|
||
| **Pure-bash dependency checker with OS detection, sort -V version comparison, color output, CLI flags (--check-deps-only, --help), and auto-install prompts** | ||
|
|
||
| ## Performance | ||
|
|
||
| - **Duration:** 6 min | ||
| - **Started:** 2026-02-04T03:22:56Z | ||
| - **Completed:** 2026-02-04T03:29:11Z | ||
| - **Tasks:** 2 | ||
| - **Files modified:** 1 | ||
|
|
||
| ## Accomplishments | ||
| - Rewrote setup.sh from scratch (329 new lines replacing 357 old lines) | ||
| - Dependency checker validates Python 3.12+, uv, and Bun with check-all-then-fail pattern | ||
| - OS detection correctly identifies macOS/Linux/WSL with package manager lookup | ||
| - Color output in terminals, plain text in pipes (verified with cat -v) | ||
| - --check-deps-only flag performs dry-run check without filesystem modifications | ||
| - Auto-install prompts with tty guard for non-interactive environments | ||
| - version_gte correctly handles edge cases: 3.14 >= 3.12, 3.10 < 3.12, 4.1 >= 3.12, 3.12 >= 3.12 | ||
| - Placeholder section for Plan 02 functions (directory creation, config scaffolding, Python deps) | ||
|
|
||
| ## Task Commits | ||
|
|
||
| Each task was committed atomically: | ||
|
|
||
| 1. **Task 1: Rewrite setup.sh with header, color detection, utility functions, and CLI args** - `74ab2da` (feat) | ||
| 2. **Task 2: Verify dependency checker against all four success criteria paths** - _verification only, no code changes_ | ||
|
|
||
| ## Files Created/Modified | ||
| - `setup.sh` - Complete rewrite: dependency checker, OS detection, color output, CLI args, auto-install prompts | ||
|
|
||
| ## Decisions Made | ||
| - Used `sort -V` for version comparison instead of arithmetic splitting -- avoids the critical bug where `4.1 >= 3.12` incorrectly fails (RESEARCH.md Pitfall 1) | ||
| - Used `${TERM:-dumb}` default for unset TERM -- prevents ANSI codes leaking in CI/cron where TERM is unset (RESEARCH.md Pitfall 3) | ||
| - Checked `command -v brew` before offering brew install commands -- prevents "command not found: brew" during auto-install (RESEARCH.md Pitfall 6) | ||
| - Used `[ -t 0 ]` guard before `read` prompts -- prevents script hanging in non-interactive contexts (RESEARCH.md Pitfall 4) | ||
| - Removed Steps 8-11 from old script (symlinks, onboarding, MCP Launchpad) -- out of scope per plan | ||
|
|
||
| ## Deviations from Plan | ||
|
|
||
| None - plan executed exactly as written. | ||
|
|
||
| ## Issues Encountered | ||
|
|
||
| None. | ||
|
|
||
| ## User Setup Required | ||
|
|
||
| None - no external service configuration required. | ||
|
|
||
| ## Next Phase Readiness | ||
| - setup.sh dependency checker is complete and verified | ||
| - Ready for 02-02-PLAN.md: directory creation, config scaffolding, .setup-progress tracking, idempotent re-runs | ||
| - Plan 02 will fill in the placeholder functions: create_directory_structure, scaffold_config_files, install_python_deps, print_summary | ||
| - Note: dev environment has python3 at 3.11 (python3.12 available separately) -- the script correctly identifies this version mismatch | ||
|
|
||
| --- | ||
| _Phase: 02-setup-automation_ | ||
| _Completed: 2026-02-04_ | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| --- | ||
| phase: 02-setup-automation | ||
| plan: 02 | ||
| subsystem: infra | ||
| tags: [bash, setup-script, idempotency, progress-tracking, uv, directory-scaffolding] | ||
|
|
||
| # Dependency graph | ||
| requires: | ||
| - phase: 02-setup-automation/01 | ||
| provides: "Dependency checker with OS detection, color output, CLI args, --check-deps-only" | ||
| provides: | ||
| - "Complete setup.sh: directory creation, config scaffolding, progress tracking, Python deps, summary" | ||
| - "Idempotent re-run via .setup-progress file-level tracking" | ||
| - "fin-guru-private/ directory tree with hedging, strategies, analysis subdirs" | ||
| - "user-profile.yaml template for Phase 3 onboarding wizard to populate" | ||
| - "Integration test covering first run, idempotency, missing dir detection, --check-deps-only, --help" | ||
| affects: [03-onboarding-wizard, 06-config-models] | ||
|
|
||
| # Tech tracking | ||
| tech-stack: | ||
| added: [] | ||
| patterns: | ||
| - "Progress file (.setup-progress) with line-per-step format for resumable setup" | ||
| - "scaffold_file() with [ -t 0 ] tty check for overwrite prompts" | ||
| - "verify_directory_structure() runs on EVERY path for structural validation" | ||
| - "File-level idempotency (skip or prompt) -- field-level YAML merging deferred to Phase 3" | ||
|
|
||
| key-files: | ||
| created: | ||
| - ".planning/phases/02-setup-automation/02-02-SUMMARY.md" | ||
| modified: | ||
| - "setup.sh" | ||
| - ".gitignore" | ||
| - "tests/integration/test_setup_onboarding_integration.sh" | ||
|
|
||
| key-decisions: | ||
| - "File-level idempotency only: scaffold_file skips existing files or prompts for full overwrite. Field-level YAML merging deferred to Phase 3 onboarding wizard (ONBD-06 scope boundary)" | ||
| - "verify_directory_structure runs on every execution path (first run AND re-run) to catch missing subdirs even when dirs_created is already in progress file" | ||
| - "5 trackable milestones: deps_checked, dirs_created, dirs_verified, config_scaffolded, python_deps_installed" | ||
| - "User-profile.yaml placed at fin-guru/data/ (tracked in git as template) rather than fin-guru-private/ (gitignored)" | ||
|
|
||
| patterns-established: | ||
| - "Progress tracking: is_step_complete/mark_step_complete with grep-based line matching" | ||
| - "Config scaffolding: scaffold_file handles tty detection, overwrite prompt defaults to N" | ||
| - "Summary reporting: CREATED_ITEMS/SKIPPED_ITEMS arrays for end-of-run report" | ||
|
|
||
| # Metrics | ||
| duration: 11min | ||
| completed: 2026-02-04 | ||
| --- | ||
|
|
||
| # Phase 2 Plan 2: Directory Creation, Config Scaffolding, and Idempotent Re-runs Summary | ||
|
|
||
| **Complete setup.sh with fin-guru-private/ directory tree, user-profile.yaml/env/README scaffolding, .setup-progress resumable tracking, uv sync Python deps, and 46-assertion integration test** | ||
|
|
||
| ## Performance | ||
|
|
||
| - **Duration:** 11 min | ||
| - **Started:** 2026-02-04T03:34:51Z | ||
| - **Completed:** 2026-02-04T03:46:21Z | ||
| - **Tasks:** 3 (Task 2 was verification-only, no code changes needed) | ||
| - **Files modified:** 3 | ||
|
|
||
| ## Accomplishments | ||
| - setup.sh creates all 20+ directories under fin-guru-private/ including hedging/, strategies/active|archive|risk-management, analysis/reports, and notebooks tree | ||
| - Config scaffolding with scaffold_file() creates user-profile.yaml template, .env from .env.example, and fin-guru-private/README.md with tty-aware overwrite prompts | ||
| - .setup-progress tracks 5 milestones for resumable re-runs; second run shows "Resuming setup... (5/5 steps completed)" and skips completed steps | ||
| - verify_directory_structure runs on every execution path, detecting and recreating missing subdirectories even when the progress file shows dirs_created as complete | ||
| - Integration test rewritten with 46 assertions covering first run, --check-deps-only isolation, idempotent re-run, missing directory detection, and --help flag | ||
|
|
||
| ## Task Commits | ||
|
|
||
| Each task was committed atomically: | ||
|
|
||
| 1. **Task 1: Add progress tracking, directory creation, config scaffolding, Python deps, and summary** - `f01f48e` (feat) | ||
| 2. **Task 2: Implement idempotent re-run behavior and verify SC4** - No commit (verification-only, all behavior correct from Task 1) | ||
| 3. **Task 3: Update integration test for new setup.sh behavior** - `1ef6a53` (test) | ||
|
|
||
| ## Files Created/Modified | ||
| - `setup.sh` - Added 8 new functions: is_step_complete, mark_step_complete, show_progress, create_dir, create_directory_structure, verify_directory_structure, scaffold_file, scaffold_config_files, install_python_deps, print_summary. Updated main flow with step-based execution. | ||
| - `.gitignore` - Added .setup-progress exclusion in Family Office section | ||
| - `tests/integration/test_setup_onboarding_integration.sh` - Complete rewrite: 46 assertions across 5 test groups, removed all old onboarding/symlink/MCP references | ||
|
|
||
| ## Decisions Made | ||
| - **File-level idempotency scope boundary (ONBD-06):** scaffold_file handles skip/overwrite at file level only. Field-level YAML merging (parsing existing user-profile.yaml to add missing keys) deferred to Phase 3 onboarding wizard per CONTEXT.md: "setup.sh prepares the environment, it does not collect financial profile data." | ||
| - **verify_directory_structure on every path:** Even on first run after create_directory_structure, we run verify. This catches scenarios where dirs already existed from a prior partial run but are missing expected subdirectories. | ||
| - **user-profile.yaml at fin-guru/data/ (not fin-guru-private/):** The template is committed to git so new clones get it. Phase 3 onboarding will populate it with user data into the gitignored fin-guru-private/ location or update this template in place. | ||
| - **Non-interactive default for scaffold_file:** When stdin is not a tty, existing files are kept without prompting. This prevents CI/test hangs. | ||
|
|
||
| ## Deviations from Plan | ||
|
|
||
| None - plan executed exactly as written. Task 2 (idempotency verification) required zero code fixes; all four scenarios passed on first attempt. | ||
|
|
||
| ## Issues Encountered | ||
| - **Python 3.12 not default in dev environment:** `python3` resolves to 3.11 in this environment while `python3.12` is available at `/usr/bin/python3.12`. Handled via PATH override in testing and in the integration test's PATH Setup section. This is an environment-specific issue, not a script bug -- the dependency checker correctly reports the version mismatch. | ||
|
|
||
| ## User Setup Required | ||
|
|
||
| None - no external service configuration required. | ||
|
|
||
| ## Next Phase Readiness | ||
| - setup.sh is fully functional: `./setup.sh` on a fresh clone creates working environment | ||
| - Phase 2 is complete (both plans done): dependency checking + directory/config setup | ||
| - Ready for Phase 3 (Onboarding Wizard): user-profile.yaml template exists at fin-guru/data/, onboarding wizard will populate it with interactive financial profile data | ||
| - fin-guru-private/ directory structure is in place for hedging tools (Phase 6) and analysis outputs | ||
|
|
||
| --- | ||
| _Phase: 02-setup-automation_ | ||
| _Completed: 2026-02-04_ |
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fix typo (“separately”).
Line 106 appears to have a truncated word (“separatel”).
✏️ Suggested fix
🧰 Tools
🪛 LanguageTool
[grammar] ~106-~106: Ensure spelling is correct
Context: ...int_summary - Note: dev environment has python3 at 3.11 (python3.12 available separatel...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents