incur 0.4.3 → 0.4.5

package/src/Errors.test.ts

@@ -66,6 +66,8 @@ describe('ValidationError', () => {
       message: 'Invalid arguments',
       fieldErrors: [
         {
+          code: 'invalid_value',
+          missing: false,
           path: 'state',
           expected: 'open | closed',
           received: 'invalid',
@@ -76,6 +78,8 @@ describe('ValidationError', () => {
     expect(error.name).toBe('Incur.ValidationError')
     expect(error.fieldErrors).toEqual([
       {
+        code: 'invalid_value',
+        missing: false,
         path: 'state',
         expected: 'open | closed',
         received: 'invalid',

package/src/Errors.ts

@@ -73,6 +73,10 @@ export declare namespace IncurError {
 
 /** A field-level validation error detail. */
 export type FieldError = {
+  /** The Zod issue code. */
+  code?: string | undefined
+  /** Whether the input was missing entirely. */
+  missing?: boolean | undefined
   /** The field path that failed validation. */
   path: string
   /** The expected value or type. */

package/src/Formatter.test.ts

@@ -81,6 +81,16 @@ describe('format', () => {
     expect(Formatter.format('hello world', 'md')).toBe('hello world')
   })
 
+  test('formats JSON object strings as JSON', () => {
+    const result = Formatter.format('{"url":"https://example.com/","title":""}', 'json')
+    expect(result).toMatchInlineSnapshot(`
+      "{
+        "url": "https://example.com/",
+        "title": ""
+      }"
+    `)
+  })
+
   test('formats number value', () => {
     expect(Formatter.format(42)).toBe('42')
     expect(Formatter.format(42, 'json')).toBe('42')

package/src/Formatter.ts

@@ -7,7 +7,17 @@ export type Format = 'toon' | 'json' | 'yaml' | 'md' | 'jsonl'
 /** Serializes a value to the specified format. Defaults to TOON. */
 export function format(value: unknown, fmt: Format = 'toon'): string {
   if (value == null) return ''
-  if (fmt === 'json') return JSON.stringify(value, null, 2)
+  if (fmt === 'json') {
+    if (typeof value === 'string') {
+      const trimmed = value.trim()
+      if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+          return JSON.stringify(JSON.parse(value), null, 2)
+        } catch {}
+      }
+    }
+    return JSON.stringify(value, null, 2)
+  }
   if (fmt === 'yaml') return yamlStringify(value)
   if (fmt === 'md') return formatMarkdown(value)
   if (fmt === 'jsonl') {

package/src/Parser.test.ts

@@ -107,6 +107,40 @@ describe('parse', () => {
     ).toThrow(expect.objectContaining({ name: 'Incur.ValidationError' }))
   })
 
+  test('captures missing metadata for missing positional args', () => {
+    try {
+      Parser.parse([], {
+        args: z.object({ name: z.string() }),
+      })
+      expect.unreachable()
+    } catch (error: any) {
+      expect(error.fieldErrors).toEqual([
+        expect.objectContaining({
+          code: 'invalid_type',
+          missing: true,
+          path: 'name',
+        }),
+      ])
+    }
+  })
+
+  test('captures metadata for invalid option values', () => {
+    try {
+      Parser.parse(['--state', 'invalid'], {
+        options: z.object({ state: z.enum(['open', 'closed']) }),
+      })
+      expect.unreachable()
+    } catch (error: any) {
+      expect(error.fieldErrors).toEqual([
+        expect.objectContaining({
+          code: 'invalid_value',
+          missing: false,
+          path: 'state',
+        }),
+      ])
+    }
+  })
+
   test('stacks boolean short aliases (-vD)', () => {
     const result = Parser.parse(['-vD'], {
       options: z.object({

package/src/Parser.ts

@@ -263,6 +263,8 @@ function zodParse(schema: z.ZodObject<any>, data: Record<string, unknown>) {
   } catch (err: any) {
     const issues: any[] = err?.issues ?? err?.error?.issues ?? []
     const fieldErrors: FieldError[] = issues.map((issue: any) => ({
+      code: issue.code,
+      missing: !hasPath(data, issue.path ?? []),
       path: (issue.path ?? []).join('.'),
       expected: issue.expected ?? '',
       received: issue.received ?? '',
@@ -276,6 +278,20 @@ function zodParse(schema: z.ZodObject<any>, data: Record<string, unknown>) {
   }
 }
 
+/** Checks whether the raw input contains the full issue path. */
+function hasPath(data: Record<string, unknown>, path: PropertyKey[]): boolean {
+  if (path.length === 0) return true
+
+  let current: unknown = data
+  for (const part of path) {
+    if (!isRecord(current) && !Array.isArray(current)) return false
+    if (!(part in current)) return false
+    current = (current as any)[part]
+  }
+
+  return true
+}
+
 /** Parses environment variables against a Zod schema. Falls back to `process.env` → `Deno.env` when no source is provided. */
 export function parseEnv<const env extends z.ZodObject<any>>(
   schema: env,

package/src/Skill.test.ts

@@ -373,6 +373,14 @@ describe('split', () => {
     expect(files[0]!.content).toContain('requires_bin: gh')
   })
 
+  test('YAML-quotes description containing colon-space', () => {
+    const groups = new Map([['search', 'Search items. Use key: value for precision']])
+    const files = Skill.split('app', [{ name: 'search list', description: 'List results' }], 1, groups)
+    expect(files[0]!.content).toContain(
+      'description: "Search items. Use key: value for precision. Run `app search --help` for usage details."',
+    )
+  })
+
   test('no per-command frontmatter in split files', () => {
     const files = Skill.split('gh', commands, 1, groups)
     const afterFrontmatter = files[0]!.content.slice(

package/src/Skill.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto'
 import type { z } from 'zod'
+import { stringify as yamlStringify } from 'yaml'
 
 import * as Schema from './Schema.js'
 
@@ -136,13 +137,14 @@ function renderGroup(
     ? `${desc.replace(/\.$/, '')}. Run \`${title} --help\` for usage details.`
     : `Run \`${title} --help\` for usage details.`
 
-  const fm = ['---', `name: ${slugify(title)}`]
-  fm.push(`description: ${description}`)
-  fm.push(`requires_bin: ${cli}`)
-  fm.push(`command: ${title}`, '---')
+  const fm = yamlStringify(
+    { 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')
-  return `${fm.join('\n')}\n\n${body}`
+  return `${fmBlock}\n\n${body}`
 }
 
 /** @internal Renders a command's heading and sections without frontmatter. */

package/src/SyncSkills.test.ts

@@ -161,6 +161,37 @@ test('installed SKILL.md contains frontmatter', async () => {
   rmSync(tmp, { recursive: true, force: true })
 })
 
+test('sync returns unquoted descriptions from YAML frontmatter', async () => {
+  const tmp = join(tmpdir(), `clac-quoted-description-test-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+
+  const search = Cli.create('search', { description: 'Search items. Use key: value for precision' })
+  search.command('list', { description: 'List results', run: () => ({}) })
+
+  const cli = Cli.create('app')
+  cli.command('search', search)
+
+  const commands = Cli.toCommands.get(cli)!
+  const installDir = join(tmp, 'install')
+  mkdirSync(join(installDir, '.agents', 'skills'), { recursive: true })
+
+  const result = await SyncSkills.sync('app', commands, {
+    global: false,
+    cwd: installDir,
+  })
+
+  expect(result.skills).toMatchInlineSnapshot(`
+    [
+      {
+        "description": "Search items. Use key: value for precision. Run \`app search --help\` for usage details.",
+        "name": "app-search",
+      },
+    ]
+  `)
+
+  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: () => ({}) })

package/src/SyncSkills.ts

@@ -2,6 +2,7 @@ import fsSync from 'node:fs'
 import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
+import { parse as yamlParse } from 'yaml'
 
 import { formatExamples } from './Cli.js'
 import * as Agents from './internal/agents.js'
@@ -30,9 +31,8 @@ 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: nameMatch?.[1] ?? (file.dir || name), description: descMatch?.[1] })
+      const meta = parseFrontmatter(file.content)
+      skills.push({ name: meta.name ?? (file.dir || name), description: meta.description })
     }
 
     // Include additional SKILL.md files matched by glob patterns
@@ -42,16 +42,14 @@ export async function sync(
         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 meta = parseFrontmatter(content)
             const skillName =
-              pattern === '_root' ? (nameMatch?.[1] ?? name) : path.basename(path.dirname(match))
+              pattern === '_root' ? (meta.name ?? name) : path.basename(path.dirname(match))
             const dest = path.join(tmpDir, skillName, 'SKILL.md')
             await fs.mkdir(path.dirname(dest), { recursive: true })
             await fs.writeFile(dest, content)
-            if (!skills.some((s) => s.name === skillName)) {
-              const descMatch = content.match(/^description:\s*(.+)$/m)
-              skills.push({ name: skillName, description: descMatch?.[1], external: true })
-            }
+            if (!skills.some((s) => s.name === skillName))
+              skills.push({ name: skillName, description: meta.description, external: true })
           } catch {}
         }
       }
@@ -148,12 +146,11 @@ export async function list(
   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)
+    const meta = parseFrontmatter(file.content)
+    const skillName = meta.name ?? (file.dir || name)
     skills.push({
       name: skillName,
-      description: descMatch?.[1],
+      description: meta.description,
       installed: installed.has(skillName),
     })
   }
@@ -165,14 +162,12 @@ export async function list(
       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))
+          const meta = parseFrontmatter(content)
+          const skillName = pattern === '_root' ? (meta.name ?? 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],
+              description: meta.description,
               installed: installed.has(skillName),
             })
           }
@@ -284,6 +279,15 @@ function collectEntries(
   return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''))
 }
 
+function parseFrontmatter(content: string): { description?: string | undefined; name?: string | undefined } {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) return {}
+
+  const meta = yamlParse(match[1]!)
+  if (!meta || typeof meta !== 'object') return {}
+  return meta as { description?: string | undefined; name?: string | undefined }
+}
+
 /** 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]