@orderful/droid 0.2.0

package/src/lib/skills.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { homedir } from 'os';
+import YAML from 'yaml';
+import { AITool, SkillStatus } from './types.js';
+import {
+  getSkillsInstallPath,
+  getCommandsInstallPath,
+  getAIConfigPath,
+  getSkillStatusDisplay,
+  getBundledSkillsDir,
+} from './skills.js';
+
+describe('getSkillsInstallPath', () => {
+  it('should return Claude Code path', () => {
+    const path = getSkillsInstallPath(AITool.ClaudeCode);
+    expect(path).toBe(join(homedir(), '.claude', 'skills'));
+  });
+
+  it('should return OpenCode path', () => {
+    const path = getSkillsInstallPath(AITool.OpenCode);
+    expect(path).toBe(join(homedir(), '.config', 'opencode', 'skills'));
+  });
+});
+
+describe('getCommandsInstallPath', () => {
+  it('should return Claude Code commands path', () => {
+    const path = getCommandsInstallPath(AITool.ClaudeCode);
+    expect(path).toBe(join(homedir(), '.claude', 'commands'));
+  });
+
+  it('should return OpenCode commands path', () => {
+    const path = getCommandsInstallPath(AITool.OpenCode);
+    expect(path).toBe(join(homedir(), '.config', 'opencode', 'command'));
+  });
+});
+
+describe('getAIConfigPath', () => {
+  it('should return Claude Code CLAUDE.md path', () => {
+    const path = getAIConfigPath(AITool.ClaudeCode);
+    expect(path).toBe(join(homedir(), '.claude', 'CLAUDE.md'));
+  });
+
+  it('should return OpenCode AGENTS.md path', () => {
+    const path = getAIConfigPath(AITool.OpenCode);
+    expect(path).toBe(join(homedir(), '.config', 'opencode', 'AGENTS.md'));
+  });
+});
+
+describe('getBundledSkillsDir', () => {
+  it('should return a path ending in skills', () => {
+    const dir = getBundledSkillsDir();
+    expect(dir.endsWith('skills')).toBe(true);
+  });
+
+  it('should return an existing directory', () => {
+    const dir = getBundledSkillsDir();
+    expect(existsSync(dir)).toBe(true);
+  });
+});
+
+describe('getSkillStatusDisplay', () => {
+  it('should return [alpha] for alpha status', () => {
+    expect(getSkillStatusDisplay(SkillStatus.Alpha)).toBe('[alpha]');
+  });
+
+  it('should return [beta] for beta status', () => {
+    expect(getSkillStatusDisplay(SkillStatus.Beta)).toBe('[beta]');
+  });
+
+  it('should return empty string for stable status', () => {
+    expect(getSkillStatusDisplay(SkillStatus.Stable)).toBe('');
+  });
+
+  it('should return empty string for undefined status', () => {
+    expect(getSkillStatusDisplay(undefined)).toBe('');
+  });
+});
+
+describe('skill manifest parsing', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `droid-skill-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true });
+    }
+  });
+
+  it('should parse valid skill manifest', () => {
+    const manifest = {
+      name: 'test-skill',
+      description: 'A test skill',
+      version: '1.0.0',
+      status: 'beta',
+      dependencies: ['comments'],
+      provides_output: true,
+    };
+
+    const manifestPath = join(testDir, 'SKILL.yaml');
+    writeFileSync(manifestPath, YAML.stringify(manifest), 'utf-8');
+
+    const content = require('fs').readFileSync(manifestPath, 'utf-8');
+    const parsed = YAML.parse(content);
+
+    expect(parsed.name).toBe('test-skill');
+    expect(parsed.description).toBe('A test skill');
+    expect(parsed.version).toBe('1.0.0');
+    expect(parsed.status).toBe('beta');
+    expect(parsed.dependencies).toEqual(['comments']);
+    expect(parsed.provides_output).toBe(true);
+  });
+
+  it('should handle manifest without optional fields', () => {
+    const manifest = {
+      name: 'minimal-skill',
+      description: 'Minimal',
+      version: '0.1.0',
+    };
+
+    const manifestPath = join(testDir, 'SKILL.yaml');
+    writeFileSync(manifestPath, YAML.stringify(manifest), 'utf-8');
+
+    const content = require('fs').readFileSync(manifestPath, 'utf-8');
+    const parsed = YAML.parse(content);
+
+    expect(parsed.name).toBe('minimal-skill');
+    expect(parsed.status).toBeUndefined();
+    expect(parsed.dependencies).toBeUndefined();
+    expect(parsed.provides_output).toBeUndefined();
+  });
+});

package/src/lib/skills.ts

@@ -0,0 +1,285 @@
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, cpSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import YAML from 'yaml';
+import { loadConfig, saveConfig } from './config.js';
+import { AITool, SkillStatus, type SkillManifest, type InstalledSkill } from './types.js';
+
+// Marker comments for CLAUDE.md skill registration
+const DROID_SKILLS_START = '<!-- droid-skills-start -->';
+const DROID_SKILLS_END = '<!-- droid-skills-end -->';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_SKILLS_DIR = join(__dirname, '../skills');
+
+/**
+ * Get the path to bundled skills directory
+ */
+export function getBundledSkillsDir(): string {
+  return BUNDLED_SKILLS_DIR;
+}
+
+/**
+ * Get the installation path for skills based on AI tool
+ */
+export function getSkillsInstallPath(aiTool: AITool): string {
+  switch (aiTool) {
+    case AITool.ClaudeCode:
+      return join(homedir(), '.claude', 'skills');
+    case AITool.OpenCode:
+      return join(homedir(), '.config', 'opencode', 'skills');
+  }
+}
+
+/**
+ * Get the commands installation path based on AI tool
+ */
+export function getCommandsInstallPath(aiTool: AITool): string {
+  switch (aiTool) {
+    case AITool.ClaudeCode:
+      return join(homedir(), '.claude', 'commands');
+    case AITool.OpenCode:
+      return join(homedir(), '.config', 'opencode', 'command');
+  }
+}
+
+/**
+ * Get the path to the AI tool's main config markdown file
+ */
+export function getAIConfigPath(aiTool: AITool): string {
+  switch (aiTool) {
+    case AITool.ClaudeCode:
+      return join(homedir(), '.claude', 'CLAUDE.md');
+    case AITool.OpenCode:
+      return join(homedir(), '.config', 'opencode', 'AGENTS.md');
+  }
+}
+
+/**
+ * Update the AI tool's config file with skill registrations
+ */
+export function updateAIConfigSkills(aiTool: AITool, installedSkills: string[]): void {
+  const configPath = getAIConfigPath(aiTool);
+
+  let content = '';
+  if (existsSync(configPath)) {
+    content = readFileSync(configPath, 'utf-8');
+  }
+
+  // Generate skills section
+  const skillLines = installedSkills.map(name => {
+    const relativePath = `skills/${name}/SKILL.md`;
+    return `- [${name}](${relativePath})`;
+  });
+
+  const skillsSection = installedSkills.length > 0
+    ? `${DROID_SKILLS_START}\n## Droid Skills\n\n${skillLines.join('\n')}\n${DROID_SKILLS_END}`
+    : '';
+
+  // Check if section already exists
+  const startIdx = content.indexOf(DROID_SKILLS_START);
+  const endIdx = content.indexOf(DROID_SKILLS_END);
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing section
+    content = content.slice(0, startIdx) + skillsSection + content.slice(endIdx + DROID_SKILLS_END.length);
+  } else if (skillsSection) {
+    // Append new section
+    content = content.trim() + '\n\n' + skillsSection + '\n';
+  }
+
+  // Ensure parent directory exists
+  const configDir = dirname(configPath);
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+
+  writeFileSync(configPath, content, 'utf-8');
+}
+
+/**
+ * Load a skill manifest from a skill directory
+ */
+export function loadSkillManifest(skillDir: string): SkillManifest | null {
+  const manifestPath = join(skillDir, 'SKILL.yaml');
+
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(manifestPath, 'utf-8');
+    return YAML.parse(content) as SkillManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get all bundled skills
+ */
+export function getBundledSkills(): SkillManifest[] {
+  if (!existsSync(BUNDLED_SKILLS_DIR)) {
+    return [];
+  }
+
+  const skillDirs = readdirSync(BUNDLED_SKILLS_DIR, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => dirent.name);
+
+  const skills: SkillManifest[] = [];
+
+  for (const skillDir of skillDirs) {
+    const manifest = loadSkillManifest(join(BUNDLED_SKILLS_DIR, skillDir));
+    if (manifest) {
+      skills.push(manifest);
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Check if a skill is installed
+ */
+export function isSkillInstalled(skillName: string): boolean {
+  const config = loadConfig();
+  return skillName in config.skills;
+}
+
+/**
+ * Get installed skill info
+ */
+export function getInstalledSkill(skillName: string): InstalledSkill | null {
+  const config = loadConfig();
+  return config.skills[skillName] || null;
+}
+
+/**
+ * Install a skill
+ */
+export function installSkill(skillName: string): { success: boolean; message: string } {
+  const config = loadConfig();
+  const bundledSkillDir = join(BUNDLED_SKILLS_DIR, skillName);
+
+  if (!existsSync(bundledSkillDir)) {
+    return { success: false, message: `Skill '${skillName}' not found` };
+  }
+
+  const manifest = loadSkillManifest(bundledSkillDir);
+  if (!manifest) {
+    return { success: false, message: `Invalid skill manifest for '${skillName}'` };
+  }
+
+  // Check dependencies
+  if (manifest.dependencies) {
+    for (const dep of manifest.dependencies) {
+      if (!isSkillInstalled(dep)) {
+        return {
+          success: false,
+          message: `Missing dependency: '${dep}'. Install it first with \`droid install ${dep}\``,
+        };
+      }
+    }
+  }
+
+  const skillsPath = getSkillsInstallPath(config.ai_tool);
+  const targetSkillDir = join(skillsPath, skillName);
+
+  // Ensure skills directory exists
+  if (!existsSync(skillsPath)) {
+    mkdirSync(skillsPath, { recursive: true });
+  }
+
+  // Copy SKILL.md (the actual skill file for Claude Code / OpenCode)
+  const skillMdSource = join(bundledSkillDir, 'SKILL.md');
+  if (existsSync(skillMdSource)) {
+    if (!existsSync(targetSkillDir)) {
+      mkdirSync(targetSkillDir, { recursive: true });
+    }
+    const skillMdTarget = join(targetSkillDir, 'SKILL.md');
+    const content = readFileSync(skillMdSource, 'utf-8');
+    writeFileSync(skillMdTarget, content);
+  }
+
+  // Copy commands if present
+  const commandsSource = join(bundledSkillDir, 'commands');
+  if (existsSync(commandsSource)) {
+    const commandsPath = getCommandsInstallPath(config.ai_tool);
+    if (!existsSync(commandsPath)) {
+      mkdirSync(commandsPath, { recursive: true });
+    }
+    cpSync(commandsSource, commandsPath, { recursive: true });
+  }
+
+  // Update config
+  config.skills[skillName] = {
+    version: manifest.version,
+    installed_at: new Date().toISOString(),
+  };
+  saveConfig(config);
+
+  // Update AI tool's config file with skill reference
+  const installedSkillNames = Object.keys(config.skills);
+  updateAIConfigSkills(config.ai_tool, installedSkillNames);
+
+  return { success: true, message: `Installed ${skillName} v${manifest.version}` };
+}
+
+/**
+ * Uninstall a skill
+ */
+export function uninstallSkill(skillName: string): { success: boolean; message: string } {
+  const config = loadConfig();
+
+  if (!isSkillInstalled(skillName)) {
+    return { success: false, message: `Skill '${skillName}' is not installed` };
+  }
+
+  // Remove skill files from AI tool location
+  const skillsPath = getSkillsInstallPath(config.ai_tool);
+  const skillDir = join(skillsPath, skillName);
+  if (existsSync(skillDir)) {
+    rmSync(skillDir, { recursive: true });
+  }
+
+  // Remove command files if they exist
+  const bundledSkillDir = join(BUNDLED_SKILLS_DIR, skillName);
+  const commandsSource = join(bundledSkillDir, 'commands');
+  if (existsSync(commandsSource)) {
+    const commandsPath = getCommandsInstallPath(config.ai_tool);
+    const commandFiles = readdirSync(commandsSource);
+    for (const file of commandFiles) {
+      const commandPath = join(commandsPath, file);
+      if (existsSync(commandPath)) {
+        rmSync(commandPath);
+      }
+    }
+  }
+
+  // Remove from config
+  delete config.skills[skillName];
+  saveConfig(config);
+
+  // Update AI tool's config file to remove skill reference
+  const installedSkillNames = Object.keys(config.skills);
+  updateAIConfigSkills(config.ai_tool, installedSkillNames);
+
+  return { success: true, message: `Uninstalled ${skillName}` };
+}
+
+/**
+ * Get skill status display string
+ */
+export function getSkillStatusDisplay(status?: SkillStatus): string {
+  switch (status) {
+    case SkillStatus.Alpha:
+      return '[alpha]';
+    case SkillStatus.Beta:
+      return '[beta]';
+    case SkillStatus.Stable:
+    default:
+      return '';
+  }
+}

package/src/lib/types.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'bun:test';
+import {
+  AITool,
+  BuiltInOutput,
+  SkillStatus,
+  ConfigOptionType,
+  getAITag,
+} from './types.js';
+
+describe('AITool enum', () => {
+  it('should have correct values', () => {
+    expect(AITool.ClaudeCode).toBe('claude-code');
+    expect(AITool.OpenCode).toBe('opencode');
+  });
+
+  it('should be usable in switch statements', () => {
+    const tool = AITool.ClaudeCode;
+    let result = '';
+
+    switch (tool) {
+      case AITool.ClaudeCode:
+        result = 'claude';
+        break;
+      case AITool.OpenCode:
+        result = 'opencode';
+        break;
+    }
+
+    expect(result).toBe('claude');
+  });
+});
+
+describe('BuiltInOutput enum', () => {
+  it('should have correct values', () => {
+    expect(BuiltInOutput.Terminal).toBe('terminal');
+    expect(BuiltInOutput.Editor).toBe('editor');
+  });
+
+  it('should only have Terminal and Editor (Brain is skill-provided)', () => {
+    const values = Object.values(BuiltInOutput);
+    expect(values).toEqual(['terminal', 'editor']);
+  });
+});
+
+describe('SkillStatus enum', () => {
+  it('should have correct values', () => {
+    expect(SkillStatus.Stable).toBe('stable');
+    expect(SkillStatus.Beta).toBe('beta');
+    expect(SkillStatus.Alpha).toBe('alpha');
+  });
+});
+
+describe('ConfigOptionType enum', () => {
+  it('should have correct values', () => {
+    expect(ConfigOptionType.String).toBe('string');
+    expect(ConfigOptionType.Boolean).toBe('boolean');
+    expect(ConfigOptionType.Select).toBe('select');
+  });
+});
+
+describe('getAITag', () => {
+  it('should always return @droid', () => {
+    expect(getAITag()).toBe('@droid');
+  });
+});

package/src/lib/types.ts

@@ -0,0 +1,68 @@
+export enum AITool {
+  ClaudeCode = 'claude-code',
+  OpenCode = 'opencode',
+}
+
+/**
+ * Get the AI's mention tag
+ * Always @droid - consistent branding regardless of underlying AI tool
+ */
+export function getAITag(): string {
+  return '@droid';
+}
+
+// Built-in output preferences (always available)
+export enum BuiltInOutput {
+  Terminal = 'terminal',
+  Editor = 'editor',
+}
+
+// Output preference in config can be a built-in OR a skill name
+export type OutputPreference = BuiltInOutput | string;
+
+export enum SkillStatus {
+  Stable = 'stable',
+  Beta = 'beta',
+  Alpha = 'alpha',
+}
+
+export enum ConfigOptionType {
+  String = 'string',
+  Boolean = 'boolean',
+  Select = 'select',
+}
+
+export interface DroidConfig {
+  ai_tool: AITool;
+  user_mention: string;
+  output_preference: OutputPreference;
+  git_username: string;
+  skills: Record<string, InstalledSkill>;
+}
+
+export interface InstalledSkill {
+  version: string;
+  installed_at: string;
+}
+
+export interface SkillManifest {
+  name: string;
+  description: string;
+  version: string;
+  status?: SkillStatus;
+  dependencies?: string[];
+  config_schema?: Record<string, ConfigOption>;
+  // Skills can declare they provide an output target
+  provides_output?: boolean;
+}
+
+export interface ConfigOption {
+  type: ConfigOptionType;
+  description: string;
+  default?: string | boolean;
+  options?: string[]; // for select type
+}
+
+export interface SkillOverrides {
+  [key: string]: string | boolean | number;
+}

package/src/lib/version.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'bun:test';
+import { getVersion } from './version.js';
+
+describe('getVersion', () => {
+  it('should return a version string', () => {
+    const version = getVersion();
+    expect(typeof version).toBe('string');
+  });
+
+  it('should return a valid semver format', () => {
+    const version = getVersion();
+    // Basic semver check: major.minor.patch
+    const semverRegex = /^\d+\.\d+\.\d+/;
+    expect(version).toMatch(semverRegex);
+  });
+
+  it('should return version from package.json', () => {
+    const version = getVersion();
+    // Version should be a non-empty semver string (actual value changes with releases)
+    expect(version.length).toBeGreaterThan(0);
+    expect(version).not.toBe('0.0.0');
+  });
+});

package/src/lib/version.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '../../package.json');
+
+/**
+ * Get the current version from package.json
+ */
+export function getVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    return pkg.version as string;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Check for updates (non-blocking)
+ * Shows a message if a new version is available
+ */
+export async function checkForUpdates(): Promise<void> {
+  try {
+    const currentVersion = getVersion();
+
+    // Use npm view to check latest version
+    const latestVersion = execSync('npm view @orderful/droid version 2>/dev/null', {
+      encoding: 'utf-8',
+      timeout: 3000,
+    }).trim();
+
+    if (latestVersion && latestVersion !== currentVersion) {
+      console.log(
+        chalk.yellow(
+          `\n⚠️  A new version of droid is available (${currentVersion} → ${latestVersion})`
+        )
+      );
+      console.log(chalk.yellow(`   Run ${chalk.bold('droid update')} to upgrade\n`));
+    }
+  } catch {
+    // Silently fail - update check is non-critical
+  }
+}

package/src/skills/comments/SKILL.md

@@ -0,0 +1,65 @@
+# Comments Skill
+
+Enable inline conversation in any file using `> @droid` and `> @{user}` markers.
+
+## How It Works
+
+Leave comments for the AI using `> @droid`:
+
+```markdown
+> @droid What do you think of this approach?
+
+> @droid Can you add error handling here?
+```
+
+The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `@fry`):
+
+```markdown
+> @fry I think this approach is solid. One consideration...
+```
+
+## Tag Convention
+
+| Who | Tag |
+|-----|-----|
+| AI | `@droid` (+ any configured aliases) |
+| User | Configured (e.g., `@fry`) |
+
+## Commands
+
+- `/comments check` - Scan for AI markers and address each one
+- `/comments check {path}` - Scope to specific file or directory
+- `/comments cleanup` - Find resolved comment threads and remove them
+
+## Behavior
+
+### On `/comments check`:
+1. Search for `> @droid` (and any configured `ai_mentions`) in the specified scope
+2. If there's a `git diff`, check those files first for relevant context
+3. For each comment, determine intent:
+   - **Action request** ("do X", "add Y", "fix Z") → Execute the action, remove the comment
+   - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`, keep original comment
+
+### On `/comments cleanup`:
+1. Find AI tag and `> @{user_mention}` pairs where conversation appears resolved
+2. Remove both markers
+3. Output a summary of what was discussed/decided
+
+## Configuration
+
+Configured via `~/.droid/skills/comments/overrides.yaml` or inherits from global `~/.droid/config.yaml`:
+
+```yaml
+# Override the user mention (default: from global config)
+user_mention: "@fry"
+
+# Additional AI mentions to recognize (e.g., if you're used to @claude)
+ai_mentions: "@claude"
+
+# Keep comments after addressing them (default: false)
+preserve_comments: false
+```
+
+## File Type Support
+
+Works in any text file. Respects `.gitignore` and skips common build directories (node_modules, dist, .git, etc.).