@ekanos/cli 0.1.0

package/dist/merge-manifest.js

@@ -0,0 +1,124 @@
+/**
+ * Merging the scaffold's package.json into one a partner already has.
+ *
+ * The ordinary way to start a project is `npm init -y`, and doing that before
+ * `ekanos init` used to cost the partner every dependency, every script, and
+ * leave `"type": "commonjs"` under ESM/TypeScript sources — reported only as
+ * `skipped package.json (already exists)`. A skip that expensive has to either
+ * do the work or say precisely what it did not do.
+ *
+ * The rule here is ADDITIVE ONLY: a value the partner already set is never
+ * changed, because their pinned version or their own `test` script is a
+ * decision, not an omission. Anything we would have set but cannot becomes a
+ * note carrying its own remediation.
+ */
+const RECORD_FIELDS = ['dependencies', 'devDependencies', 'scripts'];
+/**
+ * Values `npm init -y` writes that are placeholders, not decisions.
+ *
+ * Treating npm's stub `test` script as a real choice left the ordinary
+ * `npm init -y` → `ekanos init` path with a `test` script that exits 1, so
+ * `ekanos test` — the second command a partner runs — failed on a fresh
+ * scaffold. This is the one narrow exception to additive-only, and it is safe
+ * because the string is npm's own fixed literal, not something a partner types.
+ */
+const NPM_PLACEHOLDERS = {
+    'scripts.test': ['echo "Error: no test specified" && exit 1'],
+};
+/**
+ * `npm init -y` writes `"type": "commonjs"` EXPLICITLY (npm 11.6.2), so
+ * "only set it when absent" never fires for the ordinary way a partner starts
+ * a project — it is the mainline, not an edge case.
+ *
+ * It is npm boilerplate by exactly the same argument as the stub `test` script
+ * above, and treating one as boilerplate and the other as a considered choice
+ * was inconsistent. The decisive point: the files this scaffolder writes are
+ * ESM TypeScript and cannot load under `commonjs`, so leaving it would mean
+ * writing files that do not run. A scaffolder that does that has not
+ * scaffolded anything.
+ *
+ * So it is overwritten, loudly — with a note saying what changed and what to
+ * do if the project really does have CommonJS sources.
+ */
+const REQUIRED_TYPE = 'module';
+function isPlaceholder(field, name, value) {
+    var _a;
+    return ((_a = NPM_PLACEHOLDERS[`${field}.${name}`]) !== null && _a !== void 0 ? _a : []).includes(value);
+}
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return {};
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === 'string')
+            out[key] = entry;
+    }
+    return out;
+}
+/**
+ * Merge `template` into `existing`, adding only what is missing.
+ *
+ * `type` is the one field that cannot be resolved additively: the scaffold's
+ * sources are ESM TypeScript, so they need `"type": "module"`, but flipping an
+ * explicit `"commonjs"` could break code the partner already has. Absent, we
+ * set it; set to anything else, we leave it and say what will break.
+ */
+export function mergeManifest(existing, template) {
+    const manifest = Object.assign({}, existing);
+    const added = [];
+    const kept = [];
+    const notes = [];
+    for (const field of RECORD_FIELDS) {
+        const wanted = asRecord(template[field]);
+        if (Object.keys(wanted).length === 0)
+            continue;
+        const current = asRecord(existing[field]);
+        const merged = Object.assign({}, current);
+        let replacedPlaceholder = false;
+        for (const [name, value] of Object.entries(wanted)) {
+            const existingValue = current[name];
+            if (existingValue !== undefined) {
+                if (!isPlaceholder(field, name, existingValue)) {
+                    kept.push(`${field}.${name}`);
+                    continue;
+                }
+                replacedPlaceholder = true;
+            }
+            merged[name] = value;
+            added.push(`${field}.${name}`);
+        }
+        if (replacedPlaceholder ||
+            Object.keys(merged).length > Object.keys(current).length) {
+            manifest[field] = sortKeys(merged);
+        }
+    }
+    const existingType = existing.type;
+    if (existingType === REQUIRED_TYPE) {
+        kept.push('type');
+    }
+    else {
+        manifest.type = REQUIRED_TYPE;
+        added.push('type');
+        if (existingType !== undefined) {
+            notes.push({
+                field: 'type',
+                message: `Changed "type" from ${JSON.stringify(existingType)} to "module" in ` +
+                    'package.json. The scaffolded sources are ES modules and Node ' +
+                    'cannot load them otherwise, so leaving it would have written files ' +
+                    'that do not run.',
+                hint: 'If this project has CommonJS sources of its own, revert that line ' +
+                    'and put your integration in its own package instead — the two ' +
+                    'module systems cannot share one package.json.',
+            });
+        }
+    }
+    return { manifest, added, kept, notes, changed: added.length > 0 };
+}
+function sortKeys(record) {
+    return Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+/** Serialize a manifest the way npm does — 2-space indent, trailing newline. */
+export function serializeManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+//# sourceMappingURL=merge-manifest.js.map

package/dist/merge-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-manifest.js","sourceRoot":"","sources":["../src/merge-manifest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Merging the scaffold's package.json into one a partner already has.\n *\n * The ordinary way to start a project is `npm init -y`, and doing that before\n * `ekanos init` used to cost the partner every dependency, every script, and\n * leave `\"type\": \"commonjs\"` under ESM/TypeScript sources — reported only as\n * `skipped package.json (already exists)`. A skip that expensive has to either\n * do the work or say precisely what it did not do.\n *\n * The rule here is ADDITIVE ONLY: a value the partner already set is never\n * changed, because their pinned version or their own `test` script is a\n * decision, not an omission. Anything we would have set but cannot becomes a\n * note carrying its own remediation.\n */\n\nexport interface Manifest {\n  [key: string]: unknown;\n}\n\nexport interface ManifestNote {\n  field: string;\n  message: string;\n  hint: string;\n}\n\nexport interface MergeResult {\n  manifest: Manifest;\n  /** Dotted paths this merge added, e.g. `dependencies.@ekanos/sdk`. */\n  added: string[];\n  /** Fields left alone because the partner had already set them. */\n  kept: string[];\n  /** Things a partner must decide or do themselves. */\n  notes: ManifestNote[];\n  /** False when nothing changed, so the caller can skip the write entirely. */\n  changed: boolean;\n}\n\nconst RECORD_FIELDS = ['dependencies', 'devDependencies', 'scripts'] as const;\n\n/**\n * Values `npm init -y` writes that are placeholders, not decisions.\n *\n * Treating npm's stub `test` script as a real choice left the ordinary\n * `npm init -y` → `ekanos init` path with a `test` script that exits 1, so\n * `ekanos test` — the second command a partner runs — failed on a fresh\n * scaffold. This is the one narrow exception to additive-only, and it is safe\n * because the string is npm's own fixed literal, not something a partner types.\n */\nconst NPM_PLACEHOLDERS: Record<string, readonly string[]> = {\n  'scripts.test': ['echo \"Error: no test specified\" && exit 1'],\n};\n\n/**\n * `npm init -y` writes `\"type\": \"commonjs\"` EXPLICITLY (npm 11.6.2), so\n * \"only set it when absent\" never fires for the ordinary way a partner starts\n * a project — it is the mainline, not an edge case.\n *\n * It is npm boilerplate by exactly the same argument as the stub `test` script\n * above, and treating one as boilerplate and the other as a considered choice\n * was inconsistent. The decisive point: the files this scaffolder writes are\n * ESM TypeScript and cannot load under `commonjs`, so leaving it would mean\n * writing files that do not run. A scaffolder that does that has not\n * scaffolded anything.\n *\n * So it is overwritten, loudly — with a note saying what changed and what to\n * do if the project really does have CommonJS sources.\n */\nconst REQUIRED_TYPE = 'module';\n\nfunction isPlaceholder(field: string, name: string, value: string): boolean {\n  return (NPM_PLACEHOLDERS[`${field}.${name}`] ?? []).includes(value);\n}\n\nfunction asRecord(value: unknown): Record<string, string> {\n  if (typeof value !== 'object' || value === null) return {};\n  const out: Record<string, string> = {};\n  for (const [key, entry] of Object.entries(value)) {\n    if (typeof entry === 'string') out[key] = entry;\n  }\n  return out;\n}\n\n/**\n * Merge `template` into `existing`, adding only what is missing.\n *\n * `type` is the one field that cannot be resolved additively: the scaffold's\n * sources are ESM TypeScript, so they need `\"type\": \"module\"`, but flipping an\n * explicit `\"commonjs\"` could break code the partner already has. Absent, we\n * set it; set to anything else, we leave it and say what will break.\n */\nexport function mergeManifest(\n  existing: Manifest,\n  template: Manifest,\n): MergeResult {\n  const manifest: Manifest = { ...existing };\n  const added: string[] = [];\n  const kept: string[] = [];\n  const notes: ManifestNote[] = [];\n\n  for (const field of RECORD_FIELDS) {\n    const wanted = asRecord(template[field]);\n    if (Object.keys(wanted).length === 0) continue;\n\n    const current = asRecord(existing[field]);\n    const merged = { ...current };\n    let replacedPlaceholder = false;\n    for (const [name, value] of Object.entries(wanted)) {\n      const existingValue = current[name];\n      if (existingValue !== undefined) {\n        if (!isPlaceholder(field, name, existingValue)) {\n          kept.push(`${field}.${name}`);\n          continue;\n        }\n        replacedPlaceholder = true;\n      }\n      merged[name] = value;\n      added.push(`${field}.${name}`);\n    }\n\n    if (\n      replacedPlaceholder ||\n      Object.keys(merged).length > Object.keys(current).length\n    ) {\n      manifest[field] = sortKeys(merged);\n    }\n  }\n\n  const existingType = existing.type;\n  if (existingType === REQUIRED_TYPE) {\n    kept.push('type');\n  } else {\n    manifest.type = REQUIRED_TYPE;\n    added.push('type');\n\n    if (existingType !== undefined) {\n      notes.push({\n        field: 'type',\n        message:\n          `Changed \"type\" from ${JSON.stringify(existingType)} to \"module\" in ` +\n          'package.json. The scaffolded sources are ES modules and Node ' +\n          'cannot load them otherwise, so leaving it would have written files ' +\n          'that do not run.',\n        hint:\n          'If this project has CommonJS sources of its own, revert that line ' +\n          'and put your integration in its own package instead — the two ' +\n          'module systems cannot share one package.json.',\n      });\n    }\n  }\n\n  return { manifest, added, kept, notes, changed: added.length > 0 };\n}\n\nfunction sortKeys(record: Record<string, string>): Record<string, string> {\n  return Object.fromEntries(\n    Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),\n  );\n}\n\n/** Serialize a manifest the way npm does — 2-space indent, trailing newline. */\nexport function serializeManifest(manifest: Manifest): string {\n  return `${JSON.stringify(manifest, null, 2)}\\n`;\n}\n"]}

package/dist/package-manager.d.ts

@@ -0,0 +1,25 @@
+export type PackageManagerName = 'pnpm' | 'yarn' | 'bun' | 'npm';
+export interface PackageManager {
+    name: PackageManagerName;
+    bin: string;
+}
+/**
+ * Detect the package manager from the lockfile in the project root, falling
+ * back to npm. Only the lockfile is authoritative — we do not parse
+ * `packageManager` fields or probe $PATH.
+ */
+export declare function detectPackageManager(projectDir: string): PackageManager;
+/**
+ * The argv for running a project-local binary through a package manager.
+ *
+ * The harness shell has no `node_modules` of its own — `next` lives in the
+ * partner's project root and resolves upward — so we cannot spawn the bin
+ * directly by path without guessing a layout (pnpm's is not npm's). Every
+ * package manager already knows how to find it; each just spells it
+ * differently.
+ */
+export declare function execArgs(pm: PackageManager, bin: string, args: readonly string[]): string[];
+/** The same invocation as a display string, for logs and the JSON envelope. */
+export declare function formatCommand(bin: string, args: readonly string[]): string;
+/** The install command that adds `packages` as dev dependencies. */
+export declare function installCommand(pm: PackageManager, packages: readonly string[]): string;

package/dist/package-manager.js

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Detect the package manager from the lockfile in the project root, falling
+ * back to npm. Only the lockfile is authoritative — we do not parse
+ * `packageManager` fields or probe $PATH.
+ */
+export function detectPackageManager(projectDir) {
+    const has = (file) => fs.existsSync(path.join(projectDir, file));
+    if (has('pnpm-lock.yaml'))
+        return { name: 'pnpm', bin: 'pnpm' };
+    if (has('yarn.lock'))
+        return { name: 'yarn', bin: 'yarn' };
+    if (has('bun.lockb') || has('bun.lock'))
+        return { name: 'bun', bin: 'bun' };
+    return { name: 'npm', bin: 'npm' };
+}
+/**
+ * The argv for running a project-local binary through a package manager.
+ *
+ * The harness shell has no `node_modules` of its own — `next` lives in the
+ * partner's project root and resolves upward — so we cannot spawn the bin
+ * directly by path without guessing a layout (pnpm's is not npm's). Every
+ * package manager already knows how to find it; each just spells it
+ * differently.
+ */
+export function execArgs(pm, bin, args) {
+    switch (pm.name) {
+        case 'pnpm':
+            return ['exec', bin, ...args];
+        case 'yarn':
+            return [bin, ...args];
+        case 'bun':
+            return ['x', bin, ...args];
+        case 'npm':
+            return ['exec', '--', bin, ...args];
+    }
+}
+/** The same invocation as a display string, for logs and the JSON envelope. */
+export function formatCommand(bin, args) {
+    return [bin, ...args].join(' ');
+}
+/** The install command that adds `packages` as dev dependencies. */
+export function installCommand(pm, packages) {
+    const spec = packages.join(' ');
+    switch (pm.name) {
+        case 'pnpm':
+            return `pnpm add -D ${spec}`;
+        case 'yarn':
+            return `yarn add -D ${spec}`;
+        case 'bun':
+            return `bun add -d ${spec}`;
+        case 'npm':
+            return `npm install -D ${spec}`;
+    }
+}
+//# sourceMappingURL=package-manager.js.map

package/dist/package-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manager.js","sourceRoot":"","sources":["../src/package-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AASlC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;IACzE,IAAI,GAAG,CAAC,gBAAgB,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAChE,IAAI,GAAG,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAC3D,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAC5E,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,EAAkB,EAClB,GAAW,EACX,IAAuB;IAEvB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAChC,KAAK,MAAM;YACT,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QACxB,KAAK,KAAK;YACR,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC7B,KAAK,KAAK;YACR,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACxC,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAuB;IAChE,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAC5B,EAAkB,EAClB,QAA2B;IAE3B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,eAAe,IAAI,EAAE,CAAC;QAC/B,KAAK,MAAM;YACT,OAAO,eAAe,IAAI,EAAE,CAAC;QAC/B,KAAK,KAAK;YACR,OAAO,cAAc,IAAI,EAAE,CAAC;QAC9B,KAAK,KAAK;YACR,OAAO,kBAAkB,IAAI,EAAE,CAAC;IACpC,CAAC;AACH,CAAC","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nexport type PackageManagerName = 'pnpm' | 'yarn' | 'bun' | 'npm';\n\nexport interface PackageManager {\n  name: PackageManagerName;\n  bin: string;\n}\n\n/**\n * Detect the package manager from the lockfile in the project root, falling\n * back to npm. Only the lockfile is authoritative — we do not parse\n * `packageManager` fields or probe $PATH.\n */\nexport function detectPackageManager(projectDir: string): PackageManager {\n  const has = (file: string) => fs.existsSync(path.join(projectDir, file));\n  if (has('pnpm-lock.yaml')) return { name: 'pnpm', bin: 'pnpm' };\n  if (has('yarn.lock')) return { name: 'yarn', bin: 'yarn' };\n  if (has('bun.lockb') || has('bun.lock')) return { name: 'bun', bin: 'bun' };\n  return { name: 'npm', bin: 'npm' };\n}\n\n/**\n * The argv for running a project-local binary through a package manager.\n *\n * The harness shell has no `node_modules` of its own — `next` lives in the\n * partner's project root and resolves upward — so we cannot spawn the bin\n * directly by path without guessing a layout (pnpm's is not npm's). Every\n * package manager already knows how to find it; each just spells it\n * differently.\n */\nexport function execArgs(\n  pm: PackageManager,\n  bin: string,\n  args: readonly string[],\n): string[] {\n  switch (pm.name) {\n    case 'pnpm':\n      return ['exec', bin, ...args];\n    case 'yarn':\n      return [bin, ...args];\n    case 'bun':\n      return ['x', bin, ...args];\n    case 'npm':\n      return ['exec', '--', bin, ...args];\n  }\n}\n\n/** The same invocation as a display string, for logs and the JSON envelope. */\nexport function formatCommand(bin: string, args: readonly string[]): string {\n  return [bin, ...args].join(' ');\n}\n\n/** The install command that adds `packages` as dev dependencies. */\nexport function installCommand(\n  pm: PackageManager,\n  packages: readonly string[],\n): string {\n  const spec = packages.join(' ');\n  switch (pm.name) {\n    case 'pnpm':\n      return `pnpm add -D ${spec}`;\n    case 'yarn':\n      return `yarn add -D ${spec}`;\n    case 'bun':\n      return `bun add -d ${spec}`;\n    case 'npm':\n      return `npm install -D ${spec}`;\n  }\n}\n"]}

package/dist/parse-argv.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A hand-rolled argv parser — deliberately NOT commander/yargs/citty. The
+ * agent-native envelope needs total control over how an unknown flag is
+ * reported (exit 2 through the JSON envelope with a hint, never a library's own
+ * `console.error` + `process.exit`), and it must never abbreviate, never
+ * auto-print help, and never guess. Every off-ramp routes through `usageError`.
+ *
+ * Supports: `--flag` (boolean), `--key=value`, `--key value`, `--no-<bool>`
+ * negation, positionals, and a `--` passthrough where everything after the
+ * first bare `--` is captured verbatim (that argv belongs to `test`'s child).
+ */
+export type FlagType = 'boolean' | 'string';
+export interface FlagSpec {
+    type: FlagType;
+    /** Optional default applied when the flag is absent. */
+    default?: string | boolean;
+}
+export type FlagSpecs = Record<string, FlagSpec>;
+export interface ParsedArgs {
+    positionals: string[];
+    flags: Record<string, string | boolean>;
+    /** Raw argv after the first standalone `--`, unparsed. */
+    passthrough: string[];
+    /** True when a standalone `--` was present (even with nothing after it). */
+    hasPassthrough: boolean;
+}
+export declare function parseArgv(argv: readonly string[], specs: FlagSpecs): ParsedArgs;

package/dist/parse-argv.js

@@ -0,0 +1,74 @@
+import { usageError } from './errors.js';
+export function parseArgv(argv, specs) {
+    var _a;
+    const positionals = [];
+    const flags = {};
+    const passthrough = [];
+    let hasPassthrough = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        // Everything after the first standalone `--` is passthrough, verbatim.
+        if (token === '--') {
+            hasPassthrough = true;
+            passthrough.push(...argv.slice(i + 1));
+            break;
+        }
+        // A bare positional (does not start with `-`), or a lone `-`.
+        if (!token.startsWith('--')) {
+            if (token.startsWith('-') && token !== '-') {
+                throw usageError(`Unknown flag "${token}". Short flags are not supported.`, `Use the long form (e.g. "--json"). Run "ekanos --help" for the ` +
+                    `full flag list.`);
+            }
+            positionals.push(token);
+            continue;
+        }
+        // A long flag. Split an inline `--key=value`.
+        const body = token.slice(2);
+        const eq = body.indexOf('=');
+        const hasInlineValue = eq !== -1;
+        let name = hasInlineValue ? body.slice(0, eq) : body;
+        const inlineValue = hasInlineValue ? body.slice(eq + 1) : undefined;
+        // `--no-<bool>` negation.
+        let negated = false;
+        if (!hasInlineValue && name.startsWith('no-')) {
+            const candidate = name.slice(3);
+            if (((_a = specs[candidate]) === null || _a === void 0 ? void 0 : _a.type) === 'boolean') {
+                negated = true;
+                name = candidate;
+            }
+        }
+        const spec = specs[name];
+        if (!spec) {
+            throw usageError(`Unknown flag "--${hasInlineValue ? name : body}".`, `Remove it or check the spelling. Run "ekanos --help" (or ` +
+                `"ekanos <command> --help") for the accepted flags.`);
+        }
+        if (spec.type === 'boolean') {
+            if (hasInlineValue) {
+                throw usageError(`Flag "--${name}" is a boolean and does not take a value.`, `Pass "--${name}" to enable it or "--no-${name}" to disable it — ` +
+                    `not "--${name}=${inlineValue !== null && inlineValue !== void 0 ? inlineValue : ''}".`);
+            }
+            flags[name] = !negated;
+            continue;
+        }
+        // String flag: value is inline (`--key=value`) or the next token
+        // (`--key value`).
+        if (hasInlineValue) {
+            flags[name] = inlineValue;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined || next === '--') {
+            throw usageError(`Flag "--${name}" expects a value.`, `Provide one as "--${name} <value>" or "--${name}=<value>".`);
+        }
+        flags[name] = next;
+        i++;
+    }
+    // Apply declared defaults for flags the user did not pass.
+    for (const [name, spec] of Object.entries(specs)) {
+        if (spec.default !== undefined && !(name in flags)) {
+            flags[name] = spec.default;
+        }
+    }
+    return { positionals, flags, passthrough, hasPassthrough };
+}
+//# sourceMappingURL=parse-argv.js.map

package/dist/parse-argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-argv.js","sourceRoot":"","sources":["../src/parse-argv.ts"],"names":[],"mappings":"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","sourcesContent":["import { usageError } from './errors';\n\n/**\n * A hand-rolled argv parser — deliberately NOT commander/yargs/citty. The\n * agent-native envelope needs total control over how an unknown flag is\n * reported (exit 2 through the JSON envelope with a hint, never a library's own\n * `console.error` + `process.exit`), and it must never abbreviate, never\n * auto-print help, and never guess. Every off-ramp routes through `usageError`.\n *\n * Supports: `--flag` (boolean), `--key=value`, `--key value`, `--no-<bool>`\n * negation, positionals, and a `--` passthrough where everything after the\n * first bare `--` is captured verbatim (that argv belongs to `test`'s child).\n */\n\nexport type FlagType = 'boolean' | 'string';\n\nexport interface FlagSpec {\n  type: FlagType;\n  /** Optional default applied when the flag is absent. */\n  default?: string | boolean;\n}\n\nexport type FlagSpecs = Record<string, FlagSpec>;\n\nexport interface ParsedArgs {\n  positionals: string[];\n  flags: Record<string, string | boolean>;\n  /** Raw argv after the first standalone `--`, unparsed. */\n  passthrough: string[];\n  /** True when a standalone `--` was present (even with nothing after it). */\n  hasPassthrough: boolean;\n}\n\nexport function parseArgv(\n  argv: readonly string[],\n  specs: FlagSpecs,\n): ParsedArgs {\n  const positionals: string[] = [];\n  const flags: Record<string, string | boolean> = {};\n  const passthrough: string[] = [];\n  let hasPassthrough = false;\n\n  for (let i = 0; i < argv.length; i++) {\n    const token = argv[i]!;\n\n    // Everything after the first standalone `--` is passthrough, verbatim.\n    if (token === '--') {\n      hasPassthrough = true;\n      passthrough.push(...argv.slice(i + 1));\n      break;\n    }\n\n    // A bare positional (does not start with `-`), or a lone `-`.\n    if (!token.startsWith('--')) {\n      if (token.startsWith('-') && token !== '-') {\n        throw usageError(\n          `Unknown flag \"${token}\". Short flags are not supported.`,\n          `Use the long form (e.g. \"--json\"). Run \"ekanos --help\" for the ` +\n            `full flag list.`,\n        );\n      }\n      positionals.push(token);\n      continue;\n    }\n\n    // A long flag. Split an inline `--key=value`.\n    const body = token.slice(2);\n    const eq = body.indexOf('=');\n    const hasInlineValue = eq !== -1;\n    let name = hasInlineValue ? body.slice(0, eq) : body;\n    const inlineValue = hasInlineValue ? body.slice(eq + 1) : undefined;\n\n    // `--no-<bool>` negation.\n    let negated = false;\n    if (!hasInlineValue && name.startsWith('no-')) {\n      const candidate = name.slice(3);\n      if (specs[candidate]?.type === 'boolean') {\n        negated = true;\n        name = candidate;\n      }\n    }\n\n    const spec = specs[name];\n    if (!spec) {\n      throw usageError(\n        `Unknown flag \"--${hasInlineValue ? name : body}\".`,\n        `Remove it or check the spelling. Run \"ekanos --help\" (or ` +\n          `\"ekanos <command> --help\") for the accepted flags.`,\n      );\n    }\n\n    if (spec.type === 'boolean') {\n      if (hasInlineValue) {\n        throw usageError(\n          `Flag \"--${name}\" is a boolean and does not take a value.`,\n          `Pass \"--${name}\" to enable it or \"--no-${name}\" to disable it — ` +\n            `not \"--${name}=${inlineValue ?? ''}\".`,\n        );\n      }\n      flags[name] = !negated;\n      continue;\n    }\n\n    // String flag: value is inline (`--key=value`) or the next token\n    // (`--key value`).\n    if (hasInlineValue) {\n      flags[name] = inlineValue!;\n      continue;\n    }\n\n    const next = argv[i + 1];\n    if (next === undefined || next === '--') {\n      throw usageError(\n        `Flag \"--${name}\" expects a value.`,\n        `Provide one as \"--${name} <value>\" or \"--${name}=<value>\".`,\n      );\n    }\n    flags[name] = next;\n    i++;\n  }\n\n  // Apply declared defaults for flags the user did not pass.\n  for (const [name, spec] of Object.entries(specs)) {\n    if (spec.default !== undefined && !(name in flags)) {\n      flags[name] = spec.default;\n    }\n  }\n\n  return { positionals, flags, passthrough, hasPassthrough };\n}\n"]}

package/dist/project-checks.d.ts

@@ -0,0 +1,18 @@
+import type { Finding } from '@ekanos/integration-schema';
+/**
+ * Project-level integrity checks that read files in the project root (next to
+ * ekanos.json), NOT the integration definition. These are deliberately kept
+ * out of the schema package's definition collectors: the definition is valid or
+ * not on its own; whether the partner's TEST runner is configured to load the
+ * published SDK is a property of THIS project.
+ *
+ * The highest-value check: a partner's vitest must inline `@ekanos/sdk`. The
+ * published SDK dist imports extensionless `next/link`, so without
+ * `test.server.deps.inline: ['@ekanos/sdk']` vitest fails to load the SDK, the
+ * test file silently imports nothing, and vitest reports green over zero tests.
+ *
+ * The check is conditional: if the project declares NO vitest/vite config at
+ * all, there is nothing to assert (the `test` verb would surface a missing
+ * runner on its own). If a config IS present, it MUST inline the SDK.
+ */
+export declare function collectProjectFindings(projectDir: string): Finding[];

package/dist/project-checks.js

@@ -0,0 +1,77 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const VITEST_CONFIG_NAMES = [
+    'vitest.config.ts',
+    'vitest.config.mts',
+    'vitest.config.cts',
+    'vitest.config.js',
+    'vitest.config.mjs',
+    'vitest.config.cjs',
+    'vite.config.ts',
+    'vite.config.mts',
+    'vite.config.js',
+    'vite.config.mjs',
+];
+/** The exact block the hint quotes — the one config that makes the SDK load. */
+const REQUIRED_INLINE_BLOCK = [
+    'test: {',
+    '  server: {',
+    '    deps: {',
+    "      inline: ['@ekanos/sdk'],",
+    '    },',
+    '  },',
+    '}',
+].join('\n');
+/**
+ * Project-level integrity checks that read files in the project root (next to
+ * ekanos.json), NOT the integration definition. These are deliberately kept
+ * out of the schema package's definition collectors: the definition is valid or
+ * not on its own; whether the partner's TEST runner is configured to load the
+ * published SDK is a property of THIS project.
+ *
+ * The highest-value check: a partner's vitest must inline `@ekanos/sdk`. The
+ * published SDK dist imports extensionless `next/link`, so without
+ * `test.server.deps.inline: ['@ekanos/sdk']` vitest fails to load the SDK, the
+ * test file silently imports nothing, and vitest reports green over zero tests.
+ *
+ * The check is conditional: if the project declares NO vitest/vite config at
+ * all, there is nothing to assert (the `test` verb would surface a missing
+ * runner on its own). If a config IS present, it MUST inline the SDK.
+ */
+export function collectProjectFindings(projectDir) {
+    const configFile = VITEST_CONFIG_NAMES.map((name) => path.join(projectDir, name)).find((candidate) => fs.existsSync(candidate));
+    if (!configFile)
+        return [];
+    const source = fs.readFileSync(configFile, 'utf8');
+    if (vitestInlinesSdk(source))
+        return [];
+    return [
+        {
+            check: 'project.vitest-inline-sdk',
+            severity: 'error',
+            file: configFile,
+            message: `${path.basename(configFile)} does not inline @ekanos/sdk. The ` +
+                `published SDK dist imports extensionless "next/link", so without ` +
+                `test.server.deps.inline including "@ekanos/sdk", vitest cannot load ` +
+                `the SDK — the test file imports nothing and vitest reports green ` +
+                `over zero tests.`,
+            hint: `Add this to your vitest config's defineConfig so the SDK is ` +
+                `transformed for the test runner:\n\n${REQUIRED_INLINE_BLOCK}`,
+        },
+    ];
+}
+/**
+ * True when the config source contains an `inline: [ … ]` array that lists
+ * `@ekanos/sdk`. Textual on purpose — evaluating a partner's config module
+ * would run arbitrary code; a lint-style scan does not.
+ */
+function vitestInlinesSdk(source) {
+    var _a;
+    const inlineArrayPattern = /inline\s*:\s*\[([\s\S]*?)\]/g;
+    for (let match = inlineArrayPattern.exec(source); match !== null; match = inlineArrayPattern.exec(source)) {
+        if (/['"]@ekanos\/sdk['"]/.test((_a = match[1]) !== null && _a !== void 0 ? _a : ''))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=project-checks.js.map

package/dist/project-checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-checks.js","sourceRoot":"","sources":["../src/project-checks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,mBAAmB,GAAG;IAC1B,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,gBAAgB;IAChB,iBAAiB;IACjB,gBAAgB;IAChB,iBAAiB;CAClB,CAAC;AAEF,gFAAgF;AAChF,MAAM,qBAAqB,GAAG;IAC5B,SAAS;IACT,aAAa;IACb,aAAa;IACb,gCAAgC;IAChC,QAAQ;IACR,MAAM;IACN,GAAG;CACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,MAAM,UAAU,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAClD,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAC5B,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhD,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAE3B,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACnD,IAAI,gBAAgB,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IAExC,OAAO;QACL;YACE,KAAK,EAAE,2BAA2B;YAClC,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,UAAU;YAChB,OAAO,EACL,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,oCAAoC;gBAChE,mEAAmE;gBACnE,sEAAsE;gBACtE,mEAAmE;gBACnE,kBAAkB;YACpB,IAAI,EACF,8DAA8D;gBAC9D,uCAAuC,qBAAqB,EAAE;SACjE;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,MAAc;;IACtC,MAAM,kBAAkB,GAAG,8BAA8B,CAAC;IAC1D,KACE,IAAI,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAC3C,KAAK,KAAK,IAAI,EACd,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EACvC,CAAC;QACD,IAAI,sBAAsB,CAAC,IAAI,CAAC,MAAA,KAAK,CAAC,CAAC,CAAC,mCAAI,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import type { Finding } from '@ekanos/integration-schema';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nconst VITEST_CONFIG_NAMES = [\n  'vitest.config.ts',\n  'vitest.config.mts',\n  'vitest.config.cts',\n  'vitest.config.js',\n  'vitest.config.mjs',\n  'vitest.config.cjs',\n  'vite.config.ts',\n  'vite.config.mts',\n  'vite.config.js',\n  'vite.config.mjs',\n];\n\n/** The exact block the hint quotes — the one config that makes the SDK load. */\nconst REQUIRED_INLINE_BLOCK = [\n  'test: {',\n  '  server: {',\n  '    deps: {',\n  \"      inline: ['@ekanos/sdk'],\",\n  '    },',\n  '  },',\n  '}',\n].join('\\n');\n\n/**\n * Project-level integrity checks that read files in the project root (next to\n * ekanos.json), NOT the integration definition. These are deliberately kept\n * out of the schema package's definition collectors: the definition is valid or\n * not on its own; whether the partner's TEST runner is configured to load the\n * published SDK is a property of THIS project.\n *\n * The highest-value check: a partner's vitest must inline `@ekanos/sdk`. The\n * published SDK dist imports extensionless `next/link`, so without\n * `test.server.deps.inline: ['@ekanos/sdk']` vitest fails to load the SDK, the\n * test file silently imports nothing, and vitest reports green over zero tests.\n *\n * The check is conditional: if the project declares NO vitest/vite config at\n * all, there is nothing to assert (the `test` verb would surface a missing\n * runner on its own). If a config IS present, it MUST inline the SDK.\n */\nexport function collectProjectFindings(projectDir: string): Finding[] {\n  const configFile = VITEST_CONFIG_NAMES.map((name) =>\n    path.join(projectDir, name),\n  ).find((candidate) => fs.existsSync(candidate));\n\n  if (!configFile) return [];\n\n  const source = fs.readFileSync(configFile, 'utf8');\n  if (vitestInlinesSdk(source)) return [];\n\n  return [\n    {\n      check: 'project.vitest-inline-sdk',\n      severity: 'error',\n      file: configFile,\n      message:\n        `${path.basename(configFile)} does not inline @ekanos/sdk. The ` +\n        `published SDK dist imports extensionless \"next/link\", so without ` +\n        `test.server.deps.inline including \"@ekanos/sdk\", vitest cannot load ` +\n        `the SDK — the test file imports nothing and vitest reports green ` +\n        `over zero tests.`,\n      hint:\n        `Add this to your vitest config's defineConfig so the SDK is ` +\n        `transformed for the test runner:\\n\\n${REQUIRED_INLINE_BLOCK}`,\n    },\n  ];\n}\n\n/**\n * True when the config source contains an `inline: [ … ]` array that lists\n * `@ekanos/sdk`. Textual on purpose — evaluating a partner's config module\n * would run arbitrary code; a lint-style scan does not.\n */\nfunction vitestInlinesSdk(source: string): boolean {\n  const inlineArrayPattern = /inline\\s*:\\s*\\[([\\s\\S]*?)\\]/g;\n  for (\n    let match = inlineArrayPattern.exec(source);\n    match !== null;\n    match = inlineArrayPattern.exec(source)\n  ) {\n    if (/['\"]@ekanos\\/sdk['\"]/.test(match[1] ?? '')) return true;\n  }\n  return false;\n}\n"]}

package/dist/project.d.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+/** One integration: the pair that addresses a definition module. */
+declare const IntegrationEntrySchema: z.ZodObject<{
+    slug: z.ZodString;
+    entry: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    slug: string;
+    entry: string;
+}, {
+    slug: string;
+    entry: string;
+}>;
+export type IntegrationEntry = z.infer<typeof IntegrationEntrySchema>;
+/**
+ * `ekanos.json` — the project contract. Written by `init`, read by `validate`,
+ * `dev` and `test`.
+ *
+ * Two shapes, because a project can hold more than one integration and the
+ * single-integration form is what `init` writes and what most projects keep:
+ *
+ * ```json
+ * { "slug": "acme-crm", "entry": "src/integration.ts" }
+ *
+ * { "integrations": [
+ *     { "slug": "acme-crm",    "entry": "src/crm.ts" },
+ *     { "slug": "acme-billing", "entry": "src/billing.ts" }
+ * ] }
+ * ```
+ *
+ * A second integration used to be invisible to the CLI entirely — the harness
+ * registry is an array and `collectCollisionFindings` exists precisely to
+ * cross-check several definitions against each other, but `validate` could
+ * only ever see one. Both forms normalise to the same list, so nothing
+ * downstream has to know which was written.
+ */
+export declare const EkanosProjectSchema: z.ZodEffects<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    entry: z.ZodOptional<z.ZodString>;
+    integrations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        entry: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        slug: string;
+        entry: string;
+    }, {
+        slug: string;
+        entry: string;
+    }>, "many">>;
+    sourceGlobs: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    slug?: string | undefined;
+    entry?: string | undefined;
+    $schema?: string | undefined;
+    integrations?: {
+        slug: string;
+        entry: string;
+    }[] | undefined;
+    sourceGlobs?: string[] | undefined;
+}, {
+    slug?: string | undefined;
+    entry?: string | undefined;
+    $schema?: string | undefined;
+    integrations?: {
+        slug: string;
+        entry: string;
+    }[] | undefined;
+    sourceGlobs?: string[] | undefined;
+}>, {
+    slug?: string | undefined;
+    entry?: string | undefined;
+    $schema?: string | undefined;
+    integrations?: {
+        slug: string;
+        entry: string;
+    }[] | undefined;
+    sourceGlobs?: string[] | undefined;
+}, {
+    slug?: string | undefined;
+    entry?: string | undefined;
+    $schema?: string | undefined;
+    integrations?: {
+        slug: string;
+        entry: string;
+    }[] | undefined;
+    sourceGlobs?: string[] | undefined;
+}>;
+export type EkanosProject = z.infer<typeof EkanosProjectSchema>;
+/** Both `ekanos.json` shapes, flattened to the one the CLI works in. */
+export declare function projectIntegrations(project: EkanosProject): IntegrationEntry[];
+export declare const EKANOS_CONFIG_FILENAME = "ekanos.json";
+/** One integration from `ekanos.json`, with its entry resolved on disk. */
+export interface LoadedIntegration {
+    slug: string;
+    entry: string;
+    /** Absolute path to the resolved entry module. */
+    entryPath: string;
+}
+export interface LoadedProject {
+    project: EkanosProject;
+    /** Absolute path to the directory containing ekanos.json (the project root). */
+    projectDir: string;
+    /** Absolute path to ekanos.json itself. */
+    configPath: string;
+    /** Every integration the project declares, in declaration order. */
+    integrations: LoadedIntegration[];
+    /**
+     * The first integration. It names the generated harness shell and is what a
+     * single-integration project means by "the" integration; nothing else
+     * privileges it.
+     */
+    primary: LoadedIntegration;
+}
+/**
+ * Read and validate ekanos.json from a directory. Missing file → not-found
+ * (exit 6); malformed JSON or a schema violation → precondition failed
+ * (exit 9), because a project the CLI cannot even read is a precondition for
+ * every verb, not a definition-level validation finding.
+ */
+export declare function loadProject(dir: string): LoadedProject;
+/**
+ * Fail unless the project is an ES module package.
+ *
+ * `init` sets `"type": "module"` and says so, but a warning can be scrolled
+ * past, and a partner who misses it gets a confusing module-resolution error
+ * from deep inside Node or Next rather than a sentence naming the problem.
+ * This is the backstop: one precondition, in the loader every verb after
+ * `init` goes through, so the failure is loud and says what to do.
+ *
+ * `init` deliberately does NOT come through here — it is the thing that fixes
+ * this state.
+ *
+ * A project with no package.json at all is left alone: `dev` reports missing
+ * dependencies with its own better message, and `validate`/`test` have their
+ * own preconditions. We only assert on a manifest that exists and disagrees.
+ */
+export declare function assertEsmProject(projectDir: string): void;
+/** Serialize an ekanos.json body with a trailing newline. */
+export declare function serializeProject(project: EkanosProject): string;
+export {};