@syntax-syllogism/sfd 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# 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.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
+
+- 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,145 @@
-# 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 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
+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, 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:
+
+```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
+
+## 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

@@ -0,0 +1,220 @@
+#!/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";
+import { UsageError } from "../src/usage-error.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)
+  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
+
+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" }
+};
+
+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) {
+  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; }
+
+  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.2.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})`);