Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
011ab82
Architectural cleanup P0-P3: hygiene, SQL consolidation, IPC split, c…
ddutchie Jun 18, 2026
3b0362a
P4: Analytics canvas consistency — unify priority colors, extract hoo…
ddutchie Jun 18, 2026
8b64bdb
P5: God-component splits — type relocation, page.tsx, project-overvie…
ddutchie Jun 18, 2026
1972c88
Create v2.1.0.md
ddutchie Jun 18, 2026
e16970f
Update README.md, CONTRIBUTING.md, PR template, AGENTS.md for P0-P5 c…
ddutchie Jun 18, 2026
7f5e23e
Code Review
ddutchie Jun 18, 2026
af99741
Address PR review findings — data safety, resource cleanup, conventio…
ddutchie Jun 18, 2026
edafaff
P5-3: Decompose card-detail.tsx (550→232 LOC) — extract CardDetailSid…
ddutchie Jun 18, 2026
441cd2e
P5-3+P5-6: Decompose card-detail + notes-view god components
ddutchie Jun 18, 2026
55d6c48
Fix DatePicker popover clipping inside modals with overflow-y-auto
ddutchie Jun 18, 2026
4585d9b
Fix DatePicker: grow leftward when trigger is near right window edge
ddutchie Jun 18, 2026
6c6a730
Fix DatePicker: render popover via createPortal to document.body
ddutchie Jun 18, 2026
b7b2fde
P5-5: Decompose SessionPane.tsx (1009→269 LOC) — extract 6 components…
ddutchie Jun 18, 2026
3b1bfa3
P5-7+P5-8: Decompose flow-view + note-editor god components
ddutchie Jun 18, 2026
ce85be3
Update v2.1.0 changelog with full P0-P5 cleanup + PR review fixes
ddutchie Jun 18, 2026
7d32e36
Remove docs
ddutchie Jun 18, 2026
1b7bacc
Address PR review findings — IPC error consistency, SSRF host validat…
ddutchie Jun 18, 2026
cd3981c
Remove hex fallback from TerminalTab success color token
ddutchie Jun 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ jobs:
run: node scripts/generate-licenses.js

- name: Type check
run: npx tsc --noEmit
run: npm run type-check:all

# ── Lint ────────────────────────────────────────────────────────────────────
lint:
Expand Down
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,13 @@ This version has breaking changes — APIs, conventions, and file structure may
- **Alpha variants**: `color-mix(in srgb, var(--token) X%, transparent)` — never hardcode `rgba()`
- **Font sizes**: use `rem`-based Tailwind classes (`text-xs`, `text-sm`, `text-[0.714rem]`, etc.). Never use `text-[Npx]` — pixel classes don't scale with the font size setting.
- **Font scaling**: `--font-scale` CSS variable is set on `<html>` inline by `applyFontScale()`. Root `font-size: calc(14px * var(--font-scale))`. SVG `fontSize` attributes must be multiplied by `useFontScale()` from `analyticsHooks.ts`.
- `mcp-server.ts` uses inlined SQL only (no `queries.ts` import) due to Node ABI boundary
- **better-sqlite3 ABI**: the only ABI-sensitive operation is constructing the `Database` instance via `new Database(dbPath, { nativeBinding })`. That happens once in `electron/db/client.ts` (Electron ABI, `electron-native/`) for the main process and once in `mcp-server.ts` (Node 22 ABI, `pkg-native/`) for the MCP runtime. Helper functions in `electron/db/queries.ts` and `electron/db/graph-queries.ts` may be imported from `electron/mcp/tools/*` — they run on the already-constructed `db` handle regardless of which TS file defines them (see `electron/mcp/tools/codebase.ts`, which already does `import * as q from "../../db/queries"`). Never construct a `Database` outside those two bootstrap sites.

## Build

```bash
npm run compile # rebuilds dist-electron/ + dist-mcp/mcp-server.bundle.js
npx tsc --noEmit # type-check (always run after changes)
npm run compile # rebuilds dist-electron/ + dist-mcp/mcp-server.bundle.js
npm run type-check:all # type-check renderer + electron (always run after changes)
```

esbuild is stricter than tsc — backticks inside template literals must be unescaped at the template level. Use `import * as z from "zod"` (not `import { z }`) in all Electron files.
Expand All @@ -49,7 +49,7 @@ esbuild is stricter than tsc — backticks inside template literals must be unes

**KnowledgeGraphView** (`src/components/graph/KnowledgeGraphView.tsx`) — Force-directed and Radial tree layouts only. Reads from `graphData` store slice (populated by `loadGraph()`). `GraphLayoutMode = "force" | "radial"`.

**InsightsView** (`src/components/insights/InsightsView.tsx`) — hosts all seven analytics canvases. Also calls `loadGraph()` on mount (same as KGV) because canvases scope data via `useScopedData(nodes)` which needs `graphData.nodes` populated. Local `InsightsLayout` type — not stored in the global store.
**InsightsView** (`src/components/insights/InsightsView.tsx`) — hosts all seven analytics canvases (which live in `src/components/graph/` alongside the KnowledgeGraph canvases and the shared scaffold). Also calls `loadGraph()` on mount (same as KGV) because canvases scope data via `useScopedData(nodes)` which needs `graphData.nodes` populated. Local `InsightsLayout` type — not stored in the global store.

## Analytics canvas architecture

Expand Down Expand Up @@ -115,7 +115,7 @@ Notes write to both `.md` files and SQLite simultaneously. Dashboards write to S

## Key constraints

- Never import from `queries.ts` in `mcp-server.ts` — it crosses the Node ABI boundary
- Never construct a `Database` instance outside `electron/db/client.ts` (Electron) and `mcp-server.ts` (MCP runtime) — those are the only two ABI bootstrap sites (see "better-sqlite3 ABI" above)
- All DB writes from renderer go through `ipc()` / `ipcAwait()` to the Electron main process
- `graphData` is lazy — only populated when `loadGraph(activeWorkspaceId)` is called. Both `KnowledgeGraphView` and `InsightsView` call it on mount.
- D3 `fontSize` in SVG must always be multiplied by `useFontScale()` — never hardcode px values
Expand Down
92 changes: 92 additions & 0 deletions changelogs/cleanup-p0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
## Cleanup (P0 — Hygiene & Safety Net)

Architectural-deep-dive cleanup (see `docs/cleanup/`). Phase P0 removes dead code
and reconciles the native-binding / type-checking setup so later phases can be done
safely. No behaviour changes.

### Removed (dead code)

- **`mcp-native/` folder** deleted. The system-Node build was removed in v0.3.8 but
the folder lingered; no source code referenced it (only stale `dist-electron/` and
`dist-mcp/` artifacts, also regenerated).
- **`pkg-native/better_sqlite3_node25.node`** deleted. No references anywhere in the
repo (scripts, electron source, configs). Stale binary from an earlier pkg target.
- **`scripts/check-tool-parity.ts`** + **`electron/ipc/tool-parity.test.ts`** deleted.
Both referenced the `TOOL_DEFINITIONS` constant which was refactored away into
`electron/lib/tool-schemas.ts` (`TOOL_SCHEMAS`). Never invoked by `package.json` or
CI; gave false confidence.
- **`dist-electron/mcp-server.js`** + **`dist-mcp/mcp-server.js`** deleted. Stale
artifacts from an older build pipeline (the current compile produces
`dist-mcp/mcp-server.bundle.js`). They still referenced the deleted `mcp-native/`.
- **`src/components/graph/GraphAIPanel.test.ts`** renamed to
**`graph-ai-utils.test.ts`**. The test was *not* dead — it imports and tests
`./graph-ai-utils` (`wikilinkAlreadyExists` + `buildGraphContext`, 16 passing
tests). Only the filename implied an orphaned `GraphAIPanel.tsx` component that
doesn't exist.

### Native binding setup

- **`vitest-sqlite-shim.cjs` now honors `process.env.BETTER_SQLITE3_BINDING`**
(falling back to `vitest-native/better_sqlite3.node`). Previously the shim
hardcoded the path and the env var set in `vitest.config.ts` was silently ignored.
- **`vitest.config.ts` env var repointed at `vitest-native/`** (the actually-correct
system-Node ABI build), not `pkg-native/` (which holds the Node 22 ABI for the
pkg-bundled MCP binary). The misleading comment claiming "pkg-native/ always has
the system Node ABI" is corrected.
- **`vitest-native/` folder kept.** Despite looking redundant with `pkg-native/`, the
two hold *different* ABIs in general: `pkg-native/` is Node 22 (pkg binary target),
`vitest-native/` is whatever system Node the developer runs (CONTRIBUTING.md:55
documents three distinct ABIs). They only coincide on Node 22; consolidating would
silently break vitest for developers on Node ≠ 22 (there is no `engines` or `.nvmrc`
pin in the repo).

### Type-checking

- **`tsconfig.mcp.json` removed.** It type-checked only `electron/mcp-server.ts` as a
single root file, which gives superficial coverage (TypeScript doesn't pull
transitive imports during a no-emit check of one root).
- **`tsconfig.electron.json`** now removes the unused `@shared/*` path alias.
- **New `type-check:electron` and `type-check:all` npm scripts.** Previously only
`tsc --noEmit` (renderer) existed; electron code was never type-checked.
- **CI `type-check` job** now runs `npm run type-check:all`, covering both the
renderer and the electron/mcp codebase. AGENTS.md updated to instruct
`npm run type-check:all` after changes.

### Build

- **esbuild target bumped from `node20` → `node22`** in `package.json` (`compile` + `compile:watch`) and `scripts/build.js` (main+preload production build). Electron 41 ships Node 22 and the MCP bundle runs under Node 22; the previous `node20` was stale.

### Type-check fixes (P0-3 detail)

**`electron/` had 142 pre-existing type errors** that were never surfaced because CI only ran `tsc --noEmit` (renderer-only `tsconfig.json`). All 142 are now fixed and the electron type-check is green.

**Architectural fix — `IpcHandler` was too strict (resolved 80 errors).**
`electron/ipc/registry.ts` declared `IpcHandler = (event: unknown, ...args: unknown[]) => unknown`. By contravariance, every handler with a destructured typed second arg (e.g. `(_e, { id }: { id: string })`) was rejected. Made the type **generic** over the args tuple, and split event typing for the two ipc surfaces: `IpcHandleHandler<T>` (event `Electron.IpcMainInvokeEvent`) for `registerIpcHandle` and `IpcOnHandler<T>` (event `Electron.IpcMainEvent`) for `registerIpcOn`. The erased `IpcHandler<T>` remains the internal storage type. This properly types both `event.sender` accesses and destructured args, with no `any`.

**Mechanical fixes (resolved 17 errors).** Missing imports in `electron/mcp/db.ts` (`Database`, `newId`, `ts`) and `electron/lib/tools.ts` (`ToolName`); `https.ClientRequest` → `http.ClientRequest` in `electron/lib/llama-server.ts` (Node 22 types); widened `chatOnlySet`/`agentExcluded` to `Set<string>` in `context-audit.test.ts` (filters `Object.keys()` results).

**Handler arg typing (resolved 25 errors).** `electron/ipc/handlers.ts` forwarding handlers annotated with `Parameters<typeof q.fn>[1]` for type-safe IPC-boundary forwarding; two `reqConfig` locals widened to optional fields matching `CachedConfig.aiConfig`'s shape (downstream already used `?.` + fallbacks); `electron/mcp/tools/tasks.ts` row typed as `{ archived_at?: string | null; title?: string } | undefined`.

**Real type bugs fixed (resolved 12 errors).**
- `electron/ipc/pi-agent.ts`: `PiAgentPromptRequest.config` and `PiAgentApprovePlanRequest.config` were missing `provider?` (the handler checks `req.config?.provider === "localllm"`).
- `electron/lib/config-cache.ts`: `CachedConfig.agentConfig` was missing `maxSteps?`/`temperature?` (the pi-agent merge reads `cached.maxSteps`/`cached.temperature`). Note `saveCachedConfig("agent")` still doesn't persist these two — a behavioural follow-up (cache them, or drop the dead fallback) is tracked in `findings.md`.
- `electron/db/graph-queries.ts`: the local `GraphNode.meta` type was missing `isArchived?` (the code adds `isArchived: !!(c.archived_at)` to card nodes). This is a second instance of the type-duplication-across-boundary issue noted for `wikilink-parser` in `findings.md §2.8` — a P1+ consolidation candidate.
- `electron/lib/mobile-server.ts`: typed the `clientSocket.on("error")` callback param as `Error`.

### Docs

- **AGENTS.md** corrected: the "mcp-server.ts uses inlined SQL only due to Node ABI
boundary" claim is stale. `mcp/tools/codebase.ts` already imports
`* as q from "../../db/queries"` and works in the bundle — the only ABI-sensitive
operation is `new Database(dbPath, { nativeBinding })` which happens once in
`mcp-server.ts`. This unblocks the P1 SQL-consolidation phase.
- **AGENTS.md** corrected: the seven analytics canvases live in
`src/components/graph/`, not `src/components/insights/` (only `InsightsView.tsx`
lives in `insights/`).

## Verification

- `npm run type-check:all` — clean (renderer + electron).
- `npm run lint -- --max-warnings 0` — clean.
- `npm run compile` — clean (esbuild node22 targets).
- `npm test` — **430 tests pass across 18 files** (including the renamed `graph-ai-utils.test.ts`).
88 changes: 88 additions & 0 deletions changelogs/cleanup-p1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
## Cleanup (P1 — SQL Consolidation across the Electron↔MCP boundary)

Architectural-deep-dive cleanup (see `docs/cleanup/`). Phase P1 eliminates the
~1000 lines of SQL duplicated between the Electron main process (`electron/db/queries.ts`
+ `electron/db/graph-queries.ts`) and the MCP server (`electron/mcp/tools/*` + `mcp/db.ts`).
This is unblocked by P0-5, which corrected the stale AGENTS.md claim that an "ABI boundary"
prevented importing `queries.ts` from the MCP runtime.

### Why this was safe

The only ABI-sensitive operation in `better-sqlite3` is constructing the `Database`
instance — that happens once in `electron/mcp-server.ts:140`
(`new Database(dbPath, { nativeBinding: MCP_NATIVE_BINDING })`). All `db.prepare(...).run(...)`
calls execute on that already-constructed handle regardless of which TS file defines them.
`electron/mcp/tools/codebase.ts` already imported `* as q from "../../db/queries"` and
worked in the bundle — P1 extends that pattern to the other 6 tool files.

### Consolidated files (in migration order)

Every MCP tool file now delegates to the canonical `q.*` (or `getKnowledgeGraph` /
`getNeighbours` from `graph-queries.ts`) helpers. Each migration preserved the public MCP
tool signatures and return shapes; only the implementation changed. All 103 MCP server
tests pass unchanged.

| File | Before | After | Net | What was removed |
|------|-------:|------:|----:|------------------|
| `mcp/tools/tags.ts` | 14 | 18 | +4 | Wrapped `q.createTag`; tiny file got slightly longer because of arg-validation boilerplate |
| `mcp/tools/projects.ts` | 70 | 55 | −15 | Inline INSERT/UPDATE/DELETE + the 4-statement cascade → `q.createProject` / `q.updateProject` / `q.deleteProject` (+ `q.createColumn` for default columns) |
| `mcp/tools/dashboards.ts` | 30 | 31 | +1 | INSERT note with `type='dashboard'` → `q.createNote` / `q.updateNote` with `type: "dashboard"` |
| `mcp/tools/notes.ts` | 187 | 213 | +26 | UPDATE-then-write-file flow kept (MCP-specific file-sync); SQL replaced with `q.updateNote` / `q.createNote` / `q.getNoteById` / `q.deleteNote`. Slight growth from passing patch objects explicitly. The `lockNote`/`unlockNote`/`getNoteVersion` MCP-active-write helpers stay in `mcp/db.ts` (genuinely MCP-only behaviour). |
| `mcp/tools/tasks.ts` | 321 | 230 | −91 | 28 `db.prepare` calls collapsed: `q.createCard`, `q.updateCard`, `q.deleteCard`, `q.restoreCard`, `q.clearCardDueDate`, `q.addCardBlocker`, `q.removeCardBlocker`, `q.clearBlockersFromAll`, `q.getReadyCards`, `q.getCardById`. `list_ready_tasks` now wraps `q.getReadyCards` and only adds `columnName` from the snapshot (a one-line lookup). |
| `mcp/tools/flow.ts` | 313 | 290 | −23 | The 100-line `get_idea_flow` (a duplicate of `q.getResolvedFlow`'s 84-line BFS) now delegates to it and only maps the return shape (`node.position = {x,y}`, `resolved*` fields nested in `data`). Node/edge CRUD uses `q.createFlowNode` / `q.updateFlowNode` / `q.deleteFlowNode` / `q.createFlowEdge` / `q.deleteFlowEdge` (the `INSERT OR IGNORE` dedup is already in `q.createFlowEdge`). `layout_idea_flow` keeps its dagre logic (no equivalent in queries.ts). |
| `mcp/tools/graph.ts` | 183 | 39 | **−144** | The big one. `get_knowledge_graph` (114 LOC, 12 prepare calls, same project→notes→cards→tags→flow→relationship_cache algorithm as `getKnowledgeGraph`'s 312 LOC in `graph-queries.ts`) now delegates and only adapts the filter shape. `get_neighbors` (69 LOC, same BFS as `getNeighbours`) now delegates directly — same return shape. The algorithm is no longer maintained in two places. |
| `mcp/db.ts` | 212 | 199 | −13 | `getSnapshot` now delegates to `q.getFullSnapshot`. The `Snapshot.tags` element type is aliased to `ReturnType<typeof toTag>` (the 4-field shape `{id, workspaceId, name, color}` was already what `toTag` returns; the local redefinition is gone). MCP-active-write helpers (`lockNote`/`unlockNote`/`getNoteVersion`/`getCardVersion`/`resolveTagNames`/`insertNotification`/`ensureMcpActiveWritesTable`) stay — they implement genuinely MCP-only behaviour (locking + best-effort notifications on the MCP runtime). |

### Codebase-wide impact

- **Net LOC change in `electron/mcp/`:** −216 lines. (The few files that grew slightly did so
because passing typed patch objects is more verbose than inlining SQL — but the SQL
surface area and behavioural drift surface both shrank dramatically.)
- **Total `db.prepare()` calls eliminated:** ~80 (84 in `mcp/tools/*.ts` + 6 in `mcp/db.ts`
via the snapshot consolidation; offset by ~6 added for the MCP-side existence checks the
helpers don't cover).
- **Single source of truth:** the canonical graph algorithm (`getKnowledgeGraph` + BFS in
`getNeighbours`) and the canonical flow-resolution algorithm (`getResolvedFlow`) and
the canonical snapshot shape are each now defined once. The previous situation meant a
fix to either algorithm had to be manually mirrored across the ABI boundary.
- **`electron/db/queries.ts`** now has a governance header documenting that it is the
single source of truth for all SQL, may be imported from `mcp/tools/*` (precedent:
`codebase.ts`), and that `Database` instances must never be constructed here.
- **`mcp/db.ts`** still re-exports `j`/`j2`/`p`/`b`/`newId`/`ts`/`toWorkspace`/`toProject`/
`toNote`/`toColumn`/`toCard`/`toTag`/`writeNoteFile`/`deleteNoteFile`/etc. for the
remaining MCP-specific code; these are unchanged.

### Behaviour preservation

- All 103 `electron/mcp-server.test.ts` tests pass unchanged (they exercise every MCP tool
end-to-end against a real in-memory SQLite DB).
- All 22 `electron/db/queries.test.ts` tests pass (they exercise the query helpers
directly).
- The MCP public API (tool names, argument shapes, return shapes) is unchanged — only the
implementations behind those tools were consolidated.

### Follow-ups tracked in `docs/cleanup/findings.md`

These are out of scope for P1 but worth noting:

- `mcp/db.ts:getCardVersion` and `getNoteVersion` query the `version` column directly.
They could move to queries.ts as `q.getCardVersion`/`q.getNoteVersion` if the Electron
main process ever needs them (currently it doesn't — IPC handlers use optimistic UI
merge instead).
- `mcp/db.ts:resolveTagNames` is MCP-only today but could move to queries.ts if needed
elsewhere.
- The MCP-side existence checks in `flow.ts` (`getNodeFlowId`, the `SELECT 1 FROM
idea_flow_nodes WHERE id = ?` lookups) could be replaced by
`q.getFlowNodeById`/`q.getFlowEdgeById` helpers added to queries.ts. Left for now —
keeping API surface small.

## Verification

- `npm run type-check:all` — clean (renderer + electron).
- `npm run lint -- --max-warnings 0` — clean.
- `npm run compile` — clean (esbuild bundles; the `* as q` import resolves to the inlined
queries.ts module, exactly as it already did in `codebase.ts`).
- `npm test` — **430 tests pass across 18 files** (incl. 103 MCP server tests + 22
queries tests).
- `npm run smoke-test` — 4/4 checks pass (verifies the compiled bundles load and native
modules resolve).
Loading