tolaria/CLAUDE.md

CLAUDE.md — Laputa App

⛔ BEFORE EVERY COMMIT — Non-negotiable checklist

Run all of these. If any fails, fix before committing. No exceptions.

pnpm lint && npx tsc --noEmit       # lint + types
pnpm test                           # unit tests
pnpm test:coverage                  # frontend ≥70% coverage
cargo test                          # Rust tests
cargo llvm-cov --manifest-path src-tauri/Cargo.toml --no-clean --fail-under-lines 85
pre_commit_code_health_safeguard    # CodeScene ≥9.2 — if it fails, fix structurally (see below)

CI is a safety net, not a discovery tool. If CI catches something you didn't catch locally, that's a process failure. All these tools are available locally — use them while you code, not just at the end.

⛔ BEFORE FIRING laputa-task-done — QA on real vault

⚠️ TAURI APP ONLY — never test in browser (pnpm dev / localhost) The browser dev server has a fake HTTP server (/api/* routes, mock handlers) that doesn't exist in the real Tauri app. If it works in the browser but crashes in Tauri, it's broken. Always test in pnpm tauri dev.

1. Acquire lockfile: echo $$ > /tmp/laputa-qa.lock && trap "rm -f /tmp/laputa-qa.lock" EXIT
2. Kill other instances: pkill -x laputa 2>/dev/null || true; sleep 1
3. Start app: pnpm tauri dev from worktree
4. Switch vault to ~/Laputa (not demo)
5. Test the feature/fix with real mouse clicks (cliclick) on real notes
6. If task touches file save: verify git -C ~/Laputa diff shows changes
7. If QA fails → fix and re-run. Do NOT fire the signal until it passes.

Fire done signal only after QA passes:

rm -f /tmp/laputa-qa.lock
openclaw system event --text "laputa-task-done:<task_id>:<slug>" --mode now

⛔ CODE HEALTH — No shortcuts

If pre_commit_code_health_safeguard flags a file:

• Understand why — use code_health_review via CodeScene MCP
• Fix the structural problem (extract hooks, split components, reduce complexity)
• Never add a JSDoc comment, #[allow(...)], // eslint-disable, or as any just to pass the gate
• It's fine to take longer. False quality is worse than no quality.

---

Project

Tauri v2 + React + TypeScript desktop app. Reads a vault of markdown files with YAML frontmatter.

• Spec: docs/PROJECT-SPEC.md
• Architecture: docs/ARCHITECTURE.md
• Abstractions: docs/ABSTRACTIONS.md
• Wireframes: ui-design.pen
• Luca's vault: ~/Laputa/ (~9200 markdown files)

Tech Stack

• Desktop: Tauri v2 (Rust backend)
• Frontend: React 18 + TypeScript + BlockNote editor
• Tests: Vitest (unit), Playwright (E2E), cargo test (Rust)
• Package manager: pnpm

Architecture

• src-tauri/src/ — Rust backend (file I/O, git, frontmatter parsing)
• src/ — React frontend
• src/mock-tauri.ts — Mock layer for browser/test env (silently swallows Tauri calls — not a substitute for native app testing)
• src/types.ts — Shared TypeScript types

How to Work

• Never develop on main — always on task/<slug> branch
• Commit every 20–30 min — atomic commits, one concern per commit (feat:, fix:, refactor:, test:, docs:)
• Update docs/ when changing architecture, abstractions, or significant design
• Test as you go — write tests alongside code, not after

Testing

• Unit tests must cover real business logic, not "component renders"
• Every bug fixed manually → add a regression test
• Every new feature → new tests for new behavior paths
• pnpm test:coverage and cargo llvm-cov must pass before committing

Design File (every UI task)

Every task with UI changes needs a design file. Follow this process:

1. Open ui-design.pen first — study existing frames to understand the visual language, spacing, and component style before designing anything new.
2. Design in light mode — all existing designs use light mode. New frames must match. Never use dark mode for designs.
3. Create design/<slug>.pen for the new feature — additive only, NOT a copy of ui-design.pen.
4. When merging to main — merge your frames into ui-design.pen with proper layout:
   • Place frames in a logical area (group by feature area, not stacked on top of each other)
   • Leave at least 100px spacing between frames
   • Delete design/<slug>.pen after merging — the frames now live in ui-design.pen

mkdir -p design
# Study schema first:
node -e "const f=JSON.parse(require('fs').readFileSync('ui-design.pen','utf8')); console.log(JSON.stringify(f.children[0],null,2))"
# Start fresh:
echo '{"children":[],"variables":{}}' > design/<slug>.pen

macOS / Tauri Gotchas

• Option+N on macOS → special chars (¡, ™), not key:'N'. Use e.code or Cmd+N.
• Tauri menu accelerators: use MenuItemBuilder::new(label).accelerator("CmdOrCtrl+1") — decorative text in labels doesn't register shortcuts.
• app.set_menu() replaces the ENTIRE menu bar — include all submenus.

QA Scripts

bash ~/.openclaw/skills/laputa-qa/scripts/focus-app.sh laputa
bash ~/.openclaw/skills/laputa-qa/scripts/screenshot.sh /tmp/out.png
bash ~/.openclaw/skills/laputa-qa/scripts/shortcut.sh "command" "s"
bash ~/.openclaw/skills/laputa-qa/scripts/click.sh 400 300   # logical coords

Keyboard-First Principle (mandatory for every new feature)

Every feature must be reachable via keyboard. This is both a UX requirement and a QA requirement — Brian tests the native app using keyboard only (osascript key events, no mouse).

Before marking any task done:

• Can the feature be triggered/used without touching the mouse?
• If it requires clicking a button, add a command palette entry or keyboard shortcut
• Document the shortcut in the command palette or menu bar

If you add UI that is only reachable by mouse, you must also add a keyboard path (command palette entry, shortcut, or Tab-navigable focus). No exceptions.

Push Workflow (IMPORTANT — changed Feb 27, 2026)

Push directly to main — no PRs, no branches, no CI queue.

The pre-push hook runs all checks locally before the push goes through. This replaces remote CI.

# After QA passes and you're ready to ship:
git push origin main    # pre-push hook runs automatically

⛔ NEVER open a Pull Request

PRs on separate branches diverge from main with every merge, requiring continuous rebases and creating unnecessary conflicts. Always push directly to main. If the push fails (disk full, test failure, etc.) — fix the problem, then push again. There is no scenario where opening a PR is the right fallback.

⛔ NEVER use --no-verify

# FORBIDDEN — will be caught and rejected:
git push --no-verify
git commit --no-verify   # also forbidden for pre-push bypass

The hook runs: tsc, Vite build, frontend tests, frontend coverage, Rust coverage, Clippy, rustfmt, CodeScene. Fix any failures before pushing — do not skip.

If a check fails, fix the issue and push again. The hook is the gate — not remote CI.