jettypod 4.4.118 → 4.4.121

package/crates/jettypod-core/src/skills.rs

@@ -0,0 +1,556 @@
+//! Skills file synchronization.
+//!
+//! Copies skill definition files from the project's skills directory
+//! into Claude Code's settings directory. Two modes:
+//!
+//! - **Full sync** (`sync_skills`): Used by CLI `jettypod init`. Creates a
+//!   timestamped backup of existing skills, copies fresh from source, and
+//!   restores the backup on failure.
+//!
+//! - **Optimized sync** (`sync_skills_optimized`): Used by the desktop app on
+//!   launch. Skips files where the destination is already newer or same-size,
+//!   reducing I/O on repeated launches.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use crate::{CoreError, Result};
+
+/// Options for skill synchronization.
+pub struct SyncOptions {
+    /// Directory containing source skill templates (e.g. `./skills-templates`).
+    pub source_dir: PathBuf,
+    /// Destination `.claude/skills` directory.
+    pub dest_dir: PathBuf,
+}
+
+/// Full sync: backup existing skills, copy fresh from source, restore on failure.
+///
+/// Used by `jettypod init`. This always overwrites destination files.
+pub fn sync_skills(opts: &SyncOptions) -> Result<SyncResult> {
+    let source = &opts.source_dir;
+    let dest = &opts.dest_dir;
+
+    // Validate source exists and is non-empty.
+    if !source.exists() {
+        return Ok(SyncResult {
+            files_copied: 0,
+            files_skipped: 0,
+            backup_path: None,
+            restored: false,
+            warning: Some("Source skills directory does not exist".into()),
+        });
+    }
+
+    let source_entries = read_dir_entries(source)?;
+    if source_entries.is_empty() {
+        return Ok(SyncResult {
+            files_copied: 0,
+            files_skipped: 0,
+            backup_path: None,
+            restored: false,
+            warning: Some("Source skills directory is empty".into()),
+        });
+    }
+
+    // Create backup if destination already exists.
+    let backup_path = if dest.exists() {
+        Some(create_backup(dest)?)
+    } else {
+        None
+    };
+
+    // Attempt the copy.
+    match do_full_copy(source, dest) {
+        Ok(count) => Ok(SyncResult {
+            files_copied: count,
+            files_skipped: 0,
+            backup_path,
+            restored: false,
+            warning: None,
+        }),
+        Err(e) => {
+            // Restore backup on failure.
+            if let Some(ref bp) = backup_path {
+                if bp.exists() {
+                    // Safety: only delete dest if it contains ".claude".
+                    let resolved = dest.canonicalize().unwrap_or_else(|_| dest.to_path_buf());
+                    if resolved.to_string_lossy().contains(".claude") {
+                        let _ = fs::remove_dir_all(dest);
+                    }
+                    let _ = fs::rename(bp, dest);
+                    return Err(CoreError::Skills(format!(
+                        "Sync failed, backup restored: {e}"
+                    )));
+                }
+            }
+            Err(CoreError::Skills(format!("Sync failed: {e}")))
+        }
+    }
+}
+
+/// Optimized sync: skip files where dest is newer or same size.
+///
+/// Used by the desktop app on every launch. Reduces I/O when skills
+/// haven't changed.
+pub fn sync_skills_optimized(opts: &SyncOptions) -> Result<SyncResult> {
+    let source = &opts.source_dir;
+    let dest = &opts.dest_dir;
+
+    if !source.exists() {
+        return Ok(SyncResult {
+            files_copied: 0,
+            files_skipped: 0,
+            backup_path: None,
+            restored: false,
+            warning: Some("Source skills directory does not exist".into()),
+        });
+    }
+
+    let source_entries = read_dir_entries(source)?;
+    if source_entries.is_empty() {
+        return Ok(SyncResult {
+            files_copied: 0,
+            files_skipped: 0,
+            backup_path: None,
+            restored: false,
+            warning: Some("Source skills directory is empty".into()),
+        });
+    }
+
+    fs::create_dir_all(dest).map_err(|e| {
+        CoreError::Skills(format!("Failed to create dest dir {}: {e}", dest.display()))
+    })?;
+
+    let (copied, skipped) = copy_dir_optimized(source, dest)?;
+
+    Ok(SyncResult {
+        files_copied: copied,
+        files_skipped: skipped,
+        backup_path: None,
+        restored: false,
+        warning: None,
+    })
+}
+
+/// Result of a sync operation.
+#[derive(Debug)]
+pub struct SyncResult {
+    pub files_copied: usize,
+    pub files_skipped: usize,
+    pub backup_path: Option<PathBuf>,
+    pub restored: bool,
+    pub warning: Option<String>,
+}
+
+/// Resolve the default source skills directory relative to project root.
+pub fn default_source_dir(project_root: &Path) -> PathBuf {
+    if let Ok(override_dir) = std::env::var("JETTYPOD_SKILLS_SOURCE_DIR") {
+        PathBuf::from(override_dir)
+    } else {
+        project_root.join("skills-templates")
+    }
+}
+
+/// Resolve the default destination skills directory relative to project root.
+pub fn default_dest_dir(project_root: &Path) -> PathBuf {
+    project_root.join(".claude").join("skills")
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/// Read directory entries, returning an empty vec if the dir doesn't exist.
+fn read_dir_entries(dir: &Path) -> Result<Vec<fs::DirEntry>> {
+    match fs::read_dir(dir) {
+        Ok(rd) => {
+            let mut entries = Vec::new();
+            for entry in rd {
+                entries.push(entry.map_err(|e| {
+                    CoreError::Skills(format!("Failed to read entry in {}: {e}", dir.display()))
+                })?);
+            }
+            Ok(entries)
+        }
+        Err(e) => Err(CoreError::Skills(format!(
+            "Failed to read directory {}: {e}",
+            dir.display()
+        ))),
+    }
+}
+
+/// Create a timestamped backup of the skills directory.
+///
+/// Naming: `skills.backup-2026-02-22T15-33-45-123Z` with counter if collision.
+fn create_backup(skills_dir: &Path) -> Result<PathBuf> {
+    let parent = skills_dir
+        .parent()
+        .ok_or_else(|| CoreError::Skills("Skills dir has no parent".into()))?;
+
+    let now = chrono::Utc::now();
+    let ts = now
+        .format("%Y-%m-%dT%H-%M-%S-%3fZ")
+        .to_string();
+    let base_name = format!("skills.backup-{ts}");
+
+    // Handle timestamp collisions with counter.
+    let mut backup_name = base_name.clone();
+    let mut counter = 0u32;
+    loop {
+        let candidate = parent.join(&backup_name);
+        if !candidate.exists() {
+            break;
+        }
+        counter += 1;
+        backup_name = format!("{base_name}-{counter}");
+    }
+
+    let backup_path = parent.join(&backup_name);
+    fs::rename(skills_dir, &backup_path).map_err(|e| {
+        CoreError::Skills(format!(
+            "Failed to create backup at {}: {e}",
+            backup_path.display()
+        ))
+    })?;
+
+    Ok(backup_path)
+}
+
+/// Recursively copy `src` into `dest`, overwriting all files.
+/// Returns the number of files copied.
+fn do_full_copy(src: &Path, dest: &Path) -> Result<usize> {
+    fs::create_dir_all(dest).map_err(|e| {
+        CoreError::Skills(format!(
+            "Failed to create directory {}: {e}",
+            dest.display()
+        ))
+    })?;
+
+    let mut count = 0;
+    for entry in read_dir_entries(src)? {
+        let path = entry.path();
+        let name = entry.file_name();
+        let target = dest.join(&name);
+
+        if path.is_dir() {
+            count += do_full_copy(&path, &target)?;
+        } else {
+            fs::copy(&path, &target).map_err(|e| {
+                CoreError::Skills(format!(
+                    "Failed to copy {} -> {}: {e}",
+                    path.display(),
+                    target.display()
+                ))
+            })?;
+            count += 1;
+        }
+    }
+
+    Ok(count)
+}
+
+/// Recursively copy `src` into `dest`, skipping files where dest is newer
+/// or same size. Returns (copied, skipped) counts.
+fn copy_dir_optimized(src: &Path, dest: &Path) -> Result<(usize, usize)> {
+    fs::create_dir_all(dest).map_err(|e| {
+        CoreError::Skills(format!(
+            "Failed to create directory {}: {e}",
+            dest.display()
+        ))
+    })?;
+
+    let mut copied = 0;
+    let mut skipped = 0;
+
+    for entry in read_dir_entries(src)? {
+        let path = entry.path();
+        let name = entry.file_name();
+        let target = dest.join(&name);
+
+        if path.is_dir() {
+            let (c, s) = copy_dir_optimized(&path, &target)?;
+            copied += c;
+            skipped += s;
+        } else {
+            if should_skip_copy(&path, &target) {
+                skipped += 1;
+            } else {
+                fs::copy(&path, &target).map_err(|e| {
+                    CoreError::Skills(format!(
+                        "Failed to copy {} -> {}: {e}",
+                        path.display(),
+                        target.display()
+                    ))
+                })?;
+                copied += 1;
+            }
+        }
+    }
+
+    Ok((copied, skipped))
+}
+
+/// Check if we can skip copying a file (dest is newer/equal mtime AND same size).
+fn should_skip_copy(src: &Path, dest: &Path) -> bool {
+    let dest_meta = match fs::metadata(dest) {
+        Ok(m) => m,
+        Err(_) => return false, // dest doesn't exist, must copy
+    };
+
+    let src_meta = match fs::metadata(src) {
+        Ok(m) => m,
+        Err(_) => return false, // can't read src, try to copy anyway
+    };
+
+    let src_mtime = src_meta
+        .modified()
+        .unwrap_or(SystemTime::UNIX_EPOCH);
+    let dest_mtime = dest_meta
+        .modified()
+        .unwrap_or(SystemTime::UNIX_EPOCH);
+
+    // Skip if dest is newer or equal AND same size.
+    dest_mtime >= src_mtime && dest_meta.len() == src_meta.len()
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    fn create_test_skills(dir: &Path) {
+        // Create a couple of skill directories with files.
+        let skill1 = dir.join("request-routing");
+        fs::create_dir_all(&skill1).unwrap();
+        fs::write(skill1.join("SKILL.md"), "# Request Routing\nRoutes requests.").unwrap();
+
+        let skill2 = dir.join("speed-mode");
+        fs::create_dir_all(&skill2).unwrap();
+        fs::write(skill2.join("SKILL.md"), "# Speed Mode\nFast implementation.").unwrap();
+        fs::write(skill2.join("test-runner.js"), "module.exports = {};").unwrap();
+    }
+
+    #[test]
+    fn test_full_sync_copies_all_files() {
+        let tmp = tempfile::tempdir().unwrap();
+        let source = tmp.path().join("skills-templates");
+        let dest = tmp.path().join(".claude").join("skills");
+
+        create_test_skills(&source);
+
+        let result = sync_skills(&SyncOptions {
+            source_dir: source,
+            dest_dir: dest.clone(),
+        })
+        .unwrap();
+
+        assert_eq!(result.files_copied, 3);
+        assert_eq!(result.files_skipped, 0);
+        assert!(result.backup_path.is_none()); // no pre-existing dest
+        assert!(result.warning.is_none());
+
+        // Verify files exist.
+        assert!(dest.join("request-routing/SKILL.md").exists());
+        assert!(dest.join("speed-mode/SKILL.md").exists());
+        assert!(dest.join("speed-mode/test-runner.js").exists());
+    }
+
+    #[test]
+    fn test_full_sync_creates_backup() {
+        let tmp = tempfile::tempdir().unwrap();
+        let source = tmp.path().join("skills-templates");
+        let dest = tmp.path().join(".claude").join("skills");
+
+        // Create initial skills.
+        create_test_skills(&source);
+        fs::create_dir_all(&dest).unwrap();
+        fs::write(dest.join("old-file.txt"), "old content").unwrap();
+
+        let result = sync_skills(&SyncOptions {
+            source_dir: source,
+            dest_dir: dest.clone(),
+        })
+        .unwrap();
+
+        assert!(result.backup_path.is_some());
+        let backup = result.backup_path.unwrap();
+        assert!(backup.exists());
+        assert!(backup.join("old-file.txt").exists());
+
+        // New skills should be in place.
+        assert!(dest.join("request-routing/SKILL.md").exists());
+    }
+
+    #[test]
+    fn test_full_sync_missing_source() {
+        let tmp = tempfile::tempdir().unwrap();
+        let source = tmp.path().join("nonexistent");
+        let dest = tmp.path().join(".claude").join("skills");
+
+        let result = sync_skills(&SyncOptions {
+            source_dir: source,
+            dest_dir: dest,
+        })
+        .unwrap();
+
+        assert_eq!(result.files_copied, 0);
+        assert!(result.warning.is_some());
+    }
+
+    #[test]
+    fn test_full_sync_empty_source() {
+        let tmp = tempfile::tempdir().unwrap();
+        let source = tmp.path().join("empty-skills");
+        let dest = tmp.path().join(".claude").join("skills");
+        fs::create_dir_all(&source).unwrap();
+
+        let result = sync_skills(&SyncOptions {
+            source_dir: source,
+            dest_dir: dest,
+        })
+        .unwrap();
+
+        assert_eq!(result.files_copied, 0);
+        assert!(result.warning.is_some());
+    }
+
+    #[test]
+    fn test_optimized_sync_skips_unchanged_files() {
+        let tmp = tempfile::tempdir().unwrap();
+        let source = tmp.path().join("skills-templates");
+        let dest = tmp.path().join(".claude").join("skills");
+
+        create_test_skills(&source);
+
+        // First sync — copies everything.
+        let r1 = sync_skills_optimized(&SyncOptions {
+            source_dir: source.clone(),
+            dest_dir: dest.clone(),
+        })
+        .unwrap();
+        assert_eq!(r1.files_copied, 3);
+        assert_eq!(r1.files_skipped, 0);
+
+        // Second sync — should skip all (dest has same mtime/size from copy).
+        let r2 = sync_skills_optimized(&SyncOptions {
+            source_dir: source.clone(),
+            dest_dir: dest.clone(),
+        })
+        .unwrap();
+        assert_eq!(r2.files_copied, 0);
+        assert_eq!(r2.files_skipped, 3);
+    }
+
+    #[test]
+    fn test_optimized_sync_copies_modified_files() {
+        let tmp = tempfile::tempdir().unwrap();
+        let source = tmp.path().join("skills-templates");
+        let dest = tmp.path().join(".claude").join("skills");
+
+        create_test_skills(&source);
+
+        // First sync.
+        sync_skills_optimized(&SyncOptions {
+            source_dir: source.clone(),
+            dest_dir: dest.clone(),
+        })
+        .unwrap();
+
+        // Modify a source file (different size triggers re-copy).
+        std::thread::sleep(std::time::Duration::from_millis(50));
+        fs::write(
+            source.join("request-routing/SKILL.md"),
+            "# Request Routing\nUpdated with new content that is longer.",
+        )
+        .unwrap();
+
+        // Second sync — should copy the modified file.
+        let r2 = sync_skills_optimized(&SyncOptions {
+            source_dir: source,
+            dest_dir: dest.clone(),
+        })
+        .unwrap();
+
+        assert_eq!(r2.files_copied, 1);
+        assert_eq!(r2.files_skipped, 2);
+
+        // Verify updated content.
+        let content = fs::read_to_string(dest.join("request-routing/SKILL.md")).unwrap();
+        assert!(content.contains("Updated with new content"));
+    }
+
+    #[test]
+    fn test_default_paths() {
+        let root = Path::new("/tmp/test-project");
+        assert_eq!(
+            default_source_dir(root),
+            PathBuf::from("/tmp/test-project/skills-templates")
+        );
+        assert_eq!(
+            default_dest_dir(root),
+            PathBuf::from("/tmp/test-project/.claude/skills")
+        );
+    }
+
+    #[test]
+    fn test_backup_naming_collision() {
+        let tmp = tempfile::tempdir().unwrap();
+        let skills = tmp.path().join(".claude").join("skills");
+        let claude_dir = tmp.path().join(".claude");
+
+        // Create skills dir.
+        fs::create_dir_all(&skills).unwrap();
+        fs::write(skills.join("test.txt"), "content").unwrap();
+
+        // First backup — no collision, should succeed.
+        let backup1 = create_backup(&skills).unwrap();
+        assert!(backup1.exists());
+        assert!(backup1.to_string_lossy().contains("skills.backup-"));
+
+        // Recreate skills dir for second backup.
+        fs::create_dir_all(&skills).unwrap();
+        fs::write(skills.join("test.txt"), "content").unwrap();
+
+        // Create a collision with the exact timestamp the second backup would use.
+        // Since we can't predict the exact ms, we pre-create the base name
+        // that will collide with the second backup attempt.
+        let now = chrono::Utc::now();
+        let ts = now.format("%Y-%m-%dT%H-%M-%S-%3fZ").to_string();
+        let collision = claude_dir.join(format!("skills.backup-{ts}"));
+        if !collision.exists() {
+            fs::create_dir_all(&collision).unwrap();
+        }
+
+        let backup2 = create_backup(&skills).unwrap();
+        assert!(backup2.exists());
+        // backup2 should have either a different timestamp or a counter suffix.
+        assert!(backup2 != backup1);
+    }
+
+    #[test]
+    fn test_should_skip_copy() {
+        let tmp = tempfile::tempdir().unwrap();
+        let src = tmp.path().join("src.txt");
+        let dest = tmp.path().join("dest.txt");
+
+        fs::write(&src, "hello").unwrap();
+
+        // Dest doesn't exist — should not skip.
+        assert!(!should_skip_copy(&src, &dest));
+
+        // Copy to dest — same content/size, dest mtime >= src.
+        fs::copy(&src, &dest).unwrap();
+        assert!(should_skip_copy(&src, &dest));
+
+        // Modify src to be different size — should not skip.
+        std::thread::sleep(std::time::Duration::from_millis(50));
+        fs::write(&src, "hello world longer content").unwrap();
+        assert!(!should_skip_copy(&src, &dest));
+    }
+}