dsh-runnpu 0.1.0-rc.1

package/bin/dsh-runnpu.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+/**
+ * `dsh-runnpu` — the parts of installing this package that npm cannot do:
+ * the agent presets (real directories under $DSH_HOME/.agent-presets) and the
+ * two host CLIs the modes drive.
+ *
+ *   dsh-runnpu install <compute|training|all> [--force] [--profile <name|dir>] [--with-cli]
+ *   dsh-runnpu uninstall <compute|training|all> [--force]
+ *   dsh-runnpu status
+ *   dsh-runnpu doctor
+ *   dsh-runnpu cli <runnpu|swanlab|all> [--from <archive|dir|url>] [--bin-dir <dir>] [--python <exe>] [--dry-run]
+ *
+ * `--profile web` additionally adds "dsh-runnpu" to that profile's
+ * `dsh.profile.bundles` (a name resolves under $DSH_HOME/profiles/, a path is
+ * used as is). The dependency itself is `pnpm add dsh-runnpu`'s job.
+ *
+ * `--with-cli` runs `cli` for what the mode needs after the presets:
+ * compute → runnpu; training → runnpu + swanlab. `doctor` only reports.
+ *
+ * DSH_HOME overrides ~/.dsh. RUNNPU_BIN_DIR overrides ~/.local/bin.
+ * GITHUB_TOKEN / GH_TOKEN is sent when downloading from a private GitHub mirror.
+ */
+
+import { delimiter, join } from 'node:path'
+
+import {
+  defaultBinDir,
+  doctor,
+  installRunnpu,
+  installSwanlab,
+  onPath,
+  platformKey,
+  readPins,
+  runnpuDownloadUrl,
+  runnpuReleaseDir,
+} from './cli-deps.mjs'
+import {
+  MODES,
+  PACKAGE_NAME,
+  dshHome,
+  inspectTarget,
+  installPreset,
+  mountInProfile,
+  presetRoot,
+  profileDir,
+  selectModes,
+  uninstallPreset,
+} from './presets.mjs'
+
+const USAGE = `usage:
+  ${PACKAGE_NAME} install <compute|training|all> [--force] [--link] [--profile <name|dir>] [--with-cli]
+  ${PACKAGE_NAME} uninstall <compute|training|all> [--force]
+  ${PACKAGE_NAME} status
+  ${PACKAGE_NAME} doctor
+  ${PACKAGE_NAME} cli <runnpu|swanlab|all> [--from <archive|dir|url>] [--bin-dir <dir>] [--python <exe>] [--dry-run]
+
+  install     copy the preset(s) into $DSH_HOME/.agent-presets/<id> (DSH_HOME defaults to ~/.dsh)
+  --force     replace / remove a preset directory this package did not install
+  --profile   also add "${PACKAGE_NAME}" to <profile>/package.json → dsh.profile.bundles
+  --with-cli  then install the host CLIs the mode needs (compute: runnpu; training: runnpu + swanlab)
+  --link      dev only: symlink instead of copy (a symlinked preset is NOT discovered by dsh)
+  doctor      check runnpu / swanlab on PATH against the versions this package was built for
+  cli         install runnpu (pinned build, from the release or --from) and/or swanlab (uv > pipx > pip)
+  --from      runnpu source: a local runnpu_<ver>_<os>_<arch>.tar.gz/.zip, an extracted directory, or a URL
+  --bin-dir   where runnpu goes (default $RUNNPU_BIN_DIR or ~/.local/bin)
+  --python    interpreter for swanlab (default: uv tool, else pipx, else python3 -m pip --user)
+`
+
+/** @param {string[]} argv */
+function parse(argv) {
+  const flags = {
+    force: false,
+    link: false,
+    withCli: false,
+    dryRun: false,
+    profile: /** @type {string | undefined} */ (undefined),
+    from: /** @type {string | undefined} */ (undefined),
+    binDir: /** @type {string | undefined} */ (undefined),
+    python: /** @type {string | undefined} */ (undefined),
+  }
+  const valued = { '--profile': 'profile', '--from': 'from', '--bin-dir': 'binDir', '--python': 'python' }
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    const eq = arg.indexOf('=')
+    const key = eq > 0 ? arg.slice(0, eq) : arg
+    if (key in valued) {
+      const value = eq > 0 ? arg.slice(eq + 1) : argv[++i]
+      if (!value) throw new Error(`${key} needs a value`)
+      flags[valued[key]] = value
+    } else if (arg === '--force') flags.force = true
+    else if (arg === '--link') flags.link = true
+    else if (arg === '--with-cli') flags.withCli = true
+    else if (arg === '--dry-run') flags.dryRun = true
+    else if (arg === '-h' || arg === '--help') positional.push('help')
+    else if (arg.startsWith('-')) throw new Error(`unknown flag ${arg}`)
+    else positional.push(arg)
+  }
+  return { command: positional[0], selector: positional[1], flags }
+}
+
+/** @param {string} home */
+async function status(home) {
+  console.log(`preset root: ${presetRoot(home)}`)
+  for (const mode of MODES) {
+    const target = join(presetRoot(home), mode.id)
+    const state = await inspectTarget(target, mode.from)
+    const label = { absent: 'not installed', ours: 'installed', 'our-link': 'symlinked (dev only, not discovered)', foreign: 'present, not ours' }[state]
+    console.log(`  ${mode.id.padEnd(9)} ${mode.display}  ${label}`)
+  }
+}
+
+/**
+ * Print the doctor report; returns whether everything checked out.
+ * @param {NodeJS.ProcessEnv} [env] PATH to probe (default: this process's)
+ */
+async function runDoctor(env = process.env) {
+  const pins = await readPins()
+  const findings = await doctor(pins, env)
+  for (const f of findings) {
+    const mark = f.ok ? '✓' : '✗'
+    const where = f.path ? `${f.path}` : '(not found)'
+    console.log(`${mark} ${f.name.padEnd(8)} ${(f.version ?? '-').padEnd(16)} want ${f.want.padEnd(10)} ${where}`)
+    if (!f.ok) console.log(`    ${f.detail}`)
+  }
+  const bad = findings.filter(f => !f.ok)
+  if (bad.length) {
+    console.log(`\nfix: ${PACKAGE_NAME} cli ${bad.length === 2 ? 'all' : bad[0].name}`)
+  }
+  return bad.length === 0
+}
+
+/**
+ * @param {('runnpu' | 'swanlab')[]} which
+ * @param {ReturnType<typeof parse>['flags']} flags
+ */
+async function runCli(which, flags) {
+  const pins = await readPins()
+  // The verification pass after installing looks in the install dir first, so
+  // it reports the binary just installed even when that dir is not on PATH yet.
+  let checkEnv = process.env
+  if (which.includes('runnpu')) {
+    const plat = platformKey()
+    const binDir = flags.binDir ?? defaultBinDir()
+    checkEnv = { ...process.env, PATH: [binDir, process.env.PATH ?? ''].filter(Boolean).join(delimiter) }
+    const source = flags.from ?? runnpuDownloadUrl(pins.runnpu, plat)
+    if (flags.dryRun) {
+      console.log(`runnpu: would install build ${pins.runnpu.version} from ${source} → ${join(binDir, `runnpu${plat.exe}`)}`)
+    } else {
+      console.log(`runnpu: installing build ${pins.runnpu.version} (${plat.os}/${plat.arch}) from ${source}`)
+      try {
+        const result = await installRunnpu({ pin: pins.runnpu, from: flags.from, binDir, plat })
+        console.log(`✓ runnpu ${result.version ?? ''} → ${result.path}`)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        throw new Error(
+          `${message}\n` +
+            `  The runnpu build must match the vendored skill (${pins.runnpu.version}). If the release asset is not\n` +
+            `  reachable (offline cluster → use the archive the RunNPU console ships, a mirror → its URL),\n` +
+            `  pass it with --from <archive|dir|url>. Release: ${runnpuReleaseDir(pins.runnpu)}`,
+        )
+      }
+      if (!onPath(binDir)) {
+        console.log(`\n⚠ ${binDir} is not on PATH — add it, e.g.\n  fish:     fish_add_path ${binDir}\n  bash/zsh: echo 'export PATH="${binDir}:$PATH"' >> ~/.profile`)
+      }
+    }
+  }
+  if (which.includes('swanlab')) {
+    const result = await installSwanlab({ pin: pins.swanlab, python: flags.python, dryRun: flags.dryRun })
+    const cmd = result.plan.argv.join(' ')
+    if (flags.dryRun) console.log(`swanlab: would run (${result.plan.tool}): ${cmd}`)
+    else if (result.ok) console.log(`✓ swanlab installed via ${result.plan.tool}: ${cmd}`)
+    else throw new Error(`swanlab install failed (${cmd}):\n${result.output}`)
+  }
+  if (!flags.dryRun) {
+    console.log('')
+    await runDoctor(checkEnv)
+  }
+}
+
+async function main() {
+  const { command, selector, flags } = parse(process.argv.slice(2))
+  const home = dshHome()
+
+  if (!command || command === 'help') {
+    console.log(USAGE)
+    return
+  }
+  if (command === 'status') {
+    await status(home)
+    return
+  }
+  if (command === 'doctor') {
+    process.exitCode = (await runDoctor()) ? 0 : 1
+    return
+  }
+  if (command === 'cli') {
+    const which = selector === 'all' ? ['runnpu', 'swanlab'] : selector === 'runnpu' || selector === 'swanlab' ? [selector] : undefined
+    if (!which) throw new Error(`cli: expected runnpu | swanlab | all, got ${JSON.stringify(selector ?? '')}`)
+    await runCli(/** @type {('runnpu' | 'swanlab')[]} */ (which), flags)
+    return
+  }
+  if (command !== 'install' && command !== 'uninstall') throw new Error(`unknown command ${command}\n${USAGE}`)
+
+  const modes = selectModes(selector)
+
+  if (command === 'uninstall') {
+    for (const mode of modes) {
+      const result = await uninstallPreset(mode, { home, force: flags.force })
+      console.log(`${result === 'removed' ? 'removed' : 'not installed'}: ${mode.id} (${mode.display})`)
+    }
+    return
+  }
+
+  for (const mode of modes) {
+    const target = await installPreset(mode, { home, force: flags.force, link: flags.link })
+    console.log(`installed ${mode.id} (${mode.display}) → ${target}${flags.link ? ' (symlink, dev only)' : ''}`)
+  }
+
+  if (flags.profile) {
+    const dir = profileDir(flags.profile, home)
+    const changed = await mountInProfile(dir)
+    console.log(`${changed ? 'added' : 'already in'} dsh.profile.bundles: ${join(dir, 'package.json')}`)
+  }
+
+  if (flags.withCli) {
+    const needSwanlab = modes.some(mode => mode.id === 'training')
+    console.log('')
+    await runCli(needSwanlab ? ['runnpu', 'swanlab'] : ['runnpu'], flags)
+  }
+
+  if (flags.profile) {
+    const dir = profileDir(flags.profile, home)
+    console.log(`
+Next:
+  cd ${dir} && pnpm install     # if "${PACKAGE_NAME}" is not yet in dependencies: pnpm add ${PACKAGE_NAME}
+  restart dsh, then start a NEW session and pick the mode in the picker.${flags.withCli ? '' : `\n  host CLIs: ${PACKAGE_NAME} doctor   (install with: ${PACKAGE_NAME} cli all)`}
+`)
+    return
+  }
+
+  console.log(`
+Next, mount the plugin bundle in the dsh profile you run (usually $DSH_HOME/profiles/web):
+
+  1. dependencies:          pnpm add ${PACKAGE_NAME}      (already done if you are running this via npx from that profile)
+  2. dsh.profile.bundles:   add "${PACKAGE_NAME}"        (or re-run with --profile <name|dir>)
+  3. host CLIs:             ${PACKAGE_NAME} doctor        (install with: ${PACKAGE_NAME} cli all)
+  4. restart dsh, then start a NEW session and pick the mode in the picker.
+`)
+}
+
+main().catch(error => {
+  console.error(`${PACKAGE_NAME}: ${error instanceof Error ? error.message : String(error)}`)
+  process.exit(1)
+})

package/bin/presets.mjs

@@ -0,0 +1,167 @@
+/**
+ * Preset installation — the logic behind the `dsh-runnpu` bin and
+ * `scripts/install-presets.mjs`.
+ *
+ * A dsh agent preset lives at `<dshHome>/.agent-presets/<id>` and MUST be a
+ * real directory: a symlinked preset is silently not discovered by the roster
+ * (the picker just lists the shipped presets, no error anywhere). npm cannot
+ * put files there, which is the whole reason this installer exists.
+ *
+ * The preset yml cannot carry an absolute skill path from the author's
+ * machine, so it carries `__DSH_PRESET_ROOT__` and the real root is resolved
+ * here, on the machine the preset is installed onto.
+ *
+ * @module dsh-runnpu/bin/presets
+ */
+
+import { cp, lstat, mkdir, readFile, readlink, rm, symlink, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const PACKAGE_NAME = 'dsh-runnpu'
+
+/** Repo / installed-package root: this file sits in `<root>/bin/`. */
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** @typedef {{ id: 'compute' | 'training', display: string, from: string }} Mode */
+
+/** @type {readonly Mode[]} */
+export const MODES = Object.freeze([
+  { id: 'compute', display: '算力管理模式', from: join(packageRoot, 'compute-mode', 'preset') },
+  { id: 'training', display: '训练模式', from: join(packageRoot, 'training-mode', 'preset') },
+])
+
+/** Marks a copy as ours, so a re-install replaces it without --force. */
+export const MARKER = `.installed-by-${PACKAGE_NAME}`
+/** Markers written by earlier releases of this package, still recognised as ours. */
+const LEGACY_MARKERS = ['.installed-by-dsh-runnpu-modes']
+
+export const PLACEHOLDER = '__DSH_PRESET_ROOT__'
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function dshHome(env = process.env) {
+  return env.DSH_HOME || join(homedir(), '.dsh')
+}
+
+/** @param {string} home */
+export function presetRoot(home) {
+  return join(home, '.agent-presets')
+}
+
+/**
+ * Resolve `compute` / `training` / `all` to modes; throws on anything else.
+ * @param {string | undefined} selector
+ * @returns {Mode[]}
+ */
+export function selectModes(selector) {
+  if (selector === 'all') return [...MODES]
+  const mode = MODES.find(m => m.id === selector)
+  if (!mode) {
+    throw new Error(`unknown mode ${JSON.stringify(selector ?? '')}: expected ${MODES.map(m => m.id).join(' | ')} | all`)
+  }
+  return [mode]
+}
+
+/**
+ * What sits at the preset's target path, if anything.
+ * @param {string} target
+ * @param {string} from
+ * @returns {Promise<'absent' | 'ours' | 'our-link' | 'foreign'>}
+ */
+export async function inspectTarget(target, from) {
+  let existing
+  try {
+    existing = await lstat(target)
+  } catch {
+    return 'absent'
+  }
+  if (existing.isSymbolicLink()) return (await readlink(target)) === from ? 'our-link' : 'foreign'
+  if ([MARKER, ...LEGACY_MARKERS].some(marker => existsSync(join(target, marker)))) return 'ours'
+  return 'foreign'
+}
+
+/**
+ * Install one mode's preset. Returns the target path.
+ *
+ * `link` symlinks instead of copying — dev-only: the roster does NOT discover
+ * a symlinked preset, and the placeholder is served verbatim. Kept for
+ * experiments, never for a working install.
+ *
+ * @param {Mode} mode
+ * @param {{ home?: string, force?: boolean, link?: boolean }} [options]
+ */
+export async function installPreset(mode, { home = dshHome(), force = false, link = false } = {}) {
+  const root = presetRoot(home)
+  const target = join(root, mode.id)
+  await mkdir(root, { recursive: true })
+
+  const state = await inspectTarget(target, mode.from)
+  if (state === 'foreign' && !force) {
+    throw new Error(
+      `refusing to replace ${target}: it exists and was not installed by ${PACKAGE_NAME} (pass --force to replace)`,
+    )
+  }
+  if (state !== 'absent') await rm(target, { recursive: true, force: true })
+
+  if (link) {
+    await symlink(mode.from, target, 'dir')
+    return target
+  }
+
+  await cp(mode.from, target, { recursive: true, filter: src => !src.endsWith('.DS_Store') })
+  const cordis = join(target, 'agent.cordis.yml')
+  await writeFile(cordis, (await readFile(cordis, 'utf8')).replaceAll(PLACEHOLDER, root), 'utf8')
+  await writeFile(join(target, MARKER), `installed from ${mode.from}\n`, 'utf8')
+  return target
+}
+
+/**
+ * Remove one mode's preset. Only removes what we installed unless forced.
+ * @param {Mode} mode
+ * @param {{ home?: string, force?: boolean }} [options]
+ * @returns {Promise<'removed' | 'absent'>}
+ */
+export async function uninstallPreset(mode, { home = dshHome(), force = false } = {}) {
+  const target = join(presetRoot(home), mode.id)
+  const state = await inspectTarget(target, mode.from)
+  if (state === 'absent') return 'absent'
+  if (state === 'foreign' && !force) {
+    throw new Error(`refusing to remove ${target}: it was not installed by ${PACKAGE_NAME} (pass --force to remove)`)
+  }
+  await rm(target, { recursive: true, force: true })
+  return 'removed'
+}
+
+/**
+ * Resolve `--profile web` (a name under `<dshHome>/profiles/`) or a path to
+ * the profile directory.
+ * @param {string} profile
+ * @param {string} home
+ */
+export function profileDir(profile, home) {
+  if (isAbsolute(profile) || profile.startsWith('.') || profile.includes('/')) return resolve(profile)
+  return join(home, 'profiles', profile)
+}
+
+/**
+ * Add this package to a profile's `dsh.profile.bundles`. Does NOT touch
+ * `dependencies` — that is `pnpm add`'s job — and does not run the package
+ * manager. Returns whether the file changed.
+ *
+ * @param {string} dir profile directory (holds package.json)
+ */
+export async function mountInProfile(dir) {
+  const file = join(dir, 'package.json')
+  if (!existsSync(file)) throw new Error(`no package.json in ${dir}: is this a dsh profile directory?`)
+  const text = await readFile(file, 'utf8')
+  const pkg = JSON.parse(text)
+  const profile = { ...(pkg.dsh?.profile ?? {}) }
+  const bundles = Array.isArray(profile.bundles) ? [...profile.bundles] : []
+  if (bundles.includes(PACKAGE_NAME)) return false
+  bundles.push(PACKAGE_NAME)
+  pkg.dsh = { ...(pkg.dsh ?? {}), profile: { ...profile, bundles } }
+  await writeFile(file, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+  return true
+}