kcode-rust-libs-v2 1.0.0

Create, edit, validate, and publish complete agent-authored Rust library snapshots
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

# Agent Integration Reference

`kcode-rust-libs-v2` is the synchronous server-side boundary for creating, opening, editing, checking, and publishing small agent-authored Rust libraries. Version 1.0.0 intentionally replaces the unused experimental 0.1.0 API.

## Rust API

The public API has exactly six operations:

```rust
use kcode_rust_libs_v2::{File, create, docs, open};

let root = "/srv/kcode-rust-libs";
let token = load_crates_io_token_from_private_server_state()?;

let mut library = open(root, "example-lib", &token)?;
library.files.push(File {
    path: "tests/new_case.rs".to_owned(),
    contents: "#[test]\nfn new_case() {}\n".to_owned(),
});
library.write()?;
library.check()?;
library.publish()?;

let (version, documentation) = docs(root, "example-lib")?;
```

```text
create(root, name, token) -> Result<Lib>
open(root, name, token)   -> Result<Lib>
docs(root, name)          -> Result<(String, String)>
Lib::write()              -> Result<()>
Lib::check()              -> Result<()>
Lib::publish()            -> Result<()>
```

`Lib::files` is the complete editable source: a canonically sorted `Vec<File>` whose `File` values have public `path` and `contents` fields. There is no manager, constructor object, publisher object, public snapshot identifier, name/version/files accessor method, check-result model, close, lock, patch, delete, rename, reload, list, or compatibility alias.

## Creation, opening, and documentation

`create` makes a minimal Rust 2024 library at version `0.1.0` containing root `Cargo.toml`, root `Documentation.md`, and `src/lib.rs`, then returns it as a `Lib`.

`open` returns every useful UTF-8 source file once in canonical path order. Root `Cargo.toml` and `Documentation.md` are included. Root `Cargo.lock` is excluded even if legacy material exists, and documentation has no second representation. Paths must be canonical relative UTF-8 paths. Traversal, symlinks, special files, non-UTF-8 files, duplicate paths, invalid package metadata, and noncanonical versions are rejected.

`docs` is a lightweight read of only the canonical root `[package].version` and complete root `Documentation.md`. It does not traverse or render the remaining source.

## Writing and concurrency

Edit `Lib::files`, then call `write`. The vector is the complete replacement: omitted files disappear. `Cargo.lock` is reserved for ephemeral validation and cannot be written as managed source.

Each `Lib` privately retains the repository generation from which it was opened. `write` validates and stages the complete replacement, acquires only a call-scoped filesystem lock, compares that private generation with current state, and atomically advances the repository head. If another writer advanced first, `write` returns a bounded `stale_snapshot` error and the caller must reopen. A successful write refreshes the private generation and canonical file vector, so the same `Lib` can write again. Dropping or abandoning a `Lib` leaves no lock held.

## Checking and publication

`check` validates exactly the current in-memory `Lib::files` and returns `Ok(())` on success. It writes those files to disposable work, resolves dependencies once with networked `cargo fetch`, and uses the resulting ephemeral lockfile for network-disabled formatting, locked/offline build, Clippy with warnings denied, tests, and doc tests. The workspace, targets, Cargo home, and lockfile are discarded.

`publish` reruns that complete check on the same in-memory source and publishes that exact source through a fresh disposable workspace. The registry token supplied to `create` or `open` is private implementation data, is passed to Cargo only through the publication environment, is absent from command arguments and managed source, and is redacted from errors. The integrating server must keep the token out of model-facing arguments.

Both methods return only `Ok(())` on success. Failures are one bounded displayable error containing a category and useful diagnostic excerpt; successful stage logs and compiler chatter are not returned.

## Model-facing operations

The server adapter should expose only these lower-case, collision-safe names:

```text
kcode-rust-libs/create
kcode-rust-libs/open
kcode-rust-libs/docs
kcode-rust-libs/write
kcode-rust-libs/check
kcode-rust-libs/publish
```

The adapter owns configured roots, private credentials, authorization, transport, and compact rendering. Check, package publication, independent registry verification, adapter adoption, deployment, and live behavior remain separate states.