refactor: implement configurable directory structure with XDG support

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

opal-task/cmd/reports.go

@@ -86,7 +86,7 @@ var reportsCmd = &cobra.Command{
 		}
 		sort.Strings(names)
 
-		fmt.Println("Available reports:\n")
+		fmt.Println("Available reports:")
 		for _, name := range names {
 			report := reports[name]
 			fmt.Printf("  %-12s %s\n", name, report.Description)

opal-task/cmd/root.go

@@ -21,6 +21,12 @@ type contextKey string
 
 const parsedArgsKey contextKey = "parsedArgs"
 
+// Global flags
+var (
+	configDirFlag string
+	dataDirFlag   string
+)
+
 // Command classification
 var commandNames = []string{
 	"add", "done", "modify", "delete",
@@ -188,6 +194,12 @@ func preprocessArgs(args []string) *ParsedArgs {
 }
 
 func init() {
+	// Add persistent flags for directory overrides
+	rootCmd.PersistentFlags().StringVar(&configDirFlag, "config-dir", "",
+		"Config directory (default: $XDG_CONFIG_HOME/opal or ~/.config/opal)")
+	rootCmd.PersistentFlags().StringVar(&dataDirFlag, "data-dir", "",
+		"Data directory (default: $XDG_DATA_HOME/opal or ~/.local/share/opal)")
+
 	cobra.OnInitialize(initializeApp)
 
 	// Add regular subcommands
@@ -212,6 +224,14 @@ func init() {
 }
 
 func initializeApp() {
+	// Set directory overrides from flags if provided
+	if configDirFlag != "" {
+		engine.SetConfigDirOverride(configDirFlag)
+	}
+	if dataDirFlag != "" {
+		engine.SetDataDirOverride(dataDirFlag)
+	}
+
 	// Initialize database
 	if err := engine.InitDB(); err != nil {
 		fmt.Fprintf(os.Stderr, "Error initializing database: %v\n", err)

opal-task/cmd/server.go

@@ -3,12 +3,76 @@ package cmd
 import (
 	"fmt"
 	"os"
+	"strings"
 
 	"git.jnss.me/joakim/opal/internal/api"
 	"git.jnss.me/joakim/opal/internal/engine"
 	"github.com/spf13/cobra"
 )
 
+// validateServerConfig checks that all required environment variables are set for server mode
+func validateServerConfig() error {
+	// Check required OAuth/JWT environment variables
+	required := map[string]string{
+		"OAUTH_CLIENT_ID":     os.Getenv("OAUTH_CLIENT_ID"),
+		"OAUTH_CLIENT_SECRET": os.Getenv("OAUTH_CLIENT_SECRET"),
+		"OAUTH_ISSUER":        os.Getenv("OAUTH_ISSUER"),
+		"OAUTH_REDIRECT_URI":  os.Getenv("OAUTH_REDIRECT_URI"),
+		"JWT_SECRET":          os.Getenv("JWT_SECRET"),
+	}
+
+	missing := []string{}
+	for key, value := range required {
+		if value == "" {
+			missing = append(missing, key)
+		}
+	}
+
+	if len(missing) > 0 {
+		return fmt.Errorf("missing required environment variables for server mode:\n  %s\n\nPlease set these variables before starting the server.", strings.Join(missing, "\n  "))
+	}
+
+	// Validate data directory is writable
+	dataDir, err := engine.GetDataDir()
+	if err != nil {
+		return fmt.Errorf("cannot resolve data directory: %w", err)
+	}
+
+	// Check if directory exists and is writable
+	info, err := os.Stat(dataDir)
+	if err != nil {
+		// Directory doesn't exist yet, check parent
+		parent := dataDir
+		for parent != "/" && parent != "." {
+			parent = strings.TrimSuffix(parent, "/")
+			idx := strings.LastIndex(parent, "/")
+			if idx <= 0 {
+				parent = "/"
+				break
+			}
+			parent = parent[:idx]
+			if parent == "" {
+				parent = "/"
+			}
+
+			if pInfo, pErr := os.Stat(parent); pErr == nil {
+				if !pInfo.IsDir() {
+					return fmt.Errorf("parent path is not a directory: %s", parent)
+				}
+				// Check write permission by trying to create data dir
+				if err := os.MkdirAll(dataDir, 0755); err != nil {
+					return fmt.Errorf("data directory not writable: %s (error: %v)", dataDir, err)
+				}
+				break
+			}
+		}
+	} else if !info.IsDir() {
+		return fmt.Errorf("data directory path exists but is not a directory: %s", dataDir)
+	}
+
+	return nil
+}
+
 var serverCmd = &cobra.Command{
 	Use:   "server",
 	Short: "Server management commands",
@@ -33,6 +97,12 @@ Examples:
 			os.Setenv("OPAL_DB_PATH", dbPath)
 		}
 
+		// Validate server configuration
+		if err := validateServerConfig(); err != nil {
+			fmt.Fprintf(os.Stderr, "Server configuration validation failed:\n%v\n", err)
+			os.Exit(1)
+		}
+
 		// Initialize database
 		if err := engine.InitDB(); err != nil {
 			fmt.Fprintf(os.Stderr, "Error initializing database: %v\n", err)

opal-task/cmd/sync.go

@@ -286,13 +286,11 @@ var syncLogCmd = &cobra.Command{
 	Short: "Show conflict resolution log",
 	Long:  `Display the log of sync conflicts and how they were resolved`,
 	Run: func(cmd *cobra.Command, args []string) {
-		configDir, err := engine.GetConfigDir()
+		logPath, err := engine.GetSyncConflictLogPath()
 		if err != nil {
 			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 			os.Exit(1)
 		}
-
-		logPath := fmt.Sprintf("%s/sync_conflicts.log", configDir)
 		data, err := os.ReadFile(logPath)
 		if err != nil {
 			if os.IsNotExist(err) {