@platforma-sdk/block-tools 2.10.13 → 2.10.15

package/src/structure/engine/runner.ts

@@ -0,0 +1,519 @@
+// Engine runner — structural pass, managed pass, post-run recheck.
+//
+// `run(structure, fs, ctx, opts)` drives one block through the structural
+// pass, managed pass, and post-run recheck (DISCOVERY happens in the
+// caller, which constructs `ctx.modules`). The function is shared by
+// `check`, `refresh`,
+// `refresh --update-deps-only`, and `init`. The mode (see `currentMode`)
+// selects which leaves fire — a leaf fires iff its `modes` include the
+// current one:
+//   - dryRun=true                            → check, mode "default" (no
+//                                              writes)
+//   - dryRun=false, updateDepsOnly=false     → refresh, mode "default"
+//                                              (writes + .structure bump +
+//                                              post-run recheck)
+//   - dryRun=false, updateDepsOnly=true      → refresh --update-deps-only,
+//                                              mode "updateDeps" (only
+//                                              onUpdateDeps/onInitOrUpdate
+//                                              leaves fire; no version
+//                                              bump; no recheck)
+//   - dryRun=false, opts.initMode=true       → init, mode "init" (default
+//                                              + onInitOrUpdate leaves +
+//                                              seeds; no recheck — the
+//                                              init→check test runs an
+//                                              explicit dry-run afterwards)
+//
+// Idempotency invariant is enforced by the post-run recheck: after a
+// successful refresh, the runner reruns the lifecycle in dry-run mode (fresh
+// rediscover when supplied) and throws `RecheckError` on any non-empty
+// change list. The error carries the failing item's
+// (scope, path, primitive, action) tuple for diagnostics.
+
+import { stringify as yamlStringify } from "yaml";
+import type { ContentForm, FlatItem, RunMode, Structure, TriggerContext, ManagedBody } from "./ir";
+import type { RunContext, Scope } from "./api";
+import type { FileSystem } from "./fs/api";
+import type { TemplateProvider } from "./templates";
+import { substituteVars } from "./templates";
+import { flatten } from "./flatten";
+import { matchesGlob } from "./glob";
+import { withRunContext } from "./builders";
+import {
+  withManagedBody,
+  withManagedYaml,
+  withManagedLines,
+  resolveSdkSentinelsInJson,
+} from "./content-rules";
+import { parseJson, stringifyJson } from "./parsers/json";
+import type { JsonObject } from "./parsers/json";
+import { parseYaml, stringifyYaml } from "./parsers/yaml";
+import { parseLines, serializeLines } from "./parsers/lines";
+import { writeStructureVersion, STRUCTURE_META_FILE } from "./version";
+
+export type ChangeAction = "create" | "update" | "delete" | "rename" | "noop";
+
+export type Change = {
+  scope: Scope;
+  /** Resolved (block-relative) path. For rename, the source path. */
+  path: string;
+  /** "fixed" | "managed" | "scaffold" | "seed" | "remove" | "rename" */
+  primitive: string;
+  action: ChangeAction;
+};
+
+export type RunResult = {
+  changes: Change[];
+};
+
+export type RunOptions = {
+  /** Called before the post-run recheck to obtain a fresh RunContext
+   *  reflecting the just-written FS state (re-reads `pnpm-workspace.yaml`).
+   *  If absent, recheck reuses the original ctx with `dryRun: true`. */
+  rediscover?: (fs: FileSystem) => RunContext;
+  /** Template provider used by `file(...)` and `tpl(...)` content forms.
+   *  Required whenever the structure references such forms. */
+  templates?: TemplateProvider;
+  /** Init mode: write seed leaves (only-if-missing semantics) and skip
+   *  the post-run recheck. The caller is expected to follow with an
+   *  explicit dry-run check (Layer-2 invariant). */
+  initMode?: boolean;
+  /** Sync accessor for prefetched npm "latest" versions, consumed by
+   *  `ensureCatalogLatest` inside `onUpdateDeps` managed bodies. The CLI
+   *  prefetches the catalog's package versions before the run (network)
+   *  and passes the resulting sync map here; unit tests pass a mock.
+   *  Absent → `ensureCatalogLatest` is a no-op (default refresh). */
+  registryLookup?: (packageName: string) => string | undefined;
+};
+
+export class RecheckError extends Error {
+  constructor(public readonly failing: Change) {
+    super(
+      `Post-run recheck: rule set not idempotent. ` +
+        `Failing item: ${failing.primitive} '${failing.path}' ` +
+        `(scope=${failing.scope}, action=${failing.action}). Engine bug.`,
+    );
+    this.name = "RecheckError";
+  }
+}
+
+/** Resolve a `ContentForm` to its on-disk string for the given file
+ *  path. `file` / `tpl` resolution goes through the configured
+ *  `TemplateProvider`; `generate` returns parsed structure → JSON/YAML
+ *  or a string. */
+function resolveContent(
+  form: ContentForm,
+  filePath: string,
+  templates: TemplateProvider | undefined,
+  isSdkInternal: boolean,
+): string {
+  switch (form.kind) {
+    case "text":
+      return form.value;
+    case "file": {
+      if (!templates) {
+        throw new Error(
+          `file('${form.path}'): no TemplateProvider configured. ` +
+            `Pass opts.templates to engine.run(...).`,
+        );
+      }
+      return templates.staticRead(form.path);
+    }
+    case "tpl": {
+      if (!templates) {
+        throw new Error(
+          `tpl('${form.path}'): no TemplateProvider configured. ` +
+            `Pass opts.templates to engine.run(...).`,
+        );
+      }
+      const raw = templates.textRead(form.path);
+      const vars = typeof form.vars === "function" ? form.vars() : form.vars;
+      return substituteVars(raw, vars);
+    }
+    case "generate": {
+      const value = form.fn();
+      if (filePath.endsWith(".json")) {
+        // Resolve `sdk:` sentinels in the generated dep sections so the
+        // initial content matches what the body rules re-assert.
+        resolveSdkSentinelsInJson(value, isSdkInternal);
+        // package.json stays fully expanded (oxfmt's package.json shape);
+        // every other .json collapses to oxfmt's generic-file shape.
+        return stringifyJson(value, { collapse: !filePath.endsWith("package.json") });
+      }
+      if (filePath.endsWith(".yaml") || filePath.endsWith(".yml")) {
+        return yamlStringify(value);
+      }
+      if (typeof value !== "string") {
+        throw new Error(
+          `generate() for '${filePath}' must return a string for non-JSON/YAML files; got ${typeof value}`,
+        );
+      }
+      return value;
+    }
+    case "binary":
+      throw new Error(
+        `binary('${form.path}') cannot be resolved to a string; it is only valid ` +
+          `inside seed()/scaffold(), which copy it verbatim via fs.writeBinary.`,
+      );
+  }
+}
+
+/** Write a leaf's content to disk, dispatching binary assets (copied
+ *  verbatim, never utf-8 decoded) from string content. */
+function writeLeafContent(
+  fs: FileSystem,
+  resolvedPath: string,
+  form: ContentForm,
+  templates: TemplateProvider | undefined,
+  isSdkInternal: boolean,
+): void {
+  if (form.kind === "binary") {
+    if (!templates) {
+      throw new Error(
+        `binary('${form.path}'): no TemplateProvider configured. ` +
+          `Pass opts.templates to engine.run(...).`,
+      );
+    }
+    fs.writeBinary(resolvedPath, templates.staticReadBinary(form.path));
+    return;
+  }
+  fs.write(resolvedPath, resolveContent(form, resolvedPath, templates, isSdkInternal));
+}
+
+/** Dispatch managed-body parse → mutate → serialize by file extension /
+ *  basename. JSON, YAML, and lines all share the same `(initial, body,
+ *  triggerContext) → newRaw` shape via the active-state wrappers in
+ *  `content-rules.ts`. */
+function runManagedBody(
+  path: string,
+  raw: string,
+  body: ManagedBody,
+  tctx: TriggerContext,
+  registryLookup: ((packageName: string) => string | undefined) | undefined,
+): string {
+  const base = path.split("/").pop() ?? path;
+  if (path.endsWith(".json")) {
+    const parsed = parseJson(raw) as JsonObject;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`managed: parsed value at '${path}' is not a JSON object`);
+    }
+    withManagedBody(parsed, body, { triggerContext: tctx });
+    // package.json stays fully expanded; other .json (tsconfig, …) collapses
+    // to oxfmt's generic-file shape.
+    return stringifyJson(parsed, { collapse: base !== "package.json" });
+  }
+  if (path.endsWith(".yaml") || path.endsWith(".yml")) {
+    const doc = parseYaml(raw);
+    withManagedYaml(doc, body, { triggerContext: tctx, getLatestVersion: registryLookup });
+    return stringifyYaml(doc);
+  }
+  if (base === ".gitignore" || base.endsWith(".gitignore")) {
+    const lines = parseLines(raw);
+    withManagedLines(lines, body, { triggerContext: tctx });
+    return serializeLines(lines);
+  }
+  throw new Error(
+    `managed('${path}'): unsupported file kind. Only .json, .yaml, .yml, .gitignore are dispatched.`,
+  );
+}
+
+function buildSnapshot(fs: FileSystem): Set<string> {
+  const files = fs.list("");
+  const out = new Set<string>();
+  for (const f of files) {
+    out.add(f);
+    const parts = f.split("/");
+    for (let i = 1; i < parts.length; i++) {
+      out.add(parts.slice(0, i).join("/"));
+    }
+  }
+  return out;
+}
+
+function snapshotHas(snap: Set<string>, p: string): boolean {
+  const n = p === "" ? p : p.endsWith("/") ? p.slice(0, -1) : p;
+  return snap.has(n);
+}
+
+/** Build the trigger context for one leaf. `pathExists`/`pathMissing` are
+ *  block-relative; `filesMatch` resolves its glob MODULE-RELATIVE to
+ *  `modulePath` so the same predicate (`whenFilesExist("src/*.test.ts")`)
+ *  reads the right module when a scope fans out. The snapshot is shared
+ *  across leaves; only the resolution prefix differs per item. */
+function buildTriggerCtx(snap: Set<string>, ctx: RunContext, modulePath: string): TriggerContext {
+  return {
+    ctx,
+    version: ctx.version,
+    pathExists: (p: string) => snapshotHas(snap, p),
+    pathMissing: (p: string) => !snapshotHas(snap, p),
+    filesMatch: (glob: string) => {
+      const resolved = modulePath ? `${modulePath}/${glob}` : glob;
+      for (const entry of snap) {
+        if (matchesGlob(resolved, entry)) return true;
+      }
+      return false;
+    },
+  };
+}
+
+function passesTriggers(item: FlatItem, tctx: TriggerContext): boolean {
+  for (const t of item.triggers) {
+    if (!t(tctx)) return false;
+  }
+  return true;
+}
+
+/** Derive the active run mode from the context + init flag. `check`
+ *  (dryRun) and `refresh` share `"default"` — same leaves, the `dryRun`
+ *  flag alone decides whether writes land. */
+function currentMode(ctx: RunContext, initMode: boolean): RunMode {
+  if (initMode) return "init";
+  if (ctx.updateDepsOnly) return "updateDeps";
+  return "default";
+}
+
+function filterByMode(items: FlatItem[], mode: RunMode): FlatItem[] {
+  return items.filter((i) => i.modes.includes(mode));
+}
+
+function applyStructural(
+  item: FlatItem,
+  fs: FileSystem,
+  dryRun: boolean,
+  templates: TemplateProvider | undefined,
+  initMode: boolean,
+  isSdkInternal: boolean,
+): Change | undefined {
+  const leaf = item.leaf;
+  if (leaf.kind === "fixed") {
+    const desired = resolveContent(leaf.content, item.resolvedPath, templates, isSdkInternal);
+    const exists = fs.exists(item.resolvedPath);
+    if (!exists) {
+      if (!dryRun) fs.write(item.resolvedPath, desired);
+      return {
+        scope: item.scope,
+        path: item.resolvedPath,
+        primitive: "fixed",
+        action: "create",
+      };
+    }
+    const current = fs.read(item.resolvedPath);
+    if (current === desired) return undefined;
+    if (!dryRun) fs.write(item.resolvedPath, desired);
+    return {
+      scope: item.scope,
+      path: item.resolvedPath,
+      primitive: "fixed",
+      action: "update",
+    };
+  }
+  if (leaf.kind === "scaffold") {
+    if (fs.exists(item.resolvedPath)) return undefined;
+    if (!dryRun) {
+      writeLeafContent(fs, item.resolvedPath, leaf.initial, templates, isSdkInternal);
+    }
+    return {
+      scope: item.scope,
+      path: item.resolvedPath,
+      primitive: "scaffold",
+      action: "create",
+    };
+  }
+  if (leaf.kind === "seed") {
+    // Init mode: write seeds once if missing (same shape as scaffold).
+    // Refresh / check: seeds are off-limits to the engine — they belong
+    // to the block author. Layer-2 init→check parity relies on the
+    // init action depositing canonical seed content, then the check
+    // pass simply skipping seeds (vacuously fine).
+    if (!initMode) return undefined;
+    if (fs.exists(item.resolvedPath)) return undefined;
+    if (!dryRun) {
+      writeLeafContent(fs, item.resolvedPath, leaf.initial, templates, isSdkInternal);
+    }
+    return {
+      scope: item.scope,
+      path: item.resolvedPath,
+      primitive: "seed",
+      action: "create",
+    };
+  }
+  if (leaf.kind === "remove") {
+    if (!fs.exists(item.resolvedPath)) return undefined;
+    if (!dryRun) fs.delete(item.resolvedPath);
+    return {
+      scope: item.scope,
+      path: item.resolvedPath,
+      primitive: "remove",
+      action: "delete",
+    };
+  }
+  if (leaf.kind === "rename") {
+    if (!fs.exists(item.resolvedPath)) return undefined;
+    const to = item.resolvedTo!;
+    if (fs.exists(to)) {
+      // dest exists — treat as already-renamed; no change.
+      return undefined;
+    }
+    if (!dryRun) fs.move(item.resolvedPath, to);
+    return {
+      scope: item.scope,
+      path: item.resolvedPath,
+      primitive: "rename",
+      action: "rename",
+    };
+  }
+  return undefined;
+}
+
+function applyManaged(
+  item: FlatItem,
+  fs: FileSystem,
+  dryRun: boolean,
+  tctx: TriggerContext,
+  templates: TemplateProvider | undefined,
+  registryLookup: ((packageName: string) => string | undefined) | undefined,
+  isSdkInternal: boolean,
+): Change | undefined {
+  if (item.leaf.kind !== "managed") return undefined;
+  const leaf = item.leaf;
+  const path = item.resolvedPath;
+  const exists = fs.exists(path);
+
+  let beforeRaw: string;
+  let created = false;
+
+  if (!exists) {
+    beforeRaw = resolveContent(leaf.initial, path, templates, isSdkInternal);
+    created = true;
+  } else {
+    beforeRaw = fs.read(path);
+  }
+
+  const after = runManagedBody(path, beforeRaw, leaf.body, tctx, registryLookup);
+
+  if (created) {
+    if (!dryRun) fs.write(path, after);
+    return {
+      scope: item.scope,
+      path,
+      primitive: "managed",
+      action: "create",
+    };
+  }
+  if (after === beforeRaw) return undefined;
+  if (!dryRun) fs.write(path, after);
+  return {
+    scope: item.scope,
+    path,
+    primitive: "managed",
+    action: "update",
+  };
+}
+
+/** Execute one pass over the flattened items: structural items first
+ *  (declaration order), then managed items. Returns the change list. */
+function executePass(
+  flat: FlatItem[],
+  fs: FileSystem,
+  ctx: RunContext,
+  dryRun: boolean,
+  templates: TemplateProvider | undefined,
+  initMode: boolean,
+  registryLookup: ((packageName: string) => string | undefined) | undefined,
+): Change[] {
+  const items = filterByMode(flat, currentMode(ctx, initMode));
+  const changes: Change[] = [];
+
+  // Structural pass. The trigger context is per-item: `filesMatch` resolves
+  // module-relative, so it must carry the leaf's bound module path.
+  const snap1 = buildSnapshot(fs);
+  for (const item of items) {
+    if (item.leaf.kind === "managed") continue;
+    const tctx1 = buildTriggerCtx(snap1, ctx, item.modulePath);
+    if (!passesTriggers(item, tctx1)) continue;
+    const change = applyStructural(item, fs, dryRun, templates, initMode, ctx.isSdkInternal);
+    if (change) changes.push(change);
+  }
+
+  // Re-snapshot after structural pass — managed-body triggers see the
+  // post-rename / post-delete world.
+  const snap2 = buildSnapshot(fs);
+  for (const item of items) {
+    if (item.leaf.kind !== "managed") continue;
+    const tctx2 = buildTriggerCtx(snap2, ctx, item.modulePath);
+    if (!passesTriggers(item, tctx2)) continue;
+    const change = applyManaged(
+      item,
+      fs,
+      dryRun,
+      tctx2,
+      templates,
+      registryLookup,
+      ctx.isSdkInternal,
+    );
+    if (change) changes.push(change);
+  }
+
+  return changes;
+}
+
+/**
+ * Run the structurer engine end-to-end. See module header for mode
+ * semantics. Throws `RecheckError` if the post-run dry-run finds any
+ * leftover diff after a successful refresh.
+ */
+export function run(
+  structure: Structure,
+  fs: FileSystem,
+  ctx: RunContext,
+  opts: RunOptions = {},
+): RunResult {
+  return withRunContext(ctx, () => {
+    const flat = flatten(structure, ctx);
+    const initMode = !!opts.initMode;
+    const changes = executePass(
+      flat,
+      fs,
+      ctx,
+      ctx.dryRun,
+      opts.templates,
+      initMode,
+      opts.registryLookup,
+    );
+
+    const isRefreshDefault = !ctx.dryRun && !ctx.updateDepsOnly && !initMode;
+
+    if (isRefreshDefault) {
+      // version bump
+      writeStructureVersion(fs);
+
+      // post-run recheck. Fresh discovery → fresh flatten →
+      // dry-run. Any change list emits RecheckError on the first item.
+      const recheckCtxBase = opts.rediscover ? opts.rediscover(fs) : ctx;
+      const recheckCtx: RunContext = { ...recheckCtxBase, dryRun: true };
+      const recheckFlat = flatten(structure, recheckCtx);
+      const recheckChanges = executePass(
+        recheckFlat,
+        fs,
+        recheckCtx,
+        true,
+        opts.templates,
+        false,
+        opts.registryLookup,
+      );
+      // Ignore .structure self-write (already up to date after
+      // writeStructureVersion above).
+      const filtered = recheckChanges.filter((c) => c.path !== STRUCTURE_META_FILE);
+      if (filtered.length > 0) {
+        throw new RecheckError(filtered[0]!);
+      }
+    }
+
+    // Init mode: write .structure so the resulting tree carries the
+    // current version (matches what `init` ships to disk).
+    if (initMode && !ctx.dryRun) {
+      writeStructureVersion(fs);
+    }
+
+    return { changes };
+  });
+}

package/src/structure/engine/templates.ts

@@ -0,0 +1,74 @@
+// Template-content provider for the runner.
+//
+// `file(path)` and `tpl(path, vars)` content forms resolve through this
+// provider. Static templates live at `<root>/static/`; templated text
+// lives at `<root>/text/`. The runner accepts a TemplateProvider via
+// `RunOptions.templates`; the production CLI wires a NodeTemplateProvider
+// rooted at the bundled `templates/` directory, and tests can use
+// `MemoryTemplateProvider` or point at the on-disk templates directory
+// during the Layer-2 zero-diff invariant.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export interface TemplateProvider {
+  /** Read a static template file (under `<root>/static/`). */
+  staticRead(p: string): string;
+  /** Read a static template file as raw bytes (under `<root>/static/`).
+   *  For binary assets (logos, images) that must not be utf-8 decoded. */
+  staticReadBinary(p: string): Uint8Array;
+  /** Read a text template file (under `<root>/text/`). */
+  textRead(p: string): string;
+}
+
+/** Provider backed by an on-disk template tree. Reads are synchronous
+ *  so the runner can stay sync inside content-form resolution. */
+export class NodeTemplateProvider implements TemplateProvider {
+  constructor(private root: string) {}
+
+  staticRead(p: string): string {
+    return fs.readFileSync(path.resolve(this.root, "static", p), "utf-8");
+  }
+
+  staticReadBinary(p: string): Uint8Array {
+    return fs.readFileSync(path.resolve(this.root, "static", p));
+  }
+
+  textRead(p: string): string {
+    return fs.readFileSync(path.resolve(this.root, "text", p), "utf-8");
+  }
+}
+
+/** In-memory provider for tests. Keyed by the same `static/...` /
+ *  `text/...` shape as on disk. */
+export class MemoryTemplateProvider implements TemplateProvider {
+  constructor(private files: Record<string, string>) {}
+
+  staticRead(p: string): string {
+    const k = `static/${p}`;
+    const v = this.files[k];
+    if (v === undefined) throw new Error(`MemoryTemplateProvider: missing '${k}'`);
+    return v;
+  }
+
+  staticReadBinary(p: string): Uint8Array {
+    // In-memory templates are stored as strings; expose their bytes. Real
+    // binary assets are exercised through NodeTemplateProvider on disk.
+    return new TextEncoder().encode(this.staticRead(p));
+  }
+
+  textRead(p: string): string {
+    const k = `text/${p}`;
+    const v = this.files[k];
+    if (v === undefined) throw new Error(`MemoryTemplateProvider: missing '${k}'`);
+    return v;
+  }
+}
+
+/** Shell-style `${name}` substitution. Unknown names left as-is so
+ *  template authors notice. Backslash escape is not supported. */
+export function substituteVars(text: string, vars: Record<string, string>): string {
+  return text.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name: string) => {
+    return vars[name] ?? `\${${name}}`;
+  });
+}

package/src/structure/engine/testing.ts

@@ -0,0 +1,93 @@
+// Test helpers for the engine.
+//
+// `runRulesAgainst`: unit helper — install `input` as the active
+// managed-body object, invoke the body lambda, return the mutated object.
+//
+// `simulateInit`: produce an in-memory FS populated as if `block-tools
+// structure init` had just run for the given BlockVars, then RE-DISCOVER
+// the module set from that written FS (the same DISCOVERY the real `check`
+// runs) rather than reusing init's module set. The returned `ctx` is the
+// rediscovered one — running `engine.run(STRUCTURE, fs, {...ctx, dryRun:
+// true})` against the same fs and asserting no changes is then a genuine
+// init→check round-trip: a discovery / classification regression surfaces
+// instead of being masked.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { BlockVars, Module, RunContext, Structure } from "./api";
+import type { JsonObject } from "./content-rules";
+import { withManagedBody } from "./content-rules";
+import { MemoryFileSystem } from "./fs/memory";
+import { createRunContext, modulesForInit } from "./ctx";
+import { NodeTemplateProvider, type TemplateProvider } from "./templates";
+import { run as engineRun } from "./runner";
+import { discoverRunContext } from "./discovery-fs";
+import { STRUCTURE_VERSION } from "./version";
+import { STRUCTURE } from "../structure-definition";
+
+/** Layer-1 helper. */
+export function runRulesAgainst(input: JsonObject, body: () => void): JsonObject {
+  return withManagedBody(input, body);
+}
+
+export type SimulateInitInput = {
+  vars: BlockVars;
+  /** Override the discovered module set. Defaults to `defaultModulesFor`. */
+  modules?: Module[];
+  /** Override the structure under test (defaults to the canonical one). */
+  structure?: Structure;
+  /** Override the template provider (defaults to NodeTemplateProvider
+   *  pointing at the bundled `templates/` directory). */
+  templates?: TemplateProvider;
+  /** SDK-internal flag. Default `false` (standalone block). */
+  isSdkInternal?: boolean;
+  /** Sync npm-latest lookup for the `onInitOrUpdate` catalog resolution.
+   *  Absent → the SDK catalog keeps its seed versions (no bump), matching
+   *  an offline scaffold; tests that assert init writes latest pass a mock. */
+  registryLookup?: (packageName: string) => string | undefined;
+};
+
+export type SimulatedInit = {
+  fs: MemoryFileSystem;
+  ctx: RunContext;
+};
+
+/** Module set produced by `init` for a given BlockVars. Delegates to the
+ *  shared `modulesForInit` so the test helper and the real `init`
+ *  constructor never drift. */
+export function defaultModulesFor(vars: BlockVars): Module[] {
+  return modulesForInit(vars);
+}
+
+/** Default template provider — reads from the bundled templates tree
+ *  next to this file. */
+export function defaultTemplateProvider(): TemplateProvider {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  // engine/testing.ts → ../templates
+  const root = path.resolve(here, "..", "templates");
+  return new NodeTemplateProvider(root);
+}
+
+export function simulateInit(input: SimulateInitInput): SimulatedInit {
+  const fs = new MemoryFileSystem();
+  const isSdkInternal = input.isSdkInternal ?? false;
+  const modules = input.modules ?? defaultModulesFor(input.vars);
+  const initCtx = createRunContext({
+    blockVars: input.vars,
+    modules,
+    isSdkInternal,
+    version: STRUCTURE_VERSION,
+  });
+  const structure = input.structure ?? STRUCTURE;
+  const templates = input.templates ?? defaultTemplateProvider();
+  engineRun(structure, fs, initCtx, {
+    templates,
+    initMode: true,
+    registryLookup: input.registryLookup,
+  });
+
+  // Re-discover from the written FS — the returned ctx is what `check`
+  // would build, not what `init` assembled.
+  const ctx = discoverRunContext({ fs, isSdkInternal });
+  return { fs, ctx };
+}