incur 0.0.0 → 0.0.2

package/src/Schema.test.ts

@@ -0,0 +1,125 @@
+import { Schema, z } from 'incur'
+
+describe('toJsonSchema', () => {
+  test('converts z.string()', () => {
+    expect(Schema.toJsonSchema(z.string())).toEqual({ type: 'string' })
+  })
+
+  test('converts z.number()', () => {
+    expect(Schema.toJsonSchema(z.number())).toEqual({ type: 'number' })
+  })
+
+  test('converts z.boolean()', () => {
+    expect(Schema.toJsonSchema(z.boolean())).toEqual({ type: 'boolean' })
+  })
+
+  test('converts z.enum()', () => {
+    expect(Schema.toJsonSchema(z.enum(['open', 'closed']))).toEqual({
+      type: 'string',
+      enum: ['open', 'closed'],
+    })
+  })
+
+  test('converts z.array()', () => {
+    expect(Schema.toJsonSchema(z.array(z.string()))).toEqual({
+      type: 'array',
+      items: { type: 'string' },
+    })
+  })
+
+  test('converts z.object() with required fields', () => {
+    expect(Schema.toJsonSchema(z.object({ name: z.string(), count: z.number() }))).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        count: { type: 'number' },
+      },
+      required: ['name', 'count'],
+      additionalProperties: false,
+    })
+  })
+
+  test('.optional() removes from required', () => {
+    expect(
+      Schema.toJsonSchema(
+        z.object({
+          name: z.string(),
+          age: z.number().optional(),
+        }),
+      ),
+    ).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    })
+  })
+
+  test('.default() adds default to schema', () => {
+    const result = Schema.toJsonSchema(
+      z.object({
+        state: z.enum(['open', 'closed']).default('open'),
+      }),
+    )
+    expect(result).toMatchObject({
+      properties: {
+        state: { type: 'string', enum: ['open', 'closed'], default: 'open' },
+      },
+    })
+  })
+
+  test('.describe() adds description', () => {
+    const result = Schema.toJsonSchema(
+      z.object({
+        name: z.string().describe('The user name'),
+      }),
+    )
+    expect(result).toMatchObject({
+      properties: {
+        name: { type: 'string', description: 'The user name' },
+      },
+    })
+  })
+
+  test('full object with optional, default, and describe', () => {
+    const result = Schema.toJsonSchema(
+      z.object({
+        name: z.string().describe('User name'),
+        state: z.enum(['open', 'closed']).default('open').describe('Filter state'),
+        limit: z.number().optional().describe('Max items'),
+      }),
+    )
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "additionalProperties": false,
+        "properties": {
+          "limit": {
+            "description": "Max items",
+            "type": "number",
+          },
+          "name": {
+            "description": "User name",
+            "type": "string",
+          },
+          "state": {
+            "default": "open",
+            "description": "Filter state",
+            "enum": [
+              "open",
+              "closed",
+            ],
+            "type": "string",
+          },
+        },
+        "required": [
+          "name",
+          "state",
+        ],
+        "type": "object",
+      }
+    `)
+  })
+})

package/src/Schema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+/** Converts a Zod schema to a JSON Schema object. Strips the `$schema` meta-property. */
+export function toJsonSchema(schema: z.ZodType): Record<string, unknown> {
+  const result = z.toJSONSchema(schema) as Record<string, unknown>
+  delete result.$schema
+  return result
+}

package/src/Skill.test.ts

@@ -0,0 +1,293 @@
+import { Skill, z } from 'incur'
+
+test('generates skill file with frontmatter and heading', () => {
+  const result = Skill.generate('test', [{ name: 'ping', description: 'Health check' }])
+  expect(result).toMatchInlineSnapshot(`
+    "# test ping
+
+    Health check"
+  `)
+})
+
+test('includes arguments table', () => {
+  const result = Skill.generate('test', [
+    {
+      name: 'greet',
+      description: 'Greet someone',
+      args: z.object({ name: z.string().describe('Name to greet') }),
+    },
+  ])
+  expect(result).toMatchInlineSnapshot(`
+    "# test greet
+
+    Greet someone
+
+    ## Arguments
+
+    | Name | Type | Required | Description |
+    |------|------|----------|-------------|
+    | \`name\` | \`string\` | yes | Name to greet |"
+  `)
+})
+
+test('includes options table', () => {
+  const result = Skill.generate('test', [
+    {
+      name: 'list',
+      description: 'List items',
+      options: z.object({
+        limit: z.number().default(30).describe('Max items'),
+        verbose: z.boolean().default(false).describe('Show details'),
+      }),
+    },
+  ])
+  expect(result).toMatchInlineSnapshot(`
+    "# test list
+
+    List items
+
+    ## Options
+
+    | Flag | Type | Default | Description |
+    |------|------|---------|-------------|
+    | \`--limit\` | \`number\` | \`30\` | Max items |
+    | \`--verbose\` | \`boolean\` | \`false\` | Show details |"
+  `)
+})
+
+test('includes output schema', () => {
+  const result = Skill.generate('test', [
+    {
+      name: 'greet',
+      description: 'Greet someone',
+      output: z.object({ message: z.string().describe('Greeting message') }),
+    },
+  ])
+  expect(result).toMatchInlineSnapshot(`
+    "# test greet
+
+    Greet someone
+
+    ## Output
+
+    | Field | Type | Required | Description |
+    |-------|------|----------|-------------|
+    | \`message\` | \`string\` | yes | Greeting message |"
+  `)
+})
+
+test('expands nested output schema', () => {
+  const result = Skill.generate('test', [
+    {
+      name: 'list',
+      description: 'List items',
+      output: z.object({
+        items: z.array(
+          z.object({
+            id: z.number(),
+            meta: z.object({ tag: z.string() }),
+          }),
+        ),
+      }),
+    },
+  ])
+  expect(result).toMatchInlineSnapshot(`
+    "# test list
+
+    List items
+
+    ## Output
+
+    | Field | Type | Required | Description |
+    |-------|------|----------|-------------|
+    | \`items\` | \`array\` | yes |  |
+    | \`items[].id\` | \`number\` | yes |  |
+    | \`items[].meta\` | \`object\` | yes |  |
+    | \`items[].meta.tag\` | \`string\` | yes |  |"
+  `)
+})
+
+test('omits sections when not applicable', () => {
+  const result = Skill.generate('test', [{ name: 'ping', description: 'Health check' }])
+  expect(result).not.toContain('## Arguments')
+  expect(result).not.toContain('## Options')
+  expect(result).not.toContain('## Output')
+})
+
+test('concatenates multiple commands', () => {
+  const result = Skill.generate('test', [
+    { name: 'ping', description: 'Health check' },
+    { name: 'pong', description: 'Pong back' },
+  ])
+  expect(result).toMatchInlineSnapshot(`
+    "# test ping
+
+    Health check
+
+    # test pong
+
+    Pong back"
+  `)
+})
+
+describe('hash', () => {
+  test('returns consistent hash for same commands', () => {
+    const commands: Skill.CommandInfo[] = [
+      { name: 'ping', description: 'Health check' },
+      { name: 'greet', description: 'Say hello' },
+    ]
+    expect(Skill.hash(commands)).toBe(Skill.hash(commands))
+  })
+
+  test('changes when command is added', () => {
+    const a = Skill.hash([{ name: 'ping', description: 'Health check' }])
+    const b = Skill.hash([
+      { name: 'ping', description: 'Health check' },
+      { name: 'greet', description: 'Say hello' },
+    ])
+    expect(a).not.toBe(b)
+  })
+
+  test('changes when description changes', () => {
+    const a = Skill.hash([{ name: 'ping', description: 'Health check' }])
+    const b = Skill.hash([{ name: 'ping', description: 'Check health' }])
+    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() }) }])
+    expect(a).not.toBe(b)
+  })
+
+  test('returns 16-char hex string', () => {
+    const h = Skill.hash([{ name: 'ping' }])
+    expect(h).toMatch(/^[0-9a-f]{16}$/)
+  })
+})
+
+describe('split', () => {
+  const commands: Skill.CommandInfo[] = [
+    { name: 'auth login', description: 'Log in' },
+    { name: 'auth status', description: 'Check status' },
+    { name: 'pr list', description: 'List PRs' },
+    { name: 'pr create', description: 'Create PR' },
+  ]
+
+  const groups = new Map([
+    ['auth', 'Authenticate with GitHub'],
+    ['pr', 'Manage pull requests'],
+  ])
+
+  test('depth 0 returns single file', () => {
+    const files = Skill.split('gh', commands, 0)
+    expect(files.map((f) => f.dir)).toMatchInlineSnapshot(`
+      [
+        "",
+      ]
+    `)
+    expect(files[0]!.content).toContain('name: gh')
+    expect(files[0]!.content).toContain('# gh auth login')
+    expect(files[0]!.content).toContain('# gh pr list')
+  })
+
+  test('depth 1 groups by first segment with group frontmatter', () => {
+    const files = Skill.split('gh', commands, 1, groups)
+    expect(files.map((f) => f.dir)).toMatchInlineSnapshot(`
+      [
+        "auth",
+        "pr",
+      ]
+    `)
+    expect(files[0]!.content).toMatchInlineSnapshot(`
+      "---
+      name: gh-auth
+      description: Authenticate with GitHub. Log in, Check status. Run \`gh auth --help\` for usage details.
+      command: gh auth
+      ---
+
+      # gh auth login
+
+      Log in
+
+      ---
+
+      # gh auth status
+
+      Check status"
+    `)
+    expect(files[1]!.content).toMatchInlineSnapshot(`
+      "---
+      name: gh-pr
+      description: Manage pull requests. List PRs, Create PR. Run \`gh pr --help\` for usage details.
+      command: gh pr
+      ---
+
+      # gh pr list
+
+      List PRs
+
+      ---
+
+      # gh pr create
+
+      Create PR"
+    `)
+  })
+
+  test('depth 1 without group descriptions uses child descriptions', () => {
+    const files = Skill.split('gh', commands, 1)
+    expect(files[0]!.content).toContain('description: Log in, Check status. Run `gh auth --help` for usage details.')
+  })
+
+  test('depth 2 groups by first two segments', () => {
+    const files = Skill.split('gh', commands, 2)
+    expect(files.map((f) => f.dir)).toMatchInlineSnapshot(`
+      [
+        "auth-login",
+        "auth-status",
+        "pr-create",
+        "pr-list",
+      ]
+    `)
+  })
+
+  test('shallow commands use available segments', () => {
+    const files = Skill.split('test', [{ name: 'ping', description: 'Ping' }], 2)
+    expect(files.map((f) => f.dir)).toMatchInlineSnapshot(`
+      [
+        "ping",
+      ]
+    `)
+  })
+
+  test('description includes --help hint for depth 0', () => {
+    const files = Skill.split('gh', commands, 0, groups)
+    expect(files[0]!.content).toContain('Run `gh --help` for usage details.')
+  })
+
+  test('description includes --help hint for depth 1 with groups', () => {
+    const files = Skill.split('gh', commands, 1, groups)
+    expect(files[0]!.content).toContain('Run `gh auth --help` for usage details.')
+    expect(files[1]!.content).toContain('Run `gh pr --help` for usage details.')
+  })
+
+  test('description includes --help hint for depth 2', () => {
+    const files = Skill.split('gh', commands, 2)
+    expect(files[0]!.content).toContain('Run `gh auth login --help` for usage details.')
+  })
+
+  test('omits --help hint when no descriptions exist', () => {
+    const files = Skill.split('test', [{ name: 'ping' }], 1)
+    expect(files[0]!.content).not.toContain('--help')
+  })
+
+  test('no per-command frontmatter in split files', () => {
+    const files = Skill.split('gh', commands, 1, groups)
+    const afterFrontmatter = files[0]!.content.slice(
+      files[0]!.content.indexOf('---', files[0]!.content.indexOf('---') + 3) + 3,
+    )
+    expect(afterFrontmatter).not.toMatch(/^title:/m)
+    expect(afterFrontmatter).not.toMatch(/^command:/m)
+  })
+})

package/src/Skill.ts

@@ -0,0 +1,253 @@
+import { createHash } from 'node:crypto'
+import type { z } from 'zod'
+
+import * as Schema from './Schema.js'
+
+/** Information about a single command, passed to `generate()`. */
+export type CommandInfo = {
+  name: string
+  description?: string | undefined
+  args?: z.ZodObject<any> | undefined
+  env?: z.ZodObject<any> | undefined
+  hint?: string | undefined
+  options?: z.ZodObject<any> | undefined
+  output?: z.ZodType | undefined
+  examples?: { command: string; description?: string }[] | undefined
+}
+
+/** A skill file entry with its directory name and content. */
+export type File = {
+  /** Directory name relative to output root (empty string for depth 0). */
+  dir: string
+  /** Markdown content. */
+  content: string
+}
+
+/** Generates a Markdown skill file from a CLI name and collected command data. */
+export function generate(
+  name: string,
+  commands: CommandInfo[],
+  groups: Map<string, string> = new Map(),
+): string {
+  const hasGroups = groups.size > 0
+  if (!hasGroups) return commands.map((cmd) => renderCommandBody(name, cmd)).join('\n\n')
+
+  const sections: string[] = [`# ${name}`]
+  let lastGroup: string | undefined
+
+  for (const cmd of commands) {
+    const segment = 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)
+    }
+    sections.push(renderCommandBody(name, cmd, 3))
+  }
+
+  return sections.join('\n\n')
+}
+
+/** Splits commands into skill files grouped by depth. */
+export function split(
+  name: string,
+  commands: CommandInfo[],
+  depth: number,
+  groups: Map<string, string> = new Map(),
+): File[] {
+  if (depth === 0) return [{ dir: '', content: renderGroup(name, name, commands, groups, name) }]
+
+  const buckets = new Map<string, CommandInfo[]>()
+  for (const cmd of commands) {
+    const segments = cmd.name.split(' ')
+    const key = segments.slice(0, depth).join('-')
+    const bucket = buckets.get(key) ?? []
+    bucket.push(cmd)
+    buckets.set(key, bucket)
+  }
+
+  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) }
+    })
+}
+
+/** @internal Renders a group-level frontmatter + command bodies. */
+function renderGroup(
+  cli: string,
+  title: string,
+  cmds: CommandInfo[],
+  groups: Map<string, string>,
+  prefix?: string | undefined,
+): string {
+  const groupDesc = prefix ? groups.get(prefix) : undefined
+  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(', '))
+  const description = descParts.join('. ') || undefined
+
+  const slug = title.replace(/\s+/g, '-')
+  const fm = ['---', `name: ${slug}`]
+  if (description) fm.push(`description: ${description}. Run \`${title} --help\` for usage details.`)
+  fm.push(`command: ${title}`, '---')
+
+  const body = cmds.map((cmd) => renderCommandBody(cli, cmd)).join('\n\n---\n\n')
+  return `${fm.join('\n')}\n\n${body}`
+}
+
+/** @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 sections: string[] = []
+  const h = (n: number) => '#'.repeat(n)
+
+  let heading = `${h(level)} ${fullName}`
+  if (cmd.description) heading += `\n\n${cmd.description}`
+  sections.push(heading)
+
+  const sub = h(level + 1)
+
+  // Arguments table
+  if (cmd.args) {
+    const shape = cmd.args.shape as Record<string, z.ZodType>
+    const json = Schema.toJsonSchema(cmd.args)
+    const required = new Set((json.required as string[] | undefined) ?? [])
+    const properties = json.properties as Record<string, Record<string, unknown>> | undefined
+    const rows = Object.entries(shape).map(([key, field]) => {
+      const prop = properties?.[key]
+      const type = resolveTypeName(prop)
+      const req = required.has(key) ? 'yes' : 'no'
+      const desc = field.description ?? ''
+      return `| \`${key}\` | \`${type}\` | ${req} | ${desc} |`
+    })
+    sections.push(
+      `${sub} Arguments\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n${rows.join('\n')}`,
+    )
+  }
+
+  // Environment Variables table
+  if (cmd.env) {
+    const shape = cmd.env.shape as Record<string, z.ZodType>
+    const json = Schema.toJsonSchema(cmd.env)
+    const required = new Set((json.required as string[] | undefined) ?? [])
+    const properties = json.properties as Record<string, Record<string, unknown>> | undefined
+    const rows = Object.entries(shape).map(([key, field]) => {
+      const prop = properties?.[key]
+      const type = resolveTypeName(prop)
+      const def = prop?.default !== undefined ? String(prop.default) : ''
+      const req = required.has(key) ? 'yes' : 'no'
+      const desc = field.description ?? ''
+      return `| \`${key}\` | \`${type}\` | ${req} | ${def ? `\`${def}\`` : ''} | ${desc} |`
+    })
+    sections.push(
+      `${sub} Environment Variables\n\n| Name | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|\n${rows.join('\n')}`,
+    )
+  }
+
+  // Options table
+  if (cmd.options) {
+    const shape = cmd.options.shape as Record<string, z.ZodType>
+    const json = Schema.toJsonSchema(cmd.options)
+    const properties = json.properties as Record<string, Record<string, unknown>> | undefined
+    const rows = Object.entries(shape).map(([key, field]) => {
+      const prop = properties?.[key]
+      const type = resolveTypeName(prop)
+      const def = prop?.default !== undefined ? String(prop.default) : ''
+      const desc = field.description ?? ''
+      return `| \`--${key}\` | \`${type}\` | ${def ? `\`${def}\`` : ''} | ${desc} |`
+    })
+    sections.push(
+      `${sub} Options\n\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n${rows.join('\n')}`,
+    )
+  }
+
+  // Output table
+  if (cmd.output) {
+    const outputSchema = Schema.toJsonSchema(cmd.output)
+    const table = schemaToTable(outputSchema)
+    if (table) sections.push(`${sub} Output\n\n${table}`)
+    else {
+      const type = resolveTypeName(outputSchema)
+      sections.push(`${sub} Output\n\nType: \`${type}\``)
+    }
+  }
+
+  // Examples
+  if (cmd.examples && cmd.examples.length > 0) {
+    const lines = cmd.examples.map((ex) => {
+      const comment = ex.description ? `# ${ex.description}\n` : ''
+      return `${comment}${cli} ${ex.command}`
+    })
+    sections.push(`${sub} Examples\n\n\`\`\`sh\n${lines.join('\n\n')}\n\`\`\``)
+  }
+
+  // Hint
+  if (cmd.hint) sections.push(`> ${cmd.hint}`)
+
+  return sections.join('\n\n')
+}
+
+/** Computes a deterministic hash of command structure for staleness detection. */
+export function hash(commands: CommandInfo[]): string {
+  const data = commands.map((cmd) => ({
+    name: cmd.name,
+    description: cmd.description,
+    args: cmd.args ? Schema.toJsonSchema(cmd.args) : undefined,
+    env: cmd.env ? Schema.toJsonSchema(cmd.env) : undefined,
+    options: cmd.options ? Schema.toJsonSchema(cmd.options) : undefined,
+    output: cmd.output ? Schema.toJsonSchema(cmd.output) : undefined,
+  }))
+  return createHash('sha256').update(JSON.stringify(data)).digest('hex').slice(0, 16)
+}
+
+/** @internal Renders a JSON Schema object as a Markdown table. Returns `undefined` for non-object schemas. */
+function schemaToTable(schema: Record<string, unknown>, prefix = ''): string | undefined {
+  if (schema.type !== 'object') return undefined
+  const properties = schema.properties as Record<string, Record<string, unknown>> | undefined
+  if (!properties || Object.keys(properties).length === 0) return undefined
+  const required = new Set((schema.required as string[] | undefined) ?? [])
+
+  const rows: string[] = []
+  for (const [key, prop] of Object.entries(properties)) {
+    const name = prefix ? `${prefix}.${key}` : key
+    const type = resolveTypeName(prop)
+    const req = required.has(key) ? 'yes' : 'no'
+    const desc = (prop.description as string) ?? ''
+    rows.push(`| \`${name}\` | \`${type}\` | ${req} | ${desc} |`)
+
+    // Expand nested objects inline
+    if (prop.type === 'object' && prop.properties) {
+      const nested = schemaToTable(prop, name)
+      if (nested) {
+        const lines = nested.split('\n')
+        rows.push(...lines.slice(2)) // skip header + separator
+      }
+    }
+
+    // Expand array item objects inline
+    if (prop.type === 'array' && prop.items) {
+      const items = prop.items as Record<string, unknown>
+      if (items.type === 'object' && items.properties) {
+        const nested = schemaToTable(items, `${name}[]`)
+        if (nested) {
+          const lines = nested.split('\n')
+          rows.push(...lines.slice(2))
+        }
+      }
+    }
+  }
+
+  return `| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n${rows.join('\n')}`
+}
+
+/** @internal Resolves a simple type name from a JSON Schema property. */
+function resolveTypeName(prop: Record<string, unknown> | undefined): string {
+  if (!prop) return 'unknown'
+  const type = prop.type as string | undefined
+  if (type) return type === 'integer' ? 'number' : type
+  return 'unknown'
+}