techtree 0.1.0__py3-none-any.whl

techtree/cli/commands/withdraw.py

@@ -0,0 +1,212 @@
+"""``techtree withdraw``. Decisions document 0038.
+
+The founder chose to implement withdrawal rather than to promise it: a public
+promise with no executable path would be worse than neither. This is the path.
+
+*An entry is addressed by its bundle digest.* That is how the log addresses a
+run — ``/runs/sha256:…`` — so it is what a person copies off the page they are
+looking at, and it works whether or not the run is still on this machine.
+
+*The request is signed with the key that signed the run.* The identity store
+holds it and it is the only signing key this machine has. The network verifies
+it against the participant key inside the publication it already accepted, which
+is why nothing here sends a public key: a key that travelled with the request
+would be a key the requester chose.
+
+*There is no reason field.* Nothing a submitter writes appears on the site, and
+a free-text reason attached to a public entry would be the one string that did.
+
+*Withdrawn is not deleted.* The entry stays where it is, marked, and what comes
+back names where it still lives. The wording says that rather than implying an
+erasure this release does not perform.
+
+Somebody has to say so. Withdrawal changes a public page, so it is asked for the
+same way publishing is asked for, and where nobody can be asked the command
+stops and names the flag instead of deciding on their behalf.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Final
+
+import typer
+from rich.console import Console
+
+from techtree.canonical import validate_digest
+from techtree.cli.confirm import confirmed
+from techtree.cli.context import CliContext, cli_context
+from techtree.cli.invoke import CommandResult, invoke_command
+from techtree.cli.output import human_console, render_pairs
+from techtree.drafts.store import utc_now
+from techtree.errors import UsageError
+from techtree.identity.service import IdentityService
+from techtree.identity.store import IdentityStore
+from techtree.models.base import Digest, NonEmptyString, ProtocolModel, UtcDateTime
+from techtree.models.cli import CliMessage, MessageLevel
+from techtree.publication.coordinates import packaged_publication_coordinates
+from techtree.publication.transport import (
+    HttpsPublicationTransport,
+    resolved_endpoint,
+)
+from techtree.publication.withdraw import WithdrawalService
+
+__all__ = [
+    "WITHDRAWAL_CONFIRMATION_REQUIRED",
+    "WITHDRAW_COMMAND",
+    "WithdrawalPayload",
+    "build_withdrawal_service",
+    "withdraw_run_command",
+    "withdrawal_review_lines",
+]
+
+WITHDRAW_COMMAND: Final = "withdraw"
+
+#: Stable error code for "nobody said to withdraw this".
+WITHDRAWAL_CONFIRMATION_REQUIRED: Final = "withdrawal_confirmation_required"
+
+_WITHDRAW_PROMPT: Final = "Withdraw this entry from the public log?"
+
+#: What withdrawal is and is not, said where somebody is deciding. It is the
+#: honest claim rather than the comfortable one: the entry stays, marked, and
+#: nothing about backups is implied.
+_WHAT_WITHDRAWAL_DOES: Final = (
+    "Withdrawing marks the entry withdrawn. It is not a deletion: the entry "
+    "stays at the address it already has, the log records the withdrawal as "
+    "another event, and anyone who already has the proof still has it."
+)
+
+
+class WithdrawalPayload(ProtocolModel):
+    """What ``techtree withdraw`` returns once the log has marked an entry."""
+
+    bundle_digest: Digest
+    endpoint: NonEmptyString
+    entry_url: NonEmptyString
+    withdrawn_at: UtcDateTime
+    #: The participant key the request was signed with. It is the identity the
+    #: log checked against the publication it accepted, so a person can see that
+    #: the entry was withdrawn by the identity that published it.
+    key_id: NonEmptyString
+
+
+def withdraw_run_command(
+    ctx: typer.Context,
+    bundle_digest: Annotated[
+        str,
+        typer.Argument(
+            metavar="BUNDLE_DIGEST",
+            help="The published entry's bundle digest, as the log addresses it.",
+        ),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            help=(
+                "Withdraw without being asked. For an operator running Techtree "
+                "where nobody can answer a prompt."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """Withdraw a published run from the public run log."""
+    context = cli_context(ctx)
+
+    def action() -> CommandResult[WithdrawalPayload]:
+        digest = validate_digest(bundle_digest)
+        service = build_withdrawal_service(context)
+        if not yes:
+            _require_withdrawal_confirmation(context, digest, service.endpoint)
+
+        outcome = service.withdraw(digest)
+        payload = WithdrawalPayload(
+            bundle_digest=outcome.bundle_digest,
+            endpoint=service.endpoint,
+            entry_url=outcome.entry_url,
+            withdrawn_at=outcome.withdrawn_at,
+            key_id=outcome.key_id,
+        )
+        return CommandResult(
+            data=payload,
+            messages=[
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="entry_withdrawn",
+                    text=(
+                        f"The entry at {payload.entry_url} is marked withdrawn. "
+                        "It stays where it is: the log appended the withdrawal "
+                        "rather than removing anything."
+                    ),
+                )
+            ],
+        )
+
+    invoke_command(context, WITHDRAW_COMMAND, action, render_data=_render)
+
+
+def build_withdrawal_service(context: CliContext) -> WithdrawalService:
+    """Construct the service this command withdraws through.
+
+    The same pinned coordinates and the same development override publishing
+    uses, and for the same reasons — one address for the whole of this feature,
+    and one key whose countersignature is worth having.
+    """
+    coordinates = packaged_publication_coordinates()
+    return WithdrawalService(
+        coordinates=coordinates,
+        endpoint=resolved_endpoint(coordinates, context.settings.publication_endpoint),
+        identity=IdentityService(IdentityStore(context.paths)),
+        transport=HttpsPublicationTransport(),
+        clock=utc_now,
+    )
+
+
+def _require_withdrawal_confirmation(
+    context: CliContext, bundle_digest: Digest, endpoint: str
+) -> None:
+    """Show what would happen, take the answer, or send nothing."""
+    if context.no_input:
+        raise UsageError(
+            "withdrawing changes a public page, so somebody has to agree to "
+            "it. Nothing here can be asked, so say so with --yes",
+            code=WITHDRAWAL_CONFIRMATION_REQUIRED,
+            details={"bundle_digest": bundle_digest},
+        )
+
+    console = human_console(no_color=context.no_color)
+    for line in withdrawal_review_lines(bundle_digest, endpoint):
+        console.print(line)
+    console.print()
+    if not confirmed(_WITHDRAW_PROMPT):
+        raise UsageError(
+            f"entry {bundle_digest} was not withdrawn; no request left this machine",
+            code=WITHDRAWAL_CONFIRMATION_REQUIRED,
+            details={"bundle_digest": bundle_digest},
+        )
+
+
+def withdrawal_review_lines(bundle_digest: Digest, endpoint: str) -> list[str]:
+    """Return what a person reads before they answer."""
+    return [
+        f"Withdrawing entry {bundle_digest}",
+        "",
+        f"A signed request goes to {endpoint}. It is signed with this "
+        "machine's own key, which is the key that signed the run.",
+        "",
+        _WHAT_WITHDRAWAL_DOES,
+    ]
+
+
+def _render(data: object, console: Console) -> None:
+    if not isinstance(data, WithdrawalPayload):
+        return
+
+    render_pairs(
+        [
+            ("Entry", data.entry_url),
+            ("Proof", data.bundle_digest),
+            ("Withdrawn", data.withdrawn_at.isoformat()),
+            ("Signed by", data.key_id),
+        ],
+        console,
+    )

techtree/cli/confirm.py

@@ -0,0 +1,47 @@
+"""Asking a person a yes-or-no question. Spec section 12.3.
+
+Every mutation this CLI performs on somebody's behalf is confirmed before it
+happens, and there are two ways that confirmation can fail to arrive. A person
+can read the question and say no. Or nobody can be there to read it: the
+command was piped from ``/dev/null``, run from a cron entry, or launched by a
+host agent that gave it no terminal, and the prompt reaches end of input
+without ever being seen. A person can also press ``Ctrl-C`` in the middle of
+reading it, which is a third way of not answering.
+
+All three are the same outcome, and it is a usage outcome rather than a defect.
+Nothing went wrong inside the product: it asked, and it was not told to go
+ahead. Reported as a defect — which is what an unhandled ``Abort`` escaping to
+the CLI's error boundary becomes — an unanswerable prompt tells a caller that
+Techtree is broken and gives it an exit code that means so, when the true
+answer is that it needs a flag.
+
+That is the whole of what lives here. This module asks the question and says
+whether it was told to go ahead; what a "no" means, which error it is, and what
+the person should be told belong to the command that had something to confirm,
+because only that command knows what was about to happen.
+
+The default is always no. A prompt whose default is yes turns a stray newline
+into consent, and nothing in this product is worth confirming by accident.
+"""
+
+from __future__ import annotations
+
+import typer
+
+__all__ = ["confirmed"]
+
+
+def confirmed(question: str) -> bool:
+    """Ask ``question`` and return whether the answer was an explicit yes.
+
+    Returns ``False`` for every way of not being told to go ahead: a person who
+    typed no, a prompt that reached end of input because nothing was there to
+    answer it, and a person who interrupted it. A caller that must distinguish
+    "nobody can be asked" from "somebody said no" checks that before it asks —
+    ``CliContext.no_input`` is that check — because by the time a prompt has
+    been written there is nothing left to distinguish.
+    """
+    try:
+        return typer.confirm(question, default=False)
+    except typer.Abort:
+        return False

techtree/cli/context.py

@@ -0,0 +1,96 @@
+"""What every command is allowed to assume. Spec section 12.1.
+
+One object carries the four things a command needs before it can do anything:
+where local state lives, what the user configured, whether the caller is a
+person or a machine, and how much detail to put on stderr. It is built once, in
+the root callback, and handed down through Typer's context.
+
+Two rules are enforced here rather than repeated in every command.
+
+Machine mode is derived, not merely requested. ``--json`` turns it on, and so
+does an ``output_mode`` of ``json`` in settings, because a caller that has
+configured machine output has already said which side of the boundary it is on.
+
+Machine mode implies ``--no-input``. A prompt written to a host agent is a
+hang, not a question, so the flags cannot disagree: asking for JSON is asking
+for a CLI that never waits for a human.
+
+No command-specific service is created here. This module knows about paths and
+settings and nothing else.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+from techtree.errors import PrerequisiteError, TechtreeError
+from techtree.paths import (
+    TechtreePaths,
+    default_paths,
+    ensure_path_layout,
+    paths_from_root,
+)
+from techtree.settings import Settings, resolved_settings
+
+__all__ = ["CliContext", "build_cli_context", "cli_context"]
+
+
+@dataclass(frozen=True)
+class CliContext:
+    """Everything a command may assume about its invocation."""
+
+    paths: TechtreePaths
+    settings: Settings
+    json_output: bool
+    no_color: bool
+    no_input: bool
+    debug: bool
+
+
+def build_cli_context(
+    *,
+    home: Path | None,
+    json_output: bool,
+    no_color: bool,
+    no_input: bool,
+    debug: bool,
+) -> CliContext:
+    """Resolve paths, create layout, load settings, and return context."""
+    paths = (
+        default_paths() if home is None else paths_from_root(Path(home).expanduser())
+    )
+
+    try:
+        ensure_path_layout(paths)
+    except OSError as error:
+        raise PrerequisiteError(
+            f"cannot create the Techtree home directory {paths.root}: {error.strerror}",
+            code="techtree_home_unusable",
+            details={"path": str(paths.root)},
+        ) from error
+
+    settings = resolved_settings(paths)
+    machine = json_output or settings.output_mode == "json"
+
+    return CliContext(
+        paths=paths,
+        settings=settings,
+        json_output=machine,
+        no_color=no_color or machine,
+        no_input=no_input or machine,
+        debug=debug,
+    )
+
+
+def cli_context(ctx: typer.Context) -> CliContext:
+    """Return the context the root callback attached to this invocation."""
+    context = ctx.obj
+    if not isinstance(context, CliContext):
+        raise TechtreeError(
+            "the CLI context was never built for this invocation",
+            code="internal_error",
+        )
+    return context

techtree/cli/invoke.py

@@ -0,0 +1,220 @@
+"""The error boundary every command runs inside. Spec section 12.3.
+
+One invariant governs this module: an invocation that starts a command emits
+exactly one envelope and exits with the code that envelope implies. ``ok`` and
+the exit status never disagree — zero means ``ok`` is true, anything else means
+``ok`` is false and an error is present. A host agent can therefore branch on
+the exit code alone and only parse output when it wants the detail.
+
+Three kinds of outcome funnel through :func:`invoke_command`.
+
+A command can succeed, and say what it produced and what could sensibly happen
+next. A command can fail by raising a typed :class:`~techtree.errors.
+TechtreeError`, which carries its own code, exit status, and repair actions —
+the code that knows why something failed is the code that says what to do about
+it. And a command can *diagnose* a failure while still having a complete answer
+to give: Doctor finds a broken environment, and the checks it ran are the most
+useful thing it could return. That is what ``CommandResult.error`` is for, and
+it is why a failing envelope may still carry data.
+
+Anything else escaping a command is a defect, not a user error. It becomes an
+``internal_error`` with a sanitized message and exit code 1; the traceback goes
+to stderr under ``--debug``, never into the contract.
+"""
+
+from __future__ import annotations
+
+import traceback
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import NoReturn
+
+import typer
+
+from techtree.cli.context import CliContext
+from techtree.cli.output import (
+    DataRenderer,
+    emit_envelope,
+    stderr_log,
+    write_envelope,
+)
+from techtree.constants import CLI_SCHEMA_VERSION
+from techtree.errors import (
+    EXIT_ERROR,
+    EXIT_OK,
+    TechtreeError,
+    error_to_cli_error,
+    exit_code_for,
+    stable_exception_message,
+)
+from techtree.models.cli import MAX_NEXT_ACTIONS, CliEnvelope, CliMessage, NextAction
+
+__all__ = [
+    "CommandResult",
+    "emit_boundary_failure",
+    "failure_envelope",
+    "invoke_command",
+    "not_implemented_error",
+    "success_envelope",
+]
+
+
+@dataclass
+class CommandResult[T]:
+    """What a command produced, in the CLI's own vocabulary.
+
+    ``error`` is set by a command that completed its work and still has to
+    report failure. Raising is the ordinary way to fail; this is for the case
+    where the diagnosis *is* the payload.
+    """
+
+    data: T
+    messages: list[CliMessage] = field(default_factory=list)
+    warnings: list[CliMessage] = field(default_factory=list)
+    next_actions: list[NextAction] = field(default_factory=list)
+    error: TechtreeError | None = None
+
+
+def success_envelope[T](
+    *,
+    command: str,
+    data: T,
+    messages: list[CliMessage] | None = None,
+    warnings: list[CliMessage] | None = None,
+    next_actions: list[NextAction] | None = None,
+) -> CliEnvelope[T]:
+    """Construct a successful envelope."""
+    return CliEnvelope[T](
+        schema_version=CLI_SCHEMA_VERSION,
+        ok=True,
+        command=command,
+        data=data,
+        messages=list(messages or ()),
+        warnings=list(warnings or ()),
+        next_actions=_capped(next_actions or ()),
+        error=None,
+    )
+
+
+def failure_envelope[T](
+    *,
+    command: str,
+    error: TechtreeError,
+    data: T | None = None,
+    messages: list[CliMessage] | None = None,
+    warnings: list[CliMessage] | None = None,
+    next_actions: list[NextAction] | None = None,
+) -> CliEnvelope[T]:
+    """Construct a failed envelope.
+
+    Repair actions default to the ones the error itself carries, so a raising
+    call site never has to reach the CLI to be helpful.
+    """
+    actions = error.next_actions if next_actions is None else next_actions
+    return CliEnvelope[T](
+        schema_version=CLI_SCHEMA_VERSION,
+        ok=False,
+        command=command,
+        data=data,
+        messages=list(messages or ()),
+        warnings=list(warnings or ()),
+        next_actions=_capped(actions),
+        error=error_to_cli_error(error),
+    )
+
+
+def invoke_command[T](
+    context: CliContext,
+    command: str,
+    action: Callable[[], CommandResult[T]],
+    *,
+    render_data: DataRenderer | None = None,
+) -> NoReturn:
+    """Execute, emit exactly one envelope, and exit correctly."""
+    if context.debug:
+        stderr_log(f"techtree: running {command}")
+
+    envelope: CliEnvelope[T]
+    try:
+        result = action()
+    except TechtreeError as error:
+        envelope = failure_envelope(command=command, error=error)
+        exit_code = exit_code_for(error)
+    except Exception as unexpected:
+        if context.debug:
+            stderr_log(traceback.format_exc().rstrip())
+        envelope = failure_envelope(command=command, error=_internal(unexpected))
+        exit_code = EXIT_ERROR
+    else:
+        if result.error is None:
+            envelope = success_envelope(
+                command=command,
+                data=result.data,
+                messages=result.messages,
+                warnings=result.warnings,
+                next_actions=result.next_actions,
+            )
+            exit_code = EXIT_OK
+        else:
+            envelope = failure_envelope(
+                command=command,
+                error=result.error,
+                data=result.data,
+                messages=result.messages,
+                warnings=result.warnings,
+                next_actions=result.next_actions,
+            )
+            exit_code = exit_code_for(result.error)
+
+    emit_envelope(context, envelope, render_data=render_data)
+
+    if context.debug:
+        stderr_log(f"techtree: {command} exited with code {exit_code}")
+    raise typer.Exit(exit_code)
+
+
+def emit_boundary_failure(
+    *,
+    json_output: bool,
+    no_color: bool,
+    command: str,
+    error: TechtreeError,
+) -> NoReturn:
+    """Report a failure that happened before any command could start."""
+    write_envelope(
+        failure_envelope(command=command, error=error),
+        json_output=json_output,
+        no_color=no_color,
+    )
+    raise typer.Exit(exit_code_for(error))
+
+
+def not_implemented_error(command: str) -> TechtreeError:
+    """Return the error a registered but unbuilt command reports.
+
+    The command name is part of the CLI surface already, so a caller can
+    discover it, script it, and be told plainly that this build does not
+    implement it yet — which is more useful than the command not existing.
+    """
+    return TechtreeError(
+        f"`techtree {command}` is not implemented in this build",
+        code="not_implemented",
+        details={"command": command},
+    )
+
+
+def _internal(error: Exception) -> TechtreeError:
+    return TechtreeError(
+        stable_exception_message(error),
+        code="internal_error",
+        details={"exception_type": type(error).__name__},
+    )
+
+
+def _capped(actions: Sequence[NextAction]) -> list[NextAction]:
+    """Keep the highest-priority actions and drop the rest.
+
+    Callers order actions by usefulness. Truncating here means a caller can
+    offer everything it thought of without having to know the ceiling.
+    """
+    return list(actions[:MAX_NEXT_ACTIONS])