@orderful/droid 0.2.0 → 0.4.0

package/src/lib/agents.ts

@@ -0,0 +1,186 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+import YAML from 'yaml';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_AGENTS_DIR = join(__dirname, '../agents');
+const INSTALLED_AGENTS_DIR = join(homedir(), '.claude', 'agents');
+
+/**
+ * Agent manifest structure
+ */
+export interface AgentManifest {
+  name: string;
+  description: string;
+  version: string;
+  status?: 'alpha' | 'beta' | 'stable';
+  mode?: 'primary' | 'subagent' | 'all'; // How the agent is used
+  tools?: string[]; // Allowed tools for this agent
+  triggers?: string[];
+  persona?: string;
+}
+
+/**
+ * Get the path to bundled agents directory
+ */
+export function getBundledAgentsDir(): string {
+  return BUNDLED_AGENTS_DIR;
+}
+
+/**
+ * Load an agent manifest from an agent directory
+ */
+export function loadAgentManifest(agentDir: string): AgentManifest | null {
+  const manifestPath = join(agentDir, 'AGENT.yaml');
+
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(manifestPath, 'utf-8');
+    return YAML.parse(content) as AgentManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get all bundled agents
+ */
+export function getBundledAgents(): AgentManifest[] {
+  if (!existsSync(BUNDLED_AGENTS_DIR)) {
+    return [];
+  }
+
+  const agentDirs = readdirSync(BUNDLED_AGENTS_DIR, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => dirent.name);
+
+  const agents: AgentManifest[] = [];
+
+  for (const agentDir of agentDirs) {
+    const manifest = loadAgentManifest(join(BUNDLED_AGENTS_DIR, agentDir));
+    if (manifest) {
+      agents.push(manifest);
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Get agent status display string
+ */
+export function getAgentStatusDisplay(status?: string): string {
+  switch (status) {
+    case 'alpha':
+      return '[alpha]';
+    case 'beta':
+      return '[beta]';
+    case 'stable':
+    default:
+      return '';
+  }
+}
+
+/**
+ * Get installed agents directory
+ */
+export function getInstalledAgentsDir(): string {
+  return INSTALLED_AGENTS_DIR;
+}
+
+/**
+ * Check if an agent is installed
+ */
+export function isAgentInstalled(agentName: string): boolean {
+  const agentPath = join(INSTALLED_AGENTS_DIR, `${agentName}.md`);
+  return existsSync(agentPath);
+}
+
+/**
+ * Install an agent to ~/.claude/agents/
+ * Combines AGENT.yaml metadata with AGENT.md content into a single .md file
+ */
+export function installAgent(agentName: string): { success: boolean; message: string } {
+  const agentDir = join(BUNDLED_AGENTS_DIR, agentName);
+  const manifestPath = join(agentDir, 'AGENT.yaml');
+  const contentPath = join(agentDir, 'AGENT.md');
+
+  if (!existsSync(manifestPath)) {
+    return { success: false, message: `Agent manifest not found: ${agentName}` };
+  }
+
+  try {
+    // Load manifest
+    const manifest = YAML.parse(readFileSync(manifestPath, 'utf-8')) as AgentManifest;
+
+    // Load content (AGENT.md)
+    let agentContent = '';
+    if (existsSync(contentPath)) {
+      const rawContent = readFileSync(contentPath, 'utf-8');
+      // Strip frontmatter from AGENT.md if present (we'll use AGENT.yaml for metadata)
+      const frontmatterMatch = rawContent.match(/^---\n[\s\S]*?\n---\n?/);
+      agentContent = frontmatterMatch ? rawContent.slice(frontmatterMatch[0].length) : rawContent;
+    }
+
+    // If no AGENT.md content, use persona from AGENT.yaml
+    if (!agentContent.trim() && manifest.persona) {
+      agentContent = manifest.persona;
+    }
+
+    // Build frontmatter for Claude Code agent format
+    const frontmatter: Record<string, unknown> = {
+      name: manifest.name,
+      description: manifest.description,
+    };
+
+    // Add tools if specified
+    if (manifest.tools && manifest.tools.length > 0) {
+      frontmatter.tools = manifest.tools.join(', ');
+    }
+
+    // Generate the installed agent file
+    const installedContent = `---
+name: ${frontmatter.name}
+description: ${frontmatter.description}${frontmatter.tools ? `\ntools: ${frontmatter.tools}` : ''}
+---
+
+${agentContent.trim()}
+`;
+
+    // Ensure agents directory exists
+    if (!existsSync(INSTALLED_AGENTS_DIR)) {
+      mkdirSync(INSTALLED_AGENTS_DIR, { recursive: true });
+    }
+
+    // Write the agent file
+    const outputPath = join(INSTALLED_AGENTS_DIR, `${agentName}.md`);
+    writeFileSync(outputPath, installedContent);
+
+    return { success: true, message: `Installed ${agentName} to ~/.claude/agents/` };
+  } catch (error) {
+    return { success: false, message: `Failed to install agent: ${error}` };
+  }
+}
+
+/**
+ * Uninstall an agent from ~/.claude/agents/
+ */
+export function uninstallAgent(agentName: string): { success: boolean; message: string } {
+  const agentPath = join(INSTALLED_AGENTS_DIR, `${agentName}.md`);
+
+  if (!existsSync(agentPath)) {
+    return { success: false, message: `Agent not installed: ${agentName}` };
+  }
+
+  try {
+    unlinkSync(agentPath);
+    return { success: true, message: `Uninstalled ${agentName}` };
+  } catch (error) {
+    return { success: false, message: `Failed to uninstall agent: ${error}` };
+  }
+}

package/src/lib/skills.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
-import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { homedir } from 'os';
@@ -13,6 +13,19 @@ import {
   getBundledSkillsDir,
 } from './skills.js';
 
+/**
+ * Parse YAML frontmatter from markdown content
+ */
+function parseFrontmatter(content: string): Record<string, unknown> | null {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  try {
+    return YAML.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+
 describe('getSkillsInstallPath', () => {
   it('should return Claude Code path', () => {
     const path = getSkillsInstallPath(AITool.ClaudeCode);
@@ -136,3 +149,64 @@ describe('skill manifest parsing', () => {
     expect(parsed.provides_output).toBeUndefined();
   });
 });
+
+describe('bundled skills validation', () => {
+  it('all skills should have SKILL.md with valid frontmatter', () => {
+    const skillsDir = getBundledSkillsDir();
+    const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    for (const skillName of skillDirs) {
+      const skillMdPath = join(skillsDir, skillName, 'SKILL.md');
+      expect(existsSync(skillMdPath)).toBe(true);
+
+      const content = readFileSync(skillMdPath, 'utf-8');
+      const frontmatter = parseFrontmatter(content);
+
+      expect(frontmatter).not.toBeNull();
+      expect(frontmatter?.name).toBe(skillName);
+      expect(typeof frontmatter?.description).toBe('string');
+    }
+  });
+
+  it('all skills should have SKILL.yaml manifest', () => {
+    const skillsDir = getBundledSkillsDir();
+    const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    for (const skillName of skillDirs) {
+      const yamlPath = join(skillsDir, skillName, 'SKILL.yaml');
+      expect(existsSync(yamlPath)).toBe(true);
+
+      const content = readFileSync(yamlPath, 'utf-8');
+      const manifest = YAML.parse(content);
+
+      expect(manifest.name).toBe(skillName);
+      expect(typeof manifest.description).toBe('string');
+      expect(typeof manifest.version).toBe('string');
+    }
+  });
+
+  it('SKILL.md frontmatter should match SKILL.yaml', () => {
+    const skillsDir = getBundledSkillsDir();
+    const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    for (const skillName of skillDirs) {
+      const mdPath = join(skillsDir, skillName, 'SKILL.md');
+      const yamlPath = join(skillsDir, skillName, 'SKILL.yaml');
+
+      const mdContent = readFileSync(mdPath, 'utf-8');
+      const yamlContent = readFileSync(yamlPath, 'utf-8');
+
+      const frontmatter = parseFrontmatter(mdContent);
+      const manifest = YAML.parse(yamlContent);
+
+      expect(frontmatter?.name).toBe(manifest.name);
+      expect(frontmatter?.description).toBe(manifest.description);
+    }
+  });
+});

package/src/lib/skills.ts

@@ -283,3 +283,128 @@ export function getSkillStatusDisplay(status?: SkillStatus): string {
       return '';
   }
 }
+
+/**
+ * Check if a command is installed
+ * @param commandName - The display name (e.g., "comments check")
+ * @param skillName - The skill the command belongs to
+ */
+export function isCommandInstalled(commandName: string, skillName: string): boolean {
+  // If the parent skill is installed, the command is installed with it
+  if (isSkillInstalled(skillName)) {
+    return true;
+  }
+
+  // Otherwise check if command was installed standalone
+  const config = loadConfig();
+  const commandsPath = getCommandsInstallPath(config.ai_tool);
+
+  // Command filename is derived from the command name after the skill prefix
+  // e.g., "comments check" from skill "comments" → "check.md"
+  const cmdPart = commandName.startsWith(skillName + ' ')
+    ? commandName.slice(skillName.length + 1)
+    : commandName;
+  const filename = cmdPart.replace(/\s+/g, '-') + '.md';
+
+  return existsSync(join(commandsPath, filename));
+}
+
+/**
+ * Install a single command (without installing the full skill)
+ */
+export function installCommand(
+  commandName: string,
+  skillName: string
+): { success: boolean; message: string } {
+  const config = loadConfig();
+
+  // Find the source command file
+  const cmdPart = commandName.startsWith(skillName + ' ')
+    ? commandName.slice(skillName.length + 1)
+    : commandName;
+  const filename = cmdPart.replace(/\s+/g, '-') + '.md';
+  const sourcePath = join(BUNDLED_SKILLS_DIR, skillName, 'commands', filename);
+
+  if (!existsSync(sourcePath)) {
+    // Try without hyphen conversion (original filename)
+    const altFilename = cmdPart + '.md';
+    const altSourcePath = join(BUNDLED_SKILLS_DIR, skillName, 'commands', altFilename);
+    if (!existsSync(altSourcePath)) {
+      return { success: false, message: `Command file not found: ${filename}` };
+    }
+  }
+
+  // Ensure commands directory exists
+  const commandsPath = getCommandsInstallPath(config.ai_tool);
+  if (!existsSync(commandsPath)) {
+    mkdirSync(commandsPath, { recursive: true });
+  }
+
+  // Find the actual source file
+  const commandsDir = join(BUNDLED_SKILLS_DIR, skillName, 'commands');
+  const files = readdirSync(commandsDir);
+  const sourceFile = files.find(f => {
+    const base = f.replace('.md', '');
+    return base === cmdPart || base === cmdPart.replace(/\s+/g, '-');
+  });
+
+  if (!sourceFile) {
+    return { success: false, message: `Command file not found for: ${commandName}` };
+  }
+
+  const actualSourcePath = join(commandsDir, sourceFile);
+  const targetPath = join(commandsPath, sourceFile);
+
+  try {
+    const content = readFileSync(actualSourcePath, 'utf-8');
+    writeFileSync(targetPath, content);
+    return { success: true, message: `Installed /${commandName}` };
+  } catch (error) {
+    return { success: false, message: `Failed to install command: ${error}` };
+  }
+}
+
+/**
+ * Uninstall a single command
+ */
+export function uninstallCommand(
+  commandName: string,
+  skillName: string
+): { success: boolean; message: string } {
+  const config = loadConfig();
+
+  // If the parent skill is installed, block command uninstall
+  if (isSkillInstalled(skillName)) {
+    return {
+      success: false,
+      message: `Command belongs to installed skill '${skillName}'. Uninstall the skill to remove this command.`,
+    };
+  }
+
+  const commandsPath = getCommandsInstallPath(config.ai_tool);
+
+  // Find the installed command file
+  const cmdPart = commandName.startsWith(skillName + ' ')
+    ? commandName.slice(skillName.length + 1)
+    : commandName;
+
+  // Check possible filenames
+  const possibleFilenames = [
+    cmdPart + '.md',
+    cmdPart.replace(/\s+/g, '-') + '.md',
+  ];
+
+  for (const filename of possibleFilenames) {
+    const commandPath = join(commandsPath, filename);
+    if (existsSync(commandPath)) {
+      try {
+        rmSync(commandPath);
+        return { success: true, message: `Uninstalled /${commandName}` };
+      } catch (error) {
+        return { success: false, message: `Failed to uninstall command: ${error}` };
+      }
+    }
+  }
+
+  return { success: false, message: `Command not installed: ${commandName}` };
+}

package/src/lib/types.ts

@@ -45,6 +45,11 @@ export interface InstalledSkill {
   installed_at: string;
 }
 
+export interface SkillExample {
+  title: string;
+  code: string;
+}
+
 export interface SkillManifest {
   name: string;
   description: string;
@@ -54,6 +59,8 @@ export interface SkillManifest {
   config_schema?: Record<string, ConfigOption>;
   // Skills can declare they provide an output target
   provides_output?: boolean;
+  // Usage examples to show in the TUI
+  examples?: SkillExample[];
 }
 
 export interface ConfigOption {

package/src/lib/version.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'bun:test';
-import { getVersion } from './version.js';
+import { getVersion, compareSemver } from './version.js';
 
 describe('getVersion', () => {
   it('should return a version string', () => {
@@ -21,3 +21,22 @@ describe('getVersion', () => {
     expect(version).not.toBe('0.0.0');
   });
 });
+
+describe('compareSemver', () => {
+  it('should return 1 when first version is greater', () => {
+    expect(compareSemver('1.0.0', '0.9.9')).toBe(1);
+    expect(compareSemver('0.2.1', '0.2.0')).toBe(1);
+    expect(compareSemver('2.0.0', '1.9.9')).toBe(1);
+  });
+
+  it('should return -1 when first version is lesser', () => {
+    expect(compareSemver('0.9.9', '1.0.0')).toBe(-1);
+    expect(compareSemver('0.2.0', '0.2.1')).toBe(-1);
+    expect(compareSemver('1.9.9', '2.0.0')).toBe(-1);
+  });
+
+  it('should return 0 when versions are equal', () => {
+    expect(compareSemver('1.0.0', '1.0.0')).toBe(0);
+    expect(compareSemver('0.2.1', '0.2.1')).toBe(0);
+  });
+});

package/src/lib/version.ts

@@ -19,6 +19,23 @@ export function getVersion(): string {
   }
 }
 
+/**
+ * Compare two semver versions
+ * Returns: 1 if a > b, -1 if a < b, 0 if equal
+ */
+export function compareSemver(a: string, b: string): number {
+  const partsA = a.split('.').map(Number);
+  const partsB = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const numA = partsA[i] || 0;
+    const numB = partsB[i] || 0;
+    if (numA > numB) return 1;
+    if (numA < numB) return -1;
+  }
+  return 0;
+}
+
 /**
  * Check for updates (non-blocking)
  * Shows a message if a new version is available
@@ -33,7 +50,8 @@ export async function checkForUpdates(): Promise<void> {
       timeout: 3000,
     }).trim();
 
-    if (latestVersion && latestVersion !== currentVersion) {
+    // Only show update message if latest is actually newer
+    if (latestVersion && compareSemver(latestVersion, currentVersion) > 0) {
       console.log(
         chalk.yellow(
           `\n⚠️  A new version of droid is available (${currentVersion} → ${latestVersion})`

package/src/skills/README.md

@@ -0,0 +1,85 @@
+# Contributing Skills
+
+Skills are reusable AI capabilities that can be installed into Claude Code or OpenCode.
+
+## Directory Structure
+
+Each skill is a directory containing:
+
+```
+skills/
+└── my-skill/
+    ├── SKILL.yaml      # Required: Manifest with metadata
+    ├── SKILL.md        # Required: Instructions for the AI
+    └── commands/       # Optional: Slash commands
+        └── my-command.md
+```
+
+## SKILL.yaml (Manifest)
+
+```yaml
+name: my-skill                          # Must match directory name
+description: Short description          # Shown in TUI and listings
+version: 1.0.0                          # Semver
+status: beta                            # alpha | beta | stable (optional)
+dependencies: []                        # Other skills required (optional)
+provides_output: false                  # Can this skill be an output target?
+
+# Configuration schema (optional)
+config_schema:
+  option_name:
+    type: string                        # string | boolean
+    description: What this option does
+    default: "default value"            # Optional default
+
+# Examples shown in TUI (optional)
+examples:
+  - title: "Example name"
+    code: |
+      // Example code block
+```
+
+## SKILL.md (AI Instructions)
+
+The SKILL.md file contains instructions for the AI. It must have YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: Short description (must match SKILL.yaml)
+globs:
+  - "**/*"                              # File patterns this skill applies to
+alwaysApply: false                      # Always include in context?
+---
+
+# My Skill
+
+Instructions for the AI on how to use this skill...
+```
+
+## Commands (Optional)
+
+Commands are slash commands the user can invoke. Each is a markdown file:
+
+```
+commands/
+└── do-thing.md
+```
+
+The command file is just markdown instructions. The filename becomes the command name (`/do-thing`).
+
+## Testing Your Skill
+
+1. Run `npm run build` to compile
+2. Run `droid` to open the TUI
+3. Navigate to Skills tab
+4. Install your skill
+5. Test in Claude Code with `/your-command` or by referencing the skill
+
+## Checklist
+
+- [ ] `SKILL.yaml` has all required fields (name, description, version)
+- [ ] `SKILL.md` has valid YAML frontmatter
+- [ ] Name in frontmatter matches directory name
+- [ ] Description matches between SKILL.yaml and SKILL.md
+- [ ] Tests pass: `bun test src/lib/skills.test.ts`

package/src/skills/comments/SKILL.md

@@ -1,3 +1,11 @@
+---
+name: comments
+description: Inline conversation in any file via @droid/@user markers
+globs:
+  - "**/*"
+alwaysApply: false
+---
+
 # Comments Skill
 
 Enable inline conversation in any file using `> @droid` and `> @{user}` markers.

package/src/skills/comments/SKILL.yaml

@@ -16,3 +16,35 @@ config_schema:
     type: boolean
     description: Keep original comments after addressing (vs removing them)
     default: false
+examples:
+  - title: "Action request"
+    code: |
+      // @droid use PascalCase for enum keys
+      enum Status {
+        PENDING = 'pending'
+      }
+  - title: "Ask a question"
+    code: |
+      > @droid Should we cache this?
+
+      > @fry Yes, add Redis caching here...
+  - title: "TODO with context"
+    code: |
+      // @droid TODO: refactor to async/await
+      // The callback pattern is unwieldy
+      function fetchData(callback) {
+        api.get('/data', callback);
+      }
+  - title: "Code review note"
+    code: |
+      // @droid potential memory leak here
+      // Clear interval on unmount?
+      useEffect(() => {
+        setInterval(poll, 1000);
+      }, []);
+  - title: "Multi-line discussion"
+    code: |
+      > @droid Best approach for pagination?
+      > We have ~10k records.
+
+      > @fry Use cursor-based, limit 50.

package/src/skills/comments/commands/README.md

@@ -0,0 +1,58 @@
+# Contributing Commands
+
+Commands are slash commands that users invoke in Claude Code or OpenCode. They're bundled with skills.
+
+## Location
+
+Commands live in a `commands/` subdirectory within a skill:
+
+```
+skills/
+└── my-skill/
+    ├── SKILL.yaml
+    ├── SKILL.md
+    └── commands/
+        ├── README.md       # This file
+        ├── check.md        # /check command
+        └── cleanup.md      # /cleanup command
+```
+
+## Command File Format
+
+Each command is a simple markdown file. The filename (without `.md`) becomes the command name.
+
+**Example: `commands/check.md`**
+
+```markdown
+Scan the codebase for @droid comments and address each one.
+
+## Behavior
+
+1. Search for `> @droid` markers in files
+2. For each comment found:
+   - If it's an action request → execute and remove
+   - If it's a question → respond with `> @{user_mention}`
+
+## Arguments
+
+- `{path}` - Optional path to scope the search (default: current directory)
+
+## Examples
+
+- `/comments check` - Check all files
+- `/comments check src/` - Check only src directory
+```
+
+## Naming Convention
+
+Commands are namespaced by skill. If your skill is `comments`, your commands become:
+
+- `commands/check.md` → `/comments check`
+- `commands/cleanup.md` → `/comments cleanup`
+
+## Best Practices
+
+1. **Be specific** - Describe exactly what the command does
+2. **Include examples** - Show common usage patterns
+3. **Document arguments** - List any parameters the command accepts
+4. **Explain behavior** - Break down the steps the AI should follow