@ekanos/cli 0.1.3 → 0.1.5

package/templates/AGENTS.md.tmpl

@@ -29,6 +29,7 @@ export const integration = defineIntegration<MyStorage>({
   tools: [ /* assistant-callable functions */ ],
   webhooks: [ /* inbound deliveries */ ],
   schedules: [ /* cron runs */ ],
+  onActivate: async (ctx) => { /* seed caches, sanity-check credentials */ },
   storage: { account: { /* key → zod schema */ } },
   egress: ['https://api.example.com'],
 });
@@ -45,7 +46,7 @@ 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
+`oauth.onTokens`, `onActivate`) 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
@@ -148,6 +149,37 @@ failure). Schedule results: `{ status: 'completed' }` / `{ status: 'skipped' }`
 (`invocation.trigger` distinguishes them). Cron is 5-field numeric only — no
 names, no `@daily`, no seconds.
 
+### `onActivate`
+
+Runs once after an activation is first persisted, and again after
+activationData is updated — **seed the cache in `onActivate`; the schedule
+keeps it fresh.** Without it, a cache-backed widget is empty until the first
+schedule tick. v1 errors are non-fatal: a throw is logged as a warning and the
+activation stays connected, so this is for cache seeding and eager
+validation, never a connect gate. Seed BEST-EFFORT — swallow what you can
+name, log loudly what you can't: catch the upstream error classes you can
+reason about (timeouts, 5xx, provider errors) and warn; log anything
+unrecognized as an error and return, so a genuine bug stays visible in logs
+without telling a user their brand-new connection failed. Reserve the throw
+for misconfiguration the user can actually fix. Treat onActivate as an
+OPTIMIZATION, never a correctness dependency: the schedule remains the
+freshness guarantee, and a config fingerprint keeps the stale window safe
+whether or not the hook fires.
+
+Troubleshooting `ekanos dev`: adding/removing/re-adding handler modules can
+leave the harness's Turbopack cache resolving a deleted path ("Module not
+found" for a file that exists). Clear it with `rm -rf .ekanos/harness/.next`
+and restart.
+
+A cache invalidated only by age still serves the *previous* activation's data
+for a while even with `onActivate` wired up. Close that gap with a
+fingerprint: store a hash of the activation fields a cached value's **values**
+depended on (not just the ones that pick which data to fetch — currency, units
+and locale change the numbers without changing the cache key) alongside the
+value, and treat a mismatch or an absent fingerprint on read as a miss.
+Declare that field `.optional()` on the storage schema, or every pre-existing
+row throws `StorageValidationError` on read.
+
 ## Widgets
 
 Dashboard widgets are client components (`'use client'`) declared at
@@ -168,8 +200,17 @@ system. Available modules (import individually, e.g. `@ekanos/ui/button`):
 `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.
+`@ekanos/ui/icon`. This generated shell loads Font Awesome **Free**
+(`@fortawesome/fontawesome-free`) — a much smaller set than the Pro kit Fusion
+itself runs — so a name that's Pro-only (or just mistyped) renders a
+circle-question disc instead of vanishing, and dev builds `console.warn` once
+per name to catch it before a screenshot review does. `fa-light` / `fa-duotone`
+/ `fa-thin` are rewritten to `fa-solid`, the one weight Free ships, so author
+`fa-light` anyway — it degrades harmlessly today, and the intended weight
+survives if this host ever loads Pro instead. Verify a glyph name against the
+Free set (`pnpm --filter @ekanos/ui check:fa-free-names`, or
+https://fontawesome.com/search?o=r&s=solid,regular,brands) before relying on
+it looking like anything in particular.
 
 ## Testing
 
@@ -215,20 +256,40 @@ carries an imperative `hint`; treat hints as remediation instructions.
 | `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.
+| `ekanos sources` | List every Fusion source you hold a developer/admin seat on, marking this project's current target |
+| `ekanos use <source-slug>` | Set this project's publish target — refuses (`forbidden`) a slug you hold no seat on |
+| `ekanos publish` | Validate, pack (whitelist: ekanos.json, package.json, README.md, src/), verify the target, and submit. Refuses on any error-severity finding |
+
+Host resolution for `logout`/`whoami`/`status`/`sources`/`use`/`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.
+
+### Publish targeting — do not skip this if you hold more than one seat
+
+`publish` verifies its target BEFORE packing or submitting anything: it fetches
+your seat list and refuses (`forbidden`, exit 5) a source you hold no seat on,
+naming your actual seats in the hint. If the target came from ekanos.json
+(not `--source` this run) and you hold more than one seat, a scripted/agent
+run (JSON mode, which is what running under an agent means) is refused with
+`validation` (exit 3) and the seat list **unless `--yes` is passed** — publish
+never guesses and never prompts in this mode.
+
+**As an agent: never pass `--yes` to paper over that ambiguity.** Run
+`ekanos sources` first and pass `--source <slug>` explicitly, or run
+`ekanos use <slug>` once to set the project's target deliberately. `--yes` is
+for a human who already confirmed the target, or a pipeline pinned to one
+source — not a way to silence the check when you are unsure.
 
 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`).
+usage, `3` validation (also: ambiguous publish target — pass `--source` or
+`--yes`), `4` auth required (run `ekanos login`), `5` forbidden (also: no seat
+on the target source — check `ekanos sources`), `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`.

package/templates/claude-skill.md.tmpl

@@ -18,8 +18,14 @@ root. Read it before writing integration code. The definition is one
 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).
+6. **Before publishing, know your target.** If you hold more than one
+   developer seat, run `npx ekanos sources --json` and pass the intended
+   `--source <slug>` explicitly to `publish`. Never pass `--yes` to get past
+   an ambiguous-target error you have not actually resolved — `--yes` is
+   consent to a target you already chose, not a way to silence the check.
+7. `npx ekanos publish --source <slug>` — submits to the Fusion host (refuses
+   while any error-severity finding remains, and refuses `forbidden` if you
+   hold no seat on that source).
 
 ## Reading CLI output
 
@@ -32,22 +38,37 @@ 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`) ·
+Exit codes to branch on: `0` ok · `2` usage · `3` validation (also: ambiguous
+publish target — pass `--source` or `--yes`, never guess) · `4` run
+`ekanos login` · `5` forbidden (also: no seat on the target source — run
+`ekanos sources`) · `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.
+`status`/`sources`/`use`/`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.
+
+## Publish targets, when you hold more than one seat
+
+`ekanos sources` lists every source you hold a seat on; `ekanos use <slug>`
+sets this project's saved target (seat-checked — refuses a slug you don't
+hold). `publish` verifies its resolved target against your seats before
+packing anything, and — running as an agent, which is JSON/non-interactive
+mode — never prompts: an ambiguous implicit target (ekanos.json, more than one
+seat) is refused with the seat list unless you pass `--yes`. **Always resolve
+the ambiguity yourself** (pick the right `--source`) rather than reaching for
+`--yes` on a target you have not verified.
 
 ## 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.
+good as the validate that precedes it. If publishing, confirm you named the
+right `--source` rather than relying on `--yes`.