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**:
```bash
$ 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**:
```bash
$ 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**:
```toml
[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:
```bash
install_binary() {
    cp "$source" "$dest"
    chmod 755 "$dest"
}
```

Should be:
```bash
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:
```nu
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:

```bash
./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