Skip to content

docs(readme): every command runs as written, and a workflow runs the install lines - #417

Merged
dinndev2 merged 2 commits into
mainfrom
docs/readme-commands-run-as-written
Nov 14, 2026
Merged

dinndev2 merged 2 commits into
mainfrom
docs/readme-commands-run-as-written

Conversation

@dinndev2

Copy link
Copy Markdown
Contributor

What

Every command in both READMEs (the root one and packages/aitm/README.md, which npm shows) now runs as written, and a workflow runs the install lines so they cannot rot again.

Install, Deno. deno install -A npm:@developerz.ai/aitm fails on every Deno version, not only on Deno 2:

Deno install -A (before) install -g -A install -g -A -n aitm (now)
1.40.0 / 1.41.3 no executable name -g unknown —
1.42.0 / 1.46.3 no executable name no executable name installs, then aitm crashes at startup in a dependency
2.0.0 --global required no executable name ✅ 0.0.56
2.9.8 --global required ✅ ✅ 0.0.56

So the line is deno install -g -A -n aitm npm:@developerz.ai/aitm, and the floor is Deno ≥ 2.0. Deno 1.x cannot run the published CLI at all, so the old "Deno ≥ 1.40" was wrong as well.

Install, Bun. bun install -g works, but the installed aitm is #!/usr/bin/env node: on a machine with Bun and no Node it fails with node: No such file or directory. The README now says so, and the requirements row reads "Node ≥ 20 (whether bun or npm installed aitm), or Deno ≥ 2.0". Measured: npm on Node 20 and 22 ✅, bun 1.1.0 and 1.4.4 with Node on PATH ✅.

Contributing. bun test gave 17 failures on a clean checkout when this was audited on 2026-11-11, and the repository says not to use it as the runner (CLAUDE.md, oven-sh/bun#5090). The block is now the repository's own bin/setup + bin/check.

Sandbox walkthrough. Step 1 cloned a placeholder URL that 404s, and step 2's echo "…\n…" wrote a literal \n (bash's echo does not interpret escapes). Step 1 now creates a private throwaway repository with gh repo create … --add-readme --clone, and step 2 writes CLAUDE.md with printf and commits and pushes it. The text no longer promises "CI runs": a new repository has no CI, and aitm merges once it has confirmed there are no checks (src/github/checks-poller.ts).

The check. .github/workflows/readme-install.yml reads each README's Install block, runs the bun, npm or deno line as written (one per job, read from the README, never copied into the workflow), then runs aitm --version. It runs on the Node 20 and Deno 2.0 floors plus current Deno 2.x, on a README change, weekly and by hand.

Verification

  • The workflow's install step, extracted verbatim from the YAML, run locally for both READMEs × {npm on Node 20, bun + Node 20, Deno 2.0.0, Deno 2.9.8}: 8/8 pass, each aitm --version → 0.0.56.
  • Red first: the same step against main's READMEs fails for Deno 2.0.0 and 2.9.8 on both files (exit 1). A README with no deno line fails with a named error.
  • actionlint 1.7.12: clean.
  • The walkthrough's steps 2 and 3, run against a local bare remote: CLAUDE.md is written as intended and the commit pushes. Step 1's gh repo create flags are checked against gh 2.102.1's help; I did not create a repository.
  • bin/setup + bin/check on this branch (Node 22.23.5, Bun 1.4.4): typecheck, test typecheck, lint, import cycles and the compat build pass. Unit tests: compat 447/447, aitm 2371 pass, 0 fail, 1 cancelled. The cancelled one is src/cli/commands.test.ts hitting its 30 s file timeout on this 8-core box, and it does the same on an unmodified clone of main (alone it passes 120/120 in 17–25 s). The integration suite, run separately because bin/check stops at the first failure: 73 pass, 0 fail, 5 skipped (the e2e smoke tests need secrets). That includes doc-links.test.ts over the edited READMEs.

Not in this PR

  • packages/aitm/docs/runtime.md, docs/architecture.md and packages/ai-claude-compat/README.md still say "Deno ≥ 1.40" and "Bun ≥ 1.1" for the runtime. Measured: Deno 1.x and Bun 1.1.0 (bun --bun aitm) cannot run the published CLI. That is a separate runtime-floor decision.
  • The package README reaches npm only on the next publish, which chore(release): the manifests carry the published version, so main can never be published #401 blocks.
  • src/cli/commands.test.ts takes 17–25 s on a quiet box against a 30 s file-level timeout, so it times out under load. That is not touched here.

Closes #402

🤖 Generated with Claude Code

…install lines

The Deno line failed on every Deno version: it now passes -g and names the
executable, and the floor is Deno 2.0 (Deno 1.x cannot run the CLI). A
bun-installed aitm runs on Node, which the README now says. Contributing
points at bin/setup + bin/check instead of `bun test`. The sandbox
walkthrough creates a throwaway repository instead of cloning a placeholder,
and writes CLAUDE.md with printf. readme-install.yml runs each README's
install lines as written and then `aitm --version`.

Closes #402

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@developerz-ai

developerz-ai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

✅ Reviewed — nothing blocking

0 actionable comment(s) · grounded on your code

⚠️ 1 config note(s): test files were not shown to the reviewer — this diff touched no path recognised as a test, so no assertion was available to read the change against

🤖 developerz.ai — automated review, running on your model and your box.

developerz-ai[bot]
developerz-ai Bot previously approved these changes Nov 14, 2026

@developerz-ai developerz-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review summary — 3 file(s), 1 finding(s).

Critical 0 · Major 0 · Minor 1 · Nit 0

Fixes the Deno/Bun/npm install lines and runtime floors in both READMEs, rewrites the sandbox and contributing blocks, and adds a workflow that runs each README install line as written. Low risk.

  • test files were not shown to the reviewer — this diff touched no path recognised as a test, so no assertion was available to read the change against

🤖 developerz.ai review — automated, running on your model and your box. What is this?

Comment thread README.md Resolved
A bun-installed aitm runs on Node, and Bun 1.1 cannot run the CLI, so the
Bun badge advertised a runtime the README no longer claims.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@developerz-ai
developerz-ai Bot dismissed their stale review November 14, 2026 04:30

Dismissed automatically by developerz.ai (bot): its own earlier approval is superseded by a newer automated review of this pull request, on commit 38fe66c. No human dismissed this review.

@developerz-ai developerz-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review summary — 1 file(s), 0 finding(s).

This increment swaps the root README's Bun ≥ 1.1 badge for a Deno ≥ 2.0 badge, so the badges now match the requirements row and fix the earlier finding. It only touches docs and carries no risk.

  • test files were not shown to the reviewer — this diff touched no path recognised as a test, so no assertion was available to read the change against

🤖 developerz.ai review — automated, running on your model and your box. What is this?

@dinndev2
dinndev2 merged commit ec1c02b into main Nov 14, 2026
13 checks passed
@dinndev2
dinndev2 deleted the docs/readme-commands-run-as-written branch November 14, 2026 04:33
dinndev2 added a commit that referenced this pull request Nov 14, 2026
…hable docs (#419)

## What

The documentation now describes the distribution that exists, and `aitm
--help` points at docs a reader can reach.

- **No compiled binary.** There is no compile script and all seven
releases have zero assets. The README's "Plain ESM + a `bun build
--compile` single-file binary" now reads "Plain ESM, published to npm".
`runtime.md` drops the `bun build --compile` row and its Distribution
row says no binary is built.
- **`--help`.** The last line named four repo-relative paths
(`docs/commands/start.md`, …). The installed package ships no docs
directory, and the paths don't resolve from the user's working directory
either. It now prints `Docs:
https://github.com/developerz-ai/ai-task-master/tree/main/packages/aitm/docs/commands`,
which answers 200 and covers all five command docs (the old line left
out `update.md`).
- **A test holds it.** `help: points at docs a reader can reach, and
that still exist` fails if the help names a bare `docs/…` path, names no
URL, or names a URL that isn't on this repo's `main` tree or whose path
no longer exists in the checkout. So moving the docs fails here instead
of leaving the help pointing at a 404.

While in `runtime.md`, I corrected four more statements that were false:
- the runtime floors: measured in #417, Deno 1.x and Bun 1.1 cannot run
the published CLI;
- the lockfile name (`bun.lock`, not `bun.lockb`);
- the claim that CI runs the suite under both `bun test` and `node
--test` (it deliberately runs no `bun test`, per CLAUDE.md and
oven-sh/bun#5090);
- in `architecture.md`, the same runtime floor.

The manifest's `files` list is unchanged on purpose: the package keeps
shipping only `dist`, the README and the licence, and the help points at
the web docs instead (criterion 3).

## Verification

- `help.test.ts` under Node: 6/6. Under Bun: 6 pass, 0 fail.
- **Red first:** with `main`'s `help.ts` the new test fails ("help names
a repo-relative docs path"). With the URL pointed at a path that doesn't
exist, it fails naming that URL.
- Built the CLI and ran it: `aitm --help` ends with the new URL.
- `bun run lint`, `bun run typecheck`, `bun run typecheck:tests`: clean.
0 broken relative links outside `docs/vendor/`.

Closes #403

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(readme): three of the README's commands do not work as written

1 participant