Improve import status handling (#151)

Author: Che-Zhu

app/(dashboard)/projects/_components/import-github-dialog.tsx

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useState } from 'react'
 import { FaGithub } from 'react-icons/fa'
 import { MdRefresh } from 'react-icons/md'
-import type { ProjectTaskStatus, ProjectTaskType } from '@prisma/client'
+import type { ProjectStatus, ProjectTask, ResourceStatus } from '@prisma/client'
 import { useRouter } from 'next/navigation'
 import { toast } from 'sonner'
 
@@ -19,6 +19,7 @@ import {
 import { importProjectFromGitHub } from '@/lib/actions/project'
 import { env } from '@/lib/env'
 import { GET } from '@/lib/fetch-client'
+import { getProjectImportStatus } from '@/lib/util/project-import-status'
 
 type Step = 'loading' | 'check-github-app' | 'select-repo'
 
@@ -27,6 +28,12 @@ interface ImportGitHubDialogProps {
   onOpenChange: (open: boolean) => void
 }
 
+type ImportStatusPollResponse = {
+  status: ProjectStatus
+  sandboxes: Array<{ status: ResourceStatus }>
+  tasks: Array<Pick<ProjectTask, 'type' | 'status' | 'createdAt'>>
+}
+
 export function ImportGitHubDialog({ open, onOpenChange }: ImportGitHubDialogProps) {
   const router = useRouter()
   const [step, setStep] = useState<Step>('loading')
@@ -97,20 +104,29 @@ export function ImportGitHubDialog({ open, onOpenChange }: ImportGitHubDialogPro
 
     const pollImportStatus = async () => {
       try {
-        const project = await GET<{ tasks: Array<{ type: ProjectTaskType; status: ProjectTaskStatus }> }>(
+        const project = await GET<ImportStatusPollResponse>(
           `/api/projects/${importProjectId}`
         )
 
-        const cloneTask = project.tasks.find((task) => task.type === 'CLONE_REPOSITORY')
-        if (!cloneTask || cloneTask.status === 'SUCCEEDED') {
+        if (project.status === 'ERROR' || project.sandboxes.some((sandbox) => sandbox.status === 'ERROR')) {
+          toast.error('Project creation failed because the sandbox could not start.')
+          onOpenChange(false)
+          setImportProjectId(null)
+          router.refresh()
+          return
+        }
+
+        const importStatus = getProjectImportStatus({ tasks: project.tasks })
+
+        if (importStatus === 'IMPORTED') {
           toast.success('Repository imported successfully')
           onOpenChange(false)
           setImportProjectId(null)
           router.refresh()
           return
         }
 
-        if (cloneTask.status === 'FAILED' || cloneTask.status === 'CANCELLED') {
+        if (importStatus === 'IMPORT_FAILED') {
           toast.error('Repository import failed. An empty project was created instead.')
           onOpenChange(false)
           setImportProjectId(null)

docs/prds/import-project-control-flow.md

@@ -9,6 +9,7 @@ repository as a Fulling project.
 
 This PRD exists to clarify what "success" means for:
 
+- request acceptance
 - project creation
 - sandbox creation
 - repository cloning
@@ -22,6 +23,7 @@ This document covers the current import flow for:
 - creating the initial sandbox for that project
 - cloning the selected repository into the sandbox
 - representing clone failure without rolling back the project
+- deriving import status from the clone task lifecycle
 
 This document does not define future repository analysis, skill installation, or
 deploy automation after import.
@@ -38,6 +40,18 @@ product success condition.
 
 ## Success Semantics
 
+### Request acceptance success
+
+The import request is considered accepted when the control plane successfully:
+
+- verifies the selected GitHub installation and repository access
+- creates the project record
+- creates the initial sandbox record
+- creates the initial clone-repository task
+
+At this point, the API may return success immediately even though the sandbox is
+not yet runnable and the repository has not yet been cloned.
+
 ### Project creation success
 
 A project is considered successfully created when its sandbox is successfully created
@@ -53,11 +67,23 @@ This means:
 The import transaction is considered successful only when the repository is cloned
 successfully into the sandbox.
 
+This is independent from request acceptance and independent from project creation
+success once the sandbox is already runnable.
+
 ## Failure Semantics
 
 ### Sandbox creation failure
 
-If the sandbox fails to reach a runnable state, project creation is considered failed.
+If the sandbox enters `ERROR`, project creation is considered failed.
+
+Current implementation note:
+
+- explicit sandbox create/start failures transition the sandbox to `ERROR`
+- there is currently no startup timeout that converts a sandbox stuck in `STARTING`
+  into `ERROR`
+
+So today, "failed to reach runnable state" is fully represented only for explicit
+failures, not for indefinite startup stalls.
 
 ### Repository clone failure
 
@@ -84,6 +110,7 @@ For the current stage of the product:
 - the user should still land in a usable project with an empty sandbox
 - no dedicated import-failure modal is required yet
 - the system should preserve existing code paths as much as possible
+- the UI should not wait forever on clone task state if the sandbox has already failed
 
 ## Status Requirements
 
@@ -92,21 +119,49 @@ The system should represent two layers of status:
 1. Project resource status
 2. Import transaction status
 
-For the current product behavior:
+### Project resource status
+
+Project resource status is represented by `Project.status` and continues to mean
+resource lifecycle state only.
+
+Examples:
+
+- `CREATING`
+- `STARTING`
+- `RUNNING`
+- `ERROR`
+
+### Import transaction status
+
+Import transaction status is not a separate persisted `ProjectStatus` enum.
+It is derived from the latest `CLONE_REPOSITORY` task for the project.
+
+Derived meaning:
+
+- `WAITING_FOR_PREREQUISITES`, `PENDING`, or `RUNNING` => `IMPORTING`
+- `SUCCEEDED` => `IMPORTED`
+- `FAILED` or `CANCELLED` => `IMPORT_FAILED`
+
+For the current product contract:
 
 - project status may become `RUNNING`
-- import may independently become `IMPORT_FAILED`
+- import may independently derive to `IMPORT_FAILED`
 
 The intended current UI meaning is:
 
-- `RUNNING + IMPORT FAILED`
+- `RUNNING + IMPORT_FAILED`
 
 This combination means:
 
 - the sandbox is available
 - the project exists and is usable
 - the requested repository import did not complete successfully
 
+Current implementation note:
+
+- UI may choose to render this as `Needs Attention`
+- `Needs Attention` is a presentation label, not the underlying persisted import status
+
 ## Retry Behavior
 
 Repository clone should automatically retry up to 3 times, matching the current system behavior.
@@ -132,6 +187,12 @@ If clone fails, the database must still clearly reflect:
 - project creation succeeded
 - import did not succeed
 
+This currently means:
+
+- `Project` persists the imported GitHub metadata
+- `ProjectTask` persists clone attempts, final success or failure, and error text
+- import status is inferred from task state rather than stored as a dedicated project column
+
 ## GitHub Metadata Requirements
 
 If the repository later becomes unavailable or permissions change, the project should
@@ -150,15 +211,19 @@ This PRD does not define:
 
 - a new import intent model
 - a dedicated import failure modal
+- a new `ProjectStatus` enum value for import outcomes
 - post-import repository analysis
 - skill installation after import
 - deployment after import
 - new manual retry workflows
+- sandbox startup timeout policy
 
 ## Implementation Notes
 
 Current implementation should preserve this product contract:
 
-- project creation success is anchored to sandbox success
+- request acceptance is synchronous and returns after control-plane state is created
+- project creation success is asynchronous and is anchored to sandbox success
 - clone failure is visible as an import failure, not as project creation failure
 - import logic may fail independently after the project already exists
+- import status should be derived from clone task state, not folded into `Project.status`

lib/util/project-display-status.ts

@@ -1,4 +1,6 @@
-import type { ProjectStatus, ProjectTask, ProjectTaskStatus, ProjectTaskType } from '@prisma/client'
+import type { ProjectStatus, ProjectTask } from '@prisma/client'
+
+import { getProjectImportStatus } from '@/lib/util/project-import-status'
 
 export type ProjectDisplayStatus =
   | 'CREATING'
@@ -30,9 +32,9 @@ export function getProjectDisplayStatus(
   project: ProjectDisplayStatusInput
 ): ProjectDisplayStatus {
   const importProject = isImportProject(project)
-  const cloneTask = getLatestTask(project.tasks, 'CLONE_REPOSITORY')
+  const importStatus = getProjectImportStatus({ tasks: project.tasks })
 
-  if (cloneTask?.status === 'FAILED') {
+  if (importStatus === 'IMPORT_FAILED') {
     return 'NEEDS_ATTENTION'
   }
 
@@ -56,7 +58,7 @@ export function getProjectDisplayStatus(
     return 'UPDATING'
   }
 
-  if (importProject && cloneTask && isActiveTaskStatus(cloneTask.status)) {
+  if (importProject && importStatus === 'IMPORTING') {
     return 'IMPORTING'
   }
 
@@ -74,16 +76,3 @@ export function getProjectDisplayStatus(
 
   return 'NEEDS_ATTENTION'
 }
-
-function getLatestTask(
-  tasks: ProjectDisplayStatusInput['tasks'],
-  type: ProjectTaskType
-) {
-  return tasks
-    ?.filter((task) => task.type === type)
-    .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())[0]
-}
-
-function isActiveTaskStatus(status: ProjectTaskStatus): boolean {
-  return ['PENDING', 'WAITING_FOR_PREREQUISITES', 'RUNNING'].includes(status)
-}

lib/util/project-import-status.ts

@@ -0,0 +1,64 @@
+import type { ProjectTask, ProjectTaskStatus, ProjectTaskType } from '@prisma/client'
+
+export type ProjectImportStatus = 'IMPORTING' | 'IMPORTED' | 'IMPORT_FAILED' | 'NOT_STARTED'
+
+type ProjectImportStatusInput = {
+  tasks?: Pick<ProjectTask, 'type' | 'status' | 'createdAt'>[]
+}
+
+/**
+ * Derives the current import transaction state from the latest clone task.
+ *
+ * Expected inputs:
+ * - Project tasks that may include one or more CLONE_REPOSITORY records.
+ *
+ * Expected outputs:
+ * - Returns the current import state for the latest clone task.
+ *
+ * Out of scope:
+ * - Does not inspect sandbox or project resource status.
+ * - Does not infer whether a project originated from GitHub metadata.
+ */
+export function getProjectImportStatus(
+  input: ProjectImportStatusInput
+): ProjectImportStatus {
+  const cloneTask = getLatestTask(input.tasks, 'CLONE_REPOSITORY')
+
+  if (!cloneTask) {
+    return 'NOT_STARTED'
+  }
+
+  if (isActiveTaskStatus(cloneTask.status)) {
+    return 'IMPORTING'
+  }
+
+  if (cloneTask.status === 'SUCCEEDED') {
+    return 'IMPORTED'
+  }
+
+  if (cloneTask.status === 'FAILED' || cloneTask.status === 'CANCELLED') {
+    return 'IMPORT_FAILED'
+  }
+
+  return 'NOT_STARTED'
+}
+
+export function getLatestProjectTask(
+  tasks: ProjectImportStatusInput['tasks'],
+  type: ProjectTaskType
+) {
+  return getLatestTask(tasks, type)
+}
+
+function getLatestTask(
+  tasks: ProjectImportStatusInput['tasks'],
+  type: ProjectTaskType
+) {
+  return tasks
+    ?.filter((task) => task.type === type)
+    .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())[0]
+}
+
+function isActiveTaskStatus(status: ProjectTaskStatus): boolean {
+  return ['PENDING', 'WAITING_FOR_PREREQUISITES', 'RUNNING'].includes(status)
+}