sayfirst-cli 0.2.0__py3-none-any.whl

sayfirst_cli/exit_codes.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+"""One process exit code per thing that can come back, all of them distinct.
+
+Article 1 names this file's guard: "The project's client renders 'denied' and
+'could not ask' as distinct results with distinct exit codes, and a test holds
+them apart." Article 2 is why the list is longer than two: an answer, a refusal
+of the question and an unanswerable question are three different facts, and a
+shell that collapses them into "non-zero" has lost the one distinction the
+constitution insists on.
+
+Three of these codes are not this repository's to choose. `sayfirst whoami`,
+which the contract distribution implements, already publishes `0`, `3`, `4` and
+`64` for the same four situations; a second client of the same contract that
+numbered them differently would make the same event read two ways depending on
+which subcommand produced it. So they are taken as given; the codes for the
+three outcomes and the local checks are added here.
+
+Article 1 also keeps a local check apart from an answer. A broken chain or a
+contradicted verdict is something this client found, not a denial the plane
+gave. A check that cannot conclude is not a failure to ask the plane either:
+the record may have arrived, while its version or coverage prevents a check.
+
+`2` is absent on purpose: `argparse` exits with it on a usage error it rejects
+itself, before any of this runs. Claiming it for an outcome would make a
+mistyped flag indistinguishable from an answer.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+#: The control plane answered `allow`. The only code that means "go ahead".
+EXIT_ALLOW: Final[int] = 0
+
+#: The control plane answered `deny`. An answer, not a failure to obtain one.
+EXIT_DENY: Final[int] = 1
+
+#: The request was refused — the question was received and rejected.
+#: The value `sayfirst whoami` publishes for the same situation.
+EXIT_REFUSED: Final[int] = 3
+
+#: The control plane could not be asked, or answered something this generation
+#: cannot read. Never rendered as a denial (articles 1 and 2). The value
+#: `sayfirst whoami` publishes for the same situation.
+EXIT_COULD_NOT_ASK: Final[int] = 4
+
+#: The control plane answered `suspend`: the effect waits for a person.
+EXIT_SUSPEND: Final[int] = 5
+
+# A successful read exits 0 without another zero-valued name in CODES: a read's
+# success is not an outcome; the record's own outcome is data, not permission.
+#: A local verification found what the plane did not say: a broken chain, an
+#: undeclared gap, a manifest that does not recompute, or a served verdict the
+#: local check contradicts. A finding, never a denial (article 1).
+EXIT_CHECK_FAILED: Final[int] = 6
+
+#: The local check could not conclude: an unknown preimage or manifest version,
+#: or insufficient coverage. An unknown check, not an unanswerable question.
+EXIT_COULD_NOT_CHECK: Final[int] = 7
+
+#: The invocation was wrong, or something it named cannot be read — a profile
+#: that cannot say what it must verify, a pack manifest that does not parse, a
+#: pack this distribution ships that will not read. The value `sayfirst whoami`
+#: publishes for the same situation; `packs list` uses it for a broken shipped
+#: pack rather than minting a code for a case no caller can act on differently,
+#: because a distinct number would cost one in a table three commands share and
+#: the paragraph above says why the numbers here are not this repository's alone
+#: to choose. « The invocation was wrong » is a stretch for a pack the
+#: DISTRIBUTION ships, and it is the honest half of the answer: the caller typed
+#: nothing wrong, and something the command named cannot be read.
+EXIT_MISUSE: Final[int] = 64
+
+#: The code `argparse` uses for a usage error it rejects itself. Reserved
+#: rather than assigned, so that nothing here can collide with it.
+EXIT_PARSER_USAGE: Final[int] = 2
+
+#: Every code this client can exit with, by the name of what it means.
+CODES: Final[dict[str, int]] = {
+    "allow": EXIT_ALLOW,
+    "deny": EXIT_DENY,
+    "refused": EXIT_REFUSED,
+    "could_not_ask": EXIT_COULD_NOT_ASK,
+    "suspend": EXIT_SUSPEND,
+    "check_failed": EXIT_CHECK_FAILED,
+    "could_not_check": EXIT_COULD_NOT_CHECK,
+    "misuse": EXIT_MISUSE,
+    "parser_usage": EXIT_PARSER_USAGE,
+}

sayfirst_cli/explain.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Read a decision's reason, rule and policy version in the plane's own words."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from typing import TextIO
+
+from . import reads, render
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sayfirst explain", description="Read the record and reason of a decision."
+    )
+    reads.add_connection_arguments(parser)
+    parser.add_argument("--decision", required=True, help="the reference of the recorded decision")
+    return parser
+
+
+def main(
+    argv: Sequence[str] | None = None, *, out: TextIO | None = None, err: TextIO | None = None
+) -> int:
+    stdout, stderr = out or sys.stdout, err or sys.stderr
+    arguments = build_parser().parse_args(argv)
+    connection = reads.open_connection(arguments, stderr)
+    if isinstance(connection, int):
+        return connection
+    try:
+        result = reads.read(lambda: connection.read_decision(arguments.scope, arguments.decision))
+        return reads.finish(result, arguments, connection, stdout, stderr, render.write_record)
+    finally:
+        connection.close()

sayfirst_cli/instrument/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The instrumentation chain's client side: the manifest, the engine, the verifier.
+
+Article 9 says the open project ships the instrumentation engine, the
+instrumentation verifier and the convenience packs. Two of the three live here.
+
+Layer 1 is `manifest`, `engine` and `launch`: they read what a pack declares,
+install it in front of the named operations, and hand the program over. Layer 3
+is `verify` and `harness`: they run the program again under the interpreter's
+own audit hook and ask the daemon's chain whether every effect of a named kind
+was decided. The two do not meet — the verifier consumes audit events and
+evidence and nothing the engine kept — because a proof that trusts the thing it
+is proving is not a proof.
+"""

sayfirst_cli/instrument/commands.py

@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sayfirst instrument`: run somebody's program with the boundary in front of it.
+
+Three verbs, because one word cannot carry two meanings. Article 9 writes
+« `sayfirst instrument apply` executes it » while also making runtime
+interposition the primary mode and a committed code modification a later option
+— and a verb that undoes itself when the process ends is not the same act as a
+verb that edits somebody's repository. `apply` is the ordinary name for the
+second, so it keeps the article's name for the article's later option and says,
+in as many words, that it is not that option yet (the architecture reading of
+2026-09-14). Nothing is renamed into meaning its opposite, and a reader who
+disagrees has an amendment to write rather than a redefinition to find in code.
+
+The codes this command produces come from two places and never a third: the
+invocation's own mistakes, which are this client's to report, and the governed
+program's ending, which is the program's and is passed through untouched.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Final, TextIO
+
+from sayfirst_contract.client import Refused
+from sayfirst_contract.generation import CONTRACT_GENERATION
+from sayfirst_contract.transport.socket_client import (
+    PER_USER,
+    SYSTEM,
+    ProfileMisuse,
+    SocketClientProblem,
+    SocketProfile,
+)
+
+from .. import exit_codes, reads, render
+from . import engine, launch, manifest, verify
+
+#: What `apply` says instead of doing anything. The sentence names the mode that
+#: does exist, because a refusal that leaves the reader with no next step is
+#: only half of what article 2 asks of an absence.
+APPLY_REFUSAL: Final[str] = (
+    "instrument apply is reserved for the committed code modification, which does not "
+    "exist yet; use `instrument run`, the reversible mode (architecture reading, 2026-09-14)"
+)
+
+#: The verbs that do nothing, and the sentence each says instead. They are
+#: answered before the parser reads their arguments, because they refuse the
+#: ACT: a usage error about an option would suggest that some other spelling of
+#: the same act would be accepted, and none would. `verify` left this table
+#: when the verifier arrived; `apply` stays until the committed code
+#: modification does.
+RESERVED: Final[dict[str, str]] = {"apply": APPLY_REFUSAL}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Every verb this command answers, and only the ones it answers."""
+    parser = argparse.ArgumentParser(
+        prog="sayfirst instrument",
+        description="Run a program with the sayfirst boundary in front of named effects.",
+    )
+    verbs = parser.add_subparsers(dest="verb", required=True)
+    running = verbs.add_parser("run", help="run a program with the designated packs installed")
+    running.add_argument(
+        "--pack",
+        action="append",
+        required=True,
+        metavar="DIR",
+        help="a pack directory; repeat the option for each pack",
+    )
+    running.add_argument("--scope", required=True, help="the scope the questions are asked in")
+    running.add_argument("--socket", required=True, help="the path of the daemon's socket")
+    running.add_argument("--mode", choices=(PER_USER, SYSTEM), default=PER_USER)
+    running.add_argument(
+        "--daemon-user",
+        default=None,
+        help="the account the daemon runs as; a system profile names it",
+    )
+    running.add_argument(
+        "--principal",
+        default=None,
+        metavar="REF",
+        help="the principal reference to hold grants against; this account by default",
+    )
+    running.add_argument(
+        "target",
+        nargs="*",
+        metavar="TARGET",
+        help="after `--`: either -m MODULE [args] or SCRIPT [args]",
+    )
+    verify.add_arguments(
+        verbs.add_parser("verify", help="prove every named effect of a program was decided")
+    )
+    # Declared so that `--help` names every verb this command answers, article 2's
+    # rule about a help text being a claim. `main` answers this one before the
+    # parser is asked to read anything after it.
+    verbs.add_parser("apply", help="the committed code modification (reserved; it refuses)")
+    return parser
+
+
+def main(
+    argv: Sequence[str] | None = None, *, out: TextIO | None = None, err: TextIO | None = None
+) -> int:
+    """Run the verb and return the code the calling shell should see."""
+    stdout = out or sys.stdout
+    stderr = err or sys.stderr
+    forwarded = list(sys.argv[1:] if argv is None else argv)
+    if forwarded and forwarded[0] in RESERVED:
+        stderr.write(f"{RESERVED[forwarded[0]]}\n")
+        return exit_codes.EXIT_MISUSE
+    return _run(build_parser().parse_args(forwarded), stdout, stderr)
+
+
+def _run(arguments: argparse.Namespace, stdout: TextIO, stderr: TextIO) -> int:
+    """Read the packs, open the profile, and hand the program over.
+
+    Everything that can be wrong with the invocation is found before a single
+    attribute is replaced — with the one exception the engine names: an
+    attribute a pack declares on a module the program only imports later
+    cannot be checked before that import, and is refused when it happens. A
+    program half instrumented would be running partly governed with nothing
+    saying which part, which is worse than not running.
+    """
+    if arguments.verb == "verify":
+        # Layer 3 owns its own codes: they are about the proof, never about the
+        # program's ending, which `run` below is the one that passes through.
+        return verify.run(arguments, stdout, stderr)
+    packs: list[manifest.Pack] = []
+    for named in arguments.pack:
+        try:
+            packs.append(manifest.read_pack(Path(named)))
+        except manifest.PackInvalid as invalid:
+            # The path as it was TYPED, not as it was resolved: with more than
+            # one `--pack` the sentence alone does not say which one to fix, and
+            # a resolved path is not what the reader has in their shell history.
+            stderr.write(f"{named}: {invalid}\n")
+            return exit_codes.EXIT_MISUSE
+    try:
+        profile = SocketProfile(
+            arguments.socket,
+            mode=arguments.mode,
+            daemon_user=arguments.daemon_user,
+            scope=arguments.scope,
+        )
+    except ProfileMisuse as invalid:
+        stderr.write(f"{invalid}\n")
+        return exit_codes.EXIT_MISUSE
+    try:
+        return launch.run(
+            packs,
+            profile,
+            arguments.target,
+            principal=arguments.principal,
+            out=stdout,
+            err=stderr,
+        )
+    except launch.LaunchMisuse as misuse:
+        # Everything the launcher refuses BEFORE the hand-off: a point the
+        # engine will not install, an execution module that will not load, a
+        # target that names no program. The program has not started, so this is
+        # the invocation's mistake and not an outcome about an effect.
+        stderr.write(f"{misuse}\n")
+        return exit_codes.EXIT_MISUSE
+    except engine.EngineMisuse as misuse:
+        # A point naming an attribute a module does not have, discovered inside
+        # the program's own import — the one check that cannot be made before
+        # the hand-off (the engine says why). The pack is the invocation's and
+        # the program is innocent: no question was ever put, so it is 64, the
+        # same answer this file already gives the byte-identical shape of a
+        # `-m` name that resolves to a package with no `__main__`. Uncaught, it
+        # reached a shell as a traceback and exit 1, this client's published
+        # code for « deny », over a mistake the plane was never asked about.
+        stderr.write(f"{misuse}\n")
+        return exit_codes.EXIT_MISUSE
+    except SocketClientProblem as failure:
+        # Raised while the connection was being arranged, so no question was
+        # ever put. It is reported with the contract's own classification and
+        # never as a denial (articles 1 and 2); a refusal the boundary raises
+        # later, inside the program, is the program's and is not caught here.
+        return _write_problem(failure, stderr)
+
+
+def _write_problem(failure: SocketClientProblem, stderr: TextIO) -> int:
+    """A non-answer, said as the reads say it, with the code the reads use."""
+    result = reads.connection_problem(failure)
+    could_not_ask = not isinstance(result, Refused)
+    render.write_problem(
+        result.problem.to_document(CONTRACT_GENERATION), stderr, could_not_ask=could_not_ask
+    )
+    return exit_codes.EXIT_COULD_NOT_ASK if could_not_ask else exit_codes.EXIT_REFUSED