CliSubprocessCore.Command (CliSubprocessCore v0.1.0)

Copy Markdown View Source

Normalized subprocess invocation data shared by provider profiles.

The module also exposes the shared provider-aware one-shot command lane through run/1 and run/2.

Summary

Types

env_key()
env_map()
env_value()
run_error()
run_result()
t()
user()

Functions

argv(command)

Returns the executable and arguments as an argv list.

merge_env(command, env)

Merges environment variables into the invocation.

new(command, args \\ [], opts \\ [])

Builds a normalized invocation struct.

put_env(command, key, value)

Adds or replaces a single environment variable.

run(opts)

Runs a provider-aware one-shot command through the shared transport-owned non-PTY lane.

run(invocation, opts)

Runs a prebuilt normalized invocation through the shared non-PTY command lane.

to_transport_command(command)

Projects a CLI-domain invocation onto the generic transport substrate.

validate(command)

Validates the invocation contract expected by the provider profile behaviour.

Types

env_key()

@type env_key() :: String.t()

env_map()

@type env_map() :: %{optional(env_key()) => env_value()}

env_value()

@type env_value() :: String.t()

run_error()

@type run_error() :: CliSubprocessCore.Command.Error.t()

run_result()

@type run_result() :: CliSubprocessCore.Command.RunResult.t()

t()

@type t() :: %CliSubprocessCore.Command{
  args: [String.t()],
  clear_env?: boolean(),
  command: String.t(),
  cwd: String.t() | nil,
  env: env_map(),
  user: user()
}

user()

@type user() :: String.t() | nil

Functions

argv(command)

@spec argv(t()) :: [String.t()]

Returns the executable and arguments as an argv list.

merge_env(command, env)

@spec merge_env(t(), map()) :: t()

Merges environment variables into the invocation.

new(command, args \\ [], opts \\ [])

@spec new(
  String.t() | CliSubprocessCore.CommandSpec.t(),
  [String.t()] | keyword(),
  keyword()
) :: t()

Builds a normalized invocation struct.

put_env(command, key, value)

@spec put_env(t(), String.t() | atom(), String.t() | atom() | number() | boolean()) ::
  t()

Adds or replaces a single environment variable.

run(opts)

@spec run(keyword()) :: {:ok, run_result()} | {:error, run_error()}

Runs a provider-aware one-shot command through the shared transport-owned non-PTY lane.

Reserved command-lane options are:

  • :provider
  • :profile
  • :registry
  • :stdin
  • :timeout
  • :stderr
  • :close_stdin

All remaining options are passed through to the resolved provider profile's build_invocation/1 callback.

run(invocation, opts)

@spec run(
  t(),
  keyword()
) :: {:ok, run_result()} | {:error, run_error()}

Runs a prebuilt normalized invocation through the shared non-PTY command lane.

to_transport_command(command)

@spec to_transport_command(t()) :: ExternalRuntimeTransport.Command.t()

Projects a CLI-domain invocation onto the generic transport substrate.

validate(command)

@spec validate(t()) ::
  :ok
  | {:error, {:invalid_command, term()}}
  | {:error, {:invalid_args, term()}}
  | {:error, {:invalid_cwd, term()}}
  | {:error, {:invalid_env, term()}}
  | {:error, {:invalid_clear_env, term()}}
  | {:error, {:invalid_user, term()}}

Validates the invocation contract expected by the provider profile behaviour.