Skip to content
zit Artifact [f1b6608d42]
Login

Artifact [f1b6608d42]

Artifact f1b6608d427ea6431836f4ca3f42b77da761c7c0e4174b9f0ad1f50751685958:


const std = @import("std");
const repeat = @import("zit").repeat;
const logstore = @import("zit").logstore;
const storage = @import("zit").storage;
const artifact = @import("zit").artifact;
const support = @import("support.zig");
const addManaged = support.addManaged;
const amendHash = support.amendHash;
const checkinHash = support.checkinHash;
const expectExit = support.expectExit;
const expectExitDiag = support.expectExitDiag;
const freeResult = support.freeResult;
const initRepo = support.initRepo;
const initTreeRepo = support.initTreeRepo;
const parseCheckin = support.parseCheckin;
const readFile = support.readFile;
const runCommitEnv = support.runCommitEnv;
const runZit = support.runZit;
const seedRootCheckin = support.seedRootCheckin;
const sha3HexAlloc = support.sha3HexAlloc;
const writeFile = support.writeFile;

// ==========================================================================
// `zit artifact` end-to-end (contracts/artifact.md B-artifact-1..14). zit's
// plumbing window: a read-only describe (`whatis`) / dump (`--raw`) of ONE
// stored artifact addressed by its hash — every artifact kind, file blobs
// included. Card interpretation flows through the ONE artifact parser; the
// oracles here are RFC-derived (sha3-256 of content for a blob name; the
// stored manifest bytes read back through the library), never fossil.
// ==========================================================================

const artifact_help_expected =
    \\usage: zit artifact HASH [--raw]
    \\
    \\Describe or dump a single stored artifact addressed by its hash. HASH is a full
    \\or abbreviated (>=4 character) lowercase hexadecimal artifact ID, resolved
    \\against every stored artifact — file blobs included. Branch and tag names are
    \\not accepted; use 'zit info' for those.
    \\
    \\Without --raw, print a summary: the full hash, the artifact's size, its type,
    \\and — for a structural artifact — one line per card and whether its Z
    \\self-checksum verifies. A blob reports its size and whether it is binary.
    \\
    \\With --raw, write the artifact's exact stored bytes to standard output,
    \\verbatim — no trailing newline is added and binary content passes through
    \\unchanged. Hashing those bytes reproduces HASH.
    \\
    \\options:
    \\      --raw       write the exact stored bytes instead of a summary
    \\  -R, --repo <path>
    \\                read this repository instead of the one found from the
    \\                current directory; <path> is the directory holding '.zit'
    \\                (or the '.zit' file itself). No working tree is required.
    \\  -h, --help      show this help and exit
    \\
    \\exit status:
    \\  0  success
    \\  1  operational failure (not a repository, unreadable state, a refused
    \\     action) — the diagnostic on stderr names it
    \\  2  usage error (an unknown option or unexpected argument)
    \\
;

/// Appends one artifact frame keyed by `digest` (its raw 32-byte name) holding
/// `content`, straight into the repo's `.zit` through the library — the only
/// way to seed an artifact the CLI itself would never mint: a Z-mismatched
/// structural artifact (B-artifact-5) and a prefix-colliding pair
/// (B-artifact-7). A read-write reopen + append + commit, exactly like a real
/// writer. The derive tolerates a non-parseable/Z-mismatched frame as an opaque
/// blob (repoview.linkOne "crosslink whatever parses"), so `repo.open` succeeds.
fn injectFrame(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, digest: [32]u8, content: []const u8) !void {
    var file = try dir.openFile(io, ".zit", .{ .mode = .read_write });
    defer file.close(io);
    const st = try file.stat(io);
    var fs = storage.FileStorage.init(io, file, st.size);
    var log = try logstore.LogStore.open(gpa, fs.storageFile(), 0);
    defer log.deinit(gpa);
    _ = try log.put(&digest, content);
    try log.commit();
}

test "cli artifact B-artifact-1: a manifest summary carries the hash, type, size, and one line per card" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try writeFile(io, tmp.dir, "a.txt", "alpha\n");
    try writeFile(io, tmp.dir, "b.txt", "beta\n");
    try addManaged(gpa, io, tmp.dir, &.{ "a.txt", "b.txt" });
    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);
    const ck = try gpa.dupe(u8, try checkinHash(commit.stdout));
    defer gpa.free(ck);

    // The stored-manifest byte length is the size oracle, read back through the
    // library (never a hand-count).
    var mc = try parseCheckin(gpa, io, tmp.dir, ck);
    defer mc.deinit();
    const size = mc.bytes.len;

    var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", ck });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    try std.testing.expectEqualStrings("", res.stderr); // stream discipline

    // Header line is the full hash; the type and size lines are exact.
    var lines = std.mem.splitScalar(u8, res.stdout, '\n');
    try std.testing.expectEqualStrings(ck, lines.first());
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "type: manifest\n") != null);
    const size_line = try std.fmt.allocPrint(gpa, "size: {d} bytes\n", .{size});
    defer gpa.free(size_line);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, size_line) != null);

    // One F line per file, each `F <name> <sha3(content)>` (§4.7.6 decoded via
    // the ONE parser). The blob hashes are RFC-derived here.
    const a_hash = try sha3HexAlloc(gpa, "alpha\n");
    defer gpa.free(a_hash);
    const b_hash = try sha3HexAlloc(gpa, "beta\n");
    defer gpa.free(b_hash);
    const a_line = try std.fmt.allocPrint(gpa, "\nF a.txt {s}\n", .{a_hash});
    defer gpa.free(a_line);
    const b_line = try std.fmt.allocPrint(gpa, "\nF b.txt {s}\n", .{b_hash});
    defer gpa.free(b_line);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, a_line) != null);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, b_line) != null);
    // The comment, user, and the verified Z verdict are shown too.
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "\nC root\n") != null);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "\nU u\n") != null);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "\nZ: verified\n") != null);
}

test "cli artifact B-artifact-2: a control artifact reports type control and its T cards' sign, name, target" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    const root_hash = try seedRootCheckin(gpa, io, tmp.dir);
    defer gpa.free(root_hash);

    // `amend --branch` mints a control artifact whose T cards move the check-in
    // onto a new branch (§4.7.16): a `*sym-feature` add and a `-sym-trunk`
    // cancel, both targeting the root check-in.
    var am = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "amend", root_hash, "--branch", "feature" });
    defer freeResult(gpa, &am);
    try expectExit(am.term, 0);
    const control_hash = try gpa.dupe(u8, try amendHash(am.stdout));
    defer gpa.free(control_hash);

    var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", control_hash });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    try std.testing.expectEqualStrings("", res.stderr);

    var lines = std.mem.splitScalar(u8, res.stdout, '\n');
    try std.testing.expectEqualStrings(control_hash, lines.first());
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "type: control\n") != null);
    // T <sign><name> <target>: sign+name glued, self/hash target rendered.
    const sym_add = try std.fmt.allocPrint(gpa, "\nT *sym-feature {s}\n", .{root_hash});
    defer gpa.free(sym_add);
    const sym_cancel = try std.fmt.allocPrint(gpa, "\nT -sym-trunk {s}\n", .{root_hash});
    defer gpa.free(sym_cancel);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, sym_add) != null);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, sym_cancel) != null);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "\nZ: verified\n") != null);
}

test "cli artifact B-artifact-3: a file blob reports type file, its size, and its binary/text verdict" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // A text file and a NUL-bearing binary file. Each blob's name is the
    // §7.2 sha3 of its content.
    const text = "plain text content\n";
    var binary: [64]u8 = undefined;
    for (&binary, 0..) |*b, i| b.* = @intCast(i % 256); // includes NUL at 0, no trailing LF
    try writeFile(io, tmp.dir, "t.txt", text);
    try writeFile(io, tmp.dir, "b.bin", &binary);
    try addManaged(gpa, io, tmp.dir, &.{ "t.txt", "b.bin" });
    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);

    const text_hash = try sha3HexAlloc(gpa, text);
    defer gpa.free(text_hash);
    const bin_hash = try sha3HexAlloc(gpa, &binary);
    defer gpa.free(bin_hash);

    // Text blob: type file, exact size, binary: no. No card listing, no Z line.
    {
        var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", text_hash });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 0);
        try std.testing.expectEqualStrings("", res.stderr);
        const expected = try std.fmt.allocPrint(gpa, "{s}\ntype: file\nsize: {d} bytes\nbinary: no\n", .{ text_hash, text.len });
        defer gpa.free(expected);
        try std.testing.expectEqualStrings(expected, res.stdout);
    }
    // Binary blob: binary: yes, exact size.
    {
        var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", bin_hash });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 0);
        const expected = try std.fmt.allocPrint(gpa, "{s}\ntype: file\nsize: {d} bytes\nbinary: yes\n", .{ bin_hash, binary.len });
        defer gpa.free(expected);
        try std.testing.expectEqualStrings(expected, res.stdout);
    }
}

test "cli artifact B-artifact-4: --raw is byte-exact and its bytes hash back to HASH for manifest, control, and blob" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    const root_hash = try seedRootCheckin(gpa, io, tmp.dir); // one manifest + one blob "v1\n"
    defer gpa.free(root_hash);
    var am = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "amend", root_hash, "--branch", "feature" });
    defer freeResult(gpa, &am);
    try expectExit(am.term, 0);
    const control_hash = try gpa.dupe(u8, try amendHash(am.stdout));
    defer gpa.free(control_hash);
    const blob_hash = try sha3HexAlloc(gpa, "v1\n");
    defer gpa.free(blob_hash);

    // For each kind: --raw emits the exact stored bytes, and sha3-256 of those
    // bytes reproduces HASH (§3.4 round-trip). The blob additionally equals its
    // source content verbatim — no trailing newline added.
    for ([_][]const u8{ root_hash, control_hash, blob_hash }) |h| {
        var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", h, "--raw" });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 0);
        try std.testing.expectEqualStrings("", res.stderr);
        const round = try sha3HexAlloc(gpa, res.stdout);
        defer gpa.free(round);
        try std.testing.expectEqualStrings(h, round); // hashing the emitted bytes reproduces HASH
    }
    var blob = try runZit(gpa, io, tmp.dir, &.{ "artifact", blob_hash, "--raw" });
    defer freeResult(gpa, &blob);
    try expectExit(blob.term, 0);
    try std.testing.expectEqualStrings("v1\n", blob.stdout); // verbatim, no added framing
}

test "cli artifact B-artifact-5: a Z-mismatched structural artifact reports the mismatch, exit 0 (window, not gate)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // Build a structural manifest (C ⇒ §5.3 MANIFEST fallback) and seal it with
    // a DELIBERATELY WRONG §6.2 Z digest, then inject it under its real §7.2
    // name so `blob` accepts it. `parse` (gate 4) would reject it — the derive
    // therefore skips it as a blob — but the summary's `parseWindow` assembles
    // it and REPORTS the mismatch.
    const body = "C zmismatch\nD 2026-01-01T00:00:00\n";
    var zbuf: [32]u8 = undefined;
    const correct = artifact.selfChecksum(body, &zbuf);
    var full: std.ArrayList(u8) = .empty;
    defer full.deinit(gpa);
    try full.appendSlice(gpa, body);
    try full.appendSlice(gpa, "Z ");
    var bad: [32]u8 = undefined;
    @memcpy(&bad, correct);
    bad[0] = if (correct[0] == 'a') 'b' else 'a'; // corrupt one hex digit ⇒ mismatch
    try full.appendSlice(gpa, &bad);
    try full.append(gpa, '\n');

    var raw_digest: [32]u8 = undefined;
    std.crypto.hash.sha3.Sha3_256.hash(full.items, &raw_digest, .{});
    try injectFrame(gpa, io, tmp.dir, raw_digest, full.items);
    const name = try sha3HexAlloc(gpa, full.items);
    defer gpa.free(name);

    var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", name });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0); // mismatch is reported, not enforced
    try std.testing.expectEqualStrings("", res.stderr);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "type: manifest\n") != null);
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "\nZ: checksum mismatch\n") != null);
}

test "cli artifact B-artifact-6: an uppercase abbreviated prefix resolves; the header carries the full lowercase hash" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try writeFile(io, tmp.dir, "only.txt", "unique blob content\n");
    try addManaged(gpa, io, tmp.dir, &.{"only.txt"});
    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);

    const blob_hash = try sha3HexAlloc(gpa, "unique blob content\n");
    defer gpa.free(blob_hash);
    // A 12-char UPPERCASE prefix — case-insensitive resolution (§3.6).
    var upper: [12]u8 = undefined;
    for (blob_hash[0..12], 0..) |c, i| upper[i] = std.ascii.toUpper(c);

    var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", &upper });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    var lines = std.mem.splitScalar(u8, res.stdout, '\n');
    try std.testing.expectEqualStrings(blob_hash, lines.first()); // full LOWERCASE hash, however addressed
    try std.testing.expect(std.mem.indexOf(u8, res.stdout, "type: file\n") != null);
}

test "cli artifact B-artifact-7: an ambiguous prefix is refused with exit 1, diagnostic on stderr, empty stdout" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // Two injected artifacts whose names both begin "abcd" (§8.3 item 8 makes a
    // multi-match a refusal, never a silent pick). The prefix names both.
    const d1 = [_]u8{ 0xab, 0xcd, 0x00 } ++ @as([29]u8, @splat(0));
    const d2 = [_]u8{ 0xab, 0xcd, 0x11 } ++ @as([29]u8, @splat(0));
    try injectFrame(gpa, io, tmp.dir, d1, "one");
    try injectFrame(gpa, io, tmp.dir, d2, "two");

    var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", "abcd" });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 1);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expect(std.mem.indexOf(u8, res.stderr, "ambiguous") != null);
}

test "cli artifact B-artifact-8: an unknown hash and a syntactically invalid one are one not-found family (exit 1, empty stdout)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try writeFile(io, tmp.dir, "a.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});
    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);

    // A well-formed but unknown hex hash, a non-hex token, a too-short token,
    // and a too-long token all refuse identically — no distinct error surface.
    for ([_][]const u8{ "deadbeefdeadbeef", "zznothex", "abc", repeat("a", 65) }) |bad| {
        var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", bad });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 1);
        try std.testing.expectEqualStrings("", res.stdout);
        try std.testing.expect(std.mem.indexOf(u8, res.stderr, "no artifact matches") != null);
    }
}

test "cli artifact B-artifact-9: no invocation mutates .zit, .zit-checkout, or the working tree" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try writeFile(io, tmp.dir, "a.txt", "content\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});
    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);
    const ck = try gpa.dupe(u8, try checkinHash(commit.stdout));
    defer gpa.free(ck);
    const blob_hash = try sha3HexAlloc(gpa, "content\n");
    defer gpa.free(blob_hash);

    const zit_before = try tmp.dir.readFileAlloc(io, ".zit", gpa, .limited(1 << 20));
    defer gpa.free(zit_before);
    const ck_before = try readFile(gpa, io, tmp.dir, ".zit-checkout");
    defer gpa.free(ck_before);
    const tree_before = try readFile(gpa, io, tmp.dir, "a.txt");
    defer gpa.free(tree_before);

    // A summary, a raw dump, and two refusals — none may touch stored state.
    inline for (.{
        &[_][]const u8{ "artifact", ck },
        &[_][]const u8{ "artifact", ck, "--raw" },
        &[_][]const u8{ "artifact", blob_hash },
        &[_][]const u8{ "artifact", "deadbeef" },
    }) |tail| {
        var res = try runZit(gpa, io, tmp.dir, tail);
        freeResult(gpa, &res);
    }

    const zit_after = try tmp.dir.readFileAlloc(io, ".zit", gpa, .limited(1 << 20));
    defer gpa.free(zit_after);
    const ck_after = try readFile(gpa, io, tmp.dir, ".zit-checkout");
    defer gpa.free(ck_after);
    const tree_after = try readFile(gpa, io, tmp.dir, "a.txt");
    defer gpa.free(tree_after);
    try std.testing.expectEqualSlices(u8, zit_before, zit_after);
    try std.testing.expectEqualSlices(u8, ck_before, ck_after);
    try std.testing.expectEqualSlices(u8, tree_before, tree_after);
}

test "cli artifact B-artifact-10: -h/--help and 'help artifact' print the verbatim help on stdout, exit 0" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    for ([_][]const u8{ "--help", "-h" }) |flag| {
        var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", flag });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 0);
        try std.testing.expectEqualStrings(artifact_help_expected, res.stdout);
        try std.testing.expectEqualStrings("", res.stderr);
    }
    var routed = try runZit(gpa, io, tmp.dir, &.{ "help", "artifact" });
    defer freeResult(gpa, &routed);
    try expectExit(routed.term, 0);
    try std.testing.expectEqualStrings(artifact_help_expected, routed.stdout);
}

test "cli artifact B-artifact-11: missing HASH, an unknown option, and a second positional each exit 2 to stderr" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const cases = [_]struct { tail: []const []const u8, needle: []const u8 }{
        .{ .tail = &.{"artifact"}, .needle = "zit artifact: no hash given\n" },
        .{ .tail = &.{ "artifact", "--bogus" }, .needle = "zit artifact: unknown option '--bogus'\n" },
        .{ .tail = &.{ "artifact", "abcd", "efgh" }, .needle = "zit artifact: unexpected argument 'efgh'\n" },
    };
    for (cases) |c| {
        var res = try runZit(gpa, io, tmp.dir, c.tail);
        defer freeResult(gpa, &res);
        try expectExit(res.term, 2);
        try std.testing.expectEqualStrings("", res.stdout);
        try std.testing.expect(std.mem.indexOf(u8, res.stderr, c.needle) != null);
        try std.testing.expect(std.mem.indexOf(u8, res.stderr, "try 'zit artifact --help'\n") != null);
    }
}

test "cli artifact B-artifact-12/nongoal: outside a repo exits 1 with not-a-repo; a symbolic name is a not-found refusal" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;

    // (a) Outside any repository: the standard not-a-repo diagnostic, exit 1,
    // empty stdout (openRepo runs before hash resolution).
    {
        var tmp = std.testing.tmpDir(.{});
        defer tmp.cleanup();
        var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", "deadbeef" });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 1);
        try std.testing.expectEqualStrings("", res.stdout);
        try std.testing.expect(std.mem.indexOf(u8, res.stderr, "no zit checkout here") != null);
    }

    // (b) A symbolic name (a branch) is NOT an artifact address — `zit info`
    // owns names — so `zit artifact trunk` is the not-found refusal, exit 1.
    {
        var tmp = std.testing.tmpDir(.{});
        defer tmp.cleanup();
        try initRepo(gpa, io, tmp.dir);
        try writeFile(io, tmp.dir, "a.txt", "root\n");
        try addManaged(gpa, io, tmp.dir, &.{"a.txt"});
        var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
        defer freeResult(gpa, &commit);
        try expectExit(commit.term, 0);

        var res = try runZit(gpa, io, tmp.dir, &.{ "artifact", "trunk" });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 1);
        try std.testing.expectEqualStrings("", res.stdout);
        try std.testing.expect(std.mem.indexOf(u8, res.stderr, "no artifact matches 'trunk'") != null);
    }
}

test "cli artifact B-artifact-14: help lists artifact and did-you-mean suggests it; there is no whatis sibling verb" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // The top-level command list names the verb (discoverability).
    var help = try runZit(gpa, io, tmp.dir, &.{"help"});
    defer freeResult(gpa, &help);
    try expectExit(help.term, 0);
    try std.testing.expect(std.mem.indexOf(u8, help.stdout, "artifact") != null);

    // `whatis` is not a zit verb — the summary IS the whatis mode (single
    // spelling). It resolves to unknown-command, exit 2.
    var whatis = try runZit(gpa, io, tmp.dir, &.{ "whatis", "deadbeef" });
    defer freeResult(gpa, &whatis);
    try expectExit(whatis.term, 2);
    try std.testing.expect(std.mem.indexOf(u8, whatis.stderr, "unknown command 'whatis'") != null);
}

/// Lines of `text` that begin with `prefix`.
fn countLinesStarting(text: []const u8, prefix: []const u8) usize {
    var n: usize = 0;
    var it = std.mem.splitScalar(u8, text, '\n');
    while (it.next()) |line| {
        if (std.mem.startsWith(u8, line, prefix)) n += 1;
    }
    return n;
}

test "cli artifact: renders a tree check-in's S cards, one per card, agreeing with --raw" {
    // `renderCardLines` had a lane per card letter and no S lane, so a tree
    // check-in — whose entire file set is S cards and no F cards — printed as
    // a manifest with no files at all while `ls` on the same hash listed
    // thousands. Raw output always showed the cards; rendered output is
    // checked against it here so the two can never disagree again.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    const tip = try initTreeRepo(gpa, io, tmp.dir);
    defer gpa.free(tip);

    var raw = try runZit(gpa, io, tmp.dir, &.{ "artifact", "--raw", tip });
    defer freeResult(gpa, &raw);
    try expectExitDiag(raw.term, 0, raw);
    var shown = try runZit(gpa, io, tmp.dir, &.{ "artifact", tip });
    defer freeResult(gpa, &shown);
    try expectExitDiag(shown.term, 0, shown);

    const raw_s = countLinesStarting(raw.stdout, "S ");
    try std.testing.expect(raw_s >= 1); // the fixture really is a tree
    try std.testing.expectEqual(@as(usize, 0), countLinesStarting(raw.stdout, "F "));
    try std.testing.expectEqual(raw_s, countLinesStarting(shown.stdout, "S "));
    try std.testing.expectEqual(@as(usize, 0), countLinesStarting(shown.stdout, "F "));
    // Every rendered S line is a raw S line verbatim: filename then hash.
    var it = std.mem.splitScalar(u8, shown.stdout, '\n');
    while (it.next()) |line| {
        if (!std.mem.startsWith(u8, line, "S ")) continue;
        try std.testing.expect(std.mem.indexOf(u8, raw.stdout, line) != null);
    }
}