brainctl 0.1.2 → 0.1.4

package/dist/cli.d.ts

@@ -2,13 +2,17 @@
 import { Command } from 'commander';
 import { type DoctorService } from './services/doctor-service.js';
 import { type InitService } from './services/init-service.js';
+import { type ProfileService } from './services/profile-service.js';
 import { type RunService } from './services/run-service.js';
 import { type StatusService } from './services/status-service.js';
+import { type SyncService } from './services/sync-service.js';
 export interface CliServices {
     initService: InitService;
     runService: RunService;
     statusService: StatusService;
     doctorService: DoctorService;
+    profileService: ProfileService;
+    syncService: SyncService;
 }
 export declare function createProgram(overrides?: Partial<CliServices>): Command;
 export declare function main(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -1,29 +1,40 @@
 #!/usr/bin/env node
-import { realpathSync } from 'node:fs';
+import { realpathSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerInitCommand } from './commands/init.js';
+import { registerMcpCommand } from './commands/mcp.js';
+import { registerProfileCommand } from './commands/profile.js';
 import { registerRunCommand } from './commands/run.js';
 import { registerStatusCommand } from './commands/status.js';
+import { registerSyncCommand } from './commands/sync.js';
+import { registerUiCommand } from './commands/ui.js';
 import { printError } from './output.js';
 import { createDoctorService } from './services/doctor-service.js';
 import { createInitService } from './services/init-service.js';
+import { createProfileService } from './services/profile-service.js';
 import { createRunService } from './services/run-service.js';
 import { createStatusService } from './services/status-service.js';
+import { createSyncService } from './services/sync-service.js';
 import { createExecutorResolver } from './executor/resolver.js';
+const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export function createProgram(overrides = {}) {
     const services = createDefaultServices(overrides);
     const program = new Command();
     program
         .name('brainctl')
         .description('Manage repeatable AI environments for local agent workflows')
-        .version('0.1.0');
+        .version(packageVersion.version);
     registerInitCommand(program, services.initService);
     registerStatusCommand(program, services.statusService);
     registerRunCommand(program, services.runService);
     registerDoctorCommand(program, services.doctorService);
+    registerProfileCommand(program, services.profileService);
+    registerSyncCommand(program, services.syncService);
+    registerUiCommand(program);
+    registerMcpCommand(program);
     return program;
 }
 export async function main(argv = process.argv) {
@@ -44,11 +55,14 @@ export function shouldRunMain(entryPointPath, moduleUrl) {
 }
 function createDefaultServices(overrides) {
     const resolver = createExecutorResolver();
+    const profileService = createProfileService();
     return {
         initService: createInitService(),
         runService: createRunService({ resolver }),
         statusService: createStatusService({ resolver }),
         doctorService: createDoctorService({ resolver }),
+        profileService,
+        syncService: createSyncService({ profileService }),
         ...overrides
     };
 }

package/dist/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerMcpCommand(program: Command): void;

package/dist/commands/mcp.js

@@ -0,0 +1,9 @@
+import { startMcpServer } from '../mcp/server.js';
+export function registerMcpCommand(program) {
+    program
+        .command('mcp')
+        .description('Start the brainctl MCP server (stdio transport)')
+        .action(async () => {
+        await startMcpServer({ cwd: process.cwd() });
+    });
+}

package/dist/commands/profile.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { ProfileService } from '../services/profile-service.js';
+export declare function registerProfileCommand(program: Command, profileService: ProfileService): void;

package/dist/commands/profile.js

@@ -0,0 +1,43 @@
+import pc from 'picocolors';
+export function registerProfileCommand(program, profileService) {
+    const profileCmd = program
+        .command('profile')
+        .description('Manage brainctl profiles');
+    profileCmd
+        .command('list')
+        .description('List available profiles')
+        .action(async () => {
+        const { profiles, activeProfile } = await profileService.list({ cwd: process.cwd() });
+        if (profiles.length === 0) {
+            console.log('No profiles found. Run "brainctl profile create <name>" to create one.');
+            return;
+        }
+        console.log(pc.bold('Profiles:'));
+        for (const name of profiles) {
+            const marker = name === activeProfile ? pc.green(' (active)') : '';
+            console.log(`  ${name}${marker}`);
+        }
+    });
+    profileCmd
+        .command('create')
+        .argument('<name>', 'Profile name')
+        .option('-d, --description <text>', 'Profile description')
+        .description('Create a new profile')
+        .action(async (name, options) => {
+        const result = await profileService.create({
+            cwd: process.cwd(),
+            name,
+            description: options.description,
+        });
+        console.log(`Created profile at ${result.profilePath}`);
+    });
+    profileCmd
+        .command('use')
+        .argument('<name>', 'Profile name to activate')
+        .description('Switch the active profile')
+        .action(async (name) => {
+        const result = await profileService.use({ cwd: process.cwd(), name });
+        const prev = result.previousProfile ? ` (was "${result.previousProfile}")` : '';
+        console.log(`Switched to profile "${name}"${prev}`);
+    });
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { SyncService } from '../services/sync-service.js';
+export declare function registerSyncCommand(program: Command, syncService: SyncService): void;

package/dist/commands/sync.js

@@ -0,0 +1,31 @@
+import pc from 'picocolors';
+export function registerSyncCommand(program, syncService) {
+    program
+        .command('sync')
+        .description('Sync active profile to agent configs')
+        .option('--restore', 'Restore agent configs from most recent backup')
+        .action(async (options) => {
+        const results = await syncService.execute({
+            cwd: process.cwd(),
+            restore: options.restore,
+        });
+        if (results.length === 0) {
+            console.log('No agents to sync.');
+            return;
+        }
+        if (options.restore) {
+            console.log(pc.bold('Restored agent configs:'));
+            for (const result of results) {
+                console.log(`  ${result.agent}: restored from ${result.configPath}`);
+            }
+            return;
+        }
+        console.log(pc.bold('Synced profile to agents:'));
+        for (const result of results) {
+            console.log(`  ${result.agent}: ${result.configPath} (${result.mcpCount} MCPs)`);
+            if (result.backedUpTo) {
+                console.log(`    backed up to ${result.backedUpTo}`);
+            }
+        }
+    });
+}

package/dist/commands/ui.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerUiCommand(program: Command): void;

package/dist/commands/ui.js

@@ -0,0 +1,10 @@
+import { startUiServer } from '../ui/server.js';
+export function registerUiCommand(program) {
+    program
+        .command('ui')
+        .description('Start the local brainctl dashboard')
+        .action(async () => {
+        const server = await startUiServer({ cwd: process.cwd() });
+        console.log(`brainctl UI listening at ${server.url}`);
+    });
+}

package/dist/config.d.ts

@@ -1,6 +1,14 @@
-import type { BrainctlConfig } from './types.js';
+import type { BrainctlConfig, SkillConfig } from './types.js';
 interface LoadConfigOptions {
     cwd?: string;
 }
+export interface ConfigPayload {
+    memory: {
+        paths: string[];
+    };
+    skills: Record<string, SkillConfig>;
+    mcps: Record<string, unknown>;
+}
 export declare function loadConfig(options?: LoadConfigOptions): Promise<BrainctlConfig>;
+export declare function parseConfigPayload(value: unknown): ConfigPayload;
 export {};

package/dist/config.js

@@ -14,30 +14,48 @@ export async function loadConfig(options = {}) {
     }
     let parsed;
     try {
-        parsed = (YAML.parse(source) ?? {});
+        parsed = YAML.parse(source) ?? {};
     }
     catch (error) {
         throw new ConfigError('ai-stack.yaml could not be parsed.');
     }
+    const config = parseConfigPayload(parsed);
+    return {
+        configPath,
+        rootDir: cwd,
+        memory: {
+            paths: config.memory.paths.map((memoryPath) => {
+                if (typeof memoryPath !== 'string' || memoryPath.trim().length === 0) {
+                    throw new ConfigError('ai-stack.yaml contains an invalid memory path.');
+                }
+                return path.resolve(cwd, memoryPath);
+            })
+        },
+        skills: config.skills,
+        mcps: config.mcps
+    };
+}
+export function parseConfigPayload(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ConfigError('ai-stack.yaml is missing the required "memory.paths" section.');
+    }
+    const parsed = value;
     if (!parsed.memory || !Array.isArray(parsed.memory.paths)) {
         throw new ConfigError('ai-stack.yaml is missing the required "memory.paths" section.');
     }
     if (!parsed.skills || typeof parsed.skills !== 'object' || Array.isArray(parsed.skills)) {
         throw new ConfigError('ai-stack.yaml is missing the required "skills" section.');
     }
-    const skills = normalizeSkills(parsed.skills);
     return {
-        configPath,
-        rootDir: cwd,
         memory: {
             paths: parsed.memory.paths.map((memoryPath) => {
                 if (typeof memoryPath !== 'string' || memoryPath.trim().length === 0) {
                     throw new ConfigError('ai-stack.yaml contains an invalid memory path.');
                 }
-                return path.resolve(cwd, memoryPath);
+                return memoryPath;
             })
         },
-        skills,
+        skills: normalizeSkills(parsed.skills),
         mcps: normalizeMcps(parsed.mcps)
     };
 }

package/dist/context/memory.js

@@ -5,11 +5,16 @@ export async function loadMemory(options) {
     const markdownFiles = (await Promise.all(options.paths.map(async (memoryPath) => collectMarkdownFiles(memoryPath))))
         .flat()
         .sort((left, right) => left.localeCompare(right));
-    const contents = await Promise.all(markdownFiles.map(async (filePath) => (await readFile(filePath, 'utf8')).trim()));
+    const entries = await Promise.all(markdownFiles.map(async (filePath) => ({
+        path: filePath,
+        content: await readFile(filePath, 'utf8')
+    })));
+    const contents = entries.map((entry) => entry.content.trim());
     return {
         files: markdownFiles,
         count: markdownFiles.length,
-        content: contents.filter((entry) => entry.length > 0).join('\n\n')
+        content: contents.filter((entry) => entry.length > 0).join('\n\n'),
+        entries
     };
 }
 async function collectMarkdownFiles(targetPath) {

package/dist/errors.d.ts

@@ -25,3 +25,12 @@ export declare class AgentNotAvailableError extends BrainctlError {
 export declare class ExecutionError extends BrainctlError {
     constructor(message: string);
 }
+export declare class ProfileError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class ProfileNotFoundError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class SyncError extends BrainctlError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -43,3 +43,18 @@ export class ExecutionError extends BrainctlError {
         super(message, 'system', 'EXECUTION_ERROR');
     }
 }
+export class ProfileError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'PROFILE_ERROR');
+    }
+}
+export class ProfileNotFoundError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'PROFILE_NOT_FOUND');
+    }
+}
+export class SyncError extends BrainctlError {
+    constructor(message) {
+        super(message, 'system', 'SYNC_ERROR');
+    }
+}

package/dist/executor/process.js

@@ -9,6 +9,7 @@ export async function runAgentProcess(options) {
         child.stdout.on('data', (chunk) => {
             const text = chunk.toString();
             output += text;
+            options.runOptions?.onOutputChunk?.(text);
             if (options.runOptions?.streamOutput !== false) {
                 process.stdout.write(chunk);
             }
@@ -16,6 +17,7 @@ export async function runAgentProcess(options) {
         child.stderr.on('data', (chunk) => {
             const text = chunk.toString();
             output += text;
+            options.runOptions?.onOutputChunk?.(text);
             if (options.runOptions?.streamOutput !== false) {
                 process.stderr.write(chunk);
             }

package/dist/executor/resolver.js

@@ -4,10 +4,11 @@ import path from 'node:path';
 import { AgentNotAvailableError } from '../errors.js';
 import { ClaudeExecutor } from './claude.js';
 import { CodexExecutor } from './codex.js';
-const SUPPORTED_AGENTS = ['claude', 'codex'];
+const SUPPORTED_AGENTS = ['claude', 'codex', 'gemini'];
 const AGENT_COMMANDS = {
     claude: 'claude',
-    codex: 'codex'
+    codex: 'codex',
+    gemini: 'gemini'
 };
 class DefaultExecutorResolver {
     availabilityCache = new Map();
@@ -45,6 +46,8 @@ function createExecutor(agentName) {
             return new ClaudeExecutor();
         case 'codex':
             return new CodexExecutor();
+        default:
+            throw new AgentNotAvailableError(`Agent "${agentName}" does not have an executor implementation.`);
     }
 }
 async function checkAvailability(agentName) {

package/dist/executor/types.d.ts

@@ -1,6 +1,7 @@
 import type { AgentName } from '../types.js';
 export interface ExecutorRunOptions {
     streamOutput?: boolean;
+    onOutputChunk?: (chunk: string) => void;
 }
 export interface ExecutorResult {
     output: string;

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+import { FastMCP } from 'fastmcp';
+export declare function createMcpServer(options?: {
+    cwd?: string;
+}): FastMCP;
+export declare function startMcpServer(options?: {
+    cwd?: string;
+}): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,183 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { loadConfig } from '../config.js';
+import { loadMemory } from '../context/memory.js';
+import { createDoctorService } from '../services/doctor-service.js';
+import { createMemoryWriteService } from '../services/memory-write-service.js';
+import { createProfileService } from '../services/profile-service.js';
+import { createRunService } from '../services/run-service.js';
+import { createStatusService } from '../services/status-service.js';
+import { createSyncService } from '../services/sync-service.js';
+const packageVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+export function createMcpServer(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const server = new FastMCP({
+        name: 'brainctl',
+        version: packageVersion.version,
+    });
+    server.addTool({
+        name: 'brainctl_list_skills',
+        description: 'List available skills from the ai-stack.yaml config',
+        parameters: z.object({}),
+        execute: async () => {
+            const config = await loadConfig({ cwd });
+            const skills = Object.entries(config.skills).map(([name, skill]) => ({
+                name,
+                description: skill.description ?? null,
+            }));
+            return JSON.stringify(skills, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_run',
+        description: 'Execute a skill with input text. Runs the skill through the configured agent and returns the output.',
+        parameters: z.object({
+            skill: z.string().describe('Skill name as defined in ai-stack.yaml'),
+            input: z.string().describe('Input text to pass to the skill'),
+            agent: z.enum(['claude', 'codex']).default('claude').describe('Agent to use for execution'),
+            fallback_agent: z.enum(['claude', 'codex']).optional().describe('Fallback agent if primary is unavailable'),
+        }),
+        execute: async (args) => {
+            const inputPath = path.join(cwd, `.brainctl-mcp-input-${Date.now()}.tmp`);
+            const { writeFile: writeFileAsync, unlink } = await import('node:fs/promises');
+            try {
+                await writeFileAsync(inputPath, args.input, 'utf8');
+                const runService = createRunService();
+                const trace = await runService.execute({
+                    cwd,
+                    skill: args.skill,
+                    inputFile: path.basename(inputPath),
+                    primaryAgent: args.agent,
+                    fallbackAgent: args.fallback_agent,
+                });
+                return trace.finalOutput;
+            }
+            finally {
+                try {
+                    await unlink(inputPath);
+                }
+                catch {
+                    // temp file cleanup is best-effort
+                }
+            }
+        },
+    });
+    server.addTool({
+        name: 'brainctl_status',
+        description: 'Show project status: config path, memory files, available skills, and agent availability',
+        parameters: z.object({}),
+        execute: async () => {
+            const statusService = createStatusService();
+            const result = await statusService.execute({ cwd });
+            return JSON.stringify(result, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_doctor',
+        description: 'Run health checks on the brainctl setup: config validity, memory paths, skill definitions, and agent availability',
+        parameters: z.object({}),
+        execute: async () => {
+            const doctorService = createDoctorService();
+            const result = await doctorService.execute({ cwd });
+            return JSON.stringify(result, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_read_memory',
+        description: 'Read all shared memory files. Returns every markdown file from configured memory paths with file names and content. Use this to understand context left by other agents.',
+        parameters: z.object({}),
+        execute: async () => {
+            const config = await loadConfig({ cwd });
+            const memory = await loadMemory({ paths: config.memory.paths });
+            const result = {
+                count: memory.count,
+                files: memory.entries.map((entry) => ({
+                    path: entry.path,
+                    content: entry.content,
+                })),
+            };
+            return JSON.stringify(result, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_write_memory',
+        description: 'Write or update a shared memory file. Use this to leave notes, decisions, or context for other agents. The file must be within a configured memory path.',
+        parameters: z.object({
+            file_path: z.string().describe('Relative path for the memory file (e.g., "memory/notes.md")'),
+            content: z.string().describe('Markdown content to write'),
+        }),
+        execute: async (args) => {
+            const memoryWriteService = createMemoryWriteService();
+            const result = await memoryWriteService.execute({
+                cwd,
+                filePath: args.file_path,
+                content: args.content,
+            });
+            return JSON.stringify({ written: result.filePath });
+        },
+    });
+    server.addTool({
+        name: 'brainctl_get_skill',
+        description: 'Get the full details of a specific skill including its prompt text and description. Use this to understand what a skill does before running it.',
+        parameters: z.object({
+            skill: z.string().describe('Skill name as defined in ai-stack.yaml'),
+        }),
+        execute: async (args) => {
+            const config = await loadConfig({ cwd });
+            const skillConfig = config.skills[args.skill];
+            if (!skillConfig) {
+                throw new Error(`Skill "${args.skill}" is not defined in ai-stack.yaml.`);
+            }
+            return JSON.stringify({
+                name: args.skill,
+                description: skillConfig.description ?? null,
+                prompt: skillConfig.prompt,
+            }, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_list_profiles',
+        description: 'List available profiles and show which one is active.',
+        parameters: z.object({}),
+        execute: async () => {
+            const profileService = createProfileService();
+            const result = await profileService.list({ cwd });
+            return JSON.stringify(result, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_switch_profile',
+        description: 'Switch the active profile and sync it to all configured agents. Combines profile switch + sync in one step.',
+        parameters: z.object({
+            name: z.string().describe('Profile name to activate'),
+        }),
+        execute: async (args) => {
+            const profileService = createProfileService();
+            const switchResult = await profileService.use({ cwd, name: args.name });
+            const syncService = createSyncService({ profileService });
+            const syncResult = await syncService.execute({ cwd });
+            return JSON.stringify({
+                previousProfile: switchResult.previousProfile,
+                activeProfile: args.name,
+                synced: syncResult,
+            }, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_sync',
+        description: 'Sync the active profile to all configured agent configs (Claude, Codex). Creates backups before overwriting.',
+        parameters: z.object({}),
+        execute: async () => {
+            const syncService = createSyncService();
+            const result = await syncService.execute({ cwd });
+            return JSON.stringify(result, null, 2);
+        },
+    });
+    return server;
+}
+export async function startMcpServer(options = {}) {
+    const server = createMcpServer(options);
+    await server.start({ transportType: 'stdio' });
+}

package/dist/services/config-write-service.d.ts

@@ -0,0 +1,12 @@
+import type { ConfigPayload } from '../config.js';
+export interface ConfigWriteRequest {
+    cwd?: string;
+    config: ConfigPayload;
+}
+export interface ConfigWriteResult {
+    configPath: string;
+}
+export interface ConfigWriteService {
+    execute(request: ConfigWriteRequest): Promise<ConfigWriteResult>;
+}
+export declare function createConfigWriteService(): ConfigWriteService;

package/dist/services/config-write-service.js

@@ -0,0 +1,70 @@
+import { lstat, mkdir, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import { ConfigError } from '../errors.js';
+export function createConfigWriteService() {
+    return {
+        async execute(request) {
+            const cwd = request.cwd ?? process.cwd();
+            const configPath = path.join(cwd, 'ai-stack.yaml');
+            const memoryPaths = await Promise.all(request.config.memory.paths.map((memoryPath) => normalizeMemoryPath(cwd, memoryPath)));
+            const payload = {
+                memory: {
+                    paths: memoryPaths
+                },
+                skills: request.config.skills,
+                mcps: request.config.mcps
+            };
+            await mkdir(path.dirname(configPath), { recursive: true });
+            await writeFile(configPath, `${YAML.stringify(payload)}`, 'utf8');
+            return { configPath };
+        }
+    };
+}
+async function normalizeMemoryPath(cwd, filePath) {
+    const workspaceRoot = await realpath(cwd);
+    const resolvedPath = path.resolve(cwd, filePath);
+    const realTargetPath = await resolvePathForWrite(resolvedPath);
+    if (!isWithinDirectory(workspaceRoot, realTargetPath)) {
+        throw new ConfigError('Memory paths must stay within the workspace root.');
+    }
+    const relativePath = path.relative(cwd, resolvedPath);
+    return relativePath.length > 0 ? relativePath : '.';
+}
+async function resolvePathForWrite(targetPath) {
+    const existingPath = await findNearestExistingPath(targetPath);
+    const resolvedExistingPath = await realpath(existingPath);
+    if (existingPath === targetPath) {
+        return resolvedExistingPath;
+    }
+    return path.resolve(resolvedExistingPath, path.relative(existingPath, targetPath));
+}
+async function findNearestExistingPath(targetPath) {
+    let currentPath = targetPath;
+    while (true) {
+        try {
+            await lstat(currentPath);
+            return currentPath;
+        }
+        catch (error) {
+            if (!isMissingPathError(error)) {
+                throw error;
+            }
+        }
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) {
+            throw new ConfigError(`Could not resolve filesystem path for ${targetPath}.`);
+        }
+        currentPath = parentPath;
+    }
+}
+function isWithinDirectory(parentDirectory, targetPath) {
+    const relativePath = path.relative(parentDirectory, targetPath);
+    if (relativePath === '') {
+        return true;
+    }
+    return !relativePath.startsWith(`..${path.sep}`) && relativePath !== '..' && !path.isAbsolute(relativePath);
+}
+function isMissingPathError(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}

package/dist/services/memory-write-service.d.ts

@@ -0,0 +1,12 @@
+export interface MemoryWriteRequest {
+    cwd?: string;
+    filePath: string;
+    content: string;
+}
+export interface MemoryWriteResult {
+    filePath: string;
+}
+export interface MemoryWriteService {
+    execute(request: MemoryWriteRequest): Promise<MemoryWriteResult>;
+}
+export declare function createMemoryWriteService(): MemoryWriteService;