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 CanonicalNodeURN(ref 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 NodeURN(memory, loc string) string
- func ParseJSONArg(s, what string) (*json.RawMessage, 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 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 for the server's memory(ref:) dispatch: a raw id (no colon) or an already hrn:/urn:-prefixed URN passes through; a bare "org:slug" / "org::slug" becomes the canonical hrn:memory:org::slug, so the short forms the CLI advertises resolve consistently instead of failing as "not found" (#108).
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 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 NodeURN ¶ added in v0.6.0
NodeURN composes the canonical hrn:node URN for a (memory, loc). The memory's org::slug separators are normalized (single-colon accepted), so it emits the double-colon <org>::<memory>::<loc> the server resolves. It returns "" when the memory isn't EXACTLY an org::slug pair (a raw id, or a malformed multi-part ref like foo::bar::baz) 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 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 ValidateURNPath ¶ added in v0.7.0
ValidateURNPath checks a colon-delimited URN path (a node loc, or an agent slug that may carry an author-org atom) the way the server's `validatePathSegment` does: every ':'-separated atom must be a valid slug atom. It rejects the empty path, leading/trailing/doubled colons (empty atoms), and any atom with a space or illegal character.
func ValidateURNSlug ¶ added in v0.7.0
ValidateURNSlug checks a single URN slug atom (an org or app slug) supplied on a create/rename flag, rejecting the malformed input — spaces, empty, over-length, illegal characters — that the server would reject anyway, but before the network round-trip and with a clearer, flag-anchored message. `flag` names the source flag (e.g. "--urn") for the error.
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