STTracker/docs/TODO.md

TODO

Durable backlog. Agents append here instead of leaving TODO comments in source. Small, specific, independently actionable. Remove only when actually done.

Now

• Choose a linter/formatter (e.g. Biome), then add lint to package.json, AGENTS.md and docs/PERMISSIONS.md.

• Add CI on Gitea Actions: install, typecheck, and test on SQLite and Postgres. Add a guard that fails if AGENTS.md is over 150 lines.

• Agent permissions for Task 16 commands: add bun run typecheck, bun apps/server/src/main.ts and bun --hot apps/server/src/main.ts (all verified 2026-10-30) to docs/PERMISSIONS.md, .claude/settings.json, .gemini/settings.json, then fill Typecheck/Dev/Start in AGENTS.md Commands. Needs a human: agents may not edit their own permission files.

Next

• API: response schemas in the OpenAPI document (requests only today).
• Deployment docs (Task 19): the server runs Bun.serve in production mode unless NODE_ENV=development or bun --hot, so Docker needs no NODE_ENV. Document NODE_ENV=development for local debugging.
• API: restoreVersion, acceptSuggestion and resolveChange take no actor, so history records "user" for them even when an app token calls them. Thread the actor through if script provenance matters there.
• API: login/register rate limit is per process and keyed on the socket IP; behind a reverse proxy every client shares one key. Add a trusted-proxy setting for X-Forwarded-For.
• API: file imports are base64 in the jobs.payload row (up to ~67 MB of text). Move uploads to DATA_DIR/uploads/ and pass a path.
• API: PATCH list-items/:id only moves items; editing an item's note needs a core function.
• Phase 2 and Phase 3 plans (spec §12).
• Generate image thumbnails for attachments (Phase 1 sizes images with CSS).
• Web: convert the vendored Gelasio variable TTFs (~170 KB each) to latin-subset woff2 once fonttools/woff2 is available; Bun inlines fonts into the CSS bundle.
• Web/API: "Linked sources" is inferred from plugin: actors in fieldSources, so a source that matched an entry but never wrote a field is not shown. Add a per-entry source-links route.
• Web: the detail pane only lists attachments of the entry itself, not those linked to its reads or copies.

Someday

Recurring

• Maintain AGENTS.md:
  • Add a rule only in response to a real failure. When an agent repeatedly gets something wrong, that is a gap; add one line, ideally with a code example. Do not pre-empt hypothetical mistakes.
  • Update in the same PR as the convention change. A stale rules file is worse than none, because it actively misleads.
  • Prune quarterly. Delete rules whose convention has changed or whose mistake no longer occurs.
  • Optional, cheap validation: run the same task twice in clean sessions, with and without the file, and compare steps and token use.

Known issues

• Web: in production the bundled HTML references /../../chunk-*.css|js (Bun bundles ../../web/index.html from apps/server). Browsers normalise it to /chunk-* and it loads; check it behind a reverse proxy.
• Plugins: reload re-imports entry files only; edits to a plugin's other modules need a server restart.
• Plugins: rate limiting is per run (each run builds its own client), not per plugin (spec §11); share a limiter per plugin in Phase 2.
• Plugins: ctx.log reaches source_runs.log only after the run ends, so a crash mid-run loses it.
• Sync: two concurrent runs of one connection outside the job queue (e.g. a manual run) can still race on source_records. Queued syncs are serialised by lockKey.
• Restore: a new child work whose parent+position collides with an existing child of a re-matched parent fails with ImportError("conflict") instead of being merged or repositioned.
• Restore: an unlink of identical attachment bytes between the pre-write and the commit could remove the file; mitigated by re-writing after commit, not locked.
• Export bundles hold attachment bytes in memory; very large libraries need a streaming zip.
• Admin merge does not merge colliding children recursively; colliding children stay under the tombstoned parent.
• Matching: a shared parent resolved without external IDs or position (title/year reuse in packages/core/src/matching.ts) has no unique key, so concurrent matches can create it twice.
• Library search (q) and the title sort use the work's title, not the user's overrides.title (overrides are a JSON text column). The tag filter matches the JSON text with LIKE.
• Library hierarchy rollup and orphan detection look three levels deep; deeper trees are not rolled up.
• Undoing a per-user move does not move copies or list items back, nor restore aliases that the move re-pointed.
• bun run typecheck fails with TS18003 until source files exist under apps/, packages/ or plugins/.