@asobacloud/nehanda 0.0.0-stage → 0.3.0

package/lib/scripts/python-safety-checker.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+
+import ast
+import os
+import subprocess
+import sys
+
+class PythonSafetyChecker:
+    def __init__(self, root_path):
+        self.root_path = root_path
+        self.issues = []
+
+    def check(self):
+        self._check_dependencies()
+        self._run_bandit()
+        self._run_ruff()
+        self._run_ast_checks()
+        self._print_summary()
+
+    def _check_dependencies(self):
+        try:
+            import importlib.util
+            # Check if dependencies are available (imported but unused in code)
+            importlib.util.find_spec('bandit')
+            importlib.util.find_spec('ruff')
+        except ImportError:
+            print("ERROR: Missing dependencies. Please run 'pip install -r requirements-dev.txt' to install the required tools.")
+            sys.exit(1)
+
+    def _run_bandit(self):
+        print("Running bandit...")
+        try:
+            # Exclude safety checker itself, test files, and build artifacts from Bandit checks
+            result = subprocess.run(
+                ['bandit', '-r', self.root_path,
+                 '--exclude', 'scripts/python-safety-checker.py,tests/,*/test_*.py,.aws-sam/,build/,dist/,node_modules/,.venv/,venv/,./.venv-ci/,./.venv-configure-tests/,./_pt/,./.tvenv/,./.agent-venv/,.venv-ci/,.venv-configure-tests/,_pt/,.tvenv/,.agent-venv/'],
+                capture_output=True, text=True
+            )
+            # Only report High/Critical severity issues as errors (warnings are non-blocking)
+            if result.returncode == 1 and result.stdout:
+                # Parse output to find only High/Critical severity issues
+                lines = result.stdout.split('\n')
+                high_critical_issues = []
+                current_issue_lines = []
+                in_high_critical_issue = False
+                
+                for i, line in enumerate(lines):
+                    if '>> Issue:' in line:
+                        # Start of new issue
+                        if in_high_critical_issue and current_issue_lines:
+                            high_critical_issues.extend(current_issue_lines)
+                        current_issue_lines = [line]
+                        in_high_critical_issue = False
+                    elif 'Severity: High' in line or 'Severity: Critical' in line:
+                        in_high_critical_issue = True
+                        if current_issue_lines:
+                            current_issue_lines.append(line)
+                    elif in_high_critical_issue and current_issue_lines:
+                        current_issue_lines.append(line)
+                        # Stop collecting when we hit separator or next issue
+                        if line.startswith('--') or line.strip() == '':
+                            high_critical_issues.extend(current_issue_lines)
+                            current_issue_lines = []
+                            in_high_critical_issue = False
+                
+                # Add last issue if applicable
+                if in_high_critical_issue and current_issue_lines:
+                    high_critical_issues.extend(current_issue_lines)
+                
+                if high_critical_issues:
+                    filtered_output = '\n'.join(high_critical_issues)
+                    self.issues.append(("Bandit", filtered_output))
+        except FileNotFoundError:
+            self.issues.append(("Bandit", "ERROR: bandit is not installed or not in PATH."))
+
+    def _run_ruff(self):
+        print("Running ruff...")
+        try:
+            # Exclude Jupyter notebooks from Ruff checks (they have different structure)
+            result = subprocess.run(
+                ['ruff', 'check', self.root_path, '--exclude', '*.ipynb,node_modules,.venv-ci,.tvenv,.venv-configure-tests,.agent-venv,_pt'],
+                capture_output=True, text=True
+            )
+            # Only add Ruff issues if exit code is non-zero (actual errors found)
+            if result.returncode != 0 and result.stdout:
+                self.issues.append(("Ruff", result.stdout))
+            elif result.stdout and 'All checks passed!' not in result.stdout:
+                # Also handle cases where ruff outputs warnings but exit code is 0
+                self.issues.append(("Ruff", result.stdout))
+        except FileNotFoundError:
+            self.issues.append(("Ruff", "ERROR: ruff is not installed or not in PATH."))
+
+    def _run_ast_checks(self):
+        print("Running AST checks...")
+        
+        # Support scanning a single file directly
+        if os.path.isfile(self.root_path):
+            if self.root_path.endswith('.py'):
+                self._check_file_path(self.root_path)
+            return
+
+        for root, _, files in os.walk(self.root_path):
+            for file in files:
+                if file.endswith('.py'):
+                    path = os.path.join(root, file)
+                    # Skip safety checker itself, test files, and build artifacts
+                    if ('python-safety-checker.py' in path or
+                        '/test_' in path or
+                        '/tests/' in path or
+                        '/.aws-sam/' in path or
+                        '/build/' in path or
+                        '/dist/' in path or
+                        '/node_modules/' in path or
+                        '/.venv/' in path or
+                        '/.venv-ci/' in path or
+                        '/.tvenv/' in path or
+                        '/.venv-configure-tests/' in path or
+                        '/.agent-venv/' in path or
+                        '/_pt/' in path or
+                        '/venv/' in path):
+                        continue
+                    self._check_file_path(path)
+
+    def _check_file_path(self, path):
+        with open(path, 'r') as f:
+            try:
+                tree = ast.parse(f.read(), filename=path)
+                self._check_file(tree, path)
+            except SyntaxError as e:
+                self.issues.append(("AST", f"ERROR: Could not parse {path}: {e}"))
+
+    def _check_file(self, tree, path):
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id.upper() in ['PASSWORD', 'SECRET', 'API_KEY']:
+                        # Check if value is from environment variable (os.getenv, os.environ, etc.)
+                        value_is_from_env = False
+                        if isinstance(node.value, ast.Call):
+                            # Check for os.getenv(), os.environ.get(), etc.
+                            if isinstance(node.value.func, ast.Attribute):
+                                if node.value.func.attr in ['getenv', 'get'] and isinstance(node.value.func.value, ast.Name) and node.value.func.value.id == 'os':
+                                    value_is_from_env = True
+                            # Check for os.environ['KEY'] or os.environ.get('KEY')
+                            if isinstance(node.value.func, ast.Subscript) and isinstance(node.value.func.value, ast.Attribute):
+                                if node.value.func.value.attr == 'environ' and isinstance(node.value.func.value.value, ast.Name) and node.value.func.value.value.id == 'os':
+                                    value_is_from_env = True
+                        elif isinstance(node.value, ast.Attribute):
+                            # Check for os.environ['KEY'] assignments
+                            if isinstance(node.value.value, ast.Attribute) and node.value.value.attr == 'environ':
+                                value_is_from_env = True
+                        
+                        # Only flag hardcoded string literals, not environment variable lookups
+                        # Handle both Python 3.7 (ast.Str) and Python 3.8+ (ast.Constant)
+                        is_string_literal = False
+                        if hasattr(ast, 'Constant'):
+                            # Python 3.8+
+                            if isinstance(node.value, ast.Constant) and isinstance(node.value.value, str):
+                                is_string_literal = True
+                        else:
+                            # Python 3.7 and earlier
+                            if isinstance(node.value, getattr(ast, 'Str', type(None))):
+                                is_string_literal = True
+                        
+                        if is_string_literal and not value_is_from_env:
+                            self.issues.append(("AST", f"Hardcoded credential found in {path} on line {node.lineno}"))
+            elif isinstance(node, ast.Call):
+                if isinstance(node.func, ast.Name) and node.func.id in ['eval', 'exec']:
+                    self.issues.append(("AST", f"Insecure function '{node.func.id}' used in {path} on line {node.lineno}"))
+                if isinstance(node.func, ast.Attribute) and node.func.attr in ['load', 'loads'] and isinstance(node.func.value, ast.Name) and node.func.value.id == 'pickle':
+                    self.issues.append(("AST", f"Insecure function 'pickle.{node.func.attr}' used in {path} on line {node.lineno}"))
+            elif isinstance(node, ast.FunctionDef):
+                # Missing docstrings are warnings (non-blocking), not errors
+                # Only flag mutable default arguments as errors
+                for arg in node.args.defaults:
+                    if isinstance(arg, (ast.List, ast.Dict)):
+                        self.issues.append(("AST", f"Mutable default argument used in function '{node.name}' in {path} on line {node.lineno}"))
+            elif isinstance(node, ast.ClassDef):
+                # Missing docstrings are warnings (non-blocking), not errors
+                pass
+
+    def _print_summary(self):
+        print("\nPython Safety Checker Summary")
+        print("=============================")
+        if not self.issues:
+            print("✓ All checks passed!")
+        else:
+            for tool, issue in self.issues:
+                print(f"\n--- {tool} Issues ---")
+                print(issue)
+            print(f"\n✗ Found {len(self.issues)} issues.")
+            sys.exit(1)
+
+if __name__ == "__main__":
+    target = sys.argv[1] if len(sys.argv) > 1 else '.'
+    checker = PythonSafetyChecker(target)
+    checker.check()

package/lib/scripts/shell-safety-checker.sh

@@ -0,0 +1,306 @@
+#!/usr/bin/env bash
+# shell-safety-checker.sh - Safety checker for shell scripts
+# Based on ui/js-safety-checker.js pattern
+# Integrates shellcheck for comprehensive static analysis
+
+set -euo pipefail
+
+# Check if shellcheck is available
+SHELLCHECK_AVAILABLE=0
+if command -v shellcheck >/dev/null 2>&1; then
+    SHELLCHECK_AVAILABLE=1
+fi
+
+# Checks for loops that could be parallelized
+# Returns warnings (non-blocking optimization suggestions) via stdout
+function check_parallelization_opportunities() {
+    local filePath="$1"
+    local line_num=0
+    local in_loop=0
+    local loop_start_line=0
+    local loop_body=""
+    local loop_indent=""
+    local loop_type="" # To store 'for', 'while', or 'until'
+
+    # Read file line by line to handle nested structures
+    while IFS= read -r line; do
+        ((line_num++))
+
+        # Detect the start of a loop (for, while, until)
+        if [[ $in_loop -eq 0 && $line =~ ^([[:space:]]*)(for|while|until)[[:space:]]+.*do$ ]]; then
+            in_loop=1
+            loop_start_line=$line_num
+            loop_indent="${BASH_REMATCH[1]}"
+            loop_type="${BASH_REMATCH[2]}"
+            loop_body=""
+            continue
+        fi
+
+        # Detect the end of the loop
+        if [[ $in_loop -eq 1 && $line =~ ^${loop_indent}done$ ]]; then
+            # Heuristic: If the loop body is not already backgrounded, it's a candidate.
+            # Check for '&' at the end of a command or 'wait' for PIDs
+            # Note: Parallelization opportunities are optimization suggestions, not errors
+            if ! echo "$loop_body" | grep -qE '&[[:space:]]*$|wait[[:space:]]+\$!|pids[[:space:]]*\+='; then
+                echo "Potential parallelization opportunity: A '${loop_type}' loop was found at lines $loop_start_line-$line_num. If iterations are independent, consider parallelizing tasks (e.g., using '&' with 'wait', 'xargs -P', or 'parallel')."
+            fi
+
+            # Reset state for the next loop
+            in_loop=0
+            loop_body=""
+            loop_start_line=0
+            loop_indent=""
+            loop_type=""
+            continue
+        fi
+
+        # If inside a loop, append the current line to the loop_body
+        if [[ $in_loop -eq 1 ]]; then
+            loop_body+="$line\n"
+        fi
+    done < "$filePath"
+}
+
+# Add a new check for consecutive similar operations
+# Returns warnings (non-blocking optimization suggestions) via stdout
+function check_consecutive_similar_operations() {
+    local filePath="$1"
+    # Use awk to find consecutive lines with similar operations, ignoring common non-parallelizable keywords.
+    awk -v blocklist_str="export local readonly unset echo log_info log_warn log_error if for while case select function time mkdir cp git source" '
+            BEGIN {
+                # Keywords/built-ins that are typically not candidates for parallelization
+                split(blocklist_str, blocklist_arr, " ");
+                for (i in blocklist_arr) {
+                    is_blocklisted[blocklist_arr[i]] = 1;
+                }
+            }
+
+            function check_and_report() {
+                if (count >= 3 && !is_blocklisted[opName]) { # Check against blocklist
+                    print "Potential parallelization opportunity: A block of " count " similar sequential operations (\"" opName "\") was found starting at line " startLine ". Consider refactoring into a parallelized loop or using '\''xargs -P'\'' / '\''parallel'\''.";
+                }
+            }
+
+            # Match lines that look like operations, ignore empty or commented lines
+            /^[[:space:]]*[a-zA-Z0-9_]+[[:space:]]+.*$/ {
+                # Use the first word as the operation name
+                op = $1;
+                # Further refine op to ignore variable assignments or simple declarations
+                if (op ~ /=/) { op = ""; } # Ignore assignments
+                if (op == "local" || op == "export" || op == "readonly") { op = ""; } # Ignore declarations
+
+                if (op != "") {
+                    if (op == opName && ! /&[[:space:]]*$/) {
+                        count++;
+                    } else {
+                        check_and_report();
+                        opName = op;
+                        startLine = NR;
+                        count = 1;
+                    }
+                }
+            }
+            END { check_and_report(); }
+        ' "$filePath"
+}
+
+
+function checkShellFile() {
+    local filePath="$1"
+    local issues=()
+    local warnings=()
+
+    # Check parallelization opportunities (warnings, not errors)
+    # Capture warnings from functions that output to stdout
+    while IFS= read -r warning; do
+        warnings+=("$warning")
+    done < <(check_parallelization_opportunities "$filePath")
+    
+    while IFS= read -r warning; do
+        warnings+=("$warning")
+    done < <(check_consecutive_similar_operations "$filePath")
+    
+    # Check for silent failures (|| true) - CRITICAL
+    # Exception: Allow || true for non-blocking optional operations (e.g., CloudWatch logging, existence checks)
+    if grep -q "|| true" "$filePath"; then
+        # Check if it's part of a non-blocking optional operation pattern
+        # For multiline AWS commands, check if file has both AWS list/get/describe AND || true
+        local has_aws_list=0
+        local has_aws_get=0
+        local has_aws_describe=0
+        if grep -qE "(aws.*list|aws acm)" "$filePath"; then
+            has_aws_list=1
+        fi
+        if grep -qE "aws.*get" "$filePath"; then
+            has_aws_get=1
+        fi
+        if grep -qE "aws.*describe" "$filePath"; then
+            has_aws_describe=1
+        fi
+        
+        # Check if it matches allowed patterns (same line or multiline for AWS commands)
+        # Allow || true for AWS list/get/describe commands (handles multiline patterns)
+        local is_allowed=0
+        if grep -qE "(2>/dev/null \|\| true|>/dev/null \|\| true|\|\| true.*2>/dev/null|send_to_cloudwatch.*\|\| true|\|\| true.*cloudwatch)" "$filePath"; then
+            is_allowed=1
+        elif [[ ($has_aws_list -eq 1 || $has_aws_get -eq 1 || $has_aws_describe -eq 1) ]]; then
+            is_allowed=1
+        fi
+        
+        if [[ $is_allowed -eq 0 ]]; then
+            issues+=("Silent failure detected: || true")
+        fi
+    fi
+    
+    # Check for missing set -euo pipefail - CRITICAL
+    # Check first 20 lines to allow for comments/headers
+    if ! head -20 "$filePath" | grep -q "set -euo pipefail"; then
+        issues+=("Missing 'set -euo pipefail'")
+    fi
+
+    # Check for dangerous combination: set -e with background jobs - CRITICAL SILENT FAILURE RISK
+    # Behavior-based detection rather than syntax-based
+    local has_background_job=0
+    local has_pid_capture=0
+    local has_wait_for_pid=0
+    local has_exit_code_check=0
+
+    # Check for background jobs (any command ending with &)
+    if grep -qE '\&[[:space:]]*$' "$filePath"; then
+        has_background_job=1
+    fi
+
+    # Check for PID capture behavior (any mechanism that stores $!)
+    # This includes: var=$!, array[key]=$!, var="${var}$!", etc.
+    if grep -qE '\$![[:space:]]*\)?[[:space:]]*$|\$![[:space:]]*\)?[[:space:]]*;|\$![[:space:]]*\)?[[:space:]]*&' "$filePath" || \
+       grep -qE '[a-zA-Z0-9_]+(\[[^]]+\])?[[:space:]]*=[[:space:]]*.*\$!' "$filePath"; then
+        has_pid_capture=1
+    fi
+
+    # Check for wait behavior (any wait command that could wait for specific processes)
+    # This includes: wait, wait $var, wait ${var}, wait $!, wait "${var}", etc.
+    if grep -qE 'wait[[:space:]]*$|wait[[:space:]]+[^[:space:]]+' "$filePath"; then
+        has_wait_for_pid=1
+    fi
+
+    # Check for exit code check behavior (any mechanism that checks $?)
+    # This includes: var=$?, if [[ $? -eq 0 ]], if [ $? = 0 ], if ! wait, wait || log, etc.
+    if grep -qE '\$\?[[:space:]]*\)?[[:space:]]*$|\$\?[[:space:]]*\)?[[:space:]]*;|[a-zA-Z0-9_]+[[:space:]]*=[[:space:]]*.*\$\?|if[[:space:]]+.*\$\?|\[\[[[:space:]]*.*\$\?|if[[:space:]]+!.*wait|if.*wait.*pids|wait.*pids.*then|wait[[:space:]]+.*\|\||wait[[:space:]]+\$.*\|\|' "$filePath"; then
+        has_exit_code_check=1
+    fi
+
+    if [[ $has_background_job -eq 1 ]]; then
+        if [[ $has_pid_capture -eq 0 || $has_wait_for_pid -eq 0 || $has_exit_code_check -eq 0 ]]; then
+            issues+=("CRITICAL SILENT FAILURE RISK: Background jobs ('&') with 'set -e' can fail silently. Ensure PIDs are captured, waited on, and their exit codes are explicitly checked. (Detected: BG_JOB=$has_background_job, PID_CAP=$has_pid_capture, WAIT=$has_wait_for_pid, EXIT_CHECK=$has_exit_code_check)")
+        fi
+    fi
+    
+    # Check for proper shebang - CRITICAL
+    if ! head -1 "$filePath" | grep -q "^#!/.*bash"; then
+        issues+=("Missing or incorrect shebang")
+    fi
+    
+    # Check for hardcoded credentials - SECURITY (more specific patterns)
+    # Exception: Variable assignments from environment variables are OK
+    if grep -qiE "(password|secret|api_key|api-key)\s*=\s*[a-zA-Z0-9_]{10,}" "$filePath" && ! grep -qE "\$\{.*\}.*=" "$filePath"; then
+        # Check if it's from an environment variable or parameter store
+        if ! grep -qE "(getenv|os\.environ|\$\{.*:-|\$\(.*\)|\$\{.*\}|\$\$|aws ssm|parameter.*store)" "$filePath"; then
+            issues+=("Potential hardcoded credential detected")
+        fi
+    fi
+    
+    # Run shellcheck if available
+    if [[ $SHELLCHECK_AVAILABLE -eq 1 ]]; then
+        # Run shellcheck and capture only errors (warnings are non-blocking)
+        local shellcheck_output
+        shellcheck_output=$(shellcheck --severity=error "$filePath" 2>&1 || true)
+
+        if [[ -n "$shellcheck_output" ]]; then
+            issues+=("SHELLCHECK FINDINGS:")
+            # Parse shellcheck output and add as issues
+            while IFS= read -r line; do
+                if [[ -n "$line" ]]; then
+                    issues+=("  $line")
+                fi
+            done <<< "$shellcheck_output"
+        fi
+    fi
+
+    # Return issues
+    if [[ ${#issues[@]} -gt 0 ]]; then
+        echo "ERROR: $filePath"
+        for issue in "${issues[@]}"; do
+            echo "  - $issue"
+        done
+        # Print warnings if any (non-blocking)
+        if [[ ${#warnings[@]} -gt 0 ]]; then
+            echo "  WARNINGS (non-blocking):"
+            for warning in "${warnings[@]}"; do
+                echo "    - $warning"
+            done
+        fi
+        return 1
+    else
+        # Print warnings even if no errors
+        if [[ ${#warnings[@]} -gt 0 ]]; then
+            echo "OK: $filePath (with warnings)"
+            for warning in "${warnings[@]}"; do
+                echo "  WARNING (non-blocking): $warning"
+            done
+        else
+            echo "OK: $filePath"
+        fi
+        return 0
+    fi
+}
+
+# Main execution - only run if script is executed directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    # Temporarily disable strict mode for main execution
+    set +euo pipefail
+    
+    echo "Shell Script Safety Checker"
+    echo "=========================="
+    if [[ $SHELLCHECK_AVAILABLE -eq 1 ]]; then
+        echo "Using shellcheck for static analysis (warnings and errors)"
+    else
+        echo "WARNING: shellcheck not found - install with 'apt-get install shellcheck' for comprehensive analysis"
+    fi
+    echo ""
+
+    totalIssues=0
+    fileCount=0
+    targetDir="${1:-.}"
+
+    if [ -f "$targetDir" ]; then
+        checkShellFile "$targetDir" || totalIssues=1
+        fileCount=1
+    else
+        # Check all shell scripts except this safety checker
+        while IFS= read -r -d '' file; do
+            # Skip the safety checker itself
+            if [[ "$file" != *"shell-safety-checker.sh" ]]; then
+                ((fileCount++))
+                checkShellFile "$file" || ((totalIssues++))
+            fi
+        done < <(find "$targetDir" -name "*.sh" -type f -not -path "*/venv/*" -not -path "*/.venv*" -print0)
+    fi
+
+    echo ""
+    echo "Safety Check Summary"
+    echo "==================="
+    echo "Files checked: $fileCount"
+    echo "Files with issues: $totalIssues"
+
+    echo ""
+    echo "Final Result"
+    echo "============"
+
+    if [[ $totalIssues -eq 0 ]]; then
+        echo "✓ All checks passed!"
+        exit 0
+    else
+        echo "✗ Safety check failed"
+        exit 1
+    fi
+fi

package/lib/settings.mjs

@@ -0,0 +1,147 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { withTransaction } from './store.mjs'
+
+const DEFAULT_EFFECTIVE = {
+  model_config: {
+    provider: 'zhipu',
+    model_id: 'glm_4_7_flash',
+    base_url: null,
+  },
+  permissions: { defaultMode: 'default', allow: [], deny: [], ask: [] },
+  hooks: [],
+  apiKeyHelper: null,
+  mcp_servers: {},
+}
+
+/**
+ * Get file modification time or null if file doesn't exist.
+ * @param {string} filePath - Path to the file
+ * @returns {Date | null} File modification time or null
+ */
+function getFileModificationTime(filePath) {
+  try {
+    const stats = fs.statSync(filePath)
+    return stats.mtime
+  } catch {
+    return null
+  }
+}
+
+/** §4.4 — bootstrap once at process start. */
+export function bootstrapSettings(db, projectRoot) {
+  const candidates = [
+    path.join(projectRoot, '.ona', 'settings.json'),
+    path.join(projectRoot, '.claude', 'settings.local.json'),
+    path.join(projectRoot, 'settings.json'),
+  ]
+  
+  // Step 1: Load settings from files (if they exist)
+  let fileSettings = null
+  let newestFileTime = null
+  
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue
+    try {
+      const content = fs.readFileSync(p, 'utf8')
+      const parsed = JSON.parse(content)
+      fileSettings = deepMerge(fileSettings || {}, parsed)
+      
+      // Track newest file modification time
+      const modTime = getFileModificationTime(p)
+      if (modTime && (!newestFileTime || modTime > newestFileTime)) {
+        newestFileTime = modTime
+      }
+    } catch {
+      // Skip invalid JSON files
+      continue
+    }
+  }
+  
+  // Step 2: Load existing settings from database
+  const row = db.prepare(`SELECT json, updated_at FROM settings_snapshot WHERE scope = 'effective'`).get()
+  
+  let dbSettings = null
+  let dbTimestamp = null
+  
+  if (row) {
+    try {
+      dbSettings = JSON.parse(row.json)
+      dbTimestamp = new Date(row.updated_at)
+    } catch {
+      // Database has invalid JSON, treat as empty
+      dbSettings = null
+    }
+  }
+  
+  // Step 3: Determine merge strategy based on timestamps
+  let shouldUpdateDatabase = false
+  let finalSettings = null
+  let source = null
+  
+  if (!dbSettings) {
+    // Case A: Database is empty (first run)
+    // Merge: File > Defaults
+    finalSettings = deepMerge(structuredClone(DEFAULT_EFFECTIVE), fileSettings || {})
+    shouldUpdateDatabase = true
+    source = 'bootstrap-first-run'
+  } else if (fileSettings && newestFileTime && newestFileTime > dbTimestamp) {
+    // Case B: File was manually edited after last database update
+    // Merge: File > Database > Defaults
+    finalSettings = deepMerge(structuredClone(DEFAULT_EFFECTIVE), dbSettings)
+    finalSettings = deepMerge(finalSettings, fileSettings)
+    shouldUpdateDatabase = true
+    source = 'bootstrap-file-newer'
+  } else {
+    // Case C: Database has settings and is newer than (or equal to) file
+    // Keep database settings unchanged (preserves runtime changes)
+    finalSettings = dbSettings
+    shouldUpdateDatabase = false
+    source = 'bootstrap-db-preserved'
+  }
+  
+  // Step 4: Update database if needed
+  if (shouldUpdateDatabase) {
+    const json = JSON.stringify(finalSettings)
+    withTransaction(db, () => {
+      db.prepare(
+        `INSERT OR REPLACE INTO settings_snapshot(scope, json, updated_at) VALUES ('effective', ?, datetime('now'))`,
+      ).run(json)
+    })
+  }
+  
+  return finalSettings
+}
+
+export function getEffectiveSettings(db) {
+  const row = db.prepare(`SELECT json FROM settings_snapshot WHERE scope = 'effective'`).get()
+  if (!row) return structuredClone(DEFAULT_EFFECTIVE)
+  try { return JSON.parse(row.json) } catch { return structuredClone(DEFAULT_EFFECTIVE) }
+}
+
+export function updateEffectiveSettings(db, patch) {
+  const current = getEffectiveSettings(db)
+  const merged = deepMerge(current, patch)
+  const json = JSON.stringify(merged)
+  withTransaction(db, () => {
+    db.prepare(
+      `INSERT OR REPLACE INTO settings_snapshot(scope, json, updated_at) VALUES ('effective', ?, datetime('now'))`,
+    ).run(json)
+  })
+  return merged
+}
+
+function deepMerge(a, b) {
+  if (!b || typeof b !== 'object') return a
+  const out = Array.isArray(a) ? [...a] : { ...a }
+  for (const k of Object.keys(b)) {
+    const bv = b[k]
+    if (bv === undefined) continue
+    if (bv && typeof bv === 'object' && !Array.isArray(bv) && typeof out[k] === 'object' && !Array.isArray(out[k])) {
+      out[k] = deepMerge(out[k] || {}, bv)
+    } else {
+      out[k] = bv
+    }
+  }
+  return out
+}