@swarmclawai/swarmclaw 1.0.0 → 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

@@ -1,6 +1,7 @@
 #!/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')
@@ -143,13 +144,51 @@ function detectGlobalInstallManagerForRoot(pkgRoot, execImpl = execFileSync, env
   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

@@ -10,7 +10,9 @@ 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', () => {
@@ -59,3 +61,61 @@ test('detectGlobalInstallManagerForRoot matches the owning global root by realpa
 
   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 })
+})

package/bin/server-cmd.js

@@ -5,7 +5,6 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const { spawn, execFileSync } = require('node:child_process')
-const os = require('node:os')
 const {
   detectPackageManager,
   getInstallCommand,
@@ -13,21 +12,30 @@ const {
 const {
   readPackageVersion,
   resolvePackageRoot,
+  resolveStateHome,
 } = require('./install-root.js')
 
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
 
-const SWARMCLAW_HOME = process.env.SWARMCLAW_HOME || path.join(os.homedir(), '.swarmclaw')
 const PKG_ROOT = resolvePackageRoot({
   moduleDir: __dirname,
   argv1: process.argv[1],
   cwd: process.cwd(),
 })
+const SWARMCLAW_HOME = resolveStateHome({
+  pkgRoot: PKG_ROOT,
+  moduleDir: __dirname,
+  argv1: process.argv[1],
+  cwd: process.cwd(),
+  env: process.env,
+})
 const PID_FILE = path.join(SWARMCLAW_HOME, 'server.pid')
 const LOG_FILE = path.join(SWARMCLAW_HOME, 'server.log')
 const DATA_DIR = path.join(SWARMCLAW_HOME, 'data')
+const WORKSPACE_DIR = path.join(SWARMCLAW_HOME, 'workspace')
+const BROWSER_PROFILES_DIR = path.join(SWARMCLAW_HOME, 'browser-profiles')
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -67,6 +75,10 @@ function resolveStandaloneBase(pkgRoot = PKG_ROOT) {
   return path.join(pkgRoot, '.next', 'standalone')
 }
 
+function isGitCheckout(pkgRoot = PKG_ROOT) {
+  return fs.existsSync(path.join(pkgRoot, '.git'))
+}
+
 function getVersion() {
   return readPackageVersion(PKG_ROOT) || 'unknown'
 }
@@ -99,11 +111,12 @@ function runBuild({ pkgRoot = PKG_ROOT } = {}) {
   const nextCli = ensurePackageDependencies(pkgRoot)
 
   log('Building Next.js application (this may take a minute)...')
-  execFileSync(process.execPath, [nextCli, 'build'], {
+  execFileSync(process.execPath, [nextCli, 'build', '--webpack'], {
     cwd: pkgRoot,
     stdio: 'inherit',
     env: {
       ...process.env,
+      SWARMCLAW_HOME,
       DATA_DIR,
       SWARMCLAW_BUILD_MODE: '1',
     },
@@ -162,7 +175,10 @@ function startServer(opts, { pkgRoot = PKG_ROOT } = {}) {
 
   const env = {
     ...process.env,
+    SWARMCLAW_HOME,
     DATA_DIR,
+    WORKSPACE_DIR,
+    BROWSER_PROFILES_DIR,
     HOSTNAME: host,
     PORT: port,
     WS_PORT: wsPort,
@@ -170,6 +186,7 @@ function startServer(opts, { pkgRoot = PKG_ROOT } = {}) {
 
   log(`Starting server on ${host}:${port} (WebSocket: ${wsPort})...`)
   log(`Package root: ${pkgRoot}`)
+  log(`Home: ${SWARMCLAW_HOME}`)
   log(`Data directory: ${DATA_DIR}`)
 
   if (opts.detach) {
@@ -248,6 +265,8 @@ function showStatus() {
   log(`Package: ${PKG_ROOT}`)
   log(`Home: ${SWARMCLAW_HOME}`)
   log(`Data: ${DATA_DIR}`)
+  log(`Workspace: ${WORKSPACE_DIR}`)
+  log(`Browser profiles: ${BROWSER_PROFILES_DIR}`)
   log(`WebSocket port: ${process.env.WS_PORT || '(PORT + 1)'}`)
 
   const serverJs = findStandaloneServer()
@@ -282,8 +301,7 @@ Options:
   console.log(help)
 }
 
-function main() {
-  const args = process.argv.slice(3)
+function main(args = process.argv.slice(3)) {
   let command = 'start'
   let forceBuild = false
   let detach = false
@@ -330,7 +348,17 @@ function main() {
   }
 
   if (needsBuild(forceBuild)) {
-    runBuild()
+    if (!forceBuild) {
+      const installKind = isGitCheckout() ? 'checkout' : 'installed package'
+      log(`Standalone server bundle not found in this ${installKind}. Building locally...`)
+    }
+    try {
+      runBuild()
+    } catch (err) {
+      logError(`Build failed: ${err.message}`)
+      logError('Retry manually with: swarmclaw server --build')
+      process.exit(1)
+    }
   }
 
   startServer({ port, wsPort, host, detach })
@@ -342,10 +370,13 @@ if (require.main === module) {
 
 module.exports = {
   DATA_DIR,
+  BROWSER_PROFILES_DIR,
   PKG_ROOT,
   SWARMCLAW_HOME,
+  WORKSPACE_DIR,
   findStandaloneServer,
   getVersion,
+  isGitCheckout,
   main,
   needsBuild,
   resolveStandaloneBase,

package/bin/swarmclaw.js

@@ -96,6 +96,19 @@ function normalizeLegacyCliEnv(env) {
   return nextEnv
 }
 
+function printPackageVersion() {
+  const pkg = require('../package.json')
+  process.stdout.write(`${pkg.name || 'swarmclaw'} ${pkg.version || '0.0.0'}\n`)
+}
+
+function printVersionHelp() {
+  process.stdout.write(`
+Usage: swarmclaw version
+
+Show the installed SwarmClaw package version.
+`.trim() + '\n')
+}
+
 async function runMappedCli(argv) {
   const cliPath = path.join(__dirname, '..', 'src', 'cli', 'index.js')
   const cliModule = await import(cliPath)
@@ -106,25 +119,91 @@ async function runMappedCli(argv) {
   return runCli(argv)
 }
 
+async function runHelp(argv) {
+  const [target, ...rest] = argv
+  if (!target) {
+    const code = await runMappedCli(['--help'])
+    process.exitCode = typeof code === 'number' ? code : 1
+    return
+  }
+
+  if (target === 'run' || target === 'start' || target === 'stop' || target === 'status' || target === 'server') {
+    require('./server-cmd.js').main(['--help'])
+    return
+  }
+  if (target === 'worker') {
+    require('./worker-cmd.js').main(['--help'])
+    return
+  }
+  if (target === 'doctor') {
+    require('./doctor-cmd.js').main(['--help'])
+    return
+  }
+  if (target === 'update') {
+    require('./update-cmd.js').main(['--help'])
+    return
+  }
+  if (target === 'version') {
+    printVersionHelp()
+    return
+  }
+
+  const forwarded = rest.includes('--help') || rest.includes('-h')
+    ? [target, ...rest]
+    : [target, ...rest, '--help']
+  const code = shouldUseLegacyTsCli(forwarded)
+    ? runLegacyTsCli(forwarded)
+    : await runMappedCli(forwarded)
+
+  process.exitCode = typeof code === 'number' ? code : 1
+}
+
 async function main() {
   const argv = process.argv.slice(2)
   const top = argv[0]
 
   // Default to 'server' when invoked with no arguments.
   if (!top) {
-    require('./server-cmd.js').main()
+    require('./server-cmd.js').main([])
+    return
+  }
+
+  if (top === '-v') {
+    printPackageVersion()
+    return
+  }
+
+  if (top === 'version' && argv.length === 1) {
+    printPackageVersion()
     return
   }
 
-  // Route 'server', 'worker', and 'update' subcommands to CJS scripts (no TS dependency).
+  if (top === 'help') {
+    await runHelp(argv.slice(1))
+    return
+  }
+
+  // Route local lifecycle/maintenance commands to CJS scripts (no TS dependency).
   if (top === 'server') {
-    require('./server-cmd.js').main()
+    require('./server-cmd.js').main(argv.slice(1))
+    return
+  }
+  if (top === 'run' || top === 'start') {
+    require('./server-cmd.js').main(argv.slice(1))
+    return
+  }
+  if (top === 'status' || top === 'stop') {
+    require('./server-cmd.js').main([top, ...argv.slice(1)])
     return
   }
   if (top === 'worker') {
     require('./worker-cmd.js').main()
     return
   }
+  if (top === 'doctor') {
+    require('./doctor-cmd.js').main(argv.slice(1))
+    return
+  }
   if (top === 'update') {
     require('./update-cmd.js').main()
     return
@@ -146,6 +225,7 @@ module.exports = {
   hasTsxRuntime,
   TS_CLI_ACTIONS,
   normalizeLegacyCliEnv,
+  printPackageVersion,
   supportsStripTypes,
   shouldUseLegacyTsCli,
 }

package/bin/update-cmd.js

@@ -75,7 +75,6 @@ function runRegistrySelfUpdate(
   packageManager = resolveRegistryPackageManager(),
   execImpl = execFileSync,
   logger = { log, logError },
-  rebuildImpl = execFileSync,
 ) {
   const update = getGlobalUpdateSpec(packageManager, PACKAGE_NAME)
   logger.log(`No git checkout detected. Updating the global ${PACKAGE_NAME} install via ${packageManager}...`)
@@ -92,15 +91,11 @@ function runRegistrySelfUpdate(
     return 1
   }
 
-  const rebuildExitCode = rebuildStandaloneServer(rebuildImpl, logger)
-  if (rebuildExitCode !== 0) return rebuildExitCode
-
   logger.log('Restart the server to apply changes: swarmclaw server stop && swarmclaw server start')
   return 0
 }
 
-function main() {
-  const args = process.argv.slice(3)
+function main(args = process.argv.slice(3)) {
   if (args.includes('-h') || args.includes('--help')) {
     console.log(`
 Usage: swarmclaw update

package/bin/update-cmd.test.js

@@ -3,11 +3,10 @@
 
 const test = require('node:test')
 const assert = require('node:assert/strict')
-const path = require('node:path')
 
 const { runRegistrySelfUpdate } = require('./update-cmd.js')
 
-test('runRegistrySelfUpdate executes the manager-specific global update command and rebuilds the standalone server', () => {
+test('runRegistrySelfUpdate executes the manager-specific global update command', () => {
   const messages = []
   const captured = []
 
@@ -20,9 +19,6 @@ test('runRegistrySelfUpdate executes the manager-specific global update command
       log: (message) => messages.push(`log:${message}`),
       logError: (message) => messages.push(`err:${message}`),
     },
-    (command, args, options) => {
-      captured.push({ command, args, options })
-    },
   )
 
   assert.equal(exitCode, 0)
@@ -36,20 +32,9 @@ test('runRegistrySelfUpdate executes the manager-specific global update command
         timeout: 120_000,
       },
     },
-    {
-      command: process.execPath,
-      args: [path.join(process.cwd(), 'bin', 'server-cmd.js'), '--build'],
-      options: {
-        cwd: process.cwd(),
-        stdio: 'inherit',
-        timeout: 600_000,
-      },
-    },
   ])
   assert.match(messages.join('\n'), /updating the global @swarmclawai\/swarmclaw install via pnpm/i)
   assert.match(messages.join('\n'), /global update complete via pnpm/i)
-  assert.match(messages.join('\n'), /rebuilding the standalone server bundle/i)
-  assert.match(messages.join('\n'), /standalone server bundle rebuilt/i)
 })
 
 test('runRegistrySelfUpdate reports a manual retry command when the registry update fails', () => {
@@ -70,23 +55,3 @@ test('runRegistrySelfUpdate reports a manual retry command when the registry upd
   assert.match(messages.join('\n'), /registry update failed: spawn bun ENOENT/i)
   assert.match(messages.join('\n'), /retry manually with: bun add -g @swarmclawai\/swarmclaw@latest/i)
 })
-
-test('runRegistrySelfUpdate reports a manual rebuild command when the rebuild step fails', () => {
-  const messages = []
-
-  const exitCode = runRegistrySelfUpdate(
-    'npm',
-    () => {},
-    {
-      log: (message) => messages.push(`log:${message}`),
-      logError: (message) => messages.push(`err:${message}`),
-    },
-    () => {
-      throw new Error('build failed')
-    },
-  )
-
-  assert.equal(exitCode, 1)
-  assert.match(messages.join('\n'), /standalone rebuild failed: build failed/i)
-  assert.match(messages.join('\n'), /retry manually with: swarmclaw server --build/i)
-})