minecraft-dev-starter 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "minecraft-dev-starter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "description": "DSH plugin that detects Minecraft mod projects and launches the client from the session header, with live logs in the sidebar",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "minecraft",
+    "modding",
+    "gradle",
+    "fabric",
+    "neoforge",
+    "forge"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build-client.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "test": "node --test \"test/*.test.js\""
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  }
+}

package/src/client/Capsule.js

@@ -0,0 +1,158 @@
+/**
+ * 标题栏胶囊：状态点 + 选中目标名 + 一个启停按钮。点名字展开浮层选目标。
+ *
+ * 工作区跟着**当前会话**走：会话头 slot 会把 `sessionId` 与 `useSessions` 传给组件，
+ * 我们从中取 cwd 再让宿主按这个目录扫描。早期版本只在挂载时扫一次、且宿主用的是
+ * "最近创建的会话"，于是切会话后胶囊不会同步。
+ * @module minecraft-dev-starter/client/Capsule
+ */
+
+import { useEffect, useRef } from 'react'
+import { h } from './h.js'
+import { IconPlay, IconStop } from './icons.js'
+import { report } from './debug.js'
+import { capsuleParts, selectedTarget } from './selection.js'
+import {
+  activeLaunchFor,
+  loadScan,
+  loadStateInfo,
+  selectedProject,
+  startTarget,
+  stopLaunch,
+  store,
+  useLaunches,
+  useStoreState,
+} from './state.js'
+import { Flyout } from './Flyout.js'
+
+/**
+ * 入口：有会话标准工具（sessionId + useSessions）就按会话取 cwd，否则退回宿主默认。
+ * @param {{ sessionId?: string, useSessions?: any }} [props]
+ */
+export function Capsule(props) {
+  if (props?.useSessions === undefined) return h(CapsuleBody, { cwd: undefined })
+  return h(SessionCapsule, props)
+}
+
+/**
+ * 订阅当前会话的 cwd；会话切换时这里会重渲染，把新 root 交给下面的 body。
+ * @param {{ sessionId?: string, useSessions: any }} props
+ */
+function SessionCapsule(props) {
+  const cwd = props.useSessions((state) => state.byId?.[props.sessionId]?.cwd)
+  return h(CapsuleBody, { cwd: typeof cwd === 'string' && cwd !== '' ? cwd : undefined })
+}
+
+/**
+ * @param {{ cwd?: string }} props
+ */
+function CapsuleBody({ cwd }) {
+  const state = useStoreState()
+  const launches = useLaunches(5000)
+  const anchor = useRef(/** @type {HTMLDivElement | null} */ (null))
+  const lastRoot = useRef(/** @type {string | undefined} */ (undefined))
+
+  useEffect(() => {
+    report('capsule.mounted')
+    void loadStateInfo()
+  }, [])
+
+  // 会话切换 = 工作区切换：清掉上一个工作区的扫描结果再重新扫
+  useEffect(() => {
+    if (cwd === undefined) {
+      if (lastRoot.current === undefined) void loadScan()
+      return
+    }
+    if (lastRoot.current === cwd) return
+    lastRoot.current = cwd
+    store.set({ workspaceRoot: cwd, scan: undefined, selectedRoot: undefined, error: undefined })
+    report('workspace.changed', { root: cwd })
+    void loadScan({ root: cwd, refresh: true })
+  }, [cwd])
+
+  useEffect(() => {
+    if (!state.flyoutOpen) return undefined
+    const onPointerDown = (event) => {
+      if (anchor.current !== null && anchor.current.contains(/** @type {Node} */ (event.target))) return
+      store.set({ flyoutOpen: false })
+    }
+    document.addEventListener('pointerdown', onPointerDown)
+    return () => document.removeEventListener('pointerdown', onPointerDown)
+  }, [state.flyoutOpen])
+
+  const project = selectedProject()
+  const target = selectedTarget(project, state.selection)
+  const running = project === undefined ? undefined : activeLaunchFor(project.root)
+  const busy = launches.busy !== undefined
+  const multipleProjects = (state.scan?.projects?.length ?? 0) > 1
+
+  // 四种状态：错误（红）、启动中（黄，呼吸）、运行中（绿，呼吸）、空闲（灰）
+  const tone =
+    state.error !== undefined || launches.error !== undefined
+      ? 'error'
+      : running === undefined
+        ? (project === undefined ? 'idle' : 'ok')
+        : running.status === 'starting'
+          ? 'warn'
+          : 'ok'
+  const parts = capsuleParts(project, target, { multipleProjects })
+  const runningLabel = running === undefined ? undefined : running.label
+  const title =
+    launches.error ??
+    state.error ??
+    (project === undefined
+      ? `没有识别到 MC 工程\n${state.workspaceRoot ?? ''}`
+      : `${project.modName ?? project.name}\n${project.root}\n${target === undefined ? '没有可运行目标' : target.taskPath}`)
+
+  return h(
+    'div',
+    { className: 'mcdev-anchor', ref: anchor },
+    h(
+      'div',
+      { className: 'mcdev-capsule' },
+      h(
+        'button',
+        { type: 'button', className: 'mcdev-pill', title, onClick: () => store.set({ flyoutOpen: !state.flyoutOpen }) },
+        h('span', { className: 'mcdev-dot', 'data-state': tone, 'data-pulse': running === undefined ? 'false' : 'true' }),
+        h(
+          'span',
+          { className: 'mcdev-pill-text' },
+          runningLabel !== undefined || parts.project === undefined
+            ? undefined
+            : [
+                h('span', { key: 'project', className: 'mcdev-pill-project', title: parts.project }, parts.project),
+                h('span', { key: 'sep', className: 'mcdev-pill-sep' }, '·'),
+              ],
+          h('span', { key: 'target', className: 'mcdev-pill-target' }, runningLabel ?? parts.target),
+        ),
+      ),
+      running === undefined
+        ? h(
+            'button',
+            {
+              type: 'button',
+              className: 'mcdev-run mcdev-run-icon',
+              disabled: target === undefined || busy,
+              title: target === undefined ? '没有可运行目标' : `启动 ${target.taskPath}`,
+              onClick: () => {
+                if (project !== undefined && target !== undefined) void startTarget(project, target)
+              },
+            },
+            h('span', { className: 'mcdev-icon' }, h(IconPlay, undefined)),
+          )
+        : h(
+            'button',
+            {
+              type: 'button',
+              className: 'mcdev-run mcdev-run-icon',
+              'data-tone': 'stop',
+              disabled: busy,
+              title: `停止 ${running.taskPath}`,
+              onClick: () => void stopLaunch(running.id),
+            },
+            h('span', { className: 'mcdev-icon' }, h(IconStop, undefined)),
+          ),
+    ),
+    state.flyoutOpen ? h(Flyout) : undefined,
+  )
+}

package/src/client/DetailTab.js

@@ -0,0 +1,228 @@
+/**
+ * 右侧栏「MC 工程」标签：单个工程的完整画像——版本、环境、模块与目标、证据、警告。
+ *
+ * 这是给人核对"你凭什么说它是 Forge 1.20.1"的地方，所以证据永远展开显示。
+ * @module minecraft-dev-starter/client/DetailTab
+ */
+
+import { useEffect } from 'react'
+import { h } from './h.js'
+import { kindLabel, loaderLabel, PANEL_TITLE, projectSubtitle, projectTitle, text } from './format.js'
+import { IconRefresh, IconWarning } from './icons.js'
+import { capsuleText, selectedTarget } from './selection.js'
+import { Skeleton } from './Skeleton.js'
+import { openLogTab } from './runtime.js'
+import {
+  loadScan,
+  selectedProject,
+  startTarget,
+  stopLaunch,
+  useLaunches,
+  useStoreState,
+} from './state.js'
+
+export function DetailTab() {
+  const state = useStoreState()
+  const launches = useLaunches(1500)
+
+  useEffect(() => {
+    if (state.scan === undefined) loadScan()
+  }, [state.scan])
+
+  const project = selectedProject()
+  const chosen = selectedTarget(project, state.selection)
+
+  const running = project === undefined
+    ? undefined
+    : launches.list.find(
+        (entry) =>
+          String(entry.root).toLowerCase() === String(project.root).toLowerCase() &&
+          (entry.status === 'starting' || entry.status === 'running'),
+      )
+
+  if (project === undefined) {
+    return h(
+      'div',
+      { className: 'mcdev-detail' },
+      h('div', { className: 'mcdev-title' }, PANEL_TITLE),
+      state.loading
+        ? h(Skeleton, { rows: 4, hint: '正在扫描工作区…' })
+        : h('div', { className: 'mcdev-muted', style: { marginTop: 8 } }, '当前工作区没有识别到模组工程'),
+      state.error === undefined ? undefined : h('div', { className: 'mcdev-error', style: { marginTop: 8 } }, state.error),
+    )
+  }
+
+  const java = /** @type {Record<string, any>} */ (project.java ?? {})
+  const modules = /** @type {Array<Record<string, any>>} */ (project.modules ?? [])
+  const evidence = /** @type {Array<Record<string, any>>} */ (project.evidence ?? [])
+  const warnings = /** @type {string[]} */ (project.warnings ?? [])
+  const conflicts = /** @type {string[]} */ (project.conflicts ?? [])
+
+  return h(
+    'div',
+    { className: 'mcdev-detail' },
+    h('div', { className: 'mcdev-title' }, projectTitle(project)),
+    h('div', { className: 'mcdev-sub' }, projectSubtitle(project)),
+    h('div', { className: 'mcdev-muted mcdev-code' }, project.root),
+    h(
+      'div',
+      { className: 'mcdev-muted', style: { marginTop: 2 } },
+      `${kindLabel(project.kind)} · 置信度 ${Math.round(Number(project.confidence ?? 0) * 100)}%`,
+    ),
+
+    section('基本信息', [
+      row('loader', loaderLabel(project.loader)),
+      row('MC 版本', text(project.minecraftVersion)),
+      row('loader 版本', text(project.loaderVersion)),
+      row('mod id', text(project.modId)),
+      row('mod 版本', text(project.modVersion)),
+    ]),
+
+    section('构建环境', [
+      row('Gradle', `${text(project.gradleVersion)}${project.wrapper === true ? '（wrapper）' : '（无 wrapper）'}`),
+      row('JDK 需求', text(java.required)),
+      row('JDK 选中', `${text(java.selected)}${java.exact === true ? '' : '（不完全匹配）'}`),
+      row('本机 JDK', java.available?.length > 0 ? java.available.map((jdk) => `${jdk.major}`).join(' / ') : '未发现'),
+    ]),
+
+    section('运行', [
+      ...(running === undefined
+        ? [
+            row('目标', capsuleText(project, chosen)),
+            h(
+              'div',
+              { className: 'mcdev-actions', style: { marginTop: 6 } },
+              h(
+                'button',
+                {
+                  type: 'button',
+                  className: 'mcdev-run',
+                  disabled: chosen === undefined || launches.busy !== undefined,
+                  title: chosen?.taskPath ?? '',
+                  onClick: () => {
+                    if (chosen !== undefined) void startTarget(project, chosen)
+                  },
+                },
+                '▶ 启动',
+              ),
+              h('span', { className: 'mcdev-hint' }, '在标题栏胶囊的浮层里切换目标'),
+            ),
+          ]
+        : [
+            row('实例', `${running.id} · ${running.taskPath}`),
+            row('状态', `${running.status === 'starting' ? '启动中' : '运行中'}${running.readyTimedOut === true ? '（还没看到启动信号，可能仍在构建）' : ''}`),
+            row('PID', text(running.pid)),
+            h(
+              'div',
+              { className: 'mcdev-actions', style: { marginTop: 6 } },
+              h(
+                'button',
+                { type: 'button', className: 'mcdev-run', 'data-tone': 'stop', disabled: launches.busy === running.id, onClick: () => stopLaunch(running.id) },
+                '⏹ 停止',
+              ),
+              h(
+                'button',
+                { type: 'button', className: 'mcdev-run', onClick: () => openLogTab() },
+                '打开日志',
+              ),
+            ),
+          ]),
+    ]),
+
+    section('模块与运行目标', [
+      ...(modules.length === 0
+        ? [h('div', { className: 'mcdev-muted' }, '没有模块信息')]
+        : [
+            h(
+              'table',
+              { className: 'mcdev-table' },
+              h('thead', undefined, h('tr', undefined, h('th', undefined, '模块'), h('th', undefined, '平台'), h('th', undefined, '任务'))),
+              h(
+                'tbody',
+                undefined,
+                modules.map((module) =>
+                  h(
+                    'tr',
+                    { key: module.path },
+                    h('td', undefined, module.path),
+                    h('td', undefined, module.platform),
+                    h(
+                      'td',
+                      { className: 'mcdev-code' },
+                      module.targets?.length > 0
+                        ? module.targets.map((target) => `${target.taskPath}${target.guessed === true ? ' ?' : ''}`).join('  ')
+                        : '—',
+                    ),
+                  ),
+                ),
+              ),
+            ),
+          ]),
+      h('div', { className: 'mcdev-hint', style: { marginTop: 6 } }, '带 ? 的任务是按 loader 惯例推测的，未经验证；启动能力在 M2 接入。'),
+    ]),
+
+    section(
+      '证据',
+      evidence.length === 0
+        ? [h('div', { className: 'mcdev-muted' }, '没有证据')]
+        : [
+            h(
+              'div',
+              { className: 'mcdev-stack' },
+              evidence.map((entry, index) =>
+                h(
+                  'div',
+                  { key: `${entry.file}:${index}` },
+                  h('span', { className: 'mcdev-code mcdev-sub' }, entry.file),
+                  h('span', { className: 'mcdev-muted' }, ` — ${entry.detail}`),
+                ),
+              ),
+            ),
+          ],
+    ),
+
+    warnings.length === 0 && conflicts.length === 0
+      ? undefined
+      : section('提示', [
+          ...warnings.map((warning, index) =>
+            h(
+              'div',
+              { key: `w${index}`, className: 'mcdev-warn mcdev-icon-text' },
+              h('span', { className: 'mcdev-icon' }, h(IconWarning, undefined)),
+              warning,
+            ),
+          ),
+          ...conflicts.map((conflict, index) => h('div', { key: `c${index}`, className: 'mcdev-error' }, `· ${conflict}`)),
+        ]),
+
+    h(
+      'div',
+      { style: { marginTop: 14 } },
+      h(
+        'button',
+        { type: 'button', className: 'mcdev-mini', onClick: () => loadScan({ refresh: true }) },
+        h('span', { className: 'mcdev-icon' }, h(IconRefresh, { size: 12 })),
+        state.loading ? '重新扫描中…' : '重新扫描',
+      ),
+    ),
+    state.scan?.scannedAt === undefined
+      ? undefined
+      : h('div', { className: 'mcdev-muted mcdev-hint', style: { marginTop: 4 } }, `扫描于 ${state.scan.scannedAt}`),
+  )
+}
+
+/**
+ * @param {string} title
+ * @param {Array<any>} children
+ */
+function section(title, children) {
+  return h('div', { className: 'mcdev-section' }, h('h4', undefined, title), ...children)
+}
+
+/**
+ * @param {string} key
+ * @param {string} value
+ */
+function row(key, value) {
+  return h('div', { className: 'mcdev-row', key }, h('span', { className: 'mcdev-key' }, key), h('span', { className: 'mcdev-code' }, value))
+}

package/src/client/Flyout.js

@@ -0,0 +1,191 @@
+/**
+ * 工程浮层。两种形态：
+ *
+ * - **多工程**：三层结构——表头固定、工程列表滚动、选中工程的目标固定在底部。
+ *   列表每行高度恒定，选工程只改底部，不会"点一下整块跳一下"。
+ * - **单工程**（更常见）：跳过列表，表头直接显示工程名与 loader/版本，底下就是目标；
+ *   少一层选择，也少一次点击。
+ *
+ * @module minecraft-dev-starter/client/Flyout
+ */
+
+import { h } from './h.js'
+import { kindLabel, PANEL_TITLE, projectSubtitle, projectTitle } from './format.js'
+import { IconChevronRight, IconRefresh } from './icons.js'
+import { groupByModule, selectedTarget, targetKey } from './selection.js'
+import { Skeleton } from './Skeleton.js'
+import { loadScan, selectTarget, store, useLaunches, useStoreState } from './state.js'
+import { openDetailTab } from './runtime.js'
+
+export function Flyout() {
+  const state = useStoreState()
+  const launches = useLaunches(1500)
+  const projects = state.scan?.projects ?? []
+  const current = projects.find((project) => project.root === state.selectedRoot) ?? projects[0]
+  const single = projects.length === 1
+  const running = launches.list.find(
+    (entry) =>
+      (entry.status === 'starting' || entry.status === 'running') &&
+      String(entry.root).toLowerCase() === String(current?.root ?? '').toLowerCase(),
+  )
+
+  return h(
+    'div',
+    { className: 'mcdev-flyout', role: 'dialog', 'aria-label': PANEL_TITLE },
+
+    // ① 表头：与列表之间有一条通栏分割线，滚动时不动
+    h(
+      'div',
+      { className: 'mcdev-flyout-head' },
+      h(
+        'div',
+        { className: 'mcdev-row', style: { justifyContent: 'space-between', alignItems: 'center' } },
+        h('span', { className: 'mcdev-title' }, PANEL_TITLE),
+        h(
+          'button',
+          {
+            type: 'button',
+            className: 'mcdev-mini mcdev-mini-icon',
+            title: state.loading ? '扫描中…' : '重新扫描工作区',
+            disabled: state.loading,
+            onClick: () => loadScan({ refresh: true }),
+          },
+          h('span', { className: 'mcdev-icon' }, h(IconRefresh, { size: 12 })),
+        ),
+      ),
+      // 单工程：表头直接承担原来列表行的工作，省掉一层选择
+      single && current !== undefined
+        ? h(
+            'div',
+            { style: { display: 'flex', flexDirection: 'column', gap: 2 } },
+            h('div', { className: 'mcdev-title', title: projectTitle(current) }, projectTitle(current)),
+            h('div', { className: 'mcdev-sub' }, projectSubtitle(current)),
+            h('div', { className: 'mcdev-muted mcdev-code mcdev-ellipsis', title: current.root }, current.root),
+          )
+        : h('div', { className: 'mcdev-muted mcdev-code mcdev-ellipsis', title: state.scan?.root ?? '' }, state.scan?.root ?? '—'),
+      state.error === undefined ? undefined : h('div', { className: 'mcdev-error' }, state.error),
+      launches.error === undefined ? undefined : h('div', { className: 'mcdev-error' }, launches.error),
+    ),
+
+    // ② 列表：只在多工程时出现；每行只有名字与 loader/版本，高度恒定
+    single
+      ? undefined
+      : h(
+      'div',
+      { className: 'mcdev-flyout-list' },
+      projects.length === 0
+        ? state.loading
+          ? h(Skeleton, { rows: 3, hint: '正在扫描工作区…' })
+          : h('div', { className: 'mcdev-hint', style: { padding: '10px 4px' } }, '没有找到 Gradle 工程')
+        : projects.map((project) =>
+            h(
+              'button',
+              {
+                key: project.root,
+                type: 'button',
+                className: 'mcdev-list-row',
+                'data-current': project.root === current?.root ? 'true' : 'false',
+                title: `${project.root}\n${kindLabel(project.kind)}`,
+                onClick: () => store.set({ selectedRoot: project.root }),
+              },
+              h('span', { className: 'mcdev-list-name' }, project.modName ?? project.name ?? project.root),
+              h('span', { className: 'mcdev-list-meta' }, projectSubtitle(project)),
+            ),
+          ),
+    ),
+
+    // ③ 选择区：选中工程的目标，位置固定
+    h(
+      'div',
+      { className: 'mcdev-flyout-pane' },
+      current === undefined
+        ? undefined
+        : [
+            h(
+              'div',
+              { className: 'mcdev-row', style: { justifyContent: 'space-between', alignItems: 'center' } },
+              h(
+                'span',
+                { className: 'mcdev-ellipsis', style: { minWidth: 0 } },
+                h('span', { className: 'mcdev-muted' }, '运行目标'),
+                running === undefined
+                  ? undefined
+                  : h(
+                      'span',
+                      { className: 'mcdev-inline-status' },
+                      h('span', {
+                        className: 'mcdev-dot',
+                        'data-state': running.status === 'starting' ? 'warn' : 'ok',
+                        'data-pulse': 'true',
+                      }),
+                      `${running.label} ${running.status === 'starting' ? '启动中' : '运行中'} · ${elapsed(running.startedAt)}`,
+                    ),
+              ),
+              h(
+                'button',
+                { type: 'button', className: 'mcdev-mini', onClick: () => openDetailTab() },
+                '详情',
+                h('span', { className: 'mcdev-icon' }, h(IconChevronRight, { size: 12 })),
+              ),
+            ),
+            renderTargets(current, state.selection, running !== undefined),
+          ],
+    ),
+  )
+}
+
+/**
+ * @param {Record<string, any>} project
+ * @param {Record<string, string>} selection
+ * @param {boolean} locked 有实例在跑时不允许换目标
+ */
+function renderTargets(project, selection, locked) {
+  const targets = /** @type {Array<Record<string, any>>} */ (project.runTargets ?? [])
+  if (targets.length === 0) return h('div', { className: 'mcdev-hint', style: { marginTop: 6 } }, '没有找到可运行目标')
+
+  const chosen = selectedTarget(project, selection)
+  const groups = groupByModule(targets)
+
+  return h(
+    'div',
+    { className: 'mcdev-options' },
+    groups.map((group) =>
+      h(
+        'div',
+        { key: group.module, className: 'mcdev-option-group' },
+        groups.length > 1 ? h('div', { className: 'mcdev-option-module' }, group.module) : undefined,
+        group.targets.map((target) =>
+          h(
+            'label',
+            { key: targetKey(target), className: `mcdev-option${locked ? ' is-disabled' : ''}`, title: target.taskPath },
+            h('input', {
+              type: 'radio',
+              className: 'mcdev-radio',
+              name: `mcdev-${project.root}`,
+              checked: chosen !== undefined && targetKey(chosen) === targetKey(target),
+              disabled: locked,
+              onChange: () => selectTarget(project.root, targetKey(target)),
+            }),
+            h('span', { className: 'mcdev-option-label' }, target.label),
+            target.guessed === true
+              ? h('span', { className: 'mcdev-badge', 'data-guessed': 'true', title: '按 loader 惯例推测，尚未验证' }, '未验证')
+              : undefined,
+          ),
+        ),
+      ),
+    ),
+  )
+}
+
+/**
+ * @param {string} startedAt
+ * @returns {string}
+ */
+function elapsed(startedAt) {
+  const started = Date.parse(startedAt)
+  if (Number.isNaN(started)) return '—'
+  const seconds = Math.max(0, Math.round((Date.now() - started) / 1000))
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  return `${minutes}m${String(seconds % 60).padStart(2, '0')}s`
+}