@code2rich/jpage 1.5.0

package/README_EN.md

@@ -0,0 +1,399 @@
+# jpage
+
+> Drop a file, get a page — instantly.
+
+[![CI](https://github.com/code2rich/jpage/actions/workflows/ci.yml/badge.svg)](https://github.com/code2rich/jpage/actions/workflows/ci.yml)
+
+**[>>> View Product Introduction <<<](https://jpage.cn/)**
+
+**jpage** is a zero-config HTML / Markdown instant preview and sharing tool. Drop in a document and instantly get a clean online page — no deployment pipeline, no server knowledge required. Especially great for one-click sharing of AI-generated content.
+
+---
+
+## Features
+
+### Core
+
+- **Instant Preview** — Upload HTML or Markdown files, get a rendered online page in seconds
+- **Enhanced Markdown Rendering** — Syntax highlighting (highlight.js), math formulas (KaTeX), Mermaid diagrams, with automatic dark/light theme switching
+- **Source View** — Toggle between rendered and source modes for easy comparison
+- **Short Links** — Each file gets an auto-generated 8-character short link (`/s/xxxxxxxx`)
+- **File Management** — Rename, delete, download, toggle public/private — simple and intuitive
+- **Drag & Drop Upload** — Click or drag to upload, up to 50MB per file
+- **Version History** — Overwrite uploads automatically preserve previous versions; rollback anytime
+- **Responsive Design** — Adapts to desktop and mobile; dark mode follows system preference
+
+### Organization
+
+- **Tags** — Tag files for multi-dimensional categorization and search
+- **Categories** — Organize files into categories for clear hierarchy
+- **Favorites** — One-click bookmark for quick access to frequently used files
+
+### Security & Permissions
+
+- **Multi-user Support** — Admin can create and manage multiple users; regular users can only access their own files and public files
+- **Open Registration** — Enable self-service registration via `ALLOW_REGISTRATION=true`, with optional SMTP email verification
+- **Session Auth** — Cookie + bcrypt password hashing
+- **API Tokens** — Each user can create multiple API tokens for scripts and AI tools
+- **Public/Private Files** — Toggle visibility on upload; private files are only accessible to the owner and admin
+- **Rate Limiting** — Login and upload endpoints are rate-limited to prevent brute force and abuse
+
+### AI Integration
+
+- **MCP Protocol** — Built-in MCP Streamable HTTP endpoint for direct AI tool integration
+- **Skills Management** — Auto-discovers Claude Code/Desktop skill packs in the `skills/` directory
+- **JSON Upload API** — `/api/files/upload-json` for programmatic uploads, ideal for AI workflows
+
+### Deployment
+
+- **Zero-Dependency Runtime** — Single container startup with built-in SQLite storage
+- **Docker One-Click Deploy** — Multi-stage build, env var configuration, volume persistence
+- **Database Migrations** — Automatic schema migration on startup; no manual upgrades needed
+
+## Tech Stack
+
+- **Backend**: Node.js + Express + express-session (SQLite session store), domain-split Router architecture (routes/ + lib/ shared layer)
+- **Database**: SQLite3 (zero-config, auto-migration)
+- **Frontend**: Vanilla JavaScript (no framework dependencies)
+- **Rendering**: marked.js + highlight.js + KaTeX + Mermaid
+- **Security**: helmet + layered CSP (strict policy for admin UI, iframe sandbox isolation + content-tiered CSP for render pages)
+- **Protocol**: MCP Streamable HTTP (@modelcontextprotocol/sdk)
+- **Testing**: node:test + supertest (unit + integration), GitHub Actions CI
+- **Container**: Docker / Docker Compose
+
+## Quick Start
+
+### Docker Deploy (Recommended)
+
+```bash
+git clone https://github.com/code2rich/jpage.git
+cd jpage
+cp .env.example .env       # Edit .env with ADMIN_PASSWORD and SESSION_SECRET
+docker-compose up -d
+```
+
+Visit http://localhost:8858 — you'll be redirected to the login page.
+
+### Local Development
+
+```bash
+npm install
+ADMIN_USER=admin ADMIN_PASSWORD=test1234 SESSION_SECRET=dev-secret npm start
+```
+
+Development mode (hot reload):
+
+```bash
+npm run dev
+```
+
+### Development & Testing
+
+```bash
+npm test            # Unit + integration tests (node:test + supertest)
+npm run test:unit   # Unit tests only
+npm run build       # Build frontend bundle (esbuild → public/dist)
+```
+
+End-to-end / benchmarks (start the server first with `npm start`):
+
+```bash
+node test/perf-harness.js 8858   # Core e2e (login/upload/render/short-link/tags)
+node test/mcp-harness.js 8858    # MCP endpoint
+node test/perf-bench.js 8858     # Render/list/cache latency benchmarks
+```
+
+## Auth & Security
+
+jpage supports a multi-user system. Admin manages all users and files; regular users can only access their own files and public files. Share links (`/api/files/:id/render`, `/s/:key`, download, source) are anonymously accessible when the file is marked public. Uncheck "Public access" on upload to make the file visible only to the owner and admin.
+
+**Content Security (CSP)**: Hardened via helmet + layered policies — the admin UI gets a strict CSP (same-origin scripts only); user-content render pages are isolated by iframe sandbox (without `allow-same-origin`, blocking access to the parent window). Markdown pages use a strict CSP (inline mermaid init script whitelisted via nonce), while HTML pages use a relaxed CSP + sandbox fallback (user HTML often contains legitimate scripts).
+
+### Authentication Methods
+
+API and MCP endpoints support three authentication methods:
+
+1. **Session Cookie** — `jpage.sid` cookie after login, for browser access
+2. **API Token** — User-created `jp_` prefixed tokens, for script integration
+3. **MCP Token** — `MCP_TOKEN` environment variable, for AI tool connections (backward compatible)
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ADMIN_USER` | No | Admin username for first startup when users table is empty; defaults to `admin` |
+| `ADMIN_PASSWORD` | No | Admin password for first startup (≥8 chars); if empty, a random 16-char password is generated and printed to startup logs |
+| `SESSION_SECRET` | Prod | Encrypts session cookies; in dev mode a temporary key is auto-generated (lost on restart) |
+| `NODE_ENV` | No | When `production`, cookies are sent only over HTTPS; missing SESSION_SECRET will refuse to start |
+| `PORT` | No | Default `8858` |
+| `MCP_TOKEN` | No | Global Bearer token for the `/mcp` endpoint (backward compatible); when unset, `/mcp` is still accessible via a user-level API token (`jp_` prefix) |
+| `ALLOW_REGISTRATION` | No | Set to `true` to enable self-service registration; defaults to off (admin-only user creation) |
+| `SMTP_HOST` | No | SMTP server address (e.g. `smtp.qq.com`); enables email verification when configured |
+| `SMTP_PORT` | No | SMTP port (e.g. `465`) |
+| `SMTP_SECURE` | No | Use SSL (`true`/`false`) |
+| `SMTP_USER` | No | SMTP login username |
+| `SMTP_PASS` | No | SMTP login password or authorization code |
+| `SMTP_FROM` | No | Sender address (e.g. `"jpage <user@example.com>"`) |
+| `APP_URL` | No | External app URL used to build verification links (e.g. `https://jpage.cn`) |
+
+If both `ADMIN_USER` and `ADMIN_PASSWORD` are left empty, the startup log will output:
+
+```
+[jpage] Created initial admin: admin
+[jpage] Initial password (save this): 7Hk2mN9pq4rTv8wX
+[jpage] ⚠️  Please change the password after first login
+```
+
+Copy the password from the log to log in.
+
+Recommended `SESSION_SECRET` generation:
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+### Reset or Change Password
+
+All users can change their password in Settings after login. Admin can reset other users' passwords in User Management.
+
+Manual method (SQLite command line):
+
+```bash
+node -e "console.log(require('bcryptjs').hashSync('new-password', 10))"
+sqlite3 data/database.sqlite "UPDATE users SET password_hash='<hash-from-above>' WHERE username='admin';"
+```
+
+## Project Structure
+
+```
+jpage/
+├── server.js           # Entry: app assembly + middleware + startup orchestration (logic split out)
+├── routes/             # Domain-split Express Routers
+│   ├── auth.js         # Login/register/email verification
+│   ├── users.js        # User management (admin)
+│   ├── tokens.js       # API tokens
+│   ├── files.js        # File CRUD/upload/render/versions/tags/star/stats
+│   ├── tags.js         # Tags
+│   ├── categories.js   # Categories + template metadata
+│   ├── content-templates.js  # Content template marketplace
+│   ├── admin.js        # Backup export/import/stats
+│   └── skills.js       # Skills + MCP config
+├── lib/                # Shared layer (reused by routes)
+│   ├── db.js           # SQLite access (dbRun/dbGet/dbAll + PRAGMA)
+│   ├── paths.js        # Data/upload dir constants
+│   ├── util.js         # now/shareKey/clientIp/decodeFilename pure helpers
+│   ├── csp.js          # Layered CSP policies + nonce
+│   ├── auth-state.js   # Shared adminUserId state
+│   ├── templates.js    # Template system + marked/hljs/KaTeX pipeline
+│   ├── render.js       # File → HTML rendering (with CSP headers)
+│   ├── render-cache.js # Render result LRU cache
+│   ├── fts.js          # FTS5 full-text index
+│   ├── categories.js   # Category name in-memory cache
+│   ├── view-counts.js  # Buffered view-count batched flush
+│   ├── zip.js          # ZIP upload (security validation/extraction/classification)
+│   ├── dispatch.js     # MCP in-process request dispatch (bypass TCP self-call)
+│   └── middleware/     # Auth + file-loading middleware
+├── logger.js           # Structured JSON Lines logger
+├── mailer.js           # SMTP mail (verification codes/links)
+├── mcp-server.js       # MCP Streamable HTTP endpoint (/mcp)
+├── migrations.js       # Database migration runner
+├── migrations/         # Sequential schema migrations (001-012)
+├── skills-registry.js  # Scans skills/ dir, provides skill list/details/zip packaging
+├── templates/          # Markdown render style templates (default/github/academic/dark-pro)
+├── package.json
+├── build.js            # esbuild bundles frontend → public/dist
+├── Dockerfile
+├── docker-compose.yml
+├── .env.example        # Environment variable template
+├── .mcp.json           # MCP client config example
+├── docs/
+│   ├── api.md          # Complete REST API reference
+│   └── design/         # Design documents
+├── skills/
+│   └── jpage-upload/   # Claude Code / Desktop skill
+│       └── SKILL.md
+├── test/               # Unit + integration tests (node:test + supertest) + e2e harness
+├── data/               # SQLite databases, uploaded files & sessions (auto-created)
+└── public/             # Frontend static assets
+    ├── index.html
+    ├── css/style.css
+    ├── js/             # Page-split ES modules
+    └── dist/           # Build output (npm run build, git-ignored)
+```
+
+## REST API
+
+Port `8858` (overridable via `PORT`). All write endpoints require login or Bearer token.
+
+### Auth
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/auth/me` | GET | Current login info |
+| `/api/auth/login` | POST | Login (`{username, password}`) |
+| `/api/auth/register` | POST | Register (requires `ALLOW_REGISTRATION=true`) |
+| `/api/auth/logout` | POST | Logout |
+| `/api/auth/change-password` | POST | Change password (all users) |
+
+### User Management (Admin only)
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/users` | GET | List all users |
+| `/api/users` | POST | Create user |
+| `/api/users/:id` | PUT | Update role or reset password |
+| `/api/users/:id` | DELETE | Delete user; files transfer to admin |
+
+### API Tokens
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/tokens` | GET | List own tokens |
+| `/api/tokens` | POST | Create token (plaintext returned once only) |
+| `/api/tokens/:id` | DELETE | Delete token |
+
+### File Management
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/files` | GET | List files (admin sees all; users see own + public) |
+| `/api/files/upload` | POST | Multipart upload |
+| `/api/files/upload-json` | POST | JSON upload (`{name, content, isPublic?}`) |
+| `/api/files/:id` | PUT | Rename or toggle public/private |
+| `/api/files/:id` | DELETE | Delete file |
+| `/api/files/:id/content` | GET | Return raw text |
+| `/api/files/:id/render` | GET | Return rendered HTML |
+| `/api/files/:id/download` | GET | Stream download file |
+| `/s/:key` | GET | Short link page render |
+
+### Tags
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/tags` | GET | List all tags (with file_count) |
+| `/api/tags` | POST | Create tag |
+| `/api/tags/:id` | DELETE | Delete tag |
+| `/api/files/:id/tags` | PUT | Replace file's tag list |
+
+### Favorites
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/files/:id/star` | POST | Favorite file |
+| `/api/files/:id/star` | DELETE | Unfavorite file |
+
+### Categories
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/categories` | GET | List categories (with file_count) |
+| `/api/categories` | POST | Create category |
+| `/api/categories/:id` | PUT | Rename category |
+| `/api/categories/:id` | DELETE | Delete category |
+| `/api/files/:id/category` | PUT | Set file category |
+
+### Skills
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/skills` | GET | List installed skill packs |
+| `/api/skills/:name` | GET | Skill details |
+| `/api/skills/:name/download` | GET | ZIP download of skill directory |
+
+Full API documentation: [docs/api.md](docs/api.md).
+
+## MCP / AI Integration
+
+jpage includes a built-in [MCP Streamable HTTP](https://modelcontextprotocol.io) endpoint, enabling AI tools like Claude Code and Claude Desktop to directly upload and manage files.
+
+### Enable
+
+Set the `MCP_TOKEN` environment variable:
+
+```bash
+MCP_TOKEN=your-secret-token
+```
+
+### Client Configuration
+
+**Claude Code** — Add to your project's `.mcp.json` or merge into `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "jpage": {
+      "type": "http",
+      "url": "http://localhost:8858/mcp",
+      "headers": {
+        "Authorization": "Bearer ${env.MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** — Merge the `mcpServers` block into `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+### Capabilities
+
+**Tools** (15):
+
+| Tool | Purpose |
+|---|---|
+| `upload_file` | Upload HTML or Markdown, return preview link |
+| `list_files` | List all files |
+| `get_file_content` | Read file content |
+| `get_file_url` | Get file preview URL |
+| `rename_file` | Rename file |
+| `delete_file` | Delete file |
+| `list_file_versions` | View file version history |
+| `restore_file_version` | Rollback to specified version |
+| `list_tags` | List tags |
+| `add_tags_to_file` | Add tags to file |
+| `star_file` | Favorite file |
+| `unstar_file` | Unfavorite file |
+| `list_categories` | List categories |
+| `create_category` | Create category |
+| `set_file_category` | Set file category |
+
+**Resources** (2):
+
+| URI | Description |
+|---|---|
+| `jpage://files` | All file metadata (JSON list) |
+| `jpage://file/{id}` | Single file content (≤ 256KB) |
+
+### Companion Skill
+
+The repo includes `skills/jpage-upload/SKILL.md`, a ready-to-use skill for Claude Code / Desktop. Once installed, AI-generated HTML, Markdown, reports, and visualizations are automatically uploaded to jpage with a preview link.
+
+```bash
+ln -s "$(pwd)/skills/jpage-upload" ~/.claude/skills/jpage-upload
+```
+
+### Web Management
+
+After login, the homepage bottom section shows an **AI Skills** block where you can view details and download zip packages. Add new skills by creating `skills/<name>/SKILL.md` with YAML frontmatter — the service auto-discovers them on restart.
+
+### Debug
+
+```bash
+npx -y @modelcontextprotocol/inspector http://localhost:8858/mcp
+```
+
+## Use Cases
+
+- **AI Content Sharing** — One-click upload of HTML reports and visualizations generated by Claude Code, Cursor, and similar tools
+- **Technical Documentation** — Markdown notes, meeting minutes, project reports with auto-rendered code highlighting, math formulas, and diagrams
+- **Static Page Hosting** — Single-page HTML demos, prototypes, landing pages — no server configuration needed
+- **Temporary File Sharing** — Any HTML/Markdown file, drag and drop to get a link — no account required
+- **Version Management** — Iterative document updates automatically preserve history; rollback anytime
+
+## Why
+
+Existing solutions are either too heavy (requiring server setup, domains, CI) or too closed (locked to specific platforms).
+
+jpage does one thing: make static content sharing simple again. Drop a file, get a link. An optional multi-user system exists, but the default is zero-friction — drop a file to get a link, share public files anonymously without registering.
+
+## License
+
+MIT

package/bin/args.js

@@ -0,0 +1,64 @@
+// 零依赖 argv 解析器。
+//
+// 约定：
+//   - 以 `--` 开头的 token 是选项（长选项）；支持 `--key value` 和 `--key=value` 两种形式
+//   - 不支持单字母组合短选项（-a），避免歧义；单字母需求用长选项
+//   - 布尔标志：出现即为 true（如 --public）。需要显式值时用 --key=value
+//   - 其余 token 是位置参数（positional）
+//   - 第一个位置参数视作命令（cmd），第二个视作子命令（sub）
+//
+// 返回：{ cmd, sub, opts, positional }
+//   cmd        第一个位置参数（字符串，无则 null）
+//   sub        第二个位置参数（字符串，无则 null）
+//   opts       选项对象（键名去掉 -- 前缀，值默认 true，否则字符串）
+//   positional 全部位置参数数组（含 cmd/sub）
+//
+// 设计目标：够用、可预测、无运行时依赖。commander 级别的复杂场景（子命令嵌套、
+// 变长参数类型校验）超出 CLI 需求，故不引入。
+
+function parse(argv) {
+  const opts = {};
+  const positional = [];
+  let cmd = null;
+  let sub = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+
+    if (tok === '--') {
+      // 之后的全部当位置参数
+      for (let j = i + 1; j < argv.length; j++) positional.push(argv[j]);
+      break;
+    }
+
+    if (tok.startsWith('--')) {
+      const eq = tok.indexOf('=');
+      if (eq > 1) {
+        // --key=value
+        const key = tok.slice(2, eq);
+        const value = tok.slice(eq + 1);
+        opts[key] = value;
+      } else {
+        const key = tok.slice(2);
+        const next = argv[i + 1];
+        // 下一个 token 不是选项（且存在）→ 当作值；否则当布尔标志
+        if (next !== undefined && !next.startsWith('--')) {
+          opts[key] = next;
+          i++;
+        } else {
+          opts[key] = true;
+        }
+      }
+      continue;
+    }
+
+    positional.push(tok);
+  }
+
+  if (positional.length >= 1) cmd = positional[0];
+  if (positional.length >= 2) sub = positional[1];
+
+  return { cmd, sub, opts, positional };
+}
+
+module.exports = { parse };

package/bin/client.js

@@ -0,0 +1,93 @@
+// CLI HTTP 客户端：基于全局 fetch 的薄封装，统一鉴权与错误处理。
+//
+// 接口形：{ get, post, postForm, put, del }，path 以 /api/... 开头。
+// 非预期 JSON（如下载二进制）用 raw(path, init) 拿原始 Response。
+//
+// 测试注入：createClient 接受可选 fetchImpl 参数。集成测试注入一个打到 supertest
+// app 的 fetch shim，避免起真实 TCP 端口（项目既有测试都是 in-process 模式）。
+//
+// 与 lib/dispatch.js 的区别：dispatch 是「服务端进程内直调」（绕过 TCP），
+// 本文件是「客户端经网络调」（真 fetch），两者职责正交。
+
+// 请求失败的统一错误类型。带 status + 可读 message，命令层据此决定退出码与提示。
+class HttpError extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.name = 'HttpError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * 创建 API 客户端。
+ * @param {object} opts
+ * @param {string} opts.base - 服务地址（如 http://localhost:8858），无尾斜杠
+ * @param {string} [opts.token] - Bearer token；为空时不发 Authorization 头
+ * @param {function} [opts.fetchImpl] - 可选 fetch 实现（测试注入）
+ * @returns {object}
+ */
+function createClient({ base, token, fetchImpl } = {}) {
+  const f = fetchImpl || fetch;
+
+  async function raw(path, init = {}) {
+    const url = base + path;
+    const headers = { ...(init.headers || {}) };
+    if (token) headers.Authorization = 'Bearer ' + token;
+
+    let res;
+    try {
+      res = await f(url, { ...init, headers });
+    } catch (e) {
+      // 网络层错误（ECONNREFUSED / DNS / 超时）→ 包装成可识别错误
+      const err = new Error(`无法连接到 ${base}：${e.message}`);
+      err.name = 'NetworkError';
+      err.cause = e;
+      throw err;
+    }
+    return res;
+  }
+
+  // JSON 请求：发 JSON body，期望 JSON 响应。失败抛 HttpError。
+  async function json(method, path, body) {
+    const init = { method };
+    if (body !== undefined) {
+      init.headers = { 'content-type': 'application/json' };
+      init.body = JSON.stringify(body);
+    }
+    const res = await raw(path, init);
+    return parseJson(res, method, path);
+  }
+
+  async function parseJson(res, method, path) {
+    const text = await res.text();
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = { raw: text };
+      }
+    }
+    if (res.status < 200 || res.status >= 300) {
+      const msg = (data && data.error) || `HTTP ${res.status}`;
+      throw new HttpError(res.status, `REST ${method} ${path} -> ${res.status} ${msg}`, data);
+    }
+    return data;
+  }
+
+  return {
+    raw,
+    get: (p) => json('GET', p),
+    post: (p, body) => json('POST', p, body),
+    put: (p, body) => json('PUT', p, body),
+    del: (p) => json('DELETE', p),
+    // multipart：调用方传已构造好的 FormData
+    postForm: async (p, formData) => {
+      const res = await raw(p, { method: 'POST', body: formData });
+      return parseJson(res, 'POST', p);
+    },
+  };
+}
+
+module.exports = { createClient, HttpError };

package/bin/commands/_shared.js

@@ -0,0 +1,54 @@
+// 命令间共享的输出辅助函数。
+//
+// 设计：命令模块只做「调 API + 格式化输出」，错误码由 bin/jpage.js 统一处理。
+// 这里集中放格式化工具（人类可读的字节/时间、表格），避免命令文件互相重复。
+//
+// I/O 注入：out()/err() 默认写 process.stdout/stderr，但 run() 可通过 setIo()
+// 注入自定义流（测试用），这样测试捕获输出时不必 monkeypatch process.stdout
+// （那会破坏 node:test 自身的 TAP 输出）。
+
+let _stdout = process.stdout;
+let _stderr = process.stderr;
+
+function setIo({ stdout, stderr } = {}) {
+  if (stdout) _stdout = stdout;
+  if (stderr) _stderr = stderr;
+}
+
+function resetIo() {
+  _stdout = process.stdout;
+  _stderr = process.stderr;
+}
+
+// 写一行到 stdout（自动补换行）。
+function out(s) {
+  _stdout.write(s);
+}
+// 写一行到 stderr。
+function err(s) {
+  _stderr.write(s);
+}
+
+// 字节 → 人类可读（B / KB / MB）。
+function formatSize(bytes) {
+  if (bytes == null) return '-';
+  const n = Number(bytes);
+  if (!isFinite(n)) return '-';
+  if (n < 1024) return n + 'B';
+  if (n < 1024 * 1024) return (n / 1024).toFixed(1) + 'K';
+  return (n / 1024 / 1024).toFixed(1) + 'M';
+}
+
+// ISO/SQLite 时间 → 简短显示。原样返回无法解析的输入。
+function formatTime(t) {
+  if (!t) return '-';
+  return String(t).replace('T', ' ').replace(/\.\d+$/, '');
+}
+
+// 从文件元数据拼预览 URL：优先 /s/:key，无私有短链时返回 null。
+function shareUrl(base, file) {
+  if (!file || !file.share_key) return null;
+  return `${base}/s/${file.share_key}`;
+}
+
+module.exports = { setIo, resetIo, out, err, formatSize, formatTime, shareUrl };

package/bin/commands/cat.js

@@ -0,0 +1,23 @@
+// cat 命令：输出文件原始内容到 stdout。
+// 后端：GET /api/files/:id/content（owner/admin 限定）。
+// bundle（is_bundle=1）不支持取「整个内容」，后端会返回入口文件内容，此处原样输出。
+
+const { out } = require('./_shared');
+
+async function run(client, args) {
+  const id = args.sub;
+  if (!id) {
+    const e = new Error('用法：jpage cat <id>');
+    e.name = 'UsageError';
+    throw e;
+  }
+  const data = await client.get(`/api/files/${id}/content`);
+  if (typeof data.content === 'string') {
+    out(data.content);
+    if (!data.content.endsWith('\n')) out('\n');
+  } else {
+    out(JSON.stringify(data, null, 2) + '\n');
+  }
+}
+
+module.exports = { run };

package/bin/commands/ls.js

@@ -0,0 +1,44 @@
+// ls 命令：列出文件。
+// 后端：GET /api/files（支持 page/limit/sort/order/keyword/category/tag）。
+
+const { formatSize, formatTime, out } = require('./_shared');
+
+async function run(client, args) {
+  const o = args.opts;
+  const params = new URLSearchParams();
+  if (o.page) params.set('page', o.page);
+  if (o.limit) params.set('limit', o.limit);
+  if (o.sort) params.set('sort', o.sort);
+  if (o.order) params.set('order', o.order);
+  if (o.kw || o.keyword) params.set('keyword', o.kw || o.keyword);
+  if (o.cat || o.category) params.set('category', o.cat || o.category);
+  if (o.tag) params.set('tag', o.tag);
+  const qs = params.toString();
+
+  const data = await client.get('/api/files' + (qs ? '?' + qs : ''));
+  const files = data.files || [];
+  const pg = data.pagination || {};
+
+  if (files.length === 0) {
+    out('（无文件）\n');
+    return;
+  }
+
+  // 对齐表格：id / 类型 / 公开 / 大小 / 更新时间 / 文件名 / 标签
+  for (const f of files) {
+    const pub = f.is_public ? 'pub' : 'pri';
+    const tags = (f.tags || []).map((t) => t.name).join(',');
+    const bundle = f.is_bundle ? ' 📦' : '';
+    out(
+      `#${f.id}  [${f.file_type || '?'} ${pub}]  ${formatSize(f.size).padEnd(7)}  ` +
+        `${formatTime(f.updated_at)}  ${f.original_name}${bundle}` +
+        (tags ? `  {${tags}}` : '') +
+        '\n'
+    );
+  }
+  out(
+    `\n第 ${pg.page || 1} / ${pg.totalPages || 1} 页，共 ${pg.total || files.length} 个\n`
+  );
+}
+
+module.exports = { run };