@brainjar/cli 0.5.2 → 0.6.0

package/package.json

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

package/src/commands/brain.ts

@@ -160,7 +160,26 @@ export const brain = Cli.create('brain', {
     },
   })
   .command('drop', {
-    description: 'Delete a brain',
+    description: 'Deactivate the current brain — clears soul, persona, and rules',
+    options: z.object({
+      project: z.boolean().default(false).describe('Remove project brain override or deactivate workspace brain'),
+    }),
+    async run(c) {
+      const api = await getApi()
+
+      const mutationOpts = c.options.project
+        ? { project: basename(process.cwd()) }
+        : undefined
+      await putState(api, { soul_slug: '', persona_slug: '', rule_slugs: [] }, mutationOpts)
+
+      await sync({ api })
+      if (c.options.project) await sync({ api, project: true })
+
+      return { deactivated: true, project: c.options.project }
+    },
+  })
+  .command('delete', {
+    description: 'Delete a brain permanently',
     args: z.object({
       name: z.string().describe('Brain name to delete'),
     }),
@@ -177,6 +196,6 @@ export const brain = Cli.create('brain', {
         throw e
       }
 
-      return { dropped: name }
+      return { deleted: name }
     },
   })

package/src/commands/persona.ts

@@ -17,6 +17,7 @@ export const persona = Cli.create('persona', {
       name: z.string().describe('Persona name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Persona content (if omitted, creates with a starter template you can edit)'),
       description: z.string().optional().describe('One-line description of the persona'),
       rules: z.array(z.string()).optional().describe('Rules to bundle with this persona'),
     }),
@@ -50,24 +51,29 @@ export const persona = Cli.create('persona', {
 
       const effectiveRules = rulesList
 
-      const lines: string[] = []
-      lines.push(`# ${name}`)
-      lines.push('')
-      if (c.options.description) {
-        lines.push(c.options.description)
+      let content: string
+      if (c.options.content) {
+        content = c.options.content.trim()
+      } else {
+        const lines: string[] = []
+        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('')
+        content = lines.join('\n')
       }
-      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 api.put<ApiPersona>(`/api/v1/personas/${name}`, {
         content,
         bundled_rules: effectiveRules,
@@ -87,11 +93,12 @@ export const persona = Cli.create('persona', {
     },
   })
   .command('update', {
-    description: 'Update a persona\'s content (reads from stdin)',
+    description: 'Update a persona\'s content (reads from stdin or --content)',
     args: z.object({
       name: z.string().describe('Persona name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Persona content (reads from stdin if omitted)'),
       rules: z.array(z.string()).optional().describe('Update bundled rules'),
     }),
     async run(c) {
@@ -109,11 +116,14 @@ export const persona = Cli.create('persona', {
         throw e
       }
 
-      const chunks: Uint8Array[] = []
-      for await (const chunk of Bun.stdin.stream()) {
-        chunks.push(chunk)
+      let content = c.options.content?.trim()
+      if (!content) {
+        const chunks: Uint8Array[] = []
+        for await (const chunk of Bun.stdin.stream()) {
+          chunks.push(chunk)
+        }
+        content = Buffer.concat(chunks).toString().trim()
       }
-      const content = Buffer.concat(chunks).toString().trim()
 
       // Validate rules if provided
       const rulesList = c.options.rules
@@ -245,6 +255,31 @@ export const persona = Cli.create('persona', {
       return result
     },
   })
+  .command('delete', {
+    description: 'Delete a persona permanently',
+    args: z.object({
+      name: z.string().describe('Persona name to delete'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'persona name')
+      const api = await getApi()
+
+      try {
+        await api.delete(`/api/v1/personas/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.PERSONA_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
+
+      // If this persona was active, sync to reflect removal
+      const state = await getEffectiveState(api)
+      if (state.persona === name) await sync({ api })
+
+      return { deleted: name }
+    },
+  })
   .command('drop', {
     description: 'Deactivate the current persona',
     options: z.object({
@@ -256,7 +291,7 @@ export const persona = Cli.create('persona', {
       const mutationOpts = c.options.project
         ? { project: basename(process.cwd()) }
         : undefined
-      await putState(api, { persona_slug: null }, mutationOpts)
+      await putState(api, { persona_slug: '' }, mutationOpts)
 
       await sync({ api })
       if (c.options.project) await sync({ api, project: true })

package/src/commands/rules.ts

@@ -17,6 +17,7 @@ export const rules = Cli.create('rules', {
       name: z.string().describe('Rule name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Rule content (if omitted, creates with a starter template you can edit)'),
       description: z.string().optional().describe('One-line description of the rule'),
     }),
     async run(c) {
@@ -32,15 +33,20 @@ export const rules = Cli.create('rules', {
         if (e instanceof IncurError && e.code !== ErrorCode.NOT_FOUND) throw e
       }
 
-      const scaffold = [
-        `# ${name}`,
-        '',
-        c.options.description ?? 'Describe what this rule enforces and why.',
-        '',
-        '## Constraints',
-        '- ',
-        '',
-      ].join('\n')
+      let scaffold: string
+      if (c.options.content) {
+        scaffold = c.options.content.trim()
+      } else {
+        scaffold = [
+          `# ${name}`,
+          '',
+          c.options.description ?? 'Describe what this rule enforces and why.',
+          '',
+          '## Constraints',
+          '- ',
+          '',
+        ].join('\n')
+      }
 
       await api.put<ApiRule>(`/api/v1/rules/${name}`, {
         entries: [{ name: `${name}.md`, content: scaffold }],
@@ -59,10 +65,13 @@ export const rules = Cli.create('rules', {
     },
   })
   .command('update', {
-    description: 'Update a rule\'s content (reads from stdin)',
+    description: 'Update a rule\'s content (reads from stdin or --content)',
     args: z.object({
       name: z.string().describe('Rule name'),
     }),
+    options: z.object({
+      content: z.string().optional().describe('Rule content (reads from stdin if omitted)'),
+    }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'rule name')
       const api = await getApi()
@@ -77,11 +86,14 @@ export const rules = Cli.create('rules', {
         throw e
       }
 
-      const chunks: Uint8Array[] = []
-      for await (const chunk of Bun.stdin.stream()) {
-        chunks.push(chunk)
+      let content = c.options.content?.trim()
+      if (!content) {
+        const chunks: Uint8Array[] = []
+        for await (const chunk of Bun.stdin.stream()) {
+          chunks.push(chunk)
+        }
+        content = Buffer.concat(chunks).toString().trim()
       }
-      const content = Buffer.concat(chunks).toString().trim()
 
       if (!content) {
         throw createError(ErrorCode.MISSING_ARG, {
@@ -182,13 +194,38 @@ export const rules = Cli.create('rules', {
       return { activated: name, project: c.options.project }
     },
   })
-  .command('remove', {
+  .command('delete', {
+    description: 'Delete a rule permanently',
+    args: z.object({
+      name: z.string().describe('Rule name to delete'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'rule name')
+      const api = await getApi()
+
+      try {
+        await api.delete(`/api/v1/rules/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.RULE_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
+
+      // If this rule was active, sync to reflect removal
+      const state = await getEffectiveState(api)
+      if (state.rules.includes(name)) await sync({ api })
+
+      return { deleted: name }
+    },
+  })
+  .command('drop', {
     description: 'Deactivate a rule',
     args: z.object({
-      name: z.string().describe('Rule name to remove'),
+      name: z.string().describe('Rule name to deactivate'),
     }),
     options: z.object({
-      project: z.boolean().default(false).describe('Remove rule at project scope'),
+      project: z.boolean().default(false).describe('Deactivate rule at project scope'),
     }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'rule name')

package/src/commands/soul.ts

@@ -17,6 +17,7 @@ export const soul = Cli.create('soul', {
       name: z.string().describe('Soul name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Soul content (if omitted, creates with a starter template you can edit)'),
       description: z.string().optional().describe('One-line description of the soul'),
     }),
     async run(c) {
@@ -32,24 +33,29 @@ export const soul = Cli.create('soul', {
         if (e instanceof IncurError && e.code !== ErrorCode.NOT_FOUND) throw e
       }
 
-      const lines: string[] = []
-      lines.push(`# ${name}`)
-      lines.push('')
-      if (c.options.description) {
-        lines.push(c.options.description)
+      let content: string
+      if (c.options.content) {
+        content = c.options.content.trim()
+      } else {
+        const lines: string[] = []
+        lines.push(`# ${name}`)
         lines.push('')
+        if (c.options.description) {
+          lines.push(c.options.description)
+          lines.push('')
+        }
+        lines.push('## Voice')
+        lines.push('- ')
+        lines.push('')
+        lines.push('## Character')
+        lines.push('- ')
+        lines.push('')
+        lines.push('## Standards')
+        lines.push('- ')
+        lines.push('')
+        content = lines.join('\n')
       }
-      lines.push('## Voice')
-      lines.push('- ')
-      lines.push('')
-      lines.push('## Character')
-      lines.push('- ')
-      lines.push('')
-      lines.push('## Standards')
-      lines.push('- ')
-      lines.push('')
-
-      const content = lines.join('\n')
+
       await api.put<ApiSoul>(`/api/v1/souls/${name}`, { content })
 
       if (c.agent || c.formatExplicit) {
@@ -65,10 +71,13 @@ export const soul = Cli.create('soul', {
     },
   })
   .command('update', {
-    description: 'Update a soul\'s content (reads from stdin)',
+    description: 'Update a soul\'s content (reads from stdin or --content)',
     args: z.object({
       name: z.string().describe('Soul name'),
     }),
+    options: z.object({
+      content: z.string().optional().describe('Soul content (reads from stdin if omitted)'),
+    }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'soul name')
       const api = await getApi()
@@ -83,11 +92,14 @@ export const soul = Cli.create('soul', {
         throw e
       }
 
-      const chunks: Uint8Array[] = []
-      for await (const chunk of Bun.stdin.stream()) {
-        chunks.push(chunk)
+      let content = c.options.content?.trim()
+      if (!content) {
+        const chunks: Uint8Array[] = []
+        for await (const chunk of Bun.stdin.stream()) {
+          chunks.push(chunk)
+        }
+        content = Buffer.concat(chunks).toString().trim()
       }
-      const content = Buffer.concat(chunks).toString().trim()
 
       if (!content) {
         throw createError(ErrorCode.MISSING_ARG, {
@@ -201,6 +213,31 @@ export const soul = Cli.create('soul', {
       return { activated: name, project: c.options.project }
     },
   })
+  .command('delete', {
+    description: 'Delete a soul permanently',
+    args: z.object({
+      name: z.string().describe('Soul name to delete'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'soul name')
+      const api = await getApi()
+
+      try {
+        await api.delete(`/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 this soul was active, sync to reflect removal
+      const state = await getEffectiveState(api)
+      if (state.soul === name) await sync({ api })
+
+      return { deleted: name }
+    },
+  })
   .command('drop', {
     description: 'Deactivate the current soul',
     options: z.object({
@@ -212,7 +249,7 @@ export const soul = Cli.create('soul', {
       const mutationOpts = c.options.project
         ? { project: basename(process.cwd()) }
         : undefined
-      await putState(api, { soul_slug: null }, mutationOpts)
+      await putState(api, { soul_slug: '' }, mutationOpts)
 
       await sync({ api })
       if (c.options.project) await sync({ api, project: true })

package/src/daemon.ts

@@ -8,6 +8,7 @@ import { readConfig, activeContext, localContext } from './config.js'
 import { ErrorCode, createError } from './errors.js'
 
 export const DIST_BASE = 'https://get.brainjar.sh/brainjar-server'
+export const SEMVER_RE = /^v?\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?(\+[a-zA-Z0-9.]+)?$/
 
 /**
  * Compare two semver strings. Returns -1, 0, or 1.
@@ -156,7 +157,13 @@ export async function fetchLatestVersion(distBase: string = DIST_BASE): Promise<
       hint: 'Check your network connection or try again later.',
     })
   }
-  return (await response.text()).trim()
+  const version = (await response.text()).trim()
+  if (!SEMVER_RE.test(version)) {
+    throw createError(ErrorCode.VALIDATION_ERROR, {
+      message: `Invalid server version string from distribution: "${version}"`,
+    })
+  }
+  return version
 }
 
 /**

package/src/pack.ts

@@ -1,5 +1,5 @@
 import { readFile, readdir, writeFile, access, mkdir, stat } from 'node:fs/promises'
-import { join, dirname } from 'node:path'
+import { join, dirname, basename } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { Errors } from 'incur'
 import { ErrorCode, createError } from './errors.js'
@@ -127,7 +127,13 @@ export async function exportPack(brainName: string, options: ExportOptions = {})
       const ruleDir = join(packDir, 'rules', ruleSlug)
       await mkdir(ruleDir, { recursive: true })
       for (const entry of rule.entries) {
-        await writeFile(join(ruleDir, entry.name), entry.content)
+        const safeName = basename(entry.name)
+        if (!safeName || safeName !== entry.name) {
+          throw createError(ErrorCode.PACK_INVALID_MANIFEST, {
+            message: `Rule entry name contains invalid path: "${entry.name}"`,
+          })
+        }
+        await writeFile(join(ruleDir, safeName), entry.content)
       }
     }
   }

package/src/upgrade.ts

@@ -2,14 +2,22 @@ import { execFile } from 'node:child_process'
 import {
   healthCheck,
   start,
-  stop,
   status as daemonStatus,
   upgradeServer,
+  SEMVER_RE,
 } from './daemon.js'
 import { checkForUpdates } from './version-check.js'
 import { ErrorCode, createError } from './errors.js'
 import pkg from '../package.json'
 
+function validateVersion(v: string, label: string): void {
+  if (!SEMVER_RE.test(v)) {
+    throw createError(ErrorCode.VALIDATION_ERROR, {
+      message: `Invalid ${label} version string: "${v}"`,
+    })
+  }
+}
+
 export interface ComponentResult {
   upgraded: boolean
   from: string
@@ -59,6 +67,7 @@ export async function upgradeCli(): Promise<ComponentResult> {
   }
 
   const latestVersion = updates.cli.latest
+  validateVersion(latestVersion, 'CLI')
   const pm = detectPackageManager()
 
   try {