@code2rich/jpage 1.5.0

package/bin/commands/mv.js

@@ -0,0 +1,20 @@
+// mv 命令：修改文件名（original_name）。后端：PUT /api/files/:id { name }。
+
+const { out } = require('./_shared');
+
+async function run(client, args) {
+  const id = args.sub;
+  const newName = args.positional[2];
+  if (!id || !newName) {
+    const e = new Error('用法：jpage mv <id> <新文件名>');
+    e.name = 'UsageError';
+    throw e;
+  }
+  const body = { name: newName };
+  if (args.opts.public !== undefined) body.isPublic = true;
+  if (args.opts.private !== undefined) body.isPublic = false;
+  await client.put(`/api/files/${id}`, body);
+  out(`✓ 已更新 #${id}\n`);
+}
+
+module.exports = { run };

package/bin/commands/rm.js

@@ -0,0 +1,22 @@
+// rm 命令：删除文件。后端：DELETE /api/files/:id。不可撤销。
+
+const { out, err } = require('./_shared');
+
+async function run(client, args, { exit }) {
+  const id = args.sub;
+  if (!id) {
+    const e = new Error('用法：jpage rm <id>');
+    e.name = 'UsageError';
+    throw e;
+  }
+  // 简单防误删：--yes 才跳过确认（非交互环境默认会提示）
+  if (!args.opts.yes && process.stdin.isTTY) {
+    err(`将删除文件 #${id}，此操作不可撤销。加 --yes 跳过确认。\n`);
+    (exit || ((c) => { process.exitCode = c; }))(1);
+    return;
+  }
+  await client.del(`/api/files/${id}`);
+  out(`✓ 已删除 #${id}\n`);
+}
+
+module.exports = { run };

package/bin/commands/skills.js

@@ -0,0 +1,70 @@
+// skills 命令：列出 / 查看 / 下载 Skill 包。
+// 后端：GET /api/skills、GET /api/skills/:name、GET /api/skills/:name/download（zip 流）。
+
+const fs = require('fs');
+const path = require('path');
+const { out } = require('./_shared');
+
+async function run(client, args, { base }) {
+  const sub = args.sub; // ls / get / download
+  if (!sub || sub === 'ls' || sub === 'list') {
+    return listSkills(client);
+  }
+  const name = args.positional[2];
+  if (!name) {
+    const e = new Error('用法：jpage skills get <name> | jpage skills download <name>');
+    e.name = 'UsageError';
+    throw e;
+  }
+  if (sub === 'get') {
+    return getSkill(client, name);
+  }
+  if (sub === 'download') {
+    return downloadSkill(client, name, args, { base });
+  }
+  const e = new Error(`未知子命令：${sub}。支持：ls / get / download`);
+  e.name = 'UsageError';
+  throw e;
+}
+
+async function listSkills(client) {
+  const data = await client.get('/api/skills');
+  const skills = data.skills || [];
+  if (skills.length === 0) {
+    out('（无 Skill）\n');
+    return;
+  }
+  for (const s of skills) {
+    out(`${s.name}  v${s.version || '-'}  (${s.fileCount || 0} 文件)\n`);
+    if (s.description) {
+      out(`  ${s.description}\n`);
+    }
+  }
+}
+
+async function getSkill(client, name) {
+  const s = await client.get(`/api/skills/${name}`);
+  out(`${s.title || s.name}  v${s.version || '-'}  作者：${s.author || '-'}\n`);
+  if (s.description) out(`\n${s.description}\n`);
+  out(`\n文件（${s.fileCount || (s.files || []).length}）：\n`);
+  for (const f of s.files || []) {
+    out(`  ${f}\n`);
+  }
+}
+
+async function downloadSkill(client, name, args, _ctx) {
+  const res = await client.raw(`/api/skills/${name}/download`);
+  if (res.status < 200 || res.status >= 300) {
+    const text = await res.text().catch(() => '');
+    const e = new Error(`下载失败：HTTP ${res.status} ${text}`);
+    e.name = 'HttpError';
+    e.status = res.status;
+    throw e;
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const outFile = args.opts.out || `${name}.zip`;
+  fs.writeFileSync(path.resolve(outFile), buf);
+  out(`✓ 已下载 ${name} → ${outFile} (${buf.length} 字节)\n`);
+}
+
+module.exports = { run };

package/bin/commands/star.js

@@ -0,0 +1,23 @@
+// star / unstar 命令：收藏 / 取消收藏。
+// 后端：POST /api/files/:id/star、DELETE /api/files/:id/star。
+
+const { out } = require('./_shared');
+
+async function run(client, args) {
+  const id = args.sub;
+  if (!id) {
+    const e = new Error('用法：jpage star <id>');
+    e.name = 'UsageError';
+    throw e;
+  }
+  // cmd 本身就是 star 或 unstar
+  if (args.cmd === 'unstar') {
+    await client.del(`/api/files/${id}/star`);
+    out(`✓ 已取消收藏 #${id}\n`);
+  } else {
+    await client.post(`/api/files/${id}/star`);
+    out(`✓ 已收藏 #${id}\n`);
+  }
+}
+
+module.exports = { run };

package/bin/commands/tags.js

@@ -0,0 +1,97 @@
+// tags 命令：查看/添加/替换/清空文件的标签。
+//
+// 后端语义：PUT /api/files/:id/tags { tagIds:[] } 是「全量替换」，且只收 tag id（数字），
+// 没有「按名字追加」端点。CLI 在客户端封装出更友好的命令：
+//
+//   jpage tags <id>               列出当前标签
+//   jpage tags <id> add a,b,c     把这些标签追加到现有标签（缺失的标签自动创建）
+//   jpage tags <id> set a,b       全量替换为这些标签（缺失的自动创建）
+//   jpage tags <id> clear         清空标签
+//
+// 标签名 → id：GET /api/tags 拿全表按 name 精确匹配；缺失的 POST /api/tags {name} 建。
+
+const { out } = require('./_shared');
+
+async function run(client, args) {
+  const id = args.sub;
+  if (!id) {
+    const e = new Error('用法：jpage tags <id> [add|set|clear] [标签名,标签名,...]');
+    e.name = 'UsageError';
+    throw e;
+  }
+
+  const action = args.positional[2]; // add / set / clear，或空（查询）
+  const namesArg = args.positional[3];
+
+  // 无 action → 列出
+  if (!action) {
+    return listTags(client, id);
+  }
+
+  if (action === 'clear') {
+    await client.put(`/api/files/${id}/tags`, { tagIds: [] });
+    out(`✓ 已清空 #${id} 的标签\n`);
+    return;
+  }
+
+  if (action !== 'add' && action !== 'set') {
+    const e = new Error(`未知操作：${action}。支持：add / set / clear`);
+    e.name = 'UsageError';
+    throw e;
+  }
+
+  if (!namesArg) {
+    const e = new Error(`用法：jpage tags ${id} ${action} <标签名,标签名,...>`);
+    e.name = 'UsageError';
+    throw e;
+  }
+
+  const names = namesArg.split(',').map((s) => s.trim()).filter(Boolean);
+
+  // add：先拿现有标签，合并去重；set：直接用新的
+  let targetNames = names;
+  if (action === 'add') {
+    const file = await client.get(`/api/files/${id}`);
+    const existing = (file.tags || []).map((t) => t.name);
+    targetNames = [...new Set([...existing, ...names])];
+  }
+
+  // 名字 → id（缺失的创建）
+  const tagIds = await resolveOrCreateTagIds(client, targetNames);
+  await client.put(`/api/files/${id}/tags`, { tagIds });
+  out(
+    `✓ 已${action === 'add' ? '追加' : '设置'} #${id} 的标签：${targetNames.join(', ')}\n`
+  );
+}
+
+async function listTags(client, id) {
+  const file = await client.get(`/api/files/${id}`);
+  const tags = file.tags || [];
+  if (tags.length === 0) {
+    out(`文件 #${id} 没有标签\n`);
+    return;
+  }
+  out(`文件 #${id} 的标签：\n`);
+  for (const t of tags) {
+    out(`  ${t.name} (#${t.id})\n`);
+  }
+}
+
+// 把标签名数组解析为 id 数组；缺失的标签通过 POST /api/tags 创建。
+async function resolveOrCreateTagIds(client, names) {
+  const all = await client.get('/api/tags');
+  const byName = new Map((all.tags || []).map((t) => [t.name, t.id]));
+  const ids = [];
+  for (const name of names) {
+    if (byName.has(name)) {
+      ids.push(byName.get(name));
+      continue;
+    }
+    const created = await client.post('/api/tags', { name });
+    byName.set(name, created.id);
+    ids.push(created.id);
+  }
+  return ids;
+}
+
+module.exports = { run };

package/bin/commands/upload.js

@@ -0,0 +1,84 @@
+// upload 命令：上传本地文件到即页。
+//
+// 后端契约（routes/files/upload.js）：
+//   POST /api/files/upload          multipart，field=file，可选 isPublic=true
+//                                  （同名自动覆盖，含 version 备份）
+//   POST /api/files/:id/overwrite   multipart，field=file（按 id 覆盖，仅 file 一个 field）
+//
+// 性能：用全局 FormData + Blob 构造 multipart，二进制流式，
+// 不把内容 base64 塞进任何 token 流（这正是 CLI 相对 MCP upload_file 的核心优势）。
+
+const fs = require('fs');
+const path = require('path');
+const { formatSize, out } = require('./_shared');
+
+async function run(client, args, { base }) {
+  const filePath = args.sub; // 第一个位置参数（cmd=upload，sub=文件路径）
+  if (!filePath) {
+    throw new UsageError('用法：jpage upload <文件路径> [--public] [--overwrite ID]');
+  }
+
+  const abs = path.resolve(filePath);
+  let stat;
+  try {
+    stat = fs.statSync(abs);
+  } catch {
+    throw new UsageError(`文件不存在或无法读取：${filePath}`);
+  }
+  if (!stat.isFile()) {
+    throw new UsageError(`不是文件：${filePath}`);
+  }
+
+  const buf = fs.readFileSync(abs);
+  const name = path.basename(abs);
+  const blob = new Blob([buf]);
+  const overwriteId = args.opts.overwrite;
+
+  const form = new FormData();
+  form.append('file', blob, name);
+  // multipart 默认私有；--public 才公开（与 routes/files/upload.js:28 一致）
+  if (args.opts.public) form.append('isPublic', 'true');
+
+  let endpoint;
+  if (overwriteId) {
+    endpoint = `/api/files/${overwriteId}/overwrite`;
+  } else {
+    endpoint = '/api/files/upload';
+  }
+
+  const data = await client.postForm(endpoint, form);
+  printResult(data, base);
+}
+
+function printResult(data, base) {
+  // 批量上传（ZIP 含多个独立文件）
+  if (data.type === 'batch') {
+    out(`✓ 批量上传 ${data.count} 个文件\n`);
+    for (const f of data.files) {
+      const url = f.share_key ? `${base}/s/${f.share_key}` : '-';
+      out(`  #${f.id}  ${f.original_name}  →  ${url}\n`);
+    }
+    return;
+  }
+
+  // 单文件 / bundle
+  const url = data.share_key ? `${base}/s/${data.share_key}` : '-';
+  out(`✓ 上传成功 #${data.id}  ${data.original_name}  (${formatSize(data.size)})\n`);
+  if (data.overwritten) {
+    out(`  覆盖已有文件，版本 v${data.version}\n`);
+  }
+  if (data.is_bundle) {
+    out(`  网站包（bundle），入口：${data.entry_path || 'index.html'}\n`);
+  }
+  out(`  预览：${url}\n`);
+}
+
+// 命令层专用的用法错误（区别于 HTTP/网络错误），bin/jpage.js 据此打印帮助并退出 2
+class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+module.exports = { run, UsageError };

package/bin/commands/url.js

@@ -0,0 +1,25 @@
+// url 命令：打印文件的公开预览短链。
+// 后端：GET /api/files/:id（取 share_key，拼 /s/:key）。
+
+const { shareUrl, out, err } = require('./_shared');
+
+async function run(client, args, { base, exit }) {
+  const id = args.sub;
+  if (!id) {
+    const e = new Error('用法：jpage url <id>');
+    e.name = 'UsageError';
+    throw e;
+  }
+  const data = await client.get(`/api/files/${id}`);
+  const url = shareUrl(base, data);
+  if (!url) {
+    err(
+      `文件 #${id} 没有公开短链（私有文件）。用 \`jpage mv ${id} --public\` 设为公开后再获取链接。\n`
+    );
+    (exit || ((c) => { process.exitCode = c; }))(1);
+    return;
+  }
+  out(url + '\n');
+}
+
+module.exports = { run };

package/bin/commands/whoami.js

@@ -0,0 +1,29 @@
+// whoami 命令：校验当前 token 是否有效（纯客户端，不动后端）。
+//
+// 后端没有 token→用户名的解析端点（GET /api/auth/me 只认 session，不认 Bearer）。
+// 故用 GET /api/files?limit=1 探测：200=有效，401=无效。无法显示用户名。
+
+const { out, err } = require('./_shared');
+
+async function run(client, _args, { base, token, exit }) {
+  try {
+    await client.get('/api/files?limit=1');
+    out(`✓ token 有效，可访问 ${base}\n`);
+    if (token) {
+      // 只显示前缀，避免在终端泄露完整 token
+      const prefix = token.length > 8 ? token.slice(0, 8) + '…' : token;
+      out(`  token：${prefix}\n`);
+    }
+  } catch (e) {
+    if (e.status === 401) {
+      err(
+        '✗ token 无效或未设置。用 --token <TOKEN>、JPAGE_TOKEN 环境变量、或 .env 的 MCP_TOKEN 提供。\n'
+      );
+      (exit || ((c) => { process.exitCode = c; }))(1);
+      return;
+    }
+    throw e;
+  }
+}
+
+module.exports = { run };

package/bin/config.js

@@ -0,0 +1,85 @@
+// CLI 配置解析：token 与 base（服务地址）的来源优先级。
+//
+// 不引入 dotenv。.env 文件按 KEY=VALUE 简单行解析（兼容带引号、注释、空行）。
+//
+// 优先级（高 → 低）：
+//   --token  >  JPAGE_TOKEN env  >  MCP_TOKEN env（环境 + .env 文件）
+//   --base   >  JPAGE_BASE  env  >  默认 http://localhost:8858
+//
+// 设计：让 jpage 能「无参跑通本地默认实例」，同时支持远程/CI 场景显式指定。
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_BASE = 'http://localhost:8858';
+
+// 解析 .env 文件为对象。仅支持最简语法：KEY=VALUE，值可带引号，# 开头为注释。
+// 失败（文件不存在/读错）返回空对象，由调用方决定是否报错。
+function parseEnvFile(filePath) {
+  const result = {};
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return result;
+  }
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq < 1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    // 去引号
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+// 从当前目录向上查找 .env（最多 5 层），合并所有命中文件。
+// 这模仿 MCP/SKILL.md 里「项目根 .env」的惯例。
+function loadEnvUp(startDir) {
+  const merged = {};
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 5; i++) {
+    const envPath = path.join(dir, '.env');
+    const parsed = parseEnvFile(envPath);
+    Object.assign(merged, parsed);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return merged;
+}
+
+/**
+ * 解析最终配置。
+ * @param {object} opts - 来自 args.parse 的 opts 对象（含 --token/--base 等）
+ * @param {object} [env] - 环境变量（默认 process.env，测试可注入）
+ * @param {string} [cwd] - .env 查找起点（默认 process.cwd()）
+ * @returns {{token: string|null, base: string}}
+ */
+function resolveConfig(opts, env = process.env, cwd = process.cwd()) {
+  const dotEnv = loadEnvUp(cwd);
+
+  const token =
+    opts.token ||
+    env.JPAGE_TOKEN ||
+    dotEnv.JPAGE_TOKEN ||
+    env.MCP_TOKEN ||
+    dotEnv.MCP_TOKEN ||
+    null;
+
+  const base = (opts.base || env.JPAGE_BASE || dotEnv.JPAGE_BASE || DEFAULT_BASE)
+    .replace(/\/+$/, ''); // 去尾部斜杠，避免拼接出 //
+
+  return { token, base };
+}
+
+module.exports = { resolveConfig, parseEnvFile, loadEnvUp, DEFAULT_BASE };

package/bin/jpage.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// jpage CLI 入口：解析 argv → 解析配置 → 创建 client → dispatch 到命令。
+//
+// 分层：
+//   args.js     argv → {cmd, sub, opts, positional}
+//   config.js   opts + env + .env → {token, base}
+//   client.js   createClient({base, token, fetchImpl})
+//   commands/*  每个命令导出 async run(client, args, ctx)
+//
+// 错误处理集中在此：
+//   UsageError  → 打印用法到 stderr，退出 2
+//   HttpError   → 打印 API 错误到 stderr，401 额外提示 token，退出 1
+//   NetworkError→ 打印连接错误，退出 1
+//
+// 导出 run(argv, {fetchImpl}) 供测试调用（不依赖 process.argv、不退出进程）。
+
+const { parse } = require('./args');
+const { resolveConfig } = require('./config');
+const { createClient, HttpError } = require('./client');
+const { setIo, resetIo } = require('./commands/_shared');
+
+const COMMANDS = {
+  upload: () => require('./commands/upload'),
+  ls: () => require('./commands/ls'),
+  cat: () => require('./commands/cat'),
+  url: () => require('./commands/url'),
+  mv: () => require('./commands/mv'),
+  rm: () => require('./commands/rm'),
+  star: () => require('./commands/star'),
+  unstar: () => require('./commands/star'),
+  tags: () => require('./commands/tags'),
+  skills: () => require('./commands/skills'),
+  whoami: () => require('./commands/whoami'),
+};
+
+const HELP = `jpage —— 即页命令行
+
+用法：
+  jpage <命令> [参数] [选项]
+
+命令：
+  upload <路径> [--public] [--overwrite ID]   上传文件（multipart，ZIP 自动判 bundle/batch）
+  ls [--page N --limit N --sort 字段 --order asc|desc --kw 词 --cat 分类 --tag 标签]
+                                              列出文件
+  cat <id>                                    输出文件原始内容
+  url <id>                                    打印文件公开预览链接 /s/:key
+  mv <id> <新名> [--public|--private]          改名 / 改公开性
+  rm <id> [--yes]                             删除文件（--yes 跳过确认）
+  star <id> / unstar <id>                     收藏 / 取消收藏
+  tags <id> [add|set|clear] [名,名,...]        查看 / 追加 / 替换 / 清空标签
+  skills ls | get <名> | download <名> [--out 文件]
+                                              列出 / 查看 / 下载 Skill
+  whoami                                      校验 token 是否有效
+
+通用选项：
+  --token <TOKEN>        鉴权 token（jp_ 用户 token 或 MCP_TOKEN）
+  --base <URL>           服务地址（默认 http://localhost:8858）
+  --help, -h             显示本帮助
+
+token 优先级：--token > JPAGE_TOKEN 环境变量 > MCP_TOKEN 环境变量 > .env 里的同名变量
+base  优先级：--base  > JPAGE_BASE  环境变量 > 默认 http://localhost:8858
+
+示例：
+  jpage upload ./report.html --public
+  jpage upload ./site.zip --public
+  jpage upload ./x.html --overwrite 12
+  jpage ls --kw 季度 --limit 5
+  jpage cat 8
+  jpage tags 8 add 季度,财报
+  jpage skills download jpage-upload
+
+详细文档：https://github.com/code2rich/jpage`;
+
+/**
+ * 运行 CLI。供入口和测试共用。
+ * @param {string[]} argv - 去掉 node/脚本名后的参数
+ * @param {object} [inject] - 测试注入：{ fetchImpl, env, cwd, stdout, stderr, exit }
+ * @returns {Promise<void>} 失败时设置 exit 状态（默认 process.exitCode，测试可注入）
+ */
+async function run(argv, inject = {}) {
+  // 注入 I/O：默认走 process.stdout/stderr + process.exitCode。
+  // 测试注入 { stdout, stderr, exit } 用内存 sink + 计数器，避免污染 node:test 输出。
+  const stdout = inject.stdout || process.stdout;
+  const stderr = inject.stderr || process.stderr;
+  const exit = inject.exit || ((code) => { process.exitCode = code; });
+
+  // 把命令模块的 out()/err() 重定向到同一组流
+  setIo({ stdout, stderr });
+
+  const parsed = parse(argv);
+  const { cmd, opts } = parsed;
+
+  if (opts.version) {
+    const pkg = require('../package.json');
+    stdout.write(pkg.version + '\n');
+    return;
+  }
+
+  if (opts.help || opts.h || !cmd) {
+    stdout.write(HELP + '\n');
+    return;
+  }
+
+  if (!COMMANDS[cmd]) {
+    stderr.write(`未知命令：${cmd}\n\n${HELP}\n`);
+    exit(2);
+    return;
+  }
+
+  const { token, base } = resolveConfig(opts, inject.env, inject.cwd);
+  if (!token) {
+    stderr.write(
+      '未提供 token。用 --token <TOKEN>、JPAGE_TOKEN 环境变量、或 .env 的 MCP_TOKEN 设置。\n'
+    );
+    exit(2);
+    return;
+  }
+
+  const client = createClient({ base, token, fetchImpl: inject.fetchImpl });
+  const ctx = { base, token, exit };
+  const mod = COMMANDS[cmd]();
+
+  try {
+    await mod.run(client, parsed, ctx);
+  } catch (e) {
+    handleError(e, { stderr, exit });
+  }
+}
+
+function handleError(e, { stderr, exit }) {
+  if (e.name === 'UsageError') {
+    stderr.write(e.message + '\n');
+    exit(2);
+    return;
+  }
+  if (e instanceof HttpError) {
+    stderr.write(`✗ ${e.message}\n`);
+    if (e.status === 401) {
+      stderr.write('  token 无效或已失效。检查 --token / JPAGE_TOKEN / .env 的 MCP_TOKEN。\n');
+    }
+    if (e.status === 429) {
+      stderr.write('  请求过于频繁（如上传 50 次/15 分钟）。稍后再试。\n');
+    }
+    exit(1);
+    return;
+  }
+  if (e.name === 'NetworkError') {
+    stderr.write(`✗ ${e.message}\n`);
+    exit(1);
+    return;
+  }
+  // 兜底
+  stderr.write(`✗ ${e.message || e}\n`);
+  exit(1);
+}
+
+// 直接执行（node bin/jpage.js ...）
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  run(argv).catch((e) => {
+    process.stderr.write(`✗ ${e && e.message ? e.message : e}\n`);
+    process.exitCode = 1;
+  }).finally(() => {
+    resetIo();
+  });
+}
+
+module.exports = { run, HELP, COMMANDS, handleError };