keepgreen 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.1
+
+- OpenRouter and other OpenAI-compatible endpoints in the GitHub Action: new `base-url`, `api-key`, `price-in` and `price-out` inputs (the template shows them commented out). The README has an OpenRouter section.
+- `keepgreen explore` sets `KEEPGREEN=1` for the app and the tests, so a Playwright `webServer` can reuse the app KeepGreen started: `reuseExistingServer: !process.env.CI || !!process.env.KEEPGREEN`. Without it, Playwright stops in CI with "port already in use".
+- Explore workflow template: a blank `max-flows` input now keeps the value from `.keepgreen.yml` (it used to force 3).
+- A refused AI request (no credit, bad key) now prints a short reason and what to do, instead of a stack trace.
+- First release published from CI with npm provenance (0.1.0 was published by hand).
+
+## 0.1.0
+
+First release.
+
+- `keepgreen explore`: looks at your app (playwright-e2e-mcp `inspect-page`), reads which tests already exist, asks your AI for the most important user flows with no test, and writes a test for each with AutoHeal's `cover`. A test is kept only if it passes the new-test guard (real assertions, no fakes, skips or fixed waits) and runs green several times in a row. One spend cap covers the whole run.
+- `keepgreen heal`: AutoHeal's local `fix` (run the tests, fix what broke, leave the changes for review).
+- `keepgreen init`: writes `.keepgreen.yml`, the explore workflow (read-only explore job + publish job that only accepts new test files) and AutoHeal's heal workflow.
+- `keepgreen doctor`, `keepgreen autoheal <command>`, `keepgreen check-patch`.
+- GitHub Action (`xsignon-secure/keepgreen@v0.1.0`) and a Docker Compose bundle for the self-hosted history server and AutoHeal dashboard.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XSignOn
+
+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/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# KeepGreen
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Your AI test agent that writes, fixes and keeps your end-to-end tests green.**
+
+KeepGreen is free and MIT licensed. It runs on your own CI runner or laptop with your own AI key
+(Anthropic, OpenAI or any OpenAI-compatible endpoint, including local models). There is no
+KeepGreen server, no account and no telemetry. You pay only your AI provider, and one spend cap
+covers every run.
+
+It combines two XSignOn projects into one agent:
+
+- [playwright-e2e-mcp](https://github.com/xsignon-secure/E2E) is the toolbox. It opens pages,
+  finds stable locators, runs tests and reads failures.
+- [AutoHeal](https://github.com/xsignon-secure/AutoHeal-AI) is the guarded fixer and test writer,
+  with its anti-cheat guard and stability proof.
+
+| Recipe | What it does | Command |
+| --- | --- | --- |
+| **Explore** | Looks at your app, picks the most important user flows that have **no test yet**, and writes a test for each. A test is kept only if it makes real assertions and passes every run (5 by default). | `npx keepgreen explore` |
+| **Heal** | Runs your tests, finds what broke, fixes it and proves the fix. App bugs are reported, not "fixed". | `npx keepgreen heal` (local) · AutoHeal workflow (CI) |
+
+Works with Playwright Test and pytest-playwright. Healing also covers Cypress and WebdriverIO.
+
+## Quick start (your machine)
+
+```bash
+npm install -D keepgreen              # or use npx keepgreen ... without installing
+export ANTHROPIC_API_KEY=sk-ant-...   # your own key
+npx keepgreen init                    # writes .keepgreen.yml + workflows, checks your setup
+npx keepgreen explore --url http://localhost:3000
+```
+
+Explore prints a table of the flows it tried and which tests it kept. New files are named
+`tests/keepgreen-<flow>.spec.ts`. Review them with `git diff` and commit the ones you like.
+
+Try it without writing anything first:
+
+```bash
+npx keepgreen explore --url http://localhost:3000 --dry-run   # plan only: shows the flows it would test
+```
+
+Let KeepGreen start your app:
+
+```bash
+npx keepgreen explore --start-command "npm run dev" --start-url http://localhost:3000
+```
+
+Fix broken tests:
+
+```bash
+npx keepgreen heal          # = AutoHeal's `autoheal fix`; changes stay in your working tree for review
+```
+
+## In GitHub Actions
+
+`npx keepgreen init` writes two workflows:
+
+- **`.github/workflows/keepgreen-explore.yml`** runs from *Actions > KeepGreen explore > Run
+  workflow*, or weekly if you uncomment the schedule. It opens **one PR** with the new tests that
+  passed. It has two jobs. The explore job runs the AI-written tests with a read-only token. The
+  publish job accepts the result only if it just adds test files, then opens the PR.
+- **`.github/workflows/autoheal.yml`** is written by AutoHeal's own `init`. It runs after your
+  test workflow fails and opens a fix PR.
+
+Then:
+
+1. Add `ANTHROPIC_API_KEY` as a repository secret. For OpenAI, add `OPENAI_API_KEY` and a
+   repository variable `AUTOHEAL_MODEL`.
+2. Go to *Settings > Actions > General > Workflow permissions* and tick "Allow GitHub Actions to
+   create and approve pull requests".
+3. Make the explore job's install steps match your test workflow (Node or Python, browsers,
+   services).
+
+You can also use the action directly:
+
+```yaml
+- uses: xsignon-secure/keepgreen@v0.1.1
+  with:
+    url: http://localhost:3000
+    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+# leaves keepgreen-out/ (report.md, summary.json, new-tests.patch); output `written` = tests kept
+```
+
+## Settings
+
+`.keepgreen.yml` at the repo root. Command-line flags override it.
+
+```yaml
+url: http://localhost:3000        # the running app, or:
+# start-command: npm run dev
+# start-url: http://localhost:3000
+pages:                            # extra pages to look at when choosing flows
+  - /login
+  - /pricing
+max-flows: 3                      # new tests per explore run (1-10)
+max-usd: 3                        # AI spend cap for one explore run
+runs: 5                           # passing runs in a row a new test needs (2-20)
+framework: auto                   # auto | playwright | pytest | cypress | webdriverio
+```
+
+AI settings use AutoHeal's variables:
+
+| Variable | Meaning |
+| --- | --- |
+| `ANTHROPIC_API_KEY` | Use Anthropic (default model `claude-opus-5-5`) |
+| `OPENAI_API_KEY` + `AUTOHEAL_MODEL` | Use OpenAI |
+| `AUTOHEAL_BASE_URL` + `AUTOHEAL_MODEL` (+ `AUTOHEAL_API_KEY`) | Any OpenAI-compatible endpoint: OpenRouter, or Ollama at `http://localhost:11434/v1` |
+| `AUTOHEAL_EFFORT` | Anthropic effort: `low` … `max` (default `medium`) |
+| `AUTOHEAL_PRICE_IN` / `AUTOHEAL_PRICE_OUT` | USD per 1M tokens, for models without a listed price |
+
+### OpenRouter (or any OpenAI-compatible endpoint)
+
+```bash
+export AUTOHEAL_BASE_URL=https://openrouter.ai/api/v1
+export AUTOHEAL_API_KEY=sk-or-...            # your OpenRouter key; give it a credit limit
+export AUTOHEAL_MODEL=<model id from openrouter.ai/models>
+export AUTOHEAL_PRICE_IN=3 AUTOHEAL_PRICE_OUT=15   # USD per 1M tokens of that model, so max-usd is enforced
+npx keepgreen explore --url http://localhost:3000
+```
+
+In the Action: `base-url: https://openrouter.ai/api/v1`, `api-key: ${{ secrets.OPENROUTER_API_KEY }}`,
+`model: ...`, and `price-in` / `price-out`.
+
+### Playwright `webServer`
+
+If your `playwright.config` starts the app with `webServer`, and KeepGreen starts it too
+(`start-command`), let Playwright reuse it during a KeepGreen run:
+
+```ts
+webServer: { command: 'npm run start', url: 'http://127.0.0.1:3000/', reuseExistingServer: !process.env.CI || !!process.env.KEEPGREEN },
+```
+
+## How explore works
+
+1. **Look.** It opens your app's start page and every path in `pages:` with playwright-e2e-mcp's
+   `inspect-page`, which lists the interactive elements and their locators.
+2. **Plan.** It reads the titles of your existing tests and asks your AI for the most important
+   user flows that have no test yet. Flows that pay money, send email or delete data are skipped.
+3. **Write.** For each flow, AutoHeal's `cover` explores the pages, checks every locator, and
+   writes one test in your project's own style.
+4. **Prove.** The new-test guard rejects tests that cannot fail, or that use skips, faked network
+   answers, fixed waits, forced clicks or retries. The test must then pass every run in a row.
+   Anything less is thrown away.
+
+One `max-usd` cap covers the whole run. Each flow gets an even share of what is left, so money one
+flow saves goes to the next.
+
+## All commands
+
+```
+keepgreen init [--force] [--dry-run]
+keepgreen doctor
+keepgreen explore [--url <app>] [--start-command <cmd> --start-url <url>] [--pages /a,/b]
+                  [--max-flows 3] [--max-usd 3] [--runs 5] [--dry-run] [--out <dir>]
+keepgreen heal [AutoHeal fix options]
+keepgreen autoheal <command> [...]      # any AutoHeal command: learn, metrics, dashboard, ...
+keepgreen check-patch <file>            # CI publish step
+keepgreen --version
+```
+
+## Self-host bundle (optional)
+
+KeepGreen needs no server. If you want **test history across all CI runs** (flaky ranking, the
+commit where a test went bad) and **AutoHeal's dashboard** (fixes, blocked cheats, AI spend),
+[`selfhost/`](selfhost/) starts both servers with one command:
+
+```bash
+cd selfhost && sh make-env.sh your-org/your-repo && docker compose up -d --build
+```
+
+## Security
+
+See [SECURITY.md](SECURITY.md). In short: your key goes only to your AI provider, AI-written tests
+never run with a write token or your AI key, the publish step only accepts new test files, and
+every change arrives as a PR for a person to review.
+
+## License
+
+MIT. Free for any use, with no paid tier.

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security
+
+KeepGreen runs an AI model against your app and your tests, so it is built on the assumption that
+the model can be wrong or manipulated. Text on a page or in a test file could try to instruct it;
+every prompt marks such text as data.
+
+## What protects you
+
+- **Your key, your runner.** KeepGreen has no server, no account and no telemetry. The only
+  network calls go to the AI provider you choose, your own app, and (in CI) GitHub to open the PR.
+- **Two jobs in CI.** The explore job, where AI-written tests run, has a read-only token and
+  checks out with `persist-credentials: false`. It uploads the new tests as a patch. The publish
+  job never runs your project's code. `keepgreen check-patch` accepts the patch only if it just
+  **adds** plain test files (`*.spec.ts`, `*.test.js`, `*.cy.ts`, `test_*.py`, ...): no changes
+  to existing files, no deletes, renames, mode changes or binary data, nothing under hidden
+  folders such as `.github/`, nothing in `node_modules`, at most 10 files. Then git applies it
+  with hooks off and the PR is opened.
+- **Secrets stay out of test runs.** New tests, and an app started with `start-command`, run in a
+  child process without the AI key or any GitHub / Actions token (AutoHeal's scrubbed engine
+  environment).
+- **New-test guard.** AutoHeal's `scanNewTest` rejects tests without real assertions, or with
+  skips, faked network answers (`page.route`), injected scripts, fixed waits, `force: true`,
+  extra retries or timeouts, file, environment or network access. A test must then pass every
+  one of `runs` runs in a row. The scans are pattern based, so every test still arrives as a PR
+  for a person to review.
+- **Pages stay on your app.** Planning only opens the app URL and the paths you list in
+  `pages:`; `cover` only opens pages on the same origin.
+- **Spend cap.** One `max-usd` limit covers a whole explore run (planning plus every flow).
+
+## Your part
+
+- Use an AI key with a spend limit; it is present in the explore job.
+- Run explore on your own branches only. The template runs on `workflow_dispatch` and an
+  optional schedule, never on pull requests from forks.
+- Review every KeepGreen PR like any other change.
+- For the self-host bundle, put the servers behind HTTPS and keep `.env` out of git.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting on this repository
+(Security > Report a vulnerability). Do not open a public issue.

package/action.yml

@@ -0,0 +1,128 @@
+name: KeepGreen explore
+description: Free, self-hosted AI test agent. Finds important user flows with no test and writes Playwright tests for them, with your own AI key.
+author: xsignon-secure
+branding:
+  icon: check-circle
+  color: green
+
+# Runs `keepgreen explore` and leaves keepgreen-out/ (report.md, summary.json,
+# new-tests.patch) for an upload step. It opens no PR itself: the template's
+# publish job does that with a separate, write-only step. See
+# templates/keepgreen-explore.yml.
+
+inputs:
+  url:
+    description: App URL to explore (blank = url in .keepgreen.yml)
+    required: false
+    default: ""
+  start-command:
+    description: Command that starts your app (with start-url)
+    required: false
+    default: ""
+  start-url:
+    description: Address to wait for after start-command
+    required: false
+    default: ""
+  max-flows:
+    description: New tests to try (1-10; blank = .keepgreen.yml or 3)
+    required: false
+    default: ""
+  max-usd:
+    description: AI spend cap for the run in USD (blank = .keepgreen.yml or 3)
+    required: false
+    default: ""
+  runs:
+    description: Passing runs in a row a new test needs (blank = .keepgreen.yml or 5)
+    required: false
+    default: ""
+  anthropic-api-key:
+    description: Anthropic API key
+    required: false
+    default: ""
+  openai-api-key:
+    description: OpenAI API key (also set model)
+    required: false
+    default: ""
+  model:
+    description: Model id (optional for Anthropic; for OpenRouter e.g. the id shown on openrouter.ai/models)
+    required: false
+    default: ""
+  base-url:
+    description: OpenAI-compatible endpoint, e.g. https://openrouter.ai/api/v1 (use with api-key and model)
+    required: false
+    default: ""
+  api-key:
+    description: API key for base-url (e.g. your OpenRouter key)
+    required: false
+    default: ""
+  price-in:
+    description: USD per 1M input tokens, for models KeepGreen has no price for (enforces max-usd)
+    required: false
+    default: ""
+  price-out:
+    description: USD per 1M output tokens
+    required: false
+    default: ""
+  working-directory:
+    description: Project folder
+    required: false
+    default: "."
+  version:
+    description: keepgreen version from npm
+    required: false
+    default: "0.1.1"
+
+outputs:
+  written:
+    description: Number of new tests kept
+    value: ${{ steps.run.outputs.written }}
+
+runs:
+  using: composite
+  steps:
+    - id: run
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        ANTHROPIC_API_KEY: ${{ inputs.anthropic-api-key }}
+        OPENAI_API_KEY: ${{ inputs.openai-api-key }}
+        AUTOHEAL_MODEL: ${{ inputs.model }}
+        KG_BASE_URL: ${{ inputs.base-url }}
+        KG_API_KEY: ${{ inputs.api-key }}
+        KG_PRICE_IN: ${{ inputs.price-in }}
+        KG_PRICE_OUT: ${{ inputs.price-out }}
+        KG_VERSION: ${{ inputs.version }}
+        KG_URL: ${{ inputs.url }}
+        KG_START_COMMAND: ${{ inputs.start-command }}
+        KG_START_URL: ${{ inputs.start-url }}
+        KG_MAX_FLOWS: ${{ inputs.max-flows }}
+        KG_MAX_USD: ${{ inputs.max-usd }}
+        KG_RUNS: ${{ inputs.runs }}
+        OUT: ${{ github.workspace }}/keepgreen-out
+      run: |
+        [ -n "$ANTHROPIC_API_KEY" ] || unset ANTHROPIC_API_KEY
+        [ -n "$OPENAI_API_KEY" ] || unset OPENAI_API_KEY
+        [ -n "$AUTOHEAL_MODEL" ] || unset AUTOHEAL_MODEL
+        # Inputs win; otherwise keep any AUTOHEAL_* already set on the job.
+        if [ -n "$KG_BASE_URL" ]; then export AUTOHEAL_PROVIDER=openai-compatible AUTOHEAL_BASE_URL="$KG_BASE_URL"; fi
+        if [ -n "$KG_API_KEY" ]; then export AUTOHEAL_API_KEY="$KG_API_KEY"; fi
+        if [ -n "$KG_PRICE_IN" ]; then export AUTOHEAL_PRICE_IN="$KG_PRICE_IN"; fi
+        if [ -n "$KG_PRICE_OUT" ]; then export AUTOHEAL_PRICE_OUT="$KG_PRICE_OUT"; fi
+        unset KG_API_KEY
+        if ! [[ "$KG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then echo "::error::version must be like 1.2.3"; exit 2; fi
+        args=(explore --out "$OUT")
+        [ -n "$KG_URL" ] && args+=(--url "$KG_URL")
+        [ -n "$KG_START_COMMAND" ] && args+=(--start-command "$KG_START_COMMAND")
+        [ -n "$KG_START_URL" ] && args+=(--start-url "$KG_START_URL")
+        [ -n "$KG_MAX_FLOWS" ] && args+=(--max-flows "$KG_MAX_FLOWS")
+        [ -n "$KG_MAX_USD" ] && args+=(--max-usd "$KG_MAX_USD")
+        [ -n "$KG_RUNS" ] && args+=(--runs "$KG_RUNS")
+        set +e
+        npx -y "keepgreen@$KG_VERSION" "${args[@]}"
+        code=$?
+        set -e
+        written=0
+        [ -f "$OUT/summary.json" ] && written="$(node -p 'require(process.env.OUT + "/summary.json").written.length')"
+        echo "written=$written" >> "$GITHUB_OUTPUT"
+        # 1 = ran fine but kept no test; that is not a failed job.
+        if [ "$code" -gt 1 ] || { [ "$code" -eq 1 ] && [ ! -f "$OUT/summary.json" ]; }; then exit "$code"; fi

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * keepgreen: one command for the whole agent.
+ *   explore  writes new tests (KeepGreen's own recipe, built on AutoHeal's cover)
+ *   heal     fixes broken tests on your machine (AutoHeal's `fix`)
+ *   init     writes .keepgreen.yml, the explore workflow and AutoHeal's heal workflow
+ *   doctor   checks the setup
+ */
+export declare const USAGE: string;
+/** Path of AutoHeal's CLI inside the installed xsignon-autoheal package. */
+export declare function autohealCli(): string;
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * keepgreen: one command for the whole agent.
+ *   explore  writes new tests (KeepGreen's own recipe, built on AutoHeal's cover)
+ *   heal     fixes broken tests on your machine (AutoHeal's `fix`)
+ *   init     writes .keepgreen.yml, the explore workflow and AutoHeal's heal workflow
+ *   doctor   checks the setup
+ */
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { ConfigError, CypressTools, McpTools, ProviderError, WdioTools, checkAppUrl, cover, frameworkSetting, isCypressProject, isPytestProject, isWdioProject, priceFor, providerFromEnv, startApp, } from 'xsignon-autoheal';
+import { ConfigFileError, loadConfigFile, resolveConfig } from './config.js';
+import { existingTitles, explore, exploreReport } from './explore.js';
+import { init } from './init.js';
+import { newFilesPatch } from './newfiles.js';
+import { checkPatch } from './patch.js';
+import { VERSION } from './version.js';
+export const USAGE = `keepgreen ${VERSION}: free, self-hosted AI test agent. It writes new end-to-end tests
+for your app and fixes the ones that break, with your own AI key (Anthropic, OpenAI or any
+OpenAI-compatible endpoint). Built on playwright-e2e-mcp and AutoHeal. MIT, no account, no telemetry.
+
+  keepgreen init [--force] [--dry-run]
+        write .keepgreen.yml, the explore workflow and AutoHeal's heal workflow (GitHub Actions)
+  keepgreen doctor
+        check this project and machine
+  keepgreen explore [--url <app>] [--start-command <cmd> --start-url <url>] [--pages /a,/b]
+                    [--max-flows 3] [--max-usd 3] [--runs 5] [--dry-run] [--out <dir>]
+        find important user flows with no test yet and write a test for each; a test is kept
+        only if it makes real assertions and passes --runs times in a row
+  keepgreen heal [AutoHeal fix options]
+        run your tests, fix what broke, leave the changes for you to review
+  keepgreen autoheal <command> [...]
+        run any AutoHeal command (heal, publish, learn, metrics, dashboard, ...)
+  keepgreen check-patch <file>
+        CI publish step: accept a patch only if it just adds test files
+  keepgreen --version
+
+Settings come from .keepgreen.yml; flags win. The AI key comes from ANTHROPIC_API_KEY,
+OPENAI_API_KEY (+ AUTOHEAL_MODEL) or AUTOHEAL_BASE_URL (+ AUTOHEAL_MODEL).
+`;
+const log = (line) => process.stderr.write(`[keepgreen] ${line}\n`);
+/** Path of AutoHeal's CLI inside the installed xsignon-autoheal package. */
+export function autohealCli() {
+    const entry = fileURLToPath(import.meta.resolve('xsignon-autoheal'));
+    return path.join(path.dirname(entry), 'cli.js');
+}
+function runAutoheal(args) {
+    const r = spawnSync(process.execPath, [autohealCli(), ...args], { stdio: 'inherit' });
+    if (r.error)
+        throw r.error;
+    return r.status ?? 1;
+}
+async function detectFramework(root, value) {
+    let setting;
+    try {
+        setting = frameworkSetting(value ?? process.env.AUTOHEAL_FRAMEWORK);
+    }
+    catch (error) {
+        throw new ConfigError(error instanceof Error ? error.message : String(error));
+    }
+    if (setting !== 'auto')
+        return setting;
+    if (await isWdioProject(root))
+        return 'webdriverio';
+    if (await isCypressProject(root))
+        return 'cypress';
+    return (await isPytestProject(root)) ? 'pytest' : 'playwright';
+}
+async function cmdExplore(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            url: { type: 'string' },
+            'start-command': { type: 'string' },
+            'start-url': { type: 'string' },
+            pages: { type: 'string' },
+            'max-flows': { type: 'string' },
+            'max-usd': { type: 'string' },
+            runs: { type: 'string' },
+            framework: { type: 'string' },
+            project: { type: 'string' },
+            out: { type: 'string' },
+            'dry-run': { type: 'boolean' },
+        },
+        strict: true,
+    });
+    const projectRoot = path.resolve(values.project ?? '.');
+    const { project: _p, out: _o, 'dry-run': _d, ...flags } = values;
+    const config = resolveConfig(await loadConfigFile(projectRoot), flags);
+    const env = process.env;
+    // Lets playwright.config tell a KeepGreen run apart, e.g.
+    // reuseExistingServer: !process.env.CI || !!process.env.KEEPGREEN
+    env.KEEPGREEN = '1';
+    const provider = providerFromEnv(env);
+    if (!provider)
+        throw new ConfigError('keepgreen explore needs an AI key: set ANTHROPIC_API_KEY, OPENAI_API_KEY (and AUTOHEAL_MODEL) or AUTOHEAL_BASE_URL.');
+    const framework = await detectFramework(projectRoot, config.framework);
+    let app = null;
+    let appUrl = config.url;
+    let engine = null;
+    let runner = null;
+    try {
+        if (config.startCommand) {
+            const url = config.startUrl ?? config.url;
+            if (!url)
+                throw new ConfigError('start-command needs start-url: the address to wait for.');
+            // startApp gives your app the tests' scrubbed environment: no AI key, no CI tokens.
+            app = await startApp({ command: config.startCommand, url, cwd: projectRoot, sandbox: null, log });
+            appUrl = app.url;
+        }
+        if (!appUrl)
+            throw new ConfigError('Tell KeepGreen where your app runs: --url http://localhost:3000, or url: in .keepgreen.yml (or start-command + start-url).');
+        checkAppUrl(appUrl);
+        log(`KeepGreen ${VERSION}: exploring ${appUrl} (${framework}, ${provider.name} ${provider.model}, limit $${config.maxUsd})`);
+        engine = await McpTools.start(projectRoot);
+        runner = framework === 'cypress' ? new CypressTools(projectRoot, { log }) : framework === 'webdriverio' ? new WdioTools(projectRoot, { log }) : engine;
+        const result = await explore({
+            projectRoot,
+            provider,
+            engine,
+            runner,
+            appUrl,
+            pages: config.pages,
+            existing: await existingTitles(projectRoot),
+            maxFlows: config.maxFlows,
+            maxUsd: config.maxUsd,
+            runs: config.runs,
+            price: priceFor(provider.model, env),
+            framework,
+            cover,
+            log,
+            dryRun: values['dry-run'] === true,
+        });
+        const report = exploreReport(result, config.runs);
+        process.stdout.write(`\n${report}\n`);
+        const written = result.results.filter((r) => r.result.status === 'written').map((r) => r.result.file);
+        if (values.out) {
+            const out = path.resolve(values.out);
+            await mkdir(out, { recursive: true });
+            await writeFile(path.join(out, 'report.md'), `${report}\n`);
+            await writeFile(path.join(out, 'summary.json'), `${JSON.stringify({ version: VERSION, written, flows: result.flows, usd: result.usd }, null, 2)}\n`);
+            await writeFile(path.join(out, 'new-tests.patch'), await newFilesPatch(projectRoot, written));
+            log(`Wrote ${path.relative(process.cwd(), out) || '.'}/report.md, summary.json and new-tests.patch`);
+        }
+        if (env.GITHUB_STEP_SUMMARY)
+            await appendFile(env.GITHUB_STEP_SUMMARY, `${report}\n`).catch(() => undefined);
+        return values['dry-run'] || written.length ? 0 : 1;
+    }
+    finally {
+        if (runner && runner !== engine)
+            await runner.close().catch(() => undefined);
+        await engine?.close();
+        await app?.stop().catch(() => undefined);
+    }
+}
+async function cmdInit(argv) {
+    const { values } = parseArgs({ args: argv, options: { project: { type: 'string' }, force: { type: 'boolean' }, 'dry-run': { type: 'boolean' } }, strict: true });
+    const root = path.resolve(values.project ?? '.');
+    const dryRun = values['dry-run'] === true;
+    const r = await init(root, { force: values.force === true, dryRun });
+    const out = [`KeepGreen ${VERSION}`, ''];
+    for (const w of r.written)
+        out.push(`${dryRun ? 'would write' : 'wrote'}   ${w}`);
+    for (const w of r.skipped)
+        out.push(`kept    ${w} (exists; --force to overwrite)`);
+    out.push('', 'Now AutoHeal sets up healing:', '');
+    process.stdout.write(out.join('\n'));
+    const code = runAutoheal(['init', '--ci', 'github', '--project', root, ...(values.force ? ['--force'] : []), ...(dryRun ? ['--dry-run'] : [])]);
+    process.stdout.write([
+        '',
+        'For KeepGreen explore, also:',
+        '  1. Set url: in .keepgreen.yml (or start-command + start-url) so KeepGreen can reach your app.',
+        '  2. Add ANTHROPIC_API_KEY (or OPENAI_API_KEY + the AUTOHEAL_MODEL variable) as a repository secret.',
+        '  3. Settings > Actions > General: allow GitHub Actions to create pull requests.',
+        '  4. Run it: Actions > KeepGreen explore > Run workflow (or `npx keepgreen explore` on your machine).',
+        '',
+    ].join('\n'));
+    return code;
+}
+async function cmdDoctor(argv) {
+    const { values } = parseArgs({ args: argv, options: { project: { type: 'string' } }, strict: true });
+    const root = path.resolve(values.project ?? '.');
+    const lines = [`KeepGreen ${VERSION} doctor`, ''];
+    let failed = false;
+    try {
+        const config = resolveConfig(await loadConfigFile(root), {});
+        const target = config.startCommand ? `start-command "${config.startCommand}" then ${config.startUrl ?? config.url ?? '(no start-url!)'}` : (config.url ?? null);
+        lines.push(target ? `ok    explore target: ${target}` : 'warn  no url in .keepgreen.yml: pass --url to keepgreen explore');
+        if (config.startCommand && !(config.startUrl ?? config.url))
+            failed = true;
+    }
+    catch (error) {
+        failed = true;
+        lines.push(`fail  .keepgreen.yml: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    lines.push('', 'AutoHeal checks (keys, framework, CI):', '');
+    process.stdout.write(lines.join('\n'));
+    const code = runAutoheal(['doctor', '--project', root]);
+    return failed ? 1 : code;
+}
+async function cmdCheckPatch(argv) {
+    const file = argv[0];
+    if (!file || argv.length > 1)
+        throw new ConfigError('Usage: keepgreen check-patch <file>');
+    const result = checkPatch(await readFile(file, 'utf8'));
+    if (result.ok) {
+        process.stdout.write(`${result.files.join('\n')}\n`);
+        return 0;
+    }
+    log(result.files.length || result.problems.length ? `Patch refused:\n  ${(result.problems.length ? result.problems : ['no files']).join('\n  ')}` : 'Patch is empty.');
+    return 1;
+}
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    try {
+        if (!command || command === 'help' || command === '--help' || command === '-h') {
+            process.stdout.write(USAGE);
+            return command ? 0 : 2;
+        }
+        if (command === '--version' || command === '-v' || command === 'version') {
+            process.stdout.write(`${VERSION}\n`);
+            return 0;
+        }
+        if (command === 'explore')
+            return await cmdExplore(rest);
+        if (command === 'heal')
+            return runAutoheal(['fix', ...rest]);
+        if (command === 'autoheal')
+            return runAutoheal(rest);
+        if (command === 'init')
+            return await cmdInit(rest);
+        if (command === 'doctor')
+            return await cmdDoctor(rest);
+        if (command === 'check-patch')
+            return await cmdCheckPatch(rest);
+        process.stderr.write(`Unknown command "${command}".\n\n${USAGE}`);
+        return 2;
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof ConfigFileError || error.code?.startsWith('ERR_PARSE_ARGS')) {
+            log(error.message);
+            return 2;
+        }
+        if (error instanceof ProviderError) {
+            log(`The AI provider refused the request: ${error.message.slice(0, 600)}`);
+            if (/HTTP 402|credits|quota|insufficient/i.test(error.message))
+                log('Your AI account or key is out of credit (or its spend limit is too low). Add credit or raise the key\'s limit, then run again.');
+            else if (/HTTP 401|HTTP 403|api key|unauthori/i.test(error.message))
+                log('Check the API key (and AUTOHEAL_BASE_URL / AUTOHEAL_MODEL for OpenAI-compatible endpoints).');
+            return 1;
+        }
+        log(error instanceof Error ? (error.stack ?? error.message) : String(error));
+        return 1;
+    }
+}
+const invoked = process.argv[1] ? pathToFileURL(realpathSync(process.argv[1])).href : '';
+if (invoked === import.meta.url) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}
+//# sourceMappingURL=cli.js.map