Expand description
arcature-templates — the Arcature application-template engine.
This crate owns the canonical Arcature application file tree and its
deterministic, safe generation. It removes application-skeleton ownership
from arcature-cli: the CLI parses options and orchestrates processes;
this crate owns the file tree, the template variants, the rendering, the
destination validation, and the generated application contract.
§What this crate owns
- The canonical application root:
Cargo.toml,arcature.toml,proxy.rs,s.script, plus frontend/package metadata.proxy.rsis the application request-lifecycle boundary;s.scriptis the application custom-command lifecycle. Both exist from generation, even if initially no-op. - The generated Rust module graph:
main.rs(minimal entry point),lib.rs(module declarations and re-exports),app.rs,state.rs,routes/{mod,web,api}.rs, and thecontrollers/,models/,middleware/,validation/,jobs/,mail/,pages/seams (each a directory with amod.rsthat only declares submodules — no implementation logic inmod.rsper AGENTS.md §1). The module graph is wired from generation so a user does not hand-wire basic modules afterarc new; the binary delegates to the library crate’sapp::run(). - The template layers (
base/,frontend/react/,frontend/vue/,database/postgres/) and their deterministic composition into presets. - Cross-ecosystem project-name validation (one strict rule valid for
Cargo,
arcature.toml,package.json, and Rust identifiers). - The safety boundary: path-traversal rejection, absolute-escape rejection, duplicate-destination rejection, no-overwrite of an existing target, unresolved-placeholder detection, and atomic staging-then-rename so the destination is never partially written.
- The
Presettype (frontend × database) and thegenerateentrypoint.
§What this crate does not own
It does not implement a general AST rewriting engine, does not regex-edit
user Rust source, does not run the generated application, does not
execute template content as code during rendering, and does not depend on
arcature at runtime (the generated app depends on arcature; this crate
does not). It has zero runtime dependencies — rendering is pure Rust over
std, and templates are embedded with include_str!.
§Composition
A Preset composes layers with last-write-wins by path:
base/— shared by every preset (module graph, proxy, root document, frontend asset routes, shared frontend config).database/postgres/— overlay (only when database is enabled): replacesCargo.toml,run.rs,state.rswith DB-aware versions and adds thedatabase/migrations/package and.env.example. Thebootstrap/main.rsis identical across presets (the binary delegates to the library), so it is not overridden.frontend/react/orfrontend/vue/— the Inertia client, the page, the Vite config, and thepackage.json. Nopnpm-lock.yamlis committed: the package declares@arcature/clientat the certified__ARCATURE_CLIENT_VERSION__(an internal certified placeholder sentinel0.0.0while the package is unpublished, modeled aspublished: false; a real authorized npm publication replaces it with a real shipping version — ADR-0006 §6 / §5), so the user’s firstpnpm installproduces the lockfile.
The four certified presets (React+DB, React+no-DB, Vue+DB, Vue+no-DB) are
returned by preset::certified in a stable order.
§Safety
generate refuses to overwrite an existing target, validates the
project name before any file is written, rejects any rendered path that
escapes the staging root (path traversal or absolute path), rejects
duplicate destinations, and detects any unresolved __PLACEHOLDER__
left after substitution. Files are written to a hidden staging directory
and renamed into place in one step; a write failure removes the staging
directory. Template content is never executed as code during rendering.
§Deployment awareness
The generated application does not assume source code exists on production
servers. Production artifacts are: the application native binary, the
compiled frontend assets, an optional arc ops binary, and an optional
s.script. The generated Cargo.toml and arcature.toml carry no
runtime dependency on Cargo, Node, or pnpm.
§Example
use arcature_templates::{CertifiedVersions, generate, certified, Database, Frontend, Preset};
use std::path::Path;
let preset = Preset::new(Frontend::React, Database::Enabled);
// Certified versions read from the Platform manifest by `arc new`.
let versions = CertifiedVersions::new("2026.2.1", "2026.1.0", "0.0.0");
generate(Path::new("/tmp/my-app"), preset, &versions)?;The generated application is a complete Arcature app: cargo build in the
new directory compiles the Rust backend, and arc install && arc build
installs and produces the frontend assets through the Arcature lifecycle.
Structs§
- Certified
Versions - The certified versions written into a generated application.
- Preset
- A generation preset: a frontend combined with a database mode.
- Project
Name - A validated cross-ecosystem project name.
Enums§
- Database
- Whether to generate the database layer.
- Frontend
- The frontend framework.
- Template
Error - A template-generation failure.
Functions§
- certified
- The four certified presets the phase spec requires to build.
- generate
- Generate a complete Arcature application at
targetforpreset, using the certified version setversions(read from the Platform manifest by the CLI — RV2.12 / ADR-0005 invariant 14: generated projects are reproducible against a certified Platform set, not “latest of each crate”).