Documentation
¶
Overview ¶
Package ship — hook.go provides the pre-push hook content and installation.
Package ship implements the deterministic agent pipeline guardrail. It wraps pre-flight checks, git push, PR creation, and synchronous CI polling into a single blocking operation so AI agents cannot skip post-merge verification.
Index ¶
- Constants
- func CreatePR(dir, title, body, baseBranch string) (string, error)
- func CurrentBranch(dir string) string
- func DetectStack(dir string) *stackInfo
- func GitPush(dir, commitMsg, branch string) error
- func HasStagedChanges(dir string) bool
- func InstallPrePushHook(repoDir string) error
- func IsPrePushHookInstalled(repoDir string) bool
- func MergePR(dir, prURL string) error
- func WatchPRChecks(dir, prURL, branch string, timeout time.Duration) (runID, conclusion string, failureLogs []string, err error)
- type Options
- type PipelineConfig
- type PipelineStage
- type PreFlightResult
- type Result
Constants ¶
const ( ExitOK = 0 ExitPreFlightFail = 50 ExitPushFail = 51 ExitPRFail = 52 ExitCIFail = 53 ExitCITimeout = 54 ExitDocCheckFail = 55 ExitNothingToShip = 56 )
ExitCodes for deterministic agent error handling.
const PrePushHookContent = `` /* 2336-byte string literal not displayed */
PrePushHookContent is the shell script installed into .git/hooks/pre-push. It runs devx audit (secrets + vulnerability scanning) first, then blocks all git push attempts and directs agents to use devx agent ship. Humans can bypass with: git push --no-verify
Variables ¶
This section is empty.
Functions ¶
func CurrentBranch ¶
CurrentBranch returns the current git branch name.
func DetectStack ¶
func DetectStack(dir string) *stackInfo
DetectStack profiles the repository by looking for marker files.
func GitPush ¶
GitPush stages, commits, and pushes to a feature branch using --no-verify to bypass our own pre-push hook.
func HasStagedChanges ¶
HasStagedChanges checks if there are any uncommitted changes.
func InstallPrePushHook ¶
InstallPrePushHook writes the pre-push hook into .git/hooks/. If any devx-managed hook already exists, it will be safely overwritten. If a non-devx hook exists, it returns an error to avoid clobbering.
func IsPrePushHookInstalled ¶
IsPrePushHookInstalled checks if a devx pre-push hook is present.
func WatchPRChecks ¶ added in v0.34.0
func WatchPRChecks(dir, prURL, branch string, timeout time.Duration) (runID, conclusion string, failureLogs []string, err error)
WatchPRChecks waits for the PR checks to complete using gh pr checks --watch. It blocks until the pipeline finishes or the timeout expires. Returns the run conclusion and any failure logs.
Types ¶
type Options ¶
type Options struct {
CommitMsg string
Branch string // target branch (default: current)
BaseBranch string // base branch for PR (default: main)
Verbose bool
JSON bool
NonInteractive bool
SkipPreFlight bool
CITimeout time.Duration
}
Options configures a ship run.
type PipelineConfig ¶ added in v0.30.0
type PipelineConfig struct {
Test *PipelineStage
Lint *PipelineStage
Build *PipelineStage
Verify *PipelineStage
}
PipelineConfig holds explicit pipeline stage overrides from devx.yaml. When non-nil, auto-detection via DetectStack is bypassed entirely ("Explicit Wins").
type PipelineStage ¶ added in v0.30.0
type PipelineStage struct {
Cmds [][]string // Resolved commands to run sequentially
Before [][]string // Pre-stage hooks (run before Cmds)
After [][]string // Post-stage hooks (run after Cmds)
}
PipelineStage defines a single pipeline step with support for multi-command and lifecycle hooks (before/after).
type PreFlightResult ¶
type PreFlightResult struct {
Stack string `json:"stack"`
TestPass bool `json:"test_pass"`
LintPass bool `json:"lint_pass"`
BuildPass bool `json:"build_pass"`
TestSkipped bool `json:"test_skipped,omitempty"`
LintSkipped bool `json:"lint_skipped,omitempty"`
BuildSkipped bool `json:"build_skipped,omitempty"`
}
PreFlightResult holds the outcome of each local pre-flight step.
func RunPreFlight ¶
func RunPreFlight(dir string, verbose bool, pipeline *PipelineConfig) (*PreFlightResult, error)
RunPreFlight executes local tests, linter, and build. If an explicit pipeline is provided, it takes precedence over auto-detection.
type Result ¶
type Result struct {
Success bool `json:"success"`
ExitCode int `json:"exit_code"`
Phase string `json:"phase"`
Message string `json:"message"`
PRURL string `json:"pr_url,omitempty"`
CIRunID string `json:"ci_run_id,omitempty"`
CIStatus string `json:"ci_status,omitempty"`
FailureLogs []string `json:"failure_logs,omitempty"`
PreFlight *PreFlightResult `json:"pre_flight,omitempty"`
}
Result is the machine-readable output of a ship operation.
Source Files