Module extensions 

CLI extension registry, match, preexec, and expand (ADR-0022). CLI extension registry: load, merge, match, expand, and dispatch.

Extensions are an argv preprocessor inside the wyvern crate (ADR-0022). They produce existing wyvern_schema::Command JSON only — no new host dialog types. Phase E --interactive reuses this module; MCP tools consume pre-expanded Command JSON.

Examples

use std::path::Path;
use wyvern::extensions::{build_match_context, expand_and_validate, ExtensionRegistry};

let registry = ExtensionRegistry::load(Path::new("share/wyvern/extensions.json"), None)?;
let argv = vec!["doc.md".to_string()];
if let Some(matched) = registry.match_argv(&argv) {
    let ctx = build_match_context(&matched, matched.extension());
    let expanded = expand_and_validate(matched.extension(), &ctx)?;
    assert_eq!(expanded.command["type"], "markdown");
}

Structs

ArgName

Declared {arg:name} flag name (no leading dashes).

BinaryName

Bare PATH binary name (non-empty, no path separators).

ExpandSpec

Expand templates for command JSON and host overrides.

ExpandedInvocation

Validated expansion ready for the existing host pipeline.

ExtensionDef

One registry entry after merge and extends resolution.

ExtensionId

Validated, non-empty extension identifier.

ExtensionIdError

Failure from ExtensionId::try_from.

ExtensionRegistry

Merged, extends-resolved extension registry.

HostExpandSpec

Host template object (ui_root only).

HostOverrides

Host overrides produced by phase-2 expand (ui_root only in Phase F).

MatchContext

Context collected from an ExtensionMatch plus optional preexec outputs.

MatchOutcome

Result of walking the registry with skip diagnostics.

MatchSpec

Match fields from the registry schema.

MatchToken

Non-empty match token (suffix, filename, or argv prefix element).

PathRequiresProbe

Default probe that searches PATH (and Windows PATHEXT).

PreexecSpec

Preexec subprocess declaration.

ScriptAssets

Embedded scripts/ext/** preexec helpers.

ScriptOutput

Successful wait outcome for run_script.

ScriptRequest

Subprocess request shared by extension preexec and workflow hooks.

ShareAssets

Embedded share/wyvern/** assets (extensions.json, packaged UI extras).

SkillArg

One declared {arg:name} / {arg:name:repeat} flag.

SkillRecord

One catalog / help record for a resolved extension (REQ-0132).

SkillRequire

One preexec.requires binary and its current PATH availability.

SkippedExtension

Extension that would have matched argv but was skipped for requires.

Enums

ExtensionError

Structured extension-engine failure.

ExtensionMatch

Successful argv match against one extension.

ExtensionsCmdError

Failure from the extensions built-in.

NearMissKind

Why remainder argv did not match an extension (REQ-0136).

PreexecFailureKind

Why a preexec subprocess failed.

ScriptError

Failure from run_script (spawn, timeout, wait, or stdout capture).

SkillSource

Whether a catalog entry came from shipped defaults or a project file.

StdoutCapture

Stdout capture mode for PreexecSpec.

TemplateErrorKind

Why ExtensionError::Template failed (RBP-F006).

Constants

SHIPPED_EXTENSIONS_JSON

Shipped defaults compiled into the binary (dev + cargo install).

Traits

RequiresProbe

Probe used at match time for preexec.requires.

Functions

binary_on_path

Return whether name resolves on PATH.

build_match_context

Build the initial match context (no preexec outputs yet).

build_skill_record

Build a help-oriented SkillRecord from a resolved extension.

build_skill_records

Build a SkillRecord for every merged extension, in registry order.

classify_near_miss

Classify a no-match remainder using the Phase G near-miss table.

create_tmpdir

Create a secure temp directory for {tmpdir}.

emit_near_miss

Serialize a near-miss as the existing StderrError envelope.

expand_and_validate

Create tmpdir if needed, run preexec, expand, and validate.

expand_command_host

Phase 2: expand command / command_from_file and host.

expand_preexec_args

Phase 1: expand preexec.cmd and preexec.args only.

extensions_usage_message

Usage text for wyvern extensions --help / -h.

find_workspace_root

Walk start and parents looking for share/wyvern/extensions.json.

format_extensions_list

Format each extension as a format_skill_card block.

format_skill_card

Format one skill as the single help / list / show text card.

infer_wizard_root

Walk from the file’s directory until wizard.json or pages/ is found.

is_help_only_tokens

Returns whether every token is --help or -h (and at least one is present).

last_created_tmpdir

Path of the temp dir created by the last expand_and_validate on this thread.

match_extension_help

Match an extension whose remaining tokens are only --help / -h.

match_kind_summary

relpath_from_ui_root

{path} relative to {wizard_root} using / separators.

resolve_wyvern_share

Resolve {wyvern_share} to a unified directory (dev workspace or embed).

resolve_wyvern_share_with

Resolve {wyvern_share} from injectable inputs (no process-global mutation).

run_extensions_command

Run wyvern extensions …; returns stdout text on success.

run_preexec

Runs the extension preexec command. On timeout the child is killed so a piped stdout reader cannot keep buffering after the CLI has moved on. See WYVERN_PREEXEC_TIMEOUT_SECS.

run_script

Spawn a subprocess with timeout, optional stdin, and stderr tail.

skill_help_command

Recovery --help using the invocation prefix, not the extension id.