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

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@intentius/chant-lexicon-e2b",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.124.32",
+  "type": "module",
+  "description": "e2b lexicon for chant — run Ops on a steward sandbox on E2B, or any API that speaks E2B's, and declare the template it is made from",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/INTENTIUS/chant#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/INTENTIUS/chant.git",
+    "directory": "lexicons/e2b"
+  },
+  "bugs": {
+    "url": "https://github.com/INTENTIUS/chant/issues"
+  },
+  "keywords": [
+    "chant",
+    "e2b",
+    "sandbox",
+    "ops",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "development": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./lint/post-synth": {
+      "development": "./src/lint/post-synth/index.ts",
+      "types": "./dist/lint/post-synth/index.d.ts",
+      "default": "./dist/lint/post-synth/index.js"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "tsx src/codegen/generate-cli.ts",
+    "bundle": "tsx src/package-cli.ts",
+    "docs": "tsx src/codegen/docs-cli.ts",
+    "prepack": "npm run generate && npm run bundle && npm run build",
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "e2b": "^2.56.0"
+  },
+  "peerDependencies": {
+    "@intentius/chant": "^0.124.32",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@intentius/chant": "*",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^5.9.3"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 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 const TEMPLATE_PROPERTIES: Record<string, PropertyDoc> = {
+  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: Record<string, LexiconEntry> = {
+  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/src/codegen/docs-cli.ts

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

package/src/codegen/docs.ts

@@ -0,0 +1,130 @@
+/**
+ * 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, type DocsConfig } 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?: { verbose?: boolean }): Promise<void> {
+  const config: DocsConfig = {
+    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: string) => 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/src/codegen/generate-cli.ts

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

package/src/codegen/generate.ts

@@ -0,0 +1,22 @@
+/**
+ * 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(): number {
+  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/src/codegen/package.ts

@@ -0,0 +1,39 @@
+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";
+import { e2bPlugin } from "../plugin";
+
+/**
+ * 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?: { verbose?: boolean; force?: boolean }) {
+  const srcDir = dirname(moduleSourceDir(import.meta.url));
+  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8")) as { version?: string };
+
+  return packagePipeline(
+    {
+      generate: async () => ({
+        lexiconJSON: JSON.stringify(LEXICON_ENTRIES, null, 2),
+        typesDTS: 'export * from "../index";\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/src/config.ts

@@ -0,0 +1,102 @@
+/**
+ * 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";
+
+/** A secret named by its environment variable, never a literal value. */
+const envRef = z.strictObject({ env: z.string() });
+
+export const e2bProfileSchema = z.strictObject({
+  /** The E2B API key, by environment variable. Default `E2B_API_KEY`. */
+  apiKey: envRef.optional(),
+  /**
+   * 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.string().optional(),
+  /** The template a steward's sandbox is made from. Default `base`. It needs git and Node. */
+  template: z.string().optional(),
+  /**
+   * 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.string().optional(),
+  /**
+   * The repository the sandbox clones, as an https URL. Default: `origin`'s
+   * URL, with an ssh URL rewritten to https.
+   */
+  repo: z.string().optional(),
+  /**
+   * 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: envRef.optional(),
+});
+
+export const e2bConfigSchema = z.strictObject({
+  profiles: z.record(z.string(), e2bProfileSchema).optional(),
+  /** Profile used when a run names none. */
+  defaultProfile: z.string().optional(),
+});
+
+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 function resolveProfile(config: Pick<ChantConfig, "e2b"> | undefined, name?: string): E2bProfile | undefined {
+  const profiles = config?.e2b?.profiles;
+  if (name !== undefined) {
+    const named = profiles?.[name];
+    if (!named) {
+      throw new Error(
+        `e2b runtime: no profile "${name}" under e2b.profiles in chant.config.ts. ` +
+          `Declare it, or drop --profile to use e2b.defaultProfile.`,
+      );
+    }
+    return named;
+  }
+  const fallback = config?.e2b?.defaultProfile;
+  return fallback !== undefined ? profiles?.[fallback] : undefined;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { e2bPlugin } from "./plugin";
+export { e2bSerializer } from "./serializer";
+export { Template, type TemplateProps } from "./resources";
+export { e2bConfigSchema, e2bProfileSchema, resolveProfile, type E2bConfig, type E2bProfile } from "./config";
+export { createE2bOpRuntime, type E2bOpRuntimeOptions } from "./op/runtime";
+export { e2bSandboxes, STEWARD_METADATA_KEY, type StewardSandbox, type StewardSandboxes } from "./op/sandbox";

package/src/lint/audit-catalog.ts

@@ -0,0 +1,29 @@
+/**
+ * The e2b lexicon's chant audit catalog: metadata for the E2B post-synth
+ * checks, contributed via `e2bPlugin.auditCatalog()`.
+ *
+ * Every check reads the chant model (`ctx.entities`), not the emitted files,
+ * so they fire on `chant build` and not on an audit of a hand-written
+ * `e2b.Dockerfile`.
+ */
+
+import type { RuleMeta } from "@intentius/chant/audit/catalog";
+
+function rule(id: string, tier: RuleMeta["tier"], title: string, remediation: string): RuleMeta {
+  return { id, tier, fixKind: "guidance", category: "correctness", title, remediation, yamlBased: false };
+}
+
+export const e2bAuditCatalog: Record<string, RuleMeta> = {
+  E2B011: rule(
+    "E2B011",
+    "merge-worthy",
+    "Template name is not one E2B accepts, or two templates share it",
+    "Name the template with lowercase letters, digits, dashes and underscores, and give each template its own name.",
+  ),
+  E2B012: rule(
+    "E2B012",
+    "report-only",
+    "Template shows no sign of git or Node",
+    "Start from a `node` image, or add a `run` step that installs git and Node.",
+  ),
+};

package/src/lint/post-synth/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/src/lint/post-synth/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/src/lint/post-synth/index.ts

@@ -0,0 +1,9 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { e2b011 } from "./e2b011-template-name";
+import { e2b012 } from "./e2b012-steward-tools";
+
+export const postSynthChecks: PostSynthCheck[] = [
+  e2b011,
+  e2b012,
+];

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { Template, type TemplateProps } from "../../resources";
+import { postSynthChecks } from "./index";
+import { e2b011 } from "./e2b011-template-name";
+import { e2b012, stewardTools } from "./e2b012-steward-tools";
+
+function ctx(...templates: Array<[string, TemplateProps]>): PostSynthContext {
+  const entities = new Map(templates.map(([n, p]) => [n, new Template(p) as unknown as Declarable]));
+  return { outputs: new Map(), entities, buildResult: { outputs: new Map(), entities, warnings: [], errors: [], sourceFileCount: 1 } };
+}
+
+const GOOD: TemplateProps = { name: "chant-steward", fromImage: "node:22-bookworm" };
+
+describe("e2b post-synth checks", () => {
+  test("the barrel lists the two checks", () => {
+    expect(postSynthChecks.map((c) => c.id)).toEqual(["E2B011", "E2B012"]);
+  });
+
+  test("a full node image passes both", () => {
+    for (const check of postSynthChecks) expect(check.check(ctx(["steward", GOOD])), check.id).toEqual([]);
+  });
+
+  describe("E2B011: template name", () => {
+    test("fails a name E2B refuses", () => {
+      for (const name of ["Chant-Steward", "chant steward", "chant.steward", ""]) {
+        const diags = e2b011.check(ctx(["steward", { ...GOOD, name }]));
+        expect(diags, name).toHaveLength(1);
+        expect(diags[0].severity).toBe("error");
+      }
+    });
+
+    test("fails a second template with the same name", () => {
+      const diags = e2b011.check(ctx(["a", GOOD], ["b", GOOD]));
+      expect(diags).toHaveLength(1);
+      expect(diags[0]).toMatchObject({ entity: "b" });
+      expect(diags[0].message).toContain('"a" and "b"');
+    });
+  });
+
+  describe("E2B012: git and Node", () => {
+    test("stewardTools reads the image and the run steps", () => {
+      expect(stewardTools(GOOD)).toEqual({ git: true, node: true });
+      expect(stewardTools({ ...GOOD, fromImage: "node:22-bookworm-slim" })).toEqual({ git: false, node: true });
+      expect(stewardTools({ ...GOOD, fromImage: "node:22-alpine" })).toEqual({ git: false, node: true });
+      expect(stewardTools({ name: "x", fromImage: "alpine:3.20", run: ["apk add --no-cache git nodejs npm"] })).toEqual({ git: true, node: true });
+      expect(stewardTools({ name: "x", fromImage: "debian:12", run: ["apt-get install -y git nodejs"] })).toEqual({ git: true, node: true });
+      expect(stewardTools({ name: "x", fromImage: "debian:12" })).toEqual({ git: false, node: false });
+    });
+
+    test("warns, naming what is missing", () => {
+      const [d] = e2b012.check(ctx(["steward", { ...GOOD, fromImage: "node:22-bookworm-slim" }]));
+      expect(d).toMatchObject({ checkId: "E2B012", severity: "warning" });
+      expect(d.message).toContain("no sign of git");
+      expect(d.message).not.toContain("Node");
+    });
+  });
+});