Replace cobra.OnInitialize with PersistentPreRun pattern to fix initialization
issues with setup and server commands. This follows Cobra best practices and
allows subcommands to properly override initialization behavior.
Problem:
- OnInitialize runs globally before command parsing
- os.Args check for 'setup' was fragile and broke with flags
- Setup wizard failed on server: 'unable to open database file: no such file
or directory'
Solution:
- Use rootCmd.PersistentPreRun for initialization (inherited by all commands)
- setup and server commands override with their own PersistentPreRun
- Directory overrides still applied correctly in all cases
- Removes fragile os.Args parsing
Benefits:
- Works regardless of flag order
- Follows Cobra's intended design patterns
- Only 3 files modified (root.go, setup.go, server.go)
- Commands that need custom init (setup/server) simply override
- All other commands get automatic initialization
- Cleaner, more maintainable code
Testing:
- ✓ opal setup works without initialization errors
- ✓ opal list initializes database correctly
- ✓ First-run detection still works
- ✓ Directory overrides work with flags in any position
- ✓ Server command handles its own initialization
Implement a comprehensive setup wizard to improve onboarding and
configuration experience for both personal and server deployments.
Key features:
- Interactive wizard with profile selection (personal/server/custom)
- Quick setup mode with sensible defaults
- First-run detection with helpful welcome message
- Directory configuration with validation
- Server OAuth/JWT configuration with auto-generation
- Environment file creation for server deployments
- Template generators for systemd service and env files
New commands:
- opal setup # Interactive wizard
- opal setup --quick # Quick setup with defaults
- opal setup --profile # Use specific profile
- opal setup --show-systemd # Show systemd template
- opal setup --show-env # Show environment file template
Implementation:
- internal/wizard/prompts.go: Reusable prompt utilities
- internal/wizard/profiles.go: Profile definitions and templates
- cmd/setup.go: Main setup command implementation
- cmd/root.go: First-run detection and welcome message
- internal/engine/config.go: ConfigExists() and IsFirstRun() helpers
User experience:
- On first run, shows welcome message suggesting 'opal setup'
- Non-intrusive - creates defaults automatically if skipped
- Wizard guides through all configuration options
- Server setup includes OAuth/JWT configuration
- Environment file created with proper permissions (0600)
- Clear next steps displayed after completion
Separate configuration from data storage and make paths configurable
via environment variables and command-line flags. This improves
Unix/Linux compliance and supports both development and production
deployments.
Key changes:
- Separate config dir (opal.yml) from data dir (database, logs)
- Support XDG Base Directory specification
- Add --config-dir and --data-dir flags
- Environment variables: OPAL_CONFIG_DIR, OPAL_DATA_DIR, OPAL_DB_PATH
- Smart fallback: /etc/opal, /var/lib/opal -> ~/.config/opal, ~/.local/share/opal
- Server mode validates required OAuth/JWT environment variables
- Update naming from 'jade' to 'opal' throughout
- Update systemd service name to 'opal.service'
- Add migration guide in README
Default paths:
- Config: /etc/opal (fallback: ~/.config/opal)
- Data: /var/lib/opal (fallback: ~/.local/share/opal)
Files modified:
- internal/engine/config.go: New directory resolution logic
- internal/engine/database.go: Auto-create data directory
- cmd/root.go: Add global flags for directory overrides
- cmd/server.go: Add configuration validation
- cmd/sync.go, internal/sync/*: Use new path helper functions
- tests: Update to use directory overrides
- docs: Update deployment guide and README
- Add urgency calculation based on multiple factors:
* Due date (linear scale: overdue=12.0, today=10.0, week=6.0, 2weeks=2.0)
* Priority (H=6.0, M=3.9, D=1.8, L=0.0)
* Age (0-2.0 over 365 days)
* Active status (+4.0 boost)
* Waiting status (-3.0 penalty)
* Tags (+1.0 with count modifier)
* Project assignment (+1.0)
* Configurable urgent tag (default 'next', +15.0)
- Replace priority column with urgency in all reports
* Display as decimal with 1 decimal place
* 4-tier color coding: ≥10 (bright red), ≥5 (red), ≥2 (yellow), <2 (cyan)
* Minimal format color-coded by urgency
- Add default urgency sorting to all reports
* list, minimal, active, ready, overdue reports sort by urgency
* newest/oldest keep date-based sorting
- Implement 'next' report
* Shows most urgent ready tasks
* Configurable limit (default 5)
* Only includes tasks ready to work on (no future wait/scheduled)
- Add urgency display to info command
* Shows urgency score alongside priority
- All urgency coefficients configurable via config
* Adjusted defaults for Opal's simpler model (no blocking/annotations)
* Configurable urgent tag name (not hardcoded to 'next')
Priority order maintained: High > Medium > Default > Low
- Fix template task filtering bug: templates now hidden from all reports
except 'template' and 'all' reports, even when using custom filters
- Add support for status:template filter to explicitly show templates
- Implement comprehensive report system with 12 predefined reports:
* active - Started tasks
* all - All tasks including templates
* completed - Completed tasks
* list - Pending tasks (default)
* minimal - Pending tasks in minimal format
* newest - Most recent pending tasks
* oldest - Oldest pending tasks
* overdue - Overdue tasks
* ready - Tasks ready to work on
* recurring - Pending recurring instances
* template - Recurring template tasks
* waiting - Hidden/waiting tasks
- Replace list command with report-based architecture
- Add configurable default_report option (defaults to 'list')
- Add minimal display format (ID + description only)
- Support flexible syntax: 'opal <report> [filters]' or 'opal [filters] <report>'
- Add 'opal reports' command to list all available reports
- Created comprehensive sync command suite:
- 'opal sync init' - Configure sync with server (URL, API key)
- 'opal sync status' - Show sync configuration and queue status
- 'opal sync now' - Bidirectional sync with conflict resolution
- 'opal sync up' - Push local changes to server
- 'opal sync down' - Pull server changes to local
- 'opal sync log' - View conflict resolution log
- Added interactive prompts for init (URL and API key)
- Automatic client ID generation (UUID)
- Display user-friendly sync results with emojis
- Support for viewing queued offline changes
- Integration with config system for persistent sync settings
- Add 'opal info' command to display detailed task information
- Shows all task attributes including UUID, timestamps, and metadata
- Supports flexible syntax (opal info 2 or opal 2 info)
- Displays recurrence information and parent UUID for recurring tasks
- Add 'opal edit' command to edit tasks in $EDITOR
- Opens task in text editor with human-readable format
- Supports all editable fields with smart date formatting
- Special handling for recurring tasks (updates parent template)
- Status changes trigger appropriate methods (Complete/Delete)
- Auto-saves changes on editor exit without confirmation
- Clear validation and error messages
- Register new commands in root command dispatcher
Previously, 'opal -h', 'opal --help', and 'opal help' would show the
list command help instead of the root command help. This was because
the argument preprocessing logic would rewrite these as 'opal list -h'
before Cobra could handle them.
Now we detect help flags/command before preprocessing and let Cobra
handle them naturally. This ensures:
- 'opal -h' and 'opal --help' show root help
- 'opal help' shows root help
- 'opal help <command>' shows command-specific help
- 'opal <command> -h' still shows command-specific help
- All existing flexible syntax continues to work
Issue 1: Fix recurrence calculation for overdue tasks
- Use completion date (End) as base for next instance, not original due date
- If task due Monday completed Wednesday, next is Wednesday+7d not Monday+7d
- Fallback to Due date if End is not set
- Update test to verify new behavior
Issue 2: Fix description parsing to work without quotes
- Add parseAddArgs() to extract description from non-modifier words
- Description = all words that don't start with +, -, or contain :
- Enables: opal add buy groceries +shop carrots → 'buy groceries carrots'
- Validate description is required (error if only modifiers)
- Validate recurring tasks require due date
Issue 3: Implement flexible command syntax
- Add preprocessArgs() to parse arguments before Cobra routing
- Detect command position and split filters (left) from modifiers (right)
- Rewrite os.Args so Cobra routes correctly
- Enable both 'opal 2 done' and 'opal done 2' syntax
- Commands without modifiers accept filters on either side
- Commands with modifiers enforce [filters] command [modifiers]
- Add confirmation for modify without filters (modifies all tasks)
All commands updated to use preprocessed ParsedArgs from context.
All tests passing (33 tests).
Phase 6: Display and Basic Commands
- Add display.go with colored formatting for tasks, projects, tags
- Implement cmd/root.go with Cobra command structure
- Implement cmd/list.go for listing and filtering tasks
- Implement cmd/add.go with support for regular and recurring tasks
- Implement cmd/done.go with bulk completion and confirmation
Phase 7: Advanced Commands
- Implement cmd/modify.go for updating task attributes
- Implement cmd/delete.go with soft delete confirmation
- Implement cmd/start.go and cmd/stop.go for task timing
- Implement cmd/count.go for counting filtered tasks
- Implement cmd/projects.go and cmd/tags.go for aggregation
Phase 8: Integration and Polish
- Update main.go to use CLI commands
- Add colored output with fatih/color
- Format task lists with proper alignment
- Highlight overdue tasks in red, upcoming in yellow
- Test end-to-end workflow: add, list, done, recurring tasks
- Verify recurrence spawning works correctly
All CLI commands functional and tested!
joakim