Calvin Library API Reference

Version: 0.6.0 | Updated: 2025-12-27

Calvin is available as a Rust library. The crate re-exports common types from calvin::models, calvin::parser, and the clean-architecture layers (application, domain, infrastructure, presentation).

Installation

[dependencies]
calvin = "0.6"

Core Types (Common Re-Exports)

`Frontmatter`

YAML metadata extracted from PromptPack source files.

use calvin::{AssetKind, Frontmatter, Scope, Target};

pub struct Frontmatter {
    pub description: String,
    pub kind: AssetKind,
    pub scope: Scope,
    pub targets: Vec<Target>,
    pub apply: Option<String>,
    pub allowed_tools: Vec<String>, // YAML key: "allowed-tools"
}

impl Frontmatter {
    pub fn new(description: impl Into<String>) -> Self;
    pub fn effective_targets(&self) -> Vec<Target>;
}

Notes:

allowed_tools is parsed from YAML key allowed-tools and is intended for skills.
apply is a single glob string (not a list).

`PromptAsset`

A parsed source file (frontmatter + body) from .promptpack/.

use calvin::PromptAsset;

pub struct PromptAsset {
    pub id: String,
    pub source_path: std::path::PathBuf,
    pub frontmatter: Frontmatter,
    pub content: String,
}

`OutputFile`

A compiled output ready to be written to a destination filesystem.

use calvin::{OutputFile, Target};

impl OutputFile {
    pub fn new(path: impl Into<std::path::PathBuf>, content: impl Into<String>, target: Target) -> Self;
    pub fn path(&self) -> &std::path::PathBuf;
    pub fn content(&self) -> &str;
    pub fn target(&self) -> Target;
    pub fn hash(&mut self) -> &str; // sha256:<hex>
}

`AssetKind`

use calvin::AssetKind;

pub enum AssetKind {
    Policy,
    Action,
    Agent,
    Skill,
}

`Target`

use calvin::Target;

pub enum Target {
    ClaudeCode,
    Cursor,
    VSCode,
    Antigravity,
    Codex,
    All,
}

impl Target {
    pub const ALL_CONCRETE: [Target; 5];
    pub fn is_all(&self) -> bool;
    pub fn expand(&self) -> Vec<Target>;
    pub fn supports_skills(&self) -> bool;
    pub fn directory_name(&self) -> &'static str;
    pub fn display_name(&self) -> &'static str;
}

Parsing Helpers

Calvin exposes the frontmatter parser:

use calvin::{extract_frontmatter, parse_frontmatter};

let extracted = extract_frontmatter("---\ndescription: Example\n---\nBody\n", "example.md".as_ref())?;
let fm = parse_frontmatter(&extracted.yaml, "example.md".as_ref())?;
assert_eq!(fm.description, "Example");

Use Case Example (Deploy)

use calvin::application::deploy::DeployOptions;
use calvin::domain::value_objects::{Scope, Target};
use calvin::presentation::factory::create_deploy_use_case;

let use_case = create_deploy_use_case();
let options = DeployOptions::new(".promptpack")
    .with_scope(Scope::Project)
    .with_targets(vec![Target::ClaudeCode, Target::Codex])
    .with_dry_run(true);

let result = use_case.execute(&options);
assert!(result.errors.is_empty());

Library API Reference