rebut-mcp 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/LICENSE +21 -0
  2. package/README.en.md +73 -0
  3. package/README.ja.md +73 -0
  4. package/README.md +73 -2
  5. package/README.zh-CN.md +73 -0
  6. package/bin/rebut.mjs +6 -0
  7. package/config.example.json +28 -0
  8. package/docs/guide/en/architecture.md +29 -0
  9. package/docs/guide/en/configuration.md +106 -0
  10. package/docs/guide/en/installation.md +103 -0
  11. package/docs/guide/en/operations.md +51 -0
  12. package/docs/guide/en/reviewer-integration.md +16 -0
  13. package/docs/guide/en/validation.md +38 -0
  14. package/docs/guide/en.md +20 -0
  15. package/docs/guide/ja/architecture.md +29 -0
  16. package/docs/guide/ja/configuration.md +106 -0
  17. package/docs/guide/ja/installation.md +103 -0
  18. package/docs/guide/ja/operations.md +51 -0
  19. package/docs/guide/ja/reviewer-integration.md +16 -0
  20. package/docs/guide/ja/validation.md +38 -0
  21. package/docs/guide/ja.md +20 -0
  22. package/docs/guide/ko/architecture.md +29 -0
  23. package/docs/guide/ko/configuration.md +106 -0
  24. package/docs/guide/ko/installation.md +103 -0
  25. package/docs/guide/ko/operations.md +51 -0
  26. package/docs/guide/ko/reviewer-integration.md +16 -0
  27. package/docs/guide/ko/validation.md +38 -0
  28. package/docs/guide/ko.md +20 -0
  29. package/docs/guide/zh-CN/architecture.md +29 -0
  30. package/docs/guide/zh-CN/configuration.md +106 -0
  31. package/docs/guide/zh-CN/installation.md +103 -0
  32. package/docs/guide/zh-CN/operations.md +51 -0
  33. package/docs/guide/zh-CN/reviewer-integration.md +16 -0
  34. package/docs/guide/zh-CN/validation.md +38 -0
  35. package/docs/guide/zh-CN.md +20 -0
  36. package/docs/releases/0.1.0.ko.md +43 -0
  37. package/docs/releases/0.2.0.ko.md +72 -0
  38. package/docs/releases/release-checklist.ko.md +35 -0
  39. package/lib/cli.mjs +2466 -0
  40. package/migrations/0001_ledger.sql +20 -0
  41. package/migrations/0002_profiles.sql +6 -0
  42. package/package.json +65 -4
  43. package/src/contracts.ts +162 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rebut contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,73 @@
1
+ <div align="center">
2
+
3
+ # Rebut
4
+
5
+ **Local-first independent code review MCP. Cloudflare Worker is optional.**
6
+
7
+ [한국어](README.md) · **English** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
8
+
9
+ </div>
10
+
11
+ Rebut reviews code using your own OpenAI API key. New installations run a local stdio server without a Cloudflare account or a separate HTTP daemon.
12
+
13
+ Review material is sent to the OpenAI API; the local ledger stores only request and usage metadata.
14
+
15
+ The tested release targets macOS/Linux; Windows behavior and ACLs are not validated.
16
+
17
+ ## Quick start
18
+
19
+ Use Node.js 24 or later. This example uses macOS Keychain.
20
+
21
+ ```sh
22
+ npm install -g rebut-mcp
23
+ rebut set api-key
24
+ rebut setup --client codex
25
+ rebut doctor --connect
26
+ ```
27
+
28
+ `rebut set api-key` accepts hidden OpenAI API key input and stores it in Keychain. On Linux and other environments, select `rebut set secret-store env` and supply `REBUT_OPENAI_API_KEY` through the actual MCP host’s secure environment. Setup records the variable name only; never put keys in arguments or tracked files.
29
+
30
+ ## Optional Worker
31
+
32
+ Choose a self-hosted Worker when multiple machines need a shared budget and request ledger. `rebut set endpoint URL` selects Worker mode. On macOS, `rebut set token` stores the separate Worker access token. The OpenAI API key, Worker access token and admin token are different credentials.
33
+
34
+ ```sh
35
+ rebut set endpoint https://YOUR_HOST/mcp
36
+ rebut setup --client codex --replace
37
+ ```
38
+
39
+ Existing endpoint configurations remain in Worker mode. Switch explicitly with `rebut set mode local`; failures never trigger automatic backend fallback. Switching does not move existing requests or reservations.
40
+
41
+ ## What it does
42
+
43
+ - Collect, redact and freeze explicitly supplied files, diffs and requirements, then make one provider call.
44
+ - Use atomic budget reservations and deduplication in local SQLite or Worker D1. Source, reviews and keys are not stored in the ledger.
45
+ - Return structured findings with supplied file/line evidence, model identity, usage and estimated cost.
46
+ - Expose review and metadata-only review_status. Keep the same ID after uncertainty and do not replay an unknown on another backend.
47
+
48
+ Example defaults are $6.66/day and $200/month in UTC, one pending/unknown request, and 100 new requests/day. **Local limits cover only that device’s data directory**: they do not aggregate another Mac, Worker, external API usage or the OpenAI account balance. Worker users share that deployment’s ledger. Estimates are not invoices; uncertain executions keep their reservations and slots.
49
+
50
+ The provider waiting ceiling is 30 minutes, with corresponding HTTP/MCP and Codex deadlines. Local profile changes require OS ownership; Worker changes use separate admin authentication. See [installation](docs/guide/en/installation.md) and [configuration](docs/guide/en/configuration.md) for credentials, models, budgets and optional Worker deployment.
51
+
52
+ ## Developer validation
53
+
54
+ ```sh
55
+ npm ci --ignore-scripts
56
+ npm run typecheck
57
+ npm run build
58
+ npm test
59
+ npm run test:package
60
+ ```
61
+
62
+ Automated tests and package smoke tests mock the provider. Default real API tests use gpt-6-luna; production uses gpt-6-astra / medium. Luna success does not establish Astra review quality.
63
+
64
+ ## Documentation
65
+
66
+ - [User guide](docs/guide/en.md)
67
+ - [Installation and input collection](docs/guide/en/installation.md)
68
+ - [Configuration, budgets and MCP contract](docs/guide/en/configuration.md)
69
+ - [Operations and recovery](docs/guide/en/operations.md)
70
+ - [Opt-in reviewer integration](docs/guide/en/reviewer-integration.md)
71
+ - [Architecture](docs/guide/en/architecture.md)
72
+ - [Validation and limits of the results](docs/guide/en/validation.md)
73
+ - [MIT license](LICENSE)
package/README.ja.md ADDED
@@ -0,0 +1,73 @@
1
+ <div align="center">
2
+
3
+ # Rebut
4
+
5
+ **ローカル実行を標準とする独立コードレビューMCP。Cloudflare Workerは任意です。**
6
+
7
+ [한국어](README.md) · [English](README.en.md) · [简体中文](README.zh-CN.md) · **日本語**
8
+
9
+ </div>
10
+
11
+ Rebutは自分のOpenAI APIキーでコードをレビューします。新規インストールはローカルstdioサーバーとして動作し、Cloudflareアカウントや別のHTTPデーモンは不要です。
12
+
13
+ レビュー資料はOpenAI APIへ送信し、ローカル台帳には要求・使用量メタデータのみ保存します。
14
+
15
+ 検証対象はmacOS/Linuxで、Windows動作・ACLは未検証です。
16
+
17
+ ## クイックスタート
18
+
19
+ Node.js 24以降が必要です。以下はmacOS Keychainを使う例です。
20
+
21
+ ```sh
22
+ npm install -g rebut-mcp
23
+ rebut set api-key
24
+ rebut setup --client codex
25
+ rebut doctor --connect
26
+ ```
27
+
28
+ `rebut set api-key` はOpenAI APIキーを非表示入力で受け取りKeychainに保存します。Linux等では `rebut set secret-store env` を選び、実際のMCPホストの安全な環境で `REBUT_OPENAI_API_KEY` を提供してください。登録には変数名だけを記録し、キーを引数や追跡対象ファイルに書きません。
29
+
30
+ ## 任意のWorker
31
+
32
+ 複数端末で予算と要求台帳を共有する場合はセルフホストのWorkerを選べます。`rebut set endpoint URL` はWorkerモードを選択します。macOSでは `rebut set token` で別のWorker接続トークンを保存します。OpenAI APIキー・Worker接続トークン・管理者トークンは別の資格情報です。
33
+
34
+ ```sh
35
+ rebut set endpoint https://YOUR_HOST/mcp
36
+ rebut setup --client codex --replace
37
+ ```
38
+
39
+ 既存endpoint設定はWorkerモードを維持します。`rebut set mode local` で明示的に切り替え、障害時の自動切り替えはしません。切り替えても既存の要求や予約は移行されません。
40
+
41
+ ## 主な機能
42
+
43
+ - 明示されたファイル・diff・要件だけを収集・秘匿処理・固定し、プロバイダーを1回呼び出します。
44
+ - ローカルSQLiteまたはWorker D1で原子的な予算予約と重複排除を行い、原文・レビュー本文・キーは台帳に保存しません。
45
+ - 指定ファイル・行の根拠、モデル識別、使用量、推定費用を含む構造化された指摘を返します。
46
+ - reviewとメタデータ専用review_statusを提供します。不確かな結果後は同じIDを維持し、unknownを別backendで再実行しません。
47
+
48
+ 既定例はUTCで日額$6.66・月額$200、pending/unknown同時1件、日100件の新規要求です。**ローカル制限はその端末のデータディレクトリのみが対象**で、別のMac・Worker・外部API・OpenAIアカウント残高は合算しません。Worker利用者はそのデプロイの台帳を共有します。推定は請求書ではなく、不確かな実行の予約と枠は保持します。
49
+
50
+ プロバイダー待機上限は30分で、HTTP/MCP・Codexの期限も合わせます。ローカルプロファイルはOS所有者、Workerは別の管理者認証で管理します。資格情報・モデル・予算・任意のWorkerデプロイは[インストール](docs/guide/ja/installation.md)と[設定](docs/guide/ja/configuration.md)を参照してください。
51
+
52
+ ## 開発者向け検証
53
+
54
+ ```sh
55
+ npm ci --ignore-scripts
56
+ npm run typecheck
57
+ npm run build
58
+ npm test
59
+ npm run test:package
60
+ ```
61
+
62
+ 自動テストとパッケージsmokeはプロバイダーを模擬します。既定の実APIテストはgpt-6-luna、運用はgpt-6-astra / mediumです。Lunaの成功はAstraのレビュー品質を証明しません。
63
+
64
+ ## ドキュメント
65
+
66
+ - [ユーザーガイド](docs/guide/ja.md)
67
+ - [インストールと入力の収集](docs/guide/ja/installation.md)
68
+ - [設定、予算、MCP 仕様](docs/guide/ja/configuration.md)
69
+ - [運用と復旧](docs/guide/ja/operations.md)
70
+ - [明示的に選択するレビュアーの統合](docs/guide/ja/reviewer-integration.md)
71
+ - [アーキテクチャ](docs/guide/ja/architecture.md)
72
+ - [検証と結果の限界](docs/guide/ja/validation.md)
73
+ - [MIT ライセンス](LICENSE)
package/README.md CHANGED
@@ -1,3 +1,74 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- 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.
3
+ # Rebut
4
+
5
+ **로컬에서 바로 실행하는 독립 코드 검토 MCP. Cloudflare Worker는 선택 사항입니다.**
6
+
7
+ **한국어** · [English](README.en.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
8
+
9
+ </div>
10
+
11
+ Rebut은 자신의 OpenAI API 키로 실행하는 코드 검토 도구입니다. 새 설치는 로컬 stdio 서버를 사용하며 Cloudflare 계정이나 별도 HTTP 서버가 필요하지 않습니다.
12
+
13
+ 검토 자료는 OpenAI API로 전송하며, 로컬 원장에는 요청·사용량 메타데이터만 저장합니다.
14
+
15
+ 검증 대상은 macOS/Linux이며 Windows 동작·ACL은 확인하지 않았습니다.
16
+
17
+ ## 빠른 시작
18
+
19
+ Node.js 24 이상이 필요합니다. 다음은 macOS Keychain을 사용하는 예입니다.
20
+
21
+ ```sh
22
+ npm install -g rebut-mcp
23
+ rebut set api-key
24
+ rebut setup --client codex
25
+ rebut doctor --connect
26
+ ```
27
+
28
+ `rebut set api-key`는 OpenAI API 키를 숨김 입력으로 받아 Keychain에 저장합니다. Linux 등에서는 `rebut set secret-store env`를 선택하고 실제 MCP 호스트의 안전한 환경에 `REBUT_OPENAI_API_KEY`를 제공하세요. 설정에는 변수명만 기록하며 키를 인자나 추적 파일에 넣지 않습니다.
29
+
30
+ ## Worker 선택
31
+
32
+ 여러 기기가 하나의 예산과 요청 장부를 공유하려면 직접 호스팅한 Worker를 선택할 수 있습니다. `rebut set endpoint URL`은 Worker 모드를 선택합니다. macOS에서는 `rebut set token`으로 별도의 Worker 접속 토큰을 저장합니다. OpenAI API 키와 접속·관리자 토큰은 서로 다른 자격증명입니다.
33
+
34
+ ```sh
35
+ rebut set endpoint https://YOUR_HOST/mcp
36
+ rebut setup --client codex --replace
37
+ ```
38
+
39
+ 기존 endpoint 설정은 Worker 모드로 유지됩니다. `rebut set mode local`로 명시적으로 전환할 수 있으며 장애 시 다른 backend로 자동 대체하지 않습니다. backend 전환은 기존 기록이나 예약을 이전하지 않습니다.
40
+
41
+ ## 주요 기능
42
+
43
+ - 명시한 파일·diff·요구사항만 수집·마스킹·해시 고정하고 공급자를 한 번 호출합니다.
44
+ - 로컬 SQLite 또는 Worker D1에서 원자적 예산 예약과 요청 중복 방지를 적용합니다. 원문·리뷰·키는 장부에 저장하지 않습니다.
45
+ - 파일·행 근거, 모델 식별, 사용량, 예상 비용을 포함한 구조화된 검토 결과를 반환합니다.
46
+ - `review`와 메타데이터 전용 `review_status`를 제공합니다. unknown 이후 같은 ID를 유지하며 다른 backend로 우회 재실행하지 않습니다.
47
+
48
+ 기본 예시는 UTC 하루 $6.66·월 $200, 동시 pending/unknown 한 건, 하루 신규 요청 100건입니다. **로컬 한도는 해당 기기의 데이터 디렉터리에만 적용**됩니다. 다른 Mac·Worker·외부 API 사용량이나 OpenAI 계정 잔액을 합산하지 않습니다. Worker는 해당 배포의 장부를 공유합니다. 예상 비용은 청구서가 아니며 불확실한 실행의 예약과 슬롯은 유지합니다.
49
+
50
+ 공급자 대기 상한은 30분이며 HTTP/MCP·Codex의 외부 제한도 함께 조정합니다. 로컬 프로필은 OS 소유자가, Worker 프로필은 별도 관리자 인증으로 관리합니다. 자세한 키 설정·모델·예산·Worker 배포는 [설치](docs/guide/ko/installation.md)와 [설정](docs/guide/ko/configuration.md)을 참고하세요.
51
+
52
+ ## 개발 검증
53
+
54
+ ```sh
55
+ npm ci --ignore-scripts
56
+ npm run typecheck
57
+ npm run build
58
+ npm test
59
+ npm run test:package
60
+ ```
61
+
62
+ 자동화 테스트와 패키지 smoke는 공급자를 모의 처리합니다. 기본 실제 API 테스트는 gpt-6-luna, 운영 프로필은 gpt-6-astra / medium이며 Luna 성공으로 Astra 품질을 추론하지 않습니다.
63
+
64
+ ## 문서
65
+
66
+ - [사용자 가이드](docs/guide/ko.md)
67
+ - [설치 및 입력 수집](docs/guide/ko/installation.md)
68
+ - [설정, 예산 및 MCP 계약](docs/guide/ko/configuration.md)
69
+ - [운영 및 복구](docs/guide/ko/operations.md)
70
+ - [선택적 검토자 연동](docs/guide/ko/reviewer-integration.md)
71
+ - [아키텍처](docs/guide/ko/architecture.md)
72
+ - [검증 및 결과의 한계](docs/guide/ko/validation.md)
73
+ - [최초 릴리즈 기록](docs/releases/0.1.0.ko.md) · [0.2.0 릴리즈 후보](docs/releases/0.2.0.ko.md)
74
+ - [MIT 라이선스](LICENSE)
@@ -0,0 +1,73 @@
1
+ <div align="center">
2
+
3
+ # Rebut
4
+
5
+ **默认本地运行的独立代码审查 MCP,可选 Cloudflare Worker。**
6
+
7
+ [한국어](README.md) · [English](README.en.md) · **简体中文** · [日本語](README.ja.md)
8
+
9
+ </div>
10
+
11
+ Rebut 使用您自己的 OpenAI API 密钥审查代码。新安装默认运行本地 stdio 服务器,无需 Cloudflare 账户或独立 HTTP 守护进程。
12
+
13
+ 审查资料会发送至 OpenAI API;本地账本仅存储请求和用量元数据。
14
+
15
+ 验证目标为 macOS/Linux,Windows 行为与 ACL 未验证。
16
+
17
+ ## 快速开始
18
+
19
+ 需要 Node.js 24 或更高版本。以下示例使用 macOS Keychain。
20
+
21
+ ```sh
22
+ npm install -g rebut-mcp
23
+ rebut set api-key
24
+ rebut setup --client codex
25
+ rebut doctor --connect
26
+ ```
27
+
28
+ `rebut set api-key` 隐藏输入 OpenAI API 密钥并存入 Keychain。Linux 等环境请选择 `rebut set secret-store env`,通过实际 MCP 宿主的安全环境提供 `REBUT_OPENAI_API_KEY`。配置仅记录变量名,不要把密钥写入参数或受版本控制的文件。
29
+
30
+ ## 可选 Worker
31
+
32
+ 多台设备需要共享预算和请求账本时,可选择自托管 Worker。`rebut set endpoint URL` 会选择 Worker 模式。macOS 可通过 `rebut set token` 保存独立的 Worker 访问令牌。OpenAI API 密钥、Worker 访问令牌和管理员令牌是不同凭据。
33
+
34
+ ```sh
35
+ rebut set endpoint https://YOUR_HOST/mcp
36
+ rebut setup --client codex --replace
37
+ ```
38
+
39
+ 已有 endpoint 配置继续使用 Worker 模式。通过 `rebut set mode local` 明确切换;失败不会自动切换后端。切换不会迁移已有请求或预留。
40
+
41
+ ## 功能
42
+
43
+ - 仅收集、脱敏并冻结明确提供的文件、diff 和要求,再调用供应商一次。
44
+ - 在本地 SQLite 或 Worker D1 中进行原子预算预留和去重;账本不存储源码、审查正文或密钥。
45
+ - 返回结构化发现、给定文件及行号证据、模型标识、用量与预估成本。
46
+ - 提供 review 和仅元数据的 review_status。不确定后保留同一 ID,不在另一后端重放 unknown 请求。
47
+
48
+ 默认示例为 UTC 每日 $6.66、每月 $200、一个 pending/unknown 请求及每日 100 个新请求。**本地限额仅覆盖该设备的数据目录**,不汇总另一台 Mac、Worker、外部 API 或 OpenAI 账户余额。Worker 用户共享该部署的账本。预估不是账单;不确定的执行继续占用预留和并发槽。
49
+
50
+ 供应商等待上限为 30 分钟,并配套调整 HTTP/MCP 和 Codex 期限。本地配置方案由 OS 所有者管理;Worker 变更需要独立管理员认证。凭据、模型、预算与可选部署见[安装](docs/guide/zh-CN/installation.md)和[配置](docs/guide/zh-CN/configuration.md)。
51
+
52
+ ## 开发者验证
53
+
54
+ ```sh
55
+ npm ci --ignore-scripts
56
+ npm run typecheck
57
+ npm run build
58
+ npm test
59
+ npm run test:package
60
+ ```
61
+
62
+ 自动化测试与包 smoke 测试模拟供应商。默认真实 API 测试使用 gpt-6-luna,生产使用 gpt-6-astra / medium。Luna 成功不证明 Astra 的审查质量。
63
+
64
+ ## 文档
65
+
66
+ - [用户指南](docs/guide/zh-CN.md)
67
+ - [安装与输入收集](docs/guide/zh-CN/installation.md)
68
+ - [配置、预算与 MCP 契约](docs/guide/zh-CN/configuration.md)
69
+ - [运维与恢复](docs/guide/zh-CN/operations.md)
70
+ - [可选审查器集成](docs/guide/zh-CN/reviewer-integration.md)
71
+ - [架构](docs/guide/zh-CN/architecture.md)
72
+ - [验证及结果的局限](docs/guide/zh-CN/validation.md)
73
+ - [MIT 许可证](LICENSE)
package/bin/rebut.mjs ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env node
2
+ import { runCli, safeError } from "../lib/cli.mjs";
3
+ runCli(process.argv.slice(2)).catch((error) => {
4
+ process.stderr.write(safeError(error) + "\n");
5
+ if (!process.exitCode) process.exitCode = 1;
6
+ });
@@ -0,0 +1,28 @@
1
+ {
2
+ "profiles": {
3
+ "astra-medium": {
4
+ "model": "gpt-6-astra",
5
+ "reasoning": "medium",
6
+ "maxOutputTokens": 8192,
7
+ "inputMicrousdPerMillion": 10000000,
8
+ "outputMicrousdPerMillion": 50000000,
9
+ "priceVersion": "openai-standard-2026-11-12"
10
+ },
11
+ "luna-test": {
12
+ "model": "gpt-6-luna",
13
+ "reasoning": "medium",
14
+ "maxOutputTokens": 2048,
15
+ "inputMicrousdPerMillion": 100000,
16
+ "outputMicrousdPerMillion": 500000,
17
+ "priceVersion": "openai-standard-2026-11-12"
18
+ }
19
+ },
20
+ "limits": {
21
+ "dailyMicrousd": 6660000,
22
+ "monthlyMicrousd": 200000000,
23
+ "requestMicrousd": 6660000,
24
+ "maxConcurrent": 1,
25
+ "dailyRequests": 100
26
+ },
27
+ "hostname": "localhost"
28
+ }
@@ -0,0 +1,29 @@
1
+ # Architecture
2
+
3
+ [한국어](../ko/architecture.md) · **English** · [简体中文](../zh-CN/architecture.md) · [日本語](../ja/architecture.md)
4
+
5
+ [Rebut](../../../README.en.md) · [User guide](../en.md)
6
+
7
+ ## Local and Worker execution
8
+
9
+ New installations use local stdio MCP → the shared review service → private SQLite reservation → one OpenAI Responses call → validation and metadata settlement. No Cloudflare account, local HTTP port or daemon is required. Explicit Worker mode retains authenticated HTTP MCP → D1 → the same provider adapter.
10
+
11
+ src/service.ts owns hash/profile selection, request ownership and settlement; src/review.ts owns provider and evidence validation; src/local.ts adapts Node SQLite and stdio; src/worker.ts retains HTTP authentication and D1 bindings. Local provider keys, Worker access tokens and admin tokens are separate. Neither ledger stores source, review bodies or keys. Local budgets and IDs cover only one local directory; Worker principals share one deployment. Switching backends does not migrate history or authorize replay of an uncertain request.
12
+
13
+ The existing Worker-specific path and references follow.
14
+
15
+
16
+ Client explicit allowlist → redact/freeze/hash → authenticated Streamable HTTP MCP → validated profile/hash → atomic D1 reservation → one bounded Responses call → schema/evidence/usage validation → metadata settlement → return review to client.
17
+
18
+ The host-independent contract and provider adapter live in `src/contracts.ts` and `src/review.ts`; `src/worker.ts` supplies MCP/authentication and `src/ledger.ts` supplies the D1 adapter. Cloudflare's per-request `createMcpHandler` uses MCP SDK v2 and supports legacy stateless clients. Stateful sessions, background tasks, OAuth, model-driven tools, repository access, and persisted review replay are outside this MVP.
19
+
20
+ A single `INSERT ... SELECT` evaluates global UTC budgets, active reservations, and daily request counts while writing the request row. Its unique `(principal,request_id)` key selects a single owner with an unpredictable claim. Only that owner dispatches the provider call and settles the row. Crash windows retain the reservation; execution never depends on `waitUntil` or an automatically expired lease. Instructions embedded in supplied material are treated as data, findings must cite supplied lines, and the model has no execution tools.
21
+
22
+ References checked 2026-11-12:
23
+
24
+ - [Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create)
25
+ - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
26
+ - [Cloudflare MCP handler](https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/)
27
+ - [D1 Worker API](https://developers.cloudflare.com/d1/worker-api/d1-database/)
28
+
29
+ Compatibility was checked through a real local Workers/D1 runtime using synthetic upstream responses. This does not establish arbitrary client support or review quality parity with other models.
@@ -0,0 +1,106 @@
1
+ # Configuration and MCP contract
2
+
3
+ [한국어](../ko/configuration.md) · **English** · [简体中文](../zh-CN/configuration.md) · [日本語](../ja/configuration.md)
4
+
5
+ [Rebut](../../../README.en.md) · [User guide](../en.md)
6
+
7
+
8
+ ## Local profiles and budget scope
9
+
10
+ New settings use local mode; endpoint-only legacy settings remain Worker. `rebut set api-key` stores a local OpenAI key in Keychain, while Worker `set token` and `set admin-token` store different credentials. env uses REBUT_OPENAI_API_KEY locally, REBUT_TOKEN/REBUT_ADMIN_TOKEN for Worker. Vaultwarden local keys use vaultwarden-api-key-item. `rebut profile list/set/remove` targets the selected backend; local profile changes require no Worker admin token. Local profiles, revisions and metadata are stored in private SQLite. Limits apply to one data directory, not all devices or the OpenAI account. Use a shared Worker for a central ledger. A mode switch does not migrate uncertain requests or release reservations.
11
+
12
+
13
+ ## Model and reasoning preferences
14
+
15
+ Set local preferences for newly collected bundles, or select a server profile directly:
16
+
17
+ ```sh
18
+ rebut set model MODEL_ID
19
+ rebut set reasoning EFFORT
20
+ rebut set profile PROFILE_ID
21
+ ```
22
+
23
+ `MODEL_ID`, `EFFORT`, and `PROFILE_ID` are placeholders. Model/reasoning preferences resolve an allowlisted server profile; they do not grant arbitrary model access. An explicit collector `--profile` overrides local preferences. With no preferences the default remains `astra-medium`. `rebut review` respects the profile embedded in the frozen bundle and does not rewrite it using current preferences.
24
+
25
+ ## Owner-managed server profiles
26
+
27
+ Worker mode only: local profile management does not require these admin credentials.
28
+
29
+ The owner/admin instructions in this section apply only to Worker mode. Local profile commands use OS ownership and the local SQLite registry.
30
+
31
+ `rebut profile list` makes an authenticated, read-only GET to list server profiles, models, reasoning settings, output limits, rates, and revisions. It does not call the provider or start a paid review.
32
+
33
+ ```sh
34
+ rebut profile list
35
+ rebut set admin-token
36
+ ```
37
+
38
+ Profile mutation requires a separate owner admin bearer. `rebut set admin-token` uses hidden interactive input; `rebut set admin-token --stdin` explicitly accepts a protected pipe. Never pass tokens as arguments or put them in tracked files. macOS Keychain uses service `com.abruption.rebut`, review account `codex-mcp-bearer`, and admin account `codex-mcp-admin`. The selected Vaultwarden backend can use a separate user-selected item: default `Rebut — MCP Admin Token`, configured with `rebut set vaultwarden-admin-item NAME`. The env backend reads `REBUT_ADMIN_TOKEN` from a secure execution environment. The admin token is never forwarded to Codex. There is no automatic backend fallback.
39
+
40
+ After a one-time Worker upgrade, D1 migration `0002`, and `ADMIN_TOKEN_SHA256` secret setup described in [installation](installation.md), the owner can add/update a profile. This example uses the existing Astra/medium configuration and its dated 2026-11-12 Standard rates; verify the official [model](https://developers.openai.com/api/docs/models/gpt-6-astra) and [pricing](https://developers.openai.com/api/docs/pricing) documents before choosing values. For a new model, substitute the placeholder `MODEL_ID` with a verified Responses-compatible model ID and explicitly supply its supported reasoning setting, output limit, and official rates.
41
+
42
+ ```sh
43
+ rebut profile set astra-medium --model gpt-6-astra --reasoning medium --max-output-tokens 8192 --input-usd-per-million 10 --output-usd-per-million 50 --price-version official-2026-11-12
44
+ ```
45
+
46
+ Both prices and `--price-version` are required; the server uses them for budget reservations and cost estimates. Rebut does not automatically fetch prices or call a provider models endpoint. `--if-revision N` adds an explicit compare-and-swap revision condition to set/remove. A `409` conflict requires rereading `rebut profile list` and deciding what to change; never overwrite automatically.
47
+
48
+ ```sh
49
+ rebut profile remove PROFILE_ID --if-revision N
50
+ ```
51
+
52
+ Removal creates a disabling tombstone rather than deleting review history. Once Worker/D1 support is installed, these profile changes write D1 only: Responses-compatible new model IDs or reasoning values require no Worker build/deploy or npm upgrade. Existing requests retain their original model and revision after profile updates or removal. Changes never rerun requests or automatically release/refund reservations. The normal review bearer cannot mutate profiles; this owner API is not exposed as an MCP tool and cannot change budgets, authentication, or the provider URL.
53
+
54
+ ## Server configuration
55
+
56
+ [`config.example.json`](../../../config.example.json) defines the structure of the `REBUT_CONFIG` secret. Set `hostname` to the exact endpoint hostname, configure server-side profile IDs, and set deployment-wide limits. Clients choose profile IDs; they cannot override model names or the provider URL. The example is configuration, not a promise of account-level model access.
57
+
58
+ `REBUT_CONFIG` supplies seed profiles. D1 overrides and disabling tombstones take precedence; profile removal does not restore a seed with the same ID. The server freezes the resolved profile and revision for each reserved request.
59
+
60
+ | Profile | Model | Reasoning | Maximum output tokens | Standard input/output per 1M tokens |
61
+ | -------------- | ------------- | --------- | --------------------- | ----------------------------------- |
62
+ | `astra-medium` | `gpt-6-astra` | `medium` | 8,192 | $10 / $50 |
63
+ | `luna-test` | `gpt-6-luna` | `medium` | 2,048 | $0.10 / $0.50 |
64
+
65
+ Output limits include reasoning tokens. The dated price table is `openai-standard-2026-11-12`; estimates apply no cached-input discount. Use **Luna for real API tests** and mocks for automated tests. The production profile remains Astra/medium; Luna results do not establish Astra runtime availability or equivalent review quality. Verify the official [Astra](https://developers.openai.com/api/docs/models/gpt-6-astra), [Luna](https://developers.openai.com/api/docs/models/gpt-6-luna), and [pricing](https://developers.openai.com/api/docs/pricing) documents before deploying.
66
+
67
+ Requests pin `service_tier:default` and `prompt_cache_options.mode:explicit` with no breakpoints, disabling prompt caching for these profiles. No execution tools are supplied. Estimates are not invoices and do not account for other services sharing the key or project.
68
+
69
+ ## Budget and concurrency
70
+
71
+ | Setting | Example value |
72
+ | ----------------------------------- | ---------------------------------- |
73
+ | UTC calendar day | $6.66 (`dailyMicrousd:6660000`) |
74
+ | UTC calendar month | $200 (`monthlyMicrousd:200000000`) |
75
+ | Per request | $6.66 (`requestMicrousd:6660000`) |
76
+ | Concurrent pending/unknown requests | 1 (`maxConcurrent:1`) |
77
+ | New review requests per UTC day | 100 (`dailyRequests:100`) |
78
+
79
+ These limits aggregate all principals in the deployment. Reserve before calling: serialized request bytes plus framing padding count as input tokens, and the maximum output budget is reserved. Validated usage settles conservatively at uncached Standard rates. Unknown execution or missing usage keeps the full reservation. A new UTC day/month resets that period's spend window; unresolved executions continue occupying concurrency. Budget windows follow the original submission date, not a subscription credit's grant or expiration date. This ledger cannot enforce an OpenAI account-wide limit across other consumers. Confirm your account/organization's credit eligibility separately.
80
+
81
+ ## Input limits and hashing
82
+
83
+ | Material | Limit |
84
+ | --------------------------------------- | ------------------ |
85
+ | Canonically serialized UTF-8 JSON input | 128,000 bytes |
86
+ | Files | 40 |
87
+ | Diff | 100,000 characters |
88
+ | Requirements | 16,000 characters |
89
+ | Transport envelope | 160,000 bytes |
90
+
91
+ The SHA-256 covers canonical `{schema_version,task_kind,requirements,files,diff}` after redaction, with file key order `{path,start_line,content}`. Request IDs and profile names are separate from this frozen evidence hash. See [`ReviewInputSchema`](../../../src/contracts.ts) for the full contract. Preserve the same evidence for independent first-pass reviewers and keep their outputs separate.
92
+
93
+ ## MCP tools
94
+
95
+ - `review`: choose an allowlisted profile ID and supply the frozen material. Returns status, validated findings, provider model/IDs, hash, usage and estimated microUSD. Only `completed` is a successful review. Refusal, incomplete generation, invalid output, and unknown execution remain distinct. Every finding must reference supplied file lines or supplied new-side diff lines. An empty findings array with a nonempty summary is valid; an empty or malformed response is not.
96
+ - `review_status`: `{request_id}` returns only metadata for the caller's principal. It cannot replay the review body.
97
+
98
+ After a timeout, query **the same request ID**. Repeating it never creates another provider execution. Reusing an ID with a changed input hash or profile returns `conflict`. A completed duplicate returns metadata rather than the review body: clients must save their initial response locally. See [operations](operations.md) for reconciliation; `not_found` after a transport failure is not by itself permission to use a new ID.
99
+
100
+ ## Storage and privacy
101
+
102
+ The metadata-only D1 ledger retains request IDs, hashes, profile, status, reservation, sanitized provider IDs and usage. It never stores source or review text. Worker observability is disabled in the example. `AUTH_TOKENS` contains token digests, not bearer values; keep original bearer tokens in your password manager. See [installation](installation.md) for setup.
103
+
104
+ The OpenAI request uses `store:false`; this does **not** promise zero provider retention or replace your organization's data policy. See [OpenAI data controls](https://developers.openai.com/api/docs/guides/your-data). Keep credentials and private deployment identifiers outside public source and logs.
105
+
106
+ When the result is `invalid_output`, `invalid_output_reason` identifies the failed validation stage without retaining source or review text. Intermediate `commentary` messages are excluded; only `final_answer` (or a legacy message with no phase) is parsed as the structured review. Multiple final outputs, invalid JSON/schema, and findings outside supplied evidence remain errors.
@@ -0,0 +1,103 @@
1
+ # Installation and input collection
2
+
3
+ [한국어](../ko/installation.md) · **English** · [简体中文](../zh-CN/installation.md) · [日本語](../ja/installation.md)
4
+
5
+ [Rebut](../../../README.en.md) · [User guide](../en.md)
6
+
7
+
8
+ Use Node.js **24 or later**. New installations default to a local stdio MCP server. No Cloudflare account, Worker endpoint or HTTP daemon is required.
9
+
10
+ ```sh
11
+ npm install -g rebut-mcp
12
+ ```
13
+
14
+ ## Local setup
15
+
16
+ On macOS, `rebut set api-key` takes hidden OpenAI API key input and stores it in the login Keychain. The provider account is `openai-api-key` under `com.abruption.rebut`, separate from the Worker access/admin accounts. `--stdin` accepts a protected pipe; never use credential values as command arguments.
17
+
18
+ ```sh
19
+ rebut set api-key
20
+ ```
21
+
22
+ For environment-backed credentials, select `rebut set secret-store env` and provide `REBUT_OPENAI_API_KEY` in the secure environment of the actual MCP host. Setup records only that variable name. For Vaultwarden, use `rebut set secret-store vaultwarden` and `rebut set vaultwarden-api-key-item NAME`; the default local item is `Rebut — OpenAI API Key`. Existing bw-get login is required. There is no automatic credential or backend fallback.
23
+
24
+ ## Connect and verify
25
+
26
+ ```sh
27
+ rebut setup --client codex
28
+ rebut doctor --connect
29
+ ```
30
+
31
+ `rebut setup --client codex` registers `rebut mcp` using CODEX_HOME or ~/.codex; select another home with --codex-home PATH. The host starts the server automatically. `doctor --connect` checks local credential availability, SQLite and real MCP tool registration without making a provider call; it does not prove API account access. Local env setup forwards REBUT_OPENAI_API_KEY by name only. Preserve custom REBUT_CONFIG_DIR when replacing a registration.
32
+
33
+ ## Optional Worker mode
34
+
35
+ Setting an endpoint explicitly selects Worker mode. Existing endpoint-only configurations keep Worker mode on upgrade. Worker mode uses its separate MCP access token, not the local OpenAI key: on macOS store it with `rebut set token`; env mode reads REBUT_TOKEN and Vaultwarden uses vaultwarden-item. Admin operations use the separate admin credential. Use the private deployment section below if you need to create a Worker.
36
+
37
+ ```sh
38
+ rebut set endpoint https://YOUR_HOST/mcp
39
+ rebut setup --client codex --replace
40
+ ```
41
+
42
+ Use `rebut set mode local` to switch explicitly. No automatic fallback occurs. Backends do not share or migrate request history, reservations or budgets: never replay an unknown against another backend. Local SQLite lives at ~/.local/share/rebut/local/ledger.sqlite, or local/ under a custom REBUT_CONFIG_DIR. Defaults are UTC $6.66/day and $200/month for this data directory only; local budget commands are `set daily-budget`, `set monthly-budget`, and `set request-budget` with decimal USD values. Worker limits remain deployment configuration.
43
+
44
+ ## Source checkout and developer validation
45
+
46
+ This guide targets CLI 0.2.0. The npm package runs the local server and optional Worker bridge; it is not a hosted review service and grants no API credits. Only optional Worker deployment needs a Cloudflare account and source checkout. Packages contain no real endpoint, private settings, credentials or review bodies.
47
+
48
+ ```sh
49
+ npm ci
50
+ npm run typecheck
51
+ npm run build
52
+ npm test
53
+ ```
54
+
55
+ Tests use synthetic inputs, mocked provider responses, real SQLite statements, and a local Workers/D1 runtime. `npm test` requires the Worker bundle from `npm run build`. No automated test makes a paid model call. See the [validation record](validation.md) for the separate Luna smoke test.
56
+
57
+ ## Freeze a review input
58
+
59
+ Use an explicit source-file allowlist; do not collect an entire repository automatically. The collector emits frozen JSON on stdout. Default profile: `astra-medium`; real API tests must explicitly use `luna-test`.
60
+
61
+ ```sh
62
+ umask 077
63
+ rebut collect --root /path/to/project --request-id request-001 --requirements 'Check that the supplied function preserves its input' --profile astra-medium -- src/example.ts > /protected/path/request-001.bundle.json
64
+ ```
65
+
66
+ The collector rejects symlinks, FIFOs, secret filenames, binary files, and oversize material. It removes common recognizable secret patterns while preserving line numbers. Pattern redaction is incomplete: inspect the resulting bundle before sending. Files may also be supplied as numbered snippets, or a unified diff may be provided directly. The canonical hash and limits are explained under [configuration](configuration.md).
67
+
68
+ ## Deploy privately
69
+
70
+ 1. Copy `wrangler.jsonc` to `wrangler.private.json` (ignored by Git). Set your account ID, an available Worker name, actual D1 ID, and `workers_dev:true` or your own route. Create a dedicated D1 database with `npx wrangler d1 create rebut-ledger`; set its ID in the private config.
71
+ 2. Apply `npx wrangler d1 migrations apply rebut-ledger --remote --config wrangler.private.json`.
72
+ 3. Deploy with `npx wrangler deploy --config wrangler.private.json`. An unconfigured Worker returns 503 and cannot call the provider.
73
+ 4. Store three Workers Secrets: `OPENAI_API_KEY`, `REBUT_CONFIG`, and `AUTH_TOKENS`. Use Wrangler's interactive secret prompt or `secret bulk` via protected stdin; never put secret values in arguments or tracked files. `REBUT_CONFIG` uses the structure in [`config.example.json`](../../../config.example.json); change `hostname` to your exact endpoint hostname. `AUTH_TOKENS` is a JSON object mapping stable principal IDs to SHA-256 digests of independently generated random 256-bit bearer tokens. Store original tokens in your password manager. Clients with the same token share a principal; distinct tokens isolate request/status access.
74
+ 5. Connect a bearer-header-capable MCP client to `https://YOUR_HOST/mcp`, and verify `tools/list`. Host and browser Origin validation apply before tool execution. This bearer setup does not implement OAuth for clients that require OAuth discovery.
75
+
76
+ ## One-time upgrade for owner-managed profiles
77
+
78
+ Dynamic profiles require one Worker upgrade from the source checkout, D1 migration `0002`, and the `ADMIN_TOKEN_SHA256` Worker secret. Apply pending migrations to the existing D1 database, preserving its ledger, then deploy the upgraded Worker with your private config. Generate a separate random 256-bit admin bearer, store its SHA-256 hash as `ADMIN_TOKEN_SHA256` using a protected interactive secret prompt, and keep the original bearer in your credential store. Do not reuse the review bearer or change existing principal IDs. After this one-time setup, CLI profile changes write D1 without another Worker build/deploy or npm upgrade.
79
+
80
+ Store the owner bearer with `rebut set admin-token` (hidden input), or explicitly use `rebut set admin-token --stdin` with a protected pipe. With the selected Vaultwarden backend, the default admin item is `Rebut — MCP Admin Token`; change it with `rebut set vaultwarden-admin-item NAME`. The env backend uses `REBUT_ADMIN_TOKEN` in a secure execution environment; it is never forwarded to Codex. Keychain service `com.abruption.rebut` separates review account `codex-mcp-bearer` from admin account `codex-mcp-admin`. Backends do not fall back automatically. See [configuration](configuration.md) for model preferences, listing, explicit prices, and revision-safe updates/removal.
81
+
82
+ ## Run the client
83
+
84
+ `rebut review` reads a JSON bundle from stdin and starts a paid review only when explicitly selected by the user. `rebut status REQUEST_ID` is a free metadata query.
85
+
86
+ ```sh
87
+ rebut review < /protected/path/request-001.bundle.json
88
+ rebut status request-001
89
+ ```
90
+
91
+ Save the initial response locally with restrictive permissions; the server stores only metadata and cannot replay review bodies. Keep the same request ID after timeout or uncertainty. The provider deadline is 1,800 seconds (30 minutes). The MCP HTTP client allows 1,830 seconds and Codex `tool_timeout_sec` is 1,860 seconds, leaving time to record and deliver the outcome. Startup and handshake limits remain short and separate. Update both the Worker and CLI, refresh existing registration with `rebut setup --client codex --replace`, and restart Codex. Editing host configuration alone does not update the older limit inside the 0.1.0 CLI. See the [opt-in reviewer workflow](reviewer-integration.md).
92
+
93
+ ## Upgrade or remove
94
+
95
+ Use the [operations guide](operations.md) to preserve the D1 ledger and reconcile pending executions before upgrading or removing a deployment. Source publication and a private paid deployment are separate actions.
96
+
97
+ Upgrade in this order: **install the CLI → refresh Codex registration with existing options preserved → restart Codex/MCP → deploy the Worker**. Deploying the longer Worker deadline first can let the old CLI disconnect at 65 seconds. Preserve custom registration options such as `REBUT_CONFIG_DIR`. Node HTTP headers/body deadlines also match the MCP tool deadline. Thirty minutes is an application upper bound, not a guarantee from every network or host. Sleep, termination or disconnection can leave a request reserved or unknown; query its original ID without automatic replay or reservation release.
98
+
99
+ After changing mode, credential backend or local budgets, refresh registration with `rebut setup --client codex --replace` when needed and restart MCP hosts. Existing processes keep their startup settings; doctor does not reload them. Preserve custom `REBUT_CONFIG_DIR` (for example, provide the same environment variable when rerunning setup). The chosen secret-store backend applies to all credential roles, which use separate accounts/items.
100
+
101
+ Local env mode defaults to REBUT_OPENAI_API_KEY so a key belonging to Codex or another application is not silently reused. To deliberately share OPENAI_API_KEY, run `rebut set api-key-env OPENAI_API_KEY`, refresh registration and restart. There is no fallback between these variables. Daily, monthly and per-request ceilings are independent; changing one does not scale the others. Custom limits are retained across upgrades. Tool descriptions are startup hints; execution resolves the explicit request profile dynamically.
102
+
103
+ The tested release targets macOS/Linux; Windows behavior and ACLs are not validated.