@intentius/chant 0.124.31 → 0.124.33

package/src/lint/discover.test.ts

@@ -1,7 +1,9 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { discoverLintRules, discoverPostSynthChecks } from "./discover";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { discoverLintRules, discoverPostSynthChecks, listRuleFiles } from "./discover";
 
 const thisDir = dirname(fileURLToPath(import.meta.url));
 
@@ -67,3 +69,45 @@ describe("discoverPostSynthChecks", () => {
     expect(checks.length).toBe(0);
   });
 });
+
+describe("rule modules compiled to JS (#3981)", () => {
+  let dir: string;
+
+  beforeAll(() => {
+    // A compiled rules directory: ES modules in a "type": "module" package, each with its declarations beside it.
+    dir = mkdtempSync(join(tmpdir(), "chant-discover-js-"));
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ type: "module" }));
+    writeFileSync(join(dir, "alpha.js"), `export const alpha = { id: "JS002", severity: "warning", category: "style", check: () => [] };\n`);
+    writeFileSync(join(dir, "alpha.d.ts"), `export declare const alpha: unknown;\n`);
+    writeFileSync(join(dir, "beta.js"), `export const beta = { id: "JS001", severity: "error", category: "security", check: () => [] };\n`);
+    writeFileSync(join(dir, "beta.d.ts"), `export declare const beta: unknown;\n`);
+    writeFileSync(join(dir, "gamma.js"), `export const gamma = { id: "JSP001", description: "a post-synth check", check: () => [] };\n`);
+    writeFileSync(join(dir, "index.js"), `export * from "./alpha.js";\n`);
+    writeFileSync(join(dir, "rule-helpers.js"), `export const helper = 1;\n`);
+    writeFileSync(join(dir, "alpha.test.js"), `throw new Error("a test is not a rule");\n`);
+  });
+
+  afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("listRuleFiles lists .js modules and leaves out declarations, tests, helpers and the index", () => {
+    expect(listRuleFiles(dir).sort()).toEqual(["alpha.js", "beta.js", "gamma.js"]);
+  });
+
+  test("a source module and its compiled twin list once, as the source", () => {
+    const both = mkdtempSync(join(tmpdir(), "chant-discover-both-"));
+    try {
+      for (const f of ["one.ts", "one.js", "one.d.ts", "two.js"]) writeFileSync(join(both, f), "");
+      expect(listRuleFiles(both).sort()).toEqual(["one.ts", "two.js"]);
+    } finally {
+      rmSync(both, { recursive: true, force: true });
+    }
+  });
+
+  test("discoverLintRules loads compiled rules", () => {
+    expect(discoverLintRules(dir, import.meta.url).map((r) => r.id)).toEqual(["JS001", "JS002"]);
+  });
+
+  test("discoverPostSynthChecks loads compiled checks", () => {
+    expect(discoverPostSynthChecks(dir, import.meta.url).map((c) => c.id)).toEqual(["JSP001"]);
+  });
+});

package/src/lint/discover.ts

@@ -1,8 +1,11 @@
 /**
  * Auto-discovery for lint rules and post-synth checks.
  *
- * Scans directories for .ts files and loads exported rules/checks,
- * eliminating the need to manually list every rule in plugin.ts.
+ * Scans directories for rule modules and loads exported rules/checks,
+ * eliminating the need to manually list every rule in plugin.ts. A lexicon
+ * run from source has `.ts` rule modules; one run compiled has `.js` modules
+ * beside `.d.ts` declarations (#3981). Both are found, and tsx is registered
+ * only when a module found is TypeScript.
  */
 
 import { readdirSync } from "fs";
@@ -11,6 +14,7 @@ import { createRequire } from "module";
 import type { LintRule } from "./rule";
 import type { PostSynthCheck } from "./post-synth";
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { isTypeScriptModule } from "../module-source";
 
 let cjsTypeScript = false;
 
@@ -22,7 +26,8 @@ let cjsTypeScript = false;
  * From source this runs when the module loads, as it always has: vitest and
  * the source CLI rely on tsx's CommonJS hook being in place from then on. The
  * compiled CLI imports this module on every start and most commands read no
- * rule directory, so there it waits for the first one (#3878).
+ * rule directory, so there it waits for the first directory that holds a
+ * TypeScript rule module (#3878, #3981).
  */
 function registerTypeScriptRequire(): void {
   if (cjsTypeScript) return;
@@ -40,82 +45,83 @@ function registerTypeScriptRequire(): void {
 if (!import.meta.url.endsWith(".js")) registerTypeScriptRequire();
 
 /**
- * Discover lint rules from a directory.
- *
- * Scans the directory for .ts files (excluding tests, helpers, and index files),
- * loads each module, and collects any exported objects that look like a LintRule
- * (has `id`, `severity`, `category`, and `check` function).
- *
- * @param dir - Absolute path to the rules directory
- * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ * Load every rule module in `dir` and collect the exports `accept` takes.
+ * Registers tsx first only when one of the modules is TypeScript.
  */
-export function discoverLintRules(dir: string, importMetaUrl: string): LintRule[] {
-  registerTypeScriptRequire();
+function discoverExports<T>(dir: string, importMetaUrl: string, accept: (value: unknown) => value is T): T[] {
+  const files = listRuleFiles(dir);
+  if (files.some(isTypeScriptModule)) registerTypeScriptRequire();
   const require = createRequire(importMetaUrl);
-  const rules: LintRule[] = [];
-
-  for (const file of listRuleFiles(dir)) {
+  const found: T[] = [];
+  for (const file of files) {
     try {
-      // Strip .ts extension — require() resolves without it
-      const modPath = join(dir, file.replace(/\.ts$/, ""));
-      const mod = require(modPath);
+      const mod = require(join(dir, file)) as Record<string, unknown>;
       for (const exp of Object.values(mod)) {
-        if (isLintRule(exp)) rules.push(exp);
+        if (accept(exp)) found.push(exp);
       }
     } catch {
       // Skip files that fail to load
     }
   }
+  return found;
+}
 
-  return rules.sort((a, b) => a.id.localeCompare(b.id));
+/**
+ * Discover lint rules from a directory.
+ *
+ * Scans the directory for rule modules (see {@link listRuleFiles}), loads
+ * each one, and collects any exported objects that look like a LintRule (has
+ * `id`, `severity`, `category`, and `check` function).
+ *
+ * @param dir - Absolute path to the rules directory
+ * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ */
+export function discoverLintRules(dir: string, importMetaUrl: string): LintRule[] {
+  return discoverExports(dir, importMetaUrl, isLintRule).sort((a, b) => a.id.localeCompare(b.id));
 }
 
 /**
  * Discover post-synth checks from a directory.
  *
- * Scans the directory for .ts files (excluding tests, helpers, and index files),
- * loads each module, and collects any exported objects that look like a PostSynthCheck
- * (has `id`, `description`, and `check` function).
+ * Scans the directory for rule modules (see {@link listRuleFiles}), loads
+ * each one, and collects any exported objects that look like a
+ * PostSynthCheck (has `id`, `description`, and `check` function).
  *
  * @param dir - Absolute path to the post-synth rules directory
  * @param importMetaUrl - The caller's import.meta.url (for createRequire)
  */
 export function discoverPostSynthChecks(dir: string, importMetaUrl: string): PostSynthCheck[] {
-  registerTypeScriptRequire();
-  const require = createRequire(importMetaUrl);
-  const checks: PostSynthCheck[] = [];
-
-  for (const file of listRuleFiles(dir)) {
-    try {
-      // Strip .ts extension — require() resolves without it
-      const modPath = join(dir, file.replace(/\.ts$/, ""));
-      const mod = require(modPath);
-      for (const exp of Object.values(mod)) {
-        if (isPostSynthCheck(exp)) checks.push(exp);
-      }
-    } catch {
-      // Skip files that fail to load
-    }
-  }
+  return discoverExports(dir, importMetaUrl, isPostSynthCheck).sort((a, b) => a.id.localeCompare(b.id));
+}
 
-  return checks.sort((a, b) => a.id.localeCompare(b.id));
+/** A rule module's name without its extension: `foo` for `foo.ts` and `foo.js`. */
+export function ruleModuleBase(file: string): string {
+  return file.replace(/\.(?:ts|js)$/, "");
 }
 
 /**
- * List rule files in a directory (excluding tests, helpers, index).
+ * List rule modules in a directory: `.ts` source or compiled `.js`, leaving
+ * out declarations (`.d.ts`), tests, helpers and the index. A directory
+ * holding both `foo.ts` and `foo.js` lists `foo.ts` alone, so a rule is
+ * never loaded twice.
  */
 export function listRuleFiles(dir: string): string[] {
+  let entries: string[];
   try {
-    return readdirSync(dir).filter((f) => {
-      if (!f.endsWith(".ts")) return false;
-      if (f.endsWith(".test.ts")) return false;
-      if (f === "index.ts") return false;
-      if (f.includes("helper")) return false;
-      return true;
-    });
+    entries = readdirSync(dir);
   } catch {
     return [];
   }
+  const modules = entries.filter((f) => {
+    if (!f.endsWith(".ts") && !f.endsWith(".js")) return false;
+    if (f.endsWith(".d.ts")) return false;
+    if (/\.test\.[tj]s$/.test(f)) return false;
+    if (f === "index.ts" || f === "index.js") return false;
+    if (f.includes("helper")) return false;
+    return true;
+  });
+  const sources = new Set(modules.filter((f) => f.endsWith(".ts")).map(ruleModuleBase));
+  return modules.filter((f) => f.endsWith(".ts") || !sources.has(ruleModuleBase(f)));
 }
 
 function isLintRule(obj: unknown): obj is LintRule {

package/src/lint/rules/op/index.ts

@@ -16,6 +16,7 @@ import { ops014 } from "./ops014-converge-rule-refusals";
 import { ops015 } from "./ops015-gate-approval";
 import { ops016 } from "./ops016-gate-resume";
 import { ops017Check } from "./ops017-gate-alias";
+import { ops018 } from "./ops018-shell-image-digest";
 import { sys010Check } from "./sys010-key-over-plain-http";
 import type { DecideBackend } from "../../../op/decide-config";
 
@@ -25,6 +26,7 @@ export { ops014 } from "./ops014-converge-rule-refusals";
 export { ops015 } from "./ops015-gate-approval";
 export { ops016 } from "./ops016-gate-resume";
 export { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias";
+export { ops018 } from "./ops018-shell-image-digest";
 export { sys010, sys010Check } from "./sys010-key-over-plain-http";
 
 export interface CoreOpCheckOptions {
@@ -36,9 +38,9 @@ export interface CoreOpCheckOptions {
 
 /**
  * Core's own post-synth checks over the Op model: OPS012, OPS013, OPS014,
- * OPS015, OPS016, OPS017 over the workspace's `identity.gates`, and SYS010
+ * OPS015, OPS016, OPS017 over the workspace's `identity.gates`, OPS018, and SYS010
  * over the `decide` steps and the configured decide backends.
  */
 export function coreOpChecks(opts: CoreOpCheckOptions = {}): PostSynthCheck[] {
-  return [ops012, ops013, ops014, ops015, ops016, ops017Check(opts.identityGates), sys010Check(opts.decideBackends)];
+  return [ops012, ops013, ops014, ops015, ops016, ops017Check(opts.identityGates), ops018, sys010Check(opts.decideBackends)];
 }

package/src/lint/rules/op/ops018-shell-image-digest.test.ts

@@ -0,0 +1,60 @@
+/**
+ * OPS018 (#4015): a shell step's image is pinned by digest.
+ */
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "../../post-synth";
+import { DECLARABLE_MARKER } from "../../../declarable";
+import { stepOutput } from "../../../op/step-output-ref";
+import { ops018 } from "./ops018-shell-image-digest";
+import { coreOpChecks } from "./index";
+
+const PINNED = `node:24@sha256:${"d".repeat(64)}`;
+
+function ctxWith(props: Record<string, unknown>): PostSynthContext {
+  const entities = new Map<string, unknown>([["build", {
+    [DECLARABLE_MARKER]: true,
+    entityType: "Chant::Op",
+    lexicon: "chant",
+    kind: "resource",
+    props: { name: "build", overview: "test", ...props },
+    attributes: {},
+  }]]);
+  return {
+    outputs: new Map([["chant", ""]]),
+    entities: entities as Map<string, never>,
+    buildResult: { outputs: new Map([["chant", ""]]), entities: entities as Map<string, never>, warnings: [], errors: [], sourceFileCount: 1 },
+  };
+}
+
+const sh = (args: Record<string, unknown>) => ({ kind: "activity", fn: "shellCmd", args: { cmd: "npm test", ...args } });
+
+describe("OPS018", () => {
+  test("is one of core's Op checks", () => {
+    expect(coreOpChecks().map((c) => c.id)).toContain("OPS018");
+  });
+
+  test("a pinned image and a step with no image pass", () => {
+    expect(ops018.check(ctxWith({ phases: [{ name: "Build", steps: [sh({ image: PINNED }), sh({})] }] }))).toEqual([]);
+  });
+
+  test("a tag is refused, naming the Op, the phase and the fix", () => {
+    const [diag, ...rest] = ops018.check(ctxWith({ phases: [{ name: "Build", steps: [sh({ image: "node:24" })] }] }));
+    expect(rest).toEqual([]);
+    expect(diag?.checkId).toBe("OPS018");
+    expect(diag?.severity).toBe("error");
+    expect(diag?.message).toBe('Op "build", phase "Build", shellCmd: image "node:24" is not pinned by digest: name it as <ref>@sha256:<digest>');
+  });
+
+  test("an image read from another step is refused, since the record could not say what ran", () => {
+    const [diag] = ops018.check(ctxWith({ phases: [{ name: "Build", steps: [sh({ image: stepOutput("pick", "stdout") })] }] }));
+    expect(diag?.message).toContain("image must be a literal string");
+  });
+
+  test("onFailure and effect steps are checked too", () => {
+    const diags = ops018.check(ctxWith({
+      phases: [{ name: "Apply", steps: [{ kind: "effect", receipt: {}, steps: [sh({ image: "alpine" })] }] }],
+      onFailure: [{ name: "Rollback", steps: [sh({ image: "alpine:latest" })] }],
+    }));
+    expect(diags.map((d) => d.message.split(",")[1]?.trim())).toEqual(['phase "Apply"', 'phase "Rollback"']);
+  });
+});

package/src/lint/rules/op/ops018-shell-image-digest.ts

@@ -0,0 +1,48 @@
+/**
+ * OPS018: a `shellCmd` step that runs in a container (#4015) names its image
+ * pinned by digest, `<ref>@sha256:<digest>`, as a literal string. A tag can
+ * move between two runs of the same Op, and then the step record's image no
+ * longer says what ran. Checked over the main phases, `onFailure`, and the
+ * steps inside an effect.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
+import type { OpConfig, PhaseDefinition, StepDefinition } from "../../../op";
+import { imageProblem } from "../../../op/activities/shell";
+import { isOpEntity } from "./support";
+
+function activitySteps(steps: readonly StepDefinition[]): Array<{ fn: string; args?: Record<string, unknown> }> {
+  return steps.flatMap((step) =>
+    step.kind === "activity" ? [step] : step.kind === "effect" ? step.steps.filter((s) => s.kind === "activity") : [],
+  ) as Array<{ fn: string; args?: Record<string, unknown> }>;
+}
+
+export const ops018: PostSynthCheck = {
+  id: "OPS018",
+  description: "A shell step with an image names it pinned by digest, as a literal string",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [entityKey, entity] of ctx.entities) {
+      if (!isOpEntity(entity)) continue;
+      const rec = entity as unknown as Record<string, unknown>;
+      const props = ((entity as { props?: Record<string, unknown> }).props ?? {}) as unknown as OpConfig;
+      if (typeof props.name !== "string" || !Array.isArray(props.phases)) continue;
+      const phases: PhaseDefinition[] = [...props.phases, ...(props.onFailure ?? [])];
+      for (const phase of phases) {
+        for (const step of activitySteps(phase.steps ?? [])) {
+          if (step.fn !== "shellCmd" || step.args?.image === undefined) continue;
+          const problem = imageProblem(step.args.image);
+          if (!problem) continue;
+          diagnostics.push({
+            checkId: "OPS018",
+            severity: "error",
+            message: `Op "${props.name}", phase "${phase.name}", shellCmd: ${problem}`,
+            entity: entityKey,
+            lexicon: typeof rec.lexicon === "string" ? rec.lexicon : undefined,
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/module-source.test.ts

@@ -0,0 +1,85 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { isJavaScriptModule, isTypeScriptModule, moduleSourceDir, moduleSourceUrl, SOURCE_EXPORT_CONDITIONS } from "./module-source";
+
+describe("module-source (#3981)", () => {
+  test("from source, chant's own resolution adds the development condition", () => {
+    expect(SOURCE_EXPORT_CONDITIONS).toEqual(["development"]);
+  });
+
+  const pkg = join(sep, "x", "node_modules", "@intentius", "chant-lexicon-aws");
+
+  test("moduleSourceDir maps a compiled module's directory to the source directory", () => {
+    expect(moduleSourceDir(pathToFileURL(join(pkg, "dist", "lint", "post-synth", "ext001.js")).href)).toBe(join(pkg, "src", "lint", "post-synth"));
+    expect(moduleSourceDir(pathToFileURL(join(pkg, "dist", "taggable.js")).href)).toBe(join(pkg, "src"));
+  });
+
+  test("moduleSourceDir leaves a source module's directory alone, even under a dist/ directory", () => {
+    expect(moduleSourceDir(pathToFileURL(join(pkg, "src", "taggable.ts")).href)).toBe(join(pkg, "src"));
+    const checkout = join(sep, "home", "dist", "chant", "lexicons", "aws", "src", "taggable.ts");
+    expect(moduleSourceDir(pathToFileURL(checkout).href)).toBe(join(sep, "home", "dist", "chant", "lexicons", "aws", "src"));
+  });
+
+  test("moduleSourceUrl is a URL in the source directory, for createRequire", () => {
+    const url = moduleSourceUrl(pathToFileURL(join(pkg, "dist", "lsp", "hover.js")).href);
+    expect(url).toBe(pathToFileURL(join(pkg, "src", "lsp", "hover.js")).href);
+    expect(new URL("../generated/lexicon-aws.json", url).href).toBe(pathToFileURL(join(pkg, "src", "generated", "lexicon-aws.json")).href);
+  });
+
+  test("isTypeScriptModule and isJavaScriptModule", () => {
+    expect(isTypeScriptModule("/p/src/index.ts")).toBe(true);
+    expect(isTypeScriptModule("file:///p/src/index.mts?x=1")).toBe(true);
+    expect(isTypeScriptModule("/p/dist/index.d.ts")).toBe(false);
+    expect(isTypeScriptModule("/p/dist/index.js")).toBe(false);
+    expect(isJavaScriptModule("file:///p/dist/index.js")).toBe(true);
+    expect(isJavaScriptModule("/p/dist/index.mjs")).toBe(true);
+    expect(isJavaScriptModule("/p/src/index.ts")).toBe(false);
+    // No extension: only tsx's resolver completes it, so it is not plain JavaScript.
+    expect(isJavaScriptModule("/p/lexicon/index")).toBe(false);
+  });
+});
+
+describe("package sources run under plain node ESM (#3981)", () => {
+  const repo = resolve(import.meta.dirname, "..", "..", "..");
+  const SKIP_DIRS = new Set(["node_modules", "generated", "testdata", "fixtures", "__fixtures__", "test-fixtures"]);
+
+  function sources(dir: string, out: string[] = []): string[] {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) sources(join(dir, entry.name), out);
+      } else if (/\.ts$/.test(entry.name) && !/\.(test|d)\.ts$/.test(entry.name)) {
+        out.push(join(dir, entry.name));
+      }
+    }
+    return out;
+  }
+
+  test("no lexicon or package source uses the CommonJS __dirname or __filename", () => {
+    // Both are undefined in an ES module under plain node, and under tsx too: a
+    // read built on one throws, and the catch around it hides the data.
+    // moduleSourceDir(import.meta.url) names the source directory from src/ and dist/ alike.
+    const roots = ["lexicons", "packages"].flatMap((top) =>
+      readdirSync(join(repo, top), { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => join(repo, top, e.name, "src")),
+    );
+    const offenders: string[] = [];
+    for (const root of roots) {
+      let files: string[];
+      try {
+        files = sources(root);
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        const code = readFileSync(file, "utf-8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+        code.split("\n").forEach((line, i) => {
+          if (/\b__(?:dirname|filename)\b/.test(line)) offenders.push(`${relative(repo, file)}:${i + 1}: ${line.trim()}`);
+        });
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/module-source.ts

@@ -0,0 +1,112 @@
+/**
+ * #3981 — paths for a module that may run from `src/*.ts` or from compiled
+ * `dist/*.js`.
+ *
+ * A package compiles `src/` to `dist/` with the same layout (`rootDir: src`,
+ * `outDir: dist`), so a compiled module sits at the same relative path under
+ * `dist/` as its source does under `src/`. tsc compiles only the modules: a
+ * file a module reads beside itself (generated JSON, skills markdown,
+ * snapshots) stays under `src/`, which every package publishes. A module that
+ * reads such a file names it from {@link moduleSourceDir}, not from its own
+ * directory, and finds it from either layout.
+ *
+ * String arithmetic only, no filesystem access, so it is safe in a sandboxed
+ * child and costs nothing at module scope.
+ */
+
+import { dirname, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DIST = `${sep}dist${sep}`;
+
+/**
+ * The path a module's source has: `path` itself for a source module, and the
+ * matching path under `<package>/src` for a module under `<package>/dist`.
+ */
+function sourcePathOf(path: string): string {
+  if (!/\.[cm]?js$/.test(path)) return path;
+  const at = path.lastIndexOf(DIST);
+  if (at < 0) return path;
+  return path.slice(0, at) + `${sep}src${sep}` + path.slice(at + DIST.length);
+}
+
+/**
+ * #3981 — the source file a compiled module was built from:
+ * `<package>/dist/x/y.js` is `<package>/src/x/y.ts` (`.mjs` from `.mts`, `.cjs`
+ * from `.cts`). `undefined` for a path that is not a compiled module under a
+ * `dist/`. The file is not checked for.
+ */
+export function compiledModuleSource(path: string): string | undefined {
+  const ext = /\.([cm]?)js$/.exec(path);
+  if (!ext || path.lastIndexOf(DIST) < 0) return undefined;
+  return sourcePathOf(path).slice(0, -ext[0].length) + `.${ext[1]}ts`;
+}
+
+/**
+ * The directory a module's source sits in: `dirname` of `moduleUrl` when it
+ * runs from source, and the matching directory under `<package>/src` when it
+ * runs compiled from `<package>/dist`.
+ */
+export function moduleSourceDir(moduleUrl: string): string {
+  return dirname(sourcePathOf(fileURLToPath(moduleUrl)));
+}
+
+/**
+ * A URL in the module's source directory, for `createRequire` to read a file
+ * that sits beside the source (`require("./generated/lexicon-aws.json")`). The
+ * file name keeps the compiled extension; only the directory matters to
+ * `createRequire`.
+ */
+export function moduleSourceUrl(moduleUrl: string): string {
+  return pathToFileURL(sourcePathOf(fileURLToPath(moduleUrl))).href;
+}
+
+/**
+ * Whether `pathOrUrl` names a TypeScript module, which plain node cannot
+ * import without a loader: `.ts`, `.mts`, `.cts` or `.tsx`, and not a
+ * declaration file. A query or hash is ignored.
+ */
+export function isTypeScriptModule(pathOrUrl: string): boolean {
+  const path = pathOrUrl.replace(/[?#].*$/, "");
+  return /\.(?:[cm]?ts|tsx)$/.test(path) && !/\.d\.[cm]?ts$/.test(path);
+}
+
+/**
+ * Whether plain node imports `pathOrUrl` with no loader: `.js`, `.mjs`,
+ * `.cjs` or `.json`. Anything else, a module with no extension included, is
+ * left to tsx, whose resolver completes an extensionless path.
+ */
+export function isJavaScriptModule(pathOrUrl: string): boolean {
+  return /\.(?:[cm]?js|json)$/.test(pathOrUrl.replace(/[?#].*$/, ""));
+}
+
+/**
+ * #3981 — whether this process resolves chant's packages through their
+ * `development` export condition: always when chant runs from source (the
+ * CLI's `main()` installs a resolve hook that does so, and vitest's resolver
+ * adds the condition outside production mode), and otherwise when node runs
+ * with `--conditions=development` (or `-C development`, on the command line
+ * or in `NODE_OPTIONS`). Not from the environment: a compiled CLI that a test
+ * spawns inherits vitest's variables.
+ */
+function resolvesDevelopment(): boolean {
+  if (isTypeScriptModule(import.meta.url)) return true;
+  if (typeof process === "undefined") return false;
+  const flags = [...process.execArgv, ...(process.env.NODE_OPTIONS ?? "").split(/\s+/)];
+  return flags.some(
+    (flag, i) =>
+      flag === "--conditions=development" ||
+      flag === "-C=development" ||
+      ((flag === "--conditions" || flag === "-C") && flags[i + 1] === "development"),
+  );
+}
+
+/**
+ * #3981 — the package export conditions chant adds to `import`, `node` and
+ * `default` when it resolves a package itself (fold's import resolution, the
+ * sandbox bundle), so it lands on the module this process's `import()` would.
+ * Each chant package maps `development` to `src/*.ts` and `default` to the
+ * compiled `dist/*.js` it publishes. `["development"]` when the process
+ * resolves with it ({@link resolvesDevelopment}), else empty.
+ */
+export const SOURCE_EXPORT_CONDITIONS: readonly string[] = resolvesDevelopment() ? ["development"] : [];

package/src/op/activities/activity-contracts.ts

@@ -59,6 +59,9 @@ export const shellCmdContract = activityContract(
     gatedExit: z.number().optional(),
     gate: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
     json: z.boolean().optional(),
+    image: z.string().optional(),
+    mounts: z.strictObject({ workspace: z.enum(["ro", "rw"]).optional() }).optional(),
+    outputs: z.array(z.string()).optional(),
   }),
   // `json` is stdout parsed, when the step sets `json` (#2787): whatever the
   // command printed, so its shape is the author's and only the whole value is

package/src/op/activities/factory.ts

@@ -357,7 +357,7 @@ function inWorktree(kindFile: string, checkout: string, worktree: string): strin
     }
   };
   const [file, top, tree] = [real(kindFile), real(checkout), real(worktree)];
-  // Read from the worktree already (it sits under the checkout's .git), or outside the checkout: as it is.
+  // Read from the worktree already (it sits in the checkout's .chant/work, #2893), or outside the checkout: as it is.
   if (file.startsWith(`${tree}/`) || !file.startsWith(`${top}/`)) return file;
   return join(tree, file.slice(top.length + 1));
 }

package/src/op/activities/shell-container.e2e.test.ts

@@ -0,0 +1,67 @@
+/**
+ * A `shell()` step in a container (#4015), run for real with `docker run
+ * --rm`. Skipped when Docker is not running. The containers are `--rm` and
+ * mount only host directories, so nothing is left behind.
+ */
+import { execSync } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { shellCmd } from "./shell";
+
+// alpine 3.21, pinned by its index digest.
+const IMAGE = process.env.CHANT_SHELL_E2E_IMAGE ?? "alpine:3.21@sha256:ce64758a109eb420d874a118f87920e625e12d3634e03b4a5573fd9f6e5d3507";
+
+function available(cmd: string): boolean {
+  try {
+    execSync(cmd, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const hasDocker = available("docker info");
+const skipReason = hasDocker ? "" : " (skipped: Docker is not running)";
+
+describe.skipIf(!hasDocker)(`shellCmd with an image${skipReason}`, () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), "chant-shell-e2e-"));
+    await writeFile(join(dir, "input.txt"), "from the host\n");
+    execSync(`docker pull -q ${IMAGE}`, { stdio: "ignore" });
+  }, 120_000);
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("runs in the image, reads the workspace read-only, sees env by name, and writes its output directory on the host", async () => {
+    process.env.CHANT_SHELL_E2E_HOST_ONLY = "leaked";
+    try {
+      const result = await shellCmd({
+        cmd: 'cat /etc/alpine-release >/dev/null && echo "$GREETING:$CHANT_SHELL_E2E_HOST_ONLY" && cat input.txt > out/copy.txt; touch input.txt 2>/dev/null || echo read-only',
+        image: IMAGE,
+        cwd: dir,
+        env: { GREETING: "hi" },
+        outputs: ["out"],
+      });
+      expect(result.stdout.split("\n")).toEqual(["hi:", "read-only"]);
+      expect(await readFile(join(dir, "out", "copy.txt"), "utf8")).toBe("from the host\n");
+    } finally {
+      delete process.env.CHANT_SHELL_E2E_HOST_ONLY;
+    }
+  }, 60_000);
+
+  test("a declared output directory the command left empty fails the step", async () => {
+    await expect(shellCmd({ cmd: "true", image: IMAGE, cwd: dir, outputs: ["empty"] })).rejects.toThrow(/left it empty/);
+  }, 60_000);
+
+  test("keeps the command's exit status, and okExit still applies", async () => {
+    await expect(shellCmd({ cmd: "exit 4", image: IMAGE, cwd: dir })).rejects.toThrow(/command exited 4/);
+    const ok = await shellCmd({ cmd: "echo done; exit 1", image: IMAGE, cwd: dir, okExit: [0, 1] });
+    expect(ok).toMatchObject({ stdout: "done", exitCode: 1 });
+  }, 60_000);
+});