@o/cli 0.16.19 → 0.16.20

package/src/tko/commands/skills.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+import { transformSkillForHarness } from './skills'
+
+describe('transformSkillForHarness', () => {
+  it('maps runner tiers to Claude models for claude harness', () => {
+    const inputSm = `---
+name: my-skill
+model: sm
+description: A helpful skill
+---
+
+# My skill
+`
+    const outputSm = transformSkillForHarness(inputSm, 'claude')
+    expect(outputSm).toContain('model: haiku')
+    expect(outputSm).not.toContain('model: sm')
+
+    const inputMd = `---
+name: my-skill
+model: md
+description: A helpful skill
+---
+`
+    expect(transformSkillForHarness(inputMd, 'claude')).toContain('model: sonnet')
+
+    const inputLg = `---
+name: my-skill
+model: lg
+description: A helpful skill
+---
+`
+    expect(transformSkillForHarness(inputLg, 'claude')).toContain('model: opus')
+
+    const inputXl = `---
+name: my-skill
+model: xl
+description: A helpful skill
+---
+`
+    expect(transformSkillForHarness(inputXl, 'claude')).toContain('model: fable')
+  })
+
+  it('leaves models untouched for agents harness', () => {
+    const input = `---
+name: my-skill
+model: sm
+description: A helpful skill
+---
+`
+    expect(transformSkillForHarness(input, 'agents')).toBe(input)
+  })
+
+  it('leaves already-specific Claude models untouched', () => {
+    const input = `---
+name: my-skill
+model: haiku
+description: A helpful skill
+---
+`
+    expect(transformSkillForHarness(input, 'claude')).toBe(input)
+  })
+
+  it('leaves files without model untouched', () => {
+    const input = `---
+name: my-skill
+description: A helpful skill
+---
+
+# Body
+`
+    expect(transformSkillForHarness(input, 'claude')).toBe(input)
+  })
+})
+
+describe('skills generation ownership', () => {
+  it('leaves linked skill directories intact during generation, clean and stale pruning', () => {
+    const fixture = mkdtempSync(join(tmpdir(), 'orez-skill-ownership-'))
+    const cli = resolve(import.meta.dir, '../cli.ts')
+    const original =
+      '---\nname: upgrade\ndescription: shared owned skill\n---\nkeep this source\n'
+    try {
+      const shared = join(fixture, '.team-machine/skills/upgrade')
+      mkdirSync(shared, { recursive: true })
+      writeFileSync(join(shared, 'SKILL.md'), original)
+      mkdirSync(join(shared, 'agents'))
+      const docs = join(fixture, 'skills')
+      mkdirSync(docs)
+      for (const harness of ['.claude', '.agents']) {
+        const root = join(fixture, harness, 'skills')
+        mkdirSync(root, { recursive: true })
+        symlinkSync(shared, join(root, 'upgrade'), 'dir')
+        symlinkSync(shared, join(root, 'takeout-linked'), 'dir')
+        const stale = join(root, 'takeout-stale')
+        mkdirSync(stale)
+        writeFileSync(join(stale, 'SKILL.md'), 'old generated skill')
+      }
+      const run = (clean: boolean) => {
+        const result = Bun.spawnSync({
+          cmd: [
+            process.execPath,
+            cli,
+            'skills',
+            'generate',
+            ...(clean ? ['--clean'] : []),
+          ],
+          cwd: fixture,
+          stdout: 'pipe',
+          stderr: 'pipe',
+        })
+        expect(result.exitCode).toBe(0)
+        expect(result.stderr.toString()).toBe('')
+        expect(readFileSync(join(shared, 'SKILL.md'), 'utf8')).toBe(original)
+        for (const harness of ['.claude', '.agents']) {
+          const root = join(fixture, harness, 'skills')
+          expect(lstatSync(join(root, 'upgrade')).isSymbolicLink()).toBe(true)
+          expect(lstatSync(join(root, 'takeout-linked')).isSymbolicLink()).toBe(true)
+          expect(existsSync(join(root, 'takeout-stale'))).toBe(false)
+        }
+      }
+      run(false)
+      writeFileSync(
+        join(docs, 'upgrade.md'),
+        '---\nname: upgrade\ndescription: a generated name collision\nmodel: md\n---\nreplacement\n'
+      )
+      writeFileSync(
+        join(docs, 'current.md'),
+        '---\nname: current\ndescription: actual generated output\nmodel: md\n---\ncurrent source\n'
+      )
+      run(true)
+      expect(
+        readFileSync(join(fixture, '.claude/skills/current/SKILL.md'), 'utf8')
+      ).toContain('model: sonnet')
+      expect(
+        readFileSync(join(fixture, '.agents/skills/current/SKILL.md'), 'utf8')
+      ).toContain('model: md')
+    } finally {
+      rmSync(fixture, { recursive: true, force: true })
+    }
+  })
+
+  it('leaves a linked harness root intact while generating for independent harnesses', () => {
+    const fixture = mkdtempSync(join(tmpdir(), 'orez-skill-root-'))
+    try {
+      const shared = join(fixture, 'shared-skills')
+      mkdirSync(join(shared, 'manual'), { recursive: true })
+      writeFileSync(join(shared, 'manual/SKILL.md'), 'retain root-owned source')
+      mkdirSync(join(fixture, '.claude'))
+      symlinkSync(shared, join(fixture, '.claude/skills'), 'dir')
+      mkdirSync(join(fixture, 'skills'))
+      writeFileSync(
+        join(fixture, 'skills/current.md'),
+        '---\nname: current\ndescription: generated skill\n---\ncurrent source\n'
+      )
+      const result = Bun.spawnSync({
+        cmd: [
+          process.execPath,
+          resolve(import.meta.dir, '../cli.ts'),
+          'skills',
+          'generate',
+          '--clean',
+        ],
+        cwd: fixture,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      expect(result.exitCode).toBe(0)
+      expect(result.stderr.toString()).toBe('')
+      expect(readFileSync(join(shared, 'manual/SKILL.md'), 'utf8')).toBe(
+        'retain root-owned source'
+      )
+      expect(existsSync(join(shared, 'current'))).toBe(false)
+      expect(lstatSync(join(fixture, '.claude/skills')).isSymbolicLink()).toBe(true)
+      expect(
+        readFileSync(join(fixture, '.agents/skills/current/SKILL.md'), 'utf8')
+      ).toContain('current source')
+    } finally {
+      rmSync(fixture, { recursive: true, force: true })
+    }
+  })
+})

package/src/tko/commands/skills.ts

@@ -0,0 +1,361 @@
+/**
+ * skills command group - manage repository agent skills
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  rmdirSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+
+import { defineCommand } from 'citty'
+import pc from 'picocolors'
+
+// --- doc skills generation ---
+
+const SKILL_PREFIX = 'takeout-'
+
+export type SkillHarness = 'claude' | 'agents'
+
+export interface SkillTargetDir {
+  path: string
+  harness: SkillHarness
+}
+
+export const TIER_TO_CLAUDE_MODEL: Record<string, string> = {
+  sm: 'haiku',
+  md: 'sonnet',
+  lg: 'opus',
+  xl: 'fable',
+}
+
+export function transformSkillForHarness(content: string, harness: SkillHarness): string {
+  if (harness !== 'claude') return content
+  if (!content.startsWith('---')) return content
+  const endIndex = content.indexOf('---', 3)
+  if (endIndex === -1) return content
+  const frontmatter = content.slice(0, endIndex)
+  const transformed = frontmatter.replace(
+    /^(\s*model:\s*)(sm|md|lg|xl)\s*$/m,
+    (match, prefix, tier) => {
+      const mapped = TIER_TO_CLAUDE_MODEL[tier]
+      return mapped ? `${prefix}${mapped}` : match
+    }
+  )
+  return transformed + content.slice(endIndex)
+}
+
+function getSkillsDirs(cwd: string): SkillTargetDir[] {
+  return [
+    { path: join(cwd, '.claude', 'skills'), harness: 'claude' },
+    { path: join(cwd, '.agents', 'skills'), harness: 'agents' },
+  ].filter(
+    (target) => !lstatSync(target.path, { throwIfNoEntry: false })?.isSymbolicLink()
+  ) as SkillTargetDir[]
+}
+
+function hasSkillFrontmatter(content: string): boolean {
+  if (!content.startsWith('---')) return false
+  const endIndex = content.indexOf('---', 3)
+  if (endIndex === -1) return false
+  const frontmatter = content.slice(3, endIndex)
+  return frontmatter.includes('name:') && frontmatter.includes('description:')
+}
+
+function isDevOnly(content: string): boolean {
+  if (!content.startsWith('---')) return false
+  const endIndex = content.indexOf('---', 3)
+  if (endIndex === -1) return false
+  const frontmatter = content.slice(3, endIndex)
+  return /\bdev:\s*true\b/.test(frontmatter)
+}
+
+// prefer a project's ./skills dir if it exists, else fall back to ./docs. lets
+// consumers cleanly separate agent skills (frontmatter md) from plain docs.
+function resolveLocalDocsDir(cwd: string): string {
+  const skillsDir = join(cwd, 'skills')
+  if (existsSync(skillsDir)) return skillsDir
+  return join(cwd, 'docs')
+}
+
+function collectAllDocs(cwd: string): Array<{ name: string; path: string }> {
+  const docs: Array<{ name: string; path: string }> = []
+
+  const localDocsDir = resolveLocalDocsDir(cwd)
+  if (existsSync(localDocsDir)) {
+    const files = readdirSync(localDocsDir).filter((f) => f.endsWith('.md'))
+    for (const file of files) {
+      const name = file.replace(/\.md$/, '')
+      docs.push({ name, path: join(localDocsDir, file) })
+    }
+  }
+
+  return docs
+}
+
+async function generateDocSkills(
+  cwd: string,
+  clean: boolean
+): Promise<{
+  symlinked: number
+  generated: number
+  unchanged: number
+  removed: number
+  skipped: number
+}> {
+  const skillsDirs = getSkillsDirs(cwd)
+  const docs = collectAllDocs(cwd)
+  const localDocsDir = resolveLocalDocsDir(cwd)
+  const expectedSkillNames = new Set<string>()
+
+  if (docs.length === 0) {
+    console.info(pc.yellow('no documentation files found'))
+  } else {
+    console.info(pc.dim(`found ${docs.length} documentation files`))
+  }
+
+  for (const target of skillsDirs) {
+    const skillsDir = target.path
+    if (clean && existsSync(skillsDir)) {
+      const existing = readdirSync(skillsDir)
+      for (const dir of existing) {
+        if (
+          dir.startsWith(SKILL_PREFIX) &&
+          !lstatSync(join(skillsDir, dir)).isSymbolicLink()
+        ) {
+          rmSync(join(skillsDir, dir), { recursive: true })
+        }
+      }
+    }
+
+    if (!existsSync(skillsDir)) {
+      mkdirSync(skillsDir, { recursive: true })
+    }
+  }
+
+  let symlinked = 0
+  let generated = 0
+  let unchanged = 0
+  let removed = 0
+  let skipped = 0
+  const isDev = !!process.env.IS_TAMAGUI_DEV
+
+  for (const doc of docs) {
+    const content = readFileSync(doc.path, 'utf-8')
+    if (isDevOnly(content) && !isDev) continue
+
+    const hasFrontmatter = hasSkillFrontmatter(content)
+
+    if (hasFrontmatter) {
+      const nameMatch = content.match(/^---\s*\nname:\s*([^\n]+)/m)
+      if (!nameMatch) continue
+
+      const skillName = nameMatch[1]!.trim()
+      expectedSkillNames.add(skillName)
+
+      for (const target of skillsDirs) {
+        const skillsDir = target.path
+        const skillDir = join(skillsDir, skillName)
+        const skillFile = join(skillDir, 'SKILL.md')
+
+        // linked directories belong to another source, including dangling links.
+        if (lstatSync(skillDir, { throwIfNoEntry: false })?.isSymbolicLink()) {
+          skipped++
+          continue
+        }
+
+        if (!existsSync(skillDir)) {
+          mkdirSync(skillDir, { recursive: true })
+        }
+
+        const relativePath = relative(skillDir, doc.path)
+        const targetContent = transformSkillForHarness(content, target.harness)
+        const isSymlinkTarget = targetContent === content
+
+        let shouldCreate = true
+        try {
+          const stat = lstatSync(skillFile)
+          if (isSymlinkTarget && stat.isSymbolicLink() && existsSync(skillFile)) {
+            const existingContent = readFileSync(skillFile, 'utf-8')
+            if (existingContent === content) {
+              unchanged++
+              shouldCreate = false
+            }
+          } else if (
+            !isSymlinkTarget &&
+            !stat.isSymbolicLink() &&
+            existsSync(skillFile)
+          ) {
+            const existingContent = readFileSync(skillFile, 'utf-8')
+            if (existingContent === targetContent) {
+              unchanged++
+              shouldCreate = false
+            }
+          }
+          if (shouldCreate) {
+            unlinkSync(skillFile)
+          }
+        } catch {
+          // nothing exists
+        }
+
+        if (!shouldCreate) continue
+
+        if (isSymlinkTarget) {
+          symlinkSync(relativePath, skillFile)
+          symlinked++
+
+          console.info(
+            `  ${pc.green('⟷')} ${skillName} ${pc.dim(`(${relative(cwd, skillsDir)})`)}`
+          )
+        } else {
+          writeFileSync(skillFile, targetContent, 'utf-8')
+          generated++
+
+          console.info(
+            `  ${pc.cyan('✎')} ${skillName} ${pc.dim(`(${relative(cwd, skillsDir)}: model mapped)`)}`
+          )
+        }
+      }
+    } else {
+      if (!hasFrontmatter) {
+        skipped++
+        console.info(
+          `  ${pc.yellow('!')} skipped ${pc.dim(doc.name)} ${pc.dim('(missing skill frontmatter)')}`
+        )
+        continue
+      }
+    }
+  }
+
+  for (const target of skillsDirs) {
+    const skillsDir = target.path
+    for (const dir of readdirSync(skillsDir)) {
+      if (expectedSkillNames.has(dir)) continue
+
+      const skillDir = join(skillsDir, dir)
+      const skillFile = join(skillDir, 'SKILL.md')
+
+      if (lstatSync(skillDir).isSymbolicLink()) continue
+
+      if (dir.startsWith(SKILL_PREFIX)) {
+        rmSync(skillDir, { recursive: true, force: true })
+        removed++
+        console.info(
+          `  ${pc.red('✕')} ${dir} ${pc.dim('(removed stale generated skill)')}`
+        )
+        continue
+      }
+
+      let shouldUnlink = false
+
+      try {
+        const stat = lstatSync(skillFile)
+        if (stat.isSymbolicLink()) {
+          const linkTarget = readlinkSync(skillFile)
+          const resolvedTarget = resolve(skillDir, linkTarget)
+          shouldUnlink = resolvedTarget.startsWith(`${localDocsDir}/`)
+        } else if (stat.isFile()) {
+          shouldUnlink = true
+        }
+      } catch {
+        // ignore unrelated skill directories
+      }
+
+      if (!shouldUnlink) continue
+
+      unlinkSync(skillFile)
+      if (readdirSync(skillDir).length === 0) {
+        rmdirSync(skillDir)
+      }
+      removed++
+      console.info(`  ${pc.red('✕')} ${dir} ${pc.dim('(removed stale skill)')}`)
+    }
+  }
+
+  return { symlinked, generated, unchanged, removed, skipped }
+}
+
+// --- commands ---
+
+const generateCommand = defineCommand({
+  meta: {
+    name: 'generate',
+    description: 'Generate Claude Code and Codex skills from documentation',
+  },
+  args: {
+    clean: {
+      type: 'boolean',
+      description: 'Remove existing takeout-* skills before generating',
+      default: false,
+    },
+    'skip-internal-docs': {
+      type: 'boolean',
+      description: 'Skip generating skills from internal documentation files',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = process.cwd()
+    const skillsDirs = getSkillsDirs(cwd)
+
+    console.info()
+    console.info(pc.bold(pc.cyan('Generate all skills')))
+    console.info()
+
+    let symlinked = 0
+    let generated = 0
+    let unchanged = 0
+    let removed = 0
+    let skipped = 0
+
+    // 1. doc skills (unless skipped)
+    if (!args['skip-internal-docs']) {
+      const docStats = await generateDocSkills(cwd, args.clean)
+      symlinked = docStats.symlinked
+      generated = docStats.generated
+      unchanged = docStats.unchanged
+      removed = docStats.removed
+      skipped = docStats.skipped
+      console.info()
+    }
+
+    // summary
+    console.info()
+    console.info(pc.bold('summary:'))
+    if (symlinked > 0) console.info(`  ${pc.green(`${symlinked} symlinked`)}`)
+    if (generated > 0)
+      console.info(
+        `  ${pc.cyan(`${generated} generated`)} ${pc.dim('(model tier translated)')}`
+      )
+    if (skipped > 0)
+      console.info(
+        `  ${pc.yellow(`${skipped} skipped`)} ${pc.dim('(linked directories or missing skill frontmatter)')}`
+      )
+    if (unchanged > 0) console.info(`  ${pc.dim(`${unchanged} unchanged`)}`)
+    if (removed > 0) console.info(`  ${pc.red(`${removed} removed`)}`)
+    for (const target of skillsDirs) {
+      console.info(pc.dim(`  skills in ${target.path}`))
+    }
+    console.info()
+  },
+})
+
+export const skillsCommand = defineCommand({
+  meta: {
+    name: 'skills',
+    description: 'Manage repository agent skills',
+  },
+  subCommands: {
+    generate: generateCommand,
+  },
+})