Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

checkpoint: File edit:

rUv69bb42a47569
diff --git a/v3/@claude-flow/cli/__tests__/cli.test.ts b/v3/@claude-flow/cli/__tests__/cli.test.ts
index 04f1c66ee5..2ba0e87a98 100644
--- a/v3/@claude-flow/cli/__tests__/cli.test.ts
+++ b/v3/@claude-flow/cli/__tests__/cli.test.ts
@@ -31,7 +31,7 @@ describe('CLI', () => {
// Mock process.exit to prevent actual exits
processExitMock = vi.spyOn(process, 'exit').mockImplementation((code?: string | number | null | undefined) => {
throw new Error(`process.exit: ${code}`);
- });
+ }) as unknown as ReturnType<typeof vi.spyOn>;
// Create CLI instance (non-interactive for testing)
cli = new CLI({ interactive: false });
diff --git a/v3/@claude-flow/cli/__tests__/commands.test.ts b/v3/@claude-flow/cli/__tests__/commands.test.ts
new file mode 100644
index 0000000000..0e77f1405f
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/commands.test.ts
@@ -0,0 +1,726 @@
+/**
+ * V3 CLI Commands Tests
+ * Tests for agent, swarm, memory, and config commands
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { agentCommand } from '../src/commands/agent.js';
+import { swarmCommand } from '../src/commands/swarm.js';
+import { memoryCommand } from '../src/commands/memory.js';
+import { configCommand } from '../src/commands/config.js';
+import type { CommandContext } from '../src/types.js';
+
+// Mock MCP client
+vi.mock('../src/mcp-client.js', () => ({
+ callMCPTool: vi.fn(async (toolName: string, input: Record<string, unknown>) => {
+ // Mock responses for different tools
+ if (toolName === 'agent/spawn') {
+ return {
+ agentId: input.id || 'mock-agent-123',
+ agentType: input.agentType,
+ status: 'active',
+ createdAt: new Date().toISOString()
+ };
+ }
+
+ if (toolName === 'agent/list') {
+ return {
+ agents: [
+ { id: 'agent-1', agentType: 'coder', status: 'active', createdAt: '2024-01-01T00:00:00Z' },
+ { id: 'agent-2', agentType: 'tester', status: 'idle', createdAt: '2024-01-01T00:01:00Z' }
+ ],
+ total: 2
+ };
+ }
+
+ if (toolName === 'agent/status') {
+ return {
+ id: input.agentId,
+ agentType: 'coder',
+ status: 'active',
+ createdAt: '2024-01-01T00:00:00Z',
+ lastActivityAt: new Date().toISOString(),
+ metrics: {
+ tasksCompleted: 10,
+ tasksInProgress: 2,
+ tasksFailed: 1,
+ averageExecutionTime: 1500,
+ uptime: 3600000
+ }
+ };
+ }
+
+ if (toolName === 'agent/terminate') {
+ return {
+ agentId: input.agentId,
+ terminated: true,
+ terminatedAt: new Date().toISOString()
+ };
+ }
+
+ if (toolName === 'swarm/init') {
+ return {
+ swarmId: 'swarm-mock-123',
+ topology: input.topology,
+ initializedAt: new Date().toISOString(),
+ config: {
+ topology: input.topology,
+ maxAgents: input.maxAgents || 15,
+ currentAgents: 0,
+ autoScaling: true
+ }
+ };
+ }
+
+ return {};
+ }),
+ MCPClientError: class MCPClientError extends Error {
+ constructor(message: string, public toolName: string, public cause?: Error) {
+ super(message);
+ this.name = 'MCPClientError';
+ }
+ }
+}));
+
+// Mock output
+vi.mock('../src/output.js', () => ({
+ output: {
+ writeln: vi.fn(),
+ printInfo: vi.fn(),
+ printSuccess: vi.fn(),
+ printError: vi.fn(),
+ printWarning: vi.fn(),
+ printTable: vi.fn(),
+ printJson: vi.fn(),
+ printList: vi.fn(),
+ printBox: vi.fn(),
+ createSpinner: vi.fn(() => ({
+ start: vi.fn(),
+ succeed: vi.fn(),
+ fail: vi.fn(),
+ stop: vi.fn()
+ })),
+ highlight: (str: string) => str,
+ bold: (str: string) => str,
+ dim: (str: string) => str,
+ success: (str: string) => str,
+ error: (str: string) => str,
+ warning: (str: string) => str,
+ info: (str: string) => str,
+ progressBar: () => '[=====> ]',
+ setColorEnabled: vi.fn()
+ }
+}));
+
+// Mock prompts (always return default values for non-interactive tests)
+vi.mock('../src/prompt.js', () => ({
+ select: vi.fn(async (opts) => opts.default || opts.options[0]?.value),
+ confirm: vi.fn(async (opts) => opts.default ?? false),
+ input: vi.fn(async (opts) => opts.default || 'test-input'),
+ multiSelect: vi.fn(async (opts) => opts.default || [])
+}));
+
+describe('Agent Commands', () => {
+ let ctx: CommandContext;
+
+ beforeEach(() => {
+ ctx = {
+ args: [],
+ flags: { _: [] },
+ cwd: '/test',
+ interactive: false
+ };
+ });
+
+ describe('agent spawn', () => {
+ it('should spawn agent with type flag', async () => {
+ const spawnCmd = agentCommand.subcommands?.find(c => c.name === 'spawn');
+ expect(spawnCmd).toBeDefined();
+
+ ctx.flags = { type: 'coder', _: [] };
+ const result = await spawnCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('agentId');
+ expect(result.data).toHaveProperty('agentType', 'coder');
+ });
+
+ it('should spawn agent with custom name', async () => {
+ const spawnCmd = agentCommand.subcommands?.find(c => c.name === 'spawn');
+
+ ctx.flags = { type: 'tester', name: 'my-tester', _: [] };
+ const result = await spawnCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('agentId', 'my-tester');
+ });
+
+ it('should fail without agent type in non-interactive mode', async () => {
+ const spawnCmd = agentCommand.subcommands?.find(c => c.name === 'spawn');
+
+ ctx.flags = { _: [] };
+ const result = await spawnCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ expect(result.exitCode).toBe(1);
+ });
+
+ it('should pass provider and model options', async () => {
+ const spawnCmd = agentCommand.subcommands?.find(c => c.name === 'spawn');
+
+ ctx.flags = {
+ type: 'coder',
+ provider: 'anthropic',
+ model: 'claude-3-5-sonnet',
+ _: []
+ };
+ const result = await spawnCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+
+ it('should handle task option', async () => {
+ const spawnCmd = agentCommand.subcommands?.find(c => c.name === 'spawn');
+
+ ctx.flags = {
+ type: 'researcher',
+ task: 'Research React patterns',
+ _: []
+ };
+ const result = await spawnCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+ });
+
+ describe('agent list', () => {
+ it('should list all agents', async () => {
+ const listCmd = agentCommand.subcommands?.find(c => c.name === 'list');
+ expect(listCmd).toBeDefined();
+
+ const result = await listCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('agents');
+ expect(result.data).toHaveProperty('total', 2);
+ });
+
+ it('should filter by agent type', async () => {
+ const listCmd = agentCommand.subcommands?.find(c => c.name === 'list');
+
+ ctx.flags = { type: 'coder', _: [] };
+ const result = await listCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+
+ it('should filter by status', async () => {
+ const listCmd = agentCommand.subcommands?.find(c => c.name === 'list');
+
+ ctx.flags = { status: 'active', _: [] };
+ const result = await listCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+
+ it('should include inactive agents with --all flag', async () => {
+ const listCmd = agentCommand.subcommands?.find(c => c.name === 'list');
+
+ ctx.flags = { all: true, _: [] };
+ const result = await listCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+ });
+
+ describe('agent status', () => {
+ it('should show agent status', async () => {
+ const statusCmd = agentCommand.subcommands?.find(c => c.name === 'status');
+ expect(statusCmd).toBeDefined();
+
+ ctx.args = ['agent-123'];
+ const result = await statusCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('id');
+ expect(result.data).toHaveProperty('status');
+ expect(result.data).toHaveProperty('metrics');
+ });
+
+ it('should fail without agent ID', async () => {
+ const statusCmd = agentCommand.subcommands?.find(c => c.name === 'status');
+
+ ctx.args = [];
+ ctx.interactive = false;
+ const result = await statusCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ expect(result.exitCode).toBe(1);
+ });
+ });
+
+ describe('agent stop', () => {
+ it('should stop agent', async () => {
+ const stopCmd = agentCommand.subcommands?.find(c => c.name === 'stop');
+ expect(stopCmd).toBeDefined();
+
+ ctx.args = ['agent-123'];
+ ctx.flags = { force: true, _: [] };
+ const result = await stopCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('agentId', 'agent-123');
+ expect(result.data).toHaveProperty('terminated', true);
+ });
+
+ it('should fail without agent ID', async () => {
+ const stopCmd = agentCommand.subcommands?.find(c => c.name === 'stop');
+
+ ctx.args = [];
+ const result = await stopCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ });
+ });
+
+ describe('agent metrics', () => {
+ it('should show agent metrics', async () => {
+ const metricsCmd = agentCommand.subcommands?.find(c => c.name === 'metrics');
+ expect(metricsCmd).toBeDefined();
+
+ const result = await metricsCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('summary');
+ expect(result.data).toHaveProperty('performance');
+ });
+
+ it('should accept period option', async () => {
+ const metricsCmd = agentCommand.subcommands?.find(c => c.name === 'metrics');
+
+ ctx.flags = { period: '7d', _: [] };
+ const result = await metricsCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+ });
+});
+
+describe('Swarm Commands', () => {
+ let ctx: CommandContext;
+
+ beforeEach(() => {
+ ctx = {
+ args: [],
+ flags: { _: [] },
+ cwd: '/test',
+ interactive: false
+ };
+ });
+
+ describe('swarm init', () => {
+ it('should initialize swarm with default topology', async () => {
+ const initCmd = swarmCommand.subcommands?.find(c => c.name === 'init');
+ expect(initCmd).toBeDefined();
+
+ const result = await initCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('swarmId');
+ expect(result.data).toHaveProperty('topology');
+ });
+
+ it('should initialize swarm with custom topology', async () => {
+ const initCmd = swarmCommand.subcommands?.find(c => c.name === 'init');
+
+ ctx.flags = { topology: 'mesh', _: [] };
+ const result = await initCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('topology', 'mesh');
+ });
+
+ it('should enable V3 mode', async () => {
+ const initCmd = swarmCommand.subcommands?.find(c => c.name === 'init');
+
+ ctx.flags = { v3Mode: true, _: [] };
+ const result = await initCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+
+ it('should set max agents', async () => {
+ const initCmd = swarmCommand.subcommands?.find(c => c.name === 'init');
+
+ ctx.flags = { maxAgents: 20, _: [] };
+ const result = await initCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data?.config).toHaveProperty('maxAgents', 20);
+ });
+ });
+
+ describe('swarm start', () => {
+ it('should start swarm with objective', async () => {
+ const startCmd = swarmCommand.subcommands?.find(c => c.name === 'start');
+ expect(startCmd).toBeDefined();
+
+ ctx.flags = { objective: 'Build REST API', _: [] };
+ const result = await startCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('objective', 'Build REST API');
+ });
+
+ it('should fail without objective', async () => {
+ const startCmd = swarmCommand.subcommands?.find(c => c.name === 'start');
+
+ const result = await startCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ expect(result.exitCode).toBe(1);
+ });
+
+ it('should accept strategy option', async () => {
+ const startCmd = swarmCommand.subcommands?.find(c => c.name === 'start');
+
+ ctx.flags = { objective: 'Test project', strategy: 'testing', _: [] };
+ const result = await startCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('strategy', 'testing');
+ });
+ });
+
+ describe('swarm status', () => {
+ it('should show swarm status', async () => {
+ const statusCmd = swarmCommand.subcommands?.find(c => c.name === 'status');
+ expect(statusCmd).toBeDefined();
+
+ const result = await statusCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('agents');
+ expect(result.data).toHaveProperty('tasks');
+ expect(result.data).toHaveProperty('metrics');
+ });
+ });
+
+ describe('swarm stop', () => {
+ it('should stop swarm', async () => {
+ const stopCmd = swarmCommand.subcommands?.find(c => c.name === 'stop');
+ expect(stopCmd).toBeDefined();
+
+ ctx.args = ['swarm-123'];
+ ctx.flags = { force: true, _: [] };
+ const result = await stopCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('swarmId', 'swarm-123');
+ expect(result.data).toHaveProperty('stopped', true);
+ });
+
+ it('should fail without swarm ID', async () => {
+ const stopCmd = swarmCommand.subcommands?.find(c => c.name === 'stop');
+
+ const result = await stopCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ });
+ });
+
+ describe('swarm scale', () => {
+ it('should scale swarm', async () => {
+ const scaleCmd = swarmCommand.subcommands?.find(c => c.name === 'scale');
+ expect(scaleCmd).toBeDefined();
+
+ ctx.args = ['swarm-123'];
+ ctx.flags = { agents: 20, _: [] };
+ const result = await scaleCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('agents', 20);
+ });
+
+ it('should fail without target agent count', async () => {
+ const scaleCmd = swarmCommand.subcommands?.find(c => c.name === 'scale');
+
+ ctx.args = ['swarm-123'];
+ const result = await scaleCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ });
+ });
+
+ describe('swarm coordinate', () => {
+ it('should show V3 coordination structure', async () => {
+ const coordinateCmd = swarmCommand.subcommands?.find(c => c.name === 'coordinate');
+ expect(coordinateCmd).toBeDefined();
+
+ const result = await coordinateCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('agents');
+ expect(result.data?.agents).toHaveLength(15);
+ });
+ });
+});
+
+describe('Memory Commands', () => {
+ let ctx: CommandContext;
+
+ beforeEach(() => {
+ ctx = {
+ args: [],
+ flags: { _: [] },
+ cwd: '/test',
+ interactive: false
+ };
+ });
+
+ describe('memory store', () => {
+ it('should store data', async () => {
+ const storeCmd = memoryCommand.subcommands?.find(c => c.name === 'store');
+ expect(storeCmd).toBeDefined();
+
+ ctx.flags = { key: 'test-key', value: 'test-value', _: [] };
+ const result = await storeCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('key', 'test-key');
+ });
+
+ it('should fail without key', async () => {
+ const storeCmd = memoryCommand.subcommands?.find(c => c.name === 'store');
+
+ ctx.flags = { value: 'test-value', _: [] };
+ const result = await storeCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ });
+ });
+
+ describe('memory retrieve', () => {
+ it('should retrieve data', async () => {
+ const retrieveCmd = memoryCommand.subcommands?.find(c => c.name === 'retrieve');
+ expect(retrieveCmd).toBeDefined();
+
+ ctx.args = ['test-key'];
+ const result = await retrieveCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('key', 'test-key');
+ });
+ });
+
+ describe('memory search', () => {
+ it('should search memory', async () => {
+ const searchCmd = memoryCommand.subcommands?.find(c => c.name === 'search');
+ expect(searchCmd).toBeDefined();
+
+ ctx.flags = { query: 'authentication', _: [] };
+ const result = await searchCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(Array.isArray(result.data)).toBe(true);
+ });
+
+ it('should fail without query', async () => {
+ const searchCmd = memoryCommand.subcommands?.find(c => c.name === 'search');
+
+ const result = await searchCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ });
+ });
+
+ describe('memory list', () => {
+ it('should list memory entries', async () => {
+ const listCmd = memoryCommand.subcommands?.find(c => c.name === 'list');
+ expect(listCmd).toBeDefined();
+
+ const result = await listCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(Array.isArray(result.data)).toBe(true);
+ });
+ });
+
+ describe('memory delete', () => {
+ it('should delete entry', async () => {
+ const deleteCmd = memoryCommand.subcommands?.find(c => c.name === 'delete');
+ expect(deleteCmd).toBeDefined();
+
+ ctx.args = ['test-key'];
+ ctx.flags = { force: true, _: [] };
+ const result = await deleteCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('deleted', true);
+ });
+ });
+
+ describe('memory stats', () => {
+ it('should show memory statistics', async () => {
+ const statsCmd = memoryCommand.subcommands?.find(c => c.name === 'stats');
+ expect(statsCmd).toBeDefined();
+
+ const result = await statsCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('entries');
+ expect(result.data).toHaveProperty('storage');
+ expect(result.data).toHaveProperty('performance');
+ });
+ });
+
+ describe('memory configure', () => {
+ it('should configure memory backend', async () => {
+ const configureCmd = memoryCommand.subcommands?.find(c => c.name === 'configure');
+ expect(configureCmd).toBeDefined();
+
+ ctx.flags = { backend: 'agentdb', _: [] };
+ const result = await configureCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('backend', 'agentdb');
+ });
+ });
+});
+
+describe('Config Commands', () => {
+ let ctx: CommandContext;
+
+ beforeEach(() => {
+ ctx = {
+ args: [],
+ flags: { _: [] },
+ cwd: '/test',
+ interactive: false
+ };
+ });
+
+ describe('config init', () => {
+ it('should initialize configuration', async () => {
+ const initCmd = configCommand.subcommands?.find(c => c.name === 'init');
+ expect(initCmd).toBeDefined();
+
+ const result = await initCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('version');
+ });
+
+ it('should initialize with V3 mode', async () => {
+ const initCmd = configCommand.subcommands?.find(c => c.name === 'init');
+
+ ctx.flags = { v3: true, _: [] };
+ const result = await initCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('v3Mode', true);
+ });
+ });
+
+ describe('config get', () => {
+ it('should get configuration value', async () => {
+ const getCmd = configCommand.subcommands?.find(c => c.name === 'get');
+ expect(getCmd).toBeDefined();
+
+ ctx.args = ['swarm.topology'];
+ const result = await getCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('key');
+ expect(result.data).toHaveProperty('value');
+ });
+
+ it('should show all config when no key provided', async () => {
+ const getCmd = configCommand.subcommands?.find(c => c.name === 'get');
+
+ const result = await getCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ });
+ });
+
+ describe('config set', () => {
+ it('should set configuration value', async () => {
+ const setCmd = configCommand.subcommands?.find(c => c.name === 'set');
+ expect(setCmd).toBeDefined();
+
+ ctx.flags = { key: 'swarm.maxAgents', value: '20', _: [] };
+ const result = await setCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('key', 'swarm.maxAgents');
+ expect(result.data).toHaveProperty('value', '20');
+ });
+
+ it('should fail without key and value', async () => {
+ const setCmd = configCommand.subcommands?.find(c => c.name === 'set');
+
+ const result = await setCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ });
+ });
+
+ describe('config providers', () => {
+ it('should list providers', async () => {
+ const providersCmd = configCommand.subcommands?.find(c => c.name === 'providers');
+ expect(providersCmd).toBeDefined();
+
+ const result = await providersCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(Array.isArray(result.data)).toBe(true);
+ });
+ });
+
+ describe('config reset', () => {
+ it('should reset configuration', async () => {
+ const resetCmd = configCommand.subcommands?.find(c => c.name === 'reset');
+ expect(resetCmd).toBeDefined();
+
+ ctx.flags = { force: true, _: [] };
+ const result = await resetCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('reset', true);
+ });
+ });
+
+ describe('config export', () => {
+ it('should export configuration', async () => {
+ const exportCmd = configCommand.subcommands?.find(c => c.name === 'export');
+ expect(exportCmd).toBeDefined();
+
+ const result = await exportCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('config');
+ });
+ });
+
+ describe('config import', () => {
+ it('should import configuration', async () => {
+ const importCmd = configCommand.subcommands?.find(c => c.name === 'import');
+ expect(importCmd).toBeDefined();
+
+ ctx.flags = { file: './config.json', _: [] };
+ const result = await importCmd!.action!(ctx);
+
+ expect(result.success).toBe(true);
+ expect(result.data).toHaveProperty('imported', true);
+ });
+
+ it('should fail without file path', async () => {
+ const importCmd = configCommand.subcommands?.find(c => c.name === 'import');
+
+ const result = await importCmd!.action!(ctx);
+
+ expect(result.success).toBe(false);
+ });
+ });
+});
diff --git a/v3/@claude-flow/deployment/examples/basic-release.ts b/v3/@claude-flow/deployment/examples/basic-release.ts
new file mode 100644
index 0000000000..e50eb52d09
--- /dev/null
+++ b/v3/@claude-flow/deployment/examples/basic-release.ts
@@ -0,0 +1,92 @@
+/**
+ * Basic Release Workflow Example
+ *
+ * This example demonstrates a complete release workflow:
+ * 1. Validate package
+ * 2. Prepare release (bump version, generate changelog, create tag)
+ * 3. Publish to npm
+ */
+
+import { Validator, ReleaseManager, Publisher } from '@claude-flow/deployment';
+
+async function basicRelease() {
+ console.log('Starting release workflow...\n');
+
+ // Step 1: Validate package
+ console.log('1. Validating package...');
+ const validator = new Validator();
+ const validation = await validator.validate({
+ lint: true,
+ test: true,
+ build: true,
+ checkDependencies: true,
+ checkGitStatus: true
+ });
+
+ console.log(` Valid: ${validation.valid}`);
+ if (validation.errors.length > 0) {
+ console.log(` Errors: ${validation.errors.join(', ')}`);
+ }
+ if (validation.warnings.length > 0) {
+ console.log(` Warnings: ${validation.warnings.join(', ')}`);
+ }
+
+ if (!validation.valid) {
+ console.error('\n❌ Validation failed. Fix errors before releasing.');
+ process.exit(1);
+ }
+
+ // Step 2: Prepare release
+ console.log('\n2. Preparing release...');
+ const manager = new ReleaseManager();
+ const release = await manager.prepareRelease({
+ bumpType: 'patch', // or 'minor', 'major', 'prerelease'
+ generateChangelog: true,
+ createTag: true,
+ commit: true,
+ dryRun: false // Set to true for testing
+ });
+
+ if (!release.success) {
+ console.error(`\n❌ Release preparation failed: ${release.error}`);
+ process.exit(1);
+ }
+
+ console.log(` Version: ${release.oldVersion} → ${release.newVersion}`);
+ console.log(` Tag: ${release.tag}`);
+ console.log(` Commit: ${release.commitHash?.substring(0, 7)}`);
+
+ // Step 3: Publish to npm
+ console.log('\n3. Publishing to npm...');
+ const publisher = new Publisher();
+
+ // Verify authentication
+ const authenticated = await publisher.verifyAuth();
+ if (!authenticated) {
+ console.error('\n❌ Not authenticated with npm. Run: npm login');
+ process.exit(1);
+ }
+
+ const publish = await publisher.publishToNpm({
+ tag: 'latest',
+ access: 'public',
+ dryRun: false // Set to true for testing
+ });
+
+ if (!publish.success) {
+ console.error(`\n❌ Publish failed: ${publish.error}`);
+ process.exit(1);
+ }
+
+ console.log(` Package: ${publish.packageName}@${publish.version}`);
+ console.log(` Tag: ${publish.tag}`);
+ console.log(` Tarball: ${publish.tarball}`);
+
+ console.log('\n✅ Release completed successfully!');
+}
+
+// Run the release
+basicRelease().catch(error => {
+ console.error('Release failed:', error);
+ process.exit(1);
+});
diff --git a/v3/@claude-flow/deployment/examples/dry-run.ts b/v3/@claude-flow/deployment/examples/dry-run.ts
new file mode 100644
index 0000000000..b3940c5224
--- /dev/null
+++ b/v3/@claude-flow/deployment/examples/dry-run.ts
@@ -0,0 +1,70 @@
+/**
+ * Dry Run Example
+ *
+ * Test release without making actual changes
+ */
+
+import { prepareRelease, publishToNpm, validate } from '@claude-flow/deployment';
+
+async function dryRunRelease() {
+ console.log('Dry Run Mode - Testing release without changes\n');
+
+ // Validate package
+ console.log('1. Validating package...');
+ const validation = await validate();
+
+ if (!validation.valid) {
+ console.log(' ⚠️ Validation issues found:');
+ validation.errors.forEach(err => console.log(` - ${err}`));
+ console.log('\n (Continuing anyway in dry-run mode)\n');
+ } else {
+ console.log(' ✅ Package validation passed\n');
+ }
+
+ // Prepare release (dry run)
+ console.log('2. Preparing release (dry run)...');
+ const release = await prepareRelease({
+ bumpType: 'minor',
+ generateChangelog: true,
+ createTag: true,
+ commit: true,
+ dryRun: true // No actual changes
+ });
+
+ if (release.success) {
+ console.log(' Would create release:');
+ console.log(` Version: ${release.oldVersion} → ${release.newVersion}`);
+ console.log(` Tag: ${release.tag}`);
+ console.log(' \n Generated changelog:');
+ if (release.changelog) {
+ release.changelog.split('\n').forEach(line => {
+ console.log(` ${line}`);
+ });
+ }
+ console.log();
+ }
+
+ // Publish (dry run)
+ console.log('3. Publishing to npm (dry run)...');
+ const publish = await publishToNpm({
+ tag: 'latest',
+ access: 'public',
+ dryRun: true // No actual publish
+ });
+
+ if (publish.success) {
+ console.log(' Would publish:');
+ console.log(` Package: ${publish.packageName}@${publish.version}`);
+ console.log(` Tag: ${publish.tag}`);
+ console.log();
+ }
+
+ console.log('✅ Dry run completed - no changes were made');
+ console.log(' To perform actual release, remove dryRun: true option');
+}
+
+// Run dry run
+dryRunRelease().catch(error => {
+ console.error('Dry run failed:', error);
+ process.exit(1);
+});
diff --git a/v3/@claude-flow/deployment/examples/prerelease-workflow.ts b/v3/@claude-flow/deployment/examples/prerelease-workflow.ts
new file mode 100644
index 0000000000..51e4b46553
--- /dev/null
+++ b/v3/@claude-flow/deployment/examples/prerelease-workflow.ts
@@ -0,0 +1,98 @@
+/**
+ * Prerelease Workflow Example
+ *
+ * Demonstrates publishing alpha/beta/rc versions
+ */
+
+import { prepareRelease, publishToNpm } from '@claude-flow/deployment';
+
+async function prereleaseWorkflow() {
+ console.log('Prerelease Workflow\n');
+
+ // Alpha release (early development)
+ console.log('1. Creating alpha release...');
+ const alpha = await prepareRelease({
+ bumpType: 'prerelease',
+ channel: 'alpha',
+ generateChangelog: true,
+ createTag: true,
+ commit: true
+ });
+
+ if (alpha.success) {
+ console.log(` Created: ${alpha.newVersion}`);
+
+ await publishToNpm({
+ tag: 'alpha',
+ access: 'public'
+ });
+ console.log(' Published to npm with tag "alpha"\n');
+ }
+
+ // Beta release (feature complete, testing)
+ console.log('2. Creating beta release...');
+ const beta = await prepareRelease({
+ bumpType: 'prerelease',
+ channel: 'beta',
+ generateChangelog: true,
+ createTag: true,
+ commit: true
+ });
+
+ if (beta.success) {
+ console.log(` Created: ${beta.newVersion}`);
+
+ await publishToNpm({
+ tag: 'beta',
+ access: 'public'
+ });
+ console.log(' Published to npm with tag "beta"\n');
+ }
+
+ // RC release (release candidate)
+ console.log('3. Creating release candidate...');
+ const rc = await prepareRelease({
+ bumpType: 'prerelease',
+ channel: 'rc',
+ generateChangelog: true,
+ createTag: true,
+ commit: true
+ });
+
+ if (rc.success) {
+ console.log(` Created: ${rc.newVersion}`);
+
+ await publishToNpm({
+ tag: 'rc',
+ access: 'public'
+ });
+ console.log(' Published to npm with tag "rc"\n');
+ }
+
+ // Final release (stable)
+ console.log('4. Creating final release...');
+ const final = await prepareRelease({
+ bumpType: 'patch',
+ generateChangelog: true,
+ createTag: true,
+ commit: true
+ });
+
+ if (final.success) {
+ console.log(` Created: ${final.newVersion}`);
+
+ await publishToNpm({
+ tag: 'latest',
+ access: 'public'
+ });
+ console.log(' Published to npm with tag "latest"\n');
+ }
+
+ console.log('✅ Prerelease workflow completed!');
+}
+
+// Run the workflow
+prereleaseWorkflow().catch(error => {
+ console.error('Workflow failed:', error);
+ process.exit(1);
+});