quillshield 1.0.0 → 1.0.1

package/README.md

@@ -1,21 +1,20 @@
-# QuillShield
+# QuillShield CLI
 
-> Smart Contract Security Auditing from the Command Line
+> Smart contract security auditing from the command line.
 
-A powerful CLI tool that automatically detects your project type (Foundry/Hardhat/Truffle), collects all Solidity files, and sends them to QuillShield for comprehensive security auditing.
+The QuillShield CLI detects your project type (Foundry, Hardhat, or Truffle), collects Solidity sources and dependencies, and submits them for security analysis.
 
 ---
 
 ## Quick Start
 
 ```bash
-# Install globally
 npm install -g quillshield
 
-# Audit a single Solidity file
+# Audit a single file
 quillshield audit ./contracts/MyToken.sol
 
-# Audit an entire project folder
+# Audit a project
 quillshield audit ./my-foundry-project
 ```
 
@@ -23,198 +22,108 @@ quillshield audit ./my-foundry-project
 
 ## Features
 
-- **Audit files or folders** - Pass a single `.sol` file or an entire project directory
-- **Auto-detect project type** - Foundry, Hardhat, Truffle, or raw Solidity
-- **Smart file collection** - Only collects `.sol` files needed for analysis
-- **Remapping support** - Automatically extracts and applies remappings
-- **Dependency resolution** - Includes all imported libraries
-- **Real-time progress** - Beautiful terminal UI with spinners and colors
-- **Wait for results** - Optionally wait for audit completion
-- **Multiple output formats** - Table or JSON format
-- **Save reports** - Export reports to files
+| Feature | Description |
+|--------|-------------|
+| **Files or folders** | Pass a single `.sol` file or a project directory |
+| **Auto-detect** | Recognizes Foundry, Hardhat, Truffle, or raw Solidity |
+| **Smart collection** | Collects only `.sol` files needed for analysis |
+| **Remappings** | Reads and applies remappings from project config |
+| **Dependencies** | Includes imported libraries (e.g. OpenZeppelin) |
+| **Progress UI** | Terminal spinners and status output |
+| **Wait or async** | Optionally wait for completion or run with `--no-wait` |
+| **Reports** | Table or JSON output; save to file with `--output` |
 
 ---
 
 ## Installation
 
-### From npm (recommended)
+Install globally from npm:
 
 ```bash
 npm install -g quillshield
 ```
 
-After installation, the `quillshield` command is available globally.
-
-### From source
-
-```bash
-git clone https://github.com/quillshield/quillshield-cli.git
-cd quillshield-cli
-npm install
-npm run build
-npm link
-```
+The `quillshield` command is then available in your PATH.
 
 ---
 
 ## Usage
 
-### Audit a Single File
+### Audit
+
+**Single file:**
 
 ```bash
-# Audit a single Solidity file
 quillshield audit ./MyToken.sol
-
-# With a custom project name
 quillshield audit ./MyToken.sol --name "My Token Audit"
 ```
 
-### Audit a Project Folder
+**Project folder:**
 
 ```bash
-# Basic audit (auto-detects project type)
 quillshield audit ./my-foundry-project
-
-# Specify analysis type
 quillshield audit ./my-project --type full
-
-# Custom project name
 quillshield audit ./my-project --name "My DeFi Protocol"
-
-# Don't wait for completion
 quillshield audit ./my-project --no-wait
 ```
 
-**Analysis Types:**
-- `full` - Complete AI-enhanced audit (default)
-- `raw` - Raw Slither analysis only
-- `semantic` - Multi-agent semantic analysis
+**Analysis types:** `full` (default), `raw`, `semantic`.
 
-### Check Status
+### Status & report
 
 ```bash
 quillshield status <project-id>
-```
-
-### Get Report
-
-```bash
-# Display report in terminal (table format)
 quillshield report <project-id>
-
-# Get report as JSON
 quillshield report <project-id> --format json
-
-# Save report to file
 quillshield report <project-id> --output report.json
 ```
 
-### Configuration
+### Config
 
 ```bash
-# Show current configuration
 quillshield config --show
-
-# Set API URL (for self-hosted backend)
 quillshield config --url https://your-backend.com
-
-# Interactive configuration
-quillshield config
+quillshield config   # interactive
 ```
 
 ---
 
-## Supported Project Types
-
-### Foundry Projects
-
-```
-my-foundry-project/
-├── foundry.toml          ← Detected automatically
-├── src/
-│   ├── Token.sol
-│   └── Vault.sol
-└── lib/
-    └── openzeppelin-contracts/
-```
-
-**What gets collected:**
-- All `.sol` files in `src/`
-- All `.sol` files in `lib/` (marked as dependencies)
-- Remappings from `foundry.toml`
-- Compiler version from `foundry.toml`
-
-### Hardhat Projects
-
-```
-my-hardhat-project/
-├── hardhat.config.js     ← Detected automatically
-├── contracts/
-│   ├── Token.sol
-│   └── NFT.sol
-└── node_modules/
-    └── @openzeppelin/
-```
+## Project types
 
-**What gets collected:**
-- All `.sol` files in `contracts/`
-- Common libraries from `node_modules/` (@openzeppelin, @chainlink, @uniswap)
-- Standard Hardhat remappings
-- Compiler version from `hardhat.config.js`
+### Foundry
 
-### Truffle Projects
+- **Detected by:** `foundry.toml`
+- **Collected:** `.sol` in `src/` and `lib/`, remappings and compiler version from `foundry.toml`
 
-```
-my-truffle-project/
-├── truffle-config.js     ← Detected automatically
-└── contracts/
-    ├── Token.sol
-    └── Migrations.sol
-```
+### Hardhat
 
-### Single Solidity File
+- **Detected by:** `hardhat.config.js`
+- **Collected:** `.sol` in `contracts/`, common libs from `node_modules` (@openzeppelin, @chainlink, @uniswap), compiler from config
 
-```bash
-quillshield audit ./MyContract.sol
-```
+### Truffle
 
-The compiler version is automatically extracted from the `pragma solidity` directive.
+- **Detected by:** `truffle-config.js`
+- **Collected:** `.sol` in `contracts/`
 
-### Raw Solidity (folder with .sol files)
+### Single file / raw folder
 
-```
-my-project/
-├── Token.sol
-├── Vault.sol
-└── lib/
-    └── SafeMath.sol
-```
+- Single `.sol`: compiler from `pragma solidity`
+- Folder of `.sol` files: all `.sol` in the tree (e.g. including `lib/`)
 
 ---
 
 ## Configuration
 
-### Environment Variables
-
-Create a `.env` file in the directory you run the command from:
+### Environment (`.env` in cwd)
 
 ```env
-# Backend API URL (defaults to production)
 QUILLSHIELD_API_URL=https://quillshieldtest-production.up.railway.app
-
-# Default analysis type
 QUILLSHIELD_ANALYSIS_TYPE=full
-
-# Polling interval (seconds)
 QUILLSHIELD_POLL_INTERVAL=5
-
-# Max wait time (seconds)
 QUILLSHIELD_MAX_WAIT_TIME=600
 ```
 
-### Config File
-
-Configuration is stored in `~/.quillshield/config.json`:
+### Config file (`~/.quillshield/config.json`)
 
 ```json
 {
@@ -227,11 +136,24 @@ Configuration is stored in `~/.quillshield/config.json`:
 
 ---
 
-## Example Output
+## Commands reference
 
-```bash
-$ quillshield audit ./my-foundry-project
+| Command | Description |
+|--------|-------------|
+| `quillshield audit <path>` | Run audit on file or directory |
+| `quillshield status <project-id>` | Check audit status |
+| `quillshield report <project-id>` | Show or save report |
+| `quillshield config` | View or set config |
+
+**Audit options:** `-t, --type` (full \| raw \| semantic), `-n, --name`, `-w, --wait`, `--no-wait`  
+**Report options:** `-o, --output <file>`, `-f, --format` (json \| table)  
+**Config options:** `-s, --show`, `-u, --url <url>`
 
+---
+
+## Example output
+
+```
    ___          _   _  _   ____   _      _        _      _
   / _ \  _   _ (_) | || | / ___| | |__  (_)  ___ | |  __| |
  | | | || | | || | | || | \___ \ | '_ \ | | / _ \| | / _` |
@@ -247,152 +169,41 @@ Smart Contract Security Auditing CLI
    Found 4 remapping(s)
 ✓ Collected 25 files (8 source, 17 dependencies)
    Total lines: 3,450
-✓ Project data prepared
 ✓ Project created: 65abc123def456...
 ✓ Audit started
 
 ⏳ Waiting for audit to complete...
-
 .....✓ Audit completed!
 
 ═══════════════════════════════════════════════════════════════════
-
 Security Score: 82/100
 Audited Files: 8 | Total Lines: 3,450
-
 ───────────────────────────────────────────────────────────────────
-
 Vulnerability Summary:
-
 ┌──────────────────┬────────┐
 │ Severity         │ Count  │
 ├──────────────────┼────────┤
 │ High             │ 2      │
 │ Medium           │ 3      │
-│ Low              │ 1      │
-│ Informational    │ 5      │
-│ Optimization     │ 2      │
-└──────────────────┴────────┘
-
+...
 📊 View full report: https://frontend-production-2f25.up.railway.app/project/65abc123def456...
 ```
 
 ---
 
-## Commands Reference
-
-### `quillshield audit <path>`
-
-Audit a smart contract file or project folder.
-
-**Arguments:**
-- `<path>` - Path to a `.sol` file or project directory
-
-**Options:**
-- `-t, --type <type>` - Analysis type: `full`, `raw`, `semantic` (default: `full`)
-- `-n, --name <name>` - Custom project name
-- `-w, --wait` - Wait for audit completion (default: `true`)
-- `--no-wait` - Don't wait for completion
-
-**Examples:**
-```bash
-quillshield audit ./MyToken.sol
-quillshield audit ./my-project
-quillshield audit ./my-project --type semantic
-quillshield audit ./my-project --name "My Token" --no-wait
-```
-
-### `quillshield status <project-id>`
-
-Check audit status for a project.
-
-**Examples:**
-```bash
-quillshield status 65abc123def456...
-```
-
-### `quillshield report <project-id>`
-
-Get audit report for a project.
-
-**Options:**
-- `-o, --output <file>` - Save report to file
-- `-f, --format <format>` - Output format: `json`, `table` (default: `table`)
-
-**Examples:**
-```bash
-quillshield report 65abc123def456...
-quillshield report 65abc123def456... --format json
-quillshield report 65abc123def456... --output report.json
-```
-
-### `quillshield config`
-
-Configure QuillShield CLI.
-
-**Options:**
-- `-s, --show` - Show current configuration
-- `-u, --url <url>` - Set API URL
-
-**Examples:**
-```bash
-quillshield config --show
-quillshield config --url https://your-backend.com
-quillshield config  # Interactive mode
-```
-
----
-
 ## Troubleshooting
 
-### "Path not found"
-
-Make sure the file or directory path is correct:
-```bash
-quillshield audit ./contracts/MyToken.sol
-```
-
-### "Only Solidity (.sol) files are supported"
-
-When auditing a single file, it must be a `.sol` file. For non-Solidity projects, point to the project folder instead.
-
-### "No Solidity files found"
-
-Check that your project has `.sol` files in the expected locations:
-- Foundry: `src/`
-- Hardhat: `contracts/`
-- Truffle: `contracts/`
-
-### "Failed to connect to backend"
-
-Check that the backend is reachable:
-```bash
-curl https://quillshieldtest-production.up.railway.app/health
-```
-
-Update API URL if using a self-hosted backend:
-```bash
-quillshield config --url http://your-backend-url
-```
-
-### "Audit taking too long"
-
-Large projects may take several minutes. Use `--no-wait` and check status later:
-```bash
-quillshield audit my-project --no-wait
-# Wait a few minutes
-quillshield status <project-id>
-```
-
----
-
-## License
-
-MIT License
+| Issue | What to do |
+|-------|------------|
+| **Path not found** | Use a correct path: `quillshield audit ./contracts/MyToken.sol` |
+| **Only Solidity (.sol) supported** | For a single file, use a `.sol` path; for a project, use the project directory |
+| **No Solidity files found** | Ensure `.sol` files exist in `src/` (Foundry), `contracts/` (Hardhat/Truffle) |
+| **Failed to connect to backend** | Check connectivity: `curl https://quillshieldtest-production.up.railway.app/health`. For self-hosted: `quillshield config --url http://your-backend-url` |
+| **Audit taking too long** | Use `quillshield audit <path> --no-wait`, then `quillshield status <project-id>` later |
 
 ---
 
-**Start auditing with a single command!**
+**Run an audit:**
 
 ```bash
 quillshield audit ./my-contract.sol

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quillshield",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "QuillShield - Smart contract security auditing tool. Audit Solidity files and projects from the command line.",
   "main": "dist/index.js",
   "bin": {