@vucinatim/agentic-devtools 0.1.0

package/src/core/config-store.mjs

@@ -0,0 +1,106 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const CONFIG_ROOT = path.join(os.homedir(), ".config", "agentic-devtools");
+
+export const isTruthyEnv = (value) =>
+  typeof value === "string" &&
+  ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+
+export const pickString = (value, fallback = undefined) => {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  return fallback;
+};
+
+export const resolveConfigPath = ({ env, envVar, fileName }) => {
+  const override = pickString(env?.[envVar]);
+  return override ? path.resolve(override) : path.join(CONFIG_ROOT, fileName);
+};
+
+export const readJsonConfig = async (filePath) => {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+};
+
+export const readJsonConfigSync = (filePath) => {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  return JSON.parse(readFileSync(filePath, "utf8"));
+};
+
+export const writeJsonConfig = async (filePath, config) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`);
+  await chmod(filePath, 0o600).catch(() => {});
+};
+
+export const removeJsonConfig = async (filePath) => {
+  await rm(filePath, { force: true });
+};
+
+export const escapeHtml = (value) =>
+  String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+
+export const parseFormBody = async (request) => {
+  const chunks = [];
+
+  for await (const chunk of request) {
+    chunks.push(chunk);
+  }
+
+  const body = Buffer.concat(chunks).toString("utf8");
+  const params = new URLSearchParams(body);
+
+  return Object.fromEntries(params.entries());
+};
+
+/* v8 ignore start */
+export const openBrowser = async (url, { skipEnvVar } = {}) => {
+  if (skipEnvVar && isTruthyEnv(process.env[skipEnvVar])) {
+    return;
+  }
+
+  await new Promise((resolve, reject) => {
+    const platform = process.platform;
+    let command;
+    let args;
+
+    if (platform === "darwin") {
+      command = "open";
+      args = [url];
+    } else if (platform === "win32") {
+      command = "cmd";
+      args = ["/c", "start", "", url];
+    } else {
+      command = "xdg-open";
+      args = [url];
+    }
+
+    execFile(command, args, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+};
+/* v8 ignore stop */

package/src/core/result.mjs

@@ -0,0 +1,13 @@
+export const createJsonResult = (value) => ({
+  content: [
+    {
+      type: "text",
+      text: JSON.stringify(value, null, 2),
+    },
+  ],
+  structuredContent: value,
+});
+
+export const printJson = (value) => {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+};

package/src/core/tool-registry.mjs

@@ -0,0 +1,29 @@
+export const tools = {
+  namecheap: {
+    name: "namecheap",
+    description: "Inspect and manage Namecheap domains and DNS.",
+    mcpModule: "../tools/namecheap/mcp.mjs",
+  },
+  railway: {
+    name: "railway",
+    description: "Inspect Railway projects, environments, and deployments.",
+    mcpModule: "../tools/railway/mcp.mjs",
+  },
+  npm: {
+    name: "npm",
+    description: "Inspect npm packages, auth, tokens, and publishing setup.",
+    mcpModule: "../tools/npm/mcp.mjs",
+  },
+};
+
+export const listTools = () => Object.values(tools);
+
+export const getTool = (name) => {
+  const tool = tools[name];
+  if (!tool) {
+    throw new Error(
+      `Unknown tool "${name}". Available tools: ${Object.keys(tools).join(", ")}`,
+    );
+  }
+  return tool;
+};

package/src/index.mjs

@@ -0,0 +1,47 @@
+export {
+  AUTH_CONFIG_PATH,
+  CONFIG_ROOT,
+  clearStoredAuthConfig,
+  connectNamecheap,
+  disconnectNamecheap,
+  getAuthStatus as getNamecheapAuthStatus,
+  getResolvedAuthConfig,
+  resolvePublicIpv4,
+  runBrowserAuthFlow,
+  saveAuthConfig,
+} from "./tools/namecheap/auth.mjs";
+export {
+  createNamecheapClient,
+  createResolvedNamecheapClient,
+  NamecheapApiError,
+} from "./tools/namecheap/client.mjs";
+export {
+  createRailwayClient,
+  getRailwayAuthStatus,
+  RailwayApiError,
+  resolveRailwayApiToken,
+} from "./tools/railway/client.mjs";
+export {
+  clearStoredRailwayAuthConfig,
+  connectRailway,
+  disconnectRailway,
+  RAILWAY_AUTH_CONFIG_PATH,
+  runRailwayBrowserAuthFlow,
+  saveRailwayAuthConfig,
+} from "./tools/railway/auth.mjs";
+export {
+  clearStoredNpmAuthConfig,
+  connectNpm,
+  disconnectNpm,
+  getNpmAuthStatus,
+  NPM_AUTH_CONFIG_PATH,
+  resolveNpmAuthConfig,
+  runNpmBrowserAuthFlow,
+  saveNpmAuthConfig,
+} from "./tools/npm/auth.mjs";
+export {
+  createNpmClient,
+  encodePackageName,
+  NpmRegistryError,
+} from "./tools/npm/client.mjs";
+export { getTool, listTools, tools } from "./core/tool-registry.mjs";

package/src/tools/namecheap/auth.mjs

@@ -0,0 +1,429 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { isIP } from "node:net";
+import {
+  CONFIG_ROOT,
+  escapeHtml,
+  isTruthyEnv,
+  openBrowser,
+  parseFormBody,
+  pickString,
+  readJsonConfig,
+  removeJsonConfig,
+  resolveConfigPath,
+  writeJsonConfig,
+} from "../../core/config-store.mjs";
+
+const AUTH_CONFIG_PATH = resolveConfigPath({
+  env: process.env,
+  envVar: "NAMECHEAP_AUTH_CONFIG_PATH",
+  fileName: "namecheap.json",
+});
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+
+const resolveStoredConfig = async () => {
+  const stored = await readJsonConfig(AUTH_CONFIG_PATH);
+  if (stored) {
+    return stored;
+  }
+
+  const legacyPath = AUTH_CONFIG_PATH.endsWith("namecheap.json")
+    ? AUTH_CONFIG_PATH.replace(/namecheap\.json$/, "namecheap-auth.json")
+    : null;
+
+  return legacyPath ? await readJsonConfig(legacyPath) : null;
+};
+
+export const resolvePublicIpv4 = async ({
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 2500,
+} = {}) => {
+  if (typeof fetchImpl !== "function") {
+    return null;
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchImpl("https://api.ipify.org?format=json", {
+      signal: controller.signal,
+    });
+    const payload = await response.json();
+    const ip = typeof payload?.ip === "string" ? payload.ip.trim() : "";
+    return isIP(ip) === 4 ? ip : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+export const getResolvedAuthConfig = async () => {
+  const stored = await resolveStoredConfig();
+  const sandboxEnv = process.env.NAMECHEAP_API_SANDBOX;
+
+  const config = {
+    apiUser: pickString(process.env.NAMECHEAP_API_USER, stored?.apiUser),
+    apiKey: pickString(process.env.NAMECHEAP_API_KEY, stored?.apiKey),
+    username: pickString(process.env.NAMECHEAP_USERNAME, stored?.username),
+    clientIp: pickString(process.env.NAMECHEAP_CLIENT_IP, stored?.clientIp),
+    baseUrl: pickString(process.env.NAMECHEAP_API_BASE_URL, stored?.baseUrl),
+    sandbox:
+      sandboxEnv != null
+        ? isTruthyEnv(sandboxEnv)
+        : typeof stored?.sandbox === "boolean"
+          ? stored.sandbox
+          : false,
+    source:
+      process.env.NAMECHEAP_API_USER ||
+      process.env.NAMECHEAP_API_KEY ||
+      process.env.NAMECHEAP_USERNAME ||
+      process.env.NAMECHEAP_CLIENT_IP
+        ? "env"
+        : stored
+          ? "file"
+          : "none",
+  };
+
+  return config;
+};
+
+export const getAuthStatus = async () => {
+  const config = await getResolvedAuthConfig();
+  const hasCredentials = Boolean(
+    config.apiUser && config.apiKey && config.username && config.clientIp,
+  );
+
+  return {
+    configured: hasCredentials,
+    source: config.source,
+    sandbox: config.sandbox,
+    baseUrl: config.baseUrl || null,
+    hasApiUser: Boolean(config.apiUser),
+    hasApiKey: Boolean(config.apiKey),
+    hasUsername: Boolean(config.username),
+    hasClientIp: Boolean(config.clientIp),
+    configPath: AUTH_CONFIG_PATH,
+  };
+};
+
+export const saveAuthConfig = async ({
+  apiUser,
+  apiKey,
+  username,
+  clientIp,
+  sandbox = false,
+  baseUrl = "",
+} = {}) => {
+  const config = {
+    apiUser: String(apiUser ?? "").trim(),
+    apiKey: String(apiKey ?? "").trim(),
+    username: String(username ?? "").trim(),
+    clientIp: String(clientIp ?? "").trim(),
+    sandbox: Boolean(sandbox),
+    baseUrl: String(baseUrl ?? "").trim(),
+    savedAt: new Date().toISOString(),
+  };
+
+  for (const [key, value] of Object.entries(config)) {
+    if (
+      ["apiUser", "apiKey", "username", "clientIp"].includes(key) &&
+      (!value || String(value).trim().length === 0)
+    ) {
+      throw new Error(`Missing ${key} in Namecheap auth config.`);
+    }
+  }
+
+  await writeJsonConfig(AUTH_CONFIG_PATH, config);
+
+  return {
+    configPath: AUTH_CONFIG_PATH,
+    sandbox: config.sandbox,
+  };
+};
+
+/* v8 ignore start */
+const renderPage = ({ csrfToken, message = "", defaults = {} }) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Namecheap Setup</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: #f5efe8;
+        --panel: #fffaf5;
+        --text: #1f1a16;
+        --muted: #6f6258;
+        --accent: #de3723;
+        --border: #e5d3c4;
+      }
+      body {
+        margin: 0;
+        font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        background: radial-gradient(circle at top, #fff3ea, var(--bg));
+        color: var(--text);
+      }
+      .wrap {
+        max-width: 760px;
+        margin: 32px auto;
+        padding: 24px;
+      }
+      .panel {
+        background: var(--panel);
+        border: 1px solid var(--border);
+        border-radius: 20px;
+        padding: 24px;
+        box-shadow: 0 20px 50px rgba(70, 43, 20, 0.08);
+      }
+      h1 { margin-top: 0; font-size: 28px; }
+      p, li { line-height: 1.5; color: var(--muted); }
+      a { color: var(--accent); }
+      form { display: grid; gap: 16px; margin-top: 24px; }
+      label { display: grid; gap: 6px; font-weight: 600; }
+      input[type="text"], input[type="password"] {
+        padding: 12px 14px;
+        border-radius: 12px;
+        border: 1px solid var(--border);
+        font: inherit;
+        background: white;
+      }
+      .row { display: grid; gap: 16px; grid-template-columns: 1fr 1fr; }
+      .message {
+        margin-top: 16px;
+        padding: 12px 14px;
+        border-radius: 12px;
+        background: #fff1ec;
+        color: #8f2719;
+      }
+      button {
+        border: 0;
+        border-radius: 999px;
+        padding: 12px 18px;
+        font: inherit;
+        font-weight: 700;
+        color: white;
+        background: var(--accent);
+        cursor: pointer;
+        width: fit-content;
+      }
+      code {
+        background: #f1e3d6;
+        padding: 2px 6px;
+        border-radius: 6px;
+      }
+      @media (max-width: 720px) {
+        .row { grid-template-columns: 1fr; }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <div class="panel">
+        <h1>Connect Namecheap</h1>
+        <p>Namecheap does not use OAuth here. You need to generate an API key in Namecheap and whitelist your IPv4 address, then paste the values below.</p>
+        ${
+          defaults.detectedClientIp
+            ? `<p>Detected public IPv4: <code>${escapeHtml(defaults.detectedClientIp)}</code></p>`
+            : ""
+        }
+        <ol>
+          <li>Open <a href="https://www.namecheap.com/support/knowledgebase/article.aspx/763/63/what-is-sandbox/" target="_blank" rel="noreferrer">Sandbox setup</a> if you want safe testing first.</li>
+          <li>Open <a href="https://ap.www.namecheap.com/settings/tools/apiaccess/" target="_blank" rel="noreferrer">production API access</a> or the Sandbox account’s API access page.</li>
+          <li>Enable API access and whitelist the same IPv4 address you enter as <code>Client IP</code>.</li>
+          <li>Copy your API user, API key, and username into this form.</li>
+        </ol>
+        ${
+          message
+            ? `<div class="message">${escapeHtml(message)}</div>`
+            : ""
+        }
+        <form method="post" action="/save">
+          <input type="hidden" name="csrfToken" value="${escapeHtml(csrfToken)}" />
+          <div class="row">
+            <label>
+              API User
+              <input name="apiUser" type="text" value="${escapeHtml(defaults.apiUser ?? "")}" required />
+            </label>
+            <label>
+              Username
+              <input name="username" type="text" value="${escapeHtml(defaults.username ?? "")}" required />
+            </label>
+          </div>
+          <label>
+            API Key
+            <input name="apiKey" type="password" value="${escapeHtml(defaults.apiKey ?? "")}" required />
+          </label>
+          <div class="row">
+            <label>
+              Client IP (must be whitelisted in Namecheap)
+              <input name="clientIp" type="text" value="${escapeHtml(defaults.clientIp ?? "")}" required />
+            </label>
+            <label>
+              API Base URL Override (optional)
+              <input name="baseUrl" type="text" value="${escapeHtml(defaults.baseUrl ?? "")}" placeholder="https://api.namecheap.com/xml.response" />
+            </label>
+          </div>
+          <label style="display:flex; align-items:center; gap:10px; font-weight:500;">
+            <input name="sandbox" type="checkbox" value="1" ${defaults.sandbox ? "checked" : ""} />
+            Use Sandbox account
+          </label>
+          <button type="submit">Save Namecheap Credentials</button>
+        </form>
+      </div>
+    </div>
+  </body>
+</html>`;
+
+export const runBrowserAuthFlow = async ({
+  defaultSandbox = true,
+  fetchImpl = globalThis.fetch,
+  validateConnection = true,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) => {
+  const existing = await getResolvedAuthConfig();
+  const detectedClientIp = existing.clientIp
+    ? null
+    : await resolvePublicIpv4({ fetchImpl });
+  const csrfToken = randomUUID();
+
+  return await new Promise((resolve, reject) => {
+    let closed = false;
+    let timeoutId;
+
+    const finish = (callback) => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      clearTimeout(timeoutId);
+      server.close(() => callback());
+    };
+
+    const server = createServer(async (request, response) => {
+      const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+
+      if (request.method === "GET" && requestUrl.pathname === "/") {
+        response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        response.end(
+          renderPage({
+            csrfToken,
+            defaults: {
+              apiUser: existing.apiUser ?? "",
+              username: existing.username ?? "",
+              clientIp: existing.clientIp ?? detectedClientIp ?? "",
+              detectedClientIp,
+              baseUrl: existing.baseUrl ?? "",
+              sandbox: existing.sandbox || defaultSandbox,
+            },
+          }),
+        );
+        return;
+      }
+
+      if (request.method === "POST" && requestUrl.pathname === "/save") {
+        try {
+          const body = await parseFormBody(request);
+          if (body.csrfToken !== csrfToken) {
+            response.writeHead(403, {
+              "content-type": "text/html; charset=utf-8",
+            });
+            response.end("Invalid CSRF token.");
+            return;
+          }
+
+          if (validateConnection) {
+            const { createNamecheapClient } = await import("./client.mjs");
+            const client = createNamecheapClient({
+              apiUser: body.apiUser,
+              apiKey: body.apiKey,
+              username: body.username,
+              clientIp: body.clientIp,
+              baseUrl: body.baseUrl,
+              sandbox: body.sandbox === "1",
+            });
+            await client.listDomains({ page: 1, pageSize: 1 });
+          }
+
+          const saved = await saveAuthConfig({
+            apiUser: body.apiUser,
+            apiKey: body.apiKey,
+            username: body.username,
+            clientIp: body.clientIp,
+            baseUrl: body.baseUrl,
+            sandbox: body.sandbox === "1",
+          });
+
+          response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+          response.end(`<!doctype html><html><body style="font-family: sans-serif; padding: 24px;"><h1>Namecheap connected</h1><p>Credentials were saved to <code>${escapeHtml(saved.configPath)}</code>. You can close this tab.</p></body></html>`);
+          finish(() => resolve(saved));
+        } catch (error) {
+          response.writeHead(400, {
+            "content-type": "text/html; charset=utf-8",
+          });
+          response.end(
+            renderPage({
+              csrfToken,
+              message:
+                error instanceof Error ? error.message : String(error),
+              defaults: {
+                apiUser: "",
+                username: "",
+                clientIp: "",
+                baseUrl: "",
+                sandbox: defaultSandbox,
+              },
+            }),
+          );
+        }
+        return;
+      }
+
+      response.writeHead(404);
+      response.end("Not found");
+    });
+
+    server.listen(0, "127.0.0.1", async () => {
+      try {
+        const address = server.address();
+        if (!address || typeof address === "string") {
+          throw new Error("Failed to bind local Namecheap auth server.");
+        }
+
+        const url = `http://127.0.0.1:${address.port}/`;
+        await openBrowser(url, { skipEnvVar: "NAMECHEAP_SKIP_BROWSER_OPEN" });
+      } catch (error) {
+        finish(() => reject(error));
+      }
+    });
+
+    timeoutId = setTimeout(() => {
+      finish(() =>
+        reject(
+          new Error(
+            "Timed out waiting for Namecheap browser setup to complete.",
+          ),
+        ),
+      );
+    }, timeoutMs);
+  });
+};
+/* v8 ignore stop */
+
+export const clearStoredAuthConfig = async () => {
+  await removeJsonConfig(AUTH_CONFIG_PATH);
+};
+
+export const connectNamecheap = runBrowserAuthFlow;
+
+export const disconnectNamecheap = async () => {
+  await clearStoredAuthConfig();
+  return {
+    disconnected: true,
+    configPath: AUTH_CONFIG_PATH,
+  };
+};
+
+export { AUTH_CONFIG_PATH, CONFIG_ROOT };