@brainjar/cli 0.1.0

package/src/commands/soul.ts

@@ -0,0 +1,207 @@
+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 { readState, writeState, withStateLock, readLocalState, writeLocalState, withLocalStateLock, readEnvState, mergeState, requireBrainjarDir, stripFrontmatter, normalizeSlug } from '../state.js'
+import { sync } from '../sync.js'
+
+export const soul = Cli.create('soul', {
+  description: 'Manage soul — personality and values for the agent',
+})
+  .command('create', {
+    description: 'Create a new soul',
+    args: z.object({
+      name: z.string().describe('Soul name (will be used as filename)'),
+    }),
+    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`)
+
+      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.',
+        })
+      } catch (e) {
+        if (e instanceof IncurError) throw e
+      }
+
+      const lines: string[] = []
+      lines.push(`# ${name}`)
+      lines.push('')
+      if (c.options.description) {
+        lines.push(c.options.description)
+        lines.push('')
+      }
+
+      const content = lines.join('\n')
+      await writeFile(dest, content)
+
+      if (c.agent || c.formatExplicit) {
+        return { created: dest, name, template: content }
+      }
+
+      return {
+        created: dest,
+        name,
+        template: `\n${content}`,
+        next: `Edit ${dest} to flesh out your soul, then run \`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 }
+    },
+  })
+  .command('show', {
+    description: 'Show a soul by name, or the active soul if no name given',
+    args: z.object({
+      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)'),
+      short: z.boolean().default(false).describe('Print only the active soul 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.soul.value ?? '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.',
+          })
+        }
+      }
+
+      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' }
+        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 }
+        } catch {
+          return { active: false, scope: 'local', name: local.soul, error: 'File not found' }
+        }
+      }
+
+      const global = await readState()
+      const local = await readLocalState()
+      const env = readEnvState()
+      const effective = mergeState(global, local, env)
+      if (!effective.soul.value) 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 }
+      } catch {
+        return { active: false, name: effective.soul.value, error: 'File not found' }
+      }
+    },
+  })
+  .command('use', {
+    description: 'Activate a soul',
+    args: z.object({
+      name: z.string().describe('Soul name (filename without .md in ~/.brainjar/souls/)'),
+    }),
+    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, 'soul name')
+      const source = join(paths.souls, `${name}.md`)
+      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.',
+        })
+      }
+
+      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()
+        })
+      }
+
+      return { activated: name, local: c.options.local }
+    },
+  })
+  .command('drop', {
+    description: 'Deactivate the current soul',
+    options: z.object({
+      local: z.boolean().default(false).describe('Remove local soul override or deactivate global 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 }
+    },
+  })

package/src/commands/status.ts

@@ -0,0 +1,131 @@
+import { Cli, z } from 'incur'
+import { readState, readLocalState, readEnvState, mergeState, loadIdentity, requireBrainjarDir } from '../state.js'
+import { sync } from '../sync.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'),
+    short: z.boolean().default(false).describe('One-line output: soul | persona | identity'),
+  }),
+  async run(c) {
+    await requireBrainjarDir()
+
+    // --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 slug = effective.identity.value
+        ? (await loadIdentity(effective.identity.value).catch(() => null))?.slug ?? effective.identity.value
+        : null
+      const parts = [
+        `soul: ${effective.soul.value ?? 'none'}`,
+        `persona: ${effective.persona.value ?? 'none'}`,
+        `identity: ${slug ?? 'none'}`,
+      ]
+      return parts.join(' | ')
+    }
+
+    // Sync if requested
+    let synced: Record<string, unknown> | undefined
+    if (c.options.sync) {
+      const syncResult = await sync()
+      synced = { written: syncResult.written, warnings: syncResult.warnings }
+    }
+
+    // --global: show only global state (v0.1 behavior)
+    if (c.options.global) {
+      const state = await readState()
+      let identityFull: Record<string, unknown> | null = null
+      if (state.identity) {
+        try {
+          const { content: _, ...id } = await loadIdentity(state.identity)
+          identityFull = id
+        } catch {
+          identityFull = { slug: state.identity, error: 'File not found' }
+        }
+      }
+      const result: Record<string, unknown> = {
+        soul: state.soul ?? null,
+        persona: state.persona ?? null,
+        rules: state.rules,
+        identity: identityFull,
+      }
+      if (synced) result.synced = synced
+      return result
+    }
+
+    // --local: show only local overrides
+    if (c.options.local) {
+      const local = await readLocalState()
+      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 ('identity' in local) result.identity = local.identity
+      if (Object.keys(result).length === 0) result.note = 'No local 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)
+
+    // Resolve identity details
+    let identityFull: Record<string, unknown> | null = null
+    if (effective.identity.value) {
+      try {
+        const { content: _, ...id } = await loadIdentity(effective.identity.value)
+        identityFull = { ...id, scope: effective.identity.scope }
+      } catch {
+        identityFull = { slug: effective.identity.value, scope: effective.identity.scope, error: 'File not found' }
+      }
+    }
+
+    // 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,
+        identity: identityFull,
+      }
+      if (synced) result.synced = synced
+      return result
+    }
+
+    // Humans get a compact view with scope annotations
+    const fmtScope = (scope: string) => `(${scope})`
+
+    const identityLabel = identityFull
+      ? identityFull.error
+        ? `${effective.identity.value} (not found)`
+        : identityFull.engine
+          ? `${identityFull.slug} ${fmtScope(effective.identity.scope)} (${identityFull.engine})`
+          : `${identityFull.slug} ${fmtScope(effective.identity.scope)}`
+      : null
+
+    const rulesLabel = effective.rules.length
+      ? effective.rules
+          .filter(r => !r.scope.startsWith('-'))
+          .map(r => `${r.value} ${fmtScope(r.scope)}`)
+          .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,
+      rules: rulesLabel,
+      identity: identityLabel,
+    }
+    if (synced) result.synced = synced
+    return result
+  },
+})

package/src/engines/bitwarden.ts

@@ -0,0 +1,105 @@
+import { $ } from 'bun'
+import { readFile } from 'node:fs/promises'
+import { paths } from '../paths.js'
+import type { CredentialEngine, EngineStatus } from './types.js'
+
+export async function loadSession(): Promise<string | null> {
+  // Env var takes precedence, then session file
+  if (process.env.BW_SESSION) return process.env.BW_SESSION
+  try {
+    const session = (await readFile(paths.session, 'utf-8')).trim()
+    return session || null
+  } catch {
+    return null
+  }
+}
+
+/** Thin shell wrapper — extracted so tests can replace it via spyOn. */
+export const bw = {
+  async whichBw(): Promise<void> {
+    await $`which bw`.quiet()
+  },
+
+  async status(session: string | null): Promise<any> {
+    return session
+      ? $`bw status`.env({ ...process.env, BW_SESSION: session }).json()
+      : $`bw status`.json()
+  },
+
+  async getItem(item: string, session: string): Promise<any> {
+    return $`bw get item ${item}`.env({ ...process.env, BW_SESSION: session }).json()
+  },
+
+  async lock(): Promise<void> {
+    await $`bw lock`.quiet()
+  },
+}
+
+export const bitwarden: CredentialEngine = {
+  name: 'bitwarden',
+
+  async status(): Promise<EngineStatus> {
+    try {
+      await bw.whichBw()
+    } catch {
+      return { state: 'not_installed', install: 'npm install -g @bitwarden/cli' }
+    }
+
+    try {
+      const session = await loadSession()
+      const result = await bw.status(session)
+
+      if (result.status === 'unauthenticated') {
+        return {
+          state: 'unauthenticated',
+          operator_action: `bw login ${result.userEmail ?? '<email>'}`,
+        }
+      }
+
+      if (result.status === 'unlocked' && session) {
+        return { state: 'unlocked', session }
+      }
+
+      return {
+        state: 'locked',
+        operator_action: 'Run `bw unlock` and then `brainjar identity unlock <session>`',
+      }
+    } catch {
+      return {
+        state: 'locked',
+        operator_action: 'Could not determine vault status. Run `bw unlock` and then `brainjar identity unlock <session>`',
+      }
+    }
+  },
+
+  async get(item: string, session: string) {
+    if (!item || item.length > 256 || /[\x00-\x1f]/.test(item)) {
+      return { error: `Invalid item name: "${item}"` }
+    }
+    try {
+      const result = await bw.getItem(item, session)
+
+      if (result.login?.password) {
+        return { value: result.login.password }
+      }
+      if (result.notes) {
+        return { value: result.notes }
+      }
+
+      return { error: `Item "${item}" found but has no password or notes.` }
+    } catch (e) {
+      const stderr = (e as any)?.stderr?.toString?.()?.trim?.()
+      const message = stderr || (e as Error).message || 'unknown error'
+      return { error: `Could not retrieve "${item}": ${message}` }
+    }
+  },
+
+  async lock() {
+    try {
+      await bw.lock()
+    } catch (e) {
+      const stderr = (e as any)?.stderr?.toString?.()?.trim?.()
+      throw new Error(`Failed to lock vault: ${stderr || (e as Error).message}`)
+    }
+  },
+}

package/src/engines/index.ts

@@ -0,0 +1,12 @@
+import type { CredentialEngine } from './types.js'
+import { bitwarden } from './bitwarden.js'
+
+const engines: Record<string, CredentialEngine> = {
+  bitwarden,
+}
+
+export function getEngine(name: string): CredentialEngine | null {
+  return engines[name] ?? null
+}
+
+export type { CredentialEngine }

package/src/engines/types.ts

@@ -0,0 +1,12 @@
+export type EngineStatus =
+  | { state: 'not_installed'; install: string }
+  | { state: 'unauthenticated'; operator_action: string }
+  | { state: 'locked'; operator_action: string }
+  | { state: 'unlocked'; session: string }
+
+export interface CredentialEngine {
+  name: string
+  status(): Promise<EngineStatus>
+  get(item: string, session: string): Promise<{ value: string } | { error: string }>
+  lock(): Promise<void>
+}

package/src/paths.ts

@@ -0,0 +1,48 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Resolved lazily so tests can override HOME env var. */
+export function getHome() {
+  return process.env.BRAINJAR_TEST_HOME ?? homedir()
+}
+
+export function getBrainjarDir() {
+  return process.env.BRAINJAR_HOME ?? join(getHome(), '.brainjar')
+}
+
+export type Backend = 'claude' | 'codex'
+
+const BACKEND_CONFIG_FILES: Record<Backend, string> = {
+  claude: 'CLAUDE.md',
+  codex: 'AGENTS.md',
+}
+
+export function getBackendConfig(backend: Backend, options?: { local?: boolean }) {
+  const configFileName = BACKEND_CONFIG_FILES[backend]
+  const dir = options?.local
+    ? join(process.cwd(), backend === 'claude' ? '.claude' : '.codex')
+    : join(getHome(), backend === 'claude' ? '.claude' : '.codex')
+  return {
+    dir,
+    configFile: join(dir, configFileName),
+    configFileName,
+    backupFile: join(dir, `${configFileName}.pre-brainjar`),
+  }
+}
+
+/** Local brainjar dir for per-repo state. */
+export function getLocalDir() {
+  return process.env.BRAINJAR_LOCAL_DIR ?? join(process.cwd(), '.brainjar')
+}
+
+export const paths = {
+  get root() { return getBrainjarDir() },
+  get souls() { return join(getBrainjarDir(), 'souls') },
+  get personas() { return join(getBrainjarDir(), 'personas') },
+  get rules() { return join(getBrainjarDir(), 'rules') },
+  get brains() { return join(getBrainjarDir(), 'brains') },
+  get identities() { return join(getBrainjarDir(), 'identities') },
+  get session() { return join(getBrainjarDir(), '.session') },
+  get state() { return join(getBrainjarDir(), 'state.yaml') },
+  get localState() { return join(getLocalDir(), 'state.yaml') },
+}

package/src/seeds/personas/engineer.md

@@ -0,0 +1,26 @@
+---
+rules:
+  - default
+  - git-discipline
+---
+
+# Engineer
+
+Build what's asked. Build it well.
+
+## Direct mode
+- Clarify ambiguous requirements before writing code. One targeted question beats three assumptions.
+- Show your plan briefly, then execute. Don't ask for permission on obvious steps.
+
+## Subagent mode
+- You will be given a specific task by the orchestrating agent. Deliver production-quality code.
+- Return the implementation with a brief note on any decisions you made.
+- If the task spec is incomplete, flag what's missing — don't fill in gaps silently.
+
+## Always
+- Read existing code before writing new code. Match the project's patterns and conventions.
+- Prefer the simplest solution that fully meets the requirement.
+- Handle errors. Happy path only is not done.
+- Run tests before declaring a task complete.
+- One logical change at a time. Don't mix unrelated fixes.
+- Respect the codebase. It's the user's house — don't rearrange the furniture.

package/src/seeds/personas/planner.md

@@ -0,0 +1,24 @@
+---
+rules:
+  - default
+---
+
+# Planner
+
+Think first, build second.
+
+## Direct mode
+- Start with "what problem are we solving?" Clarify intent and constraints before proposing solutions.
+- Present options with tradeoffs, then recommend one. Don't just list — decide.
+
+## Subagent mode
+- You will be given a design or analysis task. Return structured, actionable output — not vague suggestions.
+- Include file paths, interfaces, and concrete steps. A plan someone else can execute.
+- Surface risks and dependencies explicitly.
+
+## Always
+- Break large problems into phases. Name what's in each phase and what's deferred.
+- Consider how pieces fit together. Local changes have system-wide effects.
+- Challenge assumptions. "Do we actually need this?" is a valid design question.
+- Keep the long game in mind, but don't gold-plate. Design for the next 3 changes, not the next 30.
+- Write it down. A plan in prose beats a plan in memory.

package/src/seeds/personas/reviewer.md

@@ -0,0 +1,27 @@
+---
+rules:
+  - default
+  - security
+---
+
+# Reviewer
+
+Find problems before they ship.
+
+## Direct mode
+- Review code the user points you to. Ask for context if the intent isn't clear.
+- Prioritize: correctness first, then security, then maintainability. Style last.
+
+## Subagent mode
+- You will be given specific files or changes to review. Read every file mentioned. Return a structured verdict:
+  - **Pass**: implementation is correct, secure, and meets the stated goal.
+  - **Issues found**: list each issue with file path, line number, severity (blocker/warning), and suggested fix.
+- Do not make changes yourself — report findings.
+
+## Always
+- Be skeptical by default. Assume there's a bug until proven otherwise.
+- Read error paths as carefully as happy paths. Most bugs live in error handling.
+- Look for edge cases, null/undefined, and off-by-one errors.
+- Flag security issues immediately: injection, auth gaps, leaked secrets.
+- Be honest, not harsh. Point out issues clearly without being condescending.
+- Don't nitpick style when there are real problems to fix.

package/src/seeds/rules/default/boundaries.md

@@ -0,0 +1,25 @@
+# Boundaries
+
+This rule prevents scope creep and unwanted changes.
+
+## Scope Control
+
+- Only modify files directly related to the current task.
+- Don't refactor code that isn't broken and isn't part of the task.
+- Don't "improve" code you happen to read while working on something else.
+- One task at a time. Finish the current task before suggesting new ones.
+
+## Ask Before
+
+- Adding or removing dependencies.
+- Changing configuration files (CI, linters, formatters, build configs).
+- Modifying git workflow (hooks, branch strategies).
+- Changing project structure or moving files.
+- Altering APIs or interfaces used by other parts of the codebase.
+
+## File Discipline
+
+- Don't create files that weren't requested (docs, configs, helpers "for later").
+- Don't delete files without confirming they're unused.
+- Don't rename files or variables for style preferences.
+- Keep changes minimal and reviewable.

package/src/seeds/rules/default/context-recovery.md

@@ -0,0 +1,17 @@
+# Context Recovery
+
+This rule governs behavior after context compaction, session resume, or any situation where prior conversation may be lost.
+
+## After Context Loss
+
+1. **Re-read the task plan.** Check todo lists, plan files, and any task-tracking artifacts.
+2. **Check recent changes.** Run `git diff` and `git log --oneline -10` to see what's been done.
+3. **Re-read active files.** Open files you're currently modifying — don't rely on memory of their contents.
+4. **Summarize state.** Briefly state what's done, what's in progress, and what's next before continuing work.
+
+## Rules
+
+- Never continue from memory alone after compaction. Always re-ground in artifacts.
+- If you can't determine the current state, ask the user rather than guessing.
+- Treat every post-compaction turn as if you're a new engineer picking up someone else's work.
+- The task isn't "remember what we were doing" — it's "figure out what needs doing next."

package/src/seeds/rules/default/task-completion.md

@@ -0,0 +1,31 @@
+# Task Completion
+
+This rule defines what "done" means. Premature completion is worse than slow completion.
+
+## Completion Criteria
+
+A task is done only when ALL of the following are true:
+
+1. **No stubs.** No TODOs, no placeholders, no "implement this later" comments.
+2. **Code works.** It compiles/parses without errors. If there are tests, they pass.
+3. **Requirement met.** Re-read the original request. Does the implementation fully satisfy it?
+4. **Self-review passed.** Read through your changes as if reviewing someone else's PR.
+
+## Before Declaring Done
+
+- Re-read the user's original request word by word.
+- Diff your changes against what was asked for. Look for gaps.
+- If the task involved multiple steps, verify each one individually.
+- Run any relevant verification commands (build, test, lint).
+
+## When You Can't Complete
+
+- Say so explicitly. "I can't complete this because X."
+- Don't deliver partial work dressed up as complete work.
+- Suggest concrete next steps the user can take.
+
+## Anti-Patterns
+
+- Saying "done" then listing caveats that mean it's not actually done.
+- Implementing 90% and leaving the hard part as a TODO.
+- Skipping verification because "it should work."