cmd

Documentation

Overview

Package cmd implements the qvr Cobra command tree: one file per command, all registered on rootCmd, with a persistent --output flag that routes structured data to stdout and diagnostics to stderr.

Index

• Variables
• func Execute()
• type CacheCleanOutput
• type CacheEntry
• type CacheListOutput
• type CachePruneOutput
• type LockResolveEntryResult
• type LockResolveOutput
• type UpgradeEntryResult
• type UpgradeOutput
• type VerifyOutput
• type VerifySummary

Variables

var ErrPublishForkNeedsInstall = errors.New("--fork requires an installed skill name; pass the skill name (not a path) and run `qvr edit <skill>` first")

ErrPublishForkNeedsInstall is surfaced when --fork is passed but the arg doesn't match a lock entry (and so we'd otherwise fall through to greenfield mode, which can't accept --fork).

Functions

func Execute

func Execute()

Execute runs the root command and is the binary's sole entry point from main. On failure it prints the error (a structured JSON envelope when --output json, a plain `error:` line otherwise) and exits 1; commands that already surfaced their own failure output signal that via errJSONHandled / errTextHandled so the envelope is not duplicated.

Types

type CacheCleanOutput

type CacheCleanOutput struct {
	Removed            []string `json:"removed,omitempty"`
	WouldRemove        []string `json:"wouldRemove,omitempty"`
	FreedBytes         int64    `json:"freedBytes,omitempty"`
	WouldFree          int64    `json:"wouldFree,omitempty"`
	DryRun             bool     `json:"dryRun"`
	IncludedRegistries bool     `json:"includedRegistries"`
	Errors             []string `json:"errors,omitempty"`
}

CacheCleanOutput is the JSON envelope for `qvr cache clean`. It mirrors CachePruneOutput's Removed/WouldRemove split (issue #122) so a dry-run can never be mistaken for a real wipe by a scriptable consumer. IncludedRegistries records whether the bare clones were dropped too (--registries).

type CacheEntry

type CacheEntry struct {
	Path      string `json:"path"`
	Reachable bool   `json:"reachable"`
	SizeBytes int64  `json:"sizeBytes"`
}

CacheEntry describes one worktree in the cache, used by both list and prune output. Reachable is true when the worktree is referenced by at least one known lock file.

type CacheListOutput

type CacheListOutput struct {
	Entries         []CacheEntry `json:"entries"`
	TotalBytes      int64        `json:"totalBytes"`
	OrphanBytes     int64        `json:"orphanBytes"`
	MissingProjects []string     `json:"missingProjects,omitempty"`
}

CacheListOutput is the JSON envelope for `qvr cache list`.

type CachePruneOutput

type CachePruneOutput struct {
	Removed        []string `json:"removed,omitempty"`
	WouldRemove    []string `json:"wouldRemove,omitempty"`
	ForgottenProjs []string `json:"forgottenProjects,omitempty"`
	FreedBytes     int64    `json:"freedBytes,omitempty"`
	WouldFree      int64    `json:"wouldFree,omitempty"`
	DryRun         bool     `json:"dryRun"`
	// MissingProjects covers project lock files that vanished — surfaced
	// in both list and prune output. List used to print these only as
	// trailing `! …` warnings in text and as a top-level JSON field;
	// prune merges them into the count via ForgottenProjs after the run.
	MissingProjects []string `json:"missingProjects,omitempty"`
	Errors          []string `json:"errors,omitempty"`
	// Derived-cache sweep (reconstructible memos backing fast materialization):
	// the content-store blobs and the global identity / provenance caches. Their
	// reclaimed bytes are folded into FreedBytes / WouldFree; these counts are
	// the per-cache detail.
	IdentityRemoved   int `json:"identityRemoved,omitempty"`
	ProvenanceRemoved int `json:"provenanceRemoved,omitempty"`
	BlobsRemoved      int `json:"blobsRemoved,omitempty"`
}

CachePruneOutput is the JSON envelope for `qvr cache prune`.

Removed/FreedBytes populate on a real prune; WouldRemove/WouldFree populate on --dry-run (issue #122). Pre-fix the dry-run path reused the `removed`/`freedBytes` names, so a scriptable consumer reading `removed` after a dry-run would think the prune ran — a PagerDuty footgun under pressure. The field-name split is the on-disk contract.

type LockResolveEntryResult

type LockResolveEntryResult struct {
	Name string `json:"name"`
	Ref  string `json:"ref,omitempty"`
	// Status vocabulary mirrors `qvr lock upgrade`'s verbs:
	//   "repinned"         — wrote a new commit to the entry
	//   "would-repin"      — --dry-run says we'd re-pin
	//   "ref-updated"      — --from-toml rewrote the ref; commit unchanged (#246)
	//   "would-ref-update" — --dry-run says we'd rewrite the ref (same commit)
	//   "unchanged"        — entry not modified at all
	//   "skipped"          — link/edit/standalone entry with no registry upstream
	//   "failed"           — couldn't resolve the ref (e.g. registry not fetched)
	Status    string `json:"status"`
	OldCommit string `json:"oldCommit,omitempty"`
	NewCommit string `json:"newCommit,omitempty"`
	// OldRef is set on "ref-updated"/"would-ref-update": the ref the lock
	// carried before --from-toml adopted qvr.toml's declared ref.
	OldRef  string `json:"oldRef,omitempty"`
	Message string `json:"message,omitempty"`
}

LockResolveEntryResult is one row of `qvr lock` (standalone re-resolve).

type LockResolveOutput

type LockResolveOutput struct {
	LockVersion int                      `json:"lockVersion"`
	Entries     []LockResolveEntryResult `json:"entries"`
	DryRun      bool                     `json:"dryRun"`
}

LockResolveOutput is the top-level shape `qvr lock` emits in JSON mode.

type UpgradeEntryResult

type UpgradeEntryResult struct {
	Name string `json:"name"`
	// Status vocabulary matches the text-mode verbs:
	//   "upgraded"      — wrote a new subtree hash to disk
	//   "would-upgrade" — --dry-run says we'd write
	//   "unchanged"     — entry already had a hash + complete provenance
	//   "skipped"       — link install, or hash computation failed
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

UpgradeEntryResult is one row of `qvr lock upgrade` output.

type UpgradeOutput

type UpgradeOutput struct {
	LockVersion int                  `json:"lockVersion"`
	Entries     []UpgradeEntryResult `json:"entries"`
	DryRun      bool                 `json:"dryRun"`
}

UpgradeOutput is the top-level shape `qvr lock upgrade` emits in JSON mode.

type VerifyOutput

type VerifyOutput struct {
	LockVersion int                       `json:"lockVersion"`
	Entries     []skill.VerifyEntryResult `json:"entries"`
	Summary     VerifySummary             `json:"summary"`
	// Error populates only on --frozen / --strict failure paths and lets
	// JSON consumers parse stdout as a single document. The text path uses
	// the same string as the printed `Error: ...` line on stderr.
	Error string `json:"error,omitempty"`
}

VerifyOutput is the top-level shape `qvr lock verify` emits in JSON mode.

type VerifySummary

type VerifySummary struct {
	OK         int `json:"ok"`
	Drift      int `json:"drift"`
	Unverified int `json:"unverified"`
	Missing    int `json:"missing"`
	Link       int `json:"link"`
	Failed     int `json:"failed"`
	Repaired   int `json:"repaired,omitempty"`
}

VerifySummary aggregates per-status counts for the JSON output.