@jskit-ai/jskit-cli 0.2.39 → 0.2.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.39",
+  "version": "0.2.41",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,8 +20,8 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.39",
-    "@jskit-ai/kernel": "0.1.31"
+    "@jskit-ai/jskit-catalog": "0.1.40",
+    "@jskit-ai/kernel": "0.1.32"
   },
   "engines": {
     "node": "20.x"

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

@@ -16,7 +16,8 @@ import {
   hashBuffer,
   fileExists,
   readFileBufferIfExists,
-  loadMutationWhenConfigContext
+  loadMutationWhenConfigContext,
+  resolveAppRelativePathWithinRoot
 } from "../ioAndMigrations.js";
 import {
   copyTemplateFile,
@@ -113,7 +114,7 @@ async function applyFileMutations(
           mutation,
           configContext
         })
-      : [path.join(appRoot, to)];
+      : [resolveAppRelativePathWithinRoot(appRoot, to, `${packageEntry.packageId} files mutation.to`).absolutePath];
     const hasPrecomputedTemplateContext =
       precomputedTemplateContextByMutationIndex instanceof Map &&
       precomputedTemplateContextByMutationIndex.has(mutationIndex);
@@ -224,7 +225,7 @@ async function preflightFileMutationTemplateContexts(
             mutation,
             configContext
           })
-        : [path.join(appRoot, to)]
+        : [resolveAppRelativePathWithinRoot(appRoot, to, `${packageEntry.packageId} files mutation.to`).absolutePath]
       : [path.join(appRoot, mutation.toDir || "migrations")];
     const replacements = await resolveTemplateContextReplacementsForMutation({
       packageEntry,

package/src/server/cliRuntime/packageInstallFlow.js

@@ -275,7 +275,8 @@ async function applyPackageInstall({
   appPackageJson,
   lock,
   packageRegistry,
-  touchedFiles
+  touchedFiles,
+  reportTemplateFetchStatus = null
 }) {
   const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
   const existingManaged = ensureObject(existingInstall.managed);
@@ -292,7 +293,11 @@ async function applyPackageInstall({
   const mutationWarnings = [];
   const mutations = ensureObject(packageEntry.descriptor.mutations);
   const fileMutations = ensureArray(mutations.files);
-  const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
+  const templateRoot = await resolvePackageTemplateRoot({
+    packageEntry,
+    appRoot,
+    reportTemplateFetchStatus
+  });
   const packageEntryForMutations =
     templateRoot === packageEntry.rootDir
       ? packageEntry

package/src/server/cliRuntime/packageOptions.js

@@ -1,3 +1,4 @@
+import { normalizePagesRelativeTargetRoot } from "@jskit-ai/kernel/server/support";
 import { createCliError } from "../shared/cliError.js";
 import {
   ensureObject,
@@ -15,6 +16,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_NORMALIZATION_PAGES_RELATIVE_TARGET_ROOT = "pages-relative-target-root";
 
 function normalizeSurfaceIdForMutation(value = "") {
   return String(value || "").trim().toLowerCase();
@@ -100,6 +103,95 @@ function normalizeResolvedOptionValue(value = "") {
   return String(value || "").trim().toLowerCase();
 }
 
+function normalizeResolvedOptionSchemaValue({
+  packageEntry,
+  optionName = "",
+  schema = {},
+  value = ""
+} = {}) {
+  const normalizedValue = String(value || "").trim();
+  if (!normalizedValue) {
+    return "";
+  }
+
+  const normalizationType = normalizeResolvedOptionValue(schema?.normalizationType);
+  if (!normalizationType) {
+    return normalizedValue;
+  }
+
+  if (normalizationType === OPTION_NORMALIZATION_PAGES_RELATIVE_TARGET_ROOT) {
+    return normalizePagesRelativeTargetRoot(normalizedValue, {
+      context: `package ${String(packageEntry?.packageId || "unknown-package")}`,
+      label: `option "${String(optionName || "").trim() || "unknown"}"`
+    }).slice("src/pages/".length);
+  }
+
+  throw createCliError(
+    `Invalid option normalization type in package ${String(packageEntry?.packageId || "unknown-package")}: ${String(schema?.normalizationType || "").trim()}.`
+  );
+}
+
+function resolveSchemaValidatedOptionNames(packageEntry = {}, validationType = "", { optionNames = null } = {}) {
+  const normalizedValidationType = String(validationType || "").trim().toLowerCase();
+  if (!normalizedValidationType) {
+    return [];
+  }
+
+  const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
+  const candidateOptionNames = Array.isArray(optionNames) && optionNames.length > 0
+    ? optionNames
+    : Object.keys(optionSchemas);
+
+  return [
+    ...new Set(
+      candidateOptionNames.filter((optionName) => {
+        const schema = ensureObject(optionSchemas[optionName]);
+        return normalizeResolvedOptionValue(schema.validationType) === normalizedValidationType;
+      })
+    )
+  ];
+}
+
+function validateEnabledSurfaceOptionValues({
+  packageEntry,
+  resolvedOptions = {},
+  optionNames = null,
+  configContext = {}
+} = {}) {
+  const validatedOptionNames = resolveSchemaValidatedOptionNames(
+    packageEntry,
+    OPTION_VALIDATION_ENABLED_SURFACE_ID,
+    { optionNames }
+  );
+  if (validatedOptionNames.length < 1) {
+    return;
+  }
+
+  const providedSurfaceOptionNames = validatedOptionNames.filter((optionName) => {
+    return normalizeSurfaceIdForMutation(resolvedOptions?.[optionName]).length > 0;
+  });
+  if (providedSurfaceOptionNames.length < 1) {
+    return;
+  }
+
+  const packageId = String(packageEntry?.packageId || "").trim() || "unknown-package";
+  const surfaceDefinitions = resolveSurfaceDefinitionsForOptionPolicy(configContext);
+  for (const optionName of providedSurfaceOptionNames) {
+    const surfaceId = normalizeSurfaceIdForMutation(resolvedOptions?.[optionName]);
+    const surfaceDefinition = surfaceDefinitions[surfaceId];
+    if (!surfaceDefinition) {
+      throw createCliError(
+        `Invalid option for package ${packageId}: --${optionName} references unknown surface "${surfaceId}" in config/public.js.`
+      );
+    }
+    if (surfaceDefinition.enabled !== true) {
+      throw createCliError(
+        `Invalid option for package ${packageId}: --${optionName} references disabled surface "${surfaceId}" in config/public.js.`
+      );
+    }
+  }
+}
+
 function validateSurfaceVisibilityOptionPolicy({
   packageEntry,
   resolvedOptions = {},
@@ -159,6 +251,34 @@ async function validateResolvedOptionPolicies({
   });
 }
 
+async function validateOptionValuesForPackage({
+  packageEntry,
+  resolvedOptions = {},
+  appRoot = "",
+  optionNames = null
+} = {}) {
+  if (!appRoot) {
+    return;
+  }
+
+  const validatedOptionNames = resolveSchemaValidatedOptionNames(
+    packageEntry,
+    OPTION_VALIDATION_ENABLED_SURFACE_ID,
+    { optionNames }
+  );
+  if (validatedOptionNames.length < 1) {
+    return;
+  }
+
+  const configContext = await loadMutationWhenConfigContext(appRoot);
+  validateEnabledSurfaceOptionValues({
+    packageEntry,
+    resolvedOptions,
+    optionNames: validatedOptionNames,
+    configContext
+  });
+}
+
 async function resolvePackageOptions(packageEntry, inlineOptions, io, { appRoot = "" } = {}) {
   const optionSchemas = ensureObject(packageEntry.descriptor.options);
   const optionNames = Object.keys(optionSchemas);
@@ -211,10 +331,23 @@ async function resolvePackageOptions(packageEntry, inlineOptions, io, { appRoot
   for (const optionName of optionNames) {
     const schema = ensureObject(optionSchemas[optionName]);
     const allowEmpty = schema.allowEmpty === true;
+    const assignResolvedOption = (rawValue = "") => {
+      const normalizedOptionValue = normalizeResolvedOptionSchemaValue({
+        packageEntry,
+        optionName,
+        schema,
+        value: rawValue
+      });
+      if (normalizedOptionValue || allowEmpty) {
+        resolved[optionName] = normalizedOptionValue;
+        return true;
+      }
+      return false;
+    };
     if (hasInlineOption(optionName)) {
       const inlineValue = String(inlineOptionValues[optionName] || "").trim();
       if (inlineValue || allowEmpty) {
-        resolved[optionName] = inlineValue;
+        assignResolvedOption(inlineValue);
         continue;
       }
       if (schema.required) {
@@ -226,7 +359,7 @@ async function resolvePackageOptions(packageEntry, inlineOptions, io, { appRoot
     if (defaultFromConfigPath) {
       const defaultFromConfigValue = await resolveOptionDefaultFromConfig(defaultFromConfigPath);
       if (defaultFromConfigValue || allowEmpty) {
-        resolved[optionName] = defaultFromConfigValue;
+        assignResolvedOption(defaultFromConfigValue);
         continue;
       }
     }
@@ -235,31 +368,37 @@ async function resolvePackageOptions(packageEntry, inlineOptions, io, { appRoot
     if (defaultFromOptionTemplate) {
       const derivedOptionValue = resolveOptionDefaultFromTemplate(defaultFromOptionTemplate, optionName);
       if (derivedOptionValue || allowEmpty) {
-        resolved[optionName] = derivedOptionValue;
+        assignResolvedOption(derivedOptionValue);
         continue;
       }
     }
 
     if (typeof schema.defaultValue === "string" && schema.defaultValue.trim()) {
-      resolved[optionName] = schema.defaultValue.trim();
+      assignResolvedOption(schema.defaultValue.trim());
       continue;
     }
 
     if (schema.required) {
-      resolved[optionName] = await promptForRequiredOption({
+      assignResolvedOption(await promptForRequiredOption({
         ownerType: "package",
         ownerId: packageEntry.packageId,
         optionName,
         optionSchema: schema,
         stdin: io.stdin,
         stdout: io.stdout
-      });
+      }));
       continue;
     }
 
     resolved[optionName] = "";
   }
 
+  await validateOptionValuesForPackage({
+    packageEntry,
+    resolvedOptions: resolved,
+    appRoot
+  });
+
   await validateResolvedOptionPolicies({
     packageEntry,
     resolvedOptions: resolved,
@@ -291,9 +430,23 @@ function validateInlineOptionsForPackage(packageEntry, inlineOptions) {
   );
 }
 
+async function validateInlineOptionValuesForPackage(
+  packageEntry,
+  inlineOptions,
+  { appRoot = "", optionNames = null } = {}
+) {
+  await validateOptionValuesForPackage({
+    packageEntry,
+    resolvedOptions: ensureObject(inlineOptions),
+    appRoot,
+    optionNames
+  });
+}
+
 export {
   normalizeSurfaceIdForMutation,
   parseSurfaceIdListForMutation,
   resolvePackageOptions,
-  validateInlineOptionsForPackage
+  validateInlineOptionsForPackage,
+  validateInlineOptionValuesForPackage
 };

package/src/server/cliRuntime/packageTemplateResolution.js

@@ -68,7 +68,10 @@ async function ensureMaterializedInstallWorkspace(installRoot) {
   );
 }
 
-async function installCatalogPackageIntoCache({ installRoot, packageEntry }) {
+async function installCatalogPackageIntoCache({
+  installRoot,
+  packageEntry
+}) {
   const packageId = String(packageEntry?.packageId || "").trim();
   const version = String(packageEntry?.version || "").trim();
   const packageSpec = version ? `${packageId}@${version}` : packageId;
@@ -124,6 +127,7 @@ async function installCatalogPackageIntoCache({ installRoot, packageEntry }) {
 async function materializeCatalogPackageRoot({
   packageEntry,
   appRoot,
+  reportTemplateFetchStatus = null,
   installCatalogPackage = installCatalogPackageIntoCache
 } = {}) {
   if (!isInternalCatalogPackageEntry(packageEntry)) {
@@ -139,12 +143,20 @@ async function materializeCatalogPackageRoot({
   const installRoot = buildMaterializedInstallRoot({ appRoot, packageEntry });
   const candidateRoot = path.join(installRoot, "node_modules", ...packageId.split("/"));
   const descriptorPath = path.join(candidateRoot, "package.descriptor.mjs");
+  let didInstallPackage = false;
 
   if (!(await fileExists(descriptorPath))) {
+    if (typeof reportTemplateFetchStatus === "function") {
+      reportTemplateFetchStatus({
+        packageEntry,
+        state: "start"
+      });
+    }
     await installCatalogPackage({
       installRoot,
       packageEntry
     });
+    didInstallPackage = true;
   }
 
   if (!(await fileExists(descriptorPath))) {
@@ -153,6 +165,13 @@ async function materializeCatalogPackageRoot({
     );
   }
 
+  if (didInstallPackage && typeof reportTemplateFetchStatus === "function") {
+    reportTemplateFetchStatus({
+      packageEntry,
+      state: "complete"
+    });
+  }
+
   MATERIALIZED_PACKAGE_ROOTS.set(cacheKey, candidateRoot);
   return candidateRoot;
 }
@@ -243,6 +262,7 @@ async function resolvePackageRootFromLocalWorkspace({ packageId }) {
 async function resolvePackageTemplateRoot({
   packageEntry,
   appRoot,
+  reportTemplateFetchStatus = null,
   materializeCatalogRoot = materializeCatalogPackageRoot
 } = {}) {
   const packageRoot = String(packageEntry?.rootDir || "").trim();
@@ -267,7 +287,8 @@ async function resolvePackageTemplateRoot({
 
   const materializedCatalogPackageRoot = await materializeCatalogRoot({
     packageEntry,
-    appRoot
+    appRoot,
+    reportTemplateFetchStatus
   });
   if (materializedCatalogPackageRoot) {
     return materializedCatalogPackageRoot;

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

@@ -38,7 +38,8 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
     adoptAppLocalPackageDependencies,
     writeJsonFile,
     runNpmInstall,
-    renderResolvedSummary
+    renderResolvedSummary,
+    createCatalogFetchStatusReporter = () => () => {}
   } = ctx;
 
   const invocationMode = options?.commandMode === "generate" ? "generate" : "add";
@@ -242,6 +243,9 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
 
   const packagesToInstall = [];
   const resolvedOptionsByPackage = {};
+  const reportTemplateFetchStatus = createCatalogFetchStatusReporter(io, {
+    enabled: options.json !== true
+  });
   const forceReapplyTarget = options?.forceReapplyTarget === true;
   const hasInlineOptions = Object.keys(ensureObject(options.inlineOptions)).length > 0;
   for (const packageId of resolvedPackageIds) {
@@ -293,7 +297,8 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
       appPackageJson: packageJson,
       lock,
       packageRegistry: combinedPackageRegistry,
-      touchedFiles
+      touchedFiles,
+      reportTemplateFetchStatus
     });
     installedPackageRecords.push(managedRecord);
   }