README
¶
JVS
Pre-GA control data for real folders
JVS (Juicy Versioned Workspaces) is in a pre-GA surface collapse. The current release-facing user path is intentionally small: initialize a folder, inspect status/health, and use project clone/metadata commands that remain part of the release path. The old public save/restore workflow is not the active user path.
mkdir myproject
cd myproject
jvs init
echo "hello" > notes.txt
jvs status
jvs doctor
jvs repo clone ../myproject-copy --dry-run
Trusted platform callers use the internal direct AFSCP contract documented in
docs/contracts/jvs-afscp-direct-v1.md. That direct contract is not public
user CLI guidance.
Why JVS?
| Need | JVS approach |
|---|---|
| Prepare a folder | jvs init [folder] creates JVS control data without moving files |
| Inspect current state | jvs status and jvs doctor report folder/control-data health |
| Keep real directories | A workspace is a normal folder; your tools keep using normal filesystem paths |
| Clone project metadata safely | jvs repo clone <target-folder> --dry-run previews a clone |
Install
Download a binary from GitHub Releases or build from source:
git clone https://github.com/agentsmith-project/jvs.git
cd jvs
make build
With Go installed, use a published version tag:
go install github.com/agentsmith-project/jvs/cmd/jvs@<VERSION>
Core Commands
| Command | What it does |
|---|---|
jvs init [folder] |
Adopt a folder and prepare JVS control data |
jvs status |
Show the active folder, workspace, control-data pointer, and unsaved-change summary |
jvs doctor |
Check repository health |
jvs repo clone <target-folder> [--dry-run] |
Clone a local JVS project into a new folder |
jvs completion <shell> |
Generate shell completion |
How It Works
After jvs init, your folder stays where it is:
myproject/
├── .jvs/ # JVS control data
├── notes.txt # your managed files
└── ...
JVS control data is not workspace content. The direct AFSCP path keeps JVS metadata outside the managed HOME and uses a strict JuiceFS clone path with no public slow fallback.
Documentation
Start with the collapsed pre-GA docs:
| Document | Description |
|---|---|
| Overview | Active surface and boundaries |
| CLI Spec | Release-facing command surface |
| AFSCP Direct Contract | Internal trusted platform JSON contract |
| Documentation Index | Maintainer and historical reference map |
Contributor, architecture, and release evidence documents live under docs/.
Development
make test
make contract-check
make conformance
make lint
make release-gate
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
jvs
command
|
|
|
internal
|
|
|
audit
Package audit provides audit logging with hash chain verification.
|
Package audit provides audit logging with hash chain verification. |
|
capacitygate
Package capacitygate provides preflight free-space checks for operations that materialize save point payloads before mutating public state.
|
Package capacitygate provides preflight free-space checks for operations that materialize save point payloads before mutating public state. |
|
clonehistory
Package clonehistory owns durable metadata for save points imported by repository clone.
|
Package clonehistory owns durable metadata for save points imported by repository clone. |
|
compression
Package compression provides compression support for JVS snapshots.
|
Package compression provides compression support for JVS snapshots. |
|
diff
Package diff implements snapshot differencing for JVS.
|
Package diff implements snapshot differencing for JVS. |
|
doctor
Package doctor provides repository health checking and repair operations.
|
Package doctor provides repository health checking and repair operations. |
|
engine
Package engine provides snapshot engines for copying worktree data.
|
Package engine provides snapshot engines for copying worktree data. |
|
gc
Package gc provides garbage collection for snapshots.
|
Package gc provides garbage collection for snapshots. |
|
integrity
Package integrity provides checksum and payload hash computation for snapshots.
|
Package integrity provides checksum and payload hash computation for snapshots. |
|
lifecycle
Package lifecycle contains durable primitives for repo and workspace lifecycle operations.
|
Package lifecycle contains durable primitives for repo and workspace lifecycle operations. |
|
recovery
Package recovery manages durable recovery plans for restore operations.
|
Package recovery manages durable recovery plans for restore operations. |
|
recoverystate
Package recoverystate classifies external restore/recovery state that can block mutations on separated-control repositories.
|
Package recoverystate classifies external restore/recovery state that can block mutations on separated-control repositories. |
|
repo
Package repo handles JVS repository initialization and discovery.
|
Package repo handles JVS repository initialization and discovery. |
|
repoclone
Package repoclone implements local JVS project cloning.
|
Package repoclone implements local JVS project cloning. |
|
restore
Package restore handles snapshot restore operations.
|
Package restore handles snapshot restore operations. |
|
restoreplan
Package restoreplan builds and persists preview plans for destructive restore operations.
|
Package restoreplan builds and persists preview plans for destructive restore operations. |
|
snapshot
Package snapshot handles snapshot creation, listing, and querying.
|
Package snapshot handles snapshot creation, listing, and querying. |
|
snapshotpayload
Package snapshotpayload materializes and hashes the logical user payload stored inside a snapshot directory.
|
Package snapshotpayload materializes and hashes the logical user payload stored inside a snapshot directory. |
|
sourcepin
Package sourcepin manages active source save point pins.
|
Package sourcepin manages active source save point pins. |
|
terminal
Package terminal centralizes interactive terminal detection for CLI output.
|
Package terminal centralizes interactive terminal detection for CLI output. |
|
verify
Package verify provides snapshot integrity verification.
|
Package verify provides snapshot integrity verification. |
|
worktree
Package worktree provides worktree management operations.
|
Package worktree provides worktree management operations. |
|
pkg
|
|
|
color
Package color provides terminal color output support for JVS.
|
Package color provides terminal color output support for JVS. |
|
config
Package config provides configuration file support for JVS.
|
Package config provides configuration file support for JVS. |
|
fsutil
Package fsutil provides filesystem utilities for atomic operations and syncing.
|
Package fsutil provides filesystem utilities for atomic operations and syncing. |
|
jsonutil
Package jsonutil provides deterministic JSON marshaling.
|
Package jsonutil provides deterministic JSON marshaling. |
|
jvs
Package jvs provides a high-level Go facade for JVS file-system version control.
|
Package jvs provides a high-level Go facade for JVS file-system version control. |
|
logging
Package logging provides structured logging for JVS.
|
Package logging provides structured logging for JVS. |
|
pathutil
Package pathutil provides path and name validation utilities for JVS.
|
Package pathutil provides path and name validation utilities for JVS. |
|
progress
Package progress provides progress reporting for long-running operations.
|
Package progress provides progress reporting for long-running operations. |
Click to show internal directories.
Click to hide internal directories.