design-system-selector 0.1.1 → 0.1.2

package/README.md

@@ -18,6 +18,22 @@ brew install design-system-selector
 
 Requires Node.js 20 or later.
 
+## AI Matching
+
+AI matching is provided through the hosted Design System Selector API proxy.
+
+- Users do **not** need to configure `ANTHROPIC_API_KEY`
+- The CLI sends questionnaire preferences to the backend and receives ranked results
+- If the API is unavailable, the CLI automatically falls back to static matching
+
+For local backend testing, maintainers can override the API base URL:
+
+```sh
+DESIGN_SYSTEM_SELECTOR_API_URL=http://localhost:8787 npx design-system-selector
+```
+
+Backend deployment guide: [`docs/vercel-backend.md`](docs/vercel-backend.md)
+
 ## How It Works
 
 The CLI asks you 5 questions about your project:

package/dist/cli.js

@@ -402,91 +402,43 @@ function match(systems2, prefs) {
 }
 
 // src/agent/client.ts
-import Anthropic from "@anthropic-ai/sdk";
-function isAgentAvailable() {
-  const key = process.env["ANTHROPIC_API_KEY"];
-  return typeof key === "string" && key.length > 0;
-}
-function createClient() {
-  if (!isAgentAvailable()) {
-    throw new Error(
-      "ANTHROPIC_API_KEY environment variable is not set. AI matching is unavailable."
-    );
+var DEFAULT_AGENT_API_URL = "https://api.thelostbygass.com";
+var AGENT_MATCH_PATH = "/v1/match";
+var REQUEST_TIMEOUT_MS = 15e3;
+function normalizeBaseUrl(raw) {
+  return raw.replace(/\/+$/, "");
+}
+function getAgentApiUrl() {
+  const configured = process.env["DESIGN_SYSTEM_SELECTOR_API_URL"];
+  if (typeof configured === "string" && configured.trim().length > 0) {
+    return normalizeBaseUrl(configured.trim());
+  }
+  return DEFAULT_AGENT_API_URL;
+}
+function buildEndpoint() {
+  return `${getAgentApiUrl()}${AGENT_MATCH_PATH}`;
+}
+async function requestAgentMatch(preferences) {
+  const payload = { preferences };
+  const response = await fetch(buildEndpoint(), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok) {
+    const details = (await response.text()).trim();
+    const suffix = details ? `: ${details}` : "";
+    throw new Error(`AI API request failed (${response.status})${suffix}`);
   }
-  return new Anthropic();
-}
-
-// src/agent/prompt.ts
-function buildSystemPrompt() {
-  return `You are a design system advisor. Given a set of design systems and user preferences, score and rank the systems to find the best matches.
-
-## Scoring Dimensions (total 100 points)
-- accessibility (22): Match accessibility score and EU compliance to user need
-- designPhilosophy (18): Match visual style to system philosophy
-- customization (18): Match opinion level to customization depth
-- learningCurve (17): Match experience level to learning curve
-- projectType (15): Match project type to system strengths
-- color (10): Match color preference to system color strengths
-
-## Accessibility Hard Filter
-Before scoring, exclude systems that fail the accessibility filter:
-- "critical" need \u2192 ONLY systems with accessibilityScore "AAA" AND euCompliance "full"
-- "important" need \u2192 ONLY systems with accessibilityScore "AAA" or "AA"
-- "standard" need \u2192 all systems pass
-
-## Framework Hard Filter
-Before scoring, exclude systems that don't support the user's framework:
-- If framework is "any" \u2192 all systems pass
-- Otherwise \u2192 ONLY systems whose frameworks array includes the user's framework
-
-## Output Format
-Return ONLY valid JSON (no markdown, no explanation) matching this exact shape:
-{
-  "primary": { "systemId": string, "score": number (0-100), "matchedDimensions": number (0-6), "reasons": string[] },
-  "alternatives": [
-    { "systemId": string, "score": number (0-100), "matchedDimensions": number (0-6), "reasons": string[] },
-    { "systemId": string, "score": number (0-100), "matchedDimensions": number (0-6), "reasons": string[] }
-  ],
-  "relaxed": boolean
-}
-
-Rules:
-- primary is the best match, alternatives are the next two best
-- reasons should be 2-4 concise, context-aware explanations per system
-- relaxed is true if primary matchedDimensions < 4
-- systemId must be one of the provided system IDs
-- score is 0-100, matchedDimensions is 0-6`;
-}
-function compressSystem(system) {
-  return {
-    id: system.id,
-    name: system.name,
-    philosophy: system.designPhilosophy.join(","),
-    frameworks: system.frameworks.join(","),
-    a11y: system.accessibilityScore,
-    customization: system.customizationDepth,
-    learning: system.learningCurve,
-    colors: system.colorStrengths.join(","),
-    projects: system.projectStrengths.join(","),
-    eu: system.euCompliance,
-    tradeoffs: system.tradeoffs
-  };
-}
-function buildUserMessage(systems2, prefs) {
-  const compressed = systems2.map(compressSystem);
-  return `## Available Design Systems
-${compressed.map((s2) => `- ${s2.id}: ${s2.name} | philosophy=${s2.philosophy} | frameworks=${s2.frameworks} | a11y=${s2.a11y} | eu=${s2.eu} | customization=${s2.customization} | learning=${s2.learning} | colors=${s2.colors} | projects=${s2.projects} | tradeoffs="${s2.tradeoffs}"`).join("\n")}
-
-## User Preferences
-- visualStyle: ${prefs.visualStyle}
-- accessibilityNeed: ${prefs.accessibilityNeed}
-- opinionLevel: ${prefs.opinionLevel}
-- experienceLevel: ${prefs.experienceLevel}
-- colorPreference: ${prefs.colorPreference}
-- projectType: ${prefs.projectType}
-- framework: ${prefs.framework}
-
-Score and rank these systems for this user. Return JSON only.`;
+  const json = await response.json();
+  if (typeof json !== "object" || json === null) {
+    throw new Error("AI API response is not a JSON object");
+  }
+  return json;
 }
 
 // src/agent/parser.ts
@@ -581,24 +533,8 @@ function parseAgentResponse(raw, systems2) {
 
 // src/agent/matcher.ts
 async function agentMatch(systems2, prefs) {
-  const client = createClient();
-  const response = await client.messages.create({
-    model: "claude-haiku-4-5-20251001",
-    max_tokens: 1024,
-    temperature: 0,
-    system: buildSystemPrompt(),
-    messages: [
-      {
-        role: "user",
-        content: buildUserMessage(systems2, prefs)
-      }
-    ]
-  });
-  const textBlock = response.content.find((block) => block.type === "text");
-  if (!textBlock || textBlock.type !== "text") {
-    throw new Error("No text content in AI response");
-  }
-  return parseAgentResponse(textBlock.text, systems2);
+  const rawResponse = await requestAgentMatch(prefs);
+  return parseAgentResponse(JSON.stringify(rawResponse), systems2);
 }
 
 // src/output.ts
@@ -3773,26 +3709,20 @@ async function main() {
   }
   const prefs = await runQuestionnaire();
   let result;
-  if (isAgentAvailable()) {
+  if (!mcpOnly) {
+    console.log(chalk5.dim("\n  Analyzing with AI...\n"));
+  }
+  try {
+    result = await agentMatch(systems, prefs);
+  } catch (err) {
     if (!mcpOnly) {
-      console.log(chalk5.dim("\n  Analyzing with AI...\n"));
-    }
-    try {
-      result = await agentMatch(systems, prefs);
-    } catch (err) {
-      if (!mcpOnly) {
-        console.log(
-          chalk5.yellow(
-            `  AI matching failed (${err instanceof Error ? err.message : "unknown error"}), using static analysis...
+      console.log(
+        chalk5.yellow(
+          `  AI matching unavailable (${err instanceof Error ? err.message : "unknown error"}), using static analysis...
 `
-          )
-        );
-      }
-      result = match(systems, prefs);
-    }
-  } else {
-    if (!mcpOnly) {
-      console.log(chalk5.dim("\n  Analyzing your preferences...\n"));
+        )
+      );
+      console.log(chalk5.dim("  Analyzing your preferences...\n"));
     }
     result = match(systems, prefs);
   }

package/dist/index.js

@@ -400,91 +400,43 @@ function match(systems2, prefs) {
 }
 
 // src/agent/client.ts
-import Anthropic from "@anthropic-ai/sdk";
-function isAgentAvailable() {
-  const key = process.env["ANTHROPIC_API_KEY"];
-  return typeof key === "string" && key.length > 0;
-}
-function createClient() {
-  if (!isAgentAvailable()) {
-    throw new Error(
-      "ANTHROPIC_API_KEY environment variable is not set. AI matching is unavailable."
-    );
+var DEFAULT_AGENT_API_URL = "https://api.thelostbygass.com";
+var AGENT_MATCH_PATH = "/v1/match";
+var REQUEST_TIMEOUT_MS = 15e3;
+function normalizeBaseUrl(raw) {
+  return raw.replace(/\/+$/, "");
+}
+function getAgentApiUrl() {
+  const configured = process.env["DESIGN_SYSTEM_SELECTOR_API_URL"];
+  if (typeof configured === "string" && configured.trim().length > 0) {
+    return normalizeBaseUrl(configured.trim());
+  }
+  return DEFAULT_AGENT_API_URL;
+}
+function buildEndpoint() {
+  return `${getAgentApiUrl()}${AGENT_MATCH_PATH}`;
+}
+async function requestAgentMatch(preferences) {
+  const payload = { preferences };
+  const response = await fetch(buildEndpoint(), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok) {
+    const details = (await response.text()).trim();
+    const suffix = details ? `: ${details}` : "";
+    throw new Error(`AI API request failed (${response.status})${suffix}`);
   }
-  return new Anthropic();
-}
-
-// src/agent/prompt.ts
-function buildSystemPrompt() {
-  return `You are a design system advisor. Given a set of design systems and user preferences, score and rank the systems to find the best matches.
-
-## Scoring Dimensions (total 100 points)
-- accessibility (22): Match accessibility score and EU compliance to user need
-- designPhilosophy (18): Match visual style to system philosophy
-- customization (18): Match opinion level to customization depth
-- learningCurve (17): Match experience level to learning curve
-- projectType (15): Match project type to system strengths
-- color (10): Match color preference to system color strengths
-
-## Accessibility Hard Filter
-Before scoring, exclude systems that fail the accessibility filter:
-- "critical" need \u2192 ONLY systems with accessibilityScore "AAA" AND euCompliance "full"
-- "important" need \u2192 ONLY systems with accessibilityScore "AAA" or "AA"
-- "standard" need \u2192 all systems pass
-
-## Framework Hard Filter
-Before scoring, exclude systems that don't support the user's framework:
-- If framework is "any" \u2192 all systems pass
-- Otherwise \u2192 ONLY systems whose frameworks array includes the user's framework
-
-## Output Format
-Return ONLY valid JSON (no markdown, no explanation) matching this exact shape:
-{
-  "primary": { "systemId": string, "score": number (0-100), "matchedDimensions": number (0-6), "reasons": string[] },
-  "alternatives": [
-    { "systemId": string, "score": number (0-100), "matchedDimensions": number (0-6), "reasons": string[] },
-    { "systemId": string, "score": number (0-100), "matchedDimensions": number (0-6), "reasons": string[] }
-  ],
-  "relaxed": boolean
-}
-
-Rules:
-- primary is the best match, alternatives are the next two best
-- reasons should be 2-4 concise, context-aware explanations per system
-- relaxed is true if primary matchedDimensions < 4
-- systemId must be one of the provided system IDs
-- score is 0-100, matchedDimensions is 0-6`;
-}
-function compressSystem(system) {
-  return {
-    id: system.id,
-    name: system.name,
-    philosophy: system.designPhilosophy.join(","),
-    frameworks: system.frameworks.join(","),
-    a11y: system.accessibilityScore,
-    customization: system.customizationDepth,
-    learning: system.learningCurve,
-    colors: system.colorStrengths.join(","),
-    projects: system.projectStrengths.join(","),
-    eu: system.euCompliance,
-    tradeoffs: system.tradeoffs
-  };
-}
-function buildUserMessage(systems2, prefs) {
-  const compressed = systems2.map(compressSystem);
-  return `## Available Design Systems
-${compressed.map((s2) => `- ${s2.id}: ${s2.name} | philosophy=${s2.philosophy} | frameworks=${s2.frameworks} | a11y=${s2.a11y} | eu=${s2.eu} | customization=${s2.customization} | learning=${s2.learning} | colors=${s2.colors} | projects=${s2.projects} | tradeoffs="${s2.tradeoffs}"`).join("\n")}
-
-## User Preferences
-- visualStyle: ${prefs.visualStyle}
-- accessibilityNeed: ${prefs.accessibilityNeed}
-- opinionLevel: ${prefs.opinionLevel}
-- experienceLevel: ${prefs.experienceLevel}
-- colorPreference: ${prefs.colorPreference}
-- projectType: ${prefs.projectType}
-- framework: ${prefs.framework}
-
-Score and rank these systems for this user. Return JSON only.`;
+  const json = await response.json();
+  if (typeof json !== "object" || json === null) {
+    throw new Error("AI API response is not a JSON object");
+  }
+  return json;
 }
 
 // src/agent/parser.ts
@@ -579,24 +531,8 @@ function parseAgentResponse(raw, systems2) {
 
 // src/agent/matcher.ts
 async function agentMatch(systems2, prefs) {
-  const client = createClient();
-  const response = await client.messages.create({
-    model: "claude-haiku-4-5-20251001",
-    max_tokens: 1024,
-    temperature: 0,
-    system: buildSystemPrompt(),
-    messages: [
-      {
-        role: "user",
-        content: buildUserMessage(systems2, prefs)
-      }
-    ]
-  });
-  const textBlock = response.content.find((block) => block.type === "text");
-  if (!textBlock || textBlock.type !== "text") {
-    throw new Error("No text content in AI response");
-  }
-  return parseAgentResponse(textBlock.text, systems2);
+  const rawResponse = await requestAgentMatch(prefs);
+  return parseAgentResponse(JSON.stringify(rawResponse), systems2);
 }
 
 // src/output.ts
@@ -3771,26 +3707,20 @@ async function main() {
   }
   const prefs = await runQuestionnaire();
   let result;
-  if (isAgentAvailable()) {
+  if (!mcpOnly) {
+    console.log(chalk5.dim("\n  Analyzing with AI...\n"));
+  }
+  try {
+    result = await agentMatch(systems, prefs);
+  } catch (err) {
     if (!mcpOnly) {
-      console.log(chalk5.dim("\n  Analyzing with AI...\n"));
-    }
-    try {
-      result = await agentMatch(systems, prefs);
-    } catch (err) {
-      if (!mcpOnly) {
-        console.log(
-          chalk5.yellow(
-            `  AI matching failed (${err instanceof Error ? err.message : "unknown error"}), using static analysis...
+      console.log(
+        chalk5.yellow(
+          `  AI matching unavailable (${err instanceof Error ? err.message : "unknown error"}), using static analysis...
 `
-          )
-        );
-      }
-      result = match(systems, prefs);
-    }
-  } else {
-    if (!mcpOnly) {
-      console.log(chalk5.dim("\n  Analyzing your preferences...\n"));
+        )
+      );
+      console.log(chalk5.dim("  Analyzing your preferences...\n"));
     }
     result = match(systems, prefs);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-system-selector",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI tool that recommends alternative design systems based on your project needs",
   "type": "module",
   "main": "dist/index.js",
@@ -30,6 +30,7 @@
   "homepage": "https://github.com/TheLostByGass/design-system-selector#readme",
   "scripts": {
     "dev": "tsx --env-file=.env src/index.ts",
+    "vercel-build": "echo 'No build step required for Vercel API deployment'",
     "lint": "eslint src tests",
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
@@ -47,16 +48,15 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.77.0",
     "@inquirer/prompts": "^7.0.0",
     "chalk": "^5.3.0",
     "ora": "^9.3.0"
   },
   "devDependencies": {
-    "dotenv": "^17.3.1",
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@types/node": "^22.0.0",
+    "dotenv": "^17.3.1",
     "eslint": "^10.0.0",
     "prettier": "^3.8.1",
     "tsup": "^8.0.0",