brainctl 0.1.2 → 0.1.3

package/dist/cli.js

@@ -1,29 +1,34 @@
 #!/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 { registerRunCommand } from './commands/run.js';
 import { registerStatusCommand } from './commands/status.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 { createRunService } from './services/run-service.js';
 import { createStatusService } from './services/status-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);
+    registerUiCommand(program);
+    registerMcpCommand(program);
     return program;
 }
 export async function main(argv = process.argv) {

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/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/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/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,88 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { loadConfig } from '../config.js';
+import { createDoctorService } from '../services/doctor-service.js';
+import { createRunService } from '../services/run-service.js';
+import { createStatusService } from '../services/status-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);
+        },
+    });
+    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;

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

@@ -0,0 +1,56 @@
+import { lstat, mkdir, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { MemoryPathError } from '../errors.js';
+export function createMemoryWriteService() {
+    return {
+        async execute(request) {
+            const cwd = request.cwd ?? process.cwd();
+            const targetPath = path.resolve(cwd, request.filePath);
+            const workspaceRoot = await realpath(cwd);
+            const resolvedTargetPath = await resolvePathForWrite(targetPath);
+            if (!isWithinDirectory(workspaceRoot, resolvedTargetPath)) {
+                throw new MemoryPathError('Memory files must stay within the workspace root.');
+            }
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await writeFile(targetPath, request.content, 'utf8');
+            return { filePath: targetPath };
+        }
+    };
+}
+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 MemoryPathError(`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/run-service.d.ts

@@ -1,7 +1,11 @@
 import type { ExecutorResolver } from '../executor/resolver.js';
 import type { ExecutionStep, ExecutionTrace, RunRequest } from '../types.js';
 export interface RunService {
-    execute(request: RunRequest): Promise<ExecutionTrace>;
+    execute(request: RunRequest, options?: RunServiceExecuteOptions): Promise<ExecutionTrace>;
+}
+export interface RunServiceExecuteOptions {
+    onOutputChunk?: (chunk: string) => void;
+    streamOutput?: boolean;
 }
 interface RunServiceDependencies {
     resolver?: ExecutorResolver;

package/dist/services/run-service.js

@@ -9,7 +9,7 @@ import { createExecutorResolver } from '../executor/resolver.js';
 export function createRunService(dependencies = {}) {
     const resolver = dependencies.resolver ?? createExecutorResolver();
     return {
-        async execute(request) {
+        async execute(request, options = {}) {
             const cwd = request.cwd ?? process.cwd();
             const config = await loadConfig({ cwd });
             const memory = await loadMemory({ paths: config.memory.paths });
@@ -30,7 +30,8 @@ export function createRunService(dependencies = {}) {
                     fallbackUsed = true;
                 }
                 const result = await executor.instance.run(context, {
-                    streamOutput: true
+                    streamOutput: options.streamOutput ?? true,
+                    onOutputChunk: options.onOutputChunk
                 });
                 previousOutput = result.output;
                 results.push({

package/dist/types.d.ts

@@ -18,6 +18,10 @@ export interface MemoryLoadResult {
     content: string;
     files: string[];
     count: number;
+    entries: Array<{
+        path: string;
+        content: string;
+    }>;
 }
 export interface RunRequest {
     cwd?: string;

package/dist/ui/routes.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { RunService } from '../services/run-service.js';
+import type { StatusService } from '../services/status-service.js';
+export interface UiRouteDependencies {
+    cwd: string;
+    statusService?: StatusService;
+    runService?: RunService;
+}
+export type UiRouteHandler = (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+export declare function createUiRouteHandler(dependencies: UiRouteDependencies): UiRouteHandler;