feat: harness init, doctor, and docs overhaul#76
Merged
Conversation
harness init generates a customized harness.yaml by asking entrypoint, providers, and gateway target. Discovers available providers from openshell provider list-profiles (falls back to built-in list). Supports --non-interactive, --force, and --output flags. harness doctor validates the environment can run the configured sandbox with a two-phase CheckFunc pipeline: - Phase 1 (offline): openshell binary, target deps (podman/docker for local, kubectl+kind for kind, kubectl+kubeconfig for remote), and provider env vars (via openshell provider profile export). - Phase 2 (online): provider registration status if gateway reachable. Outputs grouped by target/provider/openshell with -o table|json|yaml. 29 tests covering all codepaths including credential masking.
Rewrite Quick Start to show the three-step onramp: init -> doctor -> apply. Add init and doctor to the commands reference. Update the hero code block and flow diagram. Move advanced examples under "More examples" subsection.
Two fixes: - Map harness provider names to OpenShell profile IDs (vertex-local -> google-vertex-ai, gws -> google-workspace) so profile export finds the right profile. - Skip env var checks for gateway-managed credentials (those with a refresh strategy). Instead check the actual auth state: ADC file for vertex, gws auth export for GWS.
podman info --format with .Host.Os fails on podman 5.x (field removed). Use plain podman info instead and get version from podman version. Also fall through to docker when podman is installed but not responding.
Init wrote OpenShell profile IDs (google-vertex-ai, google-workspace) as provider names, but apply expects harness names (vertex-local, gws). Added harnessProviderName mapping to translate on output. Simplified gateway targets to local/kind/ocp. Removed 'remote' alias that had no matching gateway profile.
Rename vertex-local to google-vertex-ai and gws to google-workspace across the entire codebase. Eliminates the providerProfileType and harnessProviderName mapping tables that caused init to generate configs incompatible with apply. One namespace: harness uses the same provider IDs as openshell.
README: add experimental banner, rewrite intro to explain OpenShell foundation-layer architecture and the harness as a workflow layer. Reference upstream operator discussion (#1719) and explain that the gateway is narrowing to data-plane while control-plane moves to CRDs. TODO: update upstream issue tracking to reflect core team comments on #1886 (rejected in favor of operator/CRD path) and note #1520/#1814 have no maintainer engagement.
robbycochran
changed the title
Lead with the primary use case: point a skill at a repo, get results. Example shows cpp-pro skill running against stackrox/collector for highest-priority remediation. Explains OpenShell as a foundation layer and the harness as a workflow layer on top. Trimmed reference section into tables.
robbycochran
changed the title
Document the agent config YAML format with all fields, multi-document composition, provider profiles with credential details for all four supported providers (github, vertex-ai, atlassian, google-workspace), scope policy via refresh.scopes, and gateway profiles for all three deployment targets.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
harness initgenerates a customized harness.yaml by prompting for entrypoint, providers, and gateway target. Discovers available providers fromopenshell provider list-profiles.harness doctorvalidates the environment with a two-phase CheckFunc pipeline: offline checks (openshell binary, target deps, provider env vars) + online checks (provider registration if gateway reachable).profiles/,profiles/providers/, andprofiles/gateways/explaining YAML formats, all four supported providers with credential details, scope policy, and gateway deployment targets.Test plan
make test-- all tests pass (vet + 5 packages)harness init-> answer prompts -> generates valid harness.yamlharness doctor-> reports target/provider/openshell statusharness doctor -o json-> stable JSON output with no credential valuesharness init --non-interactive-> writes embedded default