From ddf07723fa7cefbb933bc76df5ad165e6077aa8a Mon Sep 17 00:00:00 2001 From: NIJAT Date: Sun, 28 Dec 2025 17:55:30 +0400 Subject: [PATCH] docs: update README and CONTRIBUTING with current project structure --- CONTRIBUTING.md | 67 ++++++++++++++++++++++++++++++++++--------------- README.md | 55 ++++++++++++++++++++++++++++++++-------- 2 files changed, 92 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2a2e85..1755aea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -177,32 +177,34 @@ VPN & Network • Security • File Sharing • System ## 🎨 Icon System -TuxMate uses the [Iconify API](https://iconify.design/) for icons. +TuxMate uses the [Iconify API](https://iconify.design/) for icons. Icon helpers are defined in [`src/lib/data.ts`](src/lib/data.ts). ### Helper Functions | Function | Use Case | Example | |----------|----------|---------| -| `si('slug', '#color')` | Brand icons | `si('firefox', '#FF7139')` | +| `si('slug', '#color')` | Simple Icons (brands) | `si('firefox', '#FF7139')` | | `lo('slug')` | Colorful logos | `lo('chrome')` | -| `mdi('slug', '#color')` | Material icons | `mdi('console', '#57F287')` | -| `dev('slug')` | Developer tools | `dev('vscode')` | -| `sk('slug')` | Skill/tech icons | `sk('react')` | +| `mdi('slug', '#color')` | Material Design icons | `mdi('console', '#57F287')` | +| `dev('slug')` | Devicon (dev tools) | `dev('vscode')` | +| `sk('slug')` | Skill Icons (colorful) | `sk('react')` | | `vs('slug')` | VS Code file icons | `vs('file-type-shell')` | ### Finding Icon Slugs | Source | URL | Notes | |--------|-----|-------| -| **Simple Icons** | [simpleicons.org](https://simpleicons.org/) | Use lowercase slug | +| **Simple Icons** | [simpleicons.org](https://simpleicons.org/) | Use lowercase slug, add hex color | | **Material Design** | [pictogrammers.com/library/mdi](https://pictogrammers.com/library/mdi/) | Use icon name | +| **Iconify Search** | [icon-sets.iconify.design](https://icon-sets.iconify.design/) | Search all sets | | **Fallback** | — | Use `mdi('application', '#color')` | ### Icon Requirements - ✅ Must be recognizable at 24×24px -- ✅ Use [official brand colors](https://simpleicons.org) -- ✅ Monochrome icons require a color parameter +- ✅ Use [official brand colors](https://simpleicons.org) - click icon to copy hex +- ✅ Monochrome icons (si, mdi) require a color parameter +- ✅ Colorful icons (lo, sk, vs) don't need color - ❌ Don't use blurry or low-quality external URLs --- @@ -224,6 +226,7 @@ TuxMate uses the [Iconify API](https://iconify.design/) for icons. - [ ] Tested locally with `npm run dev` - [ ] Production build passes: `npm run build` - [ ] Lint passes: `npm run lint` +- [ ] Unit tests pass: `npm run test` - [ ] Apps added in **alphabetical order** within their category - [ ] Icons display correctly at small sizes @@ -273,6 +276,7 @@ npm run dev ```bash npm run lint # Check for errors npm run lint -- --fix # Auto-fix issues +npm run test # Run unit tests npm run build # Verify production build ``` @@ -304,34 +308,57 @@ Distributions are defined in [`src/lib/data.ts`](src/lib/data.ts). { id: 'distro-id', name: 'Display Name', - iconUrl: si('distro-slug'), + iconUrl: si('distro-slug', '#color'), color: '#HexColor', installPrefix: 'sudo pkg install -y' } ``` ### After Adding a Distro -1. Update `src/lib/generateInstallScript.ts` -2. Add the distro case in `generateInstallScript()` -3. Handle distro-specific logic (repo enabling, AUR helpers, etc.) -4. Include proper error handling and package detection +1. Add the distro ID to the `DistroId` type in `src/lib/data.ts` +2. Create a new script generator file: `src/lib/scripts/[distro].ts` +3. Export the generator from `src/lib/scripts/index.ts` +4. Add the case in `src/lib/generateInstallScript.ts` (both functions) +5. Handle distro-specific logic (repo setup, package detection, etc.) +6. Add `targets.[distro]` entries to relevant apps in `data.ts` --- ## ⚙️ Script Generation -The install script logic lives in [`src/lib/generateInstallScript.ts`](src/lib/generateInstallScript.ts). +Script generation is modular. Each distro has its own generator: + +``` +src/lib/ +├── generateInstallScript.ts # Main entry point +├── aur.ts # AUR package detection +└── scripts/ + ├── index.ts # Exports all generators + ├── shared.ts # Colors, progress bars, utilities + ├── arch.ts # Arch + AUR (yay) + ├── debian.ts # Debian apt + ├── ubuntu.ts # Ubuntu apt + PPA handling + ├── fedora.ts # Fedora dnf + RPM Fusion + ├── opensuse.ts # openSUSE zypper + ├── nix.ts # Nix package manager + ├── flatpak.ts # Flatpak (parallel install) + └── snap.ts # Snap packages +``` ### Key Features to Maintain -- Package detection for already-installed software -- AUR handling with auto-install of yay helper -- RPM Fusion auto-enabling for Fedora -- Parallel installation support for Flatpak -- Exponential backoff retry for network failures -- Progress bars with ETA and colored output +- **Package detection** - Skip already-installed packages +- **AUR handling** - Auto-install `yay` helper (see `aur.ts` for patterns) +- **RPM Fusion** - Auto-enable for Fedora when needed +- **Parallel installation** - Flatpak concurrent installs +- **Network retry** - Exponential backoff for failures +- **Progress bars** - ETA with colored output +- **Shell escaping** - Security against injection (see `escapeShellString()` in `shared.ts`) ### Testing Script Changes ```bash +# Run unit tests (shell escaping, AUR detection) +npm run test + # Generate and test a script npm run dev # Select packages → Copy script → Test in VM/container diff --git a/README.md b/README.md index f194811..e3fdf24 100644 --- a/README.md +++ b/README.md @@ -52,11 +52,11 @@ Shows which apps are available for your selected distro, with instructions for u -## �📸 Screenshots 🖼️ +## 📸 Screenshots -![](src/screenshots/1.png) -![](src/screenshots/2.png) -![](src/screenshots/3.png) +![Main interface with app selection](src/screenshots/1.png) +![Category browsing and filtering](src/screenshots/2.png) +![Generated install script](src/screenshots/3.png) @@ -81,6 +81,39 @@ npm start +
+

🗂️ Project Structure

 + +``` +src/ +├── app/ # Next.js app router +│ ├── page.tsx # Main page component +│ ├── layout.tsx # Root layout with meta tags +│ └── globals.css # Tailwind styles +├── components/ +│ ├── app/ # App cards & categories +│ ├── command/ # Command footer & AUR bar +│ ├── common/ # Tooltips, loading states +│ ├── distro/ # Distribution selector +│ ├── header/ # Header & theme toggle +│ └── ui/ # Base UI components +├── hooks/ # React hooks +│ ├── useLinuxInit.ts # Main app state management +│ ├── useKeyboardNavigation.ts +│ ├── useTheme.ts +│ └── useDelayedTooltip.ts +├── lib/ +│ ├── data.ts # Apps, distros, icons +│ ├── aur.ts # AUR package detection +│ ├── analytics.ts # Umami tracking +│ ├── generateInstallScript.ts +│ └── scripts/ # Per-distro script generators +└── __tests__/ # Vitest unit tests +``` + +
+ +

🐳 Docker Deployment

 @@ -153,12 +186,14 @@ docker run -p 3000:3000 \ ## 🛠️ Tech Stack -- Next.js 16 -- React 19 -- TypeScript -- Tailwind CSS 4 -- Framer Motion -- GSAP +- [Next.js](https://nextjs.org/) 16 (App Router) +- [React](https://react.dev/) 19 +- [TypeScript](https://www.typescriptlang.org/) +- [Tailwind CSS](https://tailwindcss.com/) 4 +- [Framer Motion](https://www.framer.com/motion/) +- [GSAP](https://gsap.com/) +- [Vitest](https://vitest.dev/) (testing) +- [Lucide React](https://lucide.dev/) (icons) ## 🚀 Usage