SPLENT Cache

The local feature cache stores pinned (versioned) features as read-only snapshots. Editable features live at the workspace root, not in the cache.

What is the cache

The cache is a directory at .splent_cache/features/ inside the workspace. It holds only versioned snapshots — shallow clones of specific git tags. The cache is read-only (filesystem-enforced) and developers should never edit files there directly.

.splent_cache/features/
└── splent_io/
    ├── splent_feature_auth@v1.0.0/    ← versioned snapshot (read-only)
    ├── splent_feature_auth@v1.2.7/    ← versioned snapshot (read-only)
    └── splent_feature_redis@v1.2.7/   ← versioned snapshot (read-only)

Editable features live at the workspace root, alongside splent_framework/ and splent_cli/:

splent_workspace/
├── splent_feature_auth/               ← editable (read-write, workspace root)
├── splent_feature_profile/            ← editable (read-write, workspace root)
├── splent_framework/
├── splent_cli/
├── sample_splent_app/
└── .splent_cache/                     ← pinned only, read-only

Namespaces map to GitHub organisations, with - replaced by _ on the filesystem.

Two kinds of features

Editable features have no version suffix in pyproject.toml (e.g. splent-io/splent_feature_auth). They live at the workspace root as full git clones on the main branch — you edit code, commit, and push directly. Changes are reflected immediately without re-installing.

Pinned features have a version (e.g. splent-io/splent_feature_auth@v1.2.7). They are read-only shallow clones (--depth 1) of a specific git tag, stored in .splent_cache/. All files are chmod read-only after clone. The CLI blocks operations that would modify them (e.g., db:migrate refuses to generate migrations for pinned features).

To transition between modes:

Pinned → editable: splent feature:unlock <name> (copies to workspace root, unlocks, updates symlink, triggers Flask reload)
Editable → pinned: splent feature:release + splent feature:attach (publishes, clones snapshot, locks)

Symlinks

Products reference features through relative symlinks in {product}/features/{org}/:

# Pinned → cache
features/splent_io/splent_feature_auth@v1.2.7 → ../../../.splent_cache/features/splent_io/splent_feature_auth@v1.2.7

# Editable → workspace root
features/splent_io/splent_feature_auth → ../../../splent_feature_auth

product:resolve creates and updates these symlinks automatically. If a cache entry or workspace root directory is deleted without going through the CLI, the symlink becomes broken. Cache cleanup commands handle this automatically.

What problems it solves

Reproducibility. A product that declares splent_feature_auth@v1.2.7 will behave identically on every machine that has that snapshot, with no dependency on network availability or upstream changes.

Speed. Features are cloned once and reused. Running product:resolve on a machine that already has the cache is near-instant.

Multiple versions coexisting. You can have @v1.0.0 and @v1.2.7 of the same feature cached at the same time. Different products can reference different versions without conflict.

Decoupled development. You can develop a feature in editable mode (workspace root) while another product in the same workspace uses a pinned release (cache) of the same feature.

Safety. Developers cannot accidentally modify pinned features. The filesystem permissions (r--r--r--) prevent writes, and the CLI guards block mutation commands.

Managing the cache

The CLI provides a dedicated set of commands for inspecting and maintaining the cache. See the Cache CLI reference for the full list.

Command	Description
`cache:status`	Overview of all entries (pinned in cache + editable at workspace root)
`cache:size`	Disk usage per namespace and entry
`cache:versions`	All cached versions of a specific feature
`cache:usage`	Which products reference each feature
`cache:orphans`	Cache entries not referenced by any product
`cache:outdated`	Products using an older version than what is cached
`cache:prune`	Delete orphaned entries and clean broken symlinks
`cache:clear`	Full or partial cache wipe (by namespace, by feature)

cache:prune is the safe option — it removes only what no product uses. cache:clear is the nuclear option.