@ekanos/cli 0.1.1 → 0.1.3

package/dist/publish-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"publish-api.js","sourceRoot":"","sources":["../src/publish-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from './auth/fusion-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  invalidStateError,\n  networkError,\n  notFoundError,\n  validationError,\n} from './errors';\n\n/**\n * The CLI's client for the Fusion submission intake route.\n *\n * ---------------------------------------------------------------------------\n * WIRE CONTRACT — the seam between this package and the Fusion web app.\n *\n * The server side lives in `apps/web/app/api/partner/submissions/route.ts`.\n * As with the auth routes (see `auth/fusion-api.ts`), the two halves are\n * coupled only by HTTP; tests stub `fetch`, never the route.\n *\n *   POST /api/partner/submissions    [Authorization: Bearer <access_token>]\n *     ← multipart/form-data:\n *         source   — Fusion source slug\n *         slug     — integration slug (kebab-case)\n *         version  — semver\n *         manifest — JSON string (the parsed ekanos.json + declaration summary)\n *         archive  — gzipped tarball, ≤ 4 MiB\n *     → 201 { ok: true, data: { submissionId, slug, version, state,\n *                               archiveSha256 } }\n *     → 400 { error, code: \"INVALID_REQUEST\" | \"INVALID_ARCHIVE\" }\n *     → 401 { error, code: \"AUTH_REQUIRED\" }      token absent or expired —\n *                                                 refresh once and retry\n *     → 403 { error, code: \"FORBIDDEN\" }          no dev seat on the source\n *     → 404 { error, code: \"SOURCE_NOT_FOUND\" }\n *     → 409 { error, code: \"VERSION_EXISTS\" }     this (slug, version) is\n *                                                 already submitted\n *     → 413 { error, code: \"ARCHIVE_TOO_LARGE\" }\n *     → 3xx                                       treated as 401 (an\n *                                                 auth-gated Fusion page\n *                                                 answers 307)\n * ---------------------------------------------------------------------------\n */\n\nexport interface SubmissionPayload {\n  source: string;\n  slug: string;\n  version: string;\n  /** JSON string — already serialized by the caller. */\n  manifest: string;\n  archive: Uint8Array;\n}\n\nexport interface SubmissionReceipt {\n  submissionId: string;\n  slug: string;\n  version: string;\n  state: string;\n  archiveSha256: string;\n}\n\nexport type SubmitResult =\n  | { status: 'ok'; receipt: SubmissionReceipt }\n  /** The bearer token did not authenticate — refresh and retry, once. */\n  | { status: 'unauthorized' };\n\nexport async function submitArchive(\n  host: string,\n  accessToken: string,\n  payload: SubmissionPayload,\n): Promise<SubmitResult> {\n  const form = new FormData();\n  form.append('source', payload.source);\n  form.append('slug', payload.slug);\n  form.append('version', payload.version);\n  form.append('manifest', payload.manifest);\n  form.append(\n    'archive',\n    // Copy into a fresh Uint8Array: Buffer is Uint8Array<ArrayBufferLike>,\n    // which BlobPart refuses (a SharedArrayBuffer view is not a BlobPart).\n    new Blob([new Uint8Array(payload.archive)], { type: 'application/gzip' }),\n    'archive.tgz',\n  );\n\n  const response = await request(`${host}/api/partner/submissions`, {\n    method: 'POST',\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n    },\n    body: form,\n  });\n\n  // 401, or the 307 an auth-gated Fusion route answers with: the token did\n  // not authenticate. The caller owns the refresh-and-retry decision.\n  if (response.status === 401 || isRedirect(response.status)) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const serverMessage = str(body.error);\n\n  if (response.status === 403) {\n    throw forbiddenError(\n      serverMessage ??\n        `${host} refused the submission: this account does not hold the ` +\n          `dev seat on source \"${payload.source}\".`,\n      `Ask the source operator to grant your account the developer seat for ` +\n        `\"${payload.source}\", then retry.`,\n    );\n  }\n\n  if (response.status === 404) {\n    throw notFoundError(\n      serverMessage ?? `${host} has no source with slug \"${payload.source}\".`,\n      `Check the --source value (or the \"source\" field in ekanos.json) ` +\n        `against the slug your Fusion operator gave you.`,\n    );\n  }\n\n  if (response.status === 409) {\n    throw invalidStateError(\n      serverMessage ??\n        `Version ${payload.version} of \"${payload.slug}\" is already submitted.`,\n      `Submitted versions are immutable. Bump the \"version\" field in ` +\n        `package.json and publish again.`,\n    );\n  }\n\n  if (response.status === 400 || response.status === 413) {\n    throw validationError(\n      serverMessage ?? `${host} rejected the submission as invalid.`,\n      `Fix the reported problem and re-run \"ekanos publish\". If the message ` +\n        `names the archive, re-check the project layout (\"ekanos validate\").`,\n    );\n  }\n\n  if (!response.ok) {\n    throw networkError(\n      `${host}/api/partner/submissions responded ${response.status}.`,\n      response.status >= 500\n        ? `The Fusion deployment returned a server error. Retry shortly; if ` +\n            `it persists, report it with the status code.`\n        : `Confirm the host is a Fusion deployment running a build that ` +\n            `includes the partner submissions route.`,\n    );\n  }\n\n  const data = (body.data ?? {}) as Record<string, unknown>;\n  const receipt = {\n    submissionId: str(data.submissionId),\n    slug: str(data.slug),\n    version: str(data.version),\n    state: str(data.state),\n    archiveSha256: str(data.archiveSha256),\n  };\n\n  if (Object.values(receipt).some((value) => value === null)) {\n    throw networkError(\n      `${host} accepted the submission but returned an incomplete receipt.`,\n      `Confirm the deployment is running a Fusion build that includes the ` +\n        `partner submissions route, then check the submission's state with ` +\n        `your operator before re-publishing.`,\n    );\n  }\n\n  return { status: 'ok', receipt: receipt as SubmissionReceipt };\n}\n\n/** Guard for the \"still unauthorized after one refresh\" terminal case. */\nexport function stillUnauthorized(host: string): never {\n  throw authRequiredError(\n    `The session for ${host} could not authorize the submission.`,\n    `Run \"ekanos login --host ${host}\" and retry.`,\n  );\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n\nfunction isRedirect(status: number): boolean {\n  return status >= 300 && status < 400;\n}\n\nfunction str(value: unknown): string | null {\n  return typeof value === 'string' && value.length > 0 ? value : null;\n}\n"]}
+{"version":3,"file":"publish-api.js","sourceRoot":"","sources":["../src/publish-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from './auth/fusion-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  invalidStateError,\n  networkError,\n  notFoundError,\n  validationError,\n} from './errors';\n\n/**\n * The CLI's client for the Fusion submission intake route.\n *\n * ---------------------------------------------------------------------------\n * WIRE CONTRACT — the seam between this package and the Fusion web app.\n *\n * The server side lives in `apps/web/app/api/partner/submissions/route.ts`.\n * As with the auth routes (see `auth/fusion-api.ts`), the two halves are\n * coupled only by HTTP; tests stub `fetch`, never the route.\n *\n *   POST /api/partner/submissions    [Authorization: Bearer <access_token>]\n *     ← multipart/form-data:\n *         source   — Fusion source slug\n *         slug     — integration slug (kebab-case)\n *         version  — semver\n *         manifest — JSON string (the parsed ekanos.json + declaration summary)\n *         archive  — gzipped tarball, ≤ 4 MiB\n *     → 201 { ok: true, data: { submissionId, slug, version, state,\n *                               archiveSha256 } }\n *     → 400 { error, code: \"INVALID_REQUEST\" | \"INVALID_ARCHIVE\" }\n *     → 401 { error, code: \"AUTH_REQUIRED\" }      token absent or expired —\n *                                                 refresh once and retry\n *     → 403 { error, code: \"FORBIDDEN\" }          no dev seat on the source\n *     → 404 { error, code: \"SOURCE_NOT_FOUND\" }\n *     → 409 { error, code: \"VERSION_EXISTS\" }     this (slug, version) is\n *                                                 already submitted\n *     → 413 { error, code: \"ARCHIVE_TOO_LARGE\" }\n *     → 3xx                                       treated as 401 (an\n *                                                 auth-gated Fusion page\n *                                                 answers 307)\n *\n *   GET /api/partner/submissions?source=<slug|id>  [Authorization: Bearer]\n *     → 200 { ok: true, data: { source, integrations: [{ id, slug, name,\n *             createdAt, versions: [{ id, version, state, archiveSha256,\n *             submittedAt }] }] } }\n *     → 400 { error, code: \"INVALID_REQUEST\" }\n *     → 401 { error, code: \"AUTH_REQUIRED\" }      refresh once and retry\n *     → 403 { error, code: \"MFA_REQUIRED\" }\n *     → 404 { error, code: \"SOURCE_NOT_FOUND\" }\n *     → 3xx                                       treated as 401\n * ---------------------------------------------------------------------------\n */\n\n/**\n * The server's manifest cap — 64 KiB of UTF-8, enforced in\n * `apps/web/app/api/partner/submissions/_lib/submission-validation.ts` against\n * `Buffer.byteLength`. Mirrored here so `publish` can refuse an oversized\n * manifest with a clear message instead of the server's generic 400.\n */\nexport const MAX_MANIFEST_BYTES = 64 * 1024;\n\nexport interface SubmissionPayload {\n  source: string;\n  slug: string;\n  version: string;\n  /** JSON string — already serialized by the caller. */\n  manifest: string;\n  archive: Uint8Array;\n}\n\nexport interface SubmissionReceipt {\n  submissionId: string;\n  slug: string;\n  version: string;\n  state: string;\n  archiveSha256: string;\n}\n\nexport type SubmitResult =\n  | { status: 'ok'; receipt: SubmissionReceipt }\n  /** The bearer token did not authenticate — refresh and retry, once. */\n  | { status: 'unauthorized' };\n\nexport async function submitArchive(\n  host: string,\n  accessToken: string,\n  payload: SubmissionPayload,\n): Promise<SubmitResult> {\n  const form = new FormData();\n  form.append('source', payload.source);\n  form.append('slug', payload.slug);\n  form.append('version', payload.version);\n  form.append('manifest', payload.manifest);\n  form.append(\n    'archive',\n    // Copy into a fresh Uint8Array: Buffer is Uint8Array<ArrayBufferLike>,\n    // which BlobPart refuses (a SharedArrayBuffer view is not a BlobPart).\n    new Blob([new Uint8Array(payload.archive)], { type: 'application/gzip' }),\n    'archive.tgz',\n  );\n\n  const response = await request(`${host}/api/partner/submissions`, {\n    method: 'POST',\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n    },\n    body: form,\n  });\n\n  // 401, or the 307 an auth-gated Fusion route answers with: the token did\n  // not authenticate. The caller owns the refresh-and-retry decision.\n  if (response.status === 401 || isRedirect(response.status)) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const serverMessage = str(body.error);\n\n  if (response.status === 403) {\n    throw forbiddenError(\n      serverMessage ??\n        `${host} refused the submission: this account does not hold the ` +\n          `dev seat on source \"${payload.source}\".`,\n      `Ask the source operator to grant your account the developer seat for ` +\n        `\"${payload.source}\", then retry.`,\n    );\n  }\n\n  if (response.status === 404) {\n    throw notFoundError(\n      serverMessage ?? `${host} has no source with slug \"${payload.source}\".`,\n      `Check the --source value (or the \"source\" field in ekanos.json) ` +\n        `against the slug your Fusion operator gave you.`,\n    );\n  }\n\n  if (response.status === 409) {\n    throw invalidStateError(\n      serverMessage ??\n        `Version ${payload.version} of \"${payload.slug}\" is already submitted.`,\n      `Submitted versions are immutable. Bump the \"version\" field in ` +\n        `package.json and publish again.`,\n    );\n  }\n\n  if (response.status === 400 || response.status === 413) {\n    throw validationError(\n      serverMessage ?? `${host} rejected the submission as invalid.`,\n      `Fix the reported problem and re-run \"ekanos publish\". If the message ` +\n        `names the archive, re-check the project layout (\"ekanos validate\").`,\n    );\n  }\n\n  if (!response.ok) {\n    throw networkError(\n      `${host}/api/partner/submissions responded ${response.status}.`,\n      response.status >= 500\n        ? `The Fusion deployment returned a server error. Retry shortly; if ` +\n            `it persists, report it with the status code.`\n        : `Confirm the host is a Fusion deployment running a build that ` +\n            `includes the partner submissions route.`,\n    );\n  }\n\n  const data = (body.data ?? {}) as Record<string, unknown>;\n  const receipt = {\n    submissionId: str(data.submissionId),\n    slug: str(data.slug),\n    version: str(data.version),\n    state: str(data.state),\n    archiveSha256: str(data.archiveSha256),\n  };\n\n  if (Object.values(receipt).some((value) => value === null)) {\n    throw networkError(\n      `${host} accepted the submission but returned an incomplete receipt.`,\n      `Confirm the deployment is running a Fusion build that includes the ` +\n        `partner submissions route, then check the submission's state with ` +\n        `your operator before re-publishing.`,\n    );\n  }\n\n  return { status: 'ok', receipt: receipt as SubmissionReceipt };\n}\n\nexport interface SubmissionVersion {\n  id: string;\n  version: string;\n  state: string;\n  archiveSha256: string | null;\n  submittedAt: string | null;\n}\n\nexport interface SubmissionListing {\n  id: string;\n  slug: string;\n  name: string | null;\n  createdAt: string | null;\n  versions: SubmissionVersion[];\n}\n\nexport type ListResult =\n  | { status: 'ok'; integrations: SubmissionListing[] }\n  /** The bearer token did not authenticate — refresh and retry, once. */\n  | { status: 'unauthorized' };\n\n/**\n * List the caller's visible submissions for a source. Same authorization model\n * as `submitArchive`: the seat SELECT policies filter server-side, so a caller\n * with no seat sees an empty list rather than an error.\n */\nexport async function listSubmissions(\n  host: string,\n  accessToken: string,\n  source: string,\n): Promise<ListResult> {\n  const response = await request(\n    `${host}/api/partner/submissions?source=${encodeURIComponent(source)}`,\n    {\n      method: 'GET',\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n      },\n    },\n  );\n\n  if (response.status === 401 || isRedirect(response.status)) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const serverMessage = str(body.error);\n\n  if (response.status === 403) {\n    throw forbiddenError(\n      serverMessage ?? `${host} refused to list submissions for \"${source}\".`,\n      `Complete MFA in the browser if the message names it, then run ` +\n        `\"ekanos login --host ${host}\" again.`,\n    );\n  }\n\n  if (response.status === 404) {\n    throw notFoundError(\n      serverMessage ?? `${host} has no source with slug \"${source}\".`,\n      `Check the \"source\" field in ekanos.json (or --source) against the ` +\n        `slug your Fusion operator gave you.`,\n    );\n  }\n\n  if (response.status === 400) {\n    throw validationError(\n      serverMessage ?? `${host} rejected the submissions query.`,\n      `Fix the reported problem and re-run \"ekanos status\".`,\n    );\n  }\n\n  if (!response.ok) {\n    throw networkError(\n      `${host}/api/partner/submissions responded ${response.status}.`,\n      response.status >= 500\n        ? `The Fusion deployment returned a server error. Retry shortly; if ` +\n            `it persists, report it with the status code.`\n        : `Confirm the host is a Fusion deployment running a build that ` +\n            `includes the partner submissions route.`,\n    );\n  }\n\n  const data = (body.data ?? {}) as Record<string, unknown>;\n  const rows = Array.isArray(data.integrations) ? data.integrations : [];\n\n  const integrations = rows\n    .filter(\n      (row): row is Record<string, unknown> =>\n        typeof row === 'object' && row !== null,\n    )\n    .map((row) => ({\n      id: str(row.id) ?? '',\n      slug: str(row.slug) ?? '',\n      name: str(row.name),\n      createdAt: str(row.createdAt),\n      versions: (Array.isArray(row.versions) ? row.versions : [])\n        .filter(\n          (version): version is Record<string, unknown> =>\n            typeof version === 'object' && version !== null,\n        )\n        .map((version) => ({\n          id: str(version.id) ?? '',\n          version: str(version.version) ?? '',\n          state: str(version.state) ?? '',\n          archiveSha256: str(version.archiveSha256),\n          submittedAt: str(version.submittedAt),\n        })),\n    }));\n\n  return { status: 'ok', integrations };\n}\n\n/** Guard for the \"still unauthorized after one refresh\" terminal case. */\nexport function stillUnauthorized(host: string): never {\n  throw authRequiredError(\n    `The session for ${host} could not authorize the submission.`,\n    `Run \"ekanos login --host ${host}\" and retry.`,\n  );\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n\nfunction isRedirect(status: number): boolean {\n  return status >= 300 && status < 400;\n}\n\nfunction str(value: unknown): string | null {\n  return typeof value === 'string' && value.length > 0 ? value : null;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ekanos/integration-schema": "0.1.2",
+    "@ekanos/integration-schema": "0.1.3",
     "esbuild": "0.28.1"
   },
   "peerDependencies": {

package/templates/AGENTS.md.tmpl

@@ -0,0 +1,247 @@
+# __DISPLAY_NAME__ — an Ekanos integration
+
+This project is a **Fusion integration** built with `@ekanos/sdk`. This file is
+the authoring contract: everything an agent needs to build, test, and publish
+it without fetching external documentation. The `@ekanos/sdk` README (in
+`node_modules/@ekanos/sdk/README.md` after install) is the long-form version;
+where the two disagree, the README wins.
+
+## What an integration is
+
+One call to `defineIntegration()` in `src/integration.ts`, exported under the
+exact name `integration`. It validates at import time and returns a deep-frozen
+definition; the host re-parses the same object against the same schema when it
+registers the package, so a definition that loads locally is one the platform
+accepts.
+
+```ts
+import { defineIntegration } from '@ekanos/sdk/integration';
+
+export const integration = defineIntegration<MyStorage>({
+  slug: '__SLUG__',            // must match ekanos.json's "slug"
+  name: '__DISPLAY_NAME__',
+  description: '…',
+  version: '0.1.0',            // semver — bump it before every publish
+
+  capabilities: [ /* copy for the detail page */ ],
+  permissions: [ /* disclosure of what you read/write */ ],
+  components: { widgets: [ /* … */ ] },
+  tools: [ /* assistant-callable functions */ ],
+  webhooks: [ /* inbound deliveries */ ],
+  schedules: [ /* cron runs */ ],
+  storage: { account: { /* key → zod schema */ } },
+  egress: ['https://api.example.com'],
+});
+```
+
+Only `slug`, `name`, `description`, `version` are required. The schema is
+**strict everywhere**: an unrecognized key is a hard error, and host-assigned
+fields (`productId`, `kind`, trust tier, per-tool `effect`/`sensitivity`) are
+structurally un-settable — the closest you get is the `proposes` block.
+
+`ekanos.json` at the project root maps the slug to the entry module. The slug
+lives in both files; `ekanos validate` reports a finding if they disagree.
+
+## The capability context (`ctx`) — the ONLY platform surface
+
+Every server-side handler (tool `run`, webhook `handler`, schedule `handler`,
+`oauth.onTokens`) receives one `ctx` object, already scoped to
+`{account, integration}` before your code runs.
+
+**Hard rule: NEVER use global `fetch`, `process.env`, or `node:fs` in
+integration code.** There is no ambient platform access — network goes through
+`ctx.fetch` (refused synchronously unless the origin is in your `egress`
+list), credentials through `ctx.secrets`, state through `ctx.storage`. Code
+that reaches around `ctx` fails review and breaks under the mock.
+
+| Surface | What it is |
+|---|---|
+| `ctx.storage.account` | per-account state, schema-validated (`get`/`set`/`delete`, all async) |
+| `ctx.storage.user` | per-user state — **throws for machine actors** (workflows) |
+| `ctx.secrets` | `get(name)`, `names()`, `set(name, value)` — `set` writes the account tier only |
+| `ctx.fetch` | `fetch` constrained to your `egress` allowlist, redirects included |
+| `ctx.logger` | `debug`/`info`/`warn`/`error`, each `(contextObject, message)` — context FIRST |
+| `ctx.actor` | `{ kind: 'user', userId }` or `{ kind: 'machine', tokenId, createdBy }` |
+
+Read-only identity facts: `ctx.accountId`, `ctx.accountSlug`, `ctx.userId`
+(null for machine actors), `ctx.sourceId`, `ctx.integration`
+(`{ slug, productId }`), `ctx.timezone`.
+
+### Storage
+
+Declare every key up front with a zod schema; an undeclared key cannot be
+read, written, or deleted (`StorageValidationError` at runtime, a type error
+when the schema map is statically known).
+
+```ts
+import type { StorageSchemas } from '@ekanos/sdk';
+
+export const myStorage = {
+  account: {
+    'cache/latest': z.object({ fetchedAt: z.string(), body: z.unknown() }),
+    // Descriptor form opts a key in to the browser-readable storage route.
+    'settings/main': { schema: SettingsSchema, clientReadable: true },
+  },
+  user: { 'preferences/units': z.enum(['metric', 'imperial']) },
+} satisfies StorageSchemas;
+
+export type MyStorage = typeof myStorage;
+```
+
+Pass the type as the generic (`defineIntegration<MyStorage>`) and every
+handler's `ctx.storage` is typed to it.
+
+Key names are `[a-z0-9_-]+` with at most one `/` segment, and the first
+segment is the **data type**, drawn from a closed vocabulary. The canonical
+lists are exported from `@ekanos/integration-schema` as
+`ACCOUNT_STORAGE_DATA_TYPES` and `USER_STORAGE_DATA_TYPES` — import and check
+them rather than guessing; a key outside them fails `defineIntegration()`.
+`secret` is reserved (`RESERVED_STORAGE_DATA_TYPES`): credentials go through
+`ctx.secrets`, never `ctx.storage`.
+
+`get` returns `{ data, externalId, expiresAt, updatedAt } | null` (null for a
+missing key and for an entry past its `expiresAt`). Evolve a schema with a
+versioned key or a `z.union` — a stored value that no longer parses throws on
+read.
+
+### Secrets and the activation contract
+
+There is **no `secrets` block** in the definition. Secrets are *named*, not
+declared, and the activation form is where most names come from:
+
+**Every string-valued field of the `activationData` a user submits becomes
+readable as `ctx.secrets.get('<that exact field name>')`.** No prefixing, no
+transformation. Renaming a form field renames the secret and breaks every
+handler reading it, so keep each name in one exported constant
+(`src/config.ts`) imported by both the form and the handlers.
+
+Secret values go to the platform vault — **never** write a credential into
+`ctx.storage`, `configData`, logs, or a tool result. `ctx.secrets.set()` is
+for token rotation (OAuth refresh) and writes the account tier only; a name
+that resolves from an admin-issued tier throws `SecretAccessError`.
+
+The activation form itself is a client component declared at
+`components.activationForm`, built with `react-hook-form` + a zod resolver and
+rendered inside `BaseActivationForm` from `@ekanos/sdk/components` (pass the
+`inline` prop through). `useActivateIntegration()` from `@ekanos/sdk/hooks`
+posts the activation. Omit the form and the host renders a generic one.
+
+### Tools
+
+Assistant-callable functions. `parameters` is a narrow JSON-Schema slice: the
+top level accepts exactly `type: 'object'`, `properties`, `required`,
+`additionalProperties` — nothing else. Return a plain JSON value; return
+`{ error: '…' }` for an expected failure the model should explain; **throw**
+for a genuine fault. Tool names are `^[a-z][a-z0-9_]*$` and are namespaced by
+your slug at discovery.
+
+### Webhooks and schedules
+
+Declared with kebab-case ids. The transport validates `payloadSchema` before
+your handler runs and owns signature verification (`signature: { header,
+secretName }` or `'none'`) — never verify a signature in the handler.
+
+Webhook results: `{ status: 'processed' }` (done), `{ status: 'ignored' }`
+(valid but irrelevant — the sender must not retry), or **throw** (retryable
+failure). Schedule results: `{ status: 'completed' }` / `{ status: 'skipped' }`
+/ throw. Handlers must be safe under redelivery and under a manual "Run now"
+(`invocation.trigger` distinguishes them). Cron is 5-field numeric only — no
+names, no `@daily`, no seconds.
+
+## Widgets
+
+Dashboard widgets are client components (`'use client'`) declared at
+`components.widgets`. Widget ids are **globally** unique — always prefix with
+your slug (`__SLUG__-<name>`). `widgetState` (usually `'active'`), plus
+`layouts` per breakpoint, seed the dashboard placement.
+
+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.
+
+Build widget UI from `@ekanos/ui` — the published slice of the host design
+system. Available modules (import individually, e.g. `@ekanos/ui/button`):
+`alert`, `badge`, `button`, `card`, `dialog`, `dropdown-menu`, `form`, `icon`,
+`if`, `input`, `label`, `select`, `separator`, `skeleton`, `spinner`,
+`switch`, `textarea`, `tooltip`, `trans`, `utils` (the `cn()` helper),
+`ai-prompt-input`, plus the stylesheets `styles.css` / `tokens.css` /
+`theme.css` / `base.css`. Icons are Font Awesome glyph names via
+`@ekanos/ui/icon`; outside a host that loads Font Awesome they render as
+nothing — expected, not a bug.
+
+## Testing
+
+`@ekanos/sdk/testing` builds the same context production uses, in memory —
+same storage schema validation, same egress allowlist, same secret tiers:
+
+```ts
+import { createMockContext, invokeSchedule, invokeWebhook } from '@ekanos/sdk/testing';
+
+const ctx = createMockContext({
+  integration: { slug: '__SLUG__' },   // the options object is REQUIRED
+  storageSchemas: myStorage,
+  egress: integration.egress,
+  secrets: { account: { api_key: 'test-key' } },
+  fetchHandlers: [
+    { match: 'https://api.example.com', respond: () => Response.json({ ok: true }) },
+  ],
+});
+
+// Inspect what happened:
+ctx.fetchCalls;        // { url, init, denied }[]
+ctx.logs;              // { level, context, message }[]
+ctx.dumpStorage();     // { account, user }
+```
+
+`invokeWebhook(integration, '<webhook-id>', payload, options)` and
+`invokeSchedule(integration, '<schedule-id>', options)` run declared handlers
+with transport semantics (payload validated first, signature skip logged) and
+derive the context from the definition. Reuse one context across invocations
+via `options.context` to accumulate state.
+
+## The iteration loop (`npx ekanos <verb>`)
+
+Every verb speaks a JSON envelope on stdout with `--json` (auto-on when piped):
+`{ ok: true, data }` or `{ ok: false, error: { code, message, hint }, data? }`
+— exactly one JSON object per process, everything else on stderr. Every error
+carries an imperative `hint`; treat hints as remediation instructions.
+
+| Verb | Purpose |
+|---|---|
+| `ekanos validate` | Parse ekanos.json + load the definition + run every finding pass. Findings land in `data.findings`, each with severity and a hint |
+| `ekanos dev` | Scaffold `.ekanos/harness` and run the integration in a local Next dev shell (loopback by default) |
+| `ekanos test` | Run this project's test script through its package manager |
+| `ekanos login --host <url>` | Device-flow login to a Fusion deployment (stores the host for later verbs) |
+| `ekanos status` | Login state for the resolved host + this project's submissions |
+| `ekanos publish` | Validate, pack (whitelist: ekanos.json, package.json, README.md, src/), and submit. Refuses on any error-severity finding |
+
+Host resolution for `logout`/`whoami`/`status`/`publish`: `--host` flag →
+`EKANOS_HOST` → the `host` field in ekanos.json → the sole stored login. The
+first successful `publish` saves `host` and `source` into ekanos.json.
+`login` is the exception — it never reads ekanos.json for a host (`--host` →
+`EKANOS_HOST` → the sole stored login only), since it is the verb that
+creates credentials and a committed file must not be able to redirect it.
+
+Exit codes (frozen contract — branch on these): `0` ok, `1` internal, `2`
+usage, `3` validation, `4` auth required (run `ekanos login`), `5` forbidden,
+`6` not found, `7` invalid state (e.g. version already submitted — bump
+`package.json#version`), `8` network (retry, do NOT re-login), `9`
+precondition failed, `10` publish gate failed (fix `data.findings`).
+
+The loop: `ekanos dev` → edit → `npx tsc --noEmit` → `ekanos validate` →
+`ekanos test` → `ekanos publish`.
+
+## Verify your work
+
+Before claiming anything is done:
+
+1. `npm run typecheck` (or `npx tsc --noEmit`) — zero errors.
+2. `npx ekanos validate --json` — zero error-severity findings; fix by
+   following each finding's `hint` verbatim.
+3. `npm test` — green, and confirm vitest actually ran your test files (the
+   scaffolded vitest config's `server.deps.inline` block is REQUIRED for SDK
+   imports to load; without it vitest reports green over zero tests).
+4. `ekanos publish` re-runs the same findings pass and refuses on errors, so a
+   clean validate is what makes a publish land.

package/templates/CLAUDE.md.tmpl

@@ -0,0 +1,6 @@
+# __DISPLAY_NAME__
+
+This project is an Ekanos integration for the Fusion platform — read
+[AGENTS.md](./AGENTS.md) for the full authoring contract before changing code.
+The toolchain is `npx ekanos <verb>` (init, validate, dev, test, login,
+status, publish); every verb supports `--json` and a stable exit-code taxonomy.

package/templates/claude-skill.md.tmpl

@@ -0,0 +1,53 @@
+---
+name: ekanos
+description: Build, iterate on, validate, and publish this Fusion integration with the ekanos CLI. Use for any change to the integration definition, widgets, tools, webhooks, schedules, or tests, and for publishing to a Fusion host.
+---
+
+# Working on this Ekanos integration
+
+The authoring contract — what an integration is, the `ctx` API, storage/secret
+rules, widget and testing patterns — lives in **AGENTS.md** at the project
+root. Read it before writing integration code. The definition is one
+`defineIntegration()` in `src/integration.ts`, exported as `integration`.
+
+## The loop
+
+1. `npx ekanos dev` — local harness (only when you need to see UI).
+2. Edit code. Never use global `fetch`/`process.env`/`fs` in integration
+   code — everything goes through `ctx`.
+3. `npx tsc --noEmit` — types clean.
+4. `npx ekanos validate --json` — findings clean.
+5. `npm test` — green.
+6. `npx ekanos publish` — submits to the Fusion host (refuses while any
+   error-severity finding remains).
+
+## Reading CLI output
+
+Every verb emits ONE JSON envelope on stdout when piped (or with `--json`):
+`{ ok: true, data }` or `{ ok: false, error: { code, message, hint }, data? }`.
+Progress and prose go to stderr.
+
+**Every error and every validation finding carries a `hint` — treat hints as
+remediation instructions and follow them verbatim.** `ekanos validate` puts
+findings in `data.findings`; `ekanos publish` refuses with exit 10 and the
+same findings in `data.findings`.
+
+Exit codes to branch on: `0` ok · `2` usage · `3` validation · `4` run
+`ekanos login` · `7` version already submitted (bump `package.json#version`) ·
+`8` network (retry — do NOT re-login) · `9` precondition · `10` fix findings,
+publish again.
+
+## Hosts and sessions
+
+`ekanos login --host <url>` stores a session; after that, `logout`/`whoami`/
+`status`/`publish` resolve the host from `--host` → `EKANOS_HOST` →
+ekanos.json's `host` field → the sole stored login. `login` itself never reads
+ekanos.json for a host — only `--host`, `EKANOS_HOST`, or the sole stored
+login — since it is the verb that creates credentials. `ekanos status` shows
+who you are logged in as and what this project has submitted. The first
+successful publish saves `host` and `source` into ekanos.json.
+
+## Before claiming done
+
+Run steps 3-5 above and confirm all three are clean — a publish is only as
+good as the validate that precedes it.