@jskit-ai/jskit-cli 0.2.27 → 0.2.29

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

@@ -0,0 +1,171 @@
+import {
+  mkdir,
+  readFile,
+  writeFile
+} from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createCliError } from "../../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject
+} from "../../shared/collectionUtils.js";
+import { interpolateOptionValue } from "../../shared/optionInterpolation.js";
+import {
+  fileExists,
+  resolveAppRelativePathWithinRoot
+} from "../ioAndMigrations.js";
+
+function interpolateFileMutationRecord(mutation, options, packageId) {
+  const mutationKey = String(
+    mutation?.id || mutation?.to || mutation?.toSurface || mutation?.from || "files"
+  ).trim();
+  const interpolate = (value, field) =>
+    interpolateOptionValue(String(value || ""), options, packageId, `${mutationKey}.${field}`);
+
+  return {
+    ...mutation,
+    from: interpolate(mutation.from, "from"),
+    to: interpolate(mutation.to, "to"),
+    toSurface: interpolate(mutation.toSurface, "toSurface"),
+    toSurfacePath: interpolate(mutation.toSurfacePath, "toSurfacePath"),
+    toDir: interpolate(mutation.toDir, "toDir"),
+    extension: interpolate(mutation.extension, "extension"),
+    id: interpolate(mutation.id, "id"),
+    category: interpolate(mutation.category, "category"),
+    reason: interpolate(mutation.reason, "reason"),
+    templateContext: mutation.templateContext
+      ? {
+          entrypoint: interpolate(mutation.templateContext.entrypoint, "templateContext.entrypoint"),
+          export: interpolate(mutation.templateContext.export, "templateContext.export")
+        }
+      : null
+  };
+}
+
+function applyTemplateContextReplacements(sourceContent, replacements) {
+  let output = String(sourceContent || "");
+  for (const [placeholder, value] of Object.entries(ensureObject(replacements))) {
+    const normalizedPlaceholder = String(placeholder || "");
+    if (!normalizedPlaceholder) {
+      continue;
+    }
+    output = output.split(normalizedPlaceholder).join(String(value == null ? "" : value));
+  }
+  return output;
+}
+
+async function copyTemplateFile(
+  sourcePath,
+  targetPath,
+  options,
+  packageId,
+  interpolationKey,
+  templateContextReplacements = null
+) {
+  const sourceContent = await readFile(sourcePath, "utf8");
+  let renderedContent = sourceContent.includes("${")
+    ? interpolateOptionValue(sourceContent, options, packageId, interpolationKey)
+    : sourceContent;
+  if (templateContextReplacements) {
+    renderedContent = applyTemplateContextReplacements(renderedContent, templateContextReplacements);
+  }
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, renderedContent, "utf8");
+}
+
+async function resolveTemplateContextReplacementsForMutation({
+  packageEntry,
+  mutation,
+  options,
+  appRoot,
+  sourcePath,
+  targetPaths,
+  mutationContext = "files mutation"
+} = {}) {
+  const templateContext = ensureObject(mutation?.templateContext);
+  const hasTemplateContext = Object.keys(templateContext).length > 0;
+  const entrypoint = String(templateContext.entrypoint || "").trim();
+  const resolvedMutationContext = String(mutationContext || "files mutation").trim() || "files mutation";
+  if (!hasTemplateContext) {
+    return null;
+  }
+  if (!entrypoint) {
+    throw createCliError(
+      `Invalid ${resolvedMutationContext} in ${packageEntry.packageId}: templateContext.entrypoint is required when templateContext is set.`
+    );
+  }
+  const exportName = String(templateContext.export || "").trim() || "buildTemplateContext";
+  const resolvedEntrypointPath = resolveAppRelativePathWithinRoot(
+    packageEntry.rootDir,
+    entrypoint,
+    `${packageEntry.packageId} ${resolvedMutationContext} templateContext.entrypoint`
+  );
+  const absoluteEntrypointPath = resolvedEntrypointPath.absolutePath;
+  if (!(await fileExists(absoluteEntrypointPath))) {
+    throw createCliError(
+      `Invalid ${resolvedMutationContext} in ${packageEntry.packageId}: templateContext.entrypoint not found at ${entrypoint}.`
+    );
+  }
+
+  let moduleNamespace = null;
+  try {
+    moduleNamespace = await import(`${pathToFileURL(absoluteEntrypointPath).href}?t=${Date.now()}_${Math.random()}`);
+  } catch (error) {
+    throw createCliError(
+      `Unable to load templateContext entrypoint ${entrypoint} for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  const resolver = moduleNamespace?.[exportName];
+  if (typeof resolver !== "function") {
+    throw createCliError(
+      `Invalid ${resolvedMutationContext} in ${packageEntry.packageId}: templateContext export "${exportName}" is not a function.`
+    );
+  }
+
+  let replacements = null;
+  try {
+    replacements = await resolver({
+      packageId: packageEntry.packageId,
+      packageRoot: packageEntry.rootDir,
+      appRoot,
+      options: Object.freeze({ ...ensureObject(options) }),
+      mutation: Object.freeze({ ...ensureObject(mutation) }),
+      sourcePath,
+      targetPaths: Object.freeze([...ensureArray(targetPaths)])
+    });
+  } catch (error) {
+    throw createCliError(
+      `templateContext export "${exportName}" failed for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  if (replacements == null) {
+    return null;
+  }
+  if (!replacements || typeof replacements !== "object" || Array.isArray(replacements)) {
+    throw createCliError(
+      `Invalid ${resolvedMutationContext} in ${packageEntry.packageId}: templateContext export "${exportName}" must return an object map of placeholder replacements.`
+    );
+  }
+
+  const normalizedReplacements = {};
+  for (const [placeholder, value] of Object.entries(replacements)) {
+    const normalizedPlaceholder = String(placeholder || "").trim();
+    if (!normalizedPlaceholder) {
+      continue;
+    }
+    normalizedReplacements[normalizedPlaceholder] = String(value == null ? "" : value);
+  }
+
+  return Object.freeze(normalizedReplacements);
+}
+
+export {
+  applyTemplateContextReplacements,
+  copyTemplateFile,
+  interpolateFileMutationRecord,
+  resolveTemplateContextReplacementsForMutation
+};

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

@@ -0,0 +1,250 @@
+import {
+  mkdir,
+  writeFile
+} from "node:fs/promises";
+import path from "node:path";
+import { createCliError } from "../../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject
+} from "../../shared/collectionUtils.js";
+import {
+  appendTextSnippet,
+  interpolateOptionValue,
+  normalizeSkipChecks
+} from "../../shared/optionInterpolation.js";
+import {
+  normalizeFileMutationRecord,
+  normalizeMutationWhen,
+  shouldApplyMutationWhen
+} from "../mutationWhen.js";
+import {
+  loadMutationWhenConfigContext,
+  normalizeRelativePath,
+  readFileBufferIfExists
+} from "../ioAndMigrations.js";
+import { upsertEnvValue } from "../appState.js";
+import {
+  applyTemplateContextReplacements,
+  resolveTemplateContextReplacementsForMutation
+} from "./templateContext.js";
+import { normalizeMutationRelativeFilePath } from "./mutationPathUtils.js";
+
+const SETTINGS_FIELDS_CONTRACT_TARGETS = Object.freeze({
+  "packages/main/src/shared/resources/consoleSettingsFields.js": Object.freeze({
+    contractId: "users.settings-fields.console.v1",
+    marker: "@jskit-contract users.settings-fields.console.v1",
+    requiredSnippets: Object.freeze([
+      "defineField",
+      "resetConsoleSettingsFields"
+    ])
+  }),
+  "packages/main/src/shared/resources/workspaceSettingsFields.js": Object.freeze({
+    contractId: "users.settings-fields.workspace.v1",
+    marker: "@jskit-contract users.settings-fields.workspace.v1",
+    requiredSnippets: Object.freeze([
+      "defineField",
+      "resetWorkspaceSettingsFields"
+    ])
+  })
+});
+
+function resolveSettingsFieldsContractTarget(relativeFile = "") {
+  const normalizedRelativeFile = normalizeMutationRelativeFilePath(relativeFile);
+  if (!normalizedRelativeFile) {
+    return null;
+  }
+  const target = SETTINGS_FIELDS_CONTRACT_TARGETS[normalizedRelativeFile];
+  if (!target) {
+    return null;
+  }
+  return {
+    normalizedRelativeFile,
+    target
+  };
+}
+
+async function validateSettingsFieldsContractMutationTarget({
+  appRoot,
+  relativeFile,
+  packageId
+} = {}) {
+  const contractTarget = resolveSettingsFieldsContractTarget(relativeFile);
+  if (!contractTarget) {
+    return;
+  }
+
+  const { normalizedRelativeFile, target } = contractTarget;
+  const absoluteFile = path.join(appRoot, normalizedRelativeFile);
+  const existing = await readFileBufferIfExists(absoluteFile);
+  if (!existing.exists) {
+    throw createCliError(
+      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} is missing. ` +
+      `Install @jskit-ai/users-core to scaffold ${target.contractId}.`
+    );
+  }
+
+  const source = existing.buffer.toString("utf8");
+  if (!source.includes(target.marker)) {
+    throw createCliError(
+      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} is missing contract marker "${target.marker}".`
+    );
+  }
+  for (const snippet of target.requiredSnippets) {
+    if (source.includes(snippet)) {
+      continue;
+    }
+    throw createCliError(
+      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} must include "${snippet}" for ${target.contractId}.`
+    );
+  }
+}
+
+async function applyTextMutations(packageEntry, appRoot, textMutations, options, managedText, touchedFiles) {
+  for (const mutation of textMutations) {
+    const when = normalizeMutationWhen(mutation?.when);
+    const configContext = when?.config ? await loadMutationWhenConfigContext(appRoot) : {};
+    if (
+      !shouldApplyMutationWhen(when, {
+        options,
+        configContext,
+        packageId: packageEntry.packageId,
+        mutationContext: "text mutation"
+      })
+    ) {
+      continue;
+    }
+
+    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) {
+        throw createCliError(`Invalid upsert-env mutation in ${packageEntry.packageId}: "file" and "key" are required.`);
+      }
+
+      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);
+
+      await mkdir(path.dirname(absoluteFile), { recursive: true });
+      await writeFile(absoluteFile, upserted.content, "utf8");
+
+      const recordKey = `${relativeFile}::${String(mutation?.id || key)}`;
+      managedText[recordKey] = {
+        file: relativeFile,
+        op: "upsert-env",
+        key,
+        value: resolvedValue,
+        hadPrevious: upserted.hadPrevious,
+        previousValue: upserted.previousValue,
+        reason: String(mutation?.reason || ""),
+        category: String(mutation?.category || ""),
+        id: String(mutation?.id || "")
+      };
+      touchedFiles.add(normalizeRelativePath(appRoot, absoluteFile));
+      continue;
+    }
+
+    if (operation === "append-text") {
+      const relativeFile = String(mutation?.file || "").trim();
+      const snippet = String(mutation?.value || "");
+      const position = String(mutation?.position || "bottom").trim().toLowerCase();
+      if (!relativeFile) {
+        throw createCliError(`Invalid append-text mutation in ${packageEntry.packageId}: "file" is required.`);
+      }
+      if (position !== "top" && position !== "bottom") {
+        throw createCliError(`Invalid append-text mutation in ${packageEntry.packageId}: "position" must be "top" or "bottom".`);
+      }
+      await validateSettingsFieldsContractMutationTarget({
+        appRoot,
+        relativeFile,
+        packageId: packageEntry.packageId
+      });
+
+      const absoluteFile = path.join(appRoot, relativeFile);
+      const previous = await readFileBufferIfExists(absoluteFile);
+      const previousContent = previous.exists ? previous.buffer.toString("utf8") : "";
+      const mutationId = String(mutation?.id || "").trim() || "append-text";
+      const resolvedSnippet = interpolateOptionValue(snippet, options, packageEntry.packageId, mutationId);
+      const templateContextReplacements = await resolveTemplateContextReplacementsForMutation({
+        packageEntry,
+        mutation,
+        options,
+        appRoot,
+        sourcePath: absoluteFile,
+        targetPaths: [absoluteFile],
+        mutationContext: "text mutation"
+      });
+      const renderedSnippet = templateContextReplacements
+        ? applyTemplateContextReplacements(resolvedSnippet, templateContextReplacements)
+        : resolvedSnippet;
+      const skipChecks = normalizeSkipChecks(mutation?.skipIfContains)
+        .map((entry) => interpolateOptionValue(entry, options, packageEntry.packageId, `${mutationId}.skipIfContains`))
+        .map((entry) => {
+          if (!templateContextReplacements) {
+            return entry;
+          }
+          return applyTemplateContextReplacements(entry, templateContextReplacements);
+        })
+        .filter((entry) => String(entry || "").trim().length > 0);
+
+      const shouldSkip = skipChecks.some((pattern) => previousContent.includes(String(pattern)));
+      if (shouldSkip) {
+        continue;
+      }
+
+      const appended = appendTextSnippet(previousContent, renderedSnippet, position);
+      if (!appended.changed) {
+        continue;
+      }
+
+      await mkdir(path.dirname(absoluteFile), { recursive: true });
+      await writeFile(absoluteFile, appended.content, "utf8");
+
+      const recordKey = `${relativeFile}::${mutationId}`;
+      managedText[recordKey] = {
+        file: relativeFile,
+        op: "append-text",
+        value: renderedSnippet,
+        position,
+        reason: String(mutation?.reason || ""),
+        category: String(mutation?.category || ""),
+        id: String(mutation?.id || "")
+      };
+      touchedFiles.add(normalizeRelativePath(appRoot, absoluteFile));
+      continue;
+    }
+
+    throw createCliError(`Unsupported text mutation op "${operation}" in ${packageEntry.packageId}.`);
+  }
+}
+
+function isPositioningTextMutation(value = {}) {
+  const mutation = ensureObject(value);
+  const operation = String(mutation.op || "").trim();
+  if (operation !== "append-text") {
+    return false;
+  }
+  return normalizeMutationRelativeFilePath(mutation.file) === "src/placement.js";
+}
+
+function resolvePositioningMutations(descriptorMutations = {}) {
+  const mutations = ensureObject(descriptorMutations);
+  const files = ensureArray(mutations.files).filter((mutationValue) => {
+    const normalized = normalizeFileMutationRecord(mutationValue);
+    return Boolean(normalized.toSurface);
+  });
+  const text = ensureArray(mutations.text).filter((mutationValue) => isPositioningTextMutation(mutationValue));
+  return {
+    files,
+    text
+  };
+}
+
+export {
+  applyTextMutations,
+  resolvePositioningMutations
+};