feat: add "Create Project" dialog for initializing new project types

Backend: new GET /creatable-types (cached) and POST /create endpoints
that introspect the projspec registry and call Project.create().

Frontend: searchable type picker dialog launched via a "+" button in
the sidebar header, the command palette, or a directory context menu.
Already-detected types are filtered out. Success triggers a re-scan
and a toast notification.

Requires projspec >0.2.0 for the updated Project.create() API.
Bumps jupyter-projspec version to 0.3.0.

Made-with: Cursor

Author: Konstantin Taletskiy

jupyter_projspec/routes.py

@@ -88,6 +88,47 @@ class ArtifactLookupError(ValueError):
     """Raised when a spec type or artifact name cannot be found in projspec."""
 
 
+class TypeNotCreatableError(ValueError):
+    """Raised when a requested project type does not support creation."""
+
+
+# Cached list of project types that support creation.
+# Computed once on first access since the projspec registry is stable at runtime.
+_creatable_types_cache: list[dict] | None = None
+
+
+def _get_creatable_types() -> list[dict]:
+    """Return the list of project types that have implemented _create.
+
+    Results are cached at module level since the registry does not change
+    during the lifetime of the server process.
+    """
+    global _creatable_types_cache
+    if _creatable_types_cache is not None:
+        return _creatable_types_cache
+
+    from projspec.proj.base import ProjectSpec, registry
+
+    result = []
+    for name, cls in sorted(registry.items()):
+        if not issubclass(cls, ProjectSpec):
+            continue
+        if cls._create is ProjectSpec._create:
+            continue
+        result.append({
+            "name": name,
+            "doc": (cls.__doc__ or "").strip(),
+            "link": getattr(cls, "spec_doc", ""),
+        })
+    _creatable_types_cache = result
+    return _creatable_types_cache
+
+
+def _is_type_creatable(type_name: str) -> bool:
+    """Check whether a given type name is in the creatable types list."""
+    return any(t["name"] == type_name for t in _get_creatable_types())
+
+
 def resolve_path(contents_manager: ContentsManager, relative_path: str) -> str:
     """Validate and resolve a relative path to an absolute path within the server root.
 
@@ -508,16 +549,127 @@ def get(self):
             self.finish(json.dumps({"error": "Error scanning directory"}))
 
 
+class CreatableTypesRouteHandler(APIHandler):
+    """Handler that returns the list of project types supporting creation.
+
+    The result is computed once from projspec's registry and cached for the
+    lifetime of the server process.
+    """
+
+    @tornado.web.authenticated
+    def get(self):
+        """Return all creatable project types.
+
+        Returns:
+            JSON with "types" key containing a list of
+            {name, doc, link} objects.
+        """
+        try:
+            types = _get_creatable_types()
+            self.finish(json.dumps({"types": types}))
+        except Exception as e:
+            logger.error("Error fetching creatable types: %s", e, exc_info=True)
+            self.set_status(500)
+            self.finish(json.dumps({"error": "Failed to retrieve creatable types"}))
+
+
+class CreateRouteHandler(APIHandler):
+    """Handler for creating new project types in a directory via projspec."""
+
+    @tornado.web.authenticated
+    async def post(self):
+        """Create a new project type in the specified directory.
+
+        Request Body:
+            path: Relative path from server root (empty string for root)
+            type_name: The projspec type to create (e.g., "git_repo", "pixi")
+
+        Returns:
+            JSON with "created_files" listing the new files.
+        """
+        try:
+            data = self.get_json_body()
+        except (json.JSONDecodeError, ValueError):
+            self.set_status(400)
+            self.finish(json.dumps({"error": "Invalid or missing JSON body"}))
+            return
+
+        if not isinstance(data, dict):
+            self.set_status(400)
+            self.finish(json.dumps({"error": "Request body must be a JSON object"}))
+            return
+
+        type_name = data.get("type_name")
+        if not isinstance(type_name, str) or not type_name.strip():
+            self.set_status(400)
+            self.finish(json.dumps({"error": "Missing or invalid required field: type_name"}))
+            return
+
+        path = data.get("path", "")
+        if not isinstance(path, str):
+            self.set_status(400)
+            self.finish(json.dumps({"error": "Field 'path' must be a string"}))
+            return
+
+        try:
+            result = await tornado.ioloop.IOLoop.current().run_in_executor(
+                _executor, self._run_create, path, type_name.strip()
+            )
+            self.finish(json.dumps(result))
+        except PathSecurityError as e:
+            self.set_status(403)
+            self.finish(json.dumps({"error": str(e)}))
+        except PathNotFoundError as e:
+            self.set_status(404)
+            self.finish(json.dumps({"error": str(e)}))
+        except PathNotDirectoryError as e:
+            self.set_status(400)
+            self.finish(json.dumps({"error": str(e)}))
+        except TypeNotCreatableError as e:
+            self.set_status(400)
+            self.finish(json.dumps({"error": str(e)}))
+        except Exception as e:
+            logger.error("Create project error: %s", e, exc_info=True)
+            self.set_status(500)
+            self.finish(json.dumps({"error": f"Failed to create project type: {e}"}))
+
+    def _run_create(self, path: str, type_name: str) -> dict:
+        """Resolve path and run projspec create (called in thread pool)."""
+        absolute_path = resolve_path(self.contents_manager, path)
+
+        if not _is_type_creatable(type_name):
+            raise TypeNotCreatableError(
+                f"Project type '{type_name}' does not support creation"
+            )
+
+        project = projspec.Project(absolute_path)
+
+        if type_name in project.specs:
+            raise TypeNotCreatableError(
+                f"Project type '{type_name}' already exists in this directory"
+            )
+
+        # project.create() returns the list of newly created file paths
+        created_files = project.create(type_name)
+        return {"created_files": [str(f) for f in created_files]}
+
+
 def setup_route_handlers(web_app):
     host_pattern = ".*$"
     base_url = web_app.settings["base_url"]
 
     scan_route_pattern = url_path_join(base_url, "jupyter-projspec", "scan")
     make_route_pattern = url_path_join(base_url, "jupyter-projspec", "make")
+    creatable_types_pattern = url_path_join(
+        base_url, "jupyter-projspec", "creatable-types"
+    )
+    create_pattern = url_path_join(base_url, "jupyter-projspec", "create")
 
     handlers = [
         (scan_route_pattern, ScanRouteHandler),
         (make_route_pattern, MakeRouteHandler),
+        (creatable_types_pattern, CreatableTypesRouteHandler),
+        (create_pattern, CreateRouteHandler),
     ]
 
     web_app.add_handlers(host_pattern, handlers)

package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyter-projspec",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "A Jupyter interface for projspec",
     "keywords": [
         "jupyter",
@@ -58,6 +58,7 @@
     },
     "dependencies": {
         "@jupyterlab/application": "^4.0.0",
+        "@jupyterlab/apputils": "^4.0.0",
         "@jupyterlab/coreutils": "^6.0.0",
         "@jupyterlab/filebrowser": "^4.0.0",
         "@jupyterlab/services": "^7.0.0",

pyproject.toml

@@ -23,7 +23,7 @@ classifiers = [
 ]
 dependencies = [
     "jupyter_server>=2.4.0,<3",
-    "projspec>=0.2.0,<0.3"
+    "projspec>0.2.0,<0.3"
 ]
 dynamic = ["version", "description", "authors", "urls", "keywords"]
 

src/api.ts

@@ -1,4 +1,5 @@
 import { ServerConnection } from '@jupyterlab/services';
+import { ICreatableType, ICreateRequest, ICreateResponse } from './types';
 import { requestAPI } from './request';
 
 /**
@@ -25,6 +26,28 @@ interface IMakeResponse {
   truncated: boolean;
 }
 
+/**
+ * Extract a user-friendly error message from a caught error.
+ */
+function extractErrorMessage(err: unknown, context: string): string {
+  if (err instanceof ServerConnection.ResponseError) {
+    const status = err.response.status;
+    let detail = err.message;
+
+    if (
+      typeof detail === 'string' &&
+      (detail.includes('<!DOCTYPE') || detail.includes('<html'))
+    ) {
+      detail = `HTML error page (${detail.substring(0, 100)}...)`;
+    }
+
+    return `${context} (${status}): ${detail}`;
+  }
+
+  const msg = err instanceof Error ? err.message : 'Unknown error';
+  return `${context}: ${msg}`;
+}
+
 /**
  * Execute an artifact's build command via the backend.
  *
@@ -46,22 +69,64 @@ export async function make(request: IMakeRequest): Promise<IMakeResponse> {
     }
     return response;
   } catch (err) {
-    if (err instanceof ServerConnection.ResponseError) {
-      const status = err.response.status;
-      let detail = err.message;
+    throw new Error(extractErrorMessage(err, 'Make request failed'));
+  }
+}
+
+/**
+ * Module-level cache for creatable types.
+ * The list is static for the lifetime of the server, so we fetch once.
+ */
+let creatableTypesCache: ICreatableType[] | null = null;
 
-      // Truncate HTML responses for cleaner error messages
-      if (
-        typeof detail === 'string' &&
-        (detail.includes('<!DOCTYPE') || detail.includes('<html'))
-      ) {
-        detail = `HTML error page (${detail.substring(0, 100)}...)`;
-      }
+/**
+ * Fetch the list of project types that support creation.
+ *
+ * Results are cached after the first successful call since the
+ * projspec registry does not change at runtime.
+ */
+export async function fetchCreatableTypes(): Promise<ICreatableType[]> {
+  if (creatableTypesCache !== null) {
+    return creatableTypesCache;
+  }
 
-      throw new Error(`Make request failed (${status}): ${detail}`);
+  try {
+    const response = await requestAPI<{ types: ICreatableType[] }>(
+      'creatable-types',
+      { method: 'GET' }
+    );
+    if (!response?.types) {
+      throw new Error('Empty response from server');
     }
+    creatableTypesCache = response.types;
+    return creatableTypesCache;
+  } catch (err) {
+    throw new Error(
+      extractErrorMessage(err, 'Failed to fetch creatable types')
+    );
+  }
+}
 
-    const msg = err instanceof Error ? err.message : 'Unknown error';
-    throw new Error(`Make request failed: ${msg}`);
+/**
+ * Create a new project type in the specified directory.
+ *
+ * @param request - The path and type_name for creation
+ * @returns The list of files created by projspec
+ */
+export async function createProject(
+  request: ICreateRequest
+): Promise<ICreateResponse> {
+  try {
+    const response = await requestAPI<ICreateResponse>('create', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request)
+    });
+    if (response === undefined) {
+      throw new Error('Create request returned an empty response');
+    }
+    return response;
+  } catch (err) {
+    throw new Error(extractErrorMessage(err, 'Create project failed'));
   }
 }