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(ci): gate helper sync on import and manifest checks (#4507)

Lenin Mookiah2be0b69d6853
diff --git a/.github/workflows/helpers-manifest-guard.yml b/.github/workflows/helpers-manifest-guard.yml
index 565d8ebf09..9caf93ec6b 100644
--- a/.github/workflows/helpers-manifest-guard.yml
+++ b/.github/workflows/helpers-manifest-guard.yml
@@ -14,7 +14,19 @@ name: helpers-manifest-guard
on:
pull_request:
paths:
- - 'v3/@claude-flow/cli/.claude/helpers/auto-memory-hook.mjs'
+ - '.claude/helpers/**'
+ - 'tests/hook-handler-runwithtimeout.test.cjs'
+ - 'v3/@claude-flow/cli/__tests__/helper-signing.test.ts'
+ - 'v3/@claude-flow/cli/src/init/helper-signing.ts'
+ - 'scripts/check-helper-sync.mjs'
+ - 'v3/@claude-flow/cli/vitest.config.ts'
+ - 'v3/package.json'
+ - 'v3/pnpm-lock.yaml'
+ - 'v3/pnpm-workspace.yaml'
+ - 'package.json'
+ - 'package-lock.json'
+ - 'docs/helpers-sync.md'
+ - 'v3/@claude-flow/cli/.claude/helpers/**'
- 'v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs'
- 'v3/@claude-flow/cli/.claude/helpers/intelligence.cjs'
- 'v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json'
@@ -27,6 +39,19 @@ on:
push:
branches: [main]
paths:
+ - '.github/workflows/helpers-manifest-guard.yml'
+ - '.claude/helpers/**'
+ - 'tests/hook-handler-runwithtimeout.test.cjs'
+ - 'v3/@claude-flow/cli/__tests__/helper-signing.test.ts'
+ - 'v3/@claude-flow/cli/src/init/helper-signing.ts'
+ - 'scripts/check-helper-sync.mjs'
+ - 'v3/@claude-flow/cli/vitest.config.ts'
+ - 'v3/package.json'
+ - 'v3/pnpm-lock.yaml'
+ - 'v3/pnpm-workspace.yaml'
+ - 'package.json'
+ - 'package-lock.json'
+ - 'docs/helpers-sync.md'
- 'v3/@claude-flow/cli/.claude/helpers/**'
- 'v3/@claude-flow/cli/scripts/sign-helpers.mjs'
- 'v3/@claude-flow/cli/scripts/verify-helpers.mjs'
@@ -39,9 +64,15 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
+ # Match the CLI test install in v3-ci.yml (Test V3 Packages).
+ - uses: pnpm/action-setup@v6
+ with:
+ version: '8'
- uses: actions/setup-node@v4
with:
- node-version: '20'
+ node-version: '22'
+ cache: 'pnpm'
+ cache-dependency-path: v3/pnpm-lock.yaml
# 1. The scripts themselves must exist. If either is deleted, the
# prepublishOnly command below silently no-ops on that step and
@@ -81,3 +112,10 @@ jobs:
echo "::error::sign-helpers.mjs must run BEFORE verify-helpers.mjs in prepublishOnly (#2593)"
exit 1
fi
+
+ - name: Install CLI test dependencies
+ working-directory: v3
+ run: pnpm install --frozen-lockfile
+
+ - name: Verify helper sync and committed manifest (#3206)
+ run: node scripts/check-helper-sync.mjs
diff --git a/docs/helpers-sync.md b/docs/helpers-sync.md
new file mode 100644
index 0000000000..6a9ca93917
--- /dev/null
+++ b/docs/helpers-sync.md
@@ -0,0 +1,28 @@
+# Checking a dogfood-helper sync
+
+The packaged `v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs` and the
+repository's `.claude/helpers/hook-handler.cjs` must both retain the
+`require.main === module` startup guard and the `runWithTimeout` and
+`INTELLIGENCE_TIMEOUT_MS` exports. A manual copy must preserve them (#3206).
+
+Before committing a helper sync:
+
+1. Make the intended helper changes and update the dogfood copy as needed.
+2. If a packaged critical helper changed, an authorized maintainer must run
+ the existing signer from `v3/@claude-flow/cli`:
+ `node scripts/sign-helpers.mjs`. Use the project's existing private-key
+ provisioning; never commit a key. Contributors without the signing key
+ should ask a maintainer to sign the reviewed helper changes.
+3. Install the CLI test dependencies with `pnpm install --frozen-lockfile`
+ from `v3` (pnpm 8, Node 22, matching the Test V3 Packages job in
+ `.github/workflows/v3-ci.yml`).
+4. From the repository root run `node scripts/check-helper-sync.mjs`.
+ This runs the timeout suite on both copies, then the CLI's
+ `__tests__/helper-signing.test.ts` with its local Vitest 4. It checks the
+ real committed manifest signature and every listed packaged helper's bytes.
+5. Commit the helper changes and matching `helpers.manifest.json` together.
+
+This is a manual pre-commit check. The helpers-manifest-guard workflow runs
+the same command after a push or PR as an enforced CI backstop. The check
+never signs or repairs files: stale or invalid committed signatures must fail.
+Publish-time re-signing cannot repair a manifest that already failed CI.
diff --git a/scripts/check-helper-sync.mjs b/scripts/check-helper-sync.mjs
new file mode 100644
index 0000000000..adea9ddcd3
--- /dev/null
+++ b/scripts/check-helper-sync.mjs
@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/** Verify a helper sync before committing; never sign or repair its inputs. */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const cli = join(root, 'v3', '@claude-flow', 'cli');
+const vitest = join(cli, 'node_modules', 'vitest');
+
+function run(args, cwd) {
+ const result = spawnSync(process.execPath, args, { cwd, stdio: 'inherit' });
+ if (result.error) throw result.error;
+ if (result.signal || result.status !== 0) {
+ throw new Error(`Helper sync check failed (${result.signal || result.status}): ${args.join(' ')}`);
+ }
+}
+
+try {
+ const manifest = join(vitest, 'package.json');
+ const runner = join(vitest, 'vitest.mjs');
+ if (!existsSync(manifest) || !existsSync(runner)) {
+ throw new Error('CLI-local Vitest 4 is required. Run pnpm install --frozen-lockfile in v3 first.');
+ }
+ const { version } = JSON.parse(readFileSync(manifest, 'utf8'));
+ if (!/^4\./.test(version)) throw new Error(`CLI-local Vitest 4 is required; found ${version}.`);
+
+ console.log('[helper-sync] Checking root and packaged hook-handler.cjs imports and timeout behavior');
+ run(['--test', join(root, 'tests', 'hook-handler-runwithtimeout.test.cjs')], root);
+ console.log('[helper-sync] Checking the committed packaged helpers.manifest.json signature and helper bytes');
+ run([runner, 'run', '__tests__/helper-signing.test.ts', '--maxWorkers=1'], cli);
+} catch (error) {
+ console.error(`[helper-sync] ${error.message}`);
+ process.exitCode = 1;
+}
diff --git a/tests/hook-handler-runwithtimeout.test.cjs b/tests/hook-handler-runwithtimeout.test.cjs
index 7a3dfecff6..8cc0a2da4f 100644
--- a/tests/hook-handler-runwithtimeout.test.cjs
+++ b/tests/hook-handler-runwithtimeout.test.cjs
@@ -9,48 +9,65 @@
*
* Uses node:test (built-in) so it runs without installing dependencies.
*/
+// Both copies must also remain importable after a helper sync (#3206).
const test = require('node:test');
const assert = require('node:assert/strict');
-const path = require('path');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { mkdtempSync, rmSync } = require('node:fs');
+const { tmpdir } = require('node:os');
-const { runWithTimeout, INTELLIGENCE_TIMEOUT_MS } = require(
- path.join(__dirname, '..', '.claude', 'helpers', 'hook-handler.cjs')
-);
+const root = path.join(__dirname, '..');
+for (const [label, relative] of [
+ ['root dogfood', '.claude/helpers/hook-handler.cjs'],
+ ['packaged', 'v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs'],
+]) {
+ test(`${label}: import surface and runWithTimeout`, async (t) => {
+ const helper = path.join(root, relative);
+ const cwd = mkdtempSync(path.join(tmpdir(), 'helper-import-'));
+ const marker = 'HELPER_IMPORT_RETURNED_WITH_EXPORTS';
+ try {
+ // An unguarded main() can exit 0 before registering any tests. Keep
+ // that import out of the parent and require a marker AFTER it returns.
+ const child = spawnSync(process.execPath, ['-e', `
+ const assert = require('node:assert/strict');
+ const helper = require(process.argv[1]);
+ assert.equal(typeof helper.runWithTimeout, 'function');
+ assert.equal(typeof helper.INTELLIGENCE_TIMEOUT_MS, 'number');
+ assert.ok(Number.isFinite(helper.INTELLIGENCE_TIMEOUT_MS) && helper.INTELLIGENCE_TIMEOUT_MS > 0);
+ console.log(${JSON.stringify(marker)});
+ `, helper], { cwd, input: '', encoding: 'utf8', timeout: 10000, maxBuffer: 65536 });
+ assert.ifError(child.error);
+ assert.equal(child.signal, null, child.stderr);
+ assert.equal(child.status, 0, child.stderr);
+ assert.equal(child.stdout.trim(), marker, 'require must return without running main()');
+ } finally {
+ rmSync(cwd, { recursive: true, force: true });
+ }
-test('returns the value for a fast async fn', async () => {
- const r = await runWithTimeout(() => Promise.resolve(42), 'fast-async');
- assert.equal(r, 42);
-});
-
-test('returns the value for a fast sync fn', async () => {
- const r = await runWithTimeout(() => 7, 'fast-sync');
- assert.equal(r, 7);
-});
-
-test('resolves null (never rejects) when fn throws synchronously', async () => {
- const r = await runWithTimeout(() => { throw new Error('boom'); }, 'sync-throw');
- assert.equal(r, null);
-});
-
-test('resolves null (never rejects) when an async fn rejects', async () => {
- const r = await runWithTimeout(() => Promise.reject(new Error('boom')), 'async-reject');
- assert.equal(r, null);
-});
-
-test('times out a slow async fn and resolves null near the timeout', { timeout: 8000 }, async () => {
- const start = Date.now();
- const r = await runWithTimeout(
- () => new Promise((res) => {
- // .unref() so the dangling timer never keeps the test process alive
- const t = setTimeout(() => res('late'), INTELLIGENCE_TIMEOUT_MS + 2000);
- if (t.unref) t.unref();
- }),
- 'slow-async'
- );
- const elapsed = Date.now() - start;
- assert.equal(r, null, "should time out to null, not return the late value");
- assert.ok(
- elapsed >= INTELLIGENCE_TIMEOUT_MS - 200 && elapsed < INTELLIGENCE_TIMEOUT_MS + 1500,
- `should resolve near the ${INTELLIGENCE_TIMEOUT_MS}ms timeout, took ${elapsed}ms`
- );
-});
+ const { runWithTimeout, INTELLIGENCE_TIMEOUT_MS } = require(helper);
+ await t.test('returns the value for a fast async fn', async () => {
+ assert.equal(await runWithTimeout(() => Promise.resolve(42), 'fast-async'), 42);
+ });
+ await t.test('returns the value for a fast sync fn', async () => {
+ assert.equal(await runWithTimeout(() => 7, 'fast-sync'), 7);
+ });
+ await t.test('resolves null (never rejects) when fn throws synchronously', async () => {
+ assert.equal(await runWithTimeout(() => { throw new Error('boom'); }, 'sync-throw'), null);
+ });
+ await t.test('resolves null (never rejects) when an async fn rejects', async () => {
+ assert.equal(await runWithTimeout(() => Promise.reject(new Error('boom')), 'async-reject'), null);
+ });
+ await t.test('times out a slow async fn and resolves null near the timeout', { timeout: 8000 }, async () => {
+ const start = Date.now();
+ const result = await runWithTimeout(() => new Promise((res) => {
+ const timer = setTimeout(() => res('late'), INTELLIGENCE_TIMEOUT_MS + 2000);
+ timer.unref();
+ }), 'slow-async');
+ const elapsed = Date.now() - start;
+ assert.equal(result, null, 'should time out to null, not return the late value');
+ assert.ok(elapsed >= INTELLIGENCE_TIMEOUT_MS - 200 && elapsed < INTELLIGENCE_TIMEOUT_MS + 1500,
+ `should resolve near ${INTELLIGENCE_TIMEOUT_MS}ms, took ${elapsed}ms`);
+ });
+ });
+}