astvcs-develop

name	astvcs-develop
description	Builds, tests, and validates the astvcs Rust CLI. Use when changing astvcs source, fixing CI, running cargo test or clippy, or when the user asks about project layout, build requirements, or release binaries.
compatibility	Requires Rust 1.96+ (edition 2024), cargo, and a working C toolchain for tree-sitter native deps. CI runs on push/PR via `.github/workflows/ci.yml`. Tagged releases (`v*`) build and publish binaries via `.github/workflows/release.yml`.
metadata	{"project":"astvcs"}

Develop astvcs

Gather

1. Read docs/architecture.md for repository model, AST diff, and merge behavior.
2. Read docs/commands.md for CLI flags and subcommands.
3. Read README.md for project overview, documentation map, quick start, and scope at a glance.
4. Identify which layer changed: frontend/, graph/, diff/, intent/, merge/, store/, network/, or CLI (main.rs, store/repo.rs).

Act

Build and verify

Run the verify script after substantive changes:

bash .cursor/skills/astvcs-develop/scripts/verify.sh

Windows: powershell -File .cursor/skills/astvcs-develop/scripts/verify.ps1

Benchmark astvcs vs Git (optional):

bash .cursor/skills/astvcs-develop/scripts/benchmark-git.sh

Or run steps manually:

cargo test
cargo test --test props --test history_smoke --test diff_git
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release

Release packaging

• astvcs --version prints CARGO_PKG_VERSION from Cargo.toml (clap #[command(version = env!("CARGO_PKG_VERSION"))] on the root Parser in src/main.rs).
• Push a tag matching v* (for example v0.1.0) to trigger .github/workflows/release.yml.
• The workflow matrix builds on ubuntu-latest and windows-latest with cargo build --release --locked, runs smoke tests (astvcs --version, astvcs init creating .astvcs), packages astvcs-linux-x86_64.tar.gz and astvcs-windows-x86_64.zip, and attaches them to a GitHub Release via softprops/action-gh-release.
• Windows jobs enable symlink creation (same registry step as ci.yml) so smoke tests can create symlinks if needed.
• Draft release notes from docs/RELEASE.md. Do not publish to crates.io.

Code change rules

• Minimize scope. Match existing module layout and naming in src/.
• NodeId is per-snapshot only. Cross-version continuity comes from diff_graphs alignment, not persistent ids.
• Refs and timeline use commit ids (hash_commit); states/ and blobs use manifest ids (hash_manifest).
• Parse failures and unsupported extensions fall back to text blobs with warning: on stderr; AST-capable text fallback paths also show (text fallback) in status and a banner plus parse mode: intent in diff.
• NUL-containing or non-UTF-8 file content stores as FileContent::Binary (byte-for-byte round-trip).
• Operational detail uses trace::notice (gated by -v); user-facing problems use trace::warning. Default diffs and conflicts stay focused, --details restores structural diagnostics, and -v includes details plus notices.

Source layout

Module	Role
graph/	AstGraph, NodeId, Mutation, apply_batch
frontend/	tree-sitter parse, extension map, text fallback
diff/	structural alignment (LCS), text Myers diff, change-first diff --view HTML (view.rs)
intent/	human-readable edit intents, overlap checks
merge/	three-way merge, conflict detection
store/	blobs, pack storage (pack.rs), timeline, repo CLI backend, manifest metadata (manifest.rs, tracked.rs, working.rs), incremental working-tree scan (walk.rs, scan_cache.rs); error.rs, identity.rs, lock.rs, hooks.rs, rebase.rs, cherry_pick.rs, blame.rs, bisect.rs, atomic.rs, format.rs, reachability.rs, integrity.rs (gc, fsck, repack), git_import.rs (import-git snapshot migration)
network/	remotes, fetch/pull/push/clone, HTTP/HTTPS serve (optional bearer auth, TLS via rustls), SSH remotes (OpenSSH + remote-serve protocol)
unparser.rs	AST back to source text (leading trivia between siblings)

Verify

• All tests pass (cargo test).
• Clippy is clean with -D warnings.
• If CLI behavior changed (including --details, identity, --json, reset, revert, merge, rebase, cherry-pick, blame, bisect, pull, checkout, stash, tag, branch remove, branch create, default_branch config sync, add, staging index, client hooks (--no-verify, .astvcs/hooks/), gc (--prune, --prune-history), fsck (--repair, --prune-refs), repack, import-git, binary file tracking, symlink and executable file modes, materialize dirty-tree guard, remote ref resolution, parse fallback visibility in status/diff, diff --view change-first HTML viewer, incremental scan cache / --full-scan, on-disk format versioning / migrations, repository lock errors, shallow fetch/clone --depth, serve auth/TLS/concurrency, or SSH/HTTPS remotes), update docs/commands.md and add or extend a test in tests/integration.rs; update docs/architecture.md when network, locking, atomicity, reachability, gc/fsck/repack (including two-tier history retention and fsck repair), author identity, structured errors, binary blobs, symlink/mode metadata, parse fallback policy, incremental scan cache, on-disk format versioning, staging index, default branch config, lightweight tags, client hooks, rebase, cherry-pick, blame, bisect, git import interoperability, diff_graphs_detailed / alignment export / diff --view, or repository model semantics change; refresh README.md (what it is / is not, documentation map, quick start, scope at a glance) when user-facing boundaries or onboarding change.
• If merge, revert, or diff semantics changed, update the matching fixture under examples/ and its row in examples/README.md. After refreshing walkthrough commands, run ./examples/run-demos.sh (or ./examples/run-demos.sh --log-path <file>; Windows: .\examples\run-demos.ps1) to replay all nine fixtures non-interactively (workflow, merge, identity, same-file, network, lifecycle, shallow, import-git when git is on PATH, serve).
• If network sync behavior changed, update docs/architecture.md network section and extend tests/integration.rs or src/network/ tests (serve auth, HTTPS/TLS, serve concurrency, SSH remotes and remote-serve protocol, transport bearer token and --insecure, file remote unchanged, shallow fetch/clone --depth).