@owlmeans/agent-skills 0.1.8

package/build/run.js

@@ -0,0 +1,124 @@
+import { resolve } from 'node:path';
+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';
+const ACTION_LABEL = {
+    'install': 'install',
+    'skip-uptodate': 'up-to-date',
+    'update': 'update',
+    'conflict': 'CONFLICT',
+};
+const padEnd = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
+const printTable = (items) => {
+    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 const run = async (args) => {
+    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 };
+};
+//# sourceMappingURL=run.js.map

package/build/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@owlmeans/agent-skills",
+  "version": "0.1.8",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "bin": {
+    "owlmeans-agent-skills": "./build/bin.js"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^24.10.1",
+    "nodemon": "^3.1.11",
+    "typescript": "^6.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/apply.ts

@@ -0,0 +1,38 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { InstallItem } from './plan.js'
+
+export interface ApplyResult {
+  installed: number
+  updated: number
+  skipped: number
+  conflicts: number
+}
+
+/**
+ * Execute an install plan. Items with action 'conflict' or 'skip-uptodate'
+ * are not written. Only 'install' and 'update' items are written.
+ */
+export const applyInstall = (items: InstallItem[]): ApplyResult => {
+  const result: ApplyResult = { installed: 0, updated: 0, skipped: 0, conflicts: 0 }
+
+  for (const item of items) {
+    if (item.action === 'skip-uptodate') {
+      result.skipped++
+      continue
+    }
+    if (item.action === 'conflict') {
+      result.conflicts++
+      continue
+    }
+
+    const content = readFileSync(item.entry.sourcePath, 'utf8')
+    mkdirSync(dirname(item.targetPath), { recursive: true })
+    writeFileSync(item.targetPath, content, 'utf8')
+
+    if (item.action === 'install') result.installed++
+    else result.updated++
+  }
+
+  return result
+}

package/src/args.ts

@@ -0,0 +1,108 @@
+export interface CliArgs {
+  dir: string
+  yes: boolean
+  only: string[]
+  claudeOnly: boolean
+  copilotOnly: boolean
+  extras: boolean
+  force: boolean
+  dryRun: boolean
+  help: boolean
+}
+
+const HELP = `owlmeans-agent-skills — install embedded @owlmeans/* agent guidance
+
+Usage: npx @owlmeans/agent-skills [options]
+
+Options:
+  --dir <path>        target project directory (default: cwd)
+  --yes, -y           skip interactive confirmation
+  --only <pkg,...>    comma-separated @owlmeans/* package names to install from
+  --claude-only       install only Claude Code skills
+  --copilot-only      install only Copilot instructions
+  --extras            include extras bundled with the installer (default: on)
+  --no-extras         skip installer-bundled extras
+  --force             overwrite locally-edited files (no AUTO-GENERATED banner)
+  --dry-run           print plan without writing files
+  --help, -h          show this help
+`
+
+export const parseArgs = (argv: string[]): CliArgs | null => {
+  const args = argv.slice(2) // strip node + script
+  const result: CliArgs = {
+    dir: process.cwd(),
+    yes: false,
+    only: [],
+    claudeOnly: false,
+    copilotOnly: false,
+    extras: true,
+    force: false,
+    dryRun: false,
+    help: false,
+  }
+
+  let i = 0
+  while (i < args.length) {
+    const a = args[i]
+    switch (a) {
+      case '--help':
+      case '-h':
+        result.help = true
+        break
+      case '--yes':
+      case '-y':
+        result.yes = true
+        break
+      case '--force':
+        result.force = true
+        break
+      case '--dry-run':
+        result.dryRun = true
+        break
+      case '--claude-only':
+        result.claudeOnly = true
+        break
+      case '--copilot-only':
+        result.copilotOnly = true
+        break
+      case '--extras':
+        result.extras = true
+        break
+      case '--no-extras':
+        result.extras = false
+        break
+      case '--dir': {
+        const v = args[i + 1]
+        if (v == null || v.startsWith('-')) {
+          process.stderr.write(`error: --dir requires a path argument\n`)
+          return null
+        }
+        result.dir = v
+        i++
+        break
+      }
+      case '--only': {
+        const v = args[i + 1]
+        if (v == null || v.startsWith('-')) {
+          process.stderr.write(`error: --only requires a comma-separated package list\n`)
+          return null
+        }
+        result.only = v.split(',').map(s => s.trim()).filter(Boolean)
+        i++
+        break
+      }
+      default:
+        if (a.startsWith('--')) {
+          process.stderr.write(`error: unknown flag ${a}\n`)
+          return null
+        }
+    }
+    i++
+  }
+
+  return result
+}
+
+export const printHelp = (): void => {
+  process.stdout.write(HELP)
+}

package/src/bin.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { parseArgs, printHelp } from './args.js'
+import { run } from './run.js'
+
+const args = parseArgs(process.argv)
+
+if (args == null) {
+  process.stderr.write('Run with --help for usage.\n')
+  process.exit(2)
+} else if (args.help) {
+  printHelp()
+  process.exit(0)
+} else {
+  run(args).then(result => {
+    process.exit(result.code)
+  }).catch((err: unknown) => {
+    process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`)
+    process.exit(1)
+  })
+}

package/src/discover.ts

@@ -0,0 +1,202 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export interface ManifestEntry {
+  kind: 'skill' | 'instruction'
+  name: string
+  category: 'package-specific' | 'multi-package'
+  file: string
+  canonicalPath: string
+}
+
+export interface Manifest {
+  schemaVersion: number
+  package: string
+  version: string
+  generatedAt: string
+  canonicalRepo: string
+  entries: ManifestEntry[]
+}
+
+export interface DiscoveredEntry {
+  kind: 'skill' | 'instruction'
+  name: string
+  category: 'package-specific' | 'multi-package'
+  /** Absolute path to the embedded source file. */
+  sourcePath: string
+  canonicalPath: string
+  /** Package this came from. */
+  packageName: string
+  version: string
+  /** True for extras bundled in the installer itself. */
+  isExtra: boolean
+}
+
+/** Parse a manifest.json, return null if invalid/unparseable. */
+const parseManifest = (manifestPath: string): Manifest | null => {
+  try {
+    const raw = readFileSync(manifestPath, 'utf8')
+    const m = JSON.parse(raw) as Manifest
+    if (typeof m.schemaVersion !== 'number' || !Array.isArray(m.entries)) return null
+    return m
+  } catch {
+    return null
+  }
+}
+
+// Scan node_modules/@owlmeans/*/agent-meta/ for manifests.
+const scanNodeModules = (targetDir: string): DiscoveredEntry[] => {
+  const nmDir = join(targetDir, 'node_modules', '@owlmeans')
+  if (!existsSync(nmDir)) return []
+
+  const entries: DiscoveredEntry[] = []
+  let pkgDirs: string[]
+  try {
+    pkgDirs = readdirSync(nmDir)
+  } catch {
+    return []
+  }
+
+  for (const pkgDir of pkgDirs) {
+    const manifestPath = join(nmDir, pkgDir, 'agent-meta', 'manifest.json')
+    if (!existsSync(manifestPath)) continue
+    const manifest = parseManifest(manifestPath)
+    if (manifest == null) continue
+
+    const agentMetaDir = join(nmDir, pkgDir, 'agent-meta')
+    for (const e of manifest.entries) {
+      const sourcePath = join(agentMetaDir, e.file)
+      if (!existsSync(sourcePath)) continue
+      entries.push({
+        kind: e.kind,
+        name: e.name,
+        category: e.category,
+        sourcePath,
+        canonicalPath: e.canonicalPath,
+        packageName: manifest.package,
+        version: manifest.version,
+        isExtra: false,
+      })
+    }
+  }
+
+  return entries
+}
+
+/** Resolve the installer package's own agent-meta dir (for bundled extras). */
+const selfAgentMetaDir = (): string | null => {
+  try {
+    const selfDir = dirname(fileURLToPath(import.meta.url))
+    // src/ → .. → package root → agent-meta
+    const candidate = join(selfDir, '..', 'agent-meta')
+    return existsSync(candidate) ? candidate : null
+  } catch {
+    return null
+  }
+}
+
+/** Scan the installer's own agent-meta/ for bundled extras. */
+const scanSelfExtras = (packageName: string, version: string): DiscoveredEntry[] => {
+  const agentMetaDir = selfAgentMetaDir()
+  if (agentMetaDir == null) return []
+
+  const manifestPath = join(agentMetaDir, 'manifest.json')
+  const manifest = parseManifest(manifestPath)
+  if (manifest == null) return []
+
+  const entries: DiscoveredEntry[] = []
+  for (const e of manifest.entries) {
+    const sourcePath = join(agentMetaDir, e.file)
+    if (!existsSync(sourcePath)) continue
+    entries.push({
+      kind: e.kind,
+      name: e.name,
+      category: e.category,
+      sourcePath,
+      canonicalPath: e.canonicalPath,
+      packageName,
+      version,
+      isExtra: true,
+    })
+  }
+  return entries
+}
+
+export interface DiscoverOptions {
+  /** Include installer's bundled extras. Default: true */
+  extras?: boolean
+  /** Restrict to entries from these package names. */
+  only?: string[]
+  /** Install only skills. */
+  claudeOnly?: boolean
+  /** Install only instructions. */
+  copilotOnly?: boolean
+}
+
+/** Collect all DiscoveredEntries, deduplicated by (kind, name). */
+export const discover = (targetDir: string, opts: DiscoverOptions = {}): DiscoveredEntry[] => {
+  const { extras = true, only, claudeOnly = false, copilotOnly = false } = opts
+
+  const allEntries = scanNodeModules(targetDir)
+
+  if (extras) {
+    // Get installer's own package name+version from its package.json
+    let selfName = '@owlmeans/agent-skills'
+    let selfVersion = '0.0.0'
+    try {
+      const selfPkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
+      if (existsSync(selfPkgPath)) {
+        const pkg = JSON.parse(readFileSync(selfPkgPath, 'utf8'))
+        if (pkg.name) selfName = pkg.name
+        if (pkg.version) selfVersion = pkg.version
+      }
+    } catch { /* use defaults */ }
+    allEntries.push(...scanSelfExtras(selfName, selfVersion))
+  }
+
+  // Deduplicate by (kind, name): prefer highest semver version
+  const byKey = new Map<string, DiscoveredEntry>()
+  for (const e of allEntries) {
+    const key = `${e.kind}:${e.name}`
+    const existing = byKey.get(key)
+    if (existing == null) {
+      byKey.set(key, e)
+    } else if (compareSemver(e.version, existing.version) > 0) {
+      byKey.set(key, e)
+    }
+  }
+
+  let result = Array.from(byKey.values())
+
+  // Apply --only filter
+  if (only != null && only.length > 0) {
+    result = result.filter(e => only.some(n => matchPkgName(n, e.packageName)))
+  }
+
+  // Apply tool filters
+  if (claudeOnly) result = result.filter(e => e.kind === 'skill')
+  if (copilotOnly) result = result.filter(e => e.kind === 'instruction')
+
+  return result
+}
+
+/** Compare two semver strings. Returns >0 if a > b, <0 if a < b, 0 if equal. */
+const compareSemver = (a: string, b: string): number => {
+  const parse = (s: string): number[] =>
+    s.replace(/^[^0-9]*/, '').split('.').map(n => parseInt(n, 10) || 0)
+  const pa = parse(a)
+  const pb = parse(b)
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+/** Match package name allowing bare name without scope (@owlmeans/ prefix optional). */
+const matchPkgName = (filter: string, pkgName: string): boolean => {
+  if (filter === pkgName) return true
+  if (!filter.startsWith('@') && pkgName === `@owlmeans/${filter}`) return true
+  return false
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { discover } from './discover.js'
+export type { DiscoveredEntry, Manifest, ManifestEntry, DiscoverOptions } from './discover.js'
+
+export { detectLinked } from './linked.js'
+export type { LinkedResult } from './linked.js'
+
+export { planInstall, AUTO_GENERATED_BANNER } from './plan.js'
+export type { InstallAction, InstallItem, PlanOptions } from './plan.js'
+
+export { applyInstall } from './apply.js'
+export type { ApplyResult } from './apply.js'
+
+export { run } from './run.js'
+export type { RunResult } from './run.js'

package/src/linked.ts

@@ -0,0 +1,51 @@
+import { existsSync, readdirSync, lstatSync, realpathSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+export interface LinkedResult {
+  linked: boolean
+  /** Symlinked package names found in node_modules. */
+  evidence: string[]
+}
+
+/**
+ * Detect whether @owlmeans/* packages in node_modules are symlinked
+ * (i.e. this project has them via a workspace/libraries/ dev link, not
+ * from the npm registry). Returns { linked: true } if any are found.
+ *
+ * A package is considered linked when its node_modules/@owlmeans/<pkg>
+ * entry is a symlink whose real path escapes the node_modules tree.
+ */
+export const detectLinked = (targetDir: string): LinkedResult => {
+  const nmScope = join(targetDir, 'node_modules', '@owlmeans')
+  if (!existsSync(nmScope)) return { linked: false, evidence: [] }
+
+  let pkgNames: string[]
+  try {
+    pkgNames = readdirSync(nmScope)
+  } catch {
+    return { linked: false, evidence: [] }
+  }
+
+  const evidence: string[] = []
+  const nmDir = resolve(join(targetDir, 'node_modules'))
+
+  for (const pkg of pkgNames) {
+    const pkgPath = join(nmScope, pkg)
+    try {
+      const stat = lstatSync(pkgPath)
+      if (stat.isSymbolicLink()) {
+        evidence.push(`@owlmeans/${pkg}`)
+        continue
+      }
+      // Also check if realpath escapes node_modules (e.g. hoisted symlink)
+      const real = realpathSync(pkgPath)
+      if (!real.startsWith(nmDir + '/') && !real.startsWith(nmDir + '\\')) {
+        evidence.push(`@owlmeans/${pkg}`)
+      }
+    } catch {
+      // Ignore stat errors
+    }
+  }
+
+  return { linked: evidence.length > 0, evidence }
+}

package/src/plan.ts

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { DiscoveredEntry } from './discover.js'
+
+export type InstallAction =
+  | 'install'       // target missing → write
+  | 'skip-uptodate' // bytes identical → no-op
+  | 'update'        // managed (banner present) and differs → overwrite
+  | 'conflict'      // local edit (no banner) and differs → skip or prompt
+
+export interface InstallItem {
+  entry: DiscoveredEntry
+  targetPath: string
+  action: InstallAction
+}
+
+/** The banner text injected by sync-agent-meta into every generated file. */
+export const AUTO_GENERATED_BANNER = '<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->'
+
+const targetPath = (targetDir: string, entry: DiscoveredEntry): string => {
+  if (entry.kind === 'skill') {
+    return join(targetDir, '.claude', 'skills', entry.name, 'SKILL.md')
+  }
+  return join(targetDir, '.github', 'instructions', `${entry.name}.instructions.md`)
+}
+
+export interface PlanOptions {
+  /** Treat conflicts as 'overwrite' (--force). */
+  force?: boolean
+}
+
+export const planInstall = (
+  entries: DiscoveredEntry[],
+  targetDir: string,
+  opts: PlanOptions = {},
+): InstallItem[] => {
+  return entries.map(entry => {
+    const path = targetPath(targetDir, entry)
+
+    if (!existsSync(path)) {
+      return { entry, targetPath: path, action: 'install' }
+    }
+
+    let existing: string
+    try {
+      existing = readFileSync(path, 'utf8')
+    } catch {
+      return { entry, targetPath: path, action: 'install' }
+    }
+
+    const source = readFileSync(entry.sourcePath, 'utf8')
+
+    if (existing === source) {
+      return { entry, targetPath: path, action: 'skip-uptodate' }
+    }
+
+    const isManaged = existing.includes(AUTO_GENERATED_BANNER)
+    if (isManaged) {
+      return { entry, targetPath: path, action: 'update' }
+    }
+
+    // Local edit: skip by default, overwrite if --force
+    return {
+      entry,
+      targetPath: path,
+      action: opts.force ? 'update' : 'conflict',
+    }
+  })
+}