@ekanos/cli 0.1.5 → 0.1.7

package/dist/schema-skew.d.ts

@@ -0,0 +1,77 @@
+import type { CliContext } from './context.js';
+/**
+ * The schema-skew gate: `validate` and `publish` parse a partner's
+ * declaration with the REAL zod schemas from `@ekanos/integration-schema`,
+ * pinned to the EXACT version this build of `@ekanos/cli` was built against.
+ * A partner project can end up with a NEWER schema installed than the one
+ * this CLI validates with — `@ekanos/sdk` (or the project directly) got
+ * upgraded, the CLI did not — and that state is not merely "a little behind".
+ * It is actively WRONG: a field the newer schema added parses here as an
+ * `unrecognized_keys` zod issue, and the generic "host-assigned fields are
+ * never partner-authorable" hint tells the partner to delete code that is
+ * completely correct. That happened to a real partner. Failing loudly here
+ * beats answering falsely, so this gate runs BEFORE validate or publish do
+ * any of their own work — an incompatible pair produces no findings at all,
+ * rather than confidently wrong ones.
+ *
+ * The opposite skew — the project's schema is OLDER than the CLI's — is not
+ * dangerous in the same way (the CLI's validation is still correct; the
+ * partner just cannot use fields the CLI would recognize yet), so it warns
+ * instead of blocking.
+ */
+export declare const INTEGRATION_SCHEMA_PACKAGE = "@ekanos/integration-schema";
+/**
+ * The version of `@ekanos/integration-schema` THIS CLI validates with.
+ *
+ * Two tiers, tried in order:
+ *
+ *  1. The exact version declared in this CLI's own `package.json`
+ *     dependencies. In a published build this is a real pinned semver — `pnpm
+ *     publish` rewrites the monorepo's `workspace:*` protocol to the exact
+ *     version of the linked package at publish time, which is exactly the
+ *     "declare it explicitly" contract `compatibility.ts` already commits to
+ *     for the shell contract.
+ *  2. Failing that (this repo's own dev checkout, where the dependency is
+ *     still the literal `workspace:*` string), fall back to whatever
+ *     `@ekanos/integration-schema` this CLI itself resolves on disk — the
+ *     package a workspace install actually links next to the CLI.
+ *
+ * Returns null — never throws — when neither resolves, which degrades the
+ * gate to a no-op exactly like "the project has no node_modules" does. A
+ * partner's validate/publish must never fail because THIS lookup couldn't
+ * find an answer.
+ */
+export declare function bundledSchemaVersion(): string | null;
+export interface SchemaSkewResult {
+    status: 'ok' | 'project-newer' | 'project-older' | 'unresolvable';
+    cliSchemaVersion: string | null;
+    projectSchemaVersion: string | null;
+}
+/**
+ * What the PROJECT resolves for `@ekanos/integration-schema`, compared
+ * against what this CLI bundles.
+ *
+ * The project rarely depends on the schema package directly — it is a
+ * transitive dependency of `@ekanos/sdk` — so two candidates are considered,
+ * per the task: a direct top-level resolution (works when a package manager
+ * hoists it, or when a partner added it explicitly) AND the version
+ * `@ekanos/sdk` itself declares a dependency on (its package.json is always a
+ * direct project dependency, so it always resolves at the top level even when
+ * the schema package's own copy does not). The greater of whichever resolves
+ * is what "the project's installed schema" means here — either could be the
+ * copy Node actually loads, and closing the gate on the newer of the two is
+ * the safe direction: it only ever asks a partner to upgrade a CLI that is
+ * genuinely behind.
+ */
+export declare function detectSchemaSkew(projectDir: string): SchemaSkewResult;
+/**
+ * The gate itself. Call before `validate`/`publish` do anything else.
+ *
+ * Throws PRECONDITION_FAILED (never a validation finding — the definition
+ * cannot even be trusted to parse correctly in this state) when the project's
+ * schema is newer. Warns on stderr and returns normally for every other
+ * status, including the two that mean "nothing to say" (`ok`, `unresolvable`)
+ * so callers can uniformly branch on the returned result to decide whether to
+ * annotate their own JSON envelope.
+ */
+export declare function assertSchemaNotSkewed(ctx: CliContext, projectDir: string): SchemaSkewResult;

package/dist/schema-skew.js

@@ -0,0 +1,163 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { compareVersions } from './compatibility.js';
+import { preconditionError } from './errors.js';
+import { readInstalledPackageManifest } from './harness-scaffold.js';
+import { templatesDir } from './templates.js';
+/**
+ * The schema-skew gate: `validate` and `publish` parse a partner's
+ * declaration with the REAL zod schemas from `@ekanos/integration-schema`,
+ * pinned to the EXACT version this build of `@ekanos/cli` was built against.
+ * A partner project can end up with a NEWER schema installed than the one
+ * this CLI validates with — `@ekanos/sdk` (or the project directly) got
+ * upgraded, the CLI did not — and that state is not merely "a little behind".
+ * It is actively WRONG: a field the newer schema added parses here as an
+ * `unrecognized_keys` zod issue, and the generic "host-assigned fields are
+ * never partner-authorable" hint tells the partner to delete code that is
+ * completely correct. That happened to a real partner. Failing loudly here
+ * beats answering falsely, so this gate runs BEFORE validate or publish do
+ * any of their own work — an incompatible pair produces no findings at all,
+ * rather than confidently wrong ones.
+ *
+ * The opposite skew — the project's schema is OLDER than the CLI's — is not
+ * dangerous in the same way (the CLI's validation is still correct; the
+ * partner just cannot use fields the CLI would recognize yet), so it warns
+ * instead of blocking.
+ */
+export const INTEGRATION_SCHEMA_PACKAGE = '@ekanos/integration-schema';
+const SDK_PACKAGE = '@ekanos/sdk';
+const SEMVER_LIKE = /^\d+\.\d+\.\d+/;
+function looksLikeSemver(value) {
+    return typeof value === 'string' && SEMVER_LIKE.test(value);
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * The version of `@ekanos/integration-schema` THIS CLI validates with.
+ *
+ * Two tiers, tried in order:
+ *
+ *  1. The exact version declared in this CLI's own `package.json`
+ *     dependencies. In a published build this is a real pinned semver — `pnpm
+ *     publish` rewrites the monorepo's `workspace:*` protocol to the exact
+ *     version of the linked package at publish time, which is exactly the
+ *     "declare it explicitly" contract `compatibility.ts` already commits to
+ *     for the shell contract.
+ *  2. Failing that (this repo's own dev checkout, where the dependency is
+ *     still the literal `workspace:*` string), fall back to whatever
+ *     `@ekanos/integration-schema` this CLI itself resolves on disk — the
+ *     package a workspace install actually links next to the CLI.
+ *
+ * Returns null — never throws — when neither resolves, which degrades the
+ * gate to a no-op exactly like "the project has no node_modules" does. A
+ * partner's validate/publish must never fail because THIS lookup couldn't
+ * find an answer.
+ */
+export function bundledSchemaVersion() {
+    var _a;
+    const cliRoot = path.join(templatesDir(), '..');
+    const ownManifest = readJsonFile(path.join(cliRoot, 'package.json'));
+    const declared = typeof ownManifest === 'object' && ownManifest !== null
+        ? ((_a = ownManifest
+            .dependencies) !== null && _a !== void 0 ? _a : {})[INTEGRATION_SCHEMA_PACKAGE]
+        : undefined;
+    if (looksLikeSemver(declared))
+        return declared;
+    const nested = readJsonFile(path.join(cliRoot, 'node_modules', '@ekanos', 'integration-schema', 'package.json'));
+    const nestedVersion = typeof nested === 'object' && nested !== null
+        ? nested.version
+        : undefined;
+    return looksLikeSemver(nestedVersion) ? nestedVersion : null;
+}
+/**
+ * What the PROJECT resolves for `@ekanos/integration-schema`, compared
+ * against what this CLI bundles.
+ *
+ * The project rarely depends on the schema package directly — it is a
+ * transitive dependency of `@ekanos/sdk` — so two candidates are considered,
+ * per the task: a direct top-level resolution (works when a package manager
+ * hoists it, or when a partner added it explicitly) AND the version
+ * `@ekanos/sdk` itself declares a dependency on (its package.json is always a
+ * direct project dependency, so it always resolves at the top level even when
+ * the schema package's own copy does not). The greater of whichever resolves
+ * is what "the project's installed schema" means here — either could be the
+ * copy Node actually loads, and closing the gate on the newer of the two is
+ * the safe direction: it only ever asks a partner to upgrade a CLI that is
+ * genuinely behind.
+ */
+export function detectSchemaSkew(projectDir) {
+    var _a;
+    const cliSchemaVersion = bundledSchemaVersion();
+    if (!cliSchemaVersion) {
+        return {
+            status: 'unresolvable',
+            cliSchemaVersion: null,
+            projectSchemaVersion: null,
+        };
+    }
+    const direct = readInstalledPackageManifest(projectDir, INTEGRATION_SCHEMA_PACKAGE);
+    const sdk = readInstalledPackageManifest(projectDir, SDK_PACKAGE);
+    const sdkDeclaredSchema = sdk && typeof sdk.manifest === 'object' && sdk.manifest !== null
+        ? ((_a = sdk.manifest
+            .dependencies) !== null && _a !== void 0 ? _a : {})[INTEGRATION_SCHEMA_PACKAGE]
+        : undefined;
+    const candidates = [direct === null || direct === void 0 ? void 0 : direct.version, sdkDeclaredSchema].filter(looksLikeSemver);
+    if (candidates.length === 0) {
+        return {
+            status: 'unresolvable',
+            cliSchemaVersion,
+            projectSchemaVersion: null,
+        };
+    }
+    const projectSchemaVersion = candidates.reduce((max, candidate) => compareVersions(candidate, max) > 0 ? candidate : max);
+    const cmp = compareVersions(projectSchemaVersion, cliSchemaVersion);
+    return {
+        status: cmp > 0 ? 'project-newer' : cmp < 0 ? 'project-older' : 'ok',
+        cliSchemaVersion,
+        projectSchemaVersion,
+    };
+}
+/**
+ * The gate itself. Call before `validate`/`publish` do anything else.
+ *
+ * Throws PRECONDITION_FAILED (never a validation finding — the definition
+ * cannot even be trusted to parse correctly in this state) when the project's
+ * schema is newer. Warns on stderr and returns normally for every other
+ * status, including the two that mean "nothing to say" (`ok`, `unresolvable`)
+ * so callers can uniformly branch on the returned result to decide whether to
+ * annotate their own JSON envelope.
+ */
+export function assertSchemaNotSkewed(ctx, projectDir) {
+    const result = detectSchemaSkew(projectDir);
+    if (result.status === 'project-newer') {
+        throw preconditionError(`The project's ${INTEGRATION_SCHEMA_PACKAGE}@${result.projectSchemaVersion} ` +
+            `is newer than ${result.cliSchemaVersion}, the version this ` +
+            `@ekanos/cli build validates with. Findings from "ekanos validate" ` +
+            'are UNRELIABLE in this state: a field the newer schema added ' +
+            'parses here as an unrecognized key, and the usual hint for that ' +
+            'tells you to delete code that is actually correct.', 
+        // NEVER interpolate the schema version into a "@ekanos/cli@<version>"
+        // install spec — the two version completely independently (this build
+        // is cli 0.1.6 validating against schema 0.1.4). "ekanos upgrade"
+        // resolves the actual coherent set; the manual fallback can only ever
+        // be "latest", never a computed number.
+        'Upgrade the CLI: run "ekanos upgrade" (it resolves a coherent target ' +
+            'version set), or pin it explicitly by hand with ' +
+            '"npm i -D @ekanos/cli@latest". Then re-run "ekanos validate" or ' +
+            '"ekanos publish".');
+    }
+    if (result.status === 'project-older') {
+        ctx.warn(`ekanos: the installed ${INTEGRATION_SCHEMA_PACKAGE}@${result.projectSchemaVersion} ` +
+            `is older than ${result.cliSchemaVersion}, the version this CLI ` +
+            'validates with — some fields this CLI recognizes may not be usable ' +
+            'yet. Run "ekanos upgrade" to bring the toolchain in sync.');
+    }
+    return result;
+}
+//# sourceMappingURL=schema-skew.js.map

package/dist/schema-skew.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-skew.js","sourceRoot":"","sources":["../src/schema-skew.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { compareVersions } from './compatibility';\nimport type { CliContext } from './context';\nimport { preconditionError } from './errors';\nimport { readInstalledPackageManifest } from './harness-scaffold';\nimport { templatesDir } from './templates';\n\n/**\n * The schema-skew gate: `validate` and `publish` parse a partner's\n * declaration with the REAL zod schemas from `@ekanos/integration-schema`,\n * pinned to the EXACT version this build of `@ekanos/cli` was built against.\n * A partner project can end up with a NEWER schema installed than the one\n * this CLI validates with — `@ekanos/sdk` (or the project directly) got\n * upgraded, the CLI did not — and that state is not merely \"a little behind\".\n * It is actively WRONG: a field the newer schema added parses here as an\n * `unrecognized_keys` zod issue, and the generic \"host-assigned fields are\n * never partner-authorable\" hint tells the partner to delete code that is\n * completely correct. That happened to a real partner. Failing loudly here\n * beats answering falsely, so this gate runs BEFORE validate or publish do\n * any of their own work — an incompatible pair produces no findings at all,\n * rather than confidently wrong ones.\n *\n * The opposite skew — the project's schema is OLDER than the CLI's — is not\n * dangerous in the same way (the CLI's validation is still correct; the\n * partner just cannot use fields the CLI would recognize yet), so it warns\n * instead of blocking.\n */\n\nexport const INTEGRATION_SCHEMA_PACKAGE = '@ekanos/integration-schema';\nconst SDK_PACKAGE = '@ekanos/sdk';\n\nconst SEMVER_LIKE = /^\\d+\\.\\d+\\.\\d+/;\n\nfunction looksLikeSemver(value: unknown): value is string {\n  return typeof value === 'string' && SEMVER_LIKE.test(value);\n}\n\nfunction readJsonFile(filePath: string): unknown {\n  try {\n    return JSON.parse(fs.readFileSync(filePath, 'utf8'));\n  } catch {\n    return null;\n  }\n}\n\n/**\n * The version of `@ekanos/integration-schema` THIS CLI validates with.\n *\n * Two tiers, tried in order:\n *\n *  1. The exact version declared in this CLI's own `package.json`\n *     dependencies. In a published build this is a real pinned semver — `pnpm\n *     publish` rewrites the monorepo's `workspace:*` protocol to the exact\n *     version of the linked package at publish time, which is exactly the\n *     \"declare it explicitly\" contract `compatibility.ts` already commits to\n *     for the shell contract.\n *  2. Failing that (this repo's own dev checkout, where the dependency is\n *     still the literal `workspace:*` string), fall back to whatever\n *     `@ekanos/integration-schema` this CLI itself resolves on disk — the\n *     package a workspace install actually links next to the CLI.\n *\n * Returns null — never throws — when neither resolves, which degrades the\n * gate to a no-op exactly like \"the project has no node_modules\" does. A\n * partner's validate/publish must never fail because THIS lookup couldn't\n * find an answer.\n */\nexport function bundledSchemaVersion(): string | null {\n  const cliRoot = path.join(templatesDir(), '..');\n\n  const ownManifest = readJsonFile(path.join(cliRoot, 'package.json'));\n  const declared =\n    typeof ownManifest === 'object' && ownManifest !== null\n      ? ((ownManifest as { dependencies?: Record<string, unknown> })\n          .dependencies ?? {})[INTEGRATION_SCHEMA_PACKAGE]\n      : undefined;\n  if (looksLikeSemver(declared)) return declared;\n\n  const nested = readJsonFile(\n    path.join(\n      cliRoot,\n      'node_modules',\n      '@ekanos',\n      'integration-schema',\n      'package.json',\n    ),\n  );\n  const nestedVersion =\n    typeof nested === 'object' && nested !== null\n      ? (nested as { version?: unknown }).version\n      : undefined;\n\n  return looksLikeSemver(nestedVersion) ? nestedVersion : null;\n}\n\nexport interface SchemaSkewResult {\n  status: 'ok' | 'project-newer' | 'project-older' | 'unresolvable';\n  cliSchemaVersion: string | null;\n  projectSchemaVersion: string | null;\n}\n\n/**\n * What the PROJECT resolves for `@ekanos/integration-schema`, compared\n * against what this CLI bundles.\n *\n * The project rarely depends on the schema package directly — it is a\n * transitive dependency of `@ekanos/sdk` — so two candidates are considered,\n * per the task: a direct top-level resolution (works when a package manager\n * hoists it, or when a partner added it explicitly) AND the version\n * `@ekanos/sdk` itself declares a dependency on (its package.json is always a\n * direct project dependency, so it always resolves at the top level even when\n * the schema package's own copy does not). The greater of whichever resolves\n * is what \"the project's installed schema\" means here — either could be the\n * copy Node actually loads, and closing the gate on the newer of the two is\n * the safe direction: it only ever asks a partner to upgrade a CLI that is\n * genuinely behind.\n */\nexport function detectSchemaSkew(projectDir: string): SchemaSkewResult {\n  const cliSchemaVersion = bundledSchemaVersion();\n  if (!cliSchemaVersion) {\n    return {\n      status: 'unresolvable',\n      cliSchemaVersion: null,\n      projectSchemaVersion: null,\n    };\n  }\n\n  const direct = readInstalledPackageManifest(\n    projectDir,\n    INTEGRATION_SCHEMA_PACKAGE,\n  );\n  const sdk = readInstalledPackageManifest(projectDir, SDK_PACKAGE);\n  const sdkDeclaredSchema =\n    sdk && typeof sdk.manifest === 'object' && sdk.manifest !== null\n      ? ((sdk.manifest as { dependencies?: Record<string, unknown> })\n          .dependencies ?? {})[INTEGRATION_SCHEMA_PACKAGE]\n      : undefined;\n\n  const candidates = [direct?.version, sdkDeclaredSchema].filter(\n    looksLikeSemver,\n  );\n\n  if (candidates.length === 0) {\n    return {\n      status: 'unresolvable',\n      cliSchemaVersion,\n      projectSchemaVersion: null,\n    };\n  }\n\n  const projectSchemaVersion = candidates.reduce((max, candidate) =>\n    compareVersions(candidate, max) > 0 ? candidate : max,\n  );\n\n  const cmp = compareVersions(projectSchemaVersion, cliSchemaVersion);\n\n  return {\n    status: cmp > 0 ? 'project-newer' : cmp < 0 ? 'project-older' : 'ok',\n    cliSchemaVersion,\n    projectSchemaVersion,\n  };\n}\n\n/**\n * The gate itself. Call before `validate`/`publish` do anything else.\n *\n * Throws PRECONDITION_FAILED (never a validation finding — the definition\n * cannot even be trusted to parse correctly in this state) when the project's\n * schema is newer. Warns on stderr and returns normally for every other\n * status, including the two that mean \"nothing to say\" (`ok`, `unresolvable`)\n * so callers can uniformly branch on the returned result to decide whether to\n * annotate their own JSON envelope.\n */\nexport function assertSchemaNotSkewed(\n  ctx: CliContext,\n  projectDir: string,\n): SchemaSkewResult {\n  const result = detectSchemaSkew(projectDir);\n\n  if (result.status === 'project-newer') {\n    throw preconditionError(\n      `The project's ${INTEGRATION_SCHEMA_PACKAGE}@${result.projectSchemaVersion} ` +\n        `is newer than ${result.cliSchemaVersion}, the version this ` +\n        `@ekanos/cli build validates with. Findings from \"ekanos validate\" ` +\n        'are UNRELIABLE in this state: a field the newer schema added ' +\n        'parses here as an unrecognized key, and the usual hint for that ' +\n        'tells you to delete code that is actually correct.',\n      // NEVER interpolate the schema version into a \"@ekanos/cli@<version>\"\n      // install spec — the two version completely independently (this build\n      // is cli 0.1.6 validating against schema 0.1.4). \"ekanos upgrade\"\n      // resolves the actual coherent set; the manual fallback can only ever\n      // be \"latest\", never a computed number.\n      'Upgrade the CLI: run \"ekanos upgrade\" (it resolves a coherent target ' +\n        'version set), or pin it explicitly by hand with ' +\n        '\"npm i -D @ekanos/cli@latest\". Then re-run \"ekanos validate\" or ' +\n        '\"ekanos publish\".',\n    );\n  }\n\n  if (result.status === 'project-older') {\n    ctx.warn(\n      `ekanos: the installed ${INTEGRATION_SCHEMA_PACKAGE}@${result.projectSchemaVersion} ` +\n        `is older than ${result.cliSchemaVersion}, the version this CLI ` +\n        'validates with — some fields this CLI recognizes may not be usable ' +\n        'yet. Run \"ekanos upgrade\" to bring the toolchain in sync.',\n    );\n  }\n\n  return result;\n}\n"]}

package/dist/sources-api.d.ts

@@ -10,7 +10,7 @@
  *
  *   GET /api/partner/sources        [Authorization: Bearer <access_token>]
  *     → 200 { ok: true, data: { sources: [{ id, slug, name, roles }] } }
- *           roles is a non-empty array of "dev" | "admin", sorted; sources
+ *           roles is a non-empty array of "developer" | "source_admin", sorted; sources
  *           is sorted by slug. Empty array means no seats anywhere.
  *     → 401 { error, code: "AUTH_REQUIRED" }      token absent or expired —
  *                                                 refresh once and retry

package/dist/sources-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"sources-api.js","sourceRoot":"","sources":["../src/sources-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from './auth/fusion-api';\nimport { authRequiredError, networkError } from './errors';\n\n/**\n * The CLI's client for the Fusion source-seat visibility 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/sources/route.ts`. As\n * with the auth routes and `publish-api.ts`, the two halves are coupled only\n * by HTTP; tests stub `fetch`, never the route.\n *\n *   GET /api/partner/sources        [Authorization: Bearer <access_token>]\n *     → 200 { ok: true, data: { sources: [{ id, slug, name, roles }] } }\n *           roles is a non-empty array of \"dev\" | \"admin\", sorted; sources\n *           is sorted by slug. Empty array means no seats anywhere.\n *     → 401 { error, code: \"AUTH_REQUIRED\" }      token absent or expired —\n *                                                 refresh once and retry\n *     → 403 { error, code: \"MFA_REQUIRED\" }\n *     → 3xx                                       treated as 401 (an\n *                                                 auth-gated Fusion page\n *                                                 answers 307)\n * ---------------------------------------------------------------------------\n */\n\nexport interface SourceSeat {\n  id: string;\n  slug: string;\n  name: string | null;\n  roles: string[];\n}\n\nexport type FetchSourceSeatsResult =\n  | { status: 'ok'; sources: SourceSeat[] }\n  /** The bearer token did not authenticate — refresh and retry, once. */\n  | { status: 'unauthorized' };\n\n/**\n * List the sources the caller holds a seat on (any role). Authorization is\n * entirely server-side (RLS on `source_memberships`): there is no client-side\n * filter to get wrong here.\n */\nexport async function fetchSourceSeats(\n  host: string,\n  accessToken: string,\n): Promise<FetchSourceSeatsResult> {\n  const response = await request(`${host}/api/partner/sources`, {\n    method: 'GET',\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n    },\n  });\n\n  if (response.status === 401 || isRedirect(response.status)) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n\n  if (response.status === 403) {\n    throw authRequiredError(\n      str(body.error) ??\n        `${host} requires multi-factor authentication for this account.`,\n      `Complete MFA in the browser, then run \"ekanos login\" again.`,\n    );\n  }\n\n  if (!response.ok) {\n    throw networkError(\n      `${host}/api/partner/sources 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 sources route.`,\n    );\n  }\n\n  const data = (body.data ?? {}) as Record<string, unknown>;\n  const rows = Array.isArray(data.sources) ? data.sources : [];\n\n  const sources = 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      roles: Array.isArray(row.roles)\n        ? row.roles.filter((role): role is string => typeof role === 'string')\n        : [],\n    }));\n\n  return { status: 'ok', sources };\n}\n\n/** Guard for the \"still unauthorized after one refresh\" terminal case. */\nexport function stillUnauthorizedSourceSeats(host: string): never {\n  throw authRequiredError(\n    `The session for ${host} could not authorize the source seat lookup.`,\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":"sources-api.js","sourceRoot":"","sources":["../src/sources-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from './auth/fusion-api';\nimport { authRequiredError, networkError } from './errors';\n\n/**\n * The CLI's client for the Fusion source-seat visibility 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/sources/route.ts`. As\n * with the auth routes and `publish-api.ts`, the two halves are coupled only\n * by HTTP; tests stub `fetch`, never the route.\n *\n *   GET /api/partner/sources        [Authorization: Bearer <access_token>]\n *     → 200 { ok: true, data: { sources: [{ id, slug, name, roles }] } }\n *           roles is a non-empty array of \"developer\" | \"source_admin\", sorted; sources\n *           is sorted by slug. Empty array means no seats anywhere.\n *     → 401 { error, code: \"AUTH_REQUIRED\" }      token absent or expired —\n *                                                 refresh once and retry\n *     → 403 { error, code: \"MFA_REQUIRED\" }\n *     → 3xx                                       treated as 401 (an\n *                                                 auth-gated Fusion page\n *                                                 answers 307)\n * ---------------------------------------------------------------------------\n */\n\nexport interface SourceSeat {\n  id: string;\n  slug: string;\n  name: string | null;\n  roles: string[];\n}\n\nexport type FetchSourceSeatsResult =\n  | { status: 'ok'; sources: SourceSeat[] }\n  /** The bearer token did not authenticate — refresh and retry, once. */\n  | { status: 'unauthorized' };\n\n/**\n * List the sources the caller holds a seat on (any role). Authorization is\n * entirely server-side (RLS on `source_memberships`): there is no client-side\n * filter to get wrong here.\n */\nexport async function fetchSourceSeats(\n  host: string,\n  accessToken: string,\n): Promise<FetchSourceSeatsResult> {\n  const response = await request(`${host}/api/partner/sources`, {\n    method: 'GET',\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n    },\n  });\n\n  if (response.status === 401 || isRedirect(response.status)) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n\n  if (response.status === 403) {\n    throw authRequiredError(\n      str(body.error) ??\n        `${host} requires multi-factor authentication for this account.`,\n      `Complete MFA in the browser, then run \"ekanos login\" again.`,\n    );\n  }\n\n  if (!response.ok) {\n    throw networkError(\n      `${host}/api/partner/sources 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 sources route.`,\n    );\n  }\n\n  const data = (body.data ?? {}) as Record<string, unknown>;\n  const rows = Array.isArray(data.sources) ? data.sources : [];\n\n  const sources = 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      roles: Array.isArray(row.roles)\n        ? row.roles.filter((role): role is string => typeof role === 'string')\n        : [],\n    }));\n\n  return { status: 'ok', sources };\n}\n\n/** Guard for the \"still unauthorized after one refresh\" terminal case. */\nexport function stillUnauthorizedSourceSeats(host: string): never {\n  throw authRequiredError(\n    `The session for ${host} could not authorize the source seat lookup.`,\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/dist/toolchain-api.d.ts

@@ -0,0 +1,54 @@
+import { type ToolchainNote, type ToolchainVersions } from './toolchain.js';
+/**
+ * The CLI's client for the Fusion toolchain-advisory route.
+ *
+ * ---------------------------------------------------------------------------
+ * WIRE CONTRACT — the seam between this package and the Fusion web app.
+ *
+ * The server side lives in `apps/web/app/api/partner/toolchain/route.ts` and
+ * ships on a DIFFERENT BRANCH from this file, same as every other route in
+ * `auth/fusion-api.ts` and `publish-api.ts`. Nothing here imports from
+ * `apps/web`; the two halves are coupled only by HTTP, and the tests stub
+ * `fetch`, never the route.
+ *
+ *   GET /api/partner/toolchain   [Authorization: Bearer <access_token>]
+ *     → 200 { ok: true, data: {
+ *         current:  { cli, sdk, ui, integrationSchema, harness },  // the
+ *                                                                  // coherent
+ *                                                                  // set the
+ *                                                                  // host
+ *                                                                  // recommends
+ *         minimum:  { cli, sdk, ui, integrationSchema, harness },  // below
+ *                                                                  // this the
+ *                                                                  // host
+ *                                                                  // refuses
+ *         notes?:   [{ level: "warn" | "info", message: string }],
+ *       } }
+ *     → any other status, or a body that fails to parse or match this shape
+ *
+ * This endpoint is treated as ADVISORY, not authoritative in the way the auth
+ * and submission routes are: a 404 (an older Fusion deployment that predates
+ * this route) or a 501 (deliberately unimplemented) are both entirely
+ * ordinary, and a 4xx/5xx/network failure/malformed body all mean exactly the
+ * same thing to every caller — "the endpoint is unavailable, fall back to the
+ * npm registry" — so this module never throws. There is no not-configured
+ * distinction to make here the way `cli-config` has: a caller with no way to
+ * reach this route at all (no host, no session) never calls it in the first
+ * place; see `toolchain-resolve.ts`.
+ *
+ * Unknown extra fields in the response are tolerated (only the fields above
+ * are read); a missing `notes` defaults to an empty array.
+ * ---------------------------------------------------------------------------
+ */
+export interface ToolchainReport {
+    current: ToolchainVersions;
+    minimum: ToolchainVersions;
+    notes: ToolchainNote[];
+}
+export type FetchToolchainResult = {
+    status: 'ok';
+    report: ToolchainReport;
+} | {
+    status: 'unavailable';
+};
+export declare function fetchToolchainReport(host: string, accessToken: string): Promise<FetchToolchainResult>;

package/dist/toolchain-api.js

@@ -0,0 +1,58 @@
+import { request } from './auth/fusion-api.js';
+import { TOOLCHAIN_PACKAGES, } from './toolchain.js';
+export async function fetchToolchainReport(host, accessToken) {
+    try {
+        const response = await request(`${host}/api/partner/toolchain`, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+                authorization: `Bearer ${accessToken}`,
+            },
+        });
+        if (!response.ok)
+            return { status: 'unavailable' };
+        const body = await response.json();
+        const report = parseReport(body);
+        return report ? { status: 'ok', report } : { status: 'unavailable' };
+    }
+    catch (_a) {
+        // Network failure, timeout, or a body that is not even JSON — all read
+        // the same: the endpoint is unavailable this time, fall back to npm.
+        return { status: 'unavailable' };
+    }
+}
+function parseReport(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const data = body.data;
+    if (typeof data !== 'object' || data === null)
+        return null;
+    const current = parseVersions(data.current);
+    const minimum = parseVersions(data.minimum);
+    if (!current || !minimum)
+        return null;
+    const rawNotes = data.notes;
+    const notes = Array.isArray(rawNotes) ? rawNotes.filter(isNote) : [];
+    return { current, minimum, notes };
+}
+function parseVersions(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const record = value;
+    const result = {};
+    for (const key of Object.keys(TOOLCHAIN_PACKAGES)) {
+        const raw = record[key];
+        if (typeof raw !== 'string' || raw.length === 0)
+            return null;
+        result[key] = raw;
+    }
+    return result;
+}
+function isNote(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const note = value;
+    return ((note.level === 'warn' || note.level === 'info') &&
+        typeof note.message === 'string');
+}
+//# sourceMappingURL=toolchain-api.js.map

package/dist/toolchain-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain-api.js","sourceRoot":"","sources":["../src/toolchain-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from './auth/fusion-api';\nimport {\n  TOOLCHAIN_PACKAGES,\n  type ToolchainNote,\n  type ToolchainVersions,\n} from './toolchain';\n\n/**\n * The CLI's client for the Fusion toolchain-advisory 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/toolchain/route.ts` and\n * ships on a DIFFERENT BRANCH from this file, same as every other route in\n * `auth/fusion-api.ts` and `publish-api.ts`. Nothing here imports from\n * `apps/web`; the two halves are coupled only by HTTP, and the tests stub\n * `fetch`, never the route.\n *\n *   GET /api/partner/toolchain   [Authorization: Bearer <access_token>]\n *     → 200 { ok: true, data: {\n *         current:  { cli, sdk, ui, integrationSchema, harness },  // the\n *                                                                  // coherent\n *                                                                  // set the\n *                                                                  // host\n *                                                                  // recommends\n *         minimum:  { cli, sdk, ui, integrationSchema, harness },  // below\n *                                                                  // this the\n *                                                                  // host\n *                                                                  // refuses\n *         notes?:   [{ level: \"warn\" | \"info\", message: string }],\n *       } }\n *     → any other status, or a body that fails to parse or match this shape\n *\n * This endpoint is treated as ADVISORY, not authoritative in the way the auth\n * and submission routes are: a 404 (an older Fusion deployment that predates\n * this route) or a 501 (deliberately unimplemented) are both entirely\n * ordinary, and a 4xx/5xx/network failure/malformed body all mean exactly the\n * same thing to every caller — \"the endpoint is unavailable, fall back to the\n * npm registry\" — so this module never throws. There is no not-configured\n * distinction to make here the way `cli-config` has: a caller with no way to\n * reach this route at all (no host, no session) never calls it in the first\n * place; see `toolchain-resolve.ts`.\n *\n * Unknown extra fields in the response are tolerated (only the fields above\n * are read); a missing `notes` defaults to an empty array.\n * ---------------------------------------------------------------------------\n */\n\nexport interface ToolchainReport {\n  current: ToolchainVersions;\n  minimum: ToolchainVersions;\n  notes: ToolchainNote[];\n}\n\nexport type FetchToolchainResult =\n  { status: 'ok'; report: ToolchainReport } | { status: 'unavailable' };\n\nexport async function fetchToolchainReport(\n  host: string,\n  accessToken: string,\n): Promise<FetchToolchainResult> {\n  try {\n    const response = await request(`${host}/api/partner/toolchain`, {\n      method: 'GET',\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n      },\n    });\n\n    if (!response.ok) return { status: 'unavailable' };\n\n    const body: unknown = await response.json();\n    const report = parseReport(body);\n\n    return report ? { status: 'ok', report } : { status: 'unavailable' };\n  } catch {\n    // Network failure, timeout, or a body that is not even JSON — all read\n    // the same: the endpoint is unavailable this time, fall back to npm.\n    return { status: 'unavailable' };\n  }\n}\n\nfunction parseReport(body: unknown): ToolchainReport | null {\n  if (typeof body !== 'object' || body === null) return null;\n  const data = (body as { data?: unknown }).data;\n  if (typeof data !== 'object' || data === null) return null;\n\n  const current = parseVersions((data as { current?: unknown }).current);\n  const minimum = parseVersions((data as { minimum?: unknown }).minimum);\n  if (!current || !minimum) return null;\n\n  const rawNotes = (data as { notes?: unknown }).notes;\n  const notes = Array.isArray(rawNotes) ? rawNotes.filter(isNote) : [];\n\n  return { current, minimum, notes };\n}\n\nfunction parseVersions(value: unknown): ToolchainVersions | null {\n  if (typeof value !== 'object' || value === null) return null;\n  const record = value as Record<string, unknown>;\n  const result: Partial<ToolchainVersions> = {};\n\n  for (const key of Object.keys(\n    TOOLCHAIN_PACKAGES,\n  ) as (keyof ToolchainVersions)[]) {\n    const raw = record[key];\n    if (typeof raw !== 'string' || raw.length === 0) return null;\n    result[key] = raw;\n  }\n\n  return result as ToolchainVersions;\n}\n\nfunction isNote(value: unknown): value is ToolchainNote {\n  if (typeof value !== 'object' || value === null) return false;\n  const note = value as { level?: unknown; message?: unknown };\n  return (\n    (note.level === 'warn' || note.level === 'info') &&\n    typeof note.message === 'string'\n  );\n}\n"]}

package/dist/toolchain-resolve.d.ts

@@ -0,0 +1,26 @@
+import { type ToolchainNote, type ToolchainVersions } from './toolchain.js';
+export type ToolchainResolution = {
+    status: 'ok';
+    source: 'host';
+    target: ToolchainVersions;
+    minimum: ToolchainVersions;
+    notes: ToolchainNote[];
+} | {
+    status: 'ok';
+    source: 'npm';
+    target: ToolchainVersions;
+} | {
+    status: 'incoherent';
+    detail: string;
+} | {
+    status: 'unavailable';
+};
+export interface ResolveToolchainParams {
+    host?: string;
+    session?: {
+        accessToken: string;
+    } | null;
+    /** Per-request timeout for the underlying fetches. */
+    timeoutMs?: number;
+}
+export declare function resolveToolchainTarget(params: ResolveToolchainParams): Promise<ToolchainResolution>;

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