mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-20 20:07:59 +00:00
159 lines
14 KiB
Markdown
159 lines
14 KiB
Markdown
# agents.md
|
|
|
|
This file is the single source of truth for codebase obstacles, oddities, and their resolutions. Do not scatter this knowledge in comments, commit messages, or memory.
|
|
|
|
---
|
|
|
|
## Rules for agents
|
|
|
|
1. **Before solving a problem**, check this file. If the problem is documented, use the recorded solution or workaround. Do not re-derive it.
|
|
2. **After solving a new problem**, document it here before moving on. Keep entries concise.
|
|
3. **Do not deviate** from a recorded solution without first confirming with the user. Once confirmed, update this file with the new approach and reason before proceeding.
|
|
|
|
---
|
|
|
|
## Entry format
|
|
|
|
```text
|
|
### [Short problem title]
|
|
**Area:** [file, module, or system this affects]
|
|
**Obstacle:** What the problem is and where it appears.
|
|
**Solution/Workaround:** What was done to fix or work around it.
|
|
**Preference:** If multiple approaches exist, which was chosen and why.
|
|
```
|
|
|
|
---
|
|
|
|
## Documented obstacles
|
|
|
|
### Shared dependency aliases created circular imports
|
|
**Area:** web/app/deps.py, web/app/auth/session.py, web/app/settings.py
|
|
**Obstacle:** Moving session aliases into deps.py made it import auth/session.py, which already imports get_db from deps.py. Renaming config.py to settings.py also left stale imports.
|
|
**Solution/Workaround:** Keep get_db in deps.py and dependency aliases local to their consuming modules. Update imports to app.settings and import AppSettings directly from app.models.app_settings.
|
|
**Preference:** Keep dependency wiring simple while building the feature; defer shared alias extraction.
|
|
|
|
### TypeScript composite builds fail with no output
|
|
**Area:** cli/tsconfig.json, tsconfig.base.json
|
|
**Obstacle:** When `composite: true` is set in tsconfig, TypeScript requires proper project references to build. The CLI package was building but producing no output files, causing "cannot find module" errors.
|
|
**Solution:** Remove `composite: true` from cli/tsconfig.json. Also removed `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` from tsconfig.base.json as they caused strict type issues with dynamic config objects.
|
|
**Preference:** Use simple tsconfig without composite mode for CLI package.
|
|
|
|
### verify.ts overly complex abstraction
|
|
**Area:** cli/src/commands/verify.ts
|
|
**Obstacle:** Code had too many layers: collectResults → addResult (inner function) → displayDiagnosticResults/verifyResults. Made it hard to trace and debug.
|
|
**Solution:** Rewrote to be flatter: verifyCommand → runDiagnosticMode/runVerifyMode. Used simple inline logic instead of adding functions for everything.
|
|
**Preference:** KISS - keep functions small but avoid over-abstraction.
|
|
|
|
### Error messages in forgejo-checks too generic
|
|
**Area:** cli/src/utils/forgejo-checks.ts
|
|
**Obstacle:** Network errors showed "fetch failed" with no context. HTTP errors showed just status codes. Not actionable for users.
|
|
**Solution:** Added getErrorMessage() helper to detect: timeouts, connection refused, host not found. Improved HTTP error messages to include status text. Added context prefixes like "cannot reach server", "cannot connect to API".
|
|
**Preference:** Actionable messages that tell users what to fix.
|
|
|
|
### ENV_MAPPING duplicated inline in verify.ts
|
|
**Area:** cli/src/commands/verify.ts
|
|
**Obstacle:** Had duplicate object with same keys as ENV_MAPPING from config.ts. Two sources of truth.
|
|
**Solution:** Import ENV_MAPPING and use it. Change display to show env var names (SNAKE_CASE) instead of internal keys.
|
|
**Preference:** Single source of truth in config.ts.
|
|
|
|
### Display verbiage redundancy
|
|
**Area:** cli/src/commands/verify.ts
|
|
**Obstacle:** Displayed "MYST_PUBLIC_URL set" - "set" is redundant, icon already shows status.
|
|
**Solution:** Just show env var name, remove "set".
|
|
**Preference:** Cleaner, let icon indicate status.
|
|
|
|
### loadConfig returning wrong type for error case
|
|
**Area:** cli/src/commands/verify.ts
|
|
**Obstacle:** loadConfig() threw error when .env not found, but caught and re-threw in verifyCommand. This caused process to exit with stack trace instead of clean message.
|
|
**Solution:** Return null on ENOENT, handle null in verifyCommand. Return type: `Record<string, string> | null`.
|
|
**Preference:** Explicit null handling over exceptions for user-facing errors.
|
|
|
|
### Logout cookie not reaching browser
|
|
**Area:** web/app/routers/auth.py, web/app/auth/session.py
|
|
**Obstacle:** `revoke_session` set cookies on the injected `Response` parameter, but the logout handler returned a new `RedirectResponse` — so `Set-Cookie` was discarded.
|
|
**Solution:** Create `RedirectResponse` first, then pass it into `revoke_session`. Same pattern used in `callback_forgejo` for `create_session`.
|
|
**Preference:** Pass the actual response object that will be returned.
|
|
|
|
### crypto.py decrypt functions kept proactively
|
|
**Area:** web/app/auth/crypto.py
|
|
**Obstacle:** CodeRabbit flagged missing decryption functions and key validation. Added `decrypt_token`/`decrypt_optional` + key format validation in `fernet_from_encryption_key`.
|
|
**Solution:** Added the functions even though no consumer exists yet. They will be used for PAT decryption in share link flow.
|
|
**Preference:** Keep dead code if it's small, symmetric (`encrypt`/`decrypt`), and has an obvious future consumer.
|
|
|
|
### User model Session import direct instead of TYPE_CHECKING
|
|
**Area:** web/app/models/user.py
|
|
**Obstacle:** `Session` was imported directly (`from .session import Session`) while `Grant` used `TYPE_CHECKING`. Inconsistent and risked circular imports.
|
|
**Solution:** Moved `Session` import under `TYPE_CHECKING`, changed relationship to string ref `"Session"`.
|
|
**Preference:** Always use `TYPE_CHECKING` for model references within models to avoid circular imports.
|
|
|
|
### Boilerplate UI must follow attached light vault system
|
|
**Area:** web/app/static/css/input.css, web/app/templates/*.html
|
|
**Obstacle:** Existing boilerplate used dark-mode pink tokens that conflicted with the attached "Mystique Minimalist Security" design system.
|
|
**Solution/Workaround:** Use light Geist/JetBrains Mono typography, glacier-blue primary actions, white/off-white tonal surfaces, hairline slate borders, compact labels, mono technical strings, and pill status badges.
|
|
**Preference:** Keep visual changes in Tailwind tokens and boilerplate templates; avoid backend route changes for design-only updates.
|
|
|
|
### Tailwind design tokens should use paired semantic roles
|
|
**Area:** web/app/static/css/input.css, web/app/templates/*.html
|
|
**Obstacle:** Early UI templates mixed old role names (`background-*`, `text-*`, `stroke`) and hardcoded `white` values inside component classes, which made dark mode and future theming brittle.
|
|
**Solution/Workaround:** Use Tailwind v4 `@theme` tokens with semantic pairs such as `background/foreground`, `card/card-foreground`, `primary/primary-foreground`, `secondary/secondary-foreground`, `border`, `input`, and `ring`. Keep shared component structure in base classes like `.btn`, with variant classes only setting semantic colors.
|
|
**Preference:** Prefer semantic token names over appearance-based names; add dark mode by overriding CSS variables under `.dark`.
|
|
|
|
### Header brand SVG inherits unwanted icon styling
|
|
**Area:** web/app/templates/base.html, web/app/templates/index.html, web/app/static/css/input.css
|
|
**Obstacle:** The inline Firebreak header wordmark uses hardcoded SVG fills, and page-level header rules can accidentally apply icon `stroke` styles to the brand SVG. On forced-dark landing headers, the `#17191C` wordmark fill disappears against the obsidian nav.
|
|
**Solution/Workaround:** Give the header brand link a stable `brand-link` class, prevent inherited SVG strokes on `.brand-link svg`, and override only the hardcoded wordmark fill in dark contexts or forced-dark page headers.
|
|
**Preference:** Scope icon stroke rules to nav icons; do not apply broad `header svg` stroke styles.
|
|
|
|
### Landing video poster caused logo flash
|
|
**Area:** web/app/templates/index.html, web/app/static/img/
|
|
**Obstacle:** Using a logo SVG as the `<video poster>` made the browser briefly stretch the logo across the full hero video area before the MP4 painted, which looked like the center logo flashing huge on refresh.
|
|
**Solution/Workaround:** Use a real video-frame poster image (`firebreak-hero-poster.jpg`) or omit `poster`; do not use logo assets as full-bleed video posters.
|
|
**Preference:** Keep logo sizing in the logo `<img>` and use a frame still for video loading states.
|
|
|
|
### POST forms lack CSRF tokens
|
|
**Area:** web/app/routers/setup.py, web/app/routers/settings.py, web/app/templates/setup.html, web/app/templates/settings.html
|
|
**Obstacle:** All state-changing forms (`/setup`, `/settings/pat`, `/settings/pat/delete`) use plain POST with no CSRF token. SameSite=Lax on the session cookie mitigates most cross-origin attacks, but does not fully cover same-site subdomain scenarios.
|
|
**Solution/Workaround:** Deferred. Low practical risk since Firebreak runs behind a VPN. Add server-generated CSRF tokens (hidden form field + server-side check) before exposing the app to the public internet.
|
|
**Preference:** Use a FastAPI CSRF middleware or manual double-submit cookie pattern when addressing this.
|
|
|
|
### Firebreak UI is currently dark-only
|
|
**Area:** web/app/templates/base.html, web/app/static/css/input.css
|
|
**Obstacle:** Theme switching and persisted localStorage theme state conflicted with the current Firebreak brand pass, especially on the cinematic landing page.
|
|
**Solution/Workaround:** Force the root document to use the `.dark` token set and remove the theme toggle UI/scripts.
|
|
**Preference:** Keep semantic dark tokens; only reintroduce theme switching after the dark Firebreak identity is stable.
|
|
|
|
### Forgejo repository check accepted empty accounts
|
|
**Area:** cli/src/utils/forgejo-checks.ts
|
|
**Obstacle:** `checkRepoAccess` treated any parsed user object as success, even when Forgejo reported zero accessible repositories.
|
|
**Solution/Workaround:** Require `totalRepos > 0` before returning the existing success result; preserve the existing zero-repository failure.
|
|
**Preference:** A valid token alone is insufficient for repository-access verification.
|
|
|
|
### Forgejo PAT could be sent over remote HTTP
|
|
**Area:** cli/src/utils/forgejo-checks.ts, cli/src/commands/config/init.ts
|
|
**Obstacle:** CLI setup and verification accepted remote `http://` Forgejo URLs, allowing the PAT to be sent without transport encryption.
|
|
**Solution/Workaround:** Centralize Forgejo URL validation, require HTTPS for non-local endpoints, and allow HTTP only for the documented `forgejo` service and loopback hosts. Validate again inside authenticated checks before constructing requests.
|
|
**Preference:** Reject insecure remote transport instead of adding an acknowledgement flag.
|
|
|
|
### Tailwind standalone CLI was killed by macOS code signing
|
|
**Area:** web/tailwindcss, web/dev.sh
|
|
**Obstacle:** The downloaded standalone Tailwind binary is ad-hoc ("linker-signed") only. macOS AMFI rejected it with `has no CMS blob` / `Unrecoverable CT signature issue`, and the kernel denied the page at offset `0x4b00000` and sent SIGKILL. `dev.sh` uses `set -euo pipefail`, so the script aborted silently with exit 137 and no error message.
|
|
**Solution/Workaround:** Resolved by migrating the web CSS build to pnpm (`@tailwindcss/cli`), which ships a normally signed binary. If the standalone binary is ever re-downloaded, fix with `xattr -c web/tailwindcss && codesign --force --sign - web/tailwindcss`. Diagnose this class of failure with `/usr/bin/log show --predicate 'eventMessage CONTAINS[c] "tailwind"'`.
|
|
**Preference:** Prefer the pnpm-managed CLI; do not re-add the standalone binary.
|
|
|
|
### Tailwind `--watch` exits when stdin is closed
|
|
**Area:** web/package.json (`css:watch` script)
|
|
**Obstacle:** Tailwind v4 `--watch` keeps watching only while stdin is open. Under non-interactive shells and some CI contexts stdin closes immediately, so the watcher builds once, exits 0, and silently stops watching. This looks identical to a broken watcher and is easy to misdiagnose.
|
|
**Solution/Workaround:** No change needed for normal use — `dev.sh` backgrounds the watcher from an interactive terminal, which inherits an open stdin. If a caller needs watching without a tty, pass `--watch=always`.
|
|
**Preference:** Use bare `--watch` for interactive dev; reserve `--watch=always` for headless callers.
|
|
|
|
### pnpm install failed with exit 1 on blocked build scripts
|
|
**Area:** pnpm-workspace.yaml
|
|
**Obstacle:** pnpm 10 does not run dependency lifecycle scripts unless allowlisted, so `@parcel/watcher` (a dep of `@tailwindcss/cli`) was skipped and `pnpm install` exited **1** with `ERR_PNPM_IGNORED_BUILDS`. That would break CI and Docker builds.
|
|
**Solution/Workaround:** Added `allowBuilds: {"@parcel/watcher": false}` to `pnpm-workspace.yaml`. `false` is correct — the prebuilt platform package (`@parcel/watcher-darwin-arm64`) already provides the native binding, so the node-gyp build is unnecessary; watch mode verified working. Note `onlyBuiltDependencies` is deprecated as of pnpm v10.26.0 and is silently ignored.
|
|
**Preference:** Set `allowBuilds` explicitly per dependency rather than `dangerouslyAllowAllBuilds`.
|
|
|
|
### Killing a pnpm-wrapped watcher orphaned the node process
|
|
**Area:** web/dev.sh
|
|
**Obstacle:** `pnpm run` spawns node as a child, so `$!` captured pnpm's PID rather than the Tailwind process. The `trap "kill $TW_PID"` cleanup killed the wrapper and left the node watcher running, accumulating orphans across dev-server restarts.
|
|
**Solution/Workaround:** Enable job control with `set -m` before backgrounding so the job becomes a process-group leader, then kill the group: `kill -- -$TW_PID`.
|
|
**Preference:** When backgrounding a package-manager wrapper, always kill the process group rather than the wrapper PID.
|