@jskit-ai/jskit-cli 0.2.25 → 0.2.27

package/src/server/cliRuntime.js

@@ -28,9 +28,7 @@ import {
 import {
   BUNDLES_ROOT,
   CATALOG_PACKAGES_PATH,
-  CLI_PACKAGE_ROOT,
-  MODULES_ROOT,
-  WORKSPACE_ROOT
+  CLI_PACKAGE_ROOT
 } from "./pathResolution.js";
 import {
   appendTextSnippet,
@@ -55,13 +53,15 @@ const VITE_DEV_PROXY_CONFIG_RELATIVE_PATH = ".jskit/vite.dev.proxy.json";
 const VITE_DEV_PROXY_CONFIG_VERSION = 1;
 const PUBLIC_APP_CONFIG_RELATIVE_PATH = "config/public.js";
 const SERVER_APP_CONFIG_RELATIVE_PATH = "config/server.js";
-const PACKAGE_INSTALL_MODE_INSTALLABLE = "installable";
-const PACKAGE_INSTALL_MODE_CLONE_ONLY = "clone-only";
-const PACKAGE_INSTALL_MODES = Object.freeze([PACKAGE_INSTALL_MODE_INSTALLABLE, PACKAGE_INSTALL_MODE_CLONE_ONLY]);
+const PACKAGE_KIND_RUNTIME = "runtime";
+const PACKAGE_KIND_GENERATOR = "generator";
+const PACKAGE_KINDS = Object.freeze([PACKAGE_KIND_RUNTIME, PACKAGE_KIND_GENERATOR]);
 const WORKSPACE_VISIBILITY_LEVELS = Object.freeze(["workspace", "workspace_user"]);
 const WORKSPACE_VISIBILITY_SET = new Set(WORKSPACE_VISIBILITY_LEVELS);
 const MATERIALIZED_PACKAGE_ROOTS = new Map();
 const MATERIALIZED_PACKAGE_TEMP_DIRECTORIES = new Set();
+const LOCAL_WORKSPACE_PACKAGE_ROOTS = new Map();
+let LOCAL_WORKSPACE_PACKAGE_ID_INDEX = null;
 const BUILTIN_CAPABILITY_PROVIDERS = Object.freeze({
   "runtime.actions": Object.freeze(["@jskit-ai/kernel"])
 });
@@ -95,6 +95,20 @@ function normalizeMutationExtension(value) {
   return `.${extension}`;
 }
 
+function normalizeTemplateContextRecord(value) {
+  const record = ensureObject(value);
+  const entrypoint = String(record.entrypoint || "").trim();
+  const exportName = String(record.export || "").trim();
+  if (!entrypoint && !exportName) {
+    return null;
+  }
+
+  return Object.freeze({
+    entrypoint,
+    export: exportName || "buildTemplateContext"
+  });
+}
+
 function normalizeFileMutationRecord(value) {
   const record = ensureObject(value);
   const op = String(record.op || "copy-file").trim().toLowerCase() || "copy-file";
@@ -111,6 +125,7 @@ function normalizeFileMutationRecord(value) {
     id: String(record.id || "").trim(),
     category: String(record.category || "").trim(),
     reason: String(record.reason || "").trim(),
+    templateContext: normalizeTemplateContextRecord(record.templateContext),
     when: normalizeMutationWhen(record.when)
   };
 }
@@ -184,6 +199,44 @@ function normalizeWhenSourceValue(value) {
   return "";
 }
 
+function normalizeWhenComparisonValue(value) {
+  const normalizedValue = normalizeWhenSourceValue(value);
+  if (!normalizedValue.includes(",")) {
+    return normalizedValue;
+  }
+
+  return normalizedValue
+    .split(",")
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean)
+    .join(",");
+}
+
+function splitWhenComparisonTokens(value) {
+  return normalizeWhenComparisonValue(value)
+    .split(",")
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+}
+
+function matchesWhenComparisonValue(optionValue, optionTokens, expectedValue) {
+  const expected = normalizeWhenComparisonValue(expectedValue);
+  if (!expected) {
+    return false;
+  }
+
+  const expectedTokens = splitWhenComparisonTokens(expected);
+  if (expectedTokens.length > 1) {
+    return optionValue === expected;
+  }
+
+  if (optionTokens.length > 1) {
+    return optionTokens.includes(expectedTokens[0]);
+  }
+
+  return optionValue === expectedTokens[0];
+}
+
 function resolveWhenConfigValue(configContext = {}, configPath = "") {
   const normalizedPath = String(configPath || "").trim();
   if (!normalizedPath) {
@@ -244,11 +297,12 @@ function shouldApplyMutationWhen(
   const sourceValue = optionName
     ? readObjectPath(options, optionName)
     : resolveWhenConfigValue(configContext, configPath);
-  const optionValue = normalizeWhenSourceValue(sourceValue);
-  const equals = String(when.equals || "").trim();
-  const notEquals = String(when.notEquals || "").trim();
-  const includes = ensureArray(when.includes).map((entry) => String(entry || "").trim()).filter(Boolean);
-  const excludes = ensureArray(when.excludes).map((entry) => String(entry || "").trim()).filter(Boolean);
+  const optionValue = normalizeWhenComparisonValue(sourceValue);
+  const optionTokens = splitWhenComparisonTokens(optionValue);
+  const equals = normalizeWhenComparisonValue(when.equals);
+  const notEquals = normalizeWhenComparisonValue(when.notEquals);
+  const includes = ensureArray(when.includes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
+  const excludes = ensureArray(when.excludes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
 
   if (equals && optionValue !== equals) {
     return false;
@@ -256,10 +310,10 @@ function shouldApplyMutationWhen(
   if (notEquals && optionValue === notEquals) {
     return false;
   }
-  if (includes.length > 0 && !includes.includes(optionValue)) {
+  if (includes.length > 0 && !includes.some((entry) => matchesWhenComparisonValue(optionValue, optionTokens, entry))) {
     return false;
   }
-  if (excludes.length > 0 && excludes.includes(optionValue)) {
+  if (excludes.length > 0 && excludes.some((entry) => matchesWhenComparisonValue(optionValue, optionTokens, entry))) {
     return false;
   }
 
@@ -1113,16 +1167,16 @@ function removeEnvValue(content, key, expectedValue, previous) {
   };
 }
 
-function normalizePackageInstallationMode(rawValue, descriptorPath) {
-  const normalized = String(rawValue || "")
-    .trim()
-    .toLowerCase();
+function normalizePackageKind(rawValue, descriptorPath) {
+  const normalized = String(rawValue || "").trim().toLowerCase();
   if (!normalized) {
-    return PACKAGE_INSTALL_MODE_INSTALLABLE;
+    throw createCliError(
+      `Invalid package descriptor at ${descriptorPath}: missing kind (expected ${PACKAGE_KINDS.join(" | ")}).`
+    );
   }
-  if (!PACKAGE_INSTALL_MODES.includes(normalized)) {
+  if (!PACKAGE_KINDS.includes(normalized)) {
     throw createCliError(
-      `Invalid package descriptor at ${descriptorPath}: installationMode must be one of: ${PACKAGE_INSTALL_MODES.join(", ")}.`
+      `Invalid package descriptor at ${descriptorPath}: kind must be one of: ${PACKAGE_KINDS.join(", ")}.`
     );
   }
   return normalized;
@@ -1177,13 +1231,13 @@ function validatePackageDescriptorShape(descriptor, descriptorPath) {
 
   return {
     ...normalized,
-    installationMode: normalizePackageInstallationMode(normalized.installationMode, descriptorPath)
+    kind: normalizePackageKind(normalized.kind, descriptorPath)
   };
 }
 
-function isCloneOnlyPackageEntry(packageEntry) {
+function isGeneratorPackageEntry(packageEntry) {
   const descriptor = ensureObject(packageEntry?.descriptor);
-  return String(descriptor.installationMode || "").trim().toLowerCase() === PACKAGE_INSTALL_MODE_CLONE_ONLY;
+  return String(descriptor.kind || "").trim().toLowerCase() === PACKAGE_KIND_GENERATOR;
 }
 
 function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { expectedPackageId = "", fallbackVersion = "" } = {}) {
@@ -1208,7 +1262,8 @@ function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { ex
   return {
     ...normalized,
     packageId,
-    version
+    version,
+    kind: normalizePackageKind(normalized.kind, descriptorPath)
   };
 }
 
@@ -1277,85 +1332,6 @@ function validateBundleDescriptorShape(descriptor, descriptorPath) {
   return normalized;
 }
 
-async function loadWorkspacePackageRegistry() {
-  if (!MODULES_ROOT || !(await fileExists(MODULES_ROOT))) {
-    return new Map();
-  }
-
-  const directories = [];
-  const levelOne = await readdir(MODULES_ROOT, { withFileTypes: true });
-
-  for (const entry of levelOne) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-    if (entry.name.startsWith(".") || entry.name.endsWith(".LEGACY")) {
-      continue;
-    }
-
-    const absolute = path.join(MODULES_ROOT, entry.name);
-    const descriptorPath = path.join(absolute, "package.descriptor.mjs");
-    if (await fileExists(descriptorPath)) {
-      directories.push(absolute);
-      continue;
-    }
-
-    const nested = await readdir(absolute, { withFileTypes: true }).catch(() => []);
-    for (const child of nested) {
-      if (!child.isDirectory() || child.name.startsWith(".")) {
-        continue;
-      }
-      const nestedAbsolute = path.join(absolute, child.name);
-      const nestedDescriptor = path.join(nestedAbsolute, "package.descriptor.mjs");
-      if (await fileExists(nestedDescriptor)) {
-        directories.push(nestedAbsolute);
-      }
-    }
-  }
-
-  const uniqueDirectories = sortStrings([...new Set(directories)]);
-  const registry = new Map();
-
-  for (const packageRoot of uniqueDirectories) {
-    const descriptorPath = path.join(packageRoot, "package.descriptor.mjs");
-    const descriptorModule = await import(pathToFileURL(descriptorPath).href);
-    const descriptor = validatePackageDescriptorShape(descriptorModule?.default, descriptorPath);
-
-    const packageJsonPath = path.join(packageRoot, "package.json");
-    if (!(await fileExists(packageJsonPath))) {
-      throw createCliError(`Missing package.json for ${descriptor.packageId} at ${packageRoot}.`);
-    }
-    const packageJson = await readJsonFile(packageJsonPath);
-    const packageName = String(packageJson?.name || "").trim();
-    if (packageName !== descriptor.packageId) {
-      throw createCliError(
-        `Descriptor/package mismatch at ${packageRoot}: package.descriptor.mjs has ${descriptor.packageId} but package.json has ${packageName || "(empty)"}.`
-      );
-    }
-
-    const relativeDir = normalizeRelativePath(WORKSPACE_ROOT || MODULES_ROOT, packageRoot);
-    const descriptorRelativePath = normalizeRelativePath(WORKSPACE_ROOT || MODULES_ROOT, descriptorPath);
-    registry.set(
-      descriptor.packageId,
-      createPackageEntry({
-        packageId: descriptor.packageId,
-        version: descriptor.version,
-        descriptor,
-        rootDir: packageRoot,
-        relativeDir,
-        descriptorRelativePath,
-        packageJson,
-        sourceType: "packages-directory",
-        source: {
-          descriptorPath: descriptorRelativePath
-        }
-      })
-    );
-  }
-
-  return registry;
-}
-
 async function loadAppLocalPackageRegistry(appRoot) {
   const localPackagesRoot = path.join(appRoot, "packages");
   if (!(await fileExists(localPackagesRoot))) {
@@ -1468,17 +1444,14 @@ async function loadCatalogPackageRegistry() {
 }
 
 async function loadPackageRegistry() {
-  const workspaceRegistry = await loadWorkspacePackageRegistry();
   const catalogRegistry = await loadCatalogPackageRegistry();
-  const merged = mergePackageRegistries(catalogRegistry, workspaceRegistry);
-
-  if (merged.size === 0) {
+  if (catalogRegistry.size === 0) {
     throw createCliError(
-      "Unable to load package registry. Provide JSKIT_REPO_ROOT for workspace mode or ensure @jskit-ai/jskit-catalog is installed (or set JSKIT_CATALOG_PACKAGES_PATH)."
+      "Unable to load package registry from @jskit-ai/jskit-catalog. Install it alongside @jskit-ai/jskit-cli or set JSKIT_CATALOG_PACKAGES_PATH."
     );
   }
 
-  return merged;
+  return catalogRegistry;
 }
 
 async function loadInstalledNodeModulePackageEntry({ appRoot, packageId }) {
@@ -1745,6 +1718,7 @@ function createLocalPackageDescriptorTemplate({ packageId, description }) {
   packageVersion: 1,
   packageId: "${packageId}",
   version: "0.1.0",
+  kind: "runtime",
   description: ${JSON.stringify(String(description || ""))},
   dependsOn: [
     // "@jskit-ai/kernel"
@@ -3511,11 +3485,110 @@ async function materializePackageRootFromRegistry({ packageEntry, appRoot }) {
   return packageRoot;
 }
 
+async function resolvePackageRootFromNodeModules({ appRoot, packageId }) {
+  const normalizedAppRoot = path.resolve(String(appRoot || "").trim());
+  const normalizedPackageId = String(packageId || "").trim();
+  if (!normalizedAppRoot || !normalizedPackageId) {
+    return "";
+  }
+
+  const candidateRoot = path.resolve(normalizedAppRoot, "node_modules", ...normalizedPackageId.split("/"));
+  const candidateDescriptorPath = path.join(candidateRoot, "package.descriptor.mjs");
+  if (!(await fileExists(candidateDescriptorPath))) {
+    return "";
+  }
+
+  return candidateRoot;
+}
+
+async function loadLocalWorkspacePackageIdIndex() {
+  if (LOCAL_WORKSPACE_PACKAGE_ID_INDEX instanceof Map) {
+    return LOCAL_WORKSPACE_PACKAGE_ID_INDEX;
+  }
+
+  const repoRoot = path.resolve(CLI_PACKAGE_ROOT, "..", "..");
+  const parentDirectories = [
+    path.join(repoRoot, "packages"),
+    path.join(repoRoot, "tooling")
+  ];
+  const packageIdIndex = new Map();
+
+  for (const parentDirectory of parentDirectories) {
+    if (!(await fileExists(parentDirectory))) {
+      continue;
+    }
+
+    const entries = await readdir(parentDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) {
+        continue;
+      }
+
+      const candidateRoot = path.join(parentDirectory, entry.name);
+      const packageJsonPath = path.join(candidateRoot, "package.json");
+      const descriptorPath = path.join(candidateRoot, "package.descriptor.mjs");
+      if (!(await fileExists(packageJsonPath)) || !(await fileExists(descriptorPath))) {
+        continue;
+      }
+
+      let packageJson = {};
+      try {
+        packageJson = await readJsonFile(packageJsonPath);
+      } catch {
+        continue;
+      }
+
+      const packageId = String(packageJson?.name || "").trim();
+      if (!packageId.startsWith("@jskit-ai/")) {
+        continue;
+      }
+      if (packageIdIndex.has(packageId)) {
+        continue;
+      }
+      packageIdIndex.set(packageId, candidateRoot);
+    }
+  }
+
+  LOCAL_WORKSPACE_PACKAGE_ID_INDEX = packageIdIndex;
+  return packageIdIndex;
+}
+
+async function resolvePackageRootFromLocalWorkspace({ packageId }) {
+  const normalizedPackageId = String(packageId || "").trim();
+  if (!normalizedPackageId.startsWith("@jskit-ai/")) {
+    return "";
+  }
+  if (LOCAL_WORKSPACE_PACKAGE_ROOTS.has(normalizedPackageId)) {
+    return LOCAL_WORKSPACE_PACKAGE_ROOTS.get(normalizedPackageId);
+  }
+
+  const packageIdIndex = await loadLocalWorkspacePackageIdIndex();
+  const packageRoot = String(packageIdIndex.get(normalizedPackageId) || "").trim();
+  LOCAL_WORKSPACE_PACKAGE_ROOTS.set(normalizedPackageId, packageRoot);
+  return packageRoot;
+}
+
 async function resolvePackageTemplateRoot({ packageEntry, appRoot }) {
   const packageRoot = String(packageEntry?.rootDir || "").trim();
   if (packageRoot) {
     return packageRoot;
   }
+
+  const installedPackageRoot = await resolvePackageRootFromNodeModules({
+    appRoot,
+    packageId: packageEntry?.packageId
+  });
+  if (installedPackageRoot) {
+    return installedPackageRoot;
+  }
+
+  const localWorkspacePackageRoot = await resolvePackageRootFromLocalWorkspace({
+    packageId: packageEntry?.packageId
+  });
+  if (localWorkspacePackageRoot) {
+    return localWorkspacePackageRoot;
+  }
+
   return await materializePackageRootFromRegistry({ packageEntry, appRoot });
 }
 
@@ -3525,6 +3598,8 @@ async function cleanupMaterializedPackageRoots() {
   }
   MATERIALIZED_PACKAGE_TEMP_DIRECTORIES.clear();
   MATERIALIZED_PACKAGE_ROOTS.clear();
+  LOCAL_WORKSPACE_PACKAGE_ROOTS.clear();
+  LOCAL_WORKSPACE_PACKAGE_ID_INDEX = null;
 }
 
 function interpolateFileMutationRecord(mutation, options, packageId) {
@@ -3544,20 +3619,134 @@ function interpolateFileMutationRecord(mutation, options, packageId) {
     extension: interpolate(mutation.extension, "extension"),
     id: interpolate(mutation.id, "id"),
     category: interpolate(mutation.category, "category"),
-    reason: interpolate(mutation.reason, "reason")
+    reason: interpolate(mutation.reason, "reason"),
+    templateContext: mutation.templateContext
+      ? {
+          entrypoint: interpolate(mutation.templateContext.entrypoint, "templateContext.entrypoint"),
+          export: interpolate(mutation.templateContext.export, "templateContext.export")
+        }
+      : null
   };
 }
 
-async function copyTemplateFile(sourcePath, targetPath, options, packageId, interpolationKey) {
+function applyTemplateContextReplacements(sourceContent, replacements) {
+  let output = String(sourceContent || "");
+  for (const [placeholder, value] of Object.entries(ensureObject(replacements))) {
+    const normalizedPlaceholder = String(placeholder || "");
+    if (!normalizedPlaceholder) {
+      continue;
+    }
+    output = output.split(normalizedPlaceholder).join(String(value == null ? "" : value));
+  }
+  return output;
+}
+
+async function copyTemplateFile(
+  sourcePath,
+  targetPath,
+  options,
+  packageId,
+  interpolationKey,
+  templateContextReplacements = null
+) {
   const sourceContent = await readFile(sourcePath, "utf8");
-  const renderedContent = sourceContent.includes("${")
+  let renderedContent = sourceContent.includes("${")
     ? interpolateOptionValue(sourceContent, options, packageId, interpolationKey)
     : sourceContent;
+  if (templateContextReplacements) {
+    renderedContent = applyTemplateContextReplacements(renderedContent, templateContextReplacements);
+  }
 
   await mkdir(path.dirname(targetPath), { recursive: true });
   await writeFile(targetPath, renderedContent, "utf8");
 }
 
+async function resolveTemplateContextReplacementsForMutation({
+  packageEntry,
+  mutation,
+  options,
+  appRoot,
+  sourcePath,
+  targetPaths
+} = {}) {
+  const templateContext = ensureObject(mutation?.templateContext);
+  const hasTemplateContext = Object.keys(templateContext).length > 0;
+  const entrypoint = String(templateContext.entrypoint || "").trim();
+  if (!hasTemplateContext) {
+    return null;
+  }
+  if (!entrypoint) {
+    throw createCliError(
+      `Invalid files mutation in ${packageEntry.packageId}: templateContext.entrypoint is required when templateContext is set.`
+    );
+  }
+  const exportName = String(templateContext.export || "").trim() || "buildTemplateContext";
+  const resolvedEntrypointPath = resolveAppRelativePathWithinRoot(
+    packageEntry.rootDir,
+    entrypoint,
+    `${packageEntry.packageId} files mutation templateContext.entrypoint`
+  );
+  const absoluteEntrypointPath = resolvedEntrypointPath.absolutePath;
+  if (!(await fileExists(absoluteEntrypointPath))) {
+    throw createCliError(
+      `Invalid files mutation in ${packageEntry.packageId}: templateContext.entrypoint not found at ${entrypoint}.`
+    );
+  }
+
+  let moduleNamespace = null;
+  try {
+    moduleNamespace = await import(`${pathToFileURL(absoluteEntrypointPath).href}?t=${Date.now()}_${Math.random()}`);
+  } catch (error) {
+    throw createCliError(
+      `Unable to load templateContext entrypoint ${entrypoint} for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  const resolver = moduleNamespace?.[exportName];
+  if (typeof resolver !== "function") {
+    throw createCliError(
+      `Invalid files mutation in ${packageEntry.packageId}: templateContext export "${exportName}" is not a function.`
+    );
+  }
+
+  let replacements = null;
+  try {
+    replacements = await resolver({
+      packageId: packageEntry.packageId,
+      packageRoot: packageEntry.rootDir,
+      appRoot,
+      options: Object.freeze({ ...ensureObject(options) }),
+      mutation: Object.freeze({ ...ensureObject(mutation) }),
+      sourcePath,
+      targetPaths: Object.freeze([...ensureArray(targetPaths)])
+    });
+  } catch (error) {
+    throw createCliError(
+      `templateContext export "${exportName}" failed for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  if (replacements == null) {
+    return null;
+  }
+  if (!replacements || typeof replacements !== "object" || Array.isArray(replacements)) {
+    throw createCliError(
+      `Invalid files mutation in ${packageEntry.packageId}: templateContext export "${exportName}" must return an object map of placeholder replacements.`
+    );
+  }
+
+  const normalizedReplacements = {};
+  for (const [placeholder, value] of Object.entries(replacements)) {
+    const normalizedPlaceholder = String(placeholder || "").trim();
+    if (!normalizedPlaceholder) {
+      continue;
+    }
+    normalizedReplacements[normalizedPlaceholder] = String(value == null ? "" : value);
+  }
+
+  return Object.freeze(normalizedReplacements);
+}
+
 function normalizeSurfaceIdForMutation(value = "") {
   return String(value || "")
     .trim()
@@ -3738,8 +3927,10 @@ async function applyFileMutations(
   managedFiles,
   managedMigrations,
   touchedFiles,
-  warnings = []
+  warnings = [],
+  precomputedTemplateContextByMutationIndex = null
 ) {
+  const mutationList = ensureArray(fileMutations);
   const managedMigrationById = new Map();
   for (const managedMigrationValue of ensureArray(managedMigrations)) {
     const managedMigration = ensureObject(managedMigrationValue);
@@ -3750,7 +3941,7 @@ async function applyFileMutations(
     managedMigrationById.set(migrationId, managedMigration);
   }
 
-  for (const mutationValue of fileMutations) {
+  for (const [mutationIndex, mutationValue] of mutationList.entries()) {
     const normalizedMutation = normalizeFileMutationRecord(mutationValue);
     const requiresConfigContext = Boolean(normalizedMutation.when?.config || normalizedMutation.toSurface);
     const configContext = requiresConfigContext ? await loadMutationWhenConfigContext(appRoot) : {};
@@ -3788,10 +3979,27 @@ async function applyFileMutations(
         throw createCliError(`Missing migration template source ${sourcePath} for ${packageEntry.packageId}.`);
       }
 
+      const hasPrecomputedTemplateContext =
+        precomputedTemplateContextByMutationIndex instanceof Map &&
+        precomputedTemplateContextByMutationIndex.has(mutationIndex);
+      const templateContextReplacements = hasPrecomputedTemplateContext
+        ? precomputedTemplateContextByMutationIndex.get(mutationIndex)
+        : await resolveTemplateContextReplacementsForMutation({
+            packageEntry,
+            mutation,
+            options,
+            appRoot,
+            sourcePath,
+            targetPaths: [path.join(appRoot, toDir)]
+          });
+
       const sourceContent = await readFile(sourcePath, "utf8");
-      const renderedSourceContent = sourceContent.includes("${")
+      let renderedSourceContent = sourceContent.includes("${")
         ? interpolateOptionValue(sourceContent, options, packageEntry.packageId, `${mutation.id || from}.source`)
         : sourceContent;
+      if (templateContextReplacements) {
+        renderedSourceContent = applyTemplateContextReplacements(renderedSourceContent, templateContextReplacements);
+      }
       const sourceExtension = normalizeMigrationExtension(path.extname(from), ".cjs");
       const extension = normalizeMigrationExtension(mutation.extension, sourceExtension);
       const sourceHash = hashBuffer(Buffer.from(renderedSourceContent, "utf8"));
@@ -3956,6 +4164,19 @@ async function applyFileMutations(
           configContext
         })
       : [path.join(appRoot, to)];
+    const hasPrecomputedTemplateContext =
+      precomputedTemplateContextByMutationIndex instanceof Map &&
+      precomputedTemplateContextByMutationIndex.has(mutationIndex);
+    const templateContextReplacements = hasPrecomputedTemplateContext
+      ? precomputedTemplateContextByMutationIndex.get(mutationIndex)
+      : await resolveTemplateContextReplacementsForMutation({
+          packageEntry,
+          mutation,
+          options,
+          appRoot,
+          sourcePath,
+          targetPaths
+        });
     for (const targetPath of targetPaths) {
       const previous = await readFileBufferIfExists(targetPath);
       await copyTemplateFile(
@@ -3963,7 +4184,8 @@ async function applyFileMutations(
         targetPath,
         options,
         packageEntry.packageId,
-        `${mutation.id || to || from}.source`
+        `${mutation.id || to || from}.source`,
+        templateContextReplacements
       );
       const nextBuffer = await readFile(targetPath);
 
@@ -3982,6 +4204,91 @@ async function applyFileMutations(
   }
 }
 
+async function preflightFileMutationTemplateContexts(
+  packageEntry,
+  options,
+  appRoot,
+  fileMutations
+) {
+  const mutationList = ensureArray(fileMutations);
+  const replacementsByMutationIndex = new Map();
+
+  for (const [mutationIndex, mutationValue] of mutationList.entries()) {
+    const normalizedMutation = normalizeFileMutationRecord(mutationValue);
+    const requiresConfigContext = Boolean(normalizedMutation.when?.config || normalizedMutation.toSurface);
+    const configContext = requiresConfigContext ? await loadMutationWhenConfigContext(appRoot) : {};
+    if (
+      !shouldApplyMutationWhen(normalizedMutation.when, {
+        options,
+        configContext,
+        packageId: packageEntry.packageId,
+        mutationContext: "files mutation"
+      })
+    ) {
+      continue;
+    }
+
+    const mutation = interpolateFileMutationRecord(normalizedMutation, options, packageEntry.packageId);
+    const templateContext = ensureObject(mutation.templateContext);
+    if (Object.keys(templateContext).length < 1) {
+      continue;
+    }
+
+    const operation = mutation.op || "copy-file";
+    if (operation !== "copy-file" && operation !== "install-migration") {
+      continue;
+    }
+
+    const from = mutation.from;
+    const to = mutation.to;
+    const toSurface = mutation.toSurface;
+    if (!from) {
+      throw createCliError(
+        `Invalid files mutation in ${packageEntry.packageId}: "from" is required.`
+      );
+    }
+    if (operation === "copy-file") {
+      if (to && toSurface) {
+        throw createCliError(
+          `Invalid files mutation in ${packageEntry.packageId}: "to" and "toSurface" cannot both be set.`
+        );
+      }
+      if (!to && !toSurface) {
+        throw createCliError(
+          `Invalid files mutation in ${packageEntry.packageId}: "from" plus one destination ("to" or "toSurface") are required.`
+        );
+      }
+    }
+
+    const sourcePath = path.join(packageEntry.rootDir, from);
+    if (!(await fileExists(sourcePath))) {
+      throw createCliError(`Missing template source ${sourcePath} for ${packageEntry.packageId}.`);
+    }
+
+    const targetPaths = operation === "copy-file"
+      ? toSurface
+        ? resolveSurfaceTargetPathsForMutation({
+            appRoot,
+            packageId: packageEntry.packageId,
+            mutation,
+            configContext
+          })
+        : [path.join(appRoot, to)]
+      : [path.join(appRoot, mutation.toDir || "migrations")];
+    const replacements = await resolveTemplateContextReplacementsForMutation({
+      packageEntry,
+      mutation,
+      options,
+      appRoot,
+      sourcePath,
+      targetPaths
+    });
+    replacementsByMutationIndex.set(mutationIndex, replacements);
+  }
+
+  return replacementsByMutationIndex;
+}
+
 async function applyTextMutations(packageEntry, appRoot, textMutations, options, managedText, touchedFiles) {
   for (const mutation of textMutations) {
     const when = normalizeMutationWhen(mutation?.when);
@@ -4391,9 +4698,10 @@ async function applyPackageInstall({
 
   const managedRecord = createManagedRecordBase(packageEntry, packageOptions);
   managedRecord.managed.migrations = cloneManagedArray(existingManaged.migrations);
-  const cloneOnlyPackage = isCloneOnlyPackageEntry(packageEntry);
+  const generatorPackage = isGeneratorPackageEntry(packageEntry);
   const mutationWarnings = [];
   const mutations = ensureObject(packageEntry.descriptor.mutations);
+  const fileMutations = ensureArray(mutations.files);
   const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
   const packageEntryForMutations =
     templateRoot === packageEntry.rootDir
@@ -4402,6 +4710,14 @@ async function applyPackageInstall({
           ...packageEntry,
           rootDir: templateRoot
         };
+
+  const precomputedTemplateContextByMutationIndex = await preflightFileMutationTemplateContexts(
+    packageEntryForMutations,
+    packageOptions,
+    appRoot,
+    fileMutations
+  );
+
   const mutationDependencies = ensureObject(mutations.dependencies);
   const runtimeDependencies = ensureObject(mutationDependencies.runtime);
   const devDependencies = ensureObject(mutationDependencies.dev);
@@ -4471,7 +4787,7 @@ async function applyPackageInstall({
     }
   }
 
-  if (cloneOnlyPackage) {
+  if (generatorPackage) {
     const removedRuntimeDependency = removePackageJsonField(appPackageJson, "dependencies", packageEntry.packageId);
     const removedDevDependency = removePackageJsonField(appPackageJson, "devDependencies", packageEntry.packageId);
     if (removedRuntimeDependency || removedDevDependency) {
@@ -4507,11 +4823,12 @@ async function applyPackageInstall({
     packageEntryForMutations,
     packageOptions,
     appRoot,
-    ensureArray(mutations.files),
+    fileMutations,
     managedRecord.managed.files,
     managedRecord.managed.migrations,
     touchedFiles,
-    mutationWarnings
+    mutationWarnings,
+    precomputedTemplateContextByMutationIndex
   );
 
   await applyTextMutations(
@@ -4532,7 +4849,7 @@ async function applyPackageInstall({
     touchedFiles
   );
 
-  if (cloneOnlyPackage) {
+  if (generatorPackage) {
     delete lock.installedPackages[packageEntry.packageId];
   } else {
     managedRecord.migrationSyncVersion = packageEntry.version;