💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all \u003cpre\u003e\u003ccode\u003e blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks"); } } catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); } })(); (function(){ try { var __m = "github.com"; var __re = new RegExp('^' + "github\\.com" + '
Skip to content

💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix"); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length \u003e 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms"); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links"); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + '
Skip to content

💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default"); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers"); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode"); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })();
Skip to content

💥 feat(core): return schema-validated values from components and roots#200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taras merged 6 commits into from
Jul 28, 2026
Merged

💥 feat(core): return schema-validated values from components and roots #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ff278b0
💥 feat(core): return schema-validated values from components and roots
taras Jul 28, 2026
e305539
💄 style(site): format the returning-values section with deno fmt
taras Jul 28, 2026
6871ec0
♻️ refactor(tests): launch the CLI through one shared helper
taras Jul 28, 2026
548856f
♻️ refactor(tests): synchronize CLI runs like any exec
taras Jul 28, 2026
da8e159
📝 docs: drop comments that restate the code they sit on
taras Jul 28, 2026
8eacf1b
📝 docs: drop the last comments that narrate their own call
taras Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -77,6 +77,13 @@ jobs:
--component-dir packages/core/components \
--raw

# The guide documents this command and its output; running it keeps the
# value-root contract executable rather than described.
- name: Smoke test a value root's JSON result
run: |
test "$(./dist/xmd run smoke-test/value-root.md)" = \
'{"passed":true,"summary":"no findings"}'

# Covers the compiled binary relaunching itself as `xmd test-agent`,
# which the source-mode worker command never exercises.
- name: Smoke test the compiled binary as a test agent
Expand Down
2 changes: 2 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 33 additions & 1 deletion packages/cli/src/cli.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -364,6 +364,10 @@ function* run(
yield* installAgentStack(mode.agent);
}

// `xmd test` reports on stdout, so the JSON result contract is `xmd run`'s
// alone. Reading the mode costs no document effects.
const valueRoot = !mode.testing && (yield* readsValue(rootPath));

const execution = yield* execute({
path: rootPath,
stream,
Expand All@@ -372,16 +376,24 @@ function* run(
});

// Consume the output stream with forEach.
// A value root reserves stdout for its result: its rendered body is
// observability, shown on stderr under --verbose and dropped otherwise.
// Interactive TTY: write each chunk as it arrives.
// Piped: collect and write the full output at the end.
const fullOutput = yield* forEach(function* (chunk: string) {
if (valueRoot) {
if (verbose) {
process.stderr.write(chunk);
}
return;
}
if (process.stdout.isTTY) {
process.stdout.write(chunk);
}
}, execution.output);

// When piped (not TTY), write the full output at the end.
if (!process.stdout.isTTY) {
if (!valueRoot && !process.stdout.isTTY) {
process.stdout.write(fullOutput);
}

Expand All@@ -401,6 +413,26 @@ function* run(
console.error(result.error.message);
}
yield* exit(1);
return;
}

// Written straight to stdout, so the result never passes through markdown
// normalization or terminal formatting.
if (valueRoot) {
process.stdout.write(`${JSON.stringify(result.value)}\n`);
}
}

/**
* A document that cannot be inspected — missing, malformed, or unreadable —
* reports text, so execution produces the diagnostic rather than inspection.
*/
function* readsValue(rootPath: string): Operation<boolean> {
try {
const description = yield* inspectDocument({ path: rootPath });
return description.returnMode === "value";
} catch {
return false;
}
}

Expand Down
116 changes: 31 additions & 85 deletions packages/cli/tests/agent-cli.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,77 +10,13 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { timebox } from "@effectionx/timebox";
import { ensure, scoped, spawn, each } from "effection";
import { ensure, scoped } from "effection";
import type { Operation } from "effection";
import { exec } from "@effectionx/process";
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
import { randomUUID } from "node:crypto";
import * as path from "node:path";
import * as os from "node:os";
import process from "node:process";
import { cliCommand } from "@executablemd/test-support/launch";

const TIMEOUT = 60_000;

interface CliResult {
code: number | undefined;
stdout: string;
stderr: string;
}

/**
* The environment a fixture run gets: an isolated HOME so ACPX never
* reads or writes the developer's configuration or session store, plus
* the cache variables Deno needs to run without re-downloading.
*/
function fixtureEnv(home: string, overrides: Record<string, string>): Record<string, string> {
const env: Record<string, string> = { HOME: home };
for (const name of ["PATH", "DENO_DIR", "DENO_INSTALL_ROOT", "XDG_CACHE_HOME", "TMPDIR"]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return { ...env, ...overrides };
}

function* runCli(
args: string[],
fixture: { dir: string; home: string },
overrides: Record<string, string> = {},
): Operation<CliResult> {
const result = yield* timebox<CliResult>(TIMEOUT, function* () {
const cli = cliCommand(args);
const proc = yield* exec(cli.command, {
arguments: cli.arguments,
cwd: fixture.dir,
env: fixtureEnv(fixture.home, overrides),
});
const stdoutChunks: string[] = [];
const stderrChunks: string[] = [];
const readStdout = yield* spawn(function* () {
for (const chunk of yield* each(proc.stdout)) {
stdoutChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const readStderr = yield* spawn(function* () {
for (const chunk of yield* each(proc.stderr)) {
stderrChunks.push(new TextDecoder().decode(chunk));
yield* each.next();
}
});
const status = yield* proc.join();
yield* readStdout;
yield* readStderr;
return { code: status.code, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
});
if (result.timeout) {
throw new Error("CLI subprocess timed out");
}
return result.value;
}
import { runCli } from "@executablemd/test-support/launch";

interface Fixture {
dir: string;
Expand DownExpand Up@@ -110,6 +46,10 @@ function* useFixture<T>(
});
}

function env(fixture: Fixture): { cwd: string; env: Record<string, string> } {
return { cwd: fixture.dir, env: { HOME: fixture.home } };
}

const AGENT_DOC = [
"BEFORE_MARKER",
"",
Expand All@@ -135,7 +75,10 @@ const PLAIN_DOC = "PLAIN_MARKER\n\nNo agent here.\n";
describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CA1: an unknown --agent-provider fails before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--agent-provider", "bogus", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--agent-provider", "bogus", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('Unknown agent provider "bogus"');
Expand All@@ -145,7 +88,10 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA2: mutually exclusive permission flags fail before the document executes", function* () {
const result = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--approve-all", "--deny-all", "--raw"], fixture);
return yield* runCli(
["run", "doc.md", "--approve-all", "--deny-all", "--raw"],
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("mutually exclusive");
Expand All@@ -154,7 +100,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

it("CA3: a document that never uses an agent runs with default flags", function* () {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
Expand All@@ -167,7 +113,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const rejected = ["1e3", "0x10", ".5", "+1", "Infinity", "NaN", "12seconds", "0", "-1"];
for (const value of rejected) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("--timeout");
Expand All@@ -176,43 +122,43 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour

for (const value of ["30", "0.5"]) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout", value, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(0);
expect(result.stdout).toContain("PLAIN_MARKER");
}

const equalsForm = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], fixture);
return yield* runCli(["run", "doc.md", "--timeout=1e3", "--raw"], env(fixture)).join();
});
expect(equalsForm.code).toBe(1);
expect(equalsForm.stderr).toContain("--timeout");
});

it("CA5: the default agent resolves environment, then flag, with the flag winning", function* () {
const fromEnv = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(["run", "doc.md", "--raw"], fixture, {
DEFAULT_AGENT_NAME: "xmd-env-only-agent",
});
return yield* runCli(["run", "doc.md", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-only-agent" },
}).join();
});
expect(fromEnv.code).toBe(1);
expect(fromEnv.stderr).toContain('agent "xmd-env-only-agent" is unavailable');

const fromFlag = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-only-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(fromFlag.code).toBe(1);
expect(fromFlag.stderr).toContain('agent "xmd-flag-only-agent" is unavailable');

const both = yield* useFixture({ "doc.md": AGENT_DOC }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"],
fixture,
{ DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
);
return yield* runCli(["run", "doc.md", "--default-agent", "xmd-flag-wins-agent", "--raw"], {
cwd: fixture.dir,
env: { HOME: fixture.home, DEFAULT_AGENT_NAME: "xmd-env-loses-agent" },
}).join();
});
expect(both.code).toBe(1);
expect(both.stderr).toContain('agent "xmd-flag-wins-agent" is unavailable');
Expand All@@ -225,8 +171,8 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
const result = yield* useFixture({ "doc.md": doc }, function* (fixture) {
return yield* runCli(
["run", "doc.md", "--default-agent", "xmd-nonexistent-agent", "--raw"],
fixture,
);
env(fixture),
).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain('agent "xmd-nonexistent-agent" is unavailable');
Expand All@@ -247,7 +193,7 @@ describe("Tier CA — xmd run agent stack", { sanitizeOps: false, sanitizeResour
];
for (const option of options) {
const result = yield* useFixture({ "doc.md": PLAIN_DOC }, function* (fixture) {
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], fixture);
return yield* runCli(["test", "doc.md", ...option.args, "--raw"], env(fixture)).join();
});
expect(result.code).toBe(1);
expect(result.stderr).toContain("unrecognized option for xmd test");
Expand Down
27 changes: 1 addition & 26 deletions packages/cli/tests/cli-help.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,32 +9,7 @@
*/
import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { exec, type Exec } from "@effectionx/process";
import { cliCommand } from "@executablemd/test-support/launch";
import process from "node:process";

function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const name of [
"PATH",
"HOME",
"DENO_DIR",
"DENO_INSTALL_ROOT",
"XDG_CACHE_HOME",
"TMPDIR",
]) {
const value = process.env[name];
if (typeof value === "string") {
env[name] = value;
}
}
return env;
}

function runCli(args: string[]): Exec {
const cli = cliCommand(args);
return exec(cli.command, { arguments: cli.arguments, env: cliEnv() });
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false }, () => {
it("CH1: program help lists the commands", function* () {
Expand Down
37 changes: 8 additions & 29 deletions packages/cli/tests/command.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,26 +10,11 @@ import { describe, it } from "@executablemd/test-support/bdd";
import { expect } from "@executablemd/test-support/expect";
import { ensure } from "effection";
import { ensureDir, rm } from "@effectionx/fs";
import { exec } from "@effectionx/process";
import type { ProcessResult } from "@effectionx/process";
import { timebox } from "@effectionx/timebox";
import { randomUUID } from "node:crypto";
import * as os from "node:os";
import * as path from "node:path";
import process from "node:process";
import { API, command } from "@executablemd/runtime";
import { cliCommand } from "@executablemd/test-support/launch";

/** Inherit PATH so the Node launcher can resolve tsx. */
function cliEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === "string") {
env[key] = value;
}
}
return env;
}
import { runCli } from "@executablemd/test-support/launch";

describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources: false }, () => {
it("XC1: with no adapter installed, command reports that rather than guessing", function* () {
Expand DownExpand Up@@ -84,18 +69,12 @@ describe("Tier XC — the xmd command", { sanitizeOps: false, sanitizeResources:
yield* ensureDir(elsewhere);
yield* ensure(() => rm(elsewhere, { recursive: true, force: true }));

const result = yield* timebox<ProcessResult>(180_000, function* () {
const cli = cliCommand(["test", path.resolve("smoke-test/test-agent/README.md")]);
return yield* exec(cli.command, {
arguments: cli.arguments,
cwd: elsewhere,
env: cliEnv(),
}).join();
});
if (result.timeout) {
throw new Error("the CLI timed out");
}
expect(result.value.code).toBe(0);
expect(result.value.stdout).toContain("The review of **packages/core** passed.");
const result = yield* runCli(["test", path.resolve("smoke-test/test-agent/README.md")], {
cwd: elsewhere,
inheritEnv: true,
timeout: 180_000,
}).join();
expect(result.code).toBe(0);
expect(result.stdout).toContain("The review of **packages/core** passed.");
});
});
Loading
Loading