@project-ajax/sdk 0.0.50 → 0.0.52

package/src/capabilities/tool.test.ts

@@ -1,4 +1,12 @@
-import { describe, expect, it } from "vitest";
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	type Mock,
+	vi,
+} from "vitest";
 import {
 	InvalidToolInputError,
 	InvalidToolOutputError,
@@ -7,6 +15,18 @@ import {
 } from "./tool.js";
 
 describe("tool", () => {
+	let stdoutSpy: Mock<typeof process.stdout.write>;
+
+	beforeEach(() => {
+		stdoutSpy = vi
+			.spyOn(process.stdout, "write")
+			.mockImplementation(() => true);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
 	it("sync execution", async () => {
 		const myTool = tool<{ name: string }, string>({
 			title: "Say Hello",
@@ -30,6 +50,10 @@ describe("tool", () => {
 		if (result._tag === "success") {
 			expect(result.value).toBe("Hello, Alice!");
 		}
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>"Hello, Alice!"</output>\n`,
+		);
 	});
 
 	it("async execution", async () => {
@@ -57,6 +81,10 @@ describe("tool", () => {
 		if (result._tag === "success") {
 			expect(result.value).toEqual({ data: "Data for ID 42" });
 		}
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"data":"Data for ID 42"}</output>\n`,
+		);
 	});
 
 	it("execution error", async () => {
@@ -81,6 +109,10 @@ describe("tool", () => {
 			expect(result.error).toBeInstanceOf(ToolExecutionError);
 			expect(result.error.message).toBe("Something went wrong");
 		}
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"_tag":"error","error":{"name":"ToolExecutionError","message":"Something went wrong"}}</output>\n`,
+		);
 	});
 
 	it("invalid input", async () => {
@@ -107,6 +139,12 @@ describe("tool", () => {
 			expect(result.error).toBeInstanceOf(InvalidToolInputError);
 			expect(result.error.message).toContain("name");
 		}
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`\n<output>{"_tag":"error","error":{"name":"InvalidToolInputError"`,
+			),
+		);
 	});
 
 	it("invalid output", async () => {
@@ -140,6 +178,12 @@ describe("tool", () => {
 			expect(result.error).toBeInstanceOf(InvalidToolOutputError);
 			expect(result.error.message).toContain("result");
 		}
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`\n<output>{"_tag":"error","error":{"name":"InvalidToolOutputError"`,
+			),
+		);
 	});
 
 	it("invalid output with custom output schema", async () => {
@@ -181,5 +225,11 @@ describe("tool", () => {
 			expect(result.error).toBeInstanceOf(InvalidToolOutputError);
 			expect(result.error.message).toContain("message");
 		}
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`\n<output>{"_tag":"error","error":{"name":"InvalidToolOutputError"`,
+			),
+		);
 	});
 });

package/src/cli/api/client.ts

@@ -29,65 +29,24 @@ export interface ApiError {
 	};
 }
 
-/**
- * Get the base URL for the given environment
- */
-export function baseUrl({
-	environment,
-	override,
-}: {
-	environment: Environment;
-	override?: string | undefined;
-}): string {
-	if (override) {
-		return override;
-	}
-
-	switch (environment) {
-		case "local":
-			return "http://localhost:3000";
-		case "staging":
-			return "https://staging.notion.so";
-		case "dev":
-			return "https://dev.notion.so";
-		case "prod":
-			return "https://www.notion.so";
-	}
-}
-
-/**
- * Get the base API URL for the given environment
- */
-function baseApiUrl({
-	environment,
-	override,
-}: {
-	environment: Environment;
-	override?: string | undefined;
-}): string {
-	return `${baseUrl({ environment, override })}/api/v3`;
-}
-
 /**
  * API client for making authenticated requests to Workers endpoints
  */
 export class ApiClient {
 	readonly #token: string;
-	readonly #env: Environment;
 	readonly #baseUrl: string | undefined;
 	readonly #cellId: string;
 	readonly #writer: Writer;
 
 	constructor(config: ApiClientConfig) {
 		this.#token = config.token;
-		this.#env = config.environment;
 		this.#baseUrl = config.baseUrl;
 		this.#cellId = config.cellId;
 		this.#writer = config.writer;
 	}
 
-	private baseApiUrl() {
-		return baseApiUrl({ environment: this.#env, override: this.#baseUrl });
+	#baseApiUrl() {
+		return `${this.#baseUrl}/api/v3`;
 	}
 
 	/**
@@ -113,7 +72,7 @@ export class ApiClient {
 			throw new Error("Endpoint must start with a slash (/)");
 		}
 
-		const url = `${this.baseApiUrl()}${endpoint}`;
+		const url = `${this.#baseApiUrl()}${endpoint}`;
 
 		this.#writer.debug(`Fetching ${url}`);
 		this.#writer.debug(

package/src/cli/commands/.cursor/rules/testing-commands.mdc

@@ -0,0 +1,212 @@
+---
+description: Testing patterns for CLI command implementations
+globs:
+  - "**/*.impl.test.ts"
+alwaysApply: false
+---
+
+# Testing CLI Commands
+
+## Understanding buildHandler
+
+Commands are wrapped with `buildHandler` which:
+1. Returns a function that accepts `(flags, ...args)`
+2. Internally loads config using `Config.load()`
+3. Requires a `this` context with `process`, `fs`, `os`, `path`, and `writer`
+
+## Test Structure Pattern
+
+```typescript
+describe("commandName", () => {
+  let stderrSpy: Mock<typeof process.stderr.write>; // or stdoutSpy
+
+  beforeEach(() => {
+    stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+  });
+
+  it("does something", async () => {
+    // 1. Create a mock config with the desired state
+    const mockConfig = await createTestConfig({
+      token: "test-token",
+      workerId: null,
+      environment: "local",
+      baseUrl: "http://localhost:3000",
+    });
+
+    // 2. Spy on Config.load to return your mock config
+    vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+
+    // 3. Spy on config methods to verify they're called
+    const setTokenSpy = vi.spyOn(mockConfig, "setToken");
+
+    // 4. Create a base context
+    const context = createBaseContext();
+
+    // 5. Call the handler with .call(context, flags, ...args)
+    await commandHandler.call(context, baseFlags, "arg1", "arg2");
+
+    // 6. Assert on spies and output
+    expect(setTokenSpy).toHaveBeenCalledWith("expected-value");
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Expected message"),
+    );
+  });
+});
+```
+
+## Key Testing Patterns
+
+### 1. Mocking Config.load
+
+Always mock `Config.load` to return your test config. The handler loads config internally, so you can't pass it directly.
+
+```typescript
+const mockConfig = await createTestConfig({
+  token: null,
+  workerId: null,
+  environment: "local",
+  baseUrl: "http://localhost:3000",
+});
+
+vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+```
+
+### 2. Creating Context
+
+Handlers expect a context with specific properties:
+
+```typescript
+function createBaseContext() {
+  return {
+    writer: new Writer({ debugEnabled: false }),
+    process,
+    fs,
+    os,
+    path,
+  };
+}
+```
+
+### 3. Calling Handlers
+
+Use `.call()` to provide the context:
+
+```typescript
+await handler.call(context, flags, ...args);
+```
+
+**Don't** call the handler directly without context - it will fail because `this.process` will be undefined.
+
+### 4. Verifying Config Updates
+
+Spy on config methods to verify they were called, rather than checking state directly:
+
+```typescript
+const setTokenSpy = vi.spyOn(mockConfig, "setToken");
+await handler.call(context, flags);
+expect(setTokenSpy).toHaveBeenCalledWith(expectedValue);
+```
+
+Config methods like `setToken()`, `setEnvironment()`, and `setWorkerId()` write to the file asynchronously, so checking the config state immediately won't work.
+
+### 5. Mocking External Dependencies
+
+Mock external modules before importing the implementation:
+
+```typescript
+vi.mock("../utils/openUrl.js", () => ({
+  openNotionUrl: vi.fn().mockResolvedValue(undefined),
+}));
+
+import { commandHandler } from "./command.impl.js";
+import { openNotionUrl } from "../utils/openUrl.js";
+
+// In your test:
+expect(openNotionUrl).toHaveBeenCalledWith("local", "http://...");
+
+// For one-time failures:
+vi.mocked(openNotionUrl).mockRejectedValueOnce(new Error("Failed"));
+```
+
+### 6. Capturing stdout/stderr
+
+When testing output, spy on the write methods and check the content:
+
+```typescript
+let stderrSpy: Mock<typeof process.stderr.write>;
+
+beforeEach(() => {
+  stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation(() => true);
+});
+
+// For single messages:
+expect(stderrSpy).toHaveBeenCalledWith(
+  expect.stringContaining("Expected message"),
+);
+
+// For multiple messages (concatenate all calls):
+const allCalls = stderrSpy.mock.calls.map((call) => call[0]).join("");
+expect(allCalls).toContain("Expected message");
+```
+
+## Helper Functions
+
+Place helper functions at the bottom of test files:
+
+```typescript
+// Test helpers
+
+type ConfigFileContents = {
+  token: string | null;
+  workerId: string | null;
+  environment: Environment;
+  baseUrl: string;
+};
+
+const tmpDirectories: string[] = [];
+
+const baseFlags: GlobalFlags = {
+  debug: false,
+};
+
+async function createConfigFile(contents: ConfigFileContents) {
+  const dir = await mkdtemp(path.join(tmpdir(), "test-prefix-"));
+  tmpDirectories.push(dir);
+  const configFilePath = path.join(dir, "config.json");
+  await writeFile(configFilePath, JSON.stringify(contents, null, 2), "utf-8");
+  return configFilePath;
+}
+
+async function createTestConfig(
+  configFileContents: ConfigFileContents,
+): Promise<Config> {
+  const configFilePath = await createConfigFile(configFileContents);
+  return Config.load({
+    configFilePath,
+    processEnv: {} as NodeJS.ProcessEnv,
+    flags: { debug: false },
+  });
+}
+
+function createBaseContext() {
+  return {
+    writer: new Writer({ debugEnabled: false }),
+    process,
+    fs,
+    os,
+    path,
+  };
+}
+```
+
+## Common Mistakes to Avoid
+
+1. **Don't call handlers directly without context**: Always use `.call(context, ...)`
+2. **Don't check config state directly**: Spy on the setter methods instead
+3. **Don't forget to mock Config.load**: The handler loads config internally
+4. **Don't forget to create unique temp directories**: Use `mkdtemp` with unique prefixes
+5. **Don't forget to clean up temp files**: Use `afterEach` to remove temp directories

package/src/cli/commands/auth.impl.test.ts

@@ -0,0 +1,206 @@
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	type Mock,
+	vi,
+} from "vitest";
+import { Config } from "../config.js";
+import {
+	baseFlags,
+	cleanupTmpDirectories,
+	createBaseContext,
+	createTestConfig,
+} from "./utils/testing.js";
+
+// Mock the openUrl module before importing the implementation
+vi.mock("../utils/openUrl.js", () => ({
+	openNotionUrl: vi.fn().mockResolvedValue(undefined),
+}));
+
+import { openNotionUrl } from "../utils/openUrl.js";
+import { login, logout, show } from "./auth.impl.js";
+
+afterEach(cleanupTmpDirectories);
+
+describe("login", () => {
+	let stderrSpy: Mock<typeof process.stderr.write>;
+
+	beforeEach(() => {
+		stderrSpy = vi
+			.spyOn(process.stderr, "write")
+			.mockImplementation(() => true);
+	});
+
+	it("opens browser and displays instructions when no token provided", async () => {
+		const mockConfig = await createTestConfig({
+			token: null,
+			workerId: null,
+			environment: "local",
+			baseUrl: "http://localhost:3000",
+		});
+
+		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+
+		const context = createBaseContext();
+
+		await login.call(context, baseFlags);
+
+		expect(openNotionUrl).toHaveBeenCalledWith(
+			"local",
+			"http://localhost:3000/__workers__?createToken=true",
+		);
+
+		const allCalls = stderrSpy.mock.calls.map((call) => call[0]).join("");
+		expect(allCalls).toContain("Opening browser to create a token...");
+		expect(allCalls).toContain(
+			"http://localhost:3000/__workers__?createToken=true",
+		);
+		expect(allCalls).toContain("After creating a token, run:");
+		expect(allCalls).toContain("npx workers auth login <token>");
+	});
+
+	it("shows error message when browser fails to open", async () => {
+		const mockConfig = await createTestConfig({
+			token: null,
+			workerId: null,
+			environment: "local",
+			baseUrl: "http://localhost:3000",
+		});
+
+		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+		vi.mocked(openNotionUrl).mockRejectedValueOnce(new Error("Failed to open"));
+
+		const context = createBaseContext();
+
+		await login.call(context, baseFlags);
+
+		const allCalls = stderrSpy.mock.calls.map((call) => call[0]).join("");
+		expect(allCalls).toContain("Failed to open browser automatically");
+		expect(allCalls).toContain(
+			"http://localhost:3000/__workers__?createToken=true",
+		);
+	});
+
+	it("saves token and clears workerId when token is provided", async () => {
+		const mockConfig = await createTestConfig({
+			token: null,
+			workerId: null,
+			environment: "local",
+			baseUrl: "http://localhost:3000",
+		});
+
+		// Spy on Config.load to return our mock config
+		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+
+		const testToken =
+			"1.2.eyJzcGFjZUlkIjoic3BhY2UxIiwidXNlcklkIjoidXNlcjEiLCJjZWxsSWQiOiJjZWxsMSJ9.sig";
+
+		const setEnvironmentSpy = vi.spyOn(mockConfig, "setEnvironment");
+		const setTokenSpy = vi.spyOn(mockConfig, "setToken");
+		const setWorkerIdSpy = vi.spyOn(mockConfig, "setWorkerId");
+
+		const context = createBaseContext();
+
+		await login.call(context, baseFlags, testToken);
+
+		expect(setEnvironmentSpy).toHaveBeenCalledWith("local");
+		expect(setTokenSpy).toHaveBeenCalledWith(testToken);
+		expect(setWorkerIdSpy).toHaveBeenCalledWith(null);
+		expect(stderrSpy).toHaveBeenCalledWith(
+			expect.stringContaining("Successfully logged in!"),
+		);
+	});
+
+	it("saves environment from config when logging in", async () => {
+		const mockConfig = await createTestConfig({
+			token: null,
+			workerId: null,
+			environment: "prod",
+			baseUrl: "https://www.notion.so",
+		});
+
+		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+
+		const testToken =
+			"1.2.eyJzcGFjZUlkIjoic3BhY2UxIiwidXNlcklkIjoidXNlcjEiLCJjZWxsSWQiOiJjZWxsMSJ9.sig";
+
+		const setEnvironmentSpy = vi.spyOn(mockConfig, "setEnvironment");
+
+		const context = createBaseContext();
+
+		await login.call(context, baseFlags, testToken);
+
+		expect(setEnvironmentSpy).toHaveBeenCalledWith("prod");
+	});
+});
+
+describe("show", () => {
+	let stdoutSpy: Mock<typeof process.stdout.write>;
+
+	beforeEach(() => {
+		stdoutSpy = vi
+			.spyOn(process.stdout, "write")
+			.mockImplementation(() => true);
+	});
+
+	it("writes token to stdout when token exists", async () => {
+		const testToken =
+			"1.2.eyJzcGFjZUlkIjoic3BhY2UxIiwidXNlcklkIjoidXNlcjEiLCJjZWxsSWQiOiJjZWxsMSJ9.sig";
+
+		const mockConfig = await createTestConfig({
+			token: testToken,
+			workerId: "worker-1",
+			environment: "local",
+			baseUrl: "http://localhost:3000",
+		});
+
+		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+
+		const context = createBaseContext();
+
+		await show.call(context, baseFlags);
+
+		expect(stdoutSpy).toHaveBeenCalledWith(`${testToken}\n`);
+	});
+
+	it("writes empty string to stdout when no token exists", async () => {
+		const mockConfig = await createTestConfig({
+			token: null,
+			workerId: null,
+			environment: "local",
+			baseUrl: "http://localhost:3000",
+		});
+
+		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+
+		const context = createBaseContext();
+
+		await show.call(context, baseFlags);
+
+		expect(stdoutSpy).toHaveBeenCalledWith("\n");
+	});
+});
+
+describe("logout", () => {
+	it("calls setToken with null", async () => {
+		const mockConfig = await createTestConfig({
+			token: "existing-token",
+			workerId: "worker-1",
+			environment: "local",
+			baseUrl: "http://localhost:3000",
+		});
+
+		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
+
+		const setTokenSpy = vi.spyOn(mockConfig, "setToken");
+
+		const context = createBaseContext();
+
+		await logout.call(context, baseFlags);
+
+		expect(setTokenSpy).toHaveBeenCalledWith(null);
+	});
+});

package/src/cli/commands/auth.impl.ts

@@ -1,30 +1,17 @@
-import { baseUrl } from "../api/client.js";
-import type { Environment } from "../config.js";
+import type { GlobalFlags } from "../flags.js";
 import { buildHandler, type HandlerContext } from "../handler.js";
 import { openNotionUrl } from "../utils/openUrl.js";
 
-interface LoginFlags {
-	env?: Environment;
-	"base-url"?: string;
-}
-
 export const login = buildHandler(async function (
 	this: HandlerContext,
-	flags: LoginFlags,
+	_: GlobalFlags,
 	token?: string,
 ) {
-	const environment = flags.env ?? "prod";
-
-	if (flags["base-url"]) {
-		await this.config.setBaseUrl(flags["base-url"]);
-	}
+	const environment = this.config.environment;
 
 	// If no token provided, open the browser to get one
 	if (!token) {
-		const url = `${baseUrl({
-			environment,
-			override: this.config.baseUrl,
-		})}/__workers__?createToken=true`;
+		const url = `${this.config.baseUrl}/__workers__?createToken=true`;
 
 		this.writer.writeErr(`Opening browser to create a token...\n${url}\n`);
 		this.writer.writeErr("After creating a token, run:");
@@ -43,6 +30,7 @@ export const login = buildHandler(async function (
 
 	await this.config.setEnvironment(environment);
 	await this.config.setToken(token);
+	await this.config.setWorkerId(null);
 
 	this.writer.writeErr("Successfully logged in!");
 });

package/src/cli/commands/auth.ts

@@ -1,5 +1,4 @@
 import { buildCommand, buildRouteMap } from "@stricli/core";
-import { Environments } from "../config.js";
 import { globalFlags } from "../flags.js";
 
 export const authCommands = buildRouteMap({
@@ -9,7 +8,8 @@ export const authCommands = buildRouteMap({
 	routes: {
 		login: buildCommand({
 			docs: {
-				brief: "Login to the Project Ajax platform using a Workers API token",
+				brief:
+					"Login to the Project Ajax platform using a Workers API token; will clear existing token, environment, and worker ID",
 			},
 
 			parameters: {
@@ -26,19 +26,6 @@ export const authCommands = buildRouteMap({
 				},
 
 				flags: {
-					env: {
-						kind: "enum",
-						values: Environments,
-						brief: "The environment to use for the command",
-						optional: true,
-					},
-					"base-url": {
-						kind: "parsed",
-						parse: String,
-						brief: "The base URL to use for all API requests",
-						optional: true,
-						hidden: true,
-					},
 					...globalFlags,
 				},
 			},