Gritpack

Gritpack is a headless, polyglot package manager and package server, comparable in purpose to npm. It also provides a compiler-facing API for fast module and transitive file-graph queries.

Author: Alexander R. Croft · source files carry AGPL-3.0-or-later notices; prebuilt binaries are distributed under the bundled proprietary LICENSE

The same core serves the embedded library, gritpack command-line client, and server. A self-hosted server may use local disk; a hosted server may use S3-compatible Capsule storage. Private hubs use mutual TLS. Public hubs may explicitly allow anonymous reads while retaining mTLS for every mutation.

Package names may be global (bobs-package) or scoped (@bob/bobs-package). Packages are public to every client accepted by their server. Private distribution is provided by running a private Gritpack server, not by a private-package flag.

Install Gritpack

Official prebuilt releases are published from the public frogfishio/homebrew-gritpack distribution repository. The small Formula-only tap is frogfishio/homebrew-gritpack-tap. The private source repository is not needed to install Gritpack.

Homebrew

brew tap frogfishio/gritpack-tap
brew trust --formula frogfishio/gritpack-tap/gritpack
brew install --formula frogfishio/gritpack-tap/gritpack
gritpack --version

If the legacy frogfishio/gritpack tap is already present, migrate explicitly:

brew untap --force frogfishio/gritpack
brew tap frogfishio/gritpack-tap
brew trust --formula frogfishio/gritpack-tap/gritpack
brew install --formula frogfishio/gritpack-tap/gritpack

Homebrew uninstalls the legacy-tap Formula during the forced untap; the final command reinstalls the same released version from the lean tap.

APT

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSLo /tmp/gritpack-repository.gpg \
  https://frogfishio.github.io/homebrew-gritpack/repository-signing-key.gpg
sudo install -m 0644 /tmp/gritpack-repository.gpg \
  /etc/apt/keyrings/gritpack.gpg
curl -fsSLo /tmp/gritpack.sources \
  https://frogfishio.github.io/homebrew-gritpack/gritpack.sources
sudo install -m 0644 /tmp/gritpack.sources \
  /etc/apt/sources.list.d/gritpack.sources
sudo apt update
sudo apt install gritpack
gritpack --version

DNF or RPM

curl -fsSLo /tmp/gritpack.repo \
  https://frogfishio.github.io/homebrew-gritpack/gritpack.repo
sudo install -m 0644 /tmp/gritpack.repo \
  /etc/yum.repos.d/gritpack.repo
sudo dnf install gritpack
gritpack --version

APT and DNF authenticate the Frogfish repository metadata with its dedicated OpenPGP key. macOS releases are Developer ID signed, timestamped, hardened, and Apple-notarized. Versioned archives, Debian packages, RPMs, signed checksums, and their detached signature can also be obtained directly from GitHub Releases.

That native installation is also the recovery bootstrap for Gritpack's own user-global channel. The current explicit-hub preview can install a newer target-specific Gritpack Capsule without waiting for a Homebrew/APT/RPM projection. This command requires Gritpack 1.2.7 or newer; 1.2.6 machines use the compatibility bridge documented in DISTRIBUTION.md.

gritpack install @frogfish/gritpack --from get.gritpack.org
export PATH="$HOME/.frogfish/gritpack/bin:$PATH"
gritpack --version

Until the public administrator-admission catalogue is deployed, this explicit source is accurately recorded as untrusted; no package is silently blessed because of its name. Feature releases continue to refresh the native bootstrap channels, while qualified patch releases may use the Capsule channel.

Detailed verification, upgrade, direct-download, compatibility, and release-operator instructions are in DISTRIBUTION.md. The normative destination for moving bootstrap authority from GitHub to get.gritpack.org, projecting exact publisher-owned artifacts into Homebrew, APT, and RPM repositories, and retaining native installers' responsibility is defined in BOOTSTRAP_AND_NATIVE_REPOSITORY_PROJECTIONS.md. The authoritative map of local, CI, Apple, OpenPGP, and S3 credential names is in CREDENTIALS.md. The normative simple command-line and credential-provider destination is in CLI_DX.md. Frogfish tools share the user-home convention in FROGFISH_HOME.md; Gritpack defaults beneath ~/.frogfish/gritpack.

For a concise capability map and a fair comparison with npm and Cargo, start with FEATURES.md. The product boundary and current refinement questions are defined in PRODUCT_DEFINITION.md. The normative destination for classic projects, editable monorepos, and hybrid workspaces is OPERATING_MODEL.md. It defines explicit package boundaries, nested file ownership, stable snapshots, editable versus immutable resolution, publication transitions, and the boundaries between Gritpack, Taxis, Loom, and storage providers. The normative destination for the embedded verified-package API, extensible metadata facets, portable attestations, signed lifecycle evidence, offline bundles, and curated distribution slices is PORTABLE_PACKAGE_EVIDENCE_AND_DISTRIBUTION.md. The implemented offline-bundle and static/live-slice commands are documented step by step in PORTABLE_DISTRIBUTION.md. The supported Rust consumption surface, hard limits, cancellation, offline replay, error categories, and compatibility policy are frozen separately in EMBEDDED_API.md. The implemented caller-managed publisher-attestation, role-separated key, signed-receipt, and lifecycle-checkpoint APIs—and the remaining managed-hub boundary—are documented in PACKAGE_EVIDENCE.md. The enterprise trust model, progressively disclosed DX, governance gaps, and infrastructure-sovereign operation and curated partner/customer distribution slices are defined in ENTERPRISE_PRODUCT_POSTURE.md. The separate Crisptastic and Auth0 human experience for the hosted public service is specified in PUBLIC_WEB_APPLICATION.md. It does not add a GUI or hosted identity dependency to the Gritpack package server.

For client, compiler-integration, certificate, and hub startup instructions, see USER_GUIDE.md.

For production deployment, administration, S3, private Cargo, backup, upgrade, monitoring, and incident procedures, see OPERATIONS_MANUAL.md. Frogfish project maintainers should use the explicit enrollment, Cargo, publication, consumption, CI, and pilot checklist in FROGFISH_PRIVATE_REGISTRY_GUIDE.md.

The Taxis/Residiuum integration boundary for polyglot module graphs and compiler queries is defined in GRAPH_INDEXING.md. The implemented provider handshake and the exact gates for connecting the supported Taxis SDK are documented in TAXIS_INTEGRATION.md. The deterministic semantic projection is specified in SEMANTIC_GRAPH_PROJECTION.md, and its bounded domain-query contract in SEMANTIC_QUERIES.md. The first published Taxis Capsule's complete producer-to-consumer proof is in TAXIS_GRITPACK_ROUND_TRIP_EVIDENCE.md, and Loom's exact adoption procedure is LOOM_TAXIS_VIA_GRITPACK.md. Noema's producer handoff for a coherent multi-platform C SDK is NOEMA_GRITPACK_PUBLICATION_HANDOFF.md.

The adapter contract, experimental Go module-proxy, native npm registry, and C/C++ source-package integrations, and the planned Python compatibility programme are defined in ECOSYSTEM_ADAPTERS.md.

The supported read-only-first agent interface and its security boundary are defined in MCP_INTEGRATION.md.

The production public-registry boundary for get.gritpack.org, anonymous package consumption, invitation-only publishing, deployment, and the future gritpack.org website is defined in PUBLIC_REGISTRY.md. The live bootstrap topology, qualification evidence, operating observations, and prioritized hardening gaps are recorded in PUBLIC_REGISTRY_AS_BUILT.md. The isolated Frogfish private registry running beside it, including its Cargo integration and mixed public/private qualification, is recorded in PRIVATE_REGISTRY_AS_BUILT.md.

Current Status

The core package lifecycle is implemented:

• deterministic Capsule packing and strict validation
• certificate enrollment with client-local keys, local operator codes, or persisted administrator-issued account-bound invitations
• zero-configuration anonymous reads from get.gritpack.org:443, plus explicit public-read server mode with authenticated mutations
• separate package and management mTLS listeners
• npm-style scoped names and publication ownership
• immutable filesystem Capsule storage, plus optional S3-compatible storage for native packages and the private Cargo, Go, and npm registries
• experimental disk/S3-backed native npm publication/read, dist-tags, deprecation, credential-free client setup, public/private diagnostics, and a bounded renewable-credential execution bridge qualified with real npm across maintained Node lines and shipped host architectures on the shared ecosystem TLS listener
• Residiuum alpha-3 Heap metadata, indexed RQL queries, and flat-store migration
• publish, search, metadata lookup, Capsule download, and installation
• owner deprecation/yank and administrator quarantine lifecycle controls
• project init/add, installed graph listing/explanation, outdated reporting, synchronization/repair, strict verification, and project diagnosis
• named package-server profiles plus unambiguous local credential discovery
• verified shared content-addressed Capsule caching with corrupt-object repair
• cache status/verification and dry-run-first deterministic pruning
• bounded parallel graph downloads and integrity-bound resumable transfers
• SemVer dependency resolution and deterministic lock files
• preferred private-server lookup with default fallback and source-pinned locks
• hybrid workspace schema 2 with explicit nested members, exclusive file ownership, content-bound snapshots, selected editable/immutable closure resolution, lock v4, immutable update reporting, and network-free frozen replay
• administrator account/scope lifecycle with certificate-attributed audit, and ordinary self-service operations
• remove, update, and direct-dependency upgrade
• Ratatouille telemetry selected through GRITPACK_TELEMETRY_FILTER

Ranked headless discovery is implemented over a persisted Residiuum inverted candidate index, with explainable lexical-v1 results for human, JSON, and NDJSON clients. A local read-only stdio MCP adapter exposes search, package inspection, version listing, resolution preview and explanation, and verified installed-file inventory through the same application services.

The semantic query contract is also available through the typed library, authenticated POST /v1/graphs/query, gritpack graph query, and the read-only MCP adapter. Hub startup keeps that route unavailable until its production composition supplies a live Residiuum graph capability and verified Taxis vocabularies; the supported Taxis extractor remains the integration blocker.

Automation can select the stable gritpack/error@1 JSON failure envelope and categorized exit codes documented in CLI_ERRORS.md.

The exact pre-semantic compiler substrate now exists: authoritative lock roots, a verified resolved package/file universe, conservative dialect candidate indexes, and a deterministic mechanical Residiuum draft projection. A fail-closed semantic provider handshake now negotiates exact Taxis generations, profiles, resource limits, cancellation, and universe/lock binding. The remaining core blocker is the real semantic module graph: Taxis does not yet expose the supported resolved-module SDK needed to implement and qualify the adapter and projection without duplicating module semantics.

Build

cd gritpack
cargo build
cargo test

# Hosted/server build with the S3 Capsule backend:
cargo build --features s3

From the repository root:

make test      # unit tests
make ci        # fmt + clippy + unit tests + e2e lifecycle
make e2e       # enroll → pack → serve → publish → search → install

CI is defined in .github/workflows/ci.yml. The e2e script lives at scripts/e2e-lifecycle.sh (ephemeral certs and free ports).

Inspect the initial command surface with:

cargo run -- --help
cargo run -- serve --help

For a private Rust registry, keep crates.io as Cargo's default and add the hub as a named source:

gritpack cargo setup --profile office --registry company
gritpack cargo doctor --registry company
cargo publish --registry company

Hub Interfaces

The default listeners are:

• package API: 127.0.0.1:7443, mTLS using the package-client CA
• management API: 127.0.0.1:7444, mTLS using the management-client CA
• optional enrollment API: 127.0.0.1:7445, server-authenticated TLS
• Cargo sparse registry/API: 127.0.0.1:7446, server-authenticated TLS with short-lived bearer credentials minted through the package mTLS API

The management listener accepts administrator certificates and exposes health, account creation, and scope assignment. The package listener exposes ordinary self-service account inspection, credential revocation, and unowned-scope claiming. The matching CLI commands are whoami, revoke, claim-scope, add-user, users, user, suspend-user, reactivate-user, delete-user, assign-scope, scopes, scope, unassign-scope, audit-log, yank, deprecate, and quarantine; there is no built-in GUI.

Use gritpack <command> --help for the environment-backed runtime parameters.

Proposals Under Review

REPOSITORY_PROTOCOL.md specifies a proposed static repository format for publishing the same immutable Capsules from local directories, S3, ordinary HTTPS sites, and GitHub-driven deployments without requiring a running hub. It is deliberately marked for critique and is not yet part of the implemented product contract.

GLOBAL_INSTALLATION.md specifies the companion user-global application model: gritpack install, managed commands in ~/.frogfish/gritpack/bin, untrusted explicit external sources, and an admin-curated official installation catalogue whose admissions bind exact Capsule digests.

CARGO_REGISTRY_INTEGRATION.md specifies the private Cargo-registry adapter: Cargo remains the resolver and builder, while Gritpack stores canonical Capsules and serves deterministic .crate and sparse index projections. crates.io remains the untouched default Cargo source.

PUBLICATION_PLANNING.md specifies the ecosystem-neutral publication control plane. Native, Cargo, Go, and npm artifacts now enter the same deterministic selected-closure plan, authoritative verification, staged transaction, activation boundary, recovery path, and durable receipt. Ordinary ecosystem-native publication remains compatible; distributed multi-hub reservation arbitration is still pending.

Extensions

Startup peer synchronization is an experimental federation extension built with --features peer-sync; it is not the core multi-server model. Captain and software-lifecycle work are also extensions, recorded separately in SOFTWARE_INSTALLATION_EXPLORATION.md.