Merge pull request #95 from datadog-labs/feat/wasm-build-support

feat(wasm): add WASM build support with DD_ACCESS_TOKEN auth

Author: platinummonkey

.github/workflows/ci.yml

@@ -233,6 +233,12 @@ jobs:
       - name: Verify binary
         run: ./pup --version
 
+      - name: Build WASM binary
+        env:
+          GOOS: js
+          GOARCH: wasm
+        run: go build -o pup.wasm .
+
   sast:
     name: Datadog Static Analysis
     runs-on: ubuntu-latest

.gitignore

@@ -5,6 +5,8 @@
 *.so
 *.dylib
 pup
+*.wasm
+wasm_exec.js
 coverage.html
 
 # Test binary, built with `go test -c`

.goreleaser.yml

@@ -7,6 +7,8 @@ before:
   hooks:
     # Ensure go.mod is tidy
     - go mod tidy
+    # Copy wasm_exec.js from Go toolchain for WASM builds
+    - cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" wasm_exec.js
 
 builds:
   # Darwin builds must have CGO_ENABLED=1 so the keyring library's
@@ -54,8 +56,28 @@ builds:
       - -X github.com/datadog-labs/pup/internal/version.GitCommit={{.Commit}}
       - -X github.com/datadog-labs/pup/internal/version.BuildDate={{.Date}}
 
+  # WASM build for browser/Deno/Bun/Workers runtimes.
+  # Uses GOOS=js (Fetch API networking) with stateless auth (DD_ACCESS_TOKEN).
+  - id: pup-wasm
+    binary: pup
+    main: .
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - js
+    goarch:
+      - wasm
+    ldflags:
+      - -s -w
+      - -X github.com/datadog-labs/pup/internal/version.Version={{.Version}}
+      - -X github.com/datadog-labs/pup/internal/version.GitCommit={{.Commit}}
+      - -X github.com/datadog-labs/pup/internal/version.BuildDate={{.Date}}
+
 archives:
   - id: pup
+    builds:
+      - pup-darwin
+      - pup-nix
     name_template: >-
       {{ .ProjectName }}_
       {{- .Version }}_
@@ -70,6 +92,15 @@ archives:
       - CHANGELOG.md
       - docs/*
 
+  - id: pup-wasm
+    builds:
+      - pup-wasm
+    name_template: "{{ .ProjectName }}_{{ .Version }}_WASM"
+    files:
+      - wasm_exec.js
+      - LICENSE
+      - README.md
+
 # Source archive
 source:
   enabled: true

README.md

@@ -234,11 +234,25 @@ export DD_SITE="datadoghq.com"  # Optional, defaults to datadoghq.com
 pup monitors list
 ```
 
+### Bearer Token Authentication (WASM / Headless)
+
+For WASM builds or environments without keychain access, use a pre-obtained bearer token:
+
+```bash
+export DD_ACCESS_TOKEN="your-oauth-access-token"
+export DD_SITE="datadoghq.com"
+
+pup monitors list
+```
+
+API key authentication (`DD_API_KEY` + `DD_APP_KEY`) also works in WASM. See the [WASM](#wasm) section below.
+
 ### Authentication Priority
 
 Pup checks for authentication in this order:
-1. **OAuth2 tokens** (from `pup auth login`) - Used if valid tokens exist
-2. **API keys** (from `DD_API_KEY` and `DD_APP_KEY`) - Used if OAuth tokens not available
+1. **`DD_ACCESS_TOKEN`** - Stateless bearer token (highest priority)
+2. **OAuth2 tokens** (from `pup auth login`) - Used if valid tokens exist
+3. **API keys** (from `DD_API_KEY` and `DD_APP_KEY`) - Used if OAuth tokens not available
 
 ## Usage
 
@@ -333,12 +347,94 @@ pup incidents get abc-123-def
 
 ## Environment Variables
 
-- `DD_API_KEY`: Datadog API key (optional if using OAuth2)
-- `DD_APP_KEY`: Datadog Application key (optional if using OAuth2)
+- `DD_ACCESS_TOKEN`: Bearer token for stateless auth (highest priority)
+- `DD_API_KEY`: Datadog API key (optional if using OAuth2 or DD_ACCESS_TOKEN)
+- `DD_APP_KEY`: Datadog Application key (optional if using OAuth2 or DD_ACCESS_TOKEN)
 - `DD_SITE`: Datadog site (default: datadoghq.com)
 - `DD_AUTO_APPROVE`: Auto-approve destructive operations (true/false)
 - `DD_TOKEN_STORAGE`: Token storage backend (keychain or file, default: auto-detect)
 
+## Agent Mode
+
+When pup is invoked by an AI coding agent, it automatically switches to **agent mode** which returns structured JSON responses optimized for machine consumption (including metadata, error details, and hints). Agent mode also auto-approves confirmation prompts.
+
+Agent mode is **auto-detected** when any of these environment variables are set to `1` or `true`:
+
+| Variable | Agent |
+|----------|-------|
+| `CLAUDE_CODE` or `CLAUDECODE` | Claude Code |
+| `CURSOR_AGENT` | Cursor |
+| `CODEX` or `OPENAI_CODEX` | OpenAI Codex |
+| `AIDER` | Aider |
+| `CLINE` | Cline |
+| `WINDSURF_AGENT` | Windsurf |
+| `GITHUB_COPILOT` | GitHub Copilot |
+| `AMAZON_Q` or `AWS_Q_DEVELOPER` | Amazon Q |
+| `GEMINI_CODE_ASSIST` | Gemini Code Assist |
+| `SRC_CODY` | Sourcegraph Cody |
+| `FORCE_AGENT_MODE` | Any agent (manual override) |
+
+You can also enable it explicitly with the `--agent` flag or by setting `FORCE_AGENT_MODE=1`:
+
+```bash
+# Auto-detected (e.g., running inside Claude Code)
+pup monitors list
+
+# Explicit flag
+pup monitors list --agent
+
+# Environment variable override
+FORCE_AGENT_MODE=1 pup monitors list
+```
+
+If you are integrating pup into an AI agent workflow, make sure the appropriate environment variable is set so responses are optimized for your agent. Without it, pup defaults to human-friendly output.
+
+## WASM
+
+Pup compiles to WebAssembly (`GOOS=js GOARCH=wasm`) for use in browser-like runtimes such as Deno, Bun, and Cloudflare Workers.
+
+### Building
+
+```bash
+GOOS=js GOARCH=wasm go build -o pup.wasm .
+
+# Copy the Go WASM support file
+cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" .
+```
+
+### Authentication
+
+The WASM build supports **stateless authentication** — keychain storage and browser-based OAuth login are not available. Use either `DD_ACCESS_TOKEN` or API keys:
+
+```bash
+# Option 1: Bearer token
+DD_ACCESS_TOKEN="your-token" DD_SITE="datadoghq.com" deno run pup.wasm monitors list
+
+# Option 2: API keys
+DD_API_KEY="your-api-key" DD_APP_KEY="your-app-key" deno run pup.wasm monitors list
+```
+
+The `pup auth status` command works in WASM and reports which credentials are configured. The `login`, `logout`, and `refresh` subcommands return guidance to use `DD_ACCESS_TOKEN`.
+
+### Limitations
+
+- No local token storage (keychain/file) — use `DD_ACCESS_TOKEN` or API keys
+- No browser-based OAuth login flow
+- Networking relies on the host runtime's Fetch API
+
+### Running with Deno
+
+```javascript
+import "./wasm_exec.js";
+
+const go = new Go();
+const wasm = await Deno.readFile("pup.wasm");
+const result = await WebAssembly.instantiate(wasm, go.importObject);
+go.run(result.instance);
+```
+
+Pre-built WASM archives (including `wasm_exec.js`) are available in [GitHub Releases](https://github.com/datadog-labs/pup/releases).
+
 ## Development
 
 ```bash
@@ -348,6 +444,9 @@ go test ./...
 # Build
 go build -o pup .
 
+# Build WASM
+GOOS=js GOARCH=wasm go build -o pup.wasm .
+
 # Run without building
 go run main.go monitors list
 ```

cmd/auth.go

@@ -3,6 +3,8 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2024-present Datadog, Inc.
 
+//go:build !js
+
 package cmd
 
 import (

cmd/auth_test.go

@@ -3,6 +3,8 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2024-present Datadog, Inc.
 
+//go:build !js
+
 package cmd
 
 import (

cmd/auth_wasm.go

@@ -0,0 +1,71 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2024-present Datadog, Inc.
+
+//go:build js
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+var authCmd = &cobra.Command{
+	Use:   "auth",
+	Short: "Authentication commands (limited in WASM)",
+	Long:  `In WASM builds, OAuth2 browser login is not available. Set DD_ACCESS_TOKEN or DD_API_KEY + DD_APP_KEY instead.`,
+}
+
+var authLoginCmd = &cobra.Command{
+	Use:   "login",
+	Short: "Login via OAuth2 (not available in WASM)",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return fmt.Errorf("OAuth2 browser login is not available in WASM builds; set DD_ACCESS_TOKEN instead")
+	},
+}
+
+var authStatusCmd = &cobra.Command{
+	Use:   "status",
+	Short: "Check authentication status",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		hasAccessToken := cfg.AccessToken != ""
+		hasAPIKeys := cfg.APIKey != "" && cfg.AppKey != ""
+
+		if hasAccessToken {
+			fmt.Println("Authenticated via DD_ACCESS_TOKEN")
+		} else if hasAPIKeys {
+			fmt.Println("Authenticated via API keys (DD_API_KEY + DD_APP_KEY)")
+		} else {
+			fmt.Println("Not authenticated")
+			fmt.Println("  Set DD_ACCESS_TOKEN or DD_API_KEY + DD_APP_KEY environment variables")
+		}
+		fmt.Printf("  Site: %s\n", cfg.Site)
+		return nil
+	},
+}
+
+var authLogoutCmd = &cobra.Command{
+	Use:   "logout",
+	Short: "Logout (not available in WASM)",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return fmt.Errorf("token storage is not available in WASM builds; unset DD_ACCESS_TOKEN to revoke access")
+	},
+}
+
+var authRefreshCmd = &cobra.Command{
+	Use:   "refresh",
+	Short: "Refresh access token (not available in WASM)",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return fmt.Errorf("token refresh is not available in WASM builds; set a new DD_ACCESS_TOKEN instead")
+	},
+}
+
+func init() {
+	authCmd.AddCommand(authLoginCmd)
+	authCmd.AddCommand(authStatusCmd)
+	authCmd.AddCommand(authLogoutCmd)
+	authCmd.AddCommand(authRefreshCmd)
+}

pkg/auth/storage/factory.go

@@ -3,6 +3,8 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2024-present Datadog, Inc.
 
+//go:build !js
+
 package storage
 
 import (
@@ -25,20 +27,6 @@ var (
 	mu sync.Mutex
 )
 
-// StorageOptions configures storage backend selection
-type StorageOptions struct {
-	// ForceBackend forces a specific storage backend
-	ForceBackend BackendType
-
-	// StorageDir overrides the storage directory (file backend only)
-	StorageDir string
-}
-
-const (
-	// StorageEnvVar is the environment variable to override storage backend
-	StorageEnvVar = "DD_TOKEN_STORAGE"
-)
-
 // GetStorage returns a storage instance, automatically detecting the best backend
 //
 // Selection priority:

pkg/auth/storage/factory_test.go

@@ -3,6 +3,8 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2024-present Datadog, Inc.
 
+//go:build !js
+
 package storage
 
 import (

pkg/auth/storage/factory_wasm.go

@@ -0,0 +1,36 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2024-present Datadog, Inc.
+
+//go:build js
+
+package storage
+
+import "fmt"
+
+// GetStorage returns an error on WASM directing users to DD_ACCESS_TOKEN.
+// Local token storage is not available in WASM runtimes.
+func GetStorage(_ *StorageOptions) (Storage, error) {
+	return nil, fmt.Errorf(
+		"token storage is not available in WASM builds; set DD_ACCESS_TOKEN instead",
+	)
+}
+
+// GetActiveBackend returns an empty backend type on WASM.
+func GetActiveBackend() BackendType {
+	return ""
+}
+
+// IsUsingSecureStorage always returns false on WASM.
+func IsUsingSecureStorage() bool {
+	return false
+}
+
+// GetStorageDescription returns a description indicating WASM mode.
+func GetStorageDescription() string {
+	return "not available (WASM)"
+}
+
+// ResetStorage is a no-op on WASM.
+func ResetStorage() {}