Confusing error messages when TypeScript project is not properly initialized

[iamdrewfortini]

Description

When running spacetime dev in a directory with spacetime.json but without a properly initialized TypeScript project, the error messages are confusing and don't guide users to the root cause.

Steps to Reproduce

1. Create a directory with spacetime.json and spacetime.local.json:

// spacetime.json
{
  "server": "maincloud"
}

// spacetime.local.json
{
  "database": "test-db"
}

2. Have a package.json present (either symlinked or for a different project) that doesn't include TypeScript as a dependency

3. Do NOT have a tsconfig.json file

4. Run spacetime dev <database-name>

Actual Behavior

The CLI outputs:

Found existing SpacetimeDB project.
...
Building...
tsc not found in node_modules. Make sure you have the `typescript` package as a dev-dependency and that your dependencies are installed.
Error: Failed to build project

Caused by:
    Something went wrong inside rolldown, please report this problem at https://github.com/rolldown/rolldown/issues.
    Tsconfig not found /home/user/tsconfig.json
    
    Caused by:
        Failed to resolve `tsconfig` option: /home/user/tsconfig.json

Expected Behavior

The CLI should:

1. Validate project structure - Don't just check for spacetime.json to determine if a project exists. Validate that the project is properly initialized with:

   • Correct package.json with required dependencies
   • tsconfig.json for TypeScript projects
   • The spacetimedb/ directory with module code

2. Provide actionable error messages - Instead of a cryptic rolldown error, show:

   Error: TypeScript project not properly initialized
   
   Missing or invalid files:
   - tsconfig.json not found
   - TypeScript dependency not installed
   - spacetimedb/ module directory not found
   
   To fix this, run:
   spacetime init --lang typescript <project-name>
   

3. Detect incomplete initialization - When spacetime.json exists but other required files don't, warn the user:

   Warning: Found spacetime.json but project appears incomplete.
   Did you mean to run 'spacetime init --lang typescript'?
   

Environment

• SpacetimeDB CLI version: 2.0.1
• OS: Linux
• Node.js version: v22.20.0

Additional Context

This issue affects developer experience, especially for new users trying to set up SpacetimeDB projects. The current error message:

1. Incorrectly states "Found existing SpacetimeDB project" when the project isn't properly set up
2. Points to a rolldown GitHub issues page instead of helping users fix their setup
3. Doesn't mention that spacetime init should be used to properly initialize a project

Suggested Fix

Add validation in the CLI before attempting to build:

// Pseudocode
fn validate_typescript_project(project_path: &Path) -> Result<(), Error> {
    if !project_path.join("tsconfig.json").exists() {
        return Err(Error::MissingTsConfig {
            suggestion: "Run 'spacetime init --lang typescript' to create a new project"
        });
    }
    
    if !typescript_installed(project_path) {
        return Err(Error::MissingTypeScript {
            suggestion: "Install TypeScript with: npm install --save-dev typescript"
        });
    }
    
    if !project_path.join("spacetimedb").exists() {
        return Err(Error::MissingModuleDirectory {
            suggestion: "Create a spacetimedb/ directory with your server module code"
        });
    }
    
    Ok(())
}

Labels

• bug
• developer-experience
• cli
• typescript