pinoc 0.1.5

Authors:

About

Pinoc is a command-line tool designed to make it easy to set up and manage Pinocchio projects on Solana. It automates common development tasks including project initialization, building, testing, and deployment with simple commands.

Features

• 🚀 Fast Project Scaffolding - Create new projects with best practices in seconds
• 📁 Proper Directory Structure - Solana/Pinocchio development structure out of the box
• 🔨 Simple Commands - Build, test, and deploy with intuitive commands
• 🧹 Smart Project Cleaning - Clean build artifacts while preserving keypairs
• 📦 Package Management - Add dependencies and search for Pinocchio packages
• 💻 Comprehensive Testing - Built-in testing environment with mollusk-svm
• 🔐 Automatic Keypair Management - Generate and manage program keypairs
• 🔑 Program Key Sync - Keep your program IDs consistent with smart checking
• ⚙️ Configuration Management - Use Pinoc.toml for deployment settings

Installation

From crates.io (Recommended)

cargo install pinoc

From GitHub

cargo install --git https://github.com/a91y/pinoc --force

From Source

1. Clone the repository

   git clone https://github.com/a91y/pinoc.git
   cd pinoc
   

2. Build the tool

   cargo build --release
   

3. Install globally

   cargo install --path .
   

Quick Start

# Install pinoc
cargo install pinoc

# Create a new project
pinoc init my_awesome_app

# Navigate to your project
cd my_awesome_app

# Build and test
pinoc build
pinoc test

# Deploy to Solana
pinoc deploy

# Create a new project without git initialization
pinoc init my_awesome_app --no-git
# This will skip git repository initialization.

Usage

Available Commands

Command	Description
pinoc init <project-name> [--no-git] [--no-boilerplate]	Initialize a new Pinocchio project (skip git init with --no-git, minimal structure with --no-boilerplate)
pinoc build	Build your Solana program
pinoc test	Run project tests
pinoc deploy [--cluster] [--wallet]	Deploy your program to Solana (uses Pinoc.toml config, optional overrides)
pinoc clean [--no-preserve]	Clean target directory (preserves keypairs by default)
pinoc add <package-name>	Add a package to your project
pinoc search [query]	Search for Pinocchio packages
pinoc keys list	List all program keypairs
pinoc keys sync	Sync program ID in lib.rs with keypair
pinoc --help	Get help and see all available commands
pinoc help	Display custom help banner with all commands

Complete Workflow Example

# Create a new project
pinoc init my_pinocchio_app

# Create a new project without git initialization
pinoc init my_pinocchio_app --no-git

# Create a minimal project without tests and boilerplate
pinoc init my_minimal_project --no-boilerplate

# Navigate to your project
cd my_pinocchio_app

# Build your project
pinoc build

# Run tests
pinoc test

# List program keys
pinoc keys list

# Sync program keys (checks consistency first)
pinoc keys sync

# Clean build artifacts (preserves keypairs)
pinoc clean

# Add a package
pinoc add some_package

# Search for packages
pinoc search database

# Get help
pinoc help

# Deploy your program
pinoc deploy

# Deploy with custom cluster and wallet
pinoc deploy --cluster devnet --wallet ./custom-keypair.json

Project Structure

When you initialize a project with pinoc init, it creates the following structure:

my_project/
├── Cargo.toml              # Project configuration with Pinocchio dependencies
├── README.md               # Project documentation
├── .gitignore              # Git ignore file
├── Pinoc.toml              # Deployment configuration
├── src/
│   ├── lib.rs              # Library crate using no_std
│   ├── entrypoint.rs       # Program entrypoint
│   ├── errors.rs           # Error definitions
│   ├── instructions/       # Program instructions
│   │   ├── mod.rs
│   │   └── initialize.rs   # Initialize instruction
│   └── states/             # Account state definitions
│       ├── mod.rs
│       ├── state.rs        # State structure
│       └── utils.rs        # State management utilities
├── tests/                  # Test files
│   └── tests.rs            # Unit tests using mollusk-svm
└── target/
    └── deploy/
        └── my_project-keypair.json  # Generated program keypair

Minimal Project

When you initialize a project with pinoc init --no-boilerplate, it creates a minimal structure:

my_minimal_project/
├── Cargo.toml              # Minimal configuration with only pinocchio dependency
├── README.md               # Basic documentation
├── .gitignore              # Git ignore file
├── Pinoc.toml              # Deployment configuration
├── src/
│   └── lib.rs              # Minimal program with just program ID and basic structure
└── target/
    └── deploy/
        └── my_minimal_project-keypair.json  # Generated program keypair

Minimal Project Features:

• No Tests: No test directory or test dependencies
• No Boilerplate: No instructions, states, or utility files
• Essential Only: Just the core files needed to build and deploy
• Fast Setup: Perfect for quick prototypes or learning

Key Features in Detail

🧹 Smart Project Cleaning

The pinoc clean command intelligently manages your build artifacts:

# Clean target directory while preserving keypairs (default)
pinoc clean

# Clean everything including keypairs
pinoc clean --no-preserve

Why preserve keypairs? Your program keypair is essential for deployment. The default behavior ensures you don't accidentally lose your deployment credentials.

📦 Package Management

Easily add dependencies and discover new packages:

# Add a package to your project
pinoc add package-name

# Search for Pinocchio-related packages
pinoc search database
pinoc search oracle

🔐 Automatic Keypair Management

• Generation: Keypairs are automatically created during project initialization
• Preservation: Clean commands preserve keypairs by default
• Security: Keypairs are stored securely in target/deploy/

🔑 Program Key Management

Manage your program keys with consistency checks:

# List all program keypairs
pinoc keys list

# Sync program ID in lib.rs with keypair
pinoc keys sync

Key Sync Features:

• Consistency Check: Verifies if the program ID in declare_id! matches the keypair's public key
• Smart Updates: Only updates the file if there's a mismatch
• Clear Feedback: Shows current state and any changes made
• No Unnecessary Writes: Prevents file updates when keys are already consistent

Example Output:

# When keys are already consistent
✅ Program key is already consistent!
🔑 Program ID: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
📝 No update needed in src/lib.rs

# When keys need syncing
🔄 Program key mismatch detected:
   Current in lib.rs: 11111111111111111111111111111111
   Actual keypair:    9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
✅ Successfully synced program key!
🔑 Program ID: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
📝 Updated src/lib.rs with new program ID

⚙️ Configuration Management

Pinoc uses a Pinoc.toml configuration file to manage deployment settings. This file is automatically created when you initialize a new project.

Pinoc.toml Structure:

[provider]
cluster = "localhost"
wallet = "~/.config/solana/id.json"

Configuration Options:

• cluster: The Solana cluster URL to deploy to (e.g., "localhost", "devnet", "mainnet-beta")
• wallet: Path to your Solana wallet keypair file (supports ~ for home directory expansion)

Deployment Process:

When you run pinoc deploy, the tool will:

1. Read the Pinoc.toml configuration file
2. Display the cluster and wallet being used
3. Deploy your program using the specified settings

Command-Line Overrides:

You can override the configuration from Pinoc.toml using command-line arguments:

# Override cluster only
pinoc deploy --cluster devnet

# Override wallet only  
pinoc deploy --wallet ./custom-keypair.json

# Override both cluster and wallet
pinoc deploy --cluster mainnet-beta --wallet ~/.config/solana/mainnet-keypair.json

Example Deployment Output:

$ pinoc deploy
Deploying program
📋 Using configuration:
   Cluster: devnet
   Wallet: ~/.config/solana/id.json
Program deployed successfully!

Customizing Configuration:

You can edit the Pinoc.toml file to change deployment settings, or use command-line arguments for one-time overrides:

# For mainnet deployment
[provider]
cluster = "mainnet-beta"
wallet = "~/.config/solana/mainnet-keypair.json"

# For local development
[provider]
cluster = "localhost"
wallet = "~/.config/solana/id.json"

Command-Line Override Examples:

# Use different cluster for this deployment
pinoc deploy --cluster devnet

# Use different wallet for this deployment
pinoc deploy --wallet ./test-keypair.json

# Override both settings
pinoc deploy --cluster mainnet-beta --wallet ~/.config/solana/production-keypair.json

Prerequisites

Before using Pinoc, make sure you have the following installed:

• Rust and Cargo - Install Rust
• Solana CLI Tools - Install Solana CLI
• Git - For version control

Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests to ensure everything works
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Setup

1. Clone and Build

   git clone https://github.com/a91y/pinoc.git
   cd pinoc
   cargo build --release
   

2. Install Locally

   cargo install --path .
   

3. Test Your Changes

   # Test the CLI
   pinoc --help
   
   # Create a test project
   pinoc init test-project
   cd test-project
   pinoc build
   

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation: This README and the Pinocchio documentation
• 🐛 Issues: Report bugs and request features on GitHub Issues