# ==============================================================================
# SYNTAXIS SERVICES CATALOG
# ==============================================================================
#
# Central registry of all available syntaxis services.
# This file is the source of truth for:
#   - What services are available
#   - How to run each service
#   - Service dependencies and requirements
#   - How users interact with each service
#
# Used by:
#   - install-with-presets.nu: Show what's available in each preset
#   - project-provisioning: Understand deployment requirements
#   - Service discovery: Registry for running services
#   - Documentation: Generate usage guides
#

[version]
catalog_version = "1.0.0"
syntaxis_version = "0.1.0"
created_at = "2025-11-19"

# ==============================================================================
# SERVICE DEFINITIONS
# ==============================================================================

# SERVICE: syntaxis-cli
# Core command-line interface for project management
[service.syntaxis-cli]
name = "syntaxis-cli"
display_name = "syntaxis CLI"
description = "Command-line interface for project management"
type = "cli"
required = true

[service.syntaxis-cli.binary]
name = "syntaxis-cli"
installed_to = "~/.local/bin/syntaxis-cli"

[service.syntaxis-cli.usage]
description = "Command-line tool for managing projects, tasks, and phases"
basic_command = "syntaxis-cli init my-project"
help_command = "syntaxis-cli --help"
examples = [
    "syntaxis-cli init my-project",
    "syntaxis-cli project list",
    "syntaxis-cli task add my-project 'Design API'",
    "syntaxis-cli phase advance my-project",
]

[service.syntaxis-cli.metadata]
platform_support = ["linux", "macos", "windows"]
min_disk_space_mb = 50
min_memory_mb = 64
internet_required = false
user_interaction = "required"

[service.syntaxis-cli.dependencies]
requires = []
conflicts = []

[service.syntaxis-cli.configuration]
config_location = "~/.config/syntaxis"
database_required = true
database_types = ["sqlite", "surrealdb"]

# ---

# SERVICE: syntaxis-tui
# Terminal User Interface for interactive project management
[service.syntaxis-tui]
name = "syntaxis-tui"
display_name = "syntaxis TUI"
description = "Terminal UI for interactive project management"
type = "tui"
required = false

[service.syntaxis-tui.binary]
name = "syntaxis-tui"
installed_to = "~/.local/bin/syntaxis-tui"

[service.syntaxis-tui.usage]
description = "Interactive terminal interface with vim-style navigation"
basic_command = "syntaxis-tui"
help_command = "syntaxis-tui --help"
keybindings = [
    "h/j/k/l: Navigate",
    "Enter: Select",
    "q: Quit",
    "?/h: Help",
    ":w: Write/Save",
    ":q: Quit",
]
examples = [
    "syntaxis-tui",
    "syntaxis-tui --project my-project",
    "syntaxis-tui --config ~/.config/syntaxis/tui.toml",
]

[service.syntaxis-tui.metadata]
platform_support = ["linux", "macos"]
min_disk_space_mb = 50
min_memory_mb = 128
internet_required = false
user_interaction = "required"
terminal_required = true

[service.syntaxis-tui.dependencies]
requires = ["syntaxis-cli"]
conflicts = []

[service.syntaxis-tui.configuration]
config_location = "~/.config/syntaxis"
database_required = true
database_types = ["sqlite", "surrealdb"]

# ---

# SERVICE: syntaxis-api
# REST API server for programmatic access
[service.syntaxis-api]
name = "syntaxis-api"
display_name = "syntaxis REST API"
description = "REST API server for programmatic access to syntaxis"
type = "server"
required = false

[service.syntaxis-api.binary]
name = "syntaxis-api"
installed_to = "~/.local/bin/syntaxis-api"

[service.syntaxis-api.server]
default_host = "127.0.0.1"
default_port = 3000
port_configurable = true
scheme = "http"

[service.syntaxis-api.usage]
description = "REST API for programmatic access to projects, tasks, and phases"
basic_command = "syntaxis-api --bind 127.0.0.1:3000"
health_check_endpoint = "/health"
health_check_method = "GET"
health_check_expected_status = 200
examples = [
    "syntaxis-api --bind 127.0.0.1:3000",
    "curl http://127.0.0.1:3000/health",
    "curl http://127.0.0.1:3000/api/projects",
    "curl -X POST http://127.0.0.1:3000/api/projects -d '{...}'",
]

[service.syntaxis-api.metadata]
platform_support = ["linux", "macos", "windows"]
min_disk_space_mb = 100
min_memory_mb = 256
internet_required = false
user_interaction = "optional"
background_service = true

[service.syntaxis-api.dependencies]
requires = ["syntaxis-cli"]
optional = ["dashboard"]
conflicts = []

[service.syntaxis-api.configuration]
config_location = "~/.config/syntaxis"
database_required = true
database_types = ["sqlite", "surrealdb"]
authentication = "optional"
tls_support = true

[service.syntaxis-api.performance]
typical_startup_time_seconds = 2
typical_memory_usage_mb = 256
typical_cpu_usage_percent = 5

# ---

# SERVICE: syntaxis-dashboard
# Web dashboard UI
[service.syntaxis-dashboard]
name = "syntaxis-dashboard"
display_name = "syntaxis Dashboard"
description = "Web-based dashboard UI for project management"
type = "web"
required = false

[service.syntaxis-dashboard.web]
default_host = "127.0.0.1"
default_port = 8080
scheme = "http"
browser_required = true

[service.syntaxis-dashboard.usage]
description = "Modern web dashboard for project visualization and management"
access_url = "http://127.0.0.1:8080"
browser = "Any modern browser (Chrome, Firefox, Safari, Edge)"
examples = [
    "Start API: syntaxis-api --bind 127.0.0.1:3000",
    "Open browser: http://127.0.0.1:8080",
    "Dashboard auto-connects to API on port 3000",
]

[service.syntaxis-dashboard.metadata]
platform_support = ["linux", "macos", "windows"]
min_disk_space_mb = 50
min_memory_mb = 128
internet_required = false
user_interaction = "required"

[service.syntaxis-dashboard.dependencies]
requires = ["syntaxis-api"]
conflicts = []

[service.syntaxis-dashboard.configuration]
config_location = "~/.config/syntaxis"
api_endpoint_configurable = true
authentication = "inherited from API"

# ---

# SERVICE: surrealdb
# Document database backend
[service.surrealdb]
name = "surrealdb"
display_name = "SurrealDB"
description = "Multi-model document database"
type = "database"
required = false
external_service = true

[service.surrealdb.binary]
name = "surreal"
installed_to = "~/.cargo/bin/surreal"  # Usually installed via cargo/homebrew
note = "Install via: cargo install surreal or homebrew"

[service.surrealdb.server]
default_host = "127.0.0.1"
default_port = 8000
port_configurable = true
scheme = "ws"  # WebSocket

[service.surrealdb.modes]
embedded = "In-process database (no network)"
file_based = "Persistent file on disk"
memory = "In-memory (resets on restart)"
server = "Network server mode"

[service.surrealdb.usage]
description = "Modern multi-model database for syntaxis"
basic_command = "surreal start --bind 127.0.0.1:8000 memory"
health_check_endpoint = "/"
health_check_method = "GET"
health_check_expected_status = 200
examples = [
    "surreal start --bind 127.0.0.1:8000 memory",
    "surreal start --bind 127.0.0.1:8000 file:///data/syntaxis.db",
    "curl http://127.0.0.1:8000",
    "# Connect via CLI: surreal sql --endpoint ws://127.0.0.1:8000",
]

[service.surrealdb.metadata]
platform_support = ["linux", "macos"]
min_disk_space_mb = 100
min_memory_mb = 256
internet_required = false
user_interaction = "optional"
background_service = true

[service.surrealdb.dependencies]
requires = []
optional = []
conflicts = []

[service.surrealdb.configuration]
data_location = "~/.local/share/surrealdb"
log_location = "~/.local/share/surrealdb/logs"
authentication = "optional (username/password)"
tls_support = true

[service.surrealdb.performance]
typical_startup_time_seconds = 1
typical_memory_usage_mb = 512
typical_cpu_usage_percent = 10

# ---

# SERVICE: nats
# Message bus and event streaming
[service.nats]
name = "nats"
display_name = "NATS"
description = "Cloud-native messaging platform"
type = "messaging"
required = false
external_service = true

[service.nats.binary]
name = "nats-server"
installed_to = "~/.cargo/bin/nats-server"
note = "Install via: cargo install nats-server or homebrew"

[service.nats.server]
default_host = "127.0.0.1"
default_port = 4222
port_configurable = true
scheme = "nats"

[service.nats.usage]
description = "Event streaming and inter-service messaging"
basic_command = "nats-server"
health_check_endpoint = "http://127.0.0.1:8222/healthz"
health_check_method = "GET"
health_check_expected_status = 200
examples = [
    "nats-server",
    "nats-server --port 4222",
    "nats pub my.subject 'Hello from syntaxis'",
    "nats sub my.subject",
]

[service.nats.metadata]
platform_support = ["linux", "macos"]
min_disk_space_mb = 50
min_memory_mb = 256
internet_required = false
user_interaction = "optional"
background_service = true

[service.nats.dependencies]
requires = []
optional = []
conflicts = []

[service.nats.configuration]
config_location = "~/.config/syntaxis"
authentication = "optional"
tls_support = true
clustering = true

[service.nats.performance]
typical_startup_time_seconds = 1
typical_memory_usage_mb = 256
typical_cpu_usage_percent = 5

# ==============================================================================
# SERVICE GROUPS (for organization and reference)
# ==============================================================================

[groups.core]
description = "Essential syntaxis binaries"
services = ["syntaxis-cli"]

[groups.interactive]
description = "Interactive interfaces"
services = ["syntaxis-cli", "syntaxis-tui", "syntaxis-dashboard"]

[groups.api]
description = "API and programmatic access"
services = ["syntaxis-api", "syntaxis-dashboard"]

[groups.data]
description = "Data storage and messaging"
services = ["surrealdb", "nats"]

[groups.development]
description = "Development environment"
services = ["syntaxis-cli", "syntaxis-tui", "syntaxis-api", "syntaxis-dashboard", "surrealdb"]

[groups.production]
description = "Production deployment"
services = ["syntaxis-cli", "syntaxis-api", "surrealdb", "nats"]

# ==============================================================================
# DEPLOYMENT PATTERNS
# ==============================================================================

[pattern.cli_only]
name = "CLI Only"
description = "Command-line only, no services"
services = ["syntaxis-cli"]
use_cases = ["CI/CD", "Headless servers", "Embedded systems"]

[pattern.local_dev]
name = "Local Development"
description = "Single user development with TUI"
services = ["syntaxis-cli", "syntaxis-tui"]
use_cases = ["Individual development", "Laptop/desktop"]

[pattern.dev_with_api]
name = "Development with API"
description = "Full development stack"
services = ["syntaxis-cli", "syntaxis-tui", "syntaxis-api", "syntaxis-dashboard", "surrealdb"]
use_cases = ["Team development", "API testing", "Dashboard development"]

[pattern.production]
name = "Production"
description = "Minimal production deployment"
services = ["syntaxis-api", "surrealdb", "nats"]
use_cases = ["Kubernetes", "Docker", "Cloud deployment"]

# ==============================================================================
# PORTS & NETWORKING
# ==============================================================================

[ports]
api = 3000
dashboard = 8080
surrealdb = 8000
nats = 4222
nats_monitoring = 8222

[networking]
localhost_only = "127.0.0.1"
all_interfaces = "0.0.0.0"
note = "In dev: use 127.0.0.1 to prevent external access. In prod: use 0.0.0.0 with TLS+auth"

# ==============================================================================
# QUICK REFERENCE FOR USERS
# ==============================================================================

[help.getting_started]
"1_list_available" = "nu scripts/provisioning/install-with-presets.nu --list-presets"
"2_show_preset" = "nu scripts/provisioning/install-with-presets.nu --preset dev --show-services"
"3_install" = "nu scripts/provisioning/install-with-presets.nu --preset dev"
"4_start_api" = "syntaxis-api --bind 127.0.0.1:3000"
"5_check_health" = "curl http://127.0.0.1:3000/health"

[help.common_tasks]
"list_projects" = "syntaxis-cli project list"
"add_task" = "syntaxis-cli task add my-project 'Task description'"
"use_tui" = "syntaxis-tui"
"access_dashboard" = "Open http://127.0.0.1:8080 in browser (requires syntaxis-api running)"
"start_all_services" = "provctl deploy dev"