From c2747e6c1dcae93101c5e9ab036d748129a1939f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 9 May 2026 16:02:18 +0000 Subject: [PATCH 1/2] docs: add Cursor Cloud specific instructions to AGENTS.md Co-authored-by: andykais-claude --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 51fb34fa..462353ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -890,3 +890,33 @@ Forager is a well-architected media management system with: - Migration-based schema evolution When working on this codebase, prioritize type safety, follow established patterns, write tests, and maintain the clean separation of concerns across layers. + +## Cursor Cloud specific instructions + +### Environment + +- **Deno stable** (not canary) must be used for the web package build. The Deno canary channel has a regression where dynamic `import()` of bare specifiers fails inside the `.deno/` node_modules directory during vite build. Use Deno stable 2.7.x. +- **FFmpeg** is pre-installed at `/usr/bin/ffmpeg` and `/usr/bin/ffprobe`. +- **No external services** are needed — the database is embedded SQLite and the web server is built into the CLI. + +### Running services + +- **GUI server**: `deno task --cwd packages/cli develop --config gui` starts the web UI on `127.0.0.1:8000`. Requires a YAML config file (see AGENTS.md main section for schema). A minimal config needs `core.database.folder`, `core.database.filename`, `core.thumbnails.folder`, `core.migrations.automatic: true`, and `web.port`. +- **Dev mode** (with HMR): `deno task develop` first builds the web package then starts the CLI GUI. This is the recommended dev workflow. + +### Key commands + +| Task | Command | +|------|---------| +| Lint (core) | `deno task --cwd packages/core lint` | +| Test (core) | `deno task --cwd packages/core test` | +| Test (CLI) | `deno task --cwd packages/cli test` (requires web build first) | +| Build (web) | `deno task --cwd packages/web build` | +| Format | `deno fmt` | +| Full dev | `deno task develop` | + +### Known test quirks + +- Core tests have 4 failures related to FFmpeg version-specific floating-point precision (duration values differ slightly from expected). These are not code bugs. +- CLI tests require the web package to be built first (`deno task --cwd packages/web build`). +- The `--env-file=../../.env` warning from CLI develop tasks is harmless if no `.env` file exists. From 1744a2117172c0393497b9d46575b7e41ab86c59 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 9 May 2026 16:25:03 +0000 Subject: [PATCH 2/2] docs: document Deno canary bare specifier regression and web build/dev commands Co-authored-by: andykais-claude --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 462353ed..f2126072 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -895,7 +895,7 @@ When working on this codebase, prioritize type safety, follow established patter ### Environment -- **Deno stable** (not canary) must be used for the web package build. The Deno canary channel has a regression where dynamic `import()` of bare specifiers fails inside the `.deno/` node_modules directory during vite build. Use Deno stable 2.7.x. +- **Deno stable** (not canary) must be used for the web package build. Deno canary has a regression where bare specifiers (e.g. `import 'zimmerframe'` inside `svelte/src/compiler/index.js`) are resolved as relative paths during vite's config evaluation, causing `Unable to load .../svelte/compiler` errors. The root cause: when vite loads vite.config.ts, it evaluates `@sveltejs/kit`'s `import_peer('svelte/compiler')` which loads `node_modules/svelte/src/compiler/index.js`; that file's `import 'zimmerframe'` is then incorrectly resolved as `./zimmerframe` instead of using Node module resolution. `nodeModulesDir: "manual"` + `npm install` does NOT fix this because the issue is in Deno canary's module loader (not the node_modules layout). Use Deno stable 2.7.x. - **FFmpeg** is pre-installed at `/usr/bin/ffmpeg` and `/usr/bin/ffprobe`. - **No external services** are needed — the database is embedded SQLite and the web server is built into the CLI. @@ -911,7 +911,8 @@ When working on this codebase, prioritize type safety, follow established patter | Lint (core) | `deno task --cwd packages/core lint` | | Test (core) | `deno task --cwd packages/core test` | | Test (CLI) | `deno task --cwd packages/cli test` (requires web build first) | -| Build (web) | `deno task --cwd packages/web build` | +| Build (web) | `deno task --cwd packages/web build` or `build:local` | +| Dev (web HMR) | `deno task --cwd packages/web dev` (vite dev on port 5173) | | Format | `deno fmt` | | Full dev | `deno task develop` |