@lionad/port-key 0.1.5 → 0.2.0

package/README.md

@@ -8,6 +8,11 @@
   <strong>PortKey：A Simple, Practical Port Naming Strategy</strong>
 </p>
 
+<p align="center">
+  <!-- LANGUAGES=("cn" "es" "fr" "de" "ja" "ko" "ru" "ar" "pt" "it") -->
+  <a href="./docs/README.cn.md">中文</a> | <a href="./docs/README.es.md">Español</a> | <a href="./docs/README.fr.md">Français</a> | <a href="./docs/README.de.md">Deutsch</a> | <a href="./docs/README.ja.md">日本語</a> | <a href="./docs/README.ko.md">한국어</a> | <a href="./docs/README.ru.md">Русский</a> | <a href="./docs/README.ar.md">العربية</a> | <a href="./docs/README.pt.md">Português</a> | <a href="./docs/README.it.md">Italiano</a>
+</p>
+
 ## Brief
 
 Generate ports with a letter-to-number keyboard mapping
@@ -25,7 +30,7 @@ For example, I have more than ten Nuxt apps on my machine. If they all default t
 
 Instead of picking random numbers, map the **project name to numbers based on the keyboard**, so the port is *readable* and *memorable*.
 
-As long as the result is within the valid port range (**0–65535**) and doesn’t hit reserved/system ports, you can just use it.
+As long as the result is within the valid port range (**1024–65535**) and doesn’t hit reserved/system ports, you can just use it.
 
 More specifically: using a standard QWERTY keyboard, map each letter to a single digit based on its **row/column position**.
 
@@ -53,18 +58,39 @@ If a project needs multiple ports (frontend, backend, database, etc.), pick **on
 
 ### Valid port range
 
-- Ports must be within **0–65535**.
-- For custom services, it’s usually best to use **1024–49151** (non-reserved) or **49152–65535** (private/dynamic).
-- As long as the mapped number stays under the limit, it’s valid.
+- Ports must be within **1024–65535** (System ports 0-1023 are blocked).
+- **System Ports (0-1023)**: Assigned by IETF. Strictly blocked.
+- **User Ports (1024-49151)**: Assigned by IANA. Use with caution as they might conflict with registered services.
+- **Dynamic/Private Ports (49152-65535)**: Not assigned. Safest for private or dynamic use.
 
 ---
 
 ## How to use
 
+Simple command:
+
+```sh
+npx -y @lionad/port-key <your-project-name>
+```
+
+Or you want a stdio MCP server:
+
+```sh
+npx -y @lionad/port-key-mcp
 ```
-npx @lionad/port-key <your-project-name>
+
+```json
+{
+  "mcpServers": {
+    "port-key": {
+      "command": "npx",
+      "args": ["@lionad/port-key-mcp"]
+    }
+  }
+}
 ```
 
+
 ### CLI options
 
 - `-m, --map <object>`: custom mapping (JSON or JS-like object literal)

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@lionad/port-key",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "A simple, practical port naming strategy",
   "type": "module",
+  "types": "./src/port-key.d.ts",
   "exports": {
-    ".": "./src/port-key.js"
+    ".": {
+      "types": "./src/port-key.d.ts",
+      "default": "./src/port-key.js"
+    }
   },
   "keywords": [
     "portkey",
@@ -26,10 +30,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "author": "Lionad",
   "license": "ISC",
   "repository": {
@@ -49,5 +49,10 @@
   "dependencies": {},
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "echo 'skip build steps in packages/core'",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}

package/src/port-key.d.ts

@@ -0,0 +1,43 @@
+export type DigitKey = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+export type DigitLetterMap = Record<DigitKey | `${DigitKey}`, string>;
+
+export type RejectedCandidate = {
+  candidate: string;
+  reason: string;
+};
+
+export type PickPortOptions = {
+  preferDigitCount?: number;
+  minPort?: number;
+  maxPort?: number;
+  blockedPorts?: ReadonlySet<number> | number[];
+};
+
+export const DEFAULT_MAP: Readonly<DigitLetterMap>;
+export const DEFAULT_BLOCKED_PORTS: ReadonlySet<number>;
+
+export function buildReverseMap(map: DigitLetterMap): Map<string, string>;
+export function normalizeInput(text: unknown): string;
+export function mapToDigits(text: unknown, map?: DigitLetterMap): string;
+export function isValidPort(port: unknown): port is number;
+
+export function pickPortFromDigits(
+  digits: unknown,
+  options?: PickPortOptions
+):
+  | { port: number; rejectedCandidates?: RejectedCandidate[] }
+  | { port: null; reason: string; rejectedCandidates?: RejectedCandidate[] };
+
+export function mapToPort(
+  text: unknown,
+  map?: DigitLetterMap,
+  options?: PickPortOptions
+): {
+  digits: string;
+  port: number | null;
+  rejectedCandidates?: RejectedCandidate[];
+  reason?: string;
+};
+
+export function parseUserMap(mapString: unknown): DigitLetterMap;

package/src/port-key.js

@@ -14,30 +14,8 @@ const DEFAULT_MAP = Object.freeze({
 });
 
 const DEFAULT_BLOCKED_PORTS = Object.freeze(
+  // well-known application ports
   new Set([
-    0,
-    20,
-    21,
-    22,
-    23,
-    25,
-    53,
-    67,
-    68,
-    80,
-    110,
-    123,
-    143,
-    161,
-    162,
-    389,
-    443,
-    445,
-    465,
-    587,
-    636,
-    993,
-    995,
     3000,
     3001,
     5000,
@@ -105,6 +83,8 @@ function isValidPort(port) {
 }
 
 function isPortBlocked(port, blockedPorts) {
+  // System Ports (0-1023) are assigned by IETF and should not be used.
+  if (port < 1024) return true;
   if (blockedPorts && typeof blockedPorts.has === 'function') {
     return blockedPorts.has(port);
   }
@@ -219,6 +199,7 @@ export {
   normalizeInput,
   mapToDigits,
   isValidPort,
+  isPortBlocked,
   pickPortFromDigits,
   mapToPort,
   parseUserMap,