holycodex 0.2.1

package/plugin/skills/frontend/references/ui-ux-db/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography, google-fonts
+Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, nuxtjs, nuxt-ui, html-tailwind, shadcn, jetpack-compose, threejs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+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')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max 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['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)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help=f"Stack-specific search. Available: {', '.join(AVAILABLE_STACKS)}")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/plugin/skills/handoff/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: handoff
+description: Compact conversation state into a safe resumable handoff. Use when asked to hand off, save context, or prepare another agent/session to continue.
+---
+
+# Handoff
+
+Write handoff to OS temp directory, never workspace. Tailor it to any user-provided next-session focus.
+
+Include current objective, completed work, state, key decisions, blockers, next steps, verification, and suggested skills. Reference existing specs, plans, ADRs, issues, commits, and diffs by path or URL instead of duplicating them. Redact secrets, credentials, and personal data.

package/plugin/skills/lsp/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: lsp
+description: Use when Codex needs language-server diagnostics, definitions, references, symbols, or rename safety checks in the current workspace.
+---
+
+# Codex LSP
+
+Call `lsp` MCP tools through the tool interface; `lsp.*`/`mcp__lsp__*` are tool-call names, not shell commands.
+
+## Tools
+
+- `lsp.status`: list configured, installed, missing, disabled, and active language servers.
+- `lsp.diagnostics`: check one file or directory for LSP diagnostics. Prefer `severity: "error"` after edits.
+- `lsp.goto_definition`: locate a symbol definition from file, line, and character.
+- `lsp.find_references`: find usages of a symbol across the workspace.
+- `lsp.symbols`: inspect document symbols or search workspace symbols.
+- `lsp.prepare_rename`: check whether a rename is valid at a position.
+- `lsp.rename`: apply a language-server workspace edit for a rename.
+
+## Config
+
+Project config lives at `.codex/lsp-client.json`; user config lives at `~/.codex/lsp-client.json`.
+
+```json
+{
+  "lsp": {
+    "typescript": {
+      "command": ["typescript-language-server", "--stdio"],
+      "extensions": [".ts", ".tsx", ".js", ".jsx"]
+    }
+  }
+}
+```
+
+Use `lsp.status` first when diagnostics report a missing language server.

package/plugin/skills/lsp-setup/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: lsp-setup
+description: Configure and verify one language server. Use when semantic tooling is missing, unconfigured, or reports that its server is not installed.
+---
+
+# LSP Setup
+
+Use when user asks setup/install/configure, or required server is missing. Do not install silently.
+
+1. Detect language, project root, package manager, existing server, and current `.codex/lsp-client.json` or project setting.
+2. Run `scripts/detect-lsp.ts` or inspect `scripts/lsp-server-table.ts` for matching server, command, extensions, and install hint.
+3. Prefer project-local maintained server. Preserve existing config.
+4. If install changes machine or network state, ask unless user already authorized setup.
+5. Add smallest config entry: command, args, extensions, root markers only when needed.
+6. Verify executable, start server, run diagnostics on one representative file.
+7. Report server, version, config path, verification result.
+
+No duplicate server for same extension without explicit priority. No global install when project-local works. No broad editor configuration changes.

package/plugin/skills/lsp-setup/scripts/detect-lsp.ts

@@ -0,0 +1,233 @@
+#!/usr/bin/env bun
+// detect-lsp.ts <targetDir> [--json] — scan a directory for source languages and
+// report, per detected language: the builtin LSP server, whether its executable
+// is on PATH, an install hint, and whether a project LSP config references it.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { delimiter, extname, join, sep } from "node:path";
+import process from "node:process";
+
+import { LANGUAGES, type LanguageServer, PROJECT_CONFIG_FILES } from "./lsp-server-table";
+
+const SKIP_DIRECTORIES = new Set<string>([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "out",
+  "target",
+  ".venv",
+  "venv",
+  "vendor",
+  ".cache",
+  "__pycache__",
+  ".turbo",
+  "coverage",
+]);
+
+const MAX_FILES = 50_000;
+
+// Mirrors effectiveExtension() in packages/lsp-tools-mcp/src/lsp/effective-extension.ts:
+// extensionless Dockerfile/Containerfile resolve to .dockerfile (exact-case basenames).
+const BASENAME_EXTENSIONS: Record<string, string> = {
+  Dockerfile: ".dockerfile",
+  Containerfile: ".dockerfile",
+};
+
+interface ConfigFileState {
+  readonly path: string;
+  readonly exists: boolean;
+  readonly serverIds: readonly string[];
+}
+
+interface DetectionResult {
+  readonly server: LanguageServer;
+  readonly executable: string;
+  readonly installed: boolean;
+  readonly resolvedPath: string | null;
+  readonly configuredIn: readonly string[];
+}
+
+function collectExtensions(root: string): ReadonlySet<string> {
+  const found = new Set<string>();
+  const stack: string[] = [root];
+  let visited = 0;
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === undefined) break;
+
+    let entries: string[];
+    try {
+      entries = readdirSync(current);
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (visited >= MAX_FILES) return found;
+      const fullPath = join(current, entry);
+
+      let kind: "dir" | "file" | "other" = "other";
+      try {
+        const stat = statSync(fullPath);
+        kind = stat.isDirectory() ? "dir" : stat.isFile() ? "file" : "other";
+      } catch {
+        continue;
+      }
+
+      if (kind === "dir") {
+        if (!SKIP_DIRECTORIES.has(entry)) stack.push(fullPath);
+      } else if (kind === "file") {
+        visited += 1;
+        const ext = (BASENAME_EXTENSIONS[entry] ?? extname(entry)).toLowerCase();
+        if (ext.length > 0) found.add(ext);
+      }
+    }
+  }
+
+  return found;
+}
+
+function pathDirectories(): readonly string[] {
+  return (process.env["PATH"] ?? "").split(delimiter).filter((dir: string) => dir.length > 0);
+}
+
+function resolveExecutable(command: string): string | null {
+  const extensions =
+    process.platform === "win32"
+      ? (process.env["PATHEXT"]?.split(";") ?? [".EXE", ".CMD", ".BAT"])
+      : [""];
+  const bases =
+    command.includes("/") || command.includes(sep)
+      ? [command]
+      : pathDirectories().map((dir: string) => join(dir, command));
+
+  for (const base of bases) {
+    for (const ext of extensions) {
+      const candidate = ext.length > 0 ? `${base}${ext}` : base;
+      try {
+        if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseConfiguredServerIds(path: string): readonly string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return [];
+  }
+  if (!isRecord(parsed)) return [];
+  const lsp = parsed["lsp"];
+  return isRecord(lsp) ? Object.keys(lsp) : [];
+}
+
+function readConfigState(root: string): readonly ConfigFileState[] {
+  return PROJECT_CONFIG_FILES.map((relative: string): ConfigFileState => {
+    const path = join(root, relative);
+    if (!existsSync(path)) return { path: relative, exists: false, serverIds: [] };
+    return { path: relative, exists: true, serverIds: parseConfiguredServerIds(path) };
+  });
+}
+
+function detect(root: string, configState: readonly ConfigFileState[]): readonly DetectionResult[] {
+  const extensions = collectExtensions(root);
+  const results: DetectionResult[] = [];
+
+  for (const server of LANGUAGES) {
+    if (!server.extensions.some((ext: string) => extensions.has(ext))) continue;
+
+    const executable = server.command[0] ?? server.serverId;
+    const resolvedPath = resolveExecutable(executable);
+    const configuredIn = configState
+      .filter((state) => state.serverIds.includes(server.serverId))
+      .map((state) => state.path);
+
+    results.push({
+      server,
+      executable,
+      installed: resolvedPath !== null,
+      resolvedPath,
+      configuredIn,
+    });
+  }
+
+  return results;
+}
+
+function renderReport(
+  root: string,
+  results: readonly DetectionResult[],
+  configState: readonly ConfigFileState[],
+): string {
+  const lines: string[] = [`LSP setup scan: ${root}`];
+  const configSummary = configState
+    .map(
+      (state) =>
+        `${state.path} (${state.exists ? `present: ${state.serverIds.length} server(s)` : "absent"})`,
+    )
+    .join(", ");
+  lines.push(`Config files: ${configSummary}`, "");
+
+  if (results.length === 0) {
+    lines.push("No languages with a builtin LSP server were detected here.");
+    return lines.join("\n");
+  }
+
+  lines.push("DETECTED LANGUAGES (primary builtin server per language)");
+  for (const result of results) {
+    const mark = result.installed ? "OK  " : "MISS";
+    const state = result.installed ? `installed (${result.resolvedPath})` : "NOT installed";
+    const config =
+      result.configuredIn.length > 0
+        ? `configured in ${result.configuredIn.join(", ")}`
+        : "builtin-default";
+    lines.push(
+      `[${mark}] ${result.server.language.padEnd(12)} server=${result.server.serverId}  exe=${result.executable}  ${state}  ${config}`,
+    );
+    if (!result.installed) lines.push(`        install: ${result.server.installHint}`);
+  }
+
+  const missing = results.filter((result) => !result.installed);
+  lines.push(
+    "",
+    missing.length === 0
+      ? `All ${results.length} detected server(s) installed.`
+      : `${missing.length}/${results.length} server(s) NOT installed: ${missing.map((m) => m.server.language).join(", ")}`,
+    "Next: read references/<language>/README.md, then configure .codex/lsp-client.json AND .codex/lsp.json.",
+  );
+  return lines.join("\n");
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  const wantsJson = args.includes("--json");
+  const root = args.find((arg: string) => !arg.startsWith("--")) ?? process.cwd();
+
+  if (!existsSync(root)) {
+    process.stderr.write(`detect-lsp: target directory does not exist: ${root}\n`);
+    process.exit(2);
+  }
+
+  const configState = readConfigState(root);
+  const results = detect(root, configState);
+
+  if (wantsJson) {
+    process.stdout.write(`${JSON.stringify({ root, configState, results }, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(`${renderReport(root, results, configState)}\n`);
+}
+
+main();

package/plugin/skills/lsp-setup/scripts/lsp-server-table.ts

@@ -0,0 +1,188 @@
+// SOURCE OF TRUTH: packages/lsp-tools-mcp/src/lsp/server-definitions.ts
+// (BUILTIN_SERVERS + LSP_INSTALL_HINTS). This is a hand-maintained snapshot of
+// the primary builtin server per reference language, embedded so detect-lsp.ts
+// runs standalone in any user project. Mirror command/extensions when that file
+// changes.
+
+export interface LanguageServer {
+  readonly language: string;
+  readonly serverId: string;
+  readonly command: readonly string[];
+  readonly extensions: readonly string[];
+  readonly installHint: string;
+}
+
+export const LANGUAGES: readonly LanguageServer[] = [
+  {
+    language: "typescript",
+    serverId: "typescript",
+    command: ["typescript-language-server", "--stdio"],
+    extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"],
+    installHint: "npm install -g typescript-language-server typescript",
+  },
+  {
+    language: "python",
+    serverId: "basedpyright",
+    command: ["basedpyright-langserver", "--stdio"],
+    extensions: [".py", ".pyi"],
+    installHint: "pip install basedpyright (or: uv tool install basedpyright)",
+  },
+  {
+    language: "go",
+    serverId: "gopls",
+    command: ["gopls"],
+    extensions: [".go"],
+    installHint: "go install golang.org/x/tools/gopls@latest",
+  },
+  {
+    language: "rust",
+    serverId: "rust",
+    command: ["rust-analyzer"],
+    extensions: [".rs"],
+    installHint: "rustup component add rust-analyzer",
+  },
+  {
+    language: "c-cpp",
+    serverId: "clangd",
+    command: ["clangd", "--background-index", "--clang-tidy"],
+    extensions: [".c", ".cpp", ".cc", ".cxx", ".c++", ".h", ".hpp", ".hh", ".hxx", ".h++"],
+    installHint:
+      "macOS: brew install llvm | Linux: apt install clangd | https://clangd.llvm.org/installation",
+  },
+  {
+    language: "java",
+    serverId: "jdtls",
+    command: ["jdtls"],
+    extensions: [".java"],
+    installHint: "macOS: brew install jdtls | https://github.com/eclipse-jdtls/eclipse.jdt.ls",
+  },
+  {
+    language: "kotlin",
+    serverId: "kotlin-ls",
+    command: ["kotlin-lsp"],
+    extensions: [".kt", ".kts"],
+    installHint: "https://github.com/Kotlin/kotlin-lsp",
+  },
+  {
+    language: "csharp",
+    serverId: "csharp",
+    command: ["csharp-ls"],
+    extensions: [".cs"],
+    installHint: "dotnet tool install -g csharp-ls",
+  },
+  {
+    language: "razor",
+    serverId: "razor",
+    command: ["roslyn-language-server", "--stdio"],
+    extensions: [".razor", ".cshtml"],
+    installHint:
+      "dotnet tool install -g roslyn-language-server --prerelease (see references/csharp/README.md)",
+  },
+  {
+    language: "swift",
+    serverId: "sourcekit-lsp",
+    command: ["sourcekit-lsp"],
+    extensions: [".swift", ".objc", ".objcpp"],
+    installHint: "Included with Xcode (xcode-select --install) or the Swift toolchain",
+  },
+  {
+    language: "ruby",
+    serverId: "ruby-lsp",
+    command: ["rubocop", "--lsp"],
+    extensions: [".rb", ".rake", ".gemspec", ".ru"],
+    installHint: "gem install ruby-lsp (builtin runs `rubocop --lsp`; gem install rubocop)",
+  },
+  {
+    language: "php",
+    serverId: "php",
+    command: ["intelephense", "--stdio"],
+    extensions: [".php"],
+    installHint: "npm install -g intelephense",
+  },
+  {
+    language: "dart",
+    serverId: "dart",
+    command: ["dart", "language-server", "--lsp"],
+    extensions: [".dart"],
+    installHint: "Included with the Dart/Flutter SDK",
+  },
+  {
+    language: "elixir",
+    serverId: "elixir-ls",
+    command: ["elixir-ls"],
+    extensions: [".ex", ".exs"],
+    installHint: "https://github.com/elixir-lsp/elixir-ls",
+  },
+  {
+    language: "zig",
+    serverId: "zls",
+    command: ["zls"],
+    extensions: [".zig", ".zon"],
+    installHint: "https://github.com/zigtools/zls (match zls version to your zig version)",
+  },
+  {
+    language: "lua",
+    serverId: "lua-ls",
+    command: ["lua-language-server"],
+    extensions: [".lua"],
+    installHint:
+      "macOS: brew install lua-language-server | https://github.com/LuaLS/lua-language-server",
+  },
+  {
+    language: "bash",
+    serverId: "bash",
+    command: ["bash-language-server", "start"],
+    extensions: [".sh", ".bash", ".zsh", ".ksh"],
+    installHint: "npm install -g bash-language-server",
+  },
+  {
+    language: "yaml",
+    serverId: "yaml-ls",
+    command: ["yaml-language-server", "--stdio"],
+    extensions: [".yaml", ".yml"],
+    installHint: "npm install -g yaml-language-server",
+  },
+  {
+    language: "terraform",
+    serverId: "terraform",
+    command: ["terraform-ls", "serve"],
+    extensions: [".tf", ".tfvars"],
+    installHint:
+      "macOS: brew install hashicorp/tap/terraform-ls | https://github.com/hashicorp/terraform-ls",
+  },
+  {
+    language: "dockerfile",
+    serverId: "dockerfile",
+    command: ["docker-langserver", "--stdio"],
+    extensions: [".dockerfile"],
+    installHint: "npm install -g dockerfile-language-server-nodejs",
+  },
+  {
+    language: "haskell",
+    serverId: "haskell-language-server",
+    command: ["haskell-language-server-wrapper", "--lsp"],
+    extensions: [".hs", ".lhs"],
+    installHint: "ghcup install hls",
+  },
+  {
+    language: "julia",
+    serverId: "julials",
+    command: [
+      "julia",
+      "--startup-file=no",
+      "--history-file=no",
+      "-e",
+      "using LanguageServer; runserver()",
+    ],
+    extensions: [".jl"],
+    installHint:
+      "julia -e 'using Pkg; Pkg.add(\"LanguageServer\")' (see references/julia/README.md)",
+  },
+] as const;
+
+export const PROJECT_CONFIG_FILES: readonly string[] = [
+  ".codex/lsp-client.json",
+  ".codex/lsp.json",
+  ".codex/lsp.json",
+  ".codex/lsp-client.json",
+] as const;

package/plugin/skills/lsp-setup/scripts/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "lib": ["ESNext"],
+    "types": ["bun-types"]
+  },
+  "include": ["*.ts"]
+}