techtree 0.1.0__py3-none-any.whl

techtree/cli/commands/setup.py

@@ -0,0 +1,181 @@
+"""``techtree setup``. Spec section 12.9.
+
+One command that takes a machine from "Techtree is installed" to "Techtree can
+run a Climb here": create the local layout, refuse early if a prerequisite is
+missing, install the engine this build ships, make it the active one, verify
+it, settle the local signing key, and say what to do next.
+
+The signing key is created here rather than on first use, and it is announced
+rather than assumed: a person running setup is asking this machine to be made
+ready, which is the moment to tell them a key exists, what it is for, and
+where each half of it goes.
+
+It does not install the Hermes plugin. ``--hermes`` is reserved so that the
+name means one thing when it does exist, and until then it says so.
+
+Prerequisites are checked before anything is downloaded. Finding out that the
+host is unsupported after a several-hundred-megabyte install would be a worse
+version of the same answer.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from techtree.cli.commands.engine import render_engine_status
+from techtree.cli.context import CliContext, cli_context
+from techtree.cli.invoke import CommandResult, invoke_command, not_implemented_error
+from techtree.doctor.service import DoctorService
+from techtree.engines.installer import (
+    EngineInstaller,
+    InterruptedInstall,
+    find_uv,
+)
+from techtree.engines.registry import EngineRegistry
+from techtree.errors import PrerequisiteError
+from techtree.identity.service import IdentityService
+from techtree.identity.store import IdentityStore
+from techtree.models.cli import CliMessage, MessageLevel, NextAction
+from techtree.models.engine import EngineStatus
+from techtree.paths import ensure_path_layout
+
+__all__ = ["LOCAL_SIGNING_KEY_NOTICE", "setup_command"]
+
+COMMAND = "setup"
+
+#: Spec section 7.5. Printed whenever setup settles this machine's identity,
+#: whether it made one or found one, because the sentence a person needs is
+#: what the key is for and where each half of it goes.
+#:
+#: The two halves used to be summarised as "the key is not uploaded", which was
+#: true and, since decisions 0038 built ``techtree publish``, is now the kind
+#: of sentence a reader could take further than it goes. A published proof
+#: carries the public half inside the envelopes it signs — that is what makes
+#: the signature checkable by somebody who does not trust us — so the notice
+#: says which half travels rather than implying neither does.
+LOCAL_SIGNING_KEY_NOTICE = (
+    "Techtree keeps a local signing key, used only to detect changes to your "
+    "local receipts. The private half never leaves the key directory. The "
+    "public half travels inside the proofs it signs, which is what lets "
+    "anybody check one.\n"
+    "Key: {key_id}"
+)
+
+
+def setup_command(
+    ctx: typer.Context,
+    hermes: Annotated[
+        bool,
+        typer.Option(
+            "--hermes",
+            help="Reserved for installing the Hermes plugin. Not available yet.",
+        ),
+    ] = False,
+) -> None:
+    """Prepare this machine to run a Climb."""
+    context = cli_context(ctx)
+
+    def action() -> CommandResult[EngineStatus]:
+        if hermes:
+            raise not_implemented_error("setup --hermes")
+
+        ensure_path_layout(context.paths)
+        _check_prerequisites(context)
+
+        registry = EngineRegistry(context.paths, context.settings)
+        installer = EngineInstaller(context.paths, registry, find_uv())
+
+        # Decisions 0004, ratified as 0007 R7: an install that was killed is
+        # found here, said out loud, and discarded by the install that
+        # follows. Reported before the install so the sentence a person reads
+        # is about the machine they left behind, not about this run.
+        interrupted = installer.interrupted_installs()
+        installed = installer.install()
+        registry.set_active(installed.digest)
+        status = installer.verify(installed.digest)
+        identity = IdentityService(IdentityStore(context.paths)).ensure()
+
+        return CommandResult(
+            data=status,
+            messages=[
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="local_signing_key",
+                    text=LOCAL_SIGNING_KEY_NOTICE.format(key_id=identity.key_id),
+                ),
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="setup_complete",
+                    text=(
+                        f"This machine is ready. Evaluation engine "
+                        f"{status.digest} is installed, verified, and active."
+                    ),
+                ),
+            ],
+            warnings=[_interrupted_notice(install) for install in interrupted],
+            next_actions=[_browse_climbs()],
+        )
+
+    invoke_command(context, COMMAND, action, render_data=_render)
+
+
+def _interrupted_notice(install: InterruptedInstall) -> CliMessage:
+    """Say that an earlier install did not finish, and what became of it."""
+    when = "" if install.started_at is None else f", started {install.started_at}"
+    return CliMessage(
+        level=MessageLevel.WARNING,
+        code="engine_install_interrupted",
+        text=(
+            f"An earlier install of evaluation engine {install.digest} did not "
+            f"finish{when}. What it left behind was removed and the engine was "
+            "installed again from scratch."
+        ),
+    )
+
+
+def _check_prerequisites(context: CliContext) -> None:
+    """Stop before installing anything if this host cannot run a Climb."""
+    doctor = DoctorService(context.paths, context.settings)
+    blocking = doctor.blocking_failures(doctor.run())
+    if not blocking:
+        return
+
+    identifiers = [check.id for check in blocking]
+    raise PrerequisiteError(
+        "this host is not ready to run a Climb: " + ", ".join(identifiers),
+        code="environment_not_ready",
+        details={"failed_checks": list(identifiers)},
+        next_actions=[_run_doctor()],
+    )
+
+
+def _render(data: object, console: Console) -> None:
+    if isinstance(data, EngineStatus):
+        render_engine_status(data, console)
+
+
+def _run_doctor() -> NextAction:
+    return NextAction(
+        id="run_doctor",
+        label="See what this machine is missing",
+        reason="Doctor lists every prerequisite and how to satisfy it.",
+        cli=["techtree", "doctor"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )
+
+
+def _browse_climbs() -> NextAction:
+    return NextAction(
+        id="list_climbs",
+        label="Browse the available Climbs",
+        reason="This host is ready.",
+        cli=["techtree", "climb", "list"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )

techtree/cli/commands/skill.py

@@ -0,0 +1,221 @@
+"""``techtree skill starter``. Spec section 10.5, decisions 0008.
+
+One command, and it does one thing: put the starter Skill this release pins
+on this machine, and say where it is. The guided first run needs a Skill
+before it can prepare anything, and until this command existed the only way
+to get one was for a person to already have the file.
+
+Run with no options it needs nothing from the caller at all: the release names
+both which Skill it measured and the address that Skill is published at, so
+``--from-file`` and ``--from-url`` are for the cases where somebody has a copy
+of their own. Whichever route the bytes take, they are proved against the
+release's digest before they are kept.
+
+What it returns goes through ``climb prepare`` like anybody else's Skill: the
+same scanner, the same policy, the same draft, the same confirmation. There is
+no privileged route for a Skill because a release named it — the release's
+authority is over *which* Skill, not over what Techtree will accept.
+
+The command writes only into the Techtree home. A materialized Skill is
+cached under the home's own cache directory, in a directory named by the
+digest it was verified against, so a second guided run reuses it and a cached
+directory somebody edited is re-verified rather than trusted.
+
+Decisions document 0010 item 5 governs what comes back. Where the Skill *is*,
+what it is *called*, and what a candidate carrying it is *labelled* are three
+separate values, and the answer states all three separately. They are not
+interchangeable and none of them is computed from another: a path is a fact
+about this machine, a name is the Skill's own, and a label is a short public
+string a comparison is filed under. Deriving any of the latter two from the
+first is how a cache directory's digest, a temporary directory, or a download
+URL ends up printed as the name of somebody's work.
+
+The answer also says what the Skill is *for*. Decisions document 0010 item 2
+rules that the starter Skill's own text stays silent about the gap it was
+written with, and that the release metadata discloses instead — the public
+Climb page, this command, and the calibration record all carry the same
+sentence. So the purpose is printed beside the name here: nobody is handed the
+starter Skill without being told it is an introductory one that is incomplete
+on purpose.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Final, Literal
+
+import typer
+from rich.console import Console
+
+from techtree.cli.context import cli_context
+from techtree.cli.invoke import CommandResult, invoke_command
+from techtree.cli.output import render_pairs
+from techtree.constants import (
+    STARTER_SKILL_CANDIDATE_LABEL,
+    STARTER_SKILL_NAME,
+    STARTER_SKILL_PURPOSE,
+)
+from techtree.models.base import Digest, NonEmptyString, ProtocolModel
+from techtree.models.cli import CliMessage, MessageLevel, NextAction
+from techtree.release.document import packaged_release_core_bytes, parse_release_core
+from techtree.skills.starter import MaterializedStarterSkill, StarterSkillService
+
+__all__ = [
+    "STARTER_COMMAND",
+    "StarterSkillPayload",
+    "starter_skill_command",
+]
+
+STARTER_COMMAND: Final = "skill starter"
+
+
+class StarterSkillPayload(ProtocolModel):
+    """Where the pinned starter Skill is, what it is called, and what it proved.
+
+    ``skill_path`` is where the Skill's entry file sits on this machine.
+    ``skill_name`` is what the Skill calls itself. ``candidate_label`` is what
+    a comparison carrying it is filed under. Decisions document 0010 item 5
+    keeps the three apart: a reader and a host agent both need to be able to
+    take the label without ever looking at the path.
+
+    ``skill_purpose`` is the fourth, and it is about the artifact rather than
+    about this machine: decisions document 0010 item 2 puts the starter
+    Skill's disclosure in the release metadata, so whoever is handed the Skill
+    is told what it is for before they run it.
+    """
+
+    release_id: NonEmptyString
+    skill_root_digest: Digest
+    skill_path: NonEmptyString
+    skill_name: NonEmptyString
+    skill_purpose: NonEmptyString
+    candidate_label: NonEmptyString
+    file_count: int
+    total_bytes: int
+    origin: Literal["cache", "local_file", "download", "release"]
+    intro_climb_reference: NonEmptyString
+
+
+def starter_skill_command(
+    ctx: typer.Context,
+    from_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--from-file",
+            metavar="PATH",
+            help="A local copy of the starter Skill: its directory or SKILL.md.",
+        ),
+    ] = None,
+    from_url: Annotated[
+        str | None,
+        typer.Option(
+            "--from-url",
+            metavar="URL",
+            help=(
+                "Where to fetch the starter Skill from, instead of the address "
+                "this release publishes it at."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """Put the starter Skill this release pins on this machine."""
+    context = cli_context(ctx)
+
+    def action() -> CommandResult[StarterSkillPayload]:
+        release = parse_release_core(packaged_release_core_bytes())
+        materialized = StarterSkillService(context.paths).materialize(
+            release=release, local_file=from_file, url=from_url
+        )
+        payload = StarterSkillPayload(
+            release_id=release.release_id,
+            skill_root_digest=materialized.root_digest,
+            skill_path=str(materialized.entrypoint),
+            skill_name=STARTER_SKILL_NAME,
+            skill_purpose=STARTER_SKILL_PURPOSE,
+            candidate_label=STARTER_SKILL_CANDIDATE_LABEL,
+            file_count=materialized.file_count,
+            total_bytes=materialized.total_bytes,
+            origin=materialized.origin,
+            intro_climb_reference=release.intro_climb_reference,
+        )
+        return CommandResult(
+            data=payload,
+            messages=[
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="starter_skill_ready",
+                    text=_summary(materialized),
+                )
+            ],
+            next_actions=[_prepare_action(payload)],
+        )
+
+    invoke_command(context, STARTER_COMMAND, action, render_data=_render)
+
+
+def _summary(materialized: MaterializedStarterSkill) -> str:
+    """Say in one sentence what happened and what was proved."""
+    how = {
+        "cache": "was already on this machine",
+        "local_file": "was read from the file you named",
+        "download": "was fetched from the source you named",
+        "release": "was fetched from the address this release publishes it at",
+    }[materialized.origin]
+    return (
+        f"The starter Skill {how} and matches the digest this release pins. "
+        "It is prepared the same way any other Skill is."
+    )
+
+
+def _prepare_action(payload: StarterSkillPayload) -> NextAction:
+    """Point at the ordinary preparation path, because that is the only one.
+
+    The label is stated rather than left to default. ``climb prepare`` falls
+    back to the skill directory's own name, and this Skill lives in a directory
+    named by the digest it was verified against: seventy-one characters, longer
+    than a label may be, and meaningless to a reader. Decisions document 0010
+    item 5 rules that out for good — the label here is the release's own short
+    name for the candidate, never anything read off the path beside it — and
+    naming it is also what makes these arguments runnable exactly as printed.
+    """
+    return NextAction(
+        id="prepare_starter_skill",
+        label="Prepare Techtree Hello World with the starter Skill",
+        reason=(
+            "The starter Skill is scanned, checked against the Climb's policy, "
+            "and shown to you before anything runs."
+        ),
+        cli=[
+            "techtree",
+            "climb",
+            "prepare",
+            payload.intro_climb_reference,
+            "--skill",
+            payload.skill_path,
+            "--label",
+            payload.candidate_label,
+        ],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=True,
+    )
+
+
+def _render(data: object, console: Console) -> None:
+    """Print where the Skill is and what it was verified against."""
+    if not isinstance(data, StarterSkillPayload):
+        return
+    render_pairs(
+        [
+            ("Release", data.release_id),
+            ("Skill", data.skill_name),
+            ("Purpose", data.skill_purpose),
+            ("Candidate label", data.candidate_label),
+            ("Skill content digest", data.skill_root_digest),
+            ("Skill file", data.skill_path),
+            ("Files", str(data.file_count)),
+            ("Size", f"{data.total_bytes} bytes"),
+            ("Obtained", data.origin.replace("_", " ")),
+        ],
+        console,
+    )