1 -#
Notes Extension 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:** Build `extensions/notes`, a TUI-only Pi slash-command extension for session-backed pending prompt notes.
7 -**Architecture:** Keep the extension standalone in one focused `index.ts` with pure state/replay/render helpers and a thin Pi registration layer.
8 -Session persistence uses append-only `notes-state` custom entries, replayed from `ctx.sessionManager.getBranch()` on `session_start`.
9 -UI state is process memory only: compact vs expanded resets to compact on session start.
11 -**Tech Stack:** TypeScript, Pi extension API, `@earendil-works/pi-tui` key IDs, `@marcfargas/pi-test-harness`, Vitest, npm workspaces, mise tasks.
15 -**Phase:** Single-plan implementation
21 -- Create `extensions/notes/package.json`.
22 - Declares the standalone workspace package, Pi peer dependency, TUI peer dependency, harness dev dependency, and Vitest dev dependency.
23 -- Create `extensions/notes/index.ts`.
24 - Owns note state, session replay, command parsing, widget rendering, autocomplete, shortcut registration, and lifecycle hooks.
25 -- Create `extensions/notes/__tests__/harness.test.ts`.
26 - Loads the extension through the real Pi extension runtime and verifies command, persistence, widget, autocomplete, and send behavior.
27 -- Create `extensions/notes/README.md`.
28 - Documents commands, shortcut, persistence, and non-goals tersely.
29 -- Modify `README.md`.
30 - Adds `notes` to the root extension table.
31 -- Modify `package-lock.json`.
32 - Generated by `npm install` after adding the workspace package.
34 -##
Existing Patterns To Follow 36 -- Use `extensions/model-info/package.json` for package metadata shape.
37 -- Use `extensions/neko/index.ts` for `registerCommand()` plus `registerShortcut()` shape.
38 -- Use `extensions/goal/__tests__/harness.test.ts` for harness helpers around commands and UI calls.
39 -- Use `extensions/diff-review/__tests__/harness.test.ts` for manual `session_start` emission after appending custom session entries.
40 -- Use `mise run test -- extensions/notes/__tests__/harness.test.ts` for targeted tests.
41 -- Use `mise run lint` and `mise run test` before completion.
43 -##
Task 1: Package Skeleton And Runtime Registration 47 -- Create: `extensions/notes/package.json`
48 -- Create: `extensions/notes/index.ts`
49 -- Create: `extensions/notes/__tests__/harness.test.ts`
50 -- Create: `extensions/notes/README.md`
51 -- Modify: `README.md`
52 -- Modify: `package-lock.json`
54 -- [ ] **Step 1: Write the failing harness load test**
56 -Create `extensions/notes/__tests__/harness.test.ts` with this content:
59 -import { fileURLToPath }
from "node:url";
60 -import { afterEach, describe, expect, it }
from "vitest";
61 -import { createTestSession, type TestSession }
from "../../../test/harness";
63 -let t
: TestSession | undefined;
65 -function extensionPath()
: string {
66 - return fileURLToPath(
new URL(
"../index.ts",
import.
meta.url));
74 -describe(
"notes pi-test-harness", ()
=> {
75 - it(
"loads in real Pi extension runtime and registers command plus shortcut",
async ()
=> {
76 - t
= await createTestSession({ extensions: [
extensionPath()] });
77 - const [extension]
= t.session.extensionRunner.extensions;
79 - expect(extension.path).
toBe(
extensionPath());
80 - expect([
...extension.commands.
keys()]).
toEqual([
"note"]);
81 - expect([
...extension.tools.
keys()]).
toEqual([]);
82 - expect(extension.shortcuts.
has(
"alt+n")).
toBe(
true);
87 -- [ ] **Step 2: Run test to verify it fails**
92 -mise run test
-- extensions/notes/__tests__/harness.test.ts
95 -Expected: FAIL because `extensions/notes/index.ts` does not exist.
97 -- [ ] **Step 3: Add package skeleton**
99 -Create `extensions/notes/package.json` with this content:
103 - "name":
"@bugabinga/pi-ext-notes",
105 - "main":
"index.ts",
107 - "peerDependencies": {
108 - "@earendil-works/pi-coding-agent":
"*",
109 - "@earendil-works/pi-tui":
"*" 112 - "description":
"Session-backed pending prompt notes for Pi.",
117 - "devDependencies": {
118 - "@marcfargas/pi-test-harness":
"^0.6.1",
125 -Create `extensions/notes/index.ts` with this content:
128 -import type { ExtensionAPI }
from "@earendil-works/pi-coding-agent";
130 -export default function notesExtension(pi
: ExtensionAPI)
: void {
131 - pi.
registerCommand(
"note", {
132 - description:
"Park, inspect, edit, send, or clear pending prompt notes.",
133 - async handler(_args, ctx) {
134 - if (ctx.hasUI) ctx.ui.
notify(
"No pending notes",
"info");
138 - pi.
registerShortcut(
"alt+n", {
139 - description:
"Toggle notes widget",
140 - handler:
async (ctx)
=> {
141 - if (ctx.hasUI) ctx.ui.
notify(
"No pending notes",
"info");
147 -Create `extensions/notes/README.md` with this content:
152 -Session-backed pending prompt notes for Pi.
156 -Loaded through the root pi-ext package.
157 -See [root README](../../README.md).
159 -## Commands / tools / settings
163 -- `/note` — toggle the notes widget between compact and expanded mode.
164 -- `/note add <text>` — park a non-empty note.
165 -- `/note send <id>` — send one note as an exact user follow-up and remove it from pending notes.
166 -- `/note edit <id>` — edit one pending note.
167 -- `/note rm <id>` — remove one pending note.
168 -- `/note clear` — confirm and remove all pending notes.
172 -- `alt+n` — same as `/note`.
182 -Pending notes are persisted as `notes-state` custom session entries.
183 -Custom entries are invisible to the model context.
184 -Notes are branch-local because state is reconstructed from the current session branch.
185 -The widget is compact on reload or resume.
188 -- [ ] **Step 4: Add root README table row**
190 -Insert this row in `README.md` between `neko` and `nu-bang`:
193 -| `notes` | Session-backed pending prompt notes for Pi. | [README](extensions/notes/README.md) |
196 -- [ ] **Step 5: Update workspace lockfile**
204 -Expected: `package-lock.json` includes `extensions/notes` and package metadata for `@bugabinga/pi-ext-notes`.
206 -- [ ] **Step 6: Run test to verify it passes**
211 -mise run test
-- extensions/notes/__tests__/harness.test.ts
214 -Expected: PASS for the load test.
216 -- [ ] **Step 7: Commit**
221 -git add README.md package-lock.json extensions/notes/package.json extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts extensions/notes/README.md
222 -git commit -m
"feat(notes): add extension package skeleton" 225 -##
Task 2: State Replay Core 229 -- Modify: `extensions/notes/index.ts`
230 -- Modify: `extensions/notes/__tests__/harness.test.ts`
232 -- [ ] **Step 1: Add failing replay tests**
234 -Append these helpers below `extensionPath()` in `extensions/notes/__tests__/harness.test.ts`:
237 -function customEntries(kind
: string)
: Array<
Record<
string,
unknown>> {
239 - t?.session.sessionManager.
getEntries()
as Array<{
241 - customType
?: string;
242 - data
?: Record<
string,
unknown>;
245 - .
filter((entry)
=> entry.
type === "custom" && entry.customType
=== kind)
246 - .
map((entry)
=> entry.
data ?? {});
250 -Extend the import from `../index.ts` by changing no import yet.
251 -Add this import under the harness import:
254 -import { __test }
from "../index.ts";
257 -Append these tests inside the `describe()` block:
260 -it(
"replays add, edit, remove, and clear events in order", ()
=> {
261 - const state
= __test.
replayNotes([
264 - customType:
"notes-state",
265 - data: { op:
"add", id:
1, text:
"one", createdAt:
1 },
269 - customType:
"notes-state",
270 - data: { op:
"add", id:
2, text:
"two", createdAt:
2 },
274 - customType:
"notes-state",
275 - data: { op:
"edit", id:
2, text:
"two edited", updatedAt:
3 },
279 - customType:
"notes-state",
280 - data: { op:
"remove", id:
1, removedAt:
4 },
284 - customType:
"notes-state",
285 - data: { op:
"clear", clearedAt:
5 },
289 - customType:
"notes-state",
290 - data: { op:
"add", id:
3, text:
"three", createdAt:
6 },
294 - expect(__test.
pendingNotes(state)).
toEqual([{ id:
3, text:
"three" }]);
295 - expect(state.nextId).
toBe(
4);
298 -it(
"ignores malformed entries and invalid edits or removes", ()
=> {
299 - const state
= __test.
replayNotes([
302 - customType:
"notes-state",
303 - data: { op:
"edit", id:
9, text:
"missing", updatedAt:
1 },
307 - customType:
"notes-state",
308 - data: { op:
"remove", id:
9, removedAt:
2 },
312 - customType:
"other",
313 - data: { op:
"add", id:
1, text:
"wrong", createdAt:
3 },
317 - customType:
"notes-state",
318 - data: { op:
"add", id:
2, text:
"ok", createdAt:
4 },
322 - customType:
"notes-state",
323 - data: { op:
"add", id:
"bad", text:
"bad", createdAt:
5 },
327 - expect(__test.
pendingNotes(state)).
toEqual([{ id:
2, text:
"ok" }]);
328 - expect(state.nextId).
toBe(
3);
331 -it(
"appends notes-state entries through commands",
async ()
=> {
332 - t
= await createTestSession({ extensions: [
extensionPath()] });
333 - const command
= t.session.extensionRunner.extensions[
0].commands.
get(
"note");
334 - await command.
handler(
335 - "add remember parser tests",
336 - t.session.extensionRunner.
createCommandContext(),
339 - expect(
customEntries(
"notes-state")).
toEqual([
343 - text:
"remember parser tests",
344 - createdAt: expect.
any(
Number),
350 -- [ ] **Step 2: Run test to verify it fails**
355 -mise run test
-- extensions/notes/__tests__/harness.test.ts
358 -Expected: FAIL because `__test`, replay helpers, and `/note add` are missing.
360 -- [ ] **Step 3: Replace `index.ts` with state core plus add command**
362 -Replace `extensions/notes/index.ts` with this content:
368 -}
from "@earendil-works/pi-coding-agent";
370 -const ENTRY_TYPE
= "notes-state";
371 -const WIDGET_KEY
= "notes";
373 -type Note = { id
: number; text
: string };
375 - | { op
: "add"; id
: number; text
: string; createdAt
: number }
376 - | { op
: "edit"; id
: number; text
: string; updatedAt
: number }
377 - | { op
: "remove"; id
: number; removedAt
: number }
378 - | { op
: "clear"; clearedAt
: number };
380 -type SessionEntryLike = {
382 - customType
?: unknown;
387 - notes
: Map<
number,
Note>;
391 -function createState()
: NotesState {
392 - return { notes:
new Map(), nextId:
1 };
395 -function isPositiveInteger(value
: unknown)
: value
is number {
396 - return Number.
isInteger(value)
&& typeof value
=== "number" && value
> 0;
399 -function isNonEmptyText(value
: unknown)
: value
is string {
400 - return typeof value
=== "string" && value.
trim().
length > 0;
403 -function parseEvent(data
: unknown)
: NotesEvent | undefined {
404 - if (
!data
|| typeof data
!== "object")
return undefined;
405 - const event
= data
as Record<
string,
unknown>;
407 - event.op
=== "add" && isPositiveInteger(
event.
id)
408 - && isNonEmptyText(
event.
text)
&& typeof event.createdAt
=== "number" 413 - text:
event.
text.
trim(),
414 - createdAt:
event.createdAt,
418 - event.op
=== "edit" && isPositiveInteger(
event.
id)
419 - && isNonEmptyText(
event.
text)
&& typeof event.updatedAt
=== "number" 424 - text:
event.
text.
trim(),
425 - updatedAt:
event.updatedAt,
429 - event.op
=== "remove" && isPositiveInteger(
event.
id)
430 - && typeof event.removedAt
=== "number" 432 - return { op:
"remove", id:
event.
id, removedAt:
event.removedAt };
434 - if (
event.op
=== "clear" && typeof event.clearedAt
=== "number") {
435 - return { op:
"clear", clearedAt:
event.clearedAt };
440 -function applyEvent(state
: NotesState, event
: NotesEvent)
: void {
441 - if (
event.op
=== "add") {
442 - state.notes.
set(
event.
id, { id:
event.
id, text:
event.
text });
443 - state.nextId
= Math.
max(state.nextId,
event.
id + 1);
446 - if (
event.op
=== "edit") {
447 - const note
= state.notes.
get(
event.
id);
449 - state.notes.
set(
event.
id, { id:
event.
id, text:
event.
text });
450 - state.nextId
= Math.
max(state.nextId,
event.
id + 1);
453 - if (
event.op
=== "remove") {
454 - if (
!state.notes.
has(
event.
id))
return;
455 - state.notes.
delete(
event.
id);
456 - state.nextId
= Math.
max(state.nextId,
event.
id + 1);
459 - state.notes.
clear();
462 -function replayNotes(entries
: SessionEntryLike[])
: NotesState {
463 - const state
= createState();
464 - for (
const entry
of entries) {
465 - if (entry.
type !== "custom" || entry.customType
!== ENTRY_TYPE)
continue;
466 - const event
= parseEvent(entry.
data);
467 - if (
event)
applyEvent(state,
event);
472 -function pendingNotes(state
: NotesState)
: Note[] {
473 - return [
...state.notes.
values()].
sort((a, b)
=> a.
id - b.
id);
476 -function replaceState(target
: NotesState, source
: NotesState)
: void {
477 - target.notes
= source.notes;
478 - target.nextId
= source.nextId;
481 -function appendEvent(
486 - pi.
appendEntry(ENTRY_TYPE,
event);
487 - applyEvent(state,
event);
491 - ctx
: ExtensionContext,
493 - type
: "info" | "warning" | "error" = "info",
495 - if (ctx.hasUI) ctx.ui.
notify(message, type);
498 -export default function notesExtension(pi
: ExtensionAPI)
: void {
499 - const state
= createState();
500 - let expanded
= false;
502 - function refreshWidget(ctx
: ExtensionContext)
: void {
503 - if (
!ctx.hasUI)
return;
504 - if (state.notes.
size === 0) {
505 - ctx.ui.
setWidget(WIDGET_KEY,
undefined);
508 - ctx.ui.
setWidget(WIDGET_KEY, [
510 - ? ` notes · ${state.notes.size}` 511 - : ` ${state.notes.size} notes`,
515 - pi.
registerCommand(
"note", {
516 - description:
"Park, inspect, edit, send, or clear pending prompt notes.",
517 - async handler(args, ctx) {
518 - const trimmed
= args.
trim();
519 - if (trimmed.
startsWith(
"add ")) {
520 - const text
= trimmed.
slice(
4).
trim();
522 - notify(ctx,
"Note text required",
"warning");
525 - const wasEmpty
= state.notes.
size === 0;
526 - appendEvent(pi, state, {
530 - createdAt:
Date.
now(),
532 - if (wasEmpty) expanded
= false;
533 - refreshWidget(ctx);
538 - state.notes.
size === 0 539 - ? "No pending notes" 540 - : "Usage: /note [add|send|edit|rm|clear]",
543 - refreshWidget(ctx);
547 - pi.
registerShortcut(
"alt+n", {
548 - description:
"Toggle notes widget",
549 - handler:
async (ctx)
=> {
550 - notify(ctx,
"No pending notes",
"info");
554 - pi.
on(
"session_start",
async (_event, ctx)
=> {
557 - replayNotes(ctx.sessionManager.
getBranch()
as SessionEntryLike[]),
560 - refreshWidget(ctx);
564 -export const __test
= {
572 -- [ ] **Step 4: Run test to verify it passes**
577 -mise run test
-- extensions/notes/__tests__/harness.test.ts
582 -- [ ] **Step 5: Commit**
587 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
588 -git commit -m
"feat(notes): add session replay state" 591 -##
Task 3: Widget Rendering, Toggle, And Session Start Restore 595 -- Modify: `extensions/notes/index.ts`
596 -- Modify: `extensions/notes/__tests__/harness.test.ts`
598 -- [ ] **Step 1: Add failing widget and toggle tests**
600 -Append these helpers below `customEntries()`:
603 -function uiArgs(method
: string)
: unknown[][] {
604 - return t?.events.ui.
filter((call)
=> call.
method === method).
map((call)
=> 609 -function latestWidget()
: string[]
| undefined {
610 - return uiArgs(
"setWidget")
611 - .
filter((args)
=> args[
0]
=== "notes")
612 - .
map((args)
=> args[
1]
as string[]
| undefined)
616 -async function noteCommand(args
: string)
: Promise<
void> {
617 - const command
= t?.session.extensionRunner.extensions[
0].commands.
get(
"note");
618 - if (
!command
|| !t)
throw new Error(
"missing note command");
619 - await command.
handler(args, t.session.extensionRunner.
createCommandContext());
623 -Append these tests inside the `describe()` block:
626 -it(
"renders compact count and last note after add",
async ()
=> {
627 - t
= await createTestSession({ extensions: [
extensionPath()] });
628 - await noteCommand(
"add first note");
629 - await noteCommand(
"add second note");
631 - expect(
latestWidget()).
toEqual([
632 - " 2 notes · alt+n expand · last: second note",
636 -it(
"toggles expanded widget with slash command and shortcut",
async ()
=> {
637 - t
= await createTestSession({ extensions: [
extensionPath()] });
638 - await noteCommand(
"add first note");
639 - await noteCommand(
"add second note");
640 - await noteCommand(
"");
642 - expect(
latestWidget()).
toEqual([
648 - const shortcut
= t.session.extensionRunner.extensions[
0].shortcuts.
get(
651 - await shortcut.
handler(t.session.extensionRunner.
createCommandContext());
653 - expect(
latestWidget()).
toEqual([
654 - " 2 notes · alt+n expand · last: second note",
658 -it(
"shows compact widget on session_start when current branch has pending notes",
async ()
=> {
659 - t
= await createTestSession({ extensions: [
extensionPath()] });
660 - (t.session.sessionManager
as any).
appendCustomEntry(
"notes-state", {
663 - text:
"restored note",
667 - await t.session.extensionRunner.
emit({
668 - type:
"session_start",
672 - expect(
latestWidget()).
toEqual([
673 - " 1 notes · alt+n expand · last: restored note",
677 -it(
"leaves widget hidden and notifies when toggling with no notes",
async ()
=> {
678 - t
= await createTestSession({ extensions: [
extensionPath()] });
679 - await noteCommand(
"");
681 - expect(
uiArgs(
"notify").
at(
-1)).
toEqual([
"No pending notes",
"info"]);
682 - expect(
latestWidget()).
toBeUndefined();
686 -- [ ] **Step 2: Run test to verify it fails**
691 -mise run test
-- extensions/notes/__tests__/harness.test.ts
694 -Expected: FAIL because widget lines are not fully rendered and toggle does not change expanded state.
696 -- [ ] **Step 3: Add render helpers and real toggle behavior**
698 -In `extensions/notes/index.ts`, add these helpers above `export default`:
701 -function preview(text
: string, max
= 72)
: string {
702 - const oneLine
= text.
replace(
/[\x00-\x1F\x7F]+/g,
" ").
replace(
/ +/g,
" ")
704 - return oneLine.
length > max
705 - ? `${oneLine.slice(0, Math.max(0, max - 1))}…` 709 -function compactWidgetLine(state
: NotesState)
: string {
710 - const notes
= pendingNotes(state);
711 - const last
= notes.
at(
-1);
712 - return ` ${notes.length} notes · alt+n expand · last: ${ 713 - preview(last?.text ?? "") 717 -function expandedWidgetLines(state
: NotesState)
: string[] {
718 - const notes
= pendingNotes(state);
720 - ` notes · ${notes.length}`,
721 - ...notes.
map((note)
=> ` ${note.id} ${note.text}`),
725 -function widgetLines(
728 -)
: string[]
| undefined {
729 - if (state.notes.
size === 0)
return undefined;
730 - return expanded
? expandedWidgetLines(state)
: [
compactWidgetLine(state)];
734 -Replace `refreshWidget()` and add `toggleWidget()` inside `notesExtension()`:
737 -function refreshWidget(ctx
: ExtensionContext)
: void {
738 - if (
!ctx.hasUI)
return;
739 - ctx.ui.
setWidget(WIDGET_KEY,
widgetLines(state, expanded));
742 -function toggleWidget(ctx
: ExtensionContext)
: void {
743 - if (state.notes.
size === 0) {
744 - notify(ctx,
"No pending notes",
"info");
745 - refreshWidget(ctx);
748 - expanded
= !expanded;
749 - refreshWidget(ctx);
753 -Replace the default command fallback in the command handler with:
760 -notify(ctx,
"Usage: /note [add|send|edit|rm|clear]",
"warning");
764 -Replace the shortcut handler body with:
767 -handler:
async (ctx)
=> toggleWidget(ctx),
770 -- [ ] **Step 4: Export render helpers for tests**
772 -Extend `__test` at the bottom of `index.ts` to this exact object:
775 -export const __test
= {
778 - expandedWidgetLines,
787 -- [ ] **Step 5: Run test to verify it passes**
792 -mise run test
-- extensions/notes/__tests__/harness.test.ts
797 -- [ ] **Step 6: Commit**
802 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
803 -git commit -m
"feat(notes): render and toggle notes widget" 806 -##
Task 4: Remove, Clear, And Edit Commands 810 -- Modify: `extensions/notes/index.ts`
811 -- Modify: `extensions/notes/__tests__/harness.test.ts`
813 -- [ ] **Step 1: Add failing command mutation tests**
815 -Append these tests inside the `describe()` block:
818 -it(
"removes one note and clears widget when none remain",
async ()
=> {
819 - t
= await createTestSession({ extensions: [
extensionPath()] });
820 - await noteCommand(
"add first note");
821 - await noteCommand(
"rm 1");
823 - expect(
customEntries(
"notes-state").
at(
-1)).
toEqual({
826 - removedAt: expect.
any(
Number),
828 - expect(
latestWidget()).
toBeUndefined();
831 -it(
"confirms before clearing all pending notes",
async ()
=> {
832 - t
= await createTestSession({
833 - extensions: [
extensionPath()],
834 - mockUI: { confirm:
true },
836 - await noteCommand(
"add first note");
837 - await noteCommand(
"add second note");
838 - await noteCommand(
"clear");
840 - expect(
uiArgs(
"confirm").
at(
-1)).
toEqual([
842 - "Remove 2 pending notes?",
844 - expect(
customEntries(
"notes-state").
at(
-1)).
toEqual({
846 - clearedAt: expect.
any(
Number),
848 - expect(
latestWidget()).
toBeUndefined();
851 -it(
"keeps notes when clear confirmation is rejected",
async ()
=> {
852 - t
= await createTestSession({
853 - extensions: [
extensionPath()],
854 - mockUI: { confirm:
false },
856 - await noteCommand(
"add first note");
857 - await noteCommand(
"clear");
859 - expect(
customEntries(
"notes-state")).
toHaveLength(
1);
860 - expect(
latestWidget()).
toEqual([
861 - " 1 notes · alt+n expand · last: first note",
865 -it(
"edits note text and keeps old text on cancel or whitespace save",
async ()
=> {
866 - t
= await createTestSession({
867 - extensions: [
extensionPath()],
868 - mockUI: { editor:
"edited note" },
870 - await noteCommand(
"add old note");
871 - await noteCommand(
"edit 1");
873 - expect(
uiArgs(
"editor").
at(
-1)).
toEqual([
"Edit note 1",
"old note"]);
874 - expect(
customEntries(
"notes-state").
at(
-1)).
toEqual({
877 - text:
"edited note",
878 - updatedAt: expect.
any(
Number),
880 - expect(
latestWidget()).
toEqual([
881 - " 1 notes · alt+n expand · last: edited note",
885 - t
= await createTestSession({
886 - extensions: [
extensionPath()],
887 - mockUI: {
editor: ()
=> undefined },
889 - await noteCommand(
"add stable note");
890 - await noteCommand(
"edit 1");
891 - expect(
customEntries(
"notes-state")).
toHaveLength(
1);
894 - t
= await createTestSession({
895 - extensions: [
extensionPath()],
896 - mockUI: { editor:
" " },
898 - await noteCommand(
"add stable note");
899 - await noteCommand(
"edit 1");
900 - expect(
customEntries(
"notes-state")).
toHaveLength(
1);
901 - expect(
uiArgs(
"notify").
at(
-1)).
toEqual([
"Note text required",
"warning"]);
904 -it(
"unknown ids do not mutate state",
async ()
=> {
905 - t
= await createTestSession({ extensions: [
extensionPath()] });
906 - await noteCommand(
"add first note");
907 - await noteCommand(
"rm 99");
908 - await noteCommand(
"edit 99");
910 - expect(
customEntries(
"notes-state")).
toHaveLength(
1);
911 - expect(
uiArgs(
"notify").
at(
-1)).
toEqual([
"Unknown note id: 99",
"error"]);
915 -- [ ] **Step 2: Run test to verify it fails**
920 -mise run test
-- extensions/notes/__tests__/harness.test.ts
923 -Expected: FAIL because `rm`, `clear`, and `edit` are not implemented.
925 -- [ ] **Step 3: Add command parsing helpers**
927 -Add these helpers above `export default` in `extensions/notes/index.ts`:
930 -function splitCommand(args
: string)
: { command
: string; rest
: string } {
931 - const trimmed
= args.
trim();
932 - const space
= trimmed.
indexOf(
" ");
933 - if (space
=== -1)
return { command: trimmed, rest:
"" };
935 - command: trimmed.
slice(
0, space),
936 - rest: trimmed.
slice(space
+ 1).
trim(),
940 -function parseId(text
: string)
: number | undefined {
941 - const value
= Number(text.
trim());
942 - return isPositiveInteger(value)
? value
: undefined;
945 -function requireNote(
946 - ctx
: ExtensionContext,
949 -)
: Note | undefined {
950 - const id
= parseId(idText);
951 - if (
!id
|| !state.notes.
has(id)) {
952 - notify(ctx,
`Unknown note id: ${idText.trim() || "?"}`,
"error");
955 - return state.notes.
get(id);
959 -- [ ] **Step 4: Replace command handler branch body**
961 -Inside the `handler(args, ctx)` function, replace the current body with this code:
964 -const trimmed
= args.
trim();
965 -const { command, rest }
= splitCommand(trimmed);
972 -if (command
=== "add") {
973 - const text
= rest.
trim();
975 - notify(ctx,
"Note text required",
"warning");
978 - const wasEmpty
= state.notes.
size === 0;
979 - appendEvent(pi, state, {
983 - createdAt:
Date.
now(),
985 - if (wasEmpty) expanded
= false;
986 - refreshWidget(ctx);
990 -if (command
=== "rm") {
991 - const note
= requireNote(ctx, state, rest);
993 - appendEvent(pi, state, { op:
"remove", id: note.
id, removedAt:
Date.
now() });
994 - refreshWidget(ctx);
998 -if (command
=== "clear") {
999 - if (state.notes.
size === 0) {
1000 - notify(ctx,
"No pending notes",
"info");
1001 - refreshWidget(ctx);
1004 - const confirmed
= await ctx.ui.
confirm(
1006 - `Remove ${state.notes.size} pending notes?`,
1008 - if (
!confirmed)
return;
1009 - appendEvent(pi, state, { op:
"clear", clearedAt:
Date.
now() });
1010 - refreshWidget(ctx);
1014 -if (command
=== "edit") {
1015 - const note
= requireNote(ctx, state, rest);
1016 - if (
!note)
return;
1017 - const edited
= await ctx.ui.
editor(
`Edit note ${note.id}`, note.
text);
1018 - if (edited
=== undefined)
return;
1019 - const text
= edited.
trim();
1021 - notify(ctx,
"Note text required",
"warning");
1024 - appendEvent(pi, state, {
1028 - updatedAt:
Date.
now(),
1030 - refreshWidget(ctx);
1034 -notify(ctx,
"Usage: /note [add|send|edit|rm|clear]",
"warning");
1035 -refreshWidget(ctx);
1038 -- [ ] **Step 5: Run test to verify it passes**
1043 -mise run test
-- extensions/notes/__tests__/harness.test.ts
1048 -- [ ] **Step 6: Commit**
1053 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
1054 -git commit -m
"feat(notes): add edit remove and clear commands" 1057 -##
Task 5: Send Command And Autocomplete 1061 -- Modify: `extensions/notes/index.ts`
1062 -- Modify: `extensions/notes/__tests__/harness.test.ts`
1064 -- [ ] **Step 1: Add failing send and autocomplete tests**
1066 -Append these tests inside the `describe()` block:
1069 -it(
"sends exact note text when idle and removes it",
async ()
=> {
1070 - t
= await createTestSession({ extensions: [
extensionPath()] });
1071 - const sent
: Array<{ content
: unknown; options
: unknown }>
= [];
1072 - t.session.extensionRunner.runtime.
sendUserMessage = (
1075 - )
=> sent.
push({ content, options });
1077 - await noteCommand(
"add exact text");
1078 - await noteCommand(
"send 1");
1080 - expect(sent).
toEqual([{ content:
"exact text", options:
undefined }]);
1081 - expect(
customEntries(
"notes-state").
at(
-1)).
toEqual({
1084 - removedAt: expect.
any(
Number),
1086 - expect(
latestWidget()).
toBeUndefined();
1089 -it(
"queues send as follow-up when busy",
async ()
=> {
1090 - t
= await createTestSession({ extensions: [
extensionPath()] });
1091 - const sent
: Array<{ content
: unknown; options
: unknown }>
= [];
1092 - t.session.extensionRunner.runtime.
sendUserMessage = (
1095 - )
=> sent.
push({ content, options });
1097 - await noteCommand(
"add busy text");
1098 - const command
= t.session.extensionRunner.extensions[
0].commands.
get(
"note");
1099 - const ctx
= t.session.extensionRunner.
createCommandContext();
1100 - ctx.
isIdle = ()
=> false;
1101 - await command.
handler(
"send 1", ctx);
1103 - expect(sent).
toEqual([{
1104 - content:
"busy text",
1105 - options: { deliverAs:
"followUp" },
1107 - expect(
customEntries(
"notes-state").
at(
-1)).
toEqual({
1110 - removedAt: expect.
any(
Number),
1114 -it(
"unknown send id does not send or mutate",
async ()
=> {
1115 - t
= await createTestSession({ extensions: [
extensionPath()] });
1116 - const sent
: Array<{ content
: unknown; options
: unknown }>
= [];
1117 - t.session.extensionRunner.runtime.
sendUserMessage = (
1120 - )
=> sent.
push({ content, options });
1121 - await noteCommand(
"add stable text");
1122 - await noteCommand(
"send 99");
1124 - expect(sent).
toEqual([]);
1125 - expect(
customEntries(
"notes-state")).
toHaveLength(
1);
1126 - expect(
uiArgs(
"notify").
at(
-1)).
toEqual([
"Unknown note id: 99",
"error"]);
1129 -it(
"autocompletes subcommands and pending note ids with previews",
async ()
=> {
1130 - t
= await createTestSession({ extensions: [
extensionPath()] });
1131 - const command
= t.session.extensionRunner.extensions[
0].commands.
get(
"note");
1132 - await noteCommand(
"add consider split parser tests");
1133 - await noteCommand(
"add ask whether command should support autocomplete");
1135 - expect(command.
getArgumentCompletions(
"")).
toEqual([
1136 - { value:
"add", label:
"add" },
1137 - { value:
"send", label:
"send" },
1138 - { value:
"edit", label:
"edit" },
1139 - { value:
"rm", label:
"rm" },
1140 - { value:
"clear", label:
"clear" },
1142 - expect(command.
getArgumentCompletions(
"send ")).
toEqual([
1143 - { value:
"send 1", label:
"1 consider split parser tests" },
1146 - label:
"2 ask whether command should support autocomplete",
1149 - expect(command.
getArgumentCompletions(
"edit 2")).
toEqual([
1152 - label:
"2 ask whether command should support autocomplete",
1155 - expect(command.
getArgumentCompletions(
"rm ")).
toEqual([
1156 - { value:
"rm 1", label:
"1 consider split parser tests" },
1159 - label:
"2 ask whether command should support autocomplete",
1165 -- [ ] **Step 2: Run test to verify it fails**
1170 -mise run test
-- extensions/notes/__tests__/harness.test.ts
1173 -Expected: FAIL because send and autocomplete are not implemented.
1175 -- [ ] **Step 3: Add autocomplete helpers**
1177 -Add this import at the top of `extensions/notes/index.ts`:
1180 -import type { AutocompleteItem }
from "@earendil-works/pi-tui";
1183 -Add these helpers above `export default`:
1186 -const SUBCOMMANDS
= [
"add",
"send",
"edit",
"rm",
"clear"]
as const;
1188 -function argumentCompletions(
1189 - state
: NotesState,
1190 - argumentPrefix
: string,
1191 -)
: AutocompleteItem[] {
1192 - const { command, rest }
= splitCommand(argumentPrefix);
1193 - if (
!argumentPrefix.
includes(
" ")) {
1194 - return SUBCOMMANDS.
filter((item)
=> item.
startsWith(command)).
map((
1196 - )
=> ({ value: item, label: item }));
1198 - if (command
!== "send" && command
!== "edit" && command
!== "rm")
return [];
1199 - return pendingNotes(state)
1200 - .
filter((note)
=> String(note.
id).
startsWith(rest))
1202 - value:
`${command} ${note.id}`,
1203 - label:
`${note.id} ${preview(note.text)}`,
1208 -- [ ] **Step 4: Add send command branch**
1210 -Insert this branch in the command handler after the `edit` branch and before the usage fallback:
1213 -if (command
=== "send") {
1214 - const note
= requireNote(ctx, state, rest);
1215 - if (
!note)
return;
1216 - if (ctx.
isIdle()) pi.
sendUserMessage(note.
text);
1217 - else pi.
sendUserMessage(note.
text, { deliverAs:
"followUp" });
1218 - appendEvent(pi, state, { op:
"remove", id: note.
id, removedAt:
Date.
now() });
1219 - refreshWidget(ctx);
1224 -- [ ] **Step 5: Wire autocomplete into command registration**
1226 -Add this property to the `pi.registerCommand("note", { ... })` object before `handler`:
1229 -getArgumentCompletions: (argumentPrefix)
=> argumentCompletions(state, argumentPrefix),
1232 -Extend `__test` with `argumentCompletions`:
1235 -export const __test
= {
1237 - argumentCompletions,
1238 - compactWidgetLine,
1239 - expandedWidgetLines,
1248 -- [ ] **Step 6: Run test to verify it passes**
1253 -mise run test
-- extensions/notes/__tests__/harness.test.ts
1258 -- [ ] **Step 7: Commit**
1263 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
1264 -git commit -m
"feat(notes): send notes and autocomplete ids" 1267 -##
Task 6: Branch-Local Replay Coverage And Final Docs Polish 1271 -- Modify: `extensions/notes/__tests__/harness.test.ts`
1272 -- Modify: `extensions/notes/README.md`
1274 -- [ ] **Step 1: Add branch-local replay assertion**
1276 -Append this test inside the `describe()` block:
1279 -it(
"replay uses only entries returned by the current branch", ()
=> {
1280 - const state
= __test.
replayNotes([
1283 - customType:
"notes-state",
1284 - data: { op:
"add", id:
2, text:
"current branch", createdAt:
1 },
1288 - expect(__test.
pendingNotes(state)).
toEqual([{
1290 - text:
"current branch",
1292 - expect(state.nextId).
toBe(
3);
1296 -- [ ] **Step 2: Run test to verify it passes**
1301 -mise run test
-- extensions/notes/__tests__/harness.test.ts
1306 -- [ ] **Step 3: Polish README with explicit invisibility and scope**
1308 -Replace the `## Behavior` section in `extensions/notes/README.md` with:
1313 -Pending notes are persisted as `notes-state` custom session entries.
1314 -Custom entries are invisible to the model context.
1315 -Notes are branch-local because state is reconstructed from the current session branch.
1316 -The widget is compact on reload or resume.
1318 -No project-global storage exists.
1319 -No cross-session note list exists.
1320 -No system-prompt or model-context injection exists.
1321 -No steer mode exists.
1324 -- [ ] **Step 4: Run focused tests**
1329 -mise run test
-- extensions/notes/__tests__/harness.test.ts
1334 -- [ ] **Step 5: Commit**
1339 -git add extensions/notes/__tests__/harness.test.ts extensions/notes/README.md
1340 -git commit -m
"test(notes): cover branch-local replay" 1343 -##
Task 7: Repository Verification 1349 -- [ ] **Step 1: Run formatter**
1357 -Expected: command exits 0.
1358 -Expected changed files are formatting-only in files touched by this plan.
1360 -- [ ] **Step 2: Run lint**
1368 -Expected: command exits 0.
1370 -- [ ] **Step 3: Run targeted test**
1375 -mise run test
-- extensions/notes/__tests__/harness.test.ts
1378 -Expected: command exits 0.
1380 -- [ ] **Step 4: Run full test suite**
1388 -Expected: command exits 0.
1390 -- [ ] **Step 5: Run static extension checks**
1398 -Expected: command exits 0.
1400 -- [ ] **Step 6: Inspect final diff**
1405 -git diff --stat HEAD
1408 -Expected: diff includes only:
1413 -extensions/notes/package.json
1414 -extensions/notes/index.ts
1415 -extensions/notes/__tests__/harness.test.ts
1416 -extensions/notes/README.md
1419 -- [ ] **Step 7: Final commit if formatting changed files after last commit**
1421 -If Step 1 changed files after Task 6 commit, run:
1424 -git add README.md package-lock.json extensions/notes/package.json extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts extensions/notes/README.md
1425 -git commit -m
"chore(notes): format extension" 1428 -Expected: commit succeeds only when there are formatting changes.
1430 -##
Spec Coverage Checklist 1432 -- Standalone package at `extensions/notes`: Task 1.
1433 -- One slash command namespace: Tasks 1, 2, 4, 5.
1434 -- Keyboard shortcut `alt+n`: Tasks 1 and 3.
1435 -- Compact and expanded widget: Task 3.
1436 -- Session-backed append-only persistence: Task 2.
1437 -- Autocomplete: Task 5.
1438 -- Tests through real Pi extension runtime: all test tasks.
1439 -- Terse README: Tasks 1 and 6.
1440 -- No state outside Pi session: implementation keeps only derived in-memory state and appends session entries.
1441 -- No prompt/model injection: implementation uses no `before_agent_start`, `custom_message`, or system prompt APIs.
1442 -- No project-global or cross-session notes: implementation writes no project files.
1443 -- Reload/resume/compaction reconstruction: Task 2 replay and Task 3 `session_start` restore.
1444 -- Branch-local replay: Task 6.
1445 -- Unknown ID errors: Task 4 and Task 5.
1446 -- Send exact text as user follow-up when busy: Task 5.
1447 -- Edit cancel and whitespace save behavior: Task 4.