@syntax-syllogism/sfd 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Windows: `sfd start` and every other command failed with
+  "process.getuid is not a function". The daemon now listens on a per-user
+  named pipe, finds `sf` with `where` (including npm `sf.cmd` shims), and
+  starts without a console window. CI runs on Windows as well as Linux.
+
+## [0.4.0] - 2026-10-22
+
+### Added
+
+- `--limit` and `--csv` options for `sfd query`, with CSV output
+- `sfd agents-snippet` command that generates a snippet for AGENTS.md and CLAUDE.md
+- `sfd org list` command that lists locally authenticated orgs, with optional status checks
+- `sfd list-metadata-types` and `sfd list-metadata` commands for browsing org metadata
+- `sfd discover` command that reports missed opportunities to use `sfd` in place of `sf`
+
+## [0.3.1] - 2026-10-22
+
+### Changed
+
+- Internal maintenance and tooling updates
+
+## [0.3.0] - 2026-10-22
+
+### Added
+
+- Added `sfd retrieve` for pulling metadata from an org into the local project
+- Added tracking commands for inspecting changes between local source and the org
+- Added filtered debug log output
+- Added automatic TraceFlag creation when debug logs are requested
+
+### Fixed
+
+- Fixed a startup failure on Windows (`process.getuid is not a function`)
+
 ## [0.2.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -24,34 +24,91 @@ sfd query "SELECT Id, Name FROM Account LIMIT 5" -o my-org
 
 | Command | Does | `sf` equivalent |
 | --- | --- | --- |
-| `sfd query "<soql>"` | SOQL, all pages, `attributes` stripped. `--tooling`, `--all`, `--raw` for the unstripped result | `sf data query` |
+| `sfd query "<soql>"` | SOQL, all pages by default, `attributes` stripped. `--limit <n>` caps rows; `--csv` prints CSV. `--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 list-metadata-types` | Supported metadata types, folder markers and child types; cached per org and API version | `sf org list metadata-types` |
+| `sfd list-metadata -m <Type>[,<Type>…]` | Live member names; `--details` for audit fields, `--folder <name>` for folder contents | `sf org list metadata` |
 | `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 retrieve [-d <path> \| -m <Type[:Name]> \| -x <package.xml>]` | Retrieve source; no selector pulls tracked remote changes. `--ignore-conflicts`, `-w <minutes>` | `sf project retrieve start` |
+| `sfd tracking [--local \| --remote] [--conflicts]` | List local, remote and conflicting source-tracked changes; `--conflicts` shows only conflicts | |
+| `sfd test` | Run Apex tests. `-n <class>`, `-t <Class.method>`, `-s <suite>`, `-l <level>`, `-c` (coverage), `-w <minutes>`, `--logs` | `sf apex run test --wait` |
+| `sfd logs [--count 10] [--user <username>]` | Recent debug logs, one line each; `--limit` aliases `--count` | `sf apex list log` |
+| `sfd logs get <id\|latest>` | Debug, exception, validation, Flow error and high limit usage lines. `--full` prints raw text | `sf apex get log` |
+| `sfd org list [--all] [--status]` | Local authenticated orgs; `--all` includes expired scratch orgs, `--status` adds live checks | `sf org list --skip-connection-status` |
 | `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 agents-snippet [--write [file]]` | Print agent instructions, or write them into `AGENTS.md` or `CLAUDE.md`. See [Using sfd with coding agents](#using-sfd-with-coding-agents) | |
+| `sfd discover [--since 30d]` | Report missed sfd opportunities and adoption from local agent transcripts. See [docs/discover.md](docs/discover.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`
+For agents, `--csv --limit 200` is the cheapest way to read rows. The limit,
+CSV layout, output by flag and truncation trailer are described in
+[docs/query.md](docs/query.md).
+
+`-d`, `-m`, `-n`, `-t` and `-s` repeat or take comma-separated lists. The org
+commands take `-o <alias>` (except `org list`), and `--json` prints the raw daemon response. Without `-o`
 the org resolves like `sf`: `SF_TARGET_ORG`, then the nearest
 `.sf/config.json`, then the global config.
 
+`sfd list-metadata-types` sorts supported types, marks folder-based types with
+`(folder)` and shows up to six child names. Its daemon cache is scoped to the org
+and connection API version, and cleared by `sfd reload`, auth changes or session
+reconnection. `--json` includes `result.cached` and `result.apiVersion`.
+
+`sfd list-metadata -m Flow,Layout` lists sorted names grouped by requested type.
+Repeat `-m` to add types. `--details` adds the modification date, modifying user,
+namespace and manageable state, omitting empty fields. Member lists are always
+live; empty groups print `(none)`. Unknown types exit 2 with a suggestion when
+available. Listings have the coverage and limits of the Metadata API
+`listMetadata` operation; they do not enumerate special cases separately.
+
+For folder-based types, omitting `--folder` lists folders with a hint. Choose a
+folder to list its members; `--folder` accepts exactly one metadata type:
+
+```bash
+sfd list-metadata -m Report
+sfd list-metadata -m Report --folder Public_Reports
+sfd list-metadata -m ApexClass --details
+```
+
+`sfd org list` reads local auth without network calls. It shows aliases, usernames,
+`*` for the default org, `H` for the default Dev Hub, org types and scratch expiry.
+Expired scratch orgs are hidden with a count hint; use `--all` to include them.
+`--status` checks non-scratch connections in parallel with a 10-second deadline
+per org, and queries scratch status once per Dev Hub (also bounded to 10 seconds).
+Unavailable Dev Hubs leave scratch status blank. New logins and logouts are picked
+up automatically. This command rejects `-o`.
+
+```bash
+sfd org list
+sfd org list --all --status
+sfd org list --json
+```
+
+For `org list`, `--json` returns `{ "orgs": [...] }` directly, with alias,
+username, orgId, instanceUrl, type, isDefault, isDefaultDevHub, and optional
+expirationDate, expired and status. The command never includes access tokens,
+refresh tokens or client secrets in any output, including `--json`. Primary-user
+filtering, status checks and the JSON allowlist are described in
+[docs/org-list.md](docs/org-list.md).
+
 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).
+commands, 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`.
+On Windows it listens on a per-user named pipe (`\\.\pipe\sfd-<hash>`), and
+the log and pid files go in `%LOCALAPPDATA%\sfd\`.
 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.
 
@@ -75,11 +132,14 @@ 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.
+- Queries fetch every page unless `--limit` is given. Compact results preserve
+  `done` and any continuation URL supplied by Salesforce; see
+  [docs/query.md](docs/query.md) for the limit rules.
+- Deploys, retrieves and `tracking` share one queue per daemon, so they run
+  one at a time. Deploys reload `sfdx-project.json` on every call.
+- Retrieve conflicts, changes-only retrieves, and how `tracking` and deploys
+  update source tracking are described in
+  [docs/source-tracking.md](docs/source-tracking.md).
 - `deploy` without `-l` uses the Metadata API default. `-t` alone implies
   `RunSpecifiedTests`.
 - `test` without selectors runs `RunLocalTests`. A non-matching method is
@@ -87,13 +147,23 @@ it down even if its protocol differs.
 - Paths in `-d` and the project directory resolve from the client's working
   directory, not the daemon's.
 
+### Debug logs
+
+`logs`, `logs get` and `test --logs` create or extend the current user's
+developer TraceFlag for 30 minutes when it is missing, expired or has less than
+five minutes left, and print one notice on stderr when they do. `--no-trace`
+skips that setup. `logs --user` only filters the list. Setup needs Tooling API
+permission to manage TraceFlag and DebugLevel records. The TraceFlag rules,
+filtered output format and `test --logs` behavior are in
+[docs/debug-logs.md](docs/debug-logs.md).
+
 ## 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_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/retrieve/test `-w` wait plus 60 seconds (default waits: 33/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_RUNTIME_DIR` | Socket, log and pid directory (on Windows, log and pid only; the pipe name is derived from it). |
 | `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. |
 
@@ -103,7 +173,7 @@ it down even if its protocol differs.
 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.
+paging, auth refresh, deployment, retrieve, source tracking and test orchestration without an org.
 A real-org check is opt-in:
 
 ```bash
@@ -140,6 +210,46 @@ 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
+with `sfd hook check '<sf command>'`. Query result format `-r csv` (or
+`--result-format csv`) maps to `sfd query --csv`. The supported commands,
+adapter details, skip rules and the `SFD_HOOK_DISABLE=1` switch are in
 [docs/agent-hooks.md](docs/agent-hooks.md).
+
+## Using sfd with coding agents
+
+`sfd discover` scans local Claude Code, Codex CLI and Gemini CLI transcripts for
+shell tool calls using `sf`, legacy `sfdx`, or `sfd`. It uses the hook's rewrite
+engine to report rewritable calls, skip reasons, unsupported commands and adoption.
+It reads local files only, without an org, daemon, network calls or writes.
+
+```bash
+sfd discover
+sfd discover --since 12h --agent claude --agent codex --project /path/to/project
+sfd discover --top 5 --json
+```
+
+`--since` takes days (`d`) or hours (`h`), default `30d`. `--agent` is repeatable,
+and all three agents are scanned by default. Time and output-token savings are
+estimates from observed timings and output sizes; they are never extrapolated.
+The stores read, how each call is classified, the JSON shape and the limits are
+described in [docs/discover.md](docs/discover.md).
+
+The agent reference includes metadata type discovery and member listing alongside
+query, source and log operations. Print a compact command reference with
+`sfd agents-snippet`, or add it to your project's agent instructions:
+
+```bash
+sfd agents-snippet --write
+sfd agents-snippet --write docs/CLAUDE.md
+```
+
+`--write` uses the first existing `AGENTS.md` or `CLAUDE.md` in the Salesforce
+project root (or the current directory outside a project), creating `AGENTS.md`
+if neither exists. Explicit paths resolve from the current directory. Only the
+block between `<!-- sfd:start -->` and `<!-- sfd:end -->` is replaced on later
+runs; other instructions are preserved. This command needs no org or daemon.
+The block's contents and marker rules are described in
+[docs/agents-snippet.md](docs/agents-snippet.md).
+
+For automatic command rewriting, install a hook with
+`sfd hook install --agent <agent>` (see [Agent integration](#agent-integration)).

package/bin/sfd.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync } 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 { formatMetadataTypes, formatMetadataList, formatOrgList, formatApex, formatLog, formatLogList, formatDeploy, formatTests, formatRetrieve, formatTracking, toCsv } from "../src/format.mjs";
 import { paths } from "../src/paths.mjs";
+import { commandHelp } from "../src/commands.mjs";
+import { snippet, upsertSnippet } from "../src/snippet.mjs";
 import { UsageError } from "../src/usage-error.mjs";
 
 const USAGE = `sfd ${VERSION}: fast Salesforce CLI operations through a warm local daemon
@@ -13,19 +15,7 @@ const USAGE = `sfd ${VERSION}: fast Salesforce CLI operations through a warm loc
 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
+${commandHelp()}
 
 Common options:
   -o, --target-org <alias>  Org alias or username (default: sf target-org config)
@@ -36,17 +26,33 @@ Exit codes: 0 success, 1 operation failed, 2 usage error, 3 daemon error.`;
 
 const options = {
   "target-org": { type: "string", short: "o" },
+  write: { type: "boolean" },
   json: { type: "boolean" },
   help: { type: "boolean", short: "h" },
+  folder: { type: "string" },
+  details: { type: "boolean" },
   tooling: { type: "boolean" },
+  status: { type: "boolean" },
   all: { type: "boolean" },
+  csv: { type: "boolean" },
   raw: { type: "boolean" },
   log: { type: "boolean" },
+  logs: { type: "boolean" },
+  full: { type: "boolean" },
+  "no-trace": { type: "boolean" },
+  count: { type: "string" },
+  limit: { type: "string" },
+  user: { type: "string" },
   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 },
+  manifest: { type: "string", short: "x" },
+  "ignore-conflicts": { type: "boolean" },
+  local: { type: "boolean" },
+  remote: { type: "boolean" },
+  conflicts: { type: "boolean" },
   "check-only": { type: "boolean" },
   "test-level": { type: "string", short: "l" },
   tests: { type: "string", short: "t", multiple: true },
@@ -82,6 +88,13 @@ function wait(values) {
   return minutes;
 }
 
+function queryLimit(value) {
+  if (value === undefined) return undefined;
+  const limit = Number(value);
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new UsageError("--limit must be a positive integer.");
+  return limit;
+}
+
 function print(value) {
   process.stdout.write((typeof value === "string" ? value : JSON.stringify(value, null, 2)) + "\n");
 }
@@ -91,8 +104,21 @@ async function run(argv) {
     const { runHook } = await import("../src/hooks.mjs");
     return runHook(argv.slice(1));
   }
+  if (argv[0] === "discover") {
+    const { values, positionals } = parseArgs({ args: argv.slice(1), options: {
+      since: { type: "string" }, agent: { type: "string", multiple: true },
+      project: { type: "string" }, top: { type: "string" }, json: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }, allowPositionals: true });
+    if (values.help) { print("sfd discover [--since 30d] [--agent claude|codex|gemini]… [--project <path>] [--top 10] [--json]"); return 0; }
+    if (positionals.length) throw new UsageError("discover does not accept positional arguments.");
+    const { discover, discoverOptions, formatReport } = await import("../src/discover/index.mjs");
+    const report = await discover(discoverOptions(values));
+    print(values.json ? report : formatReport(report));
+    return 0;
+  }
   const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true });
-  const [command, ...rest] = positionals;
+  let [command, ...rest] = positionals;
   if (values.help || !command) { print(USAGE); return 0; }
 
   const cwd = process.cwd();
@@ -103,6 +129,32 @@ async function run(argv) {
     return dir;
   };
 
+  if (command === "agents-snippet") {
+    if (rest.length > 1 || (rest.length && !values.write)) {
+      throw new UsageError("agents-snippet accepts --write [file].");
+    }
+    const block = snippet();
+    if (!values.write) { print(block); return 0; }
+    const root = findProjectDir(cwd) ?? cwd;
+    const file = rest[0] ?? ["AGENTS.md", "CLAUDE.md"].find(name => existsSync(resolve(root, name))) ?? "AGENTS.md";
+    const target = resolve(rest[0] ? cwd : root, file);
+    let original;
+    try { original = readFileSync(target, "utf8"); }
+    catch (e) {
+      if (e.code !== "ENOENT") throw new UsageError(`Cannot read target file ${target}: ${e.message}`);
+    }
+    let updated;
+    try { updated = upsertSnippet(original ?? "", block); }
+    catch (e) { throw new UsageError(`Malformed sfd block in ${file}: ${e.message}`); }
+    if (updated === original) print(`${file} already up to date`);
+    else {
+      try { writeFileSync(target, updated); }
+      catch (e) { throw new UsageError(`Cannot write target file ${target}: ${e.message}`); }
+      print(`${original === undefined ? "Created" : "Updated"} ${file}`);
+    }
+    return 0;
+  }
+
   // Lifecycle commands.
   switch (command) {
     case "start":
@@ -137,7 +189,9 @@ async function run(argv) {
     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 };
+      const limit = queryLimit(values.limit);
+      req = { org: org(), q, tooling: values.tooling, all: values.all, raw: values.raw, limit };
+      if (values.csv) render = result => toCsv(result.records);
       break;
     }
     case "apex": {
@@ -159,6 +213,20 @@ async function run(argv) {
       req = { org: org(), sobject: rest[0], tooling: values.tooling, raw: values.raw };
       break;
     }
+    case "list-metadata-types":
+      command = "listMetadataTypes";
+      req = { org: org() };
+      render = formatMetadataTypes;
+      break;
+    case "list-metadata": {
+      const types = [...new Set(split(values.metadata) ?? [])];
+      if (!types.length) throw new UsageError("list-metadata needs -m <Type>.");
+      if (values.folder !== undefined && types.length > 1) throw new UsageError("--folder requires exactly one metadata type.");
+      command = "listMetadata";
+      req = { org: org(), types, folder: values.folder };
+      render = result => formatMetadataList(result, { details: values.details });
+      break;
+    }
     case "deploy": {
       const dir = projectDir();
       const sourcePaths = split(values["source-dir"])?.map(d => resolve(cwd, d));
@@ -172,34 +240,87 @@ async function run(argv) {
       render = result => formatDeploy(result, req.org);
       break;
     }
+    case "retrieve": {
+      const dir = projectDir();
+      const sourcePaths = split(values["source-dir"])?.map(d => resolve(cwd, d));
+      const manifest = values.manifest ? resolve(cwd, values.manifest) : undefined;
+      for (const p of [...(sourcePaths ?? []), ...(manifest ? [manifest] : [])]) {
+        if (!existsSync(p)) throw new UsageError(`No such path: ${p}`);
+      }
+      const metadata = split(values.metadata);
+      if ([Boolean(sourcePaths?.length), Boolean(metadata?.length), Boolean(manifest)].filter(Boolean).length > 1) {
+        throw new UsageError("retrieve accepts only one of -d, -m or -x.");
+      }
+      req = { org: org(), projectDir: dir, sourcePaths, metadata, manifest,
+        ignoreConflicts: values["ignore-conflicts"], waitMinutes: wait(values) };
+      render = result => formatRetrieve(result, req.org);
+      break;
+    }
+    case "tracking":
+      if (values.local && values.remote) throw new UsageError("tracking accepts only one of --local or --remote.");
+      req = { org: org(), projectDir: projectDir(), local: values.local, remote: values.remote, conflicts: values.conflicts };
+      render = formatTracking;
+      break;
+    case "logs": {
+      if (rest[0] === "get") {
+        if (rest.length !== 2) throw new UsageError("logs get needs an ID or latest.");
+        command = "logGet";
+        req = { org: org(), id: rest[1], noTrace: values["no-trace"] };
+        render = result => values.full ? result.body : formatLog(result);
+      } else {
+        if (rest.length) throw new UsageError("logs accepts only get <id|latest>.");
+        const count = Number(values.count ?? values.limit ?? 10);
+        if (!Number.isSafeInteger(count) || count < 1) throw new UsageError("Log count must be a positive integer.");
+        req = { org: org(), count, user: values.user, noTrace: values["no-trace"] };
+        render = result => formatLogList(result.records);
+      }
+      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)
+        logs: values.logs, noTrace: values["no-trace"], testLevel: values["test-level"], codeCoverage: values["code-coverage"], waitMinutes: wait(values)
       };
       render = result => formatTests(result, req.org);
       break;
     case "org":
-      req = { org: org() };
+      if (rest[0] === "list") {
+        if (rest.length !== 1 || values["target-org"] !== undefined) throw new UsageError("org list accepts no target org or additional arguments.");
+        command = "orgList";
+        req = { all: values.all, status: values.status };
+        render = formatOrgList;
+      } else {
+        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; }
+  const trace = res.result?.trace ?? res.trace;
+  if (trace) {
+    process.stderr.write(`sfd: enabled debug logging for ${trace.username} until ${trace.expires} (TraceFlag ${trace.id})\n`);
+  }
+  if (values.json) { print(command === "orgList" && res.status === 0 ? { orgs: res.result.orgs } : res); return res.status === 0 ? okStatus(command, res.result) : res.name === "UsageError" ? 2 : 1; }
   if (res.status !== 0) {
     process.stderr.write(`${res.name}: ${res.message}\n`);
-    return 1;
+    return res.name === "UsageError" ? 2 : 1;
+  }
+  const output = render(res.result);
+  if (command !== "query" || !values.csv || output) print(output);
+  if (command === "query" && res.result.truncated) {
+    const { totalSize, records } = res.result;
+    const trailer = `… ${(totalSize - records.length).toLocaleString("en-US")} more rows not shown (totalSize ${totalSize.toLocaleString("en-US")}); raise --limit or narrow the query\n`;
+    (values.csv ? process.stderr : process.stdout).write(trailer);
   }
-  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 === "deploy" || command === "retrieve") return result.success ? 0 : 1;
   if (command === "test") return result.failing === 0 && !result.setupFailures?.length ? 0 : 1;
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/sfd",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Warm Salesforce CLI daemon: SOQL, anonymous Apex, REST, describe, deploy, and Apex tests without sf startup cost.",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "for f in bin/sfd.mjs src/*.mjs; do node --check \"$f\" || exit 1; done",
+    "build": "node scripts/check-syntax.mjs",
     "test": "node --test test/*.test.mjs"
   }
 }

package/src/client.mjs

@@ -29,7 +29,7 @@ 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
+    detached: true, windowsHide: true, stdio: ["ignore", out, out], env
   });
   child.unref();
 }
@@ -55,7 +55,7 @@ export async function call(op, args = {}, { env = process.env, autoStart = true,
     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 waitMinutes = args.waitMinutes ?? (["deploy", "retrieve"].includes(op) ? 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);