From 94af0df574a2d9e85d777f9c30864bcb70e478f0 Mon Sep 17 00:00:00 2001 From: Montasim Date: Tue, 4 Aug 2026 10:50:39 +0600 Subject: [PATCH 1/2] docs: standardize project README --- README.md | 320 ++++++++++++++++++++++++++---------------------------- 1 file changed, 154 insertions(+), 166 deletions(-) diff --git a/README.md b/README.md index 490d441..babc406 100644 --- a/README.md +++ b/README.md @@ -1,194 +1,182 @@ -[![Support me on SupportKori](https://img.shields.io/badge/Support%20me-SupportKori-FFDD00?style=flat-square)](https://www.supportkori.com/montasim) - # DevTools +**A fast toolbox for formatting, generating, testing, and inspecting developer data.** +[![CI](https://github.com/montasim/devtools/actions/workflows/ci.yml/badge.svg)](https://github.com/montasim/devtools/actions/workflows/ci.yml) +[![Live app](https://img.shields.io/badge/live-devtoolsn.vercel.app-000000?logo=vercel)](https://devtoolsn.vercel.app) +[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE) +[![Support on SupportKori](https://img.shields.io/badge/support-SupportKori-ffdd00)](https://www.supportkori.com/montasim) -A comprehensive suite of 40+ free developer tools for formatting, validating, generating, and transforming data. All tools run entirely in your browser for maximum privacy and speed. - -## Features - -### Formatters & Converters - -| Tool | Description | -| ----------------------------- | ------------------------------------------------------------ | -| **JSON Tools** | Format, minify, diff, validate, and transform JSON | -| **Text Tools** | Diff, case conversion, and text cleaning | -| **Base64 Tools** | Encode/decode Base64 with media preview and format detection | -| **URL Encode/Decode** | Encode and decode percent-encoded URLs | -| **HTML Entity Encode/Decode** | Encode and decode HTML entities | -| **cURL Converter** | Convert cURL to fetch, Axios, Python, and HTTPie | -| **Number Base Converter** | Binary, octal, decimal, hex, and custom radix | -| **CSS Unit Converter** | Convert between px, rem, em, vw, vh, pt, cm | -| **Color Picker** | HEX, RGB, HSL, OKLCH and palette generator | -| **Markdown Preview** | Write Markdown with live preview | - -### Generators - -| Tool | Description | -| -------------------------- | ------------------------------------ | -| **ID Generator** | Generate UUIDs, ULIDs, and NanoIDs | -| **Hash Generator** | Generate hashes and HMAC signatures | -| **Bcrypt / Argon2 Hasher** | Hash and verify passwords | -| **RSA Key Generator** | Generate RSA key pairs (PEM/DER) | -| **Password Generator** | Secure passwords with strength meter | -| **QR Code Generator** | Generate customizable QR codes | -| **Git Branch Generator** | Generate consistent git branch names | - -### Network & API - -| Tool | Description | -| ----------------------- | --------------------------------------------------- | -| **API Request Builder** | Build, test, and debug HTTP requests | -| **WebSocket Tester** | Connect to WS endpoints, send/receive in real-time | -| **CORS Checker** | Test cross-origin requests and inspect CORS headers | -| **Certificate Decoder** | Decode and inspect SSL/TLS X.509 certificates | -| **User Agent Analyzer** | Parse and decode User-Agent strings | -| **DNS Lookup** | Query NS, A, AAAA, MX, TXT, CNAME, SOA, PTR records | - -### Reference - -| Tool | Description | -| ----------------------- | ---------------------------------------------------------- | -| **Regex Tester** | Test regex with live matching and capture groups | -| **HTTP Status Codes** | Searchable reference with descriptions and specs | -| **MIME Type Reference** | File extension to MIME type mapping | -| **Unicode Lookup** | Search Unicode characters by name and codepoint | -| **ASCII Table** | Interactive ASCII/Unicode reference with search and filter | - -### Utilities - -| Tool | Description | -| ------------------ | ---------------------------------------------------- | -| **CRON Builder** | Visual cron expression builder with next-run preview | -| **Unit Converter** | Data sizes, time durations, and time zones | -| **URL Shortener** | Shorten long URLs into compact links | - -### Platform Features - -- **Command Palette** — Press `Cmd+K` / `Ctrl+K` to search tools, actions, and pages -- **Context Menu** — Right-click anywhere for save, share, history, navigation, and quick tool access -- **Share Text** — Share content via links with optional password protection and expiration -- **Save & Sync** — Save tool state to your account and restore across sessions -- **History** — Automatic local history tracking for all tool inputs -- **Authentication** — Sign up, login, profile management with email/password -- **Dark Mode** — Full dark/light theme support with system preference detection -- **Responsive** — Works on desktop, tablet, and mobile -- **Easter Egg** — Try the Konami code (↑↑↓↓←→←→BA) -- **Console Banner** — Branded ASCII art greeting in browser DevTools console - -## Tech Stack - -| Layer | Technology | -| --------- | ---------------------------------- | -| Framework | Next.js 16 (App Router, Turbopack) | -| UI | React 19, shadcn/ui, Radix UI | -| Styling | Tailwind CSS 4 | -| State | TanStack React Query | -| Editor | CodeMirror 6 | -| Database | PostgreSQL via Prisma 7 | -| Auth | JWT with bcrypt password hashing | -| Icons | Lucide React, Tabler Icons | -| Email | Resend | -| Language | TypeScript | - -## Getting Started - -### Prerequisites - -- Node.js 18+ -- pnpm (recommended) or npm -- PostgreSQL (for auth and save/share features) - -### Installation +DevTools puts more than 50 everyday utilities behind one searchable interface: +JSON and text transforms, encoders, generators, network diagnostics, security +inspectors, and reference tables. Most transformations run locally in the +browser, while account sync, saved shares, short links, webhooks, and selected +network checks use server-side APIs. -```bash -git clone -cd devtools +**[Open DevTools](https://devtoolsn.vercel.app)** · Press `Ctrl+K` or `Cmd+K` +inside the app to jump directly to a tool. -pnpm install +## Tool collection -# Set up environment variables -cp .env.example .env -# Edit .env with your database URL and other secrets +| Area | Included workflows | +| --- | --- | +| Structured data | JSON, XML, SVG, HTML, CSS, SQL, YAML, and CSV formatting or transformation | +| Text and encoding | Text cleanup and diff, Base64, URL encoding, HTML entities, cURL conversion, fancy/leet text, and text art | +| Generators | UUID/ULID/NanoID, hashes, bcrypt/Argon2, RSA keys, passwords, passphrases, QR codes, sample data, and Git branch names | +| Network and APIs | Request builder, header parser, WebSocket tester, CORS checker, DNS lookup, STUN/TURN checks, webhook inbox, certificate decoding, and IP/CIDR tools | +| References | Regex, HTTP status, MIME and Content-Type, Unicode, ASCII, emoji, time zones, and cron expressions | +| Browser utilities | Markdown preview, color and unit conversion, web playground, email-domain checks, spam-word checks, and RSS analysis | -# Set up database -pnpm prisma generate -pnpm prisma db push +The navigation registry in [`config/navigation.tsx`](config/navigation.tsx) is +the source of truth for the current catalog. -pnpm dev -``` +## Privacy boundary + +“Browser-based” does not mean every feature is offline. The boundary is: + +- Formatters, encoders, generators, parsers, and most reference tools process + their current input in the browser. +- API, WebSocket, DNS, CORS, IP, STUN/TURN, email-domain, leaked-password, RSS, + and webhook utilities necessarily contact the selected target or a server + endpoint. +- Creating a share link, saved item, account, or shortened URL stores the + submitted state in PostgreSQL. Password-protected shares store a password + hash, but their content is still held server-side. +- Tool history and preferences that use local storage remain on that browser + unless the user explicitly invokes an account-backed feature. + +Do not paste credentials, production private keys, personal data, or classified +content into a networked workflow. Inspect the destination before sending an +API or WebSocket request. + +## Platform features -Open [http://localhost:3000](http://localhost:3000). +- Command palette and global right-click menu for navigation and actions +- Local input history and reusable saved state +- Optional email-OTP accounts with cross-device saved items +- Expiring and optionally password-protected share links +- URL shortening with click tracking +- Webhook request capture and inspection +- Light/dark themes and responsive layouts +- Keyboard-accessible tool tabs and controls -### Available Scripts +## Run locally + +### Requirements + +- Node.js 24.12.0, matching [`.nvmrc`](.nvmrc) +- pnpm 10, matching the CI workflow +- PostgreSQL for authentication, shares, saved items, and short URLs ```bash -pnpm dev # Start development server -pnpm build # Build for production -pnpm start # Start production server -pnpm lint # Run ESLint -pnpm lint:fix # Fix ESLint errors -pnpm format # Format with Prettier -pnpm format:check # Check formatting -pnpm typecheck # TypeScript type checking -pnpm test # Run Vitest +git clone https://github.com/montasim/devtools.git +cd devtools +nvm use +pnpm install +cp .env.example .env +pnpm exec prisma generate +pnpm exec prisma db push +pnpm dev ``` -## Project Structure - +Open . + +`prisma db push` changes the configured database schema. Point +`DATABASE_URL` at a disposable development database first; use reviewed Prisma +migrations rather than schema push for production change management. + +### Active configuration + +The application code currently reads these settings: + +| Variable | Required for | Purpose | +| --- | --- | --- | +| `DATABASE_URL` | Server-backed features | PostgreSQL connection used by Prisma | +| `BETTER_AUTH_SECRET` | Authentication | Better Auth signing secret; falls back to `JWT_SECRET` | +| `BETTER_AUTH_URL` | Authentication | Canonical auth origin; falls back to `BASE_URL` | +| `OTP_HMAC_SECRET` | Email OTP | HMAC secret used for OTP handling | +| `RESEND_API_KEY` | Email OTP | Resend API key; without it, email delivery is skipped | +| `FROM_EMAIL` | Email OTP | Verified sender address | +| `NEXT_PUBLIC_APP_URL` | Browser links | Public origin for auth and generated short URLs | + +Replace every placeholder with a development-safe value and never commit the +result. [`.env.example`](.env.example) also contains infrastructure notes and +reserved settings; the table above is intentionally limited to variables +referenced by the current application. + +## Commands + +| Command | Purpose | +| --- | --- | +| `pnpm dev` | Start the Next.js development server | +| `pnpm build` | Generate Prisma Client and create a production build | +| `pnpm start` | Serve the production build | +| `pnpm lint` | Run ESLint | +| `pnpm typecheck` | Check TypeScript without emitting files | +| `pnpm test --run` | Run the Vitest suite once | +| `pnpm format:check` | Check Prettier formatting | +| `pnpm format` | Rewrite files with Prettier | + +The GitHub Actions workflow runs dependency installation, lint, TypeScript, +and the production build for pushes and pull requests targeting `main`. + +## Architecture + +```mermaid +flowchart LR + Browser[Tool interface] --> Local[Local transforms and storage] + Browser --> API[Next.js route handlers] + API --> External[DNS / email / target services] + API --> DB[(PostgreSQL / Prisma)] + DB --> Accounts[Accounts, shares, saved items, short URLs] ``` -devtools/ -├── app/ -│ ├── (auth)/ # Auth pages (login, signup, profile, reset-password) -│ ├── (legal)/ # Legal pages (privacy, terms, cookies, disclaimer) -│ ├── (tools)/ # 30 tool pages -│ ├── api/ # API routes (auth, saved, shares, shortener) -│ ├── docs/ # Documentation -│ ├── share/ # Shared content viewer -│ ├── layout.tsx # Root layout -│ └── page.tsx # Home page -├── components/ -│ ├── layout/ # Layout components (context menu, command palette, easter egg) -│ ├── navbar/ # Navigation bar -│ ├── providers/ # Theme, auth, query, tooltip providers -│ └── ui/ # Reusable UI primitives (shadcn) -├── config/ -│ ├── navigation.tsx # Navigation menu and tool definitions -│ └── seo.ts # SEO metadata for all pages -├── features/ -│ ├── auth/ # Authentication hooks and components -│ └── tools/ # Tool implementations -│ ├── core/ # Shared hooks, components, plugins, context -│ └── / # Individual tool modules with tabs -├── hooks/ # Shared React hooks -├── lib/ # Utilities, API client, SEO helpers -└── prisma/ # Database schema and migrations + +```text +app/(tools)/ Tool pages and route-level metadata +features/tools/ Individual tools, tabs, hooks, data, and utilities +features/auth/ Account-facing hooks and components +app/api/ Auth, DNS, saved, share, URL, and webhook endpoints +config/navigation.tsx Searchable tool catalog and navigation +lib/ Auth, Prisma, API client, storage, and shared helpers +prisma/schema.prisma Server-backed data model ``` -## Keyboard Shortcuts +## Deployment -| Shortcut | Action | -| ------------------ | -------------------- | -| `Cmd+K` / `Ctrl+K` | Open command palette | -| `↑↑↓↓←→←→BA` | Easter egg | +The maintained deployment runs at +[devtoolsn.vercel.app](https://devtoolsn.vercel.app). A self-hosted deployment +needs a PostgreSQL database and production values for the active configuration +above. Use HTTPS for auth and shared-content flows, set the canonical public +origin consistently, and apply the Prisma schema before serving traffic. -## Contributing +## Limitations -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'feat: add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request +- Browser security policies can block cross-origin API checks even when the + target works from a server or CLI. +- DNS, IP reputation, disposable-email, and similar third-party information can + be incomplete or stale. +- Cryptographic utilities are convenience tools, not a substitute for a + reviewed key-management or password-storage design. +- Share and URL-shortener availability depends on the deployment and database; + local-only utilities remain useful without an account. -This project uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitlint. +## Contributing and security -## Support +Open a focused issue or pull request with reproduction steps, screenshots when +useful, and the checks you ran. New tools should declare whether input stays in +the browser, contacts a third party, or is persisted server-side. -If this project has been useful, you can support its continued maintenance: +Report vulnerabilities privately through the contact links on +[the maintainer's GitHub profile](https://github.com/montasim), not in a public +issue. Never include real secrets or user-submitted share content in reports. -[![Support me on SupportKori](https://img.shields.io/badge/Support%20me-SupportKori-FFDD00?style=flat-square)](https://www.supportkori.com/montasim) +Optional support through [SupportKori](https://www.supportkori.com/montasim) +helps fund hosting and maintenance. ## License -MIT +Licensed under the [MIT License](LICENSE). + +## Maintainer + +[Mohammad Montasim Al Mamun Shuvo](https://github.com/montasim) From 627049dcfb90f81141b678aa03d391985fd63d0c Mon Sep 17 00:00:00 2001 From: Montasim Date: Tue, 4 Aug 2026 11:08:32 +0600 Subject: [PATCH 2/2] docs: complete README reader guide --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/README.md b/README.md index babc406..ad64381 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,19 @@ network checks use server-side APIs. **[Open DevTools](https://devtoolsn.vercel.app)** · Press `Ctrl+K` or `Cmd+K` inside the app to jump directly to a tool. +> **Project status:** the public tool suite is actively deployed. Local-only +> transforms work without an account; authentication, sync, sharing, short +> links, and server-assisted network tools depend on the production APIs and +> PostgreSQL configuration. CI validates lint, TypeScript, and a production +> build for changes targeting `main`. + +## Why DevTools? + +Small developer tasks often mean searching for many unrelated websites, +rechecking how each handles pasted data, and losing context between tools. +DevTools keeps those workflows in one consistent, searchable interface and +makes the local-versus-network processing boundary explicit. + ## Tool collection | Area | Included workflows | @@ -30,6 +43,33 @@ inside the app to jump directly to a tool. The navigation registry in [`config/navigation.tsx`](config/navigation.tsx) is the source of truth for the current catalog. +## Using DevTools + +### Run a local transformation + +1. Open [DevTools](https://devtoolsn.vercel.app) and press `Ctrl+K` or `Cmd+K`. +2. Search for a formatter, encoder, generator, parser, or reference page. +3. Paste or generate the input and choose the relevant tab or operation. +4. Review the result before copying or downloading it. +5. Clear the browser state when working on a shared device. + +### Run a network check + +1. Open the API, WebSocket, DNS, CORS, STUN/TURN, webhook, or email-domain tool. +2. Confirm that you are authorized to contact the target and that the request + contains no secret that should be kept out of a third-party service. +3. Submit the narrowest useful request and inspect status, headers, timing, and + response output. +4. Treat browser CORS failures and third-party lookup results as diagnostic + evidence, not definitive proof that a service is unavailable or safe. + +### Save or share work + +Sign in with email OTP to sync supported saved items. Creating a share or short +link persists content or destination metadata on the server; set an expiration +and password where supported, and remove saved material when it is no longer +needed. + ## Privacy boundary “Browser-based” does not mean every feature is offline. The boundary is: @@ -49,6 +89,19 @@ Do not paste credentials, production private keys, personal data, or classified content into a networked workflow. Inspect the destination before sending an API or WebSocket request. +## Technology + +| Area | Technology | +| --- | --- | +| Application | Next.js 16, React 19, TypeScript 5 | +| Interface | Tailwind CSS 4, shadcn/ui, Radix UI, CodeMirror 6 | +| Client data | TanStack React Query, local storage | +| Server data | PostgreSQL, Prisma 7 | +| Authentication | Better Auth email OTP, bcrypt | +| Validation and formatting | Zod, AJV, Shiki, SQL Formatter | +| Testing and quality | Vitest, Testing Library, ESLint, Prettier, GitHub Actions | +| Deployment | Vercel | + ## Platform features - Command palette and global right-click menu for navigation and actions @@ -74,6 +127,11 @@ cd devtools nvm use pnpm install cp .env.example .env +``` + +Replace `DATABASE_URL` and every secret placeholder before schema setup: + +```bash pnpm exec prisma generate pnpm exec prisma db push pnpm dev @@ -93,11 +151,14 @@ The application code currently reads these settings: | --- | --- | --- | | `DATABASE_URL` | Server-backed features | PostgreSQL connection used by Prisma | | `BETTER_AUTH_SECRET` | Authentication | Better Auth signing secret; falls back to `JWT_SECRET` | +| `JWT_SECRET` | Authentication fallback | Fallback signing secret when `BETTER_AUTH_SECRET` is absent | | `BETTER_AUTH_URL` | Authentication | Canonical auth origin; falls back to `BASE_URL` | +| `BASE_URL` | Authentication fallback | Server-side fallback application origin | | `OTP_HMAC_SECRET` | Email OTP | HMAC secret used for OTP handling | | `RESEND_API_KEY` | Email OTP | Resend API key; without it, email delivery is skipped | | `FROM_EMAIL` | Email OTP | Verified sender address | | `NEXT_PUBLIC_APP_URL` | Browser links | Public origin for auth and generated short URLs | +| `NEXT_PUBLIC_BASE_URL` | Browser auth fallback | Browser-visible fallback origin for the auth client | Replace every placeholder with a development-safe value and never commit the result. [`.env.example`](.env.example) also contains infrastructure notes and @@ -112,11 +173,15 @@ referenced by the current application. | `pnpm build` | Generate Prisma Client and create a production build | | `pnpm start` | Serve the production build | | `pnpm lint` | Run ESLint | +| `pnpm lint:fix` | Run ESLint and apply safe fixes | | `pnpm typecheck` | Check TypeScript without emitting files | | `pnpm test --run` | Run the Vitest suite once | | `pnpm format:check` | Check Prettier formatting | | `pnpm format` | Rewrite files with Prettier | +`pnpm prepare` installs the repository's Husky hooks and normally runs as an +install lifecycle step. + The GitHub Actions workflow runs dependency installation, lint, TypeScript, and the production build for pushes and pull requests targeting `main`. @@ -141,6 +206,16 @@ lib/ Auth, Prisma, API client, storage, and shared helpers prisma/schema.prisma Server-backed data model ``` +## Documentation + +- [In-app documentation](https://devtoolsn.vercel.app/docs) +- [Tool registry](config/navigation.tsx) +- [Environment template](.env.example) +- [Database schema](prisma/schema.prisma) +- [CI workflow](.github/workflows/ci.yml) +- [Privacy boundary](#privacy-boundary) +- [Local development](#run-locally) + ## Deployment The maintained deployment runs at @@ -159,6 +234,8 @@ origin consistently, and apply the Prisma schema before serving traffic. reviewed key-management or password-storage design. - Share and URL-shortener availability depends on the deployment and database; local-only utilities remain useful without an account. +- The current CI workflow does not execute the Vitest suite; run + `pnpm test --run` explicitly when changing tool behavior. ## Contributing and security @@ -170,9 +247,24 @@ Report vulnerabilities privately through the contact links on [the maintainer's GitHub profile](https://github.com/montasim), not in a public issue. Never include real secrets or user-submitted share content in reports. +The repository currently has no dedicated `CONTRIBUTING.md`, `SECURITY.md`, +`CODE_OF_CONDUCT.md`, or `SUPPORT.md`. Use +[Issues](https://github.com/montasim/devtools/issues) for public reports, +[Pull Requests](https://github.com/montasim/devtools/pulls) for changes, and the +maintainer's profile for private security reports. Contributions use +Conventional Commits as configured by commitlint. + Optional support through [SupportKori](https://www.supportkori.com/montasim) helps fund hosting and maintenance. +## Funding + +Optional SupportKori contributions help cover hosting, database services, and +maintenance of the growing tool catalog. Bug reports, tests, accessibility +improvements, and documentation are equally valuable. + +[![Support DevTools on SupportKori](https://img.shields.io/badge/Support_DevTools-SupportKori-00B8B5?style=for-the-badge)](https://www.supportkori.com/montasim) + ## License Licensed under the [MIT License](LICENSE).