salpa-cli 0.1.2__py3-none-any.whl

bocoflow_cli/__init__.py

@@ -0,0 +1,8 @@
+"""BoCoFlow node authoring CLI."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("salpa-cli")
+except PackageNotFoundError:  # running from a source tree without an installed dist
+    __version__ = "0.0.0+dev"

bocoflow_cli/cli.py

@@ -0,0 +1,248 @@
+"""salpa — the Salpa node authoring CLI (also runnable as `bocoflow`).
+
+v1 surface is `salpa new` (scaffold a node package). The `publish` / `install`
+/ `run` verbs are reserved for later and intentionally not implemented yet.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+
+from . import __version__
+from .docs import DocsError, available_docs, read_doc
+from .scaffold import (
+    ScaffoldError,
+    ScaffoldSpec,
+    available_templates,
+    default_hashtags,
+    scaffold,
+    to_pascal_case,
+)
+
+app = typer.Typer(
+    add_completion=False,
+    help="Salpa node authoring CLI. Scaffold node packages that match the "
+    "shipped template contract.",
+    no_args_is_help=True,
+)
+console = Console()
+
+_TEMPLATE_HELP = {
+    "individual-node": "one node, its own pixi env (the default)",
+    "multi-node-package": "several related nodes sharing one pixi env, chained",
+    "cloud-modal-node": "a cloud client stub",
+}
+
+# Templates not shown in the interactive menu + --help. Still scaffoldable via an
+# explicit `-t <name>`. Remove a name from this set to surface it in the menu.
+_HIDDEN_TEMPLATES = {"cloud-modal-node"}
+
+
+def _ordered_templates() -> list[str]:
+    """Available templates in a sensible order (individual-node first — the
+    default), not alphabetical, so the interactive menu's default (choice 1)
+    matches the --template flag default and isn't the niche cloud stub."""
+    order = list(_TEMPLATE_HELP)
+    avail = available_templates()
+    return sorted(avail, key=lambda t: order.index(t) if t in order else len(order))
+
+
+def _menu_templates() -> list[str]:
+    """Templates offered in the interactive menu + --help — ordered, minus the hidden
+    ones. An explicit ``-t`` still accepts any available template."""
+    return [t for t in _ordered_templates() if t not in _HIDDEN_TEMPLATES]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"salpa {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Salpa node authoring CLI."""
+
+
+@app.command()
+def new(
+    name: str = typer.Argument(None, help="Package name (kebab-case, e.g. my-analyzer)."),
+    template: str = typer.Option(
+        None, "--template", "-t",
+        help=f"Template: {', '.join(_menu_templates())}.",
+    ),
+    description: str = typer.Option(None, "--description", "-d", help="One-line description."),
+    author: str = typer.Option(None, "--author", help="Author name."),
+    category: str = typer.Option(None, "--category", help="UI category, e.g. 'Cheminformatics'."),
+    hashtags: str = typer.Option(
+        None, "--hashtags", help="Comma-separated discovery hashtags, 5-10 (e.g. 'md,gromacs,protein').",
+    ),
+    output: Path = typer.Option(
+        Path("."), "--output", "-o", help="Directory to create the package in.",
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Non-interactive: accept defaults, no prompts.",
+    ),
+    install: bool = typer.Option(
+        False, "--install", help="Run `pixi install` in the new package afterwards.",
+    ),
+) -> None:
+    """Scaffold a new Salpa node package.
+
+    With no options it prompts interactively (create-next-app style); pass flags
+    and/or --yes to script it. The directory is created with underscores (the dir
+    name becomes the Python package name); meta.toml's name stays kebab-case.
+    """
+    templates = _menu_templates()
+
+    if not yes:
+        if not name:
+            name = Prompt.ask("[bold]Package name[/] (kebab-case)")
+        if not template:
+            console.print("\n[bold]Template[/]:")
+            for i, t in enumerate(templates, 1):
+                console.print(f"  {i}. [cyan]{t}[/] — {_TEMPLATE_HELP.get(t, '')}")
+            choice = Prompt.ask(
+                "Choose", choices=[str(i) for i in range(1, len(templates) + 1)], default="1",
+            )
+            template = templates[int(choice) - 1]
+        if description is None:
+            description = Prompt.ask("Short description", default="") or None
+        if author is None:
+            author = Prompt.ask("Author", default="TODO")
+        if category is None:
+            category = Prompt.ask("Category", default="TODO Category")
+        if hashtags is None:
+            suggested = ", ".join(default_hashtags(name, category or "TODO Category"))
+            hashtags = Prompt.ask("Hashtags (comma-separated, 5-10)", default=suggested)
+        if not install:
+            install = Confirm.ask("Run `pixi install` after scaffolding?", default=False)
+
+    if not name:
+        console.print("[red]A package name is required.[/] Pass it as an argument or drop --yes.")
+        raise typer.Exit(1)
+
+    tag_list = [t.strip() for t in hashtags.split(",") if t.strip()] if hashtags else None
+
+    spec = ScaffoldSpec(
+        name=name,
+        template=template or "individual-node",
+        description=description,
+        author=author or "TODO",
+        category=category or "TODO Category",
+        hashtags=tag_list,
+    )
+
+    try:
+        dest = scaffold(spec, output.resolve())
+    except ScaffoldError as e:
+        console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1)
+
+    console.print(
+        Panel(
+            f"[green]Created[/] [bold]{dest}[/]\n"
+            f"class: [cyan]{to_pascal_case(name)}[/]   template: [cyan]{spec.template}[/]",
+            title="salpa new",
+            border_style="green",
+        )
+    )
+    _next_steps(spec.template, dest)
+
+    if install:
+        _pixi_install(dest, spec.template)
+
+
+@app.command()
+def docs(
+    name: str = typer.Argument(None, help="Doc to print (omit to list the bundled docs)."),
+) -> None:
+    """Show the node-authoring docs bundled with this CLI."""
+    try:
+        if not name:
+            console.print(
+                "[bold]Bundled docs[/] — print one with [cyan]salpa docs <name>[/]:\n"
+            )
+            for doc in available_docs():
+                summary = ""
+                for line in read_doc(doc).splitlines():
+                    if line.startswith("#"):
+                        summary = line.lstrip("# ").strip()
+                        break
+                console.print(f"  [cyan]{doc}[/]  —  {summary}")
+            console.print(
+                "\nFull docs: [underline]https://salpa.app/docs/custom-nodes[/]"
+            )
+            return
+        console.print(Markdown(read_doc(name)))
+    except DocsError as e:
+        console.print(f"[red]{e}[/]")
+        raise typer.Exit(1)
+
+
+def _next_steps(template: str, dest: Path) -> None:
+    lines: list[str]
+    if template == "multi-node-package":
+        lines = [
+            "Rename node_one/ and node_two/ to real names (underscored dirs); keep each",
+            "  meta.toml class_name in sync with its node.py class.",
+            "List every node in package.toml [package.nodes]; set a unique [package].name",
+            "  and the same shared_environment in each node's meta.toml.",
+            "Put the science in each node's core.py; keep node.py a thin wrapper.",
+            "pixi install  →  pixi run test   (core tests run; node tests skip — expected)",
+        ]
+    elif template == "cloud-modal-node":
+        lines = [
+            "Edit meta.toml — description, hashtags, endpoint.",
+            "Point node.py at your deployed service (no pixi.toml needed).",
+            "Test against the deployed service.",
+        ]
+    else:
+        lines = [
+            "Edit meta.toml — description, category, hashtags, license.",
+            "Put the science in core.py; keep node.py a thin wrapper.",
+            "Edit pixi.toml — declare only platforms your deps build for (pixi solves all).",
+            "pixi install  →  pixi run test   (core tests run; node tests skip — expected)",
+        ]
+    console.print("[bold]Next steps[/]:")
+    for i, line in enumerate(lines, 1):
+        # markup=False: these lines contain literal [package.nodes]/[package].name,
+        # which Rich would otherwise parse as style tags and eat.
+        console.print(f"  {i}. {line}", markup=False)
+    # publish/install aren't CLI verbs yet (v1 is `new` only) — point at the bundled
+    # authoring docs so a newcomer isn't left guessing after scaffolding.
+    console.print(
+        "\n[dim]More: run `salpa docs` for the bundled authoring guides, or see "
+        "https://salpa.app/docs/custom-nodes[/dim]"
+    )
+
+
+def _pixi_install(dest: Path, template: str) -> None:
+    # Multi-node packages install their shared env from the package root; single
+    # node / cloud stub install in place. cloud-modal-node has no pixi.toml.
+    if template == "cloud-modal-node" or not (dest / "pixi.toml").exists():
+        console.print("[yellow]Skipping pixi install[/] (no pixi.toml in this template).")
+        return
+    console.print("Running [cyan]pixi install[/]…")
+    try:
+        subprocess.run(["pixi", "install"], cwd=dest, check=True)
+    except FileNotFoundError:
+        console.print("[yellow]pixi not found in PATH — skipped.[/]")
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]pixi install failed[/] (exit {e.returncode}).")
+
+
+if __name__ == "__main__":
+    app()

bocoflow_cli/docs/README.md

@@ -0,0 +1,13 @@
+# Salpa node authoring — bundled docs
+
+These are the authoring docs that ship with the Salpa CLI. They cover what you need to take a node
+from `salpa new` to a package that runs in Salpa. Print one with `salpa docs <name>`, or read
+them here.
+
+| Doc | What it covers |
+|-----|----------------|
+| [node-package-structure](node-package-structure.md) | The anatomy of a single node — `meta.toml`, `core.py`, `node.py`, `pixi.toml`, and the two-level split. |
+| [multi-node-packages](multi-node-packages.md) | Bundling several related nodes that share one environment (`package.toml` + a shared env). |
+| [testing-and-loading-your-node](testing-and-loading-your-node.md) | Running the tests, then loading a finished node into Salpa. |
+
+Full docs, always up to date: <https://salpa.app/docs/custom-nodes>

bocoflow_cli/docs/multi-node-packages.md

@@ -0,0 +1,46 @@
+# Multi-node packages
+
+When you have several related nodes that share the same dependencies, bundle them into one package
+with a single shared environment instead of repeating the environment per node.
+
+```
+salpa new my-suite -t multi-node-package
+```
+
+## Layout
+
+```
+my_suite/
+├── package.toml       # the manifest — its PRESENCE marks a multi-node package
+├── pixi.toml          # ONE shared environment for every node in the package
+├── node_one/
+│   ├── meta.toml      # no [dependencies] block — deps live in the root pixi.toml
+│   ├── core.py
+│   └── node.py
+├── node_two/
+│   └── ...
+└── workflows/         # an optional bundled example pipeline
+```
+
+## `package.toml`
+
+The manifest is what tells the registry and the app that this is a multi-node package (rather than a
+single node). It carries:
+
+- `[package]` — a unique `name` (kebab-case) and the list of nodes under `[package.nodes]`.
+- a `shared_environment` name that **every** node's `meta.toml` must also declare — that's how the
+  nodes are wired to the one root environment.
+
+## Shared environment
+
+There is **one** `pixi.toml`, at the package root, with all the dependencies. Each node directory has
+a `meta.toml` (with `shared_environment = "<name>"`) plus its own `core.py` / `node.py`, but **no**
+per-node `pixi.toml`. Run `pixi install` + `pixi run test` once, from the package root.
+
+To isolate a single node that has a conflicting dependency, give it its own `pixi.toml` and drop the
+`shared_environment` line from that node's `meta.toml`.
+
+## Next
+
+- Node anatomy: [node-package-structure](node-package-structure.md)
+- [Testing and loading your node](testing-and-loading-your-node.md)

bocoflow_cli/docs/node-package-structure.md

@@ -0,0 +1,75 @@
+# Node package structure
+
+A Salpa node is a small Python package — a directory (with an underscored name, so it imports
+cleanly) that `salpa new` scaffolds for you:
+
+```
+protein_analyzer/
+├── meta.toml     # metadata the node registry reads to discover your node
+├── core.py       # the science — plain Python, testable on its own
+├── node.py       # a thin wrapper: parameters + an execute() that calls core.py
+├── pixi.toml     # an isolated, reproducible environment for your dependencies
+├── README.md     # what the node does
+└── tests/        # a starting test suite
+```
+
+## The two-level split
+
+The single most important idea: **keep the science and the app integration separate.**
+
+- **`core.py`** is pure Python. It knows nothing about Salpa — just functions that take inputs and
+  return outputs. You can unit-test it without the app installed.
+- **`node.py`** is a thin wrapper. It declares the node's parameters, and its `execute()` reads those
+  parameters, calls into `core.py`, and shapes the result. It is the only file that imports the
+  runtime.
+
+That split is why `pixi run test` can exercise `core.py` in a bare environment (the science has all
+its deps) while the `node.py` tests skip (they need the running app) — expected, not a failure.
+
+## `meta.toml`
+
+The registry reads this file to discover your node. Key sections:
+
+- `[package]` — `name` (kebab-case, globally unique), `version`, `description`, `author`, and
+  `license` (**required** — a node with no license is skipped at load and never shows in the palette).
+- `[node]` — `class_name` (must match the class in `node.py`), `display_name`, `num_in` / `num_out`
+  (input/output ports), and `category`.
+- `hashtags` — 5–10 lowercase-with-hyphens tags that drive discovery. Be specific.
+- `[node.metadata]` — an emoji `icon` and a short `tooltip`.
+- `[node.features]` — flags like `requires_gpu`, `long_running`.
+
+## `node.py`
+
+Your node is a subclass of `Node` from the runtime:
+
+```python
+from bocoflow_core.node import Node, NodeException, NodeResult
+from bocoflow_core.parameters import TextParameter, FileParameterEdit, FolderParameter
+# Also available: StringParameter, IntegerParameter, FloatParameter, BooleanParameter, SelectParameter
+```
+
+Two things to fill in:
+
+- **`OPTIONS`** — a dict of the parameters the user sees in the UI. Each value is a `Parameter`.
+  (Don't add `force_to_run` — it's inherited.)
+- **`execute(self, predecessor_data, flow_vars)`** — read parameters with
+  `flow_vars["name"].get_value()`, call your `core.py`, write any output files, and return a
+  `NodeResult` as JSON (`result.to_json()`). Raise `NodeException(stage, message)` on failure.
+
+`predecessor_data` is the list of result dicts from upstream nodes, so a node can carry data forward
+through a pipeline.
+
+## `pixi.toml`
+
+Defines the node's isolated environment (via [pixi](https://pixi.sh/)):
+
+- Declare **only** the platforms your dependencies build for — pixi solves all of them.
+- Put dependencies under `[dependencies]` (prefer conda-forge). Keep `pytest` in the default
+  environment so `pixi run test` works, and keep `redis-py` so live progress logs reach the UI.
+- Do **not** add `bocoflow_core` here — the Salpa runtime provides it. That's exactly why
+  `pixi run test` can import `core.py` but not `node.py`.
+
+## Next
+
+- [Testing and loading your node](testing-and-loading-your-node.md)
+- Several related nodes? See [multi-node packages](multi-node-packages.md).

bocoflow_cli/docs/testing-and-loading-your-node.md

@@ -0,0 +1,36 @@
+# Testing and loading your node
+
+## Test it
+
+From the package directory (or the package root, for a multi-node package):
+
+```
+pixi install        # build the isolated environment
+pixi run test       # run the tests
+```
+
+You'll see the `core.py` tests pass and the `node.py` tests **skip** — the node tests need the
+running Salpa app, so they're expected to skip in this bare environment (`pixi run test` prints the
+skip reasons). A green `core.py` suite means your science is sound.
+
+Write your tests in `tests/`, and keep testing `core.py` directly — that's the fast, reliable loop.
+
+## Load it into Salpa
+
+Once the tests are green:
+
+1. Open Salpa and go to the node library.
+2. Use **Import** (Local Source) and point it at your package directory.
+3. Salpa reads `meta.toml`, installs the node's environment, and the node appears in the palette
+   under its `category`.
+4. Drop it on the canvas and run it.
+
+If you change the node, re-import (or refresh) to pick up the changes.
+
+## Iterate
+
+- Edit `core.py`, re-run `pixi run test`.
+- Adjust parameters or the result shape in `node.py`.
+- Update `meta.toml` (description, hashtags, category) so the node is easy to find.
+
+Full, always-current docs: <https://salpa.app/docs/custom-nodes>

bocoflow_cli/docs.py

@@ -0,0 +1,44 @@
+"""Locate + read the node-authoring docs bundled with the CLI.
+
+Same dev/installed resolution as ``scaffold.templates_dir()``: the docs live at the repo root
+(``docs/``) for dev runs, and are force-included into the wheel under ``bocoflow_cli/docs`` so
+``importlib.resources`` finds them once pip-installed.
+"""
+
+from __future__ import annotations
+
+import importlib.resources as ir
+from pathlib import Path
+
+
+class DocsError(Exception):
+    """The bundled docs could not be located, or a requested doc was not found."""
+
+
+def docs_dir() -> Path:
+    """Locate the bundled docs in dev (repo root) and installed (wheel) layouts."""
+    repo = Path(__file__).resolve().parents[2] / "docs"
+    if repo.is_dir():
+        return repo
+    packaged = ir.files("bocoflow_cli") / "docs"
+    if packaged.is_dir():  # type: ignore[union-attr]
+        return Path(str(packaged))
+    raise DocsError("Bundled docs not found (looked in repo root and package data).")
+
+
+def available_docs() -> list[str]:
+    """Doc names (without the .md suffix) — README first, then alphabetical."""
+    names = sorted(p.stem for p in docs_dir().glob("*.md"))
+    if "README" in names:
+        names.remove("README")
+        names.insert(0, "README")
+    return names
+
+
+def read_doc(name: str) -> str:
+    """Return the text of a bundled doc. ``name`` may omit the .md suffix."""
+    stem = name[:-3] if name.endswith(".md") else name
+    path = docs_dir() / f"{stem}.md"
+    if not path.is_file():
+        raise DocsError(f"No doc named {name!r}. Available: {', '.join(available_docs())}.")
+    return path.read_text(encoding="utf-8")

bocoflow_cli/scaffold.py

@@ -0,0 +1,184 @@
+"""Scaffold a Salpa node package from a bundled template.
+
+Pure logic — no Typer/Rich here so it stays unit-testable. Guarantees:
+underscored directory names (the directory becomes the Python package name, so
+a hyphen breaks `from .core import ...`), every placeholder substituted (an
+unlisted one is a hard error, not a silently-broken package), placeholder-named
+files renamed, and the template's own usage doc stripped.
+"""
+
+from __future__ import annotations
+
+import importlib.resources as ir
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+TEMPLATES = ("individual-node", "multi-node-package", "cloud-modal-node")
+
+_KEBAB = re.compile(r"^[a-z][a-z0-9-]*$")
+_SUBST_SUFFIXES = {".toml", ".py", ".md", ".json"}
+
+
+class ScaffoldError(Exception):
+    """A scaffold could not be produced (bad name, missing template, etc.)."""
+
+
+def templates_dir() -> Path:
+    """Locate the bundled templates in dev and installed layouts.
+
+    Dev/repo run: <repo>/templates (this file is src/bocoflow_cli/scaffold.py).
+    Installed wheel: force-included under the package as bocoflow_cli/templates.
+    """
+    repo = Path(__file__).resolve().parents[2] / "templates"
+    if repo.is_dir():
+        return repo
+    packaged = ir.files("bocoflow_cli") / "templates"
+    if packaged.is_dir():  # type: ignore[union-attr]
+        return Path(str(packaged))
+    raise ScaffoldError("Bundled templates not found (looked in repo root and package data).")
+
+
+def available_templates() -> list[str]:
+    root = templates_dir()
+    return sorted(p.name for p in root.iterdir() if p.is_dir())
+
+
+def to_pascal_case(kebab: str) -> str:
+    return "".join(part[:1].upper() + part[1:] for part in kebab.split("-"))
+
+
+def to_title_case(kebab: str) -> str:
+    return " ".join(part[:1].upper() + part[1:] for part in kebab.split("-"))
+
+
+def default_hashtags(name: str, category: str) -> list[str]:
+    """A sensible starter hashtag list — the name's words plus the category slug.
+
+    Beats the old ``[name, "todo-domain"]`` (which shipped a literal TODO), and
+    is what the interactive prompt offers as its default. Still meant to be
+    expanded toward the 5-10 the template comment recommends.
+    """
+    tags = [part for part in name.split("-") if part]
+    slug = category.strip().lower().replace(" ", "-")
+    if slug and slug not in {"todo-category", "todo"} and slug not in tags:
+        tags.append(slug)
+    return tags
+
+
+def validate_name(name: str) -> None:
+    if not _KEBAB.match(name):
+        raise ScaffoldError(
+            f"Node name must be kebab-case (lowercase, hyphens): got {name!r}.\n"
+            "  Valid:   my-new-node, protein-analyzer\n"
+            "  Invalid: MyNode, my_node, 123-node"
+        )
+
+
+@dataclass
+class ScaffoldSpec:
+    name: str  # kebab-case package name
+    template: str = "individual-node"
+    description: str | None = None
+    author: str = "TODO"
+    category: str = "TODO Category"
+    hashtags: list[str] | None = None  # None → derived from name + category
+
+    def substitutions(self) -> dict[str, str]:
+        cls = to_pascal_case(self.name)
+        disp = to_title_case(self.name)
+        desc = self.description or f"TODO: one-line description of {self.name}"
+        dir_name = self.name.replace("-", "_")
+        tags = self.hashtags or default_hashtags(self.name, self.category)
+        # Every placeholder any template uses must appear here — an unlisted one is
+        # copied through literally and caught by the guard in `scaffold`.
+        return {
+            "PACKAGE_NAME": self.name,
+            "CLASS_NAME": cls,
+            "DISPLAY_NAME": disp,
+            "DESCRIPTION": desc,
+            "PACKAGE_DESCRIPTION": desc,
+            "AUTHOR": self.author,
+            "GITHUB_USER": "your-org",
+            "CATEGORY": self.category,
+            # Expands inside a TOML/JSON list: hashtags = [{{HASHTAGS}}] →
+            # hashtags = ["a", "b", "c"]. Value is the quoted, comma-joined body.
+            "HASHTAGS": ", ".join(f'"{t}"' for t in tags),
+            "ENDPOINT_SLUG": self.name,
+            "SHARED_ENV": dir_name,
+            "NODE1_CLASS_NAME": f"{cls}One",
+            "NODE1_DISPLAY_NAME": f"{disp} One",
+            "NODE1_DESCRIPTION": "TODO: what the first node does",
+            "NODE2_CLASS_NAME": f"{cls}Two",
+            "NODE2_DISPLAY_NAME": f"{disp} Two",
+            "NODE2_DESCRIPTION": "TODO: what the second node does",
+        }
+
+
+def _apply_substitutions(text: str, subs: dict[str, str]) -> str:
+    return re.sub(
+        r"\{\{([A-Z0-9_]+)\}\}",
+        lambda m: subs.get(m.group(1), m.group(0)),
+        text,
+    )
+
+
+def scaffold(spec: ScaffoldSpec, out_dir: Path) -> Path:
+    """Create the package under out_dir/<under_scored_name>/ and return its path."""
+    validate_name(spec.name)
+    if spec.template not in available_templates():
+        raise ScaffoldError(
+            f"Unknown template {spec.template!r}. Available: {', '.join(available_templates())}"
+        )
+
+    src = templates_dir() / spec.template
+    dir_name = spec.name.replace("-", "_")  # underscores — see module docstring
+    dest = out_dir / dir_name
+    if dest.exists():
+        raise ScaffoldError(f"Destination already exists: {dest}")
+
+    # Never carry template build junk into a scaffold. If someone ran Python or
+    # pixi inside a template dir, a stray .pyc (compiled from a template core.py)
+    # still holds the {{PLACEHOLDER}} docstring bytes and would trip the guard
+    # below / ship in the wheel. (Found by the new-user trial, 2026-07-18.)
+    shutil.copytree(
+        src, dest,
+        ignore=shutil.ignore_patterns(
+            "__pycache__", "*.pyc", ".pixi", "pixi.lock", ".pytest_cache",
+            ".coverage", ".DS_Store",
+        ),
+    )
+    (dest / "_TEMPLATE_USAGE.md").unlink(missing_ok=True)
+
+    subs = spec.substitutions()
+
+    # Substitute file contents.
+    for path in dest.rglob("*"):
+        if path.is_file() and path.suffix in _SUBST_SUFFIXES:
+            path.write_text(_apply_substitutions(path.read_text(encoding="utf-8"), subs),
+                            encoding="utf-8")
+
+    # Rename placeholder-named files (e.g. workflows/{{PACKAGE_NAME}}-pipeline.json).
+    # Deepest-first so a renamed parent can't invalidate a child path mid-loop.
+    for path in sorted(dest.rglob("*{{*}}*"), key=lambda p: len(p.parts), reverse=True):
+        new = path.parent / _apply_substitutions(path.name, subs)
+        if new != path:
+            path.rename(new)
+
+    # Fail loudly rather than emit a half-substituted package.
+    leftover: set[str] = set()
+    for path in dest.rglob("*"):
+        if path.is_file() and path.suffix in _SUBST_SUFFIXES:
+            leftover |= set(re.findall(r"\{\{[A-Z0-9_]+\}\}", path.read_text(encoding="utf-8")))
+        if "{{" in path.name:
+            leftover.add(path.name)
+    if leftover:
+        shutil.rmtree(dest, ignore_errors=True)
+        raise ScaffoldError(
+            "Unsubstituted placeholders remained: "
+            + ", ".join(sorted(leftover))
+            + "\nAdd them to ScaffoldSpec.substitutions()."
+        )
+
+    return dest