incur 0.0.0 → 0.0.2

package/src/Skillgen.ts

@@ -0,0 +1,66 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import * as Cli from './Cli.js'
+import { importCli } from './internal/utils.js'
+import * as Skill from './Skill.js'
+
+/** Imports a CLI from `input`, generates Markdown skill files, and writes them to `output`. */
+export async function generate(input: string, output: string, depth = 1): Promise<string[]> {
+  const cli = await importCli(input)
+  const commands = Cli.toCommands.get(cli)
+  if (!commands) throw new Error('No commands registered on this CLI instance')
+
+  const groups = new Map<string, string>()
+  if (cli.description) groups.set(cli.name, cli.description)
+  const entries = collectEntries(commands, [], groups)
+  const files = Skill.split(cli.name, entries, depth, groups)
+
+  if (depth > 0) await fs.rm(output, { recursive: true, force: true })
+
+  const written: string[] = []
+  for (const file of files) {
+    const filePath = file.dir
+      ? path.join(output, file.dir, 'SKILL.md')
+      : path.join(output, 'SKILL.md')
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+    await fs.writeFile(filePath, `${file.content}\n`)
+    written.push(filePath)
+  }
+
+  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))
+}

package/src/SyncMcp.test.ts

@@ -0,0 +1,75 @@
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { detectPackageSpecifier } from './SyncMcp.js'
+
+let savedArgv1: string | undefined
+let tmp: string
+
+beforeEach(() => {
+  savedArgv1 = process.argv[1]
+  tmp = join(tmpdir(), `clac-test-${Date.now()}`)
+  mkdirSync(join(tmp, 'node_modules', '.bin'), { recursive: true })
+})
+
+afterEach(() => {
+  process.argv[1] = savedArgv1!
+  rmSync(tmp, { recursive: true, force: true })
+})
+
+function setupPkg(deps: Record<string, string>) {
+  writeFileSync(join(tmp, 'package.json'), JSON.stringify({ dependencies: deps }))
+  process.argv[1] = join(tmp, 'node_modules', '.bin', 'my-cli')
+}
+
+test('returns bare name when argv[1] is undefined', () => {
+  process.argv[1] = undefined as any
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli')
+})
+
+test('returns bare name when no node_modules in path', () => {
+  process.argv[1] = '/usr/local/bin/my-cli'
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli')
+})
+
+test('returns bare name when package.json is missing', () => {
+  process.argv[1] = join(tmp, 'node_modules', '.bin', 'my-cli')
+  // no package.json written
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli')
+})
+
+test('returns bare name when dep is not found', () => {
+  setupPkg({ other: '1.0.0' })
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli')
+})
+
+test('returns bare name when multiple deps exist', () => {
+  setupPkg({ 'my-cli': '1.0.0', other: '2.0.0' })
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli')
+})
+
+test('returns URL specifier for https dep', () => {
+  setupPkg({ 'my-cli': 'https://pkg.pr.new/my-cli@abc123' })
+  expect(detectPackageSpecifier('my-cli')).toBe('https://pkg.pr.new/my-cli@abc123')
+})
+
+test('returns URL specifier for file: dep', () => {
+  setupPkg({ 'my-cli': 'file:../local-cli' })
+  expect(detectPackageSpecifier('my-cli')).toBe('file:../local-cli')
+})
+
+test('returns name@version for pinned version', () => {
+  setupPkg({ 'my-cli': '1.2.3' })
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli@1.2.3')
+})
+
+test('returns bare name for range specifier', () => {
+  setupPkg({ 'my-cli': '^1.0.0' })
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli')
+})
+
+test('returns bare name for tag specifier', () => {
+  setupPkg({ 'my-cli': 'latest' })
+  expect(detectPackageSpecifier('my-cli')).toBe('my-cli')
+})

package/src/SyncMcp.ts

@@ -0,0 +1,132 @@
+import { execFile } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { detectRunner } from './internal/pm.js'
+
+/** Registers the CLI as an MCP server via `npx add-mcp` and direct config writes for unsupported agents. */
+export async function register(
+  name: string,
+  options: register.Options = {},
+): Promise<register.Result> {
+  const runner = detectRunner()
+  const command = options.command ?? `${runner} ${detectPackageSpecifier(name)} --mcp`
+  const targetAgents = options.agents ?? []
+  const ampOnly = targetAgents.length === 1 && targetAgents[0] === 'amp'
+
+  const agents: string[] = []
+
+  // Run add-mcp for agents it supports (skip if only targeting Amp)
+  if (!ampOnly) {
+    const args = [command, '--name', name, '-y']
+    if (options.global !== false) args.push('-g')
+    for (const agent of targetAgents.filter((a) => a !== 'amp')) args.push('-a', agent)
+
+    const [cmd, ...prefix] = runner.split(' ')
+    const { stdout } = await exec(cmd!, [...prefix, 'add-mcp', ...args])
+
+    // Extract agent names from add-mcp output (lines like "│ ✓ Claude Code: ~/.claude.json │")
+    agents.push(
+      ...stdout
+        .split('\n')
+        .filter((l) => l.includes('✓') || l.includes('✔'))
+        .map((l) =>
+          l
+            .replace(/[│┃|]/g, '')
+            .replace(/.*[✓✔]\s*/, '')
+            .replace(/:.*/, '')
+            .trim(),
+        )
+        .filter(Boolean),
+    )
+  }
+
+  // Register with Amp directly (add-mcp doesn't support it)
+  if (targetAgents.length === 0 || targetAgents.includes('amp')) {
+    const registered = registerAmp(name, command)
+    if (registered) agents.push('Amp')
+  }
+
+  return { command, agents }
+}
+
+/** @internal Registers an MCP server in Amp's settings.json. */
+function registerAmp(name: string, command: string): boolean {
+  const configPath = join(homedir(), '.config', 'amp', 'settings.json')
+
+  let config: Record<string, any> = {}
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'))
+    } catch {
+      return false
+    }
+  }
+
+  const [cmd, ...args] = command.split(' ')
+  if (!cmd) return false
+
+  const servers: Record<string, any> = config['amp.mcpServers'] ?? {}
+  servers[name] = { command: cmd, args }
+  config['amp.mcpServers'] = servers
+
+  const dir = dirname(configPath)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+
+  return true
+}
+
+export declare namespace register {
+  /** Options for registering an MCP server. */
+  type Options = {
+    /** Target specific agents (e.g. `'claude-code'`, `'cursor'`). */
+    agents?: string[] | undefined
+    /** Override the command agents will run. Defaults to `<runner> <name> --mcp`. */
+    command?: string | undefined
+    /** Install globally. Defaults to `true`. */
+    global?: boolean | undefined
+  }
+
+  /** Result of a register operation. */
+  type Result = {
+    /** Agents the server was registered with. */
+    agents: string[]
+    /** The command registered. */
+    command: string
+  }
+}
+
+/** @internal Detects the package specifier used to run this CLI (handles dlx/npx URL and version installs). */
+export function detectPackageSpecifier(name: string): string {
+  const bin = process.argv[1]
+  if (!bin) return name
+
+  const match = bin.match(/^(.+)[/\\]node_modules[/\\]/)
+  if (!match) return name
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(match[1]!, 'package.json'), 'utf-8'))
+    const deps = pkg.dependencies ?? {}
+    const spec = deps[name]
+    if (!spec || Object.keys(deps).length !== 1) return name
+
+    if (/^https?:\/\//.test(spec) || spec.startsWith('file:')) return spec
+    if (/^\d/.test(spec)) return `${name}@${spec}`
+  } catch {}
+
+  return name
+}
+
+/** Promisified execFile with stderr in error message. */
+function exec(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, (error, stdout, stderr) => {
+      if (error) {
+        const msg = stderr?.trim() || stdout?.trim() || error.message
+        reject(new Error(msg))
+      } else resolve({ stdout, stderr })
+    })
+  })
+}

package/src/SyncSkills.test.ts

@@ -0,0 +1,92 @@
+import { Cli, SyncSkills } from 'incur'
+import { mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+let mockExecError: Error | null = null
+
+vi.mock('node:child_process', () => ({
+  execFile: (_cmd: string, _args: string[], cb: Function) => {
+    if (mockExecError) cb(mockExecError, '', '')
+    else cb(null, '', '')
+  },
+}))
+
+let savedXdg: string | undefined
+
+beforeEach(() => {
+  mockExecError = null
+  savedXdg = process.env.XDG_DATA_HOME
+})
+
+afterEach(() => {
+  if (savedXdg === undefined) delete process.env.XDG_DATA_HOME
+  else process.env.XDG_DATA_HOME = savedXdg
+})
+
+test('generates skill files to temp dir and calls runner', async () => {
+  const cli = Cli.create('test', { description: 'A test CLI' })
+  cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
+  cli.command('greet', { description: 'Say hello', run: () => ({ hi: true }) })
+
+  const commands = Cli.toCommands.get(cli)!
+  const result = await SyncSkills.sync('test', commands, {
+    description: 'A test CLI',
+    runner: 'npx',
+  })
+
+  expect(result.skills.length).toBeGreaterThan(0)
+  expect(result.skills.map((s) => s.name)).toContain('greet')
+  expect(result.skills.map((s) => s.name)).toContain('ping')
+})
+
+test('uses custom depth', async () => {
+  const cli = Cli.create('test')
+  cli.command('ping', { description: 'Ping', run: () => ({}) })
+  cli.command('pong', { description: 'Pong', run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  const result = await SyncSkills.sync('test', commands, { depth: 0, runner: 'npx' })
+
+  // depth 0 = single skill
+  expect(result.skills).toHaveLength(1)
+})
+
+test('propagates runner errors', async () => {
+  mockExecError = new Error('skills not found')
+
+  const cli = Cli.create('test')
+  cli.command('ping', { run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  await expect(SyncSkills.sync('test', commands, { runner: 'npx' })).rejects.toThrow(
+    'skills not found',
+  )
+})
+
+test('writes hash after successful sync', async () => {
+  const tmp = join(tmpdir(), `clac-hash-test-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+  process.env.XDG_DATA_HOME = tmp
+
+  const cli = Cli.create('hash-test')
+  cli.command('ping', { description: 'Health check', run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  await SyncSkills.sync('hash-test', commands, { runner: 'npx' })
+
+  const stored = SyncSkills.readHash('hash-test')
+  expect(stored).toMatch(/^[0-9a-f]{16}$/)
+
+  rmSync(tmp, { recursive: true, force: true })
+})
+
+test('readHash returns undefined when no hash exists', () => {
+  const tmp = join(tmpdir(), `clac-hash-test-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+  process.env.XDG_DATA_HOME = tmp
+
+  expect(SyncSkills.readHash('nonexistent')).toBeUndefined()
+
+  rmSync(tmp, { recursive: true, force: true })
+})

package/src/SyncSkills.ts

@@ -0,0 +1,205 @@
+import { execFile } from 'node:child_process'
+import fsSync from 'node:fs'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { formatExamples } from './Cli.js'
+import { detectRunner } from './internal/pm.js'
+import * as Skill from './Skill.js'
+
+/** Generates skill files from a command map and installs them via `skills add`. */
+export async function sync(
+  name: string,
+  commands: Map<string, any>,
+  options: sync.Options = {},
+): Promise<sync.Result> {
+  const cwd = options.cwd ?? resolvePackageRoot()
+  const { depth = 1, description, global = true } = options
+
+  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 tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), `incur-skills-${name}-`))
+  try {
+    const skills: sync.Skill[] = []
+    for (const file of files) {
+      const filePath = file.dir
+        ? path.join(tmpDir, file.dir, 'SKILL.md')
+        : path.join(tmpDir, 'SKILL.md')
+      await fs.mkdir(path.dirname(filePath), { recursive: true })
+      await fs.writeFile(filePath, `${file.content}\n`)
+      const descMatch = file.content.match(/^description:\s*(.+)$/m)
+      skills.push({ name: file.dir || name, description: descMatch?.[1] })
+    }
+
+    // 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))
+            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 })
+            }
+          } catch {}
+        }
+      }
+    }
+
+    const runner = options.runner ?? detectRunner()
+    const [cmd, ...prefix] = runner.split(' ')
+    const flags = ['--yes', ...(global ? ['--global'] : [])]
+    const { stdout } = await exec(cmd!, [...prefix, 'skills', 'add', tmpDir, ...flags])
+
+    // Extract installed paths from `skills add` output (lines like "✓ ~/path/to/skill")
+    const paths = stdout
+      .split('\n')
+      .filter((l) => l.includes('✓'))
+      .map((l) =>
+        l
+          .replace(/.*✓\s*/, '')
+          .replace(/[│┃|]/g, '')
+          .trim(),
+      )
+      .filter(Boolean)
+
+    // Write skills hash for staleness detection
+    const entries = collectEntries(commands, [])
+    writeHash(name, Skill.hash(entries))
+
+    return { skills, paths }
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  }
+}
+
+export declare namespace sync {
+  /** Options for syncing 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
+    /** Install globally (`~/.config/agents/skills/`) instead of project-local. Defaults to `true`. */
+    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
+    /** Override the package manager runner (e.g. `npx`, `pnpx`, `bunx`). Auto-detected if omitted. */
+    runner?: string | undefined
+  }
+  /** Result of a sync operation. */
+  type Result = {
+    /** Installed paths reported by `skills add`. */
+    paths: string[]
+    /** Synced skills with metadata. */
+    skills: Skill[]
+  }
+  /** A synced skill entry. */
+  type Skill = {
+    /** Description extracted from the skill frontmatter. */
+    description?: string | undefined
+    /** Whether this skill was included from a local file (not generated from commands). */
+    external?: boolean | undefined
+    /** Skill directory name. */
+    name: string
+  }
+}
+
+/** Recursively collects leaf commands as `Skill.CommandInfo`. */
+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 entryPath = [...prefix, name]
+    if ('_group' in entry && entry._group) {
+      if (entry.description) groups.set(entryPath.join(' '), entry.description)
+      result.push(...collectEntries(entry.commands, entryPath, groups))
+    } else {
+      const cmd: Skill.CommandInfo = { name: entryPath.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 = formatExamples(entry.examples)
+      if (examples) {
+        const cmdName = entryPath.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))
+}
+
+/** 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))
+  const root = path.parse(dir).root
+  while (dir !== root) {
+    try {
+      fsSync.accessSync(path.join(dir, 'package.json'))
+      return dir
+    } catch {}
+    dir = path.dirname(dir)
+  }
+  return process.cwd()
+}
+
+/** Returns the hash file path for a CLI. */
+function hashPath(name: string): string {
+  const dir = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share')
+  return path.join(dir, 'incur', `${name}.json`)
+}
+
+/** @internal Writes the skills hash for staleness detection. */
+function writeHash(name: string, hash: 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, at: new Date().toISOString() }) + '\n')
+}
+
+/** Reads the stored skills hash for a CLI. Returns `undefined` if no hash exists. */
+export function readHash(name: string): string | undefined {
+  try {
+    const data = JSON.parse(fsSync.readFileSync(hashPath(name), 'utf-8'))
+    return data.hash
+  } catch {
+    return undefined
+  }
+}
+
+/** Promisified execFile with stderr in error message. */
+function exec(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, (error, stdout, stderr) => {
+      if (error) {
+        const msg = stderr?.trim() || stdout?.trim() || error.message
+        reject(new Error(msg))
+      } else resolve({ stdout, stderr })
+    })
+  })
+}