@sundial-ai/cli 0.0.1

package/src/core/agent-detect.ts

@@ -0,0 +1,125 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { SUPPORTED_AGENTS } from './agents.js';
+import type { DetectedAgent, AgentConfig } from '../types/index.js';
+
+const execAsync = promisify(exec);
+
+// Agent folder names to search for
+const AGENT_FOLDER_NAMES = new Set(SUPPORTED_AGENTS.map(a => a.folderName));
+
+export async function detectAgentsInDirectory(directory: string, isGlobal: boolean): Promise<DetectedAgent[]> {
+  const detected: DetectedAgent[] = [];
+
+  for (const agent of SUPPORTED_AGENTS) {
+    const agentPath = path.join(directory, agent.folderName);
+    if (await fs.pathExists(agentPath)) {
+      detected.push({
+        agent,
+        path: agentPath,
+        isGlobal
+      });
+    }
+  }
+
+  return detected;
+}
+
+export async function detectLocalAgents(): Promise<DetectedAgent[]> {
+  return detectAgentsInDirectory(process.cwd(), false);
+}
+
+export async function detectGlobalAgents(): Promise<DetectedAgent[]> {
+  return detectAgentsInDirectory(os.homedir(), true);
+}
+
+/**
+ * Search the entire file system for all agent folders.
+ * Uses `find -type d -name` for efficiency.
+ */
+export async function detectAllAgentFolders(): Promise<DetectedAgent[]> {
+  const results: DetectedAgent[] = [];
+  const homeDir = os.homedir();
+
+  // Build find command: find ~ -type d \( -name ".claude" -o -name ".codex" -o -name ".gemini" \)
+  const namePatterns = SUPPORTED_AGENTS.map(a => `-name "${a.folderName}"`).join(' -o ');
+  const findCmd = `find "${homeDir}" -type d \\( ${namePatterns} \\) 2>/dev/null`;
+
+  try {
+    const { stdout } = await execAsync(findCmd, { maxBuffer: 10 * 1024 * 1024 });
+    const agentPaths = stdout.trim().split('\n').filter(Boolean);
+
+    for (const agentPath of agentPaths) {
+      const folderName = path.basename(agentPath);
+      const agent = SUPPORTED_AGENTS.find(a => a.folderName === folderName);
+      if (!agent) continue;
+
+      const isGlobal = path.dirname(agentPath) === homeDir;
+      results.push({
+        agent,
+        path: agentPath,
+        isGlobal
+      });
+    }
+  } catch {
+    // find command failed - fall back to simple detection
+    const [local, global] = await Promise.all([
+      detectLocalAgents(),
+      detectGlobalAgents()
+    ]);
+    return [...local, ...global];
+  }
+
+  return results;
+}
+
+/**
+ * Search the entire file system for agent folders that contain skills.
+ * Uses `find` to locate skills directories with content.
+ */
+export async function detectAllSkillsFolders(): Promise<DetectedAgent[]> {
+  const allAgents = await detectAllAgentFolders();
+
+  // Filter to only those with skills installed
+  const withSkills: DetectedAgent[] = [];
+  for (const detected of allAgents) {
+    const skillsDir = path.join(detected.path, 'skills');
+    if (await fs.pathExists(skillsDir)) {
+      const entries = await fs.readdir(skillsDir);
+      if (entries.length > 0) {
+        withSkills.push(detected);
+      }
+    }
+  }
+
+  return withSkills;
+}
+
+/**
+ * Detect agents in local and global directories only (fast).
+ */
+export async function detectAllAgents(): Promise<DetectedAgent[]> {
+  const [local, global] = await Promise.all([
+    detectLocalAgents(),
+    detectGlobalAgents()
+  ]);
+  return [...local, ...global];
+}
+
+export function getAgentPath(agent: AgentConfig, isGlobal: boolean): string {
+  const baseDir = isGlobal ? os.homedir() : process.cwd();
+  return path.join(baseDir, agent.folderName);
+}
+
+export function getSkillsPath(agent: AgentConfig, isGlobal: boolean): string {
+  return path.join(getAgentPath(agent, isGlobal), 'skills');
+}
+
+export async function ensureSkillsDirectory(agent: AgentConfig, isGlobal: boolean): Promise<string> {
+  const skillsPath = getSkillsPath(agent, isGlobal);
+  await fs.ensureDir(skillsPath);
+  return skillsPath;
+}

package/src/core/agents.ts

@@ -0,0 +1,40 @@
+import type { AgentConfig, AgentType } from '../types/index.js';
+
+export const SUPPORTED_AGENTS: AgentConfig[] = [
+  {
+    name: 'Claude Code',
+    flag: 'claude',
+    folderName: '.claude'
+  },
+  {
+    name: 'Codex',
+    flag: 'codex',
+    folderName: '.codex'
+  },
+  {
+    name: 'Gemini',
+    flag: 'gemini',
+    folderName: '.gemini'
+  }
+];
+
+export function getAgentByFlag(flag: string): AgentConfig | undefined {
+  return SUPPORTED_AGENTS.find(agent => agent.flag === flag);
+}
+
+export function getAgentByFolder(folderName: string): AgentConfig | undefined {
+  return SUPPORTED_AGENTS.find(agent => agent.folderName === folderName);
+}
+
+export function getSupportedAgentsMessage(): string {
+  const agentNames = SUPPORTED_AGENTS.map(a => a.name).join(', ');
+  return `Currently supported agents: ${agentNames}`;
+}
+
+export function isValidAgentType(flag: string): flag is AgentType {
+  return SUPPORTED_AGENTS.some(agent => agent.flag === flag);
+}
+
+export function getAgentFlags(): string[] {
+  return SUPPORTED_AGENTS.map(a => a.flag);
+}

package/src/core/config-manager.ts

@@ -0,0 +1,55 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import type { SunConfig, AgentType } from '../types/index.js';
+
+const CONFIG_DIR = path.join(os.homedir(), '.sun');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+const DEFAULT_CONFIG: SunConfig = {
+  defaultAgents: [],
+  firstRunComplete: false
+};
+
+export async function ensureConfigDir(): Promise<void> {
+  await fs.ensureDir(CONFIG_DIR);
+}
+
+export async function loadConfig(): Promise<SunConfig> {
+  try {
+    await ensureConfigDir();
+    if (await fs.pathExists(CONFIG_FILE)) {
+      const content = await fs.readFile(CONFIG_FILE, 'utf-8');
+      return { ...DEFAULT_CONFIG, ...JSON.parse(content) };
+    }
+  } catch {
+    // Config doesn't exist or is invalid, return default
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+export async function saveConfig(config: SunConfig): Promise<void> {
+  await ensureConfigDir();
+  await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+export async function isFirstRun(): Promise<boolean> {
+  const config = await loadConfig();
+  return !config.firstRunComplete;
+}
+
+export async function getDefaultAgents(): Promise<AgentType[]> {
+  const config = await loadConfig();
+  return config.defaultAgents;
+}
+
+export async function setDefaultAgents(agents: AgentType[]): Promise<void> {
+  const config = await loadConfig();
+  config.defaultAgents = agents;
+  config.firstRunComplete = true;
+  await saveConfig(config);
+}
+
+export function getConfigPath(): string {
+  return CONFIG_FILE;
+}

package/src/core/skill-hash.ts

@@ -0,0 +1,61 @@
+import crypto from 'crypto';
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * Get all files in a directory recursively, sorted for consistency.
+ */
+async function getAllFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function walk(currentDir: string): Promise<void> {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  await walk(dir);
+  // Sort for consistent ordering across platforms
+  return files.sort();
+}
+
+/**
+ * Compute a SHA-256 hash of all files in a skill folder.
+ * This allows detecting if two skills with the same name have different content.
+ *
+ * The hash is computed by:
+ * 1. Getting all files recursively
+ * 2. Sorting them by path for consistency
+ * 3. Hashing each file's relative path + content
+ * 4. Combining into a final hash
+ */
+export async function computeContentHash(skillPath: string): Promise<string> {
+  const files = await getAllFiles(skillPath);
+
+  if (files.length === 0) {
+    // Empty folder - return hash of empty string
+    return crypto.createHash('sha256').update('').digest('hex').slice(0, 12);
+  }
+
+  const hash = crypto.createHash('sha256');
+
+  for (const file of files) {
+    // Include relative path in hash (so moving files changes the hash)
+    const relativePath = path.relative(skillPath, file);
+    hash.update(relativePath);
+
+    // Include file content
+    const content = await fs.readFile(file);
+    hash.update(content);
+  }
+
+  // Return first 12 chars for readability
+  return hash.digest('hex').slice(0, 12);
+}

package/src/core/skill-info.ts

@@ -0,0 +1,248 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { SUPPORTED_AGENTS } from './agents.js';
+import { computeContentHash } from './skill-hash.js';
+import type { SkillMetadata, SkillInstallation, AgentType } from '../types/index.js';
+
+/**
+ * Parse YAML-like frontmatter from SKILL.md content.
+ * Frontmatter is delimited by --- at start and end.
+ * Handles nested metadata field as key-value pairs.
+ */
+function parseFrontmatter(content: string): SkillMetadata | null {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    return null;
+  }
+
+  const lines = frontmatterMatch[1].split('\n');
+  let name = '';
+  let description = '';
+  let license: string | undefined;
+  let compatibility: string | undefined;
+  let allowedTools: string | undefined;
+  const metadata: Record<string, string> = {};
+
+  let inMetadata = false;
+
+  for (const line of lines) {
+    // Check if we're entering metadata block (indented or explicit)
+    if (line.match(/^metadata:\s*$/)) {
+      inMetadata = true;
+      continue;
+    }
+
+    // If line starts with non-whitespace, we're out of metadata block
+    if (inMetadata && line.match(/^\S/)) {
+      inMetadata = false;
+    }
+
+    const colonIndex = line.indexOf(':');
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      let value = line.slice(colonIndex + 1).trim();
+
+      // Remove surrounding quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      if (inMetadata) {
+        // Nested under metadata
+        metadata[key] = value;
+      } else {
+        // Top-level fields
+        switch (key) {
+          case 'name':
+            name = value;
+            break;
+          case 'description':
+            description = value;
+            break;
+          case 'license':
+            license = value;
+            break;
+          case 'compatibility':
+            compatibility = value;
+            break;
+          case 'allowed-tools':
+            allowedTools = value;
+            break;
+        }
+      }
+    }
+  }
+
+  // name and description are required
+  if (!name || !description) {
+    return null;
+  }
+
+  return {
+    name,
+    description,
+    license,
+    compatibility,
+    metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    allowedTools
+  };
+}
+
+/**
+ * Check if a directory is a valid skill.
+ * A valid skill must contain a SKILL.md with required frontmatter (name, description).
+ */
+export async function isValidSkillDirectory(dirPath: string): Promise<boolean> {
+  const skillMdPath = path.join(dirPath, 'SKILL.md');
+
+  if (!await fs.pathExists(skillMdPath)) {
+    return false;
+  }
+
+  try {
+    const content = await fs.readFile(skillMdPath, 'utf-8');
+    const metadata = parseFrontmatter(content);
+    return metadata !== null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find skill directories within a given path by searching recursively for SKILL.md files.
+ * A skill is any directory containing a valid SKILL.md file (with name + description).
+ */
+export async function findSkillDirectories(searchPath: string): Promise<string[]> {
+  const skills: string[] = [];
+
+  // Recursively find all SKILL.md files
+  async function searchRecursively(dir: string): Promise<void> {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isFile() && entry.name === 'SKILL.md') {
+          // Found a SKILL.md - check if it's valid
+          if (await isValidSkillDirectory(dir)) {
+            skills.push(dir);
+          }
+        } else if (entry.isDirectory() && !entry.name.startsWith('.git')) {
+          // Skip .git directories but recurse into others
+          await searchRecursively(fullPath);
+        }
+      }
+    } catch {
+      // Permission denied or other error, skip this directory
+    }
+  }
+
+  await searchRecursively(searchPath);
+  return skills;
+}
+
+/**
+ * Read skill metadata from SKILL.md frontmatter.
+ * The canonical skill name comes from the frontmatter, not the folder name.
+ */
+export async function readSkillMetadata(skillPath: string): Promise<SkillMetadata | null> {
+  const skillMdPath = path.join(skillPath, 'SKILL.md');
+
+  try {
+    const content = await fs.readFile(skillMdPath, 'utf-8');
+    return parseFrontmatter(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the canonical skill name from SKILL.md frontmatter.
+ * Returns null if not a valid skill.
+ */
+export async function getSkillName(skillPath: string): Promise<string | null> {
+  const metadata = await readSkillMetadata(skillPath);
+  return metadata?.name || null;
+}
+
+/**
+ * Find all installations of a skill by name across all agents.
+ */
+export async function findSkillInstallations(skillName: string): Promise<SkillInstallation[]> {
+  const installations: SkillInstallation[] = [];
+
+  // Check both local and global for each agent
+  const locations = [
+    { base: process.cwd(), isGlobal: false },
+    { base: os.homedir(), isGlobal: true }
+  ];
+
+  for (const { base, isGlobal } of locations) {
+    for (const agent of SUPPORTED_AGENTS) {
+      const skillPath = path.join(base, agent.folderName, 'skills', skillName);
+
+      if (await fs.pathExists(skillPath)) {
+        const metadata = await readSkillMetadata(skillPath);
+        if (metadata) {
+          const contentHash = await computeContentHash(skillPath);
+
+          installations.push({
+            agent: agent.flag as AgentType,
+            path: skillPath,
+            isGlobal,
+            metadata,
+            contentHash
+          });
+        }
+      }
+    }
+  }
+
+  return installations;
+}
+
+/**
+ * List all installed skills for a specific agent.
+ */
+export async function listSkillsForAgent(
+  agentFolderName: string,
+  isGlobal: boolean
+): Promise<string[]> {
+  const base = isGlobal ? os.homedir() : process.cwd();
+  const skillsDir = path.join(base, agentFolderName, 'skills');
+
+  if (!await fs.pathExists(skillsDir)) {
+    return [];
+  }
+
+  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+  const skills: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const skillPath = path.join(skillsDir, entry.name);
+      const skillName = await getSkillName(skillPath);
+      if (skillName) {
+        skills.push(skillName);
+      }
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Check if a skill exists in an agent's folder.
+ */
+export async function skillExists(
+  skillName: string,
+  agentFolderName: string,
+  isGlobal: boolean
+): Promise<boolean> {
+  const base = isGlobal ? os.homedir() : process.cwd();
+  const skillPath = path.join(base, agentFolderName, 'skills', skillName);
+  return (await fs.pathExists(skillPath)) && (await isValidSkillDirectory(skillPath));
+}

package/src/core/skill-install.ts

@@ -0,0 +1,165 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+import { getAgentByFlag } from './agents.js';
+import { resolveSkillSource } from './skill-source.js';
+import { findSkillDirectories, readSkillMetadata } from './skill-info.js';
+import type { AgentType, SkillSource } from '../types/index.js';
+
+/**
+ * Get the destination path for installing a skill.
+ * Skill name comes from SKILL.md frontmatter.
+ */
+function getSkillDestination(skillName: string, agentFlag: AgentType, isGlobal: boolean): string {
+  const agent = getAgentByFlag(agentFlag);
+  if (!agent) {
+    throw new Error(`Unknown agent: ${agentFlag}`);
+  }
+
+  const base = isGlobal ? os.homedir() : process.cwd();
+  return path.join(base, agent.folderName, 'skills', skillName);
+}
+
+/**
+ * Install a single skill directory to an agent.
+ * The skill name is taken from SKILL.md frontmatter (not the folder name).
+ * The destination folder will be named after the frontmatter name.
+ */
+async function installSkillDirectory(
+  skillDir: string,
+  agentFlag: AgentType,
+  isGlobal: boolean
+): Promise<string> {
+  // Get metadata from SKILL.md frontmatter (name and description are required)
+  const metadata = await readSkillMetadata(skillDir);
+  if (!metadata) {
+    throw new Error(`Invalid skill at "${skillDir}": SKILL.md must have name and description in frontmatter`);
+  }
+
+  const dest = getSkillDestination(metadata.name, agentFlag, isGlobal);
+
+  // Ensure parent directory exists
+  await fs.ensureDir(path.dirname(dest));
+
+  // Copy the skill folder (folder will be renamed to match frontmatter name)
+  await fs.copy(skillDir, dest, { overwrite: true });
+
+  return metadata.name;
+}
+
+/**
+ * Install skill(s) from a local path.
+ * Checks if path is a skill, otherwise checks direct children for SKILL.md.
+ */
+export async function installFromLocal(
+  source: SkillSource,
+  agentFlag: AgentType,
+  isGlobal: boolean
+): Promise<string[]> {
+  const skillDirs = await findSkillDirectories(source.location);
+
+  if (skillDirs.length === 0) {
+    throw new Error(`No skills found in "${source.location}". A skill must contain a SKILL.md file.`);
+  }
+
+  const installedSkills: string[] = [];
+  for (const skillDir of skillDirs) {
+    const skillName = await installSkillDirectory(skillDir, agentFlag, isGlobal);
+    installedSkills.push(skillName);
+  }
+
+  return installedSkills;
+}
+
+/**
+ * Install skill(s) from GitHub using degit.
+ * After downloading, checks if it's a skill or searches direct children for SKILL.md.
+ */
+export async function installFromGithub(
+  source: SkillSource,
+  agentFlag: AgentType,
+  isGlobal: boolean
+): Promise<string[]> {
+  // Create a temp directory to download to
+  const tempDir = path.join(os.tmpdir(), `sun-install-${Date.now()}`);
+
+  try {
+    // Download using degit
+    await fs.ensureDir(tempDir);
+    try {
+      execSync(`npx degit ${source.location} "${tempDir}"`, {
+        stdio: 'pipe'
+      });
+    } catch (error) {
+      const err = error as Error & { stderr?: Buffer };
+      const stderr = err.stderr?.toString() || err.message;
+      throw new Error(`Failed to download from GitHub: ${stderr}`);
+    }
+
+    // Find skills in downloaded content (checks itself and direct children)
+    const skillDirs = await findSkillDirectories(tempDir);
+
+    if (skillDirs.length === 0) {
+      throw new Error(`No skills found in "${source.originalInput}". A skill must contain a SKILL.md file.`);
+    }
+
+    // Install each skill found (name comes from SKILL.md frontmatter)
+    const installedSkills: string[] = [];
+    for (const skillDir of skillDirs) {
+      const skillName = await installSkillDirectory(skillDir, agentFlag, isGlobal);
+      installedSkills.push(skillName);
+    }
+
+    return installedSkills;
+  } finally {
+    // Clean up temp directory
+    await fs.remove(tempDir).catch(() => {});
+  }
+}
+
+/**
+ * Install skill(s) from any source to an agent.
+ * Returns list of installed skill names.
+ */
+export async function installSkill(
+  skillInput: string,
+  agentFlag: AgentType,
+  isGlobal: boolean
+): Promise<{ skillNames: string[]; source: SkillSource }> {
+  const source = resolveSkillSource(skillInput);
+
+  let skillNames: string[];
+
+  switch (source.type) {
+    case 'local':
+      skillNames = await installFromLocal(source, agentFlag, isGlobal);
+      break;
+    case 'github':
+    case 'shortcut':
+      skillNames = await installFromGithub(source, agentFlag, isGlobal);
+      break;
+    default:
+      throw new Error(`Unknown source type: ${(source as SkillSource).type}`);
+  }
+
+  return { skillNames, source };
+}
+
+/**
+ * Remove a skill from an agent.
+ */
+export async function removeSkill(
+  skillName: string,
+  agentFlag: AgentType,
+  isGlobal: boolean
+): Promise<boolean> {
+  const dest = getSkillDestination(skillName, agentFlag, isGlobal);
+
+  if (await fs.pathExists(dest)) {
+    await fs.remove(dest);
+    return true;
+  }
+
+  return false;
+}