Skip to content

copilot-instructions.md

Latest commit

 

History

History
253 lines (194 loc) · 14.3 KB

copilot-instructions.md

File metadata and controls

253 lines (194 loc) · 14.3 KB

🤖 GitHub Copilot Contributor Guide for DevStackBox

Welcome to the DevStackBox contributor and Copilot guide!
This file will help you develop for the modern Tauri + Vite + React + Tailwind CSS + shadcn/ui + Framer Motion stack, and use GitHub Copilot in Visual Studio Code for efficient, maintainable development.

Author: Nomad Programmer
Contact: shiv@srapsware.com
Repository: ProgrammerNomad/DevStackBox
Documentation & Issues: GitHub Issues and GitHub Wiki
Auto-updates: Managed via GitHub Releases with Tauri’s updater.

🚀 Overview

DevStackBox is a lightweight, portable, open-source local development environment for PHP developers.
It is built with Tauri for a smaller, faster, and more native experience, using a modern, maintainable frontend stack.
All documentation, project management, and bug reporting are via GitHub.

Key stack points:

  • All backend/service management runs in Rust via Tauri.
  • The frontend is a Vite-powered React app, styled with Tailwind CSS and shadcn/ui, using Framer Motion for animations.
  • No custom CSS unless absolutely necessary; dark/light mode is required everywhere.

🛠️ 1. Development Environment & Prerequisites

  • Primary OS: Windows 11 (development and primary testing)
  • Editor: Visual Studio Code (with Copilot extension)
  • Frontend: Vite + React + Tailwind CSS + shadcn/ui + Framer Motion
  • Backend: Tauri (Rust)
  • No custom CSS: Use only Tailwind and shadcn/ui, document any CSS exceptions.
  • Dark/Light Mode: All UI must fully support both (Tailwind/shadcn/ui patterns).
  • Auto-update: App is auto-updated from GitHub Releases.

Install:

git clone https://github.com/ProgrammerNomad/DevStackBox.git
cd DevStackBox
pnpm install  # or npm/yarn
cargo install tauri-cli
pnpm tauri dev  # or npm run tauri dev

📂 2. Project Structure

DevStackBox/
├── src-tauri/         # Rust backend (service mgmt, config, IPC, updater)
├── src/               # Frontend: Vite + React + Tailwind + shadcn/ui + Framer Motion
├── mysql/             # Portable MySQL setup
├── php/               # PHP 8.2 binaries (default)
├── apache/            # Apache setup (planned)
├── phpmyadmin/        # phpMyAdmin
├── apps/              # One-click app installers (planned)
├── config/            # Config files (php.ini, my.cnf, httpd.conf, etc.)
├── config-backups/    # Config backups
├── logs/              # Service/app logs
├── www/               # Web root (planned)
├── locales/           # i18next translations (EN, HI)
└── package.json

🗂️ 3. Full Feature/Status Table (Updated v0.1.6)

Feature Status Description
MySQL Database ✅ Available Embedded MySQL with GUI control
phpMyAdmin Integration ✅ Available Built-in database management
Modern Tailwind/shadcn/ui/Framer UI ✅ Available Responsive, animated, utility-first UI
Config Management (Backup/Restore) ✅ Available Syntax highlighting, backup/restore
Multilanguage UI (i18next, EN/HI) ✅ Available English & Hindi, Unicode correct
Clean Semantic Versioning ✅ Available MSI-compatible version format (v0.1.6)
GitHub Actions CI/CD ✅ Available Automated builds with MSI & NSIS installers
Project Structure Cleanup ✅ Available Organized codebase with proper file locations
Build Optimization ✅ Available 288.9MB MSI, 147.7MB NSIS installers
Crash & Bug Reporting via GitHub 🔄 In Progress Report bugs/crashes via GitHub Issues
Logs Viewer 🔄 In Progress Real-time log viewing with filter/search
System Tray Integration ✅ Available Minimize to tray/quick actions
Auto-Update 🔄 In Progress Via GitHub Releases
Apache HTTP Server 🕓 Planned Portable Apache, vhost & HTTPS
Multiple PHP Versions 🕓 Planned Download via in-app installer
One-Click App Installers 🕓 Planned WordPress, Laravel, etc.
PHP Extensions Management 🕓 Planned Enable/disable per version
Security Analyzer 🕓 Planned Scan configs/code for issues
Mail Testing Tools 🕓 Planned Mailhog, etc.
Portable Mode 🕓 Planned All data in app folder
Database/User Management 🕓 Planned Manage users, backup/restore, SSL
Database Backup/Restore (One-Click) 🕓 Planned UI to export/import MySQL databases
Quick Launch Tools 🕓 Planned Terminal (PHP/MySQL CLI), copy connection string, etc.
Full App/Data Backup/Restore 🕓 Planned Backup configs, databases, logs in one click
Automatic Virtual Host Management 🕓 Planned Pretty URLs like myapp.test
HTTPS/SSL for Local Sites 🕓 Planned One-click SSL for local domains and phpMyAdmin
Project Templates/Cloning 🕓 Planned Clone from Git or use templates for new projects
Composer Integration 🕓 Planned Global/per-project Composer support
PHP INI & Apache Config Editors 🕓 Planned User-friendly config editing
PHP Error Display Toggle 🕓 Planned Enable/disable display_errors from UI
Service Status & Tray Notifications 🕓 Planned Tray notifications for service events
Portable PHP CLI 🕓 Planned Terminal with PHP version selector
Bundled Tools (curl, git, node, npm, etc.) 🕓 Planned Optionally bundle common CLI tools
Log Viewer Enhancements 🕓 Planned Real-time, filterable, tabbed log viewer for all services/apps
Project Full Backup/Restore 🕓 Planned Backup/restore www files, configs, databases

Legend:
✅ Available  🔄 In Progress  🕓 Planned

🧑‍💻 4. Copilot Usage & Prompt Patterns

  • Backend (Rust, src-tauri):
    "Write a Tauri command to start MySQL and return its status to the frontend."
    "Add a Tauri command to download additional PHP binaries via an in-app installer."

  • Frontend (React, src/):
    "Create a MySQL control panel using shadcn/ui, Tailwind, Framer Motion; support dark/light mode."
    "Add a modal for backup/restore using shadcn/ui and Tailwind."
    "Implement a language switcher with i18next and Unicode support for Hindi."

  • Config & Logs:
    "Show a real-time logs viewer with tabs for MySQL, Apache, PHP logs using Tailwind and xterm.js."
    "Add config editor with Monaco and backup/restore UI using shadcn/ui."

  • General:
    "All UI must support dark/light mode and be styled only with Tailwind/shadcn/ui."

📦 5. Binary Management

  • Default PHP: Only PHP 8.2 is bundled by default.
  • Other Binaries: Downloadable on demand via the in-app distribution installer—do not bundle extra binaries by default.

💡 6. Detailed Copilot Examples

  • "Add a config editor with Monaco and backup/restore, styled with Tailwind and shadcn/ui, supporting dark/light mode."
  • "Implement a logs viewer in React using xterm.js, with tabs for each service, filter and search, and animated transitions with Framer Motion."
  • "Write a Tauri command in Rust to download and extract a PHP version into the php/ directory and notify the frontend on completion."
  • "Create a modal with shadcn/ui for reporting bugs, which opens a GitHub Issue link with prefilled content."
  • "Implement a multilanguage language switcher with i18next and Unicode support for Hindi, styled for header consistency."

🌐 7. Multilanguage & Unicode

  • Use i18next for all user-facing text (English & Hindi)
  • Use Tailwind and system fonts for perfect Unicode/Devanagari rendering
  • Language switcher must use Unicode names ("English", "हिन्दी") and consistent header styling

🎨 8. UI/UX & Styling Guidelines

  • All UI styled only with Tailwind and shadcn/ui; do not use custom CSS unless essential and well-documented.
  • All components must support both dark and light mode via Tailwind/shadcn/ui.
  • Animations and transitions must use Framer Motion (not CSS keyframes or raw JS).
  • Responsive, accessible, and visually consistent.
  • Use shadcn/ui dialogs, modals, menus everywhere possible.

🖥️ 9. Modern Menu & Navigation Patterns

DevStackBox uses a combination of modern, desktop-inspired navigation patterns for clarity and usability:

  • Sidebar Navigation (Primary):
    Use shadcn/ui's NavigationMenu or a custom sidebar for main sections (Dashboard, Projects, Services, Logs, Settings, About).

    • Supports icons, labels, section grouping, and collapsible "rail" mode.
    • Copilot prompt:
      "Create a sidebar menu with shadcn/ui and Tailwind, supporting dark/light mode and collapsible icons."

  • Top Bar (Secondary):
    Place global actions (theme switcher, language selector, user menu, updates) in a sticky top bar above or beside the sidebar.

    • Copilot prompt:
      "Implement a top bar with theme and language switchers, using shadcn/ui and Tailwind."

  • Tabs (Sub-navigation):
    Use shadcn/ui's Tabs for sub-sections within a page (e.g., "Overview | Logs | Settings" for a given service).

    • Copilot prompt:
      "Add tabs for logs and settings in a service detail view, using shadcn/ui Tabs."

  • Context Menus:
    Use shadcn/ui's ContextMenu for right-click/“more” actions on project, database, or service items.

    • Copilot prompt:
      "Add a context menu for each database row with edit/delete options using shadcn/ui."

  • Command Palette:
    Add a command palette (Ctrl+P/Cmd+P) with shadcn/ui's Command for fast search, navigation, and command execution (power user feature).

    • Copilot prompt:
      "Create a command palette using shadcn/ui Command for quick actions and navigation."

  • Floating Action Buttons:
    For quick “add” actions (e.g., new project/database), use floating shadcn/ui Button with fixed positioning (optional, desktop only).

Guidelines:

  • All navigation must be accessible (keyboard, screen readers).
  • Sidebar and command palette are primary navigation for all major DevStackBox features.
  • Always use Tailwind and shadcn/ui components for styling and transitions (no custom CSS unless needed).

� 12. Recent Achievements & Lessons Learned (v0.1.6)

✅ Major Fixes Completed:

  • MSI Compatibility: Fixed version format from 0.1.0-alpha.6 to 0.1.6 for MSI bundler
  • File Structure: Resolved accidental deletion of critical files (globals.css, main.tsx, index.html)
  • GitHub Actions: Fixed emoji encoding issues causing PowerShell parsing errors
  • CSS Pipeline: Restored complete Tailwind CSS compilation (27.60 kB output)
  • Build System: Successfully generating both MSI (288.9MB) and NSIS (147.7MB) installers

🎓 Key Lessons:

  • Always use clean semantic versioning for MSI compatibility (no hyphens, no text)
  • Avoid emoji characters in PowerShell scripts for GitHub Actions
  • Verify file locations before deletion - check if files are truly duplicates
  • Root-level files may be the correct ones in Vite projects
  • Test build output to ensure CSS is being compiled correctly

🔧 Technical Improvements:

  • GitHub Actions workflow is now emoji-free and stable
  • Proper project structure following Vite + React + Tauri best practices
  • All source files correctly organized with proper import paths
  • Build artifacts cleaned up for release preparation

�📦 10. Auto-Update & Issue Tracking

🤝 11. Contributing

  • Fork, branch, code, and PR as usual.
  • Use Copilot for both Rust (backend) and React (frontend) code.
  • Comment/refactor Copilot suggestions as needed.
  • Keep code linted, typed, and documented.
  • Test on all platforms (Windows 11 is primary).
  • Contact: shiv@srapsware.com

Let’s build the most modern, beautiful, and lightweight PHP dev stack together!

Author: Nomad Programmer • Email: shiv@srapsware.com • Project on GitHub