expxagents 0.1.0

package/dist/cli/src/commands/server.js

@@ -0,0 +1,22 @@
+import { spawn } from 'child_process';
+import path from 'path';
+export async function serverCommand() {
+    const cwd = process.cwd();
+    const serverDir = path.join(cwd, 'server');
+    console.log('Starting ExpxAgents server...');
+    const child = spawn('node', ['dist/index.js'], {
+        cwd: serverDir,
+        stdio: 'inherit',
+        env: { ...process.env },
+    });
+    child.on('error', (err) => {
+        console.error(`Failed to start server: ${err.message}`);
+        console.error('Make sure you have built the server: cd server && npm run build');
+        process.exit(1);
+    });
+    child.on('exit', (code) => {
+        process.exit(code ?? 0);
+    });
+    process.on('SIGINT', () => child.kill('SIGINT'));
+    process.on('SIGTERM', () => child.kill('SIGTERM'));
+}

package/dist/cli/src/commands/stop.d.ts

@@ -0,0 +1 @@
+export declare function stopCommand(name: string): Promise<void>;

package/dist/cli/src/commands/stop.js

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import path from 'path';
+import { readState, writeState, setSquadStatus } from '../../../core/state-manager.js';
+export async function stopCommand(name) {
+    const cwd = process.cwd();
+    const squadDir = path.join(cwd, 'squads', name);
+    if (!fs.existsSync(squadDir)) {
+        console.error(`Squad "${name}" not found.`);
+        process.exit(1);
+    }
+    const state = readState(squadDir);
+    if (!state) {
+        console.log(`Squad "${name}" is not running (no state.json).`);
+        return;
+    }
+    if (state.status === 'idle' || state.status === 'completed') {
+        console.log(`Squad "${name}" is already ${state.status}.`);
+        return;
+    }
+    const updated = setSquadStatus(state, 'idle');
+    writeState(squadDir, updated);
+    console.log(`Squad "${name}" stopped.`);
+}

package/dist/cli/src/commands/uninstall.d.ts

@@ -0,0 +1 @@
+export declare function uninstallCommand(skill: string): Promise<void>;

package/dist/cli/src/commands/uninstall.js

@@ -0,0 +1,12 @@
+import fs from 'fs';
+import path from 'path';
+export async function uninstallCommand(skill) {
+    const cwd = process.cwd();
+    const skillDir = path.join(cwd, 'skills', skill);
+    if (!fs.existsSync(skillDir)) {
+        console.error(`Skill "${skill}" is not installed.`);
+        process.exit(1);
+    }
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    console.log(`Skill "${skill}" uninstalled.`);
+}

package/dist/cli/src/index.d.ts

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

package/dist/cli/src/index.js

@@ -0,0 +1,57 @@
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { createCommand } from './commands/create.js';
+import { runCommand } from './commands/run.js';
+import { stopCommand } from './commands/stop.js';
+import { listCommand } from './commands/list.js';
+import { installCommand } from './commands/install.js';
+import { uninstallCommand } from './commands/uninstall.js';
+import { serverCommand } from './commands/server.js';
+import { doctorCommand } from './commands/doctor.js';
+import { onboardingCommand } from './commands/onboarding.js';
+const program = new Command();
+program
+    .name('expxagents')
+    .description('ExpxAgents — Multi-agent orchestration platform')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Initialize project (dirs, .env, admin user)')
+    .action(initCommand);
+program
+    .command('create [description]')
+    .description('Create a new squad with Solution Architect')
+    .action(createCommand);
+program
+    .command('run <name>')
+    .description('Execute squad pipeline')
+    .action(runCommand);
+program
+    .command('stop <name>')
+    .description('Stop running squad')
+    .action(stopCommand);
+program
+    .command('list')
+    .description('List squads and skills')
+    .action(listCommand);
+program
+    .command('install <skill>')
+    .description('Install skill from registry')
+    .action(installCommand);
+program
+    .command('uninstall <skill>')
+    .description('Remove skill')
+    .action(uninstallCommand);
+program
+    .command('server')
+    .description('Start the web server')
+    .action(serverCommand);
+program
+    .command('doctor')
+    .description('Run system diagnostics and health checks')
+    .action(doctorCommand);
+program
+    .command('onboarding')
+    .description('Configure company profile and preferences')
+    .action(onboardingCommand);
+program.parse();

package/dist/cli/src/utils/config.d.ts

@@ -0,0 +1,34 @@
+export interface CliConfig {
+    projectRoot: string;
+    squadsDir: string;
+    skillsDir: string;
+    coreDir: string;
+    serverDir: string;
+}
+/**
+ * Resolve project directories relative to CWD.
+ */
+export declare function resolveConfig(): CliConfig;
+/**
+ * Check if current directory is an initialized ExpxAgents project.
+ */
+export declare function isInitialized(): boolean;
+/**
+ * Get the directory where package assets are stored.
+ * Resolves to <package-root>/assets/ regardless of compiled file nesting.
+ * Works both in development (monorepo) and production (npx/global install).
+ */
+export declare function getAssetsDir(): string;
+/**
+ * Resolve a core asset path (solution-architect, runner, best-practices, etc).
+ * Falls back to monorepo path for development.
+ */
+export declare function getCoreAsset(relativePath: string): string;
+/**
+ * Resolve the agent catalog directory.
+ */
+export declare function getAgentCatalogDir(): string;
+/**
+ * Resolve the templates directory.
+ */
+export declare function getTemplateDir(): string;

package/dist/cli/src/utils/config.js

@@ -0,0 +1,79 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Resolve project directories relative to CWD.
+ */
+export function resolveConfig() {
+    const projectRoot = process.cwd();
+    return {
+        projectRoot,
+        squadsDir: path.join(projectRoot, 'squads'),
+        skillsDir: path.join(projectRoot, 'skills'),
+        coreDir: path.join(projectRoot, 'core'),
+        serverDir: path.join(projectRoot, 'server'),
+    };
+}
+/**
+ * Check if current directory is an initialized ExpxAgents project.
+ */
+export function isInitialized() {
+    const cwd = process.cwd();
+    return fs.existsSync(path.join(cwd, 'squads'))
+        && fs.existsSync(path.join(cwd, '_expxagents', '_memory'));
+}
+/**
+ * Find the package root by walking up from the compiled file's location
+ * until we find a package.json. Works regardless of dist/ nesting depth.
+ */
+function findPackageRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'package.json')))
+            return dir;
+        dir = path.dirname(dir);
+    }
+    throw new Error('Could not find expxagents package root');
+}
+/**
+ * Get the directory where package assets are stored.
+ * Resolves to <package-root>/assets/ regardless of compiled file nesting.
+ * Works both in development (monorepo) and production (npx/global install).
+ */
+export function getAssetsDir() {
+    return path.join(findPackageRoot(), 'assets');
+}
+/**
+ * Resolve a core asset path (solution-architect, runner, best-practices, etc).
+ * Falls back to monorepo path for development.
+ */
+export function getCoreAsset(relativePath) {
+    const assetsPath = path.join(getAssetsDir(), 'core', relativePath);
+    if (fs.existsSync(assetsPath))
+        return assetsPath;
+    // Fallback: monorepo development path
+    const monoPath = path.join(process.cwd(), '_expxagents', 'core', relativePath);
+    if (fs.existsSync(monoPath))
+        return monoPath;
+    return assetsPath;
+}
+/**
+ * Resolve the agent catalog directory.
+ */
+export function getAgentCatalogDir() {
+    const assetsPath = path.join(getAssetsDir(), 'agents');
+    if (fs.existsSync(assetsPath))
+        return assetsPath;
+    const monoPath = path.join(process.cwd(), 'agents');
+    return fs.existsSync(monoPath) ? monoPath : assetsPath;
+}
+/**
+ * Resolve the templates directory.
+ */
+export function getTemplateDir() {
+    const assetsPath = path.join(getAssetsDir(), 'templates');
+    if (fs.existsSync(assetsPath))
+        return assetsPath;
+    const monoPath = path.join(process.cwd(), 'templates');
+    return fs.existsSync(monoPath) ? monoPath : assetsPath;
+}

package/dist/core/skills-loader.d.ts

@@ -0,0 +1,16 @@
+export interface Skill {
+    name: string;
+    type: 'mcp' | 'script' | 'prompt';
+    description: string;
+    server?: string;
+    instructions: string;
+}
+/**
+ * Load a single skill from its directory (expects SKILL.md inside).
+ */
+export declare function loadSkill(skillDir: string): Skill;
+/**
+ * Load all skills from the skills/ directory.
+ * Returns empty array if directory doesn't exist.
+ */
+export declare function loadSkills(skillsDir: string): Skill[];

package/dist/core/skills-loader.js

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Parse SKILL.md frontmatter (YAML between --- delimiters) and body content.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) {
+        throw new Error('SKILL.md must have YAML frontmatter between --- delimiters');
+    }
+    const rawMeta = match[1];
+    const body = match[2].trim();
+    const meta = {};
+    for (const line of rawMeta.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        let value = line.slice(colonIdx + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        meta[key] = value;
+    }
+    return { meta, body };
+}
+/**
+ * Load a single skill from its directory (expects SKILL.md inside).
+ */
+export function loadSkill(skillDir) {
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    const { meta, body } = parseFrontmatter(content);
+    return {
+        name: meta.name,
+        type: meta.type,
+        description: meta.description,
+        server: meta.server || undefined,
+        instructions: body,
+    };
+}
+/**
+ * Load all skills from the skills/ directory.
+ * Returns empty array if directory doesn't exist.
+ */
+export function loadSkills(skillsDir) {
+    if (!fs.existsSync(skillsDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
+        if (!fs.existsSync(skillMdPath))
+            continue;
+        skills.push(loadSkill(path.join(skillsDir, entry.name)));
+    }
+    return skills;
+}

package/dist/core/squad-loader.d.ts

@@ -0,0 +1,26 @@
+export interface AgentConfig {
+    id: string;
+    name: string;
+    icon: string;
+    prompt: string;
+}
+export interface PipelineStep {
+    id: string;
+    agent: string;
+    label: string;
+    deliverFrom?: string;
+}
+export interface SquadConfig {
+    squad: {
+        code: string;
+        name: string;
+        description: string;
+        icon: string;
+        agents: AgentConfig[];
+        skills: string[];
+        pipeline: {
+            steps: PipelineStep[];
+        };
+    };
+}
+export declare function loadSquad(squadDir: string): SquadConfig;

package/dist/core/squad-loader.js

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+export function loadSquad(squadDir) {
+    const yamlPath = path.join(squadDir, 'squad.yaml');
+    if (!fs.existsSync(yamlPath)) {
+        throw new Error(`squad.yaml not found in ${squadDir}`);
+    }
+    const raw = fs.readFileSync(yamlPath, 'utf-8');
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.squad) {
+        throw new Error('Missing required field: squad');
+    }
+    const squad = parsed.squad;
+    const requiredFields = ['code', 'name', 'description', 'icon', 'agents', 'pipeline'];
+    for (const field of requiredFields) {
+        if (squad[field] === undefined || squad[field] === null) {
+            throw new Error(`Missing required field: squad.${field}`);
+        }
+    }
+    const agents = squad.agents;
+    if (!Array.isArray(agents) || agents.length === 0) {
+        throw new Error('Missing required field: squad.agents must be a non-empty array');
+    }
+    const pipeline = squad.pipeline;
+    if (!pipeline || !pipeline.steps) {
+        throw new Error('Missing required field: squad.pipeline.steps');
+    }
+    const steps = pipeline.steps;
+    const agentIds = new Set(agents.map(a => a.id));
+    for (const step of steps) {
+        if (!agentIds.has(step.agent)) {
+            throw new Error(`Agent "${step.agent}" not found in agents list (referenced by step "${step.id}")`);
+        }
+        if (step.deliverFrom && !agentIds.has(step.deliverFrom)) {
+            throw new Error(`deliverFrom agent "${step.deliverFrom}" not found in agents list (referenced by step "${step.id}")`);
+        }
+    }
+    const skills = squad.skills ?? [];
+    return {
+        squad: {
+            code: squad.code,
+            name: squad.name,
+            description: squad.description,
+            icon: squad.icon,
+            agents,
+            skills,
+            pipeline: { steps },
+        },
+    };
+}

package/dist/core/state-manager.d.ts

@@ -0,0 +1,45 @@
+import type { SquadConfig } from './squad-loader.js';
+export type AgentStatus = 'idle' | 'working' | 'delivering' | 'done' | 'checkpoint';
+export type SquadStatus = 'idle' | 'running' | 'completed' | 'checkpoint';
+export interface Agent {
+    id: string;
+    name: string;
+    icon: string;
+    status: AgentStatus;
+    stepIndex: number;
+    stepLabel: string;
+    deliverTo: string | null;
+    desk: {
+        col: number;
+        row: number;
+    };
+    message: string | null;
+}
+export interface Handoff {
+    from: string;
+    to: string;
+    message: string;
+    completedAt: string;
+}
+export interface SquadState {
+    squad: string;
+    status: SquadStatus;
+    step: {
+        current: number;
+        total: number;
+        label: string;
+    };
+    agents: Agent[];
+    handoff: Handoff | null;
+    startedAt: string | null;
+    updatedAt: string;
+}
+/** Delay in ms between 'delivering' and 'done' to allow handoff animation */
+export declare const HANDOFF_DELAY_MS = 2000;
+export declare function createInitialState(config: SquadConfig): SquadState;
+export declare function writeState(squadDir: string, state: SquadState): void;
+export declare function readState(squadDir: string): SquadState | null;
+export declare function updateAgentStatus(state: SquadState, agentId: string, status: AgentStatus): SquadState;
+export declare function updateStep(state: SquadState, current: number, label: string): SquadState;
+export declare function setHandoff(state: SquadState, fromId: string, toId: string, message: string): SquadState;
+export declare function setSquadStatus(state: SquadState, status: SquadStatus): SquadState;

package/dist/core/state-manager.js

@@ -0,0 +1,90 @@
+import fs from 'fs';
+import path from 'path';
+/** Delay in ms between 'delivering' and 'done' to allow handoff animation */
+export const HANDOFF_DELAY_MS = 2000;
+export function createInitialState(config) {
+    const { squad } = config;
+    const agentCount = squad.agents.length;
+    const cols = Math.ceil(Math.sqrt(agentCount));
+    const agents = squad.agents.map((agentConfig, index) => {
+        const col = (index % cols) + 1;
+        const row = Math.floor(index / cols) + 1;
+        const stepIdx = squad.pipeline.steps.findIndex(s => s.agent === agentConfig.id);
+        const step = stepIdx !== -1 ? squad.pipeline.steps[stepIdx] : null;
+        return {
+            id: agentConfig.id,
+            name: agentConfig.name,
+            icon: agentConfig.icon,
+            status: 'idle',
+            stepIndex: stepIdx + 1,
+            stepLabel: step?.label ?? '',
+            deliverTo: null,
+            desk: { col, row },
+            message: null,
+        };
+    });
+    return {
+        squad: squad.code,
+        status: 'idle',
+        step: { current: 0, total: squad.pipeline.steps.length, label: '' },
+        agents,
+        handoff: null,
+        startedAt: null,
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function writeState(squadDir, state) {
+    const statePath = path.join(squadDir, 'state.json');
+    const tmpPath = path.join(squadDir, 'state.json.tmp');
+    const data = JSON.stringify(state, null, 2);
+    fs.writeFileSync(tmpPath, data, 'utf-8');
+    fs.renameSync(tmpPath, statePath);
+}
+export function readState(squadDir) {
+    const statePath = path.join(squadDir, 'state.json');
+    if (!fs.existsSync(statePath)) {
+        return null;
+    }
+    const raw = fs.readFileSync(statePath, 'utf-8');
+    return JSON.parse(raw);
+}
+export function updateAgentStatus(state, agentId, status) {
+    const agentIndex = state.agents.findIndex(a => a.id === agentId);
+    if (agentIndex === -1) {
+        throw new Error(`Agent "${agentId}" not found in state`);
+    }
+    const agents = state.agents.map((a, i) => i === agentIndex ? { ...a, status } : a);
+    return {
+        ...state,
+        agents,
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function updateStep(state, current, label) {
+    return {
+        ...state,
+        step: { ...state.step, current, label },
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function setHandoff(state, fromId, toId, message) {
+    const agents = state.agents.map(a => a.id === fromId ? { ...a, deliverTo: toId } : a);
+    return {
+        ...state,
+        agents,
+        handoff: {
+            from: fromId,
+            to: toId,
+            message,
+            completedAt: new Date().toISOString(),
+        },
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function setSquadStatus(state, status) {
+    return {
+        ...state,
+        status,
+        updatedAt: new Date().toISOString(),
+    };
+}

package/dist/core/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/core/vitest.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'node',
+    },
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "expxagents",
+  "version": "0.1.0",
+  "description": "Multi-agent orchestration platform for AI squads",
+  "author": "ExpxAgents",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bittencourtthulio/expxagents"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "orchestration",
+    "squad",
+    "multi-agent",
+    "claude"
+  ],
+  "bin": {
+    "expxagents": "./bin/expxagents.js"
+  },
+  "files": [
+    "bin/",
+    "dist/cli/",
+    "dist/core/",
+    "assets/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.js",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}