guolei-agents 1.0.2

package/src/core/installer.ts

@@ -0,0 +1,169 @@
+import { join, basename } from 'path';
+import { existsSync, readdirSync, readFileSync, mkdirSync, copyFileSync, symlinkSync, rmSync } from 'fs';
+import { tmpdir, homedir } from 'os';
+import { mkdtempSync, rmSync as rmSyncFs } from 'fs';
+import { parseAgentFile } from './parser.js';
+import { discoverFromDirectory } from './discover.js';
+import { ensureDir, getPlatformPaths, isDirectory, findFiles } from '../utils/filesystem.js';
+import { logger } from '../utils/logger.js';
+import type { AgentPlatform, AgentFile, InstallOptions } from '../types/index.js';
+
+export async function installAgent(options: InstallOptions): Promise<void> {
+  const { source, global, platforms, agentName, copy } = options;
+  
+  logger.info(`Installing agent from: ${source}`);
+
+  const tempDir = await fetchSource(source);
+  
+  try {
+    const agents = await discoverFromDirectory(tempDir);
+    
+    if (agents.length === 0) {
+      throw new Error('No agents found in the source');
+    }
+
+    for (const platform of platforms) {
+      const targetPaths = getPlatformPaths(platform, global);
+      
+      for (const targetPath of targetPaths) {
+        ensureDir(targetPath);
+        
+        for (const agentFile of agents) {
+          const name = agentName || agentFile.agent.name || basename(agentFile.path, '.md');
+          const finalPath = join(targetPath, `${name}.md`);
+          
+          if (existsSync(finalPath) && !options.yes) {
+            logger.warn(`Agent "${name}" already exists at ${finalPath}`);
+            continue;
+          }
+
+          if (copy) {
+            const sourcePath = agentFile.path;
+            if (isDirectory(sourcePath)) {
+              copyDirectory(sourcePath, join(targetPath, name));
+            } else {
+              copyFileSync(sourcePath, finalPath);
+            }
+            logger.success(`Copied agent "${name}" to ${finalPath}`);
+          } else {
+            const sourceDir = tempDir;
+            try {
+              symlinkSync(sourceDir, finalPath, 'dir');
+              logger.success(`Symlinked agent "${name}" to ${finalPath}`);
+            } catch (err) {
+              logger.warn(`Failed to create symlink, copying instead: ${err}`);
+              copyDirectory(sourceDir, join(targetPath, name));
+              logger.success(`Copied agent "${name}" to ${targetPath}`);
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    if (existsSync(tempDir) && tempDir.startsWith(tmpdir())) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+}
+
+async function fetchSource(source: string): Promise<string> {
+  if (source.startsWith('.') || source.startsWith('/') || /^[a-zA-Z]:\\/.test(source)) {
+    return source;
+  }
+
+  const degit = await import('degit');
+  const tempDir = mkdtempSync(join(tmpdir(), 'npx-agents-'));
+  
+  const parts = source.split('/');
+  let owner = parts[0];
+  let repo = parts[1]?.replace(/#.+$/, '') || '';
+  let ref = '';
+  
+  if (source.includes('#')) {
+    const [repoPart, refPart] = source.split('#');
+    repo = repoPart.split('/')[1];
+    ref = refPart;
+  }
+
+  try {
+    const target = ref ? `${owner}/${repo}#${ref}` : `${owner}/${repo}`;
+    await degit.default(target).clone(tempDir);
+    return tempDir;
+  } catch (err) {
+    rmSync(tempDir, { recursive: true, force: true });
+    throw new Error(`Failed to fetch from ${source}: ${err}`);
+  }
+}
+
+function copyDirectory(source: string, target: string): void {
+  ensureDir(target);
+  const files = readdirSync(source);
+  for (const file of files) {
+    const srcPath = join(source, file);
+    const destPath = join(target, file);
+    if (isDirectory(srcPath)) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export function listInstalledAgents(platform: AgentPlatform, global: boolean): AgentFile[] {
+  const agents: AgentFile[] = [];
+  const paths = getPlatformPaths(platform, global);
+  
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    
+    const mdFiles = findFiles(path, /\.md$/);
+    for (const file of mdFiles) {
+      try {
+        const content = readFileSync(file, 'utf-8');
+        const agentFile = parseAgentFile(content, file);
+        agents.push(agentFile);
+      } catch (err) {
+        continue;
+      }
+    }
+  }
+  
+  return agents;
+}
+
+export function removeAgent(name: string, platform: AgentPlatform, global: boolean): boolean {
+  const paths = getPlatformPaths(platform, global);
+  
+  for (const path of paths) {
+    const agentPath = join(path, `${name}.md`);
+    if (existsSync(agentPath)) {
+      rmSync(agentPath, { recursive: true, force: true });
+      logger.success(`Removed agent "${name}" from ${path}`);
+      return true;
+    }
+    
+    if (existsSync(path)) {
+      const entries = readdirSync(path);
+      for (const entry of entries) {
+        const entryPath = join(path, entry);
+        const linkTarget = existsSync(entryPath) ? entryPath : null;
+        if (linkTarget && readlinkCheck(entryPath, name)) {
+          rmSync(entryPath, { recursive: true, force: true });
+          logger.success(`Removed agent "${name}" from ${path}`);
+          return true;
+        }
+      }
+    }
+  }
+  
+  return false;
+}
+
+function readlinkCheck(path: string, name: string): boolean {
+  try {
+    const stat = require('fs').lstatSync(path);
+    return stat.isSymbolicLink() && path.includes(name);
+  } catch {
+    return false;
+  }
+}

package/src/core/parser.ts

@@ -0,0 +1,55 @@
+import matter from 'gray-matter';
+import type { Agent, AgentFile } from '../types/index.js';
+
+export function parseAgentFile(content: string, path: string): AgentFile {
+  const { data, content: body } = matter(content);
+  
+  if (!data.description) {
+    throw new Error(`Agent at ${path} is missing required "description" field in frontmatter`);
+  }
+
+  const agent: Agent = {
+    description: data.description,
+    name: data.name,
+    mode: data.mode,
+    model: data.model,
+    temperature: data.temperature,
+    maxSteps: data.maxSteps,
+    color: data.color,
+    trigger: data.trigger,
+    hidden: data.hidden,
+    tools: data.tools,
+    permission: data.permission,
+    mcp: data.mcp,
+    version: data.version,
+  };
+
+  return {
+    path,
+    agent,
+    content: body.trim(),
+  };
+}
+
+export function parseAgentFromString(content: string, filename: string): AgentFile {
+  const baseName = filename.replace(/\.md$/, '');
+  return parseAgentFile(content, baseName);
+}
+
+export function validateAgent(agent: Agent): string[] {
+  const errors: string[] = [];
+  
+  if (!agent.description) {
+    errors.push('Missing required "description" field');
+  }
+  
+  if (agent.temperature !== undefined && (agent.temperature < 0 || agent.temperature > 1)) {
+    errors.push('Temperature must be between 0 and 1');
+  }
+  
+  if (agent.mode && !['primary', 'subagent', 'all'].includes(agent.mode)) {
+    errors.push('Mode must be "primary", "subagent", or "all"');
+  }
+  
+  return errors;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { addCommand } from './commands/add.js';
+import { listCommand } from './commands/list.js';
+import { removeCommand } from './commands/remove.js';
+import { initCommand } from './commands/init.js';
+import { findCommand } from './commands/find.js';
+import { checkCommand } from './commands/check.js';
+import { updateCommand } from './commands/update.js';
+
+const program = new Command();
+
+program
+  .name('agents')
+  .description('CLI for managing AI coding agents')
+  .version('1.0.0');
+
+program
+  .command('add <source>')
+  .description('Install one or more agents from a GitHub repository or local path')
+  .option('-g, --global', 'Install to global directory', false)
+  .option('-a, --agent <agents...>', 'Target agent platform(s)')
+  .option('--agent-name <name>', 'Name for the installed agent')
+  .option('-y, --yes', 'Skip confirmation', false)
+  .option('--copy', 'Copy instead of symlink', false)
+  .action(addCommand);
+
+program
+  .command('list')
+  .description('List installed agents')
+  .option('-g, --global', 'List only global agents')
+  .option('-a, --agent <agent>', 'Filter by platform')
+  .action(listCommand);
+
+program
+  .command('remove <name>')
+  .description('Remove an installed agent')
+  .option('-g, --global', 'Remove from global directory')
+  .option('-a, --agent <agent>', 'Remove from specific platform')
+  .action(removeCommand);
+
+program
+  .command('init [name]')
+  .description('Create a new agent definition template')
+  .action(initCommand);
+
+program
+  .command('find [query]')
+  .description('Search for available agents')
+  .action(findCommand);
+
+program
+  .command('check')
+  .description('Check for updates to installed agents')
+  .action(checkCommand);
+
+program
+  .command('update')
+  .description('Update all installed agents to the latest version')
+  .action(updateCommand);
+
+program.parse();

package/src/types/index.ts

@@ -0,0 +1,78 @@
+export interface Agent {
+  description: string;
+  name?: string;
+  mode?: 'primary' | 'subagent' | 'all';
+  model?: string;
+  temperature?: number;
+  maxSteps?: number;
+  color?: string;
+  trigger?: string;
+  hidden?: boolean;
+  tools?: {
+    read?: boolean;
+    write?: boolean;
+    edit?: boolean;
+    bash?: boolean | string;
+    glob?: boolean | string;
+    grep?: boolean | string;
+    task?: boolean;
+    skill?: boolean;
+    [key: string]: boolean | string | undefined;
+  };
+  permission?: {
+    bash?: Record<string, 'allow' | 'deny' | 'ask'>;
+    edit?: 'allow' | 'deny' | 'ask';
+    write?: 'allow' | 'deny' | 'ask';
+    skill?: Record<string, 'allow' | 'deny'>;
+    task?: Record<string, 'allow' | 'deny'>;
+    [key: string]: unknown;
+  };
+  mcp?: {
+    servers?: Array<{
+      name: string;
+      command: string;
+      args?: string[];
+    }>;
+  };
+  version?: string;
+  source?: string;
+}
+
+export interface AgentManifest {
+  agents: Agent[];
+  source: string;
+  ref?: string;
+}
+
+export interface AgentFile {
+  path: string;
+  agent: Agent;
+  content: string;
+}
+
+export interface Config {
+  global: boolean;
+  agents: Record<string, string[]>;
+  updates: {
+    check: 'daily' | 'weekly' | 'manual';
+  };
+}
+
+export type AgentPlatform = 
+  | 'opencode' 
+  | 'claude-code' 
+  | 'cursor' 
+  | 'windsurf' 
+  | 'cline' 
+  | 'roo' 
+  | 'codex' 
+  | 'continue';
+
+export interface InstallOptions {
+  source: string;
+  global: boolean;
+  platforms: AgentPlatform[];
+  agentName?: string;
+  copy: boolean;
+  yes: boolean;
+}

package/src/utils/filesystem.ts

@@ -0,0 +1,177 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, symlinkSync, copyFileSync, rmSync, statSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import { homedir } from 'os';
+import type { AgentPlatform } from '../types/index.js';
+
+export function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function readDir(dir: string): string[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return readdirSync(dir);
+}
+
+export function readFile(path: string): string {
+  return readFileSync(path, 'utf-8');
+}
+
+export function writeFile(path: string, content: string): void {
+  ensureDir(dirname(path));
+  writeFileSync(path, content, 'utf-8');
+}
+
+export function isDirectory(path: string): boolean {
+  return existsSync(path) && statSync(path).isDirectory();
+}
+
+export function isFile(path: string): boolean {
+  return existsSync(path) && statSync(path).isFile();
+}
+
+export function getPlatformPaths(platform: AgentPlatform, global: boolean): string[] {
+  const home = homedir();
+  
+  const paths: Record<AgentPlatform, { project: string[]; global: string[] }> = {
+    'opencode': {
+      project: ['.opencode/agents/'],
+      global: [join(home, '.config', 'opencode', 'agents')],
+    },
+    'claude-code': {
+      project: ['.claude/agents/'],
+      global: [join(home, '.claude', 'agents')],
+    },
+    'cursor': {
+      project: ['.cursor/agents/'],
+      global: [join(home, '.cursor', 'agents')],
+    },
+    'windsurf': {
+      project: ['.windsurf/agents/'],
+      global: [join(home, '.codeium', 'windsurf', 'agents')],
+    },
+    'cline': {
+      project: ['.cline/agents/'],
+      global: [join(home, '.cline', 'agents')],
+    },
+    'roo': {
+      project: ['.roo/agents/'],
+      global: [join(home, '.roo', 'agents')],
+    },
+    'codex': {
+      project: ['.codex/agents/'],
+      global: [join(home, '.codex', 'agents')],
+    },
+    'continue': {
+      project: ['.continue/agents/'],
+      global: [join(home, '.continue', 'agents')],
+    },
+  };
+
+  return global ? paths[platform].global : paths[platform].project;
+}
+
+export function getGlobalAgentsDir(): string {
+  return process.env.NPX_AGENTS_DIR || join(homedir(), '.config', 'npx-agents');
+}
+
+export function createSymlink(source: string, target: string): void {
+  ensureDir(dirname(target));
+  symlinkSync(source, target, 'dir');
+}
+
+export function copyDir(source: string, target: string): void {
+  ensureDir(target);
+  const files = readdirSync(source);
+  for (const file of files) {
+    const srcPath = join(source, file);
+    const destPath = join(target, file);
+    if (isDirectory(srcPath)) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export function removePath(path: string): void {
+  if (existsSync(path)) {
+    rmSync(path, { recursive: true, force: true });
+  }
+}
+
+export function findFiles(dir: string, pattern: RegExp): string[] {
+  const results: string[] = [];
+  
+  if (!existsSync(dir)) {
+    return results;
+  }
+  
+  const files = readdirSync(dir);
+  for (const file of files) {
+    const fullPath = join(dir, file);
+    if (isDirectory(fullPath)) {
+      results.push(...findFiles(fullPath, pattern));
+    } else if (pattern.test(file)) {
+      results.push(fullPath);
+    }
+  }
+  
+  return results;
+}
+
+export function detectPlatforms(): AgentPlatform[] {
+  const platforms: AgentPlatform[] = [];
+  const home = homedir();
+  const cwd = process.cwd();
+  
+  const checks: Array<{ platform: AgentPlatform; check: () => boolean }> = [
+    {
+      platform: 'opencode',
+      check: () => existsSync(join(home, '.config', 'opencode')) || existsSync(join(cwd, '.opencode')),
+    },
+    {
+      platform: 'claude-code',
+      check: () => existsSync(join(home, '.claude')) || existsSync(join(cwd, '.claude')),
+    },
+    {
+      platform: 'cursor',
+      check: () => existsSync(join(home, '.cursor')) || existsSync(join(cwd, '.cursor')),
+    },
+    {
+      platform: 'windsurf',
+      check: () => existsSync(join(home, '.codeium', 'windsurf')) || existsSync(join(cwd, '.windsurf')),
+    },
+    {
+      platform: 'cline',
+      check: () => existsSync(join(home, '.cline')) || existsSync(join(cwd, '.cline')),
+    },
+    {
+      platform: 'roo',
+      check: () => existsSync(join(home, '.roo')) || existsSync(join(cwd, '.roo')),
+    },
+    {
+      platform: 'codex',
+      check: () => existsSync(join(home, '.codex')) || existsSync(join(cwd, '.codex')),
+    },
+    {
+      platform: 'continue',
+      check: () => existsSync(join(home, '.continue')) || existsSync(join(cwd, '.continue')),
+    },
+  ];
+
+  for (const check of checks) {
+    if (check.check()) {
+      platforms.push(check.platform);
+    }
+  }
+
+  if (platforms.length === 0) {
+    platforms.push('opencode');
+  }
+
+  return platforms;
+}

package/src/utils/logger.ts

@@ -0,0 +1,13 @@
+import chalk from 'chalk';
+
+export const logger = {
+  info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
+  success: (msg: string) => console.log(chalk.green('✓'), msg),
+  warn: (msg: string) => console.log(chalk.yellow('⚠'), msg),
+  error: (msg: string) => console.error(chalk.red('✗'), msg),
+  debug: (msg: string) => {
+    if (process.env.DEBUG === 'npx-agents') {
+      console.log(chalk.gray('[debug]'), msg);
+    }
+  },
+};

package/templates/default-agent.md

@@ -0,0 +1,35 @@
+---
+description: my-agent - Add your agent description here
+mode: subagent
+model: anthropic/claude-3-5-sonnet-20241022
+temperature: 0.7
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: false
+  glob: true
+  grep: true
+  task: false
+  skill: false
+hidden: false
+---
+
+# my-agent
+
+You are a custom AI agent. Describe your purpose and behavior here.
+
+## When to Use
+
+Describe when this agent should be invoked.
+
+## Workflow
+
+1. First step...
+2. Second step...
+3. Third step...
+
+## Guidelines
+
+- Add your specific guidelines here
+- Be clear and concise

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "templates"]
+}