Working with features

In SPLENT, a feature is a self-contained, independently versioned Python package that adds functionality to a product. Features own their own routes, models, migrations, templates, assets, seeders, and tests. A product is a composition of features.

Feature types
Feature reference format
Lifecycle
Cache structure
Command sections

Feature types

Type	Description
Editable	Full git clone in `.splent_cache/features/<namespace>/<feature_name>/`. No version pin — changes take effect immediately. Used during development.
Versioned snapshot	Shallow clone at a specific tag in `.splent_cache/features/<namespace>/<feature_name>@<version>/`. Immutable. Used in stable and production products.

Feature reference format

Feature identifiers follow this format throughout the CLI:

[namespace/]feature_name[@version]

Example	Meaning
`splent_feature_auth`	Editable, default namespace (`splent_io`)
`splent-io/splent_feature_auth`	Editable, explicit namespace
`splent_feature_auth@v1.2.7`	Versioned, default namespace
`splent-io/splent_feature_auth v1.2.7`	Versioned, two-argument form (used by `feature:attach`)

Namespaces use _ on the filesystem and - on GitHub. The CLI normalises this automatically.

Lifecycle

feature:create / feature:clone / feature:fork
    ↓
  [cached]  — exists in .splent_cache, not linked to any product

feature:add / feature:attach
    ↓
  [declared]  — registered in pyproject.toml + symlinked + tracked in splent.manifest.json

product:resolve / 00_install_features.sh
    ↓
  [installed]  — pip-installed, importable

db:upgrade / 04_handle_migrations.sh
    ↓
  [migrated]  — database tables created

Flask startup (FeatureManager.register_features)
    ↓
  [active]  — blueprints registered, routes live

Use splent feature:status to see the current state of every feature at a glance. Use splent feature:order to verify the topological load order before syncing or seeding.

For the full state machine see Feature lifecycle.

Cache structure

.splent_cache/features/
└── splent_io/
    ├── splent_feature_auth/           ← editable clone
    ├── splent_feature_auth@v1.2.6/    ← versioned snapshot
    ├── splent_feature_auth@v1.2.7/    ← versioned snapshot
    └── splent_feature_redis@v1.2.7/   ← versioned snapshot

Products reference features via symlinks:

sample_splent_app/features/splent_io/splent_feature_auth@v1.2.7
  → .splent_cache/features/splent_io/splent_feature_auth@v1.2.7

Command sections

Section	Description
Feature Discovery	Browse, list, and understand features
Feature Lifecycle	Create, acquire, link, and remove features
Feature Development	Day-to-day development commands
Feature Contracts & Hooks	Extensibility contracts and template hooks
Feature Release	Release and upgrade features