Imported from Evthron/Increvise (AGENTS.md). Install upstream with npx skills add Evthron/Increvise. Copyright stays with the author.

AGENTS.md

Commands

Development

• npm run dev - Start Electron with hot reload
• npm run build - Build for production
• npm start - Preview production build

Testing

• npm test - Run all tests (auto-rebuilds better-sqlite3)
• npm run test:validation / test:incremental / test:spaced / test:workspace - Run specific test suites
• npm run test:clean - Remove test artifacts
• npm run dev:noserver - Start Electron without dev server (for testing HTML functions)

Code Quality

• npx eslint . - Lint code
• npx prettier --write . - Format code

Native Modules

• npm run rebuild:electron - Rebuild better-sqlite3 for Electron
• npm run rebuild:node - Rebuild better-sqlite3 for Node

Project Structure

Electron app with:

• src/main/ - Main process (IPC handlers, database)
  • src/main/db/ - Database initialization
  • src/main/ipc/ - IPC handlers (file, workspace, incremental, spaced)
• src/preload/ - Secure IPC bridge using contextBridge
• src/renderer/ - UI layer (Lit web components)
  • src/renderer/ui/ - Components (FileTree, EditorPanel, viewers, etc.)
• test/ - Node.js test runner tests

Key Technologies

• Better-SQLite3: Synchronous API (no async/await needed for queries)
  • Central DB: global workspace metadata and settings
  • Workspace DB: per-workspace in .increvise/db.sqlite
  • Use prepared statements and transactions for performance
• Lit: Web components extending LitElement
• CodeMirror: Code/text editor
• Marked: Markdown rendering
• pdfjs-dist: PDF viewing

Code Conventions

• ES Modules: Use import/export, node: prefix for built-ins
• Formatting: Prettier and ESLint configured (see .prettierrc and eslint.config.mjs)
• File Headers: All source files require SPDX headers:

  // SPDX-FileCopyrightText: 2025-2026 The Increvise Project Contributors
  //
  // SPDX-License-Identifier: GPL-3.0-or-later

• Import Order: Node built-ins → third-party → local modules
• Test Files: Add test files to test/ directory
• HTML Parsing: Do not use regex to match HTML nodes; use specific tools instead (e.g., DOM parsers, JSDOM, etc.)

Coding Style Guidelines

• Avoid Defensive Coding: Don't use layered try-catch blocks when one is sufficient, or redundant null checks when values are not supposed to be null. Write code that assumes valid inputs unless there's a specific need for validation.
• Error Handling — Use Exceptions, Not Result Objects: Do not return {success, error} result objects. Use exceptions instead. Validate preconditions with throw Error('message'). In the main process (IPC handlers), wrap the entire function body in a single try-catch: log via console.error(e.stack) at the main boundary, then throw e to propagate. In the UI layer, call APIs directly without try-catch wrapping; let the caller (the top-level UI handler that interacts with the user) catch and display feedback via toast. Never nest try-catch — one at the appropriate boundary is sufficient.
• Simple Styling: Avoid complicated handcrafted CSS styling. Keep styles simple and maintainable.
• Event Handling: Avoid event handling when data updates are involved - use direct function calls instead. Only use events when no data update is needed (e.g., pure UI interactions).
• State Management: Check src/renderer/ui/states.js to directly modify global variables (e.g., window.mode, window.currentWorkspace, window.currentFile). Use querySelector to tell other components to update their states. Avoid keeping local state copies when possible - prefer direct global state access.