protostar 0.1.0__tar.gz

protostar-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: Bug Report
+description: Report a reproducible issue with environment scaffolding.
+title: "bug: <short description>"
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Thank you for reporting an issue.** To help reduce debugging entropy, please provide the exact state of your environment.
+  - type: input
+    id: version
+    attributes:
+      label: Protostar Version
+      description: What version of Protostar are you running?
+      placeholder: "e.g., 0.1.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows (WSL)
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: command
+    attributes:
+      label: Command Executed
+      description: What exact command did you run?
+      placeholder: "protostar --python --scientific"
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior / Traceback
+      description: What actually happened? Paste any error output here.
+      render: shell
+    validations:
+      required: true

protostar-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: GitHub Discussions
+    url: https://github.com/jacksonfergusondev/protostar/discussions
+    about: Please ask questions and discuss ideas here before opening an issue.

protostar-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature Request
+description: Propose a new language module, IDE integration, or preset.
+title: "feat: <short description>"
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Proposing an addition to the Accretion Engine**
+        Protostar thrives on vertical integration. If you are proposing a new language or framework, please outline the exact files/commands it requires.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The Problem (Logistical Entropy)
+      description: What manual configuration are you constantly doing that Protostar should automate?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Implementation
+      description: What specific CLI commands (e.g., `cargo init`) and ignores (e.g., `node_modules/`) does this require?
+    validations:
+      required: true

protostar-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    name: Test on ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12", "3.14"]
+
+    steps:
+    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Lint with Ruff
+      run: |
+        uv run ruff check .
+        uv run ruff format --check .
+
+    - name: Lint Markdown
+      run: npx --yes markdownlint-cli "**/*.md" --ignore ".venv"
+
+    - name: Type check with Mypy
+      run: uv run mypy .
+
+    - name: Run tests
+      run: uv run pytest

protostar-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-n-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      with:
+        python-version: "3.14"
+
+    - name: Build distribution
+      run: uv build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  update-homebrew:
+    needs: build-n-publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Update Homebrew Formula
+        uses: mislav/bump-homebrew-formula-action@v3
+        with:
+          formula-name: protostar
+          homebrew-tap: JacksonFergusonDev/homebrew-tap
+          download-url: https://github.com/JacksonFergusonDev/protostar/archive/refs/tags/${{ github.ref_name }}.tar.gz
+        env:
+          COMMITTER_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}

protostar-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.DS_Store
+dist/
+build/
+*.egg-info/
+.env
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+.ipynb_checkpoints/
+.mypy_cache/

protostar-0.1.0/.markdownlint.yaml

@@ -0,0 +1,54 @@
+# .markdownlint.yaml
+
+# Inherit default rules
+default: true
+
+# --- Disabled Rules ---
+
+# MD013: Line length
+# Rationale: Hard-wrapping text disrupts IDE reading flow, breaks URLs, and creates arbitrary diff churn.
+MD013: false
+
+# MD033: Inline HTML
+# Rationale: Required for layout elements unsupported by strict Markdown (e.g., <details> blocks, complex tables).
+MD033: false
+
+# --- Refined Rules ---
+
+# MD024: Multiple headings with the same content
+# Rationale: Allows duplicate subheadings (e.g., "Parameters") under different primary function headings.
+MD024:
+  siblings_only: true
+
+# --- AST/Parser Enforcement ---
+
+# MD031: Fenced code blocks should be surrounded by blank lines
+# Rationale: Prevents strict parsers from rendering backticks as raw text instead of <pre><code> blocks.
+MD031: true
+
+# MD032: Lists should be surrounded by blank lines
+# Rationale: Prevents contiguous text from merging into lists, ensuring correct AST generation.
+MD032: true
+
+# --- Structural Consistency ---
+
+# MD003: Heading style
+# Rationale: Enforces ATX style (# Heading) exclusively.
+MD003:
+  style: "atx"
+
+# MD004: Unordered list style
+# Rationale: Enforces dash markers for consistency across the syntax tree.
+MD004:
+  style: "dash"
+
+# MD009: Trailing spaces
+# Rationale: Allows exactly two spaces for hard line breaks; flags arbitrary whitespace.
+MD009:
+  br_spaces: 2
+  strict: false
+
+# MD029: Ordered list item prefix
+# Rationale: Enforces the "one" style (1., 1., 1.) to minimize Git diff noise when rearranging list items.
+MD029:
+  style: "one"

protostar-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  # 1. Generic hooks (configured to IGNORE Python)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: \.py$
+      - id: end-of-file-fixer
+        exclude: \.py$
+      - id: check-yaml
+      - id: check-added-large-files
+
+  # 2. Python-specific toolchain
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.11
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [ --fix ]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+
+  # 3. Markdown linting
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.47.0
+    hooks:
+      - id: markdownlint
+        args: ["--fix"] # Automatically resolves formatting deviations

protostar-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

protostar-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly.

protostar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jackson Ferguson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

protostar-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: protostar
+Version: 0.1.0
+Summary: High-velocity, zero-friction environment scaffolding.
+Project-URL: Repository, https://github.com/jacksonfergusondev/protostar
+Project-URL: Issues, https://github.com/jacksonfergusondev/protostar/issues
+Author-email: jackson.ferguson0@gmail.com
+License: MIT License
+        
+        Copyright (c) 2026 Jackson Ferguson
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: rich>=14.2.0
+Description-Content-Type: text/markdown
+
+# 🌟 Protostar (v0.1.0)
+
+[![CI](https://github.com/jacksonfergusondev/protostar/actions/workflows/ci.yml/badge.svg)](https://github.com/jacksonfergusondev/protostar/actions/workflows/ci.yml)
+[![Release](https://github.com/jacksonfergusondev/protostar/actions/workflows/release.yml/badge.svg)](https://github.com/jacksonfergusondev/protostar/actions/workflows/release.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**A modular CLI tool for quickly scaffolding software environments.**
+
+Setting up a new project often requires the same manual steps: configuring linters, writing `.gitignore` files, setting up virtual environments, and linking IDEs. Protostar automates this boilerplate so you can skip the setup and get straight to writing code.
+
+---
+
+## 💡 Design Philosophy
+
+While Protostar is a lightweight utility, it was built around two specific structural concepts:
+
+### 1. Deterministic Execution
+
+Most bootstrapping scripts run a sequence of shell commands and fail unpredictably if a dependency is missing. Protostar separates state definition from execution. It uses an internal `EnvironmentManifest` where modules (Python, Rust, Linux, etc.) append their requirements. Disk I/O and subprocesses only occur at the very end, ensuring the environment is generated safely without clobbering existing files.
+
+### 2. Signal vs. Noise
+
+Project configuration is necessary noise; writing logic is the signal. By vertically integrating the OS, IDE, and Language strata into a single command, Protostar attempts to reduce the logistical entropy of starting a new repository.
+
+---
+
+## 📦 Installation
+
+### macOS (Homebrew)
+
+If you are on macOS, you can install via Homebrew:
+
+```bash
+brew tap jacksonfergusondev/tap
+brew install protostar
+```
+
+### Universal (uv)
+
+For isolated CLI tool installation on any OS, `uv` is recommended:
+
+```bash
+uv tool install protostar
+```
+
+### Universal (pip)
+
+You can also install it into your active environment using standard pip:
+
+```bash
+pip install protostar
+```
+
+---
+
+## 🚀 Usage
+
+Protostar is designed to be run right after you `mkdir` a new project.
+
+### Basic Scaffolding
+
+Navigate to your empty directory and specify the languages you are using. The OS and IDE configurations are automatically inferred from your system and global settings.
+
+```bash
+mkdir orbital-mechanics-sim
+cd orbital-mechanics-sim
+protostar --python --cpp
+```
+
+*Result: Initializes `uv`, scaffolds a Python environment, configures C++ build exclusions, and generates your `.vscode/settings.json`.*
+
+### The Scientific Preset
+
+If you are building a data analysis pipeline, use the scientific preset to pre-load a standard analytical stack.
+
+```bash
+protostar --python --scientific
+```
+
+*Result: Installs the Python scientific stack (`numpy`, `scipy`, `pandas`, `matplotlib`, `seaborn`, `ipykernel`) into the new environment.*
+
+---
+
+## 🛠 Command Reference
+
+| Flag / Command | Description |
+| :--- | :--- |
+| `--python` | Scaffolds a Python environment using `uv`. Ignores caches and venvs. |
+| `--rust` | Scaffolds a Rust environment using `cargo`. Ignores targets. |
+| `--node` | Scaffolds a Node.js/TypeScript environment. Ignores `node_modules`. |
+| `--cpp` | Configures a C/C++ footprint (ignores `build/`, `*.o`, `compile_commands.json`). |
+| `--latex` | Configures a LaTeX footprint (ignores `*.aux`, `*.log`, `*.synctex.gz`). |
+| `--scientific` | Injects foundational computational and statistical libraries (Python only). |
+
+---
+
+## ⚙️ Configuration
+
+You can set global defaults in `~/.config/protostar/config.toml` so you don't have to specify your IDE or package manager preferences manually.
+
+```toml
+[env]
+# Options: "vscode", "cursor", "jetbrains", "none"
+ide = "vscode"
+
+# Options: "npm", "pnpm", "yarn"
+node_package_manager = "npm"
+```
+
+---
+
+## 🤝 Collaboration & Extension
+
+This tool uses a decoupled `BootstrapModule` architecture. Adding support for a new language or framework requires writing a single class that appends rules to the `EnvironmentManifest`. Feel free to open an issue or pull request if you'd like to see a specific toolchain supported.
+
+## 📧 Contact
+
+### Jackson Ferguson
+
+- **GitHub:** [@JacksonFergusonDev](https://github.com/JacksonFergusonDev)
+- **LinkedIn:** [Jackson Ferguson](https://www.linkedin.com/in/jackson--ferguson/)
+- **Email:** <jackson.ferguson0@gmail.com>
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

protostar-0.1.0/README.md

@@ -0,0 +1,129 @@
+# 🌟 Protostar (v0.1.0)
+
+[![CI](https://github.com/jacksonfergusondev/protostar/actions/workflows/ci.yml/badge.svg)](https://github.com/jacksonfergusondev/protostar/actions/workflows/ci.yml)
+[![Release](https://github.com/jacksonfergusondev/protostar/actions/workflows/release.yml/badge.svg)](https://github.com/jacksonfergusondev/protostar/actions/workflows/release.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**A modular CLI tool for quickly scaffolding software environments.**
+
+Setting up a new project often requires the same manual steps: configuring linters, writing `.gitignore` files, setting up virtual environments, and linking IDEs. Protostar automates this boilerplate so you can skip the setup and get straight to writing code.
+
+---
+
+## 💡 Design Philosophy
+
+While Protostar is a lightweight utility, it was built around two specific structural concepts:
+
+### 1. Deterministic Execution
+
+Most bootstrapping scripts run a sequence of shell commands and fail unpredictably if a dependency is missing. Protostar separates state definition from execution. It uses an internal `EnvironmentManifest` where modules (Python, Rust, Linux, etc.) append their requirements. Disk I/O and subprocesses only occur at the very end, ensuring the environment is generated safely without clobbering existing files.
+
+### 2. Signal vs. Noise
+
+Project configuration is necessary noise; writing logic is the signal. By vertically integrating the OS, IDE, and Language strata into a single command, Protostar attempts to reduce the logistical entropy of starting a new repository.
+
+---
+
+## 📦 Installation
+
+### macOS (Homebrew)
+
+If you are on macOS, you can install via Homebrew:
+
+```bash
+brew tap jacksonfergusondev/tap
+brew install protostar
+```
+
+### Universal (uv)
+
+For isolated CLI tool installation on any OS, `uv` is recommended:
+
+```bash
+uv tool install protostar
+```
+
+### Universal (pip)
+
+You can also install it into your active environment using standard pip:
+
+```bash
+pip install protostar
+```
+
+---
+
+## 🚀 Usage
+
+Protostar is designed to be run right after you `mkdir` a new project.
+
+### Basic Scaffolding
+
+Navigate to your empty directory and specify the languages you are using. The OS and IDE configurations are automatically inferred from your system and global settings.
+
+```bash
+mkdir orbital-mechanics-sim
+cd orbital-mechanics-sim
+protostar --python --cpp
+```
+
+*Result: Initializes `uv`, scaffolds a Python environment, configures C++ build exclusions, and generates your `.vscode/settings.json`.*
+
+### The Scientific Preset
+
+If you are building a data analysis pipeline, use the scientific preset to pre-load a standard analytical stack.
+
+```bash
+protostar --python --scientific
+```
+
+*Result: Installs the Python scientific stack (`numpy`, `scipy`, `pandas`, `matplotlib`, `seaborn`, `ipykernel`) into the new environment.*
+
+---
+
+## 🛠 Command Reference
+
+| Flag / Command | Description |
+| :--- | :--- |
+| `--python` | Scaffolds a Python environment using `uv`. Ignores caches and venvs. |
+| `--rust` | Scaffolds a Rust environment using `cargo`. Ignores targets. |
+| `--node` | Scaffolds a Node.js/TypeScript environment. Ignores `node_modules`. |
+| `--cpp` | Configures a C/C++ footprint (ignores `build/`, `*.o`, `compile_commands.json`). |
+| `--latex` | Configures a LaTeX footprint (ignores `*.aux`, `*.log`, `*.synctex.gz`). |
+| `--scientific` | Injects foundational computational and statistical libraries (Python only). |
+
+---
+
+## ⚙️ Configuration
+
+You can set global defaults in `~/.config/protostar/config.toml` so you don't have to specify your IDE or package manager preferences manually.
+
+```toml
+[env]
+# Options: "vscode", "cursor", "jetbrains", "none"
+ide = "vscode"
+
+# Options: "npm", "pnpm", "yarn"
+node_package_manager = "npm"
+```
+
+---
+
+## 🤝 Collaboration & Extension
+
+This tool uses a decoupled `BootstrapModule` architecture. Adding support for a new language or framework requires writing a single class that appends rules to the `EnvironmentManifest`. Feel free to open an issue or pull request if you'd like to see a specific toolchain supported.
+
+## 📧 Contact
+
+### Jackson Ferguson
+
+- **GitHub:** [@JacksonFergusonDev](https://github.com/JacksonFergusonDev)
+- **LinkedIn:** [Jackson Ferguson](https://www.linkedin.com/in/jackson--ferguson/)
+- **Email:** <jackson.ferguson0@gmail.com>
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.