Merge pull request #19 from polkadot-developers/feat/cli-interactive-prompts

feat: refactor CLI with interactive prompts and improve repository structure

Author: brunopgalvao

.gitattributes

@@ -0,0 +1,25 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Source code
+*.rs text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.js text eol=lf
+*.ts text eol=lf
+*.md text eol=lf
+
+# Scripts
+*.sh text eol=lf
+justfile text eol=lf
+
+# Binary files
+*.wasm binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

.gitignore

@@ -1,13 +1,29 @@
 # Rust
 debug/
 target/
+**/*.rs.bk
+*.pdb
 
 # macOS
 .DS_Store
 .DS_Store?
+._*
+.Spotlight-V100
+.Trashes
 
-# VS Code
-.vscode
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
 
 # Node
-node_modules/
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment
+.env
+.env.local

CONTRIBUTING.md

@@ -77,8 +77,6 @@ Before contributing, ensure you have the following installed:
 - **Node.js** `20+` - [Download](https://nodejs.org/)
 - **npm** `10+` (comes with Node.js)
 - **Rust** `1.86+` - [Install via rustup](https://rustup.rs)
-- **Git** - [Install](https://git-scm.com/downloads)
-- **just** (optional, for running justfiles) - [Install](https://github.com/casey/just)
 
 ### Setting Up Your Development Environment
 
@@ -441,302 +439,27 @@ docs: update CONTRIBUTING.md with testing guidelines
 test(zero-to-hero): add integration tests for pallets
 ```
 
-## Advanced Topics
+## Additional Resources
 
-### Tutorial Configuration
+For more detailed information, see:
 
-The `tutorial.config.yml` file controls how your tutorial is built and tested.
-
-#### Basic Configuration
-
-```yaml
-name: My Tutorial Title
-slug: my-tutorial
-category: polkadot-sdk-cookbook
-needs_node: true
-description: Learn how to build a custom pallet
-type: sdk
-```
-
-#### Advanced Configuration with Manifest
-
-For tutorials with runtime/parachain code:
-
-```yaml
-name: My Tutorial Title
-slug: my-tutorial
-category: polkadot-sdk-cookbook
-needs_node: true
-description: Build a custom parachain
-type: sdk
-
-manifest:
-  build:
-    project_dir: src
-    commands:
-      - cargo build --release
-
-  runtime:
-    wasm_path: ./target/release/wbuild/my-runtime/my_runtime.compact.compressed.wasm
-
-  network:
-    relay_chain: paseo
-    para_id: 1000
-
-  tests:
-    framework: vitest
-    files:
-      - tests/my-tutorial-e2e.test.ts
-
-scripts_dir: scripts
-zombienet_dir: zombienet
-```
-
-#### When to Update
-
-Update `tutorial.config.yml` when:
-- Changing build process or commands
-- Modifying runtime WASM output paths
-- Updating network configuration
-- Changing test file locations
-- Toggling `needs_node` flag
-
-### Justfiles and Scripts
-
-#### Tutorial Justfiles
-
-Each tutorial can have a `justfile` for common development tasks:
-
-```justfile
-# List available commands
-default:
-  @just --list
-
-# Setup Rust toolchain
-setup-rust:
-  rustup install 1.86.0
-  rustup default 1.86.0
-
-# Build the runtime
-build:
-  cd src && cargo build --release
-
-# Run tests
-test:
-  npm test
-
-# Start local node
-start-node:
-  ./scripts/start-node.sh
-```
-
-**Usage**:
-```bash
-cd tutorials/my-tutorial
-just          # List commands
-just build    # Run build
-just test     # Run tests
-```
-
-#### Global vs Tutorial Scripts
-
-**Global scripts** (`/scripts/`):
-- Shared across multiple tutorials
-- Common setup procedures
-- Reusable utilities
-
-**Tutorial scripts** (`/tutorials/<slug>/scripts/`):
-- Tutorial-specific workflows
-- Auto-generated versioned scripts (post-merge)
-- Custom setup unique to this tutorial
-
-**When to use which**:
-- Use global scripts for common patterns
-- Use tutorial scripts for unique workflows
-- Propose migration to global if script is reused 3+ times
-
-### CI/CD Pipeline
-
-#### Automated Checks on PR
-
-When you submit a PR, the following checks run automatically:
-
-1. **Tutorial Tests** (`.github/workflows/test-tutorials.yml`)
-   - Runs if new tutorial folder is added
-   - Installs dependencies
-   - Runs `npm test` for affected tutorials
-   - Tests must pass or skip gracefully
-
-2. **Build Verification**
-   - Validates `tutorial.config.yml` syntax
-   - Checks for required files
-   - Verifies test files exist
-
-#### Post-Merge Workflow
-
-After your PR is merged, maintainers will:
-
-1. **Generate versioned scripts** via `/generate-scripts` command
-   - Creates pinned setup scripts in `tutorials/<slug>/scripts/`
-   - Commits scripts to repository
-
-2. **Create tutorial tag** in format `tutorial/<slug>/vYYYYMMDD-HHMMSS`
-   - Enables stable snippet extraction for documentation
-
-3. **Optionally create GitHub release** for major tutorials
-
-#### Version Management
-
-Tutorial versions are managed in `versions.yml`:
-
-```yaml
-versions:
-  rust: "1.86.0"
-  chain_spec_builder: "0.20.0"
-  polkadot_omni_node: "0.4.1"
-
-# Tutorial-specific overrides (optional)
-my_tutorial:
-  rust: "1.85.0"
-```
-
-Maintainers handle version updates. If your tutorial requires specific versions, note this in your proposal.
-
-## SDK Architecture
-
-The Polkadot Cookbook uses a modular SDK architecture consisting of two main components:
-
-### Polkadot Cookbook Core (`polkadot-cookbook-core`)
-
-The core library provides the business logic for tutorial creation and management. It can be used programmatically by other tools.
-
-**Key modules:**
-- `config` - Type-safe project and tutorial configuration
-- `error` - Comprehensive error types with serialization support
-- `git` - Async git operations
-- `templates` - Template generation for scaffolding
-- `scaffold` - Project creation and directory structure
-- `bootstrap` - Test environment setup (npm, dependencies, config files)
-
-**Features:**
-- Async-first API using Tokio
-- Structured logging with `tracing`
-- Serializable errors for tooling integration
-- Comprehensive test coverage (80%+)
-- No terminal dependencies (pure library)
-
-**Example programmatic usage:**
-```rust
-use polkadot_cookbook_core::{config::ProjectConfig, Scaffold};
-use std::path::PathBuf;
-
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let config = ProjectConfig::new("my-tutorial")
-        .with_destination(PathBuf::from("./tutorials"))
-        .with_git_init(true)
-        .with_skip_install(false);
-
-    let scaffold = Scaffold::new();
-    let project_info = scaffold.create_project(config).await?;
-
-    println!("Created: {}", project_info.project_path.display());
-    Ok(())
-}
-```
-
-For more information, see [`polkadot-cookbook-core/README.md`](polkadot-cookbook-core/README.md).
-
-### Polkadot Cookbook CLI (`polkadot-cookbook-cli`)
-
-A thin CLI wrapper around the core library that provides a command-line interface.
-
-**Features:**
-- Beautiful colored output
-- Progress indicators
-- Error handling with helpful messages
-- Command-line flags for customization
-
-**Usage:**
-```bash
-# Create a new tutorial
-cargo run --package polkadot-cookbook-cli -- my-tutorial
-
-# With options
-cargo run --package polkadot-cookbook-cli -- my-tutorial --skip-install --no-git
-
-# Show help
-cargo run --package polkadot-cookbook-cli -- --help
-```
-
-### Why This Architecture?
-
-The SDK architecture provides several benefits:
-
-1. **Separation of Concerns**
-   - Core library has zero UI/terminal dependencies
-   - CLI is a thin presentation layer
-   - Business logic is testable and reusable
-
-2. **Programmatic Access**
-   - Other tools can use the core library directly
-   - IDE extensions can integrate the functionality
-   - CI/CD pipelines can automate tutorial creation
-
-3. **Better Testing**
-   - Unit tests for business logic
-   - Integration tests for workflows
-   - CLI can be tested separately
-
-4. **Easier Maintenance**
-   - Clear module boundaries
-   - Async-first for better performance
-   - Structured logging for observability
-
-### Contributing to the SDK
-
-If you want to contribute to the SDK itself (not just tutorials):
-
-1. **Core library changes** go in `polkadot-cookbook-core/`
-   - Add features to appropriate modules
-   - Write comprehensive tests
-   - Use structured logging (`tracing`)
-   - Ensure no terminal dependencies
-
-2. **CLI changes** go in `polkadot-cookbook-cli/`
-   - Keep it thin (mostly UI/formatting)
-   - Delegate logic to core library
-   - Use colored output for better UX
-
-3. **Run tests**:
-   ```bash
-   # Test core library
-   cargo test --package polkadot-cookbook-core
-
-   # Test CLI
-   cargo run --package polkadot-cookbook-cli -- test-project --skip-install --no-git
-
-   # Test entire workspace
-   cargo test --workspace
-   ```
-
-4. **Check formatting and lints**:
-   ```bash
-   cargo fmt --check
-   cargo clippy --workspace -- -D warnings
-   ```
+- **[Advanced Topics](docs/ADVANCED_TOPICS.md)** - Tutorial configuration, justfiles, and CI/CD pipeline details
+- **[SDK Architecture](docs/SDK_ARCHITECTURE.md)** - Core library and CLI architecture for contributors
 
 ## Getting Help
 
 ### Resources
 
-- **Visual Guide**: [Tutorial Creation Workflow](docs/TUTORIAL_WORKFLOW.md)
-- **Workflow Documentation**: [docs/WORKFLOWS.md](docs/WORKFLOWS.md)
+- **[Tutorial Creation Workflow](docs/TUTORIAL_WORKFLOW.md)** - Visual workflow diagram
+- **[Advanced Topics](docs/ADVANCED_TOPICS.md)** - Configuration and CI/CD details
+- **[SDK Architecture](docs/SDK_ARCHITECTURE.md)** - Core library and CLI documentation
 - **Example Tutorial**: `tutorials/zero-to-hero/`
-- **Polkadot Documentation**: [docs.polkadot.com](https://docs.polkadot.com)
+- **[Polkadot Documentation](https://docs.polkadot.com)**
 
 ### Communication
 
 - **Questions**: Open an [issue](https://github.com/polkadot-developers/polkadot-cookbook/issues)
 
+---
+
 Thank you for contributing to Polkadot Cookbook!