@primitivedotdev/cli 0.28.0 → 0.29.0

package/dist/oclif/index.js

@@ -649,6 +649,7 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	getAccount: () => getAccount,
 	getEmail: () => getEmail,
 	getFunction: () => getFunction,
+	getFunctionTestRunTrace: () => getFunctionTestRunTrace,
 	getSendPermissions: () => getSendPermissions,
 	getSentEmail: () => getSentEmail,
 	getStorageStats: () => getStorageStats,
@@ -1635,6 +1636,24 @@ const testFunction = (options) => (options.client ?? client).post({
 	}
 });
 /**
+* Get a function test run trace
+*
+* Returns the current end-to-end trace for a function test run.
+* The trace is intentionally partial while the test is still in
+* flight: callers can poll this endpoint and watch it fill in
+* from send -> inbound -> webhook deliveries -> outbound
+* requests, logs, and replies.
+*
+*/
+const getFunctionTestRunTrace = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/{id}/test-runs/{run_id}/trace",
+	...options
+});
+/**
 * List a function's secrets
 *
 * Returns metadata for every secret bound to the function, with
@@ -3294,6 +3313,37 @@ const openapiDocument = {
 				}
 			}
 		},
+		"/functions/{id}/test-runs/{run_id}/trace": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }, {
+				"name": "run_id",
+				"in": "path",
+				"required": true,
+				"description": "Function test run id returned by POST /functions/{id}/test.",
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			}],
+			"get": {
+				"operationId": "getFunctionTestRunTrace",
+				"summary": "Get a function test run trace",
+				"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+				"tags": ["Functions"],
+				"responses": {
+					"200": {
+						"description": "Function test run trace",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "$ref": "#/components/schemas/FunctionTestRunTrace" } }
+						}] } } }
+					},
+					"400": { "$ref": "#/components/responses/ValidationError" },
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"403": { "$ref": "#/components/responses/Forbidden" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
 		"/functions/{id}/secrets": {
 			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
 			"get": {
@@ -5594,8 +5644,13 @@ const openapiDocument = {
 			},
 			"TestInvocationResult": {
 				"type": "object",
-				"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; the actual invocation lands on the function's\ninvocations list a few seconds later as the inbound mail\ntraverses the MX path.\n",
+				"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; poll `trace_url` to watch the run progress through\nsend -> inbound -> webhook deliveries -> outbound requests,\nlogs, and replies.\n",
 				"properties": {
+					"test_run_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "Durable test run id used to fetch the run trace."
+					},
 					"inbound_domain": {
 						"type": "string",
 						"description": "Verified inbound domain the test email was sent to."
@@ -5625,16 +5680,339 @@ const openapiDocument = {
 						"type": "string",
 						"format": "uri",
 						"description": "Function detail page where invocations show up live."
+					},
+					"trace_url": {
+						"type": "string",
+						"description": "Relative API URL for GET /functions/{id}/test-runs/{test_run_id}/trace."
 					}
 				},
 				"required": [
+					"test_run_id",
 					"inbound_domain",
 					"to",
 					"from",
 					"send_id",
 					"subject",
 					"poll_since",
-					"watch_url"
+					"watch_url",
+					"trace_url"
+				]
+			},
+			"FunctionTestRunState": {
+				"type": "string",
+				"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
+				"enum": [
+					"send_failed",
+					"waiting_for_send",
+					"waiting_for_inbound",
+					"waiting_for_function",
+					"completed",
+					"failed"
+				]
+			},
+			"FunctionTestRun": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"function_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"inbound_domain": { "type": "string" },
+					"to": { "type": "string" },
+					"from": { "type": "string" },
+					"subject": { "type": "string" },
+					"poll_since": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"sent_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"send_error": { "type": ["string", "null"] }
+				},
+				"required": [
+					"id",
+					"function_id",
+					"inbound_domain",
+					"to",
+					"from",
+					"subject",
+					"poll_since",
+					"created_at",
+					"sent_at",
+					"send_error"
+				]
+			},
+			"FunctionTestRunSend": {
+				"type": ["object", "null"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"status": { "$ref": "#/components/schemas/SentEmailStatus" },
+					"queue_id": { "type": ["string", "null"] },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"updated_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"id",
+					"status",
+					"queue_id",
+					"created_at",
+					"updated_at"
+				]
+			},
+			"FunctionTestRunInboundEmail": {
+				"type": ["object", "null"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"status": { "$ref": "#/components/schemas/EmailStatus" },
+					"received_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"from": { "type": "string" },
+					"to": { "type": "string" },
+					"subject": { "type": ["string", "null"] },
+					"webhook_status": { "$ref": "#/components/schemas/EmailWebhookStatus" },
+					"webhook_attempt_count": { "type": "integer" },
+					"webhook_last_status_code": { "type": ["integer", "null"] },
+					"webhook_last_error": { "type": ["string", "null"] }
+				},
+				"required": [
+					"id",
+					"status",
+					"received_at",
+					"from",
+					"to",
+					"subject",
+					"webhook_status",
+					"webhook_attempt_count",
+					"webhook_last_status_code",
+					"webhook_last_error"
+				]
+			},
+			"FunctionTestRunDeliveryEndpoint": {
+				"type": ["object", "null"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": {
+						"type": "string",
+						"description": "Endpoint kind. Current traces may include `http` or `function`; future endpoint kinds may appear."
+					},
+					"function_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"function_name": { "type": ["string", "null"] },
+					"domain_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"enabled": { "type": "boolean" },
+					"deactivated_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"is_current_function": { "type": "boolean" }
+				},
+				"required": [
+					"id",
+					"kind",
+					"function_id",
+					"function_name",
+					"domain_id",
+					"enabled",
+					"deactivated_at",
+					"is_current_function"
+				]
+			},
+			"FunctionTestRunDelivery": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"description": "Webhook delivery id."
+					},
+					"endpoint_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"endpoint_url": {
+						"type": "string",
+						"format": "uri"
+					},
+					"status": {
+						"type": "string",
+						"enum": [
+							"pending",
+							"delivered",
+							"header_confirmed",
+							"failed"
+						]
+					},
+					"attempt_count": { "type": "integer" },
+					"duration_ms": { "type": ["integer", "null"] },
+					"last_error": { "type": ["string", "null"] },
+					"last_error_code": { "type": ["string", "null"] },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"updated_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"endpoint": { "$ref": "#/components/schemas/FunctionTestRunDeliveryEndpoint" }
+				},
+				"required": [
+					"id",
+					"endpoint_id",
+					"endpoint_url",
+					"status",
+					"attempt_count",
+					"duration_ms",
+					"last_error",
+					"last_error_code",
+					"created_at",
+					"updated_at",
+					"endpoint"
+				]
+			},
+			"FunctionTestRunOutboundRequest": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"function_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"webhook_delivery_id": { "type": ["string", "null"] },
+					"email_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"endpoint_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"method": { "type": "string" },
+					"url": {
+						"type": "string",
+						"format": "uri"
+					},
+					"host": { "type": "string" },
+					"path": { "type": "string" },
+					"status_code": { "type": ["integer", "null"] },
+					"ok": { "type": ["boolean", "null"] },
+					"duration_ms": { "type": "integer" },
+					"error": { "type": ["string", "null"] },
+					"ts": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"id",
+					"function_id",
+					"webhook_delivery_id",
+					"email_id",
+					"endpoint_id",
+					"method",
+					"url",
+					"host",
+					"path",
+					"status_code",
+					"ok",
+					"duration_ms",
+					"error",
+					"ts"
+				]
+			},
+			"FunctionTestRunReply": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"status": { "$ref": "#/components/schemas/SentEmailStatus" },
+					"to": { "type": "string" },
+					"subject": { "type": "string" },
+					"queue_id": { "type": ["string", "null"] },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"id",
+					"status",
+					"to",
+					"subject",
+					"queue_id",
+					"created_at"
+				]
+			},
+			"FunctionTestRunTrace": {
+				"type": "object",
+				"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+				"properties": {
+					"state": { "$ref": "#/components/schemas/FunctionTestRunState" },
+					"test_run": { "$ref": "#/components/schemas/FunctionTestRun" },
+					"test_send": { "$ref": "#/components/schemas/FunctionTestRunSend" },
+					"inbound_email": { "$ref": "#/components/schemas/FunctionTestRunInboundEmail" },
+					"deliveries": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionTestRunDelivery" }
+					},
+					"outbound_requests": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionTestRunOutboundRequest" }
+					},
+					"logs": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionLogRow" }
+					},
+					"replies": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionTestRunReply" }
+					}
+				},
+				"required": [
+					"state",
+					"test_run",
+					"test_send",
+					"inbound_email",
+					"deliveries",
+					"outbound_requests",
+					"logs",
+					"replies"
 				]
 			},
 			"FunctionLogRow": {
@@ -8266,23 +8644,456 @@ const operationManifest = [
 					"type": "string",
 					"format": "date-time"
 				},
-				"updated_at": {
-					"type": "string",
-					"format": "date-time"
+				"updated_at": {
+					"type": "string",
+					"format": "date-time"
+				}
+			},
+			"required": [
+				"id",
+				"name",
+				"code",
+				"deploy_status",
+				"gateway_url",
+				"created_at",
+				"updated_at"
+			]
+		},
+		"sdkName": "getFunction",
+		"summary": "Get a function",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-function-test-run-trace",
+		"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getFunctionTestRunTrace",
+		"path": "/functions/{id}/test-runs/{run_id}/trace",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}, {
+			"description": "Function test run id returned by POST /functions/{id}/test.",
+			"enum": null,
+			"name": "run_id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+			"properties": {
+				"state": {
+					"type": "string",
+					"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
+					"enum": [
+						"send_failed",
+						"waiting_for_send",
+						"waiting_for_inbound",
+						"waiting_for_function",
+						"completed",
+						"failed"
+					]
+				},
+				"test_run": {
+					"type": "object",
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"function_id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"inbound_domain": { "type": "string" },
+						"to": { "type": "string" },
+						"from": { "type": "string" },
+						"subject": { "type": "string" },
+						"poll_since": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"created_at": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"sent_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						},
+						"send_error": { "type": ["string", "null"] }
+					},
+					"required": [
+						"id",
+						"function_id",
+						"inbound_domain",
+						"to",
+						"from",
+						"subject",
+						"poll_since",
+						"created_at",
+						"sent_at",
+						"send_error"
+					]
+				},
+				"test_send": {
+					"type": ["object", "null"],
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"status": {
+							"type": "string",
+							"description": "Lifecycle status of a sent_emails row. Possible values:\n\n  - `queued`: pre-call INSERT; the outbound agent has not\n    yet replied.\n  - `submitted_to_agent`: agent accepted; `queue_id` is set.\n  - `agent_failed`: agent rejected; `error_code` and\n    `error_message` carry the reason.\n  - `gate_denied`: a recipient-scope gate denied the send;\n    the agent was never called. The `gates` array carries\n    the denial detail. /send-mail returns 403 in this case\n    so callers see the denial synchronously; /sent-emails\n    additionally records the row for historical lookup,\n    which is when this status appears in a listing.\n  - `unknown`: terminal indeterminate; the on-box log\n    poller couldn't classify the receiver's response.\n  - `delivered` / `bounced` / `deferred` / `wait_timeout`:\n    terminal delivery outcomes (see DeliveryStatus).\n",
+							"enum": [
+								"queued",
+								"submitted_to_agent",
+								"agent_failed",
+								"gate_denied",
+								"unknown",
+								"delivered",
+								"bounced",
+								"deferred",
+								"wait_timeout"
+							]
+						},
+						"queue_id": { "type": ["string", "null"] },
+						"created_at": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"updated_at": {
+							"type": "string",
+							"format": "date-time"
+						}
+					},
+					"required": [
+						"id",
+						"status",
+						"queue_id",
+						"created_at",
+						"updated_at"
+					]
+				},
+				"inbound_email": {
+					"type": ["object", "null"],
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"status": {
+							"type": "string",
+							"description": "Lifecycle status of an INBOUND email (a row in the `emails`\ntable). Distinct from `SentEmailStatus`, which describes\nthe OUTBOUND lifecycle (the `sent_emails` table) and uses\na different vocabulary because the lifecycles differ.\nPossible values:\n\n  - `pending`: the row was inserted at ingestion (mx_main)\n    and has not yet completed the spam / filter / auth\n    pipeline. Body and parsed fields are present; webhook\n    delivery is not yet scheduled. Most rows transition out\n    of `pending` within seconds.\n  - `accepted`: the inbound passed the policy gates and is\n    queued for webhook delivery. The `webhook_status` field\n    tracks the separate webhook-delivery lifecycle from\n    this point.\n  - `completed`: terminal success. Webhook delivery\n    attempted and acknowledged by every active endpoint, OR\n    no endpoints are configured, so the row is durably\n    archived.\n  - `rejected`: terminal failure at ingestion (spam, blocked\n    sender, filter rule, malformed). The body and metadata\n    are stored for auditing but no webhook fires and the\n    row is not repliable.\n\nSee also `webhook_status` (separate enum tracking the\nwebhook-delivery state machine) and `SentEmailStatus` (the\noutbound vocabulary).\n",
+							"enum": [
+								"pending",
+								"accepted",
+								"completed",
+								"rejected"
+							]
+						},
+						"received_at": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"from": { "type": "string" },
+						"to": { "type": "string" },
+						"subject": { "type": ["string", "null"] },
+						"webhook_status": {
+							"type": ["string", "null"],
+							"description": "Webhook-delivery state for an inbound email. Tracks a\nSEPARATE lifecycle from the email's `status` field; the\nsame row carries both. Possible values:\n\n  - `pending`: ingestion is past `pending` (the email itself\n    is `accepted`) but the webhook fan-out has not yet\n    started for this row.\n  - `in_flight`: at least one delivery attempt is in flight.\n  - `fired`: terminal success. Every active endpoint\n    acknowledged the delivery (or accepted it after retries).\n  - `failed`: terminal partial-failure. At least one endpoint\n    exhausted its retry budget; some endpoints may still\n    have succeeded.\n  - `exhausted`: terminal failure. Every endpoint exhausted\n    its retry budget without success.\n  - `null`: no endpoints configured, so no webhook lifecycle\n    applies.\n\nNote that the value `pending` here does NOT mean the email\nis `pending`; it means the email is past ingestion but\nwebhook delivery has not yet begun. Two overlapping uses\nof the word `pending` for distinct lifecycle phases.\n",
+							"enum": [
+								"pending",
+								"in_flight",
+								"fired",
+								"failed",
+								"exhausted",
+								null
+							]
+						},
+						"webhook_attempt_count": { "type": "integer" },
+						"webhook_last_status_code": { "type": ["integer", "null"] },
+						"webhook_last_error": { "type": ["string", "null"] }
+					},
+					"required": [
+						"id",
+						"status",
+						"received_at",
+						"from",
+						"to",
+						"subject",
+						"webhook_status",
+						"webhook_attempt_count",
+						"webhook_last_status_code",
+						"webhook_last_error"
+					]
+				},
+				"deliveries": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"description": "Webhook delivery id."
+							},
+							"endpoint_id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"endpoint_url": {
+								"type": "string",
+								"format": "uri"
+							},
+							"status": {
+								"type": "string",
+								"enum": [
+									"pending",
+									"delivered",
+									"header_confirmed",
+									"failed"
+								]
+							},
+							"attempt_count": { "type": "integer" },
+							"duration_ms": { "type": ["integer", "null"] },
+							"last_error": { "type": ["string", "null"] },
+							"last_error_code": { "type": ["string", "null"] },
+							"created_at": {
+								"type": "string",
+								"format": "date-time"
+							},
+							"updated_at": {
+								"type": "string",
+								"format": "date-time"
+							},
+							"endpoint": {
+								"type": ["object", "null"],
+								"properties": {
+									"id": {
+										"type": "string",
+										"format": "uuid"
+									},
+									"kind": {
+										"type": "string",
+										"description": "Endpoint kind. Current traces may include `http` or `function`; future endpoint kinds may appear."
+									},
+									"function_id": {
+										"type": ["string", "null"],
+										"format": "uuid"
+									},
+									"function_name": { "type": ["string", "null"] },
+									"domain_id": {
+										"type": ["string", "null"],
+										"format": "uuid"
+									},
+									"enabled": { "type": "boolean" },
+									"deactivated_at": {
+										"type": ["string", "null"],
+										"format": "date-time"
+									},
+									"is_current_function": { "type": "boolean" }
+								},
+								"required": [
+									"id",
+									"kind",
+									"function_id",
+									"function_name",
+									"domain_id",
+									"enabled",
+									"deactivated_at",
+									"is_current_function"
+								]
+							}
+						},
+						"required": [
+							"id",
+							"endpoint_id",
+							"endpoint_url",
+							"status",
+							"attempt_count",
+							"duration_ms",
+							"last_error",
+							"last_error_code",
+							"created_at",
+							"updated_at",
+							"endpoint"
+						]
+					}
+				},
+				"outbound_requests": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"function_id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"webhook_delivery_id": { "type": ["string", "null"] },
+							"email_id": {
+								"type": ["string", "null"],
+								"format": "uuid"
+							},
+							"endpoint_id": {
+								"type": ["string", "null"],
+								"format": "uuid"
+							},
+							"method": { "type": "string" },
+							"url": {
+								"type": "string",
+								"format": "uri"
+							},
+							"host": { "type": "string" },
+							"path": { "type": "string" },
+							"status_code": { "type": ["integer", "null"] },
+							"ok": { "type": ["boolean", "null"] },
+							"duration_ms": { "type": "integer" },
+							"error": { "type": ["string", "null"] },
+							"ts": {
+								"type": "string",
+								"format": "date-time"
+							}
+						},
+						"required": [
+							"id",
+							"function_id",
+							"webhook_delivery_id",
+							"email_id",
+							"endpoint_id",
+							"method",
+							"url",
+							"host",
+							"path",
+							"status_code",
+							"ok",
+							"duration_ms",
+							"error",
+							"ts"
+						]
+					}
+				},
+				"logs": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"description": "One row from GET /functions/{id}/logs. Represents a single\ncaptured log line emitted by the running handler (e.g. via\n`console.log` / `console.error`).\n",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid",
+								"description": "Unique log row id (stable across pages)."
+							},
+							"function_id": {
+								"type": "string",
+								"format": "uuid",
+								"description": "The function this log row belongs to."
+							},
+							"level": {
+								"type": "string",
+								"enum": [
+									"debug",
+									"log",
+									"info",
+									"warn",
+									"error"
+								],
+								"description": "Severity. `log` is the runtime's default for unannotated\n`console.log` calls; the other levels match standard\n`console.*` methods.\n"
+							},
+							"message": {
+								"type": "string",
+								"description": "The textual message body. The runtime stringifies non-string\narguments before persisting, so this is always a plain\nstring.\n"
+							},
+							"ts": {
+								"type": "string",
+								"format": "date-time",
+								"description": "When the handler emitted this line. Newest-first ordering\non this column drives pagination; clock is the runtime's,\nnot the gateway's.\n"
+							},
+							"metadata": {
+								"type": ["object", "null"],
+								"additionalProperties": true,
+								"description": "Optional structured payload the runtime attaches alongside\nthe message (e.g. extra args passed to `console.log`).\nShape is opaque; treat keys as untyped.\n"
+							}
+						},
+						"required": [
+							"id",
+							"function_id",
+							"level",
+							"message",
+							"ts"
+						]
+					}
+				},
+				"replies": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"status": {
+								"type": "string",
+								"description": "Lifecycle status of a sent_emails row. Possible values:\n\n  - `queued`: pre-call INSERT; the outbound agent has not\n    yet replied.\n  - `submitted_to_agent`: agent accepted; `queue_id` is set.\n  - `agent_failed`: agent rejected; `error_code` and\n    `error_message` carry the reason.\n  - `gate_denied`: a recipient-scope gate denied the send;\n    the agent was never called. The `gates` array carries\n    the denial detail. /send-mail returns 403 in this case\n    so callers see the denial synchronously; /sent-emails\n    additionally records the row for historical lookup,\n    which is when this status appears in a listing.\n  - `unknown`: terminal indeterminate; the on-box log\n    poller couldn't classify the receiver's response.\n  - `delivered` / `bounced` / `deferred` / `wait_timeout`:\n    terminal delivery outcomes (see DeliveryStatus).\n",
+								"enum": [
+									"queued",
+									"submitted_to_agent",
+									"agent_failed",
+									"gate_denied",
+									"unknown",
+									"delivered",
+									"bounced",
+									"deferred",
+									"wait_timeout"
+								]
+							},
+							"to": { "type": "string" },
+							"subject": { "type": "string" },
+							"queue_id": { "type": ["string", "null"] },
+							"created_at": {
+								"type": "string",
+								"format": "date-time"
+							}
+						},
+						"required": [
+							"id",
+							"status",
+							"to",
+							"subject",
+							"queue_id",
+							"created_at"
+						]
+					}
 				}
 			},
 			"required": [
-				"id",
-				"name",
-				"code",
-				"deploy_status",
-				"gateway_url",
-				"created_at",
-				"updated_at"
+				"state",
+				"test_run",
+				"test_send",
+				"inbound_email",
+				"deliveries",
+				"outbound_requests",
+				"logs",
+				"replies"
 			]
 		},
-		"sdkName": "getFunction",
-		"summary": "Get a function",
+		"sdkName": "getFunctionTestRunTrace",
+		"summary": "Get a function test run trace",
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
@@ -8602,8 +9413,13 @@ const operationManifest = [
 		},
 		"responseSchema": {
 			"type": "object",
-			"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; the actual invocation lands on the function's\ninvocations list a few seconds later as the inbound mail\ntraverses the MX path.\n",
+			"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; poll `trace_url` to watch the run progress through\nsend -> inbound -> webhook deliveries -> outbound requests,\nlogs, and replies.\n",
 			"properties": {
+				"test_run_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "Durable test run id used to fetch the run trace."
+				},
 				"inbound_domain": {
 					"type": "string",
 					"description": "Verified inbound domain the test email was sent to."
@@ -8633,16 +9449,22 @@ const operationManifest = [
 					"type": "string",
 					"format": "uri",
 					"description": "Function detail page where invocations show up live."
+				},
+				"trace_url": {
+					"type": "string",
+					"description": "Relative API URL for GET /functions/{id}/test-runs/{test_run_id}/trace."
 				}
 			},
 			"required": [
+				"test_run_id",
 				"inbound_domain",
 				"to",
 				"from",
 				"send_id",
 				"subject",
 				"poll_since",
-				"watch_url"
+				"watch_url",
+				"trace_url"
 			]
 		},
 		"sdkName": "testFunction",
@@ -11382,41 +12204,319 @@ function emitRawSendMailFetchWarning(bundleText, write) {
 //#endregion
 //#region src/oclif/secret-flags.ts
 const SECRET_KEY_RE = /^[A-Z_][A-Z0-9_]*$/;
-function parseSecretFlags(raw) {
+function resolveSecretFlags(input) {
 	const secrets = [];
 	const seenKeys = /* @__PURE__ */ new Set();
-	for (const entry of raw) {
-		const eq = entry.indexOf("=");
-		if (eq === -1) return {
+	const env = input.env ?? process.env;
+	const readFile = input.readFile ?? defaultReadFile;
+	const readStdin = input.readStdin ?? defaultReadStdin;
+	const envFileCache = /* @__PURE__ */ new Map();
+	const reserveSecretKey = (key, sourceLabel) => {
+		const keyError = validateKey(key, sourceLabel);
+		if (keyError) return keyError;
+		if (seenKeys.has(key)) return duplicateKeyError(key);
+		seenKeys.add(key);
+		return null;
+	};
+	const addSecret = (key, value, sourceLabel) => {
+		const keyError = reserveSecretKey(key, sourceLabel);
+		if (keyError) return keyError;
+		secrets.push({
+			key,
+			value
+		});
+		return null;
+	};
+	for (const entry of input.inline ?? []) {
+		const parsed = parseKeyValueFlag(entry, "--secret");
+		if (parsed.kind === "error") return parsed;
+		const error = addSecret(parsed.key, parsed.value, "--secret");
+		if (error) return error;
+	}
+	for (const key of input.fromEnv ?? []) {
+		const keyError = reserveSecretKey(key, "--secret-from-env");
+		if (keyError) return keyError;
+		const value = env[key];
+		if (value === void 0) return {
 			kind: "error",
-			message: `--secret expects KEY=VALUE (got ${JSON.stringify(entry)}). Example: --secret API_TOKEN=abc123`
+			message: `--secret-from-env ${key} could not read ${key}: environment variable is not set.`
 		};
-		const key = entry.slice(0, eq);
-		const value = entry.slice(eq + 1);
-		if (key.length === 0) return {
+		secrets.push({
+			key,
+			value
+		});
+	}
+	for (const entry of input.fromFile ?? []) {
+		const parsed = parseKeyValueFlag(entry, "--secret-from-file");
+		if (parsed.kind === "error") return parsed;
+		const keyError = reserveSecretKey(parsed.key, "--secret-from-file");
+		if (keyError) return keyError;
+		const file = readSecretFile(parsed.value, "--secret-from-file", readFile);
+		if (file.kind === "error") return file;
+		secrets.push({
+			key: parsed.key,
+			value: file.value
+		});
+	}
+	for (const entry of input.fromEnvFile ?? []) {
+		const parsed = parseEnvFileKeyRef(entry, "--secret-from-env-file");
+		if (parsed.kind === "error") return parsed;
+		const keyError = reserveSecretKey(parsed.key, "--secret-from-env-file");
+		if (keyError) return keyError;
+		const file = readEnvFile(parsed.path, readFile, envFileCache);
+		if (file.kind === "error") return file;
+		const value = file.values.get(parsed.key);
+		if (value === void 0) return {
 			kind: "error",
-			message: `--secret is missing a KEY before '=' (got ${JSON.stringify(entry)}). Example: --secret API_TOKEN=abc123`
+			message: `--secret-from-env-file ${entry} could not read ${parsed.key}: key is not present in ${parsed.path}.`
 		};
-		if (!SECRET_KEY_RE.test(key)) return {
+		secrets.push({
+			key: parsed.key,
+			value
+		});
+	}
+	if (input.fromStdin !== void 0) {
+		const keyError = reserveSecretKey(input.fromStdin, "--secret-from-stdin");
+		if (keyError) return keyError;
+		const stdin = readSecretStdin("--secret-from-stdin", readStdin);
+		if (stdin.kind === "error") return stdin;
+		secrets.push({
+			key: input.fromStdin,
+			value: stdin.value
+		});
+	}
+	return {
+		kind: "ok",
+		secrets
+	};
+}
+function resolveSingleSecretValue(input) {
+	if ([
+		input.value !== void 0 ? "--value" : null,
+		input.valueFromEnv !== void 0 ? "--value-from-env" : null,
+		input.valueFile !== void 0 ? "--value-file" : null,
+		input.valueFromEnvFile !== void 0 ? "--value-from-env-file" : null,
+		input.stdin === true ? "--stdin" : null
+	].filter((v) => v !== null).length !== 1) return {
+		kind: "error",
+		message: "Pass exactly one of --value, --value-from-env, --value-file, --value-from-env-file, or --stdin."
+	};
+	const env = input.env ?? process.env;
+	const readFile = input.readFile ?? defaultReadFile;
+	const readStdin = input.readStdin ?? defaultReadStdin;
+	if (input.value !== void 0) return {
+		kind: "ok",
+		value: input.value
+	};
+	if (input.valueFromEnv !== void 0) {
+		const value = env[input.valueFromEnv];
+		if (value === void 0) return {
 			kind: "error",
-			message: `--secret KEY ${JSON.stringify(key)} does not match ${SECRET_KEY_RE.source} (uppercase letters, digits, underscores; first character is a letter or underscore).`
+			message: `--value-from-env ${input.valueFromEnv} could not read ${input.valueFromEnv}: environment variable is not set.`
+		};
+		return {
+			kind: "ok",
+			value
 		};
-		if (seenKeys.has(key)) return {
+	}
+	if (input.valueFile !== void 0) return readSecretFile(input.valueFile, "--value-file", readFile);
+	if (input.valueFromEnvFile !== void 0) {
+		const parsed = parseSingleValueEnvFileRef(input.valueFromEnvFile, input.key, "--value-from-env-file");
+		if (parsed.kind === "error") return parsed;
+		const file = readEnvFile(parsed.path, readFile, /* @__PURE__ */ new Map());
+		if (file.kind === "error") return file;
+		const value = file.values.get(parsed.key);
+		if (value === void 0) return {
 			kind: "error",
-			message: `--secret KEY ${JSON.stringify(key)} was passed more than once. Each key may only appear once per command.`
+			message: `--value-from-env-file ${input.valueFromEnvFile} could not read ${parsed.key}: key is not present in ${parsed.path}.`
 		};
-		seenKeys.add(key);
-		secrets.push({
-			key,
+		return {
+			kind: "ok",
 			value
-		});
+		};
 	}
+	if (input.stdin === true) return readSecretStdin("--stdin", readStdin);
+	return {
+		kind: "error",
+		message: "Pass exactly one of --value, --value-from-env, --value-file, --value-from-env-file, or --stdin."
+	};
+}
+function defaultReadFile(path) {
+	return readFileSync(path, "utf8");
+}
+function defaultReadStdin() {
+	if (process.stdin.isTTY) throw new Error("stdin is a TTY; pipe a value into this command or pass a file/env source instead.");
+	return readFileSync(0, "utf8");
+}
+function parseKeyValueFlag(entry, flagLabel) {
+	const eq = entry.indexOf("=");
+	if (eq === -1) return {
+		kind: "error",
+		message: `${flagLabel} expects KEY=VALUE (got ${JSON.stringify(entry)}). Example: ${flagLabel} API_TOKEN=abc123`
+	};
+	const key = entry.slice(0, eq);
+	const value = entry.slice(eq + 1);
+	if (key.length === 0) return {
+		kind: "error",
+		message: `${flagLabel} is missing a KEY before '=' (got ${JSON.stringify(entry)}). Example: ${flagLabel} API_TOKEN=abc123`
+	};
 	return {
 		kind: "ok",
-		secrets
+		key,
+		value
+	};
+}
+function validateKey(key, flagLabel) {
+	if (!SECRET_KEY_RE.test(key)) return {
+		kind: "error",
+		message: `${flagLabel} KEY ${JSON.stringify(key)} does not match ${SECRET_KEY_RE.source} (uppercase letters, digits, underscores; first character is a letter or underscore).`
+	};
+	return null;
+}
+function duplicateKeyError(key) {
+	return {
+		kind: "error",
+		message: `Secret KEY ${JSON.stringify(key)} was passed more than once. Each key may only appear once per command.`
+	};
+}
+function readSecretFile(path, flagLabel, readFile) {
+	try {
+		return {
+			kind: "ok",
+			value: readFile(path)
+		};
+	} catch (error) {
+		return {
+			kind: "error",
+			message: `Could not read ${flagLabel} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+function readSecretStdin(flagLabel, readStdin) {
+	try {
+		return {
+			kind: "ok",
+			value: stripOneTrailingLineEnding(readStdin())
+		};
+	} catch (error) {
+		return {
+			kind: "error",
+			message: `Could not read ${flagLabel}: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+function stripOneTrailingLineEnding(value) {
+	if (!value.endsWith("\n")) return value;
+	const withoutLf = value.slice(0, -1);
+	return withoutLf.endsWith("\r") ? withoutLf.slice(0, -1) : withoutLf;
+}
+function parseEnvFileKeyRef(entry, flagLabel) {
+	const sep = entry.lastIndexOf(":");
+	if (sep <= 0 || sep === entry.length - 1) return {
+		kind: "error",
+		message: `${flagLabel} expects FILE:KEY (got ${JSON.stringify(entry)}). Example: ${flagLabel} .env.local:OPENAI_KEY`
+	};
+	const path = entry.slice(0, sep);
+	const key = entry.slice(sep + 1);
+	const keyError = validateKey(key, flagLabel);
+	if (keyError) return keyError;
+	return {
+		kind: "ok",
+		key,
+		path
+	};
+}
+function parseSingleValueEnvFileRef(entry, fallbackKey, flagLabel) {
+	const sep = entry.lastIndexOf(":");
+	if (sep === -1) return {
+		kind: "ok",
+		key: fallbackKey,
+		path: entry
+	};
+	if (sep <= 0 || sep === entry.length - 1) return {
+		kind: "error",
+		message: `${flagLabel} expects FILE or FILE:KEY (got ${JSON.stringify(entry)}). Example: ${flagLabel} .env.local or ${flagLabel} .env.local:OPENAI_KEY`
+	};
+	const path = entry.slice(0, sep);
+	const key = entry.slice(sep + 1);
+	const keyError = validateKey(key, flagLabel);
+	if (keyError) return keyError;
+	return {
+		kind: "ok",
+		key,
+		path
+	};
+}
+function readEnvFile(path, readFile, cache) {
+	const cached = cache.get(path);
+	if (cached) return {
+		kind: "ok",
+		values: cached
 	};
+	let contents;
+	try {
+		contents = readFile(path);
+	} catch (error) {
+		return {
+			kind: "error",
+			message: `Could not read env file ${path}: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+	const values = parseEnvFile(contents);
+	cache.set(path, values);
+	return {
+		kind: "ok",
+		values
+	};
+}
+function parseEnvFile(contents) {
+	const values = /* @__PURE__ */ new Map();
+	const normalized = contents.replace(/^\uFEFF/, "");
+	for (const rawLine of normalized.split(/\r?\n/)) {
+		let line = rawLine.trimStart();
+		if (line.length === 0 || line.startsWith("#")) continue;
+		if (line.startsWith("export ")) line = line.slice(7).trimStart();
+		const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+		if (!match) continue;
+		values.set(match[1], parseEnvValue(match[2] ?? ""));
+	}
+	return values;
+}
+function parseEnvValue(raw) {
+	const value = raw.trimStart();
+	if (value.startsWith("'")) {
+		const end = value.indexOf("'", 1);
+		return end === -1 ? value.slice(1) : value.slice(1, end);
+	}
+	if (value.startsWith("\"")) return parseDoubleQuotedEnvValue(value);
+	return value.replace(/\s+#.*$/, "").trimEnd();
+}
+function parseDoubleQuotedEnvValue(value) {
+	let out = "";
+	let escaped = false;
+	for (let i = 1; i < value.length; i++) {
+		const ch = value[i];
+		if (escaped) {
+			if (ch === "n") out += "\n";
+			else if (ch === "r") out += "\r";
+			else if (ch === "t") out += "	";
+			else out += ch;
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (ch === "\"") break;
+		out += ch;
+	}
+	if (escaped) out += "\\";
+	return out;
 }
-const SECRET_FLAG_SECURITY_NOTE = "Note: values passed on the command line are visible in shell history (e.g. ~/.bash_history) and to other users via `ps aux` / /proc/[pid]/cmdline. For sensitive values prefer `--secret KEY=\"$VAR\"` where `$VAR` is set out-of-band (read -s, a secrets manager, etc.).";
+const SECRET_FLAG_SECURITY_NOTE = "Note: values passed on the command line are visible in shell history (e.g. ~/.bash_history) and to other users via `ps aux` / /proc/[pid]/cmdline. For sensitive values prefer --secret-from-env, --secret-from-file, --secret-from-env-file, or --secret-from-stdin.";
+const SECRET_SOURCE_FLAGS_DESCRIPTION = "Safe sources: --secret-from-env KEY reads process.env[KEY], --secret-from-file KEY=PATH reads the full UTF-8 file contents, --secret-from-env-file FILE:KEY reads KEY from a dotenv-style file, and --secret-from-stdin KEY reads the value from stdin.";
+const SINGLE_SECRET_VALUE_SOURCE_DESCRIPTION = "Instead of --value, use --value-from-env ENV_VAR, --value-file PATH, --value-from-env-file FILE[:KEY], or --stdin to avoid putting the secret value in shell history or process argv. If KEY is omitted from --value-from-env-file, the command's --key is used.";
 //#endregion
 //#region src/oclif/commands/functions-deploy.ts
 async function runDeployWithSecrets(api, params) {
@@ -11518,22 +12618,23 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
   \`functions:create-function\` if you need the full flag surface
   (raw-body JSON, etc.).
 
-  Pass --secret KEY=VALUE (repeatable) to seed secret bindings in the
-  same command. Keys must match \`^[A-Z_][A-Z0-9_]*$\` (uppercase
-  letters, digits, underscores; first character is a letter or
-  underscore). With one or more --secret flags the deploy fans out to
-  multiple API calls: create-function, set-secret per pair, then a
-  final update-function with the same bundle so the running handler
-  picks up the bindings. If a secret write fails after the create
-  step the function exists with whatever secrets succeeded and the
-  redeploy has NOT fired; re-run \`primitive functions set-secret\`
-  for the missing keys, then \`primitive functions redeploy\` to
-  push them live.`;
+  Pass secret source flags to seed bindings in the same command. Keys
+  must match \`^[A-Z_][A-Z0-9_]*$\` (uppercase letters, digits,
+  underscores; first character is a letter or underscore). With one
+  or more secrets the deploy fans out to multiple API calls:
+  create-function, set-secret per pair, then a final update-function
+  with the same bundle so the running handler picks up the bindings.
+  If a secret write fails after the create step the function exists
+  with whatever secrets succeeded and the redeploy has NOT fired;
+  re-run \`primitive functions set-secret\` for the missing keys, then
+  \`primitive functions redeploy\` to push them live. ${SECRET_SOURCE_FLAGS_DESCRIPTION}`;
 	static summary = "Deploy a new function from a bundled handler file";
 	static examples = [
 		"<%= config.bin %> functions deploy --name forwarder --file ./bundle.js",
 		"<%= config.bin %> functions deploy --name forwarder --file ./bundle.js --source-map-file ./bundle.js.map",
-		"<%= config.bin %> functions deploy --name forwarder --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com"
+		"<%= config.bin %> functions deploy --name forwarder --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com",
+		"<%= config.bin %> functions deploy --name forwarder --file ./bundle.js --secret-from-env OPENAI_KEY --secret-from-env-file .env.local:OWNER_EMAIL",
+		"printf '%s' \"$OPENAI_KEY\" | <%= config.bin %> functions deploy --name forwarder --file ./bundle.js --secret-from-stdin OPENAI_KEY"
 	];
 	static flags = {
 		"api-key": Flags.string({
@@ -11563,12 +12664,31 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 			description: `Secret KEY=VALUE to seed on the deployed function. Repeatable. KEY must match \`^[A-Z_][A-Z0-9_]*$\`; VALUE may contain \`=\` (only the first \`=\` is treated as a delimiter). Each KEY may only appear once per command. Passing one or more --secret flags fans out the deploy to create-function, set-secret per pair, then a final redeploy so the running handler picks up the bindings. ${SECRET_FLAG_SECURITY_NOTE}`,
 			multiple: true
 		}),
+		"secret-from-env": Flags.string({
+			description: "Secret KEY to read from the environment and seed on the deployed function. Repeatable. Example: --secret-from-env OPENAI_KEY reads process.env.OPENAI_KEY.",
+			multiple: true
+		}),
+		"secret-from-file": Flags.string({
+			description: "Secret KEY=PATH to read from a UTF-8 file and seed on the deployed function. Repeatable. The full file contents become the value.",
+			multiple: true
+		}),
+		"secret-from-env-file": Flags.string({
+			description: "Secret FILE:KEY to read from a dotenv-style file and seed on the deployed function. Repeatable. Example: --secret-from-env-file .env.local:OPENAI_KEY.",
+			multiple: true
+		}),
+		"secret-from-stdin": Flags.string({ description: "Secret KEY to read from stdin and seed on the deployed function. A single trailing line ending is stripped. Stdin is consumed once, so this flag is not repeatable." }),
 		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
 	};
 	async run() {
 		const { flags } = await this.parse(FunctionsDeployCommand);
 		await runWithTiming(flags.time, async () => {
-			const parsedSecrets = parseSecretFlags(flags.secret ?? []);
+			const parsedSecrets = resolveSecretFlags({
+				fromEnv: flags["secret-from-env"] ?? [],
+				fromEnvFile: flags["secret-from-env-file"] ?? [],
+				fromFile: flags["secret-from-file"] ?? [],
+				fromStdin: flags["secret-from-stdin"],
+				inline: flags.secret ?? []
+			});
 			if (parsedSecrets.kind === "error") {
 				process.stderr.write(`${parsedSecrets.message}\n`);
 				process.exitCode = 1;
@@ -11652,14 +12772,16 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 	}
 };
 //#endregion
-//#region src/oclif/commands/functions-init.ts
-const SDK_VERSION_RANGE = "^0.28.0";
-const CLI_VERSION_RANGE = "^0.28.0";
+//#region src/oclif/function-templates.ts
+const DEFAULT_FUNCTION_TEMPLATE_ID = "email-reply";
+const PRIMITIVE_TEAM_AUTHOR = {
+	id: "primitive-team",
+	name: "Primitive Team",
+	url: "https://primitive.dev"
+};
+const SDK_VERSION_RANGE = "^0.29.0";
+const CLI_VERSION_RANGE = "^0.29.0";
 const ESBUILD_VERSION_RANGE = "^0.27.0";
-const VALID_NAME = /^[a-z0-9][a-z0-9_-]{0,62}$/;
-function isValidFunctionName(name) {
-	return VALID_NAME.test(name);
-}
 function renderHandler() {
 	return `// env.PRIMITIVE_API_KEY is auto-injected by the Primitive Functions runtime.
 //
@@ -11880,7 +13002,7 @@ Run \`primitive login\` once to save a key in your CLI config if you
 prefer that to an env var.
 `;
 }
-function scaffoldFiles(name) {
+function renderEmailReplyTemplateFiles(name) {
 	return [
 		{
 			contents: renderHandler(),
@@ -11908,9 +13030,79 @@ function scaffoldFiles(name) {
 		}
 	];
 }
+const FUNCTION_TEMPLATES = [{
+	author: PRIMITIVE_TEAM_AUTHOR,
+	dependencies: ["@primitivedotdev/sdk"],
+	description: "A deployable TypeScript email handler that validates email.received events, skips likely loops, and replies with the Primitive SDK.",
+	devDependencies: [
+		"@primitivedotdev/cli",
+		"esbuild",
+		"typescript"
+	],
+	files: ({ name }) => renderEmailReplyTemplateFiles(name),
+	id: DEFAULT_FUNCTION_TEMPLATE_ID,
+	secrets: [],
+	summary: "Reply to inbound email with the Primitive SDK.",
+	tags: [
+		"email",
+		"reply",
+		"typescript",
+		"worker"
+	],
+	title: "Email Reply"
+}];
+function functionTemplateIds(templates) {
+	return templates.map((template) => template.id);
+}
+function findFunctionTemplate(templates, id) {
+	return templates.find((template) => template.id === id) ?? null;
+}
+function serializeFunctionTemplate(template) {
+	return {
+		author: { ...template.author },
+		dependencies: [...template.dependencies],
+		description: template.description,
+		devDependencies: [...template.devDependencies],
+		id: template.id,
+		secrets: [...template.secrets],
+		summary: template.summary,
+		tags: [...template.tags],
+		title: template.title
+	};
+}
+function formatFunctionTemplateList(templates) {
+	const lines = ["Available Primitive Function templates:", ""];
+	for (const template of templates) {
+		lines.push(`${template.id}`);
+		lines.push(`  title: ${template.title}`);
+		lines.push(`  author: ${template.author.name}`);
+		lines.push(`  summary: ${template.summary}`);
+		lines.push(`  tags: ${template.tags.length > 0 ? template.tags.join(", ") : "none"}`);
+		lines.push(`  secrets: ${template.secrets.length > 0 ? template.secrets.join(", ") : "none"}`);
+		lines.push("");
+	}
+	lines.push("Use `primitive functions init <name> --template <id>`.");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/oclif/commands/functions-init.ts
+const VALID_NAME = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+function isValidFunctionName(name) {
+	return VALID_NAME.test(name);
+}
+function unknownTemplateError(templateId) {
+	const available = functionTemplateIds(FUNCTION_TEMPLATES).join(", ");
+	return new Errors.CLIError(`Unknown function template "${templateId}". Available templates: ${available}. Run \`primitive functions templates\` for details.`, { exit: 1 });
+}
+function scaffoldFiles(name, templateId = DEFAULT_FUNCTION_TEMPLATE_ID) {
+	const template = findFunctionTemplate(FUNCTION_TEMPLATES, templateId);
+	if (!template) throw unknownTemplateError(templateId);
+	return template.files({ name });
+}
 function writeScaffold(params) {
 	if (!isValidFunctionName(params.name)) throw new Errors.CLIError(`Invalid function name "${params.name}". Use lowercase letters, digits, hyphens, or underscores (1-63 chars, must start with a letter or digit).`, { exit: 1 });
-	const files = scaffoldFiles(params.name);
+	const templateId = params.templateId ?? "email-reply";
+	const files = scaffoldFiles(params.name, templateId);
 	const written = [];
 	try {
 		mkdirSync(params.outDir, { recursive: false });
@@ -11941,7 +13133,7 @@ function writeScaffold(params) {
 	return { written };
 }
 var FunctionsInitCommand = class FunctionsInitCommand extends Command {
-	static description = `Scaffold a new Primitive Function project in ./<name>/ with handler.ts, package.json, build.mjs, tsconfig.json, .gitignore, and README.md.
+	static description = `Scaffold a new Primitive Function project from a Primitive-owned template.
 
   The scaffolded handler imports \`createPrimitiveClient\` from
   \`@primitivedotdev/sdk/api\` and demonstrates the canonical pattern:
@@ -11950,22 +13142,35 @@ var FunctionsInitCommand = class FunctionsInitCommand extends Command {
   ./dist/handler.js, ready to hand to \`primitive functions deploy --file\`.
 
   Refuses to overwrite an existing directory. Use --out-dir to pick a
-  different target path than ./<name>/.`;
+  different target path than ./<name>/. Run \`primitive functions templates\`
+  to inspect available templates.`;
 	static summary = "Scaffold a new Primitive Function project ready for functions deploy";
-	static examples = ["<%= config.bin %> functions init my-fn", "<%= config.bin %> functions init my-fn --out-dir ./functions/my-fn"];
+	static examples = [
+		"<%= config.bin %> functions init my-fn",
+		"<%= config.bin %> functions init my-fn --template email-reply",
+		"<%= config.bin %> functions init my-fn --out-dir ./functions/my-fn"
+	];
 	static args = { name: Args.string({
 		description: "Function name. Lowercase letters, digits, hyphens, underscores. 1-63 chars. Used as the directory name (when --out-dir is not set) and as the package.json name.",
 		required: true
 	}) };
-	static flags = { "out-dir": Flags.string({ description: "Directory to scaffold into. Defaults to ./<name>/. Must not already exist." }) };
+	static flags = {
+		"out-dir": Flags.string({ description: "Directory to scaffold into. Defaults to ./<name>/. Must not already exist." }),
+		template: Flags.string({
+			default: DEFAULT_FUNCTION_TEMPLATE_ID,
+			description: "Function template id. Run `primitive functions templates` to list templates.",
+			options: functionTemplateIds(FUNCTION_TEMPLATES)
+		})
+	};
 	async run() {
 		const { args, flags } = await this.parse(FunctionsInitCommand);
 		const outDir = resolve(flags["out-dir"] ?? `./${args.name}`);
 		writeScaffold({
 			name: args.name,
-			outDir
+			outDir,
+			templateId: flags.template
 		});
-		this.log(`Scaffolded ${outDir}.`);
+		this.log(`Scaffolded ${outDir} from ${flags.template} template.`);
 		this.log("Next:");
 		this.log(`  cd ${outDir}`);
 		this.log("  npm install");
@@ -12046,17 +13251,19 @@ var FunctionsRedeployCommand = class FunctionsRedeployCommand extends Command {
   the bindings table fresh on every call, so passing the existing
   bundle picks up any secret writes since the last deploy.
 
-  Pass --secret KEY=VALUE (repeatable) to write secrets BEFORE the
-  redeploy fires; one update-function call then refreshes every new
-  binding. Keys must match \`^[A-Z_][A-Z0-9_]*$\` (uppercase letters,
-  digits, underscores; first character is a letter or underscore).
-  With one or more --secret flags the redeploy fans out to multiple
-  API calls (set-secret per pair, then update-function).`;
+  Pass secret source flags to write secrets BEFORE the redeploy fires;
+  one update-function call then refreshes every new binding. Keys must
+  match \`^[A-Z_][A-Z0-9_]*$\` (uppercase letters, digits, underscores;
+  first character is a letter or underscore). With one or more secrets
+  the redeploy fans out to multiple API calls (set-secret per pair,
+  then update-function). ${SECRET_SOURCE_FLAGS_DESCRIPTION}`;
 	static summary = "Redeploy a function from a bundled handler file";
 	static examples = [
 		"<%= config.bin %> functions redeploy --id <fn-id> --file ./bundle.js",
 		"<%= config.bin %> functions redeploy --id <fn-id> --file ./bundle.js --source-map-file ./bundle.js.map",
-		"<%= config.bin %> functions redeploy --id <fn-id> --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com"
+		"<%= config.bin %> functions redeploy --id <fn-id> --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com",
+		"<%= config.bin %> functions redeploy --id <fn-id> --file ./bundle.js --secret-from-env OPENAI_KEY --secret-from-file PRIVATE_KEY=./private-key.pem",
+		"printf '%s' \"$OPENAI_KEY\" | <%= config.bin %> functions redeploy --id <fn-id> --file ./bundle.js --secret-from-stdin OPENAI_KEY"
 	];
 	static flags = {
 		"api-key": Flags.string({
@@ -12086,12 +13293,31 @@ var FunctionsRedeployCommand = class FunctionsRedeployCommand extends Command {
 			description: `Secret KEY=VALUE to write on the function before the redeploy fires. Repeatable. KEY must match \`^[A-Z_][A-Z0-9_]*$\`; VALUE may contain \`=\` (only the first \`=\` is treated as a delimiter). Each KEY may only appear once per command. Passing one or more --secret flags fans out to set-secret per pair then a single update-function call so the new bindings land in the same redeploy. ${SECRET_FLAG_SECURITY_NOTE}`,
 			multiple: true
 		}),
+		"secret-from-env": Flags.string({
+			description: "Secret KEY to read from the environment and write before the redeploy. Repeatable. Example: --secret-from-env OPENAI_KEY reads process.env.OPENAI_KEY.",
+			multiple: true
+		}),
+		"secret-from-file": Flags.string({
+			description: "Secret KEY=PATH to read from a UTF-8 file and write before the redeploy. Repeatable. The full file contents become the value.",
+			multiple: true
+		}),
+		"secret-from-env-file": Flags.string({
+			description: "Secret FILE:KEY to read from a dotenv-style file and write before the redeploy. Repeatable. Example: --secret-from-env-file .env.local:OPENAI_KEY.",
+			multiple: true
+		}),
+		"secret-from-stdin": Flags.string({ description: "Secret KEY to read from stdin and write before the redeploy. A single trailing line ending is stripped. Stdin is consumed once, so this flag is not repeatable." }),
 		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
 	};
 	async run() {
 		const { flags } = await this.parse(FunctionsRedeployCommand);
 		await runWithTiming(flags.time, async () => {
-			const parsedSecrets = parseSecretFlags(flags.secret ?? []);
+			const parsedSecrets = resolveSecretFlags({
+				fromEnv: flags["secret-from-env"] ?? [],
+				fromEnvFile: flags["secret-from-env-file"] ?? [],
+				fromFile: flags["secret-from-file"] ?? [],
+				fromStdin: flags["secret-from-stdin"],
+				inline: flags.secret ?? []
+			});
 			if (parsedSecrets.kind === "error") {
 				process.stderr.write(`${parsedSecrets.message}\n`);
 				process.exitCode = 1;
@@ -12242,9 +13468,15 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 
   Keys must match \`^[A-Z_][A-Z0-9_]*$\` (uppercase letters, digits,
   underscores; first character is a letter or underscore). System-
-  managed keys are reserved and rejected.`;
+  managed keys are reserved and rejected. ${SINGLE_SECRET_VALUE_SOURCE_DESCRIPTION}`;
 	static summary = "Write a function secret (optionally redeploying to push it live)";
-	static examples = ["<%= config.bin %> functions set-secret --id <fn-id> --key API_TOKEN --value abc123", "<%= config.bin %> functions set-secret --id <fn-id> --key API_TOKEN --value abc123 --redeploy"];
+	static examples = [
+		"<%= config.bin %> functions set-secret --id <fn-id> --key API_TOKEN --value abc123",
+		"<%= config.bin %> functions set-secret --id <fn-id> --key API_TOKEN --value abc123 --redeploy",
+		"<%= config.bin %> functions set-secret --id <fn-id> --key OPENAI_KEY --value-from-env OPENAI_KEY --redeploy",
+		"<%= config.bin %> functions set-secret --id <fn-id> --key OPENAI_KEY --value-from-env-file .env.local --redeploy",
+		"printf '%s' \"$OPENAI_KEY\" | <%= config.bin %> functions set-secret --id <fn-id> --key OPENAI_KEY --stdin --redeploy"
+	];
 	static flags = {
 		"api-key": Flags.string({
 			description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -12268,10 +13500,11 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 			description: "Secret key. Uppercase letters, digits, underscores; must start with a letter or underscore. System-managed keys are reserved.",
 			required: true
 		}),
-		value: Flags.string({
-			description: "Secret value (up to 4096 UTF-8 bytes). Encrypted at rest.",
-			required: true
-		}),
+		value: Flags.string({ description: "Secret value (up to 4096 UTF-8 bytes). Encrypted at rest. Visible in shell history and process argv; prefer a non-argv source for sensitive values." }),
+		"value-from-env": Flags.string({ description: "Environment variable to read as the secret value. Example: --value-from-env OPENAI_KEY reads process.env.OPENAI_KEY." }),
+		"value-file": Flags.string({ description: "UTF-8 file to read as the secret value. The full file contents become the value." }),
+		"value-from-env-file": Flags.string({ description: "Dotenv-style file to read as the secret value. Use FILE to read --key from that file, or FILE:KEY to read a different key." }),
+		stdin: Flags.boolean({ description: "Read the secret value from stdin. A single trailing line ending is stripped. Example: printf '%s' \"$OPENAI_KEY\" | primitive functions set-secret --id <fn-id> --key OPENAI_KEY --stdin" }),
 		redeploy: Flags.boolean({ description: "Also redeploy the function with its current code so the new value lands in the running handler. Without this, the secret is written but not visible to the handler until the next deploy. Note: when --redeploy re-uploads the function's current live code without a sourceMap field, the API preserves the current stored source map. Use `functions redeploy --file <bundle.js> --source-map-file <bundle.js.map>` to replace or restore a map." }),
 		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
 	};
@@ -12295,6 +13528,19 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 				baseUrlOverridden,
 				configDir: this.config.configDir
 			};
+			const resolvedValue = resolveSingleSecretValue({
+				key: flags.key,
+				value: flags.value,
+				valueFile: flags["value-file"],
+				valueFromEnv: flags["value-from-env"],
+				valueFromEnvFile: flags["value-from-env-file"],
+				stdin: flags.stdin
+			});
+			if (resolvedValue.kind === "error") {
+				process.stderr.write(`${resolvedValue.message}\n`);
+				process.exitCode = 1;
+				return;
+			}
 			const outcome = await runSetSecret({
 				getFunction: (p) => getFunction({
 					client: apiClient.client,
@@ -12320,7 +13566,7 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 				id: flags.id,
 				key: flags.key,
 				redeploy: flags.redeploy === true,
-				value: flags.value
+				value: resolvedValue.value
 			});
 			if (outcome.kind === "error") {
 				if (outcome.stage === "get-function") process.stderr.write("Secret was written, but reading current function code for redeploy failed; the secret is NOT yet live. Re-run with --redeploy, or call `primitive functions redeploy --id <id> --file <bundle>` once you have the bundle.\n");
@@ -12338,9 +13584,111 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 	}
 };
 //#endregion
+//#region src/oclif/commands/functions-templates.ts
+var FunctionsTemplatesCommand = class FunctionsTemplatesCommand extends Command {
+	static enableJsonFlag = true;
+	static description = `List Primitive Function templates available to \`primitive functions init\`.
+
+  The default table is optimized for quick terminal discovery. Use
+  --json when an agent or script needs stable metadata for searching,
+  ranking, or choosing a template programmatically.`;
+	static summary = "List available Primitive Function templates";
+	static examples = [
+		"<%= config.bin %> functions templates",
+		"<%= config.bin %> functions templates --json",
+		"<%= config.bin %> functions init my-fn --template email-reply"
+	];
+	static flags = {};
+	async run() {
+		const { flags } = await this.parse(FunctionsTemplatesCommand);
+		if (flags.json) return FUNCTION_TEMPLATES.map(serializeFunctionTemplate);
+		this.log(formatFunctionTemplateList(FUNCTION_TEMPLATES));
+	}
+};
+//#endregion
 //#region src/oclif/commands/functions-test-function.ts
 const DEFAULT_WAIT_TIMEOUT_SECONDS = 60;
 const TERMINAL_WEBHOOK_STATUSES = new Set(["fired", "exhausted"]);
+function buildFunctionTestOutcome(params) {
+	const outcome = {
+		elapsed_seconds: params.elapsedSeconds,
+		function_id: params.functionId,
+		inbound_domain: params.invocation.inbound_domain,
+		inbound_id: params.inboundId,
+		inbound_to: params.invocation.to,
+		poll_since: params.invocation.poll_since,
+		test_run_id: params.invocation.test_run_id,
+		test_send_id: params.invocation.send_id,
+		test_subject: params.invocation.subject,
+		trace_url: params.invocation.trace_url,
+		watch_url: params.invocation.watch_url,
+		webhook_attempt_count: params.detail.webhook_attempt_count,
+		webhook_last_error: params.detail.webhook_last_error,
+		webhook_last_status_code: params.detail.webhook_last_status_code,
+		webhook_status: params.detail.webhook_status
+	};
+	if (params.showSends) outcome.sent_emails = params.detail.replies;
+	return outcome;
+}
+function stringOrNull(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+function findMatchingFunctionEndpoints(params) {
+	const matches = [];
+	for (const endpoint of params.endpoints) {
+		if (endpoint.kind !== "function") continue;
+		if (endpoint.enabled === false) continue;
+		if (endpoint.deactivated_at !== null && endpoint.deactivated_at !== void 0) continue;
+		const id = stringOrNull(endpoint.id);
+		if (!id) continue;
+		const domainId = stringOrNull(endpoint.domain_id);
+		if (domainId !== null && (params.inboundDomainId === null || domainId !== params.inboundDomainId)) continue;
+		const functionId = stringOrNull(endpoint.function_id);
+		matches.push({
+			function_id: functionId,
+			id,
+			is_current_function: functionId === params.currentFunctionId,
+			scope: domainId === null ? "catch-all" : "domain"
+		});
+	}
+	return matches;
+}
+function formatFunctionEndpointNoiseWarning(params) {
+	if (params.endpoints.filter((endpoint) => !endpoint.is_current_function).length === 0) return null;
+	const lines = [`Warning: ${params.endpoints.length} function endpoints may receive mail for ${params.toAddress}:`];
+	for (const endpoint of params.endpoints) {
+		const scope = endpoint.scope === "catch-all" ? "catch-all" : `scoped to ${params.inboundDomain}`;
+		const current = endpoint.is_current_function ? " (this function)" : "";
+		const target = endpoint.function_id ? ` -> function ${endpoint.function_id}` : "";
+		lines.push(`- endpoint ${endpoint.id}${target}, ${scope}${current}`);
+	}
+	return lines.join("\n");
+}
+async function maybeWriteEndpointNoiseWarning(params) {
+	try {
+		const [domainsResult, endpointsResult] = await Promise.all([listDomains({
+			client: params.apiClient.client,
+			responseStyle: "fields"
+		}), listEndpoints({
+			client: params.apiClient.client,
+			responseStyle: "fields"
+		})]);
+		if (endpointsResult.error) return;
+		if (domainsResult.error) return;
+		const inboundDomainId = domainsResult.data?.data?.find((domain) => domain.domain?.toLowerCase() === params.invocation.inbound_domain.toLowerCase())?.id ?? null;
+		const endpointsEnvelope = endpointsResult.data;
+		const warning = formatFunctionEndpointNoiseWarning({
+			endpoints: findMatchingFunctionEndpoints({
+				currentFunctionId: params.currentFunctionId,
+				endpoints: endpointsEnvelope?.data ?? [],
+				inboundDomainId
+			}),
+			inboundDomain: params.invocation.inbound_domain,
+			toAddress: params.invocation.to
+		});
+		if (warning) params.writeStderr(`${warning}\n`);
+	} catch {}
+}
 var FunctionsTestFunctionCommand = 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";
@@ -12424,6 +13772,14 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 				this.log(JSON.stringify(invocation, null, 2));
 				return;
 			}
+			await maybeWriteEndpointNoiseWarning({
+				apiClient,
+				currentFunctionId: flags.id,
+				invocation,
+				writeStderr: (chunk) => {
+					process.stderr.write(chunk);
+				}
+			});
 			const startedAt = Date.now();
 			const timeoutMs = flags.timeout * 1e3;
 			const pollIntervalMs = flags["poll-interval"] * 1e3;
@@ -12486,17 +13842,14 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 			}
 			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 });
 			const elapsedSeconds = Math.round((Date.now() - startedAt) / 1e3);
-			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;
+			const outcome = buildFunctionTestOutcome({
+				detail,
+				elapsedSeconds,
+				functionId: flags.id,
+				inboundId,
+				invocation,
+				showSends: shouldShowSends
+			});
 			this.log(JSON.stringify(outcome, null, 2));
 			if (detail.webhook_status === "exhausted") process.exitCode = 1;
 		});
@@ -13648,6 +15001,7 @@ const COMMANDS = {
 	"emails:watch": EmailsWatchCommand,
 	"emails:wait": EmailsWaitCommand,
 	"functions:init": FunctionsInitCommand,
+	"functions:templates": FunctionsTemplatesCommand,
 	"functions:deploy": FunctionsDeployCommand,
 	"functions:redeploy": FunctionsRedeployCommand,
 	"functions:set-secret": FunctionsSetSecretCommand,