techtree 0.1.0__py3-none-any.whl

techtree/cli/output.py

@@ -0,0 +1,280 @@
+"""How one envelope reaches stdout. Spec section 12.2.
+
+There are exactly two renderings of a response and they never mix. A machine
+gets one compact JSON object and a newline. A person gets messages, a data
+summary, warnings, and numbered next steps. Which one happens is decided by the
+context, once, so no command can half-render.
+
+The JSON spelling is the canonical one: sorted keys, no insignificant
+whitespace. Nothing here is hashed, but a stable byte order is what makes an
+envelope diffable in a test and in a bug report.
+
+Operational logs go to stderr and only to stderr. That separation is the whole
+reason a host agent can pipe stdout into a JSON parser without filtering it
+first.
+
+``shell_display`` exists so a next action can be *shown* as a command line. It
+uses ``shlex.join`` and its output is display-only: the argv list is the
+contract, the string is a courtesy. Nothing in Techtree ever executes a
+displayed command string, which is exactly why next actions are arrays.
+"""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from techtree.canonical import canonical_json_text
+from techtree.cli.context import CliContext
+from techtree.models.cli import (
+    CliEnvelope,
+    CliError,
+    CliMessage,
+    MessageLevel,
+    NextAction,
+)
+
+__all__ = [
+    "DataRenderer",
+    "emit_envelope",
+    "human_console",
+    "json_stdout",
+    "render_human",
+    "render_next_actions",
+    "render_pairs",
+    "shell_display",
+    "stderr_log",
+    "write_envelope",
+]
+
+type DataRenderer = Callable[[Any, Console], None]
+"""Renders one command's payload for a person. Machine mode never calls it."""
+
+#: How each message level is introduced in human output. Plain words rather
+#: than symbols, so the text survives a terminal that cannot draw them.
+_LEVEL_PREFIX: dict[MessageLevel, str] = {
+    MessageLevel.INFO: "",
+    MessageLevel.WARNING: "Warning: ",
+    MessageLevel.ERROR: "Error: ",
+}
+
+_LEVEL_STYLE: dict[MessageLevel, str] = {
+    MessageLevel.INFO: "",
+    MessageLevel.WARNING: "yellow",
+    MessageLevel.ERROR: "red",
+}
+
+
+def human_console(*, no_color: bool) -> Console:
+    """Return the console human output is written to.
+
+    Rich already emits no escape sequences when stdout is not a terminal, so a
+    piped human rendering is plain text without anyone asking for it.
+    """
+    return Console(
+        file=sys.stdout,
+        no_color=no_color,
+        highlight=False,
+        emoji=False,
+        markup=False,
+    )
+
+
+def emit_envelope(
+    context: CliContext,
+    envelope: CliEnvelope[Any],
+    *,
+    render_data: DataRenderer | None = None,
+) -> None:
+    """Write one JSON object or render human output."""
+    write_envelope(
+        envelope,
+        json_output=context.json_output,
+        no_color=context.no_color,
+        render_data=render_data,
+    )
+
+
+def write_envelope(
+    envelope: CliEnvelope[Any],
+    *,
+    json_output: bool,
+    no_color: bool,
+    render_data: DataRenderer | None = None,
+) -> None:
+    """Write one envelope without needing a fully built context.
+
+    The error boundary reaches this directly: a failure while the context is
+    still being built still owes the caller exactly one response.
+    """
+    if json_output:
+        json_stdout(envelope)
+        return
+    render_human(envelope, human_console(no_color=no_color), render_data=render_data)
+
+
+def render_human(
+    envelope: CliEnvelope[Any],
+    console: Console,
+    *,
+    render_data: DataRenderer | None = None,
+) -> None:
+    """Render messages, typed data summaries, warnings, and next actions."""
+    for message in envelope.messages:
+        _render_message(message, console)
+
+    if envelope.data is not None and render_data is not None:
+        if envelope.messages:
+            console.print()
+        render_data(envelope.data, console)
+
+    if envelope.warnings:
+        console.print()
+        for warning in envelope.warnings:
+            _render_message(warning, console)
+
+    if envelope.error is not None:
+        console.print()
+        _render_error(envelope.error, console)
+
+    render_next_actions(envelope.next_actions, console)
+
+
+def render_next_actions(actions: list[NextAction], console: Console) -> None:
+    """Render ordered next steps with display-only shell quoting."""
+    if not actions:
+        return
+
+    console.print()
+    # Decision 0024 section 7: a successful response ends with one immediate
+    # action, so the one-action case is headed the way that rule reads.
+    console.print("Next:" if len(actions) == 1 else "Next steps:")
+    table = Table(box=None, show_header=False, pad_edge=False, padding=(0, 1))
+    table.add_column("index", justify="right", no_wrap=True)
+    # Folded rather than truncated. A next step is meant to be typed, and a
+    # command with an ellipsis in the middle of a path cannot be: a
+    # materialized Skill's cache directory alone is seventy-one characters
+    # (decisions document 0010 item 5), so the one place a reader most needs
+    # the whole line is the place a narrow terminal would cut it.
+    table.add_column("step", overflow="fold")
+
+    # One step is not a list, so it is not numbered like one.
+    numbered = len(actions) > 1
+    for position, action in enumerate(actions, start=1):
+        table.add_row(f"{position}." if numbered else "", _step_text(action))
+
+    console.print(table)
+
+
+def render_pairs(pairs: list[tuple[str, str]], console: Console) -> None:
+    """Render labelled facts as one two-column table.
+
+    Almost every command that shows a person what it found shows it this way:
+    a short label on the left and the value beside it. They were built one at a
+    time and drifted apart, and a reader moving between two commands should not
+    have to notice that they are looking at the same thing drawn differently.
+
+    The label is dimmed and the value is not, because the value is what the
+    reader came for and the label is only there to say which value it is.
+
+    The value column folds rather than truncates, for the reason given where
+    next actions do the same: a folded digest or path can still be copied out
+    of a narrow terminal and a shortened one cannot.
+    """
+    table = Table(box=None, show_header=False, pad_edge=False, padding=(0, 2))
+    table.add_column("label", no_wrap=True, style="dim")
+    table.add_column("value", overflow="fold")
+    for label, value in pairs:
+        table.add_row(label, value)
+    console.print(table)
+
+
+def shell_display(argv: list[str]) -> str:
+    """Use shlex.join for display only."""
+    return shlex.join(argv)
+
+
+def json_stdout(envelope: CliEnvelope[Any]) -> None:
+    """Write one compact JSON object and one newline."""
+    sys.stdout.write(canonical_json_text(envelope))
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+def stderr_log(message: str) -> None:
+    """Write operational logs to stderr."""
+    sys.stderr.write(f"{message}\n")
+    sys.stderr.flush()
+
+
+def _render_message(message: CliMessage, console: Console) -> None:
+    prefix = _LEVEL_PREFIX[message.level]
+    console.print(f"{prefix}{message.text}", style=_LEVEL_STYLE[message.level] or None)
+
+
+def _step_text(action: NextAction) -> Text:
+    """Return one next step with the line a person types set apart.
+
+    A step is up to three lines that used to look alike: what it is, the
+    command, and why. The command is the only one of them anybody retypes, so
+    it is the one the eye should land on, and the reason is the one a reader
+    who already knows why can pass over. Weight says that without moving
+    anything or changing a word, which is what was wanted here: the ordering
+    and the wording are settled elsewhere and this changes neither.
+
+    The styles are carried by a :class:`~rich.text.Text` rather than by a
+    marked-up string. Nothing this console prints is read for markup, so a
+    label or a path that happens to contain square brackets is drawn as the
+    characters it is made of and cannot choose a colour for itself.
+    """
+    step = Text(action.label)
+    if action.cli is not None:
+        step.append("\n")
+        step.append(shell_display(action.cli), style="bold")
+    if action.reason is not None:
+        step.append("\n")
+        step.append(action.reason, style="dim")
+    if action.requires_user_confirmation:
+        step.append("\nRequires confirmation by a person before it runs.")
+    return step
+
+
+def _render_error(error: CliError, console: Console) -> None:
+    """Draw a failure so that it cannot be scrolled past, when somebody is there.
+
+    The message and the code were two ordinary lines among all the other
+    ordinary lines a command prints, which is what a reader skimming a long
+    response goes straight past. A frame around them says which part went
+    wrong before any of the words have been read.
+
+    The frame is drawn only for a terminal. Box-drawing characters are not
+    colour: they are ordinary text and they survive a pipe, so framing a
+    redirected response would push decoration into whatever reads it next.
+    Redirected output stays the two plain lines it has always been, and the
+    words are the same either way.
+
+    The frame is drawn around the words rather than across the terminal.
+    Nothing else in this product draws a box at all, so one that ran the full
+    width would be by far the loudest thing on the screen, and a missing run
+    identifier does not warrant that. Sized to its own contents it still marks
+    the failure at a glance without shouting over the response it belongs to.
+    """
+    message = Text(f"Error: {error.message}", style="red")
+    code = Text(f"Code: {error.code}")
+    if not console.is_terminal:
+        console.print(message)
+        console.print(code)
+        return
+
+    framed = Text()
+    framed.append_text(message)
+    framed.append("\n")
+    framed.append_text(code)
+    console.print(Panel.fit(framed, border_style="red"))

techtree/constants.py

@@ -0,0 +1,138 @@
+"""Central protocol constants. Spec section 10.4.
+
+This module holds values only. It imports nothing from the rest of the package
+and defines no behavior, so every other module may import it freely without
+creating a cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+#: Prefix that turns a bare SHA-256 hexadecimal string into a Techtree digest.
+DIGEST_PREFIX: Final = "sha256:"
+
+CLI_SCHEMA_VERSION: Final = "techtree.cli.v1"
+CATALOG_SCHEMA_VERSION: Final = "techtree.catalog.v1alpha1"
+CAMPAIGN_SCHEMA_VERSION: Final = "techtree.campaign.v1alpha1"
+CLIMB_SCHEMA_VERSION: Final = "techtree.climb.v1alpha1"
+DATA_POLICY_SCHEMA_VERSION: Final = "techtree.data-policy.v1alpha1"
+EVALUATION_BACKEND_SCHEMA_VERSION: Final = "techtree.evaluation-backend.v1alpha1"
+SKILL_SCHEMA_VERSION: Final = "techtree.skill.v1alpha1"
+SUBMISSION_DRAFT_SCHEMA_VERSION: Final = "techtree.submission-draft.v1alpha1"
+EXPERIMENT_SCHEMA_VERSION: Final = "techtree.experiment.v1alpha1"
+TASKSET_LOCK_SCHEMA_VERSION: Final = "techtree.taskset-lock.v1alpha1"
+TASKSET_VALIDATION_SCHEMA_VERSION: Final = "techtree.taskset-validation.v1alpha1"
+#: Decisions document 0003 A1. The deterministic, normalized form of the raw
+#: upstream validation output that a receipt points at.
+VALIDATION_EVIDENCE_SCHEMA_VERSION: Final = "techtree.validation-evidence.v1alpha1"
+#: Decisions document 0003 A1. Local operational provenance for one validation
+#: execution. Never part of the Campaign graph.
+VALIDATION_EXECUTION_SCHEMA_VERSION: Final = "techtree.validation-execution.v1alpha1"
+EPISODE_RECEIPT_SCHEMA_VERSION: Final = "techtree.episode-receipt.v1alpha1"
+UPLIFT_SCHEMA_VERSION: Final = "techtree.uplift-report.v1alpha1"
+ENGINE_SCHEMA_VERSION: Final = "techtree.engine.v1alpha1"
+#: Decisions document 0038. The two documents that cross the one boundary this
+#: product opens: what a participant sends when they publish a run, and the
+#: countersigned record the network returns.
+PUBLICATION_SUBMISSION_SCHEMA_VERSION: Final = (
+    "techtree.publication-submission.v1alpha1"
+)
+PUBLICATION_RECEIPT_SCHEMA_VERSION: Final = "techtree.publication-receipt.v1alpha1"
+#: Decisions 0038: a published entry is withdrawn, never deleted. The request
+#: is signed by the same participant key that signed the run, and the network
+#: answers with a countersigned record that the entry is now marked withdrawn.
+PUBLICATION_WITHDRAWAL_SCHEMA_VERSION: Final = (
+    "techtree.publication-withdrawal.v1alpha1"
+)
+PUBLICATION_WITHDRAWAL_RECEIPT_SCHEMA_VERSION: Final = (
+    "techtree.publication-withdrawal-receipt.v1alpha1"
+)
+#: One line of a run's publication journal. Decisions 0038: publishing is
+#: recorded beside a completed run without touching a byte the run wrote.
+PUBLICATION_JOURNAL_SCHEMA_VERSION: Final = "techtree.publication-journal.v1alpha1"
+
+#: Decisions document 0003 A9. Go/OCI-style ``<os>/<arch>`` strings are the
+#: only host-platform spelling in the protocol. The tuple is ordered so that
+#: generated descriptors and schemas list the vocabulary the same way every
+#: time.
+SUPPORTED_HOST_PLATFORMS: Final[tuple[str, ...]] = (
+    "darwin/amd64",
+    "darwin/arm64",
+    "linux/amd64",
+    "linux/arm64",
+)
+
+#: The subject container every generated Campaign pins, and the per-platform
+#: manifests that index resolves to. Decisions document 0007 R5 makes this
+#: release-blocking: a tag moves, so a Campaign naming one could not claim its
+#: two variants ran the same subject, and a multi-platform index digest alone
+#: does not say which bytes a given host ran.
+#:
+#: Hermes Agent is installed into the container at setup time from a PEP 723
+#: script, so the image needs a shell, ``pip`` and nothing else; the agent's own
+#: interpreter is provisioned by ``uv`` inside the container. That is why the
+#: pin is a stock ``python:3.11-slim`` and not something Techtree publishes.
+#:
+#: Every digest below was read from the registry rather than written from
+#: memory, on 2026-08-13::
+#:
+#:     docker image inspect python:3.11-slim --format '{{index .RepoDigests 0}}'
+#:     docker manifest inspect python@sha256:90744cff...
+#:
+#: ``tests/preflight/test_subject_image_pin.py`` re-reads both and fails if the
+#: registry ever stops agreeing with what is written here.
+SUBJECT_IMAGE_REPOSITORY: Final = "python"
+SUBJECT_IMAGE_TAG: Final = "3.11-slim"
+SUBJECT_IMAGE_INDEX_DIGEST: Final = (
+    "sha256:90744cff8f32887f075c47d747a173ff333e9e98801667af93c357fa9f5e28ff"
+)
+SUBJECT_IMAGE: Final = f"{SUBJECT_IMAGE_REPOSITORY}@{SUBJECT_IMAGE_INDEX_DIGEST}"
+SUBJECT_IMAGE_PLATFORM_DIGESTS: Final[dict[str, str]] = {
+    "linux/amd64": (
+        "sha256:78b39ef14d8e2b4d71f8dc304f1328c37df95fe0ef99477c2ae6bd3d03784553"
+    ),
+    "linux/arm64": (
+        "sha256:20eadabc42589e6543b24a64ab305b9895e9fcf6dbb2cadb14812f394ecdbadf"
+    ),
+}
+
+#: What the starter Skill is called in front of a person, and what the guided
+#: first run files it under. Decisions document 0009 fixes the name and 0010
+#: item 5 fixes the label; the two are deliberately different values, and
+#: neither is ever derived from a path. A materialized Skill lives in a
+#: directory named by the digest it was verified against, and a digest is
+#: neither a name anybody would choose nor a label a candidate may carry.
+STARTER_SKILL_NAME: Final = "hello-world-starter-v1"
+STARTER_SKILL_CANDIDATE_LABEL: Final = "hello-world-v1"
+
+#: Why the starter Skill is the shape it is. Decisions document 0010 item 2
+#: amends 0007 R4: the Skill's own text stays silent about its gap, because a
+#: Skill that announced one would be measuring something other than what it
+#: says, and the release metadata discloses instead. This is that disclosure
+#: on the command line, printed beside the Skill's name wherever it is handed
+#: over — the same sentence the public Climb page and the calibration record
+#: carry. It is release metadata about the artifact, never Skill content.
+STARTER_SKILL_PURPOSE: Final = "intentionally incomplete introductory Skill"
+
+DEFAULT_WORKER_HEARTBEAT_SECONDS: Final = 2
+DEFAULT_STALE_HEARTBEAT_SECONDS: Final = 15
+
+MAX_SKILL_FILE_BYTES: Final = 256 * 1024
+MAX_SKILL_TOTAL_BYTES: Final = 2 * 1024 * 1024
+MAX_SKILL_FILES: Final = 64
+
+ALLOWED_SKILL_SUFFIXES: Final[frozenset[str]] = frozenset(
+    {
+        ".md",
+        ".txt",
+        ".json",
+        ".yaml",
+        ".yml",
+    }
+)
+
+#: Decisions document 0001. Never a branch, a tag, or an unpinned PyPI range.
+#: Changing this value requires a dedicated dependency-bump change that reruns
+#: the pinned-Verifiers preflight suite.
+PINNED_VERIFIERS_REVISION: Final = "b2e4e8157783b2c0dffc7821044c87f29f1c3ccf"

techtree/crypto.py

@@ -0,0 +1,128 @@
+"""Ed25519 primitives. Spec sections 10.8 and 2.6.
+
+This module is deliberately inert. It knows how to make a key, move key
+material in and out of raw bytes, sign a digest string, and check a signature.
+It knows nothing about where keys live, which key is "ours", or when signing
+should happen.
+
+Decisions document 0001 froze that boundary for WP0–WP5, when nothing signed
+anything; decisions document 0005 amendment 4 turned signing on in WP7. The
+boundary itself did not move. There is still no key store here on purpose:
+:mod:`techtree.identity` is the one place that knows where a key lives, which
+key is this machine's, and when something is signed with it.
+
+What gets signed is the ASCII digest string — ``sha256:`` and 64 hexadecimal
+characters — rather than the canonical bytes themselves. A verifier can then
+check a signature while holding only the digest, and the thing being attested
+to is exactly the value that appears in the protocol document.
+"""
+
+from __future__ import annotations
+
+import base64
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from techtree.canonical import validate_digest
+from techtree.errors import ValidationError
+from techtree.models.base import Digest, SignatureEnvelope
+
+__all__ = [
+    "ED25519_PRIVATE_KEY_BYTES",
+    "ED25519_PUBLIC_KEY_BYTES",
+    "ED25519_SIGNATURE_BYTES",
+    "generate_private_key",
+    "load_private_key",
+    "load_public_key",
+    "private_key_bytes",
+    "public_key_bytes",
+    "public_key_to_base64",
+    "sign_digest",
+    "verify_signature",
+]
+
+ED25519_PRIVATE_KEY_BYTES = 32
+ED25519_PUBLIC_KEY_BYTES = 32
+ED25519_SIGNATURE_BYTES = 64
+
+
+def generate_private_key() -> Ed25519PrivateKey:
+    """Create a new Ed25519 key."""
+    return Ed25519PrivateKey.generate()
+
+
+def public_key_bytes(private_key: Ed25519PrivateKey) -> bytes:
+    """Return raw public-key bytes."""
+    return private_key.public_key().public_bytes_raw()
+
+
+def private_key_bytes(private_key: Ed25519PrivateKey) -> bytes:
+    """Return raw private-key bytes."""
+    return private_key.private_bytes_raw()
+
+
+def load_private_key(raw: bytes) -> Ed25519PrivateKey:
+    """Load and validate raw private key material."""
+    if len(raw) != ED25519_PRIVATE_KEY_BYTES:
+        raise ValidationError(
+            f"Ed25519 private keys are {ED25519_PRIVATE_KEY_BYTES} raw bytes",
+            details={"length": len(raw)},
+        )
+    return Ed25519PrivateKey.from_private_bytes(raw)
+
+
+def load_public_key(raw: bytes) -> Ed25519PublicKey:
+    """Load and validate raw public key material."""
+    if len(raw) != ED25519_PUBLIC_KEY_BYTES:
+        raise ValidationError(
+            f"Ed25519 public keys are {ED25519_PUBLIC_KEY_BYTES} raw bytes",
+            details={"length": len(raw)},
+        )
+    return Ed25519PublicKey.from_public_bytes(raw)
+
+
+def public_key_to_base64(public_key: Ed25519PublicKey) -> str:
+    """Return the base64 spelling protocol documents carry a public key in."""
+    return base64.b64encode(public_key.public_bytes_raw()).decode("ascii")
+
+
+def sign_digest(
+    private_key: Ed25519PrivateKey,
+    digest: Digest,
+    *,
+    key_id: str,
+) -> SignatureEnvelope:
+    """Sign the ASCII digest string."""
+    message = validate_digest(digest).encode("ascii")
+    signature = private_key.sign(message)
+    return SignatureEnvelope(
+        algorithm="ed25519",
+        key_id=key_id,
+        signature=base64.b64encode(signature).decode("ascii"),
+    )
+
+
+def verify_signature(
+    public_key: Ed25519PublicKey,
+    digest: Digest,
+    signature: SignatureEnvelope,
+) -> bool:
+    """Verify the digest signature.
+
+    Returns ``False`` for a signature that is well-formed but wrong — a wrong
+    key, a different digest, or corrupted signature bytes. A malformed digest
+    is a different kind of problem and raises instead.
+    """
+    message = validate_digest(digest).encode("ascii")
+    raw_signature = base64.b64decode(signature.signature, validate=True)
+    if len(raw_signature) != ED25519_SIGNATURE_BYTES:
+        return False
+    try:
+        public_key.verify(raw_signature, message)
+    except InvalidSignature:
+        return False
+    return True

techtree/doctor/__init__.py

@@ -0,0 +1 @@
+"""Environment diagnosis: what is present, what is missing, what blocks work."""