@brainjar/cli 0.1.0 → 0.2.1

package/README.md

@@ -1,7 +1,7 @@
 # brainjar
 
 [![CI](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/brainjar)](https://www.npmjs.com/package/brainjar)
+[![npm](https://img.shields.io/npm/v/@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.
@@ -12,7 +12,7 @@ brainjar manages AI agent behavior through composable layers. Instead of one mon
 
 ```bash
 # Install
-bun install -g brainjar
+bun install -g @brainjar/cli
 
 # Initialize with starter content
 brainjar init --default
@@ -247,11 +247,53 @@ brainjar status
 # rules    default (global), no-delete (+local)
 ```
 
+## Pack
+
+Packs are self-contained, shareable bundles of a brain and all its layers — soul, persona, and rules. Export a brain as a pack directory, hand it to a teammate, and they import it in one command.
+
+A pack mirrors the `~/.brainjar/` structure with a `pack.yaml` manifest at the root. No tarballs, no magic — just files you can inspect with `ls` and `cat`.
+
+```bash
+# Export a brain as a pack
+brainjar pack export review                        # creates ./review/
+brainjar pack export review --out /tmp             # creates /tmp/review/
+brainjar pack export review --name my-review       # override pack name
+brainjar pack export review --version 1.0.0        # set version (default: 0.1.0)
+brainjar pack export review --author frank         # set author field
+
+# Import a pack
+brainjar pack import ./review                      # import into ~/.brainjar/
+brainjar pack import ./review --force              # overwrite conflicts
+brainjar pack import ./review --merge              # rename conflicts as <name>-from-<packname>
+brainjar pack import ./review --activate           # activate the brain after import
+```
+
+On conflict (a file already exists with different content), import fails by default and lists the conflicts. Use `--force` to overwrite or `--merge` to keep both versions. Identical files are silently skipped.
+
+## Hooks
+
+brainjar integrates with Claude Code's hook system for automatic context injection. When hooks are installed, brainjar syncs your config on every session start — no manual `brainjar sync` needed.
+
+```bash
+# Install hooks (writes to ~/.claude/settings.json)
+brainjar hooks install
+
+# Install for this project only
+brainjar hooks install --local
+
+# Check hook status
+brainjar hooks status
+
+# Remove hooks
+brainjar hooks remove
+```
+
 ## Commands
 
 ```
 brainjar init [--default] [--obsidian] [--backend claude|codex]
 brainjar status [--sync] [--global|--local] [--short]
+brainjar sync [--quiet]
 brainjar compose <brain> [--task <text>]
 brainjar compose --persona <name> [--task <text>]
 
@@ -261,6 +303,8 @@ brainjar persona create|list|show|use|drop
 brainjar rules create|list|show|add|remove
 
 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 reset [--backend claude|codex]
 ```

package/package.json

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

package/src/brain.ts

@@ -0,0 +1,69 @@
+import { Errors } from 'incur'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import { paths } from './paths.js'
+import { normalizeSlug } from './state.js'
+
+const { IncurError } = Errors
+
+/** Brain YAML schema: soul + persona + rules */
+export interface BrainConfig {
+  soul: string
+  persona: string
+  rules: string[]
+}
+
+/** Read and validate a brain YAML file. */
+export async function readBrain(name: string): Promise<BrainConfig> {
+  const slug = normalizeSlug(name, 'brain name')
+  const file = join(paths.brains, `${slug}.yaml`)
+
+  let raw: string
+  try {
+    raw = await readFile(file, 'utf-8')
+  } catch {
+    throw new IncurError({
+      code: 'BRAIN_NOT_FOUND',
+      message: `Brain "${slug}" not found.`,
+      hint: 'Run `brainjar brain list` to see available brains.',
+    })
+  }
+
+  let parsed: unknown
+  try {
+    parsed = parseYaml(raw)
+  } catch (e) {
+    throw new IncurError({
+      code: 'BRAIN_CORRUPT',
+      message: `Brain "${slug}" has invalid YAML: ${(e as Error).message}`,
+    })
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new IncurError({
+      code: 'BRAIN_CORRUPT',
+      message: `Brain "${slug}" is empty or invalid.`,
+    })
+  }
+
+  const p = parsed as Record<string, unknown>
+
+  if (typeof p.soul !== 'string' || !p.soul) {
+    throw new IncurError({
+      code: 'BRAIN_INVALID',
+      message: `Brain "${slug}" is missing required field "soul".`,
+    })
+  }
+
+  if (typeof p.persona !== 'string' || !p.persona) {
+    throw new IncurError({
+      code: 'BRAIN_INVALID',
+      message: `Brain "${slug}" is missing required field "persona".`,
+    })
+  }
+
+  const rules = Array.isArray(p.rules) ? p.rules.map(String) : []
+
+  return { soul: p.soul, persona: p.persona, rules }
+}

package/src/cli.ts

@@ -11,6 +11,9 @@ import { status } from './commands/status.js'
 import { reset } from './commands/reset.js'
 import { shell } from './commands/shell.js'
 import { compose } from './commands/compose.js'
+import { sync } from './commands/sync.js'
+import { hooks } from './commands/hooks.js'
+import { pack } from './commands/pack.js'
 
 Cli.create('brainjar', {
   description: 'Shape how your AI thinks — identity, soul, persona, rules',
@@ -27,4 +30,7 @@ Cli.create('brainjar', {
   .command(reset)
   .command(shell)
   .command(compose)
+  .command(sync)
+  .command(hooks)
+  .command(pack)
   .serve()

package/src/commands/brain.ts

@@ -3,7 +3,7 @@ import { Cli, z, Errors } from 'incur'
 const { IncurError } = Errors
 import { readdir, readFile, writeFile, access, rm } from 'node:fs/promises'
 import { join, basename } from 'node:path'
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { stringify as stringifyYaml } from 'yaml'
 import { paths } from '../paths.js'
 import {
   readState,
@@ -17,69 +17,9 @@ import {
   requireBrainjarDir,
   normalizeSlug,
 } from '../state.js'
+import { readBrain, type BrainConfig } from '../brain.js'
 import { sync } from '../sync.js'
 
-/** Brain YAML schema: soul + persona + rules */
-export interface BrainConfig {
-  soul: string
-  persona: string
-  rules: string[]
-}
-
-/** Read and validate a brain YAML file. */
-export async function readBrain(name: string): Promise<BrainConfig> {
-  const slug = normalizeSlug(name, 'brain name')
-  const file = join(paths.brains, `${slug}.yaml`)
-
-  let raw: string
-  try {
-    raw = await readFile(file, 'utf-8')
-  } catch {
-    throw new IncurError({
-      code: 'BRAIN_NOT_FOUND',
-      message: `Brain "${slug}" not found.`,
-      hint: 'Run `brainjar brain list` to see available brains.',
-    })
-  }
-
-  let parsed: unknown
-  try {
-    parsed = parseYaml(raw)
-  } catch (e) {
-    throw new IncurError({
-      code: 'BRAIN_CORRUPT',
-      message: `Brain "${slug}" has invalid YAML: ${(e as Error).message}`,
-    })
-  }
-
-  if (!parsed || typeof parsed !== 'object') {
-    throw new IncurError({
-      code: 'BRAIN_CORRUPT',
-      message: `Brain "${slug}" is empty or invalid.`,
-    })
-  }
-
-  const p = parsed as Record<string, unknown>
-
-  if (typeof p.soul !== 'string' || !p.soul) {
-    throw new IncurError({
-      code: 'BRAIN_INVALID',
-      message: `Brain "${slug}" is missing required field "soul".`,
-    })
-  }
-
-  if (typeof p.persona !== 'string' || !p.persona) {
-    throw new IncurError({
-      code: 'BRAIN_INVALID',
-      message: `Brain "${slug}" is missing required field "persona".`,
-    })
-  }
-
-  const rules = Array.isArray(p.rules) ? p.rules.map(String) : []
-
-  return { soul: p.soul, persona: p.persona, rules }
-}
-
 export const brain = Cli.create('brain', {
   description: 'Manage brains — full-stack configuration snapshots (soul + persona + rules)',
 })

package/src/commands/compose.ts

@@ -15,7 +15,7 @@ import {
   stripFrontmatter,
   resolveRuleContent,
 } from '../state.js'
-import { readBrain } from './brain.js'
+import { readBrain } from '../brain.js'
 
 export const compose = Cli.create('compose', {
   description: 'Assemble a full subagent prompt from a brain or ad-hoc persona',

package/src/commands/hooks.ts

@@ -0,0 +1,41 @@
+import { Cli, z } from 'incur'
+import { installHooks, removeHooks, getHooksStatus } from '../hooks.js'
+
+const localOption = z.object({
+  local: z.boolean().default(false).describe('Target project-local .claude/settings.json'),
+})
+
+const install = Cli.create('install', {
+  description: 'Register brainjar hooks in Claude Code settings',
+  options: localOption,
+  async run(c) {
+    return installHooks({ local: c.options.local })
+  },
+})
+
+const remove = Cli.create('remove', {
+  description: 'Remove brainjar hooks from Claude Code settings',
+  options: localOption,
+  async run(c) {
+    return removeHooks({ local: c.options.local })
+  },
+})
+
+const status = Cli.create('status', {
+  description: 'Show brainjar hook installation status',
+  options: localOption,
+  async run(c) {
+    const result = await getHooksStatus({ local: c.options.local })
+    if (Object.keys(result.hooks).length === 0) {
+      return { ...result, installed: false }
+    }
+    return { ...result, installed: true }
+  },
+})
+
+export const hooks = Cli.create('hooks', {
+  description: 'Manage Claude Code hooks for brainjar',
+})
+  .command(install)
+  .command(remove)
+  .command(status)

package/src/commands/pack.ts

@@ -0,0 +1,49 @@
+import { Cli, z } from 'incur'
+import { resolve } from 'node:path'
+import { exportPack, importPack } from '../pack.js'
+
+const exportCmd = Cli.create('export', {
+  description: 'Export a brain as a shareable pack directory',
+  args: z.object({
+    brain: z.string().describe('Brain name to export'),
+  }),
+  options: z.object({
+    out: z.string().optional().describe('Parent directory for the exported pack (default: cwd)'),
+    name: z.string().optional().describe('Override pack name (and output directory name)'),
+    version: z.string().optional().describe('Semver version string (default: 0.1.0)'),
+    author: z.string().optional().describe('Author field in manifest'),
+  }),
+  async run(c) {
+    return exportPack(c.args.brain, {
+      out: c.options.out ? resolve(c.options.out) : undefined,
+      name: c.options.name,
+      version: c.options.version,
+      author: c.options.author,
+    })
+  },
+})
+
+const importCmd = Cli.create('import', {
+  description: 'Import a pack directory into ~/.brainjar/',
+  args: z.object({
+    path: z.string().describe('Path to pack directory'),
+  }),
+  options: z.object({
+    force: z.boolean().default(false).describe('Overwrite existing files on conflict'),
+    merge: z.boolean().default(false).describe('Rename incoming files on conflict as <name>-from-<packname>'),
+    activate: z.boolean().default(false).describe('Activate the brain after successful import'),
+  }),
+  async run(c) {
+    return importPack(resolve(c.args.path), {
+      force: c.options.force,
+      merge: c.options.merge,
+      activate: c.options.activate,
+    })
+  },
+})
+
+export const pack = Cli.create('pack', {
+  description: 'Export and import brainjar packs — self-contained shareable bundles',
+})
+  .command(exportCmd)
+  .command(importCmd)

package/src/commands/shell.ts

@@ -6,7 +6,7 @@ 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'
+import { readBrain } from '../brain.js'
 
 export const shell = Cli.create('shell', {
   description: 'Spawn a subshell with BRAINJAR_* env vars set',

package/src/commands/sync.ts

@@ -0,0 +1,16 @@
+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',
+  options: z.object({
+    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
+  },
+})

package/src/hooks.test.ts

@@ -0,0 +1,132 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { readFile, rm, mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { installHooks, removeHooks, getHooksStatus } from './hooks.js'
+
+const TEST_HOME = join(import.meta.dir, '..', '.test-home-hooks')
+const SETTINGS_PATH = join(TEST_HOME, '.claude', 'settings.json')
+
+beforeEach(async () => {
+  process.env.BRAINJAR_TEST_HOME = TEST_HOME
+  await mkdir(join(TEST_HOME, '.claude'), { recursive: true })
+})
+
+afterEach(async () => {
+  delete process.env.BRAINJAR_TEST_HOME
+  await rm(TEST_HOME, { recursive: true, force: true })
+})
+
+describe('hooks install', () => {
+  test('creates hooks in empty settings', async () => {
+    const result = await installHooks()
+    expect(result.installed).toContain('SessionStart')
+
+    const settings = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    expect(settings.hooks.SessionStart).toHaveLength(1)
+    expect(settings.hooks.SessionStart[0].matcher).toBe('startup')
+    expect(settings.hooks.SessionStart[0].hooks[0].command).toBe('brainjar sync --quiet')
+    expect(settings.hooks.SessionStart[0].hooks[0]._brainjar).toBe(true)
+  })
+
+  test('preserves existing settings', async () => {
+    await writeFile(SETTINGS_PATH, JSON.stringify({
+      statusLine: { type: 'command', command: 'echo hi' },
+      enabledPlugins: { foo: true },
+    }))
+
+    await installHooks()
+
+    const settings = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    expect(settings.statusLine.command).toBe('echo hi')
+    expect(settings.enabledPlugins.foo).toBe(true)
+    expect(settings.hooks.SessionStart).toHaveLength(1)
+  })
+
+  test('preserves existing non-brainjar hooks', async () => {
+    await writeFile(SETTINGS_PATH, JSON.stringify({
+      hooks: {
+        SessionStart: [
+          { matcher: 'startup', hooks: [{ type: 'command', command: 'echo hello' }] },
+        ],
+        PreToolUse: [
+          { matcher: 'Edit', hooks: [{ type: 'command', command: 'lint.sh' }] },
+        ],
+      },
+    }))
+
+    await installHooks()
+
+    const settings = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    // Existing non-brainjar SessionStart hook preserved
+    expect(settings.hooks.SessionStart).toHaveLength(2)
+    // PreToolUse untouched
+    expect(settings.hooks.PreToolUse).toHaveLength(1)
+    expect(settings.hooks.PreToolUse[0].hooks[0].command).toBe('lint.sh')
+  })
+
+  test('is idempotent — no duplicates on re-install', async () => {
+    await installHooks()
+    await installHooks()
+
+    const settings = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    const brainjarEntries = settings.hooks.SessionStart.filter(
+      (m: any) => m.hooks.some((h: any) => h._brainjar)
+    )
+    expect(brainjarEntries).toHaveLength(1)
+  })
+})
+
+describe('hooks remove', () => {
+  test('removes brainjar hooks', async () => {
+    await installHooks()
+    const result = await removeHooks()
+
+    expect(result.removed).toContain('SessionStart')
+
+    const settings = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    expect(settings.hooks).toBeUndefined()
+  })
+
+  test('preserves non-brainjar hooks', async () => {
+    await writeFile(SETTINGS_PATH, JSON.stringify({
+      hooks: {
+        SessionStart: [
+          { matcher: 'startup', hooks: [{ type: 'command', command: 'echo hello' }] },
+        ],
+      },
+    }))
+
+    await installHooks()
+    await removeHooks()
+
+    const settings = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    expect(settings.hooks.SessionStart).toHaveLength(1)
+    expect(settings.hooks.SessionStart[0].hooks[0].command).toBe('echo hello')
+  })
+
+  test('no-op when no brainjar hooks exist', async () => {
+    await writeFile(SETTINGS_PATH, JSON.stringify({ statusLine: { command: 'echo' } }))
+
+    const result = await removeHooks()
+    expect(result.removed).toHaveLength(0)
+  })
+})
+
+describe('hooks status', () => {
+  test('reports not installed when no hooks', async () => {
+    await writeFile(SETTINGS_PATH, JSON.stringify({}))
+    const result = await getHooksStatus()
+    expect(Object.keys(result.hooks)).toHaveLength(0)
+  })
+
+  test('reports installed hooks', async () => {
+    await installHooks()
+    const result = await getHooksStatus()
+    expect(result.hooks.SessionStart).toBe('brainjar sync --quiet')
+  })
+
+  test('handles missing settings file', async () => {
+    const result = await getHooksStatus()
+    expect(Object.keys(result.hooks)).toHaveLength(0)
+  })
+})

package/src/hooks.ts

@@ -0,0 +1,142 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { getHome } from './paths.js'
+
+export interface HookEntry {
+  type: 'command'
+  command: string
+  timeout?: number
+  _brainjar?: true
+}
+
+export interface HookMatcher {
+  matcher?: string
+  hooks: HookEntry[]
+}
+
+export interface HooksConfig {
+  [event: string]: HookMatcher[]
+}
+
+interface Settings {
+  hooks?: HooksConfig
+  [key: string]: unknown
+}
+
+const BRAINJAR_HOOKS: Record<string, HookMatcher> = {
+  SessionStart: {
+    matcher: 'startup',
+    hooks: [
+      {
+        type: 'command',
+        command: 'brainjar sync --quiet',
+        timeout: 5000,
+        _brainjar: true,
+      },
+    ],
+  },
+}
+
+function getSettingsPath(local: boolean): string {
+  if (local) return join(process.cwd(), '.claude', 'settings.json')
+  return join(getHome(), '.claude', 'settings.json')
+}
+
+async function readSettings(path: string): Promise<Settings> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf-8')
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return {}
+    throw e
+  }
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw new Error(`Invalid JSON in ${path} — fix the file or delete it and re-run.`)
+  }
+}
+
+async function writeSettings(path: string, settings: Settings): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, JSON.stringify(settings, null, 2) + '\n')
+}
+
+function isBrainjarHook(entry: HookEntry): boolean {
+  return entry._brainjar === true
+}
+
+function isBrainjarMatcher(matcher: HookMatcher): boolean {
+  return matcher.hooks.some(isBrainjarHook)
+}
+
+export async function installHooks(options: { local?: boolean } = {}): Promise<{ path: string; installed: string[] }> {
+  const path = getSettingsPath(options.local ?? false)
+  const settings = await readSettings(path)
+
+  if (!settings.hooks) settings.hooks = {}
+
+  const installed: string[] = []
+
+  for (const [event, matcher] of Object.entries(BRAINJAR_HOOKS)) {
+    if (!settings.hooks[event]) settings.hooks[event] = []
+
+    // Remove any existing brainjar entries for this event
+    settings.hooks[event] = settings.hooks[event].filter(m => !isBrainjarMatcher(m))
+
+    // Add the new one
+    settings.hooks[event].push(matcher)
+    installed.push(event)
+  }
+
+  await writeSettings(path, settings)
+  return { path, installed }
+}
+
+export async function removeHooks(options: { local?: boolean } = {}): Promise<{ path: string; removed: string[] }> {
+  const path = getSettingsPath(options.local ?? false)
+  const settings = await readSettings(path)
+
+  const removed: string[] = []
+
+  if (settings.hooks) {
+    for (const [event, matchers] of Object.entries(settings.hooks)) {
+      const filtered = matchers.filter(m => !isBrainjarMatcher(m))
+      if (filtered.length < matchers.length) {
+        removed.push(event)
+        if (filtered.length === 0) {
+          delete settings.hooks[event]
+        } else {
+          settings.hooks[event] = filtered
+        }
+      }
+    }
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks
+    }
+  }
+
+  await writeSettings(path, settings)
+  return { path, removed }
+}
+
+export async function getHooksStatus(options: { local?: boolean } = {}): Promise<{ path: string; hooks: Record<string, string> }> {
+  const path = getSettingsPath(options.local ?? false)
+  const settings = await readSettings(path)
+
+  const hooks: Record<string, string> = {}
+
+  if (settings.hooks) {
+    for (const [event, matchers] of Object.entries(settings.hooks)) {
+      for (const matcher of matchers) {
+        for (const hook of matcher.hooks) {
+          if (isBrainjarHook(hook)) {
+            hooks[event] = hook.command
+          }
+        }
+      }
+    }
+  }
+
+  return { path, hooks }
+}