arcature_templates/lib.rs
1//! `arcature-templates` — the Arcature application-template engine.
2//!
3//! This crate owns the **canonical Arcature application file tree** and its
4//! deterministic, safe generation. It removes application-skeleton ownership
5//! from `arcature-cli`: the CLI parses options and orchestrates processes;
6//! this crate owns the file tree, the template variants, the rendering, the
7//! destination validation, and the generated application contract.
8//!
9//! # What this crate owns
10//!
11//! * The canonical application root: `Cargo.toml`, `arcature.toml`,
12//! `proxy.rs`, `s.script`, plus frontend/package metadata. `proxy.rs` is
13//! the application request-lifecycle boundary; `s.script` is the
14//! application custom-command lifecycle. Both exist from generation, even
15//! if initially no-op.
16//! * The generated Rust module graph: `main.rs` (minimal entry point),
17//! `lib.rs` (module declarations and re-exports), `app.rs`, `state.rs`,
18//! `routes/{mod,web,api}.rs`, and the `controllers/`, `models/`,
19//! `middleware/`, `validation/`, `jobs/`, `mail/`, `pages/` seams (each a
20//! directory with a `mod.rs` that only declares submodules — no
21//! implementation logic in `mod.rs` per AGENTS.md §1). The module graph is
22//! wired from generation so a user does not hand-wire basic modules after
23//! `arc new`; the binary delegates to the library crate's `app::run()`.
24//! * The template layers (`base/`, `frontend/react/`, `frontend/vue/`,
25//! `database/postgres/`) and their deterministic composition into presets.
26//! * Cross-ecosystem project-name validation (one strict rule valid for
27//! Cargo, `arcature.toml`, `package.json`, and Rust identifiers).
28//! * The safety boundary: path-traversal rejection, absolute-escape
29//! rejection, duplicate-destination rejection, no-overwrite of an
30//! existing target, unresolved-placeholder detection, and atomic
31//! staging-then-rename so the destination is never partially written.
32//! * The [`Preset`] type (frontend × database) and the [`generate`]
33//! entrypoint.
34//!
35//! # What this crate does not own
36//!
37//! It does not implement a general AST rewriting engine, does not regex-edit
38//! user Rust source, does not run the generated application, does not
39//! execute template content as code during rendering, and does not depend on
40//! `arcature` at runtime (the generated app depends on `arcature`; this crate
41//! does not). It has zero runtime dependencies — rendering is pure Rust over
42//! std, and templates are embedded with `include_str!`.
43//!
44//! # Composition
45//!
46//! A [`Preset`] composes layers with last-write-wins by path:
47//!
48//! 1. `base/` — shared by every preset (module graph, proxy, root document,
49//! frontend asset routes, shared frontend config).
50//! 2. `database/postgres/` — overlay (only when database is enabled):
51//! replaces `Cargo.toml`, `run.rs`, `state.rs` with DB-aware versions and
52//! adds the `database/migrations/` package and `.env.example`. The
53//! `bootstrap/main.rs` is identical across presets (the binary delegates
54//! to the library), so it is not overridden.
55//! 3. `frontend/react/` or `frontend/vue/` — the Inertia client, the page,
56//! the Vite config, and the `package.json`. No `pnpm-lock.yaml` is
57//! committed: the package declares `@arcature/client` at the certified
58//! `__ARCATURE_CLIENT_VERSION__` (an internal certified placeholder
59//! sentinel `0.0.0` while the package is unpublished, modeled as
60//! `published: false`; a real authorized npm publication replaces it with
61//! a real shipping version — ADR-0006 §6 / §5), so the user's first
62//! `pnpm install` produces the lockfile.
63//!
64//! The four certified presets (React+DB, React+no-DB, Vue+DB, Vue+no-DB) are
65//! returned by [`preset::certified`] in a stable order.
66//!
67//! # Safety
68//!
69//! [`generate`] refuses to overwrite an existing target, validates the
70//! project name before any file is written, rejects any rendered path that
71//! escapes the staging root (path traversal or absolute path), rejects
72//! duplicate destinations, and detects any unresolved `__PLACEHOLDER__`
73//! left after substitution. Files are written to a hidden staging directory
74//! and renamed into place in one step; a write failure removes the staging
75//! directory. Template content is never executed as code during rendering.
76//!
77//! # Deployment awareness
78//!
79//! The generated application does not assume source code exists on production
80//! servers. Production artifacts are: the application native binary, the
81//! compiled frontend assets, an optional `arc` ops binary, and an optional
82//! `s.script`. The generated `Cargo.toml` and `arcature.toml` carry no
83//! runtime dependency on Cargo, Node, or pnpm.
84//!
85//! # Example
86//!
87//! ```no_run
88//! use arcature_templates::{CertifiedVersions, generate, certified, Database, Frontend, Preset};
89//! use std::path::Path;
90//!
91//! # fn main() -> Result<(), arcature_templates::TemplateError> {
92//! let preset = Preset::new(Frontend::React, Database::Enabled);
93//! // Certified versions read from the Platform manifest by `arc new`.
94//! let versions = CertifiedVersions::new("2026.2.1", "2026.1.0", "0.0.0");
95//! generate(Path::new("/tmp/my-app"), preset, &versions)?;
96//! # Ok(())
97//! # }
98//! ```
99//!
100//! The generated application is a complete Arcature app: `cargo build` in the
101//! new directory compiles the Rust backend, and `arc install && arc build`
102//! installs and produces the frontend assets through the Arcature lifecycle.
103
104#![forbid(unsafe_code)]
105#![doc(html_root_url = "https://docs.rs/arcature-templates")]
106
107mod catalog;
108mod destination;
109mod error;
110mod generate;
111mod name;
112mod plan;
113mod preset;
114mod render;
115mod versions;
116
117pub use error::TemplateError;
118pub use generate::generate;
119pub use name::ProjectName;
120pub use preset::{Database, Frontend, Preset, certified};
121pub use versions::CertifiedVersions;