adopt-cli 0.3.0__py3-none-any.whl

adopt_cli/commands/doctor.py

@@ -0,0 +1,99 @@
+"""`adopt doctor` -- contracts §14.
+
+Output: ``{config[{key, value, source}], environment{}, findings[]}``.
+Exit `0` when there are no findings, `4` when there are -- degraded success, not
+failure. `doctor` reports; it never repairs. A tool that quietly fixes what it
+finds destroys the evidence needed to work out why the problem occurred.
+"""
+
+import platform
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from adopt_cli.config import (
+    Resolution,
+    load_config_file,
+    project_config_path,
+    resolve_all,
+    user_config_path,
+)
+
+__all__ = ["build_payload", "collect_findings"]
+
+
+def collect_findings(resolutions: list[Resolution]) -> list[dict[str, str]]:
+    """Report, never repair."""
+    findings: list[dict[str, str]] = []
+    by_key = {r.key: r for r in resolutions}
+
+    offline = (by_key["ADOPT_OFFLINE"].value or "1").strip().lower()
+    if offline in {"0", "false", "no"}:
+        findings.append(
+            {
+                "severity": "warning",
+                "key": "ADOPT_OFFLINE",
+                "detail": (
+                    "Offline mode is disabled. The default posture is offline; network "
+                    "egress should be an explicit, per-invocation opt-in rather than a "
+                    "standing configuration setting."
+                ),
+            }
+        )
+
+    adapter = by_key["ADOPT_ADAPTER"].value
+    model = by_key["ADOPT_MODEL"].value
+    if adapter and not model:
+        findings.append(
+            {
+                "severity": "warning",
+                "key": "ADOPT_MODEL",
+                "detail": (
+                    f"Adapter {adapter!r} is configured but ADOPT_MODEL is unset, and no "
+                    "model identifier is hard-coded anywhere. The adapter will fail at "
+                    "construction with AGENT_ADAPTER_UNKNOWN."
+                ),
+            }
+        )
+
+    if model and not adapter:
+        findings.append(
+            {
+                "severity": "warning",
+                "key": "ADOPT_ADAPTER",
+                "detail": "ADOPT_MODEL is set but no adapter is configured; it will be ignored.",
+            }
+        )
+
+    return findings
+
+
+def build_payload(
+    *,
+    flags: Mapping[str, str] | None = None,
+    env: Mapping[str, str] | None = None,
+    cwd: Path | None = None,
+    home: Path | None = None,
+) -> tuple[dict[str, Any], list[dict[str, str]]]:
+    project_path = project_config_path(cwd)
+    user_path = user_config_path(home)
+    resolutions = resolve_all(
+        flags=flags,
+        env=env,
+        project=load_config_file(project_path),
+        user=load_config_file(user_path),
+    )
+    findings = collect_findings(resolutions)
+    payload: dict[str, Any] = {
+        "config": [r.render() for r in resolutions],
+        "environment": {
+            "python": platform.python_version(),
+            "platform": platform.platform(terse=True),
+            "executable": sys.executable,
+            "project_config": str(project_path) if project_path.exists() else None,
+            "user_config": str(user_path) if user_path.exists() else None,
+        },
+        "findings": findings,
+    }
+    return payload, findings

adopt_cli/commands/freshness.py

@@ -0,0 +1,60 @@
+"""`adopt freshness resolve --item ID` -- contracts §14.
+
+Emits `{state, level, deciding_rule}`. **The deciding rule is not decoration.**
+CUJ-5 requires an operator to be told *why* knowledge stopped being fresh --
+`observation_stale` because a webhook is failing is a different problem, with a
+different owner, from `stale` because the referent moved -- and a state with no
+reason cannot be acted on and cannot be argued with.
+
+Opens the store **read-only**. `resolve_freshness` writes nothing by contract
+(contracts §6), and a read-only handle is that guarantee expressed as a property
+of the file rather than as a rule the command has to remember.
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import open_configured_store
+from adopt_freshness import resolve_freshness
+
+__all__ = ["app"]
+
+app = typer.Typer(
+    name="freshness",
+    help="Resolve freshness across source, binding, knowledge-revision and system levels.",
+    no_args_is_help=True,
+)
+
+ItemOption = Annotated[
+    str,
+    typer.Option("--item", help="The knowledge item id.", show_default=False),
+]
+StoreOption = Annotated[
+    Path | None,
+    typer.Option("--store", help="Store path. Defaults to the resolved ADOPT_STORE_PATH."),
+]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+@app.command()
+def resolve(
+    item: ItemOption,
+    store: StoreOption = None,
+    json_output: JsonOption = False,
+) -> None:
+    """Resolve one item's freshness and report the rule that decided it."""
+    with open_configured_store(store, read_only=True) as handle:
+        resolution = resolve_freshness(handle.freshness_records(), item)
+
+    emit(
+        {
+            "state": resolution.state,
+            "level": resolution.level,
+            "deciding_rule": resolution.deciding_rule,
+        },
+        as_json=json_output,
+        title="adopt freshness resolve",
+    )

adopt_cli/commands/identity.py

@@ -0,0 +1,113 @@
+"""`adopt identity build | parse | validate` -- contracts §14.
+
+Three pure functions behind three commands. No store is opened and no socket is
+touched: a URI is a deterministic function of a scope path and a referent, which
+is what lets an integrator check one from a shell script, in a container, with no
+`.adopt/` directory anywhere.
+
+**Scope is given, not inferred.** `--scope firm/engagement/system/environment`
+is required, because every alternative is worse: reading it from a store makes a
+pure function depend on a file, and defaulting it means the tool silently builds
+a URI for a scope the caller did not name -- and a wrong URI is not a wrong
+answer, it is a *different referent*, which nothing downstream can detect.
+"""
+
+from typing import Annotated
+
+import typer
+
+from adopt_cli.json_out import emit
+from adopt_identity import build_uri, parse_uri, validate_uri
+from adopt_scope import Scope, ScopeNode, ScopePath
+
+__all__ = ["app"]
+
+app = typer.Typer(
+    name="identity",
+    help="Build, parse and validate identity URIs. Deterministic, offline, no store.",
+    no_args_is_help=True,
+)
+
+ScopeOption = Annotated[
+    str,
+    typer.Option(
+        "--scope",
+        help="firm/engagement/system/environment, as immutable slugs.",
+        show_default=False,
+    ),
+]
+KindOption = Annotated[str, typer.Option("--kind", help="The identity_kind.", show_default=False)]
+NamespaceOption = Annotated[
+    str | None,
+    typer.Option("--namespace", help="The namespace. Omit where the kind needs none."),
+]
+KeyOption = Annotated[
+    list[str],
+    typer.Option(
+        "--key",
+        help="The local key. Repeat for a multi-segment key such as a symbol path; "
+        "a single value is one segment, so any slash inside it is data.",
+        show_default=False,
+    ),
+]
+UriArgument = Annotated[str, typer.Argument(help="The identity URI.")]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+def _scope_from(path: str) -> Scope:
+    """A `Scope` carrying slugs only.
+
+    The ids are absent because this command never touches a store and the URI is
+    built from slugs alone (CR-05). They are set to the slug rather than to an
+    empty string so that anything which did misuse one fails visibly instead of
+    joining to a row that happens to have an empty id.
+    """
+    parsed = ScopePath.parse(path)
+    levels = (parsed.firm, parsed.engagement, parsed.system, parsed.environment)
+    nodes = tuple(None if slug is None else ScopeNode(id=slug, slug=slug) for slug in levels)
+    return Scope(
+        firm=nodes[0] or ScopeNode(id=parsed.firm, slug=parsed.firm),
+        engagement=nodes[1],
+        system=nodes[2],
+        # const-sync: ok -- positional index into the four scope levels.
+        environment=nodes[3],
+    )
+
+
+@app.command()
+def build(
+    scope: ScopeOption,
+    kind: KindOption,
+    key: KeyOption,
+    namespace: NamespaceOption = None,
+    json_output: JsonOption = False,
+) -> None:
+    """Build the canonical URI for a referent."""
+    uri = build_uri(_scope_from(scope), kind, namespace, tuple(key))
+    emit({"uri": uri}, as_json=json_output, title="adopt identity build")
+
+
+@app.command()
+def parse(uri: UriArgument, json_output: JsonOption = False) -> None:
+    """Parse a URI into its seven segments."""
+    parsed = parse_uri(uri)
+    emit(
+        {
+            "firm": parsed.firm,
+            "engagement": parsed.engagement,
+            "system": parsed.system,
+            "environment": parsed.environment,
+            "kind": parsed.kind,
+            "namespace": parsed.namespace,
+            "key": list(parsed.key),
+        },
+        as_json=json_output,
+        title="adopt identity parse",
+    )
+
+
+@app.command()
+def validate(uri: UriArgument, json_output: JsonOption = False) -> None:
+    """Check a URI against the grammar and canonical form. Exits 2 if it is not."""
+    validate_uri(uri)
+    emit({"uri": uri}, as_json=json_output, title="adopt identity validate")

adopt_cli/commands/init.py

@@ -0,0 +1,268 @@
+"""`adopt init` -- contracts §14.
+
+The one command that takes an FDE from "here is a client repository" to "here is
+a store with a scope, an archetype and an honest boundary", offline, in one step.
+
+**Scope is given, never inferred** -- the argument CR-32 already made for
+`adopt identity build`. Slugs are permanent (CR-05) and a URI built from a
+guessed scope is not a wrong answer but a *different referent*, which nothing
+downstream can detect. There is no scope key in `03` §3's config registry for the
+same reason.
+
+**Every scope level is idempotent on its slug.** Re-running `init` reuses a firm,
+engagement, system or environment that already exists rather than failing -- a
+slug is never reissued (CR-05), so resolving one is the correct reading of "it is
+already there". What is *not* reused is the boundary: re-running appends a new
+boundary row, because the answers may have changed and a boundary is a
+declaration with a date on it.
+
+**Exit codes carry the finding** (contracts §14 gives `0, 2, 3, 4`):
+
+* `2` -- detection was ambiguous. **Nothing is written**; `04` §4 forbids a guess.
+* `3` -- `T0`. The store, the scope and the boundary are recorded and `init` then
+  **refuses to proceed to capability planning** (PRD F10.6). A policy refusal,
+  because proceeding is precisely what is being declined.
+* `4` -- degraded with findings: an `ai` system below its `T3` floor. The setup
+  is usable and something needs a human.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Any, get_args
+
+import typer
+
+from adopt_cli.commands.boundary import answers_from_file
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import configured_store_path, open_or_create_store
+from adopt_detect import declare_boundary, negotiate, parse_answers, render_markdown
+from adopt_detect import detect as run_detect
+from adopt_detect.detect import DISAMBIGUATION_FLAG
+from adopt_model._enums import Archetype
+from adopt_obs import AdoptError, ErrorCode, ExitCode
+from adopt_scope import Scope, ScopeFacade, ScopePath
+
+__all__ = ["init"]
+
+PathArgument = Annotated[Path, typer.Argument(help="The tree to classify. Read, never executed.")]
+ScopeOption = Annotated[
+    str,
+    typer.Option(
+        "--scope",
+        help="firm/engagement/system/environment, as immutable slugs. All four are "
+        "required: a boundary is declared for one environment of one system.",
+        show_default=False,
+    ),
+]
+AnswersOption = Annotated[
+    Path,
+    typer.Option(
+        "--answers",
+        help="JSON file carrying the three qualification answers.",
+        show_default=False,
+    ),
+]
+ArchetypeOption = Annotated[
+    str | None,
+    typer.Option(
+        "--archetype",
+        help="Accept an archetype explicitly, when detection was ambiguous. This is the "
+        "human decision PRD §8 requires before an archetype is written -- there is no "
+        "confidence exemption and no flag that lets a proposal write itself.",
+    ),
+]
+StoreOption = Annotated[Path | None, typer.Option("--store", help="Store path override.")]
+StatementOption = Annotated[
+    Path | None,
+    typer.Option("--write-statement", help="Also write the human-readable boundary statement."),
+]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+@dataclass(frozen=True, slots=True)
+class _FullScope:
+    """Four slugs, all present. `ScopePath` allows a prefix; `init` does not."""
+
+    firm: str
+    engagement: str
+    system: str
+    environment: str
+
+    def prefix(self, depth: int) -> ScopePath:
+        """The path naming the first `depth` levels."""
+        levels: tuple[str | None, ...] = (self.firm, self.engagement, self.system, self.environment)
+        padded = tuple(level if index < depth else None for index, level in enumerate(levels))
+        return ScopePath(
+            firm=self.firm,
+            engagement=padded[1],
+            system=padded[2],
+            # const-sync: ok -- positional indexes into the four scope levels.
+            environment=padded[3],
+        )
+
+
+def _require_full_scope(scope: str) -> _FullScope:
+    parsed = ScopePath.parse(scope)
+    if parsed.engagement is None or parsed.system is None or parsed.environment is None:
+        raise AdoptError(
+            ErrorCode.SCOPE_SLUG_INVALID,
+            message=f"--scope {scope!r} does not name all four levels",
+            hint="A boundary is declared for one environment of one system, and every "
+            "identity URI carries an environment (contracts §4). Pass "
+            "`firm/engagement/system/environment`.",
+        )
+    return _FullScope(parsed.firm, parsed.engagement, parsed.system, parsed.environment)
+
+
+def _resolves(scopes: ScopeFacade, path: ScopePath) -> Scope | None:
+    """The resolved scope, or `None` when a level in it does not exist yet.
+
+    Existence is tested by resolving and catching, because `ScopeFacade` exposes
+    no `find_*`. Widening the facade for a CLI convenience would put a second
+    lookup path beside the one the slug rules are enforced on, and the rules --
+    validity, immutability, no reissue -- all live on the creation path.
+    """
+    try:
+        return scopes.resolve(path)
+    except AdoptError as error:
+        if error.code is ErrorCode.SCOPE_SLUG_INVALID:
+            return None
+        raise
+
+
+def _ensure_scope(scopes: ScopeFacade, wanted: _FullScope, archetype: Archetype | None) -> Scope:
+    """Create whichever levels are missing, reuse the rest, return the full scope."""
+    if _resolves(scopes, wanted.prefix(1)) is None:
+        scopes.create_firm(slug=wanted.firm, name=wanted.firm)
+    firm_scope = scopes.resolve(wanted.prefix(1))
+
+    if _resolves(scopes, wanted.prefix(2)) is None:
+        scopes.create_engagement(
+            firm_id=firm_scope.firm.id, slug=wanted.engagement, name=wanted.engagement
+        )
+    engagement_scope = scopes.resolve(wanted.prefix(2))
+    assert engagement_scope.engagement is not None  # noqa: S101 -- just resolved at depth 2
+
+    # const-sync: ok -- scope depth 3 (firm/engagement/system), not SCHEMA_VERSION.
+    if _resolves(scopes, wanted.prefix(3)) is None:
+        scopes.create_system(
+            engagement_id=engagement_scope.engagement.id,
+            slug=wanted.system,
+            name=wanted.system,
+            archetype=archetype,
+        )
+    # const-sync: ok -- scope depth 3 (firm/engagement/system), not SCHEMA_VERSION.
+    system_scope = scopes.resolve(wanted.prefix(3))
+    assert system_scope.system is not None  # noqa: S101 -- just resolved at depth 3
+
+    if _resolves(scopes, wanted.prefix(4)) is None:
+        scopes.create_environment(
+            system_id=system_scope.system.id, slug=wanted.environment, name=wanted.environment
+        )
+    return scopes.resolve(wanted.prefix(4))
+
+
+def _accepted_archetype(named: str | None) -> Archetype | None:
+    """Validate an operator-supplied archetype against the canonical vocabulary.
+
+    Checked against the **generated** `Archetype` literal rather than a list held
+    here, so the vocabulary has one home (`02` §2.1) and adding an archetype to the
+    manifest cannot leave this command rejecting it.
+
+    A typo is refused rather than stored: `system.archetype` is what decides which
+    extractors a downstream item runs, so `--archetype wbe` writing an unknown
+    value would be a *different referent* rather than a slightly wrong one -- the
+    argument CR-32 made for scope, applied to the one other field an operator
+    types by hand.
+    """
+    if named is None:
+        return None
+    canonical = get_args(Archetype)
+    if named not in canonical:
+        raise AdoptError(
+            ErrorCode.DETECT_AMBIGUOUS,
+            message=f"--archetype {named!r} is not one of {', '.join(canonical)}",
+            hint="`02` §2.1 fixes the archetype vocabulary, and a value outside it "
+            "would decide which extractors run for this system. Nothing was created.",
+        )
+    accepted: Archetype = named  # type: ignore[assignment]  # membership just checked
+    return accepted
+
+
+def init(
+    path: PathArgument = Path(),
+    scope: ScopeOption = "",
+    answers: AnswersOption = Path("answers.json"),
+    archetype: ArchetypeOption = None,
+    store: StoreOption = None,
+    write_statement: StatementOption = None,
+    json_output: JsonOption = False,
+) -> None:
+    """Create a store, resolve a scope, detect the archetype and declare the boundary."""
+    wanted = _require_full_scope(scope)
+    decision = negotiate(parse_answers(answers_from_file(answers)))
+
+    # Detection runs **before** the store is created, so an ambiguous tree leaves
+    # nothing behind. A store created and then abandoned is exactly the empty
+    # database beside the real one that `store_option` already refuses to make.
+    result = run_detect(path)
+    accepted = _accepted_archetype(archetype)
+    if result.ambiguous and accepted is None:
+        raise AdoptError(
+            ErrorCode.DETECT_AMBIGUOUS,
+            message=f"confidence {result.confidence} is below the threshold; nothing was created",
+            hint=f"Run `adopt detect {path}` for the ranked scores and the rules that "
+            f"fired. Narrow the path to one system, or set {DISAMBIGUATION_FLAG}=1 for a "
+            f"proposal and re-run with `--archetype <a>` to accept it. "
+            f"Detection does not guess: a wrong archetype is a different set of "
+            f"extractors, not a slightly wrong answer.",
+        )
+    # **The operator's value wins, and that is the whole human-accept step.** PRD §8
+    # requires human approval for writing an archetype with no confidence
+    # exemption, so a named `--archetype` overrules detection rather than merely
+    # unblocking it -- an operator who has read a proposal, or who simply knows the
+    # system, is the authority the matrix names. `archetype_source` records which
+    # of the two the row came from, because "who decided this" is exactly the
+    # question an audit asks of a system that can propose.
+    effective = accepted if accepted is not None else result.archetype
+    archetype_source = "operator" if accepted is not None else "detected"
+
+    store_path = configured_store_path(store)
+    with open_or_create_store(store) as handle:
+        resolved = _ensure_scope(handle.scope(), wanted, effective)
+        view = declare_boundary(
+            handle.boundary(), scope=resolved, decision=decision, archetype=effective
+        )
+        payload: dict[str, Any] = {
+            "store_path": str(store_path),
+            "scope": {
+                "firm": wanted.firm,
+                "engagement": wanted.engagement,
+                "system": wanted.system,
+                "environment": wanted.environment,
+            },
+            "archetype": effective,
+            "archetype_source": archetype_source,
+            "tier": view.tier,
+            "schema_version": handle.schema_version,
+            "boundary_id": view.boundary_id,
+            "unavailable_capabilities": list(view.unavailable_capabilities),
+        }
+
+    if write_statement is not None:
+        write_statement.write_text(render_markdown(view), encoding="utf-8", newline="\n")
+        payload["statement_path"] = str(write_statement)
+
+    emit(payload, as_json=json_output, title="adopt init")
+
+    if view.decline_recommended:
+        raise AdoptError(
+            ErrorCode.TIER_DECLINE_RECOMMENDED,
+            message="T0: no artifact access, so no claim this platform makes could be "
+            "supported by evidence from this system",
+            hint="The store, the scope and the boundary are recorded so the decision is "
+            "auditable, and setup stops here. Re-run with different answers if "
+            "artifact access is arranged.",
+        )
+    if view.archetype_floor_violated:
+        raise typer.Exit(ExitCode.DEGRADED_WITH_FINDINGS)

adopt_cli/commands/interchange.py

@@ -0,0 +1,92 @@
+"""`adopt export DIR` and `adopt import DIR --into PATH` — contracts §14.
+
+Both emit the one envelope §14 declares for the pair --
+`{bundle_path, export_version, tables[], bytes}` -- because they are two
+directions of one operation and an integrator comparing what was written against
+what was applied should not have to reconcile two shapes.
+
+Exit codes are §13's, derived from the error's category and never chosen here: a
+policy refusal (`EXPORT_SCOPE_AMBIGUOUS`, `EXPORT_VERSION_UNSUPPORTED`,
+`EXPORT_TARGET_NOT_EMPTY`) exits `3`, an integrity failure
+(`EXPORT_DIGEST_MISMATCH`, `EXPORT_BUNDLE_MALFORMED`) exits `1`.
+
+**Export opens the store read-only and import opens its target for writing.**
+Neither needs saying twice: the direction of the operation decides it, and a
+read-only export is what makes "exporting cannot change what you exported"
+structural rather than remembered.
+
+The two commands live in one module because they share the envelope and the
+`--json` flag; they are registered as separate top-level commands rather than a
+`adopt interchange` group, because §14 names them `adopt export` and
+`adopt import`.
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import open_configured_store, open_named_store, writer_identity
+from adopt_export import BundleManifest, apply_bundle, table_relative_path, write_bundle
+
+__all__ = ["export", "import_"]
+
+BundleArgument = Annotated[
+    Path, typer.Argument(metavar="DIR", help="The bundle directory.", show_default=False)
+]
+StoreOption = Annotated[
+    Path | None,
+    typer.Option("--store", help="Store path. Defaults to the resolved ADOPT_STORE_PATH."),
+]
+IntoOption = Annotated[
+    Path,
+    typer.Option("--into", help="The store to restore into. Created empty if absent."),
+]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+def _bytes_on_disk(bundle_path: Path, manifest: BundleManifest) -> int:
+    """Total size of the table files the manifest names.
+
+    The table files and nothing else: `bytes` describes the payload an
+    integrator moves, and counting the manifest and the JSON schema would make
+    the number change whenever a comment in the schema did.
+    """
+    return sum(
+        (bundle_path / table_relative_path(entry.name)).stat().st_size for entry in manifest.tables
+    )
+
+
+def _payload(bundle_path: Path, manifest: BundleManifest) -> dict[str, object]:
+    return {
+        "bundle_path": str(bundle_path),
+        "export_version": manifest.export_version,
+        "tables": [
+            {"name": entry.name, "rows": entry.rows, "sha256": entry.sha256}
+            for entry in manifest.tables
+        ],
+        "bytes": _bytes_on_disk(bundle_path, manifest),
+    }
+
+
+def export(
+    directory: BundleArgument,
+    store: StoreOption = None,
+    json_output: JsonOption = False,
+) -> None:
+    """Write a portable bundle of every exportable table."""
+    with open_configured_store(store, read_only=True) as handle:
+        manifest = write_bundle(handle.export_records(), directory, written_by=writer_identity())
+    emit(_payload(directory, manifest), as_json=json_output, title="adopt export")
+
+
+def import_(
+    directory: BundleArgument,
+    into: IntoOption,
+    json_output: JsonOption = False,
+) -> None:
+    """Verify a bundle whole, then restore it into an empty store."""
+    with open_named_store(into, migrate=True) as handle:
+        manifest = apply_bundle(handle.import_records(), directory)
+    emit(_payload(directory, manifest), as_json=json_output, title="adopt import")