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

skm_cli-0.2.1/CLAUDE.md

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skm-cli
-Version: 0.1.0
+Version: 0.2.1
 Summary: Skill Manager - manage agent skills from GitHub repos
 Author-email: Reorx <novoreorx@gmail.com>
 Requires-Python: >=3.12
@@ -19,6 +19,12 @@ A CLI tool that manages **global** AI agent skills from GitHub repos or local di
 
 ## Install
 
+```bash
+uv tool install skm-cli
+```
+
+Or install from source:
+
 ```bash
 uv tool install git+https://github.com/reorx/skm
 ```
@@ -74,6 +80,7 @@ This detects available skills, lets you pick which ones to install (unless a spe
 | `skm list` | Show installed skills and their linked paths. |
 | `skm list --all` | Show all skills across all agent directories, marking which are managed by skm. |
 | `skm view <source>` | Browse and preview skills from a repo URL or local path without installing. |
+| `skm edit` | Open `skills.yaml` in `$EDITOR` (falls back to system default). Shows diff after editing. |
 | `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages). |
 | `skm update <skill>` | Pull latest for a skill's repo, re-detect, re-link, update lock (skips `local_path` packages). |
 
@@ -134,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.1.0 → skm_cli-0.2.1}/README.md

@@ -8,6 +8,12 @@ A CLI tool that manages **global** AI agent skills from GitHub repos or local di
 
 ## Install
 
+```bash
+uv tool install skm-cli
+```
+
+Or install from source:
+
 ```bash
 uv tool install git+https://github.com/reorx/skm
 ```
@@ -63,6 +69,7 @@ This detects available skills, lets you pick which ones to install (unless a spe
 | `skm list` | Show installed skills and their linked paths. |
 | `skm list --all` | Show all skills across all agent directories, marking which are managed by skm. |
 | `skm view <source>` | Browse and preview skills from a repo URL or local path without installing. |
+| `skm edit` | Open `skills.yaml` in `$EDITOR` (falls back to system default). Shows diff after editing. |
 | `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages). |
 | `skm update <skill>` | Pull latest for a skill's repo, re-detect, re-link, update lock (skips `local_path` packages). |
 
@@ -123,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.1.0 → skm_cli-0.2.1}/pyproject.toml

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

{skm_cli-0.1.0 → skm_cli-0.2.1}/src/skm/cli.py

@@ -294,17 +294,22 @@ def check_updates(ctx):
 
 
 @cli.command()
-@click.argument('skill_name')
+@click.argument('skill_names', nargs=-1)
+@click.option('--all', 'update_all', is_flag=True, help='Update all installed skills.')
 @click.pass_context
-def update(ctx, skill_name: str):
-    """Update a specific skill."""
+def update(ctx, skill_names: tuple[str, ...], update_all: bool):
+    """Update one or more skills (or --all)."""
     from skm.commands.update import run_update
 
+    if not skill_names and not update_all:
+        raise click.UsageError("Provide skill name(s) or use --all.")
+
     config = load_config(ctx.obj['config_path'])
     default_agents = config.agents.default if config.agents else None
     agents = _expand_agents(ctx.obj['agents_dir'], default_agents)
     run_update(
-        skill_name=skill_name,
+        skill_names=skill_names,
+        update_all=update_all,
         config=config,
         lock_path=ctx.obj['lock_path'],
         store_dir=ctx.obj['store_dir'],
@@ -322,6 +327,48 @@ def view(ctx, source: str):
     run_view(source=source, store_dir=ctx.obj['store_dir'])
 
 
+@cli.command()
+@click.pass_context
+def edit(ctx):
+    """Open skills.yaml in your editor."""
+    import os
+    import platform
+    import subprocess
+
+    config_path = ctx.obj['config_path']
+    if not config_path.exists():
+        raise click.ClickException(f'Config file not found: {config_path}')
+
+    editor = os.environ.get('EDITOR')
+    if editor:
+        import shutil
+        import tempfile
+
+        tmp = tempfile.NamedTemporaryFile(suffix='.yaml', delete=False)
+        tmp.close()
+        shutil.copy2(config_path, tmp.name)
+        try:
+            subprocess.call([editor, str(config_path)])
+            if shutil.which('diff'):
+                result = subprocess.run(
+                    ['diff', '--color=always', tmp.name, str(config_path)],
+                    capture_output=True,
+                    text=True,
+                )
+                if result.stdout:
+                    click.echo(result.stdout)
+                else:
+                    click.echo('No changes.')
+        finally:
+            os.unlink(tmp.name)
+    elif platform.system() == 'Darwin':
+        subprocess.call(['open', str(config_path)])
+    elif platform.system() == 'Windows':
+        os.startfile(str(config_path))
+    else:
+        subprocess.call(['xdg-open', str(config_path)])
+
+
 @cli.command(name='list')
 @click.argument('skill_name', required=False, default=None)
 @click.option(

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.1.0 → skm_cli-0.2.1}/src/skm/commands/check_updates.py

@@ -23,7 +23,10 @@ def run_check_updates(lock_path: Path, store_dir: Path) -> None:
 
     has_updates = False
 
-    for repo_url, skills in repos.items():
+    for i, (repo_url, skills) in enumerate(repos.items()):
+        if i > 0:
+            click.echo()
+
         repo_dir_name = repo_url_to_dirname(repo_url)
         repo_path = store_dir / repo_dir_name
 
@@ -31,24 +34,24 @@ def run_check_updates(lock_path: Path, store_dir: Path) -> None:
             click.echo(click.style(f"Warning: Repo not found locally: {repo_url}", fg="red"))
             continue
 
-        click.echo(f"Fetching {repo_url}...")
+        click.echo(f"Fetching {click.style(repo_url, fg='cyan')}...")
         fetch(repo_path)
 
         local_commit = skills[0].commit  # all skills from same repo share commit
         remote_commit = get_remote_head_commit(repo_path)
 
         if local_commit == remote_commit:
-            click.echo(f"  Up to date")
+            click.echo(click.style("  ✔ Up to date", fg="green"))
             continue
 
         has_updates = True
         log = get_log_between(repo_path, local_commit, remote_commit)
-        skill_names = ", ".join(s.name for s in skills)
+        skill_names = ", ".join(click.style(s.name, fg="yellow") for s in skills)
         click.echo(f"  Updates available for: {skill_names}")
-        click.echo(f"  {local_commit[:8]} -> {remote_commit[:8]}")
+        click.echo(f"  {click.style(local_commit[:8], fg='red')} → {click.style(remote_commit[:8], fg='green')}")
         if log:
             for line in log.splitlines():
-                click.echo(f"    {line}")
+                click.echo(click.style(f"    {line}", dim=True))
 
     if not has_updates:
-        click.echo("\nAll skills are up to date.")
+        click.echo(click.style("\n✔ All skills are up to date.", fg="green"))

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

@@ -12,7 +12,8 @@ from skm.utils import compact_path
 
 
 def run_update(
-    skill_name: str,
+    skill_names: tuple[str, ...],
+    update_all: bool,
     config: SkmConfig,
     lock_path: Path,
     store_dir: Path,
@@ -20,52 +21,84 @@ def run_update(
 ) -> None:
     lock = load_lock(lock_path)
 
-    # Find skill in lock
-    old_skill = None
-    for s in lock.skills:
-        if s.name == skill_name:
-            old_skill = s
-            break
+    # Determine which repos to update
+    if update_all:
+        repos_to_update: dict[str, list[InstalledSkill]] = {}
+        for s in lock.skills:
+            if s.repo is None:
+                continue
+            repos_to_update.setdefault(s.repo, []).append(s)
+    else:
+        # Find requested skills and collect their repos
+        repos_to_update = {}
+        for name in skill_names:
+            found = None
+            for s in lock.skills:
+                if s.name == name:
+                    found = s
+                    break
+            if found is None:
+                click.echo(f"Skill '{name}' is not installed.")
+                raise SystemExit(1)
+            if found.repo is None:
+                click.echo(f"Skill '{name}' is from a local path, skipping update.")
+                continue
+            repos_to_update.setdefault(found.repo, []).append(found)
+
+    if not repos_to_update:
+        click.echo("Nothing to update.")
+        return
 
-    if old_skill is None:
-        click.echo(f"Skill '{skill_name}' is not installed.")
-        raise SystemExit(1)
+    for repo_url, skills in repos_to_update.items():
+        _update_repo(repo_url, config, lock, store_dir, known_agents)
 
-    if old_skill.repo is None:
-        click.echo(f"Skill '{skill_name}' is from a local path, skipping update.")
-        return
+    save_lock(lock, lock_path)
+    click.echo('Lock file updated.')
 
-    repo_dir_name = repo_url_to_dirname(old_skill.repo)
+
+def _update_repo(
+    repo_url: str,
+    config: SkmConfig,
+    lock,
+    store_dir: Path,
+    known_agents: dict[str, str],
+) -> None:
+    repo_dir_name = repo_url_to_dirname(repo_url)
     repo_path = store_dir / repo_dir_name
 
-    old_commit = old_skill.commit
+    # Get old commit from any skill in this repo
+    old_commit = None
+    for s in lock.skills:
+        if s.repo == repo_url:
+            old_commit = s.commit
+            break
 
     # Pull latest
-    click.echo(f'Pulling {old_skill.repo}...')
-    clone_or_pull(old_skill.repo, repo_path)
+    click.echo(f'Pulling {click.style(repo_url, fg="cyan")}...')
+    clone_or_pull(repo_url, repo_path)
     new_commit = get_head_commit(repo_path)
 
     if old_commit == new_commit:
-        click.echo(f'  Already up to date ({old_commit[:8]})')
+        click.echo(click.style(f'  ✔ Already up to date ({old_commit[:8]})', fg='green'))
         return
 
     # Show changes
     log = get_log_between(repo_path, old_commit, new_commit)
-    click.echo(f'  Updated {old_commit[:8]} -> {new_commit[:8]}')
+    click.echo(f'  Updated {click.style(old_commit[:8], fg="red")} → {click.style(new_commit[:8], fg="green")}')
     if log:
         for line in log.splitlines():
-            click.echo(f'    {line}')
+            click.echo(click.style(f'    {line}', dim=True))
 
     # Re-detect and re-link
     detected = detect_skills(repo_path)
     repo_config = None
     for c in config.packages:
-        if c.repo == old_skill.repo:
+        if c.repo == repo_url:
             repo_config = c
             break
 
     if repo_config is None:
-        click.echo(f"  Error: repo '{old_skill.repo}' not found in config. Cannot determine target agents.")
+        click.echo(f"  Error: repo '{repo_url}' not found in config. Cannot determine target agents.")
         raise SystemExit(1)
 
     target_agents = resolve_target_agents(
@@ -76,7 +109,7 @@ def run_update(
     # Update all skills from this repo in the lock
     stale_indices = []
     for i, locked_skill in enumerate(lock.skills):
-        if locked_skill.repo != old_skill.repo:
+        if locked_skill.repo != repo_url:
             continue
         # Find matching detected skill
         matching = [d for d in detected if d.name == locked_skill.name]
@@ -95,7 +128,7 @@ def run_update(
         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(
@@ -109,6 +142,3 @@ def run_update(
     # Remove stale entries (iterate in reverse to preserve indices)
     for i in reversed(stale_indices):
         lock.skills.pop(i)
-
-    save_lock(lock, lock_path)
-    click.echo(f'Lock file updated.')

{skm_cli-0.1.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.1.0 → skm_cli-0.2.1}/src/skm/git.py

@@ -51,7 +51,7 @@ def clone_or_pull(repo_url: str, dest: Path) -> None:
     else:
         _validate_repo_url(repo_url)
         dest.parent.mkdir(parents=True, exist_ok=True)
-        run_cmd(["git", "clone", repo_url, str(dest)])
+        run_cmd(["git", "clone", "--filter=blob:none", repo_url, str(dest)])
 
 
 def get_head_commit(repo_path: Path) -> str: