@syntax-syllogism/sfd 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-22
+
+### Added
+
+- Warm local daemon for fast Salesforce CLI operations, covering queries, anonymous Apex, REST calls, describes, source deploys, and Apex test runs
+
+### Fixed
+
+- Correct UTF-8 handling of Salesforce output
+- Fix paging of large result sets
+- Fix daemon startup and shutdown lifecycle
+- Enforce timeouts on Salesforce operations
+- Fix command-line interface behavior
+

package/LICENSE

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

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# sfd
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fast Salesforce CLI operations through a warm local daemon.
+
+sfd runs common Salesforce CLI operations through a
+long-lived local daemon, so each call skips the 5–20 seconds `sf` spends
+loading oclif and its plugins. A warm call answers in about 0.2 seconds. It is
+meant for agents and scripts that make many small org calls in a row.
+
+Requires Node 22 or newer and an installed, authenticated Salesforce CLI. sfd
+has no Salesforce dependencies of its own: the daemon loads
+`@salesforce/core`, source-deploy-retrieve, apex-node and source-tracking from
+the `sf` install on `PATH`. Auth, aliases, API versions and the metadata
+registry therefore always match what `sf` uses.
+
+## Install
+
+```bash
+npm install --global @syntax-syllogism/sfd
+sfd query "SELECT Id, Name FROM Account LIMIT 5" -o my-org
+```
+
+## Commands
+
+| Command | Does | `sf` equivalent |
+| --- | --- | --- |
+| `sfd query "<soql>"` | SOQL, all pages, `attributes` stripped. `--tooling`, `--all`, `--raw` for the unstripped result | `sf data query` |
+| `sfd apex [file]` | Anonymous Apex from a file, `-f`, or stdin. Prints `USER_DEBUG` and fatal lines; `--log` for the full log | `sf apex run` |
+| `sfd rest <path>` | REST call. `-X <method>`, `--body <json\|@file>` | `sf api request rest` |
+| `sfd describe <sobject>` | Compact describe; `--raw` for the full one. `--tooling` | `sf sobject describe` |
+| `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 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
+command takes `-o <alias>` and `--json` (the raw daemon response). Without `-o`
+the org resolves like `sf`: `SF_TARGET_ORG`, then the nearest
+`.sf/config.json`, then the global config.
+
+Exit codes: `0` success, `1` the operation failed (including a compile error,
+a failed deploy, or a failing test), `2` usage error, `3` the daemon could
+not be reached or started, or a request timed out. Unreadable input files are
+usage errors and include the file path.
+
+Use `sf` (with `--json` when scripting) for anything sfd does not cover (org creation, package
+commands, retrieve, data import).
+
+## Daemon lifecycle
+
+The first command starts the daemon detached; there is nothing to set up. It
+listens on a Unix socket in `$XDG_RUNTIME_DIR/sfd-<uid>/` (or the system temp
+directory), in a directory with mode `0700` and a socket with mode `0600`.
+Access tokens stay in daemon memory and are never written to disk. The daemon
+log is `sfd.log` in the same directory; `sfd status` prints its path.
+
+The daemon exits on its own when:
+
+- it has been idle for 60 minutes (`SFD_IDLE_MINUTES` overrides),
+- a client with different sfd code connects (including lifecycle commands;
+  the protocol version includes the source mtime, so an upgrade or local edit
+  takes effect on the next call), or
+- the `sf` install changes (an `sf update` rewrites its `package.json`).
+
+In each case it stops accepting connections at once, finishes in-flight
+requests (a running deploy or test run is not cut off), and the next call
+starts a fresh daemon.
+
+Auth changes made with `sf org login` or `sf alias set` are picked up
+automatically. An expired session is rebuilt once and the call retried. Run
+`sfd reload` if org state still looks stale. Lifecycle commands replace an
+older daemon before reporting it as running or reloading it; `stop` shuts
+it down even if its protocol differs.
+
+## Behavior notes
+
+- Queries fetch every page without a record cap. Compact results preserve
+  `done` and any continuation URL supplied by Salesforce.
+- Deploys reload `sfdx-project.json` on every call and run one at a time per
+  daemon. After a successful deploy to an org that tracks source, sfd updates
+  source tracking as `sf project deploy start` does.
+- `deploy` without `-l` uses the Metadata API default. `-t` alone implies
+  `RunSpecifiedTests`.
+- `test` without selectors runs `RunLocalTests`. A non-matching method is
+  reported as skipped, as with `sf`.
+- Paths in `-d` and the project directory resolve from the client's working
+  directory, not the daemon's.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `SFD_TIMEOUT_SECONDS` | Positive request deadline in seconds, including connection time. Overrides defaults: 3 seconds for health/lifecycle requests; 120 seconds for other operations, extended to at least the deploy/test `-w` wait plus 60 seconds (default waits: 33/60 minutes). Increase this for long queries or queued deploys. Timeout exits 3. |
+| `SFD_IDLE_MINUTES` | Idle timeout, default 60. |
+| `SFD_RUNTIME_DIR` | Socket, log and pid directory. |
+| `SFD_SF_ROOT` | `@salesforce/cli` install to load libraries from, instead of the `sf` on `PATH`. |
+| `SFD_HANDLERS_MODULE` | Test seam: stub handlers module used by the CLI tests. |
+
+## Testing
+
+`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
+paging, auth refresh, deployment and test orchestration without an org.
+A real-org check is opt-in:
+
+```bash
+SFD_TEST_ORG=<alias> npm test
+```
+
+For local development, `npm run build` syntax-checks every source file and
+`npm test` runs the suite. sfd has no runtime or dev dependencies, so there is
+nothing to install; the Salesforce libraries come from your `sf` install.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for how to report vulnerabilities.
+
+## License
+
+[MIT](LICENSE) © Jacob Richter

package/bin/sfd.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { call, isRunning, startDaemon, DaemonError, VERSION } from "../src/client.mjs";
+import { findProjectDir, resolveTargetOrg } from "../src/project.mjs";
+import { formatApex, formatDeploy, formatTests } from "../src/format.mjs";
+import { paths } from "../src/paths.mjs";
+
+const USAGE = `sfd ${VERSION}: fast Salesforce CLI operations through a warm local daemon
+
+Usage: sfd <command> [options]
+
+Commands:
+  query <soql>          Run SOQL (all pages). --tooling, --all (include deleted)
+  apex [file]           Run anonymous Apex from a file, -f <file>, or stdin. --log for the full debug log
+  rest <path>           Call a REST path, e.g. /services/data/v67.0/limits. -X <method>, --body <json|@file>
+  describe <sobject>    Compact describe. --tooling, --raw for the full describe
+  deploy                Deploy source. -d <path> (repeatable), -m <Type[:Name]> (repeatable),
+                        --check-only, -l <test level>, -t <test> (repeatable), -w <minutes>
+  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)
+  start | stop | status | reload
+                        Manage the daemon. reload drops cached orgs and auth state
+
+Common options:
+  -o, --target-org <alias>  Org alias or username (default: sf target-org config)
+  --json                    Print the raw JSON response
+  -h, --help                Show this help
+
+Exit codes: 0 success, 1 operation failed, 2 usage error, 3 daemon error.`;
+
+const options = {
+  "target-org": { type: "string", short: "o" },
+  json: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  tooling: { type: "boolean" },
+  all: { type: "boolean" },
+  raw: { type: "boolean" },
+  log: { type: "boolean" },
+  file: { type: "string", short: "f" },
+  method: { type: "string", short: "X" },
+  body: { type: "string" },
+  "source-dir": { type: "string", short: "d", multiple: true },
+  metadata: { type: "string", short: "m", multiple: true },
+  "check-only": { type: "boolean" },
+  "test-level": { type: "string", short: "l" },
+  tests: { type: "string", short: "t", multiple: true },
+  "class-names": { type: "string", short: "n", multiple: true },
+  "suite-names": { type: "string", short: "s", multiple: true },
+  "code-coverage": { type: "boolean", short: "c" },
+  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() {
+  if (process.stdin.isTTY) return "";
+  try { return readFileSync(0, "utf8"); } catch { return ""; }
+}
+
+function readInputFile(file) {
+  const path = resolve(file);
+  try { return readFileSync(path, "utf8"); }
+  catch (e) { throw new UsageError(`Cannot read input file ${path}: ${e.message}`); }
+}
+
+function readBody(spec) {
+  if (spec === undefined) return undefined;
+  const text = spec.startsWith("@") ? readInputFile(spec.slice(1)) : spec;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+function wait(values) {
+  if (values.wait === undefined) return undefined;
+  const minutes = Number(values.wait);
+  if (!Number.isFinite(minutes) || minutes <= 0) throw new UsageError("--wait must be a positive number of minutes.");
+  return minutes;
+}
+
+function print(value) {
+  process.stdout.write((typeof value === "string" ? value : JSON.stringify(value, null, 2)) + "\n");
+}
+
+async function run(argv) {
+  const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true });
+  const [command, ...rest] = positionals;
+  if (values.help || !command) { print(USAGE); return 0; }
+
+  const cwd = process.cwd();
+  const org = () => resolveTargetOrg(values["target-org"], cwd);
+  const projectDir = () => {
+    const dir = findProjectDir(cwd);
+    if (!dir) throw new UsageError("No sfdx-project.json found in this directory or its parents.");
+    return dir;
+  };
+
+  // Lifecycle commands.
+  switch (command) {
+    case "start":
+      if (await isRunning()) { print("sfd already running"); return 0; }
+      startDaemon();
+      await call("ping");
+      print(`sfd started (${paths().socket})`);
+      return 0;
+    case "stop":
+      if (!(await isRunning())) { print("sfd not running"); return 0; }
+      await call("stop", {}, { autoStart: false });
+      print("sfd stopping");
+      return 0;
+    case "status": {
+      if (!(await isRunning())) { print(values.json ? { running: false } : "sfd not running"); return 0; }
+      const res = await call("status", {}, { autoStart: false });
+      const s = { running: true, version: VERSION, socket: paths().socket, log: paths().log, ...res.result };
+      print(values.json ? s : `sfd ${VERSION} running (pid ${s.pid}, up ${s.uptimeSeconds}s), orgs: ${s.orgs.join(", ") || "none"}\nlog: ${s.log}`);
+      return 0;
+    }
+    case "reload": {
+      if (!(await isRunning())) { print("sfd not running"); return 0; }
+      await call("reload", {}, { autoStart: false });
+      print("sfd reloaded");
+      return 0;
+    }
+  }
+
+  let req;
+  let render = result => result;
+  switch (command) {
+    case "query": {
+      const q = rest.join(" ") || readStdin().trim();
+      if (!q) throw new UsageError("query needs a SOQL string.");
+      req = { org: org(), q, tooling: values.tooling, all: values.all, raw: values.raw };
+      break;
+    }
+    case "apex": {
+      const file = values.file ?? rest[0];
+      const body = file ? readInputFile(file) : readStdin();
+      if (!body.trim()) throw new UsageError("apex needs code from a file, -f <file>, or stdin.");
+      req = { org: org(), body };
+      render = result => formatApex(result, { fullLog: values.log });
+      break;
+    }
+    case "rest": {
+      const url = rest[0];
+      if (!url) throw new UsageError("rest needs a path, e.g. /services/data/v67.0/limits.");
+      req = { org: org(), method: (values.method ?? (values.body ? "POST" : "GET")).toUpperCase(), url, body: readBody(values.body) };
+      break;
+    }
+    case "describe": {
+      if (!rest[0]) throw new UsageError("describe needs an sObject name.");
+      req = { org: org(), sobject: rest[0], tooling: values.tooling, raw: values.raw };
+      break;
+    }
+    case "deploy": {
+      const dir = projectDir();
+      const sourcePaths = split(values["source-dir"])?.map(d => resolve(cwd, d));
+      for (const p of sourcePaths ?? []) if (!existsSync(p)) throw new UsageError(`No such path: ${p}`);
+      const metadata = split(values.metadata);
+      if (!sourcePaths?.length && !metadata?.length) throw new UsageError("deploy needs -d <path> or -m <Type[:Name]>.");
+      req = {
+        org: org(), projectDir: dir, sourcePaths, metadata, checkOnly: values["check-only"],
+        testLevel: values["test-level"], tests: split(values.tests), waitMinutes: wait(values)
+      };
+      render = result => formatDeploy(result, req.org);
+      break;
+    }
+    case "test":
+      req = {
+        org: org(), classNames: split(values["class-names"]), tests: split(values.tests), suiteNames: split(values["suite-names"]),
+        testLevel: values["test-level"], codeCoverage: values["code-coverage"], waitMinutes: wait(values)
+      };
+      render = result => formatTests(result, req.org);
+      break;
+    case "org":
+      req = { org: org() };
+      break;
+    default:
+      throw new UsageError(`Unknown command: ${command}. Run sfd --help.`);
+  }
+
+  const res = await call(command, req);
+  if (values.json) { print(res); return res.status === 0 ? okStatus(command, res.result) : 1; }
+  if (res.status !== 0) {
+    process.stderr.write(`${res.name}: ${res.message}\n`);
+    return 1;
+  }
+  print(render(res.result));
+  return okStatus(command, res.result);
+}
+
+// A request can succeed while the Salesforce operation fails (compile error, failed deploy or test).
+function okStatus(command, result) {
+  if (command === "apex") return result.compiled && result.success ? 0 : 1;
+  if (command === "deploy") return result.success ? 0 : 1;
+  if (command === "test") return result.failing === 0 && !result.setupFailures?.length ? 0 : 1;
+  return 0;
+}
+
+try {
+  process.exitCode = await run(process.argv.slice(2));
+} catch (e) {
+  if (e instanceof UsageError || e.code?.startsWith?.("ERR_PARSE_ARGS")) {
+    process.stderr.write(`${e.message}\n`);
+    process.exitCode = 2;
+  } else if (e instanceof DaemonError || ["ENOENT", "ECONNREFUSED", "ECONNRESET", "EPIPE"].includes(e.code)) {
+    process.stderr.write(`sfd daemon error: ${e.message}\nlog: ${paths().log}\n`);
+    process.exitCode = 3;
+  } else {
+    process.stderr.write(`${e.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@syntax-syllogism/sfd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Warm Salesforce CLI daemon: SOQL, anonymous Apex, REST, describe, deploy, and Apex tests without sf startup cost.",
+  "type": "module",
+  "bin": {
+    "sfd": "bin/sfd.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin/sfd.mjs",
+    "src",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "salesforce",
+    "sf",
+    "sfdx",
+    "cli",
+    "daemon",
+    "apex",
+    "soql",
+    "agents"
+  ],
+  "homepage": "https://github.com/Syntax-Syllogism/sfd#readme",
+  "bugs": {
+    "url": "https://github.com/Syntax-Syllogism/sfd/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syntax-Syllogism/sfd.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "for f in bin/sfd.mjs src/*.mjs; do node --check \"$f\" || exit 1; done",
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/client.mjs

@@ -0,0 +1,85 @@
+import net from "node:net";
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { paths } from "./paths.mjs";
+import { PROTOCOL } from "./version.mjs";
+
+export { VERSION } from "./version.mjs";
+
+export class DaemonError extends Error {}
+
+function send(socket, req, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const conn = net.connect(socket);
+    conn.setEncoding("utf8");
+    const timer = setTimeout(() => conn.destroy(new DaemonError(`sfd request timed out after ${timeoutMs / 1000} seconds.`)), timeoutMs);
+    conn.on("close", () => clearTimeout(timer));
+    let buf = "";
+    conn.on("connect", () => conn.write(JSON.stringify(req) + "\n"));
+    conn.on("data", chunk => (buf += chunk));
+    conn.on("end", () => {
+      try { resolve(JSON.parse(buf)); } catch { reject(new DaemonError(`Bad response from sfd: ${buf.slice(0, 200)}`)); }
+    });
+    conn.on("error", reject);
+  });
+}
+
+export function startDaemon(env = process.env) {
+  const p = paths(env);
+  const out = openSync(p.log, "a");
+  const child = spawn(process.execPath, [fileURLToPath(new URL("./daemon.mjs", import.meta.url))], {
+    detached: true, stdio: ["ignore", out, out], env
+  });
+  child.unref();
+}
+
+async function waitForSocket(socket, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      return await send(socket, { op: "ping", v: PROTOCOL }, Math.max(1, Math.min(3000, deadline - Date.now())));
+    } catch (e) {
+      if (Date.now() > deadline) throw new DaemonError(`sfd did not start within ${timeoutMs} ms (${e.code ?? e.message}); see the daemon log.`);
+      await new Promise(r => setTimeout(r, 50));
+    }
+  }
+}
+
+// Send one request, starting the daemon if needed and replacing it once on a version mismatch.
+export async function call(op, args = {}, { env = process.env, autoStart = true, startTimeoutMs = 30_000 } = {}) {
+  const p = paths(env);
+  const req = { ...args, op, v: PROTOCOL };
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let res;
+    try {
+      const configured = Number(env.SFD_TIMEOUT_SECONDS);
+      const health = ["ping", "status", "stop", "reload"].includes(op);
+      const waitMinutes = args.waitMinutes ?? (op === "deploy" ? 33 : op === "test" ? 60 : 0);
+      const timeoutMs = Number.isFinite(configured) && configured > 0
+        ? configured * 1000
+        : health ? 3000 : Math.max(120_000, waitMinutes * 60_000 + 60_000);
+      res = await send(p.socket, req, timeoutMs);
+    } catch (e) {
+      if (!autoStart || !["ENOENT", "ECONNREFUSED"].includes(e.code)) throw e;
+      startDaemon(env);
+      await waitForSocket(p.socket, startTimeoutMs);
+      continue;
+    }
+    if (!res.restart) return res;
+    // The old daemon is draining and has freed the socket path; start ours.
+    startDaemon(env);
+    await waitForSocket(p.socket, startTimeoutMs);
+  }
+  throw new DaemonError("sfd kept asking for a restart; run `sfd stop` and retry.");
+}
+
+export async function isRunning(env = process.env) {
+  try {
+    await call("ping", {}, { env, autoStart: false });
+    return true;
+  } catch (e) {
+    if (["ENOENT", "ECONNREFUSED"].includes(e.code)) return false;
+    throw e;
+  }
+}

package/src/daemon.mjs

@@ -0,0 +1,43 @@
+// Daemon entry point. The client spawns this detached; it is not meant to be run by hand.
+import { readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
+import { PROTOCOL, VERSION } from "./version.mjs";
+import { AlreadyRunning, startServer } from "./server.mjs";
+import { paths } from "./paths.mjs";
+import { findSfRoot, sfInfo } from "./sf-root.mjs";
+
+const log = (...args) => console.error(new Date().toISOString(), ...args);
+const p = paths();
+const sf = sfInfo(findSfRoot());
+
+// SFD_HANDLERS_MODULE swaps in stub handlers for tests that must not touch an org.
+const { createHandlers } = await import(process.env.SFD_HANDLERS_MODULE ?? "./handlers.mjs");
+const handlers = createHandlers(sf.root);
+
+// An sf upgrade rewrites its package.json; finish in-flight work and let the next call start fresh.
+const isStale = () => {
+  try { return statSync(`${sf.root}/package.json`).mtimeMs !== sf.mtimeMs; } catch { return true; }
+};
+
+try {
+  await startServer({
+    socket: p.socket,
+    version: PROTOCOL,
+    handlers,
+    idleMs: Number(process.env.SFD_IDLE_MINUTES ?? 60) * 60_000,
+    isStale,
+    onExit: reason => {
+      log(`exiting (${reason})`);
+      try { if (readFileSync(p.pid, "utf8").trim() === String(process.pid)) unlinkSync(p.pid); } catch {}
+      setTimeout(() => process.exit(0), 100);
+    }
+  });
+} catch (e) {
+  if (e instanceof AlreadyRunning) {
+    log("another sfd daemon is already running; exiting");
+    process.exit(0);
+  }
+  throw e;
+}
+
+writeFileSync(p.pid, String(process.pid));
+log(`sfd ${VERSION} listening on ${p.socket} (pid ${process.pid}, sf ${sf.version})`);

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

@@ -0,0 +1,99 @@
+import net from "node:net";
+import { chmodSync, unlinkSync } from "node:fs";
+
+// Newline-delimited JSON over a Unix socket: one request and one response per connection.
+// Responses are {status: 0, result} | {status: 1, name, message} | {restart: true}.
+
+export class AlreadyRunning extends Error {}
+
+function probe(socket) {
+  return new Promise(resolve => {
+    const s = net.connect(socket, () => { s.destroy(); resolve(true); });
+    s.on("error", () => resolve(false));
+  });
+}
+
+function listenOnce(server, socket) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socket, () => { server.off("error", reject); resolve(); });
+  });
+}
+
+export async function startServer({ socket, version, handlers, idleMs = 60 * 60_000, isStale = () => false, onExit = () => {} }) {
+  let active = 0;
+  let idleTimer;
+  let draining;
+  let exited = false;
+
+  const maybeExit = () => {
+    if (draining && active === 0 && !exited) {
+      exited = true;
+      onExit(draining);
+    }
+  };
+
+  // Stop accepting connections and free the socket path right away, so a replacement
+  // daemon can bind it, but let in-flight requests (deploys, test runs) finish.
+  const drain = reason => {
+    if (draining) return;
+    draining = reason;
+    clearTimeout(idleTimer);
+    server.close();
+    try { unlinkSync(socket); } catch {}
+    maybeExit();
+  };
+  const armIdle = () => {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => active === 0 && drain("idle"), idleMs);
+    idleTimer.unref?.();
+  };
+
+  async function respond(req) {
+    if (req.op === "stop") return { status: 0, result: { stopping: true } };
+    if (req.v !== version) return { restart: true };
+    const handler = handlers[req.op];
+    if (!handler) return { status: 1, name: "UnknownOperation", message: `Unknown operation: ${req.op}` };
+    try {
+      return { status: 0, result: await handler(req) };
+    } catch (e) {
+      return { status: 1, name: e.name ?? "Error", message: e.message ?? String(e), errorCode: e.errorCode };
+    }
+  }
+
+  const server = net.createServer(conn => {
+    conn.setEncoding("utf8");
+    let buf = "";
+    conn.on("error", () => {});
+    conn.on("data", async chunk => {
+      buf += chunk;
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+      conn.removeAllListeners("data");
+      active++;
+      clearTimeout(idleTimer);
+      let req;
+      try { req = JSON.parse(buf.slice(0, nl)); } catch { req = {}; }
+      const res = await respond(req);
+      conn.end(JSON.stringify(res) + "\n");
+      active--;
+      if (req.op === "stop") drain("stop");
+      else if (res.restart) drain("version");
+      else if (isStale()) drain("stale");
+      if (draining) maybeExit();
+      else if (active === 0) armIdle();
+    });
+  });
+
+  try {
+    await listenOnce(server, socket);
+  } catch (e) {
+    if (e.code !== "EADDRINUSE") throw e;
+    if (await probe(socket)) throw new AlreadyRunning("sfd is already running");
+    unlinkSync(socket);
+    await listenOnce(server, socket);
+  }
+  chmodSync(socket, 0o600);
+  armIdle();
+  return { server, drain };
+}

package/src/sf-root.mjs

@@ -0,0 +1,26 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+// sfd loads @salesforce/core, SDR, apex-node and source-tracking from the installed sf CLI,
+// so auth files, API versions and metadata registries always match what `sf` itself uses.
+export function findSfRoot(env = process.env) {
+  if (env.SFD_SF_ROOT) return env.SFD_SF_ROOT;
+  const bin = execFileSync("which", ["sf"], { encoding: "utf8" }).trim();
+  for (let dir = dirname(realpathSync(bin)); dirname(dir) !== dir; dir = dirname(dir)) {
+    try {
+      if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name === "@salesforce/cli") return dir;
+    } catch {}
+  }
+  throw new Error(`Could not locate the @salesforce/cli install behind ${bin}; set SFD_SF_ROOT.`);
+}
+
+export function sfInfo(root) {
+  const file = join(root, "package.json");
+  return { root, version: JSON.parse(readFileSync(file, "utf8")).version, mtimeMs: statSync(file).mtimeMs };
+}
+
+export function sfRequire(root) {
+  return createRequire(join(root, "package.json"));
+}

package/src/version.mjs

@@ -0,0 +1,10 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+
+const pkg = new URL("../package.json", import.meta.url);
+export const VERSION = JSON.parse(readFileSync(pkg, "utf8")).version;
+
+// The client and daemon must run the same code, not just the same package version:
+// fold the newest source mtime in, so an edited or reinstalled checkout replaces a running daemon.
+const src = new URL("./", import.meta.url);
+const newest = Math.max(...readdirSync(src).map(f => statSync(new URL(f, src)).mtimeMs));
+export const PROTOCOL = `${VERSION}+${Math.floor(newest)}`;