nex-cli 0.2.1__py3-none-any.whl

nex/__init__.py

@@ -0,0 +1,3 @@
+"""Nex command-line interface."""
+
+__version__ = "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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+nex/__init__.py,sha256=jR_zLGnaVPA-KN0UDFMGZt1kTsNO0jqL5VtGLy7E2yM,57
+nex/cli.py,sha256=QaG9DzstUjiZYAKrKJ6ttF1n-QmZ8YmhHZdOYHrn7lo,2623
+nex/config.py,sha256=zF_wM1I_h8CVcZxl8OnihpfvQM8o85a2anQL3wsPk-E,2863
+nex/detection.py,sha256=kjptuoEqfPXvW5SQIwBcXJsUPxB6a74jY8B6bbFB-gw,1854
+nex_cli-0.2.1.dist-info/METADATA,sha256=z4FB53F2A-09Nvt_SqkjGWUf_GkRY8HCnloCuBqJg1o,1332
+nex_cli-0.2.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+nex_cli-0.2.1.dist-info/entry_points.txt,sha256=gThS-AxsBcWPnHl5VWliYR-u7SuD5fqDfw4dbnyiLDY,36
+nex_cli-0.2.1.dist-info/licenses/LICENSE,sha256=soXbuVf7p3iKj4kBWbL9vlr_-mZiDVbWQ4BBaqOxY-w,1073
+nex_cli-0.2.1.dist-info/RECORD,,

nex_cli-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nex_cli-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nex = nex.cli:run

nex_cli-0.2.1.dist-info/licenses/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.