Merge branch 'jeppe-cursor/auto-spawn-child-host-900b' into jeppe-cursor/attach-preferred-default-900b

Author: cursoragent

code/core/src/cli/tools/help.ts

@@ -1,13 +1,12 @@
 import * as v from 'valibot';
 
 import {
-  resolveToolsetDescription,
   type AnyToolsetDefinition,
   type AnyToolsetMethod,
   type ToolsetCtx,
 } from '../../shared/open-service/toolset-definition.ts';
 import { parseToolsetMethodId, toCliMethodName } from '../../shared/open-service/toolset-names.ts';
-import { toToolsetJsonSchema } from './sdk/json-schema.ts';
+import { toCatalogEntry } from './sdk/catalog.ts';
 import type { ToolsetCatalog, ToolsetCatalogEntry, ToolsetCatalogMethod } from './sdk/types.ts';
 import {
   JsonSchemaNodeSchema,
@@ -25,135 +24,43 @@ function optionLines(): string[] {
   return TOOLS_OPTION_SPECS.map((spec) => `  ${spec.flags.padEnd(column)}${spec.description}`);
 }
 
-/**
- * One line per tool for the `Commands:` listing, in commander's shape: the subcommand padded to a
- * shared column, a one-sentence summary, and the execution badge.
- */
-function commandLines(toolsets: AnyToolsetDefinition[], _ctx: ToolsetCtx): string[] {
-  const commands = toolsets.flatMap((toolset) =>
-    Object.entries(toolset.methods).map(([methodKey, method]) => ({
-      path: cliPath(toolset, methodKey),
-      summary: method.title,
-      badge: badge(method),
-    }))
-  );
-  const column = Math.max(...commands.map((command) => command.path.length)) + 2;
-  return commands.map(
-    (command) => `  ${command.path.padEnd(column)}${command.summary}  ${command.badge}`
-  );
-}
-
 function indented(lines: string[], depth: number): string[] {
   const pad = ' '.repeat(depth);
   // Descriptions and schema lines carry embedded newlines; every physical line gets the base
   // indent or the body's continuation lines would fall back to column 0.
   return lines.flatMap((line) => line.split('\n')).map((line) => (line ? pad + line : line));
 }
 
-function cliPath(toolset: AnyToolsetDefinition, methodKey: string): string {
-  return `${toolset.id} ${toCliMethodName(methodKey)}`;
-}
-
-/**
- * The complete agent discovery surface, in commander's conventional shape — Usage, Options, and a
- * `Commands:` listing with one-line summaries — followed by a full reference for every tool
- * (description, input schema, declared output schema) so agents learn the surface from this single
- * invocation instead of paying a project load per lookup. The Options block is the flags' only
- * documentation, since commander's own help is disabled in favor of this runtime-derived one.
- */
-export function renderToolsHelp(
-  configDir: string,
-  toolsets: AnyToolsetDefinition[],
-  ctx: ToolsetCtx
-): string {
-  const header = [
-    'Usage: npx storybook tools [options] [toolset] [tool] [args...]',
-    '',
-    `Storybook tools from the Storybook configuration at ${configDir}.`,
-    '',
-    'Options:',
-    ...optionLines(),
-    '',
-    'Commands:',
-    ...commandLines(toolsets, ctx),
-  ].join('\n');
-  const notes = [
-    `${LOCAL_BADGE} tools run in this process, without a running Storybook.`,
-    `${DEV_SERVER_BADGE} tools need a running Storybook dev server; start it first.`,
-    'Individual `--key value` flags override entries of `--input`.',
-  ].join('\n');
-  const referenceIntro =
-    'Tool reference — every command in full (`npx storybook tools <toolset> <tool> --help` shows one alone):';
-  const sections = [header, notes, referenceIntro];
-  for (const toolset of toolsets) {
-    sections.push(renderToolsetSection(toolset, ctx));
-  }
-  return sections.join('\n\n');
+function cliPath(method: ToolsetCatalogMethod): string {
+  const { toolsetId, methodName } = parseToolsetMethodId(method.ref);
+  return `${toolsetId} ${toCliMethodName(methodName)}`;
 }
 
-/** The focused view of one toolset (`storybook tools <toolset>`). */
-export function renderToolsetHelp(toolset: AnyToolsetDefinition, ctx: ToolsetCtx): string {
-  return [
-    `Usage: npx storybook tools ${toolset.id} <tool> [--key value ...]`,
-    '',
-    renderToolsetSection(toolset, ctx),
-  ].join('\n');
+function badge(method: ToolsetCatalogMethod): string {
+  return method.requiresDevServer ? DEV_SERVER_BADGE : LOCAL_BADGE;
 }
 
-/** One toolset's section of the reference dump. */
-function renderToolsetSection(toolset: AnyToolsetDefinition, ctx: ToolsetCtx): string {
-  const sections = [`${toolset.id} — ${toolset.description}`];
-  for (const [methodKey, method] of Object.entries(toolset.methods)) {
-    const heading = `  ${cliPath(toolset, methodKey)}  ${badge(method)}`;
-    sections.push([heading, '', ...indented(methodBodyLines(method, ctx), 4)].join('\n'));
+function argumentLines(schema: Record<string, unknown> | undefined, flagPrefix: boolean) {
+  if (schema === undefined) {
+    return undefined;
   }
-  return sections.join('\n\n');
-}
-
-/** The focused view of one tool (`storybook tools <toolset> <tool> --help`). */
-export function renderMethodHelp(
-  toolset: AnyToolsetDefinition,
-  methodKey: string,
-  method: AnyToolsetMethod,
-  ctx: ToolsetCtx
-): string {
-  const lines = [
-    `Usage: npx storybook tools ${cliPath(toolset, methodKey)} [--key value ...]`,
-    '',
-    method.requiresDevServer
-      ? 'Execution: requires a running Storybook dev server; start it first.'
-      : 'Execution: local (no running Storybook required).',
-    '',
-    ...methodBodyLines(method, ctx),
-  ];
-  return lines.join('\n');
-}
-
-function badge(method: AnyToolsetMethod): string {
-  return method.requiresDevServer ? DEV_SERVER_BADGE : LOCAL_BADGE;
+  return propertyLines(schema, { flagPrefix });
 }
 
-function methodBodyLines(method: AnyToolsetMethod, ctx: ToolsetCtx): string[] {
-  const lines = [resolveToolsetDescription(method.description, ctx).trim()];
-
-  const inputSchema = toToolsetJsonSchema(method.input);
-  const argumentLines = inputSchema ? propertyLines(inputSchema, { flagPrefix: true }) : undefined;
-  if (argumentLines === undefined) {
+function methodBodyLines(method: ToolsetCatalogMethod): string[] {
+  const lines = [method.description.trim()];
+  const inputLines = argumentLines(method.input, true);
+  if (inputLines === undefined) {
     lines.push('', 'Arguments: (this schema could not be rendered)');
-  } else if (argumentLines.length === 0) {
+  } else if (inputLines.length === 0) {
     lines.push('', 'Arguments: none.');
   } else {
-    lines.push('', 'Arguments:', ...argumentLines);
+    lines.push('', 'Arguments:', ...inputLines);
   }
-
-  if (method.output) {
-    const outputSchema = toToolsetJsonSchema(method.output);
-    const outputLines = outputSchema ? propertyLines(outputSchema, { flagPrefix: false }) : [];
-    if (outputLines.length > 0) {
-      lines.push('', 'Output:', ...outputLines);
-    }
+  const outputLines = argumentLines(method.output, false);
+  if (outputLines && outputLines.length > 0) {
+    lines.push('', 'Output:', ...outputLines);
   }
-
   return lines;
 }
 
@@ -177,45 +84,21 @@ function propertyLines(
   return lines;
 }
 
-function catalogCliPath(method: ToolsetCatalogMethod): string {
-  const { toolsetId, methodName } = parseToolsetMethodId(method.ref);
-  return `${toolsetId} ${toCliMethodName(methodName)}`;
-}
-
-function catalogBadge(method: ToolsetCatalogMethod): string {
-  return method.requiresDevServer ? DEV_SERVER_BADGE : LOCAL_BADGE;
-}
-
-function catalogArgumentLines(schema: Record<string, unknown> | undefined, flagPrefix: boolean) {
-  if (schema === undefined) {
-    return undefined;
-  }
-  return propertyLines(schema, { flagPrefix });
-}
-
-function catalogMethodBodyLines(method: ToolsetCatalogMethod): string[] {
-  const lines = [method.description.trim()];
-  const argumentLines = catalogArgumentLines(method.input, true);
-  if (argumentLines === undefined) {
-    lines.push('', 'Arguments: (this schema could not be rendered)');
-  } else if (argumentLines.length === 0) {
-    lines.push('', 'Arguments: none.');
-  } else {
-    lines.push('', 'Arguments:', ...argumentLines);
-  }
-  const outputLines = catalogArgumentLines(method.output, false);
-  if (outputLines && outputLines.length > 0) {
-    lines.push('', 'Output:', ...outputLines);
+function renderToolsetSection(entry: ToolsetCatalogEntry): string {
+  const sections = [`${entry.id} — ${entry.description}`];
+  for (const method of entry.methods) {
+    const heading = `  ${cliPath(method)}  ${badge(method)}`;
+    sections.push([heading, '', ...indented(methodBodyLines(method), 4)].join('\n'));
   }
-  return lines;
+  return sections.join('\n\n');
 }
 
 export function renderToolsHelpFromCatalog(catalog: ToolsetCatalog): string {
   const commands = catalog.toolsets.flatMap((toolset) =>
     toolset.methods.map((method) => ({
-      path: catalogCliPath(method),
+      path: cliPath(method),
       summary: method.title,
-      badge: catalogBadge(method),
+      badge: badge(method),
     }))
   );
   const column =
@@ -246,7 +129,7 @@ export function renderToolsHelpFromCatalog(catalog: ToolsetCatalog): string {
     'Tool reference — every command in full (`npx storybook tools <toolset> <tool> --help` shows one alone):';
   const sections = [header, notes, referenceIntro];
   for (const toolset of catalog.toolsets) {
-    sections.push(renderCatalogToolsetSection(toolset));
+    sections.push(renderToolsetSection(toolset));
   }
   return sections.join('\n\n');
 }
@@ -255,30 +138,55 @@ export function renderToolsetHelpFromCatalog(entry: ToolsetCatalogEntry): string
   return [
     `Usage: npx storybook tools ${entry.id} <tool> [--key value ...]`,
     '',
-    renderCatalogToolsetSection(entry),
+    renderToolsetSection(entry),
   ].join('\n');
 }
 
 export function renderMethodHelpFromCatalog(
-  entry: ToolsetCatalogEntry,
+  _entry: ToolsetCatalogEntry,
   method: ToolsetCatalogMethod
 ): string {
   return [
-    `Usage: npx storybook tools ${catalogCliPath(method)} [--key value ...]`,
+    `Usage: npx storybook tools ${cliPath(method)} [--key value ...]`,
     '',
     method.requiresDevServer
       ? 'Execution: requires a running Storybook dev server; start it first.'
       : 'Execution: local (no running Storybook required).',
     '',
-    ...catalogMethodBodyLines(method),
+    ...methodBodyLines(method),
   ].join('\n');
 }
 
-function renderCatalogToolsetSection(entry: ToolsetCatalogEntry): string {
-  const sections = [`${entry.id} — ${entry.description}`];
-  for (const method of entry.methods) {
-    const heading = `  ${catalogCliPath(method)}  ${catalogBadge(method)}`;
-    sections.push([heading, '', ...indented(catalogMethodBodyLines(method), 4)].join('\n'));
-  }
-  return sections.join('\n\n');
+/**
+ * The complete agent discovery surface, in commander's conventional shape — Usage, Options, and a
+ * `Commands:` listing with one-line summaries — followed by a full reference for every tool
+ * (description, input schema, declared output schema) so agents learn the surface from this single
+ * invocation instead of paying a project load per lookup. The Options block is the flags' only
+ * documentation, since commander's own help is disabled in favor of this runtime-derived one.
+ */
+export function renderToolsHelp(
+  configDir: string,
+  toolsets: AnyToolsetDefinition[],
+  ctx: ToolsetCtx
+): string {
+  return renderToolsHelpFromCatalog({
+    configDir,
+    toolsets: toolsets.map((toolset) => toCatalogEntry(toolset, ctx)),
+  });
+}
+
+/** The focused view of one toolset (`storybook tools <toolset>`). */
+export function renderToolsetHelp(toolset: AnyToolsetDefinition, ctx: ToolsetCtx): string {
+  return renderToolsetHelpFromCatalog(toCatalogEntry(toolset, ctx));
+}
+
+/** The focused view of one tool (`storybook tools <toolset> <tool> --help`). */
+export function renderMethodHelp(
+  toolset: AnyToolsetDefinition,
+  methodKey: string,
+  method: AnyToolsetMethod,
+  ctx: ToolsetCtx
+): string {
+  const entry = toCatalogEntry({ ...toolset, methods: { [methodKey]: method } }, ctx);
+  return renderMethodHelpFromCatalog(entry, entry.methods[0] as ToolsetCatalogMethod);
 }