hitkeep: Skill for Claude Code

Safe File Operations: fileflow & pathologize

Two small, composable spf13 libraries that handle the two things naive file code gets wrong: moving files safely (fileflow) and making names safe (pathologize).

When to Activate

• Moving, copying, or renaming files — especially across drives/volumes
• Handling the "destination already exists" case without clobbering data
• Seeing invalid cross-device link / EXDEV from os.Rename
• Building a destination path from a filename, user input, or a regex capture
• Downloaders, extractors, importers, file organizers, upload handlers
• Anywhere you were about to write os.Rename + io.Copy + filepath.Clean by hand

Why These Over the Standard Library

os.Rename fails across filesystems (EXDEV) and silently overwrites the destination. filepath.Clean normalizes .. but does not remove characters that are illegal on other operating systems, and does nothing about reserved names (CON, NUL). And path/filepath validates against the host OS only — a name that is fine on Linux can break the moment the file syncs to a Windows client. These libraries close all of these gaps and compose cleanly.

The Core Pattern: Join a trusted root with untrusted parts, then move

The single most important pattern. Use pathologize.Join to combine a trusted root with untrusted path parts (regex captures, user input, scraped titles), then move with fileflow. Join sanitizes each part and guarantees it stays lexically under the root — a part can't inject an absolute path or ../ its way out.

import (
    "path/filepath"

    "github.com/spf13/fileflow"
    "github.com/spf13/pathologize"
)

// destRoot is trusted (a configured directory); id/name are untrusted.
dstDir := pathologize.Join(destRoot, "ig", id)   // parts sanitized + contained
dst := filepath.Join(dstDir, filepath.Base(src))

final, err := fileflow.Move(src, dst)            // cross-fs safe, conflict safe
if err != nil {
    return err
}
// final is where the file actually landed (may be suffixed on conflict).