642d5a256791
build_tools.rs
//! A builder's own hands, for coding agents that don't bring their own (an API-key model driven
//! by our agent loop): list, read, write and edit files in the project it's building, and run its
//! build commands. They work in the session's workspace (the one a rebuild run attached), paths
//! relative to its folder. Writes and commands go through the same approval policy as Claude
//! Code's (`interaction_tools::approve`): edits inside app/ and the usual build commands go ahead,
//! dev servers are refused, anything else asks the person (or goes ahead in Auto mode, except
//! what's never done unasked). Ids follow docs/tool-ids.md.
use super::interaction_tools::{approve, inbox, inside, really_inside, resolve, workspace_of};
use crate::tool::{Ctx, Effects, Requires, ToolOutput, ToolSpec, Toolset, parse_params, schema_of};
use crate::workspace::Workspace;
use craft_anything_evidence::{ErrorCode, ToolError};
use craft_anything_platform::process::Process;
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::{Value, json};
use std::path::{Path, PathBuf};
use std::time::Duration;
/// Largest file one read returns (the rest is paged with offset/limit).
const MAX_READ: usize = 256 * 1024;
/// Largest project file a read holds in memory at once (16 MiB); larger files are refused.
const MAX_READ_FILE: u64 = 16 * 1024 * 1024;
/// Largest file a write may create.
const MAX_WRITE: usize = 8 * 1024 * 1024;
/// Most entries one listing returns.
const MAX_ENTRIES: usize = 2_000;
/// Output kept from a command (its tail, where errors are).
const OUTPUT_TAIL: usize = 24 * 1024;
pub fn specs() -> Vec<ToolSpec> {
let spec = |id, title, summary, beginner, effects, schema, run| ToolSpec {
id,
title,
summary,
beginner,
toolset: Toolset::Build,
effects,
requires: Requires::Nothing,
input_schema: schema,
run,
};
vec![
spec(
"build_files_list",
"List project files",
"List files and folders in the app: app/ usually, or the project folder when the app is edited in place. A few levels deep; paths are relative to the project folder; build output and dependencies (node_modules, target, vendor, dist…) are skipped.",
"Shows the files being built.",
Effects::READ_ONLY,
schema_of::<ListParams>,
build_files_list,
),
spec(
"build_file_read",
"Read a project file",
"Read a text file in the project (app/, capture/, reference/…), paged by lines with offset/limit for big files.",
"Reads one of the project's files.",
Effects::READ_ONLY,
schema_of::<ReadParams>,
build_file_read,
),
spec(
"build_file_write",
"Write a project file",
"Create or replace a text file. Inside app/ this goes ahead; anywhere else asks the person.",
"Writes one of the project's files.",
Effects::WRITES_FILESYSTEM,
schema_of::<WriteParams>,
build_file_write,
),
spec(
"build_file_edit",
"Edit a project file",
"Replace exact text in a file: old_text must appear exactly once (or set replace_all). Inside app/ this goes ahead; anywhere else asks the person.",
"Changes part of one of the project's files.",
Effects::WRITES_FILESYSTEM,
schema_of::<EditParams>,
build_file_edit,
),
spec(
"build_checklist",
"Update the checklist",
"Show the person your plan as a short checklist and keep it current: todos with content (a plain step), activeForm (\"Drawing the map\") and status (pending, in_progress or completed). Call it again whenever a step changes; the app pins it above the prompt box.",
"Shows the builder's plan as a checklist.",
Effects::CHANGES_UI_STATE,
schema_of::<ChecklistParams>,
build_checklist,
),
spec(
"build_command_run",
"Run a build command",
"Run a command in app/ (npm install, npm run build, cargo build, the game engine's build…) and return its exit code and the end of its output. Common build commands go ahead; dev servers and watchers are refused (they never exit); anything else asks the person. Default limit 10 minutes, at most 2 hours.",
"Runs a build step.",
Effects::LAUNCHES_PROCESS.union(Effects::WRITES_FILESYSTEM).union(Effects::EXECUTES_FOREIGN_CODE),
schema_of::<CommandParams>,
build_command_run,
),
]
}
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ListParams {
/// A folder relative to the project (default: the app folder; for a project edited in
/// place, the project folder itself).
#[serde(default)]
pub path: Option<String>,
/// How many levels down (default 4, at most 8).
#[serde(default)]
pub depth: Option<usize>,
}
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ReadParams {
/// A file relative to the project, e.g. `app/src/main.rs` or `capture/README.md`.
pub path: String,
/// First line to return (0-based).
#[serde(default)]
pub offset: Option<usize>,
/// How many lines (default: up to 256 KB).
#[serde(default)]
pub limit: Option<usize>,
}
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct WriteParams {
/// A file relative to the project, e.g. `app/src/main.rs`.
pub path: String,
/// The whole new contents.
pub content: String,
}
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct EditParams {
/// A file relative to the project.
pub path: String,
/// The exact text to replace.
pub old_text: String,
/// What replaces it.
pub new_text: String,
/// Replace every occurrence instead of exactly one.
#[serde(default)]
pub replace_all: bool,
}
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ChecklistParams {
/// The steps, in order.
pub todos: Vec<Todo>,
}
#[derive(Debug, Deserialize, JsonSchema)]
pub struct Todo {
/// The step, in plain words.
pub content: String,
/// What it says while doing it ("Drawing the map").
#[serde(default, rename = "activeForm")]
pub active_form: Option<String>,
/// `pending`, `in_progress` or `completed`.
pub status: String,
}
/// The checklist is shown from the call itself (the run folds it into the project's feed); this
/// only checks it and says how far along it is.
fn build_checklist(_ctx: &mut Ctx<'_>, params: Value) -> Result<ToolOutput, ToolError> {
let p: ChecklistParams = parse_params(params)?;
if p.todos.is_empty() || p.todos.len() > 30 {
return Err(ToolError::invalid("Give 1 to 30 steps."));
}
if let Some(bad) = p.todos.iter().find(|t| !["pending", "in_progress", "completed"].contains(&t.status.as_str())) {
return Err(ToolError::invalid(format!("status {:?} must be pending, in_progress or completed", bad.status)));
}
let done = p.todos.iter().filter(|t| t.status == "completed").count();
Ok(ToolOutput::Value(json!({"steps": p.todos.len(), "done": done})))
}
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CommandParams {
/// The command, run in app/ (`&&` joins steps).
pub command: String,
/// Time limit in seconds (default 600, at most 7200).
#[serde(default)]
pub timeout_secs: Option<u64>,
}
/// The workspace this session is building, from the inbox a rebuild run attached.
fn workspace(ctx: &Ctx<'_>) -> Result<Workspace, ToolError> {
inbox(ctx).as_ref().and_then(workspace_of).ok_or_else(|| {
ToolError::new(ErrorCode::FeatureMissing, "These tools work only while a project is being built.")
.with_remediation("Start a build (rebuild_start or the app), then use them from the builder.")
})
}
/// `rel` inside the project folder, or an error (no escaping with `..`, an absolute path or a
/// link that leads out of the project).
/// Models often write the project's folders from the root (`/app/src/main.rs`): a path like that
/// whose first folder the project has is read inside the project, where it was meant (#24).
fn in_project(ws: &Workspace, rel: &str) -> Result<PathBuf, ToolError> {
let from_root = rel.trim_start_matches(['/', '\\']);
let names_a_folder = from_root != rel
&& from_root.split(['/', '\\']).next().is_some_and(|first| !first.is_empty() && (ws.root.join(first).is_dir() || ws.root.join(first) == ws.app_dir()));
[Some(rel), names_a_folder.then_some(from_root)].into_iter().flatten().find_map(|r| resolve(&ws.root, r).filter(|p| really_inside(&ws.root, p))).ok_or_else(
|| ToolError::invalid(format!("{rel} is outside the project.")).with_remediation("Use a path relative to the project folder, like app/src/main.rs."),
)
}
/// Resolve `rel` inside `ws`, falling back to `ws.app_dir()` when `rel` is missing at `ws.root`
/// and doesn't already start with `app/`. Commands via `build_command_run` execute inside `app/`,
/// so compiler diagnostics report paths relative to `app/` rather than the workspace root.
fn in_project_or_app(ws: &Workspace, rel: &str, for_write: bool) -> Result<PathBuf, ToolError> {
let path = in_project(ws, rel)?;
if ws.manifest.app_in_root || path.exists() || rel.starts_with(['/', '\\']) {
return Ok(path);
}
let starts_with_app = inside(&ws.app_dir(), &path) || rel.split(['/', '\\']).find(|c| !c.is_empty() && *c != ".").is_none_or(|first| first == "app");
if starts_with_app {
return Ok(path);
}
let Some(app_path) = resolve(&ws.app_dir(), rel).filter(|p| really_inside(&ws.app_dir(), p) && really_inside(&ws.root, p)) else {
return Ok(path);
};
if app_path.exists() {
return Ok(app_path);
}
if for_write {
let app_parent_exists = app_path.parent().is_some_and(|parent| parent != ws.app_dir() && parent.is_dir());
let root_parent_exists = path.parent().is_some_and(|parent| parent != ws.root && parent.is_dir());
if app_parent_exists && !root_parent_exists {
return Ok(app_path);
}
}
Ok(path)
}
fn shown(ws: &Workspace, p: &Path) -> String {
let root = resolve(&ws.root, ".").unwrap_or_else(|| ws.root.clone());
let rel = p.strip_prefix(&root).unwrap_or(p);
if rel.as_os_str().is_empty() { ".".to_string() } else { rel.to_string_lossy().replace('\\', "/") }
}
fn refused(why: String) -> ToolError {
ToolError::new(ErrorCode::ConsentRequired, why)
}
fn build_files_list(ctx: &mut Ctx<'_>, params: Value) -> Result<ToolOutput, ToolError> {
let p: ListParams = parse_params(params)?;
let ws = workspace(ctx)?;
let default = if ws.manifest.app_in_root { "." } else { "app" };
let root = in_project_or_app(&ws, p.path.as_deref().unwrap_or(default), false)?;
// Our records are hidden from a listing of the project, but a listing of one of them (the
// builder is told to read capture/ and reference/) shows what is in it.
let listing_own = ws.is_own_record(&root);
let depth = p.depth.unwrap_or(4).min(8);
const SKIP: [&str; 9] = ["node_modules", "target", "vendor", "dist", "build", ".git", "Library", "Temp", "Intermediate"];
let mut entries = Vec::new();
let mut stack = vec![(root.clone(), 0usize)];
let mut truncated = false;
while let Some((dir, d)) = stack.pop() {
let mut items: Vec<_> = std::fs::read_dir(&dir).into_iter().flatten().flatten().collect();
items.sort_by_key(|e| e.file_name());
for e in items {
if entries.len() >= MAX_ENTRIES {
truncated = true;
break;
}
let path = e.path();
// Craft Anything's own records are not the app, even when the app is the project
// folder; the brief names them and the builder must leave them alone.
if !listing_own && ws.is_own_record(&path) {
continue;
}
let name = e.file_name().to_string_lossy().into_owned();
// A link is listed but never followed: it may lead out of the project.
if e.file_type().is_ok_and(|t| t.is_symlink()) {
entries.push(json!({"path": shown(&ws, &path), "link": true}));
} else if path.is_dir() {
entries.push(json!({"path": format!("{}/", shown(&ws, &path))}));
if d + 1 < depth && !SKIP.contains(&name.as_str()) {
stack.push((path, d + 1));
}
} else {
entries.push(json!({"path": shown(&ws, &path), "bytes": e.metadata().map(|m| m.len()).unwrap_or(0)}));
}
}
}
Ok(ToolOutput::Value(json!({"root": shown(&ws, &root), "entries": entries, "truncated": truncated})))
}
/// Read a project file a builder can hold in memory, with a plain error for one over the cap.
fn read_file_for_builder(path: &Path, shown: &str) -> Result<Vec<u8>, ToolError> {
capped_for_builder(path, shown, "read", "Read a smaller file, or use a build command to print the part you need.")
}
/// Read a project file as text for an edit, refusing one over the same cap before it is loaded.
fn read_text_for_edit(path: &Path, shown: &str) -> Result<String, ToolError> {
let bytes = capped_for_builder(path, shown, "edit", "Edit a smaller file, or use a build command to change it.")?;
String::from_utf8(bytes).map_err(|e| ToolError::io(path.display(), std::io::Error::new(std::io::ErrorKind::InvalidData, e)))
}
/// Read a whole project file with the builder's memory cap, so no path loads an oversized file.
fn capped_for_builder(path: &Path, shown: &str, action: &str, remedy: &str) -> Result<Vec<u8>, ToolError> {
craft_anything_platform::fs::read_file_capped(path, MAX_READ_FILE).map_err(|e| {
if e.code == ErrorCode::OverLimit {
ToolError::new(ErrorCode::OverLimit, format!("{shown} is larger than the {} MB a builder can {action} at once.", MAX_READ_FILE / (1024 * 1024)))
.with_remediation(remedy)
} else {
e
}
})
}
fn build_file_read(ctx: &mut Ctx<'_>, params: Value) -> Result<ToolOutput, ToolError> {
let p: ReadParams = parse_params(params)?;
let ws = workspace(ctx)?;
let path = in_project_or_app(&ws, &p.path, false)?;
let bytes = read_file_for_builder(&path, &p.path)?;
if bytes.iter().take(8000).any(|b| *b == 0) {
return Err(ToolError::invalid(format!("{} is a binary file.", p.path)).with_remediation("Read text files; look at pictures with your own viewer."));
}
let text = String::from_utf8_lossy(&bytes);
let lines: Vec<&str> = text.lines().collect();
let start = p.offset.unwrap_or(0).min(lines.len());
let mut out = String::new();
let mut n = 0usize;
let mut cut = false;
for line in lines.iter().skip(start) {
if p.limit.is_some_and(|l| n >= l) || (n > 0 && out.len() + line.len() > MAX_READ) {
break;
}
// A line longer than a page comes cut to one, so reading always moves on (#280).
let part = line.get(..line.floor_char_boundary(MAX_READ)).unwrap_or(line);
cut |= part.len() < line.len();
out.push_str(part);
out.push('\n');
n += 1;
}
let mut v = json!({"path": shown(&ws, &path), "offset": start, "lines": n, "total_lines": lines.len(), "more": start + n < lines.len(), "text": out});
if cut {
v["note"] = json!(format!("Line {} is longer than {} KiB, so only its start is shown.", start + 1, MAX_READ / 1024));
}
Ok(ToolOutput::Value(v))
}
fn write_checked(ctx: &mut Ctx<'_>, path: &Path, content: &str) -> Result<(), ToolError> {
if content.len() > MAX_WRITE {
return Err(ToolError::invalid("That file is too big to write in one go (8 MB at most)."));
}
approve(ctx, "Write", &json!({"file_path": path.display().to_string()}))?.map_err(refused)?;
if let Some(dir) = path.parent() {
std::fs::create_dir_all(dir).map_err(|e| ToolError::io(dir.display(), e))?;
}
crate::project::write_atomic(path, content.as_bytes())
}
fn build_file_write(ctx: &mut Ctx<'_>, params: Value) -> Result<ToolOutput, ToolError> {
let p: WriteParams = parse_params(params)?;
let ws = workspace(ctx)?;
let path = in_project_or_app(&ws, &p.path, true)?;
write_checked(ctx, &path, &p.content)?;
let mut out = json!({"written": shown(&ws, &path), "bytes": p.content.len()});
// A model that leaves out `app/` would otherwise build beside the app, where no check looks.
if !inside(&ws.app_dir(), &path) {
out["note"] = json!("This file is outside app/: the app's own files go in app/ (paths like app/package.json).");
}
Ok(ToolOutput::Value(out))
}
fn build_file_edit(ctx: &mut Ctx<'_>, params: Value) -> Result<ToolOutput, ToolError> {
let p: EditParams = parse_params(params)?;
let ws = workspace(ctx)?;
let path = in_project_or_app(&ws, &p.path, false)?;
let text = read_text_for_edit(&path, &p.path)?;
let count = if p.old_text.is_empty() { 0 } else { text.matches(p.old_text.as_str()).count() };
let new = match (count, p.replace_all) {
(0, _) => return Err(ToolError::invalid(format!("old_text isn't in {}.", p.path)).with_remediation("Read the file again and copy the text exactly.")),
(1, _) | (_, true) => text.replace(p.old_text.as_str(), &p.new_text),
(n, false) => {
return Err(ToolError::invalid(format!("old_text appears {n} times in {}.", p.path))
.with_remediation("Include more surrounding text so it appears once, or set replace_all."));
}
};
write_checked(ctx, &path, &new)?;
Ok(ToolOutput::Value(json!({"edited": shown(&ws, &path), "replaced": if p.replace_all { count } else { 1 }})))
}
fn build_command_run(ctx: &mut Ctx<'_>, params: Value) -> Result<ToolOutput, ToolError> {
let p: CommandParams = parse_params(params)?;
let ws = workspace(ctx)?;
approve(ctx, "Bash", &json!({"command": p.command}))?.map_err(refused)?;
let app = ws.app_dir();
std::fs::create_dir_all(&app).map_err(|e| ToolError::io(app.display(), e))?;
let inner = app.join("app");
let had_inner = inner.is_dir();
let (shell, flag) = if cfg!(windows) { ("cmd", "/C") } else { ("sh", "-c") };
let cancel = ctx.cancel.clone();
ctx.report(None, format!("Running {}", p.command.chars().take(120).collect::<String>()));
let out = Process::new(shell)
.args([flag, p.command.as_str()])
.cwd(&app)
.timeout(Duration::from_secs(p.timeout_secs.unwrap_or(600).clamp(1, 7200)))
.stdout_cap(4 * 1024 * 1024)
.stderr_cap(4 * 1024 * 1024)
.cancel_when(move || cancel.is_cancelled())
.label("the build command")
.run()?;
let tail = |s: String| -> String {
let skip = s.len().saturating_sub(OUTPUT_TAIL);
let mut start = skip;
while !s.is_char_boundary(start) {
start += 1;
}
s.get(start..).unwrap_or_default().to_string()
};
let mut v = json!({
"command": p.command,
"ran_in": ws.app_place(),
"exit_code": out.code,
"succeeded": out.success,
"stdout": tail(out.stdout_text()),
"stderr": tail(out.stderr_text()),
});
// A model that reads file paths and commands from one base starts with `cd app`, or makes its
// project with `cargo new app`, from inside app/.
let first = p.command.split(['&', ';', '\n']).next().unwrap_or_default().trim().replace('\\', "/");
if ["cd app", "cd app/", "cd ./app", "cd ./app/"].contains(&first.as_str()) && !inner.is_dir() {
v["note"] = json!(format!("Commands already run in {}: leave out `cd app`.", ws.app_place()));
} else if !had_inner && app != ws.root && ["Cargo.toml", "package.json"].iter().any(|m| inner.join(m).is_file()) {
// Only a project: a folder named app is fine there (Next.js keeps its routes in one).
v["note"] = json!(
"This made a project in app/app/: commands already run in app/, so the app's project goes in app/ itself (app/Cargo.toml, app/package.json)."
);
}
Ok(ToolOutput::Value(v))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::inbox::InboxDir;
use crate::workspace::{ExistingFiles, TargetRef};
use crate::{CallOptions, Caller, Consent, Engine};
use std::sync::Arc;
fn building() -> (std::path::PathBuf, Workspace, Engine) {
let mut s = crate::testing::session();
let dir = s.config_dir();
let ws = Workspace::create(&dir, "Snake", "A snake game", TargetRef::None).unwrap();
s.ext.insert(Arc::new(InboxDir(ws.inbox_dir())));
(dir, ws, Engine::new(s))
}
fn call(e: &Engine, id: &str, p: Value) -> Result<Value, ToolError> {
e.call(id, p, CallOptions::new(Caller::Mcp).with_consent(Consent::Granted)).map(|o| o.to_json()["result"].clone())
}
#[test]
fn a_builder_reads_writes_and_edits_inside_its_project() {
let (_d, ws, e) = building();
call(&e, "build_file_write", json!({"path": "app/src/main.rs", "content": "fn main() {\n println!(\"hi\");\n}\n"})).unwrap();
let r = call(&e, "build_file_read", json!({"path": "app/src/main.rs"})).unwrap();
assert_eq!(r["total_lines"], 3);
call(&e, "build_file_edit", json!({"path": "app/src/main.rs", "old_text": "\"hi\"", "new_text": "\"hello\""})).unwrap();
assert!(std::fs::read_to_string(ws.app_dir().join("src/main.rs")).unwrap().contains("hello"));
let list = call(&e, "build_files_list", json!({})).unwrap();
assert_eq!(list["root"], "app");
assert!(list["entries"].to_string().contains("app/src/main.rs"), "{list}");
let page = call(&e, "build_file_read", json!({"path": "app/src/main.rs", "offset": 1, "limit": 1})).unwrap();
assert_eq!(page["text"], " println!(\"hello\");\n");
assert_eq!(page["more"], true);
// Not found, ambiguous, outside the project.
assert!(call(&e, "build_file_edit", json!({"path": "app/src/main.rs", "old_text": "nope", "new_text": "x"})).is_err());
assert!(call(&e, "build_file_read", json!({"path": "../../etc/passwd"})).is_err());
assert!(call(&e, "build_file_write", json!({"path": "../outside.txt", "content": "x"})).is_err());
}
/// A project file over the read cap is refused instead of being read whole; a file exactly at
/// the cap still reads, with only its first page returned.
#[test]
fn a_file_over_the_read_cap_is_refused() {
let (_d, ws, e) = building();
std::fs::create_dir_all(ws.app_dir()).unwrap();
let cap = MAX_READ_FILE as usize;
std::fs::write(ws.app_dir().join("over-cap.txt"), "a".repeat(cap + 1)).unwrap();
let err = call(&e, "build_file_read", json!({"path": "app/over-cap.txt"})).unwrap_err();
assert_eq!(err.code, ErrorCode::OverLimit);
assert!(err.message.contains("16 MB"), "{err:?}");
std::fs::write(ws.app_dir().join("at-cap.txt"), "a".repeat(cap)).unwrap();
let ok = call(&e, "build_file_read", json!({"path": "app/at-cap.txt"})).unwrap();
assert_eq!((ok["lines"].as_u64(), ok["text"].as_str().map(str::len)), (Some(1), Some(MAX_READ + 1)));
}
/// An edit refuses a project file over the 16 MiB cap before reading it, and changes nothing.
#[test]
fn a_file_over_the_edit_cap_is_refused_and_left_unchanged() {
let (_d, ws, e) = building();
std::fs::create_dir_all(ws.app_dir()).unwrap();
let original = format!("old{}", "a".repeat(MAX_READ_FILE as usize));
let path = ws.app_dir().join("over-cap.txt");
std::fs::write(&path, &original).unwrap();
let err = call(&e, "build_file_edit", json!({"path": "app/over-cap.txt", "old_text": "old", "new_text": "new"})).unwrap_err();
assert_eq!(err.code, ErrorCode::OverLimit);
assert!(err.message.contains("16 MB"), "{err:?}");
assert_eq!(std::fs::read(&path).unwrap(), original.as_bytes(), "a refused edit must not change the file");
}
/// A file exactly at the edit cap still reads, and an edit that fits the write cap is saved.
#[test]
fn a_file_at_the_edit_cap_can_be_edited() {
let (_d, ws, e) = building();
std::fs::create_dir_all(ws.app_dir()).unwrap();
let cap = MAX_READ_FILE as usize;
let head = "start\n";
let mut original = String::with_capacity(cap);
original.push_str(head);
original.push_str(&"a".repeat(cap - head.len()));
let path = ws.app_dir().join("at-cap.txt");
std::fs::write(&path, &original).unwrap();
// Long enough that replacing it brings the file under the 8 MB a write may hold.
let old = "a".repeat(9 * 1024 * 1024);
let out = call(&e, "build_file_edit", json!({"path": "app/at-cap.txt", "old_text": old, "new_text": "b"})).unwrap();
assert_eq!(out["replaced"], 1);
let saved = std::fs::read_to_string(&path).unwrap();
assert!(saved.starts_with("start\nb"), "{:.20}", saved);
assert_eq!(saved.len(), cap - old.len() + 1);
}
/// "Work on my project" keeps the app in the project root: the default listing must be that
/// root, not a missing or nested `app/`, and not Craft Anything's own records.
#[test]
fn a_project_edited_in_place_is_listed_from_its_own_folder() {
let d = tempfile::tempdir().unwrap();
std::fs::write(d.path().join("main.py"), "print('hi')\n").unwrap();
std::fs::create_dir_all(d.path().join("src")).unwrap();
std::fs::write(d.path().join("src/app.py"), "x = 1\n").unwrap();
// A nested app/ would be the wrong default: the app itself is the root.
std::fs::create_dir_all(d.path().join("app")).unwrap();
std::fs::write(d.path().join("app/other.txt"), "not the app\n").unwrap();
let mut s = crate::testing::session();
let ws = Workspace::create_at(d.path(), "Mine", "Add a page", TargetRef::None, Some(ExistingFiles::Edit)).unwrap();
// checks/ isn't a Craft Anything record the builder must avoid: it keeps its own notes there.
std::fs::create_dir_all(d.path().join("checks")).unwrap();
std::fs::write(d.path().join("checks/notes.md"), "note\n").unwrap();
// capture/ is an own record in the root listing, but the brief tells the builder to read it.
std::fs::create_dir_all(d.path().join("capture/pages")).unwrap();
std::fs::write(d.path().join("capture/README.md"), "evidence\n").unwrap();
std::fs::write(d.path().join("capture/pages/index.html"), "<p>evidence</p>\n").unwrap();
// A dependency tree bigger than the entry cap must not crowd out the app's own files.
std::fs::create_dir_all(d.path().join("vendor")).unwrap();
for i in 0..MAX_ENTRIES + 10 {
std::fs::write(d.path().join("vendor").join(format!("f{i:04}.txt")), b"x").unwrap();
}
s.ext.insert(Arc::new(InboxDir(ws.inbox_dir())));
let e = Engine::new(s);
let list = call(&e, "build_files_list", json!({})).unwrap();
assert_eq!(list["root"], ".");
let entries = list["entries"].to_string();
assert!(entries.contains("main.py") && entries.contains("src/app.py"), "{list}");
assert!(entries.contains("app/other.txt"), "a real nested folder is still part of the root: {list}");
assert!(entries.contains("checks/notes.md"), "the builder's own check notes stay visible: {list}");
assert!(!entries.contains("craft.json"), "Craft Anything's own records are not app files: {list}");
assert!(!entries.contains("capture/"), "capture stays out of the default root listing: {list}");
assert!(entries.contains("vendor/"), "the dependency folder is listed but not walked: {list}");
assert_eq!(list["truncated"], false, "vendor must not consume the entry cap: {list}");
// The brief tells the builder to read capture/, so an explicit listing is allowed.
let capture = call(&e, "build_files_list", json!({"path": "capture"})).unwrap();
assert_eq!(capture["root"], "capture");
assert!(capture["entries"].to_string().contains("capture/README.md"), "{capture}");
assert!(capture["entries"].to_string().contains("capture/pages/"), "{capture}");
let pages = call(&e, "build_files_list", json!({"path": "capture/pages"})).unwrap();
assert_eq!(pages["root"], "capture/pages");
assert!(pages["entries"].to_string().contains("capture/pages/index.html"), "{pages}");
std::fs::create_dir_all(d.path().join("reference")).unwrap();
std::fs::write(d.path().join("reference/look.png"), "x").unwrap();
let reference = call(&e, "build_files_list", json!({"path": "reference"})).unwrap();
assert!(reference["entries"].to_string().contains("reference/look.png"), "{reference}");
// An explicit nested folder is still listed by that path.
let nested = call(&e, "build_files_list", json!({"path": "app"})).unwrap();
assert_eq!(nested["root"], "app");
assert!(nested["entries"].to_string().contains("app/other.txt"), "{nested}");
}
/// A project path with `..` must not make listing paths absolute or hide an explicit capture.
#[test]
fn an_explicit_capture_listing_handles_a_project_path_with_dot_dot() {
let base = tempfile::tempdir().unwrap();
let project = base.path().join("project");
std::fs::create_dir_all(&project).unwrap();
let dotted = project.join("..").join("project");
let mut s = crate::testing::session();
let ws = Workspace::create_at(&dotted, "Mine", "Look at the evidence", TargetRef::None, None).unwrap();
std::fs::create_dir_all(ws.capture_dir()).unwrap();
std::fs::write(ws.capture_dir().join("README.md"), "evidence\n").unwrap();
assert!(ws.is_own_record(&ws.capture_dir().join("README.md")), "capture is an own record");
s.ext.insert(Arc::new(InboxDir(ws.inbox_dir())));
let e = Engine::new(s);
let capture = call(&e, "build_files_list", json!({"path": "capture"})).unwrap();
assert_eq!(capture["root"], "capture");
let entries = capture["entries"].to_string();
assert!(entries.contains("capture/README.md"), "{capture}");
let absolute = base.path().to_string_lossy().into_owned();
assert!(!entries.contains(&absolute), "paths stay relative: {capture}");
}
/// A link to a folder; false where this system won't let a test make one.
fn link_dir(target: &Path, link: &Path) -> bool {
#[cfg(unix)]
let made = std::os::unix::fs::symlink(target, link);
#[cfg(windows)]
let made = std::os::windows::fs::symlink_dir(target, link);
made.is_ok()
}
#[test]
fn a_link_in_the_project_cannot_lead_outside_it() {
let (_d, ws, e) = building();
let outside = tempfile::tempdir().unwrap();
std::fs::write(outside.path().join("secret.txt"), "secret").unwrap();
std::fs::create_dir_all(ws.app_dir().join("src")).unwrap();
if !link_dir(outside.path(), &ws.app_dir().join("out")) {
eprintln!("skipped: this system won't make links for tests");
return;
}
assert!(call(&e, "build_file_read", json!({"path": "app/out/secret.txt"})).is_err());
assert!(call(&e, "build_file_edit", json!({"path": "app/out/secret.txt", "old_text": "secret", "new_text": "x"})).is_err());
assert!(call(&e, "build_file_write", json!({"path": "app/out/new.txt", "content": "x"})).is_err());
assert!(call(&e, "build_file_write", json!({"path": "app/out/deeper/new.txt", "content": "x"})).is_err());
assert_eq!(std::fs::read_to_string(outside.path().join("secret.txt")).unwrap(), "secret");
assert!(!outside.path().join("new.txt").exists() && !outside.path().join("deeper").exists());
// Listing shows the link but doesn't walk into it.
let list = call(&e, "build_files_list", json!({})).unwrap();
assert!(list["entries"].as_array().unwrap().iter().any(|x| x["path"] == "app/out" && x["link"] == true), "{list}");
assert!(!list.to_string().contains("secret.txt"), "{list}");
assert!(call(&e, "build_files_list", json!({"path": "app/out"})).is_err());
// A link that stays inside the project still works.
assert!(link_dir(&ws.app_dir().join("src"), &ws.app_dir().join("alias")));
call(&e, "build_file_write", json!({"path": "app/alias/lib.rs", "content": "x"})).unwrap();
assert!(ws.app_dir().join("src/lib.rs").is_file());
}
/// #280: a line longer than a page left reading stuck at it, with nothing shown.
#[test]
fn a_line_longer_than_a_page_is_shown_cut() {
let (_d, _ws, e) = building();
let long = "x".repeat(MAX_READ + 44_000);
call(&e, "build_file_write", json!({"path": "app/min.js", "content": format!("{long}\nend\n")})).unwrap();
let first = call(&e, "build_file_read", json!({"path": "app/min.js"})).unwrap();
assert_eq!((first["lines"].as_u64(), first["more"].as_bool()), (Some(1), Some(true)));
assert_eq!(first["text"].as_str().map(str::len), Some(MAX_READ + 1));
assert!(first["note"].as_str().is_some_and(|n| n.contains("Line 1")), "{first}");
let next = call(&e, "build_file_read", json!({"path": "app/min.js", "offset": 1})).unwrap();
assert_eq!((next["text"].as_str(), next["more"].as_bool(), next.get("note")), (Some("end\n"), Some(false), None));
}
/// #24: a model that writes `/app/…` builds the app, and one that leaves out `app/` is told.
#[test]
fn paths_from_the_root_name_the_project_folders() {
let (_d, ws, e) = building();
let r = call(&e, "build_file_write", json!({"path": "/app/package.json", "content": "{}"})).unwrap();
assert_eq!((r["written"].as_str(), r.get("note")), (Some("app/package.json"), None));
assert!(ws.app_dir().join("package.json").is_file());
// Backslashes separate folders only on Windows; elsewhere they're part of a name.
let read = if cfg!(windows) { "\\app\\package.json" } else { "/app/package.json" };
assert_eq!(call(&e, "build_file_read", json!({"path": read})).unwrap()["text"], "{}\n");
assert!(call(&e, "build_files_list", json!({"path": "/app"})).unwrap()["entries"].to_string().contains("app/package.json"));
// A folder the project doesn't have stays outside it.
assert!(call(&e, "build_file_read", json!({"path": "/etc/passwd"})).is_err());
assert!(call(&e, "build_file_write", json!({"path": "/nowhere/x.txt", "content": "x"})).is_err());
assert!(call(&e, "build_file_write", json!({"path": "/../outside.txt", "content": "x"})).is_err());
let stray = call(&e, "build_file_write", json!({"path": "index.html", "content": "<p>hi</p>"})).unwrap();
assert!(stray["note"].as_str().unwrap().contains("outside app/"), "{stray}");
}
#[test]
fn writes_outside_app_and_dev_servers_follow_the_policy() {
let (_d, ws, e) = building();
// Auto mode is on by default: outside app/ (but inside the project) goes ahead.
call(&e, "build_file_write", json!({"path": "checks/notes.md", "content": "ok"})).unwrap();
// The person's own records are never written unasked.
assert!(call(&e, "build_file_write", json!({"path": "craft.json", "content": "{}"})).is_err());
assert!(ws.root.join("craft.json").is_file(), "untouched");
// Dev servers never exit: refused before anything runs.
let err = call(&e, "build_command_run", json!({"command": "npm run dev"})).unwrap_err();
assert!(err.message.contains("dev servers"), "{}", err.message);
}
/// R5.4: a local model ran `cd app && cargo build` from inside app/, reading file paths and
/// commands from one base.
#[test]
fn a_command_says_where_it_ran() {
let (_d, _ws, e) = building();
let ok = call(&e, "build_command_run", json!({"command": "echo built"})).unwrap();
assert_eq!((ok["ran_in"].as_str(), ok["succeeded"].as_bool(), ok.get("note")), (Some("app/"), Some(true), None));
let lost = call(&e, "build_command_run", json!({"command": "cd app && echo built"})).unwrap();
assert_eq!(lost["succeeded"], false, "{lost}");
assert!(lost["note"].as_str().is_some_and(|n| n.contains("already run in app/")), "{lost}");
let lines = call(&e, "build_command_run", json!({"command": "cd app\necho built"})).unwrap();
assert!(lines["note"].as_str().is_some_and(|n| n.contains("already run in app/")), "{lines}");
// Live, its first command was `cargo new app`, which made a project in app/app/.
let nested = call(&e, "build_command_run", json!({"command": "mkdir app && cd app && echo [package]> Cargo.toml"})).unwrap();
assert!(nested["note"].as_str().is_some_and(|n| n.contains("This made a project in app/app/")), "{nested}");
// Once there, it's a folder of the app's own: going into it is left alone.
let inner = call(&e, "build_command_run", json!({"command": "cd app && echo built"})).unwrap();
assert_eq!((inner["succeeded"].as_bool(), inner.get("note")), (Some(true), None));
// A folder named app with no project in it is fine (Next.js keeps its routes in one).
let (_d, _ws, e) = building();
let routes = call(&e, "build_command_run", json!({"command": "mkdir app"})).unwrap();
assert_eq!(routes.get("note"), None, "{routes}");
}
#[test]
fn the_checklist_is_checked() {
let (_d, _ws, e) = building();
let ok = call(&e, "build_checklist", json!({"todos": [{"content": "Draw the map", "activeForm": "Drawing the map", "status": "completed"}, {"content": "Add the snake", "status": "in_progress"}]})).unwrap();
assert_eq!((ok["steps"].as_u64(), ok["done"].as_u64()), (Some(2), Some(1)));
assert!(call(&e, "build_checklist", json!({"todos": [{"content": "x", "status": "maybe"}]})).is_err());
assert!(call(&e, "build_checklist", json!({"todos": []})).is_err());
}
#[test]
fn only_while_building() {
let e = Engine::new(crate::testing::session());
let err = call(&e, "build_files_list", json!({})).unwrap_err();
assert_eq!(err.code, ErrorCode::FeatureMissing);
}
#[test]
fn app_relative_paths_fall_back_to_app_dir() {
let (_d, ws, e) = building();
call(&e, "build_file_write", json!({"path": "app/crates/example/src/board.rs", "content": "pub struct Board;\n"})).unwrap();
// Compiler errors from build_command_run emit paths relative to app/ (without app/ prefix).
let r = call(&e, "build_file_read", json!({"path": "crates/example/src/board.rs"})).unwrap();
assert_eq!(r["path"], "app/crates/example/src/board.rs");
assert_eq!(r["text"], "pub struct Board;\n");
// build_file_edit falls back to the existing file in app/.
let ed = call(&e, "build_file_edit", json!({"path": "crates/example/src/board.rs", "old_text": "Board", "new_text": "CanvasBoard"})).unwrap();
assert_eq!(ed["edited"], "app/crates/example/src/board.rs");
assert!(std::fs::read_to_string(ws.app_dir().join("crates/example/src/board.rs")).unwrap().contains("CanvasBoard"));
// build_files_list falls back when listing an app-relative subdirectory.
let list = call(&e, "build_files_list", json!({"path": "crates/example"})).unwrap();
assert_eq!(list["root"], "app/crates/example");
assert!(list["entries"].to_string().contains("app/crates/example/src/board.rs"), "{list}");
// build_file_write writes inside app/ when the parent folder already exists in app/ and not at root.
let wr = call(&e, "build_file_write", json!({"path": "crates/example/src/new_mod.rs", "content": "pub struct NewMod;\n"})).unwrap();
assert_eq!((wr["written"].as_str(), wr.get("note")), (Some("app/crates/example/src/new_mod.rs"), None));
assert!(ws.app_dir().join("crates/example/src/new_mod.rs").is_file());
assert!(!ws.root.join("crates/example/src/new_mod.rs").exists());
// Overwriting an existing file via build_file_write without app/ also targets app/.
let ov = call(&e, "build_file_write", json!({"path": "crates/example/src/board.rs", "content": "pub struct Updated;\n"})).unwrap();
assert_eq!(ov["written"], "app/crates/example/src/board.rs");
// Root-level stray file without an app-specific parent still writes to root with the note.
let stray = call(&e, "build_file_write", json!({"path": "README.md", "content": "hi"})).unwrap();
assert!(stray["note"].as_str().unwrap().contains("outside app/"), "{stray}");
// Explicit app/ paths (including ./app/...) must never fall back into a nested app/app/.
call(&e, "build_file_write", json!({"path": "app/app/page.tsx", "content": "nested"})).unwrap();
let err_plain = call(&e, "build_file_read", json!({"path": "app/page.tsx"})).unwrap_err();
let err_dot = call(&e, "build_file_read", json!({"path": "./app/page.tsx"})).unwrap_err();
assert_eq!(err_plain.code, err_dot.code);
let written = call(&e, "build_file_write", json!({"path": "./app/page.tsx", "content": "top"})).unwrap();
assert_eq!(written["written"], "app/page.tsx");
assert_eq!(std::fs::read_to_string(ws.app_dir().join("app/page.tsx")).unwrap(), "nested");
assert_eq!(std::fs::read_to_string(ws.app_dir().join("page.tsx")).unwrap(), "top");
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.