@jskit-ai/jskit-cli 0.2.39 → 0.2.40

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,6 +228,8 @@ async function runPackageGenerateCommand(
     resolvePackageKind,
     resolveGeneratorPrimarySubcommand,
     hasGeneratorSubcommandDefinition,
+    readdir,
+    validateInlineOptionValuesForPackage,
     runGeneratorSubcommand
   } = ctx;
 
@@ -145,27 +296,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 +311,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,
@@ -246,8 +437,8 @@ async function runPackageGenerateCommand(
 
     return runGeneratorSubcommand({
       packageEntry: executablePackageEntry,
-      subcommandName,
-      subcommandArgs,
+      subcommandName: normalizedSubcommandName,
+      subcommandArgs: normalizedSubcommandArgs,
       inlineOptions: options.inlineOptions,
       appRoot,
       io,
@@ -256,15 +447,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/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,

package/src/server/core/createCliRunner.js

@@ -1,5 +1,6 @@
 import {
   mkdir,
+  readdir,
   rm,
   writeFile
 } from "node:fs/promises";
@@ -67,7 +68,8 @@ import {
 } from "../cliRuntime/packageIntrospection.js";
 import {
   resolvePackageOptions,
-  validateInlineOptionsForPackage
+  validateInlineOptionsForPackage,
+  validateInlineOptionValuesForPackage
 } from "../cliRuntime/packageOptions.js";
 import {
   resolvePackageTemplateRoot,
@@ -103,6 +105,7 @@ const commandHandlers = createCommandHandlers(
     hydratePackageRegistryFromInstalledNodeModules,
     resolvePackageTemplateRoot,
     validateInlineOptionsForPackage,
+    validateInlineOptionValuesForPackage,
     resolveLocalDependencyOrder,
     validatePlannedCapabilityClosure,
     resolvePackageOptions,
@@ -119,6 +122,7 @@ const commandHandlers = createCommandHandlers(
     writeJsonFile,
     writeFile,
     mkdir,
+    readdir,
     path,
     inspectPackageOfferings,
     buildFileWriteGroups,

package/src/server/core/dispatchCli.js

@@ -122,7 +122,9 @@ function createRunCli({
       throw createCliError(`Unhandled command: ${command}`, { showUsage: true });
     } catch (error) {
       stderr.write(`jskit: ${error?.message || String(error)}\n`);
-      if (error?.showUsage) {
+      if (typeof error?.renderUsage === "function") {
+        error.renderUsage();
+      } else if (error?.showUsage) {
         printUsage(stderr);
       }
       return 1;

package/src/server/core/usageHelp.js

@@ -1,4 +1,8 @@
 import { resolveCommandAlias } from "./commandCatalog.js";
+import {
+  createColorFormatter,
+  writeWrappedLines
+} from "../shared/outputFormatting.js";
 
 const COMMAND_OVERVIEW = Object.freeze([
   Object.freeze({
@@ -114,9 +118,26 @@ const COMMAND_HELP = Object.freeze({
       "No npm install runs unless --run-npm-install is passed.",
       "Short ids resolve to @jskit-ai/<id> when available.",
       "Running without args lists available generators.",
-      "If no subcommand is provided, the generator primary command runs.",
+      "Running with only <generatorId> shows generator help.",
       "Use jskit generate <generatorId> <subcommand> help for subcommand-specific usage."
     ]),
+    examples: Object.freeze([
+      Object.freeze({
+        label: "Common usage",
+        lines: Object.freeze([
+          "npx jskit generate ui-generator page \\",
+          "  admin/reports/index.vue"
+        ])
+      }),
+      Object.freeze({
+        label: "More advanced usage",
+        lines: Object.freeze([
+          "npx jskit generate crud-ui-generator crud \\",
+          "  admin/catalog/index/products \\",
+          "  --resource-file packages/products/src/shared/productResource.js"
+        ])
+      })
+    ]),
     fullUse: "jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...] [--dry-run] [--run-npm-install] [--json] [--verbose]"
   }),
   list: Object.freeze({
@@ -297,22 +318,41 @@ const BARE_COMMAND_HELP = new Set([
   "remove"
 ]);
 
-function writeLine(stream, line = "") {
-  stream.write(`${line}\n`);
+function appendSeparatedBlocks(lines = [], blocks = []) {
+  const normalizedBlocks = Array.isArray(blocks) ? blocks : [];
+  for (const [index, block] of normalizedBlocks.entries()) {
+    if (index > 0) {
+      lines.push("");
+    }
+    const lineList = Array.isArray(block) ? block : [block];
+    for (const line of lineList) {
+      lines.push(line);
+    }
+  }
+}
+
+function writeHelpLines(stream, lines = []) {
+  writeWrappedLines({
+    stdout: stream,
+    lines
+  });
 }
 
 function printTopLevelHelp(stream = process.stderr) {
-  writeLine(stream, "JSKit CLI");
-  writeLine(stream, "");
-  writeLine(stream, "Use: jskit help <command> for command-specific usage.");
-  writeLine(stream, "");
-  writeLine(stream, "Available commands:");
+  const color = createColorFormatter(stream);
+  const lines = [];
+  lines.push(color.heading("JSKit CLI"));
+  lines.push("");
+  lines.push("Use: jskit help <command> for command-specific usage.");
+  lines.push("");
+  lines.push(color.heading("Available commands:"));
   for (const entry of COMMAND_OVERVIEW) {
-    writeLine(stream, `  ${entry.command.padEnd(16, " ")} ${entry.summary}`);
+    lines.push(`  ${color.item(entry.command.padEnd(16, " "))} ${entry.summary}`);
   }
-  writeLine(stream, "");
-  writeLine(stream, "Global flags:");
-  writeLine(stream, "  --dry-run --run-npm-install --json --verbose --help");
+  lines.push("");
+  lines.push(color.heading("Global flags:"));
+  lines.push("  --dry-run --run-npm-install --json --verbose --help");
+  writeHelpLines(stream, lines);
 }
 
 function printCommandHelp(stream = process.stderr, command = "") {
@@ -323,27 +363,54 @@ function printCommandHelp(stream = process.stderr, command = "") {
     return;
   }
 
-  writeLine(stream, `Command: ${entry.title}`);
-  writeLine(stream, "");
+  const color = createColorFormatter(stream);
+  const lines = [];
+  lines.push(`Command: ${color.emphasis(entry.title)}`);
+  lines.push("");
+
+  let sectionNumber = 1;
 
-  writeLine(stream, "1) Minimal use");
-  writeLine(stream, `   ${entry.minimalUse}`);
+  lines.push(color.heading(`${sectionNumber++}) Minimal use`));
+  lines.push(`   ${entry.minimalUse}`);
   if (entry.parameters.length > 0) {
-    writeLine(stream, "   Parameters:");
-    for (const parameter of entry.parameters) {
-      writeLine(stream, `   - ${parameter.name}: ${parameter.description}`);
-    }
+    lines.push(color.heading("   Parameters:"));
+    appendSeparatedBlocks(
+      lines,
+      entry.parameters.map((parameter) => `   - ${parameter.name}: ${parameter.description}`)
+    );
   }
-  writeLine(stream, "");
+  lines.push("");
+
+  lines.push(color.heading(`${sectionNumber++}) Defaults`));
+  appendSeparatedBlocks(
+    lines,
+    entry.defaults.map((defaultLine) => `   - ${defaultLine}`)
+  );
+  lines.push("");
 
-  writeLine(stream, "2) Defaults");
-  for (const defaultLine of entry.defaults) {
-    writeLine(stream, `   - ${defaultLine}`);
+  const examples = Array.isArray(entry.examples) ? entry.examples : [];
+  if (examples.length > 0) {
+    lines.push(color.heading(`${sectionNumber++}) Examples`));
+    appendSeparatedBlocks(
+      lines,
+      examples.map((example) => {
+        const block = [];
+        const label = String(example?.label || "").trim();
+        if (label) {
+          block.push(`   - ${color.item(label)}`);
+        }
+        for (const line of Array.isArray(example?.lines) ? example.lines : []) {
+          block.push(`     ${line}`);
+        }
+        return block;
+      })
+    );
+    lines.push("");
   }
-  writeLine(stream, "");
 
-  writeLine(stream, "3) Full use");
-  writeLine(stream, `   ${entry.fullUse}`);
+  lines.push(color.heading(`${sectionNumber++}) Full use`));
+  lines.push(`   ${entry.fullUse}`);
+  writeHelpLines(stream, lines);
 }
 
 function printUsage(stream = process.stderr, { command = "" } = {}) {

package/src/server/shared/cliError.js

@@ -1,8 +1,9 @@
-function createCliError(message, { showUsage = false, exitCode = 1 } = {}) {
+function createCliError(message, { showUsage = false, exitCode = 1, renderUsage = null } = {}) {
   const error = new Error(String(message || "Unknown CLI error"));
   error.name = "CliError";
   error.showUsage = Boolean(showUsage);
   error.exitCode = Number.isInteger(exitCode) ? exitCode : 1;
+  error.renderUsage = typeof renderUsage === "function" ? renderUsage : null;
   return error;
 }