@ekanos/cli 0.1.4 → 0.1.6

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/seats.d.ts

@@ -0,0 +1,21 @@
+import type { StoredSession } from './auth/credential-store.js';
+import { type AuthEnvironment } from './auth/session.js';
+import { type SourceSeat } from './sources-api.js';
+/**
+ * `sources`, `use`, `publish`'s target verification, and `whoami`'s seats
+ * degradation all need the same thing: the caller's source-seat list, with
+ * the one-refresh-one-retry recovery every other verb in this CLI applies to
+ * a stale access token (see `resolveIdentity` in `auth/session.ts`).
+ * Centralized here so all four call sites share one refresh policy instead of
+ * four subtly different copies.
+ */
+export type SeatsResult = {
+    status: 'ok';
+    sources: SourceSeat[];
+    session: StoredSession;
+}
+/** Unauthorized even after one refresh. */
+ | {
+    status: 'unauthorized';
+};
+export declare function fetchSeatsWithOneRefresh(env: AuthEnvironment, session: StoredSession): Promise<SeatsResult>;

package/dist/seats.js

@@ -0,0 +1,15 @@
+import { refreshStoredSession } from './auth/session.js';
+import { fetchSourceSeats } from './sources-api.js';
+export async function fetchSeatsWithOneRefresh(env, session) {
+    const first = await fetchSourceSeats(env.host, session.accessToken);
+    if (first.status === 'ok') {
+        return { status: 'ok', sources: first.sources, session };
+    }
+    const refreshed = await refreshStoredSession(env, session);
+    const second = await fetchSourceSeats(env.host, refreshed.accessToken);
+    if (second.status === 'ok') {
+        return { status: 'ok', sources: second.sources, session: refreshed };
+    }
+    return { status: 'unauthorized' };
+}
+//# sourceMappingURL=seats.js.map

package/dist/seats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seats.js","sourceRoot":"","sources":["../src/seats.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAmB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAelE,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,GAAoB,EACpB,OAAsB;IAEtB,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAEpE,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IAEvE,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IACvE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;AACpC,CAAC","sourcesContent":["import type { StoredSession } from './auth/credential-store';\nimport { type AuthEnvironment, refreshStoredSession } from './auth/session';\nimport { type SourceSeat, fetchSourceSeats } from './sources-api';\n\n/**\n * `sources`, `use`, `publish`'s target verification, and `whoami`'s seats\n * degradation all need the same thing: the caller's source-seat list, with\n * the one-refresh-one-retry recovery every other verb in this CLI applies to\n * a stale access token (see `resolveIdentity` in `auth/session.ts`).\n * Centralized here so all four call sites share one refresh policy instead of\n * four subtly different copies.\n */\nexport type SeatsResult =\n  | { status: 'ok'; sources: SourceSeat[]; session: StoredSession }\n  /** Unauthorized even after one refresh. */\n  | { status: 'unauthorized' };\n\nexport async function fetchSeatsWithOneRefresh(\n  env: AuthEnvironment,\n  session: StoredSession,\n): Promise<SeatsResult> {\n  const first = await fetchSourceSeats(env.host, session.accessToken);\n\n  if (first.status === 'ok') {\n    return { status: 'ok', sources: first.sources, session };\n  }\n\n  const refreshed = await refreshStoredSession(env, session);\n  const second = await fetchSourceSeats(env.host, refreshed.accessToken);\n\n  if (second.status === 'ok') {\n    return { status: 'ok', sources: second.sources, session: refreshed };\n  }\n\n  return { status: 'unauthorized' };\n}\n"]}

package/dist/sources-api.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The CLI's client for the Fusion source-seat visibility route.
+ *
+ * ---------------------------------------------------------------------------
+ * WIRE CONTRACT — the seam between this package and the Fusion web app.
+ *
+ * The server side lives in `apps/web/app/api/partner/sources/route.ts`. As
+ * with the auth routes and `publish-api.ts`, the two halves are coupled only
+ * by HTTP; tests stub `fetch`, never the route.
+ *
+ *   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
+ *           is sorted by slug. Empty array means no seats anywhere.
+ *     → 401 { error, code: "AUTH_REQUIRED" }      token absent or expired —
+ *                                                 refresh once and retry
+ *     → 403 { error, code: "MFA_REQUIRED" }
+ *     → 3xx                                       treated as 401 (an
+ *                                                 auth-gated Fusion page
+ *                                                 answers 307)
+ * ---------------------------------------------------------------------------
+ */
+export interface SourceSeat {
+    id: string;
+    slug: string;
+    name: string | null;
+    roles: string[];
+}
+export type FetchSourceSeatsResult = {
+    status: 'ok';
+    sources: SourceSeat[];
+}
+/** The bearer token did not authenticate — refresh and retry, once. */
+ | {
+    status: 'unauthorized';
+};
+/**
+ * List the sources the caller holds a seat on (any role). Authorization is
+ * entirely server-side (RLS on `source_memberships`): there is no client-side
+ * filter to get wrong here.
+ */
+export declare function fetchSourceSeats(host: string, accessToken: string): Promise<FetchSourceSeatsResult>;
+/** Guard for the "still unauthorized after one refresh" terminal case. */
+export declare function stillUnauthorizedSourceSeats(host: string): never;

package/dist/sources-api.js

@@ -0,0 +1,69 @@
+import { request } from './auth/fusion-api.js';
+import { authRequiredError, networkError } from './errors.js';
+/**
+ * List the sources the caller holds a seat on (any role). Authorization is
+ * entirely server-side (RLS on `source_memberships`): there is no client-side
+ * filter to get wrong here.
+ */
+export async function fetchSourceSeats(host, accessToken) {
+    var _a, _b;
+    const response = await request(`${host}/api/partner/sources`, {
+        method: 'GET',
+        headers: {
+            accept: 'application/json',
+            authorization: `Bearer ${accessToken}`,
+        },
+    });
+    if (response.status === 401 || isRedirect(response.status)) {
+        return { status: 'unauthorized' };
+    }
+    const body = await readOptionalJson(response);
+    if (response.status === 403) {
+        throw authRequiredError((_a = str(body.error)) !== null && _a !== void 0 ? _a : `${host} requires multi-factor authentication for this account.`, `Complete MFA in the browser, then run "ekanos login" again.`);
+    }
+    if (!response.ok) {
+        throw networkError(`${host}/api/partner/sources responded ${response.status}.`, response.status >= 500
+            ? `The Fusion deployment returned a server error. Retry shortly; if ` +
+                `it persists, report it with the status code.`
+            : `Confirm the host is a Fusion deployment running a build that ` +
+                `includes the partner sources route.`);
+    }
+    const data = ((_b = body.data) !== null && _b !== void 0 ? _b : {});
+    const rows = Array.isArray(data.sources) ? data.sources : [];
+    const sources = rows
+        .filter((row) => typeof row === 'object' && row !== null)
+        .map((row) => {
+        var _a, _b;
+        return ({
+            id: (_a = str(row.id)) !== null && _a !== void 0 ? _a : '',
+            slug: (_b = str(row.slug)) !== null && _b !== void 0 ? _b : '',
+            name: str(row.name),
+            roles: Array.isArray(row.roles)
+                ? row.roles.filter((role) => typeof role === 'string')
+                : [],
+        });
+    });
+    return { status: 'ok', sources };
+}
+/** Guard for the "still unauthorized after one refresh" terminal case. */
+export function stillUnauthorizedSourceSeats(host) {
+    throw authRequiredError(`The session for ${host} could not authorize the source seat lookup.`, `Run "ekanos login --host ${host}" and retry.`);
+}
+async function readOptionalJson(response) {
+    try {
+        const parsed = await response.json();
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : {};
+    }
+    catch (_a) {
+        return {};
+    }
+}
+function isRedirect(status) {
+    return status >= 300 && status < 400;
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+//# sourceMappingURL=sources-api.js.map

package/dist/sources-api.js.map

@@ -0,0 +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"]}

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>;