@jskit-ai/jskit-cli 0.2.41 → 0.2.43

package/src/server/cliRuntime/descriptorValidation.js

@@ -24,12 +24,27 @@ function normalizePackageKind(rawValue, descriptorPath) {
   return normalized;
 }
 
-function validateInstallMigrationMutationShape(descriptor, descriptorPath) {
+function validateFileMutationShape(descriptor, descriptorPath) {
   const packageId = String(ensureObject(descriptor).packageId || "").trim() || "unknown-package";
   const mutations = ensureObject(ensureObject(descriptor).mutations);
   const files = ensureArray(mutations.files);
   for (const fileMutation of files) {
     const normalized = normalizeFileMutationRecord(fileMutation);
+    if (normalized.ownership !== "package" && normalized.ownership !== "app") {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: files mutation in ${packageId} has unsupported ownership "${normalized.ownership}". Expected "package" or "app".`
+      );
+    }
+    if (normalized.expectedExistingFrom && normalized.op !== "copy-file") {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: files mutation in ${packageId} can only use "expectedExistingFrom" with copy-file.`
+      );
+    }
+    if (normalized.expectedExistingFrom && normalized.ownership !== "app") {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: files mutation in ${packageId} can only use "expectedExistingFrom" when ownership is "app".`
+      );
+    }
     if (normalized.op !== "install-migration") {
       continue;
     }
@@ -69,7 +84,7 @@ function validatePackageDescriptorShape(descriptor, descriptorPath) {
     );
   }
 
-  validateInstallMigrationMutationShape(normalized, descriptorPath);
+  validateFileMutationShape(normalized, descriptorPath);
 
   return {
     ...normalized,
@@ -99,7 +114,7 @@ function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { ex
     throw createCliError(`Invalid app-local package descriptor at ${descriptorPath}: missing version.`);
   }
 
-  validateInstallMigrationMutationShape(normalized, descriptorPath);
+  validateFileMutationShape(normalized, descriptorPath);
 
   return {
     ...normalized,

package/src/server/cliRuntime/ioAndMigrations.js

@@ -8,7 +8,7 @@ import {
   writeFile
 } from "node:fs/promises";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { importFreshModuleFromAbsolutePath } from "@jskit-ai/kernel/server/support";
 import { createCliError } from "../shared/cliError.js";
 import {
   ensureArray,
@@ -325,7 +325,7 @@ async function loadAppConfigModuleConfig(appRoot, relativePath) {
 
   let moduleNamespace = null;
   try {
-    moduleNamespace = await import(`${pathToFileURL(absolutePath).href}?t=${Date.now()}_${Math.random()}`);
+    moduleNamespace = await importFreshModuleFromAbsolutePath(absolutePath);
   } catch (error) {
     throw createCliError(
       `Unable to load ${relativePath}: ${String(error?.message || error || "unknown error")}`

package/src/server/cliRuntime/mutationApplication.js

@@ -1,6 +1,6 @@
 export {
   applyFileMutations,
-  preflightFileMutationTemplateContexts
+  prepareFileMutations
 } from "./mutations/fileMutations.js";
 
 export {

package/src/server/cliRuntime/mutationWhen.js

@@ -41,6 +41,8 @@ function normalizeFileMutationRecord(value) {
     toSurfaceRoot: record.toSurfaceRoot === true,
     toDir: String(record.toDir || "").trim(),
     extension: normalizeMutationExtension(record.extension),
+    ownership: String(record.ownership || "").trim().toLowerCase() || "package",
+    expectedExistingFrom: String(record.expectedExistingFrom || "").trim(),
     preserveOnRemove: record.preserveOnRemove === true,
     id: String(record.id || "").trim(),
     category: String(record.category || "").trim(),

package/src/server/cliRuntime/mutations/fileMutations.js

@@ -1,5 +1,6 @@
 import {
-  readFile
+  mkdir,
+  writeFile
 } from "node:fs/promises";
 import path from "node:path";
 import { createCliError } from "../../shared/cliError.js";
@@ -20,151 +21,32 @@ import {
   resolveAppRelativePathWithinRoot
 } from "../ioAndMigrations.js";
 import {
-  copyTemplateFile,
   interpolateFileMutationRecord,
+  renderTemplateFile,
   resolveTemplateContextReplacementsForMutation
 } from "./templateContext.js";
 import { resolveSurfaceTargetPathsForMutation } from "./surfaceTargets.js";
 import { applyInstallMigrationMutation } from "./installMigrationMutation.js";
 
-async function applyFileMutations(
+async function prepareFileMutations(
   packageEntry,
   options,
   appRoot,
   fileMutations,
-  managedFiles,
-  managedMigrations,
-  touchedFiles,
-  warnings = [],
-  precomputedTemplateContextByMutationIndex = null
+  existingManagedFiles = []
 ) {
   const mutationList = ensureArray(fileMutations);
-  const managedMigrationById = new Map();
-  for (const managedMigrationValue of ensureArray(managedMigrations)) {
-    const managedMigration = ensureObject(managedMigrationValue);
-    const migrationId = String(managedMigration.id || "").trim();
-    if (!migrationId) {
-      continue;
-    }
-    managedMigrationById.set(migrationId, managedMigration);
-  }
-
-  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 operation = mutation.op || "copy-file";
-
-    if (operation === "install-migration") {
-      await applyInstallMigrationMutation({
-        packageEntry,
-        mutation,
-        rawMutation: mutationValue,
-        mutationIndex,
-        options,
-        appRoot,
-        managedMigrations,
-        managedMigrationById,
-        touchedFiles,
-        warnings,
-        precomputedTemplateContextByMutationIndex
-      });
+  const existingManagedFilesByPath = new Map();
+  for (const managedFileValue of ensureArray(existingManagedFiles)) {
+    const managedFile = ensureObject(managedFileValue);
+    const managedPath = String(managedFile.path || "").trim();
+    if (!managedPath) {
       continue;
     }
-
-    if (operation !== "copy-file") {
-      throw createCliError(`Unsupported files mutation op \"${operation}\" in ${packageEntry.packageId}.`);
-    }
-
-    const from = mutation.from;
-    const to = mutation.to;
-    const toSurface = mutation.toSurface;
-    if (to && toSurface) {
-      throw createCliError(
-        `Invalid files mutation in ${packageEntry.packageId}: "to" and "toSurface" cannot both be set.`
-      );
-    }
-    if (!from || (!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 = toSurface
-      ? resolveSurfaceTargetPathsForMutation({
-          appRoot,
-          packageId: packageEntry.packageId,
-          mutation,
-          configContext
-        })
-      : [resolveAppRelativePathWithinRoot(appRoot, to, `${packageEntry.packageId} files mutation.to`).absolutePath];
-    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(
-        sourcePath,
-        targetPath,
-        options,
-        packageEntry.packageId,
-        `${mutation.id || to || from}.source`,
-        templateContextReplacements
-      );
-      const nextBuffer = await readFile(targetPath);
-
-      managedFiles.push({
-        path: normalizeRelativePath(appRoot, targetPath),
-        hash: hashBuffer(nextBuffer),
-        hadPrevious: previous.exists,
-        previousContentBase64: previous.exists ? previous.buffer.toString("base64") : "",
-        preserveOnRemove: mutation.preserveOnRemove,
-        reason: mutation.reason,
-        category: mutation.category,
-        id: mutation.id
-      });
-      touchedFiles.add(normalizeRelativePath(appRoot, targetPath));
-    }
+    existingManagedFilesByPath.set(managedPath, managedFile);
   }
-}
-
-async function preflightFileMutationTemplateContexts(
-  packageEntry,
-  options,
-  appRoot,
-  fileMutations
-) {
-  const mutationList = ensureArray(fileMutations);
-  const replacementsByMutationIndex = new Map();
 
+  const preparedMutations = [];
   for (const [mutationIndex, mutationValue] of mutationList.entries()) {
     const normalizedMutation = normalizeFileMutationRecord(mutationValue);
     const requiresConfigContext = Boolean(normalizedMutation.when?.config || normalizedMutation.toSurface);
@@ -181,23 +63,16 @@ async function preflightFileMutationTemplateContexts(
     }
 
     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;
+      throw createCliError(`Unsupported files mutation op "${operation}" in ${packageEntry.packageId}.`);
     }
 
     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.`
-      );
+      throw createCliError(`Invalid files mutation in ${packageEntry.packageId}: "from" is required.`);
     }
     if (operation === "copy-file") {
       if (to && toSurface) {
@@ -227,7 +102,7 @@ async function preflightFileMutationTemplateContexts(
           })
         : [resolveAppRelativePathWithinRoot(appRoot, to, `${packageEntry.packageId} files mutation.to`).absolutePath]
       : [path.join(appRoot, mutation.toDir || "migrations")];
-    const replacements = await resolveTemplateContextReplacementsForMutation({
+    const templateContextReplacements = await resolveTemplateContextReplacementsForMutation({
       packageEntry,
       mutation,
       options,
@@ -236,13 +111,183 @@ async function preflightFileMutationTemplateContexts(
       targetPaths,
       mutationContext: "files mutation"
     });
-    replacementsByMutationIndex.set(mutationIndex, replacements);
+    const interpolationKey = `${mutation.id || to || from}.source`;
+    const renderedSourceContent = await renderTemplateFile(
+      sourcePath,
+      options,
+      packageEntry.packageId,
+      interpolationKey,
+      templateContextReplacements
+    );
+
+    if (operation === "copy-file" && mutation.ownership === "app") {
+      const renderedSourceBuffer = Buffer.from(renderedSourceContent, "utf8");
+      const renderedSourceHash = hashBuffer(renderedSourceBuffer);
+      let expectedExistingHash = "";
+      if (mutation.expectedExistingFrom) {
+        const expectedExistingPath = path.join(packageEntry.rootDir, mutation.expectedExistingFrom);
+        if (!(await fileExists(expectedExistingPath))) {
+          throw createCliError(
+            `Missing expected existing source ${expectedExistingPath} for ${packageEntry.packageId}.`
+          );
+        }
+        const expectedExistingContent = await renderTemplateFile(
+          expectedExistingPath,
+          options,
+          packageEntry.packageId,
+          `${mutation.id || to || from}.expectedExisting`,
+          templateContextReplacements
+        );
+        expectedExistingHash = hashBuffer(Buffer.from(expectedExistingContent, "utf8"));
+      }
+
+      for (const targetPath of targetPaths) {
+        const relativeTargetPath = normalizeRelativePath(appRoot, targetPath);
+        if (existingManagedFilesByPath.has(relativeTargetPath)) {
+          const existing = await readFileBufferIfExists(targetPath);
+          if (!existing.exists) {
+            throw createCliError(
+              `${packageEntry.packageId}: app-owned file ${relativeTargetPath} is managed in lock but missing on disk. Restore it before updating, or remove and re-add the package intentionally.`
+            );
+          }
+          continue;
+        }
+
+        const existing = await readFileBufferIfExists(targetPath);
+        if (!existing.exists) {
+          continue;
+        }
+
+        const existingHash = hashBuffer(existing.buffer);
+        if (existingHash === renderedSourceHash) {
+          continue;
+        }
+        if (expectedExistingHash && existingHash === expectedExistingHash) {
+          continue;
+        }
+
+        const expectedSourceLabel = mutation.expectedExistingFrom
+          ? ` or match ${mutation.expectedExistingFrom}`
+          : "";
+        throw createCliError(
+          `${packageEntry.packageId}: app-owned file ${relativeTargetPath} already exists and cannot be claimed. It must already match the rendered scaffold${expectedSourceLabel}.`
+        );
+      }
+    }
+
+    preparedMutations.push({
+      mutationIndex,
+      mutation,
+      operation,
+      sourcePath,
+      targetPaths,
+      renderedSourceContent
+    });
+  }
+
+  return preparedMutations;
+}
+
+async function applyFileMutations(
+  packageEntry,
+  appRoot,
+  preparedMutations,
+  managedFiles,
+  managedMigrations,
+  touchedFiles,
+  warnings = [],
+  existingManagedFiles = []
+) {
+  const existingManagedFilesByPath = new Map();
+  for (const managedFileValue of ensureArray(existingManagedFiles)) {
+    const managedFile = ensureObject(managedFileValue);
+    const managedPath = String(managedFile.path || "").trim();
+    if (!managedPath) {
+      continue;
+    }
+    existingManagedFilesByPath.set(managedPath, managedFile);
+  }
+
+  const managedMigrationById = new Map();
+  for (const managedMigrationValue of ensureArray(managedMigrations)) {
+    const managedMigration = ensureObject(managedMigrationValue);
+    const migrationId = String(managedMigration.id || "").trim();
+    if (!migrationId) {
+      continue;
+    }
+    managedMigrationById.set(migrationId, managedMigration);
   }
 
-  return replacementsByMutationIndex;
+  for (const preparedMutation of ensureArray(preparedMutations)) {
+    const mutation = ensureObject(preparedMutation.mutation);
+    const operation = String(preparedMutation.operation || "").trim() || "copy-file";
+    if (operation === "install-migration") {
+      await applyInstallMigrationMutation({
+        packageEntry,
+        preparedMutation,
+        appRoot,
+        managedMigrations,
+        managedMigrationById,
+        touchedFiles,
+        warnings
+      });
+      continue;
+    }
+
+    const renderedSourceContent = String(preparedMutation.renderedSourceContent || "");
+    const renderedSourceBuffer = Buffer.from(renderedSourceContent, "utf8");
+    const renderedSourceHash = hashBuffer(renderedSourceBuffer);
+
+    for (const targetPath of ensureArray(preparedMutation.targetPaths)) {
+      const relativeTargetPath = normalizeRelativePath(appRoot, targetPath);
+      const previous = await readFileBufferIfExists(targetPath);
+      const existingManaged = existingManagedFilesByPath.get(relativeTargetPath);
+
+      if (mutation.ownership === "app" && existingManaged) {
+        managedFiles.push({
+          ...existingManaged,
+          path: relativeTargetPath,
+          preserveOnRemove: mutation.preserveOnRemove,
+          reason: mutation.reason || String(existingManaged.reason || ""),
+          category: mutation.category || String(existingManaged.category || ""),
+          id: mutation.id || String(existingManaged.id || "")
+        });
+        continue;
+      }
+
+      if (mutation.ownership === "app" && previous.exists && hashBuffer(previous.buffer) === renderedSourceHash) {
+        managedFiles.push({
+          path: relativeTargetPath,
+          hash: renderedSourceHash,
+          hadPrevious: true,
+          previousContentBase64: previous.buffer.toString("base64"),
+          preserveOnRemove: mutation.preserveOnRemove,
+          reason: mutation.reason,
+          category: mutation.category,
+          id: mutation.id
+        });
+        continue;
+      }
+
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      await writeFile(targetPath, renderedSourceContent, "utf8");
+
+      managedFiles.push({
+        path: relativeTargetPath,
+        hash: renderedSourceHash,
+        hadPrevious: previous.exists,
+        previousContentBase64: previous.exists ? previous.buffer.toString("base64") : "",
+        preserveOnRemove: mutation.preserveOnRemove,
+        reason: mutation.reason,
+        category: mutation.category,
+        id: mutation.id
+      });
+      touchedFiles.add(relativeTargetPath);
+    }
+  }
 }
 
 export {
   applyFileMutations,
-  preflightFileMutationTemplateContexts
+  prepareFileMutations
 };

package/src/server/cliRuntime/mutations/installMigrationMutation.js

@@ -6,7 +6,6 @@ import {
 import path from "node:path";
 import { createCliError } from "../../shared/cliError.js";
 import { ensureObject } from "../../shared/collectionUtils.js";
-import { interpolateOptionValue } from "../../shared/optionInterpolation.js";
 import {
   hashBuffer,
   normalizeMigrationExtension,
@@ -19,25 +18,18 @@ import {
   fileExists
 } from "../ioAndMigrations.js";
 import { normalizeRelativePosixPath } from "../localPackageSupport.js";
-import {
-  applyTemplateContextReplacements,
-  resolveTemplateContextReplacementsForMutation
-} from "./templateContext.js";
 
 async function applyInstallMigrationMutation({
   packageEntry,
-  mutation,
-  rawMutation,
-  mutationIndex,
-  options,
+  preparedMutation,
   appRoot,
   managedMigrations,
   managedMigrationById,
   touchedFiles,
-  warnings,
-  precomputedTemplateContextByMutationIndex
+  warnings
 } = {}) {
-  if (Object.hasOwn(ensureObject(rawMutation), "preserveOnRemove")) {
+  const mutation = ensureObject(preparedMutation?.mutation);
+  if (mutation.preserveOnRemove === true) {
     warnings.push(
       `${packageEntry.packageId}: install-migration ignores preserveOnRemove (migrations are always preserved on remove).`
     );
@@ -45,36 +37,17 @@ async function applyInstallMigrationMutation({
 
   const from = mutation.from;
   const toDir = mutation.toDir || "migrations";
+  const sourcePath = String(preparedMutation?.sourcePath || "").trim();
+  const renderedSourceContent = preparedMutation?.renderedSourceContent;
   if (!from) {
     throw createCliError(`Invalid install-migration mutation in ${packageEntry.packageId}: \"from\" is required.`);
   }
-  const migrationId = normalizeMigrationId(mutation.id, packageEntry.packageId);
-
-  const sourcePath = path.join(packageEntry.rootDir, from);
-  if (!(await fileExists(sourcePath))) {
-    throw createCliError(`Missing migration template source ${sourcePath} for ${packageEntry.packageId}.`);
+  if (!sourcePath) {
+    throw createCliError(`Invalid install-migration mutation in ${packageEntry.packageId}: missing prepared source path.`);
   }
-
-  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");
-  let renderedSourceContent = sourceContent.includes("${")
-    ? interpolateOptionValue(sourceContent, options, packageEntry.packageId, `${mutation.id || from}.source`)
-    : sourceContent;
-  if (templateContextReplacements) {
-    renderedSourceContent = applyTemplateContextReplacements(renderedSourceContent, templateContextReplacements);
+  const migrationId = normalizeMigrationId(mutation.id, packageEntry.packageId);
+  if (typeof renderedSourceContent !== "string") {
+    throw createCliError(`Invalid install-migration mutation in ${packageEntry.packageId}: missing rendered migration source.`);
   }
   const sourceExtension = normalizeMigrationExtension(path.extname(from), ".cjs");
   const extension = normalizeMigrationExtension(mutation.extension, sourceExtension);

package/src/server/cliRuntime/mutations/templateContext.js

@@ -1,10 +1,5 @@
-import {
-  mkdir,
-  readFile,
-  writeFile
-} from "node:fs/promises";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { readFile } from "node:fs/promises";
+import { importFreshModuleFromAbsolutePath } from "@jskit-ai/kernel/server/support";
 import { createCliError } from "../../shared/cliError.js";
 import {
   ensureArray,
@@ -31,6 +26,8 @@ function interpolateFileMutationRecord(mutation, options, packageId) {
     toSurfacePath: interpolate(mutation.toSurfacePath, "toSurfacePath"),
     toDir: interpolate(mutation.toDir, "toDir"),
     extension: interpolate(mutation.extension, "extension"),
+    ownership: interpolate(mutation.ownership, "ownership"),
+    expectedExistingFrom: interpolate(mutation.expectedExistingFrom, "expectedExistingFrom"),
     id: interpolate(mutation.id, "id"),
     category: interpolate(mutation.category, "category"),
     reason: interpolate(mutation.reason, "reason"),
@@ -55,9 +52,8 @@ function applyTemplateContextReplacements(sourceContent, replacements) {
   return output;
 }
 
-async function copyTemplateFile(
+async function renderTemplateFile(
   sourcePath,
-  targetPath,
   options,
   packageId,
   interpolationKey,
@@ -70,9 +66,7 @@ async function copyTemplateFile(
   if (templateContextReplacements) {
     renderedContent = applyTemplateContextReplacements(renderedContent, templateContextReplacements);
   }
-
-  await mkdir(path.dirname(targetPath), { recursive: true });
-  await writeFile(targetPath, renderedContent, "utf8");
+  return renderedContent;
 }
 
 async function resolveTemplateContextReplacementsForMutation({
@@ -111,7 +105,7 @@ async function resolveTemplateContextReplacementsForMutation({
 
   let moduleNamespace = null;
   try {
-    moduleNamespace = await import(`${pathToFileURL(absoluteEntrypointPath).href}?t=${Date.now()}_${Math.random()}`);
+    moduleNamespace = await importFreshModuleFromAbsolutePath(absoluteEntrypointPath);
   } catch (error) {
     throw createCliError(
       `Unable to load templateContext entrypoint ${entrypoint} for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
@@ -165,7 +159,7 @@ async function resolveTemplateContextReplacementsForMutation({
 
 export {
   applyTemplateContextReplacements,
-  copyTemplateFile,
   interpolateFileMutationRecord,
+  renderTemplateFile,
   resolveTemplateContextReplacementsForMutation
 };

package/src/server/cliRuntime/mutations/textMutations.js

@@ -118,25 +118,30 @@ async function applyTextMutations(packageEntry, appRoot, textMutations, options,
     const operation = String(mutation?.op || "").trim();
     if (operation === "upsert-env") {
       const relativeFile = String(mutation?.file || "").trim();
-      const key = String(mutation?.key || "").trim();
-      if (!relativeFile || !key) {
+      const rawKey = String(mutation?.key || "").trim();
+      if (!relativeFile || !rawKey) {
         throw createCliError(`Invalid upsert-env mutation in ${packageEntry.packageId}: "file" and "key" are required.`);
       }
 
+      const resolvedKey = interpolateOptionValue(rawKey, options, packageEntry.packageId, `${rawKey}.key`).trim();
+      if (!resolvedKey) {
+        throw createCliError(`Invalid upsert-env mutation in ${packageEntry.packageId}: resolved key is empty.`);
+      }
+
       const absoluteFile = path.join(appRoot, relativeFile);
       const previous = await readFileBufferIfExists(absoluteFile);
       const previousContent = previous.exists ? previous.buffer.toString("utf8") : "";
-      const resolvedValue = interpolateOptionValue(mutation?.value || "", options, packageEntry.packageId, key);
-      const upserted = upsertEnvValue(previousContent, key, resolvedValue);
+      const resolvedValue = interpolateOptionValue(mutation?.value || "", options, packageEntry.packageId, resolvedKey);
+      const upserted = upsertEnvValue(previousContent, resolvedKey, resolvedValue);
 
       await mkdir(path.dirname(absoluteFile), { recursive: true });
       await writeFile(absoluteFile, upserted.content, "utf8");
 
-      const recordKey = `${relativeFile}::${String(mutation?.id || key)}`;
+      const recordKey = `${relativeFile}::${String(mutation?.id || resolvedKey)}`;
       managedText[recordKey] = {
         file: relativeFile,
         op: "upsert-env",
-        key,
+        key: resolvedKey,
         value: resolvedValue,
         hadPrevious: upserted.hadPrevious,
         previousValue: upserted.previousValue,