incur 0.3.13 → 0.3.15

package/src/Openapi.test.ts

@@ -47,6 +47,13 @@ describe('generateCommands', () => {
     const cmd = commands.get('listUsers')!
     expect(cmd.description).toBe('List users')
   })
+
+  test('coerced number params preserve description', async () => {
+    const commands = await Openapi.generateCommands(spec, app.fetch)
+    const cmd = commands.get('listUsers')!
+    const limitSchema = cmd.options!.shape.limit
+    expect(limitSchema.description).toBe('Max results')
+  })
 })
 
 describe('cli integration', () => {

package/src/Openapi.ts

@@ -186,20 +186,26 @@ function coerceIfNeeded(schema: z.ZodType): z.ZodType {
   const isOptional = schema instanceof z.ZodOptional
   const inner = isOptional ? schema.unwrap() : schema
 
-  // Direct number/boolean
-  if (inner instanceof z.ZodNumber)
-    return isOptional ? z.coerce.number().optional() : z.coerce.number()
-  if (inner instanceof z.ZodBoolean)
-    return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
-
-  // Union containing number (e.g. type: ["number", "null"] from OpenAPI 3.1)
-  if (inner instanceof z.ZodUnion) {
-    const options = (inner as any)._zod?.def?.options as z.ZodType[] | undefined
-    if (options?.some((o: z.ZodType) => o instanceof z.ZodNumber))
+  const coerced = (() => {
+    // Direct number
+    if (inner instanceof z.ZodNumber)
       return isOptional ? z.coerce.number().optional() : z.coerce.number()
-    if (options?.some((o: z.ZodType) => o instanceof z.ZodBoolean))
+    // Direct boolean
+    if (inner instanceof z.ZodBoolean)
       return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
-  }
+    // Union containing number or boolean (e.g. type: ["number", "null"] from OpenAPI 3.1)
+    if (inner instanceof z.ZodUnion) {
+      const options = (inner as any)._zod?.def?.options as z.ZodType[] | undefined
+      if (options?.some((o: z.ZodType) => o instanceof z.ZodNumber))
+        return isOptional ? z.coerce.number().optional() : z.coerce.number()
+      if (options?.some((o: z.ZodType) => o instanceof z.ZodBoolean))
+        return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
+    }
+    // No coercion needed
+    return undefined
+  })()
 
-  return schema
+  if (!coerced) return schema
+  const desc = (schema as any).description ?? (inner as any).description
+  return desc ? coerced.describe(desc) : coerced
 }

package/src/Parser.ts

@@ -315,7 +315,7 @@ function coerce(value: unknown, name: string, schema: z.ZodObject<any>): unknown
 }
 
 /** Returns the best available env source for the current runtime. */
-function defaultEnvSource(): Record<string, string | undefined> {
+export function defaultEnvSource(): Record<string, string | undefined> {
   if (typeof globalThis !== 'undefined') {
     const g = globalThis as any
     if (g.process?.env) return g.process.env

package/src/Skill.test.ts

@@ -216,6 +216,40 @@ describe('hash', () => {
   })
 })
 
+describe('root command (no name)', () => {
+  test('generate renders root command without trailing space', () => {
+    const result = Skill.generate('my-cli', [
+      {
+        description: 'Fetch a URL',
+        args: z.object({ url: z.string().describe('URL to fetch') }),
+      },
+      { name: 'auth', description: 'Auth commands' },
+    ])
+    expect(result).toContain('# my-cli\n\nFetch a URL')
+    expect(result).not.toContain('# my-cli \n')
+    expect(result).toContain('| `url` | `string` | yes | URL to fetch |')
+    expect(result).toContain('# my-cli auth')
+  })
+
+  test('index renders root command signature without trailing space', () => {
+    const result = Skill.index('my-cli', [
+      { description: 'Fetch a URL', args: z.object({ url: z.string() }) },
+      { name: 'auth', description: 'Auth commands' },
+    ])
+    expect(result).toContain('| `my-cli <url>` | Fetch a URL |')
+    expect(result).toContain('| `my-cli auth` | Auth commands |')
+  })
+
+  test('hash changes when root command is added', () => {
+    const a = Skill.hash([{ name: 'ping', description: 'Health check' }])
+    const b = Skill.hash([
+      { description: 'Root command' },
+      { name: 'ping', description: 'Health check' },
+    ])
+    expect(a).not.toBe(b)
+  })
+})
+
 describe('split', () => {
   const commands: Skill.CommandInfo[] = [
     { name: 'auth login', description: 'Log in' },
@@ -349,4 +383,34 @@ describe('split', () => {
     expect(afterFrontmatter).not.toMatch(/^title:/m)
     expect(afterFrontmatter).not.toMatch(/^command:/m)
   })
+
+  test('depth 1 creates separate file for root command', () => {
+    const cmds: Skill.CommandInfo[] = [
+      {
+        description: 'Fetch a URL',
+        args: z.object({ url: z.string().describe('URL to fetch') }),
+      },
+      { name: 'auth login', description: 'Log in' },
+      { name: 'auth status', description: 'Check status' },
+    ]
+    const files = Skill.split('my-cli', cmds, 1)
+    expect(files.map((f) => f.dir)).toEqual(['auth', 'my-cli'])
+    const rootFile = files.find((f) => f.dir === 'my-cli')!
+    expect(rootFile.content).toContain('name: my-cli')
+    expect(rootFile.content).toContain('command: my-cli')
+    expect(rootFile.content).toContain('# my-cli')
+    expect(rootFile.content).toContain('| `url` | `string` | yes | URL to fetch |')
+    expect(rootFile.content).not.toContain('# my-cli ')
+  })
+
+  test('depth 0 includes root command in single file', () => {
+    const cmds: Skill.CommandInfo[] = [
+      { description: 'Fetch a URL' },
+      { name: 'ping', description: 'Health check' },
+    ]
+    const files = Skill.split('test', cmds, 0)
+    expect(files).toHaveLength(1)
+    expect(files[0]!.content).toContain('# test\n\nFetch a URL')
+    expect(files[0]!.content).toContain('# test ping')
+  })
 })

package/src/Skill.ts

@@ -5,7 +5,8 @@ import * as Schema from './Schema.js'
 
 /** Information about a single command, passed to `generate()`. */
 export type CommandInfo = {
-  name: string
+  /** Command name (subcommand path). Omit for root commands. */
+  name?: string | undefined
   description?: string | undefined
   args?: z.ZodObject<any> | undefined
   env?: z.ZodObject<any> | undefined
@@ -48,7 +49,7 @@ export function index(
 
 /** @internal Builds a command signature with arg placeholders. */
 function buildSignature(cli: string, cmd: CommandInfo): string {
-  const base = `${cli} ${cmd.name}`
+  const base = !cmd.name ? cli : `${cli} ${cmd.name}`
   if (!cmd.args) return base
   const shape = cmd.args.shape as Record<string, z.ZodType>
   const json = Schema.toJsonSchema(cmd.args)
@@ -70,14 +71,16 @@ export function generate(
   let lastGroup: string | undefined
 
   for (const cmd of commands) {
-    const segment = cmd.name.split(' ')[0]!
+    const segment = !cmd.name ? '' : cmd.name.split(' ')[0]!
     if (segment !== lastGroup) {
       lastGroup = segment
-      const desc = groups.get(segment)
-      const heading = desc ? `## ${name} ${segment}\n\n${desc}` : `## ${name} ${segment}`
-      sections.push(heading)
+      if (segment) {
+        const desc = groups.get(segment)
+        const heading = desc ? `## ${name} ${segment}\n\n${desc}` : `## ${name} ${segment}`
+        sections.push(heading)
+      }
     }
-    sections.push(renderCommandBody(name, cmd, 3))
+    sections.push(renderCommandBody(name, cmd, segment ? 3 : 2))
   }
 
   return sections.join('\n\n')
@@ -94,6 +97,13 @@ export function split(
 
   const buckets = new Map<string, CommandInfo[]>()
   for (const cmd of commands) {
+    if (!cmd.name) {
+      const key = slugify(name)
+      const bucket = buckets.get(key) ?? []
+      bucket.push(cmd)
+      buckets.set(key, bucket)
+      continue
+    }
     const segments = cmd.name.split(' ')
     const key = segments.slice(0, depth).join('-')
     const bucket = buckets.get(key) ?? []
@@ -104,8 +114,10 @@ export function split(
   return [...buckets.entries()]
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([dir, cmds]) => {
-      const prefix = cmds[0]!.name.split(' ').slice(0, depth).join(' ')
-      return { dir, content: renderGroup(name, `${name} ${prefix}`, cmds, groups, prefix) }
+      const first = cmds[0]!
+      const prefix = !first.name ? '' : first.name.split(' ').slice(0, depth).join(' ')
+      const title = prefix ? `${name} ${prefix}` : name
+      return { dir, content: renderGroup(name, title, cmds, groups, prefix || undefined) }
     })
 }
 
@@ -121,18 +133,14 @@ function renderGroup(
   const childDescs = cmds.map((c) => c.description).filter(Boolean) as string[]
   const descParts: string[] = []
   if (groupDesc) descParts.push(groupDesc.replace(/\.$/, ''))
-  if (childDescs.length > 0) descParts.push(childDescs.join(', '))
+  if (childDescs.length > 0)
+    descParts.push(childDescs.map((d) => d.replace(/\.$/, '')).join(', '))
   const description =
     descParts.length > 0
       ? `${descParts.join('. ')}. Run \`${title} --help\` for usage details.`
       : `Run \`${title} --help\` for usage details.`
 
-  const slug = title
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-{2,}/g, '-')
-    .replace(/^-|-$/g, '')
-  const fm = ['---', `name: ${slug}`]
+  const fm = ['---', `name: ${slugify(title)}`]
   fm.push(`description: ${description}`)
   fm.push(`requires_bin: ${cli}`)
   fm.push(`command: ${title}`, '---')
@@ -143,7 +151,7 @@ function renderGroup(
 
 /** @internal Renders a command's heading and sections without frontmatter. */
 function renderCommandBody(cli: string, cmd: CommandInfo, level = 1): string {
-  const fullName = `${cli} ${cmd.name}`
+  const fullName = !cmd.name ? cli : `${cli} ${cmd.name}`
   const sections: string[] = []
   const h = (n: number) => '#'.repeat(n)
 
@@ -287,6 +295,15 @@ function schemaToTable(schema: Record<string, unknown>, prefix = ''): string | u
   return `| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n${rows.join('\n')}`
 }
 
+/** @internal Converts a string to a lowercase slug (e.g. `"my-cli"` → `"my-cli"`, `"My Tool"` → `"my-tool"`). */
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
 /** @internal Resolves a simple type name from a JSON Schema property. */
 function resolveTypeName(prop: Record<string, unknown> | undefined): string {
   if (!prop) return 'unknown'

package/src/Skillgen.ts

@@ -62,5 +62,5 @@ function collectEntries(
       result.push(cmd)
     }
   }
-  return result.sort((a, b) => a.name.localeCompare(b.name))
+  return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''))
 }

package/src/SyncSkills.test.ts

@@ -125,3 +125,66 @@ test('installed SKILL.md contains frontmatter', async () => {
 
   rmSync(tmp, { recursive: true, force: true })
 })
+
+test('list returns skills from command map', async () => {
+  const cli = Cli.create('test', { description: 'A test CLI' })
+  cli.command('ping', { description: 'Health check', run: () => ({}) })
+  cli.command('greet', { description: 'Say hello', run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  const result = await SyncSkills.list('test', commands)
+
+  expect(result.length).toBeGreaterThan(0)
+  const names = result.map((s) => s.name)
+  expect(names).toContain('test-ping')
+  expect(names).toContain('test-greet')
+  for (const s of result) {
+    expect(s.installed).toBe(false)
+    expect(s.description).toBeDefined()
+  }
+})
+
+test('list shows installed status after sync', async () => {
+  const tmp = join(tmpdir(), `clac-list-test-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+  process.env.XDG_DATA_HOME = tmp
+
+  const cli = Cli.create('test')
+  cli.command('ping', { description: 'Ping', run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  const installDir = join(tmp, 'install')
+  mkdirSync(join(installDir, '.agents', 'skills'), { recursive: true })
+
+  // Sync first to install
+  await SyncSkills.sync('test', commands, {
+    global: false,
+    cwd: installDir,
+  })
+
+  // Now list should show installed
+  const result = await SyncSkills.list('test', commands)
+  expect(result.length).toBeGreaterThan(0)
+  for (const s of result) expect(s.installed).toBe(true)
+
+  rmSync(tmp, { recursive: true, force: true })
+})
+
+test('list returns empty for CLI with no commands', async () => {
+  const cli = Cli.create('empty')
+  const commands = Cli.toCommands.get(cli)!
+  const result = await SyncSkills.list('empty', commands)
+  expect(result).toHaveLength(0)
+})
+
+test('list results are sorted alphabetically', async () => {
+  const cli = Cli.create('test')
+  cli.command('zebra', { description: 'Z command', run: () => ({}) })
+  cli.command('alpha', { description: 'A command', run: () => ({}) })
+  cli.command('middle', { description: 'M command', run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  const result = await SyncSkills.list('test', commands)
+  const names = result.map((s) => s.name)
+  expect(names).toEqual([...names].sort())
+})

package/src/SyncSkills.ts

@@ -18,7 +18,7 @@ export async function sync(
 
   const groups = new Map<string, string>()
   if (description) groups.set(name, description)
-  const entries = collectEntries(commands, [], groups)
+  const entries = collectEntries(commands, [], groups, options.rootCommand)
   const files = Skill.split(name, entries, depth, groups)
 
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), `incur-skills-${name}-`))
@@ -70,7 +70,7 @@ export async function sync(
     }
 
     // Write skills hash + names for staleness detection
-    const hashEntries = collectEntries(commands, [])
+    const hashEntries = collectEntries(commands, [], undefined, options.rootCommand)
     writeMeta(name, Skill.hash(hashEntries), [...currentNames])
 
     return { skills, paths, agents }
@@ -92,6 +92,18 @@ export declare namespace sync {
     global?: boolean | undefined
     /** Glob patterns for directories containing SKILL.md files to include (e.g. `"skills/*"`, `"my-skill"`). Skill name is the parent directory name. */
     include?: string[] | undefined
+    /** Root command definition (when the CLI itself has a `run` handler). */
+    rootCommand?:
+      | {
+          description?: string | undefined
+          args?: any
+          env?: any
+          hint?: string | undefined
+          options?: any
+          output?: any
+          examples?: any[] | undefined
+        }
+      | undefined
   }
   /** Result of a sync operation. */
   type Result = {
@@ -113,13 +125,114 @@ export declare namespace sync {
   }
 }
 
+/** Lists skills derived from a CLI's command map with install status. */
+export async function list(
+  name: string,
+  commands: Map<string, any>,
+  options: list.Options = {},
+): Promise<list.Skill[]> {
+  const { depth = 1, description } = options
+  const cwd = options.cwd ?? process.cwd()
+
+  const groups = new Map<string, string>()
+  if (description) groups.set(name, description)
+  const entries = collectEntries(commands, [], groups)
+  const files = Skill.split(name, entries, depth, groups)
+
+  const skills: list.Skill[] = []
+  const meta = readMeta(name)
+  const installed = new Set(meta?.skills)
+
+  for (const file of files) {
+    const nameMatch = file.content.match(/^name:\s*(.+)$/m)
+    const descMatch = file.content.match(/^description:\s*(.+)$/m)
+    const skillName = nameMatch?.[1] ?? (file.dir || name)
+    skills.push({
+      name: skillName,
+      description: descMatch?.[1],
+      installed: installed.has(skillName),
+    })
+  }
+
+  // Include additional SKILL.md files matched by glob patterns
+  if (options.include) {
+    for (const pattern of options.include) {
+      const globPattern = pattern === '_root' ? 'SKILL.md' : path.join(pattern, 'SKILL.md')
+      for await (const match of fs.glob(globPattern, { cwd })) {
+        try {
+          const content = await fs.readFile(path.resolve(cwd, match), 'utf8')
+          const nameMatch = content.match(/^name:\s*(.+)$/m)
+          const skillName =
+            pattern === '_root' ? (nameMatch?.[1] ?? name) : path.basename(path.dirname(match))
+          if (!skills.some((s) => s.name === skillName)) {
+            const descMatch = content.match(/^description:\s*(.+)$/m)
+            skills.push({
+              name: skillName,
+              description: descMatch?.[1],
+              installed: installed.has(skillName),
+            })
+          }
+        } catch {}
+      }
+    }
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+export declare namespace list {
+  /** Options for listing skills. */
+  type Options = {
+    /** Working directory for resolving `include` globs. Defaults to `process.cwd()`. */
+    cwd?: string | undefined
+    /** Grouping depth for skill files. Defaults to `1`. */
+    depth?: number | undefined
+    /** CLI description, used as the top-level group description. */
+    description?: string | undefined
+    /** Glob patterns for directories containing SKILL.md files to include. */
+    include?: string[] | undefined
+  }
+  /** A skill entry with install status. */
+  type Skill = {
+    /** Description extracted from the skill frontmatter. */
+    description?: string | undefined
+    /** Whether this skill is currently installed. */
+    installed: boolean
+    /** Skill name. */
+    name: string
+  }
+}
+
 /** Recursively collects leaf commands as `Skill.CommandInfo`. */
 function collectEntries(
   commands: Map<string, any>,
   prefix: string[],
   groups: Map<string, string> = new Map(),
+  rootCommand?:
+    | {
+        description?: string | undefined
+        args?: any
+        env?: any
+        hint?: string | undefined
+        options?: any
+        output?: any
+        examples?: any[] | undefined
+      }
+    | undefined,
 ): Skill.CommandInfo[] {
   const result: Skill.CommandInfo[] = []
+  if (rootCommand) {
+    const cmd: Skill.CommandInfo = {}
+    if (rootCommand.description) cmd.description = rootCommand.description
+    if (rootCommand.args) cmd.args = rootCommand.args
+    if (rootCommand.env) cmd.env = rootCommand.env
+    if (rootCommand.hint) cmd.hint = rootCommand.hint
+    if (rootCommand.options) cmd.options = rootCommand.options
+    if (rootCommand.output) cmd.output = rootCommand.output
+    const examples = formatExamples(rootCommand.examples)
+    if (examples) cmd.examples = examples
+    result.push(cmd)
+  }
   for (const [name, entry] of commands) {
     const entryPath = [...prefix, name]
     if ('_group' in entry && entry._group) {
@@ -144,7 +257,7 @@ function collectEntries(
       result.push(cmd)
     }
   }
-  return result.sort((a, b) => a.name.localeCompare(b.name))
+  return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''))
 }
 
 /** Resolves the package root from the executing bin script (`process.argv[1]`). Walks up from the bin's directory looking for `package.json`. Falls back to `process.cwd()`. */

package/src/e2e.test.ts

@@ -967,7 +967,7 @@ describe('help', () => {
       Integrations:
         completions  Generate shell completion script
         mcp add      Register as MCP server
-        skills add   Sync skill files to agents
+        skills       Sync skill files to agents (add, list)
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
@@ -1742,7 +1742,7 @@ describe('root command with subcommands', () => {
       Integrations:
         completions  Generate shell completion script
         mcp add      Register as MCP server
-        skills add   Sync skill files to agents
+        skills       Sync skill files to agents (add, list)
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])

package/src/internal/command.ts

@@ -422,6 +422,10 @@ export const builtinCommands = [
           noGlobal: z.boolean().optional().describe('Install to project instead of globally'),
         }),
       }),
+      subcommand({
+        name: 'list',
+        description: 'List skills',
+      }),
     ],
   },
 ] satisfies {