@pugi/cli 0.1.0-beta.96 → 0.1.0-beta.98

package/dist/tools/http-request.js

@@ -0,0 +1,336 @@
+/**
+ * http_request - Phase 1 CRUD-smoke primitive (PUGI Phase 1).
+ *
+ * Generic HTTP request tool the model uses to verify a freshly-spun
+ * service end-to-end. Distinct from `web_fetch`:
+ *   - `web_fetch` is an opt-in marketing-grade content fetch (always
+ *     GET, response folded to Markdown, sentinel wrap, SSRF guard
+ *     blocks loopback / RFC1918).
+ *   - `http_request` is a *development-evidence* primitive: any verb,
+ *     any localhost URL, JSON-aware body+response. The default
+ *     allow-list permits localhost / 127.0.0.1 / ::1 so the model can
+ *     drive a CRUD smoke against a server it just started via
+ *     `server_start`; non-loopback hosts require an explicit
+ *     `allowExternal` opt-in.
+ *
+ * Body is serialised to JSON when a plain object is supplied. Headers
+ * are merged on top of a small default set (Accept: application/json,
+ * Content-Type when body is JSON). Response body is capped at 64 KB to
+ * keep the envelope sized; when the response content-type matches
+ * `application/json` the dispatcher attempts a parse and surfaces
+ * `json` alongside `body`.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { isIP } from 'node:net';
+export const HTTP_REQUEST_INVALID_ARGS = 'HTTP_REQUEST_INVALID_ARGS';
+export const HTTP_REQUEST_BODY_CAP_BYTES = 64 * 1024;
+export const HTTP_REQUEST_DEFAULT_TIMEOUT_MS = 10_000;
+export const HTTP_REQUEST_MAX_TIMEOUT_MS = 60_000;
+const ALLOWED_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+/**
+ * Validate raw arguments. Returns the typed payload on success or a
+ * sentinel string on failure (sleep/brief convention).
+ */
+export function parseHttpRequestArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${HTTP_REQUEST_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const method = obj['method'];
+    const url = obj['url'];
+    if (typeof method !== 'string' || !ALLOWED_METHODS.has(method.toUpperCase())) {
+        return `${HTTP_REQUEST_INVALID_ARGS}: method must be one of ${Array.from(ALLOWED_METHODS).join(', ')}`;
+    }
+    if (typeof url !== 'string' || url.trim() === '') {
+        return `${HTTP_REQUEST_INVALID_ARGS}: url must be a non-empty string`;
+    }
+    const body = obj['body'];
+    if (body !== undefined && body !== null) {
+        if (typeof body !== 'string' &&
+            !(typeof body === 'object')) {
+            return `${HTTP_REQUEST_INVALID_ARGS}: body must be a string or a JSON object/array`;
+        }
+    }
+    const headers = obj['headers'];
+    if (headers !== undefined) {
+        if (typeof headers !== 'object' || headers === null || Array.isArray(headers)) {
+            return `${HTTP_REQUEST_INVALID_ARGS}: headers must be a JSON object of string values`;
+        }
+        for (const [k, v] of Object.entries(headers)) {
+            if (typeof v !== 'string') {
+                return `${HTTP_REQUEST_INVALID_ARGS}: headers["${k}"] must be a string`;
+            }
+        }
+    }
+    const timeoutMs = obj['timeoutMs'];
+    if (timeoutMs !== undefined) {
+        if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return `${HTTP_REQUEST_INVALID_ARGS}: timeoutMs must be a positive number when provided`;
+        }
+    }
+    const allowExternal = obj['allowExternal'];
+    if (allowExternal !== undefined && typeof allowExternal !== 'boolean') {
+        return `${HTTP_REQUEST_INVALID_ARGS}: allowExternal must be a boolean when provided`;
+    }
+    const result = {
+        method: method.toUpperCase(),
+        url,
+        ...(body !== undefined && body !== null
+            ? { body: body }
+            : {}),
+        ...(headers !== undefined ? { headers: headers } : {}),
+        ...(typeof timeoutMs === 'number' ? { timeoutMs } : {}),
+        ...(typeof allowExternal === 'boolean' ? { allowExternal } : {}),
+    };
+    return result;
+}
+function clampTimeout(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return HTTP_REQUEST_DEFAULT_TIMEOUT_MS;
+    }
+    return Math.min(value, HTTP_REQUEST_MAX_TIMEOUT_MS);
+}
+/**
+ * Decide whether the target host counts as loopback. Accept the
+ * familiar shorthand (`localhost`, `127.0.0.1`, `::1`) plus the
+ * full 127.0.0.0/8 IPv4 range so a server bound to e.g. `127.0.0.5`
+ * still passes the gate.
+ */
+function isLoopbackHost(host) {
+    const lower = host.toLowerCase();
+    if (lower === 'localhost' ||
+        lower === '127.0.0.1' ||
+        lower === '::1' ||
+        lower === '[::1]' ||
+        // /triple-review P1 (Claude reviewer): IPv4-mapped
+        // IPv6 (`::ffff:127.0.0.1`) reaches loopback at the OS level.
+        // Recognize so a model that emits the IPv6 form is gated as
+        // loopback (rather than blocked as external — safer to allow
+        // explicitly recognised loopback and reject everything else).
+        lower === '::ffff:127.0.0.1' ||
+        lower.startsWith('::ffff:127.')) {
+        return true;
+    }
+    if (isIP(lower) === 4 && lower.startsWith('127.')) {
+        return true;
+    }
+    // /triple-review P1: `0.0.0.0` resolves к localhost for outbound on
+    // Linux and is reachable from inside the host. Treat as loopback so
+    // a server bound к `0.0.0.0` is callable from the dispatcher без
+    // requiring `allowExternal`. The risk surface is identical к
+    // `127.0.0.0/8` — anything reachable via `0.0.0.0` is also reachable
+    // via `127.0.0.1` on the same host.
+    if (lower === '0.0.0.0') {
+        return true;
+    }
+    return false;
+}
+function headersToObject(h) {
+    const out = {};
+    h.forEach((value, key) => {
+        out[key.toLowerCase()] = value;
+    });
+    return out;
+}
+/**
+ * Dispatch entry. Pure async - no shell, no filesystem. Loopback URLs
+ * always pass; external URLs require `allowExternal: true` so the
+ * default posture stays private.
+ */
+export async function dispatchHttpRequest(ctx, raw) {
+    const parsed = parseHttpRequestArgs(raw);
+    if (typeof parsed === 'string')
+        return parsed;
+    const args = parsed;
+    const now = ctx.now ?? (() => Date.now());
+    const fetchImpl = ctx.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: 'no_fetch_available',
+        };
+        return JSON.stringify(result);
+    }
+    // URL parse + loopback gate.
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(args.url);
+    }
+    catch (error) {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: `invalid_url: ${error.message}`,
+        };
+        return JSON.stringify(result);
+    }
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: `unsupported_protocol: ${parsedUrl.protocol}`,
+        };
+        return JSON.stringify(result);
+    }
+    const host = parsedUrl.hostname;
+    const loopback = isLoopbackHost(host);
+    if (!loopback && args.allowExternal !== true) {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: `external_host_blocked: ${host} (set allowExternal: true to permit)`,
+        };
+        return JSON.stringify(result);
+    }
+    // Header + body normalisation. The default Accept header pushes
+    // servers that content-negotiate toward JSON so the response parse
+    // hits more often.
+    const defaultHeaders = {
+        accept: 'application/json,text/plain;q=0.9,*/*;q=0.5',
+    };
+    const merged = { ...defaultHeaders };
+    if (args.headers) {
+        for (const [k, v] of Object.entries(args.headers)) {
+            merged[k.toLowerCase()] = v;
+        }
+    }
+    let serialisedBody;
+    if (args.body !== undefined && args.body !== null) {
+        if (typeof args.body === 'string') {
+            serialisedBody = args.body;
+        }
+        else {
+            try {
+                serialisedBody = JSON.stringify(args.body);
+            }
+            catch (error) {
+                const result = {
+                    ok: false,
+                    status: 0,
+                    headers: {},
+                    body: '',
+                    durationMs: 0,
+                    error: `body_serialise_failed: ${error.message}`,
+                };
+                return JSON.stringify(result);
+            }
+            if (!('content-type' in merged)) {
+                merged['content-type'] = 'application/json';
+            }
+        }
+    }
+    const timeoutMs = clampTimeout(args.timeoutMs);
+    const start = now();
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const init = {
+            method: args.method,
+            headers: merged,
+            signal: ac.signal,
+            // /triple-review P1 (Claude reviewer): default `fetch`
+            // follows redirects to ANY target. A loopback service can return
+            // 30x with Location pointing к cloud metadata IPs (169.254.169.254,
+            // 100.64/10 ranges) or arbitrary external hosts, and `fetch` would
+            // chase the redirect and surface the body. SSRF bypass class.
+            // `redirect: 'manual'` stops the chase; the dispatcher returns the
+            // 30x status + Location header to the model so it can decide
+            // whether the redirect target is acceptable.
+            redirect: 'manual',
+            ...(serialisedBody !== undefined ? { body: serialisedBody } : {}),
+        };
+        const res = await fetchImpl(args.url, init);
+        const text = await res.text();
+        const truncated = text.length > HTTP_REQUEST_BODY_CAP_BYTES;
+        const body = truncated ? text.slice(0, HTTP_REQUEST_BODY_CAP_BYTES) : text;
+        const respHeaders = headersToObject(res.headers);
+        const contentType = respHeaders['content-type'] ?? '';
+        let json;
+        if (contentType.includes('application/json') && body.length > 0 && !truncated) {
+            try {
+                json = JSON.parse(body);
+            }
+            catch {
+                // Body claimed JSON but failed to parse - preserve raw text only.
+            }
+        }
+        const result = {
+            ok: res.status >= 200 && res.status < 300,
+            status: res.status,
+            headers: respHeaders,
+            body,
+            ...(json !== undefined ? { json } : {}),
+            durationMs: now() - start,
+            ...(truncated ? { truncated: true } : {}),
+        };
+        return JSON.stringify(result);
+    }
+    catch (error) {
+        const message = error.message;
+        const aborted = error.name === 'AbortError';
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: now() - start,
+            error: aborted ? `timeout_after_${timeoutMs}ms` : `request_failed: ${message}`,
+        };
+        return JSON.stringify(result);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const httpRequestJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['method', 'url'],
+    properties: {
+        method: {
+            type: 'string',
+            enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
+            description: 'HTTP verb. Uppercase preferred but the dispatcher accepts any case.',
+        },
+        url: {
+            type: 'string',
+            description: 'Fully-qualified http(s) URL. Loopback hosts always pass; external hosts require allowExternal: true.',
+        },
+        body: {
+            description: 'Request body. A string is sent verbatim; an object/array is JSON-serialised and Content-Type defaults to application/json.',
+            oneOf: [
+                { type: 'string' },
+                { type: 'object', additionalProperties: true },
+                { type: 'array' },
+            ],
+        },
+        headers: {
+            type: 'object',
+            description: 'Custom request headers. Lower-cased keys overwrite the dispatcher defaults.',
+            additionalProperties: { type: 'string' },
+        },
+        timeoutMs: {
+            type: 'number',
+            description: `Per-request timeout in ms. Default ${HTTP_REQUEST_DEFAULT_TIMEOUT_MS}, max ${HTTP_REQUEST_MAX_TIMEOUT_MS}.`,
+        },
+        allowExternal: {
+            type: 'boolean',
+            description: 'Opt-in flag for non-loopback hosts. Defaults to false so the dispatcher refuses external URLs without explicit consent.',
+        },
+    },
+};
+//# sourceMappingURL=http-request.js.map

package/dist/tools/registry.js

@@ -49,6 +49,14 @@ const registry = [
     { name: 'exit_worktree', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: false },
     { name: 'glob', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'grep', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    // Phase 1 runtime evidence pack (PUGI-291..295): http_request issues a
+    // single HTTP call, mostly against loopback URLs produced by
+    // `server_start`. permission = 'network' to share the same egress
+    // gate as web_fetch; risk = 'medium' because the dispatcher will
+    // accept arbitrary verbs (POST/PUT/DELETE) - destructive verbs only
+    // when the caller opts in by URL/body. concurrencySafe = true because
+    // every dispatch is a fresh fetch with no shared state.
+    { name: 'http_request', permission: 'network', risk: 'medium', concurrencySafe: true, m1: false },
     // : LSP read-only surface. Server runs locally, no Anvil
     // round-trip. Concurrency-safe because every operation reads
     // server state without mutating workspace files.
@@ -91,7 +99,19 @@ const registry = [
     { name: 'powershell', permission: 'bash', risk: 'high', concurrencySafe: false, m1: false },
     { name: 'question', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
     { name: 'read', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
-    { name: 'skill', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    // Phase 1 runtime evidence pack (PUGI-291..295): server_* family.
+    // server_start spawns a process under /bin/sh -c and persists pid +
+    // log path к .pugi/runs/<runId>/. permission = 'bash' shares the
+    // same destructive-classifier gate as the bash tool (the command
+    // ultimately runs in a real shell). risk = 'high' for start/stop
+    // (process lifecycle mutates the operator's machine) and 'low' for
+    // health/logs (read-only probes). concurrencySafe = false for
+    // start/stop because the pid registry is not transactional;
+    // health/logs are safe to dispatch in parallel.
+    { name: 'server_health', permission: 'network', risk: 'low', concurrencySafe: true, m1: false },
+    { name: 'server_logs', permission: 'read', risk: 'low', concurrencySafe: true, m1: false },
+    { name: 'server_start', permission: 'bash', risk: 'high', concurrencySafe: false, m1: false },
+    { name: 'server_stop', permission: 'bash', risk: 'high', concurrencySafe: false, m1: false },
     // Tool gap pack : wall-clock pause primitive. No
     // filesystem / network / shell side-effects. concurrencySafe = true
     // because every dispatch is a fresh setTimeout closure with no