Skip to main content

Crate arcature_templates

Crate arcature_templates 

Source
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.rs is the application request-lifecycle boundary; s.script is 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 the controllers/, models/, middleware/, validation/, jobs/, mail/, pages/ seams (each a directory with a mod.rs that only declares submodules — no implementation logic in mod.rs per AGENTS.md §1). The module graph is wired from generation so a user does not hand-wire basic modules after arc new; the binary delegates to the library crate’s app::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 Preset type (frontend × database) and the generate entrypoint.

§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:

  1. base/ — shared by every preset (module graph, proxy, root document, frontend asset routes, shared frontend config).
  2. database/postgres/ — overlay (only when database is enabled): replaces Cargo.toml, run.rs, state.rs with DB-aware versions and adds the database/migrations/ package and .env.example. The bootstrap/main.rs is identical across presets (the binary delegates to the library), so it is not overridden.
  3. frontend/react/ or frontend/vue/ — the Inertia client, the page, the Vite config, and the package.json. No pnpm-lock.yaml is committed: the package declares @arcature/client at the certified __ARCATURE_CLIENT_VERSION__ (an internal certified placeholder sentinel 0.0.0 while the package is unpublished, modeled as published: false; a real authorized npm publication replaces it with a real shipping version — ADR-0006 §6 / §5), so the user’s first pnpm install produces 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§

CertifiedVersions
The certified versions written into a generated application.
Preset
A generation preset: a frontend combined with a database mode.
ProjectName
A validated cross-ecosystem project name.

Enums§

Database
Whether to generate the database layer.
Frontend
The frontend framework.
TemplateError
A template-generation failure.

Functions§

certified
The four certified presets the phase spec requires to build.
generate
Generate a complete Arcature application at target for preset, using the certified version set versions (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”).