tewip-ai 0.11.0 → 0.13.0

package/README.md

@@ -181,6 +181,35 @@ Each reader was checked against real reports published in public repositories, w
 defects were found before release - a Robot timestamp that is not a date, k6's numbers living under
 `values`, and a JMeter line that read "mostly 200" when an assertion had failed.
 
+## Build a feature, test first (new)
+
+```bash
+tewip build "naturalsize should take a sep argument that goes between the number and the unit"
+tewip build --issue PROJ-123    # build from the ticket's own description and acceptance criteria
+tewip build "..." --pr          # commit the proved work on its own branch, open a draft PR
+tewip build "..." --dry-run     # prove it, show the patch, leave nothing on disk
+```
+
+Tewip writes the **test first** and runs it. **If that test passes, it stops and keeps nothing** —
+a test that passes before the feature exists is testing nothing. Then it writes the smallest code
+that makes the test pass, and keeps the work only if the new test passes *and* nothing that was
+passing has started to fail. Otherwise every file goes back byte for byte, including the test it
+wrote. Nothing is ever committed.
+
+Tried on two real public projects: it added a trailing-slash rule to **unjs/ufo** (4 lines,
+TypeScript, $0.18) and a `sep` argument to **python-humanize** (2 lines, Python, $0.10), each with
+its own failing-then-passing test and the project's whole suite still green. Asked for something
+that already worked, it stopped after one model call and kept nothing.
+
+It also refuses a feature that does not belong here at all. Handed a real Apache ticket about a
+Flink HTTP sink, a URL library got an "HTTP sink" built into it - test passing, suite green, every
+proof rule held, because when Tewip writes *both* the test and the code it can always make a
+self-consistent pair pass. So before writing anything it now asks whether the words of the feature
+mean anything in this repository, and refuses for free when they do not.
+
+The old promise was *"it can't touch your code"*. The new one is *"it can't change your code without
+showing you it works"*.
+
 ## Before anyone reads the diff (new)
 
 ```bash

package/TEAM-GUIDE.md

@@ -127,6 +127,7 @@ collects environment failures in one issue, and (optionally) opens a fix pull re
 | `tewip spec "<feature>"` | An epic, its user stories and acceptance criteria, grounded in your code; files them in Jira with `--project PROJ --create` | Before the work is broken down |
 | `tewip report report.xml --gate` | The CI command for GitLab, Jenkins, CircleCI, Azure, Bitbucket and the rest: diagnoses the run, comments on the GitLab merge request, and fails the build only on failures that need a person | Your CI is not GitHub Actions |
 | `tewip watch --cmd "npm test"` | Runs your tests when you save a file and explains each failure straight away | While you are writing code |
+| `tewip build "<what it should do>"` | Writes a feature test first, then the code, and keeps it only if the test failed without it and passes with it | You want a small feature built and proved |
 | `tewip review --diff main...HEAD` | Which tests cover your change, which have flaked before, what nothing tests, and what to run first | Before you open a pull request |
 | `tewip flaky --days 30` | Which tests to quarantine, which to fix, what they cost in CI minutes - and when a quarantined one can come back | Monday morning |
 | `tewip note --days 7` | The weekly quality note for a lead, from runs already diagnosed (no model calls, free) | Monday morning |

package/dist/cli/tewip.js

@@ -67,6 +67,14 @@ Usage:
                                     the GitLab merge request, tells Slack or Teams only when a
                                     failure needs a person, and with --gate fails the build only on
                                     those failures.
+  tewip build "<what it should do>" | --issue PROJ-123 [--dry-run] [--pr] [--out feature.patch]
+                                    Writes a feature, test first: the test must fail without the
+                                    code and pass with it, and every test that was passing must
+                                    still pass - otherwise everything goes back byte for byte.
+      --issue PROJ-123              Build from the ticket itself: its description and acceptance
+                                    criteria. Works with a public tracker without an account.
+      --pr                          Commit the proved work on a branch of its own and open a draft
+                                    pull request. Never merges, never commits to your branch.
   tewip review [--diff main...HEAD] [--out review.md]
                                     Before anyone reads the diff: which tests cover this change,
                                     which of them have flaked before, what has gone wrong in these
@@ -256,6 +264,59 @@ async function main() {
                 process.exitCode = 1;
             return;
         }
+        case 'build': {
+            const typed = args.filter((a, i) => !a.startsWith('--') && !['--repairs', '--out', '--max-lines', '--issue'].includes(args[i - 1] ?? '')).join(' ').trim();
+            const issueKey = flag(args, 'issue');
+            let feature = typed;
+            let issueTitle = '';
+            if (issueKey) {
+                // A ticket says what was asked for better than a sentence typed twice.
+                const { Jira, jiraFromEnv, jiraHelp } = await import('../engine/work/jira.js');
+                const { featureFromIssue } = await import('../engine/work/jira-command.js');
+                const config = jiraFromEnv();
+                if (!config)
+                    throw new Error(jiraHelp());
+                const issue = await new Jira(config).issue(issueKey);
+                console.error(`Read ${issue.key} (${issue.type}, ${issue.status})${issue.acceptanceCriteria ? ' with its acceptance criteria' : ''}.`);
+                issueTitle = `${issue.key}: ${issue.summary}`;
+                feature = [featureFromIssue(issue), typed].filter(Boolean).join('\n\n');
+            }
+            if (!feature)
+                throw new Error('usage: tewip build "<what the feature should do>" | --issue PROJ-123 [--dry-run] [--pr] [--out feature.patch]');
+            const { runBuild, renderBuild } = await import('../engine/build/build-command.js');
+            const dryRun = args.includes('--dry-run');
+            const result = await runBuild({
+                feature,
+                root: process.cwd(),
+                dryRun,
+                repairs: flag(args, 'repairs') === undefined ? 2 : Math.max(0, Number(flag(args, 'repairs')) || 0),
+                maxLines: flag(args, 'max-lines') ? Number(flag(args, 'max-lines')) : undefined,
+                out: flag(args, 'out'),
+            });
+            console.log(`
+${renderBuild(result, issueTitle || feature, dryRun)}`);
+            if (result.status !== 'built') {
+                process.exitCode = 1;
+                return;
+            }
+            if (args.includes('--pr')) {
+                if (dryRun)
+                    throw new Error('--pr and --dry-run ask for opposite things: one keeps the work, the other puts it back.');
+                const { proposePullRequest } = await import('../engine/build/propose-pr.js');
+                const proposed = proposePullRequest({
+                    root: process.cwd(),
+                    files: result.files,
+                    title: (issueTitle || feature.split('\n')[0]).slice(0, 72),
+                    body: result.why,
+                    issue: issueKey,
+                });
+                console.log(`
+${proposed.status === 'opened' ? 'Opened a draft pull request.' : proposed.status === 'committed' ? `Committed on ${proposed.branch}.` : 'No pull request was opened.'}`);
+                for (const line of proposed.next)
+                    console.log(`  ${line}`);
+            }
+            return;
+        }
         case 'review': {
             const { runReview } = await import('../engine/review/review-command.js');
             await runReview({

package/dist/engine/build/apply.js

@@ -0,0 +1,99 @@
+// Applying a set of edits to a working tree, and being able to put everything back exactly as it
+// was. Every step of building a feature is provisional until the tests say otherwise, so nothing
+// here writes anything it cannot undo.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { mayChange } from '../autofix/code-target.js';
+import { changedLines } from '../autofix/code-fix.js';
+export class Workspace {
+    root;
+    touched = new Map();
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    /** Remembers a file's contents the first time it is touched, so it can always be restored. */
+    remember(path) {
+        if (this.touched.has(path))
+            return;
+        this.touched.set(path, existsSync(path) ? readFileSync(path, 'utf8') : null);
+    }
+    write(path, content) {
+        this.remember(path);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content, 'utf8');
+    }
+    /** Everything back as it was: files restored, files Tewip created removed. */
+    restore() {
+        for (const [path, was] of this.touched) {
+            if (was === null)
+                rmSync(path, { force: true });
+            else
+                writeFileSync(path, was, 'utf8');
+        }
+        this.touched.clear();
+    }
+    /** Keeps the changes, and forgets how to undo them. */
+    keep() {
+        this.touched.clear();
+    }
+    /** What has been touched so far, for the report. */
+    files() {
+        return [...this.touched.keys()].map((p) => relative(this.root, p).split(sep).join('/'));
+    }
+}
+const CR = String.fromCharCode(13);
+const NL = String.fromCharCode(10);
+/**
+ * Applies a model's edits, refusing anything that is not allowed or does not match. Line endings
+ * are compared in one form, because a Windows checkout and a model's answer never agree on them.
+ */
+export function applyEdits(workspace, root, edits, maxLines) {
+    const applied = [];
+    const refused = [];
+    for (const edit of edits) {
+        const path = resolve(root, edit.file);
+        const rel = relative(resolve(root), path).split(sep).join('/');
+        if (rel.startsWith('..') || resolve(path).startsWith('..')) {
+            refused.push(`${edit.file} is outside the project`);
+            continue;
+        }
+        const allowed = mayChange(path);
+        if (!allowed.allowed) {
+            refused.push(`${rel} may not be changed: ${allowed.why}`);
+            continue;
+        }
+        const exists = existsSync(path);
+        if (!exists) {
+            if (edit.before.trim()) {
+                refused.push(`${rel} does not exist, but the change expects text to already be in it`);
+                continue;
+            }
+            workspace.write(path, edit.after);
+            applied.push({ ...edit, path, was: null, changed: edit.after.split(NL).length });
+            continue;
+        }
+        const raw = readFileSync(path, 'utf8');
+        const crlf = raw.includes(CR + NL);
+        const original = crlf ? raw.split(CR + NL).join(NL) : raw;
+        const before = edit.before.split(CR + NL).join(NL);
+        const after = edit.after.split(CR + NL).join(NL);
+        if (!before.trim()) {
+            refused.push(`${rel} already exists, so a change to it must say which text to replace`);
+            continue;
+        }
+        const occurrences = original.split(before).length - 1;
+        if (occurrences !== 1) {
+            refused.push(`the text to replace in ${rel} ${occurrences === 0 ? 'is not in the file' : `appears ${occurrences} times`}`);
+            continue;
+        }
+        const changed = original.replace(before, after);
+        const touched = changedLines(original, changed);
+        if (touched > maxLines) {
+            refused.push(`the change to ${rel} touches ${touched} lines, which is a rewrite rather than a feature`);
+            continue;
+        }
+        workspace.write(path, crlf ? changed.split(NL).join(CR + NL) : changed);
+        applied.push({ ...edit, path, was: raw, changed: touched });
+    }
+    return { applied, refused };
+}

package/dist/engine/build/build-command.js

@@ -0,0 +1,245 @@
+// `tewip build "<what it should do>"`: a feature, written test first and kept only when proved.
+//
+// The order is the product. Tewip writes the test, runs it, and **requires it to fail** - a test
+// that passes before the feature exists is testing nothing, and that single check is what stops a
+// model from writing code that agrees with itself. Then it writes the code, and keeps it only when
+// the new test passes and nothing that was passing has started to fail.
+//
+// Nothing is committed. Nothing is merged. What cannot be proved is put back byte for byte.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { chooseFramework, detectFrameworks } from '../quality/frameworks.js';
+import { existingTests, relatedCodeSources, relatedTestSources } from '../quality/grounding.js';
+import { writerFromEnv } from '../quality/model.js';
+import { usageLine } from '../llm/usage.js';
+import { failingTests } from '../autofix/code-fix.js';
+import { lineDiff, renderDiff } from '../autofix/line-diff.js';
+import { sourceFiles } from '../secure/secrets.js';
+import { applyEdits, Workspace } from './apply.js';
+import { repairFeatureCode, writeFeatureCode, writeFeatureTest } from './build.js';
+const run = (command, cwd, env, timeoutMs = 10 * 60_000) => {
+    const r = spawnSync(command, { cwd, env: { ...process.env, ...env }, shell: true, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 20 * 1024 * 1024 });
+    const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}${r.error ? `\n${r.error.message}` : ''}`.replace(/\u001b\[[0-9;]*[A-Za-z]/g, '').trim();
+    return { passed: r.status === 0, output: output.slice(-6000) };
+};
+const CODE_FILE = /\.(?:[cm]?[jt]sx?|py|rb|go|java|kt|cs|php|rs|vue|svelte)$/i;
+/**
+ * The files that define the things the feature names. Asking for "naturalsize should take a sep
+ * argument" and handing the model number.py and time.py - which is what similarity alone did -
+ * makes it answer, correctly, that it cannot see the code. The file that defines `naturalsize` is
+ * the one it needs, and finding it is a search, not a guess.
+ */
+export function definingSources(root, feature, limit = 3) {
+    const names = [...new Set((feature.match(/[A-Za-z_][A-Za-z0-9_]{3,}/g) ?? []).filter((w) => /[A-Z_]/.test(w) || w.length > 6))].slice(0, 12);
+    if (names.length === 0)
+        return [];
+    const scored = [];
+    for (const file of sourceFiles(root, 3000)) {
+        if (!CODE_FILE.test(file) || /(?:^|[\\/])(?:test|tests|spec|__tests__)[\\/]/i.test(file))
+            continue;
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // String.raw, because inside a plain template literal "\s" is just "s" and "\b" is a backspace.
+        const defines = new RegExp(String.raw `(?:^\s*(?:async\s+)?def\s+|export\s+(?:async\s+)?(?:function|const|class)\s+|function\s+)`, 'm');
+        const score = names.filter((n) => new RegExp(`${defines.source}${n}\\b`, 'm').test(text)).length;
+        if (score > 0)
+            scored.push({ file, score });
+    }
+    return scored.sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.file);
+}
+/**
+ * Does this feature belong in this project at all?
+ *
+ * Found by trying it: a real Apache ticket about a Flink HTTP sink was handed to a URL library, and
+ * Tewip built an "HTTP sink" into it - 28 lines, its own test passing, the suite green. Every proof
+ * rule held, because when Tewip writes both the test and the code it can always make a
+ * self-consistent pair pass. Nothing else referenced the invented API, so nothing else could break.
+ *
+ * The missing check is the obvious one: the words of the feature have to mean something here. A
+ * project's own vocabulary is its file names and what it exports, and a feature that shares almost
+ * none of it is a feature for some other repository.
+ */
+export function belongsHere(root, feature, sources, testNames) {
+    const stop = new Set(['should', 'when', 'with', 'that', 'this', 'from', 'into', 'have', 'been', 'will', 'must', 'also', 'able', 'given', 'then', 'there', 'their', 'which', 'while', 'where', 'after', 'before', 'value', 'values', 'return', 'returns', 'support', 'supports', 'accept', 'accepts', 'option', 'options', 'default', 'behaviour', 'behavior', 'feature', 'example', 'instead', 'without']);
+    const words = (text) => new Set((text.toLowerCase().match(/[a-z][a-z0-9]{3,}/g) ?? []).filter((w) => !stop.has(w)));
+    const asked = [...words(feature)];
+    if (asked.length < 3)
+        return { ok: true, why: '' };
+    const vocabulary = new Set();
+    for (const s of sources)
+        for (const w of words(`${s.file} ${s.content.slice(0, 20_000)}`))
+            vocabulary.add(w);
+    for (const name of testNames)
+        for (const w of words(name))
+            vocabulary.add(w);
+    // The names of a project's files are not its vocabulary: "naturalsize" lives inside filesize.py,
+    // not in its name, and judging by names alone refused a feature that really did belong here.
+    let read = 0;
+    for (const file of sourceFiles(root, 1200)) {
+        if (!CODE_FILE.test(file) || read >= 60)
+            continue;
+        read++;
+        try {
+            for (const w of words(`${basename(file)} ${readFileSync(file, 'utf8').slice(0, 20_000)}`))
+                vocabulary.add(w);
+        }
+        catch {
+            // unreadable here is simply one less file of vocabulary
+        }
+    }
+    if (vocabulary.size === 0)
+        return { ok: true, why: '' };
+    const shared = asked.filter((w) => vocabulary.has(w));
+    const share = shared.length / asked.length;
+    if (share >= 0.2)
+        return { ok: true, why: '' };
+    return {
+        ok: false,
+        why: `almost nothing in this project mentions what that describes (${shared.length} of ${asked.length} of its words appear here${shared.length ? `: ${shared.slice(0, 5).join(', ')}` : ''}). If this is the right repository, say the feature in its own words - the names of the functions and files it should change. Tewip can make a test of its own invention pass in any project, and that would prove nothing.`,
+    };
+}
+/** A test file name in the project's own shape, that does not collide with an existing one. */
+function testPathFor(framework, feature) {
+    const stem = feature.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').split('-').slice(0, 4).join('-') || 'feature';
+    let path = join(framework.testDir, framework.fileFor(stem));
+    let n = 2;
+    while (existsSync(path))
+        path = join(framework.testDir, framework.fileFor(`${stem}-${n++}`));
+    return path;
+}
+/** What the model is shown: the files that define what the feature names, then the similar ones. */
+function sourcesFor(root, feature) {
+    const defining = definingSources(root, feature).map((file) => ({ file: relative(root, file).split(sep).join('/'), content: readFileSync(file, 'utf8') }));
+    const similar = relatedCodeSources(root, feature).map((s) => ({ file: s.file, content: s.content }));
+    const seen = new Set(defining.map((s) => s.file));
+    return [...defining, ...similar.filter((s) => !seen.has(s.file))].slice(0, 4);
+}
+export async function runBuild(cmd) {
+    const root = resolve(cmd.root);
+    const model = cmd.model ?? writerFromEnv(root);
+    if (!model)
+        throw new Error('building a feature needs a model. Set TEWIP_API_KEY (and TEWIP_PROVIDER), or OPENAI_API_KEY.');
+    const runIt = cmd.runCommand ?? ((command, cwd) => run(command, cwd, framework?.env));
+    const framework = chooseFramework(detectFrameworks(root), undefined, false) ?? detectFrameworks(root)[0] ?? null;
+    if (!framework) {
+        return { status: 'no-framework', why: 'no test framework was found here, and a feature Tewip cannot test is a feature it will not write.', files: [], diff: '', log: [] };
+    }
+    const tests = existingTests(root);
+    const ctx = {
+        feature: cmd.feature,
+        framework,
+        exampleTest: framework.example ? readFileSync(framework.example, 'utf8') : (relatedTestSources(root, cmd.feature)[0]?.content ?? ''),
+        sources: sourcesFor(root, cmd.feature),
+        testNames: tests.tests,
+    };
+    const log = [`framework: ${framework.label}`, `source files read: ${ctx.sources.map((s) => s.file).join(', ') || 'none found'}`];
+    // Before anything is written: is this even a feature for this repository?
+    const belongs = belongsHere(root, cmd.feature, ctx.sources, ctx.testNames);
+    if (!belongs.ok)
+        return { status: 'not-this-project', why: belongs.why, files: [], diff: '', log: [...log, belongs.why] };
+    const workspace = new Workspace(root);
+    const maxLines = cmd.maxLines ?? 120;
+    const stop = (status, why) => {
+        workspace.restore();
+        return { status, why, files: [], diff: '', log: [...log, why] };
+    };
+    // 1. The test, first - and it has to fail.
+    console.log('Writing the test first...');
+    const draft = await writeFeatureTest(model, ctx);
+    const testPath = testPathFor(framework, cmd.feature);
+    mkdirSync(dirname(testPath), { recursive: true });
+    workspace.write(testPath, draft.code);
+    const testRel = relative(root, testPath).split(sep).join('/');
+    log.push(`wrote ${testRel}: ${draft.checks}`);
+    const before = runIt(framework.command(testPath), framework.cwd);
+    if (before.passed) {
+        return stop('test-passes-already', `the test passes without any new code, so it is not testing the feature. Either ${cmd.feature} already works, or the test checks something that is already true. Nothing was kept.`);
+    }
+    log.push(`the test fails today, as it must: ${draft.failsBecause}`);
+    // What is already broken here, so the feature is never blamed for it.
+    const baselineRun = runIt(framework.suite, framework.cwd);
+    const alreadyFailing = new Set(baselineRun.passed ? [] : failingTests(baselineRun.output));
+    if (alreadyFailing.size > 0)
+        log.push(`${alreadyFailing.size} test(s) were already failing before anything was written, and are not counted against the feature`);
+    // 2. The code.
+    console.log('Writing the code...');
+    let change = await writeFeatureCode(model, ctx, { file: testRel, code: draft.code }, before.output);
+    const attempts = Math.max(1, (cmd.repairs ?? 2) + 1);
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        if (change.outcome === 'cannot' || change.edits.length === 0) {
+            return stop('no-code', `Tewip did not write code for this: ${change.why || 'it could not see how, from what this project gave it'}. The test it wrote is a good description of what is missing; run \`tewip build\` again with more detail, or write the code yourself against that test.`);
+        }
+        const { applied, refused } = applyEdits(workspace, root, change.edits, maxLines);
+        for (const why of refused)
+            log.push(`refused: ${why}`);
+        if (applied.length === 0) {
+            return stop('refused', `every change offered was refused: ${refused.join('; ') || 'nothing could be applied'}`);
+        }
+        log.push(`attempt ${attempt}: changed ${applied.map((e) => `${relative(root, e.path).split(sep).join('/')} (${e.changed} line(s))`).join(', ')}`);
+        const after = runIt(framework.command(testPath), framework.cwd);
+        if (!after.passed) {
+            if (attempt === attempts)
+                return stop('still-failing', 'the test still fails after every attempt, so everything was put back byte for byte.');
+            console.log(`The test still fails; correcting (attempt ${attempt + 1})...`);
+            change = await repairFeatureCode(model, ctx, { edits: change.edits, output: after.output, broke: [] });
+            continue;
+        }
+        const suite = runIt(framework.suite, framework.cwd);
+        const broke = failingTests(suite.output).filter((name) => !alreadyFailing.has(name));
+        if (!suite.passed && (broke.length > 0 || failingTests(suite.output).length === 0)) {
+            if (attempt === attempts)
+                return stop('broke-others', `the new test passes, but this broke tests that were passing: ${broke.slice(0, 6).join(', ') || 'see the suite output'}. Everything was put back.`);
+            console.log('The new test passes but something else broke; correcting...');
+            change = await repairFeatureCode(model, ctx, { edits: change.edits, output: suite.output, broke });
+            continue;
+        }
+        // Proved: the new test passes, and nothing that was passing fails.
+        log.push('the new test passes, and everything that was passing still passes');
+        const diff = [
+            renderDiff(testRel, lineDiff('', draft.code)),
+            ...applied.map((e) => renderDiff(relative(root, e.path).split(sep).join('/'), lineDiff(e.was ?? '', readFileSync(e.path, 'utf8')))),
+        ]
+            .filter(Boolean)
+            .join('\n');
+        const files = [testRel, ...applied.map((e) => relative(root, e.path).split(sep).join('/'))];
+        if (cmd.dryRun) {
+            workspace.restore();
+            log.push('dry run: everything was put back, and only the patch above is yours to apply');
+        }
+        else {
+            workspace.keep();
+        }
+        if (cmd.out) {
+            mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
+            writeFileSync(resolve(cmd.out), `${diff}\n`, 'utf8');
+        }
+        return { status: 'built', why: change.why, testFile: testRel, files, diff, log };
+    }
+    return stop('still-failing', 'no change could be proved');
+}
+/** What the person reads afterwards. */
+export function renderBuild(result, feature, dryRun) {
+    const lines = [`# ${result.status === 'built' ? 'Built' : 'Not built'}: ${feature}`, ''];
+    for (const line of result.log)
+        lines.push(`- ${line}`);
+    lines.push('');
+    if (result.status !== 'built') {
+        lines.push(result.why, '', 'Nothing was kept. Tewip only leaves code behind when the test it wrote first fails without it and passes with it.');
+        return lines.join('\n');
+    }
+    lines.push(`**What it does.** ${result.why}`, '');
+    lines.push('```diff', result.diff, '```', '');
+    lines.push(dryRun ? 'This was a dry run: nothing is on disk. Apply the patch above if you want it.' : `Left in your working tree: ${result.files.join(', ')}. Nothing was committed.`);
+    lines.push('');
+    lines.push('It is proved in the only way that means anything: the test failed without this code and passes with it, and every test that was passing still passes. Read it before you commit it.');
+    const usage = usageLine();
+    if (usage)
+        lines.push('', usage);
+    return lines.join('\n');
+}

package/dist/engine/build/build.js

@@ -0,0 +1,89 @@
+export const BUILD_PROMPT_VERSION = 'build-1';
+const RULES = `Rules that do not bend:
+- Use only what the project already has: its framework, its style, its helpers, its way of importing. Copy the shape of the example test and the example source given.
+- Never weaken or delete an existing test, and never change what one asserts.
+- Keep the change small and local. Add a file when the project's own layout calls for one; do not reorganise anything.
+- Write no comments that restate the code, no logging, no defensive try/catch around things that cannot fail.
+- before must be copied character for character from the file given and appear in it exactly once. For a new file, before is empty and after is the whole file.`;
+const TEST_SYSTEM = `You are Tewip, writing the test for a feature that does not exist yet.
+
+Write ONE test that checks the described behaviour, in the project's own framework and style. It must fail when run now, and fail for the right reason: the behaviour is missing, not because of a typo, a missing import or a file that does not exist. Use only functions, files and exports that already exist, or the one new export the feature obviously needs - name it as the project would.
+
+checks is one sentence naming the behaviour the test asserts ("a full URL keeps its query when the trailing slash is removed"). It is not advice about file names or where to put things.
+failsBecause is the behaviour that is missing today, in one sentence.
+
+${RULES}`;
+const CODE_SYSTEM = `You are Tewip, writing the code that makes a failing test pass.
+
+You are given the feature, the test, the real error it produced, and the project's relevant source. Write the smallest change that makes that test pass because the behaviour now exists - never by weakening the test, never by special-casing the test's own values.
+
+If the feature cannot be built from what you were given - the code you need is not here, or the request is ambiguous in a way that changes the answer - set outcome to "cannot" and return no edits. Saying "I cannot" is a correct answer; a guess that happens to pass one test is not.
+
+${RULES}`;
+const REPAIR_SYSTEM = `You are Tewip, fixing code you just wrote. The test still fails, or other tests broke. You are given what you changed and the real output.
+
+Change your own code so the failing test passes and everything that was passing still passes. Never change the test. If you cannot, set outcome to "cannot".
+
+${RULES}`;
+const TEST_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['code', 'checks', 'failsBecause'],
+    properties: { code: { type: 'string' }, checks: { type: 'string' }, failsBecause: { type: 'string' } },
+};
+const EDIT = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['file', 'before', 'after'],
+    properties: { file: { type: 'string' }, before: { type: 'string' }, after: { type: 'string' } },
+};
+const CODE_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['outcome', 'why', 'edits'],
+    properties: { outcome: { type: 'string', enum: ['built', 'cannot'] }, why: { type: 'string' }, edits: { type: 'array', items: EDIT } },
+};
+export async function writeFeatureTest(model, ctx) {
+    const raw = await model.complete({
+        system: TEST_SYSTEM,
+        user: JSON.stringify({
+            feature: ctx.feature,
+            framework: ctx.framework.label,
+            exampleTest: ctx.exampleTest.slice(0, 6000),
+            existingTestNames: ctx.testNames.slice(0, 60),
+            source: ctx.sources.map((s) => ({ file: s.file, content: s.content.slice(0, 6000) })),
+        }),
+        schemaName: 'tewip_feature_test',
+        schema: TEST_SCHEMA,
+    });
+    return JSON.parse(raw);
+}
+export async function writeFeatureCode(model, ctx, test, error) {
+    const raw = await model.complete({
+        system: CODE_SYSTEM,
+        user: JSON.stringify({
+            feature: ctx.feature,
+            test: { file: test.file, code: test.code.slice(0, 8000) },
+            errorItProduced: error.slice(0, 4000),
+            source: ctx.sources.map((s) => ({ file: s.file, content: s.content.slice(0, 12_000) })),
+        }),
+        schemaName: 'tewip_feature_code',
+        schema: CODE_SCHEMA,
+    });
+    return JSON.parse(raw);
+}
+export async function repairFeatureCode(model, ctx, attempt) {
+    const raw = await model.complete({
+        system: REPAIR_SYSTEM,
+        user: JSON.stringify({
+            feature: ctx.feature,
+            whatYouChanged: attempt.edits.map((e) => ({ file: e.file, after: e.after.slice(0, 4000) })),
+            output: attempt.output.slice(0, 4000),
+            testsThatBroke: attempt.broke.slice(0, 10),
+            source: ctx.sources.map((s) => ({ file: s.file, content: s.content.slice(0, 12_000) })),
+        }),
+        schemaName: 'tewip_feature_repair',
+        schema: CODE_SCHEMA,
+    });
+    return JSON.parse(raw);
+}

package/dist/engine/build/propose-pr.js

@@ -0,0 +1,88 @@
+// Turning proved work into a pull request - the last step of the loop, and the one where Tewip
+// touches somebody's repository, so it is the most careful.
+//
+// Three rules, enforced here rather than promised:
+//   it only ever pushes a new branch of its own, never yours;
+//   it never merges, and opens the request as a draft so nobody can merge it by reflex;
+//   it describes exactly what was proved and what was not, because a pull request nobody can check
+//   is worse than a patch file.
+//
+// The work must already be proved before anything reaches this file. Nothing here runs a test or
+// decides anything; it commits what was verified and opens the request.
+import { spawnSync } from 'node:child_process';
+const run = (cwd, command, args) => {
+    const r = spawnSync(command, args, { cwd, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+    return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
+};
+/** A branch name a person can read at a glance, and that cannot collide with an existing one. */
+export function branchNameFor(title, now = new Date()) {
+    const stem = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').split('-').slice(0, 6).join('-') || 'change';
+    return `tewip/${stem}-${now.toISOString().slice(2, 16).replace(/\D/g, '')}`;
+}
+/** The pull request body: what was built, and precisely how far the proof goes. */
+export function requestBody(body, files, issue) {
+    return [
+        body,
+        '',
+        `Files: ${files.map((f) => `\`${f}\``).join(', ')}`,
+        issue ? `From: ${issue}` : '',
+        '',
+        '---',
+        '',
+        'Written by Tewip and kept only because it was proved: the test failed without this change and',
+        'passes with it, and every test that was passing still passes.',
+        '',
+        'What that does **not** say: whether this is the design you want, whether it is the right place',
+        'for it, or whether it is complete. That is what your review is for. This is a draft on a branch',
+        'of its own; Tewip never merges anything.',
+    ]
+        .filter((line) => line !== '')
+        .join('\n');
+}
+/**
+ * Commits the proved files on a fresh branch and opens a draft pull request with the `gh` CLI the
+ * developer is already logged into. When there is no `gh`, the branch is still pushed and the
+ * command to open the request by hand is printed - half a job done is better than a silent failure.
+ */
+export function proposePullRequest(input) {
+    const { root, files } = input;
+    if (files.length === 0)
+        return { status: 'refused', next: ['there was nothing to commit'] };
+    if (!run(root, 'git', ['rev-parse', '--git-dir']).ok)
+        return { status: 'refused', next: ['this is not a git checkout, so there is no branch to open a request from'] };
+    const branch = branchNameFor(input.title);
+    const base = run(root, 'git', ['rev-parse', '--abbrev-ref', 'HEAD']).out.trim() || 'main';
+    // A branch of Tewip's own, from wherever the person is standing. Their branch is never committed to.
+    const made = run(root, 'git', ['checkout', '-b', branch]);
+    if (!made.ok)
+        return { status: 'refused', next: [`could not create the branch ${branch}: ${made.out.slice(0, 200)}`] };
+    const added = run(root, 'git', ['add', '--', ...files]);
+    if (!added.ok) {
+        run(root, 'git', ['checkout', base]);
+        return { status: 'refused', next: [`could not stage the files: ${added.out.slice(0, 200)}`] };
+    }
+    // Only Tewip's own files are committed: anything else the person had in progress stays theirs.
+    const committed = run(root, 'git', ['commit', '-m', input.title, '-m', requestBody(input.body, files, input.issue), '--only', '--', ...files]);
+    if (!committed.ok) {
+        run(root, 'git', ['checkout', base]);
+        return { status: 'refused', next: [`could not commit: ${committed.out.slice(0, 200)}`] };
+    }
+    const next = [];
+    const pushed = run(root, 'git', ['push', '-u', 'origin', branch]);
+    if (!pushed.ok) {
+        return {
+            status: 'committed',
+            branch,
+            next: [`the work is committed on ${branch}, but pushing failed: ${pushed.out.slice(0, 200)}`, `push it yourself with: git push -u origin ${branch}`],
+        };
+    }
+    const gh = run(root, 'gh', ['pr', 'create', '--draft', '--base', base, '--head', branch, '--title', input.title, '--body', requestBody(input.body, files, input.issue)]);
+    if (gh.ok) {
+        const url = (gh.out.match(/https:\/\/\S+/) ?? [])[0];
+        return { status: 'opened', branch, url, next: [`review it: ${url ?? branch}`, `back to where you were: git checkout ${base}`] };
+    }
+    next.push(`${branch} is pushed, but the pull request was not opened: ${gh.out.slice(0, 200)}`);
+    next.push(`open it with: gh pr create --draft --base ${base} --head ${branch}`);
+    next.push(`back to where you were: git checkout ${base}`);
+    return { status: 'committed', branch, next };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [
     "test-failures",