🔧 SSCLI Development Quick Reference

🔧 SSCLI Development Quick Reference

What’s New

1. Local Dev Version Swapper

sscli dev                  # Show current version status
sscli dev swap            # Toggle between pip and local build
sscli dev use-local       # Explicitly use local build
sscli dev use-pip         # Explicitly use pip version
sscli dev test            # Quick test of current config
sscli dev build           # Build local package
sscli dev info            # Show environment details

2. Three Menu Modes

Mode Selection (appears after authentication):

Select Your Experience:
  → Seed & Source (Client Side)       [All users]
  → Foundry Ops (Internal Side)        [Admin/Internal Dev]
  → 🔧 Development Tools               [Admin + Local Dev]

3. Development Tools Menu

Access only when: is_admin() AND is_internal_dev()

sscli interactive
→ Select "🔧 Development Tools"
→ Choose:
   • Check Build Version       - Current version & source
   • Compare Build Differences - Local vs Pip versions
   • Run Development Tests     - Validate imports & env
   • View Development Info     - Python, packages, venv

---

Architecture at a Glance

sscli interactive
  ├─→ Show Logo (with version v1.4.0)
  ├─→ Auth Gate (license-server)
  ├─→ Internal Gate (admin? local-dev?)
  └─→ Route to Experience:
      ├─ CLIENT (standard user menu)
      ├─ INTERNAL (ops & admin menu)
      ├─ DEVELOPMENT (dev tools menu)
      └─ EXIT (cancelled)

---

Directory Structure

foundry/
├── tools/                           [NEW]
│   ├── __init__.py
│   ├── client/                      [For future]
│   │   └── __init__.py
│   ├── internal/                    [For future]
│   │   └── __init__.py
│   └── development/                 [Development tools]
│       ├── __init__.py
│       └── build_tools.py
│
├── development_experience.py        [NEW]
├── gate.py                          [MODIFIED - 3 modes]
├── animated_experience.py           [MODIFIED - dev mode route]
├── internal_experience.py           [EXISTING]
└── [other modules...]

---

Key Files Changed

File	Change	Impact
gate.py	Menu supports 3 modes	Developers see dev tools if admin+local
animated_experience.py	Route DEVELOPMENT mode	Loads dev experience for admins
logo_reveal.py	Show version in logo	Version displays during animation
development_experience.py	NEW - Dev tools menu	Dev tools accessible
tools/development/build_tools.py	NEW - Dev functions	Debugging/build tools
/bin/sscli-dev	NEW - Root script	Swap pip/local versions

---

How to Use (Step-by-Step)

As a Local Developer (Admin)

# 1. Check what you're running
sscli dev
# Output: Shows if on pip version or local build

# 2. Test the build locally (optional)
./scripts/smoke-test.sh

# 3. Swap to local build if needed
sscli dev swap
# Reinstalls sscli from your local stack-cli/

# 4. Access development tools
sscli interactive
# Menu appears → Select "🔧 Development Tools"

# 5. Run a dev tool
# → Select "Check Build Version"
# → Shows: v1.4.0, Location, Source (local/pip)

As a Regular User

# Standard flow (unchanged)
sscli interactive
→ Select "Seed & Source (Client Side)"
→ Use normal client menu

---

Testing Your Changes

# 1. Verify syntax
python3 -m py_compile stack-cli/foundry/development_experience.py
python3 -m py_compile stack-cli/foundry/tools/development/build_tools.py

# 2. Run smoke test
./scripts/smoke-test.sh

# 3. Test dev swap
sscli dev status
sscli dev swap        # If you want to toggle versions

# 4. Test the menu
sscli interactive
# Should show all 3 modes if admin+local-dev

# 5. Test dev tools
# Select "🔧 Development Tools" → Pick a tool

---

Troubleshooting

”🔧 Development Tools” not showing?

• Need to be admin tier user
• Need to be in is_internal_dev() environment
• Check: sscli whoami to see tier

Version not showing in logo?

• Ensure stack-cli/pyproject.toml has version field
• Check format: [project] version = "1.4.0"

sscli dev swap fails?

• Use a virtual environment
• Ensure --user flag is available or use venv
• Check: which python for correct interpreter

---

Common Commands Cheat Sheet

# Check current state
sscli dev                              # Show version & source
sscli dev info                         # Show environment

# Swap versions
sscli dev swap                         # Toggle pip←→local
sscli dev use-local                    # Go to local
sscli dev use-pip                      # Go to pip package

# Development
sscli dev build                        # Build locally
sscli dev test                         # Test current config
sscli interactive                      # Full menu (includes dev tools)

# Deployment
./scripts/smoke-test.sh                # Pre-deployment check
./scripts/bump-version.sh patch        # Bump & tag

---

What’s Where

Feature	Where	Access
Version display	Logo animation	Automatic (bottom-right)
3-mode menu	gate.py	After auth
Dev tools	development_experience.py	Admin + local
Build tools	tools/development/build_tools.py	Dev tools menu
Version swap	/bin/sscli-dev	Terminal: sscli dev

---

Quick Debugging

All 3 modes working?

sscli interactive
# Should ask: "Select Your Experience:" with 3 options
# If only 1 option: Not admin or not in local-dev environment

Building locally?

sscli dev
# Shows source: "Local development build" vs "Installed pip package"

Tools responding?

sscli interactive
→ 🔧 Development Tools
→ Check Build Version
# Should show version and location

---

Notes for Developers

• Non-breaking: All changes are backward compatible
• Gradual expansion: Tools directories ready for future additions
• Modular design: Easy to add client/ and internal/ tools later
• Version tracking: Automatic from pyproject.toml (always current)
• Safe defaults: Graceful failure if features unavailable
• Local-only: Dev mode only for admins in local code environment

---

Next Steps

1. Deploy and test the three modes
2. Add client-specific tools to tools/client/
3. Migrate internal tools to tools/internal/
4. Expand development tools as needed
5. Document new tools in their respective modules

---

Last Updated: February 2026 Stable: Yes - All syntax validated, no breaking changes Ready for: Testing → Deployment