nport 2.0.6 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,196 @@ All notable changes to NPort will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-01-27
+
+### Added
+- 🔷 **Full TypeScript Migration**: Complete rewrite of CLI and Server in TypeScript
+  - Strict type checking enabled across the entire codebase
+  - All modules converted from JavaScript to TypeScript
+  - Type-safe interfaces for configuration, tunnels, analytics, and i18n
+  - Better IDE support with IntelliSense and autocompletion
+- 📚 **Comprehensive Documentation**: New docs folder with detailed guides
+  - `docs/ARCHITECTURE.md`: System overview, component diagrams, and data flow
+  - `docs/API.md`: Complete API reference with endpoints and examples
+  - `docs/CONTRIBUTING.md`: Contribution guidelines and development setup
+- 🤖 **AI Context Support**: Added `.ai/context.md` for AI-assisted development
+  - Project structure and key patterns documented
+  - Coding conventions and architecture decisions
+  - Makes AI pair programming more effective
+- 🧪 **Unit Testing with Vitest**: Comprehensive test suite for CLI
+  - Tests for argument parsing (`tests/args.test.ts`)
+  - Tests for version comparison (`tests/version.test.ts`)
+  - Tests for state management (`tests/state.test.ts`)
+  - Easy to run with `npm test`
+- 📋 **Code Ownership**: Added `.github/CODEOWNERS` file
+  - Clear ownership for code review assignments
+  - Faster PR reviews with automatic reviewer assignment
+- 📝 **Cursor Rules**: Added `.cursorrules` for consistent AI assistance
+  - Project-specific coding conventions
+  - TypeScript and naming guidelines
+  - Common patterns and anti-patterns
+- 🔄 **Auto-download Cloudflared**: Binary downloads automatically on first run
+  - No need to run separate install commands
+  - Seamless first-time user experience
+  - Progress indicator during download
+- 🔒 **Protected Subdomain Support**: Enhanced error handling for reserved subdomains
+  - User-friendly error message when trying to create protected subdomains (like `api`)
+  - Formatted error output matching existing error style
+  - Helpful suggestions to use alternative subdomain names
+  - Prevents accidental use of backend service subdomains
+- 📋 **TODO Management**: Added `TODO.md` for tracking planned features
+  - Move time limit enforcement to backend
+  - Update README powered-by section
+  - Track terminal link clicks
+
+### Changed
+- 🏗️ **Project Structure**: Reorganized for better maintainability
+  - All source code in `src/` directory
+  - Type definitions in `src/types/`
+  - Shared constants in `src/constants.ts`
+  - Tests in `tests/` directory
+- 📦 **Build System**: Updated to TypeScript compilation
+  - Uses `tsc` for compilation
+  - Output to `dist/` directory
+  - Source maps for debugging
+- 🔧 **Development Workflow**: Improved developer experience
+  - `npm run dev` for watch mode
+  - `npm run build` for production
+  - `npm test` for running tests
+  - `npm run lint` for type checking
+- ⚙️ **System Requirements**: Updated to Node.js 20+
+  - Minimum Node.js version: 20.0.0
+  - Minimum npm version: 10.0.0
+  - Better security and performance with latest LTS
+
+### Improved
+- ✨ **Better Error Messages**: Enhanced user feedback for protected subdomains
+  - Catches `SUBDOMAIN_PROTECTED` errors from backend
+  - Formats error messages consistently with other error types
+  - Shows actionable options when subdomain is reserved
+
+### Fixed
+- 🐛 **Intel Mac Binary Download**: Fixed cloudflared binary download on Intel Macs
+  - Node.js reports architecture as `x64`, not `amd64` - now correctly mapped
+  - Fixed ARM64 Macs to download the correct `cloudflared-darwin-arm64.tgz` binary
+  - Previously ARM64 Macs were incorrectly downloading the AMD64 binary
+
+### Server (v1.1.0)
+- 🔷 **TypeScript Migration**: Server fully converted to TypeScript
+  - Type-safe Cloudflare Worker handlers
+  - Properly typed API responses
+  - Full type coverage for Cloudflare API interactions
+- 🧪 **Server Tests**: Updated test suite for TypeScript
+  - Vitest with Cloudflare Workers pool
+  - Tests for all API endpoints
+  - Scheduled task testing
+- 🔒 **Protected Subdomains**: Infrastructure to protect critical subdomains from deletion or overwriting
+  - New `PROTECTED_SUBDOMAINS` constant array for easy management of reserved subdomains
+  - Default protected subdomain: `api` (reserved for NPort backend service)
+  - Easy to add more protected subdomains by updating the array
+  - Protected subdomains are blocked at both creation and cleanup stages
+- 🛡️ **Backend Service Protection**: Prevents accidental deletion or overwriting of production services
+  - `api` subdomain is now protected from user creation attempts
+  - Scheduled cleanup job skips protected subdomains
+  - Returns clear error message when users try to use protected names
+- 🔧 **Manual Cleanup Endpoint**: Added `GET /scheduled` endpoint to manually trigger cleanup
+  - Useful for testing and on-demand cleanup
+  - Respects protected subdomains configuration
+  - Returns JSON response with cleanup results
+
+### Technical Details
+- **Type System**: 
+  - `TunnelConfig`, `TunnelState`, `ConnectionInfo` interfaces
+  - `AnalyticsParams`, `VersionInfo`, `I18nStrings` types
+  - `LogPatterns` with readonly arrays for constants
+- **ESM Compliance**: All imports use `.js` extensions as required
+- **Constants**: Centralized in `src/constants.ts` with `as const` assertions
+- **Error Handling**: Type-safe error boundaries throughout
+
+### Migration
+- Automatic migration - no manual steps required
+- Existing configuration in `~/.nport/config.json` remains compatible
+- All CLI flags and options unchanged
+
+### Breaking Changes
+- None - fully backward compatible!
+
+## [2.0.7] - 2026-01-14
+
+### Added
+- 🌐 **Smart Network Warning System**: Intelligent handling of QUIC/network connectivity issues
+  - Automatic detection and filtering of QUIC protocol errors
+  - User-friendly warning messages instead of scary red error spam
+  - Bilingual support (English & Vietnamese)
+  - Smart throttling: Shows warning only after 5 errors, max once per 30 seconds
+  - Clear explanations of what's happening and how to fix it
+  - Automatic reset when connection is restored
+- 🔒 **Protected Subdomain Support**: Enhanced error handling for reserved subdomains
+  - User-friendly error message when trying to create protected subdomains (like `api`)
+  - Formatted error output matching existing error style
+  - Helpful suggestions to use alternative subdomain names
+  - Prevents accidental use of backend service subdomains
+
+### Improved
+- 🔇 **Cleaner Terminal Output**: No more error spam from cloudflared
+  - QUIC timeout errors are now silently tracked instead of displayed
+  - Network warnings filtered: "failed to accept QUIC stream", "timeout: no recent network activity", etc.
+  - Only shows meaningful warnings when there's an actual persistent issue
+  - Terminal stays clean and readable during normal operation
+- 📡 **Better User Communication**: Context-aware network issue reporting
+  - Explains that QUIC failures are usually not critical
+  - Tunnel continues working via HTTP/2 fallback
+  - Provides actionable troubleshooting steps
+  - Reassures users that the tunnel is still functional
+- ✨ **Better Error Messages**: Enhanced user feedback for protected subdomains
+  - Catches `SUBDOMAIN_PROTECTED` errors from backend
+  - Formats error messages consistently with other error types
+  - Shows actionable options when subdomain is reserved
+
+### Technical Details
+- **Network Error Patterns**: Added detection for 7 common QUIC/network error patterns
+- **State Management**: New network issue tracking in application state
+  - `networkIssueCount`: Counter for network errors
+  - `lastNetworkWarningTime`: Timestamp tracking for cooldown
+  - `shouldShowNetworkWarning()`: Smart decision logic
+- **Configuration**: New `NETWORK_CONFIG` with threshold and cooldown settings
+- **Bilingual Messages**: Complete translations for all network warning messages
+- **Protected Subdomain Handling**: Enhanced error handling in `src/api.js`
+  - Added check for `SUBDOMAIN_PROTECTED` error type
+  - Consistent formatting with existing error messages
+  - Clear user guidance for alternative subdomain choices
+
+### User Experience
+**Before:**
+```
+[Cloudflared] 2026-01-14T04:33:02Z ERR failed to accept QUIC stream...
+[Cloudflared] 2026-01-14T04:33:03Z ERR failed to accept QUIC stream...
+[Cloudflared] 2026-01-14T04:33:04Z ERR failed to accept QUIC stream...
+[Cloudflared] 2026-01-14T04:33:05Z ERR failed to accept QUIC stream...
+```
+
+**After:**
+```
+✔ [1/2] Connection established...
+✔ [2/2] Compression enabled...
+
+⚠️  NETWORK CONNECTIVITY ISSUE DETECTED
+   Cloudflared is having trouble maintaining a stable connection...
+   📡 Your tunnel is still working, but connection quality may be affected.
+   
+   💡 Possible reasons:
+      • Unstable internet connection or high packet loss
+      • Firewall/Router blocking UDP traffic (QUIC protocol)
+      • ISP throttling or network congestion
+      
+   🔧 What to try:
+      • Check your internet connection stability
+      • Try connecting from a different network
+      • Disable VPN/Proxy if you're using one
+      
+   ℹ️  This is usually not critical - your tunnel should continue working normally.
+```
+
 ## [2.0.6] - 2026-01-13
 
 ### Added
@@ -110,6 +300,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version Upgrade Guide
 
+### From 2.0.7 to 2.1.0
+
+```bash
+npm install -g nport@latest
+```
+
+**What's New:**
+
+1. **Full TypeScript Rewrite**
+   - Both CLI and Server now fully typed
+   - Better IDE support and autocompletion
+   - Catches errors at compile time
+
+2. **Comprehensive Documentation**
+   - Architecture guide in `docs/ARCHITECTURE.md`
+   - API reference in `docs/API.md`
+   - Contributing guide in `docs/CONTRIBUTING.md`
+
+3. **Unit Testing**
+   - Run tests with `npm test`
+   - Covers argument parsing, version checks, state management
+
+4. **Auto-download Cloudflared**
+   - Binary downloads automatically on first `nport` run
+   - No separate install step needed
+
+5. **AI-Friendly Codebase**
+   - `.ai/context.md` for AI assistants
+   - `.cursorrules` for consistent AI suggestions
+   - JSDoc comments throughout
+
+**For Contributors:**
+```bash
+git clone https://github.com/tuanngocptn/nport
+cd nport
+npm install
+npm run build
+npm run dev  # Watch mode
+```
+
+**Breaking Changes:** None - fully backward compatible!
+
+### From 2.0.6 to 2.0.7
+
+```bash
+npm install -g nport@latest
+```
+
+**What's New:**
+
+1. **Cleaner Terminal Experience**
+   - No more scary red QUIC error spam
+   - Smart network warnings when needed
+   - Automatic fallback to HTTP/2 when QUIC fails
+
+2. **Better Error Communication**
+   - Understand what's happening with your connection
+   - Clear explanations in your language (EN/VI)
+   - Actionable troubleshooting steps
+
+3. **When You'll See Warnings**
+   - Only after multiple network issues (not just one)
+   - Maximum once every 30 seconds (no spam)
+   - Automatically disappears when connection improves
+
+**Breaking Changes:** None - fully backward compatible!
+
 ### From 2.0.5 to 2.0.6
 
 ```bash

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Pham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,6 +6,7 @@
 [![NPM](https://img.shields.io/npm/v/nport?color=red&logo=npm)](https://www.npmjs.com/package/nport)
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Fnport.link&up_message=nport.link&up_color=blue&down_color=lightgrey&down_message=offline)](https://nport.link)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
 
 ## What is NPort?
 
@@ -35,6 +36,17 @@ Perfect for:
 
 ## 📦 Installation
 
+### Requirements
+
+- **Node.js** >= 20.0.0
+- **npm** >= 10.0.0
+
+Check your versions:
+```bash
+node --version
+npm --version
+```
+
 ### NPM (Recommended)
 
 ```bash
@@ -258,25 +270,30 @@ Internet → Cloudflare Edge → Cloudflare Tunnel → Your localhost:3000
 
 ## 🏗️ Project Structure
 
-NPort uses a modular architecture for better maintainability:
-
 ```
 nport/
-├── index.js              # Main entry point
-├── src/
-│   ├── analytics.js      # Analytics tracking
-│   ├── api.js            # Backend API client
-│   ├── args.js           # CLI argument parser
-│   ├── binary.js         # Cloudflared binary manager
-│   ├── bin-manager.js    # Binary download/installation
-│   ├── config.js         # Configuration constants
-│   ├── lang.js           # Multilingual support
-│   ├── state.js          # Application state
-│   ├── tunnel.js         # Tunnel orchestration
-│   ├── ui.js             # User interface display
-│   └── version.js        # Version management
-└── bin/
-    └── cloudflared       # Cloudflare tunnel binary
+├── src/                         # TypeScript source files
+│   ├── index.ts                 # Entry point
+│   ├── tunnel.ts                # Tunnel orchestration
+│   ├── api.ts                   # Backend API client
+│   ├── args.ts                  # CLI argument parser
+│   ├── binary.ts                # Cloudflared process manager
+│   ├── ui.ts                    # Console UI components
+│   ├── lang.ts                  # Multilingual support
+│   ├── types/                   # TypeScript type definitions
+│   └── ...
+│
+├── tests/                       # Unit tests (vitest)
+├── dist/                        # Compiled output
+├── bin/                         # cloudflared binary (downloaded)
+│
+├── server/                      # Backend (Cloudflare Worker)
+├── website/                     # Static landing page
+├── docs/                        # Documentation
+│   ├── ARCHITECTURE.md          # Technical architecture
+│   ├── API.md                   # API reference
+│   └── CONTRIBUTING.md          # Contribution guide
+└── .ai/                         # AI context files
 ```
 
 ## 🛡️ Security
@@ -359,7 +376,7 @@ Then select your preferred language from the menu.
 - 🇺🇸 **English** (`en`) - Default
 - 🇻🇳 **Vietnamese** (`vi`) - Tiếng Việt
 
-Want to add your language? Contributions are welcome! Check out `src/lang.js` to see how easy it is to add translations.
+Want to add your language? Contributions are welcome! Check out the [Contributing Guide](docs/CONTRIBUTING.md).
 
 ## 🤝 Contributing
 
@@ -371,22 +388,26 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-### Adding a New Language
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines.
 
-To add a new language:
+### Development Setup
 
-1. Open `src/lang.js`
-2. Add your language code to `availableLanguages` array
-3. Add translations to the `TRANSLATIONS` object
-4. Submit a PR!
+```bash
+# Clone the repository
+git clone https://github.com/tuanngocptn/nport.git
+cd nport
 
-Example:
-```javascript
-const TRANSLATIONS = {
-  en: { /* English translations */ },
-  vi: { /* Vietnamese translations */ },
-  es: { /* Your Spanish translations */ },
-};
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Run CLI locally
+node dist/index.js 3000 -s test
 ```
 
 ## 💖 Support
@@ -397,7 +418,7 @@ If you find NPort useful, please consider supporting the project:
 - ☕ [Buy me a coffee](https://buymeacoffee.com/tuanngocptn)
 - 💬 Share with your friends and colleagues
 - 🐛 [Report bugs](https://github.com/tuanngocptn/nport/issues)
-- 🌍 [Add translations](https://github.com/tuanngocptn/nport/blob/main/src/lang.js)
+- 🌍 [Add translations](docs/CONTRIBUTING.md#adding-translations)
 
 ## 📄 License
 
@@ -406,8 +427,12 @@ If you find NPort useful, please consider supporting the project:
 ## 🙏 Credits
 
 - Created by [Nick Pham](https://github.com/tuanngocptn) from Vietnam
-- Powered by [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
 - Inspired by [ngrok](https://ngrok.com) and [localtunnel](https://github.com/localtunnel/localtunnel)
+- Powered by [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
+
+   <a href="https://www.cloudflare.com" target="_blank">
+      <img src="https://nport.link/assets/webp/cloudflare-logo-black.webp" alt="Cloudflare" height="60">
+   </a>
 
 ## 🔗 Links
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "nport",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "Free & open source ngrok alternative - Tunnel HTTP/HTTPS connections via Cloudflare Edge with custom subdomains",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.js",
   "bin": {
-    "nport": "index.js"
+    "nport": "dist/index.js"
   },
   "engines": {
-    "node": ">=18.0.0",
-    "npm": ">=8.0.0"
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
   },
   "keywords": [
     "ngrok",
@@ -63,17 +63,28 @@
     }
   ],
   "scripts": {
-    "postinstall": "node src/bin-manager.js",
-    "start": "node index.js"
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
   },
   "dependencies": {
     "axios": "^1.13.2",
     "chalk": "^5.6.2",
     "ora": "^9.0.0"
   },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "~3.2.0"
+  },
   "files": [
-    "index.js",
-    "src/",
+    "dist/",
+    "bin/",
+    "scripts/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/scripts/postinstall.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script
+ * 
+ * Runs bin-manager to download cloudflared binary if dist/ exists.
+ * Silently skips if dist/ doesn't exist (e.g., during development before build).
+ */
+
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const binManagerPath = join(__dirname, '..', 'dist', 'bin-manager.js');
+
+if (existsSync(binManagerPath)) {
+  // Dynamic import to run the bin-manager
+  import(binManagerPath).catch(() => {
+    // Silently fail if import fails
+  });
+} else {
+  // For development: dist/ doesn't exist yet, skip silently
+  console.log('ℹ️  Skipping binary download (run "npm run build" first for development)');
+}

package/index.js

@@ -1,110 +0,0 @@
-#!/usr/bin/env node
-
-import ora from "ora";
-import chalk from "chalk";
-import { ArgumentParser } from "./src/args.js";
-import { TunnelOrchestrator } from "./src/tunnel.js";
-import { VersionManager } from "./src/version.js";
-import { UI } from "./src/ui.js";
-import { CONFIG } from "./src/config.js";
-import { lang } from "./src/lang.js";
-import { configManager } from "./src/config-manager.js";
-
-/**
- * NPort - Free & Open Source ngrok Alternative
- * 
- * Main entry point for the NPort CLI application.
- * Handles command-line arguments and orchestrates tunnel creation.
- */
-
-/**
- * Display version information with update check
- */
-async function displayVersion() {
-  const spinner = ora(lang.t("checkingUpdates")).start();
-  const updateInfo = await VersionManager.checkForUpdates();
-  spinner.stop();
-  
-  UI.displayVersion(CONFIG.CURRENT_VERSION, updateInfo);
-}
-
-/**
- * Handle --set-backend command
- */
-function handleSetBackend(value) {
-  if (value === 'clear') {
-    // Clear saved backend URL
-    configManager.setBackendUrl(null);
-    console.log(chalk.green('✔ Backend URL cleared. Using default backend.'));
-    console.log(chalk.gray('  Default: https://api.nport.link\n'));
-  } else {
-    // Save new backend URL
-    configManager.setBackendUrl(value);
-    console.log(chalk.green('✔ Backend URL saved successfully!'));
-    console.log(chalk.cyan(`  Backend: ${value}`));
-    console.log(chalk.gray('\n  This backend will be used for all future sessions.'));
-    console.log(chalk.gray('  To clear: nport --set-backend\n'));
-  }
-  
-  // Show current configuration
-  const savedUrl = configManager.getBackendUrl();
-  if (savedUrl) {
-    console.log(chalk.white('Current configuration:'));
-    console.log(chalk.cyan(`  Saved backend: ${savedUrl}`));
-  }
-}
-
-/**
- * Main application entry point
- */
-async function main() {
-  try {
-    const args = process.argv.slice(2);
-    
-    // Parse arguments
-    const config = ArgumentParser.parse(args);
-    
-    // Initialize language first (may prompt user)
-    await lang.initialize(config.language);
-    
-    // Check for version flag (after language is set)
-    if (args.includes('-v') || args.includes('--version')) {
-      await displayVersion();
-      process.exit(0);
-    }
-    
-    // Handle --set-backend command
-    if (config.setBackend) {
-      handleSetBackend(config.setBackend);
-      process.exit(0);
-    }
-    
-    // If only --language flag was used, show success message and exit
-    if (config.language === 'prompt' && 
-        (args.includes('--language') || args.includes('--lang') || args.includes('-l'))) {
-      // Language was already selected in initialize(), just exit
-      process.exit(0);
-    }
-    
-    // Load saved backend URL if no CLI backend specified
-    if (!config.backendUrl) {
-      const savedBackend = configManager.getBackendUrl();
-      if (savedBackend) {
-        config.backendUrl = savedBackend;
-      }
-    }
-    
-    // Start tunnel
-    await TunnelOrchestrator.start(config);
-  } catch (error) {
-    console.error(`Fatal Error: ${error.message}`);
-    process.exit(1);
-  }
-}
-
-// Register cleanup handlers for graceful shutdown
-process.on("SIGINT", () => TunnelOrchestrator.cleanup());
-process.on("SIGTERM", () => TunnelOrchestrator.cleanup());
-
-// Start application
-main();