runwork 0.9.4 → 0.10.0

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>;

package/dist/utils/http.js

@@ -0,0 +1,421 @@
+/**
+ * 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.
+ */
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createBrotliDecompress, createGunzip, createInflate, createInflateRaw, } from 'node:zlib';
+const MAX_REDIRECTS = 10;
+let transportOverride = 'auto';
+export function __setTransportForTests(t) { transportOverride = t; }
+function pickTransport() {
+    if (transportOverride === 'curl')
+        return 'curl';
+    if (transportOverride === 'node')
+        return 'node';
+    const env = (process.env.RUNWORK_HTTP_TRANSPORT || '').toLowerCase().trim();
+    if (env === 'curl')
+        return 'curl';
+    return 'node';
+}
+export async function httpFetch(url, init = {}) {
+    const transport = pickTransport();
+    if (transport === 'curl')
+        return curlFetch(url, init);
+    return doRequest(url, init, 0);
+}
+async function doRequest(url, init, redirectCount) {
+    const parsed = new URL(url);
+    const isHttps = parsed.protocol === 'https:';
+    const isHttp = parsed.protocol === 'http:';
+    if (!isHttps && !isHttp) {
+        throw new Error(`Unsupported protocol "${parsed.protocol}" -- only http: and https: are supported.`);
+    }
+    const requestFn = isHttps ? httpsRequest : httpRequest;
+    const headers = normalizeHeaders(init.headers);
+    const method = (init.method || 'GET').toUpperCase();
+    const isBodylessMethod = method === 'GET' || method === 'HEAD';
+    const bodyBuffer = isBodylessMethod ? null : bodyToBuffer(init.body);
+    if (bodyBuffer && headers['content-length'] === undefined) {
+        headers['content-length'] = String(bodyBuffer.byteLength);
+    }
+    // Match `fetch`'s default of advertising compression support. We
+    // transparently decompress gzip/deflate/br responses below.
+    if (headers['accept-encoding'] === undefined) {
+        headers['accept-encoding'] = 'gzip, deflate, br';
+    }
+    const requestOptions = {
+        method,
+        headers,
+    };
+    return new Promise((resolve, reject) => {
+        const req = requestFn(url, requestOptions, (res) => {
+            const status = res.statusCode ?? 0;
+            // Follow redirects manually so behavior matches `fetch`. We wait for
+            // the previous response to fully drain before starting the recursive
+            // request: guarantees socket cleanup ordering and avoids leaking
+            // the previous request when the new one fails.
+            const location = res.headers.location;
+            if (status >= 300 && status < 400 && location && redirectCount < MAX_REDIRECTS) {
+                res.resume();
+                res.once('end', () => {
+                    let nextUrl;
+                    try {
+                        nextUrl = new URL(location, url).toString();
+                    }
+                    catch (err) {
+                        reject(err);
+                        return;
+                    }
+                    const shouldDowngradeToGet = status === 303 ||
+                        ((status === 301 || status === 302) && method !== 'GET' && method !== 'HEAD');
+                    const nextInit = shouldDowngradeToGet
+                        ? { ...init, method: 'GET', body: undefined }
+                        : init;
+                    doRequest(nextUrl, nextInit, redirectCount + 1).then(resolve, reject);
+                });
+                res.once('error', reject);
+                return;
+            }
+            // Decompress gzip / deflate / br transparently to match fetch.
+            const decoded = decompressedStream(res);
+            const chunks = [];
+            decoded.on('data', (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            decoded.on('end', () => {
+                const buffer = Buffer.concat(chunks);
+                // For HEAD responses there is no body; preserve the empty buffer.
+                resolve(buildResponse(url, res, status, buffer));
+            });
+            decoded.on('error', reject);
+            // Surface upstream socket errors too when we are reading through a
+            // decompressor (the transformed stream wouldn't otherwise see them).
+            if (decoded !== res) {
+                res.on('error', reject);
+            }
+        });
+        req.on('error', reject);
+        if (bodyBuffer)
+            req.write(bodyBuffer);
+        req.end();
+    });
+}
+function normalizeHeaders(input) {
+    const out = {};
+    if (!input)
+        return out;
+    if (input instanceof Headers) {
+        input.forEach((value, key) => {
+            out[key.toLowerCase()] = value;
+        });
+        return out;
+    }
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined || value === null)
+            continue;
+        out[key.toLowerCase()] = String(value);
+    }
+    return out;
+}
+function bodyToBuffer(body) {
+    if (body === undefined || body === null)
+        return null;
+    if (typeof body === 'string')
+        return Buffer.from(body, 'utf-8');
+    if (Buffer.isBuffer(body))
+        return body;
+    if (body instanceof Uint8Array)
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    if (body instanceof ArrayBuffer)
+        return Buffer.from(new Uint8Array(body));
+    throw new TypeError('Unsupported request body type');
+}
+function decompressedStream(res) {
+    // Per RFC 7230, Content-Encoding may be a comma-separated list of
+    // transformations applied in order. Unwrap them in reverse, but in
+    // practice servers send a single encoding so the simple cases dominate.
+    const raw = (res.headers['content-encoding'] || '').toString().toLowerCase().trim();
+    if (!raw || raw === 'identity')
+        return res;
+    const encodings = raw.split(',').map((s) => s.trim()).filter(Boolean).reverse();
+    let stream = res;
+    for (const enc of encodings) {
+        let decoder = null;
+        if (enc === 'gzip' || enc === 'x-gzip')
+            decoder = createGunzip();
+        else if (enc === 'br')
+            decoder = createBrotliDecompress();
+        else if (enc === 'deflate')
+            decoder = createInflate();
+        else if (enc === 'deflate-raw')
+            decoder = createInflateRaw();
+        else
+            continue; // unknown encoding -- pass bytes through
+        stream.pipe(decoder);
+        stream = decoder;
+    }
+    return stream;
+}
+function buildResponse(url, res, status, buffer) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(res.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                headers.append(name, v);
+        }
+        else {
+            headers.set(name, value);
+        }
+    }
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: res.statusMessage ?? '',
+        headers,
+        url,
+        async text() {
+            return buffer.toString('utf-8');
+        },
+        async json() {
+            const text = buffer.toString('utf-8');
+            return JSON.parse(text);
+        },
+        async arrayBuffer() {
+            // Slice the underlying buffer so the returned ArrayBuffer matches the
+            // exact byte range and is independent of Node's internal pool.
+            const copy = new Uint8Array(buffer.byteLength);
+            copy.set(buffer);
+            return copy.buffer;
+        },
+    };
+}
+// ────────────────────────────────────────────────────────────────────────
+// curl-based transport (Windows workaround)
+//
+// On Windows we spawn `curl.exe` for every HTTP call so we never touch
+// Bun's broken HTTP runtime in the standalone binary. The subprocess
+// approach trades a few tens of milliseconds of process-spawn overhead per
+// request for rock-solid reliability. Curl ships at
+// C:\Windows\System32\curl.exe on Windows 10+ since 2018.
+//
+// Layout:
+//   - body          → written by curl to a temp file (--output)
+//   - response hdrs → written by curl to a temp file (--dump-header)
+//   - status/url    → printed by curl to stdout via --write-out
+//
+// We never let body bytes share a stream with metadata, so binary
+// downloads (zip skeletons, presigned URL fetches) round-trip cleanly.
+// ────────────────────────────────────────────────────────────────────────
+async function curlFetch(url, init) {
+    return curlFetchOnce(url, init, 0);
+}
+async function curlFetchOnce(url, init, redirectCount) {
+    // Quick URL sanity check so we throw the same way the node:https path
+    // does for unsupported protocols, before paying the spawn cost.
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`Unsupported protocol "${parsed.protocol}" -- only http: and https: are supported.`);
+    }
+    const headers = normalizeHeaders(init.headers);
+    const method = (init.method || 'GET').toUpperCase();
+    const isBodyless = method === 'GET' || method === 'HEAD';
+    const bodyBuffer = isBodyless ? null : bodyToBuffer(init.body);
+    if (headers['accept-encoding'] === undefined) {
+        headers['accept-encoding'] = 'identity';
+    }
+    // Per-call temp directory keeps cleanup simple and concurrent calls from
+    // racing on shared filenames.
+    const tmp = mkdtempSync(join(tmpdir(), 'runwork-curl-'));
+    const bodyOutPath = join(tmp, 'body.bin');
+    const headerOutPath = join(tmp, 'headers.txt');
+    const args = [
+        '--silent',
+        '--show-error',
+        // We deliberately do NOT pass --location. curl's redirect-method
+        // semantics differ subtly from fetch's (notably curl can preserve
+        // POST across 303 in some versions despite the spec). We follow
+        // redirects ourselves below so behavior matches the node:https
+        // transport exactly.
+        '--output', bodyOutPath, // body to file (binary safe)
+        '--dump-header', headerOutPath, // response headers to file
+        '--write-out', '%{http_code}\n%{url_effective}\n',
+    ];
+    if (method === 'HEAD') {
+        // --head sends HEAD AND tells curl not to expect a body, otherwise
+        // curl hangs waiting for body bytes. The downside is that --head also
+        // writes the response headers into the --output body file -- we work
+        // around that below by ignoring the body buffer when method is HEAD.
+        args.push('--head');
+    }
+    else if (method !== 'GET') {
+        args.push('--request', method);
+    }
+    // Curl's default already follows fetch semantics on 301/302/303 (downgrade
+    // POST to GET). We do NOT pass --post30x because those flags violate that
+    // default and force POST to be preserved across redirects.
+    for (const [name, value] of Object.entries(headers)) {
+        args.push('--header', `${name}: ${value}`);
+    }
+    if (bodyBuffer) {
+        // Read request body from stdin so we don't have to write it to disk.
+        args.push('--data-binary', '@-');
+    }
+    args.push(url);
+    // Async spawn: spawnSync would block the event loop, which deadlocks
+    // unit tests (the test server lives in the same Node worker, can't
+    // service curl's connection while we're blocked). The async path is
+    // also strictly nicer for any future caller that wants to overlap
+    // requests.
+    const result = await new Promise((resolve) => {
+        const child = spawn('curl', args, { windowsHide: true });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on('data', (c) => stdoutChunks.push(c));
+        child.stderr.on('data', (c) => stderrChunks.push(c));
+        child.on('error', (err) => resolve({
+            status: -1,
+            stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+            stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+            error: err,
+        }));
+        child.on('close', (code) => resolve({
+            status: code ?? -1,
+            stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+            stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+        }));
+        if (bodyBuffer) {
+            child.stdin.write(bodyBuffer);
+        }
+        child.stdin.end();
+    });
+    if (result.error) {
+        safeRm(tmp);
+        throw result.error;
+    }
+    const stdoutLines = result.stdout.trim().split(/\r?\n/);
+    const statusLine = stdoutLines[0] || '0';
+    const finalUrl = stdoutLines[1] || url;
+    const status = Number.parseInt(statusLine, 10) || 0;
+    if (status === 0) {
+        // curl never received a response, or exited before writing the status.
+        const stderr = result.stderr.trim();
+        safeRm(tmp);
+        throw new Error(`curl failed (exit ${result.status}): ${stderr || 'no error output'}`);
+    }
+    let bodyBuf;
+    try {
+        bodyBuf = readFileSync(bodyOutPath);
+    }
+    catch {
+        bodyBuf = Buffer.alloc(0);
+    }
+    // For HEAD, --head causes curl to write the response status line + headers
+    // into the body output file (since there is no real body to write). Strip
+    // it so callers see an empty body, matching fetch's HEAD behavior.
+    if (method === 'HEAD') {
+        bodyBuf = Buffer.alloc(0);
+    }
+    let headerText = '';
+    try {
+        headerText = readFileSync(headerOutPath, 'utf-8');
+    }
+    catch {
+        // best-effort
+    }
+    safeRm(tmp);
+    // After redirects curl writes one header block per hop; the LAST block is
+    // the response we actually want to expose to the caller.
+    const blocks = headerText.split(/\r?\n\r?\n/).map((b) => b.trim()).filter(Boolean);
+    const finalBlock = blocks[blocks.length - 1] || '';
+    const finalLines = finalBlock.split(/\r?\n/);
+    // Pull statusText off the HTTP/x.y NNN <reason> status line if present.
+    let statusText = '';
+    if (finalLines.length > 0 && finalLines[0].startsWith('HTTP/')) {
+        const match = finalLines[0].match(/^HTTP\/\S+\s+\d+\s*(.*)$/);
+        if (match)
+            statusText = match[1].trim();
+    }
+    const responseHeaders = new Headers();
+    for (const line of finalLines) {
+        if (line.startsWith('HTTP/'))
+            continue;
+        const colon = line.indexOf(':');
+        if (colon < 0)
+            continue;
+        const name = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (!name)
+            continue;
+        responseHeaders.append(name, value);
+    }
+    // Manual redirect handling so curl and node:https behave identically.
+    // 303 always downgrades to GET; 301/302 downgrade non-GET/HEAD to GET;
+    // 307/308 preserve method and body.
+    const location = responseHeaders.get('location');
+    if (status >= 300 && status < 400 && location && redirectCount < MAX_REDIRECTS) {
+        let nextUrl;
+        try {
+            nextUrl = new URL(location, url).toString();
+        }
+        catch (err) {
+            throw err;
+        }
+        const shouldDowngradeToGet = status === 303 ||
+            ((status === 301 || status === 302) && method !== 'GET' && method !== 'HEAD');
+        const nextInit = shouldDowngradeToGet
+            ? { ...init, method: 'GET', body: undefined }
+            : init;
+        return curlFetchOnce(nextUrl, nextInit, redirectCount + 1);
+    }
+    // Mirror the node-path warning on unexpected encoding so the diagnostics
+    // are consistent across platforms.
+    const enc = (responseHeaders.get('content-encoding') || '').toLowerCase().trim();
+    if (enc && enc !== 'identity') {
+        try {
+            process.stderr.write(`[http] warning: server returned Content-Encoding: ${enc} despite Accept-Encoding: identity; ` +
+                `body returned as raw bytes (${url}).\n`);
+        }
+        catch { /* ignore */ }
+    }
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText,
+        headers: responseHeaders,
+        url: finalUrl,
+        async text() { return bodyBuf.toString('utf-8'); },
+        async json() { return JSON.parse(bodyBuf.toString('utf-8')); },
+        async arrayBuffer() {
+            const copy = new Uint8Array(bodyBuf.byteLength);
+            copy.set(bodyBuf);
+            return copy.buffer;
+        },
+    };
+}
+function safeRm(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runwork",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "CLI for Runwork: develop, preview, and deploy Runwork apps from your local machine.",
   "license": "UNLICENSED",
   "author": "Runwork <info@runwork.ai> (https://www.runwork.ai)",
@@ -56,7 +56,8 @@
     "vitest": "^3.2.0"
   },
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.5.0",
+    "bun": ">=1.3.13"
   },
   "files": [
     "dist/**/*.js",