Skip to content

Commit b66a4af

Browse files
committed
✨ Install trusted Plugins before a document runs (#818)
XMD gains one generic, trusted Plugin boundary. A distribution supplies an ordered list of bundled Plugins and an operator appends package or filesystem Plugins with a repeatable `--plugin`. The complete list is loaded, admitted and installed before anything imports a root document. A Plugin is a plain structural value carrying a name and one optional `install(request)`. What it returns crosses at the boundary a trusted host already had — declared Markdown, structural syntax and its handler, journal admissions — and it composes a run through three stable, namespaced contextual APIs published from `@executablemd/core/api`: `Document`, `RootMetadata` and `ActivePlugins`. `@executablemd/runtime/api` publishes the existing `Config` Api a Plugin reads timeouts and verbosity through. Both root exports are unchanged. `Document`'s terminal answers with `<Document />`. Canonical core scans the composed envelope once and splices the already parsed, already target-selected root segments in at each placeholder, at their authored positions — so an unwrapped run is the run it always was, and an authored `<Document />` is an ordinary element that projects nothing. Execution, `inspectDocument` and document validation compose the root through one shared path. The #817 review graph becomes the first production Plugin: `@executablemd/code-review-agent` exports it as the package default, built from the existing `reviewComponentDeclarations()`/`useReviewComponents()` boundary with all thirty-five declarations, six reserved registrations, origins, digests and packaged assets unchanged. `packages/cli/src/bundled-plugins.ts` is now the only CLI module that names the package, and one installation per command serves ordinary execution, `xmd syntax`, structural validation and every `<Plan>` check. A selected Plugin is trusted executable code and is not sandboxed: loading one runs its module. Refusals — no usable default export, no name, a non-callable install, a duplicate Plugin name, a remote specifier — happen before any install and before the root is read.
1 parent 637dfdc commit b66a4af

62 files changed

Lines changed: 3443 additions & 127 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/architecture-rules.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ the system itself; this file governs how new architecture is designed.
1313
4. Do not copy an inconsistent existing pattern merely because it already exists.
1414
5. Correct debt only when the feature changes that surface or cannot remain coherent without the correction.
1515
6. Record adjacent debt as a proposed follow-up Story instead of expanding the feature.
16+
7. Each package exports its consumer-facing contextual APIs and their types from /api; consumers depend on that package and import them from /api.
17+
8. Feature-specific runtime APIs stay with their feature package and are not collected into a central runner context.
1618

1719
The Architect applies these rules without another approval when they settle a
1820
design. A new concept, ambiguous fit, conflict or proposed exception returns to

‎architecture.md‎

Lines changed: 153 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,10 @@ and categorization rather than clarify them, so both stay exactly as written.
139139
| execution environment | the private bundle of services and records one execution supplies while its document expands: what resolves a name, what routes it to a retained implementation, what the execution declared, and the records it keeps about its own identities, forms, vocabulary and source output. The execution builds it from what it captured and admitted, owns it, and passes it by value through canonical expansion — never through a context, because a context resolves by name and a name is not a secret. An expansion driven directly is handed none at all, which is what "nothing is installed here" means; there is no partial one. Its shape is an architecture and product boundary |
140140
| syntax reference | the engine-owned lexical answer to "what may a document write here", carried by value on canonical core's execution environment beside what resolves an import. The execution builds one at its root from the selection inputs it captured before any installation, middleware or document code ran, or from the one set of symbols a trusted host stated for its profile; a trusted canonical evaluation boundary replaces it for the subtree it evaluates. It answers with text and decides nothing: a component the symbols name is not a component anything may run |
141141
| run profile declarations | the component registrations a first-party package makes, held as plain values apart from the middleware, providers, activation and launchers its installer also arranges. The installer registers exactly those values and inspection reads exactly those values, so what a run installs and what the symbols report cannot drift |
142+
| Plugin | trusted code a distribution bundles or an operator selects with `--plugin`, installed once before an execution imports a root document. A plain structural value carrying a name and one optional `install`; what it contributes is the existing `ExecutionInstallation` members, and what it composes through are the three stable contextual APIs below. Selecting one runs its module and its code with this process's own authority: it is trusted, and it is not sandboxed |
143+
| document envelope | the Markdown the `Document` Api composes for one run: the canonical `<Document />` placeholder wrapped by each Plugin's middleware, first Plugin outermost. Canonical core scans it once and splices the root's already parsed, already target-selected segments in at each placeholder, at their authored positions — so an unwrapped run is the run it always was, and an authored `<Document />` is an ordinary element that projects nothing |
144+
| active Plugins | the frozen ordered list of Plugin values installed for one command, published before the first `install()` runs so that every Plugin and every later consumer read the same list. It is a description of what is installed and grants nothing |
145+
| command declarations | every Markdown component one command declares, in one order: what the installed Plugins declared, then whatever the calling surface declares for itself. Built once per command so that an ordinary run, a nested `host="run"` child, inspection and `<Plan>`'s validation cannot describe four different vocabularies |
142146
| origin-only | the inspectability of a component whose contract could only be learned by loading it: a repository TypeScript module, whose schemas live on its exports and whose top level would run. Such an entry carries name, category, origin and source kind, and no contract field at all — an absent contract is stated, never rendered as an empty one |
143147
| definition-owned return state | which value body a `<Return>` selects for: one ephemeral state per execution of one value root or Markdown value component. Structural directives keep the ambient one, a component invocation hides it from the invoked body, a nested value body installs its own, and caller-projected content restores the caller's. It travels down the expansion call stack as a local rather than through a context, and no exported function accepts another body's, so nothing a document can read, replace, or import acts on a live one. The first claim on it is atomic, so a second executed return fails the body rather than replacing its value, and it appends no durable event |
144148

@@ -4416,6 +4420,139 @@ durable is written.
44164420
`undefined`, and a replay reconstructs the same validated prop set through
44174421
ordinary expansion.
44184422

4423+
## The Plugin boundary
4424+
4425+
A **Plugin** is trusted code installed before an execution imports a root
4426+
document. A distribution names the ones it bundles, and an operator appends
4427+
their own with a repeatable `--plugin <specifier>`. Together they are the one
4428+
extension boundary XMD has: there is no package with a reserved name, no
4429+
manifest, no Plugin version, no capability bag and no central runner context a
4430+
Plugin reaches through.
4431+
4432+
**A Plugin is a value, not a registration.** It carries a name and, optionally,
4433+
one `install(request)` operation:
4434+
4435+
```ts
4436+
export default Plugin({
4437+
name: "@example/reviews",
4438+
*install(request) {
4439+
if (request.command !== "run") {
4440+
return undefined;
4441+
}
4442+
yield* useExampleComponents();
4443+
return { components: yield* exampleDeclarations() };
4444+
},
4445+
});
4446+
```
4447+
4448+
The value is plain structural data, and deliberately unbranded. A selected
4449+
module ordinarily resolves its own copy of `@executablemd/core`, and a brand, a
4450+
symbol or an `instanceof` check would split that copy from the canonical
4451+
execution and silently drop everything the Plugin installed. What makes two
4452+
copies agree is the stable, namespaced contextual Api names below.
4453+
4454+
**A selected module's default export is the Plugin.** One unambiguous export
4455+
means a library package can publish its Plugin as its default while keeping
4456+
every named export it already had — which is exactly what
4457+
`@executablemd/code-review-agent` does.
4458+
4459+
**What an install contributes** is one `PluginInstallation`, or `undefined` for
4460+
a command the Plugin is not active in: exact Markdown components, structural
4461+
syntax, the handler that expands it, and journal admissions. Those are the
4462+
existing acts of infrastructure, reached through the boundary the host already
4463+
had — a Plugin composes an `ExecutionInstallation`, it does not get a new one.
4464+
Feature facilities are deliberately absent: a Plugin that needs repositories,
4465+
sessions, GitHub or upgrade services imports that feature package's own `/api`.
4466+
4467+
**Trusted, not sandboxed.** Loading a selected module runs its top level, and
4468+
that happens before anything can look at what it exported. Installing one runs
4469+
its code with the process's own authority. The engine refuses a *malformed*
4470+
Plugin — a module exporting no default, a default carrying no name, an `install`
4471+
that is not callable, two selections claiming one name — and it refuses them
4472+
before any `install()` runs and before a root document is read. It constrains a
4473+
well-formed one not at all, and none of this is a permission boundary.
4474+
4475+
**Selection is explicit.** Nothing scans the repository, `node_modules`, a
4476+
package manifest, the root document or the component search path. A package
4477+
that happens to be installed does nothing until it is named; a path inside the
4478+
current repository is valid when the operator wrote it; a remote URL is refused,
4479+
because this boundary fetches no code. Specifiers resolve from the invocation's
4480+
own captured working directory rather than from the CLI module, so a global
4481+
install, an npm install and a compiled binary agree about what one name means.
4482+
V1 performs no ambient or document-declared discovery — that is a decision about
4483+
what V1 does, not a claim that discovery can never be added.
4484+
4485+
**Order composes and never arbitrates.** The bundled list installs first, then
4486+
the explicit selections in occurrence order, and the first Plugin installed is
4487+
the outermost middleware wrapper. Position decides nothing else: two Plugins
4488+
claiming one Plugin name, one component name, one structural construct or one
4489+
documentation contribution are refused at admission, exactly as two trusted
4490+
hosts already were.
4491+
4492+
**The lifetime is the command's.** The complete command runs inside the scope
4493+
the Plugins installed into, so a failure or a cancellation part-way through the
4494+
list unwinds the earlier Plugins, reads no root and starts no document, under
4495+
ordinary structured-concurrency teardown and its existing failure precedence.
4496+
An isolated nested `<Execution host="run">` inherits none of it and installs the
4497+
same Plugin *values* again in its own scope, with command `run` — which is what
4498+
makes a run child of `xmd test` the run profile while the test root is not.
4499+
4500+
### The three contextual APIs a Plugin composes through
4501+
4502+
Each is a value-returning contextual Api: the terminal answers with what the
4503+
execution would use on its own, and a Plugin wraps that answer.
4504+
4505+
`Document` is the root's content. Its terminal answers with the exact text
4506+
`"<Document />"` — the placeholder canonical core projects the already parsed
4507+
and target-selected root into. A Plugin returns Markdown containing that
4508+
placeholder wherever the original document belongs, and canonical core scans
4509+
that envelope once and splices the root's own parsed segments in at each
4510+
placeholder. The segments are the ones the root was parsed to, at the offsets,
4511+
lines and paths they were authored at, so an element's source position and its
4512+
expansion identity are what they would have been with no Plugin at all; splicing
4513+
rather than nesting is also what keeps the root's own top-level `<Output>` a
4514+
top-level child and its `<Return>` in the value body's flow. With no middleware
4515+
the envelope is exactly the placeholder and the execution runs the definition it
4516+
imported, so there is nothing for a no-Plugin run to observe. A middleware may
4517+
delegate more than once, and nothing caches or counts: each placeholder projects
4518+
the document again.
4519+
4520+
An authored `<Document />` is an ordinary element. Only the envelope canonical
4521+
core scanned is read for placeholders; the root's own segments are spliced in as
4522+
parsed values and are never walked, so a document that writes the name reaches
4523+
ordinary component resolution and finds no component there.
4524+
4525+
`RootMetadata` is the root's ordinary `meta` record and nothing else. Its
4526+
terminal answers with the record the root's frontmatter declared, and what a
4527+
Plugin returns is detached and frozen before the execution reads it. It cannot
4528+
reach `props`, `required`, `returns`, target selection, or the metadata of any
4529+
imported component.
4530+
4531+
`ActivePlugins` is the frozen ordered list of the Plugin values installed for
4532+
this command. It is installed before the first `install()` runs, so every
4533+
Plugin — including the first — and every later consumer read the same list.
4534+
4535+
Execution, `inspectDocument` and non-executing document validation compose a
4536+
root through one shared path, so what a caller is told a document declares is
4537+
what the document will run as, and a wrapper whose own structure a document
4538+
could not write is diagnosed on the same terms the document would have been.
4539+
4540+
**No durable protocol changes.** There is no Plugin event, no Plugin-set
4541+
identity and no generic Plugin record. The root import, the declaration records
4542+
and every existing encoding are byte-identical, and a Plugin whose future
4543+
middleware must reject an incompatible retained history supplies an explicit
4544+
`JournalAdmission` rather than having one inferred from its name.
4545+
4546+
### Where a consumer imports from
4547+
4548+
`@executablemd/core/api` publishes the Plugin contracts, the three contextual
4549+
APIs and their direct operations, and the declaration constructors an
4550+
installation's members are built from. `@executablemd/runtime/api` publishes the
4551+
existing `Config` Api a Plugin reads timeouts and verbosity through. Both
4552+
packages keep every root export they had; `/api` is additive, and it is where a
4553+
consumer depending on the package imports from rather than reaching the engine's
4554+
own surface or the host boundary.
4555+
44194556
## The declared Markdown boundary
44204557

44214558
A trusted host may ship first-party Markdown, name it, and hand it to one
@@ -4584,15 +4721,22 @@ reserved registrations. The mechanisms differ in what they carry and agree in
45844721
what they mean. Moving only the Markdown would have left shadowable exactly the
45854722
six components that run processes, read credentials and reach the network.
45864723

4587-
**Where it is installed.** Everywhere the production `run` profile is assembled,
4588-
from one helper rather than a list spelled at each site: ordinary non-testing
4589-
execution, a nested `<Execution host="run">`, the registry `xmd syntax` and
4590-
structural validation enter, `<Plan>`'s internal admission validator, and
4591-
`xmd plan`'s candidate validation. A Plan is therefore checked against the
4592-
vocabulary the later `xmd run` supplies, rather than a narrower one that would
4593-
refuse a program the run would have accepted. `xmd test` at its root is a
4594-
different profile and gains none of it; the run child it can launch gains all of
4595-
it.
4724+
**Where it is installed.** Through the Plugin boundary, as this distribution's
4725+
one bundled Plugin. `packages/cli/src/bundled-plugins.ts` is the only CLI module
4726+
that names the package, and one installation per command serves every surface
4727+
that describes or validates the vocabulary: ordinary non-testing execution, the
4728+
registry `xmd syntax` and structural validation enter, `<Plan>`'s internal
4729+
admission validator, and `xmd plan`'s candidate validation. A Plan is therefore
4730+
checked against the vocabulary the later `xmd run` supplies, rather than a
4731+
narrower one that would refuse a program the run would have accepted, and the
4732+
three checks inside one Plan command consume one retained assembly rather than
4733+
reinstalling and re-reading every packaged asset.
4734+
4735+
The Plugin claims the forty-one names for the commands that can run a review —
4736+
`run`, `syntax`, `plan`, and a `workflow` action that executes a document — and
4737+
returns nothing for the rest. `xmd test` at its root is a different profile and
4738+
gains none of it; the nested `<Execution host="run">` child it can launch
4739+
installs the same Plugin values again with command `run` and gains all of it.
45964740

45974741
**What it does not change.** Ordinary inclusion and repository discovery are
45984742
untouched. A caller's own component of an unclaimed name resolves as it always
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/**
2+
* The Plugins this distribution ships.
3+
*
4+
* One list, and the only module in the CLI that names a Plugin package. Every
5+
* other surface — the run assembly, `xmd syntax`, `<Plan>`'s validation, the
6+
* nested run host — reads what the installed Plugins declared rather than
7+
* importing a package of its own, which is what keeps "what this build ships"
8+
* a single reviewable decision.
9+
*
10+
* Bundled Plugins install before the ones `--plugin` selects, so an operator's
11+
* Plugin composes around them.
12+
*
13+
* This is a code decision and is deliberately separate from the asset embedding
14+
* `scripts/lib/compile.ts` performs: the import is what makes the Plugin
15+
* executable in a compiled binary, and the whole-package include is what keeps
16+
* its Markdown and documentation assets readable there. Neither is derived from
17+
* the other.
18+
*/
19+
20+
import reviewPlugin from "@executablemd/code-review-agent";
21+
import type { Plugin } from "@executablemd/core/api";
22+
23+
export const BUNDLED_PLUGINS: readonly Plugin[] = Object.freeze([reviewPlugin]);

0 commit comments

Comments
 (0)