@jskit-ai/jskit-cli 0.2.27 → 0.2.28

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

@@ -0,0 +1,247 @@
+import {
+  readFile
+} from "node:fs/promises";
+import path from "node:path";
+import { createCliError } from "../../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject
+} from "../../shared/collectionUtils.js";
+import {
+  normalizeFileMutationRecord,
+  shouldApplyMutationWhen
+} from "../mutationWhen.js";
+import {
+  normalizeRelativePath,
+  hashBuffer,
+  fileExists,
+  readFileBufferIfExists,
+  loadMutationWhenConfigContext
+} from "../ioAndMigrations.js";
+import {
+  copyTemplateFile,
+  interpolateFileMutationRecord,
+  resolveTemplateContextReplacementsForMutation
+} from "./templateContext.js";
+import { resolveSurfaceTargetPathsForMutation } from "./surfaceTargets.js";
+import { applyInstallMigrationMutation } from "./installMigrationMutation.js";
+
+async function applyFileMutations(
+  packageEntry,
+  options,
+  appRoot,
+  fileMutations,
+  managedFiles,
+  managedMigrations,
+  touchedFiles,
+  warnings = [],
+  precomputedTemplateContextByMutationIndex = null
+) {
+  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
+      });
+      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
+        })
+      : [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(
+        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));
+    }
+  }
+}
+
+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,
+      mutationContext: "files mutation"
+    });
+    replacementsByMutationIndex.set(mutationIndex, replacements);
+  }
+
+  return replacementsByMutationIndex;
+}
+
+export {
+  applyFileMutations,
+  preflightFileMutationTemplateContexts
+};

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

@@ -0,0 +1,213 @@
+import {
+  mkdir,
+  readFile,
+  writeFile
+} from "node:fs/promises";
+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,
+  normalizeMigrationId,
+  resolveAppRelativePathWithinRoot,
+  formatMigrationTimestamp,
+  buildManagedMigrationRelativePath,
+  findExistingManagedMigrationPathById,
+  upsertManagedMigrationRecord,
+  fileExists
+} from "../ioAndMigrations.js";
+import { normalizeRelativePosixPath } from "../localPackageSupport.js";
+import {
+  applyTemplateContextReplacements,
+  resolveTemplateContextReplacementsForMutation
+} from "./templateContext.js";
+
+async function applyInstallMigrationMutation({
+  packageEntry,
+  mutation,
+  rawMutation,
+  mutationIndex,
+  options,
+  appRoot,
+  managedMigrations,
+  managedMigrationById,
+  touchedFiles,
+  warnings,
+  precomputedTemplateContextByMutationIndex
+} = {}) {
+  if (Object.hasOwn(ensureObject(rawMutation), "preserveOnRemove")) {
+    warnings.push(
+      `${packageEntry.packageId}: install-migration ignores preserveOnRemove (migrations are always preserved on remove).`
+    );
+  }
+
+  const from = mutation.from;
+  const toDir = mutation.toDir || "migrations";
+  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}.`);
+  }
+
+  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 sourceExtension = normalizeMigrationExtension(path.extname(from), ".cjs");
+  const extension = normalizeMigrationExtension(mutation.extension, sourceExtension);
+  const sourceHash = hashBuffer(Buffer.from(renderedSourceContent, "utf8"));
+
+  const existingManagedRecord = managedMigrationById.get(migrationId);
+  if (existingManagedRecord) {
+    const existingManagedPath = normalizeRelativePosixPath(String(existingManagedRecord.path || "").trim());
+    if (!existingManagedPath) {
+      throw createCliError(
+        `${packageEntry.packageId}: managed migration ${migrationId} is missing path in lock.`
+      );
+    }
+    const resolvedManagedPath = resolveAppRelativePathWithinRoot(
+      appRoot,
+      existingManagedPath,
+      `${packageEntry.packageId} managed migration path for ${migrationId}`
+    );
+    const relativePath = resolvedManagedPath.relativePath;
+    const absolutePath = resolvedManagedPath.absolutePath;
+    let existingSourceHash = String(existingManagedRecord.hash || "").trim();
+    if (!existingSourceHash && existingManagedPath && (await fileExists(absolutePath))) {
+      const existingSource = await readFile(absolutePath);
+      existingSourceHash = hashBuffer(existingSource);
+    }
+
+    if (existingSourceHash && existingSourceHash !== sourceHash) {
+      throw createCliError(
+        `${packageEntry.packageId}: migration ${migrationId} changed after install. Keep migrations immutable and create a new migration id.`
+      );
+    }
+
+    if (!(await fileExists(absolutePath))) {
+      await mkdir(path.dirname(absolutePath), { recursive: true });
+      await writeFile(absolutePath, renderedSourceContent, "utf8");
+      touchedFiles.add(relativePath);
+    }
+
+    const nextManagedRecord = {
+      ...existingManagedRecord,
+      id: migrationId,
+      path: relativePath,
+      hash: sourceHash,
+      skipped: true,
+      reason: mutation.reason || String(existingManagedRecord.reason || ""),
+      category: mutation.category || String(existingManagedRecord.category || "")
+    };
+    managedMigrationById.set(migrationId, nextManagedRecord);
+    upsertManagedMigrationRecord(managedMigrations, nextManagedRecord);
+    warnings.push(
+      `${packageEntry.packageId}: skipped migration ${migrationId} (already managed at ${nextManagedRecord.path}).`
+    );
+    return;
+  }
+
+  const existingPathById = await findExistingManagedMigrationPathById({
+    appRoot,
+    toDir,
+    packageId: packageEntry.packageId,
+    migrationId,
+    extension
+  });
+  if (existingPathById) {
+    const existingSource = await readFile(existingPathById.absolutePath);
+    const existingSourceHash = hashBuffer(existingSource);
+    if (existingSourceHash !== sourceHash) {
+      throw createCliError(
+        `${packageEntry.packageId}: migration ${migrationId} changed after install. Keep migrations immutable and create a new migration id.`
+      );
+    }
+    const nextManagedRecord = {
+      id: migrationId,
+      path: existingPathById.relativePath,
+      hash: sourceHash,
+      skipped: true,
+      reason: mutation.reason,
+      category: mutation.category
+    };
+    managedMigrationById.set(migrationId, nextManagedRecord);
+    upsertManagedMigrationRecord(managedMigrations, nextManagedRecord);
+    warnings.push(
+      `${packageEntry.packageId}: skipped migration ${migrationId} (already exists at ${nextManagedRecord.path}).`
+    );
+    return;
+  }
+
+  const baseNowMs = Date.now();
+  let targetPath = null;
+  for (let secondOffset = 0; secondOffset < 86400; secondOffset += 1) {
+    const timestamp = formatMigrationTimestamp(new Date(baseNowMs + secondOffset * 1000));
+    const candidateRelativePath = buildManagedMigrationRelativePath({
+      toDir,
+      packageId: packageEntry.packageId,
+      migrationId,
+      extension,
+      timestamp
+    });
+    const candidatePath = resolveAppRelativePathWithinRoot(
+      appRoot,
+      candidateRelativePath,
+      `${packageEntry.packageId} migration path for ${migrationId}`
+    );
+    if (await fileExists(candidatePath.absolutePath)) {
+      continue;
+    }
+    targetPath = candidatePath;
+    break;
+  }
+
+  if (!targetPath) {
+    throw createCliError(
+      `${packageEntry.packageId}: unable to allocate migration filename for ${migrationId} in ${toDir}.`
+    );
+  }
+
+  const relativePath = targetPath.relativePath;
+  const absolutePath = targetPath.absolutePath;
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, renderedSourceContent, "utf8");
+  touchedFiles.add(relativePath);
+
+  const nextManagedRecord = {
+    id: migrationId,
+    path: relativePath,
+    hash: sourceHash,
+    skipped: false,
+    reason: mutation.reason,
+    category: mutation.category
+  };
+  managedMigrationById.set(migrationId, nextManagedRecord);
+  upsertManagedMigrationRecord(managedMigrations, nextManagedRecord);
+}
+
+export {
+  applyInstallMigrationMutation
+};

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

@@ -0,0 +1,12 @@
+function normalizeMutationRelativeFilePath(value = "") {
+  return String(value || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/\/{2,}/g, "/")
+    .replace(/^\.\/+/, "")
+    .replace(/^\/+/, "");
+}
+
+export {
+  normalizeMutationRelativeFilePath
+};

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

@@ -0,0 +1,155 @@
+import path from "node:path";
+import { createCliError } from "../../shared/cliError.js";
+import { ensureObject } from "../../shared/collectionUtils.js";
+import {
+  normalizeSurfaceIdForMutation,
+  parseSurfaceIdListForMutation
+} from "../packageOptions.js";
+
+function normalizeSurfacePagesRootForMutation(value = "") {
+  const rawValue = String(value || "").trim();
+  if (!rawValue || rawValue === "/") {
+    return "";
+  }
+
+  return rawValue
+    .replace(/\\/g, "/")
+    .replace(/\/{2,}/g, "/")
+    .replace(/^\/+|\/+$/g, "");
+}
+
+function normalizeSurfacePathForMutation(value = "", { context = "toSurfacePath" } = {}) {
+  const rawValue = String(value || "").trim();
+  if (!rawValue) {
+    return "";
+  }
+
+  const normalized = rawValue
+    .replace(/\\/g, "/")
+    .replace(/\/{2,}/g, "/")
+    .replace(/^\.\/+/, "")
+    .replace(/^\/+/, "");
+  const segments = normalized.split("/");
+  const materializedSegments = [];
+  for (const segmentValue of segments) {
+    const segment = String(segmentValue || "").trim();
+    if (!segment || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      throw createCliError(`Invalid ${context}: path traversal is not allowed.`);
+    }
+    materializedSegments.push(segment);
+  }
+
+  return materializedSegments.join("/");
+}
+
+function resolveSurfaceDefinitionFromConfigForMutation({
+  configContext = {},
+  surfaceId = "",
+  packageId = ""
+} = {}) {
+  const normalizedSurfaceId = normalizeSurfaceIdForMutation(surfaceId);
+  if (!normalizedSurfaceId) {
+    throw createCliError(`Invalid files mutation in ${packageId}: "toSurface" is required when using surface targeting.`);
+  }
+
+  const publicConfig = ensureObject(configContext.public);
+  const mergedConfig = ensureObject(configContext.merged);
+  const sourceDefinitions = ensureObject(publicConfig.surfaceDefinitions);
+  const fallbackDefinitions = ensureObject(mergedConfig.surfaceDefinitions);
+  const surfaceDefinitions =
+    Object.keys(sourceDefinitions).length > 0 ? sourceDefinitions : fallbackDefinitions;
+
+  for (const [key, value] of Object.entries(surfaceDefinitions)) {
+    const definition = ensureObject(value);
+    const definitionId = normalizeSurfaceIdForMutation(definition.id || key);
+    if (definitionId !== normalizedSurfaceId) {
+      continue;
+    }
+    if (definition.enabled === false) {
+      throw createCliError(
+        `Invalid files mutation in ${packageId}: surface "${normalizedSurfaceId}" is disabled.`
+      );
+    }
+    if (!Object.prototype.hasOwnProperty.call(definition, "pagesRoot")) {
+      throw createCliError(
+        `Invalid files mutation in ${packageId}: surface "${normalizedSurfaceId}" is missing pagesRoot in config/public.js.`
+      );
+    }
+
+    return Object.freeze({
+      ...definition,
+      id: definitionId,
+      pagesRoot: normalizeSurfacePagesRootForMutation(definition.pagesRoot)
+    });
+  }
+
+  throw createCliError(
+    `Invalid files mutation in ${packageId}: unknown surface "${normalizedSurfaceId}" in config/public.js.`
+  );
+}
+
+function resolveSurfaceTargetPathsForMutation({
+  appRoot,
+  packageId,
+  mutation,
+  configContext
+} = {}) {
+  const normalizedSurfaceIds = parseSurfaceIdListForMutation(mutation.toSurface);
+  if (normalizedSurfaceIds.length < 1) {
+    throw createCliError(`Invalid files mutation in ${packageId}: "toSurface" is required when using surface targeting.`);
+  }
+
+  if (mutation.toSurfaceRoot === true) {
+    if (String(mutation.toSurfacePath || "").trim()) {
+      throw createCliError(
+        `Invalid files mutation in ${packageId}: "toSurfacePath" cannot be combined with "toSurfaceRoot".`
+      );
+    }
+
+    const targetPaths = [];
+    for (const surfaceId of normalizedSurfaceIds) {
+      const definition = resolveSurfaceDefinitionFromConfigForMutation({
+        configContext,
+        surfaceId,
+        packageId
+      });
+      if (!definition.pagesRoot) {
+        throw createCliError(
+          `Invalid files mutation in ${packageId}: root surface "${surfaceId}" cannot use "toSurfaceRoot".`
+        );
+      }
+      targetPaths.push(path.join(appRoot, "src/pages", `${definition.pagesRoot}.vue`));
+    }
+    return Object.freeze(targetPaths);
+  }
+
+  const normalizedSurfacePath = normalizeSurfacePathForMutation(mutation.toSurfacePath, {
+    context: "toSurfacePath"
+  });
+  if (!normalizedSurfacePath) {
+    throw createCliError(
+      `Invalid files mutation in ${packageId}: "toSurfacePath" is required when using "toSurface".`
+    );
+  }
+
+  const targetPaths = [];
+  for (const surfaceId of normalizedSurfaceIds) {
+    const definition = resolveSurfaceDefinitionFromConfigForMutation({
+      configContext,
+      surfaceId,
+      packageId
+    });
+    const basePagesDirectory = definition.pagesRoot
+      ? path.join(appRoot, "src/pages", definition.pagesRoot)
+      : path.join(appRoot, "src/pages");
+    targetPaths.push(path.join(basePagesDirectory, normalizedSurfacePath));
+  }
+  return Object.freeze(targetPaths);
+}
+
+export {
+  resolveSurfaceTargetPathsForMutation
+};