brainctl 0.1.0

package/dist/executor/codex.d.ts

@@ -0,0 +1,5 @@
+import type { Executor, ExecutorRunOptions, ExecutorResult } from './types.js';
+export declare class CodexExecutor implements Executor {
+    readonly agent: "codex";
+    run(context: string, options?: ExecutorRunOptions): Promise<ExecutorResult>;
+}

package/dist/executor/codex.js

@@ -0,0 +1,12 @@
+import { runAgentProcess } from './process.js';
+export class CodexExecutor {
+    agent = 'codex';
+    async run(context, options) {
+        return await runAgentProcess({
+            command: 'codex',
+            agent: this.agent,
+            context,
+            runOptions: options
+        });
+    }
+}

package/dist/executor/process.d.ts

@@ -0,0 +1,10 @@
+import type { AgentName } from '../types.js';
+import type { ExecutorResult, ExecutorRunOptions } from './types.js';
+interface RunAgentProcessOptions {
+    command: string;
+    agent: AgentName;
+    context: string;
+    runOptions?: ExecutorRunOptions;
+}
+export declare function runAgentProcess(options: RunAgentProcessOptions): Promise<ExecutorResult>;
+export {};

package/dist/executor/process.js

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process';
+import { ExecutionError } from '../errors.js';
+export async function runAgentProcess(options) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(options.command, [], {
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        let output = '';
+        child.stdout.on('data', (chunk) => {
+            const text = chunk.toString();
+            output += text;
+            if (options.runOptions?.streamOutput !== false) {
+                process.stdout.write(chunk);
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            const text = chunk.toString();
+            output += text;
+            if (options.runOptions?.streamOutput !== false) {
+                process.stderr.write(chunk);
+            }
+        });
+        child.on('error', (error) => {
+            reject(new ExecutionError(`Failed to start ${options.agent}: ${error.message}`));
+        });
+        child.on('close', (code) => {
+            resolve({
+                output,
+                exitCode: code ?? 1,
+                agent: options.agent
+            });
+        });
+        child.stdin.on('error', () => {
+            // Ignore broken-pipe behavior if the child exits before stdin completes.
+        });
+        child.stdin.end(options.context);
+    });
+}

package/dist/executor/resolver.d.ts

@@ -0,0 +1,13 @@
+import type { AgentName } from '../types.js';
+import type { Executor } from './types.js';
+export interface AgentAvailability {
+    agent: AgentName;
+    available: boolean;
+    command: string;
+    resolvedPath?: string;
+}
+export interface ExecutorResolver {
+    resolveExecutor(agentName: AgentName): Promise<Executor>;
+    getAgentAvailability(): Promise<Record<AgentName, AgentAvailability>>;
+}
+export declare function createExecutorResolver(): ExecutorResolver;

package/dist/executor/resolver.js

@@ -0,0 +1,94 @@
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+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 AGENT_COMMANDS = {
+    claude: 'claude',
+    codex: 'codex'
+};
+class DefaultExecutorResolver {
+    availabilityCache = new Map();
+    executorCache = new Map();
+    async resolveExecutor(agentName) {
+        const availability = await this.getAvailabilityForAgent(agentName);
+        if (!availability.available) {
+            throw new AgentNotAvailableError(`Agent "${agentName}" is not available on PATH.`);
+        }
+        if (!this.executorCache.has(agentName)) {
+            this.executorCache.set(agentName, createExecutor(agentName));
+        }
+        return this.executorCache.get(agentName);
+    }
+    async getAgentAvailability() {
+        const checks = await Promise.all(SUPPORTED_AGENTS.map(async (agentName) => [
+            agentName,
+            await this.getAvailabilityForAgent(agentName)
+        ]));
+        return Object.fromEntries(checks);
+    }
+    async getAvailabilityForAgent(agentName) {
+        if (!this.availabilityCache.has(agentName)) {
+            this.availabilityCache.set(agentName, checkAvailability(agentName));
+        }
+        return await this.availabilityCache.get(agentName);
+    }
+}
+export function createExecutorResolver() {
+    return new DefaultExecutorResolver();
+}
+function createExecutor(agentName) {
+    switch (agentName) {
+        case 'claude':
+            return new ClaudeExecutor();
+        case 'codex':
+            return new CodexExecutor();
+    }
+}
+async function checkAvailability(agentName) {
+    const command = AGENT_COMMANDS[agentName];
+    const resolvedPath = await findExecutable(command);
+    return {
+        agent: agentName,
+        command,
+        available: resolvedPath !== null,
+        resolvedPath: resolvedPath ?? undefined
+    };
+}
+async function findExecutable(command) {
+    if (command.includes(path.sep)) {
+        return (await isExecutable(command)) ? command : null;
+    }
+    const pathEntries = (process.env.PATH ?? '')
+        .split(path.delimiter)
+        .filter((entry) => entry.length > 0);
+    const extensions = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM')
+            .split(';')
+            .filter((entry) => entry.length > 0)
+        : [''];
+    for (const pathEntry of pathEntries) {
+        for (const extension of extensions) {
+            const candidate = process.platform === 'win32' &&
+                extension.length > 0 &&
+                !command.toLowerCase().endsWith(extension.toLowerCase())
+                ? path.join(pathEntry, `${command}${extension}`)
+                : path.join(pathEntry, command);
+            if (await isExecutable(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+async function isExecutable(filePath) {
+    try {
+        await access(filePath, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/executor/types.d.ts

@@ -0,0 +1,13 @@
+import type { AgentName } from '../types.js';
+export interface ExecutorRunOptions {
+    streamOutput?: boolean;
+}
+export interface ExecutorResult {
+    output: string;
+    exitCode: number;
+    agent: AgentName;
+}
+export interface Executor {
+    readonly agent: AgentName;
+    run(context: string, options?: ExecutorRunOptions): Promise<ExecutorResult>;
+}

package/dist/executor/types.js

@@ -0,0 +1 @@
+export {};

package/dist/output.d.ts

@@ -0,0 +1,4 @@
+import type { DiagnosticStatus } from './types.js';
+export declare function printError(error: unknown): void;
+export declare function formatError(error: unknown): string;
+export declare function formatDiagnosticStatus(status: DiagnosticStatus): string;

package/dist/output.js

@@ -0,0 +1,25 @@
+import pc from 'picocolors';
+import { BrainctlError } from './errors.js';
+export function printError(error) {
+    console.error(formatError(error));
+}
+export function formatError(error) {
+    if (error instanceof BrainctlError) {
+        const prefix = error.category === 'user' ? 'Error' : 'System error';
+        return pc.red(`${prefix}: ${error.message}`);
+    }
+    if (error instanceof Error) {
+        return pc.red(`System error: ${error.message}`);
+    }
+    return pc.red('System error: An unknown failure occurred.');
+}
+export function formatDiagnosticStatus(status) {
+    switch (status) {
+        case 'ok':
+            return pc.green('OK');
+        case 'warn':
+            return pc.yellow('WARN');
+        case 'error':
+            return pc.red('ERROR');
+    }
+}

package/dist/services/doctor-service.d.ts

@@ -0,0 +1,14 @@
+import type { ExecutorResolver } from '../executor/resolver.js';
+import type { DiagnosticCheck } from '../types.js';
+export interface DoctorResult {
+    checks: DiagnosticCheck[];
+    hasIssues: boolean;
+}
+export interface DoctorService {
+    execute(options?: {
+        cwd?: string;
+    }): Promise<DoctorResult>;
+}
+export declare function createDoctorService(dependencies?: {
+    resolver?: ExecutorResolver;
+}): DoctorService;

package/dist/services/doctor-service.js

@@ -0,0 +1,79 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { loadConfig } from '../config.js';
+import { createExecutorResolver } from '../executor/resolver.js';
+export function createDoctorService(dependencies = {}) {
+    const resolver = dependencies.resolver ?? createExecutorResolver();
+    return {
+        async execute(options = {}) {
+            const cwd = options.cwd ?? process.cwd();
+            const checks = [];
+            const configPath = path.join(cwd, 'ai-stack.yaml');
+            const configExists = await pathExists(configPath);
+            if (!configExists) {
+                checks.push({
+                    label: 'Config',
+                    status: 'error',
+                    message: 'ai-stack.yaml was not found.'
+                });
+            }
+            if (configExists) {
+                try {
+                    const config = await loadConfig({ cwd });
+                    checks.push({
+                        label: 'Config',
+                        status: 'ok',
+                        message: `Loaded ${config.configPath}`
+                    });
+                    for (const memoryPath of config.memory.paths) {
+                        const exists = await pathExists(memoryPath);
+                        checks.push({
+                            label: 'Memory',
+                            status: exists ? 'ok' : 'error',
+                            message: exists
+                                ? `Memory path is available: ${memoryPath}`
+                                : `Memory path is missing: ${memoryPath}`
+                        });
+                    }
+                    checks.push({
+                        label: 'Skills',
+                        status: Object.keys(config.skills).length > 0 ? 'ok' : 'error',
+                        message: Object.keys(config.skills).length > 0
+                            ? `${Object.keys(config.skills).length} skills configured`
+                            : 'No skills are configured.'
+                    });
+                }
+                catch (error) {
+                    checks.push({
+                        label: 'Config',
+                        status: 'error',
+                        message: error instanceof Error ? error.message : 'Config validation failed.'
+                    });
+                }
+            }
+            const availability = await resolver.getAgentAvailability();
+            for (const agent of Object.values(availability)) {
+                checks.push({
+                    label: 'Agent',
+                    status: agent.available ? 'ok' : 'warn',
+                    message: agent.available
+                        ? `${agent.agent} is available`
+                        : `${agent.agent} is not available on PATH`
+                });
+            }
+            return {
+                checks,
+                hasIssues: checks.some((check) => check.status !== 'ok')
+            };
+        }
+    };
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/services/init-service.d.ts

@@ -0,0 +1,14 @@
+export interface InitServiceRequest {
+    cwd?: string;
+    force?: boolean;
+}
+export interface InitServiceResult {
+    created: string[];
+    replaced: string[];
+    skipped: string[];
+    alreadyInitialized: boolean;
+}
+export interface InitService {
+    execute(request?: InitServiceRequest): Promise<InitServiceResult>;
+}
+export declare function createInitService(): InitService;

package/dist/services/init-service.js

@@ -0,0 +1,88 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const SAMPLE_CONFIG = `memory:
+  paths:
+    - ./memory
+
+skills:
+  summarize:
+    description: Summarize content
+    prompt: |
+      Summarize the following content into concise bullet points.
+
+  analyze:
+    description: Analyze content deeply
+    prompt: |
+      Analyze the following content and extract key insights.
+
+mcps: {}
+`;
+const SAMPLE_MEMORY = `# Team Notes
+
+- Track important project context here.
+- Keep prompts and references concise.
+`;
+export function createInitService() {
+    return {
+        async execute(request = {}) {
+            const cwd = request.cwd ?? process.cwd();
+            const force = request.force ?? false;
+            const configPath = path.join(cwd, 'ai-stack.yaml');
+            const memoryDir = path.join(cwd, 'memory');
+            const notesPath = path.join(memoryDir, 'notes.md');
+            const created = [];
+            const replaced = [];
+            const skipped = [];
+            await writeManagedFile({
+                targetPath: configPath,
+                content: SAMPLE_CONFIG,
+                force,
+                created,
+                replaced,
+                skipped
+            });
+            const memoryDirExists = await pathExists(memoryDir);
+            if (!memoryDirExists) {
+                await mkdir(memoryDir, { recursive: true });
+                created.push(memoryDir);
+            }
+            await writeManagedFile({
+                targetPath: notesPath,
+                content: SAMPLE_MEMORY,
+                force,
+                created,
+                replaced,
+                skipped
+            });
+            return {
+                created,
+                replaced,
+                skipped,
+                alreadyInitialized: created.length === 0 && replaced.length === 0
+            };
+        }
+    };
+}
+async function writeManagedFile(options) {
+    const exists = await pathExists(options.targetPath);
+    if (exists && !options.force) {
+        options.skipped.push(options.targetPath);
+        return;
+    }
+    await mkdir(path.dirname(options.targetPath), { recursive: true });
+    await writeFile(options.targetPath, options.content, 'utf8');
+    if (exists) {
+        options.replaced.push(options.targetPath);
+        return;
+    }
+    options.created.push(options.targetPath);
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/services/run-service.d.ts

@@ -0,0 +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>;
+}
+interface RunServiceDependencies {
+    resolver?: ExecutorResolver;
+}
+export declare function createRunService(dependencies?: RunServiceDependencies): RunService;
+export declare function buildExecutionPlan(request: RunRequest): ExecutionStep[];
+export {};

package/dist/services/run-service.js

@@ -0,0 +1,93 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AgentNotAvailableError, InputFileError } from '../errors.js';
+import { loadConfig } from '../config.js';
+import { buildContext } from '../context/builder.js';
+import { loadMemory } from '../context/memory.js';
+import { resolveSkillPrompt } from '../context/skills.js';
+import { createExecutorResolver } from '../executor/resolver.js';
+export function createRunService(dependencies = {}) {
+    const resolver = dependencies.resolver ?? createExecutorResolver();
+    return {
+        async execute(request) {
+            const cwd = request.cwd ?? process.cwd();
+            const config = await loadConfig({ cwd });
+            const memory = await loadMemory({ paths: config.memory.paths });
+            const steps = buildExecutionPlan(request);
+            const results = [];
+            let previousOutput;
+            for (const [stepIndex, step] of steps.entries()) {
+                const input = await resolveInput(step, cwd, previousOutput);
+                const skill = resolveSkillPrompt(config, step.skill);
+                const context = buildContext({
+                    memory: memory.content,
+                    skill,
+                    input
+                });
+                let executor = await resolvePrimaryExecutor(resolver, step);
+                let fallbackUsed = false;
+                if (executor.fallbackRequired) {
+                    fallbackUsed = true;
+                }
+                const result = await executor.instance.run(context, {
+                    streamOutput: true
+                });
+                previousOutput = result.output;
+                results.push({
+                    stepIndex,
+                    requestedAgent: step.primaryAgent,
+                    agent: result.agent,
+                    fallbackUsed,
+                    exitCode: result.exitCode,
+                    output: result.output
+                });
+            }
+            const finalResult = results.at(-1);
+            return {
+                steps: results,
+                finalOutput: finalResult?.output ?? '',
+                finalExitCode: finalResult?.exitCode ?? 0
+            };
+        }
+    };
+}
+export function buildExecutionPlan(request) {
+    return [
+        {
+            skill: request.skill,
+            inputFile: request.inputFile,
+            primaryAgent: request.primaryAgent,
+            fallbackAgent: request.fallbackAgent,
+            usePreviousOutput: false
+        }
+    ];
+}
+async function resolveInput(step, cwd, previousOutput) {
+    if (step.usePreviousOutput && previousOutput !== undefined) {
+        return previousOutput;
+    }
+    const inputPath = path.resolve(cwd, step.inputFile);
+    try {
+        return await readFile(inputPath, 'utf8');
+    }
+    catch (error) {
+        throw new InputFileError(`Could not read input file: ${step.inputFile}`);
+    }
+}
+async function resolvePrimaryExecutor(resolver, step) {
+    try {
+        return {
+            instance: await resolver.resolveExecutor(step.primaryAgent),
+            fallbackRequired: false
+        };
+    }
+    catch (error) {
+        if (!(error instanceof AgentNotAvailableError) || !step.fallbackAgent) {
+            throw error;
+        }
+        return {
+            instance: await resolver.resolveExecutor(step.fallbackAgent),
+            fallbackRequired: true
+        };
+    }
+}

package/dist/services/status-service.d.ts

@@ -0,0 +1,17 @@
+import type { AgentAvailability, ExecutorResolver } from '../executor/resolver.js';
+import type { AgentName, MemoryLoadResult } from '../types.js';
+export interface StatusResult {
+    configPath: string;
+    memory: MemoryLoadResult;
+    skills: string[];
+    mcpCount: number;
+    agents: Record<AgentName, AgentAvailability>;
+}
+export interface StatusService {
+    execute(options?: {
+        cwd?: string;
+    }): Promise<StatusResult>;
+}
+export declare function createStatusService(dependencies?: {
+    resolver?: ExecutorResolver;
+}): StatusService;

package/dist/services/status-service.js

@@ -0,0 +1,21 @@
+import { loadConfig } from '../config.js';
+import { loadMemory } from '../context/memory.js';
+import { createExecutorResolver } from '../executor/resolver.js';
+export function createStatusService(dependencies = {}) {
+    const resolver = dependencies.resolver ?? createExecutorResolver();
+    return {
+        async execute(options = {}) {
+            const cwd = options.cwd ?? process.cwd();
+            const config = await loadConfig({ cwd });
+            const memory = await loadMemory({ paths: config.memory.paths });
+            const agents = await resolver.getAgentAvailability();
+            return {
+                configPath: config.configPath,
+                memory,
+                skills: Object.keys(config.skills).sort((left, right) => left.localeCompare(right)),
+                mcpCount: Object.keys(config.mcps).length,
+                agents
+            };
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export type AgentName = 'claude' | 'codex';
+export type ErrorCategory = 'user' | 'system';
+export type DiagnosticStatus = 'ok' | 'warn' | 'error';
+export interface SkillConfig {
+    description?: string;
+    prompt: string;
+}
+export interface BrainctlConfig {
+    configPath: string;
+    rootDir: string;
+    memory: {
+        paths: string[];
+    };
+    skills: Record<string, SkillConfig>;
+    mcps: Record<string, unknown>;
+}
+export interface MemoryLoadResult {
+    content: string;
+    files: string[];
+    count: number;
+}
+export interface RunRequest {
+    cwd?: string;
+    skill: string;
+    inputFile: string;
+    primaryAgent: AgentName;
+    fallbackAgent?: AgentName;
+}
+export interface ExecutionStep {
+    skill: string;
+    inputFile: string;
+    primaryAgent: AgentName;
+    fallbackAgent?: AgentName;
+    usePreviousOutput?: boolean;
+}
+export interface ExecutionStepResult {
+    stepIndex: number;
+    requestedAgent: AgentName;
+    agent: AgentName;
+    fallbackUsed: boolean;
+    exitCode: number;
+    output: string;
+}
+export interface ExecutionTrace {
+    steps: ExecutionStepResult[];
+    finalOutput: string;
+    finalExitCode: number;
+}
+export interface DiagnosticCheck {
+    label: string;
+    status: DiagnosticStatus;
+    message: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "brainctl",
+  "version": "0.1.0",
+  "description": "CLI environment manager for consistent AI workflows",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rorogogogo/brainctl.git"
+  },
+  "homepage": "https://github.com/Rorogogogo/brainctl#readme",
+  "bugs": {
+    "url": "https://github.com/Rorogogogo/brainctl/issues"
+  },
+  "bin": {
+    "brainctl": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm test && npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.1",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}