@jskit-ai/jskit-cli 0.2.40 → 0.2.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "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.40",
-    "@jskit-ai/kernel": "0.1.32"
+    "@jskit-ai/jskit-catalog": "0.1.41",
+    "@jskit-ai/kernel": "0.1.33"
   },
   "engines": {
     "node": "20.x"

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

@@ -118,25 +118,30 @@ async function applyTextMutations(packageEntry, appRoot, textMutations, options,
     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) {
+      const rawKey = String(mutation?.key || "").trim();
+      if (!relativeFile || !rawKey) {
         throw createCliError(`Invalid upsert-env mutation in ${packageEntry.packageId}: "file" and "key" are required.`);
       }
 
+      const resolvedKey = interpolateOptionValue(rawKey, options, packageEntry.packageId, `${rawKey}.key`).trim();
+      if (!resolvedKey) {
+        throw createCliError(`Invalid upsert-env mutation in ${packageEntry.packageId}: resolved key is empty.`);
+      }
+
       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);
+      const resolvedValue = interpolateOptionValue(mutation?.value || "", options, packageEntry.packageId, resolvedKey);
+      const upserted = upsertEnvValue(previousContent, resolvedKey, resolvedValue);
 
       await mkdir(path.dirname(absoluteFile), { recursive: true });
       await writeFile(absoluteFile, upserted.content, "utf8");
 
-      const recordKey = `${relativeFile}::${String(mutation?.id || key)}`;
+      const recordKey = `${relativeFile}::${String(mutation?.id || resolvedKey)}`;
       managedText[recordKey] = {
         file: relativeFile,
         op: "upsert-env",
-        key,
+        key: resolvedKey,
         value: resolvedValue,
         hadPrevious: upserted.hadPrevious,
         previousValue: upserted.previousValue,

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

@@ -91,6 +91,7 @@ function resolveSurfaceDefinitionsForOptionPolicy(configContext = {}) {
 
     normalizedDefinitions[definitionId] = Object.freeze({
       id: definitionId,
+      label: String(definition.label || "").trim(),
       enabled: definition.enabled !== false,
       requiresWorkspace: definition.requiresWorkspace === true
     });
@@ -251,6 +252,23 @@ async function validateResolvedOptionPolicies({
   });
 }
 
+function resolvePromptChoicesForOption({ schema = {}, configContext = {} } = {}) {
+  const validationType = normalizeResolvedOptionValue(schema.validationType);
+  if (validationType !== OPTION_VALIDATION_ENABLED_SURFACE_ID) {
+    return [];
+  }
+
+  const surfaceDefinitions = resolveSurfaceDefinitionsForOptionPolicy(configContext);
+  return Object.values(surfaceDefinitions)
+    .filter((entry) => entry.enabled === true)
+    .map((entry) => Object.freeze({
+      value: entry.id,
+      label: entry.label && entry.label.toLowerCase() !== entry.id.toLowerCase()
+        ? `${entry.id} (${entry.label})`
+        : entry.id
+    }));
+}
+
 async function validateOptionValuesForPackage({
   packageEntry,
   resolvedOptions = {},
@@ -379,11 +397,13 @@ async function resolvePackageOptions(packageEntry, inlineOptions, io, { appRoot
     }
 
     if (schema.required) {
+      const promptConfigContext = appRoot ? await loadConfigContext() : {};
       assignResolvedOption(await promptForRequiredOption({
         ownerType: "package",
         ownerId: packageEntry.packageId,
         optionName,
         optionSchema: schema,
+        promptChoices: resolvePromptChoicesForOption({ schema, configContext: promptConfigContext }),
         stdin: io.stdin,
         stdout: io.stdout
       }));

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);
   }

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

@@ -73,40 +73,11 @@ function mapDescriptorBackedSubcommandArgsToInlineOptions(
 }
 
 function resolveSubcommandRequiresInput(packageEntry = {}, subcommandName = "") {
-  const descriptor = packageEntry?.descriptor && typeof packageEntry.descriptor === "object"
-    ? packageEntry.descriptor
-    : {};
-  const optionSchemas = descriptor?.options && typeof descriptor.options === "object"
-    ? descriptor.options
-    : {};
   const subcommandDefinition = resolveGeneratorSubcommandDefinitionMetadata(packageEntry, subcommandName);
   const positionalArgs = Array.isArray(subcommandDefinition?.positionalArgs)
     ? subcommandDefinition.positionalArgs
     : [];
-  if (positionalArgs.length > 0) {
-    return true;
-  }
-  const requiredOptionNames = Array.isArray(subcommandDefinition?.requiredOptionNames)
-    ? subcommandDefinition.requiredOptionNames
-    : [];
-  if (requiredOptionNames.some((optionName) => String(optionName || "").trim().length > 0)) {
-    return true;
-  }
-
-  const optionNames = Array.isArray(subcommandDefinition?.optionNames) && subcommandDefinition.optionNames.length > 0
-    ? subcommandDefinition.optionNames
-    : Object.keys(optionSchemas);
-  for (const optionName of optionNames) {
-    const normalizedOptionName = String(optionName || "").trim();
-    if (!normalizedOptionName) {
-      continue;
-    }
-    const schema = optionSchemas[normalizedOptionName];
-    if (schema && typeof schema === "object" && schema.required === true) {
-      return true;
-    }
-  }
-  return false;
+  return positionalArgs.some((arg) => arg && typeof arg === "object" && arg.required !== false);
 }
 
 function collectUnexpectedGeneratorSubcommandOptionNames(packageEntry = {}, subcommandName = "", inlineOptions = {}) {
@@ -230,7 +201,8 @@ async function runPackageGenerateCommand(
     hasGeneratorSubcommandDefinition,
     readdir,
     validateInlineOptionValuesForPackage,
-    runGeneratorSubcommand
+    runGeneratorSubcommand,
+    createCatalogFetchStatusReporter = () => () => {}
   } = ctx;
 
   const firstToken = String(positional[0] || "").trim();
@@ -244,6 +216,9 @@ async function runPackageGenerateCommand(
   const targetId = firstToken === "package" ? secondToken : firstToken;
   const subcommandName = firstToken === "package" ? thirdToken : secondToken;
   const subcommandArgs = firstToken === "package" ? positional.slice(3) : positional.slice(2);
+  const reportTemplateFetchStatus = createCatalogFetchStatusReporter(io, {
+    enabled: options.json !== true
+  });
 
   async function resolveGeneratorPackageEntry(packageIdInput = "") {
     const appRoot = await resolveAppRootFromCwd(cwd);
@@ -425,7 +400,8 @@ async function runPackageGenerateCommand(
 
     const templateRoot = await resolvePackageTemplateRoot({
       packageEntry,
-      appRoot
+      appRoot,
+      reportTemplateFetchStatus
     });
     const executablePackageEntry =
       templateRoot === packageEntry.rootDir

package/src/server/commandHandlers/shared.js

@@ -39,6 +39,44 @@ function createCommandHandlerShared(ctx = {}) {
     return lines.join("\n");
   }
 
+  function createCatalogFetchStatusReporter(io = {}, { enabled = true } = {}) {
+    if (enabled !== true) {
+      return () => {};
+    }
+
+    const stdout = io?.stdout;
+    if (!stdout || typeof stdout.write !== "function") {
+      return () => {};
+    }
+
+    const activeFetchLabels = new Set();
+    return ({ packageEntry, state } = {}) => {
+      const packageId = String(packageEntry?.packageId || "").trim();
+      const version = String(packageEntry?.version || "").trim();
+      const packageLabel = version ? `${packageId}@${version}` : packageId;
+      if (!packageLabel) {
+        return;
+      }
+
+      if (state === "start") {
+        if (activeFetchLabels.has(packageLabel)) {
+          return;
+        }
+        activeFetchLabels.add(packageLabel);
+        stdout.write(`Fetching ${packageLabel}...\n`);
+        return;
+      }
+
+      if (state === "complete") {
+        if (!activeFetchLabels.has(packageLabel)) {
+          return;
+        }
+        activeFetchLabels.delete(packageLabel);
+        stdout.write(`Fetching ${packageLabel}... done!\n`);
+      }
+    };
+  }
+
   async function runNpmInstall(appRoot, stderr) {
     await new Promise((resolve, reject) => {
       const child = spawn("npm", ["install"], {
@@ -298,6 +336,7 @@ function createCommandHandlerShared(ctx = {}) {
 
   return {
     renderResolvedSummary,
+    createCatalogFetchStatusReporter,
     runNpmInstall,
     getInstalledDependents,
     resolvePackageKind,

package/src/server/core/argParser.js

@@ -120,8 +120,9 @@ function parseArgs(argv, { createCliError } = {}) {
       if (hasInlineValue) {
         optionValueRaw = withoutPrefix.slice(withoutPrefix.indexOf("=") + 1);
       } else {
-        const nextToken = typeof args[0] === "string" ? String(args[0]) : "";
-        if (nextToken && !nextToken.startsWith("-")) {
+        const hasNextStringToken = typeof args[0] === "string";
+        const nextToken = hasNextStringToken ? String(args[0]) : "";
+        if (hasNextStringToken && !nextToken.startsWith("-")) {
           optionValueRaw = args.shift();
         }
       }