Skip to main content

Crate toha

Crate toha 

Source
Expand description

§Toha

Generate projects and files from templates.

CI Latest release

Toha terminal demo

Toha is a project scaffolding tool and Rust crate. A template contains an interview and files to render with Jinja. Toha plans the output before it writes, so you can inspect a dry run and handle conflicts.

The same interview engine serves terminal users, scripts, agents, and Rust callers. Scripts and agents can answer one JSON Schema batch at a time and resume a staged interview in another process.

  • One interview for people, scripts, agents, and Rust callers
  • Resumable async interviews and headless answers files
  • Typed Jinja values and rendered file paths
  • each file generation and static files
  • Template hooks gated by trust
  • Git template sources, short names, and aliases
  • Embedded agent skills through toha skills

Read the Toha documentation for guides and the full contract.

§Install

Homebrew:

brew install wyrd-company/tools/toha

APT:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://repo.wyrd.foo/pubkey.asc |
  sudo tee /etc/apt/keyrings/wyrd-company.asc >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/wyrd-company.asc] \
https://repo.wyrd.foo/apt stable main" |
  sudo tee /etc/apt/sources.list.d/wyrd-company.list >/dev/null
sudo apt update
sudo apt install toha

RPM:

sudo curl -fsSL https://repo.wyrd.foo/wyrd.repo -o /etc/yum.repos.d/wyrd.repo
sudo dnf install toha

Arch Linux (AUR):

paru -S toha-bin

GitHub Releases also provides Linux and macOS tarballs, Windows zip archives, and SHA256SUMS for direct installation.

§First run

Toha ships a small demo template inside the binary. From any directory, offline, with nothing installed:

toha apply toha-demo ./notes

Answer Note title and Topic. To inspect the file plan without writing it, use toha apply toha-demo ./preview --dry-run.

toha-demo is a reserved fallback name. If you install or alias a template as toha-demo, that template resolves instead.

§Using Toha from Rust

Add the library without the CLI dependencies:

cargo add toha --no-default-features

From this repository checkout, drive the same interview with an identity-bearing answers document. The document names the template it answers, which Toha compares by exact string equality with the formal name the caller has established before it evaluates any answer:

use std::path::Path;
use toha::{Interview, Seed, Template};
use toha::context::{EnvironmentSnapshot, ExecutionFacts, HostFacts, InvocationContext, SelectedTemplate};
use toha::protocol::{self, DocumentStep};
use toha::staging::canonical_target;
let template_root = Path::new("docs/examples/demo").canonicalize().unwrap();
let template = Template::load(&template_root).unwrap();
let expected = template_root.to_str().unwrap();
let target = canonical_target(Path::new("./notes")).unwrap();
let seed = Seed {
    now: "2026-01-01T00:00:00Z[UTC]".parse().unwrap(),
    defaults: Default::default(),
    context: InvocationContext::new(
        target,
        SelectedTemplate::new(expected.into(), template.name.clone(), Vec::new(), None),
        HostFacts::capture(),
        ExecutionFacts::new(false, false),
        EnvironmentSnapshot::Unavailable,
    ).unwrap(),
};
let Interview::Asking(pending) = Interview::start(&template, seed).unwrap() else { panic!("expected questions") };
// The document must name the formal template it answers.
let text = serde_json::json!({
    "template": expected,
    "answers": {"title": "Sample note", "topic": "Research"},
}).to_string();
let DocumentStep::Accepted { interview, .. } =
    protocol::answer_document_once(expected, pending, &text).unwrap()
else { panic!("the document was rejected") };
let Interview::Complete(done) = interview else { panic!("expected complete interview") };
assert_eq!(done.answers.len(), 2);

In-memory callers that build answers directly still use Pending::answer with RawAnswers and the raw headless walk; the envelope is only for external JSON.

See CONTRIBUTING.md for development and changes.

Re-exports§

pub use apply::Applied;
pub use apply::ApplyError;
pub use apply::ApplyOptions;
pub use apply::HookReport;
pub use inject::Anchor;
pub use inject::EditReport;
pub use inject::EditResolution;
pub use inject::JsonEditError;
pub use inject::JsonFormat;
pub use inject::JsonPath;
pub use inject::JsonPathSegment;
pub use inject::MarkerStyle;
pub use inject::Occurrence;
pub use inject::PlannedEdit;
pub use inject::PlannedJsonEdit;
pub use inject::PlannedRegionEdit;
pub use inject::RegionError;
pub use inject::RegionKey;
pub use inject::json_value_to_cst_input;
pub use inject::report_json_edit;
pub use inject::report_region_edit;
pub use inject::resolve_json_edit;
pub use inject::resolve_region_edit;
pub use interview::Answer;
pub use interview::AnswerError;
pub use interview::Answers;
pub use interview::Batch;
pub use interview::CheckError;
pub use interview::Completed;
pub use interview::Disposition;
pub use interview::EndKind;
pub use interview::Ended;
pub use interview::EvalError;
pub use interview::Interview;
pub use interview::Item;
pub use interview::Pending;
pub use interview::Prompt;
pub use interview::PromptKind;
pub use interview::RawAnswer;
pub use interview::RawAnswers;
pub use interview::Rejection;
pub use interview::RejectionKind;
pub use interview::Rejections;
pub use interview::Seed;
pub use interview::Step;
pub use plan::Content;
pub use plan::Deferred;
pub use plan::FileMutation;
pub use plan::Plan;
pub use plan::PlanError;
pub use plan::Planned;
pub use plan::PlannedFile;
pub use plan::PlannedHook;
pub use plan::PlannedProgram;
pub use plan::TargetPath;
pub use requirement::MissingRequirements;
pub use requirement::Requirement;
pub use review::HookSurface;
pub use review::HookSurfaceDiff;
pub use review::HookView;
pub use review::ReviewDigest;
pub use review::ReviewError;
pub use review::ScriptDigest;
pub use review::Trust;
pub use review::evaluate_trust;
pub use template::FlowAction;
pub use template::FlowNode;
pub use template::Id;
pub use template::LoadError;
pub use template::Node;
pub use template::Problem;
pub use template::Question;
pub use template::QuestionKind;
pub use template::SkipScope;
pub use template::Template;

Modules§

apply
config
Layered configuration for template lookup.
context
Toha’s immutable, typed invocation context.
git_target
Initializes an apply target as a git repository for a template’s git question, with an optional origin remote.
hook
inject
Content injection: bounded mutation of an existing target file.
interview
plan
protocol
The interview protocol boundary: the external answers envelope, the identity gate, and the result documents.
registry
Validated registry layers, discovery, and name resolution.
requirement
The programs a template declares in requires, confirmed on PATH before an interview starts so that a caller does not answer questions for an apply whose hooks cannot run.
review
The reviewable executable surface of a template and the single trust rule.
snapshot
Git-based project snapshots and template updates.
source
Template addresses and immutable Git fetches.
staging
template