nex-cli 0.2.1__tar.gz → 0.3.0__tar.gz

nex_cli-0.3.0/LICENSE

@@ -0,0 +1,200 @@
+											Apache License
+									Version 2.0, January 2004
+								https://www.apache.org/licenses/
+
+	TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+	1. Definitions.
+
+		"License" shall mean the terms and conditions for use, reproduction,
+		and distribution as defined by Sections 1 through 9 of this document.
+
+		"Licensor" shall mean the copyright owner or entity authorized by
+		the copyright owner that is granting the License.
+
+		"Legal Entity" shall mean the union of the acting entity and all
+		other entities that control, are controlled by, or are under common
+		control with that entity. For the purposes of this definition,
+		"control" means (i) the power, direct or indirect, to cause the
+		direction or management of such entity, whether by contract or
+		otherwise, or (ii) ownership of fifty percent (50%) or more of the
+		outstanding shares, or (iii) beneficial ownership of such entity.
+
+		"You" (or "Your") shall mean an individual or Legal Entity
+		exercising permissions granted by this License.
+
+		"Source" form shall mean the preferred form for making modifications,
+		including but not limited to software source code, documentation
+		source, and configuration files.
+
+		"Object" form shall mean any form resulting from mechanical
+		transformation or translation of a Source form, including but
+		not limited to compiled object code, generated documentation,
+		and conversions to other media types.
+
+		"Work" shall mean the work of authorship, whether in Source or
+		Object form, made available under the License, as indicated by a
+		copyright notice that is included in or attached to the work
+		(an example is provided in the Appendix below).
+
+		"Derivative Works" shall mean any work, whether in Source or Object
+		form, that is based on (or derived from) the Work and for which the
+		editorial revisions, annotations, elaborations, or other modifications
+		represent, as a whole, an original work of authorship. For the purposes
+		of this License, Derivative Works shall not include works that remain
+		separable from, or merely link (or bind by name) to the interfaces of,
+		the Work and Derivative Works thereof.
+
+		"Contribution" shall mean any work of authorship, including
+		the original version of the Work and any modifications or additions
+		to that Work or Derivative Works thereof, that is intentionally
+		submitted to Licensor for inclusion in the Work by the copyright owner
+		or by an individual or Legal Entity authorized to submit on behalf of
+		the copyright owner. For the purposes of this definition, "submitted"
+		means any form of electronic, verbal, or written communication sent
+		to the Licensor or its representatives, including but not limited to
+		communication on electronic mailing lists, source code control systems,
+		and issue tracking systems that are managed by, or on behalf of, the
+		Licensor for the purpose of discussing and improving the Work, but
+		excluding communication that is conspicuously marked or otherwise
+		designated in writing by the copyright owner as "Not a Contribution."
+
+		"Contributor" shall mean Licensor and any individual or Legal Entity
+		on behalf of whom a Contribution has been received by Licensor and
+		subsequently incorporated within the Work.
+
+	2. Grant of Copyright License. Subject to the terms and conditions of
+		this License, each Contributor hereby grants to You a perpetual,
+		worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+		copyright license to reproduce, prepare Derivative Works of,
+		publicly display, publicly perform, sublicense, and distribute the
+		Work and such Derivative Works in Source or Object form.
+
+	3. Grant of Patent License. Subject to the terms and conditions of
+		this License, each Contributor hereby grants to You a perpetual,
+		worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+		(except as stated in this section) patent license to make, have made,
+		use, offer to sell, sell, import, and otherwise transfer the Work,
+		where such license applies only to those patent claims licensable
+		by such Contributor that are necessarily infringed by their
+		Contribution(s) alone or by combination of their Contribution(s)
+		with the Work to which such Contribution(s) was submitted. If You
+		institute patent litigation against any entity (including a
+		cross-claim or counterclaim in a lawsuit) alleging that the Work
+		or a Contribution incorporated within the Work constitutes direct
+		or contributory patent infringement, then any patent licenses
+		granted to You under this License for that Work shall terminate
+		as of the date such litigation is filed.
+
+	4. Redistribution. You may reproduce and distribute copies of the
+		Work or Derivative Works thereof in any medium, with or without
+		modifications, and in Source or Object form, provided that You meet
+		the following conditions:
+
+		(a) You must give any other recipients of the Work or Derivative Works
+			 a copy of this License; and
+
+		(b) You must cause any modified files to carry prominent notices
+			 stating that You changed the files; and
+
+		(c) You must retain, in the Source form of any Derivative Works that
+			 You distribute, all copyright, patent, trademark, and attribution
+			 notices from the Source form of the Work, excluding those notices
+			 that do not pertain to any part of the Derivative Works; and
+
+		(d) If the Work includes a "NOTICE" text file as part of its
+			 distribution, then any Derivative Works that You distribute must
+			 include a readable copy of the attribution notices contained
+			 within such NOTICE file, excluding those notices that do not
+			 pertain to any part of the Derivative Works, in at least one
+			 of the following places: within a NOTICE text file distributed
+			 as part of the Derivative Works; within the Source form or
+			 documentation, if provided along with the Derivative Works; or,
+			 within a display generated by the Derivative Works, if and
+			 wherever such third-party notices normally appear. The contents
+			 of the NOTICE file are for informational purposes only and
+			 do not modify the License. You may add Your own attribution
+			 notices within Derivative Works that You distribute, alongside
+			 or as an addendum to the NOTICE text from the Work, provided
+			 that such additional attribution notices cannot be construed
+			 as modifying the License.
+
+		You may add Your own copyright statement to Your modifications and
+		may provide additional or different license terms and conditions
+		for use, reproduction, or distribution of Your modifications, or
+		for any such Derivative Works as a whole, provided Your use,
+		reproduction, and distribution of the Work otherwise complies with
+		the conditions stated in this License.
+
+	5. Submission of Contributions. Unless You explicitly state otherwise,
+		any Contribution intentionally submitted for inclusion in the Work
+		by You to the Licensor shall be under the terms and conditions of
+		this License, without any additional terms or conditions.
+		Notwithstanding the above, nothing herein shall supersede or modify
+		the terms of any separate license agreement you may have executed
+		with Licensor regarding such Contributions.
+
+	6. Trademarks. This License does not grant permission to use the trade
+		names, trademarks, service marks, or product names of the Licensor,
+		except as required for reasonable and customary use in describing the
+		origin of the Work and reproducing the content of the NOTICE file.
+
+	7. Disclaimer of Warranty. Unless required by applicable law or
+		agreed to in writing, Licensor provides the Work (and each
+		Contributor provides its Contributions) on an "AS IS" BASIS,
+		WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+		implied, including, without limitation, any warranties or conditions
+		of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+		PARTICULAR PURPOSE. You are solely responsible for determining the
+		appropriateness of using or redistributing the Work and assume any
+		risks associated with Your exercise of permissions under this License.
+
+	8. Limitation of Liability. In no event and under no legal theory,
+		whether in tort (including negligence), contract, or otherwise,
+		unless required by applicable law (such as deliberate and grossly
+		negligent acts) or agreed to in writing, shall any Contributor be
+		liable to You for damages, including any direct, indirect, special,
+		incidental, or consequential damages of any character arising as a
+		result of this License or out of the use or inability to use the
+		Work (including but not limited to damages for loss of goodwill,
+		work stoppage, computer failure or malfunction, or any and all
+		other commercial damages or losses), even if such Contributor
+		has been advised of the possibility of such damages.
+
+	9. Accepting Warranty or Additional Liability. While redistributing
+		the Work or Derivative Works thereof, You may choose to offer,
+		and charge a fee for, acceptance of support, warranty, indemnity,
+		or other liability obligations and/or rights consistent with this
+		License. However, in accepting such obligations, You may act only
+		on Your own behalf and on Your sole responsibility, not on behalf
+		of any other Contributor, and only if You agree to indemnify,
+		defend, and hold each Contributor harmless for any liability
+		incurred by, or claims asserted against, such Contributor by reason
+		of your accepting any such warranty or additional liability.
+
+	END OF TERMS AND CONDITIONS
+
+	APPENDIX: How to apply the Apache License to your work.
+
+		To apply the Apache License to your work, attach the following
+		boilerplate notice, with the fields enclosed by brackets "[]"
+		replaced with your own identifying information. (Don't include
+		the brackets!) The text should be enclosed in the appropriate
+		comment syntax for the file format. We also recommend that a
+		file or class name and description of purpose be included on the
+		same "printed page" as the copyright notice for easier
+		identification within third-party archives.
+
+	Copyright 2026 Ankush Thakur
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		 https://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.

nex_cli-0.3.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: nex-cli
+Version: 0.3.0
+Summary: A command-line interface for Nex.
+Author: Nex contributors
+License: Apache-2.0
+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
+
+For normal use, install Nex from PyPI with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install nex-cli
+nex --version
+```
+
+The current release reports `nex 0.2.1`.
+
+## Development
+
+To work on Nex locally, clone the repository and install the development
+dependencies in an isolated environment:
+
+```bash
+git clone https://github.com/ankush-exe/nex-cli.git
+cd nex-cli
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+pytest
+```
+
+On Windows, activate the environment with `.venv\\Scripts\\activate` instead.
+
+## Usage
+
+```bash
+nex learn                    # Discover the project and save workflow configuration
+nex                         # Execute the saved workflow when one component is runnable
+nex --component client      # Execute the workflow for the client component
+nex learn --force           # Replace an existing Nex config
+nex --help
+nex --version
+```
+
+`nex learn` discovers and understands the project, then saves workflow
+configuration to `.nex/config.toml`. For example, run `nex learn` from a
+project root before running `nex`:
+
+```bash
+nex learn
+nex
+```
+
+Bare `nex` reads the saved configuration and executes the workflow when exactly
+one runnable component exists. If discovery finds multiple runnable components,
+bare `nex` asks you to select one by its relative path:
+
+```bash
+nex --component client
+```
+
+Nex streams workflow output directly to the terminal, returns the workflow's
+exit code, and maps Ctrl+C to exit code 130.
+
+`nex learn` scans the current directory and up to three levels of child
+directories, reports each detected project component, and saves the result to
+`.nex/config.toml`. It detects `package.json`, `requirements.txt`,
+`pyproject.toml`, and `docker-compose.yml`, while skipping common generated,
+environment, dependency, and version-control directories.
+
+For JavaScript components, Nex reports `dev` and `start` scripts and detects
+the package manager from lockfiles for npm, pnpm, Yarn, or Bun. For Python
+components, it records safe metadata such as the project name and Python
+requirement from `pyproject.toml`. Malformed manifests are retained as detected
+components and reported as warnings instead of stopping discovery. `nex learn`
+does not install dependencies, modify project files, or start processes.
+
+The generated configuration uses schema version 2 and records components,
+signals, workflows, warnings, and deterministic suggested commands. Nex
+refuses to replace an existing config unless you pass `--force`; this leaves
+older v0.2.x schema version 1 files untouched until the user explicitly
+chooses to replace them.
+
+Nex v0.3.0 executes one workflow command at a time. It does not configure
+environments, orchestrate multiple services, or supervise process trees. When
+one component exposes more than one suggestion, Nex runs its first deterministic
+suggestion (`dev` before `start`).
+
+## Not yet
+
+- Multi-service orchestration and process supervision
+- Automatic workflow detection beyond the reported file signals
+- Dependency installation
+
+## License
+
+Nex is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for the
+full terms.
+
+The `v0.1.0`, `v0.2.0`, and `v0.2.1` release tags and their distributed
+artifacts remain available under their original MIT licenses. This change does
+not revoke permissions already granted under those licenses.
+
+---
+
+© 2026 Ankush Thakur. All rights reserved.

nex_cli-0.3.0/README.md

@@ -0,0 +1,104 @@
+# nex-cli
+
+`nex-cli` is the command-line interface for Nex.
+
+## Installation
+
+For normal use, install Nex from PyPI with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install nex-cli
+nex --version
+```
+
+The current release reports `nex 0.2.1`.
+
+## Development
+
+To work on Nex locally, clone the repository and install the development
+dependencies in an isolated environment:
+
+```bash
+git clone https://github.com/ankush-exe/nex-cli.git
+cd nex-cli
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+pytest
+```
+
+On Windows, activate the environment with `.venv\\Scripts\\activate` instead.
+
+## Usage
+
+```bash
+nex learn                    # Discover the project and save workflow configuration
+nex                         # Execute the saved workflow when one component is runnable
+nex --component client      # Execute the workflow for the client component
+nex learn --force           # Replace an existing Nex config
+nex --help
+nex --version
+```
+
+`nex learn` discovers and understands the project, then saves workflow
+configuration to `.nex/config.toml`. For example, run `nex learn` from a
+project root before running `nex`:
+
+```bash
+nex learn
+nex
+```
+
+Bare `nex` reads the saved configuration and executes the workflow when exactly
+one runnable component exists. If discovery finds multiple runnable components,
+bare `nex` asks you to select one by its relative path:
+
+```bash
+nex --component client
+```
+
+Nex streams workflow output directly to the terminal, returns the workflow's
+exit code, and maps Ctrl+C to exit code 130.
+
+`nex learn` scans the current directory and up to three levels of child
+directories, reports each detected project component, and saves the result to
+`.nex/config.toml`. It detects `package.json`, `requirements.txt`,
+`pyproject.toml`, and `docker-compose.yml`, while skipping common generated,
+environment, dependency, and version-control directories.
+
+For JavaScript components, Nex reports `dev` and `start` scripts and detects
+the package manager from lockfiles for npm, pnpm, Yarn, or Bun. For Python
+components, it records safe metadata such as the project name and Python
+requirement from `pyproject.toml`. Malformed manifests are retained as detected
+components and reported as warnings instead of stopping discovery. `nex learn`
+does not install dependencies, modify project files, or start processes.
+
+The generated configuration uses schema version 2 and records components,
+signals, workflows, warnings, and deterministic suggested commands. Nex
+refuses to replace an existing config unless you pass `--force`; this leaves
+older v0.2.x schema version 1 files untouched until the user explicitly
+chooses to replace them.
+
+Nex v0.3.0 executes one workflow command at a time. It does not configure
+environments, orchestrate multiple services, or supervise process trees. When
+one component exposes more than one suggestion, Nex runs its first deterministic
+suggestion (`dev` before `start`).
+
+## Not yet
+
+- Multi-service orchestration and process supervision
+- Automatic workflow detection beyond the reported file signals
+- Dependency installation
+
+## License
+
+Nex is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for the
+full terms.
+
+The `v0.1.0`, `v0.2.0`, and `v0.2.1` release tags and their distributed
+artifacts remain available under their original MIT licenses. This change does
+not revoke permissions already granted under those licenses.
+
+---
+
+© 2026 Ankush Thakur. All rights reserved.

{nex_cli-0.2.1 → nex_cli-0.3.0}/nex/cli.py

@@ -9,7 +9,8 @@ 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
+from nex.discovery import discover_project
+from nex.execution import WorkflowConfigError, run_configured_workflow
 
 
 def version_callback(value: bool) -> None:
@@ -37,10 +38,20 @@ def main(
         is_eager=True,
         help="Show the Nex version and exit.",
     ),
+    component: str | None = typer.Option(
+        None,
+        "--component",
+        help="Select one component path when multiple workflows are available.",
+    ),
 ) -> None:
     """Nex command-line interface."""
     if ctx.invoked_subcommand is None and not version:
-        typer.echo(ctx.get_help())
+        try:
+            exit_code = run_configured_workflow(Path.cwd().resolve(), component)
+        except WorkflowConfigError as error:
+            typer.echo(str(error), err=True)
+            raise typer.Exit(code=1) from None
+        raise typer.Exit(code=exit_code)
 
 
 @app.command()
@@ -53,31 +64,44 @@ def learn(
 ) -> None:
     """Detect project signals and save them to .nex/config.toml."""
     root = Path.cwd().resolve()
-    detection = detect_project(directory=root)
+    discovery = discover_project(root)
     console = Console()
 
-    if not detection.found_anything:
+    if not discovery.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")
+        table.add_column("Component", style="bold")
+        table.add_column("Role")
+        table.add_column("Signals")
+        table.add_column("Workflow")
+
+        for component in discovery.components:
+            workflows = []
+            for workflow in component.workflows:
+                details = workflow.ecosystem
+                if workflow.package_manager:
+                    details += f"/{workflow.package_manager}"
+                if workflow.scripts:
+                    details += f" ({', '.join(workflow.scripts)})"
+                workflows.append(details)
+            table.add_row(
+                component.relative_path.as_posix(),
+                component.role,
+                ", ".join(signal.name for signal in component.signals),
+                ", ".join(workflows) or "-",
+            )
 
         console.print(table)
+        for component in discovery.components:
+            for warning in component.warnings:
+                console.print(f"[yellow]Warning: {warning}[/yellow]")
 
     try:
         config_path = write_learn_config(
-            build_learn_config(root, detection), force=force
+            build_learn_config(root, discovery), force=force
         )
     except ConfigAlreadyExistsError as error:
         console.print(

nex_cli-0.3.0/nex/config.py

@@ -0,0 +1,147 @@
+"""Persistence for the project signals learned by Nex."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from nex.discovery.models import ProjectDiscovery
+
+
+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 discovery result."""
+
+    root: Path
+    components: tuple[ComponentConfig, ...]
+
+
+@dataclass(frozen=True)
+class ComponentConfig:
+    """The serializable representation of one discovered component."""
+
+    name: str
+    path: str
+    role: str
+    signals: tuple[str, ...]
+    workflows: tuple[WorkflowConfig, ...]
+    warnings: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class WorkflowConfig:
+    """The serializable representation of one component workflow."""
+
+    ecosystem: str
+    manifest: str
+    package_manager: str | None
+    scripts: tuple[str, ...]
+    metadata: tuple[tuple[str, str], ...]
+    suggested_commands: tuple[str, ...]
+
+
+def build_learn_config(root: Path, discovery: ProjectDiscovery) -> LearnConfig:
+    """Convert a project discovery result into Nex's persisted configuration."""
+    components = tuple(
+        ComponentConfig(
+            name=component.name,
+            path=component.relative_path.as_posix(),
+            role=component.role,
+            signals=tuple(signal.name for signal in component.signals),
+            workflows=tuple(
+                WorkflowConfig(
+                    ecosystem=workflow.ecosystem,
+                    manifest=workflow.manifest,
+                    package_manager=workflow.package_manager,
+                    scripts=workflow.scripts,
+                    metadata=workflow.metadata,
+                    suggested_commands=workflow.suggested_commands,
+                )
+                for workflow in component.workflows
+            ),
+            warnings=component.warnings,
+        )
+        for component in discovery.components
+    )
+    return LearnConfig(root=root.resolve(), components=components)
+
+
+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 v2 multi-component configuration schema as TOML."""
+    lines = [
+        "schema_version = 2",
+        "",
+        "[project]",
+        f"name = {_toml_string(config.root.name)}",
+        f"root = {_toml_string(str(config.root))}",
+    ]
+    for component in config.components:
+        lines.extend(
+            (
+                "",
+                "[[components]]",
+                f"name = {_toml_string(component.name)}",
+                f"path = {_toml_string(component.path)}",
+                f"role = {_toml_string(component.role)}",
+                f"signals = {_toml_string_array(component.signals)}",
+            )
+        )
+        for workflow in component.workflows:
+            lines.extend(
+                (
+                    "",
+                    "[[components.workflows]]",
+                    f"ecosystem = {_toml_string(workflow.ecosystem)}",
+                    f"manifest = {_toml_string(workflow.manifest)}",
+                )
+            )
+            if workflow.package_manager is not None:
+                lines.append(
+                    f"package_manager = {_toml_string(workflow.package_manager)}"
+                )
+            lines.append(f"scripts = {_toml_string_array(workflow.scripts)}")
+            lines.append(
+                f"suggested_commands = {_toml_string_array(workflow.suggested_commands)}"
+            )
+            if workflow.metadata:
+                lines.append("[components.workflows.metadata]")
+                for key, value in workflow.metadata:
+                    lines.append(f"{_toml_key(key)} = {_toml_string(value)}")
+        if component.warnings:
+            lines.append(f"warnings = {_toml_string_array(component.warnings)}")
+
+    lines.append("")
+    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)}]"
+
+
+def _toml_key(value: str) -> str:
+    return value if value.replace("-", "").replace("_", "").isalnum() else _toml_string(value)

nex_cli-0.3.0/nex/discovery/__init__.py

@@ -0,0 +1,13 @@
+"""Multi-directory project discovery for Nex."""
+
+from nex.discovery.models import Component, ProjectDiscovery, Signal, Workflow
+from nex.discovery.scanner import DEFAULT_MAX_DEPTH, discover_project
+
+__all__ = [
+    "Component",
+    "DEFAULT_MAX_DEPTH",
+    "ProjectDiscovery",
+    "Signal",
+    "Workflow",
+    "discover_project",
+]