@brainjar/cli 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # brainjar
 
-[![CI](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml)
+[![CI](https://github.com/brainjar-sh/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/brainjar-sh/cli/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@brainjar/cli)](https://www.npmjs.com/package/@brainjar/cli)
 [![downloads](https://img.shields.io/npm/dm/@brainjar/cli)](https://www.npmjs.com/package/@brainjar/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -50,7 +50,8 @@ brainjar pack export|import
 brainjar hooks install|remove|status [--local]
 brainjar shell [--brain <name>] [--soul <name>] [--persona <name>]
 brainjar reset [--backend claude|codex]
-brainjar server start|stop|status|logs|local|remote|upgrade
+brainjar server start|stop|status|logs|local|remote
+brainjar upgrade [--cli-only] [--server-only]
 brainjar migrate [--dry-run] [--skip-backup]
 ```
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@brainjar/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Shape how your AI thinks — composable soul, persona, and rules for AI agents",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/brainjar-sh/brainjar-cli.git"
+    "url": "https://github.com/brainjar-sh/cli.git"
   },
   "homepage": "https://brainjar.sh",
-  "bugs": "https://github.com/brainjar-sh/brainjar-cli/issues",
+  "bugs": "https://github.com/brainjar-sh/cli/issues",
   "keywords": [
     "ai",
     "agent",

package/src/cli.ts

@@ -15,6 +15,8 @@ import { hooks } from './commands/hooks.js'
 import { pack } from './commands/pack.js'
 import { server } from './commands/server.js'
 import { migrate } from './commands/migrate.js'
+import { upgrade } from './commands/upgrade.js'
+import { context } from './commands/context.js'
 
 Cli.create('brainjar', {
   description: 'Shape how your AI thinks — soul, persona, rules',
@@ -35,4 +37,6 @@ Cli.create('brainjar', {
   .command(pack)
   .command(server)
   .command(migrate)
+  .command(upgrade)
+  .command(context)
   .serve()

package/src/client.ts

@@ -1,6 +1,6 @@
 import { Errors } from 'incur'
 import { basename } from 'node:path'
-import { readConfig } from './config.js'
+import { readConfig, activeContext } from './config.js'
 import { getLocalDir } from './paths.js'
 import { access } from 'node:fs/promises'
 import { ensureRunning } from './daemon.js'
@@ -55,11 +55,12 @@ async function detectProject(explicit?: string): Promise<string | null> {
  */
 export async function createClient(options?: ClientOptions): Promise<BrainjarClient> {
   const config = await readConfig()
-  const serverUrl = (options?.serverUrl ?? config.server.url).replace(/\/$/, '')
-  const workspace = options?.workspace ?? config.workspace
+  const ctx = activeContext(config)
+  const serverUrl = (options?.serverUrl ?? ctx.url).replace(/\/$/, '')
+  const workspace = options?.workspace ?? ctx.workspace
   const session = options?.session ?? process.env.BRAINJAR_SESSION ?? null
   const defaultTimeout = options?.timeout ?? 10_000
-  const mode = config.server.mode
+  const mode = ctx.mode
 
   async function request<T>(method: string, path: string, body?: unknown, reqOpts?: RequestOptions): Promise<T> {
     const url = `${serverUrl}${path}`

package/src/commands/context.ts

@@ -0,0 +1,220 @@
+import { Cli, z } from 'incur'
+import { readConfig, writeConfig, activeContext, isLocalContext, contextNameFromUrl, uniqueContextName } from '../config.js'
+import type { RemoteContext } from '../config.js'
+import { healthCheck, ensureRunning } from '../daemon.js'
+import { getApi } from '../client.js'
+import { sync } from '../sync.js'
+import { ErrorCode, createError } from '../errors.js'
+
+const SLUG_RE = /^[a-zA-Z0-9_-]+$/
+
+const listCmd = Cli.create('list', {
+  description: 'List all contexts',
+  async run() {
+    const config = await readConfig()
+    const entries = Object.entries(config.contexts).map(([name, ctx]) => ({
+      name,
+      active: name === config.current_context,
+      mode: ctx.mode,
+      url: ctx.url,
+      workspace: ctx.workspace,
+    }))
+    return { contexts: entries }
+  },
+})
+
+const addCmd = Cli.create('add', {
+  description: 'Add a remote context',
+  args: z.object({
+    name: z.string().describe('Context name'),
+    url: z.string().describe('Server URL'),
+  }),
+  options: z.object({
+    workspace: z.string().default('default').describe('Workspace name'),
+  }),
+  async run(c) {
+    const name = c.args.name
+    const url = c.args.url.replace(/\/$/, '')
+
+    if (!SLUG_RE.test(name)) {
+      throw createError(ErrorCode.VALIDATION_ERROR, {
+        message: `Invalid context name "${name}". Use only letters, numbers, hyphens, and underscores.`,
+      })
+    }
+
+    if (name === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, { params: ['local'] })
+    }
+
+    const config = await readConfig()
+
+    if (name in config.contexts) {
+      throw createError(ErrorCode.CONTEXT_EXISTS, { params: [name] })
+    }
+
+    const health = await healthCheck({ url, timeout: 5000 })
+    if (!health.healthy) {
+      throw createError(ErrorCode.SERVER_UNREACHABLE, { params: [url] })
+    }
+
+    config.contexts[name] = {
+      url,
+      mode: 'remote',
+      workspace: c.options.workspace,
+    }
+    await writeConfig(config)
+
+    return { added: name, url, hint: `Switch with \`brainjar context use ${name}\`` }
+  },
+})
+
+const removeCmd = Cli.create('remove', {
+  description: 'Remove a context',
+  args: z.object({
+    name: z.string().describe('Context name'),
+  }),
+  async run(c) {
+    const name = c.args.name
+    const config = await readConfig()
+
+    if (name === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, { params: ['local'] })
+    }
+
+    if (!(name in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [name] })
+    }
+
+    if (name === config.current_context) {
+      throw createError(ErrorCode.CONTEXT_ACTIVE, { params: [name] })
+    }
+
+    delete config.contexts[name]
+    await writeConfig(config)
+
+    return { removed: name }
+  },
+})
+
+const useCmd = Cli.create('use', {
+  description: 'Switch active context',
+  args: z.object({
+    name: z.string().describe('Context name'),
+  }),
+  async run(c) {
+    const name = c.args.name
+    const config = await readConfig()
+
+    if (!(name in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [name] })
+    }
+
+    config.current_context = name
+    await writeConfig(config)
+
+    const ctx = activeContext(config)
+
+    // If switching to local, ensure running
+    if (isLocalContext(ctx)) {
+      await ensureRunning()
+    }
+
+    // Sync if server is reachable
+    const health = await healthCheck({ url: ctx.url, timeout: 3000 })
+    if (health.healthy) {
+      const api = await getApi()
+
+      // Ensure workspace exists
+      try {
+        await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      } catch (e: any) {
+        if (e.code !== 'CONFLICT') throw e
+      }
+
+      await sync({ api })
+    }
+
+    return { active: name, mode: ctx.mode, url: ctx.url, workspace: ctx.workspace }
+  },
+})
+
+const showCmd = Cli.create('show', {
+  description: 'Show context details',
+  args: z.object({
+    name: z.string().optional().describe('Context name (defaults to active)'),
+  }),
+  async run(c) {
+    const config = await readConfig()
+    const name = c.args.name ?? config.current_context
+
+    if (!(name in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [name] })
+    }
+
+    const ctx = config.contexts[name]
+    return {
+      name,
+      active: name === config.current_context,
+      ...ctx,
+    }
+  },
+})
+
+const renameCmd = Cli.create('rename', {
+  description: 'Rename a context',
+  args: z.object({
+    old: z.string().describe('Current name'),
+    new: z.string().describe('New name'),
+  }),
+  async run(c) {
+    const oldName = c.args.old
+    const newName = c.args.new
+
+    if (oldName === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, { params: ['local'] })
+    }
+
+    if (newName === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, {
+        message: 'Cannot rename to "local" — that name is reserved.',
+      })
+    }
+
+    if (!SLUG_RE.test(newName)) {
+      throw createError(ErrorCode.VALIDATION_ERROR, {
+        message: `Invalid context name "${newName}". Use only letters, numbers, hyphens, and underscores.`,
+      })
+    }
+
+    const config = await readConfig()
+
+    if (!(oldName in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [oldName] })
+    }
+
+    if (newName in config.contexts) {
+      throw createError(ErrorCode.CONTEXT_EXISTS, { params: [newName] })
+    }
+
+    config.contexts[newName] = config.contexts[oldName]
+    delete config.contexts[oldName]
+
+    if (config.current_context === oldName) {
+      config.current_context = newName
+    }
+
+    await writeConfig(config)
+
+    return { renamed: { from: oldName, to: newName } }
+  },
+})
+
+export const context = Cli.create('context', {
+  description: 'Manage server contexts — named server profiles',
+})
+  .command(listCmd)
+  .command(addCmd)
+  .command(removeCmd)
+  .command(useCmd)
+  .command(showCmd)
+  .command(renameCmd)

package/src/commands/init.ts

@@ -5,7 +5,7 @@ import { buildSeedBundle } from '../seeds.js'
 import { putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
-import { readConfig, writeConfig, type Config } from '../config.js'
+import { readConfig, writeConfig, activeContext, isLocalContext, type Config } from '../config.js'
 import { ensureBinary, upgradeServer } from '../daemon.js'
 import type { ApiImportResult } from '../api-types.js'
 
@@ -32,14 +32,18 @@ export const init = Cli.create('init', {
 
     if (!configExists) {
       const config: Config = {
-        server: {
-          url: 'http://localhost:7742',
-          mode: 'local',
-          bin: `${brainjarDir}/bin/brainjar-server`,
-          pid_file: `${brainjarDir}/server.pid`,
-          log_file: `${brainjarDir}/server.log`,
+        version: 2,
+        current_context: 'local',
+        contexts: {
+          local: {
+            url: 'http://localhost:7742',
+            mode: 'local',
+            bin: `${brainjarDir}/bin/brainjar-server`,
+            pid_file: `${brainjarDir}/server.pid`,
+            log_file: `${brainjarDir}/server.log`,
+            workspace: 'default',
+          },
         },
-        workspace: 'default',
         backend: c.options.backend as Backend,
       }
       await writeConfig(config)
@@ -48,9 +52,10 @@ export const init = Cli.create('init', {
     // 3. Ensure server binary exists and is up to date
     await ensureBinary()
     const config = await readConfig()
-    if (config.server.mode === 'local') {
+    const ctx = activeContext(config)
+    if (isLocalContext(ctx)) {
       // Only upgrade if server isn't already running (can't overwrite a running binary)
-      const health = await (await import('../daemon.js')).healthCheck({ timeout: 1000, url: config.server.url })
+      const health = await (await import('../daemon.js')).healthCheck({ timeout: 1000, url: ctx.url })
       if (!health.healthy) {
         await upgradeServer()
       }
@@ -61,7 +66,7 @@ export const init = Cli.create('init', {
 
     // 5. Ensure workspace exists (ignore conflict if already created)
     try {
-      await api.post('/api/v1/workspaces', { name: config.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
     } catch (e: any) {
       if (e.code !== 'CONFLICT') throw e
     }

package/src/commands/persona.ts

@@ -86,6 +86,61 @@ export const persona = Cli.create('persona', {
       }
     },
   })
+  .command('update', {
+    description: 'Update a persona\'s content (reads from stdin)',
+    args: z.object({
+      name: z.string().describe('Persona name'),
+    }),
+    options: z.object({
+      rules: z.array(z.string()).optional().describe('Update bundled rules'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'persona name')
+      const api = await getApi()
+
+      // Validate it exists and get current data
+      let existing: ApiPersona
+      try {
+        existing = await api.get<ApiPersona>(`/api/v1/personas/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.PERSONA_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
+
+      const chunks: Uint8Array[] = []
+      for await (const chunk of Bun.stdin.stream()) {
+        chunks.push(chunk)
+      }
+      const content = Buffer.concat(chunks).toString().trim()
+
+      // Validate rules if provided
+      const rulesList = c.options.rules
+      if (rulesList && rulesList.length > 0) {
+        const available = await api.get<ApiRuleList>('/api/v1/rules')
+        const availableSlugs = available.rules.map(r => r.slug)
+        const invalid = rulesList.filter(r => !availableSlugs.includes(r))
+        if (invalid.length > 0) {
+          throw createError(ErrorCode.RULES_NOT_FOUND, {
+            message: `Rules not found: ${invalid.join(', ')}`,
+            hint: `Available rules: ${availableSlugs.join(', ')}`,
+          })
+        }
+      }
+
+      await api.put<ApiPersona>(`/api/v1/personas/${name}`, {
+        content: content || existing.content,
+        bundled_rules: rulesList ?? existing.bundled_rules,
+      })
+
+      // Sync if this persona is active
+      const state = await getEffectiveState(api)
+      if (state.persona === name) await sync({ api })
+
+      return { updated: name, rules: rulesList ?? existing.bundled_rules }
+    },
+  })
   .command('list', {
     description: 'List available personas',
     async run() {

package/src/commands/rules.ts

@@ -18,7 +18,6 @@ export const rules = Cli.create('rules', {
     }),
     options: z.object({
       description: z.string().optional().describe('One-line description of the rule'),
-      pack: z.boolean().default(false).describe('Create as a rule pack (multiple entries)'),
     }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'rule name')
@@ -48,18 +47,60 @@ export const rules = Cli.create('rules', {
       })
 
       if (c.agent || c.formatExplicit) {
-        return { created: name, name, pack: c.options.pack, template: scaffold }
+        return { created: name, name, template: scaffold }
       }
 
       return {
         created: name,
         name,
-        pack: c.options.pack,
         template: `\n${scaffold}`,
         next: `Run \`brainjar rules show ${name}\` to view, then \`brainjar rules add ${name}\` to activate.`,
       }
     },
   })
+  .command('update', {
+    description: 'Update a rule\'s content (reads from stdin)',
+    args: z.object({
+      name: z.string().describe('Rule name'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'rule name')
+      const api = await getApi()
+
+      // Validate it exists
+      try {
+        await api.get<ApiRule>(`/api/v1/rules/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.RULE_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
+
+      const chunks: Uint8Array[] = []
+      for await (const chunk of Bun.stdin.stream()) {
+        chunks.push(chunk)
+      }
+      const content = Buffer.concat(chunks).toString().trim()
+
+      if (!content) {
+        throw createError(ErrorCode.MISSING_ARG, {
+          message: 'No content provided. Pipe content via stdin.',
+          hint: `echo "# ${name}\\n..." | brainjar rules update ${name}`,
+        })
+      }
+
+      await api.put<ApiRule>(`/api/v1/rules/${name}`, {
+        entries: [{ name: `${name}.md`, content }],
+      })
+
+      // Sync if this rule is active
+      const state = await getEffectiveState(api)
+      if (state.rules.includes(name)) await sync({ api })
+
+      return { updated: name }
+    },
+  })
   .command('list', {
     description: 'List available and active rules',
     options: z.object({

package/src/commands/server.ts

@@ -7,19 +7,19 @@ import {
   status as daemonStatus,
   ensureRunning,
   readLogFile,
-  upgradeServer,
 } from '../daemon.js'
-import { readConfig, writeConfig } from '../config.js'
+import { readConfig, writeConfig, activeContext, localContext, contextNameFromUrl, uniqueContextName } from '../config.js'
 import { getApi } from '../client.js'
 import { sync } from '../sync.js'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
 
-function assertLocalMode(config: { server: { mode: string } }, action: string) {
-  if (config.server.mode === 'remote') {
+function assertLocalContext(config: { current_context: string; contexts: Record<string, { mode: string }> }, action: string) {
+  const ctx = config.contexts[config.current_context]
+  if (ctx.mode === 'remote') {
     throw createError(ErrorCode.INVALID_MODE, {
-      message: `Server is in remote mode. Cannot ${action}.`,
+      message: `Active context is remote. Cannot ${action}.`,
     })
   }
 }
@@ -35,6 +35,7 @@ const statusCmd = Cli.create('status', {
       healthy: s.healthy,
       running: s.running,
       pid: s.pid,
+      serverVersion: health.serverVersion ?? null,
       latencyMs: health.latencyMs ?? null,
     }
   },
@@ -44,12 +45,13 @@ const startCmd = Cli.create('start', {
   description: 'Start the local server daemon',
   async run() {
     const config = await readConfig()
-    assertLocalMode(config, 'start')
+    assertLocalContext(config, 'start')
+    const ctx = activeContext(config)
 
     const health = await healthCheck({ timeout: 2000 })
     if (health.healthy) {
       const s = await daemonStatus()
-      return { already_running: true, pid: s.pid, url: config.server.url }
+      return { already_running: true, pid: s.pid, url: ctx.url }
     }
 
     const { pid } = await start()
@@ -58,7 +60,7 @@ const startCmd = Cli.create('start', {
     while (Date.now() < deadline) {
       await new Promise(r => setTimeout(r, 200))
       const check = await healthCheck({ timeout: 2000 })
-      if (check.healthy) return { started: true, pid, url: config.server.url }
+      if (check.healthy) return { started: true, pid, url: ctx.url }
     }
 
     throw createError(ErrorCode.SERVER_START_FAILED, {
@@ -71,7 +73,7 @@ const stopCmd = Cli.create('stop', {
   description: 'Stop the local server daemon',
   async run() {
     const config = await readConfig()
-    assertLocalMode(config, 'stop')
+    assertLocalContext(config, 'stop')
 
     const result = await stop()
     if (!result.stopped) {
@@ -89,9 +91,10 @@ const logsCmd = Cli.create('logs', {
   }),
   async run(c) {
     const config = await readConfig()
+    const local = localContext(config)
 
     if (c.options.follow) {
-      const child = spawn('tail', ['-f', '-n', String(c.options.lines), config.server.log_file], {
+      const child = spawn('tail', ['-f', '-n', String(c.options.lines), local.log_file], {
         stdio: 'inherit',
       })
       await new Promise<void>((resolve) => {
@@ -106,32 +109,31 @@ const logsCmd = Cli.create('logs', {
 })
 
 const localCmd = Cli.create('local', {
-  description: 'Switch to managed local server',
+  description: 'Switch to local server (use `brainjar context use local` instead)',
   async run() {
     const config = await readConfig()
-    config.server.url = 'http://localhost:7742'
-    config.server.mode = 'local'
+    config.current_context = 'local'
     await writeConfig(config)
 
     await ensureRunning()
 
     const api = await getApi()
+    const ctx = activeContext(config)
 
-    // Ensure workspace exists (ignore conflict if already created)
     try {
-      await api.post('/api/v1/workspaces', { name: config.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
     } catch (e: any) {
       if (e.code !== 'CONFLICT') throw e
     }
 
     await sync({ api })
 
-    return { mode: 'local', url: config.server.url }
+    return { mode: 'local', url: ctx.url }
   },
 })
 
 const remoteCmd = Cli.create('remote', {
-  description: 'Switch to a remote server',
+  description: 'Switch to a remote server (use `brainjar context add` instead)',
   args: z.object({
     url: z.string().describe('Remote server URL'),
   }),
@@ -144,15 +146,26 @@ const remoteCmd = Cli.create('remote', {
     }
 
     const config = await readConfig()
-    config.server.url = url
-    config.server.mode = 'remote'
+
+    // Find existing context with this URL, or create one
+    let ctxName = Object.entries(config.contexts).find(([, ctx]) => ctx.url === url)?.[0]
+    if (!ctxName) {
+      ctxName = uniqueContextName(contextNameFromUrl(url), config.contexts)
+      config.contexts[ctxName] = {
+        url,
+        mode: 'remote',
+        workspace: 'default',
+      }
+    }
+
+    config.current_context = ctxName
     await writeConfig(config)
 
     const api = await getApi()
+    const ctx = activeContext(config)
 
-    // Ensure workspace exists (ignore conflict if already created)
     try {
-      await api.post('/api/v1/workspaces', { name: config.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
     } catch (e: any) {
       if (e.code !== 'CONFLICT') throw e
     }
@@ -163,43 +176,6 @@ const remoteCmd = Cli.create('remote', {
   },
 })
 
-const upgradeCmd = Cli.create('upgrade', {
-  description: 'Upgrade the server binary to the latest version',
-  async run() {
-    const config = await readConfig()
-    assertLocalMode(config, 'upgrade')
-
-    // Stop server if running before replacing binary
-    const s = await daemonStatus()
-    const wasRunning = s.running
-
-    if (wasRunning) {
-      await stop()
-    }
-
-    const result = await upgradeServer()
-
-    if (result.alreadyLatest) {
-      if (wasRunning) await start()
-      return { upgraded: false, version: result.version, message: 'Already on latest version' }
-    }
-
-    // Restart if it was running
-    if (wasRunning) {
-      const { pid } = await start()
-      const deadline = Date.now() + 10_000
-      while (Date.now() < deadline) {
-        await new Promise(r => setTimeout(r, 200))
-        const check = await healthCheck({ timeout: 2000 })
-        if (check.healthy) return { upgraded: true, version: result.version, pid, restarted: true }
-      }
-      return { upgraded: true, version: result.version, restarted: false, warning: 'Server upgraded but failed health check after restart' }
-    }
-
-    return { upgraded: true, version: result.version }
-  },
-})
-
 export const server = Cli.create('server', {
   description: 'Manage the brainjar server',
 })
@@ -209,4 +185,3 @@ export const server = Cli.create('server', {
   .command(logsCmd)
   .command(localCmd)
   .command(remoteCmd)
-  .command(upgradeCmd)