Packages
Karkain ships a real package manager with a deterministic resolver, a
lockfile, git and local source fetching, and a full pkg command
namespace.
Usage
Top-level shortcuts, all of which have an equivalent karkain pkg
<verb> spelling:
$ karkain init [name] # create a new project (in current dir)
$ karkain new <name> # create a new project directory
$ karkain add <pkg> [version] # add a dependency
$ karkain remove|rm <pkg> # remove a dependency
$ karkain update [pkg] # re-resolve versions, write karkain.lock
$ karkain fetch # fetch resolved dependencies (lockfile)
$ karkain list # list direct + transitive dependencies
$ karkain tree # show recursive dependency graph
Full command set
Command |
Description |
|---|---|
|
Create a new project |
|
Create a new project directory |
|
Add a dependency ( |
|
Remove a dependency |
|
Re-resolve versions; write |
|
Update all packages to the latest compatible version |
|
Resolve and fetch exactly the locked versions |
|
List dependencies ( |
|
List direct + transitive dependencies |
|
Show recursive dependency graph |
|
Search the package registry |
|
Show package details |
|
Publish the current project ( |
|
Create a local package registry (local-only) |
|
Authenticate with the registry |
|
Clear the auth token |
|
Show the current user |
|
Check for vulnerabilities ( |
|
Verify checksums / integrity of all dependencies |
|
Show cached packages |
|
Remove all (or stale) cached packages |
|
Show the cache directory |
|
Workspace management (alias |
Sources
Two dependency sources are fully implemented:
local —
--source local --url <path>points at a local project directory.git —
--source git --url <url>fetches a git repository.
Fetching is made safe by atomic temp → rename writes plus checksum
verification, all stored under the project’s .karkain/cache/.
Registry
Phase 135 is local-only. No network registry exists yet: the registry is a
directory on the local filesystem, selected by --registry <dir> (flag
wins) or the KARKAIN_REGISTRY environment variable.
$ karkain pkg registry init ./my-registry # create packages/ + index/
$ karkain pkg publish --registry ./my-registry
$ karkain add hello 1.0.0 --registry ./my-registry
$ karkain fetch # resolve, verify, cache
$ karkain run src/main.kark # build against the dep, run
Layout: packages/<name>/<version>/ holds the manifest copy, the
published source tree and a digest; index/<name> lists the published
versions and the latest. Versions must be semver; resolution accepts an
exact version, */empty (latest) or an existing semver constraint.
Published versions are immutable — republishing name@version fails and
leaves the stored contents untouched. Names are validated (letters,
digits, -, _, .); traversal and absolute paths are rejected.
Fetching verifies the stored digest and aborts on mismatch.
Limitations: registry dependencies resolve at their declared version and
are not transitively expanded; pkg search/pkg info against a
remote backend remain unserved (no silent results).
Lockfile
Resolved versions are written to karkain.lock at the project root.
fetchuses the lockfile: it retrieves exactly the locked versions and never re-resolves.updatere-resolves within the manifest constraints and rewrites the lockfile.addfetches the new dependency immediately and caches it.
Manifest
The project manifest is karkain.toml. Dependencies map a package
name to a version, source flavor and optional URL.
[dependencies]
stdlib = "^0.14.0"
Workspaces
A workspace root is marked with karkain pkg workspace init and gains
members through workspace add <path>. Member operations run in
dependency order.
Exit codes
0— success5— package or dependency failure2— CLI usage error inside thepkgnamespace
See also
Dependencies — dependency workflow.
Project Layout — directory layout including
karkain.toml and the cache directory.