@indexyz/pi-todo 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,8 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Add a repository-owned todo extension with compact backward-compatible session persistence.
8
+ - Fix the package file manifest for the first release.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 juicesharp
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,82 @@
1
- # Temporary Holding Version
1
+ # @indexyz/pi-todo
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A repository-owned fork of [`@juicesharp/rpiv-todo` 2.15.0](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo), verified with Pi 1.5.0. It adds a `todo` tool, a
4
+ `/todos` command, and a live task panel above the editor. Task state survives
5
+ `/reload`, compaction, and detached sessions, while new session records store
6
+ compact action records instead of repeating the complete task list on every
7
+ call.
8
+
9
+ The runtime identities from the upstream extension are intentionally preserved:
10
+ `todo`, `/todos`, the `rpiv-todo-state` session entry, and the `rpiv-todos`
11
+ widget key. Existing sessions can therefore be replayed by the fork.
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ pi install npm:@indexyz/pi-todo
17
+ ```
18
+
19
+ Releases are published to npm as `@indexyz/pi-todo`; each release is tagged
20
+ `@indexyz/pi-todo@<version>`.
21
+
22
+ To try the repository checkout for one session (after `npm install` at the
23
+ repository root):
24
+
25
+ ```bash
26
+ pi -e ./pi-todo/index.ts
27
+ ```
28
+
29
+ ## Usage
30
+
31
+ - Ask the agent to track multi-step work; it can call the `todo` tool with
32
+ `create`, `update`, `list`, `get`, `delete`, and `clear` actions.
33
+ - Run `/todos` in an interactive session to display all current tasks grouped by
34
+ status.
35
+ - Press `ctrl+shift+t` to collapse or expand the live panel. Configure this key
36
+ with `collapseKey` or set it to `off`.
37
+
38
+ The task model supports statuses, descriptions, active forms, owners,
39
+ `blockedBy` dependencies, metadata, batch creation, and session-scoped task
40
+ state. The overlay hides completed rows after the current turn and truncates
41
+ large lists according to its configured row budget.
42
+
43
+ ### Configuration
44
+
45
+ The extension reads the existing `rpiv-todo` configuration location:
46
+
47
+ ```text
48
+ $XDG_CONFIG_HOME/rpiv-todo/config.json
49
+ ~/.config/rpiv-todo/config.json
50
+ ```
51
+
52
+ Example:
53
+
54
+ ```json
55
+ {
56
+ "maxWidgetLines": 8,
57
+ "collapseKey": "alt+t"
58
+ }
59
+ ```
60
+
61
+ The optional `guidance` field replaces the built-in model instructions. The
62
+ optional peer `@juicesharp/rpiv-i18n` enables localized UI strings; without it,
63
+ English fallbacks are used.
64
+
65
+ ### Session persistence
66
+
67
+ New tool results and `rpiv-todo-state` custom entries serialize the action and
68
+ parameters needed for replay, not the cumulative `tasks` and `nextId` snapshot.
69
+ This applies to both direct calls and nested `ctx.executeTool` calls. Legacy
70
+ sessions containing full snapshots remain readable and do not need migration.
71
+
72
+ ## Development
73
+
74
+ ```bash
75
+ npm install
76
+ npm run check --workspace @indexyz/pi-todo
77
+ npm run test:e2e -- --package @indexyz/pi-todo
78
+ ```
79
+
80
+ ## License
81
+
82
+ MIT
package/config.ts ADDED
@@ -0,0 +1,141 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { isAbsolute, join } from "node:path";
4
+
5
+ interface TodoConfig {
6
+ guidance?: GuidanceFields;
7
+ maxWidgetLines?: number;
8
+ /**
9
+ * Key spec for the overlay collapse/expand shortcut, in the same format as
10
+ * pi-coding-agent keybinding ids (`modifier+key`, e.g. `ctrl+shift+t`, `alt+o`).
11
+ * Defaults to `"ctrl+shift+t"`. Pass `"off"` to disable the collapse shortcut.
12
+ */
13
+ collapseKey?: string;
14
+ }
15
+
16
+ export interface GuidanceFields {
17
+ promptSnippet?: string;
18
+ promptGuidelines?: string[];
19
+ description?: string;
20
+ }
21
+
22
+ /** Default content-row budget when the config is missing or invalid. */
23
+ export const DEFAULT_MAX_WIDGET_LINES = 12;
24
+
25
+ /** Key spec for the collapse/expand shortcut. */
26
+ export type CollapseKeySpec = string;
27
+
28
+ /** Default collapse/expand key when the config value is missing or invalid. */
29
+ export const DEFAULT_COLLAPSE_KEY: CollapseKeySpec = "ctrl+shift+t";
30
+
31
+ /** Sentinel value for `collapseKey` that disables the shortcut. */
32
+ export const COLLAPSE_KEY_OFF: CollapseKeySpec = "off";
33
+
34
+ function expandTilde(path: string): string {
35
+ if (path === "~") return homedir();
36
+ if (path.startsWith("~/")) return join(homedir(), path.slice(2));
37
+ return path;
38
+ }
39
+
40
+ function resolveConfigDir(): string {
41
+ const xdg = process.env.XDG_CONFIG_HOME?.trim();
42
+ if (!xdg) return join(homedir(), ".config");
43
+ const expanded = expandTilde(xdg);
44
+ return isAbsolute(expanded) ? expanded : join(homedir(), ".config");
45
+ }
46
+
47
+ function configPath(name: string): string {
48
+ return join(resolveConfigDir(), name, "config.json");
49
+ }
50
+
51
+ function legacyConfigPath(name: string): string {
52
+ return join(homedir(), ".config", name, "config.json");
53
+ }
54
+
55
+ function loadJsonConfig<T>(path: string): T {
56
+ if (!existsSync(path)) return {} as T;
57
+ try {
58
+ const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
59
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {} as T;
60
+ return parsed as T;
61
+ } catch (error) {
62
+ console.warn(`[pi-todo] invalid JSON at ${path}; using defaults: ${String(error)}`);
63
+ return {} as T;
64
+ }
65
+ }
66
+
67
+ export function loadConfig(): TodoConfig {
68
+ const currentPath = configPath("rpiv-todo");
69
+ if (existsSync(currentPath)) return loadJsonConfig<TodoConfig>(currentPath);
70
+ return loadJsonConfig<TodoConfig>(legacyConfigPath("rpiv-todo"));
71
+ }
72
+
73
+ export function getMaxWidgetLines(): number {
74
+ const lines = loadConfig().maxWidgetLines;
75
+ return typeof lines === "number" && lines >= 3 ? lines : DEFAULT_MAX_WIDGET_LINES;
76
+ }
77
+
78
+ const SPECIAL_KEYS = new Set([
79
+ "escape",
80
+ "esc",
81
+ "enter",
82
+ "return",
83
+ "tab",
84
+ "space",
85
+ "backspace",
86
+ "delete",
87
+ "insert",
88
+ "clear",
89
+ "home",
90
+ "end",
91
+ "pageup",
92
+ "pagedown",
93
+ "up",
94
+ "down",
95
+ "left",
96
+ "right",
97
+ ...Array.from({ length: 12 }, (_, index) => `f${index + 1}`),
98
+ ]);
99
+
100
+ const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
101
+
102
+ /** Validate a collapse-key spec against pi-tui's KeyId grammar. */
103
+ export function isValidCollapseKeySpec(spec: string): boolean {
104
+ if (!spec || spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
105
+ const parts = spec.split("+");
106
+ const base = parts.at(-1) ?? "";
107
+ const modifiers = parts.slice(0, -1);
108
+ if (modifiers.length !== new Set(modifiers).size) return false;
109
+ if (!modifiers.every((modifier) => MODIFIERS.has(modifier))) return false;
110
+ return base.length === 1
111
+ ? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base)
112
+ : SPECIAL_KEYS.has(base);
113
+ }
114
+
115
+ /** Resolve the configured collapse key, falling back to the default. */
116
+ export function resolveCollapseKey(): CollapseKeySpec {
117
+ const configured = loadConfig().collapseKey;
118
+ const raw = typeof configured === "string" ? configured.trim().toLowerCase() : undefined;
119
+ if (!raw) return DEFAULT_COLLAPSE_KEY;
120
+ if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
121
+ return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
122
+ }
123
+
124
+ export function validateGuidanceFields(fields: unknown): GuidanceFields {
125
+ if (!fields || typeof fields !== "object" || Array.isArray(fields)) return {};
126
+ const value = fields as Record<string, unknown>;
127
+ const result: GuidanceFields = {};
128
+ if (typeof value.promptSnippet === "string" && value.promptSnippet.length > 0) {
129
+ result.promptSnippet = value.promptSnippet;
130
+ }
131
+ if (
132
+ Array.isArray(value.promptGuidelines) &&
133
+ value.promptGuidelines.length > 0 &&
134
+ value.promptGuidelines.every((item) => typeof item === "string" && item.length > 0)
135
+ ) {
136
+ result.promptGuidelines = value.promptGuidelines;
137
+ }
138
+ if (typeof value.description === "string" && value.description.length > 0)
139
+ result.description = value.description;
140
+ return result;
141
+ }
@@ -0,0 +1,108 @@
1
+ # Configuration reference
2
+
3
+ Every option `@indexyz/pi-todo` reads, where the file lives, and exactly what happens when a value is wrong.
4
+
5
+ ## Where the file lives
6
+
7
+ The config file is optional. It is resolved in this order:
8
+
9
+ 1. `$XDG_CONFIG_HOME/rpiv-todo/config.json` — used when `XDG_CONFIG_HOME` is set
10
+ to an absolute path. A bare `~` or a leading `~/` is expanded first; a `~user`
11
+ form is not expanded and therefore falls through.
12
+ 2. `~/.config/rpiv-todo/config.json` — used when `XDG_CONFIG_HOME` is unset,
13
+ empty, whitespace-only, or relative.
14
+ 3. If the XDG file does not exist, the legacy `~/.config/rpiv-todo/config.json`
15
+ is read anyway, so a pre-XDG file is still found after you set
16
+ `XDG_CONFIG_HOME`. This fallback is one-way: if the XDG file exists but is
17
+ malformed, you get a warning and defaults — it does **not** quietly read the
18
+ legacy file instead.
19
+
20
+ Both files missing means every default applies. Malformed JSON prints a
21
+ `rpiv-config: invalid JSON at …` warning and is treated as `{}`. A JSON array or
22
+ a non-object value (`null`, a string, a number, a boolean) is silently treated as
23
+ `{}` — no warning.
24
+
25
+ `rpiv-todo` never writes this file — you create and edit it yourself, and the
26
+ extension only reads it.
27
+
28
+ ## Example
29
+
30
+ ```json
31
+ {
32
+ "maxWidgetLines": 8,
33
+ "collapseKey": "alt+t",
34
+ "guidance": {
35
+ "promptSnippet": "Use the `todo` tool to track multi-step work before starting it.",
36
+ "promptGuidelines": [
37
+ "Create one task per discrete step.",
38
+ "Mark a task in_progress while working on it; completed when done."
39
+ ]
40
+ }
41
+ }
42
+ ```
43
+
44
+ ## `maxWidgetLines`
45
+
46
+ **Default `12`.** The content-row budget for the overlay — the heading row and,
47
+ on overflow, the `+N more` summary row both count against it. Only the trailing
48
+ blank spacer sits outside the budget, so `12` renders up to 13 terminal rows.
49
+
50
+ - Floor of `3`. A number below `3` falls back to the default.
51
+ - A non-number falls back to the default.
52
+ - No ceiling.
53
+ - Read fresh on every render, so a change takes effect on the next repaint —
54
+ no `/reload`.
55
+ - Pi's tool-output expansion mode (`ctrl+o` by default) temporarily overrides
56
+ this budget and shows every task; collapsing restores the configured budget.
57
+
58
+ ## `collapseKey`
59
+
60
+ **Default `"ctrl+shift+t"`.** The shortcut that collapses and expands the
61
+ overlay.
62
+
63
+ The value is trimmed and lowercased, then matched against Pi's keybinding
64
+ grammar: zero or more distinct modifiers joined by `+`, then a base key.
65
+
66
+ | Part | Accepted |
67
+ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68
+ | Modifiers | `ctrl`, `shift`, `alt`, `super` — each at most once |
69
+ | Base key | one printable character (`a`, `7`, `]`, `/`, …) |
70
+ | Base key | a named key: `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`, `f1`–`f12` |
71
+
72
+ Examples: `alt+o`, `ctrl+shift+t`, `super+alt+f5`.
73
+
74
+ - A missing, empty, blank, non-string, or ungrammatical value falls back to the
75
+ default. The grammar is checked strictly on purpose: Pi takes the last `+`-part
76
+ as the base key and ignores unknown parts, so a typo like `ctr+]` would
77
+ otherwise capture every bare `]` keypress globally.
78
+ - `"off"` disables the feature — no shortcut is registered at all.
79
+ - The binding is resolved **once at extension load**. After editing this value,
80
+ run `/reload` to rebind; until you do, the old key stays active even though the
81
+ collapsed panel's hint text (which is resolved per render) already shows the
82
+ new one.
83
+
84
+ ## Guidance
85
+
86
+ `guidance.promptSnippet` (string) and `guidance.promptGuidelines` (array of
87
+ strings) replace the prompt copy the `todo` tool advertises to the model. Both
88
+ are absent by default, in which case the built-in snippet and the nine built-in
89
+ guideline bullets are used.
90
+
91
+ - `promptSnippet` must be a non-empty string; an empty string or a wrong type
92
+ falls back to the default.
93
+ - `promptGuidelines` must be a non-empty array of non-empty strings. A non-array,
94
+ or an array containing an empty string, falls back to the default — the array
95
+ is all-or-nothing, not merged item by item.
96
+ - Both are read at extension load, so `/reload` after editing them.
97
+
98
+ ## Environment variables
99
+
100
+ | Variable | Effect |
101
+ | ----------------- | ---------------------------------------------------------- |
102
+ | `XDG_CONFIG_HOME` | Relocates the config directory, as described above. |
103
+ | `HOME` | Anchors `~/.config` when `XDG_CONFIG_HOME` does not apply. |
104
+
105
+ `rpiv-todo` reads no environment variables of its own. If you have
106
+ [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
107
+ installed, that package has its own locale configuration and its own env-var
108
+ chain — see its README.
@@ -0,0 +1,128 @@
1
+ # Overlay and `/todos` display
2
+
3
+ How `@indexyz/pi-todo` renders the task list — when the overlay appears, what
4
+ each glyph means, how overflow is trimmed, and which strings localize.
5
+
6
+ ## When the overlay exists
7
+
8
+ The widget is mounted above the Pi editor under the key `rpiv-todos`.
9
+
10
+ | Stage | Condition |
11
+ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
12
+ | Created | At the first session start that has a UI. A headless session never creates it. |
13
+ | Registered | Only while at least one overlay-visible task exists. The widget unregisters itself when the list empties, and re-registers when a task reappears. |
14
+ | Bound | Only the foreground session's overlay is refreshed. A detached or child session has its own task state and never rebinds or repaints the foreground panel. |
15
+ | Disposed | On the foreground session's shutdown. A child session shutting down leaves the overlay alone. |
16
+
17
+ Task state is partitioned by session id, so parallel sessions cannot read or
18
+ overwrite each other's lists. Nothing is written to disk: on session start,
19
+ compaction, and session-tree changes, the list is rebuilt by walking the branch
20
+ and taking the last saved snapshot, which replaces the whole list
21
+ (last-write-wins). See [tool-schema.md](./tool-schema.md#persistence) for where
22
+ snapshots are saved.
23
+
24
+ ## Anatomy of a row
25
+
26
+ ```
27
+ ● Todos (2/5)
28
+ ├─ ✓ Create DemoTodo domain entity
29
+ ├─ ✓ Create IDemoTodoRepository interface
30
+ ├─ ◐ Create DemoTodoRepository (creating the repository)
31
+ ├─ ○ Register DI bindings
32
+ └─ ○ Add integration tests
33
+ ```
34
+
35
+ - **Heading** — `● Todos (done/total)` in the accent color while any task is
36
+ `pending` or `in_progress`; `○ Todos (done/total)` dimmed once everything is
37
+ completed.
38
+ - **Glyphs** — `○` pending, `◐` in_progress, `✓` completed, `✗` deleted.
39
+ Completed and deleted subjects render dim and struck through.
40
+ - **activeForm** — appended dim in parentheses, only while the task is
41
+ `in_progress`.
42
+ - **Dependencies** — appended as `⛓ #1,#2` when the task has a `blockedBy` set.
43
+ - **`#id` prefix** — shown on every row only when at least one visible task
44
+ carries a `blockedBy`. Without a `⛓ #N` anywhere, the per-row ids have nothing
45
+ to point at, so they are omitted.
46
+ - **Prefixes** — `├─` on each row, `└─` on the last one. A blank spacer line is
47
+ always appended below the panel so it is not flush against the input box.
48
+
49
+ Rows longer than the terminal width are truncated with `…`.
50
+
51
+ ## Overflow
52
+
53
+ The content-row budget is `maxWidgetLines` (default `12`), and the heading counts
54
+ against it. When there are more tasks than fit:
55
+
56
+ 1. one row is reserved for the summary line;
57
+ 2. completed tasks are dropped first, newest first — the oldest completed rows
58
+ are the last completed rows to go;
59
+ 3. if the unfinished tasks alone still overflow, the tail of that list is
60
+ truncated;
61
+ 4. the last row becomes `+N more (X completed, Y pending)`.
62
+
63
+ Use Pi's tool-output expansion shortcut (`ctrl+o` by default) to expand the
64
+ widget and show every task. Collapsing Pi's tool output reapplies the configured
65
+ row budget. Unfinished work is therefore the last thing to disappear in the
66
+ compact view. See [configuration.md](./configuration.md#maxwidgetlines) for the
67
+ budget's floor and reload semantics.
68
+
69
+ ## Completed tasks fading out
70
+
71
+ A completed task stays on screen for the remainder of the turn in which it was
72
+ completed. At the start of the next agent turn, every completed row that has
73
+ already been displayed is hidden from later renders. Reloading or compacting the
74
+ session resets that tracking, so a fresh session shows the full list again.
75
+
76
+ ## Collapsing
77
+
78
+ Press `ctrl+shift+t` to collapse the panel to two lines — the heading plus a dim
79
+ `└─ ctrl+shift+t to expand` hint — and again to expand it. The hint always shows
80
+ the currently configured key.
81
+
82
+ Rebind or disable the shortcut with the `collapseKey` option; see
83
+ [configuration.md](./configuration.md#collapsekey). If the shortcut is set to
84
+ `"off"` while the panel is collapsed, the hint becomes a static `collapsed`
85
+ label rather than advertising an unbindable key.
86
+
87
+ ## `/todos`
88
+
89
+ `/todos` prints the whole list grouped by status, independent of the overlay's
90
+ row budget and auto-hiding:
91
+
92
+ ```
93
+ 2/7 completed · 1 in progress · 4 pending
94
+ ── Pending ──
95
+ ○ #4 Register DI bindings
96
+ ○ #5 Add integration tests ⛓ #4
97
+ ○ #6 Wire up the HTTP endpoint
98
+ ○ #7 Update the API docs
99
+ ── In Progress ──
100
+ ◐ #3 Create DemoTodoRepository (creating the repository)
101
+ ── Completed ──
102
+ ✓ #1 Create DemoTodo domain entity
103
+ ✓ #2 Create IDemoTodoRepository interface
104
+ ```
105
+
106
+ The header omits any count that is zero. Sections appear only when they have
107
+ tasks. Tombstoned tasks are never listed.
108
+
109
+ - With no tasks: `No todos yet. Ask the agent to add some!`
110
+ - In a non-interactive session: `/todos requires interactive mode`
111
+
112
+ ## Localization
113
+
114
+ The overlay heading, the `+N more` summary, the collapse hint, the `/todos`
115
+ section headers, and the status words all localize through
116
+ [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
117
+ when that package is installed. Bundled locales: `de`, `en`, `es`, `fr`, `pt`,
118
+ `pt-BR`, `ru`, `uk`, `zh`.
119
+
120
+ LLM-facing output — the tool response envelope, reducer error messages, and the
121
+ schema descriptions — stays English by design.
122
+
123
+ The SDK is a soft optional peer, loaded through a dynamic import at module init.
124
+ When it is absent, every call site returns its inline English literal and the
125
+ extension stays online: no warning, no crash. Install it at any time with
126
+ `pi install npm:@juicesharp/rpiv-i18n` and restart the session. To add or
127
+ override a translation, drop a `locales/<code>.json` file mirroring `en.json` —
128
+ see the `@juicesharp/rpiv-i18n` README's "Contributing translations" section.