Named package imports, version 1

The CLI can import a published package by name using the official package catalog. Import resolves the selected version once and records its immutable archive URL and SHA-256 using the existing remote package archive declaration. This is a CLI authoring feature. It keeps the existing package, world and cartridge formats.

Commands and resolution

Run these commands from a game project:

# Resolve the latest stable version at import time.
karty package import fps-kit

# Select this exact version when published in the catalog.
karty package import fps-kit@0.0.1

The CLI reads https://karty-game.github.io/karty-packages/master.json. A bare name selects that entry's latest stable version. name@version requires an exact matching version; an unknown name, unavailable version or package with no published version is an error. The catalog can reference packages maintained in different GitHub repositories. This version adds no custom catalog option.

Existing local paths retain priority. An existing folder named fps-kit is imported locally by karty package import fps-kit. Use ./fps-kit to explicitly select a local path, including when diagnosing a missing folder. Local .kpkg archive imports and their project-local copies keep their existing behavior.

Validation and project changes

Catalog resolution supplies the archive URL and SHA-256; it does not execute package code. The CLI downloads a bounded HTTPS archive and verifies its checksum. It then validates the complete archive, package name and version, exports and compatibility with the project before committing changes to authored project files. Invalid catalog data, mismatched identity, corrupt contents and incompatible packages fail the import. Existing archive path confinement, symlink restrictions and content bounds remain in force.

The dependency stored in karty.toml contains the resolved archive URL and sha256, rather than a floating name or latest-version selector. The project therefore retains the selected bytes even when the catalog gains new versions. Code packages retain their ordinary Go module integration.

Upgrade an installed archive dependency to the latest stable catalog release:

# Update to the latest stable release available now.
karty package upgrade fps-kit

# Replace the dependency with this exact published version.
karty package import --replace fps-kit@0.0.1

Upgrade accepts one installed package name without @version. It always resolves that name through the catalog, bypassing same-named local folders. Missing dependencies and linked development folders are rejected; changing a link to a release requires an explicit import --replace instead. Checksum, identity, inventory, compatibility and transactional project-update checks remain the same as import. Only an explicit upgrade or replacement changes a saved archive pin.

Review and commit the resulting manifest and any Go module changes as part of the project's dependency update. The example version is illustrative; these commands require that release to exist in the catalog.

Restore and compatibility

karty package restore, builds and development previews use the recorded URL and checksum without contacting the catalog. An existing verified cached archive supports offline restoration; a first restore still needs the release archive to be reachable. Cached bytes are verified against the recorded digest before reuse. Catalog availability is needed when importing or explicitly upgrading or replacing a dependency by name, not when restoring its saved pin.

Named imports require a CLI implementing this decision. Older CLIs with remote archive support can restore the resulting URL-and-checksum declaration without understanding the original named command. Local folder and archive workflows remain available. Automatic updates, direct URL-import commands and transitive resource dependencies are outside this version.