@lionad/port-key 0.1.2 → 0.1.4

package/LICENSE

@@ -5,4 +5,3 @@ Copyright (c) 2026 Lionad
 Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
 
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-

package/locales/cn.json

@@ -18,5 +18,8 @@
   "invalidDigits": "无效的位数。必须为 4 或 5。",
   "missingLang": "缺少 --lang 的值",
   "invalidLang": "不支持的语言。仅支持 \"en\" 或 \"cn\"。",
-  "noValidPort": "无法从输入生成有效端口。"
+  "noValidPort": "无法从输入生成有效端口。",
+  "configReadFailed": "[info] 配置文件 {path} 似乎无法读取或不是有效的 JSON 格式。将使用默认配置。",
+  "firstRunNoConfig": "[info] 欢迎使用 PortKey！\n\n你可以在 {configDir} 目录下创建 config.json 文件来自定义配置。\n\n配置示例请参考：\n{readmeUrl}",
+  "readmeConfigExampleLink": "https://github.com/Lionad-Morotar/port-key#config"
 }

package/locales/en.json

@@ -18,5 +18,8 @@
   "invalidDigits": "Invalid digit count. Must be 4 or 5.",
   "missingLang": "Missing value for --lang",
   "invalidLang": "Unsupported language. Only \"en\" or \"cn\" are available.",
-  "noValidPort": "No valid port could be generated from input."
+  "noValidPort": "No valid port could be generated from input.",
+  "configReadFailed": "[info] It seems the config file at {path} could not be read or is not valid JSON. Using default config.",
+  "firstRunNoConfig": "[info] Welcome to PortKey!\n\nYou can create a config.json file in {configDir} to customize your settings.\n\nFor config examples, see:\n{readmeUrl}",
+  "readmeConfigExampleLink": "https://github.com/Lionad-Morotar/port-key#config"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionad/port-key",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A simple, practical port naming strategy",
   "type": "module",
   "exports": {
@@ -46,5 +46,8 @@
   "devDependencies": {
     "vitest": "4.0.16"
   },
-  "dependencies": {}
+  "dependencies": {},
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
 }

package/src/cli.js

@@ -1,7 +1,7 @@
 'use strict';
 
 import { DEFAULT_MAP, mapToPort, parseUserMap } from './port-key.js';
-import { loadUserConfigSync, mergeConfig } from './config.js';
+import { loadUserConfigSync, mergeConfig, getPortKeyDirPath, loadRunCount, incrementRunCount } from './config.js';
 import { getLangOrDefault, loadMessages } from './i18n.js';
 
 function formatHelp(lang = 'cn') {
@@ -78,7 +78,6 @@ function parseArgv(argv) {
       continue;
     }
 
-    // Unknown option: treat as positional (so "portkey -foo" still works when user passes "--")
     positionals.push(token);
     i += 1;
   }
@@ -93,7 +92,24 @@ function parseArgv(argv) {
 }
 
 function runCli(argv, stdout = process.stdout, stderr = process.stderr, deps = {}) {
-  const { config } = loadUserConfigSync(deps);
+  const { config, configReadError, path: configPath, configExists } = loadUserConfigSync(deps);
+  const { isFirstRun } = loadRunCount(deps);
+
+  if (configReadError && configPath) {
+    const lang = getLangOrDefault((config && config.lang) || 'cn');
+    const MSG = loadMessages(lang);
+    stderr.write(MSG.configReadFailed.replace('{path}', configPath) + '\n');
+  }
+
+  if (isFirstRun && !configExists) {
+    const lang = getLangOrDefault((config && config.lang) || 'cn');
+    const MSG = loadMessages(lang);
+    const portKeyDir = getPortKeyDirPath(deps);
+    stderr.write(MSG.firstRunNoConfig.replace('{configDir}', portKeyDir || '~/.port-key').replace('{readmeUrl}', MSG.readmeConfigExampleLink) + '\n');
+  }
+
+  incrementRunCount(deps);
+
   let parsed;
   try {
     parsed = parseArgv(argv);

package/src/config.js

@@ -11,7 +11,6 @@ function getConfigPath(pathModule, osModule, env) {
   const newPath = pathToUse.join(home, '.port-key', 'config.json');
   const oldPath = pathToUse.join(home, '.portkey', 'config.json');
   try {
-    // Prefer new path if exists; otherwise fall back to old path
     if (fs.existsSync(newPath)) return newPath;
     return oldPath;
   } catch {
@@ -26,20 +25,19 @@ function loadUserConfigSync(deps = {}) {
   const env = deps.env || process.env;
 
   const configPath = getConfigPath(pathModule, osModule, env);
-  if (!configPath) return { path: null, config: {} };
+  if (!configPath) return { path: null, config: {}, configReadError: false, configExists: false };
 
   try {
-    if (!fsModule.existsSync(configPath)) return { path: configPath, config: {} };
+    if (!fsModule.existsSync(configPath)) return { path: configPath, config: {}, configReadError: false, configExists: false };
     const raw = fsModule.readFileSync(configPath, 'utf8');
-    if (!String(raw || '').trim()) return { path: configPath, config: {} };
+    if (!String(raw || '').trim()) return { path: configPath, config: {}, configReadError: false, configExists: true };
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      return { path: configPath, config: {} };
+      return { path: configPath, config: {}, configReadError: true, configExists: true };
     }
-    return { path: configPath, config: parsed };
+    return { path: configPath, config: parsed, configReadError: false, configExists: true };
   } catch {
-    // Ignore config errors; CLI should still work.
-    return { path: configPath, config: {} };
+    return { path: configPath, config: {}, configReadError: true, configExists: true };
   }
 }
 
@@ -60,8 +58,75 @@ function mergeConfig(base, override) {
   };
 }
 
+function getPortKeyDirPath(deps = {}) {
+  const osModule = deps.os || os;
+  const pathModule = deps.path || path;
+  const env = deps.env || process.env;
+
+  const home = (env && (env.PORTKEY_HOME || env.HOME)) || (osModule && osModule.homedir && osModule.homedir());
+  if (!home) return null;
+
+  const pathToUse = pathModule || path;
+  return pathToUse.join(home, '.port-key');
+}
+
+function getLogPath(deps = {}) {
+  const portKeyDir = getPortKeyDirPath(deps);
+  if (!portKeyDir) return null;
+  const pathModule = deps.path || path;
+  return pathModule.join(portKeyDir, 'log.json');
+}
+
+function loadRunCount(deps = {}) {
+  const fsModule = deps.fs || fs;
+  const logPath = getLogPath(deps);
+  if (!logPath) return { count: 0, isFirstRun: true, logPath: null };
+
+  try {
+    if (!fsModule.existsSync(logPath)) {
+      return { count: 0, isFirstRun: true, logPath };
+    }
+    const raw = fsModule.readFileSync(logPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const count = typeof parsed?.count === 'number' ? parsed.count : 0;
+    return { count, isFirstRun: count === 0, logPath };
+  } catch {
+    return { count: 0, isFirstRun: true, logPath };
+  }
+}
+
+function incrementRunCount(deps = {}) {
+  const fsModule = deps.fs || fs;
+  const pathModule = deps.path || path;
+  const logPath = getLogPath(deps);
+  const portKeyDir = getPortKeyDirPath(deps);
+
+  if (!logPath || !portKeyDir) return;
+
+  try {
+    if (!fsModule.existsSync(portKeyDir)) {
+      fsModule.mkdirSync(portKeyDir, { recursive: true });
+    }
+
+    let count = 0;
+    if (fsModule.existsSync(logPath)) {
+      const raw = fsModule.readFileSync(logPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      count = typeof parsed?.count === 'number' ? parsed.count : 0;
+    }
+
+    count += 1;
+    fsModule.writeFileSync(logPath, JSON.stringify({ count }, null, 2), 'utf8');
+  } catch {
+  }
+}
+
 export {
   getConfigPath,
   loadUserConfigSync,
   mergeConfig,
+  getPortKeyDirPath,
+  getLogPath,
+  loadRunCount,
+  incrementRunCount,
 };

package/src/port-key.js

@@ -16,7 +16,6 @@ const DEFAULT_MAP = Object.freeze({
 const DEFAULT_BLOCKED_PORTS = Object.freeze(
   new Set([
     0,
-    // common/system-ish
     20,
     21,
     22,
@@ -39,7 +38,6 @@ const DEFAULT_BLOCKED_PORTS = Object.freeze(
     636,
     993,
     995,
-    // very common dev defaults
     3000,
     3001,
     5000,
@@ -51,7 +49,6 @@ const DEFAULT_BLOCKED_PORTS = Object.freeze(
     9000,
     27017,
     3306,
-    // common dev port
     1234,
   ])
 );
@@ -125,16 +122,14 @@ function pickPortFromDigits(digits, options = {}) {
   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; // default to 4
+  const preferDigitCount = options.preferDigitCount || 4;
 
-  // Prefer exact digit count using normalized prefix first, then normalized suffix
   const candidates = [];
   const normalized = raw.replace(/^0+/, '');
   if (preferDigitCount && normalized.length >= preferDigitCount) {
     candidates.push(normalized.slice(0, preferDigitCount));
     candidates.push(normalized.slice(normalized.length - preferDigitCount));
   } else {
-    // Fallback only when digits are fewer than preferDigitCount
     for (let len = Math.min(normalized.length, preferDigitCount); len >= 2; len -= 1) {
       candidates.push(normalized.slice(0, len));
     }
@@ -180,7 +175,6 @@ function parseUserMap(mapString) {
   const raw = String(mapString || '').trim();
   if (!raw) throw new Error('Empty map string');
 
-  // 1) Strict JSON: {"1":"qaz",...}
   try {
     const maybe = JSON.parse(raw);
     if (!isPlainObject(maybe)) throw new Error('Map must be an object');
@@ -200,11 +194,8 @@ function parseUserMap(mapString) {
     if (err.message === 'Keys must be digits, values must be mapped letters') {
       throw err;
     }
-    // fall through
   }
 
-  // 2) JS-ish object literal: { 1: 'qaz', 0: 'p' }
-  // Extract digit keys and quoted string values.
   const extracted = {};
   const re = /([0-9])\s*:\s*(['"])(.*?)\2/g;
   let match;

package/README.md

@@ -1,91 +0,0 @@
-# PortKey
-
-<p align="center">
-  <img width="200" src="/public/logo.png" />
-</p>
-
-<p align="center">
-  <strong>PortKey：A Simple, Practical Port Naming Strategy</strong>
-</p>
-
-## Brief
-
-Generate ports with a letter-to-number keyboard mapping
-
-When you’re running a bunch of projects locally, picking port numbers becomes annoying.
-
-- Over the last couple of years, there have been *so many* new projects. To really try them out, you often need to boot them locally—and then ports start colliding.
-- If you want to keep browser tabs (or bookmarks) stable, a project’s port shouldn’t keep changing.
-
-For example, I have more than ten Nuxt apps on my machine. If they all default to `3000`, that’s obviously not going to work. So I came up with a simple, consistent port naming rule to “assign” ports per project.
-
-[Source Blog Post](https://lionad.art/articles/simple-naming-method)
-
-### Core idea
-
-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.
-
-More specifically: using a standard QWERTY keyboard, map each letter to a single digit based on its **row/column position**.
-
-Example:
-
-`"cfetch"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（port number）
-
-Then you can take the first 4 digits (e.g. `3453`), or keep more digits (e.g. `34353`). Either is fine.
-
-If a project needs multiple ports (frontend, backend, database, etc.), pick **one** of these two approaches:
-
-1. Use the project prefix, then append a “role suffix”  
-   - For `"cfetch"`, take `3435` as the base  
-   - Frontend (`fe`, i.e. `43`) → `34354`  
-   - Backend (`server`) → `34352`  
-   - Database (`mongo`) → `34357`  
-   - …and so on
-
-2. Use the project prefix, then assign sequential roles  
-   - For `"cfetch"`, take `3435` as the base  
-   - Web → `34351`  
-   - Backend → `34352`  
-   - Database → `34353`  
-   - …and so 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.
-
----
-
-## How to use
-
-```
-npx @lionad/port-key <your-project-name>
-```
-
-### 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)
-- `-h, --help`: show help
-
-Examples:
-
-```bash
-npx @lionad/port-key cfetch # -> 3435
-npx @lionad/port-key cfetch --digits 4  # -> 3435 (4-digit port)
-npx @lionad/port-key cfetch --digits 5  # -> 34353 (5-digit port)
-```
-
-Notes:
-- Default log language is `cn`. Use `--lang en` to show English messages.
-- Use `-h` or `--help` to show help.
-
-### Config
-
-PortKey reads optional user config from:
-
-- `~/.port-key/config.json`