@kevlns/v-cli 0.1.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kevlns <936277610@qq.com>
+
+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

@@ -0,0 +1,156 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/kevlns/v-cli/main/logo.png" alt="v-cli logo" width="320" />
+
+# v-cli
+
+**kevlns 的个人工具箱 CLI：插件化架构，内置命令随版本发布，本地插件放目录即生效。**
+
+[![npm version](https://img.shields.io/npm/v/%40kevlns%2Fv-cli?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@kevlns/v-cli)
+[![npm downloads](https://img.shields.io/npm/dm/%40kevlns%2Fv-cli?style=flat-square&color=4c8bf5)](https://www.npmjs.com/package/@kevlns/v-cli)
+[![CI](https://img.shields.io/github/actions/workflow/status/kevlns/v-cli/test.yml?branch=main&style=flat-square&label=CI)](https://github.com/kevlns/v-cli/actions/workflows/test.yml)
+[![license](https://img.shields.io/github/license/kevlns/v-cli?style=flat-square&color=2e8b57)](./LICENSE)
+
+[Getting started](#getting-started) · [API](#api) · [Examples](#examples) · [Package family](#package-family)
+
+</div>
+
+---
+
+## Why v-cli?
+
+v-cli 让你**用一个命令沉淀所有个人小工具**，而不用为每个工具建仓库、发包、记命令。
+它被设计为**依赖极少、秒级启动、写个文件就能扩展**，与 kevlns 工具家族的其余部分可自由组合。
+
+- **插件化架构** - 内置命令走注册表随版本发布；本地插件放进 `~/.v-cli/commands/` 立即生效，无需发版
+- **容错加载** - 单个插件语法错误或形状不符只会被跳过并报告，绝不阻断其他命令
+- **双通道输出** - 结果走 stdout（可管道、可脚本化），诊断走 stderr；全局 `--json` 任意位置生效
+- **TypeScript-first** - 严格类型编写，tsup 将核心逻辑打包为单文件 ESM，仅保留 `commander` 运行依赖
+
+## Getting started
+
+### Install
+
+```bash
+# beta 阶段请显式安装预发布版本
+npm install -g @kevlns/v-cli@beta
+
+# 或直接从 GitHub 仓库安装开发版本
+npm install -g git+https://github.com/kevlns/v-cli.git
+```
+
+发布稳定版并设置 `latest` 标签后，可直接使用 `npm install -g @kevlns/v-cli`。
+
+### Quick start
+
+```bash
+v-cli doctor          # 环境体检：node/版本、主目录、配置、插件状态
+v-cli plugin list     # 列出内置命令与本地插件
+v-cli ts 1710000000   # 时间戳互转
+```
+
+> [!TIP]
+> 所有命令都支持 `--json`（任意位置）：`v-cli doctor --json` 输出机器可读结果，方便脚本消费。
+
+## Examples
+
+### 写一个本地插件
+
+```js
+// ~/.v-cli/commands/hello.mjs
+export default {
+  name: "hello",
+  description: "示例插件",
+  register(program, ctx) {
+    program.action(() => ctx.log.result("hello world"));
+  },
+};
+```
+
+保存后立即生效：
+
+```bash
+v-cli hello           # hello world
+v-cli plugin list     # [local] hello 已出现
+```
+
+### 在脚本中消费输出
+
+```bash
+v-cli ts 1710000000 --json | jq .seconds
+```
+
+## API
+
+### 内置命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `v-cli doctor` | 环境体检：node/v-cli 版本、主目录、config 可写性、本地插件与加载错误 |
+| `v-cli plugin list` | 列出全部命令（标注 builtin/local 来源） |
+| `v-cli plugin path` | 打印本地插件目录 |
+| `v-cli ts [value]` | 无参=当前时间；数字（秒/毫秒自动识别）=转可读时间；日期串=转时间戳 |
+
+### 插件契约 `CliCommand`
+
+```ts
+interface CliCommand {
+  name: string;                                    // 子命令名
+  description: string;
+  hidden?: boolean;
+  register(program: Command, ctx: CliContext): void;
+}
+
+interface CliContext {
+  log: Logger;        // result() 走 stdout，info/warn/error 走 stderr
+  config: ConfigStore; // <home>/config.json 惰性读写
+  json: boolean;      // 全局 --json 开关，命令必须尊重
+  homeDir: string;    // 主目录（默认 ~/.v-cli）
+}
+```
+
+#### 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `V_CLI_HOME` | `~/.v-cli` | 覆盖主目录（配置、本地插件都从这里找） |
+
+## Package family
+
+kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）。
+
+| Package | Purpose | Status |
+| --- | --- | --- |
+| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.1.1-beta.1 |
+| [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.1-beta.1 |
+
+## Compatibility
+
+| Runtime | Supported versions |
+| --- | --- |
+| Node.js | `18` and later |
+| TypeScript | `5.6` and later（仅开发时） |
+
+CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时仅依赖 `commander`。
+
+## Contributing
+
+```bash
+git clone https://github.com/kevlns/v-cli.git
+cd v-cli
+npm install
+npm run build && npm test
+```
+
+For bugs and feature requests, use
+[GitHub Issues](https://github.com/kevlns/v-cli/issues).
+
+## License
+
+Released under the [MIT License](./LICENSE).
+
+<div align="center">
+
+Part of the **kevlns** tool family.
+
+</div>

package/dist/cli.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command, CommanderError } from "commander";
+
+// src/core/context.ts
+import os from "os";
+import path2 from "path";
+
+// src/core/config.ts
+import fs from "fs";
+import path from "path";
+var ConfigStore = class _ConfigStore {
+  constructor(file) {
+    this.file = file;
+  }
+  static fromHome(homeDir) {
+    return new _ConfigStore(path.join(homeDir, "config.json"));
+  }
+  get() {
+    try {
+      return JSON.parse(fs.readFileSync(this.file, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+  set(updater) {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    const cfg = updater(this.get());
+    fs.writeFileSync(this.file, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    return cfg;
+  }
+};
+
+// src/core/logger.ts
+var Logger = class {
+  constructor(jsonMode = false) {
+    this.jsonMode = jsonMode;
+  }
+  /** 命令结果输出：--json 时输出结构化 JSON，否则原样输出 */
+  result(data) {
+    if (this.jsonMode) {
+      process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    } else if (typeof data === "string") {
+      process.stdout.write(data + "\n");
+    } else {
+      process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    }
+  }
+  info(msg) {
+    process.stderr.write(`[v-cli] ${msg}
+`);
+  }
+  warn(msg) {
+    process.stderr.write(`[v-cli] \u8B66\u544A: ${msg}
+`);
+  }
+  error(msg) {
+    process.stderr.write(`[v-cli] \u9519\u8BEF: ${msg}
+`);
+  }
+};
+
+// src/core/context.ts
+function createContext(homeDir, json) {
+  return {
+    log: new Logger(json),
+    config: ConfigStore.fromHome(homeDir),
+    json,
+    homeDir
+  };
+}
+function defaultHomeDir() {
+  return process.env.V_CLI_HOME || path2.join(os.homedir(), ".v-cli");
+}
+
+// src/core/loader.ts
+import fs3 from "fs";
+import path4 from "path";
+import { pathToFileURL } from "url";
+
+// src/core/command.ts
+function isCliCommand(candidate) {
+  if (typeof candidate !== "object" || candidate === null) return false;
+  const cmd = candidate;
+  return typeof cmd.name === "string" && typeof cmd.description === "string" && typeof cmd.register === "function";
+}
+
+// src/commands/doctor.ts
+import fs2 from "fs";
+
+// src/version.ts
+var VERSION = "0.1.1-beta.1";
+
+// src/commands/doctor.ts
+var doctor = {
+  name: "doctor",
+  description: "\u4F53\u68C0\uFF1Anode/v-cli \u7248\u672C\u3001homeDir\u3001config\u3001\u63D2\u4EF6\u72B6\u6001",
+  register(program, ctx) {
+    program.action(async () => {
+      const homeDir = ctx.homeDir;
+      const exists = fs2.existsSync(homeDir);
+      let configWritable = false;
+      try {
+        ctx.config.set((cfg) => cfg);
+        configWritable = true;
+      } catch {
+        configWritable = false;
+      }
+      const plugins = await loadLocalPlugins(ctx);
+      const list = plugins.map((p) => ({
+        source: p.source,
+        file: p.file,
+        error: p.error ?? null
+      }));
+      const report = {
+        version: VERSION,
+        node: process.version,
+        homeDir,
+        homeDirExists: exists,
+        configWritable,
+        localPluginCount: plugins.length,
+        localPlugins: list
+      };
+      if (ctx.json) {
+        ctx.log.result(report);
+      } else {
+        ctx.log.result(`vcli ${VERSION} (node ${process.version})`);
+        ctx.log.result(`homeDir: ${homeDir} ${exists ? "(\u5B58\u5728)" : "(\u4E0D\u5B58\u5728)"}`);
+        ctx.log.result(`config: ${configWritable ? "\u53EF\u8BFB\u5199" : "\u4E0D\u53EF\u5199"}`);
+        ctx.log.result(`\u672C\u5730\u63D2\u4EF6: ${plugins.length} \u4E2A`);
+        for (const p of plugins) {
+          ctx.log.result(`  - ${p.file}${p.error ? `  [\u5931\u8D25: ${p.error}]` : ""}`);
+        }
+      }
+    });
+  }
+};
+
+// src/commands/plugin.ts
+import path3 from "path";
+var plugin = {
+  name: "plugin",
+  description: "\u63D2\u4EF6\u7BA1\u7406\uFF1Alist \u5217\u51FA\u547D\u4EE4\uFF0Cpath \u663E\u793A\u672C\u5730\u63D2\u4EF6\u76EE\u5F55",
+  register(program, ctx) {
+    program.command("list").description("\u5217\u51FA\u5185\u7F6E\u547D\u4EE4\u4E0E\u672C\u5730\u63D2\u4EF6").action(async () => {
+      const all = await loadAllCommands(ctx);
+      const rows = all.map((item) => ({
+        source: item.source,
+        name: item.command?.name ?? "(\u52A0\u8F7D\u5931\u8D25)",
+        description: item.command?.description ?? item.error ?? "",
+        file: item.file ?? ""
+      }));
+      if (ctx.json) {
+        ctx.log.result(rows);
+      } else {
+        for (const row of rows) {
+          ctx.log.result(`[${row.source}] ${row.name}: ${row.description}`);
+        }
+      }
+    });
+    program.command("path").description("\u6253\u5370\u672C\u5730\u63D2\u4EF6\u76EE\u5F55\uFF08\u653E\u5165 .mjs \u6587\u4EF6\u5373\u751F\u6548\uFF09").action(() => {
+      const dir = path3.join(ctx.homeDir, "commands");
+      if (ctx.json) {
+        ctx.log.result({ dir });
+      } else {
+        ctx.log.result(dir);
+      }
+    });
+  }
+};
+
+// src/commands/ts.ts
+function formatTime(ms) {
+  const d = new Date(ms);
+  return d.toISOString().replace("T", " ").replace("Z", "");
+}
+function parseInput(input) {
+  if (/^\d+$/.test(input)) {
+    const n = Number(input);
+    if (n > 1e12) {
+      return { seconds: Math.floor(n / 1e3), milliseconds: n, raw: input };
+    }
+    return { seconds: n, milliseconds: n * 1e3, raw: input };
+  }
+  const parsed = Date.parse(input);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`\u65E0\u6CD5\u89E3\u6790\u65F6\u95F4: ${input}`);
+  }
+  return { seconds: Math.floor(parsed / 1e3), milliseconds: parsed, raw: input };
+}
+var ts = {
+  name: "ts",
+  description: "\u65F6\u95F4\u6233\u5DE5\u5177\uFF1A\u65F6\u95F4\u6233 <-> \u53EF\u8BFB\u65F6\u95F4\u4E92\u8F6C",
+  register(program, ctx) {
+    program.argument("[value]", "\u6570\u5B57\u65F6\u95F4\u6233\uFF08\u79D2\u6216\u6BEB\u79D2\uFF0C\u81EA\u52A8\u8BC6\u522B\uFF09\u6216\u65E5\u671F\u5B57\u7B26\u4E32").action((value) => {
+      if (!value || value === "now") {
+        const now = Date.now();
+        const report2 = {
+          seconds: Math.floor(now / 1e3),
+          milliseconds: now,
+          iso: new Date(now).toISOString(),
+          local: new Date(now).toString()
+        };
+        ctx.log.result(ctx.json ? report2 : report2.iso);
+        return;
+      }
+      const result = parseInput(value);
+      const report = {
+        input: result.raw,
+        seconds: result.seconds,
+        milliseconds: result.milliseconds,
+        iso: new Date(result.milliseconds).toISOString(),
+        local: formatTime(result.milliseconds)
+      };
+      ctx.log.result(ctx.json ? report : report.local);
+    });
+  }
+};
+
+// src/commands/index.ts
+var builtinCommands = [doctor, plugin, ts];
+
+// src/core/loader.ts
+async function loadBuiltinCommands() {
+  return builtinCommands.map((command) => ({ command, source: "builtin" }));
+}
+async function loadLocalPlugins(ctx) {
+  const dir = path4.join(ctx.homeDir, "commands");
+  const loaded = [];
+  if (!fs3.existsSync(dir)) return loaded;
+  const files = fs3.readdirSync(dir).filter((f) => f.endsWith(".mjs")).sort();
+  for (const file of files) {
+    const abs = path4.join(dir, file);
+    try {
+      const mod = await import(
+        /* @vite-ignore */
+        pathToFileURL(abs).href
+      );
+      const cmd = mod.default ?? mod;
+      if (!isCliCommand(cmd)) {
+        loaded.push({ source: "local", file: abs, error: "\u9ED8\u8BA4\u5BFC\u51FA\u4E0D\u7B26\u5408 CliCommand \u5951\u7EA6" });
+        continue;
+      }
+      loaded.push({ command: cmd, source: "local", file: abs });
+    } catch (err) {
+      loaded.push({
+        source: "local",
+        file: abs,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return loaded;
+}
+async function loadAllCommands(ctx) {
+  return [...await loadBuiltinCommands(), ...await loadLocalPlugins(ctx)];
+}
+
+// src/cli.ts
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const json = rawArgs.includes("--json");
+  const args = rawArgs.filter((a) => a !== "--json");
+  const ctx = createContext(defaultHomeDir(), json);
+  const program = new Command();
+  program.name("v-cli").description("kevlns \u7684\u4E2A\u4EBA\u5DE5\u5177\u7BB1").version(VERSION).option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").showHelpAfterError();
+  const loaded = await loadAllCommands(ctx);
+  for (const item of loaded) {
+    if (!item.command) {
+      ctx.log.warn(`${item.file ?? "?"} \u52A0\u8F7D\u5931\u8D25: ${item.error ?? "\u672A\u77E5\u9519\u8BEF"}`);
+      continue;
+    }
+    const cmd = item.command;
+    if (cmd.hidden) continue;
+    const sub = program.command(cmd.name).description(cmd.description);
+    cmd.register(sub, ctx);
+  }
+  try {
+    await program.parseAsync(args, { from: "user" });
+    return 0;
+  } catch (err) {
+    if (err instanceof CommanderError) {
+      return err.exitCode ?? 1;
+    }
+    ctx.log.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`[v-cli] \u672A\u6355\u83B7\u5F02\u5E38: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+);

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kevlns/v-cli",
+  "version": "0.1.1-beta.1",
+  "description": "kevlns 的个人工具箱 CLI（插件化架构，内置 + 本地插件）+ doctor/plugin/ts 命令",
+  "type": "module",
+  "bin": {
+    "v-cli": "dist/cli.mjs"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run build && npm run typecheck && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "kevlns <936277610@qq.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kevlns/v-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kevlns/v-cli/issues"
+  },
+  "homepage": "https://github.com/kevlns/v-cli#readme",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cli",
+    "toolbox",
+    "personal"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
+  },
+  "allowScripts": {
+    "esbuild@0.27.2": true
+  }
+}