The design language that makes your AI harness better at design.
JavaScript
//! Component review is an explicit, opt-in runtime. It does not yet replace the build-phase gates.
pub mod capture;
mod history;
mod lifecycle;
mod manifest;
pub mod plan;
mod server;
mod store;
#[cfg(test)]
mod tests;
pub mod verify;
mod visual_approval;
use impeccable_common::Io;
use serde_json::json;
use std::path::{Path, PathBuf};
fn arg(args: &[String], name: &str) -> Option<String> {
args.iter()
.position(|v| v == name)
.and_then(|i| args.get(i + 1))
.cloned()
}
fn decode_path(s: &str) -> Result<String, String> {
let mut out = Vec::new();
let bytes = s.as_bytes();
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'%' {
if i + 2 >= bytes.len() {
return Err("bad path escape".into());
}
let pair = std::str::from_utf8(&bytes[i + 1..i + 3]).map_err(|e| e.to_string())?;
out.push(u8::from_str_radix(pair, 16).map_err(|e| e.to_string())?);
i += 3;
} else {
out.push(bytes[i]);
i += 1;
}
}
let decoded = String::from_utf8(out).map_err(|e| e.to_string())?;
if decoded.chars().any(char::is_control) {
return Err("control character in path".into());
}
Ok(decoded)
}
pub fn run(args: &[String], io: &mut Io) -> i32 {
run_with_capturer(args, io, None)
}
pub fn run_with_capturer(
args: &[String],
io: &mut Io,
mut capturer: Option<&mut dyn capture::ComponentCapturer>,
) -> i32 {
let result = (|| -> Result<i32, String> {
let store = arg(args, "--store")
.map(PathBuf::from)
.or_else(|| io.home().map(|h| h.join(".impeccable/component-reviews")))
.ok_or("no home directory; supply --store outside the project")?;
match args.first().map(String::as_str) {
Some("lifecycle") => {
let sessions: Vec<PathBuf> = args.windows(2).filter(|w| w[0] == "--session-dir")
.map(|w| PathBuf::from(&w[1])).collect();
let mut required: Vec<String> = args.windows(2).filter(|w| w[0] == "--require")
.map(|w| w[1].clone()).collect();
// A host names the builder project so the components stage is read
// against its spec: nothing to decide means no kit review is owed.
if let Some(project) = arg(args, "--project") {
if !plan::spec_needs_review(Path::new(&project)) {
required.retain(|stage| stage != "components");
}
}
let sessions = if sessions.is_empty() && !args.iter().any(|a| a == "--hosted") {
let project = io.cwd.canonicalize().map_err(|e| e.to_string())?;
lifecycle::project_sessions(&store, &project)?
} else { sessions };
io.out(&format!("{}\n", lifecycle::inspect(&sessions, &required)?));
Ok(0)
}
Some("plan") => {
let out = arg(args, "--out").unwrap_or_else(|| plan::DEFAULT_OUT.into());
let packet = plan::write(&io.cwd, &out)?;
let components = packet["components"].as_array().unwrap();
let count = |role: &str| components.iter().filter(|c| c["role"] == role).count();
let flagged = components.iter().filter(|c| c["role"] == "plan" && (c["flags"].is_array() || c["codeDrawn"] == true)).count();
let flagged_assets = components.iter().filter(|c| c["role"] == "asset" && c["flags"].is_array()).count();
let s = impeccable_common::launcher::spell_self(io.env("IMPECCABLE_SELF").filter(|v| !v.trim().is_empty()).unwrap_or("impeccable"));
io.out(&format!("PLAN {out}: {} assets{}, {} plan items ({flagged} flagged or code-drawn), {} code regions\nNEXT {s} component-review capture --manifest {out}, then {s} component-review serve --session <session from capture>\n",
count("asset"), if flagged_assets > 0 { format!(" ({flagged_assets} flagged)") } else { String::new() }, count("plan"), packet["codeRegions"].as_array().map_or(0, Vec::len)));
Ok(0)
}
Some("prepare") | Some("capture") => {
let path = arg(args, "--manifest")
.ok_or("prepare needs --manifest <project-relative file>")?;
if args[0] == "capture" {
if let Some(tool) = io.env("IMPECCABLE_COMPONENT_REVIEW_TOOL") {
return Err(format!("This session uses hosted human review. Call {tool} with manifest_path={path:?}; it captures the components and waits for the user's decisions. A failed capture is not approval."));
}
}
let project = io.cwd.canonicalize().map_err(|e| e.to_string())?;
// The plan review is proven without a browser; only v1/v2 packets reach the native capturer.
let v3 = std::fs::read(project.join(manifest::relative(&path)?)).ok()
.and_then(|b| serde_json::from_slice::<serde_json::Value>(&b).ok())
.is_some_and(|m| m["schemaVersion"] == 3);
let mut plan_capturer = capture::PlanCapturer;
let renderer: Option<&mut dyn capture::ComponentCapturer> = if args[0] != "capture" { None }
else if v3 { Some(&mut plan_capturer) }
else { Some(capturer.take().ok_or("native component capturer unavailable")?) };
let dir=store::prepare_file(&store,&project,&path,renderer)?;
let state = store::read(&dir.join("current.json"))?;
let status = state["receipt"]["visualDecision"]
.as_str()
.unwrap_or("awaiting-review");
io.out(&format!("{}\n", json!({
"session": dir.file_name().unwrap().to_string_lossy(),
"revision": state["packet"]["revision"],
"status": status,
"capture": state["capture"],
"round": state["packet"]["round"],
"lifecycle": if lifecycle::closed(&state) { lifecycle::terminal(&state) } else { serde_json::Value::Null }
})));
Ok(0)
}
Some("verify") => {
let path = arg(args, "--manifest").ok_or("verify needs --manifest <project-relative file>")?;
let receipt = verify::approved(&store, &io.cwd, &path)?;
io.out(&format!("{}\n", receipt));
Ok(0)
}
Some("serve") | Some("status") | Some("refresh-approvals") => {
let id = arg(args, "--session").ok_or("needs --session <id from prepare>")?;
if id.len() != 64 || !id.bytes().all(|b| b.is_ascii_hexdigit()) {
return Err("invalid session id".into());
}
let dir = store.join(id);
if args[0] == "refresh-approvals" {
let count=store::refresh_approvals(&dir)?;
io.out(&format!("{}\n",json!({"carried":count})));
Ok(0)
} else if args[0] == "serve" {
// Same no-browser signal as serve-question: exit 2 routes to the unattended path.
let set = |k: &str| io.env(k).is_some_and(|v| !v.is_empty());
let headless = set("CI") || (set("SSH_CONNECTION") && !set("DISPLAY"))
|| (cfg!(target_os = "linux") && !set("DISPLAY") && !set("WAYLAND_DISPLAY"));
if set("IMPECCABLE_QUESTION_DISABLED") || (headless && !set("IMPECCABLE_QUESTION_FORCE")) {
io.out("component-review: no reviewer can open a browser in this session; the review stays pending.\n");
return Ok(2);
}
let port = arg(args, "--port")
.unwrap_or_else(|| "0".into())
.parse::<u16>()
.map_err(|e| e.to_string())?;
let idle = arg(args, "--idle-timeout")
.or_else(|| io.env("IMPECCABLE_COMPONENT_REVIEW_IDLE_TIMEOUT").map(String::from))
.map(|v| v.parse::<u64>().ok().filter(|&n| n > 0).ok_or("--idle-timeout needs a positive number of seconds"))
.transpose()?
.unwrap_or(30 * 60);
static STOP: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
impeccable_common::proc::on_interrupt(&STOP);
let limits = server::Limits { idle: std::time::Duration::from_secs(idle), grace: std::time::Duration::from_secs(5) };
server::serve(&dir, port, io, limits, Some(&STOP))
} else {
let state = store::read(&dir.join("current.json"))?;
io.out(&format!("{}\n", json!({
"revision": state["packet"]["revision"],
"receipt": state["receipt"],
"capture": state["capture"],
"sourceStatus": if lifecycle::closed(&state) { None } else { store::sources_current(&state).err() },
"lifecycle": if lifecycle::closed(&state) { lifecycle::terminal(&state) } else { serde_json::Value::Null },
// A crashed or killed server leaves its file behind; only a live PID is a service.
"service": store::read(&dir.join("service.json")).ok()
.filter(|s| s["pid"].as_i64().is_some_and(impeccable_common::proc::pid_reachable))
})));
Ok(0)
}
}
_ => Err("usage: impeccable component-review plan [--out .impeccable/review/components.json] | prepare|capture|verify --manifest <file> | lifecycle [--session-dir <dir>] [--require components|hero] [--hosted] | serve --session <id> [--port 0] [--idle-timeout <seconds>] | status|refresh-approvals --session <id> [--store <outside-project-dir>]".into())
}
})();
match result {
Ok(code) => code,
Err(e) => {
io.err(&format!("component-review: {e}\n"));
1
}
}
}