simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/instructions.py

@@ -0,0 +1,152 @@
+"""Assemble the instruction file a generated project receives, and the three files written from it.
+
+A template's `AGENTS.md` is half a file. The generic Cadmould rules are authored once in
+`templates/_shared/AGENTS.base.md`; the template's own half describes only its workflow.
+The file a customer's assistant actually reads therefore exists nowhere on disk in this
+repository — it is produced here, and this module is the only place that join happens.
+
+Two of the three derived files are one-line imports and the third is a byte copy, and
+that asymmetry is vendor behaviour rather than taste:
+
+* `.github/copilot-instructions.md` is the only instruction file read on every Copilot
+  surface, and Visual Studio chat, JetBrains chat, Xcode and Eclipse do not read
+  `AGENTS.md` at all — so a pointer there would be read by nothing. It carries the same
+  content rather than a reference, and its relative links are re-rooted as it is written:
+  it sits one directory deeper, so a bare `METHOD.md` correct at the project root would
+  resolve to `.github/METHOD.md` and find nothing. Same content, one adjustment, made in
+  the one place the copy happens — so the two still cannot drift apart.
+* `CLAUDE.md` and `GEMINI.md` stay one-line imports. Claude Code reads `AGENTS.md`
+  directly in recent versions but not in Bedrock or telemetry-disabled sessions, where
+  the import is the documented fallback. It never causes a double read.
+
+An `@path` import does not reduce context — an imported file loads exactly like inlined
+text — so indirection is an organisation tool here, never a way to buy length.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from simcon_toolkit.manifest import TEMPLATES_ROOT
+from simcon_toolkit.project import RUN_RULES
+
+SHARED_BASE = TEMPLATES_ROOT / "_shared" / "AGENTS.base.md"
+
+#: What the assembled file must stay under. Vendor guidance, not a house style.
+MAX_ASSEMBLED_LINES = 200
+
+#: The pointer the two import-capable tools receive. Bare on its own line: an `@` import
+#: is silently skipped when the path is followed by a colon or a comma.
+POINTER = "@AGENTS.md\n"
+
+#: Written from the assembled file rather than authored, so there is one source.
+POINTER_FILES = ("CLAUDE.md", "GEMINI.md")
+COPILOT_FILE = Path(".github") / "copilot-instructions.md"
+
+#: A markdown inline link or image, split so the target can be rewritten in place.
+MARKDOWN_LINK = re.compile(r"(!?\[[^\]]*\]\()([^)]+)(\))")
+
+#: A reference-style definition — `[guide]: ./GUIDE.md "Title"` — on its own line. A second
+#: shape rather than a wider pattern, because this one carries no parentheses to anchor on.
+#: Grouped the same way as the inline pattern, prefix / target / rest, so one rewrite and one
+#: extraction serve both. Four spaces of indent is a code block, not a definition.
+MARKDOWN_LINK_DEFINITION = re.compile(r"(^[ ]{0,3}\[[^\]]+\]:[ \t]*)(\S+)(.*)$", re.MULTILINE)
+
+#: Both shapes a relative target can take.
+LINK_PATTERNS = (MARKDOWN_LINK, MARKDOWN_LINK_DEFINITION)
+
+#: Targets that are already absolute, or are not paths at all.
+_NOT_A_RELATIVE_PATH = ("http://", "https://", "//", "#", "mailto:", "/")
+
+
+def reroot_relative_links(text: str, prefix: str) -> str:
+    """Prefix every relative link target, leaving absolute ones and anchors alone.
+
+    Written for one job: the Copilot copy sits one directory below the file it copies, so
+    every relative target in it is wrong by exactly that one level.
+
+    Both link shapes are rewritten. Handling only the inline one would leave the rewriter
+    and the check that guards it disagreeing about what a link is — and the half that ships
+    to the customer would be the one that is wrong.
+    """
+
+    def rewrite(match: re.Match[str]) -> str:
+        opening, target, closing = match.groups()
+        # A title after the path — `[x](path "Title")` — must not be prefixed with it.
+        path, separator, title = target.partition(" ")
+        bare = path.strip("<>")
+        if not bare or bare.startswith(_NOT_A_RELATIVE_PATH):
+            return match.group(0)
+        rerooted = path.replace(bare, prefix + bare, 1)
+        return f"{opening}{rerooted}{separator}{title}{closing}"
+
+    for pattern in LINK_PATTERNS:
+        text = pattern.sub(rewrite, text)
+    return text
+
+
+def assembled(template: Path, shared_base: Path = SHARED_BASE, package_manager: str | None = None) -> str:
+    """The `AGENTS.md` a generated project receives: the shared base, then this template's half.
+
+    With a package manager, the rule for running a command sits between the two. Without one
+    the result is the plain join, which is what the repository's own checks measure.
+
+    The blank line between the parts comes from each part's own trailing newline plus the
+    separator added here. `check_shared_base` is what keeps that true for the base.
+    """
+    parts = [shared_base.read_text(encoding="utf-8")]
+    if package_manager is not None:
+        parts.append(RUN_RULES[package_manager])
+    parts.append((template / "AGENTS.md").read_text(encoding="utf-8"))
+    return "\n".join(parts)
+
+
+def check_shared_base(shared_base: Path = SHARED_BASE) -> None:
+    """Fail when the base cannot produce a blank line between the two halves.
+
+    The separator is one newline, so the base must already end with one. Without that the
+    last line of the shared rules and the first line of the template's half run together
+    into a single line, which no line-count or link check would notice.
+    """
+    text = shared_base.read_text(encoding="utf-8")
+    if not text.endswith("\n"):
+        raise ValueError(
+            f"{shared_base} does not end with a newline, so the assembled AGENTS.md would run "
+            "the shared half straight into the template's half on one line."
+        )
+
+
+def write_instruction_files(
+    destination: Path, template: Path, shared_base: Path = SHARED_BASE, package_manager: str | None = None
+) -> list[Path]:
+    """Write the assembled `AGENTS.md` and the three files derived from it.
+
+    Returns the paths written, so a caller can report them without re-deriving the list.
+    """
+    check_shared_base(shared_base)
+    text = assembled(template, shared_base, package_manager)
+
+    written = []
+    agents = destination / "AGENTS.md"
+    # newline="\n" on every write a customer receives: Python otherwise translates to the
+    # platform separator, so a project generated on Windows would carry CRLF while the same
+    # project generated on Linux carries LF, and the two would not be byte-comparable.
+    agents.write_text(text, encoding="utf-8", newline="\n")
+    written.append(agents)
+
+    for name in POINTER_FILES:
+        pointer = destination / name
+        pointer.write_text(POINTER, encoding="utf-8", newline="\n")
+        written.append(pointer)
+
+    # The same text, with relative link targets moved up one level for the directory it
+    # sits in. Written from the same string rather than re-derived, so the two cannot
+    # drift in content; only the paths differ, and only because they have to.
+    copilot = destination / COPILOT_FILE
+    copilot.parent.mkdir(parents=True, exist_ok=True)
+    depth = len(COPILOT_FILE.parent.parts)
+    copilot.write_text(reroot_relative_links(text, "../" * depth), encoding="utf-8", newline="\n")
+    written.append(copilot)
+
+    return written

simcon_toolkit/manifest.py

@@ -0,0 +1,86 @@
+"""Read `templates.toml`, the one description of what each template is.
+
+This lives in the installer rather than beside the generator because the installer is the
+only copy that ships. Resolving against `KIT_ROOT` is what makes one reader serve both: in
+a published wheel it points inside the package, and in a source checkout it is the
+repository root, so the repository's own tooling reads exactly what a customer's copy does.
+
+The manifest's parity test already fails when a field drifts from the filesystem, so
+nothing here revalidates what that test guarantees — this module only reads.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from simcon_toolkit import KIT_ROOT
+
+ROOT = KIT_ROOT
+MANIFEST = ROOT / "templates.toml"
+TEMPLATES_ROOT = ROOT / "templates"
+PACKAGES_ROOT = ROOT / "packages"
+ASSETS_ROOT = ROOT / "assets"
+
+
+@dataclass(frozen=True)
+class TemplateSpec:
+    """One `[templates.<name>]` table, with the paths it names already resolved."""
+
+    name: str
+    title: str
+    description: str
+    category: str
+    client: str
+    needs: tuple[str, ...]
+    heavy: bool
+    modules: tuple[str, ...]
+    sample: str
+    package: str | None
+
+    @property
+    def directory(self) -> Path:
+        """Where this template's files live."""
+        return TEMPLATES_ROOT / self.name
+
+    @property
+    def sample_source(self) -> Path:
+        """The geometry a generated project receives, so it runs the moment it exists."""
+        return ASSETS_ROOT / "parts" / self.sample
+
+    def module_sources(self) -> list[Path]:
+        """The shared packages copied in beside the workflow, each under its own name."""
+        return [PACKAGES_ROOT / module for module in self.modules]
+
+
+def load_manifest(manifest: Path = MANIFEST) -> dict[str, TemplateSpec]:
+    """Every template the manifest describes, keyed by name."""
+    tables = tomllib.loads(manifest.read_text(encoding="utf-8"))["templates"]
+    return {
+        name: TemplateSpec(
+            name=name,
+            title=table["title"],
+            description=table["description"],
+            category=table["category"],
+            client=table["client"],
+            needs=tuple(table["needs"]),
+            heavy=table["heavy"],
+            modules=tuple(table["modules"]),
+            sample=table["sample"],
+            # Absent for a template that is a single script at its root, so a reader
+            # must tolerate None rather than assume every template has an inner folder.
+            package=table.get("package"),
+        )
+        for name, table in tables.items()
+    }
+
+
+def load_template(name: str, manifest: Path = MANIFEST) -> TemplateSpec:
+    """One template by name, with the available names listed when it is unknown."""
+    templates = load_manifest(manifest)
+    try:
+        return templates[name]
+    except KeyError:
+        known = ", ".join(sorted(templates))
+        raise KeyError(f"no template named {name!r}. Available: {known}") from None

simcon_toolkit/project.py

@@ -0,0 +1,356 @@
+"""The files a generated project gets that exist in no template: its manifest, licence and stamp."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tomllib
+from datetime import UTC, datetime
+from pathlib import Path
+
+from simcon_toolkit.manifest import ROOT, TemplateSpec
+
+KIT_PYPROJECT = ROOT / "pyproject.toml"
+LICENSE_SOURCE = ROOT / "LICENSE"
+NOTICE_SOURCE = ROOT / "NOTICE"
+
+#: A floor and no ceiling. The floor turns a confusing failure deep inside a workflow into
+#: "you need Python 3.12 or newer"; a ceiling would only refuse people, and a virtual
+#: environment cannot work around one because it isolates packages, not the interpreter.
+GENERATED_REQUIRES_PYTHON = ">=3.12"
+
+#: The interpreter uv selects for the project, and downloads if the machine lacks it. The
+#: floor above only refuses; this is what actually steers, because uv follows it silently.
+#: The minor rather than a patch release, which would be a maintenance chore with no benefit.
+PYTHON_VERSION_PIN = "3.12"
+
+#: Git for Windows installs with `core.autocrlf=true`, which checks every text file out as
+#: CRLF. Everything written here is LF, and an assistant writing LF into a CRLF working copy
+#: turns a one-line edit into a whole-file diff. An attribute is the one setting git lets a
+#: repository impose over each person's own configuration. Binary STL needs no rule: its
+#: triangle count always carries a zero byte, which is how git recognises binary.
+GITATTRIBUTES = "* text=auto eol=lf\n"
+
+#: Addresses a customer can actually open. The repository URL is deliberately absent: this
+#: repository is internal, so a link to it answers 404 for every customer who follows it.
+PROJECT_URLS = {
+    # simcon.com permanently redirects here; pointing at the destination spares a customer
+    # a hop and keeps the link honest if the old domain is ever retired.
+    "Homepage": "https://www.simcon.ai",
+    "Documentation": "https://api.simcon.ai/scalar",
+    "Instructions for AI assistants": "https://agents.simcon.ai/start.md",
+}
+
+#: SIMCON's private package index, where the licensed `cadmould` wheel lives: the customer
+#: channel, and the address `cadmould-sdk-auth` itself publishes on PyPI. Not a secret — AWS
+#: states an account id is not one — and it carries no token, which uv keeps in its own
+#: credential store.
+CADMOULD_INDEX = "https://cadmould-620794556704.d.codeartifact.eu-central-1.amazonaws.com/pypi/cadmould-python/simple/"
+
+#: Written into every project, whichever installer was chosen: pip ignores `[tool.uv]`, so a
+#: project a colleague opens with the other installer still installs. `explicit` plus the
+#: source pin is the part that matters. Without it uv checks public PyPI first, finds our
+#: defensive `cadmould 0.0.1` there, and stops.
+UV_INDEX_BLOCK = f"""\
+# uv reads these two tables and pip ignores them. They send `cadmould`, and nothing else,
+# to SIMCON's private index; everything else still comes from PyPI.
+[[tool.uv.index]]
+name = "cadmould"
+url = "{CADMOULD_INDEX}"
+explicit = true
+
+[tool.uv.sources]
+cadmould = {{ index = "cadmould" }}
+"""
+
+#: The README's setup block for a uv project, replacing the pip route the template carries.
+#: One spelling for bash and PowerShell on purpose: a pipe into `--password -` works in both,
+#: uv strips the CRLF Windows PowerShell appends, and it avoids `| iex`, the shape endpoint
+#: security flags.
+UV_SETUP = f"""\
+**uv installs everything, Python 3.12 included.** Install uv once: on Windows
+`winget install --id=astral-sh.uv -e`, then open a new terminal so it is on the path;
+otherwise see <https://docs.astral.sh/uv/getting-started/installation/>.
+
+**Three sign-ins, each in your browser, and each does a different job.**
+
+1. **The package index**, the first line below: it hands uv a token for SIMCON's private index,
+   where the licensed `cadmould` wheel lives. Your company's email domain has to be enabled for
+   it: if you can sign in but the browser tab then says `Access denied: your email domain is not
+   authorized for this API`, ask SIMCON support.
+2. **Your licence**, the first time the code opens a licence session. It first checks the
+   Thales Sentinel run-time on your machine, and prints `License init failed: HASP driver
+   version too old` or `... runtime version too old` when that needs installing or updating.
+3. **The cloud**, the first time the code calls it.
+
+⚠️ A failed licence sign-in does not stop the script. It prints `License init failed: ...` or
+`License acquisition failed.` to the terminal and carries on, so the error you meet later is `Cadmould API licence (LICENCE_API)
+required`. When you see that one, scroll up to the first.
+
+From this folder, the same two lines in bash and in PowerShell:
+
+```
+uvx cadmould-sdk-auth --print-token | uv auth login {CADMOULD_INDEX} --username aws --password -
+uv sync
+```
+
+The token lasts about an hour, and uv needs it only while it installs something, so
+`uv run` keeps working after it expires. If a later `uv sync` or `uv add` fails with
+`401 Unauthorized`, run the first line again.
+
+**Run every command in this README through uv.** Where it says `python main.py ...`, run
+`uv run main.py ...`; where it says `python -m ...`, run `uv run python -m ...`. uv uses this
+project's own environment, so there is nothing to activate on any operating system.
+"""
+
+#: What the instruction file says about running a command, per installer. Every playbook and
+#: every hint the code prints says `python main.py`, which in a uv project runs with no
+#: environment active and fails on an import the assistant then misdiagnoses.
+RUN_RULES = {
+    "uv": """\
+## Running a command in this project
+
+This project installs with uv. Run every `python ...` command the playbooks and the code's
+own hints show through uv: `uv run main.py ...` for `python main.py ...`, and
+`uv run python -m ...` for `python -m ...`. Never `pip install` here, and pass uv no
+`--index-url` or `--extra-index-url`: `cadmould` is already pinned to SIMCON's private index
+in `pyproject.toml`, so no index flag is ever needed. A `401 Unauthorized` from uv means the
+index token expired; the README's first setup line renews it.
+""",
+    "pip": """\
+## Running a command in this project
+
+This project installs with pip into `.venv`. Run every `python ...` command with that
+environment's interpreter: `.venv/bin/python` on macOS and Linux, `.venv\\Scripts\\python.exe`
+on Windows. The system `python` does not have `cadmould` installed.
+""",
+}
+
+SAMPLE_README = """\
+# Sample geometry
+
+`{sample}` is sample geometry shipped so this project runs the moment you generate it.
+
+Replace the file, or pass your own with `--part path/to/your.stl`. Nothing here is
+special: once you are running your own parts you can delete this folder.
+"""
+
+
+#: Never copied into a customer's project. Compiled output was the first prototype's
+#: mistake; the rest is a developer's working tree, which a template directory accumulates
+#: and which `shutil.copytree` would otherwise ship verbatim. `.env` is the one that matters:
+#: every template's own .gitignore says "never commit credentials", and shipping a
+#: developer's licence identity to a customer would make the generator the leak.
+EXCLUDED_NAMES = frozenset(
+    {
+        "__pycache__",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".venv",
+        "venv",
+        ".DS_Store",
+        "Thumbs.db",
+        # Written by a template when it is run in place; ours to regenerate, never to ship.
+        # `build` is one of these, not a packaging directory: run-one-simulation writes its
+        # meshed part and downloaded result there.
+        "build",
+        "cache",
+        "output",
+        # The generator writes sample/ itself, from the one copy under assets/parts/.
+        "sample",
+    }
+)
+
+#: Suffix and prefix rules for the same job. `.env`, `.env.local`, `token.json` and a
+#: compiled module are all things a working tree grows and a customer must never receive.
+EXCLUDED_SUFFIXES = (".pyc", ".pyo", ".egg-info")
+EXCLUDED_PREFIXES = (".env",)
+
+#: Read back in after the prefix rule above, because it names the variables a customer has
+#: to set and carries no value. Excluding it would delete the one file that says what a
+#: real `.env` should contain.
+#:
+#: Matched by NAME ONLY, and it has to stay that way: `content_digest` calls `is_excluded`
+#: on bare relative path components, where any filesystem question would be asked of the
+#: process working directory rather than of the template. A predicate that touched the disk
+#: would answer differently for the copy and for the digest, which is the one thing this
+#: module exists to prevent. That a directory of this name is therefore copied too is
+#: refused in the repository instead, where the check is deterministic.
+PREFIX_EXCEPTIONS = frozenset({".env.example"})
+
+
+def is_excluded(path: Path) -> bool:
+    """Whether a path is a developer's working tree rather than part of the template.
+
+    Used by BOTH the copy and the digest, which is the point of it living here. If the two
+    ever disagree, an untracked file in a template directory changes the digest without
+    changing the project — so two clean checkouts would report different digests for
+    identical content and the stamp would stop meaning anything.
+    """
+    name = path.name
+    if name in PREFIX_EXCEPTIONS:
+        return False
+    return name in EXCLUDED_NAMES or name.endswith(EXCLUDED_SUFFIXES) or name.startswith(EXCLUDED_PREFIXES)
+
+
+def _file_digest(path: Path) -> str:
+    """Hash one file, with text normalised to LF first.
+
+    `.gitattributes` pins the template trees to LF everywhere, but the repository-wide rule
+    is `text=auto`, which checks out **native** — so a file from outside those trees is CRLF
+    in a Windows checkout and LF in a Linux one. Hashing raw bytes
+    would therefore give two digests for identical content, and the stamp would identify the
+    operating system rather than the template. Binary is detected by a NUL byte and hashed
+    untouched, because normalising a `.stl` would corrupt the very thing being identified.
+    """
+    data = path.read_bytes()
+    if b"\x00" not in data:
+        data = data.replace(b"\r\n", b"\n")
+    return hashlib.sha256(data).hexdigest()
+
+
+def content_digest(sources: list[Path]) -> str:
+    """A digest of the template content a project was generated from.
+
+    Keyed on bytes rather than on a version number, because a template can change
+    substantially while every version string in the repository stays still. It is what
+    lets a support engineer tell two projects apart when nobody bumped anything.
+    """
+    digest = hashlib.sha256()
+    for source in sorted(sources):
+        # A source may be a single file — the shared instruction base is one — and rglob on
+        # a file yields nothing, so it would contribute silently nothing to the digest.
+        candidates = [source] if source.is_file() else sorted(p for p in source.rglob("*") if p.is_file())
+        for path in candidates:
+            # The same rule the copy uses, so an untracked file cannot move the digest
+            # without moving the project.
+            if any(is_excluded(Path(part)) for part in path.relative_to(source).parts) or is_excluded(path):
+                continue
+            # as_posix(), never str(): `str()` on a Windows path yields backslashes, so the
+            # same content would digest differently on the two runners CI uses and the field
+            # would stop identifying anything.
+            digest.update(path.relative_to(source.parent).as_posix().encode("utf-8"))
+            digest.update(_file_digest(path).encode("ascii"))
+    return digest.hexdigest()
+
+
+def kit_version(pyproject: Path = KIT_PYPROJECT) -> str:
+    """The kit's own version, parsed rather than matched.
+
+    A regex for `^version = "..."` is correct only while `[project]` is the first table
+    carrying that key, which nothing enforces.
+    """
+    return str(tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]["version"])
+
+
+def _kit_dependencies(pyproject: Path = KIT_PYPROJECT) -> tuple[list[str], dict[str, list[str]]]:
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]
+    return data["dependencies"], data.get("optional-dependencies", {})
+
+
+def dependencies_for(spec: TemplateSpec, pyproject: Path = KIT_PYPROJECT) -> list[str]:
+    """Everything the generated project needs, in one list.
+
+    A single-template project has no use for extras — its one template's dependencies are
+    simply its dependencies — so the kit's shared core and the template's own extra are
+    merged here and `pip install .` is the whole story.
+    """
+    core, extras = _kit_dependencies(pyproject)
+    merged = list(core)
+    for requirement in extras.get(spec.name, []):
+        if requirement not in merged:
+            merged.append(requirement)
+    return merged
+
+
+def _toml_string(value: str) -> str:
+    """One TOML basic string, fully escaped.
+
+    `json.dumps` rather than a hand-rolled quote-and-backslash swap: TOML basic strings and
+    JSON strings share an escape syntax, and JSON covers what the swap missed — a newline, a
+    tab, a control character. Verified by round-tripping each of those through `tomllib`.
+    `ensure_ascii=False` keeps non-ASCII readable, which TOML allows.
+
+    A value that closes the string early produces a manifest that does not parse, and that
+    failure reaches the customer rather than us.
+    """
+    return json.dumps(value, ensure_ascii=False)
+
+
+def render_pyproject(spec: TemplateSpec, project_name: str, pyproject: Path = KIT_PYPROJECT) -> str:
+    """The generated project's `pyproject.toml`, declaring what its one template needs."""
+    # Encoded like every other string: a PEP 508 environment marker legitimately contains
+    # quotes -- `httpx>=0.27; python_version >= "3.12"` -- so an unescaped requirement is one
+    # marker away from a manifest that does not parse.
+    deps = "\n".join(f"    {_toml_string(requirement)}," for requirement in dependencies_for(spec, pyproject))
+    urls = "\n".join(f"{_toml_string(label)} = {_toml_string(url)}" for label, url in PROJECT_URLS.items())
+    return f"""\
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = {_toml_string(project_name)}
+version = "0.1.0"
+description = {_toml_string(spec.description)}
+readme = "README.md"
+# A floor and no ceiling. A virtual environment isolates packages, not the interpreter, so
+# a ceiling refuses people who cannot work around it; the floor turns a confusing error
+# deep inside a workflow into a clear one at install time.
+requires-python = "{GENERATED_REQUIRES_PYTHON}"
+dependencies = [
+{deps}
+]
+
+[project.urls]
+{urls}
+
+# The workflow is scripts you run and edit, not a library to import, so the distribution
+# ships no packages. This file is here for the dependency list.
+[tool.setuptools]
+packages = []
+
+{UV_INDEX_BLOCK}"""
+
+
+def stamp(
+    spec: TemplateSpec,
+    digest: str,
+    *,
+    generated_at: str | None = None,
+    cli_version: str | None = None,
+    package_manager: str,
+) -> dict[str, object]:
+    """What `.simcon-toolkit.json` records, so support can tell which template this is.
+
+    `template_digest` is the load-bearing field: version numbers move only when somebody
+    remembers, and the kit has sat at one version through every template change so far.
+    """
+    return {
+        "template": spec.name,
+        "template_digest": digest,
+        "starter_kit_version": kit_version(),
+        # Absent until the CLI exists and fills it in; recorded as null rather than omitted
+        # so a reader can tell "no CLI" from "an older stamp that had no such field".
+        "cli_version": cli_version,
+        # Which instructions the project was given, so support reads the right route.
+        "package_manager": package_manager,
+        "generated_at": generated_at or datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "needs": list(spec.needs),
+        "client": spec.client,
+    }
+
+
+def write_sample(destination: Path, spec: TemplateSpec) -> list[Path]:
+    """Copy the one shipped part into the project, and say it is disposable.
+
+    A binary `.stl` cannot carry a header comment the way an example env file can, so the
+    folder has to say it in a sibling file.
+    """
+    sample_dir = destination / "sample"
+    sample_dir.mkdir(parents=True, exist_ok=True)
+    part = sample_dir / spec.sample
+    part.write_bytes(spec.sample_source.read_bytes())
+    readme = sample_dir / "README.md"
+    readme.write_text(SAMPLE_README.format(sample=spec.sample), encoding="utf-8", newline="\n")
+    return [part, readme]