@owlmeans/agent-skills 0.1.8

package/src/prompt.ts

@@ -0,0 +1,25 @@
+import { createInterface } from 'node:readline/promises'
+import { stdin, stdout } from 'node:process'
+
+let rl: ReturnType<typeof createInterface> | null = null
+
+const getReadline = (): ReturnType<typeof createInterface> => {
+  if (rl == null) {
+    rl = createInterface({ input: stdin, output: stdout })
+  }
+  return rl
+}
+
+export const closeReadline = (): void => {
+  if (rl != null) {
+    rl.close()
+    rl = null
+  }
+}
+
+export const confirm = async (question: string): Promise<boolean> => {
+  const answer = await getReadline().question(`${question} [y/N] `)
+  return answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes'
+}
+
+export const isTTY = (): boolean => process.stdin.isTTY === true

package/src/run.ts

@@ -0,0 +1,167 @@
+import { resolve } from 'node:path'
+import type { CliArgs } from './args.js'
+import { discover } from './discover.js'
+import { detectLinked } from './linked.js'
+import { planInstall } from './plan.js'
+import { applyInstall } from './apply.js'
+import { confirm, closeReadline, isTTY } from './prompt.js'
+import type { InstallAction, InstallItem } from './plan.js'
+
+const ACTION_LABEL: Record<InstallAction, string> = {
+  'install': 'install',
+  'skip-uptodate': 'up-to-date',
+  'update': 'update',
+  'conflict': 'CONFLICT',
+}
+
+const padEnd = (s: string, n: number): string => s + ' '.repeat(Math.max(0, n - s.length))
+
+const printTable = (items: InstallItem[]): void => {
+  const colWidths = {
+    kind: 11,
+    name: Math.max(...items.map(i => i.entry.name.length), 4) + 2,
+    pkg: Math.max(...items.map(i => i.entry.packageName.length), 7) + 2,
+    action: 10,
+  }
+
+  const header =
+    padEnd('kind', colWidths.kind) +
+    padEnd('name', colWidths.name) +
+    padEnd('package', colWidths.pkg) +
+    'action'
+  process.stdout.write(header + '\n')
+  process.stdout.write('-'.repeat(header.length) + '\n')
+
+  for (const item of items) {
+    const kindLabel = item.entry.kind === 'skill' ? 'skill' : 'instruction'
+    const actionLabel = ACTION_LABEL[item.action]
+    process.stdout.write(
+      padEnd(kindLabel, colWidths.kind) +
+      padEnd(item.entry.name, colWidths.name) +
+      padEnd(item.entry.packageName, colWidths.pkg) +
+      actionLabel +
+      '\n',
+    )
+  }
+  process.stdout.write('\n')
+}
+
+export type RunResult =
+  | { code: 0 }
+  | { code: 2; message: string }  // CLI parse
+  | { code: 3; message: string }  // nothing found
+  | { code: 4; message: string }  // linked refusal
+  | { code: 5; message: string }  // unresolved conflicts
+
+export const run = async (args: CliArgs): Promise<RunResult> => {
+  const targetDir = resolve(args.dir)
+
+  // 1. Linked monorepo check
+  if (!args.force) {
+    const linked = detectLinked(targetDir)
+    if (linked.linked) {
+      const pkgList = linked.evidence.slice(0, 5).join(', ')
+      const more = linked.evidence.length > 5 ? ` (+${linked.evidence.length - 5} more)` : ''
+      process.stderr.write(
+        `\nerror: linked monorepo detected — ${pkgList}${more} are symlinked.\n\n` +
+        `In this setup, agents already load guidance from the linked monorepo's\n` +
+        `root .claude/skills/ and .github/instructions/. Installing embedded copies\n` +
+        `would place stale duplicates that conflict with the canonical live files.\n\n` +
+        `Pass --force only if you understand this and want to proceed anyway.\n\n`,
+      )
+      return { code: 4, message: 'linked monorepo' }
+    }
+  }
+
+  // 2. Discover
+  const entries = discover(targetDir, {
+    extras: args.extras,
+    only: args.only.length > 0 ? args.only : undefined,
+    claudeOnly: args.claudeOnly,
+    copilotOnly: args.copilotOnly,
+  })
+
+  if (entries.length === 0) {
+    process.stdout.write(
+      `No embedded @owlmeans/* agent guidance found in node_modules.\n` +
+      `Install @owlmeans/* packages first, then re-run.\n`,
+    )
+    return { code: 3, message: 'nothing found' }
+  }
+
+  // 3. Plan
+  const items = planInstall(entries, targetDir, { force: args.force })
+
+  // 4. Print table
+  process.stdout.write('\n')
+  printTable(items)
+
+  if (args.dryRun) {
+    process.stdout.write('(dry-run — no files written)\n')
+    return { code: 0 }
+  }
+
+  // 5. Count actionable items
+  const toWrite = items.filter(i => i.action === 'install' || i.action === 'update')
+  const conflicts = items.filter(i => i.action === 'conflict')
+
+  if (toWrite.length === 0 && conflicts.length === 0) {
+    process.stdout.write('Everything up to date.\n')
+    closeReadline()
+    return { code: 0 }
+  }
+
+  // 6. Interactive: confirm per conflict, or if not --yes confirm overall
+  const resolvedItems = [...items]
+
+  if (isTTY() && !args.yes && toWrite.length > 0) {
+    const ok = await confirm(`Install ${toWrite.length} file(s) into ${targetDir}?`)
+    if (!ok) {
+      process.stdout.write('Aborted.\n')
+      closeReadline()
+      return { code: 0 }
+    }
+  }
+
+  // Per-conflict prompts in interactive mode
+  if (isTTY() && conflicts.length > 0) {
+    for (const item of resolvedItems) {
+      if (item.action !== 'conflict') continue
+      const ok = await confirm(
+        `  ${item.entry.name} has local edits — overwrite ${item.targetPath}?`,
+      )
+      if (ok) {
+        // Upgrade to update
+        Object.assign(item, { action: 'update' })
+      }
+    }
+  }
+
+  closeReadline()
+
+  const remainingConflicts = resolvedItems.filter(i => i.action === 'conflict')
+  if (remainingConflicts.length > 0) {
+    process.stdout.write(
+      `\nSkipping ${remainingConflicts.length} file(s) with local edits:\n`,
+    )
+    for (const c of remainingConflicts) {
+      process.stdout.write(`  ${c.targetPath}\n`)
+    }
+    process.stdout.write(`Pass --force to overwrite.\n\n`)
+
+    // In non-interactive --yes mode with remaining conflicts, exit 5
+    if (!isTTY() && !args.yes && !args.force) {
+      return { code: 5, message: 'unresolved conflicts' }
+    }
+  }
+
+  // 7. Apply
+  const result = applyInstall(resolvedItems)
+
+  process.stdout.write(
+    `Done: ${result.installed} installed, ${result.updated} updated, ` +
+    `${result.skipped} up-to-date, ${result.conflicts} skipped (conflicts).\n`,
+  )
+
+  return { code: 0 }
+}

package/tests/installer.test.ts

@@ -0,0 +1,297 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+import { discover } from '../src/discover.js'
+import { detectLinked } from '../src/linked.js'
+import { planInstall, AUTO_GENERATED_BANNER } from '../src/plan.js'
+import { applyInstall } from '../src/apply.js'
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+const BANNER = AUTO_GENERATED_BANNER
+
+const makeFixtureManifest = (pkgName: string, version: string, entries: Array<{
+  kind: 'skill' | 'instruction'
+  name: string
+  category?: 'package-specific' | 'multi-package'
+}>) => ({
+  schemaVersion: 1,
+  package: pkgName,
+  version,
+  generatedAt: '2026-06-10T00:00:00Z',
+  canonicalRepo: 'https://github.com/owlmeans/common',
+  entries: entries.map(e => ({
+    kind: e.kind,
+    name: e.name,
+    category: e.category ?? 'package-specific',
+    file: e.kind === 'skill'
+      ? `skills/${e.name}/SKILL.md`
+      : `instructions/${e.name}.instructions.md`,
+    canonicalPath: e.kind === 'skill'
+      ? `.claude/skills/${e.name}/SKILL.md`
+      : `.github/instructions/${e.name}.instructions.md`,
+  })),
+})
+
+const writeFixturePackage = (
+  nmDir: string,
+  pkgName: string,
+  version: string,
+  entries: Array<{ kind: 'skill' | 'instruction'; name: string }>,
+): void => {
+  const pkgDir = join(nmDir, '@owlmeans', pkgName.replace('@owlmeans/', ''))
+  const agentMetaDir = join(pkgDir, 'agent-meta')
+  mkdirSync(join(agentMetaDir, 'skills'), { recursive: true })
+  mkdirSync(join(agentMetaDir, 'instructions'), { recursive: true })
+
+  const manifest = makeFixtureManifest(pkgName, version, entries)
+  writeFileSync(join(agentMetaDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8')
+
+  for (const e of entries) {
+    let content = `${BANNER}\n`
+    if (e.kind === 'skill') {
+      content += `---\nname: ${e.name}\n---\n# ${e.name}\nSkill content.\n`
+      const skillDir = join(agentMetaDir, 'skills', e.name)
+      mkdirSync(skillDir, { recursive: true })
+      writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf8')
+    } else {
+      content += `---\ndescription: "${e.name}"\napplyTo: "**/*.ts"\n---\n# ${e.name}\n`
+      writeFileSync(join(agentMetaDir, 'instructions', `${e.name}.instructions.md`), content, 'utf8')
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test setup
+// ---------------------------------------------------------------------------
+
+let tmpDir: string
+
+beforeEach(() => {
+  tmpDir = join(tmpdir(), `agent-skills-test-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  mkdirSync(tmpDir, { recursive: true })
+})
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+// ---------------------------------------------------------------------------
+// discover()
+// ---------------------------------------------------------------------------
+
+describe('discover()', () => {
+  it('returns empty when no node_modules/@owlmeans exists', () => {
+    const entries = discover(tmpDir, { extras: false })
+    expect(entries).toEqual([])
+  })
+
+  it('discovers entries from node_modules', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+      { kind: 'instruction', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    expect(entries).toHaveLength(2)
+    expect(entries.some(e => e.kind === 'skill' && e.name === 'context')).toBe(true)
+    expect(entries.some(e => e.kind === 'instruction' && e.name === 'context')).toBe(true)
+  })
+
+  it('deduplicates by (kind, name), keeping highest version', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.5', [
+      { kind: 'skill', name: 'context' },
+    ])
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/auth', '0.1.7', [
+      { kind: 'skill', name: 'context' }, // same name, higher version
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    expect(entries).toHaveLength(1)
+    expect(entries[0].version).toBe('0.1.7')
+  })
+
+  it('--only filter restricts by package name', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/auth', '0.1.7', [
+      { kind: 'skill', name: 'auth' },
+    ])
+    const entries = discover(tmpDir, { extras: false, only: ['@owlmeans/context'] })
+    expect(entries).toHaveLength(1)
+    expect(entries[0].name).toBe('context')
+  })
+
+  it('--claude-only filter', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+      { kind: 'instruction', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false, claudeOnly: true })
+    expect(entries.every(e => e.kind === 'skill')).toBe(true)
+  })
+
+  it('--copilot-only filter', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+      { kind: 'instruction', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false, copilotOnly: true })
+    expect(entries.every(e => e.kind === 'instruction')).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// detectLinked()
+// ---------------------------------------------------------------------------
+
+describe('detectLinked()', () => {
+  it('returns linked=false when no node_modules', () => {
+    const result = detectLinked(tmpDir)
+    expect(result.linked).toBe(false)
+    expect(result.evidence).toEqual([])
+  })
+
+  it('returns linked=false for regular (non-symlinked) packages', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [])
+    const result = detectLinked(tmpDir)
+    expect(result.linked).toBe(false)
+  })
+
+  it('detects symlinked packages', () => {
+    const nmScope = join(tmpDir, 'node_modules', '@owlmeans')
+    mkdirSync(nmScope, { recursive: true })
+    // Create real package elsewhere and symlink it
+    const realPkg = join(tmpDir, 'real-pkg')
+    mkdirSync(realPkg)
+    symlinkSync(realPkg, join(nmScope, 'context'))
+
+    const result = detectLinked(tmpDir)
+    expect(result.linked).toBe(true)
+    expect(result.evidence).toContain('@owlmeans/context')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// planInstall()
+// ---------------------------------------------------------------------------
+
+describe('planInstall()', () => {
+  it('marks missing targets as install', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    const items = planInstall(entries, tmpDir)
+    expect(items).toHaveLength(1)
+    expect(items[0].action).toBe('install')
+  })
+
+  it('marks identical files as skip-uptodate', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    // Write same content to target
+    const targetDir = join(tmpDir, '.claude', 'skills', 'context')
+    mkdirSync(targetDir, { recursive: true })
+    const source = readFileSync(entries[0].sourcePath, 'utf8')
+    writeFileSync(join(targetDir, 'SKILL.md'), source, 'utf8')
+
+    const items = planInstall(entries, tmpDir)
+    expect(items[0].action).toBe('skip-uptodate')
+  })
+
+  it('marks managed (banner) changed files as update', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    const targetDir = join(tmpDir, '.claude', 'skills', 'context')
+    mkdirSync(targetDir, { recursive: true })
+    // Write old managed content (has banner, but different)
+    writeFileSync(join(targetDir, 'SKILL.md'), `${BANNER}\n# Old content\n`, 'utf8')
+
+    const items = planInstall(entries, tmpDir)
+    expect(items[0].action).toBe('update')
+  })
+
+  it('marks locally-edited (no banner) files as conflict', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    const targetDir = join(tmpDir, '.claude', 'skills', 'context')
+    mkdirSync(targetDir, { recursive: true })
+    writeFileSync(join(targetDir, 'SKILL.md'), '# My custom skill\n', 'utf8')
+
+    const items = planInstall(entries, tmpDir)
+    expect(items[0].action).toBe('conflict')
+  })
+
+  it('--force upgrades conflict to update', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    const targetDir = join(tmpDir, '.claude', 'skills', 'context')
+    mkdirSync(targetDir, { recursive: true })
+    writeFileSync(join(targetDir, 'SKILL.md'), '# My custom skill\n', 'utf8')
+
+    const items = planInstall(entries, tmpDir, { force: true })
+    expect(items[0].action).toBe('update')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// applyInstall() — idempotency
+// ---------------------------------------------------------------------------
+
+describe('applyInstall()', () => {
+  it('writes install items', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+      { kind: 'instruction', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    const items = planInstall(entries, tmpDir)
+    const result = applyInstall(items)
+    expect(result.installed).toBe(2)
+    expect(existsSync(join(tmpDir, '.claude', 'skills', 'context', 'SKILL.md'))).toBe(true)
+    expect(existsSync(join(tmpDir, '.github', 'instructions', 'context.instructions.md'))).toBe(true)
+  })
+
+  it('is idempotent — second run yields all skip-uptodate', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    // First run
+    applyInstall(planInstall(entries, tmpDir))
+    // Second run
+    const items2 = planInstall(entries, tmpDir)
+    expect(items2[0].action).toBe('skip-uptodate')
+    const result2 = applyInstall(items2)
+    expect(result2.installed).toBe(0)
+    expect(result2.skipped).toBe(1)
+  })
+
+  it('does not write conflict items', () => {
+    writeFixturePackage(join(tmpDir, 'node_modules'), '@owlmeans/context', '0.1.7', [
+      { kind: 'skill', name: 'context' },
+    ])
+    const entries = discover(tmpDir, { extras: false })
+    const targetDir = join(tmpDir, '.claude', 'skills', 'context')
+    mkdirSync(targetDir, { recursive: true })
+    const localContent = '# My custom skill\n'
+    writeFileSync(join(targetDir, 'SKILL.md'), localContent, 'utf8')
+
+    const items = planInstall(entries, tmpDir)
+    applyInstall(items)
+    // File should remain unchanged
+    expect(readFileSync(join(targetDir, 'SKILL.md'), 'utf8')).toBe(localContent)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/",
+    "types": ["node"]
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}