Documentation
¶
Overview ¶
Package cmdutil provides the Factory injected into every command: lazily-resolved config, token store, and API client, plus the values of the persistent --json/--server/--app flags.
Index ¶
- func CanonicalMemoryRef(ref string) string
- func CanonicalNodeRef(ref string) string
- func CanonicalNodeURN(ref string) (string, error)
- func CanonicalizeURN(flag, input string) (string, error)
- func Confirm(io *output.IOStreams, yes bool, prompt string) error
- func ConfirmDeletion(io *output.IOStreams, yes bool, what string) error
- func EdgeDisplay(name *string, loc string) string
- func KeyValsToJSON(pairs []string, flag string) (*json.RawMessage, error)
- func MemoryParts(ref string) (root, slug string, ok bool)
- func NodeURN(memory, loc string) string
- func ParseJSONArg(s, what string) (*json.RawMessage, error)
- func ParseNodePropertySort(raw string) (*gqltypes.NodePropertySort, error)
- func ParseNodeWhere(raw string) (*gqltypes.NodeWhereInput, error)
- func ResolveAppRef(f *Factory, flag string) (string, error)
- func ResolveNodeRef(cmd *cobra.Command, client graphql.Client, memory, ref string) (string, error)
- func ResolveNodeURN(cmd *cobra.Command, client graphql.Client, ref string) (string, error)
- func ResolveTextInput(flag, value, file string, stdin io.Reader) (string, error)
- func ValidateAgentURNPath(flag, path string) error
- func ValidateURNPath(flag, path string) error
- func ValidateURNSlug(flag, slug string) error
- type Factory
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanonicalMemoryRef ¶ added in v0.6.0
CanonicalMemoryRef normalizes a memory reference to the canonical grammar-v2 flat URN hrn:mem:<root>:<slug> (#697 emission flip) for the server's memory(ref:) dispatch. A raw id (no separator) or an unrecognized shape passes through untouched — the server accepts every legacy spelling forever (#239), so the short forms the CLI advertises resolve consistently either way (#108).
func CanonicalNodeRef ¶ added in v0.8.0
CanonicalNodeRef canonicalizes a node reference for a server op that itself accepts an ID or a URN (spec 007 dispatch) — e.g. the object store's object(ref:)/updateObject/deleteObject, which forward ref to node(ref:). A scheme-prefixed URN passes through, a bare/legacy fully-qualified node URN (<org>::<memory>::<loc>) gets the canonical hrn:node: prefix, and a raw id (or any unrecognized shape) is left for the server to resolve. Unlike ResolveNodeURN it does NOT round-trip through resolveUrn, so a raw object id works without a lookup and without being rejected as "not a URN".
func CanonicalNodeURN ¶ added in v0.6.0
CanonicalNodeURN validates and normalizes a fully-qualified entry-node URN for the headless-run surface (schedule/webhook/trigger entryNodeUrn). It is the no-network half of ResolveNodeURN: a scheme-prefixed ref (hrn:/urn:) passes through verbatim; a bare <org>::<memory>::<loc> gets the canonical hrn:node: prefix; anything without the two `::` separators is rejected as ambiguous. The result is a URN the server stores, not a node ID — the entry node is resolved at run time, not now.
func CanonicalizeURN ¶ added in v0.8.0
CanonicalizeURN validates a scheme-prefixed Hadron URN and returns its parser-canonical form. It is intentionally kept as a thin wrapper for the spec-047 golden tests, which pin CLI parser parity to urn-lib-go.
func Confirm ¶ added in v0.2.0
Confirm gates a significant but non-deletion action behind the same rule as ConfirmDeletion: --yes skips the prompt, an interactive terminal is asked y/N, and a non-interactive caller without --yes is refused with a Usage error so the action is always explicit. `prompt` is the full question, without the trailing " (y/N)".
func ConfirmDeletion ¶
ConfirmDeletion gates destructive commands. --yes skips the prompt; otherwise an interactive terminal asks y/N, and a non-interactive caller (scripts, agents) is refused with a Usage error so deletions are always explicit.
func EdgeDisplay ¶ added in v0.3.0
EdgeDisplay is the human handle for an edge: its name, or its loc when the name is empty (spec 037 — an edge's name is optional, its loc is the identity, so a nameless edge still prints something addressable).
func KeyValsToJSON ¶ added in v0.6.0
func KeyValsToJSON(pairs []string, flag string) (*json.RawMessage, error)
KeyValsToJSON assembles repeated key=value flags into a JSON object (e.g. `--arg k=v` → an eventData object, `--param k=v` → a provider-params object). Each value is sent as JSON when it parses as JSON (numbers, booleans, arrays, objects), otherwise as a string. Returns nil for no pairs so the variable is omitted, not sent as `{}`. `flag` names the source flag in the error.
func MemoryParts ¶ added in v0.8.0
MemoryParts decomposes a memory reference into its grammar-v2 (root, slug) atoms. It accepts every spelling the CLI advertises — a bare "org:slug" or "org::slug", or an hrn:memory:/urn:memory: (v1) / hrn:mem:/urn:mem: (v2) URN — and normalizes the separator either way. ok is false for a raw id (no separator), an unrelated scheme (hrn:node:…), or a malformed multi-part ref; callers pass those through for the server to resolve.
func NodeURN ¶ added in v0.6.0
NodeURN composes the canonical grammar-v2 flat node URN hrn:node:<root>:<slug>:<loc…> for a (memory, loc). The memory's separators are normalized (single-colon and legacy "::" both accepted). It returns "" when the memory isn't an <org>::<slug> pair (a raw id, or a malformed multi-part ref) or loc is empty — composing a URN from those would produce an invalid one that resolves to nothing, silently defeating the existence probe (#129 review). The caller must probe otherwise.
func ParseJSONArg ¶ added in v0.6.0
func ParseJSONArg(s, what string) (*json.RawMessage, error)
ParseJSONArg parses a JSON-document flag (--policy, --args-schema). An empty string means "not provided" and returns nil so the variable is omitted; a non-empty value must be valid JSON. The `what` label names the flag in the error.
func ParseNodePropertySort ¶ added in v0.8.0
func ParseNodePropertySort(raw string) (*gqltypes.NodePropertySort, error)
ParseNodePropertySort parses the raw-JSON `--sort-property` value (server NodePropertySort, #719) into the bound gqltypes struct. Same grammar-parity contract as ParseNodeWhere: keys are path (required), field, as, direction.
func ParseNodeWhere ¶ added in v0.8.0
func ParseNodeWhere(raw string) (*gqltypes.NodeWhereInput, error)
ParseNodeWhere parses the raw-JSON `--where` predicate (grammar parity with the server's NodeWhereInput, #719) into the bound gqltypes struct. The JSON keys are the GraphQL field names verbatim (and/or/not, path, field, as, and one of eq|ne|in|lt|lte|gt|gte|between|exists|contains), so a user's predicate unmarshals straight through — the struct's omitempty tags then omit every field they left unset, which the server's "exactly one operator" leaf check requires (it counts any operator key that is not undefined). Deep validation (depth, leaf-arity, path shape) is the server's job and surfaces as BAD_USER_INPUT; this only enforces well-formed JSON and rejects unknown keys so a typo like "equals" fails loudly instead of being silently dropped.
func ResolveAppRef ¶ added in v0.6.0
ResolveAppRef resolves the App a headless-run command targets: the explicit --app flag when set, otherwise the configured/global App context (the same source `hadron app use` and the persistent --app write). Empty both ways is a usage error — every run/schedule/webhook command names an App. The ref is passed to the server verbatim, which dispatches an ID or a URN.
func ResolveNodeRef ¶ added in v0.3.0
ResolveNodeRef resolves a node reference into a node ID. With an empty memory it requires a fully-qualified URN (ResolveNodeURN). With a memory (the `org::memory` form, optionally hrn:/urn:-prefixed) the ref is a bare loc within that memory: a node URN is just <org>::<memory>::<loc>, so the two are joined and resolved. The memory form is the additive convenience; without it the strict-URN behavior is unchanged.
func ResolveNodeURN ¶
ResolveNodeURN turns a fully-qualified node URN into a node ID via Query.resolveUrn. Bare locs are rejected client-side with a usage error: node references always name the memory (same-loc collisions across memories made anything less ambiguous). A URN that resolves to a different entity kind is a usage error too.
func ResolveTextInput ¶ added in v0.3.0
ResolveTextInput resolves a text field that may be supplied inline, from a file, or on stdin — the same convention the --content / --content-file / "-" flags already use, factored out so every write flag behaves identically.
flag is the user-facing flag name (e.g. "abstract"): the inline value comes from --<flag>, the file from --<flag>-file, and a sentinel value of "-" reads stdin. The inline value and the file are mutually exclusive. Callers that gate on cmd.Flags().Changed decide whether an empty result means "clear" (an explicit empty string) or "leave unset".
A paragraph-length field with backticks or newlines is hostile to inline shell quoting, so --<flag>-file / stdin are the ergonomic path (issue #38).
func ValidateAgentURNPath ¶ added in v0.8.0
ValidateAgentURNPath checks an agent slug path supplied as a partial URN component. Unlike a node loc, an agent path may include owner/author context; urn-lib-go owns those shape rules.
func ValidateURNPath ¶ added in v0.7.0
ValidateURNPath checks a colon-delimited node loc. A loc is a single hierarchy leaf whose atoms are separated by single colons.
func ValidateURNSlug ¶ added in v0.7.0
ValidateURNSlug checks a single URN slug atom supplied on a create/rename flag. The shared urn-lib owns the create-time slug policy.
Types ¶
type Factory ¶
type Factory struct {
IOStreams *output.IOStreams
HTTPClient *http.Client
// Persistent flag values, bound by the root command.
JSON bool
ServerFlag string
AppFlag string
// Overridable for tests.
ConfigFn func() (*config.Config, error)
TokenStoreFn func() store.Store
// contains filtered or unexported fields
}
func NewFactory ¶
func NewFactory() *Factory
func (*Factory) App ¶
App resolves the App URN context: --app flag, then config default. Empty means no App context, which the server treats as fine.
func (*Factory) GraphQLClient ¶
GraphQLClient returns an authenticated genqlient client, failing with the AuthRequired exit code when no credentials are present.
func (*Factory) Server ¶
Server resolves the server base URL: --server flag, then HADRON_SERVER env, then config, then the hosted default.
func (*Factory) Token ¶
func (f *Factory) Token() (string, auth.TokenSource, error)
Token returns the active token and its source for the resolved server ("" source when unauthenticated). HADRON_TOKEN is checked before the token store so CI never triggers a keyring probe.
Source Files