apm-cli 0.30.0__tar.gz → 0.32.0__tar.gz

{apm_cli-0.30.0/src/apm_cli.egg-info → apm_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.30.0
+Version: 0.32.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -67,7 +67,7 @@ Requires-Dist: pylint>=3.0.0; extra == "dev"
 Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Requires-Dist: mutmut==3.6.0; extra == "dev"
 Provides-Extra: build
-Requires-Dist: pyinstaller>=6.0.0; extra == "build"
+Requires-Dist: pyinstaller>=6.17.0; extra == "build"
 Dynamic: license-file
 
 # APM – Agent Package Manager
@@ -78,7 +78,7 @@ Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent c
 
 GitHub Copilot | Claude Code | Grok Build | Cursor | OpenCode | Codex | Gemini | Windsurf | Kiro
 
-**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)**
+**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
 
 ---
 
@@ -196,7 +196,7 @@ For standalone installations, `apm self-update` reuses the matching platform ins
 You do not need Homebrew to use APM.
 
 <details>
-<summary>Other install methods: pip and Scoop</summary>
+<summary>Other install methods: pip, WinGet, and Scoop</summary>
 
 #### Linux / macOS
 
@@ -207,6 +207,11 @@ pip install apm-cli
 
 #### Windows
 
+```powershell
+# WinGet
+winget install --id Microsoft.APM --exact --source winget
+```
+
 ```powershell
 # Scoop
 scoop bucket add apm https://github.com/microsoft/scoop-apm
@@ -251,7 +256,7 @@ Use agentrc to author high-quality instructions, then package them with APM to s
 
 Created by [@danielmeppiel](https://github.com/danielmeppiel). Maintained by [@danielmeppiel](https://github.com/danielmeppiel) and [@sergio-sisternes-epam](https://github.com/sergio-sisternes-epam).
 
-- [v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)
+- [Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)
 - [Discussions](https://github.com/microsoft/apm/discussions)
 - [Contributing](CONTRIBUTING.md)
 - [AI Native Development guide](https://danielmeppiel.github.io/awesome-ai-native) — a practical learning path for AI-native development

{apm_cli-0.30.0 → apm_cli-0.32.0}/README.md

@@ -6,7 +6,7 @@ Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent c
 
 GitHub Copilot | Claude Code | Grok Build | Cursor | OpenCode | Codex | Gemini | Windsurf | Kiro
 
-**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)**
+**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
 
 ---
 
@@ -124,7 +124,7 @@ For standalone installations, `apm self-update` reuses the matching platform ins
 You do not need Homebrew to use APM.
 
 <details>
-<summary>Other install methods: pip and Scoop</summary>
+<summary>Other install methods: pip, WinGet, and Scoop</summary>
 
 #### Linux / macOS
 
@@ -135,6 +135,11 @@ pip install apm-cli
 
 #### Windows
 
+```powershell
+# WinGet
+winget install --id Microsoft.APM --exact --source winget
+```
+
 ```powershell
 # Scoop
 scoop bucket add apm https://github.com/microsoft/scoop-apm
@@ -179,7 +184,7 @@ Use agentrc to author high-quality instructions, then package them with APM to s
 
 Created by [@danielmeppiel](https://github.com/danielmeppiel). Maintained by [@danielmeppiel](https://github.com/danielmeppiel) and [@sergio-sisternes-epam](https://github.com/sergio-sisternes-epam).
 
-- [v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)
+- [Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)
 - [Discussions](https://github.com/microsoft/apm/discussions)
 - [Contributing](CONTRIBUTING.md)
 - [AI Native Development guide](https://danielmeppiel.github.io/awesome-ai-native) — a practical learning path for AI-native development

{apm_cli-0.30.0 → apm_cli-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.30.0"
+version = "0.32.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -56,7 +56,7 @@ dev = [
     "mutmut==3.6.0",
 ]
 build = [
-    "pyinstaller>=6.0.0",
+    "pyinstaller>=6.17.0",
 ]
 
 [project.scripts]

apm_cli-0.32.0/src/apm_cli/adopt/__init__.py

@@ -0,0 +1 @@
+"""Metadata-only onboarding of existing local packages."""

apm_cli-0.32.0/src/apm_cli/adopt/discovery.py

@@ -0,0 +1,248 @@
+"""Read native target locations without importing, converting, or executing content.
+
+The profile inversion follows @chkp-roniz's discovery work in PR #2857; the
+onboarding result is restricted to existing installable local package roots.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from apm_cli.compilation.root_context_protection import catalog_root_context_markers
+from apm_cli.core.deployment_ledger import DeploymentLedgerCodec
+from apm_cli.core.deployment_state import LocatorKind
+from apm_cli.core.target_detection import SIGNAL_WHITELIST
+from apm_cli.deps.lockfile import LockFile, resolve_lockfile_path_for_read
+from apm_cli.integration.targets import (
+    KNOWN_TARGETS,
+    active_targets,
+    active_targets_user_scope,
+    apply_legacy_skill_paths,
+)
+from apm_cli.models.dependency import DependencyReference
+from apm_cli.models.validation import validate_apm_package
+
+from .manifest_edit import local_directory, package_entry, read_manifest
+from .safety import MAX_DEPTH, MAX_ENTRIES, checked_file, checked_path, checked_tree
+
+
+def _inventory(root: Path, *, user_scope: bool) -> list[tuple[Path, str]]:
+    """Invert scope-resolved profiles, including legacy skill roots, once per path."""
+    profiles = (
+        active_targets_user_scope("all", create_config=False)
+        if user_scope
+        else active_targets(root, "all", create_config=False)
+    )
+    profiles = profiles + apply_legacy_skill_paths(profiles)
+    directories: dict[Path, str] = {}
+    shallow: set[Path] = set()
+    for profile in profiles:
+        base = root / profile.root_dir
+        shallow.add(base)
+        for primitive, mapping in profile.primitives.items():
+            directory = root / (mapping.deploy_root or profile.root_dir) / mapping.subdir
+            if mapping.subdir:
+                directories[directory] = primitive
+            else:
+                shallow.add(directory)
+    found: dict[Path, str] = {}
+    for _, kind, relative in SIGNAL_WHITELIST:
+        if kind == "file":
+            candidate = root / relative
+            if candidate.exists() or candidate.is_symlink():
+                found[candidate] = "native"
+    for name in catalog_root_context_markers():
+        candidate = root / name
+        if candidate.exists() or candidate.is_symlink():
+            found[candidate] = "native"
+    if (root / "SKILL.md").exists():
+        found[root] = "package"
+    count = 0
+    pending = [(directory, kind, 0) for directory, kind in directories.items()]
+    pending.extend((directory, "native", MAX_DEPTH) for directory in shallow)
+    visited: set[Path] = set()
+    while pending:
+        directory, kind, depth = pending.pop()
+        if directory in visited:
+            continue
+        visited.add(directory)
+        try:
+            checked_path(directory, root)
+        except ValueError:
+            if directory.exists() or directory.is_symlink():
+                found[directory] = "unsafe"
+            continue
+        if not directory.is_dir():
+            continue
+        if (directory / "SKILL.md").exists() or (directory / "apm.yml").exists():
+            found[directory] = "package"
+            continue
+        for child in directory.iterdir():
+            count += 1
+            if count > MAX_ENTRIES:
+                raise ValueError(
+                    "Discovery entry limit exceeded. Narrow the project before retrying."
+                )
+            if child.is_symlink():
+                found[child] = "unsafe"
+            elif child.is_file():
+                found[child] = kind
+            elif child.is_dir() and depth < MAX_DEPTH:
+                pending.append((child, kind, depth + 1))
+            elif not child.is_dir() or kind != "native":
+                found[child] = "unsafe"
+    return sorted(found.items(), key=lambda item: item[0].as_posix())
+
+
+def _managed_paths(consumer: Path, root: Path) -> set[Path]:
+    """Read actual deployment claims through the canonical ledger codec."""
+    path = resolve_lockfile_path_for_read(consumer, read_only=True)
+    checked_path(path, root)
+    if not path.exists():
+        return set()
+    checked_file(path, root)
+    lockfile = LockFile.read(path)
+    if lockfile is None:
+        return set()
+    result: set[Path] = set()
+    for record in DeploymentLedgerCodec.from_lockfile(lockfile).records.values():
+        if record.locator.kind is LocatorKind.URI:
+            continue
+        profile = KNOWN_TARGETS.get(record.locator.target, next(iter(KNOWN_TARGETS.values())))
+        if record.locator.kind is LocatorKind.TARGET_RELATIVE:
+            profile = profile.for_scope(user_scope=True)
+            if profile is None:
+                continue
+        candidate = DeploymentLedgerCodec.resolve_locator(
+            record.locator, project_root=root, target=profile
+        )
+        checked_path(candidate, root)
+        result.add(candidate)
+    return result
+
+
+def discover(root: Path, manifest: Path, *, user_scope: bool = False) -> dict[str, Any]:
+    """Build a read-only report using normal package admission and identities."""
+    _, references, _ = read_manifest(manifest, root)
+    consumer = manifest.parent
+    declared = {local_directory(ref, consumer) for ref in references if ref.is_local}
+    slots: dict[Path, set[Path | str]] = {}
+    for ref in references:
+        if not ref.is_marketplace:
+            identity = local_directory(ref, consumer) if ref.is_local else ref.get_unique_key()
+            slot = ref.get_install_path(consumer / "apm_modules")
+            slots.setdefault(slot, set()).add(identity)
+    managed = _managed_paths(consumer, root)
+    findings: list[dict[str, Any]] = []
+    for slot, identities in slots.items():
+        if len(identities) > 1:
+            findings.append(
+                {
+                    "path": manifest.relative_to(root).as_posix(),
+                    "kind": "manifest",
+                    "status": "unsafe",
+                    "reason": (
+                        "Existing dependency install identity collision at "
+                        f"{slot.relative_to(consumer).as_posix()}. "
+                        "Remove conflicting references and retry."
+                    ),
+                    "dependency": None,
+                }
+            )
+    supported: list[tuple[dict[str, Any], Path, Path]] = []
+    for path, kind in _inventory(root, user_scope=user_scope):
+        finding = {
+            "path": path.relative_to(root).as_posix() if path.is_relative_to(root) else str(path),
+            "kind": kind,
+            "status": "unsupported",
+            "reason": "Loose native content is not a package. Prepare a supported package manually.",
+            "dependency": None,
+        }
+        findings.append(finding)
+        try:
+            checked_path(path, root)
+            if kind == "unsafe":
+                raise ValueError("Unsafe path; use a regular directory within the discovery root.")
+            if any(path == owned or path.is_relative_to(owned) for owned in managed) or (
+                path.is_dir() and any(owned.is_relative_to(path) for owned in managed)
+            ):
+                finding.update(
+                    status="managed", reason="Already managed by the installation ledger."
+                )
+                continue
+            if kind != "package":
+                checked_file(path, root)
+                continue
+            if path == consumer or consumer.is_relative_to(path):
+                finding.update(
+                    status="unsafe",
+                    reason="Source contains the consumer; self-dependencies are refused.",
+                )
+                continue
+            checked_tree(path, root)
+            if (path / "apm.yml").exists():
+                read_manifest(path / "apm.yml", root)
+            admission = validate_apm_package(path, read_only=True)
+            if not admission.is_valid:
+                finding["reason"] = (
+                    "Existing package admission rejected this directory. Prepare it manually."
+                )
+                continue
+            entry = package_entry(path, consumer, user_scope=user_scope)
+            finding["dependency"] = entry
+            if path.resolve() in declared:
+                finding.update(
+                    status="already-declared", reason="Existing dependency and options preserved."
+                )
+                continue
+            if any(path.is_relative_to(other) or other.is_relative_to(path) for other in declared):
+                finding.update(
+                    status="unsafe", reason="Package overlaps an existing dependency source."
+                )
+                continue
+            ref = DependencyReference.parse_from_dict(entry)
+            slot = ref.get_install_path(consumer / "apm_modules")
+            finding.update(
+                status="supported",
+                reason="Existing local package; only a dependency will be added.",
+            )
+            supported.append((finding, path, slot))
+        except (ValueError, OSError) as exc:
+            finding.update(
+                status="unsafe",
+                reason=f"{type(exc).__name__}: package/path rejected. Repair it and retry.",
+            )
+    by_slot: dict[Path, list[dict[str, Any]]] = {}
+    for finding, path, slot in supported:
+        by_slot.setdefault(slot, []).append(finding)
+        if slot in slots and slots[slot] != {path.resolve()}:
+            finding.update(
+                status="unsafe", reason="Install identity collision with an existing dependency."
+            )
+    for group in by_slot.values():
+        if len(group) > 1:
+            for finding in group:
+                finding.update(
+                    status="unsafe",
+                    reason="Install identity collision: packages share an install path.",
+                )
+    for index, (finding, path, _) in enumerate(supported):
+        for other_finding, other, _ in supported[index + 1 :]:
+            if path.is_relative_to(other) or other.is_relative_to(path):
+                finding.update(
+                    status="unsafe",
+                    reason="Overlapping package roots cannot be onboarded together.",
+                )
+                other_finding.update(
+                    status="unsafe",
+                    reason="Overlapping package roots cannot be onboarded together.",
+                )
+    return {
+        "scope": "global" if user_scope else "project",
+        "root": str(root),
+        "manifest": str(manifest),
+        "findings": findings,
+        "additions": [item["dependency"] for item in findings if item["status"] == "supported"],
+        "applied": False,
+    }

apm_cli-0.32.0/src/apm_cli/adopt/manifest_edit.py

@@ -0,0 +1,76 @@
+"""Consumer manifest planning: preserve author metadata; never edit sources."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from apm_cli.deps.path_anchoring import _join
+from apm_cli.models.apm_package import APMPackage
+from apm_cli.models.dependency import DependencyReference
+from apm_cli.models.dependency.object_fields import local_path_apm_yml_entry
+from apm_cli.utils.yaml_io import (
+    load_yaml_roundtrip,
+    write_yaml_text_atomic,
+    yaml_roundtrip_to_str,
+)
+
+from .safety import checked_file, checked_path
+
+
+def read_manifest(path: Path, root: Path) -> tuple[Any, list[DependencyReference], bytes | None]:
+    """Read and validate existing metadata; do not silently replace invalid YAML."""
+    checked_path(path, root)
+    if not path.exists():
+        return {"name": "onboarded-project", "version": "1.0.0"}, [], None
+    checked_file(path, root)
+    original = path.read_bytes()
+    data = load_yaml_roundtrip(path)
+    if not isinstance(data, dict):
+        raise ValueError("Invalid apm.yml: expected a mapping. Repair the manifest and retry.")
+    for group in ("dependencies", "devDependencies"):
+        dependencies = data.get(group, {})
+        if not isinstance(dependencies, dict):
+            raise ValueError(f"Invalid apm.yml: {group} must be a mapping.")
+        for kind, entries in dependencies.items():
+            if not isinstance(entries, list) or any(
+                not isinstance(entry, (str, dict)) for entry in entries
+            ):
+                raise ValueError(f"Invalid apm.yml: {group}.{kind} must be a list of references.")
+    package = APMPackage.from_mapping(data, package_path=path.parent, create_config=False)
+    references = package.get_all_apm_dependencies()
+    return data, references, original
+
+
+def local_directory(reference: DependencyReference, consumer: Path) -> Path:
+    """Resolve a direct local reference through the existing path anchoring owner."""
+    return _join(consumer, reference.local_path)
+
+
+def package_entry(source: Path, consumer: Path, *, user_scope: bool) -> dict[str, object]:
+    """Emit the canonical local object form, absolute at user scope."""
+    raw = source.as_posix() if user_scope else "./" + source.relative_to(consumer).as_posix()
+    reference = DependencyReference.parse(raw)
+    return local_path_apm_yml_entry(reference.local_path, None, None, None)
+
+
+def write_manifest(
+    path: Path,
+    root: Path,
+    data: Any,
+    additions: list[dict[str, object]],
+    original: bytes | None,
+) -> bool:
+    """Commit only missing dependency entries, atomically, after revalidation."""
+    if not additions:
+        return False
+    checked_path(path, root)
+    current = path.read_bytes() if path.exists() else None
+    if current != original:
+        raise ValueError("apm.yml changed during discovery. Review and retry.")
+    data.setdefault("dependencies", {}).setdefault("apm", []).extend(additions)
+    content = yaml_roundtrip_to_str(data)
+    checked_path(path.parent, root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_yaml_text_atomic(path, content)
+    return True

apm_cli-0.32.0/src/apm_cli/adopt/materialize.py

@@ -0,0 +1,32 @@
+"""Apply an approved manifest delta, never source or deployment content."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from apm_cli.install.locking import lifecycle_operation
+
+from .discovery import discover
+from .manifest_edit import read_manifest, write_manifest
+
+
+def apply_report(report: dict[str, Any]) -> dict[str, Any]:
+    """Revalidate the consented plan under the normal lifecycle lock."""
+    if any(item["status"] == "unsafe" for item in report["findings"]):
+        raise ValueError(
+            "Unsafe paths or install identity collisions found. Repair them and rediscover."
+        )
+    if not report["additions"]:
+        return report
+    root = Path(report["root"])
+    manifest = Path(report["manifest"])
+    with lifecycle_operation():
+        data, _, original = read_manifest(manifest, root)
+        current = discover(root, manifest, user_scope=report["scope"] == "global")
+        if current != report:
+            raise ValueError(
+                "Discovery changed since the preview. Review the new report and retry."
+            )
+        current["applied"] = write_manifest(manifest, root, data, current["additions"], original)
+    return current

apm_cli-0.32.0/src/apm_cli/adopt/render.py

@@ -0,0 +1,35 @@
+"""Onboarding presentation at the CommandLogger boundary."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from apm_cli.core.command_logger import CommandLogger
+from apm_cli.utils.yaml_io import yaml_to_str
+
+
+class DiscoveryLogger(CommandLogger):
+    """Render inventory without exposing file contents or native secrets."""
+
+    def report(self, report: dict[str, Any], fmt: str) -> None:
+        """Render one complete report; machine stdout contains only data."""
+        if fmt != "text":
+            content = json.dumps(report, indent=2) + "\n" if fmt == "json" else yaml_to_str(report)
+            sys.stdout.write(content)
+            return
+        self.info(f"Discovery ({report['scope']}): {report['root']}")
+        for finding in report["findings"]:
+            self.info(f"{finding['status']}: {finding['path']} -- {finding['reason']}")
+        for entry in report["additions"]:
+            self.info(f"apm.yml dependencies.apm: path: {entry['path']}")
+        if report["applied"]:
+            install = "apm install --global" if report["scope"] == "global" else "apm install"
+            self.success(f"Updated consumer apm.yml. Run '{install}' separately.")
+        elif report["additions"]:
+            self.info(
+                "Read-only preview. Use --apply to add these dependencies after confirmation."
+            )
+        else:
+            self.info("No missing supported package dependencies; no manifest changes.")

apm_cli-0.32.0/src/apm_cli/adopt/safety.py

@@ -0,0 +1,51 @@
+"""Bounded, non-following filesystem reads for onboarding."""
+
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+from apm_cli.utils.path_security import ensure_path_within, has_symlink_component
+
+MAX_ENTRIES = 2000
+MAX_FILE_BYTES = 1024 * 1024
+MAX_DEPTH = 16
+
+
+def checked_path(path: Path, root: Path) -> Path:
+    """Reject symlinks and escapes before inspecting a discovery path."""
+    if has_symlink_component(root, path):
+        raise ValueError("Symlinked paths are not onboarded; use a regular directory.")
+    return ensure_path_within(path, root)
+
+
+def checked_file(path: Path, root: Path) -> None:
+    """Bound parser inputs and reject device files without opening them."""
+    checked_path(path, root)
+    info = path.stat()
+    if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_FILE_BYTES:
+        raise ValueError("Not a regular file or exceeds the 1 MiB discovery read limit.")
+
+
+def checked_tree(path: Path, root: Path) -> None:
+    """Validate package trees without reading payloads or following symlinks."""
+    checked_path(path, root)
+    pending = [(path, 0)]
+    count = 0
+    while pending:
+        directory, depth = pending.pop()
+        if depth > MAX_DEPTH:
+            raise ValueError(
+                "Package exceeds the discovery depth limit; prepare a smaller package."
+            )
+        for child in directory.iterdir():
+            count += 1
+            if count > MAX_ENTRIES:
+                raise ValueError(
+                    "Package exceeds the discovery entry limit; prepare a smaller package."
+                )
+            checked_path(child, root)
+            if child.is_dir():
+                pending.append((child, depth + 1))
+            else:
+                checked_file(child, root)

{apm_cli-0.30.0 → apm_cli-0.32.0}/src/apm_cli/agent_plugins/projection.py

@@ -10,13 +10,16 @@ from .errors import AgentPluginManifestAuthorityError
 from .ir import AgentPlugin, thaw_frozen_json
 
 
-def project_agent_plugin_package(plugin: AgentPlugin) -> APMPackage:
+def project_agent_plugin_package(plugin: AgentPlugin, *, create_config: bool = True) -> APMPackage:
     """Project canonical Agent Plugin facts into the compatibility package model.
 
     Portable identity comes only from ``plugin.identity``. APM-owned manifest
     fields come only from ``plugin.apm_configuration``. Component facts remain
     attached through the canonical frozen IR rather than being reparsed from
     ``plugin.json``, ``mcp.json``, or the package filesystem.
+
+    Read-only admission passes ``create_config=False`` to avoid initializing
+    user configuration while projecting existing source metadata.
     """
     data = _project_apm_configuration(plugin)
     identity = plugin.identity
@@ -41,6 +44,7 @@ def project_agent_plugin_package(plugin: AgentPlugin) -> APMPackage:
             package_path=plugin.root,
             source_path=plugin.root,
             manifest_path=manifest_path,
+            create_config=create_config,
         )
     except (TargetResolutionError, ValueError) as exc:
         raise AgentPluginManifestAuthorityError(