Scaffold

scaffold

InitScaffoldTool — project scaffolding as an AXMTool.

InitScaffoldTool

Initialize a new Python project with best practices.

Registered as init_scaffold via axm.tools entry point.

Source code in packages/axm-init/src/axm_init/tools/scaffold.py

class InitScaffoldTool:
    """Initialize a new Python project with best practices.

    Registered as ``init_scaffold`` via axm.tools entry point.
    """

    @property
    def name(self) -> str:
        """Tool name used for MCP registration."""
        return "init_scaffold"

    @property
    def kinds(self) -> tuple[str, ...]:
        """Scaffold kinds this tool declares, in template order.

        The declared set is the tool's contract: every value is selectable
        through the ``kind`` input (MCP) and ``--kind`` (CLI), and each one
        routes either to a bundled template or the protocol scaffolder.
        """
        return SCAFFOLD_KINDS

    def _validate_inputs(
        self,
        kwargs: dict[str, object],
    ) -> (
        tuple[
            str,
            str | None,
            str,
            str,
            str,
            str,
            str,
            bool,
            bool,
            str | None,
            str | None,
            Framework,
        ]
        | ToolResult
    ):
        """Extract and validate inputs from kwargs.

        Returns a tuple of validated values or a ToolResult on error.
        """

        def _str(key: str, default: str = "") -> str:
            v = kwargs.get(key, default)
            return v if isinstance(v, str) else default

        def _opt_str(key: str) -> str | None:
            v = kwargs.get(key)
            return v if isinstance(v, str) else None

        path: str = _str("path", ".")
        name: str | None = _opt_str("name")
        org: str = _str("org")
        author: str = _str("author")
        email: str = _str("email")
        license_type: str = _str("license", "Apache-2.0")
        license_holder: str | None = _opt_str("license_holder")
        description: str = _str("description")
        private_raw = kwargs.get("private")
        if not isinstance(private_raw, bool):
            return ToolResult(
                success=False,
                error=f"'private' must be a boolean, got {type(private_raw).__name__}",
            )
        private: bool = private_raw
        workspace_raw = kwargs.get("workspace", False)
        if not isinstance(workspace_raw, bool):
            return ToolResult(
                success=False,
                error=(
                    f"'workspace' must be a boolean, got {type(workspace_raw).__name__}"
                ),
            )
        workspace: bool = workspace_raw
        member: str | None = _opt_str("member")

        if not org or not author or not email:
            return ToolResult(
                success=False,
                error="org, author, and email are required",
            )

        try:
            framework = Framework(_str("framework", Framework.PYTHON.value))
        except ValueError:
            valid = ", ".join(f.value for f in Framework)
            return ToolResult(
                success=False,
                error=f"Unknown framework '{_str('framework')}'. Valid: {valid}",
            )

        if workspace and member is not None:
            return ToolResult(
                success=False,
                error="'workspace' and 'member' are mutually exclusive",
            )

        return (
            path,
            name,
            org,
            author,
            email,
            license_type,
            description,
            private,
            workspace,
            member,
            license_holder,
            framework,
        )

    def _build_template_data(
        self,
        *,
        project_name: str,
        workspace: bool,
        description: str,
        meta: _ProjectMeta,
        license_holder: str | None,
        private: bool,
    ) -> dict[str, object]:
        """Build template data dict for workspace or standalone scaffold."""
        name_key = "workspace_name" if workspace else "package_name"
        default_desc = (
            "A modern Python workspace" if workspace else "A modern Python package"
        )
        return {
            name_key: project_name,
            "description": description or default_desc,
            "org": meta.org,
            "license": meta.license_type,
            "license_holder": license_holder or meta.org,
            "author_name": meta.author_name,
            "author_email": meta.author_email,
            "private": private,
            # Jinja has no date filter and copier exposes none, so a template
            # cannot compute this itself: supplied here so a scaffolded
            # wrangler.toml pins the Workers runtime current at creation time
            # rather than a date frozen in the template.
            "compatibility_date": date.today().isoformat(),
        }

    def execute(
        self,
        path: str = ".",
        *,
        name: str | None = None,
        org: str = "",
        author: str = "",
        email: str = "",
        license: str = "Apache-2.0",
        license_holder: str | None = None,
        description: str = "",
        # Safe default: removing one classifier is reversible; a PyPI upload is not.
        private: bool = True,
        workspace: bool = False,
        member: str | None = None,
        framework: str = Framework.PYTHON.value,
        kind: str | None = None,
        check_pypi: bool = False,
        json_output: bool = False,
        profile: str | None = None,
        domain: str | None = None,
        unit: str | None = None,
        protocols: list[dict[str, object]] | str | None = None,
        preview: bool = False,
    ) -> ToolResult:
        """Initialize a new Python project.

        Args:
            path: Path to initialize project.
            name: Project name (defaults to directory name).
            org: GitHub org or username.
            author: Author name.
            email: Author email.
            license: License type.
            license_holder: License holder (defaults to org).
            description: Project description.
            private: If True, prevent publication to PyPI.
            workspace: If True, scaffold a UV workspace.
            member: Member package name to scaffold inside a workspace.
            framework: Target framework (python, node, svelte).
            kind: Explicit scaffold kind — one of ``SCAFFOLD_KINDS``
                (standalone, workspace, member, paper, experiment,
                learning, protocol_unit, protocol).
            check_pypi: If True, check name availability on PyPI.
            json_output: If True, render the structured report.
            profile: Protocol profile to scaffold.
            domain: Protocol domain to scaffold.
            unit: Protocol unit to scaffold.
            protocols: Protocol definitions, as objects or a JSON string.
            preview: If True, report the planned protocol scaffold
                without writing it.

        Returns:
            ToolResult with created files list.
        """
        kwargs: dict[str, object] = {
            "path": path,
            "name": name,
            "org": org,
            "author": author,
            "email": email,
            "license": license,
            "license_holder": license_holder,
            "description": description,
            "private": private,
            "workspace": workspace,
            "member": member,
            "framework": framework,
            "kind": kind,
        }
        prepared = self._prepare_context(
            kwargs,
            protocol_options={
                "profile": profile,
                "domain": domain,
                "unit": unit,
                "protocols": protocols,
                "preview": preview,
            },
            check_pypi=check_pypi,
        )
        if isinstance(prepared, ToolResult):
            return _apply_json_output(prepared, json_output)

        try:
            result = (
                _route_protocol_request(prepared.protocol_request, prepared.target_path)
                or self._dispatch_kind(
                    prepared.kind,
                    target_path=prepared.target_path,
                    name=prepared.name,
                    description=prepared.description,
                    meta=prepared.meta,
                )
                or self._scaffold_from_templates(prepared)
            )
        except Exception as exc:
            result = ToolResult(success=False, error=str(exc))
        return _apply_json_output(result, json_output)

    def _prepare_context(
        self,
        kwargs: dict[str, object],
        *,
        protocol_options: dict[str, object],
        check_pypi: bool,
    ) -> _ScaffoldContext | ToolResult:
        """Validate every precondition, returning a context or the refusal."""
        if kwargs.get("kind") == "paper":
            return ToolResult(
                success=False,
                error="Paper scaffolding is owned by axm-lab; use paper_scaffold.",
            )
        validated = self._validate_inputs(kwargs)
        if isinstance(validated, ToolResult):
            return validated
        (
            path,
            name,
            org,
            author,
            email,
            license_type,
            description,
            private,
            workspace,
            member,
            license_holder,
            framework,
        ) = validated

        kind = _read_kind(kwargs)
        if kind_error := _unknown_kind_error(kind):
            return kind_error
        workspace, member = _apply_kind_flags(
            kind, workspace=workspace, member=member, name=name
        )

        learning_domain = (
            _opt_str_option(protocol_options, "domain") if kind == "learning" else None
        )
        protocol_request = prepare_protocol_request(
            profile=_opt_str_option(protocol_options, "profile"),
            domain=(
                None
                if kind == "learning"
                else _opt_str_option(protocol_options, "domain")
            ),
            unit=_opt_str_option(protocol_options, "unit"),
            protocols=_protocols_option(protocol_options),
            preview=bool(protocol_options.get("preview", False)),
            framework=framework,
        )
        if isinstance(protocol_request, str):
            return ToolResult(success=False, error=protocol_request)

        try:
            target_path = Path(path).resolve()
        except Exception as exc:  # pragma: no cover - defensive path resolution
            return ToolResult(success=False, error=str(exc))
        project_name = name or target_path.name
        if check_pypi:
            taken = _check_pypi_availability(project_name)
            if taken is not None:
                return taken

        return _ScaffoldContext(
            target_path=target_path,
            project_name=project_name,
            name=name,
            description=description,
            license_holder=license_holder,
            private=private,
            framework=framework,
            workspace=workspace,
            member=member,
            kind=kind,
            learning_domain=learning_domain,
            meta=_ProjectMeta(
                org=org,
                license_type=license_type,
                author_name=author,
                author_email=email,
            ),
            protocol_request=protocol_request,
        )

    def _scaffold_from_templates(self, ctx: _ScaffoldContext) -> ToolResult:
        """Route the member / workspace / standalone template cascade."""
        if ctx.member:
            return self._scaffold_member_with_profile(ctx, ctx.member)
        return self._scaffold_root(ctx)

    def _scaffold_member_with_profile(
        self, ctx: _ScaffoldContext, member: str
    ) -> ToolResult:
        """Scaffold a workspace member, registering its protocol profile if asked."""
        meta = ctx.meta
        member_result = self._scaffold_member(
            ctx.target_path,
            member,
            scaffold_data={
                "org": meta.org,
                "author_name": meta.author_name,
                "author_email": meta.author_email,
                "license": meta.license_type,
                "description": ctx.description,
            },
            license_holder=ctx.license_holder,
            private=ctx.private,
            learning=ctx.kind == "learning",
            learning_domain=ctx.learning_domain,
        )
        request = ctx.protocol_request
        if not member_result.success or request is None:
            return member_result
        member_root = ctx.target_path / "packages" / member
        register_protocol_profile(member_root, request.domain)
        member_data = dict(member_result.data or {})
        member_data.update(
            {
                "profile": request.profile,
                "mode": "member",
                "distribution": member,
                "root": str(member_root),
            }
        )
        return ToolResult(success=True, data=member_data, text=member_result.text)

    def _scaffold_root(self, ctx: _ScaffoldContext) -> ToolResult:
        """Render the workspace or standalone template at the target root."""
        from axm_init.adapters.copier import CopierAdapter, CopierConfig
        from axm_init.core.templates import (
            TemplateType,
            get_template_path,
            template_chain,
        )

        template_type = (
            TemplateType.LEARNING
            if ctx.kind == "learning"
            else TemplateType.WORKSPACE
            if ctx.workspace
            else TemplateType.STANDALONE
        )
        module_name = ctx.project_name.replace("-", "_")
        requested_learning_domain = ctx.learning_domain or module_name
        if template_type is TemplateType.LEARNING:
            declared_learning_domain(ctx.target_path, requested_learning_domain)
        template_data = self._build_template_data(
            project_name=ctx.project_name,
            workspace=ctx.workspace,
            description=ctx.description,
            meta=ctx.meta,
            license_holder=ctx.license_holder,
            private=ctx.private,
        )
        if template_type is TemplateType.LEARNING:
            template_data.update(
                {
                    "learning_mode": "standalone",
                    "domain": requested_learning_domain,
                }
            )
        copier = CopierAdapter()
        if template_type is TemplateType.LEARNING:
            layers = template_chain(
                template_type,
                ctx.framework,
                member=False,
                existing=(ctx.target_path / "pyproject.toml").is_file(),
            )
            result = copier.apply_chain(
                list(layers),
                ctx.target_path,
                template_data,
            )
        else:
            result = copier.copy(
                CopierConfig(
                    template_path=get_template_path(template_type, ctx.framework),
                    destination=ctx.target_path,
                    data=template_data,
                    trust_template=True,
                )
            )

        files = [str(f) for f in result.files_created]
        result_data: dict[str, object] = {
            "project_name": ctx.project_name,
            "template": template_type.value,
            "files": files,
        }
        request = ctx.protocol_request
        if result.success and template_type is TemplateType.LEARNING:
            metadata_path = ctx.target_path / "pyproject.toml"
            if metadata_path.is_file():
                register_learning_profile(
                    ctx.target_path,
                    requested_learning_domain,
                    module_name,
                )
            result_data.update(
                {
                    "profile": "learning",
                    "mode": "standalone",
                    "distribution": ctx.project_name,
                    "root": str(ctx.target_path),
                }
            )
        elif result.success and request is not None:
            register_protocol_profile(ctx.target_path, request.domain)
            result_data.update(
                {
                    "profile": request.profile,
                    "mode": "standalone",
                    "distribution": ctx.project_name,
                    "root": str(ctx.target_path),
                }
            )
        return ToolResult(
            success=result.success,
            data=result_data,
            text=(
                _render_scaffold_text(
                    label=ctx.project_name,
                    kind=template_type.value,
                    files=files,
                )
                if result.success
                else None
            ),
            error=None if result.success else result.message,
        )

    def _dispatch_kind(
        self,
        kind: str | None,
        *,
        target_path: Path,
        name: str | None,
        description: str,
        meta: _ProjectMeta,
    ) -> ToolResult | None:
        """Route the paper and experiment kinds.

        Returns ``None`` when *kind* is not one of them, so the caller falls
        through to the member / workspace / standalone cascade.
        """
        label = name or target_path.name
        if kind == "paper":
            return self._scaffold_paper(
                target_path,
                paper_name=label,
                meta=meta,
                description=description,
            )
        if kind == "experiment":
            return self._scaffold_experiment(
                target_path,
                experiment_name=label,
                description=description,
            )
        return None

    def _scaffold_paper(
        self,
        target_path: Path,
        *,
        paper_name: str,
        meta: _ProjectMeta,
        description: str,
    ) -> ToolResult:
        """Direct obsolete paper creation to the edition-aware Lab tool."""
        return ToolResult(
            success=False,
            error=(
                "Paper scaffolding is owned by axm-lab; use paper_scaffold "
                "with workspace, venue, year and slug."
            ),
        )

    def _scaffold_experiment(
        self, target_path: Path, *, experiment_name: str, description: str
    ) -> ToolResult:
        """Refuse retired scaffolding and direct callers to Lab's owned workflow."""
        return ToolResult(
            success=False,
            error=(
                "Experiment scaffolding is owned by axm-lab "
                "investigations/experiments 2.0; install axm-lab and use its "
                "experiment_scaffold tool with an investigation owner."
            ),
        )

    @staticmethod
    def _resolve_workspace_root(target_path: Path) -> Path | None:
        """Resolve workspace root from target path, or None if not in a workspace."""
        return resolve_workspace_root(target_path)

    def _scaffold_member(
        self,
        target_path: Path,
        member_name: str,
        *,
        scaffold_data: dict[str, str],
        license_holder: str | None = None,
        private: bool | None = None,
        learning: bool = False,
        learning_domain: str | None = None,
    ) -> ToolResult:
        """Scaffold a member sub-package inside an existing workspace.

        Args:
            target_path: Current directory (must be inside a workspace).
            member_name: Name of the new member package.
            scaffold_data: Template variables (org, author, email, etc.).
            license_holder: Explicit LICENSE holder; falls back to ``org``.
            private: Publication guard forwarded to Copier when provided.

        Returns:
            ToolResult with member scaffold results.
        """
        from axm_init.adapters.copier import CopierAdapter, CopierConfig
        from axm_init.adapters.workspace_patcher import patch_all
        from axm_init.core.templates import TemplateType, get_template_path
        from axm_init.scaffolding import (
            ScaffoldRequest,
            _finalize_provider,
            _provider_layers,
            load_provider,
        )

        workspace_root = self._resolve_workspace_root(target_path)
        if workspace_root is None:
            return ToolResult(success=False, error="Not inside a UV workspace")

        member_dir = workspace_root / "packages" / member_name
        module_name = member_name.replace("-", "_")
        requested_learning_domain = learning_domain or module_name
        reconcile_learning = False
        if member_dir.exists() and learning:
            existing_domain = declared_learning_domain(
                member_dir, requested_learning_domain
            )
            reconcile_learning = existing_domain == requested_learning_domain or (
                (member_dir / "pyproject.toml").is_file()
            )
        if member_dir.exists() and not reconcile_learning:
            return ToolResult(
                success=False,
                error=f"Member '{member_name}' already exists at {member_dir}",
            )

        recipe_path = member_dir / "src" / module_name / "recipe.py"
        recipe_bytes = (
            recipe_path.read_bytes()
            if reconcile_learning and recipe_path.is_file()
            else None
        )
        data = build_member_data(
            member_name,
            read_workspace_name(workspace_root),
            scaffold_data,
            license_holder=license_holder,
            private=private,
        )
        if learning:
            data.update(
                {
                    "package_name": member_name.replace("_", "-"),
                    "learning_mode": "standalone",
                    "domain": requested_learning_domain,
                }
            )

        copier_adapter = CopierAdapter()

        learning_request = ScaffoldRequest(
            "learning", member=True, existing=reconcile_learning
        )
        layers = _provider_layers(learning_request) if learning else None
        if layers is not None:
            result = copier_adapter.apply_chain(list(layers), member_dir, data)
        else:
            copier_config = CopierConfig(
                template_path=get_template_path(TemplateType.MEMBER),
                destination=member_dir,
                data=data,
                trust_template=True,
                overwrite=reconcile_learning,
            )
            result = copier_adapter.copy(copier_config)
        if recipe_bytes is not None:
            recipe_path.write_bytes(recipe_bytes)

        if not result.success:
            return ToolResult(
                success=False,
                error=result.message or "Member scaffold failed",
            )

        if layers is not None:
            _finalize_provider(
                load_provider("learning"), learning_request, member_dir, data
            )

        report = patch_all(workspace_root, member_name)

        files = [str(f) for f in result.files_created]
        result_data: dict[str, object] = {
            "member": member_name,
            "path": str(member_dir),
            "files": files,
            "patched_root_files": report.patched,
            "skipped_root_files": report.skipped,
            "failed_root_files": report.failed,
        }
        if learning:
            result_data.update(
                {
                    "profile": "learning",
                    "mode": "member",
                    "distribution": member_name,
                    "root": str(member_dir),
                }
            )
        return ToolResult(
            success=True,
            data=result_data,
            text=_render_scaffold_text(
                label=member_name,
                kind="learning" if learning else "member",
                files=files,
                path=str(member_dir),
                report=report,
            ),
        )

kinds property

Scaffold kinds this tool declares, in template order.

The declared set is the tool's contract: every value is selectable through the kind input (MCP) and --kind (CLI), and each one routes either to a bundled template or the protocol scaffolder.

name property

Tool name used for MCP registration.

execute(path='.', *, name=None, org='', author='', email='', license='Apache-2.0', license_holder=None, description='', private=True, workspace=False, member=None, framework=Framework.PYTHON.value, kind=None, check_pypi=False, json_output=False, profile=None, domain=None, unit=None, protocols=None, preview=False)

Initialize a new Python project.

Parameters:

Name	Type	Description	Default
path	str	Path to initialize project.	'.'
name	str | None	Project name (defaults to directory name).	None
org	str	GitHub org or username.	''
author	str	Author name.	''
email	str	Author email.	''
license	str	License type.	'Apache-2.0'
license_holder	str | None	License holder (defaults to org).	None
description	str	Project description.	''
private	bool	If True, prevent publication to PyPI.	True
workspace	bool	If True, scaffold a UV workspace.	False
member	str | None	Member package name to scaffold inside a workspace.	None
framework	str	Target framework (python, node, svelte).	value
kind	str | None	Explicit scaffold kind — one of SCAFFOLD_KINDS (standalone, workspace, member, paper, experiment, learning, protocol_unit, protocol).	None
check_pypi	bool	If True, check name availability on PyPI.	False
json_output	bool	If True, render the structured report.	False
profile	str | None	Protocol profile to scaffold.	None
domain	str | None	Protocol domain to scaffold.	None
unit	str | None	Protocol unit to scaffold.	None
protocols	list[dict[str, object]] | str | None	Protocol definitions, as objects or a JSON string.	None
preview	bool	If True, report the planned protocol scaffold without writing it.	False

Returns:

Type	Description
ToolResult	ToolResult with created files list.

Source code in packages/axm-init/src/axm_init/tools/scaffold.py

def execute(
    self,
    path: str = ".",
    *,
    name: str | None = None,
    org: str = "",
    author: str = "",
    email: str = "",
    license: str = "Apache-2.0",
    license_holder: str | None = None,
    description: str = "",
    # Safe default: removing one classifier is reversible; a PyPI upload is not.
    private: bool = True,
    workspace: bool = False,
    member: str | None = None,
    framework: str = Framework.PYTHON.value,
    kind: str | None = None,
    check_pypi: bool = False,
    json_output: bool = False,
    profile: str | None = None,
    domain: str | None = None,
    unit: str | None = None,
    protocols: list[dict[str, object]] | str | None = None,
    preview: bool = False,
) -> ToolResult:
    """Initialize a new Python project.

    Args:
        path: Path to initialize project.
        name: Project name (defaults to directory name).
        org: GitHub org or username.
        author: Author name.
        email: Author email.
        license: License type.
        license_holder: License holder (defaults to org).
        description: Project description.
        private: If True, prevent publication to PyPI.
        workspace: If True, scaffold a UV workspace.
        member: Member package name to scaffold inside a workspace.
        framework: Target framework (python, node, svelte).
        kind: Explicit scaffold kind — one of ``SCAFFOLD_KINDS``
            (standalone, workspace, member, paper, experiment,
            learning, protocol_unit, protocol).
        check_pypi: If True, check name availability on PyPI.
        json_output: If True, render the structured report.
        profile: Protocol profile to scaffold.
        domain: Protocol domain to scaffold.
        unit: Protocol unit to scaffold.
        protocols: Protocol definitions, as objects or a JSON string.
        preview: If True, report the planned protocol scaffold
            without writing it.

    Returns:
        ToolResult with created files list.
    """
    kwargs: dict[str, object] = {
        "path": path,
        "name": name,
        "org": org,
        "author": author,
        "email": email,
        "license": license,
        "license_holder": license_holder,
        "description": description,
        "private": private,
        "workspace": workspace,
        "member": member,
        "framework": framework,
        "kind": kind,
    }
    prepared = self._prepare_context(
        kwargs,
        protocol_options={
            "profile": profile,
            "domain": domain,
            "unit": unit,
            "protocols": protocols,
            "preview": preview,
        },
        check_pypi=check_pypi,
    )
    if isinstance(prepared, ToolResult):
        return _apply_json_output(prepared, json_output)

    try:
        result = (
            _route_protocol_request(prepared.protocol_request, prepared.target_path)
            or self._dispatch_kind(
                prepared.kind,
                target_path=prepared.target_path,
                name=prepared.name,
                description=prepared.description,
                meta=prepared.meta,
            )
            or self._scaffold_from_templates(prepared)
        )
    except Exception as exc:
        result = ToolResult(success=False, error=str(exc))
    return _apply_json_output(result, json_output)

read_workspace_name(workspace_root)

Read the workspace name from pyproject.toml or fall back to dir name.

Source code in packages/axm-init/src/axm_init/core/scaffolder.py

def read_workspace_name(workspace_root: Path) -> str:
    """Read the workspace name from ``pyproject.toml`` or fall back to dir name."""
    root_pyproject = workspace_root / "pyproject.toml"
    if root_pyproject.is_file():
        with open(root_pyproject, "rb") as f:
            root_data = tomllib.load(f)
        return str(root_data.get("project", {}).get("name", workspace_root.name))
    return workspace_root.name