@syntax-syllogism/sfd 0.2.0 → 0.4.0

package/src/paths.mjs

@@ -1,16 +1,34 @@
 import { mkdirSync, chmodSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { tmpdir, userInfo } from "node:os";
+import { createHash } from "node:crypto";
 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) {
+export function runtimeDir(env = process.env, platform = process.platform) {
+  if (platform === "win32") {
+    const base = env.SFD_RUNTIME_DIR ?? join(env.LOCALAPPDATA ?? tmpdir(), "sfd");
+    mkdirSync(base, { recursive: true });
+    return base;
+  }
   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") };
+// Windows has no Unix sockets in the filesystem; the daemon listens on a named pipe instead.
+// Pipe names are machine-wide, so derive one per user and runtime dir.
+export function socketPath(dir, platform = process.platform) {
+  if (platform !== "win32") return join(dir, "sfd.sock");
+  const id = createHash("sha256").update(`${userInfo().username}\0${dir.toLowerCase()}`).digest("hex").slice(0, 16);
+  return `\\\\.\\pipe\\sfd-${id}`;
+}
+
+export function isPipe(socket) {
+  return socket.startsWith("\\\\.\\pipe\\");
+}
+
+export function paths(env = process.env, platform = process.platform) {
+  const dir = runtimeDir(env, platform);
+  return { dir, socket: socketPath(dir, platform), log: join(dir, "sfd.log"), pid: join(dir, "sfd.pid") };
 }

package/src/rewrite.mjs

@@ -2,7 +2,7 @@
 const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
 const skip = reason => ({ skip: reason });
 
-function lex(source) {
+export function lex(source) {
   const tokens = [];
   let i = 0;
   while (i < source.length) {
@@ -44,12 +44,18 @@ const wait = ["w wait", "-w", true];
 const level = ["l test-level", "-l", true];
 const tests = ["t tests", "-t", true, true];
 const mappings = [
+  { sf: "org list metadata-types", sfd: "list-metadata-types", flags: [org, json] },
+  { sf: "org list metadata", sfd: "list-metadata", flags: [org, json, ["m metadata-type", "-m", true], ["folder", "--folder", true]] },
+  { sf: "apex list log", sfd: "logs", flags: [org, json] },
+  { sf: "apex get log", sfd: "logs get", flags: [org, json, ["i log-id", "", true], ["n number", "", true]] },
   { 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 retrieve start", sfd: "retrieve", flags: [org, json, wait, ["d source-dir", "-d", true, true], ["m metadata", "-m", true, true], ["x manifest", "-x", true], ["c ignore-conflicts", "--ignore-conflicts", false]] },
   { 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 list", sfd: "org list", flags: [["all", "--all", false], ["skip-connection-status", "", false], ["json", "--json", false]] },
   { sf: "org display", sfd: "org", flags: [org, json] }
 ];
 
@@ -79,15 +85,21 @@ function mapArgs(argv) {
       }
     } 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 === "r") {
+      if (mapping.sfd === "query" && values[0] === "csv") output.push("--csv");
+      else if (!["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.sfd === "org list" && !seen.has("skip-connection-status")) output.push("--status");
   if (mapping.required && !seen.has(mapping.required)) return skip(`missing required ${mapping.required} flag`);
+  if (mapping.sfd === "list-metadata" && !seen.has("m")) return skip("metadata listing needs metadata-type");
   if (mapping.sfd === "deploy" && !seen.has("d") && !seen.has("m")) return skip("deploy needs source-dir or metadata");
+  if (mapping.sfd === "retrieve" && ["d", "m", "x"].filter(key => seen.has(key)).length > 1) return skip("retrieve selectors are mutually exclusive");
   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";
@@ -96,7 +108,14 @@ function mapArgs(argv) {
     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;
+  let logTarget;
+  if (mapping.sfd === "logs get") {
+    if (seen.has("i") && seen.has("n")) return skip("choose log-id or number");
+    if (seen.has("i")) logTarget = seen.get("i")[0];
+    else if (seen.get("n")?.[0] === "1") logTarget = "latest";
+    else return skip("log get needs log-id or --number 1");
+  }
+  const positional = logTarget ? [logTarget] : 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" };

package/src/server.mjs

@@ -1,5 +1,6 @@
 import net from "node:net";
 import { chmodSync, unlinkSync } from "node:fs";
+import { isPipe } from "./paths.mjs";
 
 // 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}.
@@ -40,7 +41,7 @@ export async function startServer({ socket, version, handlers, idleMs = 60 * 60_
     draining = reason;
     clearTimeout(idleTimer);
     server.close();
-    try { unlinkSync(socket); } catch {}
+    if (!isPipe(socket)) try { unlinkSync(socket); } catch {}
     maybeExit();
   };
   const armIdle = () => {
@@ -57,7 +58,7 @@ export async function startServer({ socket, version, handlers, idleMs = 60 * 60_
     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 };
+      return { status: 1, name: e.name ?? "Error", message: e.message ?? String(e), errorCode: e.errorCode, ...(e.trace ? { trace: e.trace } : {}) };
     }
   }
 
@@ -90,10 +91,12 @@ export async function startServer({ socket, version, handlers, idleMs = 60 * 60_
   } catch (e) {
     if (e.code !== "EADDRINUSE") throw e;
     if (await probe(socket)) throw new AlreadyRunning("sfd is already running");
+    // A named pipe disappears with its owner, so only a Unix socket file can be stale.
+    if (isPipe(socket)) throw e;
     unlinkSync(socket);
     await listenOnce(server, socket);
   }
-  chmodSync(socket, 0o600);
+  if (!isPipe(socket)) chmodSync(socket, 0o600);
   armIdle();
   return { server, drain };
 }

package/src/sf-root.mjs

@@ -5,17 +5,27 @@ 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) {
+export function findSfRoot(env = process.env, platform = process.platform) {
   if (env.SFD_SF_ROOT) return env.SFD_SF_ROOT;
-  const bin = execFileSync("which", ["sf"], { encoding: "utf8" }).trim();
+  const bin = whichSf(platform);
   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 {}
+    // npm installs on Windows put an sf.cmd shim next to node_modules instead of a symlink.
+    for (const candidate of [dir, join(dir, "node_modules", "@salesforce", "cli")]) {
+      try {
+        if (JSON.parse(readFileSync(join(candidate, "package.json"), "utf8")).name === "@salesforce/cli") return candidate;
+      } catch {}
+    }
   }
   throw new Error(`Could not locate the @salesforce/cli install behind ${bin}; set SFD_SF_ROOT.`);
 }
 
+function whichSf(platform) {
+  if (platform !== "win32") return execFileSync("which", ["sf"], { encoding: "utf8" }).trim();
+  // `where` lists every match in PATH order; prefer the cmd shim over the extensionless sh script.
+  const found = execFileSync("where", ["sf"], { encoding: "utf8" }).split(/\r?\n/).filter(Boolean);
+  return found.find(f => /\.(cmd|exe)$/i.test(f)) ?? found[0];
+}
+
 export function sfInfo(root) {
   const file = join(root, "package.json");
   return { root, version: JSON.parse(readFileSync(file, "utf8")).version, mtimeMs: statSync(file).mtimeMs };

package/src/snippet.mjs

@@ -0,0 +1,42 @@
+import { COMMANDS } from "./commands.mjs";
+
+const START = "<!-- sfd:start -->";
+const END = "<!-- sfd:end -->";
+
+export function snippet() {
+  const lines = [];
+  let previousGroup;
+  for (const { name, args, summary, agentTip, agentGroup } of COMMANDS) {
+    const tip = agentTip ?? `${args}: ${summary.replaceAll("\n", " ")}`;
+    const separator = tip.indexOf(": ");
+    if (separator === -1) throw new Error(`Invalid agentTip for ${name}: expected ": " separator`);
+    const invocation = ["sfd", name, tip.slice(0, separator).trim()].filter(Boolean).join(" ");
+    const entry = `\`${invocation}\`: ${tip.slice(separator + 2)}`;
+    if (agentGroup && agentGroup === previousGroup) lines[lines.length - 1] += `; ${entry}`;
+    else lines.push(`- ${entry}`);
+    previousGroup = agentGroup;
+  }
+  return [
+    START,
+    'Prefer `sfd` (warm Salesforce daemon, ~0.2 s/call, compact output) over `sf`:',
+    ...lines,
+    'Add `-o <alias>` as with `sf`. Exit: 0 ok, 1 operation failed, 2 usage, 3 daemon. For anything else use `sf … --json`; pipe through `jq` for a few fields.',
+    END
+  ].join("\n");
+}
+
+export function upsertSnippet(text, block) {
+  const start = text.indexOf(START);
+  const end = text.indexOf(END);
+  if (start === -1 && end === -1) {
+    const prefix = text.replace(/\s+$/, "");
+    return `${prefix ? `${prefix}\n\n` : ""}${block}\n`;
+  }
+  if (end === -1) throw new Error("found start marker without end");
+  if (start === -1) throw new Error("found end marker without start");
+  if (end < start) throw new Error("end marker precedes start marker");
+  if (text.indexOf(START, start + START.length) !== -1 || text.indexOf(END, end + END.length) !== -1) {
+    throw new Error("found multiple sfd blocks or nested markers");
+  }
+  return text.slice(0, start) + block + text.slice(end + END.length);
+}

package/src/usage-error.mjs

@@ -1 +1,3 @@
-export class UsageError extends Error {}
+export class UsageError extends Error {
+  name = "UsageError";
+}