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

fix(proxy): show actionable lifecycle guidance (#2710)

rUv5c02b5cda843
diff --git a/ruflo/package.json b/ruflo/package.json
index 70489c9cbf..2ac09036d9 100644
--- a/ruflo/package.json
+++ b/ruflo/package.json
@@ -1,6 +1,6 @@
{
"name": "ruflo",
- "version": "3.32.4",
+ "version": "3.32.5",
"description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "bin/ruflo.js",
"type": "module",
@@ -40,7 +40,7 @@
"package:rvf": "bash src/scripts/package-rvf.sh"
},
"dependencies": {
- "@claude-flow/cli": "^3.32.4"
+ "@claude-flow/cli": "^3.32.5"
},
"optionalDependencies": {},
"overrides": {
diff --git a/v3/@claude-flow/cli/__tests__/proxy-console-guidance.test.ts b/v3/@claude-flow/cli/__tests__/proxy-console-guidance.test.ts
new file mode 100644
index 0000000000..1ab5f3c1d5
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/proxy-console-guidance.test.ts
@@ -0,0 +1,68 @@
+/** Bare `ruflo proxy` should be an actionable lifecycle dashboard, not the
+ * unrelated sponsored-capacity status command. */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const writeln = vi.fn();
+
+vi.mock('../src/output.js', () => ({
+ output: {
+ writeln,
+ printJson: vi.fn(),
+ printInfo: vi.fn(),
+ printSuccess: vi.fn(),
+ printError: vi.fn(),
+ printWarning: vi.fn(),
+ createSpinner: vi.fn(),
+ },
+}));
+
+let stateDir: string;
+let savedEnv: NodeJS.ProcessEnv;
+
+beforeEach(() => {
+ stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proxy-console-guidance-test-'));
+ savedEnv = { ...process.env };
+ process.env.RUFLO_STATE_DIR = stateDir;
+ writeln.mockClear();
+});
+
+afterEach(() => {
+ process.env = savedEnv;
+ fs.rmSync(stateDir, { recursive: true, force: true });
+});
+
+function renderedLines(): string[] {
+ return writeln.mock.calls.map(([line]) => String(line));
+}
+
+describe('bare proxy console guidance', () => {
+ it('tells a user with an installed but stopped proxy exactly how to start it', async () => {
+ const { proxyBinaryPath } = await import('../src/proxy/paths.js');
+ fs.mkdirSync(path.dirname(proxyBinaryPath()), { recursive: true });
+ fs.writeFileSync(proxyBinaryPath(), 'test binary marker');
+
+ const { proxyCommand } = await import('../src/commands/proxy.js');
+ const result = await proxyCommand.action!({ args: [], flags: { _: [] }, cwd: stateDir, interactive: false });
+ const lines = renderedLines().join('\n');
+
+ expect(result).toMatchObject({ success: true, data: { installed: true, running: false } });
+ expect(lines).toContain('Meta Proxy');
+ expect(lines).toContain('npx ruflo@latest proxy start --service');
+ expect(lines).toContain('npx ruflo@latest auth login');
+ expect(lines).not.toContain('Sponsored downtime consent');
+ expect(lines).not.toContain('Rate-limit flag');
+ });
+
+ it('gives installation guidance before the proxy exists', async () => {
+ const { proxyConsoleGuidance } = await import('../src/commands/proxy-lifecycle.js');
+ const lines = proxyConsoleGuidance({ installed: false, running: false, pid: null, stalePidFile: false }).join('\n');
+
+ expect(lines).toContain('npx ruflo@latest proxy install --yes');
+ expect(lines).toContain('Meta-Proxy v0.4.0');
+ expect(lines).not.toContain('auth login');
+ });
+});
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index baf350e2eb..2d172b9865 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.32.4",
+ "version": "3.32.5",
"type": "module",
"description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
"main": "dist/src/index.js",
diff --git a/v3/@claude-flow/cli/src/commands/proxy-lifecycle.ts b/v3/@claude-flow/cli/src/commands/proxy-lifecycle.ts
index 41050c5aaa..2b39ac224e 100644
--- a/v3/@claude-flow/cli/src/commands/proxy-lifecycle.ts
+++ b/v3/@claude-flow/cli/src/commands/proxy-lifecycle.ts
@@ -15,6 +15,7 @@ import {
startBackground,
stopProxy,
getProxyStatus,
+ type ProxyStatus,
readProxyLogTail,
watchProxyLog,
ProxyNotInstalledError,
@@ -26,6 +27,57 @@ import { removeInjectedToken, startTokenRefreshPump } from '../proxy/token-bridg
/** Pinned and reviewed; later upgrades remain explicit commands. */
export const DEFAULT_PROXY_RELEASE = '0.4.0';
+const PROXY_COMMAND = 'npx ruflo@latest proxy';
+const AUTH_COMMAND = 'npx ruflo@latest auth';
+
+/**
+ * Human-oriented next steps for `ruflo proxy` and `ruflo proxy status`.
+ * Keep this independent of the command framework so the state-specific
+ * guidance has a small, direct regression-test surface.
+ */
+export function proxyConsoleGuidance(status: ProxyStatus): string[] {
+ if (!status.installed) {
+ return [
+ '',
+ 'Next step',
+ ` ${PROXY_COMMAND} install --yes Install signed Meta-Proxy v${DEFAULT_PROXY_RELEASE}`,
+ '',
+ 'After installation, start it in the background:',
+ ` ${PROXY_COMMAND} start --service`,
+ ];
+ }
+
+ if (!status.running) {
+ return [
+ '',
+ 'Next step',
+ ` ${PROXY_COMMAND} start --service Start the proxy in the background`,
+ '',
+ 'Foreground mode (shows live logs; Ctrl+C stops it):',
+ ` ${PROXY_COMMAND} start`,
+ '',
+ 'Optional: enable Cognitum cloud routing (local-only is the default):',
+ ` ${AUTH_COMMAND} login`,
+ ` ${PROXY_COMMAND} config --cloud --yes`,
+ ];
+ }
+
+ return [
+ '',
+ 'Meta Proxy is ready.',
+ ` Logs: ${PROXY_COMMAND} logs`,
+ ` Stop: ${PROXY_COMMAND} stop`,
+ '',
+ 'Optional: enable Cognitum cloud routing (local-only is the default):',
+ ` ${AUTH_COMMAND} login`,
+ ` ${PROXY_COMMAND} config --cloud --yes`,
+ ];
+}
+
+export function printProxyConsoleGuidance(status: ProxyStatus): void {
+ for (const line of proxyConsoleGuidance(status)) output.writeln(line);
+}
+
const INSTALL_DISCLOSURE = [
'Installing the Meta LLM Proxy (ADR-304/307).',
'',
@@ -183,11 +235,11 @@ const statusSub: Command = {
output.printJson(status);
return { success: true, data: status };
}
- output.writeln(`Installed: ${status.installed ? 'yes' : 'no'}`);
- output.writeln(`Running: ${status.running ? `yes (pid ${status.pid})` : 'no'}`);
+ output.writeln('Meta Proxy');
+ output.writeln(` Installation: ${status.installed ? 'ready' : 'not installed'}`);
+ output.writeln(` Process: ${status.running ? `running (pid ${status.pid})` : 'not running'}`);
if (status.stalePidFile) output.writeln(' (a stale PID file was found and will be cleared on next start)');
- if (!status.installed) output.writeln(`Run: ruflo proxy install --yes (installs ${DEFAULT_PROXY_RELEASE})`);
- else if (!status.running) output.writeln('Run: ruflo proxy start');
+ printProxyConsoleGuidance(status);
return { success: true, data: status };
},
};
diff --git a/v3/@claude-flow/cli/src/commands/proxy.ts b/v3/@claude-flow/cli/src/commands/proxy.ts
index 4ce39389e9..afe7d6956e 100644
--- a/v3/@claude-flow/cli/src/commands/proxy.ts
+++ b/v3/@claude-flow/cli/src/commands/proxy.ts
@@ -25,7 +25,8 @@ import { clearRateLimitStatus, readRateLimitStatus } from '../funnel/rate-limit-
import { clearQuotaLowStatus, readQuotaLowStatus } from '../funnel/power-saver-notifier.js';
import { getInstalledCliVersion } from '../init/helper-refresh.js';
import * as path from 'path';
-import { proxyLifecycleSubcommands } from './proxy-lifecycle.js';
+import { proxyLifecycleSubcommands, printProxyConsoleGuidance } from './proxy-lifecycle.js';
+import { getProxyStatus } from '../proxy/lifecycle.js';
const PROXY_CONFIG_FILE = 'proxy-config.toml';
@@ -419,11 +420,14 @@ export const proxyCommand: Command = {
{ command: 'ruflo proxy power-saver-enable --yes', description: 'Opt into power saver mode' },
{ command: 'ruflo proxy training-share-enable --yes', description: 'Opt into training-data sharing (ADR-315)' },
],
- action: async (ctx) => {
- const { getProxyStatus } = await import('../proxy/lifecycle.js');
+ action: async () => {
const status = getProxyStatus();
- output.writeln(`Installed: ${status.installed ? 'yes' : 'no'}; Running: ${status.running ? `yes (pid ${status.pid})` : 'no'}`);
- return sponsorStatusSub.action!(ctx);
+ output.writeln('Meta Proxy');
+ output.writeln(` Installation: ${status.installed ? 'ready' : 'not installed'}`);
+ output.writeln(` Process: ${status.running ? `running (pid ${status.pid})` : 'not running'}`);
+ if (status.stalePidFile) output.writeln(' (a stale PID file was found and will be cleared on next start)');
+ printProxyConsoleGuidance(status);
+ return { success: true, data: status };
},
};