Skip to content

Commit ddd2999

Browse files
committed
✨ Ship the plan program as a packaged Markdown document (#260)
The first document-backed command needs its Markdown where the command is: a source checkout, a published npm package, and a compiled binary with no checkout. The document is the deployed program, so it ships as a file rather than as a generated string. src/documents/prompt-plan.md is that program. A package declares what it ships by putting it in that directory; test documents and scenario fixtures live under src/ too, and a build that swept those up would publish fixtures and grow every binary carrying them. The command locates it from its module's own URL, never from the working directory and never through the component search path, so it finds the same policy whatever directory a person stands in and no repository file can answer for it. Each build keeps the directory beside its module: both deno compile sites embed it, and the npm build copies it into the emitted tree, because dnt emits the module graph only and an asset nothing imports would otherwise reach Node and Bun missing while Deno stayed green. A regression holds the two compile sites to the documents that exist, since that list is the one thing no build discovers. The host still runs the TypeScript authorship loop; wiring the plan program into the plan profile follows. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6
1 parent d6ca47d commit ddd2999

9 files changed

Lines changed: 391 additions & 4 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ jobs:
9898
--exclude-unused-npm \
9999
--allow-all \
100100
--include packages/code-review-agent \
101+
--include packages/cli/src/documents/prompt-plan.md \
101102
--target ${{ matrix.target }} \
102103
--output dist/${{ matrix.artifact }} \
103104
packages/cli/src/compiled.ts

‎deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@
5757
"verify:clean": "deno run --allow-all --node-modules-dir=none --cached-only --frozen scripts/verify-clean.ts",
5858
"deps": "deno run --allow-all scripts/deps.ts",
5959
"deps:target": "deno run --allow-all scripts/deps-target.ts",
60-
"build": "deno task build:web && deno compile --node-modules-dir=none --cached-only --frozen --exclude-unused-npm --allow-all --include packages/code-review-agent --output dist/xmd packages/cli/src/compiled.ts",
60+
"build": "deno task build:web && deno compile --node-modules-dir=none --cached-only --frozen --exclude-unused-npm --allow-all --include packages/code-review-agent --include packages/cli/src/documents/prompt-plan.md --output dist/xmd packages/cli/src/compiled.ts",
6161
"build:web": "deno run --allow-all --node-modules-dir=none --cached-only --frozen scripts/preflight.ts scripts/build-web-client.ts",
6262
"gen:publish-workflow": "deno run --allow-all packages/cli/src/deno.ts run scripts/gen-publish-workflow.md",
6363
"bump": "deno run -A scripts/bump-version.ts",
Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
props:
3+
type: object
4+
properties:
5+
request: { type: string }
6+
syntax: { type: string }
7+
session: { type: string }
8+
required: [request, syntax, session]
9+
additionalProperties: false
10+
returns:
11+
type: string
12+
---
13+
14+
# The plan `xmd prompt` follows
15+
16+
This is the policy behind `xmd prompt`, and it is a program rather than a
17+
setting: what the agent is asked, how many times a draft may be repaired, what a
18+
person is shown, and what happens when nobody approves anything are all written
19+
here, in the open, where they can be read and argued with.
20+
21+
The command supplies three things — the request as the person typed it, the
22+
syntax catalog for this working directory, and the name of the session every
23+
turn belongs to. Nothing here runs the document being written. A candidate is
24+
text until a person approves it and the command runs it separately.
25+
26+
<Let as="round" value={0} />
27+
28+
<Session name={props.session}>
29+
30+
<Prompt as="candidate">
31+
Write one complete Executable Markdown root document that accomplishes this:
32+
33+
{props.request}
34+
35+
Reply with the document source and nothing else. No enclosing code fence, no
36+
explanation before or after it, no commentary about what you did.
37+
38+
Write it as a document a person would want to read, not as a script with
39+
comments bolted on. State what it does and why in ordinary prose, and let the
40+
components appear where that prose leads to them. The person asked for the
41+
outcome above; the document should still read as though it is about that
42+
outcome.
43+
44+
Everything you may use is described below. Use nothing that is not here.
45+
46+
{props.syntax}
47+
</Prompt>
48+
49+
<Loop max={10}>
50+
<Let as="round" value={round + 1} />
51+
52+
Each draft gets one validation and up to three chances to fix what validation
53+
found. A revision the person asked for is a new draft, so it gets its own three.
54+
55+
<ValidateCandidate source={candidate} as="assessment" />
56+
57+
<Loop max={3}>
58+
<If condition={assessment.valid}>
59+
<Break />
60+
</If>
61+
62+
<Prompt as="candidate">
63+
That document does not validate. These are the exact findings:
64+
65+
<CodeBlock value={JSON.stringify(assessment.diagnostics, null, 2)} language="json" />
66+
67+
Return one complete replacement root document that resolves every finding above.
68+
Source only, no enclosing fence, no explanation. Keep the narrative that explains
69+
what the document is for.
70+
</Prompt>
71+
72+
<ValidateCandidate source={candidate} as="assessment" />
73+
</Loop>
74+
75+
The person decides. A valid draft can be approved; one that is still invalid
76+
after three repairs is shown with its findings and can only be sent back or
77+
abandoned. On the tenth and last presentation there is nothing left to revise
78+
into, so revision is not offered.
79+
80+
<Elicit
81+
as="review"
82+
schema={{
83+
type: "object",
84+
properties: {
85+
decision: {
86+
type: "string",
87+
enum: assessment.valid
88+
? (round === 10 ? ["approve", "abort"] : ["approve", "revise", "abort"])
89+
: (round === 10 ? ["abort"] : ["revise", "abort"]),
90+
},
91+
feedback: { type: "string" },
92+
},
93+
required: ["decision"],
94+
additionalProperties: false,
95+
if: { properties: { decision: { const: "revise" } }, required: ["decision"] },
96+
then: { required: ["feedback"], properties: { feedback: { minLength: 1 } } },
97+
}}
98+
>
99+
This document was written for: {props.request}
100+
101+
<CodeBlock value={candidate} language="markdown" />
102+
103+
<If condition={!assessment.valid}>
104+
It still does not validate after three attempts to repair it. These are the
105+
remaining findings:
106+
107+
<CodeBlock value={JSON.stringify(assessment.diagnostics, null, 2)} language="json" />
108+
</If>
109+
</Elicit>
110+
111+
<If condition={review.decision === "approve"}>
112+
<Return value={candidate} />
113+
<Break />
114+
</If>
115+
116+
<If condition={review.decision === "abort"}>
117+
<Fail message="xmd prompt: you ended the review, so nothing was saved and nothing ran." />
118+
</If>
119+
120+
<Prompt as="candidate">
121+
The person read that document and asked for this to change:
122+
123+
{review.feedback}
124+
125+
Return one complete replacement root document. Source only, no enclosing fence,
126+
no explanation. Keep the narrative that explains what the document is for.
127+
</Prompt>
128+
</Loop>
129+
130+
</Session>
131+
132+
<Fail message="xmd prompt: ten drafts were reviewed and none was approved, so nothing was saved and nothing ran. Try again with a more specific request." />
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
/**
2+
* The Markdown documents this CLI ships and executes itself.
3+
*
4+
* `xmd prompt` runs a first-party document rather than a TypeScript policy, so
5+
* that document has to be present wherever the command is: a source checkout, a
6+
* published npm package, and a compiled binary with no checkout at all. It is
7+
* located from this module's own URL, never from the working directory and never
8+
* through the component search path — the command must find the same program
9+
* whatever directory a person happens to be standing in, and a repository file
10+
* must not be able to answer for it.
11+
*
12+
* Each build keeps `src/documents/` beside its module: `deno compile --include`
13+
* embeds each file at the same relative path, and the npm build copies the
14+
* directory into the emitted tree. So the one lookup below is correct in all
15+
* four places, and a build that forgets the asset fails loudly on first use
16+
* rather than silently choosing different behavior.
17+
*/
18+
19+
import { readFile } from "node:fs/promises";
20+
import { until } from "effection";
21+
import type { Operation } from "effection";
22+
23+
/** The plan program `xmd prompt` executes. */
24+
export const PROMPT_PLAN = "prompt-plan.md";
25+
26+
/**
27+
* Where a packaged document lives, as a URL beside this module.
28+
*
29+
* One directory rather than "any Markdown under `src/`": packages keep test
30+
* documents and scenario fixtures beside their modules too, and a build that
31+
* swept those up would publish them and grow the binary for no reason. Being in
32+
* here is what declares a document shipped.
33+
*/
34+
export function packagedDocumentUrl(name: string): URL {
35+
return new URL(`./documents/${name}`, import.meta.url);
36+
}
37+
38+
/**
39+
* Read one packaged document.
40+
*
41+
* `node:fs` rather than a host File Api: this is the CLI reading its own
42+
* program, not a document reaching the caller's filesystem, and it must not be
43+
* answerable by whatever the running document installed.
44+
*/
45+
export function* readPackagedDocument(name: string): Operation<string> {
46+
const url = packagedDocumentUrl(name);
47+
try {
48+
return yield* until(readFile(url, "utf8"));
49+
} catch (error) {
50+
throw new Error(
51+
`the packaged document ${name} is missing from this build (looked in ${url.href})`,
52+
{ cause: error },
53+
);
54+
}
55+
}
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/**
2+
* The documents the CLI ships and executes itself.
3+
*
4+
* `xmd prompt` runs a first-party Markdown program, so that program has to be
5+
* present and identical wherever the command is. This suite runs under Deno,
6+
* Node and Bun, which is what makes it evidence: the lookup is package-relative,
7+
* and a resolution that only works under the runtime the author happened to use
8+
* is the failure this catches.
9+
*
10+
* The compiled binary and the published npm package are proven where those
11+
* artifacts exist — `scripts/tests/cli-npm-bin.test.ts` for the package, and the
12+
* `dist/xmd` suites for the binary.
13+
*/
14+
import { describe, it } from "@executablemd/test-support/bdd";
15+
import { expect } from "@executablemd/test-support/expect";
16+
import { readTextFile } from "@effectionx/fs";
17+
import { fileURLToPath } from "node:url";
18+
19+
import {
20+
packagedDocumentUrl,
21+
PROMPT_PLAN,
22+
readPackagedDocument,
23+
} from "../src/packaged-document.ts";
24+
import { useWorkingDirectory } from "./support/prompt-harness.ts";
25+
26+
describe("packaged documents", () => {
27+
it("reads the plan program from beside its module, whatever the cwd is", function* () {
28+
// A temporary contextual cwd with no document in it. A lookup that reached
29+
// for the working directory would find nothing here, and one that reached
30+
// through the component search path would be answerable by a repository
31+
// file — neither may decide which program this command runs.
32+
const source = yield* useWorkingDirectory(function* () {
33+
return yield* readPackagedDocument(PROMPT_PLAN);
34+
});
35+
36+
expect(source).toBe(yield* readTextFile(fileURLToPath(packagedDocumentUrl(PROMPT_PLAN))));
37+
// It is the plan program, not merely some file that exists.
38+
expect(source).toContain("returns:");
39+
expect(source).toContain("<ValidateCandidate");
40+
expect(source).toContain("<Fail");
41+
});
42+
43+
it("says which build is missing a document rather than behaving differently", function* () {
44+
// The failure a forgotten `deno compile --include` or npm asset copy
45+
// produces. It names the path it looked at, because that is the difference
46+
// between the four builds and the only thing worth reporting.
47+
let failure: Error | undefined;
48+
try {
49+
yield* readPackagedDocument("no-such-document.md");
50+
} catch (error) {
51+
failure = error instanceof Error ? error : new Error(String(error));
52+
}
53+
54+
expect(failure?.message).toContain("no-such-document.md is missing from this build");
55+
expect(failure?.message).toContain("looked in");
56+
});
57+
});

‎scripts/build-npm.ts‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,19 +27,37 @@ import { build } from "jsr:@deno/[email protected]";
2727
import {
2828
copyFile,
2929
emptyDir,
30+
ensureDir,
3031
exists,
3132
fromFileUrl,
3233
readTextFile,
3334
rm,
3435
writeTextFile,
3536
} from "@effectionx/fs";
3637
import { listWorkspacePaths } from "./lib/workspace.ts";
37-
import { join } from "node:path";
38+
import { join, sep } from "node:path";
3839
// Recursive directory copy and temp-dir creation are not part of @effectionx/fs.
39-
import { cp, mkdtemp } from "node:fs/promises";
40+
import { cp, mkdtemp, readdir } from "node:fs/promises";
4041
import { tmpdir } from "node:os";
4142
import { z } from "npm:zod@^4";
4243

44+
/**
45+
* The documents a package ships, as package-relative paths.
46+
*
47+
* `src/documents/` and nothing else. Packages keep test documents and scenario
48+
* fixtures under `src/` as well, so publishing every Markdown found there would
49+
* ship a package full of fixtures; being in this one directory is what declares
50+
* a document part of the product.
51+
*/
52+
function* packagedDocuments(pkgDir: URL): Operation<string[]> {
53+
const documents = new URL("src/documents/", pkgDir);
54+
if (!(yield* exists(documents))) {
55+
return [];
56+
}
57+
const names = yield* until(readdir(fromFileUrl(documents), { recursive: true }));
58+
return names.map((name) => `src/documents/${name.split(sep).join("/")}`);
59+
}
60+
4361
const ExportsSchema = z.union([z.string(), z.record(z.string(), z.string())]);
4462

4563
const DenoJsonSchema = z.object({
@@ -312,6 +330,17 @@ function* buildPackage(pkgArg: string, version: string, ctx: BuildContext): Oper
312330
yield* copyFile(license, new URL("LICENSE", outDir));
313331
}
314332

333+
// A package that executes its own Markdown ships that Markdown beside its
334+
// emitted module. dnt emits the module graph and nothing else, so an asset no
335+
// TypeScript imports would be absent from the published package while the
336+
// source checkout kept working — the command would find nothing at runtime,
337+
// on Node and Bun only.
338+
for (const asset of yield* packagedDocuments(pkgDir)) {
339+
const target = new URL(`esm/${asset}`, outDir);
340+
yield* ensureDir(fromFileUrl(new URL(".", target)));
341+
yield* copyFile(new URL(asset, pkgDir), target);
342+
}
343+
315344
ctx.built.add(denoJson.name);
316345
const provenance =
317346
ctx.localSiblings && workspaceDeps.length > 0 ? " (local siblings — not publishable)" : "";

‎scripts/tests/cli-npm-bin.test.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,5 +101,14 @@ describe("npm CLI package", { sanitizeOps: false, sanitizeResources: false }, ()
101101
// the whole of what a built npm bin has to get right for one.
102102
expect(run.stdout).toContain("You chose to approve the review.");
103103
expect(run.stdout).not.toContain("ERROR");
104+
105+
// The Markdown this package executes itself ships beside the module that
106+
// reads it. dnt emits the module graph only, so an asset nothing imports is
107+
// absent from the package unless the build copies it — and the command
108+
// would then find no program to run, on Node and Bun while Deno stayed
109+
// green.
110+
expect(yield* readTextFile(path.join(OUT_DIR, "esm/src/documents/prompt-plan.md"))).toBe(
111+
yield* readTextFile(path.join(ROOT, PKG_DIR, "src/documents/prompt-plan.md")),
112+
);
104113
});
105114
});
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
/**
2+
* Every packaged Markdown document reaches every build that ships it.
3+
*
4+
* The npm build discovers these documents, so it needs no list. `deno compile`
5+
* names files one at a time, and it is named twice — in `deno task build` and in
6+
* the release matrix. A document added beside its module and forgotten in either
7+
* place produces a binary that runs until the moment it looks for its own
8+
* program, which is the failure this refuses to let reach a release.
9+
*/
10+
import { describe, it } from "@executablemd/test-support/bdd";
11+
import { expect } from "@executablemd/test-support/expect";
12+
import { readTextFile } from "@effectionx/fs";
13+
import type { Operation } from "effection";
14+
import { readdir } from "node:fs/promises";
15+
import { until } from "effection";
16+
import path from "node:path";
17+
import { fileURLToPath } from "node:url";
18+
19+
const ROOT = fileURLToPath(new URL("../../", import.meta.url));
20+
21+
/** Every document a package ships, repository-relative. */
22+
function* packagedDocuments(): Operation<string[]> {
23+
const found: string[] = [];
24+
for (const member of yield* until(readdir(path.join(ROOT, "packages")))) {
25+
const documents = path.join(ROOT, "packages", member, "src/documents");
26+
let entries: string[];
27+
try {
28+
entries = yield* until(readdir(documents, { recursive: true }));
29+
} catch {
30+
continue;
31+
}
32+
for (const entry of entries) {
33+
found.push(`packages/${member}/src/documents/${entry.split(path.sep).join("/")}`);
34+
}
35+
}
36+
return found.sort();
37+
}
38+
39+
describe("packaged documents reach every build", () => {
40+
it("is embedded by both compile sites", function* () {
41+
const documents = yield* packagedDocuments();
42+
// The suite is only meaningful while at least one exists; an empty sweep
43+
// would pass while proving nothing.
44+
expect(documents.length).toBeGreaterThan(0);
45+
46+
const denoJson = yield* readTextFile(path.join(ROOT, "deno.json"));
47+
const release = yield* readTextFile(path.join(ROOT, ".github/workflows/release.yml"));
48+
const [buildTask = ""] = denoJson.split("\n").filter((line) => line.includes('"build":'));
49+
50+
for (const document of documents) {
51+
expect(buildTask).toContain(`--include ${document}`);
52+
expect(release).toContain(`--include ${document}`);
53+
}
54+
});
55+
});

0 commit comments

Comments
 (0)