@ankhorage/apm

Headless project update analysis, planning, execution, recovery, and verification.

Generated documentation

• Interactive documentation app
• Public API reference
• Component registry
• Architecture overview
• Module relationships
• Export graph
• apm sequence
• createNpmRegistryAvailabilityPort sequence
• inspectDependencyInventoryAsync sequence
• validatePackageUpdateMetadata sequence
• validateUpdateExtensionCapabilities sequence

Public API

Utilities

Publish the deterministic planning guarantees and native resolver matrix implemented by APM.

plan is read-only with respect to the inspected project. Package-manager resolution runs in a disposable staging directory and uses the selected project's native npm, pnpm, Yarn, or Bun resolver. Lifecycle scripts are disabled. Only reviewed manifest and lockfile changes are returned as serializable plan evidence; staging/cache/network effects remain outside the project tree.

The default dependency policy is conservative: only direct registry packages with a newer version satisfying their existing declared range are selected automatically. Latest majors, prereleases, downgrades and exact versions require explicit selections and APM never invents a new caret range. Explicit transitive selections remain lock-only; they are not promoted into root dependencies.

Native solver output is re-inspected through the same package-manager evidence adapters used by status. Duplicate package instances, peer contexts and workspace links keep their native identity. Unknown artifact sources, peer conflicts, unsupported lock/linker modes and unresolved targets are blockers rather than partial executable plans.

Package-owned migration/projection planners can request additional dependency selections. APM resolves those through a bounded fixed-point loop (four iterations by default). Conflicting owner requirements or non-convergence block the plan, and intermediate diffs are never exposed as an executable result. Required host/extension upgrades are explicit restart-and-re-plan boundaries.

Saved plans contain exact targets, reviewed file content/digests, resolved graph/artifact identities, ordered step prerequisites, executor identity and a semantic input fingerprint. Registry freshness timestamps are recorded separately from fingerprint validity: refreshing identical registry evidence does not invalidate an otherwise identical plan. Apply must revalidate the project fingerprint and executor instead of re-resolving latest.

Shipment effects remain separate from source updates. In particular, dependency graph changes are never assumed OTA-safe; without package/platform evidence APM records OTA eligibility as unknown.

Module: src/features/plan/constants/support.ts Source: src/features/plan/constants/support.ts:34:14

Publish the exact read-only status matrix proven by the evidence adapters.

Runtime: APM requires Node 24 or newer. Development uses Bun 1.4.2, but inspected customer projects may use any explicitly supported manager below.

Ordinary JavaScript and TypeScript projects require no ankh.config.json. APM derives package, workspace and package-manager evidence from Project Detector plus package-manager-native files. Detected non-JavaScript ecosystems remain inspection-only until an explicit APM adapter owns their dependency semantics; they never become a false complete/current result.

Install-root selection is evidence based. An explicit packageManager declaration wins over lockfile heuristics while stale lockfiles from other managers remain diagnostic evidence. If multiple manager lockfiles exist without an explicit selection, the root is conflicting and incomplete. Nested packages that carry their own manager/lock evidence become independent install roots rather than being folded into the parent workspace.

npm: package-lock v2 and v3 are parsed. The physical node_modules locations recorded by npm are checked without executing package code. package-lock v1 is detected but remains inspection-only. Duplicate versions remain separate physical package instances and dependency edges retain the instance identity they actually resolve to.

pnpm: lockfile v9 is parsed, including importer roots, package/snapshot instance identities, workspace links and peer-context suffixes. Installed state is confirmed from the pnpm virtual store lock when present; unknown/custom layouts stay explicit. Peer variants therefore remain distinct package instances rather than being collapsed by package name.

Yarn: Berry lock metadata v8 is parsed. nodeLinker: node-modules uses .yarn-state.yml; nodeLinker: pnp reads .pnp.data.json when present and never executes .pnp.cjs. An inlined PnP map therefore remains incomplete by design. Yarn Classic and Yarn's pnpm linker are detected but are not claimed as complete inventory modes in this release.

Bun: text bun.lock v2 is parsed. Bun's isolated .bun store and ordinary node_modules links are inspected as data. Hoisted lock-path keys retain nested and scoped package placements; installed identity/version mismatches remain explicit incomplete evidence. Binary bun.lockb and unknown lock versions are inspection-only.

Registry availability uses npm-compatible registries selected from project/user npmrc and environment overrides. Credentials are used only at the HTTP edge and are never returned in reports. Lookups deduplicate registry names, retain each instance's declared constraint, and run in batches of at most eight requests (configurable 1–64), with a default budget of 4096 names. Hosts can pass a configured registry availability port to statusProjectAsync; exceeding an explicit budget leaves uncached packages unknown rather than truncating them from the report. Offline cache misses and registry/auth/network failures make availability unknown.

status and plan are read-only project operations. Status reads manifests, lockfiles, installation metadata and registry data. Plan performs package-manager-native resolution only in disposable staging and returns reviewed diffs without writing the inspected project. Neither operation executes project lifecycle hooks or migrations. apply and verify remain separate roadmap operations.

Module: src/features/status/constants/support.ts Source: src/features/status/constants/support.ts:52:14

statusAsync(input: ApmStatusInput, ports: ApmStatusPorts) => Promise<ApmStatusResult>

Build evidence-based, serializable APM status without mutating the inspected project.

The use case separates Project Detector evidence, package-manager inventory, registry availability, and optional package-owned projection/migration evidence behind outbound ports. Missing or partial evidence makes currency unknown; it never becomes a green current result. Hosts can call this boundary without a terminal and can test it with deterministic fake ports.

Module: src/features/status/application/statusAsync.ts Source: src/features/status/application/statusAsync.ts:20:1 Related symbols: ApmStatusInput, ApmStatusPorts, ApmStatusResult