fix: ap init fails when pnpm already exists

Author: softwareentrepreneer

afterpython/doc/CONTRIBUTING.md

@@ -45,6 +45,10 @@ favicon = "favicon.svg"
 logo = "logo.svg"
 logo_dark = "logo.svg"
 thumbnail = "thumbnail.png"
+announcement = ""
+# using marimo notebook (README.py) in the landing page, useful for showcasing project demos
+readme_py = "wasm"  # marimo html export format: "wasm" or "static"
+execute_readme_py = false  # execute README.py cells at build time and embed outputs as a preview (wasm mode only)
 api_reference = false  # set to true to enable the pdoc-generated API reference
 ```
 

afterpython/doc/concepts.md

@@ -25,8 +25,8 @@
 - Go from writing to **website deployment in minutes** — no need to learn any of the underlying tools
 - Centralize all your content in a modern, **unified project website** — from documentation to blog posts
 - Zero-config orchestration — Pre-configured modern tooling with sane defaults (see [](overview.md#tech-stack)), so you can start maintaining packages immediately **without learning each tool**
+- **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
 - 🚧 Export content as PDF — for example, combine all blog posts into a single PDF file
-- 🚧 **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
 - 🚧 **🤖 Embedded AI Chatbot** that answers questions directly using an in-browser LLM — at no cost
 
 

afterpython/doc/overview.md

@@ -43,6 +43,16 @@ def init_py_typed():
     click.echo(f"Created {py_typed_path}")
 
 
+def _preflight_init(skip_website: bool) -> None:
+    """Validate external prerequisites before any filesystem writes, so a
+    failure aborts cleanly instead of leaving a half-initialized project."""
+    if not skip_website:
+        from afterpython.tools.myst import ensure_pnpm_11
+        from afterpython.utils import find_node_env
+
+        ensure_pnpm_11(find_node_env())
+
+
 @click.group(invoke_without_command=True)
 @click.option(
     "--yes",
@@ -70,48 +80,60 @@ def init(ctx, yes, skip_website: bool):
     from afterpython.tools.pre_commit import init_pre_commit
     from afterpython.tools.pyproject import init_pyproject
 
+    _preflight_init(skip_website)
+
     paths = ctx.obj["paths"]
     click.echo("Initializing afterpython...")
     afterpython_path = paths.afterpython_path
     static_path = paths.static_path
 
-    afterpython_path.mkdir(parents=True, exist_ok=True)
-    static_path.mkdir(parents=True, exist_ok=True)
-
-    init_pyproject()
-
-    init_afterpython()
-
-    if not skip_website:
-        subprocess.run(["ap", "init", "website"])
-
-    # TODO: add type checking related stuff here
-    init_py_typed()
-
-    create_workflow("ci")
-
-    if yes or click.confirm(
-        f"\nCreate .pre-commit-config.yaml in {afterpython_path}?", default=True
-    ):
-        init_pre_commit()
-
-    if yes or click.confirm(f"\nCreate ruff.toml in {afterpython_path}?", default=True):
-        init_ruff_toml()
-
-    if yes or click.confirm(
-        f"\nCreate commitizen configuration (cz.toml) in {afterpython_path} "
-        f"and release workflow in .github/workflows/release.yml?",
-        default=True,
-    ):
-        init_commitizen()
-        create_workflow("release")
-
-    if yes or click.confirm(
-        "\nCreate Dependabot configuration (.github/dependabot.yml) "
-        "to auto-update GitHub Actions versions?",
-        default=True,
-    ):
-        create_dependabot()
+    try:
+        afterpython_path.mkdir(parents=True, exist_ok=True)
+        static_path.mkdir(parents=True, exist_ok=True)
+
+        init_pyproject()
+
+        init_afterpython()
+
+        if not skip_website:
+            # check=True so a failure inside `ap init website` aborts the parent
+            # run instead of silently continuing to write more files.
+            subprocess.run(["ap", "init", "website"], check=True)
+
+        # TODO: add type checking related stuff here
+        init_py_typed()
+
+        create_workflow("ci")
+
+        if yes or click.confirm(
+            f"\nCreate .pre-commit-config.yaml in {afterpython_path}?", default=True
+        ):
+            init_pre_commit()
+
+        if yes or click.confirm(
+            f"\nCreate ruff.toml in {afterpython_path}?", default=True
+        ):
+            init_ruff_toml()
+
+        if yes or click.confirm(
+            f"\nCreate commitizen configuration (cz.toml) in {afterpython_path} "
+            f"and release workflow in .github/workflows/release.yml?",
+            default=True,
+        ):
+            init_commitizen()
+            create_workflow("release")
+
+        if yes or click.confirm(
+            "\nCreate Dependabot configuration (.github/dependabot.yml) "
+            "to auto-update GitHub Actions versions?",
+            default=True,
+        ):
+            create_dependabot()
+    except BaseException:
+        if afterpython_path.exists():
+            click.echo(f"ap init failed — removing {afterpython_path}", err=True)
+            shutil.rmtree(afterpython_path, ignore_errors=True)
+        raise
 
 
 @init.command("website")
@@ -122,10 +144,18 @@ def init_website_subcommand():
     the website to an existing AfterPython project.
     """
     from afterpython.tools.github_actions import create_workflow
-    from afterpython.tools.myst import init_myst
+    from afterpython.tools.myst import ensure_pnpm_11, init_myst
+    from afterpython.utils import find_node_env
+
+    # Pre-flight: same rationale as `ap init` — guard the standalone entry too,
+    # since this subcommand can be invoked directly via `ap init website`.
+    ensure_pnpm_11(find_node_env())
 
     init_faq()
     init_myst()
     click.echo(f"Initializing project website template in {ap.paths.website_path}...")
-    subprocess.run(["ap", "update", "website"])
+    # check=True so a network/pnpm failure inside `ap update website` aborts
+    # the subcommand instead of silently dropping the deploy workflow on top
+    # of a broken website install.
+    subprocess.run(["ap", "update", "website"], check=True)
     create_workflow("deploy")

src/afterpython/cli/commands/init.py

@@ -179,6 +179,56 @@ def _write_welcome_file(content_type: tContentType):
     return welcome_file
 
 
+def ensure_pnpm_11(node_env: NodeEnv) -> None:
+    """Ensure pnpm 11.x is available on `node_env`'s PATH. No-op if already satisfied.
+
+    Pinned to major 11 because an unpinned `npm install -g pnpm` previously did
+    a silent 9→10 jump that broke `ap init` via ERR_PNPM_IGNORED_BUILDS. We
+    pre-check the installed version so we don't redundantly invoke `npm install
+    -g`, which fails with EEXIST when pnpm was installed by a different package
+    manager (e.g. Homebrew) that owns the shim filenames npm wants to write.
+    """
+    current: str | None = None
+    try:
+        result = subprocess.run(
+            ["pnpm", "--version"],
+            env=node_env,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode == 0:
+            current = result.stdout.strip()
+            if current.startswith("11."):
+                return
+    except FileNotFoundError:
+        pass
+
+    install = subprocess.run(
+        ["npm", "install", "-g", "pnpm@11"],
+        env=node_env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if install.returncode == 0:
+        return
+
+    msg = ["Failed to install pnpm@11 via npm."]
+    if current:
+        msg.append(f"Detected existing pnpm version: {current}")
+    msg.append(
+        "If pnpm is already installed via another package manager "
+        "(e.g. Homebrew: `brew install pnpm`), npm refuses to overwrite "
+        "its shims. Please either:\n"
+        "  - upgrade your existing pnpm to major version 11, or\n"
+        "  - uninstall it and let afterpython manage pnpm via npm."
+    )
+    if install.stderr:
+        msg.append(f"\nnpm stderr:\n{install.stderr}")
+    raise RuntimeError("\n".join(msg))
+
+
 def init_myst():
     """
     Initialize MyST Markdown (mystmd) and myst.yml files in
@@ -189,14 +239,19 @@ def init_myst():
 
     # find any existing node.js version and use it, if no, install the Node.js version specified in NODEENV_VERSION
     node_env: NodeEnv = find_node_env()
-    # Pin to pnpm major version — `npm install -g pnpm` (unpinned) caused a
-    # silent 9→10 jump that broke `ap init` via ERR_PNPM_IGNORED_BUILDS.
-    subprocess.run(["npm", "install", "-g", "pnpm@11"], env=node_env, check=True)
+    ensure_pnpm_11(node_env)
     for content_type in CONTENT_TYPES:
         path = ap.paths.afterpython_path / content_type
         print(f"Initializing MyST Markdown (mystmd) in {path.name}/ directory ...")
         path.mkdir(parents=True, exist_ok=True)
-        subprocess.run(["myst", "init"], cwd=path, input="n\n", text=True, env=node_env)
+        subprocess.run(
+            ["myst", "init"],
+            cwd=path,
+            input="n\n",
+            text=True,
+            env=node_env,
+            check=True,
+        )
         myst_yml_defaults = {
             "extends": "../authors.yml",
             "project": {