Evaluate `xmd` against Configliere’s route API

[taras]

Story

As an XMD maintainer collaborating with Configliere, I want to express xmd through Configliere’s proposed route API, so both projects can inspect the diff from a real, non-trivial consumer and decide whether the API is ready to adopt.

The outcome is a draft pull request against Executable.md. It is an evaluation artifact and a source of upstream feedback; this issue does not authorize merging the dependency or changing the public xmd command line.

Concrete comparison

Use these exact upstream references:

• Preview package: https://pkg.pr.new/configliere@30
• API guide pinned at the preview head: https://github.com/thefrontside/configliere/blob/fb52bc6567dadd2528e684b123d013eb9b701ace/README.md
• Upstream discussion: Project Tom Hagen: document dynamic parsing thefrontside/configliere#30

At issue creation, the preview reports commit fb52bc6567dadd2528e684b123d013eb9b701ace and manifest version 0.4.0-pr+dbd7d191ab8aff37c71cc03bc4688ad372ec7e23. The draft records the exact artifact it actually consumes so a later update to the PR preview cannot silently change the comparison.

Today, XMD depends on configliere@^0.4.0 and defines its command line with program(), commands(), object(), field(), and cli(). The proposed API describes immutable command() and route() pipelines whose parse() result narrows by method and route, with checkpoints for configuration that can only be discovered after I/O.

A representative public path remains unchanged:

xmd run README.md#Test/Focused --verbose
xmd workflow status <run-id> --json
xmd plan "prepare the release program"

The draft shows how those same invocations are defined, parsed, typed, and dispatched through the proposed API.

Current gap

XMD exercises more than a static command tree. It has a default run form, nested workflow actions, options owned by different commands, document-derived --props-* options discovered only after reading a definition, multiple configuration sources, help and version requests, the -- separator, the standard-input - argument, repeatable options, and strict refusals for malformed or unknown input.

The current adapter also performs explicit scans around behavior the released parser cannot express or report safely, including unknown options, missing values, boolean options written with =, and document arguments that begin with -. Reading the proposed README does not establish which of that code disappears, which becomes clearer, and which still belongs to XMD. A real port makes those tradeoffs visible.

Evaluation contract

• Start from current main and use the preview package rather than a locally modified Configliere checkout.
• Apply the proposed API to XMD’s real command definitions and dispatch boundary. A toy command or parallel demonstration does not answer the issue.
• Keep Configliere’s parsing synchronous. File, environment, Git, and other I/O remains owned by XMD’s Effection operations, including work needed to resume a parsing checkpoint.
• Preserve the existing public command grammar, source precedence, help intent, exit behavior, and failure ordering while evaluating the API. Do not change expectations merely to make the port pass.
• When the proposed API intentionally produces a different observable result, retain a focused comparison and classify it as an XMD contract change, a Configliere gap, or an improvement that needs separate approval.
• Follow the repository dependency workflow: update the lock explicitly, rerun deno task setup, and do not leave the prepared dependency layouts inconsistent.
• Open the result as a draft pull request. Its description explains the important before/after shapes and links any actionable Configliere feedback.

Two preview details must be resolved by evidence rather than assumption: the tarball manifest names configliere while the README imports @frontside/configliere, and the tarball contains a dynamic module while its root declaration currently exposes extend and checkpoint but not dynamic.

Questions to answer

1. Does the route model make the top-level command tree, default run shorthand, and nested workflow actions easier to define and dispatch?
2. Does narrowing on method and route remove unsafe or duplicated configuration checks at the handler boundary?
3. Can a checkpoint represent document-derived property options without moving I/O into Configliere or weakening XMD’s “inspect before effects” ordering?
4. Which current argument scans become unnecessary, and which still express XMD-specific grammar that should remain outside the library?
5. Are help, version, unknown-option, missing-value, separator, repeatable-option, and multi-source behaviors compatible with XMD’s existing contract?
6. Does the preview resolve and typecheck through XMD’s Deno, Node, Bun, and compiled entrypoints?
7. Which API, documentation, package-export, or diagnostic changes would make the real consumer diff smaller or clearer?

Acceptance

• A linked draft PR contains the real migration diff and is explicitly not offered for merge.
• The PR records the exact preview package identity and pinned API documentation used.
• Existing black-box CLI tests remain unchanged where public behavior is unchanged.
• Focused evidence covers top-level help and version, default and named command routing, nested workflow routing, document-derived properties, source precedence, malformed input, and at least one entrypoint under each supported runtime.
• Typechecking demonstrates the inferred intent and route models at XMD’s dispatch boundary; casts do not conceal gaps in narrowing.
• The PR records every remaining XMD-owned pre-scan and explains the observable contract that requires it.
• The findings compare the released and proposed APIs for definition clarity, dispatch typing, dynamic phases, diagnostics, runtime packaging, and total migration size.
• Actionable upstream findings are linked from the draft PR to Configliere’s discussion.
• The conclusion recommends one of: promote the draft into separately approved adoption work, request upstream changes and repeat the experiment, or defer adoption. No branch is merged as part of this spike.

Related work

Issue #173 adds document-declared positional properties. This spike does not implement it, but records whether the proposed parameter and checkpoint model materially changes that issue’s feasible design.

Out of scope

• Merging or releasing the preview dependency.
• Changing public xmd syntax, help, precedence, or errors without separate approval.
• Implementing Let root documents declare ordered positional arguments #173.
• Publishing or renaming Configliere packages.
• Adding a permanent compatibility layer solely to make the experiment appear complete.