Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@ a caller is here, what it changes inside a guard is in the commits.

## Unreleased

- Each crate carries a README of its own (what it reads, how to depend on
it, its example, compiled with the doctests), where every crate showed the
workspace's; the front door `milo-guards` keeps that one.
- The README's logo is named by its absolute URL, so crates.io shows it.

## 0.1.0 (2026-11-05)

The first release, on crates.io as `milo-guards` with the guards behind it.
Expand Down
2 changes: 1 addition & 1 deletion crates/code/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ edition.workspace = true
license.workspace = true
repository.workspace = true
homepage.workspace = true
readme.workspace = true
readme = "README.md"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
Expand Down
85 changes: 85 additions & 0 deletions crates/code/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# milo-guards-code

Reads Python and JavaScript code and says what it is certain to do to files
and what it runs, or that it does not understand it. Part of
[milo-guards](https://github.com/camiloazula/milo-guards); a reader, not a guard.

A shell line can hand an interpreter code (`python3 -c`, `node -e`), and an
agent can write a script or run a snippet directly. What matters to a guard
is which files the code deletes, writes, reads and moves, and what it runs.
This crate reads Python and JavaScript (Node, Bun and Deno) with their own
tree-sitter grammars and answers two questions of a piece of code:

- **What is it certain to do?** `read` gives the `Act`s the code makes, in
order: a delete, a write, a read, a move, a program started, an
environment changed, each with the paths it names. What the reader cannot
follow comes out as `Act::Unread`, never left out.
- **Does it understand the code?** `understand` holds the code to a strict
allow-list: a few plain statements whose every call, name and import is on
a short list that only computes. Anything else is
`Understanding::NotUnderstood`, and a caller must not take "no acts" for
"does nothing" for such code.

The reader judges nothing. Whether a delete of a path is risky is the
caller's: the shell guard of milo-guards turns an act into what it already
judges (a delete is `rm -rf PATH`, a command line a script a shell reads).

## Install

Through the front door, where it is the `code` feature (on by default) and
what the shell guard reads inline code with:

```toml
[dependencies]
milo-guards = "0.1"
```

Or on its own:

```toml
[dependencies]
milo-guards-code = "0.1"
```

If your program also links tree-sitter, it has to be on the 0.26 runtime:
tree-sitter allows one version per lockfile.

## Example

```rust
use milo_guards_code::{read, understand, Act, Arg, Language, Understanding};

// A snippet that computes is understood, and does nothing to a file.
let code = "print(1 + 1)";
assert!(read(Language::Python, code).acts.is_empty());
assert_eq!(
understand(Language::Python, code),
Understanding::Understood { imports: true },
);

// A delete is an act with the path it names, kept whatever the code is.
let code = "import shutil\nshutil.rmtree('/home/me')";
let reading = read(Language::Python, code);
assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Known(path))] if path == "/home/me"));
assert_eq!(understand(Language::Python, code), Understanding::NotUnderstood);

// A name only known when the code runs is an argument it does not know.
let reading = read(Language::JavaScript, "require('fs').rmSync(process.argv[1])");
assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Unknown(_))]));
```

## Contract

Like every milo-guards crate: no I/O and no environment reads, deterministic
(the same input gives the same answer on every machine), no policy (it
reports, and what to do with a finding is the caller's), what cannot be read
is risky, and nothing it is given makes it panic. The rules are on the
repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md).

## License

MIT or Apache-2.0, at your option
([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT),
[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of
[milo-guards](https://github.com/camiloazula/milo-guards); the API is on
[docs.rs](https://docs.rs/milo-guards-code).
11 changes: 11 additions & 0 deletions crates/code/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1000,3 +1000,14 @@ pub(crate) fn loads(specifier: &str, code: &str) -> Option<Act> {
Foreign::Outside => Act::Loads(shorten(code)),
})
}

/// The README's example, compiled and run with the doctests so it cannot
/// drift from the code. Only rustdoc's doctest pass reads the file, so
/// building this crate never needs the README.
#[cfg(doctest)]
#[allow(
clippy::disallowed_macros,
reason = "the README include is read by rustdoc's doctest pass only"
)]
#[doc = include_str!("../README.md")]
mod readme {}
2 changes: 1 addition & 1 deletion crates/core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ edition.workspace = true
license.workspace = true
repository.workspace = true
homepage.workspace = true
readme.workspace = true
readme = "README.md"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
Expand Down
64 changes: 64 additions & 0 deletions crates/core/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# milo-guards-core

What every guard of [milo-guards](https://github.com/camiloazula/milo-guards) shares: the verdict types, the path
model and the test kit.

A guard reads what an agent is about to do and says whether it is safe to do
without asking, or risky and why. This crate holds the parts of that which do
not depend on what is being read:

- **The verdict.** `Assessment` is `Safe`, or `Risky` with a `Finding` for
each reason. A finding names a rule of the guard's own enum (which
implements `RuleName`, with a stable wire name), the reason in words, the
target it is about, and where there is one, what to do instead.
- **The directories everything is judged against.** `Paths`: the working
directory, the home directory and the workspace folders, with the files
the caller gates (`Protected`).
- **The path model.** `Resolver` says where a path spelled out as text lands
(`Place`), by its spelling alone, for POSIX and Windows (`Flavour`), on
whatever host it runs.
- **For guard crates**, helpers that take a path's spelling apart
(`spelling`), and behind the `testing` feature the table checker and the
sample directories the guards test themselves with.

It depends on nothing beyond `std`, and does no I/O.

## Install

A caller of the guards depends on [`milo-guards`](https://docs.rs/milo-guards),
which re-exports this crate's types; depend on this crate directly only to
write a guard of your own.

```toml
[dependencies]
milo-guards-core = "0.1"
```

## Example

```rust
use milo_guards_core::{Flavour, Paths, Place, Resolver, Spelling};

let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]);
let resolver = Resolver::new(&paths);
let place = |path| resolver.place(Spelling::Plain(path), Flavour::Posix);
assert_eq!(place("src/../target"), Place::Inside);
assert_eq!(place("/home/me"), Place::Home { exact: true });
assert_eq!(place("/etc/hosts"), Place::Top("a system folder"));
```

## Contract

Like every milo-guards crate: no I/O and no environment reads, deterministic
(the same input gives the same answer on every machine), no policy (it
reports, and what to do with a finding is the caller's), what cannot be read
is risky, and nothing it is given makes it panic. The rules are on the
repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md).

## License

MIT or Apache-2.0, at your option
([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT),
[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of
[milo-guards](https://github.com/camiloazula/milo-guards); the API is on
[docs.rs](https://docs.rs/milo-guards-core).
11 changes: 11 additions & 0 deletions crates/core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -44,3 +44,14 @@ pub use paths::{Paths, Protected, ProtectedKind};
pub use place::{Place, Sensitivity};
pub use resolve::{Flavour, Resolver, Spelling};
pub use verdict::{Assessment, Finding, RuleName};

/// The README's example, compiled and run with the doctests so it cannot
/// drift from the code. Only rustdoc's doctest pass reads the file, so
/// building this crate never needs the README.
#[cfg(doctest)]
#[allow(
clippy::disallowed_macros,
reason = "the README include is read by rustdoc's doctest pass only"
)]
#[doc = include_str!("../README.md")]
mod readme {}
2 changes: 1 addition & 1 deletion crates/file/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ edition.workspace = true
license.workspace = true
repository.workspace = true
homepage.workspace = true
readme.workspace = true
readme = "README.md"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
Expand Down
79 changes: 79 additions & 0 deletions crates/file/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# milo-guards-file

Judges one read or write of a path through a file API and says whether it is
safe without asking, or risky and why. The file guard of
[milo-guards](https://github.com/camiloazula/milo-guards).

A shell line shows what a shell is about to do; an agent also reads and
writes files through a file API, and no line shows those calls. This guard
takes the two things such a call has, an `Access` and the path as the agent
wrote it, and judges them: `judge`.

The path is one literal path, resolved by its spelling alone against the
`Paths` the caller passes: relative to the working directory, `~` as the home
directory, `..` applied, and the Windows spellings (drives, shares, long
paths, short names, any case) read as Windows reads them, whatever host the
guard runs on. Nothing is read from the disk, so a symlink is judged by its
own name.

- A **read** is safe wherever it lands, except a key or a credential
(`read_secret`). An agent reads widely, and reading is what a caller lets
run unasked.
- A **write** (an edit, a create, an append, a rename's target) is safe
inside a workspace folder, to a temporary file and to the null device.
Anywhere else is a finding: beyond the workspace (`write_outside`), to a
key, a startup file, a file a tool runs on its own or the repository's
history (`write_sensitive`), or to what the caller gates
(`write_protected`).
- A path that is not one literal path, or that cannot be placed, is
`unreadable`; one on another machine is `network_share`.

## Install

Through the front door, where it is the `file` feature (on by default):

```toml
[dependencies]
milo-guards = "0.1"
```

Or on its own:

```toml
[dependencies]
milo-guards-file = "0.1"
```

## Example

```rust
use milo_guards_file::{judge, Access, Paths, Rule};

let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]);

assert!(judge(Access::Read, "src/main.rs", &paths).is_safe());
assert!(judge(Access::Write, "src/main.rs", &paths).is_safe());

let assessment = judge(Access::Read, "~/.ssh/id_ed25519", &paths);
assert_eq!(assessment.findings()[0].rule, Rule::ReadSecret);
assert_eq!(assessment.findings()[0].reason, "reads your SSH keys");

let assessment = judge(Access::Write, "../other/x", &paths);
assert_eq!(assessment.findings()[0].rule, Rule::WriteOutside);
```

## Contract

Like every milo-guards crate: no I/O and no environment reads, deterministic
(the same input gives the same answer on every machine), no policy (it
reports, and what to do with a finding is the caller's), what cannot be read
is risky, and nothing it is given makes it panic. The rules are on the
repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md).

## License

MIT or Apache-2.0, at your option
([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT),
[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of
[milo-guards](https://github.com/camiloazula/milo-guards); the API is on
[docs.rs](https://docs.rs/milo-guards-file).
11 changes: 11 additions & 0 deletions crates/file/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -343,3 +343,14 @@ fn has_variable(path: &str) -> bool {
_ => false,
})
}

/// The README's example, compiled and run with the doctests so it cannot
/// drift from the code. Only rustdoc's doctest pass reads the file, so
/// building this crate never needs the README.
#[cfg(doctest)]
#[allow(
clippy::disallowed_macros,
reason = "the README include is read by rustdoc's doctest pass only"
)]
#[doc = include_str!("../README.md")]
mod readme {}
2 changes: 1 addition & 1 deletion crates/secrets/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ edition.workspace = true
license.workspace = true
repository.workspace = true
homepage.workspace = true
readme.workspace = true
readme = "README.md"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
Expand Down
Loading
Loading