@brainjar/cli 0.1.0

package/src/commands/persona.ts

@@ -0,0 +1,259 @@
+import { Cli, z, Errors } from 'incur'
+
+const { IncurError } = Errors
+import { readdir, readFile, writeFile, access } from 'node:fs/promises'
+import { join, basename } from 'node:path'
+import { paths } from '../paths.js'
+import { type State, readState, writeState, withStateLock, readLocalState, writeLocalState, withLocalStateLock, readEnvState, mergeState, requireBrainjarDir, parseLayerFrontmatter, stripFrontmatter, normalizeSlug, listAvailableRules } from '../state.js'
+import { sync } from '../sync.js'
+
+export const persona = Cli.create('persona', {
+  description: 'Manage personas — role behavior and workflow for the agent',
+})
+  .command('create', {
+    description: 'Create a new persona',
+    args: z.object({
+      name: z.string().describe('Persona name (will be used as filename)'),
+    }),
+    options: z.object({
+      description: z.string().optional().describe('One-line description of the persona'),
+      rules: z.array(z.string()).optional().describe('Rules to bundle with this persona'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'persona name')
+      const dest = join(paths.personas, `${name}.md`)
+
+      try {
+        await access(dest)
+        throw new IncurError({
+          code: 'PERSONA_EXISTS',
+          message: `Persona "${name}" already exists.`,
+          hint: 'Choose a different name or edit the existing file.',
+        })
+      } catch (e) {
+        if (e instanceof IncurError) throw e
+      }
+
+      const rulesList = c.options.rules ?? []
+
+      // Validate rules exist
+      const availableRules = await listAvailableRules()
+      const invalid = rulesList.filter(r => !availableRules.includes(r))
+      if (invalid.length > 0) {
+        throw new IncurError({
+          code: 'RULES_NOT_FOUND',
+          message: `Rules not found: ${invalid.join(', ')}`,
+          hint: `Available rules: ${availableRules.join(', ')}`,
+        })
+      }
+
+      const lines: string[] = []
+
+      // Frontmatter — always write it (rules default to [default])
+      const effectiveRules = rulesList.length > 0 ? rulesList : ['default']
+      lines.push('---')
+      lines.push('rules:')
+      for (const rule of effectiveRules) {
+        lines.push(`  - ${rule}`)
+      }
+      lines.push('---')
+      lines.push('')
+
+      lines.push(`# ${name}`)
+      lines.push('')
+      if (c.options.description) {
+        lines.push(c.options.description)
+      }
+      lines.push('')
+      lines.push('## Direct mode')
+      lines.push('- ')
+      lines.push('')
+      lines.push('## Subagent mode')
+      lines.push('- ')
+      lines.push('')
+      lines.push('## Always')
+      lines.push('- ')
+      lines.push('')
+
+      const content = lines.join('\n')
+      await writeFile(dest, content)
+
+      if (c.agent || c.formatExplicit) {
+        return {
+          created: dest,
+          name,
+          rules: effectiveRules,
+          template: content,
+        }
+      }
+
+      return {
+        created: dest,
+        name,
+        rules: effectiveRules,
+        template: `\n${content}`,
+        next: `Edit ${dest} to fill in your persona, then run \`brainjar persona use ${name}\` to activate.`,
+      }
+    },
+  })
+  .command('list', {
+    description: 'List available personas',
+    async run() {
+      await requireBrainjarDir()
+      const entries = await readdir(paths.personas).catch(() => [])
+      const personas = entries.filter(f => f.endsWith('.md')).map(f => basename(f, '.md'))
+      return { personas }
+    },
+  })
+  .command('show', {
+    description: 'Show a persona by name, or the active persona if no name given',
+    args: z.object({
+      name: z.string().optional().describe('Persona name to show (defaults to active persona)'),
+    }),
+    options: z.object({
+      local: z.boolean().default(false).describe('Show local persona override (if any)'),
+      short: z.boolean().default(false).describe('Print only the active persona name'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+
+      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.persona.value ?? 'none'
+      }
+
+      // If a specific name was given, show that persona directly
+      if (c.args.name) {
+        const name = normalizeSlug(c.args.name, 'persona name')
+        try {
+          const raw = await readFile(join(paths.personas, `${name}.md`), 'utf-8')
+          const frontmatter = parseLayerFrontmatter(raw)
+          const content = stripFrontmatter(raw)
+          const title = content.split('\n').find(l => l.startsWith('# '))?.replace('# ', '') ?? null
+          return { name, title, content, ...frontmatter }
+        } catch {
+          throw new IncurError({
+            code: 'PERSONA_NOT_FOUND',
+            message: `Persona "${name}" not found.`,
+            hint: 'Run `brainjar persona list` to see available personas.',
+          })
+        }
+      }
+
+      if (c.options.local) {
+        const local = await readLocalState()
+        if (!('persona' in local)) return { active: false, scope: 'local', note: 'No local persona override (cascades from global)' }
+        if (local.persona === null) return { active: false, scope: 'local', name: null, note: 'Explicitly unset at local scope' }
+        try {
+          const raw = await readFile(join(paths.personas, `${local.persona}.md`), 'utf-8')
+          const frontmatter = parseLayerFrontmatter(raw)
+          const content = stripFrontmatter(raw)
+          const title = content.split('\n').find(l => l.startsWith('# '))?.replace('# ', '') ?? null
+          return { active: true, scope: 'local', name: local.persona, title, content, ...frontmatter }
+        } catch {
+          return { active: false, scope: 'local', name: local.persona, error: 'File not found' }
+        }
+      }
+
+      const global = await readState()
+      const local = await readLocalState()
+      const env = readEnvState()
+      const effective = mergeState(global, local, env)
+      if (!effective.persona.value) return { active: false }
+      try {
+        const raw = await readFile(join(paths.personas, `${effective.persona.value}.md`), 'utf-8')
+        const frontmatter = parseLayerFrontmatter(raw)
+        const content = stripFrontmatter(raw)
+        const title = content.split('\n').find(l => l.startsWith('# '))?.replace('# ', '') ?? null
+        return { active: true, name: effective.persona.value, scope: effective.persona.scope, title, content, ...frontmatter }
+      } catch {
+        return { active: false, name: effective.persona.value, error: 'File not found' }
+      }
+    },
+  })
+  .command('use', {
+    description: 'Activate a persona',
+    args: z.object({
+      name: z.string().describe('Persona name (filename without .md in ~/.brainjar/personas/)'),
+    }),
+    options: z.object({
+      local: z.boolean().default(false).describe('Write to local .claude/CLAUDE.md instead of global'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'persona name')
+      const source = join(paths.personas, `${name}.md`)
+      let raw: string
+      try {
+        raw = await readFile(source, 'utf-8')
+      } catch {
+        throw new IncurError({
+          code: 'PERSONA_NOT_FOUND',
+          message: `Persona "${name}" not found.`,
+          hint: 'Run `brainjar persona list` to see available personas.',
+        })
+      }
+
+      const frontmatter = parseLayerFrontmatter(raw)
+
+      if (c.options.local) {
+        await withLocalStateLock(async () => {
+          const local = await readLocalState()
+          local.persona = name
+          if (frontmatter.rules.length > 0) {
+            local.rules = { ...local.rules, add: frontmatter.rules }
+          }
+          await writeLocalState(local)
+          await sync({ local: true })
+        })
+      } else {
+        await withStateLock(async () => {
+          const state = await readState()
+          state.persona = name
+          if (frontmatter.rules.length > 0) state.rules = frontmatter.rules
+          await writeState(state)
+          await sync()
+        })
+      }
+
+      const result: Record<string, unknown> = { activated: name, local: c.options.local }
+      if (frontmatter.rules.length > 0) result.rules = frontmatter.rules
+      return result
+    },
+  })
+  .command('drop', {
+    description: 'Deactivate the current persona',
+    options: z.object({
+      local: z.boolean().default(false).describe('Remove local persona override or deactivate global persona'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      if (c.options.local) {
+        await withLocalStateLock(async () => {
+          const local = await readLocalState()
+          delete local.persona
+          await writeLocalState(local)
+          await sync({ local: true })
+        })
+      } else {
+        await withStateLock(async () => {
+          const state = await readState()
+          if (!state.persona) {
+            throw new IncurError({
+              code: 'NO_ACTIVE_PERSONA',
+              message: 'No active persona to deactivate.',
+            })
+          }
+          state.persona = null
+          await writeState(state)
+          await sync()
+        })
+      }
+      return { deactivated: true, local: c.options.local }
+    },
+  })

package/src/commands/reset.ts

@@ -0,0 +1,46 @@
+import { Cli, z } from 'incur'
+import { readFile, rm, copyFile, writeFile } from 'node:fs/promises'
+import { getBackendConfig, type Backend } from '../paths.js'
+import { MARKER_START, MARKER_END } from '../sync.js'
+
+export const reset = Cli.create('reset', {
+  description: 'Remove brainjar-managed config from agent backend and restore backup',
+  options: z.object({
+    backend: z.enum(['claude', 'codex']).default('claude').describe('Agent backend to reset'),
+  }),
+  async run(c) {
+    const backend = c.options.backend as Backend
+    const config = getBackendConfig(backend)
+    let removed = false
+    let restored = false
+
+    try {
+      const content = await readFile(config.configFile, 'utf-8')
+      const startIdx = content.indexOf(MARKER_START)
+      const endIdx = content.indexOf(MARKER_END)
+
+      if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Remove the brainjar section, preserve user content
+        const before = content.slice(0, startIdx).trimEnd()
+        const after = content.slice(endIdx + MARKER_END.length).trimStart()
+        const remaining = [before, after].filter(Boolean).join('\n\n')
+
+        if (remaining.trim()) {
+          await writeFile(config.configFile, remaining + '\n')
+        } else {
+          // Nothing left — try to restore backup or remove file
+          try {
+            await copyFile(config.backupFile, config.configFile)
+            await rm(config.backupFile, { force: true })
+            restored = true
+          } catch {
+            await rm(config.configFile, { force: true })
+          }
+        }
+        removed = true
+      }
+    } catch {}
+
+    return { backend, removed, restored }
+  },
+})

package/src/commands/rules.ts

@@ -0,0 +1,269 @@
+import { Cli, z, Errors } from 'incur'
+
+const { IncurError } = Errors
+import { access, readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { paths } from '../paths.js'
+import { readState, writeState, withStateLock, readLocalState, writeLocalState, withLocalStateLock, readEnvState, mergeState, requireBrainjarDir, normalizeSlug, listAvailableRules } from '../state.js'
+import { sync } from '../sync.js'
+
+export const rules = Cli.create('rules', {
+  description: 'Manage rules — behavioral constraints for the agent',
+})
+  .command('create', {
+    description: 'Create a new rule',
+    args: z.object({
+      name: z.string().describe('Rule name (will be used as filename)'),
+    }),
+    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 (directory of .md files)'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'rule name')
+
+      if (c.options.pack) {
+        const dirPath = join(paths.rules, name)
+        try {
+          await access(dirPath)
+          throw new IncurError({
+            code: 'RULE_EXISTS',
+            message: `Rule "${name}" already exists.`,
+            hint: 'Choose a different name or edit the existing files.',
+          })
+        } catch (e) {
+          if (e instanceof IncurError) throw e
+        }
+
+        await mkdir(dirPath, { recursive: true })
+
+        const scaffold = [
+          `# ${name}`,
+          '',
+          c.options.description ?? 'Describe what this rule enforces and why.',
+          '',
+          '## Constraints',
+          '- ',
+          '',
+        ].join('\n')
+
+        await writeFile(join(dirPath, `${name}.md`), scaffold)
+
+        if (c.agent || c.formatExplicit) {
+          return { created: dirPath, name, pack: true, template: scaffold }
+        }
+
+        return {
+          created: dirPath,
+          name,
+          pack: true,
+          template: `\n${scaffold}`,
+          next: `Edit ${join(dirPath, `${name}.md`)} to define your rule, then run \`brainjar rules add ${name}\` to activate.`,
+        }
+      }
+
+      const dest = join(paths.rules, `${name}.md`)
+      try {
+        await access(dest)
+        throw new IncurError({
+          code: 'RULE_EXISTS',
+          message: `Rule "${name}" already exists.`,
+          hint: 'Choose a different name or edit the existing file.',
+        })
+      } catch (e) {
+        if (e instanceof IncurError) throw e
+      }
+
+      const scaffold = [
+        `# ${name}`,
+        '',
+        c.options.description ?? 'Describe what this rule enforces and why.',
+        '',
+        '## Constraints',
+        '- ',
+        '',
+      ].join('\n')
+
+      await writeFile(dest, scaffold)
+
+      if (c.agent || c.formatExplicit) {
+        return { created: dest, name, template: scaffold }
+      }
+
+      return {
+        created: dest,
+        name,
+        template: `\n${scaffold}`,
+        next: `Edit ${dest} to define your rule, then run \`brainjar rules add ${name}\` to activate.`,
+      }
+    },
+  })
+  .command('list', {
+    description: 'List available and active rules',
+    options: z.object({
+      local: z.boolean().default(false).describe('Show local rules delta only'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+
+      if (c.options.local) {
+        const local = await readLocalState()
+        const available = await listAvailableRules()
+        return {
+          add: local.rules?.add ?? [],
+          remove: local.rules?.remove ?? [],
+          available,
+          scope: 'local',
+        }
+      }
+
+      const [global, local, available] = await Promise.all([readState(), readLocalState(), listAvailableRules()])
+      const env = readEnvState()
+      const effective = mergeState(global, local, env)
+      const active = effective.rules.filter(r => !r.scope.startsWith('-')).map(r => r.value)
+      return { active, available, rules: effective.rules }
+    },
+  })
+  .command('show', {
+    description: 'Show the content of a rule by name',
+    args: z.object({
+      name: z.string().describe('Rule name to show'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'rule name')
+      const dirPath = join(paths.rules, name)
+      const filePath = join(paths.rules, `${name}.md`)
+
+      // Try directory of .md files first
+      try {
+        const s = await stat(dirPath)
+        if (s.isDirectory()) {
+          const files = await readdir(dirPath)
+          const mdFiles = files.filter(f => f.endsWith('.md')).sort()
+          const sections: string[] = []
+          for (const file of mdFiles) {
+            const content = await readFile(join(dirPath, file), 'utf-8')
+            sections.push(content.trim())
+          }
+          return { name, content: sections.join('\n\n') }
+        }
+      } catch {}
+
+      // Try single .md file
+      try {
+        const content = await readFile(filePath, 'utf-8')
+        return { name, content: content.trim() }
+      } catch {}
+
+      throw new IncurError({
+        code: 'RULE_NOT_FOUND',
+        message: `Rule "${name}" not found.`,
+        hint: 'Run `brainjar rules list` to see available rules.',
+      })
+    },
+  })
+  .command('add', {
+    description: 'Activate a rule or rule pack',
+    args: z.object({
+      name: z.string().describe('Rule name or directory name in ~/.brainjar/rules/'),
+    }),
+    options: z.object({
+      local: z.boolean().default(false).describe('Add rule as a local override (delta, not snapshot)'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'rule name')
+      // Verify it exists as a directory or .md file
+      const dirPath = join(paths.rules, name)
+      const filePath = join(paths.rules, `${name}.md`)
+      let found = false
+
+      try {
+        const s = await stat(dirPath)
+        if (s.isDirectory()) found = true
+      } catch {}
+
+      if (!found) {
+        try {
+          await readFile(filePath, 'utf-8')
+          found = true
+        } catch {}
+      }
+
+      if (!found) {
+        throw new IncurError({
+          code: 'RULE_NOT_FOUND',
+          message: `Rule "${name}" not found in ${paths.rules}`,
+          hint: 'Place .md files or directories in ~/.brainjar/rules/',
+        })
+      }
+
+      if (c.options.local) {
+        await withLocalStateLock(async () => {
+          const local = await readLocalState()
+          const adds = local.rules?.add ?? []
+          if (!adds.includes(name)) adds.push(name)
+          // Also remove from local removes if present
+          const removes = (local.rules?.remove ?? []).filter(r => r !== name)
+          local.rules = { add: adds, ...(removes.length ? { remove: removes } : {}) }
+          await writeLocalState(local)
+          await sync({ local: true })
+        })
+      } else {
+        await withStateLock(async () => {
+          const state = await readState()
+          if (!state.rules.includes(name)) {
+            state.rules.push(name)
+            await writeState(state)
+          }
+          await sync()
+        })
+      }
+
+      return { activated: name, local: c.options.local }
+    },
+  })
+  .command('remove', {
+    description: 'Deactivate a rule',
+    args: z.object({
+      name: z.string().describe('Rule name to remove'),
+    }),
+    options: z.object({
+      local: z.boolean().default(false).describe('Remove rule as a local override (delta, not snapshot)'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'rule name')
+
+      if (c.options.local) {
+        await withLocalStateLock(async () => {
+          const local = await readLocalState()
+          const removes = local.rules?.remove ?? []
+          if (!removes.includes(name)) removes.push(name)
+          // Also remove from local adds if present
+          const adds = (local.rules?.add ?? []).filter(r => r !== name)
+          local.rules = { ...(adds.length ? { add: adds } : {}), remove: removes }
+          await writeLocalState(local)
+          await sync({ local: true })
+        })
+      } else {
+        await withStateLock(async () => {
+          const state = await readState()
+          if (!state.rules.includes(name)) {
+            throw new IncurError({
+              code: 'RULE_NOT_ACTIVE',
+              message: `Rule "${name}" is not active.`,
+              hint: 'Run `brainjar rules list` to see active rules.',
+            })
+          }
+          state.rules = state.rules.filter(r => r !== name)
+          await writeState(state)
+          await sync()
+        })
+      }
+
+      return { removed: name, local: c.options.local }
+    },
+  })

package/src/commands/shell.ts

@@ -0,0 +1,119 @@
+import { Cli, z, Errors } from 'incur'
+
+const { IncurError } = Errors
+import { spawn } from 'node:child_process'
+import { access } from 'node:fs/promises'
+import { requireBrainjarDir } from '../state.js'
+import { sync } from '../sync.js'
+import { getLocalDir } from '../paths.js'
+import { readBrain } from './brain.js'
+
+export const shell = Cli.create('shell', {
+  description: 'Spawn a subshell with BRAINJAR_* env vars set',
+  options: z.object({
+    brain: z.string().optional().describe('Brain name — sets soul, persona, and rules from brain file'),
+    soul: z.string().optional().describe('Soul override for this session'),
+    persona: z.string().optional().describe('Persona override for this session'),
+    identity: z.string().optional().describe('Identity 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.identity
+      || c.options['rules-add'] || c.options['rules-remove']
+
+    if (c.options.brain && individualFlags) {
+      throw new IncurError({
+        code: 'MUTUALLY_EXCLUSIVE',
+        message: '--brain is mutually exclusive with --soul, --persona, --identity, --rules-add, --rules-remove.',
+        hint: 'Use --brain alone or individual flags, not both.',
+      })
+    }
+
+    const envOverrides: Record<string, 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(',')
+      }
+    } else {
+      if (c.options.soul) envOverrides.BRAINJAR_SOUL = c.options.soul
+      if (c.options.persona) envOverrides.BRAINJAR_PERSONA = c.options.persona
+      if (c.options.identity) envOverrides.BRAINJAR_IDENTITY = c.options.identity
+      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 (Object.keys(envOverrides).length === 0) {
+      throw new IncurError({
+        code: 'NO_OVERRIDES',
+        message: 'No overrides specified.',
+        hint: 'Use --brain, --soul, --persona, --identity, --rules-add, or --rules-remove.',
+      })
+    }
+
+    // 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 })
+
+    // 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_IDENTITY) labels.push(`identity: ${envOverrides.BRAINJAR_IDENTITY}`)
+    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
+    const userShell = process.env.SHELL || '/bin/sh'
+    const child = spawn(userShell, [], {
+      stdio: 'inherit',
+      env: { ...process.env, ...envOverrides },
+    })
+
+    return new Promise((resolve, reject) => {
+      child.on('exit', async (code) => {
+        // Re-sync without env overrides to restore config
+        let syncWarning: string | undefined
+        try {
+          await sync()
+          if (hasLocal) await sync({ local: true })
+        } catch (err) {
+          syncWarning = `Re-sync on exit failed: ${(err as Error).message}`
+        }
+
+        const result = {
+          shell: userShell,
+          env: envOverrides,
+          exitCode: code ?? 0,
+          ...(syncWarning ? { warning: syncWarning } : {}),
+        }
+
+        if (c.agent || c.formatExplicit) {
+          resolve(result)
+        } else {
+          if (syncWarning) process.stderr.write(`[brainjar] ${syncWarning}\n`)
+          resolve(undefined)
+        }
+      })
+      child.on('error', (err) => {
+        reject(new IncurError({
+          code: 'SHELL_ERROR',
+          message: `Failed to spawn shell: ${err.message}`,
+        }))
+      })
+    })
+  },
+})