lokuma-cli 1.0.0

package/README.md

@@ -0,0 +1,64 @@
+# lokuma-cli
+
+Install [Lokuma](https://lokuma.io) design intelligence skill for AI coding assistants.
+
+## Quick Start
+
+```bash
+npx lokuma-cli init --ai claude
+```
+
+## Supported AI Assistants
+
+| Flag | Assistant |
+|------|-----------|
+| `--ai claude` | Claude Code |
+| `--ai cursor` | Cursor |
+| `--ai windsurf` | Windsurf |
+| `--ai copilot` | GitHub Copilot |
+| `--ai kiro` | Kiro |
+| `--ai roocode` | Roo Code |
+| `--ai codex` | Codex CLI |
+| `--ai qoder` | Qoder |
+| `--ai gemini` | Gemini CLI |
+| `--ai trae` | Trae |
+| `--ai opencode` | OpenCode |
+| `--ai continue` | Continue |
+| `--ai codebuddy` | CodeBuddy |
+| `--ai droid` | Droid (Factory) |
+| `--ai all` | All assistants |
+
+## Configuration
+
+After installing, set your API key:
+
+```bash
+export LOKUMA_API_KEY=lokuma_your_key_here
+```
+
+Get your API key at [lokuma.io](https://lokuma.io).
+
+## Options
+
+```
+lokuma init [options]
+
+Options:
+  -a, --ai <type>   AI assistant type
+  -f, --force       Overwrite existing files
+  -h, --help        Show help
+  -V, --version     Show version
+```
+
+## How It Works
+
+`lokuma-cli` installs two files into your project:
+
+1. **SKILL.md** — tells your AI assistant how to use Lokuma
+2. **search.py** — a lightweight cloud client that calls the Lokuma API
+
+No local data files. No Python dependencies. Just set your API key and go.
+
+## License
+
+MIT

package/assets/search.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Lokuma Search - Cloud Client
+Calls the Lokuma cloud API to generate design intelligence.
+
+Usage:
+  python search.py "<query>" [--domain <domain>] [--max-results 3]
+  python search.py "<query>" --stack <stack>
+  python search.py "<query>" --design-system [-p "Project Name"] [-f ascii|markdown|json]
+
+Configuration:
+  Set LOKUMA_API_KEY environment variable (required):
+    export LOKUMA_API_KEY=lokuma_your_key_here
+
+  Optional overrides:
+    LOKUMA_API_URL=https://custom.endpoint.com   (default: official API)
+
+Domains: style, color, chart, landing, product, ux, typography, google-fonts,
+         icons, react, web
+Stacks: react-native
+"""
+
+import argparse
+import json
+import os
+import sys
+import io
+import urllib.request
+import urllib.error
+from typing import Optional
+
+# Force UTF-8 output on Windows
+if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
+if sys.stderr.encoding and sys.stderr.encoding.lower() != "utf-8":
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8")
+
+
+# ─────────────────────────────────────────────
+# Config
+# ─────────────────────────────────────────────
+
+API_BASE = os.environ.get("LOKUMA_API_URL", "https://api.lokuma.io").rstrip("/")
+API_VERSION = "v1"
+_BASE = f"{API_BASE}/{API_VERSION}"
+
+
+def _get_api_key() -> str:
+    key = os.environ.get("LOKUMA_API_KEY", "").strip()
+    if not key:
+        print(
+            "Error: LOKUMA_API_KEY is not set.\n"
+            "Set it with:  export LOKUMA_API_KEY=lokuma_your_key_here",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return key
+
+
+# ─────────────────────────────────────────────
+# HTTP client (stdlib only, zero deps)
+# ─────────────────────────────────────────────
+
+def _post(endpoint: str, payload: dict) -> dict:
+    """POST JSON payload to API endpoint, return parsed response."""
+    api_key = _get_api_key()
+    url = f"{_BASE}/{endpoint}"
+    data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "X-API-Key": api_key,
+            "User-Agent": "lokuma-skill/1.0",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            body = resp.read().decode("utf-8")
+            return json.loads(body)
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        try:
+            err = json.loads(body)
+            msg = err.get("error", body)
+        except Exception:
+            msg = body
+        if e.code == 401 or e.code == 403:
+            print(f"Error: Invalid or expired API key (HTTP {e.code})", file=sys.stderr)
+        else:
+            print(f"Error: API returned HTTP {e.code}: {msg}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        print(f"Error: Could not reach API at {url}: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON response from API: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+# ─────────────────────────────────────────────
+# API wrappers
+# ─────────────────────────────────────────────
+
+def search(query: str, domain: Optional[str] = None, max_results: int = 3) -> dict:
+    payload = {"query": query, "max_results": max_results}
+    if domain:
+        payload["domain"] = domain
+    return _post("search", payload)
+
+
+def search_stack(query: str, stack: str, max_results: int = 3) -> dict:
+    return _post("search/stack", {"query": query, "stack": stack, "max_results": max_results})
+
+
+def design_system(query: str, project_name: Optional[str] = None, fmt: str = "ascii") -> dict:
+    payload = {"query": query, "format": fmt}
+    if project_name:
+        payload["project_name"] = project_name
+    return _post("design-system", payload)
+
+
+# ─────────────────────────────────────────────
+# Output formatting (mirrors original search.py)
+# ─────────────────────────────────────────────
+
+def format_search_output(result: dict) -> str:
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append("## Lokuma Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append("## Lokuma Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result.get("results", []), 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+# ─────────────────────────────────────────────
+# CLI
+# ─────────────────────────────────────────────
+
+VALID_DOMAINS = [
+    "style", "color", "chart", "landing", "product", "ux",
+    "typography", "google-fonts", "icons", "react", "web",
+]
+VALID_STACKS = ["react-native"]
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Lokuma Cloud Search",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=VALID_DOMAINS, help="Search domain")
+    parser.add_argument("--stack", "-s", choices=VALID_STACKS, help="Stack-specific search")
+    parser.add_argument("--max-results", "-n", type=int, default=3, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    # Design system flags
+    parser.add_argument("--design-system", "-ds", action="store_true",
+                        help="Generate complete design system")
+    parser.add_argument("--project-name", "-p", type=str, default=None,
+                        help="Project name for design system header")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown", "json"],
+                        default="ascii", help="Output format for design system")
+
+    args = parser.parse_args()
+
+    # ── Design system ──
+    if args.design_system:
+        fmt = args.format
+        result = design_system(args.query, args.project_name, fmt)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        elif fmt == "json":
+            # Pretty-print the nested design_system dict
+            ds = result.get("design_system", result)
+            print(json.dumps(ds, indent=2, ensure_ascii=False))
+        else:
+            print(result.get("output", ""))
+        return
+
+    # ── Stack search ──
+    if args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_search_output(result))
+        return
+
+    # ── Domain search ──
+    result = search(args.query, args.domain, args.max_results)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(format_search_output(result))
+
+
+if __name__ == "__main__":
+    main()

package/dist/index.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import { readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2, join as join2 } from "path";
+
+// src/commands/init.ts
+import { mkdir, writeFile, access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import ora from "ora";
+import prompts from "prompts";
+
+// src/types/index.ts
+var AI_TYPES = [
+  "claude",
+  "cursor",
+  "windsurf",
+  "copilot",
+  "kiro",
+  "roocode",
+  "codex",
+  "qoder",
+  "gemini",
+  "trae",
+  "opencode",
+  "continue",
+  "codebuddy",
+  "droid",
+  "all"
+];
+var AI_DISPLAY_NAMES = {
+  claude: "Claude Code",
+  cursor: "Cursor",
+  windsurf: "Windsurf",
+  copilot: "GitHub Copilot",
+  kiro: "Kiro",
+  roocode: "Roo Code",
+  codex: "Codex CLI",
+  qoder: "Qoder",
+  gemini: "Gemini CLI",
+  trae: "Trae",
+  opencode: "OpenCode",
+  continue: "Continue",
+  codebuddy: "CodeBuddy",
+  droid: "Droid (Factory)",
+  all: "All assistants"
+};
+var AI_SKILL_PATHS = {
+  claude: { root: ".claude", skillMd: ".claude/skills/lokuma/SKILL.md", scriptPy: ".claude/skills/lokuma/scripts/search.py" },
+  cursor: { root: ".cursor", skillMd: ".cursor/rules/lokuma.mdc", scriptPy: ".cursor/rules/lokuma/scripts/search.py" },
+  windsurf: { root: ".windsurf", skillMd: ".windsurf/rules/lokuma.md", scriptPy: ".windsurf/rules/lokuma/scripts/search.py" },
+  copilot: { root: ".github", skillMd: ".github/instructions/lokuma.instructions.md", scriptPy: ".github/instructions/lokuma/scripts/search.py" },
+  kiro: { root: ".kiro", skillMd: ".kiro/steering/lokuma.md", scriptPy: ".kiro/steering/lokuma/scripts/search.py" },
+  roocode: { root: ".roo", skillMd: ".roo/rules/lokuma.md", scriptPy: ".roo/rules/lokuma/scripts/search.py" },
+  codex: { root: ".codex", skillMd: ".codex/instructions.md", scriptPy: ".codex/lokuma/scripts/search.py" },
+  qoder: { root: ".qoder", skillMd: ".qoder/rules/lokuma.md", scriptPy: ".qoder/rules/lokuma/scripts/search.py" },
+  gemini: { root: ".gemini", skillMd: ".gemini/GEMINI.md", scriptPy: ".gemini/lokuma/scripts/search.py" },
+  trae: { root: ".trae", skillMd: ".trae/rules/lokuma.md", scriptPy: ".trae/rules/lokuma/scripts/search.py" },
+  opencode: { root: ".opencode", skillMd: ".opencode/OPENCODE.md", scriptPy: ".opencode/lokuma/scripts/search.py" },
+  continue: { root: ".continue", skillMd: ".continue/lokuma/SKILL.md", scriptPy: ".continue/lokuma/scripts/search.py" },
+  codebuddy: { root: ".codebuddy", skillMd: ".codebuddy/lokuma/SKILL.md", scriptPy: ".codebuddy/lokuma/scripts/search.py" },
+  droid: { root: ".factory", skillMd: ".factory/skills/lokuma/SKILL.md", scriptPy: ".factory/skills/lokuma/scripts/search.py" }
+};
+
+// src/commands/init.ts
+import { createRequire } from "node:module";
+var _require = createRequire(import.meta.url);
+var _pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+var SEARCH_PY = readFileSync(join(_pkgDir, "assets", "search.py"), "utf-8");
+function buildSkillMd(scriptPath) {
+  return `---
+name: lokuma
+description: Lokuma design intelligence. 67 UI styles, 161 color palettes, 57 font pairings, 25 chart types, 99 UX guidelines. Triggers: build, design, create, implement UI/UX. Projects: landing page, dashboard, SaaS, e-commerce, portfolio, mobile app. Styles: glassmorphism, minimalism, brutalism, neumorphism, bento grid, dark mode.
+---
+
+# Lokuma - Design Intelligence
+
+## Setup
+
+Set your API key (required):
+\`\`\`bash
+export LOKUMA_API_KEY=lokuma_your_key_here
+\`\`\`
+
+Get your API key at https://lokuma.io
+
+## Usage
+
+### Generate Design System (start here)
+\`\`\`bash
+python3 ${scriptPath} "<product description>" --design-system [-p "Project Name"]
+\`\`\`
+
+Example:
+\`\`\`bash
+python3 ${scriptPath} "beauty spa wellness" --design-system -p "Serenity Spa"
+\`\`\`
+
+### Domain Search
+\`\`\`bash
+python3 ${scriptPath} "<keyword>" --domain <domain>
+\`\`\`
+
+Domains: \`style\` \`color\` \`typography\` \`chart\` \`landing\` \`product\` \`ux\` \`icons\`
+
+### Stack Guidelines
+\`\`\`bash
+python3 ${scriptPath} "<keyword>" --stack react-native
+\`\`\`
+
+## Workflow
+
+1. **New project** \u2192 \`--design-system\` first to get full design system
+2. **Component** \u2192 \`--domain style\` or \`--domain ux\`
+3. **Colors/fonts** \u2192 \`--domain color\` or \`--domain typography\`
+4. **Review** \u2192 \`--domain ux\` for best practices
+`;
+}
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function initCommand(options) {
+  console.log(chalk.bold("\n  Lokuma Design Intelligence Installer\n"));
+  let aiType = options.ai;
+  if (!aiType) {
+    const res = await prompts({
+      type: "select",
+      name: "aiType",
+      message: "Select your AI coding assistant:",
+      choices: AI_TYPES.map((t) => ({ title: AI_DISPLAY_NAMES[t], value: t }))
+    });
+    if (!res.aiType) {
+      console.log(chalk.yellow("  Cancelled."));
+      return;
+    }
+    aiType = res.aiType;
+  }
+  const targets = aiType === "all" ? AI_TYPES.filter((t) => t !== "all") : [aiType];
+  const spinner = ora("Installing\u2026").start();
+  const installed = [];
+  try {
+    for (const t of targets) {
+      const paths = AI_SKILL_PATHS[t];
+      if (!options.force && await exists(paths.skillMd)) {
+        spinner.warn(`${AI_DISPLAY_NAMES[t]}: already installed (use --force to overwrite)`);
+        spinner.start();
+        continue;
+      }
+      await mkdir(dirname(paths.skillMd), { recursive: true });
+      await mkdir(dirname(paths.scriptPy), { recursive: true });
+      await writeFile(paths.skillMd, buildSkillMd(paths.scriptPy), "utf-8");
+      await writeFile(paths.scriptPy, SEARCH_PY, "utf-8");
+      installed.push(AI_DISPLAY_NAMES[t]);
+    }
+    spinner.succeed("Done!");
+    if (installed.length > 0) {
+      console.log();
+      installed.forEach((name) => console.log(chalk.green(`  \u2713 ${name}`)));
+    }
+    console.log();
+    console.log(chalk.bold("  Next steps:"));
+    console.log(chalk.dim("  1. Set your API key:"));
+    console.log(chalk.cyan("       export LOKUMA_API_KEY=lokuma_your_key_here"));
+    console.log(chalk.dim("  2. Get a key \u2192 https://lokuma.io"));
+    console.log(chalk.dim("  3. Restart your AI assistant"));
+    console.log(chalk.dim('  4. Try: "Build a landing page for a SaaS product"'));
+    console.log();
+  } catch (err) {
+    spinner.fail("Installation failed");
+    if (err instanceof Error) console.error(chalk.red(`  ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var __filename = fileURLToPath2(import.meta.url);
+var __dirname = dirname2(__filename);
+var pkg = JSON.parse(readFileSync2(join2(__dirname, "../package.json"), "utf-8"));
+var program = new Command();
+program.name("lokuma").description("Install Lokuma design intelligence skill for AI coding assistants").version(pkg.version);
+program.command("init").description("Install Lokuma skill to current project").option("-a, --ai <type>", `AI assistant type (${AI_TYPES.join(", ")})`).option("-f, --force", "Overwrite existing files").action(async (options) => {
+  if (options.ai && !AI_TYPES.includes(options.ai)) {
+    console.error(`Invalid AI type: ${options.ai}`);
+    console.error(`Valid types: ${AI_TYPES.join(", ")}`);
+    process.exit(1);
+  }
+  await initCommand({
+    ai: options.ai,
+    force: options.force
+  });
+});
+program.parse();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "lokuma-cli",
+  "version": "1.0.0",
+  "description": "CLI to install Lokuma design intelligence skill for AI coding assistants",
+  "type": "module",
+  "bin": {
+    "lokuma": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --format=esm --external:commander --external:chalk --external:ora --external:prompts",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "lokuma",
+    "ui",
+    "ux",
+    "design",
+    "claude",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "kiro",
+    "codex",
+    "ai",
+    "skill"
+  ],
+  "author": "s1non",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ora": "^8.1.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.14",
+    "@types/node": "^22.10.1",
+    "@types/prompts": "^2.4.9",
+    "esbuild": "^0.27.4",
+    "typescript": "^5.7.2"
+  }
+}