graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Running / installed / latest comparison shared by `graff update --check`,
//! the startup update notice, and the terminal `/update` (and `/version`)
//! surfaces. One policy so the CLI and the in-session command cannot drift.
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const Value = std.json.Value;
pub const State = enum { current, older, newer, dev, unable };
pub const Failure = enum { none, fetch, latest_tag };
pub const Check = struct {
running: []const u8,
latest: ?[]const u8 = null,
latest_tag: ?[]const u8 = null,
state: State,
failure: Failure = .none,
order: ?std.math.Order = null,
clean_release: bool = false,
};
const Version = struct {
major: u32,
minor: u32,
patch: u32,
// CLI hotfix segment (0.0.300.1); 0 when the tag has three parts.
// Desktop bundles stay 3-part (see electron/update-artifacts.cjs).
build: u32 = 0,
fn eql(self: Version, other: Version) bool {
return self.major == other.major and self.minor == other.minor and self.patch == other.patch and self.build == other.build;
}
fn order(self: Version, other: Version) std.math.Order {
if (self.major != other.major) return std.math.order(self.major, other.major);
if (self.minor != other.minor) return std.math.order(self.minor, other.minor);
if (self.patch != other.patch) return std.math.order(self.patch, other.patch);
return std.math.order(self.build, other.build);
}
};
pub const repo_api = "https://api.github.com/repos/justrach/codegraff/releases/latest";
pub const repo_download_base = "https://github.com/justrach/codegraff/releases/download";
pub fn stripV(s: []const u8) []const u8 {
return if (std.mem.startsWith(u8, s, "v")) s[1..] else s;
}
fn parseVersion(s: []const u8) ?Version {
var it = std.mem.splitScalar(u8, s, '.');
const major_s = it.next() orelse return null;
const minor_s = it.next() orelse return null;
const patch_s = it.next() orelse return null;
const build_s = it.next();
if (it.next() != null) return null;
const major = std.fmt.parseInt(u32, major_s, 10) catch return null;
const minor = std.fmt.parseInt(u32, minor_s, 10) catch return null;
if (build_s) |b| {
// A pre-release suffix belongs to the last segment only; anything
// after the patch digits when a fourth segment follows is malformed.
const patch = std.fmt.parseInt(u32, patch_s, 10) catch return null;
const build_digits = std.mem.indexOfAny(u8, b, "-+") orelse b.len;
const build = std.fmt.parseInt(u32, b[0..build_digits], 10) catch return null;
return .{ .major = major, .minor = minor, .patch = patch, .build = build };
}
const patch_digits = std.mem.indexOfAny(u8, patch_s, "-+") orelse patch_s.len;
const patch = std.fmt.parseInt(u32, patch_s[0..patch_digits], 10) catch return null;
return .{ .major = major, .minor = minor, .patch = patch };
}
fn isCleanReleaseVersion(s: []const u8) bool {
if (s.len == 0) return false;
var dots: u8 = 0;
for (s) |c| switch (c) {
'0'...'9' => {},
'.' => dots += 1,
else => return false,
};
// Releases are 3-part (0.0.301); CLI hotfixes add a fourth segment
// (0.0.300.1).
return dots == 2 or dots == 3;
}
/// Pure comparison. `latest_tag` is the GitHub tag (with or without `v`);
/// `running_version` is the build option baked into this process.
pub fn compare(running_version: []const u8, latest_tag: ?[]const u8) Check {
const running = stripV(running_version);
const tag = latest_tag orelse return .{ .running = running, .state = .unable, .failure = .fetch };
const latest = stripV(tag);
const release = parseVersion(latest) orelse return .{
.running = running,
.latest_tag = tag,
.state = .unable,
.failure = .latest_tag,
};
const current = parseVersion(running);
const clean = current != null and isCleanReleaseVersion(running);
const order = if (current) |v| v.order(release) else null;
if (!clean) return .{
.running = running,
.latest = latest,
.latest_tag = tag,
.state = .dev,
.order = order,
};
return .{
.running = running,
.latest = latest,
.latest_tag = tag,
.state = switch (order.?) {
.lt => .older,
.eq => .current,
.gt => .newer,
},
.order = order,
.clean_release = true,
};
}
/// True when `candidate` is a clean release at or newer than `latest_tag`.
/// Used to refuse a reinstall or implicit downgrade of an already-installed
/// binary that is current even when this process is older.
pub fn alreadyHasRelease(installed_version: []const u8, latest_tag: []const u8) bool {
const check = compare(installed_version, latest_tag);
return switch (check.state) {
.current, .newer => true,
// A prerelease at the same numeric base is still older than stable.
.dev => check.order == .gt,
.older, .unable => false,
};
}
pub fn fetchLatestReleaseTag(io: Io, gpa: Allocator, arena: Allocator, running_version: []const u8) ?[]const u8 {
var client: std.http.Client = .{ .allocator = gpa, .io = io };
defer client.deinit();
var aw: Io.Writer.Allocating = .init(arena);
defer aw.deinit();
const extra = [_]std.http.Header{.{ .name = "Accept", .value = "application/vnd.github+json" }};
const user_agent = std.fmt.allocPrint(arena, "simple-harness/{s}", .{running_version}) catch return null;
const res = client.fetch(.{
.location = .{ .url = repo_api },
.method = .GET,
.response_writer = &aw.writer,
.headers = .{ .user_agent = .{ .override = user_agent } },
.extra_headers = &extra,
}) catch return null;
if (@backingInt(res.status) != 200 or aw.writer.buffered().len > 64 * 1024) return null;
const parsed = std.json.parseFromSliceLeaky(Value, arena, aw.writer.buffered(), .{ .allocate = .alloc_always }) catch return null;
if (parsed != .object) return null;
const tag = parsed.object.get("tag_name") orelse return null;
return if (tag == .string) tag.string else null;
}
pub fn checkLatest(io: Io, gpa: Allocator, arena: Allocator, running_version: []const u8) Check {
return compare(running_version, fetchLatestReleaseTag(io, gpa, arena, running_version));
}
/// Leak-free tag extract for tests and the update service: copies into `buf`.
pub fn copyTagName(body: []const u8, buf: []u8) ?[]const u8 {
var parsed = std.json.parseFromSlice(Value, std.heap.page_allocator, body, .{}) catch return null;
defer parsed.deinit();
if (parsed.value != .object) return null;
const tag = parsed.value.object.get("tag_name") orelse return null;
if (tag != .string or tag.string.len == 0 or tag.string.len > buf.len) return null;
@memcpy(buf[0..tag.string.len], tag.string);
return buf[0..tag.string.len];
}
/// Human-facing `/version` response. The final note is deliberately present
/// for every state: a process cannot know whether its on-disk executable was
/// replaced after launch, and `/new`/`/resume` only mutate conversation state.
pub fn renderVersion(out: *Io.Writer, check: Check) !void {
try out.print("graff v{s} (running process)\n", .{check.running});
switch (check.state) {
.current => try out.print("latest release: v{s} — current\n", .{check.latest.?}),
.older => try out.print("latest release: v{s} — update available; run `graff update`\n", .{check.latest.?}),
.newer => try out.print("latest release: v{s} — running version is newer; not downgrading\n", .{check.latest.?}),
.dev => if (check.order == .gt)
try out.print("latest release: v{s} — newer/dev build; no release update needed\n", .{check.latest.?})
else
try out.print("latest release: v{s} — dev build; run `graff update` to install the release\n", .{check.latest.?}),
.unable => try out.writeAll("latest release: unable to check\n"),
}
try out.writeAll("If `graff update` installed a new binary, quit and start `graff` again. /new and /resume keep this process and do not reload the executable.\n");
}
pub fn commandText(io: Io, gpa: Allocator, running_version: []const u8) Allocator.Error![]u8 {
var arena_state = std.heap.ArenaAllocator.init(gpa);
defer arena_state.deinit();
const check = checkLatest(io, gpa, arena_state.allocator(), running_version);
var aw: Io.Writer.Allocating = .init(gpa);
errdefer aw.deinit();
renderVersion(&aw.writer, check) catch return error.OutOfMemory;
return aw.toOwnedSlice();
}
test "comparison classifies release and dev builds with one policy" {
try std.testing.expectEqual(State.current, compare("0.0.292", "v0.0.292").state);
try std.testing.expectEqual(State.older, compare("0.0.291", "v0.0.292").state);
try std.testing.expectEqual(State.newer, compare("0.0.293", "v0.0.292").state);
const dev = compare("0.0.293-2-gabc", "v0.0.292");
try std.testing.expectEqual(State.dev, dev.state);
try std.testing.expectEqual(std.math.Order.gt, dev.order.?);
}
test "unavailable and unparseable latest checks do not guess" {
try std.testing.expectEqual(Failure.fetch, compare("0.0.292", null).failure);
try std.testing.expectEqual(Failure.latest_tag, compare("0.0.292", "latest").failure);
}
test "four-segment hotfix versions order between their neighbors" {
// 0.0.300 < 0.0.300.1 < 0.0.301, and a missing fourth segment reads as 0.
try std.testing.expectEqual(State.older, compare("0.0.300", "v0.0.300.1").state);
try std.testing.expectEqual(State.newer, compare("0.0.300.1", "v0.0.300").state);
try std.testing.expectEqual(State.older, compare("0.0.300.1", "v0.0.301").state);
try std.testing.expectEqual(State.current, compare("0.0.300.1", "v0.0.300.1").state);
try std.testing.expectEqual(State.current, compare("0.0.300", "v0.0.300.0").state);
try std.testing.expectEqual(State.current, compare("0.0.300.0", "v0.0.300").state);
try std.testing.expectEqual(std.math.Order.lt, compare("0.0.300", "v0.0.300.1").order.?);
try std.testing.expectEqual(std.math.Order.gt, compare("0.0.300.2", "v0.0.300.1").order.?);
}
test "four-segment dev builds and the reinstall guard follow the same policy" {
const dev = compare("0.0.300.1-2-gabc", "v0.0.300.1");
try std.testing.expectEqual(State.dev, dev.state);
try std.testing.expectEqual(std.math.Order.eq, dev.order.?);
try std.testing.expect(alreadyHasRelease("0.0.300.1", "v0.0.300.1"));
try std.testing.expect(alreadyHasRelease("0.0.300.1", "v0.0.300"));
try std.testing.expect(!alreadyHasRelease("0.0.300", "v0.0.300.1"));
// Five segments are not a release on either side.
try std.testing.expectEqual(Failure.latest_tag, compare("0.0.300.1", "v0.0.300.1.2").failure);
try std.testing.expectEqual(State.dev, compare("0.0.300.1.2", "v0.0.300.1").state);
}
test "alreadyHasRelease refuses a reinstall when disk is current or newer" {
try std.testing.expect(alreadyHasRelease("0.0.292", "v0.0.292"));
try std.testing.expect(alreadyHasRelease("0.0.293", "v0.0.292"));
try std.testing.expect(!alreadyHasRelease("0.0.291", "v0.0.292"));
try std.testing.expect(!alreadyHasRelease("0.0.291-3-gabc", "v0.0.292"));
}
test "version response names the running process and reload boundary" {
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
try renderVersion(&aw.writer, compare("0.0.291", "v0.0.292"));
const text = aw.writer.buffered();
try std.testing.expect(std.mem.indexOf(u8, text, "v0.0.291 (running process)") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "update available") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "/new and /resume") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "do not reload the executable") != null);
}