Skip to content
rachel/dab
File

Blob: AGENTS.md

Markdown130 lines

AGENTS.md

Purpose

This file is for durable working agreements and product constraints that future agents cannot reliably infer from the tree. Do not turn it into an entrypoint map, file inventory, or recap of implementation details already covered by the live code, SPEC.md, or docs/operations.md.

Source Of Truth

  • Start with the live checkout. Current code, tests, wrangler.jsonc, generated types, and migrations win over older planning text.
  • Treat SPEC.md as the original product and implementation brief. Use it for intent and rationale, but do not assume it is newer than the code.
  • Treat docs/operations.md as the runbook for resource setup, migrations, and validation. Do not duplicate command lists here.
  • Local RFC copies under reference/ are protocol references, not project architecture docs. For WebDAV, CalDAV, CardDAV, iCalendar, vCard, Basic auth, discovery, ACL, Extended MKCOL, or sync ambiguity, check the relevant RFC and existing compatibility tests before making a "cleaner" REST-style change.
  • Adjacent repos such as ~/code/bland can be useful for tessera/OIDC patterns, but they are not authority for dab's product model.

Working Rules

  • Keep work local unless the user explicitly asks for deployment, pushing, staging, committing, or remote resource changes.
  • Read before editing. For non-local changes, inspect the touched code, nearby tests, and the relevant docs or RFC section before changing behavior.
  • Do not ask the user questions that the repo, tests, logs, types, or local docs can answer. Ask only for product direction or missing external context.
  • Multiple agents may be working in the same checkout. Do not revert or reshape unrelated changes.
  • Do not stage changes for review unless the user explicitly asks.
  • Prefer the project's existing Hono, Drizzle, Durable Object, queue, audit, JSON error, XML, and DAV helper patterns over new glue.
  • Keep comments sparse and useful. Protocol deviations, compatibility hacks, security rationale, and platform workarounds deserve comments; obvious code does not.
  • Before calling a task complete, run validation appropriate to the change scope; see Testing And Validation for scope expectations and docs/operations.md for current commands.

Testing And Validation

  • Add or update tests for behavior changes, especially regressions, protocol edge cases, auth checks, storage repair, parser bounds, and Durable Object migration behavior. Do not rely on manual inspection for these areas.
  • Choose validation by blast radius. Focused changes can use the nearest worker tests plus typecheck; auth, routing, host classification, XML parsing, DAV method semantics, Durable Object state, queues, migrations, or storage changes need the applicable broader suites.
  • For WebDAV, CalDAV, and CardDAV compatibility, protocol tests are part of the product contract. Do not treat ordinary JSON API tests as enough when changing DAV status codes, XML bodies, ETags, locks, Depth handling, REPORT behavior, discovery, calendar parsing, recurrence, or address book matching.
  • Keep exact command lists in docs/operations.md and package.json. This file should describe validation expectations and scope, not duplicate commands that can drift.
  • If a relevant validation step cannot be run, say exactly which coverage is missing and why before handing work back.

Product Boundaries

  • dab is a Cloudflare-native DAV service, not a workspace app and not a UI app. Do not introduce tenants, organizations, public shares, collaboration, or HTML product flows unless the user explicitly changes scope.
  • tessera owns human identity. dab owns DAV storage, opaque subject host labels, API sessions, PATs, protocol authorization, and subject-local data.
  • A subject is the top-level ownership boundary. Do not import bland/limic workspace, membership, or page-access concepts into dab.
  • The opaque five-word host label is routing material, not an authorization secret. Keep subject-host ownership and PAT subject matching fail-closed.
  • Changing the production tessera issuer is a migration event. Do not turn dab into a multi-issuer identity-linking system as a convenience fix.

Security And Access

  • Auth, OIDC, cookies, PATs, host classification, R2 blob access, DAV scopes, same-origin API mutation checks, rate limits, and XML parsing are security-sensitive. Preserve fail-closed behavior.
  • Loopback-only insecure OIDC discovery is a local-development escape hatch. Do not extend it to non-loopback issuers.
  • Do not log secrets, bearer material, PAT tokens, PAT digests, session cookies, OIDC codes, ID tokens, transaction cookies, client secrets, or raw private DAV object bodies.
  • PAT delete means revoke unless the product explicitly changes. Avoid physical deletion when it would erase auditability or UI projection history.
  • Write scopes imply read for the same DAV area because interoperable DAV writes need discovery, ETags, and readback. Do not "tighten" this into unusable write-only clients without a protocol review.

Runtime Boundaries

  • Keep D1 as control-plane state, Durable Object SQLite as subject/protocol state, R2 as file bytes, and Queues as asynchronous repair/cleanup.
  • Durable Object names and R2 blob keys should use internal storage ids, not raw tessera subject ids.
  • Durable Objects should not query or mutate control-plane D1 from normal RPC paths. Let the Worker orchestrate cross-runtime coordination.
  • Queue handlers and repair jobs must stay idempotent. Blob GC should be conservative when object state cannot verify that a blob is unreferenced.
  • Use Durable Object constructor migration setup for DO SQLite. Avoid blockConcurrencyWhile inside normal RPC methods.
  • Expected protocol or validation failures should return structured results or DAV/JSON errors. Reserve thrown errors for unexpected failures.

Protocol Compatibility

  • DAV compatibility beats aesthetic API shape. Many clients depend on exact status codes, XML names, namespaces, ETags, depth handling, locking behavior, and discovery responses.
  • Use reference/ RFC copies to resolve protocol semantics for DAV, CalDAV, CardDAV, iCalendar, vCard, Basic auth, discovery, ACLs, Extended MKCOL, and sync behavior. Prefer the relevant RFC section over intuition from ordinary REST APIs.
  • When an RFC permits multiple valid behaviors, preserve the behavior covered by existing compatibility tests unless changing it is intentional and tested against real clients.
  • Do not edit or refresh RFC copies as part of feature work. Treat them as local vendor references; only update them in an explicit reference-maintenance change.
  • Preserve bounded parsers and hostile-input limits. Do not add iCalendar, recurrence, vCard, XML, or markdown parser dependencies without checking Worker compatibility, maintenance, bounds, and licensing.
  • Litmus and caldav-server-tester coverage are part of real confidence for DAV behavior. Treat failures there as product regressions unless proven to be a harness limitation.