craftkit 0.3.0__tar.gz → 0.3.2__tar.gz

craftkit-0.3.2/PKG-INFO

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: craftkit
+Version: 0.3.2
+Summary: Study → build → check → refine any software, from the terminal, with your coding agent.
+License-Expression: MIT OR Apache-2.0
+Keywords: cli,coding-agent,claude-code,codex,gemini,rebuild,skill
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE-MIT
+License-File: LICENSE-APACHE
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == "browser"
+Dynamic: license-file
+
+# craftkit
+
+**Rebuild any software with the coding agent you already use, and prove the result is right.**
+
+[![npm](https://img.shields.io/npm/v/craftkit-cli?label=npm)](https://www.npmjs.com/package/craftkit-cli)
+[![PyPI](https://img.shields.io/pypi/v/craftkit?label=PyPI)](https://pypi.org/project/craftkit/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT%20or%20Apache--2.0-green)
+
+[Français](README.fr.md)
+
+`craft` is a free command-line tool. Point it at a website, a command-line program or an app (or
+just describe what you want), and it has your coding agent (Claude Code, Codex or Gemini CLI) build
+your own version. It then **checks the result against the original with real measurements** and
+sends the differences back to the agent until every check passes.
+
+```sh
+npm install -g craftkit-cli        # or: pipx install craftkit
+craft new https://example.com "recreate this landing page in React"
+cd recreate-this-landing-page-in-react && craft run
+```
+
+---
+
+## Why craft?
+
+Coding agents write code fast, but on their own they don't know **when they're done**. Ask one to
+"make a site like this one" and you get something that *looks* finished. You then spend the
+afternoon comparing screenshots and pasting differences back by hand.
+
+`craft` does that loop for you:
+
+| Without craft | With craft |
+|---------------|------------|
+| You describe the original in words | `craft` captures it: screenshots at 3 screen widths, visible fonts and colours, what a program prints |
+| The agent decides when it's "done" | The work is done when **measured checks pass**: it builds, it looks the same, it prints the same, its tests pass |
+| You compare by eye and paste feedback | Each difference goes back to the agent automatically, up to a set budget |
+| A long prompt, then you hope | A project folder with evidence, the brief, every check and every turn on disk, ready to resume anytime |
+| Locked to one tool | Works with Claude Code, Codex, Gemini CLI, or any assistant (copy-paste mode) |
+
+### What people use it for
+
+- **Recreate a website** you like as a starting point: same layout on desktop, tablet and phone,
+  built from scratch in your stack.
+- **Rebuild a command-line tool** in another language, for example a Python script rewritten in
+  Rust that prints the same output for the same inputs.
+- **Make a game or desktop app** from a description or from your own screenshots, with a
+  self-test that proves the core loop works.
+- **Build a new tool from a plain request** ("a pomodoro timer CLI in Go"), verified by tests the
+  agent must write and pass.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[1 · Study<br/>capture the original] --> B[2 · Build<br/>your agent writes app/]
+    B --> C[3 · Check<br/>measure the differences]
+    C -- not there yet --> D[4 · Refine<br/>send the differences back]
+    D --> B
+    C -- every check passes --> E[✓ Ready]
+```
+
+1. **Study.** `craft` gathers evidence into `capture/`. For a website, it takes full-page
+   screenshots at 1440, 768 and 390 px and records visible facts (title, headings, fonts,
+   colours). For a program, it records what it prints for a few inputs (only if you allow running
+   it). Pictures you add to `reference/` are included.
+2. **Build.** Your coding agent receives a clear brief and works only inside `app/`. You watch
+   it live: every file read, edit and command appears as it happens.
+3. **Check.** The same checks run every round: does it build? Does it look like the original at
+   each width? Does it print the same thing? Do its tests pass?
+4. **Refine.** Anything that fails goes back to the agent with the exact differences. This repeats
+   until every check passes, with a budget of 6 refinements per request. It also stops if the
+   agent changes nothing twice in a row.
+
+What you see in your terminal while it works:
+
+```text
+ craft · pomodoro                                  cli · Rust · clean room
+ ▍study  ./pomodoro ─────────────────────────────────────────────────
+ ✓ runs    4 runs recorded
+ ▍build  building · turn 1 ──────────────────────────────────────────
+   0:03 ◇ read   BRIEF.md
+   0:05 ☰ plan   2/5 · Writing the timer
+   0:41 ✚ write  app/src/main.rs
+   1:02 ❯ run    cargo build
+   1:20 ✗ failed error[E0425]: cannot find value `paused`
+   1:31 ✎ edit   app/src/main.rs
+   └ 2m14s · 14 actions: 6 edit, 4 run, 3 read, 1 plan · 1 failed
+ ✓ build   I built the timer with pause and resume.
+ ▍check  round 1 ────────────────────────────────────────────────────
+ ✗ runs    6 of 8 claims hold; output 71% alike.
+   │ With --help, it prints what the original prints: 52% of the words match
+ ▍refine  refining 1/6 · turn 2 ─────────────────────────────────────
+   ⠼ refining 1/6 · claude · 0m48s · 3 · Edit app/src/main.rs
+```
+
+Each stage has its own colour in the terminal.
+
+---
+
+## Installation
+
+### What you need
+
+| | Required? | Why |
+|---|---|---|
+| **Python 3.9+** | yes | `craft` is written in Python, with no dependencies |
+| **A coding agent** | yes | it writes the code: [Claude Code, Codex or Gemini CLI](#install-a-coding-agent) |
+| **Node.js** | only for `npm install` | npm comes with Node.js ([nodejs.org](https://nodejs.org)) |
+| **A browser** | only for websites | for screenshots: installed Chrome/Edge works; Playwright adds visible-style measurements |
+
+Python is already installed on macOS and most Linux systems; check with `python3 --version`. On
+Windows, install it from [python.org](https://www.python.org/downloads/) or with
+`winget install Python.Python.3.12`.
+
+### Install craft (pick one)
+
+```sh
+npm install -g craftkit-cli     # with Node.js
+pipx install craftkit           # with pipx
+uv tool install craftkit        # with uv
+```
+
+All three install the same program and the same commands: `craft` (plus the aliases `craftkit`,
+`craft-new`, `craft-run`).
+
+To try it without installing anything: `npx craftkit-cli` or `uvx craftkit`.
+
+Check that it works:
+
+```sh
+craft --version      # craft 0.3.2
+craft agents         # shows which coding agents craft can find
+```
+
+### Install a coding agent
+
+`craft` doesn't write code itself; your coding agent does. Install at least one, then **run it
+once to sign in**:
+
+| Agent | Install | Then |
+|-------|---------|------|
+| **Claude Code** | `npm install -g @anthropic-ai/claude-code`<br/>or `curl -fsSL https://claude.ai/install.sh \| bash` | run `claude` and sign in |
+| **Codex** | `npm install -g @openai/codex` | run `codex` and sign in |
+| **Gemini CLI** | `npm install -g @google/gemini-cli`<br/>or `brew install gemini-cli` | run `gemini` and sign in (free tier with a Google account) |
+
+If none is installed, `craft` says so right away (on the home screen, at `craft new` and before
+`craft run` starts) and prints these exact commands.
+
+**No agent at all?** `craft brief` prints the task. Paste it into any coding assistant (Cursor,
+Copilot, …) opened in the project folder, then run `craft check`.
+
+### Optional: better website screenshots
+
+```sh
+pip install playwright && playwright install chromium
+```
+
+Without it, `craft` uses an installed Chrome or Edge in headless mode, and otherwise falls back to
+Playwright through `npx`.
+
+### Update and uninstall
+
+| Installed with | Update | Uninstall |
+|----------------|--------|-----------|
+| npm | `npm update -g craftkit-cli` | `npm uninstall -g craftkit-cli` |
+| pipx | `pipx upgrade craftkit` | `pipx uninstall craftkit` |
+| uv | `uv tool upgrade craftkit` | `uv tool uninstall craftkit` |
+
+Uninstalling leaves your projects alone.
+
+---
+
+## Usage
+
+### The easy way: the home screen
+
+Type **`craft`**. You get your past projects and a **+ New project** entry, which asks a few
+questions and creates the project in `~/craft-projects`.
+
+| Key | Action |
+|-----|--------|
+| ↑ ↓ (or j k) | move |
+| Enter | open a project: continue, ask for a change, open the result, re-check, show the folder |
+| n | new project |
+| x | remove from the list (the folder is kept) |
+| q / Esc | back, or quit |
+
+### From the command line
+
+```sh
+craft new https://example.com "recreate this site in React"   # creates ./recreate-this-site-in-react/
+cd recreate-this-site-in-react
+craft run                              # the whole loop: study → build → check → refine
+craft run "make the header sticky"     # ask for a change (starts a new refinement budget)
+craft open                             # open the result (serves a site, or runs the app)
+```
+
+More examples:
+
+```sh
+craft new "a pomodoro timer CLI in Go"                # no original: build from the request
+craft new ./my-tool "the same tool in Rust" --allow-run   # record what it prints, then match it
+craft new "a snake game in Python" --kind game
+
+craft new "a todo app in Electron"                    # from your own mockups:
+cp ~/Pictures/mockups/*.png a-todo-app-in-electron/reference/   # put them in reference/
+cd a-todo-app-in-electron && craft run
+```
+
+### All commands
+
+| Command | What it does |
+|---------|--------------|
+| `craft` | home screen: past projects, new project |
+| `craft new [TARGET] [REQUEST…]` | create a project. TARGET is a web address, a file, a folder, a command, or nothing |
+| `craft run [MESSAGE…]` | the whole loop; with a message, a change to the build |
+| `craft study` · `build` · `check` | one step at a time |
+| `craft status` | where the project is |
+| `craft answer` | answer the agent's questions |
+| `craft open` | open the result |
+| `craft agents` | which coding agents are installed, and how to get one |
+| `craft brief` | print the agent's task, to paste into any assistant |
+| `craft skill [--install DIR]` | print or install the SKILL.md (see below) |
+
+Options for `craft new`:
+
+| Option | Meaning |
+|--------|---------|
+| `--kind website\|cli\|app\|game\|tool` | what you're making (guessed from your words otherwise) |
+| `--stack rust\|python\|react\|html\|go\|…` | the language or framework (guessed from your words otherwise) |
+| `--allow-run` | allow running the original program to record what it prints |
+| `--deep` | allow looking inside the original (see [Clean room and Deep](#clean-room-and-deep)) |
+| `--dir DIR` | where to create the project |
+
+Options for `craft run` and `craft build`: `--agent claude|codex|gemini`.
+
+### What gets checked
+
+| You're making | Checks |
+|---------------|--------|
+| website | it builds · it looks like the original at 1440, 768 and 390 px · its tests pass |
+| cli | it builds · same exit code and ≥ 80% of the same words for each recorded input · tests |
+| app | it builds · it starts and draws a window (`--screenshot`) · tests |
+| game | it builds · a scripted self-test plays the core loop (`--self-test`) · a screenshot |
+| tool / library | it builds · tests that prove each feature you asked for |
+
+A round passes when no check fails and every score reaches 90%.
+
+### The project folder
+
+```text
+my-project/
+  craft.json       the request, target, kind, stack, mode and counters
+  BRIEF.md         the task as given to the agent
+  capture/         evidence from Study (read-only for the agent)
+  reference/       your own pictures or files (read-only for the agent)
+  app/             the build: the only folder the agent changes
+  checks/          every check round and every agent turn, with logs
+  unknowns.md      open questions about the original
+  questions.json   the agent's questions, with your answers
+```
+
+Everything is plain files, so you can stop at any time (Ctrl-C), close the terminal and carry on
+later with `craft run`.
+
+---
+
+## Clean room and Deep
+
+By default `craft` works in **clean room** mode: it uses only what a visitor or user can see
+(screenshots, visible text, what a program prints). It never opens the original's source, files or
+code.
+
+With `--deep`, the agent may also look inside the original (a page's HTML, a folder's files, a
+program's strings). Use it for your own software or private study.
+
+**Use it responsibly.** Rebuilding something for learning or as a starting point is fine; shipping
+someone else's brand, logos, images or text is not. The brief tells the agent to use neutral
+placeholders and never to copy the original's code or assets. Respect copyrights and the terms of
+the sites and programs you study.
+
+## Use it as a skill (Claude Code and other agents)
+
+The method behind `craft` is also written as a standalone skill that any agent can follow, with or
+without the CLI:
+
+```sh
+craft skill --install ~/.claude/skills    # Claude Code, all projects
+craft skill > SKILL.md                    # or print it for another agent
+```
+
+Then ask your agent: *"recreate example.com in React"*, and it follows the same
+study → build → check → refine steps.
+
+## Configuration
+
+Environment variables:
+
+| Variable | Effect |
+|----------|--------|
+| `CRAFT_AGENT=codex` | the agent to use (default: the first installed of claude, codex, gemini) |
+| `CRAFT_PROJECTS_DIR` | where the home screen creates projects (default `~/craft-projects`) |
+| `CRAFT_FEED=0` | hide the live action feed and keep only the progress line |
+| `NO_COLOR=1` | no colours |
+| `CRAFT_TURN_TIMEOUT` / `CRAFT_IDLE_TIMEOUT` | seconds per agent turn (3 h) / without output (20 min) |
+| `CRAFT_BROWSER=python\|chrome\|npx\|none` | how screenshots are taken |
+| `CRAFT_CHROME` | path to Chrome or Edge |
+| `CRAFT_PYTHON` | (npm install only) the Python to use |
+
+**Add or change an agent** in `~/.config/craft/agents.json`. Any command-line agent that reads its
+task from standard input works:
+
+```json
+{"my-agent": {"argv": ["my-agent", "--non-interactive"], "stream": "text"}}
+```
+
+Claude Code runs with `--permission-mode acceptEdits` and a fixed list of allowed tools (file
+edits, npm, cargo, go, python, make…). Permissions are never bypassed.
+
+---
+
+## Troubleshooting
+
+**"No coding agent found"**: install one of the [agents above](#install-a-coding-agent), sign in
+once, then run `craft agents` to confirm it's found.
+
+**"craft needs Python 3.9 or newer"** (npm install): install Python (see
+[What you need](#what-you-need)), or point to one with `CRAFT_PYTHON=/path/to/python3`.
+
+**`craft: command not found` after installing**:
+- npm: your npm global folder isn't on your PATH. `npm prefix -g` shows it; add its `bin` folder
+  to PATH. Or use `npx craftkit-cli`.
+- pipx: run `pipx ensurepath`, then open a new terminal.
+
+**The agent stops and asks to sign in**: run the agent once by itself (`claude`, `codex` or
+`gemini`), sign in, then `craft run` carries on where it stopped.
+
+**No screenshots for a website**: install Chrome, or `pip install playwright && playwright install
+chromium`.
+
+**Stopped half-way?** Nothing is lost: `craft run` resumes from the project folder.
+
+## Limitations
+
+- Visual comparison works on a colour grid. It catches layout and colour differences, not fine
+  details.
+- With headless Chrome, screenshots are 2400 px tall rather than the full page; visible-style
+  measurements need Playwright for Python.
+- The Codex and Gemini adapters haven't been tested against the real tools yet. Tested on macOS;
+  Linux and Windows aren't tested yet.
+
+## Credits and license
+
+`craft` distils the study → build → check → refine method of
+[Craft Anything](https://github.com/storytold/craft-anything) into a small terminal tool with no
+dependencies.
+
+Free and open source, under your choice of the [MIT](LICENSE-MIT) or
+[Apache 2.0](LICENSE-APACHE) license.