syntaxis/docs/wrappers/adr-decision-summary.md

ADR-001: WRAPPER STRATEGY - DECISION SUMMARY

The Question (Asked 3 Times! 🎯)

"Are we going to use wrappers for installation? Should it be optional?"

---

The Deep Analysis: Wrapper Value Formula

Wrapper Justification = Frequency × User Burden Saved ÷ Maintenance Complexity

Good wrapper:  High Frequency + High Burden + Low Complexity = KEEP ✅
Bad wrapper:   Low Frequency + Low Burden + High Complexity = REMOVE ❌

---

Pattern 1: Binary Execution Wrappers (EXISTING - KEEP ✅)

Real-World Example

Without wrapper:
$ syntaxis-cli --config ~/.config/syntaxis/config.toml status
$ syntaxis-cli --config ~/.config/syntaxis/config.toml project list
$ syntaxis-cli --config ~/.config/syntaxis/config.toml task create
# ... 100s of times per day, 365 days a year

With wrapper:
$ syntaxis-cli status
$ syntaxis-cli project list
$ syntaxis-cli task create

Analysis

• Frequency: 100s invocations per day
• User Burden: 50 chars per invocation (--config path)
• Savings: 50 × 100 × 365 = ~1.8 MILLION characters per year
• Maintenance Complexity: 3 layers (Bash → NuShell → Rust)

Verdict

VALUE >> COMPLEXITY → KEEP THE WRAPPER ✅

Why It Works

1. Called frequently (100s per day)
2. Solves real problem (config path typing)
3. Wrapper is transparent to users
4. Can be bypassed if needed (via .real extension)
5. Stable and proven system

---

Pattern 2: Installation Wrapper (NEW - REMOVE ❌)

Real-World Example

With wrapper:
$ ./provision full

Without wrapper:
$ bash install.sh --interactive
$ bash setup-config.sh --interactive

Analysis

• Frequency: 1 invocation per user lifetime
• User Burden: 50 characters ONCE (not repeating)
• Savings: 50 characters total, one time only
• Maintenance Complexity: Multi-layer orchestration + shell detection

Verdict

COMPLEXITY >> VALUE → REMOVE THE WRAPPER ❌

Why It Doesn't Work

1. Called once per lifetime (not frequent)
2. User doesn't type --config path on install
3. Only saves ~5 seconds of typing (one-time)
4. Adds confusion: Which command to use?
   • provision full ?
   • provision install ?
   • bash install.sh ?
   • bash setup-config.sh ?
5. Violates philosophy: "No unnecessary complexity"

---

The Key Insight (You Nailed It!)

"Users don't want to add --config path for each call"

Exactly! That's why binary wrappers are ESSENTIAL.

But:

"Installer wrappers add complexity... Are we going to use wrappers?"

Right! The installer wrapper adds complexity for a one-time event that doesn't have the --config problem.

---

The Decision

KEEP Binary Execution Wrappers ✅

Why:  Users invoke 100s times per day
      Typing burden is significant and repetitive
      Complexity is justified

What: Bash wrapper → NuShell wrapper → Real binary
      Auto-injects --config path
      Config discovery is automatic

Where: ~/.cargo/bin/syntaxis-cli (wrapper)
       ~/.cargo/bin/syntaxis-cli.real (binary)
       ~/.config/syntaxis/scripts/syntaxis-cli.nu (NuShell orchestrator)

REMOVE Installation Wrapper ❌

Why:  Users install once
      Not a repetitive burden
      Complexity not justified
      Causes confusion

What: Delete provision.sh
      Keep only install.sh and setup-config.sh
      Simple two-step process

How:  bash install.sh --interactive
      bash setup-config.sh --interactive

---

Implementation Plan

What Changes

BEFORE (Confusing):
  Bundle contains:
  - provision.sh         ← Master wrapper (optional?)
  - install.sh           ← Direct installer (optional?)
  - setup-config.sh      ← Config helper (optional?)

  User confusion: Which one should I use?

AFTER (Clear):
  Bundle contains:
  - install.sh           ← Install binaries
  - setup-config.sh      ← Configure

  User knows: Two clear steps

Steps

1. Delete scripts/provisioning/provision.sh
2. Update configs/provisioning.toml (remove provision.sh from scripts array)
3. Update docs/docs/installation.md (show two-step process)
4. Update docs/BUNDLE_README.md (show simple sequence)
5. Rebuild bundle with nu scripts/provisioning/pack.nu

Result

# Before
tar -tzf dist/*.tar.gz | grep -E '(provision|install)'
  provision.sh        ← CONFUSION
  install.sh
  install.nu
  setup-config.sh

# After
tar -tzf dist/*.tar.gz | grep -E '(provision|install)'
  install.sh          ← CLARITY
  install.nu
  setup-config.sh

---

Risk Assessment

Very Low Risk ✅

• ✅ Removing an optional component
• ✅ Direct scripts are proven to work
• ✅ No impact on binary wrappers (which will stay)
• ✅ No impact on user experience
• ✅ Reduces maintenance burden

If Something Goes Wrong

• Can always re-add provision.sh
• Direct scripts are bulletproof
• Bundle is self-contained

---

Why This Matters

Philosophy Alignment

SYNTAXIS says:

• ✅ "Configuration-driven design" → Wrappers help with config discovery
• ✅ "Modular with features to add or avoid" → Don't add unnecessary features
• ✅ "Users understand what's happening" → Direct scripts are transparent

Keeping both wrappers violates principle #2 and #3.

Maintenance Burden

Before: Test 6 code paths × 3 shells × 4 platforms After: Test 2 code paths × 3 shells × 4 platforms = 75% reduction in test matrix

User Documentation

Before: "Use provision full OR provision install OR bash install.sh OR..." After: "Run install.sh then setup-config.sh" = Much simpler!

---

The Bottom Line

✅ KEEP Binary Execution Wrappers

syntaxis-cli status    ← Wrapper auto-injects config
                          (saves millions of characters typed)

❌ REMOVE Installation Wrapper

bash install.sh        ← Direct script
bash setup-config.sh   ← Direct script
                          (one-time setup, no repetition)

The Principle

Wrappers should solve FREQUENT problems, not RARE ones.

Installation happens once. Config path injection happens daily.

---

Files

• Decision Document: docs/adr/ADR-001-wrapper-architecture-strategy.md
• Status: APPROVED - Ready to implement
• Implementation: Cleanup provisioning system as outlined above