sfbench 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atsuhiko Kimura
+
+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.ja.md

@@ -0,0 +1,165 @@
+# sfbench
+
+sfbench は、Salesforce の SOQL、REST API、匿名 Apex を手元のブラウザで実行するツールです。
+認証は sf CLI に保存済みのものを使うので、接続アプリケーションの作成や組織の設定は要りません。
+
+[English README](README.md)
+
+![sfbench の SOQL の画面。AI がクエリを提案している](help/images/ja/soql-ai.webp)
+
+sfbench は [lwc-soql-builder](https://github.com/lwc-soql-builder/lwc-soql-builder) の後継です。
+lwc-soql-builder は、Salesforce が OAuth のユーザーエージェントフローを使えなくしたため、ログインできなくなりました。
+
+## 特徴
+
+### SOQL
+
+- クリック操作で SOQL を組み立てる。項目を API 名でもラベルでも探せる
+- 親リレーション、子リレーション（サブクエリ）をたどって項目を選ぶ
+- カーソルの位置に応じた補完（FROM のあとはオブジェクト、`Account.` のあとは参照先の項目、サブクエリの中は子オブジェクトの項目）
+- 管理パッケージの名前空間を省略して書ける
+- 数万件の結果も、スクロールに合わせて続きを読み込む。子リレーションのレコードは表で開く
+- 読み込んだ結果の行を絞り込み、全件を CSV に出力する
+- 結果の表で値を書き換えて保存し、行を選んで削除する
+- Tooling API と Query All でのクエリ、API バージョンの指定
+
+### REST API
+
+- メソッド、パス、ヘッダー、JSON のボディを入れて送る。ボディの整形と色分け
+- 4xx と 5xx もレスポンスとして、ステータス、ヘッダー、本文を見る
+- 送った要求は実行履歴に残り、押すと欄に読み込む
+
+### 匿名 Apex
+
+- Apex を色分けして書き、実行する。API バージョンも指定できる
+- コンパイルエラーと例外は、行と列へ移るボタン付きで出す
+- デバッグログを検索し、`USER_DEBUG` の行だけに絞る
+- 実行したコードは実行履歴に残る
+
+### AI
+
+- やりたいことを書くと、AI が SOQL、REST API の要求、匿名 Apex を組む
+- 失敗したクエリ、要求、Apex を、エラー文をもとに AI が直す
+- AI の提案は差分で見せ、置き換えるまで画面を変えない。REST API と Apex は、置き換えても自動では送らない・実行しない
+- Anthropic か OpenAI の API キーを、設定画面で入れて使う
+
+### そのほか
+
+- AI のエージェント（Claude Code など）から、クエリや要求を入れた状態で起動できる
+- 本番の組織では、データを変える操作の前に確認する
+- 結果が分からなかった要求（タイムアウトなど）を送り直す前に確認する
+
+## 必要なもの
+
+- Node.js 22.21.0 以上の 22 系、または 24.5.0 以上
+- [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli)（`sf`）と、使う組織へのログイン
+
+macOS、Linux、Windows で動きます。
+組織へのログインは sf CLI で行います。
+
+```
+sf org login web -a my-org
+```
+
+## 使い方
+
+```
+npx sfbench
+```
+
+ブラウザで sfbench が開きます。
+組織は、画面右上の組織の切り替えから選びます。
+`-o` を付けない場合は、sf CLI の既定の組織（`sf config set target-org <alias>` で設定したもの）で開きます。
+
+画面の上のタブで、SOQL、REST API、Apex を切り替えます。
+タブを切り替えても、それぞれの画面の入力や結果は残ります。
+各画面の使い方は、[ヘルプ](help/ja/README.md)にあります。
+
+### コマンドライン引数
+
+| 引数 | 内容 |
+| --- | --- |
+| `-o, --target-org <alias>` | 開く組織 |
+| `--query "<SOQL>"` | SOQL を入力した状態で開く |
+| `--run` | `--query` の SOQL を実行した状態で開く |
+| `--rest <path>` | REST API の画面を、この要求を入れた状態で開く。送信はしない |
+| `--method <method>` | `--rest` の要求のメソッド。GET（既定）、POST、PATCH、PUT、DELETE |
+| `--body <json>`、`--body-file <file>` | `--rest` の要求の JSON のボディ |
+| `--apex "<code>"`、`--apex-file <file>` | Apex の画面を、このコードを入れた状態で開く。実行はしない |
+| `--json` | 開いた URL などを JSON で出力する |
+| `--no-open` | ブラウザを開かず、URL だけを出力する |
+| `stop` | 起動中の sfbench を止める |
+
+データを変えうる REST API の要求と Apex は、入れた状態で開くだけで、送信や実行は画面のボタンで行います。
+
+### AI のエージェントから使う
+
+AI のエージェントは、sfbench をまだ知りません。
+何も教えずに「sfbench で〜」と頼むと、Claude Code は `sfbench` コマンドを探して見つけられず、sf CLI で直接クエリを実行しました。
+Claude Code には、sfbench の使い方を教えるスキルを、このリポジトリからプラグインとして入れられます。
+
+```
+claude plugin install sfbench --marketplace atskimura/sfbench
+```
+
+Claude Code の中では `/plugin install sfbench --marketplace atskimura/sfbench` でも入れられます。
+指示ファイル（`CLAUDE.md`）を書き換える必要はありません。
+スキルのファイルを自分で置くこともできます。
+日本語版は [plugins/sfbench/ja/sfbench/SKILL.md](plugins/sfbench/ja/sfbench/SKILL.md)、英語版は [plugins/sfbench/skills/sfbench/SKILL.md](plugins/sfbench/skills/sfbench/SKILL.md) です。
+`sfbench` フォルダごと、エージェントがスキルを読む場所（Claude Code なら `~/.claude/skills/`、Codex なら `~/.agents/skills/`）に置きます（Codex では試していません）。
+
+スキルを入れた Claude Code に「sfbench で成約済みの商談を一覧して」と頼むと、エージェントは SOQL を組み立てて次のように起動します。
+
+```
+npx -y sfbench -o my-org --query "SELECT Id, Name, Amount FROM Opportunity WHERE IsWon = true" --run
+```
+
+sfbench はブラウザでクエリを実行した結果を開き、コマンドはすぐ終了します。
+すでに起動している場合は、新しいタブを開きます。
+
+REST API の要求や Apex も、同じように入れた状態で開けます。
+
+```
+npx -y sfbench -o my-org --rest /services/data/v62.0/sobjects/Account --method POST --body-file account.json
+npx -y sfbench -o my-org --apex-file fix-data.apex
+```
+
+### AI で組む機能
+
+設定画面（右上の歯車）で、AI の提供元（Anthropic か OpenAI）、モデル ID、API キーを入れます。
+API キーはこの PC の `~/.sfbench/settings.json` に本人だけが読める形で保存し、ブラウザには表示しません。
+AI を呼ぶのは「生成」か「AI で直す」を押したときだけで、呼ぶたびに API キーの持ち主に提供元の料金がかかります。
+
+AI に送るのは、オブジェクトと項目の名前、型、ラベル、選択リストの値、画面の内容（エディタのクエリやコード、いまの要求）、直すときのエラー文です。
+送る情報は入力欄の下の札で示し、画面の内容は札を押せば送らないようにできます。
+SOQL の結果は送りません。
+REST API のレスポンスと Apex の実行結果は、「この結果を使って AI に頼む」を押したときだけ送ります。
+
+## 仕組み
+
+sfbench は手元で小さな Web サーバー（`http://127.0.0.1:7717`。使用中なら 7736 までの空いているポート）を起動し、ブラウザで画面を開きます。
+Salesforce への問い合わせはこのサーバーが行い、アクセストークンは sf CLI から取得します。
+トークンがブラウザやほかのサーバーに渡ることはありません。
+サーバーは自動では止まりません。止めるときは `npx sfbench stop` を実行します。
+
+設定、最近のクエリ、REST API と Apex の実行履歴は `~/.sfbench/` に保存します。
+サーバーのログは `~/.sfbench/server.log` にあります。
+ログには、SOQL、要求のボディ、Apex のコード、レコードの値を書きません。
+
+## 開発
+
+```
+npm install
+npm run dev   # 画面の開発サーバーとローカルサーバーを起動する
+```
+
+`http://localhost:5173/launch/dev` を開きます。
+コードを保存すると、画面とサーバーにそのまま反映されます。
+
+設計は [docs/design.md](docs/design.md) にあります。
+
+## ライセンス
+
+MIT
+
+画面に取り込んでいるライブラリのライセンスは、設定画面の「ライセンス」から見られます（公開物の `dist/web/licenses.txt`）。

package/README.md

@@ -0,0 +1,164 @@
+# sfbench
+
+sfbench runs Salesforce SOQL, REST API requests and anonymous Apex in your browser, on your own machine.
+It uses the auth you already have in the sf CLI, so there is no connected app to create and nothing to set up in your org.
+
+[日本語の README](README.ja.md)
+
+![The SOQL screen of sfbench, with a query proposed by the AI](help/images/en/soql-ai.webp)
+
+sfbench is the successor to [lwc-soql-builder](https://github.com/lwc-soql-builder/lwc-soql-builder).
+lwc-soql-builder can no longer log in, because Salesforce has blocked the OAuth user-agent flow it relied on.
+
+## Features
+
+### SOQL
+
+- Build SOQL by clicking. Find fields by API name or by label
+- Pick fields through parent relationships and child relationships (subqueries)
+- Completion that follows the cursor: objects after FROM, the target's fields after `Account.`, the child object's fields inside a subquery
+- Leave out the namespace of a managed package
+- Results of tens of thousands of rows load as you scroll. Child relationship records open in their own table
+- Filter the loaded rows, and export the whole result to CSV
+- Edit values in the result table and save them, or select rows and delete them
+- Queries with the Tooling API and Query All, on the API version you choose
+
+### REST API
+
+- Send a request with its method, path, headers and JSON body. The body is formatted and colored
+- See 4xx and 5xx answers as responses, with their status, headers and body
+- Requests you sent stay in the history; click one to load it again
+
+### Anonymous Apex
+
+- Write Apex with syntax colors and run it, on the API version you choose
+- Compile errors and exceptions come with a button that goes to their line and column
+- Search the debug log, or show only its `USER_DEBUG` lines
+- The code you ran stays in the history
+
+### AI
+
+- Write what you want, and an AI writes the SOQL, the REST API request or the anonymous Apex
+- An AI fixes a query, a request or Apex that failed, from its error
+- Proposals show as differences and change nothing until you replace. REST API requests and Apex are never sent or run by the AI: you press Send or Run
+- Bring your own Anthropic or OpenAI API key, set in the settings
+
+### And more
+
+- AI agents (such as Claude Code) can open sfbench with a query, a request or Apex filled in
+- In a production org, sfbench asks before anything that changes data
+- sfbench asks before sending again a request whose outcome is not known (after a timeout, for example)
+
+## Requirements
+
+- Node.js 22.21.0 or later in the 22 line, or 24.5.0 or later
+- The [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli) (`sf`), logged in to the orgs you use
+
+sfbench runs on macOS, Linux and Windows.
+You log in to orgs with the sf CLI:
+
+```
+sf org login web -a my-org
+```
+
+## Usage
+
+```
+npx sfbench
+```
+
+sfbench opens in your browser.
+Choose an org from the org switcher at the top right.
+Without `-o`, sfbench opens the sf CLI's default org (the one set with `sf config set target-org <alias>`).
+
+The tabs at the top switch between SOQL, REST API and Apex.
+Each screen keeps what you typed and its result while another is shown.
+The [help](help/en/README.md) explains each screen.
+
+### Command-line options
+
+| Option | Description |
+| --- | --- |
+| `-o, --target-org <alias>` | The org to open |
+| `--query "<SOQL>"` | Open with this SOQL in the editor |
+| `--run` | Also run the `--query` SOQL |
+| `--rest <path>` | Open the REST API screen with this request. It is not sent |
+| `--method <method>` | The `--rest` request's method: GET (default), POST, PATCH, PUT or DELETE |
+| `--body <json>`, `--body-file <file>` | The `--rest` request's JSON body |
+| `--apex "<code>"`, `--apex-file <file>` | Open the Apex screen with this code. It is not run |
+| `--json` | Print the opened URL and more as JSON |
+| `--no-open` | Print the URL without opening a browser |
+| `stop` | Stop the running sfbench |
+
+A REST API request or Apex, which may change data, is only filled in: you send or run it with the button on the screen.
+
+### From an AI agent
+
+AI agents do not know sfbench yet.
+Asked to "use sfbench" with no hint, Claude Code looked for an `sfbench` command, did not find it, and ran the query with the sf CLI instead.
+For Claude Code, install the skill that teaches it sfbench, as a plugin from this repository:
+
+```
+claude plugin install sfbench --marketplace atskimura/sfbench
+```
+
+Inside Claude Code, `/plugin install sfbench --marketplace atskimura/sfbench` does the same.
+Your instructions file (`CLAUDE.md`) stays as it is.
+You can also put the skill's file in place yourself: [plugins/sfbench/skills/sfbench/SKILL.md](plugins/sfbench/skills/sfbench/SKILL.md) in English, or [plugins/sfbench/ja/sfbench/SKILL.md](plugins/sfbench/ja/sfbench/SKILL.md) in Japanese.
+Copy the `sfbench` folder to where the agent reads skills (`~/.claude/skills/` for Claude Code, `~/.agents/skills/` for Codex; untested with Codex).
+
+With the skill, ask Claude Code to "list the won opportunities in sfbench", and it writes the SOQL and starts sfbench like this:
+
+```
+npx -y sfbench -o my-org --query "SELECT Id, Name, Amount FROM Opportunity WHERE IsWon = true" --run
+```
+
+sfbench opens the result in your browser, and the command returns right away.
+If sfbench is already running, it opens a new tab.
+
+A REST API request or Apex can be filled in the same way:
+
+```
+npx -y sfbench -o my-org --rest /services/data/v62.0/sobjects/Account --method POST --body-file account.json
+npx -y sfbench -o my-org --apex-file fix-data.apex
+```
+
+### Writing with AI
+
+In the settings (the gear at the top right), choose the AI provider (Anthropic or OpenAI) and enter the model ID and your API key.
+The key is saved in `~/.sfbench/settings.json` on your machine, readable by you only, and never shown in the browser.
+sfbench calls the AI only when you press Generate or Fix with AI, and each call is billed to the key's owner by the provider.
+
+What goes to the AI: the names, types and labels of objects and fields, picklist values, what is on the screen (the query or code in the editor, the request in the fields), and the error when fixing.
+The pills under the input show what is sent; untick a pill to keep what is on the screen from being sent.
+SOQL results are never sent.
+A REST API response or an Apex result is sent only when you press "Use this result with AI".
+
+## How it works
+
+sfbench starts a small web server on your machine (`http://127.0.0.1:7717`, or the next free port up to 7736) and opens its page in your browser.
+The server sends the requests to Salesforce, with an access token it gets from the sf CLI.
+The token never goes to the browser or to any other server.
+The server keeps running until you stop it with `npx sfbench stop`.
+
+Settings, recent queries, and the REST API and Apex histories are saved in `~/.sfbench/`.
+The server log is `~/.sfbench/server.log`.
+The log never holds SOQL, request bodies, Apex code or record values.
+
+## Development
+
+```
+npm install
+npm run dev   # starts the web dev server and the local server
+```
+
+Open `http://localhost:5173/launch/dev`.
+Saved changes show up in the page and the server right away.
+
+The design documents in [docs/](docs/) are in Japanese.
+
+## License
+
+MIT
+
+The licenses of the libraries bundled into the web interface are under "Licenses" in the settings (`dist/web/licenses.txt` in the package).

package/dist/server/ai/agent.js

@@ -0,0 +1,132 @@
+import { agentPrompt, checkAgentOutput } from "./agentTasks.js";
+import { anthropicConversation } from "./anthropic.js";
+import { AiError } from "./errors.js";
+import { openAiConversation } from "./openai.js";
+import { findObject, MAX_READ_BYTES, METADATA_TOOLS, newReadState, readObject, runTool, shown } from "./tools.js";
+/** Local models are out, but large models can still take minutes (docs/ai.md "API"). */
+export const AI_TIMEOUT_MS = 300_000;
+/** The most metadata tool calls in one request (docs/ai-agent.md). */
+export const MAX_TOOL_CALLS = 8;
+/** The most text the tools return in one request, about 30,000 tokens. */
+export const MAX_TOOL_BYTES = 100_000;
+/** Which limit stops the tools: the text they return, or else the number of calls. */
+const limitName = (toolBytes) => (toolBytes >= MAX_TOOL_BYTES ? `the limit of what the tools return (${MAX_TOOL_BYTES / 1000} KB)` : `the limit of ${MAX_TOOL_CALLS} tool calls`);
+const CONVERSATIONS = {
+    anthropic: anthropicConversation,
+    openai: openAiConversation,
+};
+const encoder = new TextEncoder();
+/** Today in the user's time zone, as YYYY-MM-DD. */
+export function todayIn(timeZone, now = new Date()) {
+    return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(now);
+}
+/**
+ * The tiny request of "Test connection" (docs/ai-agent.md "接続を確かめる"):
+ * proves the model calls tools, submit included, before a screen finds out.
+ * The org is not read: the tools find nothing.
+ */
+export const TEST_AGENT_REQUEST = {
+    task: 'generateApex',
+    input: { request: 'Print the number 1 with System.debug.', language: 'en', timeZone: 'UTC' },
+};
+export const NO_METADATA = { objects: async () => [], describe: async () => undefined };
+/**
+ * What the screen named, matched against the org's objects: the open object
+ * as a hint, and the fields of the object a failed query read from
+ * (docs/ai-agent.md "タスク"). A name the org does not have is left out.
+ */
+async function givenMetadata(req, source, state) {
+    if (req.task === 'generateSoql' && req.input.openObject) {
+        const open = await findObject(source, req.input.openObject);
+        return open ? { openObject: shown(source, open.name) } : {};
+    }
+    if (req.task === 'fixSoql' && req.input.object) {
+        // Within one result, so that the AI can still find fields with what is left.
+        const fields = await readObject(source, req.input.object, MAX_READ_BYTES, state);
+        return fields ? { fields } : {};
+    }
+    return {};
+}
+/**
+ * Runs one task. `signal` is the caller's (the web UI going away); the
+ * timeout is added here. Throws AiError.
+ */
+export async function runAgent(ai, req, source, apiVersion, signal, timeoutMs = AI_TIMEOUT_MS) {
+    if (!ai || ai.provider === 'off')
+        throw new AiError('AI_NOT_CONFIGURED', 'AI is not set up. Choose an AI in the settings.');
+    if (!ai.model.trim())
+        throw new AiError('AI_NOT_CONFIGURED', 'No model ID is saved for the AI. Enter it in the settings.');
+    // Checked again here, not only when saving: a key never goes to a provider it was not entered for.
+    if (!ai.apiKey || ai.keyProvider !== ai.provider)
+        throw new AiError('AI_NOT_CONFIGURED', 'No API key is saved for this AI. Enter it in the settings.');
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(), timeoutMs);
+    const both = AbortSignal.any([signal, timeout.signal]);
+    let aiCalls = 0;
+    let toolCalls = 0;
+    let toolBytes = 0;
+    // One nudge each: to call submit at all, and to stop reading past the limit.
+    let nudgedToSubmit = false;
+    let nudgedAtLimit = false;
+    try {
+        // What the AI has read in this request: objects read in full are not sent again.
+        const state = newReadState();
+        const given = await givenMetadata(req, source, state);
+        // Fields given from the start count against the budget as the tools' results do.
+        if (given.fields)
+            toolBytes += encoder.encode(given.fields).length;
+        const prompt = agentPrompt(req, apiVersion, todayIn(req.input.timeZone), given);
+        const submit = { name: 'submit', description: 'Gives the final answer. Call it once, when done.', schema: prompt.submitSchema };
+        const conversation = CONVERSATIONS[ai.provider]({
+            apiKey: ai.apiKey,
+            model: ai.model,
+            system: prompt.system,
+            user: prompt.user,
+            tools: [...METADATA_TOOLS, submit],
+            signal: both,
+        });
+        // Each turn either calls tools (counted, so it ends) or uses up a nudge.
+        for (;;) {
+            const turn = await conversation.next();
+            aiCalls++;
+            const answer = turn.calls.find((c) => c.name === 'submit');
+            if (answer)
+                return { output: checkAgentOutput(req.task, answer.input), aiCalls, toolCalls };
+            if (turn.calls.length === 0) {
+                if (nudgedToSubmit)
+                    throw new AiError('AI_BAD_OUTPUT', 'The AI answered without calling submit.', turn.text);
+                nudgedToSubmit = true;
+                conversation.say('Give your answer by calling the submit tool.');
+                continue;
+            }
+            if (toolCalls >= MAX_TOOL_CALLS || toolBytes >= MAX_TOOL_BYTES) {
+                if (nudgedAtLimit)
+                    throw new AiError('AI_BAD_OUTPUT', `The AI kept reading the org's metadata past the limit (${limitName(toolBytes)}).`);
+                nudgedAtLimit = true;
+                // Every call of the turn needs its answer before anything else can be said.
+                conversation.answer(turn.calls.map((c) => ({ id: c.id, content: `Not run: ${limitName(toolBytes)} is reached. Call submit now with your best answer.` })));
+                continue;
+            }
+            const results = [];
+            for (const call of turn.calls) {
+                // The screen went away (Cancel, a closed tab): no more reads of the org.
+                if (both.aborted)
+                    throw both.reason;
+                toolCalls++;
+                const over = toolCalls > MAX_TOOL_CALLS || toolBytes >= MAX_TOOL_BYTES;
+                const content = over ? `Not run: ${limitName(toolBytes)} is reached. Call submit now.` : await runTool(source, call.name, call.input, MAX_TOOL_BYTES - toolBytes, state);
+                toolBytes += encoder.encode(content).length;
+                results.push({ id: call.id, content });
+            }
+            conversation.answer(results);
+        }
+    }
+    catch (e) {
+        if (timeout.signal.aborted)
+            throw new AiError('AI_TIMEOUT', `The AI did not answer within ${Math.round(timeoutMs / 1000)} seconds.`);
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}