harnessweaver-cli 0.7.1__py3-none-any.whl

harnessweaver_cli/scaffold.py

@@ -0,0 +1,158 @@
+"""``harnessweaver init``: start a project from a template, and ``harnessweaver test``.
+
+Templates are directories copied as they are; the only substitution is the
+project name for the marker ``__app_name__`` in file contents (there is no
+template language, R12). Built-in templates ship with the CLI; a plugin's
+templates are named ``<namespace>.<template>`` (DESIGNS No. 13). Templates whose
+names start with ``_`` are scaffolds for other commands (``plugin new``), not
+projects.
+"""
+
+import os
+import re
+import subprocess
+import sys
+from collections.abc import Mapping
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Annotated, Final
+
+import typer
+
+from harnessweaver.core.errors import HarnessError
+from harnessweaver.ports import TEST_MODE_ENV
+from harnessweaver_cli._load import fail
+
+__all__ = [
+    "BUILTIN_TEMPLATES",
+    "copy_tree",
+    "init",
+    "render_template",
+    "run_tests",
+    "template_root",
+]
+
+MARKER: Final = "__app_name__"
+BUILTIN_TEMPLATES: Final = ("extraction", "rag", "agent", "workflow", "chat")
+_NAME = re.compile(r"^[a-z][a-z0-9-]*$")
+_SKIP = {"__pycache__", ".pytest_cache", ".DS_Store"}
+
+
+def template_root(name: str) -> Traversable:
+    """Where template ``name`` lives: in the CLI, or in the plugin that ships it.
+
+    Raises:
+        typer.Exit: For a template nobody ships.
+    """
+    if name.startswith("_"):
+        raise fail(f"no template {name!r}; built-in templates: {', '.join(BUILTIN_TEMPLATES)}")
+    return _root(name)
+
+
+def _root(name: str) -> Traversable:
+    if "." not in name:
+        root = resources.files("harnessweaver_cli").joinpath("templates", name)
+        if not root.is_dir():
+            raise fail(f"no template {name!r}; built-in templates: {', '.join(BUILTIN_TEMPLATES)}")
+        return root
+    from harnessweaver.core.registry import PluginCatalog
+
+    namespace, _, template = name.partition(".")
+    try:
+        loaded = PluginCatalog.default().load(namespace)
+    except HarnessError as exc:
+        raise fail(exc) from None
+    path = loaded.plugin.templates.get(template)
+    if path is None:
+        raise fail(f"plugin {namespace!r} has no template {template!r}")
+    return loaded.resource(path)
+
+
+def _files(root: Traversable, prefix: Path = Path()) -> list[tuple[Path, Traversable]]:
+    found: list[tuple[Path, Traversable]] = []
+    for entry in sorted(root.iterdir(), key=lambda e: e.name):
+        if entry.name in _SKIP:
+            continue
+        if entry.is_dir():
+            found += _files(entry, prefix / entry.name)
+        else:
+            found.append((prefix / entry.name, entry))
+    return found
+
+
+def _filled(text: str, markers: Mapping[str, str]) -> str:
+    for marker, value in markers.items():
+        text = text.replace(marker, value)
+    return text
+
+
+def copy_tree(
+    root: Traversable, directory: Path, markers: Mapping[str, str], *, force: bool = False
+) -> list[Path]:
+    """Copy the files under ``root`` into ``directory``, replacing each marker with its
+    value in file contents and in paths. Returns the files written.
+
+    Raises:
+        typer.Exit: If a file would be overwritten (without ``force``).
+    """
+    files = [(Path(_filled(str(relative), markers)), source) for relative, source in _files(root)]
+    clashes = [str(relative) for relative, _ in files if (directory / relative).exists()]
+    if clashes and not force:
+        raise fail(f"{', '.join(clashes)} already exist in {directory}; use --force to overwrite")
+    written: list[Path] = []
+    for relative, source in files:
+        target = directory / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(_filled(source.read_text(encoding="utf-8"), markers), encoding="utf-8")
+        written.append(target)
+    return written
+
+
+def render_template(
+    name: str, directory: Path, app_name: str, *, force: bool = False
+) -> list[Path]:
+    """Copy template ``name`` into ``directory``, named ``app_name``. Returns the files written.
+
+    Raises:
+        typer.Exit: For an unknown template, or if a file would be overwritten
+            (without ``force``).
+    """
+    return copy_tree(template_root(name), directory, {MARKER: app_name}, force=force)
+
+
+def init(
+    directory: Annotated[Path, typer.Argument(help="Where to create the project.")] = Path("."),
+    template: Annotated[
+        str, typer.Option("--template", "-t", help="A template name.")
+    ] = "extraction",
+    name: Annotated[
+        str | None, typer.Option("--name", help="Project name (default: the directory).")
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite existing files.")] = False,
+) -> None:
+    """Start a project: harness.yaml, an offline overlay, code, prompts, evals and tests."""
+    app_name = name or directory.resolve().name.lower().replace("_", "-")
+    if not _NAME.match(app_name):
+        raise fail(f"invalid project name {app_name!r}: use lowercase letters, digits and dashes")
+    written = render_template(template, directory, app_name, force=force)
+    typer.echo(f"created {len(written)} files in {directory} from the {template} template")
+    typer.echo("next:")
+    typer.echo(f"  cd {directory}")
+    typer.echo("  harnessweaver spec validate --env offline")
+    typer.echo("  harnessweaver test")
+
+
+def run_tests(
+    ctx: typer.Context,
+    env: Annotated[str, typer.Option("--env", "-e", help="Overlay for the tests.")] = "offline",
+) -> None:
+    """Run the app's tests offline: test mode on, the offline overlay, extra args to pytest."""
+    environment = {**os.environ, TEST_MODE_ENV: "1", "HARNESSWEAVER_ENV": env}
+    try:
+        done = subprocess.run(
+            [sys.executable, "-m", "pytest", *ctx.args], env=environment, check=False
+        )
+    except OSError as exc:
+        raise fail(f"can't run pytest ({type(exc).__name__})") from None
+    raise typer.Exit(code=done.returncode)

harnessweaver_cli/sidecar.py

@@ -0,0 +1,48 @@
+"""``harnessweaver sidecar``: run harnessd for a spec, if harnessweaver-sidecar is installed.
+
+The CLI doesn't depend on the sidecar package (it brings FastAPI and uvicorn), so
+the import happens only when the command runs.
+"""
+
+import importlib
+from typing import Annotated
+
+import typer
+
+from harnessweaver.core.errors import HarnessError
+from harnessweaver_cli._load import fail, spec_path
+from harnessweaver_cli.spec import Env, Path_, ProfileDirs
+
+__all__ = ["sidecar"]
+
+
+def sidecar(
+    path: Path_ = None,
+    env: Env = None,
+    profile_dir: ProfileDirs = None,
+    host: Annotated[str, typer.Option(help="Where to listen; keep 127.0.0.1 (S6).")] = "127.0.0.1",
+    port: Annotated[int, typer.Option(help="The port.")] = 7070,
+    token_env: Annotated[
+        str, typer.Option(help="The variable holding the bearer token clients send.")
+    ] = "HARNESSD_TOKEN",
+    max_body_bytes: Annotated[
+        int, typer.Option(help="The largest request body read; anything over answers 413.")
+    ] = 10 * 1024 * 1024,
+) -> None:
+    """Serve the spec to other languages over HTTP: run harnessd (DESIGNS No. 24)."""
+    try:
+        harnessd = importlib.import_module("harnessweaver_sidecar.main")
+    except ImportError:
+        raise fail("harnessd isn't installed; run: uv add harnessweaver-sidecar") from None
+    try:
+        harnessd.serve(
+            spec_path(path),
+            env=env,
+            profile_dirs=profile_dir or [],
+            host=host,
+            port=port,
+            token_env=token_env,
+            max_body_bytes=max_body_bytes,
+        )
+    except HarnessError as exc:
+        raise fail(exc) from None

harnessweaver_cli/spec.py

@@ -0,0 +1,160 @@
+"""``harnessweaver spec validate|explain|diff``, ``hooks`` and ``contracts export``."""
+
+import json
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from harnessweaver import HookPoint
+from harnessweaver.contracts import stale_schemas, write_schemas
+from harnessweaver.spec import diff_specs, render_diff, render_explain
+from harnessweaver_cli._load import load_effective, load_harness, spec_path
+
+__all__ = ["contracts_app", "hooks", "spec_app"]
+
+spec_app = typer.Typer(help="Validate, explain and diff harness.yaml.", no_args_is_help=True)
+contracts_app = typer.Typer(help="Work with the language-neutral contracts.", no_args_is_help=True)
+
+Path_ = Annotated[Path | None, typer.Argument(help="The app spec (default: harness.yaml).")]
+Env = Annotated[str | None, typer.Option("--env", "-e", help="Overlay: harness.<env>.yaml.")]
+ProfileDirs = Annotated[
+    list[Path] | None, typer.Option("--profile-dir", help="Also search here for org:// profiles.")
+]
+Format = Annotated[Literal["text", "json"], typer.Option("--format", help="Output format.")]
+
+
+def _console() -> Console:
+    return Console(width=120, highlight=False, soft_wrap=True)
+
+
+@spec_app.command("validate")
+def validate(
+    path: Path_ = None, env: Env = None, profile_dir: ProfileDirs = None, output: Format = "text"
+) -> None:
+    """Load the spec as the app would: layers, locks, bounds, plugins, tasks, hooks (R4)."""
+    harness = load_harness(path, env, profile_dir or [])
+    level = harness.spec.level
+    if output == "json":
+        body = {
+            "ok": True,
+            "name": harness.name,
+            "level": level.level.value,
+            "required": level.required.value,
+            "tasks": harness.tasks,
+            "layers": [p.describe() for p in harness.spec.layers],
+        }
+        typer.echo(json.dumps(body, indent=2))
+        return
+    typer.echo(f"ok: {harness.name} is valid")
+    typer.echo(f"  adoption level {level.level.value} (required: {level.required.value})")
+    typer.echo(f"  layers: {', '.join(p.describe() for p in harness.spec.layers)}")
+    typer.echo(f"  tasks: {', '.join(harness.tasks) or '(none)'}")
+
+
+@spec_app.command("explain")
+def explain(
+    path: Path_ = None,
+    env: Env = None,
+    profile_dir: ProfileDirs = None,
+    prefix: Annotated[
+        str | None, typer.Option("--path", help="Only paths starting with this.")
+    ] = None,
+    output: Format = "text",
+) -> None:
+    """Show every effective value, the layer it came from, and its locks and bounds."""
+    effective = load_effective(str(spec_path(path)), env, profile_dir or [])
+    rows = [r for r in effective.explain() if prefix is None or r.path.startswith(prefix)]
+    if output == "json":
+        body = [
+            {
+                "path": r.path,
+                "value": r.value,
+                "layer": r.origin.layer if r.origin else None,
+                "locked_by": r.locked_by.declared_by.layer if r.locked_by else None,
+            }
+            for r in rows
+        ]
+        typer.echo(json.dumps(body, indent=2))
+        return
+    typer.echo(render_explain(rows))
+
+
+@spec_app.command("diff")
+def diff(
+    before: Annotated[str, typer.Argument(help="Old spec: a path, or git:<ref>:<path>.")],
+    after: Annotated[str, typer.Argument(help="New spec: a path, or git:<ref>:<path>.")],
+    env: Env = None,
+    profile_dir: ProfileDirs = None,
+    exit_code: Annotated[
+        bool, typer.Option("--exit-code", help="Exit 1 when the effective specs differ.")
+    ] = False,
+) -> None:
+    """Compare two effective specs as Markdown: values, locks and adoption level."""
+    dirs = profile_dir or []
+    result = diff_specs(load_effective(before, env, dirs), load_effective(after, env, dirs))
+    typer.echo(render_diff(result))
+    if exit_code and not result.empty:
+        raise typer.Exit(code=1)
+
+
+def hooks(
+    path: Path_ = None,
+    env: Env = None,
+    profile_dir: ProfileDirs = None,
+    task: Annotated[str | None, typer.Option("--task", help="Show a task's chains.")] = None,
+) -> None:
+    """Show the middleware on every hook point, in the order it runs (DESIGNS No. 8)."""
+    harness = load_harness(path, env, profile_dir or [])
+    reaches = harness.runner_of(task).reaches if task is not None else None
+    title = f"{harness.name} hooks" + (f" for task {task}" if task else "")
+    table = Table(title=escape(title), box=box.ASCII)
+    for column in ("hook", "order", "middleware", "band", "fail mode", "timeout"):
+        table.add_column(column)
+    for hook, chain in harness.hooks(task).items():
+        label = hook.value
+        if reaches is not None and hook not in reaches:
+            label += " (not reached)"
+        if not chain:
+            table.add_row(label, "-", "-", "", "", "")
+        for position, registration in enumerate(chain, start=1):
+            timeout = f"{registration.timeout.total_seconds():g}s" if registration.timeout else ""
+            table.add_row(
+                label if position == 1 else "",
+                str(position),
+                escape(registration.name),
+                registration.band.value,
+                registration.fail_mode,
+                timeout,
+            )
+    console = _console()
+    console.print(table)
+    direction = {h.value: h.direction.value for h in HookPoint}
+    console.print(
+        "inbound hooks run baseline -> task; outbound hooks run task -> baseline: "
+        + ", ".join(sorted(k for k, v in direction.items() if v == "outbound"))
+    )
+
+
+@contracts_app.command("export")
+def export(
+    out: Annotated[Path, typer.Argument(help="Directory for the JSON Schemas.")] = Path(
+        "contracts/schemas"
+    ),
+    check: Annotated[bool, typer.Option("--check", help="Report drift; write nothing.")] = False,
+) -> None:
+    """Write the JSON Schema of every contract (harness.yaml, events, outcomes, ...)."""
+    if check:
+        problems = stale_schemas(out)
+        for problem in problems:
+            typer.echo(problem)
+        if problems:
+            raise typer.Exit(code=1)
+        typer.echo(f"ok: the schemas in {out} are up to date")
+        return
+    written = write_schemas(out)
+    typer.echo(f"wrote {len(written)} schemas to {out}")

harnessweaver_cli/templates/_dev/compose.yaml

@@ -0,0 +1,183 @@
+# A local stack for this app, written by `harnessweaver dev` (ADR-0039): LiteLLM Proxy
+# (config from `harnessweaver gateway litellm`), an OpenTelemetry collector that sends
+# traces to Langfuse, and harnessd serving the spec. Secrets and the provider models
+# are in .env, next to this file; nothing here is meant to be committed.
+#
+#   docker compose up -d        (or: harnessweaver dev --up)
+#
+# harnessd and the collector share LiteLLM's network, so the URLs a spec uses on the
+# developer's machine (http://localhost:4000 for the gateway, :4318 for OTLP) work
+# unchanged inside the containers too. Every port is published on 127.0.0.1 only (S6),
+# and every image is pinned by digest (S5).
+
+name: harnessweaver-dev
+
+x-langfuse-env: &langfuse-env
+  NEXTAUTH_URL: http://localhost:3000
+  DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/postgres
+  SALT: ${SALT}
+  ENCRYPTION_KEY: ${ENCRYPTION_KEY}
+  TELEMETRY_ENABLED: "false"
+  CLICKHOUSE_MIGRATION_URL: clickhouse://clickhouse:9000
+  CLICKHOUSE_URL: http://clickhouse:8123
+  CLICKHOUSE_USER: clickhouse
+  CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
+  CLICKHOUSE_CLUSTER_ENABLED: "false"
+  LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
+  LANGFUSE_S3_EVENT_UPLOAD_REGION: auto
+  LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: minio
+  LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}
+  LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://minio:9000
+  LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
+  LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
+  LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: langfuse
+  LANGFUSE_S3_MEDIA_UPLOAD_REGION: auto
+  LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: minio
+  LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}
+  LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: http://localhost:9090
+  LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
+  LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
+  REDIS_HOST: redis
+  REDIS_PORT: "6379"
+  REDIS_AUTH: ${REDIS_AUTH}
+
+x-langfuse-depends: &langfuse-depends
+  postgres: { condition: service_healthy }
+  clickhouse: { condition: service_healthy }
+  minio: { condition: service_healthy }
+  redis: { condition: service_healthy }
+
+services:
+  litellm:
+    image: ghcr.io/berriai/litellm:v1.104.0@sha256:625981c83410a3ea68eb0697590a57ec1d764d634514d54fa5db0591077ee839
+    command: ["--config", "/etc/litellm/config.yaml", "--port", "4000"]
+    env_file: .env
+    volumes:
+      - ./litellm.yaml:/etc/litellm/config.yaml:ro
+    ports:
+      - 127.0.0.1:4000:4000     # LiteLLM Proxy
+      - 127.0.0.1:4317:4317     # OTLP gRPC (the collector)
+      - 127.0.0.1:4318:4318     # OTLP HTTP (the collector)
+      - 127.0.0.1:7070:7070     # harnessd
+    restart: unless-stopped
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.162.0@sha256:39923a8e431bd1f57be82411999d389fcfe40857492e4365456d97a4c1f74be6
+    command: ["--config", "/etc/otelcol/config.yaml"]
+    network_mode: service:litellm
+    environment:
+      LANGFUSE_OTLP_AUTH: ${LANGFUSE_OTLP_AUTH}
+    volumes:
+      - ./otel-collector.yaml:/etc/otelcol/config.yaml:ro
+    depends_on: [litellm, langfuse-web]
+    restart: unless-stopped
+
+  harnessd:
+    # Build it from the HarnessWeaver repository: docker build -f deploy/harnessd/Dockerfile -t harnessd:dev .
+    image: ${HARNESSD_IMAGE:-harnessd:dev}
+    network_mode: service:litellm
+    env_file: .env
+    environment:
+      HARNESSWEAVER_ENV: "__env__"
+      HARNESSWEAVER_PROFILE_PATH: "__profile_path__"   # the folders --profile-dir named
+    volumes:
+      - ../..:/app:ro           # the app: its spec, overlays, profiles and code
+__profile_volumes__    command: ["__spec__"]
+    depends_on: [litellm]
+    restart: unless-stopped
+
+  langfuse-web:
+    image: docker.io/langfuse/langfuse:4@sha256:ce6c636df92db6638f15beb7d826f0460a51d04fcfe2e55132fcc8aad9e1bef8
+    depends_on: *langfuse-depends
+    ports:
+      - 127.0.0.1:3000:3000
+    environment:
+      <<: *langfuse-env
+      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
+      LANGFUSE_S3_MEDIA_UPLOAD_INTERNAL_ENDPOINT: http://minio:9000
+      LANGFUSE_INIT_ORG_ID: harnessweaver
+      LANGFUSE_INIT_ORG_NAME: HarnessWeaver
+      LANGFUSE_INIT_PROJECT_ID: dev
+      LANGFUSE_INIT_PROJECT_NAME: dev
+      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY}
+      LANGFUSE_INIT_PROJECT_SECRET_KEY: ${LANGFUSE_SECRET_KEY}
+      LANGFUSE_INIT_USER_EMAIL: ${LANGFUSE_USER_EMAIL}
+      LANGFUSE_INIT_USER_NAME: dev
+      LANGFUSE_INIT_USER_PASSWORD: ${LANGFUSE_USER_PASSWORD}
+    restart: unless-stopped
+
+  langfuse-worker:
+    image: docker.io/langfuse/langfuse-worker:4@sha256:68549f1167370de7e601114e592dbc86aac13216d90c5193063a2d9d83d9ec57
+    depends_on: *langfuse-depends
+    environment: *langfuse-env
+    restart: unless-stopped
+
+  postgres:
+    image: docker.io/postgres:17@sha256:2d2b8998d31037bf721cfdf764d76ba74171b4fab3431b7f72c27c56ddbdf9e3
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: postgres
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+    restart: unless-stopped
+
+  clickhouse:
+    image: docker.io/clickhouse/clickhouse-server:25.12@sha256:8a790dd3468db22b1d4e7b18a176f378ff5ff6053b9c48dd4ea1fa71a24c5ba6
+    user: "101:101"
+    environment:
+      CLICKHOUSE_DB: default
+      CLICKHOUSE_USER: clickhouse
+      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
+    volumes:
+      - clickhouse_data:/var/lib/clickhouse
+      - clickhouse_logs:/var/log/clickhouse-server
+    healthcheck:
+      test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  minio:
+    image: cgr.dev/chainguard/minio:latest@sha256:cff197fef764642223ef9f4444c903d51aee9b544a7be8bc007fef6b7b00d136
+    entrypoint: sh
+    # Langfuse's bucket must exist before it starts.
+    command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
+    environment:
+      MINIO_ROOT_USER: minio
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
+    ports:
+      - 127.0.0.1:9090:9000     # media uploads from the browser
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 1s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  redis:
+    image: docker.io/redis:7@sha256:4fa24486b8bcca8eec45ee0eb166edc674795e53a2b53d1a9ef263eecebaac85
+    command: ["--requirepass", "${REDIS_AUTH}", "--maxmemory-policy", "noeviction"]
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "-a", "${REDIS_AUTH}", "ping"]
+      interval: 3s
+      timeout: 10s
+      retries: 10
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+  clickhouse_data:
+  clickhouse_logs:
+  minio_data:
+  redis_data:

harnessweaver_cli/templates/_dev/otel-collector.yaml

@@ -0,0 +1,25 @@
+# The dev stack's OpenTelemetry collector, written by `harnessweaver dev`: OTLP in from
+# the app, harnessd and LiteLLM, traces out to the local Langfuse (OTLP over HTTP;
+# Langfuse doesn't take gRPC). LANGFUSE_OTLP_AUTH comes from .env.
+receivers:
+  otlp:
+    protocols:
+      grpc: { endpoint: 0.0.0.0:4317 }
+      http: { endpoint: 0.0.0.0:4318 }
+
+processors:
+  batch: {}
+
+exporters:
+  otlp_http/langfuse:
+    endpoint: http://langfuse-web:3000/api/public/otel
+    headers:
+      Authorization: "Basic ${env:LANGFUSE_OTLP_AUTH}"
+      x-langfuse-ingestion-version: "4"
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp_http/langfuse]

harnessweaver_cli/templates/_plugin/README.md

@@ -0,0 +1,26 @@
+# __dist__
+
+A HarnessWeaver plugin. It contributes everything under the namespace `__ns__`; the sample contribution is the guard `__ns__.banned_words`.
+
+```bash
+uv sync                  # install it, with pytest
+uv run pytest            # its tests and the HarnessWeaver conformance suite
+```
+
+Use it from any app's `harness.yaml` once it is installed next to `harnessweaver`:
+
+```yaml
+guardrails:
+  input:
+    - { use: __ns__.banned_words, words: [lottery, wire transfer], mode: log_only }
+```
+
+New guards start in shadow mode (`mode: log_only`) and are promoted to `enforce` once evals back them. If the org baseline locks `plugins.allow`, ask the platform team to add `__ns__` to it.
+
+## Add a contribution
+
+1. Write it in `src/__ns___harness/` with its decorator: `@hw.provider(port=..., name="__ns__.<name>", ...)`, `@hw.middleware(...)`, `@hw.decider("<name>")`, `@hw.runner(...)` or `@hw.adapter(...)`. A contribution whose config has required fields declares `sample=` settings for the conformance suite.
+2. List it in `plugin = hw.Plugin(...)` in `src/__ns___harness/__init__.py`.
+3. Test it, and run `uv run pytest`: the conformance suite checks every contribution.
+
+Build only against the public surface: `harnessweaver` (`hw.Plugin`, the decorators and the contract models), `harnessweaver.ports` and `harnessweaver.testing`. It is versioned with the contract (`contract=">=1.0,<2"`), so the plugin keeps working across HarnessWeaver releases within `harnessweaver/v1`.

harnessweaver_cli/templates/_plugin/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.32"]
+build-backend = "hatchling.build"
+
+[project]
+name = "__dist__"
+version = "0.1.0"
+description = "A HarnessWeaver plugin: guards and other contributions under the __ns__ namespace."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["harnessweaver>=0.1.0"]
+
+# The one registration a plugin needs: its namespace, and where its hw.Plugin is (DESIGNS No. 13).
+[project.entry-points."harnessweaver.plugins"]
+__ns__ = "__ns___harness:plugin"
+
+[dependency-groups]
+dev = ["pytest>=9"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/__ns___harness"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Every run also runs the HarnessWeaver conformance suite on this plugin (RULES T5).
+addopts = ["--import-mode=importlib", "--harnessweaver-conformance=__ns__"]

harnessweaver_cli/templates/_plugin/src/__ns___harness/__init__.py

@@ -0,0 +1,20 @@
+"""__dist__: a HarnessWeaver plugin under the namespace ``__ns__``.
+
+Installing it registers nothing and imports nothing: HarnessWeaver finds it
+through the ``harnessweaver.plugins`` entry point and imports it only when a
+spec names one of its contributions, such as ``use: __ns__.banned_words``
+(DESIGNS No. 13, RULES S8). So this module must not do I/O when it is imported.
+"""
+
+import harnessweaver as hw
+from __ns___harness.guards import BannedWords, BannedWordsConfig
+
+plugin = hw.Plugin(
+    namespace="__ns__",
+    version="0.1.0",
+    contract=">=1.0,<2",
+    providers=[BannedWords],
+    description="Guards for __ns__ apps.",
+)
+
+__all__ = ["BannedWords", "BannedWordsConfig", "plugin"]