@drawbridge/drawbridge-agents 0.1.10 → 0.1.15

package/claude/CLAUDE.md

@@ -12,6 +12,7 @@
 @../conventions/drawbridge-packages.md
 @../conventions/sentry-sdk.md
 @../conventions/app-web-forms.md
+@../conventions/app-web-gates.md
 @../conventions/docs-linkage.md
 @../conventions/superpowers-docs.md
 @../conventions/git-branching.md

package/conventions/app-web-gates.md

@@ -0,0 +1,22 @@
+# app-web gate helpers
+
+Applies to `drawbridge-app-web` only.
+
+UI gating goes through the shared helpers in `@/lib/helpers` — never inline the
+underlying object walks:
+
+- `hasCapability( organization, key, level = 'manage' )` — capability checks by
+  dot-path (`'campaigns.settings'`, `'brands'`). Never write
+  `organization?.capabilities?.x === 'manage'` inline; a missed optional chain
+  in that pattern has crashed pages before.
+- `hasConnection( organization, slug )` — "org has an ACTIVE connection for
+  this slug". Reads `connectionItems` from the org payload (see the
+  organization-payload contract in `cross-repo-contracts.md`); never fetch
+  `/organization/:id/connections` just to gate UI.
+- `hasRestriction( object, key )` — plan-limit restrictions on an org or
+  campaign.
+
+Compose extras (`getPlanFeature(...).granted`, totals checks) explicitly at the
+call site; the helpers stay single-purpose. Pass the org from the
+`[ 'organization', id ]` query cache (or an `enabled : false` `useQuery` on
+that key when the component must re-render as it refreshes).

package/conventions/cross-repo-contracts.md

@@ -26,6 +26,12 @@ skill) so it stops living only in tribal memory.
   `queue/index.js` together.
 - BullMQ jobs are keyed on the change-stream resume token as `jobId` for HA dedup across sync
   replicas. Reusing a static `jobId` with `removeOnComplete` makes re-enqueues no-op silently.
+- Scraped-asset file reuse keys on `organization + meta.origin + meta.element` **plus
+  `meta.render` for pipeline-rendered marks** (sync `resolveAsset` writes/queries it; the field
+  and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
+  `render` content-hashes the rendered output — drop `render` from either side and a rendering
+  fix never ships: reuse serves the first-ever render forever (the onemethod
+  black-on-black-logo-twice bug).
 
 ## Billing / metering
 
@@ -39,6 +45,14 @@ skill) so it stops living only in tribal memory.
   sync upserts the same invoice from three concurrent webhooks (finalized/payment_succeeded/voided)
   and relies on the index to reject the losing insert so the catch can redo it as an update. Drop
   the index → silent duplicate invoice rows; remove the catch → concurrent events throw + retry.
+- The `contact` collection's **unique multikey index on `leads`** (drawbridge-api
+  `schema/contact.js`) and sync's contact resolution (`lib/contact.js` + `queue/contact.js`) are
+  one contract: a lead belongs to at most one contact. One submission enqueues two resolve jobs
+  (lead insert + totals-update events) that race; the index rejects the losing create and the
+  worker retries it into the update path. The merge path must delete duplicate contacts BEFORE
+  `$set`-ing the survivor (the expanded `leads` array collides with rows about to be deleted).
+  Drop the index → duplicate contacts, doubled segment members, double-billed `contact.create` +
+  `segment.join`; reorder the merge → every merge aborts E11000 and duplicates never heal.
 
 ## `@drawbridge/*` package coordination
 
@@ -54,3 +68,32 @@ skill) so it stops living only in tribal memory.
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`
   and throws at call time, not at import. Check `drawbridge-docs/reference/packages.md` (the
   generated export surface) when unsure.
+
+## Shopify sales channel
+
+- `@drawbridge/shopify` storefront `getProduct`/`getProductVariantsPage` throw the **exact
+  message `'Shopify product not found'`** when the Storefront API can't see a product
+  (unpublished from the Drawbridge channel / deleted); transport and GraphQL failures throw
+  `'Shopify storefront error: …'`. drawbridge-sync's product worker (`queue/product.js`)
+  string-matches the not-found message to send publish-this-product ResourceFeedback instead of
+  retrying. Reword the message → unpublished products retry-loop forever and merchants get no
+  feedback; drawbridge-api's shopifyProduct route relies on the not-found throw staying a throw.
+- The `write_resource_feedbacks` and `read_publications` scopes live in drawbridge-shopify-app's
+  `shopify.app.*.toml` but power other repos: sync's product ResourceFeedback sends and the
+  embedded app's publishing section. Removing either → silent Shopify userErrors, no crash.
+- `SHOPIFY_REQUIRED_SCOPES` (`@drawbridge/shopify` `lib/constants.js`) must stay in lockstep with
+  `[access_scopes]` in drawbridge-shopify-app's `shopify.app.*.toml` (both files). drawbridge-api
+  diffs each store's granted scopes against it to flag "update permissions" on the connections
+  page. A scope added to the toml but not the constant silently escapes the check; one added to
+  the constant but not the toml flags every store forever.
+
+## Organization payload (api ↔ app-web)
+
+- `connectionItems` on the org payload comes only from drawbridge-api
+  `extend.organization({ connections : true })` (org GET + org menu opt in via
+  `hasOrganizationAccess`); app-web's `hasConnection` helper (`lib/helpers.js`) and api's
+  `lib/tasks.js connectionErrors` read it. Two invariants: the lookup's `$project`
+  (id/slug/status/title/shop/errors) is a **security boundary** — the org response spreads to the
+  browser, so adding a credential field ships connection tokens to every dashboard user; and api
+  deploys before app-web — the gate treats a missing field as "no connection" and silently hides
+  connection-gated UI (e.g. the campaign Shop product columns row).

package/package.json

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