repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: plan shame command implementation

9185b21c9dfdd92e471dfac76f986b6323419c73

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/plans/2026-07-11-shame-command.md

Added
new file mode 100644
1 +# Shame Command Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Rename `/review` to `/shame` and replace typed targets with inferred targets, `@` paths, and argument completion.
7 +**Architecture:** Keep the extension in one implementation file. Parse flags and tokens first, then resolve tokens asynchronously against the filesystem, GitHub PR syntax, and Git refs in that order; keep completion synchronous and side-effect-free using Node filesystem APIs plus a bounded Git ref query.
9 +**Tech Stack:** TypeScript, Node 26 standard library, Pi extension API, Vitest, Pi test harness
11 +**Roadmap:** None
13 +**Phase:** Single-plan implementation
15 +---
17 +### Task 1: Rename the extension
19 +**Files:**
21 +- Rename: `extensions/review/` → `extensions/shame/`
22 +- Modify: `extensions/shame/package.json`
23 +- Modify: `extensions/shame/index.ts`
24 +- Modify: `extensions/shame/__tests__/harness.test.ts`
25 +- Modify: `README.md`
26 +- Modify: `CHANGELOG.md`
27 +- Modify: `package-lock.json`
29 +- [ ] **Step 1: Rename the directory and package**
31 +Run:
33 +```bash
34 +mv extensions/review extensions/shame
35 +```
37 +Change the package name in `extensions/shame/package.json`:
39 +```json
40 +"name": "@bugabinga/pi-ext-shame"
41 +```
43 +Rename the exported extension function and command registration in `extensions/shame/index.ts`:
45 +```ts
46 +export default function shameExtension(pi: ExtensionAPI) {
47 + pi.registerCommand("shame", {
48 + description:
49 + "Shame code. Usage: /shame [@path ...|#pr|pr-url|git-ref] [--extra <focus>]",
50 +```
52 +- [ ] **Step 2: Rename test imports and the load test**
54 +Use these names in `extensions/shame/__tests__/harness.test.ts`:
56 +```ts
57 +import shameExtension, { __test } from "../index";
59 +describe("shame extension", () => {
60 + it("loads in real Pi extension runtime", async () => {
61 + t = await createTestSession({ extensionFactories: [shameExtension] });
62 + expect(t.session.extensionRunner.extensions).toHaveLength(1);
63 + });
64 +});
65 +```
67 +- [ ] **Step 3: Update repository metadata**
69 +Replace the root README row with:
71 +```markdown
72 +| `shame` | Hostile agent code review for Pi. | [README](extensions/shame/README.md) |
73 +```
75 +Replace the review changelog entry with one sentence describing `/shame`, inferred targets, `@` paths, and completion.
76 +Update `extensions/shame/README.md` to show only the approved interface from `docs/super/specs/2026-07-11-shame-command-design.md`.
77 +Regenerate workspace lock entries:
79 +```bash
80 +npm install --package-lock-only --ignore-scripts
81 +```
83 +Expected: `package-lock.json` contains `extensions/shame` and `@bugabinga/pi-ext-shame`, with no review workspace entry.
85 +- [ ] **Step 4: Run the renamed harness test**
87 +Run:
89 +```bash
90 +mise run test -- extensions/shame/__tests__/harness.test.ts
91 +```
93 +Expected: all existing parser and extension-load assertions pass, and no import path references `extensions/review`.
95 +- [ ] **Step 5: Commit the rename**
97 +```bash
98 +git add CHANGELOG.md README.md package-lock.json extensions/review extensions/shame
99 +git commit -m "refactor(shame): rename review extension"
100 +```
102 +### Task 2: Infer review targets
104 +**Files:**
106 +- Modify: `extensions/shame/index.ts`
107 +- Modify: `extensions/shame/__tests__/harness.test.ts`
109 +- [ ] **Step 1: Replace parser tests with failing inferred-target tests**
111 +Expose `parseInput` and `resolveTarget` through `__test`.
112 +Add tests using a temporary Git repository created inside the harness cwd:
114 +```ts
115 +it("parses @ paths and extra focus", () => {
116 + expect(__test.parseInput('@src @test --extra "focus auth"')).toEqual({
117 + tokens: ["@src", "@test"],
118 + extra: "focus auth",
119 + });
120 +});
122 +it("recognizes PR shorthand and URLs", () => {
123 + expect(__test.pullRequestRef("#123")).toBe("123");
124 + expect(
125 + __test.pullRequestRef("https://github.com/acme/app/pull/42"),
126 + ).toBe("https://github.com/acme/app/pull/42");
127 +});
128 +```
130 +Add async resolver assertions for `@src`, multiple paths, a plain existing path, a local branch, a commit SHA, a missing path, and mixed path/ref tokens.
131 +Use `pi.exec("git", ["init", "-b", "trunk"])`, configure a local test identity, create one commit, and create branch `feature`.
133 +- [ ] **Step 2: Run tests to verify failure**
135 +Run:
137 +```bash
138 +mise run test -- extensions/shame/__tests__/harness.test.ts
139 +```
141 +Expected: FAIL because `parseInput`, `pullRequestRef`, and `resolveTarget` do not exist.
143 +- [ ] **Step 3: Implement flag parsing and target resolution**
145 +Replace `ParsedReviewArgs` with:
147 +```ts
148 +type ParsedInput = {
149 + tokens: string[];
150 + extra?: string;
151 + error?: string;
153 +```
155 +Implement these functions in `extensions/shame/index.ts`:
157 +```ts
158 +function parseInput(input: string): ParsedInput;
159 +function pullRequestRef(token: string): string | null;
160 +async function resolveTarget(
161 + pi: ExtensionAPI,
162 + cwd: string,
163 + tokens: string[],
164 +): Promise<{ target?: ReviewTarget; error?: string }>;
165 +```
167 +`parseInput` retains the existing quote-aware tokenizer and removes `--extra`/`-e` plus its value.
168 +`pullRequestRef` accepts `#` followed only by digits and `https://github.com/<owner>/<repo>/pull/<number>` URLs.
169 +`resolveTarget` performs exactly this sequence:
171 +1. Empty tokens return `smartTarget(pi)`.
172 +2. Strip one leading `@`; if any original token starts with `@` or any resulting token exists under `cwd`, require every token to exist and return one folder target containing normalized repo-relative paths.
173 +3. One PR token returns a PR target.
174 +4. One token matching `refs/heads/<token>` or `refs/remotes/<token>` through `git show-ref --verify` returns a branch target.
175 +5. One token accepted by `git rev-parse --verify <token>^{commit}` returns a commit target.
176 +6. Multiple non-path tokens return `Cannot mix paths and Git refs in one review`.
177 +7. One unresolved token returns `Cannot resolve "<token>". Try /shame @<path>, #123, a PR URL, branch, or commit`.
179 +Add an `execOk` helper that checks `pi.exec(...).code === 0`; do not parse localized Git stderr.
180 +Paths outside `cwd` after `path.resolve` must be rejected.
182 +Update the command handler:
184 +```ts
185 +const parsed = parseInput(args);
186 +if (parsed.error) return ctx.ui.notify(parsed.error, "error");
187 +const resolved = await resolveTarget(pi, ctx.cwd, parsed.tokens);
188 +if (!resolved.target) {
189 + ctx.ui.notify(resolved.error ?? "Cannot resolve review target", "error");
190 + return;
192 +const target = resolved.target;
193 +```
195 +Keep prompt generation unchanged except `/review` wording becomes `/shame` where user-visible.
197 +- [ ] **Step 4: Run resolver tests**
199 +Run:
201 +```bash
202 +mise run test -- extensions/shame/__tests__/harness.test.ts
203 +```
205 +Expected: all inferred-target and existing prompt/load tests pass.
207 +- [ ] **Step 5: Commit inference**
209 +```bash
210 +git add extensions/shame/index.ts extensions/shame/__tests__/harness.test.ts
211 +git commit -m "feat(shame): infer review targets"
212 +```
214 +### Task 3: Add argument completion
216 +**Files:**
218 +- Modify: `extensions/shame/index.ts`
219 +- Modify: `extensions/shame/__tests__/harness.test.ts`
221 +- [ ] **Step 1: Add failing completion tests**
223 +Create `src/`, `src/nested/`, and a local `feature` branch in the harness cwd.
224 +Fetch the command from the loaded extension and assert:
226 +```ts
227 +const command = t.session.extensionRunner.extensions[0].commands.get("shame");
228 +expect(command.getArgumentCompletions("@sr")).toContainEqual({
229 + value: "@src/",
230 + label: "@src/",
231 +});
232 +expect(command.getArgumentCompletions("@src/ @te")).toContainEqual({
233 + value: "@src/ @test/",
234 + label: "@test/",
235 +});
236 +expect(command.getArgumentCompletions("fea")).toContainEqual({
237 + value: "feature",
238 + label: "feature",
239 +});
240 +```
242 +Also assert suggestions for empty input include `--extra` and `#123` examples.
244 +- [ ] **Step 2: Run tests to verify failure**
246 +Run:
248 +```bash
249 +mise run test -- extensions/shame/__tests__/harness.test.ts
250 +```
252 +Expected: FAIL because `/shame` has no `getArgumentCompletions`.
254 +- [ ] **Step 3: Implement completion**
256 +Track the active cwd from `session_start` and initialize it to `process.cwd()`.
257 +Add `completeArguments(cwd, argumentText)` using `readdirSync(..., { withFileTypes: true })` for the active `@` token and `execFileSync("git", ["for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes"], { cwd, encoding: "utf8" })` for branch names.
258 +Catch filesystem/Git failures and return only applicable static suggestions.
259 +Filter control characters from values and labels.
260 +Preserve the prefix before the active whitespace-delimited token because Pi replaces the full argument string.
261 +Append `/` to directories.
262 +Register it as:
264 +```ts
265 +getArgumentCompletions(argumentText) {
266 + return completeArguments(cwd, argumentText);
268 +```
270 +Do not walk the repository recursively; list only the active directory.
272 +- [ ] **Step 4: Run focused tests and formatting**
274 +Run:
276 +```bash
277 +mise run test -- extensions/shame/__tests__/harness.test.ts
278 +mise run fmt
279 +mise run test -- extensions/shame/__tests__/harness.test.ts
280 +```
282 +Expected: all commands exit 0 and formatting leaves the focused test green.
284 +- [ ] **Step 5: Commit completion**
286 +```bash
287 +git add extensions/shame/index.ts extensions/shame/__tests__/harness.test.ts
288 +git commit -m "feat(shame): complete paths and branches"
289 +```
291 +### Task 4: Verify release readiness
293 +**Files:**
295 +- Verify: all modified files
297 +- [ ] **Step 1: Search for stale names**
299 +Run:
301 +```bash
302 +rg -n 'extensions/review|pi-ext-review|/review|`review` extension' . --glob '!docs/super/specs/**' --glob '!docs/super/plans/**'
303 +```
305 +Expected: no stale extension or command references.
307 +- [ ] **Step 2: Run the release gate**
309 +Run:
311 +```bash
312 +mise run ci
313 +```
315 +Expected: lint, all tests, and static extension checks pass.
317 +- [ ] **Step 3: Inspect final state**
319 +Run:
321 +```bash
322 +git status --short --branch
323 +git log -4 --oneline
324 +```
326 +Expected: clean worktree with the rename, inference, and completion commits above the design/plan commits.