buildai-cli 0.3.82__tar.gz → 0.3.83__tar.gz

{buildai_cli-0.3.82 → buildai_cli-0.3.83}/.gitignore

@@ -59,6 +59,7 @@ Thumbs.db
 
 # Local tool state
 .superpowers/
+.grid-builder-work/
 
 # EgoExo sync trial script spill (default output is under experiments/egoexo-pipeline/out/)
 /*.sync_trial.json

{buildai_cli-0.3.82 → buildai_cli-0.3.83}/CLAUDE.md

@@ -13,6 +13,9 @@ Typer-based CLI with two modes: standalone (PyPI, API-backed) and workspace (rep
 
 ```bash
 buildai auth whoami                                  # API auth inspection
+uv run buildai ingest deploy plan --scope active     # Dry-run ingest fleet plan
+uv run buildai ingest deploy run --scope station:2   # Staged ingest rollout
+uv run buildai ingest fleet readiness --scope active # Host readiness gate
 buildai db query "SELECT count(*) FROM core.clips"   # DB-direct
 buildai db --env staging tunnel                      # IAP/SOCKS route for private staging DB
 buildai db --env staging --all-proxy socks5://127.0.0.1:1080 query "SELECT 1"  # staging query

{buildai_cli-0.3.82 → buildai_cli-0.3.83}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildai-cli
-Version: 0.3.82
+Version: 0.3.83
 Summary: Build AI CLI (Typer)
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0

buildai_cli-0.3.83/cli/commands/ingest.py

@@ -0,0 +1,363 @@
+"""Workspace commands for BuildAI ingest fleet deploy control plane."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cli.commands.ingest_docs import (
+    DEPLOY_GROUP_HELP,
+    FLEET_GROUP_HELP,
+    HOST_GROUP_HELP,
+    INGEST_ROOT_HELP,
+    TOPIC_NAMES,
+    render_guide,
+)
+from cli.console import error, info, success, warning
+
+app = typer.Typer(
+    help=INGEST_ROOT_HELP,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+deploy_app = typer.Typer(
+    help=DEPLOY_GROUP_HELP,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+fleet_app = typer.Typer(
+    help=FLEET_GROUP_HELP,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+host_app = typer.Typer(
+    help=HOST_GROUP_HELP,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+app.add_typer(deploy_app, name="deploy")
+app.add_typer(fleet_app, name="fleet")
+app.add_typer(host_app, name="host")
+
+SCOPE_HELP = (
+    "Deploy target set. Examples: active, all, station:2, mini:1, server:1, aggregator. "
+    "See: buildai ingest docs --topic scopes"
+)
+TRANSPORT_HELP = (
+    "Remote path: tailscale (default, requires Tailscale CLI + tailnet) or "
+    "lan (on-site 10G static IPs). See: buildai ingest docs --topic transport"
+)
+
+
+def _emit_deploy_run_result(record, *, json_output: bool, engine, run_id: str) -> None:
+    """Print human-readable deploy/resume outcome from the terminal run state."""
+
+    payload = engine.deploy_status(run_id)
+    if json_output:
+        sys.stdout.write(engine.format_json(payload) + "\n")
+        return
+    state = record.state.value
+    if state == "converged":
+        success(f"deploy converged: {record.run_id} ({record.release_id})")
+    elif state == "activated":
+        success(f"deploy activated: {record.run_id} ({record.release_id})")
+    elif state == "deployed_not_converged":
+        warning(f"deploy incomplete: {record.failure_message or state}")
+    elif state == "blocked_by_readiness":
+        warning(f"deploy blocked by readiness: {record.failure_message}")
+    elif state in {"aborted", "preflight_failed"}:
+        error(f"deploy failed ({state}): {record.failure_message}")
+    else:
+        error(f"deploy finished as {state}: {record.failure_message}")
+
+
+def _ingest_engine():
+    """Import the ingest deploy engine from the workspace checkout."""
+
+    current = Path(__file__).resolve()
+    repo_root = None
+    for parent in current.parents:
+        if (parent / ".git").exists() and (parent / "apps" / "buildai-ingest" / "fleet").exists():
+            repo_root = parent
+            break
+    if repo_root is None:
+        error(
+            "Ingest deploy requires a workspace checkout with apps/buildai-ingest.\n"
+            "Run from the monorepo via: uv run buildai ingest ...\n"
+            "See: uv run buildai ingest docs --topic prerequisites"
+        )
+        raise typer.Exit(1)
+
+    ingest_dir = repo_root / "apps" / "buildai-ingest"
+    ingest_str = str(ingest_dir)
+    if ingest_str not in sys.path:
+        sys.path.insert(0, ingest_str)
+
+    import fleet.engine as engine
+
+    return engine
+
+
+@app.command("docs")
+def ingest_docs(
+    topic: Annotated[
+        str | None,
+        typer.Option(
+            "--topic",
+            "-t",
+            help=f"One section: {', '.join(TOPIC_NAMES)}",
+        ),
+    ] = None,
+) -> None:
+    """Print the ingest fleet operator guide (prerequisites, workflow, transport, credentials)."""
+
+    try:
+        sys.stdout.write(render_guide(topic=topic))
+    except ValueError as exc:
+        sys.stdout.write(f"{exc}\n")
+        raise typer.Exit(2) from exc
+
+
+@deploy_app.command("plan")
+def deploy_plan(
+    scope: str = typer.Option("active", "--scope", "-s", help=SCOPE_HELP),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON plan."),
+) -> None:
+    """Dry-run deploy plan: resolved targets, rollout order, and git warnings (no host mutation)."""
+
+    engine = _ingest_engine()
+    plan = engine.plan_deploy(scope=scope, transport=transport)
+    if json_output:
+        payload = {
+            "scope": plan.scope,
+            "transport": plan.transport,
+            "commit_sha": plan.commit_sha,
+            "targets": [target.name for target in plan.targets],
+            "excluded": [
+                {"name": target.name, "reason": target.skip_reason} for target in plan.excluded
+            ],
+            "rollout_order": plan.rollout_order,
+            "warnings": plan.warnings,
+        }
+        sys.stdout.write(engine.format_json(payload) + "\n")
+        return
+    info(engine.format_plan(plan))
+
+
+@deploy_app.command("run")
+def deploy_run(
+    scope: str = typer.Option("active", "--scope", "-s", help=SCOPE_HELP),
+    reason: str = typer.Option(
+        "", "--reason", help="Operator reason recorded in the deploy ledger."
+    ),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+    allow_dirty: bool = typer.Option(
+        False,
+        "--allow-dirty",
+        help="Allow deploy with a dirty git working tree (emergency only).",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON result."),
+) -> None:
+    """Build an immutable release artifact and execute a canaried staged fleet rollout."""
+
+    engine = _ingest_engine()
+    record, exit_code = engine.run_deploy(
+        scope=scope,
+        reason=reason,
+        transport=transport,
+        allow_dirty=allow_dirty,
+    )
+    _emit_deploy_run_result(record, json_output=json_output, engine=engine, run_id=record.run_id)
+    raise typer.Exit(exit_code)
+
+
+@deploy_app.command("status")
+def deploy_status(
+    run_id: str | None = typer.Argument(
+        None,
+        help="Deploy run id (default: latest run in ~/.buildai/ingest-deploy-runs/).",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON result."),
+) -> None:
+    """Show deploy run state, release id, and failure classification from the ledger."""
+
+    engine = _ingest_engine()
+    payload = engine.deploy_status(run_id)
+    if json_output:
+        sys.stdout.write(engine.format_json(payload) + "\n")
+        return
+    if not payload.get("run_id"):
+        info("No deploy runs recorded yet.")
+        return
+    info(f"{payload['run_id']}: state={payload.get('state')} release={payload.get('release_id')}")
+
+
+@deploy_app.command("resume")
+def deploy_resume(
+    run_id: str = typer.Argument(..., help="Non-terminal run id to continue."),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON result."),
+) -> None:
+    """Resume a partially completed deploy from its saved artifact and ledger state."""
+
+    engine = _ingest_engine()
+    record, exit_code = engine.resume_deploy(run_id, transport=transport)
+    _emit_deploy_run_result(record, json_output=json_output, engine=engine, run_id=record.run_id)
+    raise typer.Exit(exit_code)
+
+
+@deploy_app.command("rollback")
+def deploy_rollback(
+    scope: str = typer.Option(..., "--scope", "-s", help=SCOPE_HELP),
+    to_release: str | None = typer.Option(
+        None,
+        "--to",
+        help="Explicit prior release id (default: ledger previous_release_id).",
+    ),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON result."),
+) -> None:
+    """Flip current symlink to a prior release; re-stage only when that release was pruned."""
+
+    engine = _ingest_engine()
+    rollback_plan, exit_code = engine.rollback_deploy(
+        scope=scope,
+        to_release=to_release,
+        transport=transport,
+    )
+    payload = {
+        "scope": rollback_plan.scope,
+        "from_release_id": rollback_plan.from_release_id,
+        "to_release_id": rollback_plan.to_release_id,
+        "targets": list(rollback_plan.targets),
+        "action": rollback_plan.action,
+    }
+    if json_output:
+        sys.stdout.write(engine.format_json(payload) + "\n")
+    elif exit_code == 0:
+        success(
+            f"rollback complete: {rollback_plan.from_release_id} -> {rollback_plan.to_release_id}"
+        )
+    else:
+        error(f"rollback failed: {rollback_plan.from_release_id} -> {rollback_plan.to_release_id}")
+    raise typer.Exit(exit_code)
+
+
+@fleet_app.command("readiness")
+def fleet_readiness(
+    scope: str = typer.Option("active", "--scope", "-s", help=SCOPE_HELP),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON result."),
+) -> None:
+    """Report host drift and maintenance blocks before deploy run (deployable vs blocked)."""
+
+    engine = _ingest_engine()
+    payload = engine.readiness_report(scope=scope, transport=transport)
+    if json_output:
+        sys.stdout.write(engine.format_json(payload) + "\n")
+        return
+    if payload["state"] == "ready":
+        success(f"fleet readiness: {payload['state']}")
+    else:
+        warning(f"fleet readiness: {payload['state']}")
+        for action in payload.get("next_actions", []):
+            if action:
+                info(f"next: {action}")
+
+
+@fleet_app.command("preflight")
+def fleet_preflight(
+    scope: str = typer.Option(
+        "all",
+        "--scope",
+        "-s",
+        help="Preflight scope: all, minis, servers, aggregator, or mini/server filters.",
+    ),
+    targets: list[str] = typer.Argument(
+        None,
+        help="Optional filters after scope (e.g. minis 1,2,3).",
+    ),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+) -> None:
+    """Read-only gate: inventory consistency, reachability, and Tailscale CLI check."""
+
+    engine = _ingest_engine()
+    try:
+        engine.run_preflight_check(
+            scope=scope,
+            targets=list(targets or []),
+            transport=transport,
+        )
+    except Exception as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    success(f"fleet preflight passed for scope={scope}")
+
+
+@fleet_app.command("auth")
+def fleet_auth(
+    scope: str = typer.Option("all", "--scope", "-s", help="Auth validation scope."),
+    targets: list[str] = typer.Argument(None, help="Optional target filters."),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+) -> None:
+    """Validate worker, uploader, and aggregator API keys for the selected scope."""
+
+    engine = _ingest_engine()
+    try:
+        engine.validate_runtime_auth(
+            scope=scope,
+            targets=list(targets or []),
+            transport=transport,
+        )
+    except Exception as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    success(f"ingest runtime auth validated for scope={scope}")
+
+
+@host_app.command("bootstrap")
+def host_bootstrap(
+    targets: list[str] = typer.Argument(
+        ...,
+        help="Mini numbers or names: 5, 5,6,7 or ingest-mini-11.",
+    ),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON result."),
+) -> None:
+    """Pin drifted minis to the ingest-mini-1 Homebrew, rsync, and uv baseline."""
+
+    engine = _ingest_engine()
+    try:
+        payload = engine.bootstrap_hosts(targets=targets, transport=transport)
+    except Exception as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    if json_output:
+        sys.stdout.write(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+        return
+    names = [item.get("name", "") for item in payload.get("targets", [])]
+    success(f"host bootstrap complete for {', '.join(names)}")
+
+
+@host_app.command("repair")
+def host_repair(
+    target: str = typer.Argument(..., help="Mini target: ingest-mini-5 or shorthand 5."),
+    transport: str = typer.Option("tailscale", "--transport", help=TRANSPORT_HELP),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON result."),
+) -> None:
+    """Repair one mini host surface when readiness reports drift (outside app deploy)."""
+
+    _ingest_engine()
+    from fleet.host_repair import repair_mini_host
+
+    summary = repair_mini_host(target, transport_mode=transport)
+    if json_output:
+        sys.stdout.write(json.dumps(summary, indent=2, sort_keys=True) + "\n")
+        return
+    success(f"host repair complete for {summary.get('name', target)}")

buildai_cli-0.3.83/cli/commands/ingest_docs.py

@@ -0,0 +1,311 @@
+"""Operator documentation rendered by ``buildai ingest docs``."""
+
+from __future__ import annotations
+
+INGEST_ROOT_HELP = """
+[b]Ingest fleet control plane[/b] — deploy and operate Mac minis, upload servers, and the aggregator.
+
+[b]Quick start (remote laptop, Tailscale):[/b]
+  uv run buildai ingest docs
+  uv run buildai ingest fleet preflight --scope all
+  uv run buildai ingest fleet auth --scope all
+  uv run buildai ingest deploy plan --scope active
+  uv run buildai ingest deploy run --scope active --reason "ship fix"
+
+[b]Read the full guide:[/b]  [cyan]buildai ingest docs[/cyan]  or  [cyan]buildai ingest docs --topic workflow[/cyan]
+
+[b]Requires:[/b] monorepo checkout ([cyan]apps/buildai-ingest[/cyan]), Tailscale or on-site LAN, local secrets file.
+Standalone PyPI [cyan]buildai[/cyan] without a workspace cannot run ingest deploy.
+"""
+
+DEPLOY_GROUP_HELP = """
+Immutable artifact deploy: build release bundle, stage per-host [cyan]releases/<id>/[/cyan], flip [cyan]current[/cyan], audit convergence.
+
+[b]Typical flow:[/b] plan → run → status. Use [cyan]resume[/cyan] after partial failure; [cyan]rollback[/cyan] to flip [cyan]current[/cyan] back.
+
+[b]Scopes:[/b] active | all | station:N | mini:N | server:N | aggregator
+[b]Transport:[/b] tailscale (default, remote) | lan (on-site 10G static IPs)
+"""
+
+FLEET_GROUP_HELP = """
+Read-only fleet gates and drift checks before mutating hosts.
+
+[b]Order:[/b] preflight → auth → readiness → deploy run
+"""
+
+HOST_GROUP_HELP = """
+Host-level repair outside the app deploy path.
+
+[b]bootstrap[/b] — pin Homebrew/rsync/uv to the ingest-mini-1 baseline (new or drifted minis).
+[b]repair[/b] — reconcile one mini host surface when readiness reports drift.
+"""
+
+TOPICS: dict[str, str] = {
+    "overview": """
+INGEST FLEET — OPERATOR OVERVIEW
+================================
+
+The ingest fleet runs outside Cloud Run:
+  • Mac minis run ingest-agent (SD card → rsync → erase)
+  • Upload servers run upload-daemon (GCS uploads)
+  • One aggregator coordinates fleet state and operator UI
+
+All operator workflows go through the BuildAI CLI from a monorepo checkout:
+
+  uv run buildai ingest <group> <command> [options]
+
+Command groups:
+  deploy   — artifact build, staged rollout, status, resume, rollback
+  fleet    — preflight, auth, readiness (read-only gates)
+  host     — bootstrap and repair (host toolchain, not app code)
+  docs     — this guide
+
+Canonical runbook (more detail): apps/buildai-ingest/docs/deploy.md
+Semantic contract: apps/buildai-ingest/docs/deploy-contract.md
+Topology source of truth: apps/buildai-ingest/fleet/inventory.json
+""",
+    "prerequisites": """
+PREREQUISITES
+=============
+
+Workspace
+  • Clone build-ai monorepo and run setup (uv sync --locked, credentials hydration).
+  • Commands must run from the repo: uv run buildai ingest ...
+  • Standalone pip-installed buildai without apps/buildai-ingest will fail.
+
+Network — pick one transport (see: buildai ingest docs --topic transport)
+  • tailscale (default) — deploy from any laptop on the tailnet
+  • lan — on-site only; uses 10G static IPs from inventory (192.168.10.x)
+
+Tailscale (when --transport tailscale)
+  • Tailscale app installed and logged in on the operator laptop
+  • tailscale CLI on PATH (deploy preflight runs: tailscale status --json)
+  • Operator can reach mini/server tailnet hostnames in fleet/inventory.json
+
+On-site LAN (when --transport lan)
+  • Laptop on the ingest VLAN with route to 192.168.10.x
+  • No Tailscale required; minis/servers reached via ingest_ip / lan_host
+
+Local secrets (required)
+  • apps/buildai-ingest/docs/credentials.private.json (gitignored)
+  • Hydrated by scripts/setup from GCP Secret Manager on a configured workstation
+  • Or set equivalent env vars (see: buildai ingest docs --topic credentials)
+
+Git discipline (before deploy run)
+  • git branch --show-current — use an intentional feature/fix branch
+  • git status --short — prefer clean tree; pass --allow-dirty only for emergencies
+  • Commit and push the snapshot you intend to ship; minis do not git pull
+""",
+    "credentials": """
+CREDENTIALS & SECRETS
+=====================
+
+Primary file (gitignored):
+  apps/buildai-ingest/docs/credentials.private.json
+
+Deploy reads passwords and API keys from that file, with env-var overrides:
+
+  BUILD_AI_INGEST_MINI_PASSWORD      — SSH password for all minis
+  BUILD_AI_INGEST_SERVER_PASSWORD    — SSH/sudo password for servers + aggregator
+  BUILD_AI_INGEST_WORKER_API_KEY     — Mini agent → Build.ai API
+  BUILD_AI_INGEST_AGGREGATOR_API_KEY — Aggregator → Build.ai API
+  BUILD_AI_INGEST_UPLOADER_API_KEY   — Upload daemon → Build.ai API
+
+Optional observability (artifact frontend build / runtime):
+  BUILD_AI_INGEST_AGENT_SENTRY_DSN
+  BUILD_AI_INGEST_DAEMON_SENTRY_DSN
+  BUILD_AI_INGEST_AGGREGATOR_SENTRY_DSN
+  BUILD_AI_INGEST_DASHBOARD_SENTRY_DSN (Vite frontend)
+  GRAFANA_CLOUD_LOKI_URL / USERNAME / PASSWORD — Alloy log shipping on minis
+
+Validate before deploy:
+  uv run buildai ingest fleet auth --scope all
+
+Never commit live secret values to tracked docs or code.
+""",
+    "transport": """
+TRANSPORT MODES
+===============
+
+--transport tailscale  (default, recommended remote)
+  • Uses tailnet hostnames from fleet/inventory.json
+  • Requires: Tailscale CLI, active tailnet session, tailscale status --json OK
+  • Password SSH to minis/servers (LegacyPasswordTransport)
+  • Future: set BUILDAI_INGEST_TAILSCALE_SSH=1 for Tailscale SSH key transport
+
+--transport lan  (on-site)
+  • Minis: ingest_ip (10G static, e.g. 192.168.10.x) — never mDNS
+  • Servers/aggregator: lan_host from inventory
+  • Use when physically on the ingest network without Tailscale
+
+Preflight verifies reachability for the selected scope and transport:
+  uv run buildai ingest fleet preflight --scope all --transport tailscale
+""",
+    "workflow": """
+STANDARD DEPLOY WORKFLOW
+========================
+
+1. Preflight (read-only connectivity + inventory)
+     uv run buildai ingest fleet preflight --scope all
+
+2. Auth (API keys for worker/uploader/aggregator principals)
+     uv run buildai ingest fleet auth --scope all
+
+3. Readiness (host drift / maintenance blocks)
+     uv run buildai ingest fleet readiness --scope active
+
+4. Plan (dry run — targets, rollout order, git warnings)
+     uv run buildai ingest deploy plan --scope active
+
+5. Deploy (build artifact + staged rollout)
+     uv run buildai ingest deploy run --scope active --reason "describe change"
+
+6. Verify
+     uv run buildai ingest deploy status
+
+Rollout order for multi-target scopes:
+  • Canary: ingest-mini-1 first
+  • Then station batches (minis per station, then servers, aggregator)
+  • Convergence audit at the end when in rollout plan
+
+Partial failure:
+  uv run buildai ingest deploy status
+  uv run buildai ingest deploy resume <run-id>
+
+Rollback (pointer flip when prior release dir still on host):
+  uv run buildai ingest deploy rollback --scope active
+  uv run buildai ingest deploy rollback --scope station:1 --to <release-id>
+""",
+    "scopes": """
+DEPLOY SCOPES (--scope)
+=======================
+
+active     All inventory targets with desired_state=active (excludes maintenance minis)
+all        All minis, servers, aggregator (respects maintenance skips)
+station:N  Minis + server for station N; aggregator when any mini in scope
+mini:N     Single mini (e.g. mini:1 → ingest-mini-1)
+           Alias: ingest-mini-N
+server:N   Single upload server (e.g. server:2 → ingest-server-02)
+aggregator Aggregator only
+
+Comma lists: station:1,station:2
+
+Notes:
+  • ingest-mini-11 is maintenance by default — target explicitly if needed
+  • Targeted deploys do not satisfy full-fleet convergence alone; follow with active scope
+  • First production cutover to release layout: prefer --scope mini:1 as canary
+""",
+    "host-layout": """
+ON-HOST RELEASE LAYOUT
+======================
+
+Each host keeps a stable install root:
+
+  Minis:       /Users/<user>/ingest-agent/
+  Servers:     /home/buildai/upload-daemon/
+  Aggregator:  /home/buildai/aggregator/
+
+Under that root:
+
+  releases/<release-id>/   Immutable code + per-release .venv (uv sync --locked at stage)
+  current → releases/<id>/ Symlink — active release (rollback = flip this)
+  shared/
+    logs/        Agent, Alloy, launchd logs (persistent)
+    state/       Port telemetry, card state, recovery markers
+    config/      Fleet-rendered config.yaml (minis)
+    alloy-data/  Alloy storage path
+
+Deploy stages into releases/<id>/, flips current, restarts services, prunes to keep last 3.
+
+Agent plist/systemd units reference .../current for code and .../shared for data.
+""",
+    "commands": """
+COMMAND REFERENCE
+=================
+
+deploy plan     Dry plan: targets, rollout order, git warnings
+deploy run      Build artifact + execute staged rollout
+deploy status   Latest or specific run state (ledger under ~/.buildai/ingest-deploy-runs/)
+deploy resume   Continue a non-terminal run from saved artifact
+deploy rollback Flip current to previous release (re-stage only if pruned)
+
+fleet preflight Read-only: inventory, reachability, tailscale check
+fleet auth      Validate runtime API credentials for scope
+fleet readiness Host drift / maintenance deployability report
+
+host bootstrap  Pin minis to ingest-mini-1 Homebrew/rsync/uv baseline
+host repair     Repair one mini host outside app deploy
+
+docs            Print this guide (--topic <name> for one section)
+
+Common options:
+  --scope, -s     Deploy/preflight scope (default varies by command)
+  --transport     tailscale | lan (default: tailscale)
+  --json          Machine-readable output where supported
+  --allow-dirty   deploy run only — allow dirty git tree
+  --reason        deploy run only — audit trail string
+  --to            deploy rollback only — explicit prior release id
+""",
+    "troubleshooting": """
+TROUBLESHOOTING
+===============
+
+"requires a workspace checkout"
+  → Run from monorepo root: uv run buildai ingest ...
+  → apps/buildai-ingest/fleet must exist
+
+"Tailscale CLI is required"
+  → Install Tailscale; ensure tailscale status works
+  → Or use --transport lan when on-site
+
+"deploy blocked by readiness"
+  → uv run buildai ingest fleet readiness --scope <scope>
+  → Follow next_action hints (often: buildai ingest host repair <mini>)
+
+"deploy lock held"
+  → Another run in progress; buildai ingest deploy status
+  → Wait or resolve stale lock in ~/.buildai/ingest-deploy-runs/
+
+exit 6 / state staged
+  → Rollout stopped mid-batch; deploy resume <run-id>
+
+exit 4 / deployed_not_converged
+  → Hosts updated but audit failed; check aggregator visibility / health
+
+Host drift (brew/rsync/uv wrong version)
+  → uv run buildai ingest host bootstrap <mini-numbers>
+
+Canary failure
+  → Rollout aborts; fix ingest-mini-1 before widening scope
+
+Artifacts:
+  ~/.buildai/ingest-releases/<release-id>/
+Run ledger:
+  ~/.buildai/ingest-deploy-runs/
+""",
+}
+
+TOPIC_NAMES = sorted(TOPICS.keys())
+
+
+def render_guide(*, topic: str | None = None) -> str:
+    """Return full or single-topic operator documentation."""
+
+    if topic is None:
+        parts = [TOPICS["overview"].strip()]
+        for name in TOPIC_NAMES:
+            if name == "overview":
+                continue
+            parts.append(TOPICS[name].strip())
+        parts.append(
+            "Topics: "
+            + ", ".join(name for name in TOPIC_NAMES if name != "overview")
+            + "\n\nRun: buildai ingest docs --topic <name>"
+        )
+        return "\n\n".join(parts) + "\n"
+
+    key = topic.strip().lower().replace("_", "-")
+    if key not in TOPICS:
+        available = ", ".join(TOPIC_NAMES)
+        raise ValueError(f"Unknown topic {topic!r}. Available: {available}")
+    return TOPICS[key].strip() + "\n"

{buildai_cli-0.3.82 → buildai_cli-0.3.83}/cli/main.py

@@ -317,6 +317,16 @@ def db_callback(
     init_ops_context(ctx)
 
 
+def _has_ingest_workspace() -> bool:
+    """Return whether the current checkout exposes the ingest deploy engine."""
+
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        if (parent / ".git").exists() and (parent / "apps" / "buildai-ingest" / "fleet").exists():
+            return True
+    return False
+
+
 if has_core():
     from cli.commands.db import app as db_app
     from cli.commands.gigcamera import app as gigcamera_app
@@ -327,6 +337,11 @@ if has_core():
     app.add_typer(gigcamera_app, name="gigcamera")
     app.add_typer(grid_app, name="grid")
 
+if _has_ingest_workspace():
+    from cli.commands.ingest import app as ingest_app
+
+    app.add_typer(ingest_app, name="ingest")
+
 
 def main() -> None:
     app()

{buildai_cli-0.3.82 → buildai_cli-0.3.83}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "buildai-cli"
-version = "0.3.82"
+version = "0.3.83"
 description = "Build AI CLI (Typer)"
 requires-python = ">=3.11"
 dependencies = [