@drawbridge/drawbridge-agents 0.0.6 → 0.0.8

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

@@ -4,3 +4,6 @@
 @../conventions/jsx-fragments.md
 @../conventions/transactions.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/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.8",
   "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": []
-}