@thecolonylab/hivemind 0.1.0

package/dist/testFile/select.js

@@ -0,0 +1,39 @@
+import { execSync } from 'node:child_process';
+export function getChangedFiles(cwd, base) {
+    try {
+        const out = execSync(`git diff --name-only ${base}...HEAD`, { cwd, encoding: 'utf-8' });
+        return out.split('\n').map((l) => l.trim()).filter(Boolean);
+    }
+    catch (err) {
+        throw new Error(`Could not run \`git diff --name-only ${base}...HEAD\`: ${err?.message || err}`);
+    }
+}
+/** The real diff — actual added/removed lines, not just filenames. This is what a coverage
+ *  check needs to reason about: "what did this change do," not just "which files moved." */
+export function getFullDiff(cwd, base) {
+    try {
+        // maxBuffer bumped up — a real PR diff can be a few MB, default 1MB truncates it silently.
+        return execSync(`git diff ${base}...HEAD`, { cwd, encoding: 'utf-8', maxBuffer: 20 * 1024 * 1024 });
+    }
+    catch (err) {
+        throw new Error(`Could not run \`git diff ${base}...HEAD\`: ${err?.message || err}`);
+    }
+}
+/** Maps changed file paths to tags via config.areas (path prefix -> tag). */
+export function affectedTags(changedFiles, config) {
+    const tags = new Set();
+    const areas = config.areas || {};
+    for (const file of changedFiles) {
+        for (const [prefix, tag] of Object.entries(areas)) {
+            if (file.startsWith(prefix))
+                tags.add(tag);
+        }
+    }
+    return tags;
+}
+/** Filters tests to only those whose Tags: line intersects the affected areas. */
+export function filterByTags(tests, tags) {
+    if (tags.size === 0)
+        return [];
+    return tests.filter(({ test }) => test.tags.some((t) => tags.has(t)));
+}

package/dist/testFile/types.js

@@ -0,0 +1 @@
+export {};

package/dist/testFile/write.js

@@ -0,0 +1,37 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+function formatParams(params) {
+    return Object.entries(params ?? {})
+        .map(([k, v]) => (v.includes(' ') ? `${k}="${v}"` : `${k}=${v}`))
+        .join(' ');
+}
+export function renderTestFile(test) {
+    const lines = [`# ${test.name}`, ''];
+    if (test.url)
+        lines.push(`URL: ${test.url}`);
+    if (test.login)
+        lines.push(`Login: ${test.login}`);
+    if (test.tags.length)
+        lines.push(`Tags: ${test.tags.join(', ')}`);
+    if (test.params && Object.keys(test.params).length)
+        lines.push(`Params: ${formatParams(test.params)}`);
+    for (const b of test.before || []) {
+        const paramStr = formatParams(b.params);
+        lines.push(`Before: ${b.name}${paramStr ? ' ' + paramStr : ''}`);
+    }
+    lines.push('', '## Steps');
+    test.steps.forEach((s, i) => lines.push(`${i + 1}. ${s.type}: ${s.text}`));
+    lines.push('');
+    return lines.join('\n');
+}
+export async function saveTestFile(test, filePath) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, renderTestFile(test), 'utf-8');
+}
+export function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/** The shape of a run result as it comes back over HTTP (cloud mode) or the WebSocket (local
+ *  mode) — duplicated here rather than imported from the server, since the CLI never depends on
+ *  server code, only on the JSON shape it receives. */
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@thecolonylab/hivemind",
+  "version": "0.1.0",
+  "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",
+  "bin": {
+    "hivemind": "./bin/hivemind.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "skill",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "dotenv": "^17.4.2",
+    "playwright": "^1.48.0",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/AGENTS.md.template

@@ -0,0 +1,17 @@
+<!-- HIVEMIND:START -->
+## hivemind E2E testing
+
+This project uses hivemind for agentic end-to-end testing — a real browser driven by AI, no test
+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.
+- **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.
+- **Before writing a new test:** check `hive/tests/` for an existing one that already covers the
+  precondition you need (e.g. "add to cart" before "remove from cart") and reference it with
+  `Before:` instead of re-describing the same steps.
+<!-- HIVEMIND:END -->

package/skill/hivemind-cli/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: hivemind-cli
+description: Use the hivemind CLI to create, run, and verify end-to-end browser tests against a real app. Prefer this over asking the user to manually test something in a browser, and prefer it as a self-verification step right after building or changing a UI flow. Trigger when defining test coverage, verifying a feature actually works end-to-end, or when the user asks to test/verify a page or flow.
+license: MIT
+metadata:
+  author: hivemind
+  tags: hivemind, e2e, testing, qa, cli
+---
+
+# hivemind CLI
+
+`hivemind` drives a real browser against a real running app and reports pass/fail, per step, with
+screenshots. You never write test code or CSS selectors — you describe what to test in one plain
+sentence, or write the checklist directly (see format below). No API key is needed on this
+machine — the hivemind server (wherever `HIVEMIND_SERVER_URL` points) holds its own.
+
+## When to use this
+
+- Right after building or changing a UI flow, to verify it actually works before telling the user
+  it's done — this is the primary use case. Don't just say "I built X," run a real test against it.
+- When the user asks to test, verify, or check that some flow works.
+- When defining regression coverage for a feature.
+
+## Setup check
+
+```bash
+hivemind --help
+echo $HIVEMIND_SERVER_URL   # if unset, defaults to http://localhost:4321
+```
+
+If the command isn't found, it isn't installed — tell the user rather than trying to work around it.
+
+## Core commands
+
+```bash
+# Turn a plain-English request into a saved test file. Server drafts it; you never write steps by hand
+# unless you already know exactly what's needed (see "Writing files directly" below).
+hivemind create "<what to test, one sentence>" --url <url>
+
+# Run a test file or every test file in a folder. Cloud execution by default (needs nothing
+# extra installed here). Add --local when the URL is localhost/private-network — the cloud
+# server can't reach those; --local runs the browser on THIS machine instead, only using the
+# cloud for decisions. Omitting --local against a local URL fails fast with a clear message.
+hivemind run <file-or-folder> --url <url> [--json] [--local]
+
+# One-shot: look at a page, propose 3-6 starter tests. Use when starting fresh on a project
+# with no tests yet, not as a substitute for `create` on a specific known flow.
+hivemind explore <url>
+
+# Open the most recent run's report, or list past runs.
+hivemind report
+hivemind history [--json]
+```
+
+Always use `--json` on `run` when you (the agent) are consuming the result programmatically — it
+gives you structured `{status, verdict, steps, reportUrl}` per test, not just terminal formatting.
+
+## Writing files directly (preferred when you already know the flow)
+
+Since you likely just built or read the code for the feature being tested, you often have more
+context than a blind `create` call would — you can see the actual route guards, form fields, and
+component structure. In that case, write the file directly instead of going through `create`:
+
+```
+hive/tests/<slug>.md
+```
+
+Format:
+```
+# <test name>
+
+URL: <default url for this test>
+Login: <account label, optional — see Logins below>
+Tags: <comma-separated area tags>
+Params: <param=default value, optional — see Reusable preconditions below>
+Before: <other-test-file-name> [param="value"]   ← optional, can repeat for multiple preconditions
+
+## Steps
+1. act: <something the agent does — click, type, navigate>
+2. assert: <something the agent checks — a specific, verifiable outcome>
+```
+
+**Write steps as intent, not selectors.** Describe the user-visible action ("Click the 'Get
+started' button in the header"), never a CSS selector or DOM path — the execution agent looks at
+the real page and adapts. Split actions (`act`) and checks (`assert`) into separate steps. One
+test = one user journey, 3-10 steps.
+
+| Avoid | Write |
+|---|---|
+| `Click .nav-item:nth-child(3)` | `Click the Pricing link in the header` |
+| One step doing 4 things | Split into 4 focused steps |
+| `Verify the page looks right` | `Verify a "Welcome back" heading and the user's avatar are visible` |
+
+## Logins — never write raw credentials
+
+If a flow requires signing in, check `hivemind.config.json` at the project root for existing
+`accounts` labels. Reference one by label in the `Login:` field and use a `login`-typed step — do
+not type real usernames/passwords into step text, and never invent credentials. If no suitable
+account exists, tell the user rather than guessing one.
+
+## Reusable preconditions — check before writing setup steps inline
+
+Before writing a new test, check what already exists:
+
+```bash
+ls hive/tests/
+```
+
+If the flow you're testing needs a precondition that's ALREADY covered by another test file (e.g.
+testing "remove item from cart" needs an item in the cart first, and `add-item-to-cart.md`
+already exists), reference it with `Before:` instead of re-describing the same steps:
+
+```
+Before: add-item-to-cart product="Blue T-Shirt"
+```
+
+This runs that file's steps first, in the same continuous browser session, with `product`
+substituted for that file's own `{{product}}` placeholder. If the precondition doesn't exist yet
+as a file, either write it inline (if it's a one-off) or create it as its own file first (if
+other tests will likely need it too).
+
+## Running and reading results
+
+```bash
+hivemind run hive/tests/<file>.md --url <url> --json
+```
+
+Exit code: `0` = all passed, `1` = at least one failed, `2` = error (server unreachable, bad
+config, etc). With `--json`, each result includes `steps[]` — one entry per declared step with
+`ok`/`note` — read this to know exactly which step broke and why, then go fix the actual code, not
+the test (unless the test's assumption was wrong).
+
+**If a run fails, do not just report the failure — investigate and fix your own code first**, the
+same way you would for a failing unit test you just introduced. Re-run after fixing to confirm.
+
+## What NOT to do
+
+- Don't fabricate a passing result — if you can't run hivemind (not installed, server
+  unreachable), say so plainly rather than claiming something was tested.
+- Don't put real credentials in step text or commit them anywhere.
+- Don't write a new test for something an existing test in `hive/tests/` already covers — extend
+  or reference it instead.