@brainjar/cli 0.5.1 → 0.5.2

package/package.json

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

package/src/api-types.ts

@@ -63,7 +63,7 @@ export interface ApiEffectiveState {
   rules: string[]
 }
 
-/** State override at a single scope, returned by GET /api/v1/state/override. */
+/** State override at a single scope. */
 export interface ApiStateOverride {
   soul_slug?: string | null
   persona_slug?: string | null
@@ -72,6 +72,12 @@ export interface ApiStateOverride {
   rules_to_remove?: string[]
 }
 
+/** Envelope returned by GET /api/v1/state/override. */
+export interface ApiStateOverrideResponse {
+  override: ApiStateOverride | null
+  scope: { id: string; scope_type: string; reference_id: string; parent_scope_id?: string } | null
+}
+
 /** Body for PUT /api/v1/state — partial update. */
 export interface ApiStateMutation {
   soul_slug?: string | null

package/src/client.ts

@@ -19,7 +19,8 @@ export interface ClientOptions {
 export interface RequestOptions {
   timeout?: number
   headers?: Record<string, string>
-  project?: string
+  /** Pass a project name to scope to that project, null to suppress auto-detection, or undefined for auto-detect. */
+  project?: string | null
 }
 
 export interface BrainjarClient {
@@ -40,7 +41,8 @@ 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 detectProject(explicit?: string): Promise<string | null> {
+async function detectProject(explicit?: string | null): Promise<string | null> {
+  if (explicit === null) return null // explicitly suppress auto-detection
   if (explicit) return explicit
   try {
     await access(getLocalDir())
@@ -72,7 +74,8 @@ export async function createClient(options?: ClientOptions): Promise<BrainjarCli
       ...(reqOpts?.headers ?? {}),
     }
 
-    const project = await detectProject(reqOpts?.project ?? options?.project)
+    const explicitProject = reqOpts && 'project' in reqOpts ? reqOpts.project : options?.project
+    const project = await detectProject(explicitProject)
     if (project) headers['X-Brainjar-Project'] = project
     if (session) headers['X-Brainjar-Session'] = session
 

package/src/commands/persona.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
-import { normalizeSlug, getEffectiveState, putState } from '../state.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'
@@ -181,7 +181,7 @@ export const persona = Cli.create('persona', {
       }
 
       if (c.options.project) {
-        const state = await api.get<import('../api-types.js').ApiStateOverride>('/api/v1/state/override', {
+        const state = await getStateOverride(api, {
           project: basename(process.cwd()),
         })
         if (state.persona_slug === undefined) return { active: false, scope: 'project', note: 'No project persona override (cascades from workspace)' }

package/src/commands/rules.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
-import { normalizeSlug, getEffectiveState, putState } from '../state.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'
@@ -112,7 +112,7 @@ export const rules = Cli.create('rules', {
       const availableSlugs = available.rules.map(r => r.slug)
 
       if (c.options.project) {
-        const override = await api.get<import('../api-types.js').ApiStateOverride>('/api/v1/state/override', {
+        const override = await getStateOverride(api, {
           project: basename(process.cwd()),
         })
         return {

package/src/commands/soul.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
-import { normalizeSlug, getEffectiveState, putState } from '../state.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'
@@ -145,7 +145,7 @@ export const soul = Cli.create('soul', {
       }
 
       if (c.options.project) {
-        const state = await api.get<import('../api-types.js').ApiStateOverride>('/api/v1/state/override', {
+        const state = await getStateOverride(api, {
           project: basename(process.cwd()),
         })
         if (state.soul_slug === undefined) return { active: false, scope: 'project', note: 'No project soul override (cascades from workspace)' }

package/src/commands/status.ts

@@ -1,9 +1,8 @@
 import { Cli, z } from 'incur'
 import { basename } from 'node:path'
-import { getEffectiveState } from '../state.js'
+import { getEffectiveState, getStateOverride } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
-import type { ApiStateOverride } from '../api-types.js'
 
 export const status = Cli.create('status', {
   description: 'Show active brain configuration',
@@ -35,11 +34,11 @@ export const status = Cli.create('status', {
 
     // --workspace: show only workspace-level override
     if (c.options.workspace) {
-      const override = await api.get<ApiStateOverride>('/api/v1/state/override')
+      const override = await getStateOverride(api, { project: null })
       const result: Record<string, unknown> = {
         soul: override.soul_slug ?? null,
         persona: override.persona_slug ?? null,
-        rules: override.rule_slugs ?? [],
+        rules: override.rules_to_add ?? [],
       }
       if (synced) result.synced = synced
       return result
@@ -47,7 +46,7 @@ export const status = Cli.create('status', {
 
     // --project: show only project-level overrides
     if (c.options.project) {
-      const override = await api.get<ApiStateOverride>('/api/v1/state/override', {
+      const override = await getStateOverride(api, {
         project: basename(process.cwd()),
       })
       const result: Record<string, unknown> = {}

package/src/daemon.ts

@@ -1,6 +1,6 @@
 import { spawn, execFileSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
-import { readFile, writeFile, rm, access, open, chmod, mkdir } from 'node:fs/promises'
+import { readFile, writeFile, rm, access, open, chmod, mkdir, constants } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Errors } from 'incur'
@@ -30,7 +30,7 @@ const { IncurError } = Errors
  * Minimum server version this CLI is compatible with.
  * Bump when the CLI depends on server features/API changes.
  */
-export const MIN_SERVER_VERSION = '0.2.2'
+export const MIN_SERVER_VERSION = '0.2.4'
 
 export interface HealthStatus {
   healthy: boolean
@@ -268,6 +268,12 @@ export async function upgradeServer(): Promise<{ version: string; alreadyLatest:
     return { version, alreadyLatest: true }
   }
 
+  // Stop server before replacing binary to avoid ETXTBSY on Linux
+  const pid = await readPid(localContext(config).pid_file)
+  if (pid !== null && isAlive(pid)) {
+    await stop()
+  }
+
   const versionBase = `${DIST_BASE}/${version}`
   await downloadAndVerify(binPath, versionBase)
   await setInstalledServerVersion(version)
@@ -397,9 +403,25 @@ export async function readLogFile(options?: { lines?: number }): Promise<string>
   }
 }
 
+/**
+ * Try to acquire an exclusive lock file. Returns a release function on success, null if already locked.
+ */
+async function tryLock(lockFile: string): Promise<(() => Promise<void>) | null> {
+  try {
+    const fd = await open(lockFile, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY)
+    await fd.write(String(process.pid))
+    await fd.close()
+    return async () => { await rm(lockFile, { force: true }) }
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'EEXIST') return null
+    throw e
+  }
+}
+
 /**
  * Ensure the server is running and healthy.
  * Called by commands before making API calls.
+ * Uses a file lock to prevent parallel CLI invocations from spawning multiple server processes.
  */
 export async function ensureRunning(): Promise<void> {
   const config = await readConfig()
@@ -420,20 +442,31 @@ export async function ensureRunning(): Promise<void> {
     })
   }
 
-  // Local mode: auto-start
-  await cleanStalePid(local.pid_file)
+  // Local mode: auto-start with file lock to prevent races
+  const lockFile = `${local.pid_file}.lock`
+  const release = await tryLock(lockFile)
 
-  try {
-    await start()
-  } catch (e) {
-    if (e instanceof IncurError) throw e
-    throw createError(ErrorCode.SERVER_START_FAILED, {
-      message: 'Failed to start brainjar server.',
-      hint: `Check ${local.log_file}`,
-    })
+  if (release) {
+    // We hold the lock — we're responsible for starting
+    try {
+      await cleanStalePid(local.pid_file)
+
+      try {
+        await start()
+      } catch (e) {
+        if (e instanceof IncurError) throw e
+        throw createError(ErrorCode.SERVER_START_FAILED, {
+          message: 'Failed to start brainjar server.',
+          hint: `Check ${local.log_file}`,
+        })
+      }
+    } finally {
+      await release()
+    }
   }
 
   // Poll until healthy (200ms intervals, 10s timeout)
+  // Both the lock holder and waiters converge here
   const deadline = Date.now() + 10_000
   while (Date.now() < deadline) {
     await new Promise(r => setTimeout(r, 200))

package/src/state.ts

@@ -1,5 +1,5 @@
-import type { BrainjarClient } from './client.js'
-import type { ApiEffectiveState, ApiStateMutation } from './api-types.js'
+import type { BrainjarClient, RequestOptions } from './client.js'
+import type { ApiEffectiveState, ApiStateMutation, ApiStateOverride, ApiStateOverrideResponse } from './api-types.js'
 
 const SLUG_RE = /^[a-zA-Z0-9_-]+$/
 
@@ -15,8 +15,14 @@ export function normalizeSlug(value: string, label: string): string {
 }
 
 /** Fetch the fully resolved effective state from the server. */
-export async function getEffectiveState(api: BrainjarClient): Promise<ApiEffectiveState> {
-  return api.get<ApiEffectiveState>('/api/v1/state')
+export async function getEffectiveState(api: BrainjarClient, options?: RequestOptions): Promise<ApiEffectiveState> {
+  return api.get<ApiEffectiveState>('/api/v1/state', options)
+}
+
+/** Fetch the raw override at a specific scope, unwrapping the server envelope. */
+export async function getStateOverride(api: BrainjarClient, options?: RequestOptions): Promise<ApiStateOverride> {
+  const resp = await api.get<ApiStateOverrideResponse>('/api/v1/state/override', options)
+  return resp.override ?? {}
 }
 
 /** Mutate state on the server. Pass options.project to scope the mutation to a project. */

package/src/sync.ts

@@ -1,4 +1,5 @@
 import { readFile, writeFile, copyFile, mkdir } from 'node:fs/promises'
+import { basename } from 'node:path'
 import { type Backend, getBackendConfig } from './paths.js'
 import { getEffectiveState } from './state.js'
 import { getApi, type BrainjarClient } from './client.js'
@@ -72,7 +73,7 @@ export async function sync(options?: SyncOptions) {
   const opts = options ?? {}
   const api = opts.api ?? await getApi()
 
-  const state = await getEffectiveState(api)
+  const state = await getEffectiveState(api, opts.project ? { project: basename(process.cwd()) } : undefined)
   const backend: Backend = opts.backend ?? 'claude'
   const config = getBackendConfig(backend, { local: opts.project })
 

package/src/upgrade.ts

@@ -88,14 +88,10 @@ export async function upgradeServerBinary(): Promise<ServerResult> {
   const { getInstalledServerVersion } = await import('./version-check.js')
   const installedVersion = (await getInstalledServerVersion()) ?? 'unknown'
 
-  // Stop server if running before replacing binary
+  // upgradeServer() stops the server internally before replacing the binary
   const s = await daemonStatus()
   const wasRunning = s.running
 
-  if (wasRunning) {
-    await stop()
-  }
-
   const result = await upgradeServer()
 
   if (result.alreadyLatest) {