incur 0.4.8 → 0.4.9

package/src/Mcp.ts

@@ -1,8 +1,9 @@
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server'
 import type { Readable, Writable } from 'node:stream'
 import { z } from 'zod'
 
 import * as Command from './internal/command.js'
+import { formatCtaBlock, type FormattedCtaBlock } from './internal/cta.js'
+import * as Json from './internal/json.js'
 import type { Handler as MiddlewareHandler } from './middleware.js'
 import * as Schema from './Schema.js'
 
@@ -13,7 +14,14 @@ export async function serve(
   commands: Map<string, any>,
   options: serve.Options = {},
 ): Promise<void> {
-  const server = new McpServer({ name, version })
+  // Lazy: only runs when actually serving MCP, so plain command runs don't pay for the SDK import.
+  const { fromJsonSchema, McpServer, StdioServerTransport } =
+    await import('@modelcontextprotocol/server')
+
+  const server = new McpServer(
+    { name, version },
+    options.instructions ? { instructions: options.instructions } : undefined,
+  )
 
   for (const tool of collectTools(commands, [])) {
     const mergedShape: Record<string, any> = {
@@ -27,7 +35,9 @@ export async function serve(
       {
         ...(tool.description ? { description: tool.description } : undefined),
         ...(hasInput ? { inputSchema: z.object(mergedShape) } : undefined),
-        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : undefined),
+        ...(tool.outputSchema ? { outputSchema: fromJsonSchema(tool.outputSchema) } : undefined),
+        ...(tool.annotations ? { annotations: tool.annotations } : undefined),
+        ...(tool.instructions ? { _meta: { instructions: tool.instructions } } : undefined),
       } as never,
       async (...callArgs: any[]) => {
         // registerTool passes (args, extra) when inputSchema is set, (extra) when not
@@ -67,6 +77,8 @@ export declare namespace serve {
     vars?: z.ZodObject<any> | undefined
     /** CLI version string. */
     version?: string | undefined
+    /** Instructions describing how to use the server and its features. */
+    instructions?: string | undefined
   }
 }
 
@@ -88,6 +100,7 @@ export async function callTool(
 ): Promise<{
   content: { type: 'text'; text: string }[]
   structuredContent?: Record<string, unknown>
+  _meta?: { cta: FormattedCtaBlock } | undefined
   isError?: boolean
 }> {
   const allMiddleware = [
@@ -122,7 +135,7 @@ export async function callTool(
         if (progressToken !== undefined && options.sendNotification)
           await options.sendNotification({
             method: 'notifications/progress' as const,
-            params: { progressToken, progress: ++i, message: JSON.stringify(chunk) },
+            params: { progressToken, progress: ++i, message: Json.stringify(chunk) },
           })
       }
     } catch (err) {
@@ -131,21 +144,31 @@ export async function callTool(
         isError: true,
       }
     }
-    return { content: [{ type: 'text', text: JSON.stringify(chunks) }] }
+    return { content: [{ type: 'text', text: Json.stringify(chunks) }] }
   }
 
   if (!result.ok)
     return {
-      content: [{ type: 'text', text: result.error.message ?? 'Command failed' }],
+      content: [
+        {
+          type: 'text',
+          text: result.error.fieldErrors
+            ? JSON.stringify(result.error)
+            : (result.error.message ?? 'Command failed'),
+        },
+      ],
       isError: true,
     }
 
   const data = result.data ?? null
+  const jsonData = Json.normalize(data)
+  const cta = formatCtaBlock(options.name ?? tool.name, result.cta as Command.CtaBlock | undefined)
   return {
-    content: [{ type: 'text', text: JSON.stringify(data) }],
+    content: [{ type: 'text', text: Json.stringify(jsonData) }],
     ...(data !== null && tool.outputSchema
-      ? { structuredContent: data as Record<string, unknown> }
+      ? { structuredContent: jsonData as Record<string, unknown> }
       : undefined),
+    ...(cta ? { _meta: { cta } } : undefined),
   }
 }
 
@@ -161,10 +184,26 @@ export type ToolEntry = {
   description?: string | undefined
   inputSchema: { type: 'object'; properties: Record<string, unknown>; required?: string[] }
   outputSchema?: Record<string, unknown> | undefined
+  annotations?: ToolAnnotations | undefined
+  instructions?: string | undefined
   command: any
   middlewares?: MiddlewareHandler[] | undefined
 }
 
+/** MCP tool annotations that describe tool behavior to clients. */
+export type ToolAnnotations = {
+  /** A human-readable title for the tool. */
+  title?: string | undefined
+  /** If true, the tool does not modify its environment. Default: false. */
+  readOnlyHint?: boolean | undefined
+  /** If true, the tool may perform destructive updates to its environment. Meaningful only when readOnlyHint is false. Default: true. */
+  destructiveHint?: boolean | undefined
+  /** If true, calling the tool repeatedly with the same arguments has no additional effect. Meaningful only when readOnlyHint is false. Default: false. */
+  idempotentHint?: boolean | undefined
+  /** If true, the tool may interact with an open world of external entities. Default: true. */
+  openWorldHint?: boolean | undefined
+}
+
 /** @internal Recursively collects leaf commands as tool entries. */
 export function collectTools(
   commands: Map<string, any>,
@@ -189,6 +228,8 @@ export function collectTools(
         ...(entry.output
           ? { outputSchema: Schema.toJsonSchema(entry.output) as Record<string, unknown> }
           : undefined),
+        ...(entry.mcp?.annotations ? { annotations: entry.mcp.annotations } : undefined),
+        ...(entry.mcp?.instructions ? { instructions: entry.mcp.instructions } : undefined),
         command: entry,
         ...(parentMiddlewares.length > 0 ? { middlewares: parentMiddlewares } : undefined),
       })

package/src/Parser.test.ts

@@ -376,3 +376,176 @@ describe('parse', () => {
     expect(result.options).toEqual({ min: 1, max: 3 })
   })
 })
+
+describe('parseGlobals', () => {
+  test('extracts known globals and returns rest', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(['--rpc-url', 'http://example.com', 'deploy'], schema)
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('unknown flags pass through to rest', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(
+      ['--rpc-url', 'http://example.com', '--unknown', 'val', 'deploy'],
+      schema,
+    )
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['--unknown', 'val', 'deploy'])
+  })
+
+  test('handles --flag=value syntax', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(['--rpc-url=http://example.com', 'deploy'], schema)
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('handles short aliases', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(
+      ['-r', 'http://example.com', 'deploy'],
+      schema,
+      { rpcUrl: 'r' },
+    )
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('handles boolean globals', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['--verbose', 'deploy'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('validates against schema', () => {
+    const schema = z.object({ count: z.number() })
+    expect(() => Parser.parseGlobals(['--count', 'not-a-number'], schema)).toThrow()
+  })
+
+  test('coerces string to number', () => {
+    const schema = z.object({ limit: z.number() })
+    const result = Parser.parseGlobals(['--limit', '42', 'deploy'], schema)
+    expect(result.parsed).toEqual({ limit: 42 })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('positionals pass through to rest', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['deploy', 'contract', '--verbose'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['deploy', 'contract'])
+  })
+
+  test('-- separator: everything after -- passes through to rest including the --', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(
+      ['--verbose', '--', '--unknown', 'positional', '--also-unknown'],
+      schema,
+    )
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['--', '--unknown', 'positional', '--also-unknown'])
+  })
+
+  test('stacked short aliases: -rv where both are known boolean globals', () => {
+    const schema = z.object({
+      recursive: z.boolean().default(false),
+      verbose: z.boolean().default(false),
+    })
+    const result = Parser.parseGlobals(['-rv', 'deploy'], schema, {
+      recursive: 'r',
+      verbose: 'v',
+    })
+    expect(result.parsed).toEqual({ recursive: true, verbose: true })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('count options: --verbose --verbose accumulates', () => {
+    const schema = z.object({ verbose: z.number().default(0).meta({ count: true }) })
+    const result = Parser.parseGlobals(['--verbose', '--verbose', 'deploy'], schema)
+    expect(result.parsed).toEqual({ verbose: 2 })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('array options: --tag foo --tag bar collects into array', () => {
+    const schema = z.object({ tag: z.array(z.string()).default([]) })
+    const result = Parser.parseGlobals(['--tag', 'foo', '--tag', 'bar', 'deploy'], schema)
+    expect(result.parsed).toEqual({ tag: ['foo', 'bar'] })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('unknown --no-* flags pass through to rest', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['--no-color', '--verbose'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['--no-color'])
+  })
+
+  test('unknown --flag=value passes through as single token', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['--output=json', '--verbose'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['--output=json'])
+  })
+
+  test('missing value for known flag throws ParseError', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    expect(() => Parser.parseGlobals(['--rpc-url'], schema)).toThrow(
+      expect.objectContaining({ name: 'Incur.ParseError' }),
+    )
+  })
+
+  test('stacked short: count in non-last position', () => {
+    const schema = z.object({
+      verbose: z.number().default(0).meta({ count: true }),
+      recursive: z.boolean().default(false),
+    })
+    const result = Parser.parseGlobals(['-vr'], schema, { verbose: 'v', recursive: 'r' })
+    expect(result.parsed).toEqual({ verbose: 1, recursive: true })
+  })
+
+  test('stacked short: non-boolean in non-last position throws', () => {
+    const schema = z.object({
+      output: z.string(),
+      verbose: z.boolean().default(false),
+    })
+    expect(() => Parser.parseGlobals(['-ov', 'file'], schema, { output: 'o', verbose: 'v' })).toThrow(
+      /must be last/,
+    )
+  })
+
+  test('short flag value-taking as last in stacked alias', () => {
+    const schema = z.object({
+      verbose: z.boolean().default(false),
+      output: z.string(),
+    })
+    const result = Parser.parseGlobals(['-vo', 'file', 'deploy'], schema, {
+      verbose: 'v',
+      output: 'o',
+    })
+    expect(result.parsed).toEqual({ verbose: true, output: 'file' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('short flag missing value throws ParseError', () => {
+    const schema = z.object({ output: z.string() })
+    expect(() => Parser.parseGlobals(['-o'], schema, { output: 'o' })).toThrow(
+      expect.objectContaining({ name: 'Incur.ParseError' }),
+    )
+  })
+
+  test('known --no- negation for boolean global', () => {
+    const schema = z.object({ verbose: z.boolean().default(true) })
+    const result = Parser.parseGlobals(['--no-verbose', 'deploy'], schema)
+    expect(result.parsed).toEqual({ verbose: false })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('known --flag=value with setOption', () => {
+    const schema = z.object({ tag: z.array(z.string()).default([]) })
+    const result = Parser.parseGlobals(['--tag=foo', '--tag=bar'], schema)
+    expect(result.parsed).toEqual({ tag: ['foo', 'bar'] })
+  })
+})

package/src/Parser.ts

@@ -257,7 +257,7 @@ function setOption(
 }
 
 /** Wraps zod schema.parse(), converting ZodError to ValidationError. */
-function zodParse(schema: z.ZodObject<any>, data: Record<string, unknown>) {
+export function zodParse(schema: z.ZodObject<any>, data: Record<string, unknown>) {
   try {
     return schema.parse(data)
   } catch (err: any) {
@@ -330,6 +330,137 @@ function coerce(value: unknown, name: string, schema: z.ZodObject<any>): unknown
   return value
 }
 
+/** Parses known global options from argv, passing unknown flags and positionals through to `rest`. */
+export function parseGlobals<const globals extends z.ZodObject<any>>(
+  argv: string[],
+  schema: globals,
+  alias?: Record<string, string>,
+  options: parseGlobals.Options = {},
+): { parsed: z.output<globals>; rest: string[] } {
+  const optionNames = createOptionNames(schema, alias)
+
+  const rest: string[] = []
+  const rawOptions: Record<string, unknown> = {}
+
+  let i = 0
+  while (i < argv.length) {
+    const token = argv[i]!
+
+    if (token === '--') {
+      for (let j = i; j < argv.length; j++) rest.push(argv[j]!)
+      break
+    }
+
+    if (token.startsWith('--no-') && token.length > 5) {
+      const name = normalizeOptionName(token.slice(5), optionNames)
+      if (!name) {
+        rest.push(token)
+      } else {
+        rawOptions[name] = false
+      }
+      i++
+    } else if (token.startsWith('--')) {
+      const eqIdx = token.indexOf('=')
+      if (eqIdx !== -1) {
+        // --flag=value
+        const raw = token.slice(2, eqIdx)
+        const name = normalizeOptionName(raw, optionNames)
+        if (!name) {
+          rest.push(token)
+        } else {
+          setOption(rawOptions, name, token.slice(eqIdx + 1), schema)
+        }
+        i++
+      } else {
+        // --flag [value]
+        const name = normalizeOptionName(token.slice(2), optionNames)
+        if (!name) {
+          // Unknown flag — pass through as-is
+          rest.push(token)
+          i++
+        } else if (isCountOption(name, schema)) {
+          rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+          i++
+        } else if (isBooleanOption(name, schema)) {
+          rawOptions[name] = true
+          i++
+        } else {
+          const value = argv[i + 1]
+          if (value === undefined)
+            throw new ParseError({ message: `Missing value for flag: ${token}` })
+          setOption(rawOptions, name, value, schema)
+          i += 2
+        }
+      }
+    } else if (token.startsWith('-') && !token.startsWith('--') && token.length >= 2) {
+      // Short flag(s)
+      const chars = token.slice(1)
+      let allKnown = true
+      for (let j = 0; j < chars.length; j++) {
+        if (!optionNames.aliasToName.has(chars[j]!)) {
+          allKnown = false
+          break
+        }
+      }
+
+      if (!allKnown) {
+        // Unknown short flag — pass through as-is
+        rest.push(token)
+        i++
+      } else {
+        for (let j = 0; j < chars.length; j++) {
+          const short = chars[j]!
+          const name = optionNames.aliasToName.get(short)!
+          const isLast = j === chars.length - 1
+          if (!isLast) {
+            if (isCountOption(name, schema)) {
+              rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+            } else if (isBooleanOption(name, schema)) {
+              rawOptions[name] = true
+            } else {
+              throw new ParseError({
+                message: `Non-boolean flag -${short} must be last in a stacked alias`,
+              })
+            }
+          } else if (isCountOption(name, schema)) {
+            rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+          } else if (isBooleanOption(name, schema)) {
+            rawOptions[name] = true
+          } else {
+            const value = argv[i + 1]
+            if (value === undefined)
+              throw new ParseError({ message: `Missing value for flag: -${short}` })
+            setOption(rawOptions, name, value, schema)
+            i++
+          }
+        }
+        i++
+      }
+    } else {
+      // Positional — pass through
+      rest.push(token)
+      i++
+    }
+  }
+
+  if (options.validate === false) return { parsed: rawOptions as z.output<globals>, rest }
+
+  // Coerce raw option values before zod validation
+  for (const [name, value] of Object.entries(rawOptions))
+    rawOptions[name] = coerce(value, name, schema)
+
+  const parsed = zodParse(schema, rawOptions) as z.output<globals>
+  return { parsed, rest }
+}
+
+export declare namespace parseGlobals {
+  /** Options for parsing global flags. */
+  type Options = {
+    /** Whether to validate parsed globals against the schema. */
+    validate?: boolean | undefined
+  }
+}
+
 /** Returns the best available env source for the current runtime. */
 export function defaultEnvSource(): Record<string, string | undefined> {
   if (typeof globalThis !== 'undefined') {

package/src/Skill.test.ts

@@ -204,6 +204,12 @@ describe('hash', () => {
     expect(a).not.toBe(b)
   })
 
+  test('changes when hint changes', () => {
+    const a = Skill.hash([{ name: 'ping', hint: 'Read status.' }])
+    const b = Skill.hash([{ name: 'ping', hint: 'Delete status.' }])
+    expect(a).not.toBe(b)
+  })
+
   test('changes when schema changes', () => {
     const a = Skill.hash([{ name: 'greet', args: z.object({ name: z.string() }) }])
     const b = Skill.hash([{ name: 'greet', args: z.object({ name: z.string(), age: z.number() }) }])

package/src/Skill.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
-import { stringify as yamlStringify } from 'yaml'
 import type { z } from 'zod'
 
+import * as Yaml from './internal/yaml.js'
 import * as Schema from './Schema.js'
 
 /** Information about a single command, passed to `generate()`. */
@@ -137,10 +137,12 @@ function renderGroup(
     ? `${desc.replace(/\.$/, '')}. Run \`${title} --help\` for usage details.`
     : `Run \`${title} --help\` for usage details.`
 
-  const fm = yamlStringify(
-    { name: slugify(title), description, requires_bin: cli, command: title },
-    { lineWidth: 0 },
-  ).trimEnd()
+  const fm = Yaml.loadSync()
+    .stringify(
+      { name: slugify(title), description, requires_bin: cli, command: title },
+      { lineWidth: 0 },
+    )
+    .trimEnd()
   const fmBlock = `---\n${fm}\n---`
 
   const body = cmds.map((cmd) => renderCommandBody(cli, cmd)).join('\n\n---\n\n')
@@ -245,6 +247,7 @@ export function hash(commands: CommandInfo[]): string {
   const data = commands.map((cmd) => ({
     name: cmd.name,
     description: cmd.description,
+    hint: cmd.hint,
     args: cmd.args ? Schema.toJsonSchema(cmd.args) : undefined,
     env: cmd.env ? Schema.toJsonSchema(cmd.env) : undefined,
     options: cmd.options ? Schema.toJsonSchema(cmd.options) : undefined,

package/src/Skillgen.test.ts

@@ -60,13 +60,20 @@ test('collects group descriptions', async () => {
 test('includes args, options, and examples in output', async () => {
   const cli = Cli.create('tool', {
     description: 'A tool',
-  }).command('greet', {
-    description: 'Greet someone',
-    args: z.object({ name: z.string().describe('Name to greet') }),
-    options: z.object({ loud: z.boolean().default(false).describe('Shout') }),
-    examples: [{ args: { name: 'world' }, description: 'Greet the world' }],
-    run: () => ({}),
   })
+    .command('greet', {
+      description: 'Greet someone',
+      aliases: ['hi'],
+      args: z.object({ name: z.string().describe('Name to greet') }),
+      options: z.object({ loud: z.boolean().default(false).describe('Shout') }),
+      output: z.object({ message: z.string() }),
+      examples: [{ args: { name: 'world' }, description: 'Greet the world' }],
+      run: () => ({ message: 'hi' }),
+    })
+    .command('api', {
+      description: 'Proxy API',
+      fetch: () => new Response('{}'),
+    })
   vi.mocked(importCli).mockResolvedValue(cli)
 
   const files = await generate('fake-input', tmp, 0)
@@ -74,4 +81,46 @@ test('includes args, options, and examples in output', async () => {
   expect(content).toContain('Name to greet')
   expect(content).toContain('Shout')
   expect(content).toContain('Greet the world')
+  expect(content).toContain('## Output')
+  expect(content).toContain('Fetch gateway. Pass path segments')
+  expect(content).not.toContain('# tool hi')
+})
+
+test('appends confirmation hint for destructive commands', async () => {
+  const cli = Cli.create('tool')
+    .command('destroy', {
+      description: 'Destroy data',
+      destructive: true,
+      hint: 'Deletes all data.',
+      run: () => ({}),
+    })
+    .command('status', {
+      description: 'Check status',
+      hint: 'Shows current status.',
+      run: () => ({}),
+    })
+  vi.mocked(importCli).mockResolvedValue(cli)
+
+  const files = await generate('fake-input', tmp, 0)
+  const content = readFileSync(files[0]!, 'utf-8')
+  expect(content).toContain(
+    'Deletes all data. Confirm with the user before executing this destructive command.',
+  )
+  expect(content).toContain('Shows current status.')
+  expect(content).not.toContain(
+    'Shows current status. Confirm with the user before executing this destructive command.',
+  )
+})
+
+test('uses MCP destructiveHint when generating skill files', async () => {
+  const cli = Cli.create('tool').command('deploy', {
+    description: 'Deploy',
+    mcp: { annotations: { destructiveHint: true } },
+    run: () => ({}),
+  })
+  vi.mocked(importCli).mockResolvedValue(cli)
+
+  const files = await generate('fake-input', tmp, 0)
+  const content = readFileSync(files[0]!, 'utf-8')
+  expect(content).toContain('Confirm with the user before executing this destructive command.')
 })

package/src/Skillgen.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 
 import * as Cli from './Cli.js'
 import { importCli } from './internal/utils.js'
+import * as Yaml from './internal/yaml.js'
 import * as Skill from './Skill.js'
 
 /** Imports a CLI from `input`, generates Markdown skill files, and writes them to `output`. */
@@ -13,7 +14,14 @@ export async function generate(input: string, output: string, depth = 1): Promis
 
   const groups = new Map<string, string>()
   if (cli.description) groups.set(cli.name, cli.description)
-  const entries = collectEntries(commands, [], groups)
+  const entries = Cli.collectSkillCommands(
+    commands,
+    [],
+    groups,
+    Cli.toRootDefinition.get(cli as unknown as Cli.Root),
+  )
+  // Pre-load yaml for `Skill.split`'s sync call path.
+  await Yaml.load()
   const files = Skill.split(cli.name, entries, depth, groups)
 
   if (depth > 0) await fs.rm(output, { recursive: true, force: true })
@@ -30,37 +38,3 @@ export async function generate(input: string, output: string, depth = 1): Promis
 
   return written
 }
-
-/** Recursively collects leaf commands as `Skill.CommandInfo` and group descriptions. */
-function collectEntries(
-  commands: Map<string, any>,
-  prefix: string[],
-  groups: Map<string, string> = new Map(),
-): Skill.CommandInfo[] {
-  const result: Skill.CommandInfo[] = []
-  for (const [name, entry] of commands) {
-    const path = [...prefix, name]
-    if ('_group' in entry && entry._group) {
-      if (entry.description) groups.set(path.join(' '), entry.description)
-      result.push(...collectEntries(entry.commands, path, groups))
-    } else {
-      const cmd: Skill.CommandInfo = { name: path.join(' ') }
-      if (entry.description) cmd.description = entry.description
-      if (entry.args) cmd.args = entry.args
-      if (entry.env) cmd.env = entry.env
-      if (entry.hint) cmd.hint = entry.hint
-      if (entry.options) cmd.options = entry.options
-      if (entry.output) cmd.output = entry.output
-      const examples = Cli.formatExamples(entry.examples)
-      if (examples) {
-        const cmdName = path.join(' ')
-        cmd.examples = examples.map((e) => ({
-          ...e,
-          command: e.command ? `${cmdName} ${e.command}` : cmdName,
-        }))
-      }
-      result.push(cmd)
-    }
-  }
-  return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''))
-}