@jskit-ai/jskit-cli 0.2.38 → 0.2.40

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

@@ -3,8 +3,23 @@ import {
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  createColorFormatter,
+  renderInlineCodeSpans,
+  writeWrappedLines
+} from "../../shared/outputFormatting.js";
 
 const JSKIT_SCOPE_PREFIX = "@jskit-ai/";
+const HELP_TEXT_BY_KEY = Object.freeze({
+  "page-target-file":
+    "Vue page file relative to src/pages/. It must resolve to a configured surface.",
+  "existing-page-target-file":
+    "Existing Vue page file relative to src/pages/. It must resolve to a configured surface.",
+  "existing-vue-sfc-target-file":
+    "Existing Vue SFC path relative to app root.",
+  "crud-target-root":
+    "Route root directory relative to src/pages/ (example: admin/products)."
+});
 
 function isHelpToken(value = "") {
   return String(value || "").trim().toLowerCase() === "help";
@@ -23,6 +38,15 @@ function resolvePackageSummary(entry = {}) {
   return String(descriptor.description || "").trim();
 }
 
+function resolveHelpText(rawValue = "", helpTextKey = "") {
+  const normalizedValue = String(rawValue || "").trim();
+  if (normalizedValue) {
+    return normalizedValue;
+  }
+
+  return String(HELP_TEXT_BY_KEY[String(helpTextKey || "").trim()] || "").trim();
+}
+
 function buildPackageOptionRows(packageEntry = {}) {
   const descriptor = ensureObject(packageEntry?.descriptor);
   const optionSchemas = ensureObject(descriptor.options);
@@ -37,7 +61,9 @@ function buildPackageOptionRows(packageEntry = {}) {
       defaultValue: String(schema.defaultValue || "").trim(),
       allowEmpty: schema.allowEmpty === true,
       promptLabel: String(schema.promptLabel || "").trim(),
-      promptHint: String(schema.promptHint || "").trim()
+      promptHint: String(schema.promptHint || "").trim(),
+      helpLabel: resolveHelpText(schema.helpLabel, schema.helpLabelKey),
+      helpHint: resolveHelpText(schema.helpHint, schema.helpHintKey)
     }));
   }
 
@@ -75,7 +101,7 @@ function normalizeSubcommandPositionalArgRows(rawRows = []) {
     rows.push(Object.freeze({
       name,
       required: row.required !== false,
-      description: String(row.description || "").trim()
+      description: resolveHelpText(row.description, row.descriptionKey)
     }));
   }
   return rows;
@@ -136,31 +162,112 @@ function normalizeHelpExampleRows(rawRows = []) {
   return rows;
 }
 
-function appendHelpExamples(lines = [], exampleRows = []) {
+function normalizeHelpNoteRows(rawRows = []) {
+  const rows = [];
+
+  for (const rawRow of ensureArray(rawRows)) {
+    if (typeof rawRow === "string") {
+      const note = String(rawRow || "").trim();
+      if (note) {
+        rows.push(note);
+      }
+      continue;
+    }
+
+    const row = ensureObject(rawRow);
+    const note = resolveHelpText(row.text || row.note || "", row.textKey || row.noteKey);
+    if (note) {
+      rows.push(note);
+    }
+  }
+
+  return rows;
+}
+
+function normalizeHelpParagraphRows(rawValue = "") {
+  if (Array.isArray(rawValue)) {
+    return normalizeHelpNoteRows(rawValue);
+  }
+
+  const sourceText = String(rawValue || "").trim();
+  if (!sourceText) {
+    return [];
+  }
+
+  return sourceText
+    .split(/\n\s*\n/u)
+    .map((paragraph) => paragraph.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).join(" "))
+    .filter(Boolean);
+}
+
+function appendHelpLongDescription(lines = [], rawLongDescription = "", { color = null } = {}) {
+  const paragraphs = normalizeHelpParagraphRows(rawLongDescription);
+  if (paragraphs.length < 1) {
+    return;
+  }
+
+  lines.push("");
+  lines.push(color ? color.heading("Long:") : "Long:");
+  appendSeparatedBlocks(lines, paragraphs.map((paragraph) => renderInlineCodeSpans(paragraph, color)));
+}
+
+function appendHelpExamples(lines = [], exampleRows = [], { color = null } = {}) {
   const examples = ensureArray(exampleRows);
   if (examples.length < 1) {
     return;
   }
 
   lines.push("");
-  lines.push(`Examples (${examples.length}):`);
-  for (const example of examples) {
-    const label = String(example?.label || "").trim();
-    if (label) {
-      lines.push(`- ${label}`);
-      for (const commandLine of ensureArray(example?.lines)) {
-        lines.push(`  ${commandLine}`);
+  lines.push(color ? color.heading(`Examples (${examples.length}):`) : `Examples (${examples.length}):`);
+  appendSeparatedBlocks(
+    lines,
+    examples.map((example) => {
+      const block = [];
+      const label = String(example?.label || "").trim();
+      if (label) {
+        block.push(`- ${color ? color.item(label) : label}`);
+        for (const commandLine of ensureArray(example?.lines)) {
+          block.push(`  ${commandLine}`);
+        }
+        return block;
       }
-      continue;
-    }
 
-    const commandLines = ensureArray(example?.lines);
-    if (commandLines.length < 1) {
-      continue;
+      const commandLines = ensureArray(example?.lines);
+      if (commandLines.length < 1) {
+        return block;
+      }
+      block.push(`- ${commandLines[0]}`);
+      for (const commandLine of commandLines.slice(1)) {
+        block.push(`  ${commandLine}`);
+      }
+      return block;
+    }).filter((block) => block.length > 0)
+  );
+}
+
+function appendHelpNotes(lines = [], rawNotes = [], { color = null } = {}) {
+  const notes = normalizeHelpNoteRows(rawNotes);
+  if (notes.length < 1) {
+    return;
+  }
+
+  lines.push("");
+  lines.push(color ? color.heading(`Notes (${notes.length}):`) : `Notes (${notes.length}):`);
+  appendSeparatedBlocks(
+    lines,
+    notes.map((note) => `- ${renderInlineCodeSpans(note, color)}`)
+  );
+}
+
+function appendSeparatedBlocks(lines = [], blocks = []) {
+  const normalizedBlocks = ensureArray(blocks);
+  for (const [index, block] of normalizedBlocks.entries()) {
+    if (index > 0) {
+      lines.push("");
     }
-    lines.push(`- ${commandLines[0]}`);
-    for (const commandLine of commandLines.slice(1)) {
-      lines.push(`  ${commandLine}`);
+    const lineList = Array.isArray(block) ? block : [block];
+    for (const line of lineList) {
+      lines.push(line);
     }
   }
 }
@@ -194,10 +301,12 @@ function resolveGeneratorSubcommandMetadata(packageEntry = {}) {
       exportName,
       primary: primarySubcommand === name.toLowerCase(),
       description: String(definition.description || "").trim(),
+      longDescription: normalizeHelpParagraphRows(definition.longDescription),
       positionalArgs: normalizeSubcommandPositionalArgRows(definition.positionalArgs),
       optionNames,
       requiredOptionNames,
-      examples: normalizeHelpExampleRows(definition.examples)
+      examples: normalizeHelpExampleRows(definition.examples),
+      notes: normalizeHelpNoteRows(definition.notes)
     }));
   }
 
@@ -207,7 +316,7 @@ function resolveGeneratorSubcommandMetadata(packageEntry = {}) {
   });
 }
 
-function formatOptionSummary(optionRow = {}) {
+function formatOptionSummary(optionRow = {}, { color = null } = {}) {
   const status = optionRow.required ? "required" : "optional";
   const hasDefaultValue = String(optionRow.defaultValue || "").length > 0;
   const optionalDefaultSuffix = optionRow.required
@@ -217,14 +326,22 @@ function formatOptionSummary(optionRow = {}) {
     ? `; default: ${optionRow.defaultValue}`
     : optionalDefaultSuffix;
   const allowEmptySuffix = optionRow.allowEmpty ? "; allow-empty" : "";
-  const labelParts = [optionRow.promptLabel, optionRow.promptHint].filter(Boolean);
+  const labelParts = [
+    String(optionRow.helpLabel || "").trim() || String(optionRow.promptLabel || "").trim(),
+    String(optionRow.helpHint || "").trim() || String(optionRow.promptHint || "").trim()
+  ].filter(Boolean);
   const label = labelParts.join(". ");
-  const typeSuffix = optionRow.inputType ? `<${optionRow.inputType}> ` : "";
+  const normalizedInputType = String(optionRow.inputType || "").trim().toLowerCase();
+  const typeSuffix = normalizedInputType && normalizedInputType !== "flag" && normalizedInputType !== "boolean"
+    ? `<${optionRow.inputType}> `
+    : "";
   const baseDescription = label || "No description provided.";
   const description = optionRow.name === "placement-component-token"
-    ? `${baseDescription} Use jskit list-link-items to discover link-item tokens.`
+    ? `${baseDescription} Use \`jskit list-link-items\` to discover link-item tokens.`
     : baseDescription;
-  return `- --${optionRow.name} ${typeSuffix}[${status}${defaultSuffix}${allowEmptySuffix}]: ${description}`.trim();
+  const optionName = `--${optionRow.name}`;
+  const renderedOptionName = color ? color.item(optionName) : optionName;
+  return `- ${renderedOptionName} ${typeSuffix}[${status}${defaultSuffix}${allowEmptySuffix}]: ${renderInlineCodeSpans(description, color)}`.trim();
 }
 
 function formatPositionalArgUsageToken(arg = {}) {
@@ -238,14 +355,15 @@ function formatPositionalArgUsageToken(arg = {}) {
   return name;
 }
 
-function formatPositionalArgSummary(arg = {}) {
+function formatPositionalArgSummary(arg = {}, { color = null } = {}) {
   const name = String(arg.name || "").trim();
   if (!name) {
     return "";
   }
   const status = arg.required === false ? "optional" : "required";
-  const description = String(arg.description || "").trim() || "No description provided.";
-  return `- ${name} [${status}]: ${description}`;
+  const description = renderInlineCodeSpans(String(arg.description || "").trim() || "No description provided.", color);
+  const renderedName = color ? color.item(name) : name;
+  return `- ${renderedName} [${status}]: ${description}`;
 }
 
 function findGeneratorSubcommandRow(packageEntry = {}, subcommandName = "") {
@@ -326,23 +444,29 @@ function renderGenerateCatalogHelp({
     return;
   }
 
+  const color = createColorFormatter(io.stdout);
   const lines = [];
-  lines.push("Generate command");
+  lines.push(color.heading("Generate command"));
   lines.push("");
-  lines.push(`Available generators (${generators.length}):`);
+  lines.push(color.heading(`Available generators (${generators.length}):`));
   for (const generator of generators) {
     const shortIdSuffix =
-      generator.shortId && generator.shortId !== generator.packageId ? `${generator.shortId} ` : "";
+      generator.shortId && generator.shortId !== generator.packageId
+        ? `${color.item(generator.shortId)} `
+        : "";
     const versionSuffix = generator.version ? ` (${generator.version})` : "";
     const descriptionSuffix = generator.description ? `: ${generator.description}` : "";
-    lines.push(`- ${shortIdSuffix}${generator.packageId}${versionSuffix}${descriptionSuffix}`.trim());
+    lines.push(`- ${shortIdSuffix}${color.item(generator.packageId)}${versionSuffix}${descriptionSuffix}`.trim());
   }
   lines.push("");
-  lines.push("Use:");
+  lines.push(color.heading("Use:"));
   lines.push("- jskit generate <generatorId> help");
   lines.push("- jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...]");
   lines.push("- jskit list generators");
-  io.stdout.write(`${lines.join("\n")}\n`);
+  writeWrappedLines({
+    stdout: io.stdout,
+    lines
+  });
 }
 
 function renderAddCatalogHelp({
@@ -390,34 +514,38 @@ function renderAddCatalogHelp({
     return;
   }
 
+  const color = createColorFormatter(io.stdout);
   const lines = [];
-  lines.push("Add command");
+  lines.push(color.heading("Add command"));
   lines.push("");
-  lines.push(`Available bundles (${bundles.length}):`);
+  lines.push(color.heading(`Available bundles (${bundles.length}):`));
   for (const bundle of bundles) {
     const versionSuffix = bundle.version ? ` (${bundle.version})` : "";
     const countSuffix = ` [packages:${bundle.packageCount}]`;
     const descriptionSuffix = bundle.description ? `: ${bundle.description}` : "";
-    lines.push(`- ${bundle.bundleId}${versionSuffix}${countSuffix}${descriptionSuffix}`);
+    lines.push(`- ${color.item(bundle.bundleId)}${versionSuffix}${countSuffix}${descriptionSuffix}`);
   }
   lines.push("");
-  lines.push(`Available runtime packages (${runtimePackages.length}):`);
+  lines.push(color.heading(`Available runtime packages (${runtimePackages.length}):`));
   for (const runtimePackage of runtimePackages) {
     const shortIdSuffix =
       runtimePackage.shortId && runtimePackage.shortId !== runtimePackage.packageId
-        ? `${runtimePackage.shortId} `
+        ? `${color.item(runtimePackage.shortId)} `
         : "";
     const versionSuffix = runtimePackage.version ? ` (${runtimePackage.version})` : "";
     const descriptionSuffix = runtimePackage.description ? `: ${runtimePackage.description}` : "";
-    lines.push(`- ${shortIdSuffix}${runtimePackage.packageId}${versionSuffix}${descriptionSuffix}`.trim());
+    lines.push(`- ${shortIdSuffix}${color.item(runtimePackage.packageId)}${versionSuffix}${descriptionSuffix}`.trim());
   }
   lines.push("");
-  lines.push("Use:");
+  lines.push(color.heading("Use:"));
   lines.push("- jskit add package <packageId> help");
   lines.push("- jskit add bundle <bundleId> help");
   lines.push("- jskit add package <packageId> [--<option> <value>...]");
   lines.push("- jskit add bundle <bundleId> [--<option> <value>...]");
-  io.stdout.write(`${lines.join("\n")}\n`);
+  writeWrappedLines({
+    stdout: io.stdout,
+    lines
+  });
 }
 
 function renderGeneratePackageHelp({
@@ -434,13 +562,11 @@ function renderGeneratePackageHelp({
   const preferredId = toShortPackageId(packageId) || packageId;
   const usage = Object.freeze([
     `jskit generate ${preferredId} help`,
-    `jskit generate ${preferredId} help <subcommand>`,
     `jskit generate ${preferredId} <subcommand> help`,
     `jskit generate ${preferredId} [subcommand] [subcommand args...] [--<option> <value>...]`
   ]);
   const resolvedFrom = String(packageIdInput || "").trim();
   const resolvedFromLabel = resolvedFrom && resolvedFrom !== packageId ? resolvedFrom : "";
-  const hasRequiredWithDefaults = optionRows.some((row) => row.required && row.defaultValue);
 
   if (json) {
     io.stdout.write(`${JSON.stringify({
@@ -458,47 +584,60 @@ function renderGeneratePackageHelp({
     return;
   }
 
+  const color = createColorFormatter(io.stdout);
   const lines = [];
-  lines.push(`Generator help: ${packageId}`);
+  lines.push(`Generator help: ${color.emphasis(packageId)}`);
   if (resolvedFromLabel) {
-    lines.push(`Resolved from: ${resolvedFromLabel}`);
+    lines.push(`Resolved from: ${color.item(resolvedFromLabel)}`);
   }
   if (summary) {
     lines.push(`Description: ${summary}`);
   }
   lines.push("");
-  lines.push("Use:");
+  lines.push(color.heading("Use:"));
   for (const usageLine of usage) {
     lines.push(`- ${usageLine}`);
   }
   lines.push("");
 
   const subcommands = ensureArray(generatorMetadata.subcommands);
+  const shouldShowPackageExamples = subcommands.length < 1;
+  const shouldShowPackageOptions = subcommands.length < 1;
+  const hasRequiredWithDefaults = optionRows.some((row) => row.required && row.defaultValue);
   if (subcommands.length > 0) {
-    lines.push(`Subcommands (${subcommands.length}):`);
+    lines.push(color.heading(`Subcommands (${subcommands.length}):`));
     for (const subcommand of subcommands) {
-      const primarySuffix = subcommand.primary ? " [primary]" : "";
+      const primarySuffix = subcommand.primary ? color.dim(" [primary]") : "";
       const descriptionSuffix = subcommand.description ? `: ${subcommand.description}` : "";
-      lines.push(`- ${subcommand.name}${primarySuffix}${descriptionSuffix}`);
+      lines.push(`- ${color.item(subcommand.name)}${primarySuffix}${descriptionSuffix}`);
     }
-    lines.push("- Use subcommand help for details: jskit generate <generatorId> <subcommand> help");
+    lines.push("");
+    lines.push("Use subcommand help for positional args, options, notes, and examples:");
+    lines.push(`  ${color.item("jskit generate <generatorId> <subcommand> help")}`);
   }
 
-  appendHelpExamples(lines, primarySubcommandRow?.examples);
-  lines.push("");
-  lines.push(`Options (${optionRows.length}):`);
-  if (optionRows.length > 0) {
-    for (const optionRow of optionRows) {
-      lines.push(formatOptionSummary(optionRow));
-    }
-  } else {
-    lines.push("- No inline options.");
+  if (shouldShowPackageExamples) {
+    appendHelpExamples(lines, primarySubcommandRow?.examples, { color });
   }
-  if (hasRequiredWithDefaults) {
+  if (shouldShowPackageOptions) {
     lines.push("");
-    lines.push("Note: required options with defaults are auto-filled when omitted.");
+    lines.push(color.heading(`Options (${optionRows.length}):`));
+    if (optionRows.length > 0) {
+      for (const optionRow of optionRows) {
+        lines.push(formatOptionSummary(optionRow, { color }));
+      }
+    } else {
+      lines.push("- No inline options.");
+    }
+    if (hasRequiredWithDefaults) {
+      lines.push("");
+      lines.push("Note: required options with defaults are auto-filled when omitted.");
+    }
   }
-  io.stdout.write(`${lines.join("\n")}\n`);
+  writeWrappedLines({
+    stdout: io.stdout,
+    lines
+  });
 }
 
 function renderGenerateSubcommandHelp({
@@ -551,8 +690,10 @@ function renderGenerateSubcommandHelp({
         name: subcommandRow.name,
         primary: subcommandRow.primary,
         description: effectiveDescription,
+        longDescription: ensureArray(subcommandRow.longDescription),
         positionalArgs,
         examples: ensureArray(subcommandRow.examples),
+        notes: ensureArray(subcommandRow.notes),
         options: subcommandOptionRows
       },
       usage
@@ -560,47 +701,49 @@ function renderGenerateSubcommandHelp({
     return true;
   }
 
+  const color = createColorFormatter(io.stdout);
   const lines = [];
-  lines.push(`Generator subcommand help: ${packageId} ${subcommandRow.name}`);
+  lines.push(`Generator subcommand help: ${color.emphasis(packageId)} ${color.item(subcommandRow.name)}`);
   if (resolvedFromLabel) {
-    lines.push(`Resolved from: ${resolvedFromLabel}`);
-  }
-  if (summary) {
-    lines.push(`Generator: ${summary}`);
-  }
-  lines.push(`Description: ${effectiveDescription}`);
-  if (subcommandRow.primary) {
-    lines.push("Note: this is the primary generator command (same behavior as running without a subcommand).");
+    lines.push(`Resolved from: ${color.item(resolvedFromLabel)}`);
   }
+  lines.push(`Description: ${renderInlineCodeSpans(effectiveDescription, color)}`);
+  appendHelpLongDescription(lines, subcommandRow.longDescription, { color });
   lines.push("");
-  lines.push("Use:");
+  lines.push(color.heading("Use:"));
   for (const usageLine of usage) {
     lines.push(`- ${usageLine}`);
   }
   lines.push("");
-  lines.push(`Positional args (${positionalArgs.length}):`);
+  lines.push(color.heading(`Positional args (${positionalArgs.length}):`));
   if (positionalArgs.length > 0) {
-    for (const positionalArg of positionalArgs) {
-      lines.push(formatPositionalArgSummary(positionalArg));
-    }
+    appendSeparatedBlocks(
+      lines,
+      positionalArgs.map((positionalArg) => formatPositionalArgSummary(positionalArg, { color }))
+    );
   } else {
     lines.push("- No positional arguments.");
   }
+  appendHelpExamples(lines, subcommandRow.examples, { color });
+  appendHelpNotes(lines, subcommandRow.notes, { color });
   lines.push("");
-  lines.push(`Options (${subcommandOptionRows.length}):`);
+  lines.push(color.heading(`Options (${subcommandOptionRows.length}):`));
   if (subcommandOptionRows.length > 0) {
-    for (const optionRow of subcommandOptionRows) {
-      lines.push(formatOptionSummary(optionRow));
-    }
+    appendSeparatedBlocks(
+      lines,
+      subcommandOptionRows.map((optionRow) => formatOptionSummary(optionRow, { color }))
+    );
   } else {
     lines.push("- No inline options.");
   }
-  appendHelpExamples(lines, subcommandRow.examples);
   if (hasRequiredWithDefaults) {
     lines.push("");
     lines.push("Note: required options with defaults are auto-filled when omitted.");
   }
-  io.stdout.write(`${lines.join("\n")}\n`);
+  writeWrappedLines({
+    stdout: io.stdout,
+    lines
+  });
   return true;
 }
 
@@ -635,25 +778,27 @@ function renderAddPackageHelp({
     return;
   }
 
+  const color = createColorFormatter(io.stdout);
   const lines = [];
-  lines.push(`Package help: ${packageId}`);
+  lines.push(`Package help: ${color.emphasis(packageId)}`);
   if (resolvedFromLabel) {
-    lines.push(`Resolved from: ${resolvedFromLabel}`);
+    lines.push(`Resolved from: ${color.item(resolvedFromLabel)}`);
   }
   if (summary) {
     lines.push(`Description: ${summary}`);
   }
   lines.push("");
-  lines.push("Use:");
+  lines.push(color.heading("Use:"));
   for (const usageLine of usage) {
     lines.push(`- ${usageLine}`);
   }
   lines.push("");
-  lines.push(`Options (${optionRows.length}):`);
+  lines.push(color.heading(`Options (${optionRows.length}):`));
   if (optionRows.length > 0) {
-    for (const optionRow of optionRows) {
-      lines.push(formatOptionSummary(optionRow));
-    }
+    appendSeparatedBlocks(
+      lines,
+      optionRows.map((optionRow) => formatOptionSummary(optionRow, { color }))
+    );
   } else {
     lines.push("- No inline options.");
   }
@@ -661,7 +806,10 @@ function renderAddPackageHelp({
     lines.push("");
     lines.push("Note: required options with defaults are auto-filled when omitted.");
   }
-  io.stdout.write(`${lines.join("\n")}\n`);
+  writeWrappedLines({
+    stdout: io.stdout,
+    lines
+  });
 }
 
 function renderAddBundleHelp({
@@ -691,27 +839,33 @@ function renderAddBundleHelp({
     return;
   }
 
+  const color = createColorFormatter(io.stdout);
   const lines = [];
-  lines.push(`Bundle help: ${bundleId}`);
+  lines.push(`Bundle help: ${color.emphasis(bundleId)}`);
   if (description) {
     lines.push(`Description: ${description}`);
   }
   lines.push("");
-  lines.push(`Included packages (${packageIds.length}):`);
+  lines.push(color.heading(`Included packages (${packageIds.length}):`));
   for (const packageId of packageIds) {
-    lines.push(`- ${packageId}`);
+    lines.push(`- ${color.item(packageId)}`);
   }
   lines.push("");
-  lines.push("Inline options:");
-  lines.push("- Bundles do not define direct options.");
-  lines.push("- Pass package options through using --<option> <value>.");
-  lines.push("- Use package help to inspect option contracts for included packages.");
+  lines.push(color.heading("Inline options:"));
+  appendSeparatedBlocks(lines, [
+    "- Bundles do not define direct options.",
+    "- Pass package options through using --<option> <value>.",
+    "- Use package help to inspect option contracts for included packages."
+  ]);
   lines.push("");
-  lines.push("Use:");
+  lines.push(color.heading("Use:"));
   for (const usageLine of usage) {
     lines.push(`- ${usageLine}`);
   }
-  io.stdout.write(`${lines.join("\n")}\n`);
+  writeWrappedLines({
+    stdout: io.stdout,
+    lines
+  });
 }
 
 export {