strengthen repo verification and runtime coverage

Add clearer app docs plus targeted desktop, CLI, web, and worker tests so cross-surface regressions are caught earlier and the repo is easier to navigate.

apps/x/README.md

@@ -0,0 +1,54 @@
+# Rowboat Desktop App
+
+`apps/x` is the primary local-first Rowboat desktop product. It is a nested `pnpm` workspace that packages the Electron app, renderer, preload bridge, shared contracts, and core knowledge/runtime logic.
+
+## Workspace Layout
+
+- `apps/main` - Electron main process
+- `apps/renderer` - React and Vite renderer UI
+- `apps/preload` - validated IPC bridge
+- `packages/shared` - shared schemas and IPC contracts
+- `packages/core` - workspace, knowledge graph, integrations, agents, and background services
+
+## Local Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Build shared dependencies used by the app:
+
+```bash
+npm run deps
+```
+
+Run the desktop app in development:
+
+```bash
+npm run dev
+```
+
+Useful verification commands:
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run verify
+```
+
+## Build Notes
+
+- `npm run deps` builds `shared`, `core`, and `preload`
+- `apps/main` bundles the Electron main process with esbuild for packaging
+- The renderer uses Vite and hot reloads during development
+
+## Local Data Model
+
+- Default work directory: `~/.rowboat`
+- Knowledge is stored as Markdown
+- Knowledge note history is Git-backed for transparent local versioning
+
+If you are new to the repo, read the root `ARCHITECTURE.md` before making cross-surface changes.

apps/x/apps/main/src/composio-handler.ts

@@ -151,7 +151,7 @@ export async function initiateConnection(toolkitSlug: string): Promise<{
         // Set up callback server
         const timeoutRef: { current: NodeJS.Timeout | null } = { current: null };
         let callbackHandled = false;
-        const { server } = await createAuthServer(8081, async (_callbackUrl) => {
+        const { server } = await createAuthServer(8081, async () => {
             // Guard against duplicate callbacks (browser may send multiple requests)
             if (callbackHandled) return;
             callbackHandled = true;

apps/x/apps/renderer/README.md

@@ -1,73 +1,25 @@
-# React + TypeScript + Vite
+# Desktop Renderer
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+This package contains the React and Vite renderer for the Electron desktop app in `apps/x`.
 
-Currently, two official plugins are available:
+## Responsibilities
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- Render the desktop UI
+- Talk to the Electron preload bridge instead of Node APIs directly
+- Display workspace, chat, notes, graph, and other local-first product surfaces
 
-## React Compiler
+## Commands
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+npm run dev
+npm run build
+npm run lint
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+Run these from `apps/x/apps/renderer` when working only on the renderer, or use `apps/x` and run `npm run dev` to launch the full desktop stack.
 
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+## Constraints
 
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
+- Assume `nodeIntegration` is disabled in the renderer
+- Use the preload IPC bridge for privileged operations
+- Keep shared contracts in `packages/shared` when a renderer and the main process need the same schema

apps/x/package.json

@@ -7,10 +7,19 @@
     "dev": "npm run deps && concurrently -k \"npm:renderer\" \"npm:main\"",
     "renderer": "cd apps/renderer && npm run dev",
     "shared": "cd packages/shared && npm run build",
+    "shared:typecheck": "cd packages/shared && npx tsc --noEmit",
     "core": "cd packages/core && npm run build",
+    "core:typecheck": "cd packages/core && npx tsc --noEmit",
+    "core:test": "cd packages/core && npm test",
     "preload": "cd apps/preload && npm run build",
+    "preload:typecheck": "cd apps/preload && npx tsc --noEmit",
     "deps": "npm run shared && npm run core && npm run preload",
     "main": "wait-on http://localhost:5173 && cd apps/main && npm run build && npm run start",
+    "main:typecheck": "cd apps/main && npx tsc --noEmit",
+    "renderer:typecheck": "cd apps/renderer && npx tsc -p tsconfig.app.json --noEmit && npx tsc -p tsconfig.node.json --noEmit",
+    "typecheck": "npm run shared:typecheck && npm run core:typecheck && npm run deps && npm run preload:typecheck && npm run main:typecheck && npm run renderer:typecheck",
+    "test": "npm run shared && npm run core:test",
+    "verify": "npm run lint && npm run typecheck && npm run test",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },
@@ -26,4 +35,4 @@
     "typescript-eslint": "^8.50.1",
     "wait-on": "^9.0.3"
   }
-}
+}

apps/x/packages/core/package.json

@@ -6,7 +6,8 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rm -rf dist && tsc",
-    "dev": "tsc -w"
+    "dev": "tsc -w",
+    "test": "npm run build && node ./test/run-tests.mjs"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.63",

apps/x/packages/core/src/application/lib/builtin-tools.ts

@@ -561,7 +561,7 @@ export const BuiltinTools: z.infer<typeof BuiltinToolsSchema> = {
                         count: matches.length,
                         tool: 'ripgrep',
                     };
-                } catch (rgError) {
+                } catch {
                     // Fallback to basic grep if ripgrep not available or failed
                     const grepArgs = [
                         '-rn',

apps/x/packages/core/src/config/config.ts

@@ -1,7 +1,6 @@
 import path from "path";
 import fs from "fs";
 import { homedir } from "os";
-import { fileURLToPath } from "url";
 
 function resolveWorkDir(): string {
     const configured = process.env.ROWBOAT_WORKDIR;
@@ -23,10 +22,6 @@ function resolveWorkDir(): string {
 // Normalize to an absolute path so workspace boundary checks behave consistently.
 export const WorkDir = resolveWorkDir();
 
-// Get the directory of this file (for locating bundled assets)
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
 function ensureDirs() {
     const ensure = (p: string) => { if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true }); };
     ensure(WorkDir);

apps/x/packages/core/src/config/strictness_analyzer.ts

@@ -390,9 +390,6 @@ export function analyzeEmailsAndRecommend(): AnalysisResult {
     let reason: string;
 
     const totalHumanSenders = lowWouldCreate;
-    const noiseRatio = uniqueSenders.size > 0
-        ? (newsletterSenders.size + automatedSenders.size) / uniqueSenders.size
-        : 0;
     const consumerRatio = totalHumanSenders > 0
         ? consumerServiceSenders.size / totalHumanSenders
         : 0;

apps/x/packages/core/src/knowledge/agent_notes.ts

@@ -193,13 +193,16 @@ function extractConversationMessages(runFilePath: string): { role: string; text:
 // --- Wait for agent run completion ---
 
 async function waitForRunCompletion(runId: string): Promise<void> {
-    return new Promise(async (resolve) => {
-        const unsubscribe = await bus.subscribe('*', async (event) => {
+    return new Promise((resolve, reject) => {
+        let unsubscribe = () => {};
+        bus.subscribe('*', async (event) => {
             if (event.type === 'run-processing-end' && event.runId === runId) {
                 unsubscribe();
                 resolve();
             }
-        });
+        }).then((nextUnsubscribe) => {
+            unsubscribe = nextUnsubscribe;
+        }).catch(reject);
     });
 }
 

apps/x/packages/core/src/knowledge/build_graph.ts

@@ -189,13 +189,16 @@ async function readFileContents(filePaths: string[]): Promise<{ path: string; co
  * Wait for a run to complete by listening for run-processing-end event
  */
 async function waitForRunCompletion(runId: string): Promise<void> {
-    return new Promise(async (resolve) => {
-        const unsubscribe = await bus.subscribe('*', async (event) => {
+    return new Promise((resolve, reject) => {
+        let unsubscribe = () => {};
+        bus.subscribe('*', async (event) => {
             if (event.type === 'run-processing-end' && event.runId === runId) {
                 unsubscribe();
                 resolve();
             }
-        });
+        }).then((nextUnsubscribe) => {
+            unsubscribe = nextUnsubscribe;
+        }).catch(reject);
     });
 }
 

apps/x/packages/core/src/knowledge/chrome-extension/server/server.ts

@@ -43,7 +43,7 @@ function pathToSlug(url: string): string {
         const parsed = new URL(url);
         const p = parsed.pathname + (parsed.search || '');
         if (!p || p === '/') return 'index';
-        let slug = p.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_|_$/g, '');
+        const slug = p.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_|_$/g, '');
         return slug.substring(0, 80) || 'index';
     } catch {
         return 'index';
@@ -184,12 +184,13 @@ function saveConfig(config: Config): void {
     fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
 }
 
-function validateConfig(data: any): data is Config {
+function validateConfig(data: unknown): data is Config {
     if (typeof data !== 'object' || data === null) return false;
-    if (data.mode !== 'all' && data.mode !== 'ask') return false;
-    if (!Array.isArray(data.whitelist)) return false;
-    if (!Array.isArray(data.blacklist)) return false;
-    if (typeof data.enabled !== 'boolean') return false;
+    const candidate = data as Partial<Config>;
+    if (candidate.mode !== 'all' && candidate.mode !== 'ask') return false;
+    if (!Array.isArray(candidate.whitelist)) return false;
+    if (!Array.isArray(candidate.blacklist)) return false;
+    if (typeof candidate.enabled !== 'boolean') return false;
     return true;
 }
 

apps/x/packages/core/src/knowledge/inline_tasks.ts

@@ -133,13 +133,16 @@ function scanDirectoryRecursive(dir: string): string[] {
  * Wait for a run to complete by listening for run-processing-end event
  */
 async function waitForRunCompletion(runId: string): Promise<void> {
-    return new Promise(async (resolve) => {
-        const unsubscribe = await bus.subscribe('*', async (event) => {
+    return new Promise((resolve, reject) => {
+        let unsubscribe = () => {};
+        bus.subscribe('*', async (event) => {
             if (event.type === 'run-processing-end' && event.runId === runId) {
                 unsubscribe();
                 resolve();
             }
-        });
+        }).then((nextUnsubscribe) => {
+            unsubscribe = nextUnsubscribe;
+        }).catch(reject);
     });
 }
 

apps/x/packages/core/src/knowledge/label_emails.ts

@@ -66,13 +66,16 @@ function getUnlabeledEmails(state: LabelingState): string[] {
  * Wait for a run to complete by listening for run-processing-end event
  */
 async function waitForRunCompletion(runId: string): Promise<void> {
-    return new Promise(async (resolve) => {
-        const unsubscribe = await bus.subscribe('*', async (event) => {
+    return new Promise((resolve, reject) => {
+        let unsubscribe = () => {};
+        bus.subscribe('*', async (event) => {
             if (event.type === 'run-processing-end' && event.runId === runId) {
                 unsubscribe();
                 resolve();
             }
-        });
+        }).then((nextUnsubscribe) => {
+            unsubscribe = nextUnsubscribe;
+        }).catch(reject);
     });
 }
 

apps/x/packages/core/src/knowledge/sync_calendar.ts

@@ -348,24 +348,6 @@ async function performSync(syncDir: string, lookbackDays: number) {
 
 // --- Composio-based Sync ---
 
-interface ComposioCalendarState {
-    last_sync: string; // ISO string
-}
-
-function loadComposioState(stateFile: string): ComposioCalendarState | null {
-    if (fs.existsSync(stateFile)) {
-        try {
-            const data = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
-            if (data.last_sync) {
-                return { last_sync: data.last_sync };
-            }
-        } catch (e) {
-            console.error('[Calendar] Failed to load composio state:', e);
-        }
-    }
-    return null;
-}
-
 function saveComposioState(stateFile: string, lastSync: string): void {
     fs.writeFileSync(stateFile, JSON.stringify({ last_sync: lastSync }, null, 2));
 }

apps/x/packages/core/src/knowledge/tag_notes.ts

@@ -79,13 +79,16 @@ function getUntaggedNotes(state: NoteTaggingState): string[] {
  * Wait for a run to complete by listening for run-processing-end event
  */
 async function waitForRunCompletion(runId: string): Promise<void> {
-    return new Promise(async (resolve) => {
-        const unsubscribe = await bus.subscribe('*', async (event) => {
+    return new Promise((resolve, reject) => {
+        let unsubscribe = () => {};
+        bus.subscribe('*', async (event) => {
             if (event.type === 'run-processing-end' && event.runId === runId) {
                 unsubscribe();
                 resolve();
             }
-        });
+        }).then((nextUnsubscribe) => {
+            unsubscribe = nextUnsubscribe;
+        }).catch(reject);
     });
 }
 

apps/x/packages/core/src/pre_built/runner.ts

@@ -22,13 +22,16 @@ const PREBUILT_DIR = path.join(WorkDir, 'pre-built');
  * Wait for a run to complete by listening for run-processing-end event
  */
 async function waitForRunCompletion(runId: string): Promise<void> {
-    return new Promise(async (resolve) => {
-        const unsubscribe = await bus.subscribe('*', async (event) => {
+    return new Promise((resolve, reject) => {
+        let unsubscribe = () => {};
+        bus.subscribe('*', async (event) => {
             if (event.type === 'run-processing-end' && event.runId === runId) {
                 unsubscribe();
                 resolve();
             }
-        });
+        }).then((nextUnsubscribe) => {
+            unsubscribe = nextUnsubscribe;
+        }).catch(reject);
     });
 }
 
@@ -89,8 +92,6 @@ Process new items and use the user context above to identify yourself when draft
  * Check all agents and run those that are due
  */
 async function checkAndRunAgents(): Promise<void> {
-    const config = loadConfig();
-
     for (const agentName of PREBUILT_AGENTS) {
         try {
             if (shouldRunAgent(agentName)) {
@@ -149,7 +150,7 @@ export async function init(): Promise<void> {
  * Manually trigger an agent run (useful for testing)
  */
 export async function triggerAgent(agentName: string): Promise<void> {
-    if (!PREBUILT_AGENTS.includes(agentName as any)) {
+    if (!PREBUILT_AGENTS.includes(agentName as (typeof PREBUILT_AGENTS)[number])) {
         throw new Error(`Unknown agent: ${agentName}. Available: ${PREBUILT_AGENTS.join(', ')}`);
     }
     await runAgent(agentName);

apps/x/packages/core/src/workspace/watcher.ts

@@ -1,12 +1,12 @@
 import chokidar, { type FSWatcher } from 'chokidar';
 import fs from 'node:fs/promises';
+import { workspace } from '@x/shared';
 import { ensureWorkspaceRoot, absToRelPosix } from './workspace.js';
 import { WorkDir } from '../config/config.js';
-import { WorkspaceChangeEvent } from 'packages/shared/dist/workspace.js';
 import z from 'zod';
 import { Stats } from 'node:fs';
 
-export type WorkspaceChangeCallback = (event: z.infer<typeof WorkspaceChangeEvent>) => void;
+export type WorkspaceChangeCallback = (event: z.infer<typeof workspace.WorkspaceChangeEvent>) => void;
 
 /**
  * Create a workspace watcher

apps/x/packages/core/src/workspace/workspace.ts

@@ -3,7 +3,6 @@ import type { Stats } from 'node:fs';
 import path from 'node:path';
 import { workspace } from '@x/shared';
 import { z } from 'zod';
-import { RemoveOptions, WriteFileOptions, WriteFileResult } from 'packages/shared/dist/workspace.js';
 import { WorkDir } from '../config/config.js';
 import { rewriteWikiLinksForRenamedKnowledgeFile } from './wiki-link-rewrite.js';
 import { commitAll } from '../knowledge/version_history.js';
@@ -237,8 +236,8 @@ function scheduleKnowledgeCommit(filename: string): void {
 export async function writeFile(
   relPath: string,
   data: string,
-  opts?: z.infer<typeof WriteFileOptions>
-): Promise<z.infer<typeof WriteFileResult>> {
+  opts?: z.infer<typeof workspace.WriteFileOptions>
+): Promise<z.infer<typeof workspace.WriteFileResult>> {
   const filePath = resolveWorkspacePath(relPath);
   const encoding = opts?.encoding || 'utf8';
   const atomic = opts?.atomic !== false; // default true
@@ -381,7 +380,7 @@ export async function copy(
 
 export async function remove(
   relPath: string,
-  opts?: z.infer<typeof RemoveOptions>
+  opts?: z.infer<typeof workspace.RemoveOptions>
 ): Promise<{ ok: true }> {
   const filePath = resolveWorkspacePath(relPath);
   const trash = opts?.trash !== false; // default true

apps/x/packages/core/test/run-tests.mjs

@@ -0,0 +1,31 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageDir = path.resolve(__dirname, "..");
+const tempRoot = await mkdtemp(path.join(tmpdir(), "rowboat-core-test-"));
+const testWorkDir = path.join(tempRoot, "workspace");
+
+try {
+  const exitCode = await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ["--test", "./test/workspace-path-safety.test.mjs"], {
+      cwd: packageDir,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        ROWBOAT_WORKDIR: testWorkDir,
+      },
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+
+  process.exitCode = Number(exitCode);
+} finally {
+  await rm(tempRoot, { recursive: true, force: true });
+}

apps/x/packages/core/test/workspace-path-safety.test.mjs

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+
+import { WorkDir } from "../dist/config/config.js";
+import {
+  absToRelPosix,
+  assertSafeRelPath,
+  resolveWorkspacePath,
+} from "../dist/workspace/workspace.js";
+
+test("uses ROWBOAT_WORKDIR override for test isolation", () => {
+  assert.equal(WorkDir, process.env.ROWBOAT_WORKDIR);
+});
+
+test("assertSafeRelPath allows simple relative paths", () => {
+  assert.doesNotThrow(() => assertSafeRelPath("notes/today.md"));
+});
+
+test("assertSafeRelPath rejects absolute paths", () => {
+  assert.throws(() => assertSafeRelPath("/tmp/notes.md"), /Absolute paths are not allowed/);
+});
+
+test("assertSafeRelPath rejects traversal attempts", () => {
+  assert.throws(() => assertSafeRelPath("../notes.md"), /Path traversal/);
+  assert.throws(() => assertSafeRelPath("notes/../secret.md"), /Path traversal|Invalid path/);
+});
+
+test("resolveWorkspacePath returns the configured root for empty path", () => {
+  assert.equal(resolveWorkspacePath(""), WorkDir);
+});
+
+test("resolveWorkspacePath resolves safe relative paths inside the workspace", () => {
+  assert.equal(resolveWorkspacePath("knowledge/alpha.md"), path.join(WorkDir, "knowledge", "alpha.md"));
+});
+
+test("absToRelPosix returns POSIX relative paths inside the workspace", () => {
+  const absolutePath = path.join(WorkDir, "knowledge", "nested", "alpha.md");
+  assert.equal(absToRelPosix(absolutePath), "knowledge/nested/alpha.md");
+});
+
+test("absToRelPosix rejects paths outside the workspace", () => {
+  assert.equal(absToRelPosix("/tmp/outside.md"), null);
+});