@swarmclawai/swarmclaw 1.0.0 → 1.0.3

package/src/cli/binary.test.js

@@ -119,6 +119,51 @@ test('binary server help exits successfully', () => {
   assert.match(result.stdout, /Usage: swarmclaw server/i)
 })
 
+test('binary run alias routes to server help', () => {
+  const result = runBinary(['run', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw server/i)
+})
+
+test('binary help command shows root help', () => {
+  const result = runBinary(['help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /SwarmClaw CLI/i)
+  assert.match(result.stdout, /swarmclaw help \[command\]/i)
+})
+
+test('binary help command shows command help for run alias', () => {
+  const result = runBinary(['help', 'run'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw server/i)
+})
+
+test('binary help command shows command help for doctor alias', () => {
+  const result = runBinary(['help', 'doctor'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw doctor/i)
+})
+
+test('binary status alias routes to local server status', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-binary-status-'))
+  const result = runBinary(['status'], {
+    env: {
+      SWARMCLAW_HOME: homeDir,
+    },
+  })
+
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Server: not running/i)
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+})
+
+test('binary doctor help exits successfully', () => {
+  const result = runBinary(['doctor', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw doctor/i)
+})
+
 test('binary update help exits successfully', () => {
   const result = runBinary(['update', '--help'])
   assert.equal(result.status, 0, result.stderr)
@@ -131,6 +176,18 @@ test('binary version output matches package version', () => {
   assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
 })
 
+test('binary bare version alias output matches package version', () => {
+  const result = runBinary(['version'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
+})
+
+test('binary -v alias output matches package version', () => {
+  const result = runBinary(['-v'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
+})
+
 test('legacy TS launcher falls back to tsx import when strip-types is unavailable', () => {
   const cliPath = path.join(APP_ROOT, 'src', 'cli', 'index.ts')
   const args = buildLegacyTsCliArgs(cliPath, ['runs', 'list'], {

package/src/cli/index.js

@@ -1183,6 +1183,9 @@ function renderGeneralHelp() {
     'SwarmClaw CLI',
     '',
     'Usage:',
+    '  swarmclaw',
+    '  swarmclaw help [command]',
+    '  swarmclaw run|start|stop|status|doctor|update|version',
     '  swarmclaw <group> <command> [args] [options]',
     '',
     'Global options:',
@@ -1199,6 +1202,15 @@ function renderGeneralHelp() {
     '  --help                 Show help',
     '  --version              Show package version',
     '',
+    'Top-level commands:',
+    '  run, start             Start the SwarmClaw server',
+    '  stop                   Stop the detached SwarmClaw server',
+    '  status                 Show local server status',
+    '  doctor                 Show local install/build diagnostics',
+    '  help                   Show root or command help',
+    '  update                 Update this SwarmClaw installation',
+    '  version                Show package version',
+    '',
     'Groups:',
   ]
 
@@ -1210,7 +1222,7 @@ function renderGeneralHelp() {
     }
   }
 
-  lines.push('', 'Use "swarmclaw <group> --help" for group commands.')
+  lines.push('', 'Use "swarmclaw help <command>" or "swarmclaw <group> --help" for more detail.')
   return lines.join('\n')
 }
 

package/src/cli/server-cmd.test.js

@@ -58,3 +58,80 @@ test('findStandaloneServer recursively resolves nested standalone server paths',
   fs.rmSync(homeDir, { recursive: true, force: true })
   fs.rmSync(pkgRoot, { recursive: true, force: true })
 })
+
+test('resolvePackageBuildRoot uses a versioned workspace for registry installs', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  fs.writeFileSync(
+    path.join(pkgRoot, 'package.json'),
+    JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.2' }),
+    'utf8',
+  )
+
+  assert.equal(
+    serverCmd.resolvePackageBuildRoot(pkgRoot),
+    path.join(homeDir, 'builds', 'package-1.0.2'),
+  )
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
+})
+
+test('findStandaloneServer falls back to the external build workspace for registry installs', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  fs.writeFileSync(
+    path.join(pkgRoot, 'package.json'),
+    JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.2' }),
+    'utf8',
+  )
+
+  const nestedServer = path.join(
+    serverCmd.resolvePackageBuildRoot(pkgRoot),
+    '.next',
+    'standalone',
+    'Users',
+    'wayde',
+    'Dev',
+    'swarmclaw',
+    'server.js',
+  )
+  fs.mkdirSync(path.dirname(nestedServer), { recursive: true })
+  fs.writeFileSync(nestedServer, 'console.log("ok")\n', 'utf8')
+
+  assert.equal(serverCmd.findStandaloneServer({ pkgRoot }), nestedServer)
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
+})
+
+test('prepareBuildWorkspace copies the package tree and links node_modules outside node_modules paths', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
+  const externalNodeModules = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-node-modules-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  fs.writeFileSync(
+    path.join(pkgRoot, 'package.json'),
+    JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.2' }),
+    'utf8',
+  )
+  fs.mkdirSync(path.join(pkgRoot, 'src', 'app'), { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, 'src', 'app', 'page.tsx'), 'export default function Page() { return null }\n', 'utf8')
+
+  const buildRoot = serverCmd.resolvePackageBuildRoot(pkgRoot)
+  serverCmd.prepareBuildWorkspace({ pkgRoot, buildRoot, nodeModulesDir: externalNodeModules })
+
+  assert.equal(fs.readFileSync(path.join(buildRoot, 'package.json'), 'utf8'), fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'))
+  assert.equal(fs.readFileSync(path.join(buildRoot, 'src', 'app', 'page.tsx'), 'utf8'), 'export default function Page() { return null }\n')
+  assert.equal(fs.lstatSync(path.join(buildRoot, 'node_modules')).isSymbolicLink(), true)
+  assert.equal(fs.realpathSync(path.join(buildRoot, 'node_modules')), fs.realpathSync(externalNodeModules))
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
+  fs.rmSync(externalNodeModules, { recursive: true, force: true })
+})

package/src/lib/server/data-dir.test.ts

@@ -60,9 +60,9 @@ describe('data-dir resolution', () => {
 
     try {
       const env = { ...process.env, HOME: fakeHome, npm_lifecycle_event: 'build:ci' }
-      delete (env as any).DATA_DIR
-      delete (env as any).WORKSPACE_DIR
-      delete (env as any).BROWSER_PROFILES_DIR
+      delete env.DATA_DIR
+      delete env.WORKSPACE_DIR
+      delete env.BROWSER_PROFILES_DIR
 
       const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', `
         const modNs = await import('./src/lib/server/data-dir')
@@ -90,4 +90,39 @@ describe('data-dir resolution', () => {
       fs.rmSync(tempDir, { recursive: true, force: true })
     }
   })
+
+  it('derives runtime directories from SWARMCLAW_HOME when set', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-data-dir-home-'))
+    const fakeHome = path.join(tempDir, 'home')
+    const swarmclawHome = path.join(tempDir, 'project', '.swarmclaw')
+
+    try {
+      const env = { ...process.env, HOME: fakeHome, SWARMCLAW_HOME: swarmclawHome }
+      delete env.DATA_DIR
+      delete env.WORKSPACE_DIR
+      delete env.BROWSER_PROFILES_DIR
+
+      const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', `
+        const modNs = await import('./src/lib/server/data-dir')
+        const mod = modNs.default || modNs['module.exports'] || modNs
+        console.log(JSON.stringify({
+          dataDir: mod.DATA_DIR,
+          workspaceDir: mod.WORKSPACE_DIR,
+          browserProfilesDir: mod.BROWSER_PROFILES_DIR,
+        }))
+      `], {
+        cwd: repoRoot,
+        env,
+        encoding: 'utf-8',
+      })
+
+      assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+      const payload = extractLastJson(result.stdout || '')
+      assert.equal(payload.dataDir, path.join(swarmclawHome, 'data'))
+      assert.equal(payload.workspaceDir, path.join(swarmclawHome, 'workspace'))
+      assert.equal(payload.browserProfilesDir, path.join(swarmclawHome, 'browser-profiles'))
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
 })

package/src/lib/server/data-dir.ts

@@ -13,9 +13,16 @@ function isBuildBootstrapEnv(env: NodeJS.ProcessEnv = process.env, argv: string[
 
 export const IS_BUILD_BOOTSTRAP = isBuildBootstrapEnv()
 
+function resolveSwarmclawHome(): string | null {
+  const configured = process.env.SWARMCLAW_HOME?.trim()
+  return configured ? path.resolve(configured) : null
+}
+
 function resolveDataDir(): string {
   if (process.env.DATA_DIR) return process.env.DATA_DIR
   if (IS_BUILD_BOOTSTRAP) return path.join(os.tmpdir(), 'swarmclaw-build-data')
+  const appHome = resolveSwarmclawHome()
+  if (appHome) return path.join(appHome, 'data')
   return path.join(process.cwd(), 'data')
 }
 
@@ -41,6 +48,8 @@ function supportsChildWrites(dir: string): boolean {
 function resolveWorkspaceDir(): string {
   if (process.env.WORKSPACE_DIR) return process.env.WORKSPACE_DIR
   if (IS_BUILD_BOOTSTRAP) return path.join(DATA_DIR, 'workspace')
+  const appHome = resolveSwarmclawHome()
+  if (appHome) return path.join(appHome, 'workspace')
   const external = path.join(os.homedir(), '.swarmclaw', 'workspace')
   if (supportsChildWrites(external)) {
     return external
@@ -53,6 +62,8 @@ export const WORKSPACE_DIR = resolveWorkspaceDir()
 function resolveBrowserProfilesDir(): string {
   if (process.env.BROWSER_PROFILES_DIR) return process.env.BROWSER_PROFILES_DIR
   if (IS_BUILD_BOOTSTRAP) return path.join(DATA_DIR, 'browser-profiles')
+  const appHome = resolveSwarmclawHome()
+  if (appHome) return path.join(appHome, 'browser-profiles')
   const external = path.join(os.homedir(), '.swarmclaw', 'browser-profiles')
   if (supportsChildWrites(external)) {
     return external

package/src/lib/server/openclaw/health.ts

@@ -1,6 +1,8 @@
 import { deriveOpenClawWsUrl, normalizeOpenClawEndpoint } from '@/lib/openclaw/openclaw-endpoint'
 import { wsConnect } from '@/lib/providers/openclaw'
-import { decryptKey, loadCredentials } from '../storage'
+import { decryptKey, loadCredentials, loadGatewayProfiles, saveGatewayProfiles } from '../storage'
+import { notify } from '../ws-hub'
+import type { GatewayProfile } from '@/types'
 
 export interface OpenClawHealthInput {
   endpoint?: string | null
@@ -411,3 +413,30 @@ export async function probeOpenClawHealth(input: OpenClawHealthInput): Promise<O
     hint: http.hint,
   }
 }
+
+export function persistGatewayHealthResult(
+  id: string,
+  result: OpenClawHealthResult,
+  now = Date.now(),
+): GatewayProfile | null {
+  const gateways = loadGatewayProfiles()
+  const gateway = gateways[id]
+  if (!gateway) return null
+
+  gateway.status = result.ok ? 'healthy' : (result.authProvided ? 'degraded' : 'offline')
+  gateway.lastCheckedAt = now
+  gateway.lastError = result.ok ? null : (result.error || result.hint || 'Gateway health check failed.')
+  gateway.lastModelCount = Array.isArray(result.models) ? result.models.length : 0
+  gateway.deployment = {
+    ...(gateway.deployment || {}),
+    lastVerifiedAt: now,
+    lastVerifiedOk: result.ok,
+    lastVerifiedMessage: result.ok
+      ? result.message
+      : (result.error || result.hint || 'Gateway health check failed.'),
+  }
+  gateway.updatedAt = now
+  saveGatewayProfiles(gateways)
+  notify('gateways')
+  return gateway
+}

package/src/lib/server/session-tools/file-send.test.ts

@@ -113,10 +113,26 @@ describe('normalizeSendFilePaths', () => {
     fs.rmSync(cwd, { recursive: true, force: true })
   })
 
-  it('resolves browser profile screenshot paths back into the agent home directory', () => {
+  it('resolves browser profile screenshot paths into the configured browser profiles directory', () => {
     const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'send-file-browser-profile-'))
     const resolved = resolveSendFileSourcePath(cwd, '../../../.swarmclaw/browser-profiles/example/mcp-output/page.png')
-    assert.match(resolved, new RegExp(`\\.swarmclaw[\\\\/]browser-profiles[\\\\/]example[\\\\/]mcp-output[\\\\/]page\\.png$`))
+    assert.match(resolved, new RegExp(`browser-profiles[\\\\/]example[\\\\/]mcp-output[\\\\/]page\\.png$`))
     fs.rmSync(cwd, { recursive: true, force: true })
   })
+
+  it('resolves browser profile screenshot paths from BROWSER_PROFILES_DIR when set', () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'send-file-browser-profile-env-'))
+    const browserProfilesDir = path.join(cwd, '.swarmclaw', 'browser-profiles')
+    const previousDir = process.env.BROWSER_PROFILES_DIR
+
+    try {
+      process.env.BROWSER_PROFILES_DIR = browserProfilesDir
+      const resolved = resolveSendFileSourcePath(cwd, '../../../.swarmclaw/browser-profiles/example/mcp-output/page.png')
+      assert.equal(resolved, path.join(browserProfilesDir, 'example', 'mcp-output', 'page.png'))
+    } finally {
+      if (previousDir === undefined) delete process.env.BROWSER_PROFILES_DIR
+      else process.env.BROWSER_PROFILES_DIR = previousDir
+      fs.rmSync(cwd, { recursive: true, force: true })
+    }
+  })
 })

package/src/lib/server/session-tools/file.ts

@@ -1,10 +1,9 @@
 import { z } from 'zod'
 import { tool, type StructuredToolInterface } from '@langchain/core/tools'
 import fs from 'fs'
-import os from 'os'
 import path from 'path'
 import { UPLOAD_DIR } from '../storage'
-import { WORKSPACE_DIR } from '../data-dir'
+import { BROWSER_PROFILES_DIR, WORKSPACE_DIR } from '../data-dir'
 import type { ToolBuildContext } from './context'
 import { safePath, truncate, listDirRecursive, MAX_FILE } from './context'
 import type { Plugin, PluginHooks } from '@/types'
@@ -387,19 +386,24 @@ export function findRecentSendFileFallbackPaths(cwd: string, maxAgeMs = 10 * 60
   return dedup(candidates)
 }
 
+function getBrowserProfilesDir(): string {
+  return process.env.BROWSER_PROFILES_DIR || BROWSER_PROFILES_DIR
+}
+
 export function resolveSendFileSourcePath(cwd: string, rawPath: string, scope?: 'workspace' | 'machine'): string {
   const trimmed = rawPath.trim()
   const uploadMatch = trimmed.match(/^(?:sandbox:)?\/api\/uploads\/(.+)$/)
   if (uploadMatch) {
     return path.join(UPLOAD_DIR, path.basename(uploadMatch[1]))
   }
-  const browserProfileIdx = trimmed.lastIndexOf('.swarmclaw/browser-profiles/')
-  if (browserProfileIdx !== -1) {
-    const relative = trimmed.slice(browserProfileIdx)
-    return path.join(os.homedir(), relative)
+  const browserProfileMatch = trimmed
+    .replaceAll('\\', '/')
+    .match(/(?:^|\/)\.swarmclaw\/browser-profiles\/(.+)$/)
+  if (browserProfileMatch) {
+    return path.join(getBrowserProfilesDir(), browserProfileMatch[1])
   }
   if (trimmed.startsWith('browser-profiles/')) {
-    const candidate = path.join(os.homedir(), '.swarmclaw', trimmed)
+    const candidate = path.join(getBrowserProfilesDir(), trimmed.slice('browser-profiles/'.length))
     if (fs.existsSync(candidate)) return candidate
   }
   if (trimmed === '/workspace' || trimmed === 'workspace') return cwd

package/src/lib/server/skills/skill-discovery.test.ts

@@ -1,7 +1,9 @@
 import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import test from 'node:test'
-import { discoverSkills } from './skill-discovery'
+import { clearDiscoveredSkillsCache, discoverSkills } from './skill-discovery'
 
 test('discoverSkills includes tracked bundled skills from bundled-skills', () => {
   const skills = discoverSkills({ cwd: path.join(process.cwd(), 'src') })
@@ -14,3 +16,34 @@ test('discoverSkills includes tracked bundled skills from bundled-skills', () =>
     true,
   )
 })
+
+test('discoverSkills reads workspace skills from SWARMCLAW_HOME when set', () => {
+  const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-skills-home-'))
+  const skillDir = path.join(tempHome, 'skills', 'local-skill')
+  const previousHome = process.env.SWARMCLAW_HOME
+
+  try {
+    fs.mkdirSync(skillDir, { recursive: true })
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), `---
+name: local-skill
+description: A local test skill.
+---
+
+# Local Skill
+`, 'utf8')
+    process.env.SWARMCLAW_HOME = tempHome
+    clearDiscoveredSkillsCache()
+
+    const skills = discoverSkills()
+    const localSkill = skills.find((skill) => skill.name === 'local-skill')
+
+    assert.ok(localSkill)
+    assert.equal(localSkill?.source, 'workspace')
+    assert.equal(localSkill?.sourcePath, path.join(skillDir, 'SKILL.md'))
+  } finally {
+    clearDiscoveredSkillsCache()
+    if (previousHome === undefined) delete process.env.SWARMCLAW_HOME
+    else process.env.SWARMCLAW_HOME = previousHome
+    fs.rmSync(tempHome, { recursive: true, force: true })
+  }
+})

package/src/lib/server/skills/skill-discovery.ts

@@ -29,7 +29,12 @@ export function clearDiscoveredSkillsCache(): void {
 }
 
 function buildCacheKey(cwd?: string): string {
-  return `${cwd || ''}`
+  return `${cwd || ''}|${resolveWorkspaceSkillsDir()}`
+}
+
+function resolveWorkspaceSkillsDir(): string {
+  const swarmclawHome = process.env.SWARMCLAW_HOME || path.join(os.homedir(), '.swarmclaw')
+  return path.join(swarmclawHome, 'skills')
 }
 
 function scanLayer(
@@ -81,7 +86,7 @@ function scanLayer(
  * Discover skills from three layers:
  *   1. Bundled: `bundled-skills/` (tracked with the app)
  *      Legacy fallback: `data/skills/`
- *   2. Workspace: `~/.swarmclaw/skills/` (user-installed)
+ *   2. Workspace: `<swarmclaw-home>/skills/` (user-installed)
  *   3. Project: `<cwd>/skills/` (project-local)
  *
  * Results are cached with a 5-second TTL. Later layers override
@@ -102,8 +107,8 @@ export function discoverSkills(opts?: { cwd?: string }): DiscoveredSkill[] {
     ...scanLayer(BUNDLED_SKILLS_DIR, 'bundled'),
   ]
 
-  // Layer 2: Workspace skills (~/.swarmclaw/skills/)
-  const workspaceDir = path.join(os.homedir(), '.swarmclaw', 'skills')
+  // Layer 2: Workspace skills (<swarmclaw-home>/skills/)
+  const workspaceDir = resolveWorkspaceSkillsDir()
   const workspace = scanLayer(workspaceDir, 'workspace')
 
   // Layer 3: Project-local skills (<cwd>/skills/)