syntaxis/docs/wrappers/wrapper-deployment-analysis.md

Wrapper Deployment Architecture: Development vs Bundle

The Real Question

You're asking: "Should bundle installation create the SAME wrapper structure that scripts/install-syntaxis creates?"

---

Current State Comparison

Development Installation: scripts/install-syntaxis ✅ HAS WRAPPERS

User runs: ./scripts/install-syntaxis all

Result:
~/.cargo/bin/syntaxis-cli           ← Bash wrapper (212 bytes)
  └─ Calls: ~/.config/syntaxis/scripts/syntaxis-cli.nu
     └─ Calls: ~/.cargo/bin/syntaxis-cli.real

~/.config/syntaxis/scripts/
  ├── syntaxis-lib.nu               ← Shared library
  ├── syntaxis-cli.nu               ← NuShell wrapper script
  ├── syntaxis-cli-lib.nu           ← CLI utilities
  └── ... (same for tui, api)

~/.cargo/bin/
  ├── syntaxis-cli.real             ← Real binary (7.2 MB)
  ├── syntaxis-tui.real             ← Real binary (3.9 MB)
  ├── syntaxis-api.real             ← Real binary (8.3 MB)

User Experience:

$ syntaxis-cli status
# Wrapper auto-injects --config path
# Clean, simple, no typing burden

---

Bundle Installation: scripts/provisioning/install.sh ❌ NO WRAPPERS

User runs: bash install.sh

Result:
~/.local/bin/syntaxis-cli           ← Direct binary (7.2 MB)
~/.local/bin/syntaxis-tui           ← Direct binary (3.9 MB)
~/.local/bin/syntaxis-api           ← Direct binary (8.3 MB)

~/.config/syntaxis/
  ├── syntaxis-cli.toml
  ├── syntaxis-tui.toml
  ├── syntaxis-api.toml
  └── ... (configs only, no wrapper scripts!)

User Experience:

$ syntaxis-cli --config ~/.config/syntaxis/config.toml status
# No wrapper! User must type --config path
# Bad UX! Repetitive!

---

The Problem

Development users (via scripts/install-syntaxis):

• Get wrapper structure
• Auto-config injection
• Type: syntaxis-cli status
• Good UX ✅

Bundle users (via scripts/provisioning/install.sh):

• Get direct binaries only
• No config injection
• Type: syntaxis-cli --config ~/.config/syntaxis/config.toml status
• Bad UX ❌

---

Decision Required

Option A: Bundle Creates Wrappers Too ✅ RECOMMENDED

Bundle install.sh should:

1. Copy wrapper scripts to ~/.config/syntaxis/scripts/
   • syntaxis-lib.nu
   • syntaxis-cli.nu
   • syntaxis-cli-lib.nu
   • etc.
2. Rename binaries to .real
3. Create bash wrappers at original locations
4. Result: Users get same structure as dev installation

Benefits:

• ✅ Users have consistent experience (dev = bundle)
• ✅ Auto-config injection (users don't type --config)
• ✅ Same UX across all installation methods

Complexity:

• Need to include .nu scripts in bundle
• install.sh needs to create wrapper structure
• More moving parts

---

Option B: Keep Bundle Simple (Direct Binaries) ❌ NOT RECOMMENDED

Bundle install.sh stays as-is:

1. Copy binaries directly to ~/.local/bin/
2. Copy configs to ~/.config/syntaxis/
3. Users invoke with explicit --config flag

Benefits:

• ✅ Simple implementation
• ✅ Minimal dependencies (no NuShell needed)
• ✅ Lightweight

Costs:

• ❌ Bundle users have worse UX than dev users
• ❌ Users must type --config path every time
• ❌ Inconsistent experience

---

Analysis Framework

Bundle Installation Quality =
    (Same UX as dev) × (Auto-config) - (Complexity)

Option A: High × Yes - Medium = GOOD
Option B: Low × No - Low = BAD

---

Implementation: How to Add Wrappers to Bundle

If we choose Option A (RECOMMENDED), here's what's needed:

1. Bundle Contents (Updated)

Currently, bundle has:

bin/
  ├── syntaxis-cli          ← Direct binary
  ├── syntaxis-tui          ← Direct binary
  ├── syntaxis-api          ← Direct binary
configs/
  ├── database-default.toml
  ├── syntaxis-cli.toml
  └── ... (only configs)

Should also have:

scripts/                     ← NEW!
  ├── syntaxis-lib.nu       ← Shared library
  ├── syntaxis-cli.nu       ← NuShell wrapper
  ├── syntaxis-cli-lib.nu   ← CLI utilities
  ├── syntaxis-tui.nu       ← TUI wrapper
  ├── syntaxis-tui-lib.nu   ← TUI utilities
  ├── syntaxis-api.nu       ← API wrapper
  └── syntaxis-api-lib.nu   ← API utilities

2. Update provisioning.toml

Need to add to artifacts:

[artifacts]
binaries = [...]
configs = [...]
docs = [...]
scripts_for_wrappers = [                    ← NEW SECTION
    "scripts/syntaxis-lib.nu",
    "scripts/syntaxis-cli.nu",
    "scripts/syntaxis-cli-lib.nu",
    "scripts/syntaxis-tui.nu",
    "scripts/syntaxis-tui-lib.nu",
    "scripts/syntaxis-api.nu",
    "scripts/syntaxis-api-lib.nu",
]

3. Update install.sh

Current code:

install_binary() {
    cp "$source" "$dest"
    chmod 755 "$dest"
}

Should be:

install_binary() {
    local source="$1"
    local dest="$2"
    local binary_name=$(basename "$source")

    # Copy and rename to .real
    cp "$source" "$dest.real"
    chmod 755 "$dest.real"

    # Create bash wrapper
    cat > "$dest" << 'EOF'
#!/bin/bash
export NU_LIB_DIRS="$HOME/.config/syntaxis/scripts"
exec nu "$HOME/.config/syntaxis/scripts/$binary_name.nu" "$@"
EOF

    chmod 755 "$dest"
}

4. Update pack.nu

Add collection of wrapper scripts:

let wrapper_scripts = (
    $config.artifacts.wrapper_scripts
    | each { |script_path| ... }
)

Copy to scripts/ in bundle.

---

My Recommendation

✅ YES: Implement Option A (Add Wrappers to Bundle)

Rationale:

1. Users deserve same UX whether they install via dev or bundle
2. Auto-config injection is essential (users won't type --config 100s of times)
3. Complexity is justified (same as dev installation)
4. Bundle should be "self-contained" with all dependencies for good UX

Action Items:

1. Update provisioning.toml to include wrapper scripts
2. Modify install.sh to create wrapper structure
3. Update pack.nu to include scripts/ directory in bundle
4. Test complete installation flow
5. Update documentation to explain wrapper architecture

---

Alternative: Keep Provision.sh?

Wait, maybe provision.sh WAS useful after all!

If we're adding wrapper complexity to install.sh, we might want:

./provision install    # Just install binaries
./provision config     # Just setup configs
./provision wrappers   # Just create wrapper structure
./provision full       # All three (install + config + wrappers)

In this case, provision.sh makes sense as an orchestrator for wrapper creation!

But the issue remains: It's still one-time use during installation.

---

Summary: What Do You Want to Do?

Three options:

1. Option A1: Add wrappers to bundle installer

   • Users get same experience as dev installation
   • Requires modifying install.sh, pack.nu, provisioning.toml
   • Keep provision.sh as orchestrator (now it has value!)

2. Option A2: Add wrappers to bundle, no orchestrator

   • Same result but simpler
   • Users run two steps: install.sh + setup-config.sh
   • Scripts handle wrapper creation internally

3. Option B: Keep bundle simple

   • No wrappers in bundle
   • Users type --config path every time
   • Simpler but worse UX

Recommendation: Option A2 (add wrappers, no provision.sh orchestrator)

---

Clear Statement

What you're asking:

• Should end users (bundle installers) get the same wrapper infrastructure that developers get?

What the answer should be:

• YES! Absolutely. Users need auto-config injection.

What needs to change:

• install.sh should rename binaries to .real and create bash wrappers
• pack.nu should include NuShell wrapper scripts in bundle
• Documentation should explain wrapper architecture to users