@lionad/port-key 0.1.6 → 0.3.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,23 +58,45 @@ 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)
 - `--lang <code>`: output language (currently only `en` and `cn`, default: `cn`)
 - `-d, --digits <count>`: preferred digit count for port (4 or 5, default: 4)
+- `--padding-zero <true|false>`: Pad short ports with zero (default: true). e.g. "air" -> 1840
 - `-h, --help`: show help
 
 Examples:
@@ -96,6 +123,8 @@ A full Example:
 {
   // Preferred digit count for port (4 or 5)
   "preferDigitCount": 5,
+  // Pad short ports with zero (default: true)
+  "paddingZero": true,
   // Custom letter-to-digit mapping
   "blockedPorts": [3000, 3001, 3002, 6666],
   // Port range limits (inclusive)

package/locales/cn.json

@@ -7,6 +7,7 @@
   "optMap": "  -m, --map <对象>    自定义映射（JSON 或 JS 对象字面量）",
   "optLang": "      --lang <代码>   输出语言（en 或 cn）",
   "optDigits": "  -d, --digits <位数> 端口优先位数（4 或 5，默认：4）",
+  "optPadding": "      --padding-zero <true|false>  是否为短端口号补零（默认：true）",
   "optHelp": "  -h, --help           显示帮助",
   "examples": "示例：",
   "ex1": "  npx @lionad/port-key cfetch           # -> 34353",

package/locales/en.json

@@ -7,6 +7,7 @@
   "optMap": "  -m, --map <object>   Custom mapping (JSON or JS-like object literal)",
   "optLang": "      --lang <code>    Output language (en or cn)",
   "optDigits": "  -d, --digits <count> Preferred digit count for port (4 or 5, default: 4)",
+  "optPadding": "      --padding-zero <true|false>  Pad short ports with zero (default: true)",
   "optHelp": "  -h, --help           Show help",
   "examples": "Examples:",
   "ex1": "  npx @lionad/port-key cfetch           # -> 34353",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionad/port-key",
-  "version": "0.1.6",
+  "version": "0.3.0",
   "description": "A simple, practical port naming strategy",
   "type": "module",
   "types": "./src/port-key.d.ts",
@@ -30,10 +30,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "author": "Lionad",
   "license": "ISC",
   "repository": {
@@ -53,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/cli.js

@@ -18,6 +18,7 @@ function formatHelp(lang = 'cn') {
     t.optMap,
     t.optLang,
     t.optDigits,
+    t.optPadding,
     t.optHelp,
     '',
     t.examples,
@@ -35,6 +36,7 @@ function parseArgv(argv) {
   let showHelp = false;
   let lang;
   let preferDigitCount;
+  let paddingZero;
   const positionals = [];
 
   let i = 0;
@@ -78,6 +80,25 @@ function parseArgv(argv) {
       continue;
     }
 
+    if (token === '--padding-zero') {
+      const value = args[i + 1];
+      if (value === 'false') {
+        paddingZero = false;
+        i += 2;
+      } else if (value === 'true') {
+        paddingZero = true;
+        i += 2;
+      } else if (!value || value.startsWith('-')) {
+         // Treated as boolean flag (true) if no value provided
+         paddingZero = true;
+         i += 1;
+      } else {
+         // Fallback for unexpected values
+         throw new Error('Invalid value for --padding-zero. Use true or false.');
+      }
+      continue;
+    }
+
     positionals.push(token);
     i += 1;
   }
@@ -87,6 +108,7 @@ function parseArgv(argv) {
     lang,
     showHelp,
     preferDigitCount,
+    paddingZero,
     input: positionals.join(' '),
   };
 }
@@ -125,6 +147,7 @@ function runCli(argv, stdout = process.stdout, stderr = process.stderr, deps = {
     map: parsed.map !== DEFAULT_MAP ? parsed.map : undefined,
     lang: parsed.lang,
     preferDigitCount: parsed.preferDigitCount,
+    paddingZero: parsed.paddingZero,
   });
 
   const lang = getLangOrDefault(effective.lang);
@@ -151,6 +174,7 @@ function runCli(argv, stdout = process.stdout, stderr = process.stderr, deps = {
     maxPort: effective.maxPort,
     preferredRanges: effective.preferredRanges,
     preferDigitCount: effective.preferDigitCount,
+    paddingZero: effective.paddingZero,
   });
 
   if (result.port === null) {

package/src/config.js

@@ -54,6 +54,7 @@ function mergeConfig(base, override) {
     maxPort: b.maxPort ?? a.maxPort,
     preferredRanges: b.preferredRanges ?? a.preferredRanges,
     preferDigitCount: b.preferDigitCount ?? a.preferDigitCount,
+    paddingZero: b.paddingZero ?? a.paddingZero,
     lang: b.lang ?? a.lang,
   };
 }

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);
   }
@@ -117,19 +97,45 @@ function isPortBlocked(port, blockedPorts) {
 function pickPortFromDigits(digits, options = {}) {
   const raw = String(digits || '').replace(/[^0-9]/g, '');
   if (!raw) return { port: null, reason: 'No digits found in input' };
-  if (raw.length < 2) return { port: null, reason: 'Not enough digits to form a candidate' };
+  
+  const paddingZero = options.paddingZero !== false; // Default true
+  
+  // If not padding, enforce strict length check
+  // If padding, allow short length as it will be padded
+  if (!paddingZero && raw.length < 2) return { port: null, reason: 'Not enough digits to form a candidate' };
 
   const minPort = Number.isFinite(options.minPort) ? options.minPort : 0;
   const maxPort = Number.isFinite(options.maxPort) ? options.maxPort : 65535;
   const blockedPorts = options.blockedPorts || DEFAULT_BLOCKED_PORTS;
   const preferDigitCount = options.preferDigitCount || 4;
+  // paddingZero is already defined above
 
   const candidates = [];
   const normalized = raw.replace(/^0+/, '');
+  
+  // Padding Logic for short inputs like "air" (184)
+  // If normalized length is small, we can pad it with zeros to match preferDigitCount or more
+  const paddedCandidates = [];
+  if (paddingZero && normalized.length > 0 && normalized.length < preferDigitCount) {
+    let current = normalized;
+    // Fix: start padding loop immediately
+    while (current.length <= 5) {
+       // Only push if length >= 2 (valid port min length logic) and >= preferDigitCount (if we want to respect preference)
+       // Actually, the original requirement says "pad ... to match preferDigitCount or more".
+       if (current.length >= preferDigitCount) {
+         paddedCandidates.push(current);
+       }
+       current += '0';
+    }
+  }
+
   if (preferDigitCount && normalized.length >= preferDigitCount) {
     candidates.push(normalized.slice(0, preferDigitCount));
     candidates.push(normalized.slice(normalized.length - preferDigitCount));
   } else {
+    // If not padding, try smaller lengths (if >= 2)
+    // Note: if paddedCandidates is empty, we must rely on this.
+    // But if we have paddedCandidates, we can still add these as fallbacks.
     for (let len = Math.min(normalized.length, preferDigitCount); len >= 2; len -= 1) {
       candidates.push(normalized.slice(0, len));
     }
@@ -137,6 +143,9 @@ function pickPortFromDigits(digits, options = {}) {
       candidates.push(normalized.slice(normalized.length - len));
     }
   }
+  
+  // Merge padded candidates
+  candidates.push(...paddedCandidates);
 
   const unique = Array.from(new Set(candidates));
   const rejectedCandidates = [];
@@ -219,6 +228,7 @@ export {
   normalizeInput,
   mapToDigits,
   isValidPort,
+  isPortBlocked,
   pickPortFromDigits,
   mapToPort,
   parseUserMap,