@sundial-ai/cli 0.0.1

package/src/core/skill-source.ts

@@ -0,0 +1,125 @@
+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');
+}
+
+/**
+ * Normalize a GitHub URL to degit format.
+ * Converts: https://github.com/user/repo/tree/branch/path -> user/repo/path#branch
+ */
+function normalizeGithubUrl(url: string): string {
+  let location = url;
+
+  // 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 location;
+}
+
+/**
+ * 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: normalizeGithubUrl(url),
+      originalInput: input
+    };
+  }
+
+  // 2. Check if it's a GitHub URL
+  if (isGithubUrl(input)) {
+    return {
+      type: 'github',
+      location: normalizeGithubUrl(input),
+      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 all agent folders and packages, or details for a specific skill')
+  .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;
+}

package/src/utils/fuzzy-match.ts

@@ -0,0 +1,48 @@
+import fuzzysort from 'fuzzysort';
+
+const VALID_COMMANDS = ['add', 'remove', 'list', 'show', 'config'];
+
+export interface FuzzyMatch {
+  command: string;
+  score: number;
+}
+
+/**
+ * Find the closest matching command using fuzzy search.
+ * fuzzysort scores: 0 = perfect match, negative = worse match
+ */
+export function findClosestCommand(input: string): FuzzyMatch | null {
+  const results = fuzzysort.go(input, VALID_COMMANDS, {
+    // Allow any match (we'll filter by score later)
+    threshold: -Infinity
+  });
+
+  if (results.length === 0) {
+    return null;
+  }
+
+  const best = results[0];
+  return {
+    command: best.target,
+    score: best.score
+  };
+}
+
+/**
+ * Suggest a command if the input is close enough to a valid command.
+ * Returns null if no good suggestion (avoids suggesting "add" for "xyz").
+ */
+export function suggestCommand(input: string): string | null {
+  const match = findClosestCommand(input);
+
+  // Only suggest if score is reasonable (0=perfect, -100 is still decent for typos)
+  // Examples: "ad" -> "add" (good), "addd" -> "add" (good), "xyz" -> null (no suggestion)
+  if (match && match.score > -100) {
+    return match.command;
+  }
+  return null;
+}
+
+export function getValidCommands(): string[] {
+  return [...VALID_COMMANDS];
+}

package/src/utils/prompts.ts

@@ -0,0 +1,54 @@
+import { checkbox, confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { SUPPORTED_AGENTS } from '../core/agents.js';
+import type { AgentType } from '../types/index.js';
+
+/**
+ * Show an interactive checkbox UI for selecting default agents.
+ *
+ * @param currentDefaults - Previously saved defaults (empty on first run)
+ * @returns Array of selected agent flags (e.g., ['claude', 'codex'])
+ *
+ * Behavior:
+ * - Shows all supported agent TYPES from SUPPORTED_AGENTS
+ * - First run (currentDefaults empty): ALL agents are pre-selected
+ * - Subsequent runs: Only previously saved defaults are pre-selected
+ * - Must select at least one agent
+ */
+export async function promptAgentSelection(
+  currentDefaults: AgentType[] = []
+): Promise<AgentType[]> {
+  const isFirstRun = currentDefaults.length === 0;
+
+  console.log(chalk.gray('Use space to toggle, enter to confirm:\n'));
+
+  // Build choices from SUPPORTED_AGENTS constants
+  // Show paths so users understand what each agent refers to
+  const choices = SUPPORTED_AGENTS.map(agent => ({
+    name: `${agent.name} (~/${agent.folderName}/ and ./${agent.folderName}/)`,
+    value: agent.flag as AgentType,
+    // First run: select ALL agents
+    // Otherwise: only select if it was in previous defaults
+    checked: isFirstRun ? true : currentDefaults.includes(agent.flag as AgentType)
+  }));
+
+  const selectedAgents = await checkbox({
+    message: 'Select default agents:',
+    choices,
+    required: true,
+    theme: {
+      style: {
+        keysHelpTip: () => undefined
+      }
+    }
+  });
+
+  return selectedAgents;
+}
+
+export async function confirmAction(message: string): Promise<boolean> {
+  return confirm({
+    message,
+    default: true
+  });
+}

package/src/utils/registry.ts

@@ -0,0 +1,16 @@
+/** Skill shortcuts registry - maps short names to GitHub URLs */
+export const SKILL_SHORTCUTS: Record<string, string> = {
+  tinker: 'https://github.com/sundial-org/skills/tree/main/skills/tinker'
+};
+
+export function isShortcut(skill: string): boolean {
+  return skill in SKILL_SHORTCUTS;
+}
+
+export function getShortcutUrl(skill: string): string | undefined {
+  return SKILL_SHORTCUTS[skill];
+}
+
+export function listShortcuts(): string[] {
+  return Object.keys(SKILL_SHORTCUTS);
+}

package/test/README.md

@@ -0,0 +1,123 @@
+# Sundial CLI Integration Tests
+
+🚧 Warning: these tests were auto-generated by Claude Code.
+
+This directory contains bash-based integration tests for the Sundial CLI (`sun`).
+
+## Prerequisites
+
+Before running tests, build the CLI:
+
+```bash
+cd cli
+npm run build
+```
+
+## Running Tests
+
+Run all tests:
+
+```bash
+./test/run-all.sh
+```
+
+Or run `npm test` from the `cli/` directory.
+
+Run individual tests:
+
+```bash
+./test/test-add-remove.sh
+./test/test-config.sh
+./test/test-show.sh
+./test/test-fuzzy-match.sh
+```
+
+## Test Files
+
+| File | Description |
+|------|-------------|
+| `run-all.sh` | Master test runner - runs all tests and reports results |
+| `test-add-remove.sh` | Tests `sun add` and `sun remove` commands |
+| `test-config.sh` | Tests configuration management |
+| `test-show.sh` | Tests `sun show` command |
+| `test-fuzzy-match.sh` | Tests typo suggestions for misspelled commands |
+
+## Test Output
+
+All tests log their output to the `logs/` directory:
+
+- `logs/add-remove.log`
+- `logs/config.log`
+- `logs/show.log`
+- `logs/fuzzy-match.log`
+
+These logs contain the full CLI output and PASS/FAIL assertions for each test case.
+
+## Test Structure
+
+Each test script:
+
+1. Creates isolated temp directories for `HOME` and working directory
+2. Sets up any required config files
+3. Runs CLI commands and captures output
+4. Asserts on directory structure (folders exist/don't exist)
+5. Asserts on CLI output (contains expected strings)
+6. Cleans up temp directories on exit
+
+## What's Tested
+
+### test-add-remove.sh
+
+- **Local folder**: Add skill from local path
+- **Multi-skills**: Add multiple skills from parent directory
+- **Git**: Add skills from git repository (network dependent)
+- **Shortcuts**: Add skills via registry shortcuts (registry dependent)
+- **Local vs Global**: `--global` flag behavior
+- **Agent tags**: `--claude`, `--codex`, `--gemini` flags
+- **Remove**: Remove from single and multiple agents
+
+### test-config.sh
+
+- Config directory creation (`~/.sun/`)
+- Config file parsing
+- Default agents affect `add` command behavior
+- Explicit flags override config defaults
+
+### test-show.sh
+
+- Show with no agent folders
+- Show with empty agent folder
+- Show with installed skills
+- Show specific skill details
+- Show skill in multiple locations (local + global)
+- Show non-existent skill error
+
+### test-fuzzy-match.sh
+
+- Typo suggestions: `ad` → `add`, `remov` → `remove`, etc.
+- "Did you mean" messages
+- Valid commands list displayed
+- Non-zero exit code for unknown commands
+
+## Fixtures
+
+Test fixtures are in `fixtures/`:
+
+```
+fixtures/
+├── sample-skill/
+│   └── SKILL.md          # Single test skill
+└── multi-skills/
+    ├── skill-one/
+    │   └── SKILL.md      # First skill in multi-skill dir
+    └── skill-two/
+        └── SKILL.md      # Second skill in multi-skill dir
+```
+
+## Adding New Tests
+
+1. Create a new `test-*.sh` file
+2. Add header documentation following the existing pattern
+3. Use the helper functions: `log()`, `assert_dir_exists()`, `assert_output_contains()`
+4. Add cleanup trap: `trap cleanup EXIT`
+5. Add the test to the `TESTS` array in `run-all.sh`

package/test/fixtures/multi-skills/skill-one/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: skill-one
+description: First skill in multi-skills directory
+---
+
+# skill-one
+
+This is the first test skill in a multi-skill directory.

package/test/fixtures/multi-skills/skill-two/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: skill-two
+description: Second skill in multi-skills directory
+---
+
+# skill-two
+
+This is the second test skill in a multi-skill directory.

package/test/fixtures/sample-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: sample-skill
+description: A sample skill for testing the CLI
+---
+
+# sample-skill
+
+This is a test skill used by the CLI integration tests.

package/test/logs/add-remove.log

@@ -0,0 +1,108 @@
+=== Test run: Wed Jan 14 14:16:55 PST 2026 ===
+TEMP_DIR: /var/folders/64/t_nm43xn2mx3jnxm5pfyxrd80000gn/T/tmp.IvMSm6iqd9
+TEMP_HOME: /var/folders/64/t_nm43xn2mx3jnxm5pfyxrd80000gn/T/tmp.UUle90HZhY
+
+TEST: Add single skill from local folder
+----------------------------------------
+- Adding /Users/bmo/skills/cli/test/fixtures/sample-skill...
+✔ Added sample-skill
+
+Added sample-skill to Claude Code (local)
+(use --global to install globally)
+  PASS: Directory exists: .claude/skills/sample-skill
+  PASS: File exists: .claude/skills/sample-skill/SKILL.md
+
+TEST: Add multiple skills from parent directory
+------------------------------------------------
+- Adding /Users/bmo/skills/cli/test/fixtures/multi-skills...
+✔ Added skill-one, skill-two
+
+Added skill-one, skill-two to Claude Code (local)
+(use --global to install globally)
+  PASS: Directory exists: .claude/skills/skill-one
+  PASS: Directory exists: .claude/skills/skill-two
+  PASS: File exists: .claude/skills/skill-one/SKILL.md
+  PASS: File exists: .claude/skills/skill-two/SKILL.md
+
+TEST: Add skill from git repository
+------------------------------------
+- Adding github:sundial-org/skills...
+✖ Failed to add github:sundial-org/skills: Skill not found: "github:sundial-org/skills". Expected a shortcut name, GitHub URL, or local path.
+  SKIP: No skills installed (may need network)
+
+TEST: Add skill via shortcut (registry)
+----------------------------------------
+- Adding tinker-from-docs...
+✖ Failed to add tinker-from-docs: Skill not found: "tinker-from-docs". Expected a shortcut name, GitHub URL, or local path.
+  SKIP: Shortcut not available in registry
+
+TEST: Local vs Global installation
+-----------------------------------
+- Adding /Users/bmo/skills/cli/test/fixtures/sample-skill...
+✔ Added sample-skill
+
+Added sample-skill to Claude Code (local)
+(use --global to install globally)
+  PASS: Directory exists: .claude/skills/sample-skill
+  Local installation verified
+- Adding /Users/bmo/skills/cli/test/fixtures/multi-skills/skill-one...
+✔ Added skill-one
+
+Added skill-one to Claude Code (global)
+  PASS: Directory exists: /var/folders/64/t_nm43xn2mx3jnxm5pfyxrd80000gn/T/tmp.UUle90HZhY/.claude/skills/skill-one
+  Global installation verified
+  PASS: Directory exists: .claude/skills/sample-skill
+  PASS: Directory does not exist: .claude/skills/skill-one
+  PASS: Directory exists: /var/folders/64/t_nm43xn2mx3jnxm5pfyxrd80000gn/T/tmp.UUle90HZhY/.claude/skills/skill-one
+  PASS: Directory does not exist: /var/folders/64/t_nm43xn2mx3jnxm5pfyxrd80000gn/T/tmp.UUle90HZhY/.claude/skills/sample-skill
+
+TEST: Multi-agent installation (--claude --codex)
+--------------------------------------------------
+- Adding /Users/bmo/skills/cli/test/fixtures/sample-skill...
+✔ Added sample-skill
+
+Added sample-skill to Claude Code and Codex (local)
+(use --global to install globally)
+  PASS: Directory exists: .claude/skills/sample-skill
+  PASS: Directory exists: .codex/skills/sample-skill
+
+TEST: Single agent flag (--gemini only)
+----------------------------------------
+- Adding /Users/bmo/skills/cli/test/fixtures/sample-skill...
+✔ Added sample-skill
+
+Added sample-skill to Gemini (local)
+(use --global to install globally)
+  PASS: Directory exists: .gemini/skills/sample-skill
+  PASS: Directory does not exist: .claude/skills/sample-skill
+  PASS: Directory does not exist: .codex/skills/sample-skill
+
+TEST: Remove skill from single agent
+-------------------------------------
+- Adding /Users/bmo/skills/cli/test/fixtures/sample-skill...
+✔ Added sample-skill
+
+Added sample-skill to Claude Code (local)
+(use --global to install globally)
+  PASS: Directory exists: .claude/skills/sample-skill
+- Removing sample-skill...
+✔ Removed sample-skill from Claude Code
+  PASS: Directory does not exist: .claude/skills/sample-skill
+
+TEST: Remove skill from multiple agents
+----------------------------------------
+- Adding /Users/bmo/skills/cli/test/fixtures/sample-skill...
+✔ Added sample-skill
+
+Added sample-skill to Claude Code and Codex (local)
+(use --global to install globally)
+  PASS: Directory exists: .claude/skills/sample-skill
+  PASS: Directory exists: .codex/skills/sample-skill
+- Removing sample-skill...
+✔ Removed sample-skill from Claude Code and Codex
+  PASS: Directory does not exist: .claude/skills/sample-skill
+  PASS: Directory does not exist: .codex/skills/sample-skill
+
+============================================
+All add-remove tests passed!
+============================================