Skip to content

cratis extension verify: check an extension package before it is published or loaded

cratis extension verify says whether an extension package is correct, with exact diagnostics, before it is published or loaded. A package created by cratis extension new passes without edits. See Manage extension packages for the other cratis extension commands.

Terminal window
cratis extension verify [TARGET] [--range <RANGE>] [--baseline <FOLDER>] [--strict]
[--root <PATH>] [--source <FOLDER|oci://HOST/PREFIX>] [-o|--output table|json]

TARGET is one of:

Target What is verified
A folder (the default is the current directory) The folder as it ships. The contract is contract.play at its root, or in its extension/ folder as in an OCI artifact. A path to contract.play verifies its folder.
A package reference A catalog short name, an OCI reference or an npm package, as cratis extension restore resolves them, with the same registries, credentials and trust. The package is fetched, laid out as it ships and verified. --range picks the release; the version screenplay.lock pins is the default when it pins the reference, else the latest.

Every check always appears in the report with a status, so a check that did not run is never mistaken for one that passed.

Status Meaning
passed The check ran and found nothing wrong.
failed The check found at least one error.
skipped The check applies to the package but could not run. It is never reported as a pass, and --strict fails it.
notapplicable The package has nothing for the check to look at.
Check What it checks Diagnostics
contract contract.play compiles with no errors and no warnings. EXTV001 the package holds no contract; the compiler’s own codes, PLAY0998 and PLAY1100 to PLAY1112, with the line. A warning is reported as an error.
manifest A display name, a description and an icon are present. Requirements are stated. The icon and every marketplace image exist, are png, jpg, webp or svg by their content (not only their name) and are within the size limits. Captions are present. PLAY0999 a display name, description or icon is missing; EXTV010 the contract states no requires; EXTV011 an icon or image is not a supported format, or not the format its name says; EXTV012 an icon is over 256 KB or an image over 2 MB; EXTV013 an image caption is blank; EXTV014 an image has no caption (a warning); PLAY0998 an icon or image is not in the package or is outside it.
contents Everything the contract declares is shipped, and nothing it ships is undeclared. EXTV020 the declared backend is not in the package; EXTV021 a React or mount component is declared but the contract names no frontend; EXTV022 a file is shipped that the contract does not declare; PLAY0998 the declared frontend is not in the package.
placeholders Every React or mount component has a placeholder, and each is static HTML: no <script>, no event handler attributes, no javascript: URLs and no external references (styles inline, images as data: URIs), within 256 KB. PLAY1102 a component has no placeholder; PLAY1113 the placeholder is not static; EXTV030 it is over its limit; PLAY0998 it is not in the package.
frontend Each component registers as its declared kind and passes the Scene conformance kit. EXTV060 the check could not run. See What does not run yet.
backend The backend starts in its tier and completes the protocol handshake against the contract. EXTV070 the check could not run. See What does not run yet.
digests The package is the one screenplay.lock pins: its digest and its contract hash. Applies to a reference the lock pins. EXTV040 the digest differs; EXTV041 the contract hash differs.
compatibility The compiler can use the package as a provider. EXTV050 the contract requires a Screenplay version the compiler is not in; EXTV051 with --baseline, the package no longer offers an ability, trigger, component, property or signal the baseline did.

The size limits are 256 KB for an icon, 2 MB for a marketplace image and 256 KB for a placeholder.

The contents check holds a folder to what it ships. A project folder, as cratis extension new creates it, also holds sources, specifications and scripts the build does not ship. Name them in .extensionignore in the package folder, one pattern per line: src/ ignores a folder, Dockerfile a file, *.sln a file name at the root and **/Specs/ a folder at any depth. Lines starting with # are comments. .git/, node_modules/, bin/, obj/, .ai-work/, .extensionignore, and README*, LICENSE*, NOTICE* and CHANGELOG* are always ignored. Files in the folder of the declared frontend entry or backend assembly are shipped with it and need no declaration. A package fetched from a registry holds exactly what it ships, so it needs none.

The frontend and backend checks have to run the package’s code, which the CLI does not do yet. They are reported as skipped with EXTV060 and EXTV070, never as passed. Run the conformance kit in the package’s own specifications, and Stage performs the handshake when it loads the package. --strict fails a package until these checks can run.

The report is human-readable by default and machine-readable with -o json (or --output json): the target, whether it passed and, for each check, its status and diagnostics (check, code, severity, message, path and line).

Code Meaning
0 The package is correct: no check failed. With --strict, also no warning and no check that could not run.
5 A check failed, or the target is a path to a folder that does not exist.
1 The reference could not be resolved.
2 A registry could not be reached.
4 A registry refused the credentials.

Other failures to fetch a package, such as a signature or publisher the trust rules refuse, are 5.

Terminal window
cratis extension verify ./Stripe
cratis extension verify ghcr.io/acme/extension-stripe --range "^2"
cratis extension verify ./Stripe --baseline ./previous-release --strict -o json