1  // SPDX-License-Identifier: AGPL-3.0-or-later
  2  // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell
  3  = Reposystem Roadmap
  4  :toc: preamble
  5  :toclevels: 3
  6  
  7  f/i staged development plan for Reposystem — the railway yard for your repository ecosystem.
  8  
  9  == Vision
 10  
 11  A visual wiring layer that sits above individual repos, allowing you to:
 12  
 13  1. **Import** repositories (yours + upstreams)
 14  2. **Identify** components/slots/providers
 15  3. **Rewire** projects by switching providers (local ↔ ecosystem ↔ fallback)
 16  4. **Tag** with aspects (security, reliability, etc.) and flip views
 17  5. **Reason** about the dependency graph including contingency paths
 18  
 19  == Technology Stack
 20  
 21  Per Rhodium Standard Repository (RSR) language policy:
 22  
 23  [cols="1,2,2"]
 24  |===
 25  |Layer |Language |Notes
 26  
 27  |Core data model
 28  |ReScript
 29  |Type-safe, compiles to ES6 modules
 30  
 31  |CLI
 32  |Rust
 33  |Performance, cross-platform
 34  
 35  |Runtime
 36  |Deno
 37  |Replaces Node/npm
 38  
 39  |Config
 40  |Nickel
 41  |Complex configuration
 42  
 43  |State files
 44  |Guile Scheme
 45  |STATE.scm, META.scm, ECOSYSTEM.scm
 46  
 47  |Graph export
 48  |DOT/SVG + JSON
 49  |Standard formats
 50  |===
 51  
 52  == f/i Staged Plan
 53  
 54  === f1 — Freeze: MVC Graph + Tagging + Export
 55  
 56  The minimum viable cockpit: visualise, group, tag, export.
 57  
 58  ==== MUST (Freeze Criteria)
 59  
 60  * [ ] **Repo importer** — Import from local folder of git clones
 61  * [ ] **Persistent graph store** — Nodes, edges, groups in JSON
 62  * [ ] **Manual edges** — Create relationships between repos
 63  * [ ] **Manual groups** — Cluster repos into logical units
 64  * [ ] **Manual aspect tags** — Tag nodes/edges with aspects
 65  * [ ] **View filters** — Filter by group, by aspect
 66  * [ ] **Export DOT** — Graphviz-compatible output
 67  * [ ] **Export JSON** — Machine-readable graph export
 68  * [ ] **Re-import fidelity** — Re-import exported JSON → identical graph
 69  
 70  ==== SHOULD
 71  
 72  * [ ] Lightweight auto-suggestions (non-authoritative):
 73  ** Detect "container-ish" repos (Dockerfile/Containerfile)
 74  ** Detect "CI-ish" repos (.github/workflows, .gitlab-ci.yml)
 75  ** Propose tags with "why" shown, user must accept
 76  * [ ] Basic edge auto-detection from package.json / deno.json imports
 77  
 78  ==== COULD
 79  
 80  * [ ] Basic "weak link" lens:
 81  ** Show nodes/edges with highest security weight
 82  ** Show nodes tagged supply-chain with "unknown provenance"
 83  * [ ] Simple TUI for interactive exploration
 84  
 85  ==== Freeze Criteria
 86  
 87  You can import 50+ repos, group them, tag them, export the graph, re-open it later unchanged.
 88  
 89  ==== Deliverables
 90  
 91  [source]
 92  ----
 93  src/
 94  ├── importers/
 95  │   └── local_scan.res      # Scan local clones
 96  ├── graph/
 97  │   ├── types.res           # Repo, Edge, Group, Aspect types
 98  │   ├── store.res           # Graph persistence
 99  │   └── validation.res      # Invariant checks
100  ├── export/
101  │   ├── dot.res             # DOT format export
102  │   └── json.res            # JSON export
103  └── cli/
104      └── main.rs             # Rust CLI wrapper
105  ----
106  
107  ---
108  
109  === i1 — Seam Review: Graph ↔ Evidence ↔ Export
110  
111  Cross-stage seam checks before proceeding.
112  
113  ==== Invariants to Verify
114  
115  [cols="1,3"]
116  |===
117  |Seam |Check
118  
119  |Graph determinism
120  |Same repo set → same node IDs
121  
122  |Tag provenance
123  |Every non-manual tag carries rule + evidence
124  
125  |Export fidelity
126  |Re-import exported JSON → identical graph (isomorphic)
127  
128  |Edge consistency
129  |All edges reference existing nodes
130  |===
131  
132  ==== Backpatch
133  
134  Anything that violates reversibility/explainability.
135  
136  ---
137  
138  === f2 — Freeze: Slots/Providers Registry
139  
140  Define the component model (still no applying changes).
141  
142  ==== MUST
143  
144  * [ ] **Slot definitions** — Declare what can be swapped
145  * [ ] **Provider definitions** — Declare what provides a slot
146  * [ ] **Repo-to-provider links** — Provider X is implemented by repo Y
147  * [ ] **Slot/provider overlay in graph** — Visual indication
148  
149  ==== SHOULD
150  
151  * [ ] Compatibility metadata (version, interface kind)
152  * [ ] Adapter stubs (declared, not executed)
153  
154  ==== COULD
155  
156  * [ ] Scenario snapshots (local vs ecosystem) in graph only
157  * [ ] "What if" visualisation without actual changes
158  
159  ==== Deliverables
160  
161  [source]
162  ----
163  src/
164  ├── slots/
165  │   ├── types.res           # Slot, Provider, Adapter types
166  │   ├── registry.res        # Slot/provider registry
167  │   └── compatibility.res   # Version/interface matching
168  └── spec/
169      └── registry.ncl        # Nickel schema for registry
170  ----
171  
172  ---
173  
174  === i2 — Seam Review: Slot Model ↔ Aspect Model
175  
176  ==== Invariants to Verify
177  
178  [cols="1,3"]
179  |===
180  |Seam |Check
181  
182  |Provider substitution
183  |Changing a provider changes edges, not repo identity
184  
185  |Aspect attachment
186  |Aspects can attach to slots/providers/edges without ambiguity
187  
188  |No hidden edges
189  |No "inferred" edges without explanation
190  |===
191  
192  ---
193  
194  === f3 — Freeze: Plan Generation + Dry-Run Diff
195  
196  Generate and preview plans (apply comes later).
197  
198  ==== MUST
199  
200  * [ ] **Create plan from scenario** — Choose switches, generate plan
201  * [ ] **Dry-run diff** — Show intended file changes as patches
202  * [ ] **Rollback plan** — Define reversal (even if not executed yet)
203  
204  ==== SHOULD
205  
206  * [ ] Validate plan against compatibility + smoke-test hooks (declared)
207  * [ ] Risk assessment per edge change
208  
209  ==== COULD
210  
211  * [ ] Auto-fallback logic (policy-level, not implementation-level)
212  * [ ] Plan comparison between scenarios
213  
214  ==== Deliverables
215  
216  [source]
217  ----
218  src/
219  ├── plans/
220  │   ├── types.res           # Plan, ChangeSet, Op types
221  │   ├── generator.res       # Generate plan from scenario
222  │   ├── diff.res            # Generate diffs
223  │   └── rollback.res        # Rollback plan generation
224  └── cli/
225      ├── plan.rs             # `reposystem plan` command
226      └── diff.rs             # `reposystem diff` command
227  ----
228  
229  ---
230  
231  === i3 — Seam Review: Plan ↔ Apply ↔ Rollback
232  
233  ==== Invariants to Verify
234  
235  [cols="1,3"]
236  |===
237  |Seam |Check
238  
239  |Plan replayability
240  |Same inputs → same plan output
241  
242  |Diff accuracy
243  |Generated diff matches actual changes
244  
245  |Rollback completeness
246  |Rollback plan undoes all changes in apply plan
247  |===
248  
249  ---
250  
251  === f4 — Freeze: Apply + Rollback Execution
252  
253  Actually execute changes (carefully).
254  
255  ==== MUST
256  
257  * [ ] **Apply plan** — Execute changes to repos
258  * [ ] **Rollback** — Revert to previous state
259  * [ ] **Audit log** — Record all applied changes
260  
261  ==== SHOULD
262  
263  * [ ] Health checks post-apply
264  * [ ] Auto-rollback on failure
265  
266  ==== COULD
267  
268  * [ ] Staged apply (one repo at a time with confirmation)
269  * [ ] Backup before apply
270  
271  ---
272  
273  === f5 — Freeze: Interactive TUI
274  
275  A "HUD-lite" for interactive exploration.
276  
277  ==== MUST
278  
279  * [ ] Switch toggles (local/ecosystem/auto)
280  * [ ] Preview diffs before apply
281  * [ ] Show risk flags per change
282  
283  ==== SHOULD
284  
285  * [ ] Aspect flip views
286  * [ ] Scenario comparison side-by-side
287  
288  ==== COULD
289  
290  * [ ] Keyboard navigation
291  * [ ] Mouse support
292  
293  ---
294  
295  === f6 — Freeze: GUI Railway Yard
296  
297  The full visual experience (post-MVP).
298  
299  ==== COULD
300  
301  * [ ] Drag-and-drop canvas
302  * [ ] Point-switches with visual feedback
303  * [ ] Animated routing preview
304  * [ ] Contingency paths visualisation
305  
306  == "Hello Yard" Milestone
307  
308  The concrete first deliverable to maintain momentum.
309  
310  === Scope
311  
312  Pick one slot and support it end-to-end:
313  
314  * **Slot**: `container.runtime`
315  * **Providers**: `podman` (local), `cerro-torre` (ecosystem)
316  * **Consumer repos**: 2–3 repos that do container work
317  
318  === Deliverables
319  
320  1. `spec/DATA-MODEL.adoc` — Done ✓
321  2. `spec/CONCEPTS.adoc` — Done ✓
322  3. `registry.adoc` — Slot + provider declarations
323  4. CLI commands:
324  ** `reposystem scan` — Import repos
325  ** `reposystem plan --repo X --slot container.runtime --provider cerro-torre`
326  ** `reposystem apply`
327  ** `reposystem rollback`
328  ** `reposystem graph --format dot`
329  
330  == MVP Definition
331  
332  === What's In
333  
334  * Import repos from local folder
335  * Create graph (nodes = repos, edges = relationships)
336  * Group repos manually
337  * Tag nodes/edges with aspects manually
338  * "Flip view" to show chosen aspect
339  * Export to DOT + JSON
340  
341  === What's Out (for Now)
342  
343  * Auto-detection of slots/providers
344  * Actual substitution/patching
345  * Forge API integration (GitHub/GitLab)
346  * GUI (TUI first)
347  
348  == Existing Tool Mapping
349  
350  Where existing tools can help:
351  
352  [cols="1,2,2"]
353  |===
354  |Component |Existing Tool |Notes
355  
356  |Graph storage
357  |SQLite / JSON files
358  |Simple, portable
359  
360  |Graph visualization
361  |Graphviz, D2, Mermaid
362  |DOT export target
363  
364  |TUI framework
365  |Ratatui (Rust)
366  |Terminal UI
367  
368  |Diagramming
369  |Structurizr, PlantUML
370  |Reference for concepts
371  
372  |Dependency analysis
373  |dep-tree, Madge
374  |Inspiration only
375  |===
376  
377  == Gap Analysis
378  
379  What doesn't exist yet (the value proposition):
380  
381  [cols="1,3"]
382  |===
383  |Gap |What Reposystem Provides
384  
385  |Multi-repo component graph
386  |Graph of repos + components + programmable switches
387  
388  |Aspect tagging
389  |Orthogonal view layers on dependency graph
390  
391  |Component substitution with rollback
392  |Built-in provider swap with reversibility
393  
394  |Scenario comparison
395  |A/B testing with aspect impact analysis
396  |===
397  
398  == Success Criteria
399  
400  === f1 Complete When
401  
402  1. Can import 50+ repos in under 30 seconds
403  2. Can create/edit/delete edges and groups
404  3. Can tag with all 10 aspects
405  4. Export produces valid DOT and JSON
406  5. Re-import JSON produces identical graph
407  
408  === MVP Complete When
409  
410  1. All f1 criteria met
411  2. At least one slot/provider pair working
412  3. `reposystem plan` generates valid diff
413  4. Documentation covers all commands
414  
415  == Related Projects
416  
417  [cols="1,2"]
418  |===
419  |Project |Relationship
420  
421  |git-visor
422  |Consumes graph for forge HUD
423  
424  |git-seo
425  |Consumes graph for discoverability
426  
427  |rhodium-standard-repositories
428  |Standards this tool helps enforce
429  
430  |gitvisor
431  |Existing related work (examine for patterns)
432  |===