feat: add update input to refresh dependency refs (apm update)

[danielmeppiel]

TL;DR

Adds an update input. When update: 'true', the action runs apm update --yes in place of apm install — re-resolving branch/tag dependency refs to their latest matching commit and rewriting apm.lock.yaml — then runs the normal post-install steps. Closes #46.

Problem (WHY)

The action installs with apm install, which honours apm.lock.yaml and pins every dependency to the exact commit recorded there. That is reproducible by design, but it means a branch-tracked dependency such as github/awesome-copilot#main stays frozen at the lockfile commit forever. As the issue reports:

The only way to update those branch references is to manually run apm update

There was no first-class way to do that through the action. The only workaround (noted in the issue thread) was to hand-roll it through the generic script input:

with:
  script: custom-update   # -> apm.yml scripts: { custom-update: "apm update --yes" }

That works but is undiscoverable and forces every consumer to add a throwaway apm.yml script.

Approach (WHAT)

Add a dedicated boolean update input (default 'false'). When set, the action swaps the project-install verb from apm install to apm update --yes rather than running both — running install then update would resolve twice (install pins to the old lockfile, update immediately re-resolves). --yes skips the interactive plan-and-confirm gate for CI.

Because the swap happens inside the standard project-install block, update composes for free with the steps that run after it: audit-report, compile, script, additive dependencies, and pack.

It is mutually exclusive with the modes that either skip the project install or build from scratch with no lockfile to update: isolated, setup-only, bundle, bundles-file, and mode. Each combination fails fast with a clear consolidated error, matching the existing conflict-handling style in the action.

Implementation (HOW)

• action.yml — new update input with a description documenting the verb swap and the exclusivity set.
• src/runner.ts:
  • Read update once at the top of run().
  • Verb selection in the default install block: const projectVerb = update ? ['update', '--yes'] : ['install'];
  • Reject update in the mode and setup-only conflict lists, and add a dedicated update mutex guard for isolated / bundle / bundles-file.
• dist/index.js — rebuilt via npm run build (required for node-based actions; CI gates on dist freshness).
• Docs — README.md gets an "Update mode" usage section (with the scheduled auto-update + open-PR workflow) and an inputs-table row; CHANGELOG.md gets an [Unreleased] entry.

flowchart TD
    A[run] --> B{update input?}
    B -- "false (default)" --> C["apm install (lockfile-pinned)"]
    B -- "true" --> D["apm update --yes (re-resolve refs + rewrite lockfile)"]
    C --> E[audit-report / compile / script / pack]
    D --> E

Loading

Trade-offs

• Verb swap, not an extra step. Running update after install would double-resolve; swapping the verb is cleaner and faster. Trade-off: update is not composable with the no-install modes — surfaced as an explicit error instead of being silently ignored.
• Always --yes. The action is non-interactive by nature, so there is no value in exposing the confirm gate; an update run that reaches the action is an intentional refresh.
• isolated excluded. Isolated mode clears primitives and generates a fresh apm.yml with no pre-existing lockfile, so "update" has nothing to refresh; rejecting it avoids a confusing no-op.

Validation evidence

• npm run typecheck — clean.
• npm run lint (eslint) — clean.
• npm test — 193 passed (7 new tests in src/__tests__/runner.test.ts covering the verb swap, the install-default regression, compose-with-compile, and the four mutex rejections).
• npm run build — dist rebuilt and committed; CI dist-freshness mirror (git diff --name-only dist/ | grep -v '.d.ts.map$') is empty after the build.

How to test

# apm.yml with a branch-tracked dep, e.g. dependencies.apm: [github/awesome-copilot#main]
- uses: microsoft/apm-action@feat/apm-update-input
  with:
    update: 'true'
    audit-report: 'true'
- name: Open PR if changed
  uses: peter-evans/create-pull-request@v6
  with:
    title: 'chore: update AI agent assets'
    branch: apm/auto-update

Run once, merge; after upstream github/awesome-copilot#main advances, re-run — the PR now contains the refreshed assets (previously only the audit file changed).

[Copilot]

Pull request overview

Adds a first-class update input to the APM GitHub Action so workflows can refresh branch/tag-tracked dependency refs by running apm update --yes instead of apm install, updating apm.lock.yaml and then continuing with the normal post-install steps.

Changes:

• Introduce update input (default false) and enforce mutual exclusivity with no-install / from-scratch modes.
• Swap the project install verb to apm update --yes when update: 'true' and add unit tests for the main update + mutex scenarios.
• Update docs (README + CHANGELOG) and rebuild dist/.

Show a summary per file

File	Description
src/runner.ts	Implements update input, conflict handling, and verb swap to apm update --yes.
src/tests/runner.test.ts	Adds tests validating the verb swap and key mutual-exclusion errors.
README.md	Documents “Update mode” usage and adds update to the inputs table.
action.yml	Adds the update input with detailed behavior and exclusivity notes.
CHANGELOG.md	Adds an Unreleased entry describing the new update input.
dist/index.js	Rebuilt compiled action output including the new behavior.
dist/runner.d.ts	Updates generated type docs to mention update.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 5/7 changed files
• Comments generated: 1