cocalc-api/test: fix edge cases in api and improve testing

This commit updates the conftest.py test fixtures to properly support both
account-scoped and project-scoped API keys during testing.

The validate_api_key_config fixture now:
- First attempts to detect scope via hub.system.test() (account-scoped keys)
- Falls back to project.system.test() if hub fails (project-scoped keys)
- Reports both errors if both endpoints fail, for better debugging

Also clarifies that the hub endpoint's system.test() is for account-scoped
keys only, with clear comments directing project-scoped key users to the
project endpoint.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: haraldschilly

src/AGENTS.md

@@ -108,11 +108,13 @@ CoCalc is organized as a monorepo with key packages:
 #### CoCalc Conat Hub API Architecture
 
 **API Method Registration Pattern:**
+
 - **Registry**: `packages/conat/hub/api/projects.ts` contains `export const projects = { methodName: authFirstRequireAccount }`
 - **Implementation**: `packages/server/conat/api/projects.ts` contains `export async function methodName() { ... }`
 - **Flow**: Python client `@api_method("projects.methodName")` → POST `/api/conat/hub` → `hubBridge()` → conat subject `hub.account.{account_id}.api` → registry lookup → implementation
 
 **Example - projects.createProject:**
+
 1. **Python**: `@api_method("projects.createProject")` decorator
 2. **HTTP**: `POST /api/conat/hub {"name": "projects.createProject", "args": [...]}`
 3. **Bridge**: `hubBridge()` routes to conat subject
@@ -172,7 +174,6 @@ CoCalc is organized as a monorepo with key packages:
 - Prefix git commits with the package and general area. e.g. 'frontend/latex: ...' if it concerns latex editor changes in the packages/frontend/... code.
 - When pushing a new branch to Github, track it upstream. e.g. `git push --set-upstream origin feature-foo` for branch "feature-foo".
 
-
 ## React-intl / Internationalization (i18n)
 
 CoCalc uses react-intl for internationalization with SimpleLocalize as the translation platform.
@@ -234,7 +235,10 @@ Same flow as above, but **before 3. i18n:upload**, delete the key. Only new keys
 
 ## Overview
 
-The `python/cocalc-api/` directory contains a Python client library for the CoCalc API, published as the `cocalc-api` package on PyPI.
+The `python/cocalc-api/` directory contains a uv-based Python client library for the CoCalc API, published as the `cocalc-api` package on PyPI.
+
+It also contains a test framework (`python/cocalc-api/tests/README.md`) and an MCP client (`python/cocalc-api/src/cocalc_api/mcp/README.md`).
+For convenience, a `python/cocalc-api/Makefile` exists.
 
 ## Client-Server Architecture Investigation
 
@@ -248,54 +252,21 @@ The `python/cocalc-api/` directory contains a Python client library for the CoCa
 ### Endpoints Discovered
 
 #### Hub API: `POST /api/conat/hub`
+
 - **Bridge**: `packages/next/pages/api/conat/hub.ts` → `hubBridge()` → conat subject `hub.account.{account_id}.api`
 - **Implementation**: `packages/conat/hub/api/projects.ts`
 - **Available Methods**: `createProject`, `start`, `stop`, `setQuotas`, `addCollaborator`, `removeCollaborator`, etc.
-- **Missing**: ❌ **No `delete` method implemented in conat hub API**
 
 #### Project API: `POST /api/conat/project`
+
 - **Bridge**: `packages/next/pages/api/conat/project.ts` → `projectBridge()` → conat project subjects
 - **Implementation**: `packages/conat/project/api/` (system.ping, system.exec, system.jupyterExecute)
 
-### Project Deletion Investigation
-
-#### ✅ Next.js v2 API Route Available
-- **Endpoint**: `packages/next/pages/api/v2/projects/delete.ts`
-- **Functionality**: Sets deleted=true, removes licenses, stops project
-- **Authentication**: Requires collaborator access or admin
-
-#### ❌ Missing Conat Hub API Method
-- **Current Methods**: Only CRUD operations (create, start, stop, quotas, collaborators)
-- **Gap**: No `delete` method exposed through conat hub API used by cocalc-api
-
-#### Frontend Implementation
-- **Location**: `packages/frontend/projects/actions.ts:delete_project()`
-- **Method**: Direct database table update via `projects_table_set({deleted: true})`
-
-## Implementation
-
-### Solution Implemented: Direct v2 API Call
-- **Added**: `hub.projects.delete(project_id)` method to cocalc-api Python client
-- **Implementation**: Direct HTTP POST to `/api/v2/projects/delete` endpoint
-- **Reasoning**: Fastest path to complete project lifecycle without requiring conat hub API changes
-- **Consistency**: Uses same authentication and error handling patterns as other methods
-
-### Code Changes
-1. **`src/cocalc_api/hub.py`**: Added `delete()` method to Projects class
-2. **`tests/conftest.py`**: Updated cleanup to use new delete method
-3. **`tests/test_hub.py`**: Added test for delete method availability
-
-## Current Status
-- ✅ pytest test framework established with automatic project lifecycle
-- ✅ Project creation/start/stop working via conat hub API
-- ✅ Project deletion implemented by calling v2 API route directly
-- ✅ Complete project lifecycle management: create → start → test → stop → delete
-- ✅ All 14 tests passing with proper resource cleanup
-
 # important-instruction-reminders
+
 - Do what has been asked; nothing more, nothing less.
 - NEVER create files unless they're absolutely necessary for achieving your goal.
 - ALWAYS prefer editing an existing file to creating a new one.
-- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- NEVER proactively create documentation files (\*.md) or README files. Only create documentation files if explicitly requested by the User.
 - ALWAYS ask questions if something is unclear. Only proceed to the implementation step if you have no questions left.
 - When modifying a file with a copyright banner at the top, make sure to fix/add the current year to indicate the copyright year.

src/packages/server/conat/api/system.ts

@@ -18,11 +18,11 @@ export function ping() {
   return { now: Date.now() };
 }
 
-export async function test({
-  account_id,
-}: { account_id?: string } = {}) {
+export async function test({ account_id }: { account_id?: string } = {}) {
   // Return API key scope information and server time
   // The authFirst decorator determines the scope from the API key and injects account_id.
+  // Note: This endpoint only accepts account-scoped keys (see packages/next/pages/api/conat/hub.ts).
+  // For project-scoped keys, use the project endpoint (packages/next/pages/api/conat/project.ts).
   const response: { account_id: string; server_time: number } = {
     account_id: account_id ?? "",
     server_time: Date.now(),

src/python/cocalc-api/tests/conftest.py

@@ -126,10 +126,30 @@ def validate_api_key_config(hub):
     For account-scoped keys, requires COCALC_PROJECT_ID to be set.
     For project-scoped keys, no additional configuration needed.
     """
+    scope = None
+    hub_error = None
+
+    # First, try the hub endpoint (works only for account-scoped keys)
     try:
         scope = hub.system.test()
     except Exception as e:
-        pytest.fail(f"Failed to determine API key scope: {e}")
+        hub_error = e
+
+    # If hub check failed, fall back to the project endpoint so project-scoped keys work
+    if scope is None:
+        try:
+            project_client = Project(
+                api_key=hub.api_key,
+                host=hub.host,
+                project_id=os.environ.get("COCALC_PROJECT_ID"),
+            )
+            scope = project_client.system.test()
+        except Exception as project_error:
+            pytest.fail(
+                "Failed to determine API key scope using both hub and project endpoints:\n"
+                f"  hub error: {hub_error}\n"
+                f"  project error: {project_error}"
+            )
 
     is_account_scoped = "account_id" in scope
     is_project_scoped = "project_id" in scope