@jskit-ai/jskit-cli 0.2.115 → 0.2.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.115",
+  "version": "0.2.116",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.110",
-    "@jskit-ai/kernel": "0.1.103",
-    "@jskit-ai/shell-web": "0.1.102",
+    "@jskit-ai/jskit-catalog": "0.1.111",
+    "@jskit-ai/kernel": "0.1.104",
+    "@jskit-ai/shell-web": "0.1.103",
     "@vue/compiler-sfc": "^3.5.29",
     "ts-morph": "^28.0.0"
   },

package/src/server/cliRuntime/descriptorValidation.js

@@ -61,6 +61,62 @@ function validateFileMutationShape(descriptor, descriptorPath) {
   }
 }
 
+function validateSourceMutationShape(descriptor, descriptorPath) {
+  const packageId = String(ensureObject(descriptor).packageId || "").trim() || "unknown-package";
+  const mutations = ensureObject(ensureObject(descriptor).mutations);
+  const sourceMutations = ensureArray(mutations.source);
+  const supportedOps = new Set([
+    "ensure-assignment",
+    "ensure-call",
+    "ensure-export-const",
+    "ensure-import"
+  ]);
+
+  for (const rawMutation of sourceMutations) {
+    const mutation = ensureObject(rawMutation);
+    const operation = String(mutation.op || "").trim();
+    const file = String(mutation.file || "").trim();
+    if (!supportedOps.has(operation)) {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: source mutation in ${packageId} has unsupported op "${operation}".`
+      );
+    }
+    if (!file) {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: source mutation in ${packageId} requires "file".`
+      );
+    }
+    if (operation === "ensure-import") {
+      const hasImportBinding =
+        String(mutation.defaultImport || "").trim() ||
+        String(mutation.namespaceImport || "").trim() ||
+        ensureArray(mutation.namedImports).length > 0;
+      if (!String(mutation.from || "").trim() || !hasImportBinding) {
+        throw createCliError(
+          `Invalid package descriptor at ${descriptorPath}: ensure-import in ${packageId} requires "from" and an import binding.`
+        );
+      }
+    }
+    if (operation === "ensure-call" && !String(mutation.callee || "").trim()) {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: ensure-call in ${packageId} requires "callee".`
+      );
+    }
+    if (operation === "ensure-assignment") {
+      if (!String(mutation.target || "").trim() || !String(mutation.value || "").trim()) {
+        throw createCliError(
+          `Invalid package descriptor at ${descriptorPath}: ensure-assignment in ${packageId} requires "target" and "value".`
+        );
+      }
+    }
+    if (operation === "ensure-export-const" && !String(mutation.name || "").trim()) {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: ensure-export-const in ${packageId} requires "name".`
+      );
+    }
+  }
+}
+
 function validateLifecycleHookSpec(spec = {}, descriptorPath, label = "lifecycle hook") {
   const normalized = ensureObject(spec);
   if (Object.keys(normalized).length < 1) {
@@ -133,6 +189,7 @@ function validatePackageDescriptorShape(descriptor, descriptorPath) {
   }
 
   validateFileMutationShape(normalized, descriptorPath);
+  validateSourceMutationShape(normalized, descriptorPath);
   const lifecycle = validateLifecycleShape(normalized, descriptorPath);
 
   return {
@@ -165,6 +222,7 @@ function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { ex
   }
 
   validateFileMutationShape(normalized, descriptorPath);
+  validateSourceMutationShape(normalized, descriptorPath);
   const lifecycle = validateLifecycleShape(normalized, descriptorPath);
 
   return {

package/src/server/cliRuntime/mutationApplication.js

@@ -8,3 +8,9 @@ export {
   partitionPreFileConfigTextMutations,
   resolvePositioningMutations
 } from "./mutations/textMutations.js";
+
+export {
+  applySourceMutations,
+  partitionPreFileConfigSourceMutations,
+  resolvePositioningSourceMutations
+} from "./mutations/sourceMutations.js";

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

@@ -0,0 +1,458 @@
+import {
+  mkdir,
+  writeFile
+} from "node:fs/promises";
+import path from "node:path";
+import {
+  Project,
+  SyntaxKind
+} from "ts-morph";
+import { createCliError } from "../../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject
+} from "../../shared/collectionUtils.js";
+import {
+  interpolateOptionValue
+} from "../../shared/optionInterpolation.js";
+import {
+  normalizeMutationWhen,
+  shouldApplyMutationWhen
+} from "../mutationWhen.js";
+import {
+  loadMutationWhenConfigContext,
+  normalizeRelativePath,
+  readFileBufferIfExists
+} from "../ioAndMigrations.js";
+import { normalizeMutationRelativeFilePath } from "./mutationPathUtils.js";
+
+const PRE_FILE_CONFIG_MUTATION_TARGETS = new Set([
+  "config/public.js",
+  "config/server.js"
+]);
+
+function createSourceFile(relativeFile, sourceText) {
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    skipAddingFilesFromTsConfig: true
+  });
+  return project.createSourceFile(`/${relativeFile}`, sourceText, { overwrite: true });
+}
+
+function normalizeSourceText(value = "") {
+  return String(value || "").replace(/\r\n/g, "\n");
+}
+
+function insertText(sourceText, index, text) {
+  return `${sourceText.slice(0, index)}${text}${sourceText.slice(index)}`;
+}
+
+function appendBlock(sourceText, block) {
+  const normalized = normalizeSourceText(sourceText);
+  const trimmed = normalized.replace(/\s*$/u, "");
+  if (!trimmed) {
+    return `${block.trim()}\n`;
+  }
+  return `${trimmed}\n\n${block.trim()}\n`;
+}
+
+function renderImportMutation(mutation, options, packageId, mutationId) {
+  const defaultImport = interpolateOptionValue(
+    mutation.defaultImport || "",
+    options,
+    packageId,
+    `${mutationId}.defaultImport`
+  ).trim();
+  const namespaceImport = interpolateOptionValue(
+    mutation.namespaceImport || "",
+    options,
+    packageId,
+    `${mutationId}.namespaceImport`
+  ).trim();
+  const namedImports = ensureArray(mutation.namedImports)
+    .map((entry, index) =>
+      interpolateOptionValue(entry, options, packageId, `${mutationId}.namedImports.${index}`).trim()
+    )
+    .filter(Boolean);
+  const from = interpolateOptionValue(mutation.from || "", options, packageId, `${mutationId}.from`).trim();
+
+  if (!from) {
+    throw createCliError(`Invalid ensure-import source mutation in ${packageId}: "from" is required.`);
+  }
+  if (!defaultImport && !namespaceImport && namedImports.length < 1) {
+    throw createCliError(
+      `Invalid ensure-import source mutation in ${packageId}: defaultImport, namespaceImport, or namedImports is required.`
+    );
+  }
+
+  let importClause = "";
+  if (namespaceImport) {
+    importClause = `* as ${namespaceImport}`;
+  } else {
+    const namedClause = namedImports.length > 0 ? `{ ${namedImports.join(", ")} }` : "";
+    importClause = [defaultImport, namedClause].filter(Boolean).join(", ");
+  }
+
+  return {
+    defaultImport,
+    namespaceImport,
+    namedImports,
+    from,
+    statement: `import ${importClause} from "${from}";`
+  };
+}
+
+function sourceAlreadyHasImport(sourceFile, rendered) {
+  return sourceFile.getImportDeclarations().some((importDeclaration) => {
+    if (importDeclaration.getModuleSpecifierValue() !== rendered.from) {
+      return false;
+    }
+
+    const defaultImport = importDeclaration.getDefaultImport()?.getText() || "";
+    if (rendered.defaultImport && defaultImport !== rendered.defaultImport) {
+      return false;
+    }
+
+    const namespaceImport = importDeclaration.getNamespaceImport()?.getText() || "";
+    if (rendered.namespaceImport && namespaceImport !== rendered.namespaceImport) {
+      return false;
+    }
+
+    const existingNamedImports = new Set(
+      importDeclaration.getNamedImports().map((namedImport) => namedImport.getName())
+    );
+    return rendered.namedImports.every((name) => existingNamedImports.has(name));
+  });
+}
+
+function ensureImport(sourceText, relativeFile, mutation, options, packageId, mutationId) {
+  const sourceFile = createSourceFile(relativeFile, sourceText);
+  const rendered = renderImportMutation(mutation, options, packageId, mutationId);
+
+  if (sourceAlreadyHasImport(sourceFile, rendered)) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  const importDeclarations = sourceFile.getImportDeclarations();
+  if (importDeclarations.length > 0) {
+    const lastImport = importDeclarations[importDeclarations.length - 1];
+    return {
+      changed: true,
+      content: insertText(sourceText, lastImport.getEnd(), `\n${rendered.statement}`)
+    };
+  }
+
+  const normalized = normalizeSourceText(sourceText);
+  return {
+    changed: true,
+    content: normalized.trim() ? `${rendered.statement}\n\n${normalized}` : `${rendered.statement}\n`
+  };
+}
+
+function normalizeSourceArg(value = "") {
+  const raw = String(value || "").trim();
+  const quotedMatch = raw.match(/^(['"])(.*)\1$/u);
+  if (!quotedMatch) {
+    return raw;
+  }
+  try {
+    return JSON.parse(`"${quotedMatch[2].replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+  } catch {
+    return quotedMatch[2];
+  }
+}
+
+function callExpressionMatches(callExpression, callee, expectedArgs, uniqueArgIndex) {
+  if (callExpression.getExpression().getText() !== callee) {
+    return false;
+  }
+
+  const args = callExpression.getArguments();
+  if (uniqueArgIndex < 0 || uniqueArgIndex >= expectedArgs.length) {
+    return true;
+  }
+  if (uniqueArgIndex >= args.length) {
+    return false;
+  }
+
+  return normalizeSourceArg(args[uniqueArgIndex].getText()) === normalizeSourceArg(expectedArgs[uniqueArgIndex]);
+}
+
+function renderCallMutation(mutation, options, packageId, mutationId) {
+  const callee = interpolateOptionValue(mutation.callee || "", options, packageId, `${mutationId}.callee`).trim();
+  const args = ensureArray(mutation.args)
+    .map((entry, index) => interpolateOptionValue(entry, options, packageId, `${mutationId}.args.${index}`).trim())
+    .filter(Boolean);
+
+  if (!callee) {
+    throw createCliError(`Invalid ensure-call source mutation in ${packageId}: "callee" is required.`);
+  }
+
+  return {
+    callee,
+    args,
+    statement: `${callee}(${args.join(", ")});`
+  };
+}
+
+function ensureCall(sourceText, relativeFile, mutation, options, packageId, mutationId) {
+  const sourceFile = createSourceFile(relativeFile, sourceText);
+  const rendered = renderCallMutation(mutation, options, packageId, mutationId);
+  const uniqueArgIndex = Number.isInteger(mutation.uniqueArgIndex)
+    ? mutation.uniqueArgIndex
+    : 0;
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+  if (callExpressions.some((callExpression) =>
+    callExpressionMatches(callExpression, rendered.callee, rendered.args, uniqueArgIndex)
+  )) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  const beforeClass = String(mutation.beforeClass || "").trim();
+  if (beforeClass) {
+    const classDeclaration = sourceFile.getClass(beforeClass);
+    if (!classDeclaration) {
+      throw createCliError(
+        `Invalid ensure-call source mutation in ${packageId}: beforeClass "${beforeClass}" was not found in ${relativeFile}.`
+      );
+    }
+    return {
+      changed: true,
+      content: insertText(sourceText, classDeclaration.getStart(), `${rendered.statement}\n\n`)
+    };
+  }
+
+  return {
+    changed: true,
+    content: appendBlock(sourceText, rendered.statement)
+  };
+}
+
+function sourceHasAssignmentToTarget(sourceFile, target) {
+  return sourceFile
+    .getDescendantsOfKind(SyntaxKind.BinaryExpression)
+    .some((expression) => expression.getLeft().getText() === target);
+}
+
+function renderAssignmentStatement(target, value) {
+  return `${target} = ${value};`;
+}
+
+function ensureAssignment(sourceText, relativeFile, mutation, options, packageId, mutationId) {
+  const sourceFile = createSourceFile(relativeFile, sourceText);
+  const target = interpolateOptionValue(mutation.target || "", options, packageId, `${mutationId}.target`).trim();
+  const value = interpolateOptionValue(mutation.value || "", options, packageId, `${mutationId}.value`).trim();
+  if (!target) {
+    throw createCliError(`Invalid ensure-assignment source mutation in ${packageId}: "target" is required.`);
+  }
+  if (!value) {
+    throw createCliError(`Invalid ensure-assignment source mutation in ${packageId}: "value" is required.`);
+  }
+
+  const statements = [];
+  for (const rawEnsureTarget of ensureArray(mutation.ensureObjects)) {
+    const ensureTarget = interpolateOptionValue(
+      rawEnsureTarget,
+      options,
+      packageId,
+      `${mutationId}.ensureObjects`
+    ).trim();
+    if (!ensureTarget || sourceHasAssignmentToTarget(sourceFile, ensureTarget)) {
+      continue;
+    }
+    statements.push(`${ensureTarget} ||= {};`);
+  }
+
+  if (!sourceHasAssignmentToTarget(sourceFile, target)) {
+    statements.push(renderAssignmentStatement(target, value));
+  }
+
+  if (statements.length < 1) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  return {
+    changed: true,
+    content: appendBlock(sourceText, statements.join("\n"))
+  };
+}
+
+function ensureExportConst(sourceText, relativeFile, mutation, options, packageId, mutationId) {
+  const sourceFile = createSourceFile(relativeFile, sourceText);
+  const name = interpolateOptionValue(mutation.name || "", options, packageId, `${mutationId}.name`).trim();
+  const value = interpolateOptionValue(mutation.value || "{}", options, packageId, `${mutationId}.value`).trim() || "{}";
+  if (!name) {
+    throw createCliError(`Invalid ensure-export-const source mutation in ${packageId}: "name" is required.`);
+  }
+
+  if (sourceFile.getVariableDeclaration(name)) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  const statement = `export const ${name} = ${value};`;
+  const importDeclarations = sourceFile.getImportDeclarations();
+  if (importDeclarations.length > 0) {
+    const lastImport = importDeclarations[importDeclarations.length - 1];
+    return {
+      changed: true,
+      content: insertText(sourceText, lastImport.getEnd(), `\n\n${statement}`)
+    };
+  }
+
+  const normalized = normalizeSourceText(sourceText);
+  return {
+    changed: true,
+    content: normalized.trim() ? `${statement}\n\n${normalized}` : `${statement}\n`
+  };
+}
+
+function applySourceMutationToContent(sourceText, relativeFile, mutation, options, packageId) {
+  const operation = String(mutation?.op || "").trim();
+  const mutationId = String(mutation?.id || "").trim() || operation || "source";
+
+  if (operation === "ensure-import") {
+    return ensureImport(sourceText, relativeFile, mutation, options, packageId, mutationId);
+  }
+  if (operation === "ensure-call") {
+    return ensureCall(sourceText, relativeFile, mutation, options, packageId, mutationId);
+  }
+  if (operation === "ensure-assignment") {
+    return ensureAssignment(sourceText, relativeFile, mutation, options, packageId, mutationId);
+  }
+  if (operation === "ensure-export-const") {
+    return ensureExportConst(sourceText, relativeFile, mutation, options, packageId, mutationId);
+  }
+
+  throw createCliError(`Unsupported source mutation op "${operation}" in ${packageId}.`);
+}
+
+function createManagedSourceRecord(relativeFile, mutation) {
+  const mutationId = String(mutation?.id || "").trim() || String(mutation?.op || "source").trim();
+  const recordKey = `${relativeFile}::${mutationId}`;
+  return {
+    recordKey,
+    record: {
+      file: relativeFile,
+      op: String(mutation?.op || "").trim(),
+      id: String(mutation?.id || ""),
+      reason: String(mutation?.reason || ""),
+      category: String(mutation?.category || "")
+    }
+  };
+}
+
+async function applySourceMutations(
+  packageEntry,
+  appRoot,
+  sourceMutations,
+  options,
+  managedSource,
+  touchedFiles,
+  { dryRun = false } = {}
+) {
+  for (const mutation of sourceMutations) {
+    const when = normalizeMutationWhen(mutation?.when);
+    const configContext = when?.config ? await loadMutationWhenConfigContext(appRoot) : {};
+    if (
+      !shouldApplyMutationWhen(when, {
+        options,
+        configContext,
+        packageId: packageEntry.packageId,
+        mutationContext: "source mutation"
+      })
+    ) {
+      continue;
+    }
+
+    const relativeFile = normalizeMutationRelativeFilePath(mutation?.file || "");
+    if (!relativeFile) {
+      throw createCliError(`Invalid source mutation in ${packageEntry.packageId}: "file" is required.`);
+    }
+
+    const absoluteFile = path.join(appRoot, relativeFile);
+    const previous = await readFileBufferIfExists(absoluteFile);
+    const previousContent = previous.exists ? previous.buffer.toString("utf8") : "";
+    const applied = applySourceMutationToContent(
+      normalizeSourceText(previousContent),
+      relativeFile,
+      mutation,
+      options,
+      packageEntry.packageId
+    );
+    const {
+      recordKey,
+      record
+    } = createManagedSourceRecord(relativeFile, mutation);
+    if (!applied.changed) {
+      managedSource[recordKey] = record;
+      continue;
+    }
+
+    if (!dryRun) {
+      await mkdir(path.dirname(absoluteFile), { recursive: true });
+      await writeFile(absoluteFile, applied.content, "utf8");
+    }
+
+    managedSource[recordKey] = record;
+    touchedFiles.add(normalizeRelativePath(appRoot, absoluteFile));
+  }
+}
+
+function isPositioningSourceMutation(value = {}) {
+  const mutation = ensureObject(value);
+  const operation = String(mutation.op || "").trim();
+  if (operation !== "ensure-call") {
+    return false;
+  }
+  return normalizeMutationRelativeFilePath(mutation.file) === "src/placement.js";
+}
+
+function isPreFileConfigSourceMutation(value = {}) {
+  const mutation = ensureObject(value);
+  const operation = String(mutation.op || "").trim();
+  if (operation !== "ensure-assignment" && operation !== "ensure-export-const") {
+    return false;
+  }
+  return PRE_FILE_CONFIG_MUTATION_TARGETS.has(normalizeMutationRelativeFilePath(mutation.file));
+}
+
+function partitionPreFileConfigSourceMutations(sourceMutations = []) {
+  const preFileSourceMutations = [];
+  const postFileSourceMutations = [];
+
+  for (const mutation of ensureArray(sourceMutations)) {
+    if (isPreFileConfigSourceMutation(mutation)) {
+      preFileSourceMutations.push(mutation);
+      continue;
+    }
+    postFileSourceMutations.push(mutation);
+  }
+
+  return {
+    preFileSourceMutations,
+    postFileSourceMutations
+  };
+}
+
+function resolvePositioningSourceMutations(descriptorMutations = {}) {
+  const mutations = ensureObject(descriptorMutations);
+  return ensureArray(mutations.source).filter((mutationValue) => isPositioningSourceMutation(mutationValue));
+}
+
+export {
+  applySourceMutations,
+  partitionPreFileConfigSourceMutations,
+  resolvePositioningSourceMutations
+};

package/src/server/cliRuntime/packageInstallFlow.js

@@ -36,10 +36,13 @@ import {
 } from "./packageTemplateResolution.js";
 import {
   applyFileMutations,
+  applySourceMutations,
   applyTextMutations,
+  partitionPreFileConfigSourceMutations,
   partitionPreFileConfigTextMutations,
   prepareFileMutations,
-  resolvePositioningMutations
+  resolvePositioningMutations,
+  resolvePositioningSourceMutations
 } from "./mutationApplication.js";
 function createManagedRecordBase(packageEntry, options) {
   const sourceRecord = {
@@ -61,6 +64,7 @@ function createManagedRecordBase(packageEntry, options) {
         scripts: {}
       },
       text: {},
+      source: {},
       vite: {},
       files: [],
       migrations: []
@@ -172,6 +176,7 @@ async function applyPackagePositioning({
       scripts: cloneManagedMap(existingPackageJsonManaged.scripts)
     },
     text: cloneManagedMap(existingManaged.text),
+    source: cloneManagedMap(existingManaged.source),
     vite: cloneManagedMap(existingManaged.vite),
     files: cloneManagedArray(existingManaged.files),
     migrations: cloneManagedArray(existingManaged.migrations)
@@ -188,8 +193,10 @@ async function applyPackagePositioning({
 
   const mutations = ensureObject(packageEntry.descriptor.mutations);
   const positioningMutations = resolvePositioningMutations(mutations);
+  const positioningSourceMutations = resolvePositioningSourceMutations(mutations);
   const appliedManagedFiles = [];
   const appliedManagedText = {};
+  const appliedManagedSource = {};
   const preparedFileMutations = await prepareFileMutations(
     packageEntryForMutations,
     packageOptions,
@@ -225,6 +232,19 @@ async function applyPackagePositioning({
       }
     );
   }
+  if (positioningSourceMutations.length > 0) {
+    await applySourceMutations(
+      packageEntryForMutations,
+      appRoot,
+      positioningSourceMutations,
+      packageOptions,
+      appliedManagedSource,
+      touchedFiles,
+      {
+        dryRun
+      }
+    );
+  }
 
   if (appliedManagedFiles.length > 0) {
     const replacedPaths = new Set(
@@ -245,6 +265,12 @@ async function applyPackagePositioning({
       ...appliedManagedText
     };
   }
+  if (Object.keys(appliedManagedSource).length > 0) {
+    nextManaged.source = {
+      ...nextManaged.source,
+      ...appliedManagedSource
+    };
+  }
 
   const managedRecord = {
     ...existingInstall,
@@ -283,6 +309,7 @@ async function applyPackageMigrationsOnly({
       scripts: cloneManagedMap(existingPackageJsonManaged.scripts)
     },
     text: cloneManagedMap(existingManaged.text),
+    source: cloneManagedMap(existingManaged.source),
     vite: cloneManagedMap(existingManaged.vite),
     files: cloneManagedArray(existingManaged.files),
     migrations: cloneManagedArray(existingManaged.migrations)
@@ -363,6 +390,7 @@ async function applyPackageInstall({
   const mutations = ensureObject(packageEntry.descriptor.mutations);
   const fileMutations = ensureArray(mutations.files);
   const textMutations = ensureArray(mutations.text);
+  const sourceMutations = ensureArray(mutations.source);
   const hasSurfaceTargetedFileMutations = fileMutations.some((mutationValue) =>
     Boolean(normalizeFileMutationRecord(mutationValue).toSurface)
   );
@@ -375,6 +403,15 @@ async function applyPackageInstall({
         preFileTextMutations: [],
         postFileTextMutations: textMutations
       };
+  const {
+    preFileSourceMutations,
+    postFileSourceMutations
+  } = hasSurfaceTargetedFileMutations
+    ? partitionPreFileConfigSourceMutations(sourceMutations)
+    : {
+        preFileSourceMutations: [],
+        postFileSourceMutations: sourceMutations
+      };
   const templateRoot = await resolvePackageTemplateRoot({
     packageEntry,
     appRoot,
@@ -403,6 +440,19 @@ async function applyPackageInstall({
       }
     );
   }
+  if (preFileSourceMutations.length > 0) {
+    await applySourceMutations(
+      packageEntryForMutations,
+      appRoot,
+      preFileSourceMutations,
+      packageOptions,
+      managedRecord.managed.source,
+      touchedFiles,
+      {
+        dryRun
+      }
+    );
+  }
 
   const preparedFileMutations = await prepareFileMutations(
     packageEntryForMutations,
@@ -576,6 +626,18 @@ async function applyPackageInstall({
     }
   );
 
+  await applySourceMutations(
+    packageEntryForMutations,
+    appRoot,
+    postFileSourceMutations,
+    packageOptions,
+    managedRecord.managed.source,
+    touchedFiles,
+    {
+      dryRun
+    }
+  );
+
   await applyViteMutations(
     packageEntryForMutations,
     appRoot,

package/src/server/commandHandlers/app.js

@@ -10,6 +10,7 @@ import {
 } from "./appCommandCatalog.js";
 import { runAppAdoptManagedScriptsCommand } from "./appCommands/adoptManagedScripts.js";
 import { runAppLinkLocalPackagesCommand } from "./appCommands/linkLocalPackages.js";
+import { runAppMigrateSourceMutationsCommand } from "./appCommands/migrateSourceMutations.js";
 import { runAppPreparePreviewUserCommand } from "./appCommands/preparePreviewUser.js";
 import { runAppReleaseCommand } from "./appCommands/release.js";
 import { runAppUpdatePackagesCommand } from "./appCommands/updatePackages.js";
@@ -152,6 +153,9 @@ function createAppCommands(ctx = {}) {
     if (definition.name === "adopt-managed-scripts") {
       return runAppAdoptManagedScriptsCommand(ctx, { appRoot, options, stdout, stderr });
     }
+    if (definition.name === "migrate-source-mutations") {
+      return runAppMigrateSourceMutationsCommand(ctx, { appRoot, options, stdout, stderr });
+    }
     if (definition.name === "prepare-preview-user") {
       return runAppPreparePreviewUserCommand(ctx, { appRoot, options, stdout, stderr });
     }

package/src/server/commandHandlers/appCommandCatalog.js

@@ -188,6 +188,22 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
       "Customized script values are reported and left alone unless --force is used.",
       "This command is for apps that still carry copied JSKIT maintenance scripts."
     ])
+  }),
+  "migrate-source-mutations": Object.freeze({
+    name: "migrate-source-mutations",
+    summary: "Rewrite legacy append-text source edits into the current source-mutation layout.",
+    usage: "jskit app migrate-source-mutations [--dry-run]",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--dry-run",
+        description: "Preview source rewrites without writing app files."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Moves legacy MainClientProvider component registrations before the MainClientProvider class.",
+      "Leaves apps unchanged when they already use the current source-mutation layout.",
+      "Run this after updating JSKIT packages in older apps that were installed before source mutations."
+    ])
   })
 });
 
@@ -217,6 +233,7 @@ function buildAppCommandOptionMeta(subcommandName = "") {
   if (
     definition.name === "update-packages" ||
     definition.name === "adopt-managed-scripts" ||
+    definition.name === "migrate-source-mutations" ||
     definition.name === "release"
   ) {
     optionMeta["dry-run"] = { inputType: "flag" };

package/src/server/commandHandlers/appCommands/migrateSourceMutations.js

@@ -0,0 +1,538 @@
+import { readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  Node,
+  Project
+} from "ts-morph";
+import { fileExists } from "./shared.js";
+
+const MAIN_CLIENT_PROVIDER_FILE = "packages/main/src/client/providers/MainClientProvider.js";
+const CRUD_FORM_FIELD_ARRAY_NAMES = Object.freeze([
+  "UI_CREATE_FORM_FIELDS",
+  "UI_EDIT_FORM_FIELDS"
+]);
+const CRUD_FORM_FIELD_MARKERS_BY_ARRAY = Object.freeze({
+  UI_CREATE_FORM_FIELDS: "// jskit:crud-ui-form-fields:new",
+  UI_EDIT_FORM_FIELDS: "// jskit:crud-ui-form-fields:edit"
+});
+const SOURCE_FILE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".vue"]);
+const SOURCE_SCAN_SKIP_DIRS = new Set([
+  ".git",
+  ".jskit",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules"
+]);
+
+function createSourceFile(sourceText = "") {
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    skipAddingFilesFromTsConfig: true
+  });
+  return project.createSourceFile("/MainClientProvider.js", String(sourceText || ""), { overwrite: true });
+}
+
+function readStringLiteralValue(node) {
+  if (!node) {
+    return "";
+  }
+  if (Node.isStringLiteral(node) || Node.isNoSubstitutionTemplateLiteral(node)) {
+    return node.getLiteralText();
+  }
+  return "";
+}
+
+function readRegisterMainClientComponentToken(statement) {
+  if (!Node.isExpressionStatement(statement)) {
+    return "";
+  }
+  const expression = statement.getExpression();
+  if (!Node.isCallExpression(expression)) {
+    return "";
+  }
+  if (expression.getExpression().getText() !== "registerMainClientComponent") {
+    return "";
+  }
+  return readStringLiteralValue(expression.getArguments()[0]);
+}
+
+function buildMainClientProviderMigration(sourceText = "") {
+  const sourceFile = createSourceFile(sourceText);
+  const classDeclaration = sourceFile.getClass("MainClientProvider");
+  if (!classDeclaration) {
+    return {
+      changed: false,
+      content: sourceText,
+      moved: 0,
+      deduped: 0,
+      reason: "missing-class"
+    };
+  }
+
+  const classStart = classDeclaration.getStart();
+  const registerRecords = sourceFile
+    .getStatements()
+    .map((statement, index) => ({
+      statement,
+      index,
+      token: readRegisterMainClientComponentToken(statement),
+      text: statement.getText(),
+      beforeClass: statement.getStart() < classStart
+    }))
+    .filter((record) => record.token);
+
+  const movedRecords = registerRecords.filter((record) => !record.beforeClass);
+  const seenTokens = new Set();
+  const desiredRecords = [];
+  const duplicates = [];
+  for (const record of [
+    ...registerRecords.filter((entry) => entry.beforeClass),
+    ...movedRecords
+  ]) {
+    if (seenTokens.has(record.token)) {
+      duplicates.push(record);
+      continue;
+    }
+    seenTokens.add(record.token);
+    desiredRecords.push(record);
+  }
+
+  if (movedRecords.length < 1 && duplicates.length < 1) {
+    return {
+      changed: false,
+      content: sourceText,
+      moved: 0,
+      deduped: 0,
+      reason: "already-current"
+    };
+  }
+
+  for (const record of [...registerRecords].sort((left, right) => right.index - left.index)) {
+    record.statement.remove();
+  }
+
+  const nextClassIndex = sourceFile.getStatements().findIndex((statement) =>
+    Node.isClassDeclaration(statement) && statement.getName() === "MainClientProvider"
+  );
+  if (nextClassIndex < 0) {
+    return {
+      changed: false,
+      content: sourceText,
+      moved: 0,
+      deduped: 0,
+      reason: "missing-class"
+    };
+  }
+
+  sourceFile.insertStatements(nextClassIndex, desiredRecords.map((record) => record.text));
+  return {
+    changed: true,
+    content: sourceFile.getFullText(),
+    moved: movedRecords.length,
+    deduped: duplicates.length,
+    reason: "rewritten"
+  };
+}
+
+function escapeRegExp(value = "") {
+  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function findMatchingDelimiter(sourceText = "", openIndex = -1, openChar = "(", closeChar = ")") {
+  const source = String(sourceText || "");
+  if (openIndex < 0 || source[openIndex] !== openChar) {
+    return -1;
+  }
+
+  let depth = 0;
+  let quote = "";
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let index = openIndex; index < source.length; index += 1) {
+    const char = source[index];
+    const nextChar = source[index + 1] || "";
+    const previousChar = source[index - 1] || "";
+
+    if (inLineComment) {
+      if (char === "\n") {
+        inLineComment = false;
+      }
+      continue;
+    }
+    if (inBlockComment) {
+      if (char === "*" && nextChar === "/") {
+        inBlockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (char === "\\" && quote !== "`") {
+        index += 1;
+        continue;
+      }
+      if (char === quote && previousChar !== "\\") {
+        quote = "";
+      }
+      continue;
+    }
+
+    if (char === "/" && nextChar === "/") {
+      inLineComment = true;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && nextChar === "*") {
+      inBlockComment = true;
+      index += 1;
+      continue;
+    }
+    if (char === "\"" || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === openChar) {
+      depth += 1;
+      continue;
+    }
+    if (char === closeChar) {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+
+  return -1;
+}
+
+function readLineIndent(sourceText = "", index = 0) {
+  const source = String(sourceText || "");
+  const lineStart = source.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+  const linePrefix = source.slice(lineStart, index);
+  const match = linePrefix.match(/^[ \t]*/);
+  return match?.[0] || "";
+}
+
+function readFormFieldKey(sourceText = "") {
+  const match = String(sourceText || "").match(/(?:^|[,{]\s*)(?:"key"|key)\s*:\s*["']([^"']+)["']/);
+  return String(match?.[1] || "");
+}
+
+function readFormFieldKeys(sourceText = "") {
+  const keys = new Set();
+  const keyPattern = /(?:^|[,{]\s*)(?:"key"|key)\s*:\s*["']([^"']+)["']/g;
+  let match = null;
+  while ((match = keyPattern.exec(String(sourceText || ""))) != null) {
+    if (match[1]) {
+      keys.add(String(match[1]));
+    }
+  }
+  return keys;
+}
+
+function formatArrayEntry(entrySource = "", indent = "  ") {
+  return String(entrySource || "")
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => `${indent}${line}`)
+    .join("\n");
+}
+
+function findFormFieldArrayDeclaration(sourceText = "", arrayName = "") {
+  const source = String(sourceText || "");
+  const declarationPattern = new RegExp(`\\b(?:const|let)\\s+${escapeRegExp(arrayName)}\\s*=\\s*\\[`, "g");
+  const match = declarationPattern.exec(source);
+  if (!match) {
+    return null;
+  }
+
+  const openIndex = source.indexOf("[", match.index);
+  const closeIndex = findMatchingDelimiter(source, openIndex, "[", "]");
+  if (closeIndex < 0) {
+    return null;
+  }
+
+  return {
+    openIndex,
+    closeIndex,
+    indent: readLineIndent(source, match.index),
+    content: source.slice(openIndex + 1, closeIndex)
+  };
+}
+
+function findLineRangeContaining(sourceText = "", searchText = "", { afterIndex = -1 } = {}) {
+  const source = String(sourceText || "");
+  const target = String(searchText || "");
+  if (!target) {
+    return null;
+  }
+
+  const startSearchIndex = Number.isInteger(afterIndex) && afterIndex >= 0 ? afterIndex : 0;
+  const matchIndex = source.indexOf(target, startSearchIndex);
+  if (matchIndex < 0) {
+    return null;
+  }
+
+  const lineStart = source.lastIndexOf("\n", Math.max(0, matchIndex - 1)) + 1;
+  let lineEnd = source.indexOf("\n", matchIndex);
+  if (lineEnd < 0) {
+    lineEnd = source.length;
+  } else {
+    lineEnd += 1;
+  }
+
+  return {
+    startIndex: lineStart,
+    endIndex: lineEnd,
+    text: source.slice(lineStart, lineEnd)
+  };
+}
+
+function findFormFieldPushCalls(sourceText = "", arrayName = "") {
+  const source = String(sourceText || "");
+  const callPattern = new RegExp(`^[ \\t]*${escapeRegExp(arrayName)}\\.push\\s*\\(`, "gm");
+  const calls = [];
+  let match = null;
+  while ((match = callPattern.exec(source)) != null) {
+    const openIndex = source.indexOf("(", match.index);
+    const closeIndex = findMatchingDelimiter(source, openIndex, "(", ")");
+    if (closeIndex < 0) {
+      continue;
+    }
+
+    let endIndex = closeIndex + 1;
+    while (endIndex < source.length && /[ \t]/.test(source[endIndex])) {
+      endIndex += 1;
+    }
+    if (source[endIndex] === ";") {
+      endIndex += 1;
+    }
+    while (endIndex < source.length && /[ \t]/.test(source[endIndex])) {
+      endIndex += 1;
+    }
+    if (source.slice(endIndex, endIndex + 2) === "\r\n") {
+      endIndex += 2;
+    } else if (source[endIndex] === "\n") {
+      endIndex += 1;
+    }
+
+    const argumentSource = source.slice(openIndex + 1, closeIndex).trim();
+    if (!argumentSource.startsWith("{") || !argumentSource.endsWith("}")) {
+      continue;
+    }
+
+    calls.push({
+      startIndex: match.index,
+      endIndex,
+      argumentSource,
+      key: readFormFieldKey(argumentSource)
+    });
+  }
+
+  return calls;
+}
+
+function buildArrayContentWithAddedEntries(existingContent = "", entries = [], indent = "", { marker = "" } = {}) {
+  const entriesBlock = entries
+    .map((entry) => formatArrayEntry(entry, `${indent}  `))
+    .join(",\n");
+  const markerLine = String(marker || "").trim() ? `${indent}  ${String(marker || "").trim()}` : "";
+  const normalizedExistingContent = markerLine
+    ? String(existingContent || "").replace(new RegExp(`^[ \\t]*${escapeRegExp(marker)}[ \\t]*\\r?\\n?`, "m"), "")
+    : String(existingContent || "");
+  if (!entriesBlock && !markerLine) {
+    return normalizedExistingContent;
+  }
+
+  const trimmedExisting = normalizedExistingContent.trim();
+  if (!trimmedExisting) {
+    const lines = [entriesBlock, markerLine].filter(Boolean);
+    return `\n${lines.join("\n")}\n${indent}`;
+  }
+
+  const existingWithoutTrailingWhitespace = normalizedExistingContent.trimEnd();
+  const existingWithComma = existingWithoutTrailingWhitespace.endsWith(",")
+    ? existingWithoutTrailingWhitespace
+    : `${existingWithoutTrailingWhitespace},`;
+  const appendedLines = [entriesBlock, markerLine].filter(Boolean).join("\n");
+  return `${existingWithComma}\n${appendedLines}\n${indent}`;
+}
+
+function applyTextReplacements(sourceText = "", replacements = []) {
+  let content = String(sourceText || "");
+  for (const replacement of [...replacements].sort((left, right) => right.start - left.start)) {
+    content = `${content.slice(0, replacement.start)}${replacement.text}${content.slice(replacement.end)}`;
+  }
+  return content;
+}
+
+function buildCrudFormFieldPushMigration(sourceText = "") {
+  const source = String(sourceText || "");
+  if (!source.includes("UI_")) {
+    return {
+      changed: false,
+      content: source,
+      folded: 0,
+      movedMarkers: 0,
+      reason: "no-form-field-pushes"
+    };
+  }
+
+  const replacements = [];
+  let folded = 0;
+  let movedMarkers = 0;
+  for (const arrayName of CRUD_FORM_FIELD_ARRAY_NAMES) {
+    const declaration = findFormFieldArrayDeclaration(source, arrayName);
+    const calls = findFormFieldPushCalls(source, arrayName);
+    const marker = CRUD_FORM_FIELD_MARKERS_BY_ARRAY[arrayName] || "";
+    const markerInArray = marker ? declaration?.content?.includes(marker) === true : true;
+    const markerLineRange = marker && !markerInArray && declaration
+      ? findLineRangeContaining(source, marker, { afterIndex: declaration.closeIndex })
+      : null;
+    if (!declaration || (calls.length < 1 && !markerLineRange)) {
+      continue;
+    }
+
+    const knownKeys = readFormFieldKeys(declaration.content);
+    const entriesToAdd = [];
+    for (const call of calls) {
+      const callKey = call.key;
+      if (callKey && knownKeys.has(callKey)) {
+        replacements.push({ start: call.startIndex, end: call.endIndex, text: "" });
+        folded += 1;
+        continue;
+      }
+      if (callKey) {
+        knownKeys.add(callKey);
+      }
+      entriesToAdd.push(call.argumentSource);
+      replacements.push({ start: call.startIndex, end: call.endIndex, text: "" });
+      folded += 1;
+    }
+
+    if (markerLineRange) {
+      replacements.push({ start: markerLineRange.startIndex, end: markerLineRange.endIndex, text: "" });
+      movedMarkers += 1;
+    }
+
+    if (entriesToAdd.length > 0 || markerLineRange) {
+      const shouldAddMarker = marker && !markerInArray;
+      replacements.push({
+        start: declaration.openIndex + 1,
+        end: declaration.closeIndex,
+        text: buildArrayContentWithAddedEntries(declaration.content, entriesToAdd, declaration.indent, {
+          marker: shouldAddMarker ? marker : ""
+        })
+      });
+    }
+  }
+
+  if (folded < 1 && movedMarkers < 1) {
+    return {
+      changed: false,
+      content: source,
+      folded: 0,
+      movedMarkers: 0,
+      reason: "no-foldable-form-field-pushes"
+    };
+  }
+
+  return {
+    changed: true,
+    content: applyTextReplacements(source, replacements),
+    folded,
+    movedMarkers,
+    reason: "rewritten"
+  };
+}
+
+async function collectCrudFormFieldCandidateFiles(appRoot = "") {
+  const pagesRoot = path.join(appRoot, "src", "pages");
+  if (!(await fileExists(pagesRoot))) {
+    return [];
+  }
+
+  const files = [];
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || SOURCE_SCAN_SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      const absolutePath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+        continue;
+      }
+      if (!entry.isFile() || !SOURCE_FILE_EXTENSIONS.has(path.extname(entry.name))) {
+        continue;
+      }
+      files.push(absolutePath);
+    }
+  }
+
+  await visit(pagesRoot);
+  return files.sort();
+}
+
+async function runAppMigrateSourceMutationsCommand(_ctx = {}, { appRoot = "", options = {}, stdout }) {
+  const dryRun = options?.dryRun === true;
+  let changedCount = 0;
+  const absolutePath = path.join(appRoot, MAIN_CLIENT_PROVIDER_FILE);
+  if (await fileExists(absolutePath)) {
+    const previousContent = await readFile(absolutePath, "utf8");
+    const migrated = buildMainClientProviderMigration(previousContent);
+    if (migrated.changed) {
+      if (!dryRun) {
+        await writeFile(absolutePath, migrated.content, "utf8");
+      }
+
+      changedCount += 1;
+      const action = dryRun ? "would rewrite" : "rewrote";
+      const movedSuffix = migrated.moved === 1 ? "1 component registration" : `${migrated.moved} component registrations`;
+      const dedupeSuffix = migrated.deduped > 0
+        ? ` and removed ${migrated.deduped} duplicate registration${migrated.deduped === 1 ? "" : "s"}`
+        : "";
+      stdout.write(
+        `[migrate-source-mutations] ${action} ${MAIN_CLIENT_PROVIDER_FILE}: moved ${movedSuffix} before MainClientProvider${dedupeSuffix}.\n`
+      );
+    }
+  }
+
+  const crudFormFieldFiles = await collectCrudFormFieldCandidateFiles(appRoot);
+  for (const filePath of crudFormFieldFiles) {
+    const previousContent = await readFile(filePath, "utf8");
+    const migrated = buildCrudFormFieldPushMigration(previousContent);
+    if (!migrated.changed) {
+      continue;
+    }
+    if (!dryRun) {
+      await writeFile(filePath, migrated.content, "utf8");
+    }
+
+    changedCount += 1;
+    const relativePath = path.relative(appRoot, filePath).replaceAll(path.sep, "/");
+    const action = dryRun ? "would rewrite" : "rewrote";
+    const foldedSuffix = migrated.folded === 1 ? "1 form field push" : `${migrated.folded} form field pushes`;
+    const markerSuffix = migrated.movedMarkers > 0
+      ? ` and moved ${migrated.movedMarkers} form-field marker${migrated.movedMarkers === 1 ? "" : "s"} into array literals`
+      : "";
+    stdout.write(
+      `[migrate-source-mutations] ${action} ${relativePath}: folded ${foldedSuffix} into array literals${markerSuffix}.\n`
+    );
+  }
+
+  if (changedCount < 1) {
+    stdout.write("[migrate-source-mutations] source files are already current.\n");
+  }
+
+  return 0;
+}
+
+export {
+  buildCrudFormFieldPushMigration,
+  buildMainClientProviderMigration,
+  runAppMigrateSourceMutationsCommand
+};

package/src/server/commandHandlers/show/renderPackageText.js

@@ -78,6 +78,7 @@ function renderPackagePayloadText({
   const devMutations = ensureObject(ensureObject(payload.mutations).dependencies).dev || {};
   const scriptMutations = ensureObject(ensureObject(payload.mutations).packageJson).scripts || {};
   const textMutations = ensureArray(ensureObject(payload.mutations).text);
+  const sourceMutations = ensureArray(ensureObject(payload.mutations).source);
   const runtimeMutationEntries = Object.entries(ensureObject(runtimeMutations));
   const devMutationEntries = Object.entries(ensureObject(devMutations));
   const scriptMutationEntries = Object.entries(ensureObject(scriptMutations));
@@ -371,6 +372,23 @@ function renderPackagePayloadText({
     }
   }
 
+  if (sourceMutations.length > 0) {
+    stdout.write(`${color.heading(`Source mutations (${sourceMutations.length}):`)}\n`);
+    for (const mutation of sourceMutations) {
+      const record = ensureObject(mutation);
+      const op = String(record.op || "").trim();
+      const file = String(record.file || "").trim();
+      const reason = String(record.reason || "").trim();
+      const reasonSuffix = reason ? `: ${reason}` : "";
+      let target = String(record.target || record.callee || record.name || record.from || "").trim();
+      if (op === "ensure-import") {
+        target = String(record.from || "").trim();
+      }
+      const mutationLabel = `${op} ${file} ${target}`.trim();
+      stdout.write(`- ${color.item(mutationLabel)}${reasonSuffix}\n`);
+    }
+  }
+
   if (payload.fileWritePlan.fileCount > 0) {
     stdout.write(`${color.heading(`File writes (${payload.fileWritePlan.fileCount}):`)}\n`);
     for (const group of payload.fileWritePlan.groups) {

package/src/server/core/commandCatalog.js

@@ -136,13 +136,13 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     parameters: Object.freeze([
       Object.freeze({
         name: "<subcommand>",
-        description: "verify | update-packages | link-local-packages | release | adopt-managed-scripts."
+        description: "verify | update-packages | link-local-packages | release | adopt-managed-scripts | migrate-source-mutations."
       })
     ]),
     defaults: Object.freeze([
       "The scaffold keeps npm run shortcuts such as verify and jskit:update, but their maintained behavior lives under jskit app.",
       "Use jskit app <subcommand> help for subcommand-specific usage.",
-      "--dry-run is accepted by update-packages, adopt-managed-scripts, and release."
+      "--dry-run is accepted by update-packages, adopt-managed-scripts, migrate-source-mutations, and release."
     ]),
     examples: Object.freeze([
       Object.freeze({
@@ -156,7 +156,9 @@ const COMMAND_DESCRIPTORS = Object.freeze({
         label: "Existing app migration",
         lines: Object.freeze([
           "jskit app adopt-managed-scripts --dry-run",
-          "jskit app adopt-managed-scripts --force"
+          "jskit app adopt-managed-scripts --force",
+          "jskit app migrate-source-mutations --dry-run",
+          "jskit app migrate-source-mutations"
         ])
       })
     ]),