@syntax-syllogism/sfd 0.0.0-stage → 0.2.0

package/src/format.mjs

@@ -0,0 +1,138 @@
+// Compact, token-friendly renderings of Salesforce results.
+
+const asArray = x => (x === undefined || x === null ? [] : Array.isArray(x) ? x : [x]);
+
+export function stripAttributes(value) {
+  if (Array.isArray(value)) return value.map(stripAttributes);
+  if (value === null || typeof value !== "object") return value;
+  const out = {};
+  for (const [key, inner] of Object.entries(value)) {
+    if (key !== "attributes") out[key] = stripAttributes(inner);
+  }
+  return out;
+}
+
+export function compactQuery(result) {
+  return { totalSize: result.totalSize, done: result.done, ...(result.nextRecordsUrl ? { nextRecordsUrl: result.nextRecordsUrl } : {}), records: stripAttributes(result.records ?? []) };
+}
+
+export function compactDescribe(d) {
+  return {
+    name: d.name, label: d.label, keyPrefix: d.keyPrefix, custom: d.custom,
+    createable: d.createable, updateable: d.updateable, deletable: d.deletable,
+    fields: d.fields.map(f => {
+      const field = { name: f.name, type: f.type, label: f.label };
+      if (f.length) field.length = f.length;
+      if (f.referenceTo?.length) field.referenceTo = f.referenceTo;
+      if (f.picklistValues?.length) field.picklistValues = f.picklistValues.filter(p => p.active).map(p => p.value);
+      if (!f.nillable && f.createable && !f.defaultedOnCreate) field.required = true;
+      if (!f.updateable) field.readOnly = true;
+      if (f.calculated) field.formula = true;
+      return field;
+    }),
+    childRelationships: d.childRelationships.filter(c => c.relationshipName).map(c => `${c.relationshipName} (${c.childSObject}.${c.field})`)
+  };
+}
+
+const loc = d => (d.lineNumber ? ` [${d.lineNumber}:${d.columnNumber ?? ""}]` : "");
+
+export function formatApex(result, { fullLog = false } = {}) {
+  const lines = [];
+  if (!result.compiled) {
+    lines.push("COMPILE ERROR");
+    for (const d of asArray(result.diagnostic)) lines.push(`  ✖ ${d.compileProblem ?? d.exceptionMessage}${loc(d)}`);
+    return lines.join("\n");
+  }
+  lines.push(result.success ? "OK" : "EXCEPTION");
+  if (!result.success) {
+    for (const d of asArray(result.diagnostic)) {
+      lines.push(`  ✖ ${d.exceptionMessage}`);
+      if (d.exceptionStackTrace) lines.push(`    ${d.exceptionStackTrace}`);
+    }
+  }
+  const log = result.logs ?? "";
+  if (fullLog) {
+    lines.push(log);
+  } else {
+    // Keep only USER_DEBUG and fatal lines; the rest of a debug log is noise for agents.
+    for (const line of log.split("\n")) {
+      const m = line.match(/\|USER_DEBUG\|\[(\d+)\]\|\w+\|(.*)$/);
+      if (m) lines.push(`[${m[1]}] ${m[2]}`);
+      else if (/\|FATAL_ERROR\|/.test(line)) lines.push(line.replace(/^.*\|FATAL_ERROR\|/, "FATAL: "));
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatDeploy(summary, org) {
+  const action = summary.checkOnly ? "Validated" : "Deployed";
+  const tests = summary.numberTestsTotal > 0
+    ? `, tests ${summary.numberTestsCompleted}/${summary.numberTestsTotal}${summary.numberTestErrors ? ` (${summary.numberTestErrors} failed)` : ""}`
+    : "";
+  const head = summary.success
+    ? `${action} ${summary.numberComponentsDeployed}/${summary.numberComponentsTotal} components${tests} to ${org} (${summary.id})`
+    : `FAILED (${summary.status}) ${org} (${summary.id})`;
+  const lines = [head];
+  for (const c of summary.componentFailures) lines.push(`  ✖ ${c.type} ${c.fullName}: ${c.problem}${loc(c)}`);
+  for (const t of summary.testFailures) lines.push(`  ✖ test ${t.name}.${t.methodName}: ${t.message}`);
+  for (const w of summary.coverageWarnings ?? []) lines.push(`  ✖ coverage${w.name ? ` ${w.name}` : ""}: ${w.message}`);
+  if (summary.errorMessage && !summary.componentFailures.length) lines.push(`  ${summary.errorMessage}`);
+  return lines.join("\n");
+}
+
+// Reduce an SDR DeployResult response to the fields formatDeploy and --json callers need.
+export function summarizeDeploy(response) {
+  const details = response.details ?? {};
+  return {
+    id: response.id,
+    status: response.status,
+    success: response.success,
+    checkOnly: response.checkOnly,
+    numberComponentsDeployed: response.numberComponentsDeployed,
+    numberComponentsTotal: response.numberComponentsTotal,
+    numberComponentErrors: response.numberComponentErrors,
+    numberTestsCompleted: response.numberTestsCompleted,
+    numberTestsTotal: response.numberTestsTotal,
+    numberTestErrors: response.numberTestErrors,
+    errorMessage: response.errorMessage,
+    componentFailures: asArray(details.componentFailures).map(c => ({
+      type: c.componentType, fullName: c.fullName, problem: c.problem, lineNumber: c.lineNumber, columnNumber: c.columnNumber
+    })),
+    testFailures: asArray(details.runTestResult?.failures).map(t => ({
+      name: t.name, methodName: t.methodName, message: t.message, stackTrace: t.stackTrace
+    })),
+    coverageWarnings: asArray(details.runTestResult?.codeCoverageWarnings).map(w => ({ name: w.name, message: w.message }))
+  };
+}
+
+export function summarizeTests(result) {
+  const s = result.summary;
+  return {
+    outcome: s.outcome, testRunId: s.testRunId, testsRan: s.testsRan, passing: s.passing, failing: s.failing,
+    skipped: s.skipped, testExecutionTimeInMs: s.testExecutionTimeInMs,
+    testRunCoverage: s.testRunCoverage, orgWideCoverage: s.orgWideCoverage,
+    failures: asArray(result.tests).filter(t => t.outcome !== "Pass" && t.outcome !== "Skip").map(t => ({
+      name: t.fullName ?? `${t.apexClass?.name}.${t.methodName}`, outcome: t.outcome, message: t.message, stackTrace: t.stackTrace
+    })),
+    setupFailures: asArray(result.setup).filter(s => s.message).map(s => ({ name: s.fullName, message: s.message, stackTrace: s.stackTrace })),
+    coverage: result.codecoverage
+      ? result.codecoverage.map(c => ({ name: c.name, percentage: c.percentage, uncoveredLines: c.uncoveredLines }))
+      : undefined
+  };
+}
+
+export function formatTests(summary, org) {
+  const parts = [`${summary.testsRan} ran`, `${summary.passing} passed`, `${summary.failing} failed`];
+  if (summary.skipped) parts.push(`${summary.skipped} skipped`);
+  const lines = [`Tests ${summary.outcome} on ${org}: ${parts.join(", ")} in ${summary.testExecutionTimeInMs} ms (${summary.testRunId})`];
+  if (summary.testRunCoverage) lines.push(`Coverage: run ${summary.testRunCoverage}, org-wide ${summary.orgWideCoverage}`);
+  for (const s of summary.setupFailures) lines.push(`  ✖ setup ${s.name}: ${s.message}`);
+  for (const f of summary.failures) {
+    lines.push(`  ✖ ${f.name}: ${f.message}`);
+    if (f.stackTrace) lines.push(`    ${f.stackTrace.replace(/\n/g, "\n    ")}`);
+  }
+  for (const c of summary.coverage ?? []) {
+    lines.push(`  ${c.percentage.padStart(4)} ${c.name}${c.uncoveredLines.length ? ` uncovered: ${c.uncoveredLines.join(",")}` : ""}`);
+  }
+  return lines.join("\n");
+}

package/src/handlers.mjs

@@ -0,0 +1,149 @@
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { sfRequire } from "./sf-root.mjs";
+import { compactDescribe, compactQuery, summarizeDeploy, summarizeTests } from "./format.mjs";
+
+const SESSION_ERRORS = new Set(["INVALID_SESSION_ID", "INVALID_AUTH_HEADER"]);
+
+function authStamp(home) {
+  // A login, logout or alias change touches ~/.sfdx or alias.json; reload org state when it does.
+  const stamp = path => { try { return statSync(path).mtimeMs; } catch { return 0; } };
+  return `${stamp(join(home, ".sfdx"))}:${stamp(join(home, ".sfdx", "alias.json"))}`;
+}
+
+// One queue for operations that touch the local project (deploy and source tracking):
+// SDR and source-tracking keep process-wide state, so they must not interleave.
+function serial() {
+  let tail = Promise.resolve();
+  return fn => {
+    const run = tail.then(fn, fn);
+    tail = run.catch(() => {});
+    return run;
+  };
+}
+
+export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRoot) } = {}) {
+  const req = load;
+  const core = req("@salesforce/core");
+  const { Duration } = req("@salesforce/kit");
+  const lazy = name => { let mod; return () => (mod ??= req(name)); };
+  const sdr = lazy("@salesforce/source-deploy-retrieve");
+  const apex = lazy("@salesforce/apex-node");
+  const tracking = lazy("@salesforce/source-tracking");
+  const projectQueue = serial();
+
+  const orgs = new Map();
+  let stamp = authStamp(home);
+
+  async function getOrg(alias) {
+    const now = authStamp(home);
+    if (now !== stamp) {
+      stamp = now;
+      orgs.clear();
+      await core.StateAggregator.clearInstanceAsync();
+    }
+    if (!orgs.has(alias)) {
+      const pending = core.Org.create({ aliasOrUsername: alias });
+      orgs.set(alias, pending);
+      pending.catch(() => orgs.delete(alias));
+    }
+    return orgs.get(alias);
+  }
+
+  // Run fn with a cached connection; on an expired or revoked session, rebuild it once.
+  async function withConn(alias, fn) {
+    try {
+      const org = await getOrg(alias);
+      return await fn(org.getConnection(), org);
+    } catch (e) {
+      if (!SESSION_ERRORS.has(e.errorCode ?? e.name)) throw e;
+      orgs.delete(alias);
+      const org = await getOrg(alias);
+      return fn(org.getConnection(), org);
+    }
+  }
+
+  return {
+    ping: async () => ({ pong: true }),
+
+    status: async () => ({
+      pid: process.pid,
+      uptimeSeconds: Math.round(process.uptime()),
+      orgs: [...orgs.keys()]
+    }),
+
+    reload: async () => {
+      orgs.clear();
+      await core.StateAggregator.clearInstanceAsync();
+      return { reloaded: true };
+    },
+
+    org: ({ org }) => withConn(org, (conn, o) => ({
+      alias: org, username: o.getUsername(), orgId: o.getOrgId(), instanceUrl: conn.instanceUrl, apiVersion: conn.getApiVersion()
+    })),
+
+    query: ({ org, q, tooling, all, raw }) => withConn(org, async conn => {
+      const api = tooling ? conn.tooling : conn;
+      const result = await api.query(q, { scanAll: Boolean(all) });
+      while (!result.done) {
+        if (!result.nextRecordsUrl) throw new Error("Incomplete query result: missing nextRecordsUrl.");
+        const page = await api.queryMore(result.nextRecordsUrl);
+        result.records.push(...page.records);
+        result.done = page.done;
+        result.nextRecordsUrl = page.nextRecordsUrl;
+      }
+      return raw ? result : compactQuery(result);
+    }),
+
+    apex: ({ org, body }) => withConn(org, conn => new (apex().ExecuteService)(conn).executeAnonymous({ apexCode: body })),
+
+    rest: ({ org, method, url, body, headers }) => withConn(org, conn => conn.request({
+      method, url, body: body === undefined || typeof body === "string" ? body : JSON.stringify(body),
+      headers: { "content-type": "application/json", ...headers }
+    })),
+
+    describe: ({ org, sobject, tooling, raw }) => withConn(org, async conn => {
+      const d = await (tooling ? conn.tooling : conn).describe(sobject);
+      return raw ? d : compactDescribe(d);
+    }),
+
+    deploy: ({ org, projectDir, sourcePaths, metadata, checkOnly, testLevel, tests, waitMinutes = 33 }) =>
+      projectQueue(() => withConn(org, async (conn, o) => {
+        const { ComponentSetBuilder } = sdr();
+        core.SfProject.clearInstances();
+        const project = await core.SfProject.resolve(projectDir);
+        const packageDirs = project.getUniquePackageDirectories().map(d => d.fullPath);
+        const cs = await ComponentSetBuilder.build({
+          projectDir,
+          sourceapiversion: project.getSfProjectJson().get("sourceApiVersion"),
+          sourcepath: sourcePaths?.length ? sourcePaths : undefined,
+          metadata: metadata?.length ? { metadataEntries: metadata, directoryPaths: packageDirs } : undefined
+        });
+        if (cs.size === 0) throw new Error("Nothing to deploy: no source components matched.");
+        // The Metadata API serializes undefined as the string "undefined", so only set what was asked.
+        const apiOptions = { checkOnly: Boolean(checkOnly), rollbackOnError: true };
+        if (tests?.length) Object.assign(apiOptions, { testLevel: "RunSpecifiedTests", runTests: tests });
+        if (testLevel) apiOptions.testLevel = testLevel;
+        const deploy = await cs.deploy({ usernameOrConnection: conn, apiOptions });
+        const result = await deploy.pollStatus({ frequency: Duration.seconds(2), timeout: Duration.minutes(waitMinutes) });
+        // Keep scratch-org source tracking in step, as `sf project deploy start` does.
+        if (result.response.success && !checkOnly && (await o.tracksSource())) {
+          const st = await tracking().SourceTracking.create({ org: o, project });
+          await st.updateTrackingFromDeploy(result);
+        }
+        return summarizeDeploy(result.response);
+      })),
+
+    test: ({ org, classNames, tests, suiteNames, testLevel, codeCoverage, waitMinutes = 60 }) => withConn(org, async conn => {
+      const { TestService } = apex();
+      const service = new TestService(conn);
+      const level = testLevel ?? (classNames?.length || tests?.length || suiteNames?.length ? "RunSpecifiedTests" : "RunLocalTests");
+      // apex-node takes comma-separated strings, as the sf flags do.
+      const csv = list => (list?.length ? list.join(",") : undefined);
+      const payload = await service.buildAsyncPayload(level, csv(tests), csv(classNames), csv(suiteNames));
+      const result = await service.runTestAsynchronous(payload, Boolean(codeCoverage), false, undefined, undefined, Duration.minutes(waitMinutes));
+      return summarizeTests(result);
+    })
+  };
+}

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/paths.mjs

@@ -0,0 +1,16 @@
+import { mkdirSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Unix socket paths are capped near 108 bytes, so keep the runtime dir short.
+export function runtimeDir(env = process.env) {
+  const base = env.SFD_RUNTIME_DIR ?? join(env.XDG_RUNTIME_DIR ?? tmpdir(), `sfd-${process.getuid()}`);
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  chmodSync(base, 0o700);
+  return base;
+}
+
+export function paths(env = process.env) {
+  const dir = runtimeDir(env);
+  return { dir, socket: join(dir, "sfd.sock"), log: join(dir, "sfd.log"), pid: join(dir, "sfd.pid") };
+}

package/src/project.mjs

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+function walkUp(start, test) {
+  for (let dir = resolve(start); ; dir = dirname(dir)) {
+    if (test(dir)) return dir;
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+export function findProjectDir(cwd) {
+  return walkUp(cwd, dir => existsSync(join(dir, "sfdx-project.json")));
+}
+
+function readTargetOrg(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))["target-org"];
+  } catch {
+    return undefined;
+  }
+}
+
+// Same precedence as sf: flag, SF_TARGET_ORG, nearest local .sf/config.json, then global config.
+export function resolveTargetOrg(flag, cwd, env = process.env, home = homedir()) {
+  if (flag) return flag;
+  if (env.SF_TARGET_ORG) return env.SF_TARGET_ORG;
+  const local = walkUp(cwd, dir => dir !== home && readTargetOrg(join(dir, ".sf", "config.json")) !== undefined);
+  if (local) return readTargetOrg(join(local, ".sf", "config.json"));
+  const global = readTargetOrg(join(home, ".sf", "config.json"));
+  if (global) return global;
+  throw new Error("No target org. Pass -o <alias> or set target-org with `sf config set target-org`.");
+}

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" };
+}