@thecolonylab/hivemind 0.1.0 → 0.1.3

package/dist/commands/coverage.js

@@ -39,7 +39,7 @@ export async function coverageCommand(opts) {
         process.exitCode = 2;
         return;
     }
-    // The server only knows its own path (e.g. /artifacts/...) — it has no idea what URL you're
+    // The server only knows its own path (e.g. /runs/...) — 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) {

package/dist/commands/init.js

@@ -1,6 +1,9 @@
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { mkdir, readFile, writeFile, copyFile, access } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
 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, '..', '..');
@@ -9,6 +12,53 @@ async function exists(path) {
         .then(() => true)
         .catch(() => false);
 }
+/**
+ * Cloud mode (the default) never touches Playwright on this machine at all — the browser lives on
+ * the server. But `--local` mode does, and the starter hivemind.config.json defaults to
+ * localhost:3000, so most fresh projects are headed toward --local sooner or later. Checking here
+ * means the first `--local` run doesn't stall on an unexpected multi-minute download mid-test —
+ * `chromium.executablePath()` is a cheap path lookup, not a launch, so this stays fast when the
+ * browser's already installed (every run after the first).
+ */
+async function ensureLocalBrowser() {
+    const { chromium } = await import('playwright');
+    const installed = await exists(chromium.executablePath());
+    if (installed) {
+        console.log('✓ local browser (for --local mode) already installed');
+        return;
+    }
+    console.log('⧗ downloading local browser for --local mode (one-time, ~150MB)...');
+    try {
+        await execFileAsync('npx', ['playwright', 'install', 'chromium']);
+        console.log('✓ local browser installed');
+    }
+    catch (err) {
+        console.log(`- couldn't auto-install the local browser (${err?.message || err}) — run \`npx playwright install chromium\` yourself before using --local`);
+    }
+}
+const GITIGNORE_BLOCK = `# HIVEMIND:START
+# hivemind local state — real evidence (screenshots, run history, folded-in memory), but not
+# meant to be reviewed in a PR the way hive/tests/ is. Regenerated by every run, safe to delete.
+hive/history/
+hive/artifacts/
+hive/memory.md
+hive/last-run.json
+# HIVEMIND:END
+`;
+/** One hive/ folder for everything — tests/ is the only part meant to be committed and reviewed;
+ *  history/, artifacts/, memory.md, and last-run.json are local-only, excluded here rather than
+ *  living in a separate dot-prefixed folder. */
+async function ensureGitignore(cwd) {
+    const path = join(cwd, '.gitignore');
+    const existing = (await exists(path)) ? await readFile(path, 'utf-8') : '';
+    if (existing.includes('# HIVEMIND:START')) {
+        console.log('- .gitignore already has the hivemind block, left untouched');
+        return;
+    }
+    const updated = existing ? `${existing.trimEnd()}\n\n${GITIGNORE_BLOCK}` : GITIGNORE_BLOCK;
+    await writeFile(path, updated, 'utf-8');
+    console.log(existing ? '✓ .gitignore updated so hive/history, artifacts, memory stay local-only' : '✓ .gitignore created so hive/history, artifacts, memory stay local-only');
+}
 /**
  * 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.
@@ -17,6 +67,7 @@ export async function initCommand() {
     const cwd = process.cwd();
     await mkdir(join(cwd, 'hive', 'tests'), { recursive: true });
     console.log('✓ hive/tests/ ready');
+    await ensureGitignore(cwd);
     const configPath = join(cwd, 'hivemind.config.json');
     if (await exists(configPath)) {
         console.log('- hivemind.config.json already exists, left untouched');
@@ -45,6 +96,7 @@ export async function initCommand() {
     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');
+    await ensureLocalBrowser();
     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/remoteExecutor.js

@@ -1,3 +1,4 @@
+const MAX_BROWSER_LOGS = 200;
 /**
  * The Forager — runs on your machine, executes exactly what the Hivemind brain tells it to, one
  * named tool call at a time. Same `execute(name, input)` shape used in-process on the server for
@@ -11,14 +12,55 @@ export class Forager {
     runStart;
     pageStack = [];
     screenshots = [];
+    browserLogs = [];
     constructor(page, runStart) {
         this.page = page;
         this.runStart = runStart;
+        this.attachLogging(page);
+    }
+    /** Same reasoning as the server's ToolExecutor: a click can succeed while the page underneath
+     *  throws a JS error or a fetch 500s, and the report today has no way to show that. This is the
+     *  ONLY side that ever sees these events for a --local run — the server never opened this
+     *  browser — so every call's result carries the full accumulated log back over the socket
+     *  (see execute() below); RemoteToolRunner just keeps the latest one it receives. */
+    attachLogging(page) {
+        const push = (entry) => {
+            if (this.browserLogs.length < MAX_BROWSER_LOGS)
+                this.browserLogs.push(entry);
+        };
+        page.on('console', (msg) => {
+            if (msg.type() === 'log' || msg.type() === 'debug')
+                return;
+            push({ type: 'console', level: msg.type(), text: msg.text().slice(0, 500), elapsedMs: Date.now() - this.runStart });
+        });
+        page.on('pageerror', (err) => {
+            push({ type: 'console', level: 'error', text: err.message.slice(0, 500), elapsedMs: Date.now() - this.runStart });
+        });
+        page.on('requestfailed', (req) => {
+            push({
+                type: 'network',
+                level: 'failed',
+                text: `${req.method()} ${req.url()} — ${req.failure()?.errorText || 'failed'}`.slice(0, 500),
+                elapsedMs: Date.now() - this.runStart,
+            });
+        });
+        page.on('response', (res) => {
+            if (res.status() < 400)
+                return;
+            push({ type: 'network', level: String(res.status()), text: `${res.request().method()} ${res.url()} → ${res.status()}`.slice(0, 500), elapsedMs: Date.now() - this.runStart });
+        });
     }
     getScreenshots() {
         return this.screenshots;
     }
+    getBrowserLogs() {
+        return this.browserLogs;
+    }
     async execute(name, input) {
+        const result = await this.executeInner(name, input);
+        return { ...result, browserLogs: this.browserLogs };
+    }
+    async executeInner(name, input) {
         try {
             switch (name) {
                 case 'browser_navigate': {
@@ -170,6 +212,7 @@ export class Forager {
         await newPage.waitForLoadState('domcontentloaded', { timeout: 10_000 }).catch(() => { });
         this.pageStack.push(prevPage);
         this.page = newPage;
+        this.attachLogging(newPage);
         newPage.on('close', () => {
             if (this.page === newPage) {
                 const fallback = this.pageStack.pop();

package/dist/commands/report.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { exec } from 'node:child_process';
+import { readApiKey } from '../credentials.js';
 function serverUrl() {
     return process.env.HIVEMIND_SERVER_URL || 'https://app.thecolonylab.com';
 }
@@ -9,7 +10,7 @@ function open(url) {
     exec(`${opener} "${url}"`);
 }
 export async function reportCommand() {
-    const pointerPath = join(process.cwd(), '.hive', 'last-run.json');
+    const pointerPath = join(process.cwd(), 'hive', 'last-run.json');
     try {
         const pointer = JSON.parse(await readFile(pointerPath, 'utf-8'));
         console.log(`Opening ${pointer.reportUrl}`);
@@ -21,9 +22,15 @@ export async function reportCommand() {
 }
 export async function historyCommand(opts) {
     const url = `${serverUrl()}/api/runs`;
-    const res = await fetch(url).catch(() => null);
+    const apiKey = await readApiKey();
+    const res = await fetch(url, apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : undefined).catch(() => null);
     if (!res || !res.ok) {
-        console.error(`Could not reach hivemind server at ${serverUrl()}. Is it running? (hivemind-server)`);
+        if (res?.status === 401) {
+            console.error(`Not signed in — run "hivemind login <key>" (get a key from the dashboard's Settings page).`);
+        }
+        else {
+            console.error(`Could not reach hivemind server at ${serverUrl()}. Is it running? (hivemind-server)`);
+        }
         process.exitCode = 2;
         return;
     }

package/dist/commands/run.js

@@ -24,15 +24,15 @@ async function runPool(items, limit, worker) {
 }
 async function readLocalMemory(cwd) {
     try {
-        return await readFile(join(cwd, '.hive', 'memory.md'), 'utf-8');
+        return await readFile(join(cwd, 'hive', 'memory.md'), 'utf-8');
     }
     catch {
         return '';
     }
 }
 async function writeLocalMemory(cwd, content) {
-    const path = join(cwd, '.hive', 'memory.md');
-    await mkdir(join(cwd, '.hive'), { recursive: true });
+    const path = join(cwd, 'hive', 'memory.md');
+    await mkdir(join(cwd, 'hive'), { recursive: true });
     await writeFile(path, content, 'utf-8');
 }
 export async function runCommand(target, opts) {
@@ -81,7 +81,7 @@ export async function runCommand(target, opts) {
             console.error(`✗ ${test.name}: ${err.message}`);
             results[index] = {
                 name: test.name,
-                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], durationMs: 0 },
+                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], browserLogs: [], durationMs: 0 },
             };
             return;
         }
@@ -95,7 +95,7 @@ export async function runCommand(target, opts) {
             console.error(`✗ ${test.name}: ${message}`);
             results[index] = {
                 name: test.name,
-                result: { status: 'error', verdict: message, steps: [], toolLog: [], screenshots: [], durationMs: 0 },
+                result: { status: 'error', verdict: message, steps: [], toolLog: [], screenshots: [], browserLogs: [], durationMs: 0 },
             };
             return;
         }
@@ -116,7 +116,7 @@ export async function runCommand(target, opts) {
                     credential,
                     headed: opts.headed,
                 });
-                await writeFile(join(cwd, '.hive', 'last-run.json'), JSON.stringify({ reportUrl: reportPath, name: test.name }, null, 2)).catch(() => { });
+                await writeFile(join(cwd, 'hive', 'last-run.json'), JSON.stringify({ reportUrl: reportPath, name: test.name }, null, 2)).catch(() => { });
                 results[index] = { name: test.name, result, reportUrl: reportPath };
                 if (!opts.json) {
                     printResult(test.name, result);
@@ -133,7 +133,7 @@ export async function runCommand(target, opts) {
                 });
                 const reportUrl = `${serverUrl}${reportPath}`;
                 await writeLocalMemory(cwd, updatedMemory).catch(() => { });
-                await writeFile(join(cwd, '.hive', 'last-run.json'), JSON.stringify({ reportUrl, name: test.name }, null, 2)).catch(() => { });
+                await writeFile(join(cwd, 'hive', 'last-run.json'), JSON.stringify({ reportUrl, name: test.name }, null, 2)).catch(() => { });
                 results[index] = { name: test.name, result, reportUrl };
                 if (!opts.json) {
                     printResult(test.name, result);
@@ -145,7 +145,7 @@ export async function runCommand(target, opts) {
             console.error(`✗ ${test.name}: ${err.message}`);
             results[index] = {
                 name: test.name,
-                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], durationMs: 0 },
+                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], browserLogs: [], durationMs: 0 },
             };
         }
     });

package/dist/commands/runLocal.js

@@ -40,6 +40,7 @@ export async function runTestLocally(opts) {
     try {
         const wsUrl = opts.serverUrl.replace(/^http/, 'ws') + '/ws/local-run';
         const apiKey = await readApiKey();
+        let hostedReportUrl;
         const result = await new Promise((resolve, reject) => {
             const headers = { 'User-Agent': 'Hivemind-Forager/0.1.0' };
             if (apiKey)
@@ -69,6 +70,7 @@ export async function runTestLocally(opts) {
                     return;
                 }
                 if (msg.type === 'finish') {
+                    hostedReportUrl = msg.reportUrl;
                     resolve(msg.result);
                     socket.close();
                     return;
@@ -89,7 +91,9 @@ export async function runTestLocally(opts) {
         await session.close();
         closed = true;
         await writeRunArtifacts(opts.cwd, runId, opts.name, result);
-        const reportPath = `${artifactDirFor(opts.cwd, runId)}/report.html`;
+        // Prefer the real, hosted, shareable report (shows up in the dashboard's Runs list) — the
+        // local file written above is just a backup for offline viewing, same data either way.
+        const reportPath = hostedReportUrl ? `${opts.serverUrl}${hostedReportUrl}` : `${artifactDirFor(opts.cwd, runId)}/report.html`;
         return { result, reportPath };
     }
     finally {

package/dist/report/artifacts.js

@@ -5,8 +5,11 @@ import { slugify } from '../testFile/write.js';
 function timestampDir() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/** Everything lives under one hive/ folder — tests/ is the committed part, history/ and
+ *  artifacts/ are local-only and gitignored (see `hivemind init`'s .gitignore rules). One folder
+ *  to look in instead of splitting state across hive/ and a separate .hive/. */
 export function artifactDirFor(cwd, runId) {
-    return join(cwd, 'artifacts', runId);
+    return join(cwd, 'hive', 'artifacts', runId);
 }
 /** Creates the artifact directory for a run BEFORE it starts, so ToolExecutor can write screenshots into it. */
 export async function createArtifactDir(cwd, testName) {
@@ -20,7 +23,7 @@ export async function writeRunArtifacts(cwd, runId, testName, result) {
     const artifactDir = artifactDirFor(cwd, runId);
     const html = renderHtmlReport(testName, result);
     await writeFile(join(artifactDir, 'report.html'), html, 'utf-8');
-    const historyDir = join(cwd, '.hive', 'history');
+    const historyDir = join(cwd, 'hive', 'history');
     await mkdir(historyDir, { recursive: true });
     const entry = {
         name: testName,
@@ -34,7 +37,7 @@ export async function writeRunArtifacts(cwd, runId, testName, result) {
     return artifactDir;
 }
 export async function readHistory(cwd) {
-    const historyDir = join(cwd, '.hive', 'history');
+    const historyDir = join(cwd, 'hive', 'history');
     try {
         const files = await readdir(historyDir);
         const entries = await Promise.all(files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecolonylab/hivemind",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Forager — the CLI that runs on your machine and executes for the Hivemind brain. Describe a flow in plain English, an AI agent drives a real browser and reports pass/fail. No LLM key needed on this machine.",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
   "dependencies": {
     "commander": "^12.1.0",
     "dotenv": "^17.4.2",
-    "playwright": "^1.48.0",
+    "playwright": "1.48.0",
     "ws": "^8.21.0"
   },
   "devDependencies": {

package/skill/AGENTS.md.template

@@ -6,8 +6,9 @@ code or selectors required.
 
 - **Skill:** see `.agents/skills/hivemind-cli/SKILL.md` for the full command reference, test file
   format, login/precondition conventions, and how to read results.
-- **Setup check:** `hivemind --help`; server defaults to `http://localhost:4321` unless
-  `HIVEMIND_SERVER_URL` is set.
+- **Setup check:** `hivemind --help`; the CLI talks to the hosted server at
+  `https://app.thecolonylab.com` by default — only set `HIVEMIND_SERVER_URL` if pointing at a
+  self-hosted server instead.
 - **Default workflow:** right after building or changing a UI flow, write or generate a test in
   `hive/tests/`, run it with `hivemind run <file> --url <url> --json`, and fix your own code if it
   fails — before telling the user the feature is done.

package/skill/hivemind-cli/SKILL.md

@@ -25,7 +25,7 @@ machine — the hivemind server (wherever `HIVEMIND_SERVER_URL` points) holds it
 
 ```bash
 hivemind --help
-echo $HIVEMIND_SERVER_URL   # if unset, defaults to http://localhost:4321
+echo $HIVEMIND_SERVER_URL   # if unset, defaults to the hosted server at https://app.thecolonylab.com
 ```
 
 If the command isn't found, it isn't installed — tell the user rather than trying to work around it.
@@ -50,6 +50,17 @@ hivemind explore <url>
 # Open the most recent run's report, or list past runs.
 hivemind report
 hivemind history [--json]
+
+# Diff-aware regression check — for CI, or before opening a PR. Reads the real git diff, figures
+# out which known pages are affected, RE-RUNS whatever local tests already touch them (this is
+# the actual regression check), and drafts a new test for any genuine gap left uncovered. Add
+# --local when testing a build that only exists on this machine/runner (same reasoning as `run`).
+# --pr-comment <path> writes a ready-to-post markdown report (numbered pass/fail + report links).
+hivemind coverage [--changed <base>] [--local] [--pr-comment <path>]
+
+# Pull down a test `coverage` drafted for a gap — identified by a short code (e.g.
+# "amber-fern-cove") shown in its output/PR comment, not by pasting any code.
+hivemind apply <code>
 ```
 
 Always use `--json` on `run` when you (the agent) are consuming the result programmatically — it