capsula-core 0.3.0

The core library for Capsula.
Documentation

Capsula

[!WARNING] This project is in early development. The CLI interface and configuration format may change in future releases.

A powerful CLI tool for running hooks and capturing their output before and after your command executions. Capsula automatically records the state of your project environment before and after running commands, making your workflows reproducible and auditable.

[!NOTE] The Python version of Capsula is deprecated and can be found at the main branch of this repository.

Features

  • 📸 Context Capture: Automatically capture git state, file contents, environment variables, and more
  • 🔄 Reproducible Runs: Complete record of execution hook for debugging and auditing
  • 🛡️ Safety Checks: Prevent execution on dirty repositories or other unsafe conditions
  • 📊 Structured Output: JSON-formatted capture data for easy processing
  • 🔧 Extensible: Multiple built-in hooks with clean error handling

Installation

Install from crates.io

cargo install capsula-cli --locked

Install from the GitHub repository

cargo install --git https://github.com/shunichironomura/capsula --branch rust --locked capsula-cli

Quick Start

  1. Create a configuration file (capsula.toml) in your project root:
[vault]
name = "my-project"

[[pre-run.hooks]]
id = "capture-git-repo"
name = "repo-name"
path = "."

[[pre-run.hooks]]
id = "capture-cwd"

[[pre-run.hooks]]
id = "capture-file"
glob = "config.json"
mode = "copy"
hash = "sha256"
  1. Run a command with hooks:
capsula run python train_model.py

Configuration

Basic Structure

The capsula.toml configuration file defines:

  • Vault: Where to store captured data
  • Phases: Pre-run and post-run hooks
[vault]
name = "project-name"        # Vault identifier
path = ".capsula"           # Storage path (optional, defaults to .capsula/{name})

[pre-run]                 # Pre-execution hooks
[[pre-run.hooks]]
id = "capture-git-repo"
# ... hook configuration

[post-run]                # Post-execution hooks
[[post-run.hooks]]
id = "capture-file"
# ... hook configuration

Available Hook Types

Git Hook

Captures git repository state including commit hash and cleanliness check.

[[pre-run.hooks]]
id = "capture-git-repo"
name = "repo-name"          # Hook name
path = "."                  # Repository path
allow_dirty = false         # Allow uncommitted changes (default: false)

Output Example:

{
  "__meta": {
    "config": {
      "name": "repo-name",
      "path": ".",
      "allow_dirty": false
    },
    "id": "capture-git-repo",
    "success": true
  },
  "working_dir": "/path/to/repo",
  "sha": "abc123...",
  "is_dirty": false,
  "abort_on_dirty": false
}

Current Working Directory

Captures the current working directory path.

[[pre-run.contexts]]
id = "capture-cwd"

Output Example:

{
  "__meta": {
    "config": {},
    "id": "capture-cwd",
    "success": true
  },
  "cwd": "/current/working/directory"
}

File Hook

Captures file contents and/or metadata.

[[pre-run.hooks]]
id = "capture-file"
glob = "config.json"        # File pattern to capture
mode = "copy"               # Capture mode ("copy", "move", or "none". default: "copy")
hash = "sha256"             # Calculate file hash ("sha256" or "none". default: "sha256")

Output Example:

{
  "__meta": {
    "config": {
      "glob": "config.json",
      "mode": "copy",
      "hash": "sha256"
    },
    "id": "capture-file",
    "success": true
  },
  "files": [
    {
      "path": "/path/to/config.json",
      "copied_path": "/vault/run-dir/config.json",
      "hash": "sha256:abc123..."
    }
  ]
}

Environment Variables Hook

Captures specified environment variables.

[[pre-run.hooks]]
id = "capture-env"
name = "HOME"                 # Variable name to capture

Output Example:

{
  "__meta": {
    "config": {
      "name": "HOME"
    },
    "id": "capture-env",
    "success": true
  },
  "value": "/home/user"
}

Command Hook

Captures output of shell commands.

[[pre-run.hooks]]
id = "capture-command"
command = ["uname", "-a"]
abort_on_failure  = false  # Abort if command fails (default: false)

Output Example:

{
  "__meta": {
    "config": {
      "command": ["rustc", "--version"],
      "abort_on_failure": false
    },
    "id": "capture-command",
    "success": true
  },
  "status": 0,
  "stdout": "rustc 1.91.0 (f8297e351 2025-10-28)\n",
  "stderr": "",
  "abort_requested": false
}

Machine Hook

Captures system information like CPU, memory, and OS details.

[[pre-run.hooks]]
id = "capture-machine"

Output Example:

{
  "__meta": {
    "config": {},
    "id": "capture-machine",
    "success": true
  },
  "hostname": "hostname.local",
  "os": "Darwin",
  "os_version": "26.0.1",
  "kernel_version": "25.0.0",
  "architecture": "aarch64",
  "total_memory": 137438953472,
  "cpus": [
    {
      "name": "1",
      "brand": "Apple M3 Max",
      "vender_id": "Apple",
      "frequency_mhz": 4056
    }
  ]
}

CLI Usage

Commands

capsula run <command>

Execute a command with full hook capture.

# Run with default config
capsula run python script.py

# Run with custom config
capsula run --config my-config.toml python script.py

# Run with arguments
capsula run python train.py --epochs 100 --lr 0.01

Behavior:

  1. Runs pre-run hooks and saves their outputs to vault
  2. Checks for abort conditions (e.g., dirty git repo)
  3. Executes the command if safe, aborts otherwise
  4. Runs post-run hooks and saves their outputs to vault

capsula list

List all captured runs in the vault.

# List runs with default config
capsula list

# List runs with custom config
capsula list --config my-config.toml

Example Output:

TIMESTAMP (UTC)      NAME                  COMMAND
---------------------------------------------------------------------------------------------
2025-10-31 09:35:29  kind-year             echo hello
2025-10-31 09:35:28  smelly-apparel        echo hello
2025-10-31 09:35:26  clear-waste           echo hello
2025-10-31 09:30:15  cheap-trip            echo this is a very long command with many argu...

The output shows:

  • Timestamp: UTC time when the command was executed
  • Name: Human-readable generated name for the run
  • Command: The command that was executed (truncated if too long)

Output Structure

Metadata

Every hook output includes metadata for traceability:

{
  "__meta": {
    "config": {},    // Configuration used for this hook
    "id": "capture-cwd",  // Hook ID from configuration
    "success": true  // Capture success status
  }
  // ... hook-specific data
}

Vault Structure

Captured data is organized in the vault:

.capsula/
└── vault-name/
    └── 2025-10-31/                    # Date-based directory (YYYY-MM-DD, UTC)
        └── 093525-chubby-back/        # Unique run directory (HHMMSS-run-name)
            ├── _capsula/              # Capsula metadata directory
            │   ├── metadata.json      # Run metadata (ID, name, command, timestamp)
            │   ├── pre-run.json       # Pre-phase hook outputs (array)
            │   ├── command.json       # Command execution results
            │   └── post-run.json      # Post-phase hook outputs (array)
            └── [captured files]       # Files copied by file hooks

metadata.json contains run information:

{
  "id": "01K8WSYC91YAE21R7CWHQ4KYN2",
  "name": "chubby-back",
  "command": ["echo", "hello"],
  "timestamp": "2025-10-31T09:35:25.473+00:00",
  "run_dir": "/path/to/.capsula/vault-name/2025-10-31/093525-chubby-back"
}

command.json contains command execution results:

{
  "exit_code": 0,
  "stdout": "hello\n",
  "stderr": "",
  "duration": {
    "secs": 0,
    "nanos": 1986042
  }
}