syntaxis/docs/installation/installation-architecture.md

Installation Architecture: Targets with Configs & Wrappers

Status: Analysis & Design Document Created: November 15, 2025 Purpose: Document installation strategy for syntaxis binaries with configuration management

---

1. Current Installation System

1.1 Installation Scripts Infrastructure

File: scripts/install-cli.nu (NuShell)

Current Capabilities:

• Discovers binary crates in syntaxis (cli, api, tui, dashboard)
• Installs binaries to system PATH via cargo install
• Cleans up target/ directories (optional)
• Shows installation status
• Manages individual binary installation

Current Limitations:

✅ Installs binaries to ~/.cargo/bin/ (system PATH)
❌ Does NOT deploy configuration files
❌ Does NOT create wrapper scripts
❌ Does NOT manage config discovery at runtime
❌ No post-install configuration step

1.2 Manifest Management Infrastructure

File: scripts/manifest.nu (NuShell)

Tracks:

• Installed binaries (name, version, path, enabled/disabled status)
• Configurations (name, type, path, enabled/disabled)
• Installation metadata (creation date, root directory)

Example Structure:

# .syntaxis/manifest.toml (generated structure)
[syntaxis]
version = "0.1.0"
created_at = "2025-11-15"
installation_root = "/path/to/installation"

[binaries]
workspace = { enabled = true, installed_at = "2025-11-15", version = "0.1.0", path = "..." }
syntaxis-tui = { enabled = true, installed_at = "2025-11-15", version = "0.1.0", path = "..." }

[configurations]
# Currently empty - needs enhancement

1.3 Configuration Discovery System

File: scripts/common/find-config.nu

Search Order:

1. .syntaxis/{filename} - syntaxis specific
2. .project/{filename} - Generic project
3. .coder/{filename} - Documentation tracking
4. {filename} - Current directory fallback

Current Usage:

• Scripts use this to find config files at build/runtime
• Database discovery (find-db-path)
• TOML file discovery

---

2. Configuration System Analysis

2.1 Configuration File Locations

Current Structure:

syntaxis/
├── syntaxis/
│   ├── syntaxis-api-config.template.toml    ⚠️ NEEDS RENAME
│   └── configs/features/
│       ├── auth.toml.template
│       ├── cache.toml.template
│       ├── database.toml.template
│       ├── health.toml.template
│       ├── metrics.toml.template
│       ├── multi_tenant.toml.template
│       └── rate_limit.toml.template
│
├── shared/rust-api/shared-api-lib/
│   └── src/config/mod.rs                    (Config definitions)
│
└── .syntaxis/                    (Runtime configs after installation)
    ├── manifest.toml                        (Installation tracking)
    └── [configs deployed here at runtime]

2.2 Configuration Loading Flow

Current (Hardcoded):

// shared-api-lib/src/config/mod.rs
impl Config {
    pub fn load() -> Result<Self> {
        // 1. Try reading from env var
        let config_path = std::env::var("CONFIG_PATH")
            .unwrap_or_else(|_| "configs/default.toml".to_string());

        // 2. Load from file
        let content = std::fs::read_to_string(&config_path)?;

        // 3. Deserialize
        let config: Config = toml::from_str(&content)?;
        Ok(config)
    }
}

Needs Enhancement:

• Use find-config logic for standardized discovery
• Support multiple config locations
• Environment variable overrides
• Config validation and merging

2.3 Configuration Types

Main Configuration: syntaxis-api-config.toml

• Server settings (host, port)
• Database connection
• Logging level
• Feature flags

Feature Configurations: configs/features/*.toml

• auth.toml - Authentication settings
• database.toml - Database pooling
• metrics.toml - Prometheus settings
• rate_limit.toml - Rate limiting rules
• cache.toml - Caching configuration
• health.toml - Health check settings
• multi_tenant.toml - Multi-tenancy settings

Missing Workspace-Specific Configs:

• projects.toml - Project management settings
• tasks.toml - Task tracking configuration
• phases.toml - Phase lifecycle configuration
• audit.toml - Audit trail settings

---

3. Installation Targets Architecture

3.1 What is a "Target"?

In syntaxis context, a target is:

A compiled binary + its associated configs + runtime metadata

workspace (target)
├── Binary
│   └── ~/.cargo/bin/workspace  (executable)
├── Configuration
│   ├── ~/.config/core/workspace.toml          (main config)
│   └── ~/.config/core/features/*.toml         (feature configs)
├── Data
│   └── ~/.local/share/core/                   (runtime data)
├── Wrapper
│   └── /usr/local/bin/workspace                             (wrapper script)
└── Metadata
    └── .syntaxis/manifest.toml                   (installed version/path)

3.2 Target Types

1. CLI Binary (syntaxis-cli)

Purpose: Command-line interface
Executable: ~/.cargo/bin/workspace
Config: ~/.config/core/cli.toml
Data: ~/.local/share/core/cli/
Wrapper: Yes (setup env, find config, pass args)

2. TUI Binary (syntaxis-tui)

Purpose: Terminal UI interface
Executable: ~/.cargo/bin/syntaxis-tui
Config: ~/.config/core/tui.toml
Data: ~/.local/share/core/tui/
Wrapper: Yes (setup terminal, handle signals)

3. API Server (syntaxis-api)

Purpose: REST API server
Executable: ~/.cargo/bin/syntaxis-api
Config: ~/.config/core/api.toml
Data: ~/.local/share/core/api/
Wrapper: Yes (setup environment, manage process)

4. Dashboard (syntaxis-dashboard)

Purpose: Web UI
Type: Library + WASM frontend
Config: ~/.config/core/dashboard.toml
Data: ~/.local/share/core/dashboard/
Wrapper: Yes (manage server lifecycle)

---

4. Configuration Deployment Strategy

4.1 Configuration File Organization

On Host System (After Installation):

~/.config/core/
├── manifest.toml                    # Installation tracking
├── defaults.toml                    # Global defaults
├── workspace.toml                   # CLI config
├── syntaxis-tui.toml              # TUI config
├── syntaxis-api.toml              # API config
├── syntaxis-dashboard.toml        # Dashboard config
└── features/                        # Feature configs
    ├── auth.toml
    ├── cache.toml
    ├── database.toml
    ├── health.toml
    ├── metrics.toml
    ├── multi_tenant.toml
    └── rate_limit.toml

~/.local/share/core/
├── cli/                             # CLI runtime data
│   └── history.json
├── tui/                             # TUI runtime data
│   └── state.json
├── api/                             # API runtime data
│   ├── workspace.db
│   └── logs/
└── dashboard/                       # Dashboard runtime data
    └── cache/

4.2 Configuration Template Deployment

During Installation:

1. Copy syntaxis-api-config.template.toml → ~/.config/core/syntaxis-api.toml
2. Copy configs/features/*.toml.template → ~/.config/core/features/*.toml
3. Create .syntaxis/manifest.toml with installation metadata
4. Register installed configurations in manifest

Version Management:

# manifest.toml entry
[configurations.syntaxis-api]
enabled = true
type = "main"
path = "~/.config/core/syntaxis-api.toml"
version = "0.1.0"
deployed_from = "syntaxis/syntaxis-api-config.template.toml"
deployed_at = "2025-11-15T10:30:00Z"

---

5. Wrapper Scripts Architecture

5.1 Purpose of Wrappers

Wrapper scripts sit between the user/system and the binary, providing:

User Command: workspace --version
         ↓
Wrapper Script: workspace (wrapper)
         ↓ (setup environment)
         ├─ Find config file
         ├─ Set environment variables
         ├─ Validate config
         ├─ Setup logging
         └─ Call actual binary
         ↓
Actual Binary: ~/.cargo/bin/workspace.real
         ↓
Output to User

5.2 Wrapper Implementation Strategy

Type 1: Shell-based Wrappers (NuShell or Bash)

#!/usr/bin/env nu

# workspace wrapper - Setup environment and call actual binary

# 1. Find configuration
use scripts/common/find-config.nu [find-config]
let config_file = (find-config "workspace.toml")

# 2. Setup environment
let config_dir = (
    if ($config_file | is-empty) {
        "~/.config/syntaxis"
    } else {
        ($config_file | path dirname)
    }
)

# 3. Set environment variables
$env.WORKSPACE_CONFIG_DIR = ($config_dir | path expand)
$env.WORKSPACE_DATA_DIR = ("~/.local/share/syntaxis" | path expand)
$env.WORKSPACE_HOME = (pwd)

# 4. Call actual binary with arguments
~/.cargo/bin/workspace.real ...$args

Type 2: Rust-based Wrappers

// workspace-wrapper/main.rs
use std::env;
use std::process::Command;

fn main() {
    // 1. Find and load config
    let config_dir = find_config_dir()
        .unwrap_or_else(|| get_default_config_dir());

    // 2. Setup environment
    env::set_var("WORKSPACE_CONFIG_DIR", &config_dir);
    env::set_var("WORKSPACE_DATA_DIR", get_data_dir());

    // 3. Validate config
    validate_config(&config_dir)
        .expect("Configuration validation failed");

    // 4. Call actual binary
    let mut cmd = Command::new(
        get_actual_binary_path()
    );

    cmd.args(env::args().skip(1));

    let status = cmd.status()
        .expect("Failed to execute binary");

    std::process::exit(status.code().unwrap_or(1));
}

5.3 Wrapper Functions

1. Configuration Discovery & Validation

Find config file
↓
Validate TOML syntax
↓
Check required fields
↓
Merge with feature configs
↓
Set CONFIG_PATH env var

2. Environment Setup

Set WORKSPACE_HOME
Set WORKSPACE_CONFIG_DIR
Set WORKSPACE_DATA_DIR
Set WORKSPACE_LOG_LEVEL (from config)
Set RUST_LOG (from log_level config)

3. Pre-execution Hooks

Check database connectivity (for API)
Create data directories if missing
Setup logging appenders
Validate feature configurations

4. Post-execution Cleanup

Flush logs
Close database connections
Cleanup temp files

---

6. Installation Flow

6.1 Complete Installation Process

┌─────────────────────────────────────────────────────────┐
│ User: just scripts-install or install-cli.nu all        │
└─────────────┬───────────────────────────────────────────┘
              │
              ├─ 1. DISCOVERY
              │   └─ Find all binary crates in workspace
              │
              ├─ 2. COMPILATION
              │   └─ cargo build --release
              │
              ├─ 3. BINARY INSTALLATION
              │   └─ cargo install --path {crate}
              │       └─ Binary placed in ~/.cargo/bin/
              │
              ├─ 4. CONFIGURATION DEPLOYMENT
              │   ├─ Create ~/.config/core/
              │   ├─ Copy syntaxis-api-config.template.toml
              │   ├─ Copy features/*.toml.template
              │   └─ Parse and validate all configs
              │
              ├─ 5. WRAPPER INSTALLATION
              │   ├─ Rename ~/.cargo/bin/workspace → ~/.cargo/bin/workspace.real
              │   ├─ Create wrapper script at ~/.cargo/bin/workspace
              │   └─ Make wrapper executable
              │
              ├─ 6. MANIFEST REGISTRATION
              │   ├─ Load or create .syntaxis/manifest.toml
              │   ├─ Register binary (name, version, path)
              │   ├─ Register configurations
              │   └─ Save manifest
              │
              └─ 7. VERIFICATION
                  ├─ workspace --version (test wrapper)
                  ├─ Test config discovery
                  ├─ Validate environment setup
                  └─ Print installation summary

6.2 Installation Script Pseudocode

#!/usr/bin/env nu

# Phase 1: Compile binaries
cargo build --release

# Phase 2: Install binaries to ~/.cargo/bin/
for binary in [workspace syntaxis-tui syntaxis-api] {
    cargo install --path core/crates/{binary}
}

# Phase 3: Deploy configurations
let config_dir = "~/.config/syntaxis"
mkdir -p $config_dir
mkdir -p $"($config_dir)/features"

# Copy main configs
cp syntaxis/syntaxis-api-config.template.toml \
   "$config_dir/syntaxis-api.toml"

# Copy feature configs
cp syntaxis/configs/features/*.toml.template \
   "$config_dir/features/"

# Phase 4: Install wrappers
for binary in [workspace syntaxis-tui syntaxis-api] {
    let binary_path = $"~/.cargo/bin/($binary)"

    # Rename actual binary
    mv $binary_path $"$binary_path.real"

    # Create wrapper script
    create-wrapper-script $binary $binary_path

    # Make executable
    chmod +x $binary_path
}

# Phase 5: Register in manifest
register-binary "workspace" "0.1.0" "~/.cargo/bin/workspace"
register-config "syntaxis-api" "main" "~/.config/core/syntaxis-api.toml"

# Phase 6: Verify installation
print "✅ Installation complete"
print ""
print "Test with:"
print "  workspace --version"
print "  syntaxis-tui"

---

7. Proposed Implementation Roadmap

Phase 1: Configuration Deployment (Weeks 1-2)

Tasks:

1. Rename syntaxis-api-config.template.toml → syntaxis-api-config.template.toml
2. Create workspace-specific feature templates:
   • configs/features/projects.toml.template
   • configs/features/tasks.toml.template
   • configs/features/phases.toml.template
   • configs/features/audit.toml.template
3. Update install-cli.nu to copy config templates
4. Create ~/.config/core/ during installation

Deliverables:

• ✅ Config templates renamed and created
• ✅ Installation script copies configs
• ✅ Configuration files deployed to standard location

Phase 2: Wrapper Script Implementation (Weeks 3-4)

Tasks:

1. Create wrapper script generator
2. Implement configuration discovery in wrappers
3. Setup environment variables
4. Integrate manifest management
5. Test wrapper functionality

Deliverables:

• ✅ Wrapper scripts for workspace, syntaxis-tui, syntaxis-api
• ✅ Config discovery working
• ✅ Environment properly setup

Phase 3: Manifest Enhancement (Weeks 4-5)

Tasks:

1. Extend manifest.toml schema to track configs
2. Update manifest.nu to register configurations
3. Add config validation to manifest
4. Create config version tracking

Deliverables:

• ✅ Manifest tracks installed configs
• ✅ Config versions tracked
• ✅ Easy rollback capability

Phase 4: Documentation & Testing (Weeks 5-6)

Tasks:

1. Create installation guide
2. Create configuration guide
3. Write wrapper script documentation
4. Create troubleshooting guide
5. Add integration tests

Deliverables:

• ✅ docs/installation-guide.md
• ✅ docs/configuration.md
• ✅ WRAPPER_GUIDE.md
• ✅ Integration tests passing

---

8. Key Design Decisions

8.1 Configuration Location

Decision: ~/.config/core/

Rationale:

• Follows XDG Base Directory Specification
• Separates configs from binaries
• Easy to backup/restore
• Works on macOS, Linux, Windows (with WSL)
• Per-user isolation

Alternative: /etc/core/ (would require sudo)

8.2 Wrapper Language

Decision: NuShell for maximum compatibility

Rationale:

• Consistent with existing workspace scripts
• Cross-platform (Windows, macOS, Linux)
• Rich scripting capabilities
• Same repo standard tool

Alternative: Rust (compile-time, higher performance)

8.3 Configuration Format

Decision: TOML (continue existing approach)

Rationale:

• Already in use throughout workspace
• Human-readable
• Serde support for validation
• Feature-specific configs easy to compose

8.4 Manifest Location

Decision: .syntaxis/manifest.toml

Rationale:

• Version-controlled for tracking
• Centralized installation metadata
• Easy to query installation state
• Clear audit trail

---

9. Security Considerations

9.1 Configuration File Permissions

# Config files should be readable by user only
chmod 600 ~/.config/core/*.toml

# Data directories should be user-writable
chmod 700 ~/.local/share/core/

9.2 Wrapper Script Security

# Wrapper scripts should not be world-writable
chmod 755 ~/.cargo/bin/workspace

# Binaries should not be world-writable
chmod 755 ~/.cargo/bin/workspace.real

9.3 Environment Variable Injection

Risk: Wrapper script loads untrusted configs

Mitigation:

1. Validate TOML syntax before loading
2. Check file ownership (must be current user)
3. Validate required fields before use
4. Reject unknown configuration keys (strict mode)

9.4 Database Access

Risk: Database path from config could point to sensitive files

Mitigation:

1. Validate database path is within ~/.local/share/core/
2. Check database file permissions
3. Require explicit user approval for non-standard paths

---

10. Examples

10.1 User Installation Workflow

# 1. Install all targets
$ just scripts-install
  🔨 Installing syntaxis binaries...
  ✅ workspace: Installed successfully
  ✅ syntaxis-tui: Installed successfully
  ✅ syntaxis-api: Installed successfully

  📋 Configurations deployed to:
    ~/.config/core/
    └── syntaxis-api.toml
    └── features/
        ├── auth.toml
        ├── database.toml
        ├── ...

# 2. Check installation
$ just scripts-status
  📊 Installation Status
  ✅ workspace (CLI) - Installed
  ✅ syntaxis-tui (TUI) - Installed
  ✅ syntaxis-api (API) - Installed (WIP)

# 3. Verify wrapper works
$ workspace --version
  syntaxis v0.1.0

  Config loaded from: ~/.config/core/syntaxis-api.toml
  Data directory: ~/.local/share/core/

# 4. Edit configuration
$ nano ~/.config/core/syntaxis-api.toml

# 5. Restart to apply changes
$ syntaxis-api
  ✅ Config validated
  ✅ Features loaded: auth, database, metrics
  ✅ Server listening on 0.0.0.0:8080

10.2 Configuration Discovery at Runtime

// Inside binary (syntaxis-api or similar)

use std::env;
use std::path::PathBuf;

fn load_config() -> Result<Config> {
    // 1. Check explicit environment variable
    if let Ok(path) = env::var("WORKSPACE_CONFIG_PATH") {
        return load_from_path(&path);
    }

    // 2. Use WORKSPACE_CONFIG_DIR (set by wrapper)
    let config_dir = env::var("WORKSPACE_CONFIG_DIR")
        .unwrap_or_else(|_| get_default_config_dir());

    // 3. Try standard locations
    let candidates = vec![
        PathBuf::from(&config_dir).join("syntaxis-api.toml"),
        PathBuf::from(&config_dir).join("default.toml"),
        PathBuf::from(env::current_dir()?).join("syntaxis-api.toml"),
    ];

    for path in candidates {
        if path.exists() {
            return load_from_path(&path);
        }
    }

    Err("No configuration found".into())
}

---

11. Files to Create/Modify

Create New Files

• scripts/install-targets.nu - Enhanced installation with configs & wrappers
• scripts/deploy-configs.nu - Configuration deployment script
• scripts/create-wrappers.nu - Wrapper script generator
• syntaxis/configs/features/projects.toml.template
• syntaxis/configs/features/tasks.toml.template
• syntaxis/configs/features/phases.toml.template
• syntaxis/configs/features/audit.toml.template
• docs/installation-guide.md - User-facing installation documentation
• docs/configuration.md - Configuration management guide
• WRAPPER_DESIGN.md - Technical wrapper documentation

Modify Existing Files

• scripts/install-cli.nu - Add config deployment
• scripts/manifest.nu - Add config registration
• syntaxis/syntaxis-api-config.template.toml → syntaxis-api-config.template.toml
• Justfile - Add installation targets recipe
• shared/rust-api/shared-api-lib/src/config/mod.rs - Integrate find-config

Update Documentation

• README.md - Add installation instructions
• syntaxis/README.md - Add wrapper documentation
• .claude/ guidelines - Add installation best practices

---

12. Summary

Current State

• ✅ Basic binary installation working
• ✅ Manifest tracking available
• ✅ Config discovery system exists
• ❌ Configs not deployed with binaries
• ❌ No wrapper scripts
• ❌ No environment setup at runtime

Target State (After Implementation)

• ✅ Complete binary installation with configs
• ✅ Wrapper scripts setup environment
• ✅ Configuration validation
• ✅ Environment variable management
• ✅ Standardized installation locations
• ✅ Easy configuration management
• ✅ Installation verification

Next Steps

1. Review this document with team
2. Confirm design decisions
3. Begin Phase 1 (configuration deployment)
4. Follow phased roadmap
5. Write integration tests as work progresses

---

Document Version: 1.0 Status: Design Review Ready Last Updated: November 15, 2025