From 0415a6bded4e62491fd0c9b0d23d864e40b15c64 Mon Sep 17 00:00:00 2001 From: dinndev2 <116718497+dinndev2@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:02:46 +0000 Subject: [PATCH 1/2] docs: describe the distribution that exists, and point --help at reachable docs No compiled binary is built and releases carry no assets, so the README and runtime.md stop promising one. The help's last line named repo-relative docs paths that the installed package does not ship; it now prints the docs URL, and a test fails if the help names a bare docs path or a URL whose path no longer exists in the tree. runtime.md and architecture.md also get the measured runtime floors, the real lockfile name, and what CI actually runs. Closes #403 Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- packages/aitm/docs/architecture.md | 2 +- packages/aitm/docs/runtime.md | 11 +++++------ packages/aitm/src/cli/help.test.ts | 21 +++++++++++++++++++++ packages/aitm/src/cli/help.ts | 2 +- 5 files changed, 29 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index ad749927..3e98b6d1 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ The package is scoped (`@developerz.ai/aitm`); the installed command is still `a Installed with bun or npm, `aitm` runs on Node, so Node ≥ 20 must be on your `PATH` even when bun did the install. Installed with deno, it runs on Deno ≥ 2.0. -Plain ESM + a `bun build --compile` single-file binary. No runtime lock-in. +Plain ESM, published to npm. No runtime lock-in. ## 🚀 Quickstart diff --git a/packages/aitm/docs/architecture.md b/packages/aitm/docs/architecture.md index 26735c6d..98a67801 100644 --- a/packages/aitm/docs/architecture.md +++ b/packages/aitm/docs/architecture.md @@ -1,6 +1,6 @@ # Architecture -`aitm` — TypeScript rewrite of `claude-task-master`. Bun for local dev; ships portable ESM that runs on Bun, Node ≥ 20, and Deno ≥ 1.40. Autonomous loop: plan a goal into **PR-sized task groups**, work each group on its own branch, open a PR, **auto-merge** (default on), repeat until done. No final verification phase. No release phase. +`aitm` — TypeScript rewrite of `claude-task-master`. Bun for local dev; ships portable ESM that runs on Node ≥ 20 and Deno ≥ 2.0. Autonomous loop: plan a goal into **PR-sized task groups**, work each group on its own branch, open a PR, **auto-merge** (default on), repeat until done. No final verification phase. No release phase. Two commands only: `aitm start ""` and `aitm merge-pr`. With automerge on, `start` runs everything end-to-end; `merge-pr` is the manual gate for `--no-automerge` runs. diff --git a/packages/aitm/docs/runtime.md b/packages/aitm/docs/runtime.md index 10746711..0e4b9ecb 100644 --- a/packages/aitm/docs/runtime.md +++ b/packages/aitm/docs/runtime.md @@ -1,6 +1,6 @@ # Runtime -Bun is the local dev runtime. Shipped code runs unchanged on **Bun ≥ 1.1, Node ≥ 20, or Deno ≥ 1.40**. Runtime portability is a hard constraint — treat Bun-only API leaks as bugs. +Bun is the local dev runtime. Shipped code runs on **Node ≥ 20** or **Deno ≥ 2.0**; a recent Bun also runs it (`bun --bun aitm`), Bun 1.1 does not. Installed with bun or npm, the `aitm` command itself runs on Node. Runtime portability is a hard constraint — treat Bun-only API leaks as bugs. ## Why Bun for dev @@ -9,7 +9,6 @@ Bun is the local dev runtime. Shipped code runs unchanged on **Bun ≥ 1.1, Node | Native TypeScript | No build step. `bun run src/cli.ts`. | | Fast cold start | Tight feedback loop. | | Built-in test runner | `bun test` works out of the box. | -| `bun build --compile` | Single-file binary for distribution. | Bun is a convenience, not a dependency. @@ -57,8 +56,8 @@ CI-fix flow, which always rebases first). Self-merge is governed separately by ` | --- | --- | | Package manager (dev) | `bun install` | | Package manager (consumer) | any — `npm`, `pnpm`, `yarn`, `bun` | -| Lockfile | `bun.lockb` committed for dev reproducibility | -| Distribution | Plain ESM published to npm, plus a `bun build --compile` binary attached to GitHub releases | +| Lockfile | `bun.lock` committed; every CI job installs with `bun install --frozen-lockfile` | +| Distribution | Plain ESM published to npm (`@developerz.ai/aitm`). No compiled binary is built, and releases carry no assets. | | Module system | ESM only. `"type": "module"`. | ## TypeScript @@ -75,8 +74,8 @@ CI-fix flow, which always rebases first). Self-merge is governed separately by ` ## Testing -- `bun test` locally for speed. -- CI matrix runs the same suite under `bun test` and `node --test` (or `vitest run` with a Node target). Both must pass. +- `bun run test` locally for speed (it sets `AITM_INSTANT_SLEEP=1`, which the timeout-based tests need). +- CI runs the suite under `node --test` only: the `node` and `integration` jobs are authoritative, and CI deliberately runs no `bun test` (Bun's `node:test` shim mis-handles this suite across files, oven-sh/bun#5090). `bin/check` runs the same steps locally. - Integration tests spin up a throwaway git repo in a tempdir and use a sandboxed `gh` token scoped to a disposable fixture repo. - Every module has a paired `*.test.ts`. SRP + tested is the bar. diff --git a/packages/aitm/src/cli/help.test.ts b/packages/aitm/src/cli/help.test.ts index 615dd10c..da3b7b56 100644 --- a/packages/aitm/src/cli/help.test.ts +++ b/packages/aitm/src/cli/help.test.ts @@ -1,4 +1,5 @@ import assert from 'node:assert/strict'; +import { existsSync } from 'node:fs'; import { readFile } from 'node:fs/promises'; import { test } from 'node:test'; import { PRESET_NAMES } from '../config/provider-presets.ts'; @@ -79,6 +80,26 @@ test('help: every declared flag token appears in the rendered help', () => { } }); +// The help text is read by someone who installed the package, which ships no docs directory, so a +// bare `docs/…` path points at nothing. Every pointer is a repository URL, and the path it names must +// still exist in this tree, so moving the docs fails here instead of leaving the help pointing at a 404. +test('help: points at docs a reader can reach, and that still exist', () => { + assert.doesNotMatch( + HELP_TEXT, + /(? m[0]); + assert.ok(urls.length > 0, 'help names no docs URL'); + const repoRoot = new URL('../../../../', import.meta.url); + for (const url of urls) { + assert.ok(url.startsWith(prefix), `help URL is not on this repository's main tree: ${url}`); + const local = new URL(url.slice(prefix.length), repoRoot); + assert.ok(existsSync(local), `help URL names a path that does not exist in the tree: ${url}`); + } +}); + test('help: has the expected top-level structure', () => { assert.ok(HELP_TEXT.startsWith('aitm — autonomous task orchestrator')); assert.match(HELP_TEXT, /\nUsage:\n/); diff --git a/packages/aitm/src/cli/help.ts b/packages/aitm/src/cli/help.ts index 9fbe5513..138c648e 100644 --- a/packages/aitm/src/cli/help.ts +++ b/packages/aitm/src/cli/help.ts @@ -135,7 +135,7 @@ Exit codes: 1 precondition failure or run blocked 2 cancelled, or invalid/malformed command-line usage -Docs: docs/commands/start.md, docs/commands/merge-pr.md, docs/commands/config.md, docs/commands/profile.md`; +Docs: https://github.com/developerz-ai/ai-task-master/tree/main/packages/aitm/docs/commands`; } export const HELP_TEXT = renderHelp(); From f2fc5fef4ee84397e73b7195937395bdf683550c Mon Sep 17 00:00:00 2001 From: dinndev2 <116718497+dinndev2@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:11:11 +0000 Subject: [PATCH 2/2] docs(claude): the CI table names the install every job runs Since #405 the node and integration jobs install with bun install --frozen-lockfile, not npm install; the table still said npm, which is what the review bot read when it questioned runtime.md's lockfile row. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a3c22d55..692a41c1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,8 +47,8 @@ Instructions for Claude when editing `aitm` source. Not for end users. | ci.yml job | Steps | Why | | --- | --- | --- | | `bun` | install, lint, madge circular, typecheck, typecheck:tests | no `bun test` — oven-sh/bun#5090; `typecheck:tests` also covers `packages/aitm/test/`, so integration-file type drift fails CI | -| `node` | npm install, `build (compat runtime)` (`npm run build -w @developerz.ai/ai-claude-compat`), lint, `typecheck --workspaces`, `test:node --workspaces` | per-workspace npm — never shells out to bun | -| `integration` | npm install, `build (compat runtime)` (`npm run build -w @developerz.ai/ai-claude-compat`), `test:integration -w @developerz.ai/aitm` | 20-min budget; `e2e-smoke` self-skips without secrets | +| `node` | `bun install --frozen-lockfile`, `build (compat runtime)` (`npm run build -w @developerz.ai/ai-claude-compat`), lint, `typecheck --workspaces`, `test:node --workspaces` | per-workspace npm scripts; only the install uses bun, from the tracked lockfile | +| `integration` | `bun install --frozen-lockfile`, `build (compat runtime)` (`npm run build -w @developerz.ai/ai-claude-compat`), `test:integration -w @developerz.ai/aitm` | 20-min budget; `e2e-smoke` self-skips without secrets | `release.yml` publishes via npm OIDC trusted publishing (no NPM_TOKEN), npm pinned 11.5.2 (11.6.x regressed provenance), builds then publishes **ai-claude-compat first**, then aitm.