Skip to content

cratis extension update: move extension references to newer releases

cratis extension update moves a pin forward. It resolves each reference to the newest release in its range (the newest release when the model line names no version), shows how the contract changes, and checks every use in the model against the new contract before it writes screenplay.lock. See Manage extension packages for references, credentials and trust.

Terminal window
cratis extension update [SYSTEM] [--dry-run] [--allow-incompatible] [--root <PATH>] [--source <FOLDER|oci://HOST/PREFIX>]
Argument or option Meaning
SYSTEM The system whose extension to update. Every referenced extension when omitted. A system that names no extension fails Unresolvable.
--dry-run Report what would change; write nothing.
--allow-incompatible Write the lock even when a new contract no longer offers something the model uses.
--source Resolve from a vendored folder or a private mirror instead of the registry.

For each reference the newest release that satisfies its range is resolved, and checked for a valid signature, an allowed publisher, and the publisher the lock already records. Then:

  • Nothing newer. The reference is unchanged.
  • Outcomes. A reference ends as updated, would-update (with --dry-run), unchanged or failed.
  • A newer release. The report lists, against the contract the lock pins now:
    • what the new contract adds (+): abilities, triggers and components that are new;
    • what it no longer offers or offers differently (-): an ability, trigger or component that is gone, or whose typed inputs, returns, payload, properties or raised signals changed;
    • every use in the model the new contract does not offer (!), with the compiler’s diagnostic, for example a reaction that waits for a trigger the new contract no longer raises.
  • No incompatible use. The lock entry is moved: version, digest, contract hash and publisher.
  • An incompatible use. The lock is not changed for that reference unless you pass --allow-incompatible. The command exits with 5.

How a member compares is decided by what it offers, the same rule the compiler uses when one extension replaces another (provider compatibility): names and typed shapes, not where a member sits in the contract file, so a reordered contract is not a change. A reference that is not locked yet is pinned, with nothing to compare.

$ cratis extension update --dry-run
would-update cratis/stripe 2.4.0 sha256:5b0c…e1
cratis/stripe: 2.3.1 -> 2.4.0
+ ability 'RefundPayment' is new
! PLAY1112: Extension 'cratis/stripe' does not offer trigger 'PaymentSucceeded' used as 'Payments.PaymentSucceeded'.

With --dry-run the lock is untouched; the report still says what would happen.

The shared codes apply. 5 also covers an incompatible update that was not written.