primcli 1.2.0

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

@@ -0,0 +1,71 @@
+import { spawnSync } from "node:child_process";
+//#region src/oclif/proxy-auto-detect.ts
+const PROXY_ENV_VARS = [
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"http_proxy",
+	"https_proxy"
+];
+let hintPrinted = false;
+function _resetHintLatchForTest() {
+	hintPrinted = false;
+}
+function detectProxyVars(env) {
+	return PROXY_ENV_VARS.filter((name) => {
+		const value = env[name];
+		return typeof value === "string" && value.length > 0;
+	});
+}
+function restartWithProxyEnvIfNeeded(options = {}) {
+	const env = options.env ?? process.env;
+	const stderr = options.stderr ?? process.stderr;
+	const detectedVars = detectProxyVars(env);
+	if (detectedVars.length === 0) return {
+		applied: false,
+		detectedVars: [],
+		reason: "no_proxy_env"
+	};
+	if (Object.hasOwn(env, "NODE_USE_ENV_PROXY")) return {
+		applied: false,
+		detectedVars,
+		reason: "node_use_env_proxy_already_set"
+	};
+	const argv = options.argv ?? process.argv;
+	const entrypoint = argv[1];
+	if (!entrypoint) return {
+		applied: false,
+		detectedVars,
+		reason: "missing_entrypoint"
+	};
+	const execPath = options.execPath ?? process.execPath;
+	const execArgv = options.execArgv ?? process.execArgv;
+	const spawn = options.spawn ?? spawnSync;
+	const exit = options.exit ?? ((code) => {
+		process.exit(code);
+		throw new Error("process.exit returned unexpectedly");
+	});
+	if (!hintPrinted) {
+		hintPrinted = true;
+		const names = detectedVars.join("/");
+		stderr.write(`primitive: proxy detected via ${names}, restarting with NODE_USE_ENV_PROXY=1\n`);
+	}
+	const child = spawn(execPath, [
+		...execArgv,
+		entrypoint,
+		...argv.slice(2)
+	], {
+		env: {
+			...env,
+			NODE_USE_ENV_PROXY: "1"
+		},
+		stdio: "inherit"
+	});
+	if (child.error) throw child.error;
+	if (child.signal) {
+		(options.kill ?? process.kill)(options.pid ?? process.pid, child.signal);
+		return exit(1);
+	}
+	return exit(child.status ?? 1);
+}
+//#endregion
+export { _resetHintLatchForTest, restartWithProxyEnvIfNeeded };

package/dist/oclif/root-signup-hint.js

@@ -0,0 +1,136 @@
+import { c as resolveConfigEnvironment, i as loadCliConfig, x as normalizeApiBaseUrl } from "../cli-config-B5hrwe8q.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+//#region src/oclif/root-signup-hint.ts
+const CREDENTIALS_FILE = "credentials.json";
+const ROOT_AUTH_TIMEOUT_MS = 1e3;
+function activeConfigDir(env, home) {
+	if (env.PRIMITIVE_CONFIG_DIR) return env.PRIMITIVE_CONFIG_DIR;
+	return join(env.XDG_CONFIG_HOME || join(home, ".config"), "primitive");
+}
+function readRootCredentials(configDir) {
+	let raw;
+	try {
+		raw = readFileSync(join(configDir, CREDENTIALS_FILE), "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed.auth_method !== "oauth") return null;
+		if (typeof parsed.access_token !== "string" || !parsed.access_token.trim()) return null;
+		const apiBaseUrl = parsed.api_base_url ?? parsed.api_base_url_1;
+		if (typeof apiBaseUrl !== "string" || !apiBaseUrl.trim()) return null;
+		return {
+			accessToken: parsed.access_token,
+			apiBaseUrl: apiBaseUrl.replace(/\/+$/, "")
+		};
+	} catch {
+		return null;
+	}
+}
+function accountEndpoint(apiBaseUrl) {
+	return `${apiBaseUrl.replace(/\/+$/, "")}/account`;
+}
+function parseRootAccount(payload) {
+	if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return null;
+	const data = payload.data;
+	if (data === null || typeof data !== "object" || Array.isArray(data)) return null;
+	const account = data;
+	if (typeof account.email !== "string" || !account.email.trim()) return null;
+	if (typeof account.id !== "string" || !account.id.trim()) return null;
+	return {
+		email: account.email,
+		id: account.id
+	};
+}
+function rootAuthLine(account) {
+	return `Signed in as ${account.email} (org ${account.id})\n\n`;
+}
+function rootRequestConfig(configDir, env) {
+	const currentEnvironment = resolveConfigEnvironment(loadCliConfig(configDir));
+	const configuredApiBaseUrl = currentEnvironment?.config.api_base_url;
+	const envApiBaseUrl = env.PRIMITIVE_API_BASE_URL?.trim();
+	if (currentEnvironment !== null && currentEnvironment.name !== "default" && !envApiBaseUrl && !configuredApiBaseUrl) return null;
+	return {
+		apiBaseUrl: normalizeApiBaseUrl(envApiBaseUrl || configuredApiBaseUrl),
+		headers: currentEnvironment?.config.headers
+	};
+}
+async function fetchRootAccount(params) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), params.timeoutMs);
+	try {
+		const response = await params.fetch(accountEndpoint(params.apiBaseUrl), {
+			headers: {
+				...params.headers ?? {},
+				accept: "application/json",
+				authorization: `Bearer ${params.apiKey}`
+			},
+			signal: controller.signal
+		});
+		if (!response.ok) return null;
+		return parseRootAccount(await response.json().catch(() => null));
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function rootSignedInSummary(options = {}) {
+	if ((options.argv ?? process.argv.slice(2)).length > 0) return null;
+	const env = options.env ?? process.env;
+	const configDir = activeConfigDir(env, options.home ?? homedir());
+	let requestConfig;
+	try {
+		requestConfig = rootRequestConfig(configDir, env);
+	} catch {
+		return null;
+	}
+	if (!requestConfig) return null;
+	const explicitApiKey = env.PRIMITIVE_API_KEY?.trim();
+	const stored = explicitApiKey ? null : readRootCredentials(configDir);
+	const apiKey = explicitApiKey || stored?.accessToken;
+	if (!apiKey) return null;
+	const account = await fetchRootAccount({
+		apiBaseUrl: stored?.apiBaseUrl ?? requestConfig.apiBaseUrl,
+		apiKey,
+		fetch: options.fetch ?? fetch,
+		headers: requestConfig.headers,
+		timeoutMs: options.timeoutMs ?? ROOT_AUTH_TIMEOUT_MS
+	});
+	return account ? rootAuthLine(account) : null;
+}
+function shouldShowLoggedOutSignupHint(options = {}) {
+	if ((options.argv ?? process.argv.slice(2)).length > 0) return false;
+	const env = options.env ?? process.env;
+	if (env.PRIMITIVE_HIDE_SIGNUP_HINT === "1") return false;
+	if (env.PRIMITIVE_API_KEY?.trim()) return false;
+	return !existsSync(join(activeConfigDir(env, options.home ?? homedir()), CREDENTIALS_FILE));
+}
+function loggedOutSignupHint() {
+	return [
+		"New to Primitive?",
+		"  You or your user don't have an account yet?",
+		"  Run `primitive signup <email> --accept-terms`",
+		"  to create an account and get started.",
+		"  Add `--signup-code <code>` if you have one.",
+		""
+	].join("\n");
+}
+function writeLoggedOutSignupHintIfNeeded(options = {}) {
+	if (!shouldShowLoggedOutSignupHint(options)) return;
+	(options.write ?? ((message) => process.stdout.write(message)))(loggedOutSignupHint());
+}
+async function writeRootAuthContextIfNeeded(options = {}) {
+	const write = options.write ?? ((message) => process.stdout.write(message));
+	const signedIn = await rootSignedInSummary(options);
+	if (signedIn) {
+		write(signedIn);
+		return;
+	}
+	writeLoggedOutSignupHintIfNeeded(options);
+}
+//#endregion
+export { loggedOutSignupHint, rootSignedInSummary, shouldShowLoggedOutSignupHint, writeLoggedOutSignupHintIfNeeded, writeRootAuthContextIfNeeded };

package/man/primitive.1

@@ -0,0 +1,111 @@
+.TH PRIMITIVE 1
+.SH NAME
+primitive \- command line interface for Primitive email and Functions
+.SH SYNOPSIS
+.B primitive
+.I command
+[\fIoptions\fR]
+.br
+.B primitive
+.B --help
+.br
+.B primitive
+.I command
+.B --help
+.SH DESCRIPTION
+.B primitive
+is the command line interface for Primitive. It sends mail, inspects inbound and outbound email, manages domains and webhook endpoints, deploys Primitive Functions, and exposes generated API operations for scripting.
+.PP
+Most commands print human-readable output by default. Commands that expose JSON usually provide a
+.B --json
+flag or use generated operation output that can be piped into tools such as
+.BR jq (1).
+.SH AUTHENTICATION
+Commands use saved OAuth credentials from
+.B primitive signin
+or
+.B primitive login
+or an API key from
+.B --api-key
+or
+.BR PRIMITIVE_API_KEY .
+.PP
+Run
+.B primitive signin EMAIL --signup-code CODE --accept-terms
+to start email-code sign-in, then run
+.B primitive signin confirm EMAIL CODE
+with the emailed verification code.
+.B primitive login EMAIL
+and
+.B primitive otp EMAIL
+support the same email-code flow. Run
+.B primitive signin
+or
+.B primitive login
+with no email to use browser approval.
+.PP
+Run
+.B primitive logout --force
+to remove local credentials, pending email-code auth state, and stale credential locks without contacting Primitive.
+.PP
+Run
+.B primitive whoami
+to verify which account the CLI is authenticated as.
+.SH COMMON COMMANDS
+.TP
+.B primitive send --to ADDRESS --subject SUBJECT --body TEXT
+Send an outbound email.
+.TP
+.B primitive send --to ADDRESS --body TEXT --attachment PATH
+Send an outbound email with a file attachment.
+.TP
+.B primitive domains add DOMAIN
+Start a custom-domain claim.
+.TP
+.B primitive domains verify --id DOMAIN_ID
+Verify DNS records for a pending domain claim.
+.TP
+.B primitive domains zone-file --id DOMAIN_ID
+Download DNS records as a BIND-format zone file.
+.TP
+.B primitive emails latest
+Show recent inbound emails.
+.TP
+.B primitive functions init NAME
+Scaffold a Primitive Function.
+.TP
+.B primitive functions deploy --name NAME --file PATH
+Deploy a Primitive Function bundle.
+.TP
+.B primitive list-operations
+Print the generated API operation manifest.
+.TP
+.B primitive describe COMMAND_OR_OPERATION
+Describe a generated API operation, including request and response schemas.
+.SH GLOBAL OPTIONS
+.TP
+.B --api-key KEY
+Use an explicit Primitive API key for this command.
+.TP
+.B --time
+Print command duration to standard error after completion.
+.TP
+.B --help
+Show command help.
+.SH ENVIRONMENT
+.TP
+.B PRIMITIVE_API_KEY
+API key used when
+.B --api-key
+is not supplied and no saved OAuth credential should be used.
+.TP
+.B PRIMITIVE_API_BASE_URL
+Override the API base URL. Intended for development and testing.
+.SH FILES
+.TP
+.I ~/.config/primitive
+Default CLI configuration directory used by oclif on most systems.
+.SH SEE ALSO
+.B primitive --help
+.br
+Primitive documentation: https://primitive.dev

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "primcli",
+  "version": "1.2.0",
+  "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "bin",
+    "dist",
+    "man"
+  ],
+  "bin": {
+    "primitive": "./bin/run.js",
+    "prim": "./bin/run.js"
+  },
+  "man": [
+    "./man/primitive.1"
+  ],
+  "oclif": {
+    "bin": "primitive",
+    "commands": {
+      "strategy": "explicit",
+      "target": "./dist/oclif/index.js",
+      "identifier": "COMMANDS"
+    },
+    "dirname": "primitive",
+    "plugins": [
+      "@oclif/plugin-help",
+      "@oclif/plugin-autocomplete",
+      "@oclif/plugin-warn-if-update-available"
+    ],
+    "warn-if-update-available": {
+      "timeoutInDays": 1,
+      "frequency": 1,
+      "frequencyUnit": "days",
+      "message": "Primitive CLI update available from <%= chalk.greenBright(config.version) %> to <%= chalk.greenBright(latest) %>. Run `npm install -g @primitivedotdev/cli@latest` to update."
+    },
+    "topics": {
+      "chat": {
+        "description": "Chat with agents over email. Use `primitive chat <email> <message>` to start, `primitive chat reply <message>` to continue the active chat, or `primitive chat reply <id> <message>` to reply in a specific local chat."
+      },
+      "cli": {
+        "description": "CLI authentication"
+      },
+      "config": {
+        "description": "Manage local Primitive CLI request environments",
+        "hidden": true
+      },
+      "account": {
+        "description": "Manage your account settings, storage, and webhook secret"
+      },
+      "agent": {
+        "description": "Agent signup and authentication API operations"
+      },
+      "domains": {
+        "description": "Claim, verify, manage email domains, and download DNS zone files"
+      },
+      "inbox": {
+        "description": "Check inbound email setup and processing readiness. Prefer `primitive inbox setup` for a guided setup path and `primitive inbox status` for the readiness table."
+      },
+      "emails": {
+        "description": "List, inspect, and wait for received emails. Prefer task aliases like `primitive emails list`, `primitive emails get`, `primitive emails latest`, `primitive emails wait`, and `primitive emails watch`; generated API names remain available for compatibility."
+      },
+      "search": {
+        "description": "Cross-corpus semantic search. Prefer `primitive search <query>` for lexical inbound search and `primitive semantic-search <query>` for meaning-aware ranking across inbound and outbound.",
+        "hidden": true
+      },
+      "sending": {
+        "description": "Send outbound emails. Prefer `primitive send` for fresh sends and `primitive reply --id <inbound-id>` for replies. Use `primitive domains list` or `primitive inbox status` to find usable sender domains for --from; `primitive sending permissions` lists recipient-scope destinations you may send to."
+      },
+      "signin": {
+        "description": "Sign in to an existing Primitive account"
+      },
+      "login": {
+        "description": "Log in to an existing Primitive account"
+      },
+      "otp": {
+        "description": "Authenticate with an emailed one-time code"
+      },
+      "sent": {
+        "description": "Short aliases for outbound sent-email history: `primitive sent list` and `primitive sent get`."
+      },
+      "threads": {
+        "description": "Inspect conversation threads spanning received and sent emails. Prefer `primitive threads get --id <thread-id>`; generated API name `primitive threads get-thread --id <thread-id>` remains available."
+      },
+      "endpoints": {
+        "description": "Manage webhook endpoints that receive email events"
+      },
+      "filters": {
+        "description": "Manage whitelist and blocklist filter rules"
+      },
+      "webhook-deliveries": {
+        "description": "View and replay webhook delivery attempts. Prefer `primitive webhook-deliveries list` and `primitive webhook-deliveries replay`."
+      },
+      "deliveries": {
+        "description": "Short aliases for webhook delivery attempts: `primitive deliveries list` and `primitive deliveries replay`."
+      },
+      "functions": {
+        "description": "Deploy JavaScript handlers that run on inbound mail. Prefer `primitive functions templates`, `primitive functions init`, `primitive functions deploy`, `primitive functions redeploy`, `primitive functions list`, `primitive functions get`, `primitive functions logs`, and `primitive functions set-secret`; generated API names remain available for compatibility."
+      }
+    },
+    "topicSeparator": " "
+  },
+  "keywords": [
+    "primitive",
+    "cli",
+    "email",
+    "functions",
+    "webhook"
+  ],
+  "author": "Primitive <support@primitive.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/primitivedotdev/sdks.git",
+    "directory": "cli-node"
+  },
+  "bugs": {
+    "url": "https://github.com/primitivedotdev/sdks/issues"
+  },
+  "homepage": "https://primitive.dev",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oclif/core": "^4.10.5",
+    "@oclif/plugin-autocomplete": "^3.2.45",
+    "@oclif/plugin-help": "^6.2.44",
+    "@oclif/plugin-warn-if-update-available": "^3.1.65"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@primitivedotdev/api-core": "workspace:*",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^4.1.4",
+    "oclif": "^4.23.0",
+    "tsdown": "^0.21.10",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.2",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.4"
+  }
+}