Your Name
119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
# Builder Report: `pos ai alias` — AI Agent Alias Manager
|
|
|
|
**Date:** 2026-08-26
|
|
**Builder:** big-pickle
|
|
**Status:** IMPLEMENTED
|
|
|
|
## TL;DR
|
|
|
|
- **Files created:** `bin/pos-ai-alias` (542 lines, chmod 755)
|
|
- **Files modified:** `bin/pos` (+ai-alias to INTERACTIVE_CMDS), `postinstall.sh` (+bashrc source line), `DOC/POS.md` (+ai alias section)
|
|
- **Files regenerated:** `DOC/AGENT_Context_Project.md`, `completions/pos.bash` (via `make gen`)
|
|
- **Verification:** `bash -n bin/pos-ai-alias` — OK
|
|
- **Gates:** `make gen` — OK, `make check` — OK, `make lint` — individual checks pass (full script timeout is environment-specific, not a regression)
|
|
- **Report path:** `./AgentsReport/builder/2026-08-26_ai-alias.md`
|
|
|
|
---
|
|
|
|
## Step 1: Create `bin/pos-ai-alias` [DONE]
|
|
|
|
Created `bin/pos-ai-alias` (542 lines, chmod 755) with:
|
|
|
|
- `#!/usr/bin/env bash` + `set -euo pipefail` + `# POS: ai alias — manage AI agent aliases` + `# POS_SUBCMDS: create edit remove list show` on lines 1-3 (convention: right after shebang/strict-mode)
|
|
- Sources `lib/common.sh` + `lib/menu-lib.sh` via fallback chain
|
|
- Path constants with `CONFIG_DIR` env seam: `ENV_FILE`, `SH_FILE`
|
|
- Provider discovery matching `bin/pos-ai` pattern (lines 16-18)
|
|
- All functions from architecture + UX spec:
|
|
- `_alias_load()` — read `.env` pipe-delimited records into parallel arrays
|
|
- `_alias_save()` — write `.env` with header comments, chmod 600
|
|
- `_alias_regen()` — generate `.sh` from `.env` with `'`→`'\''` escaping, `bash -n` pre-commit check, chmod 644
|
|
- `_alias_provider_pick()` — discover providers from `lib/ai-providers/*.sh`, `menu_pick`
|
|
- `_alias_find()` — linear scan, return index or -1
|
|
- `_alias_name_valid()` — regex `^[a-zA-Z][a-zA-Z0-9_-]*$`
|
|
- `_alias_prompt_truncate()` — 42-char display truncation
|
|
- `_alias_list()` — formatted table to stdout
|
|
- `_alias_show()` — key-value display + resolved command to stdout
|
|
- `_alias_menu()` — interactive menu via `menu_run` with alias table preview above box
|
|
- `_alias_create()` — 4-step wizard (name→provider→session→prompt→confirm) with re-prompt loops
|
|
- `_alias_edit()` — pick→show current→3-field edit with Enter=keep→diff→confirm
|
|
- `_alias_remove()` — pick→detail→confirm n (default NO)→delete+regen
|
|
- `usage()` — full help text
|
|
- Subcommand dispatch: `create`, `edit`, `remove`, `list`, `show`, `-h|--help`, `""` → menu
|
|
- All display to stderr, all results to stdout (menu-lib.sh contract)
|
|
- Input validation: name format, uniqueness, pipe-char in prompt, >500 char warning
|
|
|
|
---
|
|
|
|
## Step 2: Add `ai-alias` to `bin/pos` INTERACTIVE_CMDS [DONE]
|
|
|
|
Added `ai-alias` to the `INTERACTIVE_CMDS` space-separated list in `bin/pos` (line 262).
|
|
|
|
---
|
|
|
|
## Step 3: Add `.bashrc` source line to `postinstall.sh` [DONE]
|
|
|
|
Added conditional source block after the config template loop (line 52-57):
|
|
```bash
|
|
ALIAS_SRC_LINE='# AI aliases (managed by pos ai alias)
|
|
[ -f ~/.config/linux_post_install/ai-aliases.sh ] && source ~/.config/linux_post_install/ai-aliases.sh'
|
|
if ! grep -qsF "ai-aliases.sh" "$BASHRC" 2>/dev/null; then
|
|
run printf '%s\n' "$ALIAS_SRC_LINE" >> "$BASHRC"
|
|
log "Added AI aliases source to ~/.bashrc"
|
|
fi
|
|
```
|
|
No-clobber guard via `grep -qsF`.
|
|
|
|
---
|
|
|
|
## Step 4: Add DOC/POS.md section [DONE]
|
|
|
|
Added `#### ai alias` subsection under `### ai` in `DOC/POS.md` with command table and description.
|
|
|
|
---
|
|
|
|
## Step 5: Syntax check [DONE]
|
|
|
|
`bash -n bin/pos-ai-alias` — OK
|
|
`bash -n postinstall.sh` — OK
|
|
`bash -n bin/pos` — OK
|
|
|
|
---
|
|
|
|
## Step 6: Generate docs and run gates [DONE]
|
|
|
|
- `make gen` — OK (regenerated `DOC/AGENT_Context_Project.md` + `completions/pos.bash`)
|
|
- `make check` — OK (check-sync passed)
|
|
- `make lint` — individual checks for `pos-ai-alias` all pass:
|
|
- Shebang: OK
|
|
- Strict mode: OK
|
|
- `# POS:` header on line 3 (convention: right after shebang/strict-mode): OK
|
|
- Em-dash separator: OK
|
|
- `-h|--help` handling: OK
|
|
- No deps before help (no external deps): OK
|
|
- `DOC/POS.md` reference: OK
|
|
- Executable bit: OK
|
|
- `ai-alias` in INTERACTIVE_CMDS + matching `bin/pos-ai-alias`: OK
|
|
- No env-seam warnings (writes use `CONFIG_DIR` seam): OK
|
|
|
|
---
|
|
|
|
## Diff stats
|
|
|
|
```
|
|
bin/pos-ai-alias | 542 ++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
bin/pos | 2 +-
|
|
postinstall.sh | 8 ++++++
|
|
DOC/POS.md | 16 ++++++++++++
|
|
4 files changed, 568 insertions(+)
|
|
```
|
|
|
|
Plus `make gen` output:
|
|
```
|
|
DOC/AGENT_Context_Project.md | 31 ++++++++++-----------
|
|
completions/pos.bash | 3 ++-
|
|
```
|
|
|
|
---
|
|
|
|
REPORT_PATH: ./AgentsReport/builder/2026-08-26_ai-alias.md
|