@wacht/bench 0.1.6 → 0.1.7

package/dist/commands.js

@@ -16,7 +16,7 @@ import { completionScript } from './completion.js';
 import { configApply, configDiff, configPull, configSchemaCommand, printConfigTemplate, } from './config-workflow.js';
 import { clearDeployment, createDeploymentCommand, createProjectCommand, currentDeployment, selectDeployment, } from './deployment-context.js';
 import { initProject, initStarter } from './init.js';
-import { docsSearch } from './docs-search.js';
+import { docsGet, docsSearch } from './docs-search.js';
 import { envPull } from './env-pull.js';
 import { apiCommand, listProjects } from './machine-api.js';
 import { openApiCall, openApiDescribe, openApiList, openApiRefresh } from './openapi.js';
@@ -220,7 +220,9 @@ export async function runCli(args) {
         .action((options) => {
         printMcpConfig(options.client);
     });
-    const docs = program.command('docs').description('search and explore Wacht docs');
+    const docs = program
+        .command('docs')
+        .description('search and read Wacht docs from the terminal — no MCP required');
     docs
         .command('search <query...>')
         .description('full-text search Wacht docs and print matching pages')
@@ -235,6 +237,18 @@ export async function runCli(args) {
             json: options.json,
         });
     });
+    docs
+        .command('get <path>')
+        .description('print the full Markdown of a Wacht docs page (e.g. /sdks/nextjs/middleware)')
+        .option('--base-url <url>', 'docs base URL (default: https://wacht.dev/docs, or $WACHT_DOCS_URL)')
+        .option('--json', 'emit JSON ({ path, url, markdown }) instead of raw Markdown')
+        .action(async (docPath, options) => {
+        await docsGet(context(program), {
+            path: docPath,
+            baseUrl: options.baseUrl,
+            json: options.json,
+        });
+    });
     const env = program.command('env').description('manage deployment credentials and environment files');
     env
         .command('pull')

package/dist/docs-search.js

@@ -1,11 +1,12 @@
-import { field, log, printBannerFor, printError, printJson, section } from './ui.js';
+import { httpFetch } from './http.js';
+import { field, log, muted, printBannerFor, printError, printJson, section } from './ui.js';
 const DEFAULT_DOCS_URL = 'https://wacht.dev/docs';
 export async function docsSearch(ctx, options) {
     const baseUrl = (options.baseUrl ?? process.env.WACHT_DOCS_URL ?? DEFAULT_DOCS_URL).replace(/\/+$/, '');
     const endpoint = `${baseUrl}/api/search?query=${encodeURIComponent(options.query)}`;
     let response;
     try {
-        response = await fetch(endpoint, { headers: { Accept: 'application/json' } });
+        response = await httpFetch(endpoint, { headers: { Accept: 'application/json' } });
     }
     catch (error) {
         printError(error);
@@ -38,7 +39,7 @@ export async function docsSearch(ctx, options) {
     }
     const orderedPages = Array.from(pages.values());
     const sliced = options.limit ? orderedPages.slice(0, options.limit) : orderedPages;
-    if (options.json) {
+    if (ctx.json || options.json) {
         printJson({
             ok: true,
             query: options.query,
@@ -78,4 +79,68 @@ export async function docsSearch(ctx, options) {
         }
         log(ctx, '');
     }
+    if (!ctx.quiet) {
+        log(ctx, muted('Read a full page with `wacht docs get <path>` (e.g. `wacht docs get /sdks/nextjs/middleware`).'));
+    }
+}
+/**
+ * Normalize whatever the caller passes (a docs path, a `/docs/...` path, a full
+ * URL, or one that already ends in `content.md`) down to the page's slug segments.
+ */
+function normalizeDocPath(input) {
+    let value = input.trim();
+    if (/^https?:\/\//i.test(value)) {
+        try {
+            value = new URL(value).pathname;
+        }
+        catch {
+            // fall through and treat it as a plain path
+        }
+    }
+    value = value.replace(/^\/+/, '').replace(/\/+$/, '');
+    value = value.replace(/^docs\//, '');
+    // tolerate a pasted markdown URL: .../sdks/node/content.md → sdks/node
+    value = value.replace(/\/content\.md$/i, '').replace(/\.mdx?$/i, '');
+    return value;
+}
+export async function docsGet(ctx, options) {
+    const baseUrl = (options.baseUrl ?? process.env.WACHT_DOCS_URL ?? DEFAULT_DOCS_URL).replace(/\/+$/, '');
+    const slug = normalizeDocPath(options.path);
+    if (!slug) {
+        printError(new Error('Pass a docs path, for example `wacht docs get /sdks/nextjs/middleware`.'));
+        process.exitCode = 1;
+        return;
+    }
+    const docPath = `/${slug}`;
+    const url = `${baseUrl}/llms.mdx/docs/${slug}/content.md`;
+    let response;
+    try {
+        response = await httpFetch(url, { headers: { Accept: 'text/markdown' } });
+    }
+    catch (error) {
+        printError(error);
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 404) {
+        printError(new Error(`No docs page at ${docPath}. Run \`wacht docs search <terms>\` to find the right path.`));
+        process.exitCode = 1;
+        return;
+    }
+    if (!response.ok) {
+        printError(new Error(`docs get failed: ${response.status} ${response.statusText} (${url})`));
+        process.exitCode = 1;
+        return;
+    }
+    const markdown = (await response.text()).trim();
+    if (ctx.json || options.json) {
+        printJson({ ok: true, path: docPath, url, markdown });
+        return;
+    }
+    if (!ctx.quiet) {
+        log(ctx, muted(`# source: ${baseUrl}${docPath}`));
+        log(ctx, '');
+    }
+    // The page body is the deliverable here — print it raw so it's pipeable.
+    console.log(markdown);
 }

package/dist/http.js

@@ -0,0 +1,73 @@
+// Shared HTTP layer: every network call in the CLI goes through `httpFetch` so
+// no request can hang an agent loop forever, and transient blips on idempotent
+// reads retry instead of failing the whole command.
+const DEFAULT_TIMEOUT_MS = (() => {
+    const raw = Number(process.env.WACHT_HTTP_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : 20_000;
+})();
+const DEFAULT_RETRIES = 2;
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD']);
+export class HttpError extends Error {
+    url;
+    status;
+    constructor(message, url, status) {
+        super(message);
+        this.url = url;
+        this.status = status;
+        this.name = 'HttpError';
+    }
+}
+function methodOf(init) {
+    return (init.method ?? 'GET').toUpperCase();
+}
+function isRetryableStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * `fetch` with a hard timeout and bounded retries. Mutations (POST/PUT/PATCH/DELETE)
+ * are never retried automatically — only idempotent reads — so a flaky network can't
+ * double-apply a write. Non-retryable responses (including 4xx) are returned as-is so
+ * callers keep their own status handling.
+ */
+export async function httpFetch(url, init = {}, opts = {}) {
+    const target = String(url);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const idempotent = IDEMPOTENT_METHODS.has(methodOf(init));
+    const maxRetries = Math.max(0, opts.retries ?? (idempotent ? DEFAULT_RETRIES : 0));
+    for (let attempt = 0;; attempt += 1) {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const response = await fetch(url, { ...init, signal: controller.signal });
+            if (isRetryableStatus(response.status) && attempt < maxRetries) {
+                await delay(200 * (attempt + 1));
+                continue;
+            }
+            return response;
+        }
+        catch (error) {
+            // A timeout means we already waited the full budget — retrying just
+            // multiplies the wait, so fail fast and let the per-request timeout cap it.
+            // Connection errors (refused/reset/DNS) are cheap to retry and often transient.
+            if (!timedOut && attempt < maxRetries) {
+                await delay(200 * (attempt + 1));
+                continue;
+            }
+            if (timedOut) {
+                throw new HttpError(`request timed out after ${timeoutMs}ms: ${target}`, target);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new HttpError(`request failed: ${message} (${target})`, target);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/init.js

@@ -50,7 +50,7 @@ This project is configured for AI-assisted Wacht development.
 | Need | Source |
 | --- | --- |
 | Framework wiring patterns (provider, middleware, loaders) | Skills: \`${skills}\`. Always load before editing SDK code — never freelance the wiring. |
-| Endpoint contracts, request/response shapes, errors | Wacht Docs MCP at \`${MCP_URL}\`. Required before calling any Machine API operation by hand. |
+| Endpoint contracts, request/response shapes, errors | Wacht Docs MCP at \`${MCP_URL}\` — or, with no MCP, \`wacht docs search "<terms>"\` then \`wacht docs get <path>\`. Ground here before calling any Machine API operation by hand. |
 | Live deployment context (project id, deployment id, hosts) | \`wacht deployments current\` — re-run every time, never cache. |
 | Available CLI surface | \`wacht --help\` and \`wacht <command> --help\`. |
 | Any Machine API operation by name | \`wacht api ls --search <text>\` → \`wacht api describe <op>\` → \`wacht api call <op>\`. |
@@ -64,6 +64,7 @@ This project is configured for AI-assisted Wacht development.
 | Manage users | \`wacht users list\` · \`wacht users get <id>\` · \`wacht users create --field …\` |
 | Manage orgs / workspaces | \`wacht orgs list\` · \`wacht workspaces list --org <id>\` |
 | Pull / diff / apply config | \`wacht config pull\` · \`wacht config diff\` · \`wacht config apply --yes\` |
+| Read Wacht docs (no MCP needed) | \`wacht docs search "<terms>"\` · \`wacht docs get <path>\` |
 | Configure Docs MCP across clients | \`wacht mcp install\` (interactive picker) · \`wacht mcp list\` |
 
 ### Rules for agent loops

package/dist/machine-api.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { MACHINE_API_URL } from './config.js';
 import { readBenchContext } from './context-store.js';
+import { httpFetch } from './http.js';
 import { getValidAuth } from './oauth.js';
 import { promptChoice, promptOptionalList, promptText } from './prompts.js';
 import { field, log, printBannerFor, printJson, section } from './ui.js';
@@ -38,7 +39,7 @@ export async function machineRequest(pathname, options = {}) {
     const headers = new Headers(options.headers);
     headers.set('authorization', `Bearer ${auth.access_token}`);
     headers.set('accept', 'application/json');
-    const response = await fetch(url, {
+    const response = await httpFetch(url, {
         ...options,
         headers,
     });

package/dist/oauth.js

@@ -1,6 +1,7 @@
 import { openBrowser } from './browser.js';
 import { MACHINE_API_URL, OAUTH_AUTHORIZE_URL, OAUTH_CLIENT_ID, OAUTH_ISSUER, OAUTH_REVOCATION_URL, OAUTH_SCOPES, OAUTH_TOKEN_URL, REDIRECT_URI, } from './config.js';
 import { isOAuthTokenResponse } from './guards.js';
+import { httpFetch } from './http.js';
 import { startOAuthCallbackServer } from './oauth-callback.js';
 import { codeChallengeFor, randomToken } from './pkce.js';
 import { clearAuth, readAuth, writeAuth } from './auth-store.js';
@@ -174,7 +175,7 @@ export async function logout(ctx) {
     const auth = await readAuth();
     if (auth?.refresh_token) {
         try {
-            await fetch(OAUTH_REVOCATION_URL, {
+            await httpFetch(OAUTH_REVOCATION_URL, {
                 method: 'POST',
                 headers: {
                     'content-type': 'application/x-www-form-urlencoded',
@@ -184,7 +185,7 @@ export async function logout(ctx) {
                     token_type_hint: 'refresh_token',
                     client_id: OAUTH_CLIENT_ID,
                 }),
-            });
+            }, { timeoutMs: 5_000 });
         }
         catch {
             // Local logout should still succeed if the network is unavailable.

package/dist/openapi.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { AUTH_DIR, OPENAPI_CACHE_FILE, PLATFORM_OPENAPI_URL } from './config.js';
 import { readBenchContext } from './context-store.js';
+import { httpFetch } from './http.js';
 import { entries, requestBody, machineRequest } from './machine-api.js';
 import { validateBody } from './openapi-validate.js';
 import { field, log, printBannerFor, printJson, section, warning } from './ui.js';
@@ -34,7 +35,7 @@ async function readCache() {
     }
 }
 async function fetchSpec() {
-    const response = await fetch(PLATFORM_OPENAPI_URL);
+    const response = await httpFetch(PLATFORM_OPENAPI_URL);
     if (!response.ok) {
         throw new Error(`OpenAPI fetch failed: HTTP ${response.status}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wacht/bench",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "CLI for Wacht Bench, the AI development workbench for Wacht.",
   "type": "module",
   "bin": {