commit 0496e1390b11ba589d02b212cc1cec4fcce573f2 Author: Anthony GAEREMYNCK <1@anthony.sh> Date: Sun Aug 2 14:27:50 2026 +0200 Add design spec for Ombrora hub landing page Astro static site, FR/EN path-based i18n, light/dark theming, hub linking to CVE Watch and Convert services. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a1bda99 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,107 @@ +## Approach +- Read existing files before writing. Don't re-read unless changed. +- Thorough in reasoning, concise in output. +- Skip files over 100KB unless required. +- No sycophantic openers or closing fluff. +- No emojis or em-dashes. +- Do not guess APIs, versions, flags, commit SHAs, or package names. Verify by reading code or docs before asserting. + + +## MCP Tools: code-review-graph + +**IMPORTANT: This project has a knowledge graph. ALWAYS use the +code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore +the codebase.** The graph is faster, cheaper (fewer tokens), and gives +you structural context (callers, dependents, test coverage) that file +scanning cannot. + +### When to use graph tools FIRST + +- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep +- **Understanding impact**: `get_impact_radius` instead of manually tracing imports +- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files +- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for +- **Architecture questions**: `get_architecture_overview` + `list_communities` + +Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need. + +### Key Tools + +| Tool | Use when | +| ------ | ---------- | +| `detect_changes` | Reviewing code changes — gives risk-scored analysis | +| `get_review_context` | Need source snippets for review — token-efficient | +| `get_impact_radius` | Understanding blast radius of a change | +| `get_affected_flows` | Finding which execution paths are impacted | +| `query_graph` | Tracing callers, callees, imports, tests, dependencies | +| `semantic_search_nodes` | Finding functions/classes by name or keyword | +| `get_architecture_overview` | Understanding high-level codebase structure | +| `refactor_tool` | Planning renames, finding dead code | + +### Workflow + +1. The graph auto-updates on file changes (via hooks). +2. Use `detect_changes` for code review. +3. Use `get_affected_flows` to understand impact. +4. Use `query_graph` pattern="tests_for" to check coverage. + +## Local environment / running tests + +- `.env` holds **production** credentials (o2switch host, real DB name/password). Never load it for local runs or tests. +- `.env.local` holds the local dev DB credentials (`DB_HOST=127.0.0.1`, `DB_USER=convert_user`, `DB_NAME=file_converter`, `DB_PASSWORD=change_me`). This is what local testing should use. +- `src/config.js` uses `dotenv/config`, which only loads `.env` and does not override variables already present in `process.env`. There's no vitest/dotenv wiring that picks up `.env.local` automatically. +- To run tests locally without touching prod config, pass the `.env.local` values as inline env vars so they take precedence before `dotenv/config` runs, e.g.: + ``` + DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run + ``` +- A local MariaDB is expected to already be running on `127.0.0.1:3306` with the `file_converter` DB and `convert_user` credentials seeded. +- Known pre-existing failures unrelated to any fix: `test/cleanup.test.js` ("deletes an expired pending job...") and `test/jobs/jobRepository.test.js` ("finds expired jobs and allows deleting them") — both fail on `main` independent of other changes (looks like a clock/timezone mismatch around `expiresAt` comparisons, not yet root-caused). Don't assume a change caused these; verify against `main` first if they show up again. + +### Manual end-to-end testing (starting server.js/worker.js yourself) + +- This dev machine typically already has its own long-running `node src/server.js` / `node src/worker.js` (and sometimes `npm run dev` for the frontend) processes started outside the session, from before any given conversation begins. Before manually verifying a change end-to-end, check for them first: `powershell -NoProfile -Command "Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | Select-Object ProcessId,CommandLine"`. +- If a pre-existing worker is running, it loaded `src/converters/*.js` at its own start time and will keep running that in-memory code until restarted — it does not pick up edits made later in the session. If you start a *second*, freshly-spawned worker to test new converter code, both workers poll the same DB and race for pending jobs; if the stale one wins, the job fails with a misleading error (e.g. "No converter registered for X -> Y" for a pair that was, in fact, just added) even though the new code is correct. Don't conclude the new code is broken from a failure like this without first checking whether an older worker process grabbed the job. +- Safe options once you notice this: only kill/clean up processes you started yourself in the session (identifiable by matching the exact command line you launched); never kill or restart the user's pre-existing `server.js`/`worker.js`/`npm run dev` instances without asking, since that's their running environment. If you want a real end-to-end confirmation, tell the user their existing server/worker needs restarting to pick up the change — don't restart it for them silently. +- `curl -F "files=@/tmp/somefile"` fails with exit code 26 ("Failed to read local file") in this Git Bash environment when the path is under `/tmp`. Write the fixture under the project directory instead (e.g. `./scratch-test.md`) and reference it with a relative path in the `-F` flag; delete it afterward. + +## Deployment (o2switch) + +- o2switch is shared hosting: no compiler toolchain, no root access. Any dependency with a native/binary component must ship as a precompiled binary — it cannot be built from source on the server. +- `sharp` (libvips) and `puppeteer` (bundled Chromium) are the current binary dependencies in `package.json`. Install them so npm fetches the prebuilt binary for the target platform/arch rather than triggering a source build. +- Before adding any new dependency with native bindings, confirm it publishes prebuilt binaries for o2switch's platform/arch — otherwise it will fail to install or run there. +- **The o2switch nodevenv/Passenger setup ("Setup Node.js App" in cPanel) only supports a single `package.json`/`node_modules` for the whole registered app — not one per subfolder.** Verified by directly debugging a failed `frontend/` build: `npm install --prefix frontend --include=dev` (root's own `build` script) and even a plain `npm install` run with `cd frontend` first (confirmed via `pwd` to genuinely be inside `frontend/`) both completed "successfully" (correct, unmodified `frontend/package-lock.json`, real `resolved` entries for every package) yet never created a `frontend/node_modules` directory on the server at all. Meanwhile `vite`/`@vitejs/plugin-react` (already present as root devDependencies) resolved fine during the build — only packages that exist *exclusively* in `frontend/package.json` (`react-router-dom`, `react-i18next`, `i18next`, `@phosphor-icons/react`) failed to resolve, with Vite/Rolldown erroring `Rolldown failed to resolve import "react-router-dom"`. + - **Fix (applied):** every runtime package `frontend/src/**` imports must also be listed in the **root** `package.json`'s `dependencies` (not just `frontend/package.json`'s) — `react`/`react-dom` already were; `react-router-dom`, `react-i18next`, `i18next`, `@phosphor-icons/react` were added there too. Root's single `node_modules` is an ancestor directory of `frontend/src/`, so Node/Vite's normal upward `node_modules` resolution walk finds them there even with no `frontend/node_modules` on the server. + - `frontend/package.json` still declares the same packages in its own `dependencies` — that's intentional, not stale duplication. It's what makes local dev (`npm run dev` inside `frontend/`, which gets a real, normal `frontend/node_modules` on a dev machine) work independently of this server-only constraint. When adding a new frontend runtime dependency, add it to **both** `package.json` files (frontend's own, for local dev; root's, for the o2switch build) and run `npm install` in both places to keep both lockfiles in sync. + - `frontend/package.json`'s `devDependencies` (`vite`, `@vitejs/plugin-react`, `oxlint`, `@types/react*`) do **not** need mirroring to root — only the ones already there (`vite`, `@vitejs/plugin-react`) are actually required for the production build to run at all; `oxlint`/`@types/*` are dev-only tooling never invoked during `npm run build`. + +## Database schema & migrations + +- `prisma/schema.prisma` is the source of truth for the `conversion_jobs` schema; `prisma/migrations/` is its version history. `db/schema.sql` no longer exists. +- Prisma CLI commands (`prisma migrate dev`, `prisma migrate deploy`, `prisma generate`) need `DATABASE_URL` in their own process environment, separate from the app. Compute it from the same `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` values used for local tests, via `node scripts/printDatabaseUrl.js` — never write `DATABASE_URL` into `.env` or `.env.local`. +- **`prisma migrate dev` does NOT work against the local dev DB** — verified by actually running it (`DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate dev --name test_shadow_db_probe`). It needs to create/drop a temporary shadow database to detect schema drift, and the local `convert_user` does not have `CREATE DATABASE`/`DROP DATABASE` privileges, so it fails immediately with: + ``` + Error: P3014 + Prisma Migrate could not create the shadow database. Please make sure the database user has permission to create databases. + Original error: Error code: P1010 + User was denied access on the database `prisma_migrate_shadow_db_...` + ``` + No migration folder is created when it fails this way (it errors before writing anything), so nothing needs cleaning up afterward. Do not use `migrate dev` in this project until `convert_user`'s privileges change. +- To create a new migration locally after editing `prisma/schema.prisma`, use the shadow-database-free fallback instead. Note this is **not** the same pattern Task 3 used for the `0_init` baseline — Task 3 used `--from-empty` (diffing against a blank schema), which is a different mode that also happens not to need a shadow database, but is not applicable here since the local DB is not empty. The verified fallback for an already-baselined DB is `--from-schema-datasource` (introspects the live DB's actual current structure — a real DB connection, but not a shadow database) diffed against `--to-schema-datamodel` (reads the target state straight from a schema file, no DB connection at all): + ``` + DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage \ + DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate diff \ + --from-schema-datasource prisma/schema.prisma --to-schema-datamodel prisma/schema.prisma --script > /tmp/migration.sql + ``` + This was verified twice against the local dev DB: with `prisma/schema.prisma` unchanged it printed `-- This is an empty migration.` (no shadow database requested, no error); with a throwaway copy of the schema (an extra `notes String? @db.Text` field on `ConversionJob`, passed as `--to-schema-datamodel `) it printed a correct `ALTER TABLE conversion_jobs ADD COLUMN notes TEXT NULL;` — again with no shadow database involved. The earlier documented fallback here (`--from-migrations prisma/migrations`) was wrong: `--from-migrations` internally requires `--shadow-database-url` too, so it fails for the same P3014 reason `migrate dev` does; it was never actually tested before being written down. + + Write the generated SQL to a path under the OS temp directory (e.g. `/tmp/migration.sql`), never to a file in the repo (an untracked `migration.sql` in the repo root is easy to accidentally commit). Review it, then manually create the next `prisma/migrations/_/migration.sql` folder with that content, and mark it applied without executing it (since you'll apply it for real via `migrate deploy` or by hand): + ``` + DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate resolve --applied _ + ``` + Delete the temp SQL file once it's been copied into the migration folder. +- To apply pending migrations in production: with the real `DB_*` values loaded from `.env`, run `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy` before starting the app. +- **ONE-TIME step, required before the very first `migrate deploy` against any environment whose `conversion_jobs` table predates Prisma** (this includes o2switch production, which still has the table created by hand from the now-deleted `db/schema.sql`, but no `_prisma_migrations` tracking table): do **not** run `migrate deploy` first. Instead, baseline that environment exactly like Task 3 did locally: + ``` + DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate resolve --applied 0_init + ``` + This tells Prisma that `0_init` is already applied (the table already exists) without trying to `CREATE TABLE` it again. Run this once, ever, per environment — after that, `migrate deploy` is the correct command for all subsequent deployments to that environment. Running `migrate deploy` first (without this baseline step) against such an environment will fail with a MySQL "table already exists" error and leave Prisma's migration history in a failed state requiring manual recovery. diff --git a/docs/superpowers/specs/2026-08-02-ombrora-hub-landing-design.md b/docs/superpowers/specs/2026-08-02-ombrora-hub-landing-design.md new file mode 100644 index 0000000..a2d76bc --- /dev/null +++ b/docs/superpowers/specs/2026-08-02-ombrora-hub-landing-design.md @@ -0,0 +1,131 @@ +# Ombrora Hub Landing Page — Design + +## Purpose + +A landing page at `www.ombrora.com` acting as a hub linking to Ombrora's existing services: + +- CVE Watch — a CVE-tracking blog, published in French (`cve-fr.ombrora.com`) and English (`cve-en.ombrora.com`) as two locale-specific deployments of the same underlying service. +- Convert (`convert.ombrora.com`) — a file conversion tool (documents, audio, images, video, archives). + +More services will be added to the hub over time; the design must make that cheap. + +## Requirements + +- Built with Astro, static output only (no SSR/SSR adapter) — required for SEO and for hosting on static shared hosting. +- Multilingual: French and English, via path-based routing (`/en/`, `/fr/`), symmetric (no unprefixed default locale route). +- Deployed to o2switch shared hosting: plain HTML/CSS/JS output uploaded to the host, no server-side runtime, `.htaccess` available for Apache-level rules. +- SEO-optimized: prerendered HTML, meta tags, hreflang, sitemap, robots.txt. +- Supports light and dark mode. +- No existing brand assets — visual direction is proposed as part of this design. +- Scope is minimal: hero + service cards + footer. No About/Contact/legal pages, no analytics. + +## Tech stack & project structure + +- Astro (latest stable), `output: 'static'` (Astro's default — no adapter needed). +- No UI framework — plain Astro components and CSS are sufficient for this scope. +- npm as package manager. + +``` +src/ + components/ Header.astro, Footer.astro, ServiceCard.astro, LanguageSwitcher.astro, ThemeToggle.astro + i18n/ en.ts, fr.ts (UI strings), services.ts (service list, per-locale copy) + layouts/ BaseLayout.astro (head/meta/hreflang/OG tags, theme init script) + pages/ + en/index.astro + fr/index.astro +public/ + .htaccess (root language redirect) + robots.txt +astro.config.mjs (i18n config, sitemap integration) +``` + +## Routing & i18n + +`astro.config.mjs`: + +```js +i18n: { + locales: ['en', 'fr'], + defaultLocale: 'en', + routing: { prefixDefaultLocale: true } +} +``` + +This produces symmetric `/en/` and `/fr/` routes (no bare unprefixed locale route). Astro's `astro:i18n` helpers (e.g. `getRelativeLocaleUrl`) generate cross-locale links for the language switcher and hreflang tags. + +`public/.htaccess` handles the bare `www.ombrora.com/` root with a real server-side redirect based on the `Accept-Language` header: + +```apache +RewriteEngine On +RewriteCond %{REQUEST_URI} ^/$ +RewriteCond %{HTTP:Accept-Language} fr [NC] +RewriteRule ^$ /fr/ [R=302,L] +RewriteCond %{REQUEST_URI} ^/$ +RewriteRule ^$ /en/ [R=302,L] +``` + +French-preferring browsers land on `/fr/`; everything else defaults to `/en/`. No JavaScript redirect needed. + +## Content model + +`src/i18n/services.ts` is the single source of truth for the service cards. `url` may be a plain string (same URL regardless of locale) or a `{ en, fr }` object (locale-specific URL) — `ServiceCard.astro` resolves whichever shape is present against the current locale. Adding a future service, whether single-domain or per-locale-domain, means adding one entry here. + +```ts +export const services = [ + { + id: 'cve', + url: { en: 'https://cve-en.ombrora.com', fr: 'https://cve-fr.ombrora.com' }, + name: { en: 'CVE Watch', fr: 'Veille CVE' }, + description: { en: '...', fr: '...' }, + }, + { + id: 'convert', + url: 'https://convert.ombrora.com', + name: { en: 'Convert', fr: 'Convert' }, + description: { en: '...', fr: '...' }, + }, +] +``` + +Note: CVE Watch is one logical service with two locale-specific deployments (matching the existing `cve-fr`/`cve-en` split), rendered as a single card whose link target depends on the hub's current locale — not two separate cards. + +`src/i18n/en.ts` / `fr.ts` hold flat key-value UI strings (hero title/subtitle, nav labels, footer text), looked up directly in templates (e.g. `t.hero.title`) — no i18n library needed for this scope. + +## Pages & components + +- **BaseLayout.astro**: ``, meta description, canonical URL, hreflang alternates (en, fr, x-default → en), Open Graph/Twitter card tags, favicon, global CSS, and the pre-paint theme-init script (see Theming). +- **Header.astro**: Ombrora wordmark, LanguageSwitcher (links to the equivalent page in the other locale, not just the other locale's root), ThemeToggle. +- **Hero**: short tagline introducing Ombrora as a hub for security and utility tools. +- **ServiceCard.astro × 2**: name, one-line description, a tag (e.g. "CVE Blog", "File Converter"), outbound link resolved per current locale. +- **Footer.astro**: copyright, optional contact mailto. No legal/About pages in this scope. + +## Visual direction + +Dark, technical aesthetic fitting a security/CVE tracker and dev utility tool: neutral dark/light backgrounds, one accent color (cool cyan or violet) for links and highlights, a clean sans-serif for body text with a monospace accent for tags/labels. No decorative gimmicks. + +## Theming (light & dark mode) + +Implemented via CSS custom properties (`--bg`, `--fg`, `--accent`, etc.) on `:root`, with `[data-theme="dark"]` / `[data-theme="light"]` overrides. + +- **Default**: follows system preference (`prefers-color-scheme`), applied by an inline `