@drawbridge/drawbridge-agents 0.1.38 → 0.1.40

package/.claude-template/skills/drawbridge-add-connection/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: drawbridge-add-connection
+description: Use when adding a new vendor connection (a new manifest in drawbridge-utils) — runs the auth-type assessment FIRST so the integration is built the way the vendor's own docs recommend, then walks the build against the documented checklist and its guards.
+---
+
+# Add a connection
+
+A connection is one manifest file in `drawbridge-utils/lib/connections/`, and the
+build half is documented — `drawbridge-docs/reference/connection-hooks.md`,
+"Adding a connection". This skill exists for what comes BEFORE the file: deciding
+what kind of connection to build, from the vendor's documentation rather than
+from whichever auth mechanism is easiest to wire.
+
+The failure it prevents is real: Attentive was first built as pasted API keys
+because keys worked, and their docs turned out to frame private-app keys as
+"integrate your own account" — the public OAuth app was the documented path for
+platforms like Drawbridge. The rebuild cost an afternoon; the assessment costs
+ten minutes.
+
+## When to use
+
+Any new vendor manifest, and any auth-type change to an existing one (keys →
+OAuth is a rebuild of the auth surface, not a tweak).
+
+## Steps
+
+1. **Fetch the vendor's developer docs and answer these in writing, with the
+   URL of the page that answers each.** Never from memory — the Klaviyo consent
+   url was once written from memory, pointed at their API host, and stalled
+   every merchant on a blank page.
+
+   - What auth mechanisms exist, and **who does the vendor say each is for**?
+     The distinction that matters is *your own account* versus *accounts outside
+     your organization*. Drawbridge is always the second: merchants connect
+     THEIR account to OUR platform.
+   - Is there a partner / public-app / marketplace program? What does
+     registration take, and what credentials does it issue?
+   - For OAuth: authorize url, token url, how client credentials are sent
+     (form fields vs Basic header), whether PKCE is required, token lifetime,
+     whether refresh tokens exist, scope names.
+
+2. **Pick the `auth.type` from the answers, not from convenience:**
+
+   | vendor's shape | type |
+   |---|---|
+   | installed from the vendor's app store, never redirects back | `install` |
+   | registered app, merchant consents on the vendor's screen | `oauth` |
+   | the vendor offers ONLY per-account credentials | `keys` |
+   | no third party behind it at all | `generated` |
+
+   `keys` when OAuth exists is a decision someone must make out loud — usually
+   as an explicitly-flagged interim while a partner registration is pending, and
+   the manifest header says so.
+
+3. **If the app is not yet registered, build it dormant.** `requires` names the
+   client env vars that will exist after registration; until they land on a
+   deployment, the connection is offered nowhere. Shipping the manifest complete
+   and inert beats waiting — adding the env vars becomes the launch.
+
+4. **Record the assessment in the manifest header**: every cited fact, every
+   contradiction between the vendor's own pages (cite both and say which one the
+   code models), and — for OAuth — the questions only a live registration
+   answers: does consent echo `state` back, what is the real token lifetime,
+   does one app accept both environments' redirect urls.
+
+5. **Build against the checklist** in
+   `drawbridge-docs/reference/connection-hooks.md` → "Adding a connection". Its
+   guards are the enforcement: the directory-registration test, the
+   feature-grant test, `build()` itself. Trust the named failures over your
+   memory of the steps.
+
+## Notes
+
+- The manifest is the only place vendor facts live. If the assessment finds a
+  fact that must hold across repos, record it with `drawbridge-record-contract`.
+- The picker/search question is part of the assessment: if the vendor's list
+  endpoint filters by name server-side, the field must NOT declare
+  `search : false` — Attentive was the first vendor that could, and a test pins
+  that it stays searchable.

package/conventions/cross-repo-contracts.md

@@ -9,7 +9,7 @@ skill) so it stops living only in tribal memory.
 
 - `OAUTH_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** — both
   `assertEnv` it at boot. A mismatch silently breaks realtime token verification.
-- `UNSUBSCRIBE_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** —
+- `HMAC_UNSUBSCRIBE_TOKEN_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** —
   both `assertEnv` it at boot. Sync signs the unsubscribe tokens it builds into notification
   emails (`lib/suppression.js buildToken`); api verifies them on the public `/unsubscribe/:token`
   routes (`lib/unsubscribe.js`). A mismatch makes every unsubscribe link 404 as "invalid or
@@ -343,6 +343,34 @@ skill) so it stops living only in tribal memory.
 - `sizes.original` must be set when a multipart upload completes, not at create — the resize
   worker reads it as its source, and a file without it is shaped unlike every other file.
 
+## Connection manifests are the single declaration (utils ↔ api ↔ sync ↔ webhooks)
+
+A connection is **one file** in `drawbridge-utils/lib/connections/`. Everything else
+derives from it: the builder catalog and `enums.step.type` in api, the queue routing table
+and hook registry in sync, the inbound receiver in webhooks, the connections page in
+app-web. Adding a vendor is that file plus its import in `index.js` — a test reads the
+directory and fails if the two disagree, because a manifest nothing imports is a vendor
+that exists on disk and in nobody's catalog.
+
+**`STEPS` and `RETIRED` in `contract.js` must stay in step with `enums.step.type` in the
+api.** That enum is the `$jsonSchema` validator on the workflow collection: a type absent
+from it is rejected by the DATABASE with "Document failed validation" naming no field. The
+enum DERIVES from `STEPS` and UNIONS its own legacy map — union rather than replace, or
+stored documents carrying a retired type become unwritable, including by the migration that
+would retire them.
+
+**A hook lives in drawbridge-sync only if it needs Drawbridge's own database, sockets or
+queues.** Everything else belongs on the manifest. `lib/hooks/` in sync mirrors
+`lib/connections/` in utils, one file per connection. A hook declared `{}` means "supported,
+implemented in the repo holding the dependencies"; if that registration is missing the
+runner resolves nothing and the step is SKIPPED with a `succeeded` record — silent, so
+`step-handler-coverage.test.js` asserts both directions.
+
+**Job identity is production state.** Step types, queue names and jobIds are live in Redis;
+renaming one orphans what is already enqueued and starts a parallel stream nobody consumes,
+with no error. `bullmq-identity.test.js` in sync spells out the routing table so moving a
+step between queues requires editing it deliberately.
+
 ## Import surfaces
 
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`

package/conventions/rules.md

@@ -6,3 +6,9 @@
 3. Don't touch unrelated code. If a file or function is not directly part of the current task, do not modify it, even if you think it could be improved.
 
 4. Flag uncertainty explicitly. If you are not confident about an approach or technical detail, say so before proceeding. Confidence without certainty causes more damage than admitting a gap.
+
+5. Read the code before you have an opinion about it. Never describe what a component, handler or helper does — what props it takes, what it cannot do, whether two things are the same — on the strength of a grep or a partial read. Open the whole file first. A grep tells you a string is present; it cannot tell you what surrounds it, what the other variant does, or which prop already solves the problem you are about to declare unsolvable.
+
+   This is not a style preference, it is the difference between advice and noise. Asserting a limitation that isn't real sends the reader to check your work, and asserting two implementations are identical when one carries a field the other drops ships a regression. Both have happened.
+
+   In practice: before claiming a component can't do something, read the component. Before calling two implementations equivalent, read both ends to end. Before proposing a new endpoint or field to work around a gap, confirm the gap exists in the code rather than in your sample of it.

package/conventions/workflow-step-naming.md

@@ -0,0 +1,70 @@
+# Workflow step naming
+
+Step `type` strings follow **`step.<domain>[.<resource>].<verb>`** — dots, never dashes.
+
+The resource segment appears when the domain acts on more than one thing, and is omitted
+when it acts on one. Both forms are correct:
+
+    step.shopify.order.record       four — shopify manages orders, customers,
+    step.shopify.customer.insert           discounts, products, tokens
+    step.shopify.token.refresh
+
+    step.email.send                 three — email sends one thing
+    step.email.notify
+    step.sms.send
+    step.segment.sync
+
+State it as a flat four segments and the three-segment ones read as drift, and someone
+tries to "correct" them. They are not drift.
+
+**The last segment is a verb.** `step.webhook.outgoing` breaks that — `outgoing` is a
+direction — and should have been `step.webhook.send`. **Do not rename it**: webhooks are
+shipped and step slugs are stored in workflow documents. Known exception, not a pattern.
+
+## Renaming
+
+**Stored step slugs cannot be renamed once merchants hold them.** A rename is only free
+while a slug has no workflows anywhere, which in practice means before it reaches `main`.
+Check both environments before assuming — dev counts prove nothing about production.
+
+## Adding a step
+
+**This used to be a six-place ritual.** The type string had to appear identically in the
+api's `enums.step.type`, its workflow catalog, its `stepSettingsShapes`, sync's
+`stepTypeToQueueName`, sync's handler registry, and app-web's builder — and a mismatch in
+any one failed silently, saving the step and then dropping the work at run time.
+
+It is now **two places**, and both are declarations rather than copies:
+
+1. `drawbridge-utils/lib/connections/contract.js` — the type and its label in `STEPS`
+2. `drawbridge-utils/lib/connections/<vendor>.js` — the step, and the hook it points at
+
+Everything else DERIVES: the builder catalog, `enums.step.type`, `stepSettingsShapes`,
+sync's routing table. `build()` refuses the manifest at import if the declaration and the
+hook disagree, and `step-handler-coverage.test.js` in drawbridge-sync fails if the body is
+missing.
+
+**A step that does real work must declare a `hook`.** The runner resolves hooks by
+declaration, so a step declaring none is *skipped* — the step doc reads `succeeded` with a
+null message and the work silently stops. That shipped once, for `segment.sync`.
+
+## Labels
+
+**One label, in `STEPS`.** The enum label and the builder's `key` used to be two strings
+for one step and they drifted — `step.sms.send` was "Send SMS" in the enum and "Send Twilio
+SMS" in the builder. The enum now derives from `STEPS`, so there is nothing to keep in
+step.
+
+The label lives on the vocabulary rather than on a vendor because a step type belongs to
+the CAPABILITY: Klaviyo and Mailchimp both do `contacts.sync`, and a label taken from
+either would show a merchant two identically-named entries. A manifest's own `key` is the
+INSTANCE label — "Sync contact to Acme Co" — which is a different sentence for a different
+place.
+
+## Retiring a type
+
+`RETIRED` in `contract.js` maps each retired type to what it became. Stored documents carry
+the old names until a backfill runs, and the runner resolves a manifest **by type** — so
+without that map a legacy step finds no manifest and is silently skipped. `enums.step.type`
+keeps every retired key so those documents stay writable, including by the migration that
+retires them. A type leaves the map a release AFTER its backfill, never with it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {