@ekanos/cli 0.1.4 → 0.1.6

package/dist/toolchain-resolve.js

@@ -0,0 +1,100 @@
+import { TOOLCHAIN_PACKAGES, } from './toolchain.js';
+import { fetchToolchainReport } from './toolchain-api.js';
+/**
+ * The single place that answers "what should this toolchain be at?" — shared
+ * by `ekanos upgrade` (which installs the answer) and the proactive update
+ * notice (which only reports it). Both need the exact same coherent target,
+ * so there is exactly one resolution path, tried in this order:
+ *
+ *  1. `GET /api/partner/toolchain` on the resolved host, when both a host and
+ *     a session are available. Whatever the host returns is trusted as
+ *     already-coherent — it is the operator's own recommendation.
+ *  2. The npm registry's `dist-tags.latest` for all five packages, with an
+ *     explicit COHERENCE check before ever calling it a "target": the
+ *     `@ekanos/sdk` / `@ekanos/ui` / `@ekanos/integration-schema` trio must
+ *     resolve to one identical version, and the `@ekanos/sdk` release at that
+ *     version must declare the exact same `@ekanos/integration-schema`
+ *     dependency. A multi-package publish is not atomic — this repo hit that
+ *     exact window mid-publish — so assembling "latest of each, independently"
+ *     can produce a set that literally cannot install together. Refusing is
+ *     the only safe response to a set caught in that state; the failure is
+ *     obvious and self-resolves the moment the publish finishes.
+ */
+const REGISTRY_BASE = 'https://registry.npmjs.org';
+/** npm registry package URLs encode the scope's `/` but not its `@`. */
+function registryPackageUrl(pkg, version) {
+    const encoded = encodeURIComponent(pkg).replace('%40', '@');
+    return version
+        ? `${REGISTRY_BASE}/${encoded}/${encodeURIComponent(version)}`
+        : `${REGISTRY_BASE}/${encoded}`;
+}
+export async function resolveToolchainTarget(params) {
+    if (params.host && params.session) {
+        const hostResult = await fetchToolchainReport(params.host, params.session.accessToken);
+        if (hostResult.status === 'ok') {
+            return {
+                status: 'ok',
+                source: 'host',
+                target: hostResult.report.current,
+                minimum: hostResult.report.minimum,
+                notes: hostResult.report.notes,
+            };
+        }
+        // 404 / 501 / network failure / malformed body: fall through to npm.
+    }
+    return resolveFromNpmRegistry(params.timeoutMs);
+}
+async function resolveFromNpmRegistry(timeoutMs) {
+    var _a;
+    const entries = Object.entries(TOOLCHAIN_PACKAGES);
+    const latests = await Promise.all(entries.map(async ([key, pkg]) => {
+        var _a;
+        const body = await fetchRegistryJson(registryPackageUrl(pkg), timeoutMs);
+        const latest = (_a = body === null || body === void 0 ? void 0 : body['dist-tags']) === null || _a === void 0 ? void 0 : _a.latest;
+        return [key, typeof latest === 'string' ? latest : null];
+    }));
+    const versions = Object.fromEntries(latests);
+    if (Object.values(versions).some((version) => version === null)) {
+        return { status: 'unavailable' };
+    }
+    const target = versions;
+    const trio = [target.sdk, target.ui, target.integrationSchema];
+    if (new Set(trio).size !== 1) {
+        return {
+            status: 'incoherent',
+            detail: `the npm registry reports mismatched versions for the sdk/ui/schema ` +
+                `trio: @ekanos/sdk@${target.sdk}, @ekanos/ui@${target.ui}, ` +
+                `@ekanos/integration-schema@${target.integrationSchema}. This is ` +
+                `usually a multi-package publish still in flight — retry shortly.`,
+        };
+    }
+    const sdkManifest = await fetchRegistryJson(registryPackageUrl(TOOLCHAIN_PACKAGES.sdk, target.sdk), timeoutMs);
+    const sdkPinnedSchema = (_a = sdkManifest === null || sdkManifest === void 0 ? void 0 : sdkManifest.dependencies) === null || _a === void 0 ? void 0 : _a['@ekanos/integration-schema'];
+    if (typeof sdkPinnedSchema !== 'string' ||
+        sdkPinnedSchema !== target.integrationSchema) {
+        return {
+            status: 'incoherent',
+            detail: `@ekanos/sdk@${target.sdk} on npm depends on ` +
+                `@ekanos/integration-schema@${String(sdkPinnedSchema)}, which does ` +
+                `not match the published @ekanos/integration-schema@` +
+                `${target.integrationSchema}. This is usually a multi-package ` +
+                `publish still in flight — retry shortly.`,
+        };
+    }
+    return { status: 'ok', source: 'npm', target };
+}
+async function fetchRegistryJson(url, timeoutMs) {
+    try {
+        const response = await fetch(url, {
+            headers: { accept: 'application/json' },
+            signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined,
+        });
+        if (!response.ok)
+            return null;
+        return await response.json();
+    }
+    catch (_a) {
+        return null;
+    }
+}
+//# sourceMappingURL=toolchain-resolve.js.map

package/dist/toolchain-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain-resolve.js","sourceRoot":"","sources":["../src/toolchain-resolve.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  TOOLCHAIN_PACKAGES,\n  type ToolchainKey,\n  type ToolchainNote,\n  type ToolchainVersions,\n} from './toolchain';\nimport { fetchToolchainReport } from './toolchain-api';\n\n/**\n * The single place that answers \"what should this toolchain be at?\" — shared\n * by `ekanos upgrade` (which installs the answer) and the proactive update\n * notice (which only reports it). Both need the exact same coherent target,\n * so there is exactly one resolution path, tried in this order:\n *\n *  1. `GET /api/partner/toolchain` on the resolved host, when both a host and\n *     a session are available. Whatever the host returns is trusted as\n *     already-coherent — it is the operator's own recommendation.\n *  2. The npm registry's `dist-tags.latest` for all five packages, with an\n *     explicit COHERENCE check before ever calling it a \"target\": the\n *     `@ekanos/sdk` / `@ekanos/ui` / `@ekanos/integration-schema` trio must\n *     resolve to one identical version, and the `@ekanos/sdk` release at that\n *     version must declare the exact same `@ekanos/integration-schema`\n *     dependency. A multi-package publish is not atomic — this repo hit that\n *     exact window mid-publish — so assembling \"latest of each, independently\"\n *     can produce a set that literally cannot install together. Refusing is\n *     the only safe response to a set caught in that state; the failure is\n *     obvious and self-resolves the moment the publish finishes.\n */\n\nconst REGISTRY_BASE = 'https://registry.npmjs.org';\n\n/** npm registry package URLs encode the scope's `/` but not its `@`. */\nfunction registryPackageUrl(pkg: string, version?: string): string {\n  const encoded = encodeURIComponent(pkg).replace('%40', '@');\n  return version\n    ? `${REGISTRY_BASE}/${encoded}/${encodeURIComponent(version)}`\n    : `${REGISTRY_BASE}/${encoded}`;\n}\n\nexport type ToolchainResolution =\n  | {\n      status: 'ok';\n      source: 'host';\n      target: ToolchainVersions;\n      minimum: ToolchainVersions;\n      notes: ToolchainNote[];\n    }\n  | { status: 'ok'; source: 'npm'; target: ToolchainVersions }\n  | { status: 'incoherent'; detail: string }\n  | { status: 'unavailable' };\n\nexport interface ResolveToolchainParams {\n  host?: string;\n  session?: { accessToken: string } | null;\n  /** Per-request timeout for the underlying fetches. */\n  timeoutMs?: number;\n}\n\nexport async function resolveToolchainTarget(\n  params: ResolveToolchainParams,\n): Promise<ToolchainResolution> {\n  if (params.host && params.session) {\n    const hostResult = await fetchToolchainReport(\n      params.host,\n      params.session.accessToken,\n    );\n\n    if (hostResult.status === 'ok') {\n      return {\n        status: 'ok',\n        source: 'host',\n        target: hostResult.report.current,\n        minimum: hostResult.report.minimum,\n        notes: hostResult.report.notes,\n      };\n    }\n\n    // 404 / 501 / network failure / malformed body: fall through to npm.\n  }\n\n  return resolveFromNpmRegistry(params.timeoutMs);\n}\n\nasync function resolveFromNpmRegistry(\n  timeoutMs?: number,\n): Promise<ToolchainResolution> {\n  const entries = Object.entries(TOOLCHAIN_PACKAGES) as [\n    ToolchainKey,\n    string,\n  ][];\n\n  const latests = await Promise.all(\n    entries.map(async ([key, pkg]) => {\n      const body = await fetchRegistryJson(registryPackageUrl(pkg), timeoutMs);\n      const latest = (body as { 'dist-tags'?: { latest?: unknown } } | null)?.[\n        'dist-tags'\n      ]?.latest;\n      return [key, typeof latest === 'string' ? latest : null] as const;\n    }),\n  );\n\n  const versions = Object.fromEntries(latests) as Record<\n    ToolchainKey,\n    string | null\n  >;\n\n  if (Object.values(versions).some((version) => version === null)) {\n    return { status: 'unavailable' };\n  }\n\n  const target = versions as ToolchainVersions;\n\n  const trio = [target.sdk, target.ui, target.integrationSchema];\n  if (new Set(trio).size !== 1) {\n    return {\n      status: 'incoherent',\n      detail:\n        `the npm registry reports mismatched versions for the sdk/ui/schema ` +\n        `trio: @ekanos/sdk@${target.sdk}, @ekanos/ui@${target.ui}, ` +\n        `@ekanos/integration-schema@${target.integrationSchema}. This is ` +\n        `usually a multi-package publish still in flight — retry shortly.`,\n    };\n  }\n\n  const sdkManifest = await fetchRegistryJson(\n    registryPackageUrl(TOOLCHAIN_PACKAGES.sdk, target.sdk),\n    timeoutMs,\n  );\n  const sdkPinnedSchema = (\n    sdkManifest as { dependencies?: Record<string, unknown> } | null\n  )?.dependencies?.['@ekanos/integration-schema'];\n\n  if (\n    typeof sdkPinnedSchema !== 'string' ||\n    sdkPinnedSchema !== target.integrationSchema\n  ) {\n    return {\n      status: 'incoherent',\n      detail:\n        `@ekanos/sdk@${target.sdk} on npm depends on ` +\n        `@ekanos/integration-schema@${String(sdkPinnedSchema)}, which does ` +\n        `not match the published @ekanos/integration-schema@` +\n        `${target.integrationSchema}. This is usually a multi-package ` +\n        `publish still in flight — retry shortly.`,\n    };\n  }\n\n  return { status: 'ok', source: 'npm', target };\n}\n\nasync function fetchRegistryJson(\n  url: string,\n  timeoutMs?: number,\n): Promise<unknown | null> {\n  try {\n    const response = await fetch(url, {\n      headers: { accept: 'application/json' },\n      signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined,\n    });\n    if (!response.ok) return null;\n    return await response.json();\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/toolchain.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The five packages that make up "the toolchain" — the CLI plus the four
+ * packages a partner's project itself installs. `ekanos upgrade` and the
+ * proactive update notice both reason about this exact set, from two
+ * different angles: upgrade moves a PROJECT to a coherent target, the notice
+ * tells a partner the CLI itself is behind. One shared vocabulary so the two
+ * features cannot drift apart on what "the toolchain" even means.
+ */
+export declare const TOOLCHAIN_PACKAGES: {
+    readonly cli: "@ekanos/cli";
+    readonly sdk: "@ekanos/sdk";
+    readonly ui: "@ekanos/ui";
+    readonly integrationSchema: "@ekanos/integration-schema";
+    readonly harness: "@ekanos/harness";
+};
+export type ToolchainKey = keyof typeof TOOLCHAIN_PACKAGES;
+export type ToolchainVersions = Record<ToolchainKey, string>;
+export interface ToolchainNote {
+    level: 'warn' | 'info';
+    message: string;
+}

package/dist/toolchain.js

@@ -0,0 +1,16 @@
+/**
+ * The five packages that make up "the toolchain" — the CLI plus the four
+ * packages a partner's project itself installs. `ekanos upgrade` and the
+ * proactive update notice both reason about this exact set, from two
+ * different angles: upgrade moves a PROJECT to a coherent target, the notice
+ * tells a partner the CLI itself is behind. One shared vocabulary so the two
+ * features cannot drift apart on what "the toolchain" even means.
+ */
+export const TOOLCHAIN_PACKAGES = {
+    cli: '@ekanos/cli',
+    sdk: '@ekanos/sdk',
+    ui: '@ekanos/ui',
+    integrationSchema: '@ekanos/integration-schema',
+    harness: '@ekanos/harness',
+};
+//# sourceMappingURL=toolchain.js.map

package/dist/toolchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain.js","sourceRoot":"","sources":["../src/toolchain.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,aAAa;IAClB,EAAE,EAAE,YAAY;IAChB,iBAAiB,EAAE,4BAA4B;IAC/C,OAAO,EAAE,iBAAiB;CAClB,CAAC","sourcesContent":["/**\n * The five packages that make up \"the toolchain\" — the CLI plus the four\n * packages a partner's project itself installs. `ekanos upgrade` and the\n * proactive update notice both reason about this exact set, from two\n * different angles: upgrade moves a PROJECT to a coherent target, the notice\n * tells a partner the CLI itself is behind. One shared vocabulary so the two\n * features cannot drift apart on what \"the toolchain\" even means.\n */\nexport const TOOLCHAIN_PACKAGES = {\n  cli: '@ekanos/cli',\n  sdk: '@ekanos/sdk',\n  ui: '@ekanos/ui',\n  integrationSchema: '@ekanos/integration-schema',\n  harness: '@ekanos/harness',\n} as const;\n\nexport type ToolchainKey = keyof typeof TOOLCHAIN_PACKAGES;\n\nexport type ToolchainVersions = Record<ToolchainKey, string>;\n\nexport interface ToolchainNote {\n  level: 'warn' | 'info';\n  message: string;\n}\n"]}

package/dist/update-notice.d.ts

@@ -0,0 +1,32 @@
+import type { CliContext } from './context.js';
+import type { ToolchainVersions } from './toolchain.js';
+export interface ToolchainNoticeData {
+    status: 'behind' | 'unsupported';
+    current: {
+        cli: string;
+    };
+    target: ToolchainVersions;
+    upgradeCommand: 'ekanos upgrade';
+}
+export interface CheckForUpdateParams {
+    env: Record<string, string | undefined>;
+    /** An already-resolved Fusion host/session, when the caller has one handy. */
+    host?: string;
+    session?: {
+        accessToken: string;
+    } | null;
+}
+/**
+ * Resolve whether this CLI is behind, respecting the 24h cache and the hard
+ * `EKANOS_NO_UPDATE_CHECK` opt-out. Returns null whenever there is nothing to
+ * say — current, unresolvable, or any failure along the way.
+ */
+export declare function checkForUpdate(params: CheckForUpdateParams): Promise<ToolchainNoticeData | null>;
+/**
+ * Surface a notice, if any. Human mode gets one stderr line; every mode gets
+ * the `claude-code-hint` stderr line so an agent parsing stderr for that
+ * marker sees it regardless of `--json`. NEVER writes to stdout — the JSON
+ * envelope's caller is responsible for embedding `notice` under a `toolchain`
+ * key in its own `data`, per the envelope docs in `context.ts`.
+ */
+export declare function announceUpdate(ctx: CliContext, notice: ToolchainNoticeData | null): void;

package/dist/update-notice.js

@@ -0,0 +1,180 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CredentialStore, resolveEkanosHome } from './auth/credential-store.js';
+import { cliVersion, compareVersions } from './compatibility.js';
+import { resolveToolchainTarget } from './toolchain-resolve.js';
+/**
+ * The proactive, NEVER-mutating "your CLI is behind" notice. Runs on
+ * `validate`, `dev`, `publish` and `status` — the verbs a partner (or an
+ * agent acting for one) runs constantly — so staleness is discovered on the
+ * next ordinary command instead of only when something breaks.
+ *
+ * The one rule that governs every line of this file: this check must be
+ * INVISIBLE on failure. A partner offline, a flaky registry, a host that
+ * predates this endpoint — none of that may add meaningful latency, change a
+ * verb's exit code, or so much as touch the JSON envelope's `ok` field.
+ * Every failure path below resolves to `null` ("say nothing"), never a throw.
+ */
+const CACHE_FILENAME = 'update-check.json';
+const CACHE_DIR_MODE = 0o700;
+const CACHE_FILE_MODE = 0o600;
+const TTL_MS = 24 * 60 * 60 * 1000;
+/** The hard ceiling on this check's total network time, whatever else happens. */
+const DEADLINE_MS = 1500;
+function cachePath(env) {
+    return path.join(resolveEkanosHome(env), '.ekanos', CACHE_FILENAME);
+}
+function readCache(env) {
+    try {
+        const raw = fs.readFileSync(cachePath(env), 'utf8');
+        const parsed = JSON.parse(raw);
+        return isCacheFile(parsed) ? parsed : null;
+    }
+    catch (_a) {
+        // Missing, unreadable, or corrupt — all read as "no cache", never an
+        // error. This check is a courtesy, not a source of truth.
+        return null;
+    }
+}
+function writeCache(env, file) {
+    const target = cachePath(env);
+    try {
+        fs.mkdirSync(path.dirname(target), {
+            recursive: true,
+            mode: CACHE_DIR_MODE,
+        });
+        const tmp = `${target}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(file), { mode: CACHE_FILE_MODE });
+        fs.renameSync(tmp, target);
+    }
+    catch (_a) {
+        // Best-effort. The next run simply re-checks — this is a cache, not a
+        // durable record.
+    }
+}
+function isCacheFile(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.checkedAt === 'number' &&
+        typeof candidate.target === 'object' &&
+        candidate.target !== null &&
+        (candidate.source === 'host' || candidate.source === 'npm'));
+}
+/**
+ * The one host/session this check will ever try, resolved WITHOUT any of the
+ * throwing machinery in `auth/session.ts` — `resolveHost` is built to demand
+ * an answer (a usage error naming the ambiguity) because a real command needs
+ * one; this check needs an answer only if one is obvious, and silence
+ * otherwise. Exactly one stored host is "obvious"; zero or several are not,
+ * and this never prompts or guesses to resolve that ambiguity — it just
+ * falls back to the npm registry, same as no session at all.
+ */
+function bestEffortHostSession(env) {
+    try {
+        const store = new CredentialStore({ home: resolveEkanosHome(env) });
+        const hosts = store.hosts();
+        if (hosts.length !== 1)
+            return null;
+        const session = store.read(hosts[0]);
+        return session ? { host: hosts[0], session } : null;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function withDeadline(promise, ms) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve(null);
+            }
+        }, ms);
+        // A rejection is a failure like any other here — resolve to null rather
+        // than letting it become an unhandled rejection.
+        promise.then((value) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(value);
+            }
+        }, () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(null);
+            }
+        });
+    });
+}
+/**
+ * Resolve whether this CLI is behind, respecting the 24h cache and the hard
+ * `EKANOS_NO_UPDATE_CHECK` opt-out. Returns null whenever there is nothing to
+ * say — current, unresolvable, or any failure along the way.
+ */
+export async function checkForUpdate(params) {
+    if (params.env.EKANOS_NO_UPDATE_CHECK)
+        return null;
+    const cached = readCache(params.env);
+    const now = Date.now();
+    let target;
+    let minimum;
+    if (cached && now - cached.checkedAt < TTL_MS) {
+        target = cached.target;
+        minimum = cached.minimum;
+    }
+    else {
+        const auth = params.host && params.session
+            ? { host: params.host, session: params.session }
+            : bestEffortHostSession(params.env);
+        const resolution = await withDeadline(resolveToolchainTarget({
+            host: auth === null || auth === void 0 ? void 0 : auth.host,
+            session: auth === null || auth === void 0 ? void 0 : auth.session,
+            timeoutMs: DEADLINE_MS,
+        }), DEADLINE_MS);
+        if (!resolution || resolution.status !== 'ok')
+            return null;
+        target = resolution.target;
+        minimum = resolution.source === 'host' ? resolution.minimum : undefined;
+        writeCache(params.env, {
+            checkedAt: now,
+            target,
+            minimum,
+            source: resolution.source,
+        });
+    }
+    const current = cliVersion();
+    if (compareVersions(current, target.cli) >= 0)
+        return null;
+    const status = minimum && compareVersions(current, minimum.cli) < 0
+        ? 'unsupported'
+        : 'behind';
+    return {
+        status,
+        current: { cli: current },
+        target,
+        upgradeCommand: 'ekanos upgrade',
+    };
+}
+/**
+ * Surface a notice, if any. Human mode gets one stderr line; every mode gets
+ * the `claude-code-hint` stderr line so an agent parsing stderr for that
+ * marker sees it regardless of `--json`. NEVER writes to stdout — the JSON
+ * envelope's caller is responsible for embedding `notice` under a `toolchain`
+ * key in its own `data`, per the envelope docs in `context.ts`.
+ */
+export function announceUpdate(ctx, notice) {
+    if (!notice)
+        return;
+    if (!ctx.jsonMode) {
+        ctx.warn(notice.status === 'unsupported'
+            ? `ekanos: @ekanos/cli ${notice.current.cli} is below the version ` +
+                `this host requires (${notice.target.cli}). Run "ekanos upgrade".`
+            : `ekanos: a newer @ekanos/cli is available (${notice.current.cli} ` +
+                `→ ${notice.target.cli}). Run "ekanos upgrade".`);
+    }
+    ctx.emitClaudeCodeHint({ tool: 'ekanos', toolchain: notice });
+}
+//# sourceMappingURL=update-notice.js.map

package/dist/update-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-notice.js","sourceRoot":"","sources":["../src/update-notice.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { CredentialStore, resolveEkanosHome } from './auth/credential-store';\nimport { cliVersion, compareVersions } from './compatibility';\nimport type { CliContext } from './context';\nimport type { ToolchainVersions } from './toolchain';\nimport { resolveToolchainTarget } from './toolchain-resolve';\n\n/**\n * The proactive, NEVER-mutating \"your CLI is behind\" notice. Runs on\n * `validate`, `dev`, `publish` and `status` — the verbs a partner (or an\n * agent acting for one) runs constantly — so staleness is discovered on the\n * next ordinary command instead of only when something breaks.\n *\n * The one rule that governs every line of this file: this check must be\n * INVISIBLE on failure. A partner offline, a flaky registry, a host that\n * predates this endpoint — none of that may add meaningful latency, change a\n * verb's exit code, or so much as touch the JSON envelope's `ok` field.\n * Every failure path below resolves to `null` (\"say nothing\"), never a throw.\n */\n\nconst CACHE_FILENAME = 'update-check.json';\nconst CACHE_DIR_MODE = 0o700;\nconst CACHE_FILE_MODE = 0o600;\nconst TTL_MS = 24 * 60 * 60 * 1000;\n/** The hard ceiling on this check's total network time, whatever else happens. */\nconst DEADLINE_MS = 1500;\n\nexport interface ToolchainNoticeData {\n  status: 'behind' | 'unsupported';\n  current: { cli: string };\n  target: ToolchainVersions;\n  upgradeCommand: 'ekanos upgrade';\n}\n\ninterface CacheFile {\n  checkedAt: number;\n  target: ToolchainVersions;\n  minimum?: ToolchainVersions;\n  source: 'host' | 'npm';\n}\n\nfunction cachePath(env: Record<string, string | undefined>): string {\n  return path.join(resolveEkanosHome(env), '.ekanos', CACHE_FILENAME);\n}\n\nfunction readCache(env: Record<string, string | undefined>): CacheFile | null {\n  try {\n    const raw = fs.readFileSync(cachePath(env), 'utf8');\n    const parsed: unknown = JSON.parse(raw);\n    return isCacheFile(parsed) ? parsed : null;\n  } catch {\n    // Missing, unreadable, or corrupt — all read as \"no cache\", never an\n    // error. This check is a courtesy, not a source of truth.\n    return null;\n  }\n}\n\nfunction writeCache(\n  env: Record<string, string | undefined>,\n  file: CacheFile,\n): void {\n  const target = cachePath(env);\n  try {\n    fs.mkdirSync(path.dirname(target), {\n      recursive: true,\n      mode: CACHE_DIR_MODE,\n    });\n    const tmp = `${target}.${process.pid}.tmp`;\n    fs.writeFileSync(tmp, JSON.stringify(file), { mode: CACHE_FILE_MODE });\n    fs.renameSync(tmp, target);\n  } catch {\n    // Best-effort. The next run simply re-checks — this is a cache, not a\n    // durable record.\n  }\n}\n\nfunction isCacheFile(value: unknown): value is CacheFile {\n  if (typeof value !== 'object' || value === null) return false;\n  const candidate = value as Partial<CacheFile>;\n  return (\n    typeof candidate.checkedAt === 'number' &&\n    typeof candidate.target === 'object' &&\n    candidate.target !== null &&\n    (candidate.source === 'host' || candidate.source === 'npm')\n  );\n}\n\n/**\n * The one host/session this check will ever try, resolved WITHOUT any of the\n * throwing machinery in `auth/session.ts` — `resolveHost` is built to demand\n * an answer (a usage error naming the ambiguity) because a real command needs\n * one; this check needs an answer only if one is obvious, and silence\n * otherwise. Exactly one stored host is \"obvious\"; zero or several are not,\n * and this never prompts or guesses to resolve that ambiguity — it just\n * falls back to the npm registry, same as no session at all.\n */\nfunction bestEffortHostSession(\n  env: Record<string, string | undefined>,\n): { host: string; session: { accessToken: string } } | null {\n  try {\n    const store = new CredentialStore({ home: resolveEkanosHome(env) });\n    const hosts = store.hosts();\n    if (hosts.length !== 1) return null;\n    const session = store.read(hosts[0]!);\n    return session ? { host: hosts[0]!, session } : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction withDeadline<T>(promise: Promise<T>, ms: number): Promise<T | null> {\n  return new Promise((resolve) => {\n    let settled = false;\n    const timer = setTimeout(() => {\n      if (!settled) {\n        settled = true;\n        resolve(null);\n      }\n    }, ms);\n    // A rejection is a failure like any other here — resolve to null rather\n    // than letting it become an unhandled rejection.\n    promise.then(\n      (value) => {\n        if (!settled) {\n          settled = true;\n          clearTimeout(timer);\n          resolve(value);\n        }\n      },\n      () => {\n        if (!settled) {\n          settled = true;\n          clearTimeout(timer);\n          resolve(null);\n        }\n      },\n    );\n  });\n}\n\nexport interface CheckForUpdateParams {\n  env: Record<string, string | undefined>;\n  /** An already-resolved Fusion host/session, when the caller has one handy. */\n  host?: string;\n  session?: { accessToken: string } | null;\n}\n\n/**\n * Resolve whether this CLI is behind, respecting the 24h cache and the hard\n * `EKANOS_NO_UPDATE_CHECK` opt-out. Returns null whenever there is nothing to\n * say — current, unresolvable, or any failure along the way.\n */\nexport async function checkForUpdate(\n  params: CheckForUpdateParams,\n): Promise<ToolchainNoticeData | null> {\n  if (params.env.EKANOS_NO_UPDATE_CHECK) return null;\n\n  const cached = readCache(params.env);\n  const now = Date.now();\n\n  let target: ToolchainVersions;\n  let minimum: ToolchainVersions | undefined;\n\n  if (cached && now - cached.checkedAt < TTL_MS) {\n    target = cached.target;\n    minimum = cached.minimum;\n  } else {\n    const auth =\n      params.host && params.session\n        ? { host: params.host, session: params.session }\n        : bestEffortHostSession(params.env);\n\n    const resolution = await withDeadline(\n      resolveToolchainTarget({\n        host: auth?.host,\n        session: auth?.session,\n        timeoutMs: DEADLINE_MS,\n      }),\n      DEADLINE_MS,\n    );\n\n    if (!resolution || resolution.status !== 'ok') return null;\n\n    target = resolution.target;\n    minimum = resolution.source === 'host' ? resolution.minimum : undefined;\n\n    writeCache(params.env, {\n      checkedAt: now,\n      target,\n      minimum,\n      source: resolution.source,\n    });\n  }\n\n  const current = cliVersion();\n  if (compareVersions(current, target.cli) >= 0) return null;\n\n  const status =\n    minimum && compareVersions(current, minimum.cli) < 0\n      ? 'unsupported'\n      : 'behind';\n\n  return {\n    status,\n    current: { cli: current },\n    target,\n    upgradeCommand: 'ekanos upgrade',\n  };\n}\n\n/**\n * Surface a notice, if any. Human mode gets one stderr line; every mode gets\n * the `claude-code-hint` stderr line so an agent parsing stderr for that\n * marker sees it regardless of `--json`. NEVER writes to stdout — the JSON\n * envelope's caller is responsible for embedding `notice` under a `toolchain`\n * key in its own `data`, per the envelope docs in `context.ts`.\n */\nexport function announceUpdate(\n  ctx: CliContext,\n  notice: ToolchainNoticeData | null,\n): void {\n  if (!notice) return;\n\n  if (!ctx.jsonMode) {\n    ctx.warn(\n      notice.status === 'unsupported'\n        ? `ekanos: @ekanos/cli ${notice.current.cli} is below the version ` +\n            `this host requires (${notice.target.cli}). Run \"ekanos upgrade\".`\n        : `ekanos: a newer @ekanos/cli is available (${notice.current.cli} ` +\n            `→ ${notice.target.cli}). Run \"ekanos upgrade\".`,\n    );\n  }\n\n  ctx.emitClaudeCodeHint({ tool: 'ekanos', toolchain: notice });\n}\n"]}

package/dist/validate-findings.d.ts

@@ -6,5 +6,17 @@ import type { LoadedProject } from './project.js';
  * implementation so the publish gate can never drift from what `validate`
  * checks — a project that validates clean is, by construction, a project that
  * publish will accept locally.
+ *
+ * NOTE on schema skew: an earlier version of this function rewrote the
+ * unrecognized-key hint when the project's `@ekanos/integration-schema` was
+ * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —
+ * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`
+ * or `publish` ever calls this function in that state, so a project-newer
+ * finding can never reach here to be rewritten, and the precondition error
+ * already names both versions and points at the fix. It was removed rather
+ * than kept "just in case": if a future caller ever makes validate proceed
+ * under skew instead of failing fast, THAT is when a rewrite here becomes
+ * necessary again, and it should be reintroduced with a real caller driving
+ * it, not tests that fake their own reachability.
  */
 export declare function collectAllFindings(loaded: LoadedProject): Promise<Finding[]>;

package/dist/validate-findings.js

@@ -8,6 +8,18 @@ import { collectProjectFindings } from './project-checks.js';
  * implementation so the publish gate can never drift from what `validate`
  * checks — a project that validates clean is, by construction, a project that
  * publish will accept locally.
+ *
+ * NOTE on schema skew: an earlier version of this function rewrote the
+ * unrecognized-key hint when the project's `@ekanos/integration-schema` was
+ * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —
+ * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`
+ * or `publish` ever calls this function in that state, so a project-newer
+ * finding can never reach here to be rewritten, and the precondition error
+ * already names both versions and points at the fix. It was removed rather
+ * than kept "just in case": if a future caller ever makes validate proceed
+ * under skew instead of failing fast, THAT is when a rewrite here becomes
+ * necessary again, and it should be reintroduced with a real caller driving
+ * it, not tests that fake their own reachability.
  */
 export async function collectAllFindings(loaded) {
     const findings = [];

package/dist/validate-findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAqB;IAErB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAA+B,EAAE,CAAC;IAEnD,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,WAAW,CAAC,SAAS,EACrB,MAAM,CAAC,UAAU,CAClB,CAAC;QAEF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CACX,GAAG,yBAAyB,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9C,IAAI,EAAE,WAAW,CAAC,SAAS;aAC5B,CAAC,CACH,CAAC;YACF,QAAQ,CAAC,IAAI,CACX,GAAG,4BAA4B,CAC7B,WAAW,EACX,MAAM,CAAC,UAAgC,CACxC,CACF,CAAC;YACF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,UAAsC,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,yEAAyE;YACzE,iEAAiE;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,iBAAiB;gBACxB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,WAAW,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EACF,oEAAoE;oBACpE,uBAAuB;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,kEAAkE;QAClE,MAAM,iBAAiB,CACrB,kDAAkD,WAAW,CAAC,IAAI,KAAK;YACrE,MAAM,CAAC,OAAO,EAChB,oEAAoE;YAClE,6BAA6B,CAChC,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,4BAA4B,CACnC,WAA+D,EAC/D,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC;IACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,WAAW,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAE7E,OAAO;QACL;YACE,KAAK,EAAE,wBAAwB;YAC/B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,WAAW,CAAC,SAAS;YAC3B,OAAO,EACL,8BAA8B,WAAW,CAAC,IAAI,wBAAwB;gBACtE,wBAAwB,QAAQ,4BAA4B;gBAC5D,sEAAsE;gBACtE,qCAAqC;YACvC,IAAI,EACF,sDAAsD,QAAQ,OAAO;gBACrE,+BAA+B,WAAW,CAAC,IAAI,OAAO;gBACtD,sBAAsB;SACzB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\n\nimport { preconditionError } from './errors';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport { collectProjectFindings } from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n"]}
+{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAqB;IAErB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAA+B,EAAE,CAAC;IAEnD,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,WAAW,CAAC,SAAS,EACrB,MAAM,CAAC,UAAU,CAClB,CAAC;QAEF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CACX,GAAG,yBAAyB,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9C,IAAI,EAAE,WAAW,CAAC,SAAS;aAC5B,CAAC,CACH,CAAC;YACF,QAAQ,CAAC,IAAI,CACX,GAAG,4BAA4B,CAC7B,WAAW,EACX,MAAM,CAAC,UAAgC,CACxC,CACF,CAAC;YACF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,UAAsC,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,yEAAyE;YACzE,iEAAiE;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,iBAAiB;gBACxB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,WAAW,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EACF,oEAAoE;oBACpE,uBAAuB;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,kEAAkE;QAClE,MAAM,iBAAiB,CACrB,kDAAkD,WAAW,CAAC,IAAI,KAAK;YACrE,MAAM,CAAC,OAAO,EAChB,oEAAoE;YAClE,6BAA6B,CAChC,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,4BAA4B,CACnC,WAA+D,EAC/D,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC;IACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,WAAW,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAE7E,OAAO;QACL;YACE,KAAK,EAAE,wBAAwB;YAC/B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,WAAW,CAAC,SAAS;YAC3B,OAAO,EACL,8BAA8B,WAAW,CAAC,IAAI,wBAAwB;gBACtE,wBAAwB,QAAQ,4BAA4B;gBAC5D,sEAAsE;gBACtE,qCAAqC;YACvC,IAAI,EACF,sDAAsD,QAAQ,OAAO;gBACrE,+BAA+B,WAAW,CAAC,IAAI,OAAO;gBACtD,sBAAsB;SACzB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\n\nimport { preconditionError } from './errors';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport { collectProjectFindings } from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n *\n * NOTE on schema skew: an earlier version of this function rewrote the\n * unrecognized-key hint when the project's `@ekanos/integration-schema` was\n * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —\n * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`\n * or `publish` ever calls this function in that state, so a project-newer\n * finding can never reach here to be rewritten, and the precondition error\n * already names both versions and points at the fix. It was removed rather\n * than kept \"just in case\": if a future caller ever makes validate proceed\n * under skew instead of failing fast, THAT is when a rewrite here becomes\n * necessary again, and it should be reintroduced with a real caller driving\n * it, not tests that fake their own reachability.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",

package/templates/AGENTS.md.tmpl

@@ -156,10 +156,20 @@ 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: catch transient upstream
-failures (timeouts, 5xx), log, and return — a throw surfaces a scary warning
-on a brand-new connection that the schedule will heal within one tick anyway.
-Reserve the throw for misconfiguration the user can actually fix.
+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
@@ -190,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
 
@@ -223,6 +242,14 @@ 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.
 
+A global install (`npm i -g @ekanos/cli`) is fine and convenient: inside a
+project, `validate`/`dev`/`publish`/`test` automatically delegate to THIS
+project's own pinned `@ekanos/cli` devDependency whenever it differs from the
+invoked binary (the same pattern as the Gradle wrapper or `npx`) — one global
+binary on PATH, but the version that actually reads your definition is always
+the one this project pins. That is also why the scaffold's local
+`@ekanos/cli` devDependency stays mandatory even with a global install.
+
 ## The iteration loop (`npx ekanos <verb>`)
 
 Every verb speaks a JSON envelope on stdout with `--json` (auto-on when piped):
@@ -237,20 +264,56 @@ 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 |
+| `ekanos upgrade` | Move this project's toolchain to a coherent target version, with verify-and-rollback |
+
+### Keeping the toolchain current
+
+`validate`/`dev`/`publish` all bundle an EXACT `@ekanos/integration-schema`
+version, and a project can end up NEWER than that (a `pnpm up` on
+`@ekanos/sdk` alone is enough). In that state `validate`'s findings are
+unreliable — a field the newer schema added parses here as an unrecognized
+key, and it is easy to "fix" that by deleting perfectly correct code. If a
+finding smells like that (an unrecognized key on a field you are confident is
+right), run `ekanos upgrade --check` first: it is READ-ONLY and always safe —
+it only reports current vs. target versions and never touches the project. A
+bare `ekanos upgrade` (no flags) MUTATES the project: it installs the target
+versions, verifies with `ekanos validate` and this project's own test script,
+and rolls everything back automatically if either fails. Never run a bare
+`ekanos upgrade` as a way to "try and see" — use `--check` for that.
+
+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.md.tmpl

@@ -3,4 +3,5 @@
 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.
+status, publish, upgrade); every verb supports `--json` and a stable
+exit-code taxonomy.