@primitivedotdev/cli 0.24.0

package/dist/oclif/auth.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_API_BASE_URL_1, DEFAULT_API_BASE_URL_2, } from "@primitivedotdev/sdk/api";
+const CREDENTIALS_FILE = "credentials.json";
+const CREDENTIALS_LOCK_DIR = "credentials.lock";
+const CREDENTIALS_LOCK_STALE_MS = 30 * 60 * 1000;
+const MALFORMED_CREDENTIALS_HINT = "Run `primitive logout` and then `primitive login`.";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        throw new Error(`Stored Primitive CLI credentials are malformed: ${key} must be a non-empty string. ${MALFORMED_CREDENTIALS_HINT}`);
+    }
+    return raw;
+}
+/**
+ * Sentinel returned by parseCredentials when the on-disk credentials
+ * were written by a pre-dual-host CLI version (i.e. they have
+ * `base_url` instead of `api_base_url_1`). The caller treats this as
+ * "no saved credentials" after auto-cleaning the stale file. Defined
+ * as a class-tagged error so loadCliCredentials can distinguish it
+ * from a genuine malformed-credentials error.
+ */
+class StaleCredentialFormatError extends Error {
+    constructor() {
+        super("stale_credential_format");
+        this.name = "StaleCredentialFormatError";
+    }
+}
+function parseCredentials(raw) {
+    if (!isRecord(raw)) {
+        throw new Error(`Stored Primitive CLI credentials are malformed: expected a JSON object. ${MALFORMED_CREDENTIALS_HINT}`);
+    }
+    // Stored credentials from an older CLI version used the field name
+    // `base_url`; the dual-host rename moved this to `api_base_url_1`.
+    // Detect the old shape specifically so loadCliCredentials can wipe
+    // the stale file and emit a clear "you've been logged out" notice
+    // instead of every command hard-failing with a generic "malformed"
+    // error that doesn't surface the actual fix (re-login).
+    if (typeof raw.api_base_url_1 !== "string" &&
+        typeof raw.base_url === "string") {
+        throw new StaleCredentialFormatError();
+    }
+    const orgName = raw.org_name;
+    if (orgName !== null && typeof orgName !== "string") {
+        throw new Error(`Stored Primitive CLI credentials are malformed: org_name must be a string or null. ${MALFORMED_CREDENTIALS_HINT}`);
+    }
+    return {
+        api_key: requireString(raw, "api_key"),
+        key_id: requireString(raw, "key_id"),
+        key_prefix: requireString(raw, "key_prefix"),
+        org_id: requireString(raw, "org_id"),
+        org_name: orgName,
+        api_base_url_1: requireString(raw, "api_base_url_1"),
+        created_at: requireString(raw, "created_at"),
+    };
+}
+export function credentialsPath(configDir) {
+    return join(configDir, CREDENTIALS_FILE);
+}
+function normalize(url, fallback) {
+    const trimmed = url?.trim();
+    if (!trimmed)
+        return fallback;
+    return trimmed.replace(/\/+$/, "");
+}
+export function normalizeApiBaseUrl1(url) {
+    return normalize(url, DEFAULT_API_BASE_URL_1);
+}
+export function normalizeApiBaseUrl2(url) {
+    return normalize(url, DEFAULT_API_BASE_URL_2);
+}
+export function loadCliCredentials(configDir) {
+    const path = credentialsPath(configDir);
+    let contents;
+    try {
+        contents = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read Primitive CLI credentials: ${detail}`);
+    }
+    try {
+        return parseCredentials(JSON.parse(contents));
+    }
+    catch (error) {
+        if (error instanceof StaleCredentialFormatError) {
+            // Saved credentials were written by a pre-dual-host CLI version.
+            // The format is incompatible (base_url vs api_base_url_1) and
+            // cannot be recovered. Clear the file so the caller sees "no
+            // saved credentials" and emit a one-shot notice telling the
+            // user they need to log back in. Idempotent: once the file is
+            // gone, this branch never fires again.
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                // Best-effort cleanup; if the unlink fails (permissions,
+                // racing process), the next CLI invocation will hit this
+                // path again and try once more.
+            }
+            process.stderr.write("You've been logged out: your saved Primitive CLI credentials were created by an older CLI version and are no longer compatible. Run `primitive login` to re-authenticate.\n");
+            return null;
+        }
+        if (error instanceof SyntaxError) {
+            throw new Error("Stored Primitive CLI credentials are not valid JSON. Run `primitive logout` and then `primitive login`.");
+        }
+        throw error;
+    }
+}
+export function saveCliCredentials(configDir, credentials) {
+    mkdirSync(configDir, { mode: 0o700, recursive: true });
+    const path = credentialsPath(configDir);
+    const tempPath = join(configDir, `${CREDENTIALS_FILE}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(credentials, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        chmodSync(tempPath, 0o600);
+        renameSync(tempPath, path);
+        chmodSync(path, 0o600);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+export function deleteCliCredentials(configDir) {
+    rmSync(credentialsPath(configDir), { force: true });
+}
+function errorCode(error) {
+    return error && typeof error === "object"
+        ? error.code
+        : undefined;
+}
+function removeStaleCliCredentialsLock(lockPath, staleMs, now) {
+    try {
+        const stats = statSync(lockPath);
+        if (now() - stats.mtimeMs < staleMs)
+            return false;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return true;
+        throw error;
+    }
+    rmSync(lockPath, { force: true, recursive: true });
+    return true;
+}
+export function acquireCliCredentialsLock(configDir, options = {}) {
+    mkdirSync(configDir, { mode: 0o700, recursive: true });
+    const lockPath = join(configDir, CREDENTIALS_LOCK_DIR);
+    const now = options.now ?? Date.now;
+    const staleMs = options.staleMs ?? CREDENTIALS_LOCK_STALE_MS;
+    let acquired = false;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            mkdirSync(lockPath, { mode: 0o700 });
+            acquired = true;
+            break;
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+            if (removeStaleCliCredentialsLock(lockPath, staleMs, now))
+                continue;
+            throw new Error("Another Primitive CLI credential operation is already in progress. Wait for it to finish, then retry.");
+        }
+    }
+    if (!acquired) {
+        throw new Error("Another Primitive CLI credential operation is already in progress. Wait for it to finish, then retry.");
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        rmSync(lockPath, { force: true, recursive: true });
+    };
+}
+export function resolveCliAuth(params) {
+    const apiKey = params.apiKey?.trim();
+    // Host 2 (api_base_url_2) is never stored; either set by env/flag or
+    // falls back to the production default. The login flow only deals
+    // with host 1.
+    const apiBaseUrl2 = normalizeApiBaseUrl2(params.apiBaseUrl2);
+    if (apiKey) {
+        return {
+            apiKey,
+            apiBaseUrl1: normalizeApiBaseUrl1(params.apiBaseUrl1),
+            apiBaseUrl2,
+            credentials: null,
+            source: "flag-or-env",
+        };
+    }
+    const credentials = loadCliCredentials(params.configDir);
+    if (credentials) {
+        return {
+            apiKey: credentials.api_key,
+            apiBaseUrl1: params.apiBaseUrl1
+                ? normalizeApiBaseUrl1(params.apiBaseUrl1)
+                : credentials.api_base_url_1,
+            apiBaseUrl2,
+            credentials,
+            source: "stored",
+        };
+    }
+    return {
+        apiKey: undefined,
+        apiBaseUrl1: normalizeApiBaseUrl1(params.apiBaseUrl1),
+        apiBaseUrl2,
+        credentials: null,
+        source: "none",
+    };
+}

package/dist/oclif/commands/emails-latest.js

@@ -0,0 +1,184 @@
+import { Command, Flags } from "@oclif/core";
+import { listEmails, PrimitiveApiClient } from "@primitivedotdev/sdk/api";
+import { extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+// `primitive emails:latest` is the agent-grade shortcut for "show me
+// the most recent inbound emails as something I can read at a glance."
+// `emails:list-emails` returns the full JSON envelope which is great
+// for piping but blows out the screen for a quick triage. The AGX
+// walkthrough flagged that an agent doing inbox triage had no compact
+// view to reach for; `latest` is that view.
+//
+// Output is a fixed-width text table: short-id, received timestamp,
+// from address, to address, and subject. Subject is truncated for
+// display only; the underlying JSON is unchanged. For machine-readable
+// output, callers should use `emails:list-emails` and pipe to jq.
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+// Truncation widths chosen so a row fits in ~140 columns total. Long
+// values wrap to "..." rather than blowing out terminal layout.
+const SUBJECT_DISPLAY_WIDTH = 50;
+const ADDRESS_DISPLAY_WIDTH = 32;
+// Two ID widths: the short prefix is for human eyes (interactive
+// TTY), the full UUID is for piped output (a script reading the row
+// as a feed). The short prefix is useless when piped because every
+// other operation requires the full UUID, so the AGX walkthrough
+// kept producing a re-run with `--json` just to recover the id.
+// Auto-switching by `process.stdout.isTTY` makes the common piped
+// case a one-call workflow.
+const ID_DISPLAY_WIDTH_SHORT = 8;
+const ID_DISPLAY_WIDTH_FULL = 36;
+const RECEIVED_DISPLAY_WIDTH = 19;
+// Truncate to width with right-padding; values longer than width are
+// cut to width-3 with a "..." suffix so the output is exactly `width`
+// chars (3 of which are the ellipsis). Display-only; never mutates
+// the underlying value the caller passed in.
+//
+// Width-exact output matters here: formatRow relies on each column
+// being exactly its declared width so columns line up across rows.
+// An overflowing truncate would shift every later column to the
+// right whenever truncation fired (e.g. a row with both addresses
+// truncated would push SUBJECT 4 chars off).
+export function truncate(value, width) {
+    if (value.length <= width)
+        return value.padEnd(width);
+    return `${value.slice(0, width - 3)}...`;
+}
+// Compact ISO timestamp for display: `YYYY-MM-DD HH:MM:SS` in UTC.
+// The full ISO string with milliseconds and `T`/`Z` markers is too
+// dense to scan at a glance; this is the same shape git log uses.
+export function formatReceivedAt(value) {
+    if (!value)
+        return "-".padEnd(RECEIVED_DISPLAY_WIDTH);
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return value.padEnd(RECEIVED_DISPLAY_WIDTH);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+// Decide whether to print the full UUID or the short 8-char prefix
+// based on whether stdout is a TTY. Piped/redirected stdout (the
+// caller is consuming the rows programmatically) gets full UUIDs;
+// interactive terminals get the compact prefix. Pulled out as a
+// helper so tests can drive the rendering branch without touching
+// process.stdout.
+export function pickIdWidth(isTty) {
+    return isTty ? ID_DISPLAY_WIDTH_SHORT : ID_DISPLAY_WIDTH_FULL;
+}
+export function formatRow(email, idWidth) {
+    // idWidth is one of ID_DISPLAY_WIDTH_SHORT or ID_DISPLAY_WIDTH_FULL.
+    // For SHORT, slice the UUID to the prefix length and pad. For FULL,
+    // pad to the full UUID width (UUIDs are already 36 chars, so this
+    // is effectively just an alignment guarantee for any malformed
+    // shorter id).
+    const id = truncate(email.id.slice(0, idWidth), idWidth);
+    const received = formatReceivedAt(email.received_at);
+    const from = truncate(email.sender ?? "", ADDRESS_DISPLAY_WIDTH);
+    const to = truncate(email.recipient ?? "", ADDRESS_DISPLAY_WIDTH);
+    const subject = (email.subject ?? "").replace(/\s+/g, " ");
+    const subjectCol = truncate(subject, SUBJECT_DISPLAY_WIDTH);
+    return `${id}  ${received}  ${from}  ${to}  ${subjectCol}`;
+}
+export function formatHeader(idWidth) {
+    return `${"ID".padEnd(idWidth)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
+}
+class EmailsLatestCommand extends Command {
+    static description = `Print the N most recent inbound emails as a one-line-per-row text table. Designed for quick triage and visual scanning. For programmatic access, use \`primitive emails:list-emails\` (full JSON envelope, cursor pagination, filters) or pass \`--json\` here for the same raw shape without pagination/filters.
+
+  ID display is TTY-aware. When STDOUT is a terminal, the table truncates each row's id to the first ${ID_DISPLAY_WIDTH_SHORT} characters for readability. When STDOUT is piped or redirected (the row stream is being consumed by another command), the full UUID is printed so the id can be fed straight back into \`emails:get-email\`, \`emails:delete-email\`, etc. without a separate \`--json\` round-trip.
+
+  Output streams: the column header line is written to STDERR so the row data on STDOUT stays grep/awk-friendly. \`--json\` writes everything (including the envelope) to STDOUT and is equivalent to running \`emails:list-emails --limit N\` for the same N.`;
+    static summary = "Show the most recent inbound emails as a compact table";
+    static examples = [
+        "<%= config.bin %> emails latest",
+        "<%= config.bin %> emails latest --limit 25",
+        "<%= config.bin %> emails latest | head -1 | awk '{print $1}'  # full UUID since piped",
+        "<%= config.bin %> emails latest --json | jq '.data[0].id'",
+    ];
+    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: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
+        }),
+        limit: Flags.integer({
+            description: `Number of rows to print (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}).`,
+            default: DEFAULT_LIMIT,
+            // oclif validates min/max at parse time and emits a consistent
+            // out-of-range error before run() is reached, so no manual
+            // bounds check is needed here.
+            min: 1,
+            max: MAX_LIMIT,
+        }),
+        json: Flags.boolean({
+            description: "Print the raw response envelope (with full UUIDs and meta) as JSON on STDOUT instead of the text table. Useful for piping into `jq`, capturing ids for follow-up commands, or scripting.",
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EmailsLatestCommand);
+        await runWithTiming(flags.time, async () => {
+            const baseUrlOverridden = flags["api-base-url-1"] !== undefined ||
+                flags["api-base-url-2"] !== undefined;
+            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,
+            });
+            const result = await listEmails({
+                client: apiClient.client,
+                query: { limit: flags.limit },
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                const errorPayload = extractErrorPayload(result.error);
+                writeErrorWithHints(errorPayload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    auth,
+                    baseUrlOverridden,
+                    configDir: this.config.configDir,
+                    payload: errorPayload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            if (flags.json) {
+                // Raw envelope on stdout. Mirrors the shape `emails:list-emails`
+                // emits so callers can swap one for the other when they want
+                // table vs json without remembering different command names.
+                this.log(JSON.stringify(envelope ?? null, null, 2));
+                return;
+            }
+            const rows = envelope?.data ?? [];
+            if (rows.length === 0) {
+                process.stderr.write("No inbound emails yet. Send an email to one of your verified domains to populate this list.\n");
+                return;
+            }
+            const idWidth = pickIdWidth(Boolean(process.stdout.isTTY));
+            // Header on stderr so the table itself stays grep-friendly.
+            process.stderr.write(`${formatHeader(idWidth)}\n`);
+            for (const row of rows) {
+                this.log(formatRow(row, idWidth));
+            }
+        });
+    }
+}
+export default EmailsLatestCommand;

package/dist/oclif/commands/emails-poll.js

@@ -0,0 +1,121 @@
+import { searchEmails } from "@primitivedotdev/sdk/api";
+export const DEFAULT_EMAIL_POLL_INTERVAL_SECONDS = 2;
+export const DEFAULT_EMAIL_POLL_PAGE_SIZE = 50;
+export const MAX_EMAIL_POLL_PAGE_SIZE = 100;
+function quoteDslValue(value) {
+    if (/^[^\s"]+$/.test(value))
+        return value;
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function combineQ(q, domain) {
+    const parts = [
+        q?.trim(),
+        domain ? `domain:${quoteDslValue(domain.trim())}` : undefined,
+    ].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join(" ") : undefined;
+}
+export function normalizeIsoDate(value, label) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`${label} must be a valid date or ISO-8601 timestamp.`);
+    }
+    return parsed.toISOString();
+}
+export function filtersFromFlags(flags) {
+    return {
+        body: flags.body,
+        domain: flags.domain,
+        domainId: flags["domain-id"],
+        from: flags.from,
+        hasAttachment: flags["has-attachment"],
+        q: flags.q,
+        spamScoreGte: flags["spam-score-gte"],
+        spamScoreLt: flags["spam-score-lt"],
+        subject: flags.subject,
+        to: flags.to,
+    };
+}
+export function sinceFromFlags(flags) {
+    if (flags.since)
+        return normalizeIsoDate(flags.since, "--since");
+    return flags["include-existing"] ? undefined : new Date().toISOString();
+}
+export function buildEmailSearchQuery(params) {
+    const query = {
+        include_facets: "false",
+        limit: params.pageSize,
+        snippet: "false",
+        sort: "received_at_asc",
+    };
+    const q = combineQ(params.filters.q, params.filters.domain);
+    if (q)
+        query.q = q;
+    if (params.filters.body)
+        query.body = params.filters.body;
+    if (params.filters.domainId)
+        query.domain_id = params.filters.domainId;
+    if (params.filters.from)
+        query.from = params.filters.from;
+    if (params.filters.hasAttachment !== undefined) {
+        query.has_attachment = params.filters.hasAttachment ? "true" : "false";
+    }
+    if (params.filters.spamScoreGte !== undefined) {
+        query.spam_score_gte = params.filters.spamScoreGte;
+    }
+    if (params.filters.spamScoreLt !== undefined) {
+        query.spam_score_lt = params.filters.spamScoreLt;
+    }
+    if (params.filters.subject)
+        query.subject = params.filters.subject;
+    if (params.filters.to)
+        query.to = params.filters.to;
+    if (params.since)
+        query.date_from = params.since;
+    if (params.cursor)
+        query.cursor = params.cursor;
+    return query;
+}
+export function encodeReceivedAtSearchCursor(email) {
+    const raw = `r|${new Date(email.received_at).toISOString()}|${email.id}`;
+    return Buffer.from(raw, "utf8").toString("base64url");
+}
+export function cursorFromRows(rows) {
+    const last = rows.at(-1);
+    return last ? encodeReceivedAtSearchCursor(last) : null;
+}
+export function collectNewAcceptedEmails(rows, seenIds) {
+    const fresh = [];
+    for (const row of rows) {
+        if (row.status !== "accepted" && row.status !== "completed")
+            continue;
+        if (seenIds.has(row.id))
+            continue;
+        seenIds.add(row.id);
+        fresh.push(row);
+    }
+    return fresh;
+}
+export async function fetchEmailSearchPage(params) {
+    const result = await searchEmails({
+        client: params.apiClient.client,
+        query: buildEmailSearchQuery({
+            cursor: params.cursor,
+            filters: params.filters,
+            pageSize: params.pageSize,
+            since: params.since,
+        }),
+        responseStyle: "fields",
+    });
+    if (result.error)
+        return { ok: false, error: result.error };
+    const envelope = result.data;
+    const rows = envelope?.data ?? [];
+    return {
+        ok: true,
+        cursor: envelope?.meta.cursor ?? cursorFromRows(rows),
+        rows,
+    };
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}