sfbench 0.1.0

package/dist/server/ai/tools.js

@@ -0,0 +1,249 @@
+// The tools the AI calls to read the org's metadata (docs/ai-agent.md "ツール",
+// "SOQL のときのツール"): searching objects and listing an object's fields.
+// Only metadata goes back, never record values. Names are full API names, with
+// their namespace, except where SOQL may leave the org's own namespace out.
+import { findByName, stripNamespace } from "../../shared/namespace.js";
+/** The most objects one search returns. */
+const MAX_FOUND = 50;
+const MAX_PICKLIST_VALUES = 50;
+/** Objects that are rarely queried and would crowd a SOQL search (sharing, history, feeds, change events): listed last. */
+const NOISE = /(Share|History|Feed|ChangeEvent)$/;
+const encoder = new TextEncoder();
+export const METADATA_TOOLS = [
+    {
+        name: 'findObjects',
+        description: `Finds the org's objects whose API name or label contains any of the keywords (case-insensitive). Returns "ApiName Label" lines, at most ${MAX_FOUND}; custom objects (made in this org or by a package) end with "(custom)".`,
+        schema: {
+            type: 'object',
+            properties: { keywords: { type: 'array', items: { type: 'string' }, description: 'Words to look for, in English or the language of the labels.' } },
+            required: ['keywords'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'describeObject',
+        description: 'Returns one object: its child relationships ("Name -> ChildObject"), then its fields one per line: "Name type(referenceTo) relationship Name [readonly] Label [picklist values]". A large object comes with less detail, or with names only; then use findFields for the fields you need.',
+        schema: {
+            type: 'object',
+            properties: { name: { type: 'string', description: 'The API name of the object.' } },
+            required: ['name'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'findFields',
+        description: `Finds the fields and child relationships of one object whose name, relationship name or label contains any of the keywords (case-insensitive), with labels and picklist values (at most ${MAX_PICKLIST_VALUES} values a field); exact names first, at most ${MAX_FOUND} lines.`,
+        schema: {
+            type: 'object',
+            properties: {
+                object: { type: 'string', description: 'The API name of the object.' },
+                keywords: { type: 'array', items: { type: 'string' }, description: 'Field or relationship names, or words of their labels.' },
+            },
+            required: ['object', 'keywords'],
+            additionalProperties: false,
+        },
+    },
+];
+/** A name as the AI is shown it. */
+export function shown(source, name) {
+    return source.omitNamespace ? stripNamespace(name, source.omitNamespace) : name;
+}
+/** The object in the list that a name means, matched without regard to case or the org's namespace. */
+export async function findObject(source, name) {
+    return findByName(await source.objects(), name.trim(), source.omitNamespace);
+}
+export function findObjectsText(objects, keywords, source = {}) {
+    const words = keywords.map((k) => k.trim().toLowerCase()).filter(Boolean);
+    if (words.length === 0)
+        return 'Give at least one keyword.';
+    const searched = source.soql ? objects.filter((o) => o.queryable !== false) : objects;
+    const matched = searched.filter((o) => words.some((w) => o.name.toLowerCase().includes(w) || o.label.toLowerCase().includes(w)));
+    // Still found when asked for (LoginHistory), but after the objects usually meant.
+    const found = source.soql ? [...matched.filter((o) => !NOISE.test(o.name)), ...matched.filter((o) => NOISE.test(o.name))] : matched;
+    if (found.length === 0)
+        return 'No object matches.';
+    const lines = found.slice(0, MAX_FOUND).map((o) => `${shown(source, o.name)} ${o.label}${o.custom ? ' (custom)' : ''}`);
+    if (found.length > MAX_FOUND)
+        lines.push(`(${found.length - MAX_FOUND} more: use more specific keywords)`);
+    return lines.join('\n');
+}
+/** The most one tool result returns, so that one large object leaves room for the objects read after it. */
+export const MAX_READ_BYTES = 40_000;
+const bytes = (text) => encoder.encode(text).length;
+const NEAR_LIMIT = 'Not returned: the limit of what the tools return is near. Answer with what you have.';
+/** Below this much budget, findFields could not return even a few lines: the tools are near their limit. */
+const MIN_USEFUL_BYTES = 4_000;
+function fieldLine(f, name, full) {
+    const parts = [name(f.name), f.type === 'reference' && f.referenceTo?.length ? `reference(${f.referenceTo.map(name).join(',')})` : f.type];
+    if (f.relationshipName)
+        parts.push(`relationship ${name(f.relationshipName)}`);
+    if (f.updateable === false && f.createable === false)
+        parts.push('readonly');
+    if (!full)
+        return parts.join(' ');
+    parts.push(f.label);
+    const active = (f.picklistValues ?? []).filter((v) => v.active);
+    if (active.length === 0)
+        return parts.join(' ');
+    const more = active.length > MAX_PICKLIST_VALUES ? ` (+${active.length - MAX_PICKLIST_VALUES} more)` : '';
+    return `${parts.join(' ')} [${active
+        .slice(0, MAX_PICKLIST_VALUES)
+        .map((v) => v.value)
+        .join(', ')}]${more}`;
+}
+const childLine = (r, name) => `${name(r.relationshipName)} -> ${name(r.childSObject)}`;
+const childrenOf = (d) => (d.childRelationships ?? []).filter((r) => Boolean(r.relationshipName));
+/**
+ * The forms of describeObject, from the most detail to the least: each names
+ * every child relationship and field (docs/ai-agent.md "大きなオブジェクト").
+ */
+const FORMS = [
+    (d, name) => describeLines(d, name, true).join('\n'),
+    (d, name) => [`Object ${name(d.name)} (${d.label})`, '(Labels and picklist values are left out: use findFields to read the fields you need in full.)', ...describeLines(d, name, false).slice(1)].join('\n'),
+    (d, name) => [
+        `Object ${name(d.name)} (${d.label})`,
+        '(Types, labels and picklist values are left out: use findFields to read the fields and child relationships you need.)',
+        `Child relationships: ${childrenOf(d)
+            .map((r) => name(r.relationshipName))
+            .join(', ')}`,
+        `Fields: ${d.fields.map((f) => name(f.name)).join(', ')}`,
+    ].join('\n'),
+];
+function describeLines(d, name, full) {
+    const lines = [`Object ${name(d.name)} (${d.label})`];
+    const children = childrenOf(d);
+    if (children.length)
+        lines.push('Child relationships:', ...children.map((r) => childLine(r, name)));
+    lines.push('Fields:', ...d.fields.map((f) => fieldLine(f, name, full)));
+    return lines;
+}
+/** The object in full, as the first form of describeObject. */
+export function describeText(d, source = {}) {
+    return FORMS[0](d, (n) => shown(source, n));
+}
+/**
+ * A text cut to the budget, on a line, saying so: the last guard for a tool
+ * result (the tools keep within the budget themselves).
+ */
+export function cutToBudget(text, budget) {
+    if (bytes(text) <= budget)
+        return text;
+    const note = '\n(Cut here: the limit of what the tools return is reached. Answer with what you have.)';
+    const room = Math.max(0, budget - bytes(note));
+    const kept = [];
+    let used = 0;
+    for (const line of text.split('\n')) {
+        const size = bytes(line) + 1;
+        if (used + size > room)
+            break;
+        kept.push(line);
+        used += size;
+    }
+    return kept.join('\n') + note;
+}
+export const newReadState = () => ({ listed: new Set() });
+/** An object's describe, matched in the list; undefined when the org has no such object. */
+async function described(source, name) {
+    // Read with the list's spelling, so that one describe is not read again under another case.
+    const object = await findObject(source, name);
+    const d = object ? await source.describe(object.name) : undefined;
+    // Anything but a describe (a cache shared with other answers) is no object.
+    return object && d && Array.isArray(d.fields) ? { object, d } : undefined;
+}
+/**
+ * describeObject: the form with the most detail that fits `budget` and one
+ * result. Undefined when the org has no such object.
+ */
+export async function readObject(source, name, budget, state) {
+    const found = await described(source, name);
+    if (!found)
+        return undefined;
+    const shownName = shown(source, found.object.name);
+    if (state.listed.has(found.object.name))
+        return `${shownName} is already above in this conversation: use it, and findFields for what was left out.`;
+    const show = (n) => shown(source, n);
+    // The detailed forms within one result; the names, the least the AI needs, within all the budget left.
+    const rooms = [Math.min(budget, MAX_READ_BYTES), Math.min(budget, MAX_READ_BYTES), budget];
+    for (const [i, form] of FORMS.entries()) {
+        const text = form(found.d, show);
+        if (bytes(text) > rooms[i])
+            continue;
+        state.listed.add(found.object.name);
+        return text;
+    }
+    // Too many names for the budget, with enough left to find fields: the AI finds what it needs instead.
+    if (budget < MIN_USEFUL_BYTES)
+        return NEAR_LIMIT;
+    state.listed.add(found.object.name);
+    return `Object ${shownName} (${found.d.label}) has ${found.d.fields.length} fields and ${childrenOf(found.d).length} child relationships, too many to list: use findFields to find the ones you need.`;
+}
+/**
+ * findFields: the fields and child relationships whose names or labels hold a
+ * keyword, in full; exact names first, within `budget` and one result.
+ */
+export async function findFieldsText(source, objectName, keywords, budget) {
+    const found = await described(source, objectName);
+    if (!found)
+        return undefined;
+    const words = keywords.map((k) => k.trim().toLowerCase()).filter(Boolean);
+    if (words.length === 0)
+        return 'Give at least one keyword.';
+    const name = (n) => shown(source, n);
+    // Both the name as shown and the full name, so that either spelling finds it.
+    const names = (n) => [n.toLowerCase(), name(n).toLowerCase()];
+    const exact = (n) => (n ? names(n).some((x) => words.includes(x)) : false);
+    const exactField = (f) => exact(f.name) || exact(f.relationshipName);
+    const contains = (n, label = '') => [...names(n), label.toLowerCase()].some((x) => words.some((w) => x.includes(w)));
+    // A reference is also found by its relationship name (Account__r), as SOQL follows it by that name.
+    const fields = found.d.fields.filter((f) => contains(f.name, f.label) || (f.relationshipName ? contains(f.relationshipName) : false));
+    const children = childrenOf(found.d).filter((r) => contains(r.relationshipName) || contains(r.childSObject));
+    const lines = [
+        ...fields.filter(exactField).map((f) => fieldLine(f, name, true)),
+        ...children.filter((r) => exact(r.relationshipName)).map((r) => `child relationship ${childLine(r, name)}`),
+        ...fields.filter((f) => !exactField(f)).map((f) => fieldLine(f, name, true)),
+        ...children.filter((r) => !exact(r.relationshipName)).map((r) => `child relationship ${childLine(r, name)}`),
+    ];
+    if (lines.length === 0)
+        return `No field or child relationship of ${name(found.object.name)} matches.`;
+    const room = Math.min(budget, MAX_READ_BYTES);
+    const head = `Object ${name(found.object.name)}:`;
+    const more = (rest) => `(${rest} more: use more specific keywords.)`;
+    const kept = [];
+    // Room for the longest closing note it can need.
+    let used = bytes(head) + bytes(more(lines.length)) + 1;
+    for (const line of lines.slice(0, MAX_FOUND)) {
+        if (used + bytes(line) + 1 > room)
+            break;
+        kept.push(line);
+        used += bytes(line) + 1;
+    }
+    if (kept.length === 0)
+        return NEAR_LIMIT;
+    const rest = lines.length - kept.length;
+    return [head, ...kept, ...(rest ? [more(rest)] : [])].join('\n');
+}
+const noObject = (name) => `The org has no object named ${name}. Use findObjects to look for it.`;
+const isName = (v) => typeof v === 'string' && /^[A-Za-z][A-Za-z0-9_]*$/.test(v);
+/** Runs one metadata tool. A call of the wrong shape is answered with what is wrong, so that the AI can try again. */
+export async function runTool(source, name, input, budget, state) {
+    const args = (input ?? {});
+    const isWords = (v) => Array.isArray(v) && v.every((k) => typeof k === 'string');
+    if (name === 'findObjects') {
+        if (!isWords(args.keywords))
+            return 'keywords must be a list of strings.';
+        return cutToBudget(findObjectsText(await source.objects(), args.keywords, source), Math.min(budget, MAX_READ_BYTES));
+    }
+    if (name === 'describeObject') {
+        if (!isName(args.name))
+            return 'name must be an object API name.';
+        return (await readObject(source, args.name, budget, state)) ?? noObject(args.name);
+    }
+    if (name === 'findFields') {
+        if (!isName(args.object))
+            return 'object must be an object API name.';
+        if (!isWords(args.keywords))
+            return 'keywords must be a list of strings.';
+        return (await findFieldsText(source, args.object, args.keywords, budget)) ?? noObject(args.object);
+    }
+    return `There is no tool named ${name}.`;
+}

package/dist/server/browser.js

@@ -0,0 +1,26 @@
+// Opens a URL in the default browser without a shell. See docs/design.md ("コマンドライン引数").
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+function command(url) {
+    switch (process.platform) {
+        case 'darwin':
+            return ['/usr/bin/open', [url]];
+        case 'win32':
+            // Absolute path, so that an executable in the working directory is never run.
+            return [join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'rundll32.exe'), ['url.dll,FileProtocolHandler', url]];
+        default:
+            return ['xdg-open', [url]];
+    }
+}
+/** Resolves true when the browser command started, false when it could not be run. */
+export function openBrowser(url) {
+    const [file, args] = command(url);
+    return new Promise((resolve) => {
+        const child = spawn(file, args, { stdio: 'ignore', detached: true, windowsHide: true });
+        child.once('error', () => resolve(false));
+        child.once('spawn', () => {
+            child.unref();
+            resolve(true);
+        });
+    });
+}

package/dist/server/cli.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Entry point of `npx sfbench`. See docs/design.md ("コマンドライン引数").
+import { parseArgs } from 'node:util';
+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 { serve } from "./serve.js";
+import { packageVersion } from "./version.js";
+const HELP = `Usage: sfbench [options]
+       sfbench stop
+
+Opens sfbench, a local workbench for Salesforce, in your browser.
+It uses the orgs you logged in to with the Salesforce CLI (sf).
+
+Options:
+  -o, --target-org <alias>  Org to open. Defaults to the sf CLI's default org (target-org).
+  --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 never sent:
+                            check it and press Send.
+  --method <method>         The --rest request's method: GET (default), POST, PATCH, PUT or DELETE.
+  --body <json>             The --rest request's JSON body (POST, PATCH and PUT).
+  --body-file <file>        Read the --rest request's JSON body from a file.
+  --apex "<code>"           Open the Apex screen with this anonymous Apex. It is never run:
+                            check it and press Run.
+  --apex-file <file>        Read the --apex code from a file.
+  --json                    Print the result as JSON.
+  --no-open                 Do not open a browser; print the URL instead.
+  -h, --help                Show this help.
+  -v, --version             Show the version.
+
+Commands:
+  stop                      Stop the background sfbench server.
+
+Examples for AI agents:
+  npx -y sfbench -o my-org --query "SELECT Id, Name FROM Account LIMIT 10" --run
+  npx -y sfbench -o my-org --query "SELECT Id FROM Opportunity WHERE IsWon = true" --run --json
+  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
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        allowNegative: true,
+        options: {
+            'target-org': { type: 'string', short: 'o' },
+            query: { type: 'string' },
+            run: { type: 'boolean', default: false },
+            rest: { type: 'string' },
+            method: { type: 'string' },
+            body: { type: 'string' },
+            'body-file': { type: 'string' },
+            apex: { type: 'string' },
+            'apex-file': { type: 'string' },
+            json: { type: 'boolean', default: false },
+            open: { type: 'boolean', default: true },
+            dev: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+    });
+    const command = positionals[0];
+    if (values.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (values.version) {
+        process.stdout.write(`${packageVersion()}\n`);
+        return;
+    }
+    // `serve` is internal: the background server process. --dev runs it in the foreground for development.
+    if (command === 'serve' || values.dev) {
+        await serve(values.dev);
+        return;
+    }
+    if (command === 'stop') {
+        await stopSfbench();
+        return;
+    }
+    if (command !== undefined)
+        throw new UserError(`Unknown command: ${command}. See \`sfbench --help\`.`);
+    await openSfbench({
+        targetOrg: values['target-org'],
+        query: values.query,
+        run: values.run,
+        rest: restOption(values),
+        apex: apexOption(values),
+        json: values.json,
+        open: values.open,
+    });
+}
+/** The --rest request, checked. --method and --body without --rest are mistakes, not ignored. */
+function restOption(values) {
+    if (values.rest === undefined) {
+        if (values.method !== undefined || values.body !== undefined || values['body-file'] !== undefined) {
+            throw new UserError('--method, --body and --body-file go with --rest.');
+        }
+        return undefined;
+    }
+    if (values.body !== undefined && values['body-file'] !== undefined)
+        throw new UserError('Use either --body or --body-file.');
+    let body = values.body;
+    if (values['body-file'] !== undefined) {
+        try {
+            // Read here, in the user's working directory; the server gets the text.
+            // Without a byte order mark, which Windows editors may put first.
+            body = readFileSync(values['body-file'], 'utf8').replace(/^\uFEFF/, '');
+        }
+        catch (e) {
+            throw new UserError(`Could not read ${values['body-file']}: ${e.message}`);
+        }
+    }
+    try {
+        return restLaunch({ path: values.rest, method: values.method, body });
+    }
+    catch (e) {
+        throw new UserError(e.message);
+    }
+}
+/** The --apex code, checked. */
+function apexOption(values) {
+    if (values.apex !== undefined && values['apex-file'] !== undefined)
+        throw new UserError('Use either --apex or --apex-file.');
+    let code = values.apex;
+    if (values['apex-file'] !== undefined) {
+        try {
+            // Without a byte order mark, which Windows editors may put first.
+            code = readFileSync(values['apex-file'], 'utf8').replace(/^\uFEFF/, '');
+        }
+        catch (e) {
+            throw new UserError(`Could not read ${values['apex-file']}: ${e.message}`);
+        }
+    }
+    if (code === undefined)
+        return undefined;
+    if (!code.trim())
+        throw new UserError('--apex needs some code.');
+    if (code.length > MAX_APEX_CODE)
+        throw new UserError(`Anonymous Apex can be at most ${MAX_APEX_CODE} characters.`);
+    return { code };
+}
+main().catch((e) => {
+    if (e instanceof UserError || (e instanceof TypeError && e.code?.startsWith('ERR_PARSE_ARGS'))) {
+        process.stderr.write(`sfbench: ${e.message}\n`);
+    }
+    else {
+        process.stderr.write(`sfbench: ${e.stack ?? String(e)}\n`);
+    }
+    process.exitCode = 1;
+});

package/dist/server/fsutil.js

@@ -0,0 +1,17 @@
+import { randomBytes } from 'node:crypto';
+import { readFileSync, renameSync, writeFileSync } from 'node:fs';
+/** Writes a file so that readers never see a partial file: write to a temporary file, then rename. */
+export function writeFileAtomic(path, data) {
+    const tmp = `${path}.${randomBytes(6).toString('hex')}.tmp`;
+    writeFileSync(tmp, data, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/** Reads and parses a JSON file. Returns undefined if it does not exist or is not valid JSON. */
+export function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/server/http/security.js

@@ -0,0 +1,37 @@
+export const DEV_WEB_HOST = 'localhost:5173';
+/** Hosts the server answers to. Anything else is rejected (DNS rebinding). */
+export function allowedHosts(port, dev) {
+    const hosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+    if (dev)
+        hosts.push(DEV_WEB_HOST);
+    return hosts;
+}
+export function isAllowedHost(host, port, dev) {
+    return host !== undefined && allowedHosts(port, dev).includes(host.toLowerCase());
+}
+/**
+ * Admin endpoints are called by the CLI entry point with Node's fetch, which
+ * sends no Origin. Browsers always send Origin on these POSTs, so any Origin
+ * means the request came from a web page and is rejected.
+ */
+export function isAdminRequestOrigin(headers) {
+    return headers.origin === undefined;
+}
+/**
+ * Same-origin check for endpoints the web UI calls. Browsers omit Origin on
+ * same-origin GET requests, so a missing Origin is not a rejection by itself:
+ * the session token in a custom header already forces a CORS preflight for
+ * cross-origin requests, and the server never approves one.
+ */
+export function isSameOriginRequest(headers) {
+    const host = headers.host?.toLowerCase();
+    if (!host)
+        return false;
+    const origin = headers.origin;
+    if (origin !== undefined && origin.toLowerCase() !== `http://${host}`)
+        return false;
+    const site = headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin')
+        return false;
+    return true;
+}