@ansh-ui/cli 0.3.1 → 0.4.0

package/dist/cli.js

@@ -1,9 +1,23 @@
 #!/usr/bin/env node
 import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
 import { parseArgs } from 'util';
-import { join, dirname, resolve } from 'path';
+import { join, dirname, resolve, relative } from 'path';
 import { parseColor, generatePalette, rgbToOklch, toOklchString, toHex, createGradient, createScale, checkContrast, harmony, effects, behaviours } from '@ansh-ui/core';
+import { createInterface } from 'readline';
 
+var CONFIG_FILE = "ansh.config.json";
+function readConfig(root) {
+  const path = join(root, CONFIG_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/project.ts
 function findRoot(cwd) {
   let current = resolve(cwd);
   for (let depth = 0; depth < 10; depth++) {
@@ -31,11 +45,12 @@ function detectProject(cwd = process.cwd()) {
   const framework = deps.nuxt ? "nuxt" : deps.next ? "next" : deps.vue ? "vue" : deps.react ? "react" : "unknown";
   const typescript = Boolean(deps.typescript) || existsSync(join(root, "tsconfig.json"));
   const packageManager = existsSync(join(root, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")) ? "bun" : existsSync(join(root, "yarn.lock")) ? "yarn" : "npm";
+  const config = readConfig(root);
   return {
     root,
     framework,
     typescript,
-    componentsDir: detectComponentsDir(root, framework),
+    componentsDir: config?.componentsDir ?? detectComponentsDir(root, framework),
     alias: detectAlias(root),
     packageManager,
     installed: Boolean(
@@ -66,10 +81,8 @@ function detectAlias(root) {
   return null;
 }
 var KNOWN_INCONSISTENCIES = [
-  {
-    title: "License key prefix is still `aur_`",
-    detail: "A leftover from the Aurelis \u2192 Ansh rename (packages/license/src/public-key.ts). Changing it without a dual-prefix verification path would invalidate already-issued keys \u2014 needs a maintainer decision, not a drive-by fix. See STATUS.md \xA77."
-  }
+  // Empty since the licence key prefix moved to `ansh_` (with `aur_` still accepted). Add an entry
+  // here when STATUS.md §7 gains one.
 ];
 function isAnshRepoRoot(root) {
   const pkg = readJson(join(root, "package.json"));
@@ -78,6 +91,16 @@ function isAnshRepoRoot(root) {
 function detectKnownInconsistencies(root) {
   return isAnshRepoRoot(root) ? KNOWN_INCONSISTENCIES : [];
 }
+function packagesFor(framework) {
+  switch (framework) {
+    case "nuxt":
+      return ["@ansh-ui/nuxt"];
+    case "vue":
+      return ["@ansh-ui/vue", "@ansh-ui/tokens"];
+    default:
+      return ["@ansh-ui/react", "@ansh-ui/tokens"];
+  }
+}
 function installCommand(info, packages) {
   const list = packages.join(" ");
   switch (info.packageManager) {
@@ -184,15 +207,7 @@ function addComponent(options) {
   return { path, contents, written: true, missingDependencies };
 }
 function missingFor(project) {
-  if (project.installed) return [];
-  switch (project.framework) {
-    case "nuxt":
-      return ["@ansh-ui/nuxt"];
-    case "vue":
-      return ["@ansh-ui/vue", "@ansh-ui/tokens"];
-    default:
-      return ["@ansh-ui/react", "@ansh-ui/tokens"];
-  }
+  return project.installed ? [] : packagesFor(project.framework);
 }
 function literal(value) {
   if (typeof value === "string") return JSON.stringify(value);
@@ -394,6 +409,242 @@ ${accentLines}
   }
   return { css, unsafeOnLight, unsafeOnDark, nearestStep };
 }
+function initProject(options = {}) {
+  const project = detectProject(options.cwd);
+  if (project.framework === "unknown") {
+    throw new Error(
+      "Could not detect a React, Next, Vue or Nuxt project. Run this from your project root, or install the framework first."
+    );
+  }
+  const configPath = join(project.root, CONFIG_FILE);
+  if (existsSync(configPath) && !options.force) {
+    throw new Error(`${CONFIG_FILE} already exists. Pass --force to overwrite it.`);
+  }
+  const themeRelative = options.brand ? join(stylesDir(project), "ansh-theme.css") : null;
+  const themePath = themeRelative ? join(project.root, themeRelative) : null;
+  if (themePath && existsSync(themePath) && !options.force) {
+    throw new Error(`${themePath} already exists. Pass --force to overwrite it.`);
+  }
+  const config = {
+    framework: project.framework,
+    typescript: project.typescript,
+    componentsDir: options.componentsDir ?? project.componentsDir,
+    alias: project.alias,
+    theme: themeRelative
+  };
+  const written = [];
+  if (!options.dryRun) {
+    if (options.brand && themePath) {
+      generateTheme({ color: options.brand, out: themePath });
+      written.push(themePath);
+    }
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+    written.push(configPath);
+  } else if (options.brand) {
+    generateTheme({ color: options.brand });
+  }
+  return {
+    project,
+    config,
+    written,
+    install: project.installed ? null : installCommand(project, packagesFor(project.framework)),
+    setup: setupFor(project, themeRelative)
+  };
+}
+function stylesDir(project) {
+  if (project.framework === "nuxt") return "assets/css";
+  return existsSync(join(project.root, "src")) ? "src/styles" : "styles";
+}
+function setupFor(project, theme) {
+  if (project.framework === "nuxt") {
+    const css = ["'@ansh-ui/vue/styles.css'", ...theme ? [`'~/${theme}'`] : []].join(", ");
+    return {
+      file: "nuxt.config.ts",
+      code: `export default defineNuxtConfig({
+  modules: ['@ansh-ui/nuxt'],
+  css: [${css}],
+})`
+    };
+  }
+  const binding = project.framework === "vue" ? "vue" : "react";
+  const entry = project.framework === "next" ? existsSync(join(project.root, "src/app")) ? "src/app/layout.tsx" : "app/layout.tsx" : project.framework === "vue" ? `src/main.${project.typescript ? "ts" : "js"}` : `src/main.${project.typescript ? "tsx" : "jsx"}`;
+  const themeImport = theme ? `
+import '${themeImportPath(project, entry, theme)}'` : "";
+  return {
+    file: entry,
+    code: `import '@ansh-ui/tokens/ansh.css'
+import '@ansh-ui/${binding}/styles.css'${themeImport}`
+  };
+}
+function themeImportPath(project, entry, theme) {
+  const path = relative(join(project.root, entry, ".."), join(project.root, theme));
+  return path.startsWith(".") ? path : `./${path}`;
+}
+var PROTOCOL_VERSION = "2025-06-18";
+var str = (value) => typeof value === "string" ? value : void 0;
+var TOOLS = [
+  {
+    name: "ansh_list",
+    description: "List Ansh canvas effects and DOM behaviours with their component names and option counts.",
+    inputSchema: {
+      type: "object",
+      properties: { kind: { type: "string", enum: ["effect", "behaviour"] } }
+    },
+    run: (args) => {
+      const kind = args.kind === "effect" || args.kind === "behaviour" ? args.kind : void 0;
+      const entries = listCatalogue(kind).map(({ name, kind: kind2, component, options }) => ({
+        name,
+        kind: kind2,
+        component,
+        options: options.length
+      }));
+      return JSON.stringify(entries, null, 2);
+    }
+  },
+  {
+    name: "ansh_info",
+    description: "Every option of one Ansh effect or behaviour, with its default value. Accepts the catalogue name (aurora) or component name (AuroraBackground).",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"]
+    },
+    run: (args) => {
+      const entry = findEntry(str(args.name) ?? "");
+      if (!entry) throw new Error(`Unknown component "${String(args.name)}". Call ansh_list.`);
+      return JSON.stringify(entry, null, 2);
+    }
+  },
+  {
+    name: "ansh_setup",
+    description: "How to set up Ansh in the current project: detected framework, install command, and the imports or nuxt.config lines to add. Pass write: true to also create ansh.config.json (and a theme file when brand is given).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        brand: { type: "string", description: "Brand colour for a generated theme, e.g. #0275f4" },
+        write: { type: "boolean", default: false }
+      }
+    },
+    run: (args, cwd) => {
+      const result = initProject({ cwd, brand: str(args.brand), dryRun: args.write !== true });
+      return JSON.stringify(
+        {
+          framework: result.config.framework,
+          install: result.install,
+          setupFile: result.setup.file,
+          setupCode: result.setup.code,
+          config: result.config,
+          written: result.written
+        },
+        null,
+        2
+      );
+    }
+  },
+  {
+    name: "ansh_add",
+    description: "Generate a typed, project-local wrapper component around an Ansh effect or behaviour, with the project\u2019s defaults. Returns the file path and contents; pass write: true to write the file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        as: { type: "string", description: "Local component name, e.g. HeroBackground" },
+        write: { type: "boolean", default: false }
+      },
+      required: ["name"]
+    },
+    run: (args, cwd) => {
+      const result = addComponent({
+        cwd,
+        name: str(args.name) ?? "",
+        as: str(args.as),
+        dryRun: args.write !== true
+      });
+      return JSON.stringify(result, null, 2);
+    }
+  },
+  {
+    name: "ansh_theme",
+    description: "Generate an Ansh token override stylesheet from a brand colour, with WCAG contrast notes for each step.",
+    inputSchema: {
+      type: "object",
+      properties: { color: { type: "string" }, withAccent: { type: "boolean", default: false } },
+      required: ["color"]
+    },
+    run: (args) => {
+      const report = generateTheme({
+        color: str(args.color) ?? "",
+        withAccent: args.withAccent === true
+      });
+      return JSON.stringify(report, null, 2);
+    }
+  }
+];
+function callTool(params, cwd) {
+  const tool = TOOLS.find((t) => t.name === params?.name);
+  if (!tool)
+    return {
+      content: [{ type: "text", text: `Unknown tool "${String(params?.name)}".` }],
+      isError: true
+    };
+  const args = params?.arguments ?? {};
+  try {
+    return { content: [{ type: "text", text: tool.run(args, cwd) }] };
+  } catch (error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text }], isError: true };
+  }
+}
+function handleMessage(message, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const reply = (result) => ({ jsonrpc: "2.0", id: message.id ?? null, result });
+  if (message.id === void 0) return null;
+  switch (message.method) {
+    case "initialize":
+      return reply({
+        protocolVersion: str(message.params?.protocolVersion) ?? PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "ansh", version: options.version },
+        instructions: "Ansh is a UI and animation library for React, Next.js, Vue and Nuxt. Call ansh_setup before writing Ansh code in a project, and ansh_info for an effect\u2019s exact options."
+      });
+    case "ping":
+      return reply({});
+    case "tools/list":
+      return reply({
+        tools: TOOLS.map(({ name, description, inputSchema }) => ({
+          name,
+          description,
+          inputSchema
+        }))
+      });
+    case "tools/call":
+      return reply(callTool(message.params, cwd));
+    default:
+      return {
+        jsonrpc: "2.0",
+        id: message.id,
+        error: { code: -32601, message: `Method not found: ${message.method}` }
+      };
+  }
+}
+function serveMcp(version, input = process.stdin, output = process.stdout) {
+  const send = (payload) => output.write(`${JSON.stringify(payload)}
+`);
+  createInterface({ input }).on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+      return;
+    }
+    const response = handleMessage(message, { version });
+    if (response) send(response);
+  });
+  console.error(`ansh mcp v${version} ready on stdio`);
+}
 
 // src/cli.ts
 var useColor = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -413,14 +664,19 @@ ${bold("USAGE")}
   ansh <command> [options]
 
 ${bold("COMMANDS")}
+  ${cyan("init")} [--brand <color>]            Set up Ansh in this project
   ${cyan("list")} [--effects|--behaviours]     List the component catalogue
   ${cyan("info")} <name>                       Show a component's full option surface
   ${cyan("add")} <name> [--as <Name>]          Generate a local wrapper component
   ${cyan("theme")} <color> [--out <file>]      Generate a token override stylesheet
   ${cyan("palette")} [colors...]               Generate or inspect a palette
   ${cyan("doctor")}                            Report the detected project setup
+  ${cyan("mcp")}                               Run as an MCP server for AI coding agents
 
 ${bold("EXAMPLES")}
+  ${dim("# Set up a project, with a theme from your brand colour")}
+  ansh init --brand '#0275f4'
+
   ${dim("# See what is available")}
   ansh list
 
@@ -442,6 +698,41 @@ function fail(message, hint) {
   if (hint) console.error(`${dim("hint")}   ${hint}`);
   process.exit(1);
 }
+function commandInit(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      brand: { type: "string" },
+      dir: { type: "string" },
+      force: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false }
+    }
+  });
+  try {
+    const result = initProject({
+      brand: values.brand,
+      componentsDir: values.dir,
+      force: values.force,
+      dryRun: values["dry-run"]
+    });
+    console.log(`
+${bold("ansh init")}  ${dim(`${result.config.framework} project detected`)}
+`);
+    for (const path of result.written) console.log(`${green("created")}  ${path}`);
+    if (result.install) console.log(`
+${yellow("1")}  Install:
+   ${result.install}`);
+    console.log(`
+${yellow(result.install ? "2" : "1")}  Add to ${result.setup.file}:
+`);
+    console.log(result.setup.code.replace(/^/gm, "   "));
+    console.log(`
+${dim(`Then try: ansh add aurora --as HeroBackground`)}
+`);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
 function commandList(argv) {
   const { values } = parseArgs({
     args: argv,
@@ -645,9 +936,8 @@ ${bold("PROJECT")}
   console.log(`  import alias    ${project.alias ?? dim("none")}`);
   console.log(`  ansh         ${project.installed ? green("installed") : yellow("not installed")}`);
   if (!project.installed) {
-    const packages = project.framework === "nuxt" ? ["@ansh-ui/nuxt"] : project.framework === "vue" ? ["@ansh-ui/vue", "@ansh-ui/tokens"] : ["@ansh-ui/react", "@ansh-ui/tokens"];
     console.log(`
-${yellow("next")}  ${installCommand(project, packages)}
+${yellow("next")}  ${installCommand(project, packagesFor(project.framework))}
 `);
   } else {
     console.log("");
@@ -673,6 +963,8 @@ function swatch(hex) {
 function main() {
   const [command, ...rest] = process.argv.slice(2);
   switch (command) {
+    case "init":
+      return commandInit(rest);
     case "list":
     case "ls":
       return commandList(rest);
@@ -687,6 +979,8 @@ function main() {
       return commandPalette(rest);
     case "doctor":
       return commandDoctor();
+    case "mcp":
+      return serveMcp(VERSION);
     case "--version":
     case "-v":
       console.log(VERSION);