@plosson/agentio 0.1.17 → 0.1.20

package/README.md

@@ -67,10 +67,11 @@ Download from [GitHub Releases](https://github.com/plosson/agentio/releases/late
 
 | Service | Status | Commands |
 |---------|--------|----------|
-| Gmail | Available | `list`, `get`, `search`, `send`, `reply`, `archive`, `mark` |
+| Gmail | Available | `list`, `get`, `search`, `send`, `reply`, `archive`, `mark`, `attachment`, `export` |
 | Telegram | Available | `send` |
-| Slack | Planned | - |
-| JIRA | Planned | - |
+| Google Chat | Available | `send`, `list`, `get` |
+| Slack | Available | `send` |
+| JIRA | Available | `projects`, `search`, `get`, `comment`, `transitions`, `transition` |
 | Linear | Planned | - |
 
 ## Usage
@@ -95,6 +96,14 @@ agentio gmail send --to user@example.com --subject "Hello" --body "Message body"
 
 # Or pipe content
 echo "Message body" | agentio gmail send --to user@example.com --subject "Hello"
+
+# Download attachments
+agentio gmail attachment <message-id>
+agentio gmail attachment <message-id> --name "document.pdf" --output ./downloads
+
+# Export email as PDF
+agentio gmail export <message-id>
+agentio gmail export <message-id> --output email.pdf
 ```
 
 ### Telegram
@@ -110,6 +119,64 @@ agentio telegram send "Hello from agentio!"
 agentio telegram send --parse-mode markdown "**Bold** and _italic_"
 ```
 
+### Google Chat
+
+```bash
+# Set up profile (webhook or OAuth)
+agentio gchat profile add
+
+# Send message via webhook
+agentio gchat send "Hello from agentio!"
+
+# Send with JSON payload for rich messages
+agentio gchat send --json message.json
+
+# List messages (OAuth profiles only)
+agentio gchat list --space <space-id>
+
+# Get a specific message (OAuth profiles only)
+agentio gchat get <message-id> --space <space-id>
+```
+
+### Slack
+
+```bash
+# Set up webhook profile
+agentio slack profile add
+
+# Send message
+agentio slack send "Hello from agentio!"
+
+# Send Block Kit message from JSON file
+agentio slack send --json blocks.json
+```
+
+### JIRA
+
+```bash
+# Authenticate with OAuth
+agentio jira profile add
+
+# List projects
+agentio jira projects
+
+# Search issues
+agentio jira search --project MYPROJ --status "In Progress"
+agentio jira search --jql "assignee = currentUser() AND status != Done"
+
+# Get issue details
+agentio jira get PROJ-123
+
+# Add a comment
+agentio jira comment PROJ-123 "This is my comment"
+
+# View available transitions
+agentio jira transitions PROJ-123
+
+# Transition an issue
+agentio jira transition PROJ-123 <transition-id>
+```
+
 ## Multi-Profile Support
 
 Each service supports multiple named profiles:
@@ -141,6 +208,29 @@ agentio provides a plugin for [Claude Code](https://claude.com/claude-code) with
 
 Once installed, Claude Code can use the agentio CLI skills to help you manage emails, send Telegram messages, and more.
 
+### Install Skills Directly
+
+You can also install skills directly without the plugin system:
+
+```bash
+# List available skills
+agentio skill list
+
+# Install all skills to current directory
+agentio skill install
+
+# Install a specific skill
+agentio skill install agentio-gmail
+
+# Install to a specific directory
+agentio skill install -d ~/myproject
+
+# Skip confirmation prompts
+agentio skill install -y
+```
+
+Skills are installed to `.claude/skills/` in the target directory.
+
 ## Design
 
 agentio is designed for LLM consumption:
@@ -157,6 +247,27 @@ Configuration is stored in `~/.config/agentio/`:
 - `config.json` - Profile names and defaults
 - `tokens.enc` - Encrypted credentials (AES-256-GCM)
 
+### Export/Import
+
+Transfer configuration between machines:
+
+```bash
+# Export configuration (generates encryption key)
+agentio config export
+
+# Export with custom output file
+agentio config export --output backup.config
+
+# Import on another machine
+agentio config import agentio.config --key <encryption-key>
+
+# Or use environment variable
+AGENTIO_KEY=<key> agentio config import agentio.config
+
+# Merge with existing config instead of replacing
+agentio config import agentio.config --key <key> --merge
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.1.17",
+  "version": "0.1.20",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",

package/src/commands/claude.ts

@@ -0,0 +1,179 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { CliError, handleError } from '../utils/errors';
+import {
+  loadAgentioJson,
+  agentioJsonExists,
+  listPlugins,
+  removePlugin,
+  getPlugin,
+} from '../services/claude-plugin/agentio-json';
+import {
+  installPlugin,
+  removePluginFiles,
+} from '../services/claude-plugin/installer';
+import type { InstalledComponent } from '../types/claude-plugin';
+
+export function registerClaudeCommands(program: Command): void {
+  const claude = program
+    .command('claude')
+    .description('Claude Code plugin operations');
+
+  const plugin = claude.command('plugin').description('Manage Claude Code plugins');
+
+  plugin
+    .command('install')
+    .description('Install plugin(s) from GitHub or agentio.json')
+    .argument('[source]', 'GitHub URL or owner/repo (omit to install from agentio.json)')
+    .option('--skills', 'Install only skills')
+    .option('--commands', 'Install only commands')
+    .option('--hooks', 'Install only hooks')
+    .option('-f, --force', 'Force reinstall if already exists')
+    .option('-d, --dir <path>', 'Target directory (default: current directory)')
+    .action(async (source, options) => {
+      try {
+        const targetDir = options.dir ? path.resolve(options.dir) : process.cwd();
+
+        if (!fs.existsSync(targetDir)) {
+          throw new CliError('INVALID_PARAMS', `Directory does not exist: ${targetDir}`);
+        }
+
+        if (source) {
+          // Install specific plugin from source
+          console.error(`Installing plugin from: ${source}`);
+          console.error(`Target: ${path.join(targetDir, '.claude')}`);
+
+          const result = await installPlugin(source, {
+            skills: options.skills,
+            commands: options.commands,
+            hooks: options.hooks,
+            force: options.force,
+            targetDir,
+          });
+
+          console.log(`\nInstalled: ${result.manifest.name} v${result.manifest.version}`);
+          if (result.installed.length > 0) {
+            console.log(`Components: ${result.installed.length}`);
+            for (const comp of result.installed) {
+              console.log(`  ${comp.type}/${comp.name}`);
+            }
+          }
+        } else {
+          // Install all plugins from agentio.json
+          if (!agentioJsonExists(targetDir)) {
+            throw new CliError(
+              'NOT_FOUND',
+              'No agentio.json found',
+              'Run: agentio claude plugin install <source> to install a plugin'
+            );
+          }
+
+          const agentioJson = loadAgentioJson(targetDir);
+          const plugins = Object.entries(agentioJson.plugins);
+
+          if (plugins.length === 0) {
+            console.log('No plugins defined in agentio.json');
+            return;
+          }
+
+          console.error(`Installing ${plugins.length} plugin(s) from agentio.json...`);
+          console.error(`Target: ${path.join(targetDir, '.claude')}`);
+
+          let installed = 0;
+          for (const [name, entry] of plugins) {
+            console.error(`\nInstalling ${name}...`);
+
+            // Determine component flags based on entry.components
+            const installOptions = {
+              skills:
+                !entry.components || entry.components.includes('skills'),
+              commands:
+                !entry.components || entry.components.includes('commands'),
+              hooks: !entry.components || entry.components.includes('hooks'),
+              force: options.force,
+              targetDir,
+            };
+
+            try {
+              const result = await installPlugin(entry.source, installOptions);
+              console.log(`  Installed: ${result.manifest.name} v${result.manifest.version}`);
+              installed++;
+            } catch (error) {
+              console.error(`  Failed to install ${name}: ${error}`);
+            }
+          }
+
+          console.log(`\nInstalled ${installed} of ${plugins.length} plugin(s)`);
+        }
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  plugin
+    .command('list')
+    .description('List plugins from agentio.json')
+    .option('-d, --dir <path>', 'Directory with agentio.json (default: current directory)')
+    .action(async (options) => {
+      try {
+        const targetDir = options.dir ? path.resolve(options.dir) : process.cwd();
+
+        const plugins = listPlugins(targetDir);
+
+        if (plugins.length === 0) {
+          console.log('No plugins in agentio.json');
+          return;
+        }
+
+        console.log(`Plugins (${plugins.length}):\n`);
+        for (const { name, entry } of plugins) {
+          console.log(`${name} v${entry.version}`);
+          console.log(`  Source: ${entry.source}`);
+          if (entry.components) {
+            console.log(`  Components: ${entry.components.join(', ')}`);
+          }
+          console.log('');
+        }
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  plugin
+    .command('remove')
+    .description('Remove an installed plugin')
+    .argument('<name>', 'Plugin name')
+    .option('-d, --dir <path>', 'Directory with agentio.json (default: current directory)')
+    .action(async (name, options) => {
+      try {
+        const targetDir = options.dir ? path.resolve(options.dir) : process.cwd();
+
+        const entry = getPlugin(targetDir, name);
+        if (!entry) {
+          throw new CliError('NOT_FOUND', `Plugin '${name}' not found in agentio.json`);
+        }
+
+        console.error(`Removing plugin: ${name}...`);
+
+        // Use stored installed components (no network calls needed)
+        const components: InstalledComponent[] = entry.installedComponents || [];
+
+        // Remove files
+        removePluginFiles(targetDir, components);
+
+        // Update agentio.json
+        removePlugin(targetDir, name);
+
+        console.log(`Removed: ${name}`);
+        if (components.length > 0) {
+          console.log(`Removed components: ${components.length}`);
+          for (const comp of components) {
+            console.log(`  ${comp.type}/${comp.name}`);
+          }
+        }
+      } catch (error) {
+        handleError(error);
+      }
+    });
+}

package/src/index.ts

@@ -7,6 +7,7 @@ import { registerJiraCommands } from './commands/jira';
 import { registerSlackCommands } from './commands/slack';
 import { registerUpdateCommand } from './commands/update';
 import { registerConfigCommands } from './commands/config';
+import { registerClaudeCommands } from './commands/claude';
 
 declare const BUILD_VERSION: string | undefined;
 
@@ -32,5 +33,6 @@ registerJiraCommands(program);
 registerSlackCommands(program);
 registerUpdateCommand(program);
 registerConfigCommands(program);
+registerClaudeCommands(program);
 
 program.parse();

package/src/services/claude-plugin/agentio-json.ts

@@ -0,0 +1,103 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { AgentioJson, AgentioPluginEntry } from '../../types/claude-plugin';
+
+const AGENTIO_JSON_FILE = 'agentio.json';
+
+/**
+ * Get the path to agentio.json in the given directory.
+ */
+function getAgentioJsonPath(dir: string): string {
+  return path.join(dir, AGENTIO_JSON_FILE);
+}
+
+/**
+ * Load agentio.json from the given directory.
+ * Returns empty structure if file doesn't exist.
+ */
+export function loadAgentioJson(dir: string): AgentioJson {
+  const filePath = getAgentioJsonPath(dir);
+
+  if (!fs.existsSync(filePath)) {
+    return { plugins: {} };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const data = JSON.parse(content) as AgentioJson;
+
+  // Ensure plugins object exists
+  if (!data.plugins) {
+    data.plugins = {};
+  }
+
+  return data;
+}
+
+/**
+ * Save agentio.json to the given directory.
+ */
+export function saveAgentioJson(dir: string, data: AgentioJson): void {
+  const filePath = getAgentioJsonPath(dir);
+  const content = JSON.stringify(data, null, 2) + '\n';
+  fs.writeFileSync(filePath, content);
+}
+
+/**
+ * Check if agentio.json exists in the given directory.
+ */
+export function agentioJsonExists(dir: string): boolean {
+  return fs.existsSync(getAgentioJsonPath(dir));
+}
+
+/**
+ * Add or update a plugin entry in agentio.json.
+ */
+export function addPlugin(
+  dir: string,
+  name: string,
+  entry: AgentioPluginEntry
+): void {
+  const data = loadAgentioJson(dir);
+  data.plugins[name] = entry;
+  saveAgentioJson(dir, data);
+}
+
+/**
+ * Remove a plugin entry from agentio.json.
+ * Returns true if plugin was found and removed.
+ */
+export function removePlugin(dir: string, name: string): boolean {
+  const data = loadAgentioJson(dir);
+
+  if (!data.plugins[name]) {
+    return false;
+  }
+
+  delete data.plugins[name];
+  saveAgentioJson(dir, data);
+  return true;
+}
+
+/**
+ * Get a plugin entry from agentio.json.
+ */
+export function getPlugin(
+  dir: string,
+  name: string
+): AgentioPluginEntry | undefined {
+  const data = loadAgentioJson(dir);
+  return data.plugins[name];
+}
+
+/**
+ * List all plugins in agentio.json.
+ */
+export function listPlugins(
+  dir: string
+): Array<{ name: string; entry: AgentioPluginEntry }> {
+  const data = loadAgentioJson(dir);
+  return Object.entries(data.plugins).map(([name, entry]) => ({
+    name,
+    entry,
+  }));
+}

package/src/services/claude-plugin/installer.ts

@@ -0,0 +1,285 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { tmpdir } from 'os';
+import { CliError } from '../../utils/errors';
+import type {
+  ParsedSource,
+  PluginManifest,
+  DiscoveredComponents,
+  PluginInstallOptions,
+  InstalledComponent,
+  InstallResult,
+  ComponentType,
+} from '../../types/claude-plugin';
+import { parseSource, buildGitCloneUrl } from './source-parser';
+import { addPlugin } from './agentio-json';
+
+/**
+ * Clone a repository to a temporary directory.
+ */
+function cloneRepo(parsed: ParsedSource): string {
+  const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'agentio-plugin-'));
+  const cloneUrl = buildGitCloneUrl(parsed);
+
+  let cmd = `git clone --depth 1`;
+  if (parsed.branch) {
+    cmd += ` -b ${parsed.branch}`;
+  }
+  cmd += ` "${cloneUrl}" "${tempDir}"`;
+
+  try {
+    execSync(cmd, { stdio: 'pipe' });
+  } catch {
+    // Clean up temp dir on clone failure
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    throw new CliError(
+      'API_ERROR',
+      `Failed to clone repository: ${parsed.owner}/${parsed.repo}`,
+      'Check the repository URL and your network connection'
+    );
+  }
+
+  return tempDir;
+}
+
+/**
+ * Clean up a temporary directory.
+ */
+function cleanupTempDir(tempDir: string): void {
+  fs.rmSync(tempDir, { recursive: true, force: true });
+}
+
+/**
+ * Read the plugin manifest from a cloned repository.
+ */
+function readPluginManifest(
+  repoDir: string,
+  parsed: ParsedSource
+): PluginManifest {
+  const basePath = parsed.path ? path.join(repoDir, parsed.path) : repoDir;
+  const manifestPath = path.join(basePath, '.claude-plugin', 'plugin.json');
+
+  if (!fs.existsSync(manifestPath)) {
+    throw new CliError(
+      'NOT_FOUND',
+      'Plugin manifest not found',
+      'Ensure .claude-plugin/plugin.json exists in the plugin root'
+    );
+  }
+
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf-8');
+    const manifest = JSON.parse(content) as PluginManifest;
+
+    if (!manifest.name || !manifest.version) {
+      throw new CliError(
+        'INVALID_PARAMS',
+        'Invalid plugin manifest: missing name or version'
+      );
+    }
+
+    return manifest;
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    if (error instanceof SyntaxError) {
+      throw new CliError('INVALID_PARAMS', 'Invalid plugin manifest JSON');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Discover available components in a cloned repository.
+ */
+function discoverComponents(
+  repoDir: string,
+  parsed: ParsedSource
+): DiscoveredComponents {
+  const basePath = parsed.path ? path.join(repoDir, parsed.path) : repoDir;
+  const result: DiscoveredComponents = {
+    skills: [],
+    commands: [],
+    hooks: [],
+  };
+
+  const componentTypes: ComponentType[] = ['skills', 'commands', 'hooks'];
+
+  for (const type of componentTypes) {
+    const typePath = path.join(basePath, type);
+    if (fs.existsSync(typePath)) {
+      const entries = fs.readdirSync(typePath, { withFileTypes: true });
+      result[type] = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Copy a component from the cloned repository to the target directory.
+ */
+function copyComponent(
+  repoDir: string,
+  parsed: ParsedSource,
+  componentType: ComponentType,
+  componentName: string,
+  targetDir: string
+): void {
+  const basePath = parsed.path ? path.join(repoDir, parsed.path) : repoDir;
+  const srcPath = path.join(basePath, componentType, componentName);
+  const destPath = path.join(targetDir, '.claude', componentType, componentName);
+
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  fs.cpSync(srcPath, destPath, { recursive: true });
+}
+
+/**
+ * Determine which components to install based on options.
+ */
+function determineComponentsToInstall(
+  options: PluginInstallOptions,
+  discovered: DiscoveredComponents
+): DiscoveredComponents {
+  // If no specific flags, install all
+  const installAll = !options.skills && !options.commands && !options.hooks;
+
+  return {
+    skills: installAll || options.skills ? discovered.skills : [],
+    commands: installAll || options.commands ? discovered.commands : [],
+    hooks: installAll || options.hooks ? discovered.hooks : [],
+  };
+}
+
+/**
+ * Get the component types array for agentio.json based on what was installed.
+ */
+function getInstalledComponentTypes(
+  options: PluginInstallOptions
+): ComponentType[] | undefined {
+  const installAll = !options.skills && !options.commands && !options.hooks;
+  if (installAll) return undefined; // Default: all
+
+  const types: ComponentType[] = [];
+  if (options.skills) types.push('skills');
+  if (options.commands) types.push('commands');
+  if (options.hooks) types.push('hooks');
+  return types;
+}
+
+/**
+ * Install a plugin from a source.
+ */
+export async function installPlugin(
+  source: string,
+  options: PluginInstallOptions
+): Promise<InstallResult> {
+  const parsed = parseSource(source);
+
+  // Clone repo to temp directory
+  const repoDir = cloneRepo(parsed);
+
+  try {
+    // Read manifest from cloned repo
+    const manifest = readPluginManifest(repoDir, parsed);
+
+    // Discover available components
+    const discovered = discoverComponents(repoDir, parsed);
+
+    // Determine what to install
+    const toInstall = determineComponentsToInstall(options, discovered);
+
+    const targetDir = options.targetDir || process.cwd();
+    const installed: InstalledComponent[] = [];
+
+    // Install skills
+    for (const skillName of toInstall.skills) {
+      const destPath = path.join(targetDir, '.claude', 'skills', skillName);
+
+      if (fs.existsSync(destPath)) {
+        if (!options.force) {
+          console.error(`  Skipping existing skill: ${skillName}`);
+          continue;
+        }
+        fs.rmSync(destPath, { recursive: true });
+      }
+
+      copyComponent(repoDir, parsed, 'skills', skillName, targetDir);
+      installed.push({ name: skillName, type: 'skills', path: destPath });
+      console.error(`  Installed skill: ${skillName}`);
+    }
+
+    // Install commands
+    for (const cmdName of toInstall.commands) {
+      const destPath = path.join(targetDir, '.claude', 'commands', cmdName);
+
+      if (fs.existsSync(destPath)) {
+        if (!options.force) {
+          console.error(`  Skipping existing command: ${cmdName}`);
+          continue;
+        }
+        fs.rmSync(destPath, { recursive: true });
+      }
+
+      copyComponent(repoDir, parsed, 'commands', cmdName, targetDir);
+      installed.push({ name: cmdName, type: 'commands', path: destPath });
+      console.error(`  Installed command: ${cmdName}`);
+    }
+
+    // Install hooks
+    for (const hookName of toInstall.hooks) {
+      const destPath = path.join(targetDir, '.claude', 'hooks', hookName);
+
+      if (fs.existsSync(destPath)) {
+        if (!options.force) {
+          console.error(`  Skipping existing hook: ${hookName}`);
+          continue;
+        }
+        fs.rmSync(destPath, { recursive: true });
+      }
+
+      copyComponent(repoDir, parsed, 'hooks', hookName, targetDir);
+      installed.push({ name: hookName, type: 'hooks', path: destPath });
+      console.error(`  Installed hook: ${hookName}`);
+    }
+
+    // Update agentio.json
+    addPlugin(targetDir, manifest.name, {
+      source: source,
+      version: manifest.version,
+      components: getInstalledComponentTypes(options),
+      installedComponents: installed,
+    });
+
+    return {
+      success: true,
+      manifest,
+      installed,
+    };
+  } finally {
+    // Always cleanup temp directory
+    cleanupTempDir(repoDir);
+  }
+}
+
+/**
+ * Remove installed components for a plugin.
+ */
+export function removePluginFiles(
+  targetDir: string,
+  components: InstalledComponent[]
+): void {
+  for (const comp of components) {
+    const compPath = path.join(
+      targetDir,
+      '.claude',
+      comp.type,
+      comp.name
+    );
+    if (fs.existsSync(compPath)) {
+      fs.rmSync(compPath, { recursive: true });
+    }
+  }
+}

package/src/services/claude-plugin/source-parser.ts

@@ -0,0 +1,114 @@
+import { CliError } from '../../utils/errors';
+import type { ParsedSource } from '../../types/claude-plugin';
+
+/**
+ * Parse various GitHub source formats into a normalized ParsedSource.
+ *
+ * Supported formats:
+ * - https://github.com/owner/repo/tree/branch/path
+ * - git@github.com:owner/repo.git
+ * - https://github.com/owner/repo.git
+ * - owner/repo
+ * - owner/repo/path/to/plugin
+ */
+export function parseSource(source: string): ParsedSource {
+  // Full GitHub tree URL: https://github.com/owner/repo/tree/branch/path
+  if (source.includes('github.com') && source.includes('/tree/')) {
+    return parseGitHubTreeUrl(source);
+  }
+
+  // SSH URL: git@github.com:owner/repo.git
+  if (source.startsWith('git@')) {
+    return parseSshUrl(source);
+  }
+
+  // HTTPS clone URL: https://github.com/owner/repo.git
+  if (source.includes('github.com') && source.endsWith('.git')) {
+    return parseHttpsCloneUrl(source);
+  }
+
+  // Plain GitHub URL without tree: https://github.com/owner/repo or https://github.com/owner/repo/path
+  if (source.includes('github.com')) {
+    return parseGitHubUrl(source);
+  }
+
+  // Short form: owner/repo or owner/repo/path
+  return parseShortForm(source);
+}
+
+function parseGitHubTreeUrl(url: string): ParsedSource {
+  // https://github.com/owner/repo/tree/branch/path/to/plugin
+  const match = url.match(
+    /github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)(?:\/(.+))?/
+  );
+  if (!match) {
+    throw new CliError('INVALID_PARAMS', `Invalid GitHub tree URL: ${url}`);
+  }
+  return {
+    owner: match[1],
+    repo: match[2],
+    branch: match[3],
+    path: match[4] || undefined,
+  };
+}
+
+function parseSshUrl(url: string): ParsedSource {
+  // git@github.com:owner/repo.git
+  const match = url.match(/git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (!match) {
+    throw new CliError('INVALID_PARAMS', `Invalid SSH URL: ${url}`);
+  }
+  return {
+    owner: match[1],
+    repo: match[2],
+  };
+}
+
+function parseHttpsCloneUrl(url: string): ParsedSource {
+  // https://github.com/owner/repo.git
+  const match = url.match(/github\.com\/([^/]+)\/([^/]+?)\.git$/);
+  if (!match) {
+    throw new CliError('INVALID_PARAMS', `Invalid HTTPS clone URL: ${url}`);
+  }
+  return {
+    owner: match[1],
+    repo: match[2],
+  };
+}
+
+function parseGitHubUrl(url: string): ParsedSource {
+  // https://github.com/owner/repo or https://github.com/owner/repo/path
+  const match = url.match(/github\.com\/([^/]+)\/([^/]+?)(?:\/(.+))?$/);
+  if (!match) {
+    throw new CliError('INVALID_PARAMS', `Invalid GitHub URL: ${url}`);
+  }
+  return {
+    owner: match[1],
+    repo: match[2],
+    path: match[3] || undefined,
+  };
+}
+
+function parseShortForm(source: string): ParsedSource {
+  // owner/repo or owner/repo/path/to/plugin
+  const parts = source.split('/');
+  if (parts.length < 2) {
+    throw new CliError(
+      'INVALID_PARAMS',
+      `Invalid source format: ${source}`,
+      'Use owner/repo or a GitHub URL'
+    );
+  }
+  return {
+    owner: parts[0],
+    repo: parts[1],
+    path: parts.length > 2 ? parts.slice(2).join('/') : undefined,
+  };
+}
+
+/**
+ * Build a git clone URL from parsed source.
+ */
+export function buildGitCloneUrl(parsed: ParsedSource): string {
+  return `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+}

package/src/types/claude-plugin.ts

@@ -0,0 +1,62 @@
+// Source URL parsing result
+export interface ParsedSource {
+  owner: string;
+  repo: string;
+  branch?: string; // undefined = default branch
+  path?: string; // path within repo to plugin root
+}
+
+// Plugin manifest (.claude-plugin/plugin.json)
+export interface PluginManifest {
+  name: string;
+  version: string;
+  description?: string;
+}
+
+// Component types that can be installed
+export type ComponentType = 'skills' | 'commands' | 'hooks';
+
+// Discovered components from filesystem
+export interface DiscoveredComponents {
+  skills: string[];
+  commands: string[];
+  hooks: string[];
+}
+
+// Installation options
+export interface PluginInstallOptions {
+  skills?: boolean;
+  commands?: boolean;
+  hooks?: boolean;
+  force?: boolean;
+  targetDir?: string;
+}
+
+// Single installed component record
+export interface InstalledComponent {
+  name: string;
+  type: ComponentType;
+  path: string;
+}
+
+// Plugin entry in agentio.json
+export interface AgentioPluginEntry {
+  source: string;
+  version: string;
+  components?: ComponentType[];
+  installedComponents: InstalledComponent[];
+}
+
+// agentio.json structure
+export interface AgentioJson {
+  plugins: {
+    [pluginName: string]: AgentioPluginEntry;
+  };
+}
+
+// Installation result
+export interface InstallResult {
+  success: boolean;
+  manifest: PluginManifest;
+  installed: InstalledComponent[];
+}