pi-ui-extend 1.0.38 → 1.0.40

package/docs/desktop-task-manager.md

@@ -0,0 +1,124 @@
+# Spec: Desktop Project Task Manager
+
+## Type
+
+Change
+
+## Goal
+
+Add a project-scoped task list to Pix Desktop in a persistent left sidebar and
+allow a saved task to start work immediately in a new session tab.
+
+## Scope
+
+- A collapsible, resizable left sidebar with `Tasks` and `Project` tabs.
+- A compact task list with create, edit, delete, filtering, and manual status
+  changes.
+- Task type (`bug`, `feature`, `improvement`), status (`backlog`, `todo`,
+  `in-progress`, `done`), and priority (`low`, `medium`, `high`, `urgent`).
+- Project-local persistence in `.pi/tasks.json` with a versioned schema.
+- Starting a task in a new ACP session, automatically sending a generated
+  prompt, marking the task in progress, and storing the new session id.
+- Opening an already-linked session instead of creating a duplicate.
+
+## Non-goals
+
+- Kanban, drag and drop, subtasks, dependencies, assignees, due dates,
+  comments, or task history.
+- Automatic transition to `done` when an agent turn finishes.
+- Synchronizing the project task file with the agent's session-local todo list.
+- Concurrent multi-window file merging.
+
+## Behavior
+
+1. The sidebar is visible below the title/session chrome, starts on `Tasks`,
+   remembers its width and collapsed state locally, and preserves the main
+   session workspace at narrow window sizes.
+2. Task rows show a title, type, status, priority, and actions. Status and
+   priority are communicated by a Lucide icon, text, and color so meaning never
+   depends on color alone. `done` is green, `in-progress` is yellow, and idle
+   states are neutral; all colors support light and dark themes.
+3. Creating or editing validates a non-empty title. A description is optional.
+4. Filters affect only the visible list and do not modify persisted ordering.
+5. A missing `.pi/tasks.json` is treated as an empty version-1 document.
+6. Starting an unlinked task creates and selects a new ACP session, persists
+   its id and `in-progress` status, appends the generated user prompt to the
+   transcript, and sends it immediately.
+7. Starting a linked task loads that session. A missing/stale linked session is
+   reported as a recoverable error and does not silently create another one.
+8. Task completion remains manual.
+
+## Contracts
+
+- Project file: `.pi/tasks.json` containing `{ version: 1, tasks: [...] }`.
+- Every task has a unique id, title, type, status, priority, `createdAt`, and
+  `updatedAt`; description and `sessionId` may be omitted.
+- Tauri exposes narrow read/write commands for this one file. Workspace paths
+  are validated and `.pi` symlinks may not escape the workspace.
+- The webview sends a complete validated document on each mutation. Writes use
+  a same-directory temporary file and replacement to avoid partial JSON.
+
+## Invariants
+
+- The task document version must be supported before it is displayed or saved.
+- Duplicate ids, unknown enum values, empty titles, and malformed timestamps
+  are rejected.
+- A task is linked to at most one session in this MVP.
+- Starting a task is disabled while another prompt/session operation is active.
+- A failed save does not leave the UI claiming a task state that was not
+  persisted.
+
+## Edge cases
+
+- Switching workspaces discards the previous workspace's in-memory task view
+  and loads the new project file.
+- Empty and missing files have distinct behavior: missing means no tasks;
+  malformed or empty JSON is an error.
+- Save, session creation, and prompt failures remain visible and retryable.
+- Collapsing the sidebar keeps its tab rail available; choosing a tab expands
+  it.
+
+## Related files
+
+- `desktop/src/App.svelte`
+- `desktop/src/components/`
+- `desktop/src/lib/`
+- `desktop/src/styles.css`
+- `desktop/src-tauri/src/lib.rs`
+
+## Verification
+
+- Unit tests for task parsing, validation, filtering, prompt generation, and
+  sidebar preference parsing.
+- Rust tests for missing/read/write/malformed files and workspace escape.
+- `npm --prefix desktop test`
+- `npm --prefix desktop run check`
+- `npm --prefix desktop run build:web`
+- `cargo test --manifest-path desktop/src-tauri/Cargo.toml`
+
+## Risks / unknowns
+
+- Whole-document writes assume one active desktop writer per project.
+- A linked session may later be removed outside Pix Desktop; the first version
+  reports this rather than automatically unlinking it.
+- Windows replacement semantics may require a fallback around replacing an
+  existing task file while retaining best-effort crash safety.
+
+## Evidence
+
+- Confirmed by code: desktop session creation/loading and prompt submission are
+  orchestrated in `desktop/src/App.svelte` through `AcpClient`.
+- Confirmed by code: Tauri already validates workspace-contained project file
+  reads in `desktop/src-tauri/src/lib.rs`.
+- Confirmed by tests: session tab ordering and ACP request behavior have focused
+  Vitest coverage under `desktop/src/lib/`.
+- Confirmed by docs: `DESIGN.md` specifies a compact persistent sidebar,
+  semantic theme roles, Lucide icons, and non-color status cues.
+- Implemented: `.pi/tasks.json` now has an explicit version-1 contract and
+  rejects unsupported versions rather than guessing a migration.
+- Verified by tests: all 82 desktop Vitest tests and all 8 Rust tests pass;
+  Svelte/TypeScript checks report no errors or warnings.
+- Verified visually: browser QA covered clean preference state, resize/collapse,
+  tabs, filters, and semantic colors in light/dark themes.
+- Verified natively: actual Tauri UI/backend CRUD, Run, persisted linkage,
+  Open session without duplication, and delete cleanup all passed.

package/external/pi-tools-suite/README.md

@@ -188,9 +188,28 @@ Install the language servers used by the bundled example config. The commands be
 # TypeScript / JavaScript
 npm install -g typescript typescript-language-server
 
+# Svelte
+npm install -g svelte-language-server
+
+# Vue
+npm install -g @vue/language-server
+
 # Python
 python3 -m pip install --user python-lsp-server
 
+# Go
+go install golang.org/x/tools/gopls@latest
+
+# C / C++ (clangd)
+brew install llvm
+# or use your distro's clangd package: apt install clangd, dnf install clang-tools-extra, ...
+
+# Lua
+brew install lua-language-server
+
+# Bash
+npm install -g bash-language-server
+
 # C# / Unity
 dotnet tool install -g Microsoft.CodeAnalysis.LanguageServer
 
@@ -252,6 +271,160 @@ Minimal shared config shape:
 
 Project-local overrides can be added in `.pi/pi-tools-suite.jsonc`; pi-tools-suite asks for trust before using project-local LSP binaries.
 
+### Popular language-server examples
+
+Copy the entries you need into `lsp.servers` of the shared config. Values mirror the commented templates shipped in the generated config file; where they disagree, the generated file is authoritative. Both diagnostics modes are on by default: servers that support pull diagnostics (`textDocument/diagnostic`) are queried directly, and push diagnostics (`publishDiagnostics`) are awaited for every server — `pullDiagnostics: false` / `waitForPublishDiagnostics: false` disable either side explicitly. Servers start lazily: one spawns only after a mutating tool (Edit/Write/ast-grep/apply_patch) touches a file matching `include`, and diagnostics land in that tool's result.
+
+```jsonc
+{
+  "lsp": {
+    "servers": [
+      // Svelte (verified with svelte-language-server): compiler + embedded TS/JS diagnostics
+      {
+        "id": "svelte",
+        "include": ["**/*.svelte"],
+        "exclude": ["**/node_modules/**"],
+        "rootMarkers": ["svelte.config.js", "package.json"],
+        "bin": "svelteserver",
+        "args": ["--stdio"],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": { ".svelte": "svelte" }
+      },
+      // Vue (Volar)
+      {
+        "id": "vue",
+        "include": ["**/*.vue"],
+        "exclude": ["**/node_modules/**"],
+        "rootMarkers": ["package.json"],
+        "bin": "vue-language-server",
+        "args": ["--stdio"],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": { ".vue": "vue" }
+      },
+      // Python (python-lsp-server)
+      {
+        "id": "python",
+        "include": ["**/*.py", "**/*.pyi"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/__pycache__/**", "**/.venv/**", "**/venv/**", "**/.tox/**", "**/.mypy_cache/**", "**/.ruff_cache/**"],
+        "rootMarkers": ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "poetry.lock", ".git"],
+        "bin": "pylsp",
+        "args": [],
+        "languageIdByExtension": { ".py": "python", ".pyi": "python" }
+      },
+      // Go (gopls, push diagnostics)
+      {
+        "id": "go",
+        "include": ["**/*.go"],
+        "exclude": ["**/.git/**", "**/vendor/**"],
+        "rootMarkers": ["go.mod", ".git"],
+        "bin": "gopls",
+        "args": [],
+        "startupTimeoutMs": 20000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": { ".go": "go" }
+      },
+      // Rust (rust-analyzer, push diagnostics)
+      {
+        "id": "rust",
+        "include": ["**/*.rs"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/target/**"],
+        "rootMarkers": ["Cargo.toml", "rust-project.json", ".git"],
+        "bin": "rust-analyzer",
+        "args": [],
+        "startupTimeoutMs": 20000,
+        "diagnosticsWaitMs": 20000,
+        "pullDiagnostics": false,
+        "waitForPublishDiagnostics": true,
+        "languageIdByExtension": { ".rs": "rust" }
+      },
+      // C / C++ (clangd, push diagnostics)
+      {
+        "id": "clangd",
+        "include": ["**/*.c", "**/*.cc", "**/*.cpp", "**/*.cxx", "**/*.h", "**/*.hh", "**/*.hpp"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": ["compile_commands.json", "CMakeLists.txt", "Makefile", ".clang-format", ".git"],
+        "bin": "clangd",
+        "args": [],
+        "startupTimeoutMs": 20000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": {
+          ".c": "c", ".cc": "cpp", ".cpp": "cpp", ".cxx": "cpp",
+          ".h": "c", ".hh": "cpp", ".hpp": "cpp"
+        }
+      },
+      // C# / Unity (Roslyn)
+      {
+        "id": "csharp",
+        "include": ["**/*.cs", "**/*.csx"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/bin/**", "**/obj/**", "**/.vs/**", "**/Library/**", "**/Temp/**", "**/Logs/**"],
+        "rootMarkers": ["*.sln", "*.csproj", "global.json", "Directory.Build.props", "Directory.Packages.props", "Packages/manifest.json", "ProjectSettings/ProjectVersion.txt", ".git"],
+        "bin": "~/.dotnet/tools/roslyn-language-server",
+        "args": ["--stdio", "--autoLoadProjects", "--logLevel", "Error"],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 15000,
+        "languageIdByExtension": { ".cs": "csharp", ".csx": "csharp" }
+      },
+      // Ruby
+      {
+        "id": "ruby",
+        "include": ["**/*.rb", "**/*.rake", "**/Gemfile", "**/Rakefile", "**/*.gemspec"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/vendor/bundle/**", "**/.bundle/**", "**/tmp/**", "**/log/**"],
+        "rootMarkers": ["Gemfile.lock", "*.gemspec", "Rakefile", ".ruby-version", ".git"],
+        "bin": "ruby-lsp",
+        "args": [],
+        "startupTimeoutMs": 60000,
+        "diagnosticsWaitMs": 10000,
+        "languageIdByExtension": { ".rb": "ruby", ".rake": "ruby", ".gemspec": "ruby" }
+      },
+      // Lua (lua-language-server)
+      {
+        "id": "lua",
+        "include": ["**/*.lua"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": [".luarc.json", ".git"],
+        "bin": "lua-language-server",
+        "args": [],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 6000,
+        "languageIdByExtension": { ".lua": "lua" }
+      },
+      // Bash
+      {
+        "id": "bash",
+        "include": ["**/*.sh", "**/*.bash"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": [".git"],
+        "bin": "bash-language-server",
+        "args": ["start"],
+        "startupTimeoutMs": 15000,
+        "diagnosticsWaitMs": 5000,
+        "languageIdByExtension": { ".sh": "shellscript", ".bash": "shellscript" }
+      },
+      // Markdown (link validation settings ship in the generated config template)
+      {
+        "id": "markdown",
+        "include": ["**/*.md", "**/*.markdown", "**/*.mdown", "**/*.mkd", "**/*.mmd"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": [".git", "package.json", "README.md"],
+        "bin": "vscode-markdown-language-server",
+        "args": ["--stdio"],
+        "startupTimeoutMs": 15000,
+        "diagnosticsWaitMs": 5000,
+        "languageIdByExtension": { ".md": "markdown", ".markdown": "markdown", ".mdown": "markdown", ".mkd": "markdown", ".mmd": "markdown" }
+      }
+    ]
+  }
+}
+```
+
+Notes:
+
+- Svelte resolves `svelte` and `typescript` from the workspace `node_modules`, so project-local versions win; `.svelte.js`/`.svelte.ts` runes modules are not covered because their extensions collide with the TypeScript server.
+- Vue requires `@vue/language-server` v2+ (the `vue-language-server` binary) plus the workspace's `vue` package for template type-checking.
+- The full commented templates (including GDScript via a headless Godot wrapper and the complete Markdown link-validation `settings`) are written to the shared config file on first run.
+
 ## Async sub-agents
 
 Sub-agent model routing normally follows task overrides, subagent type config, then `ASYNC_SUBAGENTS_MODEL` / `PI_SUBAGENTS_MODEL` fallbacks. Set `ASYNC_SUBAGENTS_FORCE_CURRENT_MODEL=1` (or `PI_SUBAGENTS_FORCE_CURRENT_MODEL=1`) to ignore task/config/env model choices and launch every sub-agent with the current parent session model. When this flag is enabled, any `--model` entries in sub-agent extra args are stripped so they cannot override the current model.
@@ -520,6 +693,40 @@ npm run test:prompt-evals:dcp
 
 The default live model is `zai/glm-5-turbo`. Override it for the whole suite with `PI_TOOLS_SUITE_E2E_MODEL=provider/model`, or use the existing component variables such as `TOOL_SELECTION_E2E_MODEL`, `ASYNC_SUBAGENTS_MODEL`, `ASYNC_SUBAGENTS_ROUTING_E2E_MODEL`, and `DCP_SUMMARY_E2E_MODEL`. The normal deterministic coverage remains `npm test`; run prompt evals after changing tool descriptions, routing/classifier prompts, DCP summary prompts, or the default evaluation model.
 
+### Unified eval harness
+
+`test/evals/` adds a shared deterministic + live-model eval layer. The coverage
+gate requires every registered extension and model-facing tool to have a
+deterministic contract. The initial live corpus contains 20 cases across tool
+selection, coding quality, orchestration/escalation, and negative overuse
+controls. Coding-quality fixtures use executable behavioral checks rather than
+an LLM judge, while reports compare parent/worker tokens, provider-reported cost,
+tool calls, changed files, and elapsed time.
+
+```bash
+# Deterministic coverage/contract gate only
+npm run test:evals:contracts
+
+# Live matrix as Bun tests. Models are comma/semicolon separated.
+PI_TOOLS_SUITE_EVAL_MODELS='zai/glm-5.3,openai-codex/gpt-5.6-luna,openai-codex/gpt-5.6-terra,openai-codex/gpt-5.6-sol' \
+  npm run test:evals:live
+
+# Produce JSON + Markdown comparison artifacts.
+PI_TOOLS_SUITE_EVAL_MODELS='zai/glm-5.3,openai-codex/gpt-5.6-terra,openai-codex/gpt-5.6-sol' \
+  npm run evals:report
+
+# Focus the report runner when iterating
+PI_TOOLS_SUITE_EVAL_MODELS='zai/glm-5.3' \
+PI_TOOLS_SUITE_EVAL_CATEGORIES='coding-quality,negative' \
+  npm run evals:report
+```
+
+Live evals are opt-in. The deterministic coverage registry is part of normal
+tests, so adding an extension or tool without eval coverage fails the gate. See
+[`docs/evals.md`](docs/evals.md) for the architecture, complete 20-case catalog,
+fixtures, assertions, metrics, model matrix, report format, environment
+variables, CI recommendations, and the procedure for adding new evals.
+
 Supporting docs and historical standalone README content are kept in `docs/`; third-party license texts are kept in `licenses/`.
 
 ## SDK pin