almightygpt 0.5.1 → 0.5.2

package/README.md

@@ -0,0 +1,234 @@
+# almightygpt
+
+> **The convention and tooling for multi-AI development.**
+> One AI writes. A different AI reviews. The decision trail lives in git.
+
+[![npm version](https://img.shields.io/npm/v/almightygpt.svg)](https://www.npmjs.com/package/almightygpt)
+[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/almightygpt.almightygpt-vscode.svg?label=VS%20Code%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=almightygpt.almightygpt-vscode)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/roxjayanath/almightygpt/blob/main/LICENSE)
+
+AlmightyGPT drops a Worker / Reviewer convention into any repo, then runs
+real cross-AI code reviews (OpenAI, Anthropic, Google) and saves the
+review artifact in git as your durable decision trail.
+
+```bash
+npx almightygpt init
+```
+
+Full documentation, design notes, and roadmap:
+**https://github.com/roxjayanath/almightygpt**
+
+---
+
+## Install
+
+```bash
+npm install -g almightygpt
+# or one-shot, no global install:
+npx almightygpt init
+```
+
+Requires Node.js 18+.
+
+## Quick start
+
+```bash
+# 1. Initialize the Convention Pack in any repo
+cd ~/your-project
+almightygpt init --stack node-ts   # or python-django / python-fastapi / rails / go
+
+# 2. Set at least one provider API key (read once, never stored)
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=...
+
+# 3. Run a review
+almightygpt review --diff --reviewer codex --topic auth-refactor
+
+# 4. Or run the headline two-role flow (one AI writes, a different AI reviews)
+almightygpt review --diff \
+  --worker claude --reviewer codex \
+  --topic auth-refactor
+
+# 5. Record your decision
+almightygpt decide latest --status approved --note "Reviewer caught the missing null check"
+```
+
+The review lands at `docs/codex-reviews/<topic>.md`, committed to git as
+your audit trail. Machine metadata (cost, tokens, raw outputs) lands at
+`.almightygpt/runs/<id>/`.
+
+## Commands
+
+| Command | What |
+| --- | --- |
+| `almightygpt init [--stack <name>] [--backup\|--force]` | Install the Convention Pack |
+| `almightygpt review --diff [range] [--worker X] --reviewer Y --topic Z` | Run a review |
+| `almightygpt runs list [--limit N]` | List recent runs |
+| `almightygpt runs latest` | Show the most recent run |
+| `almightygpt decide <id\|latest> --status <s> --note "..."` | Record a human decision |
+
+All commands accept `--json` for machine-readable output. The `review`
+command streams JSON events one per line, suitable for tooling (the VS
+Code extension uses this directly).
+
+## Five supported stack templates
+
+`node-ts`, `python-django`, `python-fastapi`, `rails`, `go` — each ships
+with a stack-tuned `CLAUDE.md` for the Worker AI, an `.almightyignore`
+covering that stack's typical secret-bearing paths, and a config with
+sensible `context.include` / `context.exclude` globs.
+
+## Four real provider adapters
+
+- **OpenAI** (default Reviewer; `gpt-4o`) — env: `OPENAI_API_KEY`
+- **Anthropic / Claude** (default Worker; `claude-3-5-sonnet-latest`) — env: `ANTHROPIC_API_KEY`
+- **Google / Gemini** (optional Reviewer; `gemini-2.5-flash` for free-tier friendliness) — env: `GOOGLE_API_KEY` or `GEMINI_API_KEY`
+- **Mock** (for testing without API keys)
+
+OpenAI and Anthropic adapters have **prompt caching enabled** — 50% off
+cached input tokens on OpenAI, 90% off on Anthropic. Kicks in
+automatically on the second run in the same 5-minute window.
+
+## VS Code extension
+
+The official UI wrapper for this CLI: **https://marketplace.visualstudio.com/items?itemName=almightygpt.almightygpt-vscode**
+
+Six commands under the **AlmightyGPT:** palette category, a Runs tree
+view in the activity bar, real-time progress driven by this CLI's JSON
+event stream. The extension never owns orchestration — all review work
+happens here in the CLI.
+
+Cursor / VSCodium / code-server / Theia users:
+**https://open-vsx.org/extension/almightygpt/almightygpt-vscode**
+
+---
+
+## Runtime behavior — what this package actually does
+
+For users and security teams evaluating AlmightyGPT, here's exactly what
+the CLI does at runtime. Every behavior is intentional and required for
+the product to work; none is hidden.
+
+### Network access (provider calls only)
+
+The CLI makes outbound HTTPS requests only to the AI provider whose
+adapter is invoked, and only when you explicitly run a review command
+that uses that adapter:
+
+- `api.openai.com` — via the official `openai` SDK, when `OPENAI_API_KEY` is set and an OpenAI adapter (e.g. `codex`) is invoked
+- `api.anthropic.com` — via the official `@anthropic-ai/sdk`, when `ANTHROPIC_API_KEY` is set and a Claude adapter is invoked
+- `generativelanguage.googleapis.com` — via the official `@google/generative-ai` SDK, when `GOOGLE_API_KEY` (or `GEMINI_API_KEY`) is set and a Gemini adapter is invoked
+
+**No other network access.** No telemetry, no analytics beaconing, no
+auto-update calls, no anonymous usage stats, no error-reporting service.
+The CLI doesn't even check for its own newer versions.
+
+### Shell access (git only)
+
+The CLI spawns `git` as a child process via
+[`execa`](https://www.npmjs.com/package/execa) for the following
+read-only operations:
+
+- `git status --short -- <file>` — per-target safety check before any
+  Markdown write
+- `git diff --no-color [range]` — collect the diff to review
+- `git rev-parse --abbrev-ref HEAD` / `git rev-parse HEAD` — record
+  branch and commit hash into `run.json`
+
+All git invocations pass arguments as an **argv array**, never as a
+shell string. The CLI never executes arbitrary user-supplied commands.
+It never calls `sh -c`, `eval`, or `exec` with concatenated input.
+
+### Environment-variable access (read-only)
+
+The CLI reads these env vars at run time:
+
+- `OPENAI_API_KEY` (for the OpenAI adapter)
+- `ANTHROPIC_API_KEY` (for the Anthropic adapter)
+- `GOOGLE_API_KEY` (for the Gemini adapter)
+- `GEMINI_API_KEY` (alias for the Gemini adapter)
+
+API keys are passed directly into each provider's official SDK and used
+as the `Authorization: Bearer <key>` header for that provider's API.
+The CLI never writes env vars, never stores keys to disk, never logs
+their values, and never sends them anywhere except the matching
+provider.
+
+### Filesystem access
+
+- **Reads** (from your workspace): `.gitignore`, `.almightyignore`,
+  `.almightygpt/config.yaml`, `.almightygpt/rules.md`, `AGENTS.md`, your
+  configured agent memory files (`CLAUDE.md`, `CODEX_AGENT.md`,
+  `GEMINI_AGENT.md`), and the file contents covered by the collected
+  `git diff`.
+- **Writes** (only to two paths, both configured in
+  `.almightygpt/config.yaml`):
+  - `docs/<reviewer>-reviews/<topic>.md` — the human review artifact
+    (subject to a refuse-overwrite policy: never overwrites an existing
+    review file without `--force`)
+  - `.almightygpt/runs/<id>/` — machine-readable run metadata
+- **Per-target git safety check** runs before every Markdown write. Dirty
+  target files are refused unless `--force` is passed.
+
+### Secret redaction (defense in depth)
+
+Before any diff is sent to a provider, the CLI:
+
+1. **Filters out ignored files** per-file by parsing the unified diff
+   into per-file sections and dropping any file matching `.gitignore`,
+   `.almightyignore`, or `config.context.exclude`. Ignored files never
+   reach the provider — they're not just redacted, they're omitted
+   entirely.
+2. **Redacts nine secret patterns** in what remains: OpenAI / Anthropic
+   keys, GitHub PATs, AWS access keys, Slack tokens, JWTs, PEM private
+   key blocks, bearer tokens in headers, generic assignment-style
+   secrets (`api_key="..."`, `password=...`).
+
+Both steps are logged in `context-manifest.json` for every run.
+
+### What the CLI does NOT do
+
+- Send your code anywhere other than the AI provider you explicitly
+  configured and invoked
+- Phone home with telemetry, analytics, or error reports
+- Auto-update itself or check for newer versions
+- Store API keys in any file
+- Execute arbitrary user-supplied shell commands
+- Eval remote content
+- Run install/postinstall scripts (none in the runtime dependency tree)
+
+### Runtime dependencies (12 total: 10 third-party + 2 our own)
+
+```
+almightygpt
+├── @almightygpt/core
+│   ├── @anthropic-ai/sdk    Anthropic's official Claude SDK
+│   ├── @google/generative-ai Google's official Gemini SDK
+│   ├── openai                OpenAI's official SDK
+│   ├── execa                 spawn `git` as child process
+│   ├── ignore                parse .gitignore / .almightyignore syntax
+│   ├── yaml                  parse .almightygpt/config.yaml
+│   ├── zod                   validate config schema
+│   └── p-limit               limit parallel adapter calls
+├── @almightygpt/templates    (no runtime dependencies)
+├── chalk                     terminal colors
+└── commander                 CLI argument parser
+```
+
+All pure JavaScript. No native binaries. No install scripts. `npm audit`
+reports zero vulnerabilities. Verify on Socket:
+**https://socket.dev/npm/package/almightygpt**
+
+---
+
+## License
+
+MIT. See [LICENSE](https://github.com/roxjayanath/almightygpt/blob/main/LICENSE).
+
+## Links
+
+- **GitHub**: https://github.com/roxjayanath/almightygpt
+- **Issues**: https://github.com/roxjayanath/almightygpt/issues
+- **VS Code extension**: https://marketplace.visualstudio.com/items?itemName=almightygpt.almightygpt-vscode
+- **Open VSX extension**: https://open-vsx.org/extension/almightygpt/almightygpt-vscode

package/dist/index.js

@@ -15,7 +15,7 @@ program
     .name("almightygpt")
     .description("The convention and tooling for multi-AI development. " +
     "One AI writes, another AI reviews.")
-    .version("0.5.1");
+    .version("0.5.2");
 program.addCommand(createInitCommand());
 program.addCommand(createReviewCommand());
 program.addCommand(createRunsCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "almightygpt",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "AlmightyGPT CLI — the convention and tooling for multi-AI development",
   "license": "MIT",
   "type": "module",