@ekanos/cli 0.1.0

package/dist/project.js

@@ -0,0 +1,228 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { notFoundError, preconditionError } from './errors.js';
+const SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
+    message: 'slug must be kebab-case ([a-z0-9] segments separated by single hyphens), e.g. "acme-crm".',
+});
+const EntrySchema = z
+    .string()
+    .min(1, { message: 'entry must be a path to the integration module.' });
+/**
+ * Extra Tailwind content globs, for an integration that does not live under
+ * the default layout. They are interpolated into the generated
+ * `styles/globals.css` as `@source` lines, so they are validated as
+ * DATA-IN-CSS: project-relative, no escaping the project, and none of the
+ * characters that could close the string or the surrounding comment.
+ *
+ * Being strict here is deliberate. A glob that matches nothing costs a partner
+ * a silently unstyled integration; a glob that is rejected costs them one
+ * clear error.
+ */
+const SOURCE_GLOB_PATTERN = /^[A-Za-z0-9_\-./*{},[\]!]+$/;
+const SourceGlobSchema = z
+    .string()
+    .min(1, { message: 'a sourceGlobs entry must not be empty.' })
+    .max(200, { message: 'a sourceGlobs entry must be under 200 characters.' })
+    .regex(SOURCE_GLOB_PATTERN, {
+    message: 'a sourceGlobs entry may contain only letters, digits and _-./*{},[]! ' +
+        '— it is written verbatim into the generated stylesheet.',
+})
+    .refine((glob) => !glob.startsWith('/'), {
+    message: 'a sourceGlobs entry must be relative to the project root.',
+})
+    .refine((glob) => !glob.split('/').includes('..'), {
+    message: 'a sourceGlobs entry must not escape the project root with "..".',
+});
+/** One integration: the pair that addresses a definition module. */
+const IntegrationEntrySchema = z
+    .object({ slug: SlugSchema, entry: EntrySchema })
+    .strict();
+/**
+ * `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 const EkanosProjectSchema = z
+    .object({
+    $schema: z.string().optional(),
+    slug: SlugSchema.optional(),
+    entry: EntrySchema.optional(),
+    integrations: z.array(IntegrationEntrySchema).optional(),
+    // There is deliberately no `harness` field. One existed, accepted by the
+    // schema and read by nothing — the same accept-and-ignore that made
+    // `sourceGlobs` cost a partner a silently unstyled integration. `.strict()`
+    // now rejects it by name, which is the honest answer until something
+    // actually consumes it.
+    sourceGlobs: z.array(SourceGlobSchema).optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const hasSingle = value.slug !== undefined || value.entry !== undefined;
+    const hasList = value.integrations !== undefined;
+    if (hasSingle && hasList) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'use either the single form ({ slug, entry }) or the list form ' +
+                '({ integrations: [...] }), not both — two places to declare the ' +
+                'same thing is how they drift apart.',
+        });
+        return;
+    }
+    if (hasList) {
+        if (value.integrations.length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['integrations'],
+                message: 'integrations must list at least one integration.',
+            });
+        }
+        const seen = new Set();
+        value.integrations.forEach((entry, index) => {
+            if (seen.has(entry.slug)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['integrations', index, 'slug'],
+                    message: `duplicate slug "${entry.slug}" — every integration in a ` +
+                        'project needs its own, since the slug addresses it everywhere.',
+                });
+            }
+            seen.add(entry.slug);
+        });
+        return;
+    }
+    if (value.slug === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['slug'],
+            message: 'slug is required (or use "integrations": [...]).',
+        });
+    }
+    if (value.entry === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['entry'],
+            message: 'entry is required (or use "integrations": [...]).',
+        });
+    }
+});
+/** Both `ekanos.json` shapes, flattened to the one the CLI works in. */
+export function projectIntegrations(project) {
+    if (project.integrations !== undefined)
+        return [...project.integrations];
+    return [{ slug: project.slug, entry: project.entry }];
+}
+export const EKANOS_CONFIG_FILENAME = 'ekanos.json';
+/**
+ * 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 function loadProject(dir) {
+    var _a;
+    const projectDir = path.resolve(dir);
+    const configPath = path.join(projectDir, EKANOS_CONFIG_FILENAME);
+    if (!fs.existsSync(configPath)) {
+        throw notFoundError(`No ${EKANOS_CONFIG_FILENAME} found in ${projectDir}.`, `Run "ekanos init" here first, or change into the project directory ` +
+            `that contains ${EKANOS_CONFIG_FILENAME}.`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch (error) {
+        throw preconditionError(`${EKANOS_CONFIG_FILENAME} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, `Fix the JSON syntax in ${configPath}.`);
+    }
+    const result = EkanosProjectSchema.safeParse(raw);
+    if (!result.success) {
+        const first = result.error.issues[0];
+        const where = first && first.path.length > 0 ? first.path.join('.') : '(root)';
+        throw preconditionError(`${EKANOS_CONFIG_FILENAME} is invalid at "${where}": ${(_a = first === null || first === void 0 ? void 0 : first.message) !== null && _a !== void 0 ? _a : 'schema violation'}`, `Correct ${configPath} so it matches the ekanos.json schema ` +
+            `({ slug, entry } or { integrations: [...] }, plus optional ` +
+            `harness and sourceGlobs).`);
+    }
+    const project = result.data;
+    const integrations = projectIntegrations(project).map((declared) => {
+        const entryPath = path.resolve(projectDir, declared.entry);
+        if (!fs.existsSync(entryPath)) {
+            throw notFoundError(`entry "${declared.entry}" for "${declared.slug}" resolves to ` +
+                `${entryPath}, which does not exist.`, `Point it at your integration module (the file that exports the ` +
+                `defineIntegration(...) result) in ${configPath}.`);
+        }
+        return { slug: declared.slug, entry: declared.entry, entryPath };
+    });
+    assertEsmProject(projectDir);
+    return {
+        project,
+        projectDir,
+        configPath,
+        integrations,
+        primary: integrations[0],
+    };
+}
+/**
+ * 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 function assertEsmProject(projectDir) {
+    const manifestPath = path.join(projectDir, 'package.json');
+    if (!fs.existsSync(manifestPath))
+        return;
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (_a) {
+        // Malformed JSON is npm's problem to report, not ours to guess at; the
+        // partner will hit it on their next install with a better message.
+        return;
+    }
+    const declared = typeof manifest === 'object' && manifest !== null
+        ? manifest.type
+        : undefined;
+    if (declared === 'module')
+        return;
+    throw preconditionError(declared === undefined
+        ? `${manifestPath} does not declare "type": "module", so Node treats ` +
+            'your integration as CommonJS and cannot load it.'
+        : `${manifestPath} declares "type": ${JSON.stringify(declared)}, but the ` +
+            'integration sources are ES modules and Node cannot load them.', `Set "type": "module" in ${manifestPath}. If this project has CommonJS ` +
+        'sources of its own, put your integration in its own package instead — ' +
+        'the two module systems cannot share one package.json. Re-running ' +
+        '"ekanos init" also fixes this.');
+}
+/** Serialize an ekanos.json body with a trailing newline. */
+export function serializeProject(project) {
+    return `${JSON.stringify(project, null, 2)}\n`;
+}
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { z } from 'zod';\n\nimport { notFoundError, preconditionError } from './errors';\n\nconst SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {\n  message:\n    'slug must be kebab-case ([a-z0-9] segments separated by single hyphens), e.g. \"acme-crm\".',\n});\n\nconst EntrySchema = z\n  .string()\n  .min(1, { message: 'entry must be a path to the integration module.' });\n\n/**\n * Extra Tailwind content globs, for an integration that does not live under\n * the default layout. They are interpolated into the generated\n * `styles/globals.css` as `@source` lines, so they are validated as\n * DATA-IN-CSS: project-relative, no escaping the project, and none of the\n * characters that could close the string or the surrounding comment.\n *\n * Being strict here is deliberate. A glob that matches nothing costs a partner\n * a silently unstyled integration; a glob that is rejected costs them one\n * clear error.\n */\nconst SOURCE_GLOB_PATTERN = /^[A-Za-z0-9_\\-./*{},[\\]!]+$/;\n\nconst SourceGlobSchema = z\n  .string()\n  .min(1, { message: 'a sourceGlobs entry must not be empty.' })\n  .max(200, { message: 'a sourceGlobs entry must be under 200 characters.' })\n  .regex(SOURCE_GLOB_PATTERN, {\n    message:\n      'a sourceGlobs entry may contain only letters, digits and _-./*{},[]! ' +\n      '— it is written verbatim into the generated stylesheet.',\n  })\n  .refine((glob) => !glob.startsWith('/'), {\n    message: 'a sourceGlobs entry must be relative to the project root.',\n  })\n  .refine((glob) => !glob.split('/').includes('..'), {\n    message: 'a sourceGlobs entry must not escape the project root with \"..\".',\n  });\n\n/** One integration: the pair that addresses a definition module. */\nconst IntegrationEntrySchema = z\n  .object({ slug: SlugSchema, entry: EntrySchema })\n  .strict();\n\nexport type IntegrationEntry = z.infer<typeof IntegrationEntrySchema>;\n\n/**\n * `ekanos.json` — the project contract. Written by `init`, read by `validate`,\n * `dev` and `test`.\n *\n * Two shapes, because a project can hold more than one integration and the\n * single-integration form is what `init` writes and what most projects keep:\n *\n * ```json\n * { \"slug\": \"acme-crm\", \"entry\": \"src/integration.ts\" }\n *\n * { \"integrations\": [\n *     { \"slug\": \"acme-crm\",    \"entry\": \"src/crm.ts\" },\n *     { \"slug\": \"acme-billing\", \"entry\": \"src/billing.ts\" }\n * ] }\n * ```\n *\n * A second integration used to be invisible to the CLI entirely — the harness\n * registry is an array and `collectCollisionFindings` exists precisely to\n * cross-check several definitions against each other, but `validate` could\n * only ever see one. Both forms normalise to the same list, so nothing\n * downstream has to know which was written.\n */\nexport const EkanosProjectSchema = z\n  .object({\n    $schema: z.string().optional(),\n    slug: SlugSchema.optional(),\n    entry: EntrySchema.optional(),\n    integrations: z.array(IntegrationEntrySchema).optional(),\n    // There is deliberately no `harness` field. One existed, accepted by the\n    // schema and read by nothing — the same accept-and-ignore that made\n    // `sourceGlobs` cost a partner a silently unstyled integration. `.strict()`\n    // now rejects it by name, which is the honest answer until something\n    // actually consumes it.\n    sourceGlobs: z.array(SourceGlobSchema).optional(),\n  })\n  .strict()\n  .superRefine((value, ctx) => {\n    const hasSingle = value.slug !== undefined || value.entry !== undefined;\n    const hasList = value.integrations !== undefined;\n\n    if (hasSingle && hasList) {\n      ctx.addIssue({\n        code: z.ZodIssueCode.custom,\n        message:\n          'use either the single form ({ slug, entry }) or the list form ' +\n          '({ integrations: [...] }), not both — two places to declare the ' +\n          'same thing is how they drift apart.',\n      });\n      return;\n    }\n\n    if (hasList) {\n      if (value.integrations!.length === 0) {\n        ctx.addIssue({\n          code: z.ZodIssueCode.custom,\n          path: ['integrations'],\n          message: 'integrations must list at least one integration.',\n        });\n      }\n      const seen = new Set<string>();\n      value.integrations!.forEach((entry, index) => {\n        if (seen.has(entry.slug)) {\n          ctx.addIssue({\n            code: z.ZodIssueCode.custom,\n            path: ['integrations', index, 'slug'],\n            message:\n              `duplicate slug \"${entry.slug}\" — every integration in a ` +\n              'project needs its own, since the slug addresses it everywhere.',\n          });\n        }\n        seen.add(entry.slug);\n      });\n      return;\n    }\n\n    if (value.slug === undefined) {\n      ctx.addIssue({\n        code: z.ZodIssueCode.custom,\n        path: ['slug'],\n        message: 'slug is required (or use \"integrations\": [...]).',\n      });\n    }\n    if (value.entry === undefined) {\n      ctx.addIssue({\n        code: z.ZodIssueCode.custom,\n        path: ['entry'],\n        message: 'entry is required (or use \"integrations\": [...]).',\n      });\n    }\n  });\n\nexport type EkanosProject = z.infer<typeof EkanosProjectSchema>;\n\n/** Both `ekanos.json` shapes, flattened to the one the CLI works in. */\nexport function projectIntegrations(\n  project: EkanosProject,\n): IntegrationEntry[] {\n  if (project.integrations !== undefined) return [...project.integrations];\n  return [{ slug: project.slug!, entry: project.entry! }];\n}\n\nexport const EKANOS_CONFIG_FILENAME = 'ekanos.json';\n\n/** One integration from `ekanos.json`, with its entry resolved on disk. */\nexport interface LoadedIntegration {\n  slug: string;\n  entry: string;\n  /** Absolute path to the resolved entry module. */\n  entryPath: string;\n}\n\nexport interface LoadedProject {\n  project: EkanosProject;\n  /** Absolute path to the directory containing ekanos.json (the project root). */\n  projectDir: string;\n  /** Absolute path to ekanos.json itself. */\n  configPath: string;\n  /** Every integration the project declares, in declaration order. */\n  integrations: LoadedIntegration[];\n  /**\n   * The first integration. It names the generated harness shell and is what a\n   * single-integration project means by \"the\" integration; nothing else\n   * privileges it.\n   */\n  primary: LoadedIntegration;\n}\n\n/**\n * Read and validate ekanos.json from a directory. Missing file → not-found\n * (exit 6); malformed JSON or a schema violation → precondition failed\n * (exit 9), because a project the CLI cannot even read is a precondition for\n * every verb, not a definition-level validation finding.\n */\nexport function loadProject(dir: string): LoadedProject {\n  const projectDir = path.resolve(dir);\n  const configPath = path.join(projectDir, EKANOS_CONFIG_FILENAME);\n\n  if (!fs.existsSync(configPath)) {\n    throw notFoundError(\n      `No ${EKANOS_CONFIG_FILENAME} found in ${projectDir}.`,\n      `Run \"ekanos init\" here first, or change into the project directory ` +\n        `that contains ${EKANOS_CONFIG_FILENAME}.`,\n    );\n  }\n\n  let raw: unknown;\n  try {\n    raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));\n  } catch (error) {\n    throw preconditionError(\n      `${EKANOS_CONFIG_FILENAME} is not valid JSON: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n      `Fix the JSON syntax in ${configPath}.`,\n    );\n  }\n\n  const result = EkanosProjectSchema.safeParse(raw);\n  if (!result.success) {\n    const first = result.error.issues[0];\n    const where =\n      first && first.path.length > 0 ? first.path.join('.') : '(root)';\n    throw preconditionError(\n      `${EKANOS_CONFIG_FILENAME} is invalid at \"${where}\": ${\n        first?.message ?? 'schema violation'\n      }`,\n      `Correct ${configPath} so it matches the ekanos.json schema ` +\n        `({ slug, entry } or { integrations: [...] }, plus optional ` +\n        `harness and sourceGlobs).`,\n    );\n  }\n\n  const project = result.data;\n\n  const integrations = projectIntegrations(project).map((declared) => {\n    const entryPath = path.resolve(projectDir, declared.entry);\n    if (!fs.existsSync(entryPath)) {\n      throw notFoundError(\n        `entry \"${declared.entry}\" for \"${declared.slug}\" resolves to ` +\n          `${entryPath}, which does not exist.`,\n        `Point it at your integration module (the file that exports the ` +\n          `defineIntegration(...) result) in ${configPath}.`,\n      );\n    }\n    return { slug: declared.slug, entry: declared.entry, entryPath };\n  });\n\n  assertEsmProject(projectDir);\n\n  return {\n    project,\n    projectDir,\n    configPath,\n    integrations,\n    primary: integrations[0]!,\n  };\n}\n\n/**\n * Fail unless the project is an ES module package.\n *\n * `init` sets `\"type\": \"module\"` and says so, but a warning can be scrolled\n * past, and a partner who misses it gets a confusing module-resolution error\n * from deep inside Node or Next rather than a sentence naming the problem.\n * This is the backstop: one precondition, in the loader every verb after\n * `init` goes through, so the failure is loud and says what to do.\n *\n * `init` deliberately does NOT come through here — it is the thing that fixes\n * this state.\n *\n * A project with no package.json at all is left alone: `dev` reports missing\n * dependencies with its own better message, and `validate`/`test` have their\n * own preconditions. We only assert on a manifest that exists and disagrees.\n */\nexport function assertEsmProject(projectDir: string): void {\n  const manifestPath = path.join(projectDir, 'package.json');\n  if (!fs.existsSync(manifestPath)) return;\n\n  let manifest: unknown;\n  try {\n    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));\n  } catch {\n    // Malformed JSON is npm's problem to report, not ours to guess at; the\n    // partner will hit it on their next install with a better message.\n    return;\n  }\n\n  const declared =\n    typeof manifest === 'object' && manifest !== null\n      ? (manifest as { type?: unknown }).type\n      : undefined;\n\n  if (declared === 'module') return;\n\n  throw preconditionError(\n    declared === undefined\n      ? `${manifestPath} does not declare \"type\": \"module\", so Node treats ` +\n          'your integration as CommonJS and cannot load it.'\n      : `${manifestPath} declares \"type\": ${JSON.stringify(declared)}, but the ` +\n          'integration sources are ES modules and Node cannot load them.',\n    `Set \"type\": \"module\" in ${manifestPath}. If this project has CommonJS ` +\n      'sources of its own, put your integration in its own package instead — ' +\n      'the two module systems cannot share one package.json. Re-running ' +\n      '\"ekanos init\" also fixes this.',\n  );\n}\n\n/** Serialize an ekanos.json body with a trailing newline. */\nexport function serializeProject(project: EkanosProject): string {\n  return `${JSON.stringify(project, null, 2)}\\n`;\n}\n"]}

package/dist/safe-fs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Filesystem primitives for writing into a directory we do not fully trust.
+ *
+ * `ekanos dev` writes a generated tree into a partner's project, and every
+ * path it touches is one an attacker (or a careless `ln -s`) may have created
+ * first. Plain `existsSync` + `writeFileSync` follows symlinks, so a
+ * `.ekanos/harness` pointing at `~/.ssh`, a generated leaf pointing at a
+ * tracked source file, or a DANGLING link (which `existsSync` reports as
+ * absent, and which `writeFileSync` then materializes) all let a scaffold
+ * write outside the project.
+ *
+ * Two invariants close that, and both are enforced here rather than at the
+ * call sites, because a single unguarded write anywhere reopens the hole:
+ *
+ *  1. **Containment** — every path resolves inside the project root.
+ *  2. **No symlinks** — no component of a path we write through may be a
+ *     symlink, and the write itself uses `O_NOFOLLOW` so the kernel enforces
+ *     it at open time rather than trusting our earlier `lstat`. That closes
+ *     the check→write TOCTOU window: a link swapped in after the check makes
+ *     `open` fail with ELOOP instead of following.
+ */
+/** True when `target` is inside `root` (or is `root` itself). */
+export declare function isContained(root: string, target: string): boolean;
+/**
+ * Walk every path component from `root` down to `target` and refuse if any
+ * existing one is a symlink. `lstat` is deliberate — `stat` would resolve the
+ * link and report the target's type, which is exactly what we must not do.
+ */
+export declare function assertNoSymlinkedComponent(root: string, target: string): void;
+/**
+ * `mkdir -p`, one guarded component at a time. `fs.mkdirSync(recursive)` is
+ * happy to walk through a symlinked ancestor; this is not.
+ */
+export declare function mkdirSafe(root: string, dir: string): void;
+/**
+ * What `destPath` currently is, without following anything. `'symlink'` is
+ * reported for a dangling link too — the case `existsSync` calls absent and
+ * `writeFileSync` would silently materialize outside the project.
+ */
+export type PathKind = 'missing' | 'file' | 'directory' | 'symlink' | 'other';
+export declare function classifyPath(destPath: string): PathKind;
+/**
+ * Read a file, refusing to follow a symlink at the final component. Returns
+ * null when it does not exist. `O_NOFOLLOW` makes the kernel enforce this, so
+ * there is no window between deciding and reading.
+ */
+export declare function readFileNoFollow(root: string, filePath: string): string | null;
+/**
+ * Write a file, creating parent directories, refusing every symlink on the
+ * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe
+ * against a link swapped in after our checks.
+ */
+export declare function writeFileNoFollow(root: string, filePath: string, contents: string): void;
+/** Append to an existing file under the same no-follow guarantee. */
+export declare function appendFileNoFollow(root: string, filePath: string, contents: string): void;

package/dist/safe-fs.js

@@ -0,0 +1,209 @@
+var _a;
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { invalidStateError } from './errors.js';
+/**
+ * Filesystem primitives for writing into a directory we do not fully trust.
+ *
+ * `ekanos dev` writes a generated tree into a partner's project, and every
+ * path it touches is one an attacker (or a careless `ln -s`) may have created
+ * first. Plain `existsSync` + `writeFileSync` follows symlinks, so a
+ * `.ekanos/harness` pointing at `~/.ssh`, a generated leaf pointing at a
+ * tracked source file, or a DANGLING link (which `existsSync` reports as
+ * absent, and which `writeFileSync` then materializes) all let a scaffold
+ * write outside the project.
+ *
+ * Two invariants close that, and both are enforced here rather than at the
+ * call sites, because a single unguarded write anywhere reopens the hole:
+ *
+ *  1. **Containment** — every path resolves inside the project root.
+ *  2. **No symlinks** — no component of a path we write through may be a
+ *     symlink, and the write itself uses `O_NOFOLLOW` so the kernel enforces
+ *     it at open time rather than trusting our earlier `lstat`. That closes
+ *     the check→write TOCTOU window: a link swapped in after the check makes
+ *     `open` fail with ELOOP instead of following.
+ */
+/** True when `target` is inside `root` (or is `root` itself). */
+export function isContained(root, target) {
+    const relative = path.relative(root, target);
+    if (relative === '')
+        return true;
+    return !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+function containmentError(root, target) {
+    throw invalidStateError(`Refusing to write ${target}: it resolves outside the project root ${root}.`, 'Remove the symlink or path component that redirects it, then re-run ' +
+        '"ekanos dev".');
+}
+function symlinkError(link) {
+    throw invalidStateError(`Refusing to write through the symlink ${link}.`, `"ekanos dev" only writes real files inside your project. Delete ${link} ` +
+        '(or the tree containing it) and re-run.');
+}
+/**
+ * Walk every path component from `root` down to `target` and refuse if any
+ * existing one is a symlink. `lstat` is deliberate — `stat` would resolve the
+ * link and report the target's type, which is exactly what we must not do.
+ */
+export function assertNoSymlinkedComponent(root, target) {
+    if (!isContained(root, target))
+        containmentError(root, target);
+    const relative = path.relative(root, target);
+    if (relative === '')
+        return;
+    let current = root;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        let stats;
+        try {
+            stats = fs.lstatSync(current);
+        }
+        catch (_a) {
+            // Does not exist yet — nothing to follow, and everything below it is
+            // ours to create.
+            return;
+        }
+        if (stats.isSymbolicLink())
+            symlinkError(current);
+    }
+}
+/**
+ * `mkdir -p`, one guarded component at a time. `fs.mkdirSync(recursive)` is
+ * happy to walk through a symlinked ancestor; this is not.
+ */
+export function mkdirSafe(root, dir) {
+    if (!isContained(root, dir))
+        containmentError(root, dir);
+    const relative = path.relative(root, dir);
+    if (relative === '')
+        return;
+    let current = root;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        let stats = null;
+        try {
+            stats = fs.lstatSync(current);
+        }
+        catch (_a) {
+            stats = null;
+        }
+        if (stats === null) {
+            try {
+                fs.mkdirSync(current);
+            }
+            catch (error) {
+                const code = error.code;
+                // Lost a race to another process; re-check what landed there.
+                if (code !== 'EEXIST')
+                    throw error;
+                stats = fs.lstatSync(current);
+            }
+            if (stats === null)
+                continue;
+        }
+        if (stats.isSymbolicLink())
+            symlinkError(current);
+        if (!stats.isDirectory()) {
+            throw invalidStateError(`${current} exists and is not a directory, so the harness shell ` +
+                'cannot be written there.', `Move or delete ${current}, then re-run "ekanos dev".`);
+        }
+    }
+}
+export function classifyPath(destPath) {
+    let stats;
+    try {
+        stats = fs.lstatSync(destPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'missing';
+        throw error;
+    }
+    if (stats.isSymbolicLink())
+        return 'symlink';
+    if (stats.isDirectory())
+        return 'directory';
+    if (stats.isFile())
+        return 'file';
+    return 'other';
+}
+/**
+ * Read a file, refusing to follow a symlink at the final component. Returns
+ * null when it does not exist. `O_NOFOLLOW` makes the kernel enforce this, so
+ * there is no window between deciding and reading.
+ */
+export function readFileNoFollow(root, filePath) {
+    assertNoSymlinkedComponent(root, filePath);
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return null;
+        if (code === 'ELOOP')
+            symlinkError(filePath);
+        throw error;
+    }
+    try {
+        return fs.readFileSync(fd, 'utf8');
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Write a file, creating parent directories, refusing every symlink on the
+ * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe
+ * against a link swapped in after our checks.
+ */
+export function writeFileNoFollow(root, filePath, contents) {
+    assertNoSymlinkedComponent(root, filePath);
+    mkdirSafe(root, path.dirname(filePath));
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_WRONLY |
+            fs.constants.O_CREAT |
+            fs.constants.O_TRUNC |
+            O_NOFOLLOW, 0o644);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ELOOP')
+            symlinkError(filePath);
+        throw error;
+    }
+    try {
+        fs.writeFileSync(fd, contents);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Append to an existing file under the same no-follow guarantee. */
+export function appendFileNoFollow(root, filePath, contents) {
+    assertNoSymlinkedComponent(root, filePath);
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_APPEND | O_NOFOLLOW);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ELOOP')
+            symlinkError(filePath);
+        throw error;
+    }
+    try {
+        fs.writeFileSync(fd, contents);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * `O_NOFOLLOW` is POSIX and present on Linux and macOS. Node exposes it as 0
+ * where the platform has no equivalent (Windows), in which case the explicit
+ * `lstat` walk above is the whole guarantee rather than a belt to the kernel's
+ * braces.
+ */
+const O_NOFOLLOW = (_a = fs.constants.O_NOFOLLOW) !== null && _a !== void 0 ? _a : 0;
+//# sourceMappingURL=safe-fs.js.map

package/dist/safe-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fs.js","sourceRoot":"","sources":["../src/safe-fs.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { invalidStateError } from './errors';\n\n/**\n * Filesystem primitives for writing into a directory we do not fully trust.\n *\n * `ekanos dev` writes a generated tree into a partner's project, and every\n * path it touches is one an attacker (or a careless `ln -s`) may have created\n * first. Plain `existsSync` + `writeFileSync` follows symlinks, so a\n * `.ekanos/harness` pointing at `~/.ssh`, a generated leaf pointing at a\n * tracked source file, or a DANGLING link (which `existsSync` reports as\n * absent, and which `writeFileSync` then materializes) all let a scaffold\n * write outside the project.\n *\n * Two invariants close that, and both are enforced here rather than at the\n * call sites, because a single unguarded write anywhere reopens the hole:\n *\n *  1. **Containment** — every path resolves inside the project root.\n *  2. **No symlinks** — no component of a path we write through may be a\n *     symlink, and the write itself uses `O_NOFOLLOW` so the kernel enforces\n *     it at open time rather than trusting our earlier `lstat`. That closes\n *     the check→write TOCTOU window: a link swapped in after the check makes\n *     `open` fail with ELOOP instead of following.\n */\n\n/** True when `target` is inside `root` (or is `root` itself). */\nexport function isContained(root: string, target: string): boolean {\n  const relative = path.relative(root, target);\n  if (relative === '') return true;\n  return !relative.startsWith('..') && !path.isAbsolute(relative);\n}\n\nfunction containmentError(root: string, target: string): never {\n  throw invalidStateError(\n    `Refusing to write ${target}: it resolves outside the project root ${root}.`,\n    'Remove the symlink or path component that redirects it, then re-run ' +\n      '\"ekanos dev\".',\n  );\n}\n\nfunction symlinkError(link: string): never {\n  throw invalidStateError(\n    `Refusing to write through the symlink ${link}.`,\n    `\"ekanos dev\" only writes real files inside your project. Delete ${link} ` +\n      '(or the tree containing it) and re-run.',\n  );\n}\n\n/**\n * Walk every path component from `root` down to `target` and refuse if any\n * existing one is a symlink. `lstat` is deliberate — `stat` would resolve the\n * link and report the target's type, which is exactly what we must not do.\n */\nexport function assertNoSymlinkedComponent(root: string, target: string): void {\n  if (!isContained(root, target)) containmentError(root, target);\n\n  const relative = path.relative(root, target);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      // Does not exist yet — nothing to follow, and everything below it is\n      // ours to create.\n      return;\n    }\n    if (stats.isSymbolicLink()) symlinkError(current);\n  }\n}\n\n/**\n * `mkdir -p`, one guarded component at a time. `fs.mkdirSync(recursive)` is\n * happy to walk through a symlinked ancestor; this is not.\n */\nexport function mkdirSafe(root: string, dir: string): void {\n  if (!isContained(root, dir)) containmentError(root, dir);\n\n  const relative = path.relative(root, dir);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats | null = null;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      stats = null;\n    }\n\n    if (stats === null) {\n      try {\n        fs.mkdirSync(current);\n      } catch (error) {\n        const code = (error as NodeJS.ErrnoException).code;\n        // Lost a race to another process; re-check what landed there.\n        if (code !== 'EEXIST') throw error;\n        stats = fs.lstatSync(current);\n      }\n      if (stats === null) continue;\n    }\n\n    if (stats.isSymbolicLink()) symlinkError(current);\n    if (!stats.isDirectory()) {\n      throw invalidStateError(\n        `${current} exists and is not a directory, so the harness shell ` +\n          'cannot be written there.',\n        `Move or delete ${current}, then re-run \"ekanos dev\".`,\n      );\n    }\n  }\n}\n\n/**\n * What `destPath` currently is, without following anything. `'symlink'` is\n * reported for a dangling link too — the case `existsSync` calls absent and\n * `writeFileSync` would silently materialize outside the project.\n */\nexport type PathKind = 'missing' | 'file' | 'directory' | 'symlink' | 'other';\n\nexport function classifyPath(destPath: string): PathKind {\n  let stats: fs.Stats;\n  try {\n    stats = fs.lstatSync(destPath);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';\n    throw error;\n  }\n  if (stats.isSymbolicLink()) return 'symlink';\n  if (stats.isDirectory()) return 'directory';\n  if (stats.isFile()) return 'file';\n  return 'other';\n}\n\n/**\n * Read a file, refusing to follow a symlink at the final component. Returns\n * null when it does not exist. `O_NOFOLLOW` makes the kernel enforce this, so\n * there is no window between deciding and reading.\n */\nexport function readFileNoFollow(\n  root: string,\n  filePath: string,\n): string | null {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return null;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    return fs.readFileSync(fd, 'utf8');\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * Write a file, creating parent directories, refusing every symlink on the\n * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe\n * against a link swapped in after our checks.\n */\nexport function writeFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n  mkdirSafe(root, path.dirname(filePath));\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY |\n        fs.constants.O_CREAT |\n        fs.constants.O_TRUNC |\n        O_NOFOLLOW,\n      0o644,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/** Append to an existing file under the same no-follow guarantee. */\nexport function appendFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY | fs.constants.O_APPEND | O_NOFOLLOW,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * `O_NOFOLLOW` is POSIX and present on Linux and macOS. Node exposes it as 0\n * where the platform has no equivalent (Windows), in which case the explicit\n * `lstat` walk above is the whole guarantee rather than a belt to the kernel's\n * braces.\n */\nconst O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;\n"]}

package/dist/templates.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The bundled `templates/` directory, resolved relative to the compiled module
+ * so it works from `dist/` and from `src/` alike. `package.json#files` ships
+ * `templates` next to `dist`, so the `../..` hop is the same either way.
+ */
+export declare function templatesDir(): string;
+/**
+ * The one substitution mechanism the CLI has: `__TOKEN__` placeholders,
+ * replaced literally. Deliberately not a template engine — a scaffolded file
+ * must be readable as-is in the repo, and every placeholder must be greppable.
+ * An unknown `__TOKEN__` left in a template is a bug, so this throws rather
+ * than shipping a placeholder into a partner's project.
+ */
+export declare function renderTemplate(source: string, vars: Readonly<Record<string, string>>): string;
+/**
+ * The raw, unrendered source of a bundled template. Used for the compatibility
+ * fingerprint, which must not vary with the slug it would be rendered for.
+ */
+export declare function readTemplateSource(relativePath: string): string;
+/** Read a bundled template and render it in one step. */
+export declare function readTemplate(relativePath: string, vars: Readonly<Record<string, string>>): string;
+/** "acme-crm" → "Acme Crm". */
+export declare function toDisplayName(slug: string): string;

package/dist/templates.js

@@ -0,0 +1,49 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The bundled `templates/` directory, resolved relative to the compiled module
+ * so it works from `dist/` and from `src/` alike. `package.json#files` ships
+ * `templates` next to `dist`, so the `../..` hop is the same either way.
+ */
+export function templatesDir() {
+    return fileURLToPath(new URL('../templates', import.meta.url));
+}
+/**
+ * The one substitution mechanism the CLI has: `__TOKEN__` placeholders,
+ * replaced literally. Deliberately not a template engine — a scaffolded file
+ * must be readable as-is in the repo, and every placeholder must be greppable.
+ * An unknown `__TOKEN__` left in a template is a bug, so this throws rather
+ * than shipping a placeholder into a partner's project.
+ */
+export function renderTemplate(source, vars) {
+    let rendered = source;
+    for (const [name, value] of Object.entries(vars)) {
+        rendered = rendered.split(`__${name}__`).join(value);
+    }
+    const leftover = /__[A-Z][A-Z0-9_]*__/.exec(rendered);
+    if (leftover) {
+        throw new Error(`Template placeholder "${leftover[0]}" was not substituted. This is a ` +
+            'bug in @ekanos/cli — the template and its variable set disagree.');
+    }
+    return rendered;
+}
+/**
+ * The raw, unrendered source of a bundled template. Used for the compatibility
+ * fingerprint, which must not vary with the slug it would be rendered for.
+ */
+export function readTemplateSource(relativePath) {
+    return fs.readFileSync(path.join(templatesDir(), relativePath), 'utf8');
+}
+/** Read a bundled template and render it in one step. */
+export function readTemplate(relativePath, vars) {
+    return renderTemplate(readTemplateSource(relativePath), vars);
+}
+/** "acme-crm" → "Acme Crm". */
+export function toDisplayName(slug) {
+    return slug
+        .split('-')
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join(' ');
+}
+//# sourceMappingURL=templates.js.map

package/dist/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,IAAsC;IAEtC,IAAI,QAAQ,GAAG,MAAM,CAAC;IACtB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,yBAAyB,QAAQ,CAAC,CAAC,CAAC,mCAAmC;YACrE,kEAAkE,CACrE,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,OAAO,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,YAAY,CAC1B,YAAoB,EACpB,IAAsC;IAEtC,OAAO,cAAc,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,CAAC;AAChE,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI;SACR,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACpE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/**\n * The bundled `templates/` directory, resolved relative to the compiled module\n * so it works from `dist/` and from `src/` alike. `package.json#files` ships\n * `templates` next to `dist`, so the `../..` hop is the same either way.\n */\nexport function templatesDir(): string {\n  return fileURLToPath(new URL('../templates', import.meta.url));\n}\n\n/**\n * The one substitution mechanism the CLI has: `__TOKEN__` placeholders,\n * replaced literally. Deliberately not a template engine — a scaffolded file\n * must be readable as-is in the repo, and every placeholder must be greppable.\n * An unknown `__TOKEN__` left in a template is a bug, so this throws rather\n * than shipping a placeholder into a partner's project.\n */\nexport function renderTemplate(\n  source: string,\n  vars: Readonly<Record<string, string>>,\n): string {\n  let rendered = source;\n  for (const [name, value] of Object.entries(vars)) {\n    rendered = rendered.split(`__${name}__`).join(value);\n  }\n\n  const leftover = /__[A-Z][A-Z0-9_]*__/.exec(rendered);\n  if (leftover) {\n    throw new Error(\n      `Template placeholder \"${leftover[0]}\" was not substituted. This is a ` +\n        'bug in @ekanos/cli — the template and its variable set disagree.',\n    );\n  }\n\n  return rendered;\n}\n\n/**\n * The raw, unrendered source of a bundled template. Used for the compatibility\n * fingerprint, which must not vary with the slug it would be rendered for.\n */\nexport function readTemplateSource(relativePath: string): string {\n  return fs.readFileSync(path.join(templatesDir(), relativePath), 'utf8');\n}\n\n/** Read a bundled template and render it in one step. */\nexport function readTemplate(\n  relativePath: string,\n  vars: Readonly<Record<string, string>>,\n): string {\n  return renderTemplate(readTemplateSource(relativePath), vars);\n}\n\n/** \"acme-crm\" → \"Acme Crm\". */\nexport function toDisplayName(slug: string): string {\n  return slug\n    .split('-')\n    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))\n    .join(' ');\n}\n"]}