Vix.cpp v2.7.3

Vix.cpp v2.7.3 expands the CLI workflow around application modules, backend projects, package management, and Softadastra Cloud.

The release adds generated WebSocket modules that integrate with vix.app, introduces an API-only backend template for projects with separately hosted frontends, and provides the first complete CLI path for connecting a local Vix project to Softadastra Cloud.

It also improves the package workflow beyond the registry. Git repositories can now be installed directly as project dependencies, command-line packages can be installed globally into a user-managed Vix prefix, and single C++ files can use temporary dependencies without turning the current directory into a permanent project.

Public registry publishing receives stricter source and identity validation so published metadata is derived from the exact tagged revision rather than the developer’s current working tree.

Release focus

The main direction of v2.7.3 is to make Vix workflows connect more naturally.

Application modules should not only generate files; they should participate correctly in project startup and builds. Packages should not only resolve from the public registry; developers should also be able to experiment with Git repositories and install useful command-line tools globally. Cloud integration should provide shared project state without moving compilation away from the developer’s machine.

These areas meet in the CLI.

Vix already knew how to create projects, resolve packages, build applications, run tests, and generate application modules. This release extends that model so the same commands can also prepare WebSocket runtimes, initialize existing directories, publish private packages, upload lockfiles, report local builds, and inspect tagged source before a public release.

The result is not one isolated feature. It is a broader project workflow in which local development, reusable packages, generated modules, and optional cloud coordination follow the same project metadata.

Softadastra Cloud CLI integration

Vix.cpp v2.7.3 introduces the first Softadastra Cloud commands in the Vix CLI.

The initial command set is:

vix login
vix cloud status
vix cloud init
vix cloud sync
vix logout

vix login authenticates the developer with Softadastra Cloud and stores the resulting session in the global Vix configuration.

vix cloud init links the current local project to a Cloud workspace and project record. The link is stored under:

.vix/cloud.json

This project-local file identifies the Cloud workspace and project associated with the current source tree.

Authentication and project identity are intentionally stored in different places. The user session belongs to the developer’s Vix environment and can be reused across projects, while the Cloud link belongs to one repository.

This allows a developer to work with several Cloud-linked projects without repeating login for each one and without embedding account credentials in project files.

Local-first Cloud workflow

Softadastra Cloud does not replace the local Vix build system.

Source files, compiler execution, generated objects, build directories, package checkouts, and native binaries remain on the developer’s machine or in the project’s own CI environment.

The Cloud integration records the parts of project state that are useful to share:

  • workspace and project identity;
  • private package versions;
  • dependency lockfiles;
  • build reports;
  • project permissions;
  • team activity.

This distinction is visible in the CLI. vix build still performs a normal local build. Adding --report submits information after that build; it does not upload the source code for remote compilation.

Similarly, vix cloud lockfile upload records the dependency state selected by the local project without changing how those dependencies are resolved or installed.

Cloud status and project linking

After authentication, the current environment can be inspected with:

vix cloud status

The command reports whether the user is authenticated, whether the current directory is linked to a Cloud project, and which workspace and project are active.

A local project can be connected with:

vix cloud init

The CLI uses the authenticated account to retrieve available workspaces and creates or selects the Cloud project associated with the current source tree.

Project metadata remains explicit. Vix does not assume that every local directory should be uploaded or linked merely because the user is authenticated.

vix cloud sync refreshes the Cloud-side project metadata associated with the local link while preserving the local project as the source of the build workflow.

Lockfile upload

Cloud-linked projects can upload their dependency lockfile with:

vix cloud lockfile upload

The shorter alias is also available:

vix cloud lock upload

By default, the command uses the project’s normal lockfile. A different file can be selected explicitly:

vix cloud lockfile upload --file vix.lock

Machine-readable output is available with:

vix cloud lockfile upload --json

The uploaded record includes checksum information, allowing the Cloud project to distinguish lockfile revisions and keep a history of dependency states.

This is useful when several developers or environments build the same project. The lockfile remains in source control as before, while the Cloud record provides another view of which dependency state was associated with project activity.

The command reports direct errors when the project has not been linked or when the requested lockfile does not exist.

Build reports

A local build can submit a report to Softadastra Cloud with:

vix build --report

The build itself follows the normal Vix process. The CLI configures the project, invokes the selected build backend, and determines whether the requested targets succeeded.

When the project is linked to Softadastra Cloud, Vix can then submit information such as:

  • build status;
  • elapsed time;
  • project identity;
  • build configuration;
  • relevant local project context.

The report is intended to describe the local build, not replace it.

A report submission failure does not turn a successful native build into a failed build command. The CLI reports the Cloud error separately while preserving the successful build exit status.

This is important for local work and CI. Cloud reporting is useful project metadata, but a temporary network or API failure should not make a valid compiled binary appear broken.

Cloud package publishing

Private package versions can be published to Softadastra Cloud through the existing publish command:

vix publish --cloud

The equivalent Cloud command is:

vix cloud publish

Cloud publication is explicit. Running vix publish without --cloud continues to use the public Vix Registry workflow.

A private package publication can specify its identity and visibility:

vix publish --cloud \
  --package softadastra/example \
  --version 0.1.0 \
  --visibility private

Additional options include:

--description
--repository-url
--archive
--manifest
--dry-run
--json

The command can prepare the package archive, calculate its checksum, read metadata from vix.json or vix.app, create the Cloud package record, and upload the version archive.

Duplicate package versions produce a clear conflict message instead of a generic API failure.

The public and private package workflows therefore share the same high-level command while remaining separate destinations with different access models.

Cloud diagnostics

vix doctor --cloud now inspects the Cloud side of the development environment.

The diagnostic includes:

  • API connectivity;
  • authentication state;
  • current project linkage;
  • lockfile upload availability;
  • build report support.

Cloud command failures also use more specific API errors for common cases such as missing authentication, missing project links, permission failures, missing files, and duplicate package versions.

The Cloud HTTP client uses the existing vix::requests module instead of introducing a separate networking implementation inside the CLI.

This keeps TLS, request handling, error conversion, and response parsing aligned with the networking code already maintained by Vix.

Generated WebSocket modules

The application module generator now supports WebSocket workflows.

A named module can be created with:

vix modules add live_chat --websocket --workflow attached

Option-based generation is also supported:

vix modules add \
  --websocket \
  --name live_chat \
  --workflow attached

The explicit --name option is useful in scripts and project generators where the module name is passed as a command option rather than a positional argument.

Generated metadata records the selected workflow in the module’s vix.module file.

WebSocket workflows

The initial WebSocket generator provides four workflows:

attached
standalone
bridge
client

Each workflow represents a different relationship between the generated module and the application runtime.

Attached

An attached module participates in the application’s existing runtime.

It is appropriate when the project already has a primary HTTP or backend application and the WebSocket feature should run as part of that process.

The generated module contributes its WebSocket behavior without defining an unrelated second application entry point.

Standalone

A standalone module provides its own runtime-capable WebSocket application.

This is useful for a service whose primary responsibility is WebSocket communication and which does not need to attach to another generated backend runtime.

Bridge

A bridge module is runtime-capable and is intended for workflows where WebSocket communication connects two parts of an application or forwards events between boundaries.

The generated structure provides a dedicated place for that bridge logic while still participating in the Vix module and runtime system.

Client

A client module generates WebSocket client support code.

Unlike the other workflows, it does not take ownership of application startup and must not be selected as the project runtime module.

Vix now excludes these non-runtime client modules when deciding which generated module should participate in runtime generation.

WebSocket runtime compatibility

Earlier generated modules still referenced runtime symbols that no longer matched the current WebSocket API, including older forms such as:

vix::websocket::Server
vix::run_http_and_ws

This could produce a module that looked structurally correct but failed during the normal application build.

The generator now uses the current WebSocket headers, runtime types, and startup model. Attached, standalone, and bridge modules can compile through the standard:

vix build

workflow.

Module registration and generated vix.app metadata were also updated so WebSocket contributions work in both application and backend projects.

Backend WebSocket status panel

Generated backend assets now include a small WebSocket connection status panel.

After starting a generated backend:

vix build
vix run

the browser page attempts to connect to the configured local WebSocket endpoint and reports whether the connection is open, closed, or unavailable.

The panel is not intended to replace application-specific WebSocket tooling. It provides immediate confirmation that the generated server, route, frontend asset, and browser connection agree on the basic runtime configuration.

This is particularly useful after creating a backend project and adding an attached WebSocket module because the developer can verify the generated integration before writing application-specific events.

API-only backend projects

Backend project generation now supports an API-only mode:

vix new api --template backend --api-only

The generated project keeps the production-oriented backend structure, including:

src/main.cpp
AppBootstrap
middleware registry
route registry
controllers
support helpers
storage
migrations
tests
.env
.env.example
vix.app
vix.json
README

It omits the parts intended for a backend that also serves its own browser frontend:

public/
views/
generated static frontend assets
template setup
static directory setup
static compression middleware
public and views resource entries

This mode is intended for applications where the C++ backend and frontend are deployed separately.

The frontend may be built with Vue, React, Next.js, SvelteKit, another web framework, or a static hosting system. The Vix project remains responsible for API routes, application services, middleware, storage, and native runtime behavior.

Static files, views, and related bootstrap code are now conditional parts of the standard backend template rather than assumptions shared by every backend project.

Global package installation

Vix now provides a user-space global installation workflow for C++ packages that expose libraries or command-line executables.

For example:

vix install -g vixcpp/ovi
ovi --version
vix uninstall -g vixcpp/ovi

Global packages are installed into a Vix-managed prefix rather than /usr/local by default.

This avoids requiring root access and gives Vix enough ownership information to update and remove package files safely.

When the package provides standard CMake installation rules, Vix builds the package and uses those rules. Installed files are recorded in the package’s global installation metadata.

Executables are exposed through the Vix global bin directory, making commands such as ovi available when that directory is present on PATH.

Global installation ownership

Global installation is more than copying a compiled binary.

Vix records which package owns each installed file and checks for executable name conflicts before replacing an existing command.

Uninstallation removes only files registered to the selected package.

This prevents a package uninstall from deleting unrelated headers, libraries, or commands that happen to share the same installation prefix.

Scoped forms are accepted consistently by install and uninstall commands, including package names such as:

@rix/rix

Normal uninstall output is kept short and reports the result with elapsed time rather than printing every removed path. More detailed output can still be requested when needed.

Packages with internal Vix targets

Some packages are designed to build inside the Vix package environment and reference internal targets prepared by the normal Vix dependency pipeline.

Treating those packages as unrelated standalone CMake projects can fail because their expected targets have not been created.

Global installation now passes packages such as rix/rix through the Vix build and installation workflow instead of configuring their source directories in isolation.

This preserves the same dependency preparation and target environment used when the package is consumed by a regular project.

Git dependencies

Vix projects can now install dependencies directly from Git repositories:

vix install https://github.com/fmtlib/fmt
vix install https://github.com/nlohmann/json.git

The CLI normalizes common Git URL forms and inspects the repository to determine how it can be consumed.

When no revision is specified, Vix selects the latest stable Semantic Versioning tag when one can be determined. It then resolves the selected revision to an exact commit and records that commit in vix.lock.

The source is materialized under:

.vix/deps

and Vix generates:

.vix/vix_deps.cmake

for normal build and run workflows.

The first implementation supports CMake repositories and header-only repositories.

Git dependency declarations

A Git dependency recorded in vix.app can describe:

  • repository URL;
  • tag;
  • branch;
  • commit;
  • expected CMake target;
  • CMake options;
  • public include roots;
  • source subdirectory;
  • header-only behavior.

This allows the lockfile to preserve the exact resolved source while the application manifest describes how the project consumes it.

The repository URL alone is often sufficient for common packages. Vix inspects the CMake project, searches for likely public targets, and prefers stable namespaced targets when the choice is unambiguous.

For example, a repository may expose several internal targets but have one clear consumer target such as:

fmt::fmt

When several plausible public targets remain and Vix cannot choose safely, installation stops with a direct ambiguity error instead of linking an arbitrary target.

Automatic dependency preparation

Dependencies declared in vix.app are prepared automatically by normal project commands.

A single-file execution inside a project no longer requires a separate deprecated dependency preparation step before running:

vix run main.cpp

When the file includes a project dependency, Vix resolves the dependency state, prepares the checkout, and selects the required compile path.

The same generated dependency information is available to regular project builds.

This brings dependency preparation into the commands that actually need the dependencies instead of requiring the developer to remember an independent synchronization command.

Initializing an existing directory

Vix.cpp v2.7.3 adds:

vix init

The command turns the current directory into a minimal Vix project without generating a complete application template.

A basic workflow is:

mkdir fmt-test
cd fmt-test
touch main.cpp
vix init

Vix derives a safe project name from the directory, detects existing C++ source files, and creates a minimal vix.app.

Supported options include:

--name
--lib
--standard
--force

vix init is intended for existing source trees or small folders that already contain code.

vix new remains the appropriate command when the developer wants a complete scaffold with a selected template, directory structure, examples, tests, and project documentation.

Temporary dependencies for single-file runs

A single C++ file can now use a Git dependency without permanently modifying the current directory:

vix run main.cpp \
  --dep https://github.com/fmtlib/fmt

Vix creates a temporary dependency environment, resolves the repository, prepares the required include or link information, compiles the file, and reuses the dependency cache where possible.

This mode does not create:

vix.app
vix.lock
.vix/

in the current directory unless the developer explicitly saves the dependency into a project.

It is useful for evaluating a library, reproducing a small example, or testing an API before deciding whether the code belongs in a permanent Vix project.

Faster single-file execution

vix run <file.cpp> now selects its execution path from the file’s actual dependency requirements.

A source file that uses only the C++ standard library can use the direct compiler path even when its parent project contains Git dependencies.

Previously, the presence of:

.vix/vix_deps.cmake

could force every single-file run through CMake, including files that did not use any dependency from that file.

Vix now examines the source includes and the dependency metadata before deciding whether CMake is necessary.

The general behavior is:

standard library only       direct compiler
header-only dependency      direct compiler with include paths
compiled dependency         CMake with vix::deps

This preserves the fast script-like workflow for simple programs while still supporting correct linking when a compiled package is required.

Direct-run caching

Repeated direct runs can reuse the compiled binary when the relevant inputs have not changed.

The cache key considers:

  • source content;
  • compiler;
  • C++ standard;
  • compiler flags;
  • include directories;
  • linked dependencies;
  • resolved dependency commits.

A change to any of these inputs invalidates the cached executable.

This is especially useful for small examples and temporary dependency experiments, where repeatedly invoking a full project configuration would add unnecessary delay.

Public registry publishing

The public vix publish workflow now validates the exact tagged source.

Publishing a version should describe the immutable revision associated with that version, not whichever files happen to exist in the current working directory.

Vix now creates a detached temporary checkout at the selected tag commit. It reads vix.json, scans public headers, and prepares registry metadata from that checkout.

Local uncommitted changes, files added after the tag, or a branch that has moved beyond the release therefore cannot silently influence the published package description.

The working tree remains untouched because inspection happens in the temporary checkout.

Durable package identity

A package’s registry identity is now tied to its normalized repository URL.

When a repository already exists in the registry under a particular:

namespace/name

future publications from the same repository must preserve that identity.

Changing the package name in vix.json does not silently create a second registry package for the same repository.

This prevents accidental renames from splitting versions, download history, search results, and ownership information across duplicate package entries.

Repository identity mismatches are checked before remote tag validation so the developer receives the most relevant error first.

Tag and remote validation

Public publishing verifies that the requested version tag exists at the expected repository revision.

Git network, authentication, and repository errors are now distinguished from a genuinely missing remote tag.

Earlier behavior could report some remote access failures as though the tag had simply not been pushed. The updated validation preserves the underlying reason when the repository cannot be reached or accessed.

This makes publication failures easier to diagnose, particularly for private remotes, incorrect repository URLs, or temporary network problems.

Public header scanning

The detached tagged checkout is also used to scan the package’s declared public include roots.

Vix derives API metadata from the source that users will actually receive for that version.

The generated metadata is deterministic: publishing the same immutable tag with the same manifest produces the same package API description.

This creates a stable basis for registry browsing, documentation links, package analysis, and future compatibility tooling.

Manifest metadata preservation

The registry package type now comes from the real package manifest.

Vix no longer forces published packages to appear as header-only when that does not match their actual build model.

Missing license information is also left missing rather than silently replaced with MIT.

Publication should preserve what the package declares and report invalid or incomplete metadata directly. It should not invent legal or technical properties on behalf of the author.

Publish output

Normal publishing output remains focused on the result.

A dry run no longer prints the complete registry JSON automatically:

vix publish --dry-run

Structured output remains available with:

vix publish --dry-run --json

Detailed human-readable diagnostics can be requested with:

vix publish --dry-run --verbose

This keeps routine publication readable while preserving the information needed for automation and investigation.

Validation and regression coverage

The release validates the new workflows across application generation, dependency management, Cloud commands, global installation, script execution, and public publishing.

WebSocket coverage includes:

  • attached runtime modules;
  • standalone runtime modules;
  • bridge modules;
  • client-only modules;
  • custom names through --name;
  • correct runtime selection;
  • generated vix.module metadata;
  • application and backend builds.

Backend template validation covers both the standard scaffold and API-only generation, including the absence of static frontend resources in API-only projects.

Cloud validation covers authentication, project linking, status reporting, lockfile upload, build report submission, explicit Cloud publication, duplicate versions, missing links, missing files, and API errors.

Package tests cover user-space global prefixes, executable exposure, package ownership, conflict detection, scoped uninstall names, and packages requiring the Vix build environment.

Git dependency tests cover URL normalization, stable tag selection, exact commit locking, CMake projects, header-only projects, target detection, ambiguous targets, generated dependency CMake, and normal run preparation.

Single-file run tests cover direct compilation, header-only include paths, compiled dependency fallback, temporary dependencies, and cache invalidation.

Public publishing tests cover tagged source inspection, repository identity, remote tag validation, header scanning, deterministic API metadata, manifest package types, missing licenses, and output modes.

Documentation

The documentation was updated to cover the workflows introduced or corrected by this release.

The application module documentation now explains WebSocket generation, workflow selection, custom names, module registration, and runtime participation.

Backend template documentation covers the generated WebSocket status panel and the difference between the standard frontend-serving backend and --api-only.

Cloud documentation covers login, project linking, status, lockfile upload, build reports, private package publication, and vix doctor --cloud.

Package documentation covers global installations, executable commands, ownership-aware uninstallation, Git dependencies, target detection, lockfile behavior, and dependency caching.

The CLI guides also document vix init, temporary vix run --dep experiments, and the stricter public publication requirements.

Compatibility

Existing public registry publication remains the default behavior of:

vix publish

Private Cloud publication requires the explicit --cloud option.

Existing backend templates continue to include frontend assets unless --api-only is selected.

Projects without Git dependencies continue to build and run through their existing workflow. Git support adds another dependency source without replacing registry packages.

Simple vix run scripts continue to use direct compilation where possible. Projects requiring compiled dependencies fall back to the generated CMake dependency environment automatically.

Global installations use a Vix-managed user prefix by default, avoiding changes to system directories. Packages that provide correct CMake installation rules continue to use those rules.

Cloud reporting remains optional. A project that is not authenticated or linked continues to build locally without requiring Softadastra Cloud.

Known limitations

The first Git dependency implementation supports CMake-based and header-only repositories. Projects that require another build system need explicit support in a later release or must provide a compatible CMake integration.

Automatic target detection is used only when Vix can identify a clear public consumer target. Repositories exposing several equally plausible targets require the developer to specify the intended target.

Temporary vix run --dep environments are intended for focused experiments. A dependency that becomes part of the application should be saved into vix.app so its exact resolution is recorded in the project lockfile.

Softadastra Cloud in this release coordinates project metadata, private packages, lockfiles, and build reports. It does not perform remote C++ compilation.

The generated WebSocket status panel checks connection availability only. Application authentication, reconnection policy, message protocols, and production frontend behavior remain the responsibility of the project.

Release summary

Vix.cpp v2.7.3 connects several workflows that previously required separate manual steps.

WebSocket modules can be generated with an explicit runtime model and built through normal application and backend projects. Backend services can be created without bundled frontend assets when the interface is hosted separately.

The CLI can authenticate with Softadastra Cloud, link local projects, upload dependency state, submit local build reports, and publish private package versions while keeping compilation on the developer’s machine.

Git repositories can participate in project dependencies, temporary single-file experiments, and reproducible lockfiles. Command-line packages can be installed globally into a user-controlled Vix prefix with tracked ownership and clean uninstallation.

Public registry publication now derives its metadata from the exact release tag and protects package identity across versions.

Together, these changes make Vix more useful across the full path from a small C++ file to a modular backend project with shared package and project state.