@hangox/mg-cli 1.0.0

package/src/shared/types.ts

@@ -0,0 +1,227 @@
+/**
+ * MG Plugin 类型定义
+ */
+
+import { ConnectionType, MessageType } from './constants.js'
+import { ErrorCode } from './errors.js'
+
+// ==================== Server 信息 ====================
+
+/** Server 运行信息 */
+export interface ServerInfo {
+  /** 监听端口 */
+  port: number
+  /** 进程 ID */
+  pid: number
+  /** 启动时间 (ISO 8601) */
+  startedAt: string
+}
+
+// ==================== WebSocket 消息 ====================
+
+/** 基础消息结构 */
+export interface BaseMessage {
+  /** 消息 ID */
+  id?: string
+  /** 消息类型 */
+  type: MessageType | string
+  /** 时间戳 */
+  timestamp?: number
+}
+
+/** 请求消息 */
+export interface RequestMessage extends BaseMessage {
+  /** 目标页面 URL（标准化后的） */
+  pageUrl?: string
+  /** 请求参数 */
+  params?: Record<string, unknown>
+}
+
+/** 响应消息 */
+export interface ResponseMessage extends BaseMessage {
+  /** 对应请求的 ID */
+  id: string
+  /** 是否成功 */
+  success: boolean
+  /** 成功时的数据 */
+  data?: unknown
+  /** 失败时的错误信息 */
+  error?: ErrorInfo | null
+}
+
+/** 错误信息 */
+export interface ErrorInfo {
+  /** 错误码 */
+  code: ErrorCode
+  /** 错误名称 */
+  name: string
+  /** 错误消息 */
+  message: string
+  /** 额外详情 */
+  details?: Record<string, unknown>
+}
+
+/** 注册消息 */
+export interface RegisterMessage extends BaseMessage {
+  type: 'register'
+  data: {
+    /** 连接类型 */
+    connectionType: ConnectionType
+    /** 页面 URL（Provider 必需） */
+    pageUrl?: string
+    /** 页面唯一 ID */
+    pageId?: string
+  }
+}
+
+/** 心跳消息 */
+export interface PingMessage extends BaseMessage {
+  type: 'ping'
+  timestamp: number
+}
+
+export interface PongMessage extends BaseMessage {
+  type: 'pong'
+  timestamp: number
+}
+
+// ==================== 连接管理 ====================
+
+/** 连接信息 */
+export interface ConnectionInfo {
+  /** 连接 ID */
+  id: string
+  /** 连接类型 */
+  type: ConnectionType
+  /** 页面 URL（仅 Provider） */
+  pageUrl?: string
+  /** 页面 ID（仅 Provider） */
+  pageId?: string
+  /** 连接时间 */
+  connectedAt: Date
+  /** 最后活跃时间 */
+  lastActiveAt: Date
+}
+
+// ==================== 节点相关 ====================
+
+/** 节点信息（简化版） */
+export interface NodeInfo {
+  /** 节点 ID */
+  id: string
+  /** 节点名称 */
+  name: string
+  /** 节点类型 */
+  type: string
+  /** 是否可见 */
+  visible: boolean
+  /** X 坐标 */
+  x?: number
+  /** Y 坐标 */
+  y?: number
+  /** 宽度 */
+  width?: number
+  /** 高度 */
+  height?: number
+  /** 子节点 */
+  children?: NodeInfo[]
+  /** 其他属性 */
+  [key: string]: unknown
+}
+
+/** 获取节点参数 */
+export interface GetNodeParams {
+  /** 节点 ID */
+  nodeId: string
+  /** 遍历深度 */
+  maxDepth?: number
+  /** 是否包含不可见节点 */
+  includeInvisible?: boolean
+  /** 索引签名 */
+  [key: string]: unknown
+}
+
+/** 获取所有节点参数 */
+export interface GetAllNodesParams {
+  /** 遍历深度 */
+  maxDepth?: number
+  /** 是否包含不可见节点 */
+  includeInvisible?: boolean
+  /** 索引签名 */
+  [key: string]: unknown
+}
+
+/** 导出图片参数 */
+export interface ExportImageParams {
+  /** 节点 ID（可选，默认第一个选中节点） */
+  nodeId?: string
+  /** 导出格式 */
+  format?: 'PNG' | 'JPG' | 'SVG' | 'PDF' | 'WEBP'
+  /** 缩放倍率 */
+  scale?: number
+  /** 固定宽度 */
+  width?: number
+  /** 固定高度 */
+  height?: number
+  /** 是否使用完整尺寸 */
+  useAbsoluteBounds?: boolean
+  /** 是否包含特效和外描边 */
+  useRenderBounds?: boolean
+}
+
+// ==================== CLI 相关 ====================
+
+/** CLI 输出格式化函数类型 */
+export type OutputFormatter = (data: Record<string, unknown>) => void
+
+/** CLI 命令选项 */
+export interface CliOptions {
+  /** 输出文件路径 */
+  output?: string
+  /** 遍历深度 */
+  maxDepth?: number
+  /** 包含不可见节点 */
+  includeInvisible?: boolean
+  /** 禁用自动重试 */
+  noRetry?: boolean
+  /** 禁用自动启动 Server */
+  noAutoStart?: boolean
+  /** Server 端口 */
+  port?: number
+  /** 前台模式运行 */
+  foreground?: boolean
+}
+
+// ==================== 页面信息 ====================
+
+/** RGBA 颜色 */
+export interface RGBA {
+  r: number
+  g: number
+  b: number
+  a: number
+}
+
+/** 单个页面信息 */
+export interface MgPageInfo {
+  /** 页面 ID */
+  id: string
+  /** 页面名称 */
+  name: string
+  /** 页面背景色 */
+  bgColor?: RGBA
+  /** 直接子节点数量 */
+  childCount: number
+}
+
+/** 所有页面信息 */
+export interface AllPagesInfo {
+  /** 文档 ID */
+  documentId: string
+  /** 文档名称 */
+  documentName: string
+  /** 页面列表 */
+  pages: MgPageInfo[]
+  /** 页面总数 */
+  totalCount: number
+}

package/src/shared/utils.ts

@@ -0,0 +1,352 @@
+/**
+ * MG Plugin 工具函数
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { dirname, resolve, isAbsolute } from 'node:path'
+import { CONFIG_DIR, SERVER_INFO_FILE, LOG_DIR } from './constants.js'
+import type { ServerInfo } from './types.js'
+
+// ==================== 文件操作 ====================
+
+/**
+ * 确保目录存在
+ */
+export function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+/**
+ * 确保配置目录存在
+ */
+export function ensureConfigDir(): void {
+  ensureDir(CONFIG_DIR)
+  ensureDir(LOG_DIR)
+}
+
+/**
+ * 读取 Server 信息文件
+ */
+export function readServerInfo(): ServerInfo | null {
+  try {
+    if (!existsSync(SERVER_INFO_FILE)) {
+      return null
+    }
+    const content = readFileSync(SERVER_INFO_FILE, 'utf-8')
+    return JSON.parse(content) as ServerInfo
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 写入 Server 信息文件
+ */
+export function writeServerInfo(info: ServerInfo): void {
+  ensureConfigDir()
+  writeFileSync(SERVER_INFO_FILE, JSON.stringify(info, null, 2), 'utf-8')
+}
+
+/**
+ * 删除 Server 信息文件
+ */
+export function deleteServerInfo(): void {
+  try {
+    if (existsSync(SERVER_INFO_FILE)) {
+      unlinkSync(SERVER_INFO_FILE)
+    }
+  } catch {
+    // 忽略删除错误
+  }
+}
+
+/**
+ * 解析输出路径（支持相对路径和绝对路径）
+ */
+export function resolveOutputPath(outputPath: string): string {
+  if (isAbsolute(outputPath)) {
+    return outputPath
+  }
+  return resolve(process.cwd(), outputPath)
+}
+
+/**
+ * 确保输出路径的目录存在
+ */
+export function ensureOutputDir(outputPath: string): void {
+  const dir = dirname(outputPath)
+  ensureDir(dir)
+}
+
+// ==================== 进程管理 ====================
+
+/**
+ * 检查进程是否存在
+ */
+export function isProcessRunning(pid: number): boolean {
+  try {
+    // 发送信号 0 不会终止进程，但如果进程不存在会抛出错误
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 终止进程
+ */
+export function killProcess(pid: number): boolean {
+  try {
+    process.kill(pid, 'SIGTERM')
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ==================== URL 处理 ====================
+
+/**
+ * 标准化页面 URL
+ *
+ * 输入: https://mastergo.netease.com/file/174135798361888?fileOpenFrom=home&page_id=0%3A8347
+ * 输出: mastergo.netease.com/file/174135798361888
+ */
+export function normalizePageUrl(url: string): string {
+  try {
+    const urlObj = new URL(url)
+    // 返回 host + pathname，去掉 https:// 前缀和查询参数
+    return urlObj.host + urlObj.pathname
+  } catch {
+    // 如果已经是标准化的格式，直接返回
+    return url
+  }
+}
+
+/**
+ * 检查是否是设计页面 URL
+ */
+export function isDesignPageUrl(url: string): boolean {
+  // 匹配 /file/数字 格式
+  return /\/file\/\d+/.test(url)
+}
+
+/**
+ * 解析 mgp:// 链接
+ *
+ * 支持的格式 (queryParams 格式，nodeId 需要 URL 编码):
+ * - mgp://mastergo.netease.com/file/174135798361888?nodeId=123%3A456 (单个节点)
+ * - mgp://mastergo.netease.com/file/174135798361888?nodeId=0%3A8633&nodePath=314%3A13190%2F0%3A8633 (带父节点路径)
+ *
+ * 输出: { pageUrl: 'mastergo.netease.com/file/174135798361888', nodeId: '0:8633', nodePath: ['314:13190', '0:8633'] }
+ */
+export function parseMgpLink(link: string): { pageUrl: string; nodeId: string; nodePath?: string[] } | null {
+  // 检查是否是 mgp:// 协议
+  if (!link.startsWith('mgp://')) {
+    return null
+  }
+
+  try {
+    // 移除 mgp:// 前缀，构造为可解析的 URL
+    const urlPart = link.slice(6) // 移除 'mgp://'
+    const questionMarkIndex = urlPart.indexOf('?')
+
+    if (questionMarkIndex === -1) {
+      // 没有查询参数，无效格式
+      return null
+    }
+
+    const pageUrl = urlPart.slice(0, questionMarkIndex)
+    const queryString = urlPart.slice(questionMarkIndex + 1)
+
+    // 解析查询参数
+    const params = new URLSearchParams(queryString)
+    const encodedNodeId = params.get('nodeId')
+
+    if (!encodedNodeId) {
+      return null
+    }
+
+    // 解码 nodeId
+    const nodeId = decodeURIComponent(encodedNodeId)
+
+    // 验证 nodeId 格式：支持单个节点 (数字:数字) 或带路径的格式 (数字:数字/数字:数字/...)
+    if (!/^(\d+:\d+)(\/\d+:\d+)*$/.test(nodeId)) {
+      return null
+    }
+
+    // 解析可选的 nodePath
+    const encodedNodePath = params.get('nodePath')
+    let nodePath: string[] | undefined
+
+    if (encodedNodePath) {
+      const decodedNodePath = decodeURIComponent(encodedNodePath)
+      nodePath = decodedNodePath.split('/').filter(Boolean)
+      // 验证每个路径段的格式
+      if (!nodePath.every(segment => /^\d+:\d+$/.test(segment))) {
+        return null
+      }
+    }
+
+    return {
+      pageUrl,
+      nodeId,
+      nodePath,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 生成 mgp:// 链接
+ *
+ * @param pageUrl 页面 URL（会被标准化）
+ * @param nodeId 节点 ID（会被 URL 编码）
+ * @param nodePath 可选的父节点路径（会被 URL 编码）
+ */
+export function generateMgpLink(pageUrl: string, nodeId: string, nodePath?: string[]): string {
+  const normalizedUrl = normalizePageUrl(pageUrl)
+  const encodedNodeId = encodeURIComponent(nodeId)
+
+  let link = `mgp://${normalizedUrl}?nodeId=${encodedNodeId}`
+
+  if (nodePath && nodePath.length > 0) {
+    const encodedNodePath = encodeURIComponent(nodePath.join('/'))
+    link += `&nodePath=${encodedNodePath}`
+  }
+
+  return link
+}
+
+// ==================== 输出格式化 ====================
+
+/**
+ * 格式化文件大小
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} 字节`
+  }
+  const kb = bytes / 1024
+  if (kb < 1024) {
+    return `${kb.toFixed(2)} KB`
+  }
+  const mb = kb / 1024
+  return `${mb.toFixed(2)} MB`
+}
+
+/**
+ * 格式化时间间隔
+ */
+export function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+  const days = Math.floor(hours / 24)
+
+  if (days > 0) {
+    return `${days} 天 ${hours % 24} 小时`
+  }
+  if (hours > 0) {
+    return `${hours} 小时 ${minutes % 60} 分钟`
+  }
+  if (minutes > 0) {
+    return `${minutes} 分钟 ${seconds % 60} 秒`
+  }
+  return `${seconds} 秒`
+}
+
+/**
+ * 生成唯一 ID
+ */
+export function generateId(): string {
+  return `${Date.now()}_${Math.random().toString(36).substring(2, 9)}`
+}
+
+/**
+ * 获取当前时间的 ISO 格式字符串
+ */
+export function getCurrentISOTime(): string {
+  return new Date().toISOString()
+}
+
+/**
+ * 格式化日期时间用于日志
+ */
+export function formatLogTime(date: Date = new Date()): string {
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  const hours = String(date.getHours()).padStart(2, '0')
+  const minutes = String(date.getMinutes()).padStart(2, '0')
+  const seconds = String(date.getSeconds()).padStart(2, '0')
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`
+}
+
+// ==================== FileId 提取 ====================
+
+/**
+ * 从完整 URL 提取 fileId
+ * 
+ * 支持格式:
+ * - https://mastergo.netease.com/file/174875497054651?page_id=321%3A11979
+ * - mastergo.netease.com/file/174875497054651
+ * 
+ * @returns fileId 或 null
+ */
+export function extractFileIdFromUrl(url: string): string | null {
+  // 匹配 /file/数字 格式
+  const match = url.match(/\/file\/(\d+)/)
+  return match ? match[1] : null
+}
+
+/**
+ * 从 mgp:// 链接提取 fileId
+ * 
+ * 支持格式:
+ * - mgp://mastergo.netease.com/file/174875497054651?nodeId=xxx
+ * 
+ * @returns fileId 或 null
+ */
+export function extractFileIdFromMgpLink(link: string): string | null {
+  if (!link.startsWith('mgp://')) {
+    return null
+  }
+  return extractFileIdFromUrl(link)
+}
+
+/**
+ * 统一处理输入，提取 fileId
+ * 
+ * 支持三种输入格式:
+ * 1. 完整 URL: https://mastergo.netease.com/file/174875497054651?page_id=xxx
+ * 2. mgp 协议: mgp://mastergo.netease.com/file/174875497054651?nodeId=xxx
+ * 3. 纯 fileId: 174875497054651
+ * 
+ * @returns fileId 或 null
+ */
+export function extractFileId(input: string): string | null {
+  const trimmed = input.trim()
+  
+  // 1. 纯数字 fileId
+  if (/^\d+$/.test(trimmed)) {
+    return trimmed
+  }
+  
+  // 2. mgp:// 协议
+  if (trimmed.startsWith('mgp://')) {
+    return extractFileIdFromMgpLink(trimmed)
+  }
+  
+  // 3. 完整 URL (http:// 或 https://)
+  if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+    return extractFileIdFromUrl(trimmed)
+  }
+  
+  // 4. 尝试作为不带协议的 URL 解析
+  return extractFileIdFromUrl(trimmed)
+}

package/tests/unit/shared/constants.test.ts

@@ -0,0 +1,66 @@
+/**
+ * 常量测试
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  DEFAULT_PORT,
+  PORT_RANGE_START,
+  PORT_RANGE_END,
+  MAX_PORT_ATTEMPTS,
+  HEARTBEAT_INTERVAL,
+  HEARTBEAT_TIMEOUT,
+  ConnectionType,
+  MessageType,
+} from '../../../src/shared/constants.js'
+
+describe('端口配置', () => {
+  it('应该有正确的默认端口', () => {
+    expect(DEFAULT_PORT).toBe(9527)
+  })
+
+  it('应该有正确的端口范围', () => {
+    expect(PORT_RANGE_START).toBe(9527)
+    expect(PORT_RANGE_END).toBe(9536)
+  })
+
+  it('端口范围应该正好是 10 个', () => {
+    expect(PORT_RANGE_END - PORT_RANGE_START + 1).toBe(MAX_PORT_ATTEMPTS)
+  })
+})
+
+describe('心跳配置', () => {
+  it('应该有正确的心跳间隔', () => {
+    expect(HEARTBEAT_INTERVAL).toBe(30000) // 30 秒
+  })
+
+  it('应该有正确的心跳超时', () => {
+    expect(HEARTBEAT_TIMEOUT).toBe(90000) // 90 秒 = 3 次心跳
+  })
+
+  it('心跳超时应该是间隔的 3 倍', () => {
+    expect(HEARTBEAT_TIMEOUT).toBe(HEARTBEAT_INTERVAL * 3)
+  })
+})
+
+describe('ConnectionType', () => {
+  it('应该有 CONSUMER 和 PROVIDER 两种类型', () => {
+    expect(ConnectionType.CONSUMER).toBe('consumer')
+    expect(ConnectionType.PROVIDER).toBe('provider')
+  })
+})
+
+describe('MessageType', () => {
+  it('应该包含系统消息类型', () => {
+    expect(MessageType.PING).toBe('ping')
+    expect(MessageType.PONG).toBe('pong')
+    expect(MessageType.REGISTER).toBe('register')
+  })
+
+  it('应该包含业务消息类型', () => {
+    expect(MessageType.GET_NODE_BY_ID).toBe('get_node_by_id')
+    expect(MessageType.GET_ALL_NODES).toBe('get_all_nodes')
+    expect(MessageType.EXPORT_IMAGE).toBe('export_image')
+    expect(MessageType.EXECUTE_CODE).toBe('execute_code')
+  })
+})