ips/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

IPS (Image Packaging System) is a Rust reimplementation of the illumos/OpenIndiana package management system (replacing the Python-based pkg5). It handles software packaging, installation, updates, and dependency resolution for illumos distributions.

Workspace crates: libips (core library), pkg6 (client CLI), pkg6repo (repo management CLI), pkg6depotd (HTTP depot server), pkg6recv, pkgtree, specfile, ports, userland, xtask.

Build and Development Commands

cargo build                        # Build all crates
cargo check                        # Check without building
cargo nextest run                  # Run tests (CRITICAL: use nextest, not cargo test)
cargo nextest run test_name        # Run specific test
make release                       # Build release + copy to artifacts/
RUST_LOG=libips=trace cargo run    # Run with logging

CRITICAL: Always use cargo nextest run instead of cargo test. Tests need process isolation to avoid port conflicts.

Coding Conventions

Error Handling (miette + thiserror)

• All error enums derive #[derive(Debug, Error, Diagnostic)]
• Each variant has #[diagnostic(code(...), help(...))] with actionable guidance
• Subsystem errors chain via #[error(transparent)] #[diagnostic(transparent)]
• Return IpsResult<T> (alias for Result<T, IpsError>) from the top-level API
• Subsystem functions return their own result type (e.g., RepositoryResult<T>, ImageResult<T>, FmriResult<T>)
• Each module defines: pub type Result<T> = std::result::Result<T, ModuleError>;
• Diagnostic codes follow the pattern ips::module::variant (e.g., ips::image_error::io)

Rust Style

• Use strongly typed idiomatic Rust — express logic in datatypes
• Do error handling — express options for how to handle issues for calling functions
• Use miette's diagnostic pattern to inform the user thoroughly what they need to do
• Never use raw SQL — use rusqlite with proper abstractions
• Edition 2024

Architecture

libips (core library)

• fmri.rs — FMRI parsing (pkg://publisher/name@version)
• actions/ — Manifest action types (File, Dir, Link, User, Group, etc.) and filesystem executors
• image/ — Image metadata, catalog queries, installed packages DB (SQLite)
• repository/ — ReadableRepository/WritableRepository traits, FileBackend (local), RestBackend (HTTP)
• solver/ — Dependency resolution via resolvo
• digest/ — SHA1/SHA2/SHA3 hashing
• payload/ — Package payload handling
• publisher.rs — Publisher configuration
• transformer.rs — Manifest transformation/linting
• depend/ — Dependency generation and parsing

Key Types

• Fmri — Fault Management Resource Identifier (pkg://publisher/name@release,branch-build:timestamp)
• Manifest — Collection of actions describing a package
• Image — Full or Partial image with metadata, publishers, catalogs
• FileBackend / RestBackend — Repository implementations

pkg5 Legacy Documentation and Compatibility

We carry the original pkg5 reference documentation in doc/pkg5_docs/ to guide compatibility with the legacy Python client. Our own docs in doc/ describe how we've implemented the compatibility layer.

Reference Specifications (from pkg5)

Topic	File	What it covers
Depot protocol	depot.txt, depot.rst	HTTP REST API: /file/0/{hash}, /catalog/0/, /manifest/0/{fmri}, /search/0/, /p5i/0/, /publisher/0/, /versions/0/
Retrieval protocol	guide-retrieval-protocol.rst	Client-depot wire protocol, ETag/If-Modified-Since caching, content negotiation
Publication protocol	guide-publication-protocol.rst	Transaction-based publishing (open, add, close)
Repository format	guide-repository-format.rst	On-disk layout: pkg/, file/ (two-level hash dirs), catalog/, trans/, updatelog/
Catalog v1	catalog-v1.txt, catalog.txt	Delta-encoded text catalog with catalog.attrs, npkgs, incremental updates
Actions	actions.txt, actions.rst	All 12 action types: file, dir, link, hardlink, depend, service, user, group, driver, license, legacy, set
FMRI & versioning	versions.txt, dev-guide chpt3.txt	pkg://publisher/name@release,branch-build:timestamp, component ordering
Image types	image.txt, image.rst	Full, Zone, User images and their metadata layout
Server API versions	server_api_versions.txt, client_api_versions.txt	Protocol version negotiation between client and depot
Signed manifests	signed_manifests.txt	Manifest signature format and verification
Linked images	linked-images.txt, parallel-linked-images.txt	Zone/parent-child image constraints
Facets & variants	facets.txt	Conditional action delivery (variant.arch, facet.doc)
Mediated links	mediated-links.txt	Conflict resolution for symlinks across packages
On-disk format	on-disk-format.txt	Container format proposal for packages
Dev guide	dev-guide/chpt1-14.txt	Full IPS developer guide chapters

Our Compatibility Implementation

Feature	Our doc	Implementation
p5i publisher files	doc/pub_p5i_implementation.md	FileBackend generates pub.p5i JSON files per publisher for backward compat with pkg set-publisher -p
Obsoleted packages	doc/obsoleted_packages.md	Detects pkg.obsolete=true during pkg5 import; stores in <repo>/obsoleted/ with structured metadata
pkg5 import	pkg6repo/src/pkg5_import.rs	Reads pkg5.repository, two-level hash dirs, gzip payloads, URL-encoded versions; converts to pkg6 format
Depot REST API	pkg6depotd/src/http/	Serves same HTTP paths as pkg5 depot (/file/0/, /manifest/0/, /catalog/0/, /publisher/0/)
libips integration	doc/forge_docs/ips_integration.md	Typed API replacing pkg5 CLI tools (pkgsend, pkgmogrify, pkgdepend, pkglint, pkgrepo)
Error handling	doc/rust_docs/error_handling.md	miette + thiserror patterns with ips::module::variant codes

Key Compatibility Surfaces for Legacy Client

The legacy pkg(1) Python client expects these from a depot server:

1. /versions/0/ — lists supported operations and protocol versions
2. /publisher/0/ — returns application/vnd.pkg5.info (p5i JSON)
3. /catalog/0/ — catalog with Last-Modified header, incremental updates
4. /manifest/0/{fmri} — text/plain manifest with ETag
5. /file/0/{hash} — gzip-compressed file content with ETag and Cache-Control
6. /search/0/{token} — search returning index action value package tuples

Documentation Maintenance

• Keep docs/ai/architecture.md updated when making structural changes. Bump the "last updated" date.
• Create a new timestamped plan in docs/ai/plans/ before starting a new phase or significant feature.
• Create a new timestamped ADR in docs/ai/decisions/ when making meaningful technology or design choices. Number sequentially from the last ADR.
• Never delete old plans or decisions. Mark superseded plans with status Superseded and link to the replacement.