Files
dragonroll/AGENTS.md
Gitea OpenCode Agent cd1e3cb125
All checks were successful
Test / test (push) Successful in 2s
Fix issue #109: Add map sync
2026-10-16 16:06:21 +00:00

22 KiB

AGENTS.md — Dragonroll

Orientation map, kept short on purpose. Read the file you are about to change: this tells you where to look and what will bite you, it does not replace the code. Longer docs: dragonroll-foundry/README.md, discord-bot/README.md, obsidian-plugin/README.md.

1. What this is

Free/open-source helper for tabletop RPG campaigns (campaigns, markdown notes, folders, characters, items, maps, dice widgets, sounds).

  • backend/ — Node + Express 5 + Mongoose 9 (MongoDB) REST API, JWT auth, CommonJS, entry src/index.js.
  • frontend/ — Nuxt 4 / Vue 3 (<script setup>), SCSS, axios, marked, mitt, motion, entry app/app.vue. Two pages: the app and /docs (§5.1).
  • discord-bot/ — Discord bot (slash commands) that talks to the backend with a shared service secret, no login.
  • dragonroll-foundry/ — Foundry VTT module (scripts/api.js) + optional read-only snapshot bridge.
  • obsidian-plugin/ — plain JavaScript Obsidian plugin that imports/pushes campaign notes.
  • tests/ — npm test (node --test, no dependencies installed): Foundry sync toggle and pairing status, map pins and tokens, sidebar entries, the /docs pages.

No DB seeding, no migrations, no linter/formatter, no Pinia/Vuex. Git: default branch master on a self-hosted Gitea; .gitea/workflows/deploy.yml builds and deploys Docker images on push to master, .gitea/workflows/test.yml runs npm test on every branch.

2. Commands

pnpm comes from corepack (packageManager in package.json); COREPACK_ENABLE_DOWNLOAD_PROMPT=0 keeps corepack from asking in non-interactive shells.

pnpm install           # whole workspace, one lockfile (`-r` / `--filter <pkg>` for a single one)
pnpm dev               # backend :5000 + frontend :3000 + discord-bot + scripts/run-foundry.js
pnpm dev:backend       # or dev:frontend | dev:discord-bot
pnpm --filter ./frontend run build     # or preview
pnpm test

No start script in backend/frontend and no lint command. Verification = run the dev server and exercise the flow (GET /api/test returns a JSON hello).

There is no PM2 and no ecosystem.config.js: pnpm dev starts every dev process at the same time through the workspace (concurrently only labels them and kills them together), and production runs from the compose images (CMD of each Dockerfile).

Env: backend/.env (PORT is read but ignored, DB_URI), frontend/.env (NUXT_PUBLIC_API_BASE_URL), both gitignored; the .env.production files are committed. backend/src/index.js loads .env.$NODE_ENV when NODE_ENV is set, otherwise .env. The server always listens on 5000.

3. Backend

src/models/ one Mongoose schema per file · src/routes/ thin Express routers · src/services/ shared infra (keys.js JWT secret, passport.js JwtStrategy, storage.js multer → src/uploads/ served publicly at /api/public, rate-limiter.js 150 req/60 min, service-links.js the service pairing in §4, *-foundry.js Foundry document → Dragonroll field mappers).

Auth chain, order matters (src/index.js): /api/public/* static → /api/user, /api/discord, /api/link, /api/foundry (link + sync, token-authenticated) are mounted before checkAuth = passport.authenticate('jwt', {session:false}); everything after it (/api/campaign|note|folder|actor|item|map|foundry) is JWT-protected. checkAuth is assigned without const (implicit global). New user routes are public unless the handler calls passport.authenticate('jwt', {session:false}) inline (/upload-avatar, /update-settings, /get-settings). JWT: payload {_id, username, name, email, admin, settings}, 48h; req.user is the Mongoose document, so routes use req.user.id.

CORS allows any origin for the service link/sync paths only; the app-wide CORS whitelists http://localhost:3000 and nothing else (production hides behind the nginx same-origin proxy).

Response envelope — always HTTP 200, no real status codes:

{ "status": "ok", ...payload }
{ "status": "error", "msg": "errors.internal" }   // msg is an i18n KEY, not prose

Common keys: errors.missing-data, errors.notfound, errors.internal, unauthorized, login.errors.invalid-credentials, register.errors.email-username-exists. GET /user/has-admin returns status: 'init' when no admin exists yet (→ first-run registration).

Authorization — single-tenant: a campaign belongs to createdBy, everything else hangs off a campaign, and handlers check ownership with a userOwnsCampaign(campaignId, userId) helper that is duplicated per router file (match that unless you refactor all at once). settings, color, description are free-form fields.

Models (* = required; notes and folders are always ordered date: -1):

  • User — name*, username*, email* (both unique), password (bcrypt, 10 rounds), admin, image, setupCode, settings
  • Campaign — name*, createdBy*→User, description, color, settings, foundryWorldId/foundryWorldTitle/foundrySystem, foundrySyncTokenHash (select: false), discordGuildId
  • Note — title, content (markdown source), campaign*, folder (null = root), color, foundryPageId
  • Folder — name*, campaign*, parentFolder (null = root, self-ref), color
  • Actor — name*, campaign*, foundryActorId (unique per campaign), discordUserId (the Discord player holding the character, unique per campaign — set only by routes/discord.js), plus free-form sheet fields (type, species, className, level, abilityScores, armorClass, speed, proficiencies, traits, spells, image) and inventory[{name,quantity,weight}] (flattened Foundry items, not Item docs)
  • Item — name*, campaign*, foundryItemId (unique per campaign), foundryNames, category, rarity, quantity, weight, properties, description
  • Map — name*, campaign*, image (filename in src/uploads, or a full URL a synced scene's picture arrives as), gridSize/offsetX/offsetY/scale (image px), pins[{note→Note, x, y}] (addressed by the pin's own _id), tokens[{actor→Actor, x, y}] (the centre of the grid cell the token stands in, also addressed by its own _id), foundrySceneId (the Foundry scene this map mirrors, unique per campaign)
  • ServiceLinkRequest — the pending/completed service pairings of §4; DiscordGuildLink maps a Discord guild to the Dragonroll user who claimed it

API surface (all under /api, all {status,msg}):

  • user — register, verify-setup?code=, setup?code=, login ({usermail,password}, accepts username or email → {token}), upload-avatar (multipart image, JWT) / retrieve-avatar?username=, has-admin, update-settings / get-settings. Files fetched from /api/public/<filename>.
  • campaign — create, update, list, retrieve/:id, services + service-unlink (what is linked to a campaign)
  • note — list?campaign= (root notes + folders with parentFolder), subfolder/list?campaign=&folder=, all?campaign= (titles only, for the map pin picker), retrieve/:id, create, update (partial), delete
  • folder — list, create, update, rename, delete (recursive: inner notes go to folder: null, subfolders re-parent then delete)
  • actor — list, create, update (partial, ownership checked), upload-image?actor= (multipart), delete
  • item — list, create, update (partial), delete
  • map — list, create (multipart image or JSON), update (multipart to replace the photo), delete, pin ({id,note,x,y}, re-pinning moves the marker), unpin ({id,pin}), place-token ({id,actor,x,y}, snapped to a cell centre, re-placing moves the token), remove-token ({id,token})
  • foundry — read-only proxy over the bridge (/world, /actors, /characters, /items, /actors/:id, /items/:id, /actors/:id/items), needs FOUNDRY_API_URL; POST /import ({campaign, kind: 'actors'|'items'}, the sidebar's "force import from Foundry") pulls that world's whole list off the bridge through the sync's writers, so rows the campaign already has are written over, and answers {imported, updated}; /icons?campaign=&dir=&offset= lists one folder of the world's core icons/ library (the bridge reads it from DRAGONROLL_FOUNDRY_DATA_PATH) and answers {dir, parent, folders, files[{path,name,url}], next}, the icons paged so the library stays lazy to load

4. Service integrations (Foundry, Discord, Obsidian)

Every external service links to a campaign the same way, never with a Dragonroll login: it calls POST /api/link/start, shows the returned sign-up link, and the user opens it in the frontend (/link/authorize, handled by views/ServiceLinkAuthorize.vue outside the window app), signs in and picks a campaign at POST /api/link/complete; the service then redeems its credential once at POST /api/link/pickup (one-time; losing it means a new link). Proofs differ per service (services/service-links.js): the Discord bot proves itself with the shared secret header, Foundry and Obsidian only hold their link code, so what a link grants is decided by the user. Codes are hashed at rest, expire after 10 min, and Obsidian gets a long-lived (365 d) token back.

Foundry then syncs with that token on /api/foundry/sync/* (routes/foundry-link.js, mounted before the JWT guard; CORS opened for it): snapshot (actors + world items, fullSync also prunes), item-snapshot, item-delete, scenes (the world's scenes as the campaign's maps, fullSync also prunes), scene-delete, characters, items, notes / map-note, status, map / map-item, delete. Rules:

  • Identity is foundryActorId / foundryItemId (unique per campaign, partial index); a Foundry document carrying the dragonroll-foundry.actorId / .itemId flag adopts the matching Dragonroll row.
  • Only the world's item directory reaches the item list (Syndria98/dragonroll#67) — snapshotItemSources reads body.items (game.items) alone; gear embedded in a character is that actor's inventory (see the Actor model), not an Item. A world item still folds into a hand-made or renamed row it matches by name (foundryNames), so a rename does not resurrect a duplicate. services/item-foundry.js returns null for non-gear types and those are skipped.
  • Item folders mirror the world's item directory (Folder.foundryFolderId, target item): every push carries the whole tree and the world owns its names and nesting. color is the one field the campaign sets too, so it travels back with the folders GET /foundry/sync/items answers with ({items, folders}) and the module writes it onto the world's folder.
  • A world's scenes arrive as its campaign's maps (Syndria98/dragonroll#99): POST /foundry/sync/scenes writes one Map per scene through saveFoundryScene, and only the scene's background picture and grid cross over (services/map-foundry.js: gridSize from grid/grid.size, the offsets from flags.core.shiftX/.shiftY) — scale, the folder, the pins and the tokens stay with the campaign and nothing of a map goes back to the world. Identity is Map.foundrySceneId (unique per campaign), a dragonroll-foundry.mapId flag or a hand-made unmapped map of the same name; a scene with no picture makes no map. POST /foundry/sync/scene-delete drops the map of a deleted scene, and only the full list the module sends when the world links or loads prunes.
  • Notes reach the world as journal pages, one way (Syndria98/dragonroll#98): the module reads GET /sync/notes and stands every campaign note as a page of one world JournalEntry named Dragonroll — the page carries the note's id in a dragonroll-foundry.noteId flag, the note keeps the page's id in foundryPageId (POST /sync/map-note). The reconcile rewrites pages from the notes and drops the page of a deleted note; journal edits never travel back.
  • fullSync preserves Dragonroll edits (only new rows are overwritten); live Foundry events overwrite. Only a full snapshot can prune.
  • Autosync is a Foundry-side setting (autoSync, on by default): off = no CRUD push, no periodic reconcile, no startup snapshot; the actor directory's Dragonroll: Force Sync still upserts the selection (fullSync:false).
  • GET /api/foundry/* (routes/foundry.js) is unrelated: a JWT-protected proxy over the read-only bridge. Its one write, POST /import, pulls the bridge's actors or world items into the campaign through the same writers as a sync push.

5. Frontend

5.1 Two pages: the app and the documentation

app/pages/ routes the only two things the frontend is. index.vue and the [...all].vue catch-all both render components/views/AppShell.vue — the window app, which has no routes of its own — and docs/index.vue + docs/[slug].vue render views/DocsView.vue, the documentation at /docs. app.vue holds only what is site-wide (the head, the theme) and <NuxtPage>. AppShell boots: GetUser() (JWT in localStorage) → RestoreCampaign() or open main_menu; no user → HasAdmin() ? 'login' : 'register' {firstTime:true}. /link/authorize (and the legacy /discord/authorize) is not a page either: AppShell checks the path and renders the service link screen instead of the app.

The documentation is markdown files under app/content/docs/<group>/<NN>-<page>.md: the folder is the sidebar group and its number orders the groups, the file's number orders its pages, the rest of its name is the slug, and the first heading is the title. services/Docs.js reads them (import.meta.glob(..., {query:'?raw'})), builds the sidebar and renders a page with marked; services/DocsMarkdown.js holds the heading/slug helpers the sidebar and the anchors share and imports nothing so tests/docs.test.js can load it. A new group's label goes in docs.json under groups.<folder> in all three locales. The first page is served at /docs itself, and inside a campaign the top bar opens the same pages in the documentation window (components/windows/DocumentationWindow.vue), which holds the page it shows as its own state instead of a route so the campaign stays behind it.

Two kinds of screens: windows (floating draggable/resizable overlays) and content — the campaign workspace (TopBar + ContentSidebar + note column + StatusBar), turned on when Campaign becomes non-null. The note column shows the open notes, or the anchored map (ActivePane / AnchoredMap / AnchorMap in services/Content.js); viewer/map/MapViewerPane.vue renders it both there and in the detached map_viewer window. Right-clicking that map pins a campaign note at the spot (services/MapPins.js translates image px ↔ screen), clicking the marker opens pinned_note. Dragging an actor row out of the sidebar onto the map makes it stand on that grid cell as a token (services/MapTokens.js snaps to cell centres and sizes the token by its cell); the token drags on with the pointer, steps over the grid with the arrow keys, and Delete takes it off.

5.2 The window system

services/WindowDefinitions.js is the registry ({ title: 'i18n.key', component: () => import(...), movable, close?, back? }) and services/Windows.js the runtime: CreateWindow(type, data) (one instance per type), CreateChildWindow(parentId, ...), ClearWindow({type}|{id}), GetWindowWithId, GetFirstWindowId, CallWindow(id, fn, arg), SetSize/SetPosition/ResetPosition(id,'center')/SetMinSize/SetMaxSize/Top, getComponent(type), SetupHandle(id, handleRef). Adding a window = registry entry + component in components/windows/; copy ExampleWindow.vue: props ['data'] (merged window object, props.data.id), and in onMounted call Top(wrapper), SetupHandle(id, handle), SetSize, ResetPosition.

DOM ids these services depend on — do not rename: window-wrapper-{id}, window-handle-{id}, window-resize-handle-{id}, context-menu, mouse-tooltip.

5.3 Services are the state layer

app/services/ are plain ES modules with module-scope ref()s — no DI, no store, singleton by import. Server.js (axios factory: Server().get(...), interceptor adds Authorization: Bearer <localStorage.token>, initApi() from plugins/api.ts), User.js (GetUser/SetUser/LogoutUser/HasAdmin, GetUserSetting/ SetUserSetting server-backed in User.settings), Campaign.js (useCampaignService(), SetCampaign writes localStorage.selectedCampaignId, RestoreCampaign), Content.js (§5.1), Emitter.js (mitt() bus), Toaster.js, Tooltip.js, ContextMenu.js, Sound.js (AddSound binds snap.wav to .sound-click), Marker.js (marked + widgets), ActionRegistry.js (command palette: register/unregister/search/execute), Windows.js / WindowDefinitions.js, MapPins.js, MapTokens.js, Docs.js + DocsMarkdown.js (§5.1), widgets/DiceParser.js.

5.4 Markdown → widgets

Marker.js turns @name\n…\n@end (block), @name[text] (inline) and [[target]] (wiki link) into placeholder divs/spans; Note.vue renders with v-html and then mounts each placeholder with its own createApp(GetWidget(kind, name), {content}) (and unmounts them on re-render). So widgets are isolated mini-apps: they get only the content string and must not rely on the parent app's provides/injection. Register one in widget_map in Marker.js, component in components/viewer/widgets/{inline,display}/. DiceParser.js evaluates \d*d\d+ with adv|dis|kh<N>|kl<N>, + - * / ( ), unary minus, floor division, and returns {total, steps[]} that RollWidgetDisplay.vue draws.

5.5 Event bus

Events in use: toast, push-note, close-note (removes from the open column only), delete-note (closes and removes from the sidebar, and drops map pins — the note's close button must not use it), title-updated, campaign-entry-created / campaign-entry-updated, note-created, note-renamed, folder-saved, folder-deleted, status-bar-update. Payloads are API documents; the UI note shape is {key, title, text, date}, mapped at the boundary as ContentSidebar.fetchCampaignNotes does. Always import { emitter } from '~/services/Emitter' — composables/useEmitter.ts is broken (§8).

5.6 Styling, i18n

colors.scss Sass maps (dark/light, accents katlum/solus/silang) become --color-* CSS variables: always style with var(--color-…), never hardcode hex, and add a new key to both maps. useTheme.ts persists theme/accent and sets data-theme/data-accent on <html>; app.vue forces setTheme('dark'). Icons are white SVGs with .icon (inverted via --color-icon-invert), from /icons/... or the pixelarticons package. Fonts (fonts.scss, 5e-style families) and sounds (/sounds/*.wav) live in public/.

i18n: frontend/i18n/locales/<lang>/<namespace>.json for en (default), es, ca; plugins/i18n.ts nests each file under its filename, so the key is <file>.<path> ($t('windows.login')). Add every new string to all three locales. Namespaces in use: general, login, register, main-menu, settings, windows, campaigns, link, foundry, discord, docs. (The /docs content is markdown under app/content/docs and is written in English; only its chrome — sidebar labels, prev / next — is translated.)

6. Conventions

  • Backend: CommonJS; every handler try/catch → {status:'error', msg:'errors.internal'} + console.error.
  • Frontend: Vue 3 <script setup>, PascalCase exported service functions (CreateWindow, GetUser), PascalCase component filenames, kebab-case DOM ids. Both ~/ and @/ resolve to app/ — use what the neighbouring file uses.
  • Components call Server() directly (no api layer); await and .then both appear.
  • Comments mix English and Catalan ("Moure aixo") — do not translate unrelated comments while editing.
  • No formatter: keep diffs minimal and local, the codebase is deliberately rough.

7. Recipes

  • New API resource: models/X.js + routes/x.js (ownership check + {status,msg} envelope), then app.use('/api/x', require('./routes/x')) in src/index.js after checkAuth if it needs auth.
  • New window: WindowDefinitions.js entry + components/windows/X.vue (§5.2) + strings in i18n/locales/*/windows.json (all three locales).
  • New widget: component in components/viewer/widgets/{inline,display}/ + widget_map entry in Marker.js.
  • New palette action: register({id, label, description, execute, isActive?}) from ~/services/ActionRegistry (palette: Ctrl/Cmd+K or /).
  • New theme color: key in both dark and light maps in colors.scss, then var(--color-<key>).
  • New documentation page: app/content/docs/<group>/NN-name.md whose first heading is its title (§5.1); a brand-new group also needs groups.<folder> in i18n/locales/*/docs.json (all three locales).

8. Known landmines (verified in code — do not "fix" silently, never make them worse)

  1. README.md says run ./install.sh / ./start.sh; neither exists. frontend/README.md says the frontend is React; it is Nuxt/Vue.
  2. services/keys.js ships the JWT secret "putyoursecrethere", used in production.
  3. POST /api/user/register responds {status:'ok', code: setupCode} but setupCode is not in scope → caught → the first-run registration actually returns errors.internal. The register UI (RegisterWindow.vue) drives that flow; fix carefully.
  4. POST /api/note/delete has no ownership check (any authenticated user can delete any note id); the other note.js handlers and folder.js do check.
  5. /api/user/* is mounted before the JWT guard: new routes there are public unless they authenticate inline (/api/discord is also before it, but every route there is gated by requireBot, the shared bot-secret header). services/middleware.js's isAdmin is imported but applied to no route.
  6. composables/useEmitter.ts reads $emitter from useNuxtApp() and no plugin provides it — use ~/services/Emitter.
  7. App-wide CORS only whitelists http://localhost:3000; .env.production files are committed with internal hosts.
  8. Windows.js: getComponent caches defineAsyncComponent per type for the whole process (restart the dev server if a new window misbehaves), SetupHandle attaches document mouse listeners per window and never removes them, and ClearAll() iterates Object.keys(windows) instead of windows.value.
  9. The frontend treats the JWT as the user cache: settings changes need GetUserSetting/SetUserSetting round-trips, the token payload goes stale.

9. Ports

frontend dev :3000 · backend :5000 (hardcoded) · MongoDB :27017 · nginx :3000 → 80 in compose, proxying / → frontend, /api/ → backend.