@jskit-ai/jskit-cli 0.2.24 → 0.2.26

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,9 +53,9 @@ 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();
@@ -95,6 +93,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 +123,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 +197,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 +295,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 +308,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 +1165,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 +1229,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 +1260,8 @@ function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { ex
   return {
     ...normalized,
     packageId,
-    version
+    version,
+    kind: normalizePackageKind(normalized.kind, descriptorPath)
   };
 }
 
@@ -1277,85 +1330,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 +1442,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 +1716,7 @@ function createLocalPackageDescriptorTemplate({ packageId, description }) {
   packageVersion: 1,
   packageId: "${packageId}",
   version: "0.1.0",
+  kind: "runtime",
   description: ${JSON.stringify(String(description || ""))},
   dependsOn: [
     // "@jskit-ai/kernel"
@@ -3544,20 +3516,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 +3824,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 +3838,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 +3876,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 +4061,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 +4081,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 +4101,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);
@@ -4298,6 +4502,79 @@ async function applyPackagePositioning({
   return managedRecord;
 }
 
+async function applyPackageMigrationsOnly({
+  packageEntry,
+  packageOptions,
+  appRoot,
+  lock,
+  touchedFiles
+}) {
+  const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
+  if (Object.keys(existingInstall).length < 1) {
+    throw createCliError(`Package is not installed: ${packageEntry.packageId}`);
+  }
+
+  const existingManaged = ensureObject(existingInstall.managed);
+  const existingPackageJsonManaged = ensureObject(existingManaged.packageJson);
+  const nextManaged = {
+    packageJson: {
+      dependencies: cloneManagedMap(existingPackageJsonManaged.dependencies),
+      devDependencies: cloneManagedMap(existingPackageJsonManaged.devDependencies),
+      scripts: cloneManagedMap(existingPackageJsonManaged.scripts)
+    },
+    text: cloneManagedMap(existingManaged.text),
+    vite: cloneManagedMap(existingManaged.vite),
+    files: cloneManagedArray(existingManaged.files),
+    migrations: cloneManagedArray(existingManaged.migrations)
+  };
+
+  const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
+  const packageEntryForMutations =
+    templateRoot === packageEntry.rootDir
+      ? packageEntry
+      : {
+          ...packageEntry,
+          rootDir: templateRoot
+        };
+  const mutations = ensureObject(packageEntry.descriptor.mutations);
+  const migrationFileMutations = ensureArray(mutations.files).filter((mutationValue) => {
+    const normalized = normalizeFileMutationRecord(mutationValue);
+    const operation = String(normalized.op || "copy-file").trim();
+    return operation === "install-migration";
+  });
+  const mutationWarnings = [];
+
+  if (migrationFileMutations.length > 0) {
+    await applyFileMutations(
+      packageEntryForMutations,
+      packageOptions,
+      appRoot,
+      migrationFileMutations,
+      [],
+      nextManaged.migrations,
+      touchedFiles,
+      mutationWarnings
+    );
+  }
+
+  const managedRecord = {
+    ...existingInstall,
+    packageId: packageEntry.packageId,
+    source: resolveManagedSourceRecord(packageEntry, existingInstall),
+    managed: nextManaged,
+    options: {
+      ...ensureObject(packageOptions)
+    },
+    migrationSyncVersion: packageEntry.version,
+    installedAt: String(existingInstall.installedAt || new Date().toISOString())
+  };
+  lock.installedPackages[packageEntry.packageId] = managedRecord;
+  if (mutationWarnings.length > 0) {
+    managedRecord.warnings = mutationWarnings;
+  }
+  return managedRecord;
+}
+
 async function applyPackageInstall({
   packageEntry,
   packageOptions,
@@ -4318,9 +4595,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
@@ -4329,6 +4607,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);
@@ -4398,7 +4684,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) {
@@ -4434,11 +4720,12 @@ async function applyPackageInstall({
     packageEntryForMutations,
     packageOptions,
     appRoot,
-    ensureArray(mutations.files),
+    fileMutations,
     managedRecord.managed.files,
     managedRecord.managed.migrations,
     touchedFiles,
-    mutationWarnings
+    mutationWarnings,
+    precomputedTemplateContextByMutationIndex
   );
 
   await applyTextMutations(
@@ -4459,9 +4746,10 @@ async function applyPackageInstall({
     touchedFiles
   );
 
-  if (cloneOnlyPackage) {
+  if (generatorPackage) {
     delete lock.installedPackages[packageEntry.packageId];
   } else {
+    managedRecord.migrationSyncVersion = packageEntry.version;
     lock.installedPackages[packageEntry.packageId] = managedRecord;
   }
   if (mutationWarnings.length > 0) {
@@ -4522,6 +4810,7 @@ const commandHandlers = createCommandHandlers(
     validatePlannedCapabilityClosure,
     resolvePackageOptions,
     applyPackageInstall,
+    applyPackageMigrationsOnly,
     applyPackagePositioning,
     adoptAppLocalPackageDependencies,
     loadAppPackageJson,