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

feat(metaharness): npx ruflo eject β€” Phase-2 differentiator (iter 4–5)

ruv42bda4874a8c
diff --git a/.github/workflows/metaharness-ci.yml b/.github/workflows/metaharness-ci.yml
index c21001bb3b..bb16dedcbc 100644
--- a/.github/workflows/metaharness-ci.yml
+++ b/.github/workflows/metaharness-ci.yml
@@ -121,3 +121,46 @@ jobs:
# [email protected], this fails BEFORE we publish a ruflo release
# that would break neural-router.ts at runtime.
run: node scripts/check-metaharness-compat.mjs
+
+ eject-dryrun:
+ # ADR-150 Phase 2 β€” verify `ruflo eject` dry-run produces a valid
+ # plan against the ruflo repo itself, AND that the safety gate
+ # rejects --target paths inside the repo. The actual eject is
+ # never executed in CI; only the dry-run path + safety gates.
+ runs-on: ubuntu-latest
+ timeout-minutes: 3
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+
+ - name: Build CLI to dist
+ # The eject command lives in v3/@claude-flow/cli/src/commands/.
+ # CI doesn't have the bundled dist; build it here.
+ run: |
+ cd v3/@claude-flow/cli
+ npm install --no-audit --no-fund --ignore-scripts --silent
+ npm run build
+
+ - name: eject dry-run produces a valid plan
+ run: |
+ set -e
+ # Run via the built bin
+ OUT=$(node v3/@claude-flow/cli/bin/cli.js eject --name my-test-harness --format json 2>&1 || true)
+ echo "$OUT" | head -20
+ # Must contain the dry-run plan + dryRun:true
+ echo "$OUT" | grep -q '"dryRun"' || { echo "FAIL: eject dry-run did not emit dryRun:true"; exit 1; }
+ echo "$OUT" | grep -q '"name": "my-test-harness"' || { echo "FAIL: name not in plan"; exit 1; }
+ echo "βœ“ eject dry-run plan validates"
+
+ - name: eject refuses --target inside the repo (safety gate)
+ run: |
+ set -e
+ OUT=$(node v3/@claude-flow/cli/bin/cli.js eject --name foo --target "$PWD/eject-test" --confirm 2>&1 || true)
+ echo "$OUT" | head -10
+ echo "$OUT" | grep -qi "refusing to write\|target-inside-repo" || {
+ echo "FAIL: eject should refuse --target inside the repo"
+ exit 1
+ }
+ echo "βœ“ eject correctly refused in-repo target"
diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.sh
index 4ae0512275..8bc0ef5cc0 100755
--- a/plugins/ruflo-metaharness/scripts/smoke.sh
+++ b/plugins/ruflo-metaharness/scripts/smoke.sh
@@ -170,5 +170,24 @@ if (!od.metaharness) { console.error('missing metaharness in optionalDependencie
if (j.dependencies && j.dependencies.metaharness) { console.error('metaharness leaked into dependencies'); process.exit(1); }
" 2>/dev/null && ok || bad "ruflo wrapper missing metaharness optionalDep"
+step "17. eject command β€” Phase 2 differentiator (iter 4)"
+F="$ROOT/../../v3/@claude-flow/cli/src/commands/eject.ts"
+miss=""
+[[ -f "$F" ]] || miss="$miss command-file-missing"
+grep -q "name: 'eject'" "$F" 2>/dev/null || miss="$miss no-name-field"
+grep -q "from-existing" "$F" 2>/dev/null || miss="$miss no-from-existing-flag"
+# Safety: must refuse writing inside the calling repo
+grep -q "target-inside-repo" "$F" 2>/dev/null || miss="$miss no-repo-refusal"
+grep -q "target-exists" "$F" 2>/dev/null || miss="$miss no-exists-refusal"
+# Dry-run default β€” confirm flag required
+grep -q "confirm" "$F" 2>/dev/null || miss="$miss no-confirm-flag"
+grep -q "dryRun" "$F" 2>/dev/null || miss="$miss no-dryrun"
+# Graceful degradation on missing binary
+grep -q "metaharness-not-available\|degraded:" "$F" 2>/dev/null || miss="$miss no-graceful-deg"
+# Registered in the loader
+LOADER="$ROOT/../../v3/@claude-flow/cli/src/commands/index.ts"
+grep -q "eject: () => import" "$LOADER" 2>/dev/null || miss="$miss not-registered-in-loader"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1
diff --git a/v3/@claude-flow/cli/src/commands/eject.ts b/v3/@claude-flow/cli/src/commands/eject.ts
new file mode 100644
index 0000000000..0e888bf3e7
--- /dev/null
+++ b/v3/@claude-flow/cli/src/commands/eject.ts
@@ -0,0 +1,196 @@
+/**
+ * V3 CLI Eject Command β€” ADR-150 Phase-2 differentiator.
+ *
+ * Lifts the calling ruflo/claude-flow project into a renamed standalone
+ * harness using `metaharness --from-existing <dir>`. Attribution to
+ * ruflo is preserved via the upstream's `<!-- ruflo-attribution-block -->`
+ * convention.
+ *
+ * npx ruflo eject --name my-harness # dry-run plan
+ * npx ruflo eject --name my-harness --confirm # actually eject
+ * npx ruflo eject --name my-harness --target /abs/out --confirm
+ *
+ * SAFETY GATES (load-bearing)
+ * 1. Dry-run by default. `--confirm` required for any disk write.
+ * 2. `--target` MUST resolve OUTSIDE the calling repo root. Default
+ * is `/tmp/ruflo-eject-<ts>-<name>/`. Writing to the calling repo
+ * is refused with exit 2 β€” protects the user from `cwd: $ruflo`
+ * eject accidents.
+ * 3. Refuses existing target dirs (no overwrites).
+ * 4. Subprocess + 10-minute hard timeout. No library import; no
+ * static `@metaharness/*` dependency.
+ *
+ * ADR-150 ARCHITECTURAL CONSTRAINT
+ * When metaharness is unavailable (offline, no network), the command
+ * exits 0 with a structured "feature not available" message. Ruflo
+ * continues to function β€” rule #3 (graceful degradation).
+ *
+ * Created with ruv.io
+ */
+
+import type { Command, CommandContext, CommandResult } from '../types.js';
+import { output } from '../output.js';
+import { spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve as resolvePath } from 'path';
+import { tmpdir } from 'os';
+
+interface EjectOptions {
+ name: string | null;
+ target: string | null;
+ confirm: boolean;
+ format: 'table' | 'json';
+}
+
+function parseArgs(args: string[]): EjectOptions {
+ const o: EjectOptions = { name: null, target: null, confirm: false, format: 'table' };
+ for (let i = 0; i < args.length; i++) {
+ const a = args[i];
+ if (a === '--name') o.name = args[++i] || null;
+ else if (a === '--target') o.target = args[++i] || null;
+ else if (a === '--confirm') o.confirm = true;
+ else if (a === '--format') o.format = (args[++i] || 'table') as 'table' | 'json';
+ }
+ return o;
+}
+
+function runEject(targetDir: string, name: string): { exitCode: number; stderr: string; degraded?: boolean } {
+ const r = spawnSync(
+ 'npx',
+ ['-y', 'metaharness@latest', '--from-existing', process.cwd(), '--name', name, '--target', targetDir, '--yes'],
+ {
+ stdio: 'inherit',
+ env: process.env,
+ timeout: 10 * 60 * 1000,
+ shell: process.platform === 'win32',
+ }
+ );
+ const stderr = ''; // stdio: inherit β€” captured by terminal not by us
+ if (r.status === null) {
+ return { exitCode: 124, stderr: 'subprocess timed out after 10 minutes', degraded: false };
+ }
+ if (r.error && /ENOENT|spawn/.test(String(r.error.message || ''))) {
+ return { exitCode: 127, stderr: 'metaharness binary unavailable', degraded: true };
+ }
+ return { exitCode: r.status, stderr };
+}
+
+export const ejectCommand: Command = {
+ name: 'eject',
+ description:
+ 'Lift the calling ruflo project into a renamed standalone harness via metaharness --from-existing (ADR-150 Phase 2). Dry-run by default; --confirm required to write.',
+ options: [
+ {
+ name: 'name',
+ description: 'Name for the ejected harness (required)',
+ type: 'string' as const,
+ required: false,
+ },
+ {
+ name: 'target',
+ description: 'Absolute output dir (default: /tmp/ruflo-eject-<ts>-<name>/); refused if inside the calling repo',
+ type: 'string' as const,
+ },
+ {
+ name: 'confirm',
+ description: 'Actually write the eject. Without this flag the command prints a dry-run plan and exits.',
+ type: 'boolean' as const,
+ default: false,
+ },
+ {
+ name: 'format',
+ description: 'Output format: table | json',
+ type: 'string' as const,
+ default: 'table',
+ },
+ ],
+ examples: [
+ { command: 'npx ruflo eject --name my-harness', description: 'Dry-run; prints what would happen' },
+ {
+ command: 'npx ruflo eject --name my-harness --confirm',
+ description: 'Eject to /tmp/ruflo-eject-<ts>-my-harness/',
+ },
+ {
+ command: 'npx ruflo eject --name my-harness --target /abs/out --confirm',
+ description: 'Eject to a specific dir (must be outside the calling repo)',
+ },
+ ],
+ async action(context: CommandContext): Promise<CommandResult> {
+ const opts = parseArgs((context as { args?: string[] }).args || []);
+
+ if (!opts.name) {
+ output.writeln(output.error('eject: --name is required'));
+ output.writeln('');
+ output.writeln('Example: npx ruflo eject --name my-harness');
+ return { success: false, exitCode: 2, data: { error: 'name-required' } };
+ }
+
+ // Safety: resolve target, refuse calling-repo paths.
+ const repoRoot = resolvePath(process.cwd());
+ const target = opts.target
+ ? resolvePath(opts.target)
+ : resolvePath(tmpdir(), `ruflo-eject-${Date.now()}-${opts.name}`);
+ if (target === repoRoot || target.startsWith(repoRoot + '/')) {
+ output.writeln(output.error(`eject: refusing to write to ${target}`));
+ output.writeln(output.error(`This is inside the calling repo (${repoRoot}). Pick a --target OUTSIDE the repo.`));
+ return { success: false, exitCode: 2, data: { error: 'target-inside-repo', target, repoRoot } };
+ }
+ if (existsSync(target)) {
+ output.writeln(output.error(`eject: target ${target} already exists β€” refusing to overwrite`));
+ return { success: false, exitCode: 2, data: { error: 'target-exists', target } };
+ }
+
+ const plan = {
+ name: opts.name,
+ sourceRepo: repoRoot,
+ target,
+ confirm: opts.confirm,
+ command: `npx -y metaharness@latest --from-existing ${repoRoot} --name ${opts.name} --target ${target} --yes`,
+ };
+
+ if (!opts.confirm) {
+ if (opts.format === 'json') {
+ output.writeln(JSON.stringify({ ...plan, dryRun: true }, null, 2));
+ } else {
+ output.writeln(output.bold('# ruflo eject (dry-run)'));
+ output.writeln('');
+ output.writeln(`name: ${plan.name}`);
+ output.writeln(`sourceRepo: ${plan.sourceRepo}`);
+ output.writeln(`target: ${plan.target}`);
+ output.writeln('');
+ output.writeln(output.dim('Would execute:'));
+ output.writeln(output.dim(` ${plan.command}`));
+ output.writeln('');
+ output.writeln('Re-run with --confirm to actually eject.');
+ }
+ return { success: true, exitCode: 0, data: { ...plan, dryRun: true } };
+ }
+
+ // Actually run.
+ output.writeln(output.bold('# ruflo eject β€” running'));
+ output.writeln('');
+ output.writeln(`Ejecting ${repoRoot} β†’ ${target} as "${opts.name}"...`);
+ output.writeln('');
+ const r = runEject(target, opts.name);
+ if (r.degraded) {
+ output.writeln(output.warning('eject: metaharness binary unavailable β€” feature degraded'));
+ output.writeln(output.dim('(ADR-150 graceful degradation: ruflo runs without it; install with `npm i -D metaharness`.)'));
+ return { success: true, exitCode: 0, data: { ...plan, degraded: true, reason: 'metaharness-not-available' } };
+ }
+ if (r.exitCode !== 0) {
+ output.writeln(output.error(`eject: metaharness exited ${r.exitCode}`));
+ if (r.stderr) output.writeln(output.dim(r.stderr.slice(0, 400)));
+ return { success: false, exitCode: r.exitCode, data: { ...plan, exitCode: r.exitCode } };
+ }
+ output.writeln('');
+ output.writeln(output.bold(`βœ“ Ejected to ${target}`));
+ output.writeln('');
+ output.writeln(output.dim('Next steps:'));
+ output.writeln(output.dim(` cd ${target}`));
+ output.writeln(output.dim(' npm install'));
+ output.writeln(output.dim(' npx harness doctor'));
+ return { success: true, exitCode: 0, data: { ...plan, ejected: true } };
+ },
+};
+
+export default ejectCommand;
diff --git a/v3/@claude-flow/cli/src/commands/index.ts b/v3/@claude-flow/cli/src/commands/index.ts
index 5f534412ab..46cc06fa01 100644
--- a/v3/@claude-flow/cli/src/commands/index.ts
+++ b/v3/@claude-flow/cli/src/commands/index.ts
@@ -80,6 +80,8 @@ const commandLoaders: Record<string, CommandLoader> = {
'gaia-bench': () => import('./gaia-bench.js'),
// MetaHarness integration (ADR-150) β€” dispatcher over plugins/ruflo-metaharness/
metaharness: () => import('./metaharness.js'),
+ // Eject (ADR-150 Phase 2) β€” lift ruflo project into a renamed standalone harness
+ eject: () => import('./eject.js'),
};
// Cache for loaded commands