todo2code

Praktyczny przewodnik CLI

CLI todo2code zamienia polecenia, Git, kod, TODO/CHANGELOG, dokumentację i komunikację ticketów na wspólny Intent Evidence DSL. Graf powstały z tych rekordów służy do diagnostyki, Intent vs Reality i porównań w czasie.

Instalacja i diagnostyka

npm install
npm run build
node dist/src/cli.js doctor
node dist/src/cli.js help

Po npm link pełne node dist/src/cli.js można zastąpić poleceniem t2c.

Sprawdzenie wersjonowanych przykładów

npm run examples:check
# albo: make examples-check

Kontrola wykonuje:

całkowicie offline npm run demo;
pipeline examples/ i analizę uczestników DEMO-101;
kompilację TypeScript strict przykładowego backendu i frontendu;
integrację HTTP: health, publikację, odczyt, klasyfikację i błąd 400;
przykłady TypeScript oraz wszystkich dostępnych lokalnie SDK Python, Go, Rust i PHP;
porównanie fingerprintu grafu pomiędzy językami.

Brak opcjonalnego toolchainu powoduje jawny SKIP tylko dla jego SDK. Node i przykład TypeScript są wymagane. Skrypt uruchamia A2A na wolnym porcie i usuwa proces oraz katalog tymczasowy także po błędzie.

Pełny pipeline offline

node dist/src/cli.js pipeline /ścieżka/do/repo \
  --task TASK.md \
  --todo TODO.md \
  --changelog CHANGELOG.md \
  --docs 'README.md,docs/**/*.md' \
  --nl-mode deterministic \
  --markdown-mode deterministic \
  --no-docs-llm \
  --no-summary-llm \
  --out .intent

Flagi są jawne, więc obecność klucza OpenRouter w prywatnym .env nie zmienia trybu wykonania. Udany run zapisuje:

.intent/
├── latest.json
└── runs/<run-id>/
    ├── nl.intent.jsonl
    ├── git.intent.jsonl
    ├── ast.intent.jsonl
    ├── todo.intent.jsonl
    ├── changelog.intent.jsonl
    ├── document.intent.jsonl
    ├── intent.graph.json
    ├── diagnostics.json
    ├── team-summary.md
    └── manifest.json

manifest.json jest źródłem prawdy o trybach, wersji runtime, ostrzeżeniach i degradacji. Szybki odczyt bez jq:

node --input-type=module <<'NODE'
import { readFile } from 'node:fs/promises';
const latest = JSON.parse(await readFile('.intent/latest.json', 'utf8'));
const manifest = JSON.parse(await readFile(`${latest.runDirectory}/manifest.json`, 'utf8'));
console.log(manifest.status, manifest.runtime, manifest.stages, manifest.warnings);
NODE

Pipeline z OpenRouter

Po ustawieniu OPENROUTER_API_KEY oraz modeli w .env:

node dist/src/cli.js pipeline . \
  --task TASK.md \
  --todo TODO.md \
  --changelog CHANGELOG.md \
  --docs 'README.md,docs/**/*.md,project/**/*.md' \
  --nl-mode prefer-llm \
  --markdown-mode prefer-llm \
  --out .intent

prefer-llm pozwala na jawnie audytowany fallback. Gdy wynik bez modelu jest niedopuszczalny, należy użyć require-llm. Wtedy brak klucza, timeout, błędny model lub niepoprawna odpowiedź kończą proces błędem i tworzą manifest status=failed bez publikowania nieistniejącego grafu jako latest.

Osobne konwertery

node dist/src/cli.js extract nl TASK.md --nl-mode deterministic --out nl.intent.jsonl
node dist/src/cli.js extract git --root . --count 10 --out git.intent.jsonl
node dist/src/cli.js extract ast . --out ast.intent.jsonl
node dist/src/cli.js extract markdown --root . --todo TODO.md --changelog CHANGELOG.md \
  --markdown-mode deterministic --out markdown.intent.jsonl
node dist/src/cli.js extract docs --root . --patterns 'README.md,docs/**/*.md' \
  --out docs.intent.jsonl

Ręczne zbudowanie i sprawdzenie grafu:

node dist/src/cli.js link nl.intent.jsonl git.intent.jsonl ast.intent.jsonl \
  markdown.intent.jsonl --out intent.graph.json
node dist/src/cli.js diagnose intent.graph.json --out diagnostics.json

Intent vs Reality i diff

node dist/src/cli.js reality intent.graph.json \
  --diagnostics diagnostics.json \
  --gaps-only --out reality.json --md reality.md --svg reality.svg

node dist/src/cli.js diff before.graph.json after.graph.json \
  --out diff.json --svg diff.svg

node dist/src/cli.js diff --mode files before.ts after.ts \
  --svg files.diff.svg --html files.diff.html

node dist/src/cli.js diff --mode git . --rev origin/main \
  --svg workspace.diff.svg --html workspace.diff.html

SVG, HTML i Markdown są projekcjami danych JSON, nie alternatywnym źródłem prawdy.

Origin kontra lokalny filesystem

node dist/src/cli.js compare-workspace . \
  --base origin/main \
  --task TASK.md \
  --markdown-mode deterministic \
  --out .intent

Polecenie tworzy osobny graf dla wskazanego refa Git i osobny dla aktualnego filesystemu, łącznie z niecommitowanymi zmianami. Wynikiem jest diff, metryki pokrycia i kierunek trendu.

Komunikacja `project/<ticket>`

node dist/src/cli.js communication . \
  --project-dir project \
  --ticket WM-101 \
  --out .intent/WM-101.analysis.json \
  --md .intent/WM-101.analysis.md \
  --graph .intent/WM-101.graph.json

Analiza zachowuje tożsamość i rolę każdego uczestnika. Raportuje konflikty człowiek–człowiek i człowiek–agent, brak odpowiedzi, działania poza zakresem oraz claimy wykonania bez dowodu Git/AST. Ten etap jest obecnie samodzielnym CLI/MCP/A2A; integracja z manifestem głównego pipeline’u pozostaje w backlogu.

Watch, MCP i A2A

node dist/src/cli.js watch . --interval 60 --scan-interval 2 --out .intent
node dist/src/interfaces/mcp.js
node dist/src/interfaces/a2a.js

A2A domyślnie udostępnia health pod http://localhost:8787/healthz, Agent Card pod /.well-known/agent-card.json i UI historii/diffów pod /ui.

This site is open source. Improve this page.