fenolite 0.0.1.dev0__py3-none-any.whl

fenolite/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""Fenolite: headless, agent-first PCB design automation (KiCad first, Altium second)."""
+
+__version__ = "0.0.1.dev0"
+
+__all__ = ["__version__"]

fenolite/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""Allow ``python -m fenolite``; behaves exactly like the ``fenolite`` console script."""
+
+from fenolite.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fenolite/cli/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""Command-line interface of Fenolite."""

fenolite/cli/api.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""What a command module provides, what it receives and what it returns.
+
+A command lives in ``fenolite/cli/cmd_<name>.py`` (dashes become underscores) and exposes a
+module-level ``COMMAND`` (:class:`Command`). Commands never write files themselves: they return
+:class:`PlannedWrite` objects and the dispatcher applies the mutation protocol
+(``--dry-run`` / ``--confirm``, atomic writes, backups, receipts).
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import pkgutil
+import random
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from fenolite.cli.output import Evidence, InputRef, Issue, OutputMode
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    """Everything a command may depend on besides its own arguments."""
+
+    mode: OutputMode
+    seed: int | None
+    timestamp: datetime
+    rng: random.Random
+    no_backup: bool
+    cwd: Path
+
+
+@dataclass(frozen=True, slots=True)
+class PlannedWrite:
+    """A file a mutating command wants to write. ``path`` is relative to the working directory."""
+
+    path: str
+    data: bytes
+    kind: str
+
+
+@dataclass(frozen=True, slots=True)
+class Result:
+    """What a command returns to the dispatcher."""
+
+    result: dict[str, Any] = field(default_factory=lambda: {})
+    issues: tuple[Issue, ...] = ()
+    evidence: Evidence = Evidence()
+    input: InputRef | None = None
+    writes: tuple[PlannedWrite, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """A registered sub-command. ``help=None`` hides it from ``--help``."""
+
+    name: str
+    help: str | None
+    mutates: bool
+    register: Callable[[argparse.ArgumentParser], None]
+    run: Callable[[argparse.Namespace, Context], Result]
+    example_args: tuple[str, ...] = ()
+    mutation_example_args: tuple[str, ...] | None = None
+
+    @property
+    def hidden(self) -> bool:
+        return self.help is None
+
+    @property
+    def schema(self) -> str:
+        return f"fenolite.{self.name}.v0"
+
+
+def module_name_for(command_name: str) -> str:
+    return "cmd_" + command_name.replace("-", "_")
+
+
+def discover() -> dict[str, Command]:
+    """Import every ``fenolite.cli.cmd_*`` module and return its ``COMMAND`` keyed by name."""
+    import fenolite.cli as package
+
+    found: dict[str, Command] = {}
+    for info in sorted(pkgutil.iter_modules(package.__path__), key=lambda m: m.name):
+        if not info.name.startswith("cmd_"):
+            continue
+        module = importlib.import_module(f"{package.__name__}.{info.name}")
+        command = getattr(module, "COMMAND", None)
+        if not isinstance(command, Command):
+            raise TypeError(f"{module.__name__} does not define COMMAND as fenolite.cli.api.Command")
+        if module_name_for(command.name) != info.name:
+            raise ValueError(f"{module.__name__} declares command {command.name!r}; module name must match")
+        found[command.name] = command
+    return found
+
+
+__all__ = ["Command", "Context", "PlannedWrite", "Result", "discover", "module_name_for"]

fenolite/cli/cmd__echo.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""Hidden ``_echo`` command: exercises every branch of the CLI contract for the consistency tests."""
+
+from __future__ import annotations
+
+import argparse
+import uuid
+from typing import Any
+
+from fenolite.cli.api import Command, Context, PlannedWrite, Result
+from fenolite.cli.output import Issue
+
+
+def _register(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--issue", action="append", choices=["error", "warning", "info"], default=[],
+                        help="emit an issue of this severity (repeatable)")  # fmt: skip
+    parser.add_argument("--raise", dest="raise_", action="store_true", help="raise an internal exception")
+    parser.add_argument("--write", metavar="PATH", help="plan a write of --content to PATH")
+    parser.add_argument("--content", default="echo\n", help="content for --write")
+    parser.add_argument("--gen-id", action="store_true", help="generate an id and a timestamp")
+
+
+def _run(args: argparse.Namespace, ctx: Context) -> Result:
+    if args.raise_:
+        raise RuntimeError("requested failure (--raise)")
+    severities: list[str] = args.issue
+    issues = tuple(
+        Issue(code=f"echo.{sev}", severity=sev, message=f"requested {sev} issue", where="_echo")  # type: ignore[arg-type]
+        for sev in severities
+    )
+    result: dict[str, Any] = {"echo": {"issues": severities, "write": args.write}}
+    if args.gen_id:
+        result["id"] = str(uuid.UUID(int=ctx.rng.getrandbits(128), version=4))
+        result["timestamp"] = ctx.timestamp.isoformat()
+    writes: tuple[PlannedWrite, ...] = ()
+    if args.write:
+        writes = (PlannedWrite(path=args.write, data=str(args.content).encode("utf-8"), kind="text"),)
+    return Result(result=result, issues=issues, writes=writes)
+
+
+COMMAND = Command(
+    name="_echo",
+    help=None,
+    mutates=True,
+    register=_register,
+    run=_run,
+    example_args=(),
+    mutation_example_args=("--write", "echo.txt"),
+)

fenolite/cli/cmd_capabilities.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""``fenolite capabilities``: what this installation can do. Agents should call it first."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+import os
+import re
+import shutil
+import subprocess
+from functools import cache
+from pathlib import Path
+from typing import Any
+
+from fenolite import __version__
+from fenolite.cli.api import Command, Context, Result, discover
+
+_MACOS_KICAD_CLI = "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
+_EXTRA_MARKER = re.compile(r"extra\s*==\s*['\"]([^'\"]+)['\"]")
+_DIST_NAME = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)")
+
+
+def _extras() -> dict[str, dict[str, Any]]:
+    """Each optional extra of the installed distribution and whether its packages are installed."""
+    try:
+        requires = importlib.metadata.metadata("fenolite").get_all("Requires-Dist") or []
+    except importlib.metadata.PackageNotFoundError:
+        return {}
+    wanted: dict[str, list[str]] = {}
+    for requirement in requires:
+        extra = _EXTRA_MARKER.search(requirement)
+        name = _DIST_NAME.match(requirement)
+        if extra and name:
+            wanted.setdefault(extra.group(1), []).append(name.group(1))
+    report: dict[str, dict[str, Any]] = {}
+    for extra, dists in sorted(wanted.items()):
+        missing: list[str] = []
+        for dist in sorted(dists):
+            try:
+                importlib.metadata.version(dist)
+            except importlib.metadata.PackageNotFoundError:
+                missing.append(dist)
+        report[extra] = {"installed": not missing, "missing": missing}
+    return report
+
+
+def _run_version(argv: list[str]) -> str | None:
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, timeout=15, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if proc.returncode != 0:
+        return None
+    text = (proc.stdout or proc.stderr).strip()
+    return text.splitlines()[0].strip() if text else None
+
+
+def _kicad_cli_path() -> str | None:
+    override = os.environ.get("FENOLITE_KICAD_CLI")
+    if override:
+        return override if Path(override).is_file() else None
+    found = shutil.which("kicad-cli")
+    if found:
+        return found
+    return _MACOS_KICAD_CLI if Path(_MACOS_KICAD_CLI).is_file() else None
+
+
+@cache
+def detect_tools() -> dict[str, dict[str, str] | None]:
+    """External tools Fenolite can drive, with their version, or ``None`` when absent or unusable."""
+    tools: dict[str, dict[str, str] | None] = {}
+    probes: dict[str, tuple[str | None, list[str]]] = {
+        "kicad-cli": (_kicad_cli_path(), ["version"]),
+        "java": (shutil.which("java"), ["-version"]),
+        "docker": (shutil.which("docker"), ["--version"]),
+    }
+    for name, (path, version_args) in probes.items():
+        version = _run_version([path, *version_args]) if path else None
+        tools[name] = {"path": path, "version": version} if path and version else None
+    return tools
+
+
+def _register(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--no-tools", action="store_true", help="skip external tool detection")
+
+
+def _run(args: argparse.Namespace, ctx: Context) -> Result:
+    commands = [
+        {"name": c.name, "mutates": c.mutates, "schema": c.schema, "hidden": c.hidden}
+        for c in sorted(discover().values(), key=lambda c: c.name)
+    ]
+    result: dict[str, Any] = {
+        "fenolite_version": __version__,
+        "commands": commands,
+        "backends": [],
+        "extras": _extras(),
+        "tools": {} if args.no_tools else detect_tools(),
+        "sends_data_offsite": False,
+    }
+    return Result(result=result)
+
+
+COMMAND = Command(
+    name="capabilities",
+    help="list commands, backends, extras and external tools available here",
+    mutates=False,
+    register=_register,
+    run=_run,
+    example_args=("--no-tools",),
+)

fenolite/cli/errors.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""Typed CLI errors: the ``FEN-NNNN`` registry, the stderr error object and :class:`CliError`."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from fenolite.cli.exitcodes import ExitCode
+
+ERROR_CODE = re.compile(r"^FEN-[1-7][0-9]{3}$")
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorSpec:
+    """Registry entry for one error code."""
+
+    code: str
+    exit_code: ExitCode
+    message: str
+    hint: str
+    retryable: bool = False
+
+
+_SPECS = (
+    ErrorSpec(
+        "FEN-1001", ExitCode.INTERNAL, "internal error", "this is a bug; report it with the command line"
+    ),
+    ErrorSpec("FEN-2001", ExitCode.USAGE, "invalid command line", "run 'fenolite --help'"),
+    ErrorSpec(
+        "FEN-2002", ExitCode.USAGE, "unknown field in --fields", "list the result keys with --json first"
+    ),
+    ErrorSpec(
+        "FEN-2003", ExitCode.USAGE, "--dry-run and --confirm are mutually exclusive", "use one of them"
+    ),
+    ErrorSpec("FEN-2004", ExitCode.USAGE, "invalid --timestamp", "use ISO 8601, e.g. 2026-01-01T00:00:00Z"),
+    ErrorSpec(
+        "FEN-3001", ExitCode.INPUT, "input file missing or unreadable", "check the path and permissions"
+    ),
+    ErrorSpec(
+        "FEN-3002", ExitCode.INPUT, "input uses a newer format version than supported", "upgrade fenolite"
+    ),
+    ErrorSpec(
+        "FEN-4001",
+        ExitCode.CONFIRM_REQUIRED,
+        "confirmation required; nothing was written",
+        "review result.plan, then re-run with --confirm (or --dry-run to only preview)",
+    ),
+    ErrorSpec(
+        "FEN-5001",
+        ExitCode.FINDINGS,
+        "verification produced findings of severity error",
+        "read 'issues' in the envelope",
+    ),
+    ErrorSpec(
+        "FEN-6001",
+        ExitCode.TOOL,
+        "external tool not found",
+        "run 'fenolite capabilities' to see what is missing",
+        retryable=True,
+    ),
+    ErrorSpec(
+        "FEN-6002", ExitCode.TOOL, "external tool version not supported", "install a supported version"
+    ),
+    ErrorSpec(
+        "FEN-7001",
+        ExitCode.LOSSY,
+        "operation would lose information",
+        "re-run with --allow-lossy to accept the loss",
+    ),
+)
+
+REGISTRY: dict[str, ErrorSpec] = {spec.code: spec for spec in _SPECS}
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorInfo:
+    """The single error object written to stderr when the exit code is not 0."""
+
+    code: str = field(metadata={"pattern": ERROR_CODE.pattern})
+    message: str
+    hint: str
+    retryable: bool
+    where: str
+
+
+class CliError(Exception):
+    """An error with a registered ``FEN-NNNN`` code; the dispatcher maps it to an exit code."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str | None = None,
+        *,
+        hint: str | None = None,
+        where: str = "",
+        retryable: bool | None = None,
+    ) -> None:
+        if code not in REGISTRY:
+            raise ValueError(f"unregistered error code {code!r}")
+        spec = REGISTRY[code]
+        self.code = code
+        self.message = message or spec.message
+        self.hint = spec.hint if hint is None else hint
+        self.where = where
+        self.retryable = spec.retryable if retryable is None else retryable
+        super().__init__(f"{code}: {self.message}")
+
+    @property
+    def exit_code(self) -> ExitCode:
+        return REGISTRY[self.code].exit_code
+
+    def info(self) -> ErrorInfo:
+        return ErrorInfo(
+            code=self.code, message=self.message, hint=self.hint, retryable=self.retryable, where=self.where
+        )
+
+
+__all__ = ["ERROR_CODE", "REGISTRY", "CliError", "ErrorInfo", "ErrorSpec"]

fenolite/cli/exitcodes.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""The fixed exit-code vocabulary of the ``fenolite`` command (frozen at 1.0)."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Process exit codes. The first digit of every ``FEN-NNNN`` error code equals one of these."""
+
+    OK = 0
+    INTERNAL = 1
+    USAGE = 2
+    INPUT = 3
+    CONFIRM_REQUIRED = 4
+    FINDINGS = 5
+    TOOL = 6
+    LOSSY = 7
+
+
+__all__ = ["ExitCode"]

fenolite/cli/main.py

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Fenolite contributors
+"""The ``fenolite`` dispatcher: global flags, command discovery, errors, exit codes and the
+mutation protocol. See ``docs/cli-contract.md``."""
+
+from __future__ import annotations
+
+import argparse
+import random
+import sys
+import time
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import NoReturn, TextIO
+
+from fenolite import __version__
+from fenolite.cli.api import Command, Context, Result, discover
+from fenolite.cli.errors import CliError, ErrorInfo
+from fenolite.cli.exitcodes import ExitCode
+from fenolite.cli.output import (
+    Envelope,
+    FieldNotFoundError,
+    OutputMode,
+    Receipt,
+    WrittenFile,
+    parse_fields,
+    project_fields,
+    render_json,
+    render_text,
+    resolve_mode,
+    write_error,
+)
+from fenolite.core.io import atomic_write, sha256_bytes
+
+
+class _Parser(argparse.ArgumentParser):
+    """argparse that raises typed usage errors instead of printing and exiting."""
+
+    def error(self, message: str) -> NoReturn:
+        raise CliError("FEN-2001", message, hint=f"run '{self.prog} --help'")
+
+
+def _add_global_options(parser: argparse.ArgumentParser, *, top_level: bool) -> None:
+    default: object = argparse.SUPPRESS
+    group = parser.add_argument_group("output and determinism")
+    group.add_argument("--json", action="store_true", default=False if top_level else default,
+                       help="force JSON output")  # fmt: skip
+    group.add_argument("--text", action="store_true", default=False if top_level else default,
+                       help="force human-readable output")  # fmt: skip
+    group.add_argument("--fields", default=None if top_level else default, metavar="A,B.C",
+                       help="keep only these dotted paths of 'result'")  # fmt: skip
+    group.add_argument("--seed", type=int, default=None if top_level else default,
+                       help="seed for generated ids (reproducible output)")  # fmt: skip
+    group.add_argument("--timestamp", default=None if top_level else default, metavar="ISO8601",
+                       help="fixed timestamp for generated dates")  # fmt: skip
+    group.add_argument("--no-backup", action="store_true", default=False if top_level else default,
+                       help="do not keep .bak copies of overwritten files")  # fmt: skip
+
+
+def build_parser(commands: dict[str, Command]) -> argparse.ArgumentParser:
+    parser = _Parser(prog="fenolite", description="Headless, agent-first PCB design automation.")
+    parser.add_argument("--version", action="version", version=f"fenolite {__version__}")
+    _add_global_options(parser, top_level=True)
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND", parser_class=_Parser)
+    for command in sorted(commands.values(), key=lambda c: c.name):
+        if command.help is None:  # hidden: not listed in --help
+            child = sub.add_parser(command.name)
+        else:
+            child = sub.add_parser(command.name, help=command.help, description=command.help)
+        _add_global_options(child, top_level=False)
+        if command.mutates:
+            protocol = child.add_argument_group("writing files")
+            protocol.add_argument("--dry-run", action="store_true", help="show the plan; write nothing")
+            protocol.add_argument("--confirm", action="store_true", help="perform the writes")
+        command.register(child)
+    return parser
+
+
+def _timestamp(value: str | None) -> datetime:
+    if value is None:
+        return datetime.now(UTC)
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise CliError("FEN-2004", f"invalid --timestamp {value!r}") from exc
+    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
+
+
+def _context(args: argparse.Namespace, mode: OutputMode) -> Context:
+    seed: int | None = args.seed
+    rng = random.Random(seed) if seed is not None else random.Random()
+    return Context(
+        mode=mode,
+        seed=seed,
+        timestamp=_timestamp(args.timestamp),
+        rng=rng,
+        no_backup=bool(args.no_backup),
+        cwd=Path.cwd(),
+    )
+
+
+def _emit(envelope: Envelope, mode: OutputMode, out: TextIO) -> None:
+    out.write((render_json(envelope) if mode == "json" else render_text(envelope)) + "\n")
+
+
+def _envelope(command: Command, outcome: Result, result: dict[str, object], *, ok: bool,
+              receipt: Receipt | None, started: float) -> Envelope:  # fmt: skip
+    return Envelope(
+        ok=ok,
+        command=command.name,
+        schema=command.schema,
+        input=outcome.input,
+        result=dict(result),
+        issues=outcome.issues,
+        evidence=outcome.evidence,
+        receipt=receipt,
+        elapsed_ms=max(0, round((time.perf_counter() - started) * 1000)),
+    )
+
+
+def _dispatch(command: Command, args: argparse.Namespace, ctx: Context, started: float,
+              out: TextIO, err: TextIO) -> int:  # fmt: skip
+    dry_run = bool(getattr(args, "dry_run", False))
+    confirm = bool(getattr(args, "confirm", False))
+    if dry_run and confirm:
+        raise CliError("FEN-2003")
+    fields = parse_fields(args.fields) if args.fields else []
+
+    try:
+        outcome = command.run(args, ctx)
+        if outcome.writes and not command.mutates:
+            raise RuntimeError(f"command {command.name!r} returned writes but is not declared mutating")
+    except CliError as exc:
+        _emit(_envelope(command, Result(), {}, ok=False, receipt=None, started=started), ctx.mode, out)
+        write_error(exc.info(), ctx.mode, err)
+        return int(exc.exit_code)
+    except Exception as exc:  # any bug inside a command becomes exit 1 with FEN-1001
+        _emit(_envelope(command, Result(), {}, ok=False, receipt=None, started=started), ctx.mode, out)
+        write_error(
+            CliError("FEN-1001", f"{type(exc).__name__}: {exc}", where=command.name).info(), ctx.mode, err
+        )
+        return int(ExitCode.INTERNAL)
+
+    try:
+        result = project_fields(outcome.result, fields) if fields else dict(outcome.result)
+    except FieldNotFoundError as exc:
+        raise CliError("FEN-2002", f"unknown field {exc.args[0]!r} in --fields") from exc
+
+    code = ExitCode.OK
+    error: ErrorInfo | None = None
+    receipt: Receipt | None = None
+    if outcome.writes:
+        plan = [
+            {"path": w.path, "kind": w.kind, "bytes": len(w.data), "sha256": sha256_bytes(w.data),
+             "overwrite": (ctx.cwd / w.path).exists()}
+            for w in outcome.writes
+        ]  # fmt: skip
+        if dry_run:
+            result["plan"] = plan
+        elif not confirm:
+            result["plan"] = plan
+            code = ExitCode.CONFIRM_REQUIRED
+            error = CliError("FEN-4001", where=command.name).info()
+        else:
+            written: list[WrittenFile] = []
+            backups: list[str] = []
+            for w in outcome.writes:
+                receipt_io = atomic_write(ctx.cwd / w.path, w.data, backup=not ctx.no_backup)
+                written.append(WrittenFile(path=w.path, sha256=receipt_io.sha256))
+                if receipt_io.backup_path is not None:
+                    backups.append(w.path + ".bak")
+            receipt = Receipt(written=tuple(written), backup=tuple(backups))
+
+    n_errors = sum(1 for issue in outcome.issues if issue.severity == "error")
+    if code is ExitCode.OK and n_errors:
+        code = ExitCode.FINDINGS
+        error = CliError("FEN-5001", f"{n_errors} finding(s) of severity error", where=command.name).info()
+
+    _emit(
+        _envelope(command, outcome, result, ok=code is ExitCode.OK, receipt=receipt, started=started),
+        ctx.mode,
+        out,
+    )
+    if error is not None:
+        write_error(error, ctx.mode, err)
+    return int(code)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run ``fenolite`` with ``argv`` (defaults to ``sys.argv[1:]``) and return the exit code."""
+    started = time.perf_counter()
+    raw = list(sys.argv[1:] if argv is None else argv)
+    out, err = sys.stdout, sys.stderr
+    mode = resolve_mode(force_json="--json" in raw, force_text="--text" in raw, stream=out)
+    try:
+        commands = discover()
+        parser = build_parser(commands)
+        try:
+            args = parser.parse_args(raw)
+        except SystemExit as exc:  # --help / --version print and exit 0
+            return exc.code if isinstance(exc.code, int) else 0
+        if args.json and args.text:
+            raise CliError("FEN-2001", "--json and --text are mutually exclusive")
+        if args.command is None:
+            parser.print_help(out)
+            return int(ExitCode.OK)
+        ctx = _context(args, mode)
+        return _dispatch(commands[args.command], args, ctx, started, out, err)
+    except CliError as exc:
+        write_error(exc.info(), mode, err)
+        return int(exc.exit_code)
+
+
+__all__ = ["build_parser", "main"]