The tasks for working on this repo
Written by charter docs from what charter docs-tasks -not tasks.toml -title "The tasks for working on this repo" prints (docs/_generated.toml): don’t edit, change the code that command reads, then mise run docs:setup.
Run one with mise run <task>; its arguments and flags go after --. mise tasks lists them, and mise run <task> --help shows one.
From dev.toml
| Task | What it does |
|---|---|
dev:types | Type-check tests/ and scripts/ (tsconfig.json) |
dev:api-types | Write scripts/core/emdash-api.d.ts, the types of every request EmDash’s HTTP API has, from scripts/core/emdash-openapi.json (with openapi-typescript). The requests the tasks make themselves are checked against it by dev:types: a path, a method or a body that EmDash does not have is a type error. The JSON file is a copy of EmDash’s own list, GET /_emdash/api/openapi.json of a built site this machine is signed in to, and its first key says which EmDash it is from. To move to a newer EmDash: save that site’s list over the file, keep the first key, run this, then dev:types — which says which of the tasks’ requests no longer fit |
dev:test | The test of every task, at one of three levels, the same here and on GitHub (dev:ci). smoke: the basics, in half a minute — a project is made, its tasks run, the site starts and answers. fast, the default: the everyday steps. all: every step, the long ones too. smoke and fast use one test site that is kept, and kept running, from one run to the next; all starts from nothing. It is the unit tests and the site, signin and plugin groups, each a task of its own that mise runs side by side — so it takes as long as the slowest of them. (The live group deploys: dev:test:live, by name) |
dev:test:unit | The unit tests, in a second: the graph of states and each state with a made-up outside, the edits to a site’s config, and that every task has a test step |
dev:test:site | The site group: making, running, checking and deleting a site, on a copy of site/ |
dev:test:signin | The signin group: the CLI and a browser window as an administrator of the built site |
dev:test:plugin | The plugin group: a plugin of your own, and plugins from EmDash’s registry |
dev:test:live | REMOTE: the live group — the tasks that act on a deployed site, on the Worker kept for testing (TEST_LIVE_URL and TEST_LIVE_NAME in mise.local.toml). It deploys, and takes about five minutes |
dev:ci | REMOTE: have GitHub run dev:test at a level on Linux, macOS and Windows (the stages workflow), on the branch you are on, as it is pushed. By itself GitHub runs smoke on a push to main and all on a release tag |
check | What must pass before a release, and what release runs before it tags: the test (dev:test) and repo:ci (the docs and the repo are as charter keeps them) |
dev:src | EmDash’s source into .src/emdash (git ignores it), to read when a task meets something EmDash does that its docs do not say. Run again: the newest |
dev:commit | What the commit check runs, in seconds: the types (dev:types), the unit tests (every task has a test step among them), and the docs are fresh and pass the lint (docs:check) |
dev:hooks | Turn on the commit check in this clone: every commit runs dev:commit |
From joeblew999/charter//tasks/repo
| Task | What it does |
|---|---|
docs:setup | Write the docs site’s config and docs/writing.md (the same for every repo; GitHub Pages renders the folder), and the pages docs/_generated.toml lists |
docs:lint | Check docs/ for what a program can check: front matter, links, the index, tasks and paths that don’t exist |
docs:check | Fail if the docs site’s config or a generated page differs from what docs:setup writes, or docs/ fails the lint |
docs:review | Have Claude (the claude command) bring docs/ up to date and into line with docs/writing.md |
docs:pages | REMOTE, once per repo: turn on GitHub Pages for docs/ on main (GitHub renders the markdown itself) |
release | REMOTE: cut a release from this machine: mise run release -- vX.Y.Z [-dry-run]. The repo is clean and is the default branch on GitHub, then the repo’s own tasks where it has them: setup, check, dist. Then the tag, the push, the GitHub Release with notes from the commits. It does not wait for GitHub’s workflows: check is the same check, run here; a workflow that FAILED on this commit stops it |
repo | REMOTE: keep the repo in shape from charter.toml at its root: docs site, issue forms, labels, description, homepage, topics, GitHub Pages; the workflows only in a repo with charter projects |
repo:check | REMOTE, read-only: fail if the repo differs from charter.toml and the tool’s templates (charter repo -check) |
issues | REMOTE, read-only: the open issues, newest first: what is reported and what is planned (a plan is an issue) |
repo:ci | Everything the repo-check workflow runs, here: docs:check (the docs site and generated pages are fresh, docs/ passes the lint), repo:check (the repo is as charter.toml says), upstream:status. The workflow runs this one task and nothing else, so a pass here is a pass on GitHub. REMOTE, read-only |
issue | Print the body to fill in for an issue of one kind, with that form’s headings, and the gh command that files it with the form’s labels: mise run issue -- bug (or feature, upstream, plan) |
upstream:status | REMOTE, read-only: the upstream issues the code works around (every Upstream: tag): CLOSED means that workaround can go |
Each task
dev:types
- Usage:
dev:types
Type-check tests/ and scripts/ (tsconfig.json)
dev:api-types
- Usage:
dev:api-types
Write scripts/core/emdash-api.d.ts, the types of every request EmDash’s HTTP API has, from scripts/core/emdash-openapi.json (with openapi-typescript). The requests the tasks make themselves are checked against it by dev:types: a path, a method or a body that EmDash does not have is a type error. The JSON file is a copy of EmDash’s own list, GET /_emdash/api/openapi.json of a built site this machine is signed in to, and its first key says which EmDash it is from. To move to a newer EmDash: save that site’s list over the file, keep the first key, run this, then dev:types — which says which of the tasks’ requests no longer fit
dev:test
The test of every task, at one of three levels, the same here and on GitHub (dev:ci). smoke: the basics, in half a minute — a project is made, its tasks run, the site starts and answers. fast, the default: the everyday steps. all: every step, the long ones too. smoke and fast use one test site that is kept, and kept running, from one run to the next; all starts from nothing. It is the unit tests and the site, signin and plugin groups, each a task of its own that mise runs side by side — so it takes as long as the slowest of them. (The live group deploys: dev:test:live, by name)
- Usage:
dev:test [--level <level>] [--node]
Flags
-
--level <level>— smoke, fast or allChoices:
smoke,fast,allDefault:
fast -
--node— On a Node site made from EmDash’s template
dev:test:unit
- Usage:
dev:test:unit
The unit tests, in a second: the graph of states and each state with a made-up outside, the edits to a site’s config, and that every task has a test step
dev:test:site
The site group: making, running, checking and deleting a site, on a copy of site/
- Usage:
dev:test:site [FLAGS]
Flags
-
--level <level>— smoke, fast or allChoices:
smoke,fast,allDefault:
fast --node— On a Node site made from EmDash’s template--only <words>— Only the steps whose name has these words
dev:test:signin
The signin group: the CLI and a browser window as an administrator of the built site
- Usage:
dev:test:signin [FLAGS]
Flags
-
--level <level>— smoke, fast or allChoices:
smoke,fast,allDefault:
fast --node— On a Node site made from EmDash’s template--only <words>— Only the steps whose name has these words
dev:test:plugin
The plugin group: a plugin of your own, and plugins from EmDash’s registry
- Usage:
dev:test:plugin [FLAGS]
Flags
-
--level <level>— smoke, fast or allChoices:
smoke,fast,allDefault:
fast --node— On a Node site made from EmDash’s template--only <words>— Only the steps whose name has these words
dev:test:live
REMOTE: the live group — the tasks that act on a deployed site, on the Worker kept for testing (TEST_LIVE_URL and TEST_LIVE_NAME in mise.local.toml). It deploys, and takes about five minutes
- Usage:
dev:test:live [FLAGS]
Flags
-
--level <level>— smoke, fast or allChoices:
smoke,fast,allDefault:
fast --node— On a Node site made from EmDash’s template--only <words>— Only the steps whose name has these words
dev:ci
REMOTE: have GitHub run dev:test at a level on Linux, macOS and Windows (the stages workflow), on the branch you are on, as it is pushed. By itself GitHub runs smoke on a push to main and all on a release tag
- Usage:
dev:ci [--level <level>]
Flags
-
--level <level>— smoke, fast or allChoices:
smoke,fast,allDefault:
smoke
check
- Usage:
check
What must pass before a release, and what release runs before it tags: the test (dev:test) and repo:ci (the docs and the repo are as charter keeps them)
dev:src
- Usage:
dev:src
EmDash’s source into .src/emdash (git ignores it), to read when a task meets something EmDash does that its docs do not say. Run again: the newest
dev:commit
- Usage:
dev:commit
What the commit check runs, in seconds: the types (dev:types), the unit tests (every task has a test step among them), and the docs are fresh and pass the lint (docs:check)
dev:hooks
- Usage:
dev:hooks
Turn on the commit check in this clone: every commit runs dev:commit
docs:setup
- Usage:
docs:setup
Write the docs site’s config and docs/writing.md (the same for every repo; GitHub Pages renders the folder), and the pages docs/_generated.toml lists
docs:lint
- Usage:
docs:lint
Check docs/ for what a program can check: front matter, links, the index, tasks and paths that don’t exist
docs:check
- Usage:
docs:check
Fail if the docs site’s config or a generated page differs from what docs:setup writes, or docs/ fails the lint
docs:review
- Usage:
docs:review
Have Claude (the claude command) bring docs/ up to date and into line with docs/writing.md
docs:pages
- Usage:
docs:pages
REMOTE, once per repo: turn on GitHub Pages for docs/ on main (GitHub renders the markdown itself)
release
- Usage:
release
REMOTE: cut a release from this machine: mise run release – vX.Y.Z [-dry-run]. The repo is clean and is the default branch on GitHub, then the repo’s own tasks where it has them: setup, check, dist. Then the tag, the push, the GitHub Release with notes from the commits. It does not wait for GitHub’s workflows: check is the same check, run here; a workflow that FAILED on this commit stops it
repo
- Usage:
repo
REMOTE: keep the repo in shape from charter.toml at its root: docs site, issue forms, labels, description, homepage, topics, GitHub Pages; the workflows only in a repo with charter projects
repo:check
- Usage:
repo:check
REMOTE, read-only: fail if the repo differs from charter.toml and the tool’s templates (charter repo -check)
issues
- Usage:
issues
REMOTE, read-only: the open issues, newest first: what is reported and what is planned (a plan is an issue)
repo:ci
- Usage:
repo:ci
Everything the repo-check workflow runs, here: docs:check (the docs site and generated pages are fresh, docs/ passes the lint), repo:check (the repo is as charter.toml says), upstream:status. The workflow runs this one task and nothing else, so a pass here is a pass on GitHub. REMOTE, read-only
issue
- Usage:
issue
Print the body to fill in for an issue of one kind, with that form’s headings, and the gh command that files it with the form’s labels: mise run issue – bug (or feature, upstream, plan)
upstream:status
- Usage:
upstream:status
REMOTE, read-only: the upstream issues the code works around (every Upstream: tag): CLOSED means that workaround can go