@gamflaz/opencode-todolist 1.0.12 → 1.1.1

package/README.md

@@ -8,6 +8,7 @@ plus a TUI widget above the composer that shows progress in real time.
 - Hierarchical tasks: any number of root tasks, each with up to 9 subtasks.
 - Numeric IDs only: root `1`, `2`, … and subtasks `1.1`, `1.2`, … (`1.9` max).
 - Small partial updates: change one item without resending the whole list.
+- Scoped reads: pull the whole list, one branch, or a single item.
 - Strict forward-only progress with enforced order between root tasks.
 - Real-time TUI widget with collapse, scroll, `↻ Continue`, and clear controls.
 - Bundled skills that teach the agent how to drive the tool.
@@ -40,22 +41,36 @@ dependencies, so `bun install` is required before use.
 
 #### Operation fields
 
-| Operation | Required fields                 | Optional fields                |
-| --------- | ------------------------------- | ------------------------------ |
-| `read`    | `operation`                     | None                           |
-| `write`   | `operation`, `todos`            | None; use `todos: []` to clear |
-| `update`  | `operation`, `id`, `status`     | `content`, `priority`, `note`  |
+| Operation | Required fields             | Optional fields                |
+| --------- | --------------------------- | ------------------------------ |
+| `read`    | `operation`                 | `scope`, `target`              |
+| `write`   | `operation`, `todos`        | None; use `todos: []` to clear |
+| `update`  | `operation`, `id`, `status` | `content`, `priority`, `note`  |
 
 For `update`, send `null` for `priority` or `note` to remove the existing value.
 
 ### Read
 
+By default `read` returns the whole list. An optional `scope` narrows it to one
+branch or one row, which keeps the response small on a long list.
+
+| `scope`    | `target`            | Returns                                      |
+| ---------- | ------------------- | -------------------------------------------- |
+| `all`      | —                   | the whole list (default)                     |
+| `root`     | a root id, e.g. `1` | that root and all of its subtasks            |
+| `children` | a subtask id, `1.1` | that subtask, with its root shown as context |
+| `item`     | `1` or `1.1`        | only that row                                |
+
+`target` is only valid together with `scope: "root"`, `"children"`, or
+`"item"` — passing it without one is rejected, so a scope can never be silently
+ignored.
+
+The whole list:
+
 ```json
 { "operation": "read" }
 ```
 
-Returns the current list as a progress tree:
-
 ```text
 [~] 1. Design architecture (1/2)
     ↳ note: Keep the hierarchy shallow
@@ -64,9 +79,35 @@ Returns the current list as a progress tree:
 [ ] 2. Write tests
 ```
 
+One branch (`root`):
+
+```json
+{ "operation": "read", "scope": "root", "target": 1 }
+```
+
+A single subtask, with its root as context (`children`):
+
+```json
+{ "operation": "read", "scope": "children", "target": 1.2 }
+```
+
+```text
+[~] 1. Design architecture (1/2)
+    [~] 1.2 API endpoints
+```
+
+One row with no context (`item`):
+
+```json
+{ "operation": "read", "scope": "item", "target": 1.2 }
+```
+
 Markers: `[ ]` pending, `[~]` in progress, `[x]` completed, `[-]` cancelled,
 `[!]` error. Notes render under their item as `↳ note: …`.
 
+Even when a scope hides rows, the root keeps its real `(completed/total)` count —
+only the display is narrowed.
+
 ### Write
 
 `write` initializes a session or clears it. A non-empty list is only accepted
@@ -100,14 +141,14 @@ Clear the current list:
 
 #### Todo item fields
 
-| Field      | Type                              | Required        | Description                                                               |
-| ---------- | --------------------------------- | --------------- | ------------------------------------------------------------------------- |
-| `id`       | number                            | Yes             | Root: positive integer. Child: `<root>.<n>`, such as `1.1`.              |
-| `content`  | string                            | Yes             | Task summary.                                                             |
-| `status`   | enum                              | Yes             | `pending`, `in_progress`, `completed`, `cancelled`, or `error`.           |
-| `priority` | `high` \| `medium` \| `low`       | No              | Optional priority label.                                                  |
-| `note`     | string                            | No              | Technical context or evidence.                                            |
-| `children` | array of child items              | No, root only   | Up to 9 subtasks. Child items cannot contain more children.               |
+| Field      | Type                        | Required      | Description                                                     |
+| ---------- | --------------------------- | ------------- | --------------------------------------------------------------- |
+| `id`       | number                      | Yes           | Root: positive integer. Child: `<root>.<n>`, such as `1.1`.     |
+| `content`  | string                      | Yes           | Task summary.                                                   |
+| `status`   | enum                        | Yes           | `pending`, `in_progress`, `completed`, `cancelled`, or `error`. |
+| `priority` | `high` \| `medium` \| `low` | No            | Optional priority label.                                        |
+| `note`     | string                      | No            | Technical context or evidence.                                  |
+| `children` | array of child items        | No, root only | Up to 9 subtasks. Child items cannot contain more children.     |
 
 Root IDs must be unique. A child ID must start with its parent root ID.
 
@@ -129,11 +170,11 @@ Root IDs must be unique. A child ID must start with its parent root ID.
 
 | Field      | Required | Notes                                                        |
 | ---------- | -------- | ------------------------------------------------------------ |
-| `id`       | Yes      | Root number or subtask number (`1`, `1.1`).                   |
-| `status`   | Yes      | `pending`, `in_progress`, `completed`, `cancelled`, `error`.  |
-| `content`  | No       | One-line summary shown in the widget.                         |
-| `note`     | No       | Technical context or evidence. Pass `null` to remove.         |
-| `priority` | No       | `high`, `medium`, or `low`. Pass `null` to remove.            |
+| `id`       | Yes      | Root number or subtask number (`1`, `1.1`).                  |
+| `status`   | Yes      | `pending`, `in_progress`, `completed`, `cancelled`, `error`. |
+| `content`  | No       | One-line summary shown in the widget.                        |
+| `note`     | No       | Technical context or evidence. Pass `null` to remove.        |
+| `priority` | No       | `high`, `medium`, or `low`. Pass `null` to remove.           |
 
 ## Skills
 
@@ -152,15 +193,3 @@ bun run compile # rebuild dist/ (tsc + Solid JSX transform)
 `bun run compile` must be used instead of `bun run build`: the raw `tsc` pass
 alone leaves intermediate `.jsx` files in `dist/`, which Bun then prefers over
 the compiled `.js` and reports as `No renderer found` / `ENOENT ... dist/tui.jsx`.
-
-## Publishing notes
-
-`dist/`, `index.js`, and `tui.js` are generated build output and are not
-committed. They reach users through the npm tarball: npm runs `prepare`
-(`bun run compile`) before packing, and `files` ships the built `dist/`
-directory. The `opencode plugin add` installer skips lifecycle scripts
-(`ignoreScripts: true`), so the tarball — not a post-install build — must
-contain `dist/`.
-
-Before publishing, run `bun run check && bun run compile` and confirm
-`dist/` contains no `.jsx` files.

package/dist/icons/glyph.d.ts

@@ -0,0 +1,77 @@
+import { type ColorInput } from "@opentui/core";
+/** Cell size accepted by the layout engine. */
+export type GlyphSize = number | "auto" | `${number}%`;
+export type GlyphProps = {
+    /**
+     * The glyph to draw. Pass a function to keep it reactive (the arrow depends
+     * on `isCollapsed()`), or a plain string for a fixed symbol.
+     */
+    glyph: (() => string) | string;
+    color?: ColorInput;
+    /** Shortcut: stretch to `100%` on both axes (fill the parent). */
+    fill?: boolean;
+    /** Shorthand that sets both `width` and `height`. */
+    size?: GlyphSize;
+    /** Horizontal cells; overrides `fill` and `size`. Defaults to `"auto"`. */
+    width?: GlyphSize;
+    /** Vertical cells; overrides `fill` and `size`. Defaults to `"auto"`. */
+    height?: GlyphSize;
+};
+export type GlyphBox = {
+    readonly width: GlyphSize;
+    readonly height: GlyphSize;
+};
+/**
+ * Resolves the box for a glyph.
+ *
+ * Precedence per axis: `width`/`height` > `fill` (100%) > `size` > `"auto"`.
+ *
+ * The default is `"auto"`, so the zero-configuration case fills exactly what
+ * the glyph needs. `fill` switches both axes to `100%` in one word, which is
+ * the simple "just stretch to whatever space there is" form.
+ *
+ * Kept pure so the rules are testable without a live renderer.
+ */
+export declare function ResolveGlyphBox(props: {
+    fill?: boolean;
+    size?: GlyphSize;
+    width?: GlyphSize;
+    height?: GlyphSize;
+}): GlyphBox;
+/**
+ * A colored terminal glyph in a single text node.
+ *
+ * Matches OpenCode's own MCP sidebar, which renders
+ * `<text fg={...}>{open ? "▼" : "▶"}</text>`
+ * (packages/tui/src/feature-plugins/sidebar/mcp.tsx). A `fg` attribute on
+ * `<text>` is reactive: TextBufferRenderable's fg setter calls requestRender().
+ *
+ * `glyph` accepts either an accessor or a plain string. Solid hands components
+ * getters, so an accessor stays live while a string is simply constant.
+ *
+ * Sizing: `width` and `height` default to `"auto"`. `fill` stretches both axes
+ * to `100%` in one word, `size` sets a square box, and explicit `width`/`height`
+ * win over both.
+ *
+ * A terminal cannot scale a character — a glyph always paints in one cell, so
+ * `size`/`fill` reserve layout space rather than enlarging the symbol. To make a
+ * control read as larger, give it a bigger box (or use the SVG icon path where
+ * the terminal supports images).
+ */
+export declare function Glyph(props: GlyphProps): import("solid-js").JSX.Element;
+/**
+ * The zero-configuration variant: only a glyph and an optional colour, with
+ * auto width and height. Use this unless a specific box is required.
+ */
+export declare function GlyphAuto(props: {
+    glyph: (() => string) | string;
+    color?: ColorInput;
+}): import("solid-js").JSX.Element;
+/**
+ * The stretch variant: fills `100%` of the parent on both axes, so the size
+ * follows the surrounding layout without hand-tuned numbers.
+ */
+export declare function GlyphFill(props: {
+    glyph: (() => string) | string;
+    color?: ColorInput;
+}): import("solid-js").JSX.Element;

package/dist/icons/glyph.js

@@ -0,0 +1,103 @@
+import { createComponent as _$createComponent } from "@opentui/solid";
+import { effect as _$effect } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
+import { setProp as _$setProp } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+/** Cell size accepted by the layout engine. */
+
+/**
+ * Resolves the box for a glyph.
+ *
+ * Precedence per axis: `width`/`height` > `fill` (100%) > `size` > `"auto"`.
+ *
+ * The default is `"auto"`, so the zero-configuration case fills exactly what
+ * the glyph needs. `fill` switches both axes to `100%` in one word, which is
+ * the simple "just stretch to whatever space there is" form.
+ *
+ * Kept pure so the rules are testable without a live renderer.
+ */
+export function ResolveGlyphBox(props) {
+  const fillSize = "100%";
+  return {
+    width: props.width ?? (props.fill ? fillSize : undefined) ?? props.size ?? "auto",
+    height: props.height ?? (props.fill ? fillSize : undefined) ?? props.size ?? "auto"
+  };
+}
+
+/**
+ * A colored terminal glyph in a single text node.
+ *
+ * Matches OpenCode's own MCP sidebar, which renders
+ * `<text fg={...}>{open ? "▼" : "▶"}</text>`
+ * (packages/tui/src/feature-plugins/sidebar/mcp.tsx). A `fg` attribute on
+ * `<text>` is reactive: TextBufferRenderable's fg setter calls requestRender().
+ *
+ * `glyph` accepts either an accessor or a plain string. Solid hands components
+ * getters, so an accessor stays live while a string is simply constant.
+ *
+ * Sizing: `width` and `height` default to `"auto"`. `fill` stretches both axes
+ * to `100%` in one word, `size` sets a square box, and explicit `width`/`height`
+ * win over both.
+ *
+ * A terminal cannot scale a character — a glyph always paints in one cell, so
+ * `size`/`fill` reserve layout space rather than enlarging the symbol. To make a
+ * control read as larger, give it a bigger box (or use the SVG icon path where
+ * the terminal supports images).
+ */
+export function Glyph(props) {
+  const text = () => {
+    const glyph = props.glyph;
+    return typeof glyph === "function" ? glyph() : glyph;
+  };
+  const box = () => ResolveGlyphBox(props);
+  return (() => {
+    var _el$ = _$createElement("text");
+    _$setProp(_el$, "wrapMode", "none");
+    _$insert(_el$, text);
+    _$effect(_p$ => {
+      var _v$ = props.color,
+        _v$2 = box().width,
+        _v$3 = box().height;
+      _v$ !== _p$.e && (_p$.e = _$setProp(_el$, "fg", _v$, _p$.e));
+      _v$2 !== _p$.t && (_p$.t = _$setProp(_el$, "width", _v$2, _p$.t));
+      _v$3 !== _p$.a && (_p$.a = _$setProp(_el$, "height", _v$3, _p$.a));
+      return _p$;
+    }, {
+      e: undefined,
+      t: undefined,
+      a: undefined
+    });
+    return _el$;
+  })();
+}
+
+/**
+ * The zero-configuration variant: only a glyph and an optional colour, with
+ * auto width and height. Use this unless a specific box is required.
+ */
+export function GlyphAuto(props) {
+  return _$createComponent(Glyph, {
+    get glyph() {
+      return props.glyph;
+    },
+    get color() {
+      return props.color;
+    }
+  });
+}
+
+/**
+ * The stretch variant: fills `100%` of the parent on both axes, so the size
+ * follows the surrounding layout without hand-tuned numbers.
+ */
+export function GlyphFill(props) {
+  return _$createComponent(Glyph, {
+    get glyph() {
+      return props.glyph;
+    },
+    get color() {
+      return props.color;
+    },
+    fill: true
+  });
+}

package/dist/icons/glyphs.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Terminal glyphs for the TUI widget.
+ *
+ * These are plain Unicode characters rather than rendered SVG images. Terminal
+ * image protocols (Kitty, Sixel) are advertised inconsistently — Termius, for
+ * example, advertises Kitty support but fails to load the payload — so a
+ * capability probe can select an image branch that never actually renders and
+ * never falls back.
+ *
+ * Reference: OpenCode's own MCP sidebar uses exactly this shape
+ * (`packages/tui/src/feature-plugins/sidebar/mcp.tsx`):
+ *
+ *   <text fg={theme.text.base}>{view.open ? "▼" : "▶"}</text>
+ *
+ * A terminal cannot scale a character: one code point paints in one cell, so
+ * `size`/`width`/`height` on a glyph reserve layout space and never enlarge the
+ * symbol. To make an indicator look bigger it must be drawn from several cells
+ * (block art) or rendered as an image on terminals that support it.
+ */
+/** Collapsed indicator. */
+export declare const ARROW_RIGHT = "\u25B6";
+/** Expanded indicator. */
+export declare const ARROW_DOWN = "\u25BC";
+/** Continue action. */
+export declare const CONTINUE = "\u21BB";
+/** Clear action. */
+export declare const CLEAR = "\u2A2F";
+export declare const ALL_GLYPHS: {
+    readonly ARROW_RIGHT: "▶";
+    readonly ARROW_DOWN: "▼";
+    readonly CONTINUE: "↻";
+    readonly CLEAR: "⨯";
+};
+/**
+ * Exact codepoints shipped. Pinned so tests catch an accidental swap to a
+ * visually similar character that may not exist in every terminal font.
+ *
+ * Update these whenever a glyph above changes; the test compares the two.
+ */
+export declare const GLYPH_CODEPOINTS: {
+    readonly ARROW_RIGHT: 9654;
+    readonly ARROW_DOWN: 9660;
+    readonly CONTINUE: 8635;
+    readonly CLEAR: 10799;
+};
+/**
+ * Rejected look-alikes: characters that are visually similar but too small or
+ * not universally available in terminal fonts. Kept so a regression cannot
+ * quietly reintroduce a shrunk indicator.
+ */
+export declare const REJECTED_GLYPHS: readonly ["▸", "▾", "▷", "◁"];

package/dist/icons/glyphs.js

@@ -0,0 +1,56 @@
+/**
+ * Terminal glyphs for the TUI widget.
+ *
+ * These are plain Unicode characters rather than rendered SVG images. Terminal
+ * image protocols (Kitty, Sixel) are advertised inconsistently — Termius, for
+ * example, advertises Kitty support but fails to load the payload — so a
+ * capability probe can select an image branch that never actually renders and
+ * never falls back.
+ *
+ * Reference: OpenCode's own MCP sidebar uses exactly this shape
+ * (`packages/tui/src/feature-plugins/sidebar/mcp.tsx`):
+ *
+ *   <text fg={theme.text.base}>{view.open ? "▼" : "▶"}</text>
+ *
+ * A terminal cannot scale a character: one code point paints in one cell, so
+ * `size`/`width`/`height` on a glyph reserve layout space and never enlarge the
+ * symbol. To make an indicator look bigger it must be drawn from several cells
+ * (block art) or rendered as an image on terminals that support it.
+ */
+/** Collapsed indicator. */
+export const ARROW_RIGHT = "▶";
+/** Expanded indicator. */
+export const ARROW_DOWN = "▼";
+/** Continue action. */
+export const CONTINUE = "↻";
+/** Clear action. */
+export const CLEAR = "⨯";
+export const ALL_GLYPHS = {
+    ARROW_RIGHT,
+    ARROW_DOWN,
+    CONTINUE,
+    CLEAR,
+};
+/**
+ * Exact codepoints shipped. Pinned so tests catch an accidental swap to a
+ * visually similar character that may not exist in every terminal font.
+ *
+ * Update these whenever a glyph above changes; the test compares the two.
+ */
+export const GLYPH_CODEPOINTS = {
+    ARROW_RIGHT: 0x25b6, // ▶
+    ARROW_DOWN: 0x25bc, // ▼
+    CONTINUE: 0x21bb, // ↻
+    CLEAR: 0x2a2f, // ⨯
+};
+/**
+ * Rejected look-alikes: characters that are visually similar but too small or
+ * not universally available in terminal fonts. Kept so a regression cannot
+ * quietly reintroduce a shrunk indicator.
+ */
+export const REJECTED_GLYPHS = [
+    "▸", // U+25B8 small triangle, too small at this size
+    "▾", // U+25BE small triangle, too small at this size
+    "▷", // U+25B7 outline triangle, too small
+    "◁", // U+25C1 outline triangle, too small
+];

package/dist/index.d.ts

@@ -1,11 +1,30 @@
 import { Plugin } from "@opencode/plugin";
-import { type TodoRootItem } from "./schemas/todo";
-export declare function formatReadOutput(todos: readonly TodoRootItem[]): string;
+import { type TodoReadInput, type TodoRootItem } from "./schemas/todo";
+export declare function formatReadOutput(todos: readonly TodoRootItem[], options?: {
+    visibleIds?: readonly number[];
+}): string;
 export declare function formatTransitionLines(before: readonly TodoRootItem[], after: readonly TodoRootItem[]): string[];
 export declare function formatWriteOutput(todos: readonly TodoRootItem[], before?: readonly TodoRootItem[]): string;
 export declare function assertWriteIsInitialization(existing: readonly TodoRootItem[], incoming: readonly TodoRootItem[]): void;
 /** Update response: progress, next step, and transition lines without resending the list. */
 export declare function formatUpdateOutput(todos: readonly TodoRootItem[], before?: readonly TodoRootItem[]): string;
+/**
+ * Narrows a list for a scoped read.
+ *
+ * - `scope: "root"` returns one root with every subtask, so the whole branch is
+ *   visible.
+ * - `scope: "children"` prints the root line as context plus the targeted
+ *   subtask line, matching a "show me this subtask within its root" read.
+ * - `scope: "item"` prints only the targeted row.
+ *
+ * Either way the root keeps every subtask in the *data*, because the root's
+ * `(completed/total)` label is computed from them — dropping them would
+ * silently turn `(2/2)` into `(1/1)`.
+ */
+export declare function selectReadScope(todos: readonly TodoRootItem[], input: TodoReadInput): {
+    todos: TodoRootItem[];
+    visibleIds?: readonly number[];
+};
 export declare function registerTodoTools(ctx: Plugin.Context): Promise<void>;
 export declare function registerTodoPromptHook(ctx: Plugin.Context): Promise<void>;
 declare const _default: Plugin.Plugin;

package/dist/index.js

@@ -5,10 +5,10 @@ import { readTodoData, readTodos, updateTodos } from "./storage/todo-store.js";
 import { buildTodoHint, consumeTodoHint, findNextTodo, findStuckParent, flattenLeaves, isAnyTodoActive, } from "./todos/hint.js";
 import { TodoTree } from "./todos/todo-tree.js";
 import { updateTodoById } from "./todos/update.js";
-export function formatReadOutput(todos) {
+export function formatReadOutput(todos, options) {
     if (todos.length === 0)
         return "No todos recorded.";
-    const tree = new TodoTree(todos).render();
+    const tree = new TodoTree(todos).render(options);
     const check = new TodoTree(todos).validateAndNormalize();
     if (check.valid)
         return tree;
@@ -75,6 +75,38 @@ export function formatUpdateOutput(todos, before = []) {
     const progress = `Todos (${stats.completedSubTasks}/${stats.totalSubTasks}).`;
     return formatWriteOutput(todos, before).replace(/^Todos \(\d+\/\d+\) updated\./, progress.slice(0, -1));
 }
+/**
+ * Narrows a list for a scoped read.
+ *
+ * - `scope: "root"` returns one root with every subtask, so the whole branch is
+ *   visible.
+ * - `scope: "children"` prints the root line as context plus the targeted
+ *   subtask line, matching a "show me this subtask within its root" read.
+ * - `scope: "item"` prints only the targeted row.
+ *
+ * Either way the root keeps every subtask in the *data*, because the root's
+ * `(completed/total)` label is computed from them — dropping them would
+ * silently turn `(2/2)` into `(1/1)`.
+ */
+export function selectReadScope(todos, input) {
+    if (input.scope !== "item" && input.scope !== "children" && input.scope !== "root") {
+        return { todos: [...todos] };
+    }
+    const target = input.target;
+    const rootId = Number.isInteger(target) ? target : Math.floor(target);
+    const root = todos.find((item) => item.id === rootId);
+    const child = Number.isInteger(target)
+        ? undefined
+        : root?.children?.find((item) => item.id === target);
+    if (!root || (!Number.isInteger(target) && !child)) {
+        throw new Error(`[manage_todo_list] todo id ${target} was not found`);
+    }
+    // `root` shows the branch as-is; it needs no row filter at all.
+    if (input.scope === "root")
+        return { todos: [root] };
+    const visibleIds = input.scope === "children" ? [rootId, target] : [target];
+    return { todos: [root], visibleIds };
+}
 export async function registerTodoTools(ctx) {
     await ctx.tool.transform((tools) => {
         tools.add({
@@ -97,7 +129,13 @@ export async function registerTodoTools(ctx) {
                 }
                 if (parsed.data.operation === "read") {
                     const todos = await readTodos(toolContext.sessionID);
-                    return { output: { todos }, content: formatReadOutput(todos) };
+                    const scoped = selectReadScope(todos, parsed.data);
+                    return {
+                        output: { todos: scoped.todos },
+                        content: formatReadOutput(scoped.todos, {
+                            visibleIds: scoped.visibleIds,
+                        }),
+                    };
                 }
                 if (parsed.data.operation === "update") {
                     const updateInput = parsed.data;