skm-cli 0.2.0__tar.gz → 0.2.1__tar.gz

skm_cli-0.2.1/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

{skm_cli-0.2.0 → skm_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skm-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: Skill Manager - manage agent skills from GitHub repos
 Author-email: Reorx <novoreorx@gmail.com>
 Requires-Python: >=3.12
@@ -141,6 +141,47 @@ Skills are symlinked into these directories by default:
 | `codex` | `~/.codex/skills/` |
 | `openclaw` | `~/.openclaw/skills/` |
 
+## Copy Strategy
+
+When skm links a skill into an agent directory, it picks a strategy based on the agent config and filesystem:
+
+### 1. Symlink (default)
+
+A symbolic link from `<agent_dir>/skills/<skill_name>` → `<store>/<skill_name>`. This is the default for all agents. Changes in the store are immediately visible.
+
+### 2. Hardlink
+
+When `use_hardlink: true` is set for an agent in `AGENT_OPTIONS`, skm creates hardlinks instead. Each file in the skill directory gets its own hardlink pointing to the same inode as the source. This only works when source and target are on the **same filesystem/device**.
+
+### 3. Reflink (copy-on-write)
+
+When hardlinks can't be used (source and target on **different devices**), skm attempts a reflink/COW clone. This creates an independent copy that shares physical disk blocks with the source until either side is modified — fast and space-efficient.
+
+The reflink backend is platform-specific:
+
+| Platform | Mechanism | Supported filesystems |
+|---|---|---|
+| **Linux** | `FICLONE` ioctl (`fcntl.ioctl`) | Btrfs, XFS, OCFS2, and others with reflink support |
+| **macOS** | `clonefile(2)` syscall (via `ctypes`) | APFS (default since macOS 10.13) |
+
+### 4. Plain copy (fallback)
+
+If reflink is not available (unsupported filesystem, non-Unix platform, etc.), skm falls back to a plain `shutil.copy2` — a full byte copy with metadata preserved.
+
+### Selection flow
+
+```
+use_hardlink enabled?
+├── No  → symlink
+└── Yes → same device?
+    ├── Yes → hardlink
+    └── No  → reflink supported?
+        ├── Yes → reflink (COW clone)
+        └── No  → plain copy
+```
+
+The reflink implementation is isolated in `src/skm/clonefile.py` with dedicated tests in `tests/test_clonefile.py`.
+
 ## CLI Path Overrides
 
 Override default paths for testing or custom setups:

{skm_cli-0.2.0 → skm_cli-0.2.1}/README.md

@@ -130,6 +130,47 @@ Skills are symlinked into these directories by default:
 | `codex` | `~/.codex/skills/` |
 | `openclaw` | `~/.openclaw/skills/` |
 
+## Copy Strategy
+
+When skm links a skill into an agent directory, it picks a strategy based on the agent config and filesystem:
+
+### 1. Symlink (default)
+
+A symbolic link from `<agent_dir>/skills/<skill_name>` → `<store>/<skill_name>`. This is the default for all agents. Changes in the store are immediately visible.
+
+### 2. Hardlink
+
+When `use_hardlink: true` is set for an agent in `AGENT_OPTIONS`, skm creates hardlinks instead. Each file in the skill directory gets its own hardlink pointing to the same inode as the source. This only works when source and target are on the **same filesystem/device**.
+
+### 3. Reflink (copy-on-write)
+
+When hardlinks can't be used (source and target on **different devices**), skm attempts a reflink/COW clone. This creates an independent copy that shares physical disk blocks with the source until either side is modified — fast and space-efficient.
+
+The reflink backend is platform-specific:
+
+| Platform | Mechanism | Supported filesystems |
+|---|---|---|
+| **Linux** | `FICLONE` ioctl (`fcntl.ioctl`) | Btrfs, XFS, OCFS2, and others with reflink support |
+| **macOS** | `clonefile(2)` syscall (via `ctypes`) | APFS (default since macOS 10.13) |
+
+### 4. Plain copy (fallback)
+
+If reflink is not available (unsupported filesystem, non-Unix platform, etc.), skm falls back to a plain `shutil.copy2` — a full byte copy with metadata preserved.
+
+### Selection flow
+
+```
+use_hardlink enabled?
+├── No  → symlink
+└── Yes → same device?
+    ├── Yes → hardlink
+    └── No  → reflink supported?
+        ├── Yes → reflink (COW clone)
+        └── No  → plain copy
+```
+
+The reflink implementation is isolated in `src/skm/clonefile.py` with dedicated tests in `tests/test_clonefile.py`.
+
 ## CLI Path Overrides
 
 Override default paths for testing or custom setups:

{skm_cli-0.2.0 → skm_cli-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "skm-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "Skill Manager - manage agent skills from GitHub repos"
 readme = "README.md"
 authors = [

skm_cli-0.2.1/src/skm/clonefile.py

@@ -0,0 +1,106 @@
+"""Platform-aware reflink (copy-on-write) file cloning.
+
+Supports two backends:
+- Linux: FICLONE ioctl (Btrfs, XFS, etc.)
+- macOS: clonefile(2) syscall (APFS)
+
+Both backends raise OSError on failure. Callers should catch OSError and
+check ``is_reflink_unsupported(exc)`` to decide whether to fall back to
+a plain copy.
+"""
+
+import ctypes
+import ctypes.util
+import errno
+import os
+import platform
+import shutil
+from pathlib import Path
+
+# --- errno values that mean "this filesystem doesn't support reflink" -------
+
+REFLINK_UNSUPPORTED_ERRNOS: set[int] = {
+    errno.ENOTSUP,
+    getattr(errno, 'EOPNOTSUPP', errno.ENOTSUP),
+    getattr(errno, 'ENOSYS', errno.ENOTSUP),
+    getattr(errno, 'ENOTTY', errno.ENOTSUP),
+    getattr(errno, 'EXDEV', errno.ENOTSUP),
+}
+
+_SYSTEM = platform.system()
+
+# --- Linux: FICLONE ioctl ---------------------------------------------------
+
+_FICLONE = 0x40049409  # from <linux/fs.h>
+_fcntl = None
+
+if _SYSTEM == 'Linux':
+    try:
+        import fcntl as _fcntl_mod
+
+        _fcntl = _fcntl_mod
+    except ImportError:  # pragma: no cover
+        pass
+
+
+def _clone_file_linux(src: Path, dst: Path) -> None:
+    """Clone via FICLONE ioctl (Linux only)."""
+    assert _fcntl is not None
+    with src.open('rb') as src_f, dst.open('wb') as dst_f:
+        _fcntl.ioctl(dst_f.fileno(), _FICLONE, src_f.fileno())
+    shutil.copystat(src, dst)
+
+
+# --- macOS: clonefile(2) ----------------------------------------------------
+
+_clonefile_func = None
+
+if _SYSTEM == 'Darwin':
+    _libc_path = ctypes.util.find_library('System')
+    if _libc_path:
+        _libc = ctypes.CDLL(_libc_path, use_errno=True)
+        _clonefile_func = _libc.clonefile
+        _clonefile_func.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int]
+        _clonefile_func.restype = ctypes.c_int
+
+
+def _clone_file_darwin(src: Path, dst: Path) -> None:
+    """Clone via clonefile(2) syscall (macOS only)."""
+    assert _clonefile_func is not None
+    ret = _clonefile_func(os.fsencode(src), os.fsencode(dst), 0)
+    if ret != 0:
+        err = ctypes.get_errno()
+        raise OSError(err, os.strerror(err), str(src))
+    shutil.copystat(src, dst)
+
+
+# --- Public API --------------------------------------------------------------
+
+
+def reflink_supported() -> bool:
+    """Return True if the current platform has a reflink backend available."""
+    if _SYSTEM == 'Linux':
+        return _fcntl is not None
+    if _SYSTEM == 'Darwin':
+        return _clonefile_func is not None
+    return False
+
+
+def clone_file(src: Path, dst: Path) -> None:
+    """Clone a single file using the platform's COW mechanism.
+
+    Raises OSError if the filesystem or platform doesn't support it.
+    Use ``is_reflink_unsupported(exc)`` to distinguish "not supported"
+    from genuine I/O errors.
+    """
+    if _SYSTEM == 'Linux' and _fcntl is not None:
+        _clone_file_linux(src, dst)
+    elif _SYSTEM == 'Darwin' and _clonefile_func is not None:
+        _clone_file_darwin(src, dst)
+    else:
+        raise OSError(errno.ENOTSUP, 'reflink is not supported on this platform')
+
+
+def is_reflink_unsupported(exc: OSError) -> bool:
+    """Return True when the error means reflink isn't available, not a real I/O failure."""
+    return exc.errno in REFLINK_UNSUPPORTED_ERRNOS

{skm_cli-0.2.0 → skm_cli-0.2.1}/src/skm/commands/update.py

@@ -128,7 +128,7 @@ def _update_repo(
         skill = matching[0]
         linked_paths = []
         for agent_name, agent_dir in target_agents.items():
-            link, _status = link_skill(skill.path, skill.name, agent_dir, agent_name=agent_name)
+            link, _status = link_skill(skill.path, skill.name, agent_dir, force=True, agent_name=agent_name)
             linked_paths.append(compact_path(str(link)))
 
         lock.skills[i] = InstalledSkill(

{skm_cli-0.2.0 → skm_cli-0.2.1}/src/skm/detect.py

@@ -6,26 +6,26 @@ from skm.types import DetectedSkill
 
 def parse_skill_name(skill_md_path: Path) -> str:
     """Extract 'name' from SKILL.md YAML frontmatter."""
-    text = skill_md_path.read_text(encoding="utf-8")
-    match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
+    text = skill_md_path.read_text(encoding='utf-8')
+    match = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
     if not match:
-        raise ValueError(f"No frontmatter found in {skill_md_path}")
+        raise ValueError(f'No frontmatter found in {skill_md_path}')
     for line in match.group(1).splitlines():
-        if line.startswith("name:"):
-            return line.split(":", 1)[1].strip()
+        if line.startswith('name:'):
+            return line.split(':', 1)[1].strip().strip('\'"')
     raise ValueError(f"No 'name' field in frontmatter of {skill_md_path}")
 
 
 def detect_skills(repo_path: Path) -> list[DetectedSkill]:
     """Detect skills in a cloned repo by walking for SKILL.md files."""
     # Case 1: Root has SKILL.md → singleton skill
-    root_skill = repo_path / "SKILL.md"
+    root_skill = repo_path / 'SKILL.md'
     if root_skill.exists():
         name = parse_skill_name(root_skill)
-        return [DetectedSkill(name=name, path=repo_path, relative_path=".")]
+        return [DetectedSkill(name=name, path=repo_path, relative_path='.')]
 
     # Determine walk root
-    skills_dir = repo_path / "skills"
+    skills_dir = repo_path / 'skills'
     walk_root = skills_dir if skills_dir.is_dir() else repo_path
 
     return _walk_for_skills(walk_root, repo_path)
@@ -37,9 +37,9 @@ def _walk_for_skills(walk_root: Path, repo_path: Path) -> list[DetectedSkill]:
     for child in sorted(walk_root.iterdir()):
         if not child.is_dir() or child.is_symlink():
             continue
-        if child.name.startswith("."):
+        if child.name == '.git':
             continue
-        skill_md = child / "SKILL.md"
+        skill_md = child / 'SKILL.md'
         if skill_md.exists():
             name = parse_skill_name(skill_md)
             relative = str(child.relative_to(repo_path))

skm_cli-0.2.1/src/skm/linker.py

@@ -0,0 +1,195 @@
+import filecmp
+import os
+import shutil
+from pathlib import Path
+from typing import Literal
+
+from skm.clonefile import clone_file, is_reflink_unsupported, reflink_supported
+from skm.types import AGENT_OPTIONS, AgentsConfig
+
+MaterializationMode = Literal['hardlink', 'reflink', 'copy']
+
+
+def _get_agent_option(agent_name: str, option: str, default=None):
+    """Look up a per-agent option from AGENT_OPTIONS."""
+    return AGENT_OPTIONS.get(agent_name, {}).get(option, default)
+
+
+def resolve_target_agents(
+    agents_config: AgentsConfig | None,
+    known_agents: dict[str, str],
+) -> dict[str, str]:
+    """Determine which agents to install to based on includes/excludes."""
+    if agents_config is None:
+        return dict(known_agents)
+
+    if agents_config.includes is not None:
+        return {k: v for k, v in known_agents.items() if k in agents_config.includes}
+
+    if agents_config.excludes is not None:
+        return {k: v for k, v in known_agents.items() if k not in agents_config.excludes}
+
+    return dict(known_agents)
+
+
+def _clone_file_reflink(src: Path, dst: Path) -> None:
+    """Clone a file using the platform's COW mechanism (see skm.clonefile)."""
+    clone_file(src, dst)
+
+
+def _copy_file(src: Path, dst: Path) -> None:
+    """Copy a file with metadata."""
+    shutil.copy2(src, dst)
+
+
+def _get_materialized_entries(path: Path) -> dict[str, Path]:
+    """Return managed candidate entries, excluding hidden files and symlinks."""
+    return {item.name: item for item in path.iterdir() if not item.name.startswith('.') and not item.is_symlink()}
+
+
+def _supports_copy_fallback(exc: OSError) -> bool:
+    """Return True when a reflink failure should fall back to plain copy."""
+    return is_reflink_unsupported(exc)
+
+
+def _materialize_file(
+    src: Path,
+    dst: Path,
+    mode: MaterializationMode,
+) -> MaterializationMode:
+    """Materialize a file and return the mode to keep using."""
+    if mode == 'hardlink':
+        os.link(src, dst)
+        return 'hardlink'
+
+    if mode == 'copy':
+        _copy_file(src, dst)
+        return 'copy'
+
+    try:
+        _clone_file_reflink(src, dst)
+    except OSError as exc:
+        if not _supports_copy_fallback(exc):
+            raise
+        _copy_file(src, dst)
+        return 'copy'
+    return 'reflink'
+
+
+def _materialize_tree(
+    src: Path,
+    dst: Path,
+    mode: MaterializationMode,
+) -> MaterializationMode:
+    """Recreate directory structure from src at dst using a materialization mode."""
+    dst.mkdir(parents=True, exist_ok=True)
+    current_mode = mode
+    for item in src.iterdir():
+        if item.name.startswith('.') or item.is_symlink():
+            continue
+        target = dst / item.name
+        if item.is_dir():
+            current_mode = _materialize_tree(item, target, current_mode)
+        else:
+            if not target.exists():
+                current_mode = _materialize_file(item, target, current_mode)
+    return current_mode
+
+
+def _is_managed_materialized_dir(link_path: Path, skill_src: Path) -> bool:
+    """Check whether link_path looks like a managed hardlink/reflink materialized copy."""
+    if not link_path.is_dir() or link_path.is_symlink():
+        return False
+
+    source_entries = _get_materialized_entries(skill_src)
+    target_entries = _get_materialized_entries(link_path)
+    if not target_entries.keys() <= source_entries.keys():
+        return False
+
+    for name, target_item in target_entries.items():
+        source_item = source_entries[name]
+        if source_item.is_dir():
+            if not _is_managed_materialized_dir(target_item, source_item):
+                return False
+            continue
+        if not target_item.is_file():
+            return False
+        if source_item.stat().st_ino == target_item.stat().st_ino:
+            continue
+        if not filecmp.cmp(source_item, target_item, shallow=False):
+            return False
+    return True
+
+
+def _select_materialization_mode(skill_src: Path, target_dir: Path) -> MaterializationMode:
+    """Pick hardlink on the same device, otherwise use reflink or plain copy."""
+    src_dev = skill_src.stat().st_dev
+    dst_dev = target_dir.stat().st_dev
+    if src_dev == dst_dev:
+        return 'hardlink'
+
+    if not reflink_supported():
+        return 'copy'
+    return 'reflink'
+
+
+def link_skill(
+    skill_src: Path, skill_name: str, agent_skills_dir: str, force: bool = False, agent_name: str = ''
+) -> tuple[Path, str]:
+    """Create a symlink (or hardlink tree) from agent_skills_dir/skill_name -> skill_src.
+
+    Returns (link_path, status) where status is "new", "exists", or "replaced".
+    """
+    use_hardlink = _get_agent_option(agent_name, 'use_hardlink', False)
+    target_dir = Path(agent_skills_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    link_path = target_dir / skill_name
+
+    if use_hardlink:
+        # Materialized mode: prefer hardlink, fall back to reflink when devices differ.
+        mode = _select_materialization_mode(skill_src, target_dir)
+        if link_path.exists() and not link_path.is_symlink():
+            if _is_managed_materialized_dir(link_path, skill_src):
+                # Already managed, refresh to pick up any changes.
+                _materialize_tree(skill_src, link_path, mode)
+                return (link_path, 'exists')
+            if not force:
+                raise FileExistsError(f'{link_path} exists and is not a managed copy')
+            shutil.rmtree(link_path)
+            _materialize_tree(skill_src, link_path, mode)
+            return (link_path, 'replaced')
+        elif link_path.is_symlink():
+            # Switching from symlink to a materialized copy.
+            link_path.unlink()
+
+        _materialize_tree(skill_src, link_path, mode)
+        return (link_path, 'new')
+
+    # Symlink mode (default)
+    if link_path.is_symlink():
+        if link_path.resolve() == skill_src.resolve():
+            return (link_path, 'exists')
+        link_path.unlink()
+        link_path.symlink_to(skill_src)
+        return (link_path, 'replaced')
+
+    if link_path.exists():
+        if force:
+            if link_path.is_dir():
+                shutil.rmtree(link_path)
+            else:
+                link_path.unlink()
+        else:
+            raise FileExistsError(f'{link_path} exists and is not a symlink')
+
+    link_path.symlink_to(skill_src)
+    return (link_path, 'new')
+
+
+def unlink_skill(skill_name: str, agent_skills_dir: str) -> None:
+    """Remove symlink or hardlinked dir for a skill from an agent dir."""
+    link_path = Path(agent_skills_dir) / skill_name
+    if link_path.is_symlink():
+        link_path.unlink()
+    elif link_path.is_dir():
+        shutil.rmtree(link_path)

{skm_cli-0.2.0 → skm_cli-0.2.1}/tests/test_cli_e2e.py

@@ -383,6 +383,34 @@ class TestUpdate:
         # The commit should be 40 hex chars (full SHA)
         assert len(old_commit) == 40
 
+    def test_update_removes_deleted_materialized_files(self, tmp_path):
+        repo = _make_skill_repo(tmp_path, 'repo-upd3', [{'name': 'upd-skill'}])
+        tracked_file = repo / 'skills' / 'upd-skill' / 'extra.md'
+        tracked_file.write_text('old content')
+        subprocess.run(['git', 'add', '.'], cwd=repo, capture_output=True, check=True)
+        subprocess.run(['git', 'commit', '-m', 'add extra'], cwd=repo, capture_output=True, check=True)
+
+        _write_config(tmp_path, [{'repo': str(repo)}])
+
+        runner = CliRunner()
+        install_result = runner.invoke(cli, [*_cli_args(tmp_path), 'install'])
+        assert install_result.exit_code == 0, install_result.output
+
+        standard_file = tmp_path / 'agents' / 'standard' / 'upd-skill' / 'extra.md'
+        openclaw_file = tmp_path / 'agents' / 'openclaw' / 'upd-skill' / 'extra.md'
+        assert standard_file.exists()
+        assert openclaw_file.exists()
+
+        tracked_file.unlink()
+        subprocess.run(['git', 'add', '-A'], cwd=repo, capture_output=True, check=True)
+        subprocess.run(['git', 'commit', '-m', 'remove extra'], cwd=repo, capture_output=True, check=True)
+
+        result = runner.invoke(cli, [*_cli_args(tmp_path), 'update', 'upd-skill'])
+        assert result.exit_code == 0, result.output
+        assert 'remove extra' in result.output
+        assert not standard_file.exists()
+        assert not openclaw_file.exists()
+
 
 class TestCheckUpdates:
     def test_check_updates_no_skills(self, tmp_path):

skm_cli-0.2.1/tests/test_clonefile.py

@@ -0,0 +1,178 @@
+"""Tests for skm.clonefile — platform-aware reflink/COW cloning."""
+
+import errno
+import platform
+import shutil
+
+import pytest
+
+from skm import clonefile
+from skm.clonefile import (
+    clone_file,
+    is_reflink_unsupported,
+    reflink_supported,
+)
+
+_SYSTEM = platform.system()
+
+
+# --- is_reflink_unsupported --------------------------------------------------
+
+
+def test_is_reflink_unsupported_recognises_enotsup():
+    assert is_reflink_unsupported(OSError(errno.ENOTSUP, 'not supported'))
+
+
+def test_is_reflink_unsupported_rejects_eio():
+    assert not is_reflink_unsupported(OSError(errno.EIO, 'disk error'))
+
+
+# --- reflink_supported -------------------------------------------------------
+
+
+def test_reflink_supported_returns_bool():
+    result = reflink_supported()
+    assert isinstance(result, bool)
+    if _SYSTEM == 'Darwin':
+        # macOS with APFS should have clonefile available
+        assert result is True
+    elif _SYSTEM == 'Linux':
+        # Linux should have fcntl available
+        assert result is True
+
+
+def test_reflink_supported_false_on_unknown_platform(monkeypatch):
+    monkeypatch.setattr(clonefile, '_SYSTEM', 'FreeBSD')
+    assert reflink_supported() is False
+
+
+# --- clone_file: unsupported platform ----------------------------------------
+
+
+def test_clone_file_raises_on_unsupported_platform(monkeypatch, tmp_path):
+    monkeypatch.setattr(clonefile, '_SYSTEM', 'FreeBSD')
+    src = tmp_path / 'src.txt'
+    dst = tmp_path / 'dst.txt'
+    src.write_text('hello')
+    with pytest.raises(OSError) as exc_info:
+        clone_file(src, dst)
+    assert is_reflink_unsupported(exc_info.value)
+
+
+# --- clone_file: Linux backend via monkeypatch --------------------------------
+
+
+def test_clone_file_linux_delegates_to_ficlone_ioctl(monkeypatch, tmp_path):
+    """Verify the Linux path calls fcntl.ioctl with FICLONE."""
+    calls = []
+
+    class FakeFcntl:
+        @staticmethod
+        def ioctl(dst_fd, request, src_fd):
+            calls.append((dst_fd, request, src_fd))
+
+    monkeypatch.setattr(clonefile, '_SYSTEM', 'Linux')
+    monkeypatch.setattr(clonefile, '_fcntl', FakeFcntl)
+
+    src = tmp_path / 'src.txt'
+    dst = tmp_path / 'dst.txt'
+    src.write_text('hello')
+
+    clone_file(src, dst)
+
+    assert len(calls) == 1
+    _dst_fd, request, _src_fd = calls[0]
+    assert request == 0x40049409  # _FICLONE
+
+
+# --- clone_file: macOS backend via monkeypatch --------------------------------
+
+
+def test_clone_file_darwin_delegates_to_clonefile_syscall(monkeypatch, tmp_path):
+    """Verify the macOS path calls the clonefile C function."""
+    calls = []
+
+    def fake_clonefile(src_bytes, dst_bytes, flags):
+        calls.append((src_bytes, dst_bytes, flags))
+        # Simulate success by actually copying
+        shutil.copy2(src_bytes.decode(), dst_bytes.decode())
+        return 0
+
+    monkeypatch.setattr(clonefile, '_SYSTEM', 'Darwin')
+    monkeypatch.setattr(clonefile, '_clonefile_func', fake_clonefile)
+
+    src = tmp_path / 'src.txt'
+    dst = tmp_path / 'dst.txt'
+    src.write_text('hello')
+
+    clone_file(src, dst)
+
+    assert len(calls) == 1
+    assert calls[0][2] == 0  # flags
+
+
+def test_clone_file_darwin_raises_on_failure(monkeypatch, tmp_path):
+    """Verify macOS clonefile errors are raised as OSError."""
+    import ctypes
+
+    def fake_clonefile(src_bytes, dst_bytes, flags):
+        ctypes.set_errno(errno.ENOTSUP)
+        return -1
+
+    monkeypatch.setattr(clonefile, '_SYSTEM', 'Darwin')
+    monkeypatch.setattr(clonefile, '_clonefile_func', fake_clonefile)
+
+    src = tmp_path / 'src.txt'
+    dst = tmp_path / 'dst.txt'
+    src.write_text('hello')
+
+    with pytest.raises(OSError) as exc_info:
+        clone_file(src, dst)
+    assert is_reflink_unsupported(exc_info.value)
+
+
+# --- Real clone_file on current platform -------------------------------------
+
+
+@pytest.mark.skipif(not reflink_supported(), reason='reflink not available on this platform')
+def test_clone_file_real(tmp_path):
+    """Attempt a real reflink clone on the current filesystem.
+
+    On APFS (macOS) this should succeed and produce a COW clone.
+    On Linux this depends on the filesystem (Btrfs/XFS succeed, ext4 fails).
+    If the filesystem doesn't support it, the error should be recognised
+    by is_reflink_unsupported.
+    """
+    src = tmp_path / 'original.txt'
+    src.write_text('content for reflink test')
+    dst = tmp_path / 'cloned.txt'
+
+    try:
+        clone_file(src, dst)
+    except OSError as exc:
+        # Filesystem doesn't support reflink — that's OK, just verify
+        # we correctly identify it as "unsupported" rather than a real error.
+        assert is_reflink_unsupported(exc), f'unexpected OSError: {exc}'
+        return
+
+    assert dst.read_text() == 'content for reflink test'
+    # On a COW filesystem, inodes should differ (it's a clone, not a hardlink)
+    assert src.stat().st_ino != dst.stat().st_ino
+
+
+@pytest.mark.skipif(not reflink_supported(), reason='reflink not available on this platform')
+def test_clone_file_real_dst_must_not_exist(tmp_path):
+    """clonefile(2) on macOS refuses to overwrite; FICLONE on Linux creates dst via open('wb')."""
+    src = tmp_path / 'src.txt'
+    src.write_text('hello')
+    dst = tmp_path / 'dst.txt'
+    dst.write_text('already here')
+
+    if _SYSTEM == 'Darwin':
+        # macOS clonefile fails with EEXIST
+        with pytest.raises(OSError):
+            clone_file(src, dst)
+    else:
+        # Linux FICLONE opens dst with 'wb' (truncates), so this succeeds
+        clone_file(src, dst)
+        assert dst.read_text() == 'hello'