@ekanos/cli 0.1.0

package/dist/harness-scaffold.d.ts

@@ -0,0 +1,212 @@
+/** The dependency that owns every line of harness behaviour. */
+export declare const HARNESS_PACKAGE = "@ekanos/harness";
+/** Where the generated shell lives, relative to the project root. */
+export declare const HARNESS_DIR: string;
+/** The single `.gitignore` line that covers the whole generated tree. */
+export declare const GITIGNORE_ENTRY = ".ekanos/";
+/**
+ * The staleness marker, inside the generated tree so deleting the tree also
+ * deletes the marker. Holds the `@ekanos/harness` version that generated the
+ * shell — a version bump means the shell may be wired against an older export
+ * surface, so it is regenerated.
+ */
+export declare const VERSION_MARKER = ".ekanos-version";
+/** The partner-owned registry, at the PROJECT ROOT. Never regenerated. */
+export declare const HARNESS_CONFIG_FILENAME = "harness.config.ts";
+/**
+ * Every file in the generated shell: bundled template → path inside
+ * `.ekanos/harness/`. The nine route files are mechanically derivable from the
+ * export map alone — which is the test of whether the package boundary is in
+ * the right place. If a shell file ever needs a judgment call, the boundary
+ * has moved, not the template.
+ *
+ * `app/harness-shell.tsx` exists because a `HarnessIntegration` holds React
+ * component references and MCP `run` functions. Next cannot serialize those
+ * across a server→client boundary, so the `'use client'` mark has to sit ABOVE
+ * the point where the registry is injected — hence a client shell of its own
+ * rather than a client `RootLayout` called from a server layout. Keeping
+ * `app/page.tsx` a server component is what lets `/` prerender static.
+ */
+export declare const SHELL_FILES: readonly {
+    template: string;
+    dest: string;
+}[];
+/**
+ * Packages the shell needs to resolve upward out of the partner's own
+ * `node_modules`. The shell declares no dependencies of its own by design, so
+ * a missing one shows up as an opaque Next resolution error at dev-server
+ * start; checking here turns that into one precondition with one fix.
+ */
+export declare const REQUIRED_DEPENDENCIES: readonly ["@ekanos/harness", "next", "react", "react-dom", "tailwindcss", "@tailwindcss/postcss"];
+export interface WrittenFiles {
+    created: string[];
+    updated: string[];
+    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.
+ */
+export interface InstalledHarness {
+    version: string;
+    /** The raw package.json, so compatibility can read its `ekanos` block. */
+    manifest: unknown;
+}
+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;
+/** Which of `REQUIRED_DEPENDENCIES` are not installed in the project root. */
+export declare function missingDependencies(projectDir: string): string[];
+/**
+ * What generated an existing shell.
+ *
+ * All three fields matter, and recording only `harness` was a real hole: the
+ * templates ship with the CLI, so a shell can be stale because the CLI changed
+ * while the harness did not. `templates` is the authoritative one — it is a
+ * hash of the template sources, so it moves whenever what we generate moves,
+ * including for a CLI build that never shipped a version bump.
+ */
+export interface ShellMarker {
+    harness: string;
+    /** null for a legacy bare-version marker written before this was recorded. */
+    cli: string | null;
+    templates: string | null;
+}
+/**
+ * Three outcomes, not two, because "no marker" and "unreadable marker" call
+ * for opposite responses.
+ *
+ * A marker's PRESENCE is itself evidence the tree is ours — a squatter does
+ * not write `.ekanos-version` — and the likeliest cause of an unreadable one
+ * is our own interrupted write. Everything under `.ekanos/harness/` is
+ * CLI-owned, gitignored and reproducible from the templates, so regenerating
+ * destroys nothing: there is no value at risk to justify charging a partner a
+ * confusing `--force` to recover from our own bad write.
+ *
+ * An ABSENT marker over a non-empty tree is the opposite: nothing says the
+ * files are ours, so we refuse. That is the L1 rule and it stays.
+ */
+export type MarkerState = {
+    kind: 'missing';
+} | {
+    kind: 'corrupt';
+} | {
+    kind: 'ok';
+    marker: ShellMarker;
+};
+export declare function readShellMarkerState(harnessDir: string): MarkerState;
+/** The parsed marker, or null when it is absent OR unreadable. */
+export declare function readShellMarker(harnessDir: string): ShellMarker | null;
+/** The `@ekanos/harness` version an existing shell was generated against. */
+export declare function readShellVersion(harnessDir: string): string | null;
+/**
+ * Write a generated file, but ONLY when its bytes would change.
+ *
+ * This is what makes a re-run cheap and a watcher quiet: an unchanged file is
+ * not rewritten, so its mtime does not move and Next's dev server does not
+ * rebuild. It also means a hand-edit inside the CLI-owned tree is silently
+ * corrected on the next run, which is the intended contract for `.ekanos/`.
+ */
+export declare function writeIfChanged(root: string, destPath: string, contents: string, into: WrittenFiles, label: string, force: boolean): void;
+export interface ScaffoldShellArgs {
+    projectDir: string;
+    slug: string;
+    harnessVersion: string;
+    /** Rewrite every file even when its bytes already match. */
+    force: boolean;
+    /** Extra Tailwind @source globs from ekanos.json, already validated. */
+    sourceGlobs?: readonly string[];
+}
+export interface ScaffoldShellResult extends WrittenFiles {
+    harnessDir: string;
+    /** The version the shell carried before this run — null on a first run. */
+    previousVersion: string | null;
+    /** What generated the previous shell, or null on a first run. */
+    previousMarker: ShellMarker | null;
+    /** True when anything that generated the shell has since changed. */
+    stale: boolean;
+    /**
+     * Which of harness / cli / templates moved. Empty on a first run; this is
+     * what lets `dev` say WHY it regenerated rather than just that it did.
+     */
+    staleReasons: string[];
+}
+/**
+ * Generate `.ekanos/harness/**` for `harnessVersion`. Every file here is
+ * CLI-owned and gitignored, so regeneration needs no permission and asks no
+ * question — the partner owns `harness.config.ts` and their integration
+ * source, and nothing else.
+ */
+export declare function scaffoldShell(args: ScaffoldShellArgs): ScaffoldShellResult;
+/**
+ * Establish that `.ekanos/harness` is a tree WE generated before writing a
+ * single byte into it, and return the version marker it carried.
+ *
+ * Path location alone is not ownership. A directory that exists but carries no
+ * `.ekanos-version` was put there by something else — a partner, another tool,
+ * a symlink — and clobbering it because it happens to sit at the path we like
+ * is the same class of mistake as following a symlink. An empty directory is
+ * fine (that is just `mkdir -p` having run), and `--force` is the explicit
+ * override.
+ *
+ * Runs BEFORE `bootstrapHarnessConfig` in `dev`, so a shell that cannot be
+ * written leaves the project completely untouched rather than half-scaffolded.
+ */
+export declare function assertShellDirIsOurs(harnessDir: string, force: boolean): string | null;
+/**
+ * The module specifier `harness.config.ts` uses to import the partner's
+ * integration: the `entry` from ekanos.json, made relative and extension-free.
+ * "src/integration.ts" → "src/integration".
+ */
+export declare function entryImportSpecifier(entry: string): string;
+/**
+ * The same specifier as a JavaScript string LITERAL, ready to drop into a
+ * generated `import` statement.
+ *
+ * `entry` is attacker-influenced data from `ekanos.json`, and a POSIX filename
+ * may legally contain a quote or a newline. Interpolating it raw would let a
+ * crafted-but-valid path close the string and append statements to the module
+ * we generate. `JSON.stringify` produces a correctly escaped literal, which is
+ * the actual fix; the explicit rejection below is a second line that also
+ * gives the partner a comprehensible error instead of a bizarre filename
+ * silently appearing, escaped, in their config.
+ *
+ * This does not cross a trust boundary on its own — a partner's own code runs
+ * unsandboxed anyway — but "the templates cannot be injected into" is a claim
+ * we make, and it should be true.
+ */
+export declare function entryImportLiteral(entry: string): string;
+export interface BootstrapConfigResult {
+    /** True only when this run created the file. */
+    bootstrapped: boolean;
+    configPath: string;
+}
+/**
+ * Write a starter `harness.config.ts` at the project root — ONCE.
+ *
+ * An existing file is left strictly alone, byte for byte, and no flag changes
+ * that: it is the one harness file the partner owns, it is git-tracked, and
+ * regenerating it would throw away their fixtures. `--force` regenerates the
+ * shell, never this.
+ */
+export declare function bootstrapHarnessConfig(projectDir: string, integrations: readonly {
+    slug: string;
+    entry: string;
+}[]): BootstrapConfigResult;
+/**
+ * "acme-crm" → "acmeCrm". A slug is kebab-case by schema, so this only has to
+ * handle hyphens, and a leading digit is impossible.
+ */
+export declare function identifierForSlug(slug: string): string;
+/**
+ * Add `.ekanos/` to the project `.gitignore`, exactly once.
+ *
+ * Matching is line-wise over the spellings git treats as the same rule
+ * (`.ekanos`, `.ekanos/`, `/.ekanos/`), so re-running never appends a
+ * duplicate — the thing that makes a scaffold verb safe to run in a loop.
+ * A negation (`!.ekanos/`) is deliberately NOT treated as a match: the
+ * partner meant to un-ignore it, and we do not fight that silently.
+ */
+export declare function ensureGitignoreEntry(projectDir: string): boolean;

package/dist/harness-scaffold.js

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