@sundial-ai/cli 0.1.0

package/src/core/skill-info.ts

@@ -0,0 +1,246 @@
+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.
+ * Only checks the path itself and its direct children.
+ * 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[] = [];
+
+  // Check if the path itself is a skill
+  if (await isValidSkillDirectory(searchPath)) {
+    skills.push(searchPath);
+    return skills;
+  }
+
+  // Check direct children only
+  try {
+    const entries = await fs.readdir(searchPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const childPath = path.join(searchPath, entry.name);
+        if (await isValidSkillDirectory(childPath)) {
+          skills.push(childPath);
+        }
+      }
+    }
+  } catch {
+    // Permission denied or other error, skip
+  }
+
+  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;
+}

package/src/core/skill-source.ts

@@ -0,0 +1,118 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { isShortcut, getShortcutUrl } from '../utils/registry.js';
+import type { SkillSource } from '../types/index.js';
+
+/**
+ * Check if input looks like a GitHub URL or reference.
+ * Matches: github.com/user/repo, https://github.com/..., etc.
+ */
+export function isGithubUrl(input: string): boolean {
+  return input.includes('github.com');
+}
+
+/**
+ * Check if input looks like a local file path.
+ * Matches: ./path, ../path, ~/path, /absolute/path
+ */
+export function isLocalPath(input: string): boolean {
+  // Check if it starts with path indicators
+  if (input.startsWith('./') ||
+      input.startsWith('../') ||
+      input.startsWith('~/') ||
+      input.startsWith('/')) {
+    return true;
+  }
+
+  // Check if it's an existing path on disk
+  const resolved = path.resolve(input);
+  return fs.pathExistsSync(resolved);
+}
+
+/**
+ * Resolve a skill input to its source type and location.
+ *
+ * Resolution order:
+ * 1. Check if it's a registered shortcut (e.g., "tinker")
+ * 2. Check if it contains "github.com" (treat as GitHub URL)
+ * 3. Check if it's a valid local path
+ * 4. Otherwise, throw error
+ */
+export function resolveSkillSource(input: string): SkillSource {
+  // 1. Check shortcuts first
+  if (isShortcut(input)) {
+    const url = getShortcutUrl(input)!;
+    return {
+      type: 'shortcut',
+      location: url,
+      originalInput: input
+    };
+  }
+
+  // 2. Check if it's a GitHub URL
+  if (isGithubUrl(input)) {
+    // Normalize the URL for degit
+    let location = input;
+
+    // Remove https:// or http:// prefix if present
+    location = location.replace(/^https?:\/\//, '');
+
+    // Handle github.com/user/repo/tree/branch/path format
+    // Convert to degit format: user/repo/path#branch
+    const treeMatch = location.match(/^github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+)$/);
+    if (treeMatch) {
+      const [, user, repo, branch, subpath] = treeMatch;
+      location = `${user}/${repo}/${subpath}#${branch}`;
+    } else {
+      // Simple format: github.com/user/repo -> user/repo
+      location = location.replace(/^github\.com\//, '');
+    }
+
+    return {
+      type: 'github',
+      location,
+      originalInput: input
+    };
+  }
+
+  // 3. Check if it's a local path
+  if (isLocalPath(input)) {
+    // Resolve to absolute path, handling ~
+    let location = input;
+    if (location.startsWith('~/')) {
+      location = path.join(process.env.HOME || '', location.slice(2));
+    }
+    location = path.resolve(location);
+
+    return {
+      type: 'local',
+      location,
+      originalInput: input
+    };
+  }
+
+  // 4. Not found
+  throw new Error(`Skill not found: "${input}". Expected a shortcut name, GitHub URL, or local path.`);
+}
+
+/**
+ * Extract skill name from a source.
+ * For GitHub: last path segment
+ * For local: folder name
+ * For shortcut: the shortcut name itself
+ */
+export function getSkillNameFromSource(source: SkillSource): string {
+  if (source.type === 'shortcut') {
+    return source.originalInput;
+  }
+
+  if (source.type === 'local') {
+    return path.basename(source.location);
+  }
+
+  // GitHub: extract from path (e.g., "user/repo/skills/tinker#main" -> "tinker")
+  const parts = source.location.split('/');
+  const lastPart = parts[parts.length - 1];
+  // Remove branch suffix if present (e.g., "tinker#main" -> "tinker")
+  return lastPart.split('#')[0];
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { SUPPORTED_AGENTS } from './core/agents.js';
+import { addCommand } from './commands/add.js';
+import { removeCommand } from './commands/remove.js';
+import { listCommand } from './commands/list.js';
+import { showCommand } from './commands/show.js';
+import { configCommand } from './commands/config.js';
+import { suggestCommand, getValidCommands } from './utils/fuzzy-match.js';
+import type { CommandFlags } from './types/index.js';
+
+const program = new Command();
+
+program
+  .name('sun')
+  .description('Sundial CLI - Manage skills for your AI agents')
+  .version('0.1.0');
+
+// Add command
+const add = program
+  .command('add <skills...>')
+  .description('Add skill(s) to agent configuration(s)')
+  .option('--global', 'Install to global agent config (~/.claude/, ~/.codex/, etc.)');
+
+// Add agent flags dynamically
+for (const agent of SUPPORTED_AGENTS) {
+  add.option(`--${agent.flag}`, `Install to ${agent.name}`);
+}
+
+add.action(async (skills: string[], options: CommandFlags) => {
+  try {
+    await addCommand(skills, options);
+  } catch (error) {
+    console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+    process.exit(1);
+  }
+});
+
+// Remove command
+const remove = program
+  .command('remove <skills...>')
+  .description('Remove skill(s) from agent configuration(s)')
+  .option('--global', 'Remove from global config');
+
+for (const agent of SUPPORTED_AGENTS) {
+  remove.option(`--${agent.flag}`, `Remove from ${agent.name}`);
+}
+
+remove.action(async (skills: string[], options: CommandFlags) => {
+  try {
+    await removeCommand(skills, options);
+  } catch (error) {
+    console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+    process.exit(1);
+  }
+});
+
+// List command
+program
+  .command('list')
+  .description('List all installed skills for each agent')
+  .action(async () => {
+    try {
+      await listCommand();
+    } catch (error) {
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+  });
+
+// Show command
+program
+  .command('show <skill>')
+  .description('Show skill details and installation locations')
+  .action(async (skill: string) => {
+    try {
+      await showCommand(skill);
+    } catch (error) {
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+  });
+
+// Config command
+program
+  .command('config')
+  .description('Configure default agents')
+  .action(async () => {
+    try {
+      await configCommand();
+    } catch (error) {
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+  });
+
+// Handle unknown commands with fuzzy matching
+program.on('command:*', (operands) => {
+  const unknownCommand = operands[0];
+  const suggestion = suggestCommand(unknownCommand);
+
+  console.error(chalk.red(`Error: Unknown command '${unknownCommand}'`));
+
+  if (suggestion) {
+    console.error(chalk.yellow(`Did you mean '${suggestion}'?`));
+  }
+
+  console.error();
+  console.error(`Valid commands: ${getValidCommands().join(', ')}`);
+  process.exit(1);
+});
+
+// Parse and execute
+program.parse();

package/src/types/index.ts

@@ -0,0 +1,64 @@
+export type AgentType = 'claude' | 'codex' | 'gemini';
+
+export interface AgentConfig {
+  name: string;
+  flag: string;
+  folderName: string;
+}
+
+export interface SunConfig {
+  defaultAgents: AgentType[];
+  firstRunComplete: boolean;
+  skillRegistryUrl?: string;
+}
+
+/**
+ * Skill metadata parsed from SKILL.md frontmatter.
+ * Per spec: https://agentskills.io/specification#skill-md-format
+ */
+export interface SkillMetadata {
+  /** Required: Max 64 chars, lowercase letters, numbers, hyphens only */
+  name: string;
+  /** Required: Max 1024 chars, describes what the skill does */
+  description: string;
+  /** Optional: License name or reference to bundled license file */
+  license?: string;
+  /** Optional: Max 500 chars, environment requirements */
+  compatibility?: string;
+  /** Optional: Arbitrary key-value mapping (includes author, version, etc.) */
+  metadata?: Record<string, string>;
+  /** Optional: Space-delimited list of pre-approved tools (experimental) */
+  allowedTools?: string;
+}
+
+export type SkillSourceType = 'shortcut' | 'github' | 'local';
+
+/** Used at install time to determine how to fetch a skill */
+export interface SkillSource {
+  type: SkillSourceType;
+  /** The resolved location (URL for github/shortcut, path for local) */
+  location: string;
+  /** Original input string from user (e.g., "tinker" or "github.com/user/skill") */
+  originalInput: string;
+}
+
+export interface SkillInstallation {
+  agent: AgentType;
+  path: string;
+  isGlobal: boolean;
+  metadata: SkillMetadata;
+  contentHash: string;
+}
+
+export interface CommandFlags {
+  global?: boolean;
+  claude?: boolean;
+  codex?: boolean;
+  gemini?: boolean;
+}
+
+export interface DetectedAgent {
+  agent: AgentConfig;
+  path: string;
+  isGlobal: boolean;
+}