beam-protocol-cli 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beam-protocol-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Beam Protocol CLI \u2014 manage Beam identities, register agents, send intents",
   "type": "module",
   "bin": {
@@ -34,4 +34,4 @@
     "ai-agents",
     "cli"
   ]
-}
+}

package/src/commands/browse.ts

@@ -0,0 +1,61 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { BeamClient } from '@beam-protocol/sdk'
+import type { BrowseFilters } from '@beam-protocol/sdk'
+import { loadConfig } from '../config.js'
+
+interface BrowseOptions {
+  page?: string
+  capability?: string
+  tier?: string
+  verifiedOnly?: boolean
+  directory?: string
+  json?: boolean
+}
+
+export async function cmdBrowse(options: BrowseOptions): Promise<void> {
+  const config = loadConfig()
+  const directoryUrl = options.directory ?? config.directoryUrl
+  const page = options.page ? parseInt(options.page, 10) : 1
+  const filters: BrowseFilters = {
+    capability: options.capability,
+    tier: options.tier as BrowseFilters['tier'],
+    verified_only: options.verifiedOnly,
+  }
+
+  const spinner = ora(`Browsing directory page ${page}...`).start()
+
+  try {
+    const client = new BeamClient({ identity: config.identity, directoryUrl })
+    const result = await client.browse(page, filters)
+    spinner.stop()
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(chalk.bold(`📚 Directory Page ${result.page}`))
+    console.log(chalk.dim(`Showing ${result.agents.length} of ${result.total} agents`))
+    console.log(chalk.dim('─'.repeat(72)))
+
+    for (const agent of result.agents) {
+      const badge = agent.verified ? chalk.green('✓') : chalk.dim('○')
+      const tier = agent.verificationTier ? chalk.magenta(agent.verificationTier) : chalk.dim('basic')
+      console.log(`  ${badge} ${chalk.bold(agent.beamId)} ${chalk.dim(`(${tier})`)}`)
+      console.log(`     ${agent.displayName}${agent.description ? chalk.dim(` — ${agent.description}`) : ''}`)
+      if (agent.capabilities.length > 0) {
+        console.log(`     ${chalk.cyan('Capabilities:')} ${agent.capabilities.join(', ')}`)
+      }
+      if (agent.website) {
+        console.log(`     ${chalk.cyan('Website:')} ${agent.website}`)
+      }
+      console.log('')
+    }
+  } catch (err) {
+    spinner.fail('Browse failed')
+    console.error(chalk.red(`✖ ${(err as Error).message}`))
+    process.exit(1)
+  }
+}

package/src/commands/delegate.ts

@@ -0,0 +1,52 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { BeamClient } from '@beam-protocol/sdk'
+import { BEAM_ID_PATTERN, loadConfig } from '../config.js'
+
+interface DelegateOptions {
+  scope?: string
+  expires?: string
+  directory?: string
+  json?: boolean
+}
+
+export async function cmdDelegate(targetBeamId: string, options: DelegateOptions): Promise<void> {
+  if (!BEAM_ID_PATTERN.test(targetBeamId)) {
+    console.error(chalk.red(`✖ Invalid Beam ID: ${targetBeamId}`))
+    process.exit(1)
+  }
+  if (!options.scope) {
+    console.error(chalk.red('✖ Missing required --scope value'))
+    process.exit(1)
+  }
+
+  const config = loadConfig()
+  const directoryUrl = options.directory ?? config.directoryUrl
+  const expiresIn = options.expires ? parseInt(options.expires, 10) : undefined
+  const spinner = ora(`Creating delegation for ${chalk.bold(targetBeamId)}...`).start()
+
+  try {
+    const client = new BeamClient({ identity: config.identity, directoryUrl })
+    const delegation = await client.delegate(targetBeamId, options.scope, expiresIn)
+    spinner.stop()
+
+    if (options.json) {
+      console.log(JSON.stringify(delegation, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(chalk.bold.green('✅ Delegation created'))
+    console.log(chalk.dim('─'.repeat(40)))
+    console.log(`${chalk.cyan('From:')}      ${delegation.sourceBeamId}`)
+    console.log(`${chalk.cyan('To:')}        ${delegation.targetBeamId}`)
+    console.log(`${chalk.cyan('Scope:')}     ${delegation.scope}`)
+    if (delegation.expiresAt) console.log(`${chalk.cyan('Expires:')}   ${delegation.expiresAt}`)
+    if (delegation.status) console.log(`${chalk.cyan('Status:')}    ${delegation.status}`)
+    console.log('')
+  } catch (err) {
+    spinner.fail('Delegation failed')
+    console.error(chalk.red(`✖ ${(err as Error).message}`))
+    process.exit(1)
+  }
+}

package/src/commands/init.ts

@@ -5,7 +5,7 @@ import { configExists, saveConfig, DEFAULT_DIRECTORY_URL } from '../config.js'
 
 interface InitOptions {
   agent: string
-  org: string
+  org?: string
   force?: boolean
   directory?: string
 }
@@ -13,12 +13,11 @@ interface InitOptions {
 export async function cmdInit(options: InitOptions): Promise<void> {
   const { agent, org, force, directory = DEFAULT_DIRECTORY_URL } = options
 
-  // Validate inputs
   if (!/^[a-z0-9_-]+$/.test(agent)) {
     console.error(chalk.red('✖ Agent name must match [a-z0-9_-]'))
     process.exit(1)
   }
-  if (!/^[a-z0-9_-]+$/.test(org)) {
+  if (org && !/^[a-z0-9_-]+$/.test(org)) {
     console.error(chalk.red('✖ Org name must match [a-z0-9_-]'))
     process.exit(1)
   }
@@ -55,5 +54,8 @@ export async function cmdInit(options: InitOptions): Promise<void> {
   console.log(chalk.yellow('⚠  Keep .beam/identity.json secret — it contains your private key!'))
   console.log(chalk.dim('   Add .beam/ to your .gitignore'))
   console.log('')
-  console.log(chalk.green('Next step:'), `beam register --display-name "My Agent" --capabilities "query,answer"`)
+  console.log(
+    chalk.green('Next step:'),
+    `beam register --display-name "${org ? agent : 'My Consumer Agent'}" --capabilities "query,answer"`
+  )
 }

package/src/commands/lookup.ts

@@ -2,7 +2,7 @@ import chalk from 'chalk'
 import ora from 'ora'
 import { BeamDirectory } from '@beam-protocol/sdk'
 import type { BeamIdString } from '@beam-protocol/sdk'
-import { loadConfig } from '../config.js'
+import { BEAM_ID_PATTERN, resolveDirectoryUrl } from '../config.js'
 
 interface LookupOptions {
   directory?: string
@@ -10,13 +10,11 @@ interface LookupOptions {
 }
 
 export async function cmdLookup(beamId: string, options: LookupOptions): Promise<void> {
-  const config = loadConfig()
-  const directoryUrl = options.directory ?? config.directoryUrl
+  const directoryUrl = resolveDirectoryUrl(options.directory)
 
-  // Validate beam ID format
-  if (!beamId.match(/^[a-z0-9_-]+@[a-z0-9_-]+\.beam\.directory$/)) {
+  if (!BEAM_ID_PATTERN.test(beamId)) {
     console.error(chalk.red(`✖ Invalid Beam ID format: ${beamId}`))
-    console.error(chalk.dim('  Expected: agent@org.beam.directory'))
+    console.error(chalk.dim('  Expected: agent@beam.directory or agent@org.beam.directory'))
     process.exit(1)
   }
 
@@ -44,11 +42,11 @@ export async function cmdLookup(beamId: string, options: LookupOptions): Promise
     console.log(chalk.bold(`🤖 ${record.displayName}`))
     console.log(chalk.dim('─'.repeat(40)))
     console.log(`${chalk.cyan('Beam ID:')}      ${chalk.bold(record.beamId)}`)
-    console.log(`${chalk.cyan('Org:')}          ${record.org}`)
+    console.log(`${chalk.cyan('Org:')}          ${record.org ?? chalk.dim('consumer')}`)
     console.log(`${chalk.cyan('Trust Score:')} ${trustBar} ${(record.trustScore * 100).toFixed(0)}%`)
     console.log(`${chalk.cyan('Verified:')}     ${record.verified ? chalk.green('✓ Verified') : chalk.yellow('Unverified')}`)
     if (record.capabilities.length > 0) {
-      console.log(`${chalk.cyan('Capabilities:')} ${record.capabilities.map(c => chalk.blue(c)).join(', ')}`)
+      console.log(`${chalk.cyan('Capabilities:')} ${record.capabilities.map((capability: string) => chalk.blue(capability)).join(', ')}`)
     }
     console.log(`${chalk.cyan('Last Seen:')}   ${new Date(record.lastSeen).toLocaleString()}`)
     console.log(`${chalk.cyan('Registered:')}  ${new Date(record.createdAt).toLocaleString()}`)

package/src/commands/profile-update.ts

@@ -0,0 +1,47 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { BeamClient } from '@beam-protocol/sdk'
+import { loadConfig } from '../config.js'
+
+interface ProfileUpdateOptions {
+  description?: string
+  logoUrl?: string
+  website?: string
+  directory?: string
+  json?: boolean
+}
+
+export async function cmdProfileUpdate(options: ProfileUpdateOptions): Promise<void> {
+  const config = loadConfig()
+  const directoryUrl = options.directory ?? config.directoryUrl
+  const spinner = ora(`Updating profile for ${chalk.bold(config.identity.beamId)}...`).start()
+
+  try {
+    const client = new BeamClient({ identity: config.identity, directoryUrl })
+    const profile = await client.updateProfile({
+      description: options.description,
+      logo_url: options.logoUrl,
+      website: options.website,
+    })
+
+    spinner.stop()
+
+    if (options.json) {
+      console.log(JSON.stringify(profile, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(chalk.bold.green('✅ Profile updated'))
+    console.log(chalk.dim('─'.repeat(40)))
+    console.log(`${chalk.cyan('Beam ID:')}      ${profile.beamId}`)
+    console.log(`${chalk.cyan('Description:')} ${profile.description ?? chalk.dim('—')}`)
+    console.log(`${chalk.cyan('Logo URL:')}    ${profile.logoUrl ?? chalk.dim('—')}`)
+    console.log(`${chalk.cyan('Website:')}     ${profile.website ?? chalk.dim('—')}`)
+    console.log('')
+  } catch (err) {
+    spinner.fail('Profile update failed')
+    console.error(chalk.red(`✖ ${(err as Error).message}`))
+    process.exit(1)
+  }
+}

package/src/commands/register.ts

@@ -41,7 +41,7 @@ export async function cmdRegister(options: RegisterOptions): Promise<void> {
     console.log(chalk.dim('─'.repeat(40)))
     console.log(`${chalk.cyan('Beam ID:')}      ${chalk.bold(record.beamId)}`)
     console.log(`${chalk.cyan('Display:')}      ${record.displayName}`)
-    console.log(`${chalk.cyan('Org:')}          ${record.org}`)
+    console.log(`${chalk.cyan('Org:')}          ${record.org ?? chalk.dim('consumer')}`)
     console.log(`${chalk.cyan('Trust Score:')} ${(record.trustScore * 100).toFixed(0)}%`)
     console.log(`${chalk.cyan('Verified:')}     ${record.verified ? chalk.green('Yes ✓') : chalk.yellow('No')}`)
     if (record.capabilities.length > 0) {

package/src/commands/report.ts

@@ -0,0 +1,49 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { BeamClient } from '@beam-protocol/sdk'
+import { BEAM_ID_PATTERN, loadConfig } from '../config.js'
+
+interface ReportOptions {
+  reason?: string
+  directory?: string
+  json?: boolean
+}
+
+export async function cmdReport(targetBeamId: string, options: ReportOptions): Promise<void> {
+  if (!BEAM_ID_PATTERN.test(targetBeamId)) {
+    console.error(chalk.red(`✖ Invalid Beam ID: ${targetBeamId}`))
+    process.exit(1)
+  }
+  if (!options.reason) {
+    console.error(chalk.red('✖ Missing required --reason value'))
+    process.exit(1)
+  }
+
+  const config = loadConfig()
+  const directoryUrl = options.directory ?? config.directoryUrl
+  const spinner = ora(`Submitting report for ${chalk.bold(targetBeamId)}...`).start()
+
+  try {
+    const client = new BeamClient({ identity: config.identity, directoryUrl })
+    const report = await client.report(targetBeamId, options.reason)
+    spinner.stop()
+
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(chalk.bold.yellow('⚠ Agent reported'))
+    console.log(chalk.dim('─'.repeat(40)))
+    console.log(`${chalk.cyan('Reporter:')} ${report.reporterBeamId}`)
+    console.log(`${chalk.cyan('Target:')}   ${report.targetBeamId}`)
+    console.log(`${chalk.cyan('Reason:')}   ${report.reason}`)
+    if (report.status) console.log(`${chalk.cyan('Status:')}   ${report.status}`)
+    console.log('')
+  } catch (err) {
+    spinner.fail('Report failed')
+    console.error(chalk.red(`✖ ${(err as Error).message}`))
+    process.exit(1)
+  }
+}

package/src/commands/search.ts

@@ -1,7 +1,7 @@
 import chalk from 'chalk'
 import ora from 'ora'
 import { BeamDirectory } from '@beam-protocol/sdk'
-import { loadConfig } from '../config.js'
+import { resolveDirectoryUrl } from '../config.js'
 
 interface SearchOptions {
   org?: string
@@ -13,8 +13,7 @@ interface SearchOptions {
 }
 
 export async function cmdSearch(options: SearchOptions): Promise<void> {
-  const config = loadConfig()
-  const directoryUrl = options.directory ?? config.directoryUrl
+  const directoryUrl = resolveDirectoryUrl(options.directory)
 
   const query = {
     org: options.org,
@@ -57,9 +56,7 @@ export async function cmdSearch(options: SearchOptions): Promise<void> {
         ? chalk.dim(` [${agent.capabilities.join(', ')}]`)
         : ''
 
-      console.log(
-        `  ${verified} ${chalk.bold(agent.beamId)}${caps}`
-      )
+      console.log(`  ${verified} ${chalk.bold(agent.beamId)}${caps}`)
       console.log(
         `     ${chalk.dim(agent.displayName)} · Trust: ${getTrustColored(agent.trustScore, trustPct + '%')} · Last seen: ${formatRelative(agent.lastSeen)}`
       )

package/src/commands/send.ts

@@ -2,7 +2,7 @@ import chalk from 'chalk'
 import ora from 'ora'
 import { BeamClient } from '@beam-protocol/sdk'
 import type { BeamIdString } from '@beam-protocol/sdk'
-import { loadConfig } from '../config.js'
+import { BEAM_ID_PATTERN, loadConfig } from '../config.js'
 
 interface SendOptions {
   directory?: string
@@ -20,14 +20,12 @@ export async function cmdSend(
   const directoryUrl = options.directory ?? config.directoryUrl
   const timeoutMs = options.timeout ? parseInt(options.timeout, 10) * 1000 : 10000
 
-  // Validate beam ID format
-  if (!to.match(/^[a-z0-9_-]+@[a-z0-9_-]+\.beam\.directory$/)) {
+  if (!BEAM_ID_PATTERN.test(to)) {
     console.error(chalk.red(`✖ Invalid Beam ID: ${to}`))
-    console.error(chalk.dim('  Expected: agent@org.beam.directory'))
+    console.error(chalk.dim('  Expected: agent@beam.directory or agent@org.beam.directory'))
     process.exit(1)
   }
 
-  // Parse params
   let params: Record<string, unknown> = {}
   if (paramsJson) {
     try {
@@ -43,10 +41,7 @@ export async function cmdSend(
     }
   }
 
-  const spinner = ora(
-    `Sending ${chalk.bold(intent)} to ${chalk.bold(to)}...`
-  ).start()
-
+  const spinner = ora(`Sending ${chalk.bold(intent)} to ${chalk.bold(to)}...`).start()
   const startTime = Date.now()
 
   try {

package/src/commands/stats.ts

@@ -0,0 +1,40 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { BeamClient } from '@beam-protocol/sdk'
+import { loadConfig } from '../config.js'
+
+interface StatsOptions {
+  directory?: string
+  json?: boolean
+}
+
+export async function cmdStats(options: StatsOptions): Promise<void> {
+  const config = loadConfig()
+  const directoryUrl = options.directory ?? config.directoryUrl
+  const spinner = ora('Fetching directory statistics...').start()
+
+  try {
+    const client = new BeamClient({ identity: config.identity, directoryUrl })
+    const stats = await client.getStats()
+    spinner.stop()
+
+    if (options.json) {
+      console.log(JSON.stringify(stats, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(chalk.bold('📈 Directory statistics'))
+    console.log(chalk.dim('─'.repeat(40)))
+    console.log(`${chalk.cyan('Total agents:')} ${stats.totalAgents}`)
+    console.log(`${chalk.cyan('Verified:')}     ${stats.verifiedAgents}`)
+    console.log(`${chalk.cyan('Intents:')}      ${stats.intentsProcessed}`)
+    if (stats.consumerAgents !== undefined) console.log(`${chalk.cyan('Consumers:')}    ${stats.consumerAgents}`)
+    if (stats.version) console.log(`${chalk.cyan('Version:')}      ${stats.version}`)
+    console.log('')
+  } catch (err) {
+    spinner.fail('Stats failed')
+    console.error(chalk.red(`✖ ${(err as Error).message}`))
+    process.exit(1)
+  }
+}

package/src/commands/verify-check.ts

@@ -0,0 +1,41 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { BeamClient } from '@beam-protocol/sdk'
+import { loadConfig } from '../config.js'
+
+interface VerifyCheckOptions {
+  directory?: string
+  json?: boolean
+}
+
+export async function cmdVerifyCheck(options: VerifyCheckOptions): Promise<void> {
+  const config = loadConfig()
+  const directoryUrl = options.directory ?? config.directoryUrl
+  const spinner = ora('Checking verification status...').start()
+
+  try {
+    const client = new BeamClient({ identity: config.identity, directoryUrl })
+    const verification = await client.checkDomainVerification()
+    spinner.stop()
+
+    if (options.json) {
+      console.log(JSON.stringify(verification, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(chalk.bold('🔎 Verification status'))
+    console.log(chalk.dim('─'.repeat(40)))
+    console.log(`${chalk.cyan('Domain:')}   ${verification.domain || chalk.dim('—')}`)
+    console.log(`${chalk.cyan('Verified:')} ${verification.verified ? chalk.green('Yes ✓') : chalk.yellow('Pending')}`)
+    console.log(`${chalk.cyan('Status:')}   ${verification.status ?? chalk.dim('—')}`)
+    if (verification.tier) {
+      console.log(`${chalk.cyan('Tier:')}     ${verification.tier}`)
+    }
+    console.log('')
+  } catch (err) {
+    spinner.fail('Verification check failed')
+    console.error(chalk.red(`✖ ${(err as Error).message}`))
+    process.exit(1)
+  }
+}

package/src/commands/verify-domain.ts

@@ -0,0 +1,42 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { BeamClient } from '@beam-protocol/sdk'
+import { loadConfig } from '../config.js'
+
+interface VerifyDomainOptions {
+  directory?: string
+  json?: boolean
+}
+
+export async function cmdVerifyDomain(domain: string, options: VerifyDomainOptions): Promise<void> {
+  const config = loadConfig()
+  const directoryUrl = options.directory ?? config.directoryUrl
+  const spinner = ora(`Starting DNS verification for ${chalk.bold(domain)}...`).start()
+
+  try {
+    const client = new BeamClient({ identity: config.identity, directoryUrl })
+    const verification = await client.verifyDomain(domain)
+    spinner.stop()
+
+    if (options.json) {
+      console.log(JSON.stringify(verification, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(chalk.bold('🌐 Domain verification started'))
+    console.log(chalk.dim('─'.repeat(40)))
+    console.log(`${chalk.cyan('Domain:')}   ${verification.domain}`)
+    console.log(`${chalk.cyan('Verified:')} ${verification.verified ? chalk.green('Yes') : chalk.yellow('Pending')}`)
+    if (verification.txtName) console.log(`${chalk.cyan('TXT Name:')} ${verification.txtName}`)
+    if (verification.txtValue ?? verification.expected) {
+      console.log(`${chalk.cyan('TXT Value:')} ${verification.txtValue ?? verification.expected}`)
+    }
+    console.log('')
+    console.log(chalk.dim('After adding the TXT record, run: beam verify check'))
+  } catch (err) {
+    spinner.fail('Domain verification failed')
+    console.error(chalk.red(`✖ ${(err as Error).message}`))
+    process.exit(1)
+  }
+}

package/src/config.ts

@@ -20,21 +20,32 @@ export function configExists(cwd = process.cwd()): boolean {
   return existsSync(getConfigPath(cwd))
 }
 
-export function loadConfig(cwd = process.cwd()): BeamConfig {
+export function loadOptionalConfig(cwd = process.cwd()): BeamConfig | null {
   const path = getConfigPath(cwd)
   if (!existsSync(path)) {
-    throw new Error(
-      `No Beam identity found. Run 'beam init' first.`
-    )
+    return null
   }
   const raw = readFileSync(path, 'utf8')
   return JSON.parse(raw) as BeamConfig
 }
 
+export function loadConfig(cwd = process.cwd()): BeamConfig {
+  const config = loadOptionalConfig(cwd)
+  if (!config) {
+    throw new Error(`No Beam identity found. Run 'beam init' first.`)
+  }
+  return config
+}
+
+export function resolveDirectoryUrl(override?: string, cwd = process.cwd()): string {
+  return override ?? loadOptionalConfig(cwd)?.directoryUrl ?? DEFAULT_DIRECTORY_URL
+}
+
 export function saveConfig(config: BeamConfig, cwd = process.cwd()): void {
   const dir = getConfigDir(cwd)
   mkdirSync(dir, { recursive: true })
   writeFileSync(getConfigPath(cwd), JSON.stringify(config, null, 2), 'utf8')
 }
 
-export const DEFAULT_DIRECTORY_URL = process.env['BEAM_DIRECTORY_URL'] ?? 'http://localhost:3100'
+export const DEFAULT_DIRECTORY_URL = process.env['BEAM_DIRECTORY_URL'] ?? 'https://api.beam.directory'
+export const BEAM_ID_PATTERN = /^(?:[a-z0-9_-]+@beam\.directory|[a-z0-9_-]+@[a-z0-9_-]+\.beam\.directory)$/