tokentrace 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.15.0] - 2026-05-22
+
+### Changed
+
+- Bumped minimum Node.js to 20.0.0 (Node 18 LTS reached end of life on 2025-04-30). This is a breaking change for users still on Node 18.
+- Upgraded `better-sqlite3` from 11 to 12 (latest major).
+- Upgraded `lucide-react` from 0.468 to 1.16 (first stable major release).
+- Upgraded `open` from 10 to 11 (now requires Node 20+, aligns with engines bump).
+- Bumped minor/patch versions for `tsx`, `postcss`, `autoprefixer`, `@types/react`, `@types/node`.
+
+### Fixed
+
+- `sqlite-history` adapter now uses SQLite identifier quoting (`""`) instead of `JSON.stringify()` when interpolating user table names into raw queries. Previously, a table name containing a quote could have caused a SQL parse error during read-only ingestion.
+- Made `eslint-plugin-react-hooks` an explicit devDependency so lint setup no longer relies on accidental dependency hoisting from `eslint-config-next`.
+- Raised global Vitest `testTimeout`/`hookTimeout` to 30s and bumped per-test/spawn timeouts in CLI subprocess tests (`mcp-server`, `serve-command`, `statusline-cli`) so they are no longer flaky under macOS process-spawn latency.
+
+### Documentation
+
+- Added a Troubleshooting section to the README covering the `prebuild-install` deprecation warning from `better-sqlite3`, native build errors, and `EBADENGINE` warnings.
+
+## [0.14.2] - 2026-05-21
+
+### Added
+
+- Added `get_agent_guide` to the MCP server with registry install snippets, recommended agent workflows, copy-paste `AGENTS.md` guidance, and local-first guardrails.
+- Added `tokentrace mcp selftest --json` to verify MCP initialization, tool listing, agent guide output, and scan-confirmation refusal without scanning files.
+- Added `docs/agent-adoption.md` with MCP setup instructions and evidence-backed recipes for coding agents.
+
+### Changed
+
+- MCP tool responses now include an agent-oriented envelope with summary, confidence, next actions, warnings, evidence hints, human-confirmation state, and the underlying data payload.
+- Package inspection and CLI smoke checks now verify the MCP agent guide, self-test, and adoption documentation.
+
+### Fixed
+
+- Data-backed CLI command help now prints before touching local runtime state, so `tokentrace scan --help`, `doctor --help`, `evidence --help`, `repair --help`, and related commands stay safe on broken or fresh local databases.
+
 ## [0.14.1] - 2026-05-20
 
 ### Fixed

package/README.md

@@ -105,6 +105,7 @@ or npm package contents before invoking commands:
 
 - [TOKENTRACE_AGENT.md](TOKENTRACE_AGENT.md)
 - [llms.txt](llms.txt)
+- [docs/agent-adoption.md](docs/agent-adoption.md)
 - [docs/agent-discovery.schema.json](docs/agent-discovery.schema.json)
 
 MCP-capable clients can start the local stdio server after installing or using
@@ -114,6 +115,16 @@ the npm package:
 tokentrace mcp
 ```
 
+Registry name: `io.github.abhiyoheswaran1/tokentrace`.
+
+First MCP call for agents: `get_agent_guide`.
+
+Self-test the local MCP entrypoint without scanning files:
+
+```bash
+tokentrace mcp selftest --json
+```
+
 The MCP server exposes the same local-first surfaces as tools: capabilities,
 status, Scan Health, evidence, repair queue, reports, and an explicit scan tool.
 It does not scan files on startup, and its scan tool requires
@@ -233,8 +244,6 @@ The CLI sets `TOKENTRACE_DB` and `DATABASE_URL` automatically. You can override
 TOKENTRACE_HOME=/custom/path tokentrace
 ```
 
-If `npm install -g tokentrace` prints a `prebuild-install` deprecation warning, it is from the native SQLite dependency chain used by `better-sqlite3`. The install should continue normally, and TokenTrace still runs locally.
-
 ## Where TokenTrace Looks
 
 Default discovery checks these locations when present:
@@ -467,6 +476,28 @@ The ingestion system is intentionally pluggable:
 
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, parser guidelines, pricing update notes, and the release policy.
 
+## Troubleshooting
+
+### `prebuild-install` deprecation warning during install
+
+```
+npm warn deprecated prebuild-install@7.1.3: No longer maintained...
+```
+
+This is a transitive dependency of `better-sqlite3` (the native SQLite driver TokenTrace uses to store local data). The warning is harmless — the install completes normally and TokenTrace runs as expected. It will go away once `better-sqlite3` upstream migrates to a different prebuilt binary loader; there is nothing to fix on the TokenTrace side.
+
+### Native build errors on `better-sqlite3`
+
+If the prebuilt binary cannot be downloaded (offline machine, restrictive proxy, unsupported Node ABI), `better-sqlite3` will try to compile from source and may fail. Workarounds:
+
+- Ensure Node.js is a supported LTS (TokenTrace requires `>= 20.0.0`; Node 20 or 22 LTS is recommended).
+- Install build tools: Xcode Command Line Tools on macOS, `build-essential` and `python3` on Linux, or the "Desktop development with C++" workload on Windows.
+- Retry the install with network access to `github.com` so the prebuilt binary can be fetched.
+
+### `EBADENGINE` warnings
+
+These appear when your local Node version is older than the `engines` field of a transitive dependency. They are warnings, not errors. Upgrading to the latest Node LTS resolves them.
+
 ## Known Limitations
 
 - Claude Code and Codex CLI log formats are inferred defensively and may need refinement with real sample logs.

package/TOKENTRACE_AGENT.md

@@ -25,6 +25,21 @@ MCP-capable clients can use the local stdio server:
 tokentrace mcp
 ```
 
+MCP registry name:
+
+```text
+io.github.abhiyoheswaran1/tokentrace
+```
+
+Agents should call `get_agent_guide` first. It returns the recommended workflow,
+install snippets, copy-paste `AGENTS.md` guidance, and local-first guardrails.
+
+Verify the MCP entrypoint without scanning files:
+
+```bash
+tokentrace mcp selftest --json
+```
+
 The MCP server does not scan on startup. Its `run_scan` tool requires
 `confirmLocalScan=true` before reading local usage files or writing the local
 database.
@@ -53,19 +68,25 @@ curl http://127.0.0.1:3030/api/roadmap
    tokentrace agent --json
    ```
 
-2. Refresh local data when the human expects current usage:
+2. In MCP clients, ask for the operating loop:
+
+   ```text
+   get_agent_guide
+   ```
+
+3. Refresh local data when the human expects current usage:
 
    ```bash
    tokentrace scan --json
    ```
 
-3. Check trust before making claims:
+4. Check trust before making claims:
 
    ```bash
    tokentrace doctor --json
    ```
 
-4. Explain totals with evidence:
+5. Explain totals with evidence:
 
    ```bash
    tokentrace evidence --json

package/app/guide/page.tsx

@@ -148,6 +148,14 @@ const roadmapSteps = [
   ["Dashboard API", "/api/roadmap", "Fetch the same roadmap status from a running local dashboard."]
 ];
 
+const mcpAgentEntries = [
+  ["Registry", "io.github.abhiyoheswaran1/tokentrace", "Use this name when an MCP client discovers TokenTrace from the registry."],
+  ["Start", "tokentrace mcp", "Start the local stdio MCP server. Startup is read-only and does not scan files."],
+  ["First tool", "get_agent_guide", "Return the recommended operating loop, install snippets, and AGENTS.md copy block."],
+  ["Self-test", "tokentrace mcp selftest --json", "Verify MCP initialization, tool listing, guide output, and scan refusal."],
+  ["Scan rule", "confirmLocalScan=true", "Only pass this to run_scan when the human expects a local filesystem scan."]
+];
+
 const workflows = [
   {
     problem: "No records imported",
@@ -506,6 +514,27 @@ export default function GuidePage() {
                 </p>
               </div>
             </div>
+            <div className="border-t p-4">
+              <div className="flex items-center gap-2">
+                <LockKeyhole className="h-4 w-4 text-primary" />
+                <h3 className="text-sm font-semibold leading-tight">MCP for agents</h3>
+              </div>
+              <p className="mt-2 max-w-[72ch] text-sm leading-6 text-muted-foreground">
+                MCP clients should connect locally, call <MonoText>get_agent_guide</MonoText> first, and use evidence before reporting
+                token, cost, model, or session numbers. The full copy-paste workflow lives in <MonoText>docs/agent-adoption.md</MonoText>.
+              </p>
+              <div className="mt-4 grid gap-3 md:grid-cols-2 xl:grid-cols-5">
+                {mcpAgentEntries.map(([label, value, detail]) => (
+                  <div key={label} className="rounded-md border bg-muted/30 p-3">
+                    <FieldLabel>{label}</FieldLabel>
+                    <div className="mt-2 min-h-10 break-words text-sm font-medium leading-5">
+                      <MonoText>{value}</MonoText>
+                    </div>
+                    <p className="mt-2 text-xs leading-5 text-muted-foreground">{detail}</p>
+                  </div>
+                ))}
+              </div>
+            </div>
             <div className="border-t p-4">
               <h3 className="text-sm font-semibold leading-tight">Agent quickstart</h3>
               <div className="table-scroll mt-3">

package/dist/runtime/agent.mjs

@@ -135,11 +135,13 @@ var commands = [
     startsLongRunningProcess: true,
     requiresNetwork: false,
     safeForAutomation: false,
-    useWhen: "An MCP-capable agent or client wants structured access to TokenTrace status, doctor, evidence, repair, report, and explicit scan tools.",
+    useWhen: "An MCP-capable agent or client wants structured access to TokenTrace guidance, status, doctor, evidence, repair, report, and explicit scan tools.",
     followUps: [
+      ["tokentrace", "mcp", "selftest", "--json"],
       ["tokentrace", "agent", "--json"]
     ],
     notes: [
+      "Agents should call get_agent_guide first after connecting through MCP.",
       "The MCP server itself does not scan files on startup.",
       "The run_scan MCP tool requires confirmLocalScan=true before reading local usage files and writing the local database."
     ]