@primitivedotdev/cli 0.24.0

package/dist/oclif/commands/functions-init.js

@@ -0,0 +1,262 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Args, Command, Errors, Flags } from "@oclif/core";
+// `primitive functions:init <name>` stamps a deployable Function project
+// into ./<name>/ so a new author can go from zero to a deployed handler
+// in two commands: `npm install && npm run build` then
+// `primitive functions:deploy --name <name> --file ./dist/handler.js`.
+//
+// The scaffolded handler imports `createPrimitiveClient` from
+// `@primitivedotdev/sdk/api`, NOT from the package root. The root export
+// pulls in webhook helpers that depend on `node:crypto`, which breaks
+// Workers-style bundles. The `/api` subpath is the runtime-client
+// surface and is the documented import for in-handler use.
+// The SDK version range that ships in the scaffolded package.json's
+// dependencies. Pinned to the current shipped minor with a caret so
+// patch releases of the SDK pick up automatically. Update alongside
+// any minor or major version bump of the SDK; keep in lockstep with
+// the CLI's own @primitivedotdev/sdk dep range in cli-node/package.json
+// so scaffolded projects use the same SDK version the CLI was built
+// and tested against.
+const SDK_VERSION_RANGE = "^0.23.0";
+// esbuild version range. Pinned to the latest stable major used
+// elsewhere in the Primitive codebase for bundling Workers-style
+// handlers. Caret range so patch fixes flow in automatically.
+const ESBUILD_VERSION_RANGE = "^0.27.0";
+// Validate a directory name passed as the positional argument.
+// Matches a conservative slug shape: lowercase letters, digits,
+// hyphens, underscores. Rejecting weirder names up front prevents
+// surprises when the same string lands in package.json's `name`
+// field (which has its own validation rules) or in shell scripts.
+const VALID_NAME = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+export function isValidFunctionName(name) {
+    return VALID_NAME.test(name);
+}
+// File contents for the scaffolded project. Each renderer takes the
+// function name and returns the raw file body. Kept as named exports
+// so the unit test can assert content without having to spin up the
+// oclif command lifecycle.
+export function renderHandler() {
+    return `// env.PRIMITIVE_API_KEY is auto-injected by the Primitive Functions runtime.
+import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
+
+export default {
+  async fetch(
+    req: Request,
+    env: { PRIMITIVE_API_KEY: string },
+  ): Promise<Response> {
+    const event = (await req.json()) as {
+      email: { headers: { from?: string; subject?: string } };
+    };
+    const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });
+
+    const reply = await client.send({
+      from: "you@your-domain.primitive.email",
+      to: event.email.headers.from ?? "you@your-domain.primitive.email",
+      subject: \`Re: \${event.email.headers.subject ?? ""}\`,
+      bodyText: "Got your message.",
+    });
+
+    return Response.json({ ok: true, reply });
+  },
+};
+`;
+}
+export function renderPackageJson(name) {
+    const pkg = {
+        name,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+            build: "node build.mjs",
+            deploy: `npm run build && primitive functions:deploy --name ${name} --file ./dist/handler.js`,
+            redeploy: "npm run build && primitive functions:redeploy --id $PRIMITIVE_FUNCTION_ID --file ./dist/handler.js",
+        },
+        dependencies: {
+            "@primitivedotdev/sdk": SDK_VERSION_RANGE,
+        },
+        devDependencies: {
+            esbuild: ESBUILD_VERSION_RANGE,
+            typescript: "^5.7.2",
+        },
+    };
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+export function renderBuildMjs() {
+    return `import { build } from "esbuild";
+
+// Bundle handler.ts into a single ESM file suitable for the Primitive
+// Functions runtime. The runtime is a Workers-style environment, so
+// we pick the "worker" / "browser" export conditions on @primitivedotdev/sdk
+// (which routes us to the /api subpath safely without dragging in
+// node:crypto-dependent webhook helpers).
+
+await build({
+  entryPoints: ["handler.ts"],
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: "es2022",
+  conditions: ["worker", "browser"],
+  outfile: "dist/handler.js",
+});
+`;
+}
+export function renderTsconfig() {
+    const tsconfig = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            strict: true,
+            lib: ["ES2022", "WebWorker"],
+            types: [],
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ["handler.ts"],
+    };
+    return `${JSON.stringify(tsconfig, null, 2)}\n`;
+}
+export function renderGitignore() {
+    return "node_modules\ndist\n";
+}
+export function renderReadme(name) {
+    return `# ${name}
+
+## What this is
+
+A Primitive Function: a JavaScript handler that runs on inbound mail.
+It receives the \`email.received\` event, demonstrates a basic reply
+via the Primitive SDK, and returns a JSON envelope.
+
+## Develop
+
+\`\`\`
+npm install
+npm run build
+\`\`\`
+
+## Deploy
+
+\`\`\`
+npm run deploy
+\`\`\`
+
+The deploy step calls \`primitive functions:deploy\` (provided by the
+\`@primitivedotdev/cli\` package; install with
+\`npm install -g @primitivedotdev/cli\` or run via
+\`npx @primitivedotdev/cli@latest <command>\`). It requires
+\`PRIMITIVE_API_KEY\` to be set in your shell (or pass \`--api-key\`).
+Run \`primitive login\` once to save a key in your CLI config if you
+prefer that to an env var.
+`;
+}
+// Files written by the scaffolder, in the order they're created.
+// Exported as a pure function so the unit test can verify the
+// exact content of every file without invoking the command and
+// touching disk.
+export function scaffoldFiles(name) {
+    return [
+        { contents: renderHandler(), relativePath: "handler.ts" },
+        { contents: renderPackageJson(name), relativePath: "package.json" },
+        { contents: renderBuildMjs(), relativePath: "build.mjs" },
+        { contents: renderTsconfig(), relativePath: "tsconfig.json" },
+        { contents: renderGitignore(), relativePath: ".gitignore" },
+        { contents: renderReadme(name), relativePath: "README.md" },
+    ];
+}
+// Write the scaffold to disk. Refuses to overwrite an existing
+// directory: if `outDir` exists the function throws and leaves the
+// filesystem untouched. On any write error after creating the
+// directory, the partially-written tree is cleaned up so re-runs
+// see a clean slate. Exported for unit testing.
+export 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 written = [];
+    // Create the target directory with recursive: false so the check
+    // and the create happen in one syscall. mkdirSync throws EEXIST
+    // atomically if the path already exists, which closes the TOCTOU
+    // window between a separate existsSync check and the mkdir call.
+    try {
+        mkdirSync(params.outDir, { recursive: false });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EEXIST") {
+            throw new Errors.CLIError(`Target directory already exists: ${params.outDir}. Refusing to overwrite. Remove it or pick a different --out-dir.`, { exit: 1 });
+        }
+        if (code === "ENOENT") {
+            throw new Errors.CLIError(`Parent directory does not exist for ${params.outDir}. Create it first or pick a different --out-dir.`, { exit: 1 });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Errors.CLIError(`Failed to create ${params.outDir}: ${detail}`, {
+            exit: 1,
+        });
+    }
+    try {
+        for (const file of files) {
+            const fullPath = resolve(params.outDir, file.relativePath);
+            mkdirSync(dirname(fullPath), { recursive: true });
+            writeFileSync(fullPath, file.contents, "utf8");
+            written.push(fullPath);
+        }
+    }
+    catch (error) {
+        // Roll back the partial scaffold so the user can retry without
+        // tripping the "directory already exists" guard above.
+        try {
+            rmSync(params.outDir, { force: true, recursive: true });
+        }
+        catch {
+            // Best-effort cleanup; surface the original error regardless.
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Errors.CLIError(`Failed to write scaffold to ${params.outDir}: ${detail}`, { exit: 1 });
+    }
+    return { written };
+}
+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.
+
+  The scaffolded handler imports \`createPrimitiveClient\` from
+  \`@primitivedotdev/sdk/api\` and demonstrates the canonical pattern:
+  parse the email.received event, send a reply via the SDK, return a
+  JSON envelope. The build script uses esbuild's JS API and emits
+  ./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>/.`;
+    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 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.",
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FunctionsInitCommand);
+        const outDir = resolve(flags["out-dir"] ?? `./${args.name}`);
+        writeScaffold({ name: args.name, outDir });
+        this.log(`Scaffolded ${outDir}.`);
+        this.log("Next:");
+        this.log(`  cd ${outDir}`);
+        this.log("  npm install");
+        this.log("  npm run build");
+        this.log(`  primitive functions:deploy --name ${args.name} --file ./dist/handler.js`);
+    }
+}
+export default FunctionsInitCommand;

package/dist/oclif/commands/functions-redeploy.js

@@ -0,0 +1,112 @@
+import { Command, Flags } from "@oclif/core";
+import { PrimitiveApiClient, updateFunction } from "@primitivedotdev/sdk/api";
+import { extractErrorPayload, readTextFileFlag, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+import { emitRawSendMailFetchWarning } from "../lint/raw-send-mail-fetch.js";
+// `primitive functions:redeploy` is the agent-grade shortcut for
+// `functions:update-function`. Same file-reading ergonomic as
+// functions:deploy but for an existing function. Use this to push a
+// new bundle, OR to refresh secret bindings: passing the
+// previously-deployed bundle (or any equivalent file) re-runs the
+// deploy and refreshes env from the secrets table, which is how
+// secret writes go live.
+class FunctionsRedeployCommand extends Command {
+    static description = `Update or redeploy a function from a bundled handler file. Agent-grade shortcut for functions:update-function.
+
+  Use to push a new bundle OR to refresh secret bindings into the
+  running handler. The same file is fine for both: the deploy reads
+  the bindings table fresh on every call, so passing the existing
+  bundle picks up any secret writes since the last deploy.`;
+    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",
+    ];
+    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,
+        }),
+        id: Flags.string({
+            description: "Function id (UUID). The function must already exist.",
+            required: true,
+        }),
+        file: Flags.string({
+            description: "Path to the bundled ESM handler file. Loaded as the `code` body field.",
+            required: true,
+        }),
+        "source-map-file": Flags.string({
+            description: "Optional path to a source map for the bundle. Used to symbolicate stack traces in the function's logs.",
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsRedeployCommand);
+        await runWithTiming(flags.time, async () => {
+            // Reads inside the timed block: --time captures disk I/O too,
+            // which is the latency the flag is meant to surface.
+            const code = readTextFileFlag(flags.file, "--file");
+            const sourceMap = flags["source-map-file"]
+                ? readTextFileFlag(flags["source-map-file"], "--source-map-file")
+                : undefined;
+            // Non-blocking deploy-time lint: if the bundle has a raw
+            // fetch(...) call against /send-mail, nudge the author toward
+            // `createPrimitiveClient` from `@primitivedotdev/sdk/api`.
+            // Same check as functions:deploy; warning goes to stderr and
+            // the deploy continues regardless.
+            emitRawSendMailFetchWarning(code, (chunk) => process.stderr.write(chunk));
+            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 authFailureContext = {
+                auth,
+                baseUrlOverridden,
+                configDir: this.config.configDir,
+            };
+            const result = await updateFunction({
+                path: { id: flags.id },
+                body: {
+                    code,
+                    ...(sourceMap !== undefined ? { sourceMap } : {}),
+                },
+                client: apiClient.client,
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                const errorPayload = extractErrorPayload(result.error);
+                writeErrorWithHints(errorPayload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    ...authFailureContext,
+                    payload: errorPayload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+        });
+    }
+}
+export default FunctionsRedeployCommand;

package/dist/oclif/commands/functions-set-secret.js

@@ -0,0 +1,212 @@
+import { Command, Flags } from "@oclif/core";
+import { getFunction, PrimitiveApiClient, setFunctionSecret, updateFunction, } from "@primitivedotdev/sdk/api";
+import { extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+// Pure-ish orchestration of the set-secret + optional redeploy
+// flow. Pulled out as a named export so the unit test can drive
+// both the happy path and each error stage with a fake API
+// surface, without spinning up a real client or the oclif
+// command lifecycle.
+//
+// The redeploy step uses the function's CURRENT code (fetched via
+// getFunction) as the new bundle. This is the documented way to
+// "refresh secret bindings without changing the handler": the
+// server-side deploy reads the secrets table fresh on every call,
+// so re-deploying the same code picks up the secret we just wrote.
+export async function runSetSecret(api, params) {
+    const setResult = await api.setSecret({
+        id: params.id,
+        key: params.key,
+        value: params.value,
+    });
+    if (setResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(setResult.error),
+            stage: "set-secret",
+        };
+    }
+    const secret = setResult.data?.data;
+    if (!secret) {
+        // Server returned 2xx with no `data` body. Treat as an error
+        // so we don't fabricate a success payload; this should not
+        // happen in practice but the shape forces us to handle it.
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Secret write returned no data",
+            },
+            stage: "set-secret",
+        };
+    }
+    if (!params.redeploy) {
+        return { kind: "ok", result: { secret } };
+    }
+    const fnResult = await api.getFunction({ id: params.id });
+    if (fnResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(fnResult.error),
+            stage: "get-function",
+        };
+    }
+    const fn = fnResult.data?.data;
+    if (!fn) {
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Could not read current function code for redeploy",
+            },
+            stage: "get-function",
+        };
+    }
+    const updateResult = await api.updateFunction({
+        code: fn.code,
+        id: params.id,
+    });
+    if (updateResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(updateResult.error),
+            stage: "redeploy",
+        };
+    }
+    const redeployed = updateResult.data?.data;
+    if (!redeployed) {
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Redeploy returned no data",
+            },
+            stage: "redeploy",
+        };
+    }
+    return { kind: "ok", result: { redeploy: redeployed, secret } };
+}
+class FunctionsSetSecretCommand extends Command {
+    static description = `Write a function secret and optionally redeploy so the new value lands in the running handler. Agent-grade shortcut for functions:set-function-secret + functions:redeploy.
+
+  Without --redeploy this is a plain secret upsert: the value is
+  encrypted at rest but is NOT visible to the running handler until
+  the next deploy. Pass --redeploy to re-run the deploy with the
+  function's current code in the same call, which refreshes the
+  binding set with the value you just wrote.
+
+  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.`;
+    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 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,
+        }),
+        id: Flags.string({
+            description: "Function id (UUID). The function must already exist.",
+            required: true,
+        }),
+        key: Flags.string({
+            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,
+        }),
+        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: source maps are stored only on the runtime side and getFunction does not return them, so this redeploy drops any previously-uploaded source map. If preserving stack-trace symbolication matters, use `functions:redeploy --file <bundle.js> --source-map-file <bundle.js.map>` instead.",
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsSetSecretCommand);
+        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 authFailureContext = {
+                auth,
+                baseUrlOverridden,
+                configDir: this.config.configDir,
+            };
+            // Adapter: thin wrappers around the generated SDK calls,
+            // routed through host 1 (apiClient.client). The secrets and
+            // function-detail endpoints are not on host 2.
+            const apiSurface = {
+                getFunction: (p) => getFunction({
+                    client: apiClient.client,
+                    path: { id: p.id },
+                    responseStyle: "fields",
+                }),
+                setSecret: (p) => setFunctionSecret({
+                    body: { value: p.value },
+                    client: apiClient.client,
+                    path: { id: p.id, key: p.key },
+                    responseStyle: "fields",
+                }),
+                updateFunction: (p) => updateFunction({
+                    body: { code: p.code },
+                    client: apiClient.client,
+                    path: { id: p.id },
+                    responseStyle: "fields",
+                }),
+            };
+            const outcome = await runSetSecret(apiSurface, {
+                id: flags.id,
+                key: flags.key,
+                redeploy: flags.redeploy === true,
+                value: flags.value,
+            });
+            if (outcome.kind === "error") {
+                // Stage-specific framing on stderr so callers can tell
+                // whether the secret landed before a failed redeploy. The
+                // JSON envelope still goes through writeErrorWithHints so
+                // any actionable hint (e.g. unauthorized) is surfaced.
+                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");
+                }
+                else if (outcome.stage === "redeploy") {
+                    process.stderr.write("Secret was written, but the redeploy step failed; the secret is NOT yet live. Inspect the function's deploy_error and re-run `primitive functions:redeploy --id <id> --file <bundle>` once the cause is fixed.\n");
+                }
+                writeErrorWithHints(outcome.payload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    ...authFailureContext,
+                    payload: outcome.payload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            this.log(JSON.stringify(outcome.result, null, 2));
+        });
+    }
+}
+export default FunctionsSetSecretCommand;