Skip to content

Commit e388b17

Browse files
CopilotCopilot
committed
Add comprehensive GitHub Copilot instructions
- Documented all validated build timings with NEVER CANCEL warnings - Included complete architecture overview and development workflow - Provided manual validation scenarios and troubleshooting guidance - Documented network isolation behavior for sandboxed environments - Added proper timeout recommendations for all operations
1 parent 2f6c268 commit e388b17

1 file changed

Lines changed: 115 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Vite-Plus Development Guide
2+
3+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
4+
5+
## Working Effectively
6+
7+
### Bootstrap and Build Process
8+
- Install Rust nightly toolchain: `rustup install nightly-2025-08-05` (version specified in rust-toolchain.toml)
9+
- Install Node.js 22.18.0+ (check .node-version file)
10+
- Install PNPM globally: `npm install -g pnpm@10.15.1`
11+
- Install project dependencies: `pnpm install` -- takes 30 seconds. Set timeout to 60+ seconds.
12+
- **RUST BUILD PROCESS:**
13+
- Dev build: `cargo build --bin vt` -- takes 54 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
14+
- Release build: `cargo build --release --bin vt` -- takes 3 minutes 44 seconds. NEVER CANCEL. Set timeout to 300+ seconds.
15+
- Check compilation: `cargo check --workspace --all-features --all-targets --locked` -- takes 3 minutes 36 seconds. NEVER CANCEL. Set timeout to 300+ seconds.
16+
- **NODE.JS BUILD PROCESS:**
17+
- Full CLI bootstrap: `pnpm run bootstrap-cli` -- takes 4 minutes 6 seconds. NEVER CANCEL. Set timeout to 300+ seconds.
18+
- This builds Rust bindings AND Node.js packages AND installs global CLI
19+
20+
### Testing
21+
- Run Rust tests: `cargo test -p vite_task` -- takes 30 seconds. Set timeout to 60+ seconds.
22+
- Run full workspace tests: `cargo test --workspace` -- takes 1 minute 47 seconds. NEVER CANCEL. Set timeout to 180+ seconds.
23+
- **NOTE**: Many tests may fail due to network/firewall limitations when accessing npm registry in sandboxed environments. This is expected and not a code issue.
24+
- You never need to run `pnpm install` in test fixtures directories - vite-plus can parse workspaces without installing dependencies.
25+
26+
### Key Binaries and Commands
27+
- **Main binary**: `./target/debug/vt` or `./target/release/vt` (built from vite_task crate)
28+
- **Global CLI**: `vite-plus` (Node.js wrapper after bootstrap-cli)
29+
- **Built-in commands**: `vite-plus build`, `vite-plus test`, `vite-plus lint`, `vite-plus fmt`
30+
- **Task execution**: `vite-plus run <task> -r` (recursive), `vite-plus run package#task`
31+
- **Debug mode**: `vite-plus --debug` or `./target/debug/vt --debug`
32+
33+
## Validation
34+
35+
### Manual Testing Scenarios
36+
- **ALWAYS verify CLI installation**: Run `vite-plus --version` and `vite-plus --help`
37+
- **Test core functionality**: Use `./target/release/vt --version` to test the Rust binary directly
38+
- **Validate command parsing**: Test `vite-plus run --help` and other subcommands
39+
- **Network isolation aware**: CLI may fail with SSL certificate errors in sandboxed environments when trying to auto-install dependencies - this is expected
40+
41+
### Build Validation Steps
42+
- Always run `cargo check` before making changes to ensure clean baseline
43+
- Always run `cargo build --bin vt` to validate Rust changes
44+
- Always run `pnpm run bootstrap-cli` when modifying both Rust and Node.js components
45+
- **CRITICAL**: Do not skip validation steps due to long build times - these are necessary
46+
47+
## Architecture Overview
48+
49+
### Core Components
50+
- **Entry Point**: `crates/vite_task/src/lib.rs` - Main CLI parsing and execution logic
51+
- **Workspace**: `crates/vite_task/src/config/workspace.rs` - Loads packages and creates task graphs
52+
- **Task Graph**: `crates/vite_task/src/config/task_graph_builder.rs` - Builds dependency graphs
53+
- **Execution**: `crates/vite_task/src/schedule.rs` - Executes tasks in dependency order
54+
- **CLI Wrapper**: `packages/cli/` - Node.js package with Rust NAPI bindings
55+
- **Global CLI**: `packages/global/` - Installable global CLI package
56+
57+
### Project Structure
58+
- **Rust workspace**: `crates/*` - Core task runner logic in Rust
59+
- **Node.js workspace**: `packages/*` - CLI wrappers and tooling integrations
60+
- **Monorepo setup**: Uses both PNPM workspaces AND Cargo workspaces
61+
- **Path safety**: All paths use `vite_path` types instead of `std::path` for type safety
62+
63+
### Task Dependencies
64+
1. **Explicit dependencies**: Defined in `vite-task.json` files
65+
2. **Implicit dependencies**: Based on package.json dependencies when `--topological` flag is used
66+
3. **Compound commands**: Commands like `"build": "tsc && rollup"` are split into subtasks
67+
68+
## Common Development Tasks
69+
70+
### Repository Structure
71+
```
72+
vite-plus/
73+
├── crates/ # Rust workspace - core task runner
74+
│ ├── vite_task/ # Main binary and library
75+
│ ├── vite_path/ # Type-safe path handling
76+
│ ├── fspy/ # File system monitoring
77+
│ └── ...
78+
├── packages/ # Node.js workspace
79+
│ ├── cli/ # NAPI bindings and CLI
80+
│ └── global/ # Global installable package
81+
├── Cargo.toml # Rust workspace config
82+
├── package.json # Node.js workspace config
83+
├── pnpm-workspace.yaml
84+
└── rust-toolchain.toml
85+
```
86+
87+
### Key Files to Check When Making Changes
88+
- Always check `crates/vite_task/src/lib.rs` for CLI argument parsing changes
89+
- Always check `packages/cli/package.json` for Node.js dependencies
90+
- Always check `Cargo.toml` for Rust dependencies
91+
- Always check `.github/workflows/ci.yml` for CI requirements
92+
93+
### Development Workflow
94+
1. Make Rust changes in `crates/` directories
95+
2. Test with `cargo build --bin vt` and `./target/debug/vt`
96+
3. If changing CLI interface, rebuild with `pnpm run bootstrap-cli`
97+
4. Validate changes with `cargo test` and manual testing
98+
5. Format code (Rust auto-formats, Node.js uses built-in tooling)
99+
100+
### Debugging and Troubleshooting
101+
- Use `--debug` flag to see cache operations and detailed execution info
102+
- Use `VITE_LOG=debug` environment variable for verbose logging
103+
- Network issues in sandboxed environments are expected - focus on core functionality
104+
- SSL certificate errors when accessing npm registry are environment-specific, not code bugs
105+
106+
## Time Expectations
107+
108+
- **Initial setup**: 5-10 minutes (toolchain + dependencies)
109+
- **Incremental Rust builds**: 30-60 seconds
110+
- **Full Rust rebuild**: 3-4 minutes
111+
- **Node.js builds**: 30 seconds
112+
- **Full bootstrap**: 4+ minutes
113+
- **Test suite**: 1-2 minutes (may have network-related failures in sandbox)
114+
115+
Always set generous timeouts (300+ seconds for builds, 180+ seconds for tests) and NEVER CANCEL long-running operations.

0 commit comments

Comments
 (0)