@swarmclawai/swarmclaw 0.9.9 → 1.0.2

package/bin/doctor-cmd.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+'use strict'
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { readPackageVersion } = require('./install-root.js')
+const {
+  PKG_ROOT,
+  SWARMCLAW_HOME,
+  findStandaloneServer,
+  isGitCheckout,
+} = require('./server-cmd.js')
+
+function readPid(pidFile) {
+  try {
+    const pid = Number.parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10)
+    return Number.isFinite(pid) ? pid : null
+  } catch {
+    return null
+  }
+}
+
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function buildDoctorReport(opts = {}) {
+  const pkgRoot = opts.pkgRoot || PKG_ROOT
+  const homeDir = opts.homeDir || SWARMCLAW_HOME
+  const pidFile = path.join(homeDir, 'server.pid')
+  const dataDir = path.join(homeDir, 'data')
+  const workspaceDir = path.join(homeDir, 'workspace')
+  const browserProfilesDir = path.join(homeDir, 'browser-profiles')
+  const nextCliPath = path.join(pkgRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
+  const standaloneServer = findStandaloneServer({ pkgRoot })
+  const pid = readPid(pidFile)
+  const running = pid ? isProcessRunning(pid) : false
+
+  const serverState = !pid
+    ? 'not-running'
+    : running
+      ? 'running'
+      : 'stale-pid'
+
+  const recommendations = []
+  if (!standaloneServer) {
+    if (fs.existsSync(nextCliPath)) {
+      recommendations.push('Standalone bundle is missing. Run `swarmclaw run` to build it automatically or `swarmclaw server --build` to prebuild it now.')
+    } else {
+      recommendations.push('Next.js build dependencies are missing from this install. Reinstall the package before starting SwarmClaw.')
+    }
+  }
+  if (serverState === 'stale-pid') {
+    recommendations.push('A stale PID file was found. Run `swarmclaw stop` to clean it up.')
+  }
+
+  return {
+    packageVersion: readPackageVersion(pkgRoot) || 'unknown',
+    packageRoot: pkgRoot,
+    installKind: isGitCheckout(pkgRoot) ? 'git' : 'package',
+    homeDir,
+    dataDir,
+    workspaceDir,
+    browserProfilesDir,
+    server: {
+      state: serverState,
+      pid,
+      pidFile,
+    },
+    build: {
+      standaloneServer,
+      nextCliPresent: fs.existsSync(nextCliPath),
+      nextCliPath,
+    },
+    recommendations,
+  }
+}
+
+function printHelp() {
+  process.stdout.write(`
+Usage: swarmclaw doctor [--json]
+
+Show local installation and build diagnostics for SwarmClaw.
+`.trim() + '\n')
+}
+
+function printHumanReport(report) {
+  const lines = [
+    `Package version: ${report.packageVersion}`,
+    `Install kind: ${report.installKind}`,
+    `Package root: ${report.packageRoot}`,
+    `Home: ${report.homeDir}`,
+    `Data: ${report.dataDir}`,
+    `Workspace: ${report.workspaceDir}`,
+    `Browser profiles: ${report.browserProfilesDir}`,
+    `Server: ${report.server.state}${report.server.pid ? ` (PID: ${report.server.pid})` : ''}`,
+    `Standalone bundle: ${report.build.standaloneServer ? `yes (${report.build.standaloneServer})` : 'no'}`,
+    `Next CLI available: ${report.build.nextCliPresent ? 'yes' : 'no'}`,
+  ]
+
+  if (report.recommendations.length > 0) {
+    lines.push('', 'Recommendations:')
+    for (const recommendation of report.recommendations) {
+      lines.push(`- ${recommendation}`)
+    }
+  }
+
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+function main(args = process.argv.slice(3)) {
+  const json = args.includes('--json')
+  if (args.includes('-h') || args.includes('--help')) {
+    printHelp()
+    process.exit(0)
+  }
+
+  const unknown = args.filter((arg) => arg !== '--json')
+  if (unknown.length > 0) {
+    process.stderr.write(`[swarmclaw] Unknown argument: ${unknown[0]}\n`)
+    printHelp()
+    process.exit(1)
+  }
+
+  const report = buildDoctorReport()
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return
+  }
+  printHumanReport(report)
+}
+
+if (require.main === module) {
+  main()
+}
+
+module.exports = {
+  buildDoctorReport,
+  isProcessRunning,
+  main,
+  readPid,
+}

package/bin/doctor-cmd.test.js

@@ -0,0 +1,50 @@
+'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const { buildDoctorReport } = require('./doctor-cmd.js')
+
+test('buildDoctorReport recommends a local build when standalone output is missing', () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-doctor-'))
+  const pkgRoot = path.join(tempDir, 'pkg')
+  const homeDir = path.join(tempDir, '.swarmclaw')
+  const nextCli = path.join(pkgRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
+
+  fs.mkdirSync(path.dirname(nextCli), { recursive: true })
+  fs.mkdirSync(homeDir, { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, 'package.json'), JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.1' }), 'utf8')
+  fs.writeFileSync(nextCli, '#!/usr/bin/env node\n', 'utf8')
+
+  const report = buildDoctorReport({ pkgRoot, homeDir })
+
+  assert.equal(report.installKind, 'package')
+  assert.equal(report.build.nextCliPresent, true)
+  assert.equal(report.build.standaloneServer, null)
+  assert.match(report.recommendations.join('\n'), /swarmclaw run/)
+
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+test('buildDoctorReport flags stale PID files', () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-doctor-stale-'))
+  const pkgRoot = path.join(tempDir, 'pkg')
+  const homeDir = path.join(tempDir, '.swarmclaw')
+  const pidFile = path.join(homeDir, 'server.pid')
+
+  fs.mkdirSync(homeDir, { recursive: true })
+  fs.mkdirSync(pkgRoot, { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, 'package.json'), JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.1' }), 'utf8')
+  fs.writeFileSync(pidFile, '999999\n', 'utf8')
+
+  const report = buildDoctorReport({ pkgRoot, homeDir })
+
+  assert.equal(report.server.state, 'stale-pid')
+  assert.match(report.recommendations.join('\n'), /swarmclaw stop/)
+
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})

package/bin/install-root.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict'
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { execFileSync } = require('node:child_process')
+
+const PACKAGE_NAME = '@swarmclawai/swarmclaw'
+const CORE_PACKAGE_NAMES = new Set([PACKAGE_NAME])
+
+function normalizeDir(value) {
+  if (!value) return null
+  const trimmed = String(value).trim()
+  if (!trimmed) return null
+  return path.resolve(trimmed)
+}
+
+function readPackageJson(rootDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function readPackageName(rootDir) {
+  return readPackageJson(rootDir)?.name?.trim() || null
+}
+
+function readPackageVersion(rootDir) {
+  const version = readPackageJson(rootDir)?.version
+  return typeof version === 'string' && version.trim() ? version.trim() : null
+}
+
+function* iterAncestorDirs(startDir, maxDepth = 12) {
+  let current = path.resolve(startDir)
+  for (let i = 0; i < maxDepth; i += 1) {
+    yield current
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+}
+
+function findPackageRoot(startDir, maxDepth = 12) {
+  for (const current of iterAncestorDirs(startDir, maxDepth)) {
+    const name = readPackageName(current)
+    if (name && CORE_PACKAGE_NAMES.has(name)) return current
+  }
+  return null
+}
+
+function candidateDirsFromArgv1(argv1) {
+  const normalized = normalizeDir(argv1)
+  if (!normalized) return []
+
+  const candidates = [path.dirname(normalized)]
+  try {
+    const resolved = fs.realpathSync(normalized)
+    if (resolved !== normalized) candidates.push(path.dirname(resolved))
+  } catch {}
+
+  const parts = normalized.split(path.sep)
+  const binIndex = parts.lastIndexOf('.bin')
+  if (binIndex > 0 && parts[binIndex - 1] === 'node_modules') {
+    const binName = path.basename(normalized)
+    const nodeModulesDir = parts.slice(0, binIndex).join(path.sep)
+    candidates.push(path.join(nodeModulesDir, binName))
+  }
+
+  return candidates
+}
+
+function resolvePackageRoot(opts = {}) {
+  const candidates = []
+  const moduleDir = normalizeDir(opts.moduleDir)
+  if (moduleDir) candidates.push(moduleDir)
+  const argv1 = opts.argv1 === undefined ? process.argv[1] : opts.argv1
+  candidates.push(...candidateDirsFromArgv1(argv1))
+  const cwd = opts.cwd === undefined ? process.cwd() : opts.cwd
+  if (normalizeDir(cwd)) candidates.push(path.resolve(cwd))
+
+  for (const candidate of candidates) {
+    const found = findPackageRoot(candidate)
+    if (found) return found
+  }
+
+  return moduleDir ? path.resolve(moduleDir, '..') : null
+}
+
+function tryRealpath(targetPath) {
+  try {
+    return fs.realpathSync(targetPath)
+  } catch {
+    return path.resolve(targetPath)
+  }
+}
+
+function runRootCommand(command, args, execImpl = execFileSync) {
+  try {
+    return String(execImpl(command, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })).trim()
+  } catch {
+    return null
+  }
+}
+
+function resolveGlobalRoot(manager, execImpl = execFileSync, env = process.env) {
+  if (manager === 'bun') {
+    const bunInstall = String(env.BUN_INSTALL || '').trim() || path.join(os.homedir(), '.bun')
+    return path.join(bunInstall, 'install', 'global', 'node_modules')
+  }
+
+  if (manager === 'pnpm') {
+    return runRootCommand('pnpm', ['root', '-g'], execImpl)
+  }
+
+  return runRootCommand('npm', ['root', '-g'], execImpl)
+}
+
+function detectGlobalInstallManagerForRoot(pkgRoot, execImpl = execFileSync, env = process.env) {
+  const pkgReal = tryRealpath(pkgRoot)
+
+  for (const manager of ['npm', 'pnpm']) {
+    const globalRoot = resolveGlobalRoot(manager, execImpl, env)
+    if (!globalRoot) continue
+
+    for (const name of CORE_PACKAGE_NAMES) {
+      const expectedReal = tryRealpath(path.join(globalRoot, name))
+      if (path.resolve(expectedReal) === path.resolve(pkgReal)) return manager
+    }
+  }
+
+  const bunRoot = resolveGlobalRoot('bun', execImpl, env)
+  for (const name of CORE_PACKAGE_NAMES) {
+    const expectedReal = tryRealpath(path.join(bunRoot, name))
+    if (path.resolve(expectedReal) === path.resolve(pkgReal)) return 'bun'
+  }
+
+  return null
+}
+
+function findLocalInstallProjectRoot(pkgRoot) {
+  const normalized = normalizeDir(pkgRoot)
+  if (!normalized) return null
+
+  const marker = `${path.sep}node_modules${path.sep}`
+  const idx = normalized.indexOf(marker)
+  if (idx === -1) return null
+
+  const projectRoot = normalized.slice(0, idx)
+  return projectRoot ? path.resolve(projectRoot) : path.parse(normalized).root
+}
+
+function resolveStateHome(opts = {}) {
+  const env = opts.env || process.env
+  const explicitHome = normalizeDir(env.SWARMCLAW_HOME)
+  if (explicitHome) return explicitHome
+
+  const pkgRoot = normalizeDir(opts.pkgRoot)
+    || resolvePackageRoot({
+      moduleDir: opts.moduleDir,
+      argv1: opts.argv1,
+      cwd: opts.cwd,
+    })
+  if (!pkgRoot) return path.join(os.homedir(), '.swarmclaw')
+
+  const execImpl = opts.execImpl || execFileSync
+  if (detectGlobalInstallManagerForRoot(pkgRoot, execImpl, env)) {
+    return path.join(os.homedir(), '.swarmclaw')
+  }
+
+  const projectRoot = findLocalInstallProjectRoot(pkgRoot)
+  if (projectRoot) return path.join(projectRoot, '.swarmclaw')
+
+  return path.join(os.homedir(), '.swarmclaw')
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  candidateDirsFromArgv1,
+  detectGlobalInstallManagerForRoot,
+  findPackageRoot,
+  findLocalInstallProjectRoot,
+  readPackageName,
+  readPackageVersion,
+  resolveGlobalRoot,
+  resolvePackageRoot,
+  resolveStateHome,
+}

package/bin/install-root.test.js

@@ -0,0 +1,121 @@
+'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const {
+  candidateDirsFromArgv1,
+  detectGlobalInstallManagerForRoot,
+  findLocalInstallProjectRoot,
+  resolvePackageRoot,
+  resolveStateHome,
+} = require('./install-root.js')
+
+test('candidateDirsFromArgv1 includes the package directory for node_modules/.bin launchers', () => {
+  const launcher = path.join('/tmp', 'example', 'node_modules', '.bin', 'swarmclaw')
+  const candidates = candidateDirsFromArgv1(launcher)
+  assert.deepEqual(candidates, [
+    path.join('/tmp', 'example', 'node_modules', '.bin'),
+    path.join('/tmp', 'example', 'node_modules', 'swarmclaw'),
+  ])
+})
+
+test('resolvePackageRoot finds the package root from argv1 candidates', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-install-root-'))
+  const pkgRoot = path.join(rootDir, 'node_modules', '@swarmclawai', 'swarmclaw')
+  const binPath = path.join(rootDir, 'node_modules', '.bin', 'swarmclaw')
+  const actualBin = path.join(pkgRoot, 'bin', 'swarmclaw.js')
+
+  fs.mkdirSync(path.join(pkgRoot, 'bin'), { recursive: true })
+  fs.mkdirSync(path.dirname(binPath), { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, 'package.json'), JSON.stringify({ name: '@swarmclawai/swarmclaw' }), 'utf8')
+  fs.writeFileSync(actualBin, '#!/usr/bin/env node\n', 'utf8')
+  fs.symlinkSync(actualBin, binPath)
+
+  assert.equal(resolvePackageRoot({ argv1: binPath, cwd: rootDir }), fs.realpathSync(pkgRoot))
+
+  fs.rmSync(rootDir, { recursive: true, force: true })
+})
+
+test('detectGlobalInstallManagerForRoot matches the owning global root by realpath', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-global-root-'))
+  const npmGlobalRoot = path.join(rootDir, 'npm-global')
+  const pnpmGlobalRoot = path.join(rootDir, 'pnpm-global')
+  const pkgRoot = path.join(pnpmGlobalRoot, '@swarmclawai', 'swarmclaw')
+
+  fs.mkdirSync(path.join(npmGlobalRoot, '@swarmclawai'), { recursive: true })
+  fs.mkdirSync(path.join(pnpmGlobalRoot, '@swarmclawai'), { recursive: true })
+  fs.mkdirSync(pkgRoot, { recursive: true })
+
+  const execImpl = (command, args) => {
+    if (command === 'npm' && args.join(' ') === 'root -g') return npmGlobalRoot
+    if (command === 'pnpm' && args.join(' ') === 'root -g') return pnpmGlobalRoot
+    throw new Error(`unexpected command: ${command} ${args.join(' ')}`)
+  }
+
+  assert.equal(detectGlobalInstallManagerForRoot(pkgRoot, execImpl), 'pnpm')
+
+  fs.rmSync(rootDir, { recursive: true, force: true })
+})
+
+test('findLocalInstallProjectRoot returns the project root for nested pnpm installs', () => {
+  const pkgRoot = path.join(
+    '/tmp',
+    'example',
+    'node_modules',
+    '.pnpm',
+    '@swarmclawai+swarmclaw@1.0.1',
+    'node_modules',
+    '@swarmclawai',
+    'swarmclaw',
+  )
+
+  assert.equal(findLocalInstallProjectRoot(pkgRoot), path.join('/tmp', 'example'))
+})
+
+test('resolveStateHome prefers the local project .swarmclaw directory for local installs', () => {
+  const projectRoot = path.join('/tmp', 'example')
+  const pkgRoot = path.join(projectRoot, 'node_modules', '@swarmclawai', 'swarmclaw')
+  const execImpl = () => {
+    throw new Error('unexpected global root lookup')
+  }
+
+  assert.equal(
+    resolveStateHome({
+      pkgRoot,
+      env: {},
+      execImpl,
+    }),
+    path.join(projectRoot, '.swarmclaw'),
+  )
+})
+
+test('resolveStateHome keeps global installs under the user home directory', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-state-home-'))
+  const npmGlobalRoot = path.join(rootDir, 'npm-global')
+  const pkgRoot = path.join(npmGlobalRoot, '@swarmclawai', 'swarmclaw')
+
+  fs.mkdirSync(path.join(npmGlobalRoot, '@swarmclawai'), { recursive: true })
+  fs.mkdirSync(pkgRoot, { recursive: true })
+
+  const execImpl = (command, args) => {
+    if (command === 'npm' && args.join(' ') === 'root -g') return npmGlobalRoot
+    if (command === 'pnpm' && args.join(' ') === 'root -g') return path.join(rootDir, 'pnpm-global')
+    throw new Error(`unexpected command: ${command} ${args.join(' ')}`)
+  }
+
+  assert.equal(
+    resolveStateHome({
+      pkgRoot,
+      env: {},
+      execImpl,
+    }),
+    path.join(os.homedir(), '.swarmclaw'),
+  )
+
+  fs.rmSync(rootDir, { recursive: true, force: true })
+})