@jskit-ai/jskit-cli 0.2.39 → 0.2.41

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

@@ -1,9 +1,11 @@
+import path from "node:path";
 import {
   isHelpToken,
   renderGenerateCatalogHelp,
   renderGeneratePackageHelp,
   renderGenerateSubcommandHelp
 } from "./discoverabilityHelp.js";
+import { interpolateOptionValue } from "../../shared/optionInterpolation.js";
 
 function resolveGeneratorSubcommandDefinitionMetadata(packageEntry = {}, subcommandName = "") {
   const descriptor = packageEntry?.descriptor && typeof packageEntry.descriptor === "object"
@@ -25,6 +27,51 @@ function resolveGeneratorSubcommandDefinitionMetadata(packageEntry = {}, subcomm
   return definition && typeof definition === "object" ? definition : {};
 }
 
+function mapDescriptorBackedSubcommandArgsToInlineOptions(
+  packageEntry = {},
+  subcommandName = "",
+  subcommandArgs = [],
+  inlineOptions = {},
+  createCliError
+) {
+  const definition = resolveGeneratorSubcommandDefinitionMetadata(packageEntry, subcommandName);
+  const positionalArgs = Array.isArray(definition?.positionalArgs)
+    ? definition.positionalArgs
+    : [];
+  const providedArgs = Array.isArray(subcommandArgs) ? subcommandArgs : [];
+  if (providedArgs.length > positionalArgs.length) {
+    throw createCliError(
+      `Generator command "${subcommandName}" for ${String(packageEntry?.packageId || "unknown-package")} accepts at most ${positionalArgs.length} positional argument${positionalArgs.length === 1 ? "" : "s"}.`
+    );
+  }
+
+  const mappedInlineOptions = {
+    ...(inlineOptions && typeof inlineOptions === "object" ? inlineOptions : {})
+  };
+  for (const [index, rawValue] of providedArgs.entries()) {
+    const positionalArg = positionalArgs[index];
+    const optionName = String(positionalArg?.name || "").trim();
+    if (!optionName) {
+      throw createCliError(
+        `Generator command "${subcommandName}" for ${String(packageEntry?.packageId || "unknown-package")} defines positional arg ${index + 1} without a name.`
+      );
+    }
+
+    const value = String(rawValue || "").trim();
+    const existingValue = Object.prototype.hasOwnProperty.call(mappedInlineOptions, optionName)
+      ? String(mappedInlineOptions[optionName] || "").trim()
+      : null;
+    if (existingValue != null && existingValue !== value) {
+      throw createCliError(
+        `Generator command "${subcommandName}" for ${String(packageEntry?.packageId || "unknown-package")} received both positional "${optionName}" and --${optionName} with different values.`
+      );
+    }
+    mappedInlineOptions[optionName] = value;
+  }
+
+  return mappedInlineOptions;
+}
+
 function resolveSubcommandRequiresInput(packageEntry = {}, subcommandName = "") {
   const descriptor = packageEntry?.descriptor && typeof packageEntry.descriptor === "object"
     ? packageEntry.descriptor
@@ -62,6 +109,108 @@ function resolveSubcommandRequiresInput(packageEntry = {}, subcommandName = "")
   return false;
 }
 
+function collectUnexpectedGeneratorSubcommandOptionNames(packageEntry = {}, subcommandName = "", inlineOptions = {}) {
+  const subcommandDefinition = resolveGeneratorSubcommandDefinitionMetadata(packageEntry, subcommandName);
+  if (!Array.isArray(subcommandDefinition?.optionNames)) {
+    return [];
+  }
+
+  const allowedOptionNameSet = new Set(
+    subcommandDefinition.optionNames
+      .map((optionName) => String(optionName || "").trim())
+      .filter(Boolean)
+  );
+  return Object.keys(inlineOptions || {})
+    .map((optionName) => String(optionName || "").trim())
+    .filter(Boolean)
+    .filter((optionName) => !allowedOptionNameSet.has(optionName))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function resolveCreateTargetPolicy(packageEntry = {}, subcommandName = "") {
+  const definition = resolveGeneratorSubcommandDefinitionMetadata(packageEntry, subcommandName);
+  const createTarget = definition?.createTarget;
+  return createTarget && typeof createTarget === "object" ? createTarget : {};
+}
+
+function normalizeRelativePathWithinApp(appRoot = "", targetPath = "", createCliError) {
+  const normalizedTargetPath = String(targetPath || "").trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+  if (!normalizedTargetPath) {
+    throw createCliError("Generator create target path cannot be empty.");
+  }
+
+  const absolutePath = path.resolve(appRoot, normalizedTargetPath);
+  const relativePath = path.relative(appRoot, absolutePath);
+  if (
+    !relativePath ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath)
+  ) {
+    throw createCliError(`Generator create target must stay within app root: ${normalizedTargetPath}`);
+  }
+
+  return {
+    absolutePath,
+    relativePath: relativePath.split(path.sep).join("/")
+  };
+}
+
+async function enforceDescriptorBackedCreateTargetPolicy({
+  packageEntry,
+  subcommandName,
+  inlineOptions = {},
+  appRoot = "",
+  packageIdInput = "",
+  createCliError,
+  readdir
+} = {}) {
+  const policy = resolveCreateTargetPolicy(packageEntry, subcommandName);
+  const pathTemplate = String(policy.pathTemplate || "").trim();
+  if (!pathTemplate) {
+    return;
+  }
+
+  const forceOptionName = String(policy.forceOptionName || "force").trim() || "force";
+  const forceOverwrite = String(inlineOptions?.[forceOptionName] || "").trim().toLowerCase() === "true";
+  if (forceOverwrite) {
+    return;
+  }
+
+  const interpolatedTargetPath = interpolateOptionValue(
+    pathTemplate,
+    inlineOptions,
+    String(packageEntry?.packageId || "unknown-package"),
+    `${String(subcommandName || "generator")}.createTarget.pathTemplate`
+  );
+  const resolvedTargetPath = normalizeRelativePathWithinApp(appRoot, interpolatedTargetPath, createCliError);
+
+  try {
+    const entries = await readdir(resolvedTargetPath.absolutePath);
+    if (policy.allowExistingEmptyDirectory === true && entries.length < 1) {
+      return;
+    }
+
+    const commandLabel = `${String(packageIdInput || packageEntry?.packageId || "generator").trim()} ${String(subcommandName || "").trim()}`.trim();
+    const targetLabel = String(policy.label || "target").trim() || "target";
+    throw createCliError(
+      `${commandLabel} will not overwrite existing ${targetLabel} ${resolvedTargetPath.relativePath}. Re-run with --force to overwrite it.`
+    );
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return;
+    }
+    if (error?.code === "ENOTDIR") {
+      const commandLabel = `${String(packageIdInput || packageEntry?.packageId || "generator").trim()} ${String(subcommandName || "").trim()}`.trim();
+      const targetLabel = String(policy.label || "target").trim() || "target";
+      throw createCliError(
+        `${commandLabel} will not overwrite existing ${targetLabel} ${resolvedTargetPath.relativePath}. Re-run with --force to overwrite it.`
+      );
+    }
+    throw error;
+  }
+}
+
 async function runPackageGenerateCommand(
   ctx = {},
   { positional, options, cwd, io },
@@ -79,7 +228,10 @@ async function runPackageGenerateCommand(
     resolvePackageKind,
     resolveGeneratorPrimarySubcommand,
     hasGeneratorSubcommandDefinition,
-    runGeneratorSubcommand
+    readdir,
+    validateInlineOptionValuesForPackage,
+    runGeneratorSubcommand,
+    createCatalogFetchStatusReporter = () => () => {}
   } = ctx;
 
   const firstToken = String(positional[0] || "").trim();
@@ -93,6 +245,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);
@@ -145,27 +300,12 @@ async function runPackageGenerateCommand(
   }
 
   if (isHelpToken(subcommandName)) {
-    const helpSubcommandName = String(subcommandArgs[0] || "").trim();
-    if (subcommandArgs.length > 1) {
-      throw createCliError("generate help accepts at most one subcommand name.");
+    if (subcommandArgs.length > 0) {
+      throw createCliError(
+        `Unknown generator usage: jskit generate ${targetId} help ${subcommandArgs.join(" ")}. Use: jskit generate ${targetId} <subcommand> help`
+      );
     }
     const { packageEntry } = await resolveGeneratorPackageEntry(targetId);
-    if (helpSubcommandName) {
-      const rendered = renderGenerateSubcommandHelp({
-        io,
-        packageEntry,
-        packageIdInput: targetId,
-        subcommandName: helpSubcommandName,
-        json: options.json
-      });
-      if (!rendered) {
-        throw createCliError(
-          `Unknown generator subcommand "${helpSubcommandName}" for ${String(packageEntry?.packageId || targetId)}.`
-        );
-      }
-      return 0;
-    }
-
     renderGeneratePackageHelp({
       io,
       packageEntry,
@@ -175,56 +315,111 @@ async function runPackageGenerateCommand(
     return 0;
   }
 
-  if (subcommandName) {
-    const {
-      appRoot,
-      packageEntry,
-      resolvedPackageId
-    } = await resolveGeneratorPackageEntry(targetId);
+  async function runResolvedGeneratorSubcommand({
+    appRoot,
+    packageEntry,
+    resolvedPackageId,
+    subcommandName: rawSubcommandName = "",
+    subcommandArgs: rawSubcommandArgs = []
+  } = {}) {
+    const normalizedSubcommandName = String(rawSubcommandName || "").trim().toLowerCase();
+    const normalizedSubcommandArgs = Array.isArray(rawSubcommandArgs)
+      ? rawSubcommandArgs
+      : [];
     const hasInlineOptions = Object.keys(options?.inlineOptions || {}).length > 0;
-    const hasSubcommandArgs = subcommandArgs.length > 0;
-    if (!hasInlineOptions && !hasSubcommandArgs && resolveSubcommandRequiresInput(packageEntry, subcommandName)) {
+    const hasSubcommandArgs = normalizedSubcommandArgs.length > 0;
+    if (!hasInlineOptions && !hasSubcommandArgs && resolveSubcommandRequiresInput(packageEntry, normalizedSubcommandName)) {
       const rendered = renderGenerateSubcommandHelp({
         io,
         packageEntry,
         packageIdInput: targetId,
-        subcommandName,
+        subcommandName: normalizedSubcommandName,
         json: options.json
       });
       if (rendered) {
         return 0;
       }
     }
-    if (subcommandArgs.length === 1 && isHelpToken(subcommandArgs[0])) {
+    if (normalizedSubcommandArgs.length === 1 && isHelpToken(normalizedSubcommandArgs[0])) {
       const rendered = renderGenerateSubcommandHelp({
         io,
         packageEntry,
         packageIdInput: targetId,
-        subcommandName,
+        subcommandName: normalizedSubcommandName,
         json: options.json
       });
       if (!rendered) {
-        throw createCliError(`Unknown generator subcommand "${subcommandName}" for ${resolvedPackageId}.`);
+        throw createCliError(`Unknown generator subcommand "${normalizedSubcommandName}" for ${resolvedPackageId}.`);
       }
       return 0;
     }
 
-    const normalizedSubcommandName = String(subcommandName || "").trim().toLowerCase();
+    const subcommandDefinition = resolveGeneratorSubcommandDefinitionMetadata(packageEntry, normalizedSubcommandName);
+    const unexpectedOptionNames = collectUnexpectedGeneratorSubcommandOptionNames(
+      packageEntry,
+      normalizedSubcommandName,
+      options.inlineOptions
+    );
+    if (unexpectedOptionNames.length > 0) {
+      const commandLabel = String(targetId || resolvedPackageId || "").trim() || resolvedPackageId;
+      throw createCliError(
+        `Unknown option${unexpectedOptionNames.length === 1 ? "" : "s"} for generator command ${commandLabel} ${normalizedSubcommandName}: ${unexpectedOptionNames.map((optionName) => `--${optionName}`).join(", ")}.`,
+        {
+          renderUsage: options.json
+            ? null
+            : () => {
+                renderGenerateSubcommandHelp({
+                  io: {
+                    ...io,
+                    stdout: io.stderr || io.stdout
+                  },
+                  packageEntry,
+                  packageIdInput: targetId,
+                  subcommandName: normalizedSubcommandName,
+                  json: false
+                });
+              }
+        }
+      );
+    }
+    const validatedOptionNames = Array.isArray(subcommandDefinition?.optionNames)
+      ? subcommandDefinition.optionNames
+      : [];
+    await validateInlineOptionValuesForPackage(packageEntry, options.inlineOptions, {
+      appRoot,
+      optionNames: validatedOptionNames
+    });
+
     const primarySubcommand = resolveGeneratorPrimarySubcommand(packageEntry);
     if (
       normalizedSubcommandName &&
       normalizedSubcommandName === primarySubcommand &&
       !hasGeneratorSubcommandDefinition(packageEntry, normalizedSubcommandName)
     ) {
-      if (subcommandArgs.length > 0) {
-        throw createCliError(
-          `Generator command "${primarySubcommand}" for ${resolvedPackageId} does not accept positional arguments.`
-        );
-      }
+      const inlineOptionsForPrimarySubcommand = mapDescriptorBackedSubcommandArgsToInlineOptions(
+        packageEntry,
+        normalizedSubcommandName,
+        normalizedSubcommandArgs,
+        options.inlineOptions,
+        createCliError
+      );
+      await validateInlineOptionValuesForPackage(packageEntry, inlineOptionsForPrimarySubcommand, {
+        appRoot
+      });
+      await enforceDescriptorBackedCreateTargetPolicy({
+        packageEntry,
+        subcommandName: normalizedSubcommandName,
+        inlineOptions: inlineOptionsForPrimarySubcommand,
+        appRoot,
+        packageIdInput: targetId,
+        createCliError,
+        readdir
+      });
       return runCommandAdd({
         positional: ["package", resolvedPackageId],
         options: {
           ...options,
+          inlineOptions: inlineOptionsForPrimarySubcommand,
           commandMode: "generate"
         },
         cwd,
@@ -234,7 +429,8 @@ async function runPackageGenerateCommand(
 
     const templateRoot = await resolvePackageTemplateRoot({
       packageEntry,
-      appRoot
+      appRoot,
+      reportTemplateFetchStatus
     });
     const executablePackageEntry =
       templateRoot === packageEntry.rootDir
@@ -246,8 +442,8 @@ async function runPackageGenerateCommand(
 
     return runGeneratorSubcommand({
       packageEntry: executablePackageEntry,
-      subcommandName,
-      subcommandArgs,
+      subcommandName: normalizedSubcommandName,
+      subcommandArgs: normalizedSubcommandArgs,
       inlineOptions: options.inlineOptions,
       appRoot,
       io,
@@ -256,15 +452,23 @@ async function runPackageGenerateCommand(
     });
   }
 
-  return runCommandAdd({
-    positional: ["package", targetId],
-    options: {
-      ...options,
-      commandMode: "generate"
-    },
-    cwd,
-    io
+  if (subcommandName) {
+    const resolvedGeneratorPackage = await resolveGeneratorPackageEntry(targetId);
+    return runResolvedGeneratorSubcommand({
+      ...resolvedGeneratorPackage,
+      subcommandName,
+      subcommandArgs
+    });
+  }
+
+  const { packageEntry } = await resolveGeneratorPackageEntry(targetId);
+  renderGeneratePackageHelp({
+    io,
+    packageEntry,
+    packageIdInput: targetId,
+    json: options.json
   });
+  return 0;
 }
 
 export { runPackageGenerateCommand };

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

@@ -51,6 +51,7 @@ function parseArgs(argv, { createCliError } = {}) {
     inlineOptions: {}
   };
   const positional = [];
+  const allowLooseInlineOptionParsing = command === "generate";
 
   while (args.length > 0) {
     const token = String(args.shift() || "");
@@ -99,27 +100,45 @@ function parseArgs(argv, { createCliError } = {}) {
       options.help = true;
       continue;
     }
+    if (token === "--force") {
+      options.inlineOptions.force = "true";
+      continue;
+    }
 
     if (token.startsWith("--")) {
       const withoutPrefix = token.slice(2);
       const hasInlineValue = withoutPrefix.includes("=");
       const optionName = hasInlineValue ? withoutPrefix.slice(0, withoutPrefix.indexOf("=")) : withoutPrefix;
-      const optionValueRaw = hasInlineValue
-        ? withoutPrefix.slice(withoutPrefix.indexOf("=") + 1)
-        : args.shift();
-
-      if (!/^[a-z][a-z0-9-]*$/.test(optionName)) {
+      const optionNamePattern = allowLooseInlineOptionParsing
+        ? /^[A-Za-z][A-Za-z0-9_-]*$/
+        : /^[a-z][a-z0-9-]*$/;
+      if (!optionNamePattern.test(optionName)) {
         throw createCliError(`Unknown option: ${token}`, { showUsage: true });
       }
-      if (typeof optionValueRaw !== "string") {
-        throw createCliError(`--${optionName} requires a value.`, { showUsage: true });
+
+      let optionValueRaw;
+      if (hasInlineValue) {
+        optionValueRaw = withoutPrefix.slice(withoutPrefix.indexOf("=") + 1);
+      } else {
+        const nextToken = typeof args[0] === "string" ? String(args[0]) : "";
+        if (nextToken && !nextToken.startsWith("-")) {
+          optionValueRaw = args.shift();
+        }
       }
-      const optionValue = optionValueRaw.trim();
-      if (!hasInlineValue && optionValue.startsWith("-")) {
+
+      if (!allowLooseInlineOptionParsing && typeof optionValueRaw !== "string") {
         throw createCliError(`--${optionName} requires a value.`, { showUsage: true });
       }
+      if (typeof optionValueRaw === "string") {
+        const optionValue = optionValueRaw.trim();
+        if (!hasInlineValue && optionValue.startsWith("-")) {
+          throw createCliError(`--${optionName} requires a value.`, { showUsage: true });
+        }
+        options.inlineOptions[optionName] = optionValue;
+        continue;
+      }
 
-      options.inlineOptions[optionName] = optionValue;
+      options.inlineOptions[optionName] = undefined;
       continue;
     }
 

package/src/server/core/buildCommandDeps.js

@@ -18,6 +18,7 @@ function createCommandHandlerDeps(deps = {}) {
     hydratePackageRegistryFromInstalledNodeModules: deps.hydratePackageRegistryFromInstalledNodeModules,
     resolvePackageTemplateRoot: deps.resolvePackageTemplateRoot,
     validateInlineOptionsForPackage: deps.validateInlineOptionsForPackage,
+    validateInlineOptionValuesForPackage: deps.validateInlineOptionValuesForPackage,
     resolveLocalDependencyOrder: deps.resolveLocalDependencyOrder,
     validatePlannedCapabilityClosure: deps.validatePlannedCapabilityClosure,
     resolvePackageOptions: deps.resolvePackageOptions,
@@ -34,6 +35,7 @@ function createCommandHandlerDeps(deps = {}) {
     writeJsonFile: deps.writeJsonFile,
     writeFile: deps.writeFile,
     mkdir: deps.mkdir,
+    readdir: deps.readdir,
     path: deps.path,
     inspectPackageOfferings: deps.inspectPackageOfferings,
     buildFileWriteGroups: deps.buildFileWriteGroups,