Defame1297
1d07d1a76b
Capture Microsoft's Agent Package Manager (APM) — overview, install, config, CLI reference, registries/marketplace, monorepo shapes, testing/validation, troubleshooting, and examples — as structured reference docs under plugins/kyberforge/docs/research/docs/microsoft-apm/. Lays the groundwork for issue #88 (build agents/skills to execute a marketplace-to-APM conversion of this repo).
2.1 KiB
topic, source_keys
| topic | source_keys | |
|---|---|---|
| troubleshooting |
|
Manifest / lockfile ref mismatch
Happens when the version or ref declared in apm.yml no longer matches what's recorded in the stale apm.lock.yaml:
<owner>/<repo>: manifest ref 'v2' != lockfile ref 'v1'
N ref mismatch(es) -- run 'apm install' to update lockfile
Fix: run apm install to reconcile the lockfile with the manifest.
Missing lockfile
Occurs when a command that needs a resolved dependency graph runs before the first install:
lockfile not found at apm.lock.yaml; run 'apm install' to generate it
Lockfile version mismatch
The installed apm binary is older than the lockfile format it's being asked to read:
[x] apm.lock.yaml uses lockfile_version "2", this binary supports "1"
[>] Upgrade APM: see https://...
Fix: upgrade the APM binary to a version that supports the newer lockfile schema.
Content hash mismatch (possible supply-chain issue)
Raised when downloaded dependency bytes don't match the hash recorded in the lockfile:
[x] Content hash mismatch for <owner>/<repo>: expected <sha>, got <sha>.
The downloaded content differs from the lockfile record. This may
indicate a supply-chain attack. Use 'apm install --update' to accept
new content and update the lockfile.
This is a fail-closed integrity check — treat an unexpected occurrence as a security signal, not just a stale-cache annoyance. Only use apm install --update once you've confirmed the new upstream content is legitimate (e.g., a real re-tag), since it deliberately overwrites the recorded hash.
Dependency version conflicts
Direct and transitive dependency constraints are resolved by intersecting version ranges. Example: a manifest directly depends on acme/foo#^1.2.0, and a transitive dependency (acme/bar) pulls in acme/foo#^1.5.0. The effective constraint is the intersection, [>=1.5.0, <2.0.0), and APM picks the highest tag in that range. If the two constraints don't overlap at all (e.g. ^1.2.0 vs. ^2.0.0), resolution fails closed rather than silently picking one side — install errors out instead of guessing.