Merge pull request #242 from paperclipinc/staging

Promote staging → main: guided credential connect (PR F)

Author: stubbi

packages/adapter-utils/src/index.ts

@@ -36,6 +36,8 @@ export type {
   StdoutLineParser,
   CLIAdapterModule,
   CreateConfigValues,
+  AdapterCredentialOption,
+  AdapterCredentialSetup,
 } from "./types.js";
 export type {
   SessionCompactionPolicy,

packages/adapter-utils/src/types.ts

@@ -554,3 +554,41 @@ export interface CreateConfigValues {
   headersJson?: string;
   password?: string;
 }
+
+// ---------------------------------------------------------------------------
+// Adapter credential setup — declarative UI descriptors for guided credential configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * A single credential option that an adapter accepts.
+ *
+ * Describes how to configure one environment variable (e.g., an API key or token),
+ * with hints and optional setup commands/URLs to help users obtain and configure it.
+ */
+export interface AdapterCredentialOption {
+  /** The environment variable name (e.g., "ANTHROPIC_API_KEY") */
+  envKey: string;
+  /** The kind of credential */
+  kind: "api_key" | "subscription_token";
+  /** Display label for the credential (e.g., "Anthropic API key") */
+  label: string;
+  /** Optional hint text explaining what the credential is for and how to use it */
+  hint?: string;
+  /** Optional command users can run to set up this credential (e.g., "claude setup-token") */
+  setupCommand?: string;
+  /** Optional URL where users can obtain/manage this credential (e.g., console URL) */
+  setupUrl?: string;
+  /** Optional placeholder text for the input field (e.g., "sk-ant-…") */
+  placeholder?: string;
+}
+
+/**
+ * A complete credential setup descriptor for an adapter.
+ *
+ * Declares all environment variables an adapter accepts and provides
+ * UI-friendly guidance for each one.
+ */
+export interface AdapterCredentialSetup {
+  /** The list of credential options this adapter accepts */
+  options: AdapterCredentialOption[];
+}

packages/adapters/claude-local/src/ui/credential-setup.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { claudeLocalCredentialSetup } from "./credential-setup.js";
+
+describe("claudeLocalCredentialSetup", () => {
+  it("exports credential options with correct envKeys", () => {
+    const envKeys = claudeLocalCredentialSetup.options.map(o => o.envKey);
+    expect(envKeys).toEqual(["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"]);
+  });
+
+  it("configures subscription_token option with setupCommand", () => {
+    const tokenOption = claudeLocalCredentialSetup.options.find(o => o.envKey === "CLAUDE_CODE_OAUTH_TOKEN");
+    expect(tokenOption).toBeDefined();
+    expect(tokenOption?.kind).toBe("subscription_token");
+    expect(tokenOption?.setupCommand).toBe("claude setup-token");
+  });
+
+  it("includes hint text mentioning both quota and extra usage for subscription_token", () => {
+    const tokenOption = claudeLocalCredentialSetup.options.find(o => o.envKey === "CLAUDE_CODE_OAUTH_TOKEN");
+    expect(tokenOption?.hint).toContain("quota");
+    expect(tokenOption?.hint).toContain("extra usage");
+  });
+});

packages/adapters/claude-local/src/ui/credential-setup.ts

@@ -0,0 +1,22 @@
+import type { AdapterCredentialSetup } from "@paperclipai/adapter-utils";
+
+export const claudeLocalCredentialSetup: AdapterCredentialSetup = {
+  options: [
+    {
+      envKey: "ANTHROPIC_API_KEY",
+      kind: "api_key",
+      label: "Anthropic API key",
+      hint: "Create a key in the Anthropic Console. Usage bills to your Anthropic API account.",
+      setupUrl: "https://console.anthropic.com/settings/keys",
+      placeholder: "sk-ant-…",
+    },
+    {
+      envKey: "CLAUDE_CODE_OAUTH_TOKEN",
+      kind: "subscription_token",
+      label: "Claude Pro/Max subscription token",
+      hint: "Mint a long-lived token with `claude setup-token` on a machine where Claude Code is logged in. Token-only auth has no usage/quota reporting, and subscription usage in third-party contexts may draw from your Anthropic \"extra usage\" credits.",
+      setupCommand: "claude setup-token",
+      placeholder: "sk-ant-oat01-…",
+    },
+  ],
+};

packages/adapters/claude-local/src/ui/index.ts

@@ -1,2 +1,3 @@
 export { parseClaudeStdoutLine } from "./parse-stdout.js";
 export { buildClaudeLocalConfig } from "./build-config.js";
+export { claudeLocalCredentialSetup } from "./credential-setup.js";

packages/adapters/codex-local/src/ui/credential-setup.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { codexLocalCredentialSetup } from "./credential-setup.js";
+
+describe("codexLocalCredentialSetup", () => {
+  it("exports credential options with correct envKeys", () => {
+    const envKeys = codexLocalCredentialSetup.options.map(o => o.envKey);
+    expect(envKeys).toEqual(["OPENAI_API_KEY"]);
+  });
+
+  it("configures api_key option with correct label and setupUrl", () => {
+    const apiKeyOption = codexLocalCredentialSetup.options.find(o => o.envKey === "OPENAI_API_KEY");
+    expect(apiKeyOption).toBeDefined();
+    expect(apiKeyOption?.kind).toBe("api_key");
+    expect(apiKeyOption?.label).toBe("OpenAI API key");
+    expect(apiKeyOption?.setupUrl).toBe("https://platform.openai.com/api-keys");
+    expect(apiKeyOption?.placeholder).toBe("sk-…");
+  });
+
+  it("includes hint mentioning codex login and CODEX_HOME sync as ChatGPT-subscription alternative", () => {
+    const apiKeyOption = codexLocalCredentialSetup.options.find(o => o.envKey === "OPENAI_API_KEY");
+    expect(apiKeyOption?.hint).toContain("codex login");
+    expect(apiKeyOption?.hint).toContain("CODEX_HOME");
+  });
+});

packages/adapters/codex-local/src/ui/credential-setup.ts

@@ -0,0 +1,14 @@
+import type { AdapterCredentialSetup } from "@paperclipai/adapter-utils";
+
+export const codexLocalCredentialSetup: AdapterCredentialSetup = {
+  options: [
+    {
+      envKey: "OPENAI_API_KEY",
+      kind: "api_key",
+      label: "OpenAI API key",
+      hint: "Create a key in the OpenAI API console. Alternatively, you can log in with `codex login` locally and Paperclip's CODEX_HOME sync will ship the credential to remote runs.",
+      setupUrl: "https://platform.openai.com/api-keys",
+      placeholder: "sk-…",
+    },
+  ],
+};

packages/adapters/codex-local/src/ui/index.ts

@@ -1,2 +1,3 @@
 export { parseCodexStdoutLine } from "./parse-stdout.js";
 export { buildCodexLocalConfig } from "./build-config.js";
+export { codexLocalCredentialSetup } from "./credential-setup.js";

packages/adapters/cursor-local/src/ui/credential-setup.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { cursorLocalCredentialSetup } from "./credential-setup.js";
+
+describe("cursorLocalCredentialSetup", () => {
+  it("exports credential options with correct envKeys", () => {
+    const envKeys = cursorLocalCredentialSetup.options.map(o => o.envKey);
+    expect(envKeys).toEqual(["CURSOR_API_KEY"]);
+  });
+
+  it("configures api_key option with correct label and setupUrl", () => {
+    const apiKeyOption = cursorLocalCredentialSetup.options.find(o => o.envKey === "CURSOR_API_KEY");
+    expect(apiKeyOption).toBeDefined();
+    expect(apiKeyOption?.kind).toBe("api_key");
+    expect(apiKeyOption?.label).toBe("Cursor API key");
+    expect(apiKeyOption?.setupUrl).toBe("https://cursor.com/dashboard");
+    expect(apiKeyOption?.placeholder).toBe("key_…");
+  });
+});

packages/adapters/cursor-local/src/ui/credential-setup.ts

@@ -0,0 +1,13 @@
+import type { AdapterCredentialSetup } from "@paperclipai/adapter-utils";
+
+export const cursorLocalCredentialSetup: AdapterCredentialSetup = {
+  options: [
+    {
+      envKey: "CURSOR_API_KEY",
+      kind: "api_key",
+      label: "Cursor API key",
+      setupUrl: "https://cursor.com/dashboard",
+      placeholder: "key_…",
+    },
+  ],
+};