const std = @import("std"); const Allocator = std.mem.Allocator; const Abort = @import("abort.zig").Abort; pub const read = @import("tools/read.zig"); pub const write = @import("tools/write.zig"); pub const edit = @import("tools/edit.zig"); pub const bash = @import("tools/bash.zig"); pub const schema = @import("tools/schema.zig"); pub const content = @import("content.zig"); /// The most lines and bytes of text that one call returns. pub const max_output_lines = 2000; pub const max_output_bytes = 50 * 1024; /// The largest file that edit changes. pub const max_file_bytes = 64 * 1024 * 1024; pub const Context = struct { io: std.Io, /// The environment of child processes. environ: std.process.Environ, abort: *Abort, /// Receives the detail of a failed call; the shared layer prefers it over the error name. detail: ?*?[]const u8 = null, }; /// One call's outcome. `text` is what the model sees. `collapsed` and /// `expanded` are what a UI shows, and never go to the model. pub const Result = struct { text: []const u8, is_error: bool = false, collapsed: content.Content = &.{}, expanded: content.Content = &.{}, }; /// How a UI shows a result: a short form, and the form a user opens. pub const Rendered = struct { collapsed: content.Content = &.{}, expanded: content.Content = &.{}, }; pub const Definition = struct { name: []const u8, description: []const u8, parameters_json: []const u8, }; /// The tool modules. Order sets the schema order. pub const modules = .{ read, write, edit, bash }; /// Runs the tool `name`. Every allocation goes to `arena`, and the result /// points into it, so the caller frees the arena after it uses the result. pub fn execute(ctx: Context, arena: Allocator, name: []const u8, args_json: []const u8) Result { inline for (modules) |module| { if (std.mem.eql(u8, module.definition.name, name)) { return executeTool(module, ctx, arena, args_json); } } return fail(arena, "unknown tool: {s}", .{name}); } fn executeTool(comptime module: type, ctx: Context, arena: Allocator, args_json: []const u8) Result { const tool = module.definition; var detail: ?[]const u8 = null; var inner = ctx; inner.detail = &detail; const args = std.json.parseFromSliceLeaky(tool.Args, arena, args_json, .{ .ignore_unknown_fields = true }) catch |err| { const value = std.json.parseFromSliceLeaky(std.json.Value, arena, args_json, .{}) catch |syntax| { return fail(arena, "invalid arguments for {s}: {s}", .{ tool.name, @errorName(syntax) }); }; const text = (argumentError(tool.Args, arena, value, "") catch null) orelse @errorName(err); return fail(arena, "invalid arguments for {s}: {s}", .{ tool.name, text }); }; const output = tool.execute(inner, arena, args) catch |err| { if (detail) |text| { return fail(arena, "{s}", .{text}); } return fail(arena, "{s}: {s}", .{ tool.name, @errorName(err) }); }; // Content only reaches the UI, so a renderer that runs out of memory shows nothing. const shown: Rendered = module.renderResult(arena, output) catch .{}; return .{ .text = output.text, .collapsed = shown.collapsed, .expanded = shown.expanded }; } /// Names the first argument at `path` that does not match its schema type `T`. fn argumentError(comptime T: type, arena: Allocator, value: std.json.Value, path: []const u8) Allocator.Error!?[]const u8 { if (@typeInfo(T) == .optional) { return if (value == .null) null else argumentError(@typeInfo(T).optional.child, arena, value, path); } if (@hasDecl(T, "Element")) { if (value == .array) { for (value.array.items, 0..) |item, index| { if (try argumentError(T.Element, arena, item, try std.fmt.allocPrint(arena, "{s}[{d}]", .{ path, index }))) |text| { return text; } } } } else if (!@hasDecl(T, "expected")) { if (value != .object) { return try std.fmt.allocPrint(arena, "{s} must be an object", .{if (path.len == 0) "the arguments" else path}); } const info = @typeInfo(T).@"struct"; inline for (info.field_names, info.field_types, info.field_attrs) |name, FieldType, attrs| { const field_path = if (path.len == 0) name else try std.fmt.allocPrint(arena, "{s}.{s}", .{ path, name }); if (value.object.get(name)) |field| { if (try argumentError(FieldType, arena, field, field_path)) |text| { return text; } } else if (attrs.defaultValue(FieldType) == null) { return try std.fmt.allocPrint(arena, "missing {s}", .{field_path}); } } return null; } // The schema types parse only from JSON text. const json = try std.json.Stringify.valueAlloc(arena, value, .{}); _ = std.json.parseFromSliceLeaky(T, arena, json, .{ .ignore_unknown_fields = true }) catch return try std.fmt.allocPrint(arena, "{s} must be {s}", .{ path, T.expected }); return null; } /// Records `path` as the detail of a failed call and returns `err`. pub fn pathError(ctx: Context, arena: Allocator, path: []const u8, err: anytype) @TypeOf(err) { if (ctx.detail) |slot| { slot.* = std.fmt.allocPrint(arena, "{s}: {s}", .{ path, @errorName(err) }) catch null; } return err; } pub fn fail(arena: Allocator, comptime fmt: []const u8, args: anytype) Result { const text = std.fmt.allocPrint(arena, fmt, args) catch "out of memory"; return plainResult(arena, text, true); } /// A result that shows its first line while collapsed and the whole text once /// expanded. Failed calls use it, so a tool's renderer cannot hide an error. pub fn plainResult(arena: Allocator, text: []const u8, is_error: bool) Result { const line = std.mem.sliceTo(text, '\n'); return .{ .text = text, .is_error = is_error, .collapsed = if (line.len == 0) &.{} else content.text(arena, line) catch &.{}, .expanded = content.text(arena, text) catch &.{}, }; } /// Replaces a file in one step, so a failed write leaves the old file whole. /// A symlink to the file stays a symlink, and an existing file keeps its permissions. pub fn replaceFile(io: std.Io, arena: Allocator, dir: std.Io.Dir, sub_path: []const u8, data: []const u8) !void { var target = sub_path; var permissions: ?std.Io.File.Permissions = null; if (dir.statFile(io, sub_path, .{ .follow_symlinks = false })) |entry| { if (entry.kind == .sym_link) { // A dangling link, or a system that cannot resolve it, is written through in place. target = dir.realPathFileAlloc(io, sub_path, arena) catch |err| switch (err) { error.FileNotFound => return dir.writeFile(io, .{ .sub_path = sub_path, .data = data }), else => return err, }; permissions = (try dir.statFile(io, target, .{})).permissions; } else { permissions = entry.permissions; } } else |err| switch (err) { error.FileNotFound => {}, else => return err, } var file = try dir.createFileAtomic(io, target, .{ .replace = true }); defer file.deinit(io); try file.file.writeStreamingAll(io, data); // Set after creation because the creation mode is masked by the umask. if (permissions) |value| { try file.file.setPermissions(io, value); } try file.file.sync(io); try file.replace(io); } /// How a UI shows a call: the tool's own renderer, or the name and the raw /// arguments when the tool is unknown or the arguments do not parse. pub fn renderCall(arena: Allocator, name: []const u8, args_json: []const u8) Allocator.Error!content.Content { inline for (modules) |module| { if (std.mem.eql(u8, module.definition.name, name)) { if (std.json.parseFromSliceLeaky(module.definition.Args, arena, args_json, .{ .ignore_unknown_fields = true })) |args| { return module.renderCall(arena, args); } else |_| {} } } return content.callLine(arena, name, args_json); } /// Temporary directory used by the tool tests. Paths handed to the tools are /// absolute, so the process working directory does not have to change. pub const TestDir = struct { tmp: std.testing.TmpDir, arena_state: std.heap.ArenaAllocator, root: []const u8, abort: Abort = .{}, const io = std.testing.io; pub fn init() !TestDir { var tmp = std.testing.tmpDir(.{}); errdefer tmp.cleanup(); var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator); errdefer arena_state.deinit(); var buffer: [std.fs.max_path_bytes]u8 = undefined; const length = try tmp.dir.realPath(io, &buffer); // The arena is filled after it is in place in this struct. var dir: TestDir = .{ .tmp = tmp, .arena_state = arena_state, .root = &.{} }; dir.root = try dir.arena_state.allocator().dupe(u8, buffer[0..length]); return dir; } pub fn deinit(self: *TestDir) void { self.tmp.cleanup(); self.arena_state.deinit(); } pub fn arena(self: *TestDir) std.mem.Allocator { return self.arena_state.allocator(); } pub fn path(self: *TestDir, sub: []const u8) ![]const u8 { return std.fs.path.join(self.arena(), &.{ self.root, sub }); } /// Path relative to the process working directory. pub fn relative(self: *TestDir, sub: []const u8) ![]const u8 { return std.fs.path.join(self.arena(), &.{ ".zig-cache", "tmp", &self.tmp.sub_path, sub }); } pub fn write(self: *TestDir, sub: []const u8, data: []const u8) ![]const u8 { if (std.fs.path.dirname(sub)) |parent| { try self.tmp.dir.createDirPath(io, parent); } try self.tmp.dir.writeFile(io, .{ .sub_path = sub, .data = data }); return self.path(sub); } pub fn read(self: *TestDir, sub: []const u8) ![]u8 { return self.tmp.dir.readFileAlloc(io, sub, self.arena(), .limited(1 << 22)); } pub fn call(self: *TestDir, name: []const u8, args: anytype) Result { const json = std.json.Stringify.valueAlloc(self.arena(), args, .{}) catch unreachable; return self.callJson(name, json); } pub fn callJson(self: *TestDir, name: []const u8, args_json: []const u8) Result { const ctx: Context = .{ .io = io, .environ = std.testing.environ, .abort = &self.abort }; return execute(ctx, self.arena(), name, args_json); } }; const testing = std.testing; pub const definitions = blk: { var list: [modules.len]Definition = undefined; for (modules, 0..) |module, index| { list[index] = .{ .name = module.definition.name, .description = module.definition.description, .parameters_json = schema.schemaJson(module.definition.Args), }; } break :blk list; }; test "the read schema matches its expected JSON" { try testing.expectEqualStrings( "{\"type\":\"object\",\"properties\":{\"files\":{\"type\":\"array\",\"description\":\"Files to read.\",\"items\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"description\":\"File path, relative to the working directory or absolute.\"},\"start\":{\"type\":\"integer\",\"description\":\"First line, 1-based and inclusive.\",\"minimum\":1},\"end\":{\"type\":\"integer\",\"description\":\"Last line, 1-based and inclusive.\",\"minimum\":1}},\"required\":[\"path\"]},\"minItems\":1}},\"required\":[\"files\"]}", definitions[0].parameters_json, ); } test "each schema lists the tool's arguments and requires those without a default" { var arena_state = std.heap.ArenaAllocator.init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator(); inline for (modules, definitions) |module, definition| { const root = try std.json.parseFromSliceLeaky(std.json.Value, arena, definition.parameters_json, .{}); try testing.expectEqualStrings("object", root.object.get("type").?.string); const properties = root.object.get("properties").?.object; var required: std.ArrayList([]const u8) = .empty; const info = @typeInfo(module.definition.Args).@"struct"; try testing.expectEqual(info.field_names.len, properties.count()); inline for (info.field_names, info.field_types, info.field_attrs, properties.keys(), properties.values()) |name, FieldType, attrs, key, property| { try testing.expectEqualStrings(name, key); try testing.expect(property.object.get("type") != null); try testing.expect(property.object.get("description").?.string.len > 0); if (attrs.defaultValue(FieldType) == null) { try required.append(arena, name); } } const listed = root.object.get("required").?.array.items; try testing.expectEqual(required.items.len, listed.len); for (required.items, listed) |name, value| try testing.expectEqualStrings(name, value.string); } } test "the definitions name the tools" { try testing.expectEqual(@as(usize, 4), definitions.len); const names = [_][]const u8{ "read", "write", "edit", "bash" }; for (definitions, names) |definition, name| { try testing.expectEqualStrings(name, definition.name); try testing.expect(definition.description.len > 0); } } test "bad calls are error results" { var dir = try TestDir.init(); defer dir.deinit(); const unknown = dir.callJson("nope", "{}"); try testing.expect(unknown.is_error); try testing.expect(std.mem.indexOf(u8, unknown.text, "unknown tool") != null); try testing.expect(dir.callJson("read", "{").is_error); const calls = [_][3][]const u8{ .{ "read", "[]", "invalid arguments for read: the arguments must be an object" }, .{ "read", "{}", "invalid arguments for read: missing files" }, .{ "read", "{\"files\":\"x\"}", "invalid arguments for read: files must be an array of at least 1 item(s)" }, .{ "read", "{\"files\":[]}", "invalid arguments for read: files must be an array of at least 1 item(s)" }, .{ "read", "{\"files\":[{\"path\":\"a\"},{\"path\":\"b\",\"start\":0}]}", "invalid arguments for read: files[1].start must be an integer of at least 1" }, .{ "write", "{\"path\":\"a.txt\"}", "invalid arguments for write: missing content" }, .{ "write", "{\"path\":5,\"content\":\"x\"}", "invalid arguments for write: path must be a string" }, .{ "edit", "{\"path\":\"a\",\"edits\":[{\"old\":\"\",\"new\":\"x\"}]}", "invalid arguments for edit: edits[0].old must be a string of at least 1 character(s)" }, .{ "bash", "{\"command\":\"true\",\"timeout\":1801,\"cwd\":\".\"}", "invalid arguments for bash: timeout must be an integer from 1 to 1800" }, }; for (calls) |call| { const result = dir.callJson(call[0], call[1]); try testing.expect(result.is_error); try testing.expectEqualStrings(call[2], result.text); } } test "read, write and edit accept paths relative to the working directory" { var dir = try TestDir.init(); defer dir.deinit(); const relative = try dir.relative("rel.txt"); const wrote = dir.call("write", .{ .path = relative, .content = "abc" }); try testing.expect(!wrote.is_error); const read_back = dir.call("read", .{ .files = &.{.{ .path = relative }} }); try testing.expect(!read_back.is_error); try testing.expect(std.mem.indexOf(u8, read_back.text, "1| abc") != null); const edits = &.{.{ .old = "a", .new = "A" }}; const edited = dir.call("edit", .{ .path = relative, .edits = edits }); try testing.expect(!edited.is_error); try testing.expectEqualStrings("Abc", try dir.read("rel.txt")); } test "write and edit replace a file in one step and keep its permissions and a symlink to it" { var dir = try TestDir.init(); defer dir.deinit(); const io = testing.io; _ = try dir.write("f.txt", "old"); try dir.tmp.dir.setFilePermissions(io, "f.txt", .fromMode(0o751), .{}); try dir.tmp.dir.symLink(io, "f.txt", "link.txt", .{}); const link = try dir.path("link.txt"); const edits = &.{.{ .old = "old", .new = "mid" }}; const calls = [_][2][]const u8{ .{ "edit", "mid" }, .{ "write", "new" } }; for (calls) |entry| { const before = try dir.tmp.dir.openFile(io, "f.txt", .{}); defer before.close(io); var old: [8]u8 = undefined; const old_len = try before.readPositional(io, &.{&old}, 0); const result = if (std.mem.eql(u8, entry[0], "edit")) dir.call("edit", .{ .path = link, .edits = edits }) else dir.call("write", .{ .path = link, .content = "new" }); try testing.expect(!result.is_error); try testing.expectEqualStrings(entry[1], try dir.read("f.txt")); // A file opened before the call keeps the old contents only if the call replaced the file. var kept: [8]u8 = undefined; try testing.expectEqualStrings(old[0..old_len], kept[0..try before.readPositional(io, &.{&kept}, 0)]); var target: [64]u8 = undefined; try testing.expectEqualStrings("f.txt", target[0..try dir.tmp.dir.readLink(io, "link.txt", &target)]); try testing.expectEqual(0o751, (try dir.tmp.dir.statFile(io, "f.txt", .{})).permissions.toMode() & 0o777); } try dir.tmp.dir.symLink(io, "missing.txt", "dangling.txt", .{}); try testing.expect(!dir.call("write", .{ .path = try dir.path("dangling.txt"), .content = "x" }).is_error); try testing.expectEqualStrings("x", try dir.read("missing.txt")); } test "a call with no renderer of its own or bad arguments shows its name and the raw arguments" { var arena_state = std.heap.ArenaAllocator.init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator(); for ([_][2][]const u8{ .{ "grep", "{}" }, .{ "bash", "{bad" } }) |call| { const shown = try renderCall(arena, call[0], call[1]); try testing.expectEqualStrings(call[0], shown[0].text); try testing.expect(shown[0].style.bold); try testing.expectEqualStrings(try std.fmt.allocPrint(arena, "{s} {s}", .{ call[0], call[1] }), try content.plain(arena, shown)); } } test "a failed call shows its first line collapsed and the whole error expanded" { var arena_state = std.heap.ArenaAllocator.init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator(); const result = fail(arena, "{s}", .{"first\nsecond"}); try testing.expect(result.is_error); try testing.expectEqualStrings("first", try content.plain(arena, result.collapsed)); try testing.expectEqualStrings("first\nsecond", try content.plain(arena, result.expanded)); } test "each tool's call line names the tool and sums up its arguments" { var arena_state = std.heap.ArenaAllocator.init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator(); const calls = [_][3][]const u8{ .{ "read", "{\"files\":[{\"path\":\"a.txt\",\"start\":2,\"end\":3},{\"path\":\"b.txt\"}]}", "read a.txt:2-3, b.txt" }, .{ "write", "{\"path\":\"a.txt\",\"content\":\"SECRET\"}", "write a.txt" }, .{ "edit", "{\"path\":\"a.txt\",\"edits\":[{\"old\":\"a\",\"new\":\"b\"}]}", "edit a.txt (1 edit(s))" }, .{ "bash", "{\"command\":\"echo hi\",\"timeout\":10,\"cwd\":\".\"}", "bash echo hi (.)" }, }; for (calls) |call| { const shown = try renderCall(arena, call[0], call[1]); try testing.expectEqualStrings(call[2], try content.plain(arena, shown)); try testing.expect(shown[0].style.bold); } } test { @import("std").testing.refAllDecls(@This()); }