minecraft-dev-starter 0.0.0-stage → 0.1.0

package/src/lib/scanner.js

@@ -0,0 +1,131 @@
+/**
+ * 工作区扫描：找出哪些目录是 MC 工程，再交给 detectProject 出画像。
+ *
+ * 规则（对应策划 §6.1）：
+ *   - 从工作区根 BFS，深度默认 3；
+ *   - 命中构建文件的目录即视为工程根，**不再往下走**（子模块由 detect 的 include 展开）；
+ *   - 剪掉 build/out/bin/run/.gradle 这类产物与依赖目录——不剪会把
+ *     `reference/` 里别人家的 mods.toml、`bin/` 里旧的 Eclipse 产物当成工程。
+ * @module minecraft-dev-starter/lib/scanner
+ */
+
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { detectProject } from './detect.js'
+import { discoverJdks } from './java.js'
+
+/** 扫描时直接跳过的目录名。 */
+export const PRUNE_DIRS = new Set([
+  '.git',
+  '.gradle',
+  '.idea',
+  '.vscode',
+  '.dsh',
+  'build',
+  'out',
+  'bin',
+  'run',
+  'node_modules',
+  'libs',
+  'reference',
+  'logs',
+])
+
+/** 构建脚本名；命中任一即认为这是一个 Gradle 工程。 */
+const BUILD_FILES = new Set(['build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts'])
+
+/**
+ * @typedef {object} ScanResult
+ * @property {string} root
+ * @property {Array<Record<string, unknown>>} projects
+ * @property {number} scannedDirs
+ * @property {boolean} truncated
+ */
+
+/**
+ * 扫一个工作区。
+ * @param {string} root
+ * @param {{ depth?: number, maxDirs?: number, maxProjects?: number, jdks?: import('./java.js').JdkInfo[], signal?: AbortSignal }} [options]
+ * @returns {Promise<ScanResult>}
+ */
+export async function scanWorkspace(root, options = {}) {
+  const depth = options.depth ?? 3
+  const maxDirs = options.maxDirs ?? 2000
+  const maxProjects = options.maxProjects ?? 120
+  const jdks = options.jdks ?? (await discoverJdks())
+
+  /** @type {Array<{ dir: string, depth: number }>} */
+  const queue = [{ dir: root, depth: 0 }]
+  /** @type {string[]} */
+  const candidates = []
+  let scannedDirs = 0
+  let truncated = false
+
+  while (queue.length > 0) {
+    if (options.signal?.aborted === true) break
+    const item = queue.shift()
+    if (item === undefined) break
+    scannedDirs += 1
+    if (scannedDirs > maxDirs) {
+      truncated = true
+      break
+    }
+    if (candidates.length >= maxProjects) {
+      truncated = true
+      break
+    }
+
+    const entries = await safeReaddir(item.dir)
+    if (entries === undefined) continue
+
+    if (item.depth > 0 && entries.files.some((name) => BUILD_FILES.has(name))) {
+      candidates.push(item.dir)
+      continue // 工程内部不再展开，模块交给 detect
+    }
+
+    if (item.depth >= depth) continue
+    for (const child of entries.dirs) {
+      if (PRUNE_DIRS.has(child)) continue
+      queue.push({ dir: join(item.dir, child), depth: item.depth + 1 })
+    }
+  }
+
+  // 工作区根本身就是一个工程的情况
+  const rootEntries = await safeReaddir(root)
+  if (rootEntries !== undefined && !candidates.includes(root)) {
+    const isProject = rootEntries.files.some((name) => BUILD_FILES.has(name))
+    if (isProject) candidates.unshift(root)
+  }
+
+  /** @type {Array<Record<string, unknown>>} */
+  const projects = []
+  for (const dir of candidates) {
+    if (options.signal?.aborted === true) break
+    try {
+      projects.push(await detectProject(dir, { jdks }))
+    } catch (error) {
+      projects.push({ root: dir, loader: 'unknown', error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  return { root, projects, scannedDirs, truncated }
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<{ files: string[], dirs: string[] } | undefined>}
+ */
+async function safeReaddir(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    const files = []
+    const dirs = []
+    for (const entry of entries) {
+      if (entry.isDirectory()) dirs.push(entry.name)
+      else if (entry.isFile()) files.push(entry.name)
+    }
+    return { files, dirs }
+  } catch {
+    return undefined
+  }
+}

package/src/lib/state.js

@@ -0,0 +1,91 @@
+/**
+ * 状态落盘：`$DSH_HOME/mc-dev-starter/state.json` 与同目录下的日志。
+ *
+ * 写入用「临时文件 + rename」：宿主被强杀时不会留下半个 JSON。
+ * @module minecraft-dev-starter/lib/state
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * 状态目录。`DSH_HOME` 优先，其次 `~/.dsh`。
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function stateDir(env = process.env) {
+  const home = env.DSH_HOME ?? join(env.USERPROFILE ?? homedir(), '.dsh')
+  return join(home, 'mc-dev-starter')
+}
+
+/**
+ * @param {string} dir
+ * @param {string} launchId
+ * @returns {string}
+ */
+export function logPath(dir, launchId) {
+  return join(dir, 'logs', `${launchId}.log`)
+}
+
+/**
+ * @typedef {object} LaunchRecord
+ * @property {string} id
+ * @property {string} root
+ * @property {string} taskPath
+ * @property {string} label
+ * @property {string} kind        client | server | data | gameTestServer
+ * @property {string} module
+ * @property {number | null} pid
+ * @property {string} startedAt
+ * @property {string | null} endedAt
+ * @property {'starting' | 'running' | 'exited' | 'unknown'} status
+ * @property {'normal' | 'crashed' | 'killed' | 'failed' | null} outcome
+ * @property {number | null} exitCode
+ * @property {string | null} signal
+ * @property {string} logPath
+ */
+
+/**
+ * @typedef {object} PersistentState
+ * @property {number} version
+ * @property {number} nextLaunch
+ * @property {LaunchRecord[]} launches
+ */
+
+/** @returns {PersistentState} */
+export function emptyState() {
+  return { version: 1, nextLaunch: 1, launches: [] }
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<PersistentState>}
+ */
+export async function loadState(dir) {
+  try {
+    const raw = await readFile(join(dir, 'state.json'), 'utf8')
+    const parsed = JSON.parse(raw)
+    if (parsed === null || typeof parsed !== 'object') return emptyState()
+    return {
+      version: Number(parsed.version ?? 1),
+      nextLaunch: Number(parsed.nextLaunch ?? 1),
+      launches: Array.isArray(parsed.launches) ? parsed.launches : [],
+    }
+  } catch {
+    return emptyState()
+  }
+}
+
+/**
+ * @param {string} dir
+ * @param {PersistentState} state
+ * @returns {Promise<void>}
+ */
+export async function saveState(dir, state) {
+  await mkdir(dir, { recursive: true })
+  const target = join(dir, 'state.json')
+  const temp = `${target}.tmp`
+  await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+  await rename(temp, target)
+}

package/src/lib/text.js

@@ -0,0 +1,92 @@
+/**
+ * 文本小工具：读文件、解析 .properties、解析 ${...} 占位符。
+ * 识别引擎的每个规则都靠这几样东西，单独放一处方便测试。
+ * @module minecraft-dev-starter/lib/text
+ */
+
+import { readFile } from 'node:fs/promises'
+
+/**
+ * 读文本文件；不存在、没权限、是目录都返回 undefined（识别过程不该因为个别文件中断）。
+ * @param {string} path
+ * @returns {Promise<string | undefined>}
+ */
+export async function readText(path) {
+  try {
+    return await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 解析 Java 风格的 .properties（`key=value`，`#`/`!` 注释）。
+ * 不处理续行与转义——Gradle 工程里几乎用不到。
+ * @param {string | undefined} text
+ * @returns {Record<string, string>}
+ */
+export function parseProperties(text) {
+  /** @type {Record<string, string>} */
+  const out = {}
+  if (!text) return out
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (line === '' || line.startsWith('#') || line.startsWith('!')) continue
+    const eq = line.indexOf('=')
+    if (eq <= 0) continue
+    const key = line.slice(0, eq).trim()
+    if (key === '') continue
+    out[key] = line.slice(eq + 1).trim()
+  }
+  return out
+}
+
+const PLACEHOLDER = /\$\{([^}]+)\}/g
+
+/**
+ * 把 `${key}` 替换成属性表里的值，替换不掉的保留原文并记下来。
+ * 元数据文件（fabric.mod.json / mods.toml）普遍写占位符，不解析就只能拿到字面量。
+ * @param {string | undefined} value
+ * @param {Record<string, string>} properties
+ * @returns {{ value: string | undefined, unresolved: string[] }}
+ */
+export function resolvePlaceholders(value, properties) {
+  if (typeof value !== 'string' || !value.includes('${')) {
+    return { value, unresolved: [] }
+  }
+  /** @type {string[]} */
+  const unresolved = []
+  const resolved = value.replace(PLACEHOLDER, (match, rawName) => {
+    const key = String(rawName).trim()
+    if (Object.hasOwn(properties, key) && properties[key] !== '') return String(properties[key])
+    unresolved.push(key)
+    return match
+  })
+  return { value: resolved, unresolved }
+}
+
+/**
+ * 取第一个命中的捕获组。
+ * @param {string | undefined} text
+ * @param {RegExp} pattern
+ * @returns {string | undefined}
+ */
+export function firstMatch(text, pattern) {
+  if (!text) return undefined
+  const match = pattern.exec(text)
+  return match?.[1]
+}
+
+/**
+ * 逐条尝试一组正则，返回第一个命中。
+ * @param {string | undefined} text
+ * @param {RegExp[]} patterns
+ * @returns {string | undefined}
+ */
+export function firstMatchOf(text, patterns) {
+  for (const pattern of patterns) {
+    const hit = firstMatch(text, pattern)
+    if (hit !== undefined) return hit
+  }
+  return undefined
+}

package/src/lib/toml.js

@@ -0,0 +1,281 @@
+/**
+ * TOML 子集解析器：只覆盖 `mods.toml` / `neoforge.mods.toml` 实际用到的语法。
+ *
+ * 支持：注释、`key = value`、基本字符串（含 `"""` / `'''` 多行）、布尔、数字、
+ * 简单数组、`[table]`、`[[array.of.tables]]`。
+ * 不支持：内联表、日期、十六进制、转义 unicode——模组元数据里没有。
+ *
+ * @module minecraft-dev-starter/lib/toml
+ */
+
+/**
+ * @typedef {Record<string, unknown>} TomlTable
+ */
+
+/**
+ * @param {string} source
+ * @returns {TomlTable}
+ */
+export function parseToml(source) {
+  /** @type {TomlTable} */
+  const root = {}
+  /** @type {TomlTable} */
+  let current = root
+  const lines = source.split(/\r?\n/)
+
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    const trimmed = line.trim()
+
+    if (trimmed === '' || trimmed.startsWith('#')) {
+      i += 1
+      continue
+    }
+
+    if (trimmed.startsWith('[[')) {
+      const close = trimmed.indexOf(']]')
+      if (close > 0) {
+        const path = trimmed.slice(2, close).trim()
+        const list = ensureArray(root, splitKey(path))
+        /** @type {TomlTable} */
+        const table = {}
+        list.push(table)
+        current = table
+      }
+      i += 1
+      continue
+    }
+
+    if (trimmed.startsWith('[')) {
+      const close = trimmed.indexOf(']')
+      if (close > 0) {
+        const path = trimmed.slice(1, close).trim()
+        current = ensureTable(root, splitKey(path))
+      }
+      i += 1
+      continue
+    }
+
+    const eq = indexOfEquals(trimmed)
+    if (eq <= 0) {
+      i += 1
+      continue
+    }
+
+    const key = unquote(trimmed.slice(0, eq).trim())
+    let rest = trimmed.slice(eq + 1).trim()
+
+    // 多行字符串：值跨行，直到出现同一对三引号
+    const triple = rest.startsWith("'''") ? "'''" : rest.startsWith('"""') ? '"""' : undefined
+    if (triple !== undefined) {
+      let body = rest.slice(3)
+      let closed = body.includes(triple)
+      while (!closed && i + 1 < lines.length) {
+        i += 1
+        body += `\n${lines[i]}`
+        closed = body.includes(triple)
+      }
+      const end = body.indexOf(triple)
+      current[key] = end >= 0 ? body.slice(0, end) : body
+      i += 1
+      continue
+    }
+
+    // 普通字符串也可能带行尾注释
+    rest = stripTrailingComment(rest)
+    current[key] = parseValue(rest)
+    i += 1
+  }
+
+  return root
+}
+
+/**
+ * 找 `=`，跳过引号内的内容。
+ * @param {string} text
+ * @returns {number}
+ */
+function indexOfEquals(text) {
+  let quote
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i]
+    if (quote !== undefined) {
+      if (ch === '\\') i += 1
+      else if (ch === quote) quote = undefined
+      continue
+    }
+    if (ch === '"' || ch === "'") quote = ch
+    else if (ch === '=') return i
+  }
+  return -1
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function stripTrailingComment(text) {
+  let quote
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i]
+    if (quote !== undefined) {
+      if (ch === '\\') i += 1
+      else if (ch === quote) quote = undefined
+      continue
+    }
+    if (ch === '"' || ch === "'") quote = ch
+    else if (ch === '#') return text.slice(0, i).trimEnd()
+  }
+  return text
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function splitKey(text) {
+  return text
+    .split('.')
+    .map((part) => unquote(part.trim()))
+    .filter((part) => part !== '')
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function unquote(text) {
+  if (text.length >= 2 && (text.startsWith('"') || text.startsWith("'"))) {
+    return text.slice(1, -1)
+  }
+  return text
+}
+
+/**
+ * @param {string} raw
+ * @returns {unknown}
+ */
+function parseValue(raw) {
+  const text = raw.trim()
+  if (text === '') return ''
+  if (text.startsWith('"') || text.startsWith("'") || text.startsWith('"""') || text.startsWith("'''")) {
+    return parseString(text)
+  }
+  if (text.startsWith('[')) return parseArray(text)
+  if (text === 'true') return true
+  if (text === 'false') return false
+  const number = Number(text)
+  return Number.isNaN(number) ? text : number
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function parseString(text) {
+  const triple = text.startsWith('"""') ? '"""' : text.startsWith("'''") ? "'''" : undefined
+  if (triple !== undefined) {
+    const body = text.slice(3)
+    const end = body.indexOf(triple)
+    return end >= 0 ? body.slice(0, end) : body
+  }
+  const quote = text[0]
+  let out = ''
+  for (let i = 1; i < text.length; i += 1) {
+    const ch = text[i]
+    if (ch === '\\' && i + 1 < text.length) {
+      const next = text[i + 1]
+      out += next === 'n' ? '\n' : next === 't' ? '\t' : next
+      i += 1
+      continue
+    }
+    if (ch === quote) break
+    out += ch
+  }
+  return out
+}
+
+/**
+ * @param {string} text
+ * @returns {Array<unknown>}
+ */
+function parseArray(text) {
+  const inner = text.slice(1, text.lastIndexOf(']'))
+  /** @type {Array<unknown>} */
+  const out = []
+  let buffer = ''
+  let quote
+  for (let i = 0; i < inner.length; i += 1) {
+    const ch = inner[i]
+    if (quote !== undefined) {
+      buffer += ch
+      if (ch === '\\') {
+        buffer += inner[i + 1] ?? ''
+        i += 1
+      } else if (ch === quote) quote = undefined
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      buffer += ch
+      continue
+    }
+    if (ch === ',') {
+      pushItem(out, buffer)
+      buffer = ''
+      continue
+    }
+    buffer += ch
+  }
+  pushItem(out, buffer)
+  return out
+}
+
+/**
+ * @param {Array<unknown>} out
+ * @param {string} raw
+ */
+function pushItem(out, raw) {
+  const text = raw.trim()
+  if (text === '') return
+  out.push(parseValue(text))
+}
+
+/**
+ * @param {TomlTable} root
+ * @param {string[]} path
+ * @returns {TomlTable}
+ */
+function ensureTable(root, path) {
+  /** @type {TomlTable} */
+  let node = root
+  for (const key of path) {
+    const next = node[key]
+    if (next !== null && typeof next === 'object' && !Array.isArray(next)) {
+      node = /** @type {TomlTable} */ (next)
+      continue
+    }
+    /** @type {TomlTable} */
+    const created = {}
+    node[key] = created
+    node = created
+  }
+  return node
+}
+
+/**
+ * @param {TomlTable} root
+ * @param {string[]} path
+ * @returns {Array<TomlTable>}
+ */
+function ensureArray(root, path) {
+  const parent = ensureTable(root, path.slice(0, -1))
+  const key = path.at(-1) ?? ''
+  const existing = parent[key]
+  if (Array.isArray(existing)) return /** @type {Array<TomlTable>} */ (existing)
+  /** @type {Array<TomlTable>} */
+  const list = []
+  parent[key] = list
+  return list
+}