@edmund32/edx-cli 0.1.2

package/README.md

@@ -0,0 +1,372 @@
+# @edmund/edx-cli
+
+跨平台 Edmund 指令包。安装后会提供这些命令：
+
+```bash
+edx
+edx-app
+edx-alias
+edx-hw
+edx-image
+edx-md
+```
+
+## 安装
+
+从 npm 官方仓库安装：
+
+```bash
+npm install -g @edmund/edx-cli
+```
+
+`-g` 表示安装到 npm 全局目录。npm 会读取 `package.json` 里的 `bin` 字段，把 `edx`、`edx-image` 等命令链接到全局 bin 目录，所以安装后可以在任意目录直接使用。
+
+依赖会一起安装。比如本包依赖 `sharp`，执行 `npm install -g ...` 时 npm 会自动下载依赖，用户不需要再进入包目录单独 `npm install`。
+
+查看全局安装位置：
+
+```bash
+npm root -g
+npm prefix -g
+```
+
+### `npm install -g` 做了什么
+
+以这个命令为例：
+
+```bash
+npm install -g @edmund/edx-cli
+```
+
+npm 会做以下几步：
+
+1. 到 npm registry 查询 `@edmund/edx-cli` 的包信息，包括最新版本、tarball 下载地址、依赖列表和 `bin` 命令配置。
+2. 下载包的 `.tgz` 压缩包。npm 包本质上就是一个 tarball，例如 `edmund-edx-cli-0.1.0.tgz`。
+3. 解压 `.tgz` 到全局 `node_modules` 目录。
+4. 读取包里的 `package.json`，安装 `dependencies`。本包里的 `sharp` 会在这一步自动下载。
+5. 读取 `package.json` 的 `bin` 字段，生成全局命令入口。
+
+本包的 `bin` 字段类似：
+
+```json
+{
+  "bin": {
+    "edx": "bin/edx.js",
+    "edx-app": "bin/edx-app.js",
+    "edx-alias": "bin/edx-alias.js",
+    "edx-hw": "bin/edx-hw.js",
+    "edx-image": "bin/edx-image.js",
+    "edx-md": "bin/edx-md.js"
+  }
+}
+```
+
+所以 npm 会把 `edx`、`edx-alias`、`edx-image` 等命令链接到全局 bin 目录。这个目录通常在系统 `PATH` 环境变量中，因此可以在任意目录直接执行：
+
+```bash
+edx-image mkdir demo
+```
+
+全局安装后的文件大致是：
+
+```text
+<npm全局node_modules>/@edmund/edx-cli/
+  bin/
+  src/
+  vendor/
+  package.json
+  node_modules/
+```
+
+命令入口大致是：
+
+```text
+<npm全局bin>/edx-image -> <npm全局node_modules>/@edmund/edx-cli/bin/edx-image.js
+```
+
+Windows 上 npm 通常会生成 `.cmd` 和 `.ps1` 启动脚本，例如：
+
+```text
+edx-image.cmd
+edx-image.ps1
+```
+
+所以 PowerShell 和 CMD 也能直接执行：
+
+```powershell
+edx-image mkdir demo
+```
+
+如果安装的是本地 tgz：
+
+```bash
+npm install -g ./edmund-edx-cli-0.1.0.tgz
+```
+
+流程也基本一样，只是主包不是从 npm registry 下载，而是从本地 `.tgz` 读取；依赖仍会根据 `package.json` 自动安装。
+
+## 使用
+
+查看顶层入口：
+
+```bash
+edx -a
+```
+
+创建图片项目目录：
+
+```bash
+edx-image mkdir demo
+```
+
+按行列切分图片或目录：
+
+```bash
+edx-image split grid ./target --rows 3 --cols 3
+```
+
+输出会生成在输入目录同级的 `target_output/` 中。单张 `A.png` 会输出到：
+
+```text
+target_output/A/A_001.png
+target_output/A/A_002.png
+...
+```
+
+递归目录会镜像为 `_output` 目录，例如 `target/A/*.png` 输出到：
+
+```text
+target_output/A_output/
+```
+
+按比例坐标裁切区域：
+
+```bash
+edx-image split region ./target --from 0,0 --to 0.5,0.5
+```
+
+`region` 坐标使用 `0-1` 比例，原点在左下角。`--from` 是左下角，`--to` 是右上角。
+
+右半边裁切不需要单独命令，直接用：
+
+```bash
+edx-image split region ./target --from 0.5,0 --to 1,1
+```
+
+拼接文件夹图片：
+
+```bash
+edx-image merge ./target --rows 3
+```
+
+输出会生成在输入目录同级的 `target_merged/` 中。`merge` 会递归处理 `target` 下面每个“直接包含图片”的文件夹，但结果目录只保留一层：
+
+```text
+target/001.png        -> target_merged/target.png
+target/A/001.png      -> target_merged/A.png
+target/B/001.png      -> target_merged/B.png
+```
+
+如果 `target` 根目录本身有图片，会单独拼成 `target_merged/target.png`。如果子文件夹也有图片，每个子文件夹会各自拼成一张图片并扁平放入 `target_merged/`。
+
+固定行列拼接：
+
+```bash
+edx-image merge ./target --rows 3 --cols 3
+```
+
+图片按文件名排序，按行优先放置：第一行是第 1、2、3 张，第二行是第 4、5、6 张。图片少于固定格子数时用黑色背景占位，图片多于固定格子数时只取排序靠前的图片。
+
+指定每个格子的尺寸：
+
+```bash
+edx-image merge ./target --rows 3 --cols 3 --cellw 512 --cellh 512
+```
+
+如果不传 `--cellw/--cellh`，每个文件夹会使用该文件夹第一张图片的尺寸作为格子尺寸；如果只传其中一个，另一个会使用相同数值。输出统一为 `png`。
+
+复制 Markdown 资源：
+
+```bash
+edx-md copy old.md new.md
+```
+
+检查鸿蒙相关环境：
+
+```bash
+edx-hw show
+```
+
+检查应用入口：
+
+```bash
+edx-app show
+edx-app ls
+edx-app run "Visual Studio Code"
+edx-app run code
+edx-app run "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk"
+```
+
+注册并打开本机常用目录或文件：
+
+```bash
+edx-alias add target /some/deep/path --type=dir
+edx-alias update target /some/new/path --type=dir
+edx-alias add note /some/deep/note.txt --type=file
+edx-alias update note /some/new/note.txt --type=file --app TextEdit
+edx-alias open target
+edx-alias open note
+edx-alias open note --app "Visual Studio Code"
+edx-alias ls
+edx-alias remove target
+edx-app ls
+```
+
+`edx-app ls` 会列出可直接启动的精确应用值：macOS 输出 `.app` 名称，Ubuntu/Linux 输出 `.desktop` 的可执行命令，Windows 输出开始菜单 `.lnk` 路径。拿到这些值后，可以用 `edx-app run <APP>` 直接打开应用，也可以把同样的值传给 `edx-alias open --app`。
+
+`edx-alias` 不内置任何固定快捷项。用户全局安装 npm 包后，自己把本机目录或文件注册到 `~/.edx/aliases.json`。添加和更新记录时必须带 `--type=dir` 或 `--type=file`；文件快捷项可以在注册时通过 `--app` 绑定默认打开应用，也可以在 `open` 时用 `--app` 临时覆盖。`edx-alias ls` 会按 `target / path / type` 三列展示记录，并按类型给 `type` 上色。
+
+## 更新
+
+更新到远端最新版：
+
+```bash
+npm install -g @edmund/edx-cli@latest
+```
+
+也可以使用：
+
+```bash
+npm update -g @edmund/edx-cli
+```
+
+查看本机已安装版本：
+
+```bash
+npm list -g @edmund/edx-cli
+```
+
+查看远端最新版本：
+
+```bash
+npm view @edmund/edx-cli version
+```
+
+卸载：
+
+```bash
+npm uninstall -g @edmund/edx-cli
+```
+
+## 开发
+
+安装开发依赖：
+
+```bash
+npm install
+```
+
+运行测试：
+
+```bash
+npm test
+```
+
+本地临时全局安装，方便在任意目录测试命令：
+
+```bash
+npm link
+```
+
+取消本地链接：
+
+```bash
+npm unlink -g @edmund/edx-cli
+```
+
+## 打包与发布
+
+本项目目前是纯 Node CLI，没有 TypeScript 编译、Vite 构建或前端产物，所以不需要 `npm run build`。
+
+发布前先检查测试：
+
+```bash
+npm test
+```
+
+预览 npm 包会包含哪些文件：
+
+```bash
+npm pack --dry-run
+```
+
+`--dry-run` 的意思是“预演”。它会模拟执行打包流程，打印将进入 npm 包的文件列表，但不会真的生成 `.tgz` 文件，也不会上传任何东西。
+
+真正打出 npm tarball：
+
+```bash
+npm pack
+```
+
+执行后会生成类似：
+
+```text
+edmund-edx-cli-0.1.0.tgz
+```
+
+这个 `.tgz` 可以上传到 GitHub Release、Cloudflare R2、公司内网文件服务器，也可以直接在另一台电脑安装：
+
+```bash
+npm install -g ./edmund-edx-cli-0.1.0.tgz
+```
+
+发布到 npm 官方仓库：
+
+```bash
+npm login
+npm publish --access public
+```
+
+每次发布新版本前都要升级版本号，因为 npm 不允许重复发布同一个包名和版本号：
+
+```bash
+npm version patch
+npm publish --access public
+```
+
+版本号常用规则：
+
+```text
+patch: 0.1.0 -> 0.1.1，小修复
+minor: 0.1.0 -> 0.2.0，新功能
+major: 0.1.0 -> 1.0.0，破坏性变更
+```
+
+## npm pack 和 npm run build 的区别
+
+`npm pack` 是 npm 自带命令，用来把当前包按 npm 发布规则打成 `.tgz`。
+
+`npm run build` 不是 npm 内置打包规则，而是执行 `package.json` 里 `scripts.build` 配置的命令。比如 Vite 项目通常会写：
+
+```json
+{
+  "scripts": {
+    "build": "vite build"
+  }
+}
+```
+
+所以 Vite 的 `npm run build` 是生成前端 `dist/` 产物，不等于 `npm pack`，也不会自动封装 `npm pack`。如果一个项目想让 `npm run build` 后再打 npm 包，需要自己显式配置脚本。
+
+本项目没有配置 `build`，因为当前源码可以直接由 Node 运行。
+
+## 图片处理命令
+
+`edx-image` 只保留通用图片处理入口：
+
+```bash
+edx-image mkdir demo
+edx-image split grid ./target --rows 3 --cols 3
+edx-image split region ./target --from 0.5,0 --to 1,1
+edx-image merge ./target --rows 3
+```

package/bin/edx-alias.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/run.mjs';
+import { runAliasCommand } from '../src/commands/alias.mjs';
+
+await runCli(runAliasCommand, process.argv.slice(2));

package/bin/edx-app.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/run.mjs';
+import { runAppCommand } from '../src/commands/app.mjs';
+
+await runCli(runAppCommand, process.argv.slice(2));

package/bin/edx-hw.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/run.mjs';
+import { runHwCommand } from '../src/commands/hw.mjs';
+
+await runCli(runHwCommand, process.argv.slice(2));

package/bin/edx-image.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/run.mjs';
+import { runImageCommand } from '../src/commands/image.mjs';
+
+await runCli(runImageCommand, process.argv.slice(2));

package/bin/edx-md.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/run.mjs';
+import { runMdCommand } from '../src/commands/md.mjs';
+
+await runCli(runMdCommand, process.argv.slice(2));

package/bin/edx.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/run.mjs';
+import { runEdxCommand } from '../src/cli/edx.mjs';
+
+await runCli(runEdxCommand, process.argv.slice(2));

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@edmund32/edx-cli",
+  "version": "0.1.2",
+  "description": "Cross-platform Edmund command set",
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "bin": {
+    "edx": "bin/edx.js",
+    "edx-app": "bin/edx-app.js",
+    "edx-alias": "bin/edx-alias.js",
+    "edx-hw": "bin/edx-hw.js",
+    "edx-image": "bin/edx-image.js",
+    "edx-md": "bin/edx-md.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "sharp": "^0.34.5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli/edx.mjs

@@ -0,0 +1,30 @@
+import { ok, fail } from '../utils/result.mjs';
+
+function help() {
+  return [
+    '欢迎使用 Edmund 的跨平台指令集',
+    '',
+    '顶层入口:',
+    '  edx-app',
+    '  edx-alias',
+    '  edx-hw',
+    '  edx-image',
+    '  edx-md',
+  ].join('\n');
+}
+
+function topLevelHint(name) {
+  const commands = new Set(['app', 'alias', 'hw', 'image', 'md']);
+  return commands.has(name) ? `\n请直接使用顶层入口: edx-${name}` : '';
+}
+
+export async function runEdxCommand(args, options = {}) {
+  void options;
+  const [name] = args;
+
+  if (!name || name === '-a' || name === '--help' || name === 'help') {
+    return ok(help());
+  }
+
+  return fail(`错误: 未知参数 '${name}'${topLevelHint(name)}\n${help()}`);
+}

package/src/cli/run.mjs

@@ -0,0 +1,17 @@
+export async function runCli(handler, args) {
+  try {
+    const result = await handler(args);
+
+    if (result.stdout) {
+      process.stdout.write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+    }
+    if (result.stderr) {
+      process.stderr.write(result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`);
+    }
+
+    process.exitCode = result.code;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}