@primitivedotdev/cli 0.26.0 → 0.26.1

package/dist/oclif/commands/functions-test-function.js

@@ -0,0 +1,238 @@
+import { Command, Flags } from "@oclif/core";
+import { getEmail, PrimitiveApiClient, testFunction, } from "@primitivedotdev/sdk/api";
+import { API_BASE_URL_1_FLAG_DESCRIPTION, API_BASE_URL_2_FLAG_DESCRIPTION, baseUrlOverriddenFromFlags, extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+import { DEFAULT_EMAIL_POLL_INTERVAL_SECONDS, fetchEmailSearchPage, sleep, } from "./emails-poll.js";
+// `primitive functions:test-function` is the agent-grade shortcut for
+// triggering a real round-trip and (optionally) waiting for the
+// function to actually run before exiting. The underlying
+// `POST /functions/{id}/test` operation only kicks off a synthetic
+// inbound through MX and returns the queued send id; AGX walkthroughs
+// flagged the missing wait-and-show-sends step as the single biggest
+// time-sink in the verification loop.
+//
+// Shapes:
+//   primitive functions:test-function --id <fn-id>
+//       Fire-and-forget. Returns the TestInvocationResult JSON
+//       (recipient, poll_since, watch_url). Same behavior as the
+//       auto-generated functions:test-function it replaces.
+//
+//   primitive functions:test-function --id <fn-id> --wait
+//       Blocks until the test inbound has arrived AND the function's
+//       webhook has fired (or --timeout elapses). Exits non-zero on
+//       timeout or on exhausted retries.
+//
+//   primitive functions:test-function --id <fn-id> --wait --show-sends
+//       Same as --wait, plus prints the inbound's `replies` array
+//       (every outbound the function emitted while processing the
+//       test inbound), with each send's id, status, recipient,
+//       subject, and queue id.
+//
+// The auto-generated functions:test-function entry is filtered out
+// of the generated-command set in oclif/index.ts so this hand-rolled
+// version owns the id.
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 60;
+// Terminal states from the EmailWebhookStatus enum. `fired` means the
+// function returned 2xx; `exhausted` means all retries are spent and
+// the delivery is permanently failed. `pending` / `in_flight` /
+// `failed` are intermediate (`failed` is a temporary failure that may
+// retry into `fired` or eventually `exhausted`), so we keep polling.
+const TERMINAL_WEBHOOK_STATUSES = new Set(["fired", "exhausted"]);
+class FunctionsTestFunctionCommand extends Command {
+    static description = "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.";
+    static summary = "Trigger a test invocation; with --wait, watch it land";
+    static examples = [
+        "<%= config.bin %> functions:test-function --id <fn-id>",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize",
+        "<%= config.bin %> functions:test-function --id <fn-id> --wait --show-sends",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize --wait --timeout 120",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "api-base-url-1": Flags.string({
+            description: API_BASE_URL_1_FLAG_DESCRIPTION,
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: API_BASE_URL_2_FLAG_DESCRIPTION,
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
+        }),
+        id: Flags.string({
+            description: "Function id (UUID).",
+            required: true,
+        }),
+        "local-part": Flags.string({
+            description: "Override the synthetic local-part the test inbound is addressed to. Otherwise the runtime picks `__primitive_function_test+<random>`.",
+        }),
+        wait: Flags.boolean({
+            description: "Block until the function has processed the test inbound (webhook status is `fired` or `exhausted`) or --timeout elapses. Exits non-zero on timeout or on exhausted retries.",
+        }),
+        "show-sends": Flags.boolean({
+            description: "When the wait resolves, also print the outbound emails the function emitted while processing the test inbound (id, status, to, subject). Implies --wait.",
+        }),
+        timeout: Flags.integer({
+            default: DEFAULT_WAIT_TIMEOUT_SECONDS,
+            description: "Seconds to wait before exiting non-zero when --wait is set; 0 waits forever.",
+            min: 0,
+        }),
+        "poll-interval": Flags.integer({
+            default: DEFAULT_EMAIL_POLL_INTERVAL_SECONDS,
+            description: "Seconds between polls while waiting.",
+            min: 1,
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsTestFunctionCommand);
+        // --show-sends implies --wait. You can't print what was sent
+        // until the function has actually run.
+        const shouldWait = flags.wait || flags["show-sends"];
+        const shouldShowSends = flags["show-sends"];
+        const baseUrlOverridden = baseUrlOverriddenFromFlags(flags);
+        const auth = resolveCliAuth({
+            apiKey: flags["api-key"],
+            apiBaseUrl1: flags["api-base-url-1"],
+            apiBaseUrl2: flags["api-base-url-2"],
+            configDir: this.config.configDir,
+        });
+        const apiClient = new PrimitiveApiClient({
+            apiKey: auth.apiKey,
+            apiBaseUrl1: auth.apiBaseUrl1,
+            apiBaseUrl2: auth.apiBaseUrl2,
+        });
+        await runWithTiming(flags.time, async () => {
+            // 1. Trigger the test send.
+            const triggerResult = await testFunction({
+                client: apiClient.client,
+                path: { id: flags.id },
+                body: flags["local-part"]
+                    ? { local_part: flags["local-part"] }
+                    : undefined,
+                responseStyle: "fields",
+            });
+            if (triggerResult.error) {
+                const payload = extractErrorPayload(triggerResult.error);
+                writeErrorWithHints(payload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    auth,
+                    baseUrlOverridden,
+                    configDir: this.config.configDir,
+                    payload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            const invocation = triggerResult.data
+                .data;
+            if (!shouldWait) {
+                // Fire-and-forget path: print the TestInvocationResult JSON
+                // unchanged. Same shape the auto-generated command emitted.
+                this.log(JSON.stringify(invocation, null, 2));
+                return;
+            }
+            const startedAt = Date.now();
+            const timeoutMs = flags.timeout * 1000;
+            const pollIntervalMs = flags["poll-interval"] * 1000;
+            const isExpired = () => flags.timeout > 0 && Date.now() - startedAt > timeoutMs;
+            // 2. Wait for the test inbound to arrive. The synthetic
+            // recipient is unique per call (random suffix in the local-part
+            // unless --local-part overrides), so `to` + `since` uniquely
+            // identifies the test inbound row.
+            this.log(`Waiting for test inbound to arrive at ${invocation.to}...`);
+            let inboundId;
+            while (!isExpired()) {
+                const page = await fetchEmailSearchPage({
+                    apiClient,
+                    filters: { to: invocation.to },
+                    pageSize: 25,
+                    since: invocation.poll_since,
+                });
+                if (!page.ok) {
+                    const payload = extractErrorPayload(page.error);
+                    writeErrorWithHints(payload);
+                    removeStaleSavedCredentialOnUnauthorized({
+                        auth,
+                        baseUrlOverridden,
+                        configDir: this.config.configDir,
+                        payload,
+                    });
+                    process.exitCode = 1;
+                    return;
+                }
+                const found = page.rows[0];
+                if (found) {
+                    inboundId = found.id;
+                    break;
+                }
+                await sleep(pollIntervalMs);
+            }
+            if (!inboundId) {
+                this.error(`Timed out after ${flags.timeout}s waiting for test inbound ${invocation.to} to land. Browse ${invocation.watch_url} for the live view.`, { exit: 2 });
+            }
+            // 3. Wait for the function (webhook) to actually run. We poll
+            // the email-detail endpoint because it already carries both the
+            // webhook_status terminal state and the `replies` array we'll
+            // print under --show-sends. No second endpoint needed.
+            this.log(`Inbound landed (${inboundId}). Waiting for function to run...`);
+            let detail;
+            while (!isExpired()) {
+                const result = await getEmail({
+                    client: apiClient.client,
+                    path: { id: inboundId },
+                    responseStyle: "fields",
+                });
+                if (result.error) {
+                    const payload = extractErrorPayload(result.error);
+                    writeErrorWithHints(payload);
+                    removeStaleSavedCredentialOnUnauthorized({
+                        auth,
+                        baseUrlOverridden,
+                        configDir: this.config.configDir,
+                        payload,
+                    });
+                    process.exitCode = 1;
+                    return;
+                }
+                const fetched = result.data.data;
+                if (fetched.webhook_status &&
+                    TERMINAL_WEBHOOK_STATUSES.has(fetched.webhook_status)) {
+                    detail = fetched;
+                    break;
+                }
+                await sleep(pollIntervalMs);
+            }
+            if (!detail) {
+                this.error(`Timed out after ${flags.timeout}s waiting for function webhook to fire for inbound ${inboundId}. Browse ${invocation.watch_url} for the live view.`, { exit: 2 });
+            }
+            // 4. Emit the outcome.
+            const elapsedSeconds = Math.round((Date.now() - startedAt) / 1000);
+            const outcome = {
+                function_id: flags.id,
+                inbound_id: inboundId,
+                inbound_to: invocation.to,
+                webhook_status: detail.webhook_status,
+                webhook_attempt_count: detail.webhook_attempt_count,
+                webhook_last_status_code: detail.webhook_last_status_code,
+                webhook_last_error: detail.webhook_last_error,
+                elapsed_seconds: elapsedSeconds,
+            };
+            if (shouldShowSends) {
+                outcome.sent_emails = detail.replies;
+            }
+            this.log(JSON.stringify(outcome, null, 2));
+            // Exit non-zero when the function failed permanently so CI
+            // scripts can gate on the exit code.
+            if (detail.webhook_status === "exhausted") {
+                process.exitCode = 1;
+            }
+        });
+    }
+}
+export default FunctionsTestFunctionCommand;

package/dist/oclif/index.js

@@ -9,6 +9,7 @@ import FunctionsDeployCommand from "./commands/functions-deploy.js";
 import FunctionsInitCommand from "./commands/functions-init.js";
 import FunctionsRedeployCommand from "./commands/functions-redeploy.js";
 import FunctionsSetSecretCommand from "./commands/functions-set-secret.js";
+import FunctionsTestFunctionCommand from "./commands/functions-test-function.js";
 import LoginCommand from "./commands/login.js";
 import LogoutCommand from "./commands/logout.js";
 import SendCommand from "./commands/send.js";
@@ -108,7 +109,17 @@ class CompletionCommand extends Command {
 function commandId(operation) {
     return `${operation.tagCommand}:${operation.command}`;
 }
-const generatedCommands = Object.fromEntries(operationManifest.map((operation) => [
+// Operation ids whose surface is owned by a hand-rolled command in
+// COMMANDS below. The auto-generated wrapper is filtered out so the
+// hand-rolled command owns the id without a name collision.
+const OVERRIDDEN_OPERATION_IDS = new Set([
+    // `functions:test-function` is hand-rolled to add --wait, --show-sends,
+    // and --timeout flags on top of the auto-generated POST /functions/{id}/test.
+    "functions:test-function",
+]);
+const generatedCommands = Object.fromEntries(operationManifest
+    .filter((operation) => !OVERRIDDEN_OPERATION_IDS.has(commandId(operation)))
+    .map((operation) => [
     commandId(operation),
     createOperationCommand(operation),
 ]));
@@ -171,5 +182,12 @@ export const COMMANDS = {
     // visible to the running handler requires a separate redeploy,
     // which this shortcut folds in via --redeploy.
     "functions:set-secret": FunctionsSetSecretCommand,
+    // `functions:test-function` is hand-rolled to add --wait, --show-sends,
+    // and --timeout on top of POST /functions/{id}/test. Without those
+    // flags, agents had to manually thread queued-send + emails:wait +
+    // emails:get-email + sending:list-sent-emails to verify a function
+    // ran and see what it emitted; AGX walkthroughs flagged that loop as
+    // the single biggest verification time-sink.
+    "functions:test-function": FunctionsTestFunctionCommand,
     ...generatedCommands,
 };

package/oclif.manifest.json

@@ -1036,6 +1036,103 @@
       "summary": "Write a function secret (optionally redeploying to push it live)",
       "enableJsonFlag": false
     },
+    "functions:test-function": {
+      "aliases": [],
+      "args": {},
+      "description": "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.",
+      "examples": [
+        "<%= config.bin %> functions:test-function --id <fn-id>",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize",
+        "<%= config.bin %> functions:test-function --id <fn-id> --wait --show-sends",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize --wait --timeout 120"
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-1": {
+          "description": "Override the primary API base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_1",
+          "hidden": true,
+          "name": "api-base-url-1",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-2": {
+          "description": "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_2",
+          "hidden": true,
+          "name": "api-base-url-2",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "id": {
+          "description": "Function id (UUID).",
+          "name": "id",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "local-part": {
+          "description": "Override the synthetic local-part the test inbound is addressed to. Otherwise the runtime picks `__primitive_function_test+<random>`.",
+          "name": "local-part",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Block until the function has processed the test inbound (webhook status is `fired` or `exhausted`) or --timeout elapses. Exits non-zero on timeout or on exhausted retries.",
+          "name": "wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "show-sends": {
+          "description": "When the wait resolves, also print the outbound emails the function emitted while processing the test inbound (id, status, to, subject). Implies --wait.",
+          "name": "show-sends",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Seconds to wait before exiting non-zero when --wait is set; 0 waits forever.",
+          "name": "timeout",
+          "default": 60,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "poll-interval": {
+          "description": "Seconds between polls while waiting.",
+          "name": "poll-interval",
+          "default": 2,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "functions:test-function",
+      "pluginAlias": "@primitivedotdev/cli",
+      "pluginName": "@primitivedotdev/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Trigger a test invocation; with --wait, watch it land",
+      "enableJsonFlag": false
+    },
     "account:get-account": {
       "aliases": [],
       "args": {},
@@ -3624,83 +3721,6 @@
       "summary": "Set a secret by key",
       "enableJsonFlag": false
     },
-    "functions:test-function": {
-      "aliases": [],
-      "args": {},
-      "description": "Sends a real test email from a Primitive-controlled sender to a\nlocal-part on one of the org's verified inbound domains. By\ndefault the recipient is a synthetic\n`__primitive_function_test+<random>@<domain>` address that\nevery handler's catch-all routing receives identically; pass\n`local_part` to override and exercise routing logic that\nbranches on a specific recipient (the common pattern when one\nfunction handles multiple inboxes like `summarize@` and\n`action@`). The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\nReturns 400 if `local_part` is set to a value that does not\nmatch the local-part character set.\n",
-      "flags": {
-        "api-key": {
-          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
-          "env": "PRIMITIVE_API_KEY",
-          "name": "api-key",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-base-url-1": {
-          "description": "Override the primary API base URL. Internal testing only; not documented to customers.",
-          "env": "PRIMITIVE_API_BASE_URL_1",
-          "hidden": true,
-          "name": "api-base-url-1",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-base-url-2": {
-          "description": "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
-          "env": "PRIMITIVE_API_BASE_URL_2",
-          "hidden": true,
-          "name": "api-base-url-2",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "time": {
-          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
-          "name": "time",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "id": {
-          "description": "Resource UUID",
-          "name": "id",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "raw-body": {
-          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
-          "name": "raw-body",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "body-file": {
-          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
-          "name": "body-file",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "local-part": {
-          "description": "Override the synthetic local-part. When set, the test email is sent to `<local_part>@<picked-domain>` instead of the default `__primitive_function_test+<random>@<picked-domain>`. Must start with an alphanumeric and contain only letters, digits, dots, plus signs, hyphens, or underscores; 1-64 characters total.",
-          "name": "local-part",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "functions:test-function",
-      "pluginAlias": "@primitivedotdev/cli",
-      "pluginName": "@primitivedotdev/cli",
-      "pluginType": "core",
-      "strict": true,
-      "summary": "Send a test invocation",
-      "enableJsonFlag": false
-    },
     "functions:update-function": {
       "aliases": [],
       "args": {},
@@ -4366,5 +4386,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.26.0"
+  "version": "0.26.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "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,
@@ -35,7 +35,7 @@
         "description": "Claim, verify, and manage email domains"
       },
       "emails": {
-        "description": "List, inspect, and manage received emails. Use `primitive emails:latest` for a one-line-per-email summary of recent inbound mail."
+        "description": "List, inspect, and wait for received emails. `primitive emails:latest` lists the most recent inbound, `primitive emails:wait` blocks until matching inbound arrives (filter with --to/--from/--subject/--q; bounded by --timeout and --number; ideal for agents and CI), and `primitive emails:watch` streams new matches indefinitely for long-running terminals."
       },
       "sending": {
         "description": "Send outbound emails. For replies to inbound mail, use `sending:reply-to-email --id <inbound-id>` (threading and Re: subject derived server-side); for fresh sends, use `sending:send-email` or the `primitive send` shortcut."