This commit is contained in:
Your Name
@@ -0,0 +1,224 @@
|
||||
# Builder Report — Self-Describing Command Registry for POS
|
||||
|
||||
**Date:** 2026-08-26
|
||||
**Status:** COMPLETE
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
- **Status:** All 8 steps implemented and verified
|
||||
- **Files created:** `lib/registry.sh` (199 lines, mode 664)
|
||||
- **Files modified:** `scripts/gen-docs.sh`, `bin/pos-tree`, `templates/pos-tool.sh`, `install.sh`, `DOC/DEV.md`, `DOC/AGENT_Context_Project.md`
|
||||
- **Verification:** All gates pass — gen drift ✅, tree output identical ✅, make check ✅, make lint shows only pre-existing issues ⚠️
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Establish Current State
|
||||
|
||||
**Prerequisite:** Pre-existing gen drift from `pos-ai-alias` was committed as `6566c83` (`chore: re-gen docs for pos-ai-alias addition`) to get a clean baseline.
|
||||
|
||||
**Baselines (all clean after gen drift fix):**
|
||||
|
||||
| Gate | Result |
|
||||
|------|--------|
|
||||
| `pos-tree` output | ✅ exit 0, captured to `/tmp/pos-tree-before.txt` |
|
||||
| `make gen && git diff --exit-code` | ✅ zero diff (gen output matches committed) |
|
||||
| `make check` | ✅ `check-sync: OK` |
|
||||
| `make lint` | ⚠️ 1 FAIL (pre-existing: `bin/pos-ai-alias` not in `INTERACTIVE_CMDS`), 1 WARN (`pos-ai-alias` not in `DOC/POS.md`) — both unrelated to this task |
|
||||
|
||||
**Notes:**
|
||||
- `make lint` takes ~2-3 minutes to complete (scans 56+ files with regex)
|
||||
- The pre-existing lint FAIL on `pos-ai-alias` is outside our scope
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create `lib/registry.sh`
|
||||
|
||||
**File:** `lib/registry.sh` (191 lines, mode 664, no shebang)
|
||||
|
||||
**Changes:**
|
||||
- Created the shared query API library following the architect's pseudocode and `lib/config-ui.sh` structural pattern
|
||||
- Key derivation: `bin/pos-network-download` → key `network-download`, category `network`; `bin/pos-config` → key `config`, category `""`
|
||||
- `reg_scan` sets/restores `LC_ALL=C` for deterministic sort
|
||||
- All associative-array lookups use `${var:-}` fallback for missing keys
|
||||
- `reg_categories` uses a sentinel `__empty__` to handle empty-category associative array limitation in bash
|
||||
- All API functions implemented: `reg_scan`, `reg_list`, `reg_categories`, `reg_tools_in`, `reg_lookup`, `reg_config_scopes`, `reg_config_keys`, `reg_config_envfile`, `reg_each`, `reg_tool_exists`
|
||||
|
||||
**Functional test:** Registry loads all ~40 tools, lookups return correct data, categories list correctly, config scopes found.
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Update `scripts/gen-docs.sh`
|
||||
|
||||
**File:** `scripts/gen-docs.sh` (modified)
|
||||
|
||||
**Changes:**
|
||||
1. **Tools collection loop (lines ~42-47):** Added `deps` and `examples` fields to the pipe-delimited `tools` array format: `"$cat|$sub|$desc|$flags|$subcmds|$deps|$examples"`
|
||||
- `deps`: parsed with same `sed` pattern as existing headers
|
||||
- `examples`: parsed with `grep | sed | paste` (pipe-delimited, `|| true` to handle empty matches with `pipefail`)
|
||||
2. **`_has_deps_examples` flag:** Scans tools array once to determine if any tool has non-empty deps/examples — drives conditional column rendering
|
||||
3. **`gen_tree()`:** Reads 7 fields now; adds `[deps: X]` annotation line when non-empty
|
||||
4. **`gen_dispatch()`:** When `_has_deps_examples=1`, adds Deps/Examples columns to the header and all data rows. When 0, renders unchanged format
|
||||
5. **`gen_filetable()`:** Updated to read 7 fields (output unchanged — no deps/examples columns for now)
|
||||
6. **`gen_posflags()`:** Updated to read 7 fields (output unchanged)
|
||||
7. **`gen_possubcmds()`:** Updated to read 7 fields (output unchanged)
|
||||
|
||||
**Drift check:** `git diff -- DOC/AGENT_Context_Project.md completions/pos.bash` → **zero diff** — gen output is byte-identical to current committed output.
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Migrate `bin/pos-tree`
|
||||
|
||||
**File:** `bin/pos-tree` (modified)
|
||||
|
||||
**Changes:**
|
||||
1. Added `source lib/registry.sh` after common.sh sourcing (with fallback chain)
|
||||
2. Replaced file-scanning loop (`for f in "$self"/pos-*`) with `reg_scan "$self"` + `reg_list` iteration
|
||||
3. Tree data collection now uses `reg_lookup "$tool_key" cat|desc|subcmds|deps`
|
||||
4. `add()` and `render()` functions kept **unchanged** — only data-collection section changed
|
||||
5. When `deps` is non-empty, appended `[deps: X]` to the description string before passing to `add()`
|
||||
|
||||
**Output comparison:** `diff /tmp/pos-tree-before.txt /tmp/pos-tree-after.txt` → **empty (identical)**
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Update `templates/pos-tool.sh`
|
||||
|
||||
**File:** `templates/pos-tool.sh` (modified)
|
||||
|
||||
**Changes:**
|
||||
- Added `# POS_SUBCMDS:`, `# POS_DEPS:`, `# POS_EXAMPLES:` to the header documentation block (step 2 comment)
|
||||
- Placed after existing `# POS_FLAGS:` example
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Update `install.sh`
|
||||
|
||||
**File:** `install.sh` (modified)
|
||||
|
||||
**Changes:**
|
||||
- Added `registry.sh` to the `lib_names` array (line 143) alongside other library names
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Update `DOC/DEV.md`
|
||||
|
||||
**File:** `DOC/DEV.md` (modified)
|
||||
|
||||
**Changes:**
|
||||
- Added `# POS_DEPS:` and `# POS_EXAMPLES:` to the header code block in "Adding a New CLI Tool → Make it discoverable"
|
||||
- Added explanation paragraph for both new headers (POS_DEPS: runtime binary names; POS_EXAMPLES: curated usage examples)
|
||||
- Both documented as optional with graceful degradation
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Update `DOC/AGENT_Context_Project.md`
|
||||
|
||||
**File:** `DOC/AGENT_Context_Project.md` (modified)
|
||||
|
||||
**Changes:**
|
||||
- Added `lib/registry.sh | 199 | Shared query API for POS tool metadata headers (...)` row to the hand-maintained line-count table (above GEN:START filetable marker)
|
||||
- Gen blocks updated via `make gen` (docmap line numbers shifted by +1 section; filetable shows pos-tree at 118 lines)
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Verification
|
||||
|
||||
### Syntax checks
|
||||
```
|
||||
bash -n lib/registry.sh ✅
|
||||
bash -n scripts/gen-docs.sh ✅
|
||||
bash -n bin/pos-tree ✅
|
||||
```
|
||||
|
||||
### Gen drift check
|
||||
```
|
||||
make gen && git diff --exit-code ✅ (no gen drift)
|
||||
```
|
||||
- Generated blocks (tree, dispatch, filetable, selfcontained, posflags, possubcmds, posconfigscopes) are **byte-identical** to committed output
|
||||
- `completions/pos.bash` has **zero diff**
|
||||
|
||||
### Tree output comparison
|
||||
```
|
||||
diff /tmp/pos-tree-before.txt /tmp/pos-tree-final.txt → empty ✅
|
||||
```
|
||||
|
||||
### Self-consistency gate
|
||||
```
|
||||
make check → check-sync: OK ✅
|
||||
```
|
||||
|
||||
### Convention lint gate
|
||||
```
|
||||
make lint → 1 FAIL, 1 WARN (both pre-existing, unrelated to this task)
|
||||
```
|
||||
- FAIL: `bin/pos-ai-alias` not in `INTERACTIVE_CMDS` — pre-existing
|
||||
- WARN: `bin/pos-ai-alias` not in `DOC/POS.md` — pre-existing
|
||||
- **Zero new issues from this implementation**
|
||||
|
||||
### Summary
|
||||
|
||||
| Gate | Result | Notes |
|
||||
|------|--------|-------|
|
||||
| Syntax | ✅ all pass | registry.sh, gen-docs.sh, pos-tree |
|
||||
| Gen drift | ✅ zero diff | Gen blocks byte-identical |
|
||||
| Tree output | ✅ identical | Before/after comparison empty |
|
||||
| make check | ✅ OK | Full self-consistency gate |
|
||||
| make lint | ⚠️ 1 FAIL, 1 WARN | Pre-existing only (pos-ai-alias) |
|
||||
|
||||
[DONE]
|
||||
|
||||
---
|
||||
|
||||
## Artifact Summary
|
||||
|
||||
### Files Created
|
||||
|
||||
| File | Mode | Lines | Purpose |
|
||||
|------|------|-------|---------|
|
||||
| `lib/registry.sh` | 664 | 199 | Shared query API for POS tool metadata headers |
|
||||
|
||||
### Files Modified
|
||||
|
||||
| File | Nature of Change |
|
||||
|------|-----------------|
|
||||
| `scripts/gen-docs.sh` | Added deps/examples to tools array format; conditional columns in gen_dispatch; deps annotation in gen_tree |
|
||||
| `bin/pos-tree` | Migrated data collection from direct sed to registry API; source registry.sh |
|
||||
| `templates/pos-tool.sh` | Documented POS_SUBCMDS, POS_DEPS, POS_EXAMPLES headers |
|
||||
| `install.sh` | Added `registry.sh` to lib_names array |
|
||||
| `DOC/DEV.md` | Documented POS_DEPS and POS_EXAMPLES in "Make it discoverable" |
|
||||
| `DOC/AGENT_Context_Project.md` | Added lib/registry.sh row to hand-maintained line-count table; gen blocks updated |
|
||||
|
||||
### Files NOT Modified (scope compliance)
|
||||
|
||||
- `bin/pos` — dispatcher logic untouched ✅
|
||||
- `completions/pos.bash` — no changes needed ✅
|
||||
- `lib/config-ui.sh` — not integrated with registry ✅
|
||||
- No `# POS_DEPS:` or `# POS_EXAMPLES:` added to existing tools ✅
|
||||
|
||||
### Prerequisite Commits
|
||||
|
||||
1. `6566c83` — `chore: re-gen docs for pos-ai-alias addition` (pre-existing gen drift)
|
||||
2. `5d7407e` — `chore: update docmap + filetable for registry.sh addition` (gen output for my changes)
|
||||
|
||||
### Pre-existing Issues (not in scope)
|
||||
|
||||
- `bin/pos-ai-alias`: FAIL — reads stdin but not in `INTERACTIVE_CMDS`
|
||||
- `bin/pos-ai-alias`: WARN — not referenced in `DOC/POS.md`
|
||||
Reference in New Issue
Block a user