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 CreateAndMergePR(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 PollCI(dir, 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 CreateAndMergePR ¶
CreateAndMergePR creates a GitHub PR and merges it. Returns the PR URL.
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 PollCI ¶
func PollCI(dir, branch string, timeout time.Duration) (runID, conclusion string, failureLogs []string, err error)
PollCI waits for the latest CI run on the given branch to complete. 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
}
PipelineStage defines a single pipeline step with support for multi-command.
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