fledge 0.16.0

Dev-lifecycle CLI — scaffolding, tasks, lanes, plugins, and more.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

---
module: spinner
version: 1
status: active
files:
  - src/spinner.rs

db_tables: []
depends_on: []
---

# Spinner

## Purpose

Provide a consistent loading spinner for long-running operations (network calls, git pushes, etc.). Randomly selects from 10 visual themes on each invocation for personality.

## Public API

### Exported Functions

| Export | Description |
|--------|-------------|
| `Spinner` | Loading spinner with random theme selection |
| `start` | Create and start a spinner with a message (`Spinner::start`) |
| `finish` | Stop the spinner and clear its line (`Spinner::finish`) |

### Structs & Enums

| Type | Description |
|------|-------------|
| `Spinner` | Wraps `indicatif::ProgressBar` with themed animation |

### Functions

| Function | Signature | Description |
|----------|-----------|-------------|
| `Spinner::start` | `(&str) -> Spinner` | Create and start a spinner with the given message |
| `Spinner::finish` | `(&self) -> ()` | Stop the spinner and clear its line |

## Internal Details

### Theme

| Field | Type | Description |
|-------|------|-------------|
| `frames` | `&'static [&'static str]` | Animation frame sequence (last frame is blank for clean finish) |
| `interval_ms` | `u64` | Milliseconds between frame ticks |

### Constants

| Constant | Description |
|----------|-------------|
| `THEMES` | 10 spinner themes: clock emoji, rock-paper-scissors, moon phases, weather, globe, 5 braille/block/arrow variants |

### Functions

| Function | Signature | Description |
|----------|-----------|-------------|
| `random_index` | `(usize) -> usize` | Platform-aware RNG: `/dev/urandom` on Unix, `SystemTime` nanos on other platforms |

## Invariants

1. Every theme's last frame is a single space (`" "`) so `finish_and_clear` leaves no artifacts
2. `random_index` never panics — fallback to 0 if RNG source fails (all-zero buf → `0 % max`)
3. Spinner template is `"  {msg} {spinner}"` — two-space indent, message before animation
4. All themes have at least 3 frames
5. Interval range is 80–300ms across all themes

## Behavioral Examples

```
# Spinner appears during any network/git operation
$ fledge templates search rust
  Searching GitHub for community templates: ⠙    # animates through braille frames

$ fledge work pr
  Pushing feat/spinner to origin: 🌎    # animates through globe frames
  ✅ Pushed to origin/feat/spinner
```

## Error Cases

| Error | When | Behavior |
|-------|------|----------|
| None | Spinner is infallible | `start` always succeeds; `finish` always clears |

## Dependencies

- `indicatif` — progress bar / spinner rendering

## Change Log

| Version | Date | Changes |
|---------|------|---------|
| 1 | 2026-04-20 | Initial spec |