diff --git a/.github/workflows/readme-install.yml b/.github/workflows/readme-install.yml new file mode 100644 index 0000000..9bc352f --- /dev/null +++ b/.github/workflows/readme-install.yml @@ -0,0 +1,88 @@ +name: readme install + +# Runs each README's Install block AS WRITTEN, one line per job, then runs the command it installed. +# The install lines are read out of the README, never copied into this file, so a README edit is +# what gets tested. Runs on a README change, weekly (the registry and the runtimes move under a +# README that did not), and by hand. + +on: + pull_request: + paths: + - README.md + - packages/aitm/README.md + - .github/workflows/readme-install.yml + push: + branches: [main] + paths: + - README.md + - packages/aitm/README.md + - .github/workflows/readme-install.yml + schedule: + - cron: '23 6 * * 1' + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + install: + name: ${{ matrix.readme }} · ${{ matrix.runtime.label }} + runs-on: ubuntu-22.04 + timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + readme: [README.md, packages/aitm/README.md] + # The floors the READMEs state (Node 20, Deno 2.0), plus current Deno 2.x: Deno's install + # flags are what changed under the README last time. + runtime: + - { label: npm on Node 20, tool: npm, node: '20' } + - { label: bun on Node 20, tool: bun, node: '20' } + - { label: deno 2.0.0, tool: deno, deno: '2.0.0' } + - { label: deno 2.x, tool: deno, deno: '2.x' } + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + + # A bun-installed aitm runs on Node (its bin is `#!/usr/bin/env node`), so the bun job gets + # the Node floor too: the README tells the reader Node must be on PATH. + - if: matrix.runtime.tool != 'deno' + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7 + with: + node-version: ${{ matrix.runtime.node }} + + - if: matrix.runtime.tool == 'bun' + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2 + with: + bun-version: latest + + - if: matrix.runtime.tool == 'deno' + uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5 + with: + deno-version: ${{ matrix.runtime.deno }} + + - name: global bin directories on PATH + run: | + echo "$HOME/.bun/bin" >> "$GITHUB_PATH" + echo "$HOME/.deno/bin" >> "$GITHUB_PATH" + + - name: run the README's ${{ matrix.runtime.tool }} install line + env: + README: ${{ matrix.readme }} + TOOL: ${{ matrix.runtime.tool }} + run: | + # The Install block is the first fenced block under the "Install" heading. + block=$(awk '/^## .*Install/ { h = 1; next } h && /^```/ { if (b) exit; b = 1; next } b' "$README") + line=$(printf '%s\n' "$block" | grep -E "^${TOOL} +install " || true) + if [ "$(printf '%s' "$line" | grep -c .)" -ne 1 ]; then + echo "::error file=$README::expected exactly one '$TOOL install' line in the Install block, found: ${line:-none}" + exit 1 + fi + echo "+ $line" + eval "$line" + + - name: the installed command runs + run: aitm --version diff --git a/README.md b/README.md index 56d60b2..ad74992 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,8 @@ Give `aitm` a sentence, walk away, come back to a stack of merged pull requests. > **Inspired by** [`developerz-ai/claude-task-master`](https://github.com/developerz-ai/claude-task-master): same idea (a task-master that drives the work to merge), built here on the Vercel AI SDK + OpenRouter, provider-agnostic, with MCP client support and a much smaller surface area. [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./packages/aitm/tsconfig.json) -[![Bun](https://img.shields.io/badge/Bun-≥1.1-fbf0df?logo=bun&logoColor=black)](https://bun.sh) [![Node](https://img.shields.io/badge/Node-≥20-339933?logo=node.js&logoColor=white)](https://nodejs.org) +[![Deno](https://img.shields.io/badge/Deno-≥2.0-000000?logo=deno&logoColor=white)](https://deno.com) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) --- @@ -32,12 +32,14 @@ No babysitting. No prompt-stuffing. No bespoke agent framework. ## ⚡ Install ```bash -bun install -g @developerz.ai/aitm # recommended for local dev -npm install -g @developerz.ai/aitm # works the same -deno install -A npm:@developerz.ai/aitm +bun install -g @developerz.ai/aitm # recommended for local dev +npm install -g @developerz.ai/aitm # works the same +deno install -g -A -n aitm npm:@developerz.ai/aitm # Deno 2 ``` The package is scoped (`@developerz.ai/aitm`); the installed command is still `aitm`. +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. @@ -110,7 +112,7 @@ same lifecycle lines are also appended to `.ai-task-master/progress.md`. | Requirement | Note | | --- | --- | -| 🟢 JS runtime | Bun ≥ 1.1, Node ≥ 20, or Deno ≥ 1.40. Bun preferred locally. | +| 🟢 JS runtime | Node ≥ 20 (whether bun or npm installed `aitm`), or Deno ≥ 2.0. Bun preferred for local dev. | | 🟣 `gh` CLI | authenticated against the target repo's remote | | 📝 Agent config | `CLAUDE.md` or `AGENTS.md` at the target repo root | | 🔑 Credentials | `OPENROUTER_API_KEY` env. That's it. | @@ -230,18 +232,21 @@ Full walkthrough in [`docs/providers.md`](packages/aitm/docs/providers.md); prof ## 🧪 Try it on a sandbox repo ```bash -# 1. Clone a throwaway repo -git clone https://github.com/you/scratch && cd scratch +# 1. Create a throwaway repo (private, with a first commit) and clone it +gh repo create aitm-scratch --private --add-readme --clone && cd aitm-scratch -# 2. Drop a tiny CLAUDE.md so subagents know the style -echo "# CLAUDE.md\n- TypeScript strict.\n- No comments unless necessary." > CLAUDE.md +# 2. Commit a tiny CLAUDE.md so subagents know the style +printf '# CLAUDE.md\n\n- TypeScript strict.\n- No comments unless necessary.\n' > CLAUDE.md +git add CLAUDE.md && git commit -m "docs: add CLAUDE.md" && git push # 3. Set your key and go export OPENROUTER_API_KEY=sk-or-... aitm start "add a /healthz endpoint with a test" --max-prs 1 ``` -A single PR opens, CI runs, it merges. Total wall-clock: a few minutes. +A single PR opens and merges. Total wall-clock: a few minutes. A new repository has no CI, so `aitm` +merges once it has confirmed there are no checks to wait for; add a workflow and it waits for green +first. Delete the repository afterwards with `gh repo delete aitm-scratch`. ## 📚 Docs @@ -268,12 +273,12 @@ A single PR opens, CI runs, it merges. Total wall-clock: a few minutes. PRs welcome. House style is in [`CLAUDE.md`](CLAUDE.md): SOLID, one responsibility per module, every module ships with a paired `*.test.ts`, no `any`, no default exports, conventional commits, no emoji in source. ```bash -bun install -bun test # unit + integration -bun run typecheck -bun run lint +bin/setup # bun install, then build the compat package a clean checkout lacks +bin/check # the gate, the same steps CI runs: typecheck, lint, import cycles, unit + integration tests ``` +`bin/check` needs both Bun and Node on your `PATH` (CI uses Node 22). + ## 📄 License MIT. diff --git a/packages/aitm/README.md b/packages/aitm/README.md index 0f81ffb..303102f 100644 --- a/packages/aitm/README.md +++ b/packages/aitm/README.md @@ -18,10 +18,12 @@ baked in. ```bash npm install -g @developerz.ai/aitm bun install -g @developerz.ai/aitm -deno install -A npm:@developerz.ai/aitm +deno install -g -A -n aitm npm:@developerz.ai/aitm # Deno 2 ``` -The package is scoped; the installed command is just **`aitm`**. +The package is scoped; the installed command is just **`aitm`**. Installed with npm or bun, it runs +on Node ≥ 20 (so Node must be on your `PATH` even when bun did the install); installed with deno, +on Deno ≥ 2.0. ## 🚀 Quickstart @@ -97,7 +99,7 @@ aitm config list - `OPENROUTER_API_KEY` in the environment. - The [`gh`](https://cli.github.com) CLI, authenticated (PRs, CI status, reviews). -- Node ≥ 20, Bun, or Deno ≥ 1.40 — ESM, no runtime lock-in. +- Node ≥ 20 (whether npm or bun installed `aitm`), or Deno ≥ 2.0 — ESM, no runtime lock-in. ## License