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

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @intentius/chant-lexicon-e2b
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run chant Ops on a steward: one [E2B](https://e2b.dev) sandbox that outlives
+every run. `chant run <op> --on e2b` hands the run to it.
+
+The steward keeps a clone of the project and its installed tools on its disk,
+runs one Op at a time, and sleeps paused between runs, which costs nothing and
+survives anything short of deleting it. Any API that speaks E2B's can host it:
+hosted E2B, or a platform of your own that serves the same API.
+
+It gives an Op what [Ops as teammates](https://intentius.io/chant/concepts/durable-workflows/)
+calls *the machine*: something that runs when nobody's laptop is open, without
+holding one open between runs.
+
+## Install
+
+```bash
+npm install --save-dev @intentius/chant-lexicon-e2b
+```
+
+```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",
+        steward: "prod-steward",
+        gitToken: { env: "GITHUB_TOKEN" },
+      },
+    },
+    defaultProfile: "prod",
+  },
+} satisfies ChantConfig;
+```
+
+| Field | Default | |
+|---|---|---|
+| `apiKey` | `{ env: "E2B_API_KEY" }` | The E2B API key, by environment variable. |
+| `domain` | `E2B_DOMAIN`, else hosted E2B | The domain the SDK talks to. |
+| `template` | `base` | The template the steward is made from. It needs git and Node. |
+| `steward` | the repository's name | The steward's sandbox is found again by its `chant/steward` metadata. |
+| `repo` | `origin`, as https | The repository the steward clones. An ssh `origin` is rewritten to https. |
+| `gitToken` | `CHANT_GIT_TOKEN`, when set | A token to fetch a private repository and push chant's ledger branch. It is handed to each command in the sandbox and never written to its disk. |
+
+With no profile, the runtime reads `E2B_API_KEY`, `E2B_DOMAIN` and
+`CHANT_GIT_TOKEN`. `--profile <name>` picks another profile for one run.
+
+The project must depend on `@intentius/chant`: the steward runs the chant the
+project installs.
+
+## The steward's template
+
+A steward's sandbox is made from the profile's `template`, which is E2B's
+`base` when the profile names none. Declare a `Template` and name it in the
+profile when the project's Ops need tools that `base` lacks:
+
+```ts
+// src/steward.ts
+import { Template } from "@intentius/chant-lexicon-e2b";
+
+const steward = new Template({
+  name: "chant-steward",
+  fromImage: "node:22-bookworm",
+  run: ["apt-get update && apt-get install -y --no-install-recommends jq && rm -rf /var/lib/apt/lists/*"],
+  cpuCount: 2,
+  memoryMB: 2048,
+});
+
+export { steward };
+```
+
+`chant build` writes it as `e2b.chant-steward.Dockerfile`, and the JSON index
+in its main output gives the command that builds it, to run once in the output
+directory:
+`e2b template create chant-steward --dockerfile e2b.chant-steward.Dockerfile --cpu-count 2 --memory-mb 2048`.
+A steward that already exists keeps its sandbox until it is deleted.
+
+Two lint rules check a template's sizes and that its base image is pinned
+(E2B001, E2B002). Two post-synth checks catch a name E2B refuses or two
+templates sharing one (E2B011), and a template with no visible git or Node
+(E2B012). The [docs](https://intentius.io/chant/lexicons/e2b/)
+cover each property and rule.
+
+## What a run does
+
+1. Finds the steward's sandbox, or makes it. A steward already running an Op is
+   busy, and the run is refused rather than queued.
+2. Fetches the repository in the steward's clone, checks out the commit this
+   checkout is at (so push it first; uncommitted changes don't travel, and the
+   run says so), and runs `npm ci` when the lockfile changed. Ignored files,
+   `node_modules` among them, are kept between runs.
+3. Runs `chant run <op> --on local --json --progress-json` there, streaming each
+   settled step back.
+4. Pushes the steward's ledger and pauses the sandbox.
+
+Gates, leases and the run ledger are the local runtime's, unchanged. A gate the
+steward reaches pushes its pending fact to the repository's `chant/lifecycle`
+branch; `chant approve` on any checkout records the answer; the next run walks
+through.
+
+```bash
+chant run prod-apply --on e2b              # exit 3: pending on rollout-gate
+chant approve prod-apply rollout-gate      # from any checkout
+chant run prod-apply --on e2b              # walks through, applies
+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
+```
+
+A client that dies mid-run leaves the run going in the sandbox. `status`
+reports it, and the steward pauses itself when its awake window (30 minutes,
+renewed while a client is watching) runs out. Ctrl-C, or `chant run cancel`
+from any checkout, stops it the way Ctrl-C stops a local run: SIGTERM, then
+SIGKILL after ten seconds.
+
+## The steward's ledger
+
+chant pushes the facts other checkouts need as it writes them (a gate's pending
+fact, an approval, a lease), but keeps run records on the local branch. A
+checkout that lives on, as a steward's does, would then diverge from the
+repository the first time someone approved a gate elsewhere, and chant refuses
+to read a diverged ledger. So before and after each run the steward reconciles
+its `chant/lifecycle` with the repository's: it pushes when it is only ahead,
+and when the two have diverged it merges them (each `.jsonl` file is
+append-only, so the merge adds the lines one side lacks) and pushes the merge.
+Its run records therefore reach the repository, and `chant run log` on any
+checkout sees them.
+
+## Schedules
+
+Nothing in E2B fires on a clock. Run `chant run <op> --on e2b` from whatever
+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.
+
+## Limits
+
+- Workspace members: `status`, `log` and `list` read the root project's run
+  ledger only.
+- `declareSteward`'s forms are `local` and `fountain`; there is no `e2b` form
+  yet, so a steward's schedules don't render to anything here. Drive them from
+  a clock as above.

package/dist/catalog.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The one kind the e2b lexicon declares, described once.
+ *
+ * The LSP's completions and hover, the bundle's `dist/meta.json` and the docs'
+ * resource reference all read this table, so a property added to `Template`
+ * is added here and reaches all three.
+ */
+import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+export declare const TEMPLATE_TYPE = "E2B::Template";
+export interface PropertyDoc {
+    type: string;
+    required?: boolean;
+    description: string;
+}
+/** `Template`'s properties, in the order the hover lists them. */
+export declare const TEMPLATE_PROPERTIES: Record<string, PropertyDoc>;
+/** The registry the LSP and `dist/meta.json` read: one resource entry. */
+export declare const LEXICON_ENTRIES: Record<string, LexiconEntry>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAE3E,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAwC3D,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CASxD,CAAC"}

package/dist/catalog.js

@@ -0,0 +1,58 @@
+/**
+ * The one kind the e2b lexicon declares, described once.
+ *
+ * The LSP's completions and hover, the bundle's `dist/meta.json` and the docs'
+ * resource reference all read this table, so a property added to `Template`
+ * is added here and reaches all three.
+ */
+export const TEMPLATE_TYPE = "E2B::Template";
+/** `Template`'s properties, in the order the hover lists them. */
+export const TEMPLATE_PROPERTIES = {
+    name: {
+        type: "string",
+        required: true,
+        description: "The template's name on E2B: lowercase letters, digits, dashes and underscores. A profile's `template` names it.",
+    },
+    fromImage: {
+        type: "string",
+        required: true,
+        description: "The image the template starts from, such as `node:22-bookworm`. Pin a tag.",
+    },
+    run: {
+        type: "string[]",
+        description: "Shell commands run in order while the template builds, one `RUN` line each.",
+    },
+    env: {
+        type: "Record<string, string>",
+        description: "Environment variables set in every sandbox made from the template.",
+    },
+    workdir: {
+        type: "string",
+        description: "The working directory for the `run` steps and the start command.",
+    },
+    startCmd: {
+        type: "string",
+        description: "The start command (`--cmd`): E2B runs it when the template is snapshotted, so a sandbox starts with it running.",
+    },
+    readyCmd: {
+        type: "string",
+        description: "The ready command (`--ready-cmd`): E2B polls it until it exits 0 before it snapshots the template.",
+    },
+    cpuCount: {
+        type: "number",
+        description: "vCPUs per sandbox. A positive integer; E2B's default is 2.",
+    },
+    memoryMB: {
+        type: "number",
+        description: "Memory per sandbox in MiB. A positive even integer; E2B's default is 1024.",
+    },
+};
+/** The registry the LSP and `dist/meta.json` read: one resource entry. */
+export const LEXICON_ENTRIES = {
+    Template: {
+        resourceType: TEMPLATE_TYPE,
+        kind: "resource",
+        lexicon: "e2b",
+        propertyConstraints: Object.fromEntries(Object.entries(TEMPLATE_PROPERTIES).map(([name, p]) => [name, { type: p.type, required: p.required ?? false }])),
+    },
+};

package/dist/codegen/docs-cli.d.ts

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

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

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

package/dist/codegen/docs-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+generateDocs({ verbose: true }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/codegen/docs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * e2b documentation generator.
+ *
+ * Calls the core docsPipeline. The how-to and reference pages are authored
+ * MDX under `docs/pages/`, each tagged with its Diátaxis quadrant; this file
+ * holds the overview and the serialization page. writeDocsSite puts the pages
+ * in the main docs site under docs/src/content/docs/lexicons/e2b/ (chant #3993).
+ */
+/**
+ * Generate the e2b lexicon's docs.
+ */
+export declare function generateDocs(options?: {
+    verbose?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/codegen/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmGH;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBjF"}

package/dist/codegen/docs.js

@@ -0,0 +1,123 @@
+/**
+ * e2b documentation generator.
+ *
+ * Calls the core docsPipeline. The how-to and reference pages are authored
+ * MDX under `docs/pages/`, each tagged with its Diátaxis quadrant; this file
+ * holds the overview and the serialization page. writeDocsSite puts the pages
+ * in the main docs site under docs/src/content/docs/lexicons/e2b/ (chant #3993).
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const overview = `The **e2b** lexicon runs chant Ops on a steward: one [E2B](https://e2b.dev) sandbox that outlives every run. \`chant run <op> --on e2b\` hands the run to it. The steward 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 can host it, hosted E2B or a platform of your own.
+
+The lexicon also declares one kind, \`Template\`, for the image a steward is made from. \`chant build\` writes each template as \`e2b.<name>.Dockerfile\`, and the \`e2b template create\` command line that builds it.
+
+Install it with:
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-e2b
+\`\`\`
+
+## Quick Start
+
+Point a profile at your E2B account in \`chant.config.ts\`:
+
+\`\`\`typescript
+import type { ChantConfig } from "@intentius/chant/config";
+import "@intentius/chant-lexicon-e2b";
+
+export default {
+  lexicons: ["e2b"],
+  e2b: {
+    profiles: {
+      prod: {
+        apiKey: { env: "E2B_API_KEY" },
+        template: "chant-steward",
+        gitToken: { env: "GITHUB_TOKEN" },
+      },
+    },
+    defaultProfile: "prod",
+  },
+} satisfies ChantConfig;
+\`\`\`
+
+Declare the template it names, with the tools the project's Ops call:
+
+\`\`\`typescript
+import { Template } from "@intentius/chant-lexicon-e2b";
+
+const steward = new Template({
+  name: "chant-steward",
+  fromImage: "node:22-bookworm",
+  run: ["apt-get update && apt-get install -y --no-install-recommends jq && rm -rf /var/lib/apt/lists/*"],
+  cpuCount: 2,
+  memoryMB: 2048,
+});
+
+export { steward };
+\`\`\`
+
+Then build the template once and run an Op on the steward:
+
+\`\`\`bash
+chant build src --lexicon e2b -o dist/e2b.json
+(cd dist && e2b template create chant-steward --dockerfile e2b.chant-steward.Dockerfile --cpu-count 2 --memory-mb 2048)
+chant run prod-apply --on e2b
+\`\`\``;
+const outputFormat = `The e2b lexicon writes each \`Template\` as a Dockerfile named after the template, so several can share a directory, and indexes them with the command that builds each one.
+
+## Building
+
+\`e2b.<name>.Dockerfile\` starts \`FROM\` the template's \`fromImage\`. Each \`env\` entry becomes an \`ENV\` line and each \`run\` step a \`RUN\` line, in order, with \`WORKDIR\` between them when \`workdir\` is set:
+
+\`\`\`dockerfile
+FROM node:22-bookworm
+ENV CI="1"
+RUN apt-get update && apt-get install -y --no-install-recommends jq && rm -rf /var/lib/apt/lists/*
+\`\`\`
+
+The primary output is a JSON index of the templates, keyed by the name each was exported as. \`build\` is the \`e2b template create\` command line for the template. It names the Dockerfile and passes \`--cmd\`, \`--ready-cmd\`, \`--cpu-count\` and \`--memory-mb\` only when the declaration sets them:
+
+\`\`\`json
+{
+  "templates": {
+    "steward": {
+      "name": "chant-steward",
+      "dockerfile": "e2b.chant-steward.Dockerfile",
+      "build": "e2b template create chant-steward --dockerfile e2b.chant-steward.Dockerfile --cpu-count 2 --memory-mb 2048",
+      "cpuCount": 2,
+      "memoryMB": 2048
+    }
+  }
+}
+\`\`\`
+
+A project that declares no template gets \`{ "templates": {} }\`.
+
+## Applying
+
+chant does not build templates. Run each template's \`build\` command in the output directory, once, and again when the declaration changes. A profile's \`template\` then names the template, and the next steward made from that profile starts from it. A steward that already exists keeps the sandbox it has; delete it to have the next run make a new one.`;
+/**
+ * Generate the e2b lexicon's docs.
+ */
+export async function generateDocs(options) {
+    const config = {
+        name: "e2b",
+        displayName: "E2B",
+        description: "Run chant Ops on a steward sandbox on E2B, and declare the template it is made from",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        srcDir: join(pkgDir, "src"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/e2b/",
+        overview,
+        outputFormat,
+        serviceFromType: (type) => type.split("::")[1] ?? type,
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (options?.verbose) {
+        console.error(`Generated docs: ${result.stats.resources} resources, ${result.stats.rules} rules`);
+    }
+}

package/dist/codegen/generate-cli.d.ts

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

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

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

package/dist/codegen/generate-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+/** `npm run generate` for the e2b lexicon: writes the post-synth barrel. */
+import { generate } from "./generate.js";
+console.error(`Generated the e2b post-synth barrel: ${generate()} checks`);

package/dist/codegen/generate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generation for the e2b lexicon.
+ *
+ * The lexicon's one kind is written by hand (../resources.ts), so there is no
+ * upstream spec to generate types from. What is generated is the static
+ * barrel of post-synth checks, `src/lint/post-synth/index.ts`, the same file
+ * every lexicon's generate step writes (#409).
+ */
+/** Write the post-synth barrel and return how many checks it lists. */
+export declare function generate(): number;
+//# sourceMappingURL=generate.d.ts.map

package/dist/codegen/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/codegen/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,uEAAuE;AACvE,wBAAgB,QAAQ,IAAI,MAAM,CAMjC"}

package/dist/codegen/generate.js

@@ -0,0 +1,20 @@
+/**
+ * Generation for the e2b lexicon.
+ *
+ * The lexicon's one kind is written by hand (../resources.ts), so there is no
+ * upstream spec to generate types from. What is generated is the static
+ * barrel of post-synth checks, `src/lint/post-synth/index.ts`, the same file
+ * every lexicon's generate step writes (#409).
+ */
+import { writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { renderPostSynthBarrelForDir } from "@intentius/chant/codegen/generate-post-synth-barrel";
+/** Write the post-synth barrel and return how many checks it lists. */
+export function generate() {
+    const srcDir = dirname(moduleSourceDir(import.meta.url));
+    const postSynthDir = join(srcDir, "lint", "post-synth");
+    const content = renderPostSynthBarrelForDir(postSynthDir, import.meta.url);
+    writeFileSync(join(postSynthDir, "index.ts"), content);
+    return (content.match(/^  \w/gm) ?? []).length;
+}

package/dist/codegen/package.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Package the e2b lexicon: `dist/manifest.json`, `dist/meta.json`, the rules
+ * and the skills. There is no generation step to run first; the registry is
+ * the hand-written catalog in ../catalog.ts.
+ */
+export declare function packageLexicon(options?: {
+    verbose?: boolean;
+    force?: boolean;
+}): Promise<import("@intentius/chant").PackageResult>;
+//# sourceMappingURL=package.d.ts.map

package/dist/codegen/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/codegen/package.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,qDA0BpF"}

package/dist/codegen/package.js

@@ -0,0 +1,34 @@
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { LEXICON_ENTRIES } from "../catalog.js";
+import { e2bPlugin } from "../plugin.js";
+/**
+ * Package the e2b lexicon: `dist/manifest.json`, `dist/meta.json`, the rules
+ * and the skills. There is no generation step to run first; the registry is
+ * the hand-written catalog in ../catalog.ts.
+ */
+export async function packageLexicon(options) {
+    const srcDir = dirname(moduleSourceDir(import.meta.url));
+    const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: async () => ({
+            lexiconJSON: JSON.stringify(LEXICON_ENTRIES, null, 2),
+            typesDTS: 'export * from "../index.js";\n',
+            indexTS: "",
+            resources: Object.values(LEXICON_ENTRIES).filter((e) => e.kind === "resource").length,
+            properties: 0,
+            enums: 0,
+            warnings: [],
+        }),
+        buildManifest: () => ({
+            name: "e2b",
+            version: pkgJson.version ?? "0.0.0",
+            chantVersion: ">=0.1.0",
+            namespace: "E2B",
+        }),
+        srcDir,
+        collectSkills: () => collectSkills(e2bPlugin.skills?.() ?? []),
+    }, options);
+}

package/dist/config.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The `e2b` namespace in `chant.config.ts`.
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-e2b";   // brings the `e2b` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["e2b"],
+ *   e2b: {
+ *     profiles: {
+ *       prod: {
+ *         apiKey: { env: "E2B_API_KEY" },
+ *         domain: "e2b.loam.example.com",     // omit for hosted E2B
+ *         steward: "prod-steward",
+ *         gitToken: { env: "GITHUB_TOKEN" },
+ *       },
+ *     },
+ *     defaultProfile: "prod",
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * One schema, three consumers, as for fountain's namespace: core validates the
+ * namespace against it at load, the type below is derived from it, and that
+ * type augments `ChantConfig`. A project with no `e2b.profiles` keeps working:
+ * the runtime falls back to `E2B_API_KEY`, `E2B_DOMAIN` and `CHANT_GIT_TOKEN`.
+ */
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+export declare const e2bProfileSchema: z.ZodObject<{
+    /** The E2B API key, by environment variable. Default `E2B_API_KEY`. */
+    apiKey: z.ZodOptional<z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>>;
+    /**
+     * The E2B domain the SDK talks to: `api.<domain>` and `<port>-<id>.<domain>`.
+     * Omitted, the SDK's own default (hosted E2B, or `E2B_DOMAIN`).
+     */
+    domain: z.ZodOptional<z.ZodString>;
+    /** The template a steward's sandbox is made from. Default `base`. It needs git and Node. */
+    template: z.ZodOptional<z.ZodString>;
+    /**
+     * The steward's name: the one sandbox every run of this profile lands on,
+     * found again by its `chant/steward` metadata. Default: the repository's name.
+     */
+    steward: z.ZodOptional<z.ZodString>;
+    /**
+     * The repository the sandbox clones, as an https URL. Default: `origin`'s
+     * URL, with an ssh URL rewritten to https.
+     */
+    repo: z.ZodOptional<z.ZodString>;
+    /**
+     * A token for that repository, by environment variable, so the sandbox can
+     * fetch a private repo and push chant's ledger branch. It is handed to each
+     * command in the sandbox and never written to its disk.
+     */
+    gitToken: z.ZodOptional<z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const e2bConfigSchema: z.ZodObject<{
+    profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** The E2B API key, by environment variable. Default `E2B_API_KEY`. */
+        apiKey: z.ZodOptional<z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>>;
+        /**
+         * The E2B domain the SDK talks to: `api.<domain>` and `<port>-<id>.<domain>`.
+         * Omitted, the SDK's own default (hosted E2B, or `E2B_DOMAIN`).
+         */
+        domain: z.ZodOptional<z.ZodString>;
+        /** The template a steward's sandbox is made from. Default `base`. It needs git and Node. */
+        template: z.ZodOptional<z.ZodString>;
+        /**
+         * The steward's name: the one sandbox every run of this profile lands on,
+         * found again by its `chant/steward` metadata. Default: the repository's name.
+         */
+        steward: z.ZodOptional<z.ZodString>;
+        /**
+         * The repository the sandbox clones, as an https URL. Default: `origin`'s
+         * URL, with an ssh URL rewritten to https.
+         */
+        repo: z.ZodOptional<z.ZodString>;
+        /**
+         * A token for that repository, by environment variable, so the sandbox can
+         * fetch a private repo and push chant's ledger branch. It is handed to each
+         * command in the sandbox and never written to its disk.
+         */
+        gitToken: z.ZodOptional<z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    /** Profile used when a run names none. */
+    defaultProfile: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type E2bProfile = z.infer<typeof e2bProfileSchema>;
+export type E2bConfig = z.infer<typeof e2bConfigSchema>;
+declare module "@intentius/chant/config" {
+    interface ChantConfig {
+        e2b?: E2bConfig;
+    }
+}
+/** Compile-time proof that the augmentation reaches `ChantConfig`, as in fountain's config. */
+export type E2bConfigNamespace = NonNullable<ChantConfig["e2b"]>;
+/**
+ * The named profile, else `defaultProfile`, else `undefined`. A name that is
+ * not declared is an error rather than a fall back to the default: running
+ * against the wrong steward because a profile name was misspelt is the one
+ * mistake a runtime must not make.
+ */
+export declare function resolveProfile(config: Pick<ChantConfig, "e2b"> | undefined, name?: string): E2bProfile | undefined;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,eAAO,MAAM,gBAAgB;IAC3B,uEAAuE;;;;IAEvE;;;OAGG;;IAEH,4FAA4F;;IAE5F;;;OAGG;;IAEH;;;OAGG;;IAEH;;;;OAIG;;;;kBAEH,CAAC;AAEH,eAAO,MAAM,eAAe;;QA3B1B,uEAAuE;;;;QAEvE;;;WAGG;;QAEH,4FAA4F;;QAE5F;;;WAGG;;QAEH;;;WAGG;;QAEH;;;;WAIG;;;;;IAMH,0CAA0C;;kBAE1C,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,GAAG,CAAC,EAAE,SAAS,CAAC;KACjB;CACF;AAED,+FAA+F;AAC/F,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAclH"}