minecraft-dev-starter 0.0.0-stage → 0.1.1

package/src/client/LogTab.js

@@ -0,0 +1,180 @@
+/**
+ * 右侧栏「运行日志」标签：按时间列出这个工作区跑过的实例，默认最新一条。
+ *
+ * 日志本体在宿主侧已经按行解码（UTF-8 / GBK 回退），这里只负责展示与跟随。
+ * @module minecraft-dev-starter/client/LogTab
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import { call } from './api.js'
+import { h } from './h.js'
+import { IconRefresh, IconWarning } from './icons.js'
+import { launchStatusText, pickLogTarget } from './selection.js'
+import { Skeleton } from './Skeleton.js'
+import { loadLaunches, selectedProject, useLaunches } from './state.js'
+
+/** 关掉标签再打开时，尽量回到上次看的那条。 */
+let lastLogId
+
+export function LogTab() {
+  const launches = useLaunches(1500)
+  const project = selectedProject()
+  const [logId, setLogId] = useState(/** @type {string | undefined} */ (lastLogId))
+  const [log, setLog] = useState(/** @type {any} */ (undefined))
+  const [follow, setFollow] = useState(true)
+  const [pinned, setPinned] = useState(false)
+  const body = useRef(/** @type {HTMLPreElement | null} */ (null))
+
+  // 历史按当前工程过滤；工程还没识别出来时退回全部
+  const projectRoot = project === undefined ? undefined : String(project.root).toLowerCase()
+  const scoped = launches.list.filter((entry) => projectRoot === undefined || String(entry.root).toLowerCase() === projectRoot)
+  const history = scoped.length > 0 ? scoped : launches.list
+
+  // 跟随：有实例在跑就跟它；用户手动选过就保持；否则跟当前/最新
+  const target = pickLogTarget(history, logId, pinned)
+  useEffect(() => {
+    if (target === undefined || target === logId) return
+    lastLogId = target
+    setLogId(target)
+    setLog(undefined)
+    // 新实例跑起来时解除手动固定
+    if (history.some((entry) => entry.id === target && (entry.status === 'starting' || entry.status === 'running'))) {
+      setPinned(false)
+    }
+  }, [target, logId, history])
+
+  // 拉日志：运行中的实例每 1.5s 刷一次，结束的不再轮询
+  useEffect(() => {
+    if (logId === undefined) {
+      setLog(undefined)
+      return undefined
+    }
+    let cancelled = false
+    const pull = async () => {
+      try {
+        const result = await call('launch.logs', { id: logId, offset: 0, limit: 800 })
+        if (!cancelled) setLog(result)
+      } catch (error) {
+        if (!cancelled) setLog({ error: error instanceof Error ? error.message : String(error) })
+      }
+    }
+    void pull()
+    const timer = setInterval(() => {
+      if (log?.status === 'starting' || log?.status === 'running' || log === undefined) void pull()
+    }, 1500)
+    return () => {
+      cancelled = true
+      clearInterval(timer)
+    }
+  }, [logId, log?.status])
+
+  // 跟随尾部
+  useEffect(() => {
+    if (!follow) return
+    const element = body.current
+    if (element !== null) element.scrollTop = element.scrollHeight
+  }, [log?.lines?.length, follow])
+
+  if (history.length === 0) {
+    return h(
+      'div',
+      { className: 'mcdev-detail' },
+      h('div', { className: 'mcdev-title' }, '运行日志'),
+      h('div', { className: 'mcdev-muted', style: { marginTop: 8 } }, '还没有运行记录。用标题栏胶囊的 ▶ 启动一次。'),
+    )
+  }
+
+  const running = log?.status === 'starting' || log?.status === 'running'
+  const tone =
+    log?.error !== undefined
+      ? 'error'
+      : running
+        ? (log?.status === 'starting' ? 'warn' : 'ok')
+        : log?.outcome === 'normal'
+          ? 'idle'
+          : 'error'
+
+  return h(
+    'div',
+    { className: 'mcdev-logtab' },
+    h(
+      'div',
+      { className: 'mcdev-log-head' },
+      h(
+        'select',
+        {
+          className: 'mcdev-select',
+          value: logId ?? '',
+          onChange: (event) => {
+            // 手动选过就固定住，等下一次有新实例跑起来再自动跟随
+            setPinned(true)
+            lastLogId = event.target.value
+            setLogId(event.target.value)
+            setLog(undefined)
+          },
+        },
+        history.map((entry) => h('option', { key: entry.id, value: entry.id }, optionLabel(entry))),
+      ),
+      h('span', { className: 'mcdev-dot', 'data-state': tone }),
+      h('span', { className: 'mcdev-hint' }, statusText(log, running)),
+      h(
+        'label',
+        { className: 'mcdev-follow' },
+        h('input', { type: 'checkbox', checked: follow, onChange: (event) => setFollow(event.target.checked) }),
+        '跟随',
+      ),
+    ),
+    log?.diagnosis === undefined
+      ? undefined
+      : h(
+          'div',
+          { className: 'mcdev-diagnosis' },
+          h(
+            'div',
+            { className: 'mcdev-diagnosis-hint mcdev-icon-text' },
+            h('span', { className: 'mcdev-icon' }, h(IconWarning, undefined)),
+            log.diagnosis.hint,
+          ),
+          h('div', { className: 'mcdev-hint mcdev-code' }, log.diagnosis.line),
+        ),
+    log?.error === undefined
+      ? log === undefined && running
+        ? h(Skeleton, { rows: 4, hint: '正在读取日志…' })
+        : h('pre', { ref: body, className: 'mcdev-logs mcdev-logs-full' }, (log?.lines ?? []).join('\n') || '（还没有输出）')
+      : h('div', { className: 'mcdev-error', style: { marginTop: 8 } }, log.error),
+    h(
+      'div',
+      { style: { marginTop: 8 } },
+      h(
+        'button',
+        { type: 'button', className: 'mcdev-mini', onClick: () => void loadLaunches() },
+        h('span', { className: 'mcdev-icon' }, h(IconRefresh, { size: 12 })),
+        '刷新实例列表',
+      ),
+    ),
+  )
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @returns {string}
+ */
+function optionLabel(entry) {
+  const time = new Date(entry.startedAt)
+  const clock = Number.isNaN(time.getTime())
+    ? '--:--'
+    : `${String(time.getHours()).padStart(2, '0')}:${String(time.getMinutes()).padStart(2, '0')}`
+  const mark = entry.status === 'running' || entry.status === 'starting' ? '●' : entry.outcome === 'normal' ? '○' : '✕'
+  return `${mark} ${entry.label} · ${clock} · ${launchStatusText(entry)}`
+}
+
+/**
+ * @param {any} log
+ * @param {boolean} running
+ * @returns {string}
+ */
+function statusText(log, running) {
+  if (log === undefined) return '加载中…'
+  void running
+  return launchStatusText({ status: log.status, outcome: log.outcome, exitCode: log.exitCode })
+}

package/src/client/Skeleton.js

@@ -0,0 +1,18 @@
+/**
+ * 骨架占位：扫描或加载中时给几行灰条，避免面板一片空白。
+ * @module minecraft-dev-starter/client/Skeleton
+ */
+
+import { h } from './h.js'
+
+/**
+ * @param {{ rows?: number, hint?: string }} [props]
+ */
+export function Skeleton({ rows = 3, hint } = {}) {
+  return h(
+    'div',
+    { className: 'mcdev-skeleton', 'aria-busy': 'true' },
+    Array.from({ length: rows }, (_value, index) => h('div', { key: index, className: 'mcdev-skeleton-row' })),
+    hint === undefined ? undefined : h('div', { className: 'mcdev-hint' }, hint),
+  )
+}

package/src/client/api.js

@@ -0,0 +1,33 @@
+/**
+ * 客户端 ↔ 宿主的唯一通道。
+ *
+ * 必须用**相对路径**：桌面版外壳的页面是 `dsh-app://app/`，由外壳把非静态路径
+ * 转发给宿主；写成绝对 origin 会变成跨域（宿主不返回 CORS 头）。
+ * 依据见 doc/调研-DSH插件机制.md §2.2。
+ * @module minecraft-dev-starter/client/api
+ */
+
+/**
+ * @template T
+ * @param {string} method
+ * @param {unknown} [payload]
+ * @returns {Promise<T>}
+ */
+export async function call(method, payload) {
+  const response = await fetch(`/mcdev/api/${method}`, {
+    method: 'POST',
+    cache: 'no-store',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload ?? {}),
+  })
+  let body
+  try {
+    body = await response.json()
+  } catch {
+    throw new Error(`HTTP ${response.status}：返回不是 JSON`)
+  }
+  if (body?.ok !== true) {
+    throw new Error(body?.error?.message ?? `HTTP ${response.status}`)
+  }
+  return body.result
+}

package/src/client/debug.js

@@ -0,0 +1,27 @@
+/**
+ * 诊断上报：只在开发期用来回答"客户端到底走到哪一步"。
+ * 生产不依赖它，失败也不影响功能。
+ * @module minecraft-dev-starter/client/debug
+ */
+
+/** 每次页面加载只报一次，避免刷屏。 */
+const reported = new Set()
+
+/**
+ * @param {string} event
+ * @param {Record<string, unknown>} [detail]
+ */
+export function report(event, detail = {}) {
+  if (reported.has(event)) return
+  reported.add(event)
+  try {
+    fetch('/mcdev/api/client.report', {
+      method: 'POST',
+      cache: 'no-store',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ event, detail }),
+    }).catch(() => {})
+  } catch {
+    /* 上报失败无所谓 */
+  }
+}

package/src/client/format.js

@@ -0,0 +1,89 @@
+/**
+ * 展示层的纯格式化：把画像里的枚举翻成界面文案。不读时钟、不发请求。
+ * @module minecraft-dev-starter/client/format
+ */
+
+/**
+ * 面板名。比"MC 工程"更说明用途：这是给模组开发用的运行面板。
+ */
+export const PANEL_TITLE = 'Mod Dev'
+
+const LOADER_LABELS = {
+  fabric: 'Fabric',
+  forge: 'Forge',
+  neoforge: 'NeoForge',
+  paper: 'Paper',
+  spigot: 'Spigot',
+  architectury: 'Architectury',
+  unknown: '未识别',
+}
+
+const KIND_LABELS = {
+  mod: '模组',
+  'server-plugin': '服务端插件',
+  'multi-loader': '多平台',
+  unknown: '未知',
+}
+
+/**
+ * @param {string | undefined} loader
+ * @returns {string}
+ */
+export function loaderLabel(loader) {
+  return LOADER_LABELS[loader ?? 'unknown'] ?? loader ?? '未识别'
+}
+
+/**
+ * @param {string | undefined} kind
+ * @returns {string}
+ */
+export function kindLabel(kind) {
+  return KIND_LABELS[kind ?? 'unknown'] ?? kind ?? '未知'
+}
+
+/**
+ * 胶囊上的短标签：单工程显示 loader + MC 版本，多工程显示数量。
+ * @param {Array<Record<string, any>>} projects
+ * @param {string | undefined} selectedRoot
+ * @returns {string}
+ */
+export function capsuleLabel(projects, selectedRoot) {
+  if (projects.length === 0) return '未发现 MC 工程'
+  const project = projects.find((entry) => entry.root === selectedRoot) ?? projects[0]
+  if (projects.length > 1) {
+    return `${loaderLabel(project?.loader)} ${project?.minecraftVersion ?? ''} · ${projects.length}`.trim()
+  }
+  const version = project?.minecraftVersion
+  const loader = loaderLabel(project?.loader)
+  return version === undefined ? loader : `${loader} ${version}`
+}
+
+/**
+ * @param {Record<string, any> | undefined} project
+ * @returns {string}
+ */
+export function projectTitle(project) {
+  if (project === undefined) return '—'
+  return project.modName ?? project.name ?? project.root
+}
+
+/**
+ * @param {Record<string, any> | undefined} project
+ * @returns {string}
+ */
+export function projectSubtitle(project) {
+  if (project === undefined) return ''
+  const parts = [loaderLabel(project.loader)]
+  if (project.minecraftVersion !== undefined) parts.push(String(project.minecraftVersion))
+  if (project.loaderVersion !== undefined) parts.push(`loader ${project.loaderVersion}`)
+  return parts.join(' · ')
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function text(value) {
+  if (value === undefined || value === null || value === '') return '—'
+  return String(value)
+}

package/src/client/h.js

@@ -0,0 +1,8 @@
+/**
+ * 一个最小 createElement 绑定，避免为了几个节点引入 JSX 构建链的额外约束。
+ * @module minecraft-dev-starter/client/h
+ */
+
+import { createElement } from 'react'
+
+export const h = createElement

package/src/client/icons.js

@@ -0,0 +1,147 @@
+/**
+ * 手绘图标：16px 栅格、1.5 描边、`currentColor`，和系统图标同一套视觉语言。
+ *
+ * 为什么不 import `@deepseek-ai/dsh-client-ui-primitives`：我们的客户端包是
+ * 懒 CJS，顶层 `require` 一旦在某个运行时里解析不到，整个 bundle 都会挂。
+ * `dsh-better-sidebar` 对库里没有的字形也是自己画 SVG，这里沿用同一做法。
+ *
+ * @module minecraft-dev-starter/client/icons
+ */
+
+import { h } from './h.js'
+
+/**
+ * @param {number} size
+ * @param {Array<any>} children
+ */
+function svg(size, children) {
+  return h(
+    'svg',
+    {
+      width: size,
+      height: size,
+      viewBox: '0 0 16 16',
+      fill: 'none',
+      'aria-hidden': 'true',
+      focusable: 'false',
+    },
+    ...children,
+  )
+}
+
+/** 播放：实心三角，和系统的 run 语义一致。 */
+export function IconPlay({ size = 13 } = {}) {
+  return svg(size, [h('path', { key: 'p', d: 'M5.5 3.4v9.2l7.2-4.6z', fill: 'currentColor' })])
+}
+
+/** 停止：圆角方块。 */
+export function IconStop({ size = 13 } = {}) {
+  return svg(size, [h('rect', { key: 'r', x: 4.2, y: 4.2, width: 7.6, height: 7.6, rx: 1.4, fill: 'currentColor' })])
+}
+
+/** 刷新：缺口圆 + 箭头。 */
+export function IconRefresh({ size = 13 } = {}) {
+  return svg(size, [
+    h('path', {
+      key: 'a',
+      d: 'M13 8a5 5 0 1 1-1.46-3.54',
+      stroke: 'currentColor',
+      strokeWidth: 1.5,
+      strokeLinecap: 'round',
+    }),
+    h('path', {
+      key: 'b',
+      d: 'M13 2.9v3.3h-3.3',
+      stroke: 'currentColor',
+      strokeWidth: 1.5,
+      strokeLinecap: 'round',
+      strokeLinejoin: 'round',
+    }),
+  ])
+}
+
+/** 警告：三角 + 感叹号。 */
+export function IconWarning({ size = 13 } = {}) {
+  return svg(size, [
+    h('path', {
+      key: 'a',
+      d: 'M8 2.4 14 13H2z',
+      stroke: 'currentColor',
+      strokeWidth: 1.4,
+      strokeLinejoin: 'round',
+    }),
+    h('path', { key: 'b', d: 'M8 6.4v3.1', stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round' }),
+    h('circle', { key: 'c', cx: 8, cy: 11.5, r: 0.85, fill: 'currentColor' }),
+  ])
+}
+
+/** 展开：下箭头（浮层入口提示用不到时也留着，保持图标集完整）。 */
+export function IconChevronDown({ size = 13 } = {}) {
+  return svg(size, [
+    h('path', {
+      key: 'a',
+      d: 'm4.5 6.5 3.5 3.5 3.5-3.5',
+      stroke: 'currentColor',
+      strokeWidth: 1.5,
+      strokeLinecap: 'round',
+      strokeLinejoin: 'round',
+    }),
+  ])
+}
+
+/** 前进：右箭头，用于"详情"这类进入动作。 */
+export function IconChevronRight({ size = 13 } = {}) {
+  return svg(size, [
+    h('path', {
+      key: 'a',
+      d: 'm6.5 4.5 3.5 3.5-3.5 3.5',
+      stroke: 'currentColor',
+      strokeWidth: 1.5,
+      strokeLinecap: 'round',
+      strokeLinejoin: 'round',
+    }),
+  ])
+}
+
+/** 勾选：用于"切换到此工程"这类确认动作。 */
+export function IconCheck({ size = 13 } = {}) {
+  return svg(size, [
+    h('path', {
+      key: 'a',
+      d: 'm3.8 8.4 2.7 2.7 5.7-6',
+      stroke: 'currentColor',
+      strokeWidth: 1.5,
+      strokeLinecap: 'round',
+      strokeLinejoin: 'round',
+    }),
+  ])
+}
+
+/** 方块：代表"模组工程"（侧边栏标签图标）。 */
+export function IconCube({ size = 14 } = {}) {
+  return svg(size, [
+    h('path', {
+      key: 'a',
+      d: 'M8 1.9 13.6 4.7v6.6L8 14.1 2.4 11.3V4.7z',
+      stroke: 'currentColor',
+      strokeWidth: 1.3,
+      strokeLinejoin: 'round',
+    }),
+    h('path', { key: 'b', d: 'M2.6 4.8 8 7.5l5.4-2.7M8 7.5v6.4', stroke: 'currentColor', strokeWidth: 1.3, strokeLinejoin: 'round' }),
+  ])
+}
+
+/** 终端：代表"运行日志"（侧边栏标签图标）。 */
+export function IconTerminal({ size = 14 } = {}) {
+  return svg(size, [
+    h('rect', { key: 'a', x: 1.9, y: 2.9, width: 12.2, height: 10.2, rx: 2, stroke: 'currentColor', strokeWidth: 1.3 }),
+    h('path', {
+      key: 'b',
+      d: 'm4.6 6.4 1.9 1.9-1.9 1.9M8.6 10.4h2.9',
+      stroke: 'currentColor',
+      strokeWidth: 1.3,
+      strokeLinecap: 'round',
+      strokeLinejoin: 'round',
+    }),
+  ])
+}