chore(ask): clean up ask tool prototype

2026-04-17 12:08:06 +02:00
parent 133a0548ba
commit a212997786
3 changed files with 279 additions and 48 deletions
@@ -0,0 +1,54 @@
+{
+	"editor.defaultFormatter": "esbenp.prettier-vscode",
+	"editor.formatOnPaste": true,
+	"editor.formatOnSave": true,
+	"emmet.showExpandedAbbreviation": "never",
+	"js/ts.tsdk.path": "node_modules/typescript/lib",
+	"js/ts.tsdk.promptToUseWorkspaceVersion": true,
+	"[css]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[graphql]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[html]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[javascript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[javascriptreact]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[json]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[jsonc]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[markdown]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[mdx]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[svelte]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescriptreact]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[vue]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[yaml]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"editor.codeActionsOnSave": {
+		"source.fixAll.biome": "explicit",
+		"source.organizeImports.biome": "explicit"
+	}
+}
@@ -1,50 +1,91 @@
 {
-  "format_on_save": "on",
-  "ensure_final_newline_on_save": true,
-  "remove_trailing_whitespace_on_save": true,
-  "languages": {
-    "TypeScript": {
-      "formatter": {
-        "external": {
-          "command": "pnpm",
-          "arguments": [
-            "exec",
-            "biome",
-            "format",
-            "--stdin-file-path",
-            "{buffer_path}"
-          ]
-        }
-      },
-      "hard_tabs": true
-    },
-    "JSON": {
-      "formatter": {
-        "external": {
-          "command": "pnpm",
-          "arguments": [
-            "exec",
-            "biome",
-            "format",
-            "--stdin-file-path",
-            "{buffer_path}"
-          ]
-        }
-      }
-    },
-    "JSONC": {
-      "formatter": {
-        "external": {
-          "command": "pnpm",
-          "arguments": [
-            "exec",
-            "biome",
-            "format",
-            "--stdin-file-path",
-            "{buffer_path}"
-          ]
-        }
-      }
-    }
-  }
+	"format_on_save": "on",
+	"ensure_final_newline_on_save": true,
+	"remove_trailing_whitespace_on_save": true,
+	"languages": {
+		"TypeScript": {
+			"formatter": {
+				"external": {
+					"command": "pnpm",
+					"arguments": [
+						"exec",
+						"biome",
+						"format",
+						"--stdin-file-path",
+						"{buffer_path}"
+					]
+				},
+				"language_server": {
+					"name": "biome"
+				}
+			},
+			"hard_tabs": true,
+			"code_actions_on_format": {
+				"source.fixAll.biome": true,
+				"source.organizeImports.biome": true
+			}
+		},
+		"JSON": {
+			"formatter": {
+				"external": {
+					"command": "pnpm",
+					"arguments": [
+						"exec",
+						"biome",
+						"format",
+						"--stdin-file-path",
+						"{buffer_path}"
+					]
+				}
+			}
+		},
+		"JSONC": {
+			"formatter": {
+				"external": {
+					"command": "pnpm",
+					"arguments": [
+						"exec",
+						"biome",
+						"format",
+						"--stdin-file-path",
+						"{buffer_path}"
+					]
+				}
+			}
+		},
+		"JavaScript": {
+			"code_actions_on_format": {
+				"source.fixAll.biome": true,
+				"source.organizeImports.biome": true
+			},
+			"formatter": {
+				"language_server": {
+					"name": "biome"
+				}
+			}
+		},
+		"TSX": {
+			"code_actions_on_format": {
+				"source.fixAll.biome": true,
+				"source.organizeImports.biome": true
+			},
+			"formatter": {
+				"language_server": {
+					"name": "biome"
+				}
+			}
+		}
+	},
+	"formatter": "language_server",
+	"lsp": {
+		"typescript-language-server": {
+			"settings": {
+				"typescript": {
+					"preferences": {
+						"includePackageJsonAutoImports": "on"
+					}
+				}
+			}
+		}
+	}
 }
@@ -0,0 +1,136 @@
+# AGENTS.md
+
+Guidance for agents working in this repository.
+
+## Project scope
+
+This repo builds a **pi.dev extension** that adds an `ask` / interview-style user question flow.
+
+Primary deliverables in this repo:
+
+- research and comparison docs:
+  - `RESEARCH.md`
+  - `FINDINGS.md`
+  - `SPEC.md`
+- TypeScript extension implementation in `src/`
+- tests for core logic in `tests/`
+
+## Key project goals
+
+When making changes, optimize for:
+
+1. **pi-native extension design**
+   - prefer `pi.registerTool()`
+   - prefer `ctx.ui.custom()` for complex interactive flows
+   - keep result shapes compatible with normal pi tool results
+
+2. **testable architecture**
+   - keep state and decision logic in plain TypeScript modules
+   - keep pi/TUI wiring thin
+   - prefer testing state transitions and serialization over testing terminal rendering details
+
+3. **research alignment**
+   - keep implementation consistent with `SPEC.md`
+   - if behavior changes materially, update `README.md` and `SPEC.md`
+   - if new harness findings are added, update `RESEARCH.md` and/or `FINDINGS.md`
+
+## Tech stack
+
+- TypeScript
+- pnpm
+- Biome
+- pi extension APIs from `@mariozechner/pi-coding-agent`
+- TUI components from `@mariozechner/pi-tui`
+- TypeBox for tool schemas
+
+## Commands
+
+Use these project commands:
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm format
+pnpm lint
+pnpm check
+```
+
+Notes:
+
+- `pnpm check` runs Biome write/check flow for this repo.
+- `pnpm test` runs the Node test runner against `tests/*.test.ts`.
+- the extension is intended to be loaded dynamically with:
+
+```bash
+pi -e ./src/index.ts
+```
+
+## File-specific guidance
+
+### `src/`
+
+- keep implementation in TypeScript only
+- preserve the separation between:
+  - schema/types
+  - state logic
+  - UI component logic
+  - tool registration
+- avoid introducing unnecessary framework abstractions
+- prefer small pure helper functions where possible
+
+### `tests/`
+
+- add or update tests when changing state behavior
+- prefer focused tests for:
+  - question normalization
+  - selection behavior
+  - tab movement
+  - custom answer submission
+  - result summarization
+  - cancellation behavior
+
+### docs
+
+Keep docs practical and synced with the implementation.
+
+- `README.md`: how to install, run, test, and use the tool
+- `SPEC.md`: intended design and UX contract
+- `RESEARCH.md`: harness comparison notes
+- `FINDINGS.md`: synthesized conclusions from source research
+
+## Coding expectations
+
+- follow Biome/Ultracite formatting and lint expectations
+- prefer explicit, readable code over clever code
+- use descriptive names
+- use early returns to keep control flow simple
+- avoid dead code and generic boilerplate comments
+- do not add React/JSX-specific patterns unless the repo actually starts using them
+
+## What to avoid
+
+- do not add unrelated framework guidance or dependencies
+- do not add browser/web UI unless the task explicitly requires it
+- do not hardcode machine-specific paths
+- do not weaken type safety just to silence errors
+- do not commit editor-specific files unless they are clearly project-useful
+
+## When changing behavior
+
+If you change the ask flow in a meaningful way, update the relevant docs in the same change:
+
+- user-facing usage changes -> `README.md`
+- architecture/contract changes -> `SPEC.md`
+- comparative harness findings -> `RESEARCH.md` / `FINDINGS.md`
+
+## Preferred workflow for agents
+
+1. read the relevant docs first
+2. inspect the existing implementation before refactoring
+3. make the smallest coherent change
+4. run:
+   - `pnpm format`
+   - `pnpm typecheck`
+   - `pnpm test`
+5. update docs if behavior or expectations changed