How to help
Report a bug
Open an issue with the task exactly as you ran it and everything it printed: the first lines say where it was acting. Check Upstream issues first. From a terminal: mise run issue -- bug prints the form to fill in.
Set up
git clone https://github.com/joeblew999/emdash-run && cd emdash-run
mise trust && mise install
mise run dev:hooks # every commit then runs the commit check
mise run dev:test --level smoke # the basics, half a minute
The tasks of this repo
The tasks for working on this repo, written from the tasks themselves. mise run dev:test --help shows the levels and flags of the test.
The test
mise run dev:test --level smoke # the unit tests, and a dev site that starts and answers
mise run dev:test # the level fast: the everyday steps of every group
mise run dev:test --level all # every step, the long ones too
mise run dev:test:plugin --level all --only plugin:demo # one group, and only the steps named
mise run dev:ci --level smoke # the same task on GitHub: Linux, macOS, Windows
What each task and level is: its description. What the descriptions do not say:
- The levels smoke and fast work on one test site that is kept, and kept running, between runs: a copy of
site/in~/.cache/emdash-run/bench, made again whensite/changes; with--node, a site made fromnode:starterinbench-node. A step then costs what its task costs. The groups take it in turn. - The level all starts from nothing: each group in a temporary folder of its own, removed at the end. Only there are the steps that stop, empty and delete a site, and the long ones,
site:check,site:seed,site:demo,plugin:demoandplugin:newamong them. - A whole group run at the level all leaves Node’s report of it in
tests/<group>/last-run.txt, which What the tests showed is written from: runmise run docs:setupafter it and commit both. A smoke or fast run, a run with--onlyand a run on GitHub leave none, somise run checkchanges no file. - The live group deploys to a Worker kept for it, and is not part of
dev:test:mise run dev:test:live. - On GitHub a push to
mainthat touches the tasks, the scripts, the tests orsite/runs the level smoke, and a release tag the level all. Not run there at any level: the twosignin:opensteps, which need a screen, the live group, and the Node site (--node). What has passed there: Getting started.
The site in this repo
site/ is a real site, made from EmDash’s cloudflare:blog template and committed: the place to try a task or a plugin in seconds, without making a site first. What is the machine’s stays out of git: its packages, its .env, its local database.
Added to the template, so that plugin:demo has something to show a visitor: French as a second language (/fr/), the two packages that draw the forms plugins’ blocks, LinguaDash’s language switcher, and src/middleware.ts (Upstream issues).
mise run site:ports # once: ports of its own for this clone
mise run site:start # the dev site; open /_emdash/api/setup/dev-bypass?redirect=/_emdash/admin
mise run site:demo # something in every core feature, on the built site
mise run plugin:demo # seven registry plugins, each doing its real thing
mise run site:status # where it is now
French there is the home page and the posts: /fr/ and /fr/posts/<slug>. Menus, widgets and the words of the layout stay English, and the one post in French is the one plugin:demo makes.
The test works on a copy of site/, so the site you are looking at and its local database are not touched.
How it is built
Each file’s first lines say what it is; this is only where to look.
| Path | What is there |
|---|---|
tasks.toml | The front door: every task another repo gets, as its name, its description (which is its documentation), its flags, and one line that runs scripts/core/cli.mjs. No logic |
scripts/core/cli.mjs, graph.mjs | The one entry, and the graph: a task is a state to reach, standing on other states. plan and reach |
scripts/core/site.mjs, signin.mjs, tasks.mjs | The states: a site on this machine, signing in, every other task |
scripts/core/seed.mjs, demo.mjs, plugin-demo.mjs | site:seed section by section, site:demo’s list of features, plugin:demo’s recipe for each plugin |
scripts/core/api.mjs, emdash-client.mjs | How site:seed and site:demo speak to a site: EmDash’s own client (emdash/client, loaded from the site’s packages) where it has a call, and a typed request where it has none |
scripts/core/emdash-api.d.ts, emdash-requests.d.ts, emdash-seed.d.ts | The types: EmDash’s requests, written by mise run dev:api-types; where that list and the site differ, by hand; a seed file, by hand |
scripts/core/world.mjs | Everything outside the program: a command, a request, a file. A state reaches outside through it only, so a unit test gives it a made-up one |
scripts/*.mjs | The work where EmDash has no command of its own, as functions the states call: signin-*.mjs, plugin-*.mjs, live-*.mjs, emdash.mjs |
seeds/demo.json | The seed file site:demo applies |
tests/core/ | The unit tests of scripts/core/, on a made-up outside and a made-up EmDash |
tests/<group>/steps.mjs, tests/both/ | The steps: each runs a task on a real site. A group to a set of tasks (site, signin, plugin, live); both holds the steps run on this machine and on a deployed site |
tests/lib/, tests/run.mjs | What a step is written with, and what the dev:test tasks run |
dev.toml | This repo’s own tasks |
.github/workflows/stages.yml | Runs dev:test at a level on Linux, macOS and Windows |
Limits of that design, as the code is now:
- The scripts beside
scripts/core/are type-checked, and all but two are tested only by running their task on a real site. The two with unit tests: the edits to a site’s config (plugin-astro-config.mjs) and the reading of a release’s permissions (inplugin-api.mjs). The rest,signin-access.mjs,signin-browser.mjs,live-preview.mjs,plugin-install.mjs,plugin-works.mjs,plugin-sandbox.mjsandemdash.mjsamong them, reach outside by themselves, not throughworld.mjs. - Only
site:seedandsite:demosend typed requests.plugin:demo, the registry plugin tasks andsite:statussend requests of their own, written by hand and not checked against EmDash’s list. - No script starts
mise. One state asks for another through the graph, in the same process;plugin-works.mjsstarts the entry again, as a process of its own, for the tasks it checks with. - The site’s own tools (astro, emdash, wrangler) are run by Node directly, not through
pnpm exec(Upstream issues). Three places still usepnpm execfor them: a rebuild inlive-preview.mjs, wrangler insignin-access.mjs, andemdash logininsignin-browser.mjs.plugin:checkandplugin:publishrun a plugin’s ownemdash-pluginwith it, in the plugin’s folder. - The copy of EmDash’s list of requests is refreshed by hand after an EmDash upgrade:
dev:api-typessays how.emdash:updatedoes not do it.
Reading EmDash
- Its skills, in any scaffolded site:
site/.agents/skills/(emdash-cli,building-emdash-site,creating-plugins). - Its docs: the
emdash-docsMCP server (.mcp.json). - Its source, to read the code:
mise run dev:srcclones it into.src/emdash(.src/is ignored by git).
Releases
mise run dev:ci --level all # the level all, on three OSes
mise run dev:test:live # the deployed-site tasks, if a live: task changed
mise run release -- vX.Y.Z -dry-run # says what it would do
mise run release -- vX.Y.Z # check, tag, push, the GitHub Release with notes from the commits
dev:ci --level all has not been run yet, only the level smoke: Getting started says what has passed, and where. release is charter’s: it runs mise run check here and does not wait for GitHub. The stages workflow then runs the level all on macOS, Linux and Windows on the tag. What changed in a release is its notes on the releases page.