Create, test and reuse Sidekick components in xmd repl #896

Story

As a person working with the Sidekick in xmd repl, I want it to create and test reusable XMD components that subsequent REPL entries can invoke, so useful work becomes part of the vocabulary we share rather than code we copy into every entry.

For example, I ask the Sidekick to create a greeting component. It writes Greeting.md and a companion Greeting.test.md into the components directory provided by the REPL, runs the Markdown tests, and receives their results. If a test fails, it can revise the component or test and run the tests again. My next entry invokes <Greeting /> and executes that file through ordinary component resolution. I do not restart the REPL or configure an include path.

“Components” here means executable Markdown or TypeScript components used by XMD programs, rather than the terminal UI's internal components.

Current gap

The REPL already searches components and . relative to its working directory. Its execution profile supplies those paths to entry validation and execution. That provides the underlying resolution mechanism, but does not provide and expose a managed components directory to the Sidekick at startup.

#883 gives the Sidekick a conversation and operations for inspecting bindings, preparing the shared entry draft and submitting work. It does not establish a shared place for authoring components, the lifecycle of those files, or an agent-facing way to run their Markdown tests and receive the results.

Accepted direction

• REPL startup automatically provides a components directory and includes it in the REPL's component-resolution paths before the first entry.
• The Sidekick knows the directory's location and how to write component files into it. No manual include option or restart is required.
• A component successfully written before the next entry is submitted is available to that entry's validation and execution under its ordinary component name.
• The person and Sidekick use the same component definitions when submitting REPL entries. A component is reusable across later entries, rather than a private definition attached only to one Sidekick response.
• Creating a component makes it available; invoking it in an entry executes it. Merely writing the file does not run its body or submit an entry.
• The Sidekick can create companion Markdown component tests and explicitly request their execution without leaving or restarting the REPL. It can select a test document or run the component directory's test suite using the existing Markdown-testing conventions.
• Test execution returns the actual outcome and diagnostics to the Sidekick, including failing test identities and assertion or execution errors, so it can fix the files and rerun. Successful component creation is distinct from passing tests; a run with no discovered tests does not report success.

Decisions before implementation

Settle these with the Product Owner before freezing a Planner handoff:

1. Location and lifetime. Does startup create the working directory's existing components/, provide a separate execution-owned directory, or use another location? Determine persistence after exit, behavior on cold reopen, and whether separate REPLs share files. An existing directory's contents must be accounted for explicitly.
2. Authoring interface. How is the directory exposed to the Sidekick, and does it write through existing file components or a dedicated REPL operation? Settle the public spelling, supported file forms, replacement behavior and feedback on success or failure. Do not assume a new shell command or general filesystem permission is necessary.
3. Resolution order and discovery. Where does this directory sit relative to repository components and other existing sources? Define collisions and confirm that the relevant syntax/documentation surface describes the same component an entry resolves. Existing protected names retain their protection.
4. Updates and entry boundaries. Define when a completed write or replacement becomes visible, including writes overlapping entry submission or an already-running entry. The next-entry guarantee must not depend on restarting or accidentally retaining a stale resolver/import cache.
5. Testing interface. Settle the operation the Sidekick uses to select and run Markdown tests, its result shape, and how results are shown to the person. Define test-run lifetime, cancellation, overlap with entry execution or file edits, and which file version a result describes. Use the provided component directory in test resolution so the tests exercise the definitions available to subsequent entries.
6. History and recovery. Determine how authored files survive reopening and how an unfinished entry resumes if a file has changed or disappeared. Historical inspection uses recorded execution facts rather than executing current component files or rerunning the Sidekick.

The confirmed requirement is next-entry availability. Same-entry authoring and invocation, live replacement inside running entries, and cross-REPL sharing are not implied by it.

Architecture boundaries

Reuse the ordinary component resolver and durable import path. A supplied directory can be part of the REPL's fixed execution profile from startup while its files are authored over time; discovering those files does not require rebuilding the profile for each entry.

Reuse the existing Markdown-testing engine and xmd test discovery, assertion, failure and per-document isolation semantics. A test request activates the real testing harness; loading <Test> as an ordinary component without testing mode is insufficient. Test execution has its own owned scope and reports its outcome through the Sidekick feedback channel, rather than treating test report text as a command result. Test bindings and registrations do not become REPL entry bindings merely because the Sidekick ran a test.

The REPL root continues to own entry admission. A Sidekick-authored component submitted through the shared input follows the same validation and execution path as a person's entry. File authoring and failures have an observable owner and truthful feedback to the Sidekick.

Component availability does not itself widen the Sidekick's generated-XMD evaluation ceiling or grant new effects to a component. Keep file-writing authority and ordinary entry execution explicit in the accepted design. Preserve protected component identities and the established behavior for malformed local definitions: report the failure rather than silently selecting a different implementation.

Product verification proposal

• Start a fresh REPL without manually creating a directory. Ask the Sidekick to write Greeting.md, then submit <Greeting /> as the next entry. Show the actual file, the admitted invocation and its rendered result through the production resolution path.
• Have the Sidekick create Greeting.test.md, run it against the authored component, and receive a passing result. Introduce an incorrect expected value, observe the identified assertion failure, fix it and rerun successfully. A source-validation check or an inactive <Test> that executes no assertions fails this comparison.
• Run the directory suite with passing and failing test documents. The Sidekick receives the aggregate failure and individual diagnostics; an empty test selection reports no tests rather than a pass. Verify test-local state does not leak into later tests or ordinary REPL entries.
• Invoke the same component in another entry. Demonstrate reuse rather than source pasted into each entry or a definition available only inside the Sidekick conversation.
• Write another component after the REPL has already executed entries. The following entry finds it without restart. A startup-only directory scan fails this comparison.
• Show that writing alone produces no component-body execution and no admitted entry. A failed write does not report successful availability.
• Exercise a malformed component and a name collision under the approved resolution rules. Demonstrate that validation and execution agree on the selected definition.
• Exercise the approved replacement, concurrent-write and reopen journeys. Inspect an earlier entry after its component file changes: inspection neither re-executes the current file nor contacts a provider.

The Architect and Product Owner refine this proposal before the Planner freezes acceptance. Existing entry and execution regression entrypoints include packages/cli/tests/repl-entries.test.ts and packages/cli/tests/repl-execution.test.ts; the implementation plan identifies the focused tests for the agreed directory, Sidekick authoring and test-execution boundaries. Existing testing-engine regression entrypoints include packages/testing/tests/use-testing.test.ts and packages/testing/tests/test-component.test.ts.

Relationships and scope

Follow-up to #883, related to REPL Quest #827. Coordinate with active Sidekick work, including PR #890, without changing its accepted implementation target. This Story owns component authoring, Markdown component-test execution and sharing through the startup-provided directory.

Relevant contracts are specs/repl-spec.md, specs/testing-spec.md, the component model and resolution/import sections of specs/executable-mdx-spec.md, and architecture.md. Relevant entry boundaries include packages/cli/src/repl-profile.ts and packages/cli/src/repl/session.ts. Update those descriptions with the accepted lifecycle and resolution behavior as part of delivery.

Exclude a component registry service, package publishing, terminal UI extensions, new language syntax, a new component loader and general session management.