@intentius/chant-lexicon-e2b 0.0.0-stage → 0.124.33

package/dist/op/sandbox.js

@@ -0,0 +1,87 @@
+/**
+ * The seam between the e2b runtime and an E2B-compatible API.
+ *
+ * {@link StewardSandboxes} is all the runtime asks of a sandbox provider: find
+ * the steward's sandbox by its metadata, make one, wake one, run a command in
+ * it, list and kill its processes, keep it awake and pause it. The production
+ * implementation below is a thin wrapper over the `e2b` SDK, so the runtime
+ * works against hosted E2B and anything that serves E2B's API (loam, for one);
+ * a test hands the runtime a fake and drives the whole path with no network.
+ */
+/** The metadata key a steward's sandbox is found by. */
+export const STEWARD_METADATA_KEY = "chant/steward";
+/** The environment variables that mark a process in the sandbox as a chant run. */
+export const RUN_OP_ENV = "CHANT_E2B_OP";
+export const RUN_ID_ENV = "CHANT_E2B_RUN";
+export const RUN_STARTED_ENV = "CHANT_E2B_STARTED";
+/** The production seam, over the `e2b` SDK. The SDK is imported on first use, so loading the plugin costs nothing. */
+export function e2bSandboxes(conn) {
+    const base = { apiKey: conn.apiKey, ...(conn.domain ? { domain: conn.domain } : {}) };
+    const sdk = () => import("e2b");
+    const wrap = (sb) => ({
+        id: sb.sandboxId,
+        async run(script, opts = {}) {
+            const { CommandExitError } = await sdk();
+            // `timeoutMs: 0` lifts the SDK's one-minute default: an op runs as long as it runs.
+            const handle = await sb.commands.run(script, {
+                background: true,
+                timeoutMs: 0,
+                ...(opts.envs ? { envs: opts.envs } : {}),
+                ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+                ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+            });
+            opts.onStart?.(handle.pid);
+            try {
+                const done = await handle.wait();
+                return { exitCode: done.exitCode, stdout: done.stdout, stderr: done.stderr };
+            }
+            catch (err) {
+                if (err instanceof CommandExitError)
+                    return { exitCode: err.exitCode, stdout: err.stdout, stderr: err.stderr };
+                throw err;
+            }
+        },
+        async processes() {
+            return (await sb.commands.list()).map((p) => ({ pid: p.pid, envs: p.envs ?? {} }));
+        },
+        async kill(pid) {
+            await sb.commands.kill(pid);
+        },
+        async keepAwake(ms) {
+            await sb.setTimeout(ms);
+        },
+        async pause() {
+            await sb.pause();
+        },
+    });
+    return {
+        async find(steward) {
+            const { Sandbox } = await sdk();
+            const page = await Sandbox.list({
+                ...base,
+                query: { metadata: { [STEWARD_METADATA_KEY]: steward }, state: ["running", "paused"] },
+                limit: 2,
+            }).nextItems();
+            if (page.length > 1) {
+                throw new Error(`e2b runtime: ${page.length} sandboxes carry ${STEWARD_METADATA_KEY}=${steward}. ` +
+                    `A steward is one machine; kill all but one (${page.map((s) => s.sandboxId).join(", ")}).`);
+            }
+            return page[0] ? { id: page[0].sandboxId, state: page[0].state } : undefined;
+        },
+        async create(steward, opts) {
+            const { Sandbox } = await sdk();
+            const sb = await Sandbox.create(opts.template, {
+                ...base,
+                timeoutMs: opts.awakeMs,
+                metadata: { [STEWARD_METADATA_KEY]: steward },
+                // Run out of time paused, not killed: the disk, and the memory, are the steward.
+                lifecycle: { onTimeout: "pause" },
+            });
+            return wrap(sb);
+        },
+        async connect(id, opts) {
+            const { Sandbox } = await sdk();
+            return wrap(await Sandbox.connect(id, { ...base, timeoutMs: opts.awakeMs }));
+        },
+    };
+}

package/dist/package-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=package-cli.d.ts.map

package/dist/package-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-cli.d.ts","sourceRoot":"","sources":["../src/package-cli.ts"],"names":[],"mappings":""}

package/dist/package-cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env tsx
+/**
+ * `npm run bundle` for the e2b lexicon: writes dist/manifest.json, dist/meta.json,
+ * the rules and the skills.
+ */
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const distDir = join(dirname(fileURLToPath(import.meta.url)), "..", "dist");
+const verbose = process.argv.includes("--verbose");
+const { spec, stats } = await packageLexicon({ verbose });
+writeBundleSpec(spec, distDir);
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills into ${distDir}`);

package/dist/plugin.d.ts

@@ -0,0 +1,12 @@
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+/**
+ * e2b lexicon plugin: `chant run <op> --on e2b`, and the `Template` a
+ * steward's sandbox is made from.
+ *
+ * The op runtime is most of the lexicon. Its one declarable kind is written
+ * by hand, so `generate` only writes the post-synth barrel, there is no
+ * upstream spec to validate against or measure coverage of, and `package`
+ * bundles the hand-written catalog.
+ */
+export declare const e2bPlugin: LexiconPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAY9D;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,EAAE,aAyDvB,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,66 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import { e2bSerializer } from "./serializer.js";
+import { e2bConfigSchema } from "./config.js";
+import { createE2bOpRuntime } from "./op/runtime.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+import { e2bAuditCatalog } from "./lint/audit-catalog.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+/**
+ * e2b lexicon plugin: `chant run <op> --on e2b`, and the `Template` a
+ * steward's sandbox is made from.
+ *
+ * The op runtime is most of the lexicon. Its one declarable kind is written
+ * by hand, so `generate` only writes the post-synth barrel, there is no
+ * upstream spec to validate against or measure coverage of, and `package`
+ * bundles the hand-written catalog.
+ */
+export const e2bPlugin = {
+    name: "e2b",
+    serializer: e2bSerializer,
+    configSchema: e2bConfigSchema,
+    auditCatalog: () => e2bAuditCatalog,
+    // Construction is pure: the key, the steward and the repository are
+    // resolved on the first call, so loading the plugin costs nothing.
+    opRuntime: createE2bOpRuntime(),
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-e2b-ops.md",
+            name: "chant-e2b-ops",
+            description: "Run chant ops on a steward sandbox with `--on e2b`, on hosted E2B or any API that speaks E2B's",
+            triggers: [{ type: "context", value: "e2b" }],
+        },
+    ]),
+    async generate() {
+        const { generate } = await import("./codegen/generate.js");
+        generate();
+    },
+    // Nothing upstream to check the hand-written kind against.
+    async validate() { },
+    async coverage() { },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec } = await packageLexicon(options);
+        writeBundleSpec(spec, join(dirname(dirname(fileURLToPath(import.meta.url))), "dist"));
+    },
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        return postSynthChecks;
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+};

package/dist/resources.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The e2b lexicon's one declarable kind: a sandbox template.
+ *
+ * A steward's sandbox is made from a template (`template` in the profile,
+ * default `base`). The runtime needs git and Node in it, and a project usually
+ * wants its own tools there too, installed once rather than on every run. A
+ * `Template` declares that image; `chant build` writes it out as a Dockerfile
+ * and the `e2b template create` command line that builds it.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+export interface TemplateProps {
+    /** The template's name on E2B: lowercase letters, digits, dashes and underscores. A profile's `template` names it. */
+    name: string;
+    /** The image the template starts from, such as `node:22-bookworm`. Pin a tag. */
+    fromImage: string;
+    /** Shell commands run in order while the template builds, one `RUN` line each. */
+    run?: string[];
+    /** Environment variables set in every sandbox made from the template. */
+    env?: Record<string, string>;
+    /** The working directory for the `run` steps and the start command. */
+    workdir?: string;
+    /** The start command (`--cmd`): E2B runs it when the template is snapshotted, so a sandbox starts with it running. */
+    startCmd?: string;
+    /** The ready command (`--ready-cmd`): E2B polls it until it exits 0 before it snapshots the template. */
+    readyCmd?: string;
+    /** vCPUs per sandbox. A positive integer; E2B's default is 2. */
+    cpuCount?: number;
+    /** Memory per sandbox in MiB. A positive even integer; E2B's default is 1024. */
+    memoryMB?: number;
+}
+export interface Template extends Declarable {
+    readonly props: TemplateProps;
+}
+/** A sandbox template, serialized to `e2b.<name>.Dockerfile` and an `e2b template create` command. */
+export declare const Template: new (props: TemplateProps) => Template;
+/** The props of a declared `Template`, or `undefined` for anything else. */
+export declare function templateProps(entity: unknown): TemplateProps | undefined;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D,MAAM,WAAW,aAAa;IAC5B,sHAAsH;IACtH,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sHAAsH;IACtH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC1C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,sGAAsG;AACtG,eAAO,MAAM,QAAQ,EAA0E,KAC7F,KAAK,EAAE,aAAa,KACjB,QAAQ,CAAC;AAEd,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAIxE"}

package/dist/resources.js

@@ -0,0 +1,21 @@
+/**
+ * The e2b lexicon's one declarable kind: a sandbox template.
+ *
+ * A steward's sandbox is made from a template (`template` in the profile,
+ * default `base`). The runtime needs git and Node in it, and a project usually
+ * wants its own tools there too, installed once rather than on every run. A
+ * `Template` declares that image; `chant build` writes it out as a Dockerfile
+ * and the `e2b template create` command line that builds it.
+ */
+import { createResource } from "@intentius/chant/runtime";
+import { TEMPLATE_TYPE } from "./catalog.js";
+/** A sandbox template, serialized to `e2b.<name>.Dockerfile` and an `e2b template create` command. */
+export const Template = /* @__PURE__ */ createResource(TEMPLATE_TYPE, "e2b", {});
+/** The props of a declared `Template`, or `undefined` for anything else. */
+export function templateProps(entity) {
+    if (!entity || typeof entity !== "object")
+        return undefined;
+    if (entity.entityType !== TEMPLATE_TYPE)
+        return undefined;
+    return (entity.props ?? {});
+}

package/dist/rules/e2b011-template-name.ts

@@ -0,0 +1,51 @@
+/**
+ * E2B011: a template's name is one E2B accepts, and only one template has it.
+ *
+ * E2B names templates with lowercase letters, digits, dashes and underscores;
+ * `e2b template create` refuses anything else. The name is also the profile's
+ * `template` and the stem of the Dockerfile the serializer writes, so two
+ * templates with one name would overwrite each other's file.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { templateProps } from "../../resources";
+
+export const TEMPLATE_NAME = /^[a-z0-9_-]+$/;
+
+export const e2b011: PostSynthCheck = {
+  id: "E2B011",
+  description: "A Template's name must be lowercase letters, digits, dashes and underscores, and unique",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const seen = new Map<string, string>();
+    for (const [entityName, entity] of ctx.entities) {
+      const props = templateProps(entity);
+      if (!props) continue;
+      const name = props.name;
+      if (typeof name !== "string" || !TEMPLATE_NAME.test(name)) {
+        diagnostics.push({
+          checkId: "E2B011",
+          severity: "error",
+          message: `Template "${entityName}" has name ${JSON.stringify(name)}. E2B template names are lowercase letters, digits, dashes and underscores.`,
+          entity: entityName,
+          lexicon: "e2b",
+        });
+        continue;
+      }
+      const first = seen.get(name);
+      if (first !== undefined) {
+        diagnostics.push({
+          checkId: "E2B011",
+          severity: "error",
+          message: `Templates "${first}" and "${entityName}" are both named "${name}"; their e2b.${name}.Dockerfile files would overwrite each other.`,
+          entity: entityName,
+          lexicon: "e2b",
+        });
+      } else {
+        seen.set(name, entityName);
+      }
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/e2b012-steward-tools.ts

@@ -0,0 +1,58 @@
+/**
+ * E2B012: a template has the git and Node a steward needs.
+ *
+ * The runtime clones the repository with git and runs the project's own chant
+ * with Node, and it stops a run at once on a sandbox that lacks either. This
+ * check looks for both in the declaration: Node from a `node` image or a
+ * step that installs it, git from a full (not `-slim` or `-alpine`) `node` image, which
+ * ships it, or a step that installs it. It cannot see inside other images, so
+ * it warns rather than fails: a template from an image that already has both
+ * can say so with a `run` step such as `git --version && node --version`.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { templateProps, type TemplateProps } from "../../resources";
+
+function imageRepoAndTag(image: string): { repo: string; tag: string } {
+  const ref = image.toLowerCase().split("@")[0];
+  const segment = ref.slice(ref.lastIndexOf("/") + 1);
+  const [repo, tag = ""] = segment.split(":");
+  return { repo, tag };
+}
+
+/** Which of git and Node the declaration visibly provides. */
+export function stewardTools(props: TemplateProps): { git: boolean; node: boolean } {
+  const { repo, tag } = imageRepoAndTag(props.fromImage ?? "");
+  const steps = (props.run ?? []).join("\n");
+  const nodeImage = repo === "node";
+  return {
+    node: nodeImage || /\b(nodejs|node|nvm|fnm|volta)\b/.test(steps),
+    git: (nodeImage && !/slim|alpine/.test(tag)) || /\bgit\b/.test(steps),
+  };
+}
+
+export const e2b012: PostSynthCheck = {
+  id: "E2B012",
+  description: "A Template a steward runs on needs git and Node",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [name, entity] of ctx.entities) {
+      const props = templateProps(entity);
+      if (!props) continue;
+      const tools = stewardTools(props);
+      const missing = [tools.git ? undefined : "git", tools.node ? undefined : "Node"].filter((t): t is string => t !== undefined);
+      if (missing.length === 0) continue;
+      diagnostics.push({
+        checkId: "E2B012",
+        severity: "warning",
+        message:
+          `Template "${name}" shows no sign of ${missing.join(" or ")}. A steward needs both; ` +
+          `start from a node image or add a run step that installs ${missing.length === 2 ? "them" : "it"}.`,
+        entity: name,
+        lexicon: "e2b",
+      });
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/pinned-image.ts

@@ -0,0 +1,41 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { ts } from "@intentius/chant/lint/typescript";
+import { at, property, templateLiterals } from "./template-literal";
+
+/** An image reference with no tag or digest, or the `latest` tag. */
+export function isFloatingImage(image: string): boolean {
+  if (image.includes("@")) return false;
+  const lastSegment = image.slice(image.lastIndexOf("/") + 1);
+  const colon = lastSegment.indexOf(":");
+  return colon === -1 || lastSegment.slice(colon + 1) === "latest";
+}
+
+/**
+ * E2B002: A template's base image is pinned.
+ *
+ * A steward keeps one sandbox for months, but a template is rebuilt whenever
+ * someone runs `e2b template create`. With `fromImage` untagged or on `latest`,
+ * two builds of the same declaration can carry different Node or git
+ * versions, and a steward made from the second behaves differently with no
+ * change in the repository.
+ */
+export const pinnedImageRule: LintRule = {
+  id: "E2B002",
+  severity: "warning",
+  category: "correctness",
+  description: "A Template's fromImage should name a tag other than latest, or a digest",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+    for (const obj of templateLiterals(sourceFile)) {
+      const image = property(obj, "fromImage", sourceFile);
+      if (image && ts.isStringLiteralLike(image) && image.text.length > 0 && isFloatingImage(image.text)) {
+        diagnostics.push(
+          at(sourceFile, image, "E2B002", "warning", `fromImage "${image.text}" is not pinned; name a version tag such as node:22-bookworm, or a digest.`),
+        );
+      }
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/template-literal.ts

@@ -0,0 +1,42 @@
+/** Helpers the e2b lint rules share: finding `new Template({...})` literals and reporting on them. */
+
+import type { LintDiagnostic } from "@intentius/chant/lint/rule";
+import { ts } from "@intentius/chant/lint/typescript";
+
+/** The object literal passed to each `new Template({...})` in the file. */
+export function templateLiterals(sourceFile: ts.SourceFile): ts.ObjectLiteralExpression[] {
+  const found: ts.ObjectLiteralExpression[] = [];
+  function visit(node: ts.Node): void {
+    if (ts.isNewExpression(node)) {
+      const callee = node.expression;
+      const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : "";
+      const arg = node.arguments?.[0];
+      if (name === "Template" && arg && ts.isObjectLiteralExpression(arg)) found.push(arg);
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return found;
+}
+
+/** The initializer of `key` in an object literal, when it is written there. */
+export function property(obj: ts.ObjectLiteralExpression, key: string, sourceFile: ts.SourceFile): ts.Expression | undefined {
+  for (const p of obj.properties) {
+    if (ts.isPropertyAssignment(p) && p.name.getText(sourceFile) === key) return p.initializer;
+  }
+  return undefined;
+}
+
+/** A numeric literal's value, a negated one included; `undefined` for anything computed. */
+export function numberLiteral(expr: ts.Expression): number | undefined {
+  if (ts.isNumericLiteral(expr)) return Number(expr.text);
+  if (ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(expr.operand)) {
+    return -Number(expr.operand.text);
+  }
+  return undefined;
+}
+
+export function at(sourceFile: ts.SourceFile, node: ts.Node, ruleId: string, severity: LintDiagnostic["severity"], message: string): LintDiagnostic {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { file: sourceFile.fileName, line: line + 1, column: character + 1, ruleId, severity, message };
+}

package/dist/rules/template-size.ts

@@ -0,0 +1,36 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { at, numberLiteral, property, templateLiterals } from "./template-literal";
+
+/**
+ * E2B001: A template's CPU and memory are sizes E2B accepts.
+ *
+ * `cpuCount` is a whole number of vCPUs, at least one. `memoryMB` is a whole
+ * number of MiB, at least one and even: `e2b template create` refuses an odd
+ * one. Both are only checked when written as literals.
+ */
+export const templateSizeRule: LintRule = {
+  id: "E2B001",
+  severity: "error",
+  category: "correctness",
+  description: "A Template's cpuCount must be a positive integer and its memoryMB a positive even integer",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+    for (const obj of templateLiterals(sourceFile)) {
+      const cpu = property(obj, "cpuCount", sourceFile);
+      const cpuValue = cpu ? numberLiteral(cpu) : undefined;
+      if (cpu && cpuValue !== undefined && !(Number.isInteger(cpuValue) && cpuValue >= 1)) {
+        diagnostics.push(at(sourceFile, cpu, "E2B001", "error", `cpuCount ${cpuValue} is not a whole number of vCPUs; use 1 or more.`));
+      }
+      const mem = property(obj, "memoryMB", sourceFile);
+      const memValue = mem ? numberLiteral(mem) : undefined;
+      if (mem && memValue !== undefined && !(Number.isInteger(memValue) && memValue >= 2 && memValue % 2 === 0)) {
+        diagnostics.push(
+          at(sourceFile, mem, "E2B001", "error", `memoryMB ${memValue} is not a positive even number of MiB, which E2B requires.`),
+        );
+      }
+    }
+    return diagnostics;
+  },
+};

package/dist/serializer.d.ts

@@ -0,0 +1,18 @@
+import type { Serializer } from "@intentius/chant/serializer";
+import { type TemplateProps } from "./resources.js";
+/**
+ * The e2b serializer: each declared `Template` becomes `e2b.<name>.Dockerfile`
+ * (`FROM`, then `ENV`, `WORKDIR` and one `RUN` per step), named after the
+ * template so several can sit in one directory.
+ *
+ * The primary output is a JSON index of the templates, keyed by the name each
+ * was exported as. Each entry carries the Dockerfile's name and `build`, the
+ * `e2b template create` command line that builds the template from it, run in
+ * the output directory. A build with no templates (a project that only runs
+ * Ops here) gets an empty index.
+ */
+export declare const e2bSerializer: Serializer;
+export declare function renderDockerfile(props: TemplateProps): string;
+/** The `e2b template create` command line that builds the template, run where the Dockerfile is. */
+export declare function createCommand(name: string, dockerfile: string, props: TemplateProps): string;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,EAAE,UA+B3B,CAAC;AAUF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAM7D;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAO5F"}

package/dist/serializer.js

@@ -0,0 +1,70 @@
+import { templateProps } from "./resources.js";
+/**
+ * The e2b serializer: each declared `Template` becomes `e2b.<name>.Dockerfile`
+ * (`FROM`, then `ENV`, `WORKDIR` and one `RUN` per step), named after the
+ * template so several can sit in one directory.
+ *
+ * The primary output is a JSON index of the templates, keyed by the name each
+ * was exported as. Each entry carries the Dockerfile's name and `build`, the
+ * `e2b template create` command line that builds the template from it, run in
+ * the output directory. A build with no templates (a project that only runs
+ * Ops here) gets an empty index.
+ */
+export const e2bSerializer = {
+    name: "e2b",
+    rulePrefix: "E2B",
+    serialize(entities) {
+        const index = {};
+        const files = {};
+        const templates = [...entities]
+            .map(([exportName, entity]) => [exportName, templateProps(entity)])
+            .filter((e) => e[1] !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b));
+        for (const [exportName, props] of templates) {
+            const name = props.name || exportName;
+            const dockerfile = `e2b.${name}.Dockerfile`;
+            files[dockerfile] = renderDockerfile(props);
+            index[exportName] = {
+                name,
+                dockerfile,
+                build: createCommand(name, dockerfile, props),
+                ...(props.cpuCount !== undefined ? { cpuCount: props.cpuCount } : {}),
+                ...(props.memoryMB !== undefined ? { memoryMB: props.memoryMB } : {}),
+            };
+        }
+        return {
+            primary: JSON.stringify({ templates: index }, null, 2) + "\n",
+            files,
+            verbatimFiles: Object.keys(files),
+        };
+    },
+};
+/** A Dockerfile string literal: Docker reads double-quoted values with JSON's escapes. */
+const quote = (value) => JSON.stringify(value);
+/** A word as one shell argument. */
+function shellWord(value) {
+    return /^[A-Za-z0-9._:@+=/,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function renderDockerfile(props) {
+    const lines = [`FROM ${props.fromImage}`];
+    for (const [key, value] of Object.entries(props.env ?? {}))
+        lines.push(`ENV ${key}=${quote(value)}`);
+    if (props.workdir)
+        lines.push(`WORKDIR ${props.workdir}`);
+    for (const step of props.run ?? [])
+        lines.push(`RUN ${step}`);
+    return lines.join("\n") + "\n";
+}
+/** The `e2b template create` command line that builds the template, run where the Dockerfile is. */
+export function createCommand(name, dockerfile, props) {
+    const args = ["e2b", "template", "create", name, "--dockerfile", dockerfile];
+    if (props.startCmd)
+        args.push("--cmd", props.startCmd);
+    if (props.readyCmd)
+        args.push("--ready-cmd", props.readyCmd);
+    if (props.cpuCount !== undefined)
+        args.push("--cpu-count", String(props.cpuCount));
+    if (props.memoryMB !== undefined)
+        args.push("--memory-mb", String(props.memoryMB));
+    return args.map(shellWord).join(" ");
+}

package/dist/skills/chant-e2b-ops.md

@@ -0,0 +1,69 @@
+---
+skill: chant-e2b-ops
+description: Run chant ops on a steward sandbox with `--on e2b`, on hosted E2B or any API that speaks E2B's
+user-invocable: true
+---
+
+# Running chant ops on an e2b steward
+
+`chant run <op> --on e2b` runs the op on a steward: one sandbox that outlives
+every run. It keeps a clone of the project and its installed tools on its disk,
+runs one op at a time, and sleeps paused between runs. Any API that speaks
+E2B's hosts one: hosted E2B, or a platform that serves the same API.
+
+## Set it up
+
+```ts
+// chant.config.ts
+import type { ChantConfig } from "@intentius/chant/config";
+import "@intentius/chant-lexicon-e2b";
+
+export default {
+  lexicons: ["e2b"],
+  e2b: {
+    profiles: {
+      prod: {
+        apiKey: { env: "E2B_API_KEY" },
+        domain: "e2b.example.com",        // omit for hosted E2B
+        steward: "prod-steward",           // default: the repository's name
+        gitToken: { env: "GITHUB_TOKEN" }, // fetch a private repo, push the ledger
+      },
+    },
+    defaultProfile: "prod",
+  },
+} satisfies ChantConfig;
+```
+
+The project must depend on `@intentius/chant`, because the steward runs the
+chant the project installs. The template (default `base`) needs git and Node.
+
+## Run, read, cancel
+
+```bash
+chant run prod-apply --on e2b              # streams the steps, then pauses the steward
+chant run status prod-apply --on e2b       # a run in progress, or the last one recorded
+chant run log prod-apply --on e2b
+chant run cancel prod-apply --on e2b --force
+```
+
+The steward runs the commit this checkout is at, fetched from the repository,
+so **push first**. Uncommitted changes are not sent; the run warns about them.
+
+One run at a time: a run while the steward is busy is refused, naming the run
+in progress. A client that dies mid-run (Ctrl-C excepted) leaves the run going;
+`status` reports it, and the steward pauses itself when it is done.
+
+## Gates
+
+A gate works as it does locally. The run reaches it in the sandbox, pushes the
+pending fact to the repository's `chant/lifecycle` branch and ends `gated`
+(exit 3). `chant approve <op> <gate>` from any checkout of the repository
+records the answer, and the next `--on e2b` run walks through. The steward also
+pushes its run records, so `chant run log` on any checkout sees its runs.
+
+## Running on a schedule
+
+Nothing in E2B fires on a clock. Run `chant run <op> --on e2b` from whatever
+already does: a CI `schedule:` trigger (the github lexicon renders an op's
+`schedule` as one), a CronJob, or `chant operator` on a machine that stays up.
+The job is short, because the steward does the work.

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export * from "../index.js";