ud-kibot 0.1.1__tar.gz

ud_kibot-0.1.1/LICENSE

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

ud_kibot-0.1.1/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: ud-kibot
+Version: 0.1.1
+Summary: UltraDuino KiCad/KiBot project automation CLI
+Author-email: UltraDuino <ops@ultraduino.org>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/ultraduino/ud-kibot
+Project-URL: Repository, https://gitlab.com/ultraduino/ud-kibot.git
+Project-URL: Documentation, https://gitlab.com/ultraduino/ud-kibot/-/blob/develop/README.md
+Keywords: kicad,kibot,gitlab,pcb,ci,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: packaging>=24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.0; extra == "release"
+Dynamic: license-file
+
+# ud-kibot
+
+UltraDuino CLI for KiCad/KiBot project automation.
+
+## Install
+
+```bash
+pip install ud-kibot
+```
+
+Development install:
+
+```bash
+cd ud-kibot
+pip install -e ".[dev,release]"
+pre-commit install
+pre-commit install --hook-type commit-msg
+```
+
+## Quick start
+
+```bash
+ud-kibot config init
+cd ../ucube_left_card
+ud-kibot init . --board ucube_left_card --skip-pcb-scaffold
+ud-kibot install . --template-path ../ultraduino-kibot-template
+ud-kibot doctor .
+```
+
+## Development
+
+```bash
+make lint
+make test
+```
+
+Coverage gate: **80%** (`pyproject.toml`).
+
+## Release flow
+
+Same model as `esys-ci-host`:
+
+1. Update `[Unreleased]` in `CHANGELOG.md`
+2. `make bump-release` (or `python scripts/bump_release.py`)
+3. Merge to `master`, wait for green CI
+4. `make tag-release` (or `python scripts/tag_release.py --yes`)
+5. `git push origin vX.Y.Z`
+
+Tag pipelines build the wheel, smoke-install it, publish to GitLab PyPI, then optionally TestPyPI/PyPI.
+
+## User configuration
+
+- Linux/macOS: `~/.config/ud-kibot/config.yaml`
+- Windows: `%APPDATA%\ud-kibot\config.yaml`
+
+Default template: `https://gitlab.com/ultraduino/ultraduino-kibot-template.git`
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ud_kibot-0.1.1/README.md

@@ -0,0 +1,60 @@
+# ud-kibot
+
+UltraDuino CLI for KiCad/KiBot project automation.
+
+## Install
+
+```bash
+pip install ud-kibot
+```
+
+Development install:
+
+```bash
+cd ud-kibot
+pip install -e ".[dev,release]"
+pre-commit install
+pre-commit install --hook-type commit-msg
+```
+
+## Quick start
+
+```bash
+ud-kibot config init
+cd ../ucube_left_card
+ud-kibot init . --board ucube_left_card --skip-pcb-scaffold
+ud-kibot install . --template-path ../ultraduino-kibot-template
+ud-kibot doctor .
+```
+
+## Development
+
+```bash
+make lint
+make test
+```
+
+Coverage gate: **80%** (`pyproject.toml`).
+
+## Release flow
+
+Same model as `esys-ci-host`:
+
+1. Update `[Unreleased]` in `CHANGELOG.md`
+2. `make bump-release` (or `python scripts/bump_release.py`)
+3. Merge to `master`, wait for green CI
+4. `make tag-release` (or `python scripts/tag_release.py --yes`)
+5. `git push origin vX.Y.Z`
+
+Tag pipelines build the wheel, smoke-install it, publish to GitLab PyPI, then optionally TestPyPI/PyPI.
+
+## User configuration
+
+- Linux/macOS: `~/.config/ud-kibot/config.yaml`
+- Windows: `%APPDATA%\ud-kibot\config.yaml`
+
+Default template: `https://gitlab.com/ultraduino/ultraduino-kibot-template.git`
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ud_kibot-0.1.1/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ud-kibot"
+dynamic = ["version"]
+description = "UltraDuino KiCad/KiBot project automation CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "UltraDuino", email = "ops@ultraduino.org" }]
+keywords = ["kicad", "kibot", "gitlab", "pcb", "ci", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+  "typer>=0.12",
+  "pydantic>=2.0",
+  "jinja2>=3.1",
+  "pyyaml>=6.0",
+  "rich>=13.0",
+  "packaging>=24.0",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/ultraduino/ud-kibot"
+Repository = "https://gitlab.com/ultraduino/ud-kibot.git"
+Documentation = "https://gitlab.com/ultraduino/ud-kibot/-/blob/develop/README.md"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.8",
+]
+release = [
+  "build>=1.2",
+  "twine>=5.0",
+]
+
+[project.scripts]
+ud-kibot = "ud_kibot.cli.main:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "ud_kibot.__version__" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.coverage.run]
+source = ["ud_kibot"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true

ud_kibot-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ud_kibot-0.1.1/src/ud_kibot/__init__.py

@@ -0,0 +1,3 @@
+"""UltraDuino KiCad/KiBot automation CLI."""
+
+__version__ = "0.1.1"

ud_kibot-0.1.1/src/ud_kibot/__main__.py

@@ -0,0 +1,4 @@
+from ud_kibot.cli.main import app
+
+if __name__ == "__main__":
+    app()

ud_kibot-0.1.1/src/ud_kibot/assets/resolver.py

@@ -0,0 +1,15 @@
+"""Resolve project logo: project override wins over template default."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_logo(project_dir: Path, template_dir: Path) -> Path:
+    project_logo = project_dir / "assets" / "logo.png"
+    if project_logo.is_file():
+        return project_logo
+    template_logo = template_dir / "assets" / "logo.png"
+    if template_logo.is_file():
+        return template_logo
+    return project_logo

ud_kibot-0.1.1/src/ud_kibot/cli/main.py

@@ -0,0 +1,372 @@
+"""Typer CLI entry point."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ud_kibot import __version__
+from ud_kibot.config.loader import load_user_config, save_user_config
+from ud_kibot.config.schema import (
+    BoardMeta,
+    CiMeta,
+    DocumentationMeta,
+    GitLabCiMeta,
+    KibotMeta,
+    KicadMeta,
+    ProjectConfig,
+    ProjectMeta,
+    SiteMeta,
+    TemplatePin,
+)
+from ud_kibot.config.user_schema import (
+    DefaultsConfig,
+    TemplateSourceConfig,
+    UserConfig,
+)
+from ud_kibot.doctor.checks import doctor_project
+from ud_kibot.hooks import install_pre_commit_hooks
+from ud_kibot.kibot.invoke import prepare_and_run
+from ud_kibot.pages import assemble_pages
+from ud_kibot.paths import normalize_project_dir
+from ud_kibot.template.installer import install_project_scaffold
+from ud_kibot.template.renderer import render_kibot_main
+from ud_kibot.template.resolver import (
+    ensure_template_cached,
+    fetch_git_template,
+    resolve_template_for_project,
+    template_source_for_id,
+)
+from ud_kibot.validate import validate_project
+
+app = typer.Typer(
+    name="ud-kibot",
+    help="UltraDuino KiCad/KiBot project automation.",
+    no_args_is_help=True,
+)
+config_app = typer.Typer(help="User configuration.")
+template_app = typer.Typer(help="Template cache management.")
+app.add_typer(config_app, name="config")
+app.add_typer(template_app, name="template")
+
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version.",
+    ),
+) -> None:
+    """Root callback."""
+
+
+def _resolve_path(path: Path) -> Path:
+    return normalize_project_dir(path)
+
+
+def _resolve_template_path(template_path: Path | None) -> Path | None:
+    return template_path.resolve() if template_path else None
+
+
+@config_app.command("init")
+def config_init(
+    non_interactive: bool = typer.Option(
+        False, "--non-interactive", help="Skip prompts; accept defaults."
+    ),
+    accept_defaults: bool = typer.Option(
+        False, "--accept-defaults", help="Alias for non-interactive with defaults."
+    ),
+) -> None:
+    """Initialize user configuration."""
+    existing = load_user_config()
+    if existing.first_run_complete and not non_interactive and not accept_defaults:
+        overwrite = typer.confirm("User config already exists. Overwrite?", default=False)
+        if not overwrite:
+            raise typer.Exit()
+
+    if non_interactive or accept_defaults:
+        config = UserConfig.create_default()
+    else:
+        use_default = typer.confirm(
+            "Use ultraduino-kibot-template as default template?\n"
+            "  https://gitlab.com/ultraduino/ultraduino-kibot-template.git",
+            default=True,
+        )
+        if use_default:
+            config = UserConfig.create_default()
+        else:
+            template_id = typer.prompt("Template id", default="custom-template")
+            git_url = typer.prompt("Template git URL")
+            config = UserConfig(
+                first_run_complete=True,
+                defaults=DefaultsConfig(template_id=template_id),
+                templates={
+                    template_id: TemplateSourceConfig(git_url=git_url, default_ref="master"),
+                },
+            )
+
+    path = save_user_config(config)
+    console.print(f"[green]Wrote user config:[/green] {path}")
+
+
+@config_app.command("show")
+def config_show() -> None:
+    """Show user configuration."""
+    from ud_kibot.paths import user_config_path
+
+    config = load_user_config()
+    console.print(config.model_dump_json(indent=2))
+    console.print(f"\nPath: {user_config_path()}")
+
+
+@app.command("init")
+def project_init(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    board: str = typer.Option(..., "--board", "-b", help="KiCad project basename."),
+    title: str = typer.Option("", "--title", help="Board title."),
+    skip_pcb_scaffold: bool = typer.Option(
+        False, "--skip-pcb-scaffold", help="Do not create pcb/ scaffold."
+    ),
+) -> None:
+    """Initialize a PCB project with ud-kibot.yaml and directories."""
+    project_dir = _resolve_path(path)
+    project_dir.mkdir(parents=True, exist_ok=True)
+    pcb_dir = project_dir / "pcb"
+    pcb_dir.mkdir(exist_ok=True)
+
+    if not skip_pcb_scaffold:
+        (pcb_dir / "lib").mkdir(exist_ok=True)
+        (pcb_dir / "Templates").mkdir(exist_ok=True)
+
+    for sub in ("assets", "kibot/local", "scripts", ".ud-kibot"):
+        (project_dir / sub).mkdir(parents=True, exist_ok=True)
+
+    config_path = project_dir / "ud-kibot.yaml"
+    if not config_path.is_file():
+        board_title = title or board.replace("_", " ").title()
+        config = ProjectConfig(
+            template=TemplatePin(),
+            project=ProjectMeta(id=board, name=board_title),
+            board=BoardMeta(basename=board, title=board_title),
+            kicad=KicadMeta(),
+            kibot=KibotMeta(),
+            documentation=DocumentationMeta(site=SiteMeta(title=f"UltraDuino · {board}")),
+            ci=CiMeta(gitlab=GitLabCiMeta()),
+        )
+        from ud_kibot.config.loader import save_project_config
+
+        save_project_config(project_dir, config)
+        console.print(f"[green]Created[/green] {config_path}")
+    else:
+        console.print(f"[yellow]Exists[/yellow] {config_path}")
+
+
+@app.command("install")
+def project_install(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    template_path: Path | None = typer.Option(
+        None, "--template-path", help="Local template checkout (dev)."
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite scaffold files."),
+    skip_hooks: bool = typer.Option(False, "--skip-hooks", help="Do not run pre-commit install."),
+) -> None:
+    """Bind project to template and install minimal scaffold."""
+    project_dir = _resolve_path(path)
+    written = install_project_scaffold(
+        project_dir,
+        template_path=_resolve_template_path(template_path),
+        force=force,
+    )
+    console.print(f"[green]Installed template scaffold ({len(written)} files).[/green]")
+    for item in written:
+        console.print(f"  - {item.relative_to(project_dir)}")
+    if not skip_hooks:
+        _report_hook_install(project_dir)
+
+
+@app.command("install-hooks")
+def project_install_hooks(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+) -> None:
+    """Install pre-commit and commit-msg hooks for a PCB project."""
+    _report_hook_install(_resolve_path(path))
+
+
+def _report_hook_install(project_dir: Path) -> None:
+    ok, message = install_pre_commit_hooks(project_dir)
+    if ok:
+        console.print(f"[green]{message}[/green]")
+    else:
+        console.print(f"[yellow]Pre-commit hooks not installed: {message}[/yellow]")
+        console.print("  Install pre-commit, then run: ud-kibot install-hooks .")
+
+
+@app.command("upgrade")
+def project_upgrade(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+    force: bool = typer.Option(False, "--force"),
+) -> None:
+    """Refresh template cache and re-render project files."""
+    project_install(path=path, template_path=template_path, force=force)
+
+
+@app.command("repair")
+def project_repair(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+) -> None:
+    """Re-fetch template, rewrite lock, and re-render."""
+    project_dir = _resolve_path(path)
+    ensure_template_cached(project_dir, template_path=_resolve_template_path(template_path))
+    install_project_scaffold(
+        project_dir,
+        template_path=_resolve_template_path(template_path),
+        force=True,
+    )
+    console.print("[green]Repair complete.[/green]")
+
+
+@app.command("render-config")
+def render_config(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+) -> None:
+    """Render KiBot main config and refresh scaffold renders."""
+    project_dir = _resolve_path(path)
+    template_dir, _ = resolve_template_for_project(
+        project_dir, template_path=_resolve_template_path(template_path)
+    )
+    output = render_kibot_main(project_dir, template_dir)
+    console.print(f"[green]Rendered[/green] {output}")
+
+
+@template_app.command("fetch")
+def template_fetch(
+    template_id: str | None = typer.Argument(None, help="Template id."),
+    project: Path | None = typer.Option(None, "--project", help="Fetch template for a project."),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+    ref: str | None = typer.Option(None, "--ref"),
+) -> None:
+    """Fetch template into global cache."""
+    if project is not None:
+        directory = ensure_template_cached(
+            _resolve_path(project), template_path=_resolve_template_path(template_path)
+        )
+        console.print(f"[green]Cached[/green] {directory}")
+        return
+
+    user = load_user_config()
+    tid = template_id or user.defaults.template_id
+    if tid not in user.templates:
+        raise typer.BadParameter(f"Unknown template id: {tid}")
+    git_url, default_ref = template_source_for_id(user, tid)
+    directory = fetch_git_template(tid, git_url, ref or default_ref)
+    from ud_kibot.template.manifest import load_manifest
+
+    manifest = load_manifest(directory)
+    console.print(f"[green]Fetched[/green] {manifest.id}@{manifest.version} → {directory}")
+
+
+@app.command("validate")
+def project_validate(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+    strict: bool = typer.Option(False, "--strict"),
+) -> None:
+    """Validate project configuration and template binding."""
+    issues = validate_project(
+        _resolve_path(path),
+        template_path=_resolve_template_path(template_path),
+        strict=strict,
+    )
+    exit_code = 0
+    for issue in issues:
+        if issue.level == "error":
+            console.print(f"[red]ERROR[/red] {issue.message}")
+            exit_code = 1
+        else:
+            console.print(f"[yellow]WARN[/yellow] {issue.message}")
+    if exit_code:
+        raise typer.Exit(code=exit_code)
+    console.print("[green]Validation passed.[/green]")
+
+
+@app.command("doctor")
+def project_doctor(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+) -> None:
+    """Run health checks."""
+    results = doctor_project(
+        _resolve_path(path), template_path=_resolve_template_path(template_path)
+    )
+    table = Table("Check", "Status", "Detail")
+    failed = False
+    non_fatal = frozenset({"docker", "user-config"})
+    for item in results:
+        ok = item.ok
+        if item.name == "validate" and not ok:
+            failed = True
+        if item.name == "validate-warning":
+            status = "warn"
+        else:
+            status = "ok" if ok else "fail"
+            if not ok and item.name not in non_fatal:
+                failed = True
+        table.add_row(item.name, status, item.detail)
+    console.print(table)
+    if failed:
+        raise typer.Exit(code=1)
+
+
+@app.command("run-kibot")
+def run_kibot(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    variant: str | None = typer.Option(None, "--variant", "-v"),
+    group: str | None = typer.Option(None, "--group", "-g"),
+    skip_pre: str | None = typer.Option(None, "--skip-pre"),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+    no_docker: bool = typer.Option(False, "--no-docker"),
+) -> None:
+    """Render config and run KiBot."""
+    code = prepare_and_run(
+        _resolve_path(path),
+        template_path=_resolve_template_path(template_path),
+        variant=variant,
+        group=group,
+        skip_pre=skip_pre,
+        no_docker=no_docker,
+    )
+    raise typer.Exit(code=code)
+
+
+@app.command("assemble-pages")
+def assemble_pages_cmd(
+    path: Path = typer.Argument(Path("."), help="Project directory."),
+    template_path: Path | None = typer.Option(None, "--template-path"),
+) -> None:
+    """Assemble GitLab Pages site into public/."""
+    public = assemble_pages(
+        _resolve_path(path), template_path=_resolve_template_path(template_path)
+    )
+    console.print(f"[green]Pages assembled at[/green] {public}")
+
+
+if __name__ == "__main__":
+    app()