dsh-ris-yds 0.0.0-stage → 1.0.0

package/lib/yms.js

@@ -0,0 +1,302 @@
+// YMS runtime: build the launch (env + JVM flags + rdbga), start in foreground
+// (for the dsh-ris-ide run-with-log wrapper) or detached (own pidfile + logs),
+// stop, status. Ports the proven work/start-yms.sh logic into cross-OS node.
+
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, openSync, closeSync, statSync, renameSync, readSync } from 'node:fs'
+import { join } from 'node:path'
+import http from 'node:http'
+import { portOpen } from './socks.js'
+import { ymsHomeIsBuilt } from './build.js'
+
+export function ymsPidFile(cfg) {
+  return join(cfg.stateDir, 'yms.pid')
+}
+
+// EXACT flag set from the proven work/start-yms.sh (YonCode launch template).
+// Do NOT edit module/package pairs from memory — wrong module names are
+// silently ignored by the JVM and break Liberty JNDI init (observed:
+// PseudoContext "no JNDI feature is configured" forever, module deploy fails).
+// The last 2 exports + 3 opens come from the YonCode-generated
+// .vscode/launch.json (ensureLaunchConfig) — same provenance, kept in sync.
+const ADD_EXPORTS = [
+  'java.base/sun.security.action=ALL-UNNAMED',
+  'java.naming/com.sun.jndi.ldap=ALL-UNNAMED',
+  'java.naming/com.sun.jndi.url.ldap=ALL-UNNAMED',
+  'jdk.naming.dns/com.sun.jndi.dns=ALL-UNNAMED',
+  'jdk.naming.dns/com.sun.jndi.url.dns=ALL-UNNAMED',
+  'java.security.jgss/sun.security.krb5.internal=ALL-UNNAMED',
+  'jdk.attach/sun.tools.attach=ALL-UNNAMED',
+  'jdk.management.agent/jdk.internal.agent=ALL-UNNAMED',
+  'java.base/jdk.internal.vm=ALL-UNNAMED',
+]
+const ADD_OPENS = [
+  'java.base/java.util=ALL-UNNAMED',
+  'java.base/java.lang=ALL-UNNAMED',
+  'java.base/java.util.concurrent=ALL-UNNAMED',
+  'java.base/java.io=ALL-UNNAMED',
+  'java.base/java.nio=ALL-UNNAMED',
+  'java.base/sun.nio.ch=ALL-UNNAMED',
+  'java.naming/javax.naming.spi=ALL-UNNAMED',
+  'java.naming/com.sun.naming.internal=ALL-UNNAMED',
+  'jdk.naming.rmi/com.sun.jndi.url.rmi=ALL-UNNAMED',
+  'java.naming/javax.naming=ALL-UNNAMED',
+  'java.rmi/java.rmi=ALL-UNNAMED',
+  'java.sql/java.sql=ALL-UNNAMED',
+  'java.management/javax.management=ALL-UNNAMED',
+  'java.base/java.lang.reflect=ALL-UNNAMED',
+  'java.desktop/java.awt.image=ALL-UNNAMED',
+  'java.base/java.security=ALL-UNNAMED',
+  'java.base/java.net=ALL-UNNAMED',
+  'java.base/java.text=ALL-UNNAMED',
+  'java.base/sun.net.www.protocol.https=ALL-UNNAMED',
+]
+
+/**
+ * rdbga cookie value (base64 of "module,/context@bind:port").
+ *
+ * Every part is validated: a half-filled config used to produce
+ * `base64("null,/@null:31010")`, and browser tools would then happily write that into
+ * the workbench — pointing the gateway at an instance that cannot exist. Fail loudly.
+ */
+export function rdbgaValue(cfg) {
+  if (cfg.module == null) throw new Error('rdbga 值缺少 module——先在项目目录下运行（yonbuilder.json / module.xml）')
+  const bind = String(cfg.serverBindAddress ?? '')
+  if (/^(\d{1,3}\.){3}\d{1,3}$/.test(bind) !== true) {
+    throw new Error('rdbga 值缺少合法的 serverBindAddress（IPv4）——补项目 .vscode/settings.json 的 yds.serverBindAddress')
+  }
+  const port = Number(cfg.serverPort)
+  if (Number.isInteger(port) !== true || port < 1 || port > 65535) {
+    throw new Error('rdbga 值缺少合法的 serverPort——补项目 .vscode/settings.json 的 yds.serverPort')
+  }
+  const context = String(cfg.context ?? '')
+  const raw = `${cfg.module},${context}@${bind}:${port}`
+  return Buffer.from(raw, 'utf8').toString('base64')
+}
+
+/** Full launch description: env, jvm args, args. */
+export function launchSpec(cfg, { jvmArgs = [] } = {}) {
+  if (cfg.module == null) throw new Error('未识别模块名')
+  const logsDir = join(cfg.ymsHome, 'logs')
+  const env = {
+    ...process.env,
+    mw_profiles_active: cfg.env,
+    YDS_STATE: 'debugging',
+    access_key: cfg.accessKey ?? '',
+    access_secret: cfg.accessSecret ?? '',
+    'access.key': cfg.accessKey ?? '',
+    'access.secret': cfg.accessSecret ?? '',
+    enable_cloud_debug: 'true',
+    YMS_ENABLE_MODULE: cfg.module,
+    yms_enable_module: cfg.module,
+  }
+  const jvm = [
+    `-DYMS_WORK_PATH=${join(cfg.ymsHome, 'workarea')}`,
+    '-DYMS-DEV=true',
+    '-DYMS-DEV-MODE=debug',
+    `-Dyms.log.path=${logsDir}`,
+    `-Dyms.dev.libProjectsFile=${join(cfg.ymsHome, '.libraryProjects.list')}`,
+    `-Dapp.metainfo.preferred-networks=${cfg.serverBindAddress}`,
+    '-Dapp.metainfo.ping_connect_timeout=200',
+    `-Ddomain.url=${cfg.workbenchUrl}`,
+    `-Dserver.port=${cfg.ymsPort}`,
+    `-Drdbga=${rdbgaValue(cfg)}`,
+    // start_mode=static: server discovery reads config/ip_node_mapping.json
+    // instead of eureka (unreachable from a dev machine) — from YonCode's
+    // generated .vscode/launch.json. Makes outbound RPC fall back to the
+    // domain.url cloud-debug rewrite for unreachable pod instances.
+    '-Dapp.metainfo.start_mode=static',
+    '-Dyms_fetch_config_version=2.0.0',
+    '-Dyms.bootstrap.enableNewConfig=true',
+    ...ADD_EXPORTS.map((v) => `--add-exports=${v}`),
+    ...ADD_OPENS.map((v) => `--add-opens=${v}`),
+    ...jvmArgs.filter((v) => typeof v === 'string' && v.trim() !== '').map((v) => v.trim()),
+  ]
+  return { java: cfg.java, env, jvm, main: 'iuap.yms.YMSLauncher', cp: join(cfg.ymsHome, 'yms.jar'), logsDir }
+}
+
+/** Ensure .javaExecutable / .libraryProjects.list exist so the home is self-contained. */
+export function ensureHomeMarkers(cfg) {
+  if (cfg.java == null) throw new Error('未找到 JDK')
+  const exe = join(cfg.ymsHome, '.javaExecutable')
+  if (!existsSync(exe)) writeFileSync(exe, cfg.java + '\n', 'utf8')
+  const libs = join(cfg.ymsHome, '.libraryProjects.list')
+  if (!existsSync(libs)) writeFileSync(libs, '\n', 'utf8')
+}
+
+/**
+ * Detached start: spawn java setsid, stdout/stderr -> yms-console.log,
+ * pidfile in .dsh-ris-yds/yms.pid. Returns { started, pid } or
+ * { alreadyRunning }.
+ */
+/** Remember the port the running instance listens on (read back by config). */
+function rememberPort(cfg) {
+  try {
+    mkdirSync(cfg.stateDir, { recursive: true })
+    writeFileSync(join(cfg.stateDir, 'yms-port'), `${cfg.ymsPort}\n`, { encoding: 'utf8' })
+  } catch { /* the port file is a convenience, never a requirement */ }
+}
+
+export async function startDetached(cfg, { jvmArgs = [] } = {}) {
+  const pidFile = ymsPidFile(cfg)
+  const running = await readRunning(cfg)
+  if (running !== null) return { started: false, alreadyRunning: true, pid: running.pid }
+  if (!ymsHomeIsBuilt(cfg)) throw new Error('yms-home 未构建（先执行 yds build）')
+  if (cfg.java == null) throw new Error('未找到 JDK——用 .env 的 java.path 或 JAVA_HOME 指定')
+  if (cfg.module == null) throw new Error('未识别模块名——检查项目 yonbuilder.json / module.xml')
+  const spec = launchSpec(cfg, { jvmArgs })
+  ensureHomeMarkers(cfg)
+  rememberPort(cfg)
+  mkdirSync(cfg.stateDir, { recursive: true })
+  const log = join(cfg.stateDir, 'yms-console.log')
+  // crude rotation: keep the last full log, never let it grow unbounded
+  try {
+    const st = statSync(log)
+    if (st.size > 16 * 1024 * 1024) renameSync(log, `${log}.old`)
+  } catch { /* absent */ }
+  const out = openSync(log, 'a')
+  const err = openSync(log, 'a')
+  const child = spawn(spec.java, [...spec.jvm, '-cp', spec.cp, spec.main], {
+    cwd: cfg.ymsHome,
+    env: spec.env,
+    detached: true,
+    stdio: ['ignore', out, err],
+    windowsHide: true,
+  })
+  child.unref()
+  // parent copies of the log fds are dup'd into the child; close ours
+  try { closeSync(out) } catch { /* ignore */ }
+  try { closeSync(err) } catch { /* ignore */ }
+  writeFileSync(pidFile, String(child.pid), 'utf8')
+  // wait for the Liberty port to accept (~35s typical; hard budget 120s)
+  let up = false
+  for (let i = 0; i < 120 && !up; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    up = await portOpen('127.0.0.1', cfg.ymsPort, 500)
+    if (!up) {
+      try { process.kill(child.pid, 0) } catch { throw new Error('YMS 进程已退出，查看 .dsh-ris-yds/yms-console.log') }
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((r) => setTimeout(r, 500))
+    }
+  }
+  if (!up) {
+    try { unlinkSync(pidFile) } catch { /* ignore */ }
+    try { process.kill(child.pid, 'SIGTERM') } catch { /* ignore */ }
+    throw new Error(`YMS 端口 ${cfg.ymsPort} 在 120 秒内未就绪——查看 ${log}`)
+  }
+  return { started: true, pid: child.pid, port: cfg.ymsPort, consoleLog: log }
+}
+
+/** Foreground start: java as our child, signals forwarded (for run-with-log wrappers). */
+export function startForeground(cfg, { jvmArgs = [], onStdout, signal } = {}) {
+  if (!ymsHomeIsBuilt(cfg)) throw new Error('yms-home 未构建（先执行 yds build）')
+  if (cfg.java == null) throw new Error('未找到 JDK——用 .env 的 java.path 或 JAVA_HOME 指定')
+  if (cfg.module == null) throw new Error('未识别模块名——检查项目 yonbuilder.json / module.xml')
+  const spec = launchSpec(cfg, { jvmArgs })
+  ensureHomeMarkers(cfg)
+  const child = spawn(spec.java, [...spec.jvm, '-cp', spec.cp, spec.main], {
+    cwd: cfg.ymsHome,
+    env: spec.env,
+    stdio: ['inherit', 'inherit', 'inherit'],
+    signal,
+    windowsHide: true,
+  })
+  const fwd = (sig) => {
+    try { child.kill(sig) } catch { /* ignore */ }
+  }
+  process.on('SIGTERM', () => fwd('SIGTERM'))
+  process.on('SIGINT', () => fwd('SIGINT'))
+  // record the java pid so `yds status` / `yds stop` are not blind to
+  // IDE-started (foreground) instances; unlink when the child goes away.
+  try {
+    mkdirSync(cfg.stateDir, { recursive: true })
+    writeFileSync(ymsPidFile(cfg), String(child.pid), 'utf8')
+    child.once('close', () => { try { unlinkSync(ymsPidFile(cfg)) } catch { /* ignore */ } })
+  } catch { /* best effort */ }
+  return child
+}
+
+/** pid is really our YMS java (cmdline marker), not a reused pid. */
+function pidIsYms(pid) {
+  try {
+    const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8')
+    return cmd.includes('yms.jar') || cmd.includes('YMSLauncher')
+  } catch { return false }
+}
+
+/** Read the pidfile; verify the process is alive AND ours; null otherwise (stale pidfile is unlinked). */
+export async function readRunning(cfg) {
+  const pidFile = ymsPidFile(cfg)
+  if (!existsSync(pidFile)) return null
+  const pid = Number(readFileSync(pidFile, 'utf8').trim())
+  if (!Number.isInteger(pid) || pid <= 0) return null
+  try { process.kill(pid, 0) } catch { try { unlinkSync(pidFile) } catch { /* ignore */ } return null }
+  if (!pidIsYms(pid)) {
+    // pid reused by an unrelated process after a crash/reboot — stale marker
+    try { unlinkSync(pidFile) } catch { /* ignore */ }
+    return null
+  }
+  return { pid }
+}
+
+/** Stop the detached YMS: TERM, grace (YMS is slow), KILL. */
+export async function stopYms(cfg, { graceMs = 30000 } = {}) {
+  const running = await readRunning(cfg) // identity-verified: never kills a reused pid
+  if (running === null) return { stopped: false, reason: '未在运行' }
+  try { process.kill(running.pid, 'SIGTERM') } catch { /* ignore */ }
+  const deadline = Date.now() + graceMs
+  while (Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((r) => setTimeout(r, 500))
+    try { process.kill(running.pid, 0) } catch { break }
+  }
+  try { process.kill(running.pid, 0); process.kill(running.pid, 'SIGKILL') } catch { /* gone */ }
+  try { unlinkSync(ymsPidFile(cfg)) } catch { /* ignore */ }
+  return { stopped: true, pid: running.pid }
+}
+
+/** Status row: process + port + forwarder + config state. */
+export async function status(cfg) {
+  const running = await readRunning(cfg) // identity-checked
+  const port = await portOpen('127.0.0.1', cfg.ymsPort, 800)
+  let ready = null
+  if (port === true) {
+    ready = await httpGet(`http://127.0.0.1:${cfg.ymsPort}/_yms/ready`, 3000)
+  }
+  return {
+    process: running,
+    port,
+    ready: ready !== null ? ready.status : null,
+    ymsHomeBuilt: ymsHomeIsBuilt(cfg),
+    configPresent: existsSync(join(cfg.ymsHome, 'config', 'yms_middleware.json')),
+    socksForwarder: cfg.socks === null ? null : await portOpen('127.0.0.1', cfg.dbForwardPort, 300),
+  }
+}
+
+function httpGet(url, timeout) {
+  return new Promise((resolve_) => {
+    const done = (value) => resolve_(value)
+    const r = http.get(url, (res) => { res.resume(); done({ status: res.statusCode }) })
+    r.setTimeout(timeout, () => { r.destroy(); done(null) })
+    r.once('error', () => done(null))
+  })
+}
+
+/** Tail helper for yds logs — reads only the last 256KB (log can be huge). */
+export function tailFile(path, lines = 80) {
+  if (!existsSync(path)) return null
+  const st = statSync(path)
+  const readSize = Math.min(st.size, 256 * 1024)
+  const fh = openSync(path, 'r')
+  try {
+    const buf = Buffer.alloc(readSize)
+    readSync(fh, buf, 0, readSize, st.size - readSize)
+    const text = buf.toString('utf8')
+    const all = text.split('\n')
+    // first line may be a partial line from the mid-file cut — drop it
+    if (readSize < st.size && all.length > 1) all.shift()
+    return all.slice(-lines).join('\n')
+  } finally {
+    closeSync(fh)
+  }
+}

package/lib/yoncode.js

@@ -0,0 +1,249 @@
+/**
+ * YonCode host patching.
+ *
+ * YonCode derives the address it advertises to the platform (serverBindAddress)
+ * from a local NIC. When `.vscode/settings.json` points it at a callback address
+ * the machine does not own — the normal case behind NAT, in WSL, or through a
+ * port forward — it refuses to launch with
+ * "Invalid IP address, no interface found with address <ip>".
+ *
+ * We cannot fix that from our side: the check lives in YonCode's bundled
+ * extension (`resources/app/extensions/yonbuilder-development-studio-core/dist/
+ * extension.js`). This module detects whether the check is still active and can
+ * turn the throw into a warning — with a `.bak` next to it, so it can be undone
+ * and re-applied after a YonCode upgrade rewrites the file.
+ *
+ * Nothing here touches the project; it is opt-in from the user (the agent asks
+ * before writing into a Program Files directory).
+ */
+
+import { copyFileSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Marker our patch leaves in the bundle (also how a patch is detected). */
+export const YONCODE_PATCH_MARKER = '[yds-patch]'
+
+/** The file we patch, relative to the YonCode installation directory. */
+export const YONCODE_EXTENSION_RELATIVE = 'resources/app/extensions/yonbuilder-development-studio-core/dist/extension.js'
+
+/** Matches the `if (!ipv4IsValid(ipv4)) { throw … }` block in the shipped bundle. */
+const VALIDATION_RE = /if\s*\(\s*!\s*_util\.ipv4IsValid\([^)]*\)\s*\)\s*\{\s*throw new Error\([^;]*?\);\s*\}/
+
+/**
+ * The YMS launch `vmArgs` snippet YonCode builds — the anchor we insert the JVM
+ * proxy flags after. It is a plain template string in the bundle.
+ */
+const SOCKS_ANCHOR = /-Dapp\.metainfo\.preferred-networks=\\?\$\{command:yds\.serverBindAddress\} -Dserver\.port=\\?\$\{config:yds\.serverPort\}/
+
+/** Our injected flags, so a re-patch replaces instead of stacking. */
+const SOCKS_FLAGS_RE = / -DsocksProxyHost=[^\s"']+ -DsocksProxyPort=\d+/
+
+/**
+ * Why this exists: ProxyBridge (WinDivert) breaks the Oracle TNS handshake —
+ * the connection is accepted, then reset right after `T2C7Oversion.doOVERSION`,
+ * so the YMS module cannot reach its database. A JVM started with
+ * `-DsocksProxyHost` opens an ordinary TCP connection through the SOCKS server
+ * instead, which is the same path that already works from WSL.
+ * @param socks - `{host, port}` from `.env` (`socks.host`/`socks.port`).
+ * @returns the flags to append, or null when no SOCKS server is configured.
+ */
+export function socksFlags(socks) {
+  const host = typeof socks?.host === 'string' ? socks.host.trim() : ''
+  const port = Number(socks?.port)
+  if (host === '' || !Number.isInteger(port) || port <= 0 || port > 65535) return null
+  return ` -DsocksProxyHost=${host} -DsocksProxyPort=${port}`
+}
+
+/**
+ * Where a YonCode install may be, most specific first.
+ *
+ * `cfg.yoncodeHome` (`.env` `yoncode.home` or `YONCODE_HOME`) wins; otherwise the
+ * platform defaults, including the Windows drives WSL can see.
+ * @param cfg - resolved plugin config (`cfg.yoncodeHome` optional).
+ * @returns candidate installation directories.
+ */
+export function yoncodeCandidates(cfg = {}) {
+  const out = []
+  const push = (value) => {
+    if (typeof value === 'string' && value !== '' && !out.includes(value)) out.push(value)
+  }
+  // An explicit location is authoritative: if it is wrong we report "absent"
+  // rather than silently inspecting some other installation.
+  const explicit = typeof cfg.yoncodeHome === 'string' && cfg.yoncodeHome !== ''
+    ? cfg.yoncodeHome
+    : (typeof process.env.YONCODE_HOME === 'string' && process.env.YONCODE_HOME !== '' ? process.env.YONCODE_HOME : '')
+  if (explicit !== '') return [explicit]
+  if (process.platform === 'win32') {
+    push('C:\\Program Files\\YonCode')
+    push('D:\\Program Files\\YonCode')
+  }
+  if (process.platform === 'darwin') {
+    push('/Applications/YonCode.app/Contents/Resources/app')
+    push(join(homedir(), 'Applications/YonCode.app/Contents/Resources/app'))
+  }
+  push('/opt/YonCode')
+  push('/usr/share/YonCode')
+  push('/usr/local/YonCode')
+  // A Windows install reached from WSL.
+  for (const drive of ['c', 'd', 'e']) push(`/mnt/${drive}/Program Files/YonCode`)
+  return out
+}
+
+/**
+ * Read the bundle and classify it.
+ *
+ * States: `patched` (our warning is in place), `unpatched` (the throw is still
+ * there), `unrecognised` (file exists but has neither shape — a different
+ * YonCode version we refuse to guess about), `absent` (no installation found),
+ * `incomplete` (directory exists without the bundle).
+ * @param cfg - resolved plugin config.
+ * @returns `{ found, home, file, state, backup, detail }`.
+ */
+export function detectYoncode(cfg = {}) {
+  let seenIncomplete = null
+  for (const home of yoncodeCandidates(cfg)) {
+    const file = join(home, YONCODE_EXTENSION_RELATIVE)
+    if (!existsSync(file)) {
+      if (seenIncomplete === null && existsSync(home)) seenIncomplete = home
+      continue
+    }
+    let text = ''
+    try {
+      if (statSync(file).size > 32 * 1024 * 1024) return { found: true, home, file, state: 'unrecognised', backup: null, detail: '文件过大，跳过' }
+      text = readFileSync(file, 'utf8')
+    } catch (error) {
+      return { found: true, home, file, state: 'unrecognised', backup: null, detail: `无法读取：${error instanceof Error ? error.message : String(error)}` }
+    }
+    const backup = `${file}.bak`
+    const hasBackup = existsSync(backup)
+    const socksMatch = SOCKS_FLAGS_RE.exec(text)
+    const socksValue = socksMatch === null ? '' : socksMatch[0].trim()
+    const socksState = socksMatch !== null ? 'patched' : SOCKS_ANCHOR.test(text) ? 'unpatched' : 'unrecognised'
+    const withSocks = (result) => ({ ...result, found: true, home, file, socksState, socksValue, backup: hasBackup ? backup : null })
+    if (text.includes(YONCODE_PATCH_MARKER)) {
+      return withSocks({ state: 'patched', detail: '网卡 IP 校验已改为告警' })
+    }
+    if (VALIDATION_RE.test(text)) {
+      return withSocks({ state: 'unpatched', detail: '网卡 IP 校验仍在（serverBindAddress 不是本机网卡时拒绝启动）' })
+    }
+    return withSocks({ state: 'unrecognised', detail: '找不到校验代码，可能是不认识的 YonCode 版本' })
+  }
+  if (seenIncomplete !== null) {
+    return { found: true, home: seenIncomplete, file: join(seenIncomplete, YONCODE_EXTENSION_RELATIVE), state: 'incomplete', backup: null, detail: '安装目录存在但没找到 YonCode 扩展包' }
+  }
+  return { found: false, home: null, file: null, state: 'absent', backup: null, detail: '没有找到 YonCode 安装（可用 .env 的 yoncode.home 指定）' }
+}
+
+/** True when the failure was a permission problem, i.e. elevation would help. */
+function isPermissionError(error) {
+  const code = error?.code ?? ''
+  return code === 'EACCES' || code === 'EPERM' || code === 'EROFS' || /permission denied/i.test(error?.message ?? '')
+}
+
+/**
+ * Patch the bundle: turn the NIC check into a warning, and (optionally) append the
+ * JVM SOCKS flags to the YMS launch arguments.
+ *
+ * Both edits share one `.bak` of the untouched file, so {@link restoreYoncode}
+ * undoes them together. Idempotent: an already patched bundle reports
+ * `changed: false`.
+ * @param detected - the result of {@link detectYoncode}.
+ * @param {{socks?: {host: string, port: number}}} [options] - SOCKS server to inject.
+ * @returns `{ ok, changed, state, socksState, error?, needElevation? }`.
+ */
+export function patchYoncode(detected, options = {}) {
+  if (!detected.found) return { ok: false, changed: false, state: detected.state, socksState: detected.socksState, error: detected.detail }
+  const flags = socksFlags(options.socks)
+  const wantsSocks = flags !== null
+  const needsValidation = detected.state === 'unpatched'
+  // Same flags already in place → nothing to do; a *different* SOCKS server must
+  // replace the old pair instead of stacking a second one.
+  const needsSocks = wantsSocks && (detected.socksState !== 'patched' || (detected.socksValue ?? '') !== flags.trim())
+  if (!needsValidation && !needsSocks) {
+    // `ok` means "the bundle has every edit this call asked for": the NIC check
+    // when it was still active, the JVM flags when a SOCKS server was given.
+    const ok = detected.state === 'patched' && (!wantsSocks || detected.socksState === 'patched')
+    const error = ok
+      ? undefined
+      : detected.socksState === 'unrecognised' && wantsSocks
+        ? '找不到 YMS 启动参数模板，无法注入 JVM 代理参数'
+        : detected.detail
+    return { ok, changed: false, state: detected.state, socksState: detected.socksState, error }
+  }
+  try {
+    let text = readFileSync(detected.file, 'utf8')
+    if (needsValidation && !VALIDATION_RE.test(text)) return { ok: false, changed: false, state: 'unrecognised', socksState: detected.socksState, error: '文件内容已变化，无法定位校验代码' }
+    if (needsSocks && !SOCKS_FLAGS_RE.test(text) && !SOCKS_ANCHOR.test(text)) {
+      return { ok: false, changed: false, state: detected.state, socksState: 'unrecognised', error: '找不到 YMS 启动参数模板，无法注入 JVM 代理参数' }
+    }
+    if (!existsSync(`${detected.file}.bak`)) copyFileSync(detected.file, `${detected.file}.bak`)
+    if (needsValidation) {
+      text = text.replace(VALIDATION_RE, (block) => {
+        const match = /ipv4IsValid\(([^)]*)\)/.exec(block)
+        const argument = match === null ? 'ipv4' : match[1].trim()
+        return `if (!_util.ipv4IsValid(${argument})) {\n            console.warn("${YONCODE_PATCH_MARKER} serverBindAddress " + ${argument} + " is not a local NIC IP, skip validation");\n        }`
+      })
+    }
+    if (needsSocks) {
+      text = SOCKS_FLAGS_RE.test(text)
+        ? text.replace(SOCKS_FLAGS_RE, flags)
+        : text.replace(SOCKS_ANCHOR, (anchor) => anchor + flags)
+    }
+    writeFileSync(detected.file, text)
+    return {
+      ok: true,
+      changed: true,
+      state: needsValidation ? 'patched' : detected.state,
+      socksState: needsSocks ? 'patched' : detected.socksState,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, changed: false, state: detected.state, socksState: detected.socksState, error: message, needElevation: isPermissionError(error) }
+  }
+}
+
+/**
+ * Put the original bundle back from `.bak`.
+ * @param detected - the result of {@link detectYoncode}.
+ * @returns `{ ok, changed, state, error?, needElevation? }`.
+ */
+export function restoreYoncode(detected) {
+  const backup = detected.backup ?? (detected.file === null ? null : `${detected.file}.bak`)
+  if (backup === null || !existsSync(backup)) {
+    return { ok: false, changed: false, state: detected.state, error: '没有 .bak 备份，无法还原（重装 YonCode 也会恢复原文件）' }
+  }
+  try {
+    copyFileSync(backup, detected.file)
+    return { ok: true, changed: true, state: 'unpatched' }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, changed: false, state: detected.state, error: message, needElevation: isPermissionError(error) }
+  }
+}
+
+/**
+ * One-line summary for `yds doctor` and the CLI.
+ * @param detected - the result of {@link detectYoncode}.
+ * @returns human readable line.
+ */
+export function describeYoncode(detected) {
+  if (!detected.found) return `yoncode: ${detected.detail}`
+  const where = detected.home ?? detected.file
+  const socks = detected.socksState === 'patched' ? '，JVM 代理参数已注入' : ''
+  return `yoncode: ${detected.state}（${detected.detail}${socks}）${where === null ? '' : ` · ${where}`}`
+}
+
+/**
+ * Should we warn the user about the launch configuration we are about to write?
+ *
+ * Only when YonCode is installed AND its check is active: an absent YonCode is
+ * not a problem (we run standalone), and a patched one is already fine.
+ * @param detected - the result of {@link detectYoncode}.
+ * @returns the warning text, or null.
+ */
+export function yoncodeWarning(detected) {
+  if (!detected.found || detected.state !== 'unpatched') return null
+  return 'YonCode 仍在校验 serverBindAddress 必须是本机网卡 IP；用外网/端口转发/回调地址启动会失败。'
+    + '可以让 ris-yds 把该校验改成告警（需写 YonCode 安装目录的权限），运行 `yds yoncode patch` 或让我代做。'
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "dsh-ris-yds",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "YonBIP YDS local runtime for the DSH agent: config resolution (project settings.json + optional .env), YYCToken, confcenter sync, SOCKS forward, yms-home build/start/stop with JDWP, and dsh-ris-ide run-config integration. Cross-OS (linux/darwin/win32, WSL aware). · YonBIP YDS 本地运行时：项目配置解析（settings.json / .env）、YYCToken、confcenter 拉取、SOCKS 转发、yms-home 构建与启停（含 JDWP 调试）、dsh-ris-ide 启动器集成；跨平台（linux/darwin/win32，识别 WSL）。",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ris-cloud/dsh-ris-yds.git"
+  },
+  "homepage": "https://gitee.com/riscloud/dsh-ris-yds#readme",
+  "bugs": {
+    "url": "https://gitee.com/riscloud/dsh-ris-yds/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "yds",
+    "yonbip",
+    "yonyou",
+    "yms",
+    "liberty"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "cordis.patch.yml"
+    }
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./cli": "./lib/cli.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "yds": "bin/yds.js"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "bin",
+    "cordis.patch.yml",
+    "lib",
+    "native",
+    "resources",
+    "skills",
+    "test",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=18",
+    "dsh": ">=0.2.0-rc.2"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "check:listing": "node bin/check-listing.mjs"
+  }
+}