use std::path::Path;
#[derive(Clone, Copy)]
pub enum Progress {
Incomplete,
Complete,
Ended,
Unknown,
}
#[derive(Clone, Copy)]
enum Shell {
Posix,
Windows,
}
const SHELL: Shell = if cfg!(windows) {
Shell::Windows
} else {
Shell::Posix
};
pub fn plain_formal(formal: &str) -> &str {
match formal.strip_prefix(r"\\?\") {
Some(rest)
if rest.as_bytes().get(0..3).is_some_and(|prefix| {
prefix[0].is_ascii_alphabetic() && prefix[1] == b':' && prefix[2] == b'\\'
}) =>
{
rest
}
_ => formal,
}
}
pub fn formal_for<'a>(command: &str, formal: &'a str) -> &'a str {
match command {
"templates remove" | "templates update" | "templates alias" | "templates trust"
| "templates untrust" => formal,
_ => plain_formal(formal),
}
}
fn path_value(value: &str, shell: Shell) -> &str {
let separators: &[char] = match shell {
Shell::Posix => &['/'],
Shell::Windows => &['/', '\\'],
};
let trimmed = value.trim_end_matches(separators);
let drive = trimmed.strip_prefix(r"\\?\").unwrap_or(trimmed);
let drive = matches!(shell, Shell::Windows)
&& drive.len() == 2
&& drive.as_bytes()[0].is_ascii_alphabetic()
&& drive.as_bytes()[1] == b':';
let root = trimmed.is_empty() || drive;
if root && trimmed.len() < value.len() {
&value[..trimmed.len() + 1]
} else {
trimmed
}
}
pub fn word(value: &str) -> String {
word_for(value, SHELL)
}
fn word_for(value: &str, shell: Shell) -> String {
match shell {
Shell::Posix => posix_word(value),
Shell::Windows => windows_word(value),
}
}
fn posix_word(value: &str) -> String {
let plain = !value.is_empty()
&& !value.starts_with('=')
&& value
.chars()
.all(|c| c.is_ascii_alphanumeric() || "_@%+=:,./-".contains(c));
if plain {
value.into()
} else {
format!("'{}'", value.replace('\'', r"'\''"))
}
}
fn windows_word(value: &str) -> String {
let plain = !value.is_empty()
&& !value.starts_with(['=', '~'])
&& value
.chars()
.all(|c| c.is_ascii_alphanumeric() || "_@%+=:,./-\\~".contains(c));
if plain {
return value.into();
}
let body = value.trim_end_matches('\\');
let trailing = &value[body.len()..];
format!("\"{}\"{trailing}", body.replace('"', "\"\""))
}
fn target(path: &Path) -> String {
word(path_value(&path.to_string_lossy(), SHELL))
}
pub struct Operand {
value: String,
written: String,
}
pub fn value(value: &str) -> Operand {
Operand {
value: value.into(),
written: word(value),
}
}
fn path_operand(path: &Path) -> Operand {
file_operand(&path.to_string_lossy())
}
fn file_operand(path: &str) -> Operand {
value(path_value(path, SHELL))
}
pub fn placeholder(name: &str) -> Operand {
Operand {
value: name.into(),
written: name.into(),
}
}
fn needs_separator(operands: &[Operand]) -> bool {
operands
.iter()
.any(|operand| operand.value.starts_with('-'))
}
pub fn toha(command: &str, options: &[String], operands: &[Operand]) -> String {
let mut words = vec!["toha".to_string(), command.to_string()];
words.extend(options.iter().cloned());
if needs_separator(operands) {
words.push("--".into());
}
words.extend(operands.iter().map(|operand| operand.written.clone()));
words.join(" ")
}
#[derive(Clone, Copy)]
pub enum Arg<'a> {
Given(&'a str),
Placeholder(&'static str),
}
impl Arg<'_> {
fn operand(self) -> Operand {
match self {
Self::Given(given) => value(given),
Self::Placeholder(name) => placeholder(name),
}
}
}
fn option_value(flag: &str, value: Arg) -> String {
match value {
Arg::Placeholder(name) => format!("{flag} {name}"),
Arg::Given(value) if value.starts_with('-') && value != "-" => {
format!("{flag}={}", word(path_value(value, SHELL)))
}
Arg::Given(value) => format!("{flag} {}", word(path_value(value, SHELL))),
}
}
#[derive(Clone, Copy)]
pub enum Invocation<'a> {
Stage {
template: Arg<'a>,
path: &'a Path,
output: Option<Option<&'a str>>,
},
Apply {
template: Option<Arg<'a>>,
path: &'a Path,
answers: Option<Arg<'a>>,
force: bool,
dry_run: bool,
trust: bool,
},
}
impl<'a> Invocation<'a> {
fn verb(&self) -> &'static str {
match self {
Self::Stage { .. } => "stage",
Self::Apply { .. } => "apply",
}
}
fn template(&self) -> Option<&str> {
match self {
Self::Stage {
template: Arg::Given(template),
..
}
| Self::Apply {
template: Some(Arg::Given(template)),
..
} => Some(template),
_ => None,
}
}
fn without_dry_run(mut self) -> Self {
if let Self::Apply { dry_run, .. } = &mut self {
*dry_run = false;
}
self
}
pub fn command(&self) -> String {
match *self {
Self::Stage {
template,
path,
output,
} => {
let operands = [template.operand(), path_operand(path)];
let option = output.map(|file| match file {
Some(file) => format!("--async={}", word(file)),
None => "--async".to_string(),
});
match option {
Some(option) if !needs_separator(&operands) => {
format!("{} {option}", toha("stage", &[], &operands))
}
option => toha("stage", &option.into_iter().collect::<Vec<_>>(), &operands),
}
}
Self::Apply {
template,
path,
answers,
force,
dry_run,
trust,
} => {
let mut options = Vec::new();
if let Some(answers) = answers {
options.push(option_value("--answers", answers));
}
for (set, flag) in [
(force, "--force"),
(trust, "--trust"),
(dry_run, "--dry-run"),
] {
if set {
options.push(flag.to_string());
}
}
let operands: Vec<Operand> = template
.map(Arg::operand)
.into_iter()
.chain([path_operand(path)])
.collect();
toha("apply", &options, &operands)
}
}
}
}
fn abort(path: &Path) -> String {
toha("abort", &[], &[path_operand(path)])
}
fn apply_staged(path: &Path) -> String {
toha("apply", &[], &[path_operand(path)])
}
fn continue_prompting(path: &Path) -> String {
toha("continue", &[], &[path_operand(path)])
}
fn continue_answers(path: &Path) -> String {
toha(
"continue",
&[],
&[path_operand(path), placeholder("<ANSWERS>")],
)
}
fn apply_dry_run(path: &Path) -> String {
toha("apply", &["--dry-run".to_string()], &[path_operand(path)])
}
fn answers_hint(template: &str) -> String {
format!(
" {{\"template\": {}, \"answers\": {{ ... }}}}",
serde_json::to_string(template).expect("template string")
)
}
pub fn answer_batch(path: &Path, template: &str) -> String {
[
"answer these questions with an answers document:".to_string(),
answers_hint(template),
format!(
"then run: {} (- reads standard input)",
continue_answers(path)
),
]
.join("\n")
}
pub fn apply_incomplete_agent(path: &Path, template: &str) -> String {
[
format!("the interview at {} has questions remaining", target(path)),
"answer these questions with an answers document:".to_string(),
answers_hint(template),
format!(
"to answer the current batch: {} (- reads standard input)",
continue_answers(path)
),
format!(
"to answer in a terminal instead: {}",
continue_prompting(path)
),
format!("then write its files: {}", apply_staged(path)),
]
.join("\n")
}
pub fn continue_complete(path: &Path) -> String {
[
format!("the interview at {} is complete", target(path)),
format!("to see the files it will write: {}", apply_dry_run(path)),
format!("to write them: {}", apply_staged(path)),
]
.join("\n")
}
fn finish(path: &Path, progress: Progress) -> String {
let apply = apply_staged(path);
let resume = continue_prompting(path);
match progress {
Progress::Complete => format!("to finish the staged interview: {apply}"),
Progress::Incomplete => {
format!("to finish the staged interview: {resume}, then {apply}")
}
Progress::Ended => {
format!(
"the staged interview was ended by a flow node; to start over: {}",
abort(path)
)
}
Progress::Unknown => {
format!("to finish the staged interview: {resume} if questions remain, then {apply}")
}
}
}
fn remaining(path: &Path) -> String {
format!(
"to answer them: {} in a terminal, or {} with an answers document (- reads standard input)",
continue_prompting(path),
continue_answers(path)
)
}
pub fn other_template(
invocation: &Invocation,
path: &Path,
staged: &str,
formal: &str,
progress: Progress,
) -> String {
let arg = invocation.template().unwrap_or(formal);
let named = if arg == formal {
arg.to_string()
} else {
format!("{arg} ({formal})")
};
[
format!(
"an interview for {staged} is staged at {}; {named} is a different template",
target(path)
),
format!(
"to {} {} instead: {}, then {}",
invocation.verb(),
word(arg),
abort(path),
invocation.command()
),
finish(path, progress),
]
.join("\n")
}
pub fn already_staged(
invocation: &Invocation,
path: &Path,
staged: &str,
progress: Progress,
) -> String {
let p = target(path);
let mut lines = match progress {
Progress::Complete => vec![
format!("an interview for {staged} is already staged at {p} and is complete"),
format!("to write its files: {}", apply_staged(path)),
],
Progress::Incomplete => vec![
format!(
"an interview for {staged} is already staged at {p} and has questions remaining"
),
remaining(path),
format!("then write its files: {}", apply_staged(path)),
],
Progress::Ended => vec![format!(
"an interview for {staged} staged at {p} was ended by a flow node"
)],
Progress::Unknown => vec![
format!("an interview for {staged} is already staged at {p}"),
finish(path, progress),
],
};
lines.push(format!(
"to start it again: {}, then {}",
abort(path),
invocation.command()
));
lines.join("\n")
}
pub fn flow_ended(ended: &toha::Ended) -> String {
let (verb, tail) = match ended.kind() {
toha::EndKind::Stop => ("stopped", "no files were written and no hooks ran"),
toha::EndKind::Abort => (
"aborted",
"no files were written, no hooks ran, and the staged interview was discarded",
),
};
match ended.label() {
Some(label) => format!("{verb}: {label} — {tail}"),
None => format!("{verb} — {tail}"),
}
}
pub fn complete(path: &Path) -> String {
format!(
"the interview at {} is complete; to write its files: {}",
target(path),
apply_staged(path)
)
}
pub fn complete_answers_unused(path: &Path) -> String {
[
format!(
"the interview at {} is complete, so the answers document is not used",
target(path)
),
format!("to preview the files: {}", apply_dry_run(path)),
format!("to write them: {}", apply_staged(path)),
]
.join("\n")
}
pub fn ended_answers_unused(path: &Path, staged: &str, kind: toha::EndKind) -> String {
let restage = Invocation::Stage {
template: Arg::Given(formal_for("stage", staged)),
path,
output: None,
};
let verb = match kind {
toha::EndKind::Stop => "was stopped by a flow node",
toha::EndKind::Abort => "was aborted by a flow node",
};
[
format!(
"the interview at {} {verb}, so the answers document is not used",
target(path)
),
format!("to start over: {}, then {}", abort(path), restage.command()),
]
.join("\n")
}
pub fn replay_failed(path: &Path, staged: &str, error: &str) -> String {
let restage = Invocation::Stage {
template: Arg::Given(formal_for("stage", staged)),
path,
output: None,
};
[
format!(
"the staged interview at {} cannot be resumed: {error}",
target(path)
),
format!("to start over: {}, then {}", abort(path), restage.command()),
]
.join("\n")
}
pub fn explain_rejections(
rejections: &toha::Rejections,
path: &Path,
staged: &str,
) -> toha::Rejections {
let restage = Invocation::Stage {
template: Arg::Given(formal_for("stage", staged)),
path,
output: Some(None),
};
rejections
.iter()
.cloned()
.map(|mut rejection| {
if rejection.kind == toha::RejectionKind::Answered {
rejection.message = format!(
"{}; to change it: {}, then {}",
rejection.message,
abort(path),
restage.command()
);
}
rejection
})
.collect()
}
pub fn staged_commands(path: &Path) -> Vec<String> {
vec![continue_answers(path), apply_staged(path), abort(path)]
}
pub fn continue_no_terminal(path: &Path) -> String {
[
format!(
"no terminal to prompt in for the interview at {}",
target(path)
),
format!(
"to answer the current batch: {} with an answers document (- reads standard input)",
continue_answers(path)
),
]
.join("\n")
}
pub fn nothing_staged(path: &Path) -> String {
let template = placeholder("<TEMPLATE>");
[
format!("no interview is staged at {}", target(path)),
format!(
"to start one: {}",
toha(
"stage",
&[],
&[placeholder("<TEMPLATE>"), path_operand(path)]
)
),
format!(
"to start one and write its files: {}",
toha("apply", &[], &[template, path_operand(path)])
),
]
.join("\n")
}
pub fn no_terminal(template: &str, path: &Path) -> String {
let stage = Invocation::Stage {
template: Arg::Given(template),
path,
output: Some(None),
};
let apply = Invocation::Apply {
template: Some(Arg::Given(template)),
path,
answers: Some(Arg::Placeholder("<FILE>")),
force: false,
dry_run: false,
trust: false,
};
[
"no terminal to prompt in".to_string(),
format!(
"to stage the interview and emit its question batch: {}",
stage.command()
),
format!(
"to answer from an answers document and write the files: {}",
apply.command()
),
]
.join("\n")
}
pub fn answers_without_template(
path: &Path,
answers: &str,
staged: Option<(&str, Progress)>,
) -> String {
let apply_new = |template| Invocation::Apply {
template: Some(template),
path,
answers: Some(Arg::Given(answers)),
force: false,
dry_run: false,
trust: false,
};
let mut lines = vec!["--answers requires a template".to_string()];
match staged {
Some((_, Progress::Complete)) => lines.push(format!(
"the staged interview at {} is complete; to write its files: {}",
target(path),
apply_staged(path)
)),
Some((staged, Progress::Ended)) => {
lines.push(format!(
"the staged interview at {} was ended by a flow node; to start over: {}, then {}",
target(path),
abort(path),
Invocation::Stage {
template: Arg::Given(formal_for("stage", staged)),
path,
output: None,
}
.command()
));
}
Some((staged, _)) => {
lines.push(format!(
"to answer the staged interview: {}, then {}",
toha(
"continue",
&[],
&[path_operand(path), file_operand(answers)]
),
apply_staged(path)
));
lines.push(format!(
"to answer it and write its files in one command: {}",
apply_new(Arg::Given(formal_for("apply", staged))).command()
));
}
None => lines.push(format!(
"to answer a new interview and write its files: {}",
apply_new(Arg::Placeholder("<TEMPLATE>")).command()
)),
}
lines.join("\n")
}
pub fn needs_trust(invocation: &Invocation, installed: Option<&str>, changed: bool) -> String {
trust_lines(
"hooks will not run without --trust\nto run them this time: ",
invocation,
installed,
changed,
)
}
pub fn dry_run_needs_trust(
invocation: &Invocation,
installed: Option<&str>,
changed: bool,
) -> String {
trust_lines(
"hooks need trust; to run them: ",
&invocation.without_dry_run(),
installed,
changed,
)
}
fn trust_lines(
lead: &str,
invocation: &Invocation,
installed: Option<&str>,
changed: bool,
) -> String {
let mut trusted = *invocation;
if let Invocation::Apply { trust, .. } = &mut trusted {
*trust = true;
}
let mut lines = Vec::new();
if changed {
lines.push("hooks changed since approval".to_string());
}
lines.push(format!("{lead}{}", trusted.command()));
if let Some(formal) = installed {
lines.push(format!(
"to trust {formal} for every run: {}",
toha(
"templates trust",
&[],
&[value(formal_for("templates trust", formal))]
)
));
}
lines.join("\n")
}
pub fn surface_unreadable(formal: &str, error: &toha::ReviewError) -> String {
format!("cannot read the installed hooks of {formal}: {error}")
}
pub fn approved_surface(surface: &toha::HookSurface) -> String {
let mut lines = vec!["approved surface:".to_string()];
for (index, view) in surface.views().iter().enumerate() {
let command = view.node.get("hook").unwrap_or(&view.node);
let mut parts = Vec::new();
if let Some(script) = command.get("script").and_then(serde_json::Value::as_str) {
parts.push(format!("script: {script}"));
}
if let Some(run) = command.get("run") {
parts.push(format!("run: {run}"));
}
if let Some(args) = command.get("args") {
parts.push(format!("args: {args}"));
}
let detail = if parts.is_empty() {
command.to_string()
} else {
parts.join(" ")
};
lines.push(format!(" hook {} {detail}", index + 1));
}
lines.join("\n")
}
pub fn conflicts(invocation: &Invocation) -> String {
let mut forced = *invocation;
if let Invocation::Apply { force, .. } = &mut forced {
*force = true;
}
format!("to overwrite them: {}", forced.command())
}
pub fn add_needs_address(name: &str, folder_exists: bool) -> String {
let mut lines = vec![
"add requires a git address or folder".to_string(),
format!(
"to see installed templates: {}",
toha("templates list", &[], &[])
),
];
if folder_exists {
lines.push(format!(
"to add the folder {name}: {}",
toha("templates add", &[], &[value(&format!("./{name}"))])
));
}
lines.push(format!(
"to add from a git address or folder: {}",
toha("templates add", &[], &[placeholder("<ADDRESS>")])
));
lines.join("\n")
}
pub fn alias_needs_one_template(alias: &str, addresses: &[String]) -> String {
let options = [format!("--alias {}", word(alias))];
std::iter::once("--alias requires exactly one template".to_string())
.chain(addresses.iter().map(|address| {
format!(
"to add {address} as {alias}: {}",
toha("templates add", &options, &[value(address)])
)
}))
.collect::<Vec<_>>()
.join("\n")
}
pub fn alias_in_use(template: &str, alias: &str, removable: bool) -> String {
let mut lines = vec!["alias is in use".to_string()];
if removable {
lines.push(format!(
"to move it to {template}: {}, then {}",
toha(
"templates alias",
&[format!("--remove {}", word(alias))],
&[]
),
toha("templates alias", &[], &[value(template), value(alias)])
));
}
lines.push(format!(
"to choose another alias: {}",
toha(
"templates alias",
&[],
&[value(template), placeholder("<ALIAS>")]
)
));
lines.join("\n")
}
pub fn not_in_user_registry(name: &str) -> String {
[
format!("not installed in user registry: {name}"),
format!(
"to see the layer of each template: {}",
toha("templates list", &["--json".into()], &[])
),
]
.join("\n")
}
pub fn ambiguous(name: &str, matches: &[String], retry: &[String]) -> String {
let mut lines = vec![format!("ambiguous template name: {name}")];
for (index, formal) in matches.iter().enumerate() {
if let Some(command) = retry.get(index) {
lines.push(format!("to use {formal}: {command}"));
}
lines.push(format!(
"to give {formal} an alias: {}",
toha(
"templates alias",
&[],
&[
value(formal_for("templates alias", formal)),
placeholder("<ALIAS>")
]
)
));
}
lines.join("\n")
}
#[cfg(test)]
mod tests {
use super::{Shell, formal_for, path_value, plain_formal, surface_unreadable, word_for};
#[test]
fn surface_unreadable_names_the_template_and_the_error() {
let error = toha::ReviewError::Escape(std::path::PathBuf::from("/outside/x.sh"));
let message = surface_unreadable("acme", &error);
assert!(
message.starts_with("cannot read the installed hooks of acme:"),
"{message}"
);
assert!(message.contains("escapes the template root"), "{message}");
}
#[test]
fn each_command_gets_the_formal_name_form_it_accepts() {
let extended = r"\\?\D:\a\template";
for command in ["stage", "apply", "templates add"] {
assert_eq!(formal_for(command, extended), r"D:\a\template", "{command}");
}
for command in [
"templates remove",
"templates update",
"templates alias",
"templates trust",
"templates untrust",
] {
assert_eq!(formal_for(command, extended), extended, "{command}");
}
assert_eq!(
word_for(formal_for("templates remove", extended), Shell::Windows),
r#""\\?\D:\a\template""#
);
}
#[test]
fn path_values_end_without_a_separator_except_a_root() {
assert_eq!(path_value(r"C:\my dir\", Shell::Windows), r"C:\my dir");
assert_eq!(path_value("C:/my dir/", Shell::Windows), "C:/my dir");
assert_eq!(path_value(r"C:\", Shell::Windows), r"C:\");
assert_eq!(path_value("C:/", Shell::Windows), "C:/");
assert_eq!(path_value(r"\", Shell::Windows), r"\");
assert_eq!(path_value("notes/", Shell::Posix), "notes");
assert_eq!(path_value("/", Shell::Posix), "/");
assert_eq!(path_value(r"a\", Shell::Posix), r"a\");
assert_eq!(
word_for(path_value(r"C:\my dir\", Shell::Windows), Shell::Windows),
r#""C:\my dir""#
);
assert_eq!(
word_for(path_value(r"C:\", Shell::Windows), Shell::Windows),
r"C:\"
);
assert_eq!(path_value("", Shell::Windows), "");
assert_eq!(path_value("", Shell::Posix), "");
assert_eq!(path_value(r"\\?\C:\", Shell::Windows), r"\\?\C:\");
assert_eq!(path_value(r"\\?\C:\dir\", Shell::Windows), r"\\?\C:\dir");
assert_eq!(path_value(r"\\?\C:\\", Shell::Windows), r"\\?\C:\");
}
#[test]
fn windows_quoted_words_keep_trailing_backslashes_outside_the_quotes() {
assert_eq!(word_for(r"\\?\C:\", Shell::Windows), r#""\\?\C:"\"#);
assert_eq!(word_for(r"C:\my dir\", Shell::Windows), r#""C:\my dir"\"#);
assert_eq!(word_for(r"C:\my dir\\", Shell::Windows), r#""C:\my dir"\\"#);
assert_eq!(word_for(r"C:\my dir", Shell::Windows), r#""C:\my dir""#);
assert_eq!(word_for("", Shell::Windows), r#""""#);
}
#[test]
fn extended_drive_paths_are_named_by_their_drive_path() {
assert_eq!(plain_formal(r"\\?\D:\a\template"), r"D:\a\template");
for kept in [
r"\\?\UNC\server\share",
r"\\server\share",
"/srv/template",
"gh:org/repo#one",
] {
assert_eq!(plain_formal(kept), kept);
}
}
const SPECIAL: [&str; 19] = [
"", "#x", "$x", "`x`", "a*", "a?", "[a]", "a!", "a&b", "a;b", "a|b", "<a>", "(a)", "{a}",
"a'b", "a\"b", "=x", "a b", "~/x",
];
#[test]
fn posix_words_a_shell_would_change_are_single_quoted() {
for plain in [
"notes",
"a/b.json",
"x=y",
"gh:org/repo@main",
"-",
"a,b%c+d",
] {
assert_eq!(word_for(plain, Shell::Posix), plain);
}
for special in SPECIAL.into_iter().chain([r"a\b", "a~b"]) {
let quoted = word_for(special, Shell::Posix);
assert!(
quoted.starts_with('\'') && quoted.ends_with('\''),
"{special}: {quoted}"
);
}
assert_eq!(word_for("a'b", Shell::Posix), r"'a'\''b'");
}
#[test]
fn windows_words_keep_paths_plain_and_double_quote_the_rest() {
for plain in [
r"C:\work",
r"C:\Users\RUNNER~1\AppData\Local\Temp\.tmpA1",
r"D:\a\toha\tests\fixtures\text-basic\template",
"file:///C:/Users/x/remote",
"notes",
"a/b.json",
"x=y",
"-",
] {
assert_eq!(word_for(plain, Shell::Windows), plain);
}
for special in SPECIAL {
let quoted = word_for(special, Shell::Windows);
assert!(
quoted.starts_with('"') && quoted.ends_with('"'),
"{special}: {quoted}"
);
}
assert_eq!(word_for(r"C:\my dir", Shell::Windows), r#""C:\my dir""#);
assert_eq!(word_for(r#"a"b"#, Shell::Windows), r#""a""b""#);
}
}