@ekanos/cli 0.1.5 → 0.1.6

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":"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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 * `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;

package/dist/harness-scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"harness-scaffold.js","sourceRoot":"","sources":["../src/harness-scaffold.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { cliVersion, templatesFingerprint } from './compatibility';\nimport { invalidStateError, preconditionError } from './errors';\nimport {\n  appendFileNoFollow,\n  classifyPath,\n  readFileNoFollow,\n  writeFileNoFollow,\n} from './safe-fs';\nimport { readTemplate } from './templates';\n\n/** The dependency that owns every line of harness behaviour. */\nexport const HARNESS_PACKAGE = '@ekanos/harness';\n\n/** Where the generated shell lives, relative to the project root. */\nexport const HARNESS_DIR = path.join('.ekanos', 'harness');\n\n/** The single `.gitignore` line that covers the whole generated tree. */\nexport const GITIGNORE_ENTRY = '.ekanos/';\n\n/**\n * The staleness marker, inside the generated tree so deleting the tree also\n * deletes the marker. Holds the `@ekanos/harness` version that generated the\n * shell — a version bump means the shell may be wired against an older export\n * surface, so it is regenerated.\n */\nexport const VERSION_MARKER = '.ekanos-version';\n\n/** The partner-owned registry, at the PROJECT ROOT. Never regenerated. */\nexport const HARNESS_CONFIG_FILENAME = 'harness.config.ts';\n\n/**\n * Every file in the generated shell: bundled template → path inside\n * `.ekanos/harness/`. The nine route files are mechanically derivable from the\n * export map alone — which is the test of whether the package boundary is in\n * the right place. If a shell file ever needs a judgment call, the boundary\n * has moved, not the template.\n *\n * `app/harness-shell.tsx` exists because a `HarnessIntegration` holds React\n * component references and MCP `run` functions. Next cannot serialize those\n * across a server→client boundary, so the `'use client'` mark has to sit ABOVE\n * the point where the registry is injected — hence a client shell of its own\n * rather than a client `RootLayout` called from a server layout. Keeping\n * `app/page.tsx` a server component is what lets `/` prerender static.\n */\nexport const SHELL_FILES: readonly { template: string; dest: string }[] = [\n  { template: 'harness/app/layout.tsx.tmpl', dest: 'app/layout.tsx' },\n  {\n    template: 'harness/app/harness-shell.tsx.tmpl',\n    dest: 'app/harness-shell.tsx',\n  },\n  { template: 'harness/app/page.tsx.tmpl', dest: 'app/page.tsx' },\n  {\n    template: 'harness/app/[slug]/layout.tsx.tmpl',\n    dest: 'app/[slug]/layout.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/widgets/page.tsx.tmpl',\n    dest: 'app/[slug]/widgets/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/widgets/[widgetId]/page.tsx.tmpl',\n    dest: 'app/[slug]/widgets/[widgetId]/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/tile/page.tsx.tmpl',\n    dest: 'app/[slug]/tile/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/activation/page.tsx.tmpl',\n    dest: 'app/[slug]/activation/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/triggers/page.tsx.tmpl',\n    dest: 'app/[slug]/triggers/page.tsx',\n  },\n  { template: 'harness/next.config.mjs.tmpl', dest: 'next.config.mjs' },\n  { template: 'harness/postcss.config.mjs.tmpl', dest: 'postcss.config.mjs' },\n  { template: 'harness/tsconfig.json.tmpl', dest: 'tsconfig.json' },\n  { template: 'harness/styles/globals.css.tmpl', dest: 'styles/globals.css' },\n  { template: 'harness/package.json.tmpl', dest: 'package.json' },\n  {\n    template: 'harness/types/team-accounts.d.ts.tmpl',\n    dest: 'types/team-accounts.d.ts',\n  },\n];\n\n/**\n * Packages the shell needs to resolve upward out of the partner's own\n * `node_modules`. The shell declares no dependencies of its own by design, so\n * a missing one shows up as an opaque Next resolution error at dev-server\n * start; checking here turns that into one precondition with one fix.\n */\nexport const REQUIRED_DEPENDENCIES = [\n  HARNESS_PACKAGE,\n  'next',\n  'react',\n  'react-dom',\n  'tailwindcss',\n  '@tailwindcss/postcss',\n] as const;\n\nexport interface WrittenFiles {\n  created: string[];\n  updated: string[];\n  unchanged: string[];\n}\n\n/**\n * Read the installed `@ekanos/harness` version out of the partner's\n * `node_modules`. Resolved by path rather than `require.resolve` on purpose:\n * the CLI runs from its own install and must read the version of the copy in\n * THEIR project, not one hoisted next to itself.\n */\nexport interface InstalledHarness {\n  version: string;\n  /** The raw package.json, so compatibility can read its `ekanos` block. */\n  manifest: unknown;\n}\n\nexport function readInstalledHarness(\n  projectDir: string,\n): InstalledHarness | null {\n  const manifest = path.join(\n    projectDir,\n    'node_modules',\n    HARNESS_PACKAGE,\n    'package.json',\n  );\n  if (!fs.existsSync(manifest)) return null;\n\n  try {\n    const parsed: unknown = JSON.parse(fs.readFileSync(manifest, 'utf8'));\n    const version =\n      typeof parsed === 'object' && parsed !== null\n        ? (parsed as { version?: unknown }).version\n        : undefined;\n    if (typeof version !== 'string' || version.length === 0) return null;\n    return { version, manifest: parsed };\n  } catch (error) {\n    throw preconditionError(\n      `${HARNESS_PACKAGE}'s package.json in node_modules is unreadable: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n      `Reinstall dependencies in ${projectDir} so ${HARNESS_PACKAGE} resolves.`,\n    );\n  }\n}\n\n/** Just the installed version, for callers that need nothing else. */\nexport function readInstalledHarnessVersion(projectDir: string): string | null {\n  return readInstalledHarness(projectDir)?.version ?? null;\n}\n\n/** Which of `REQUIRED_DEPENDENCIES` are not installed in the project root. */\nexport function missingDependencies(projectDir: string): string[] {\n  return REQUIRED_DEPENDENCIES.filter(\n    (name) =>\n      !fs.existsSync(\n        path.join(projectDir, 'node_modules', name, 'package.json'),\n      ),\n  );\n}\n\n/**\n * What generated an existing shell.\n *\n * All three fields matter, and recording only `harness` was a real hole: the\n * templates ship with the CLI, so a shell can be stale because the CLI changed\n * while the harness did not. `templates` is the authoritative one — it is a\n * hash of the template sources, so it moves whenever what we generate moves,\n * including for a CLI build that never shipped a version bump.\n */\nexport interface ShellMarker {\n  harness: string;\n  /** null for a legacy bare-version marker written before this was recorded. */\n  cli: string | null;\n  templates: string | null;\n}\n\n/**\n * Three outcomes, not two, because \"no marker\" and \"unreadable marker\" call\n * for opposite responses.\n *\n * A marker's PRESENCE is itself evidence the tree is ours — a squatter does\n * not write `.ekanos-version` — and the likeliest cause of an unreadable one\n * is our own interrupted write. Everything under `.ekanos/harness/` is\n * CLI-owned, gitignored and reproducible from the templates, so regenerating\n * destroys nothing: there is no value at risk to justify charging a partner a\n * confusing `--force` to recover from our own bad write.\n *\n * An ABSENT marker over a non-empty tree is the opposite: nothing says the\n * files are ours, so we refuse. That is the L1 rule and it stays.\n */\nexport type MarkerState =\n  | { kind: 'missing' }\n  | { kind: 'corrupt' }\n  | { kind: 'ok'; marker: ShellMarker };\n\nexport function readShellMarkerState(harnessDir: string): MarkerState {\n  const marker = path.join(harnessDir, VERSION_MARKER);\n  if (classifyPath(marker) !== 'file') return { kind: 'missing' };\n\n  const raw = (readFileNoFollow(harnessDir, marker) ?? '').trim();\n  if (raw.length === 0) return { kind: 'corrupt' };\n\n  const parsed = parseMarker(raw);\n  return parsed === null ? { kind: 'corrupt' } : { kind: 'ok', marker: parsed };\n}\n\nfunction parseMarker(raw: string): ShellMarker | null {\n  // v1 markers were a bare version string. Read them rather than crashing, and\n  // report the unknown fields as null so the shell counts as stale and is\n  // regenerated once — which is the correct outcome for an upgrade.\n  //\n  // It must actually LOOK like a version: without this, any garbage that does\n  // not happen to start with `{` — a truncated write, a stray word — reads as\n  // a legacy marker named after the garbage, and the corrupt-marker path never\n  // fires. That is how a truncated `.ekanos-version` was silently reported as\n  // \"@ekanos/harness truncat → 0.1.0\" instead of \"unreadable\".\n  if (!raw.startsWith('{')) {\n    return /^\\d+\\.\\d+/.test(raw)\n      ? { harness: raw, cli: null, templates: null }\n      : null;\n  }\n\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (typeof parsed !== 'object' || parsed === null) return null;\n    const record = parsed as Record<string, unknown>;\n    const harness = record.harness;\n    if (typeof harness !== 'string') return null;\n    return {\n      harness,\n      cli: typeof record.cli === 'string' ? record.cli : null,\n      templates: typeof record.templates === 'string' ? record.templates : null,\n    };\n  } catch {\n    return null;\n  }\n}\n\n/** The parsed marker, or null when it is absent OR unreadable. */\nexport function readShellMarker(harnessDir: string): ShellMarker | null {\n  const state = readShellMarkerState(harnessDir);\n  return state.kind === 'ok' ? state.marker : null;\n}\n\n/** The `@ekanos/harness` version an existing shell was generated against. */\nexport function readShellVersion(harnessDir: string): string | null {\n  return readShellMarker(harnessDir)?.harness ?? null;\n}\n\nfunction serializeMarker(marker: ShellMarker): string {\n  return `${JSON.stringify(marker, null, 2)}\\n`;\n}\n\n/**\n * Write a generated file, but ONLY when its bytes would change.\n *\n * This is what makes a re-run cheap and a watcher quiet: an unchanged file is\n * not rewritten, so its mtime does not move and Next's dev server does not\n * rebuild. It also means a hand-edit inside the CLI-owned tree is silently\n * corrected on the next run, which is the intended contract for `.ekanos/`.\n */\nexport function writeIfChanged(\n  root: string,\n  destPath: string,\n  contents: string,\n  into: WrittenFiles,\n  label: string,\n  force: boolean,\n): void {\n  // `classifyPath` uses lstat, so a symlink here is reported as a symlink\n  // rather than as whatever it points at — including a DANGLING one, which\n  // `existsSync` would call absent and a plain write would then materialize\n  // outside the project.\n  const kind = classifyPath(destPath);\n  const exists = kind !== 'missing';\n\n  if (\n    !force &&\n    kind === 'file' &&\n    readFileNoFollow(root, destPath) === contents\n  ) {\n    into.unchanged.push(label);\n    return;\n  }\n\n  writeFileNoFollow(root, destPath, contents);\n  (exists ? into.updated : into.created).push(label);\n}\n\nexport interface ScaffoldShellArgs {\n  projectDir: string;\n  slug: string;\n  harnessVersion: string;\n  /** Rewrite every file even when its bytes already match. */\n  force: boolean;\n  /** Extra Tailwind @source globs from ekanos.json, already validated. */\n  sourceGlobs?: readonly string[];\n}\n\nexport interface ScaffoldShellResult extends WrittenFiles {\n  harnessDir: string;\n  /** The version the shell carried before this run — null on a first run. */\n  previousVersion: string | null;\n  /** What generated the previous shell, or null on a first run. */\n  previousMarker: ShellMarker | null;\n  /** True when anything that generated the shell has since changed. */\n  stale: boolean;\n  /**\n   * Which of harness / cli / templates moved. Empty on a first run; this is\n   * what lets `dev` say WHY it regenerated rather than just that it did.\n   */\n  staleReasons: string[];\n}\n\n/**\n * Generate `.ekanos/harness/**` for `harnessVersion`. Every file here is\n * CLI-owned and gitignored, so regeneration needs no permission and asks no\n * question — the partner owns `harness.config.ts` and their integration\n * source, and nothing else.\n */\nexport function scaffoldShell(args: ScaffoldShellArgs): ScaffoldShellResult {\n  const harnessDir = path.join(args.projectDir, HARNESS_DIR);\n  assertShellDirIsOurs(harnessDir, args.force);\n\n  const markerState = readShellMarkerState(harnessDir);\n  const previousMarker = markerState.kind === 'ok' ? markerState.marker : null;\n  const previousVersion = previousMarker?.harness ?? null;\n  const marker: ShellMarker = {\n    harness: args.harnessVersion,\n    cli: cliVersion(),\n    templates: templatesFingerprint(SHELL_FILES.map((f) => f.template)),\n  };\n\n  // A shell is current only if EVERYTHING that produced it is unchanged.\n  // Checking the harness version alone certified shells generated by an older\n  // CLI, against templates that had since moved, as up to date.\n  const staleReasons: string[] = [];\n  if (markerState.kind === 'corrupt') {\n    staleReasons.push(\n      `${VERSION_MARKER} was unreadable, so the existing shell could not be ` +\n        'certified',\n    );\n  }\n  if (previousMarker !== null) {\n    if (previousMarker.harness !== marker.harness) {\n      staleReasons.push(\n        `@ekanos/harness ${previousMarker.harness} → ${marker.harness}`,\n      );\n    }\n    if (previousMarker.cli !== marker.cli) {\n      staleReasons.push(\n        `@ekanos/cli ${previousMarker.cli ?? 'unknown'} → ${marker.cli}`,\n      );\n    }\n    if (previousMarker.templates !== marker.templates) {\n      staleReasons.push('the shell templates changed');\n    }\n  }\n  const stale = staleReasons.length > 0;\n\n  const files: WrittenFiles = { created: [], updated: [], unchanged: [] };\n  const vars = {\n    SLUG: args.slug,\n    SOURCE_GLOBS: renderSourceGlobs(args.sourceGlobs ?? []),\n  };\n\n  for (const { template, dest } of SHELL_FILES) {\n    writeIfChanged(\n      args.projectDir,\n      path.join(harnessDir, dest),\n      readTemplate(template, vars),\n      files,\n      dest,\n      args.force,\n    );\n  }\n\n  writeIfChanged(\n    args.projectDir,\n    path.join(harnessDir, VERSION_MARKER),\n    serializeMarker(marker),\n    files,\n    VERSION_MARKER,\n    args.force,\n  );\n\n  return {\n    ...files,\n    harnessDir,\n    previousVersion,\n    previousMarker,\n    stale,\n    staleReasons,\n  };\n}\n\n/**\n * Turn validated `sourceGlobs` into the `@source` lines the generated\n * stylesheet carries, each relative to the shell's `styles/` directory.\n *\n * Tailwind never scans what it is not pointed at, and a glob that matches\n * nothing fails silently — so an integration living outside the default\n * layout renders completely unstyled with no error anywhere. That is what\n * `sourceGlobs` is for, and until now it was parsed and thrown away.\n */\nfunction renderSourceGlobs(globs: readonly string[]): string {\n  if (globs.length === 0) return '';\n  const lines = globs.map((glob) => `@source '${SHELL_TO_PROJECT}${glob}';`);\n  return `\\n/* From \"sourceGlobs\" in ekanos.json. */\\n${lines.join('\\n')}\\n`;\n}\n\n/** From `.ekanos/harness/styles/` back up to the project root. */\nconst SHELL_TO_PROJECT = '../../../';\n\n/**\n * Establish that `.ekanos/harness` is a tree WE generated before writing a\n * single byte into it, and return the version marker it carried.\n *\n * Path location alone is not ownership. A directory that exists but carries no\n * `.ekanos-version` was put there by something else — a partner, another tool,\n * a symlink — and clobbering it because it happens to sit at the path we like\n * is the same class of mistake as following a symlink. An empty directory is\n * fine (that is just `mkdir -p` having run), and `--force` is the explicit\n * override.\n *\n * Runs BEFORE `bootstrapHarnessConfig` in `dev`, so a shell that cannot be\n * written leaves the project completely untouched rather than half-scaffolded.\n */\nexport function assertShellDirIsOurs(\n  harnessDir: string,\n  force: boolean,\n): string | null {\n  const kind = classifyPath(harnessDir);\n\n  if (kind === 'symlink') {\n    throw invalidStateError(\n      `${harnessDir} is a symlink, so \"ekanos dev\" will not write through it.`,\n      `Delete ${harnessDir} and re-run \"ekanos dev\" — the shell is generated, ` +\n        'so nothing is lost.',\n    );\n  }\n\n  if (kind !== 'missing' && kind !== 'directory') {\n    throw invalidStateError(\n      `${harnessDir} exists and is not a directory.`,\n      `Move or delete ${harnessDir}, then re-run \"ekanos dev\".`,\n    );\n  }\n\n  if (kind === 'missing') return null;\n\n  const state = readShellMarkerState(harnessDir);\n\n  // A marker we wrote, however mangled, still identifies the tree as ours.\n  if (state.kind === 'ok') return state.marker.harness;\n  if (state.kind === 'corrupt' || force) return null;\n\n  if (fs.readdirSync(harnessDir).length === 0) return null;\n\n  throw invalidStateError(\n    `${harnessDir} already contains files but no ${VERSION_MARKER} marker, ` +\n      'so it was not generated by \"ekanos dev\".',\n    `Delete ${harnessDir} if you do not need it, or pass --force to ` +\n      'overwrite it. Everything \"ekanos dev\" generates is reproducible; ' +\n      'anything else in there is not.',\n  );\n}\n\n/**\n * The module specifier `harness.config.ts` uses to import the partner's\n * integration: the `entry` from ekanos.json, made relative and extension-free.\n * \"src/integration.ts\" → \"src/integration\".\n */\nexport function entryImportSpecifier(entry: string): string {\n  const normalized = entry.split(path.sep).join('/').replace(/^\\.\\//, '');\n  return normalized.replace(/\\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/, '');\n}\n\n/**\n * The same specifier as a JavaScript string LITERAL, ready to drop into a\n * generated `import` statement.\n *\n * `entry` is attacker-influenced data from `ekanos.json`, and a POSIX filename\n * may legally contain a quote or a newline. Interpolating it raw would let a\n * crafted-but-valid path close the string and append statements to the module\n * we generate. `JSON.stringify` produces a correctly escaped literal, which is\n * the actual fix; the explicit rejection below is a second line that also\n * gives the partner a comprehensible error instead of a bizarre filename\n * silently appearing, escaped, in their config.\n *\n * This does not cross a trust boundary on its own — a partner's own code runs\n * unsandboxed anyway — but \"the templates cannot be injected into\" is a claim\n * we make, and it should be true.\n */\nexport function entryImportLiteral(entry: string): string {\n  const specifier = entryImportSpecifier(entry);\n\n  // eslint-disable-next-line no-control-regex\n  if (/[\"'`\\\\\\n\\r\\u0000-\\u001f]/.test(specifier)) {\n    throw preconditionError(\n      `The \"entry\" in ekanos.json contains characters that cannot appear in ` +\n        `an import specifier: ${JSON.stringify(specifier)}.`,\n      'Rename the file so its path has no quotes, backslashes or control ' +\n        'characters, then update \"entry\" in ekanos.json to match.',\n    );\n  }\n\n  return JSON.stringify(`./${specifier}`);\n}\n\nexport interface BootstrapConfigResult {\n  /** True only when this run created the file. */\n  bootstrapped: boolean;\n  configPath: string;\n}\n\n/**\n * Write a starter `harness.config.ts` at the project root — ONCE.\n *\n * An existing file is left strictly alone, byte for byte, and no flag changes\n * that: it is the one harness file the partner owns, it is git-tracked, and\n * regenerating it would throw away their fixtures. `--force` regenerates the\n * shell, never this.\n */\nexport function bootstrapHarnessConfig(\n  projectDir: string,\n  integrations: readonly { slug: string; entry: string }[],\n): BootstrapConfigResult {\n  const configPath = path.join(projectDir, HARNESS_CONFIG_FILENAME);\n  const kind = classifyPath(configPath);\n\n  // A symlink here — including a dangling one, which `existsSync` reports as\n  // absent — would have us write through to its target. Since this file is the\n  // partner's to own, the only safe answer is to touch nothing and say why.\n  if (kind === 'symlink') {\n    throw invalidStateError(\n      `${configPath} is a symlink, so \"ekanos dev\" will not write through it.`,\n      `Replace ${configPath} with a real file (or delete it to have one ` +\n        'generated), then re-run \"ekanos dev\".',\n    );\n  }\n\n  if (kind !== 'missing') {\n    return { bootstrapped: false, configPath };\n  }\n\n  writeFileNoFollow(projectDir, configPath, renderHarnessConfig(integrations));\n\n  return { bootstrapped: true, configPath };\n}\n\n/**\n * Render the starter registry for EVERY integration the project declares.\n *\n * The harness registry is an array and `ekanos.json` can now hold a list, so a\n * project's second integration reaches the harness the same way its first\n * does. Each entry imports the definition under a distinct local identifier\n * derived from its slug, because two `integration` imports in one module do\n * not compile.\n */\nfunction renderHarnessConfig(\n  integrations: readonly { slug: string; entry: string }[],\n): string {\n  const imports: string[] = [];\n  const entries: string[] = [];\n\n  for (const integration of integrations) {\n    const ident = identifierForSlug(integration.slug);\n    imports.push(\n      `import { integration as ${ident} } from ${entryImportLiteral(\n        integration.entry,\n      )};`,\n    );\n    entries.push(\n      readTemplate('harness.config.entry.ts.tmpl', {\n        IDENT: ident,\n        SLUG: integration.slug,\n      }),\n    );\n  }\n\n  return readTemplate('harness.config.ts.tmpl', {\n    INTEGRATION_IMPORTS: imports.join('\\n'),\n    INTEGRATION_ENTRIES: entries.join(''),\n  });\n}\n\n/**\n * \"acme-crm\" → \"acmeCrm\". A slug is kebab-case by schema, so this only has to\n * handle hyphens, and a leading digit is impossible.\n */\nexport function identifierForSlug(slug: string): string {\n  const camel = slug.replace(/-([a-z0-9])/g, (_, char: string) =>\n    char.toUpperCase(),\n  );\n  return /^[0-9]/.test(camel) ? `i${camel}` : camel;\n}\n\n/**\n * Add `.ekanos/` to the project `.gitignore`, exactly once.\n *\n * Matching is line-wise over the spellings git treats as the same rule\n * (`.ekanos`, `.ekanos/`, `/.ekanos/`), so re-running never appends a\n * duplicate — the thing that makes a scaffold verb safe to run in a loop.\n * A negation (`!.ekanos/`) is deliberately NOT treated as a match: the\n * partner meant to un-ignore it, and we do not fight that silently.\n */\nexport function ensureGitignoreEntry(projectDir: string): boolean {\n  const gitignorePath = path.join(projectDir, '.gitignore');\n  const block = `# Ekanos dev harness — generated by \"ekanos dev\", never edited by hand\\n${GITIGNORE_ENTRY}\\n`;\n\n  const kind = classifyPath(gitignorePath);\n\n  if (kind === 'symlink') {\n    throw invalidStateError(\n      `${gitignorePath} is a symlink, so \"ekanos dev\" will not append to it.`,\n      `Add \"${GITIGNORE_ENTRY}\" to your real .gitignore yourself, or replace ` +\n        `${gitignorePath} with a regular file, then re-run \"ekanos dev\".`,\n    );\n  }\n\n  if (kind === 'missing') {\n    writeFileNoFollow(projectDir, gitignorePath, block);\n    return true;\n  }\n\n  const existing = readFileNoFollow(projectDir, gitignorePath) ?? '';\n  if (gitignoreCovers(existing)) return false;\n\n  const separator =\n    existing.length === 0 || existing.endsWith('\\n') ? '' : '\\n';\n  appendFileNoFollow(projectDir, gitignorePath, `${separator}\\n${block}`);\n  return true;\n}\n\nfunction gitignoreCovers(source: string): boolean {\n  const equivalents = new Set(['.ekanos', '.ekanos/', '/.ekanos', '/.ekanos/']);\n  return source\n    .split('\\n')\n    .map((line) => line.trim())\n    .some((line) => equivalents.has(line));\n}\n"]}
+{"version":3,"file":"harness-scaffold.js","sourceRoot":"","sources":["../src/harness-scaffold.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { cliVersion, templatesFingerprint } from './compatibility';\nimport { invalidStateError, preconditionError } from './errors';\nimport {\n  appendFileNoFollow,\n  classifyPath,\n  readFileNoFollow,\n  writeFileNoFollow,\n} from './safe-fs';\nimport { readTemplate } from './templates';\n\n/** The dependency that owns every line of harness behaviour. */\nexport const HARNESS_PACKAGE = '@ekanos/harness';\n\n/** Where the generated shell lives, relative to the project root. */\nexport const HARNESS_DIR = path.join('.ekanos', 'harness');\n\n/** The single `.gitignore` line that covers the whole generated tree. */\nexport const GITIGNORE_ENTRY = '.ekanos/';\n\n/**\n * The staleness marker, inside the generated tree so deleting the tree also\n * deletes the marker. Holds the `@ekanos/harness` version that generated the\n * shell — a version bump means the shell may be wired against an older export\n * surface, so it is regenerated.\n */\nexport const VERSION_MARKER = '.ekanos-version';\n\n/** The partner-owned registry, at the PROJECT ROOT. Never regenerated. */\nexport const HARNESS_CONFIG_FILENAME = 'harness.config.ts';\n\n/**\n * Every file in the generated shell: bundled template → path inside\n * `.ekanos/harness/`. The nine route files are mechanically derivable from the\n * export map alone — which is the test of whether the package boundary is in\n * the right place. If a shell file ever needs a judgment call, the boundary\n * has moved, not the template.\n *\n * `app/harness-shell.tsx` exists because a `HarnessIntegration` holds React\n * component references and MCP `run` functions. Next cannot serialize those\n * across a server→client boundary, so the `'use client'` mark has to sit ABOVE\n * the point where the registry is injected — hence a client shell of its own\n * rather than a client `RootLayout` called from a server layout. Keeping\n * `app/page.tsx` a server component is what lets `/` prerender static.\n */\nexport const SHELL_FILES: readonly { template: string; dest: string }[] = [\n  { template: 'harness/app/layout.tsx.tmpl', dest: 'app/layout.tsx' },\n  {\n    template: 'harness/app/harness-shell.tsx.tmpl',\n    dest: 'app/harness-shell.tsx',\n  },\n  { template: 'harness/app/page.tsx.tmpl', dest: 'app/page.tsx' },\n  {\n    template: 'harness/app/[slug]/layout.tsx.tmpl',\n    dest: 'app/[slug]/layout.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/widgets/page.tsx.tmpl',\n    dest: 'app/[slug]/widgets/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/widgets/[widgetId]/page.tsx.tmpl',\n    dest: 'app/[slug]/widgets/[widgetId]/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/tile/page.tsx.tmpl',\n    dest: 'app/[slug]/tile/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/activation/page.tsx.tmpl',\n    dest: 'app/[slug]/activation/page.tsx',\n  },\n  {\n    template: 'harness/app/[slug]/triggers/page.tsx.tmpl',\n    dest: 'app/[slug]/triggers/page.tsx',\n  },\n  { template: 'harness/next.config.mjs.tmpl', dest: 'next.config.mjs' },\n  { template: 'harness/postcss.config.mjs.tmpl', dest: 'postcss.config.mjs' },\n  { template: 'harness/tsconfig.json.tmpl', dest: 'tsconfig.json' },\n  { template: 'harness/styles/globals.css.tmpl', dest: 'styles/globals.css' },\n  { template: 'harness/package.json.tmpl', dest: 'package.json' },\n  {\n    template: 'harness/types/team-accounts.d.ts.tmpl',\n    dest: 'types/team-accounts.d.ts',\n  },\n];\n\n/**\n * Packages the shell needs to resolve upward out of the partner's own\n * `node_modules`. The shell declares no dependencies of its own by design, so\n * a missing one shows up as an opaque Next resolution error at dev-server\n * start; checking here turns that into one precondition with one fix.\n */\nexport const REQUIRED_DEPENDENCIES = [\n  HARNESS_PACKAGE,\n  'next',\n  'react',\n  'react-dom',\n  'tailwindcss',\n  '@tailwindcss/postcss',\n] as const;\n\nexport interface WrittenFiles {\n  created: string[];\n  updated: string[];\n  unchanged: string[];\n}\n\n/**\n * Read an installed package's `package.json` out of a project's TOP-LEVEL\n * `node_modules`. Resolved by direct path join rather than `require.resolve`\n * on purpose, for two independent reasons:\n *\n *  - The CLI runs from its own install and must read the version of the copy\n *    in THE CALLER'S project, not one hoisted next to itself.\n *  - Several of the packages this reads (`@ekanos/integration-schema`\n *    included) declare an `exports` map with no `./package.json` subpath, so\n *    `require.resolve('<pkg>/package.json')` throws\n *    `ERR_PACKAGE_PATH_NOT_EXPORTED` under Node's ESM resolver. A plain file\n *    read is not subject to the export map at all.\n *\n * Shared by every \"what does this project have installed?\" check in the\n * CLI — `readInstalledHarness` below, the schema-skew gate, and `upgrade`'s\n * current-toolchain report — so there is exactly one implementation of \"read\n * a package's on-disk version\", not a subtly different one per call site.\n */\nexport interface InstalledPackage {\n  version: string;\n  /** The raw package.json, for callers that need more than the version. */\n  manifest: unknown;\n}\n\nexport function readInstalledPackageManifest(\n  projectDir: string,\n  packageName: string,\n): InstalledPackage | null {\n  const manifestPath = path.join(\n    projectDir,\n    'node_modules',\n    ...packageName.split('/'),\n    'package.json',\n  );\n  if (!fs.existsSync(manifestPath)) return null;\n\n  try {\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    if (typeof version !== 'string' || version.length === 0) return null;\n    return { version, manifest: parsed };\n  } catch (error) {\n    throw preconditionError(\n      `${packageName}'s package.json in node_modules is unreadable: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n      `Reinstall dependencies in ${projectDir} so ${packageName} resolves.`,\n    );\n  }\n}\n\n/** Read the installed `@ekanos/harness` version out of the partner's project. */\nexport type InstalledHarness = InstalledPackage;\n\nexport function readInstalledHarness(\n  projectDir: string,\n): InstalledHarness | null {\n  return readInstalledPackageManifest(projectDir, HARNESS_PACKAGE);\n}\n\n/** Just the installed version, for callers that need nothing else. */\nexport function readInstalledHarnessVersion(projectDir: string): string | null {\n  return readInstalledHarness(projectDir)?.version ?? null;\n}\n\n/** Which of `REQUIRED_DEPENDENCIES` are not installed in the project root. */\nexport function missingDependencies(projectDir: string): string[] {\n  return REQUIRED_DEPENDENCIES.filter(\n    (name) =>\n      !fs.existsSync(\n        path.join(projectDir, 'node_modules', name, 'package.json'),\n      ),\n  );\n}\n\n/**\n * What generated an existing shell.\n *\n * All three fields matter, and recording only `harness` was a real hole: the\n * templates ship with the CLI, so a shell can be stale because the CLI changed\n * while the harness did not. `templates` is the authoritative one — it is a\n * hash of the template sources, so it moves whenever what we generate moves,\n * including for a CLI build that never shipped a version bump.\n */\nexport interface ShellMarker {\n  harness: string;\n  /** null for a legacy bare-version marker written before this was recorded. */\n  cli: string | null;\n  templates: string | null;\n}\n\n/**\n * Three outcomes, not two, because \"no marker\" and \"unreadable marker\" call\n * for opposite responses.\n *\n * A marker's PRESENCE is itself evidence the tree is ours — a squatter does\n * not write `.ekanos-version` — and the likeliest cause of an unreadable one\n * is our own interrupted write. Everything under `.ekanos/harness/` is\n * CLI-owned, gitignored and reproducible from the templates, so regenerating\n * destroys nothing: there is no value at risk to justify charging a partner a\n * confusing `--force` to recover from our own bad write.\n *\n * An ABSENT marker over a non-empty tree is the opposite: nothing says the\n * files are ours, so we refuse. That is the L1 rule and it stays.\n */\nexport type MarkerState =\n  | { kind: 'missing' }\n  | { kind: 'corrupt' }\n  | { kind: 'ok'; marker: ShellMarker };\n\nexport function readShellMarkerState(harnessDir: string): MarkerState {\n  const marker = path.join(harnessDir, VERSION_MARKER);\n  if (classifyPath(marker) !== 'file') return { kind: 'missing' };\n\n  const raw = (readFileNoFollow(harnessDir, marker) ?? '').trim();\n  if (raw.length === 0) return { kind: 'corrupt' };\n\n  const parsed = parseMarker(raw);\n  return parsed === null ? { kind: 'corrupt' } : { kind: 'ok', marker: parsed };\n}\n\nfunction parseMarker(raw: string): ShellMarker | null {\n  // v1 markers were a bare version string. Read them rather than crashing, and\n  // report the unknown fields as null so the shell counts as stale and is\n  // regenerated once — which is the correct outcome for an upgrade.\n  //\n  // It must actually LOOK like a version: without this, any garbage that does\n  // not happen to start with `{` — a truncated write, a stray word — reads as\n  // a legacy marker named after the garbage, and the corrupt-marker path never\n  // fires. That is how a truncated `.ekanos-version` was silently reported as\n  // \"@ekanos/harness truncat → 0.1.0\" instead of \"unreadable\".\n  if (!raw.startsWith('{')) {\n    return /^\\d+\\.\\d+/.test(raw)\n      ? { harness: raw, cli: null, templates: null }\n      : null;\n  }\n\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (typeof parsed !== 'object' || parsed === null) return null;\n    const record = parsed as Record<string, unknown>;\n    const harness = record.harness;\n    if (typeof harness !== 'string') return null;\n    return {\n      harness,\n      cli: typeof record.cli === 'string' ? record.cli : null,\n      templates: typeof record.templates === 'string' ? record.templates : null,\n    };\n  } catch {\n    return null;\n  }\n}\n\n/** The parsed marker, or null when it is absent OR unreadable. */\nexport function readShellMarker(harnessDir: string): ShellMarker | null {\n  const state = readShellMarkerState(harnessDir);\n  return state.kind === 'ok' ? state.marker : null;\n}\n\n/** The `@ekanos/harness` version an existing shell was generated against. */\nexport function readShellVersion(harnessDir: string): string | null {\n  return readShellMarker(harnessDir)?.harness ?? null;\n}\n\nfunction serializeMarker(marker: ShellMarker): string {\n  return `${JSON.stringify(marker, null, 2)}\\n`;\n}\n\n/**\n * Write a generated file, but ONLY when its bytes would change.\n *\n * This is what makes a re-run cheap and a watcher quiet: an unchanged file is\n * not rewritten, so its mtime does not move and Next's dev server does not\n * rebuild. It also means a hand-edit inside the CLI-owned tree is silently\n * corrected on the next run, which is the intended contract for `.ekanos/`.\n */\nexport function writeIfChanged(\n  root: string,\n  destPath: string,\n  contents: string,\n  into: WrittenFiles,\n  label: string,\n  force: boolean,\n): void {\n  // `classifyPath` uses lstat, so a symlink here is reported as a symlink\n  // rather than as whatever it points at — including a DANGLING one, which\n  // `existsSync` would call absent and a plain write would then materialize\n  // outside the project.\n  const kind = classifyPath(destPath);\n  const exists = kind !== 'missing';\n\n  if (\n    !force &&\n    kind === 'file' &&\n    readFileNoFollow(root, destPath) === contents\n  ) {\n    into.unchanged.push(label);\n    return;\n  }\n\n  writeFileNoFollow(root, destPath, contents);\n  (exists ? into.updated : into.created).push(label);\n}\n\nexport interface ScaffoldShellArgs {\n  projectDir: string;\n  slug: string;\n  harnessVersion: string;\n  /** Rewrite every file even when its bytes already match. */\n  force: boolean;\n  /** Extra Tailwind @source globs from ekanos.json, already validated. */\n  sourceGlobs?: readonly string[];\n}\n\nexport interface ScaffoldShellResult extends WrittenFiles {\n  harnessDir: string;\n  /** The version the shell carried before this run — null on a first run. */\n  previousVersion: string | null;\n  /** What generated the previous shell, or null on a first run. */\n  previousMarker: ShellMarker | null;\n  /** True when anything that generated the shell has since changed. */\n  stale: boolean;\n  /**\n   * Which of harness / cli / templates moved. Empty on a first run; this is\n   * what lets `dev` say WHY it regenerated rather than just that it did.\n   */\n  staleReasons: string[];\n}\n\n/**\n * Generate `.ekanos/harness/**` for `harnessVersion`. Every file here is\n * CLI-owned and gitignored, so regeneration needs no permission and asks no\n * question — the partner owns `harness.config.ts` and their integration\n * source, and nothing else.\n */\nexport function scaffoldShell(args: ScaffoldShellArgs): ScaffoldShellResult {\n  const harnessDir = path.join(args.projectDir, HARNESS_DIR);\n  assertShellDirIsOurs(harnessDir, args.force);\n\n  const markerState = readShellMarkerState(harnessDir);\n  const previousMarker = markerState.kind === 'ok' ? markerState.marker : null;\n  const previousVersion = previousMarker?.harness ?? null;\n  const marker: ShellMarker = {\n    harness: args.harnessVersion,\n    cli: cliVersion(),\n    templates: templatesFingerprint(SHELL_FILES.map((f) => f.template)),\n  };\n\n  // A shell is current only if EVERYTHING that produced it is unchanged.\n  // Checking the harness version alone certified shells generated by an older\n  // CLI, against templates that had since moved, as up to date.\n  const staleReasons: string[] = [];\n  if (markerState.kind === 'corrupt') {\n    staleReasons.push(\n      `${VERSION_MARKER} was unreadable, so the existing shell could not be ` +\n        'certified',\n    );\n  }\n  if (previousMarker !== null) {\n    if (previousMarker.harness !== marker.harness) {\n      staleReasons.push(\n        `@ekanos/harness ${previousMarker.harness} → ${marker.harness}`,\n      );\n    }\n    if (previousMarker.cli !== marker.cli) {\n      staleReasons.push(\n        `@ekanos/cli ${previousMarker.cli ?? 'unknown'} → ${marker.cli}`,\n      );\n    }\n    if (previousMarker.templates !== marker.templates) {\n      staleReasons.push('the shell templates changed');\n    }\n  }\n  const stale = staleReasons.length > 0;\n\n  const files: WrittenFiles = { created: [], updated: [], unchanged: [] };\n  const vars = {\n    SLUG: args.slug,\n    SOURCE_GLOBS: renderSourceGlobs(args.sourceGlobs ?? []),\n  };\n\n  for (const { template, dest } of SHELL_FILES) {\n    writeIfChanged(\n      args.projectDir,\n      path.join(harnessDir, dest),\n      readTemplate(template, vars),\n      files,\n      dest,\n      args.force,\n    );\n  }\n\n  writeIfChanged(\n    args.projectDir,\n    path.join(harnessDir, VERSION_MARKER),\n    serializeMarker(marker),\n    files,\n    VERSION_MARKER,\n    args.force,\n  );\n\n  return {\n    ...files,\n    harnessDir,\n    previousVersion,\n    previousMarker,\n    stale,\n    staleReasons,\n  };\n}\n\n/**\n * Turn validated `sourceGlobs` into the `@source` lines the generated\n * stylesheet carries, each relative to the shell's `styles/` directory.\n *\n * Tailwind never scans what it is not pointed at, and a glob that matches\n * nothing fails silently — so an integration living outside the default\n * layout renders completely unstyled with no error anywhere. That is what\n * `sourceGlobs` is for, and until now it was parsed and thrown away.\n */\nfunction renderSourceGlobs(globs: readonly string[]): string {\n  if (globs.length === 0) return '';\n  const lines = globs.map((glob) => `@source '${SHELL_TO_PROJECT}${glob}';`);\n  return `\\n/* From \"sourceGlobs\" in ekanos.json. */\\n${lines.join('\\n')}\\n`;\n}\n\n/** From `.ekanos/harness/styles/` back up to the project root. */\nconst SHELL_TO_PROJECT = '../../../';\n\n/**\n * Establish that `.ekanos/harness` is a tree WE generated before writing a\n * single byte into it, and return the version marker it carried.\n *\n * Path location alone is not ownership. A directory that exists but carries no\n * `.ekanos-version` was put there by something else — a partner, another tool,\n * a symlink — and clobbering it because it happens to sit at the path we like\n * is the same class of mistake as following a symlink. An empty directory is\n * fine (that is just `mkdir -p` having run), and `--force` is the explicit\n * override.\n *\n * Runs BEFORE `bootstrapHarnessConfig` in `dev`, so a shell that cannot be\n * written leaves the project completely untouched rather than half-scaffolded.\n */\nexport function assertShellDirIsOurs(\n  harnessDir: string,\n  force: boolean,\n): string | null {\n  const kind = classifyPath(harnessDir);\n\n  if (kind === 'symlink') {\n    throw invalidStateError(\n      `${harnessDir} is a symlink, so \"ekanos dev\" will not write through it.`,\n      `Delete ${harnessDir} and re-run \"ekanos dev\" — the shell is generated, ` +\n        'so nothing is lost.',\n    );\n  }\n\n  if (kind !== 'missing' && kind !== 'directory') {\n    throw invalidStateError(\n      `${harnessDir} exists and is not a directory.`,\n      `Move or delete ${harnessDir}, then re-run \"ekanos dev\".`,\n    );\n  }\n\n  if (kind === 'missing') return null;\n\n  const state = readShellMarkerState(harnessDir);\n\n  // A marker we wrote, however mangled, still identifies the tree as ours.\n  if (state.kind === 'ok') return state.marker.harness;\n  if (state.kind === 'corrupt' || force) return null;\n\n  if (fs.readdirSync(harnessDir).length === 0) return null;\n\n  throw invalidStateError(\n    `${harnessDir} already contains files but no ${VERSION_MARKER} marker, ` +\n      'so it was not generated by \"ekanos dev\".',\n    `Delete ${harnessDir} if you do not need it, or pass --force to ` +\n      'overwrite it. Everything \"ekanos dev\" generates is reproducible; ' +\n      'anything else in there is not.',\n  );\n}\n\n/**\n * The module specifier `harness.config.ts` uses to import the partner's\n * integration: the `entry` from ekanos.json, made relative and extension-free.\n * \"src/integration.ts\" → \"src/integration\".\n */\nexport function entryImportSpecifier(entry: string): string {\n  const normalized = entry.split(path.sep).join('/').replace(/^\\.\\//, '');\n  return normalized.replace(/\\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/, '');\n}\n\n/**\n * The same specifier as a JavaScript string LITERAL, ready to drop into a\n * generated `import` statement.\n *\n * `entry` is attacker-influenced data from `ekanos.json`, and a POSIX filename\n * may legally contain a quote or a newline. Interpolating it raw would let a\n * crafted-but-valid path close the string and append statements to the module\n * we generate. `JSON.stringify` produces a correctly escaped literal, which is\n * the actual fix; the explicit rejection below is a second line that also\n * gives the partner a comprehensible error instead of a bizarre filename\n * silently appearing, escaped, in their config.\n *\n * This does not cross a trust boundary on its own — a partner's own code runs\n * unsandboxed anyway — but \"the templates cannot be injected into\" is a claim\n * we make, and it should be true.\n */\nexport function entryImportLiteral(entry: string): string {\n  const specifier = entryImportSpecifier(entry);\n\n  // eslint-disable-next-line no-control-regex\n  if (/[\"'`\\\\\\n\\r\\u0000-\\u001f]/.test(specifier)) {\n    throw preconditionError(\n      `The \"entry\" in ekanos.json contains characters that cannot appear in ` +\n        `an import specifier: ${JSON.stringify(specifier)}.`,\n      'Rename the file so its path has no quotes, backslashes or control ' +\n        'characters, then update \"entry\" in ekanos.json to match.',\n    );\n  }\n\n  return JSON.stringify(`./${specifier}`);\n}\n\nexport interface BootstrapConfigResult {\n  /** True only when this run created the file. */\n  bootstrapped: boolean;\n  configPath: string;\n}\n\n/**\n * Write a starter `harness.config.ts` at the project root — ONCE.\n *\n * An existing file is left strictly alone, byte for byte, and no flag changes\n * that: it is the one harness file the partner owns, it is git-tracked, and\n * regenerating it would throw away their fixtures. `--force` regenerates the\n * shell, never this.\n */\nexport function bootstrapHarnessConfig(\n  projectDir: string,\n  integrations: readonly { slug: string; entry: string }[],\n): BootstrapConfigResult {\n  const configPath = path.join(projectDir, HARNESS_CONFIG_FILENAME);\n  const kind = classifyPath(configPath);\n\n  // A symlink here — including a dangling one, which `existsSync` reports as\n  // absent — would have us write through to its target. Since this file is the\n  // partner's to own, the only safe answer is to touch nothing and say why.\n  if (kind === 'symlink') {\n    throw invalidStateError(\n      `${configPath} is a symlink, so \"ekanos dev\" will not write through it.`,\n      `Replace ${configPath} with a real file (or delete it to have one ` +\n        'generated), then re-run \"ekanos dev\".',\n    );\n  }\n\n  if (kind !== 'missing') {\n    return { bootstrapped: false, configPath };\n  }\n\n  writeFileNoFollow(projectDir, configPath, renderHarnessConfig(integrations));\n\n  return { bootstrapped: true, configPath };\n}\n\n/**\n * Render the starter registry for EVERY integration the project declares.\n *\n * The harness registry is an array and `ekanos.json` can now hold a list, so a\n * project's second integration reaches the harness the same way its first\n * does. Each entry imports the definition under a distinct local identifier\n * derived from its slug, because two `integration` imports in one module do\n * not compile.\n */\nfunction renderHarnessConfig(\n  integrations: readonly { slug: string; entry: string }[],\n): string {\n  const imports: string[] = [];\n  const entries: string[] = [];\n\n  for (const integration of integrations) {\n    const ident = identifierForSlug(integration.slug);\n    imports.push(\n      `import { integration as ${ident} } from ${entryImportLiteral(\n        integration.entry,\n      )};`,\n    );\n    entries.push(\n      readTemplate('harness.config.entry.ts.tmpl', {\n        IDENT: ident,\n        SLUG: integration.slug,\n      }),\n    );\n  }\n\n  return readTemplate('harness.config.ts.tmpl', {\n    INTEGRATION_IMPORTS: imports.join('\\n'),\n    INTEGRATION_ENTRIES: entries.join(''),\n  });\n}\n\n/**\n * \"acme-crm\" → \"acmeCrm\". A slug is kebab-case by schema, so this only has to\n * handle hyphens, and a leading digit is impossible.\n */\nexport function identifierForSlug(slug: string): string {\n  const camel = slug.replace(/-([a-z0-9])/g, (_, char: string) =>\n    char.toUpperCase(),\n  );\n  return /^[0-9]/.test(camel) ? `i${camel}` : camel;\n}\n\n/**\n * Add `.ekanos/` to the project `.gitignore`, exactly once.\n *\n * Matching is line-wise over the spellings git treats as the same rule\n * (`.ekanos`, `.ekanos/`, `/.ekanos/`), so re-running never appends a\n * duplicate — the thing that makes a scaffold verb safe to run in a loop.\n * A negation (`!.ekanos/`) is deliberately NOT treated as a match: the\n * partner meant to un-ignore it, and we do not fight that silently.\n */\nexport function ensureGitignoreEntry(projectDir: string): boolean {\n  const gitignorePath = path.join(projectDir, '.gitignore');\n  const block = `# Ekanos dev harness — generated by \"ekanos dev\", never edited by hand\\n${GITIGNORE_ENTRY}\\n`;\n\n  const kind = classifyPath(gitignorePath);\n\n  if (kind === 'symlink') {\n    throw invalidStateError(\n      `${gitignorePath} is a symlink, so \"ekanos dev\" will not append to it.`,\n      `Add \"${GITIGNORE_ENTRY}\" to your real .gitignore yourself, or replace ` +\n        `${gitignorePath} with a regular file, then re-run \"ekanos dev\".`,\n    );\n  }\n\n  if (kind === 'missing') {\n    writeFileNoFollow(projectDir, gitignorePath, block);\n    return true;\n  }\n\n  const existing = readFileNoFollow(projectDir, gitignorePath) ?? '';\n  if (gitignoreCovers(existing)) return false;\n\n  const separator =\n    existing.length === 0 || existing.endsWith('\\n') ? '' : '\\n';\n  appendFileNoFollow(projectDir, gitignorePath, `${separator}\\n${block}`);\n  return true;\n}\n\nfunction gitignoreCovers(source: string): boolean {\n  const equivalents = new Set(['.ekanos', '.ekanos/', '/.ekanos', '/.ekanos/']);\n  return source\n    .split('\\n')\n    .map((line) => line.trim())\n    .some((line) => equivalents.has(line));\n}\n"]}

package/dist/index.js

@@ -7,6 +7,7 @@ import { runPublish } from './commands/publish.js';
 import { runSources } from './commands/sources.js';
 import { runStatus } from './commands/status.js';
 import { runTest } from './commands/test.js';
+import { runUpgrade } from './commands/upgrade.js';
 import { runUse } from './commands/use.js';
 import { runValidate } from './commands/validate.js';
 import { runWhoami } from './commands/whoami.js';
@@ -70,6 +71,15 @@ const COMMAND_SPECS = {
         dir: { type: 'string' },
         yes: { type: 'boolean' },
     },
+    upgrade: {
+        dir: { type: 'string' },
+        host: { type: 'string' },
+        check: { type: 'boolean' },
+        yes: { type: 'boolean' },
+        // `--no-verify` is the negation of this — parse-argv's `--no-<bool>`
+        // convention (same as `--no-json`/`--no-start`), not a flag of its own.
+        verify: { type: 'boolean' },
+    },
 };
 /** Commands that take a positional argument, and what it means. Every other command is positional-free. */
 const POSITIONAL_COMMANDS = {
@@ -92,8 +102,19 @@ const USAGE = [
     '  sources    List every source you hold a developer/admin seat on',
     '  use        Set this project\'s publish target ("ekanos use <source-slug>")',
     '  publish    Validate, pack and submit the integration to a Fusion host',
+    '  upgrade    Move this toolchain to a coherent target version, with',
+    '             verify-and-rollback (--check --yes --no-verify --host <url>)',
     '',
-    'Host resolution (logout, whoami, status, sources, use, publish):',
+    'Keeping the toolchain current:',
+    '  validate, dev and publish all check for a newer @ekanos/cli in the',
+    '  background (never blocking, silenced by EKANOS_NO_UPDATE_CHECK) and warn',
+    '  on stderr when one exists. Run "ekanos upgrade --check" any time a',
+    '  validate finding smells like version skew (an unrecognized-key error you',
+    '  are confident is correct) — it is read-only and safe to run freely. A',
+    '  bare "ekanos upgrade" MUTATES the project (installs the target versions,',
+    '  verifies with validate + the test script, rolls back on any failure).',
+    '',
+    'Host resolution (logout, whoami, status, sources, use, publish, upgrade):',
     '  --host, else EKANOS_HOST, else the "host" field in ekanos.json, else the',
     '  sole stored login. "ekanos publish" saves host and source to ekanos.json.',
     '  "ekanos login" never reads ekanos.json for a host (--host, else',
@@ -186,7 +207,7 @@ export async function run(argv, options = {}) {
                     yes: parsed.flags.yes === true,
                 });
             case 'validate':
-                return await runValidate(ctx, { dir });
+                return await runValidate(ctx, { dir, env });
             case 'dev':
                 return await runDev(ctx, {
                     dir,
@@ -194,6 +215,7 @@ export async function run(argv, options = {}) {
                     host: parsed.flags.host,
                     force: parsed.flags.force === true,
                     start: parsed.flags.start,
+                    env,
                 });
             case 'test':
                 return await runTest(ctx, { dir, passthrough: parsed.passthrough });
@@ -246,6 +268,17 @@ export async function run(argv, options = {}) {
                     stdinIsTTY: options.stdinIsTTY,
                     confirm: options.confirm,
                 });
+            case 'upgrade':
+                return await runUpgrade(ctx, {
+                    dir,
+                    host: parsed.flags.host,
+                    env,
+                    check: parsed.flags.check === true,
+                    yes: parsed.flags.yes === true,
+                    noVerify: parsed.flags.verify === false,
+                    stdinIsTTY: options.stdinIsTTY,
+                    confirm: options.confirm,
+                });
             default:
                 // Unreachable — COMMANDS gate above — but keeps the switch total.
                 throw usageError(`Unknown command "${command}".`, `Run one of: ${COMMANDS.join(', ')}.`);