ipkgs 0.1.0__tar.gz

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --tb=short -q

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

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install hatchling
+      - run: python -m hatchling build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ipkgs-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+pip-wheel-metadata/
+.installed.cfg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# ipkgs runtime
+ip_modules/
+ipkgs.lock
+.ipkgs_cache/

ipkgs-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: ipkgs
+Version: 0.1.0
+Summary: A package manager for Verilog IP cores
+Project-URL: Homepage, https://ipkgs.com
+Project-URL: Repository, https://github.com/ipkgs/ipkgs
+Author-email: "ipkgs.com" <hi@ipkgs.com>
+License-Expression: MIT
+Keywords: eda,fpga,ip-core,package-manager,rtl,verilog
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.10
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: keyring<26,>=25
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: rich<15,>=13
+Requires-Dist: semver<4,>=3.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pyfakefs>=5.4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ipkgs
+
+**The package manager for Verilog IP cores.**
+
+`ipkgs` is to Verilog what `npm` is to JavaScript — a CLI tool and registry for sharing, installing, and publishing reusable RTL IP cores for FPGA and ASIC projects.
+
+Registry: **[ipkgs.com](https://ipkgs.com)**
+
+---
+
+## Install
+
+```sh
+pip install ipkgs
+```
+
+## Quick start
+
+```sh
+# Initialize a new IP core project
+ipkgs init
+
+# Search for IP cores
+ipkgs search uart
+
+# Install a package
+ipkgs install uart-core
+
+# Install a specific version
+ipkgs install fifo-sync@^2.0.0
+
+# List installed packages
+ipkgs list
+
+# Publish your core to ipkgs.com
+ipkgs login
+ipkgs publish
+```
+
+## `ipkgs.json`
+
+Every IP core project has an `ipkgs.json` manifest:
+
+```json
+{
+  "name": "uart-core",
+  "version": "1.2.0",
+  "description": "Parameterized UART TX/RX for FPGA targets",
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "top_module": "uart_top",
+  "platforms": ["ice40", "ecp5", "xc7", "generic"],
+  "source_files": [
+    "rtl/uart_top.sv",
+    "rtl/uart_tx.sv",
+    "rtl/uart_rx.sv"
+  ],
+  "parameters": {
+    "BAUD_RATE": "115200",
+    "DATA_BITS": "8"
+  },
+  "dependencies": {
+    "fifo-sync": "^2.0.0"
+  },
+  "scripts": {
+    "sim":  "iverilog -g2012 -o sim.out rtl/uart_top.sv && vvp sim.out",
+    "lint": "verilator --lint-only rtl/uart_top.sv"
+  }
+}
+```
+
+Installed packages land in `ip_modules/` (add to `.gitignore`).
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ipkgs init` | Scaffold a new IP core project |
+| `ipkgs install [pkg[@ver]]` | Install packages |
+| `ipkgs uninstall <pkg>` | Remove packages |
+| `ipkgs update [pkg]` | Update to latest within semver range |
+| `ipkgs list` | List installed packages |
+| `ipkgs search <query>` | Search the registry |
+| `ipkgs info <pkg>` | Show package details |
+| `ipkgs publish` | Publish to ipkgs.com |
+| `ipkgs login` | Authenticate with ipkgs.com |
+| `ipkgs logout` | Remove stored credentials |
+
+## Version ranges
+
+`ipkgs` uses standard semver ranges:
+
+| Range | Meaning |
+|---|---|
+| `^1.2.0` | Compatible: `>=1.2.0 <2.0.0` |
+| `~1.2.0` | Patch-level: `>=1.2.0 <1.3.0` |
+| `>=1.0.0 <2.0.0` | Explicit range |
+| `1.2.3` | Exact version |
+
+> **Note on version conflicts:** Unlike npm, `ipkgs` hard-fails on incompatible version conflicts. Verilog IP cores compile into a single netlist — duplicate module definitions would cause synthesis errors. If two packages require incompatible versions of a dependency, you must resolve the conflict manually.
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `IPKGS_TOKEN` | Auth token (for CI/CD, skips keyring) |
+| `IPKGS_REGISTRY` | Override registry URL (default: `https://api.ipkgs.com/v1`) |
+
+## License
+
+MIT

ipkgs-0.1.0/README.md

@@ -0,0 +1,111 @@
+# ipkgs
+
+**The package manager for Verilog IP cores.**
+
+`ipkgs` is to Verilog what `npm` is to JavaScript — a CLI tool and registry for sharing, installing, and publishing reusable RTL IP cores for FPGA and ASIC projects.
+
+Registry: **[ipkgs.com](https://ipkgs.com)**
+
+---
+
+## Install
+
+```sh
+pip install ipkgs
+```
+
+## Quick start
+
+```sh
+# Initialize a new IP core project
+ipkgs init
+
+# Search for IP cores
+ipkgs search uart
+
+# Install a package
+ipkgs install uart-core
+
+# Install a specific version
+ipkgs install fifo-sync@^2.0.0
+
+# List installed packages
+ipkgs list
+
+# Publish your core to ipkgs.com
+ipkgs login
+ipkgs publish
+```
+
+## `ipkgs.json`
+
+Every IP core project has an `ipkgs.json` manifest:
+
+```json
+{
+  "name": "uart-core",
+  "version": "1.2.0",
+  "description": "Parameterized UART TX/RX for FPGA targets",
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "top_module": "uart_top",
+  "platforms": ["ice40", "ecp5", "xc7", "generic"],
+  "source_files": [
+    "rtl/uart_top.sv",
+    "rtl/uart_tx.sv",
+    "rtl/uart_rx.sv"
+  ],
+  "parameters": {
+    "BAUD_RATE": "115200",
+    "DATA_BITS": "8"
+  },
+  "dependencies": {
+    "fifo-sync": "^2.0.0"
+  },
+  "scripts": {
+    "sim":  "iverilog -g2012 -o sim.out rtl/uart_top.sv && vvp sim.out",
+    "lint": "verilator --lint-only rtl/uart_top.sv"
+  }
+}
+```
+
+Installed packages land in `ip_modules/` (add to `.gitignore`).
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ipkgs init` | Scaffold a new IP core project |
+| `ipkgs install [pkg[@ver]]` | Install packages |
+| `ipkgs uninstall <pkg>` | Remove packages |
+| `ipkgs update [pkg]` | Update to latest within semver range |
+| `ipkgs list` | List installed packages |
+| `ipkgs search <query>` | Search the registry |
+| `ipkgs info <pkg>` | Show package details |
+| `ipkgs publish` | Publish to ipkgs.com |
+| `ipkgs login` | Authenticate with ipkgs.com |
+| `ipkgs logout` | Remove stored credentials |
+
+## Version ranges
+
+`ipkgs` uses standard semver ranges:
+
+| Range | Meaning |
+|---|---|
+| `^1.2.0` | Compatible: `>=1.2.0 <2.0.0` |
+| `~1.2.0` | Patch-level: `>=1.2.0 <1.3.0` |
+| `>=1.0.0 <2.0.0` | Explicit range |
+| `1.2.3` | Exact version |
+
+> **Note on version conflicts:** Unlike npm, `ipkgs` hard-fails on incompatible version conflicts. Verilog IP cores compile into a single netlist — duplicate module definitions would cause synthesis errors. If two packages require incompatible versions of a dependency, you must resolve the conflict manually.
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `IPKGS_TOKEN` | Auth token (for CI/CD, skips keyring) |
+| `IPKGS_REGISTRY` | Override registry URL (default: `https://api.ipkgs.com/v1`) |
+
+## License
+
+MIT

ipkgs-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ipkgs"
+version = "0.1.0"
+description = "A package manager for Verilog IP cores"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "ipkgs.com", email = "hi@ipkgs.com" }]
+keywords = ["verilog", "fpga", "ip-core", "package-manager", "eda", "rtl"]
+classifiers = [
+  "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+]
+
+dependencies = [
+  "click>=8.1,<9",
+  "httpx>=0.27,<1",
+  "rich>=13,<15",
+  "semver>=3.0,<4",
+  "pydantic>=2.6,<3",
+  "keyring>=25,<26",
+  "platformdirs>=4,<5",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "pytest-httpx>=0.30",
+  "pyfakefs>=5.4",
+  "mypy>=1.9",
+  "ruff>=0.4",
+]
+
+[project.scripts]
+ipkgs = "ipkgs.cli.main:cli"
+
+[project.urls]
+Homepage = "https://ipkgs.com"
+Repository = "https://github.com/ipkgs/ipkgs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ipkgs"]
+
+[tool.hatch.version]
+path = "src/ipkgs/__init__.py"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

ipkgs-0.1.0/src/ipkgs/__init__.py

@@ -0,0 +1,10 @@
+"""ipkgs — Verilog IP core package manager."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("ipkgs")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

ipkgs-0.1.0/src/ipkgs/__main__.py

@@ -0,0 +1,3 @@
+from ipkgs.cli.main import cli
+
+cli()

ipkgs-0.1.0/src/ipkgs/cli/cmd_auth.py

@@ -0,0 +1,36 @@
+"""ipkgs login / logout — registry authentication."""
+
+from __future__ import annotations
+
+import asyncio
+
+import click
+
+from ipkgs.cli.main import IpkgsContext
+from ipkgs.exceptions import IpkgsError
+from ipkgs.registry.auth import AuthManager
+from ipkgs.utils.console import print_success, print_error
+
+
+@click.command("login")
+@click.option("--username", "-u", prompt=True)
+@click.option("--password", "-p", prompt=True, hide_input=True)
+@click.pass_obj
+def login(ctx: IpkgsContext, username: str, password: str) -> None:
+    """Authenticate with the ipkgs.com registry."""
+    try:
+        auth = AuthManager(ctx.registry)
+        token = asyncio.run(auth.login(username, password))
+        print_success(ctx.console, f"Logged in as [bold]{username}[/]")
+    except IpkgsError as exc:
+        print_error(ctx.console, str(exc))
+        raise SystemExit(1)
+
+
+@click.command("logout")
+@click.pass_obj
+def logout(ctx: IpkgsContext) -> None:
+    """Remove stored credentials for the registry."""
+    auth = AuthManager(ctx.registry)
+    auth.clear_token()
+    print_success(ctx.console, "Logged out.")

ipkgs-0.1.0/src/ipkgs/cli/cmd_info.py

@@ -0,0 +1,81 @@
+"""ipkgs info — show package details."""
+
+from __future__ import annotations
+
+import asyncio
+
+import click
+from rich.panel import Panel
+from rich.table import Table
+
+from ipkgs.cli.main import IpkgsContext
+from ipkgs.exceptions import IpkgsError
+from ipkgs.registry.client import RegistryClient
+from ipkgs.utils.console import print_error
+
+
+@click.command("info")
+@click.argument("package")
+@click.pass_obj
+def info(ctx: IpkgsContext, package: str) -> None:
+    """Show details about an IP core package.
+
+    \b
+    Examples:
+      ipkgs info uart-core
+      ipkgs info uart-core@1.2.0
+    """
+    try:
+        asyncio.run(_info(ctx, package))
+    except IpkgsError as exc:
+        print_error(ctx.console, str(exc))
+        raise SystemExit(1)
+
+
+async def _info(ctx: IpkgsContext, package: str) -> None:
+    name, _, version = package.partition("@")
+    client = RegistryClient(base_url=ctx.registry)
+    meta = await client.get_package(name)
+
+    target_version = version or meta.latest
+    pkg = meta.versions.get(target_version)
+
+    ctx.console.print(
+        Panel(
+            f"[bold cyan]{meta.name}[/]  [green]{target_version}[/]\n"
+            f"{meta.description or '[dim]No description[/]'}",
+            expand=False,
+        )
+    )
+
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold")
+    grid.add_column()
+    grid.add_row("Author", meta.author or "-")
+    grid.add_row("License", meta.license or "-")
+    grid.add_row("Homepage", meta.dict().get("homepage") or "-")
+    if pkg:
+        grid.add_row("Published", str(pkg.published_at.date()) if pkg.published_at else "-")
+        grid.add_row("Downloads", str(pkg.download_count))
+    ctx.console.print(grid)
+
+    if pkg and pkg.dependencies:
+        dep_table = Table(title="Dependencies", show_header=True, header_style="bold")
+        dep_table.add_column("Package", style="cyan")
+        dep_table.add_column("Range", style="green")
+        for dep_name, constraint in pkg.dependencies.items():
+            dep_table.add_row(dep_name, constraint)
+        ctx.console.print(dep_table)
+
+    # Versions list
+    versions = sorted(meta.versions.keys(), reverse=True)[:10]
+    ver_table = Table(title="Recent versions", show_header=True, header_style="bold")
+    ver_table.add_column("Version", style="cyan")
+    ver_table.add_column("Downloads")
+    for v in versions:
+        pv = meta.versions[v]
+        tag = " [bold green](latest)[/]" if v == meta.latest else ""
+        ver_table.add_row(v + tag, str(pv.download_count))
+    ctx.console.print(ver_table)
+
+    ctx.console.print(f"\n[dim]Install:[/] [cyan]ipkgs install {meta.name}[/]")

ipkgs-0.1.0/src/ipkgs/cli/cmd_init.py

@@ -0,0 +1,81 @@
+"""ipkgs init — scaffold a new IP core project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.panel import Panel
+
+from ipkgs.cli.main import IpkgsContext
+from ipkgs.core.manifest import IpkgsManifest, MANIFEST_FILENAME
+from ipkgs.utils.fs import ensure_ip_modules_dir
+
+
+@click.command("init")
+@click.option("--yes", "-y", is_flag=True, help="Accept all defaults non-interactively.")
+@click.option("--force", "-f", is_flag=True, help="Overwrite existing ipkgs.json.")
+@click.pass_obj
+def init(ctx: IpkgsContext, yes: bool, force: bool) -> None:
+    """Scaffold a new Verilog IP core project."""
+    cwd = Path.cwd()
+    manifest_path = cwd / MANIFEST_FILENAME
+
+    if manifest_path.exists() and not force:
+        ctx.console.print(
+            f"[yellow]{MANIFEST_FILENAME} already exists.[/] Use --force to overwrite."
+        )
+        raise SystemExit(1)
+
+    def ask(prompt: str, default: str, skip: bool = False) -> str:
+        if skip:
+            return default
+        return click.prompt(prompt, default=default)
+
+    name = ask("Package name", cwd.name.lower().replace("_", "-"), yes)
+    version = ask("Version", "0.1.0", yes)
+    description = ask("Description", "", yes)
+    author = ask("Author", "", yes)
+    license_ = ask("License", "MIT", yes)
+    top_module = ask("Top module name", name.replace("-", "_"), yes)
+
+    if yes:
+        platforms = ["generic"]
+    else:
+        ctx.console.print(
+            "Platforms [dim](comma-separated: ice40, ecp5, xc7, generic)[/]"
+        )
+        raw = click.prompt("Platforms", default="generic")
+        platforms = [p.strip() for p in raw.split(",") if p.strip()]
+
+    manifest = IpkgsManifest(
+        name=name,
+        version=version,
+        description=description,
+        author=author,
+        license=license_,
+        top_module=top_module,
+        platforms=platforms,
+    )
+    manifest.save(manifest_path)
+
+    ensure_ip_modules_dir(cwd)
+
+    # Add ip_modules/ to .gitignore if not present
+    gitignore = cwd / ".gitignore"
+    if gitignore.exists():
+        content = gitignore.read_text()
+        if "ip_modules/" not in content:
+            gitignore.write_text(content + "\nip_modules/\n")
+    else:
+        gitignore.write_text("ip_modules/\n")
+
+    ctx.console.print(
+        Panel(
+            f"[green]Created[/] [bold]{MANIFEST_FILENAME}[/]\n"
+            f"[green]Created[/] ip_modules/\n"
+            f"[green]Updated[/] .gitignore",
+            title=f"[bold cyan]ipkgs init[/] — {name}@{version}",
+            expand=False,
+        )
+    )