Skip to content

CLAUDE.md

Latest commit

 

History

History
108 lines (83 loc) · 3.93 KB

CLAUDE.md

File metadata and controls

108 lines (83 loc) · 3.93 KB
Raw

CLAUDE.md — artifact-keeper-cli

Overview

artifact-keeper-cli is the official CLI/TUI for Artifact Keeper, an enterprise artifact registry. The binary is named ak.

Build & Development Commands

# Build
cargo build

# Run
cargo run -- --help

# Lint
cargo fmt --check
cargo clippy --workspace -- -D warnings -A dead_code

# Test
cargo test --workspace

# Release build (LTO, stripped)
cargo build --release

# Regenerate SDK from OpenAPI spec
cargo run -p xtask -- generate

# Verify SDK is up-to-date
cargo run -p xtask -- generate --check

Architecture

Workspace Layout

Cargo.toml             # Workspace root (members: sdk, xtask)
src/                   # CLI binary (artifact-keeper-cli, bin: ak)
  main.rs              # Entry point (tokio async)
  cli.rs               # clap derive: Cli struct, Command enum, GlobalArgs
  error.rs             # miette diagnostics (AkError enum)
  output/mod.rs        # OutputFormat (table/json/yaml/quiet), render helpers
  config/
    mod.rs             # AppConfig (TOML), InstanceConfig, load/save
    instances.rs       # Instance management helpers (Issue #4)
    credentials.rs     # Keychain credential storage (Issue #5)
  commands/
    mod.rs             # Module declarations
    auth.rs            # login, logout, token, whoami, switch
    instance.rs        # add, remove, list, use, info
    repo.rs            # list, show, create, delete, browse
    artifact.rs        # push, pull, list, info, delete, search, copy
    setup/mod.rs       # auto-detect + per-ecosystem config (npm, pip, cargo, etc.)
    scan.rs            # run, list, show
    doctor.rs          # diagnostics
    admin.rs           # backup, cleanup, metrics, users, plugins
    config.rs          # get, set, list
    tui.rs             # TUI dashboard (ratatui)
    completion.rs      # shell completions (clap_complete)
sdk/                   # Generated API SDK (artifact-keeper-sdk)
  src/lib.rs           # Re-exports progenitor_client + generated types
  src/generated_sdk.rs # Generated by `cargo xtask generate` (66K lines, DO NOT EDIT)
xtask/                 # SDK generation tool
  src/main.rs          # OpenAPI 3.1→3.0 conversion + Progenitor code generation

SDK Generation

The SDK is generated from ../artifact-keeper-api/openapi.json using Progenitor (Oxide Computer).

The xtask handles OpenAPI 3.1 → 3.0 conversion (nullable types, oneOf/anyOf patterns, content type schemas) before passing to Progenitor. 2 endpoints using multipart/form-data are skipped (unsupported by Progenitor).

To regenerate: cargo run -p xtask -- generate

Key Patterns

  • GlobalArgs: Shared options (format, instance, no_input) extracted from Cli before command dispatch to avoid borrow checker issues with partial moves
  • OutputFormat: All commands use the --format flag (table/json/yaml/quiet) for output
  • Instance resolution: flag --instance > config default_instance > error
  • Config path: $AK_CONFIG_DIR or ~/.config/artifact-keeper/config.toml
  • Error handling: miette::Result throughout, AkError with diagnostic codes and help text
  • Async: All commands are async via tokio

Environment Variables

Variable Purpose
AK_FORMAT Default output format
AK_INSTANCE Override default instance
AK_NO_INPUT Disable interactive prompts
AK_COLOR Color mode (auto/always/never)
AK_CONFIG_DIR Override config directory
AK_TOKEN API token (alternative to keychain)
NO_COLOR Standard no-color flag

Git Conventions

  • Branch naming: feat/, fix/, chore/, docs/
  • Do NOT add Co-Authored-By lines to commit messages
  • Do NOT include AI attribution in PR descriptions
  • Squash merge preferred

Related Repos

  • artifact-keeper/ — Backend (Rust/Axum)
  • artifact-keeper-api/ — OpenAPI spec + generated SDKs
  • Rust SDK is generated via Progenitor 0.12 from the OpenAPI spec (progenitor-client + reqwest 0.13)