From beafdb3676e01cb1ed76b90118616ffbf8c84a10 Mon Sep 17 00:00:00 2001
From: sunrisepeak <38786181+sunrisepeak@users.noreply.github.com>
Date: Thu, 4 Jun 2026 10:03:19 +0800
Subject: [PATCH] feat: package-based project templates (design v2 T1-T5,T7)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mcpp new --template now accepts a multi-level SPEC: a bare name resolves
the builtin registry first (frozen: bin; gui = transitional deprecation
alias), then falls through to a package template — pkg | pkg:tmpl |
pkg@ver | pkg@ver:tmpl. Packages opt in by shipping templates/<name>/
(template.toml metadata: description / default / post_message /
[template.inject] self features).

New mcpp.scaffold module: SPEC parsing, {{project.name}}/{{self.name}}/
{{self.version}} rendering (.in files; everything else verbatim; pure
data — no hooks/scripts), self-dependency injection (template's own
declaration wins), template listing. new --list-templates <pkg[@ver]>
prints a package's templates with the default marked. Fetch reuses the
dependency machinery (index lua -> semver latest -> install cache).

Builtin gui keeps working with a deprecation pointer; its pinned imgui
version bumps to current as a transitional stopgap (structural fix is
the package template itself: {{self.version}} cannot rot).

e2e 69 (hermetic: pre-seeded install cache + local index lua) covers
L0/L3 resolution, rendering, inject-vs-declared, listing, error paths,
gui deprecation.
---
 docs/00-getting-started.md        |   3 +-
 src/cli.cppm                      | 192 +++++++++++++++++++++++--
 src/scaffold/template.cppm        | 231 ++++++++++++++++++++++++++++++
 tests/e2e/69_package_templates.sh | 136 ++++++++++++++++++
 4 files changed, 553 insertions(+), 9 deletions(-)
 create mode 100644 src/scaffold/template.cppm
 create mode 100755 tests/e2e/69_package_templates.sh

diff --git a/docs/00-getting-started.md b/docs/00-getting-started.md
index 79b8845d..13c48c07 100644
--- a/docs/00-getting-started.md
+++ b/docs/00-getting-started.md
@@ -122,6 +122,7 @@ mcpp pack --mode bundle-all        # 全自包含,含 libc 与 ld-linux
 
 ## 更多入口
 
-- GUI 起步:`mcpp new myapp --template gui`(imgui.app 窗口骨架,构建后 `mcpp run` 直接出窗口)。
+- GUI 起步:`mcpp new myapp --template imgui`(模板随 imgui 库分发、版本自动对齐;
+  `mcpp new --list-templates imgui` 查看库提供的全部模板,`--template imgui:docking` 选指定模板)。
 - 解释默认决策:`mcpp why [toolchain|runtime|deps]`;主机能力体检:`mcpp self doctor`;
   机器可读解析清单:构建产物 `target/<triple>/<fp>/resolution.json`。
diff --git a/src/cli.cppm b/src/cli.cppm
index 03a83e01..346fb8e8 100644
--- a/src/cli.cppm
+++ b/src/cli.cppm
@@ -38,6 +38,7 @@ import mcpp.fetcher;
 import mcpp.pm.resolver;   // PR-R4: extracted from cli.cppm
 import mcpp.pm.commands;   // PR-R5: cmd_add / cmd_remove / cmd_update live here now
 import mcpp.pm.index_spec; // IndexSpec for [indices] support
+import mcpp.scaffold;       // package-based project templates
 import mcpp.pm.mangle;     // Level 1 multi-version fallback (cross-major coexistence)
 import mcpp.pm.compat;     // 0.0.6: namespace field + dotted-name compat shims
 import mcpp.pm.dep_spec;
@@ -1093,20 +1094,191 @@ void gcc_post_install_fixup(const mcpp::config::GlobalConfig& cfg,
 
 // --- Commands ---
 
+// ─── Package-based templates (design v2: multi-level --template) ──────
+//
+// Resolve SPEC's package@version through the index, ensure the package
+// sources are installed (same cache as dependencies), and return the
+// package root (the directory containing mcpp.toml).
+struct FetchedTemplatePackage {
+    std::filesystem::path root;
+    std::string           name;     // short package name (e.g. "imgui")
+    std::string           version;  // resolved exact version
+};
+
+std::expected<FetchedTemplatePackage, std::string>
+fetch_template_package(const mcpp::scaffold::TemplateSpec& spec) {
+    auto cfg = mcpp::config::load_or_init(/*quiet=*/false,
+        make_bootstrap_progress_callback());
+    if (!cfg) return std::unexpected(cfg.error().message);
+    mcpp::pm::Fetcher fetcher(*cfg);
+
+    // Namespace candidates mirror dependency lookup: index root first,
+    // then the compat namespace.
+    std::string ns;
+    std::optional<std::string> lua;
+    for (std::string cand : {std::string{}, std::string{"compat"}}) {
+        if (auto l = fetcher.read_xpkg_lua(cand, spec.pkg)) {
+            ns = cand;
+            lua = std::move(*l);
+            break;
+        }
+    }
+    if (!lua) {
+        return std::unexpected(std::format(
+            "template package '{}' not found in the index "
+            "(check the name, or run `mcpp index update`)", spec.pkg));
+    }
+
+    std::string version = spec.version;
+    if (version.empty()) {
+        auto v = mcpp::pm::resolve_semver(ns, spec.pkg, "*", fetcher);
+        if (!v) return std::unexpected(v.error());
+        version = *v;
+    }
+
+    auto installed = fetcher.install_path(ns, spec.pkg, version);
+    if (!installed) {
+        auto fq = ns.empty() ? spec.pkg : std::format("{}.{}", ns, spec.pkg);
+        mcpp::ui::info("Downloading", std::format("{} v{}", fq, version));
+        CliInstallProgress progress;
+        std::vector<std::string> targets{ std::format("{}@{}", fq, version) };
+        auto r = fetcher.install(targets, &progress);
+        if (!r) return std::unexpected(std::format(
+            "fetch '{}@{}': {}", fq, version, r.error().message));
+        if (r->exitCode != 0) return std::unexpected(std::format(
+            "fetch '{}@{}' failed (exit {})", fq, version, r->exitCode));
+        installed = fetcher.install_path(ns, spec.pkg, version);
+        if (!installed) return std::unexpected(std::format(
+            "package '{}@{}' install path missing after fetch", fq, version));
+    }
+
+    // Package root = the directory holding mcpp.toml (tarballs usually wrap
+    // everything in a single top-level directory).
+    std::filesystem::path root = *installed;
+    if (!std::filesystem::exists(root / "mcpp.toml")) {
+        std::error_code ec;
+        for (auto& e : std::filesystem::directory_iterator(root, ec)) {
+            if (e.is_directory()
+                && std::filesystem::exists(e.path() / "mcpp.toml")) {
+                root = e.path();
+                break;
+            }
+        }
+    }
+    if (!std::filesystem::exists(root / "mcpp.toml")) {
+        return std::unexpected(std::format(
+            "package '{}@{}' has no mcpp.toml", spec.pkg, version));
+    }
+    return FetchedTemplatePackage{root, spec.pkg, version};
+}
+
+void print_template_listing(const FetchedTemplatePackage& pkg,
+                            const std::vector<mcpp::scaffold::TemplateEntry>& entries) {
+    std::println("Templates in {}@{}:", pkg.name, pkg.version);
+    for (auto& t : entries) {
+        std::println("  {:<14}{}{}", t.name,
+                     t.meta.isDefault ? "(default)  " : "           ",
+                     t.meta.description);
+    }
+    std::println("");
+    std::println("usage: mcpp new <name> --template {}[@ver][:<template>]", pkg.name);
+}
+
+int list_package_templates(const mcpp::scaffold::TemplateSpec& spec) {
+    auto pkg = fetch_template_package(spec);
+    if (!pkg) { mcpp::ui::error(pkg.error()); return 1; }
+    auto entries = mcpp::scaffold::list_templates(pkg->root);
+    if (!entries) { mcpp::ui::error(entries.error()); return 1; }
+    print_template_listing(*pkg, *entries);
+    return 0;
+}
+
+int new_from_package_template(const std::string& name, const std::string& specStr) {
+    auto spec = mcpp::scaffold::parse_spec(specStr);
+    if (spec.listOnly) return list_package_templates(spec);
+
+    auto pkg = fetch_template_package(spec);
+    if (!pkg) { mcpp::ui::error(pkg.error()); return 1; }
+    auto entries = mcpp::scaffold::list_templates(pkg->root);
+    if (!entries) { mcpp::ui::error(entries.error()); return 1; }
+
+    const mcpp::scaffold::TemplateEntry* chosen = nullptr;
+    if (spec.tmpl.empty()) {
+        for (auto& t : *entries) if (t.meta.isDefault) { chosen = &t; break; }
+        if (!chosen) {
+            mcpp::ui::error(std::format(
+                "package '{}' declares no default template — pick one explicitly:",
+                pkg->name));
+            print_template_listing(*pkg, *entries);
+            return 1;
+        }
+    } else {
+        for (auto& t : *entries) if (t.name == spec.tmpl) { chosen = &t; break; }
+        if (!chosen) {
+            mcpp::ui::error(std::format(
+                "package '{}@{}' has no template '{}'",
+                pkg->name, pkg->version, spec.tmpl));
+            print_template_listing(*pkg, *entries);
+            return 1;
+        }
+    }
+
+    std::filesystem::path root = std::filesystem::current_path() / name;
+    if (std::filesystem::exists(root)) {
+        mcpp::ui::error(std::format("'{}' already exists", root.string()));
+        return 1;
+    }
+    std::error_code ec;
+    std::filesystem::create_directories(root, ec);
+    if (ec) {
+        mcpp::ui::error(std::format("cannot create '{}': {}",
+                                    root.string(), ec.message()));
+        return 1;
+    }
+
+    mcpp::scaffold::RenderVars vars{name, pkg->name, pkg->version};
+    if (auto err = mcpp::scaffold::instantiate(
+            pkg->root / "templates" / chosen->name, root, vars)) {
+        mcpp::ui::error(*err);
+        return 1;
+    }
+    if (auto err = mcpp::scaffold::inject_self_dependency(
+            root / "mcpp.toml", vars, chosen->meta.injectSelfFeatures)) {
+        mcpp::ui::error(*err);
+        return 1;
+    }
+
+    mcpp::ui::status("Created", std::format(
+        "{} (template {}@{}:{})", name, pkg->name, pkg->version, chosen->name));
+    if (!chosen->meta.postMessage.empty())
+        std::println("{}", chosen->meta.postMessage);
+    return 0;
+}
+
 int cmd_new(const mcpplibs::cmdline::ParsedArgs& parsed) {
+    // Discovery mode: `mcpp new --list-templates <pkg>[@ver]` — no project.
+    if (auto lt = parsed.value("list-templates")) {
+        return list_package_templates(mcpp::scaffold::parse_spec(*lt));
+    }
+
     std::string name = parsed.positional(0);
     if (name.empty()) {
         std::println(stderr, "error: `mcpp new` requires a package name (e.g. `mcpp new hello`)");
         return 2;
     }
 
-    // `--template` selects the project skeleton: "bin" (default) or "gui"
-    // (an imgui.app starter — Tier-0 zero-boilerplate window).
+    // `--template` multi-level SPEC (design v2):
+    //   builtin registry (frozen: bin; gui = transitional alias), else a
+    //   package template: pkg | pkg:tmpl | pkg@ver | pkg@ver:tmpl.
     std::string tmpl = "bin";
     if (auto t = parsed.value("template")) tmpl = *t;
+    if (tmpl == "gui") {
+        mcpp::ui::warning(
+            "--template gui is deprecated; use `--template imgui` "
+            "(the template then ships with — and version-tracks — the library)");
+    }
     if (tmpl != "bin" && tmpl != "gui") {
-        std::println(stderr, "error: unknown --template '{}' (expected: bin | gui)", tmpl);
-        return 2;
+        return new_from_package_template(name, tmpl);
     }
     const bool gui = (tmpl == "gui");
 
@@ -1130,7 +1302,7 @@ int cmd_new(const mcpplibs::cmdline::ParsedArgs& parsed) {
             // The GUI template depends on the imgui module package. It does not
             // pin a toolchain — mcpp resolves the environment/default toolchain
             // and the GL runtime is closed by the ecosystem (compat.glx-runtime).
-            os << "\n[dependencies]\nimgui = \"0.0.2\"\n";
+            os << "\n[dependencies]\nimgui = \"0.0.5\"\n";
         }
     }
     // src/main.cpp — template with PROJECT placeholder, replaced with `name`.
@@ -5763,9 +5935,13 @@ int run(int argc, char** argv) {
         // ─── project commands ──────────────────────────────────────────
         .subcommand(cl::App("new")
             .description("Create a new mcpp package skeleton")
-            .arg(cl::Arg("name").help("Package directory name").required())
-            .option(cl::Option("template").short_name('t').takes_value().value_name("KIND")
-                .help("Project template: bin (default) | gui (imgui.app window starter)"))
+            // not .required(): `--list-templates` runs without a name
+            // (cmd_new validates presence for project creation itself).
+            .arg(cl::Arg("name").help("Package directory name"))
+            .option(cl::Option("template").short_name('t').takes_value().value_name("SPEC")
+                .help("bin (default) | <pkg>[@ver][:<template>] — package-shipped template"))
+            .option(cl::Option("list-templates").takes_value().value_name("PKG")
+                .help("List the templates a package ships (PKG[@ver])"))
             .action(wrap_rc(cmd_new)))
         .subcommand(cl::App("build")
             .description("Build the current package")
diff --git a/src/scaffold/template.cppm b/src/scaffold/template.cppm
new file mode 100644
index 00000000..682427e3
--- /dev/null
+++ b/src/scaffold/template.cppm
@@ -0,0 +1,231 @@
+// mcpp.scaffold — package-based project templates (design v2).
+//
+// Mechanism owned by mcpp: SPEC grammar, rendering, dependency injection.
+// Vocabulary owned by packages: template names, contents, default choice
+// (closed grammar / open vocabulary applied to scaffolding).
+//
+// A package opts in by shipping a `templates/` directory:
+//   templates/<name>/template.toml   — metadata (description/default/inject)
+//   templates/<name>/**.in           — rendered ({{var}} placeholders)
+//   templates/<name>/** (non-.in)    — copied verbatim
+//
+// Trust boundary: templates are pure data — render + copy, no hooks and no
+// script execution.
+
+export module mcpp.scaffold;
+
+import std;
+import mcpp.libs.toml;
+
+export namespace mcpp::scaffold {
+
+// `--template` package-form SPEC:
+//   pkg | pkg:tmpl | pkg@ver | pkg@ver:tmpl | pkg:   (trailing ':' = list)
+struct TemplateSpec {
+    std::string pkg;
+    std::string version;        // "" = latest
+    std::string tmpl;           // "" = the package's default template
+    bool        listOnly = false;
+};
+
+TemplateSpec parse_spec(std::string_view s) {
+    TemplateSpec spec;
+    std::string_view left = s;
+    if (auto c = s.find(':'); c != std::string_view::npos) {
+        left = s.substr(0, c);
+        auto right = s.substr(c + 1);
+        if (right.empty()) spec.listOnly = true;
+        else               spec.tmpl = std::string(right);
+    }
+    if (auto a = left.find('@'); a != std::string_view::npos) {
+        spec.pkg     = std::string(left.substr(0, a));
+        spec.version = std::string(left.substr(a + 1));
+    } else {
+        spec.pkg = std::string(left);
+    }
+    return spec;
+}
+
+struct TemplateMeta {
+    std::string description;
+    bool        isDefault = false;
+    std::string postMessage;
+    // [template.inject] self = { features = [...] }
+    std::vector<std::string> injectSelfFeatures;
+};
+
+std::expected<TemplateMeta, std::string>
+load_meta(const std::filesystem::path& templateDir) {
+    auto metaPath = templateDir / "template.toml";
+    if (!std::filesystem::exists(metaPath)) {
+        return std::unexpected(std::format(
+            "template '{}' has no template.toml", templateDir.filename().string()));
+    }
+    auto doc = mcpp::libs::toml::parse_file(metaPath);
+    if (!doc) {
+        return std::unexpected(std::format(
+            "template '{}': bad template.toml: {}",
+            templateDir.filename().string(), doc.error().message));
+    }
+
+    TemplateMeta meta;
+    if (auto v = doc->get_string("template.description"))  meta.description = *v;
+    if (auto v = doc->get_string("template.post_message")) meta.postMessage = *v;
+    if (auto* t = doc->get_table("template")) {
+        if (auto it = t->find("default"); it != t->end() && it->second.is_bool())
+            meta.isDefault = it->second.as_bool();
+        if (auto it = t->find("inject"); it != t->end() && it->second.is_table()) {
+            auto& inj = it->second.as_table();
+            if (auto self = inj.find("self");
+                self != inj.end() && self->second.is_table()) {
+                auto& st = self->second.as_table();
+                if (auto f = st.find("features");
+                    f != st.end() && f->second.is_array()) {
+                    for (auto& fv : f->second.as_array())
+                        if (fv.is_string())
+                            meta.injectSelfFeatures.push_back(fv.as_string());
+                }
+            }
+        }
+    }
+    return meta;
+}
+
+struct TemplateEntry {
+    std::string  name;
+    TemplateMeta meta;
+};
+
+// Enumerate templates/<name>/ entries of a package root (sorted by name).
+std::expected<std::vector<TemplateEntry>, std::string>
+list_templates(const std::filesystem::path& packageRoot) {
+    auto dir = packageRoot / "templates";
+    if (!std::filesystem::exists(dir)) {
+        return std::unexpected("package ships no templates/ directory");
+    }
+    std::vector<TemplateEntry> out;
+    std::error_code ec;
+    for (auto& e : std::filesystem::directory_iterator(dir, ec)) {
+        if (!e.is_directory()) continue;
+        auto meta = load_meta(e.path());
+        if (!meta) return std::unexpected(meta.error());
+        out.push_back({e.path().filename().string(), std::move(*meta)});
+    }
+    std::ranges::sort(out, {}, &TemplateEntry::name);
+    int defaults = 0;
+    for (auto& t : out) defaults += t.meta.isDefault ? 1 : 0;
+    if (defaults > 1) {
+        return std::unexpected(
+            "package declares more than one default template (template.toml "
+            "`default = true` must appear at most once)");
+    }
+    return out;
+}
+
+// The placeholder vocabulary is deliberately minimal and mcpp-owned;
+// template variability comes from packages shipping multiple templates,
+// not from growing the renderer into a programming language.
+struct RenderVars {
+    std::string projectName;
+    std::string selfName;
+    std::string selfVersion;
+};
+
+std::string render_text(std::string text, const RenderVars& vars) {
+    auto replace_all = [&](std::string_view from, std::string_view to) {
+        std::size_t pos = 0;
+        while ((pos = text.find(from, pos)) != std::string::npos) {
+            text.replace(pos, from.size(), to);
+            pos += to.size();
+        }
+    };
+    replace_all("{{project.name}}", vars.projectName);
+    replace_all("{{self.name}}",    vars.selfName);
+    replace_all("{{self.version}}", vars.selfVersion);
+    return text;
+}
+
+// Instantiate templateDir into destDir: `.in` files are rendered (suffix
+// stripped), everything else copied verbatim; template.toml is metadata
+// only and never copied.
+std::optional<std::string>
+instantiate(const std::filesystem::path& templateDir,
+            const std::filesystem::path& destDir,
+            const RenderVars& vars) {
+    std::error_code ec;
+    for (auto& e : std::filesystem::recursive_directory_iterator(templateDir, ec)) {
+        auto rel = std::filesystem::relative(e.path(), templateDir, ec);
+        if (rel == "template.toml") continue;
+        auto dest = destDir / rel;
+        if (e.is_directory()) {
+            std::filesystem::create_directories(dest, ec);
+            continue;
+        }
+        std::filesystem::create_directories(dest.parent_path(), ec);
+        if (rel.extension() == ".in") {
+            std::ifstream is(e.path());
+            std::stringstream ss; ss << is.rdbuf();
+            auto rendered = render_text(ss.str(), vars);
+            dest.replace_extension();      // strip ".in"
+            std::ofstream os(dest);
+            os << rendered;
+        } else {
+            std::filesystem::copy_file(
+                e.path(), dest,
+                std::filesystem::copy_options::overwrite_existing, ec);
+            if (ec) {
+                return std::format("copy '{}' failed: {}",
+                                   rel.string(), ec.message());
+            }
+        }
+    }
+    return std::nullopt;
+}
+
+// Ensure the generated manifest depends on the template's own package.
+// If the template already declares it (typically via {{self.version}}),
+// nothing is injected — template wins.
+std::optional<std::string>
+inject_self_dependency(const std::filesystem::path& manifestPath,
+                       const RenderVars& vars,
+                       const std::vector<std::string>& features) {
+    std::ifstream is(manifestPath);
+    if (!is) return std::format("cannot read '{}'", manifestPath.string());
+    std::stringstream ss; ss << is.rdbuf();
+    std::string content = ss.str();
+    is.close();
+
+    if (content.find(vars.selfName + " =") != std::string::npos
+        || content.find(vars.selfName + "=") != std::string::npos) {
+        return std::nullopt;   // already declared by the template
+    }
+
+    std::string depLine;
+    if (features.empty()) {
+        depLine = std::format("{} = \"{}\"\n", vars.selfName, vars.selfVersion);
+    } else {
+        std::string flist;
+        for (auto& f : features) {
+            if (!flist.empty()) flist += ", ";
+            flist += std::format("\"{}\"", f);
+        }
+        depLine = std::format("{} = {{ version = \"{}\", features = [{}] }}\n",
+                              vars.selfName, vars.selfVersion, flist);
+    }
+
+    constexpr std::string_view header = "[dependencies]";
+    if (auto pos = content.find(header); pos != std::string::npos) {
+        auto eol = content.find('\n', pos);
+        if (eol == std::string::npos) content += "\n" + depLine;
+        else content.insert(eol + 1, depLine);
+    } else {
+        if (!content.empty() && content.back() != '\n') content += '\n';
+        content += "\n[dependencies]\n" + depLine;
+    }
+
+    std::ofstream os(manifestPath);
+    os << content;
+    return std::nullopt;
+}
+
+} // namespace mcpp::scaffold
diff --git a/tests/e2e/69_package_templates.sh b/tests/e2e/69_package_templates.sh
new file mode 100755
index 00000000..e1b15c8e
--- /dev/null
+++ b/tests/e2e/69_package_templates.sh
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# 69_package_templates.sh — package-based `mcpp new --template` (design v2):
+# multi-level SPEC (bare pkg → default template | pkg:tmpl | pkg@ver:tmpl),
+# {{var}} rendering, [template.inject] features, --list-templates, errors.
+#
+# Hermetic: the package is pre-seeded into the home's install cache and the
+# index lua is written into the local official-index clone — no network.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+export MCPP_HOME="$TMP/home"
+mkdir -p "$MCPP_HOME"
+"$MCPP" self config --mirror "${MCPP_E2E_TOOLCHAIN_MIRROR:-GLOBAL}" >/dev/null 2>&1 || true
+
+# ── index entry (local official-index clone) ────────────────────────────
+mkdir -p "$MCPP_HOME/registry/data/mcpplibs/pkgs/t"
+cat > "$MCPP_HOME/registry/data/mcpplibs/pkgs/t/tpl-demo.lua" <<'EOF'
+package = {
+    spec      = "1",
+    namespace = "mcpplibs",
+    name      = "tpl-demo",
+    description = "template e2e fixture",
+    type      = "package",
+    xpm = {
+        linux = {
+            ["1.2.0"] = { url = "https://example.invalid/x.tar.gz", sha256 = "0" },
+            ["1.0.0"] = { url = "https://example.invalid/x.tar.gz", sha256 = "0" },
+        },
+        macosx = {
+            ["1.2.0"] = { url = "https://example.invalid/x.tar.gz", sha256 = "0" },
+            ["1.0.0"] = { url = "https://example.invalid/x.tar.gz", sha256 = "0" },
+        },
+        windows = {
+            ["1.2.0"] = { url = "https://example.invalid/x.tar.gz", sha256 = "0" },
+            ["1.0.0"] = { url = "https://example.invalid/x.tar.gz", sha256 = "0" },
+        },
+    },
+    mcpp = "src/*.cppm",
+}
+EOF
+
+# ── pre-seeded installed package (both versions) ────────────────────────
+seed_pkg() { # version, marker
+    local ver="$1" marker="$2"
+    local root="$MCPP_HOME/registry/data/xpkgs/mcpplibs-x-tpl-demo/$ver/tpl-demo-$ver"
+    mkdir -p "$root/src" "$root/templates/starter/src" "$root/templates/extra"
+    cat > "$root/mcpp.toml" <<EOF
+[package]
+name    = "tpl-demo"
+version = "$ver"
+EOF
+    echo "export module tpldemo;" > "$root/src/lib.cppm"
+
+    cat > "$root/templates/starter/template.toml" <<EOF
+[template]
+description  = "starter template ($marker)"
+default      = true
+post_message = "post-message-marker-$marker"
+
+[template.inject]
+self = { features = ["alpha", "beta"] }
+EOF
+    cat > "$root/templates/starter/mcpp.toml.in" <<'EOF'
+[package]
+name    = "{{project.name}}"
+version = "0.1.0"
+# from {{self.name}} {{self.version}}
+EOF
+    cat > "$root/templates/starter/src/main.cpp.in" <<'EOF'
+// {{project.name}} via {{self.name}}@{{self.version}}
+import std;
+int main() { std::println("{{project.name}}"); return 0; }
+EOF
+    echo "static-data" > "$root/templates/starter/NOTES.md"
+
+    cat > "$root/templates/extra/template.toml" <<EOF
+[template]
+description = "secondary template"
+EOF
+    cat > "$root/templates/extra/mcpp.toml.in" <<'EOF'
+[package]
+name    = "{{project.name}}"
+version = "0.1.0"
+
+[dependencies]
+tpl-demo = "{{self.version}}"
+EOF
+}
+seed_pkg 1.0.0 old
+seed_pkg 1.2.0 new
+
+WORK="$TMP/work"; mkdir -p "$WORK"; cd "$WORK"
+
+# 1. L0 bare package name → default template, latest version (1.2.0).
+"$MCPP" new app1 --template tpl-demo > out1.log 2>&1 || { cat out1.log; echo "L0 failed"; exit 1; }
+grep -q "tpl-demo@1.2.0:starter" out1.log || { cat out1.log; echo "missing resolved spec"; exit 1; }
+grep -q "post-message-marker-new" out1.log || { cat out1.log; echo "missing post_message"; exit 1; }
+grep -q 'name    = "app1"' app1/mcpp.toml || { echo "project.name not rendered"; exit 1; }
+grep -q "from tpl-demo 1.2.0" app1/mcpp.toml || { echo "self.* not rendered"; exit 1; }
+# inject with features (template did not declare the dep itself)
+grep -q 'tpl-demo = { version = "1.2.0", features = \["alpha", "beta"\] }' app1/mcpp.toml \
+    || { cat app1/mcpp.toml; echo "inject(features) missing"; exit 1; }
+[[ -f app1/NOTES.md ]] || { echo "verbatim copy missing"; exit 1; }
+[[ ! -f app1/template.toml ]] || { echo "template.toml must not be copied"; exit 1; }
+grep -q "app1 via tpl-demo@1.2.0" app1/src/main.cpp || { echo "main.cpp not rendered"; exit 1; }
+
+# 2. L3 fully explicit: pinned version + named template; template declares
+#    the dep itself via {{self.version}} → no duplicate injection.
+"$MCPP" new app2 --template tpl-demo@1.0.0:extra > out2.log 2>&1 || { cat out2.log; echo "L3 failed"; exit 1; }
+grep -q 'tpl-demo = "1.0.0"' app2/mcpp.toml || { cat app2/mcpp.toml; echo "self.version pin missing"; exit 1; }
+n=$(grep -c "tpl-demo" app2/mcpp.toml); [[ "$n" -eq 1 ]] || { cat app2/mcpp.toml; echo "duplicate injection"; exit 1; }
+
+# 3. --list-templates shows both, marks the default.
+"$MCPP" new --list-templates tpl-demo > list.log 2>&1 || { cat list.log; echo "list failed"; exit 1; }
+grep -q "starter" list.log && grep -q "extra" list.log || { cat list.log; echo "missing entries"; exit 1; }
+grep -q "(default)" list.log || { cat list.log; echo "default not marked"; exit 1; }
+
+# 4. Unknown template name → error listing alternatives.
+if "$MCPP" new app3 --template tpl-demo:nosuch > out4.log 2>&1; then
+    echo "unknown template must fail"; exit 1
+fi
+grep -q "starter" out4.log || { cat out4.log; echo "error must list alternatives"; exit 1; }
+
+# 5. Unknown package → clear index error.
+if "$MCPP" new app4 --template no-such-pkg-zz > out5.log 2>&1; then
+    echo "unknown package must fail"; exit 1
+fi
+grep -qi "not found in the index" out5.log || { cat out5.log; echo "missing index error"; exit 1; }
+
+# 6. builtin gui still works but prints the deprecation pointer.
+"$MCPP" new app6 --template gui > out6.log 2>&1 || { cat out6.log; echo "gui builtin broke"; exit 1; }
+grep -qi "deprecated" out6.log || { cat out6.log; echo "missing gui deprecation"; exit 1; }
+
+echo "OK"