hector-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{hector_cli-0.3.0/hector_cli.egg-info → hector_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hector-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: YAML-driven Renode + Verilator simulation orchestrator for embedded hardware CI
 Home-page: https://hector-ci.com
 Author: Nemesis
@@ -205,6 +205,7 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector run --gather-execution-metrics boardA` | Enable profiler for one specific machine |
 | `hector run --gather-execution-metrics boardA --gather-execution-metrics boardB` | Enable profiler for selected machines |
 | `hector run --renode-version 1.16.1` | Override the Renode version from `.hector.yaml` |
+| `hector run --renode-image my-renode:dev` | Use a specific (e.g. self-built) Renode Docker image |
 | `hector run --renode-dir /cache/renode` | Use/cache the Renode source checkout at this path (only fetched when needed) |
 | `hector run --renode-integration-dir /cache/integration` | Likewise for the verilator-integration checkout |
 | `hector run --no-docker` | Use locally installed `renode` / `renode-test` instead of Docker |
@@ -229,11 +230,15 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector validate -f board.yaml` | Validate a config file by another name |
 | `hector init` | Scaffold a starter `.hector.yaml` |
 | `hector init -f board.yaml` | Scaffold the starter config under a custom name |
+| `hector clean` | Remove generated build artifacts (`.hector/resc,repl,tests`) and `results/`; keeps the Renode cache |
+| `hector clean --all` | Also remove the cached Renode source checkouts under `.hector/` (forces a re-clone next build) |
+| `hector clean --output my-results` | Clean a custom results directory instead of `results/` |
+| `hector clean --dry-run` | Show what would be removed without deleting anything |
 | `hector --version` | Print the tool version |
 
 `hector` is structured as subcommands: `run` (simulate), `test` (run the `tests:`
-section), `export` (emit the command without running it), plus `init` and
-`validate`. Run `hector <command> --help` for the flags each one accepts.
+section), `export` (emit the command without running it), plus `init`, `validate`,
+and `clean`. Run `hector <command> --help` for the flags each one accepts.
 
 Every command reads (or, for `init`, writes) `.hector.yaml` by default. Point it
 at a different file with **`-f` / `--file`** — useful when one project keeps
@@ -338,7 +343,7 @@ hector run --snapshot results/step_1_Linux_boots/snapshot.save
 hector test --snapshot results/step_1_Linux_boots/snapshot.save
 ```
 
-When used with `--renode-version`, no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
+When used with `--renode-version` (or `--renode-image`), no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
 
 ```bash
 hector run --snapshot /path/to/snapshot.save --renode-version 1.16.1
@@ -503,6 +508,20 @@ When combined with `--snapshot` in simulation mode, `.hector.yaml` is not requir
 hector run --snapshot path/to/snapshot.save --renode-version 1.16.1
 ```
 
+#### Using a custom Renode image (`--renode-image`)
+
+By default the image is `antmicro/renode:<renode_version>`. To use any other image — a nightly, a mirror in your registry, or one you built yourself — set `renode_image:` in `.hector.yaml` or pass `--renode-image`:
+
+```yaml
+renode_image: my-renode:dev
+```
+
+```bash
+hector test --renode-image ghcr.io/acme/renode:1.16.1-patched
+```
+
+Precedence: CLI flags beat the config, and either flag replaces *both* config fields (so `--renode-version 1.15.0` wins over a `renode_image:` in the file). If both fields are set in the config, `renode_image` is the image that runs and `renode_version` only picks the Renode source tag to clone. That tag is otherwise inferred from the image tag when it looks like a version (`…:1.16.1` / `…:v1.16.1`); if the config needs the source (see below) and it can't be inferred, also set `renode_version`.
+
 #### Renode source checkout
 
 Running a simulation does **not** need the Renode source — the binary and its bundled platforms come from the `antmicro/renode` Docker image. Hector clones the Renode source (and the verilator-integration repo) into `.hector/` **only when a config actually needs it**:
@@ -600,7 +619,8 @@ The configuration lives in `.hector.yaml`.
 | Field | Required | Description |
 |---|---|---|
 | `version` | No | Schema version (currently `"0.1"`). Warns if unrecognised. |
-| `renode_version` | Yes | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_version` | Yes¹ | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_image` | Yes¹ | Full Renode Docker image to use instead of `antmicro/renode:<renode_version>` (e.g. a self-built `my-renode:dev`). See [custom Renode image](#using-a-custom-renode-image---renode-image). |
 | `arguments` | No | Scalar defaults, overridable by env var or `--set`. |
 | `build` | No | Pre-sim shell steps run once per job in containers (compile firmware, fetch/generate files, …). Interpolated with the job's arguments/matrix variables. |
 | `matrix` | No | Cross-product job expansion. |
@@ -613,6 +633,8 @@ The configuration lives in `.hector.yaml`.
 | `quantum` | No | Override the global time quantum (seconds). |
 | `ci` | No | CI pipeline definitions: when and how a CI server runs this config. |
 
+¹ At least one of `renode_version` / `renode_image` is required (or the matching CLI flag).
+
 ---
 
 ### arguments
@@ -938,8 +960,26 @@ machines:
 
 - **`repl:`** is written to `.hector/repl/job_<n>_<node>.inline.repl` and loaded with
   `machine LoadPlatformDescription` (Renode only reads platform descriptions from
-  disk). It is loaded **after** any `platform:` files, so it can extend or override
-  them — list a released board under `platform:` and patch it with `repl:`.
+  disk). It is loaded **after** any `platform:` files.
+
+> **Patching a bundled platform: use `using`, not `platform:`.** Every
+> `LoadPlatformDescription` is its **own description scope**, so an entry that another
+> file created is only partly reachable from `repl:` — setting a *constructor*
+> attribute on it fails with
+> `E35: Constructor attribute within entry for variable that is not created`.
+> To override one, pull the base platform into the *same* scope from inside `repl:`:
+>
+> ```yaml
+> repl: |
+>   using "platforms/boards/nucleo_h753zi.repl"
+>
+>   nvic:
+>       priorityMask: 0xFF        # works: same scope that creates `nvic`
+> ```
+>
+> This is what Renode's own scripts do with `LoadPlatformDescriptionFromString`.
+> Use `platform:` alone when you're loading a board as-is, and `using` inside `repl:`
+> when you need to patch it. See [`examples/nucleo-h753zi`](examples/nucleo-h753zi).
 - **`resc:`** is emitted verbatim into that machine's block, **after** the platform
   and firmware load and **before** `commands:`.
 
@@ -966,6 +1006,8 @@ other field. Worked examples:
 - [`examples/nucleo-f767zi`](examples/nucleo-f767zi) — the real motivation: a
   **NUCLEO-F767ZI**, which Renode 1.16.1 ships no `.repl` for at all, defined inline
   and running against the pinned release image.
+- [`examples/nucleo-h753zi`](examples/nucleo-h753zi) — the other side: a board that
+  **is** shipped, loaded via `using` and *patched* inline, booting Hubris.
 
 #### peripherals
 

{hector_cli-0.3.0 → hector_cli-0.4.0}/README.md

@@ -175,6 +175,7 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector run --gather-execution-metrics boardA` | Enable profiler for one specific machine |
 | `hector run --gather-execution-metrics boardA --gather-execution-metrics boardB` | Enable profiler for selected machines |
 | `hector run --renode-version 1.16.1` | Override the Renode version from `.hector.yaml` |
+| `hector run --renode-image my-renode:dev` | Use a specific (e.g. self-built) Renode Docker image |
 | `hector run --renode-dir /cache/renode` | Use/cache the Renode source checkout at this path (only fetched when needed) |
 | `hector run --renode-integration-dir /cache/integration` | Likewise for the verilator-integration checkout |
 | `hector run --no-docker` | Use locally installed `renode` / `renode-test` instead of Docker |
@@ -199,11 +200,15 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector validate -f board.yaml` | Validate a config file by another name |
 | `hector init` | Scaffold a starter `.hector.yaml` |
 | `hector init -f board.yaml` | Scaffold the starter config under a custom name |
+| `hector clean` | Remove generated build artifacts (`.hector/resc,repl,tests`) and `results/`; keeps the Renode cache |
+| `hector clean --all` | Also remove the cached Renode source checkouts under `.hector/` (forces a re-clone next build) |
+| `hector clean --output my-results` | Clean a custom results directory instead of `results/` |
+| `hector clean --dry-run` | Show what would be removed without deleting anything |
 | `hector --version` | Print the tool version |
 
 `hector` is structured as subcommands: `run` (simulate), `test` (run the `tests:`
-section), `export` (emit the command without running it), plus `init` and
-`validate`. Run `hector <command> --help` for the flags each one accepts.
+section), `export` (emit the command without running it), plus `init`, `validate`,
+and `clean`. Run `hector <command> --help` for the flags each one accepts.
 
 Every command reads (or, for `init`, writes) `.hector.yaml` by default. Point it
 at a different file with **`-f` / `--file`** — useful when one project keeps
@@ -308,7 +313,7 @@ hector run --snapshot results/step_1_Linux_boots/snapshot.save
 hector test --snapshot results/step_1_Linux_boots/snapshot.save
 ```
 
-When used with `--renode-version`, no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
+When used with `--renode-version` (or `--renode-image`), no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
 
 ```bash
 hector run --snapshot /path/to/snapshot.save --renode-version 1.16.1
@@ -473,6 +478,20 @@ When combined with `--snapshot` in simulation mode, `.hector.yaml` is not requir
 hector run --snapshot path/to/snapshot.save --renode-version 1.16.1
 ```
 
+#### Using a custom Renode image (`--renode-image`)
+
+By default the image is `antmicro/renode:<renode_version>`. To use any other image — a nightly, a mirror in your registry, or one you built yourself — set `renode_image:` in `.hector.yaml` or pass `--renode-image`:
+
+```yaml
+renode_image: my-renode:dev
+```
+
+```bash
+hector test --renode-image ghcr.io/acme/renode:1.16.1-patched
+```
+
+Precedence: CLI flags beat the config, and either flag replaces *both* config fields (so `--renode-version 1.15.0` wins over a `renode_image:` in the file). If both fields are set in the config, `renode_image` is the image that runs and `renode_version` only picks the Renode source tag to clone. That tag is otherwise inferred from the image tag when it looks like a version (`…:1.16.1` / `…:v1.16.1`); if the config needs the source (see below) and it can't be inferred, also set `renode_version`.
+
 #### Renode source checkout
 
 Running a simulation does **not** need the Renode source — the binary and its bundled platforms come from the `antmicro/renode` Docker image. Hector clones the Renode source (and the verilator-integration repo) into `.hector/` **only when a config actually needs it**:
@@ -570,7 +589,8 @@ The configuration lives in `.hector.yaml`.
 | Field | Required | Description |
 |---|---|---|
 | `version` | No | Schema version (currently `"0.1"`). Warns if unrecognised. |
-| `renode_version` | Yes | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_version` | Yes¹ | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_image` | Yes¹ | Full Renode Docker image to use instead of `antmicro/renode:<renode_version>` (e.g. a self-built `my-renode:dev`). See [custom Renode image](#using-a-custom-renode-image---renode-image). |
 | `arguments` | No | Scalar defaults, overridable by env var or `--set`. |
 | `build` | No | Pre-sim shell steps run once per job in containers (compile firmware, fetch/generate files, …). Interpolated with the job's arguments/matrix variables. |
 | `matrix` | No | Cross-product job expansion. |
@@ -583,6 +603,8 @@ The configuration lives in `.hector.yaml`.
 | `quantum` | No | Override the global time quantum (seconds). |
 | `ci` | No | CI pipeline definitions: when and how a CI server runs this config. |
 
+¹ At least one of `renode_version` / `renode_image` is required (or the matching CLI flag).
+
 ---
 
 ### arguments
@@ -908,8 +930,26 @@ machines:
 
 - **`repl:`** is written to `.hector/repl/job_<n>_<node>.inline.repl` and loaded with
   `machine LoadPlatformDescription` (Renode only reads platform descriptions from
-  disk). It is loaded **after** any `platform:` files, so it can extend or override
-  them — list a released board under `platform:` and patch it with `repl:`.
+  disk). It is loaded **after** any `platform:` files.
+
+> **Patching a bundled platform: use `using`, not `platform:`.** Every
+> `LoadPlatformDescription` is its **own description scope**, so an entry that another
+> file created is only partly reachable from `repl:` — setting a *constructor*
+> attribute on it fails with
+> `E35: Constructor attribute within entry for variable that is not created`.
+> To override one, pull the base platform into the *same* scope from inside `repl:`:
+>
+> ```yaml
+> repl: |
+>   using "platforms/boards/nucleo_h753zi.repl"
+>
+>   nvic:
+>       priorityMask: 0xFF        # works: same scope that creates `nvic`
+> ```
+>
+> This is what Renode's own scripts do with `LoadPlatformDescriptionFromString`.
+> Use `platform:` alone when you're loading a board as-is, and `using` inside `repl:`
+> when you need to patch it. See [`examples/nucleo-h753zi`](examples/nucleo-h753zi).
 - **`resc:`** is emitted verbatim into that machine's block, **after** the platform
   and firmware load and **before** `commands:`.
 
@@ -936,6 +976,8 @@ other field. Worked examples:
 - [`examples/nucleo-f767zi`](examples/nucleo-f767zi) — the real motivation: a
   **NUCLEO-F767ZI**, which Renode 1.16.1 ships no `.repl` for at all, defined inline
   and running against the pinned release image.
+- [`examples/nucleo-h753zi`](examples/nucleo-h753zi) — the other side: a board that
+  **is** shipped, loaded via `using` and *patched* inline, booting Hubris.
 
 #### peripherals
 

{hector_cli-0.3.0 → hector_cli-0.4.0}/hector/commands/__init__.py

@@ -12,7 +12,7 @@ from ..core import TOOL_VERSION
 from .base import COMMANDS, Command, add_common_arguments, add_simulation_arguments
 
 # Importing each module runs its @COMMANDS.register(...) decorator.
-from . import run, test, export, init, validate  # noqa: E402,F401
+from . import run, test, export, init, validate, clean  # noqa: E402,F401
 
 __all__ = ["COMMANDS", "Command", "build_parser",
            "add_common_arguments", "add_simulation_arguments"]

{hector_cli-0.3.0 → hector_cli-0.4.0}/hector/commands/base.py

@@ -53,6 +53,12 @@ def add_common_arguments(parser):
         help="Renode version to use (e.g. 1.16.1). Overrides renode_version from "
              ".hector.yaml.",
     )
+    parser.add_argument(
+        "--renode-image", metavar="IMAGE", dest="renode_image",
+        help="Renode Docker image to use instead of antmicro/renode:<version> (any "
+             "image, e.g. a self-built one: my-renode:dev). Overrides renode_image / "
+             "renode_version from .hector.yaml.",
+    )
     parser.add_argument(
         "--renode-dir", metavar="PATH", dest="renode_dir", default=None,
         help="Location of the Renode source checkout (only fetched when a config builds "

hector_cli-0.4.0/hector/commands/clean.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`hector clean` — remove the files hector generates (the .hector/ build artifacts
+and the results directory), so a project can be reset to a pristine checkout."""
+
+from .. import pipeline
+from .base import COMMANDS, Command
+
+
+@COMMANDS.register("clean")
+class CleanCommand(Command):
+    name = "clean"
+    help = "Remove generated files (.hector/ build outputs and the results directory)."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--output", metavar="DIR", default="results",
+            help="Results directory to remove (default: results). Match the --output "
+                 "you ran with if you used a custom one.",
+        )
+        parser.add_argument(
+            "--all", action="store_true", dest="all",
+            help="Also remove the cached Renode / verilator-integration source "
+                 "checkouts under .hector/ — a full re-clone (~200 MB) happens on the "
+                 "next build. Omit to keep them for fast iteration.",
+        )
+        parser.add_argument(
+            "-n", "--dry-run", action="store_true", dest="dry_run",
+            help="List what would be removed without deleting anything.",
+        )
+
+    def execute(self, args):
+        return pipeline.run_clean(output_dir=args.output,
+                                  include_renode=args.all,
+                                  dry_run=args.dry_run)

{hector_cli-0.3.0 → hector_cli-0.4.0}/hector/commands/run.py

@@ -17,8 +17,8 @@ class RunCommand(Command):
     def execute(self, args):
         pipeline.apply_global_flags(args)
 
-        # Convenience fast path: a snapshot + pinned version needs no .hector.yaml.
-        if args.snapshot and args.renode_version:
+        # Convenience fast path: a snapshot + pinned version/image needs no .hector.yaml.
+        if args.snapshot and (args.renode_version or args.renode_image):
             pipeline.snapshot_fastpath(args)
             return 0
 

{hector_cli-0.3.0 → hector_cli-0.4.0}/hector/core.py

@@ -67,7 +67,7 @@ class Registry:
 # ==========================================================================
 # CONSTANTS
 # ==========================================================================
-TOOL_VERSION = "0.3.0"
+TOOL_VERSION = "0.4.0"
 SUPPORTED_SCHEMA_VERSIONS = {"0.1"}
 
 RENODE_REPO_URL = "https://github.com/renode/renode.git"

{hector_cli-0.3.0 → hector_cli-0.4.0}/hector/pipeline.py

@@ -11,6 +11,7 @@ Phases per job:
 
 import copy
 import os
+import re
 import shlex
 import sys
 from dataclasses import dataclass, field
@@ -106,15 +107,35 @@ def load_config_or_exit():
     return config
 
 
+_VERSION_TAG_RE = re.compile(r"^v?\d+\.\d+\.\d+$")
+
+
 def resolve_renode_image(config, args):
-    """Pin the Renode version from --renode-version or the config; return
-    (git_tag, docker_image)."""
-    renode_version = getattr(args, "renode_version", None) or config.get("renode_version")
-    if not renode_version:
-        raise ValueError("Top-level 'renode_version' is required (e.g. '1.16.1'), "
-                         "or pass --renode-version on the command line.")
-    normalized = str(renode_version).lstrip("v")
-    return f"v{normalized}", f"antmicro/renode:{normalized}"
+    """Pick the Renode Docker image and the git tag of the matching source; return
+    (git_tag, docker_image).
+
+    The image is either an explicit `renode_image` (any image, including a self-built
+    one) or `antmicro/renode:<renode_version>`. CLI flags beat the config, and a flag
+    of either kind replaces both config fields — so `--renode-version` still wins over
+    a `renode_image:` in the file. The git tag (only used to clone the Renode source)
+    comes from the version, or from the image tag when it looks like one; it is None
+    when neither tells us, and only matters if the config needs the source."""
+    flag_version = getattr(args, "renode_version", None)
+    flag_image = getattr(args, "renode_image", None)
+    if flag_version or flag_image:
+        version, image = flag_version, flag_image
+    else:
+        version, image = config.get("renode_version"), config.get("renode_image")
+    if not version and not image:
+        raise ValueError("Top-level 'renode_version' (e.g. '1.16.1') or 'renode_image' "
+                         "is required, or pass --renode-version / --renode-image on the "
+                         "command line.")
+    normalized = str(version).lstrip("v") if version else None
+    image = str(image) if image else f"antmicro/renode:{normalized}"
+    if not normalized:
+        tag = image.rsplit("/", 1)[-1].partition(":")[2]
+        normalized = tag.lstrip("v") if _VERSION_TAG_RE.match(tag) else None
+    return (f"v{normalized}" if normalized else None), image
 
 
 def _resolve_set_overrides(args):
@@ -149,6 +170,10 @@ def build_job_config(action, config, args, *, test_mode=False):
     # Clone Renode only when the config actually needs the source; otherwise skip it
     # entirely (a ~200 MB clone) and leave the framework vars empty.
     if _needs_renode_source(config):
+        if not git_tag:
+            raise ValueError(f"This config needs the Renode source, but the version of "
+                             f"'{docker_image}' can't be inferred from its tag — also set "
+                             "'renode_version' (or --renode-version) to pick the checkout.")
         renode_dir, integration_dir = prepare_dependencies(
             git_tag,
             renode_dir=getattr(args, "renode_dir", None),
@@ -210,13 +235,12 @@ def execute_jobs(cfg, args):
 
 
 def snapshot_fastpath(args):
-    """`run --snapshot --renode-version` with no .hector.yaml: write a snapshot
-    loader resc and boot it directly, skipping config/dependency machinery."""
+    """`run --snapshot --renode-version|--renode-image` with no .hector.yaml: write a
+    snapshot loader resc and boot it directly, skipping config/dependency machinery."""
     if not os.path.isfile(args.snapshot):
         print(f"[ERROR] Snapshot not found: {args.snapshot}", file=sys.stderr)
         sys.exit(1)
-    normalized = args.renode_version.lstrip("v")
-    docker_image = f"antmicro/renode:{normalized}"
+    _, docker_image = resolve_renode_image({}, args)
     resc_root = os.path.join(ARTIFACTS_DIR, "resc")
     os.makedirs(resc_root, exist_ok=True)
     # No .hector.yaml here, so debug machine names come straight from --debug.
@@ -256,6 +280,81 @@ def _run_validate():
     sys.exit(0)
 
 
+# ---------------------------------------------------------------------------
+# clean
+# ---------------------------------------------------------------------------
+
+# The Renode source / verilator-integration checkouts hector clones on demand. They
+# live under .hector/ but are expensive to re-fetch (~200 MB), so `clean` keeps them
+# unless --all is given.
+_RENODE_CHECKOUTS = ("renode", "renode-verilator-integration")
+
+
+def clean_targets(output_dir="results", include_renode=False):
+    """The generated paths `hector clean` would remove, filtered to those that exist.
+
+    Always: the cheap build artifacts (.hector/resc, .hector/repl, .hector/tests) and
+    the results/output directory. Only with include_renode: the whole .hector/ (which
+    also takes the expensive Renode checkouts with it). Paths are relative to the cwd."""
+    if include_renode:
+        targets = [ARTIFACTS_DIR, output_dir]
+    else:
+        targets = [os.path.join(ARTIFACTS_DIR, d) for d in ("resc", "repl", "tests")]
+        targets.append(output_dir)
+    # De-dupe while preserving order, keep only what's actually there.
+    seen, existing = set(), []
+    for p in targets:
+        if p not in seen and os.path.exists(p):
+            seen.add(p)
+            existing.append(p)
+    return existing
+
+
+def _is_within_cwd(path):
+    """True if `path` resolves inside the project root — the guard that stops `clean`
+    from ever deleting something outside the workspace (e.g. an absolute --output)."""
+    root = os.path.realpath(os.getcwd())
+    real = os.path.realpath(path)
+    return real == root or real.startswith(root + os.sep)
+
+
+def run_clean(output_dir="results", include_renode=False, dry_run=False):
+    """Remove hector's generated artifacts. Returns a process exit code."""
+    import shutil
+
+    targets = clean_targets(output_dir, include_renode)
+    if not targets:
+        print("[CLEAN] Nothing to remove — the workspace is already clean.")
+        return 0
+
+    removed = 0
+    for path in targets:
+        if not _is_within_cwd(path):
+            print(f"[CLEAN] SKIP {path} — outside the project directory; refusing to remove it.")
+            continue
+        kind = "dir " if os.path.isdir(path) else "file"
+        if dry_run:
+            print(f"[CLEAN] would remove {kind} {path}")
+            continue
+        if os.path.isdir(path):
+            shutil.rmtree(path, ignore_errors=True)
+        else:
+            os.remove(path)
+        print(f"[CLEAN] removed {kind} {path}")
+        removed += 1
+
+    if dry_run:
+        print("[CLEAN] dry run — nothing was deleted.")
+    elif not include_renode and os.path.isdir(ARTIFACTS_DIR):
+        # We kept a Renode checkout; tell the user how to drop it too.
+        kept = [d for d in _RENODE_CHECKOUTS
+                if os.path.isdir(os.path.join(ARTIFACTS_DIR, d))]
+        if kept:
+            print(f"[CLEAN] kept cached Renode checkout(s) in {ARTIFACTS_DIR}/ "
+                  f"({', '.join(kept)}) — use 'hector clean --all' to remove them too.")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------

{hector_cli-0.3.0 → hector_cli-0.4.0}/hector/scaffold.py

@@ -46,7 +46,7 @@ def scaffold_init(target=".hector.yaml"):
     name .hector.yaml; override via -f/--file)."""
     if os.path.exists(target):
         print(f"[INIT] {target} already exists — not overwriting.")
-        print(f"[INIT] Delete or rename it, then run 'hector init' again.")
+        print("[INIT] Delete or rename it, then run 'hector init' again.")
         sys.exit(1)
 
     print("Hector project initialisation")

{hector_cli-0.3.0 → hector_cli-0.4.0}/hector/validator.py

@@ -10,7 +10,6 @@ Usage:
     for w in warnings: print(f"  WARNING {w.path}: {w.message}")
 """
 
-import re
 from dataclasses import dataclass
 from typing import List, Tuple
 
@@ -20,12 +19,19 @@ from .mappings import MAPPING_BACKENDS
 from .modules import MODULE_KINDS
 from .runners import TEST_RUNNERS
 
+# CI trigger / run-control keys. The whole .hector.yaml is a single pipeline (there is
+# no nested `ci:` block). These belong entirely to the CI server — the CLI's run/test/
+# export never read them and it must not act on them. They are listed here only so the
+# CLI accepts them silently instead of flagging them; the CI backend is their sole
+# validator (see ci/backend/hectorci/config.py).
+_TRIGGER_TOP_KEYS = {"when", "cron", "reporters", "jobs", "fail_fast", "timeout"}
+
 # Top-level keys defined by this schema version; anything else is flagged.
 _KNOWN_TOP_KEYS = {
-    "version", "renode_version", "arguments", "matrix",
+    "version", "renode_version", "renode_image", "arguments", "matrix",
     "modules", "hubs", "machines", "connections", "mappings", "build", "tests", "quantum",
-    "artifacts", "ci",
-}
+    "artifacts",
+} | _TRIGGER_TOP_KEYS
 
 # Keys renamed in this schema version → new name (for a helpful migration hint).
 _RENAMED_TOP_KEYS = {"nodes": "machines", "setup": "build", "prepare": "build"}
@@ -33,12 +39,6 @@ _RENAMED_TOP_KEYS = {"nodes": "machines", "setup": "build", "prepare": "build"}
 # Test types renamed this schema version → current name (old configs still run).
 _RENAMED_TEST_TYPES = {"bash": "shell", "docker": "shell"}
 
-# CI pipeline schema (top-level `ci:` block — when/how the CI server runs this config).
-_CI_EVENTS = {"push", "pull_request", "tag", "manual", "cron"}
-_CI_PIPELINE_KEYS = {"when", "arguments", "jobs", "reporters", "fail_fast", "timeout", "cron"}
-_CI_WHEN_KEYS = {"branch", "event", "path"}
-_CI_TIMEOUT_RE = re.compile(r"^\d+[smh]$")
-
 _KNOWN_NODE_KEYS = {
     "backend", "platform", "repl", "resc", "firmware",
     "peripherals", "init", "connections", "mappings", "commands",
@@ -80,12 +80,16 @@ def validate_config(config) -> Tuple[List[Issue], List[Issue]]:
                  f"({', '.join(sorted(SUPPORTED_SCHEMA_VERSIONS))}). "
                  "Some fields may not be recognised.")
 
-    # ---- renode_version (required) ----
+    # ---- renode_version / renode_image (one of them required) ----
     rv = config.get("renode_version")
-    if not rv:
-        err("renode_version", "Required field missing (e.g. '1.16.1').")
-    elif not isinstance(rv, (str, int, float)):
+    ri = config.get("renode_image")
+    if not rv and not ri:
+        err("renode_version", "Required field missing (e.g. '1.16.1') — or set "
+            "'renode_image' to use a specific Docker image.")
+    if rv and not isinstance(rv, (str, int, float)):
         err("renode_version", f"Must be a string like '1.16.1', got {type(rv).__name__}.")
+    if ri and not isinstance(ri, str):
+        err("renode_image", f"Must be a string like 'my-renode:dev', got {type(ri).__name__}.")
 
     # ---- unknown / renamed top-level keys ----
     for k in config:
@@ -291,8 +295,8 @@ def validate_config(config) -> Tuple[List[Issue], List[Issue]]:
         except (TypeError, ValueError):
             err("quantum", f"Must be a positive number (seconds), got '{quantum}'.")
 
-    # ---- ci (CI pipelines) ----
-    _validate_ci(config.get("ci"), err, warn)
+    # ---- CI triggers (when/cron/…) are accepted but never validated or acted on
+    #      here; they belong to the CI server. See _TRIGGER_TOP_KEYS. ----
 
     return errors, warnings
 
@@ -328,71 +332,6 @@ def _validate_shell_steps(item, p, err, warn):
             warn(p, "Both 'file' and 'script' — 'file' takes precedence.")
 
 
-def _validate_ci(ci_cfg, err, warn):
-    """Validate the top-level `ci:` block (pipeline-name -> CI settings)."""
-    if ci_cfg is None:
-        return
-    if not isinstance(ci_cfg, dict):
-        err("ci", f"Must be a mapping of pipeline-name: settings, got {type(ci_cfg).__name__}.")
-        return
-    for name, pipe in ci_cfg.items():
-        p = f"ci.{name}"
-        if not isinstance(pipe, dict):
-            err(p, f"Pipeline must be a mapping, got {type(pipe).__name__}."); continue
-        for k in pipe:
-            if k not in _CI_PIPELINE_KEYS:
-                warn(f"{p}.{k}", f"Unknown pipeline key '{k}'. "
-                     f"Known keys: {', '.join(sorted(_CI_PIPELINE_KEYS))}.")
-
-        # when: { branch, event, path }
-        when = pipe.get("when")
-        events = []
-        if when is not None:
-            if not isinstance(when, dict):
-                err(f"{p}.when", f"Must be a mapping, got {type(when).__name__}.")
-            else:
-                for k in when:
-                    if k not in _CI_WHEN_KEYS:
-                        warn(f"{p}.when.{k}", f"Unknown 'when' key '{k}'.")
-                raw_event = when.get("event")
-                if raw_event is None:
-                    events = []
-                elif not isinstance(raw_event, list):
-                    err(f"{p}.when.event", f"Must be a list, got {type(raw_event).__name__}.")
-                    events = []
-                else:
-                    events = raw_event
-                for ev in events:
-                    if not isinstance(ev, str) or ev not in _CI_EVENTS:
-                        err(f"{p}.when.event", f"Unknown event {ev!r}. "
-                            f"Allowed: {', '.join(sorted(_CI_EVENTS))}.")
-
-        # jobs / fail_fast
-        jobs = pipe.get("jobs")
-        if jobs is not None and (not isinstance(jobs, int) or isinstance(jobs, bool) or jobs < 1):
-            err(f"{p}.jobs", f"Must be a positive integer, got {jobs!r}.")
-        if pipe.get("fail_fast") is True and (jobs or 1) != 1:
-            err(f"{p}.fail_fast", "Only valid with jobs: 1.")
-
-        # cron (required iff event includes 'cron')
-        has_cron_event = "cron" in events
-        if has_cron_event and not isinstance(pipe.get("cron"), str):
-            err(f"{p}.cron", "A cron expression is required when event includes 'cron'.")
-        if isinstance(pipe.get("cron"), str) and not has_cron_event:
-            warn(f"{p}.cron", "cron is set but when.event does not include 'cron'.")
-
-        # timeout / reporters / arguments
-        timeout = pipe.get("timeout")
-        if timeout is not None and (not isinstance(timeout, str) or not _CI_TIMEOUT_RE.match(timeout)):
-            err(f"{p}.timeout", "Must look like '30m', '90s' or '2h'.")
-        reporters = pipe.get("reporters")
-        if reporters is not None and not isinstance(reporters, list):
-            err(f"{p}.reporters", f"Must be a list, got {type(reporters).__name__}.")
-        arguments = pipe.get("arguments")
-        if arguments is not None and not isinstance(arguments, dict):
-            err(f"{p}.arguments", f"Must be a mapping of name: value, got {type(arguments).__name__}.")
-
-
 def _validate_connection_lines(section, path, err, warn):
     for line in as_lines(section):
         if "->" not in line and "<->" not in line: