Skip to content

Commit c34b85d

Browse files
committed
✨ Expose the repository vocabulary to an ordinary xmd run (#643)
The provider exists; this is what reaches it. The Deno source entrypoint and the compiled binary install it for `xmd run` and for an approved `xmd plan --run`, parameterized by the same credential-helper assembly the workflow host uses and by the two existing host configurations, both read and validated before a document expands rather than in the middle of one. Node and Bun register the same thirteen declarations and install no operational provider, so `xmd syntax` describes one language everywhere and every repository operation on those runtimes reaches a clear provider-absence error before a lock, a credential, a subprocess or a request exists. That is the whole implementation of the portable half: one array, declared once, with three consumers — the workflow attachment, `xmd syntax` and `xmd plan`, and an ordinary document execution. `run-repositories.ts` names the managed root and the unsupported installer and is on the shared command path; `deno-repositories.ts` assembles the live provider and is imported only by the two Deno entrypoints. The split is load bearing rather than tidy: the adapter's module graph reaches `node:sqlite`, which Bun has no built-in for, so a static import from shared code would stop `xmd` loading on Bun entirely instead of refusing one operation. A nested `<Execution host="run">` child installs no provider here. Giving a child a live one is inseparable from placing it in the document's contextual repository — a child that had authority but discovered the process directory would operate on a checkout nobody named — so both land together, later, as one change. At this level `xmd test`, a nested child and a workflow execution all reach provider absence. The public specifications describe the ordinary profile, the compiled smoke proves the provider and its kernel-released lock survive `deno compile`, and CI carries the smoke as its own step.
1 parent 7937c35 commit c34b85d

23 files changed

Lines changed: 1441 additions & 39 deletions

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,13 @@ jobs:
222222
- name: The <Plan> Component the compiled binary carries
223223
run: deno test --allow-all --frozen scripts/tests/plan-component-compiled.test.ts
224224

225+
# The ordinary repository provider is assembled at a runtime-named
226+
# entrypoint and holds managed checkouts with a kernel-released advisory
227+
# lock, so only the binary shows both surviving `deno compile`. The script
228+
# runs two of them at once against a managed root of its own.
229+
- name: Smoke test repository composition with the compiled binary
230+
run: deno run --allow-all --frozen scripts/smoke-run-composition.ts
231+
225232
# `<Fetch>` resolves from core's registry, requests through the contextual
226233
# Fetch adapter, and detaches the response before binding it. All three
227234
# live in the module graph, so only the binary shows they survived

‎architecture.md‎

Lines changed: 21 additions & 15 deletions
Large diffs are not rendered by default.

‎packages/cli/src/bun.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import { runXmd, XMD_VERSION } from "./cli.ts";
1414
import type { UpgradeAssembly } from "./upgrade.ts";
1515
import { unassembledMachineSessions } from "./session-coordinator.ts";
1616
import { unsupportedWorkflowHost } from "./workflow.ts";
17+
import { unsupportedRepositories } from "./run-repositories.ts";
1718
import { useBunService } from "./bun-service.ts";
1819

1920
const ENTRYPOINT = fileURLToPath(import.meta.url);
@@ -59,10 +60,16 @@ await main(function* (args) {
5960
// build either. Advertising the same names is what makes the refusal say so:
6061
// every advertised operation stops before provider work, while ordinary ACP
6162
// work is unaffected.
63+
// The same thirteen repository components, and no provider that operates
64+
// any of them. This runtime has no kernel-released advisory lock to hold a
65+
// managed checkout with, so a Repository, Worktree, Git, Issue or PullRequest
66+
// operation reports an absent provider before a local or remote change could
67+
// happen. `xmd syntax` still describes one language everywhere.
6268
yield* runXmd(
6369
args,
6470
useBunService,
6571
UPGRADE,
72+
unsupportedRepositories,
6673
unsupportedWorkflowHost,
6774
unassembledMachineSessions(),
6875
);

‎packages/cli/src/cli.ts‎

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,8 @@ import type { UpgradeAssembly } from "./upgrade.ts";
131131
import { componentSearchPath, resolveTestTarget } from "./test-target.ts";
132132
import { renderSyntaxJson, renderSyntaxMarkdown, syntaxCatalog } from "./syntax.ts";
133133
import { testingExecutionHost } from "./testing-host.ts";
134+
import { unsupportedRepositories } from "./run-repositories.ts";
135+
import type { RepositoryInstaller } from "./run-repositories.ts";
134136
import { EVAL_ALIAS, EVAL_OPTION, evalGrammarError, readEvalFlags } from "./eval-source.ts";
135137
import type { EvalFlags } from "./eval-source.ts";
136138
import {
@@ -144,7 +146,7 @@ import type { HostWorkflowInstaller, WorkflowHost, WorkflowStart } from "./workf
144146
import { runWorkflowManagement } from "./workflow-management.ts";
145147
import { establishDefinition } from "./workflow-definition.ts";
146148
import type { EstablishedDefinition } from "./workflow-definition.ts";
147-
import { useWorkflowServiceDenial } from "@executablemd/workflow";
149+
import { COMPOSITION_REGISTRATIONS, useWorkflowServiceDenial } from "@executablemd/workflow";
148150
import denoJson from "../deno.json" with { type: "json" };
149151

150152
const SECRET_DETECTION_OPTION = "--secret-detection";
@@ -862,6 +864,13 @@ export function* installDocumentComponents(mode: DocumentMode, verbose: boolean)
862864
// `<Verbose>` is registered at all.
863865
yield* Config.around({ verbose: () => verbose }, { at: "min" });
864866

867+
// The repository-composition vocabulary, as ordinary shadowable defaults.
868+
// Registering it installs no provider, discovers no repository, acquires no
869+
// lock and reaches no network: what a name *does* is decided by whichever
870+
// provider the command installed, and a runtime that installs none still
871+
// resolves every one of these.
872+
yield* registerComponents(COMPOSITION_REGISTRATIONS);
873+
865874
// Compose testing around the single core execution entrypoint: both
866875
// commands register the components (assertions work in regular documents,
867876
// explicit <Testing> boundaries affect the outcome), while `xmd test`
@@ -913,6 +922,7 @@ function* runDocument(
913922
config: DocumentConfig,
914923
mode: DocumentMode,
915924
installService: HostServiceInstaller,
925+
installRepositories: RepositoryInstaller,
916926
): Operation<Result<void>> {
917927
const { root, include, verbose, journal, raw, secretDetection, retainProcessOutput } = config;
918928

@@ -1021,6 +1031,15 @@ function* runDocument(
10211031
// the provider for a service.
10221032
yield* installService();
10231033

1034+
// Repository authority belongs to document execution too, and it is this
1035+
// execution's own: the provider it installs holds an invocation identity, the
1036+
// leases on the checkouts this document selects, and the evidence of what it
1037+
// published. `xmd run` and an approved `xmd plan --run` supply the live one;
1038+
// `xmd test` and every runtime without an operational provider supply the one
1039+
// that installs nothing, and every repository operation then reports an
1040+
// absent provider before touching anything.
1041+
yield* installRepositories();
1042+
10241043
// What a `<Test>` in this document runs a nested execution under. Captured
10251044
// before document code begins, so a child is offered exactly what this
10261045
// command assembled — and never a second description of it.
@@ -1134,9 +1153,10 @@ function* runScopedDocument(
11341153
config: DocumentConfig,
11351154
mode: DocumentMode,
11361155
installService: HostServiceInstaller,
1156+
installRepositories: RepositoryInstaller,
11371157
): Operation<Result<void>> {
11381158
try {
1139-
return yield* scoped(() => runDocument(config, mode, installService));
1159+
return yield* scoped(() => runDocument(config, mode, installService, installRepositories));
11401160
} catch (error) {
11411161
return Err(error instanceof Error ? error : new Error(String(error)));
11421162
}
@@ -1166,6 +1186,7 @@ export function planExecutor(
11661186
stack: AgentStack,
11671187
sessions: MachineSessionAssembly | undefined,
11681188
installService: HostServiceInstaller,
1189+
installRepositories: RepositoryInstaller,
11691190
): (approved: PlanExecution) => Operation<Result<void>> {
11701191
return (approved) =>
11711192
scoped(function* (): Operation<Result<void>> {
@@ -1192,6 +1213,10 @@ export function planExecutor(
11921213
agent: stack,
11931214
},
11941215
installService,
1216+
// An approved plan's second execution is an ordinary run, so it gets
1217+
// the ordinary provider — a fresh one, since the authorship profile's
1218+
// scope is already gone.
1219+
installRepositories,
11951220
);
11961221
});
11971222
}
@@ -1246,6 +1271,8 @@ function* test(
12461271
config: TestConfig,
12471272
args: string[],
12481273
installService: HostServiceInstaller,
1274+
/** What a `<Execution host="run">` child installs. This command installs none. */
1275+
installRepositories: RepositoryInstaller,
12491276
): Operation<void> {
12501277
const patterns = readPatternFlags(args);
12511278
if (patterns.missingValue) {
@@ -1279,6 +1306,10 @@ function* test(
12791306
{ ...config, root: { path } },
12801307
{ testing: true },
12811308
installService,
1309+
// `xmd test` installs no operational repository provider, for its own
1310+
// document or for a nested one: every repository operation under it
1311+
// reaches a clear provider-absence error.
1312+
unsupportedRepositories,
12821313
);
12831314
if (!result.ok) {
12841315
reportFailure(result.error);
@@ -1319,6 +1350,7 @@ function* test(
13191350
},
13201351
{ testing: true },
13211352
installService,
1353+
unsupportedRepositories,
13221354
);
13231355
if (!result.ok) {
13241356
reportFailure(result.error, document.relativePath);
@@ -2105,6 +2137,7 @@ function* dispatch(
21052137
helpRequest: { requested: boolean; args: string[] },
21062138
installService: HostServiceInstaller,
21072139
upgrade: UpgradeAssembly,
2140+
installRepositories: RepositoryInstaller,
21082141
workflowHost: WorkflowHost | undefined,
21092142
sessions: MachineSessionAssembly | undefined,
21102143
): Operation<void> {
@@ -2206,6 +2239,7 @@ function* dispatch(
22062239
agent: runStack,
22072240
},
22082241
installService,
2242+
installRepositories,
22092243
);
22102244
});
22112245
if (!result.ok) {
@@ -2263,7 +2297,7 @@ function* dispatch(
22632297
// A host that answers installs a provider; one that does not installs
22642298
// none, and nothing downstream reads a profile to find out which.
22652299
installElicitation: installWebElicitation,
2266-
execute: planExecutor(config, planStack, sessions, installService),
2300+
execute: planExecutor(config, planStack, sessions, installService, installRepositories),
22672301
},
22682302
);
22692303
if (exitCode !== 0) {
@@ -2364,6 +2398,7 @@ function* dispatch(
23642398
{ ...command.config, retainProcessOutput: keepsProcessOutput(command.config.journal) },
23652399
evalFlags.rest,
23662400
installService,
2401+
installRepositories,
23672402
);
23682403
break;
23692404
}
@@ -2469,6 +2504,9 @@ function* dispatch(
24692504
// service adapter would: installed inside the execution scope,
24702505
// before the root document is imported.
24712506
useWorkflowServiceDenial,
2507+
// A workflow run's repositories are the retained ones its Workspace
2508+
// attachment installs, so this path installs none of its own.
2509+
unsupportedRepositories,
24722510
),
24732511
),
24742512
);
@@ -2486,6 +2524,12 @@ export function* runXmd(
24862524
// command run under any other one refuses with that installation's own remedy
24872525
// rather than reaching for a release, a lock or a file.
24882526
upgrade: UpgradeAssembly,
2527+
// What an ordinary document execution installs for `<Repository>`,
2528+
// `<Worktree>`, the Git operations, `<Issue>` and `<PullRequest>`. Deno and
2529+
// the compiled binary supply the live provider; Node and Bun supply the one
2530+
// that installs nothing, so those runtimes describe the same vocabulary and
2531+
// operate none of it.
2532+
installRepositories: RepositoryInstaller,
24892533
// Defaults to the host that refuses. A caller driving this without naming a
24902534
// workflow host has no run store, and inheriting one by omission is the
24912535
// failure mode the whole boundary exists to prevent — so the default is the
@@ -2556,7 +2600,15 @@ export function* runXmd(
25562600
(selected.name === "run" || selected.name === "plan");
25572601

25582602
if (!executes) {
2559-
return yield* dispatch(evalFlags, helpRequest, installService, upgrade, workflowHost, sessions);
2603+
return yield* dispatch(
2604+
evalFlags,
2605+
helpRequest,
2606+
installService,
2607+
upgrade,
2608+
installRepositories,
2609+
workflowHost,
2610+
sessions,
2611+
);
25602612
}
25612613

25622614
const timeouts = resolveRunTimeouts(evalFlags.rest);
@@ -2567,6 +2619,14 @@ export function* runXmd(
25672619
}
25682620

25692621
yield* underRunDeadline(timeouts, () =>
2570-
dispatch(evalFlags, helpRequest, installService, upgrade, workflowHost, sessions),
2622+
dispatch(
2623+
evalFlags,
2624+
helpRequest,
2625+
installService,
2626+
upgrade,
2627+
installRepositories,
2628+
workflowHost,
2629+
sessions,
2630+
),
25712631
);
25722632
}

‎packages/cli/src/compiled.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import { runXmd, XMD_VERSION } from "./cli.ts";
1313
import { compiledUpgradeAssembly } from "./compiled-upgrade.ts";
1414
import { useMachineSessions } from "./session-coordinator.ts";
1515
import { useDenoWorkflowHost } from "./deno-workflow.ts";
16+
import { denoRunRepositories } from "./deno-repositories.ts";
1617
import {
1718
isCredentialHelperMode,
1819
runCredentialHelper,
@@ -80,10 +81,14 @@ if (isCredentialHelperMode(process.argv.slice(2))) {
8081
// two owners of one conversation.
8182
// Helper mode receives neither this nor the workflow host: it is not the
8283
// public CLI and assembles none of it.
84+
// The ordinary repository provider, on the same terms the Deno entrypoint
85+
// installs it: the binary is Deno, and the helper assembly it hands over is
86+
// the one that names this executable rather than a module path.
8387
yield* runXmd(
8488
args,
8589
useCompiledService,
8690
UPGRADE,
91+
denoRunRepositories(HELPER),
8792
() => useDenoWorkflowHost(HELPER),
8893
useMachineSessions(),
8994
);
Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
/**
2+
* The live repository provider, assembled where it can be.
3+
*
4+
* Kept apart from `run-repositories.ts` because that module is on the shared
5+
* command path and this one names the Deno adapter, whose module graph reaches
6+
* `node:sqlite`. Bun has no such built-in, so a static import of this from
7+
* shared code would stop `xmd` loading there — not refuse a repository
8+
* operation, but fail to start at all. Only `deno.ts` and `compiled.ts` import
9+
* this file, and both of them are Deno.
10+
*
11+
* Managed checkouts live beneath `~/.xmd/repositories` and survive every
12+
* execution: what is in one is somebody's work, and nothing deletes one. There
13+
* is no environment variable naming a different root, because the only caller
14+
* that needs one is a test, and a test is handed the root directly.
15+
*/
16+
17+
import type { Operation } from "effection";
18+
import { cwd } from "@executablemd/runtime";
19+
import { useRunComposition } from "@executablemd/workflow/deno";
20+
import type { HelperAssembly } from "@executablemd/workflow/credential-helper";
21+
import { gitHubIssuesConfiguration } from "./github-issues-config.ts";
22+
import { gitHubPullRequestsConfiguration } from "./github-pull-requests-config.ts";
23+
import { DEFAULT_REPOSITORY_ROOT } from "./run-repositories.ts";
24+
import type { RepositoryInstaller } from "./run-repositories.ts";
25+
26+
/**
27+
* The live provider Deno and the compiled binary install.
28+
*
29+
* The two GitHub configurations are read once, when the installer runs, so an
30+
* operator who wrote something this host cannot use learns it before a document
31+
* expands rather than in the middle of one.
32+
*/
33+
export function denoRunRepositories(
34+
helper: HelperAssembly,
35+
root: string = DEFAULT_REPOSITORY_ROOT,
36+
): RepositoryInstaller {
37+
return function* (): Operation<void> {
38+
const gitHubIssues = yield* gitHubIssuesConfiguration();
39+
const gitHubPullRequests = yield* gitHubPullRequestsConfiguration();
40+
yield* useRunComposition({
41+
root,
42+
// The directory this execution starts in, which is where the ambient
43+
// repository is discovered from. Read through the contextual Api rather
44+
// than from the process, so a nested execution that composed its own
45+
// working directory is discovered from that one.
46+
cwd: yield* cwd(),
47+
helper,
48+
...(gitHubIssues === undefined ? {} : { gitHubIssues }),
49+
...(gitHubPullRequests === undefined ? {} : { gitHubPullRequests }),
50+
});
51+
};
52+
}

‎packages/cli/src/deno.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import { runXmd, XMD_VERSION } from "./cli.ts";
1616
import type { UpgradeAssembly } from "./upgrade.ts";
1717
import { useMachineSessions } from "./session-coordinator.ts";
1818
import { useDenoWorkflowHost } from "./deno-workflow.ts";
19+
import { denoRunRepositories } from "./deno-repositories.ts";
1920
import {
2021
isCredentialHelperMode,
2122
runCredentialHelper,
@@ -96,10 +97,17 @@ if (isCredentialHelperMode(process.argv.slice(2))) {
9697
// two owners of one conversation.
9798
// Helper mode receives neither this nor the workflow host: it is not the
9899
// public CLI and assembles none of it.
100+
// The ordinary repository provider: managed checkouts under
101+
// `~/.xmd/repositories`, the ambient repository this command was run in,
102+
// and the two GitHub configurations this deployment authorizes. It is
103+
// parameterized by the same credential-helper assembly the workflow host
104+
// uses, because the program that is running is what knows how to re-invoke
105+
// itself as one.
99106
yield* runXmd(
100107
args,
101108
useDenoService,
102109
UPGRADE,
110+
denoRunRepositories(HELPER),
103111
() => useDenoWorkflowHost(HELPER),
104112
useMachineSessions(),
105113
);

‎packages/cli/src/node.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import { runXmd, XMD_VERSION } from "./cli.ts";
2020
import type { UpgradeAssembly } from "./upgrade.ts";
2121
import { unassembledMachineSessions } from "./session-coordinator.ts";
2222
import { unsupportedWorkflowHost } from "./workflow.ts";
23+
import { unsupportedRepositories } from "./run-repositories.ts";
2324
import { useNodeService } from "./node-service.ts";
2425

2526
const ENTRYPOINT = fileURLToPath(import.meta.url);
@@ -67,10 +68,16 @@ await main(function* (args) {
6768
// build either. Advertising the same names is what makes the refusal say so:
6869
// every advertised operation stops before provider work, while ordinary ACP
6970
// work is unaffected.
71+
// The same thirteen repository components, and no provider that operates
72+
// any of them. This runtime has no kernel-released advisory lock to hold a
73+
// managed checkout with, so a Repository, Worktree, Git, Issue or PullRequest
74+
// operation reports an absent provider before a local or remote change could
75+
// happen. `xmd syntax` still describes one language everywhere.
7076
yield* runXmd(
7177
args,
7278
useNodeService,
7379
UPGRADE,
80+
unsupportedRepositories,
7481
unsupportedWorkflowHost,
7582
unassembledMachineSessions(),
7683
);

0 commit comments

Comments
 (0)