v0.1.0

.bwd-root

@@ -0,0 +1 @@
+

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pavidi"
-version = "0.1.0-preview.2"
+version = "0.1.0"
 description = "A task runner."
 license = "Apache-2.0"
 readme = "README.md"

README.md

@@ -1,67 +1,184 @@
-# Pavidi (P)
+# Pavidi (P) - The Minimalist, Powerful Task Runner
 
-> **PREVIEW STAGE**  
-> This software is currently in preview. Features and APIs are subject to change. Use with caution.
+**Pavidi** (executable as `p`) is a modern, cross-platform task runner built in Rust. It aims to provide a consistent execution layer across different operating systems, handling dependencies, environment variables, and parallel execution with ease.
 
-Pavidi (or simply **P**) is a powerful task runner and shell environment built in Rust. It aims to provide a consistent execution layer across different operating systems.
+**P stands for:**
 
-## Components
+* **Pavidi**: The identity of a minimalist, powerful runner.
+* **Perfect**: Smart caching, parallel execution, and rock-solid task management.
+* **Portable**: Cross-platform by design with built-in commands that work everywhere.
 
-- **Pavidi (Core):** The project-aware task runner that manages configuration, dependencies, and execution flow.
+[**📚 Read the Full Documentation**](docs/index.md)
 
-## Installation
+## 🚀 Key Features
+
+- **Cross-Platform Compatibility**: Write tasks once, run anywhere (Windows, Linux, macOS).
+- **Portable Commands**: Built-in cross-platform commands like `p:rm`, `p:cp`, `p:mkdir` ensuring your scripts work on any OS.
+- **Dependency Management**: Define task dependencies and execute them sequentially or in parallel.
+- **Smart Caching**: Skip tasks if inputs haven't changed (hashing based on source files and environment variables).
+- **Environment Management**: First-class support for `.env` files, dynamic variable resolution, and rigorous environment provenance tracking.
+- **Secret Redaction**: Automatically mask sensitive information in logs.
+- **Configuration Hierarchy**: Modular configuration with `p.toml` and extension files (`p.*.toml`).
+- **Parallel Execution**: Leverage multi-core processors for independent tasks.
+
+## 📦 Installation
 
 To build and install from source:
 
-```sh
+```bash
 cargo install --path .
 ```
 
-## Configuration (`p.toml`)
+Ensure `~/.cargo/bin` is in your `PATH`.
+
+## ⚡ Quick Start
 
-Project configuration is defined in a `p.toml` file at the root of your project.
+Create a `p.toml` file in your project root:
 
 ```toml
 [project]
-name = "my-awesome-app"
+name = "my-awesome-project"
 version = "0.1.0"
 
 [env]
 RUST_LOG = "info"
-app_port = "8080"
+PORT = "8080"
 
-# Simple task definition
-[runner]
-clean = "rm -rf target/"
-format = ["cargo fmt", "cargo clippy"]
-
-# Full task definition with dependencies and metadata
 [runner.build]
 cmds = ["cargo build --release"]
-description = "Builds the project for release"
+description = "Build the project"
 
 [runner.test]
 cmds = ["cargo test"]
 deps = ["build"]
 ignore_failure = false
+
+[runner.clean]
+cmds = ["p:rm -rf target/"]
+description = "Clean build artifacts"
+```
+
+Run a task:
+```bash
+p build
+```
+
+## 📖 Configuration Reference (`p.toml`)
+
+Pavidi uses `p.toml` as its primary configuration file.
+
+### Project Metadata
+
+Define project-wide settings under `[project]`.
+
+```toml
+[project]
+name = "my-project"
+version = "1.0.0"
+authors = ["Alice <alice@example.com>"]
+description = "A sample project"
+shell = "bash" # Optional: Force a specific shell (defaults to system default)
+log_strategy = "always" # Options: "always", "error-only", "none"
+log_plain = false # Disable colored logs if true
+secret_patterns = ["API_KEY_.*"] # Regex patterns to redact in logs
+```
+
+### Environment Variables (`[env]`)
+
+Define environment variables that are available to all tasks.
+
+```toml
+[env]
+DATABASE_URL = "postgres://localhost:5432/mydb"
+API_KEY = "secret-123"
+# Dynamic variables (executed at runtime)
+GIT_HASH = "$(git rev-parse --short HEAD)"
+```
+
+- **.env Files**: Pavidi automatically loads `.env` files. If `P_ENV` is set (e.g., `P_ENV=prod`), it looks for `.env.prod`.
+- **Precedence**: `.env` files override `p.toml` variables.
+
+### Task Definitions (`[runner]`)
+
+Tasks are defined in the `[runner]` section.
+
+#### Simple Command
+```toml
+[runner]
+lint = "cargo clippy"
+format = ["cargo fmt", "prettier --write ."]
+```
+
+#### Full Task Configuration
+For more control, use a table:
+
+```toml
+[runner.deploy]
+cmds = ["./deploy.sh"]
+deps = ["build", "test"] # Tasks to run before this one
+parallel = false # Run dependencies in parallel? (default: false)
+description = "Deploy the application"
+
+# Conditional Execution
+run_if = "test -f dist/app.bin" # Run only if command succeeds (exit code 0)
+skip_if = "git diff --quiet"    # Skip if command succeeds
+
+# Smart Caching (Skip if inputs/outputs are up-to-date)
+sources = ["src/**/*.rs", "Cargo.toml"]
+outputs = ["target/release/app"]
+
+# OS-Specific Overrides
+windows = ["powershell ./deploy.ps1"]
+linux = ["./deploy.sh"]
+macos = ["./deploy.sh"]
+
+# Error Handling
+ignore_failure = false # Fail if command fails? (default: false)
+retry = 3             # Number of retries
+retry_delay = 5       # Seconds between retries
+timeout = 600         # Timeout in seconds
+
+# Cleanup
+finally = ["p:rm tmp_file"] # Always runs after task (even on failure)
+```
+
+## 🛠 Portable Commands
+
+Pavidi includes built-in commands to ensure cross-platform compatibility without relying on system shells.
+
+- `p:rm [files/dirs...]`: Remove files or directories (supports `-r` for recursive, `-f` for force).
+- `p:cp [src] [dest]`: Copy files or directories (supports `-r` for recursive).
+- `p:mkdir [dirs...]`: Create directories (supports `-p` implicitly).
+- `p:ls [dirs...]`: List files.
+- `p:mv [src] [dest]`: Move/Rename files.
+- `p:cat [files...]`: Concatenate and print files.
+
+Example:
+```toml
+clean = "p:rm -rf target/ dist/"
+```
+
+## 💻 CLI Usage
+
+```bash
+p [TASK] [ARGS...]
 ```
 
-## Usage
+- **Run a task**: `p build`
+- **Pass arguments**: `p run -- --port 9000` (arguments after `--` are passed to the task)
+- **List tasks**: `p -l` or `p --list`
+- **Show Info**: `p -i` or `p --info` (shows loaded config and extensions)
+- **Inspect Env**: `p --env` (shows resolved environment variables)
+- **Trace Env**: `p -e --trace` (shows where each variable came from)
+- **Dry Run**: `p --dry-run` (print commands without executing)
 
-P uses short, mnemonic commands for efficiency.
+## 🧩 Advanced Features
 
-- **Run a task:**
-  ```sh
-  p <task_name>
-  # Example: p build
-  ```
+### Configuration Extensions
+You can split configuration into multiple files using the naming convention `p.*.toml`. These are loaded alphabetically and merged into the main configuration. This is useful for:
+- User-specific overrides (`p.local.toml` - typically gitignored).
+- Modular configurations for large projects.
 
-- **List available tasks:**
-  ```sh
-  p -l
-  ```
+### Smart Caching
+Pavidi computes a BLAKE3 hash of the files matched by `sources` and the environment variables. It compares this against a stored hash. If the hash matches AND the files in `outputs` exist, the task is skipped.
 
-- **Show project info:**
-  ```sh
-  p -i
-  ```

context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/codetease/p",
+  "public_key": "pk_pimPBrw2BH0L1lQC5NWL7"
+}

dist-workspace.toml

@@ -8,9 +8,9 @@ cargo-dist-version = "0.30.3"
 # CI backends to support
 ci = "github"
 # The installers to generate for each app
-installers = ["shell", "powershell", "homebrew", "msi"]
+installers = ["shell", "powershell", "homebrew"]
 # Target platforms to build apps for (Rust target-triple syntax)
-targets = ["aarch64-apple-darwin", "aarch64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl", "x86_64-pc-windows-msvc"]
+targets = ["aarch64-apple-darwin", "aarch64-unknown-linux-gnu", "aarch64-pc-windows-msvc", "x86_64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl", "x86_64-pc-windows-msvc"]
 # Path that installers should place binaries in
 install-path = "CARGO_HOME"
 # Whether to install an updater program

docs/README.md

@@ -0,0 +1,11 @@
+# Documentation
+
+This directory contains the documentation for **Pavidi**.
+
+*   [**Introduction**](index.md) - Start here.
+*   [**Getting Started**](getting-started.md) - Installation and your first task.
+*   [**Configuration**](configuration.md) - `p.toml` structure, environment variables, and more.
+*   [**Task Runner**](task-runner.md) - Defining tasks, dependencies, parallel execution.
+*   [**Portable Commands**](portable-commands.md) - Cross-platform commands like `p:rm`, `p:cp`.
+*   [**Smart Caching**](smart-caching.md) - Optimizing performance with caching.
+*   [**Advanced**](advanced.md) - Extensions, logging, debugging, and secrets.

docs/advanced.md

@@ -0,0 +1,68 @@
+# Advanced Features
+
+Unlock the full potential of Pavidi with these advanced configuration and debugging features.
+
+## Modular Configuration (Extensions)
+
+For large projects or user-specific overrides, you can split your configuration into multiple files. Pavidi automatically loads files matching the pattern `p.*.toml` in the project root.
+
+### Example Workflow
+
+1.  **`p.toml` (Base Config):** Contains the shared project configuration.
+2.  **`p.local.toml` (User Overrides):** Contains developer-specific settings (e.g., local database URL). Add this file to `.gitignore`.
+3.  **`p.ci.toml` (CI/CD Config):** Contains settings specific to the CI environment.
+
+### Merging Rules
+
+*   **Extensions are loaded alphabetically.**
+*   **Deep Merge:** `[env]` and `[runner]` sections are merged.
+*   **Overrides:** Values in later files override those in earlier files.
+
+## Logging & Debugging
+
+When things go wrong, Pavidi provides tools to help you understand what's happening.
+
+### Trace Mode (`--trace`)
+
+Use the `--trace` flag to see detailed execution logs, including environment variable resolution history.
+
+```bash
+p build --trace
+```
+
+### Environment Inspection (`--env`)
+
+To see the final resolved environment variables available to tasks:
+
+```bash
+p --env
+```
+
+To see *where* each variable came from (e.g., system, `p.toml`, `.env`), combine with `--trace`:
+
+```bash
+p -e --trace
+```
+
+### Dry Run (`--dry-run`)
+
+Preview the commands that would be executed without actually running them:
+
+```bash
+p build --dry-run
+```
+
+## Secret Redaction
+
+Pavidi automatically attempts to redact sensitive information from logs. You can configure custom patterns in `p.toml`.
+
+```toml
+[project]
+secret_patterns = ["API_KEY_.*", "PASSWORD_.*"]
+```
+
+Any output matching these regex patterns will be replaced with `[REDACTED]` in the console and log files.
+
+---
+
+[**Back to Introduction**](index.md)