cli

package
v3.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: MIT Imports: 49 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ExitSuccess         = 0
	ExitInputError      = 1
	ExitSpecError       = 2
	ExitGenerationError = 3
	ExitUnknownError    = 4
	ExitPublishError    = 5
)

Exit codes for structured error reporting.

Variables

View Source 
var FrameworkCommands = map[string]bool{
	"about":         true,
	"agent-context": true,
	"api":           true,
	"auth":          true,
	"completion":    true,
	"doctor":        true,
	"feedback":      true,
	"help":          true,
	"profile":       true,
	"search":        true,
	"sql":           true,
	"version":       true,
	"which":         true,
}

FrameworkCommands mirrors cobratree/classify.go.tmpl. The runtime walker skips these names entirely — they're never registered as MCP tools — so audit findings on their Cobra Short are noise. Exported so the spec drift test in internal/spec can assert the cobra-Use reserved set is a strict superset (anything cobratree skips at MCP time would shadow at cobra time too).

Functions

func Execute 

func Execute() error

Types

type CheckResult 

type CheckResult struct {
	Name    string `json:"name"`
	Passed  bool   `json:"passed"`
	Error   string `json:"error,omitempty"`
	Warning string `json:"warning,omitempty"`
}

CheckResult represents a single validation check.

type EmbossDelta 

type EmbossDelta struct {
	ScorecardDelta int     `json:"scorecard_delta"`
	VerifyDelta    float64 `json:"verify_delta"`
	CommandDelta   int     `json:"command_delta"`
	PipelineFixed  bool    `json:"pipeline_fixed"`
}

type EmbossReport 

type EmbossReport struct {
	Dir          string          `json:"dir"`
	Spec         string          `json:"spec"`
	Timestamp    string          `json:"timestamp"`
	Before       EmbossSnapshot  `json:"before"`
	After        *EmbossSnapshot `json:"after,omitempty"`
	Delta        *EmbossDelta    `json:"delta,omitempty"`
	Improvements []string        `json:"improvements,omitempty"`
	Mode         string          `json:"mode"` // "audit-only" or "full"
}

EmbossReport captures the before/after delta from an emboss cycle.

type EmbossSnapshot 

type EmbossSnapshot struct {
	ScorecardTotal int     `json:"scorecard_total"`
	ScorecardGrade string  `json:"scorecard_grade"`
	VerifyPassRate float64 `json:"verify_pass_rate"`
	VerifyPassed   int     `json:"verify_passed"`
	VerifyTotal    int     `json:"verify_total"`
	DataPipeline   bool    `json:"data_pipeline"`
	CommandCount   int     `json:"command_count"`
}

type ExitError 

type ExitError struct {
	Code   int
	Err    error
	Silent bool
}

ExitError wraps an error with a specific exit code. When Silent is true, main should exit with the code but not print the error message — used when structured output (--json) already contains the failure details.

func (*ExitError) Error 

func (e *ExitError) Error() string

func (*ExitError) Unwrap 

func (e *ExitError) Unwrap() error

type LibraryEntry 

type LibraryEntry struct {
	CLIName      string    `json:"cli_name"`
	Dir          string    `json:"dir"`
	APIName      string    `json:"api_name,omitempty"`
	Category     string    `json:"category,omitempty"`
	CatalogEntry string    `json:"catalog_entry,omitempty"`
	Description  string    `json:"description,omitempty"`
	Modified     time.Time `json:"modified"`
}

LibraryEntry represents a CLI in the local library for listing purposes.

type MCPAuditFinding 

type MCPAuditFinding struct {
	API        string `json:"api"`         // library directory basename
	HasMCP     bool   `json:"has_mcp"`     // the CLI emits an MCP server
	Transport  string `json:"transport"`   // "stdio", "http", "both", "unknown", "n/a"
	ToolDesign string `json:"tool_design"` // "endpoint-mirror", "intent", "code-orch", "n/a"
	EndpointCt int    `json:"endpoint_count"`
	IntentCt   int    `json:"intent_count"`
	Recommend  string `json:"recommend"` // short, actionable suggestion
}

MCPAuditFinding summarizes one CLI's MCP shape. Stable JSON field names so downstream tools (ci scripts, the future emboss-audit loop) can consume this without depending on go struct ordering.

type PackageResult 

type PackageResult struct {
	StagedDir           string `json:"staged_dir"`
	CLIName             string `json:"cli_name"`
	APIName             string `json:"api_name"`
	Category            string `json:"category"`
	ModulePath          string `json:"module_path,omitempty"`
	ManuscriptsIncluded bool   `json:"manuscripts_included"`
	RunID               string `json:"run_id,omitempty"`
}

PackageResult is the JSON output of publish package.

type PolishProgress 

type PolishProgress struct {
	LastProcessedFindingID string `json:"last_processed_finding_id,omitempty"`
}

PolishProgress is the agent-written checkpoint for resume after context loss. The binary derives a fallback resume hint from the finding list when this is absent, so the field is optional.

type RenameResult 

type RenameResult struct {
	Success       bool   `json:"success"`
	OldName       string `json:"old_name"`
	NewName       string `json:"new_name"`
	NewDir        string `json:"new_dir"`
	FilesModified int    `json:"files_modified"`
	Error         string `json:"error,omitempty"`
}

RenameResult is the JSON output of publish rename.

type ScorecardSnapshot 

type ScorecardSnapshot struct {
	MCPDescriptionQuality int       `json:"mcp_description_quality"`
	Captured              time.Time `json:"captured"`
}

ScorecardSnapshot captures the scorecard dimensions the polish ledger gates on, taken at run start.

type ToolsAuditFinding 

type ToolsAuditFinding struct {
	Kind     string `json:"kind"`
	Command  string `json:"command"`          // tool name (manifest) or Cobra Use head (source)
	File     string `json:"file"`             // file path relative to cli-dir
	Line     int    `json:"line"`             // 1-based source line; 0 for manifest findings
	Evidence string `json:"evidence"`         // the offending text
	Status   string `json:"status,omitempty"` // "" (== pending) or "accepted"; agent writes
	Note     string `json:"note,omitempty"`   // agent-written rationale for an accept decision

	// Pre-decision fields. The agent fills these BEFORE flipping
	// Status to "accepted" on kinds where requiresPreDecisionFields
	// is true; the gate forces per-item deliberation instead of
	// pattern-matching with one rationale across many findings.
	SpecSourceMaterial string `json:"spec_source_material,omitempty"`
	TargetDescription  string `json:"target_description,omitempty"`
	GapAnalysis        string `json:"gap_analysis,omitempty"`
}

ToolsAuditFinding is one mechanical issue discovered in either a Cobra command literal or an entry in the runtime tools manifest. Status and Note are ledger-only; the audit phase emits findings without them (omitempty keeps --json clean for downstream parsing). The agent edits the persisted ledger to flip Status to "accepted" with a Note explaining why a finding is fine as-is. On re-run the binary preserves these fields for any finding whose identity key matches.

Five finding kinds, two surfaces:

  • Cobra surface (internal/cli/*.go): "empty-short", "thin-short", "missing-read-only" — these check shell-out tools the runtime walker registers from Cobra metadata.
  • Manifest surface (tools-manifest.json): "empty-mcp-description", "thin-mcp-description" — these check the descriptions agents actually see for typed endpoint tools, where the source is the OpenAPI spec rather than the Cobra Short.

type ToolsAuditLedger 

type ToolsAuditLedger struct {
	Timestamp       time.Time           `json:"timestamp"`
	CLIDir          string              `json:"cli_dir"`
	Findings        []ToolsAuditFinding `json:"findings"`
	ScorecardBefore *ScorecardSnapshot  `json:"scorecard_before,omitempty"`
	Progress        *PolishProgress     `json:"progress,omitempty"`
}

ToolsAuditLedger is the on-disk snapshot of the last audit run.

ScorecardBefore is captured on the first audit run that finds no existing ledger and preserved across subsequent runs. It anchors the scorecard-delta gate: a polish run that "completes" with accepted thin-mcp-description findings but no movement in MCPDescriptionQuality is incomplete by definition.

Progress is an optional checkpoint the polish skill writes after deliberating on each finding. A re-invocation after a context flush reads it to resume mid-walk. When absent, the resume hint is the first pending finding in scan order.

type ValidateResult 

type ValidateResult struct {
	Passed     bool          `json:"passed"`
	CLIName    string        `json:"cli_name"`
	APIName    string        `json:"api_name"`
	HelpOutput string        `json:"help_output,omitempty"`
	Checks     []CheckResult `json:"checks"`
}

ValidateResult is the JSON output of publish validate.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.