# `jadpo package` Show, check, import and install packages. `new --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 ` names who publishes it, and without it the command asks on a terminal and leaves the key out elsewhere. `show ` 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 ` 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 [--previous ] [--publisher ]` 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 ` 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 ` checks a registry's OpenAPI document, a file or an address, against the registry protocol (area 11), exiting 1 if it differs. `record .` 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 (`@v`) 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 --into ` 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 @/` 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 ` takes that release at once. `search ` 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`. ```text jadpo package [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 `: For import: its name, such as Tidepool.v1 - `--input `: For record: the operation's input as JSON - `--live`: For conform: run it against the real API - `--into `: For recipe: the domain it is copied into - `--previous `: For verify: the release before this one - `--publisher `: 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
`: For --serve: where to listen - `--registry `: For --serve: where old archives come from - `--no-run`: For verify: run none of the package's code - `--to `: The release to take; for search, a type - `--from `: For search: the type a function takes - `--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 `: 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 ```text # Start a library package in its own repository jadpo package new TidePool --library --publisher @acme # See what the holidays package offers jadpo package show holidays # See one of its functions in full jadpo package show holidays uk.dates # Run the publishing bar in a package's own repository jadpo package check # Check a release as the registry does, against the one before it jadpo package verify ../holidays --previous ../holidays-2.0.0 --json # Import another Jadpo application's API jadpo package import openapi ../orders/build/openapi/main.json # Install a package from the registry jadpo package add @acme/holidays # Take a release before its three days are up jadpo package update holidays --to 2.1.0 # Find what answers a need jadpo package search "uk bank holidays" # See whether an advisory touches what the app reaches jadpo package audit # Run the registry's verifier on the pushed tag, publishing nothing jadpo package publish --dry-run # See the package's registry page before publishing jadpo package preview # Install a package from its git repository at a release jadpo package add github.com/acme/holidays@v2.1.0 # Try the app against a package's checkout before it is released jadpo package link ../holidays # Copy a package's recipe into a domain jadpo package recipe holidays closures --into scheduling # Record a sandbox's answer to confirm an operation jadpo package record holidays dates.list --input '{"year": 2027}' ``` ## Errors - [`cli.package_arguments`](/docs/errors/cli.package_arguments.md): A `jadpo package` command names no action, one it doesn't have, or a package the project doesn't hold - [`cli.package_not_openapi`](/docs/errors/cli.package_not_openapi.md): A file given to `jadpo package import` is JSON but not an OpenAPI 3.0 or 3.1 document - [`cli.package_unreadable`](/docs/errors/cli.package_unreadable.md): A file given to `jadpo package import` isn't there, can't be read, or isn't JSON - [`recording.failed`](/docs/errors/recording.failed.md): 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`](/docs/errors/recording.refused.md): 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`](/docs/errors/conform.failed.md): A package's answers to `jadpo package conform` don't fit the capability it fills, or the suite couldn't run - [`conform.refused`](/docs/errors/conform.refused.md): 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`](/docs/errors/install.fetch_failed.md): Installing a package couldn't read its git repository, or found no release there at the tag you gave - [`install.in_use`](/docs/errors/install.in_use.md): Package to remove is still used by the app - [`install.not_in_registry`](/docs/errors/install.not_in_registry.md): The registry has no package of the name you gave, or no such release of it - [`install.not_proved`](/docs/errors/install.not_proved.md): The registry's answers don't prove the release is the one in its public log - [`install.surface_mismatch`](/docs/errors/install.surface_mismatch.md): The package you are installing has code that offers something different from its committed `surface.jadpo_record` - [`install.yanked`](/docs/errors/install.yanked.md): The release you asked for has been yanked, so it can't be newly installed - [`package.advisory`](/docs/errors/package.advisory.md): An advisory is against a declaration of an installed package that the app reaches - [`package.name_taken`](/docs/errors/package.name_taken.md): A package has the same name as one of the app's domains, libraries, declarations or other packages - [`publish.behaviour_changed`](/docs/errors/publish.behaviour_changed.md): 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`](/docs/errors/publish.breaking_change.md): A package's new version changes or removes something its last release offered, within the same major version - [`publish.changelog_missing`](/docs/errors/publish.changelog_missing.md): Package's changelog doesn't say why its new version is released - [`publish.description_missing`](/docs/errors/publish.description_missing.md): Package's public declaration has no description - [`publish.example_failed`](/docs/errors/publish.example_failed.md): Example in a package's description doesn't compile or doesn't hold - [`publish.example_missing`](/docs/errors/publish.example_missing.md): Package's function has no example, or a failure it raises is shown by none - [`publish.failed`](/docs/errors/publish.failed.md): The registry's verifier refused the release - [`publish.licence_proprietary`](/docs/errors/publish.licence_proprietary.md): A package's licence is `Licence.proprietary`, which the public registry refuses - [`publish.not_at_tag`](/docs/errors/publish.not_at_tag.md): What `jadpo package publish` would ask for isn't a pushed `v` tag whose commit is the one checked out - [`publish.publisher_mismatch`](/docs/errors/publish.publisher_mismatch.md): A release names another publisher than the one asked to publish it - [`publish.publisher_missing`](/docs/errors/publish.publisher_missing.md): A package's index names no publisher, and it has to for the registry - [`publish.repository_refused`](/docs/errors/publish.repository_refused.md): The package's repository isn't one the registry can fetch: a public git repository reached over HTTPS - [`publish.stale_files`](/docs/errors/publish.stale_files.md): A commit's `surface.jadpo_record` or changelog list isn't what the package's code gives - [`registry.unreachable`](/docs/errors/registry.unreachable.md): The registry couldn't be reached, or answered in a way that can't be read - [`record.edited`](/docs/errors/record.edited.md): Generated record was edited by hand - [`test.failed`](/docs/errors/test.failed.md): A test failed under `jadpo test`, or among a package's own tests under `jadpo package check` - [`toolchain.artifact_write_failed`](/docs/errors/toolchain.artifact_write_failed.md): 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`](/docs/errors/toolchain.not_built_yet.md): Operation is declared but not built yet - [`toolchain.project_not_found`](/docs/errors/toolchain.project_not_found.md): 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`](/docs/errors/toolchain.scaffold_destination_exists.md): You ran `jadpo new` or `jadpo package new` with the name of a file that already exists - [`toolchain.scaffold_destination_not_empty`](/docs/errors/toolchain.scaffold_destination_not_empty.md): You ran `jadpo new` or `jadpo package new` on a folder that already has files in it, hidden files included - [`toolchain.scaffold_read_failed`](/docs/errors/toolchain.scaffold_read_failed.md): 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`](/docs/errors/toolchain.scaffold_write_failed.md): 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`](/docs/errors/toolchain.source_read_failed.md): 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