pinoc 0.1.4

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

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

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

# Deploy your program
pinoc deploy

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
├── 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 ├── 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:

```bash
# 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

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 Apache License 2.0 - see the LICENSE file for details.

Support

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