Documentation channel: current development main at compiler checkpoint 1d7e15e. The latest tagged release is v0.0.3; pages identify APIs that are not yet released.

Packages

Strut resolves local and immutable Git packages into a deterministic lock graph. Builds and editor tooling consume exact locked, checksum-verified cache entries; dependency code is never executed during acquisition.

Using packages

include <example>;
include <example/helpers.p>;

The first form loads the package's declared entry. The second loads an explicit relative file. A locked transitive package can be imported by another package, so diamond graphs share one verified package instance. Standard modules such as filesystem use the same syntax but require no manifest entry.

Manifest

Projects and packages use strut.json. A local dependency can be added with strut add ../checkout. Reproducible remote dependencies declare a semantic requirement, Git URL, and exact hexadecimal commit:

{
  "name": "todo-service",
  "version": "0.1.0",
  "entry": "src/main.p",
  "dependencies": {
    "local-tools": "1.2.3",
    "example": {
      "version": "^1.4.0",
      "git": "https://github.com/example/example-strut.git",
      "rev": "0123456789abcdef0123456789abcdef01234567"
    }
  }
}

Requirements support exact 1.2.3, compatible ^1.2.3, patch-compatible ~1.2.3, and *. Git branches, tags, latest, and install scripts are not resolution identities.

Install, update, and offline use

strut install
strut install --offline
strut update

strut install preserves a valid strut.lock.json, verifies every cached digest, and restores missing or corrupt Git packages from their locked commits. With no lockfile, it resolves one. strut update explicitly re-resolves the manifest and rewrites the lock.

strut install --offline performs no acquisition. It succeeds only when every locked checksum is verified in the cache. A failure names the package, version, revision, expected cache identity, and normal install command.

Lockfile and transitive graph

Commit strut.lock.json for applications. Schema version 2 records every direct and transitive package with its original requirement, exact version, logical source, immutable revision, SHA-256 checksum, and exact dependency edges. Entries and edges are serialized deterministically and contain no machine-specific paths or timestamps.

Shared dependencies are deduplicated when version and source requirements agree. Conflicts identify both requesters and requirements. Cycles report the complete deterministic chain.

Content-addressed cache and integrity

Entries use name/version/sha256 beneath the platform cache directory. STRUT_HOME overrides the base for CI. Acquisition stages content beside the cache, rejects symlinks and unsafe paths, verifies SHA-256, and atomically promotes the result. Concurrent installers verify and reuse the winner.

A checksum mismatch is always fatal offline. Normal install can reacquire and repair a locked Git package. Package names, paths, URLs, and exact revisions are validated before filesystem or Git operations.

Inspecting package state

strut packages
strut packages --json
strut project --json

strut packages reports direct/transitive status, requested and resolved versions, immutable revision, checksum, source, verified cache state, and offline availability. Project JSON adds the lockfile path/schema, counts, graph resolution, cache health, stale/corrupt state, and offline readiness.

Reproducible CI

strut install
strut install --offline
strut make

A clean worker can reproduce a committed lock from immutable Git revisions. Cache the directory reported by strut project --json; once populated, the offline command proves the build requires no package network. Do not run strut update in a locked build job.

Editor behavior

The language server indexes symbols only from the validated lock and verified cache. Completion, hover, signature help, and go-to-definition work without acquisition. Missing entries produce an actionable strut install diagnostic; opening a project never contacts a package remote.

Troubleshooting