Proposal: Refactor repository to prevent installation conflicts

[Utakata]

Overview

To address the critical conflicts arising from multiple installation methods (as detailed in issue #[INSERT_PREVIOUS_ISSUE_NUMBER_HERE]), this proposal outlines a four-pronged approach to refactor the repository. These changes will create a more robust, stable, and user-friendly installation experience, regardless of the chosen method (npm, pip, or plugin).

Proposed Solutions

Here are four key strategies to eliminate installation conflicts:

---

1. Centralize Version Management 📜

The current source of version mismatch is decentralized versioning across different package managers. We will unify this.

Proposed Changes:

• Create a single source-of-truth file in the repository root, e.g., VERSION.
• Modify the CI/CD pipeline to read the version from this file.
• The pipeline will automatically inject this version into package.json, pyproject.toml, and the plugin's marketplace.json during the build and release process.

Effect:

• Guarantees version consistency. All distribution channels will serve the exact same version of SuperClaude, eliminating version-related bugs.

---

2. Add a Conflict Check to Installers 🧐

Prevent users from accidentally overwriting an existing installation from a different source.

Proposed Changes:

• Upon first installation, create a hidden lock file (e.g., ~/.claude/.installer_source) that records the installation method (pip, npm, plugin).
• Modify the installation scripts (install.py, install.js) to check for this file at the start.
• If the file exists and its content differs from the current installation method, display a clear warning message (e.g., "Warning: SuperClaude is already installed via pip. Overwriting may cause issues. Please uninstall the existing version first.") and abort the installation unless explicitly forced.

Effect:

• Prevents unintentional configuration overwrites and proactively informs the user about potential conflicts.

---

3. Redefine the NPM Package's Role (Wrapper-Only) 🎁

The npm package's current behavior of auto-installing the pip version is a primary source of conflict. We will simplify its role.

Proposed Changes:

• Remove the postinstall script from package.json. The npm package will no longer attempt to run pip install.
• Redefine the npm package as a thin "wrapper" that simply executes the globally available superclaude command.
• Update the documentation to clearly state: "To use the npm package, you must first install SuperClaude via pip or pipx."

Effect:

• Creates a single installation path for the core application (via pip), fundamentally eliminating redundancy and script conflicts. Node.js developers can continue using a familiar npm workflow while relying on a stable Python backend.

---

4. Unify Command Name and Improve Documentation ✍️

Reduce user confusion and guide them toward the best practices.

Proposed Changes:

• Standardize the executable command name to superclaude (lowercase) in both pyproject.toml and package.json. Deprecate any camelCase variants.
• Explicitly state the recommended installation method in installation.md: "The recommended way to install SuperClaude is using pipx."
• Add a dedicated "Troubleshooting" section to the documentation that details the recovery steps for users who have accidentally installed from multiple sources.

Effect:

• Improves user experience by providing a consistent command name and clear, actionable guidance to prevent and resolve installation issues.

New Proposed Workflow Diagram

This diagram illustrates the improved versioning and installation flow after implementing the changes.

graph TD
    subgraph "Phase 1: CI/CD Release Process (Unified Versioning)"
        A[VERSION file] -->|Read by| B(CI/CD Pipeline);
        B -->|Updates version in| C[package.json];
        B -->|Updates version in| D[pyproject.toml];
        B -->|Updates version in| E[marketplace.json];
        C --> F[Publish to npm];
        D --> G[Publish to PyPI];
        E --> H[Publish to Marketplace];
    end

    subgraph "Phase 2: User Installation Flow (Conflict Check)"
        I{"User runs install command<br>(e.g., pipx install superclaude)"} --> J{Check for ~/.claude/.installer_source};
        J -- "Exists & Conflicts" --> K[Show Warning & Abort];
        J -- "Not Found or Matches" --> L[Proceed with Installation];
        L --> M[Install `superclaude` command];
        M --> N[Create/Update ~/.claude/.installer_source];
        N --> O[✅ Success];
    end

Loading