incur 0.4.0 → 0.4.2

package/src/SyncSkills.test.ts

@@ -1,5 +1,5 @@
 import { Cli, SyncSkills } from 'incur'
-import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -34,8 +34,8 @@ test('generates skill files and installs to canonical location', async () => {
   })
 
   expect(result.skills.length).toBeGreaterThan(0)
-  expect(result.skills.map((s) => s.name)).toContain('greet')
-  expect(result.skills.map((s) => s.name)).toContain('ping')
+  expect(result.skills.map((s) => s.name)).toContain('test-greet')
+  expect(result.skills.map((s) => s.name)).toContain('test-ping')
 
   // Verify skills were installed to canonical location
   for (const p of result.paths) {
@@ -69,6 +69,41 @@ test('uses custom depth', async () => {
   rmSync(tmp, { recursive: true, force: true })
 })
 
+test('sync results are sorted alphabetically', async () => {
+  const tmp = join(tmpdir(), `clac-sync-sort-test-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+
+  const cli = Cli.create('test')
+  const commands = Cli.toCommands.get(cli)!
+  const installDir = join(tmp, 'install')
+  mkdirSync(join(installDir, '.agents', 'skills'), { recursive: true })
+
+  mkdirSync(join(installDir, 'zeta'), { recursive: true })
+  writeFileSync(
+    join(installDir, 'zeta', 'SKILL.md'),
+    ['---', 'name: zeta', 'description: Z skill.', '---', '', '# zeta'].join('\n'),
+  )
+  writeFileSync(
+    join(installDir, 'SKILL.md'),
+    ['---', 'name: test', 'description: Root skill.', '---', '', '# test'].join('\n'),
+  )
+  mkdirSync(join(installDir, 'alpha'), { recursive: true })
+  writeFileSync(
+    join(installDir, 'alpha', 'SKILL.md'),
+    ['---', 'name: alpha', 'description: A skill.', '---', '', '# alpha'].join('\n'),
+  )
+
+  const result = await SyncSkills.sync('test', commands, {
+    global: false,
+    cwd: installDir,
+    include: ['zeta', '_root', 'alpha'],
+  })
+
+  expect(result.skills.map((s) => s.name)).toEqual(['alpha', 'test', 'zeta'])
+
+  rmSync(tmp, { recursive: true, force: true })
+})
+
 test('writes hash after successful sync', async () => {
   const tmp = join(tmpdir(), `clac-hash-test-${Date.now()}`)
   mkdirSync(tmp, { recursive: true })
@@ -125,3 +160,111 @@ 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 shows not installed when synced skills are removed', async () => {
+  const tmp = join(tmpdir(), `clac-list-missing-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 })
+
+  const sync = await SyncSkills.sync('test', commands, {
+    global: false,
+    cwd: installDir,
+  })
+
+  rmSync(sync.paths[0]!, { recursive: true, force: true })
+
+  const result = await SyncSkills.list('test', commands)
+  expect(result).toHaveLength(1)
+  expect(result[0]!.installed).toBe(false)
+
+  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 includes root command skill', async () => {
+  const cli = Cli.create('test', {
+    description: 'A test CLI',
+    run: () => ({ ok: true }),
+  })
+  cli.command('ping', { description: 'Health check', run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  const rootCommand = Cli.toRootDefinition.get(cli as any)!
+  const result = await SyncSkills.list('test', commands, {
+    description: 'A test CLI',
+    rootCommand,
+  })
+
+  const names = result.map((s) => s.name)
+  expect(names).toContain('test')
+  expect(names).toContain('test-ping')
+})
+
+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}-`))
@@ -30,8 +30,9 @@ export async function sync(
         : path.join(tmpDir, 'SKILL.md')
       await fs.mkdir(path.dirname(filePath), { recursive: true })
       await fs.writeFile(filePath, `${file.content}\n`)
+      const nameMatch = file.content.match(/^name:\s*(.+)$/m)
       const descMatch = file.content.match(/^description:\s*(.+)$/m)
-      skills.push({ name: file.dir || name, description: descMatch?.[1] })
+      skills.push({ name: nameMatch?.[1] ?? (file.dir || name), description: descMatch?.[1] })
     }
 
     // Include additional SKILL.md files matched by glob patterns
@@ -69,10 +70,15 @@ export async function sync(
     }
 
     // Write skills hash + names for staleness detection
-    const hashEntries = collectEntries(commands, [])
-    writeMeta(name, Skill.hash(hashEntries), [...currentNames])
+    const hashEntries = collectEntries(commands, [], undefined, options.rootCommand)
+    writeMeta(
+      name,
+      Skill.hash(hashEntries),
+      [...currentNames],
+      [...paths, ...agents.map((agent) => agent.path)],
+    )
 
-    return { skills, paths, agents }
+    return { skills: skills.sort((a, b) => a.name.localeCompare(b.name)), paths, agents }
   } finally {
     await fs.rm(tmpDir, { recursive: true, force: true })
   }
@@ -91,6 +97,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 = {
@@ -112,13 +130,133 @@ 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, options.rootCommand)
+  const files = Skill.split(name, entries, depth, groups)
+
+  const skills: list.Skill[] = []
+  const installed = readInstalledSkills(name, { cwd })
+
+  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))
+}
+
+/** Returns whether any previously synced skills are still installed on disk. */
+export function hasInstalledSkills(
+  name: string,
+  options: { cwd?: string | undefined } = {},
+): boolean {
+  return readInstalledSkills(name, options).size > 0
+}
+
+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
+    /** Root command definition (when the CLI itself is a command). */
+    rootCommand?:
+      | {
+          description?: string | undefined
+          args?: any
+          env?: any
+          hint?: string | undefined
+          options?: any
+          output?: any
+          examples?: any[] | undefined
+        }
+      | 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) {
@@ -143,14 +281,24 @@ 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()`. */
 function resolvePackageRoot(): string {
   const bin = process.argv[1]
   if (!bin) return process.cwd()
-  let dir = path.dirname(fsSync.realpathSync(bin))
+  let dir = path.dirname(
+    (() => {
+      try {
+        // resolve symlinks for normal bin scripts
+        return fsSync.realpathSync(bin)
+      } catch {
+        // Bun compiled binaries use a virtual `/$bunfs/` path for argv[1]
+        return process.execPath
+      }
+    })(),
+  )
   const root = path.parse(dir).root
   while (dir !== root) {
     try {
@@ -169,15 +317,20 @@ function hashPath(name: string): string {
 }
 
 /** @internal Writes the skills metadata for staleness detection and cleanup. */
-function writeMeta(name: string, hash: string, skills: string[]) {
+function writeMeta(name: string, hash: string, skills: string[], paths: string[]) {
   const file = hashPath(name)
   const dir = path.dirname(file)
   if (!fsSync.existsSync(dir)) fsSync.mkdirSync(dir, { recursive: true })
-  fsSync.writeFileSync(file, JSON.stringify({ hash, skills, at: new Date().toISOString() }) + '\n')
+  fsSync.writeFileSync(
+    file,
+    JSON.stringify({ hash, skills, paths, at: new Date().toISOString() }) + '\n',
+  )
 }
 
 /** @internal Reads the stored metadata for a CLI. */
-function readMeta(name: string): { hash: string; skills?: string[] } | undefined {
+function readMeta(
+  name: string,
+): { hash: string; paths?: string[] | undefined; skills?: string[] | undefined } | undefined {
   try {
     return JSON.parse(fsSync.readFileSync(hashPath(name), 'utf-8'))
   } catch {
@@ -185,6 +338,34 @@ function readMeta(name: string): { hash: string; skills?: string[] } | undefined
   }
 }
 
+/** Reads the names of previously synced skills that are still installed on disk. */
+function readInstalledSkills(
+  name: string,
+  options: { cwd?: string | undefined } = {},
+): Set<string> {
+  const meta = readMeta(name)
+  if (!meta?.skills?.length) return new Set()
+
+  if (meta.paths?.length) {
+    const installed = meta.paths
+      .filter((skillPath) => isInstalledSkillPath(skillPath))
+      .map((skillPath) => path.basename(skillPath))
+    return new Set(installed)
+  }
+
+  const cwd = options.cwd ?? process.cwd()
+  const bases = [path.join(os.homedir(), '.agents', 'skills'), path.join(cwd, '.agents', 'skills')]
+  const installed = meta.skills.filter((skill) =>
+    bases.some((base) => isInstalledSkillPath(path.join(base, skill))),
+  )
+  return new Set(installed)
+}
+
+/** Returns whether a skill directory currently contains a skill file. */
+function isInstalledSkillPath(skillPath: string): boolean {
+  return fsSync.existsSync(path.join(skillPath, 'SKILL.md'))
+}
+
 /** Reads the stored skills hash for a CLI. Returns `undefined` if no hash exists. */
 export function readHash(name: string): string | undefined {
   return readMeta(name)?.hash

package/src/Typegen.test.ts

@@ -169,6 +169,21 @@ describe('fromCli', () => {
     expect(output).toContain('config: { host: string; port: number }')
   })
 
+  test('optional properties use optional modifier', () => {
+    const cli = Cli.create('test').command('create', {
+      args: z.object({ name: z.string() }),
+      options: z.object({
+        verbose: z.boolean().optional(),
+        output: z.string(),
+      }),
+      run: () => ({}),
+    })
+
+    const output = Typegen.fromCli(cli)
+    expect(output).toContain('verbose?: boolean')
+    expect(output).toContain('output: string')
+  })
+
   test('mixed top-level and grouped commands', () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({}) })

package/src/Typegen.ts

@@ -49,8 +49,9 @@ function schemaToType(schema: z.ZodObject<any> | undefined): string {
   const defs = (json.$defs ?? {}) as Record<string, Record<string, unknown>>
   const properties = json.properties as Record<string, Record<string, unknown>> | undefined
   if (!properties || Object.keys(properties).length === 0) return '{}'
+  const required = new Set((json.required as string[] | undefined) ?? [])
   const entries = Object.entries(properties).map(
-    ([key, value]) => `${key}: ${resolveType(value, defs)}`,
+    ([key, value]) => `${key}${required.has(key) ? '' : '?'}: ${resolveType(value, defs)}`,
   )
   return `{ ${entries.join('; ')} }`
 }
@@ -96,8 +97,9 @@ function resolveType(
     case 'object': {
       const properties = schema.properties as Record<string, Record<string, unknown>> | undefined
       if (!properties || Object.keys(properties).length === 0) return '{}'
+      const required = new Set((schema.required as string[] | undefined) ?? [])
       const entries = Object.entries(properties).map(
-        ([key, value]) => `${key}: ${resolveType(value, defs)}`,
+        ([key, value]) => `${key}${required.has(key) ? '' : '?'}: ${resolveType(value, defs)}`,
       )
       return `{ ${entries.join('; ')} }`
     }

package/src/bin.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
+import fs from 'node:fs/promises'
 import path from 'node:path'
 import { z } from 'zod'
 
 import * as Cli from './Cli.js'
+import * as ConfigSchema from './internal/configSchema.js'
+import { importCli } from './internal/utils.js'
 import * as Typegen from './Typegen.js'
 
 const cli = Cli.create('incur', {
@@ -15,6 +18,10 @@ const cli = Cli.create('incur', {
 }).command('gen', {
   description: 'Generate type definitions for development.',
   options: z.object({
+    configSchema: z
+      .boolean()
+      .optional()
+      .describe('Generate config JSON Schema (auto-detected by default)'),
     dir: z.string().optional().describe('Project root directory'),
     entry: z.string().optional().describe('Entrypoint path (absolute)'),
     output: z.string().optional().describe('Output path (absolute)'),
@@ -23,8 +30,20 @@ const cli = Cli.create('incur', {
     const dir = c.options.dir ?? '.'
     const entry = c.options.entry ?? dir
     const output = c.options.output ?? path.join(dir, 'incur.generated.ts')
-    await Typegen.generate(entry, output)
-    return { dir, entry, output }
+
+    const cli = await importCli(entry)
+    await fs.writeFile(output, Typegen.fromCli(cli))
+
+    const result: Record<string, unknown> = { dir, entry, output }
+
+    const configSchema = c.options.configSchema ?? ConfigSchema.hasConfig(cli)
+    if (configSchema) {
+      const schemaOutput = path.join(path.dirname(output), 'config.schema.json')
+      await fs.writeFile(schemaOutput, JSON.stringify(ConfigSchema.fromCli(cli), null, 2) + '\n')
+      result.configSchema = schemaOutput
+    }
+
+    return result
   },
 })