foundry-testing-actor 0.1.0__py3-none-any.whl

foundry_testing_actor/__init__.py

@@ -0,0 +1,56 @@
+"""foundry-testing-actor — run a headless Claude Code black-box test-authoring session against one
+capability's own testing repo.
+
+An actor, for one use, with a `papeete-actor` underneath. The capability it serves is supplied by
+a sidecar (`actor-agentic-context.yaml`, `foundry-testing-actor/agentic-context/v1`), never by this
+package: a second capability instantiates the same actor by writing that file and nothing else.
+
+Two doors. `propose-acceptance` is this actor's half of the three amigos round — a query, answered
+read-only, before anything is built (ADR-FTA-0002). `test-task` authors and extends the black-box
+suite, commits it, and publishes one runnable test image per component it touched.
+
+Wiring one up is four lines:
+
+    from foundry_testing_actor import CapabilityConfig, ClaudeCodeTesterEngine, make_test_task
+
+    config = CapabilityConfig.load(".")
+    actor = Actor.from_card(".", mailbox=mailbox,
+                            engines={config.engine: ClaudeCodeTesterEngine(config)},
+                            actions={"test-task": make_test_task(config)})
+
+`correlation` is exported too — an entrypoint installs its filter on the root logger's handlers
+after configuring observability, so every record the process emits carries this request's ids.
+
+Those four lines are for embedding. A use that just wants the actor writes no Python at all: the
+image this package publishes renders the cards from the sidecar and runs `serve`, which is those
+four lines plus the observability wiring that used to be copied into every repo (ADR-FTA-0001).
+"""
+from .config import (CapabilityConfig, Component, ConfigError, Grounding, Report,
+                     cards_path, lint, runner_path, version)
+from .engine import ClaudeCodeTesterEngine
+from .handler import HandlerError, make_test_task
+from .instance import render_cards
+from .serve import ServeError, serve
+from . import conformance, correlation, grounding, instance
+
+__all__ = [
+    "CapabilityConfig",
+    "ClaudeCodeTesterEngine",
+    "Component",
+    "ConfigError",
+    "Grounding",
+    "HandlerError",
+    "Report",
+    "cards_path",
+    "conformance",
+    "correlation",
+    "grounding",
+    "instance",
+    "lint",
+    "make_test_task",
+    "render_cards",
+    "runner_path",
+    "serve",
+    "ServeError",
+    "version",
+]

foundry_testing_actor/cards/actor-data.yaml

@@ -0,0 +1,68 @@
+# WHAT DATA EXISTS. `papeete-actor-data/v0`, owned by `papeete-actor-message` — a named, minimally
+# typed dictionary. Every field here belongs to the ACTOR, not to any capability: a task id, the
+# caller's statement of the task, what was proposed, what was agreed, and what came back. Nothing
+# names a capability or a knowledge tool, because none of those are known until a sidecar supplies
+# them. `components` is a list of NAMES; which tests root each one maps to is the sidecar's.
+data: papeete-actor-data/v0
+items:
+  - name: task_id
+    type: string
+    description: the TASK-NNN card id this actor was asked about (e.g. "TASK-009")
+  - name: title
+    type: string
+    description: the task's short title/summary, supplied by the caller — no card lookup is performed here
+  - name: context
+    type: string
+    description: free-text elaboration beyond the title — background, constraints, links; optional
+  - name: definition_of_done
+    type: list
+    description: the acceptance criteria the tests must assert against, as the caller states them
+  - name: components
+    type: list
+    description: >-
+      the component name(s) the task concerns (e.g. ["backend"]), as the caller names them — each
+      one a component this use's sidecar declares a tests root for
+  - name: remediation_context
+    type: string
+    description: >-
+      on a retry, the prior attempt's failing test criteria — the session judges whether the fault
+      is in the test itself (fix it here) or in the implementation (leave the test as-is); optional,
+      absent on a first attempt
+  - name: acceptance_surface
+    type: list
+    description: >-
+      the agreed observable expectations this increment must satisfy — proposed at this actor's
+      own propose-acceptance door, then accepted, with commitments, by the implementation actor,
+      before anything was built. Each entry is an object with at least `id`, `statement` and
+      `handle`; extra keys (an attached `commitments` list, for one) are allowed. The dictionary
+      types it as a list and stops there: the entry shape is written in the doors' own means
+  - name: expectations
+    type: list
+    description: >-
+      what this actor proposes to assert black-box once the increment is built, each an object
+      with a stable `id` (short, `E1` or kebab-case, unique within the proposal — a later verdict
+      names it), a `statement` of what must hold, a `handle` saying exactly how a black-box test
+      reaches it, and optionally the `component` it belongs to. Proposed BEFORE anything is built,
+      so a concrete value in a handle is a proposal the implementer commits to or objects to, never
+      a report of what was found
+  - name: open_questions
+    type: list
+    description: >-
+      what the task and the capability's standing context do not determine, and no proposed value
+      can settle — each a string, or an object with `about` and `question`. Not a failure: a
+      non-empty list stops the round and is meant to reach a human; empty when nothing is open
+  - name: accepted
+    type: boolean
+    description: whether the test-task request was accepted, pushed, and its test images published
+  - name: because
+    type: string
+    description: why a request was refused (containment violation, nothing staged, an undeclared component, ...)
+  - name: branch
+    type: string
+    description: the branch the tests were pushed to (test/TASK-NNN)
+  - name: images
+    type: list
+    description: >-
+      the full ref of each touched component's published test image,
+      `<registry>/<capability path>/<component>/tests:<version>`, by convention — the pass/fail
+      verdict is rendered by whichever actor runs it, never reported here

foundry_testing_actor/cards/actor-message.yaml

@@ -0,0 +1,32 @@
+# WHAT MESSAGES EXIST. `papeete-actor-message/v1`, owned by `papeete-actor-message` — named
+# messages, each a pure regrouping of references into the data dictionary, under an intent.
+# Wire-agnostic by that package's own design: WHAT a message is, never HOW it is carried.
+message: papeete-actor-message/v1
+messages:
+  - name: propose-acceptance-cmd
+    intent: >-
+      ask this actor what it will assert, black-box, about a TASK-NNN card once it is built — and
+      what the task leaves undetermined — BEFORE any of it is built
+    references: [task_id, title, definition_of_done, components, context]
+    optional: [context]
+
+  - name: acceptance-proposed-result
+    intent: >-
+      answer with the proposed expectations, each with a stable id, a statement and a handle, and
+      the questions the task leaves open
+    references: [expectations, open_questions]
+    optional: [open_questions]
+
+  - name: test-task-cmd
+    intent: ask this actor to author black-box tests for the published image(s) of a TASK-NNN card
+    references: [task_id, title, definition_of_done, components, context, remediation_context,
+                 acceptance_surface]
+    optional: [context, remediation_context, acceptance_surface]
+
+  - name: test-task-result
+    intent: report that the tests were written, pushed, and their touched components' test images published
+    references: [accepted, branch, images]
+
+  - name: test-task-refused-result
+    intent: report that the task was not tested, and why
+    references: [accepted, because]

foundry_testing_actor/cards/actor-synchronous-messaging.yaml

@@ -0,0 +1,59 @@
+# THE DOORS. `synchronous-messaging-doors/v1` — one action that authors, one query that only
+# proposes.
+#
+# `engine: claude-code` is this actor kind's declared engine, on BOTH doors. A use's sidecar
+# repeats it in its own `engine:` field, and the entrypoint registers the engine under exactly that
+# key — so a use whose sidecar names a different engine is caught by its own card rather than at
+# the first request. One engine instance serves both: `Actor.judge()` hands it the door id, and it
+# dispatches on that.
+#
+# WHY `propose-acceptance` IS A QUERY. An action is a promise to try; a query is a promise to
+# answer, from this actor's own state and nothing invented. Proposing what will be asserted changes
+# nothing — no branch, no commit, no image — and placing it under `queries:` makes that structural
+# rather than merely promised. It is also why it registers no handler: with an engine and no
+# handler, `Actor.receive()` returns the judged dict as the reply. See ADR-FTA-0002, and
+# ADR-FIA-0004 for the round both halves belong to.
+manifest: synchronous-messaging-doors/v1
+actions:
+  - id: test-task
+    means: >-
+      the door for "author black-box tests for TASK-NNN of the capability I serve, now that its
+      increment is built". Send it here with the task id, title, definition of done, components,
+      and (optionally) context, remediation_context and the agreed `acceptance_surface` — the
+      caller supplies everything, no task card is looked up here. I clone my capability's testing
+      repository into my own private copy, and read-only clone its implementation repository at
+      impl/TASK-NNN solely to recompute, by convention, the image refs published there (never
+      passed to me, and never shown to my session); ground myself in that capability's own
+      standing context; and extend the persistent suite under each named component's declared
+      tests root — asserting every agreed expectation by its id, through its handle, where a
+      surface was sent. I never bring up the images, hit a live endpoint, or render a verdict.
+      Then I commit and push to test/TASK-NNN, and build each touched component's test image in
+      the cluster's shared buildkit and push it to the registry, named and versioned by
+      convention. I never open a pull request — an orchestrating actor runs that image and does.
+    completion: whether I accepted, pushed, and published test images (with the branch and image refs), or refused, and why.
+    door_schema: test-task-cmd
+    completion_schema: [test-task-result, test-task-refused-result]
+    engine: claude-code
+
+queries:
+  - id: propose-acceptance
+    means: >-
+      the door for "what will you assert about TASK-NNN once it is built?", asked BEFORE anything
+      is built. Send the task id, title, definition of done, the component names the task
+      concerns, and optional context. I clone my capability's testing repository and its
+      implementation repository's DEFAULT BRANCH read-only — never impl/TASK-NNN, because
+      assertions derived from what was built can only confirm the build — ground myself in the
+      capability's own standing context, and propose the acceptance surface. I write nothing, build
+      nothing, and publish nothing.
+    completion: >-
+      the expectations I will assert, each an object with a stable, short `id` unique within the
+      proposal, a `statement` of what must hold, a `handle` saying exactly how a black-box test
+      reaches it (the component, the endpoint, the event routing key, the environment variable its
+      base URL arrives in — with a concrete value proposed wherever a test needs one the task does
+      not name, for the implementer to commit to or object to), and optionally its `component`;
+      and the open questions the task and the standing context leave undetermined, each a string
+      or an `about`/`question` object, never an invented answer. Any open question is meant to
+      stop the round and reach a human rather than a session.
+    door_schema: propose-acceptance-cmd
+    completion_schema: acceptance-proposed-result
+    engine: claude-code

foundry_testing_actor/cards/actor.yaml

@@ -0,0 +1,19 @@
+# WHO. The actor this package defines — `papeete-actor-manifest/v0`, owned by `papeete-actor`.
+#
+# THIS FOLDER IS THE DEFINITION, NOT A USE. The four cards here say what a foundry testing actor
+# IS: the data it knows, the messages it exchanges, and the two doors it answers. They name no
+# capability, because which capability an instance serves is not part of what the actor is — that
+# is `actor-agentic-context.yaml`, supplied per use.
+#
+# A use of this actor is a folder carrying that sidecar. Its four cards are rendered from these at
+# `docker build` time (`foundry-testing-actor render-cards`), with `name:` set to the use's own.
+manifest: papeete-actor-manifest/v0
+name: foundry-testing-actor
+description: >-
+  Authors black-box tests for one TASK-NNN card of the business capability its sidecar names.
+  Before anything is built, proposes what it will assert, read-only, with each expectation's id,
+  statement and handle, and names what the task leaves undetermined. Once the increment is built,
+  extends that capability's persistent test suite in a private clone of its own testing
+  repository, writing only under the tests roots the sidecar declares — then commits, pushes a
+  branch, and publishes one runnable test image per component the task touched. Never runs the
+  tests, renders a verdict, or opens a pull request: an orchestrating actor does.

foundry_testing_actor/cli.py

@@ -0,0 +1,181 @@
+"""`foundry-testing-actor` — the gate, and the derivation table.
+
+Four subcommands. `lint` is what CI runs against a sidecar; `show` prints every rendering
+`config.py` derives from the two fields that are actually written down, so an operator can check
+the test image ref an actor WILL publish, and the image ref it will recompute for the component
+under test, before either exists — the hand-written actor this replaces could only be checked by
+reading a running actor's logs after the fact.
+
+`render-cards` and `serve` are what make a use's whole repository one sidecar (ADR-FTA-0001): the
+first writes the actor's four cards beside it from the definition in this wheel, the second boots
+the thing. Both run inside the image this package publishes, which is where a use meets them; both
+work in a plain venv too, which is where this repo's own gates run them.
+
+House rule: every published package in this ecosystem ships a CLI named exactly the package.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import conformance
+from .config import CapabilityConfig, ConfigError, lint, runner_path, version
+from .instance import render_cards
+from .serve import DEFAULT_PORT, ServeError, serve
+
+_REGISTRY_PLACEHOLDER = "<registry>"
+
+
+def _cmd_lint(args: argparse.Namespace) -> int:
+    # Two gates, one command. The sidecar says which capability this use serves; the cards say
+    # which actor it claims to be. A use can be wrong about either independently, and the second
+    # check is the only thing standing between a hand-copied card set and a caller being refused
+    # at a door — see `conformance.py`.
+    report = lint(Path(args.folder))
+    conformance_report = conformance.check(Path(args.folder))
+    report.oks.extend(conformance_report.oks)
+    report.warns.extend(conformance_report.warns)
+    report.errors.extend(conformance_report.errors)
+    for warning in report.warns:
+        print(f"  ! {warning}")
+    for error in report.errors:
+        print(f"  FAIL {error}")
+    if not report.ok:
+        print(f"✗ {len(report.errors)} error(s)")
+        return 1
+    for line in report.oks:
+        print(f"  ok   {line}")
+    checked_cards = any((Path(args.folder) / name).exists() for name in conformance.CARD_FILES)
+    print("✓ sidecar and cards conform" if checked_cards else "✓ sidecar conforms")
+    return 0
+
+
+def _cmd_show(args: argparse.Namespace) -> int:
+    try:
+        config = CapabilityConfig.load(Path(args.folder))
+    except ConfigError as e:
+        print(f"  FAIL {e}")
+        return 2
+    registry = args.registry or _REGISTRY_PLACEHOLDER
+
+    rows = [
+        ("capability", config.capability),
+        ("source_repo", config.source_repo),
+        ("implementation_repo", config.implementation_repo
+         + ("" if config.declared_implementation_repo else "   (derived)")),
+        ("registry_repo", config.registry_repo),
+        ("engine", config.engine),
+        ("actor name / git author", config.git_author_name),
+        ("git author email", config.git_author_email),
+        ("clone prefix", config.clone_prefix("TASK-NNN")),
+        ("code clone prefix", config.code_clone_prefix("TASK-NNN")),
+        ("registry path", config.capability_path),
+        ("writes only under", ", ".join(config.writes_only_under)),
+    ]
+    width = max(len(label) for label, _ in rows)
+    for label, value in rows:
+        print(f"  {label:<{width}}  {value}")
+
+    print("\n  components")
+    for component in config.components:
+        print(f"    {component.name}")
+        print(f"      tests            {component.tests}")
+        print(f"      runner           "
+              f"{component.runner or f'(default) {runner_path()}'}")
+        print(f"      test image name  {config.test_image_name(component.name)}")
+        print(f"      test image ref   "
+              f"{config.test_image_ref(registry, component.name, '<version>')}")
+        print(f"      under test       "
+              f"{config.image_ref(registry, component.name, '<version>')}")
+
+    print("\n  ground_in")
+    for entry in config.ground_in:
+        print(f"    {entry.name}  [{entry.load}] → {entry.into}")
+        print(f"      answers   {entry.answers}")
+        print(f"      fetch     {' '.join(config.expand(entry.fetch))}")
+    return 0
+
+
+def _cmd_render_cards(args: argparse.Namespace) -> int:
+    # The step that deletes the hand copy. Run at `docker build` time, right after the sidecar is
+    # COPY'd in: from then on the cards in that folder came from a version, not from someone's
+    # editor, and the next version's cards arrive with the next `FROM`.
+    try:
+        config = CapabilityConfig.load(Path(args.folder))
+    except ConfigError as e:
+        print(f"  FAIL {e}")
+        return 2
+    try:
+        written = render_cards(config, Path(args.folder))
+    except FileNotFoundError as e:
+        print(f"  FAIL {e}")
+        return 2
+    for path in written:
+        print(f"  ok   rendered {path}")
+    print(f"✓ {config.actor_name} — four cards from the definition in "
+          f"foundry-testing-actor=={version()}")
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    # No try/except around the boot itself. A misconfigured actor that starts anyway and refuses
+    # every caller at the door is strictly worse than a pod that crash-loops with the reason on
+    # stdout, which is what an uncaught ConfigError produces here.
+    try:
+        serve(Path(args.folder), port=args.port)
+    except (ConfigError, ServeError) as e:
+        print(f"  FAIL {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="foundry-testing-actor",
+        description="Inspect and validate one capability's agentic-context sidecar.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    lint_parser = sub.add_parser(
+        "lint", help="validate a sidecar against foundry-testing-actor/agentic-context/v1")
+    lint_parser.add_argument(
+        "folder", nargs="?", default=".",
+        help="the actor's folder, or the sidecar file itself (default: .)")
+    lint_parser.set_defaults(func=_cmd_lint)
+
+    show_parser = sub.add_parser(
+        "show", help="print every identifier derived from the sidecar's capability and repo")
+    show_parser.add_argument("folder", nargs="?", default=".")
+    show_parser.add_argument(
+        "--registry", help=f"render image refs against this registry (default: {_REGISTRY_PLACEHOLDER})")
+    show_parser.set_defaults(func=_cmd_show)
+
+    render_parser = sub.add_parser(
+        "render-cards",
+        help="write the actor's four cards into a use's folder, from the definition in this wheel")
+    render_parser.add_argument(
+        "folder", nargs="?", default=".",
+        help="the folder holding this use's actor-agentic-context.yaml (default: .)")
+    render_parser.set_defaults(func=_cmd_render_cards)
+
+    serve_parser = sub.add_parser(
+        "serve", help="boot this actor and answer its doors (needs the `serve` extra)")
+    serve_parser.add_argument(
+        "folder", nargs="?", default=".",
+        help="the folder holding this use's sidecar and cards (default: .)")
+    serve_parser.add_argument(
+        "--port", type=int, default=None,
+        help=f"override $PORT (default: $PORT, else {DEFAULT_PORT})")
+    serve_parser.set_defaults(func=_cmd_serve)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())