package commandkit

import (
	"context"
	"io"
)

// Identity describes the application or component represented by CommandKit.
//
// Version and Revision are caller supplied metadata. CommandKit does not infer
// them from an executable or mutate them.
type Identity struct {
	// Name is the human-readable application or component name.
	Name string
	// Version is the caller-supplied version string.
	Version string
	// Revision is the caller-supplied source revision.
	Revision string
}

// Streams contains the output destinations associated with a command
// invocation.
type Streams struct {
	// Out receives help and command reports.
	Out io.Writer
	// Err receives diagnostics and usage guidance.
	Err io.Writer
}

// Invocation provides execution context and output streams to a command
// handler. For command aliases, EnteredPath and CanonicalPath expose the route
// the caller used and the selected canonical command path. Both omit the
// executable name, flags, and operands.
type Invocation struct {
	// Context carries caller cancellation and request-scoped values.
	Context context.Context
	// Streams are the caller-selected output destinations.
	Streams Streams

	enteredPath   string
	canonicalPath string
}

// EnteredPath returns the command path used to invoke the selected command,
// excluding the executable name, flags, and operands. It is empty for an
// Invocation that was not created by command execution.
func (inv Invocation) EnteredPath() string { return inv.enteredPath }

// CanonicalPath returns the selected command's canonical path after resolving
// aliases, excluding the executable name, flags, and operands. It equals
// EnteredPath for a direct canonical invocation and is empty for an Invocation
// that was not created by command execution.
func (inv Invocation) CanonicalPath() string { return inv.canonicalPath }