product:derive

Full SPL product derivation pipeline — validates the product configuration, then syncs, configures, builds and launches it in one command.

Usage

splent product:derive --dev

Options

Option	Description
`--dev`	Derive in development mode.
`--prod`	Derive in production mode. Runs `product:build` + `product:deploy`.

Description

product:derive is the super-command for product derivation in the SPLENT Software Product Line methodology.

Before running the derivation pipeline, the command executes pre-flight checks. If any check fails, the pipeline is aborted — a product that is not configuration-valid is never derived.

For both --dev and --prod, the pre-flight phase includes a port conflict check. If a port is already in use by another product (dev or prod), the command reports which environment is blocking and suggests a fix (e.g., Run 'splent product:down --prod' to stop...).

Pre-flight checks

product:derive runs a 4-phase pre-flight sequence. Phase 0 aborts early if it fails – later phases are skipped.

Phase	Name	What it validates	Runs when
0	pyproject sanity	Duplicate features across `features`/`features_dev`/`features_prod`, inconsistent namespaces (`splent_io` vs `splent-io`), and SPL existence (`[tool.splent].spl` or legacy `[tool.splent.uvl]`).	Always
1	SAT	The product’s feature selection is satisfiable under the UVL variability model (resolved from `splent_catalog/` via the product’s `spl` setting, with legacy fallback).	Always
2	Contracts	No ERROR-level conflicts exist between the contracts of the declared features (route or blueprint name collisions).	Always
3	PyPI	All prod features are versioned and published on PyPI.	Build mode only

product:derive does not run Phase 3 (PyPI availability) during its own pre-flight. That phase is only performed by product:build (which runs its own pre-flight with build_mode=True).

product:derive will not proceed if any pre-flight phase fails. Warnings and info findings do not block derivation.

Derivation pipeline

Step	Command	Description
1	`product:resolve`	Download and cache all versioned features declared in `pyproject.toml`.
2	`product:env --generate --all --dev`	Generate `.env` files for the product and all its features.
3	`product:env --merge --dev`	Merge feature environment variables into the product `.env`.
4	`product:up --dev`	Start all Docker Compose stacks (features + product).
5	`product:run --dev`	Run the product entrypoint inside its main container.
6	`product:port`	Display the running service ports and URLs.

If any pipeline step fails, the pipeline stops at that point.

Example output

  Deriving my_first_app (dev)

  pyproject sanity checks passed
  validate  UVL configuration is satisfiable
  contract  no conflicts detected
  ports     no conflicts detected

  sync     resolving feature symlinks...
  ...
  env      generating .env files
  env      merging .env files
  up       starting containers
  run      launching application
  ...

  Product:  my_first_app
  Env:      dev
  Port:     5591 -> 5000

  URL: http://localhost:5591

  my_first_app (dev) derived successfully.

If a pre-flight check fails:

  validate Configuration is NOT satisfiable under the UVL constraints.
           run 'splent product:validate' to inspect

  Pre-flight checks failed. Fix the issues above before deriving.

Requirements

SPLENT_APP must be set.
Docker must be available.
The product must contain pyproject.toml and a docker/ directory.
The UVL model file must be present in the SPL catalog (splent spl:fetch) or at the legacy per-product location.

Notes

In --prod mode, the pipeline runs product:build (merge env + compose + build Docker image) followed by product:deploy (start production containers) instead of the dev-oriented steps. Pre-flight validation still runs, but the PyPI check is delegated to product:build’s own pre-flight.
Individual steps can always be run separately if you need finer control.
To inspect pre-flight results without running the pipeline use splent product:validate directly.