Load external components with xmd repl --include #968

An author can start xmd repl with reusable components stored outside the current workspace, using the same --include option as xmd run and xmd test.

For example, from a prepared source checkout:

deno task xmd repl --include /absolute/path/to/shared-components

If that directory contains Greeting.md, an entry can invoke <Greeting /> without copying the file into the workspace's components/ directory or switching to xmd run.

Current failure

The REPL rejects the command before opening the terminal:

unrecognized option for xmd repl: --include

This affects the repository source CLI launched with deno task xmd repl, not just an older installed executable. Current main omits include from replConfig and omits --include from the REPL value-option grammar in packages/cli/src/cli.ts. The existing run and test commands already accept component search directories.

Acceptance

• xmd repl --include <directory> and --include=<directory> accept external component directories. deno task xmd repl exposes the same behavior.
• Repeated --include options preserve their order and use the same selection and relative-path semantics as run and test. Explicit includes replace the default search list; omitting the option preserves the current defaults.
• Entry validation, execution and component discovery use the same selected directories. With two included directories defining the same ordinary component, the first directory wins consistently. Existing protected component names remain protected.
• Help describes the option. A missing option value produces a useful argument error; genuinely unknown options remain rejected.
• The option is accepted when reopening a REPL location, while completed historical work remains inspectable without re-executing agents or component effects.

Verify the CLI grammar/help boundaries and a real source-launched REPL journey with a component available only in an external directory. Include the ordered collision and no-option controls. Existing focused regression entrypoints include packages/cli/tests/cli-help.test.ts and packages/cli/tests/repl-boundaries.test.ts; keep the REPL specification aligned with the accepted command behavior.

This ticket covers selecting existing component directories. #896 owns Sidekick component authoring and its managed directory. #941 owns the separate failure after repeated component calls; repairing that projection defect is not part of this flag fix.

Delivery audit — 2026-10-31

Merged --include supports ordered external lookup through grammar/help, execution and discovery, with collision/protected-name, omitted-option and cold-reopen terminal controls.

Merged delivery: #972.

Existing implementation and regression evidence: packages/cli/tests/repl-boundaries.test.ts, packages/cli/tests/cli-help.test.ts. This audit reuses the recorded evidence and inspects merged source; it runs no new tests or model calls.