🌊 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.ymlindex 565d8ebf09..9caf93ec6b 100644--- a/.github/workflows/helpers-manifest-guard.yml+++ b/.github/workflows/helpers-manifest-guard.yml@@ -14,7 +14,19 @@ name: helpers-manifest-guardon: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-lateststeps:- 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@v4with:- 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 1fi++ - 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.mjsdiff --git a/docs/helpers-sync.md b/docs/helpers-sync.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.cjsindex 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`);+ });+ });+}