@brainjar/cli 0.6.0 → 0.6.2

package/package.json

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

package/src/api-types.ts

@@ -107,6 +107,53 @@ export interface ApiComposeResult {
   warnings?: string[]
 }
 
+// --- API key types ---
+
+export interface ApiCreateKeyResult {
+  id: string
+  name: string
+  key: string
+  key_prefix: string
+  user_id: string
+  expires_at: string | null
+  created_at: string
+}
+
+export interface ApiKeySummary {
+  id: string
+  name: string
+  key_prefix: string
+  user_id: string
+  expires_at: string | null
+  revoked_at: string | null
+  created_at: string
+}
+
+export interface ApiKeyList {
+  api_keys: ApiKeySummary[]
+}
+
+// --- Content version types ---
+
+export interface ApiVersionSummary {
+  version: number
+  created_at: string
+}
+
+export interface ApiVersionList {
+  versions: ApiVersionSummary[]
+}
+
+export interface ApiContentVersion {
+  id: string
+  content_type: string
+  slug: string
+  version: number
+  content: string | null
+  metadata: Record<string, unknown> | null
+  created_at: string
+}
+
 // --- Content bundle types (export/import) ---
 
 export interface BundleSoul {

package/src/cli.ts

@@ -17,6 +17,7 @@ import { server } from './commands/server.js'
 import { migrate } from './commands/migrate.js'
 import { upgrade } from './commands/upgrade.js'
 import { context } from './commands/context.js'
+import { apiKey } from './commands/api-key.js'
 
 Cli.create('brainjar', {
   description: 'Shape how your AI thinks — soul, persona, rules',
@@ -39,4 +40,5 @@ Cli.create('brainjar', {
   .command(migrate)
   .command(upgrade)
   .command(context)
+  .command(apiKey)
   .serve()

package/src/client.ts

@@ -1,8 +1,9 @@
 import { Errors } from 'incur'
-import { basename } from 'node:path'
-import { readConfig, activeContext } from './config.js'
-import { getLocalDir } from './paths.js'
-import { access } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { readConfig, activeContext, isLocalContext } from './config.js'
+import type { ServerContext } from './config.js'
+import { getBrainjarDir, getLocalDir } from './paths.js'
+import { access, readFile } from 'node:fs/promises'
 import { ensureRunning } from './daemon.js'
 import { ErrorCode, createError } from './errors.js'
 
@@ -41,6 +42,24 @@ const ERROR_MAP: Record<number, { code: ErrorCode; hint?: string }> = {
   503: { code: ErrorCode.SERVER_UNAVAILABLE, hint: 'Server is not ready. Try again in a moment.' },
 }
 
+async function resolveToken(ctx: ServerContext): Promise<string | null> {
+  const envToken = process.env.BRAINJAR_TOKEN
+  if (envToken) return envToken
+
+  if (isLocalContext(ctx)) {
+    const tokenFile = ctx.auth_token_file ?? join(getBrainjarDir(), 'auth-token')
+    try {
+      return (await readFile(tokenFile, 'utf-8')).trim()
+    } catch {
+      return null // token file doesn't exist yet (server not started)
+    }
+  }
+
+  if (ctx.token) return ctx.token
+
+  return null
+}
+
 async function detectProject(explicit?: string | null): Promise<string | null> {
   if (explicit === null) return null // explicitly suppress auto-detection
   if (explicit) return explicit
@@ -68,11 +87,14 @@ export async function createClient(options?: ClientOptions): Promise<BrainjarCli
     const url = `${serverUrl}${path}`
     const timeout = reqOpts?.timeout ?? defaultTimeout
 
+    const token = await resolveToken(ctx)
+
     const headers: Record<string, string> = {
       'Accept': 'application/json',
       'X-Brainjar-Workspace': workspace,
       ...(reqOpts?.headers ?? {}),
     }
+    if (token) headers['Authorization'] = `Bearer ${token}`
 
     const explicitProject = reqOpts && 'project' in reqOpts ? reqOpts.project : options?.project
     const project = await detectProject(explicitProject)

package/src/commands/api-key.ts

@@ -0,0 +1,50 @@
+import { Cli, z } from 'incur'
+import { getApi } from '../client.js'
+import type { ApiCreateKeyResult, ApiKeyList } from '../api-types.js'
+
+export const apiKey = Cli.create('api-key', {
+  description: 'Manage API keys for remote server authentication',
+})
+  .command('create', {
+    description: 'Create a new API key',
+    options: z.object({
+      name: z.string().describe('Key name (e.g. ci-pipeline)'),
+      'user-id': z.string().optional().describe('User ID label for the key'),
+      'expires-in': z.string().optional().describe('Expiration duration (e.g. 30d, 90d, 365d)'),
+    }),
+    async run(c) {
+      const api = await getApi()
+      const result = await api.post<ApiCreateKeyResult>('/api/v1/api-keys', {
+        name: c.options.name,
+        user_id: c.options['user-id'] ?? '',
+        expires_in: c.options['expires-in'] ?? '',
+      })
+      return {
+        id: result.id,
+        name: result.name,
+        key: result.key,
+        key_prefix: result.key_prefix,
+        expires_at: result.expires_at,
+        warning: 'Save this key now — it will not be shown again.',
+      }
+    },
+  })
+  .command('list', {
+    description: 'List API keys',
+    async run() {
+      const api = await getApi()
+      const result = await api.get<ApiKeyList>('/api/v1/api-keys')
+      return result
+    },
+  })
+  .command('revoke', {
+    description: 'Revoke an API key',
+    args: z.object({
+      id: z.string().describe('API key ID'),
+    }),
+    async run(c) {
+      const api = await getApi()
+      await api.delete(`/api/v1/api-keys/${c.args.id}`)
+      return { revoked: c.args.id }
+    },
+  })

package/src/commands/context.ts

@@ -209,6 +209,33 @@ const renameCmd = Cli.create('rename', {
   },
 })
 
+const setTokenCmd = Cli.create('set-token', {
+  description: 'Store an API key for a context',
+  args: z.object({
+    name: z.string().describe('Context name'),
+    key: z.string().describe('API key (bjk_...)'),
+  }),
+  async run(c) {
+    const config = await readConfig()
+
+    if (!(c.args.name in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [c.args.name] })
+    }
+
+    const ctx = config.contexts[c.args.name]
+    if (isLocalContext(ctx)) {
+      throw createError(ErrorCode.VALIDATION_ERROR, {
+        message: 'Cannot set a token on a local context. Local contexts use auto-generated tokens.',
+      })
+    }
+
+    ctx.token = c.args.key
+    await writeConfig(config)
+
+    return { context: c.args.name, token_set: true }
+  },
+})
+
 export const context = Cli.create('context', {
   description: 'Manage server contexts — named server profiles',
 })
@@ -218,3 +245,4 @@ export const context = Cli.create('context', {
   .command(useCmd)
   .command(showCmd)
   .command(renameCmd)
+  .command(setTokenCmd)

package/src/commands/persona.ts

@@ -6,7 +6,7 @@ import { ErrorCode, createError } from '../errors.js'
 import { normalizeSlug, getEffectiveState, getStateOverride, putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
-import type { ApiPersona, ApiPersonaList, ApiRuleList } from '../api-types.js'
+import type { ApiPersona, ApiPersonaList, ApiRuleList, ApiVersionList, ApiContentVersion } from '../api-types.js'
 
 export const persona = Cli.create('persona', {
   description: 'Manage personas — role behavior and workflow for the agent',
@@ -167,6 +167,7 @@ export const persona = Cli.create('persona', {
     options: z.object({
       project: z.boolean().default(false).describe('Show project persona override (if any)'),
       short: z.boolean().default(false).describe('Print only the active persona name'),
+      version: z.number().optional().describe('Show a specific version from history'),
     }),
     async run(c) {
       const api = await getApi()
@@ -177,6 +178,14 @@ export const persona = Cli.create('persona', {
         return state.persona ?? 'none'
       }
 
+      if (c.options.version) {
+        const name = c.args.name
+        if (!name) throw createError(ErrorCode.MISSING_ARG, { message: 'Name is required when using --version' })
+        const slug = normalizeSlug(name, 'persona name')
+        const v = await api.get<ApiContentVersion>(`/api/v1/personas/${slug}/versions/${c.options.version}`)
+        return { name: slug, version: v.version, content: v.content, metadata: v.metadata, created_at: v.created_at }
+      }
+
       if (c.args.name) {
         const name = normalizeSlug(c.args.name, 'persona name')
         try {
@@ -214,6 +223,40 @@ export const persona = Cli.create('persona', {
       }
     },
   })
+  .command('history', {
+    description: 'List version history for a persona',
+    args: z.object({
+      name: z.string().describe('Persona name'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'persona name')
+      const api = await getApi()
+      const result = await api.get<ApiVersionList>(`/api/v1/personas/${name}/versions`)
+      return { name, versions: result.versions }
+    },
+  })
+  .command('revert', {
+    description: 'Restore a persona to a previous version',
+    args: z.object({
+      name: z.string().describe('Persona name'),
+    }),
+    options: z.object({
+      to: z.number().describe('Version number to restore'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'persona name')
+      const api = await getApi()
+      const v = await api.get<ApiContentVersion>(`/api/v1/personas/${name}/versions/${c.options.to}`)
+      if (!v.content) throw createError(ErrorCode.BAD_REQUEST, { message: 'Version has no content to restore' })
+      const bundledRules = (v.metadata as { bundled_rules?: string[] })?.bundled_rules ?? []
+      await api.put<ApiPersona>(`/api/v1/personas/${name}`, { content: v.content, bundled_rules: bundledRules })
+
+      const state = await getEffectiveState(api)
+      if (state.persona === name) await sync({ api })
+
+      return { reverted: name, to_version: c.options.to }
+    },
+  })
   .command('use', {
     description: 'Activate a persona',
     args: z.object({

package/src/commands/rules.ts

@@ -6,7 +6,7 @@ import { ErrorCode, createError } from '../errors.js'
 import { normalizeSlug, getEffectiveState, getStateOverride, putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
-import type { ApiRule, ApiRuleList } from '../api-types.js'
+import type { ApiRule, ApiRuleList, ApiVersionList, ApiContentVersion } from '../api-types.js'
 
 export const rules = Cli.create('rules', {
   description: 'Manage rules — behavioral constraints for the agent',
@@ -145,10 +145,20 @@ export const rules = Cli.create('rules', {
     args: z.object({
       name: z.string().describe('Rule name to show'),
     }),
+    options: z.object({
+      version: z.number().optional().describe('Show a specific version from history'),
+    }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'rule name')
       const api = await getApi()
 
+      if (c.options.version) {
+        const v = await api.get<ApiContentVersion>(`/api/v1/rules/${name}/versions/${c.options.version}`)
+        const entries = (v.metadata as { entries?: Array<{ sort_key: number; content: string }> })?.entries ?? []
+        const content = entries.map(e => e.content.trim()).join('\n\n')
+        return { name, version: v.version, content, created_at: v.created_at }
+      }
+
       try {
         const rule = await api.get<ApiRule>(`/api/v1/rules/${name}`)
         const content = rule.entries.map(e => e.content.trim()).join('\n\n')
@@ -161,6 +171,40 @@ export const rules = Cli.create('rules', {
       }
     },
   })
+  .command('history', {
+    description: 'List version history for a rule',
+    args: z.object({
+      name: z.string().describe('Rule name'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'rule name')
+      const api = await getApi()
+      const result = await api.get<ApiVersionList>(`/api/v1/rules/${name}/versions`)
+      return { name, versions: result.versions }
+    },
+  })
+  .command('revert', {
+    description: 'Restore a rule to a previous version',
+    args: z.object({
+      name: z.string().describe('Rule name'),
+    }),
+    options: z.object({
+      to: z.number().describe('Version number to restore'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'rule name')
+      const api = await getApi()
+      const v = await api.get<ApiContentVersion>(`/api/v1/rules/${name}/versions/${c.options.to}`)
+      const entries = (v.metadata as { entries?: Array<{ sort_key: number; content: string }> })?.entries
+      if (!entries) throw createError(ErrorCode.BAD_REQUEST, { message: 'Version has no entries to restore' })
+      await api.put<ApiRule>(`/api/v1/rules/${name}`, { entries: entries.map(e => ({ name: `${name}.md`, content: e.content })) })
+
+      const state = await getEffectiveState(api)
+      if (state.rules.includes(name)) await sync({ api })
+
+      return { reverted: name, to_version: c.options.to }
+    },
+  })
   .command('add', {
     description: 'Activate a rule or rule pack',
     args: z.object({

package/src/commands/soul.ts

@@ -6,7 +6,7 @@ import { ErrorCode, createError } from '../errors.js'
 import { normalizeSlug, getEffectiveState, getStateOverride, putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
-import type { ApiSoul, ApiSoulList } from '../api-types.js'
+import type { ApiSoul, ApiSoulList, ApiVersionList, ApiContentVersion } from '../api-types.js'
 
 export const soul = Cli.create('soul', {
   description: 'Manage soul — personality and values for the agent',
@@ -133,6 +133,7 @@ export const soul = Cli.create('soul', {
     options: z.object({
       project: z.boolean().default(false).describe('Show project soul override (if any)'),
       short: z.boolean().default(false).describe('Print only the active soul name'),
+      version: z.number().optional().describe('Show a specific version from history'),
     }),
     async run(c) {
       const api = await getApi()
@@ -143,6 +144,14 @@ export const soul = Cli.create('soul', {
         return state.soul ?? 'none'
       }
 
+      if (c.options.version) {
+        const name = c.args.name
+        if (!name) throw createError(ErrorCode.MISSING_ARG, { message: 'Name is required when using --version' })
+        const slug = normalizeSlug(name, 'soul name')
+        const v = await api.get<ApiContentVersion>(`/api/v1/souls/${slug}/versions/${c.options.version}`)
+        return { name: slug, version: v.version, content: v.content, created_at: v.created_at }
+      }
+
       if (c.args.name) {
         const name = normalizeSlug(c.args.name, 'soul name')
         try {
@@ -180,6 +189,39 @@ export const soul = Cli.create('soul', {
       }
     },
   })
+  .command('history', {
+    description: 'List version history for a soul',
+    args: z.object({
+      name: z.string().describe('Soul name'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'soul name')
+      const api = await getApi()
+      const result = await api.get<ApiVersionList>(`/api/v1/souls/${name}/versions`)
+      return { name, versions: result.versions }
+    },
+  })
+  .command('revert', {
+    description: 'Restore a soul to a previous version',
+    args: z.object({
+      name: z.string().describe('Soul name'),
+    }),
+    options: z.object({
+      to: z.number().describe('Version number to restore'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'soul name')
+      const api = await getApi()
+      const v = await api.get<ApiContentVersion>(`/api/v1/souls/${name}/versions/${c.options.to}`)
+      if (!v.content) throw createError(ErrorCode.BAD_REQUEST, { message: 'Version has no content to restore' })
+      await api.put<ApiSoul>(`/api/v1/souls/${name}`, { content: v.content })
+
+      const state = await getEffectiveState(api)
+      if (state.soul === name) await sync({ api })
+
+      return { reverted: name, to_version: c.options.to }
+    },
+  })
   .command('use', {
     description: 'Activate a soul',
     args: z.object({

package/src/config.ts

@@ -13,12 +13,14 @@ export interface LocalContext {
   pid_file: string
   log_file: string
   workspace: string
+  auth_token_file?: string
 }
 
 export interface RemoteContext {
   url: string
   mode: 'remote'
   workspace: string
+  token?: string
 }
 
 export type ServerContext = LocalContext | RemoteContext
@@ -197,7 +199,7 @@ function parseV2(p: Record<string, unknown>): Config {
       if (!raw || typeof raw !== 'object') continue
       const ctx = raw as Record<string, unknown>
       if (ctx.mode === 'local') {
-        config.contexts[name] = {
+        const local: LocalContext = {
           url: typeof ctx.url === 'string' ? ctx.url : 'http://localhost:7742',
           mode: 'local',
           bin: typeof ctx.bin === 'string' ? ctx.bin : defLocal.bin,
@@ -205,12 +207,16 @@ function parseV2(p: Record<string, unknown>): Config {
           log_file: typeof ctx.log_file === 'string' ? ctx.log_file : defLocal.log_file,
           workspace: typeof ctx.workspace === 'string' ? ctx.workspace : 'default',
         }
+        if (typeof ctx.auth_token_file === 'string') local.auth_token_file = ctx.auth_token_file
+        config.contexts[name] = local
       } else {
-        config.contexts[name] = {
+        const remote: RemoteContext = {
           url: typeof ctx.url === 'string' ? ctx.url : '',
           mode: 'remote',
           workspace: typeof ctx.workspace === 'string' ? ctx.workspace : 'default',
         }
+        if (typeof ctx.token === 'string') remote.token = ctx.token
+        config.contexts[name] = remote
       }
     }
   }
@@ -287,7 +293,7 @@ export async function writeConfig(config: Config): Promise<void> {
   const contexts = doc.contexts as Record<string, unknown>
   for (const [name, ctx] of Object.entries(config.contexts)) {
     if (isLocalContext(ctx)) {
-      contexts[name] = {
+      const local: Record<string, unknown> = {
         url: ctx.url,
         mode: ctx.mode,
         bin: ctx.bin,
@@ -295,12 +301,16 @@ export async function writeConfig(config: Config): Promise<void> {
         log_file: ctx.log_file,
         workspace: ctx.workspace,
       }
+      if (ctx.auth_token_file) local.auth_token_file = ctx.auth_token_file
+      contexts[name] = local
     } else {
-      contexts[name] = {
+      const remote: Record<string, unknown> = {
         url: ctx.url,
         mode: ctx.mode,
         workspace: ctx.workspace,
       }
+      if (ctx.token) remote.token = ctx.token
+      contexts[name] = remote
     }
   }