@maintainer-pro/ai-server 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @maintainer-pro/ai-server
+
+Local Node **chat server** (sidecar) for Maintainer Pro. Start it with `npx` — no custom `server.mjs`.
+
+It uses [`@maintainer-pro/ai-cli`](https://www.npmjs.com/package/@maintainer-pro/ai-cli) to talk to Cursor (`agent`), Claude (`claude`), or Antigravity (`agy`).
+
+This process is **not** the host product backend. Run it **beside** the app in development. The sandbox setup guide uses port **3100** so it does not collide with the host (`:3000` / `:5173`). The binary default with no env is port `3000`.
+
+It is **not** what you ship as the production website. Without this process, `localhost:3100` is down and a page that loads the widget from there will show no chat. Production should serve `ai-ui.iife.js` as a static file and call a real chat API — see [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui).
+
+## Quick start
+
+```bash
+npx --yes @maintainer-pro/ai-server
+```
+
+Put a `.env` in the current directory (from the admin setup guide or by hand). CLI flags override env.
+
+Requires **Node.js 22+**, [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui) next to this package (for `/ai-ui.iife.js`), and one authenticated coding-agent CLI.
+
+## Routes
+
+| Path | Purpose |
+|------|---------|
+| `GET` / `POST /api/chat` | Chat (agent + Maintainer Pro store) |
+| `GET /embed-config.js` | Client keys for the widget (`window.__MAINTAINER_PRO__`) |
+| `GET /ai-ui.iife.js` | Embed widget from `node_modules/@maintainer-pro/ai-ui` (unless a file exists in `AI_SERVER_UI`) |
+| other paths | Static files from `AI_SERVER_UI` |
+
+A copied `ai-ui.iife.js` in the UI folder is served first and will not update when you `npm update @maintainer-pro/ai-ui`. Prefer the `node_modules` copy, then restart this process.
+
+## Config
+
+| Env / flag | Purpose |
+|------------|---------|
+| `PORT` / `--port` | Listen port (binary default `3000`; setup guide uses `3100`) |
+| `AI_CLI_WORKSPACE` / `--workspace` | Folder the agent may edit |
+| `AI_SERVER_UI` / `--ui` | Static UI folder |
+| `CORS_ORIGIN` / `--cors-origin` | Browser origin of the **host app** |
+| `--env-file` | Env file path (default `./.env`) |
+| `MAINTAINER_PRO_URL` | Admin base URL |
+| `MAINTAINER_PRO_API_KEY` | Server API key |
+| `MAINTAINER_PRO_CLIENT_API_KEY` | Client key (served at `/embed-config.js`) |
+| `AI_CLI_PROVIDER` | `auto` \| `claude` \| `cursor` \| `antigravity` |
+| `AI_SERVER_PRODUCT_DESCRIPTION` | Optional product text for the agent prompt |
+
+```bash
+npx --yes @maintainer-pro/ai-server --port 3100 --ui . --workspace .
+```
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| [`@maintainer-pro/ai-cli`](https://www.npmjs.com/package/@maintainer-pro/ai-cli) | Talks to coding agents |
+| [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui) | Embed widget (`/ai-ui.iife.js`) |
+| [`@maintainer-pro/setup`](https://www.npmjs.com/package/@maintainer-pro/setup) | Download the sandbox setup guide |

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ *   npx --yes @maintainer-pro/ai-server
+ */
+import "../src/server.mjs";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@maintainer-pro/ai-server",
+  "version": "0.1.0",
+  "description": "Node HTTP server for Maintainer Pro chat. Uses @maintainer-pro/ai-cli to talk to coding agents.",
+  "keywords": [
+    "maintainer-pro",
+    "ai",
+    "chat",
+    "server",
+    "npx",
+    "cursor",
+    "claude"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ai-server": "bin/cli.js",
+    "maintainer-pro-ai-server": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@maintainer-pro/ai-cli": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/server.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * Maintainer Pro chat HTTP server.
+ * Talks to coding agents through @maintainer-pro/ai-cli.
+ *
+ * Config from .env (or --env-file). CLI flags override env.
+ */
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  createChatHandler,
+  createDefaultSystemPrompt,
+  createMaintainerProStoreFromEnv,
+} from "@maintainer-pro/ai-cli";
+
+const log = (msg) => console.log(`[ai-server] ${msg}`);
+const fail = (msg) => {
+  console.error(`[ai-server] ${msg}`);
+  process.exit(1);
+};
+
+function parseArgs(argv) {
+  /** @type {Record<string, string | boolean>} */
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (arg.startsWith("--") && i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      out[key] = argv[++i];
+      continue;
+    }
+  }
+  return out;
+}
+
+function loadEnvFile(file) {
+  if (!file || !fs.existsSync(file)) return;
+  const text = fs.readFileSync(file, "utf8");
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
+}
+
+function printHelp() {
+  console.log(`Maintainer Pro AI server
+
+Usage:
+  npx @maintainer-pro/ai-server
+  npx @maintainer-pro/ai-server --port 3000 --ui . --workspace .
+
+Flags override .env. Preferred config is env (from the admin setup guide).
+
+  --port <n>           Listen port (PORT)
+  --ui <dir>           Static UI folder (AI_SERVER_UI)
+  --workspace <dir>    Agent edit root (AI_CLI_WORKSPACE)
+  --env-file <path>    Env file (default: ./.env)
+  --cors-origin <url>  CORS origin (CORS_ORIGIN)
+`);
+}
+
+function contentType(file) {
+  if (file.endsWith(".html")) return "text/html; charset=utf-8";
+  if (file.endsWith(".js")) return "text/javascript; charset=utf-8";
+  if (file.endsWith(".css")) return "text/css; charset=utf-8";
+  if (file.endsWith(".svg")) return "image/svg+xml";
+  if (file.endsWith(".json")) return "application/json";
+  if (file.endsWith(".map")) return "application/json";
+  return "application/octet-stream";
+}
+
+function resolveUiFile(uiDir, pathname) {
+  const rel = decodeURIComponent(pathname === "/" ? "/index.html" : pathname);
+  const file = path.normalize(path.join(uiDir, rel));
+  const root = path.resolve(uiDir);
+  if (!file.startsWith(root)) return null;
+  if (fs.existsSync(file) && fs.statSync(file).isFile()) return file;
+  if (pathname === "/ai-ui.iife.js") {
+    const bundled = findIife();
+    if (bundled) return bundled;
+  }
+  return null;
+}
+
+function findIife() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(process.cwd(), "node_modules/@maintainer-pro/ai-ui/dist/ai-ui.iife.js"),
+    path.resolve(here, "../../ai-ui/dist/ai-ui.iife.js"),
+    path.resolve(here, "../../../node_modules/@maintainer-pro/ai-ui/dist/ai-ui.iife.js"),
+  ];
+  return candidates.find((file) => fs.existsSync(file)) ?? null;
+}
+
+async function toFetchRequest(req) {
+  const host = req.headers.host ?? "localhost";
+  const url = `http://${host}${req.url ?? "/"}`;
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const body = Buffer.concat(chunks);
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    headers.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+  }
+  /** @type {RequestInit} */
+  const init = { method: req.method, headers };
+  if (req.method !== "GET" && req.method !== "HEAD" && body.length) {
+    init.body = body;
+    init.duplex = "half";
+  }
+  return new Request(url, init);
+}
+
+async function send(res, response) {
+  res.statusCode = response.status;
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === "transfer-encoding") return;
+    res.setHeader(key, value);
+  });
+  res.end(Buffer.from(await response.arrayBuffer()));
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const envFile = path.resolve(
+  typeof args.envFile === "string" ? args.envFile : path.join(process.cwd(), ".env")
+);
+loadEnvFile(envFile);
+
+const port = Number(args.port || process.env.PORT || 3000);
+const workspaceDir = path.resolve(
+  args.workspace || process.env.AI_CLI_WORKSPACE || process.cwd()
+);
+const uiDir = path.resolve(
+  args.ui || process.env.AI_SERVER_UI || process.cwd()
+);
+const corsOrigin =
+  (typeof args.corsOrigin === "string" ? args.corsOrigin : process.env.CORS_ORIGIN) ||
+  "*";
+
+process.env.AI_CLI_WORKSPACE = workspaceDir;
+
+const db = createMaintainerProStoreFromEnv();
+if (!db) {
+  fail(
+    `Set MAINTAINER_PRO_URL and MAINTAINER_PRO_API_KEY (env file: ${envFile}).`
+  );
+}
+
+const productDescription =
+  process.env.AI_SERVER_PRODUCT_DESCRIPTION?.trim() ||
+  "This product uses Maintainer Pro. When the user asks for a change, edit source files in the workspace using the coding agent CLI. Do not invent JSON tool calls.";
+
+const handlers = createChatHandler({
+  systemPrompt: createDefaultSystemPrompt({ productDescription }),
+  workspaceDir,
+  db,
+});
+
+const server = http.createServer((req, res) => {
+  const pathname = (req.url ?? "/").split("?")[0];
+  res.setHeader("Access-Control-Allow-Origin", corsOrigin);
+  res.setHeader("Access-Control-Allow-Headers", "content-type, authorization");
+  res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
+  if (req.method === "OPTIONS") {
+    res.statusCode = 204;
+    res.end();
+    return;
+  }
+  if (pathname === "/embed-config.js") {
+    const payload = {
+      maintainerProUrl: process.env.MAINTAINER_PRO_URL ?? "",
+      maintainerProApiKey:
+        process.env.MAINTAINER_PRO_CLIENT_API_KEY ??
+        process.env.NEXT_PUBLIC_MAINTAINER_PRO_CLIENT_API_KEY ??
+        "",
+    };
+    res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+    res.end(`window.__MAINTAINER_PRO__=${JSON.stringify(payload)};`);
+    return;
+  }
+  if (pathname === "/api/chat") {
+    const handler = req.method === "GET" ? handlers.GET : handlers.POST;
+    void toFetchRequest(req)
+      .then((request) => handler(request))
+      .then((response) => send(res, response))
+      .catch((err) => {
+        console.error(err);
+        res.statusCode = 500;
+        res.end("Chat handler failed");
+      });
+    return;
+  }
+  const file = resolveUiFile(uiDir, pathname);
+  if (!file) {
+    res.statusCode = 404;
+    res.end("Not found");
+    return;
+  }
+  res.setHeader("Content-Type", contentType(file));
+  fs.createReadStream(file).pipe(res);
+});
+
+server.listen(port, () => {
+  log(`chat → http://localhost:${port}/api/chat`);
+  log(`ui   → http://localhost:${port}/`);
+  log(`workspace ${workspaceDir}`);
+});