@brainjar/cli 0.2.3 → 0.4.0

package/README.md

@@ -5,9 +5,9 @@
 [![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)
 
-Shape how your AI thinks — identity, soul, persona, rules.
+Shape how your AI thinks — soul, persona, rules.
 
-brainjar manages AI agent behavior through composable layers. Instead of one monolithic config file, you separate **what the agent sounds like** (soul), **how it works** (persona), and **what constraints it follows** (rules). Each layer is a markdown file. Mix and match them per project, per task, or per session.
+brainjar manages AI agent behavior through composable layers. Instead of one monolithic config file, you separate **what the agent sounds like** (soul), **how it works** (persona), and **what constraints it follows** (rules). Each layer is a markdown file. Mix, match, and switch them per project, per task, or per session.
 
 **[Documentation](https://brainjar.sh)** · **[Getting Started](https://brainjar.sh/getting-started/)**
 
@@ -36,21 +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 identity create|list|show|use|drop|unlock|get|status|lock
 brainjar pack export|import
 brainjar hooks install|remove|status [--local]
-brainjar shell [--brain|--soul|--persona|--identity|--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,7 +1,7 @@
 {
   "name": "@brainjar/cli",
-  "version": "0.2.3",
-  "description": "Shape how your AI thinks — composable identity, soul, persona, and rules for AI agents",
+  "version": "0.4.0",
+  "description": "Shape how your AI thinks — composable soul, persona, and rules for AI agents",
   "type": "module",
   "license": "MIT",
   "repository": {

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

@@ -2,7 +2,6 @@
 import { Cli } from 'incur'
 import pkg from '../package.json'
 import { init } from './commands/init.js'
-import { identity } from './commands/identity.js'
 import { soul } from './commands/soul.js'
 import { persona } from './commands/persona.js'
 import { rules } from './commands/rules.js'
@@ -14,9 +13,11 @@ 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 — identity, soul, persona, rules',
+  description: 'Shape how your AI thinks — soul, persona, rules',
   version: pkg.version,
   sync: { depth: 0 },
 })
@@ -26,11 +27,12 @@ Cli.create('brainjar', {
   .command(persona)
   .command(rules)
   .command(brain)
-  .command(identity)
   .command(reset)
   .command(shell)
   .command(compose)
   .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)
+}