@project-ajax/sdk 0.0.59 → 0.0.61

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

@@ -1,212 +0,0 @@
----
-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

@@ -1,228 +0,0 @@
-import {
-	afterEach,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	type Mock,
-	vi,
-} from "vitest";
-import { Config } from "../config.js";
-import {
-	baseFlags,
-	cleanupTmpDirectories,
-	createAndLoadConfig,
-	createBaseContext,
-} 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 createAndLoadConfig({
-			configFile: {
-				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 createAndLoadConfig({
-			configFile: {
-				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 createAndLoadConfig({
-			configFile: {
-				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 updateSpy = vi.spyOn(mockConfig, "update");
-
-		const context = createBaseContext();
-
-		await login.call(context, baseFlags, testToken);
-
-		expect(updateSpy).toHaveBeenCalledWith({
-			environment: "local",
-			token: testToken,
-			workerId: null,
-		});
-		expect(stderrSpy).toHaveBeenCalledWith(
-			expect.stringContaining("Successfully logged in!"),
-		);
-	});
-
-	it("saves environment from config when logging in", async () => {
-		const [mockConfig] = await createAndLoadConfig({
-			configFile: {
-				token: null,
-				workerId: null,
-				baseUrl: "https://www.notion.so",
-			},
-			flags: {
-				env: "local",
-			},
-		});
-
-		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
-
-		const testToken =
-			"1.2.eyJzcGFjZUlkIjoic3BhY2UxIiwidXNlcklkIjoidXNlcjEiLCJjZWxsSWQiOiJjZWxsMSJ9.sig";
-
-		const updateSpy = vi.spyOn(mockConfig, "update");
-
-		const context = createBaseContext();
-
-		await login.call(context, baseFlags, testToken);
-
-		expect(updateSpy).toHaveBeenCalledWith({
-			token: testToken,
-			workerId: null,
-			environment: "local",
-		});
-	});
-});
-
-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 createAndLoadConfig({
-			configFile: {
-				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 createAndLoadConfig({
-			configFile: {
-				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 createAndLoadConfig({
-			configFile: {
-				token: "existing-token",
-				workerId: "worker-1",
-				environment: "local",
-				baseUrl: "http://localhost:3000",
-			},
-		});
-
-		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
-
-		const updateSpy = vi.spyOn(mockConfig, "update");
-
-		const context = createBaseContext();
-
-		await logout.call(context, baseFlags);
-
-		expect(updateSpy).toHaveBeenCalledWith({
-			token: null,
-		});
-	});
-});

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

@@ -1,56 +0,0 @@
-import type { ConfigMap } from "../config.js";
-import type { GlobalFlags } from "../flags.js";
-import { buildHandler, type HandlerContext } from "../handler.js";
-import { openNotionUrl } from "../utils/openUrl.js";
-
-export const login = buildHandler(async function (
-	this: HandlerContext,
-	_: GlobalFlags,
-	token?: string,
-) {
-	const environment = this.config.environment;
-
-	// If no token provided, open the browser to get one
-	if (!token) {
-		const url = `${this.config.baseUrl}/__workers__?createToken=true`;
-
-		this.io.writeErr(`Opening browser to create a token...\n${url}\n`);
-		this.io.writeErr("After creating a token, run:");
-		this.io.writeErr("\tnpx workers auth login <token>");
-
-		try {
-			await openNotionUrl(environment, url);
-		} catch (_error) {
-			this.io.writeErr(
-				`Failed to open browser automatically. Please visit:\n  ${url}`,
-			);
-		}
-
-		return;
-	}
-
-	const update: Partial<ConfigMap> = {
-		token,
-		workerId: null,
-	};
-
-	console.log("environment", environment);
-
-	if (environment !== "prod") {
-		update.environment = environment;
-	}
-
-	await this.config.update(update);
-
-	this.io.writeErr("Successfully logged in!");
-});
-
-export const show = buildHandler(function (this: HandlerContext) {
-	this.io.writeOut(`${this.config.token ?? ""}`);
-});
-
-export const logout = buildHandler(async function (this: HandlerContext) {
-	await this.config.update({
-		token: null,
-	});
-});

package/src/cli/commands/auth.ts

@@ -1,63 +0,0 @@
-import { buildCommand, buildRouteMap } from "@stricli/core";
-import { globalFlags } from "../flags.js";
-
-export const authCommands = buildRouteMap({
-	docs: {
-		brief: "Commands for managing the CLI context",
-	},
-	routes: {
-		login: buildCommand({
-			docs: {
-				brief:
-					"Login to the Project Ajax platform using a Workers API token; will clear existing token, environment, and worker ID",
-			},
-
-			parameters: {
-				positional: {
-					kind: "tuple",
-					parameters: [
-						{
-							brief: "A Workers API token",
-							parse: String,
-							placeholder: "api-token",
-							optional: true,
-						},
-					],
-				},
-
-				flags: {
-					...globalFlags,
-				},
-			},
-
-			loader: () => import("./auth.impl.js").then((m) => m.login),
-		}),
-
-		show: buildCommand({
-			docs: {
-				brief: "Get the token for the CLI",
-			},
-			parameters: {
-				flags: {
-					...globalFlags,
-				},
-			},
-
-			loader: () => import("./auth.impl.js").then((m) => m.show),
-		}),
-
-		logout: buildCommand({
-			docs: {
-				brief: "Unset the token for the CLI",
-			},
-
-			parameters: {
-				flags: {
-					...globalFlags,
-				},
-			},
-
-			loader: () => import("./auth.impl.js").then((m) => m.logout),
-		}),
-	},
-});

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

@@ -1,143 +0,0 @@
-import {
-	afterEach,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	type Mock,
-	vi,
-} from "vitest";
-import { ApiClient } from "../api/client.js";
-import { Result } from "../api/result.js";
-import { Config } from "../config.js";
-import { downloadBundle } from "./bundle.impl.js";
-import {
-	baseFlags,
-	cleanupTmpDirectories,
-	createAndLoadConfig,
-	createBaseContext,
-} from "./utils/testing.js";
-
-afterEach(cleanupTmpDirectories);
-
-describe("downloadBundle", () => {
-	let stderrSpy: Mock<typeof process.stderr.write>;
-	let stdoutSpy: Mock<typeof process.stdout.write>;
-
-	beforeEach(() => {
-		stderrSpy = vi
-			.spyOn(process.stderr, "write")
-			.mockImplementation(() => true);
-		stdoutSpy = vi
-			.spyOn(process.stdout, "write")
-			.mockImplementation(() => true);
-	});
-
-	it("downloads and pipes bundle to stdout when workerId is set", async () => {
-		const [mockConfig] = await createAndLoadConfig({
-			configFile: {
-				token:
-					"1.2.eyJzcGFjZUlkIjoic3BhY2UxIiwidXNlcklkIjoidXNlcjEiLCJjZWxsSWQiOiJjZWxsMSJ9.sig",
-				workerId: "worker-123",
-				environment: "local",
-				baseUrl: "http://localhost:3000",
-			},
-		});
-
-		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
-
-		// Create a mock web stream
-		const mockWebStream = new ReadableStream({
-			start(controller) {
-				controller.enqueue(new TextEncoder().encode("bundle content"));
-				controller.close();
-			},
-		});
-
-		// This allows us to wait for the pipe to happen.
-		let resolveWrite: () => void;
-		const writePromise = new Promise<void>((resolve) => {
-			resolveWrite = resolve;
-		});
-		stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => {
-			resolveWrite();
-			return true;
-		});
-
-		const mockDownloadWorkerBundle = vi
-			.spyOn(ApiClient.prototype, "downloadWorkerBundle")
-			.mockResolvedValue(Result.success(mockWebStream));
-
-		const context = createBaseContext();
-
-		await downloadBundle.call(context, baseFlags);
-
-		expect(mockDownloadWorkerBundle).toHaveBeenCalledWith("worker-123");
-		await writePromise;
-		expect(stdoutSpy).toHaveBeenCalledWith(Buffer.from("bundle content"));
-	});
-
-	it("throws error when workerId is not set", async () => {
-		const [mockConfig] = await createAndLoadConfig({
-			configFile: {
-				token:
-					"1.2.eyJzcGFjZUlkIjoic3BhY2UxIiwidXNlcklkIjoidXNlcjEiLCJjZWxsSWQiOiJjZWxsMSJ9.sig",
-				workerId: null,
-				environment: "local",
-				baseUrl: "http://localhost:3000",
-			},
-		});
-
-		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
-
-		const mockDownloadWorkerBundle = vi.spyOn(
-			ApiClient.prototype,
-			"downloadWorkerBundle",
-		);
-
-		const context = createBaseContext();
-
-		await expect(downloadBundle.call(context, baseFlags)).rejects.toThrow(
-			"No worker configured. Run 'workers deploy' first to create a worker.",
-		);
-
-		expect(mockDownloadWorkerBundle).not.toHaveBeenCalled();
-	});
-
-	it("handles download failure gracefully", async () => {
-		const [mockConfig] = await createAndLoadConfig({
-			configFile: {
-				token:
-					"1.2.eyJzcGFjZUlkIjoic3BhY2UxIiwidXNlcklkIjoidXNlcjEiLCJjZWxsSWQiOiJjZWxsMSJ9.sig",
-				workerId: "worker-123",
-				environment: "local",
-				baseUrl: "http://localhost:3000",
-			},
-		});
-
-		vi.spyOn(Config, "load").mockResolvedValue(mockConfig);
-
-		const mockDownloadWorkerBundle = vi
-			.spyOn(ApiClient.prototype, "downloadWorkerBundle")
-			.mockResolvedValue(
-				Result.fail({
-					status: 404,
-					statusText: "Not Found",
-					message: "Worker bundle not found",
-				}),
-			);
-
-		const context = createBaseContext();
-
-		await downloadBundle.call(context, baseFlags);
-
-		expect(mockDownloadWorkerBundle).toHaveBeenCalledWith("worker-123");
-
-		const allCalls = stderrSpy.mock.calls.map((call) => call[0]).join("");
-		expect(allCalls).toContain("✗ Failed to download bundle");
-		expect(allCalls).toContain("✗ Worker bundle not found");
-
-		// Should not write anything to stdout on error
-		expect(stdoutSpy).not.toHaveBeenCalled();
-	});
-});