repoforge 0.1.1

Repository archive discovery and safe refresh helpers for thesa
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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# RepoForge

RepoForge provides repository archive discovery and safe refresh helpers used by
`thesa`.

Made by Trevor Knott for Knott Dynamics. RepoForge is part of the thesa archive
stack alongside `modelforge`, `siteforge`, Scrin, and Aisling.

The crate is intentionally focused. It scans an archive root for Git worktrees,
derives stable `owner/repo` slugs from GitHub remotes or archive paths, and
refreshes clones with `git pull --ff-only` without touching dirty worktrees.

## Install

```toml
[dependencies]
repoforge = "0.1"
```

The package and library crate name are both `repoforge`.

## Archive Layout

RepoForge is designed for archive trees like this:

```text
archives/
  octocat/
    Hello-World/
      .git/
  rust-lang/
    rust/
      .git/
```

When `remote.origin.url` is a GitHub URL, the slug is derived from the remote.
For example `https://github.com/octocat/Hello-World.git` becomes
`octocat/Hello-World`.

If there is no GitHub remote, RepoForge falls back to the path layout. For
example `archives/octocat/Hello-World` becomes `octocat/Hello-World`.

## Discovery

```rust
use std::path::Path;

let archives = repoforge::discover_git_archives(Path::new("./archives"), None)?;
for archive in archives {
    println!("{} -> {}", archive.slug, archive.path.display());
}
# Ok::<(), repoforge::RepoForgeError>(())
```

Use a filter to limit results by slug or path:

```rust
let archives = repoforge::discover_git_archives(
    std::path::Path::new("./archives"),
    Some("octocat"),
)?;
# Ok::<(), repoforge::RepoForgeError>(())
```

Discovery is recursive but stops descending when it finds a Git worktree.
`.git`, `.thesa`, and `target` directories are skipped.

## Refresh

```rust,no_run
let archives = repoforge::discover_git_archives(std::path::Path::new("./archives"), None)?;
let summary = repoforge::refresh_git_archives(&archives, 4);

println!(
    "updated={} unchanged={} failed={}",
    summary.updated,
    summary.unchanged,
    summary.failed.len()
);

if summary.has_failures() {
    for failure in &summary.failed {
        eprintln!("{}: {}", failure.slug, failure.message);
    }
}
# Ok::<(), repoforge::RepoForgeError>(())
```

Refresh behavior:

- Runs `git status --porcelain` before pulling.
- Dirty worktrees fail fast and are not pulled.
- Runs `git pull --ff-only` for clean worktrees.
- Reports `Updated` when `HEAD` changes.
- Reports `Unchanged` when the pull succeeds without changing `HEAD`.
- Uses bounded concurrency with `refresh_git_archives`.

## Slug Helpers

```rust
assert_eq!(
    repoforge::parse_github_remote_slug("git@github.com:octocat/Hello-World.git"),
    Some("octocat/Hello-World".to_string())
);
```

Supported GitHub remote forms include HTTPS and SSH:

- `https://github.com/owner/repo.git`
- `http://github.com/owner/repo.git`
- `git@github.com:owner/repo.git`
- `ssh://git@github.com/owner/repo.git`

## Safety Contract

RepoForge does not delete, reset, checkout, stash, or force-pull anything. It
only uses read-only Git inspection commands plus `git pull --ff-only` after
confirming the worktree is clean.

Callers such as `thesa` remain responsible for archive metadata sidecars,
checksums, and higher-level reporting.

## Role In Thesa

`thesa` uses RepoForge for Git archive discovery, GitHub slugging, dirty-tree
protection, and fast-forward-only refreshes. `thesa` then wraps those outcomes
with Scrin/Aisling terminal reporting and `.thesa` integrity manifests.