@ahmed-g-gad/apothem 0.1.1

package/src/apothem/cli/_json_formatter.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+
+"""JSON-output helper for the apothem CLI.
+
+Writes a single JSON document to stdout terminated by a newline, so
+shell consumers can ``jq .`` the result directly.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def emit_json(data: object) -> None:
+    """Serialize *data* to stdout as a JSON document followed by a newline.
+
+    Uses ``default=str`` so :class:`pathlib.Path` and other non-JSON-native
+    types round-trip to their string form rather than raising.
+    """
+    sys.stdout.write(json.dumps(data, default=str) + "\n")

package/src/apothem/cli/_materialize.py

@@ -0,0 +1,376 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared install/update materialization orchestrators.
+
+``_materialize`` drives a single-harness or batch install/update from the
+shared profile (blast-radius preview, placeholder advisory, fail-fast batch
+error handling — the first harness failure aborts the run and emits the
+partial result accumulated so far, lifecycle envelope);
+``_dry_run_materialization`` returns a
+no-write plan run. Both are consumed by the install / update / quickstart
+command modules. Patchable-helper call sites resolve through the
+``apothem.cli`` package (``_pkg``)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+import click
+
+import apothem.cli as _pkg
+from apothem.cli._common_flags import get_console
+from apothem.cli._helpers import (
+    _EXIT_EXPECTED,
+    _EXIT_PARTIAL,
+    _Adapter,
+    _adapter_resolve_output_path,
+    _CliUserError,
+    _emit_expected_error,
+    _invoke_with_project,
+    _lifecycle_envelope,
+    _load_profile,
+    _materialization_error,
+    _partition_blast_radius,
+    _placeholder_advisory_entry,
+    _placeholder_identity_fields,
+    _profile_error,
+    _render_blast_radius,
+    _resolve_profile_path,
+    _resolve_project_root,
+    _result_dicts,
+    _warning_dicts,
+)
+from apothem.cli._json_formatter import emit_json
+from apothem.harnesses._shared.install_driver import (
+    MaterializationError,
+    MaterializationResult,
+    MaterializationRun,
+)
+from apothem.lib.clean_slate import CleanSlateError, run_clean_slate
+from apothem.lib.profile import ProfileValidationError
+
+
+def _materialize(
+    harness: str,
+    profile: str | None,
+    dry_run: bool,
+    verb_present: str,
+    verb_past: str,
+    *,
+    fmt: str = "plain",
+    quiet: bool = False,
+    no_color: bool = False,
+    project: str | None = None,
+    clean: bool = False,
+    assume_yes: bool = False,
+    verbose: bool = False,
+    payload_sink: list[dict[str, object]] | None = None,
+) -> None:
+    """Install or update a harness adapter from the shared profile.
+
+    The command accepts a single harness id or ``all``. Profiles are
+    validated before dry-runs and writes, and JSON output always uses the
+    lifecycle envelope required by the product contract.
+    """
+    con = get_console(no_color=no_color, quiet=quiet)
+    profile_path = _resolve_profile_path(profile)
+    try:
+        project_root = _resolve_project_root(project)
+        shared_profile = _load_profile(profile_path)
+        selected = _pkg._selected_harness_ids(
+            harness,
+            shared_profile=shared_profile,
+            apply_excludes=harness.strip().lower() == "all",
+        )
+        _pkg._require_project_for_selection(selected, project_root)
+        adapters = [
+            (
+                harness_id,
+                _pkg._load_adapter_for_entry(_pkg.get_harness_entry(harness_id)),
+            )
+            for harness_id in selected
+        ]
+    except ProfileValidationError as exc:
+        _emit_expected_error(
+            command=verb_present,
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            error=_profile_error(exc),
+        )
+        return
+    except _CliUserError as exc:
+        _emit_expected_error(
+            command=verb_present,
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            error=exc.to_dict(),
+        )
+        return
+
+    # Opt-in clean-slate removal runs after the profile is loaded into memory
+    # (above) and before any fresh materialization below. The profile file is
+    # one of the bounded removal targets, so its bytes are captured here and
+    # restored after removal — the shared profile is the operator's identity
+    # source of truth, not stale install state, and the timestamped backup
+    # preserves every removed target for recovery.
+    if clean:
+        profile_bytes = profile_path.read_bytes() if profile_path.is_file() else None
+        try:
+            run_clean_slate(
+                Path.home(),
+                dry_run=dry_run,
+                assume_yes=assume_yes,
+                # Use the patchable seam (not raw sys.stdin.isatty()) so the
+                # clean-slate interactivity gate is test-reachable, matching the
+                # blast-radius confirmation below.
+                interactive=_pkg._stdin_is_interactive(),
+                echo=(con.print if fmt != "json" else None),
+            )
+        except CleanSlateError as exc:
+            _emit_expected_error(
+                command=verb_present,
+                fmt=fmt,
+                harness=harness,
+                profile_path=profile_path,
+                error=_CliUserError(
+                    code="clean_slate.refused",
+                    message="Clean-slate removal was refused.",
+                    field="clean",
+                    reason=str(exc),
+                    fix="Re-run interactively, pass --yes for non-interactive use, "
+                    "or correct the unsafe target before retrying.",
+                ).to_dict(),
+            )
+            return
+        if not dry_run and profile_bytes is not None:
+            profile_path.parent.mkdir(parents=True, exist_ok=True)
+            profile_path.write_bytes(profile_bytes)
+        if dry_run:
+            return
+
+    # Blast-radius disclosure (multi-harness install only). An ``all`` install
+    # fans out into mixed scopes: project-scope adapters write under --project,
+    # but user-scope adapters write under the operator's real home directory —
+    # a surprise worth disclosing before any byte is written. The grouped
+    # preview prints in plain mode; when the selection writes outside the
+    # supplied project root, an interactive confirmation guards the home-rooted
+    # writes. --yes, a non-interactive context, --dry-run, and --format json
+    # each bypass the prompt (dry-run and json still print/return the preview
+    # data without mutating). Single-named installs and update are out of scope.
+    if harness.strip().lower() == "all" and verb_present == "install" and fmt != "json":
+        within, outside = _partition_blast_radius(adapters, project_root)
+        _render_blast_radius(con, within, outside, project_root)
+        if not dry_run and outside and not assume_yes and _pkg._stdin_is_interactive():
+            click.confirm("Proceed and write these files?", abort=True)
+
+    all_files_written: list[str] = []
+    all_results: list[dict[str, object]] = []
+    all_warnings: list[dict[str, object]] = []
+
+    # Placeholder-identity advisory (install + update). When the loaded profile
+    # still carries the shipped scaffold identity, surface a single advisory so a
+    # fake identity is not silently projected — advisory only, never blocking
+    # (identity is never fabricated or coerced). It rides the JSON warnings array
+    # and prints once in plain mode, regardless of the harness selection.
+    placeholder_fields = _placeholder_identity_fields(shared_profile)
+    if placeholder_fields:
+        advisory = _placeholder_advisory_entry(profile_path, placeholder_fields)
+        all_warnings.append(advisory)
+        if fmt != "json":
+            con.print(f"[yellow]Note:[/] {advisory['message']}")
+    last_output_path: Path | None = None
+    last_materialization: MaterializationRun | None = None
+
+    for harness_id, adapter in adapters:
+        output_path = _adapter_resolve_output_path(adapter, project_root)
+        last_output_path = output_path
+        materialization: MaterializationRun | None
+
+        try:
+            if dry_run:
+                materialization = _dry_run_materialization(
+                    harness_id,
+                    adapter,
+                    output_path,
+                    project_root,
+                )
+            elif verb_present == "update":
+                maybe_run = _invoke_with_project(
+                    adapter.update,
+                    shared_profile,
+                    project=project_root,
+                )
+                materialization = (
+                    maybe_run if isinstance(maybe_run, MaterializationRun) else None
+                )
+            else:
+                maybe_run = _invoke_with_project(
+                    adapter.install,
+                    shared_profile,
+                    project=project_root,
+                )
+                materialization = (
+                    maybe_run if isinstance(maybe_run, MaterializationRun) else None
+                )
+        except MaterializationError as exc:
+            error = _materialization_error(exc, files_written=exc.run.files_written)
+            results = [*all_results, *_result_dicts(harness_id, exc.run)]
+            warnings = [*all_warnings, *_warning_dicts(harness_id, exc.run)]
+            files_written = [*all_files_written, *exc.run.files_written]
+            exit_code = _EXIT_PARTIAL if files_written else _EXIT_EXPECTED
+            _emit_expected_error(
+                command=verb_present,
+                fmt=fmt,
+                harness=harness,
+                profile_path=profile_path,
+                project_root=project_root,
+                error=error,
+                files_written=files_written,
+                results=results,
+                warnings=warnings,
+                exit_code=exit_code,
+            )
+            return
+        except NotImplementedError:
+            error = _CliUserError(
+                code="harness.not_implemented",
+                message="Apothem adapter is not implemented.",
+                field="harness",
+                reason=f"{harness_id} does not implement {verb_present}.",
+                fix="Choose another harness or update the adapter package.",
+            ).to_dict()
+            _emit_expected_error(
+                command=verb_present,
+                fmt=fmt,
+                harness=harness,
+                profile_path=profile_path,
+                project_root=project_root,
+                error=error,
+                files_written=all_files_written,
+                results=all_results,
+                warnings=all_warnings,
+                exit_code=_EXIT_PARTIAL if all_files_written else _EXIT_EXPECTED,
+            )
+            return
+        except _CliUserError as exc:
+            _emit_expected_error(
+                command=verb_present,
+                fmt=fmt,
+                harness=harness,
+                profile_path=profile_path,
+                project_root=project_root,
+                error=exc.to_dict(),
+                files_written=all_files_written,
+                results=all_results,
+                warnings=all_warnings,
+                exit_code=_EXIT_PARTIAL if all_files_written else _EXIT_EXPECTED,
+            )
+            return
+
+        last_materialization = materialization
+        if materialization is not None:
+            all_files_written.extend(materialization.files_written)
+        all_results.extend(_result_dicts(harness_id, materialization))
+        all_warnings.extend(_warning_dicts(harness_id, materialization))
+
+        if fmt != "json":
+            if materialization is not None and materialization.warnings:
+                if verbose:
+                    for warning in materialization.warnings:
+                        con.print(
+                            f"[yellow]Warning:[/] {harness_id} - {warning.message}"
+                        )
+                else:
+                    count = len(materialization.warnings)
+                    noun = "capability" if count == 1 else "capabilities"
+                    con.print(
+                        f"[dim]Note:[/] {harness_id} - {count} {noun} not "
+                        "projected; pass --verbose for detail"
+                    )
+            if dry_run:
+                con.print(
+                    f"[bold yellow]DRY RUN[/] would {verb_present} "
+                    f"[cyan]{harness_id}[/] -> {output_path}"
+                )
+            else:
+                con.print(
+                    f"[green]✓[/] {verb_past} [cyan]{harness_id}[/] -> {output_path}"
+                )
+
+    if fmt == "json":
+        status = "dry_run" if dry_run else "success"
+        action = "dry_run" if dry_run else verb_past.lower()
+        payload = _lifecycle_envelope(
+            status=status,
+            command=verb_present,
+            action=action,
+            harness=harness,
+            profile_path=profile_path,
+            project_root=project_root,
+            files_written=all_files_written,
+            results=all_results,
+            warnings=all_warnings,
+            output_path=last_output_path if len(adapters) == 1 else None,
+            materialization=last_materialization if len(adapters) == 1 else None,
+        )
+        # When a caller supplies a sink (the guided ``quickstart`` flow), hand it
+        # the success envelope instead of emitting, so the caller can fold it into
+        # one combined JSON summary rather than printing two documents.
+        if payload_sink is not None:
+            payload_sink.append(payload)
+        else:
+            emit_json(payload)
+    elif len(adapters) > 1 and not quiet:
+        con.print(
+            f"[green]✓[/] {verb_past} {len(adapters)} harnesses "
+            f"({len(all_files_written)} files written)."
+        )
+
+    if clean and not dry_run and fmt != "json" and not quiet:
+        verify_harness = harness if harness.strip().lower() != "all" else "all"
+        con.print(
+            "[bold]Next step:[/] confirm the fresh install with "
+            f"[cyan]apothem verify --harness {verify_harness}[/]"
+        )
+
+
+def _dry_run_materialization(
+    harness_id: str,
+    adapter: _Adapter,
+    output_path: Path,
+    project_root: Path | None,
+) -> MaterializationRun:
+    """Return a no-write materialization run using the adapter plan surface."""
+    plan_entries: list[dict[str, str]] = []
+    plan_fn = getattr(adapter, "plan", None)
+    if callable(plan_fn):
+        try:
+            candidate = _invoke_with_project(plan_fn, output_path, project=project_root)
+        except Exception as exc:
+            raise _CliUserError(
+                code="materialization.plan_failed",
+                message="Apothem dry-run planning failed.",
+                field="harness",
+                reason=str(exc),
+                fix="Check the harness adapter and project path before retrying.",
+            ) from exc
+        if isinstance(candidate, list):
+            plan_entries = cast("list[dict[str, str]]", candidate)
+    results = tuple(
+        MaterializationResult(
+            outcome="skipped",
+            operation=entry.get("mode", "plan"),
+            path=entry.get("target", str(output_path)),
+            source=entry.get("source"),
+            message="dry run: no filesystem changes made",
+        )
+        for entry in plan_entries
+    )
+    return MaterializationRun(
+        harness=_pkg.get_harness_entry(harness_id).package_key,
+        dry_run=True,
+        results=results,
+    )

package/src/apothem/cli/completions/apothem.bash

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+
+_apothem_completion() {
+    local IFS=$'\n'
+    local response
+
+    response=$(env COMP_WORDS="${COMP_WORDS[*]}" COMP_CWORD=$COMP_CWORD _APOTHEM_COMPLETE=bash_complete $1)
+
+    for completion in $response; do
+        IFS=',' read type value <<< "$completion"
+
+        if [[ $type == 'dir' ]]; then
+            COMPREPLY=()
+            compopt -o dirnames
+        elif [[ $type == 'file' ]]; then
+            COMPREPLY=()
+            compopt -o default
+        elif [[ $type == 'plain' ]]; then
+            COMPREPLY+=($value)
+        fi
+    done
+
+    return 0
+}
+
+_apothem_completion_setup() {
+    complete -o nosort -F _apothem_completion apothem
+}
+
+_apothem_completion_setup;

package/src/apothem/cli/completions/apothem.fish

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: MIT
+
+function _apothem_completion;
+    set -l response (env _APOTHEM_COMPLETE=fish_complete COMP_WORDS=(commandline -cp) COMP_CWORD=(commandline -t) apothem);
+
+    for completion in $response;
+        set -l metadata (string split "," $completion);
+
+        if test $metadata[1] = "dir";
+            __fish_complete_directories $metadata[2];
+        else if test $metadata[1] = "file";
+            __fish_complete_path $metadata[2];
+        else if test $metadata[1] = "plain";
+            echo $metadata[2];
+        end;
+    end;
+end;
+
+complete --no-files --command apothem --arguments "(_apothem_completion)";

package/src/apothem/cli/completions/apothem.ps1

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+
+# SPDX-License-Identifier: MIT
+# Apothem PowerShell completion stub.
+#
+# Click 8 does not ship a native PowerShell completer. Source this script
+# from your $PROFILE to register dynamic completion for `apothem`. It
+# shells out to the apothem binary with _APOTHEM_COMPLETE=powershell_complete
+# on each TAB, asking Click to compute the candidate list. If your apothem
+# entry-point is not on PATH, adjust the call path below.
+Register-ArgumentCompleter -Native -CommandName apothem -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+    $env:_APOTHEM_COMPLETE = "powershell_complete"
+    $env:COMP_WORDS = $commandAst.ToString()
+    $env:COMP_CWORD = $commandAst.CommandElements.Count - 1
+    $result = apothem 2>$null
+    Remove-Item Env:_APOTHEM_COMPLETE -ErrorAction SilentlyContinue
+    Remove-Item Env:COMP_WORDS         -ErrorAction SilentlyContinue
+    Remove-Item Env:COMP_CWORD         -ErrorAction SilentlyContinue
+    foreach ($line in $result -split "`n") {
+        if ($line) {
+            [System.Management.Automation.CompletionResult]::new(
+                $line, $line, "ParameterValue", $line
+            )
+        }
+    }
+}

package/src/apothem/cli/completions/apothem.zsh

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+
+#compdef apothem
+
+_apothem_completion() {
+    local -a completions
+    local -a completions_with_descriptions
+    local -a response
+    (( ! $+commands[apothem] )) && return 1
+
+    response=("${(@f)$(env COMP_WORDS="${words[*]}" COMP_CWORD=$((CURRENT-1)) _APOTHEM_COMPLETE=zsh_complete apothem)}")
+
+    for type key descr in ${response}; do
+        if [[ "$type" == "plain" ]]; then
+            if [[ "$descr" == "_" ]]; then
+                completions+=("$key")
+            else
+                completions_with_descriptions+=("$key":"$descr")
+            fi
+        elif [[ "$type" == "dir" ]]; then
+            _path_files -/
+        elif [[ "$type" == "file" ]]; then
+            _path_files -f
+        fi
+    done
+
+    if [ -n "$completions_with_descriptions" ]; then
+        _describe -V unsorted completions_with_descriptions -U
+    fi
+
+    if [ -n "$completions" ]; then
+        compadd -U -V unsorted -a completions
+    fi
+}
+
+if [[ $zsh_eval_context[-1] == loadautofunc ]]; then
+    # autoload from fpath, call function directly
+    _apothem_completion "$@"
+else
+    # eval/source/. command, register function for later
+    compdef _apothem_completion apothem
+fi

package/src/apothem/cli/reference_export.py

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: MIT
+
+"""Deterministic JSON exporter for source-generated documentation reference.
+
+Runnable as ``python -m apothem.cli.reference_export <kind>`` where ``<kind>``
+is one of ``cli`` or ``harnesses``. The emitter introspects Apothem's own Click
+command tree and harness registry — the single source of truth — so the
+generated reference pages cannot drift from the implementation.
+
+Output is a single JSON document with stable key order and sorted collections,
+so repeated runs against an unchanged tree are byte-identical.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+from apothem.cli import main as cli_main
+from apothem.lib.harness_registry import iter_harness_entries
+
+# Continuous-form CLI aliases (``Installing`` / ``installing`` and the
+# capitalized / lowercase ``Updating`` / ``Uninstalling`` variants) duplicate
+# the canonical lowercase verbs. They are excluded from the reference so each
+# command appears exactly once under its canonical name.
+_ALIAS_COMMAND_NAMES: frozenset[str] = frozenset(
+    {
+        "Installing",
+        "installing",
+        "Updating",
+        "updating",
+        "Uninstalling",
+        "uninstalling",
+    }
+)
+
+
+def _option_signatures(command: click.Command) -> list[str]:
+    """Return the sorted flag signatures declared by *command*.
+
+    Each entry is the comma-joined option declaration string (for example
+    ``--harness`` or ``-h, --help``). The implicit ``--help`` option Click adds
+    is included so the reference matches the observable CLI surface.
+    """
+    signatures: list[str] = []
+    for param in command.params:
+        if not isinstance(param, click.Option):
+            continue
+        signatures.append(", ".join(param.opts))
+    return sorted(signatures)
+
+
+def _command_entry(name: str, command: click.Command) -> dict[str, object]:
+    """Build the deterministic export record for one leaf command."""
+    return {
+        "name": name,
+        "flags": _option_signatures(command),
+        "description": (command.help or command.short_help or "").strip(),
+    }
+
+
+def _walk_commands(prefix: str, group: click.Group) -> list[dict[str, object]]:
+    """Recursively collect leaf-command records under *group*.
+
+    Sub-groups (``profile``, ``harnesses``) recurse so their subcommands are
+    emitted as ``profile show``, ``harnesses list``, and so on. Alias commands
+    are skipped at the top level.
+    """
+    entries: list[dict[str, object]] = []
+    for child_name in group.commands:
+        if not prefix and child_name in _ALIAS_COMMAND_NAMES:
+            continue
+        child = group.commands[child_name]
+        full_name = f"{prefix} {child_name}".strip()
+        if isinstance(child, click.Group):
+            entries.extend(_walk_commands(full_name, child))
+        else:
+            entries.append(_command_entry(full_name, child))
+    return entries
+
+
+def export_cli() -> dict[str, object]:
+    """Return the deterministic CLI command-and-flag export."""
+    commands = _walk_commands("", cli_main)
+    commands.sort(key=lambda entry: str(entry["name"]))
+    return {"kind": "cli", "commands": commands}
+
+
+def export_harnesses() -> dict[str, object]:
+    """Return the deterministic harness-adapter registry export."""
+    harnesses = [
+        {
+            "id": entry.public_id,
+            "display_name": entry.display_name,
+            "scope": entry.scope,
+            "output_format": entry.output_format,
+            "target_paths": sorted(entry.target_paths),
+        }
+        for entry in iter_harness_entries()
+    ]
+    harnesses.sort(key=lambda entry: str(entry["id"]))
+    return {"kind": "harnesses", "harnesses": harnesses}
+
+
+_EXPORTERS = {
+    "cli": export_cli,
+    "harnesses": export_harnesses,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Emit the requested export kind as deterministic JSON on stdout."""
+    args = sys.argv[1:] if argv is None else argv
+    if len(args) != 1 or args[0] not in _EXPORTERS:
+        kinds = ", ".join(sorted(_EXPORTERS))
+        sys.stderr.write(f"usage: python -m apothem.cli.reference_export <{kinds}>\n")
+        return 2
+    payload = _EXPORTERS[args[0]]()
+    sys.stdout.write(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())