Breaking API changes: Improve command verbs and defaults for better UX

[korenmiklos]

Summary

Implement breaking API changes to improve command verbs, terminology, and defaults based on familiar developer mental models (git, docker, conda, poetry).

Motivation

Current command names and behaviors don't align with user expectations from familiar tools:

• bead develop → should be bead open (like git clone, docker run, tar -x)
• bead zap → should be bead remove/delete (destructive actions are never whimsical)
• Output folder should be loaded by default (symmetry with input folder)
• Need interactive confirmation for destructive operations

Breaking Changes

1. Rename bead develop → bead open

Current: bead develop <archive> - Opens an archive into a workspace
New: bead open <archive> - Opens a frozen bead into an editable state

Mental models:

• docker run (launch container from image)
• git clone (open repo from remote)
• tar -xf (unpack archive)

Implementation:

• Rename command from develop to open
• Keep develop as deprecated alias with warning
• Update all documentation and help text

2. Load output folder by default

Current: Output folder not loaded when opening archives
New: Output folder loaded by default, with --no-output flag to opt out

Rationale:

• Users expect symmetry between inputs and outputs
• Matches mental model from Make/Snakemake
• Most users want to see previous results

Implementation:

• Change default behavior to load output
• Add --no-output flag to skip output loading
• Update documentation to explain new default

3. Rename bead zap → bead remove (with aliases)

Current: bead zap - Deletes workspace without confirmation
New:

• Primary: bead remove
• Aliases: bead delete, bead zap (deprecated)
• Interactive confirmation by default
• --force flag to skip confirmation

Mental models:

• git rm, docker rm, conda remove
• Destructive actions are always "remove/delete" in professional tools

Implementation:

• Rename primary command to remove
• Add delete as full alias
• Keep zap as deprecated alias with warning
• Add interactive confirmation prompt
• Add --force flag to bypass confirmation
• Confirmation should clearly state what will be deleted

Deprecation Strategy

Phase 1: v0.9.0 (Transition Release)

• Add new commands (open, remove)
• Keep old commands as aliases with deprecation warnings
• Warning message: "Warning: 'bead develop' is deprecated and will be removed in v1.0.0. Use 'bead open' instead."
• Update documentation to use new commands
• Add migration guide to README

Phase 2: v1.0.0 (Breaking Release)

• Remove deprecated commands entirely
• Clean up codebase
• Update major version to signal breaking changes

Documentation Updates

Terminology in Docs

Use clear state-based terminology:

• Open bead - editable working state (folder with inputs/outputs/code)
• Frozen/Closed bead - saved archive state (.zip file)

Avoid jargon terms like "workspace" and "archive" in user-facing docs.

Example Documentation

## Working with Beads

A bead has two states:
- **Open bead** – an editable folder where you work on your computation
- **Frozen bead** – a saved, portable archive (.zip) of your computation

### Basic Workflow
```bash
# Create a new open bead
bead new my-analysis

# Work on your code...

# Save (freeze) your bead to an archive
bead save

# Later, open a frozen bead to continue work
bead open my-analysis_20240315.zip

# Remove a bead when no longer needed
bead remove  # Will ask for confirmation

## Testing Requirements

### Backward Compatibility Tests
- [ ] Verify deprecated commands still work with warnings
- [ ] Test that existing scripts don't break silently
- [ ] Ensure warning messages are clear and actionable

### New Behavior Tests
- [ ] Test `bead open` with and without `--no-output`
- [ ] Test `bead remove` interactive confirmation
- [ ] Test `bead remove --force` bypasses confirmation
- [ ] Test all command aliases work correctly

### Edge Cases
- [ ] Empty workspaces
- [ ] Workspaces with uncommitted changes
- [ ] Archives with missing dependencies
- [ ] Removal of non-existent beads

## Migration Guide for Users

### For Scripts and Automation
```bash
# Old way
bead develop archive.zip
bead zap

# New way (v0.9.0+)
bead open archive.zip --no-output  # if you don't want outputs
bead remove --force  # for scripts, skip confirmation

# New way (interactive use)
bead open archive.zip  # outputs loaded by default
bead remove  # will ask for confirmation

Command Mapping

Old Command	New Command	Notes
bead develop	bead open	Output loaded by default now
bead develop (no output)	bead open --no-output	Explicit flag needed
bead zap	bead remove	Interactive confirmation added
bead zap (scripted)	bead remove --force	Skip confirmation

Success Criteria

• Commands feel familiar to users of git/docker/conda
• Destructive operations are safe by default
• Migration path is clear and well-documented
• No silent breaking changes - all changes have warnings/errors

Timeline

• v0.9.0: Introduce new commands with deprecation warnings (2-3 weeks)
• v0.9.x: Gather user feedback, refine if needed (1-2 months)
• v1.0.0: Remove deprecated commands (3-4 months)

References

• Mental models from: git, docker, conda, poetry, npm
• Principle: "Destructive actions are never whimsical"
• Principle: "Symmetry in paired operations (input/output)"