@ekanos/cli 0.1.0

package/dist/commands/logout.js

@@ -0,0 +1,75 @@
+import { revokeRefreshToken } from '../auth/device-flow.js';
+import { fetchCliAuthConfig } from '../auth/fusion-api.js';
+import { newStore, resolveAuthEnvironment } from '../auth/session.js';
+/**
+ * `logout` — revoke the stored refresh token at Auth0, then delete it locally.
+ *
+ * Idempotent: logging out twice exits 0. `cleared: false` in the envelope says
+ * there was nothing to remove; it is information, not a failure.
+ *
+ * Revocation is attempted first but never blocks the local delete. A logout
+ * that only forgets the token would leave a rotating credential live for weeks;
+ * a logout that REFUSES because the network is down would leave the token on
+ * disk, which is worse. So: try to revoke, always delete, report both.
+ */
+export async function runLogout(ctx, args) {
+    if (args.all) {
+        return runLogoutAll(ctx, args);
+    }
+    const env = resolveAuthEnvironment(ctx, args.host, args.env);
+    const session = env.store.read(env.host);
+    if (!session) {
+        return ctx.succeed({ host: env.host, cleared: false, revoked: false }, `logout: no stored session for ${env.host}.`);
+    }
+    const revoked = await tryRevoke(ctx, env.host, session.auth0RefreshToken);
+    env.store.clear(env.host);
+    if (!revoked) {
+        ctx.warn(`ekanos: the local credentials were removed, but the refresh token ` +
+            `could not be revoked at Auth0. It stays valid until it expires — ` +
+            `revoke the session in Auth0 if this machine is compromised.`);
+    }
+    return ctx.succeed({ host: env.host, cleared: true, revoked }, `logout: signed out of ${env.host}${revoked ? ' and revoked the session' : ''}.`);
+}
+/**
+ * Never throws. Every failure mode here — an unreachable host, a deployment
+ * without the CLI routes, an Auth0 outage — must still end in the local token
+ * being deleted.
+ */
+async function tryRevoke(ctx, host, refreshToken) {
+    try {
+        const config = await fetchCliAuthConfig(host);
+        return await revokeRefreshToken(config, refreshToken);
+    }
+    catch (error) {
+        // Diagnostic only — the message never carries the token, and the outcome
+        // is reported in the envelope's `revoked` field either way.
+        ctx.warn(`ekanos: could not reach ${host} to revoke the session ` +
+            `(${error instanceof Error ? error.message : String(error)}).`);
+        return false;
+    }
+}
+/**
+ * `logout --all` — the "I am leaving this machine" verb. Every host is revoked
+ * independently and the local file is emptied regardless, for the same reason
+ * the single-host path does not let a failed revocation block the delete.
+ */
+async function runLogoutAll(ctx, args) {
+    const store = newStore(ctx, args.env);
+    const hosts = store.hosts();
+    if (hosts.length === 0) {
+        return ctx.succeed({ hosts: [], cleared: 0 }, 'logout: no stored sessions.');
+    }
+    const results = [];
+    for (const host of hosts) {
+        const session = store.read(host);
+        results.push({
+            host,
+            revoked: session
+                ? await tryRevoke(ctx, host, session.auth0RefreshToken)
+                : false,
+        });
+    }
+    const cleared = store.clearAll();
+    return ctx.succeed({ hosts: results, cleared }, `logout: signed out of ${cleared} host${cleared === 1 ? '' : 's'}.`);
+}
+//# sourceMappingURL=logout.js.map

package/dist/commands/logout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logout.js","sourceRoot":"","sources":["../../src/commands/logout.ts"],"names":[],"mappings":"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","sourcesContent":["import { revokeRefreshToken } from '../auth/device-flow';\nimport { fetchCliAuthConfig } from '../auth/fusion-api';\nimport { newStore, resolveAuthEnvironment } from '../auth/session';\nimport type { CliContext } from '../context';\nimport type { ExitCode } from '../exit-codes';\n\nexport interface LogoutArgs {\n  host?: string;\n  /** Sign out of every host in the credentials file. */\n  all: boolean;\n  env: Record<string, string | undefined>;\n}\n\n/**\n * `logout` — revoke the stored refresh token at Auth0, then delete it locally.\n *\n * Idempotent: logging out twice exits 0. `cleared: false` in the envelope says\n * there was nothing to remove; it is information, not a failure.\n *\n * Revocation is attempted first but never blocks the local delete. A logout\n * that only forgets the token would leave a rotating credential live for weeks;\n * a logout that REFUSES because the network is down would leave the token on\n * disk, which is worse. So: try to revoke, always delete, report both.\n */\nexport async function runLogout(\n  ctx: CliContext,\n  args: LogoutArgs,\n): Promise<ExitCode> {\n  if (args.all) {\n    return runLogoutAll(ctx, args);\n  }\n\n  const env = resolveAuthEnvironment(ctx, args.host, args.env);\n  const session = env.store.read(env.host);\n\n  if (!session) {\n    return ctx.succeed(\n      { host: env.host, cleared: false, revoked: false },\n      `logout: no stored session for ${env.host}.`,\n    );\n  }\n\n  const revoked = await tryRevoke(ctx, env.host, session.auth0RefreshToken);\n\n  env.store.clear(env.host);\n\n  if (!revoked) {\n    ctx.warn(\n      `ekanos: the local credentials were removed, but the refresh token ` +\n        `could not be revoked at Auth0. It stays valid until it expires — ` +\n        `revoke the session in Auth0 if this machine is compromised.`,\n    );\n  }\n\n  return ctx.succeed(\n    { host: env.host, cleared: true, revoked },\n    `logout: signed out of ${env.host}${revoked ? ' and revoked the session' : ''}.`,\n  );\n}\n\n/**\n * Never throws. Every failure mode here — an unreachable host, a deployment\n * without the CLI routes, an Auth0 outage — must still end in the local token\n * being deleted.\n */\nasync function tryRevoke(\n  ctx: CliContext,\n  host: string,\n  refreshToken: string,\n): Promise<boolean> {\n  try {\n    const config = await fetchCliAuthConfig(host);\n\n    return await revokeRefreshToken(config, refreshToken);\n  } catch (error) {\n    // Diagnostic only — the message never carries the token, and the outcome\n    // is reported in the envelope's `revoked` field either way.\n    ctx.warn(\n      `ekanos: could not reach ${host} to revoke the session ` +\n        `(${error instanceof Error ? error.message : String(error)}).`,\n    );\n\n    return false;\n  }\n}\n\n/**\n * `logout --all` — the \"I am leaving this machine\" verb. Every host is revoked\n * independently and the local file is emptied regardless, for the same reason\n * the single-host path does not let a failed revocation block the delete.\n */\nasync function runLogoutAll(\n  ctx: CliContext,\n  args: LogoutArgs,\n): Promise<ExitCode> {\n  const store = newStore(ctx, args.env);\n  const hosts = store.hosts();\n\n  if (hosts.length === 0) {\n    return ctx.succeed(\n      { hosts: [], cleared: 0 },\n      'logout: no stored sessions.',\n    );\n  }\n\n  const results: { host: string; revoked: boolean }[] = [];\n\n  for (const host of hosts) {\n    const session = store.read(host);\n\n    results.push({\n      host,\n      revoked: session\n        ? await tryRevoke(ctx, host, session.auth0RefreshToken)\n        : false,\n    });\n  }\n\n  const cleared = store.clearAll();\n\n  return ctx.succeed(\n    { hosts: results, cleared },\n    `logout: signed out of ${cleared} host${cleared === 1 ? '' : 's'}.`,\n  );\n}\n"]}

package/dist/commands/test.d.ts

@@ -0,0 +1,16 @@
+import type { CliContext } from '../context.js';
+export interface TestArgs {
+    dir: string;
+    /** argv after `--`, forwarded verbatim to the runner. */
+    passthrough: string[];
+}
+/**
+ * `test` — delegate to the partner's own test script; do NOT reimplement or
+ * parse the runner's output. We detect the package manager from the lockfile,
+ * spawn `<pm> run test` with any post-`--` args appended, stream the child's
+ * output to OUR stderr (keeping stdout pure for the single JSON envelope), and
+ * report `{ command, exitCode, durationMs }`.
+ *
+ * The CLI's exit code is a transparent passthrough of the runner's exit code.
+ */
+export declare function runTest(ctx: CliContext, args: TestArgs): Promise<number>;

package/dist/commands/test.js

@@ -0,0 +1,54 @@
+import { spawn } from 'node:child_process';
+import { detectPackageManager } from '../package-manager.js';
+import { loadProject } from '../project.js';
+/**
+ * `test` — delegate to the partner's own test script; do NOT reimplement or
+ * parse the runner's output. We detect the package manager from the lockfile,
+ * spawn `<pm> run test` with any post-`--` args appended, stream the child's
+ * output to OUR stderr (keeping stdout pure for the single JSON envelope), and
+ * report `{ command, exitCode, durationMs }`.
+ *
+ * The CLI's exit code is a transparent passthrough of the runner's exit code.
+ */
+export async function runTest(ctx, args) {
+    const loaded = loadProject(args.dir);
+    const pm = detectPackageManager(loaded.projectDir);
+    const runnerArgs = ['run', 'test', ...args.passthrough];
+    const command = `${pm.bin} ${runnerArgs.join(' ')}`;
+    ctx.log(`Running "${command}" in ${loaded.projectDir}…`);
+    const started = Date.now();
+    const exitCode = await new Promise((resolve, reject) => {
+        var _a, _b;
+        const child = spawn(pm.bin, runnerArgs, {
+            cwd: loaded.projectDir,
+            // stdin inherited; the child's stdout/stderr are piped so we can route
+            // them to OUR stderr and keep stdout reserved for the JSON envelope.
+            stdio: ['inherit', 'pipe', 'pipe'],
+        });
+        // In JSON mode every byte of runner output goes to stderr; in human mode we
+        // keep the child's stream separation.
+        (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => {
+            (ctx.jsonMode ? process.stderr : process.stdout).write(chunk);
+        });
+        (_b = child.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => {
+            process.stderr.write(chunk);
+        });
+        child.on('error', (error) => reject(error));
+        child.on('close', (code) => resolve(code !== null && code !== void 0 ? code : 1));
+    });
+    const durationMs = Date.now() - started;
+    const data = { command, exitCode, durationMs };
+    if (exitCode === 0) {
+        return ctx.succeed(data, `test: OK — "${command}" passed in ${durationMs}ms.`);
+    }
+    return ctx.failWith({
+        code: 'test_failed',
+        message: `"${command}" exited with code ${exitCode}.`,
+        hint: 'Read the runner output on stderr and fix the failing tests, then ' +
+            're-run "ekanos test".',
+        // Transparent passthrough of the runner's own exit code.
+        exitCode,
+        data,
+    });
+}
+//# sourceMappingURL=test.js.map

package/dist/commands/test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../../src/commands/test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAQzC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAe,EACf,IAAc;IAEd,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAEnD,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACpD,GAAG,CAAC,GAAG,CAAC,YAAY,OAAO,QAAQ,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;IAEzD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;;QAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE;YACtC,GAAG,EAAE,MAAM,CAAC,UAAU;YACtB,uEAAuE;YACvE,qEAAqE;YACrE,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;SACnC,CAAC,CAAC;QAEH,4EAA4E;QAC5E,sCAAsC;QACtC,MAAA,KAAK,CAAC,MAAM,0CAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACzC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QACH,MAAA,KAAK,CAAC,MAAM,0CAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACzC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5C,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,aAAJ,IAAI,cAAJ,IAAI,GAAI,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;IACxC,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IAE/C,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,GAAG,CAAC,OAAO,CAChB,IAAI,EACJ,eAAe,OAAO,eAAe,UAAU,KAAK,CACrD,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,QAAQ,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,IAAI,OAAO,sBAAsB,QAAQ,GAAG;QACrD,IAAI,EACF,mEAAmE;YACnE,uBAAuB;QACzB,yDAAyD;QACzD,QAAQ;QACR,IAAI;KACL,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { spawn } from 'node:child_process';\n\nimport type { CliContext } from '../context';\nimport { detectPackageManager } from '../package-manager';\nimport { loadProject } from '../project';\n\nexport interface TestArgs {\n  dir: string;\n  /** argv after `--`, forwarded verbatim to the runner. */\n  passthrough: string[];\n}\n\n/**\n * `test` — delegate to the partner's own test script; do NOT reimplement or\n * parse the runner's output. We detect the package manager from the lockfile,\n * spawn `<pm> run test` with any post-`--` args appended, stream the child's\n * output to OUR stderr (keeping stdout pure for the single JSON envelope), and\n * report `{ command, exitCode, durationMs }`.\n *\n * The CLI's exit code is a transparent passthrough of the runner's exit code.\n */\nexport async function runTest(\n  ctx: CliContext,\n  args: TestArgs,\n): Promise<number> {\n  const loaded = loadProject(args.dir);\n  const pm = detectPackageManager(loaded.projectDir);\n\n  const runnerArgs = ['run', 'test', ...args.passthrough];\n  const command = `${pm.bin} ${runnerArgs.join(' ')}`;\n  ctx.log(`Running \"${command}\" in ${loaded.projectDir}…`);\n\n  const started = Date.now();\n  const exitCode = await new Promise<number>((resolve, reject) => {\n    const child = spawn(pm.bin, runnerArgs, {\n      cwd: loaded.projectDir,\n      // stdin inherited; the child's stdout/stderr are piped so we can route\n      // them to OUR stderr and keep stdout reserved for the JSON envelope.\n      stdio: ['inherit', 'pipe', 'pipe'],\n    });\n\n    // In JSON mode every byte of runner output goes to stderr; in human mode we\n    // keep the child's stream separation.\n    child.stdout?.on('data', (chunk: Buffer) => {\n      (ctx.jsonMode ? process.stderr : process.stdout).write(chunk);\n    });\n    child.stderr?.on('data', (chunk: Buffer) => {\n      process.stderr.write(chunk);\n    });\n\n    child.on('error', (error) => reject(error));\n    child.on('close', (code) => resolve(code ?? 1));\n  });\n\n  const durationMs = Date.now() - started;\n  const data = { command, exitCode, durationMs };\n\n  if (exitCode === 0) {\n    return ctx.succeed(\n      data,\n      `test: OK — \"${command}\" passed in ${durationMs}ms.`,\n    );\n  }\n\n  return ctx.failWith({\n    code: 'test_failed',\n    message: `\"${command}\" exited with code ${exitCode}.`,\n    hint:\n      'Read the runner output on stderr and fix the failing tests, then ' +\n      're-run \"ekanos test\".',\n    // Transparent passthrough of the runner's own exit code.\n    exitCode,\n    data,\n  });\n}\n"]}

package/dist/commands/validate.d.ts

@@ -0,0 +1,14 @@
+import type { CliContext } from '../context.js';
+import type { ExitCode } from '../exit-codes.js';
+export interface ValidateArgs {
+    /** Project directory (contains ekanos.json). Defaults to cwd. */
+    dir: string;
+}
+/**
+ * `validate` — parse the declaration with the REAL zod schemas from
+ * `@ekanos/integration-schema` (never a reimplementation), gather structured
+ * findings, and add project-level integrity checks (the vitest inline-SDK
+ * check). Exit 0 with `findings: []` when clean; exit 3 when any error-severity
+ * finding is present, with the findings carried in the envelope's `data`.
+ */
+export declare function runValidate(ctx: CliContext, args: ValidateArgs): Promise<ExitCode>;

package/dist/commands/validate.js

@@ -0,0 +1,98 @@
+import { collectCollisionFindings, collectDefinitionFindings, } from '@ekanos/integration-schema';
+import { preconditionError, validationError } from '../errors.js';
+import { loadDefinition } from '../load-definition.js';
+import { loadProject } from '../project.js';
+import { collectProjectFindings } from '../project-checks.js';
+/**
+ * `validate` — parse the declaration with the REAL zod schemas from
+ * `@ekanos/integration-schema` (never a reimplementation), gather structured
+ * findings, and add project-level integrity checks (the vitest inline-SDK
+ * check). Exit 0 with `findings: []` when clean; exit 3 when any error-severity
+ * finding is present, with the findings carried in the envelope's `data`.
+ */
+export async function runValidate(ctx, args) {
+    const loaded = loadProject(args.dir);
+    const slugs = loaded.integrations.map((i) => i.slug).join(', ');
+    ctx.log(`Validating ${loaded.integrations.length} integration` +
+        `${loaded.integrations.length === 1 ? '' : 's'} (${slugs})…`);
+    const findings = [];
+    const definitions = [];
+    for (const integration of loaded.integrations) {
+        const result = await loadDefinition(integration.entryPath, loaded.projectDir);
+        if (result.ok) {
+            findings.push(...collectDefinitionFindings(result.definition, {
+                file: integration.entryPath,
+            }));
+            findings.push(...collectSlugAgreementFindings(integration, result.definition));
+            definitions.push(result.definition);
+            continue;
+        }
+        if (result.kind === 'rejected') {
+            // The module loaded but the SDK/schema rejected the definition at import
+            // time — surface it as a validation finding rather than a crash.
+            findings.push({
+                check: 'definition.load',
+                severity: 'error',
+                file: integration.entryPath,
+                message: result.message,
+                hint: 'Fix the integration definition so defineIntegration() accepts it, ' +
+                    'then re-run validate.',
+            });
+            continue;
+        }
+        // A genuine module-load failure is a precondition, not a finding.
+        throw preconditionError(`Could not load the integration definition for "${integration.slug}": ` +
+            result.message, 'Ensure the entry module and its installed dependencies load under ' +
+            'Node, then re-run validate.');
+    }
+    // Cross-checks only mean something with more than one definition in hand —
+    // which is exactly what this verb could not see before, since ekanos.json
+    // held a single { slug, entry } and a second integration was invisible.
+    findings.push(...collectCollisionFindings(definitions));
+    findings.push(...collectProjectFindings(loaded.projectDir));
+    const errorCount = findings.filter((f) => f.severity === 'error').length;
+    const data = {
+        slug: loaded.primary.slug,
+        integrations: loaded.integrations.map((i) => ({
+            slug: i.slug,
+            entry: i.entry,
+        })),
+        findings,
+    };
+    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);
+    }
+    return ctx.succeed(data, `validate: OK — no findings for ${slugs}.`);
+}
+/**
+ * `ekanos.json` and the definition each carry a slug, and nothing compared
+ * them: a project could declare `something-else` while the definition said
+ * `repo-activity` and validate would report `{ ok: true, findings: [] }`.
+ *
+ * That is the identifier every surface addresses the integration by — the
+ * harness route, the product slug, the widget id prefix, the MCP server — so
+ * two sources of truth disagreeing is not a style question. It is an error,
+ * not a warning, for the same reason a silent default is worse than a loud
+ * one: the failure it causes shows up somewhere else entirely.
+ */
+function collectSlugAgreementFindings(integration, definition) {
+    const declared = definition.slug;
+    if (typeof declared !== 'string' || declared === integration.slug)
+        return [];
+    return [
+        {
+            check: 'project.slug-agreement',
+            severity: 'error',
+            file: integration.entryPath,
+            message: `ekanos.json declares slug "${integration.slug}" for this entry, but ` +
+                `the definition says "${declared}". The slug addresses the ` +
+                'integration everywhere — its harness route, its product record, its ' +
+                'widget ids — so the two must agree.',
+            hint: `Change one to match the other: either set "slug": "${declared}" in ` +
+                `ekanos.json, or pass slug: '${integration.slug}' to ` +
+                'defineIntegration().',
+        },
+    ];
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\n\nimport type { CliContext } from '../context';\nimport { preconditionError, validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { loadDefinition } from '../load-definition';\nimport { loadProject } from '../project';\nimport { collectProjectFindings } from '../project-checks';\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 */\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: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand —\n  // which is exactly what this verb could not see before, since ekanos.json\n  // held a single { slug, entry } and a second integration was invisible.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\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\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n"]}

package/dist/commands/whoami.d.ts

@@ -0,0 +1,18 @@
+import type { CliContext } from '../context.js';
+import type { ExitCode } from '../exit-codes.js';
+export interface WhoamiArgs {
+    host?: string;
+    env: Record<string, string | undefined>;
+}
+/**
+ * `whoami` — prove the stored session still authenticates against Fusion.
+ *
+ * The identity is resolved server-side by `/api/auth/cli-whoami`, which reads
+ * the account through RLS as the caller. Printing the locally cached email
+ * would be a cheaper lie: it would keep saying "logged in" after the account
+ * was deleted or the token revoked.
+ *
+ * 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`.
+ */
+export declare function runWhoami(ctx: CliContext, args: WhoamiArgs): Promise<ExitCode>;

package/dist/commands/whoami.js

@@ -0,0 +1,29 @@
+import { requireSession, resolveAuthEnvironment, resolveIdentity, } from '../auth/session.js';
+/**
+ * `whoami` — prove the stored session still authenticates against Fusion.
+ *
+ * The identity is resolved server-side by `/api/auth/cli-whoami`, which reads
+ * the account through RLS as the caller. Printing the locally cached email
+ * would be a cheaper lie: it would keep saying "logged in" after the account
+ * was deleted or the token revoked.
+ *
+ * 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`.
+ */
+export async function runWhoami(ctx, args) {
+    var _a;
+    const env = resolveAuthEnvironment(ctx, args.host, args.env);
+    const stored = requireSession(env.store, env.host);
+    const { identity, session } = await resolveIdentity(env, stored);
+    return ctx.succeed({
+        host: env.host,
+        user: {
+            id: identity.id,
+            email: identity.email,
+            name: identity.name,
+        },
+        expiresAt: session.expiresAt,
+        credentialsPath: env.store.filePath,
+    }, `whoami: ${(_a = identity.email) !== null && _a !== void 0 ? _a : identity.id} on ${env.host}.`);
+}
+//# sourceMappingURL=whoami.js.map

package/dist/commands/whoami.js.map

@@ -0,0 +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;AASzB;;;;;;;;;;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,CAAC,CAAC;IAC7D,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  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  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"]}

package/dist/compatibility.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The shell templates ship with `@ekanos/cli`; the code they import ships with
+ * `@ekanos/harness`. The two version independently, so a partner can upgrade
+ * one without the other — and the interesting failure is the quiet one:
+ *
+ *   `pnpm up @ekanos/harness` → 0.2, which moves an export.
+ *   `ekanos dev` regenerates from the OLD CLI's templates and stamps "0.2"
+ *   into the marker. Every later run now considers the shell current. It is
+ *   not: it was generated against an obsolete contract, and what the partner
+ *   sees is a module-resolution error rather than "these are incompatible".
+ *
+ * That directly attacks the promise the package boundary exists to keep — ship
+ * a harness fix as a version bump a partner picks up with `pnpm up`. So the
+ * CLI declares which `@ekanos/harness` versions ITS templates are written
+ * against, checks the installed one before generating, and names the
+ * incompatibility instead of letting a resolution error stand in for it.
+ */
+/**
+ * The shell contract this CLI's templates GENERATE.
+ *
+ * An integer, not a semver range. A range can only INFER compatibility from
+ * version numbers — it cannot tell a harness bugfix from a change to the shell
+ * the harness requires, so it either blocks upgrades that were fine or waves
+ * through ones that were not. The integer is declared by both sides and is
+ * authoritative.
+ *
+ * **Bump this only when the generated shell's coupling to the package
+ * changes**: an export renamed or moved between `/app` and `/routes`, the
+ * props of `RootLayout` or `IndexPage`, the server/client split, the alias
+ * specifier, which side owns `@import 'tailwindcss'`, or the set of files the
+ * shell must contain. Editing a comment in a template does not count — that is
+ * what the template fingerprint in the marker is for.
+ */
+export declare const SHELL_CONTRACT = 1;
+/**
+ * The contract an installed `@ekanos/harness` declares it needs, from
+ * `{ "ekanos": { "shellContract": N } }` in its package.json.
+ *
+ * A package that declares nothing is read as contract 1 — the contract that
+ * shipped first — so the harness released before this existed keeps working.
+ * That default is deliberately silent, which is why `@ekanos/harness` asserts
+ * the field's presence in its own pack test rather than relying on it.
+ */
+export declare function declaredShellContract(harnessManifest: unknown): number;
+export declare function compareVersions(a: string, b: string): number;
+/** This CLI's own version, read from its package.json at runtime. */
+export declare function cliVersion(): string;
+/**
+ * Fail unless this CLI's templates generate the shell the installed harness
+ * expects.
+ *
+ * The templates ship with `@ekanos/cli`; the code they import ships with
+ * `@ekanos/harness`. The two version independently, so a partner can upgrade
+ * one without the other — and the failure that matters is the quiet one:
+ * `pnpm up @ekanos/harness` moves an export, `ekanos dev` regenerates from the
+ * OLD CLI's templates, and the partner sees a module-resolution error rather
+ * than anything naming the incompatibility.
+ *
+ * Byte-comparing generated files cannot catch it: the old templates' bytes are
+ * exactly what the old CLI intends, so nothing regenerates differently and the
+ * shell stays wired to something that moved. Only a declared contract can.
+ *
+ * Runs before anything is written, so an incompatible pair produces no shell
+ * at all — a broken shell that builds is worse than no shell.
+ */
+export declare function assertHarnessCompatible(params: {
+    harnessVersion: string;
+    harnessManifest: unknown;
+    installHint: (packageSpec: string) => string;
+}): void;
+/**
+ * A fingerprint of the template SOURCES, independent of the slug they are
+ * rendered with.
+ *
+ * The harness version alone cannot certify a shell: the templates can change
+ * while it stays put (a CLI patch release), and it can change while they stay
+ * put. Hashing the sources means any edit to what we generate invalidates
+ * every shell generated before it, including one produced by a CLI version
+ * that never shipped.
+ */
+export declare function templatesFingerprint(templateNames: readonly string[]): string;

package/dist/compatibility.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { preconditionError } from './errors.js';
+import { readTemplateSource, templatesDir } from './templates.js';
+/**
+ * The shell templates ship with `@ekanos/cli`; the code they import ships with
+ * `@ekanos/harness`. The two version independently, so a partner can upgrade
+ * one without the other — and the interesting failure is the quiet one:
+ *
+ *   `pnpm up @ekanos/harness` → 0.2, which moves an export.
+ *   `ekanos dev` regenerates from the OLD CLI's templates and stamps "0.2"
+ *   into the marker. Every later run now considers the shell current. It is
+ *   not: it was generated against an obsolete contract, and what the partner
+ *   sees is a module-resolution error rather than "these are incompatible".
+ *
+ * That directly attacks the promise the package boundary exists to keep — ship
+ * a harness fix as a version bump a partner picks up with `pnpm up`. So the
+ * CLI declares which `@ekanos/harness` versions ITS templates are written
+ * against, checks the installed one before generating, and names the
+ * incompatibility instead of letting a resolution error stand in for it.
+ */
+/**
+ * The shell contract this CLI's templates GENERATE.
+ *
+ * An integer, not a semver range. A range can only INFER compatibility from
+ * version numbers — it cannot tell a harness bugfix from a change to the shell
+ * the harness requires, so it either blocks upgrades that were fine or waves
+ * through ones that were not. The integer is declared by both sides and is
+ * authoritative.
+ *
+ * **Bump this only when the generated shell's coupling to the package
+ * changes**: an export renamed or moved between `/app` and `/routes`, the
+ * props of `RootLayout` or `IndexPage`, the server/client split, the alias
+ * specifier, which side owns `@import 'tailwindcss'`, or the set of files the
+ * shell must contain. Editing a comment in a template does not count — that is
+ * what the template fingerprint in the marker is for.
+ */
+export const SHELL_CONTRACT = 1;
+/**
+ * The contract an installed `@ekanos/harness` declares it needs, from
+ * `{ "ekanos": { "shellContract": N } }` in its package.json.
+ *
+ * A package that declares nothing is read as contract 1 — the contract that
+ * shipped first — so the harness released before this existed keeps working.
+ * That default is deliberately silent, which is why `@ekanos/harness` asserts
+ * the field's presence in its own pack test rather than relying on it.
+ */
+export function declaredShellContract(harnessManifest) {
+    if (typeof harnessManifest !== 'object' || harnessManifest === null)
+        return 1;
+    const ekanos = harnessManifest.ekanos;
+    if (typeof ekanos !== 'object' || ekanos === null)
+        return 1;
+    const declared = ekanos.shellContract;
+    return Number.isInteger(declared) ? declared : 1;
+}
+/** `[major, minor, patch]`, with anything non-numeric treated as 0. */
+function parseVersion(version) {
+    var _a, _b, _c;
+    const core = version.split('+')[0].split('-')[0];
+    const parts = core.split('.').map((part) => Number.parseInt(part, 10));
+    return [(_a = parts[0]) !== null && _a !== void 0 ? _a : 0, (_b = parts[1]) !== null && _b !== void 0 ? _b : 0, (_c = parts[2]) !== null && _c !== void 0 ? _c : 0];
+}
+export function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    for (let i = 0; i < 3; i++) {
+        if (left[i] !== right[i])
+            return left[i] < right[i] ? -1 : 1;
+    }
+    return 0;
+}
+/** This CLI's own version, read from its package.json at runtime. */
+export function cliVersion() {
+    const manifestPath = path.join(templatesDir(), '..', 'package.json');
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const version = typeof parsed === 'object' && parsed !== null
+        ? parsed.version
+        : undefined;
+    return typeof version === 'string' ? version : '0.0.0';
+}
+/**
+ * Fail unless this CLI's templates generate the shell the installed harness
+ * expects.
+ *
+ * The templates ship with `@ekanos/cli`; the code they import ships with
+ * `@ekanos/harness`. The two version independently, so a partner can upgrade
+ * one without the other — and the failure that matters is the quiet one:
+ * `pnpm up @ekanos/harness` moves an export, `ekanos dev` regenerates from the
+ * OLD CLI's templates, and the partner sees a module-resolution error rather
+ * than anything naming the incompatibility.
+ *
+ * Byte-comparing generated files cannot catch it: the old templates' bytes are
+ * exactly what the old CLI intends, so nothing regenerates differently and the
+ * shell stays wired to something that moved. Only a declared contract can.
+ *
+ * Runs before anything is written, so an incompatible pair produces no shell
+ * at all — a broken shell that builds is worse than no shell.
+ */
+export function assertHarnessCompatible(params) {
+    const required = declaredShellContract(params.harnessManifest);
+    if (required === SHELL_CONTRACT)
+        return;
+    if (required > SHELL_CONTRACT) {
+        throw preconditionError(`@ekanos/cli ${cliVersion()} is too old for @ekanos/harness ` +
+            `${params.harnessVersion}: that harness needs shell contract ` +
+            `${required}, and this CLI generates ${SHELL_CONTRACT}.`, `Upgrade the CLI: ${params.installHint('@ekanos/cli@latest')}. Then ` +
+            're-run "ekanos dev" and the shell is regenerated for you.');
+    }
+    throw preconditionError(`@ekanos/harness ${params.harnessVersion} is too old for @ekanos/cli ` +
+        `${cliVersion()}: this CLI generates shell contract ${SHELL_CONTRACT}, ` +
+        `and that harness needs ${required}.`, `Upgrade it: ${params.installHint('@ekanos/harness@latest')}.`);
+}
+/**
+ * A fingerprint of the template SOURCES, independent of the slug they are
+ * rendered with.
+ *
+ * The harness version alone cannot certify a shell: the templates can change
+ * while it stays put (a CLI patch release), and it can change while they stay
+ * put. Hashing the sources means any edit to what we generate invalidates
+ * every shell generated before it, including one produced by a CLI version
+ * that never shipped.
+ */
+export function templatesFingerprint(templateNames) {
+    const hash = createHash('sha256');
+    for (const name of [...templateNames].sort()) {
+        hash.update(name);
+        hash.update('\0');
+        hash.update(readTemplateSource(name));
+        hash.update('\0');
+    }
+    return hash.digest('hex').slice(0, 16);
+}
+//# sourceMappingURL=compatibility.js.map

package/dist/compatibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.js","sourceRoot":"","sources":["../src/compatibility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,eAAwB;IAC5D,IAAI,OAAO,eAAe,KAAK,QAAQ,IAAI,eAAe,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAI,eAAwC,CAAC,MAAM,CAAC;IAChE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAI,MAAsC,CAAC,aAAa,CAAC;IACvE,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAE,QAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,uEAAuE;AACvE,SAAS,YAAY,CAAC,OAAe;;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACvE,OAAO,CAAC,MAAA,KAAK,CAAC,CAAC,CAAC,mCAAI,CAAC,EAAE,MAAA,KAAK,CAAC,CAAC,CAAC,mCAAI,CAAC,EAAE,MAAA,KAAK,CAAC,CAAC,CAAC,mCAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,CAAC,CAAE,KAAK,KAAK,CAAC,CAAC,CAAE;YAAE,OAAO,IAAI,CAAC,CAAC,CAAE,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,UAAU;IACxB,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IACrE,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1E,MAAM,OAAO,GACX,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAC3C,CAAC,CAAE,MAAgC,CAAC,OAAO;QAC3C,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAIvC;IACC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAC/D,IAAI,QAAQ,KAAK,cAAc;QAAE,OAAO;IAExC,IAAI,QAAQ,GAAG,cAAc,EAAE,CAAC;QAC9B,MAAM,iBAAiB,CACrB,eAAe,UAAU,EAAE,kCAAkC;YAC3D,GAAG,MAAM,CAAC,cAAc,sCAAsC;YAC9D,GAAG,QAAQ,4BAA4B,cAAc,GAAG,EAC1D,oBAAoB,MAAM,CAAC,WAAW,CAAC,oBAAoB,CAAC,SAAS;YACnE,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,MAAM,iBAAiB,CACrB,mBAAmB,MAAM,CAAC,cAAc,8BAA8B;QACpE,GAAG,UAAU,EAAE,uCAAuC,cAAc,IAAI;QACxE,0BAA0B,QAAQ,GAAG,EACvC,eAAe,MAAM,CAAC,WAAW,CAAC,wBAAwB,CAAC,GAAG,CAC/D,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,aAAgC;IACnE,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC","sourcesContent":["import { createHash } from 'node:crypto';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { preconditionError } from './errors';\nimport { readTemplateSource, templatesDir } from './templates';\n\n/**\n * The shell templates ship with `@ekanos/cli`; the code they import ships with\n * `@ekanos/harness`. The two version independently, so a partner can upgrade\n * one without the other — and the interesting failure is the quiet one:\n *\n *   `pnpm up @ekanos/harness` → 0.2, which moves an export.\n *   `ekanos dev` regenerates from the OLD CLI's templates and stamps \"0.2\"\n *   into the marker. Every later run now considers the shell current. It is\n *   not: it was generated against an obsolete contract, and what the partner\n *   sees is a module-resolution error rather than \"these are incompatible\".\n *\n * That directly attacks the promise the package boundary exists to keep — ship\n * a harness fix as a version bump a partner picks up with `pnpm up`. So the\n * CLI declares which `@ekanos/harness` versions ITS templates are written\n * against, checks the installed one before generating, and names the\n * incompatibility instead of letting a resolution error stand in for it.\n */\n\n/**\n * The shell contract this CLI's templates GENERATE.\n *\n * An integer, not a semver range. A range can only INFER compatibility from\n * version numbers — it cannot tell a harness bugfix from a change to the shell\n * the harness requires, so it either blocks upgrades that were fine or waves\n * through ones that were not. The integer is declared by both sides and is\n * authoritative.\n *\n * **Bump this only when the generated shell's coupling to the package\n * changes**: an export renamed or moved between `/app` and `/routes`, the\n * props of `RootLayout` or `IndexPage`, the server/client split, the alias\n * specifier, which side owns `@import 'tailwindcss'`, or the set of files the\n * shell must contain. Editing a comment in a template does not count — that is\n * what the template fingerprint in the marker is for.\n */\nexport const SHELL_CONTRACT = 1;\n\n/**\n * The contract an installed `@ekanos/harness` declares it needs, from\n * `{ \"ekanos\": { \"shellContract\": N } }` in its package.json.\n *\n * A package that declares nothing is read as contract 1 — the contract that\n * shipped first — so the harness released before this existed keeps working.\n * That default is deliberately silent, which is why `@ekanos/harness` asserts\n * the field's presence in its own pack test rather than relying on it.\n */\nexport function declaredShellContract(harnessManifest: unknown): number {\n  if (typeof harnessManifest !== 'object' || harnessManifest === null) return 1;\n  const ekanos = (harnessManifest as { ekanos?: unknown }).ekanos;\n  if (typeof ekanos !== 'object' || ekanos === null) return 1;\n  const declared = (ekanos as { shellContract?: unknown }).shellContract;\n  return Number.isInteger(declared) ? (declared as number) : 1;\n}\n\n/** `[major, minor, patch]`, with anything non-numeric treated as 0. */\nfunction parseVersion(version: string): [number, number, number] {\n  const core = version.split('+')[0]!.split('-')[0]!;\n  const parts = core.split('.').map((part) => Number.parseInt(part, 10));\n  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];\n}\n\nexport function compareVersions(a: string, b: string): number {\n  const left = parseVersion(a);\n  const right = parseVersion(b);\n  for (let i = 0; i < 3; i++) {\n    if (left[i]! !== right[i]!) return left[i]! < right[i]! ? -1 : 1;\n  }\n  return 0;\n}\n\n/** This CLI's own version, read from its package.json at runtime. */\nexport function cliVersion(): string {\n  const manifestPath = path.join(templatesDir(), '..', 'package.json');\n  const parsed: unknown = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));\n  const version =\n    typeof parsed === 'object' && parsed !== null\n      ? (parsed as { version?: unknown }).version\n      : undefined;\n  return typeof version === 'string' ? version : '0.0.0';\n}\n\n/**\n * Fail unless this CLI's templates generate the shell the installed harness\n * expects.\n *\n * The templates ship with `@ekanos/cli`; the code they import ships with\n * `@ekanos/harness`. The two version independently, so a partner can upgrade\n * one without the other — and the failure that matters is the quiet one:\n * `pnpm up @ekanos/harness` moves an export, `ekanos dev` regenerates from the\n * OLD CLI's templates, and the partner sees a module-resolution error rather\n * than anything naming the incompatibility.\n *\n * Byte-comparing generated files cannot catch it: the old templates' bytes are\n * exactly what the old CLI intends, so nothing regenerates differently and the\n * shell stays wired to something that moved. Only a declared contract can.\n *\n * Runs before anything is written, so an incompatible pair produces no shell\n * at all — a broken shell that builds is worse than no shell.\n */\nexport function assertHarnessCompatible(params: {\n  harnessVersion: string;\n  harnessManifest: unknown;\n  installHint: (packageSpec: string) => string;\n}): void {\n  const required = declaredShellContract(params.harnessManifest);\n  if (required === SHELL_CONTRACT) return;\n\n  if (required > SHELL_CONTRACT) {\n    throw preconditionError(\n      `@ekanos/cli ${cliVersion()} is too old for @ekanos/harness ` +\n        `${params.harnessVersion}: that harness needs shell contract ` +\n        `${required}, and this CLI generates ${SHELL_CONTRACT}.`,\n      `Upgrade the CLI: ${params.installHint('@ekanos/cli@latest')}. Then ` +\n        're-run \"ekanos dev\" and the shell is regenerated for you.',\n    );\n  }\n\n  throw preconditionError(\n    `@ekanos/harness ${params.harnessVersion} is too old for @ekanos/cli ` +\n      `${cliVersion()}: this CLI generates shell contract ${SHELL_CONTRACT}, ` +\n      `and that harness needs ${required}.`,\n    `Upgrade it: ${params.installHint('@ekanos/harness@latest')}.`,\n  );\n}\n\n/**\n * A fingerprint of the template SOURCES, independent of the slug they are\n * rendered with.\n *\n * The harness version alone cannot certify a shell: the templates can change\n * while it stays put (a CLI patch release), and it can change while they stay\n * put. Hashing the sources means any edit to what we generate invalidates\n * every shell generated before it, including one produced by a CLI version\n * that never shipped.\n */\nexport function templatesFingerprint(templateNames: readonly string[]): string {\n  const hash = createHash('sha256');\n  for (const name of [...templateNames].sort()) {\n    hash.update(name);\n    hash.update('\\0');\n    hash.update(readTemplateSource(name));\n    hash.update('\\0');\n  }\n  return hash.digest('hex').slice(0, 16);\n}\n"]}