sfbench 0.1.0 → 0.1.1

package/README.ja.md

@@ -51,7 +51,7 @@ lwc-soql-builder は、Salesforce が OAuth のユーザーエージェントフ
 
 ## 必要なもの
 
-- Node.js 22.21.0 以上の 22 系、または 24.5.0 以上
+- Node.js 22.21.0 以上の 22 系、または 24.5.0 以上（プロジェクトで古い Node.js を指定していても、`npx -y -p node@24 -p sfbench -- sfbench` で動かせます）
 - [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli)（`sf`）と、使う組織へのログイン
 
 macOS、Linux、Windows で動きます。
@@ -108,6 +108,14 @@ Claude Code の中では `/plugin install sfbench --marketplace atskimura/sfbenc
 日本語版は [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 のシェルのサンドボックスを有効にしている場合（`/sandbox`）、sfbench はサンドボックスの中では起動できません。
+`~/.npm/` と `~/.sfbench/` に書き込み、ローカルのサーバーを動かし続けるからです。
+`~/.claude/settings.json` に次を足し、sfbench だけをサンドボックスの外で動かしてください。
+
+```json
+"sandbox": { "excludedCommands": ["npx -y sfbench *", "npx -y sfbench", "npx -y -p node@24 -p sfbench -- sfbench *", "npx -y -p node@24 -p sfbench -- sfbench"] }
+```
+
 スキルを入れた Claude Code に「sfbench で成約済みの商談を一覧して」と頼むと、エージェントは SOQL を組み立てて次のように起動します。
 
 ```

package/README.md

@@ -51,7 +51,7 @@ lwc-soql-builder can no longer log in, because Salesforce has blocked the OAuth
 
 ## Requirements
 
-- Node.js 22.21.0 or later in the 22 line, or 24.5.0 or later
+- Node.js 22.21.0 or later in the 22 line, or 24.5.0 or later (if a project pins an older Node.js, `npx -y -p node@24 -p sfbench -- sfbench` still runs it)
 - The [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli) (`sf`), logged in to the orgs you use
 
 sfbench runs on macOS, Linux and Windows.
@@ -107,6 +107,13 @@ 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).
 
+If you turned on Claude Code's command sandbox (`/sandbox`), sfbench cannot start inside it: it writes `~/.npm/` and `~/.sfbench/` and keeps a local server running.
+Let sfbench alone run outside the sandbox by adding this to `~/.claude/settings.json`:
+
+```json
+"sandbox": { "excludedCommands": ["npx -y sfbench *", "npx -y sfbench", "npx -y -p node@24 -p sfbench -- sfbench *", "npx -y -p node@24 -p sfbench -- sfbench"] }
+```
+
 With the skill, ask Claude Code to "list the won opportunities in sfbench", and it writes the SOQL and starts sfbench like this:
 
 ```

package/dist/server/cli.js

@@ -5,6 +5,7 @@ import { readFileSync } from 'node:fs';
 import { openSfbench, stopSfbench, UserError } from "./launcher.js";
 import { restLaunch } from "./rest.js";
 import { MAX_APEX_CODE } from "../shared/api.js";
+import { unsupportedNode } from "./nodeVersion.js";
 import { serve } from "./serve.js";
 import { packageVersion } from "./version.js";
 const HELP = `Usage: sfbench [options]
@@ -40,6 +41,13 @@ Examples for AI agents:
   npx -y sfbench -o my-org --apex-file fix-data.apex
 `;
 async function main() {
+    // First, before the arguments: an older Node.js may not parse them (--no-open).
+    // Help, the version and stop start no server, so they work on any.
+    const args = process.argv.slice(2);
+    const startsNoServer = args[0] === 'stop' || args.some((a) => ['-h', '--help', '-v', '--version'].includes(a));
+    const tooOld = startsNoServer ? undefined : unsupportedNode();
+    if (tooOld)
+        throw new UserError(tooOld);
     const { values, positionals } = parseArgs({
         allowPositionals: true,
         allowNegative: true,

package/dist/server/launcher.js

@@ -1,6 +1,8 @@
 // The CLI entry point's work: find or start the background server, then open
 // a new browser tab. See docs/design.md ("起動").
 import { spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { openBrowser } from "./browser.js";
 import { ensureDirs, resolvePaths } from "./paths.js";
@@ -57,19 +59,61 @@ async function stopServer(info) {
     }
     return false;
 }
+/**
+ * Opens a file for the server's stderr, one per start, so that a server still
+ * running from before keeps its own. The server removes it once it listens
+ * (serve.ts): it is kept only to tell why a start failed. Undefined when it
+ * cannot be opened; the server then starts with its stderr ignored.
+ */
+function openStderrFile(paths) {
+    const file = join(paths.tmpDir, `server-stderr-${Date.now()}-${process.pid}.log`);
+    try {
+        return { file, fd: openSync(file, 'w', 0o600) };
+    }
+    catch {
+        return undefined;
+    }
+}
 function startServer(paths) {
     // cli.js next to this file when installed; cli.ts when run from the sources.
     const cli = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './cli.ts' : './cli.js', import.meta.url));
-    const child = spawn(process.execPath, ['--use-env-proxy', cli, 'serve'], {
-        cwd: paths.tmpDir,
-        detached: true,
-        stdio: 'ignore',
-        windowsHide: true,
-    });
-    child.unref();
-    if (child.pid === undefined)
-        throw new UserError('Could not start the sfbench server.');
-    return child.pid;
+    // Node.js refusing to start the server (an unknown option, a missing module)
+    // says so on stderr, before the server can log anything.
+    const stderr = openStderrFile(paths);
+    let ended = false;
+    try {
+        const child = spawn(process.execPath, ['--use-env-proxy', cli, 'serve'], {
+            cwd: paths.tmpDir,
+            detached: true,
+            stdio: ['ignore', 'ignore', stderr ? stderr.fd : 'ignore'],
+            env: { ...process.env, ...(stderr ? { SFBENCH_STDERR_FILE: stderr.file } : {}) },
+            windowsHide: true,
+        });
+        child.on('exit', () => (ended = true));
+        child.on('error', () => (ended = true));
+        child.unref();
+        if (child.pid === undefined)
+            throw new UserError('Could not start the sfbench server.');
+        return {
+            pid: child.pid,
+            ended: () => ended,
+            stderr: () => {
+                if (!stderr)
+                    return '';
+                try {
+                    return readFileSync(stderr.file, 'utf8').trim().slice(0, 2000);
+                }
+                catch {
+                    return '';
+                }
+            },
+            stderrFile: stderr?.file,
+        };
+    }
+    finally {
+        if (stderr)
+            closeSync(stderr.fd);
+    }
 }
 /** Returns a running server of this version or newer, starting one if needed. Call with server.lock held. */
 async function ensureServer(paths) {
@@ -87,15 +131,18 @@ async function ensureServer(paths) {
             }
         }
     }
-    const pid = startServer(paths);
+    const server = startServer(paths);
     const deadline = Date.now() + START_TIMEOUT_MS;
-    while (Date.now() < deadline) {
+    while (Date.now() < deadline && !server.ended()) {
         await sleep(200);
         const info = readServerInfo(paths.serverJson);
-        if (info?.pid === pid && (await health(info)) !== undefined)
+        if (info?.pid === server.pid && (await health(info)) !== undefined)
             return info;
     }
-    throw new UserError(`The sfbench server did not start. See ${paths.serverLog}.`);
+    const said = server.stderr();
+    // The server removes its stderr file once it listens: named only while it is there.
+    const files = [paths.serverLog, ...(server.stderrFile && existsSync(server.stderrFile) ? [server.stderrFile] : [])].join(' and ');
+    throw new UserError(`The sfbench server did not start${said ? `:\n${said}` : '.'}\nSee ${files}.`);
 }
 async function resolveOrg(options) {
     if (options.targetOrg)

package/dist/server/nodeVersion.js

@@ -0,0 +1,27 @@
+// Whether this Node.js can run the sfbench server, which is started with
+// --use-env-proxy (docs/design.md "プロキシ"). Node.js has it from 22.21.0 and
+// 24.5.0 (package.json "engines"); an older one refuses the option and the
+// server dies at once. The option itself is checked, not the version.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { packageRoot } from "./paths.js";
+/** The versions package.json "engines" asks for, as the message names them. */
+function engines() {
+    try {
+        return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).engines?.node ?? 'a newer one';
+    }
+    catch {
+        return 'a newer one';
+    }
+}
+/** Why this Node.js cannot run sfbench, with what to do; undefined when it can. */
+export function unsupportedNode(hasEnvProxy = process.allowedNodeEnvironmentFlags.has('--use-env-proxy'), version = process.versions.node, execPath = process.execPath, wanted = engines()) {
+    if (hasEnvProxy)
+        return undefined;
+    return [
+        `sfbench needs Node.js ${wanted}, but this is Node.js ${version} (${execPath}).`,
+        'A version manager (asdf, nvm, mise and the like) may pick an older Node.js in this folder.',
+        'To run sfbench with Node.js 24 from npm anyway:',
+        '  npx -y -p node@24 -p sfbench -- sfbench <options>',
+    ].join('\n');
+}

package/dist/server/serve.js

@@ -2,7 +2,7 @@
 // the background; `npm run dev:server` runs it in the foreground.
 import { randomBytes } from 'node:crypto';
 import { readdirSync, rmSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { readJson, writeFileAtomic } from "./fsutil.js";
 import { App } from "./http/server.js";
 import { initLog, log } from "./log.js";
@@ -52,9 +52,35 @@ function cleanTmp(dir) {
     const now = Date.now();
     for (const name of readdirSync(dir)) {
         const file = join(dir, name);
-        const mtime = statSync(file, { throwIfNoEntry: false })?.mtimeMs;
-        if (mtime !== undefined && now - mtime > TMP_MAX_AGE_MS)
-            rmSync(file, { recursive: true, force: true });
+        try {
+            const mtime = statSync(file, { throwIfNoEntry: false })?.mtimeMs;
+            if (mtime !== undefined && now - mtime > TMP_MAX_AGE_MS)
+                rmSync(file, { recursive: true, force: true });
+        }
+        catch {
+            // In use (Windows refuses to remove a file a running server keeps open): left for the next time.
+        }
+    }
+}
+/** Whether a path is one of the files the CLI keeps a server's stderr in: only such a file is removed. */
+export function isStderrFile(file, tmpDir) {
+    return dirname(file) === tmpDir && /^server-stderr-[\w-]+\.log$/.test(basename(file));
+}
+/**
+ * Removes the file the CLI kept this server's stderr in, once it listens: it
+ * was only to tell why a start failed, and must not keep growing while the
+ * server runs (launcher.ts). Only a file of that name in tmp/ is removed.
+ * Windows may refuse to remove an open file; it is then cleared with tmp/.
+ */
+function removeStderrFile(paths) {
+    const file = process.env.SFBENCH_STDERR_FILE;
+    if (!file || !isStderrFile(file, paths.tmpDir))
+        return;
+    try {
+        rmSync(file, { force: true });
+    }
+    catch {
+        // Kept until tmp/ is cleaned.
     }
 }
 export async function serve(dev) {
@@ -100,6 +126,7 @@ export async function serve(dev) {
             // never sees a server.json for a server that is not ready.
             writeServerInfo(paths.serverJson, { port, adminToken, pid: process.pid, version });
             log.info(`sfbench ${version} listening on 127.0.0.1:${port}${dev ? ' (dev)' : ''}`);
+            removeStderrFile(paths);
             break;
         }
     }