@ekanos/cli 0.1.4 → 0.1.6

package/dist/commands/use.js

@@ -0,0 +1,62 @@
+import { requireSession, resolveAuthEnvironment } from '../auth/session.js';
+import { forbiddenError, usageError } from '../errors.js';
+import { loadProject } from '../project.js';
+import { fetchSeatsWithOneRefresh } from '../seats.js';
+import { stillUnauthorizedSourceSeats } from '../sources-api.js';
+import { persistProjectFields } from './publish.js';
+/**
+ * `use <source-slug>` — set this project's publish target, with the same
+ * seat verification `publish` runs: the slug must name a source the caller
+ * actually holds a seat on, so a project can never be pointed at a source by
+ * a typo alone.
+ *
+ * Persisted via the exact same mechanics `publish` uses after a successful
+ * submission (`persistProjectFields`), so `host` also sticks on first write
+ * and a later `publish` needs neither flag.
+ */
+export async function runUse(ctx, args) {
+    var _a;
+    if (!args.slug || args.slug.trim().length === 0) {
+        throw usageError('No source slug given.', 'Run "ekanos use <source-slug>" — see "ekanos sources" for the ' +
+            'slugs you hold a seat on.');
+    }
+    const slug = args.slug.trim();
+    // Requires a project up front: `use` sets ekanos.json's "source" field, so
+    // running it outside one is a precondition failure, not a network call.
+    const loaded = loadProject(args.dir);
+    const env = resolveAuthEnvironment(ctx, args.host, args.env, {
+        projectDir: args.dir,
+    });
+    const session = requireSession(env.store, env.host);
+    const result = await fetchSeatsWithOneRefresh(env, session);
+    if (result.status === 'unauthorized') {
+        stillUnauthorizedSourceSeats(env.host);
+    }
+    const seat = result.sources.find((s) => s.slug === slug);
+    if (!seat) {
+        throw forbiddenError(`This account does not hold a seat on source "${slug}" on ${env.host}.`, seatsHint(result.sources, env.host));
+    }
+    const persisted = persistProjectFields(loaded, seat.slug, env.host);
+    return ctx.succeed({
+        host: env.host,
+        source: {
+            id: seat.id,
+            slug: seat.slug,
+            name: seat.name,
+            roles: seat.roles,
+        },
+        sourcePersisted: persisted.source,
+        hostPersisted: persisted.host,
+    }, `use: ekanos.json now publishes to ${(_a = seat.name) !== null && _a !== void 0 ? _a : seat.slug} (${seat.slug}) on ${env.host}.`);
+}
+function seatsHint(sources, host) {
+    if (sources.length === 0) {
+        return (`You hold no seats on any source on ${host}. Ask a Fusion super-admin ` +
+            `to grant your account a seat on the intended source.`);
+    }
+    const list = sources
+        .map((s) => `${s.slug} (${s.roles.join(', ')})`)
+        .join(', ');
+    return `You hold a seat on: ${list}. Run "ekanos use <slug>" with one of these.`;
+}
+//# sourceMappingURL=use.js.map

package/dist/commands/use.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use.js","sourceRoot":"","sources":["../../src/commands/use.ts"],"names":[],"mappings":"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","sourcesContent":["import { requireSession, resolveAuthEnvironment } from '../auth/session';\nimport type { CliContext } from '../context';\nimport { forbiddenError, usageError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { loadProject } from '../project';\nimport { fetchSeatsWithOneRefresh } from '../seats';\nimport { type SourceSeat, stillUnauthorizedSourceSeats } from '../sources-api';\nimport { persistProjectFields } from './publish';\n\nexport interface UseArgs {\n  host?: string;\n  /** Project directory (contains ekanos.json). Defaults to cwd. */\n  dir: string;\n  /** The source slug to switch this project's publish target to. */\n  slug?: string;\n  env: Record<string, string | undefined>;\n}\n\n/**\n * `use <source-slug>` — set this project's publish target, with the same\n * seat verification `publish` runs: the slug must name a source the caller\n * actually holds a seat on, so a project can never be pointed at a source by\n * a typo alone.\n *\n * Persisted via the exact same mechanics `publish` uses after a successful\n * submission (`persistProjectFields`), so `host` also sticks on first write\n * and a later `publish` needs neither flag.\n */\nexport async function runUse(\n  ctx: CliContext,\n  args: UseArgs,\n): Promise<ExitCode> {\n  if (!args.slug || args.slug.trim().length === 0) {\n    throw usageError(\n      'No source slug given.',\n      'Run \"ekanos use <source-slug>\" — see \"ekanos sources\" for the ' +\n        'slugs you hold a seat on.',\n    );\n  }\n\n  const slug = args.slug.trim();\n\n  // Requires a project up front: `use` sets ekanos.json's \"source\" field, so\n  // running it outside one is a precondition failure, not a network call.\n  const loaded = loadProject(args.dir);\n\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.dir,\n  });\n  const session = requireSession(env.store, env.host);\n\n  const result = await fetchSeatsWithOneRefresh(env, session);\n\n  if (result.status === 'unauthorized') {\n    stillUnauthorizedSourceSeats(env.host);\n  }\n\n  const seat = result.sources.find((s) => s.slug === slug);\n\n  if (!seat) {\n    throw forbiddenError(\n      `This account does not hold a seat on source \"${slug}\" on ${env.host}.`,\n      seatsHint(result.sources, env.host),\n    );\n  }\n\n  const persisted = persistProjectFields(loaded, seat.slug, env.host);\n\n  return ctx.succeed(\n    {\n      host: env.host,\n      source: {\n        id: seat.id,\n        slug: seat.slug,\n        name: seat.name,\n        roles: seat.roles,\n      },\n      sourcePersisted: persisted.source,\n      hostPersisted: persisted.host,\n    },\n    `use: ekanos.json now publishes to ${seat.name ?? seat.slug} (${seat.slug}) on ${env.host}.`,\n  );\n}\n\nfunction seatsHint(sources: SourceSeat[], host: string): string {\n  if (sources.length === 0) {\n    return (\n      `You hold no seats on any source on ${host}. Ask a Fusion super-admin ` +\n      `to grant your account a seat on the intended source.`\n    );\n  }\n\n  const list = sources\n    .map((s) => `${s.slug} (${s.roles.join(', ')})`)\n    .join(', ');\n\n  return `You hold a seat on: ${list}. Run \"ekanos use <slug>\" with one of these.`;\n}\n"]}

package/dist/commands/validate.d.ts

@@ -3,6 +3,7 @@ import type { ExitCode } from '../exit-codes.js';
 export interface ValidateArgs {
     /** Project directory (contains ekanos.json). Defaults to cwd. */
     dir: string;
+    env?: Record<string, string | undefined>;
 }
 /**
  * `validate` — parse the declaration with the REAL zod schemas from
@@ -13,5 +14,9 @@ export interface ValidateArgs {
  *
  * The findings pass itself lives in `validate-findings.ts`, shared with
  * `publish` so the publish gate cannot drift from what validate checks.
+ *
+ * Runs the schema-skew gate FIRST, before anything else — see
+ * `schema-skew.ts` for why a newer project schema than the CLI bundles makes
+ * every finding below it unreliable.
  */
 export declare function runValidate(ctx: CliContext, args: ValidateArgs): Promise<ExitCode>;

package/dist/commands/validate.js

@@ -1,5 +1,7 @@
 import { validationError } from '../errors.js';
 import { loadProject } from '../project.js';
+import { assertSchemaNotSkewed } from '../schema-skew.js';
+import { announceUpdate, checkForUpdate } from '../update-notice.js';
 import { collectAllFindings } from '../validate-findings.js';
 /**
  * `validate` — parse the declaration with the REAL zod schemas from
@@ -10,22 +12,34 @@ import { collectAllFindings } from '../validate-findings.js';
  *
  * The findings pass itself lives in `validate-findings.ts`, shared with
  * `publish` so the publish gate cannot drift from what validate checks.
+ *
+ * Runs the schema-skew gate FIRST, before anything else — see
+ * `schema-skew.ts` for why a newer project schema than the CLI bundles makes
+ * every finding below it unreliable.
  */
 export async function runValidate(ctx, args) {
+    var _a;
     const loaded = loadProject(args.dir);
+    const skew = assertSchemaNotSkewed(ctx, loaded.projectDir);
+    const notice = await checkForUpdate({ env: (_a = args.env) !== null && _a !== void 0 ? _a : process.env });
+    announceUpdate(ctx, notice);
     const slugs = loaded.integrations.map((i) => i.slug).join(', ');
     ctx.log(`Validating ${loaded.integrations.length} integration` +
         `${loaded.integrations.length === 1 ? '' : 's'} (${slugs})…`);
     const findings = await collectAllFindings(loaded);
     const errorCount = findings.filter((f) => f.severity === 'error').length;
-    const data = {
-        slug: loaded.primary.slug,
-        integrations: loaded.integrations.map((i) => ({
+    const data = Object.assign(Object.assign({ slug: loaded.primary.slug, integrations: loaded.integrations.map((i) => ({
             slug: i.slug,
             entry: i.entry,
-        })),
-        findings,
-    };
+        })), findings }, (skew.status === 'project-older'
+        ? {
+            schemaSkew: {
+                status: skew.status,
+                cliSchemaVersion: skew.cliSchemaVersion,
+                projectSchemaVersion: skew.projectSchemaVersion,
+            },
+        }
+        : {})), (notice ? { toolchain: notice } : {}));
     if (errorCount > 0) {
         return ctx.fail(validationError(`${errorCount} validation finding${errorCount === 1 ? '' : 's'}.`, 'Resolve the error-severity findings in data.findings, then re-run ' +
             '"ekanos validate".'), data);

package/dist/commands/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAO1D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAe,EACf,IAAkB;IAElB,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,GAAG,CAAC,GAAG,CACL,cAAc,MAAM,CAAC,YAAY,CAAC,MAAM,cAAc;QACpD,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,CAC/D,CAAC;IAEF,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAElD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IACzE,MAAM,IAAI,GAAG;QACX,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI;QACzB,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5C,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;SACf,CAAC,CAAC;QACH,QAAQ;KACT,CAAC;IAEF,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,OAAO,GAAG,CAAC,IAAI,CACb,eAAe,CACb,GAAG,UAAU,sBAAsB,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,EACjE,oEAAoE;YAClE,oBAAoB,CACvB,EACD,IAAI,CACL,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,kCAAkC,KAAK,GAAG,CAAC,CAAC;AACvE,CAAC","sourcesContent":["import type { CliContext } from '../context';\nimport { validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { loadProject } from '../project';\nimport { collectAllFindings } from '../validate-findings';\n\nexport interface ValidateArgs {\n  /** Project directory (contains ekanos.json). Defaults to cwd. */\n  dir: string;\n}\n\n/**\n * `validate` — parse the declaration with the REAL zod schemas from\n * `@ekanos/integration-schema` (never a reimplementation), gather structured\n * findings, and add project-level integrity checks (the vitest inline-SDK\n * check). Exit 0 with `findings: []` when clean; exit 3 when any error-severity\n * finding is present, with the findings carried in the envelope's `data`.\n *\n * The findings pass itself lives in `validate-findings.ts`, shared with\n * `publish` so the publish gate cannot drift from what validate checks.\n */\nexport async function runValidate(\n  ctx: CliContext,\n  args: ValidateArgs,\n): Promise<ExitCode> {\n  const loaded = loadProject(args.dir);\n  const slugs = loaded.integrations.map((i) => i.slug).join(', ');\n  ctx.log(\n    `Validating ${loaded.integrations.length} integration` +\n      `${loaded.integrations.length === 1 ? '' : 's'} (${slugs})…`,\n  );\n\n  const findings = await collectAllFindings(loaded);\n\n  const errorCount = findings.filter((f) => f.severity === 'error').length;\n  const data = {\n    slug: loaded.primary.slug,\n    integrations: loaded.integrations.map((i) => ({\n      slug: i.slug,\n      entry: i.entry,\n    })),\n    findings,\n  };\n\n  if (errorCount > 0) {\n    return ctx.fail(\n      validationError(\n        `${errorCount} validation finding${errorCount === 1 ? '' : 's'}.`,\n        'Resolve the error-severity findings in data.findings, then re-run ' +\n          '\"ekanos validate\".',\n      ),\n      data,\n    );\n  }\n\n  return ctx.succeed(data, `validate: OK — no findings for ${slugs}.`);\n}\n"]}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAQ1D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAe,EACf,IAAkB;;IAElB,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAErC,MAAM,IAAI,GAAG,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAE3D,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,GAAG,EAAE,MAAA,IAAI,CAAC,GAAG,mCAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACtE,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAE5B,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,GAAG,CAAC,GAAG,CACL,cAAc,MAAM,CAAC,YAAY,CAAC,MAAM,cAAc;QACpD,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,CAC/D,CAAC;IAEF,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAElD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IACzE,MAAM,IAAI,iCACR,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,EACzB,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5C,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;SACf,CAAC,CAAC,EACH,QAAQ,IACL,CAAC,IAAI,CAAC,MAAM,KAAK,eAAe;QACjC,CAAC,CAAC;YACE,UAAU,EAAE;gBACV,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;gBACvC,oBAAoB,EAAE,IAAI,CAAC,oBAAoB;aAChD;SACF;QACH,CAAC,CAAC,EAAE,CAAC,GACJ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACzC,CAAC;IAEF,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,OAAO,GAAG,CAAC,IAAI,CACb,eAAe,CACb,GAAG,UAAU,sBAAsB,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,EACjE,oEAAoE;YAClE,oBAAoB,CACvB,EACD,IAAI,CACL,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,kCAAkC,KAAK,GAAG,CAAC,CAAC;AACvE,CAAC","sourcesContent":["import type { CliContext } from '../context';\nimport { validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { loadProject } from '../project';\nimport { assertSchemaNotSkewed } from '../schema-skew';\nimport { announceUpdate, checkForUpdate } from '../update-notice';\nimport { collectAllFindings } from '../validate-findings';\n\nexport interface ValidateArgs {\n  /** Project directory (contains ekanos.json). Defaults to cwd. */\n  dir: string;\n  env?: Record<string, string | undefined>;\n}\n\n/**\n * `validate` — parse the declaration with the REAL zod schemas from\n * `@ekanos/integration-schema` (never a reimplementation), gather structured\n * findings, and add project-level integrity checks (the vitest inline-SDK\n * check). Exit 0 with `findings: []` when clean; exit 3 when any error-severity\n * finding is present, with the findings carried in the envelope's `data`.\n *\n * The findings pass itself lives in `validate-findings.ts`, shared with\n * `publish` so the publish gate cannot drift from what validate checks.\n *\n * Runs the schema-skew gate FIRST, before anything else — see\n * `schema-skew.ts` for why a newer project schema than the CLI bundles makes\n * every finding below it unreliable.\n */\nexport async function runValidate(\n  ctx: CliContext,\n  args: ValidateArgs,\n): Promise<ExitCode> {\n  const loaded = loadProject(args.dir);\n\n  const skew = assertSchemaNotSkewed(ctx, loaded.projectDir);\n\n  const notice = await checkForUpdate({ env: args.env ?? process.env });\n  announceUpdate(ctx, notice);\n\n  const slugs = loaded.integrations.map((i) => i.slug).join(', ');\n  ctx.log(\n    `Validating ${loaded.integrations.length} integration` +\n      `${loaded.integrations.length === 1 ? '' : 's'} (${slugs})…`,\n  );\n\n  const findings = await collectAllFindings(loaded);\n\n  const errorCount = findings.filter((f) => f.severity === 'error').length;\n  const data = {\n    slug: loaded.primary.slug,\n    integrations: loaded.integrations.map((i) => ({\n      slug: i.slug,\n      entry: i.entry,\n    })),\n    findings,\n    ...(skew.status === 'project-older'\n      ? {\n          schemaSkew: {\n            status: skew.status,\n            cliSchemaVersion: skew.cliSchemaVersion,\n            projectSchemaVersion: skew.projectSchemaVersion,\n          },\n        }\n      : {}),\n    ...(notice ? { toolchain: notice } : {}),\n  };\n\n  if (errorCount > 0) {\n    return ctx.fail(\n      validationError(\n        `${errorCount} validation finding${errorCount === 1 ? '' : 's'}.`,\n        'Resolve the error-severity findings in data.findings, then re-run ' +\n          '\"ekanos validate\".',\n      ),\n      data,\n    );\n  }\n\n  return ctx.succeed(data, `validate: OK — no findings for ${slugs}.`);\n}\n"]}

package/dist/commands/whoami.d.ts

@@ -16,5 +16,11 @@ export interface WhoamiArgs {
  *
  * Exit 4 (auth_required) when there is no session or it cannot be renewed —
  * the code a script should branch on to decide whether to run `ekanos login`.
+ *
+ * `seats` is a best-effort add-on from the same source-visibility endpoint
+ * `ekanos sources` uses, compacted to slug+roles. Its failure — network, MFA,
+ * a deployment that predates the route — must never turn a working `whoami`
+ * into a failing one, so any error here degrades to `seats: null` rather than
+ * propagating.
  */
 export declare function runWhoami(ctx: CliContext, args: WhoamiArgs): Promise<ExitCode>;

package/dist/commands/whoami.js

@@ -1,4 +1,5 @@
 import { requireSession, resolveAuthEnvironment, resolveIdentity, } from '../auth/session.js';
+import { fetchSeatsWithOneRefresh } from '../seats.js';
 /**
  * `whoami` — prove the stored session still authenticates against Fusion.
  *
@@ -9,6 +10,12 @@ import { requireSession, resolveAuthEnvironment, resolveIdentity, } from '../aut
  *
  * Exit 4 (auth_required) when there is no session or it cannot be renewed —
  * the code a script should branch on to decide whether to run `ekanos login`.
+ *
+ * `seats` is a best-effort add-on from the same source-visibility endpoint
+ * `ekanos sources` uses, compacted to slug+roles. Its failure — network, MFA,
+ * a deployment that predates the route — must never turn a working `whoami`
+ * into a failing one, so any error here degrades to `seats: null` rather than
+ * propagating.
  */
 export async function runWhoami(ctx, args) {
     var _a;
@@ -17,6 +24,7 @@ export async function runWhoami(ctx, args) {
     });
     const stored = requireSession(env.store, env.host);
     const { identity, session } = await resolveIdentity(env, stored);
+    const seats = await fetchSeatsQuietly(env, session);
     return ctx.succeed({
         host: env.host,
         user: {
@@ -26,6 +34,23 @@ export async function runWhoami(ctx, args) {
         },
         expiresAt: session.expiresAt,
         credentialsPath: env.store.filePath,
-    }, `whoami: ${(_a = identity.email) !== null && _a !== void 0 ? _a : identity.id} on ${env.host}.`);
+        seats,
+    }, `whoami: ${(_a = identity.email) !== null && _a !== void 0 ? _a : identity.id} on ${env.host}.` +
+        (seats
+            ? seats.length > 0
+                ? ` Seats: ${seats.map((s) => `${s.slug} [${s.roles.join(', ')}]`).join(', ')}.`
+                : ' No source seats.'
+            : ' (source seat lookup unavailable)'));
+}
+async function fetchSeatsQuietly(env, session) {
+    try {
+        const result = await fetchSeatsWithOneRefresh(env, session);
+        if (result.status !== 'ok')
+            return null;
+        return result.sources.map((s) => ({ slug: s.slug, roles: s.roles }));
+    }
+    catch (_a) {
+        return null;
+    }
 }
 //# sourceMappingURL=whoami.js.map

package/dist/commands/whoami.js.map

@@ -1 +1 @@
-{"version":3,"file":"whoami.js","sourceRoot":"","sources":["../../src/commands/whoami.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAWzB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAe,EACf,IAAgB;;IAEhB,MAAM,GAAG,GAAG,sBAAsB,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE;QAC3D,UAAU,EAAE,IAAI,CAAC,GAAG;KACrB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEjE,OAAO,GAAG,CAAC,OAAO,CAChB;QACE,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE;YACJ,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI;SACpB;QACD,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ;KACpC,EACD,WAAW,MAAA,QAAQ,CAAC,KAAK,mCAAI,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,GAAG,CAC3D,CAAC;AACJ,CAAC","sourcesContent":["import {\n  requireSession,\n  resolveAuthEnvironment,\n  resolveIdentity,\n} from '../auth/session';\nimport type { CliContext } from '../context';\nimport type { ExitCode } from '../exit-codes';\n\nexport interface WhoamiArgs {\n  host?: string;\n  /** Where a project's ekanos.json may sit, for its optional `host` field. */\n  cwd: string;\n  env: Record<string, string | undefined>;\n}\n\n/**\n * `whoami` — prove the stored session still authenticates against Fusion.\n *\n * The identity is resolved server-side by `/api/auth/cli-whoami`, which reads\n * the account through RLS as the caller. Printing the locally cached email\n * would be a cheaper lie: it would keep saying \"logged in\" after the account\n * was deleted or the token revoked.\n *\n * Exit 4 (auth_required) when there is no session or it cannot be renewed —\n * the code a script should branch on to decide whether to run `ekanos login`.\n */\nexport async function runWhoami(\n  ctx: CliContext,\n  args: WhoamiArgs,\n): Promise<ExitCode> {\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.cwd,\n  });\n  const stored = requireSession(env.store, env.host);\n\n  const { identity, session } = await resolveIdentity(env, stored);\n\n  return ctx.succeed(\n    {\n      host: env.host,\n      user: {\n        id: identity.id,\n        email: identity.email,\n        name: identity.name,\n      },\n      expiresAt: session.expiresAt,\n      credentialsPath: env.store.filePath,\n    },\n    `whoami: ${identity.email ?? identity.id} on ${env.host}.`,\n  );\n}\n"]}
+{"version":3,"file":"whoami.js","sourceRoot":"","sources":["../../src/commands/whoami.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AASpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAe,EACf,IAAgB;;IAEhB,MAAM,GAAG,GAAG,sBAAsB,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE;QAC3D,UAAU,EAAE,IAAI,CAAC,GAAG;KACrB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEjE,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAEpD,OAAO,GAAG,CAAC,OAAO,CAChB;QACE,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE;YACJ,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI;SACpB;QACD,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ;QACnC,KAAK;KACN,EACD,WAAW,MAAA,QAAQ,CAAC,KAAK,mCAAI,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,GAAG;QACxD,CAAC,KAAK;YACJ,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAChB,CAAC,CAAC,WAAW,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAChF,CAAC,CAAC,mBAAmB;YACvB,CAAC,CAAC,mCAAmC,CAAC,CAC3C,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,iBAAiB,CAC9B,GAAmD,EACnD,OAAuD;IAEvD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,wBAAwB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAE5D,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAExC,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACvE,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import {\n  requireSession,\n  resolveAuthEnvironment,\n  resolveIdentity,\n} from '../auth/session';\nimport type { CliContext } from '../context';\nimport type { ExitCode } from '../exit-codes';\nimport { fetchSeatsWithOneRefresh } from '../seats';\n\nexport interface WhoamiArgs {\n  host?: string;\n  /** Where a project's ekanos.json may sit, for its optional `host` field. */\n  cwd: string;\n  env: Record<string, string | undefined>;\n}\n\n/**\n * `whoami` — prove the stored session still authenticates against Fusion.\n *\n * The identity is resolved server-side by `/api/auth/cli-whoami`, which reads\n * the account through RLS as the caller. Printing the locally cached email\n * would be a cheaper lie: it would keep saying \"logged in\" after the account\n * was deleted or the token revoked.\n *\n * Exit 4 (auth_required) when there is no session or it cannot be renewed —\n * the code a script should branch on to decide whether to run `ekanos login`.\n *\n * `seats` is a best-effort add-on from the same source-visibility endpoint\n * `ekanos sources` uses, compacted to slug+roles. Its failure — network, MFA,\n * a deployment that predates the route — must never turn a working `whoami`\n * into a failing one, so any error here degrades to `seats: null` rather than\n * propagating.\n */\nexport async function runWhoami(\n  ctx: CliContext,\n  args: WhoamiArgs,\n): Promise<ExitCode> {\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.cwd,\n  });\n  const stored = requireSession(env.store, env.host);\n\n  const { identity, session } = await resolveIdentity(env, stored);\n\n  const seats = await fetchSeatsQuietly(env, session);\n\n  return ctx.succeed(\n    {\n      host: env.host,\n      user: {\n        id: identity.id,\n        email: identity.email,\n        name: identity.name,\n      },\n      expiresAt: session.expiresAt,\n      credentialsPath: env.store.filePath,\n      seats,\n    },\n    `whoami: ${identity.email ?? identity.id} on ${env.host}.` +\n      (seats\n        ? seats.length > 0\n          ? ` Seats: ${seats.map((s) => `${s.slug} [${s.roles.join(', ')}]`).join(', ')}.`\n          : ' No source seats.'\n        : ' (source seat lookup unavailable)'),\n  );\n}\n\nasync function fetchSeatsQuietly(\n  env: Parameters<typeof fetchSeatsWithOneRefresh>[0],\n  session: Parameters<typeof fetchSeatsWithOneRefresh>[1],\n): Promise<{ slug: string; roles: string[] }[] | null> {\n  try {\n    const result = await fetchSeatsWithOneRefresh(env, session);\n\n    if (result.status !== 'ok') return null;\n\n    return result.sources.map((s) => ({ slug: s.slug, roles: s.roles }));\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/context.d.ts

@@ -20,6 +20,15 @@ export interface ContextInput {
     /** Overrides process.env for CLAUDECODE detection (tests). */
     env?: Record<string, string | undefined>;
 }
+/**
+ * `data` is deliberately `unknown` above — each verb owns its own shape — but
+ * one convention spans several of them: `validate`, `dev`, `publish` and
+ * `status` all add an OPTIONAL `toolchain` field to `data` (never to the
+ * envelope's top level) when the proactive update check in `update-notice.ts`
+ * finds this CLI is behind. See that file's `ToolchainNoticeData` for the
+ * shape, and `README.md`'s "Keeping the toolchain current" section for the
+ * full contract. It is absent, not `null`, when there is nothing to report.
+ */
 /**
  * The agent-native output envelope, resolved ONCE at startup and threaded
  * through every command.

package/dist/context.js

@@ -1,4 +1,13 @@
 import { EXIT_CODES } from './exit-codes.js';
+/**
+ * `data` is deliberately `unknown` above — each verb owns its own shape — but
+ * one convention spans several of them: `validate`, `dev`, `publish` and
+ * `status` all add an OPTIONAL `toolchain` field to `data` (never to the
+ * envelope's top level) when the proactive update check in `update-notice.ts`
+ * finds this CLI is behind. See that file's `ToolchainNoticeData` for the
+ * shape, and `README.md`'s "Keeping the toolchain current" section for the
+ * full contract. It is absent, not `null`, when there is nothing to report.
+ */
 /**
  * The agent-native output envelope, resolved ONCE at startup and threaded
  * through every command.

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["import { CliError } from './errors';\nimport { EXIT_CODES, type ExitCode } from './exit-codes';\n\n/**\n * A single writable sink. Real streams satisfy this; tests pass a capturing\n * buffer so the stdout-purity invariant can be asserted byte-for-byte.\n */\nexport interface WriteStream {\n  write(chunk: string): void;\n  isTTY?: boolean;\n}\n\nexport interface ContextInput {\n  /**\n   * The user's EXPLICIT preference, already parsed: `true` for `--json`,\n   * `false` for `--no-json`, `undefined` when neither was passed. The\n   * undefined case is what allows the mode to be inferred instead.\n   */\n  jsonFlag?: boolean;\n  stdout?: WriteStream;\n  stderr?: WriteStream;\n  /** Overrides process.env for CLAUDECODE detection (tests). */\n  env?: Record<string, string | undefined>;\n}\n\n/** The success envelope. */\ninterface OkEnvelope {\n  ok: true;\n  data: unknown;\n}\n\n/** The error envelope. `data` is optional — validate carries its findings here. */\ninterface ErrEnvelope {\n  ok: false;\n  data?: unknown;\n  error: { code: string; message: string; hint: string };\n}\n\n/**\n * The agent-native output envelope, resolved ONCE at startup and threaded\n * through every command.\n *\n * The load-bearing invariant: in JSON mode, stdout receives EXACTLY ONE JSON\n * object for the whole process — nothing else, ever. Every progress line, warn,\n * and scrap of human prose goes to stderr. This is the single most common way\n * an agent's tool call breaks (a stray log line on stdout makes the JSON\n * unparseable), so the context enforces it structurally: `succeed`/`fail` are\n * the only writers of stdout, and a `settled` latch makes a second call throw\n * rather than emit a second object.\n */\nexport class CliContext {\n  readonly jsonMode: boolean;\n  /**\n   * The environment the context resolved against — exposed so decoration\n   * (the gradient banner) can honour `NO_COLOR` / `EKANOS_NO_BANNER` without\n   * every call site threading `process.env` through by hand.\n   */\n  readonly env: Readonly<Record<string, string | undefined>>;\n  private readonly stdout: WriteStream;\n  private readonly stderr: WriteStream;\n  private settled = false;\n\n  constructor(input: ContextInput = {}) {\n    const stdout = input.stdout ?? defaultStream(process.stdout);\n    const stderr = input.stderr ?? defaultStream(process.stderr);\n    const env = input.env ?? process.env;\n\n    this.stdout = stdout;\n    this.stderr = stderr;\n    this.env = env;\n\n    // Resolve JSON mode once. An EXPLICIT flag always wins: `--json` forces the\n    // envelope on even at a terminal, `--no-json` forces the human form even\n    // when piped. Only when the user expressed no preference is the mode\n    // inferred — from a non-TTY stdout (piped into another program or an agent)\n    // or the CLAUDECODE marker.\n    const nonTty = stdout.isTTY !== true;\n    this.jsonMode = input.jsonFlag ?? (nonTty || env.CLAUDECODE === '1');\n  }\n\n  /** Whether stderr is a real terminal — decoration (the banner) gates on this. */\n  get stderrIsTTY(): boolean {\n    return this.stderr.isTTY === true;\n  }\n\n  /** Human/progress output — ALWAYS stderr, so stdout stays pure in JSON mode. */\n  log(message: string): void {\n    this.stderr.write(`${message}\\n`);\n  }\n\n  /** A warning — stderr, no ANSI. */\n  warn(message: string): void {\n    this.stderr.write(`${message}\\n`);\n  }\n\n  /**\n   * Emit the `claude-code-hint` protocol line to STDERR. Used on --help and on\n   * an unknown command so an agent reading stderr is told what to do next\n   * without the line ever touching stdout.\n   */\n  emitClaudeCodeHint(payload: Record<string, unknown>): void {\n    this.stderr.write(`claude-code-hint: ${JSON.stringify(payload)}\\n`);\n  }\n\n  /**\n   * Terminal success. Writes the single stdout object (JSON mode) or a concise\n   * human line (human mode). Returns the OK exit code so the caller can end the\n   * process with it. Idempotent-by-latch: a second settle throws.\n   */\n  succeed(data: unknown, humanSummary?: string): ExitCode {\n    this.settle();\n    if (this.jsonMode) {\n      const envelope: OkEnvelope = { ok: true, data };\n      this.stdout.write(`${JSON.stringify(envelope)}\\n`);\n    } else {\n      this.stdout.write(`${humanSummary ?? 'OK'}\\n`);\n    }\n    return EXIT_CODES.OK;\n  }\n\n  /**\n   * Terminal failure. Writes the single stdout error object (JSON mode) or the\n   * message + hint to stderr (human mode). Returns the error's exit code.\n   *\n   * `error.hint` is guaranteed non-empty by CliError's constructor, so the\n   * envelope's \"every error carries a hint\" invariant holds for every path\n   * that reaches here.\n   */\n  fail(error: CliError, data?: unknown): ExitCode {\n    this.failWith({\n      code: error.code,\n      message: error.message,\n      hint: error.hint,\n      exitCode: error.exitCode,\n      data,\n    });\n    return error.exitCode;\n  }\n\n  /**\n   * The low-level failure emitter. Used directly by `test`, whose exit code is\n   * a TRANSPARENT passthrough of the delegated runner's exit code (which is not\n   * one of the CLI's own frozen numeric conditions) and whose error `code` is\n   * an out-of-taxonomy string. Enforces the same non-empty-hint invariant as\n   * CliError so no failure path can emit an empty hint.\n   */\n  failWith(params: {\n    code: string;\n    message: string;\n    hint: string;\n    exitCode: number;\n    data?: unknown;\n  }): number {\n    this.settle();\n    if (!params.hint || params.hint.trim().length === 0) {\n      throw new Error(\n        `failWith for \"${params.message}\" was given an empty hint. Every CLI ` +\n          'error must carry an imperative remediation.',\n      );\n    }\n    if (this.jsonMode) {\n      const envelope: ErrEnvelope = {\n        ok: false,\n        ...(params.data !== undefined ? { data: params.data } : {}),\n        error: {\n          code: params.code,\n          message: params.message,\n          hint: params.hint,\n        },\n      };\n      this.stdout.write(`${JSON.stringify(envelope)}\\n`);\n    } else {\n      this.stderr.write(`Error: ${params.message}\\n`);\n      this.stderr.write(`Hint: ${params.hint}\\n`);\n    }\n    return params.exitCode;\n  }\n\n  private settle(): void {\n    if (this.settled) {\n      throw new Error(\n        'CliContext settled twice — a command tried to emit a second ' +\n          'terminal result. In JSON mode this would corrupt stdout with two ' +\n          'objects. This is a bug in the command.',\n      );\n    }\n    this.settled = true;\n  }\n}\n\nfunction defaultStream(stream: NodeJS.WriteStream): WriteStream {\n  return {\n    write: (chunk: string) => {\n      stream.write(chunk);\n    },\n    isTTY: stream.isTTY,\n  };\n}\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAiB,MAAM,cAAc,CAAC;AAqCzD;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,UAAU;IAYrB,YAAY,QAAsB,EAAE;;QAF5B,YAAO,GAAG,KAAK,CAAC;QAGtB,MAAM,MAAM,GAAG,MAAA,KAAK,CAAC,MAAM,mCAAI,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,MAAA,KAAK,CAAC,MAAM,mCAAI,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7D,MAAM,GAAG,GAAG,MAAA,KAAK,CAAC,GAAG,mCAAI,OAAO,CAAC,GAAG,CAAC;QAErC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QAEf,4EAA4E;QAC5E,yEAAyE;QACzE,qEAAqE;QACrE,4EAA4E;QAC5E,4BAA4B;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,MAAA,KAAK,CAAC,QAAQ,mCAAI,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC;IACvE,CAAC;IAED,iFAAiF;IACjF,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;IACpC,CAAC;IAED,gFAAgF;IAChF,GAAG,CAAC,OAAe;QACjB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,mCAAmC;IACnC,IAAI,CAAC,OAAe;QAClB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,OAAgC;QACjD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAa,EAAE,YAAqB;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,QAAQ,GAAe,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAChD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,aAAZ,YAAY,cAAZ,YAAY,GAAI,IAAI,IAAI,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,UAAU,CAAC,EAAE,CAAC;IACvB,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,KAAe,EAAE,IAAc;QAClC,IAAI,CAAC,QAAQ,CAAC;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,IAAI;SACL,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,QAAQ,CAAC;IACxB,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,MAMR;QACC,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,OAAO,uCAAuC;gBACpE,6CAA6C,CAChD,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,QAAQ,iCACZ,EAAE,EAAE,KAAK,IACN,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAC3D,KAAK,EAAE;oBACL,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,IAAI,EAAE,MAAM,CAAC,IAAI;iBAClB,GACF,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YAChD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,MAAM,CAAC,QAAQ,CAAC;IACzB,CAAC;IAEO,MAAM;QACZ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,8DAA8D;gBAC5D,mEAAmE;gBACnE,wCAAwC,CAC3C,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;CACF;AAED,SAAS,aAAa,CAAC,MAA0B;IAC/C,OAAO;QACL,KAAK,EAAE,CAAC,KAAa,EAAE,EAAE;YACvB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC;AACJ,CAAC","sourcesContent":["import { CliError } from './errors';\nimport { EXIT_CODES, type ExitCode } from './exit-codes';\n\n/**\n * A single writable sink. Real streams satisfy this; tests pass a capturing\n * buffer so the stdout-purity invariant can be asserted byte-for-byte.\n */\nexport interface WriteStream {\n  write(chunk: string): void;\n  isTTY?: boolean;\n}\n\nexport interface ContextInput {\n  /**\n   * The user's EXPLICIT preference, already parsed: `true` for `--json`,\n   * `false` for `--no-json`, `undefined` when neither was passed. The\n   * undefined case is what allows the mode to be inferred instead.\n   */\n  jsonFlag?: boolean;\n  stdout?: WriteStream;\n  stderr?: WriteStream;\n  /** Overrides process.env for CLAUDECODE detection (tests). */\n  env?: Record<string, string | undefined>;\n}\n\n/** The success envelope. */\ninterface OkEnvelope {\n  ok: true;\n  data: unknown;\n}\n\n/** The error envelope. `data` is optional — validate carries its findings here. */\ninterface ErrEnvelope {\n  ok: false;\n  data?: unknown;\n  error: { code: string; message: string; hint: string };\n}\n\n/**\n * `data` is deliberately `unknown` above — each verb owns its own shape — but\n * one convention spans several of them: `validate`, `dev`, `publish` and\n * `status` all add an OPTIONAL `toolchain` field to `data` (never to the\n * envelope's top level) when the proactive update check in `update-notice.ts`\n * finds this CLI is behind. See that file's `ToolchainNoticeData` for the\n * shape, and `README.md`'s \"Keeping the toolchain current\" section for the\n * full contract. It is absent, not `null`, when there is nothing to report.\n */\n\n/**\n * The agent-native output envelope, resolved ONCE at startup and threaded\n * through every command.\n *\n * The load-bearing invariant: in JSON mode, stdout receives EXACTLY ONE JSON\n * object for the whole process — nothing else, ever. Every progress line, warn,\n * and scrap of human prose goes to stderr. This is the single most common way\n * an agent's tool call breaks (a stray log line on stdout makes the JSON\n * unparseable), so the context enforces it structurally: `succeed`/`fail` are\n * the only writers of stdout, and a `settled` latch makes a second call throw\n * rather than emit a second object.\n */\nexport class CliContext {\n  readonly jsonMode: boolean;\n  /**\n   * The environment the context resolved against — exposed so decoration\n   * (the gradient banner) can honour `NO_COLOR` / `EKANOS_NO_BANNER` without\n   * every call site threading `process.env` through by hand.\n   */\n  readonly env: Readonly<Record<string, string | undefined>>;\n  private readonly stdout: WriteStream;\n  private readonly stderr: WriteStream;\n  private settled = false;\n\n  constructor(input: ContextInput = {}) {\n    const stdout = input.stdout ?? defaultStream(process.stdout);\n    const stderr = input.stderr ?? defaultStream(process.stderr);\n    const env = input.env ?? process.env;\n\n    this.stdout = stdout;\n    this.stderr = stderr;\n    this.env = env;\n\n    // Resolve JSON mode once. An EXPLICIT flag always wins: `--json` forces the\n    // envelope on even at a terminal, `--no-json` forces the human form even\n    // when piped. Only when the user expressed no preference is the mode\n    // inferred — from a non-TTY stdout (piped into another program or an agent)\n    // or the CLAUDECODE marker.\n    const nonTty = stdout.isTTY !== true;\n    this.jsonMode = input.jsonFlag ?? (nonTty || env.CLAUDECODE === '1');\n  }\n\n  /** Whether stderr is a real terminal — decoration (the banner) gates on this. */\n  get stderrIsTTY(): boolean {\n    return this.stderr.isTTY === true;\n  }\n\n  /** Human/progress output — ALWAYS stderr, so stdout stays pure in JSON mode. */\n  log(message: string): void {\n    this.stderr.write(`${message}\\n`);\n  }\n\n  /** A warning — stderr, no ANSI. */\n  warn(message: string): void {\n    this.stderr.write(`${message}\\n`);\n  }\n\n  /**\n   * Emit the `claude-code-hint` protocol line to STDERR. Used on --help and on\n   * an unknown command so an agent reading stderr is told what to do next\n   * without the line ever touching stdout.\n   */\n  emitClaudeCodeHint(payload: Record<string, unknown>): void {\n    this.stderr.write(`claude-code-hint: ${JSON.stringify(payload)}\\n`);\n  }\n\n  /**\n   * Terminal success. Writes the single stdout object (JSON mode) or a concise\n   * human line (human mode). Returns the OK exit code so the caller can end the\n   * process with it. Idempotent-by-latch: a second settle throws.\n   */\n  succeed(data: unknown, humanSummary?: string): ExitCode {\n    this.settle();\n    if (this.jsonMode) {\n      const envelope: OkEnvelope = { ok: true, data };\n      this.stdout.write(`${JSON.stringify(envelope)}\\n`);\n    } else {\n      this.stdout.write(`${humanSummary ?? 'OK'}\\n`);\n    }\n    return EXIT_CODES.OK;\n  }\n\n  /**\n   * Terminal failure. Writes the single stdout error object (JSON mode) or the\n   * message + hint to stderr (human mode). Returns the error's exit code.\n   *\n   * `error.hint` is guaranteed non-empty by CliError's constructor, so the\n   * envelope's \"every error carries a hint\" invariant holds for every path\n   * that reaches here.\n   */\n  fail(error: CliError, data?: unknown): ExitCode {\n    this.failWith({\n      code: error.code,\n      message: error.message,\n      hint: error.hint,\n      exitCode: error.exitCode,\n      data,\n    });\n    return error.exitCode;\n  }\n\n  /**\n   * The low-level failure emitter. Used directly by `test`, whose exit code is\n   * a TRANSPARENT passthrough of the delegated runner's exit code (which is not\n   * one of the CLI's own frozen numeric conditions) and whose error `code` is\n   * an out-of-taxonomy string. Enforces the same non-empty-hint invariant as\n   * CliError so no failure path can emit an empty hint.\n   */\n  failWith(params: {\n    code: string;\n    message: string;\n    hint: string;\n    exitCode: number;\n    data?: unknown;\n  }): number {\n    this.settle();\n    if (!params.hint || params.hint.trim().length === 0) {\n      throw new Error(\n        `failWith for \"${params.message}\" was given an empty hint. Every CLI ` +\n          'error must carry an imperative remediation.',\n      );\n    }\n    if (this.jsonMode) {\n      const envelope: ErrEnvelope = {\n        ok: false,\n        ...(params.data !== undefined ? { data: params.data } : {}),\n        error: {\n          code: params.code,\n          message: params.message,\n          hint: params.hint,\n        },\n      };\n      this.stdout.write(`${JSON.stringify(envelope)}\\n`);\n    } else {\n      this.stderr.write(`Error: ${params.message}\\n`);\n      this.stderr.write(`Hint: ${params.hint}\\n`);\n    }\n    return params.exitCode;\n  }\n\n  private settle(): void {\n    if (this.settled) {\n      throw new Error(\n        'CliContext settled twice — a command tried to emit a second ' +\n          'terminal result. In JSON mode this would corrupt stdout with two ' +\n          'objects. This is a bug in the command.',\n      );\n    }\n    this.settled = true;\n  }\n}\n\nfunction defaultStream(stream: NodeJS.WriteStream): WriteStream {\n  return {\n    write: (chunk: string) => {\n      stream.write(chunk);\n    },\n    isTTY: stream.isTTY,\n  };\n}\n"]}

package/dist/delegate.d.ts

@@ -0,0 +1,28 @@
+import { spawn } from 'node:child_process';
+export interface DelegationPlan {
+    shouldDelegate: boolean;
+    ownVersion: string;
+    localVersion?: string;
+    /** Absolute path to the local CLI's bin entry, when `shouldDelegate`. */
+    localBinPath?: string;
+}
+/**
+ * Decide whether this invocation should delegate. Pure and side-effect-free
+ * (beyond the one file read of the local `@ekanos/cli` manifest, mirroring
+ * `readInstalledHarness`/`dev`'s own project-package resolution rather than
+ * writing a second one) so it is directly testable without spawning anything.
+ */
+export declare function planDelegation(argv: readonly string[], env: Record<string, string | undefined>, cwd: string): DelegationPlan;
+/**
+ * The one-line stderr announcement — human mode only, and NEVER on stdout
+ * (a delegated `validate --json` must still emit exactly one JSON object on
+ * stdout, from the CHILD, with nothing of ours ahead of it).
+ */
+export declare function announceDelegation(plan: DelegationPlan, argv: readonly string[], env: Record<string, string | undefined>, stdoutIsTTY: boolean): void;
+/**
+ * Spawn the local CLI's own bin entry with the SAME node executable,
+ * `stdio: 'inherit'` so the JSON envelope and banner gating are
+ * byte-identical to a direct run, and propagate its exit code exactly.
+ * `spawnFn` is injectable so tests never actually fork a process.
+ */
+export declare function delegate(plan: DelegationPlan, argv: readonly string[], env: NodeJS.ProcessEnv, spawnFn?: typeof spawn): Promise<number>;

package/dist/delegate.js

@@ -0,0 +1,136 @@
+import { spawn } from 'node:child_process';
+import * as path from 'node:path';
+import { cliVersion } from './compatibility.js';
+import { readInstalledPackageManifest } from './harness-scaffold.js';
+/**
+ * Wrapper-style delegation to the project-local `@ekanos/cli` — the
+ * Gradle-wrapper / Yarn / `npx` pattern, applied to this CLI.
+ *
+ * A global install bundles ONE `@ekanos/integration-schema` version but
+ * routinely serves N projects on different `@ekanos/sdk` versions — it
+ * cannot be correct for all of them simultaneously (this is exactly the
+ * failure mode `schema-skew.ts` detects). Delegation dissolves the tension:
+ * `ekanos` stays on PATH for convenience, but the four verbs that actually
+ * read or generate project files always run through the project's OWN
+ * pinned copy when one is installed and differs from the invoked binary.
+ *
+ * Machine-level verbs (`init`, `login`, `logout`, `whoami`, `sources`,
+ * `use`, `status`, `upgrade`) are deliberately NEVER delegated: you never
+ * want an old local copy handling credentials, and `upgrade` must always be
+ * the newest logic doing the upgrading — delegating it could have an old CLI
+ * "upgrade" a project using its own out-of-date resolution.
+ */
+const DELEGATABLE_VERBS = new Set(['validate', 'publish', 'dev', 'test']);
+/** The first bare (non-flag) token before a standalone `--` — mirrors `splitCommand` in `index.ts`. */
+function firstCommand(argv) {
+    for (const token of argv) {
+        if (token === '--')
+            break;
+        if (!token.startsWith('-'))
+            return token;
+    }
+    return null;
+}
+/** `--dir <path>` / `--dir=<path>`, before a standalone `--`. */
+function scanDirFlag(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--')
+            break;
+        if (token === '--dir')
+            return argv[i + 1];
+        if (token.startsWith('--dir='))
+            return token.slice('--dir='.length);
+    }
+    return undefined;
+}
+/**
+ * Decide whether this invocation should delegate. Pure and side-effect-free
+ * (beyond the one file read of the local `@ekanos/cli` manifest, mirroring
+ * `readInstalledHarness`/`dev`'s own project-package resolution rather than
+ * writing a second one) so it is directly testable without spawning anything.
+ */
+export function planDelegation(argv, env, cwd) {
+    var _a;
+    const ownVersion = cliVersion();
+    // The recursion guard, and the explicit escape hatch, both win outright.
+    if (env.EKANOS_DELEGATED === '1' || env.EKANOS_NO_DELEGATE === '1') {
+        return { shouldDelegate: false, ownVersion };
+    }
+    const command = firstCommand(argv);
+    if (!command || !DELEGATABLE_VERBS.has(command)) {
+        return { shouldDelegate: false, ownVersion };
+    }
+    const projectDir = path.resolve(cwd, (_a = scanDirFlag(argv)) !== null && _a !== void 0 ? _a : '.');
+    // Best-effort, like every other resolution this function does: a corrupt
+    // local manifest must fall through to "don't delegate", never throw. This
+    // runs in `bin.ts` BEFORE `run()`'s try/catch exists, so an uncaught throw
+    // here would bypass the JSON-envelope error machinery entirely and print a
+    // raw stderr string instead — a real regression in the "exactly one
+    // terminal emission" contract the rest of this package guarantees.
+    let local = null;
+    try {
+        local = readInstalledPackageManifest(projectDir, '@ekanos/cli');
+    }
+    catch (_b) {
+        local = null;
+    }
+    if (!local || local.version === ownVersion) {
+        return { shouldDelegate: false, ownVersion, localVersion: local === null || local === void 0 ? void 0 : local.version };
+    }
+    return {
+        shouldDelegate: true,
+        ownVersion,
+        localVersion: local.version,
+        localBinPath: path.join(projectDir, 'node_modules', '@ekanos', 'cli', 'dist', 'bin.js'),
+    };
+}
+/**
+ * Same JSON-mode inference `CliContext` uses (`context.ts`) — duplicated
+ * deliberately rather than shared, because this runs BEFORE a `CliContext`
+ * exists (delegation is decided ahead of the whole `run()` machinery). Keep
+ * this in sync with `CliContext`'s constructor if that heuristic ever
+ * changes: an explicit `--json`/`--no-json` wins, otherwise a non-TTY stdout
+ * or `CLAUDECODE=1` means JSON mode.
+ */
+function looksLikeJsonMode(argv, env, stdoutIsTTY) {
+    for (const token of argv) {
+        if (token === '--')
+            break;
+        if (token === '--json')
+            return true;
+        if (token === '--no-json')
+            return false;
+    }
+    return !stdoutIsTTY || env.CLAUDECODE === '1';
+}
+/**
+ * The one-line stderr announcement — human mode only, and NEVER on stdout
+ * (a delegated `validate --json` must still emit exactly one JSON object on
+ * stdout, from the CHILD, with nothing of ours ahead of it).
+ */
+export function announceDelegation(plan, argv, env, stdoutIsTTY) {
+    if (!plan.shouldDelegate)
+        return;
+    if (looksLikeJsonMode(argv, env, stdoutIsTTY))
+        return;
+    process.stderr.write(`ekanos: using this project's pinned CLI ${plan.localVersion} (global: ` +
+        `${plan.ownVersion}). Set EKANOS_NO_DELEGATE=1 to bypass.\n`);
+}
+/**
+ * Spawn the local CLI's own bin entry with the SAME node executable,
+ * `stdio: 'inherit'` so the JSON envelope and banner gating are
+ * byte-identical to a direct run, and propagate its exit code exactly.
+ * `spawnFn` is injectable so tests never actually fork a process.
+ */
+export function delegate(plan, argv, env, spawnFn = spawn) {
+    return new Promise((resolve) => {
+        const child = spawnFn(process.execPath, [plan.localBinPath, ...argv], {
+            stdio: 'inherit',
+            env: Object.assign(Object.assign({}, env), { EKANOS_DELEGATED: '1' }),
+        });
+        child.on('error', () => resolve(1));
+        child.on('exit', (code) => resolve(code !== null && code !== void 0 ? code : 1));
+    });
+}
+//# sourceMappingURL=delegate.js.map

package/dist/delegate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.js","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport * as path from 'node:path';\n\nimport { cliVersion } from './compatibility';\nimport { readInstalledPackageManifest } from './harness-scaffold';\n\n/**\n * Wrapper-style delegation to the project-local `@ekanos/cli` — the\n * Gradle-wrapper / Yarn / `npx` pattern, applied to this CLI.\n *\n * A global install bundles ONE `@ekanos/integration-schema` version but\n * routinely serves N projects on different `@ekanos/sdk` versions — it\n * cannot be correct for all of them simultaneously (this is exactly the\n * failure mode `schema-skew.ts` detects). Delegation dissolves the tension:\n * `ekanos` stays on PATH for convenience, but the four verbs that actually\n * read or generate project files always run through the project's OWN\n * pinned copy when one is installed and differs from the invoked binary.\n *\n * Machine-level verbs (`init`, `login`, `logout`, `whoami`, `sources`,\n * `use`, `status`, `upgrade`) are deliberately NEVER delegated: you never\n * want an old local copy handling credentials, and `upgrade` must always be\n * the newest logic doing the upgrading — delegating it could have an old CLI\n * \"upgrade\" a project using its own out-of-date resolution.\n */\n\nconst DELEGATABLE_VERBS = new Set(['validate', 'publish', 'dev', 'test']);\n\nexport interface DelegationPlan {\n  shouldDelegate: boolean;\n  ownVersion: string;\n  localVersion?: string;\n  /** Absolute path to the local CLI's bin entry, when `shouldDelegate`. */\n  localBinPath?: string;\n}\n\n/** The first bare (non-flag) token before a standalone `--` — mirrors `splitCommand` in `index.ts`. */\nfunction firstCommand(argv: readonly string[]): string | null {\n  for (const token of argv) {\n    if (token === '--') break;\n    if (!token.startsWith('-')) return token;\n  }\n  return null;\n}\n\n/** `--dir <path>` / `--dir=<path>`, before a standalone `--`. */\nfunction scanDirFlag(argv: readonly string[]): string | undefined {\n  for (let i = 0; i < argv.length; i++) {\n    const token = argv[i]!;\n    if (token === '--') break;\n    if (token === '--dir') return argv[i + 1];\n    if (token.startsWith('--dir=')) return token.slice('--dir='.length);\n  }\n  return undefined;\n}\n\n/**\n * Decide whether this invocation should delegate. Pure and side-effect-free\n * (beyond the one file read of the local `@ekanos/cli` manifest, mirroring\n * `readInstalledHarness`/`dev`'s own project-package resolution rather than\n * writing a second one) so it is directly testable without spawning anything.\n */\nexport function planDelegation(\n  argv: readonly string[],\n  env: Record<string, string | undefined>,\n  cwd: string,\n): DelegationPlan {\n  const ownVersion = cliVersion();\n\n  // The recursion guard, and the explicit escape hatch, both win outright.\n  if (env.EKANOS_DELEGATED === '1' || env.EKANOS_NO_DELEGATE === '1') {\n    return { shouldDelegate: false, ownVersion };\n  }\n\n  const command = firstCommand(argv);\n  if (!command || !DELEGATABLE_VERBS.has(command)) {\n    return { shouldDelegate: false, ownVersion };\n  }\n\n  const projectDir = path.resolve(cwd, scanDirFlag(argv) ?? '.');\n  // Best-effort, like every other resolution this function does: a corrupt\n  // local manifest must fall through to \"don't delegate\", never throw. This\n  // runs in `bin.ts` BEFORE `run()`'s try/catch exists, so an uncaught throw\n  // here would bypass the JSON-envelope error machinery entirely and print a\n  // raw stderr string instead — a real regression in the \"exactly one\n  // terminal emission\" contract the rest of this package guarantees.\n  let local: ReturnType<typeof readInstalledPackageManifest> = null;\n  try {\n    local = readInstalledPackageManifest(projectDir, '@ekanos/cli');\n  } catch {\n    local = null;\n  }\n\n  if (!local || local.version === ownVersion) {\n    return { shouldDelegate: false, ownVersion, localVersion: local?.version };\n  }\n\n  return {\n    shouldDelegate: true,\n    ownVersion,\n    localVersion: local.version,\n    localBinPath: path.join(\n      projectDir,\n      'node_modules',\n      '@ekanos',\n      'cli',\n      'dist',\n      'bin.js',\n    ),\n  };\n}\n\n/**\n * Same JSON-mode inference `CliContext` uses (`context.ts`) — duplicated\n * deliberately rather than shared, because this runs BEFORE a `CliContext`\n * exists (delegation is decided ahead of the whole `run()` machinery). Keep\n * this in sync with `CliContext`'s constructor if that heuristic ever\n * changes: an explicit `--json`/`--no-json` wins, otherwise a non-TTY stdout\n * or `CLAUDECODE=1` means JSON mode.\n */\nfunction looksLikeJsonMode(\n  argv: readonly string[],\n  env: Record<string, string | undefined>,\n  stdoutIsTTY: boolean,\n): boolean {\n  for (const token of argv) {\n    if (token === '--') break;\n    if (token === '--json') return true;\n    if (token === '--no-json') return false;\n  }\n  return !stdoutIsTTY || env.CLAUDECODE === '1';\n}\n\n/**\n * The one-line stderr announcement — human mode only, and NEVER on stdout\n * (a delegated `validate --json` must still emit exactly one JSON object on\n * stdout, from the CHILD, with nothing of ours ahead of it).\n */\nexport function announceDelegation(\n  plan: DelegationPlan,\n  argv: readonly string[],\n  env: Record<string, string | undefined>,\n  stdoutIsTTY: boolean,\n): void {\n  if (!plan.shouldDelegate) return;\n  if (looksLikeJsonMode(argv, env, stdoutIsTTY)) return;\n\n  process.stderr.write(\n    `ekanos: using this project's pinned CLI ${plan.localVersion} (global: ` +\n      `${plan.ownVersion}). Set EKANOS_NO_DELEGATE=1 to bypass.\\n`,\n  );\n}\n\n/**\n * Spawn the local CLI's own bin entry with the SAME node executable,\n * `stdio: 'inherit'` so the JSON envelope and banner gating are\n * byte-identical to a direct run, and propagate its exit code exactly.\n * `spawnFn` is injectable so tests never actually fork a process.\n */\nexport function delegate(\n  plan: DelegationPlan,\n  argv: readonly string[],\n  env: NodeJS.ProcessEnv,\n  spawnFn: typeof spawn = spawn,\n): Promise<number> {\n  return new Promise((resolve) => {\n    const child = spawnFn(process.execPath, [plan.localBinPath!, ...argv], {\n      stdio: 'inherit',\n      env: { ...env, EKANOS_DELEGATED: '1' },\n    });\n    child.on('error', () => resolve(1));\n    child.on('exit', (code) => resolve(code ?? 1));\n  });\n}\n"]}

package/dist/harness-scaffold.d.ts

@@ -44,16 +44,31 @@ export interface WrittenFiles {
     unchanged: string[];
 }
 /**
- * Read the installed `@ekanos/harness` version out of the partner's
- * `node_modules`. Resolved by path rather than `require.resolve` on purpose:
- * the CLI runs from its own install and must read the version of the copy in
- * THEIR project, not one hoisted next to itself.
+ * Read an installed package's `package.json` out of a project's TOP-LEVEL
+ * `node_modules`. Resolved by direct path join rather than `require.resolve`
+ * on purpose, for two independent reasons:
+ *
+ *  - The CLI runs from its own install and must read the version of the copy
+ *    in THE CALLER'S project, not one hoisted next to itself.
+ *  - Several of the packages this reads (`@ekanos/integration-schema`
+ *    included) declare an `exports` map with no `./package.json` subpath, so
+ *    `require.resolve('<pkg>/package.json')` throws
+ *    `ERR_PACKAGE_PATH_NOT_EXPORTED` under Node's ESM resolver. A plain file
+ *    read is not subject to the export map at all.
+ *
+ * Shared by every "what does this project have installed?" check in the
+ * CLI — `readInstalledHarness` below, the schema-skew gate, and `upgrade`'s
+ * current-toolchain report — so there is exactly one implementation of "read
+ * a package's on-disk version", not a subtly different one per call site.
  */
-export interface InstalledHarness {
+export interface InstalledPackage {
     version: string;
-    /** The raw package.json, so compatibility can read its `ekanos` block. */
+    /** The raw package.json, for callers that need more than the version. */
     manifest: unknown;
 }
+export declare function readInstalledPackageManifest(projectDir: string, packageName: string): InstalledPackage | null;
+/** Read the installed `@ekanos/harness` version out of the partner's project. */
+export type InstalledHarness = InstalledPackage;
 export declare function readInstalledHarness(projectDir: string): InstalledHarness | null;
 /** Just the installed version, for callers that need nothing else. */
 export declare function readInstalledHarnessVersion(projectDir: string): string | null;

package/dist/harness-scaffold.js

@@ -88,12 +88,12 @@ export const REQUIRED_DEPENDENCIES = [
     'tailwindcss',
     '@tailwindcss/postcss',
 ];
-export function readInstalledHarness(projectDir) {
-    const manifest = path.join(projectDir, 'node_modules', HARNESS_PACKAGE, 'package.json');
-    if (!fs.existsSync(manifest))
+export function readInstalledPackageManifest(projectDir, packageName) {
+    const manifestPath = path.join(projectDir, 'node_modules', ...packageName.split('/'), 'package.json');
+    if (!fs.existsSync(manifestPath))
         return null;
     try {
-        const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+        const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
         const version = typeof parsed === 'object' && parsed !== null
             ? parsed.version
             : undefined;
@@ -102,9 +102,12 @@ export function readInstalledHarness(projectDir) {
         return { version, manifest: parsed };
     }
     catch (error) {
-        throw preconditionError(`${HARNESS_PACKAGE}'s package.json in node_modules is unreadable: ${error instanceof Error ? error.message : String(error)}`, `Reinstall dependencies in ${projectDir} so ${HARNESS_PACKAGE} resolves.`);
+        throw preconditionError(`${packageName}'s package.json in node_modules is unreadable: ${error instanceof Error ? error.message : String(error)}`, `Reinstall dependencies in ${projectDir} so ${packageName} resolves.`);
     }
 }
+export function readInstalledHarness(projectDir) {
+    return readInstalledPackageManifest(projectDir, HARNESS_PACKAGE);
+}
 /** Just the installed version, for callers that need nothing else. */
 export function readInstalledHarnessVersion(projectDir) {
     var _a, _b;