minecraft-dev-starter 0.0.0-stage → 0.1.1

package/src/client/index.js

@@ -0,0 +1,205 @@
+/**
+ * 客户端入口（cordis 插件形状：inject + apply）。
+ *
+ * 挂四处：
+ *   - 会话标题栏的胶囊（`conversation.session.header.utilities`）
+ *   - 右侧栏「Mod Dev」工程标签
+ *   - 右侧栏「运行日志」标签
+ *   - 装了 `dsh-better-sidebar` 时，再向它的侧栏注册同样两个页面（带图标）
+ *
+ * @module minecraft-dev-starter/client
+ */
+
+import { Capsule } from './Capsule.js'
+import { DetailTab } from './DetailTab.js'
+import { PANEL_TITLE } from './format.js'
+import { LogTab } from './LogTab.js'
+import { report } from './debug.js'
+import { h } from './h.js'
+import { IconCube, IconTerminal } from './icons.js'
+import { DETAIL_KIND, LOG_KIND, runtime } from './runtime.js'
+import { ensureStyles } from './styles.js'
+
+export const name = 'mcdev-client'
+
+/** cordis 只把 inject 里声明过的服务交给插件；三个服务都在 web 组合里。 */
+export const inject = ['slots', 'sidebarRight', 'sidebarRightTabs']
+
+const DETAIL_ID = 'minecraft-dev-starter/detail'
+const LOG_ID = 'minecraft-dev-starter/logs'
+
+/**
+ * @param {any} ctx
+ */
+export function apply(ctx) {
+  runtime.ctx = ctx
+  ensureStyles()
+  report('apply')
+
+  // 1) 标题栏胶囊
+  try {
+    ctx.slots.inject('conversation.session.header.utilities', () =>
+      ctx.slots.register(
+        {
+          name: 'conversation.session.header.utilities',
+          id: 'mc-dev-starter:run-capsule',
+          order: 15,
+          registrant: 'minecraft-dev-starter',
+        },
+        Capsule,
+      ),
+    )
+    report('capsule.registered')
+  } catch (error) {
+    report('capsule.failed', { message: String(error) })
+  }
+
+  // 2) 右侧栏两个标签类型：工程面板 + 运行日志
+  try {
+    ctx.effect(
+      () => ctx.sidebarRightTabs.register({ id: DETAIL_ID, kind: DETAIL_KIND, title: () => PANEL_TITLE }),
+      'mcdev: detail tab type',
+    )
+    ctx.effect(
+      () => ctx.sidebarRightTabs.register({ id: LOG_ID, kind: LOG_KIND, title: () => '运行日志' }),
+      'mcdev: log tab type',
+    )
+    report('tab.type.registered')
+  } catch (error) {
+    report('tab.type.failed', { message: String(error) })
+  }
+
+  // 3) 标签正文
+  registerBody(DETAIL_ID, DetailTab, 'detail')
+  registerBody(LOG_ID, LogTab, 'logs')
+
+  // 4) 装了 dsh-better-sidebar 时，把同样的两个页面挂到它的侧栏（它支持标签图标）
+  ctx.effect(() => registerBetterSidebarTabs(ctx), 'mcdev: better-sidebar tabs')
+}
+
+/**
+ * 向 `dsh-better-sidebar` 注册两个带图标的标签。
+ *
+ * 它是可选的第三方插件：可能没装、也可能比我们晚加载，所以轮询取服务，
+ * 拿到就注册，拿不到就安静退出（不报错、不影响别的功能）。
+ * @param {any} ctx
+ * @returns {() => void} disposer
+ */
+function registerBetterSidebarTabs(ctx) {
+  /** @type {Array<() => void>} */
+  const disposers = []
+  /** @type {(() => void) | undefined} */
+  let injectHandle
+
+  /**
+   * @param {any} sidebar
+   */
+  const register = (sidebar) => {
+    if (sidebar === undefined || typeof sidebar.registerTab !== 'function') return
+    try {
+      disposers.push(
+        sidebar.registerTab({
+          id: 'minecraft-dev-starter:project',
+          title: PANEL_TITLE,
+          icon: (size) => h(IconCube, { size }),
+          component: () => h(DetailTab),
+        }),
+      )
+      disposers.push(
+        sidebar.registerTab({
+          id: 'minecraft-dev-starter:logs',
+          title: '运行日志',
+          icon: (size) => h(IconTerminal, { size }),
+          component: () => h(LogTab),
+        }),
+      )
+      report('betterSidebar.registered')
+    } catch (error) {
+      report('betterSidebar.failed', { message: String(error) })
+    }
+  }
+
+  // 首选 cordis 的作用域注入：等服务出现再注册，插件不在也不会报错。
+  if (typeof ctx.inject === 'function') {
+    try {
+      injectHandle = ctx.inject(['betterSidebar'], (scoped) => {
+        register(scoped.get('betterSidebar', false))
+      })
+      report('betterSidebar.waiting')
+      return () => {
+        try {
+          injectHandle?.()
+        } catch {
+          /* ignore */
+        }
+        for (const dispose of disposers.splice(0)) {
+          try {
+            dispose()
+          } catch {
+            /* ignore */
+          }
+        }
+      }
+    } catch (error) {
+      report('betterSidebar.inject.failed', { message: String(error) })
+    }
+  }
+
+  // 兜底：轮询 get（strict=false 不抛），30 秒找不到就放弃
+  let stopped = false
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer
+  const startedAt = Date.now()
+  const attempt = () => {
+    if (stopped) return
+    let sidebar
+    try {
+      sidebar = typeof ctx.get === 'function' ? ctx.get('betterSidebar', false) : undefined
+    } catch {
+      sidebar = undefined
+    }
+    if (sidebar === undefined || typeof sidebar.registerTab !== 'function') {
+      if (Date.now() - startedAt > 30_000) {
+        report('betterSidebar.absent')
+        return
+      }
+      timer = setTimeout(attempt, 700)
+      return
+    }
+    register(sidebar)
+  }
+  attempt()
+  return () => {
+    stopped = true
+    if (timer !== undefined) clearTimeout(timer)
+    for (const dispose of disposers.splice(0)) {
+      try {
+        dispose()
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/**
+ * 注册标签正文；某些版本要求先等 slot 声明上账，所以失败后走 inject 再试一次。
+ * @param {string} id
+ * @param {any} component
+ * @param {string} tag 诊断上报里的名字
+ */
+function registerBody(id, component, tag) {
+  const ctx = runtime.ctx
+  const register = () => ctx.slots.register({ name: 'sidebar.right.pane.tab', key: id }, component)
+  try {
+    register()
+    report(`${tag}.body.registered`)
+  } catch {
+    try {
+      ctx.slots.inject('sidebar.right.pane.tab', register)
+      report(`${tag}.body.registered.via-inject`)
+    } catch (error) {
+      report(`${tag}.body.failed`, { message: String(error) })
+    }
+  }
+}

package/src/client/runtime.js

@@ -0,0 +1,41 @@
+/**
+ * 客户端运行时句柄。
+ *
+ * 用模块级对象而不是 props：slot 组件的注入约定会随版本变，
+ * 而 `ctx` 在 apply 时就确定了，组件里读它最稳。
+ * @module minecraft-dev-starter/client/runtime
+ */
+
+/** 右侧栏「MC 工程」详情标签的 kind。 */
+export const DETAIL_KIND = 'mcdev.detail'
+
+/** 右侧栏「运行日志」标签的 kind。 */
+export const LOG_KIND = 'mcdev.logs'
+
+/** @type {{ ctx?: any }} */
+export const runtime = {}
+
+/**
+ * @param {string} kind
+ * @returns {boolean}
+ */
+function open(kind) {
+  const sidebar = runtime.ctx?.sidebarRight
+  if (sidebar === undefined) return false
+  try {
+    sidebar.openTab(kind)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** 打开工程详情标签（openTab 会顺带展开面板）。 */
+export function openDetailTab() {
+  return open(DETAIL_KIND)
+}
+
+/** 打开运行日志标签。 */
+export function openLogTab() {
+  return open(LOG_KIND)
+}

package/src/client/selection.js

@@ -0,0 +1,154 @@
+/**
+ * 目标选择的纯逻辑（不碰 React、不碰 DOM），方便单测。
+ *
+ * 选择结果按工程根目录记在 localStorage：同一工程下次打开还是上次那个目标。
+ * @module minecraft-dev-starter/client/selection
+ */
+
+/** @type {Record<string, string>} */
+const STORAGE_KEY = 'mcdev.selection'
+
+/**
+ * 一个目标的稳定 key（模块 + 任务路径）。
+ * @param {Record<string, any>} target
+ * @returns {string}
+ */
+export function targetKey(target) {
+  return `${target.module ?? '.'}:${target.taskPath}`
+}
+
+/**
+ * 按模块分组，保持 discovery 顺序；`common` 这类不可运行模块本来就无目标，不出现。
+ * @param {Array<Record<string, any>>} targets
+ * @returns {Array<{ module: string, targets: Array<Record<string, any>> }>}
+ */
+export function groupByModule(targets) {
+  /** @type {Array<{ module: string, targets: Array<Record<string, any>> }>} */
+  const groups = []
+  for (const target of targets) {
+    const module = String(target.module ?? '.')
+    const group = groups.find((entry) => entry.module === module)
+    if (group === undefined) groups.push({ module, targets: [target] })
+    else group.targets.push(target)
+  }
+  return groups
+}
+
+/**
+ * 当前选中的目标：记住的还在就用它，否则退回第一个。
+ * @param {Record<string, any> | undefined} project
+ * @param {Record<string, string>} selection
+ * @returns {Record<string, any> | undefined}
+ */
+export function selectedTarget(project, selection) {
+  const targets = /** @type {Array<Record<string, any>>} */ (project?.runTargets ?? [])
+  if (targets.length === 0) return undefined
+  const remembered = selection[String(project?.root ?? '')]
+  return targets.find((target) => targetKey(target) === remembered) ?? targets[0]
+}
+
+/**
+ * 胶囊上那行字：单模块只显示目标名，多模块带模块前缀。
+ * @param {Record<string, any> | undefined} project
+ * @param {Record<string, any> | undefined} target
+ * @returns {string}
+ */
+export function capsuleText(project, target) {
+  if (project === undefined) return '未检测到 MC 工程'
+  if (target === undefined) return '无可运行目标'
+  const module = String(target.module ?? '.')
+  return module === '.' ? String(target.label) : `${module} · ${target.label}`
+}
+
+/**
+ * 读一次记住的选择（localStorage 不可用时返回空表）。
+ * @returns {Record<string, string>}
+ */
+export function readSelection() {
+  try {
+    const raw = globalThis.localStorage?.getItem(STORAGE_KEY)
+    if (typeof raw !== 'string') return {}
+    const parsed = JSON.parse(raw)
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 写回选择。
+ * @param {Record<string, string>} selection
+ */
+export function writeSelection(selection) {
+  try {
+    globalThis.localStorage?.setItem(STORAGE_KEY, JSON.stringify(selection))
+  } catch {
+    /* 隐身模式等场景写不进去，忽略 */
+  }
+}
+
+/**
+ * 日志标签应该看哪一条实例。
+ *
+ * 规则（按优先级）：
+ *   1. 有正在跑/启动中的实例 → 永远跟它（点 ▶ 之后最想看的就是这次）；
+ *   2. 用户手动选过（pinned）→ 保持他的选择；
+ *   3. 否则跟当前、再否则跟最新一条。
+ *
+ * 早期版本只在"没选过"时挑一次，于是新启动的实例不会顶上来——
+ * 面板会一直停在旧实例（哪怕它是 0 字节的失败记录）。
+ * @param {Array<Record<string, any>>} history
+ * @param {string | undefined} currentId
+ * @param {boolean} pinned
+ * @returns {string | undefined}
+ */
+export function pickLogTarget(history, currentId, pinned) {
+  const active = history.find((entry) => entry.status === 'starting' || entry.status === 'running')
+  if (active !== undefined) return active.id
+  if (pinned && currentId !== undefined) return currentId
+  if (currentId !== undefined && history.some((entry) => entry.id === currentId)) return currentId
+  return history[0]?.id
+}
+
+/**
+ * 实例状态的中文标签。
+ * @param {Record<string, any>} entry
+ * @returns {string}
+ */
+export function launchStatusText(entry) {
+  if (entry.status === 'starting') return '启动中'
+  if (entry.status === 'running') return '运行中'
+  if (entry.status === 'unknown') return '状态未知'
+  if (entry.outcome === 'killed') return '已停止'
+  if (entry.outcome === 'normal') return '已退出'
+  return entry.exitCode === null || entry.exitCode === undefined ? '已退出' : `已退出(${entry.exitCode})`
+}
+
+/**
+ * 胶囊的两段文案。窄的时候应该让"工程名"省略，而不是把目标名截掉——
+ * 目标名才是可操作的那部分，工程名只是上下文。
+ * @param {Record<string, any> | undefined} project
+ * @param {Record<string, any> | undefined} target
+ * @param {{ multipleProjects?: boolean }} [options]
+ * @returns {{ project: string | undefined, target: string }}
+ */
+export function capsuleParts(project, target, options = {}) {
+  const targetText = capsuleText(project, target)
+  if (project === undefined || target === undefined || options.multipleProjects !== true) {
+    return { project: undefined, target: targetText }
+  }
+  return { project: String(project.modName ?? project.name ?? project.root), target: targetText }
+}
+
+/**
+ * 胶囊文案。工作区里有多个工程时把工程名带上——否则只显示 "Client" 没人知道
+ * 它是哪个工程的（一个工作区里每工程都记着自己的选择）。
+ * @param {Record<string, any> | undefined} project
+ * @param {Record<string, any> | undefined} target
+ * @param {{ multipleProjects?: boolean }} [options]
+ * @returns {string}
+ */
+export function capsuleSummary(project, target, options = {}) {
+  const parts = capsuleParts(project, target, options)
+  return parts.project === undefined ? parts.target : `${parts.project} · ${parts.target}`
+}

package/src/client/state.js

@@ -0,0 +1,233 @@
+/**
+ * 客户端共享状态与数据加载。
+ *
+ * 一次 `projects.scan` 结果给三个地方用：标题栏胶囊、浮层、右侧栏详情；
+ * 所以放在模块级 store 里，而不是每个组件各拉一次。
+ * @module minecraft-dev-starter/client/state
+ */
+
+import { useEffect, useState } from 'react'
+import { call } from './api.js'
+import { openLogTab } from './runtime.js'
+import { readSelection, writeSelection } from './selection.js'
+import { createStore } from './store.js'
+
+/** @typedef {{ store: ReturnType<typeof createStore> }} Never */
+
+export const store = createStore({
+  loading: false,
+  /** @type {string | undefined} */
+  error: undefined,
+  /** @type {{ root: string, projects: Array<Record<string, any>>, truncated: boolean, scannedAt: string } | undefined} */
+  scan: undefined,
+  /** @type {string | undefined} */
+  selectedRoot: undefined,
+  flyoutOpen: false,
+  /** @type {Record<string, string>} 每个工程记住的目标 key */
+  selection: readSelection(),
+  /** @type {{ autoOpenLogTab?: boolean }} 宿主下发的部署配置 */
+  config: { autoOpenLogTab: true },
+  /** @type {string | undefined} 当前会话的工作区（由胶囊从会话上下文注入） */
+  workspaceRoot: undefined,
+})
+
+/**
+ * 拉一次宿主配置（启动时自动打开日志标签等），只取一次。
+ */
+export async function loadStateInfo() {
+  try {
+    const info = await call('state.info', {})
+    store.set({ config: { autoOpenLogTab: true, ...(info?.config ?? {}) } })
+  } catch {
+    /* 拉不到就用默认值 */
+  }
+}
+
+/**
+ * 记住某个工程选中的目标。
+ * @param {string} root
+ * @param {string} key
+ */
+export function selectTarget(root, key) {
+  const selection = { ...store.get().selection, [root]: key }
+  writeSelection(selection)
+  store.set({ selection })
+}
+
+/** @type {Promise<unknown> | undefined} */
+let inFlight
+/** @type {string | undefined} */
+let inFlightRoot
+
+/**
+ * 拉一次扫描结果。
+ *
+ * `root` 默认取当前会话的工作区（由胶囊从会话上下文里读出来再塞进 store）。
+ * 切会话时 `root` 变了，必须清掉旧结果，否则胶囊会短暂显示上一个工作区的工程。
+ * @param {{ root?: string, refresh?: boolean }} [options]
+ * @returns {Promise<void>}
+ */
+export async function loadScan(options = {}) {
+  const root = options.root ?? store.get().workspaceRoot
+  if (inFlight !== undefined) {
+    if (root === inFlightRoot) return inFlight
+    await inFlight.catch(() => {})
+  }
+  inFlightRoot = root
+  store.set({ loading: true, error: undefined })
+  inFlight = call('projects.scan', {
+    ...(root === undefined ? {} : { root }),
+    ...(options.refresh === true ? { refresh: true } : {}),
+  })
+    .then((result) => {
+      const scan = /** @type {NonNullable<ReturnType<typeof store.get>['scan']>} */ (result)
+      const current = store.get().selectedRoot
+      const stillThere = scan.projects.some((project) => project.root === current)
+      store.set({
+        loading: false,
+        scan,
+        workspaceRoot: scan.root,
+        error: undefined,
+        selectedRoot: stillThere ? current : scan.projects[0]?.root,
+      })
+    })
+    .catch((error) => {
+      store.set({ loading: false, error: error instanceof Error ? error.message : String(error) })
+    })
+    .finally(() => {
+      inFlight = undefined
+      inFlightRoot = undefined
+    })
+  return inFlight
+}
+
+/** 当前选中的工程（默认第一个）。 */
+export function selectedProject() {
+  const state = store.get()
+  const projects = state.scan?.projects ?? []
+  return projects.find((project) => project.root === state.selectedRoot) ?? projects[0]
+}
+
+/**
+ * React 绑定：订阅 store 并在变化时重渲染。
+ * @returns {ReturnType<typeof store.get>}
+ */
+export function useStoreState() {
+  const [state, setState] = useState(store.get())
+  useEffect(() => store.subscribe(setState), [])
+  return state
+}
+
+// ── 运行实例 ──────────────────────────────────────────────────────────
+
+/** 实例列表单独一个 store：轮询频率比扫描高，别互相拖累。 */
+export const launchStore = createStore({
+  /** @type {Array<Record<string, any>>} */
+  list: [],
+  /** @type {string | undefined} */
+  error: undefined,
+  /** @type {string | undefined} 正在启停的目标 key，用来禁用按钮 */
+  busy: undefined,
+  /** @type {number} 每次拉取递增，供 tail 刷新用 */
+  rev: 0,
+})
+
+/**
+ * 拉一次实例列表。
+ * @param {string | undefined} [root]
+ */
+export async function loadLaunches(root) {
+  try {
+    const list = await call('launch.list', root === undefined ? {} : { root })
+    launchStore.set({ list: /** @type {Array<Record<string, any>>} */ (list), error: undefined, rev: Date.now() })
+  } catch (error) {
+    launchStore.set({ error: error instanceof Error ? error.message : String(error) })
+  }
+}
+
+/**
+ * @param {string} root
+ * @returns {Record<string, any> | undefined}
+ */
+export function activeLaunchFor(root) {
+  return launchStore.get().list.find(
+    (entry) => String(entry.root).toLowerCase() === root.toLowerCase() && (entry.status === 'starting' || entry.status === 'running'),
+  )
+}
+
+/**
+ * 启动一个目标。
+ * @param {Record<string, any>} project
+ * @param {Record<string, any>} target
+ */
+export async function startTarget(project, target) {
+  const key = `${project.root}:${target.taskPath}`
+  launchStore.set({ busy: key, error: undefined })
+  try {
+    await call('launch.start', {
+      root: project.root,
+      taskPath: target.taskPath,
+      label: target.label,
+      kind: target.kind,
+      module: target.module,
+    })
+    // 启动成功就把日志摆到人眼前（部署配置可关）
+    if (store.get().config.autoOpenLogTab !== false) openLogTab()
+  } catch (error) {
+    launchStore.set({ error: error instanceof Error ? error.message : String(error) })
+  } finally {
+    launchStore.set({ busy: undefined })
+    await loadLaunches()
+  }
+}
+
+/**
+ * 停止一个实例。
+ * @param {string} id
+ */
+export async function stopLaunch(id) {
+  launchStore.set({ busy: id, error: undefined })
+  try {
+    await call('launch.stop', { id })
+  } catch (error) {
+    launchStore.set({ error: error instanceof Error ? error.message : String(error) })
+  } finally {
+    launchStore.set({ busy: undefined })
+    await loadLaunches()
+  }
+}
+
+/**
+ * React 绑定 + 轮询（页面不可见时停轮询）。
+ * @param {number} [intervalMs]
+ * @returns {ReturnType<typeof launchStore.get>}
+ */
+export function useLaunches(intervalMs = 1500) {
+  const [state, setState] = useState(launchStore.get())
+  useEffect(() => {
+    const unsubscribe = launchStore.subscribe(setState)
+    void loadLaunches()
+    let timer
+    const tick = () => {
+      if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return
+      void loadLaunches()
+    }
+    timer = setInterval(tick, intervalMs)
+    return () => {
+      unsubscribe()
+      clearInterval(timer)
+    }
+  }, [intervalMs])
+  return state
+}
+
+/**
+ * 拉一次某个实例的日志尾部。
+ * @param {string} id
+ * @param {number} limit
+ * @returns {Promise<string[]>}
+ */
+export async function fetchLogTail(id, limit = 40) {
+  const result = await call('launch.logs', { id, offset: 0, limit })
+  return /** @type {string[]} */ (result.lines ?? [])
+}

package/src/client/store.js

@@ -0,0 +1,34 @@
+/**
+ * 极简可订阅状态。客户端不需要状态库：一个扫描结果 + 一个选中项就够。
+ * @module minecraft-dev-starter/client/store
+ */
+
+/**
+ * @template {Record<string, unknown>} T
+ * @param {T} initial
+ */
+export function createStore(initial) {
+  /** @type {T} */
+  let value = initial
+  const listeners = new Set()
+
+  return {
+    /** @returns {T} */
+    get() {
+      return value
+    },
+    /** @param {Partial<T>} next */
+    set(next) {
+      value = { ...value, ...next }
+      for (const listener of listeners) listener(value)
+    },
+    /**
+     * @param {(value: T) => void} listener
+     * @returns {() => void}
+     */
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}