taskai-cli 1.6.2__tar.gz → 1.6.3__tar.gz

{taskai_cli-1.6.2 → taskai_cli-1.6.3}/DEVLOG.md

@@ -1,3 +1,47 @@
+# 8-29
+
+Worked the TRIAGE backlog, then built out the docs.
+
+TRIAGE fixes:
+- **Critical:** `_find_model_by_stringmatch` inverted `{id: name}` -> `{name:
+  id}`, silently collapsing duplicate names to one arbitrary id (so
+  update/delete-by-name could hit the wrong item). Now collects every
+  fnmatch hit; one resolves, zero -> `None`, 2+ -> `throw_error` listing the
+  ids. Also gave `throw_error` a `verbose` flag so it stops dumping
+  `args=/kwargs=` on every error.
+- Added `task unlink {parent} {item}` (mirrors `add_link`).
+- Stripped the dead `for record_type in [TodoItem, Comment]` loop in
+  `_find_model_by_stringmatch` and the now-unused `Comment` import.
+- `show_examples()` now prints a real `help_examples` string (via `task
+  examples`); removed the redundant `task show examples` branch.
+
+Browser: soft links (`linked_ids`) now render as "shadow" nodes — a ghost
+copy of the linked item as an extra child under the linking node (~0.92
+alpha, flat, dashed grey border, italic, `↗` glyph, real id). Edge to it is
+dashed grey with a gradient stroke that goes transparent inside either node.
+Selecting/editing a shadow acts on the real item (`itemForNode` -> `realId`).
+
+Docs: README synced with `execute_commands` and given a `task setup`
+walkthrough + Web UI section; `help_menu.py` gained `task browser` / `task
+help` and lost its stale "requires id, not name" grouping (everything takes
+id-or-name now). Then turned `docs/` into a real Read the Docs site — Sphinx
++ MyST + Furo, dynamic version, a `builder-inited` hook that dumps
+`help_general` and the provider table to git-ignored `_generated/` files so
+the reference pages can't drift. Pages (all `.md`): index (gif placeholder +
+feature bullets), getting-started, configuration, managing-the-tree,
+item-data, interactive-mode, browser-mode, ai-integration, commands. No
+caveats/notes in user pages — gaps went to TRIAGE (`dependency_ids`
+unreachable from the CLI; interactive-REPL staleness).
+
+DEVPLAN: added Phases 4-7 (browser improvements: comments, big description
+editor, keyboard shortcuts + left panel; CLI view expansion + config keys;
+comprehensive testing; advertising).
+
+Still open in TRIAGE: multi-word unquoted input (design-blocked), `task
+browser` `[port]`, the two gaps above.
+
+---
+
 # 8-22
 
 Found and fixed a real bug from the `litellm` migration earlier today: it

{taskai_cli-1.6.2 → taskai_cli-1.6.3}/DEVPLAN.md

@@ -57,7 +57,7 @@ is why `taskai/browser.py` reuses `from taskai.cli import db` rather than
 opening a second connection.
 
 **Views.** [taskai/views.py](taskai/views.py): Rich-based tree rendering
-(`view_lists`, `view_item`, `view_items`), display format configurable via
+(`view_lists`, `view_item`), display format configurable via
 `DISPLAY_STRING`/`DISPLAY_COLORS`.
 
 **AI services.** [taskai/services/ai.py](taskai/services/ai.py):
@@ -90,9 +90,12 @@ unless you're told to fix them):**
   name-only-duplicate methods (`show_by_item_name`, `delete_item_by_name`)
   and several inline `_is_int(...)` dispatch branches in `execute_commands`
   were deleted outright rather than kept alongside the id path.
-- `task show <id1>,<id2>,...` is documented in the README but
+- ~~`task show <id1>,<id2>,...` is documented in the README but
   `execute_commands`'s `show` case never dispatches to
-  `Controller.show_items`/`view_items` — there's no wired path to it.
+  `Controller.show_items`/`view_items` — there's no wired path to it.~~
+  Removed rather than wired up — `Controller.show_items` and `view_items`
+  are gone (CLI audit, see DEVLOG); `task show` only ever takes one target
+  now.
 - `Controller.update_item` never calls `Controller._parse_item_kwargs`
   (`create_item` does) before handing kwargs to `db.update_item`. Confirmed
   effects: `update <id> --due_by MM-DD-YYYY` throws a pydantic validation
@@ -250,10 +253,25 @@ stdlib `http.server` — no new dependency, consistent with "less code."
 
 ### 1.4 — DAG view (v2: full graph + interaction)
 
-- [ ] Draw `dependency_ids` and `linked_ids` as a second edge style (dashed
-      / different color) layered on top of the tree edges — this is what
-      makes it a DAG rather than just a tree view. Still open — only
-      parent/child tree edges render today.
+- [~] **`linked_ids` done as "shadow" nodes; `dependency_ids` still
+      deferred to 2.0.** A soft link renders as a lightweight *ghost copy*
+      of the linked item, placed as an extra child under the linking node
+      (`buildShadowNode` in `canvas.js` — non-recursing, carries `realId`
+      back to the true item; `buildTree` appends one per `linked_ids`
+      entry). It's styled subtly apart from a real placement: ~0.92 alpha,
+      no drop shadow, dashed grey border, italic label, an `↗` glyph
+      top-right (the one colour accent), and it shows the linked item's
+      real id rather than the synthetic shadow id. The parent→shadow edge
+      is dashed and uncoloured — grey, the dash pattern alone distinguishes
+      it from the solid tree edges — and drawn with a gradient stroke that
+      goes fully transparent inside either node's square so it never
+      crosses node content (`drawLinkEdges`); solid-edge drawing
+      (`drawLines`) skips shadow children. Selecting or editing a shadow
+      acts on the real item (`itemForNode` resolves `realId`), so the edit
+      panel and `update` commands hit the true record. `dependency_ids` edges are still not drawn — and `task
+      depend` was itself removed from the CLI in an earlier audit pass, so
+      there's no dependency data being created right now anyway; revisit
+      both together in 2.0.
 - [x] Pan (drag) and zoom (wheel) — done via canvas context transforms
       (`ctx.translate`/`ctx.scale` + a `view` state object), not SVG
       `viewBox`, same toolchain reasoning as above. Zoom keeps the point
@@ -335,11 +353,11 @@ purpose, current call.
       of expecting text output.
 - [ ] Up-arrow history — still open, not done.
 
-At the end of Phase 1: dependency/link edges (1.4) and up-arrow console
-history (1.6) are the only pieces left open. The DAG, edit panel, and
-console all funnel through one `/api/command` endpoint and one `/api/tree`
-read, as planned — that's the "less code" payoff of routing everything
-through the existing `Controller`.
+At the end of Phase 1: up-arrow console history (1.6) is the only piece
+left open (dependency/link edges (1.4) deferred to 2.0, see above). The
+DAG, edit panel, and console all funnel through one `/api/command` endpoint
+and one `/api/tree` read, as planned — that's the "less code" payoff of
+routing everything through the existing `Controller`.
 
 ---
 
@@ -459,7 +477,10 @@ like Flash-Lite.
 - [x] Updated README's Config section to match the new `AI_MODEL`
       `provider/model` shape and point at `task setup`.
 
-### 2.4 — `task ai agent <prompt>` (later — real tool-calling loop)
+### 2.4 — `task ai agent <prompt>` (deferred to 2.0 — real tool-calling loop)
+
+**Deferred to 2.0.** Out of scope for the current polish pass; revisit as
+part of the larger 2.0 rework rather than squeezing it in here.
 
 A separate entry point, not a replacement for `task ai`. `task ai <prompt>`
 stays the fast, ungated, one-shot-plan-and-execute path from 2.1-2.3;
@@ -501,15 +522,101 @@ Re-scope this section before starting 2.4.
       `editmenu.js`) and delete anything exploratory left over from getting
       the DAG layout working. Still no bundler — just multiple `<script>`
       tags loaded in order.
-- [ ] **Minimalist docs.** A short "Web UI" section in the README (how to
-      run `task web`, one screenshot) covers most of it; only split into a
-      separate `docs/` page if the README starts feeling long. Keep the
-      "less code" principle applied to prose too — this doesn't need to be
-      exhaustive.
+- [~] **Docs.** README is synced with `execute_commands` (command list,
+      `task ai` flags, Web UI section, `task setup` walkthrough);
+      `help_menu.py` lists `task browser` / `task help`, and its stale
+      "requires id, not name" grouping was corrected (every item-taking
+      command resolves id-or-name via `_resolve_item` now). Grew past a
+      README-only scope into a proper Read the Docs site under `docs/`
+      (Sphinx + MyST + Furo).
+      **Built:** `conf.py` rebuilt (dynamic version from pyproject, Furo,
+      copybutton, sphinx-design; a `builder-inited` hook dumps `help_general`
+      and the `PROVIDER_ENV_VARS` table to git-ignored files under
+      `docs/_generated/` so the reference/config content can't drift from
+      source). Pages, all `.md`: `index` (gif placeholder + "what you can
+      do" + toctree), `getting-started`, `configuration`,
+      `managing-the-tree`, `item-data`, `interactive-mode`, `browser-mode`,
+      `ai-integration`, `commands` (`literalinclude` of the generated help
+      text). No "notes"/caveats in any user page — gaps go to TRIAGE
+      instead. README links to the site.
+      **Still open:** replace `docs/_static/demo.gif` placeholder with a real
+      recording; confirm the RTD project slug (assumed `taskai` in `conf.py`
+      `html_baseurl` + README); explanation/architecture pages; polish
+      (screenshots for browser-mode, custom 404, OpenGraph cards, CI
+      `linkcheck`, tested examples, changelog).
 - [ ] **UX pass.** Empty/loading state for the DAG when a user has no tasks
       yet (currently the app would just render nothing); a keyboard shortcut
       to toggle the console (e.g. backtick); consistent spacing/typography
-      in `style.css`; visual legend distinguishing tree edges from
-      dependency/link edges.
+      in `style.css`. (Edge legend dropped — depended on 1.4's dependency/
+      link edges, now deferred to 2.0.)
 - [ ] Re-check the Phase 0 fixes are still holding once the web UI is
       exercising more command paths than the CLI alone did.
+
+---
+
+## Phase 4 — Browser view improvements
+
+Builds on Phase 1's canvas / edit panel / console. Still plain HTML/CSS/JS, no
+framework, everything routed through the existing `/api/tree` + `/api/command`
+endpoints.
+
+- [ ] **Show comments.** Items carry `comment_ids` but the browser never
+      surfaces them. Render an item's comments in the edit panel — read-only
+      list at minimum; adding one posts `comment <id> <text>` through
+      `/api/command` like every other field. Consider a comment-count
+      affordance on the canvas node itself.
+- [ ] **Much larger description editor.** The `description` field in the edit
+      panel is a small single-line-ish input today. Make it a real multi-line
+      textarea that dominates the panel (large fixed height or auto-grow), so
+      the panel is usable for actual note-taking — likely widen the panel
+      itself while a node is selected.
+- [ ] **Keyboard shortcuts + a shortcuts panel.** Add real key bindings
+      (toggle console, toggle edit panel, complete / delete the selected
+      node, deselect, focus a search box, zoom/pan, …) and a **left-hand
+      panel listing them**, mirroring the right-hand edit panel and
+      collapsible the same way. Follow the existing `STYLE` object +
+      collapsible-panel machinery (`setRightPanelWidth`); this adds a left
+      equivalent. Supersedes the single console-toggle shortcut noted in
+      Phase 3's UX pass.
+
+---
+
+## Phase 5 — CLI view
+
+- [ ] **Expand what `task show` renders, and its options.** Exact scope TBD —
+      needs a working session with Alex to pin down. Candidates: filter by
+      status / priority / completion, depth limits, flat vs. tree layout,
+      sort order, inline comments / links, format and colour toggles. Prompt
+      before implementing.
+- [ ] **New view-settings config keys.** Extend `CLIConfig` (today just
+      `DISPLAY_STRING` / `DISPLAY_COLORS`) with keys backing whatever the
+      expanded view supports; document them in `docs/configuration.md` and
+      `help_menu.py` alongside the existing ones.
+
+---
+
+## Phase 6 — Comprehensive testing & bugfixing
+
+- [ ] **Broaden the test suite.** Currently 7 tests across `test_cli.py` /
+      `test_execution.py` / `test_json_dir_database.py` / `test_view.py`.
+      Cover every `execute_commands` branch, id/name resolution (including
+      the multi-match error path), `_parse_item_kwargs`, the browser
+      endpoints (`/api/tree`, `/api/command`), and the AI command-execution
+      loop with a mocked LLM.
+- [ ] **Fix what the tests surface**, and clear the still-open TRIAGE items
+      as they come up (multi-word unquoted input, `task browser` `[port]`,
+      `dependency_ids` reachability, interactive-REPL staleness).
+- [ ] **Wire CI.** `pytest` on every PR, plus `sphinx-build -W` +
+      `linkcheck` for the docs.
+
+---
+
+## Phase 7 — Advertising
+
+- [ ] Get the docs site live: confirm the Read the Docs slug, record the
+      `docs/_static/demo.gif` terminal demo.
+- [ ] Polish the PyPI listing — `pyproject.toml` has an empty `description`
+      and no keywords / classifiers / project URLs.
+- [ ] Write a short "show and tell" (what it is, the everything-is-an-item
+      model, the AI layer, the canvas view) built around the gif, and decide
+      on channels (Show HN, r/commandline, r/productivity, GitHub topics).

{taskai_cli-1.6.2 → taskai_cli-1.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: taskai-cli
-Version: 1.6.2
+Version: 1.6.3
 Author-email: Alex Paskal <alexcpaskal@gmail.com>
 Requires-Python: >=3.12
 Requires-Dist: fastapi>=0.141.1
@@ -15,6 +15,8 @@ Description-Content-Type: text/markdown
 
 A command-line task manager with AI features.
 
+📖 **Full documentation:** <https://taskai.readthedocs.io>
+
 ```bash
 pip install taskai-cli
 ```
@@ -32,10 +34,11 @@ task setup
 
 ```
 task                              interactive mode
+task help                         show every command
+task examples                     worked command sequences for common workflows
 
 task show all                     show everything
 task show <id|name>               show a specific item
-task show <id1>,<id2>,...         show multiple items
 
 task create <name>                create a top-level item
 task add <parent> <name>          add a child item
@@ -44,27 +47,31 @@ task rename <id> <new name>       rename an item
 task move <item> <new parent>     reparent an item
 task complete <id>                mark complete (recursive)
 task delete <id|name>             delete by id or name
-task delete completed             delete all completed items
+task clear                        delete all completed items
 task clear <parent>               delete completed under a parent
 
 task comment <id> <text>          add a comment
-task depend <src_id> <dst_id>     src depends on dst
-task link <parent> <item>         soft-link two items
+task link <parent> <item>         soft-link an item under a second parent
+task unlink <parent> <item>       remove a soft-link
 task reorder <id1> before|after <id2>
 
 task status <id> <text>           set a status string
 task pomo <on_mins> <off_mins>    pomodoro timer
 
 task ai <prompt>                  natural language → commands
+  --context <path[,path...]>      fold file contents into the prompt
+  --reasoning <level>             model thinking effort: minimal|low|medium|high|disable|none
 task ai headstart <id>            AI suggests next step, saved as comment
 
+task browser                      launch the web UI (see below)
+
 task config show                  list current config
 task config set <key> <value>     set a config value
 task config get <key>             get a config value
 task config pop <key>             remove a config value
 
 task repair                       repair the database
-task nuke                         delete all data
+task nuke                         delete all data (asks to confirm)
 ```
 
 ### Item fields
@@ -78,44 +85,68 @@ Pass any of these as `--field value` to `create`, `add`, or `update`:
 | `priority` | integer | `--priority 2` |
 | `status` | string | `--status "in progress"` |
 | `completed` | bool | `--completed true` |
-| `depends_on` | comma-separated ids | `--depends_on 3,7` |
 
 ---
 
 ## Config
 
-AI features require a model, set as a `provider/model` string (via [litellm](https://github.com/BerriAI/litellm)),
-plus that provider's credentials set as environment variables (e.g. `GEMINI_API_KEY`, `OPENAI_API_KEY`).
-`task setup` will walk you through picking a provider and model and tell you which env vars it needs.
+AI features need a model. `task setup` walks you through choosing a provider
+and model, then tells you which environment variable(s) to set:
+
+```text
+$ task setup
+Beginning setup
+  1. openai
+  2. anthropic
+  3. gemini
+  4. vertex_ai
+  5. groq
+  ...
+  20. ollama
+
+Select a provider (number or name): 3
+  1. gemini-3.7-flash
+  2. gemini-3.1-pro-preview
+  3. gemini-3.6-flash
+  4. gemini-3.5-flash-lite
+  5. gemini-2.5-pro
+
+Select a model for 'gemini' (number or name): 1
+Storing: gemini/gemini-3.7-flash
+Make sure these environment variables are set:
+  GEMINI_API_KEY
+Setup complete! Use 'task config set|get|list' to interact with your configuration options
+```
+
+Either prompt also accepts free-typed text, so you can pick a model newer than
+the built-in menu.
+
+Or set it directly — a `provider/model` string, using
+[litellm](https://github.com/BerriAI/litellm)'s naming:
 
 ```bash
-task config set AI_MODEL gemini/gemini-2.0-flash
+task config set AI_MODEL <provider>/<model>   # e.g. gemini/gemini-3.7-flash
 ```
 
 ---
 
-## Example
+## Web UI
 
-```
-task create "Today"
-task add "Today" "Morning run"
-task add "Today" "Review pull requests" --status "blocked"
-task add "Today" "Call dentist" --due_by 08-02-2026
-task show "Today"
-task complete 4
-task show "Today"
-task exit
+```bash
+task browser
 ```
 
-Or:
+Launches a local web server with a canvas view of your item tree:
 
-```bash
-task ai "add a task called 'Reply to Alex' under Today, and mark the dentist task as done"
-```
+- **pan / zoom** the graph; completed items are tinted green, and soft-links
+  (`task link`) show as dashed "shadow" copies under their host item
+- **click a node** to open an edit panel — each field writes back immediately,
+  there's no save button
+- **console** at the bottom for typing raw `task` commands against the same data
 
 ---
 
-## Another Example
+## Examples
 
 ```bash
 task create "Launch website"
@@ -134,4 +165,12 @@ task ai headstart 3
 # mark something done and clean up
 task complete 2
 task clear "Launch website"
-```
+```
+
+Or drive it entirely from a prompt:
+
+```bash
+task ai "add a task called 'Reply to Alex' under Launch website, and mark the hosting task as done"
+```
+
+Run `task examples` for more worked sequences.

taskai_cli-1.6.3/README.md

@@ -0,0 +1,163 @@
+# taskai
+
+A command-line task manager with AI features.
+
+📖 **Full documentation:** <https://taskai.readthedocs.io>
+
+```bash
+pip install taskai-cli
+```
+
+---
+
+## Setup
+
+```bash
+task setup
+```
+---
+
+## Commands
+
+```
+task                              interactive mode
+task help                         show every command
+task examples                     worked command sequences for common workflows
+
+task show all                     show everything
+task show <id|name>               show a specific item
+
+task create <name>                create a top-level item
+task add <parent> <name>          add a child item
+task update <id> --field value    update any field
+task rename <id> <new name>       rename an item
+task move <item> <new parent>     reparent an item
+task complete <id>                mark complete (recursive)
+task delete <id|name>             delete by id or name
+task clear                        delete all completed items
+task clear <parent>               delete completed under a parent
+
+task comment <id> <text>          add a comment
+task link <parent> <item>         soft-link an item under a second parent
+task unlink <parent> <item>       remove a soft-link
+task reorder <id1> before|after <id2>
+
+task status <id> <text>           set a status string
+task pomo <on_mins> <off_mins>    pomodoro timer
+
+task ai <prompt>                  natural language → commands
+  --context <path[,path...]>      fold file contents into the prompt
+  --reasoning <level>             model thinking effort: minimal|low|medium|high|disable|none
+task ai headstart <id>            AI suggests next step, saved as comment
+
+task browser                      launch the web UI (see below)
+
+task config show                  list current config
+task config set <key> <value>     set a config value
+task config get <key>             get a config value
+task config pop <key>             remove a config value
+
+task repair                       repair the database
+task nuke                         delete all data (asks to confirm)
+```
+
+### Item fields
+
+Pass any of these as `--field value` to `create`, `add`, or `update`:
+
+| Field | Format | Example |
+|---|---|---|
+| `description` | string | `--description "needs review"` |
+| `due_by` | MM-DD-YYYY | `--due_by 08-15-2026` |
+| `priority` | integer | `--priority 2` |
+| `status` | string | `--status "in progress"` |
+| `completed` | bool | `--completed true` |
+
+---
+
+## Config
+
+AI features need a model. `task setup` walks you through choosing a provider
+and model, then tells you which environment variable(s) to set:
+
+```text
+$ task setup
+Beginning setup
+  1. openai
+  2. anthropic
+  3. gemini
+  4. vertex_ai
+  5. groq
+  ...
+  20. ollama
+
+Select a provider (number or name): 3
+  1. gemini-3.7-flash
+  2. gemini-3.1-pro-preview
+  3. gemini-3.6-flash
+  4. gemini-3.5-flash-lite
+  5. gemini-2.5-pro
+
+Select a model for 'gemini' (number or name): 1
+Storing: gemini/gemini-3.7-flash
+Make sure these environment variables are set:
+  GEMINI_API_KEY
+Setup complete! Use 'task config set|get|list' to interact with your configuration options
+```
+
+Either prompt also accepts free-typed text, so you can pick a model newer than
+the built-in menu.
+
+Or set it directly — a `provider/model` string, using
+[litellm](https://github.com/BerriAI/litellm)'s naming:
+
+```bash
+task config set AI_MODEL <provider>/<model>   # e.g. gemini/gemini-3.7-flash
+```
+
+---
+
+## Web UI
+
+```bash
+task browser
+```
+
+Launches a local web server with a canvas view of your item tree:
+
+- **pan / zoom** the graph; completed items are tinted green, and soft-links
+  (`task link`) show as dashed "shadow" copies under their host item
+- **click a node** to open an edit panel — each field writes back immediately,
+  there's no save button
+- **console** at the bottom for typing raw `task` commands against the same data
+
+---
+
+## Examples
+
+```bash
+task create "Launch website"
+
+# add subtasks (by name or id)
+task add "Launch website" "Write copy"
+task add "Launch website" "Design mockups" --priority 1
+task add "Launch website" "Set up hosting" --due_by 08-15-2026
+
+# check your work
+task show "Launch website"
+
+# ask AI what to do first on a specific task
+task ai headstart 3
+
+# mark something done and clean up
+task complete 2
+task clear "Launch website"
+```
+
+Or drive it entirely from a prompt:
+
+```bash
+task ai "add a task called 'Reply to Alex' under Launch website, and mark the hosting task as done"
+```
+
+Run `task examples` for more worked sequences.