runwork 0.9.4 → 0.10.1

package/dist/utils/__tests__/http.test.js

@@ -0,0 +1,381 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { createServer } from 'node:http';
+import { gzipSync, deflateSync, brotliCompressSync } from 'node:zlib';
+import { spawnSync } from 'node:child_process';
+import { httpFetch, __setTransportForTests } from '../http.js';
+let server;
+let port;
+const calls = [];
+function startServer() {
+    return new Promise((resolve) => {
+        server = createServer(async (req, res) => {
+            const chunks = [];
+            for await (const chunk of req)
+                chunks.push(chunk);
+            const body = Buffer.concat(chunks).toString('utf-8');
+            calls.push({ url: req.url || '', method: req.method || '', headers: req.headers, body });
+            const url = req.url || '/';
+            // Simple endpoints exercised by the test cases below.
+            if (url === '/json') {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ hello: 'world' }));
+                return;
+            }
+            if (url === '/text') {
+                res.writeHead(200, { 'content-type': 'text/plain' });
+                res.end('plain body');
+                return;
+            }
+            if (url === '/binary') {
+                res.writeHead(200, { 'content-type': 'application/octet-stream' });
+                res.end(Buffer.from([1, 2, 3, 4, 5]));
+                return;
+            }
+            if (url === '/echo-headers') {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ headers: req.headers, method: req.method }));
+                return;
+            }
+            if (url === '/echo-body') {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ body, contentType: req.headers['content-type'] }));
+                return;
+            }
+            if (url === '/status/404') {
+                res.writeHead(404, { 'content-type': 'text/plain' });
+                res.end('not found');
+                return;
+            }
+            if (url === '/status/500') {
+                res.writeHead(500, { 'content-type': 'text/plain' });
+                res.end('boom');
+                return;
+            }
+            if (url === '/redirect/302') {
+                res.writeHead(302, { location: '/json' });
+                res.end();
+                return;
+            }
+            if (url === '/redirect/303-post') {
+                res.writeHead(303, { location: '/echo-headers' });
+                res.end();
+                return;
+            }
+            if (url === '/redirect/307') {
+                res.writeHead(307, { location: '/echo-body' });
+                res.end();
+                return;
+            }
+            if (url === '/redirect/loop') {
+                res.writeHead(302, { location: '/redirect/loop' });
+                res.end();
+                return;
+            }
+            if (url === '/gzip') {
+                res.writeHead(200, { 'content-type': 'text/plain', 'content-encoding': 'gzip' });
+                res.end(gzipSync(Buffer.from('compressed-gzip-body')));
+                return;
+            }
+            if (url === '/deflate') {
+                res.writeHead(200, { 'content-type': 'text/plain', 'content-encoding': 'deflate' });
+                res.end(deflateSync(Buffer.from('compressed-deflate-body')));
+                return;
+            }
+            if (url === '/brotli') {
+                res.writeHead(200, { 'content-type': 'text/plain', 'content-encoding': 'br' });
+                res.end(brotliCompressSync(Buffer.from('compressed-brotli-body')));
+                return;
+            }
+            if (url === '/head') {
+                res.writeHead(200, { 'content-type': 'text/plain', 'x-marker': 'present' });
+                res.end();
+                return;
+            }
+            res.writeHead(404);
+            res.end();
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (typeof addr === 'object' && addr && 'port' in addr) {
+                port = addr.port;
+            }
+            resolve();
+        });
+    });
+}
+beforeAll(async () => { await startServer(); });
+afterAll(() => new Promise((resolve) => server.close(() => resolve())));
+function url(path) { return `http://127.0.0.1:${port}${path}`; }
+describe('httpFetch — basic Response surface', () => {
+    it('parses JSON responses', async () => {
+        const res = await httpFetch(url('/json'));
+        expect(res.ok).toBe(true);
+        expect(res.status).toBe(200);
+        expect(res.headers.get('content-type')).toContain('application/json');
+        expect(await res.json()).toEqual({ hello: 'world' });
+    });
+    it('reads text responses', async () => {
+        const res = await httpFetch(url('/text'));
+        expect(res.ok).toBe(true);
+        expect(await res.text()).toBe('plain body');
+    });
+    it('reads binary responses as ArrayBuffer with the exact byte content', async () => {
+        const res = await httpFetch(url('/binary'));
+        const ab = await res.arrayBuffer();
+        expect(new Uint8Array(ab)).toEqual(new Uint8Array([1, 2, 3, 4, 5]));
+    });
+    it('returns ok=false for 4xx without throwing', async () => {
+        const res = await httpFetch(url('/status/404'));
+        expect(res.ok).toBe(false);
+        expect(res.status).toBe(404);
+        expect(await res.text()).toBe('not found');
+    });
+    it('returns ok=false for 5xx without throwing', async () => {
+        const res = await httpFetch(url('/status/500'));
+        expect(res.ok).toBe(false);
+        expect(res.status).toBe(500);
+    });
+});
+describe('httpFetch — request shape', () => {
+    it('passes through plain object headers, lowercased per HTTP convention', async () => {
+        const res = await httpFetch(url('/echo-headers'), {
+            headers: { 'X-Custom-Foo': 'bar', Authorization: 'Bearer abc' },
+        });
+        const data = await res.json();
+        expect(data.method).toBe('GET');
+        expect(data.headers['x-custom-foo']).toBe('bar');
+        expect(data.headers['authorization']).toBe('Bearer abc');
+    });
+    it('passes through Headers instance', async () => {
+        const headers = new Headers();
+        headers.set('X-One', 'a');
+        headers.set('X-Two', 'b');
+        const res = await httpFetch(url('/echo-headers'), { headers });
+        const data = await res.json();
+        expect(data.headers['x-one']).toBe('a');
+        expect(data.headers['x-two']).toBe('b');
+    });
+    it('uppercases lowercase methods', async () => {
+        const res = await httpFetch(url('/echo-headers'), { method: 'post', body: '' });
+        const data = await res.json();
+        expect(data.method).toBe('POST');
+    });
+    it('sends string body and content-length', async () => {
+        const res = await httpFetch(url('/echo-body'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ a: 1 }),
+        });
+        const data = await res.json();
+        expect(data.body).toBe('{"a":1}');
+        expect(data.contentType).toBe('application/json');
+    });
+    it('sends Buffer body', async () => {
+        const res = await httpFetch(url('/echo-body'), {
+            method: 'PUT',
+            body: Buffer.from('raw-buffer'),
+        });
+        const data = await res.json();
+        expect(data.body).toBe('raw-buffer');
+    });
+    it('sends Uint8Array body with offset', async () => {
+        const backing = new Uint8Array([0, 0, 65, 66, 67, 0]);
+        const view = backing.subarray(2, 5); // "ABC"
+        const res = await httpFetch(url('/echo-body'), { method: 'POST', body: view });
+        const data = await res.json();
+        expect(data.body).toBe('ABC');
+    });
+    it('sends ArrayBuffer body', async () => {
+        const ab = new TextEncoder().encode('via-arraybuffer').buffer;
+        const res = await httpFetch(url('/echo-body'), { method: 'POST', body: ab });
+        const data = await res.json();
+        expect(data.body).toBe('via-arraybuffer');
+    });
+    it('drops body on bodyless GET/HEAD methods (matches fetch behavior)', async () => {
+        const res = await httpFetch(url('/echo-body'), {
+            method: 'GET',
+            // GET requests with bodies are non-conformant; fetch silently drops the body.
+            body: 'should-not-be-sent',
+        });
+        const data = await res.json();
+        expect(data.body).toBe('');
+    });
+});
+describe('httpFetch — redirects', () => {
+    it('follows a 302 to the final URL', async () => {
+        const res = await httpFetch(url('/redirect/302'));
+        expect(res.status).toBe(200);
+        expect(res.url.endsWith('/json')).toBe(true);
+        expect(await res.json()).toEqual({ hello: 'world' });
+    });
+    it('downgrades POST to GET on 303 (matches fetch semantics)', async () => {
+        const res = await httpFetch(url('/redirect/303-post'), {
+            method: 'POST',
+            body: 'ignored-after-303',
+        });
+        const data = await res.json();
+        expect(data.method).toBe('GET');
+    });
+    it('preserves method and body on 307', async () => {
+        const res = await httpFetch(url('/redirect/307'), {
+            method: 'POST',
+            body: 'preserved-on-307',
+        });
+        const data = await res.json();
+        expect(data.body).toBe('preserved-on-307');
+    });
+    it('rejects after exceeding the redirect limit', async () => {
+        // The endpoint redirects to itself; after MAX_REDIRECTS we stop following
+        // and return the redirect response itself rather than crash.
+        const res = await httpFetch(url('/redirect/loop'));
+        expect(res.status).toBe(302);
+    });
+});
+describe('httpFetch — content decoding', () => {
+    it('advertises gzip/deflate/br by default', async () => {
+        await httpFetch(url('/echo-headers'));
+        const last = calls[calls.length - 1];
+        expect(last.headers['accept-encoding']).toBe('gzip, deflate, br');
+    });
+    it('decompresses gzip responses transparently', async () => {
+        const res = await httpFetch(url('/gzip'));
+        expect(await res.text()).toBe('compressed-gzip-body');
+    });
+    it('decompresses brotli responses transparently', async () => {
+        const res = await httpFetch(url('/brotli'));
+        expect(await res.text()).toBe('compressed-brotli-body');
+    });
+    it('decompresses deflate responses transparently', async () => {
+        const res = await httpFetch(url('/deflate'));
+        expect(await res.text()).toBe('compressed-deflate-body');
+    });
+});
+describe('httpFetch — HEAD requests', () => {
+    it('returns headers and an empty body', async () => {
+        const res = await httpFetch(url('/head'), { method: 'HEAD' });
+        expect(res.status).toBe(200);
+        expect(res.headers.get('x-marker')).toBe('present');
+        expect(await res.text()).toBe('');
+    });
+});
+describe('httpFetch — errors', () => {
+    it('rejects on connection failure', async () => {
+        // 127.0.0.1:1 is virtually guaranteed to refuse connections.
+        await expect(httpFetch('http://127.0.0.1:1/')).rejects.toThrow();
+    });
+    it('rejects on unsupported protocols', async () => {
+        await expect(httpFetch('ftp://example.com/')).rejects.toThrow(/Unsupported protocol/);
+    });
+});
+// ────────────────────────────────────────────────────────────────────────
+// curl-transport tests
+//
+// `curl` is the opt-in escape hatch (`RUNWORK_HTTP_TRANSPORT=curl`). It
+// shells out to the system `curl` so HTTP runs in a subprocess, immune to
+// any future runtime regression. These tests force the curl path via the
+// test-only override so the break-glass path stays exercised in CI even
+// though the default transport is `node:https`. Skipped when curl is
+// missing on the host.
+// ────────────────────────────────────────────────────────────────────────
+const curlAvailable = (() => {
+    try {
+        const r = spawnSync('curl', ['--version'], { encoding: 'utf-8' });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+})();
+describe.skipIf(!curlAvailable)('httpFetch — curl transport (opt-in via env var)', () => {
+    beforeAll(() => { __setTransportForTests('curl'); });
+    afterAll(() => { __setTransportForTests('auto'); });
+    it('parses JSON responses through curl', async () => {
+        const res = await httpFetch(url('/json'));
+        expect(res.ok).toBe(true);
+        expect(res.status).toBe(200);
+        expect(await res.json()).toEqual({ hello: 'world' });
+    });
+    it('reads binary responses with exact byte content', async () => {
+        const res = await httpFetch(url('/binary'));
+        const ab = await res.arrayBuffer();
+        expect(new Uint8Array(ab)).toEqual(new Uint8Array([1, 2, 3, 4, 5]));
+    });
+    it('returns ok=false for 4xx without throwing', async () => {
+        const res = await httpFetch(url('/status/404'));
+        expect(res.ok).toBe(false);
+        expect(res.status).toBe(404);
+        expect(await res.text()).toBe('not found');
+    });
+    it('follows 302 redirects to the final URL', async () => {
+        const res = await httpFetch(url('/redirect/302'));
+        expect(res.status).toBe(200);
+        expect(res.url.endsWith('/json')).toBe(true);
+        expect(await res.json()).toEqual({ hello: 'world' });
+    });
+    it('downgrades POST to GET on 303 (matches fetch semantics)', async () => {
+        const res = await httpFetch(url('/redirect/303-post'), {
+            method: 'POST',
+            body: 'ignored-after-303',
+        });
+        const data = await res.json();
+        expect(data.method).toBe('GET');
+    });
+    it('preserves method and body on 307', async () => {
+        const res = await httpFetch(url('/redirect/307'), {
+            method: 'POST',
+            body: 'preserved-on-307',
+        });
+        const data = await res.json();
+        expect(data.body).toBe('preserved-on-307');
+    });
+    it('passes plain object headers through', async () => {
+        const res = await httpFetch(url('/echo-headers'), {
+            headers: { 'X-Custom': 'curl-roundtrip', Authorization: 'Bearer abc' },
+        });
+        const data = await res.json();
+        expect(data.headers['x-custom']).toBe('curl-roundtrip');
+        expect(data.headers['authorization']).toBe('Bearer abc');
+    });
+    it('sends string body and content-type', async () => {
+        const res = await httpFetch(url('/echo-body'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ a: 1 }),
+        });
+        const data = await res.json();
+        expect(data.body).toBe('{"a":1}');
+        expect(data.contentType).toBe('application/json');
+    });
+    it('sends binary Uint8Array body with offset', async () => {
+        const backing = new Uint8Array([0, 0, 65, 66, 67, 0]);
+        const view = backing.subarray(2, 5); // "ABC"
+        const res = await httpFetch(url('/echo-body'), { method: 'POST', body: view });
+        const data = await res.json();
+        expect(data.body).toBe('ABC');
+    });
+    it('returns headers and an empty body for HEAD', async () => {
+        const res = await httpFetch(url('/head'), { method: 'HEAD' });
+        expect(res.status).toBe(200);
+        expect(res.headers.get('x-marker')).toBe('present');
+        expect(await res.text()).toBe('');
+    });
+    it('warns and returns raw bytes on unexpected gzip', async () => {
+        const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        try {
+            const res = await httpFetch(url('/gzip'));
+            expect(res.ok).toBe(true);
+            const ab = await res.arrayBuffer();
+            expect(ab.byteLength).toBeGreaterThan(0);
+            expect(stderr).toHaveBeenCalledWith(expect.stringMatching(/Content-Encoding: gzip/));
+        }
+        finally {
+            stderr.mockRestore();
+        }
+    });
+    it('rejects on connection failure', async () => {
+        await expect(httpFetch('http://127.0.0.1:1/')).rejects.toThrow();
+    });
+    it('rejects on unsupported protocols', async () => {
+        await expect(httpFetch('ftp://example.com/')).rejects.toThrow(/Unsupported protocol/);
+    });
+});

package/dist/utils/agent-guidance.js

@@ -20,13 +20,19 @@ export const APP_STRUCTURE = {
 };
 const COMMON_TIPS = [
     'Read CLAUDE.md in the app directory first -- it has complete framework documentation with code examples.',
-    'You do NOT need git commands. runwork dev handles file syncing automatically.',
+    'You do NOT need to run git commands manually. runwork dev handles file syncing automatically. (git itself must be installed on the system -- see dependencies.)',
     'Do NOT install external AI SDKs (openai, @anthropic-ai/sdk). Use @runworkai/framework/ai instead.',
     'Every workflow MUST have a trigger (API endpoint, scheduled job, or UI button). Workflows without triggers are dead code.',
     'Every conversational agent MUST have a frontend page to access it.',
     'After adding entities, workflows, or agents, update blueprint.json with the new metadata.',
     'Never guess integration IDs. Run: runwork integrations search <query>',
 ];
+/**
+ * Required system dependencies for the Runwork CLI to function. The AI agent
+ * reading these guides should verify each is installed and install missing
+ * ones for the user using whatever method is appropriate for their platform.
+ */
+const SYSTEM_DEPENDENCIES_NOTE = 'System dependency: git must be installed on this machine. The CLI uses git internally to sync files between local and the workspace remote. Verify with: git --version. If missing, the AI agent reading this guide should install git for the user without prompting -- pick the method that fits the platform: macOS uses "brew install git" (or "xcode-select --install" if Homebrew is unavailable); Debian/Ubuntu uses "sudo apt-get update && sudo apt-get install -y git"; Fedora/RHEL uses "sudo dnf install -y git"; Arch uses "sudo pacman -S --noconfirm git"; Windows uses "winget install --id Git.Git -e" or "choco install git -y". After installing, re-verify with git --version before continuing.';
 export function buildInitGuide(appName, dir) {
     return {
         context: 'Created a Runwork app -- a full-stack Cloudflare Workers application with built-in support for persistent data (entities), background jobs (schedules), multi-step durable processes (workflows), AI agents, public APIs, and third-party integrations. The app runs in a sandbox during development and deploys to Cloudflare Workers for production.',
@@ -52,7 +58,7 @@ export function buildCloneGuide(appName, dir) {
             'Edit files for your needs',
             'runwork deploy  # deploy to production when ready',
         ],
-        tips: COMMON_TIPS,
+        tips: [SYSTEM_DEPENDENCIES_NOTE, ...COMMON_TIPS],
         learnMore: 'Read CLAUDE.md in the app directory for complete framework documentation.',
     };
 }
@@ -65,7 +71,8 @@ export function buildDevSessionGuide() {
             'Run runwork deploy in another terminal when ready for production',
         ],
         tips: [
-            'You do NOT need git commands. The dev server handles all file syncing.',
+            SYSTEM_DEPENDENCIES_NOTE,
+            'You in normal cases do NOT need to run git commands manually. The dev server handles all file syncing (it shells out to the system git binary, which must be installed).',
             'If the preview seems stuck, try runwork dev again to restart the session.',
         ],
     };

package/dist/utils/format-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Render an unknown thrown value as a single human-readable line. Tailored
+ * for `execFileSync` failures (which carry stderr/stdout buffers, an `errno`
+ * code, and a `message` like "Command failed: git ...") so the most useful
+ * piece of information surfaces first.
+ *
+ * Used by command entry points that have a `stdio: 'pipe'` git invocation
+ * to keep the diagnostic from being silently dropped.
+ */
+export declare function formatError(err: unknown): string;

package/dist/utils/format-error.js

@@ -0,0 +1,38 @@
+/**
+ * Render an unknown thrown value as a single human-readable line. Tailored
+ * for `execFileSync` failures (which carry stderr/stdout buffers, an `errno`
+ * code, and a `message` like "Command failed: git ...") so the most useful
+ * piece of information surfaces first.
+ *
+ * Used by command entry points that have a `stdio: 'pipe'` git invocation
+ * to keep the diagnostic from being silently dropped.
+ */
+export function formatError(err) {
+    if (!err)
+        return 'unknown error';
+    if (err instanceof Error) {
+        const obj = err;
+        const stderr = bufToStr(obj.stderr);
+        const stdout = bufToStr(obj.stdout);
+        const detail = stderr || stdout;
+        if (detail) {
+            // Common case for ENOENT: errno -> "git ENOENT: no such file or directory"
+            if (obj.code)
+                return `${obj.code}: ${detail}`;
+            return detail;
+        }
+        if (obj.code)
+            return `${obj.code}: ${obj.message}`;
+        return obj.message || String(err);
+    }
+    return String(err);
+}
+function bufToStr(value) {
+    if (!value)
+        return '';
+    if (typeof value === 'string')
+        return value.trim();
+    if (Buffer.isBuffer(value))
+        return value.toString('utf-8').trim();
+    return '';
+}

package/dist/utils/http.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Minimal `fetch`-like HTTP client built on `node:http` / `node:https`.
+ *
+ * Why this exists rather than calling `fetch` directly:
+ *  1) Single seam for diagnostics, retries, transport swaps, etc., without
+ *     touching every call site.
+ *  2) Opt-in `curl` transport (set `RUNWORK_HTTP_TRANSPORT=curl`) as a
+ *     break-glass: it shells out to the system `curl` binary so HTTP runs
+ *     in a subprocess, immune to any runtime regression in the Bun-compiled
+ *     binary. We've kept it after needing it once on an older Bun version.
+ *
+ * Default transport is `node:https` on every platform. Surface mirrors
+ * enough of the standard `Response` API for call sites to swap from
+ * `fetch(...)` to `httpFetch(...)` with no other change. Out of scope:
+ * streaming bodies, AbortController, ReadableStream request bodies, the
+ * `cache` option. This is a workaround layer, not a fetch polyfill.
+ */
+export interface HttpRequestInit {
+    method?: string;
+    headers?: Record<string, string | undefined> | Headers;
+    body?: string | Uint8Array | ArrayBuffer | Buffer | null;
+    /** Accepted for compatibility with `fetch(..., { cache: 'no-store' })`; ignored. */
+    cache?: string;
+    /** Accepted for compatibility; ignored (no AbortController support yet). */
+    signal?: AbortSignal;
+}
+export interface HttpResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: Headers;
+    readonly url: string;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Available HTTP transports. `node` is the default everywhere. `curl` is an
+ * opt-in escape hatch (set the `RUNWORK_HTTP_TRANSPORT=curl` env var) that
+ * shells out to `curl.exe` / `curl` for each request, sidestepping the
+ * runtime's native HTTP stack entirely. We keep it around as break-glass
+ * for any future Bun runtime regression on Windows; see file header.
+ */
+export type HttpTransport = 'auto' | 'node' | 'curl';
+export declare function __setTransportForTests(t: HttpTransport): void;
+export declare function httpFetch(url: string, init?: HttpRequestInit): Promise<HttpResponse>;