@thecolonylab/hivemind 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hivemind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/hivemind.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/browser/session.js

@@ -0,0 +1,21 @@
+import { chromium } from 'playwright';
+const VIEWPORT = { width: 1280, height: 800 };
+/** No video recording — evidence is per-step base64 screenshots sent back to the server, not a
+ *  screen recording. */
+export async function openSession(opts = {}) {
+    const browser = await chromium.launch({ headless: !opts.headed });
+    const context = await browser.newContext({
+        viewport: VIEWPORT,
+        locale: 'en-US',
+    });
+    const page = await context.newPage();
+    return {
+        browser,
+        context,
+        page,
+        close: async () => {
+            await context.close();
+            await browser.close();
+        },
+    };
+}

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { Command } from 'commander';
+import { runCommand } from './commands/run.js';
+import { createCommand } from './commands/create.js';
+import { reportCommand, historyCommand } from './commands/report.js';
+import { dashboardCommand } from './commands/dashboard.js';
+import { exploreCommand } from './commands/explore.js';
+import { coverageCommand } from './commands/coverage.js';
+import { applyCommand } from './commands/apply.js';
+import { initCommand } from './commands/init.js';
+import { loginCommand } from './commands/login.js';
+const program = new Command();
+program
+    .name('hivemind')
+    .description('Agentic E2E testing. This CLI is the Forager: it runs on your machine and executes exactly ' +
+    'what the Hivemind brain tells it to. Describe a flow in plain English — the server drives ' +
+    'a real browser and reports pass/fail. No LLM key needed on your machine.')
+    .version('0.1.0');
+program
+    .command('login <key>')
+    .description('Store an API key (generate one from the dashboard\'s Settings page) so this machine is signed in')
+    .action(loginCommand);
+program
+    .command('init')
+    .description('Set up hivemind in this project — hive/tests/, hivemind.config.json, AGENTS.md, and the agent skill file')
+    .action(initCommand);
+program
+    .command('run <target>')
+    .description('Run a test file or every test file in a folder — cloud execution by default')
+    .option('--url <url>', 'Target URL (overrides the test file and config)')
+    .option('--env <name>', 'Named environment from hivemind.config.json')
+    .option('--json', 'Print machine-readable JSON output')
+    .option('--changed [base]', 'Only run tests tagged for what changed vs. this base ref (default: main)')
+    .option('--local', 'Run the browser on this machine instead of the cloud server — required for localhost/private URLs, needs Playwright browsers installed locally')
+    .option('--headed', 'Local mode only: show the browser window instead of running headless')
+    .option('--concurrency <n>', 'Swarm mode: run up to n tests at once instead of one at a time (default 1)', '1')
+    .option('--pr-comment <path>', 'Write a PR-comment-ready markdown report to this path (post it yourself, e.g. via `gh pr comment --body-file`)')
+    .action(runCommand);
+program
+    .command('create <request>')
+    .description('Turn a plain-English request into a saved test file')
+    .option('--url <url>', 'URL to save into the test file')
+    .option('--out <dir>', 'Output directory (default hive/tests)')
+    .action(createCommand);
+program
+    .command('explore <url>')
+    .description('Send a Scout: crawls the site for real (follows links), maps pages, writes starter tests for what it finds')
+    .option('--out <dir>', 'Output directory (default hive/tests/generated)')
+    .action(exploreCommand);
+program
+    .command('coverage')
+    .description('Reads the real git diff, checks which known pages are affected, reports gaps and drafts tests for them — nothing unaffected gets touched')
+    .option('--changed [base]', 'Base ref to diff against (default: main)')
+    .option('--out <dir>', 'Output directory for drafted tests (default hive/tests/generated)')
+    .option('--local', 'Run the browser on this machine instead of the cloud server — use this in CI, where the PR\'s changes usually aren\'t deployed anywhere the server could reach')
+    .option('--headed', 'Local mode only: show the browser window instead of running headless')
+    .option('--pr-comment <path>', 'Write a PR-comment-ready markdown report to this path (post it yourself, e.g. via `gh pr comment --body-file`)')
+    .action(coverageCommand);
+program
+    .command('apply <code>')
+    .description('Pull down a test coverage drafted for a gap — the short code (e.g. amber-fern-cove) is shown in the PR comment')
+    .option('--out <dir>', 'Output directory (default hive/tests/generated)')
+    .action(applyCommand);
+program
+    .command('report')
+    .description("Open this project's most recent run report")
+    .action(reportCommand);
+program
+    .command('history')
+    .description('List runs the hivemind server has executed')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(historyCommand);
+program
+    .command('dashboard')
+    .description("Open the hivemind server's hosted dashboard")
+    .action(dashboardCommand);
+program.parseAsync(process.argv);

package/dist/commands/apply.js

@@ -0,0 +1,33 @@
+import { join } from 'node:path';
+import { getDraftTest } from '../serverClient.js';
+import { saveTestFile, slugify } from '../testFile/write.js';
+/** Pulls down a test `coverage` drafted for a gap it found — identified by the short code
+ *  (e.g. "amber-fern-cove") shown in the PR comment, not by pasting any code. Mirrors Momentic's
+ *  own `apply` command: the actual content lives on the server, the comment only ever shows the
+ *  id, and this is the one command that turns that id into a real file in your project. */
+export async function applyCommand(code, opts) {
+    let draft;
+    try {
+        draft = await getDraftTest(code);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exitCode = 2;
+        return;
+    }
+    const test = {
+        name: draft.name,
+        url: draft.url,
+        tags: draft.tags,
+        params: {},
+        before: [],
+        steps: draft.steps,
+    };
+    const outDir = opts.out || 'hive/tests/generated';
+    const filePath = join(outDir, `${slugify(draft.name)}.md`);
+    await saveTestFile(test, filePath);
+    console.log(`Wrote ${filePath}`);
+    console.log(`  ${test.steps.length} steps, tags: ${test.tags.join(', ') || '(none)'}`);
+    console.log(`  why hivemind drafted this: ${draft.reason}`);
+    console.log(`  review it, then commit it like any other file.`);
+}

package/dist/commands/coverage.js

@@ -0,0 +1,98 @@
+import { join } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { getChangedFiles, getFullDiff } from '../testFile/select.js';
+import { coverageOnServer } from '../serverClient.js';
+import { checkCoverageLocally } from './coverageLocal.js';
+import { saveTestFile, slugify } from '../testFile/write.js';
+import { loadAllTestsFull } from '../testFile/loadAllTests.js';
+import { renderCoveragePrComment } from '../report/prComment.js';
+/**
+ * The actual diff-aware check: reads the real code diff (not just filenames), sends it — plus
+ * every local test with its full steps — to the server. The server figures out which known
+ * pages are genuinely affected, RUNS whichever local tests already target each one (this is the
+ * regression check: your change might break something a test wasn't written for), and only
+ * after that checks whether anything on the page is still left uncovered.
+ */
+export async function coverageCommand(opts) {
+    const cwd = process.cwd();
+    const base = typeof opts.changed === 'string' ? opts.changed : 'main';
+    const changedFiles = getChangedFiles(cwd, base);
+    if (changedFiles.length === 0) {
+        console.log(`No changes vs ${base} — nothing to check.`);
+        return;
+    }
+    const diff = getFullDiff(cwd, base);
+    const localTests = await loadAllTestsFull(cwd);
+    const serverUrl = process.env.HIVEMIND_SERVER_URL || 'https://app.thecolonylab.com';
+    console.log(`🐝 Scout reading the diff (${changedFiles.length} file${changedFiles.length === 1 ? '' : 's'} changed vs ${base})...`);
+    if (opts.local) {
+        console.log(`  🐝 Forager active — browser on this machine, Hivemind brain via ${serverUrl}`);
+    }
+    let result;
+    try {
+        result = opts.local
+            ? await checkCoverageLocally({ serverUrl, diff, localTests, headed: opts.headed })
+            : await coverageOnServer(diff, localTests);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exitCode = 2;
+        return;
+    }
+    // The server only knows its own path (e.g. /artifacts/...) — it has no idea what URL you're
+    // reaching it at (localhost in dev, a real domain in prod), so the full link gets built here.
+    for (const page of result.affectedPages) {
+        for (const t of page.testsRun) {
+            if (t.reportUrl)
+                t.reportUrl = `${serverUrl}${t.reportUrl}`;
+        }
+    }
+    if (!result.affectedPages.length) {
+        console.log('No known pages look affected by this change — nothing to re-check.');
+        if (opts.prComment) {
+            await writeFile(opts.prComment, renderCoveragePrComment([]), 'utf-8');
+            console.log(`PR comment written to ${opts.prComment}`);
+        }
+        return;
+    }
+    const outDir = opts.out || 'hive/tests/generated';
+    let regressions = 0;
+    let gaps = 0;
+    for (const page of result.affectedPages) {
+        console.log(`\n${page.url}${page.isNew ? ' (new)' : ''}`);
+        console.log(`  why: ${page.reason}`);
+        if (!page.testsRun.length) {
+            console.log(`  (no existing test targets this page yet)`);
+        }
+        for (const t of page.testsRun) {
+            const icon = t.status === 'passed' ? '✓' : t.status === 'error' ? '⚠' : '✗';
+            console.log(`  ${icon} ${t.name} — ${t.status}${t.status !== 'passed' ? `: ${t.verdict}` : ''}`);
+            if (t.reportUrl)
+                console.log(`    report: ${t.reportUrl}`);
+            if (t.status !== 'passed')
+                regressions++;
+        }
+        if (!page.proposedTest)
+            continue;
+        gaps++;
+        const test = {
+            name: page.proposedTest.name,
+            url: page.url,
+            tags: page.proposedTest.tags || [],
+            params: {},
+            before: [],
+            steps: page.proposedTest.steps,
+        };
+        const filePath = join(outDir, `${slugify(test.name)}.md`);
+        await saveTestFile(test, filePath);
+        console.log(`  + new gap found — wrote ${filePath} (also saved on the server as "${page.proposedTest.code}" — run \`hivemind apply ${page.proposedTest.code}\` to pull it down anywhere else)`);
+    }
+    console.log(`\n${regressions} regression${regressions === 1 ? '' : 's'}, ${gaps} new gap${gaps === 1 ? '' : 's'} found across ${result.affectedPages.length} affected page${result.affectedPages.length === 1 ? '' : 's'}.`);
+    if (opts.prComment) {
+        await writeFile(opts.prComment, renderCoveragePrComment(result.affectedPages), 'utf-8');
+        console.log(`PR comment written to ${opts.prComment}`);
+    }
+    // Only a broken existing test is a real failure. A drafted test for a new gap is a good outcome
+    // (something to review), not a failure — it shouldn't flip the exit code.
+    process.exitCode = regressions > 0 ? 1 : 0;
+}

package/dist/commands/coverageLocal.js

@@ -0,0 +1,60 @@
+import WebSocket from 'ws';
+import { openSession } from '../browser/session.js';
+import { Forager } from './remoteExecutor.js';
+import { readApiKey } from '../credentials.js';
+/**
+ * `coverage --local` — for the real case a plain cloud coverage check can't handle: the PR's
+ * changed code is only running inside this machine's own sandbox (a CI runner, usually), with no
+ * public URL the server could ever reach. Same split as `runTestLocally`: the browser runs here
+ * (the Forager), the server still does all the deciding — which pages are affected, what's
+ * covered, what to write — this machine just looks at whatever page it's told to.
+ */
+export async function checkCoverageLocally(opts) {
+    const session = await openSession({ headed: opts.headed });
+    const executor = new Forager(session.page, Date.now());
+    try {
+        const wsUrl = opts.serverUrl.replace(/^http/, 'ws') + '/ws/local-coverage';
+        const apiKey = await readApiKey();
+        const result = await new Promise((resolve, reject) => {
+            const headers = { 'User-Agent': 'Hivemind-Forager/0.1.0' };
+            if (apiKey)
+                headers.Authorization = `Bearer ${apiKey}`;
+            const socket = new WebSocket(wsUrl, { headers });
+            socket.on('open', () => {
+                socket.send(JSON.stringify({ type: 'start', diff: opts.diff, localTests: opts.localTests }));
+            });
+            socket.on('message', async (raw) => {
+                let msg;
+                try {
+                    msg = JSON.parse(raw.toString());
+                }
+                catch {
+                    return;
+                }
+                if (msg.type === 'call') {
+                    const toolResult = await executor.execute(msg.name, msg.input);
+                    socket.send(JSON.stringify({ type: 'result', callId: msg.callId, ...toolResult }));
+                    return;
+                }
+                if (msg.type === 'finish') {
+                    resolve(msg.result);
+                    socket.close();
+                    return;
+                }
+                if (msg.type === 'error') {
+                    reject(new Error(msg.message));
+                    socket.close();
+                }
+            });
+            socket.on('error', (err) => reject(err));
+            socket.on('close', (code) => {
+                if (code !== 1000 && code !== 1005)
+                    reject(new Error(`Connection to hivemind server closed unexpectedly (code ${code})`));
+            });
+        });
+        return result;
+    }
+    finally {
+        await session.close();
+    }
+}

package/dist/commands/create.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { createOnServer } from '../serverClient.js';
+import { saveTestFile, slugify } from '../testFile/write.js';
+import { listExistingTests } from '../testFile/listExisting.js';
+import { loadConfig } from '../config.js';
+export async function createCommand(request, opts) {
+    const cwd = process.cwd();
+    const existingTests = await listExistingTests(cwd);
+    const config = await loadConfig(cwd);
+    const accountLabels = Object.keys(config.accounts || {});
+    let proposed;
+    try {
+        proposed = await createOnServer(request, opts.url, existingTests, accountLabels);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exitCode = 2;
+        return;
+    }
+    const test = {
+        name: proposed.name,
+        url: opts.url,
+        login: proposed.login,
+        tags: proposed.tags || [],
+        params: proposed.params || {},
+        before: (proposed.before || []).map((b) => ({ name: b.name, params: b.params || {} })),
+        steps: proposed.steps,
+    };
+    const outDir = opts.out || 'hive/tests';
+    const filePath = join(outDir, `${slugify(proposed.name)}.md`);
+    await saveTestFile(test, filePath);
+    console.log(`Wrote ${filePath}`);
+    console.log(`  ${test.steps.length} steps, tags: ${test.tags.join(', ') || '(none)'}`);
+    if (test.before.length) {
+        console.log(`  reused existing test(s) as precondition: ${test.before.map((b) => b.name).join(', ')}`);
+    }
+    console.log(proposed.grounded
+        ? `  grounded: looked at the real page at ${opts.url} before drafting these steps`
+        : `  blind guess: no --url given, drafted from common patterns only — review carefully`);
+}

package/dist/commands/dashboard.js

@@ -0,0 +1,12 @@
+import { exec } from 'node:child_process';
+/**
+ * The dashboard is now hosted BY the hivemind server (it has real, shared, multi-machine data —
+ * every run any CLI has ever submitted). This command is just a convenience shortcut to open it;
+ * there is no local dashboard server anymore.
+ */
+export async function dashboardCommand() {
+    const url = process.env.HIVEMIND_SERVER_URL || 'https://app.thecolonylab.com';
+    console.log(`Opening ${url}`);
+    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    exec(`${opener} "${url}"`);
+}

package/dist/commands/explore.js

@@ -0,0 +1,34 @@
+import { join } from 'node:path';
+import { exploreOnServer } from '../serverClient.js';
+import { saveTestFile, slugify } from '../testFile/write.js';
+import { listExistingTests } from '../testFile/listExisting.js';
+/**
+ * A real multi-page crawl, not a one-shot snapshot — the server maps pages, follows doors, and
+ * proposes starter tests along the way. Existing tests are sent along (same pattern `create`
+ * uses) so it doesn't propose a duplicate for a flow already covered.
+ */
+export async function exploreCommand(url, opts) {
+    console.log(`🐝 Scout dispatched to ${url}...`);
+    const existingTests = await listExistingTests(process.cwd());
+    let proposed;
+    try {
+        proposed = await exploreOnServer(url, existingTests);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exitCode = 2;
+        return;
+    }
+    const outDir = opts.out || 'hive/tests/generated';
+    const written = [];
+    for (const p of proposed) {
+        const test = { name: p.name, url, tags: p.tags || [], params: {}, before: [], steps: p.steps };
+        const filePath = join(outDir, `${slugify(p.name)}.md`);
+        await saveTestFile(test, filePath);
+        written.push(filePath);
+    }
+    console.log(`\nWrote ${written.length} starter test${written.length === 1 ? '' : 's'} to ${outDir}/:`);
+    for (const f of written)
+        console.log(`  ${f}`);
+    console.log(`\nReview and edit these like any other code, then run: hivemind run ${outDir}/`);
+}

package/dist/commands/init.js

@@ -0,0 +1,50 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { mkdir, readFile, writeFile, copyFile, access } from 'node:fs/promises';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// dist/commands/init.js -> package root (skill/ ships alongside dist/, see package.json "files")
+const packageRoot = join(__dirname, '..', '..');
+async function exists(path) {
+    return access(path)
+        .then(() => true)
+        .catch(() => false);
+}
+/**
+ * One-time setup for a project adopting hivemind — matches TesterArmy's `ta agent init` pattern.
+ * Idempotent: safe to run again later, never overwrites something already there.
+ */
+export async function initCommand() {
+    const cwd = process.cwd();
+    await mkdir(join(cwd, 'hive', 'tests'), { recursive: true });
+    console.log('✓ hive/tests/ ready');
+    const configPath = join(cwd, 'hivemind.config.json');
+    if (await exists(configPath)) {
+        console.log('- hivemind.config.json already exists, left untouched');
+    }
+    else {
+        const starter = {
+            environments: { default: 'http://localhost:3000' },
+            accounts: {},
+            areas: {},
+        };
+        await writeFile(configPath, JSON.stringify(starter, null, 2) + '\n', 'utf-8');
+        console.log('✓ hivemind.config.json created — edit environments.default to match your app');
+    }
+    const agentsPath = join(cwd, 'AGENTS.md');
+    const template = await readFile(join(packageRoot, 'skill', 'AGENTS.md.template'), 'utf-8');
+    const existingAgents = (await exists(agentsPath)) ? await readFile(agentsPath, 'utf-8') : '';
+    if (existingAgents.includes('<!-- HIVEMIND:START -->')) {
+        console.log('- AGENTS.md already has the hivemind block, left untouched');
+    }
+    else {
+        const updated = existingAgents ? `${existingAgents.trimEnd()}\n\n${template}` : template;
+        await writeFile(agentsPath, updated, 'utf-8');
+        console.log(existingAgents ? '✓ AGENTS.md updated with hivemind instructions' : '✓ AGENTS.md created with hivemind instructions');
+    }
+    const skillDir = join(cwd, '.agents', 'skills', 'hivemind-cli');
+    await mkdir(skillDir, { recursive: true });
+    await copyFile(join(packageRoot, 'skill', 'hivemind-cli', 'SKILL.md'), join(skillDir, 'SKILL.md'));
+    console.log('✓ .agents/skills/hivemind-cli/SKILL.md installed');
+    console.log('\nDone. A coding agent working in this repo now knows how to use hivemind.');
+    console.log('Next: hivemind create "<what to test>" --url <your app url>');
+}

package/dist/commands/login.js

@@ -0,0 +1,20 @@
+import { writeApiKey } from '../credentials.js';
+import { serverUrl } from '../serverClient.js';
+/** Stores an API key generated from the web dashboard's Settings page — the CLI has no browser,
+ *  so it can't sign in the normal way; this is the whole auth story for it. */
+export async function loginCommand(key) {
+    if (!key.startsWith('hm_')) {
+        console.error('That doesn\'t look like a hivemind API key (should start with "hm_"). Generate one from the dashboard\'s Settings page.');
+        process.exitCode = 1;
+        return;
+    }
+    const res = await fetch(`${serverUrl()}/api/auth/me`, { headers: { Authorization: `Bearer ${key}` } }).catch(() => null);
+    if (!res || !res.ok) {
+        console.error(`Could not verify that key against ${serverUrl()} — check the key and that HIVEMIND_SERVER_URL is correct.`);
+        process.exitCode = 1;
+        return;
+    }
+    const user = (await res.json());
+    await writeApiKey(key);
+    console.log(`✓ Signed in as ${user.email}`);
+}