jadpo package

Show, check, import and install packages.

new <Name> --library or --provider starts a package in its own repository, in a folder named as the registry writes the name, and it passes check as written; --publisher <handle> names who publishes it, and without it the command asks on a terminal and leaves the key out elsewhere. show <name> prints a package's description, licence, version, kind and public surface (area 11), installed in packages/ or the app's own in shared/providers/; show <name> <declaration> prints one operation, function, type or failure in full with its file, and --guide prints the package's GUIDE.md. check, run in a package's own repository, checks it as the app's own integration, runs the publishing bar (no errors, a description on every public declaration, the examples in its descriptions run as tests, its tests, a version its changes since the last tag allow, a changelog that says why), prints the release's facts and change record, and writes surface.jadpo_record and CHANGELOG.md's new section. verify <folder> [--previous <folder>] [--publisher <handle>] runs the same bar as the registry's verifier does, on a commit as it stands, writing nothing, and --json gives all a release shows; --serve answers the registry, in a sandbox with no network. import openapi <file> reads an OpenAPI 3 document, as JSON, once and offline, into the app's own integration in shared/providers///: another Jadpo application's exactly, from its x-jadpo fields, any other's by its formats, with what it leaves out listed to check; importing again merges, keeping corrections. protocol <document> checks a registry's OpenAPI document, a file or an address, against the registry protocol (area 11), exiting 1 if it differs. record <connection> <resource>.<operation> calls the provider's sandbox once, never live, with --input as the operation's input, checks the answer against the operation's types and keeps it in the package's recordings/ with its values as placeholders; jadpo test and check then decode it with every decoder. add installs a package from its folder or from a git repository at a release tag (<repository>@v<version>) into packages/ and jadpo.lock, once its surface matches its code; update moves one to its newest release, listing what changed; remove takes out one the app no longer uses; link compiles the app against a package's live checkout, which CI refuses, and unlink goes back to the installed version. recipe <package> <recipe> --into <domain> copies one of a package's recipes into a domain, where it becomes the app's own code, never writing over a file it has. add @<publisher>/<name> installs that exact name from the registry, checked against its public log; update then takes the newest release at least three days old, or an urgent one at once, and --to <version> takes that release at once. search <words> finds packages and standard-library functions for a need, audit lists the advisories against the app's packages and whether the app reaches each, publish [--dry-run] asks the registry to release the package from its pushed tag, and preview serves the package's registry page on this machine.

Also: jadpo packages.

jadpo package <action> [name] [declaration]

Arguments

• action: What to do: show, check, verify, import, record, conform, protocol, add, update, remove, link, unlink, recipe, search, audit, publish or preview
• name (optional): The package, such as holidays; for check, verify, link and preview, its folder; for add, @/, its folder or @v; for search, the words; for import, openapi; for record, the connection; for conform and recipe, the package; for protocol, the registry's OpenAPI document, a file or an address
• declaration (optional): One of its declarations, such as uk.dates; for import, the file; for record, the operation, as .; for conform, the capability, ai; for recipe, the recipe

Flags

• --guide: Print the package's GUIDE.md
• --as <name>: For import: its name, such as Tidepool.v1
• --input <json>: For record: the operation's input as JSON
• --live: For conform: run it against the real API
• --into <domain>: For recipe: the domain it is copied into
• --previous <folder>: For verify: the release before this one
• --publisher <handle>: For verify and new: who publishes it
• --library: For new: a package of code an app calls
• --provider: For new: a package that describes an API
• --serve: For verify: answer the registry
• --listen <address>: For --serve: where to listen
• --registry <url>: For --serve: where old archives come from
• --no-run: For verify: run none of the package's code
• --to <version>: The release to take; for search, a type
• --from <type>: For search: the type a function takes
• --kind <kind>: For search: library or provider
• --dry-run: For publish: check, and publish nothing

On every command

• --json: Print data for tools instead of text
• --full: Show everything a report shortens
• --help: Show every flag, with examples
• --color <when>: Choose when to use colour

jadpo package --json writes one JSON document to standard output instead of text, with the same exit code. The document has schemaVersion, command ("package"), ok, data (what the command produced, null when it failed) and diagnostics (each error with its rule, reason, next and help). A command that needs a terminal refuses --json and names the flags that do the same job.

Examples

# Start a library package in its own repositoryjadpo package new TidePool --library --publisher @acme# See what the holidays package offersjadpo package show holidays# See one of its functions in fulljadpo package show holidays uk.dates# Run the publishing bar in a package's own repositoryjadpo package check# Check a release as the registry does, against the one before itjadpo package verify ../holidays --previous ../holidays-2.0.0 --json# Import another Jadpo application's APIjadpo package import openapi ../orders/build/openapi/main.json# Install a package from the registryjadpo package add @acme/holidays# Take a release before its three days are upjadpo package update holidays --to 2.1.0# Find what answers a needjadpo package search "uk bank holidays"# See whether an advisory touches what the app reachesjadpo package audit# Run the registry's verifier on the pushed tag, publishing nothingjadpo package publish --dry-run# See the package's registry page before publishingjadpo package preview# Install a package from its git repository at a releasejadpo package add github.com/acme/holidays@v2.1.0# Try the app against a package's checkout before it is releasedjadpo package link ../holidays# Copy a package's recipe into a domainjadpo package recipe holidays closures --into scheduling# Record a sandbox's answer to confirm an operationjadpo package record holidays dates.list --input '{"year": 2027}'

Errors

• cli.package_arguments: A jadpo package command names no action, one it doesn't have, or a package the project doesn't hold
• cli.package_not_openapi: A file given to jadpo package import is JSON but not an OpenAPI 3.0 or 3.1 document
• cli.package_unreadable: A file given to jadpo package import isn't there, can't be read, or isn't JSON
• recording.failed: A recording by jadpo package record or jadpo ai record got no answer worth keeping from the sandbox or the model, or its call couldn't be made
• recording.refused: A recording was refused before anything was sent, because its connection would call a live API or has nothing set for its sandbox, its package is installed, or there is nothing to ask its prompt with
• conform.failed: A package's answers to jadpo package conform don't fit the capability it fills, or the suite couldn't run
• conform.refused: The conformance suite wasn't sent to the provider's live API, because the app has no connection to the package, nothing sets the connection's credential or address, or ai: doesn't ask its models through it
• install.fetch_failed: Installing a package couldn't read its git repository, or found no release there at the tag you gave
• install.in_use: Package to remove is still used by the app
• install.not_in_registry: The registry has no package of the name you gave, or no such release of it
• install.not_proved: The registry's answers don't prove the release is the one in its public log
• install.surface_mismatch: The package you are installing has code that offers something different from its committed surface.jadpo_record
• install.yanked: The release you asked for has been yanked, so it can't be newly installed
• package.advisory: An advisory is against a declaration of an installed package that the app reaches
• package.name_taken: A package has the same name as one of the app's domains, libraries, declarations or other packages
• publish.behaviour_changed: An example or test of a package's last release fails against its new version, and the change isn't marked a fix
• publish.breaking_change: A package's new version changes or removes something its last release offered, within the same major version
• publish.changelog_missing: Package's changelog doesn't say why its new version is released
• publish.description_missing: Package's public declaration has no description
• publish.example_failed: Example in a package's description doesn't compile or doesn't hold
• publish.example_missing: Package's function has no example, or a failure it raises is shown by none
• publish.failed: The registry's verifier refused the release
• publish.licence_proprietary: A package's licence is Licence.proprietary, which the public registry refuses
• publish.not_at_tag: What jadpo package publish would ask for isn't a pushed v<version> tag whose commit is the one checked out
• publish.publisher_mismatch: A release names another publisher than the one asked to publish it
• publish.publisher_missing: A package's index names no publisher, and it has to for the registry
• publish.repository_refused: The package's repository isn't one the registry can fetch: a public git repository reached over HTTPS
• publish.stale_files: A commit's surface.jadpo_record or changelog list isn't what the package's code gives
• registry.unreachable: The registry couldn't be reached, or answered in a way that can't be read
• record.edited: Generated record was edited by hand
• test.failed: A test failed under jadpo test, or among a package's own tests under jadpo package check
• toolchain.artifact_write_failed: A file Jadpo writes for you, such as a record, couldn't be written, usually because it or its folder is read-only
• toolchain.not_built_yet: Operation is declared but not built yet
• toolchain.project_not_found: You ran a command that works on a project in a folder with no app.jadpo, in it or in any folder above it
• toolchain.scaffold_destination_exists: You ran jadpo new or jadpo package new with the name of a file that already exists
• toolchain.scaffold_destination_not_empty: You ran jadpo new or jadpo package new on a folder that already has files in it, hidden files included
• toolchain.scaffold_read_failed: You ran jadpo new or jadpo package new on a path Jadpo can't look into, such as a folder you can't read or a path through a file
• toolchain.scaffold_write_failed: You ran jadpo new or jadpo package new, and writing its files failed, usually because the folder they go in can't be written
• toolchain.source_read_failed: A .jadpo file in the project couldn't be read, because it isn't UTF-8 text or you aren't allowed to read it