@syntax-syllogism/sfd 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-22
+
+### Added
+
+- Agent hook that rewrites supported `sf` commands to their faster `sfd` equivalents
+
 ## [0.1.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -31,6 +31,7 @@ sfd query "SELECT Id, Name FROM Account LIMIT 5" -o my-org
 | `sfd deploy -d <path> \| -m <Type[:Name]>` | Deploy source. `--check-only`, `-l <level>`, `-t <test>`, `-w <minutes>` | `sf project deploy start` |
 | `sfd test` | Run Apex tests. `-n <class>`, `-t <Class.method>`, `-s <suite>`, `-l <level>`, `-c` (coverage), `-w <minutes>` | `sf apex run test --wait` |
 | `sfd org` | Resolved username, org id, instance URL and API version | `sf org display` |
+| `sfd hook <agent>`, `check`, `install`, `uninstall` | Agent integration: rewrite `sf` commands before an agent runs them. See [docs/agent-hooks.md](docs/agent-hooks.md) | |
 | `sfd start \| stop \| status \| reload` | Daemon lifecycle; `reload` drops cached orgs and auth state | |
 
 `-d`, `-m`, `-n`, `-t` and `-s` repeat or take comma-separated lists. Every
@@ -100,7 +101,8 @@ it down even if its protocol differs.
 
 `npm test` covers project and org resolution, output formatting, the socket
 protocol (dispatch, version restart, drain, idle, stale socket), and the CLI
-end to end against stub handlers. Injected Salesforce modules cover handler
+end to end against stub handlers, and the agent hook adapters and `sf` rewrite
+rules. Injected Salesforce modules cover handler
 paging, auth refresh, deployment and test orchestration without an org.
 A real-org check is opt-in:
 
@@ -124,3 +126,20 @@ See [SECURITY.md](SECURITY.md) for how to report vulnerabilities.
 ## License
 
 [MIT](LICENSE) © Jacob Richter
+
+## Agent integration
+
+`sfd hook` rewrites supported `sf` shell commands before a coding agent runs
+them, so they reach the warm daemon. Install an adapter for Claude Code, Codex
+CLI or Gemini CLI (user scope by default):
+
+```bash
+sfd hook install --agent claude
+sfd hook install --agent codex
+sfd hook install --agent gemini
+```
+
+Add `--project` to install into the current project instead. Preview a rewrite
+with `sfd hook check '<sf command>'`. The supported commands, adapter details,
+skip rules and the `SFD_HOOK_DISABLE=1` switch are in
+[docs/agent-hooks.md](docs/agent-hooks.md).

package/bin/sfd.mjs

@@ -6,6 +6,7 @@ import { call, isRunning, startDaemon, DaemonError, VERSION } from "../src/clien
 import { findProjectDir, resolveTargetOrg } from "../src/project.mjs";
 import { formatApex, formatDeploy, formatTests } from "../src/format.mjs";
 import { paths } from "../src/paths.mjs";
+import { UsageError } from "../src/usage-error.mjs";
 
 const USAGE = `sfd ${VERSION}: fast Salesforce CLI operations through a warm local daemon
 
@@ -21,6 +22,8 @@ Commands:
   test                  Run Apex tests. -n <class> (repeatable), -t <Class.method> (repeatable),
                         -s <suite> (repeatable), -l <test level>, -c (coverage), -w <minutes>
   org                   Show the resolved org (username, id, instance, API version)
+  hook <agent|check|install|uninstall>
+                        Integrate with Claude Code, Codex CLI or Gemini CLI
   start | stop | status | reload
                         Manage the daemon. reload drops cached orgs and auth state
 
@@ -53,8 +56,6 @@ const options = {
   wait: { type: "string", short: "w" }
 };
 
-class UsageError extends Error {}
-
 const split = list => list?.flatMap(v => v.split(",")).map(v => v.trim()).filter(Boolean);
 
 function readStdin() {
@@ -86,6 +87,10 @@ function print(value) {
 }
 
 async function run(argv) {
+  if (argv[0] === "hook") {
+    const { runHook } = await import("../src/hooks.mjs");
+    return runHook(argv.slice(1));
+  }
   const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true });
   const [command, ...rest] = positionals;
   if (values.help || !command) { print(USAGE); return 0; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/sfd",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Warm Salesforce CLI daemon: SOQL, anonymous Apex, REST, describe, deploy, and Apex tests without sf startup cost.",
   "type": "module",
   "bin": {

package/src/hooks.mjs

@@ -0,0 +1,102 @@
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, renameSync, unlinkSync, statSync, constants } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { rewrite } from "./rewrite.mjs";
+import { UsageError } from "./usage-error.mjs";
+
+const USAGE = "Usage: sfd hook claude|codex|gemini|check <command>|install|uninstall --agent <agent> [--project]";
+
+const agents = {
+  claude: { directory: ".claude", file: "settings.json", event: "PreToolUse", tool: "Bash" },
+  codex: { directory: ".codex", file: "hooks.json", event: "PreToolUse", tool: "Bash" },
+  gemini: { directory: ".gemini", file: "settings.json", event: "BeforeTool", tool: "run_shell_command" }
+};
+
+export function handle(agent, inputJson, env = process.env) {
+  try {
+    if (env.SFD_HOOK_DISABLE === "1") return "";
+    const config = agents[agent];
+    if (!config) return "";
+    const input = JSON.parse(inputJson);
+    if (input?.tool_name !== config.tool || (input.hook_event_name && input.hook_event_name !== config.event)) return "";
+    if (!input.tool_input || typeof input.tool_input.command !== "string") return "";
+    const result = rewrite(input.tool_input.command);
+    if (result.skip) return "";
+    const updatedInput = { ...input.tool_input, command: result.command };
+    if (agent === "gemini") return JSON.stringify({ hookSpecificOutput: { tool_input: updatedInput } });
+    return JSON.stringify({ hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      ...(agent === "codex" ? { permissionDecision: "allow" } : {}),
+      permissionDecisionReason: result.reason,
+      updatedInput
+    } });
+  } catch { return ""; }
+}
+
+function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+
+export function editSettings(action, agent, { project = false, cwd = process.cwd(), home = homedir() } = {}) {
+  const config = agents[agent];
+  if (!config || !["install", "uninstall"].includes(action)) throw new UsageError("Expected install|uninstall --agent claude|codex|gemini [--project]");
+  const file = join(project ? cwd : home, config.directory, config.file);
+  let original, settings = {};
+  try { original = readFileSync(file, "utf8"); settings = JSON.parse(original); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (!object(settings) || (settings.hooks !== undefined && !object(settings.hooks))) throw Error(`Invalid hooks settings in ${file}`);
+  const entries = settings.hooks?.[config.event] ?? [];
+  if (!Array.isArray(entries) || entries.some(entry => !object(entry) || !Array.isArray(entry.hooks))) throw Error(`Invalid ${config.event} settings in ${file}`);
+  const isSfd = hook => hook?.type === "command" && typeof hook.command === "string" && new RegExp(`^sfd hook ${agent}(?:\\s|$)`).test(hook.command);
+  const exists = entries.some(entry => entry.hooks.some(isSfd));
+  if ((action === "install") === exists) return { file, changed: false };
+  let updated;
+  if (action === "install") {
+    updated = [...entries, { matcher: config.tool, hooks: [{ type: "command", command: `sfd hook ${agent}` }] }];
+  } else {
+    updated = entries.flatMap(entry => {
+      const hooks = entry.hooks.filter(hook => !isSfd(hook));
+      return hooks.length === entry.hooks.length ? [entry] : hooks.length ? [{ ...entry, hooks }] : [];
+    });
+  }
+  settings.hooks ??= {};
+  settings.hooks[config.event] = updated;
+  mkdirSync(dirname(file), { recursive: true });
+  if (original !== undefined) {
+    try { copyFileSync(file, `${file}.bak`, constants.COPYFILE_EXCL); }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+  }
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify(settings, null, 2) + "\n", { flag: "wx", mode: original === undefined ? 0o600 : statSync(file).mode & 0o777 });
+    renameSync(temporary, file);
+  } finally {
+    try { unlinkSync(temporary); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return { file, changed: true };
+}
+
+export function runHook(argv) {
+  const [action, ...args] = argv;
+  if (action === "--help" || action === "-h") {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  if (Object.hasOwn(agents, action)) {
+    // Adapter errors must never change whether the original tool call can run.
+    try { process.stdout.write(handle(action, readFileSync(0, "utf8"))); } catch { /* no opinion */ }
+    return 0;
+  }
+  if (action === "check") {
+    const result = process.env.SFD_HOOK_DISABLE === "1" ? { skip: "SFD_HOOK_DISABLE=1" } : rewrite(args.join(" "));
+    process.stdout.write(result.skip ? `skip: ${result.skip}\n` : `→ ${result.command}\n`);
+    return result.skip ? 1 : 0;
+  }
+  if (["install", "uninstall"].includes(action)) {
+    const { values } = parseArgs({ args, options: { agent: { type: "string" }, project: { type: "boolean" } } });
+    const result = editSettings(action, values.agent, { project: values.project });
+    process.stdout.write(`${result.changed ? "Updated" : "Unchanged"} ${result.file}\n`);
+    if (action === "install" && values.agent === "codex") process.stdout.write("Review and trust the hook with /hooks in Codex before it can run.\n");
+    return 0;
+  }
+  throw new UsageError(USAGE);
+}

package/src/rewrite.mjs

@@ -0,0 +1,173 @@
+// This is deliberately a literal-shell subset. Unknown shell syntax stays with sf.
+const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
+const skip = reason => ({ skip: reason });
+
+function lex(source) {
+  const tokens = [];
+  let i = 0;
+  while (i < source.length) {
+    if (/[ \t\r]/.test(source[i])) { i++; continue; }
+    const start = i;
+    const op = /^(?:2>&1|2>\/dev\/null|&&|\|\||>>|<<|[|;&<>\n])/.exec(source.slice(i));
+    if (op) {
+      tokens.push({ op: op[0], start, end: i += op[0].length });
+      continue;
+    }
+    let value = "", mode = "";
+    while (i < source.length) {
+      const c = source[i];
+      if (!mode && /[ \t\r\n|;&<>]/.test(c)) break;
+      if (c === "'" && mode !== '"') { mode = mode === "'" ? "" : "'"; i++; continue; }
+      if (c === '"' && mode !== "'") { mode = mode === '"' ? "" : '"'; i++; continue; }
+      if (c === "\\" && mode !== "'") {
+        if (++i === source.length) throw Error("incomplete escape");
+        if (mode === '"' && !/[\$`"\\]/.test(source[i])) value += "\\";
+        value += source[i++];
+        continue;
+      }
+      if (mode !== "'" && /[$`]/.test(c)) throw Error("shell expansion or command substitution");
+      if (!mode && /[(){}*?\[\]~#]/.test(c)) throw Error("unsupported shell syntax");
+      value += c; i++;
+    }
+    if (mode) throw Error("unclosed quote");
+    tokens.push({ value, start, end: i });
+  }
+  return tokens;
+}
+
+// [sf names, sfd flag (empty means drop), takes value, repeatable]
+const org = ["o target-org", "-o", true];
+const json = ["json", "", false];
+const tooling = ["t use-tooling-api", "--tooling", false];
+const format = ["r result-format", "", true];
+const wait = ["w wait", "-w", true];
+const level = ["l test-level", "-l", true];
+const tests = ["t tests", "-t", true, true];
+const mappings = [
+  { sf: "data query", sfd: "query", flags: [org, json, tooling, ["q query", "", true], ["all-rows", "--all", false], format], required: "q" },
+  { sf: "apex run test", sfd: "test", flags: [org, json, wait, level, tests, format, ["n class-names", "-n", true, true], ["s suite-names", "-s", true, true], ["c code-coverage", "-c", false], ["y synchronous", "", false]] },
+  { sf: "apex run", sfd: "apex", flags: [org, json, ["f file", "-f", true]] },
+  { sf: "project deploy start", sfd: "deploy", flags: [org, json, wait, level, tests, ["d source-dir", "-d", true, true], ["m metadata", "-m", true, true], ["dry-run", "--check-only", false]] },
+  { sf: "sobject describe", sfd: "describe", flags: [org, json, tooling, ["s sobject", "", true]], required: "s" },
+  { sf: "api request rest", sfd: "rest", flags: [org, ["X method", "-X", true], ["b body", "--body", true]], positional: true },
+  { sf: "org display", sfd: "org", flags: [org, json] }
+];
+
+function mapArgs(argv) {
+  const mapping = mappings.find(m => m.sf.split(" ").every((v, i) => argv[i] === v));
+  if (!mapping) return skip("unsupported sf command");
+  const args = argv.slice(mapping.sf.split(" ").length);
+  const seen = new Map(), output = [], positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("-")) { positionals.push(arg); continue; }
+    const match = /^(?:--([^=]+)|-([A-Za-z]))(?:=(.*))?$/.exec(arg);
+    const name = match?.[1] ?? match?.[2];
+    const spec = mapping.flags.find(f => f[0].split(" ").includes(name));
+    if (!spec) return skip(`unsupported flag ${arg.split("=")[0]}`);
+    const [names, target, takesValue, multiple] = spec;
+    const key = names.split(" ")[0];
+    if (seen.has(key) && !multiple) return skip(`duplicate flag ${arg.split("=")[0]}`);
+    let values = [];
+    if (takesValue) {
+      const value = match[3] ?? args[++i];
+      if (value === undefined || value === "") return skip(`missing value for ${arg}`);
+      if (value.startsWith("-")) return skip(`unsupported value for ${arg}`);
+      values.push(value);
+      if (multiple && match[3] === undefined) {
+        while (args[i + 1] !== undefined && !args[i + 1].startsWith("-")) values.push(args[++i]);
+      }
+    } else if (match[3] !== undefined) return skip(`unsupported boolean value ${arg}`);
+    seen.set(key, values);
+    if (key === "r" && !["human", "json"].includes(values[0])) return skip(`unsupported result format ${values[0]}`);
+    if (key === "w" && (!Number.isFinite(Number(values[0])) || Number(values[0]) <= 0)) return skip("wait must be positive");
+    if (target) {
+      if (takesValue) for (const v of values) output.push(target, quote(v));
+      else output.push(target);
+    }
+  }
+  if (mapping.required && !seen.has(mapping.required)) return skip(`missing required ${mapping.required} flag`);
+  if (mapping.sfd === "deploy" && !seen.has("d") && !seen.has("m")) return skip("deploy needs source-dir or metadata");
+  if (mapping.sfd === "test" && !seen.has("w") && !seen.has("y")) return skip("asynchronous tests need --wait or --synchronous");
+  if (mapping.sfd === "rest") {
+    const method = seen.get("X")?.[0] ?? "GET";
+    if (!["GET", "POST", "PUT", "PATCH", "HEAD", "DELETE", "OPTIONS", "TRACE"].includes(method)) return skip("unsupported REST method");
+    // sf ignores a body with GET; sfd infers POST from a body instead.
+    if (seen.has("b") && method === "GET") return skip("REST body with implicit or explicit GET is unsupported");
+  }
+  if (mapping.positional ? positionals.length !== 1 : positionals.length !== 0) return skip("unsupported positional arguments");
+  const positional = mapping.required ? seen.get(mapping.required) : positionals;
+  // Protect sfd's own option parser from values that could be interpreted as options.
+  if (positional.some(v => v.startsWith("-"))) return skip("unsupported positional value");
+  return { command: ["sfd", mapping.sfd, ...positional.map(quote), ...output].join(" "), apex: mapping.sfd === "apex" };
+}
+
+export function rewrite(command) {
+  if (typeof command !== "string" || !command.trim()) return skip("empty command");
+  try {
+    return rewriteShell(command);
+  } catch (error) { return skip(error.message); }
+}
+
+function rewriteShell(command) {
+  // Only remove continuations outside single quotes; the lexer does the rest.
+  let source = "", single = false, double = false;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (c === "\n" && !single && !double) { source += command.slice(i); break; }
+    if (c === "\\" && !single) {
+      if (command[i + 1] === "\n") { i++; continue; }
+      source += c + (command[++i] ?? ""); continue;
+    }
+    if (c === "'" && !double) single = !single;
+    if (c === '"' && !single) double = !double;
+    source += c;
+  }
+  source = source.trimStart();
+  // Heredoc contents are opaque: preserve them byte for byte and require one literal delimiter.
+  const newline = source.indexOf("\n");
+  let body = "";
+  if (newline !== -1) { body = source.slice(newline); source = source.slice(0, newline); }
+  const tokens = lex(source);
+  let stderr = "";
+  while (["2>&1", "2>/dev/null"].includes(tokens.at(-1)?.op)) {
+    stderr = ` ${tokens.pop().op}${stderr}`;
+  }
+  let heredoc = "";
+  const hd = tokens.findIndex(t => t.op === "<<");
+  if (hd !== -1) {
+    const delimiter = tokens[hd + 1];
+    if (!delimiter || delimiter.op || hd + 2 !== tokens.length || !/^[A-Za-z_][\w]*$/.test(delimiter.value)) return skip("unsupported heredoc");
+    const contents = body.slice(1);
+    const lines = (contents.endsWith("\n") ? contents.slice(0, -1) : contents).split("\n");
+    if (lines.at(-1) !== delimiter.value || lines.slice(0, -1).includes(delimiter.value)) return skip("unsupported heredoc terminator");
+    heredoc = source.slice(tokens[hd].start, delimiter.end) + body;
+    tokens.splice(hd);
+  } else if (body.trim()) return skip("unsupported multiline command");
+  while (["2>&1", "2>/dev/null"].includes(tokens.at(-1)?.op)) {
+    stderr = ` ${tokens.pop().op}${stderr}`;
+  }
+  if (tokens.some(t => t.op && !["&&", "|"].includes(t.op))) return skip("output redirection or unsupported shell chain");
+  const chains = tokens.flatMap((t, i) => t.op === "&&" ? [i] : []);
+  let start = 0;
+  if (chains.length) {
+    if (chains.length !== 1 || chains[0] !== 2 || tokens[0].value !== "cd" || !tokens[1].value || tokens[1].value.startsWith("-")) return skip("unsupported && chain");
+    start = 3;
+  }
+  const pipes = tokens.flatMap((t, i) => t.op === "|" ? [i] : []);
+  if (pipes.length) {
+    if (pipes.some(i => i <= start || i === tokens.length - 1 || tokens[i - 1].op)) return skip("unsupported pipeline");
+    // Never rewrite sf whose stdout is consumed, even if a later segment is also sf.
+    for (const i of [start, ...pipes.map(p => p + 1)].slice(0, -1)) {
+      if (tokens[i]?.value === "sf" || tokens[i]?.value?.startsWith("SF_TARGET_ORG=")) return skip("sf output is piped");
+    }
+    start = pipes.at(-1) + 1;
+  }
+  if (tokens[start]?.value?.startsWith("SF_TARGET_ORG=")) start++;
+  if (tokens[start]?.value !== "sf") return skip("not a plain sf invocation (paths, env prefixes and sfdx are unsupported)");
+  if (tokens.slice(start).some(t => t.op)) return skip("unsupported shell operator");
+  const mapped = mapArgs(tokens.slice(start + 1).map(t => t.value));
+  if (mapped.skip) return mapped;
+  if ((pipes.length || heredoc) && !mapped.apex) return skip("stdin is supported only for apex run");
+  return { command: source.slice(0, tokens[start].start) + mapped.command + stderr + (heredoc ? ` ${heredoc}` : ""), reason: "sfd: warm daemon, ~0.3 s" };
+}

package/src/usage-error.mjs

@@ -0,0 +1 @@
+export class UsageError extends Error {}