Merge branch 'main' into copilot/fix-windows-path-compatibility

Author: danielmeppiel

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Systematic Windows path compatibility hardening: added `portable_relpath()` utility and migrated ~23 `relative_to()` call sites to use `.resolve()` on both sides + `.as_posix()` output, preventing `ValueError` on Windows 8.3 short names and backslash-contaminated path strings (#419)
 - Virtual package types (files, collections, subdirectories) now respect `ARTIFACTORY_ONLY=1`, matching the primary zip-archive proxy-only behavior (#418)
+- `apm pack --target claude` no longer produces an empty bundle when skills/agents are installed under `.github/` -- cross-target path mapping remaps `skills/` and `agents/` to the pack target prefix (#420)
 
 ### Added
 
@@ -32,6 +33,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `gh-aw-compat` is now informational (`continue-on-error: true`) — non-deterministic external dependencies should not block releases (#371)
 - Copilot encoding instructions: `encoding.instructions.md` (`applyTo: "**"`) bans non-ASCII characters in source and CLI output; updated `copilot-instructions.md` and `cli.instructions.md` to use ASCII bracket notation (`[+]`/`[!]`/`[x]`/`[i]`/`[*]`/`[>]`) instead of emoji STATUS_SYMBOLS (#282)
 
+### Fixed
+
+- Resolved Windows 8.3 short-name path mismatch: call `.resolve()` on both sides of `relative_to()` in `_generate_placement_summary` and `_generate_distributed_summary` so paths display correctly on Windows CI runners (#411)
+
 ## [0.8.4] - 2026-03-22
 
 ### Added

docs/src/content/docs/guides/pack-distribute.md

@@ -40,7 +40,7 @@ Creates a self-contained bundle from installed dependencies. Reads the `deployed
 apm pack
 
 # Filter by target
-apm pack --target vscode          # only .github/ files
+apm pack --target copilot         # only .github/ files
 apm pack --target claude          # only .claude/ files
 apm pack --target all             # both targets
 
@@ -62,7 +62,7 @@ apm pack --dry-run
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--format` | `apm` | Bundle format (`apm` or `plugin`) |
-| `-t, --target` | auto-detect | File filter: `copilot`, `vscode`, `claude`, `cursor`, `opencode`, `all`. `vscode` is an alias for `copilot` |
+| `-t, --target` | auto-detect | File filter: `copilot`, `claude`, `cursor`, `opencode`, `all`. `vscode` is a deprecated alias for `copilot` |
 | `--archive` | off | Produce `.tar.gz` instead of directory |
 | `-o, --output` | `./build` | Output directory |
 | `--dry-run` | off | List files without writing |
@@ -75,14 +75,48 @@ The target flag controls which deployed files are included based on path prefix:
 | Target | Includes |
 |--------|----------|
 | `copilot` | Paths starting with `.github/` |
-| `vscode` | Alias for `copilot` |
+| `vscode` | Deprecated alias for `copilot` |
 | `claude` | Paths starting with `.claude/` |
 | `cursor` | Paths starting with `.cursor/` |
 | `opencode` | Paths starting with `.opencode/` |
 | `all` | `.github/`, `.claude/`, `.cursor/`, and `.opencode/` |
 
 When no target is specified, APM auto-detects from the `target` field in `apm.yml`, falling back to `all`.
 
+### Cross-target path mapping
+
+Skills and agents are semantically identical across targets -- `.github/skills/X` and `.claude/skills/X` contain the same content. When the lockfile records files under a different target prefix than the one you are packing for, APM automatically remaps `skills/` and `agents/` paths:
+
+```
+apm pack --target claude
+# .github/skills/my-plugin/SKILL.md  ->  .claude/skills/my-plugin/SKILL.md
+# .github/agents/helper.md           ->  .claude/agents/helper.md
+```
+
+Only `skills/` and `agents/` are remapped. Commands, instructions, and hooks are target-specific and are never mapped.
+
+The enriched lockfile inside the bundle uses the remapped paths, so the bundle is self-consistent. When mapping occurs, the `pack:` section includes a `mapped_from` field listing the original prefixes.
+
+### Targeting mental model
+
+**Choose your target when you pack. Unpack delivers exactly what was packed.**
+
+A bundle is a deployable snapshot, not a retargetable source artifact. Target selection happens at pack time because that is when the full context is available -- which file types are remappable (skills, agents) and which are target-specific (commands, instructions, hooks).
+
+`apm unpack` does not remap paths. If the bundle was packed for Claude, the files land under `.claude/`. If you need a different target, re-pack from source with the desired `--target` flag, or use `--target all` to include all platforms.
+
+When unpacking, APM reads the bundle's `pack:` metadata and shows the target it was packed for. If the bundle target does not match the project's detected target, a warning is displayed:
+
+```
+$ apm unpack team-skills.tar.gz
+[*] Unpacking team-skills.tar.gz -> .
+[i] Bundle target: claude (1 dep(s), 3 file(s))
+[!] Bundle target 'claude' differs from project target 'copilot'
+[+] Unpacked 3 file(s) (verified)
+```
+
+This is informational -- the files still extract. The warning helps users understand why their tool may not see the unpacked files and suggests the correct workflow.
+
 ## Bundle structure
 
 The bundle mirrors the directory structure that `apm install` produces. It is not an intermediate format — extract it at the project root and the files land exactly where they belong.
@@ -212,7 +246,7 @@ The bundle includes a copy of `apm.lock.yaml` enriched with a `pack:` section. T
 ```yaml
 pack:
   format: apm
-  target: vscode
+  target: copilot
   packed_at: '2025-07-14T09:30:00+00:00'
 lockfile_version: '1'
 generated_at: '2025-07-14T09:28:00+00:00'
@@ -263,6 +297,7 @@ apm unpack ./build/my-project-1.0.0.tar.gz --dry-run
 | `-o, --output` | `.` (current dir) | Target project directory |
 | `--skip-verify` | off | Skip completeness check against lockfile |
 | `--dry-run` | off | List files without writing |
+| `--force` | off | Deploy despite critical hidden-character findings |
 
 ### Behavior
 
@@ -390,4 +425,7 @@ During unpack, verification found files listed in the bundle's lockfile that are
 
 ### Empty bundle
 
-If `apm pack` produces zero files, check that your dependencies have `deployed_files` entries in `apm.lock.yaml`. This can happen if `apm install` completed but no integration files were deployed (e.g., the package has no prompts or agents for the active target).
+If `apm pack` produces zero files, check:
+
+1. Your dependencies have `deployed_files` entries in `apm.lock.yaml`. This can happen if `apm install` completed but no integration files were deployed (e.g., the package has no prompts or agents for the active target).
+2. The `--target` filter matches where files were deployed. For example, if files are under `.github/` but you pack with `--target claude`, APM will remap `skills/` and `agents/` automatically. If no remappable files exist, the bundle will be empty. Try `--target all` or check `apm.lock.yaml` to see which prefixes your files use.

src/apm_cli/bundle/lockfile_enrichment.py

@@ -1,12 +1,12 @@
 """Lockfile enrichment for pack-time metadata."""
 
 from datetime import datetime, timezone
-from typing import List
+from typing import Dict, List, Tuple
 
 from ..deps.lockfile import LockFile
 
 
-# Must stay in sync with packer._TARGET_PREFIXES
+# Authoritative mapping of target names to deployed-file path prefixes.
 _TARGET_PREFIXES = {
     "copilot": [".github/"],
     "vscode": [".github/"],
@@ -16,11 +16,74 @@
     "all": [".github/", ".claude/", ".cursor/", ".opencode/"],
 }
 
+# Cross-target path equivalences for skills/ and agents/ directories.
+# Only these two directory types are semantically identical across targets;
+# commands, instructions, hooks are target-specific and are NOT mapped.
+#
+# .github/ is the canonical interop prefix -- install always creates it, so
+# all non-github targets map FROM .github/.  The copilot target additionally
+# maps FROM .claude/ for the common case of Claude-first projects packing
+# for Copilot.  Cursor/opencode sources are niche; if someone publishes
+# skills exclusively under .cursor/, they must pack with --target cursor.
+_CROSS_TARGET_MAPS: Dict[str, Dict[str, str]] = {
+    "claude": {
+        ".github/skills/": ".claude/skills/",
+        ".github/agents/": ".claude/agents/",
+    },
+    "vscode": {
+        ".claude/skills/": ".github/skills/",
+        ".claude/agents/": ".github/agents/",
+    },
+    "copilot": {
+        ".claude/skills/": ".github/skills/",
+        ".claude/agents/": ".github/agents/",
+    },
+    "cursor": {
+        ".github/skills/": ".cursor/skills/",
+        ".github/agents/": ".cursor/agents/",
+    },
+    "opencode": {
+        ".github/skills/": ".opencode/skills/",
+        ".github/agents/": ".opencode/agents/",
+    },
+}
+
+
+def _filter_files_by_target(
+    deployed_files: List[str], target: str
+) -> Tuple[List[str], Dict[str, str]]:
+    """Filter deployed file paths by target prefix, with cross-target mapping.
 
-def _filter_files_by_target(deployed_files: List[str], target: str) -> List[str]:
-    """Filter deployed file paths by target prefix."""
+    When files are deployed under one target prefix (e.g. ``.github/skills/``)
+    but the pack target is different (e.g. ``claude``), skills and agents are
+    remapped to the equivalent target path.  Commands, instructions, and hooks
+    are NOT remapped -- they are target-specific.
+
+    Returns:
+        A tuple of ``(filtered_files, path_mappings)`` where *path_mappings*
+        maps ``bundle_path -> disk_path`` for any file that was cross-target
+        remapped.  Direct matches have no entry in the dict.
+    """
     prefixes = _TARGET_PREFIXES.get(target, _TARGET_PREFIXES["all"])
-    return [f for f in deployed_files if any(f.startswith(p) for p in prefixes)]
+    direct = [f for f in deployed_files if any(f.startswith(p) for p in prefixes)]
+
+    path_mappings: Dict[str, str] = {}
+    cross_map = _CROSS_TARGET_MAPS.get(target, {})
+    if cross_map:
+        direct_set = set(direct)
+        for f in deployed_files:
+            if f in direct_set:
+                continue
+            for src_prefix, dst_prefix in cross_map.items():
+                if f.startswith(src_prefix):
+                    mapped = dst_prefix + f[len(src_prefix):]
+                    if mapped not in direct_set:
+                        direct.append(mapped)
+                        direct_set.add(mapped)
+                        path_mappings[mapped] = f
+                    break
+
+    return direct, path_mappings
 
 
 def enrich_lockfile_for_pack(
@@ -40,35 +103,54 @@ def enrich_lockfile_for_pack(
     Args:
         lockfile: The resolved lockfile to enrich.
         fmt: Bundle format (``"apm"`` or ``"plugin"``).
-        target: Effective target used for packing (``"vscode"``, ``"claude"``, ``"all"``).
+        target: Effective target used for packing (e.g. ``"copilot"``, ``"claude"``,
+            ``"all"``).  The internal alias ``"vscode"`` is also accepted.
 
     Returns:
         A YAML string with the ``pack:`` block followed by the original
         lockfile content.
     """
     import yaml
 
-    pack_section = yaml.dump(
-        {
-            "pack": {
-                "format": fmt,
-                "target": target,
-                "packed_at": datetime.now(timezone.utc).isoformat(),
-            }
-        },
-        default_flow_style=False,
-        sort_keys=False,
-    )
-
     # Build a filtered lockfile YAML: each dep's deployed_files is narrowed
-    # to only the paths matching the pack target.
+    # to only the paths matching the pack target (with cross-target mapping).
+    all_mappings: Dict[str, str] = {}
     data = yaml.safe_load(lockfile.to_yaml())
     if data and "dependencies" in data:
         for dep in data["dependencies"]:
             if "deployed_files" in dep:
-                dep["deployed_files"] = _filter_files_by_target(
+                filtered, mappings = _filter_files_by_target(
                     dep["deployed_files"], target
                 )
+                dep["deployed_files"] = filtered
+                all_mappings.update(mappings)
+
+    # Build the pack: metadata section (after filtering so we know if mapping
+    # occurred).
+    pack_meta: Dict = {
+        "format": fmt,
+        "target": target,
+        "packed_at": datetime.now(timezone.utc).isoformat(),
+    }
+    if all_mappings:
+        # Record the source prefixes that were remapped so consumers know the
+        # bundle paths differ from the original lockfile.  Use the canonical
+        # prefix keys from _CROSS_TARGET_MAPS rather than reverse-engineering
+        # them from file paths.
+        cross_map = _CROSS_TARGET_MAPS.get(target, {})
+        used_src_prefixes = set()
+        for original in all_mappings.values():
+            for src_prefix in cross_map:
+                if original.startswith(src_prefix):
+                    used_src_prefixes.add(src_prefix)
+                    break
+        pack_meta["mapped_from"] = sorted(used_src_prefixes)
+
+    pack_section = yaml.dump(
+        {"pack": pack_meta},
+        default_flow_style=False,
+        sort_keys=False,
+    )
 
     lockfile_yaml = yaml.dump(
         data, default_flow_style=False, sort_keys=False, allow_unicode=True

src/apm_cli/bundle/packer.py

@@ -5,12 +5,12 @@
 import tarfile
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import List, Optional
+from typing import Dict, List, Optional
 
 from ..deps.lockfile import LockFile, get_lockfile_path, migrate_lockfile_if_needed
 from ..models.apm_package import APMPackage
 from ..core.target_detection import detect_target
-from .lockfile_enrichment import enrich_lockfile_for_pack, _TARGET_PREFIXES, _filter_files_by_target
+from .lockfile_enrichment import enrich_lockfile_for_pack, _filter_files_by_target
 
 
 @dataclass
@@ -20,6 +20,8 @@ class PackResult:
     bundle_path: Path
     files: List[str] = field(default_factory=list)
     lockfile_enriched: bool = False
+    mapped_count: int = 0
+    path_mappings: Dict[str, str] = field(default_factory=dict)
 
 
 def pack_bundle(
@@ -38,7 +40,7 @@ def pack_bundle(
         project_root: Root of the project containing ``apm.lock.yaml`` and ``apm.yml``.
         output_dir: Directory where the bundle will be created.
         fmt: Bundle format  -- ``"apm"`` (default) or ``"plugin"``.
-        target: Target filter  -- ``"vscode"``, ``"claude"``, ``"all"``, or *None*
+        target: Target filter  -- ``"copilot"``, ``"claude"``, ``"all"``, or *None*
             (auto-detect from apm.yml / project structure).
         archive: If *True*, produce a ``.tar.gz`` and remove the directory.
         dry_run: If *True*, resolve the file list but write nothing to disk.
@@ -114,7 +116,7 @@ def pack_bundle(
     for dep in lockfile.get_all_dependencies():
         all_deployed.extend(dep.deployed_files)
 
-    filtered_files = _filter_files_by_target(all_deployed, effective_target)
+    filtered_files, path_mappings = _filter_files_by_target(all_deployed, effective_target)
     # Deduplicate while preserving order
     seen = set()
     unique_files: List[str] = []
@@ -133,14 +135,16 @@ def pack_bundle(
             raise ValueError(
                 f"Refusing to pack unsafe path from lockfile: {rel_path!r}"
             )
-        abs_path = project_root / rel_path
+        # For cross-target mapped files, verify the original (on-disk) path
+        disk_path = path_mappings.get(rel_path, rel_path)
+        abs_path = project_root / disk_path
         if not abs_path.resolve().is_relative_to(project_root_resolved):
             raise ValueError(
-                f"Refusing to pack path that escapes project root: {rel_path!r}"
+                f"Refusing to pack path that escapes project root: {disk_path!r}"
             )
         # deployed_files may reference directories (ending with /)
         if not abs_path.exists():
-            missing.append(rel_path)
+            missing.append(disk_path)
     if missing:
         raise ValueError(
             f"The following deployed files are missing on disk  -- "
@@ -155,6 +159,8 @@ def pack_bundle(
             bundle_path=bundle_dir,
             files=unique_files,
             lockfile_enriched=True,
+            mapped_count=len(path_mappings),
+            path_mappings=path_mappings,
         )
 
     # 5b. Scan files for hidden characters before bundling.
@@ -168,7 +174,8 @@ def pack_bundle(
 
     _scan_findings_total = 0
     for rel_path in unique_files:
-        src = project_root / rel_path
+        disk_path = path_mappings.get(rel_path, rel_path)
+        src = project_root / disk_path
         if src.is_symlink():
             continue
         if src.is_dir():
@@ -193,13 +200,21 @@ def pack_bundle(
     # 6. Build output directory
     bundle_dir = output_dir / f"{pkg_name}-{pkg_version}"
     bundle_dir.mkdir(parents=True, exist_ok=True)
+    bundle_dir_resolved = bundle_dir.resolve()
 
     # 7. Copy files preserving directory structure
     for rel_path in unique_files:
-        src = project_root / rel_path
+        # For cross-target mapped files, read from the original disk path
+        disk_path = path_mappings.get(rel_path, rel_path)
+        src = project_root / disk_path
         if src.is_symlink():
             continue  # Never bundle symlinks
         dest = bundle_dir / rel_path
+        # Defense-in-depth: verify mapped destination stays inside the bundle
+        if not dest.resolve().is_relative_to(bundle_dir_resolved):
+            raise ValueError(
+                f"Refusing to write outside bundle directory: {rel_path!r}"
+            )
         if src.is_dir():
             from ..security.gate import ignore_symlinks
             shutil.copytree(src, dest, dirs_exist_ok=True, ignore=ignore_symlinks)
@@ -215,6 +230,8 @@ def pack_bundle(
         bundle_path=bundle_dir,
         files=unique_files,
         lockfile_enriched=True,
+        mapped_count=len(path_mappings),
+        path_mappings=path_mappings,
     )
 
     # 10. Archive if requested