simple-module-cli 0.0.11__tar.gz → 0.0.13__tar.gz

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: simple_module_cli
-Version: 0.0.11
-Summary: Standalone scaffolder for the SimpleModule framework — `sm new`, `sm create-module`, plugin host.
+Version: 0.0.13
+Summary: Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host.
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
 Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
@@ -34,7 +34,7 @@ pip install simple_module_cli
 # or, to keep the CLI in its own venv:
 pipx install simple_module_cli
 # or, to run it without installing:
-uvx --from simple_module_cli sm new my-app
+uvx --from simple_module_cli smpy new my-app
 ```
 
 The package depends only on `typer` and `tomlkit` — installing it does **not** pull in FastAPI, SQLModel, or any other framework runtime.
@@ -42,21 +42,21 @@ The package depends only on `typer` and `tomlkit` — installing it does **not**
 ## Usage
 
 ```bash
-sm new my-app                       # interactive wizard
-sm new my-app --yes --preset full   # all built-in modules + background jobs
-sm create-module my_feature         # scaffold a publishable module package
-sm create-host bare-host            # scaffold a bare host (no opinionated wiring)
+smpy new my-app                       # interactive wizard
+smpy new my-app --yes --preset full   # all built-in modules + background jobs
+smpy create-module my_feature         # scaffold a publishable module package
+smpy create-host bare-host            # scaffold a bare host (no opinionated wiring)
 ```
 
-Built-in commands: `sm new`, `sm create-host`, `sm create-module`.
+Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`.
 
 When other framework packages are installed, they contribute additional subcommands via the `simple_module_cli.cli_plugins` entry-point group:
 
 | Package | Commands |
 |---|---|
-| `simple_module_hosting` | `sm host gen-pages`, `sm host sync-js-deps` |
-| `simple_module_users`   | `sm users create-admin` |
-| `simple_module_settings` | `sm settings import-from-env` |
+| `simple_module_hosting` | `smpy host gen-pages`, `smpy host sync-js-deps` |
+| `simple_module_users`   | `smpy users create-admin` |
+| `simple_module_settings` | `smpy settings import-from-env` |
 
 ## License
 

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/README.md

@@ -9,7 +9,7 @@ pip install simple_module_cli
 # or, to keep the CLI in its own venv:
 pipx install simple_module_cli
 # or, to run it without installing:
-uvx --from simple_module_cli sm new my-app
+uvx --from simple_module_cli smpy new my-app
 ```
 
 The package depends only on `typer` and `tomlkit` — installing it does **not** pull in FastAPI, SQLModel, or any other framework runtime.
@@ -17,21 +17,21 @@ The package depends only on `typer` and `tomlkit` — installing it does **not**
 ## Usage
 
 ```bash
-sm new my-app                       # interactive wizard
-sm new my-app --yes --preset full   # all built-in modules + background jobs
-sm create-module my_feature         # scaffold a publishable module package
-sm create-host bare-host            # scaffold a bare host (no opinionated wiring)
+smpy new my-app                       # interactive wizard
+smpy new my-app --yes --preset full   # all built-in modules + background jobs
+smpy create-module my_feature         # scaffold a publishable module package
+smpy create-host bare-host            # scaffold a bare host (no opinionated wiring)
 ```
 
-Built-in commands: `sm new`, `sm create-host`, `sm create-module`.
+Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`.
 
 When other framework packages are installed, they contribute additional subcommands via the `simple_module_cli.cli_plugins` entry-point group:
 
 | Package | Commands |
 |---|---|
-| `simple_module_hosting` | `sm host gen-pages`, `sm host sync-js-deps` |
-| `simple_module_users`   | `sm users create-admin` |
-| `simple_module_settings` | `sm settings import-from-env` |
+| `simple_module_hosting` | `smpy host gen-pages`, `smpy host sync-js-deps` |
+| `simple_module_users`   | `smpy users create-admin` |
+| `simple_module_settings` | `smpy settings import-from-env` |
 
 ## License
 

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "simple_module_cli"
-version = "0.0.11"
-description = "Standalone scaffolder for the SimpleModule framework — `sm new`, `sm create-module`, plugin host."
+version = "0.0.13"
+description = "Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -25,7 +25,7 @@ dependencies = [
 ]
 
 [project.scripts]
-sm = "simple_module_cli.cli:main"
+smpy = "simple_module_cli.cli:main"
 simple-module = "simple_module_cli.cli:main"
 
 [project.urls]

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/simple_module_cli/app_project.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import json as _json
 import secrets as _secrets
+import shutil as _shutil
 from collections.abc import Sequence
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
@@ -26,6 +27,7 @@ from simple_module_cli.case import to_kebab_case, to_pascal_case
 from simple_module_cli.catalog import CATALOG, PRESETS, expand_deps
 from simple_module_cli.recipes import RECIPES, ScaffoldCtx
 from simple_module_cli.scaffolding import (
+    SAFE_PRESERVED_NAMES,
     _module_to_pypi_name,
     create_host,
     create_module,
@@ -55,7 +57,14 @@ def _resolve_framework_version() -> str:
 
 _FRAMEWORK_VERSION = _resolve_framework_version()
 
-_APP_PY_DEV_DEPS = [f"simple_module_test=={_FRAMEWORK_VERSION}", "pytest>=8.0"]
+# Pin ``simple_module_cli`` as a dev dep so ``uv run smpy`` resolves to the
+# project venv. The global ``uv tool`` install runs in its own isolated venv
+# that can't see the project's plugin entry points (issue #134).
+_APP_PY_DEV_DEPS = [
+    f"simple_module_test=={_FRAMEWORK_VERSION}",
+    f"simple_module_cli=={_FRAMEWORK_VERSION}",
+    "pytest>=8.0",
+]
 
 _APP_NPM_DEPS = {
     "@simple-module-py/ui": _FRAMEWORK_VERSION,
@@ -89,35 +98,39 @@ def create_app_project(
     tenancy: bool = False,
     selected: Sequence[str] | None = None,
     flat: bool = False,
-) -> None:
+) -> tuple[Path, list[Path]]:
     """Greenfield ``simple-module new`` scaffold.
 
-    In workspace mode (the default), lays down a uv + npm workspace at
-    ``target/`` with the host under ``target/host/`` and a sample module
-    under ``target/modules/hello/``. In flat mode (``flat=True``), keeps
-    the legacy single-host layout: host files at ``target/`` with no
-    ``modules/`` directory or workspace plumbing.
+    Workspace mode (default) lays down a uv + npm workspace at ``target/``
+    with the host under ``target/host/`` and a sample module under
+    ``target/modules/hello/``. Flat mode keeps the legacy single-host layout.
+    Tolerates ``SAFE_PRESERVED_NAMES`` at ``target`` (leftovers from
+    ``git init`` / ``gh repo create`` / IDE setup); other pre-existing
+    entries raise ``FileExistsError``.
 
-    Generates a secret, picks a DB URL, rewrites the host's
-    ``pyproject.toml`` / the relevant ``package.json`` to pin exact
-    framework versions, and applies any matching post-scaffold recipes
-    (e.g. the ``background_tasks`` recipe drops a Celery worker stack).
+    Returns ``(host_dir, preserved)`` — the host directory (``target`` in
+    flat mode, ``target/host`` in workspace mode) and the paths whose
+    scaffold copy was skipped because the user already had one.
     """
-    if target.exists() and any(target.iterdir()):
-        raise FileExistsError(
-            f"Destination {target} already exists and is non-empty; "
-            "choose a new path or remove its contents first."
-        )
-
     chosen = list(selected) if selected is not None else list(PRESETS["standard"])
     resolved, _added = expand_deps(chosen)
 
     display_names = [to_pascal_case(CATALOG[m].display) for m in resolved]
     host_dir = target if flat else target / "host"
+    preserved: list[Path] = []
     if not flat:
-        target.mkdir(parents=True, exist_ok=True)
-        create_workspace(target, name=name)
-    create_host(host_dir, name=name, modules=display_names, framework_version=_FRAMEWORK_VERSION)
+        preserved.extend(
+            create_workspace(target, name=name, preserve_existing=SAFE_PRESERVED_NAMES)
+        )
+    preserved.extend(
+        create_host(
+            host_dir,
+            name=name,
+            modules=display_names,
+            framework_version=_FRAMEWORK_VERSION,
+            preserve_existing=SAFE_PRESERVED_NAMES if flat else frozenset(),
+        )
+    )
     if not flat:
         _strip_workspace_owned_files(host_dir)
 
@@ -169,6 +182,8 @@ def create_app_project(
         if recipe_key is not None and recipe_key in RECIPES:
             RECIPES[recipe_key].apply(target, ctx)
 
+    return host_dir, preserved
+
 
 def _strip_workspace_owned_files(host_dir: Path) -> None:
     """Drop host copies of files the workspace root owns in workspace mode."""
@@ -181,6 +196,9 @@ def _scaffold_sample_module(target: Path) -> None:
     if sample_dest.exists():
         return
     create_module(sample_dest, name=_SAMPLE_MODULE_NAME)
+    # GitHub only reads workflows from the repo root, so the template's
+    # .github/ is dead inside a workspace.
+    _shutil.rmtree(sample_dest / ".github")
     _pin_sample_module_deps(sample_dest)
     _seed_static_dist_placeholder(sample_dest / _SAMPLE_MODULE_NAME / "static" / "dist")
 
@@ -195,7 +213,7 @@ def _seed_static_dist_placeholder(static_dist: Path) -> None:
 def _pin_sample_module_deps(sample_dest: Path) -> None:
     """Replace the module template's future-API range pins with exact pins.
 
-    The shared ``sm create-module`` template ships ``>=1.0,<2.0`` against the
+    The shared ``smpy create-module`` template ships ``>=1.0,<2.0`` against the
     framework's eventual stable line, but the workspace-bundled sample has to
     resolve against whatever the framework version actually is today (``==X``
     in pre-1.0). Without rewriting, ``uv sync`` can't satisfy the workspace.

simple_module_cli-0.0.13/simple_module_cli/case.py

@@ -0,0 +1,79 @@
+"""Identifier case-conversion helpers used by every scaffolder.
+
+Module/host names are accepted in any case style and normalized to the
+three forms the templates need: snake_case (Python package + entry-point
+key), kebab-case (PyPI slug), and PascalCase (display name in Meta).
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "InvalidScaffoldNameError",
+    "to_kebab_case",
+    "to_pascal_case",
+    "to_snake_case",
+    "validate_scaffold_name",
+]
+
+
+class InvalidScaffoldNameError(ValueError):
+    """Raised when a user-supplied scaffold name can't be canonicalized.
+
+    Names that mix case, lead with a digit, contain spaces or non
+    ``[a-z0-9_-]`` characters, or mix ``_`` and ``-`` separators within
+    the same identifier are ambiguous: the scaffolder would have to guess
+    a canonical form, and the directory name would diverge from the
+    READMEs that reference it. Reject up front instead.
+    """
+
+
+def to_snake_case(name: str) -> str:
+    """'MyFeature' / 'my-feature' / 'My Feature' / 'URLPath' -> 'my_feature' / 'url_path'.
+
+    Handles acronyms by treating ``Acronym|Word`` and ``word|Capital`` as
+    boundaries: ``URLPath`` -> ``url_path``, ``APIClient`` -> ``api_client``,
+    ``HTTPServer2`` -> ``http_server2``. The single-pass ``(?=[A-Z])`` form
+    that preceded this would emit ``u_r_l_path`` and propagate the typo
+    into the PyPI slug + display name.
+    """
+    s = re.sub(r"[\s\-]+", "_", name)
+    s = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", s)
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s)
+    return s.lower()
+
+
+def to_kebab_case(name: str) -> str:
+    """'MyFeature' / 'my_feature' -> 'my-feature' (used as the PyPI slug)."""
+    return to_snake_case(name).replace("_", "-")
+
+
+def to_pascal_case(name: str) -> str:
+    """'my-feature' / 'my_feature' -> 'MyFeature' (the display name in Meta)."""
+    snake = to_snake_case(name)
+    return "".join(part.capitalize() for part in snake.split("_") if part)
+
+
+_VALID_NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$")
+
+
+def validate_scaffold_name(name: str) -> str:
+    """Reject ambiguous host/module names; return the canonical display form.
+
+    A valid name is lowercase alphanumerics with at most one separator
+    style — either ``_`` or ``-``, not both. Examples:
+
+    * ``simple_module_chat`` -> ``simple_module_chat``
+    * ``simple-module-chat`` -> ``simple-module-chat``
+    * ``MyApp`` -> rejected (mixed case is ambiguous: ``my-app`` or ``my_app``?)
+    * ``1chat`` -> rejected (must start with a letter)
+    * ``foo_bar-baz`` -> rejected (mixed separators leave no canonical form)
+    """
+    if not name or not _VALID_NAME_RE.match(name) or ("_" in name and "-" in name):
+        raise InvalidScaffoldNameError(
+            f"{name!r} is not a valid scaffold name. Use lowercase letters and "
+            "digits with at most one separator style (all '_' or all '-'), "
+            "starting with a letter. e.g. 'my_app', 'my-app', or 'myapp'."
+        )
+    return name

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/simple_module_cli/cli.py

@@ -1,13 +1,13 @@
-"""Root `sm` Typer app — scaffolders + plugin mount.
+"""Root `smpy` Typer app — scaffolders + plugin mount.
 
 Built-in commands:
-  sm new
-  sm create-host
-  sm create-module
-  sm skills add / list / update
+  smpy new
+  smpy create-host
+  smpy create-module
+  smpy skills add / list / update
 
 Plugins discovered via the ``simple_module_cli.cli_plugins`` entry-point
-group are mounted as named subgroups (e.g. ``sm host gen-pages``).
+group are mounted as named subgroups (e.g. ``smpy host gen-pages``).
 """
 
 from __future__ import annotations
@@ -101,7 +101,7 @@ discover_and_mount(app)
 
 
 def main() -> None:
-    """Entry point for the `sm` console script."""
+    """Entry point for the `smpy` console script."""
     app()
 
 

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/simple_module_cli/new.py

@@ -1,4 +1,4 @@
-"""``sm new`` Typer command — flag-driven or interactive scaffolder."""
+"""``smpy new`` Typer command — flag-driven or interactive scaffolder."""
 
 from __future__ import annotations
 
@@ -11,11 +11,14 @@ from typing import Annotated
 import typer
 
 from simple_module_cli.app_project import create_app_project
+from simple_module_cli.case import InvalidScaffoldNameError, to_kebab_case, validate_scaffold_name
 from simple_module_cli.catalog import PRESETS, expand_deps
 from simple_module_cli.wizard import run_wizard
 
 __all__ = ["new_project"]
 
+_ALEMBIC = ("uv", "run", "alembic")
+
 
 class Db(StrEnum):
     sqlite = "sqlite"
@@ -61,7 +64,7 @@ def new_project(
         bool,
         typer.Option(
             "--no-install",
-            help="Skip 'uv sync' / 'npm install' / 'alembic upgrade head' after scaffolding.",
+            help=("Skip 'uv sync' / 'npm install' / initial alembic migration after scaffolding."),
         ),
     ] = False,
     flat: Annotated[
@@ -76,6 +79,14 @@ def new_project(
     ] = False,
 ) -> None:
     """Scaffold a new SimpleModule app, optionally with background jobs."""
+    try:
+        validate_scaffold_name(name)
+    except InvalidScaffoldNameError as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    pypi_name = to_kebab_case(name)
+    if pypi_name != name:
+        typer.echo(f"Normalizing PyPI name to {pypi_name!r}.")
     target = dest or Path.cwd() / name
     extra_list = [m.strip() for m in extra.split(",") if m.strip()]
     flag_driven = preset is not None or bool(extra_list)
@@ -100,7 +111,7 @@ def new_project(
             raise typer.Exit(code=1) from None
 
     try:
-        create_app_project(
+        host_dir, preserved = create_app_project(
             target,
             name=name,
             db=db_final,
@@ -114,12 +125,21 @@ def new_project(
 
     typer.echo(f"Created app '{name}' at {target}")
     typer.echo(f"Modules: {', '.join(resolved)}")
+    if preserved:
+        typer.echo(
+            "\nPreserved existing files (scaffold's versions were skipped — "
+            "merge by hand if you want their contents):"
+        )
+        for path in preserved:
+            rel = path.relative_to(target) if path.is_relative_to(target) else path
+            typer.echo(f"  {rel}")
     typer.echo("\nNext steps:")
     typer.echo(f"  cd {target}")
     if no_install:
         typer.echo("  uv sync")
         typer.echo("  npm install")
-        typer.echo("  alembic upgrade head")
+        typer.echo('  make migration msg="initial schema"')
+        typer.echo("  make migrate")
         typer.echo("  make dev")
         if "background_tasks" in resolved:
             typer.echo("  docker compose up -d redis worker beat   # background jobs")
@@ -143,7 +163,24 @@ def new_project(
             )
             return
 
-    subprocess.run(["uv", "run", "alembic", "upgrade", "head"], cwd=target, check=False)
+    _bootstrap_initial_migration(host_dir)
+    subprocess.run([*_ALEMBIC, "upgrade", "head"], cwd=host_dir, check=False)
     typer.echo("\nSetup complete. Run `make dev` in the new directory.")
     if "background_tasks" in resolved:
         typer.echo("For background jobs, also run: docker compose up -d redis worker beat")
+
+
+def _bootstrap_initial_migration(host_dir: Path) -> None:
+    """Autogenerate the baseline migration if the scaffold ships none.
+
+    Without a real revision, ``alembic upgrade head`` is a silent no-op
+    against an empty schema — the bundled modules' tables never exist.
+    """
+    versions_dir = host_dir / "migrations" / "versions"
+    if any(p.name != "__init__.py" for p in versions_dir.glob("*.py")):
+        return
+    subprocess.run(
+        [*_ALEMBIC, "revision", "--autogenerate", "-m", "initial schema"],
+        cwd=host_dir,
+        check=False,
+    )

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/simple_module_cli/package_update.py

@@ -1,4 +1,4 @@
-"""``sm package-update`` — bump simple_module_* deps to latest PyPI versions.
+"""``smpy package-update`` — bump simple_module_* deps to latest PyPI versions.
 
 Walks the project's ``pyproject.toml`` (and any ``[tool.uv.workspace]`` members),
 finds every dependency whose distribution name starts with ``simple_module_`` /

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/simple_module_cli/plugins.py

@@ -1,11 +1,11 @@
-"""Plugin discovery for ``sm`` via the ``simple_module_cli.cli_plugins`` group.
+"""Plugin discovery for ``smpy`` via the ``simple_module_cli.cli_plugins`` group.
 
 Each entry-point's value (``module:attr``) must resolve to a
 :class:`typer.Typer` instance. The entry-point name becomes the
-subcommand namespace under ``sm`` (e.g. ``sm host gen-pages``).
+subcommand namespace under ``smpy`` (e.g. ``smpy host gen-pages``).
 
 Failed loads (broken import, wrong type) print one line to stderr and
-are skipped — ``sm`` keeps working with whatever else loads.
+are skipped — ``smpy`` keeps working with whatever else loads.
 """
 
 from __future__ import annotations

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/simple_module_cli/recipes.py

@@ -1,6 +1,6 @@
 """Per-module post-scaffold recipes.
 
-A recipe is invoked by ``sm new`` after the base host scaffold lands. It
+A recipe is invoked by ``smpy new`` after the base host scaffold lands. It
 performs module-specific actions (write helper scripts, append Make
 targets, drop a docker-compose stack). The framework layer is kept free
 of devex concerns — recipes know about Makefiles and compose, framework
@@ -68,7 +68,7 @@ class BackgroundTasksRecipe:
             if path.exists():
                 raise FileExistsError(
                     f"{path} already exists — refusing to clobber. "
-                    "Remove the file or run `sm new` against an empty directory."
+                    "Remove the file or run `smpy new` against an empty directory."
                 )
 
         run_worker_dest.parent.mkdir(parents=True, exist_ok=True)

{simple_module_cli-0.0.11 → simple_module_cli-0.0.13}/simple_module_cli/scaffolding.py

@@ -21,15 +21,35 @@ import shutil
 from collections.abc import Mapping, Sequence
 from pathlib import Path
 
-from simple_module_cli.case import to_kebab_case, to_pascal_case, to_snake_case
-
-__all__ = ["create_host", "create_module", "create_workspace"]
+from simple_module_cli.case import (
+    to_kebab_case,
+    to_pascal_case,
+    to_snake_case,
+    validate_scaffold_name,
+)
+
+__all__ = [
+    "SAFE_PRESERVED_NAMES",
+    "create_host",
+    "create_module",
+    "create_workspace",
+]
 
 logger = logging.getLogger(__name__)
 
 _TEMPLATES_PACKAGE = "simple_module_cli.templates"
 _PACKAGE_PATH_TOKEN = "__PACKAGE__"
 
+# Pre-existing entries we tolerate at a scaffold target — typical leftovers
+# from ``git init`` / ``gh repo create`` / IDE setup.
+SAFE_PRESERVED_NAMES = frozenset(
+    {".git", ".gitignore", ".gitattributes", ".editorconfig", ".DS_Store"}
+    | {".claude", ".vscode", ".idea"}
+    | {"README", "README.md", "README.rst"}
+    | {"LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"}
+    | {"CHANGELOG.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md"}
+)
+
 
 def _module_to_pypi_name(name: str) -> str:
     return f"simple_module_{name.lower()}"
@@ -45,12 +65,21 @@ def _iter_template_files(template_root: Path):
         yield path
 
 
-def _require_empty_dest(dest: Path) -> None:
-    if dest.exists() and any(dest.iterdir()):
-        raise FileExistsError(
-            f"Destination {dest} already exists and is non-empty. "
-            "Choose a new path or remove the contents first."
-        )
+def _require_empty_dest(dest: Path, *, preserve_existing: frozenset[str] = frozenset()) -> None:
+    """Refuse a non-empty destination unless every top-level entry is allowed.
+
+    ``preserve_existing`` is matched against the *name* of each top-level entry,
+    so callers can permit common pre-existing files (``.git``, ``README.md``,
+    ...) without silently overwriting unrelated user content.
+    """
+    if dest.exists():
+        unexpected = sorted(p.name for p in dest.iterdir() if p.name not in preserve_existing)
+        if unexpected:
+            raise FileExistsError(
+                f"Destination {dest} exists and contains files that would collide "
+                f"with the scaffold: {', '.join(unexpected)}. "
+                "Move them aside or choose another path."
+            )
     dest.mkdir(parents=True, exist_ok=True)
 
 
@@ -66,13 +95,20 @@ def _apply_template_files(
     substitutions: Mapping[str, str],
     *,
     path_rewrites: Mapping[str, str] | None = None,
-) -> None:
+    preserve_existing: frozenset[str] = frozenset(),
+) -> list[Path]:
+    """Write template files into ``dest``; return paths skipped to preserve the user's copy."""
+    preserved: list[Path] = []
     for src in _iter_template_files(src_root):
         rel_str = str(src.relative_to(src_root))
         for old, new in (path_rewrites or {}).items():
             rel_str = rel_str.replace(old, new)
         rel_str = rel_str.removesuffix(".tpl")
         target = dest / rel_str
+        top = Path(rel_str).parts[0] if rel_str else ""
+        if top in preserve_existing and target.exists():
+            preserved.append(target)
+            continue
         target.parent.mkdir(parents=True, exist_ok=True)
         if src.suffix == ".tpl":
             text = src.read_text(encoding="utf-8")
@@ -81,29 +117,41 @@ def _apply_template_files(
             target.write_text(text, encoding="utf-8")
         else:
             shutil.copy2(src, target)
+    return preserved
 
 
 def create_workspace(
     dest: Path,
     name: str,
     template_root: Path | None = None,
-) -> Path:
-    """Materialize the workspace-root shell at ``dest``.
+    *,
+    preserve_existing: frozenset[str] = frozenset(),
+) -> list[Path]:
+    """Materialize the workspace-root shell at ``dest``; return preserved paths.
 
     Lays down the top-level ``pyproject.toml`` (uv workspace), ``package.json``
     (npm workspace), ``Makefile`` (delegates to host), ``.env.example``,
     ``.gitignore``, and ``README.md``. Does NOT create the host or any
     modules — those go under ``dest/host`` and ``dest/modules/`` afterwards.
+
+    ``preserve_existing`` lists top-level entry names that may already exist
+    in ``dest``; the scaffold's copy is skipped and the preserved path is
+    included in the returned list. Other pre-existing entries raise
+    ``FileExistsError``.
     """
     dest = Path(dest)
-    dest.mkdir(parents=True, exist_ok=True)
-    _apply_template_files(
+    _require_empty_dest(dest, preserve_existing=preserve_existing)
+    preserved = _apply_template_files(
         _resolve_template_root("workspace", template_root),
         dest,
-        {"{{HOST_NAME}}": to_kebab_case(name)},
+        {
+            "{{HOST_NAME}}": validate_scaffold_name(name),
+            "{{HOST_PYPI_NAME}}": to_kebab_case(name),
+        },
+        preserve_existing=preserve_existing,
     )
     logger.info("Scaffolded workspace root at %s", dest)
-    return dest
+    return preserved
 
 
 def create_host(
@@ -112,23 +160,31 @@ def create_host(
     modules: Sequence[str],
     template_root: Path | None = None,
     framework_version: str = "*",
-) -> Path:
+    *,
+    preserve_existing: frozenset[str] = frozenset(),
+) -> list[Path]:
+    """Scaffold a host project at ``dest``; return preserved pre-existing paths.
+
+    ``preserve_existing`` semantics match :func:`create_workspace`.
+    """
     dest = Path(dest)
-    _require_empty_dest(dest)
+    _require_empty_dest(dest, preserve_existing=preserve_existing)
     module_dep_lines = "\n".join(f'    "{_module_to_pypi_name(m)}>=0.1,<1.0",' for m in modules)
-    _apply_template_files(
+    preserved = _apply_template_files(
         _resolve_template_root("host", template_root),
         dest,
         {
-            "{{HOST_NAME}}": name,
+            "{{HOST_NAME}}": validate_scaffold_name(name),
+            "{{HOST_PYPI_NAME}}": to_kebab_case(name),
             "{{MODULE_DEPS}}": module_dep_lines,
             "{{FRAMEWORK_VERSION}}": framework_version,
         },
+        preserve_existing=preserve_existing,
     )
     logger.info(
         "Scaffolded host '%s' at %s (modules: %s)", name, dest, ", ".join(modules) or "<none>"
     )
-    return dest
+    return preserved
 
 
 def create_module(