nex-cli 0.2.1__tar.gz

nex_cli-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nex-cli
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

nex_cli-0.2.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+*.egg-info/

nex_cli-0.2.1/LICENSE

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

nex_cli-0.2.1/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: nex-cli
+Version: 0.2.1
+Summary: A command-line interface for Nex.
+Author: Nex contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nex-cli
+
+`nex-cli` is the command-line interface for Nex.
+
+## Installation
+
+Install the project in editable mode:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+nex --help
+nex --version
+nex learn          # Detect and save project signals
+nex learn --force  # Replace an existing Nex config
+```
+
+Running `nex` without arguments displays help and exits successfully.
+
+`nex learn` inspects the current directory, reports common project signals, and
+saves them to `.nex/config.toml`. It detects:
+`package.json` (including `dev` and `start` scripts), `requirements.txt`,
+`pyproject.toml`, and `docker-compose.yml`.
+
+The config records the project root, a future-ready frontend command such as
+`npm run dev`, backend file signals, and Docker Compose presence. Nex refuses
+to replace an existing config unless you pass `--force`.
+
+## Not yet
+
+- Running or supervising development processes
+- Automatic workflow detection beyond the reported file signals
+- Reading saved configuration to start a project

nex_cli-0.2.1/README.md

@@ -0,0 +1,37 @@
+# nex-cli
+
+`nex-cli` is the command-line interface for Nex.
+
+## Installation
+
+Install the project in editable mode:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+nex --help
+nex --version
+nex learn          # Detect and save project signals
+nex learn --force  # Replace an existing Nex config
+```
+
+Running `nex` without arguments displays help and exits successfully.
+
+`nex learn` inspects the current directory, reports common project signals, and
+saves them to `.nex/config.toml`. It detects:
+`package.json` (including `dev` and `start` scripts), `requirements.txt`,
+`pyproject.toml`, and `docker-compose.yml`.
+
+The config records the project root, a future-ready frontend command such as
+`npm run dev`, backend file signals, and Docker Compose presence. Nex refuses
+to replace an existing config unless you pass `--force`.
+
+## Not yet
+
+- Running or supervising development processes
+- Automatic workflow detection beyond the reported file signals
+- Reading saved configuration to start a project

nex_cli-0.2.1/nex/__init__.py

@@ -0,0 +1,3 @@
+"""Nex command-line interface."""
+
+__version__ = "0.2.1"

nex_cli-0.2.1/nex/cli.py

@@ -0,0 +1,94 @@
+"""Command-line entry point for Nex."""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from nex import __version__
+from nex.config import ConfigAlreadyExistsError, build_learn_config, write_learn_config
+from nex.detection import detect_project
+
+
+def version_callback(value: bool) -> None:
+    """Print the installed Nex CLI version and exit."""
+    if value:
+        typer.echo(f"nex {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=False,
+    invoke_without_command=True,
+    help="Command-line interface for Nex.",
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show the Nex version and exit.",
+    ),
+) -> None:
+    """Nex command-line interface."""
+    if ctx.invoked_subcommand is None and not version:
+        typer.echo(ctx.get_help())
+
+
+@app.command()
+def learn(
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite an existing .nex/config.toml file.",
+    ),
+) -> None:
+    """Detect project signals and save them to .nex/config.toml."""
+    root = Path.cwd().resolve()
+    detection = detect_project(directory=root)
+    console = Console()
+
+    if not detection.found_anything:
+        console.print(
+            Panel("No supported project signals found in this directory.", title="Nex learn")
+        )
+    else:
+        table = Table(title="Nex learn", show_header=True)
+        table.add_column("Type", style="bold")
+        table.add_column("Detected")
+
+        if detection.frontend:
+            scripts = ", ".join(detection.frontend.scripts) or "no dev/start script"
+            table.add_row("Frontend", f"package.json ({scripts})")
+        if detection.python_files:
+            table.add_row("Python backend", ", ".join(detection.python_files))
+        if detection.docker_compose:
+            table.add_row("Services", "docker-compose.yml")
+
+        console.print(table)
+
+    try:
+        config_path = write_learn_config(
+            build_learn_config(root, detection), force=force
+        )
+    except ConfigAlreadyExistsError as error:
+        console.print(
+            f"[yellow]Nex config already exists at {error.filename}. "
+            "Use --force to overwrite it.[/yellow]"
+        )
+        raise typer.Exit(code=1) from None
+
+    console.print(f"[green]Saved Nex config to {config_path}[/green]")
+
+
+def run() -> None:
+    """Run the Nex CLI."""
+    app()

nex_cli-0.2.1/nex/config.py

@@ -0,0 +1,95 @@
+"""Persistence for the project signals learned by Nex."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from nex.detection import ProjectDetection
+
+
+CONFIG_DIRECTORY = ".nex"
+CONFIG_FILENAME = "config.toml"
+
+
+class ConfigAlreadyExistsError(FileExistsError):
+    """Raised when saving would overwrite an existing Nex config."""
+
+
+@dataclass(frozen=True)
+class LearnConfig:
+    """The stable, persisted representation of a detection result."""
+
+    root: Path
+    frontend_script: str | None
+    backend_signals: tuple[str, ...]
+    docker_compose: bool
+
+
+def build_learn_config(root: Path, detection: ProjectDetection) -> LearnConfig:
+    """Convert a project detection result into Nex's persisted configuration."""
+    frontend_script = None
+    if detection.frontend and detection.frontend.scripts:
+        frontend_script = detection.frontend.scripts[0]
+
+    return LearnConfig(
+        root=root.resolve(),
+        frontend_script=frontend_script,
+        backend_signals=detection.python_files,
+        docker_compose=detection.docker_compose,
+    )
+
+
+def write_learn_config(config: LearnConfig, *, force: bool = False) -> Path:
+    """Write a learned config, refusing to replace an existing file by default."""
+    config_path = config.root / CONFIG_DIRECTORY / CONFIG_FILENAME
+    if config_path.exists() and not force:
+        raise ConfigAlreadyExistsError(config_path)
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(render_learn_config(config), encoding="utf-8")
+    return config_path
+
+
+def render_learn_config(config: LearnConfig) -> str:
+    """Render the fixed v1 configuration schema as TOML."""
+    lines = [
+        "schema_version = 1",
+        "",
+        "[project]",
+        f"name = {_toml_string(config.root.name)}",
+        f"root = {_toml_string(str(config.root))}",
+        "",
+        "[frontend]",
+        f"detected = {'true' if config.frontend_script is not None else 'false'}",
+    ]
+    if config.frontend_script is not None:
+        lines.extend(
+            (
+                f"script = {_toml_string(config.frontend_script)}",
+                f"command = {_toml_string(f'npm run {config.frontend_script}')}",
+            )
+        )
+
+    lines.extend(
+        (
+            "",
+            "[backend]",
+            f"signals = {_toml_string_array(config.backend_signals)}",
+            "",
+            "[services]",
+            f"docker_compose = {'true' if config.docker_compose else 'false'}",
+            "",
+        )
+    )
+    return "\n".join(lines)
+
+
+def _toml_string(value: str) -> str:
+    """Encode a string using TOML's JSON-compatible basic-string syntax."""
+    return json.dumps(value)
+
+
+def _toml_string_array(values: tuple[str, ...]) -> str:
+    return f"[{', '.join(_toml_string(value) for value in values)}]"

nex_cli-0.2.1/nex/detection.py

@@ -0,0 +1,61 @@
+"""Read-only project signal detection for Nex."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class FrontendDetection:
+    """A JavaScript project and the conventional start scripts it exposes."""
+
+    scripts: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ProjectDetection:
+    """Common project signals found in a directory."""
+
+    frontend: FrontendDetection | None
+    python_files: tuple[str, ...]
+    docker_compose: bool
+
+    @property
+    def found_anything(self) -> bool:
+        """Whether any supported signal was found."""
+        return bool(self.frontend or self.python_files or self.docker_compose)
+
+
+def detect_project(directory: Path) -> ProjectDetection:
+    """Inspect *directory* without modifying it or traversing subdirectories."""
+    package_json = directory / "package.json"
+    frontend = _detect_frontend(package_json) if package_json.is_file() else None
+    python_files = tuple(
+        filename
+        for filename in ("requirements.txt", "pyproject.toml")
+        if (directory / filename).is_file()
+    )
+
+    return ProjectDetection(
+        frontend=frontend,
+        python_files=python_files,
+        docker_compose=(directory / "docker-compose.yml").is_file(),
+    )
+
+
+def _detect_frontend(package_json: Path) -> FrontendDetection:
+    """Read known npm scripts, tolerating malformed package metadata."""
+    try:
+        package_data = json.loads(package_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return FrontendDetection(scripts=())
+
+    scripts = package_data.get("scripts", {})
+    if not isinstance(scripts, dict):
+        return FrontendDetection(scripts=())
+
+    return FrontendDetection(
+        scripts=tuple(name for name in ("dev", "start") if name in scripts),
+    )

nex_cli-0.2.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nex-cli"
+version = "0.2.1"
+description = "A command-line interface for Nex."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Nex contributors" }]
+dependencies = ["rich>=13", "typer>=0.12"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+nex = "nex.cli:run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["nex"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nex_cli-0.2.1/tests/test_cli.py

@@ -0,0 +1,72 @@
+import json
+
+from typer.testing import CliRunner
+
+from nex.cli import app
+
+
+runner = CliRunner()
+
+
+def test_help() -> None:
+    result = runner.invoke(app, ["--help"])
+
+    assert result.exit_code == 0
+    assert "Usage:" in result.output
+
+
+def test_version() -> None:
+    result = runner.invoke(app, ["--version"])
+
+    assert result.exit_code == 0
+    assert result.output == "nex 0.2.1\n"
+
+
+def test_no_arguments_shows_help() -> None:
+    result = runner.invoke(app)
+
+    assert result.exit_code == 0
+    assert "Usage:" in result.output
+
+
+def test_learn_reports_detected_project_signals(tmp_path, monkeypatch) -> None:
+    (tmp_path / "package.json").write_text(
+        json.dumps({"scripts": {"dev": "vite"}}), encoding="utf-8"
+    )
+    (tmp_path / "requirements.txt").write_text("fastapi\n", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(app, ["learn"])
+
+    assert result.exit_code == 0
+    assert "Frontend" in result.output
+    assert "package.json (dev)" in result.output
+    assert "Python backend" in result.output
+    assert "Saved Nex config to" in result.output
+    assert (tmp_path / ".nex" / "config.toml").is_file()
+
+
+def test_learn_refuses_to_overwrite_existing_config(tmp_path, monkeypatch) -> None:
+    config_path = tmp_path / ".nex" / "config.toml"
+    config_path.parent.mkdir()
+    config_path.write_text("keep = true\n", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(app, ["learn"])
+
+    assert result.exit_code == 1
+    assert "Use --force to overwrite it." in result.output
+    assert config_path.read_text(encoding="utf-8") == "keep = true\n"
+
+
+def test_learn_force_overwrites_existing_config(tmp_path, monkeypatch) -> None:
+    config_path = tmp_path / ".nex" / "config.toml"
+    config_path.parent.mkdir()
+    config_path.write_text("old = true\n", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(app, ["learn", "--force"])
+
+    assert result.exit_code == 0
+    assert "Saved Nex config to" in result.output
+    assert "old = true" not in config_path.read_text(encoding="utf-8")

nex_cli-0.2.1/tests/test_config.py

@@ -0,0 +1,73 @@
+import json
+import tomllib
+
+import pytest
+
+from nex.config import (
+    ConfigAlreadyExistsError,
+    build_learn_config,
+    write_learn_config,
+)
+from nex.detection import detect_project
+
+
+def test_writes_config_for_a_fresh_project_directory(tmp_path) -> None:
+    (tmp_path / "requirements.txt").write_text("fastapi\n", encoding="utf-8")
+    config = build_learn_config(tmp_path, detect_project(tmp_path))
+
+    config_path = write_learn_config(config)
+
+    assert config_path == tmp_path / ".nex" / "config.toml"
+    assert config_path.is_file()
+
+
+def test_does_not_clobber_an_existing_config(tmp_path) -> None:
+    config_path = tmp_path / ".nex" / "config.toml"
+    config_path.parent.mkdir()
+    config_path.write_text("keep = true\n", encoding="utf-8")
+    config = build_learn_config(tmp_path, detect_project(tmp_path))
+
+    with pytest.raises(ConfigAlreadyExistsError):
+        write_learn_config(config)
+
+    assert config_path.read_text(encoding="utf-8") == "keep = true\n"
+
+
+def test_force_overwrites_an_existing_config(tmp_path) -> None:
+    config_path = tmp_path / ".nex" / "config.toml"
+    config_path.parent.mkdir()
+    config_path.write_text("old = true\n", encoding="utf-8")
+    (tmp_path / "requirements.txt").write_text("fastapi\n", encoding="utf-8")
+    config = build_learn_config(tmp_path, detect_project(tmp_path))
+
+    write_learn_config(config, force=True)
+
+    assert "old = true" not in config_path.read_text(encoding="utf-8")
+    assert tomllib.loads(config_path.read_text(encoding="utf-8"))["backend"] == {
+        "signals": ["requirements.txt"]
+    }
+
+
+def test_config_content_captures_a_mixed_project(tmp_path) -> None:
+    (tmp_path / "package.json").write_text(
+        json.dumps({"scripts": {"start": "next start"}}), encoding="utf-8"
+    )
+    (tmp_path / "pyproject.toml").write_text("[project]\nname = 'api'\n", encoding="utf-8")
+    (tmp_path / "docker-compose.yml").write_text("services: {}\n", encoding="utf-8")
+
+    config_path = write_learn_config(
+        build_learn_config(tmp_path, detect_project(tmp_path))
+    )
+    content = tomllib.loads(config_path.read_text(encoding="utf-8"))
+
+    assert content == {
+        "schema_version": 1,
+        "project": {"name": tmp_path.name, "root": str(tmp_path.resolve())},
+        "frontend": {
+            "detected": True,
+            "script": "start",
+            "command": "npm run start",
+        },
+        "backend": {"signals": ["pyproject.toml"]},
+        "services": {"docker_compose": True},
+    }

nex_cli-0.2.1/tests/test_detection.py

@@ -0,0 +1,47 @@
+import json
+
+from nex.detection import detect_project
+
+
+def test_detects_frontend_project_and_known_scripts(tmp_path) -> None:
+    (tmp_path / "package.json").write_text(
+        json.dumps({"scripts": {"dev": "vite", "test": "vitest"}}), encoding="utf-8"
+    )
+
+    detection = detect_project(tmp_path)
+
+    assert detection.frontend is not None
+    assert detection.frontend.scripts == ("dev",)
+    assert detection.python_files == ()
+    assert not detection.docker_compose
+
+
+def test_detects_python_backend_project(tmp_path) -> None:
+    (tmp_path / "requirements.txt").write_text("fastapi\n", encoding="utf-8")
+
+    detection = detect_project(tmp_path)
+
+    assert detection.frontend is None
+    assert detection.python_files == ("requirements.txt",)
+    assert not detection.docker_compose
+
+
+def test_detects_mixed_project(tmp_path) -> None:
+    (tmp_path / "package.json").write_text(
+        json.dumps({"scripts": {"start": "next start"}}), encoding="utf-8"
+    )
+    (tmp_path / "pyproject.toml").write_text("[project]\nname = 'api'\n", encoding="utf-8")
+    (tmp_path / "docker-compose.yml").write_text("services: {}\n", encoding="utf-8")
+
+    detection = detect_project(tmp_path)
+
+    assert detection.frontend is not None
+    assert detection.frontend.scripts == ("start",)
+    assert detection.python_files == ("pyproject.toml",)
+    assert detection.docker_compose
+
+
+def test_reports_no_signals_for_empty_directory(tmp_path) -> None:
+    detection = detect_project(tmp_path)
+
+    assert not detection.found_anything