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 caller-owned output destinations associated with an
// invocation. Out receives substantive results; Err receives messages,
// terminal explanations, usage guidance, and CommandKit diagnostics. Nil
// destinations are replaced with io.Discard. CommandKit does not close or flush
// supplied writers.
type Streams struct {
	// Out receives help and command reports.
	Out io.Writer
	// Err receives diagnostics and usage guidance.
	Err io.Writer
}

func normalizeStreams(streams Streams) Streams {
	if streams.Out == nil {
		streams.Out = io.Discard
	}
	if streams.Err == nil {
		streams.Err = io.Discard
	}
	return streams
}

// Invocation provides execution context and invocation-scoped reporting to a
// command handler. Execute finalizes its reporter before returning. 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

	reporter      *Reporter
	enteredPath   string
	canonicalPath string
}

// Reporter returns the reporting facility supplied for this invocation. A
// manually constructed Invocation has no reporter.
func (inv Invocation) Reporter() *Reporter { return inv.reporter }

// 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 }