pucit 0.1.0__tar.gz

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

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q
+
+      - name: CLI smoke
+        shell: bash
+        run: |
+          pucit version
+          pucit --help
+          pucit doctor

pucit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pucit
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pucit-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Packaging / envs
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Local tooling
+*.log
+.pucit/

pucit-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mudassir Ashraf
+
+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.

pucit-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: pucit
+Version: 0.1.0
+Summary: PUCIT student toolkit CLI — Oracle, PF/C++, campus bypass, and ease-of-use commands
+Project-URL: Documentation, https://github.com/mudassir-cpp/pucit#readme
+Project-URL: Issues, https://github.com/mudassir-cpp/pucit/issues
+Project-URL: Source, https://github.com/mudassir-cpp/pucit
+Author-email: MIZI <gem920se@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: PUCIT,bypass,cpp,docker,g++,oracle,pucit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.8
+Requires-Dist: bypass-pucit>=0.0.2
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pucit
+
+PUCIT student toolkit CLI — install Oracle (Docker), set up PF/C++ essentials, campus proxy bypass, and compile/run lab code in one command.
+
+```bash
+pip install pucit
+# or from source:
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```bash
+pucit doctor
+pucit install pf
+pucit run main.cpp
+```
+
+## Commands
+
+### C++ labs (ease)
+
+| Command | What it does |
+|---|---|
+| `pucit run main.cpp` | Compile with `g++` into `build/`, then run — no `./a.out` |
+| `pucit compile main.cpp` | Compile only |
+| `pucit debug main.cpp` | Compile with `-g` and open `gdb` |
+| `pucit watch main.cpp` | Recompile + run on save |
+| `pucit clean` | Remove `build/` and `a.out` |
+| `pucit new hello` | Create `hello.cpp` from template |
+| `pucit init` | Scaffold `main.cpp` + `Makefile` + `.gitignore` |
+
+Extras:
+
+```bash
+pucit run main.cpp util.cpp
+pucit run main.cpp -f "-O2 -std=c++20"
+pucit run main.cpp -i input.txt
+```
+
+### Oracle (Docker)
+
+```bash
+pucit install oracle
+pucit start oracle
+pucit stop oracle
+pucit status oracle
+pucit logs oracle
+pucit oracle connect
+pucit oracle rm
+```
+
+Uses Oracle Database Free image `container-registry.oracle.com/database/free:latest` as container `pucit-oracle` on port `1521`. Password is saved under `~/.config/pucit/oracle.env`.
+
+If pull fails with auth errors, accept the license on [Oracle Container Registry](https://container-registry.oracle.com/), then `docker login container-registry.oracle.com` and retry.
+
+### Tooling / campus net
+
+```bash
+pucit install pf          # g++, make, gdb, cmake
+pucit install docker
+pucit install sqlclient   # Instant Client / sqlplus guidance
+pucit bypass set          # wraps bypass-pucit
+pucit bypass unset
+pucit doctor
+pucit list
+pucit which g++
+pucit open .
+```
+
+## Supported OS
+
+Linux (dnf/apt/…) and Windows (winget/choco) for installers. `run` / `compile` work anywhere `g++` or `clang++` is available.
+
+## Development / CI
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+GitHub Actions:
+
+- **CI** (`.github/workflows/ci.yml`) — tests on Linux + Windows for Python 3.10–3.13
+- **Publish** (`.github/workflows/publish.yml`) — uploads to PyPI on GitHub Release (Trusted Publisher / OIDC)
+
+### First PyPI publish
+
+1. On PyPI → **Publishing** → add a **pending trusted publisher**:
+   - Project: `pucit`
+   - Owner: `mudassir-cpp`
+   - Repo: `pucit`
+   - Workflow: `publish.yml`
+   - Environment: `pypi`
+2. On GitHub → **Settings → Environments → New** → name it `pypi` (optional approval rule recommended).
+3. Create a Release (e.g. tag `v0.1.0`) — the publish workflow runs and creates the PyPI project.
+
+## License
+
+MIT — see `LICENSE.txt`.

pucit-0.1.0/README.md

@@ -0,0 +1,100 @@
+# pucit
+
+PUCIT student toolkit CLI — install Oracle (Docker), set up PF/C++ essentials, campus proxy bypass, and compile/run lab code in one command.
+
+```bash
+pip install pucit
+# or from source:
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```bash
+pucit doctor
+pucit install pf
+pucit run main.cpp
+```
+
+## Commands
+
+### C++ labs (ease)
+
+| Command | What it does |
+|---|---|
+| `pucit run main.cpp` | Compile with `g++` into `build/`, then run — no `./a.out` |
+| `pucit compile main.cpp` | Compile only |
+| `pucit debug main.cpp` | Compile with `-g` and open `gdb` |
+| `pucit watch main.cpp` | Recompile + run on save |
+| `pucit clean` | Remove `build/` and `a.out` |
+| `pucit new hello` | Create `hello.cpp` from template |
+| `pucit init` | Scaffold `main.cpp` + `Makefile` + `.gitignore` |
+
+Extras:
+
+```bash
+pucit run main.cpp util.cpp
+pucit run main.cpp -f "-O2 -std=c++20"
+pucit run main.cpp -i input.txt
+```
+
+### Oracle (Docker)
+
+```bash
+pucit install oracle
+pucit start oracle
+pucit stop oracle
+pucit status oracle
+pucit logs oracle
+pucit oracle connect
+pucit oracle rm
+```
+
+Uses Oracle Database Free image `container-registry.oracle.com/database/free:latest` as container `pucit-oracle` on port `1521`. Password is saved under `~/.config/pucit/oracle.env`.
+
+If pull fails with auth errors, accept the license on [Oracle Container Registry](https://container-registry.oracle.com/), then `docker login container-registry.oracle.com` and retry.
+
+### Tooling / campus net
+
+```bash
+pucit install pf          # g++, make, gdb, cmake
+pucit install docker
+pucit install sqlclient   # Instant Client / sqlplus guidance
+pucit bypass set          # wraps bypass-pucit
+pucit bypass unset
+pucit doctor
+pucit list
+pucit which g++
+pucit open .
+```
+
+## Supported OS
+
+Linux (dnf/apt/…) and Windows (winget/choco) for installers. `run` / `compile` work anywhere `g++` or `clang++` is available.
+
+## Development / CI
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+GitHub Actions:
+
+- **CI** (`.github/workflows/ci.yml`) — tests on Linux + Windows for Python 3.10–3.13
+- **Publish** (`.github/workflows/publish.yml`) — uploads to PyPI on GitHub Release (Trusted Publisher / OIDC)
+
+### First PyPI publish
+
+1. On PyPI → **Publishing** → add a **pending trusted publisher**:
+   - Project: `pucit`
+   - Owner: `mudassir-cpp`
+   - Repo: `pucit`
+   - Workflow: `publish.yml`
+   - Environment: `pypi`
+2. On GitHub → **Settings → Environments → New** → name it `pypi` (optional approval rule recommended).
+3. Create a Release (e.g. tag `v0.1.0`) — the publish workflow runs and creates the PyPI project.
+
+## License
+
+MIT — see `LICENSE.txt`.

pucit-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pucit"
+dynamic = ["version"]
+description = "PUCIT student toolkit CLI — Oracle, PF/C++, campus bypass, and ease-of-use commands"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+keywords = ["pucit", "PUCIT", "oracle", "cpp", "g++", "docker", "bypass"]
+authors = [
+  { name = "MIZI", email = "gem920se@gmail.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Education",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Education",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+  "typer>=0.12.0",
+  "rich>=13.0.0",
+  "bypass-pucit>=0.0.2",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/mudassir-cpp/pucit#readme"
+Issues = "https://github.com/mudassir-cpp/pucit/issues"
+Source = "https://github.com/mudassir-cpp/pucit"
+
+[project.scripts]
+pucit = "pucit.cli:app"
+
+[tool.hatch.version]
+path = "src/pucit/__about__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

pucit-0.1.0/src/pucit/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pucit-0.1.0/src/pucit/__init__.py

@@ -0,0 +1,3 @@
+from pucit.__about__ import __version__
+
+__all__ = ["__version__"]

pucit-0.1.0/src/pucit/__main__.py

@@ -0,0 +1,4 @@
+from pucit.cli import app
+
+if __name__ == "__main__":
+    app()

pucit-0.1.0/src/pucit/cli.py

@@ -0,0 +1,258 @@
+"""pucit — PUCIT student toolkit CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+
+from pucit import __version__
+from pucit import cpp_build
+from pucit import docker_util as d
+from pucit.commands.bypass import bypass_app
+from pucit.commands.doctor import run_doctor, run_list
+from pucit.commands.install import install_app
+from pucit.commands.oracle import oracle_app
+from pucit.commands.scaffold import init_project, new_file
+from pucit.util import fail, first_existing, info, ok, run_cmd, run_streaming, which
+
+app = typer.Typer(
+    name="pucit",
+    help="PUCIT student toolkit — Oracle, PF/C++, bypass, and lab ease commands.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.add_typer(install_app, name="install")
+app.add_typer(bypass_app, name="bypass")
+app.add_typer(oracle_app, name="oracle")
+
+
+def _oracle_target(target: str) -> None:
+    if target.lower() not in {"oracle", "db", "oracledb"}:
+        fail(f"Unknown target '{target}'. Try: oracle")
+        raise typer.Exit(1)
+
+
+@app.command("start")
+def start_cmd(target: str = typer.Argument(..., help="Service to start (oracle)")) -> None:
+    """Start a managed service: pucit start oracle"""
+    _oracle_target(target)
+    from pucit.commands.oracle import oracle_start
+
+    oracle_start()
+
+
+@app.command("stop")
+def stop_cmd(target: str = typer.Argument(..., help="Service to stop (oracle)")) -> None:
+    """Stop a managed service: pucit stop oracle"""
+    _oracle_target(target)
+    from pucit.commands.oracle import oracle_stop
+
+    oracle_stop()
+
+
+@app.command("status")
+def status_cmd(target: str = typer.Argument("oracle", help="Service (oracle)")) -> None:
+    """Show service status: pucit status oracle"""
+    _oracle_target(target)
+    from pucit.commands.oracle import oracle_status
+
+    oracle_status()
+
+
+@app.command("logs")
+def logs_cmd(
+    target: str = typer.Argument("oracle"),
+    follow: bool = typer.Option(False, "--follow", "-f"),
+    tail: int = typer.Option(100, "--tail"),
+) -> None:
+    """Show service logs: pucit logs oracle"""
+    _oracle_target(target)
+    from pucit.commands.oracle import oracle_logs
+
+    oracle_logs(follow=follow, tail=tail)
+
+
+@app.command("run")
+def run_cmd(
+    sources: Optional[List[str]] = typer.Argument(None, help="C++ sources (default: main.cpp)"),
+    flags: Optional[str] = typer.Option(None, "--flags", "-f", help='Extra flags e.g. "-O2"'),
+    std: Optional[str] = typer.Option(None, "--std", help="Language standard"),
+    out: Optional[str] = typer.Option(None, "--out", "-o", help="Output binary"),
+    input_file: Optional[str] = typer.Option(None, "--input", "-i", help="stdin from file"),
+) -> None:
+    """Compile and run: pucit run main.cpp"""
+    try:
+        code = cpp_build.execute_run(
+            list(sources or []),
+            flags=flags,
+            std=std,
+            out=out,
+            input_file=input_file,
+        )
+    except (FileNotFoundError, RuntimeError) as exc:
+        fail(str(exc))
+        raise typer.Exit(1) from exc
+    raise typer.Exit(code)
+
+
+@app.command("compile")
+def compile_cmd(
+    sources: Optional[List[str]] = typer.Argument(None),
+    flags: Optional[str] = typer.Option(None, "--flags", "-f"),
+    std: Optional[str] = typer.Option(None, "--std"),
+    out: Optional[str] = typer.Option(None, "--out", "-o"),
+) -> None:
+    """Compile only: pucit compile main.cpp"""
+    try:
+        code = cpp_build.execute_run(
+            list(sources or []),
+            flags=flags,
+            std=std,
+            out=out,
+            compile_only=True,
+        )
+    except (FileNotFoundError, RuntimeError) as exc:
+        fail(str(exc))
+        raise typer.Exit(1) from exc
+    raise typer.Exit(code)
+
+
+@app.command("debug")
+def debug_cmd(
+    sources: Optional[List[str]] = typer.Argument(None),
+    flags: Optional[str] = typer.Option(None, "--flags", "-f"),
+    std: Optional[str] = typer.Option(None, "--std"),
+    out: Optional[str] = typer.Option(None, "--out", "-o"),
+) -> None:
+    """Compile with -g and open gdb."""
+    try:
+        resolved = cpp_build.resolve_sources(list(sources or []))
+        code, binary, _ = cpp_build.compile_sources(
+            resolved, out=out, flags=flags, std=std, debug=True
+        )
+    except (FileNotFoundError, RuntimeError) as exc:
+        fail(str(exc))
+        raise typer.Exit(1) from exc
+    if code != 0:
+        raise typer.Exit(code)
+    gdb = which("gdb")
+    if not gdb:
+        fail("gdb not found. Run: pucit install pf")
+        raise typer.Exit(1)
+    info(f"Starting gdb on {binary}")
+    raise typer.Exit(run_streaming([gdb, str(binary)]))
+
+
+@app.command("watch")
+def watch_cmd(
+    sources: Optional[List[str]] = typer.Argument(None),
+    flags: Optional[str] = typer.Option(None, "--flags", "-f"),
+    std: Optional[str] = typer.Option(None, "--std"),
+    out: Optional[str] = typer.Option(None, "--out", "-o"),
+    input_file: Optional[str] = typer.Option(None, "--input", "-i"),
+) -> None:
+    """Recompile + run on file change."""
+    try:
+        code = cpp_build.watch_run(
+            list(sources or []),
+            flags=flags,
+            std=std,
+            out=out,
+            input_file=input_file,
+        )
+    except (FileNotFoundError, RuntimeError) as exc:
+        fail(str(exc))
+        raise typer.Exit(1) from exc
+    raise typer.Exit(code)
+
+
+@app.command("clean")
+def clean_cmd() -> None:
+    """Remove build/ and a.out in the current directory."""
+    removed = cpp_build.clean_artifacts()
+    if not removed:
+        info("Nothing to clean")
+    else:
+        for path in removed:
+            ok(f"Removed {path}")
+
+
+@app.command("new")
+def new_cmd(
+    name: str = typer.Argument(..., help="File or stem, e.g. hello or hello.cpp"),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Create a new C++ file from template."""
+    new_file(name, force=force)
+
+
+@app.command("init")
+def init_cmd(force: bool = typer.Option(False, "--force", "-f")) -> None:
+    """Scaffold a PF lab folder (main.cpp, Makefile, .gitignore)."""
+    init_project(force=force)
+
+
+@app.command("doctor")
+def doctor_cmd() -> None:
+    """Check compilers, Docker, Oracle, bypass, and friends."""
+    raise typer.Exit(run_doctor())
+
+
+@app.command("list")
+def list_cmd() -> None:
+    """List managed components and their status."""
+    raise typer.Exit(run_list())
+
+
+@app.command("version")
+def version_cmd() -> None:
+    """Show pucit version."""
+    typer.echo(__version__)
+
+
+@app.command("which")
+def which_cmd(tool: str = typer.Argument(..., help="Tool name, e.g. g++ or docker")) -> None:
+    """Show resolved path for a tool."""
+    # allow g++ style
+    path = which(tool) or first_existing((tool,))
+    if not path and tool in {"g++", "cxx", "compiler"}:
+        path = cpp_build.find_compiler()
+    if not path and tool == "docker":
+        path = d.docker_bin()
+    if path:
+        typer.echo(path)
+    else:
+        fail(f"{tool} not found")
+        raise typer.Exit(1)
+
+
+@app.command("open")
+def open_cmd(path: str = typer.Argument(".", help="Path to open")) -> None:
+    """Open a folder/file in VS Code, Cursor, or the file manager."""
+    target = Path(path).resolve()
+    editors = ("cursor", "code", "codium")
+    for editor in editors:
+        binary = which(editor)
+        if binary:
+            raise typer.Exit(run_cmd([binary, str(target)]).returncode)
+    # fallback file manager / start
+    import sys
+
+    if sys.platform.startswith("win"):
+        raise typer.Exit(run_cmd(["explorer", str(target)]).returncode)
+    opener = which("xdg-open")
+    if opener:
+        raise typer.Exit(run_cmd([opener, str(target)]).returncode)
+    fail("No editor or file manager found")
+    raise typer.Exit(1)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

pucit-0.1.0/src/pucit/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for the pucit CLI."""