use std::collections::BTreeMap;
use std::fs::{self, OpenOptions};
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use std::process::ExitCode;
use change_capsule::{
Author, CapsuleManager, CheckpointOptions, CloseOptions, CreateOptions, EvidenceInput,
IntegrateOptions, VerifyOptions, verify_authenticated_bundle, verify_bundle,
};
use clap::{Args, Parser, Subcommand};
use serde::Serialize;
use serde_json::json;
use sha2::{Digest, Sha256};
use zeroize::Zeroizing;
#[derive(Debug, Parser)]
#[command(
name = "capsule",
version,
about = "Create recoverable, agent-neutral change attempts backed by Git worktrees"
)]
struct Cli {
#[arg(long, global = true, env = "CAPSULE_HOME")]
home: Option<PathBuf>,
#[arg(long, global = true)]
json: bool,
#[command(subcommand)]
command: Command,
}
#[derive(Debug, Subcommand)]
enum Command {
Capabilities,
Create(CreateArgs),
Lookup(LookupArgs),
List(ListArgs),
Show(IdArgs),
Path(IdArgs),
Status(IdArgs),
Diff(DiffArgs),
Result(IdArgs),
Artifacts(IdArgs),
Export(ExportArgs),
Keygen(KeygenArgs),
Sign(SignArgs),
Verify(VerifyArgs),
Attest(AttestArgs),
Checkpoint(CheckpointArgs),
Evidence(EvidenceArgs),
Close(CloseArgs),
Integrate(IntegrateArgs),
Drop(DropArgs),
Recover(RecoverArgs),
}
#[derive(Debug, Args)]
struct CreateArgs {
#[arg(long, default_value = ".")]
repo: PathBuf,
#[arg(long, default_value = "HEAD")]
base: String,
#[arg(long)]
label: Option<String>,
#[arg(long, value_parser = parse_link)]
link: Vec<(String, String)>,
#[arg(long)]
idempotency_key: Option<String>,
}
#[derive(Debug, Args)]
struct LookupArgs {
#[arg(long)]
idempotency_key: String,
}
#[derive(Debug, Args)]
struct ListArgs {
#[arg(long)]
skip_invalid: bool,
}
#[derive(Debug, Args)]
struct IdArgs {
id: String,
}
#[derive(Debug, Args)]
struct RecoverArgs {
id: Option<String>,
}
#[derive(Debug, Args)]
struct DiffArgs {
id: String,
#[arg(long)]
output: Option<PathBuf>,
}
#[derive(Debug, Args)]
struct ExportArgs {
id: String,
#[arg(long)]
output: PathBuf,
}
#[derive(Debug, Args)]
struct KeygenArgs {
#[arg(long)]
private_key: PathBuf,
#[arg(long)]
public_key: PathBuf,
}
#[derive(Debug, Args)]
struct SignArgs {
bundle: PathBuf,
#[arg(long)]
private_key: PathBuf,
#[arg(long)]
output: PathBuf,
}
#[derive(Debug, Args)]
struct AttestArgs {
bundle: PathBuf,
#[arg(long)]
repo: Option<PathBuf>,
#[arg(long)]
output: Option<PathBuf>,
#[arg(long)]
predicate_only: bool,
}
#[derive(Debug, Args)]
struct VerifyArgs {
bundle: PathBuf,
#[arg(long)]
repo: Option<PathBuf>,
#[arg(long)]
require_successful_evidence: bool,
#[arg(long)]
require_current_successful_evidence: bool,
#[arg(long)]
require_executed_evidence: bool,
#[arg(long, requires = "trusted_public_key")]
signature: Option<PathBuf>,
#[arg(long, requires = "signature")]
trusted_public_key: Option<PathBuf>,
}
#[derive(Debug, Args)]
struct CheckpointArgs {
id: String,
#[arg(short = 'm', long)]
message: String,
#[command(flatten)]
author: AuthorArgs,
}
#[derive(Debug, Args)]
struct EvidenceArgs {
id: String,
#[arg(long, requires = "exit_code")]
claim: Option<String>,
#[arg(long, requires = "claim")]
exit_code: Option<i32>,
#[arg(long, conflicts_with = "claim")]
timeout_seconds: Option<u64>,
#[arg(long)]
summary: Option<String>,
#[arg(last = true)]
argv: Vec<String>,
}
#[derive(Debug, Args)]
struct CloseArgs {
id: String,
#[arg(long)]
require_successful_evidence: bool,
#[arg(long)]
require_current_successful_evidence: bool,
#[arg(long)]
require_executed_evidence: bool,
}
#[derive(Debug, Args)]
struct IntegrateArgs {
id: String,
#[arg(long, default_value = ".")]
target: PathBuf,
#[arg(short = 'm', long)]
message: Option<String>,
#[command(flatten)]
author: AuthorArgs,
}
#[derive(Debug, Args)]
struct DropArgs {
id: String,
#[arg(long)]
force: bool,
}
#[derive(Debug, Args)]
struct AuthorArgs {
#[arg(long, default_value = "Capsule")]
author_name: String,
#[arg(long, default_value = "capsule@localhost")]
author_email: String,
}
impl From<AuthorArgs> for Author {
fn from(value: AuthorArgs) -> Self {
Self::new(value.author_name, value.author_email)
}
}
fn main() -> ExitCode {
let arguments: Vec<_> = std::env::args_os().collect();
let json_mode = arguments.iter().any(|argument| argument == "--json");
let cli = match Cli::try_parse_from(&arguments) {
Ok(cli) => cli,
Err(error) => {
let exit_code = u8::try_from(error.exit_code()).unwrap_or(2);
if exit_code == 0 {
if json_mode {
let payload = json!({
"ok": true,
"kind": "cli_help",
"output": error.to_string(),
});
println!(
"{}",
serde_json::to_string(&payload).unwrap_or_else(|_| {
"{\"ok\":false,\"error\":\"failed to serialize CLI help\",\"kind\":\"internal\"}"
.to_owned()
})
);
} else {
let _ = error.print();
}
} else if json_mode {
let payload = json!({
"ok": false,
"error": error.to_string(),
"kind": "cli",
});
eprintln!(
"{}",
serde_json::to_string(&payload).unwrap_or_else(|_| {
"{\"ok\":false,\"error\":\"failed to serialize CLI error\",\"kind\":\"internal\"}"
.to_owned()
})
);
} else {
let _ = error.print();
}
return ExitCode::from(exit_code);
}
};
match run(cli) {
Ok(()) => ExitCode::SUCCESS,
Err(error) => {
if json_mode {
let payload = json!({
"ok": false,
"error": error.to_string(),
"kind": error_kind(&error),
});
eprintln!(
"{}",
serde_json::to_string(&payload).unwrap_or_else(|_| {
"{\"ok\":false,\"error\":\"failed to serialize error\"}".to_owned()
})
);
} else {
eprintln!("error: {error}");
}
ExitCode::FAILURE
}
}
}
#[allow(clippy::too_many_lines)]
fn run(cli: Cli) -> change_capsule::Result<()> {
if matches!(cli.command, Command::Capabilities) {
return print_value(&change_capsule::Capabilities::current(), cli.json);
}
if let Command::Lookup(arguments) = &cli.command {
let state_root = match &cli.home {
Some(home) => home.clone(),
None => change_capsule::default_state_root()?,
};
return print_value(
&CapsuleManager::lookup_idempotency_key_at(&state_root, &arguments.idempotency_key)?,
cli.json,
);
}
if let Command::Keygen(arguments) = &cli.command {
let keys = change_capsule::generate_keypair()?;
write_new_key_file(&arguments.public_key, &keys.public_key(), false).map_err(|error| {
change_capsule::Error::InvalidInput(format!(
"public key publication failed at {}; no private key was published: {error}; remove the public key before retrying if it exists",
arguments.public_key.display()
))
})?;
write_new_key_file(&arguments.private_key, keys.private_seed(), true).map_err(|error| {
change_capsule::Error::InvalidInput(format!(
"public key was published at {}; private key publication failed at {}: {error}; remove the public key before retrying if desired",
arguments.public_key.display(),
arguments.private_key.display()
))
})?;
return print_value(
&json!({ "private_key": arguments.private_key, "public_key": arguments.public_key }),
cli.json,
);
}
if let Command::Sign(arguments) = &cli.command {
let key = read_private_seed(&arguments.private_key)?;
change_capsule::sign_bundle(&arguments.bundle, &key, &arguments.output)?;
return print_value(
&json!({ "bundle": arguments.bundle, "signature": arguments.output }),
cli.json,
);
}
if let Command::Attest(arguments) = &cli.command {
let statement = change_capsule::attest_bundle(
&arguments.bundle,
&verify_options(false, false, false, arguments.repo.clone()),
)?;
let mut rendered = if arguments.predicate_only {
serde_json::to_vec_pretty(&statement.predicate)
} else {
serde_json::to_vec_pretty(&statement)
}
.map_err(|source| change_capsule::Error::Json {
path: PathBuf::from("attestation"),
source,
})?;
rendered.push(b'\n');
if let Some(path) = &arguments.output {
return write_new_file(path, &rendered);
}
print!("{}", String::from_utf8_lossy(&rendered));
return Ok(());
}
if let Command::Verify(arguments) = &cli.command {
let report = if let (Some(signature), Some(public_key)) =
(&arguments.signature, &arguments.trusted_public_key)
{
let signature = read_exact_file::<64>(signature, "Ed25519 signature")?;
let key = read_exact_file::<32>(public_key, "trusted Ed25519 public key")?;
verify_authenticated_bundle(
&arguments.bundle,
&signature,
&key,
&verify_options(
arguments.require_successful_evidence,
arguments.require_current_successful_evidence,
arguments.require_executed_evidence,
arguments.repo.clone(),
),
)?
} else {
verify_bundle(
&arguments.bundle,
&verify_options(
arguments.require_successful_evidence,
arguments.require_current_successful_evidence,
arguments.require_executed_evidence,
arguments.repo.clone(),
),
)?
};
return print_value(&report, cli.json);
}
let manager = match cli.home {
Some(home) => CapsuleManager::open(home)?,
None => CapsuleManager::open_default()?,
};
match cli.command {
Command::Capabilities => {
unreachable!("capabilities is handled before state initialization")
}
Command::Create(arguments) => {
let mut options = CreateOptions::new(arguments.repo);
options.base = arguments.base;
options.label = arguments.label;
let mut links = BTreeMap::new();
for (key, value) in arguments.link {
if links.insert(key.clone(), value).is_some() {
return Err(change_capsule::Error::InvalidInput(format!(
"duplicate link key: {key:?}"
)));
}
}
options.links = links;
let capsule = match arguments.idempotency_key {
Some(key) => manager.create_idempotent(options, &key)?,
None => manager.create(options)?,
};
if cli.json {
print_json(&capsule)?;
} else {
println!("{}", capsule.id);
println!("path={}", capsule.workspace_path.display());
println!("base={}", capsule.base_commit);
}
}
Command::Lookup(_) => {
unreachable!("lookup is handled before state initialization")
}
Command::List(arguments) if arguments.skip_invalid => {
let listing = manager.list_reporting()?;
if cli.json {
print_json(&listing)?;
} else {
for capsule in &listing.capsules {
println!("{} {:?} {}", capsule.id, capsule.state, capsule.base_commit);
}
for record in &listing.unreadable {
println!("{} UNREADABLE {}", record.id, record.error);
}
}
}
Command::List(_) => {
let capsules = manager.list()?;
if cli.json {
print_json(&capsules)?;
} else if capsules.is_empty() {
println!("No capsules.");
} else {
for capsule in capsules {
println!(
"{}\t{:?}\t{}\t{}",
capsule.id,
capsule.state,
capsule.label.as_deref().unwrap_or("-"),
capsule.workspace_path.display()
);
}
}
}
Command::Show(arguments) => print_value(&manager.show(&arguments.id)?, cli.json)?,
Command::Path(arguments) => {
let path = manager.workspace_path(&arguments.id)?;
if cli.json {
print_json(&json!({ "id": arguments.id, "path": path }))?;
} else {
println!("{}", path.display());
}
}
Command::Status(arguments) => print_value(&manager.status(&arguments.id)?, cli.json)?,
Command::Diff(arguments) => {
let patch = manager.diff(&arguments.id)?;
if let Some(output) = arguments.output {
write_output_file(&output, &patch)?;
if cli.json {
print_json(&json!({
"id": arguments.id,
"output": output,
"bytes": patch.len(),
"patch_sha256": hex::encode(Sha256::digest(&patch)),
}))?;
} else {
println!("{}", output.display());
}
} else if cli.json {
let changed_paths = match manager.result(&arguments.id) {
Ok(result) => result.changed_paths,
Err(change_capsule::Error::InvalidState { .. }) => {
manager.status(&arguments.id)?.changed_paths
}
Err(error) => return Err(error),
};
print_json(&json!({
"id": arguments.id,
"bytes": patch.len(),
"patch_sha256": hex::encode(Sha256::digest(&patch)),
"changed_paths": changed_paths,
"hint": "pass --output <path> to write patch bytes",
}))?;
} else {
io::stdout().lock().write_all(&patch).map_err(|source| {
change_capsule::Error::Io {
path: PathBuf::from("stdout"),
source,
}
})?;
}
}
Command::Result(arguments) => {
let result = manager.result(&arguments.id)?;
if cli.json {
print_json(&result)?;
} else {
println!("kind={:?}", result.kind);
println!("base={}", result.base_commit);
println!("head={}", result.head_commit);
println!(
"patch={}",
manager.result_patch_path(&arguments.id)?.display()
);
for path in result.changed_paths {
println!("changed={path}");
}
}
}
Command::Artifacts(arguments) => {
print_value(&manager.artifacts(&arguments.id)?, cli.json)?;
}
Command::Export(arguments) => {
print_value(
&manager.export_artifacts(&arguments.id, arguments.output)?,
cli.json,
)?;
}
Command::Keygen(_) | Command::Sign(_) | Command::Verify(_) | Command::Attest(_) => {
unreachable!("keygen, sign, verify, and attest run before state initialization")
}
Command::Checkpoint(arguments) => {
let checkpoint = manager.checkpoint(
&arguments.id,
CheckpointOptions::new(arguments.message, arguments.author.into()),
)?;
print_value(&checkpoint, cli.json)?;
}
Command::Evidence(arguments) => {
let mut input = match (&arguments.claim, arguments.argv.is_empty()) {
(Some(command), true) => {
EvidenceInput::claim(command, arguments.exit_code.unwrap_or_default())
}
(None, false) => {
let mut input = EvidenceInput::run(arguments.argv.clone());
if let Some(seconds) = arguments.timeout_seconds {
input = input.with_timeout(std::time::Duration::from_secs(seconds));
}
input
}
_ => {
return Err(change_capsule::Error::InvalidInput(
"pass either a command after `--` for Capsule to run, or --claim with --exit-code".to_owned(),
));
}
};
if let Some(summary) = arguments.summary {
input = input.with_summary(summary);
}
print_value(&manager.add_evidence(&arguments.id, input)?, cli.json)?;
}
Command::Close(arguments) => {
let result = manager.close(
&arguments.id,
CloseOptions::requiring(
arguments.require_successful_evidence,
arguments.require_current_successful_evidence,
arguments.require_executed_evidence,
),
)?;
print_value(&result, cli.json)?;
}
Command::Integrate(arguments) => {
let capsule = manager.integrate(&arguments.id, &{
let mut options = IntegrateOptions::new(arguments.target, arguments.author.into());
options.message = arguments.message;
options
})?;
print_value(&capsule, cli.json)?;
}
Command::Drop(arguments) => {
let capsule = manager.drop_capsule(&arguments.id, arguments.force)?;
print_value(&capsule, cli.json)?;
}
Command::Recover(arguments) => {
let actions: Vec<_> = match arguments.id {
Some(id) => manager.recover_capsule(&id)?.into_iter().collect(),
None => manager.recover()?,
};
if cli.json {
print_json(&actions)?;
} else if actions.is_empty() {
println!("No recovery actions required.");
} else {
for action in actions {
println!("{}\t{}", action.capsule_id, action.action);
}
}
}
}
Ok(())
}
fn verify_options(
require_successful_evidence: bool,
require_current_successful_evidence: bool,
require_executed_evidence: bool,
repository: Option<PathBuf>,
) -> VerifyOptions {
let mut options = VerifyOptions::requiring(
require_successful_evidence,
require_current_successful_evidence,
require_executed_evidence,
);
if let Some(repository) = repository {
options = options.with_repository(repository);
}
options
}
fn parse_link(value: &str) -> Result<(String, String), String> {
let (key, value) = value
.split_once('=')
.ok_or_else(|| "links must use KEY=VALUE".to_owned())?;
Ok((key.to_owned(), value.to_owned()))
}
fn parent_directory(path: &Path) -> &Path {
path.parent()
.filter(|parent| !parent.as_os_str().is_empty())
.unwrap_or_else(|| Path::new("."))
}
fn write_new_file(path: &Path, bytes: &[u8]) -> change_capsule::Result<()> {
let mut file = OpenOptions::new()
.write(true)
.create_new(true)
.open(path)
.map_err(|source| change_capsule::Error::Io {
path: path.to_path_buf(),
source,
})?;
file.write_all(bytes)
.and_then(|()| file.sync_all())
.map_err(|source| change_capsule::Error::Io {
path: path.to_path_buf(),
source,
})?;
sync_parent_directory(parent_directory(path))
}
fn write_new_key_file(path: &Path, bytes: &[u8], private: bool) -> change_capsule::Result<()> {
let parent = parent_directory(path);
let mut temporary =
tempfile::NamedTempFile::new_in(parent).map_err(|source| change_capsule::Error::Io {
path: parent.to_path_buf(),
source,
})?;
#[cfg(unix)]
if private {
use std::os::unix::fs::PermissionsExt;
temporary
.as_file()
.set_permissions(fs::Permissions::from_mode(0o600))
.map_err(|source| change_capsule::Error::Io {
path: temporary.path().to_path_buf(),
source,
})?;
}
let _ = private;
temporary
.write_all(bytes)
.and_then(|()| temporary.as_file().sync_all())
.map_err(|source| change_capsule::Error::Io {
path: temporary.path().to_path_buf(),
source,
})?;
temporary.persist_noclobber(path).map_err(|error| {
if error.error.kind() == io::ErrorKind::AlreadyExists {
change_capsule::Error::InvalidInput(format!(
"refusing to overwrite key file: {}",
path.display()
))
} else {
change_capsule::Error::Io {
path: path.to_path_buf(),
source: error.error,
}
}
})?;
sync_parent_directory(parent)
}
fn read_private_seed(path: &Path) -> change_capsule::Result<Zeroizing<[u8; 32]>> {
Ok(Zeroizing::new(read_exact_file::<32>(
path,
"Ed25519 private seed",
)?))
}
fn open_readonly_input(path: &Path) -> change_capsule::Result<fs::File> {
let mut options = OpenOptions::new();
options.read(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
let flags = rustix::fs::OFlags::NOFOLLOW | rustix::fs::OFlags::NONBLOCK;
options.custom_flags(
i32::try_from(flags.bits())
.expect("O_NOFOLLOW | O_NONBLOCK fits platform custom_flags"),
);
}
#[cfg(windows)]
{
use std::os::windows::fs::OpenOptionsExt;
options.custom_flags(windows_sys::Win32::Storage::FileSystem::FILE_FLAG_OPEN_REPARSE_POINT);
}
options
.open(path)
.map_err(|source| change_capsule::Error::Io {
path: path.to_path_buf(),
source,
})
}
fn read_exact_file<const N: usize>(
path: &Path,
description: &str,
) -> change_capsule::Result<[u8; N]> {
let mut file = open_readonly_input(path)?;
validate_opened_exact_file(&file, path, description, N)?;
let mut bytes = [0_u8; N];
file.read_exact(&mut bytes)
.map_err(|source| change_capsule::Error::Io {
path: path.to_path_buf(),
source,
})?;
let mut trailing = [0_u8; 1];
if file
.read(&mut trailing)
.map_err(|source| change_capsule::Error::Io {
path: path.to_path_buf(),
source,
})?
!= 0
{
return Err(invalid_exact_file(path, description, N));
}
validate_opened_exact_file(&file, path, description, N)?;
Ok(bytes)
}
fn validate_opened_exact_file(
file: &fs::File,
path: &Path,
description: &str,
size: usize,
) -> change_capsule::Result<()> {
let metadata = file
.metadata()
.map_err(|source| change_capsule::Error::Io {
path: path.to_path_buf(),
source,
})?;
if metadata_is_reparse_point(&metadata) || !metadata.is_file() || metadata.len() != size as u64
{
return Err(invalid_exact_file(path, description, size));
}
Ok(())
}
fn metadata_is_reparse_point(metadata: &fs::Metadata) -> bool {
#[cfg(windows)]
{
use std::os::windows::fs::MetadataExt;
metadata.file_attributes()
& windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_REPARSE_POINT
!= 0
}
#[cfg(not(windows))]
{
let _ = metadata;
false
}
}
fn invalid_exact_file(path: &Path, description: &str, size: usize) -> change_capsule::Error {
change_capsule::Error::InvalidInput(format!(
"{description} must be a regular non-link file containing exactly {size} raw bytes: {}",
path.display()
))
}
#[cfg(unix)]
fn sync_parent_directory(path: &Path) -> change_capsule::Result<()> {
fs::File::open(path)
.and_then(|directory| directory.sync_all())
.map_err(|source| change_capsule::Error::Io {
path: path.to_path_buf(),
source,
})
}
#[cfg(not(unix))]
#[allow(clippy::unnecessary_wraps)]
fn sync_parent_directory(_path: &Path) -> change_capsule::Result<()> {
Ok(())
}
fn print_value<T: Serialize + std::fmt::Debug>(
value: &T,
json_mode: bool,
) -> change_capsule::Result<()> {
if json_mode {
print_json(value)
} else {
println!("{value:#?}");
Ok(())
}
}
fn print_json<T: Serialize>(value: &T) -> change_capsule::Result<()> {
let rendered =
serde_json::to_string_pretty(value).map_err(|source| change_capsule::Error::Json {
path: PathBuf::from("stdout"),
source,
})?;
println!("{rendered}");
Ok(())
}
fn write_output_file(path: &Path, bytes: &[u8]) -> change_capsule::Result<()> {
let parent = parent_directory(path);
fs::create_dir_all(parent).map_err(|source| change_capsule::Error::Io {
path: parent.to_path_buf(),
source,
})?;
let mut temporary =
tempfile::NamedTempFile::new_in(parent).map_err(|source| change_capsule::Error::Io {
path: parent.to_path_buf(),
source,
})?;
temporary
.write_all(bytes)
.map_err(|source| change_capsule::Error::Io {
path: temporary.path().to_path_buf(),
source,
})?;
temporary
.as_file()
.sync_all()
.map_err(|source| change_capsule::Error::Io {
path: temporary.path().to_path_buf(),
source,
})?;
temporary.persist_noclobber(path).map_err(|error| {
if error.error.kind() == io::ErrorKind::AlreadyExists {
change_capsule::Error::InvalidInput(format!(
"refusing to overwrite output file: {}",
path.display()
))
} else {
change_capsule::Error::Io {
path: path.to_path_buf(),
source: error.error,
}
}
})?;
Ok(())
}
#[allow(clippy::match_same_arms)]
fn error_kind(error: &change_capsule::Error) -> &'static str {
match error {
change_capsule::Error::NotRepository(_) => "not_repository",
change_capsule::Error::NotFound(_) => "not_found",
change_capsule::Error::InvalidId(_) | change_capsule::Error::InvalidInput(_) => {
"invalid_input"
}
change_capsule::Error::IdempotencyConflict => "idempotency_conflict",
change_capsule::Error::IdempotencyNotFound => "idempotency_not_found",
change_capsule::Error::InvalidState { .. } => "invalid_state",
change_capsule::Error::ArtifactNotFound(_) => "artifact_not_found",
change_capsule::Error::Verification(_) => "verification",
change_capsule::Error::UnsafeState(_) | change_capsule::Error::ForeignWorktree(_) => {
"safety"
}
change_capsule::Error::UnsealedChanges(_) | change_capsule::Error::ResultDrift(_) => {
"unsealed_result"
}
change_capsule::Error::DirtyIntegrationTarget(_) => "dirty_target",
change_capsule::Error::Git { .. } | change_capsule::Error::GitOutputTooLarge { .. } => {
"git"
}
change_capsule::Error::NonUtf8Path(_) => "unsupported_path",
change_capsule::Error::SchemaVersion { .. } => "schema_version",
change_capsule::Error::Io { .. }
| change_capsule::Error::Json { .. }
| change_capsule::Error::CaptureWorker => "internal",
_ => "internal",
}
}