@brainjar/cli 0.3.0 → 0.4.0

package/src/commands/shell.ts

@@ -1,99 +1,107 @@
 import { Cli, z, Errors } from 'incur'
+import { randomUUID } from 'node:crypto'
 
 const { IncurError } = Errors
+import { ErrorCode, createError } from '../errors.js'
 import { spawn } from 'node:child_process'
-import { access } from 'node:fs/promises'
-import { requireBrainjarDir } from '../state.js'
+import { putState } from '../state.js'
 import { sync } from '../sync.js'
-import { getLocalDir } from '../paths.js'
-import { readBrain } from '../brain.js'
+import { getApi } from '../client.js'
+import type { ApiBrain } from '../api-types.js'
 
 export const shell = Cli.create('shell', {
-  description: 'Spawn a subshell with BRAINJAR_* env vars set',
+  description: 'Spawn a subshell with session-scoped state overrides',
   options: z.object({
-    brain: z.string().optional().describe('Brain name — sets soul, persona, and rules from brain file'),
+    brain: z.string().optional().describe('Brain name — sets soul, persona, and rules from brain'),
     soul: z.string().optional().describe('Soul override for this session'),
     persona: z.string().optional().describe('Persona override for this session'),
     'rules-add': z.string().optional().describe('Comma-separated rules to add'),
     'rules-remove': z.string().optional().describe('Comma-separated rules to remove'),
   }),
   async run(c) {
-    await requireBrainjarDir()
-
     const individualFlags = c.options.soul || c.options.persona
       || c.options['rules-add'] || c.options['rules-remove']
 
     if (c.options.brain && individualFlags) {
-      throw new IncurError({
-        code: 'MUTUALLY_EXCLUSIVE',
+      throw createError(ErrorCode.MUTUALLY_EXCLUSIVE, {
         message: '--brain is mutually exclusive with --soul, --persona, --rules-add, --rules-remove.',
         hint: 'Use --brain alone or individual flags, not both.',
       })
     }
 
-    const envOverrides: Record<string, string> = {}
+    if (!c.options.brain && !individualFlags) {
+      throw createError(ErrorCode.NO_OVERRIDES, {
+        message: 'No overrides specified.',
+      })
+    }
+
+    // Create a unique session ID
+    const sessionId = randomUUID()
+    const api = await getApi({ session: sessionId })
+
+    // Build session-scoped state mutation
+    const mutation: Record<string, unknown> = {}
+    const labels: string[] = []
 
     if (c.options.brain) {
-      const config = await readBrain(c.options.brain)
-      envOverrides.BRAINJAR_SOUL = config.soul
-      envOverrides.BRAINJAR_PERSONA = config.persona
-      if (config.rules.length > 0) {
-        envOverrides.BRAINJAR_RULES_ADD = config.rules.join(',')
-      }
+      const config = await api.get<ApiBrain>(`/api/v1/brains/${c.options.brain}`)
+      mutation.soul_slug = config.soul_slug
+      mutation.persona_slug = config.persona_slug
+      mutation.rule_slugs = config.rule_slugs
+      labels.push(`brain: ${c.options.brain}`)
     } else {
-      if (c.options.soul) envOverrides.BRAINJAR_SOUL = c.options.soul
-      if (c.options.persona) envOverrides.BRAINJAR_PERSONA = c.options.persona
-      if (c.options['rules-add']) envOverrides.BRAINJAR_RULES_ADD = c.options['rules-add']
-      if (c.options['rules-remove']) envOverrides.BRAINJAR_RULES_REMOVE = c.options['rules-remove']
+      if (c.options.soul) {
+        mutation.soul_slug = c.options.soul
+        labels.push(`soul: ${c.options.soul}`)
+      }
+      if (c.options.persona) {
+        mutation.persona_slug = c.options.persona
+        labels.push(`persona: ${c.options.persona}`)
+      }
+      if (c.options['rules-add']) {
+        mutation.rules_to_add = c.options['rules-add'].split(',').map(s => s.trim())
+        labels.push(`+rules: ${c.options['rules-add']}`)
+      }
+      if (c.options['rules-remove']) {
+        mutation.rules_to_remove = c.options['rules-remove'].split(',').map(s => s.trim())
+        labels.push(`-rules: ${c.options['rules-remove']}`)
+      }
     }
 
-    if (Object.keys(envOverrides).length === 0) {
-      throw new IncurError({
-        code: 'NO_OVERRIDES',
-        message: 'No overrides specified.',
-        hint: 'Use --brain, --soul, --persona, --rules-add, or --rules-remove.',
-      })
-    }
+    // Apply session-scoped state on server
+    await putState(api, mutation)
 
-    // Sync with env overrides passed explicitly (no process.env mutation)
-    const hasLocal = await access(getLocalDir()).then(() => true, () => false)
-    await sync({ envOverrides })
-    if (hasLocal) await sync({ local: true, envOverrides })
+    // Sync CLAUDE.md with session state
+    await sync({ api })
 
     // Print active config banner
-    const labels: string[] = []
-    if (envOverrides.BRAINJAR_SOUL) labels.push(`soul: ${envOverrides.BRAINJAR_SOUL}`)
-    if (envOverrides.BRAINJAR_PERSONA) labels.push(`persona: ${envOverrides.BRAINJAR_PERSONA}`)
-    if (envOverrides.BRAINJAR_RULES_ADD) labels.push(`+rules: ${envOverrides.BRAINJAR_RULES_ADD}`)
-    if (envOverrides.BRAINJAR_RULES_REMOVE) labels.push(`-rules: ${envOverrides.BRAINJAR_RULES_REMOVE}`)
-
     if (!c.agent) {
       const banner = `[brainjar] ${labels.join(' | ')}`
       process.stderr.write(`${banner}\n`)
       process.stderr.write(`${'─'.repeat(banner.length)}\n`)
     }
 
-    // Spawn subshell with overrides
+    // Spawn subshell with session ID so nested brainjar commands use the session
     const userShell = process.env.SHELL || '/bin/sh'
     const child = spawn(userShell, [], {
       stdio: 'inherit',
-      env: { ...process.env, ...envOverrides },
+      env: { ...process.env, BRAINJAR_SESSION: sessionId },
     })
 
     return new Promise((resolve, reject) => {
       child.on('exit', async (code) => {
-        // Re-sync without env overrides to restore config
+        // Clear session state and re-sync to restore
         let syncWarning: string | undefined
         try {
-          await sync()
-          if (hasLocal) await sync({ local: true })
+          const cleanApi = await getApi()
+          await sync({ api: cleanApi })
         } catch (err) {
           syncWarning = `Re-sync on exit failed: ${(err as Error).message}`
         }
 
         const result = {
           shell: userShell,
-          env: envOverrides,
+          session: sessionId,
           exitCode: code ?? 0,
           ...(syncWarning ? { warning: syncWarning } : {}),
         }
@@ -106,8 +114,7 @@ export const shell = Cli.create('shell', {
         }
       })
       child.on('error', (err) => {
-        reject(new IncurError({
-          code: 'SHELL_ERROR',
+        reject(createError(ErrorCode.SHELL_ERROR, {
           message: `Failed to spawn shell: ${err.message}`,
         }))
       })

package/src/commands/soul.ts

@@ -1,11 +1,12 @@
 import { Cli, z, Errors } from 'incur'
+import { basename } from 'node:path'
 
 const { IncurError } = Errors
-import { readdir, readFile, writeFile, access } from 'node:fs/promises'
-import { join, basename } from 'node:path'
-import { paths } from '../paths.js'
-import { readState, writeState, withStateLock, readLocalState, writeLocalState, withLocalStateLock, readEnvState, mergeState, requireBrainjarDir, stripFrontmatter, normalizeSlug } from '../state.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 { ApiSoul, ApiSoulList } from '../api-types.js'
 
 export const soul = Cli.create('soul', {
   description: 'Manage soul — personality and values for the agent',
@@ -13,25 +14,22 @@ export const soul = Cli.create('soul', {
   .command('create', {
     description: 'Create a new soul',
     args: z.object({
-      name: z.string().describe('Soul name (will be used as filename)'),
+      name: z.string().describe('Soul name'),
     }),
     options: z.object({
       description: z.string().optional().describe('One-line description of the soul'),
     }),
     async run(c) {
-      await requireBrainjarDir()
       const name = normalizeSlug(c.args.name, 'soul name')
-      const dest = join(paths.souls, `${name}.md`)
+      const api = await getApi()
 
+      // Check if it already exists
       try {
-        await access(dest)
-        throw new IncurError({
-          code: 'SOUL_EXISTS',
-          message: `Soul "${name}" already exists.`,
-          hint: 'Choose a different name or edit the existing file.',
-        })
+        await api.get<ApiSoul>(`/api/v1/souls/${name}`)
+        throw createError(ErrorCode.SOUL_EXISTS, { params: [name] })
       } catch (e) {
-        if (e instanceof IncurError) throw e
+        if (e instanceof IncurError && e.code === ErrorCode.SOUL_EXISTS) throw e
+        if (e instanceof IncurError && e.code !== ErrorCode.NOT_FOUND) throw e
       }
 
       const lines: string[] = []
@@ -43,27 +41,26 @@ export const soul = Cli.create('soul', {
       }
 
       const content = lines.join('\n')
-      await writeFile(dest, content)
+      await api.put<ApiSoul>(`/api/v1/souls/${name}`, { content })
 
       if (c.agent || c.formatExplicit) {
-        return { created: dest, name, template: content }
+        return { created: name, name, template: content }
       }
 
       return {
-        created: dest,
+        created: name,
         name,
         template: `\n${content}`,
-        next: `Edit ${dest} to flesh out your soul, then run \`brainjar soul use ${name}\` to activate.`,
+        next: `Run \`brainjar soul show ${name}\` to view, then \`brainjar soul use ${name}\` to activate.`,
       }
     },
   })
   .command('list', {
     description: 'List available souls',
     async run() {
-      await requireBrainjarDir()
-      const entries = await readdir(paths.souls).catch(() => [])
-      const souls = entries.filter(f => f.endsWith('.md')).map(f => basename(f, '.md'))
-      return { souls }
+      const api = await getApi()
+      const result = await api.get<ApiSoulList>('/api/v1/souls')
+      return { souls: result.souls.map(s => s.slug) }
     },
   })
   .command('show', {
@@ -72,136 +69,104 @@ export const soul = Cli.create('soul', {
       name: z.string().optional().describe('Soul name to show (defaults to active soul)'),
     }),
     options: z.object({
-      local: z.boolean().default(false).describe('Show local soul override (if any)'),
+      project: z.boolean().default(false).describe('Show project soul override (if any)'),
       short: z.boolean().default(false).describe('Print only the active soul name'),
     }),
     async run(c) {
-      await requireBrainjarDir()
+      const api = await getApi()
 
       if (c.options.short) {
         if (c.args.name) return c.args.name
-        const global = await readState()
-        const local = await readLocalState()
-        const env = readEnvState()
-        const effective = mergeState(global, local, env)
-        return effective.soul.value ?? 'none'
+        const state = await getEffectiveState(api)
+        return state.soul ?? 'none'
       }
 
-      // If a specific name was given, show that soul directly
       if (c.args.name) {
         const name = normalizeSlug(c.args.name, 'soul name')
         try {
-          const raw = await readFile(join(paths.souls, `${name}.md`), 'utf-8')
-          const content = stripFrontmatter(raw)
-          const title = content.split('\n').find(l => l.startsWith('# '))?.replace('# ', '') ?? null
-          return { name, title, content }
-        } catch {
-          throw new IncurError({
-            code: 'SOUL_NOT_FOUND',
-            message: `Soul "${name}" not found.`,
-            hint: 'Run `brainjar soul list` to see available souls.',
-          })
+          const soul = await api.get<ApiSoul>(`/api/v1/souls/${name}`)
+          return { name, title: soul.title, content: soul.content }
+        } catch (e) {
+          if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+            throw createError(ErrorCode.SOUL_NOT_FOUND, { params: [name] })
+          }
+          throw e
         }
       }
 
-      if (c.options.local) {
-        const local = await readLocalState()
-        if (!('soul' in local)) return { active: false, scope: 'local', note: 'No local soul override (cascades from global)' }
-        if (local.soul === null) return { active: false, scope: 'local', name: null, note: 'Explicitly unset at local scope' }
+      if (c.options.project) {
+        const state = await api.get<import('../api-types.js').ApiStateOverride>('/api/v1/state/override', {
+          project: basename(process.cwd()),
+        })
+        if (state.soul_slug === undefined) return { active: false, scope: 'project', note: 'No project soul override (cascades from workspace)' }
+        if (state.soul_slug === null) return { active: false, scope: 'project', name: null, note: 'Explicitly unset at project scope' }
         try {
-          const raw = await readFile(join(paths.souls, `${local.soul}.md`), 'utf-8')
-          const content = stripFrontmatter(raw)
-          const title = content.split('\n').find(l => l.startsWith('# '))?.replace('# ', '') ?? null
-          return { active: true, scope: 'local', name: local.soul, title, content }
+          const soul = await api.get<ApiSoul>(`/api/v1/souls/${state.soul_slug}`)
+          return { active: true, scope: 'project', name: state.soul_slug, title: soul.title, content: soul.content }
         } catch {
-          return { active: false, scope: 'local', name: local.soul, error: 'File not found' }
+          return { active: false, scope: 'project', name: state.soul_slug, error: 'Not found on server' }
         }
       }
 
-      const global = await readState()
-      const local = await readLocalState()
-      const env = readEnvState()
-      const effective = mergeState(global, local, env)
-      if (!effective.soul.value) return { active: false }
+      const state = await getEffectiveState(api)
+      if (!state.soul) return { active: false }
       try {
-        const raw = await readFile(join(paths.souls, `${effective.soul.value}.md`), 'utf-8')
-        const content = stripFrontmatter(raw)
-        const title = content.split('\n').find(l => l.startsWith('# '))?.replace('# ', '') ?? null
-        return { active: true, name: effective.soul.value, scope: effective.soul.scope, title, content }
+        const soul = await api.get<ApiSoul>(`/api/v1/souls/${state.soul}`)
+        return { active: true, name: state.soul, title: soul.title, content: soul.content }
       } catch {
-        return { active: false, name: effective.soul.value, error: 'File not found' }
+        return { active: false, name: state.soul, error: 'Not found on server' }
       }
     },
   })
   .command('use', {
     description: 'Activate a soul',
     args: z.object({
-      name: z.string().describe('Soul name (filename without .md in ~/.brainjar/souls/)'),
+      name: z.string().describe('Soul name'),
     }),
     options: z.object({
-      local: z.boolean().default(false).describe('Write to local .claude/CLAUDE.md instead of global'),
+      project: z.boolean().default(false).describe('Apply at project scope'),
     }),
     async run(c) {
-      await requireBrainjarDir()
       const name = normalizeSlug(c.args.name, 'soul name')
-      const source = join(paths.souls, `${name}.md`)
+      const api = await getApi()
+
+      // Validate it exists on server
       try {
-        await readFile(source, 'utf-8')
-      } catch {
-        throw new IncurError({
-          code: 'SOUL_NOT_FOUND',
-          message: `Soul "${name}" not found.`,
-          hint: 'Run `brainjar soul list` to see available souls.',
-        })
+        await api.get<ApiSoul>(`/api/v1/souls/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.SOUL_NOT_FOUND, { params: [name] })
+        }
+        throw e
       }
 
-      if (c.options.local) {
-        await withLocalStateLock(async () => {
-          const local = await readLocalState()
-          local.soul = name
-          await writeLocalState(local)
-          await sync({ local: true })
-        })
-      } else {
-        await withStateLock(async () => {
-          const state = await readState()
-          state.soul = name
-          await writeState(state)
-          await sync()
-        })
-      }
+      const mutationOpts = c.options.project
+        ? { project: basename(process.cwd()) }
+        : undefined
+      await putState(api, { soul_slug: name }, mutationOpts)
+
+      await sync({ api })
+      if (c.options.project) await sync({ api, project: true })
 
-      return { activated: name, local: c.options.local }
+      return { activated: name, project: c.options.project }
     },
   })
   .command('drop', {
     description: 'Deactivate the current soul',
     options: z.object({
-      local: z.boolean().default(false).describe('Remove local soul override or deactivate global soul'),
+      project: z.boolean().default(false).describe('Remove project soul override or deactivate workspace soul'),
     }),
     async run(c) {
-      await requireBrainjarDir()
-      if (c.options.local) {
-        await withLocalStateLock(async () => {
-          const local = await readLocalState()
-          delete local.soul
-          await writeLocalState(local)
-          await sync({ local: true })
-        })
-      } else {
-        await withStateLock(async () => {
-          const state = await readState()
-          if (!state.soul) {
-            throw new IncurError({
-              code: 'NO_ACTIVE_SOUL',
-              message: 'No active soul to deactivate.',
-            })
-          }
-          state.soul = null
-          await writeState(state)
-          await sync()
-        })
-      }
-      return { deactivated: true, local: c.options.local }
+      const api = await getApi()
+
+      const mutationOpts = c.options.project
+        ? { project: basename(process.cwd()) }
+        : undefined
+      await putState(api, { soul_slug: null }, mutationOpts)
+
+      await sync({ api })
+      if (c.options.project) await sync({ api, project: true })
+
+      return { deactivated: true, project: c.options.project }
     },
   })

package/src/commands/status.ts

@@ -1,27 +1,27 @@
 import { Cli, z } from 'incur'
-import { readState, readLocalState, readEnvState, mergeState, requireBrainjarDir } from '../state.js'
+import { basename } from 'node:path'
+import { getEffectiveState } from '../state.js'
 import { sync } from '../sync.js'
+import { getApi } from '../client.js'
+import type { ApiStateOverride } from '../api-types.js'
 
 export const status = Cli.create('status', {
   description: 'Show active brain configuration',
   options: z.object({
     sync: z.boolean().default(false).describe('Regenerate config file from active layers'),
-    global: z.boolean().default(false).describe('Show only global state'),
-    local: z.boolean().default(false).describe('Show only local overrides'),
+    workspace: z.boolean().default(false).describe('Show only workspace state'),
+    project: z.boolean().default(false).describe('Show only project overrides'),
     short: z.boolean().default(false).describe('One-line output: soul | persona'),
   }),
   async run(c) {
-    await requireBrainjarDir()
+    const api = await getApi()
 
     // --short: compact one-liner for scripts/statuslines
     if (c.options.short) {
-      const global = await readState()
-      const local = await readLocalState()
-      const env = readEnvState()
-      const effective = mergeState(global, local, env)
+      const state = await getEffectiveState(api)
       const parts = [
-        `soul: ${effective.soul.value ?? 'none'}`,
-        `persona: ${effective.persona.value ?? 'none'}`,
+        `soul: ${state.soul ?? 'none'}`,
+        `persona: ${state.persona ?? 'none'}`,
       ]
       return parts.join(' | ')
     }
@@ -29,64 +29,59 @@ export const status = Cli.create('status', {
     // Sync if requested
     let synced: Record<string, unknown> | undefined
     if (c.options.sync) {
-      const syncResult = await sync()
+      const syncResult = await sync({ api })
       synced = { written: syncResult.written, warnings: syncResult.warnings }
     }
 
-    // --global: show only global state (v0.1 behavior)
-    if (c.options.global) {
-      const state = await readState()
+    // --workspace: show only workspace-level override
+    if (c.options.workspace) {
+      const override = await api.get<ApiStateOverride>('/api/v1/state/override')
       const result: Record<string, unknown> = {
-        soul: state.soul ?? null,
-        persona: state.persona ?? null,
-        rules: state.rules,
+        soul: override.soul_slug ?? null,
+        persona: override.persona_slug ?? null,
+        rules: override.rule_slugs ?? [],
       }
       if (synced) result.synced = synced
       return result
     }
 
-    // --local: show only local overrides
-    if (c.options.local) {
-      const local = await readLocalState()
+    // --project: show only project-level overrides
+    if (c.options.project) {
+      const override = await api.get<ApiStateOverride>('/api/v1/state/override', {
+        project: basename(process.cwd()),
+      })
       const result: Record<string, unknown> = {}
-      if ('soul' in local) result.soul = local.soul
-      if ('persona' in local) result.persona = local.persona
-      if (local.rules) result.rules = local.rules
-      if (Object.keys(result).length === 0) result.note = 'No local overrides'
+      if (override.soul_slug !== undefined) result.soul = override.soul_slug
+      if (override.persona_slug !== undefined) result.persona = override.persona_slug
+      if (override.rules_to_add?.length) result.rules_to_add = override.rules_to_add
+      if (override.rules_to_remove?.length) result.rules_to_remove = override.rules_to_remove
+      if (Object.keys(result).length === 0) result.note = 'No project overrides'
       if (synced) result.synced = synced
       return result
     }
 
     // Default: effective state with scope annotations
-    const global = await readState()
-    const local = await readLocalState()
-    const env = readEnvState()
-    const effective = mergeState(global, local, env)
+    const state = await getEffectiveState(api)
 
     // Agents and explicit --format get full structured data
     if (c.agent || c.formatExplicit) {
       const result: Record<string, unknown> = {
-        soul: effective.soul,
-        persona: effective.persona,
-        rules: effective.rules,
+        soul: state.soul,
+        persona: state.persona,
+        rules: state.rules,
       }
       if (synced) result.synced = synced
       return result
     }
 
-    // Humans get a compact view with scope annotations
-    const fmtScope = (scope: string) => `(${scope})`
-
-    const rulesLabel = effective.rules.length
-      ? effective.rules
-          .filter(r => !r.scope.startsWith('-'))
-          .map(r => `${r.value} ${fmtScope(r.scope)}`)
-          .join(', ')
+    // Humans get a compact view
+    const rulesLabel = state.rules.length
+      ? state.rules.join(', ')
       : null
 
     const result: Record<string, unknown> = {
-      soul: effective.soul.value ? `${effective.soul.value} ${fmtScope(effective.soul.scope)}` : null,
-      persona: effective.persona.value ? `${effective.persona.value} ${fmtScope(effective.persona.scope)}` : null,
+      soul: state.soul ?? null,
+      persona: state.persona ?? null,
       rules: rulesLabel,
     }
     if (synced) result.synced = synced

package/src/commands/sync.ts

@@ -1,6 +1,5 @@
 import { Cli, z } from 'incur'
 import { sync as runSync } from '../sync.js'
-import { requireBrainjarDir } from '../state.js'
 
 export const sync = Cli.create('sync', {
   description: 'Regenerate config file from active layers',
@@ -8,7 +7,6 @@ export const sync = Cli.create('sync', {
     quiet: z.boolean().default(false).describe('Suppress output (for use in hooks)'),
   }),
   async run(c) {
-    await requireBrainjarDir()
     const result = await runSync()
     if (c.options.quiet) return
     return result