@modwrench/core 0.0.1

package/dist/auth.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Token shape persisted in the OS keychain after an OAuth flow.
+ * Stored as a JSON-stringified string under one keychain entry per service.
+ */
+export type StoredToken = {
+    access_token: string;
+    refresh_token?: string;
+    expires_at: number | null;
+    saved_at: number;
+};
+type KeychainStatus = "unknown" | "available" | "unavailable";
+/**
+ * Public status of the OS keychain integration on this system. Useful for
+ * tools that want to surface a clearer error or recommend the env-var path
+ * proactively.
+ */
+export declare function getKeychainStatus(): KeychainStatus;
+export declare function getStoredToken(name: string): StoredToken | null;
+export declare function setStoredToken(name: string, token: StoredToken): void;
+export declare function deleteStoredToken(name: string): boolean;
+export type Credential = {
+    source: "keychain";
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number | null;
+} | {
+    source: "env";
+    apiKey: string;
+};
+/**
+ * Resolve a credential by trying the OS keychain first, then an env var, then
+ * failing with a hint that points the user at `auth login`. The shape of the
+ * returned credential differs by source — callers should branch on `source`
+ * to decide which auth header (Bearer vs platform-specific) to send.
+ *
+ * If the keychain is unavailable (Steam Deck Game Mode, headless Linux, etc.)
+ * the thrown error explicitly says so rather than just reporting "no credential
+ * found" — which helps users fix the actual problem.
+ */
+export declare function loadCredential(opts: {
+    service: string;
+    envVar: string;
+    authHint: string;
+}): Credential;
+export {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAQF,KAAK,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;AAI9D;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AA8CD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAc/D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAkBrE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAavD;AAMD,MAAM,MAAM,UAAU,GAClB;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GACD;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,UAAU,CAyBb"}

package/dist/auth.js

@@ -0,0 +1,143 @@
+import { Entry } from "@napi-rs/keyring";
+// ─── Keychain storage ─────────────────────────────────────────────────────────
+// Tokens land in the OS-native secrets store: Windows Credential Manager,
+// macOS Keychain, or Linux libsecret. Service identifiers are prefixed with
+// "modwrench-" so a user inspecting their keychain sees a recognizable owner.
+//
+// On Linux specifically — and especially on Steam Deck Game Mode or headless
+// installs — libsecret / D-Bus may not be available. We detect that case and
+// surface a clear error message instead of silently sending the user to env
+// vars without explanation.
+const KEYCHAIN_ACCOUNT = "default";
+function service(name) {
+    return `modwrench-${name}`;
+}
+let keychainStatus = "unknown";
+let unavailableWarningEmitted = false;
+/**
+ * Public status of the OS keychain integration on this system. Useful for
+ * tools that want to surface a clearer error or recommend the env-var path
+ * proactively.
+ */
+export function getKeychainStatus() {
+    return keychainStatus;
+}
+/**
+ * Classify a keychain error as either "no entry exists" (the keychain works,
+ * we just haven't stored anything yet) or "unavailable" (the keychain service
+ * itself can't be reached). The distinction matters because the first case
+ * is normal and the second case usually means the user is on Steam Deck Game
+ * Mode, a headless Linux box, a container, or otherwise lacks libsecret.
+ */
+function classifyKeychainError(err) {
+    const msg = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
+    if (msg.includes("d-bus") ||
+        msg.includes("dbus") ||
+        msg.includes("libsecret") ||
+        msg.includes("schema") ||
+        msg.includes("no such file") ||
+        msg.includes("could not connect") ||
+        msg.includes("not running") ||
+        msg.includes("session bus")) {
+        return "unavailable";
+    }
+    return "no-entry";
+}
+function emitUnavailableWarningOnce(err) {
+    if (unavailableWarningEmitted)
+        return;
+    unavailableWarningEmitted = true;
+    // Write directly to stderr — avoid importing log() from index.ts which would
+    // create a circular dependency back to this module.
+    process.stderr.write(JSON.stringify({
+        ts: new Date().toISOString(),
+        level: "warn",
+        msg: "OS keychain unavailable on this system; falling back to env vars",
+        hint: "Common on Steam Deck Game Mode, headless Linux, or systems without " +
+            "libsecret/D-Bus. Set the platform's API_KEY env var in your .env to " +
+            "use the legacy auth path instead.",
+        error: err instanceof Error ? err.message : String(err),
+    }) + "\n");
+}
+export function getStoredToken(name) {
+    try {
+        const entry = new Entry(service(name), KEYCHAIN_ACCOUNT);
+        const raw = entry.getPassword();
+        keychainStatus = "available";
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (classifyKeychainError(err) === "unavailable") {
+            keychainStatus = "unavailable";
+            emitUnavailableWarningOnce(err);
+        }
+        return null;
+    }
+}
+export function setStoredToken(name, token) {
+    try {
+        const entry = new Entry(service(name), KEYCHAIN_ACCOUNT);
+        entry.setPassword(JSON.stringify(token));
+        keychainStatus = "available";
+    }
+    catch (err) {
+        if (classifyKeychainError(err) === "unavailable") {
+            keychainStatus = "unavailable";
+            throw new Error(`[modwrench/core] Cannot save credential: OS keychain unavailable. ` +
+                `This is common on Steam Deck Game Mode, headless Linux, or systems ` +
+                `without libsecret/D-Bus. Use the legacy API-key path instead — set ` +
+                `the platform's API_KEY env var in your .env. ` +
+                `Original error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        throw err;
+    }
+}
+export function deleteStoredToken(name) {
+    try {
+        const entry = new Entry(service(name), KEYCHAIN_ACCOUNT);
+        const removed = entry.deletePassword();
+        keychainStatus = "available";
+        return removed;
+    }
+    catch (err) {
+        if (classifyKeychainError(err) === "unavailable") {
+            keychainStatus = "unavailable";
+            emitUnavailableWarningOnce(err);
+        }
+        return false;
+    }
+}
+/**
+ * Resolve a credential by trying the OS keychain first, then an env var, then
+ * failing with a hint that points the user at `auth login`. The shape of the
+ * returned credential differs by source — callers should branch on `source`
+ * to decide which auth header (Bearer vs platform-specific) to send.
+ *
+ * If the keychain is unavailable (Steam Deck Game Mode, headless Linux, etc.)
+ * the thrown error explicitly says so rather than just reporting "no credential
+ * found" — which helps users fix the actual problem.
+ */
+export function loadCredential(opts) {
+    const stored = getStoredToken(opts.service);
+    if (stored && stored.access_token) {
+        return {
+            source: "keychain",
+            accessToken: stored.access_token,
+            refreshToken: stored.refresh_token,
+            expiresAt: stored.expires_at,
+        };
+    }
+    const env = process.env[opts.envVar];
+    if (env && env.trim() !== "") {
+        return { source: "env", apiKey: env };
+    }
+    const keychainNote = keychainStatus === "unavailable"
+        ? "OS keychain is unavailable on this system (likely libsecret/D-Bus missing — common on Steam Deck Game Mode or headless Linux). "
+        : "Tried OS keychain and ";
+    throw new Error(`[modwrench/core] No credential found for "${opts.service}". ` +
+        `${keychainNote}env var ${opts.envVar} is not set. ` +
+        opts.authHint);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -0,0 +1,55 @@
+export type RetryConfig = {
+    /** Total request attempts (1 = no retry). Default 3. */
+    maxAttempts?: number;
+    /** First backoff delay in ms when no Retry-After header is present. Default 250. */
+    initialDelayMs?: number;
+    /** Upper bound for backoff in ms (excluding server-supplied Retry-After). Default 8000. */
+    maxDelayMs?: number;
+};
+export type HttpClientOptions = {
+    /** Required. Used as the base for relative paths in request(). */
+    baseUrl: string;
+    /** Required. Set the User-Agent string for every outbound request. */
+    userAgent: string;
+    /**
+     * Called per request. Return headers like `{ Authorization: "Bearer ..." }`
+     * or `{ apikey: "..." }`. Return an empty object if no auth is required
+     * (e.g. Thunderstore reads).
+     */
+    authHeaders?: () => Record<string, string>;
+    /** Max concurrent in-flight requests. Default 4. */
+    concurrencyLimit?: number;
+    /** Tuning for retries. */
+    retry?: RetryConfig;
+    /** Optional default headers attached to every request (besides UA + auth). */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Optional override for the error-code prefix in thrown ModWrenchErrors.
+     * Defaults to "http". Set to e.g. "nexus" so callers see codes like
+     * "nexus_http_error" rather than "http_error".
+     */
+    errorCodePrefix?: string;
+};
+export type RequestInit = {
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /**
+     * Query string parameters. Undefined/null/empty values are dropped (so
+     * platforms can pass optional zod-defaulted args directly).
+     */
+    query?: Record<string, string | number | boolean | undefined | null>;
+    headers?: Record<string, string>;
+    body?: string;
+};
+export type HttpClient = {
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+    /** Number of requests currently waiting on the concurrency gate. */
+    inFlight(): number;
+};
+/**
+ * Parse a Retry-After header value. Per RFC 9110 §10.2.3 the value is either
+ * an integer number of seconds or an HTTP-date. Returns delay in ms, or null
+ * if the value couldn't be parsed (caller falls back to its own backoff).
+ */
+export declare function parseRetryAfter(value: string | null): number | null;
+export declare function createHttpClient(opts: HttpClientOptions): HttpClient;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,WAAW,GAAG;IACxB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzD,oEAAoE;IACpE,QAAQ,IAAI,MAAM,CAAC;CACpB,CAAC;AAqCF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAanE;AAwDD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CA6GpE"}

package/dist/http.js

@@ -0,0 +1,211 @@
+// Shared HTTP client for every MCPwrench platform package. Centralizes the
+// concerns that each platform shouldn't re-implement individually:
+//
+//   - 429 handling with Retry-After parsing (seconds OR HTTP date)
+//   - Exponential backoff on transient 5xx errors
+//   - Per-client concurrency cap so we never hammer a platform with parallel
+//     requests
+//   - User-Agent injection
+//   - Caller-supplied auth-header callback (keeps Bearer vs apikey routing
+//     decisions in the platform package, not in core)
+//   - Structured ModWrenchError on non-retryable failures
+//
+// Design rule: this client is the "polite citizen" tier. It reacts to 429s
+// and 5xxs but does NOT do proactive rate-limit window tracking via
+// X-RL-* response headers — different platforms expose different shapes for
+// those and that's a v2 concern. The current 429-reactive behavior is what
+// keeps us off blocklists.
+import { ModWrenchError } from "./index.js";
+// ─── Internals ─────────────────────────────────────────────────────────────
+/**
+ * Tiny async semaphore that caps concurrent operations. Each acquire() returns
+ * a release function; callers must always release in a finally block.
+ */
+function createGate(limit) {
+    let active = 0;
+    const waiters = [];
+    function acquire() {
+        return new Promise((resolve) => {
+            const tryProceed = () => {
+                if (active < limit) {
+                    active++;
+                    resolve(() => {
+                        active--;
+                        const next = waiters.shift();
+                        if (next)
+                            next();
+                    });
+                }
+                else {
+                    waiters.push(tryProceed);
+                }
+            };
+            tryProceed();
+        });
+    }
+    return { acquire, inFlight: () => active + waiters.length };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Parse a Retry-After header value. Per RFC 9110 §10.2.3 the value is either
+ * an integer number of seconds or an HTTP-date. Returns delay in ms, or null
+ * if the value couldn't be parsed (caller falls back to its own backoff).
+ */
+export function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    // Seconds (most common — Nexus, mod.io, GitHub all use this form).
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+        return Math.max(0, Number(trimmed) * 1000);
+    }
+    // HTTP-date — preserved per spec even if rarely seen on these APIs.
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - Date.now());
+    }
+    return null;
+}
+/** Exponential backoff with jitter, clamped to maxDelayMs. */
+function computeBackoff(attempt, initial, max) {
+    const expo = initial * Math.pow(2, attempt - 1);
+    const jittered = expo * (0.5 + Math.random());
+    return Math.min(jittered, max);
+}
+function buildUrl(baseUrl, path, query) {
+    const full = path.startsWith("http://") || path.startsWith("https://")
+        ? path
+        : `${baseUrl}${path}`;
+    if (!query || Object.keys(query).length === 0)
+        return full;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        params.append(k, String(v));
+    }
+    const qs = params.toString();
+    if (!qs)
+        return full;
+    return full.includes("?") ? `${full}&${qs}` : `${full}?${qs}`;
+}
+const SENSITIVE_QUERY_KEYS = new Set([
+    "access_token",
+    "api_key",
+    "apikey",
+    "authorization",
+    "client_secret",
+    "password",
+    "refresh_token",
+    "secret",
+    "token",
+]);
+function redactUrl(value) {
+    try {
+        const url = new URL(value);
+        for (const key of Array.from(url.searchParams.keys())) {
+            if (SENSITIVE_QUERY_KEYS.has(key.toLowerCase())) {
+                url.searchParams.set(key, "[redacted]");
+            }
+        }
+        return url.toString();
+    }
+    catch {
+        return value;
+    }
+}
+// ─── Public factory ────────────────────────────────────────────────────────
+export function createHttpClient(opts) {
+    const concurrency = opts.concurrencyLimit ?? 4;
+    const gate = createGate(concurrency);
+    const maxAttempts = opts.retry?.maxAttempts ?? 3;
+    const initialDelayMs = opts.retry?.initialDelayMs ?? 250;
+    const maxDelayMs = opts.retry?.maxDelayMs ?? 8000;
+    const errorPrefix = opts.errorCodePrefix ?? "http";
+    async function request(path, init = {}) {
+        const url = buildUrl(opts.baseUrl, path, init.query);
+        const safeUrl = redactUrl(url);
+        const method = init.method ?? "GET";
+        const auth = opts.authHeaders?.() ?? {};
+        const headers = {
+            "User-Agent": opts.userAgent,
+            Accept: "application/json",
+            ...(opts.defaultHeaders ?? {}),
+            ...auth,
+            ...(init.headers ?? {}),
+        };
+        const release = await gate.acquire();
+        try {
+            let lastError = null;
+            for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+                let response;
+                try {
+                    const fetchInit = { method, headers };
+                    if (init.body !== undefined)
+                        fetchInit.body = init.body;
+                    response = await fetch(url, fetchInit);
+                }
+                catch (err) {
+                    // Network-level failure (DNS, connection reset, etc.). Treat as
+                    // retryable up to maxAttempts.
+                    lastError = err;
+                    if (attempt < maxAttempts) {
+                        await sleep(computeBackoff(attempt, initialDelayMs, maxDelayMs));
+                        continue;
+                    }
+                    throw new ModWrenchError(`${errorPrefix}_network_error`, `Network error contacting ${safeUrl}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+                }
+                if (response.ok) {
+                    // Most platform APIs return JSON; some return empty body (204).
+                    // Treat empty as null so callers can branch on it cleanly.
+                    const ct = response.headers.get("content-type") ?? "";
+                    if (response.status === 204 || !ct.includes("json")) {
+                        // Best-effort: try JSON parse, fall back to raw text in result.
+                        const txt = await response.text().catch(() => "");
+                        if (!txt)
+                            return null;
+                        try {
+                            return JSON.parse(txt);
+                        }
+                        catch {
+                            return txt;
+                        }
+                    }
+                    return (await response.json());
+                }
+                // 429 → respect Retry-After if present, else exponential backoff.
+                if (response.status === 429 && attempt < maxAttempts) {
+                    const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+                    const delay = retryAfter ?? computeBackoff(attempt, initialDelayMs, maxDelayMs);
+                    await sleep(delay);
+                    continue;
+                }
+                // 5xx → retry with exponential backoff up to maxAttempts.
+                if (response.status >= 500 && attempt < maxAttempts) {
+                    await sleep(computeBackoff(attempt, initialDelayMs, maxDelayMs));
+                    continue;
+                }
+                // Non-retryable HTTP error. Read body for diagnostics and throw.
+                const body = await response.text().catch(() => "<no body>");
+                throw new ModWrenchError(`${errorPrefix}_http_error`, `HTTP ${response.status} for ${method} ${path}`, {
+                    status: response.status,
+                    meta: { body: body.slice(0, 500), url: safeUrl },
+                });
+            }
+            // Exhausted retries on the retryable path (429 / 5xx that never
+            // recovered). The last response's body isn't useful here so we keep
+            // it generic.
+            throw new ModWrenchError(`${errorPrefix}_retries_exhausted`, `Exhausted ${maxAttempts} attempts for ${method} ${path}`, { cause: lastError });
+        }
+        finally {
+            release();
+        }
+    }
+    return {
+        request,
+        inFlight: gate.inFlight,
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Retrieve a secret from environment variables.
+ * Throws a clear error if the secret is missing — fail fast, fail loud.
+ */
+export declare function getSecret(name: string): string;
+/**
+ * Retrieve an optional environment variable with a fallback default.
+ */
+export declare function getEnv(name: string, fallback: string): string;
+export declare function redactSensitiveText(value: string): string;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Minimal structured logger. Writes JSON to stderr so it never interferes
+ * with MCP stdio protocol traffic (which uses stdout).
+ */
+export declare function log(level: LogLevel, message: string, meta?: Record<string, unknown>): void;
+export * from "./auth.js";
+export * from "./http.js";
+/**
+ * Error type used across ModWrench servers for predictable error envelopes.
+ */
+export declare class ModWrenchError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly meta?: Record<string, unknown>;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        meta?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwCA;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS9C;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG7D;AAmBD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAczD;AAID,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAW3D;;;GAGG;AACH,wBAAgB,GAAG,CACjB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CASN;AAID,cAAc,WAAW,CAAC;AAI1B,cAAc,WAAW,CAAC;AAI1B;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChC,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAG7C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQjF"}

package/dist/index.js

@@ -0,0 +1,122 @@
+import { config as loadDotenv } from "dotenv";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// ─── Locate the workspace root ────────────────────────────────────────────────
+// Walk up from this file's location until we find a package.json that declares
+// "workspaces" — that's the monorepo root, regardless of where the process was
+// launched from. Falls back to process.cwd() if no workspace marker is found
+// (which lets the core package work fine even outside a monorepo).
+function findWorkspaceRoot(startDir) {
+    let current = startDir;
+    // Safety bound: don't walk forever even on weird filesystems.
+    for (let i = 0; i < 20; i++) {
+        const pkgPath = resolve(current, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (pkg && Array.isArray(pkg.workspaces)) {
+                    return current;
+                }
+            }
+            catch {
+                // Ignore malformed package.json and keep walking.
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break; // hit filesystem root
+        current = parent;
+    }
+    return startDir;
+}
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_ROOT = findWorkspaceRoot(HERE);
+loadDotenv({ path: resolve(WORKSPACE_ROOT, ".env") });
+// ─── Secret & env helpers ─────────────────────────────────────────────────────
+/**
+ * Retrieve a secret from environment variables.
+ * Throws a clear error if the secret is missing — fail fast, fail loud.
+ */
+export function getSecret(name) {
+    const value = process.env[name];
+    if (!value || value.trim() === "") {
+        throw new Error(`[modwrench/core] Missing required secret: ${name}. ` +
+            `Check your .env file at the workspace root (${WORKSPACE_ROOT}).`);
+    }
+    return value;
+}
+/**
+ * Retrieve an optional environment variable with a fallback default.
+ */
+export function getEnv(name, fallback) {
+    const value = process.env[name];
+    return value && value.trim() !== "" ? value : fallback;
+}
+const SENSITIVE_TEXT_KEYS = [
+    "access_token",
+    "api_key",
+    "apikey",
+    "authorization",
+    "client_secret",
+    "password",
+    "refresh_token",
+    "secret",
+    "security_code",
+    "token",
+];
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function redactSensitiveText(value) {
+    let redacted = value;
+    for (const key of SENSITIVE_TEXT_KEYS) {
+        const escaped = escapeRegExp(key);
+        redacted = redacted.replace(new RegExp(`("${escaped}"\\s*:\\s*")([^"]*)(")`, "gi"), "$1[redacted]$3");
+        redacted = redacted.replace(new RegExp(`(\\b${escaped}\\b\\s*[=:]\\s*)([^&\\s"']+)`, "gi"), "$1[redacted]");
+    }
+    return redacted;
+}
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const currentLevel = getEnv("LOG_LEVEL", "info") ?? "info";
+/**
+ * Minimal structured logger. Writes JSON to stderr so it never interferes
+ * with MCP stdio protocol traffic (which uses stdout).
+ */
+export function log(level, message, meta) {
+    if (LEVEL_RANK[level] < LEVEL_RANK[currentLevel])
+        return;
+    const entry = {
+        ts: new Date().toISOString(),
+        level,
+        msg: message,
+        ...(meta ?? {}),
+    };
+    process.stderr.write(JSON.stringify(entry) + "\n");
+}
+// ─── Auth & keychain ──────────────────────────────────────────────────────────
+export * from "./auth.js";
+// ─── Shared HTTP client ───────────────────────────────────────────────────────
+export * from "./http.js";
+// ─── Error type ───────────────────────────────────────────────────────────────
+/**
+ * Error type used across ModWrench servers for predictable error envelopes.
+ */
+export class ModWrenchError extends Error {
+    code;
+    status;
+    meta;
+    constructor(code, message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = "ModWrenchError";
+        this.code = code;
+        this.status = options?.status;
+        this.meta = options?.meta;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@modwrench/core",
+  "version": "0.0.1",
+  "description": "Shared core library for ModWrench servers — auth, secrets, logging, errors.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/171county/modwrench.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/171county/modwrench#readme",
+  "bugs": {
+    "url": "https://github.com/171county/modwrench/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.1.7",
+    "dotenv": "^16.4.5"
+  }
+}