@brainjar/cli 0.3.0 → 0.4.0

package/README.md

@@ -36,20 +36,22 @@ brainjar status
 ## Commands
 
 ```
-brainjar init [--default] [--obsidian] [--backend claude|codex]
-brainjar status [--sync] [--global|--local] [--short]
+brainjar init [--default] [--backend claude|codex]
+brainjar status [--sync] [--workspace] [--project] [--short]
 brainjar sync [--quiet]
-brainjar compose <brain> [--task <text>]
+brainjar compose <brain> [--persona <name>] [--task <text>]
 
 brainjar brain save|use|list|show|drop
-brainjar soul create|list|show|use|drop
-brainjar persona create|list|show|use|drop
-brainjar rules create|list|show|add|remove
+brainjar soul create|use|show|list|drop
+brainjar persona create|use|show|list|drop
+brainjar rules create|add|remove|show|list
 
 brainjar pack export|import
 brainjar hooks install|remove|status [--local]
-brainjar shell [--brain|--soul|--persona|--rules-add|--rules-remove]
+brainjar shell [--brain <name>] [--soul <name>] [--persona <name>]
 brainjar reset [--backend claude|codex]
+brainjar server start|stop|status|logs|local|remote|upgrade
+brainjar migrate [--dry-run] [--skip-backup]
 ```
 
 See the [CLI reference](https://brainjar.sh/reference/cli/) for full details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainjar/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shape how your AI thinks — composable soul, persona, and rules for AI agents",
   "type": "module",
   "license": "MIT",

package/src/api-types.ts

@@ -0,0 +1,155 @@
+/** Soul as returned by the server. */
+export interface ApiSoul {
+  slug: string
+  title: string | null
+  content: string
+}
+
+/** Persona as returned by the server. */
+export interface ApiPersona {
+  slug: string
+  title: string | null
+  content: string
+  bundled_rules: string[]
+}
+
+/** Single entry within a rule. */
+export interface ApiRuleEntry {
+  name: string
+  content: string
+}
+
+/** Rule as returned by the server. */
+export interface ApiRule {
+  slug: string
+  entries: ApiRuleEntry[]
+}
+
+/** Rule summary for list responses. */
+export interface ApiRuleSummary {
+  slug: string
+  entry_count: number
+}
+
+/** Brain as returned by the server. */
+export interface ApiBrain {
+  slug: string
+  soul_slug: string
+  persona_slug: string
+  rule_slugs: string[]
+}
+
+/** List response wrappers. */
+export interface ApiSoulList {
+  souls: Array<{ slug: string; title: string | null }>
+}
+
+export interface ApiPersonaList {
+  personas: Array<{ slug: string; title: string | null }>
+}
+
+export interface ApiRuleList {
+  rules: ApiRuleSummary[]
+}
+
+export interface ApiBrainList {
+  brains: ApiBrain[]
+}
+
+/** Effective state as returned by GET /api/v1/state. */
+export interface ApiEffectiveState {
+  soul: string | null
+  persona: string | null
+  rules: string[]
+}
+
+/** State override at a single scope, returned by GET /api/v1/state/override. */
+export interface ApiStateOverride {
+  soul_slug?: string | null
+  persona_slug?: string | null
+  rule_slugs?: string[]
+  rules_to_add?: string[]
+  rules_to_remove?: string[]
+}
+
+/** Body for PUT /api/v1/state — partial update. */
+export interface ApiStateMutation {
+  soul_slug?: string | null
+  persona_slug?: string | null
+  rule_slugs?: string[]
+  rules_to_add?: string[]
+  rules_to_remove?: string[]
+}
+
+/** Token estimate breakdown from compose. */
+export interface ApiTokenEstimate {
+  soul: number
+  persona: number
+  rules: number
+  task: number
+  total: number
+}
+
+/** Response from POST /api/v1/compose. */
+export interface ApiComposeResult {
+  prompt: string
+  soul: string | null
+  persona: string
+  brain?: string
+  rules: string[]
+  token_estimate?: ApiTokenEstimate
+  warnings?: string[]
+}
+
+// --- Content bundle types (export/import) ---
+
+export interface BundleSoul {
+  content: string
+}
+
+export interface BundlePersona {
+  content: string
+  bundled_rules: string[]
+}
+
+export interface BundleRuleEntry {
+  sort_key: number
+  content: string
+}
+
+export interface BundleRule {
+  entries: BundleRuleEntry[]
+}
+
+export interface BundleBrain {
+  soul_slug: string
+  persona_slug: string
+  rule_slugs: string[]
+}
+
+export interface BundleState {
+  soul: string
+  persona: string
+  rules: string[]
+}
+
+export interface ContentBundle {
+  souls?: Record<string, BundleSoul>
+  personas?: Record<string, BundlePersona>
+  rules?: Record<string, BundleRule>
+  brains?: Record<string, BundleBrain>
+  state?: BundleState
+}
+
+export interface ImportCounts {
+  souls: number
+  personas: number
+  rules: number
+  brains: number
+  state: boolean
+}
+
+export interface ApiImportResult {
+  imported: ImportCounts
+  warnings: string[]
+}

package/src/cli.ts

@@ -13,6 +13,8 @@ import { compose } from './commands/compose.js'
 import { sync } from './commands/sync.js'
 import { hooks } from './commands/hooks.js'
 import { pack } from './commands/pack.js'
+import { server } from './commands/server.js'
+import { migrate } from './commands/migrate.js'
 
 Cli.create('brainjar', {
   description: 'Shape how your AI thinks — soul, persona, rules',
@@ -31,4 +33,6 @@ Cli.create('brainjar', {
   .command(sync)
   .command(hooks)
   .command(pack)
+  .command(server)
+  .command(migrate)
   .serve()

package/src/client.ts

@@ -0,0 +1,157 @@
+import { Errors } from 'incur'
+import { basename } from 'node:path'
+import { readConfig } from './config.js'
+import { getLocalDir } from './paths.js'
+import { access } from 'node:fs/promises'
+import { ensureRunning } from './daemon.js'
+import { ErrorCode, createError } from './errors.js'
+
+const { IncurError } = Errors
+
+export interface ClientOptions {
+  serverUrl?: string
+  workspace?: string
+  project?: string
+  session?: string
+  timeout?: number
+}
+
+export interface RequestOptions {
+  timeout?: number
+  headers?: Record<string, string>
+  project?: string
+}
+
+export interface BrainjarClient {
+  get<T>(path: string, options?: RequestOptions): Promise<T>
+  post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>
+  put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>
+  delete<T>(path: string, options?: RequestOptions): Promise<T>
+}
+
+const ERROR_MAP: Record<number, { code: ErrorCode; hint?: string }> = {
+  400: { code: ErrorCode.BAD_REQUEST },
+  401: { code: ErrorCode.UNAUTHORIZED, hint: 'Check your server configuration.' },
+  404: { code: ErrorCode.NOT_FOUND },
+  409: { code: ErrorCode.CONFLICT },
+  422: { code: ErrorCode.VALIDATION_ERROR },
+  500: { code: ErrorCode.SERVER_ERROR, hint: 'Check server logs at ~/.brainjar/server.log' },
+  502: { code: ErrorCode.SERVER_ERROR, hint: 'Server may be starting up. Try again.' },
+  503: { code: ErrorCode.SERVER_UNAVAILABLE, hint: 'Server is not ready. Try again in a moment.' },
+}
+
+async function detectProject(explicit?: string): Promise<string | null> {
+  if (explicit) return explicit
+  try {
+    await access(getLocalDir())
+    return basename(process.cwd())
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Create a client instance bound to the current config.
+ */
+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 session = options?.session ?? process.env.BRAINJAR_SESSION ?? null
+  const defaultTimeout = options?.timeout ?? 10_000
+  const mode = config.server.mode
+
+  async function request<T>(method: string, path: string, body?: unknown, reqOpts?: RequestOptions): Promise<T> {
+    const url = `${serverUrl}${path}`
+    const timeout = reqOpts?.timeout ?? defaultTimeout
+
+    const headers: Record<string, string> = {
+      'Accept': 'application/json',
+      'X-Brainjar-Workspace': workspace,
+      ...(reqOpts?.headers ?? {}),
+    }
+
+    const project = await detectProject(reqOpts?.project ?? options?.project)
+    if (project) headers['X-Brainjar-Project'] = project
+    if (session) headers['X-Brainjar-Session'] = session
+
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json'
+    }
+
+    let response: Response
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeout),
+      })
+    } catch (e) {
+      if (e instanceof DOMException && e.name === 'TimeoutError') {
+        throw createError(ErrorCode.TIMEOUT, {
+          message: `Request timed out after ${timeout}ms`,
+        })
+      }
+      const hint = mode === 'local'
+        ? "Run 'brainjar server start' or 'brainjar init'."
+        : `Check the URL or run 'brainjar server remote <url>'.`
+      throw createError(ErrorCode.SERVER_UNREACHABLE, {
+        params: [serverUrl],
+        hint,
+      })
+    }
+
+    if (!response.ok) {
+      let serverError: { error?: string | { code?: string; message?: string }; code?: string; message?: string } | null = null
+      try {
+        serverError = await response.json()
+      } catch {}
+
+      const mapped = ERROR_MAP[response.status]
+
+      // Handle both flat { error: "msg", code: "X" } and nested { error: { code: "X", message: "msg" } }
+      let code: string
+      let message: string
+      if (serverError?.error && typeof serverError.error === 'object') {
+        code = serverError.error.code ?? mapped?.code ?? ErrorCode.API_ERROR
+        message = serverError.error.message ?? `Server returned ${response.status}`
+      } else {
+        code = serverError?.code ?? mapped?.code ?? ErrorCode.API_ERROR
+        message = (typeof serverError?.error === 'string' ? serverError.error : null)
+          ?? serverError?.message
+          ?? `Server returned ${response.status}`
+      }
+      const hint = mapped?.hint
+
+      throw new IncurError({ code, message, hint })
+    }
+
+    return response.json() as Promise<T>
+  }
+
+  return {
+    get<T>(path: string, options?: RequestOptions) {
+      return request<T>('GET', path, undefined, options)
+    },
+    post<T>(path: string, body?: unknown, options?: RequestOptions) {
+      return request<T>('POST', path, body, options)
+    },
+    put<T>(path: string, body?: unknown, options?: RequestOptions) {
+      return request<T>('PUT', path, body, options)
+    },
+    delete<T>(path: string, options?: RequestOptions) {
+      return request<T>('DELETE', path, undefined, options)
+    },
+  }
+}
+
+/**
+ * Ensure the server is running and return a connected client.
+ * Convenience wrapper — commands should use this instead of calling
+ * ensureRunning() + createClient() separately.
+ */
+export async function getApi(options?: ClientOptions): Promise<BrainjarClient> {
+  await ensureRunning()
+  return createClient(options)
+}

package/src/commands/brain.ts

@@ -1,24 +1,12 @@
 import { Cli, z, Errors } from 'incur'
+import { basename } from 'node:path'
 
 const { IncurError } = Errors
-import { readdir, readFile, writeFile, access, rm } from 'node:fs/promises'
-import { join, basename } from 'node:path'
-import { stringify as stringifyYaml } from 'yaml'
-import { paths } from '../paths.js'
-import {
-  readState,
-  writeState,
-  withStateLock,
-  readLocalState,
-  writeLocalState,
-  withLocalStateLock,
-  readEnvState,
-  mergeState,
-  requireBrainjarDir,
-  normalizeSlug,
-} from '../state.js'
-import { readBrain, type BrainConfig } from '../brain.js'
+import { ErrorCode, createError } from '../errors.js'
+import { normalizeSlug, getEffectiveState, putState } from '../state.js'
 import { sync } from '../sync.js'
+import { getApi } from '../client.js'
+import type { ApiBrain, ApiBrainList, ApiSoul, ApiPersona } from '../api-types.js'
 
 export const brain = Cli.create('brain', {
   description: 'Manage brains — full-stack configuration snapshots (soul + persona + rules)',
@@ -26,65 +14,50 @@ export const brain = Cli.create('brain', {
   .command('save', {
     description: 'Snapshot current effective state as a named brain',
     args: z.object({
-      name: z.string().describe('Brain name (will be used as filename)'),
+      name: z.string().describe('Brain name'),
     }),
     options: z.object({
-      overwrite: z.boolean().default(false).describe('Overwrite existing brain file'),
+      overwrite: z.boolean().default(false).describe('Overwrite existing brain'),
     }),
     async run(c) {
-      await requireBrainjarDir()
       const name = normalizeSlug(c.args.name, 'brain name')
-      const dest = join(paths.brains, `${name}.yaml`)
+      const api = await getApi()
 
       // Check for existing brain
       if (!c.options.overwrite) {
         try {
-          await access(dest)
-          throw new IncurError({
-            code: 'BRAIN_EXISTS',
-            message: `Brain "${name}" already exists.`,
-            hint: 'Use --overwrite to replace it, or choose a different name.',
-          })
+          await api.get<ApiBrain>(`/api/v1/brains/${name}`)
+          throw createError(ErrorCode.BRAIN_EXISTS, { params: [name] })
         } catch (e) {
-          if (e instanceof IncurError) throw e
+          if (e instanceof IncurError && e.code === ErrorCode.BRAIN_EXISTS) throw e
+          if (e instanceof IncurError && e.code !== ErrorCode.NOT_FOUND) throw e
         }
       }
 
-      // Read effective state
-      const globalState = await readState()
-      const localState = await readLocalState()
-      const envState = readEnvState()
-      const effective = mergeState(globalState, localState, envState)
-
-      if (!effective.soul.value) {
-        throw new IncurError({
-          code: 'NO_ACTIVE_SOUL',
-          message: 'Cannot save brain: no active soul.',
-          hint: 'Activate a soul first with `brainjar soul use <name>`.',
-        })
+      const effective = await getEffectiveState(api)
+
+      if (!effective.soul) {
+        throw createError(ErrorCode.NO_ACTIVE_SOUL)
       }
 
-      if (!effective.persona.value) {
-        throw new IncurError({
-          code: 'NO_ACTIVE_PERSONA',
-          message: 'Cannot save brain: no active persona.',
-          hint: 'Activate a persona first with `brainjar persona use <name>`.',
-        })
+      if (!effective.persona) {
+        throw createError(ErrorCode.NO_ACTIVE_PERSONA)
       }
 
       const activeRules = effective.rules
-        .filter(r => !r.scope.startsWith('-'))
-        .map(r => r.value)
 
-      const config: BrainConfig = {
-        soul: effective.soul.value,
-        persona: effective.persona.value,
+      await api.put<ApiBrain>(`/api/v1/brains/${name}`, {
+        soul_slug: effective.soul,
+        persona_slug: effective.persona,
+        rule_slugs: activeRules,
+      })
+
+      return {
+        saved: name,
+        soul: effective.soul,
+        persona: effective.persona,
         rules: activeRules,
       }
-
-      await writeFile(dest, stringifyYaml(config))
-
-      return { saved: name, ...config }
     },
   })
   .command('use', {
@@ -93,68 +66,77 @@ export const brain = Cli.create('brain', {
       name: z.string().describe('Brain name to activate'),
     }),
     options: z.object({
-      local: z.boolean().default(false).describe('Apply brain at project scope'),
+      project: z.boolean().default(false).describe('Apply brain at project scope'),
     }),
     async run(c) {
-      await requireBrainjarDir()
       const name = normalizeSlug(c.args.name, 'brain name')
-      const config = await readBrain(name)
+      const api = await getApi()
+
+      let config: ApiBrain
+      try {
+        config = await api.get<ApiBrain>(`/api/v1/brains/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.BRAIN_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
 
       // Validate soul exists
       try {
-        await readFile(join(paths.souls, `${config.soul}.md`), 'utf-8')
-      } catch {
-        throw new IncurError({
-          code: 'SOUL_NOT_FOUND',
-          message: `Brain "${name}" references soul "${config.soul}" which does not exist.`,
-          hint: 'Create the soul first or update the brain file.',
-        })
+        await api.get<ApiSoul>(`/api/v1/souls/${config.soul_slug}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.SOUL_NOT_FOUND, {
+            params: [config.soul_slug],
+            message: `Brain "${name}" references soul "${config.soul_slug}" which does not exist.`,
+            hint: 'Create the soul first or update the brain.',
+          })
+        }
+        throw e
       }
 
       // Validate persona exists
       try {
-        await readFile(join(paths.personas, `${config.persona}.md`), 'utf-8')
-      } catch {
-        throw new IncurError({
-          code: 'PERSONA_NOT_FOUND',
-          message: `Brain "${name}" references persona "${config.persona}" which does not exist.`,
-          hint: 'Create the persona first or update the brain file.',
-        })
+        await api.get<ApiPersona>(`/api/v1/personas/${config.persona_slug}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.PERSONA_NOT_FOUND, {
+            params: [config.persona_slug],
+            message: `Brain "${name}" references persona "${config.persona_slug}" which does not exist.`,
+            hint: 'Create the persona first or update the brain.',
+          })
+        }
+        throw e
       }
 
-      if (c.options.local) {
-        await withLocalStateLock(async () => {
-          const local = await readLocalState()
-          local.soul = config.soul
-          local.persona = config.persona
-          // Replace rules entirely — brain is a complete snapshot
-          local.rules = { add: config.rules, remove: [] }
-          await writeLocalState(local)
-          await sync({ local: true })
-        })
-      } else {
-        await withStateLock(async () => {
-          const state = await readState()
-          state.soul = config.soul
-          state.persona = config.persona
-          state.rules = config.rules
-          await writeState(state)
-          await sync()
-        })
+      const mutationOpts = c.options.project
+        ? { project: basename(process.cwd()) }
+        : undefined
+      await putState(api, {
+        soul_slug: config.soul_slug,
+        persona_slug: config.persona_slug,
+        rule_slugs: config.rule_slugs,
+      }, mutationOpts)
+
+      await sync({ api })
+      if (c.options.project) await sync({ api, project: true })
+
+      return {
+        activated: name,
+        project: c.options.project,
+        soul: config.soul_slug,
+        persona: config.persona_slug,
+        rules: config.rule_slugs,
       }
-
-      return { activated: name, local: c.options.local, ...config }
     },
   })
   .command('list', {
     description: 'List available brains',
     async run() {
-      await requireBrainjarDir()
-      const entries = await readdir(paths.brains).catch(() => [])
-      const brains = entries
-        .filter(f => f.endsWith('.yaml'))
-        .map(f => basename(f, '.yaml'))
-      return { brains }
+      const api = await getApi()
+      const result = await api.get<ApiBrainList>('/api/v1/brains')
+      return { brains: result.brains.map(b => b.slug) }
     },
   })
   .command('show', {
@@ -163,10 +145,18 @@ export const brain = Cli.create('brain', {
       name: z.string().describe('Brain name to show'),
     }),
     async run(c) {
-      await requireBrainjarDir()
       const name = normalizeSlug(c.args.name, 'brain name')
-      const config = await readBrain(name)
-      return { name, ...config }
+      const api = await getApi()
+
+      try {
+        const config = await api.get<ApiBrain>(`/api/v1/brains/${name}`)
+        return { name, soul: config.soul_slug, persona: config.persona_slug, rules: config.rule_slugs }
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.BRAIN_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
     },
   })
   .command('drop', {
@@ -175,22 +165,18 @@ export const brain = Cli.create('brain', {
       name: z.string().describe('Brain name to delete'),
     }),
     async run(c) {
-      await requireBrainjarDir()
       const name = normalizeSlug(c.args.name, 'brain name')
-      const file = join(paths.brains, `${name}.yaml`)
+      const api = await getApi()
 
       try {
-        await access(file)
-      } catch {
-        throw new IncurError({
-          code: 'BRAIN_NOT_FOUND',
-          message: `Brain "${name}" not found.`,
-          hint: 'Run `brainjar brain list` to see available brains.',
-        })
+        await api.delete(`/api/v1/brains/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.BRAIN_NOT_FOUND, { params: [name] })
+        }
+        throw e
       }
 
-      await rm(file)
-
       return { dropped: name }
     },
   })