embedagents-stm32 0.3.0__py3-none-any.whl

embedagents/stm32/__init__.py

@@ -0,0 +1,15 @@
+"""STM32 substrate — deterministic Python wrapper around ST's vendor CLIs.
+
+``__version__`` is derived from the installed package metadata so it can never
+drift from ``pyproject.toml``. In a bare source checkout (package not installed)
+it falls back to a sentinel.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("embedagents-stm32")
+except PackageNotFoundError:  # source checkout, not installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

embedagents/stm32/_jsonc.py

@@ -0,0 +1,141 @@
+"""Minimal JSONC loader (strip ``//`` + ``/* ... */`` comments, accept trailing commas).
+
+Substrate uses JSONC for human-edited config files per SC-005. The stdlib
+``json`` module does not accept comments, so we strip them in a single pass
+that is aware of string literals (a ``"// not a comment"`` string is
+preserved untouched).
+
+Public surface:
+    ``load_jsonc(text)`` — parse a JSONC string and return the value.
+    ``load_jsonc_file(path)`` — read + parse a JSONC file.
+
+The stripper handles the common cases used by ST-tooling configs:
+
+- ``//`` line comments
+- ``/* ... */`` block comments (single-line and multi-line)
+- trailing commas immediately before ``}`` or ``]``
+- string escapes (``\\"``) inside strings
+
+It is intentionally not a full JSON5 parser. For v1, simpler is better
+(M-018). If users want JSON5 features (unquoted keys, single quotes,
+hex numbers), the substrate raises a clean parse error pointing at the
+offending position.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_jsonc(text: str) -> Any:
+    """Parse a JSONC string and return the decoded value."""
+    return json.loads(_strip(text))
+
+
+def load_jsonc_file(path: Path) -> Any:
+    """Read + parse a JSONC file."""
+    return load_jsonc(path.read_text(encoding="utf-8"))
+
+
+# ---------------------------------------------------------------------------
+# Stripper
+# ---------------------------------------------------------------------------
+
+
+def _strip(text: str) -> str:
+    """Return ``text`` with comments and trailing commas removed.
+
+    State machine over characters: outside strings, ``//`` starts a line
+    comment and ``/*`` starts a block comment. Inside strings (including
+    escapes), everything is preserved verbatim.
+    """
+    out: list[str] = []
+    i = 0
+    n = len(text)
+    in_string = False
+    while i < n:
+        ch = text[i]
+
+        if in_string:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 2
+                continue
+            if ch == '"':
+                in_string = False
+            i += 1
+            continue
+
+        if ch == '"':
+            in_string = True
+            out.append(ch)
+            i += 1
+            continue
+
+        if ch == "/" and i + 1 < n:
+            nxt = text[i + 1]
+            if nxt == "/":
+                # Line comment — skip to end of line (preserve the newline so
+                # error positions stay aligned with the source).
+                j = text.find("\n", i + 2)
+                i = n if j == -1 else j
+                continue
+            if nxt == "*":
+                # Block comment — skip to matching ``*/``.
+                end = text.find("*/", i + 2)
+                if end == -1:
+                    # Unterminated; let json.loads surface the resulting
+                    # error at this column.
+                    i = n
+                else:
+                    i = end + 2
+                continue
+
+        out.append(ch)
+        i += 1
+
+    return _strip_trailing_commas("".join(out))
+
+
+def _strip_trailing_commas(text: str) -> str:
+    """Remove commas that immediately precede ``}`` or ``]`` (ignoring whitespace).
+
+    Same string-aware state machine, in reverse-look style: emit characters
+    one at a time, but defer emitting a comma until we see what's next.
+    """
+    out: list[str] = []
+    i = 0
+    n = len(text)
+    in_string = False
+    while i < n:
+        ch = text[i]
+        if in_string:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 2
+                continue
+            if ch == '"':
+                in_string = False
+            i += 1
+            continue
+        if ch == '"':
+            in_string = True
+            out.append(ch)
+            i += 1
+            continue
+        if ch == ",":
+            # Look ahead past whitespace; if next non-space is `}` or `]`,
+            # drop the comma.
+            j = i + 1
+            while j < n and text[j].isspace():
+                j += 1
+            if j < n and text[j] in "}]":
+                i += 1
+                continue
+        out.append(ch)
+        i += 1
+    return "".join(out)

embedagents/stm32/cli/__init__.py

@@ -0,0 +1,125 @@
+"""Top-level ``stm32`` CLI entry point.
+
+Aggregates five per-tool subparser groups — ``prog`` (cubeprogrammer +
+signing per ADR-002 §M1), ``build`` (cubeide), ``mx`` (cubemx), ``debug``
+(gdbserver + arm-gdb), ``vcp`` (USB virtual COM) — and routes parsed args
+to each group's ``dispatch``.
+
+Per ``v1/api-conventions.md`` § "Logging and progress streaming", the
+library does NOT configure logging handlers — the CLI does. ``main()``
+installs a stderr handler with a structured-field formatter, scoped to
+the ``embedagents.stm32`` root logger.
+
+TODO(v1+): ``--project`` / ``--tools-config`` / ``--defaults-config``
+overrides plumbed into ``SubstrateContext.from_environment``; current Pass-1
+surface uses repo-walked discovery only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from embedagents.stm32 import __version__
+from embedagents.stm32.cli import _build, _debug, _mx, _prog, _vcp
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="stm32",
+        description=(
+            "STM32 substrate CLI — wraps STM32_Programmer_CLI / CubeIDE / "
+            "CubeMX / ST-LINK_gdbserver / arm-none-eabi-gdb / "
+            "STM32_SigningTool_CLI behind a unified surface."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"embedagents-stm32 {__version__}",
+    )
+    parser.add_argument(
+        "--pretty",
+        action="store_true",
+        help="pretty-print JSON output (default: compact)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="increase log verbosity (-v INFO, -vv DEBUG)",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        metavar="<group>",
+    )
+    _prog.add_subparser(subparsers)
+    _build.add_subparser(subparsers)
+    _mx.add_subparser(subparsers)
+    _debug.add_subparser(subparsers)
+    _vcp.add_subparser(subparsers)
+
+    if argv is None:
+        argv = sys.argv[1:]
+    # `stm32 build PATH` ergonomics: route a leading non-action positional
+    # into --project before argparse sees the build subtree. The global
+    # flags (--pretty, -v) never consume a value, so the first non-flag
+    # token is always the command.
+    for i, token in enumerate(argv):
+        if not token.startswith("-"):
+            if token == "build":
+                argv = [*argv[: i + 1], *_build.pre_parse_argv(argv[i + 1 :])]
+            break
+
+    args = parser.parse_args(argv)
+    _configure_logging(args.verbose)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+    if args.command == "prog":
+        return _prog.dispatch(args)
+    if args.command == "build":
+        return _build.dispatch(args)
+    if args.command == "mx":
+        return _mx.dispatch(args)
+    if args.command == "debug":
+        return _debug.dispatch(args)
+    if args.command == "vcp":
+        return _vcp.dispatch(args)
+
+    # argparse should reject unknown commands before reaching this
+    # branch — defensive only.
+    parser.error(f"unknown command {args.command!r}")
+    return 2  # unreachable; argparse.error raises SystemExit
+
+
+def _configure_logging(verbosity: int) -> None:
+    """Attach a stderr handler to the substrate root logger.
+
+    ``-v`` → INFO; ``-vv`` → DEBUG; default → WARNING.
+    """
+    level = logging.WARNING
+    if verbosity == 1:
+        level = logging.INFO
+    elif verbosity >= 2:
+        level = logging.DEBUG
+
+    root = logging.getLogger("embedagents.stm32")
+    # Don't double-install when ``main()`` is called multiple times in
+    # the same Python process (e.g. tests).
+    if not any(getattr(h, "_substrate_installed", False) for h in root.handlers):
+        handler = logging.StreamHandler(stream=sys.stderr)
+        handler.setFormatter(
+            logging.Formatter("%(levelname)s %(name)s: %(message)s")
+        )
+        handler._substrate_installed = True  # type: ignore[attr-defined]
+        root.addHandler(handler)
+    root.setLevel(level)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

embedagents/stm32/cli/_build.py

@@ -0,0 +1,300 @@
+"""``stm32 build`` CLI subcommand group — cubeide-side operations.
+
+Maps to ``v1/cubeide-api.md`` § "CLI subcommand surface". The base
+``stm32 build`` accepts all simple flags (project / config / clean /
+debug-level / opt / preset / all-configs); action sub-subcommands
+(``add-symbol`` / ``add-lib`` / ``add-source`` / ``add-include``) handle
+the list-shaped edits; discovery sub-subcommands (``in-folder`` /
+``named``) chain ``find_project`` + ``build``.
+
+Output:
+
+- Successful build (success=True) → exit 0 with ``BuildResult`` JSON on
+  stdout. ``console_output`` mirrored to stderr so users see the build
+  log in their terminal.
+- **Build-level failure** (compile / link errors → ``success=False``) →
+  **exit 0**: build failure is a result the user scripts check via
+  ``BuildResult.success``. console_output still mirrored.
+- Substrate-side failure (``CubeIDEError`` / ``WorkspaceLockedError`` /
+  ``CProjectEditError``) → exit 1 with the error JSON on stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from embedagents.stm32.cli._serialize import (
+    dumps,
+    serialise_error,
+    serialise_unexpected,
+)
+from embedagents.stm32.context import SubstrateContext
+from embedagents.stm32.cubeide import CubeIDE
+from embedagents.stm32.errors import SubstrateError
+
+
+# ---------------------------------------------------------------------------
+# Public entry points
+# ---------------------------------------------------------------------------
+
+
+_BUILD_ACTIONS = frozenset({
+    "add-symbol", "add-lib", "add-source",
+    "add-include", "in-folder", "named",
+})
+
+
+def pre_parse_argv(argv: list[str]) -> list[str]:
+    """Rewrite ``stm32 build PATH ...`` → ``stm32 build --project PATH ...``.
+
+    If the first positional token after ``build`` is not a known action
+    keyword and not a flag, treat it as a project path and route it
+    through ``--project``. Leaves everything else untouched.
+
+    Caveat: a path whose final component literally matches an action
+    keyword (a folder called ``named``, say) dispatches as that action —
+    action names win, matching the pre-existing parser behavior.
+    """
+    # argv at this point starts at the token after "build".
+    if not argv:
+        return argv
+    first = argv[0]
+    if first.startswith("-"):
+        return argv
+    if first in _BUILD_ACTIONS:
+        return argv
+    # Treat as project path.
+    return ["--project", first, *argv[1:]]
+
+
+def add_subparser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``build`` group on the top-level parser."""
+    parser = subparsers.add_parser(
+        "build",
+        help="STM32CubeIDE headless build (B-* prompts).",
+    )
+    _add_common_flags(parser, include_edit_flags=True)
+    parser.set_defaults(build_fn=_cmd_base_build)
+
+    sub = parser.add_subparsers(
+        dest="build_action",
+        required=False,
+        metavar="<action>",
+    )
+
+    # ---- add-symbol ----
+    p = sub.add_parser(
+        "add-symbol",
+        help="B-011 — append preprocessor symbols (one or more NAME[=VALUE]).",
+    )
+    p.add_argument("symbols", nargs="+", help="NAME or NAME=VALUE")
+    _add_common_flags(p, include_edit_flags=False)
+    p.set_defaults(build_fn=_cmd_add_symbol)
+
+    # ---- add-lib ----
+    p = sub.add_parser(
+        "add-lib",
+        help="B-012 — append linker libraries (paths).",
+    )
+    p.add_argument("libs", nargs="+", type=Path)
+    _add_common_flags(p, include_edit_flags=False)
+    p.set_defaults(build_fn=_cmd_add_lib)
+
+    # ---- add-source ----
+    p = sub.add_parser(
+        "add-source",
+        help="B-013 — append source files. v1 records only (tracks aux).",
+    )
+    p.add_argument("sources", nargs="+", type=Path)
+    p.add_argument(
+        "--target",
+        type=Path,
+        default=None,
+        help="optional target directory to copy each source into (paired tuple)",
+    )
+    _add_common_flags(p, include_edit_flags=False)
+    p.set_defaults(build_fn=_cmd_add_source)
+
+    # ---- add-include ----
+    p = sub.add_parser(
+        "add-include",
+        help="B-014 — append compiler include paths.",
+    )
+    p.add_argument("includes", nargs="+")
+    _add_common_flags(p, include_edit_flags=False)
+    p.set_defaults(build_fn=_cmd_add_include)
+
+    # ---- in-folder ----
+    p = sub.add_parser(
+        "in-folder",
+        help="B-018 — discover a project under FOLDER (one match) then build.",
+    )
+    p.add_argument(
+        "folder",
+        nargs="?",
+        default=None,
+        type=Path,
+        help="defaults to ctx.cwd",
+    )
+    p.add_argument("--config", default=None)
+    p.add_argument("--clean", action="store_true")
+    p.set_defaults(build_fn=_cmd_in_folder)
+
+    # ---- named ----
+    p = sub.add_parser(
+        "named",
+        help="B-019 — discover by name (exact > substring) then build.",
+    )
+    p.add_argument("name")
+    p.add_argument("--folder", type=Path, default=None)
+    p.add_argument("--config", default=None)
+    p.add_argument("--clean", action="store_true")
+    p.set_defaults(build_fn=_cmd_named)
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    """Run the parsed build subcommand. Returns the process exit code.
+
+    Build-level failures (``success=False``) exit 0 — the user inspects
+    the JSON. Substrate-side failures exit 1 with error JSON on stderr.
+    """
+    handler = args.build_fn
+    try:
+        ctx = SubstrateContext.from_environment()
+        client = CubeIDE(ctx)
+    except SubstrateError as err:
+        sys.stderr.write(serialise_error(err) + "\n")
+        return 1
+    except Exception as err:  # CLI boundary: never leak a raw traceback (HARD RULE 1)
+        sys.stderr.write(serialise_unexpected(err) + "\n")
+        return 2
+
+    try:
+        result = handler(args, client)
+    except SubstrateError as err:
+        sys.stderr.write(serialise_error(err) + "\n")
+        return 1
+    except Exception as err:  # CLI boundary: never leak a raw traceback (HARD RULE 1)
+        sys.stderr.write(serialise_unexpected(err) + "\n")
+        return 2
+
+    # BuildResult.console_output also goes to stderr so the user sees the
+    # build log without parsing the JSON envelope.
+    if getattr(result, "console_output", None):
+        sys.stderr.write(result.console_output)
+        if not result.console_output.endswith("\n"):
+            sys.stderr.write("\n")
+
+    sys.stdout.write(dumps(result, pretty=getattr(args, "pretty", False)) + "\n")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Shared flag helper
+# ---------------------------------------------------------------------------
+
+
+def _add_common_flags(parser: argparse.ArgumentParser, *, include_edit_flags: bool) -> None:
+    parser.add_argument("--project", type=Path, default=None)
+    parser.add_argument("--config", default=None, help="CDT configuration name (e.g. Debug)")
+    parser.add_argument("--clean", action="store_true")
+    parser.add_argument(
+        "--all-configs",
+        action="store_true",
+        help="apply settings edits to every configuration (not just active)",
+    )
+    if include_edit_flags:
+        parser.add_argument("--debug-level", default=None, dest="debug_level")
+        parser.add_argument("--opt", default=None, dest="optimization")
+        parser.add_argument("--preset", default=None, help="fast / size / balanced")
+
+
+def _common_kwargs(args: argparse.Namespace) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {
+        "project": getattr(args, "project", None),
+        "configuration": getattr(args, "config", None),
+        "clean": getattr(args, "clean", False),
+    }
+    if getattr(args, "all_configs", False):
+        kwargs["modify_all_configurations"] = True
+    return kwargs
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def _cmd_base_build(args: argparse.Namespace, client: CubeIDE) -> Any:
+    """``stm32 build`` (no sub-subcommand) — base build with simple flags."""
+    kwargs = _common_kwargs(args)
+    kwargs["debug_level"] = getattr(args, "debug_level", None)
+    kwargs["optimization"] = getattr(args, "optimization", None)
+    kwargs["preset"] = getattr(args, "preset", None)
+    return client.build(**kwargs)
+
+
+def _cmd_add_symbol(args: argparse.Namespace, client: CubeIDE) -> Any:
+    parsed = [_parse_symbol(s) for s in args.symbols]
+    kwargs = _common_kwargs(args)
+    kwargs["add_symbols"] = parsed
+    return client.build(**kwargs)
+
+
+def _cmd_add_lib(args: argparse.Namespace, client: CubeIDE) -> Any:
+    kwargs = _common_kwargs(args)
+    kwargs["add_libraries"] = list(args.libs)
+    return client.build(**kwargs)
+
+
+def _cmd_add_source(args: argparse.Namespace, client: CubeIDE) -> Any:
+    sources: list = list(args.sources)
+    if args.target is not None:
+        sources = [(p, args.target) for p in sources]
+    kwargs = _common_kwargs(args)
+    kwargs["add_sources"] = sources
+    return client.build(**kwargs)
+
+
+def _cmd_add_include(args: argparse.Namespace, client: CubeIDE) -> Any:
+    kwargs = _common_kwargs(args)
+    kwargs["add_include_paths"] = list(args.includes)
+    return client.build(**kwargs)
+
+
+def _cmd_in_folder(args: argparse.Namespace, client: CubeIDE) -> Any:
+    found = client.find_project(folder=args.folder)
+    return client.build(
+        project=found.path,
+        configuration=args.config,
+        clean=args.clean,
+    )
+
+
+def _cmd_named(args: argparse.Namespace, client: CubeIDE) -> Any:
+    found = client.find_project(folder=args.folder, name=args.name)
+    return client.build(
+        project=found.path,
+        configuration=args.config,
+        clean=args.clean,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_symbol(s: str) -> str | tuple[str, str]:
+    """Parse ``NAME`` or ``NAME=VALUE`` for ``add-symbol``."""
+    if "=" not in s:
+        return s
+    name, _, value = s.partition("=")
+    if not name:
+        raise argparse.ArgumentTypeError(
+            f"add-symbol expects NAME or NAME=VALUE, got {s!r}"
+        )
+    return (name, value)