@primitivedotdev/cli 0.25.2 → 0.26.0

package/bin/run.js

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
 
 import { execute } from "@oclif/core";
+import { applyProxyAutoDetect } from "../dist/oclif/proxy-auto-detect.js";
+
+// Auto-set NODE_USE_ENV_PROXY=1 when HTTP(S)_PROXY is in the env.
+// Must run before any network init (e.g. before oclif loads commands
+// that touch fetch). See proxy-auto-detect.ts for the full rationale.
+applyProxyAutoDetect();
 
 await execute({ dir: import.meta.url });

package/dist/oclif/api-command.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { Command, Errors, Flags } from "@oclif/core";
 import { operations, PrimitiveApiClient } from "@primitivedotdev/sdk/api";
 import { deleteCliCredentials, resolveCliAuth, } from "./auth.js";
+import { maybeWriteFunctionEndpointRedirect, } from "./endpoints-test-redirect.js";
 export const API_ERROR_CODES = {
     accessDenied: "access_denied",
     authorizationPending: "authorization_pending",
@@ -722,6 +723,29 @@ export function createOperationCommand(operation) {
                         configDir: this.config.configDir,
                         payload: errorPayload,
                     });
+                    // Function-endpoint redirect. POST /endpoints/{id}/test on a
+                    // function-kind endpoint returns `not_found` even though the
+                    // same id IS visible in `endpoints:list-endpoints`. The hook
+                    // looks the id up via listEndpoints; if it matches a
+                    // function-kind row, it prints a redirect to
+                    // `functions:test-function` (with the function id) so the
+                    // caller does not have to translate the id themselves.
+                    // No-op for any other operation, any other error code, or
+                    // when the lookup misses or fails.
+                    const listClient = apiClient.client;
+                    const listEndpointsFn = () => operations.listEndpoints({
+                        client: listClient,
+                        responseStyle: "fields",
+                    });
+                    await maybeWriteFunctionEndpointRedirect({
+                        sdkName: operation.sdkName,
+                        errorCode: extractErrorCode(errorPayload),
+                        endpointId: typeof parsedFlags.id === "string" ? parsedFlags.id : undefined,
+                        listEndpoints: listEndpointsFn,
+                        writeStderr: (chunk) => {
+                            process.stderr.write(chunk);
+                        },
+                    });
                     process.exitCode = 1;
                     return;
                 }

package/dist/oclif/commands/functions-init.js

@@ -29,7 +29,7 @@ const SDK_VERSION_RANGE = "^0.25.0";
 // resolves at least v1.2.3, so the user does not silently downgrade
 // the bin under themselves. The lockstep test in functions-init.test.ts
 // enforces that invariant.
-const CLI_VERSION_RANGE = "^0.25.0";
+const CLI_VERSION_RANGE = "^0.26.0";
 // esbuild version range. Pinned to the latest stable major used
 // elsewhere in the Primitive codebase for bundling Workers-style
 // handlers. Caret range so patch fixes flow in automatically.
@@ -52,9 +52,11 @@ export function renderHandler() {
 import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
 
 // TODO: replace with your verified sender address. Must be a domain
-// you own or your managed *.primitive.email subdomain. The
-// self-reply guard below compares incoming mail against this value
-// to avoid the handler replying to its own outbound traffic.
+// you own or your managed *.primitive.email subdomain. The isLoop
+// guard below compares incoming mail against this value (in addition
+// to the *.primitive.email suffix) so the handler does not reply to
+// its own outbound traffic when REPLY_FROM is on a non-managed
+// domain.
 const REPLY_FROM = "you@your-domain.primitive.email";
 
 interface EmailReceivedEvent {
@@ -64,6 +66,45 @@ interface EmailReceivedEvent {
   };
 }
 
+// Loop protection. A deployed Function receives catch-all inbound for
+// the managed *.primitive.email subdomain, which includes bounces and
+// auto-replies generated by its own outbound traffic. Without this
+// guard the handler can respond to its own bounces and create a
+// fan-out loop.
+//
+// The default check returns true when From is on any *.primitive.email
+// address (covers the managed subdomain catch-all, the simple
+// self-reply case, and bounces from mailer-daemon@*.primitive.email)
+// or when From contains REPLY_FROM as a case-insensitive substring.
+// Substring matching is deliberate so display-name forms like
+// "Support <support@example.com>" match a bare-address REPLY_FROM,
+// but it also accepts false positives where REPLY_FROM is a suffix
+// of another address (e.g. REPLY_FROM="info@x.com" matches
+// "mr.info@x.com"). For strict equality, parse the address out of the
+// header and exact-match against REPLY_FROM.
+//
+// Extend this helper if you need stricter detection. Common additions:
+//   - Match the org's signup / account-owner email (not auto-injected
+//     into env today; either bake it into a SIGNUP_EMAIL const or read
+//     it from a secret you set via \`primitive functions:set-secret\`).
+//   - Honor RFC 3834 auto-response headers: skip when
+//     \`event.email.headers["auto-submitted"]\` is anything other than
+//     "no", or when a \`List-Unsubscribe\` / \`Precedence: bulk\` header
+//     is present.
+//   - Track Message-ID / In-Reply-To chains to break ping-pong loops
+//     between two cooperating handlers on different domains.
+export function isLoop(event: EmailReceivedEvent): boolean {
+  // event.email.headers.from is the raw RFC 2822 header value, so it
+  // may be a bare address ("alice@example.com") or a display-name form
+  // ("Alice <alice@example.com>"). Lowercase substring checks match
+  // both shapes without needing to parse the bracketed address.
+  const from = event.email.headers.from?.toLowerCase() ?? "";
+  if (!from) return false;
+  if (from.includes(".primitive.email")) return true;
+  if (from.includes(REPLY_FROM.toLowerCase())) return true;
+  return false;
+}
+
 export default {
   async fetch(
     req: Request,
@@ -80,18 +121,12 @@ export default {
         return Response.json({ ok: true, skipped: event.event });
       }
 
-      // Self-reply guard: do not act on mail that this function itself
-      // sent. Without this, an outbound reply that gets forwarded back
-      // into the inbox would trigger another reply, and so on.
-      //
-      // event.email.headers.from is the raw RFC 2822 header value, so
-      // it may be either a bare address ("alice@example.com") or a
-      // display-name form ("Alice <alice@example.com>"). A substring
-      // check matches both. Tighten this predicate (e.g. parse the
-      // bracketed address) if you legitimately want to act on mail
-      // from your own domain.
-      if (event.email.headers.from?.includes(REPLY_FROM)) {
-        return Response.json({ ok: true, skipped: "self-reply" });
+      // Loop protection runs immediately after the event-type check
+      // (the gateway has already HMAC-verified the request before it
+      // reaches this handler). See isLoop above for what's covered and
+      // how to extend it.
+      if (isLoop(event)) {
+        return Response.json({ ok: true, skipped: "loop" });
       }
 
       const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });

package/dist/oclif/endpoints-test-redirect.js

@@ -0,0 +1,94 @@
+// `endpoints:test-endpoint` calls POST /endpoints/{id}/test. The server
+// implementation only resolves http-kind endpoints by url and returns
+// `not_found` for function-kind endpoints (where url is null). The same
+// function-endpoint id IS returned by `endpoints:list-endpoints`, so a
+// caller naturally tries it against test-endpoint and is greeted with
+// "Endpoint not found." Confusing.
+//
+// This helper closes the loop on the CLI side. After test-endpoint
+// returns `not_found`, the dispatcher in `api-command.ts` calls
+// `detectFunctionEndpoint` to see whether the id actually belongs to a
+// function-kind endpoint owned by the caller. If yes, we replace the
+// generic envelope with a redirect to `functions:test-function`,
+// surfacing both the endpoint id and the function id so the caller
+// does not have to look the function id up themselves.
+//
+// `kind` and `function_id` are not currently declared on the OpenAPI
+// `Endpoint` schema (so they are absent from the generated TS types),
+// but they are present in the JSON the server returns. We read them
+// off a loose Record<string, unknown> rather than relying on the
+// generated type, then sanity-check both fields before treating an
+// endpoint as a function endpoint.
+// Returns a `FunctionEndpointMatch` if and only if `endpointId` matches
+// an endpoint in the caller's `listEndpoints` response whose `kind` is
+// `function` and whose `function_id` is a non-empty string. Any other
+// outcome (no match, http-kind match, list call failure, missing
+// fields) returns `null` so the dispatcher falls back to surfacing the
+// original error envelope unchanged.
+export async function detectFunctionEndpoint(endpointId, listEndpoints) {
+    let response;
+    try {
+        response = await listEndpoints();
+    }
+    catch {
+        return null;
+    }
+    if (response.error)
+        return null;
+    const rows = response.data?.data;
+    if (!Array.isArray(rows))
+        return null;
+    // Relies on `listEndpoints` returning every endpoint in a single response.
+    // True today: the operation has `query?: never` in the generated types and
+    // the server returns all rows. If pagination is ever added, an endpoint on
+    // a later page would silently miss the redirect and reduce this to the
+    // original "Endpoint not found" UX. Update this call (filter-by-id or
+    // exhaust-pages) at the same time pagination lands on listEndpoints.
+    for (const row of rows) {
+        if (!row || typeof row !== "object")
+            continue;
+        if (row.id !== endpointId)
+            continue;
+        if (row.kind !== "function")
+            return null;
+        const functionId = row.function_id;
+        if (typeof functionId !== "string" || functionId.length === 0)
+            return null;
+        return { endpointId, functionId };
+    }
+    return null;
+}
+// Stderr copy printed when the dispatcher detects the
+// `endpoints:test-endpoint` `not_found` was really a function-kind
+// endpoint. Surfaces both ids so the caller does not have to run
+// `endpoints:list-endpoints` again to find the function_id. Returned
+// as a string rather than written here so the call site controls the
+// stream (stderr, in practice) and the tests can assert on the value.
+export function formatFunctionEndpointRedirect(match) {
+    return [
+        "This is a function endpoint. Function endpoints are tested differently. Run:",
+        "",
+        `    primitive functions:test-function --id ${match.functionId}`,
+        "",
+        `(pass the function id, not the endpoint id. endpoint_id=${match.endpointId} function_id=${match.functionId})`,
+    ].join("\n");
+}
+// Post-error hook: if the operation that just failed is
+// `endpoints:test-endpoint`, the failure is a `not_found`, and the
+// caller's id matches a function-kind endpoint they own, print a
+// redirect to `functions:test-function`. Returns the resolved match
+// so the caller (and the test) can assert the branch taken without
+// scraping stderr.
+export async function maybeWriteFunctionEndpointRedirect(inputs) {
+    if (inputs.sdkName !== "testEndpoint")
+        return null;
+    if (inputs.errorCode !== "not_found")
+        return null;
+    if (!inputs.endpointId)
+        return null;
+    const match = await detectFunctionEndpoint(inputs.endpointId, inputs.listEndpoints);
+    if (!match)
+        return null;
+    inputs.writeStderr(`${formatFunctionEndpointRedirect(match)}\n`);
+    return match;
+}

package/dist/oclif/proxy-auto-detect.js

@@ -0,0 +1,64 @@
+// Auto-detect proxy environment variables at CLI startup so users
+// behind a corporate proxy don't have to prefix every command with
+// `NODE_USE_ENV_PROXY=1`.
+//
+// Node 22+ ignores `HTTP_PROXY` / `HTTPS_PROXY` for the built-in
+// `fetch` / undici client unless `NODE_USE_ENV_PROXY=1` is set. That
+// turns a one-line proxy export into per-command friction: every CLI
+// invocation either inherits the prefix or fails with `ENETUNREACH`.
+//
+// This module is called once from `bin/run.js` before any network
+// initialization. If any of the standard proxy env vars are set AND
+// `NODE_USE_ENV_PROXY` is not already set explicitly, it sets it to
+// `1` for the current process and prints a one-time stderr hint so
+// the user knows what changed.
+//
+// An explicit `NODE_USE_ENV_PROXY` value (including `0`, `""`, etc.)
+// is always respected: if the user has chosen to disable proxy use
+// for this invocation, we don't override that choice.
+const PROXY_ENV_VARS = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "http_proxy",
+    "https_proxy",
+];
+// Module-level latch so the hint is printed at most once per process
+// even if `applyProxyAutoDetect` is called more than once (e.g. from
+// tests, or if a future entry point routes through it twice).
+let hintPrinted = false;
+// Test-only: reset the one-shot hint latch so each test case can
+// observe the first-call behavior independently.
+export function _resetHintLatchForTest() {
+    hintPrinted = false;
+}
+function detectProxyVars(env) {
+    return PROXY_ENV_VARS.filter((name) => {
+        const value = env[name];
+        return typeof value === "string" && value.length > 0;
+    });
+}
+export function applyProxyAutoDetect(options = {}) {
+    const env = options.env ?? process.env;
+    const stderr = options.stderr ?? process.stderr;
+    const detectedVars = detectProxyVars(env);
+    if (detectedVars.length === 0) {
+        return { applied: false, detectedVars: [], reason: "no_proxy_env" };
+    }
+    // Respect any explicit `NODE_USE_ENV_PROXY` value, including `0`
+    // or an empty string. The user has made a deliberate choice and
+    // auto-detection must not silently override it.
+    if (Object.hasOwn(env, "NODE_USE_ENV_PROXY")) {
+        return {
+            applied: false,
+            detectedVars,
+            reason: "node_use_env_proxy_already_set",
+        };
+    }
+    env.NODE_USE_ENV_PROXY = "1";
+    if (!hintPrinted) {
+        hintPrinted = true;
+        const names = detectedVars.join("/");
+        stderr.write(`primitive: proxy detected via ${names}, NODE_USE_ENV_PROXY=1 set automatically\n`);
+    }
+    return { applied: true, detectedVars, reason: "applied" };
+}

package/oclif.manifest.json

@@ -4366,5 +4366,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.25.2"
+  "version": "0.26.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.25.2",
+  "version": "0.26.0",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,