stackloom-cli 1.0.0

package/src/core/template-loader.js

@@ -0,0 +1,163 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import ejs from 'ejs';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const HOME = os.homedir();
+
+/**
+ * TemplateLoader — resolves and renders templates from 3 locations:
+ *   1. ./<project>/.loom/templates/<template-path>   (project-specific — highest priority)
+ *   2. ~/.loom/templates/<template-path>             (user-global overrides)
+ *   3. built-in/packages/cli/src/templates/         (shipped defaults)
+ */
+export class TemplateLoader {
+  constructor() {
+    this.cache = new Map(); // cacheKey → { compiled, mtime }
+    this.projectRoot = process.cwd(); // default, can be overridden per call
+  }
+
+  /**
+   * Resolve template file path from template identifier
+   * @param {string} templatePath - e.g., 'resource/model.js.ejs'
+   * @param {string} projectRoot - root of the Stackloom project
+   * @returns {string} absolute path to template file
+   */
+  resolve(templatePath, projectRoot = this.projectRoot) {
+    const locations = [
+      path.join(projectRoot, '.loom', 'templates', templatePath),
+      path.join(HOME, '.loom', 'templates', templatePath),
+      path.join(__dirname, '..', '..', 'src', 'templates', templatePath),
+    ];
+
+    for (const loc of locations) {
+      if (fs.existsSync(loc)) {
+        return loc;
+      }
+    }
+
+    // Not found anywhere — helpful error
+    const relativePath = templatePath;
+    throw new Error(
+      `Template not found: ${relativePath}\n` +
+      `Searched in:\n` +
+      locations.map(l => `  ${l}`).join('\n') + '\n' +
+      `Run 'loom template list' to see available templates.`
+    );
+  }
+
+  /**
+   * Render a template with given context
+   * @param {string} templatePath - template identifier
+   * @param {object} context - variables available in template
+   * @param {string} projectRoot - Stackloom project root
+   * @returns {string} rendered content
+   */
+  async render(templatePath, context = {}, projectRoot = this.projectRoot) {
+    const fullPath = this.resolve(templatePath, projectRoot);
+    
+    // Build cache key: file path + resource name (so cache invalidation is per-resource)
+    const cacheKey = `${fullPath}:${context.resource?.name || 'global'}`;
+    
+    // Check cache
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      const currentMtime = (await fs.stat(fullPath)).mtimeMs;
+      if (currentMtime === cached.mtime) {
+        return cached.compiled(context);
+      }
+    }
+
+    const source = await fs.readFile(fullPath, 'utf-8');
+    
+    // Compile with EJS.
+    // rmWhitespace MUST stay false — it strips every line's leading whitespace,
+    // flattening generated code to column 0. Templates instead control output
+    // whitespace explicitly with the `-%>` slurp tag.
+    const compiled = ejs.compile(source, {
+      filename: fullPath,
+      cache: false, // we manage our own cache
+      rmWhitespace: false,
+    });
+
+    // Verify compilation works
+    try {
+      const result = compiled(context);
+      
+      // Cache it
+      const mtime = (await fs.stat(fullPath)).mtimeMs;
+      this.cache.set(cacheKey, { compiled, mtime, path: fullPath });
+      
+      return result;
+    } catch (err) {
+      const lineInfo = this.getErrorLine(err, source);
+      throw new Error(
+        `Template render error in ${templatePath}${lineInfo ? ` (line ${lineInfo})` : ''}:\n` +
+        `${err.message}\n` +
+        `Available context keys: ${Object.keys(context).join(', ')}`
+      );
+    }
+  }
+
+  getErrorLine(err, source) {
+    const match = err.stack?.match(/\((\d+):(\d+)\)$/);
+    if (match) return match[1];
+    return null;
+  }
+
+  /**
+   * List all built-in templates
+   * @returns {Array<{relativePath: string, fullPath: string, size: number}>}
+   */
+  async listBuiltIn() {
+    const builtInDir = path.join(__dirname, '..', '..', 'src', 'templates');
+    return this.listTemplatesRecursive(builtInDir, '');
+  }
+
+  listTemplatesRecursive(dir, prefix) {
+    const entries = [];
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+    
+    for (const item of items) {
+      const relPath = prefix ? `${prefix}/${item.name}` : item.name;
+      const fullPath = path.join(dir, item.name);
+      
+      if (item.isDirectory()) {
+        entries.push(...this.listTemplatesRecursive(fullPath, relPath));
+      } else if (item.isFile() && (item.name.endsWith('.ejs') || item.name.endsWith('.js') || item.name.endsWith('.jsx'))) {
+        const stat = fs.statSync(fullPath);
+        entries.push({
+          relativePath: relPath.replace(/\.ejs$/, ''), // strip .ejs for display
+          fullPath,
+          size: stat.size,
+        });
+      }
+    }
+    
+    return entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  }
+
+  /**
+   * Clear cache (useful for tests or after template edits)
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+}
+
+/**
+ * Helper functions available in all templates
+ */
+export const templateHelpers = {
+  pascal: (s) => s.charAt(0).toUpperCase() + s.slice(1),
+  camel: (s) => s.charAt(0).toLowerCase() + s.slice(1),
+  snake: (s) => s.replace(/[A-Z]/g, m => '_' + m.toLowerCase()),
+  kebab: (s) => s.replace(/[A-Z]/g, m => '-' + m.toLowerCase()),
+  quote: (str) => JSON.stringify(str),
+  indent: (str, n = 2) => str.split('\n').map(l => ' '.repeat(n) + l).join('\n'),
+  pluralize: (word) => word + 's', // simplistic
+};

package/src/engine/__tests__/engine.test.js

@@ -0,0 +1,306 @@
+import { describe, it, expect } from "vitest";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  FileTransaction,
+  Validator,
+  scanDelimiters,
+  Injector,
+  InjectionError,
+  Pipeline,
+  defineStep,
+  createGenerationPipeline,
+} from "../index.js";
+import { blueprintLoader } from "../../blueprint/index.js";
+import { recipeLoader } from "../../recipes/index.js";
+
+const tmp = (label) =>
+  path.join(os.tmpdir(), `${label}-${Math.random().toString(36).slice(2)}`);
+
+/** A minimal project carrying the four MERN anchor files. */
+function scaffold(root) {
+  const write = (rel, content) => {
+    const abs = path.join(root, rel);
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  };
+  write("backend/package.json", "{}");
+  write(
+    "backend/src/routes/index.js",
+    'const router = require("express").Router();\nrouter.use("/auth", authRoutes);\nmodule.exports = router;\n',
+  );
+  write("frontend/src/main.jsx", "");
+  write(
+    "frontend/src/routes/AppRouter.jsx",
+    'import { lazy } from "react";\n' +
+      'const LoginPage = lazy(() => import("@/pages/auth/LoginPage"));\n' +
+      "export function AppRouter() {\n  return (\n    <Routes>\n" +
+      '      <Route path="*" element={<NotFound />} />\n' +
+      "    </Routes>\n  );\n}\n",
+  );
+  write(
+    "frontend/src/config/app-preset.js",
+    'export const preset = {\n  navigation: [\n    { label: "Dashboard", href: "/dashboard" },\n  ],\n};\n',
+  );
+  return root;
+}
+
+/** Fake renderer: sensible, balanced output keyed by template path. */
+const fakeRenderer = (templatePath) => {
+  if (templatePath === "snippets/route-mount.ejs") return 'router.use("/order", r);\n';
+  if (templatePath === "snippets/lazy-import.ejs") return "const OrderList = lazy(() => 0);\n";
+  if (templatePath === "snippets/route-entry.ejs") return '<Route path="/admin/order" />\n';
+  if (templatePath === "snippets/nav-entry.ejs") return '{ label: "Order" },\n';
+  return `// ${templatePath}\nmodule.exports = {};\n`;
+};
+
+describe("scanDelimiters", () => {
+  it("accepts balanced code, strings, regex, template literals and JSX", () => {
+    expect(scanDelimiters("function f() { return [1, 2]; }").balanced).toBe(true);
+    expect(scanDelimiters("const s = '})]'; const o = {};").balanced).toBe(true);
+    expect(scanDelimiters("const re = /[(]/; f();").balanced).toBe(true);
+    expect(scanDelimiters("const t = `a ${b} c`; g();").balanced).toBe(true);
+    expect(scanDelimiters("return (<div><Routes></Routes></div>);").balanced).toBe(true);
+  });
+
+  it("rejects unbalanced delimiters and unterminated literals", () => {
+    expect(scanDelimiters("function broken( {").balanced).toBe(false);
+    expect(scanDelimiters("return 1; }").balanced).toBe(false);
+    expect(scanDelimiters("const s = 'unterminated").balanced).toBe(false);
+  });
+});
+
+describe("Validator", () => {
+  it("gates code and JSON, lets unknown file types pass", () => {
+    const v = new Validator();
+    expect(v.validateFile({ relPath: "a.js", content: "module.exports = {};" }).ok).toBe(true);
+    expect(v.validateFile({ relPath: "a.js", content: "module.exports = {" }).ok).toBe(false);
+    expect(v.validateFile({ relPath: "a.js", content: "   " }).ok).toBe(false);
+    expect(v.validateFile({ relPath: "a.json", content: '{"x":1}' }).ok).toBe(true);
+    expect(v.validateFile({ relPath: "a.json", content: "{bad}" }).ok).toBe(false);
+    expect(v.validateFile({ relPath: "readme.md", content: "# unbalanced ]" }).ok).toBe(true);
+  });
+
+  it("validateAll reports every failing file", () => {
+    const result = new Validator().validateAll([
+      { relPath: "ok.js", content: "f();" },
+      { relPath: "bad.jsx", content: "<div>{" },
+    ]);
+    expect(result.ok).toBe(false);
+    expect(result.failures.map((f) => f.relPath)).toEqual(["bad.jsx"]);
+  });
+});
+
+describe("FileTransaction", () => {
+  it("stages without writing, then commits atomically", () => {
+    const root = tmp("tx");
+    mkdirSync(root, { recursive: true });
+    const tx = new FileTransaction({ projectRoot: root });
+    tx.stage("src/a.js", "// a\n").stage("src/nested/b.js", "// b\n");
+    expect(existsSync(path.join(root, "src/a.js"))).toBe(false);
+    expect(tx.commit()).toHaveLength(2);
+    expect(readFileSync(path.join(root, "src/a.js"), "utf-8")).toBe("// a\n");
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("upserts: re-staging a path replaces it", () => {
+    const tx = new FileTransaction({ projectRoot: tmp("tx-upsert") });
+    tx.stage("a.js", "first").stage("a.js", "second");
+    expect(tx.get("a.js")).toBe("second");
+    expect(tx.staged()).toHaveLength(1);
+  });
+
+  it("rolls back fully when a write fails mid-commit", () => {
+    const root = tmp("tx-rollback");
+    mkdirSync(root, { recursive: true });
+    writeFileSync(path.join(root, "existing.js"), "ORIGINAL");
+
+    let writes = 0;
+    const fs = {
+      existsSync,
+      readFileSync,
+      mkdirSync,
+      rmSync,
+      writeFileSync(file, data) {
+        if (++writes === 2) throw new Error("disk full (simulated)");
+        writeFileSync(file, data);
+      },
+    };
+    const tx = new FileTransaction({ projectRoot: root, fs });
+    tx.stage("existing.js", "MODIFIED").stage("fresh.js", "NEW");
+    expect(() => tx.commit()).toThrow(/disk full/);
+    expect(readFileSync(path.join(root, "existing.js"), "utf-8")).toBe("ORIGINAL");
+    expect(existsSync(path.join(root, "fresh.js"))).toBe(false);
+    rmSync(root, { recursive: true, force: true });
+  });
+});
+
+describe("Injector", () => {
+  it("splices each strategy at its anchor", async () => {
+    const root = scaffold(tmp("inj"));
+    const blueprint = await blueprintLoader.load(root);
+    const injector = new Injector();
+    const tx = new FileTransaction({ projectRoot: root });
+    const run = (anchorName, snippet) =>
+      injector.inject({ anchorName, snippet, blueprint, projectRoot: root, transaction: tx });
+
+    run("backend.routes", 'router.use("/order", orderRoutes);');
+    run("frontend.lazyImports", 'const OrderList = lazy(() => import("@/pages/admin/order/ListPage"));');
+    run("frontend.routes", '<Route path="/admin/order" element={<OrderList />} />');
+    run("frontend.nav", '{ label: "Order", href: "/admin/order" },');
+
+    const routes = tx.get("backend/src/routes/index.js");
+    expect(routes.indexOf('router.use("/order"')).toBeLessThan(routes.indexOf("module.exports = router;"));
+
+    const router = tx.get("frontend/src/routes/AppRouter.jsx");
+    expect(router).toContain("const OrderList = lazy(");
+    expect(router.indexOf("/admin/order")).toBeLessThan(router.indexOf('path="*"'));
+
+    expect(tx.get("frontend/src/config/app-preset.js")).toContain(
+      '{ label: "Order", href: "/admin/order" },',
+    );
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("is idempotent — re-injecting the same snippet is a no-op", async () => {
+    const root = scaffold(tmp("inj-idem"));
+    const blueprint = await blueprintLoader.load(root);
+    const injector = new Injector();
+    const tx = new FileTransaction({ projectRoot: root });
+    const args = {
+      anchorName: "backend.routes",
+      snippet: 'router.use("/order", orderRoutes);',
+      blueprint,
+      projectRoot: root,
+      transaction: tx,
+    };
+    expect(injector.inject(args).action).toBe("inject");
+    const second = injector.inject(args);
+    expect(second.action).toBe("skip");
+    expect(second.reason).toBe("already-present");
+    const count = tx.get("backend/src/routes/index.js").split('router.use("/order"').length - 1;
+    expect(count).toBe(1);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("throws InjectionError when the anchor file is missing", async () => {
+    const root = tmp("inj-missing");
+    mkdirSync(root, { recursive: true });
+    const blueprint = await blueprintLoader.load(root);
+    expect(() =>
+      new Injector().inject({
+        anchorName: "backend.routes",
+        snippet: "x",
+        blueprint,
+        projectRoot: root,
+        transaction: new FileTransaction({ projectRoot: root }),
+      }),
+    ).toThrow(InjectionError);
+    rmSync(root, { recursive: true, force: true });
+  });
+});
+
+describe("Pipeline", () => {
+  it("runs steps in order, threading the context", async () => {
+    const trail = [];
+    const out = await new Pipeline([
+      defineStep("one", (ctx) => {
+        trail.push("one");
+        ctx.a = 1;
+      }),
+      defineStep("two", (ctx) => {
+        trail.push("two");
+        ctx.b = ctx.a + 1;
+      }),
+    ]).run({});
+    expect(trail).toEqual(["one", "two"]);
+    expect(out.b).toBe(2);
+  });
+});
+
+describe("createGenerationPipeline", () => {
+  const setup = async (root) => {
+    scaffold(root);
+    return {
+      blueprint: await blueprintLoader.load(root),
+      recipe: await recipeLoader.load("resource"),
+    };
+  };
+  const invoke = (root, blueprint, recipe, extra = {}) => ({
+    projectRoot: root,
+    recipe,
+    blueprint,
+    recipeContext: { withFrontend: true },
+    vars: { kebab: "order", Name: "Order" },
+    templateContext: {},
+    ...extra,
+  });
+
+  it("plan → render → inject → validate → commit writes files and anchors", async () => {
+    const root = tmp("gen-ok");
+    const { blueprint, recipe } = await setup(root);
+    const ctx = await createGenerationPipeline({ renderer: fakeRenderer }).run(
+      invoke(root, blueprint, recipe),
+    );
+    // 12 generated files (full-stack, no tests, no TS) + 3 modified anchor files.
+    expect(ctx.result.files.length).toBe(15);
+    expect(ctx.injections.filter((i) => i.action === "inject")).toHaveLength(4);
+    expect(existsSync(path.join(root, "backend/src/modules/order/models/Order.js"))).toBe(true);
+    expect(readFileSync(path.join(root, "backend/src/routes/index.js"), "utf-8")).toContain(
+      'router.use("/order"',
+    );
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("commits nothing when any file fails validation", async () => {
+    const root = tmp("gen-bad");
+    const { blueprint, recipe } = await setup(root);
+    const pipeline = createGenerationPipeline({ renderer: () => "function broken( {\n" });
+    await expect(pipeline.run(invoke(root, blueprint, recipe))).rejects.toThrow(/failed validation/);
+    expect(existsSync(path.join(root, "backend/src/modules/order/models/Order.js"))).toBe(false);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("a bad inject snippet aborts the whole commit, leaving anchor files untouched", async () => {
+    const root = tmp("gen-inj-bad");
+    const { blueprint, recipe } = await setup(root);
+    const renderer = (t) =>
+      t === "snippets/nav-entry.ejs" ? "{ label: broken (\n" : "module.exports = {};\n";
+    await expect(
+      createGenerationPipeline({ renderer }).run(invoke(root, blueprint, recipe)),
+    ).rejects.toThrow(/failed validation/);
+    expect(readFileSync(path.join(root, "frontend/src/config/app-preset.js"), "utf-8")).not.toContain(
+      "broken",
+    );
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("dry-run reports the plan without writing", async () => {
+    const root = tmp("gen-dry");
+    const { blueprint, recipe } = await setup(root);
+    const ctx = await createGenerationPipeline({ renderer: fakeRenderer }).run(
+      invoke(root, blueprint, recipe, { dryRun: true }),
+    );
+    expect(ctx.result.dryRun).toBe(true);
+    expect(existsSync(path.join(root, "backend/src/modules/order/models/Order.js"))).toBe(false);
+    expect(readFileSync(path.join(root, "backend/src/routes/index.js"), "utf-8")).not.toContain(
+      "/order",
+    );
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("withInject: false runs render → validate → commit only", async () => {
+    const root = tmp("gen-noinject");
+    const { blueprint, recipe } = await setup(root);
+    const ctx = await createGenerationPipeline({ renderer: fakeRenderer, withInject: false }).run(
+      invoke(root, blueprint, recipe, { recipeContext: { withFrontend: false } }),
+    );
+    expect(ctx.result.files).toHaveLength(5);
+    expect(ctx.injections).toBeUndefined();
+    expect(readFileSync(path.join(root, "backend/src/routes/index.js"), "utf-8")).not.toContain(
+      "/order",
+    );
+    rmSync(root, { recursive: true, force: true });
+  });
+});

package/src/engine/index.js

@@ -0,0 +1,21 @@
+/**
+ * Engine — the transactional generation core.
+ *
+ * Composable, injectable, all-or-nothing: a recipe is planned, every file is
+ * rendered and validated in a staging transaction, and only a fully-valid set
+ * is committed atomically. Nothing here knows about a specific architecture or
+ * template library — those arrive as a Blueprint and an injected renderer.
+ */
+export { FileTransaction, realFs } from "./transaction.js";
+export { Validator, scanDelimiters } from "./validator.js";
+export { Injector, InjectionError } from "./injector.js";
+export {
+  Pipeline,
+  defineStep,
+  planStep,
+  commitStep,
+  createRenderStep,
+  createInjectStep,
+  createValidateStep,
+  createGenerationPipeline,
+} from "./pipeline.js";

package/src/engine/injector.js

@@ -0,0 +1,198 @@
+/**
+ * Injector — splices generated snippets into existing project files at the
+ * injection points a blueprint declares.
+ *
+ * Replaces the scattered, fragile regex string-replacement in the old
+ * generator. Properties:
+ *   - blueprint-driven   — anchors (file + strategy + pattern) come from the
+ *     architecture contract, not hardcoded here
+ *   - idempotent         — re-running an injection that is already present is a
+ *     no-op, so generators are safe to re-run
+ *   - transaction-aware  — modified files are staged into the same
+ *     FileTransaction as generated files, so the whole change set is atomic and
+ *     successive injections into one file compose correctly
+ *   - loud on failure    — a missing anchor file or unfound pattern throws an
+ *     InjectionError rather than silently skipping
+ */
+import path from "node:path";
+import { realFs } from "./transaction.js";
+
+export class InjectionError extends Error {
+  constructor(message, { anchor, file } = {}) {
+    super(message);
+    this.name = "InjectionError";
+    this.anchor = anchor;
+    this.file = file;
+  }
+}
+
+/** Leading whitespace of the line containing `idx`. */
+function lineIndentAt(content, idx) {
+  const lineStart = content.lastIndexOf("\n", idx) + 1;
+  return (content.slice(lineStart).match(/^[ \t]*/) || [""])[0];
+}
+
+/** Indent every non-blank line of `block` by `indent`. */
+function indentBlock(block, indent) {
+  return block
+    .split("\n")
+    .map((line) => (line.trim() ? indent + line : line))
+    .join("\n");
+}
+
+/**
+ * Index of the delimiter that closes the one at `openIndex`, aware of strings,
+ * template literals and comments. Returns -1 if unbalanced.
+ */
+function findMatchingDelimiter(src, openIndex, openChar, closeChar) {
+  let depth = 0;
+  let i = openIndex;
+  const n = src.length;
+  while (i < n) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < n && src[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < n && !(src[i] === "*" && src[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") {
+      i++;
+      while (i < n && src[i] !== c) {
+        if (src[i] === "\\") i++;
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (c === openChar) depth++;
+    else if (c === closeChar) {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/** Apply one anchor's strategy, returning the updated file content. */
+function applyStrategy(anchor, anchorName, relFile, content, snippet) {
+  const fail = (msg) => {
+    throw new InjectionError(`${msg} (anchor "${anchorName}" → ${relFile})`, {
+      anchor: anchorName,
+      file: relFile,
+    });
+  };
+  const block = snippet.endsWith("\n") ? snippet : `${snippet}\n`;
+
+  switch (anchor.strategy) {
+    case "marker-comment": {
+      const idx = anchor.comment ? content.indexOf(anchor.comment) : -1;
+      if (idx === -1) fail(`anchor comment "${anchor.comment}" not found`);
+      const nl = content.indexOf("\n", idx);
+      const at = nl === -1 ? content.length : nl + 1;
+      return content.slice(0, at) + indentBlock(block, lineIndentAt(content, idx)) + content.slice(at);
+    }
+
+    case "before-line": {
+      const idx = content.indexOf(anchor.pattern);
+      if (idx === -1) fail(`pattern "${anchor.pattern}" not found`);
+      const lineStart = content.lastIndexOf("\n", idx) + 1;
+      return content.slice(0, lineStart) + indentBlock(block, lineIndentAt(content, idx)) + content.slice(lineStart);
+    }
+
+    case "before-match": {
+      const match = new RegExp(anchor.pattern, "m").exec(content);
+      if (!match) fail(`pattern /${anchor.pattern}/ not found`);
+      const lineStart = content.lastIndexOf("\n", match.index) + 1;
+      return (
+        content.slice(0, lineStart) +
+        indentBlock(block, lineIndentAt(content, match.index)) +
+        content.slice(lineStart)
+      );
+    }
+
+    case "after-last-match": {
+      const re = new RegExp(anchor.pattern, "gm");
+      let last = null;
+      let m;
+      while ((m = re.exec(content)) !== null) {
+        last = m;
+        if (m[0] === "") re.lastIndex++;
+      }
+      if (!last) fail(`pattern /${anchor.pattern}/ not found`);
+      const nl = content.indexOf("\n", last.index + last[0].length);
+      const at = nl === -1 ? content.length : nl + 1;
+      return content.slice(0, at) + indentBlock(block, lineIndentAt(content, last.index)) + content.slice(at);
+    }
+
+    case "array-append": {
+      const match = new RegExp(anchor.pattern, "m").exec(content);
+      if (!match) fail(`array pattern /${anchor.pattern}/ not found`);
+      const open = content.indexOf("[", match.index);
+      if (open === -1) fail(`no "[" found after array pattern`);
+      const close = findMatchingDelimiter(content, open, "[", "]");
+      if (close === -1) fail(`unbalanced "[" for array anchor`);
+
+      const inner = content.slice(open + 1, close).replace(/\s+$/, "");
+      const closeIndent = lineIndentAt(content, close);
+      const entryIndent = `${closeIndent}  `;
+      const needsComma = inner.length > 0 && !inner.endsWith(",");
+      const newInner = `${inner}${needsComma ? "," : ""}\n${entryIndent}${snippet.trim()}\n${closeIndent}`;
+      return content.slice(0, open + 1) + newInner + content.slice(close);
+    }
+
+    default:
+      return fail(`unknown injection strategy "${anchor.strategy}"`);
+  }
+}
+
+export class Injector {
+  /**
+   * @param {object} [options]
+   * @param {typeof realFs} [options.fs] - filesystem adapter (injectable for tests)
+   */
+  constructor({ fs = realFs } = {}) {
+    this.fs = fs;
+  }
+
+  /**
+   * Splice `snippet` into the file named by blueprint anchor `anchorName`,
+   * staging the modified file into `transaction`.
+   * @returns {{ anchor: string, file: string, action: "inject"|"skip", reason?: string }}
+   */
+  inject({ anchorName, snippet, blueprint, projectRoot, transaction }) {
+    const anchor = blueprint.getAnchor(anchorName); // throws if anchor undeclared
+    const relFile = blueprint.expand(anchor.file, projectRoot);
+    const absFile = path.join(projectRoot, relFile);
+
+    // Prefer the transaction's pending content so successive injections compose.
+    let content = transaction.get(relFile);
+    if (content === undefined) {
+      if (!this.fs.existsSync(absFile)) {
+        throw new InjectionError(
+          `Anchor "${anchorName}" targets ${relFile}, which does not exist in this project.`,
+          { anchor: anchorName, file: relFile },
+        );
+      }
+      content = this.fs.readFileSync(absFile, "utf-8");
+    }
+
+    const trimmed = snippet.trim();
+    if (!trimmed) {
+      return { anchor: anchorName, file: relFile, action: "skip", reason: "empty-snippet" };
+    }
+    if (content.includes(trimmed)) {
+      return { anchor: anchorName, file: relFile, action: "skip", reason: "already-present" };
+    }
+
+    transaction.stage(relFile, applyStrategy(anchor, anchorName, relFile, content, snippet));
+    return { anchor: anchorName, file: relFile, action: "inject" };
+  }
+}