Skip to content

Commit c4127b7

Browse files
AlexMikhalevAlexMikhalev
committed
feat(grep): add update commands via shared updater
1 parent 3c62704 commit c4127b7

7 files changed

Lines changed: 525 additions & 5 deletions

File tree

‎.docs/design-terraphim-grep-update.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Implementation Plan: terraphim-grep Update Support
2+
3+
**Status**: Approved for implementation
4+
**Research Doc**: `.docs/research-terraphim-grep-update.md`
5+
**Author**: OpenCode
6+
**Date**: 2026-07-04
7+
**Estimated Effort**: 1-2 hours
8+
9+
## Overview
10+
11+
### Summary
12+
13+
Add explicit update support to `terraphim-grep` by reusing `terraphim_update`. The CLI will gain `check-update` and `update` subcommands while preserving the existing `terraphim-grep <QUERY>` search form.
14+
15+
### Approach
16+
17+
Use the same command pattern as `terraphim-agent`, but configure the updater for `terraphim/terraphim-clients` because that is where `terraphim-grep` releases are published.
18+
19+
### Scope
20+
21+
**In Scope:**
22+
- `terraphim-grep check-update`.
23+
- `terraphim-grep update`.
24+
- Shared `UpdaterConfig::with_repo` helper.
25+
- CLI tests for update command visibility and legacy query mode.
26+
27+
**Out of Scope:**
28+
- Automatic background update checks.
29+
- Binary asset build/signing pipeline.
30+
- Custom install path selection.
31+
- Updating other binaries.
32+
33+
**Avoid At All Cost**:
34+
- Reimplementing update logic outside `terraphim_update`.
35+
- Breaking `terraphim-grep <QUERY>`.
36+
- Adding network calls to normal search.
37+
38+
## Architecture
39+
40+
### Component Diagram
41+
42+
```text
43+
terraphim-grep CLI
44+
|-- legacy search path -> TerraphimGrep::search
45+
|-- check-update -----> UpdaterConfig -> TerraphimUpdater::check_update
46+
`-- update -----------> UpdaterConfig -> TerraphimUpdater::check_and_update
47+
```
48+
49+
### Data Flow
50+
51+
```text
52+
check-update -> config(bin=terraphim-grep, repo=terraphim/terraphim-clients, version=CARGO_PKG_VERSION) -> GitHub Releases -> status output
53+
```
54+
55+
```text
56+
search query -> existing role/thesaurus resolution -> existing grep search path
57+
```
58+
59+
### Key Design Decisions
60+
61+
| Decision | Rationale | Alternatives Rejected |
62+
|----------|-----------|----------------------|
63+
| Add subcommands, keep optional query | Matches `terraphim-agent` and preserves old usage. | Flags-only update API. |
64+
| Add `UpdaterConfig::with_repo` | Avoids mutating public fields directly in each binary and keeps configuration fluent. | Hardcode clients repo inside updater crate. |
65+
| Do not auto-check on search startup | Avoids latency and network dependency on grep. | Background update check on every run. |
66+
67+
### Eliminated Options
68+
69+
| Option Rejected | Why Rejected | Risk of Including |
70+
|-----------------|--------------|-------------------|
71+
| Autoupdate on startup | Not requested; makes grep non-deterministic. | Slow or failed searches due to network. |
72+
| New `terraphim-grep self` command tree | More structure than needed for two commands. | CLI complexity. |
73+
| Release asset/signing work | Separate release pipeline concern. | Larger, riskier change. |
74+
75+
### Simplicity Check
76+
77+
The simplest design is a direct wrapper around `terraphim_update`, plus one repo override method. No speculative abstraction is needed.
78+
79+
**Nothing Speculative Checklist:**
80+
- [x] No features the user did not request.
81+
- [x] No extra update providers.
82+
- [x] No install-path configuration yet.
83+
- [x] No auto network calls during search.
84+
85+
## File Changes
86+
87+
### New Files
88+
89+
None.
90+
91+
### Modified Files
92+
93+
| File | Changes |
94+
|------|---------|
95+
| `crates/terraphim_update/src/lib.rs` | Add `UpdaterConfig::with_repo(owner, repo)`. |
96+
| `crates/terraphim_grep/Cargo.toml` | Add `terraphim_update` dependency. |
97+
| `crates/terraphim_grep/src/main.rs` | Add subcommand enum, updater helper, and early command handling. |
98+
| `crates/terraphim_grep/tests/no_thesaurus_cli.rs` | Add CLI help/check-update visibility or legacy search guard if suitable. |
99+
100+
## API Design
101+
102+
### Shared Updater API
103+
104+
```rust
105+
impl UpdaterConfig {
106+
pub fn with_repo(mut self, owner: impl Into<String>, name: impl Into<String>) -> Self;
107+
}
108+
```
109+
110+
### Grep CLI Types
111+
112+
```rust
113+
#[derive(Subcommand, Debug)]
114+
enum Command {
115+
CheckUpdate,
116+
Update,
117+
}
118+
119+
#[derive(Parser, Debug)]
120+
struct Args {
121+
query: Option<String>,
122+
#[command(subcommand)]
123+
command: Option<Command>,
124+
// existing search options unchanged
125+
}
126+
```
127+
128+
### Grep Helper
129+
130+
```rust
131+
fn grep_updater() -> TerraphimUpdater;
132+
133+
async fn handle_update_command(command: Command) -> Result<()>;
134+
```
135+
136+
## Test Strategy
137+
138+
### Unit Tests
139+
140+
| Test | Location | Purpose |
141+
|------|----------|---------|
142+
| `updater_config_accepts_repo_override` | `terraphim_update/src/lib.rs` tests | Verify helper changes owner/repo. |
143+
144+
### Integration Tests
145+
146+
| Test | Location | Purpose |
147+
|------|----------|---------|
148+
| `cli_runs_without_thesaurus` | Existing grep CLI test | Ensure legacy search still works. |
149+
| `cli_help_lists_update_commands` | `crates/terraphim_grep/tests/no_thesaurus_cli.rs` | Ensure commands are exposed. |
150+
151+
### Manual Smoke Tests
152+
153+
```bash
154+
terraphim-grep --help
155+
terraphim-grep check-update
156+
terraphim-grep "score_kg_boost" --haystack code --paths crates/terraphim_grep/src -C 1
157+
```
158+
159+
## Implementation Steps
160+
161+
### Step 1: Shared Updater Config
162+
163+
**Files:** `crates/terraphim_update/src/lib.rs`
164+
**Description:** Add fluent repo override.
165+
**Tests:** Unit test asserting owner/repo fields change.
166+
167+
### Step 2: Grep Dependency
168+
169+
**Files:** `crates/terraphim_grep/Cargo.toml`
170+
**Description:** Add workspace-local `terraphim_update` dependency with version metadata.
171+
**Tests:** `cargo check -p terraphim_grep`.
172+
173+
### Step 3: Grep CLI Commands
174+
175+
**Files:** `crates/terraphim_grep/src/main.rs`
176+
**Description:** Add subcommands and early handling before query-required search flow.
177+
**Tests:** Help and existing search tests.
178+
179+
### Step 4: Verification
180+
181+
**Files:** tests only if needed.
182+
**Description:** Run focused test suite and manual smoke commands.
183+
184+
## Rollback Plan
185+
186+
1. Revert the grep dependency and CLI command wiring.
187+
2. Revert `UpdaterConfig::with_repo` if no other consumer uses it.
188+
3. Existing search behaviour returns to the prior flat parser.
189+
190+
## Dependencies
191+
192+
### New Dependencies
193+
194+
| Crate | Version | Justification |
195+
|-------|---------|---------------|
196+
| `terraphim_update` | Local path, version metadata | Required shared update implementation. |
197+
198+
## Performance Considerations
199+
200+
Normal search should not call update code, so search performance remains unchanged. `check-update` and `update` are explicitly network-bound commands.
201+
202+
## Open Items
203+
204+
| Item | Status | Owner |
205+
|------|--------|-------|
206+
| Release binary assets for actual self-update install | Deferred | Release engineering |
207+
| Configurable install path | Deferred | Future design |
208+
209+
## Approval
210+
211+
- [x] Technical review complete.
212+
- [x] Test strategy defined.
213+
- [x] Human request received.

0 commit comments

Comments
 (0)