💫 Toolkit to help you get started with SDD or any other process!
"""Domain install/validation for custom workflow step packages.
This module owns the source-independent behavior shared by every
``specify workflow step add`` source mode (catalog, ``--dev`` local directory,
and ``--from`` archive URL): step-id and base-directory validation, package
shape/symlink/limit validation, staging, atomic commit, and registry
provenance. It is deliberately CLI-independent -- it never prints and never
raises ``typer.Exit``. Callers receive :class:`StepInstallError` and decide how
to surface it.
"""
from __future__ import annotations
import contextlib
import os
import shutil
import stat
import sys
import tempfile
import warnings
from collections.abc import Mapping
from pathlib import Path
from typing import Any
import yaml
# Custom step packages contain executable Python, metadata, and optional helper
# files. These ceilings apply uniformly to catalog, local, and archive sources.
_MAX_STEP_PACKAGE_FILES = 512
_MAX_STEP_PACKAGE_BYTES = 50 * 1024 * 1024 # 50 MiB
_MAX_STEP_PACKAGE_DEPTH = 32
_COPY_CHUNK_BYTES = 64 * 1024
# Files/dirs never inspected, copied into, or counted as part of an installed
# step package; excluded directories are pruned without being entered. Mirrors
# ``bundles/packager.py`` ``EXCLUDE_NAMES``.
EXCLUDE_NAMES: frozenset[str] = frozenset({".git", "__pycache__", ".DS_Store"})
# Prefix for the private same-filesystem working directory created beneath the
# steps base directory. The leading dot keeps it out of the way, and because it
# contains only a ``staged/`` child (never ``step.yml``/``__init__.py`` at its
# root) the runtime loader never mistakes it for an installable package.
_WORK_DIR_PREFIX = ".speckit-step-install-"
_RESERVED_STEP_IDS: frozenset[str] = frozenset({".cache", "step-registry.json"})
_WINDOWS_RESERVED_NAMES: frozenset[str] = frozenset(
{
"con",
"prn",
"aux",
"nul",
"com1",
"com2",
"com3",
"com4",
"com5",
"com6",
"com7",
"com8",
"com9",
"lpt1",
"lpt2",
"lpt3",
"lpt4",
"lpt5",
"lpt6",
"lpt7",
"lpt8",
"lpt9",
}
)
_WINDOWS_INVALID_CHARS: frozenset[str] = frozenset('<>:"|?*')
_SOURCES: frozenset[str] = frozenset({"catalog", "local", "url"})
class StepInstallError(Exception):
"""User-facing step package install/validation failure."""
@contextlib.contextmanager
def _step_install_transaction(project_root: Path):
"""Serialize step directory and registry mutations (install and remove)."""
from ...shared_infra import _exclusive_project_lock
# Only acquisition failures are reported as lock errors; exceptions raised
# by the caller's critical section propagate unchanged. The message is
# operation-neutral because both install and remove share this lock; callers
# that add their own context should report ``exc.__cause__`` instead.
with contextlib.ExitStack() as stack:
try:
stack.enter_context(
_exclusive_project_lock(
Path(project_root), ".step-install.lock", context="step"
)
)
except OSError as exc:
raise StepInstallError(f"Failed to acquire the step lock: {exc}") from exc
yield
# ---------------------------------------------------------------------------
# Step id + base directory validation
# ---------------------------------------------------------------------------
def validate_step_id(step_id: str) -> None:
"""Validate that ``step_id`` is a single safe path component.
Rejects empty strings, whitespace-only strings, leading/trailing
whitespace, path separators, ``.``/``..`` components, dotfile prefixes,
reserved names, Windows-invalid filename characters, trailing dots/spaces,
and Windows reserved device names.
"""
stem = step_id.split(".")[0].lower() if step_id else ""
if (
not step_id
or not step_id.strip()
or step_id != step_id.strip()
or "/" in step_id
or "\\" in step_id
or step_id in (".", "..")
or step_id.startswith(".")
or step_id.endswith((".", " "))
or step_id.lower() in _RESERVED_STEP_IDS
or stem in _WINDOWS_RESERVED_NAMES
or any(c in _WINDOWS_INVALID_CHARS for c in step_id)
or any(ord(c) < 32 for c in step_id)
):
raise StepInstallError(
f"Invalid step id '{step_id}': must be a single safe "
"path component (no separators, no leading dot, not a reserved name, "
"no invalid filename characters)"
)
def resolve_steps_base_dir(project_root: Path) -> Path:
"""Resolve ``.specify/workflows/steps`` refusing symlinked parent dirs."""
project_root = Path(project_root)
project_root_resolved = project_root.resolve()
steps_base_dir_unresolved = project_root / ".specify" / "workflows" / "steps"
current = project_root
for part in (".specify", "workflows", "steps"):
current = current / part
if current.is_symlink():
raise StepInstallError(
f"Refusing to use symlinked step directory '{current}'"
)
if current.exists() and not current.is_dir():
raise StepInstallError(
f"Step directory path is not a directory: '{current}'"
)
steps_base_dir = steps_base_dir_unresolved.resolve()
try:
steps_base_dir.relative_to(project_root_resolved)
except ValueError:
raise StepInstallError(
f"Step directory escapes project root: '{steps_base_dir}'"
) from None
return steps_base_dir
def _resolve_step_dir(steps_base_dir: Path, step_id: str) -> Path:
"""Return the canonical destination directory for ``step_id``."""
step_dir = steps_base_dir / step_id
try:
rel_parts = step_dir.relative_to(steps_base_dir).parts
except ValueError:
raise StepInstallError(f"Invalid step id '{step_id}'") from None
if rel_parts != (step_id,):
raise StepInstallError(f"Invalid step id '{step_id}'")
return step_dir
def _reject_unsafe_destination(step_dir: Path) -> None:
"""Refuse a symlink (including dangling) or non-directory destination."""
if step_dir.is_symlink():
raise StepInstallError(
f"Refusing to install step through a symlinked path: '{step_dir}'"
)
if step_dir.exists() and not step_dir.is_dir():
raise StepInstallError(
f"Step install path exists but is not a directory: '{step_dir}'"
)
# ---------------------------------------------------------------------------
# Package shape + safety validation
# ---------------------------------------------------------------------------
def _entry_limit_error() -> StepInstallError:
return StepInstallError(
"Step package contains too many entries, exceeding the "
f"{_MAX_STEP_PACKAGE_FILES}-entry limit (files and directories combined)"
)
def _scan_retained_entries(directory: Path, budget: int) -> list[os.DirEntry]:
"""Return *directory*'s retained children, sorted by name.
Streams the listing and drops ``EXCLUDE_NAMES`` without inspecting them.
Raises the entry-limit error as soon as more than *budget* retained
entries are seen, so an oversized directory is never fully materialized
or sorted. ``OSError`` propagates to the caller.
"""
entries: list[os.DirEntry] = []
with os.scandir(directory) as iterator:
for entry in iterator:
if entry.name in EXCLUDE_NAMES:
continue
if len(entries) >= budget:
raise _entry_limit_error()
entries.append(entry)
entries.sort(key=lambda entry: entry.name)
return entries
def _walk_package_tree(package_dir: Path):
"""Yield ``(path, is_dir)`` for every retained descendant of *package_dir*.
Excluded names are pruned without being entered or inspected, matching
``bundles/packager.py``; their contents are never staged, so they are not
part of the package. Every retained entry discovered counts against
``_MAX_STEP_PACKAGE_FILES`` before its directory listing is sorted, which
bounds traversal work by the entry ceiling. Never follows a symlink.
Raises :class:`StepInstallError` on any symlink, object that is neither a
regular file nor a directory, nesting deeper than
``_MAX_STEP_PACKAGE_DEPTH``, or too many entries. Iterative so deep trees
cannot exhaust the Python recursion limit.
"""
discovered = 0
def _children(current: Path, depth: int):
nonlocal discovered
try:
entries = _scan_retained_entries(
current, _MAX_STEP_PACKAGE_FILES - discovered
)
except OSError as exc:
raise StepInstallError(
f"Failed to read step package directory '{current}': {exc}"
) from exc
discovered += len(entries)
return [(entry, depth) for entry in reversed(entries)]
stack = _children(package_dir, 1)
while stack:
entry, depth = stack.pop()
try:
mode = entry.stat(follow_symlinks=False).st_mode
except OSError as exc:
raise StepInstallError(
f"Failed to inspect step package entry '{entry.path}': {exc}"
) from exc
path = Path(entry.path)
if stat.S_ISLNK(mode):
raise StepInstallError(f"Step package contains symlink: {path}")
if stat.S_ISDIR(mode):
if depth > _MAX_STEP_PACKAGE_DEPTH:
raise StepInstallError(
f"Step package exceeds the {_MAX_STEP_PACKAGE_DEPTH}-level "
"directory depth limit"
)
yield path, True
stack.extend(_children(path, depth + 1))
elif stat.S_ISREG(mode):
yield path, False
else:
raise StepInstallError(
f"Step package contains unsupported file: {path}"
)
def _parse_step_metadata(step_yml_text: str, step_id: str) -> dict[str, Any]:
"""Parse and validate ``step.yml``, returning the ``step`` mapping."""
try:
# ``safe_load`` returns None for BOTH an empty document and an explicit
# null scalar (``null``, ``~``, ``NULL``), so it cannot tell them apart
# on its own. ``compose`` yields no node only for a genuinely empty
# document.
node = yaml.compose(step_yml_text)
meta = yaml.safe_load(step_yml_text)
is_empty_document = node is None or (
meta is None
and isinstance(node, yaml.nodes.ScalarNode)
and node.value == ""
and node.start_mark.index == node.end_mark.index
)
except Exception as exc:
raise StepInstallError(f"Invalid step.yml: {exc}") from exc
# Do NOT coerce with ``or {}`` here: that also turns a FALSY non-mapping
# (top-level ``[]``, ``false``, ``0``, ``''``, or an explicit ``null``)
# into ``{}`` and silently bypasses this shape check. Only a genuinely
# empty document defaults to ``{}``.
if meta is None and is_empty_document:
meta = {}
elif not isinstance(meta, dict):
raise StepInstallError("step.yml must be a YAML mapping")
step_meta = meta.get("step", {})
if not isinstance(step_meta, dict):
raise StepInstallError("step.yml 'step' field must be a mapping")
type_key = step_meta.get("type_key", "")
if not type_key:
raise StepInstallError("step.yml missing 'step.type_key' field")
if type_key != step_id:
raise StepInstallError(
f"step.yml type_key ({type_key!r}) does not match step ID ({step_id!r})"
)
return step_meta
def validate_step_package(package_dir: Path, step_id: str) -> dict[str, Any]:
"""Validate a materialized step package directory.
Returns the validated ``step.yml`` ``step`` mapping. Raises
:class:`StepInstallError` on any shape, symlink, limit, path, or identity
violation. Never imports or executes ``__init__.py``.
"""
package_dir = Path(package_dir)
if package_dir.is_symlink():
raise StepInstallError(
f"Refusing to install from a symlinked package directory: '{package_dir}'"
)
if not package_dir.is_dir():
raise StepInstallError(f"Step package directory not found: '{package_dir}'")
for required in ("step.yml", "__init__.py"):
required_path = package_dir / required
if required_path.is_symlink():
raise StepInstallError(
f"Step package '{required}' must be a regular file, not a symlink"
)
if not required_path.is_file():
raise StepInstallError(
f"Step package is missing required file '{required}' at its root"
)
# The walk enforces the entry ceiling itself; only bytes are summed here.
retained_bytes = 0
for path, is_dir in _walk_package_tree(package_dir):
if is_dir:
continue
try:
retained_bytes += path.lstat().st_size
except OSError as exc:
raise StepInstallError(
f"Failed to inspect step package file '{path}': {exc}"
) from exc
if retained_bytes > _MAX_STEP_PACKAGE_BYTES:
raise StepInstallError(
f"Step package exceeds the {_MAX_STEP_PACKAGE_BYTES}-byte total "
"size limit"
)
try:
step_yml_text = (package_dir / "step.yml").read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as exc:
raise StepInstallError(f"Invalid step.yml: {exc}") from exc
return _parse_step_metadata(step_yml_text, step_id)
def resolve_package_root(extracted_root: Path) -> Path:
"""Resolve a root-level or single-nested step package directory."""
extracted_root = Path(extracted_root)
root_manifest = extracted_root / "step.yml"
if root_manifest.is_file() and not root_manifest.is_symlink():
return extracted_root
try:
entries = list(extracted_root.iterdir())
except OSError as exc:
raise StepInstallError(
f"Failed to inspect archive contents: {exc}"
) from exc
if len(entries) == 1:
candidate = entries[0]
candidate_manifest = candidate / "step.yml"
if (
candidate.is_dir()
and not candidate.is_symlink()
and candidate_manifest.is_file()
and not candidate_manifest.is_symlink()
):
return candidate
raise StepInstallError(
"archive must contain step.yml at its root or in exactly one top-level "
"directory"
)
# ---------------------------------------------------------------------------
# Collision / duplicate preflight
# ---------------------------------------------------------------------------
def _reject_builtin_collision(step_id: str) -> None:
from .. import BUILTIN_STEP_TYPES
if step_id in BUILTIN_STEP_TYPES:
raise StepInstallError(
f"Step type '{step_id}' conflicts with a built-in step type"
)
def _check_duplicate(
registry: Any, step_id: str, step_dir: Path, *, force: bool
) -> None:
folded_id = step_id.casefold()
try:
registered_ids = registry.list()
except (AttributeError, TypeError):
registered_ids = ()
for registered_id in registered_ids:
if (
isinstance(registered_id, str)
and registered_id != step_id
and registered_id.casefold() == folded_id
):
raise StepInstallError(
f"Step ID '{step_id}' collides case-insensitively with registered "
f"step ID '{registered_id}'; use the exact registered ID with --force"
)
try:
destination_exists = step_dir.exists()
for existing_path in step_dir.parent.iterdir():
existing_name = existing_path.name
if existing_name == step_id:
continue
aliases_destination = (
destination_exists and existing_path.samefile(step_dir)
)
if existing_name.casefold() != folded_id and not aliases_destination:
continue
raise StepInstallError(
f"Step ID '{step_id}' collides case-insensitively or resolves to "
f"the same filesystem path as existing step directory "
f"'{existing_name}'"
)
except FileNotFoundError:
pass
except OSError as exc:
raise StepInstallError(
f"Failed to inspect existing step directories: {exc}"
) from exc
if force:
return
if registry.is_installed(step_id):
raise StepInstallError(
f"Step type '{step_id}' is already installed. Remove it first with: "
f"specify workflow step remove {step_id}"
)
if step_dir.exists():
raise StepInstallError(
f"Step directory already exists at '{step_dir}'. Remove it manually "
f"or use: specify workflow step remove {step_id}"
)
def check_installable(project_root: Path, step_id: str, *, force: bool = False) -> Path:
"""Advisory preflight shared by all sources.
Validates the id, base directory, built-in collision, and
duplicate/orphan-destination state without touching the package. The CLI
uses this to reject before a download; :func:`install_step_package`
re-runs the same checks as defense-in-depth.
"""
from .catalog import StepRegistry
validate_step_id(step_id)
steps_base_dir = resolve_steps_base_dir(project_root)
step_dir = _resolve_step_dir(steps_base_dir, step_id)
_reject_unsafe_destination(step_dir)
_reject_builtin_collision(step_id)
registry = StepRegistry(project_root)
_check_duplicate(registry, step_id, step_dir, force=force)
return step_dir
# ---------------------------------------------------------------------------
# Staging + commit
# ---------------------------------------------------------------------------
def _build_entry(
step_id: str,
step_meta: Mapping[str, Any],
*,
source: str,
catalog_name: str,
catalog_metadata: Mapping[str, Any] | None,
) -> dict[str, Any]:
if source not in _SOURCES:
raise StepInstallError(
"Step install source must be one of: catalog, local, url"
)
if source == "catalog" and not isinstance(catalog_name, str):
raise StepInstallError("Catalog step install requires a string catalog name")
if catalog_metadata is not None and not isinstance(catalog_metadata, Mapping):
raise StepInstallError("Catalog step metadata must be a mapping")
catalog_metadata = catalog_metadata or {}
def _string_value(metadata: Mapping[str, Any], field: str) -> str | None:
value = metadata.get(field)
if value is None:
return None
if not isinstance(value, str):
raise StepInstallError(
f"step metadata '{field}' must be a string when present"
)
return value
type_key = _string_value(step_meta, "type_key")
if not type_key:
raise StepInstallError("step.yml missing 'step.type_key' field")
package_values = {
field: _string_value(step_meta, field)
for field in ("name", "version", "description", "author")
}
catalog_values = {
field: _string_value(catalog_metadata, field)
for field in ("name", "version", "description", "author")
}
entry: dict[str, Any] = {
"name": catalog_values["name"] or package_values["name"] or step_id,
"version": catalog_values["version"] or package_values["version"] or "0.0.0",
"description": (
catalog_values["description"]
if catalog_values["description"] is not None
else package_values["description"] or ""
),
"author": (
catalog_values["author"]
if catalog_values["author"] is not None
else package_values["author"] or ""
),
"type_key": type_key,
"source": source,
}
if source == "catalog":
entry["catalog_name"] = catalog_name
return entry
def _copy_package_tree(source_dir: Path, target_dir: Path) -> None:
"""Copy *source_dir* into *target_dir*, skipping excludes.
Refuses to follow a symlink encountered mid-copy so a source swapped after
validation cannot smuggle external content into the staged package, and
re-enforces the depth, entry, and byte budgets. Entries count against the
entry budget as each listing is streamed, before it is sorted, so an
oversized source directory is rejected without being fully read. Iterative
so a deep tree cannot exhaust the Python recursion limit.
"""
remaining_bytes = _MAX_STEP_PACKAGE_BYTES
discovered_entries = 0
pending = [(source_dir, target_dir, 0)]
while pending:
current, destination, depth = pending.pop()
if depth > _MAX_STEP_PACKAGE_DEPTH:
raise StepInstallError(
f"Step package exceeds the {_MAX_STEP_PACKAGE_DEPTH}-level "
"directory depth limit"
)
try:
destination.mkdir(parents=True, exist_ok=True)
except OSError as exc:
raise StepInstallError(
f"Failed to stage step package: {exc}"
) from exc
try:
entries = _scan_retained_entries(
current, _MAX_STEP_PACKAGE_FILES - discovered_entries
)
except OSError as exc:
raise StepInstallError(
f"Failed to stage step package: {exc}"
) from exc
discovered_entries += len(entries)
for entry in entries:
try:
mode = entry.stat(follow_symlinks=False).st_mode
except OSError as exc:
raise StepInstallError(f"Failed to stage step package: {exc}") from exc
target = destination / entry.name
if stat.S_ISLNK(mode):
raise StepInstallError(
f"Step package contains symlink: {entry.path}"
)
if not (stat.S_ISDIR(mode) or stat.S_ISREG(mode)):
raise StepInstallError(
f"Step package contains unsupported file: {entry.path}"
)
if stat.S_ISDIR(mode):
pending.append((Path(entry.path), target, depth + 1))
else:
remaining_bytes -= _copy_regular_file(
entry.path, target, mode, remaining_bytes
)
def _copy_regular_file(
source: str, target: Path, expected_mode: int, remaining_bytes: int
) -> int:
"""Copy an inspected regular file within the remaining package byte budget."""
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
try:
fd = os.open(source, flags)
except OSError as exc:
raise StepInstallError(f"Failed to stage step package: {exc}") from exc
try:
opened = os.fstat(fd)
source_state = os.stat(source, follow_symlinks=False)
if (
not stat.S_ISREG(opened.st_mode)
or not stat.S_ISREG(source_state.st_mode)
or opened.st_dev != source_state.st_dev
or opened.st_ino != source_state.st_ino
or stat.S_IFMT(source_state.st_mode) != stat.S_IFMT(expected_mode)
):
raise StepInstallError(
f"Step package file changed while staging: {source}"
)
copied_bytes = 0
with os.fdopen(fd, "rb", closefd=False) as source_file, target.open(
"xb"
) as target_file:
while True:
chunk = source_file.read(
min(_COPY_CHUNK_BYTES, remaining_bytes - copied_bytes + 1)
)
if not chunk:
break
if copied_bytes + len(chunk) > remaining_bytes:
raise StepInstallError(
f"Step package exceeds the {_MAX_STEP_PACKAGE_BYTES}-byte "
"total size limit while staging"
)
target_file.write(chunk)
copied_bytes += len(chunk)
return copied_bytes
except OSError as exc:
raise StepInstallError(f"Failed to stage step package: {exc}") from exc
finally:
try:
os.close(fd)
except OSError:
pass
def _replace_install(
step_dir: Path,
staged_dir: Path,
registry: Any,
step_id: str,
entry: dict[str, Any],
*,
force: bool,
) -> None:
"""Publish the staged package and record its registry entry."""
from .catalog import StepValidationError
if step_dir.exists():
if not force:
raise StepInstallError(
f"Step directory already exists at '{step_dir}'. Remove it manually "
f"or use: specify workflow step remove {step_id}"
)
# --force replacement: the replacement is fully staged and validated,
# so it is safe to remove the previous installation now.
try:
shutil.rmtree(step_dir)
except OSError as exc:
raise StepInstallError(
f"Failed to remove the existing step installation at "
f"'{step_dir}': {exc}. Reinstall from the original source with "
"--force."
) from exc
try:
os.replace(staged_dir, step_dir)
except OSError as exc:
raise StepInstallError(
f"Failed to publish the replacement for step type '{step_id}': "
f"{exc}. The previous installation was removed; reinstall from "
"the original source with --force."
) from exc
try:
registry.add(step_id, entry)
except (StepValidationError, OSError, TypeError, ValueError) as exc:
raise StepInstallError(
f"Failed to update the step registry for '{step_id}': {exc}. The "
"package was replaced but the registry metadata was not updated; "
"reinstall from the original source with --force."
) from exc
return
try:
os.replace(staged_dir, step_dir)
except OSError as exc:
raise StepInstallError(
f"Failed to install step '{step_id}': {exc}"
) from exc
try:
registry.add(step_id, entry)
except (StepValidationError, OSError, TypeError, ValueError) as exc:
# Fresh install: roll back the just-published directory so the system
# is not left with an unregistered step package on disk.
try:
shutil.rmtree(step_dir)
except OSError as cleanup_exc:
raise StepInstallError(
f"Failed to update the step registry for '{step_id}': {exc}. "
f"The unregistered package remains at '{step_dir}' because rollback "
f"failed: {cleanup_exc}. Remove it manually before reinstalling."
) from exc
raise StepInstallError(str(exc)) from exc
def install_step_package(
project_root: Path,
step_id: str,
package_dir: Path,
*,
source: str,
catalog_name: str = "",
catalog_metadata: Mapping[str, Any] | None = None,
force: bool = False,
) -> dict[str, Any]:
"""Validate, stage, and commit a step package from any source.
``source`` is exactly ``"catalog"``, ``"local"``, or ``"url"``. Returns the
registry entry that was persisted.
"""
from .catalog import StepRegistry
package_dir = Path(package_dir)
if package_dir.is_symlink():
raise StepInstallError(
f"Refusing to install from a symlinked package directory: '{package_dir}'"
)
if not package_dir.is_dir():
raise StepInstallError(f"Step package directory not found: '{package_dir}'")
validate_step_id(step_id)
steps_base_dir = resolve_steps_base_dir(project_root)
step_dir = _resolve_step_dir(steps_base_dir, step_id)
_reject_unsafe_destination(step_dir)
# Reject a source that resolves to (or contains) the install destination:
# a --force replacement would otherwise delete the source before it can be
# copied.
try:
source_resolved = package_dir.resolve()
dest_resolved = step_dir.resolve()
except OSError as exc:
raise StepInstallError(f"Failed to resolve step package path: {exc}") from exc
if source_resolved == dest_resolved or dest_resolved.is_relative_to(
source_resolved
):
raise StepInstallError(
f"Step package source resolves to the install destination: "
f"'{package_dir}'"
)
_reject_builtin_collision(step_id)
registry = StepRegistry(project_root)
_check_duplicate(registry, step_id, step_dir, force=force)
# Validate source and all caller-controlled metadata before creating any
# project directories. The staged metadata is used for the final entry.
_build_entry(
step_id,
validate_step_package(package_dir, step_id),
source=source,
catalog_name=catalog_name,
catalog_metadata=catalog_metadata,
)
try:
steps_base_dir.mkdir(parents=True, exist_ok=True)
work_dir = Path(
tempfile.mkdtemp(prefix=_WORK_DIR_PREFIX, dir=steps_base_dir)
)
except OSError as exc:
raise StepInstallError(f"Failed to create staging directory: {exc}") from exc
staged_dir = work_dir / "staged"
committed = False
try:
_copy_package_tree(package_dir, staged_dir)
# Re-validate the complete staged copy: the source may have changed
# while it was copied.
staged_meta = validate_step_package(staged_dir, step_id)
entry = _build_entry(
step_id,
staged_meta,
source=source,
catalog_name=catalog_name,
catalog_metadata=catalog_metadata,
)
# Serialize destination and registry changes. Source downloads/copying
# stay outside the lock, but all state that can conflict is reloaded and
# checked again immediately before publication.
with _step_install_transaction(project_root):
locked_base_dir = resolve_steps_base_dir(project_root)
if locked_base_dir != steps_base_dir:
raise StepInstallError(
"Step directory changed while staging; reinstall from the original source"
)
step_dir = _resolve_step_dir(locked_base_dir, step_id)
_reject_unsafe_destination(step_dir)
_reject_builtin_collision(step_id)
registry = StepRegistry(project_root)
_check_duplicate(registry, step_id, step_dir, force=force)
_replace_install(
step_dir,
staged_dir,
registry,
step_id,
entry,
force=force,
)
committed = True
finally:
primary_error = sys.exc_info()[1]
try:
shutil.rmtree(work_dir)
except OSError as cleanup_exc:
if work_dir.exists():
message = (
f"Could not remove step staging directory '{work_dir}': "
f"{cleanup_exc}"
)
if primary_error is not None:
primary_error.add_note(message)
elif committed:
warnings.warn(message, UserWarning, stacklevel=2)
else:
raise StepInstallError(message) from cleanup_exc
return entry