@primitivedotdev/cli 0.24.0

package/dist/oclif/fish-completion.js

@@ -0,0 +1,87 @@
+import { openapiDocument, operationManifest, } from "@primitivedotdev/sdk/openapi";
+function fishEscape(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function toKebabCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+}
+function tagDescriptions() {
+    const descriptions = new Map();
+    const tags = (openapiDocument.tags ??
+        []);
+    for (const tag of tags) {
+        if (tag.name) {
+            descriptions.set(toKebabCase(tag.name), tag.description ?? tag.name);
+        }
+    }
+    return descriptions;
+}
+function operationCondition(operation) {
+    return `__fish_${fishEscape(BIN_PLACEHOLDER)}_using_operation ${fishEscape(operation.tagCommand)} ${fishEscape(operation.command)}`;
+}
+const BIN_PLACEHOLDER = "__BIN__";
+export function renderFishCompletion(binName) {
+    const tagDescriptionByCommand = tagDescriptions();
+    const topLevelTopics = [
+        ...new Set(operationManifest.map((operation) => operation.tagCommand)),
+    ];
+    const lines = [
+        `function __fish_${binName}_needs_command`,
+        "  set -l cmd (commandline -opc)",
+        "  test (count $cmd) -le 1",
+        "end",
+        "",
+        `function __fish_${binName}_topic_needs_subcommand`,
+        "  set -l cmd (commandline -opc)",
+        "  test (count $cmd) -eq 2",
+        '  and test "$cmd[2]" = "$argv[1]"',
+        "end",
+        "",
+        `function __fish_${binName}_using_operation`,
+        "  set -l cmd (commandline -opc)",
+        "  test (count $cmd) -ge 3",
+        '  and test "$cmd[2]" = "$argv[1]"',
+        '  and test "$cmd[3]" = "$argv[2]"',
+        "end",
+        "",
+        `function __fish_${binName}_using_root_command`,
+        "  set -l cmd (commandline -opc)",
+        "  test (count $cmd) -eq 2",
+        '  and test "$cmd[2]" = "$argv[1]"',
+        "end",
+        "",
+        `complete -c ${binName} -f -n '__fish_${binName}_needs_command' -a 'list-operations' -d 'List all generated API operations'`,
+        `complete -c ${binName} -f -n '__fish_${binName}_needs_command' -a 'completion' -d 'Show shell completion output or installation instructions'`,
+        `complete -c ${binName} -f -n '__fish_${binName}_needs_command' -a 'autocomplete' -d 'Install or display shell autocomplete for bash, zsh, and powershell'`,
+        `complete -c ${binName} -f -n '__fish_${binName}_needs_command' -a 'help' -d 'Display help for ${binName}'`,
+    ];
+    for (const topic of topLevelTopics) {
+        lines.push(`complete -c ${binName} -f -n '__fish_${binName}_needs_command' -a '${fishEscape(topic)}' -d '${fishEscape(tagDescriptionByCommand.get(topic) ?? topic)}'`);
+    }
+    lines.push(`complete -c ${binName} -f -n '__fish_${binName}_using_root_command completion' -a 'bash zsh powershell fish' -d 'Shell type'`);
+    for (const topic of topLevelTopics) {
+        const topicOperations = operationManifest.filter((operation) => operation.tagCommand === topic);
+        for (const operation of topicOperations) {
+            lines.push(`complete -c ${binName} -f -n '__fish_${binName}_topic_needs_subcommand ${fishEscape(topic)}' -a '${fishEscape(operation.command)}' -d '${fishEscape(operation.summary ?? `${operation.method} ${operation.path}`)}'`);
+            for (const parameter of [
+                ...operation.pathParams,
+                ...operation.queryParams,
+            ]) {
+                lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l '${fishEscape(parameter.name.replace(/_/g, "-"))}' -r -d '${fishEscape(parameter.description ?? parameter.name)}'`);
+            }
+            lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'api-key' -r -d 'Primitive API key (defaults to PRIMITIVE_API_KEY or saved primitive login credentials)'`);
+            if (operation.hasJsonBody) {
+                lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'body' -r -d 'JSON request body'`, `complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'body-file' -r -d 'Path to a JSON file used as the request body'`);
+            }
+            if (operation.binaryResponse) {
+                lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'output' -r -d 'Write binary response bytes to a file'`);
+            }
+        }
+    }
+    lines.push(`complete -c ${binName} -l help -d 'Show help for ${binName}'`, `complete -c ${binName} -l version -d 'Show version for ${binName}'`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/oclif/index.js

@@ -0,0 +1,167 @@
+import { Args, Command, Errors } from "@oclif/core";
+import { operationManifest, } from "@primitivedotdev/sdk/openapi";
+import { createOperationCommand } from "./api-command.js";
+import EmailsLatestCommand from "./commands/emails-latest.js";
+import EmailsWaitCommand from "./commands/emails-wait.js";
+import EmailsWatchCommand from "./commands/emails-watch.js";
+import FunctionsDeployCommand from "./commands/functions-deploy.js";
+import FunctionsInitCommand from "./commands/functions-init.js";
+import FunctionsRedeployCommand from "./commands/functions-redeploy.js";
+import FunctionsSetSecretCommand from "./commands/functions-set-secret.js";
+import LoginCommand from "./commands/login.js";
+import LogoutCommand from "./commands/logout.js";
+import SendCommand from "./commands/send.js";
+import WhoamiCommand from "./commands/whoami.js";
+import { renderFishCompletion } from "./fish-completion.js";
+class ListOperationsCommand extends Command {
+    static description = "List all generated API operations as JSON. Useful for piping to `jq` to discover available commands, their request/response schemas, and per-field descriptions. For inspecting a single operation in detail, prefer `primitive describe <command>`.";
+    static summary = "List all generated API operations (JSON)";
+    async run() {
+        this.log(JSON.stringify(operationManifest, null, 2));
+    }
+}
+// Looks up an operation manifest entry by its `<topic>:<command>` id
+// (e.g. `emails:get-email`). On miss, returns up to 5 closest
+// candidates by substring match so the caller can render a
+// "did you mean" hint. Pure function: no oclif config dependency,
+// so it's also unit-testable in isolation.
+export function lookupOperation(id) {
+    const trimmed = id.trim();
+    const sep = trimmed.indexOf(":");
+    const tag = sep === -1 ? "" : trimmed.slice(0, sep);
+    const cmd = sep === -1 ? trimmed : trimmed.slice(sep + 1);
+    const match = operationManifest.find((op) => op.command === cmd && op.tagCommand === tag) ?? null;
+    if (match)
+        return { match, candidates: [] };
+    const candidates = operationManifest
+        .filter((op) => op.command.includes(cmd) || op.tagCommand.includes(tag))
+        .slice(0, 5)
+        .map((op) => op.tagCommand ? `${op.tagCommand}:${op.command}` : op.command);
+    return { match: null, candidates };
+}
+// `primitive describe <command>` is the operation-detail inspector
+// the AGX walkthrough kept wanting. The information is already in
+// the operation manifest emitted by `list-operations`, but agents
+// don't intuitively reach for `list-operations | jq '.[] | select(...)'`
+// when they want to know "what does the from_email field on this
+// response actually mean." A direct command is more discoverable.
+//
+// Lookup is by the colon-joined command id (e.g. `emails:get-email`,
+// `sending:send-email`, `account:get-account`). For top-level
+// generated commands (without a topic), pass the bare command id.
+class DescribeCommand extends Command {
+    static args = {
+        command: Args.string({
+            description: "Command id to describe, in `<topic>:<command>` form (e.g. `emails:get-email`). Run `primitive list-operations | jq -r '.[] | \"\\(.tagCommand):\\(.command)\"'` to enumerate.",
+            required: true,
+        }),
+    };
+    static description = `Print the full operation manifest entry for a single API command, including the path, request schema, response schema, and per-field descriptions sourced from the OpenAPI spec.
+
+  The manifest entry's \`responseSchema\` carries the inlined JSON Schema for the operation's 200/201 \`data\` envelope contents (\`$ref\`s resolved). Use it to look up what specific response fields mean. Examples:
+
+      # Which of EmailDetail's sender-shaped fields is canonical?
+      primitive describe emails:get-email | jq '.responseSchema.properties | keys'
+      primitive describe emails:get-email | jq -r '.responseSchema.properties.from_email.description'
+
+      # What does each value of SentEmailStatus mean?
+      primitive describe sending:get-sent-email | jq -r '.responseSchema.properties.status.description'
+
+  \`requestSchema\` is the same shape for the request body when one exists. For a single field across many operations at once, use \`primitive list-operations | jq\` instead.`;
+    static summary = "Describe a single API operation in detail";
+    static examples = [
+        "<%= config.bin %> describe emails:get-email",
+        "<%= config.bin %> describe sending:send-email",
+    ];
+    async run() {
+        const { args } = await this.parse(DescribeCommand);
+        const { match, candidates } = lookupOperation(args.command);
+        if (!match) {
+            const hint = candidates.length > 0
+                ? `Did you mean: ${candidates.join(", ")}?`
+                : "Run `primitive list-operations` to enumerate.";
+            throw new Errors.CLIError(`Unknown operation \`${args.command.trim()}\`. ${hint}`, { exit: 1 });
+        }
+        this.log(JSON.stringify(match, null, 2));
+    }
+}
+class CompletionCommand extends Command {
+    static args = {
+        shell: Args.string({
+            description: "Shell type",
+            options: ["bash", "zsh", "powershell", "fish"],
+            required: true,
+        }),
+    };
+    static description = "Show shell completion output or installation instructions for supported shells";
+    static summary = "Show shell completion output or installation instructions";
+    async run() {
+        const { args } = await this.parse(CompletionCommand);
+        if (args.shell === "fish") {
+            this.log(renderFishCompletion(this.config.bin));
+            return;
+        }
+        await this.config.runCommand("autocomplete", [args.shell]);
+    }
+}
+function commandId(operation) {
+    return `${operation.tagCommand}:${operation.command}`;
+}
+const generatedCommands = Object.fromEntries(operationManifest.map((operation) => [
+    commandId(operation),
+    createOperationCommand(operation),
+]));
+export const COMMANDS = {
+    completion: CompletionCommand,
+    "list-operations": ListOperationsCommand,
+    // `describe` prints a single operation's full manifest entry
+    // (path, request schema, response schema, per-field descriptions).
+    // The same data is in `list-operations` but agents don't reach for
+    // `list-operations | jq` when they want to clarify a field meaning.
+    describe: DescribeCommand,
+    // `send` is the agent-grade shortcut for sending:send-email with
+    // sensible defaults (auto from-address, auto subject). The full
+    // operation stays available under sending:send-email for callers
+    // who want every flag.
+    send: SendCommand,
+    // `login` creates and stores an org-scoped CLI API key via browser approval.
+    login: LoginCommand,
+    // `logout` revokes the saved CLI API key and removes local credentials.
+    logout: LogoutCommand,
+    // `whoami` is the credentials smoke test. Prints the account the
+    // current API key authenticates as. AGX walkthroughs kept
+    // wanting this before risking a real call against a possibly-
+    // bad key.
+    whoami: WhoamiCommand,
+    // `emails:latest` is the inbox-triage shortcut: the most recent N
+    // inbound emails as a compact text table. emails:list-emails stays
+    // available for the full JSON envelope + cursor pagination.
+    "emails:latest": EmailsLatestCommand,
+    // `emails:watch` and `emails:wait` poll the search API for new matching
+    // inbound mail. `watch` defaults to a human table; `wait` defaults to JSONL.
+    "emails:watch": EmailsWatchCommand,
+    "emails:wait": EmailsWaitCommand,
+    // `functions:init` scaffolds a deployable Function project so a
+    // new author can go zero-to-deployed without writing the handler,
+    // package.json, build script, and tsconfig from scratch. The
+    // scaffolded handler imports from @primitivedotdev/sdk/api (the
+    // runtime-client subpath) and demonstrates client.send() so the
+    // first thing the author sees is the SDK pattern, not raw fetch.
+    "functions:init": FunctionsInitCommand,
+    // `functions:deploy` and `functions:redeploy` are file-input
+    // shortcuts for create-function / update-function. The underlying
+    // ops take `code` as a body string, which is awkward at the CLI
+    // for multi-line bundles; these read the bundle off disk and pass
+    // it through. The auto-generated functions:* operations stay
+    // available for callers that want the full surface.
+    "functions:deploy": FunctionsDeployCommand,
+    "functions:redeploy": FunctionsRedeployCommand,
+    // `functions:set-secret` is the one-call shortcut for "write a
+    // secret AND (optionally) push it live." The raw
+    // functions:set-function-secret / functions:create-function-secret
+    // operations only do the secret upsert; making the new value
+    // visible to the running handler requires a separate redeploy,
+    // which this shortcut folds in via --redeploy.
+    "functions:set-secret": FunctionsSetSecretCommand,
+    ...generatedCommands,
+};

package/dist/oclif/lint/raw-send-mail-fetch.js

@@ -0,0 +1,98 @@
+// Deploy-time lint for `functions:deploy --file <bundle>` and
+// `functions:redeploy --file <bundle>`. Looks for a raw
+// `fetch("...primitive.dev/.../send-mail", ...)` call in the bundle
+// text and, on a match, emits a stderr warning telling the author
+// to prefer `createPrimitiveClient` from `@primitivedotdev/sdk/api`.
+//
+// Why: a recurring pattern in agent-assisted Function deploys is to
+// copy the REST snippet from the docs and call `fetch` directly
+// against the Primitive send-mail endpoint, even after the docs
+// switched to leading with the SDK and `functions:init` ships a
+// scaffold that uses `createPrimitiveClient`. The SDK already
+// handles dual-host routing, error envelopes, and send-permission
+// gate denials; raw `fetch` re-discovers each of those by hand. The
+// warning is the catch-net at deploy time: the deploy still
+// proceeds.
+//
+// Scope by design:
+// - We only flag the empirically observed footgun: `/send-mail`.
+//   Not arbitrary calls to api.primitive.dev. Other endpoints have
+//   not surfaced the same pattern.
+// - We require the URL string literal to immediately follow the
+//   `fetch(` token (allowing whitespace) so we don't trip on a
+//   comment that merely mentions the URL. esbuild strips most
+//   comments anyway, but anchoring on `fetch(` keeps the rule
+//   honest without trying to parse JS.
+// - We only look at the bundle text passed in. Source maps and
+//   sibling files are not scanned.
+// - Variable-URL cases (`fetch(url, ...)` where `url` was assembled
+//   elsewhere) are accepted false negatives. The value here is
+//   catching the obvious inline-literal case, not full taint
+//   analysis.
+// Match `fetch(` then a string literal (single, double, or backtick)
+// whose contents include `primitive.dev` and end with `/send-mail`
+// (optionally with a query string or trailing path boundary). Examples
+// matched:
+//   fetch("https://api.primitive.dev/v1/send-mail", {...})
+//   fetch(`https://www.primitive.dev/api/v1/send-mail`, {...})
+//   fetch('https://primitive.dev/api/v1/send-mail?wait=1')
+//
+// The `[^`'"]*` inside the literal forbids the closing quote
+// character itself so we can't accidentally span across two adjacent
+// string literals. The trailing `(?![A-Za-z0-9_-])` forbids any
+// letter, digit, underscore, or hyphen immediately after `send-mail`
+// so `/send-mail-template-preview` does not trip the rule. (Plain
+// `\b` does not help here because `-` is itself a non-word character,
+// so `mail\b` still matches `mail-...`.)
+const RAW_SEND_MAIL_FETCH_REGEX = /fetch\s*\(\s*[`'"][^`'"]*primitive\.dev[^`'"]*\/send-mail(?![A-Za-z0-9_-])/g;
+// How much surrounding text to include on either side of the match
+// when building the sample snippet. Kept short on purpose: bundles
+// are minified and a 120-char window is enough to spot the call
+// without flooding stderr.
+const SNIPPET_PADDING = 60;
+export function detectRawSendMailFetch(bundleText) {
+    // Reset lastIndex defensively: this regex is module-scoped with
+    // the /g flag, so a prior call's state would skip the next match.
+    RAW_SEND_MAIL_FETCH_REGEX.lastIndex = 0;
+    const match = RAW_SEND_MAIL_FETCH_REGEX.exec(bundleText);
+    if (!match) {
+        return { found: false, sampleSnippet: null };
+    }
+    const start = Math.max(0, match.index - SNIPPET_PADDING);
+    const end = Math.min(bundleText.length, match.index + match[0].length + SNIPPET_PADDING);
+    const raw = bundleText.slice(start, end);
+    // Collapse newlines and runs of whitespace so the snippet is one
+    // readable line on stderr regardless of how the bundle was
+    // formatted.
+    const sampleSnippet = raw.replace(/\s+/g, " ").trim();
+    return { found: true, sampleSnippet };
+}
+// The stderr warning copy. Three beats: name the issue, name the
+// SDK alternative, link the docs. Plus a one-line "deploy proceeds"
+// reassurance. Kept punctuation simple (commas, periods, line
+// breaks) so it doesn't trip the no-em-dashes hook and so the lines
+// wrap predictably in a terminal.
+export const RAW_SEND_MAIL_FETCH_WARNING_LINES = [
+    "warning: this bundle calls fetch(...) against /send-mail directly.",
+    "The Primitive SDK exposes createPrimitiveClient from",
+    "@primitivedotdev/sdk/api which handles host routing, error envelopes,",
+    "and gate denials for you. See https://www.primitive.dev/docs/functions",
+    "for the recommended in-handler pattern. Continuing with deploy.",
+];
+export function formatRawSendMailFetchWarning(finding) {
+    const lines = [...RAW_SEND_MAIL_FETCH_WARNING_LINES];
+    if (finding.sampleSnippet) {
+        lines.push(`  found: ${finding.sampleSnippet}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+// Convenience: run the detector and, on a match, write the warning
+// to a stderr-shaped writer. Pulled out so both deploy and redeploy
+// share one code path and so the unit tests can pass a fake writer.
+export function emitRawSendMailFetchWarning(bundleText, write) {
+    const finding = detectRawSendMailFetch(bundleText);
+    if (finding.found) {
+        write(formatRawSendMailFetchWarning(finding));
+    }
+    return finding;
+}