doctor

doctor diagnoses workspace consistency and the feature cache state. It runs a series of checks to detect common problems before they become runtime errors.

Typical use cases:

  • SPLENT fails to start after switching products
  • Features are declared but not found at runtime
  • Cache is corrupted or incomplete
  • Symlinks between the product and .splent_cache are broken
  • CLI and Framework versions are incompatible

Table of contents

  1. Usage
  2. Exit codes
  3. What it checks
    1. Phase 1: Environment
    2. Phase 2: pyproject.toml
    3. Phase 3: Dependencies
    4. Phase 4: Features & cache
    5. Phase 5: Symlink validation
  4. Feature naming rules (as interpreted by doctor)
  5. Output and summary
  6. Recommended workflow

Usage 

splent doctor

Exit codes

  • 0: all checks passed
  • 2: one or more checks failed (workspace should be fixed)

What it checks

The command runs five phases.

Phase 1: Environment

Validates the basic runtime and workspace context:

  • Python version
  • Installed versions of splent_cli and splent_framework and major-version compatibility
  • SPLENT_APP is set
  • Active product exists under the workspace ($WORKING_DIR or /workspace)
  • Detects whether the product uses src/ layout or flat layout

Common failures:

  • SPLENT_APP not set
  • App folder not found

Version mismatch: CLI=… / Framework=…

Phase 2: pyproject.toml

Validates that the active product has a valid pyproject.toml:

  • Ensures the file exists
  • Ensures it parses correctly

This phase is critical. If it fails, the command stops early.

If SPLENT_APP is not set or pyproject.toml is missing/invalid, doctor exits immediately with code 2.

Phase 3: Dependencies

Checks whether the dependencies declared in:

[project].dependencies

are installed in the current Python environment.

It reports missing packages (based on installed distribution metadata).

Common failure:

  • Missing: flask, redis, …

Phase 4: Features & cache

Reads the list of features declared by the product. SPLENT expects features to be declared under:

[project.optional-dependencies].features

doctor extracts them and then verifies the feature cache structure under:

<workspace>/.splent_cache/features/

For every declared external feature (a feature containing @version), it checks:

  • the cache folder exists: org/feature@version
  • the Python package structure exists: src/<org>/<feature>
  • pyproject.toml exists inside the cached feature (warn if missing)

Results:

  • OK: feature exists and looks well-formed in cache
  • WARN: cache exists but pyproject.toml is missing
  • FAIL: cache entry missing or malformed

Local features (without @version) are not validated against .splent_cache because they are not expected to be cached.

Validates that the product’s features/ directory contains correct symlinks pointing to the cache for versioned features.

Expected product layout:

<product>/features/<namespace>/<feature>@<version>  ->  <workspace>/.splent_cache/features/<namespace>/<feature>@<version>

Checks performed:

  • the symlink exists inside the product
  • the path is actually a symlink (not a folder/file)
  • the symlink target exists in .splent_cache
  • reports broken symlinks

Common failures:

  • Missing symlink: /features/...
  • Expected symlink but found directory/file
  • Broken symlink → target missing

Feature naming rules (as interpreted by doctor)

Declared feature strings can be expressed as:

  • feature_name@1.2.3 (defaults to org splent_io)
  • org/feature_name@1.2.3
  • feature_name (local feature; not checked against cache)
  • org/feature_name (local feature; not checked against cache)

For cache and symlink paths, the org/namespace is normalized:

  • and . are converted to _

Output and summary

At the end, doctor prints a summary:

  • number of OK checks
  • number of warnings
  • number of failures

If there is at least one failure, it exits with code 2.

Recommended workflow

When something feels “off” in your workspace (features not loading, import errors, broken cache), run:

splent doctor

Then fix issues in this order:

  1. Ensure SPLENT_APP points to a valid product
  2. Fix pyproject.toml parsing errors
  3. Install missing dependencies
  4. Rebuild or restore the feature cache
  5. Regenerate symlinks (if applicable in your workflow)