@open-mercato/cli 0.6.7-develop.6685.1.77c0a5591b → 0.6.7-develop.6686.1.bdda5ed397

package/dist/agentic/shared/ai/skills/om-integration-builder/references/package-and-activation.md

@@ -0,0 +1,16 @@
+# Package and Activation
+
+Load this reference to choose provider ownership before creating files.
+
+1. **App-specific (default):** create `src/modules/<provider>/`, add `index.ts`, `integration.ts`, `di.ts`, the installed typed host adapter when one exists, `acl.ts`/`setup.ts` when features or bootstrap are needed, validators, transport services, and health; activate it as `{ id: '<provider>', from: '@app' }` in `src/modules.ts` and run generation/typecheck/focused tests in this app. A detached client seam alone is never a production registration.
+2. **Reusable (explicit user requirement):** create a separate publishable package/repository with compatible peer/runtime dependencies, public exports, build/prepack, and compiled discovery output. Add its packed artifact to the standalone app as a dependency and activate it in `src/modules.ts`.
+3. Do not create `packages/*` or add workspace configuration inside a standalone app unless the user explicitly approves that architecture change. Ask before adding the reusable provider's production dependency.
+4. Persist credentials/state/logs/mappings through generic integration/data-sync services; do not duplicate host tables.
+5. If env bootstrap is needed, implement a provider-prefixed preset inside provider `setup.ts` and an idempotent rerun CLI.
+6. Test missing provider configuration as `unconfigured`/degraded, not a crash or secret leak.
+
+An app-owned `integration.ts` may export singular `integration`/`bundle` definitions or plural `integrations`/`bundles` arrays. Prefer the singular form for one provider and keep any default export aligned with it; generation normalizes both forms. Run `yarn generate` and `yarn typecheck` so the generated registry proves that exact export shape.
+
+For payment providers, implement `GatewayAdapter`, register it with `registerGatewayAdapter`, make its verified webhook path reachable with `registerWebhookHandler`, and publish UI capabilities with `registerPaymentGatewayDescriptor`. For shipping providers, implement `ShippingAdapter` and call `registerShippingAdapter`. Transactional email over SMTP has no equivalent installed generic adapter: register the app-owned sender and exact health service in DI instead. Mailbox providers use the separate installed `communication_channels` `ChannelAdapter` path described in `provider-families.md`.
+
+On the reusable branch, record the supported host/framework version range and test package exports from a fresh standalone consumer. Do not impose packed-consumer work on the local-module branch.

package/dist/agentic/shared/ai/skills/om-integration-builder/references/provider-families.md

@@ -0,0 +1,14 @@
+# Provider Families
+
+Load this reference to choose provider contracts.
+
+- **Transactional email:** tenant credentials; `IntegrationDefinition`; DI sender and health services; bounded retry/redaction; activation. No generic installed transactional-email adapter exists, so do not invent one.
+- **Mailbox/email channel:** installed `communication_channels` hub; `ChannelAdapter`; `integration.ts` with `hub: 'communication_channels'`; DI + setup adapter/health registration; per-user credentials; threading/dedup; webhook/poll convergence. Follow installed `channel_gmail`/`channel_imap` facts and contracts.
+- **Shipping:** installed `ShippingAdapter` plus `registerShippingAdapter`; services/rates/labels/tracking; address/package validation; idempotent fulfillment transitions; signed status callbacks. Keep host domain state provider-neutral (`provider-neutral-domain`); the carrier module is optional, so preserve a safe absent-provider path (`optional-provider`).
+- **Payment:** installed `GatewayAdapter` plus `registerGatewayAdapter`, `registerWebhookHandler`, and `registerPaymentGatewayDescriptor`; register `verifyWebhook` so the host can reach it; durable idempotency; money/currency exactness; signed webhook reconciliation; concurrency-safe status machine.
+- **Data sync:** `DataSyncAdapter`; entity mappings/presets; external IDs; streaming batches/cursors; overlap, progress, cancellation, reconciliation.
+- **Webhooks:** inbound verification/replay; outbound Standard Webhooks signing; queued deliveries, retries, logs, status.
+- **Import/export:** streaming format adapter; mapping/validation; formula and archive safety; row errors; progress/artifact cleanup.
+- **Storage/media:** authorize object/record access (`artifact-authorization`); use scoped keys, signed access, encrypted metadata (`encrypted-storage`), retention, and lifecycle cleanup (`cleanup`).
+
+Combine branches only when the provider genuinely owns them. Keep generic orchestration in the installed host services.

package/dist/agentic/shared/ai/skills/om-integration-builder/references/security-and-reliability.md

@@ -0,0 +1,15 @@
+# Provider Security and Reliability
+
+Load this reference for every external provider.
+
+- Encrypt credentials through host services (`encrypted-credentials`). Thread per-user scope on every per-user read/write. Tenant-wide scope is valid only when the installed provider/job contract declares it; it never sees per-user or organization-owned rows without deriving their narrower trusted scope.
+- Validate configurable URLs for SSRF, redirects, private networks, protocols, and DNS. Bound request/response size and timeout.
+- Redact headers/tokens/credentials/signed URLs/sensitive bodies from logs, events, errors, and fixtures.
+- Verify inbound signatures on raw body (`webhook-signature`) with timestamp/replay limits (`replay-protection`); atomically claim each inbox delivery before side effects (`atomic-inbox-claim`) and make duplicate callbacks/subscribers idempotent (`subscriber-idempotency`).
+- Use bounded exponential retry with jitter and explicit handling of timeouts, 429/retry-after, 5xx, invalid payloads, and terminal 4xx.
+- Persist a stable idempotency key for every remote mutation; reuse it across transaction rollback and worker retry.
+- Reconcile provider truth after ambiguous/partial responses. Protect state transitions against webhook/poll/manual races.
+- Health checks and OAuth refresh retries redact credentials and provider details (`health-retry-redaction`); concurrent refresh uses one guarded winner (`oauth-single-flight-refresh`).
+- Keep API-version/capability/site/store/currency variants explicit and validated.
+
+Tests cover normal, duplicate, concurrent, timeout, rate limit, malformed, partial, signature, replay, and redaction behavior.

package/dist/agentic/shared/ai/skills/om-integration-builder/references/sync-and-files.md

@@ -0,0 +1,12 @@
+# Sync and File Branches
+
+Load for `DataSyncAdapter`, imports, or exports.
+
+1. Stream pages/rows with bounded memory. Validate mappings, formats, encoding, locale, decimals, dates, and maximum sizes.
+2. Isolate item errors and report them without stopping safe siblings; define batch-atomic versus item-atomic semantics.
+3. Save external ID mappings and cursor only after the durable batch commits. A transient page failure leaves the previous cursor intact.
+4. Prevent overlapping scoped runs or define safe concurrency. Support cancellation, retry, resume, progress, and final reconciliation.
+5. Neutralize spreadsheet formulas, reject archive/path traversal, and clean temporary files in `finally`/retention while preserving declared artifacts.
+6. Test first run, rerun, partial error, duplicate item, page failure, retry/resume, cancellation, and provider variant.
+
+Use mocked contract endpoints unless the user explicitly supplies and approves live test credentials.