From f1448c3a0af87adcb7b49f7d4c59e8087efd2730 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Fri, 27 Feb 2026 08:19:23 -0700 Subject: [PATCH 1/5] Add .preflight/ example config directory with config.yml, triage.yml, and contracts The README references .preflight/ config extensively but there were no concrete example files to copy. This adds a ready-to-use examples/.preflight/ directory with annotated config.yml, triage.yml, and contracts/api.yml, plus a README explaining how to use them. --- README.md | 6 ++++ examples/.preflight/README.md | 25 ++++++++++++++ examples/.preflight/config.yml | 29 +++++++++++++++++ examples/.preflight/contracts/api.yml | 47 +++++++++++++++++++++++++++ examples/.preflight/triage.yml | 38 ++++++++++++++++++++++ 5 files changed, 145 insertions(+) create mode 100644 examples/.preflight/README.md create mode 100644 examples/.preflight/config.yml create mode 100644 examples/.preflight/contracts/api.yml create mode 100644 examples/.preflight/triage.yml diff --git a/README.md b/README.md index f60fefa..cb437d8 100644 --- a/README.md +++ b/README.md @@ -406,6 +406,12 @@ This prevents the common failure mode: changing a shared type in one service and ## Configuration Reference +> **Want a ready-to-use starting point?** Copy the example configs: +> ```bash +> cp -r examples/.preflight /path/to/your/project/ +> ``` +> See [`examples/.preflight/README.md`](examples/.preflight/README.md) for details. + ### `.preflight/config.yml` Drop this in your project root. Every field is optional — defaults are sensible. diff --git a/examples/.preflight/README.md b/examples/.preflight/README.md new file mode 100644 index 0000000..b8aaf8c --- /dev/null +++ b/examples/.preflight/README.md @@ -0,0 +1,25 @@ +# `.preflight/` Example Config + +Copy this directory into your project root to configure preflight: + +```bash +cp -r examples/.preflight /path/to/your/project/ +``` + +## Files + +| File | Purpose | +|------|---------| +| `config.yml` | Main config — profile, related projects, thresholds, embeddings | +| `triage.yml` | Triage rules — which keywords trigger which classification level | +| `contracts/*.yml` | Manual contract definitions — supplement auto-extraction | + +## Quick Setup + +1. Copy the directory: `cp -r examples/.preflight ./` +2. Edit `config.yml` — set your `related_projects` paths +3. Edit `triage.yml` — add your domain-specific keywords to `always_check` +4. Optionally add contracts in `contracts/` for planned or external APIs +5. Commit `.preflight/` to your repo so your team shares the same config + +All fields are optional. Defaults work well out of the box — only customize what you need. diff --git a/examples/.preflight/config.yml b/examples/.preflight/config.yml new file mode 100644 index 0000000..0ad12e8 --- /dev/null +++ b/examples/.preflight/config.yml @@ -0,0 +1,29 @@ +# .preflight/config.yml — drop this in your project root +# All fields are optional. Defaults are sensible. +# See: https://github.com/TerminalGravity/preflight#configuration-reference + +# Profile controls overall verbosity +# "minimal" — only flag ambiguous+, skip clarification detail +# "standard" — default behavior +# "full" — maximum detail on every non-trivial prompt +profile: standard + +# Related projects for cross-service awareness +# Preflight will search these projects' indexes when your prompt +# touches shared contracts (types, routes, schemas). +related_projects: + # - path: /absolute/path/to/auth-service + # alias: auth-service + # - path: /absolute/path/to/shared-types + # alias: shared-types + +# Behavioral thresholds +thresholds: + session_stale_minutes: 30 # warn if no activity for this long + max_tool_calls_before_checkpoint: 100 # suggest checkpoint after N tool calls + correction_pattern_threshold: 3 # min corrections before forming a pattern + +# Embedding configuration +embeddings: + provider: local # "local" (Xenova, zero config) or "openai" + # openai_api_key: sk-... # only needed if provider is "openai" diff --git a/examples/.preflight/contracts/api.yml b/examples/.preflight/contracts/api.yml new file mode 100644 index 0000000..754c5da --- /dev/null +++ b/examples/.preflight/contracts/api.yml @@ -0,0 +1,47 @@ +# .preflight/contracts/api.yml — manual contract definitions +# These supplement auto-extracted contracts from your codebase. +# Manual definitions win on name conflicts with auto-extracted ones. +# +# Use this when: +# - You have contracts that aren't in code yet (planned APIs) +# - Auto-extraction misses something important +# - You want to document cross-service agreements explicitly + +- name: User + kind: interface + description: Core user object shared across services + fields: + - name: id + type: string + required: true + - name: email + type: string + required: true + - name: role + type: "'admin' | 'member' | 'viewer'" + required: true + - name: createdAt + type: Date + required: true + +- name: "POST /api/users" + kind: route + description: Create a new user account + fields: + - name: body + type: "{ email: string, role: string }" + required: true + - name: response + type: "{ user: User, token: string }" + required: true + +- name: "GET /api/users/:id" + kind: route + description: Fetch user by ID + fields: + - name: params + type: "{ id: string }" + required: true + - name: response + type: User + required: true diff --git a/examples/.preflight/triage.yml b/examples/.preflight/triage.yml new file mode 100644 index 0000000..22b05d3 --- /dev/null +++ b/examples/.preflight/triage.yml @@ -0,0 +1,38 @@ +# .preflight/triage.yml — controls the triage classification engine +# Customize which prompts get flagged, skipped, or escalated. + +rules: + # Prompts containing these words → always at least AMBIGUOUS + # Add domain terms that are too vague without context + always_check: + - rewards + - permissions + - migration + - schema + # - billing # uncomment for your domain + # - onboarding + + # Prompts containing these words → TRIVIAL (pass through immediately) + # Common low-risk commands that don't need analysis + skip: + - commit + - format + - lint + - "git status" + - "git log" + + # Prompts containing these words → CROSS-SERVICE + # Triggers search across related_projects defined in config.yml + cross_service_keywords: + - auth + - notification + - event + - webhook + # - payment + # - analytics + +# How aggressively to classify +# "relaxed" — more prompts pass as clear (faster, less interruption) +# "standard" — balanced (recommended) +# "strict" — more prompts flagged as ambiguous (thorough, more interruptions) +strictness: standard From be8beb39203419d6a8037f9f7c2be8e48a137571 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Fri, 27 Feb 2026 11:08:20 -0700 Subject: [PATCH 2/5] Add concrete usage examples for all major tools Created examples/USAGE_EXAMPLES.md with 8 real-world scenarios showing what each tool looks like in practice: preflight_check catching vague prompts, scope_work creating execution plans, enrich_agent_task for sub-agents, sharpen_followup resolving ambiguity, session health checks, semantic history search, weekly scorecards, and prompt grading. Added link to usage examples in README nav bar. --- README.md | 2 +- examples/USAGE_EXAMPLES.md | 205 +++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 examples/USAGE_EXAMPLES.md diff --git a/README.md b/README.md index cb437d8..e23927b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ A 24-tool MCP server for Claude Code that catches ambiguous instructions before [![npm](https://img.shields.io/npm/v/preflight-dev)](https://www.npmjs.com/package/preflight-dev) [![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/) -[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard) +[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Usage Examples](examples/USAGE_EXAMPLES.md) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard) diff --git a/examples/USAGE_EXAMPLES.md b/examples/USAGE_EXAMPLES.md new file mode 100644 index 0000000..55a2100 --- /dev/null +++ b/examples/USAGE_EXAMPLES.md @@ -0,0 +1,205 @@ +# Usage Examples + +Real-world examples of preflight tools in action inside Claude Code. + +--- + +## 1. Catching a Vague Prompt with `preflight_check` + +You type this into Claude Code: + +``` +fix the login bug +``` + +Preflight intercepts and returns: + +``` +⚠️ Ambiguity detected — routing to clarify_intent + +I found 3 potential login issues: + 1. JWT token not refreshing on expiry (src/auth/jwt.ts:42) + 2. OAuth callback returning 404 after redirect (src/auth/oauth.ts:118) + 3. "Remember me" checkbox not persisting session (src/components/LoginForm.tsx:23) + +Which one? Or describe the symptoms and I'll narrow it down. +``` + +Instead of Claude guessing and editing the wrong file, you get a targeted question. One round-trip instead of three. + +--- + +## 2. Scoping Work Before Coding with `scope_work` + +``` +> scope_work "Add rate limiting to the /api/upload endpoint" + +📋 Execution Plan +───────────────── +Goal: Add rate limiting to POST /api/upload + +Files to touch: + - src/api/routes/upload.ts (add middleware) + - src/middleware/rateLimit.ts (create) + - src/config/limits.ts (add upload limits) + - tests/api/upload.test.ts (add rate limit tests) + +Dependencies: + - Check if express-rate-limit is already installed + - Review existing middleware chain in src/api/index.ts + +Risks: + - Existing upload tests may break if rate limit hits in CI + - Need to decide: per-IP or per-user limiting? + +Estimated scope: ~120 lines across 4 files +``` + +--- + +## 3. Enriching a Sub-Agent Task with `enrich_agent_task` + +You want to spawn a sub-agent for a refactor: + +``` +> enrich_agent_task "refactor the database queries to use the new ORM" + +📦 Enriched Task Brief +────────────────────── +Original: "refactor the database queries to use the new ORM" + +Context added: + - ORM: Drizzle (see drizzle.config.ts, src/db/schema.ts) + - 14 files with raw SQL queries (grep results attached) + - Existing patterns: src/db/queries/users.ts uses query builder already + - Related contracts: UserRecord, PostRecord types in src/types/db.ts + - Test coverage: 8/14 query files have corresponding tests + +Suggested task for sub-agent: + "Refactor raw SQL queries in src/db/queries/ to use Drizzle ORM. + Follow the pattern in src/db/queries/users.ts. Schema is in + src/db/schema.ts. Run `npm test -- --grep db` after each file. + 14 files total — see list below." +``` + +The sub-agent gets everything it needs instead of fumbling through the codebase. + +--- + +## 4. Resolving Vague Follow-ups with `sharpen_followup` + +After Claude fixes a bug, you say: + +``` +> do the same for the others +``` + +Without preflight, Claude guesses what "the others" means. With it: + +``` +> sharpen_followup "do the same for the others" + +🔍 Resolved "the others" from conversation context: + +You just fixed a missing null check in src/api/users.ts:34. +Similar pattern found in 4 other files: + 1. src/api/posts.ts:28 — same nullable field access + 2. src/api/comments.ts:41 — same pattern + 3. src/api/teams.ts:55 — same pattern + 4. src/api/billing.ts:19 — slightly different (optional chain exists but incomplete) + +Shall I apply the fix to all 4? +``` + +--- + +## 5. Checking Session Health with `check_session_health` + +``` +> check_session_health + +🏥 Session Health +───────────────── +⏱ Session duration: 47 min +📝 Uncommitted files: 8 (⚠️ commit soon) +🔄 Last commit: 38 min ago (⚠️ overdue) +💬 Turn count: 23 +📊 Context usage: ~62% (healthy) +🎯 Focus score: B (2 directory switches) + +Recommendation: Commit your current changes before continuing. +Run `checkpoint` to save state. +``` + +--- + +## 6. Searching Past Sessions with `search_history` + +``` +> search_history "how did we handle the Stripe webhook retry logic" + +🔍 Found 3 relevant results across 2 sessions: + +Session 2024-12-15 (confidence: 0.92) + "Implemented exponential backoff for Stripe webhook retries + in src/webhooks/stripe.ts. Uses 3 retries with 1s/4s/16s delays. + Idempotency key stored in Redis." + +Session 2024-11-28 (confidence: 0.78) + "Discussed webhook retry strategies. Decided against queue-based + approach due to infrastructure complexity. Went with in-process + retry with circuit breaker." +``` + +Never re-research decisions you already made. + +--- + +## 7. Getting a Scorecard with `generate_scorecard` + +``` +> generate_scorecard type=trend period=week + +📊 Weekly Trend — Jan 20–26, 2025 +────────────────────────────────── +Overall: B+ (78/100) ↑ from B (74) last week + +Improving: + ✅ Clarification: 82 → 89 (+7) — more file refs in prompts + ✅ Verification: 65 → 78 (+13) — running tests before done + +Declining: + ⚠️ Compaction Mgmt: 71 → 58 (-13) — 3 compactions without prior commit + ⚠️ Session Lifecycle: 80 → 72 (-8) — longer gaps between commits + +Top tip: Run `checkpoint` before long exploratory conversations +to avoid losing work on compaction. +``` + +--- + +## 8. Quick Prompt Grading with `prompt_score` + +``` +> prompt_score "update the thing" + +📝 Prompt Score: D (32/100) +─────────────────────────── +Specificity: F — no file, function, or component named +Scope: F — "the thing" is completely ambiguous +Actionability: D — "update" is vague (add? change? remove?) +Done-condition: F — no way to verify completion + +Try: "Update the user avatar upload handler in src/api/users.ts +to accept WebP format and add a test case" → A (94/100) +``` + +--- + +## Tips + +- **Start every session** with `preflight_check` on your first prompt — it'll route to the right tool automatically +- **Use `checkpoint`** every 20–30 minutes or before exploring a new direction +- **Run `search_history`** before implementing something — you may have solved it before +- **Check `session_stats`** at the end of a session to spot waste patterns +- **Set up `.preflight/config.yml`** to tune thresholds for your team (see [examples/.preflight/](/.preflight/)) From 251807612db92f64ed1f883657fa8e1c3bec0103 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Sat, 28 Feb 2026 11:55:35 -0700 Subject: [PATCH 3/5] docs: add troubleshooting FAQ section to README --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/README.md b/README.md index e23927b..8a71843 100644 --- a/README.md +++ b/README.md @@ -606,6 +606,78 @@ src/ └── ... # One file per tool ``` +## Troubleshooting + +### Tools don't show up in Claude Code + +**Symptom:** You added the MCP config but Claude doesn't see any preflight tools. + +1. Make sure you restarted Claude Code after editing `.mcp.json` +2. Check the path in your config is absolute, not relative — `npx tsx /Users/you/preflight/src/index.ts` +3. Run the server directly to check for startup errors: + ```bash + npx tsx /path/to/preflight/src/index.ts + ``` + If it crashes on startup, the error will tell you what's missing. + +### LanceDB / timeline search not working + +**Symptom:** `search_timeline` returns empty results or errors about the database. + +- LanceDB stores data in `~/.preflight/projects//timeline.lance/` +- You need to **ingest sessions first** — run `preflight_onboard_project` with your project dir, or use the CLI: `preflight-dev init` +- If you get native module errors, make sure your Node version matches your OS architecture (especially on Apple Silicon — don't use x64 Node via Rosetta) +- To reset a corrupt database, delete the `.lance` directory and re-ingest: + ```bash + rm -rf ~/.preflight/projects/YOUR_PROJECT/timeline.lance + ``` + +### `CLAUDE_PROJECT_DIR` not set + +**Symptom:** Tools that need project context (contracts, file search) return nothing useful. + +Set it in your `.mcp.json` env block: +```json +"env": { + "CLAUDE_PROJECT_DIR": "/absolute/path/to/your/project" +} +``` +Or export it before running Claude Code: +```bash +export CLAUDE_PROJECT_DIR=/path/to/your/project +claude +``` + +### `preflight_check` says everything is "TRIVIAL" + +This is by design for short, unambiguous commands like `git status` or `ls`. The triage engine only flags prompts that are genuinely ambiguous. If you want stricter checking, add keywords to `always_check` in `.preflight/triage.yml`: + +```yaml +always_check: + - refactor + - update + - change +``` + +### npm global install: `preflight-dev: command not found` + +After `npm install -g preflight-dev`, your shell may not see the new binary. Try: +```bash +# Check where npm puts global bins +npm bin -g +# Make sure that directory is in your PATH +export PATH="$(npm bin -g):$PATH" +``` + +### High memory usage during session ingestion + +Large JSONL session files (100MB+) can spike memory. Set `NODE_OPTIONS` to increase the heap: +```bash +NODE_OPTIONS="--max-old-space-size=4096" npx tsx src/index.ts +``` + +--- + ## License MIT — do whatever you want with it. From cdc9e10185f92740d7988243730b628c9019f334 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Sat, 28 Feb 2026 15:14:57 -0700 Subject: [PATCH 4/5] fix: extractText bug in estimate-cost + add test coverage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fixed extractText to filter by b.type === 'text' (was counting tool_use blocks as text tokens, inflating estimates) - Exported analyzeSessionFile and SessionAnalysis for testability - Added 7 tests covering: token counting, correction detection, tool call counting, preflight tool tracking, content block filtering, tool_result handling, malformed input, and epoch timestamps - Test count: 43 → 50 --- src/tools/estimate-cost.ts | 6 +- tests/tools/estimate-cost.test.ts | 140 ++++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+), 3 deletions(-) create mode 100644 tests/tools/estimate-cost.test.ts diff --git a/src/tools/estimate-cost.ts b/src/tools/estimate-cost.ts index 327491a..d8ae313 100644 --- a/src/tools/estimate-cost.ts +++ b/src/tools/estimate-cost.ts @@ -39,7 +39,7 @@ function extractText(content: unknown): string { if (typeof content === "string") return content; if (Array.isArray(content)) { return content - .filter((b: any) => typeof b.text === "string") + .filter((b: any) => b.type === "text" && typeof b.text === "string") .map((b: any) => b.text) .join("\n"); } @@ -72,7 +72,7 @@ function formatDuration(ms: number): string { return `${hours}h ${rem}m`; } -interface SessionAnalysis { +export interface SessionAnalysis { inputTokens: number; outputTokens: number; promptCount: number; @@ -85,7 +85,7 @@ interface SessionAnalysis { lastTimestamp: string | null; } -function analyzeSessionFile(filePath: string): SessionAnalysis { +export function analyzeSessionFile(filePath: string): SessionAnalysis { const content = readFileSync(filePath, "utf-8"); const lines = content.trim().split("\n").filter(Boolean); diff --git a/tests/tools/estimate-cost.test.ts b/tests/tools/estimate-cost.test.ts new file mode 100644 index 0000000..a5c5e91 --- /dev/null +++ b/tests/tools/estimate-cost.test.ts @@ -0,0 +1,140 @@ +import { describe, it, expect, beforeEach, afterEach } from "vitest"; +import { writeFileSync, mkdirSync, rmSync } from "fs"; +import { join } from "path"; +import { tmpdir } from "os"; +import { analyzeSessionFile } from "../../src/tools/estimate-cost.js"; + +const TMP = join(tmpdir(), "preflight-estimate-cost-test"); + +function jsonl(...lines: object[]): string { + return lines.map((l) => JSON.stringify(l)).join("\n"); +} + +beforeEach(() => mkdirSync(TMP, { recursive: true })); +afterEach(() => rmSync(TMP, { recursive: true, force: true })); + +describe("analyzeSessionFile", () => { + it("counts basic user/assistant tokens", () => { + const file = join(TMP, "session.jsonl"); + writeFileSync( + file, + jsonl( + { type: "user", message: { content: "Hello world" }, timestamp: "2025-01-01T00:00:00Z" }, + { type: "assistant", message: { content: "Hi there, how can I help?" }, timestamp: "2025-01-01T00:01:00Z" }, + ), + ); + + const result = analyzeSessionFile(file); + expect(result.promptCount).toBe(1); + expect(result.inputTokens).toBeGreaterThan(0); + expect(result.outputTokens).toBeGreaterThan(0); + expect(result.corrections).toBe(0); + expect(result.firstTimestamp).toBe("2025-01-01T00:00:00Z"); + expect(result.lastTimestamp).toBe("2025-01-01T00:01:00Z"); + }); + + it("detects corrections after assistant responses", () => { + const file = join(TMP, "session.jsonl"); + writeFileSync( + file, + jsonl( + { type: "user", message: { content: "Write a function" }, timestamp: "2025-01-01T00:00:00Z" }, + { type: "assistant", message: { content: "Here is a function that does X..." }, timestamp: "2025-01-01T00:01:00Z" }, + { type: "user", message: { content: "No, that's not what I meant. Try again." }, timestamp: "2025-01-01T00:02:00Z" }, + ), + ); + + const result = analyzeSessionFile(file); + expect(result.corrections).toBe(1); + expect(result.wastedOutputTokens).toBeGreaterThan(0); + }); + + it("counts tool calls in assistant content blocks", () => { + const file = join(TMP, "session.jsonl"); + writeFileSync( + file, + jsonl( + { + type: "assistant", + message: { + content: [ + { type: "text", text: "Let me check that." }, + { type: "tool_use", name: "Read", id: "t1", input: { path: "foo.ts" } }, + { type: "tool_use", name: "clarify_intent", id: "t2", input: { prompt: "test" } }, + ], + }, + timestamp: "2025-01-01T00:00:00Z", + }, + ), + ); + + const result = analyzeSessionFile(file); + expect(result.toolCallCount).toBe(2); + expect(result.preflightCalls).toBe(1); // clarify_intent is a preflight tool + expect(result.preflightTokens).toBeGreaterThan(0); + }); + + it("handles content block arrays for extractText (ignores non-text blocks)", () => { + const file = join(TMP, "session.jsonl"); + writeFileSync( + file, + jsonl( + { + type: "user", + message: { + content: [ + { type: "text", text: "Hello" }, + { type: "tool_use", name: "Read", id: "x", input: { path: "very/long/path/that/should/not/count/as/text/tokens" } }, + ], + }, + timestamp: "2025-01-01T00:00:00Z", + }, + ), + ); + + const result = analyzeSessionFile(file); + // Should only count "Hello" (5 chars → ~2 tokens), not the tool_use block + expect(result.inputTokens).toBeLessThan(10); + }); + + it("counts tool_result tokens as input", () => { + const file = join(TMP, "session.jsonl"); + writeFileSync( + file, + jsonl( + { + type: "tool_result", + content: "File contents here with some data", + tool_use_id: "t1", + timestamp: "2025-01-01T00:00:00Z", + }, + ), + ); + + const result = analyzeSessionFile(file); + expect(result.inputTokens).toBeGreaterThan(0); + }); + + it("handles empty/malformed lines gracefully", () => { + const file = join(TMP, "session.jsonl"); + writeFileSync(file, "not json\n\n{}\n" + JSON.stringify({ type: "user", message: { content: "hi" }, timestamp: "2025-01-01T00:00:00Z" }) + "\n"); + + const result = analyzeSessionFile(file); + expect(result.promptCount).toBe(1); + }); + + it("handles numeric epoch timestamps", () => { + const file = join(TMP, "session.jsonl"); + writeFileSync( + file, + jsonl( + { type: "user", message: { content: "test" }, timestamp: 1704067200 }, // epoch seconds + { type: "assistant", message: { content: "response" }, timestamp: 1704067200000 }, // epoch ms + ), + ); + + const result = analyzeSessionFile(file); + expect(result.firstTimestamp).toBeTruthy(); + expect(result.lastTimestamp).toBeTruthy(); + }); +}); From 952759638f12251af56f854deccd17788cdc0542 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Sat, 28 Feb 2026 15:44:44 -0700 Subject: [PATCH 5/5] test: add 20 tests for preflight_check triage integration Covers trivial/clear/ambiguous/cross-service/multi-step classification, skip/always_check keywords, strictness modes, edge cases (empty prompt, bullet lists, pronoun detection, vague verbs). --- tests/tools/preflight-check.test.ts | 141 ++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 tests/tools/preflight-check.test.ts diff --git a/tests/tools/preflight-check.test.ts b/tests/tools/preflight-check.test.ts new file mode 100644 index 0000000..e6e802d --- /dev/null +++ b/tests/tools/preflight-check.test.ts @@ -0,0 +1,141 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; + +/** + * Tests for preflight-check tool helper functions. + * + * We test the pure logic (extractFilePaths, buildSequenceSection, etc.) + * by importing from the source. The MCP registration itself is integration-level. + */ + +// Since the helpers are not exported, we test them via the triage system +// and through the tool's observable behavior. We also add targeted tests +// for the triage → preflight_check integration. + +import { triagePrompt, type TriageResult } from "../../src/lib/triage.js"; + +describe("preflight_check triage integration", () => { + it("trivial prompts pass through", () => { + const result = triagePrompt("commit"); + expect(result.level).toBe("trivial"); + expect(result.confidence).toBeGreaterThanOrEqual(0.9); + }); + + it("short vague prompts are ambiguous", () => { + const result = triagePrompt("fix the bug"); + expect(result.level).toBe("ambiguous"); + expect(result.reasons.some(r => /vague/i.test(r))).toBe(true); + }); + + it("prompts with file refs are clear", () => { + const result = triagePrompt("fix the null check in src/auth/jwt.ts line 42"); + expect(result.level).toBe("clear"); + expect(result.reasons.some(r => /file/i.test(r))).toBe(true); + }); + + it("multi-step prompts with 'then' are classified correctly", () => { + const result = triagePrompt("refactor the auth module then update all API consumers"); + expect(result.level).toBe("multi-step"); + }); + + it("multi-step prompts with numbered lists", () => { + const result = triagePrompt("Do these things:\n1) add login page\n2) add signup page\n3) add dashboard"); + expect(result.level).toBe("multi-step"); + }); + + it("cross-service detected with schema keyword", () => { + const result = triagePrompt("update the shared schema for user events", { + crossServiceKeywords: ["shared"], + }); + expect(result.level).toBe("cross-service"); + }); + + it("cross-service detected with related project alias", () => { + const result = triagePrompt("sync with rewards-api types", { + relatedAliases: ["rewards-api"], + }); + expect(result.level).toBe("cross-service"); + }); + + it("skip keywords override to trivial", () => { + const result = triagePrompt("just deploy it already", { + skip: ["just deploy"], + }); + expect(result.level).toBe("trivial"); + expect(result.confidence).toBe(0.95); + }); + + it("always_check keywords force ambiguous", () => { + const result = triagePrompt("migrate the database", { + alwaysCheck: ["migrate"], + }); + expect(result.level).toBe("ambiguous"); + }); + + it("strict mode adjusts clear confidence", () => { + const result = triagePrompt("add error handling to src/utils/parser.ts", { + strictness: "strict", + }); + expect(result.level).toBe("clear"); + expect(result.confidence).toBe(0.8); + }); + + it("pronoun-heavy prompts without file refs are ambiguous", () => { + const result = triagePrompt("fix it and update them"); + expect(result.level).toBe("multi-step"); // "and" splits into multi-step + }); + + it("vague pronoun alone triggers ambiguous", () => { + const result = triagePrompt("change it"); + expect(result.level).toBe("ambiguous"); + expect(result.reasons.some(r => /pronoun/i.test(r))).toBe(true); + }); + + it("detailed prompt without vague signals is clear", () => { + const result = triagePrompt("Add retry logic with exponential backoff to the HTTP client in src/lib/http.ts"); + expect(result.level).toBe("clear"); + }); + + it("multiple files in different directories triggers multi-step", () => { + const result = triagePrompt("update src/auth/login.ts and lib/utils/validate.ts"); + expect(result.level).toBe("multi-step"); + }); + + it("pattern match count boosts trivial to ambiguous", () => { + // This tests the config path — patternMatchCount isn't used in triagePrompt directly, + // but the preflight_check tool uses it. We verify triage alone stays trivial. + const result = triagePrompt("commit", { patternMatchCount: 3 }); + // patternMatchCount is not consumed by triagePrompt — that's handled by the tool layer + expect(result.level).toBe("trivial"); + }); + + it("returns recommended tools for ambiguous", () => { + const result = triagePrompt("fix the bug"); + expect(result.recommended_tools).toContain("clarify-intent"); + }); + + it("returns recommended tools for multi-step", () => { + const result = triagePrompt("first refactor auth then update tests"); + expect(result.recommended_tools).toContain("sequence-tasks"); + }); +}); + +describe("preflight_check edge cases", () => { + it("empty prompt is ambiguous", () => { + const result = triagePrompt(""); + expect(result.level).toBe("ambiguous"); + }); + + it("very long clear prompt has high confidence", () => { + const result = triagePrompt( + "Please add comprehensive input validation to the createUser function in src/controllers/user.ts " + + "including email format checking plus password strength validation" + ); + expect(result.level).toBe("clear"); + expect(result.confidence).toBeGreaterThanOrEqual(0.8); + }); + + it("bullet list triggers multi-step", () => { + const result = triagePrompt("Changes needed:\n- fix auth\n- update tests\n- deploy"); + expect(result.level).toBe("multi-step"); + }); +});