Skip to content

Commit b7549f5

Browse files
committed
Give dependency preparation an owner, and make builds inert
Two dependency layouts, not one: `node_modules/` and Deno's global cache. Both were being written by whatever ran first, so the documented `deno task build` reinstalled, pruned the links pnpm had placed, and left `pnpm exec tsc` failing on two dozen unrelated modules. `deno task deps` now owns both — `deno install --frozen`, the cached module graphs a build and a compile walk, and the `sideEffects` fact the bundle needs — and `deno task setup` runs it, pnpm, that fact again, then the bundle. A build installs nothing, and cannot: automatic node-module management writes `node_modules/.deno` before a process reaches its own code, so the build script and the compile run `--node-modules-dir=none --cached-only --frozen` and the bundler `--node-modules-dir=manual --no-remote --frozen`. A dependency-free preflight produces the setup diagnostic, because `--cached-only` stops Deno on a cold cache before any imported code runs. The fact is recorded on every installed copy. Which copy the bundler reads depends on its resolution mode: `manual` walks up from the client entry and finds pnpm's copy under `packages/web/node_modules`, and without the fact there the bundle is 734 KB carrying `new Function` instead of 606 KB tree-shaken. Staged writes are named per invocation and their cancellation waits for the in-flight write, so two preparations cannot delete one another's file. Part of #279.
1 parent 32ed872 commit b7549f5

25 files changed

Lines changed: 1306 additions & 278 deletions

‎.github/workflows/ci.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ jobs:
4444
# The npm build packages every workspace dependency of the CLI, and
4545
# `@executablemd/web` carries a generated browser bundle that is not
4646
# committed. Without this the CLI's npm artifact cannot be built at all.
47+
# Preparing is its own step: a build installs nothing (AGENTS.md).
48+
- name: Install dependencies
49+
run: deno task deps
50+
4751
- name: Build the browser bundle
4852
run: deno task build:web
4953

@@ -61,6 +65,9 @@ jobs:
6165
with:
6266
deno-version: v2.9.1
6367

68+
- name: Install dependencies
69+
run: deno task deps
70+
6471
# With the generated bundle absent the negated `publish.exclude` glob
6572
# matches nothing and the dry run quietly checks a package the release
6673
# would never upload. Building first makes this validate the real shape.
@@ -79,6 +86,9 @@ jobs:
7986
with:
8087
deno-version: v2.9.1
8188

89+
- name: Install dependencies
90+
run: deno task deps
91+
8292
- name: Build the xmd binary
8393
run: deno task build
8494

@@ -169,6 +179,38 @@ jobs:
169179
--component-dir smoke-test/agent/components \
170180
--raw
171181
182+
# The chain `deno task verify:clean` runs locally, on a checkout that is clean
183+
# by construction. It is the regression for #279's ownership claim: a build
184+
# that installs anything prunes pnpm's links and the resolution probe fails.
185+
# It duplicates work other jobs do — that is the cost of asserting the whole
186+
# chain end to end rather than each link separately.
187+
composability:
188+
runs-on: ubuntu-latest
189+
steps:
190+
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
191+
192+
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
193+
with:
194+
node-version: "22"
195+
196+
- uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
197+
198+
- uses: denoland/setup-deno@e95548e56dfa95d4e1a28d6f422fafe75c4c26fb # v2.0.3
199+
with:
200+
deno-version: v2.9.1
201+
202+
- name: Prepare both dependency layouts
203+
run: deno task setup
204+
205+
- name: Build, which must install nothing
206+
run: deno task build
207+
208+
- name: Both stores still resolve
209+
run: node scripts/probe-resolution.mjs
210+
211+
- name: Typecheck through the layout the build left behind
212+
run: pnpm exec tsc --project tsconfig.node.json --noEmit
213+
172214
site:
173215
runs-on: ubuntu-latest
174216
steps:
@@ -215,6 +257,9 @@ jobs:
215257
with:
216258
deno-version: v2.9.1
217259

260+
- name: Install dependencies
261+
run: deno task deps
262+
218263
- name: Build the browser bundle
219264
run: deno task build:web
220265

‎.github/workflows/publish-one.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@ jobs:
5050
# and dnt packages it from the source tree. Building unconditionally keeps
5151
# this job independent of which package it was asked for: `web` needs it for
5252
# itself, and any dependent needs it because dnt builds siblings too.
53+
- name: Install dependencies
54+
run: deno task deps
55+
5356
- name: Build the browser bundle
5457
run: deno task build:web
5558

‎.github/workflows/publish-packages.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,10 @@ jobs:
137137
with:
138138
deno-version: v2.9.1
139139

140+
# A build installs nothing, so a fresh checkout prepares first (spec §8).
141+
- name: Install dependencies
142+
run: deno task deps
143+
140144
# `@executablemd/web` ships a browser bundle that is generated, not
141145
# committed, and a negated `publish.exclude` glob is what puts it in the
142146
# package. On a fresh checkout the glob matches nothing and `deno publish`

‎.github/workflows/release.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,9 @@ jobs:
7373
# `deno compile` embeds the generated browser bundle by following the
7474
# literal dynamic import, and compiles without complaint when the file is
7575
# absent — producing a binary that cannot serve a form (spec §8).
76+
- name: Install dependencies
77+
run: deno task deps
78+
7679
- name: Build the browser bundle
7780
run: deno task build:web
7881

‎AGENTS.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,37 @@
11
# Executable Markdown Agents
22

3+
## Setup
4+
5+
One command prepares a worktree, and nothing else installs:
6+
7+
```bash
8+
deno task setup
9+
```
10+
11+
There are two dependency layouts, not one: `node_modules/` and Deno's global
12+
cache. `deno task deps` owns both — `deno install --frozen`, the cached module
13+
graphs a build and a compile walk, and the one `sideEffects` fact the browser
14+
bundle needs — and `deno task setup` runs it, then `pnpm install`, then records
15+
that fact again (pnpm restores its own copy of that manifest from its store),
16+
then builds the bundle.
17+
18+
The order is load-bearing: `pnpm install` adds its store beside Deno's without
19+
pruning it, and the union resolves for Deno, for `tsc` and the Node suite, for
20+
Bun, for oxlint, and for the site. Run setup again after changing a dependency.
21+
22+
**Builds install nothing.** `deno task build:web` and `deno task build` run
23+
under node-modules and cache modes that cannot create, relink, or fetch —
24+
automatic management writes `node_modules/.deno` before a process reaches its
25+
own code, so a runtime check would be too late — and they refuse to run at all
26+
on an unprepared worktree, naming `deno task setup`
27+
(`scripts/preflight.ts`). A check or a build that reinstalls prunes the links
28+
another command is resolving through, which is how the Node typecheck came to
29+
fail after a `deno task build` (#279).
30+
31+
`deno task verify:clean` runs that whole claim end to end against a clone of
32+
`HEAD`: setup, build, a resolution probe against both stores, then `tsc`. CI
33+
runs the same chain in its `composability` job.
34+
335
## Verification
436

537
After making any changes to source files (`src/`) or test files (`tests/`),

‎README.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -224,16 +224,23 @@ Each invocation requires a new path. If the path already exists, `xmd` exits wit
224224

225225
## Development
226226

227-
This is a Deno-first project. Run the tool from source and the checks with `deno`:
227+
This is a Deno-first project. Prepare a checkout once, then run the tool from
228+
source and the checks with `deno`:
228229

229230
```bash
231+
deno task setup # install both dependency layouts, build the browser bundle
230232
deno task xmd run packages/core/examples/hello-world.md # run a document from source
231233
deno task build # compile the standalone xmd binary
232234
deno task lint # oxlint + oxfmt
233-
deno check packages/core/mod.ts # typecheck
235+
deno task check # typecheck
234236
deno task test # run the test suite
235237
```
236238

239+
`deno task setup` is the only thing that installs. Builds and checks read what
240+
it prepared and write nothing back, so they compose instead of undoing one
241+
another — `deno task verify:clean` runs that claim end to end against a clean
242+
clone (AGENTS.md).
243+
237244
## Status
238245

239246
This is an early, first public release and a draft spec, optimized for experimentation around executable markdown workflows, Effection-based evaluation, and provider-driven AI documents. Feedback, issues, and contributions are very welcome — please [open an issue](https://github.com/taras/executable.md/issues).

‎deno.json‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,15 @@
3939
},
4040
"tasks": {
4141
"xmd": "deno run --allow-all packages/cli/src/deno.ts",
42-
"build": "deno task build:web && deno compile --node-modules-dir=none --exclude-unused-npm --allow-all --include packages/code-review-agent --output dist/xmd packages/cli/src/compiled.ts",
43-
"build:web": "deno run --allow-all scripts/build-web-client.ts",
42+
"setup": "deno run --allow-all scripts/setup.ts",
43+
"verify:clean": "deno run --allow-all scripts/verify-clean.ts",
44+
"deps": "deno run --allow-all scripts/deps.ts",
45+
"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",
46+
"build:web": "deno run --allow-all --node-modules-dir=none --cached-only --frozen scripts/preflight.ts scripts/build-web-client.ts",
4447
"gen:publish-workflow": "deno run --allow-all packages/cli/src/deno.ts run scripts/gen-publish-workflow.md",
4548
"bump": "deno run -A scripts/bump-version.ts",
46-
"test": "deno test --allow-all",
47-
"check": "deno check",
49+
"test": "deno test --allow-all --frozen",
50+
"check": "deno check --frozen",
4851
"check:jsr": "deno publish --dry-run --allow-dirty",
4952
"review": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.md --component-dir .reviews/components --component-dir .reviews/policies --component-dir packages/core/components -j .reviews/journal.jsonl",
5053
"review:local": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.local.md --component-dir .reviews/components --component-dir .reviews/policies --component-dir packages/core/components -j .reviews/journal.local.jsonl",

‎packages/cli/src/node.ts‎

100644100755
File mode changed.

0 commit comments

Comments
 (0)