Updating a package

In AEL, the Agent Engineering Language, ael pack update moves one package that a scope already declares to another version that its requirement in pack.ael allows.

Usage

ael pack update server/http
ael pack update server/http --scope src/api
ael pack update server/http --json

Argument or option	Meaning
`<name>`	The package to update, as `pack.ael` names it.
`--scope <folder>`	Update the package in that folder's manifest. Without it, the manifest that covers the folder you are in.
`--json`	A machine-readable report of the change.

Which version

ael pack update chooses the highest version that the package's requirement allows. A requirement of "^1.2.0" allows versions from 1.2.0 up to, not including, 2.0.0; a version with a suffix after a - is chosen only when you name it exactly.

To move outside the range, change the requirement in pack.ael first, then run ael pack update. The Manifest reference describes every form of requirement.

Before anything changes

The command shows what the update brings:

the old and the new version;
packages that the new version adds or no longer needs;
changes of features, and any capability that a package now asks for.

A new capability is a request, never a grant, and it is always shown before the update is made.

What changes

pack.lock and .package/ of that scope change together, in one atomic step, after every new package file has been verified.
Only that scope changes. A folder with its own manifest keeps its own version, and a sibling folder is never touched.
Nothing in a package runs during the update.

If two requirements in one scope cannot both be met by the new version, the update stops and names both dependency paths. Nothing changes.

After updating

Run ael check and your tests: a new version may change an export your code uses. ael pack lock-diff shows exactly what changed between the old and the new pack.lock.

Adding a package: for a package the scope does not already declare.
Writing the lock file: how versions are resolved.