@a13xu/lucid 1.11.0 → 1.12.0

package/build/index.js

@@ -54,7 +54,7 @@ else {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "lucid", version: "1.11.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "lucid", version: "1.12.0" }, { capabilities: { tools: {} } });
 // ---------------------------------------------------------------------------
 // Tool definitions
 // ---------------------------------------------------------------------------

package/build/tools/init.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { resolve, join } from "path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { fileURLToPath } from "url";
 import { indexProject } from "../indexer/project.js";
 import { saveAdminConfig, loadAdminConfig, isAdminConfigured, sendTestAlert, } from "../security/alerts.js";
 export const InitProjectSchema = z.object({
@@ -118,6 +119,18 @@ export async function handleInitProject(stmts, input) {
     else {
         lines.push(`🔗 Hook: ${hookResult.reason}`);
     }
+    // ── Skills ────────────────────────────────────────────────────────────────
+    const skillsResult = installSkills(dir);
+    if (skillsResult.installed.length > 0) {
+        lines.push(`📚 Skills installed in .claude/skills/:`);
+        for (const s of skillsResult.installed) {
+            lines.push(`   • /${s}`);
+        }
+        lines.push(`   Invoke with /<skill-name> in Claude Code.`);
+    }
+    else if (skillsResult.skipped.length > 0) {
+        lines.push(`📚 Skills: already installed (${skillsResult.skipped.length} skill(s))`);
+    }
     // ── CLAUDE.md injection ───────────────────────────────────────────────────
     const injected = injectClaudeMdInstruction(dir);
     if (injected) {
@@ -200,6 +213,34 @@ export async function handleInitProject(stmts, input) {
     lines.push(`Use recall() to query accumulated project knowledge.`);
     return lines.join("\n");
 }
+// ---------------------------------------------------------------------------
+// Instalează Lucid skills în .claude/skills/ al proiectului
+// ---------------------------------------------------------------------------
+const PACKAGE_ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "../..");
+function installSkills(projectDir) {
+    const skillsSource = join(PACKAGE_ROOT, "skills");
+    const result = { installed: [], skipped: [] };
+    if (!existsSync(skillsSource))
+        return result;
+    const skillDirs = readdirSync(skillsSource, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    for (const skillName of skillDirs) {
+        const srcSkillMd = join(skillsSource, skillName, "SKILL.md");
+        if (!existsSync(srcSkillMd))
+            continue;
+        const destDir = join(projectDir, ".claude", "skills", skillName);
+        const destFile = join(destDir, "SKILL.md");
+        if (existsSync(destFile)) {
+            result.skipped.push(skillName);
+            continue;
+        }
+        mkdirSync(destDir, { recursive: true });
+        writeFileSync(destFile, readFileSync(srcSkillMd, "utf-8"), "utf-8");
+        result.installed.push(skillName);
+    }
+    return result;
+}
 function buildChannelSummary(cfg) {
     const channels = [];
     if (cfg.adminEmail && cfg.smtpHost)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a13xu/lucid",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Token-efficient memory, code indexing, and validation for Claude Code agents — SQLite + FTS5, TF-IDF + Qdrant retrieval, AST skeleton pruning, diff-aware context, Logic Guardian drift detection",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "build/**/*.js",
     "build/**/*.d.ts",
+    "skills/**/*.md",
     "README.md"
   ],
   "scripts": {

package/skills/lucid-audit/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: lucid-audit
+description: Run after writing or modifying code — validates logic correctness (Logic Guardian 5 passes) and code quality (25 Golden Rules) before marking work as done.
+argument-hint: "[file path or 'all']"
+---
+
+# Lucid Code Audit
+
+Run this skill BEFORE marking any implementation as complete. It runs two complementary validators:
+
+- **Logic Guardian** (`validate_file`) — detects LLM drift: logic inversions, null propagation, off-by-one, copy-paste mistakes
+- **Code Quality Guard** (`check_code_quality`) — detects structural issues: file/function size, vague naming, deep nesting, prop explosion, inline styles
+
+## Steps
+
+### 1. Validate logic correctness
+```
+validate_file(path="<file you wrote or modified>")
+```
+Fix any 🔴 CRITICAL issues before continuing.
+
+### 2. Validate code quality
+```
+check_code_quality(path="<same file>")
+```
+Fix any 🔴 HIGH severity issues. Address 🟠 MEDIUM where practical.
+
+### 3. If unsure about a snippet before writing it to disk
+```
+check_drift(code="<your code>", language="typescript")
+```
+
+### 4. Get the full 5-pass mental checklist
+```
+get_checklist()
+```
+Use this when changes are complex or involve critical business logic.
+
+## Severity guide
+
+| Icon | Level | Action |
+|---|---|---|
+| 🔴 | Critical/High | Fix immediately — do not ship |
+| 🟠 | Medium/Warning | Fix if not risky refactor |
+| 🔵 | Low/Info | Note for future cleanup |
+
+## What each tool catches
+
+| Tool | Catches |
+|---|---|
+| `validate_file` | Logic inversions, silent exceptions, null propagation, type confusion, stale closures |
+| `check_code_quality` | Files >500 lines, functions >100 lines, vague names, nesting >4 levels, dead code, React/Vue component anti-patterns |
+| `check_drift` | Same as validate_file but on inline snippets — use before writing |

package/skills/lucid-context/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: lucid-context
+description: Use before starting any coding task — retrieves minimal relevant context via Lucid's TF-IDF retrieval, then rewards or penalizes based on usefulness.
+argument-hint: "[what you are working on]"
+---
+
+# Lucid Context Retrieval
+
+Use this skill at the START of every coding task to get only the relevant files instead of reading the whole codebase.
+
+## Steps
+
+1. **Call `get_context`** with a concise description of what you're working on:
+   ```
+   get_context(query="<what you are working on>", maxTokens=4000)
+   ```
+
+2. **Review the returned skeletons/files.** If they are relevant → call `reward()`. If they missed important files → call `penalize()` and note what was missing.
+
+3. **Start coding** using the context you received.
+
+## Tips
+
+- Use `dirs` to narrow scope: `get_context(query="...", dirs=["src/api"])`
+- Use `get_recent(hours=2)` after a git pull or when resuming a session to see what changed
+- Use `grep_code(pattern="...")` to locate specific function usages without reading full files
+- After finishing, call `sync_file(path="<modified file>")` to keep the knowledge graph current
+
+## When to reward vs penalize
+
+| Situation | Action |
+|---|---|
+| Context included the files that helped solve the task | `reward()` |
+| Context missed key files you had to find manually | `penalize(note="missed: src/utils/auth.ts")` |
+| Context was partially useful | No action needed |

package/skills/lucid-plan/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: lucid-plan
+description: Create and track an implementation plan before writing any code — use Lucid's planning tools to define user story, ordered tasks, and test criteria.
+argument-hint: "[feature or task description]"
+---
+
+# Lucid Planning Workflow
+
+Use this skill BEFORE writing code for any non-trivial feature. Plans are persisted in the Lucid DB and survive session restarts.
+
+## Steps
+
+### 1. Create the plan
+```
+plan_create(
+  title="<short title>",
+  description="<what this plan accomplishes>",
+  user_story="As a <user>, I want <goal>, so that <benefit>.",
+  tasks=[
+    { title: "Task 1", description: "...", test_criteria: "How to verify done" },
+    { title: "Task 2", description: "...", test_criteria: "..." },
+  ]
+)
+```
+Returns a `plan_id` and task IDs (format: `planId * 100 + sequence`).
+
+### 2. Work through tasks
+For each task, mark it in progress when you start:
+```
+plan_update_task(task_id=101, status="in_progress")
+```
+
+When done, mark it complete (optionally add a note):
+```
+plan_update_task(task_id=101, status="done", note="Used useFetch instead of axios")
+```
+
+Plan auto-completes when all tasks reach `done`.
+
+### 3. Resume a session — check plan status
+```
+plan_list()                  # see all active plans
+plan_get(plan_id=1)          # see full details + task status
+```
+
+## Task statuses
+
+| Status | When to use |
+|---|---|
+| `pending` | Not started yet |
+| `in_progress` | Currently working on it |
+| `done` | Completed and verified |
+| `blocked` | Waiting on external dependency |
+
+## Tips
+
+- Define `test_criteria` clearly — it becomes your acceptance test
+- Use `plan_get` when resuming to quickly re-orient yourself
+- Keep tasks small (1–4 hours each); use more tasks rather than fewer
+- Notes are append-only — use them to document decisions made during implementation

package/skills/lucid-security/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: lucid-security
+description: Run a full security review on a file or snippet — combines web vulnerability scanning (XSS, injection, secrets) with LLM drift detection before shipping code.
+argument-hint: "[file path or paste code]"
+---
+
+# Lucid Security Review
+
+Run this skill before shipping any code that handles user input, authentication, file access, or external data.
+
+## Steps
+
+### 1. Scan for web security vulnerabilities
+```
+security_scan(
+  code="<file contents or snippet>",
+  language="typescript",    # javascript | typescript | html | vue
+  context="backend"         # frontend | backend | api
+)
+```
+Detects: XSS vectors, eval/new Function, SQL injection via string concat, hardcoded secrets/keys, open redirects, prototype pollution, path traversal, insecure CORS.
+
+### 2. Scan for logic errors (LLM drift)
+```
+validate_file(path="<file path>")
+```
+Catches security-adjacent logic bugs: wrong condition direction, silent exception swallowing, null propagation into auth checks.
+
+### 3. For frontend components — audit accessibility too
+```
+accessibility_audit(code="<template or JSX>", wcag_level="AA", framework="vue")
+```
+
+## Severity guide
+
+| Icon | Severity | Action |
+|---|---|---|
+| 🔴 Critical | XSS, eval, hardcoded secret, SQL injection | Fix before any commit |
+| 🟠 High | Open redirect, path traversal, prototype pollution | Fix before merge |
+| 🟡 Medium | Wildcard CORS, missing CSRF protection | Fix before production |
+| 🔵 Low | console.log, minor info leakage | Fix when convenient |
+
+## Common patterns to watch
+
+| Pattern | Risk |
+|---|---|
+| `element.innerHTML = userInput` | XSS — use `textContent` or DOMPurify |
+| `eval(...)` / `new Function(...)` | Code injection |
+| `const key = "sk-abc123..."` | Hardcoded secret — move to env var |
+| `res.redirect(req.query.url)` | Open redirect — validate against allowlist |
+| `readFile(req.params.filename)` | Path traversal — use `path.resolve` + bounds check |
+| `Access-Control-Allow-Origin: *` | Overly permissive CORS |
+
+## Note
+
+Static scanning finds patterns, not all vulnerabilities. Complement with:
+- Manual code review for business logic flaws
+- DAST (dynamic testing) for runtime issues
+- Dependency audit: `npm audit` / `pip-audit`

package/skills/lucid-webdev/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: lucid-webdev
+description: Web development code generation tools — generate components, pages, SEO meta, API clients, tests, layouts, design tokens, and analyze accessibility and performance.
+argument-hint: "[component | page | seo | a11y | api | test | layout | security | tokens | perf]"
+---
+
+# Lucid Web Dev Tools
+
+10 tools for common web development tasks. Pick the one that matches what you need:
+
+## Component & Page Generation
+
+### Generate a component
+```
+generate_component(
+  description="user profile card with avatar and edit button",
+  framework="vue",          # react | vue | nuxt
+  styling="tailwind",       # tailwind | css-modules | none
+  typescript=true
+)
+```
+
+### Generate a page scaffold
+```
+scaffold_page(
+  page_name="ProductDetail",
+  framework="nuxt",          # nuxt | next | vue
+  sections=["hero", "specs", "reviews", "cta"],
+  seo_title="Product Detail"
+)
+```
+
+## SEO & Accessibility
+
+### Generate SEO metadata
+```
+seo_meta(
+  title="Buy Widgets — Best Price",
+  description="Shop our range of premium widgets with free delivery.",
+  keywords=["widgets", "buy widgets", "widget shop"],
+  page_type="product",       # article | product | landing | home
+  url="https://example.com/widgets",
+  image_url="https://example.com/og/widgets.jpg"
+)
+```
+Returns: HTML meta tags + Open Graph + Twitter Card + JSON-LD structured data.
+
+### Audit accessibility (WCAG)
+```
+accessibility_audit(
+  code="<your HTML/JSX/Vue snippet>",
+  wcag_level="AA",           # A | AA | AAA
+  framework="vue"            # html | jsx | vue
+)
+```
+Returns: violations with severity (critical/warning/info), WCAG criterion, and corrected code.
+
+## API & Testing
+
+### Generate a typed API client
+```
+api_client(
+  endpoint="/users/:id",
+  method="GET",              # GET | POST | PUT | PATCH | DELETE
+  response_schema="{ id: string; name: string; email: string }",
+  auth="bearer",             # bearer | cookie | apikey | none
+  base_url_var="NEXT_PUBLIC_API_URL"
+)
+```
+
+### Generate tests
+```
+test_generator(
+  code="<your function or component source>",
+  test_framework="vitest",   # vitest | jest | playwright
+  test_type="unit",          # unit | integration | e2e
+  component_framework="vue"  # vue | react | none
+)
+```
+
+## Layout & Design
+
+### Generate a responsive layout
+```
+responsive_layout(
+  description="sidebar left 260px, main content, right panel 240px",
+  framework="tailwind",      # tailwind | css-grid | flexbox
+  breakpoints=["mobile", "tablet", "desktop"],
+  container="sidebar"        # full | centered | sidebar
+)
+```
+
+### Generate design tokens
+```
+design_tokens(
+  brand_name="Acme",
+  primary_color="#6366F1",   # hex or name (blue, green, etc.)
+  mood="minimal",            # minimal | bold | playful | corporate
+  output_format="css-variables"  # css-variables | tailwind-config | json
+)
+```
+
+## Security & Performance
+
+### Scan for security vulnerabilities
+```
+security_scan(
+  code="<your code snippet>",
+  language="typescript",     # javascript | typescript | html | vue
+  context="frontend"         # frontend | backend | api
+)
+```
+Detects: XSS, eval/injection, hardcoded secrets, SQL injection, open redirects, CORS issues.
+
+### Analyze Core Web Vitals issues
+```
+perf_hints(
+  code="<your component or page source>",
+  framework="vue",           # react | vue | nuxt | vanilla
+  context="page"             # component | page | layout
+)
+```
+Detects: missing image dimensions (CLS), render-blocking scripts (FCP), fetch-in-render (TTFB), heavy click handlers (INP), missing useMemo/computed.