evo-cli 0.17.0__tar.gz → 0.19.0__tar.gz

{evo_cli-0.17.0 → evo_cli-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evo_cli
-Version: 0.17.0
+Version: 0.19.0
 Summary: Evolution CLI - a developer toolbox for setting up dev machines
 Author: maycuatroi
 Project-URL: Homepage, https://github.com/maycuatroi/evo-cli
@@ -159,6 +159,21 @@ else has the flat file open.
 
 #### Harness Repositories
 
+Clone every repository a harness manifest declares but this machine does not have yet:
+
+```bash
+evo harness clone
+evo harness clone --dry-run                     # show what lands where, change nothing
+evo harness clone --repo backend --depth 1
+evo harness clone --all                         # include repos marked present: false
+```
+
+Each repo lands on its declared `path`, falling back to `<workspace>/<name>`, so a fresh machine
+ends up with the layout the manifest, the contract seams and the exec-plans already assume. A repo
+already on disk is left alone; if its `origin` is not the remote the manifest names, the summary
+says so instead of touching it. When the manifest names a `branch`, the clone moves onto it, and a
+branch nobody has pushed yet is reported rather than treated as a failure.
+
 Fast-forward every available repository declared in a harness manifest:
 
 ```bash
@@ -235,6 +250,52 @@ to disk and the command warns.
 The same engine backs the `evo-tts` MCP server in
 [agent-skills](https://github.com/maycuatroi1/agent-skills), which gives an agent a `speak` tool.
 
+#### Google Search (SerpApi)
+
+Search Google from the terminal through [SerpApi](https://serpapi.com). One-time setup installs the
+official `serpapi` CLI and stores the key in the omelet credential store:
+
+```bash
+evo setup serp                        # install the CLI + prompt for the key (no echo)
+evo setup serp --from-stdin < key.txt # non-interactive
+evo setup serp --method none          # key only; searches use the HTTPS API
+```
+
+`--method auto` (the default) tries Homebrew first, then falls back to the GitHub release binary
+dropped into `~/.evo/bin`. Homebrew 5 refuses to build from an untrusted third-party tap, so the
+brew path needs `evo setup serp --trust-tap` (which runs `brew trust --formula
+serpapi/tap/serpapi-cli`); without it the fallback fetches the same official binary.
+
+```bash
+evo serp search "evo cli python"                     # top 10 Google results
+evo serp search coffee -l "Austin, Texas" -n 5       # localized
+evo serp search openai -t news --hl vi --gl vn       # news vertical, Vietnamese
+evo serp search "site:github.com serpapi" --links    # only URLs, pipe-friendly
+evo serp search "rust async" -p 3 --json > out.json  # 3 merged pages of raw JSON
+evo serp search x -P tbs=qdr:d                       # any extra SerpApi parameter
+```
+
+`-t` picks the vertical (`web`, `news`, `images`, `videos`, `shopping`, `scholar`). Google treats
+`num` as a hint and often returns more, so the rendered output is capped at what `-n` asked for
+while `--json` / `-o` keep the full payload.
+
+Supporting commands:
+
+```bash
+evo serp account            # plan, searches used and left this month
+evo serp locations Hanoi    # canonical names to pass to --location
+evo serp doctor             # binary, key source (masked), remaining quota
+evo serp raw search --jq '.organic_results[0]' engine=google q=coffee
+```
+
+`search` runs through the `serpapi` binary when it is installed and falls back to the SerpApi HTTPS
+endpoint otherwise, so a machine that only has the key still works (`--transport cli|http|auto`
+forces the choice). The key is resolved from `SERPAPI_KEY`, then `evo cred get serpapi_api_key`,
+then `~/.config/serpapi/config.toml`, and is passed to the binary through the environment - never on
+the command line, where any process listing would show it. `evo setup serp --write-config` writes
+`~/.config/serpapi/config.toml` (mode 600) if you also want the bare `serpapi` binary to
+authenticate on its own.
+
 ## `evo harness` - read a repo cluster
 
 A harness is a repo that describes a *cluster* of repos: `harness.yaml` lists them, `contracts.yaml`
@@ -253,6 +314,7 @@ evo harness plans      # progress across every exec-plan
 evo harness show <plan>
 evo harness check <plan> [--fetch]      # what the plan claims vs what git says
 evo harness graph <plan>:steps          # the same DAG as an adjacency list
+evo harness clone      # clone every declared repo into its declared path
 evo harness pull       # fast-forward every repo
 ```
 

{evo_cli-0.17.0 → evo_cli-0.19.0}/README.md

@@ -131,6 +131,21 @@ else has the flat file open.
 
 #### Harness Repositories
 
+Clone every repository a harness manifest declares but this machine does not have yet:
+
+```bash
+evo harness clone
+evo harness clone --dry-run                     # show what lands where, change nothing
+evo harness clone --repo backend --depth 1
+evo harness clone --all                         # include repos marked present: false
+```
+
+Each repo lands on its declared `path`, falling back to `<workspace>/<name>`, so a fresh machine
+ends up with the layout the manifest, the contract seams and the exec-plans already assume. A repo
+already on disk is left alone; if its `origin` is not the remote the manifest names, the summary
+says so instead of touching it. When the manifest names a `branch`, the clone moves onto it, and a
+branch nobody has pushed yet is reported rather than treated as a failure.
+
 Fast-forward every available repository declared in a harness manifest:
 
 ```bash
@@ -207,6 +222,52 @@ to disk and the command warns.
 The same engine backs the `evo-tts` MCP server in
 [agent-skills](https://github.com/maycuatroi1/agent-skills), which gives an agent a `speak` tool.
 
+#### Google Search (SerpApi)
+
+Search Google from the terminal through [SerpApi](https://serpapi.com). One-time setup installs the
+official `serpapi` CLI and stores the key in the omelet credential store:
+
+```bash
+evo setup serp                        # install the CLI + prompt for the key (no echo)
+evo setup serp --from-stdin < key.txt # non-interactive
+evo setup serp --method none          # key only; searches use the HTTPS API
+```
+
+`--method auto` (the default) tries Homebrew first, then falls back to the GitHub release binary
+dropped into `~/.evo/bin`. Homebrew 5 refuses to build from an untrusted third-party tap, so the
+brew path needs `evo setup serp --trust-tap` (which runs `brew trust --formula
+serpapi/tap/serpapi-cli`); without it the fallback fetches the same official binary.
+
+```bash
+evo serp search "evo cli python"                     # top 10 Google results
+evo serp search coffee -l "Austin, Texas" -n 5       # localized
+evo serp search openai -t news --hl vi --gl vn       # news vertical, Vietnamese
+evo serp search "site:github.com serpapi" --links    # only URLs, pipe-friendly
+evo serp search "rust async" -p 3 --json > out.json  # 3 merged pages of raw JSON
+evo serp search x -P tbs=qdr:d                       # any extra SerpApi parameter
+```
+
+`-t` picks the vertical (`web`, `news`, `images`, `videos`, `shopping`, `scholar`). Google treats
+`num` as a hint and often returns more, so the rendered output is capped at what `-n` asked for
+while `--json` / `-o` keep the full payload.
+
+Supporting commands:
+
+```bash
+evo serp account            # plan, searches used and left this month
+evo serp locations Hanoi    # canonical names to pass to --location
+evo serp doctor             # binary, key source (masked), remaining quota
+evo serp raw search --jq '.organic_results[0]' engine=google q=coffee
+```
+
+`search` runs through the `serpapi` binary when it is installed and falls back to the SerpApi HTTPS
+endpoint otherwise, so a machine that only has the key still works (`--transport cli|http|auto`
+forces the choice). The key is resolved from `SERPAPI_KEY`, then `evo cred get serpapi_api_key`,
+then `~/.config/serpapi/config.toml`, and is passed to the binary through the environment - never on
+the command line, where any process listing would show it. `evo setup serp --write-config` writes
+`~/.config/serpapi/config.toml` (mode 600) if you also want the bare `serpapi` binary to
+authenticate on its own.
+
 ## `evo harness` - read a repo cluster
 
 A harness is a repo that describes a *cluster* of repos: `harness.yaml` lists them, `contracts.yaml`
@@ -225,6 +286,7 @@ evo harness plans      # progress across every exec-plan
 evo harness show <plan>
 evo harness check <plan> [--fetch]      # what the plan claims vs what git says
 evo harness graph <plan>:steps          # the same DAG as an adjacency list
+evo harness clone      # clone every declared repo into its declared path
 evo harness pull       # fast-forward every repo
 ```
 

evo_cli-0.19.0/evo_cli/VERSION

@@ -0,0 +1 @@
+0.19.0

{evo_cli-0.17.0 → evo_cli-0.19.0}/evo_cli/cli.py

@@ -18,6 +18,7 @@ from evo_cli.commands.miniconda import miniconda
 from evo_cli.commands.netcheck import netcheck
 from evo_cli.commands.opencode import setup_opencode
 from evo_cli.commands.plantuml import plantuml
+from evo_cli.commands.serp import serp_group, setup_serp
 from evo_cli.commands.site2s import site2s
 from evo_cli.commands.ssh import setupssh
 from evo_cli.commands.sysmon import sysmon
@@ -56,6 +57,7 @@ setup_group.add_command(agent_toy)
 setup_group.add_command(setup_claude)
 setup_group.add_command(setup_gh)
 setup_group.add_command(setup_opencode)
+setup_group.add_command(setup_serp)
 setup_group.add_command(miniconda)
 setup_group.add_command(setupssh)
 
@@ -73,6 +75,7 @@ cli.add_command(localproxy)
 cli.add_command(mcp_group)
 cli.add_command(netcheck)
 cli.add_command(plantuml)
+cli.add_command(serp_group)
 cli.add_command(sysmon)
 cli.add_command(tts_group)
 cli.add_command(update)

{evo_cli-0.17.0 → evo_cli-0.19.0}/evo_cli/commands/harness/__init__.py

@@ -1,6 +1,7 @@
 import rich_click as click
 
 from evo_cli.commands.harness.check import check
+from evo_cli.commands.harness.clone import clone
 from evo_cli.commands.harness.edit import debt, question, repo, step
 from evo_cli.commands.harness.pull import pull
 from evo_cli.commands.harness.serve import serve
@@ -21,9 +22,10 @@ def harness_group():
     evo harness graph <plan>       print a DAG as an adjacency list
     evo harness check <plan>       check what the plan claims against real git
     evo harness step <plan> 3 done mark a step
+    evo harness clone              clone every declared repo into its declared path
     evo harness pull               fast-forward every repo
     """
 
 
-for command in (serve, repos, seams, plans, show, graph, check, step, debt, question, repo, pull):
+for command in (serve, repos, seams, plans, show, graph, check, step, debt, question, repo, clone, pull):
     harness_group.add_command(command)

{evo_cli-0.17.0 → evo_cli-0.19.0}/evo_cli/commands/harness/_paths.py

@@ -62,6 +62,10 @@ def load_repos(manifest_path):
             {
                 "name": name,
                 "path": path,
+                # Where the manifest says the repo belongs, whether or not it is there yet.
+                # `path` falls back to the workspace when the declared path is missing, so a
+                # command that creates the checkout has to read this one instead.
+                "declared_path": declared or fallback.resolve(),
                 "present": bool(present) and path.is_dir(),
                 "declared_present": bool(present),
                 "role": str(entry.get("role") or ""),

{evo_cli-0.17.0 → evo_cli-0.19.0}/evo_cli/commands/harness/_render.py

@@ -85,6 +85,16 @@ def print_graph(title: str, graph: dict) -> None:
         print_warnings(graph["warnings"])
 
 
+def print_summary(results: list) -> None:
+    """One `name  status` line per repo, coloured by the verb the status starts with."""
+    click.echo()
+    click.secho("Summary", bold=True)
+    width = max((len(name) for name, _ in results), default=0)
+    for name, status in results:
+        color = "red" if status.startswith("failed") else "yellow" if status.startswith("skipped") else "green"
+        click.secho(f"  {name:<{width}}  {status}", fg=color)
+
+
 def fail_if(condition: bool) -> None:
     if condition:
         raise click.exceptions.Exit(1)

evo_cli-0.19.0/evo_cli/commands/harness/clone.py

@@ -0,0 +1,123 @@
+import re
+import shutil
+
+import rich_click as click
+
+from evo_cli.commands.harness._paths import find_manifest, git, harness_option, load_repos
+from evo_cli.commands.harness._render import print_summary
+
+SCHEME_RE = re.compile(r"^\w+://")
+USER_RE = re.compile(r"^[^@/]+@")
+
+
+def normalize_remote(url):
+    """Reduce a remote URL to host + path so the ssh and https forms of one repo compare equal."""
+    text = str(url).strip().rstrip("/")
+    if text.endswith(".git"):
+        text = text[: -len(".git")]
+    text = USER_RE.sub("", SCHEME_RE.sub("", text))
+    return text.replace(":", "/", 1).lower()
+
+
+def detail_of(result, fallback):
+    lines = ((result.stderr or "") + (result.stdout or "")).strip().splitlines()
+    return lines[-1] if lines else fallback
+
+
+def already_cloned(entry, target):
+    """A checkout is already there. Say so, and say if it came from a different remote."""
+    declared = entry["origin"]
+    actual = git(target, "remote", "get-url", "origin").stdout.strip()
+    if declared and actual and normalize_remote(declared) != normalize_remote(actual):
+        return f"skipped (already cloned, but origin is {actual})"
+    return "skipped (already cloned)"
+
+
+def checkout_declared_branch(entry, target):
+    """Move onto the branch the manifest names. A branch that is not on origin is not an error.
+
+    Cloning with `--branch` would fail the whole clone for a branch that has not been pushed yet,
+    which is a normal state for a plan in progress. Clone the default branch, then try to move.
+    """
+    branch = entry["branch"]
+    if not branch or branch.upper() == "TBD":
+        return ""
+    current = git(target, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
+    if current == branch:
+        return ""
+    if git(target, "checkout", branch, timeout=120).returncode != 0:
+        return f" (branch {branch!r} is not on origin, left on {current or 'HEAD'})"
+    return f" (on {branch})"
+
+
+@click.command("clone", help="Clone the repositories a harness declares into their declared paths.")
+@harness_option
+@click.option("--repo", "repos", multiple=True, help="Clone only this repo name. Repeat for multiple repos.")
+@click.option("--all", "include_absent", is_flag=True, help="Also clone repos the manifest marks present: false.")
+@click.option("--depth", type=int, help="Shallow clone with this many commits of history.")
+@click.option("--dry-run", is_flag=True, help="Show what would be cloned, and where.")
+def clone(harness_path, repos, include_absent, depth, dry_run):
+    """Clone every repository the harness manifest declares but this machine does not have.
+
+    Each repo lands on its declared `path`, falling back to `<workspace>/<name>`, so a fresh
+    machine ends up with the layout the manifest, the contract seams and the exec-plans already
+    assume. Repos already on disk are left alone.
+    """
+    if shutil.which("git") is None:
+        raise click.ClickException("git is not installed or is not on PATH")
+
+    manifest_path = find_manifest(harness_path)
+    manifest, entries = load_repos(manifest_path)
+    available = {entry["name"] for entry in entries}
+    unknown = sorted(set(repos) - available)
+    if unknown:
+        raise click.ClickException(f"Unknown repo name(s): {', '.join(unknown)}")
+    selected = [entry for entry in entries if not repos or entry["name"] in repos]
+
+    click.echo(f"Harness: {manifest.get('name') or manifest_path.parent.name}")
+    click.echo(f"Manifest: {manifest_path}")
+    results = []
+    failures = 0
+
+    for entry in selected:
+        name = entry["name"]
+        target = entry["declared_path"]
+
+        # `present: false` means the manifest knows about the repo and deliberately does not want
+        # it here. Naming it with --repo, or asking for --all, overrides that.
+        if not entry["declared_present"] and not include_absent and not repos:
+            results.append((name, "skipped (present: false)"))
+            continue
+        if (target / ".git").is_dir():
+            results.append((name, already_cloned(entry, target)))
+            continue
+        if entry["path"] != target and (entry["path"] / ".git").is_dir():
+            results.append((name, f"skipped (already cloned at {entry['path']}, manifest says {target})"))
+            continue
+        if target.exists() and (not target.is_dir() or any(target.iterdir())):
+            results.append((name, f"failed (path is taken and is not an empty directory: {target})"))
+            failures += 1
+            continue
+        if not entry["origin"]:
+            results.append((name, "failed (no origin declared in the manifest)"))
+            failures += 1
+            continue
+        if dry_run:
+            results.append((name, f"would clone {entry['origin']} into {target}"))
+            continue
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        args = ["clone"]
+        if depth:
+            args += ["--depth", str(depth)]
+        args += [entry["origin"], str(target)]
+        result = git(target.parent, *args, timeout=900)
+        if result.returncode != 0:
+            results.append((name, f"failed ({detail_of(result, 'git clone failed')})"))
+            failures += 1
+            continue
+        results.append((name, f"cloned into {target}{checkout_declared_branch(entry, target)}"))
+
+    print_summary(results)
+    if failures:
+        raise click.exceptions.Exit(1)

{evo_cli-0.17.0 → evo_cli-0.19.0}/evo_cli/commands/harness/pull.py

@@ -3,6 +3,7 @@ import shutil
 import rich_click as click
 
 from evo_cli.commands.harness._paths import find_manifest, git, harness_option, load_repos
+from evo_cli.commands.harness._render import print_summary
 
 
 @click.command("pull", help="Fast-forward all available repositories in a harness.")
@@ -34,7 +35,7 @@ def pull(harness_path, repos, prune, dry_run):
             results.append((name, "skipped (present: false)"))
             continue
         if not path.is_dir():
-            results.append((name, f"failed (missing: {path})"))
+            results.append((name, f"failed (missing: {path} - run `evo harness clone`)"))
             incomplete += 1
             continue
 
@@ -64,11 +65,6 @@ def pull(harness_path, repos, prune, dry_run):
         head = git(path, "log", "-1", "--oneline")
         results.append((name, head.stdout.strip() or "updated"))
 
-    click.echo()
-    click.secho("Summary", bold=True)
-    width = max((len(name) for name, _ in results), default=0)
-    for name, status in results:
-        color = "red" if status.startswith("failed") else "yellow" if status.startswith("skipped") else "green"
-        click.secho(f"  {name:<{width}}  {status}", fg=color)
+    print_summary(results)
     if incomplete:
         raise click.exceptions.Exit(1)

{evo_cli-0.17.0 → evo_cli-0.19.0}/evo_cli/commands/harness/views.py

@@ -71,6 +71,10 @@ def repos(harness_path, with_git):
         grid.add_row(f"[bold]{entry['name']}[/]", entry["role"] or "-", branch, state, one_line(entry["note"], width))
     console.print(grid)
 
+    missing = [entry["name"] for entry in info["repos"] if not entry["present"]]
+    if missing:
+        console.print(f"\n[red]{len(missing)} repo(s) missing[/] - run [accent]evo harness clone[/] to fetch them")
+
     if info["proposals_pending"]:
         console.print(f"\n[yellow]{len(info['proposals_pending'])} pending proposal(s)[/] in proposals/_pending")