fjrevoredo/mini-diarium/archive

tauri-agent-dev Skill

Metadata

• Plan Status: COMPLETED
• Created: 2026-05-22
• Last Updated: 2026-05-22 (sandbox journal config + WebView storage isolation added; full smoke test completed)
• Owner: Coding agent
• Approval: APPROVED

Implementation Status

• 2026-05-22: Self-check completed. Plan revised to drop Milestone 3 (Playwright fallback) after confirming agent-browser connect <port|url> is available. Script runner convention pinned to npx tsx. The initial assumption that MINI_DIARIUM_DATA_DIR alone would avoid sandbox config seeding was later disproven during smoke testing and corrected in the final implementation.
• 2026-05-22: Attempted Milestone 1 CDP smoke probe. Blocked: port 1420 (Vite dev server) was already held by an active tauri dev session belonging to the user (node PID 19076). User chose to pause all implementation work rather than have the agent kill their running session. No files written; one scratch log file (.agent-dev-probe.log) created at repo root from the failed probe attempt and pending cleanup.
• 2026-05-22: User asked to continue. Pre-resume check found no listeners on ports 1420/1421/9222/9223, so the original Milestone 1 blocker is cleared and the CDP smoke probe can proceed.
• 2026-05-22: Milestone 1 completed. Running tauri dev with WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222 exposed http://localhost:9222/json/version and http://localhost:9222/json; the page target URL was http://localhost:1420/. Teardown via taskkill /F /T succeeded and left ports 1420/1421/9222/9223 unbound.
• 2026-05-22: Task 2.1 completed. npx tsx scripts/agent-dev/start.ts --timeout 180 launched a sandboxed tauri dev, wrote .agent-dev/state.json, and exposed the expected CDP browser/page websocket URLs for http://localhost:1420/.
• 2026-05-22: Task 2.2 completed after hardening the process model. On Windows, the initial launcher PID exits early, so start.ts now records the two durable child roots (cmd /S /C "bun run dev" and cargo run ...) as managed_pids. stop.ts kills every recorded root, verifies port 9222 is closed, and only then removes sandbox/state.
• 2026-05-22: Task 2.3 completed. npx tsx scripts/agent-dev/probe.ts reports one-line JSON health for a live sandboxed session and correctly resolves the page target even when startup first reaches the browser CDP endpoint before /json exposes the app page.
• 2026-05-22: Task 2.4 completed. bun run agent:dev:start --help, bun run agent:dev:stop --help, and bun run agent:dev:probe --help all execute through package.json.
• 2026-05-22: Task 2.5 completed and Milestone 2 exit criteria satisfied. A full bun run agent:dev:start → bun run agent:dev:probe → bun run agent:dev:stop cycle succeeded, and git status --short did not surface .agent-dev/.
• 2026-05-22: Task 4.1 completed. skill-creator initialized .agents/skills/tauri-agent-dev/; the draft SKILL.md was replaced with a repo-specific Windows-only workflow, validated with quick_validate.py, and agents/openai.yaml was corrected to keep the literal $tauri-agent-dev prompt.
• 2026-05-22: Tasks 4.3 and 4.4 completed. tauri-agent-dev is not in PLUGIN_SKILLS, bun run sync-skills linked it into .claude/skills/tauri-agent-dev, and the linked SKILL.md resolves correctly.
• 2026-05-22: Task 4.2 completed. The drafted skill was exercised in a real session, adjusted to document sandbox journal config seeding and WebView storage isolation, and no further wording changes were requested before continuing implementation.
• 2026-05-22: Follow-up hardening after the first smoke attempts: start.ts now seeds sandbox/app/config.json with one active journal because initializeAuth() still depends on journal metadata even when MINI_DIARIUM_DATA_DIR overrides the backend DB path.
• 2026-05-22: Follow-up hardening after the first smoke attempts: agent-dev sandboxing now isolates browser-side state too. start.ts sets MINI_DIARIUM_WEBVIEW_DATA_DIR, and src-tauri/src/lib.rs applies WebviewWindowBuilder::data_directory(...), so fresh sandboxes no longer inherit stale localStorage preferences such as aggressive auto-lock timers.
• 2026-05-22: Milestone 5 completed. Real UI smoke test succeeded against a live sandboxed dev app: created a password journal, opened Preferences → Security, enabled Lock after inactivity, clicked Save, verified JSON.parse(localStorage.getItem('preferences')).autoLockEnabled === true, reopened Preferences → Security, confirmed the checkbox remained checked, and captured a screenshot at .agent-dev/smoke-autolock-preferences.png.
• 2026-05-22: Task 5.2 completed after a delayed recheck. An immediate process/port sample raced the shutdown, but the follow-up verification showed no live bun/cargo/mini-diarium processes, only TIME_WAIT sockets, and bun run agent:dev:probe correctly returned {"running":false,"reason":"no state file"}.

Self-Check Findings (2026-05-22)

Empirical verifications performed before approval:

• `agent-browser connect <port|url>` is a real, documented command. Verified via agent-browser --help and agent-browser skills get electron. The electron skill explicitly documents the launch-with-remote-debugging-port + connect pattern, which is exactly what we need. Milestone 3 (Playwright fallback wrapper) is now SKIPPED.
• Backend DB path override is only half the story. MINI_DIARIUM_DATA_DIR makes the backend use <dir>/diary.db directly (src-tauri/src/lib.rs:142-147), but frontend startup still depends on list_journals() / active_journal_id from config.json (src/state/auth.ts). So sandbox mode must seed sandbox/app/config.json with one active journal. Fresh sandbox then lands on PasswordCreation; a reused sandbox lands on PasswordPrompt.
• `bun run tauri` → `bun scripts/tauri-dev.js` → `bun x tauri dev`, spreading process.env. Our env vars (WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS, MINI_DIARIUM_DATA_DIR, MINI_DIARIUM_APP_DIR) propagate cleanly.
• Script runner: `npx tsx` is the project convention for .ts scripts (used by validate-locales.ts and sync-languages.ts). Use it here too.
• `sync-skills.js` links via NTFS junction on Windows from .agents/skills/<name>/ to .claude/skills/<name>/. tauri-agent-dev is not in PLUGIN_SKILLS — no collision.
• Vite HMR risk overblown. Vite swaps modules within a stable page target; CDP target ID does not change. Retry-on-disconnect was over-engineering. Drop it from the plan; add only if M5 smoke test surfaces a real issue.
• WebView state needs its own sandbox too. Without a dedicated WebView data dir, localStorage leaks across runs and can re-enable old preferences such as a 5-second auto-lock timer. Final implementation sets MINI_DIARIUM_WEBVIEW_DATA_DIR and uses WebviewWindowBuilder::data_directory(...) to keep browser-side state inside .agent-dev/sandbox/webview/.
• PowerShell `@`-ref gotcha — agent-browser's own SKILL.md documents that @e174 must be single-quoted in PowerShell. Surface this in our SKILL.md (user is on Windows).

Status Legend

• Plan Status values: DRAFT, QUESTIONS PENDING, READY FOR APPROVAL, APPROVED, IN PROGRESS, COMPLETED, BLOCKED
• Task/Milestone Status values: TO BE DONE, IN PROGRESS, COMPLETED, BLOCKED, SKIPPED

Goal

Give the coding agent a reliable, repeatable way to spawn the Mini Diarium Tauri v2 dev binary, drive its UI programmatically (click/type/eval/screenshot/inspect localStorage), and tear it down cleanly — so that UI bug verification ("does the auto-lock toggle actually persist?") can be done by the agent end-to-end without the human in the loop. Targets Windows-only for v1 because that's where the WebView2-CDP path works; macOS and Linux are out of scope.

This complements — does not replace — the existing tauri-driver + WebdriverIO E2E harness, which remains the CI/regression layer. This skill is for ad-hoc manual-style probing during a coding session.

Scope

• New skill directory .agents/skills/tauri-agent-dev/ with SKILL.md describing the workflow.
• Three new repo scripts under scripts/agent-dev/: start.ts, stop.ts, probe.ts.
• Optionally a fourth script control.ts only if the validation step in Milestone 1 confirms agent-browser cannot speak raw CDP. Decided at implementation time, not pre-committed.
• Three new package.json npm scripts: agent:dev:start, agent:dev:stop, agent:dev:probe.
• .gitignore entry for .agent-dev/ (state file + sandbox dirs).
• Skill triggers on phrases like "manually test", "drive the dev app", "verify in the real UI", "agent dev mode", "spawn the dev app", "open the running app and check…".
• Reuse existing env-var sandbox: MINI_DIARIUM_DATA_DIR, MINI_DIARIUM_APP_DIR, and MINI_DIARIUM_WEBVIEW_DATA_DIR set to .agent-dev/sandbox/ by default so DB/config/browser state all stay isolated. Opt-in --use-real-config flag for the rare case where a bug only repros against real state.
• Sync skill via bun run sync-skills (project's existing pipeline that links .agents/skills/ into .claude/skills/).

Non-Goals

• Do NOT add macOS or Linux support. WKWebView has no remote debugging; WebKitGTK uses a different protocol. Start scripts must exit early on these platforms with a clear message.
• Do NOT replace or modify the existing wdio.conf.ts E2E harness.
• Do NOT set MINI_DIARIUM_E2E=1. That env var forces an 800×660 viewport and disables tauri-plugin-window-state — wrong for interactive driving where the agent needs realistic UI sizing.
• Do NOT bundle or wrap the agent-browser skill. It's already a separate skill; this skill provides only the spawn/sandbox layer and points agent-browser at the CDP endpoint.
• Do NOT support production builds. Dev only.
• Do NOT implement recording/playback of agent sessions.
• Do NOT publish this skill outside the repo. Internal tooling only.

Assumptions

• The user is on Windows 10/11 with WebView2 installed (confirmed: project's primary dev environment).
• WebView2 honors WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=<port> and exposes a CDP endpoint at http://localhost:<port>/json/version once the webview is ready. (Standard Chromium flag pass-through; documented behavior.)
• bun run tauri dev is the canonical dev command (already wired in package.json).
• The existing env-var contract MINI_DIARIUM_DATA_DIR / MINI_DIARIUM_APP_DIR (read only in src-tauri/src/lib.rs) is sufficient for a clean sandboxed config — confirmed by the E2E setup in wdio.conf.ts:254-270.
• Port 9222 (default Chrome remote-debugging port) does not collide with any other dev tool the user runs. Configurable via env var or CLI flag for the edge case where it does.
• Port 4444 (tauri-driver) is reserved by E2E; we use 9222 to avoid stomping on it. Both can run simultaneously in principle.
• The agent-browser skill listed in this project's available skills can connect to a custom CDP endpoint (connectOverCDP(http://localhost:9222)). This is the central technical assumption — Milestone 1 validates it before any other work proceeds.
• Vite's HMR will occasionally tear down + reattach the CDP target on hot reload. The wrapper / usage docs note this and instruct the agent to retry on disconnect.
• tsx is available as a runtime for .ts scripts (already used by other repo scripts; confirm in package.json before relying on it).

Open Questions

• None settled at plan-draft time. One discovery moment is Milestone 1 (agent-browser CDP support); the rest of the plan branches on its outcome.

Milestones

Milestone 1: Verify WebView2 CDP Exposure (Smoke Spike)