@ekanos/cli 0.2.0 → 0.2.2

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.2.0",
-  "private": false,
+  "version": "0.2.2",
   "type": "module",
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test a Fusion integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "license": "MIT",
@@ -34,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ekanos/integration-schema": "0.1.5",
+    "@ekanos/integration-schema": "0.2.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/AGENTS.md.tmpl

@@ -212,9 +212,15 @@ your slug (`__SLUG__-<name>`). `widgetState` (usually `'active'`), plus
 
 Render through the `Widget.*` compound API and `WidgetContext` from
 `@ekanos/sdk/components`; wrap in `WidgetPreviewProvider` to render outside
-the host. There is **no client-side `ctx.fetch`** — a widget reads declared
-`clientReadable` account-scope storage back with `fetchIntegrationStorage()`
-from `@ekanos/sdk/hooks`, and anything else needs your own seam.
+the host. Widgets talk to a vendor with `useIntegrationFetch()` from
+`@ekanos/sdk/hooks` — never global `fetch` — and reach for `useActivationData()`
+(same module) when a widget needs a client-visible credential or activation
+field. Both have a safe default when nothing has mounted a provider (a plain
+fetch wrapper, and `null`, respectively), so calling them never crashes; see
+"Network model" below for what that fetch is actually gated by, in the
+harness and in production. A widget reads declared `clientReadable`
+account-scope storage back with `fetchIntegrationStorage()` from
+`@ekanos/sdk/hooks`.
 
 Build widget UI from `@ekanos/ui` — the published slice of the host design
 system. Available modules (import individually, e.g. `@ekanos/ui/button`):
@@ -240,11 +246,13 @@ it looking like anything in particular.
 The harness (`npx ekanos dev`) mocks FUSION, not your vendor. **You do not
 need mock data to develop against the real API**, and never claim otherwise:
 the dev toolbar has a fixtures ⇄ live switch per integration, and in live
-mode your widgets' real query functions run and their requests reach the
-real vendor API. The only gate is the `egress` allowlist from
-`defineIntegration()` — enforced locally by the same matcher production
-uses, so an origin you forgot to declare fails on this machine with
-`EgressDeniedError` instead of in review.
+mode your widgets' real query functions — calling `useIntegrationFetch()` —
+run and their requests reach the real vendor API. The gate is the `egress`
+allowlist from `defineIntegration()`, checked with the same matcher
+production's `ctx.fetch` uses, so an origin you forgot to declare fails on
+this machine with `EgressDeniedError` instead of in review — see "Network
+model" below for what that check does and does not mean once you're not in
+the harness anymore.
 
 Live mode is opt-in per integration. Add a `live` block to the entry in
 `harness.config.ts`:
@@ -269,6 +277,30 @@ webhook/schedule/onActivate handlers against the mock context (its
 `ctx.fetch` never touches the network) — cover handler network behavior
 with fixtures in tests, then for real on the dev host after publishing.
 
+### Network model
+
+Two different fetches, two different guarantees:
+
+- **`ctx.fetch` (handlers — `onActivate`/webhooks/schedules/tools).** Real
+  enforcement, in the harness AND in production: your `egress` allowlist,
+  redirect re-vetting, IP pinning. Locally, handlers only ever run on
+  Triggers/Activate against the mock context, so their `ctx.fetch` never
+  leaves your machine regardless of the toolbar — real network only after
+  you publish to a dev host.
+- **`useIntegrationFetch()` (widgets, browser-side).** In the harness, live
+  mode routes it through the same egress check as a convenience, enforced
+  centrally rather than something you configure per widget. **That check
+  does not exist in production** — a browser can't pin an address or
+  re-vet a redirect the way `ctx.fetch` does, and today's host mounts no
+  egress check on the client path at any layer. Do not read
+  `useIntegrationFetch()`'s live-mode behavior as "the same protection as
+  `ctx.fetch`, just in the browser" — that is the one thing this section
+  means to rule out.
+
+In short: widgets get real network in Live API mode, gated by convenience in
+the harness and by nothing in production; handlers get fixtures locally and
+the real, enforced thing only after publish.
+
 ## Testing
 
 `@ekanos/sdk/testing` builds the same context production uses, in memory —

package/templates/skills/build-integration/references/widget-design.md

@@ -71,8 +71,11 @@ hierarchy, and no amount of padding will save it.
 
 Every widget: `'use client'`, `Widget.DataState` wrapping `Widget.Card` →
 `Widget.Header` + `Widget.Loading` + `Widget.Error` + `Widget.Active`. Gate
-fetching on `ctx?.state.state === 'active'` from `WidgetContext`. Copy the
-canonical example from the SDK README rather than improvising the tree.
+fetching on `ctx?.state.state === 'active'` from `WidgetContext`, and fetch
+with `useIntegrationFetch()` from `@ekanos/sdk/hooks` — never global
+`fetch` — reaching for `useActivationData()` (same module) if the widget
+needs a client-visible credential. Copy the canonical example from the SDK
+README rather than improvising the tree.
 
 `Widget.Active` itself renders flush (no padding) so full-bleed charts and
 tables can run edge-to-edge. For ordinary content — text, rows, a KPI