fastvex 0.0.1__tar.gz

fastvex-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+.fastvex/
+dist/
+build/
+*.egg-info/

fastvex-0.0.1/LICENSE

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

fastvex-0.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: fastvex
+Version: 0.0.1
+Summary: Fast VEX V5 slot-oriented build and upload CLI
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.16.0
+Description-Content-Type: text/markdown
+
+# fastvex
+
+`fastvex` 是面向 VEX V5 / PROS 机器人项目的槽位构建与上传工具。
+
+它会读取机器人项目根目录中的 `fastvex.yaml`，根据 slot、role、route 配置生成构建参数和程序名，调用 PROS 完成构建/上传，并把本机运行状态写入 `.fastvex/state.json`。
+
+## 安装与运行
+
+临时运行：
+
+```powershell
+uvx fastvex validate
+uvx fastvex upload --slots 1,3 -y
+```
+
+全局安装：
+
+```powershell
+pipx install fastvex
+fastvex show
+```
+
+本仓库本地开发时：
+
+```powershell
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## 在机器人项目中使用
+
+在包含 `fastvex.yaml` 的机器人仓库根目录运行：
+
+```powershell
+fastvex validate
+fastvex show
+fastvex upload --slots 1,3 -y
+fastvex route show
+fastvex route set red r1
+```
+
+也可以在机器人项目子目录中运行，`fastvex` 会向上查找 `fastvex.yaml`。
+
+如果需要显式指定配置：
+
+```powershell
+fastvex validate --config D:\path\to\robot\fastvex.yaml
+fastvex --config D:\path\to\robot\fastvex.yaml validate
+```
+
+## 配置与状态
+
+- `fastvex.yaml`：机器人项目配置，建议提交到机器人代码仓库。
+- `.fastvex/state.json`：本机状态与上传历史，建议加入机器人仓库的 `.gitignore`。
+- `vex_upload_config.yaml`：旧配置文件名仍可读取，但新项目建议迁移到 `fastvex.yaml`。
+
+## 常用命令
+
+```powershell
+# 初始化 fastvex.yaml 和 .fastvex/state.json，不覆盖已有文件
+fastvex init
+
+# 校验配置
+fastvex validate
+
+# 展示槽位映射、当前状态和历史
+fastvex show
+
+# 预览上传，不执行 PROS 构建/上传
+fastvex upload --slots 3 --dry-run
+
+# 上传指定槽位
+fastvex upload --slots 1,3 -y
+
+# 按配置中的分组上传
+fastvex upload --group all-enabled -y
+
+# 查看和切换当前路线
+fastvex route show
+fastvex route set red r1
+
+# 查看和清理历史
+fastvex history show
+fastvex history clean --keep 10
+```
+
+## Python API
+
+`fastvex` 也提供命令级 Python API，方便测试或脚本复用：
+
+```python
+from fastvex.services import UploadRequest, upload_slots, validate_project
+
+report = validate_project(config="D:/path/to/robot/fastvex.yaml")
+assert report.warnings == []
+
+upload_report = upload_slots(
+    UploadRequest(slots="3", dry_run=True),
+    config="D:/path/to/robot/fastvex.yaml",
+)
+assert upload_report.failed_slots == []
+```

fastvex-0.0.1/README.md

@@ -0,0 +1,103 @@
+# fastvex
+
+`fastvex` 是面向 VEX V5 / PROS 机器人项目的槽位构建与上传工具。
+
+它会读取机器人项目根目录中的 `fastvex.yaml`，根据 slot、role、route 配置生成构建参数和程序名，调用 PROS 完成构建/上传，并把本机运行状态写入 `.fastvex/state.json`。
+
+## 安装与运行
+
+临时运行：
+
+```powershell
+uvx fastvex validate
+uvx fastvex upload --slots 1,3 -y
+```
+
+全局安装：
+
+```powershell
+pipx install fastvex
+fastvex show
+```
+
+本仓库本地开发时：
+
+```powershell
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## 在机器人项目中使用
+
+在包含 `fastvex.yaml` 的机器人仓库根目录运行：
+
+```powershell
+fastvex validate
+fastvex show
+fastvex upload --slots 1,3 -y
+fastvex route show
+fastvex route set red r1
+```
+
+也可以在机器人项目子目录中运行，`fastvex` 会向上查找 `fastvex.yaml`。
+
+如果需要显式指定配置：
+
+```powershell
+fastvex validate --config D:\path\to\robot\fastvex.yaml
+fastvex --config D:\path\to\robot\fastvex.yaml validate
+```
+
+## 配置与状态
+
+- `fastvex.yaml`：机器人项目配置，建议提交到机器人代码仓库。
+- `.fastvex/state.json`：本机状态与上传历史，建议加入机器人仓库的 `.gitignore`。
+- `vex_upload_config.yaml`：旧配置文件名仍可读取，但新项目建议迁移到 `fastvex.yaml`。
+
+## 常用命令
+
+```powershell
+# 初始化 fastvex.yaml 和 .fastvex/state.json，不覆盖已有文件
+fastvex init
+
+# 校验配置
+fastvex validate
+
+# 展示槽位映射、当前状态和历史
+fastvex show
+
+# 预览上传，不执行 PROS 构建/上传
+fastvex upload --slots 3 --dry-run
+
+# 上传指定槽位
+fastvex upload --slots 1,3 -y
+
+# 按配置中的分组上传
+fastvex upload --group all-enabled -y
+
+# 查看和切换当前路线
+fastvex route show
+fastvex route set red r1
+
+# 查看和清理历史
+fastvex history show
+fastvex history clean --keep 10
+```
+
+## Python API
+
+`fastvex` 也提供命令级 Python API，方便测试或脚本复用：
+
+```python
+from fastvex.services import UploadRequest, upload_slots, validate_project
+
+report = validate_project(config="D:/path/to/robot/fastvex.yaml")
+assert report.warnings == []
+
+upload_report = upload_slots(
+    UploadRequest(slots="3", dry_run=True),
+    config="D:/path/to/robot/fastvex.yaml",
+)
+assert upload_report.failed_slots == []
+```

fastvex-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "fastvex"
+version = "0.0.1"
+description = "Fast VEX V5 slot-oriented build and upload CLI"
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "PyYAML>=6.0.2",
+  "pydantic>=2.11",
+  "rich>=13.0",
+  "typer>=0.16.0",
+]
+
+[project.scripts]
+fastvex = "fastvex.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3.5",
+  "ruff>=0.11.2",
+]
+
+[tool.ruff]
+line-length = 100
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastvex"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/fastvex",
+  "tests",
+  "LICENSE",
+  "README.md",
+]

fastvex-0.0.1/src/fastvex/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"

fastvex-0.0.1/src/fastvex/cli.py

@@ -0,0 +1,383 @@
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import click
+import typer
+
+from .display import print_execution_result, print_history, print_show, print_upload_plan
+from .services import (
+    HistoryCleanReport,
+    UploadRequest,
+    clean_history,
+    get_history,
+    init_project,
+    plan_upload,
+    set_route,
+    show_project,
+    show_routes,
+    upload_slots,
+    validate_project,
+)
+from .storage import ValidationError
+from .theme import FAIL, INFO, OK, WARN, confirm, console
+
+CommonConfig = Annotated[str | None, typer.Option("--config", help="Config file path.")]
+CommonState = Annotated[str | None, typer.Option("--state", help="State file path.")]
+
+app = typer.Typer(
+    name="fastvex",
+    help="Fast VEX slot-oriented build/upload manager.",
+    invoke_without_command=True,
+)
+history_app = typer.Typer(help="Show or clean history.")
+route_app = typer.Typer(help="Show or set active route by route set.")
+app.add_typer(history_app, name="history")
+app.add_typer(route_app, name="route")
+
+
+def rprint(*args, **kwargs) -> None:
+    """Rich-aware print: uses console.print unless an explicit file= is given."""
+    file = kwargs.pop("file", None)
+    if file is not None:
+        kwargs.setdefault("sep", " ")
+        kwargs.setdefault("end", "\n")
+        kwargs.setdefault("flush", False)
+        print(*args, file=file, **kwargs)
+    else:
+        console.print(*args, **kwargs)
+
+
+def _ctx_options(ctx: typer.Context, config: str | None, state: str | None) -> dict[str, str | None]:
+    obj = ctx.obj or {}
+    return {
+        "config": config if config is not None else obj.get("config"),
+        "state": state if state is not None else obj.get("state"),
+    }
+
+
+def _print_legacy_warning(legacy_config: bool, config_path: object) -> None:
+    if legacy_config:
+        rprint(f"  [yellow]{WARN} using legacy config name:[/yellow] {config_path}")
+
+
+def _finish(code: int) -> None:
+    if code:
+        raise typer.Exit(code)
+
+
+def _upload_request(
+    *,
+    slots: str | None = None,
+    group: str | None = None,
+    all_enabled: bool = False,
+    robot_name: str | None = None,
+    port: str | None = None,
+    clean: bool = False,
+    quiet: bool = False,
+    dry_run: bool = False,
+    yes: bool = False,
+) -> UploadRequest:
+    return UploadRequest(
+        slots=slots,
+        group=group,
+        all_enabled=all_enabled,
+        robot_name=robot_name,
+        port=port,
+        clean=clean,
+        quiet=quiet,
+        dry_run=dry_run,
+        yes=yes,
+    )
+
+
+def run_default_interactive(config: str | None = None, state: str | None = None) -> int:
+    report = show_project(config=config, state=state)
+    _print_legacy_warning(report.paths.legacy_config, report.paths.config)
+    print_show(report.config, report.state)
+
+    rprint("  [bold cyan]Select upload target:[/bold cyan]")
+    rprint("    [dim]slot list[/dim]  e.g. [green]1,3,5[/green]")
+    rprint("    [dim]group:name[/dim]  e.g. [green]group:comp-default[/green]")
+    rprint("    [dim]all[/dim]         upload all enabled slots")
+    rprint("    [dim]q[/dim]           quit")
+    rprint()
+
+    raw = console.input("  [cyan]target[/cyan]> ").strip()
+    if not raw or raw.lower() in {"q", "quit", "exit"}:
+        rprint("\n  [blue]bye[/blue]\n")
+        return 0
+
+    request = _upload_request()
+    if raw.lower() == "all":
+        request = _upload_request(all_enabled=True)
+    elif raw.lower().startswith("group:"):
+        request = _upload_request(group=raw.split(":", 1)[1].strip())
+    else:
+        request = _upload_request(slots=raw)
+
+    planned = plan_upload(request, config=config, state=state)
+    paths, loaded_config, _, slots, _, _ = planned
+    _print_legacy_warning(paths.legacy_config, paths.config)
+    print_upload_plan(loaded_config, slots)
+    if not confirm(
+        "  [yellow]Continue upload?[/yellow] [[green]Y[/green]/[red]n[/red]] (Enter for 'Y'): ",
+        default_yes=True,
+    ):
+        rprint(f"\n  [yellow]{WARN} aborted[/yellow]\n")
+        return 0
+
+    report = upload_slots(request, config=config, state=state)
+    if report.execution:
+        print_execution_result(report.execution)
+    return 1 if report.failed_slots else 0
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    ctx.obj = {"config": config, "state": state}
+    if ctx.invoked_subcommand is None:
+        _finish(run_default_interactive(config=config, state=state))
+
+
+@app.command("init")
+def init_command(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    options = _ctx_options(ctx, config, state)
+    report = init_project(**options)
+
+    if report.config_exists:
+        rprint(f"  [cyan]config exists:[/cyan] {report.paths.config}")
+    elif report.legacy_config_exists:
+        rprint(f"  [yellow]{WARN} legacy config exists:[/yellow] {report.paths.root / 'vex_upload_config.yaml'}")
+        rprint("  [dim]fastvex init will not migrate or overwrite configs.[/dim]")
+    elif report.config_created:
+        rprint(f"  [green]created config:[/green] {report.paths.config}")
+
+    if report.state_exists:
+        rprint(f"  [cyan]state exists:[/cyan] {report.paths.state}")
+    elif report.state_created:
+        rprint(f"  [green]created state:[/green] {report.paths.state}")
+
+    rprint(f"\n  [bold green]{OK} init ok[/bold green]\n")
+
+
+@app.command("show")
+def show_command(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    report = show_project(**_ctx_options(ctx, config, state))
+    _print_legacy_warning(report.paths.legacy_config, report.paths.config)
+    print_show(report.config, report.state)
+
+
+@app.command("validate")
+def validate_command(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    report = validate_project(**_ctx_options(ctx, config, state))
+    _print_legacy_warning(report.paths.legacy_config, report.paths.config)
+    for warning in report.warnings:
+        rprint(f"  {WARN} {warning}")
+    rprint(f"\n  [bold green]{OK} validate ok[/bold green]\n")
+
+
+@app.command("upload")
+def upload_command(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+    slots: Annotated[str | None, typer.Option("--slots", help="Slot list, e.g. '1,3,5'.")] = None,
+    group: Annotated[str | None, typer.Option("--group", help="Group name defined in config.")] = None,
+    all_enabled: Annotated[
+        bool,
+        typer.Option("--all-enabled", help="Target all configured slots."),
+    ] = False,
+    robot_name: Annotated[str | None, typer.Option("--robot-name", help="Override robot name.")] = None,
+    port: Annotated[str | None, typer.Option("--port", help="Override port. Empty means auto.")] = None,
+    clean: Annotated[bool, typer.Option("--clean", help="Run make clean before build.")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Capture build/upload output.")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Plan without build/upload.")] = False,
+    yes: Annotated[bool, typer.Option("-y", "--yes", help="Skip confirm prompt.")] = False,
+) -> None:
+    options = _ctx_options(ctx, config, state)
+    request = _upload_request(
+        slots=slots,
+        group=group,
+        all_enabled=all_enabled,
+        robot_name=robot_name,
+        port=port,
+        clean=clean,
+        quiet=quiet,
+        dry_run=dry_run,
+        yes=yes,
+    )
+    paths, loaded_config, _, selected_slots, _, _ = plan_upload(request, **options)
+    _print_legacy_warning(paths.legacy_config, paths.config)
+    print_upload_plan(loaded_config, selected_slots)
+
+    if not yes and not dry_run:
+        if not confirm(
+            "  [yellow]Continue upload?[/yellow] [[green]Y[/green]/[red]n[/red]] (Enter for 'Y'): ",
+            default_yes=True,
+        ):
+            rprint(f"\n  [yellow]{WARN} aborted[/yellow]\n")
+            return
+
+    report = upload_slots(request, **options)
+    if report.execution:
+        print_execution_result(report.execution)
+    _finish(1 if report.failed_slots else 0)
+
+
+@history_app.callback()
+def history_root(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    parent = ctx.parent.obj if ctx.parent and ctx.parent.obj else {}
+    ctx.obj = {
+        "config": config if config is not None else parent.get("config"),
+        "state": state if state is not None else parent.get("state"),
+    }
+
+
+@history_app.command("show")
+def history_show_command(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    report = get_history(**_ctx_options(ctx, config, state))
+    _print_legacy_warning(report.paths.legacy_config, report.paths.config)
+    rprint()
+    if not report.state.history:
+        rprint("  [dim](empty)[/dim]")
+    else:
+        print_history(report.state.history)
+
+
+@history_app.command("clean")
+def history_clean_command(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+    keep: Annotated[int, typer.Option("--keep", help="Number of entries to keep.")] = 10,
+) -> None:
+    report: HistoryCleanReport = clean_history(**_ctx_options(ctx, config, state), keep=keep)
+    _print_legacy_warning(report.paths.legacy_config, report.paths.config)
+    if report.removed_count == 0:
+        rprint(f"  [dim]history has {report.kept_count} entries, no cleanup needed (keep={keep})[/dim]")
+    else:
+        rprint(
+            f"  [green]{OK} cleaned[/green] {report.removed_count} "
+            f"[dim]old entries, kept last[/dim] {report.kept_count}"
+        )
+
+
+@route_app.callback()
+def route_root(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    parent = ctx.parent.obj if ctx.parent and ctx.parent.obj else {}
+    ctx.obj = {
+        "config": config if config is not None else parent.get("config"),
+        "state": state if state is not None else parent.get("state"),
+    }
+
+
+@route_app.command("show")
+def route_show_command(
+    ctx: typer.Context,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    from .theme import role_tone
+
+    report = show_routes(**_ctx_options(ctx, config, state))
+    _print_legacy_warning(report.paths.legacy_config, report.paths.config)
+    loaded_config = report.config
+
+    rprint()
+    route_items = []
+    for route_set in sorted(loaded_config.active_route.keys()):
+        color, _ = role_tone(route_set, "COMP")
+        key = loaded_config.active_route[route_set]
+        route_items.append(f"[bold {color}]{route_set}[/bold {color}]:[{color}]{key}[/{color}]")
+
+    rprint("  [bold cyan]Active Routes[/bold cyan]")
+    rprint(f"  {'   '.join(route_items)}")
+    rprint()
+
+    rprint("  [bold cyan]Available Routes[/bold cyan]")
+    for route_set in sorted(loaded_config.routes.keys()):
+        color, _ = role_tone(route_set, "COMP")
+        active_key = loaded_config.active_route.get(route_set)
+
+        rprint(f"\n  [bold {color}]{route_set}[/bold {color}]")
+        for key, opt in loaded_config.routes[route_set].items():
+            is_active = key == active_key
+            marker = f"[green]{OK}[/green] " if is_active else "    "
+            active_tag = " [green](active)[/green]" if is_active else ""
+            rprint(
+                f"    {marker}[cyan]{key}[/cyan]  "
+                f"route={opt.route}  routeName={opt.route_name}{active_tag}"
+            )
+    rprint()
+
+
+@route_app.command("set")
+def route_set_command(
+    ctx: typer.Context,
+    route_set: str,
+    route_key: str,
+    config: CommonConfig = None,
+    state: CommonState = None,
+) -> None:
+    from .theme import role_tone
+
+    report = set_route(route_set, route_key, **_ctx_options(ctx, config, state))
+    _print_legacy_warning(report.paths.legacy_config, report.paths.config)
+    if not report.changed:
+        rprint(f"\n  [dim]{INFO} route unchanged:[/dim] {report.route_set}={report.new_key}\n")
+        return
+
+    color, _ = role_tone(report.route_set, "COMP")
+    rprint(
+        f"\n  [bold green]{OK} updated active route:[/bold green] "
+        f"[bold {color}]{report.route_set}[/bold {color}] [dim]{report.old_key}[/dim] "
+        f"[cyan]→[/cyan] [bold {color}]{report.new_key}[/bold {color}]\n"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        app(args=argv, prog_name="fastvex", standalone_mode=False)
+        return 0
+    except click.exceptions.Exit as exc:
+        return int(exc.exit_code)
+    except ValidationError as exc:
+        print(f"\n  [bold red]{FAIL} validation error:[/bold red] {exc}\n", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print(f"\n  [yellow]{WARN} interrupted[/yellow]\n", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fastvex-0.0.1/src/fastvex/config_edit.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from .storage import ValidationError
+
+
+def replace_active_route_in_text(text: str, route_set: str, route_key: str) -> str:
+    """Text-based replacement to keep YAML comments/formatting intact."""
+    lines = text.splitlines()
+    in_active = False
+    found = False
+    for idx, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped == "activeRoute:":
+            in_active = True
+            continue
+        if in_active:
+            if stripped and not line.startswith("  "):
+                break
+            key_prefix = f"  {route_set}:"
+            if line.startswith(key_prefix):
+                lines[idx] = f"  {route_set}: {route_key}"
+                found = True
+                break
+    if not found:
+        raise ValidationError(f"failed to update activeRoute.{route_set} in config file")
+    return "\n".join(lines) + "\n"