@drawbridge/drawbridge-agents 0.0.6 → 0.0.9

package/.root-template/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sentry": {
+      "type": "http",
+      "url": "https://mcp.sentry.dev/mcp"
+    }
+  }
+}

package/README.md

@@ -26,8 +26,11 @@ claude/
   agents/
   commands/
 
+.root-template/             ← mirrored into each consumer repo's root
+  .mcp.json                 ← project-level MCP servers (e.g. Sentry)
+
 bin/
-  sync-claude.js            ← drawbridge-agents-sync — mirrors .claude-template/ → consumer's .claude/
+  sync-claude.js            ← drawbridge-agents-sync — mirrors templates into consumer repo
 ```
 
 ## Consuming from a drawbridge-* repo
@@ -55,7 +58,11 @@ bin/
    "sync": ". \"$HOME/.nvm/nvm.sh\" && nvm use && npm prune && npm install && npx drawbridge-agents-sync"
    ```
 
-   On every `npm run sync`, the contents of this package's `.claude-template/` are copied into the consumer's `.claude/`. Paths that exist in the template are **managed** (overwritten on each sync). Anything else in `.claude/` — including `settings.local.json` and any consumer-only hooks/agents/commands — is left untouched.
+   On every `npm run sync`, this package mirrors:
+   - `.claude-template/` → consumer's `.claude/`
+   - `.root-template/` → consumer's repo root (currently just `.mcp.json`)
+
+   Paths that exist in the templates are **managed** (overwritten on each sync). Anything else in `.claude/` or at the repo root — including `settings.local.json` and any consumer-only hooks/agents/commands — is left untouched.
 
 Claude Code's `@` imports cascade — one import line resolves the whole tree under `claude/CLAUDE.md`.
 

package/bin/sync-claude.js

@@ -3,13 +3,12 @@ const fs = require('fs')
 const path = require('path')
 
 const consumerRoot = process.env.INIT_CWD || process.cwd()
-const templateRoot = path.resolve(__dirname, '..', '.claude-template')
-const destRoot = path.join(consumerRoot, '.claude')
+const packageRoot = path.resolve(__dirname, '..')
 
-if (!fs.existsSync(templateRoot)) {
-  console.error(`drawbridge-agents-sync: template not found at ${templateRoot}`)
-  process.exit(1)
-}
+const targets = [
+  { src: path.join(packageRoot, '.claude-template'), dst: path.join(consumerRoot, '.claude'), required: true },
+  { src: path.join(packageRoot, '.root-template'), dst: consumerRoot, required: false },
+]
 
 const copied = []
 
@@ -27,7 +26,16 @@ const mirror = (src, dst) => {
   }
 }
 
-mirror(templateRoot, destRoot)
+for (const { src, dst, required } of targets) {
+  if (!fs.existsSync(src)) {
+    if (required) {
+      console.error(`drawbridge-agents-sync: template not found at ${src}`)
+      process.exit(1)
+    }
+    continue
+  }
+  mirror(src, dst)
+}
 
-console.log(`drawbridge-agents-sync: ${copied.length} file(s) mirrored to ${path.relative(consumerRoot, destRoot) || '.claude'}`)
+console.log(`drawbridge-agents-sync: ${copied.length} file(s) mirrored`)
 for (const p of copied) console.log(`  ${p}`)

package/claude/CLAUDE.md

@@ -3,4 +3,8 @@
 @../conventions/nested-objects.md
 @../conventions/jsx-fragments.md
 @../conventions/transactions.md
+@../conventions/cascade-cleanup.md
 @../conventions/property-shorthand.md
+@../conventions/drawbridge-packages.md
+@../conventions/sentry-sdk.md
+@../conventions/app-web-forms.md

package/conventions/app-web-forms.md

@@ -0,0 +1,28 @@
+# app-web form conventions
+
+Applies to `drawbridge-app-web` only.
+
+## Always use react-hook-form
+
+Every form is built with **react-hook-form** (`useForm` + `Controller`,
+with the `yup` resolver from `@/lib/yup` where validation is needed).
+Never hand-rolled `useState` field handling. Mirror existing forms like
+`components/form-profile.js` and `components/form-auth.js`.
+
+This applies even to **field-less submit/action forms** — a form that's
+just a button, e.g. a "send code" or confirm step. Use
+`useForm()` + `handleSubmit(onSubmit)` and drive disabled/loader state
+off `formState.isSubmitting`. Do NOT use a manual
+`const [submitting, setSubmitting] = useState(false)` +
+`event.preventDefault()`. Reference pattern: `components/form-action.js`.
+
+## Secondary forms launch in the global modal
+
+For a form triggered from within another form (e.g. "change email" from
+the profile form), render it inside the **global modal** via
+`useModal({ queryClient })` → `modal.open({ title, message: <TheForm/> })`.
+Do not nest a second `<form>` inside an existing `<form>`.
+
+The modal portals to the top level, so the inner `<form>` is not a DOM
+descendant of the outer one. Nested `<form>` is invalid HTML and breaks
+submit propagation. Reference pattern: `components/form-verify-prize.js`.

package/conventions/cascade-cleanup.md

@@ -0,0 +1,25 @@
+# Cascade cleanup belongs in drawbridge-sync
+
+When a Drawbridge document delete should trigger cleanup of dependent rows in another collection — actions tied to a workflow, workflows tied to a connection, exports tied to a user, anything where deleting X requires also deleting Y — the cleanup belongs in a change-stream listener in `drawbridge-sync`, **not** inline in the API route handler that triggered the original delete.
+
+## Why
+
+- API routes stay focused on the user's request. Cascade work shouldn't block the HTTP response or balloon the request's transaction scope.
+- A sync-side listener fires on **every** delete path: the direct route, a cascade from a different route, an admin tool, a manual Mongo write. An inline cascade only runs on the one route that has it.
+- Change streams are configured with `fullDocumentBeforeChange: 'required'`, so the listener receives the full prior document and has everything it needs to reason about the dependents.
+
+## How to apply
+
+- In an API route delete handler, do **not** add `controllers.base.delete` (or `bulk` with `deleteMany`) for child collections. Just delete the parent. The sync listener cleans up.
+- Add the cleanup handler in `drawbridge-sync/queue/<collection>.js`, in the `handlers.delete` slot, signature `async ({ fullDocumentBeforeChange : doc }) => { ... }`. Copy the shape from `queue/user.js` or `queue/organization.js`.
+- For the listener to fire at all, the collection must be in both:
+  - `drawbridge-sync/stream.js` `collections` array
+  - `drawbridge-sync/lib/queue.js` queue map
+  - **And** registered in `drawbridge-sync/queue/index.js`'s workers array.
+  - If any of these are missing, change-stream events get enqueued and silently dropped, or never enqueued at all. Audit all four sites when adding a new collection.
+- For deep cascades (parent → child → grandchild), let the chain ride the change streams: the child's own listener handles its own dependents. Don't reach down two levels from the parent's listener.
+
+## Counter-examples (these stay inline in the API)
+
+- Decrementing `organization.totals.<resource>` and `usage.totals.<resource>` on delete. These are counter mutations against the *same* request, not cleanup of dependent rows. Done inline in the API route handler.
+- The deleted document itself. The route deletes it; the listener reacts to the deletion.

package/conventions/drawbridge-packages.md

@@ -0,0 +1,66 @@
+# Drawbridge package workflow
+
+Conventions for working on the `@drawbridge/*` npm packages
+(`drawbridge-utils`, `drawbridge-components`, `drawbridge-mongodb`,
+`drawbridge-redis`, `drawbridge-stripe`, `drawbridge-shopify`,
+`drawbridge-telemetry`) and the apps that consume them.
+
+## Build + publish script
+
+All `@drawbridge/*` packages standardize on:
+
+```json
+"scripts": {
+	"sync": ". \"$HOME/.nvm/nvm.sh\" && nvm use && npm prune && npm install",
+	"build": "tsup && npm publish"
+}
+```
+
+**Do NOT add a `prepare: tsup` script.** `prepare` runs automatically on
+`npm publish`, so it duplicates the work `build` already does. Worse: if
+`npm publish` is invoked from a shell where the wrong Node version is
+active (e.g. system Node before `nvm use`), `prepare` triggers `tsup`
+under that wrong Node and fails with cryptic syntax errors (optional
+chaining unrecognized, etc.) even though `npm publish` itself would have
+worked fine.
+
+## Coordinating peer dependencies on bump
+
+When bumping any `@drawbridge/*` package, audit every sibling package's
+`peerDependencies` for a stale pin. Peer pins are version-exact (e.g.
+`"@drawbridge/shopify": "0.0.3"`), so bumping the package in consumer
+apps while leaving a sibling's peer dep on the old version triggers
+`ERESOLVE` at install time.
+
+Before publishing a bump, grep peerDependencies across the family:
+
+```sh
+grep -A8 peerDependencies /Users/darrenshea/Projects/drawbridge-*/package.json
+```
+
+If a sibling package peer-pins something you just bumped, that sibling
+needs a coordinated peer-dep update + republish in the same release.
+
+## Check for duplicate logic before renaming across repos
+
+When changing a value at the api side (enum keys, schema shape, operator
+vocabulary, etc.), grep every sibling repo for identical-purpose code
+paths that operate on that value. There are known copy-paste duplicates
+that drift silently when only one side is updated.
+
+```sh
+grep -rn "<old-value>" /Users/darrenshea/Projects/drawbridge-* --include="*.js"
+grep -rn "<file-name-or-export>" /Users/darrenshea/Projects/drawbridge-* --include="*.js"
+```
+
+Specifically watch for:
+- segment / rules evaluation
+- mongo schema-shape consumers
+- credential / connection field reads
+- any "pure helper" pattern that may have been copied rather than shared
+
+If a duplicate is found, prefer extracting the live copy and deleting
+the stale one over leaving both. Don't reflexively reach for
+`drawbridge-utils` — utils is for code with multiple live consumers;
+if only one repo actually imports the duplicate, the others are dead
+code that should just be deleted.

package/conventions/javascript-formatting.md

@@ -53,3 +53,7 @@ const run = async () => {
 - Single quotes for strings
 
 When adding or removing a wrapper block (e.g. a transaction callback, an `if` block), re-indent all enclosed lines to match the new nesting level. If the indentation shift is large or the block is long, prefer rewriting the whole function with the Write tool rather than using multiple Edit calls.
+
+## No underscores in identifiers or prose
+
+The drawbridge codebases use camelCase identifiers — never snake_case. This applies to both code and prose in comments, commit messages, and chat. Say "worker thread" (two words) in prose, not "worker_thread". The only acceptable underscores are literal external API names that require them (e.g. the Node module `worker_threads` in a `require`), and even then refer to the concept as "worker thread" in surrounding prose.

package/conventions/sentry-sdk.md

@@ -0,0 +1,39 @@
+# Sentry SDK encapsulation
+
+Shared `@drawbridge/*` packages that wrap a stateful SDK (one that
+maintains module-scope state — Sentry scopes, registries, singletons)
+must depend on that SDK as a **direct dependency** with a pinned exact
+version. Do NOT declare it as a peer dep with a loose range like
+`">=10"`.
+
+## Why
+
+Loose peer-dep ranges let npm resolve two module instances with
+independent state. The previous incident: `drawbridge-telemetry`
+declared `@sentry/core: ">=10"` as a peer. Consumers' `@sentry/node`
+had a strict `@sentry/core@<exact>` dep, but the loose peer range
+happily resolved to a hoisted `@sentry/core@<different version>` from
+elsewhere in the tree. npm kept both: a hoisted copy used by
+`drawbridge-telemetry` and a nested copy under `@sentry/node` used by
+service code. Each held its own `getIsolationScope()` registry, so
+`Sentry.setTag(...)` writes from the wrapper landed on one scope while
+`captureException` from service code read from the other —
+silently-broken telemetry that took an entire debug session to
+root-cause.
+
+## How to apply
+
+- New shared package wrapping `@sentry/*`, `redis`, `mongodb`,
+  `opentelemetry`, or any other SDK with module-state: direct-dep the
+  SDK, pinned to an exact version. Export the SDK namespace if
+  consumers need the full surface
+  (`export { Sentry }; export * from 'X';`).
+- New consumer of such a wrapper: NEVER `require('@sentry/node')` or
+  similar in service code. Route everything through the wrapper.
+- For heavy SDKs only some consumers need (e.g. `@sentry/nextjs`),
+  use an *optional* peer dep at an exact pinned version, and document
+  in the wrapper README that consumers must install that version.
+- When stateful behavior fails mysteriously — scope tags missing,
+  registry lookups empty, singleton mismatch — `npm ls <sdk-package>`
+  is the first diagnostic. There must be exactly one entry, fully
+  deduped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -17,6 +17,7 @@
     "claude",
     "conventions",
     ".claude-template",
+    ".root-template",
     "bin",
     "README.md"
   ],

package/.claude-template/mcp.json

@@ -1,9 +0,0 @@
-{
-	"servers": {
-		"sentry": {
-			"serverUrl": "https://mcp.sentry.dev/mcp",
-			"type": "http"
-		}
-	},
-	"inputs": []
-}