@jskit-ai/jskit-cli 0.2.42 → 0.2.44

package/src/server/cliRuntime/packageInstallFlow.js

@@ -32,7 +32,8 @@ import {
 import {
   applyFileMutations,
   applyTextMutations,
-  preflightFileMutationTemplateContexts,
+  partitionPreFileConfigTextMutations,
+  prepareFileMutations,
   resolvePositioningMutations
 } from "./mutationApplication.js";
 function createManagedRecordBase(packageEntry, options) {
@@ -138,15 +139,23 @@ async function applyPackagePositioning({
   const positioningMutations = resolvePositioningMutations(mutations);
   const appliedManagedFiles = [];
   const appliedManagedText = {};
+  const preparedFileMutations = await prepareFileMutations(
+    packageEntryForMutations,
+    packageOptions,
+    appRoot,
+    positioningMutations.files,
+    nextManaged.files
+  );
   if (positioningMutations.files.length > 0) {
     await applyFileMutations(
       packageEntryForMutations,
-      packageOptions,
       appRoot,
-      positioningMutations.files,
+      preparedFileMutations,
       appliedManagedFiles,
       [],
-      touchedFiles
+      touchedFiles,
+      [],
+      nextManaged.files
     );
   }
   if (positioningMutations.text.length > 0) {
@@ -236,17 +245,24 @@ async function applyPackageMigrationsOnly({
     return operation === "install-migration";
   });
   const mutationWarnings = [];
+  const preparedFileMutations = await prepareFileMutations(
+    packageEntryForMutations,
+    packageOptions,
+    appRoot,
+    migrationFileMutations,
+    nextManaged.files
+  );
 
   if (migrationFileMutations.length > 0) {
     await applyFileMutations(
       packageEntryForMutations,
-      packageOptions,
       appRoot,
-      migrationFileMutations,
+      preparedFileMutations,
       [],
       nextManaged.migrations,
       touchedFiles,
-      mutationWarnings
+      mutationWarnings,
+      nextManaged.files
     );
   }
 
@@ -280,19 +296,23 @@ async function applyPackageInstall({
 }) {
   const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
   const existingManaged = ensureObject(existingInstall.managed);
-  await removeManagedViteProxyEntries({
-    appRoot,
-    packageId: packageEntry.packageId,
-    managedViteChanges: ensureObject(existingManaged.vite),
-    touchedFiles
-  });
-
-  const managedRecord = createManagedRecordBase(packageEntry, packageOptions);
-  managedRecord.managed.migrations = cloneManagedArray(existingManaged.migrations);
   const generatorPackage = isGeneratorPackageEntry(packageEntry);
   const mutationWarnings = [];
   const mutations = ensureObject(packageEntry.descriptor.mutations);
   const fileMutations = ensureArray(mutations.files);
+  const textMutations = ensureArray(mutations.text);
+  const hasSurfaceTargetedFileMutations = fileMutations.some((mutationValue) =>
+    Boolean(normalizeFileMutationRecord(mutationValue).toSurface)
+  );
+  const {
+    preFileTextMutations,
+    postFileTextMutations
+  } = hasSurfaceTargetedFileMutations
+    ? partitionPreFileConfigTextMutations(textMutations)
+    : {
+        preFileTextMutations: [],
+        postFileTextMutations: textMutations
+      };
   const templateRoot = await resolvePackageTemplateRoot({
     packageEntry,
     appRoot,
@@ -305,13 +325,33 @@ async function applyPackageInstall({
           ...packageEntry,
           rootDir: templateRoot
         };
+  const managedRecord = createManagedRecordBase(packageEntry, packageOptions);
+  managedRecord.managed.migrations = cloneManagedArray(existingManaged.migrations);
 
-  const precomputedTemplateContextByMutationIndex = await preflightFileMutationTemplateContexts(
+  if (preFileTextMutations.length > 0) {
+    await applyTextMutations(
+      packageEntryForMutations,
+      appRoot,
+      preFileTextMutations,
+      packageOptions,
+      managedRecord.managed.text,
+      touchedFiles
+    );
+  }
+
+  const preparedFileMutations = await prepareFileMutations(
     packageEntryForMutations,
     packageOptions,
     appRoot,
-    fileMutations
+    fileMutations,
+    ensureArray(existingManaged.files)
   );
+  await removeManagedViteProxyEntries({
+    appRoot,
+    packageId: packageEntry.packageId,
+    managedViteChanges: ensureObject(existingManaged.vite),
+    touchedFiles
+  });
 
   const mutationDependencies = ensureObject(mutations.dependencies);
   const runtimeDependencies = ensureObject(mutationDependencies.runtime);
@@ -416,20 +456,19 @@ async function applyPackageInstall({
 
   await applyFileMutations(
     packageEntryForMutations,
-    packageOptions,
     appRoot,
-    fileMutations,
+    preparedFileMutations,
     managedRecord.managed.files,
     managedRecord.managed.migrations,
     touchedFiles,
     mutationWarnings,
-    precomputedTemplateContextByMutationIndex
+    ensureArray(existingManaged.files)
   );
 
   await applyTextMutations(
     packageEntryForMutations,
     appRoot,
-    ensureArray(mutations.text),
+    postFileTextMutations,
     packageOptions,
     managedRecord.managed.text,
     touchedFiles

package/src/server/cliRuntime/packageIntrospection/placementNormalization.js

@@ -2,15 +2,17 @@ import {
   ensureArray,
   ensureObject
 } from "../../shared/collectionUtils.js";
+import {
+  normalizeShellOutletTargetId
+} from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 
 function normalizePlacementOutlets(value) {
   const outlets = [];
   const source = ensureArray(value);
   for (const entry of source) {
     const record = ensureObject(entry);
-    const host = String(record.host || "").trim();
-    const position = String(record.position || "").trim();
-    if (!host || !position) {
+    const target = normalizeShellOutletTargetId(record.target);
+    if (!target) {
       continue;
     }
 
@@ -19,8 +21,7 @@ function normalizePlacementOutlets(value) {
     const sourceLabel = String(record.source || "").trim();
     outlets.push(
       Object.freeze({
-        host,
-        position,
+        target,
         surfaces: Object.freeze(surfaces),
         description,
         source: sourceLabel
@@ -30,11 +31,7 @@ function normalizePlacementOutlets(value) {
 
   return Object.freeze(
     [...outlets].sort((left, right) => {
-      const hostCompare = left.host.localeCompare(right.host);
-      if (hostCompare !== 0) {
-        return hostCompare;
-      }
-      return left.position.localeCompare(right.position);
+      return left.target.localeCompare(right.target);
     })
   );
 }
@@ -44,9 +41,8 @@ function normalizePlacementContributions(value) {
   for (const entry of ensureArray(value)) {
     const record = ensureObject(entry);
     const id = String(record.id || "").trim();
-    const host = String(record.host || "").trim();
-    const position = String(record.position || "").trim();
-    if (!id || !host || !position) {
+    const target = normalizeShellOutletTargetId(record.target);
+    if (!id || !target) {
       continue;
     }
 
@@ -60,8 +56,7 @@ function normalizePlacementContributions(value) {
     contributions.push(
       Object.freeze({
         id,
-        host,
-        position,
+        target,
         surfaces: Object.freeze(surfaces),
         order,
         componentToken,
@@ -74,13 +69,9 @@ function normalizePlacementContributions(value) {
 
   return Object.freeze(
     [...contributions].sort((left, right) => {
-      const hostCompare = left.host.localeCompare(right.host);
-      if (hostCompare !== 0) {
-        return hostCompare;
-      }
-      const positionCompare = left.position.localeCompare(right.position);
-      if (positionCompare !== 0) {
-        return positionCompare;
+      const targetCompare = left.target.localeCompare(right.target);
+      if (targetCompare !== 0) {
+        return targetCompare;
       }
       const leftOrder = Number.isFinite(left.order) ? left.order : Number.POSITIVE_INFINITY;
       const rightOrder = Number.isFinite(right.order) ? right.order : Number.POSITIVE_INFINITY;

package/src/server/cliRuntime/packageOptions.js

@@ -17,6 +17,8 @@ import { loadMutationWhenConfigContext } from "./ioAndMigrations.js";
 const WORKSPACE_VISIBILITY_LEVELS = Object.freeze(["workspace", "workspace_user"]);
 const WORKSPACE_VISIBILITY_SET = new Set(WORKSPACE_VISIBILITY_LEVELS);
 const OPTION_VALIDATION_ENABLED_SURFACE_ID = "enabled-surface-id";
+const OPTION_VALIDATION_ENUM = "enum";
+const OPTION_VALIDATION_CSV_ENUM = "csv-enum";
 const OPTION_NORMALIZATION_PAGES_RELATIVE_TARGET_ROOT = "pages-relative-target-root";
 
 function normalizeSurfaceIdForMutation(value = "") {
@@ -153,6 +155,114 @@ function resolveSchemaValidatedOptionNames(packageEntry = {}, validationType = "
   ];
 }
 
+function resolveAllowedValuesForSchema(schema = {}) {
+  const values = [];
+  const seen = new Set();
+  for (const rawValue of Array.isArray(schema?.allowedValues) ? schema.allowedValues : []) {
+    const value = String(
+      typeof rawValue === "string"
+        ? rawValue
+        : ensureObject(rawValue).value
+    ).trim();
+    if (!value || seen.has(value.toLowerCase())) {
+      continue;
+    }
+    seen.add(value.toLowerCase());
+    values.push(value);
+  }
+  return Object.freeze(values);
+}
+
+function parseCsvEnumOptionValues(value = "") {
+  return String(value || "")
+    .split(",")
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+}
+
+function validateEnumOptionValues({
+  packageEntry,
+  resolvedOptions = {},
+  optionNames = null
+} = {}) {
+  const validatedOptionNames = resolveSchemaValidatedOptionNames(
+    packageEntry,
+    OPTION_VALIDATION_ENUM,
+    { optionNames }
+  );
+  if (validatedOptionNames.length < 1) {
+    return;
+  }
+
+  const packageId = String(packageEntry?.packageId || "").trim() || "unknown-package";
+  const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
+  for (const optionName of validatedOptionNames) {
+    const schema = ensureObject(optionSchemas[optionName]);
+    const value = String(resolvedOptions?.[optionName] || "").trim();
+    if (!value) {
+      continue;
+    }
+
+    const allowedValues = resolveAllowedValuesForSchema(schema);
+    if (allowedValues.length < 1) {
+      continue;
+    }
+    const allowedValueSet = new Set(allowedValues.map((entry) => entry.toLowerCase()));
+    if (!allowedValueSet.has(value.toLowerCase())) {
+      throw createCliError(
+        `Invalid option for package ${packageId}: --${optionName} must be one of: ${allowedValues.join(", ")}.`
+      );
+    }
+  }
+}
+
+function validateCsvEnumOptionValues({
+  packageEntry,
+  resolvedOptions = {},
+  optionNames = null
+} = {}) {
+  const validatedOptionNames = resolveSchemaValidatedOptionNames(
+    packageEntry,
+    OPTION_VALIDATION_CSV_ENUM,
+    { optionNames }
+  );
+  if (validatedOptionNames.length < 1) {
+    return;
+  }
+
+  const packageId = String(packageEntry?.packageId || "").trim() || "unknown-package";
+  const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
+  for (const optionName of validatedOptionNames) {
+    const schema = ensureObject(optionSchemas[optionName]);
+    const value = String(resolvedOptions?.[optionName] || "").trim();
+    if (!value) {
+      continue;
+    }
+
+    const allowedValues = resolveAllowedValuesForSchema(schema);
+    if (allowedValues.length < 1) {
+      continue;
+    }
+    const allowedValueSet = new Set(allowedValues.map((entry) => entry.toLowerCase()));
+    const providedValues = parseCsvEnumOptionValues(value);
+    if (providedValues.length < 1) {
+      throw createCliError(
+        `Invalid option for package ${packageId}: --${optionName} must include at least one value from: ${allowedValues.join(", ")}.`
+      );
+    }
+    const invalidValues = [
+      ...new Set(
+        providedValues.filter((entry) => !allowedValueSet.has(entry.toLowerCase()))
+      )
+    ];
+    if (invalidValues.length > 0) {
+      throw createCliError(
+        `Invalid option for package ${packageId}: --${optionName} includes unsupported value(s): ${invalidValues.join(", ")}. Allowed values: ${allowedValues.join(", ")}.`
+      );
+    }
+  }
+}
+
 function validateEnabledSurfaceOptionValues({
   packageEntry,
   resolvedOptions = {},
@@ -254,6 +364,12 @@ async function validateResolvedOptionPolicies({
 
 function resolvePromptChoicesForOption({ schema = {}, configContext = {} } = {}) {
   const validationType = normalizeResolvedOptionValue(schema.validationType);
+  if (validationType === OPTION_VALIDATION_ENUM) {
+    return resolveAllowedValuesForSchema(schema).map((value) => Object.freeze({
+      value,
+      label: value
+    }));
+  }
   if (validationType !== OPTION_VALIDATION_ENABLED_SURFACE_ID) {
     return [];
   }
@@ -275,9 +391,16 @@ async function validateOptionValuesForPackage({
   appRoot = "",
   optionNames = null
 } = {}) {
-  if (!appRoot) {
-    return;
-  }
+  validateEnumOptionValues({
+    packageEntry,
+    resolvedOptions,
+    optionNames
+  });
+  validateCsvEnumOptionValues({
+    packageEntry,
+    resolvedOptions,
+    optionNames
+  });
 
   const validatedOptionNames = resolveSchemaValidatedOptionNames(
     packageEntry,
@@ -287,6 +410,9 @@ async function validateOptionValuesForPackage({
   if (validatedOptionNames.length < 1) {
     return;
   }
+  if (!appRoot) {
+    return;
+  }
 
   const configContext = await loadMutationWhenConfigContext(appRoot);
   validateEnabledSurfaceOptionValues({

package/src/server/cliRuntime/packageRegistries.js

@@ -1,6 +1,7 @@
 import { readdir } 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,
@@ -92,7 +93,7 @@ async function loadAppLocalPackageRegistry(appRoot) {
       throw createCliError(`Invalid app-local package at ${normalizeRelativePath(appRoot, packageRoot)}: package.json missing name.`);
     }
 
-    const descriptorModule = await import(pathToFileURL(descriptorPath).href + `?t=${Date.now()}_${Math.random()}`);
+    const descriptorModule = await importFreshModuleFromAbsolutePath(descriptorPath);
     const descriptor = validateAppLocalPackageDescriptorShape(descriptorModule?.default, descriptorPath, {
       expectedPackageId: packageId,
       fallbackVersion: String(packageJson?.version || "").trim()
@@ -207,7 +208,7 @@ async function loadInstalledNodeModulePackageEntry({ appRoot, packageId }) {
     return null;
   }
 
-  const descriptorModule = await import(pathToFileURL(descriptorPath).href + `?t=${Date.now()}_${Math.random()}`);
+  const descriptorModule = await importFreshModuleFromAbsolutePath(descriptorPath);
   const descriptor = validateAppLocalPackageDescriptorShape(descriptorModule?.default, descriptorPath, {
     expectedPackageId: resolvedPackageId,
     fallbackVersion: String(packageJson?.version || "").trim()

package/src/server/commandHandlers/completion.js

@@ -0,0 +1,129 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import {
+  getCompletions,
+  renderBashCompletionScript
+} from "../cliRuntime/completion.js";
+
+const INSTALL_MARKER_BEGIN = "# >>> jskit completion >>>";
+const INSTALL_MARKER_END = "# <<< jskit completion <<<";
+
+function resolveInstallBlock(relativeCompletionPath = "") {
+  return [
+    INSTALL_MARKER_BEGIN,
+    `if [ -f "$HOME/${relativeCompletionPath}" ]; then`,
+    `  source "$HOME/${relativeCompletionPath}"`,
+    "fi",
+    INSTALL_MARKER_END
+  ].join("\n");
+}
+
+async function readTextFileIfExists(filePath = "") {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (String(error?.code || "").trim().toUpperCase() === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+async function installBashCompletion() {
+  const homeDirectory = os.homedir();
+  const completionRelativePath = ".jskit/completion/bash/jskit.bash";
+  const completionAbsolutePath = path.join(homeDirectory, completionRelativePath);
+  const bashrcAbsolutePath = path.join(homeDirectory, ".bashrc");
+  const installBlock = resolveInstallBlock(completionRelativePath);
+
+  await mkdir(path.dirname(completionAbsolutePath), { recursive: true });
+  await writeFile(completionAbsolutePath, renderBashCompletionScript(), "utf8");
+
+  const existingBashrc = await readTextFileIfExists(bashrcAbsolutePath);
+  const markerPattern = new RegExp(
+    `${INSTALL_MARKER_BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${INSTALL_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+    "u"
+  );
+  const normalizedExisting = String(existingBashrc || "");
+  const nextBashrc = markerPattern.test(normalizedExisting)
+    ? normalizedExisting.replace(markerPattern, installBlock)
+    : `${normalizedExisting.replace(/\s*$/u, "")}${normalizedExisting.trim() ? "\n\n" : ""}${installBlock}\n`;
+
+  if (nextBashrc !== normalizedExisting) {
+    await writeFile(bashrcAbsolutePath, nextBashrc, "utf8");
+  }
+
+  return {
+    completionAbsolutePath,
+    bashrcAbsolutePath
+  };
+}
+
+function createCompletionCommands(ctx = {}) {
+  const {
+    createCliError,
+    resolveAppRootFromCwd
+  } = ctx;
+
+  async function commandCompletion({ positional = [], options = {}, cwd = "", stdout }) {
+    const shell = String(positional[0] || "").trim().toLowerCase();
+    if (shell !== "bash") {
+      throw createCliError(`Unsupported completion shell: ${shell || "<empty>"}.`, { showUsage: true });
+    }
+
+    const installRequested = String(options?.inlineOptions?.install || "").trim().toLowerCase() === "true";
+    const mode = String(positional[1] || "").trim();
+    if (installRequested && mode) {
+      throw createCliError("jskit completion bash --install does not accept internal completion mode arguments.", {
+        showUsage: true
+      });
+    }
+
+    if (installRequested) {
+      const {
+        completionAbsolutePath,
+        bashrcAbsolutePath
+      } = await installBashCompletion();
+      stdout.write(`Installed Bash completion to ${completionAbsolutePath}.\n`);
+      stdout.write(`Updated ${bashrcAbsolutePath}.\n`);
+      stdout.write("Run: source ~/.bashrc\n");
+      return 0;
+    }
+
+    if (!mode) {
+      stdout.write(renderBashCompletionScript());
+      return 0;
+    }
+
+    if (mode !== "__complete__") {
+      throw createCliError(`Unknown completion mode: ${mode}.`, { showUsage: true });
+    }
+
+    const rawCword = Number.parseInt(String(positional[2] || "0"), 10);
+    const words = positional.slice(3).map((value) => String(value ?? ""));
+
+    let appRoot = String(cwd || process.cwd());
+    try {
+      appRoot = await resolveAppRootFromCwd(appRoot);
+    } catch {
+      // Fall back to cwd so top-level completion still works outside an app root.
+    }
+
+    const completions = await getCompletions({
+      appRoot,
+      words,
+      cword: Number.isInteger(rawCword) ? rawCword : 0
+    });
+    if (completions.length > 0) {
+      stdout.write(`${completions.join("\n")}\n`);
+    }
+    return 0;
+  }
+
+  return {
+    commandCompletion
+  };
+}
+
+export { createCompletionCommands };

package/src/server/commandHandlers/list.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { readdir, readFile } from "node:fs/promises";
-import { pathToFileURL } from "node:url";
+import { importFreshModuleFromAbsolutePath } from "@jskit-ai/kernel/server/support";
 import {
   ensureArray,
   ensureObject,
@@ -72,7 +72,7 @@ async function resolveDescriptorFromLockEntry({ appRoot = "", packageId = "", in
 
   let descriptorModule = null;
   try {
-    descriptorModule = await import(`${pathToFileURL(descriptorAbsolutePath).href}?t=${Date.now()}_${Math.random()}`);
+    descriptorModule = await importFreshModuleFromAbsolutePath(descriptorAbsolutePath);
   } catch {
     return null;
   }
@@ -180,7 +180,7 @@ function createListCommands(ctx = {}) {
     }
     if (mode === "placement-component-tokens") {
       throw createCliError(
-        'list mode "placement-component-tokens" moved to a dedicated command: jskit list-link-items.'
+        'list mode "placement-component-tokens" moved to a dedicated command: jskit list-component-tokens.'
       );
     }
 
@@ -385,9 +385,7 @@ function createListCommands(ctx = {}) {
     if (options.json) {
       const payload = {
         placements: placementTargets.map((placementTarget) => ({
-          id: String(placementTarget.id || "").trim(),
-          host: String(placementTarget.host || "").trim(),
-          position: String(placementTarget.position || "").trim(),
+          target: String(placementTarget.id || "").trim(),
           default: placementTarget.default === true,
           sourcePath: String(placementTarget.sourcePath || "").trim()
         }))

package/src/server/commandHandlers/packageCommands/add.js

@@ -10,10 +10,31 @@ import {
   renderAddBundleHelp
 } from "./discoverabilityHelp.js";
 import {
-  TAB_LINK_COMPONENT_TOKEN,
-  ensureLocalMainTabLinkItemProvisioning
+  ensureLocalMainPlacementComponentProvisioning,
+  resolveProvisionableLocalPlacementComponentTokens
 } from "./tabLinkItemProvisioning.js";
 
+const COMPONENT_TOKEN_PATTERN = /\bcomponentToken\s*:\s*["']([^"']+)["']/g;
+
+function collectPlacementComponentTokensFromManagedRecords(installedPackageRecords = []) {
+  const collectedTokens = new Set();
+
+  for (const record of ensureArray(installedPackageRecords)) {
+    const managedTextMutations = ensureObject(ensureObject(ensureObject(record).managed).text);
+    for (const mutationRecord of Object.values(managedTextMutations)) {
+      const source = String(ensureObject(mutationRecord).value || "");
+      for (const match of source.matchAll(COMPONENT_TOKEN_PATTERN)) {
+        const componentToken = String(match[1] || "").trim();
+        if (componentToken) {
+          collectedTokens.add(componentToken);
+        }
+      }
+    }
+  }
+
+  return sortStrings([...collectedTokens]);
+}
+
 async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io }) {
   const {
     createCliError,
@@ -325,18 +346,17 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
 
   const finalResolvedPackageIds = sortStrings([...resolvedPackageIds, ...adoptedPackageIds]);
 
-  const requestedPlacementComponentToken = String(options?.inlineOptions?.["placement-component-token"] || "").trim();
-  if (
-    invocationMode === "generate" &&
-    targetType === "package" &&
-    resolvedTargetPackageId === "@jskit-ai/crud-ui-generator" &&
-    requestedPlacementComponentToken === TAB_LINK_COMPONENT_TOKEN
-  ) {
-    await ensureLocalMainTabLinkItemProvisioning({
+  const generatedPlacementComponentTokens = await resolveProvisionableLocalPlacementComponentTokens({
+    appRoot,
+    componentTokens: collectPlacementComponentTokensFromManagedRecords(installedPackageRecords)
+  });
+  if (generatedPlacementComponentTokens.length > 0) {
+    await ensureLocalMainPlacementComponentProvisioning({
       appRoot,
       createCliError,
       dryRun: options.dryRun === true,
-      touchedFiles
+      touchedFiles,
+      componentTokens: generatedPlacementComponentTokens
     });
   }