tina4-nodejs 3.10.34 → 3.10.40

package/packages/core/src/ai.ts

@@ -1,137 +1,229 @@
 /**
- * Tina4 AI — Detect AI coding assistants and scaffold context files.
+ * Tina4 AI — Install AI coding assistant context files.
  *
- * Detect which AI coding tools are available and install framework-aware
- * context so that any AI assistant understands how to build with Tina4.
+ * Simple menu-driven installer for AI tool context files.
+ * The user picks which tools they use, we install the appropriate files.
  *
- *   import { detectAi, installAiContext } from "@tina4/core";
- *
- *   const tools = detectAi();          // [{ name: "claude-code", ... }]
- *   installAiContext();                 // Scaffold context for all detected tools
+ *   import { showMenu, installSelected } from "@tina4/core";
  */
-import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, copyFileSync, cpSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, cpSync, statSync } from "node:fs";
 import { join, resolve, relative, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { createInterface } from "node:readline";
 
 // ── Types ────────────────────────────────────────────────────
 
 export interface AiTool {
   name: string;
   description: string;
-  configDir: string | null;
   contextFile: string;
+  configDir: string | null;
 }
 
-export interface AiDetection {
-  name: string;
-  description: string;
-  configFile: string;
-  status: "detected" | "not-detected";
+// ── Tool definitions (ordered array) ────────────────────────
+
+export const AI_TOOLS: AiTool[] = [
+  { name: "claude-code", description: "Claude Code", contextFile: "CLAUDE.md", configDir: ".claude" },
+  { name: "cursor", description: "Cursor", contextFile: ".cursorules", configDir: ".cursor" },
+  { name: "copilot", description: "GitHub Copilot", contextFile: ".github/copilot-instructions.md", configDir: ".github" },
+  { name: "windsurf", description: "Windsurf", contextFile: ".windsurfrules", configDir: null },
+  { name: "aider", description: "Aider", contextFile: "CONVENTIONS.md", configDir: null },
+  { name: "cline", description: "Cline", contextFile: ".clinerules", configDir: null },
+  { name: "codex", description: "OpenAI Codex", contextFile: "AGENTS.md", configDir: null },
+];
+
+// ── Helpers ─────────────────────────────────────────────────
+
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+
+/**
+ * Check if a tool's context file already exists.
+ */
+export function isInstalled(root: string, tool: AiTool): boolean {
+  return existsSync(join(resolve(root), tool.contextFile));
 }
 
-// ── Tool definitions ─────────────────────────────────────────
-
-const AI_TOOLS: Record<string, AiTool> = {
-  "claude-code": {
-    name: "claude-code",
-    description: "Claude Code (Anthropic CLI)",
-    configDir: ".claude",
-    contextFile: "CLAUDE.md",
-  },
-  cursor: {
-    name: "cursor",
-    description: "Cursor IDE",
-    configDir: ".cursor",
-    contextFile: ".cursorules",
-  },
-  copilot: {
-    name: "copilot",
-    description: "GitHub Copilot",
-    configDir: ".github",
-    contextFile: ".github/copilot-instructions.md",
-  },
-  windsurf: {
-    name: "windsurf",
-    description: "Windsurf (Codeium)",
-    configDir: null,
-    contextFile: ".windsurfrules",
-  },
-  aider: {
-    name: "aider",
-    description: "Aider",
-    configDir: null,
-    contextFile: "CONVENTIONS.md",
-  },
-  cline: {
-    name: "cline",
-    description: "Cline (VS Code)",
-    configDir: null,
-    contextFile: ".clinerules",
-  },
-  codex: {
-    name: "codex",
-    description: "OpenAI Codex CLI",
-    configDir: null,
-    contextFile: "AGENTS.md",
-  },
-};
-
-// ── Detection helpers ────────────────────────────────────────
-
-function detectTool(root: string, toolName: string): boolean {
+/**
+ * Print the numbered menu and read user input via readline.
+ * Returns a promise that resolves to the user's selection string.
+ */
+export function showMenu(root: string = "."): Promise<string> {
   const r = resolve(root);
-  switch (toolName) {
-    case "claude-code":
-      return existsSync(join(r, ".claude")) || existsSync(join(r, "CLAUDE.md"));
-    case "cursor":
-      return existsSync(join(r, ".cursor")) || existsSync(join(r, ".cursorules"));
-    case "copilot":
-      return existsSync(join(r, ".github", "copilot-instructions.md")) || existsSync(join(r, ".github"));
-    case "windsurf":
-      return existsSync(join(r, ".windsurfrules"));
-    case "aider":
-      return existsSync(join(r, ".aider.conf.yml")) || existsSync(join(r, "CONVENTIONS.md"));
-    case "cline":
-      return existsSync(join(r, ".clinerules"));
-    case "codex":
-      return existsSync(join(r, "AGENTS.md")) || existsSync(join(r, "codex.md"));
-    default:
-      return false;
+
+  console.log("\n  Tina4 AI Context Installer\n");
+
+  for (let i = 0; i < AI_TOOLS.length; i++) {
+    const tool = AI_TOOLS[i];
+    const installed = isInstalled(r, tool);
+    const marker = installed ? `  ${GREEN}[installed]${RESET}` : "";
+    const desc = tool.description.padEnd(20);
+    console.log(`  ${i + 1}. ${desc} ${tool.contextFile}${marker}`);
+  }
+
+  // tina4-ai tools option
+  let tina4AiInstalled = false;
+  try {
+    execSync("which mdview", { stdio: "ignore" });
+    tina4AiInstalled = true;
+  } catch {
+    // not installed
+  }
+  const tina4AiMarker = tina4AiInstalled ? `  ${GREEN}[installed]${RESET}` : "";
+  console.log(`  8. Install tina4-ai tools  (requires Python)${tina4AiMarker}`);
+  console.log();
+
+  return new Promise<string>((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question("  Select (comma-separated, or 'all'): ", (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Install context files for the selected tools.
+ *
+ * selection: comma-separated numbers like "1,2,3" or "all"
+ * Returns list of created/updated file paths.
+ */
+export function installSelected(root: string, selection: string): string[] {
+  const rootPath = resolve(root);
+  const created: string[] = [];
+
+  let indices: number[];
+  let doInstallTina4Ai = false;
+
+  if (selection.toLowerCase() === "all") {
+    indices = AI_TOOLS.map((_, i) => i);
+    doInstallTina4Ai = true;
+  } else {
+    const parts = selection.split(",").map((s) => s.trim()).filter(Boolean);
+    indices = [];
+    for (const p of parts) {
+      const n = parseInt(p, 10);
+      if (isNaN(n)) continue;
+      if (n === 8) {
+        doInstallTina4Ai = true;
+      } else if (n >= 1 && n <= AI_TOOLS.length) {
+        indices.push(n - 1);
+      }
+    }
+  }
+
+  const context = generateContext();
+
+  for (const idx of indices) {
+    const tool = AI_TOOLS[idx];
+    const files = installForTool(rootPath, tool, context);
+    created.push(...files);
+  }
+
+  if (doInstallTina4Ai) {
+    installTina4Ai();
   }
+
+  return created;
 }
 
-// ── Public API ───────────────────────────────────────────────
+/**
+ * Install context for all AI tools (non-interactive).
+ */
+export function installAll(root: string = "."): string[] {
+  return installSelected(root, "all");
+}
 
 /**
- * Detect which AI coding tools are present in the project.
+ * Install context file for a single tool.
  */
-export function detectAi(root: string = "."): AiDetection[] {
-  const r = resolve(root);
-  const results: AiDetection[] = [];
-
-  for (const [name, tool] of Object.entries(AI_TOOLS)) {
-    results.push({
-      name,
-      description: tool.description,
-      configFile: tool.contextFile,
-      status: detectTool(r, name) ? "detected" : "not-detected",
-    });
+function installForTool(root: string, tool: AiTool, context: string): string[] {
+  const created: string[] = [];
+  const contextPath = join(root, tool.contextFile);
+
+  // Create directories
+  if (tool.configDir) {
+    mkdirSync(join(root, tool.configDir), { recursive: true });
+  }
+  const parentDir = dirname(contextPath);
+  mkdirSync(parentDir, { recursive: true });
+
+  // Always overwrite -- user chose to install
+  writeFileSync(contextPath, context, "utf-8");
+  const rel = relative(root, contextPath);
+  created.push(rel);
+  console.log(`  ${GREEN}\u2713${RESET} Updated ${rel}`);
+
+  // Claude-specific extras
+  if (tool.name === "claude-code") {
+    const skills = installClaudeSkills(root);
+    created.push(...skills);
   }
 
-  return results;
+  return created;
+}
+
+/**
+ * Install tina4-ai package (provides mdview for markdown viewing).
+ */
+function installTina4Ai(): void {
+  console.log("  Installing tina4-ai tools...");
+  for (const cmd of ["pip3", "pip"]) {
+    let hasCmd = false;
+    try {
+      execSync(`which ${cmd}`, { stdio: "ignore" });
+      hasCmd = true;
+    } catch {
+      // not available
+    }
+    if (!hasCmd) continue;
+
+    try {
+      execSync(`${cmd} install --upgrade tina4-ai`, { stdio: "pipe", timeout: 60000 });
+      console.log(`  ${GREEN}\u2713${RESET} Installed tina4-ai (mdview)`);
+      return;
+    } catch (err: any) {
+      const stderr = err.stderr ? err.stderr.toString().trim().slice(0, 100) : "unknown error";
+      console.log(`  ${YELLOW}!${RESET} ${cmd} failed: ${stderr}`);
+    }
+  }
+  console.log(`  ${YELLOW}!${RESET} Python/pip not available -- skip tina4-ai`);
 }
 
 /**
- * Return just the names of detected AI tools.
+ * Copy Claude Code skill files from the framework's directories.
  */
-export function detectAiNames(root: string = "."): string[] {
-  return detectAi(root)
-    .filter((t) => t.status === "detected")
-    .map((t) => t.name);
+function installClaudeSkills(root: string): string[] {
+  const created: string[] = [];
+
+  // Determine the framework root (where packages/core/src/ lives)
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const frameworkRoot = resolve(thisDir, "..", "..", "..");
+
+  // Copy skill directories from .claude/skills/ in the framework to the project
+  const frameworkSkillsDir = join(frameworkRoot, ".claude", "skills");
+  if (existsSync(frameworkSkillsDir)) {
+    const targetSkillsDir = join(root, ".claude", "skills");
+    mkdirSync(targetSkillsDir, { recursive: true });
+    for (const entry of readdirSync(frameworkSkillsDir)) {
+      const skillDir = join(frameworkSkillsDir, entry);
+      if (existsSync(skillDir) && statSync(skillDir).isDirectory()) {
+        const targetDir = join(targetSkillsDir, entry);
+        cpSync(skillDir, targetDir, { recursive: true, force: true });
+        const rel = relative(root, targetDir);
+        created.push(rel);
+        console.log(`  ${GREEN}\u2713${RESET} Updated ${rel}`);
+      }
+    }
+  }
+
+  return created;
 }
 
 /**
- * Generate a universal Tina4 context document for any AI assistant.
+ * Generate the universal Tina4 context document for any AI assistant.
  */
 export function generateContext(): string {
   return `# Tina4 Node.js — AI Context
@@ -144,23 +236,24 @@ web framework with zero third-party dependencies for core features.
 ## Quick Start
 
 \`\`\`bash
-tina4nodejs init .          # Scaffold project
-tina4nodejs serve           # Start dev server on port 7148
-tina4nodejs migrate         # Run database migrations
-tina4nodejs test            # Run test suite
-tina4nodejs routes          # List all registered routes
+npx tina4nodejs init .          # Scaffold project
+npx tina4nodejs serve           # Start dev server on port 7148
+npx tina4nodejs migrate         # Run database migrations
+npx tina4nodejs test            # Run test suite
+npx tina4nodejs routes          # List all registered routes
 \`\`\`
 
 ## Project Structure
 
 \`\`\`
-src/routes/       — Route handlers (auto-discovered, file-based routing)
-src/models/       — ORM models (one per file, convention-based)
-src/templates/    — Twig templates
-src/public/       — Static assets served at /
-src/scss/         — SCSS files (auto-compiled to public/css/)
-migrations/       — SQL migration files (sequential numbered)
-test/             — Test files
+packages/core/src/    — Framework core (server, router, middleware, events)
+src/routes/           — Route handlers (auto-discovered, file-based routing)
+src/models/           — ORM models (one per file, convention-based)
+src/templates/        — Twig templates
+src/public/           — Static assets served at /
+src/scss/             — SCSS files (auto-compiled to public/css/)
+migrations/           — SQL migration files (sequential numbered)
+test/                 — Test files
 \`\`\`
 
 ## Built-in Features (No External Packages Needed)
@@ -170,8 +263,8 @@ test/             — Test files
 | Routing | router | \`import { get, post, put, del } from "@tina4/core"\` |
 | ORM | orm | \`import { BaseModel } from "@tina4/orm"\` |
 | Database | database | \`import { initDatabase } from "@tina4/orm"\` |
-| Templates | twig | \`import { renderTemplate } from "@tina4/frond"\` |
-| JWT Auth | auth | \`import { createToken, validateToken } from "@tina4/core"\` |
+| Templates | twig | \`import { renderTemplate } from "@tina4/twig"\` |
+| JWT Auth | auth | \`import { createToken, validateToken, hashPassword, checkPassword } from "@tina4/core"\` |
 | REST API Client | api | \`import { Api } from "@tina4/core"\` |
 | GraphQL | graphql | \`import { GraphQL } from "@tina4/core"\` |
 | WebSocket | websocket | \`import { WebSocketServer } from "@tina4/core"\` |
@@ -179,12 +272,18 @@ test/             — Test files
 | Email (SMTP+IMAP) | messenger | \`import { Messenger } from "@tina4/core"\` |
 | Background Queue | queue | \`import { Queue } from "@tina4/core"\` |
 | SCSS Compilation | scss | Auto-compiled from src/scss/ |
-| Migrations | migration | \`tina4nodejs migrate\` CLI command |
+| Migrations | migration | \`npx tina4nodejs migrate\` CLI command |
+| Seeder | seeder | \`import { FakeData, seedTable } from "@tina4/orm"\` |
 | i18n | i18n | \`import { I18n } from "@tina4/core"\` |
 | Swagger/OpenAPI | swagger | Auto-generated at /swagger |
 | Sessions | session | \`import { Session } from "@tina4/core"\` |
 | Middleware | middleware | \`import { MiddlewareChain } from "@tina4/core"\` |
-| Cache | cache | \`import { responseCache } from "@tina4/core"\` |
+| Cache | cache | \`import { responseCache, cacheStats, clearCache } from "@tina4/core"\` |
+| Events | events | \`import { Events } from "@tina4/core"\` |
+| HTML Builder | htmlElement | \`import { HtmlElement, htmlElement, addHtmlHelpers } from "@tina4/core"\` |
+| Error Overlay | errorOverlay | \`import { renderErrorOverlay, isDebugMode } from "@tina4/core"\` |
+| Inline Testing | testing | \`import { tests, assertEqual, runAllTests } from "@tina4/core"\` |
+| DI Container | container | \`import { Container } from "@tina4/core"\` |
 
 ## Key Conventions
 
@@ -197,6 +296,30 @@ test/             — Test files
 7. **All schema changes via migrations** — never create tables in route code
 8. **Use built-in features** — never install packages for things Tina4 already provides
 
+## AI Workflow — Available Skills
+
+When using an AI coding assistant with Tina4, these skills are available:
+
+| Skill | Description |
+|-------|-------------|
+| \`/tina4-route\` | Create a new route with proper decorators and auth |
+| \`/tina4-orm\` | Create an ORM model with migration |
+| \`/tina4-crud\` | Generate complete CRUD (migration, ORM, routes, template, tests) |
+| \`/tina4-auth\` | Set up JWT authentication with login/register |
+| \`/tina4-api\` | Create an external API integration |
+| \`/tina4-queue\` | Set up background job processing |
+| \`/tina4-template\` | Create a server-rendered template page |
+| \`/tina4-graphql\` | Set up a GraphQL endpoint |
+| \`/tina4-websocket\` | Set up WebSocket communication |
+| \`/tina4-wsdl\` | Create a SOAP/WSDL service |
+| \`/tina4-messenger\` | Set up email send/receive |
+| \`/tina4-test\` | Write tests for a feature |
+| \`/tina4-migration\` | Create a database migration |
+| \`/tina4-seed\` | Generate fake data for development |
+| \`/tina4-i18n\` | Set up internationalization |
+| \`/tina4-scss\` | Set up SCSS stylesheets |
+| \`/tina4-frontend\` | Set up a frontend framework |
+
 ## Common Patterns
 
 ### Route
@@ -227,133 +350,4 @@ export default class User {
 `;
 }
 
-/**
- * Install Tina4 context files for detected (or specified) AI tools.
- *
- * Returns list of files created/updated.
- */
-export function installAiContext(
-  root: string = ".",
-  options?: { tools?: string[]; force?: boolean },
-): string[] {
-  const r = resolve(root);
-  const force = options?.force ?? false;
-  const created: string[] = [];
-
-  const toolNames = options?.tools ?? detectAiNames(r);
-  const context = generateContext();
-
-  for (const toolName of toolNames) {
-    const tool = AI_TOOLS[toolName];
-    if (!tool) continue;
-
-    const contextPath = join(r, tool.contextFile);
-
-    // Create config directory if needed
-    if (tool.configDir) {
-      mkdirSync(join(r, tool.configDir), { recursive: true });
-    }
-
-    // Ensure parent directory of context file exists
-    const parentDir = join(contextPath, "..");
-    mkdirSync(parentDir, { recursive: true });
-
-    if (!existsSync(contextPath) || force) {
-      writeFileSync(contextPath, context, "utf-8");
-      created.push(relative(r, contextPath));
-    }
-
-    // Install Claude Code skills if it's Claude
-    if (toolName === "claude-code") {
-      const skillFiles = installClaudeSkills(r, force);
-      created.push(...skillFiles);
-    }
-  }
-
-  return created;
-}
-
-/**
- * Copy Claude Code skill files from the framework's directories.
- */
-function installClaudeSkills(root: string, force: boolean): string[] {
-  const created: string[] = [];
-
-  // Determine the framework root (where packages/core/src/ lives)
-  const thisDir = dirname(fileURLToPath(import.meta.url));
-  const frameworkRoot = resolve(thisDir, "..", "..", "..");
-
-  // Copy .skill files from the framework's skills/ directory to project root
-  const skillsSource = join(frameworkRoot, "skills");
-  if (existsSync(skillsSource)) {
-    for (const entry of readdirSync(skillsSource)) {
-      if (entry.endsWith(".skill")) {
-        const srcFile = join(skillsSource, entry);
-        const target = join(root, entry);
-        if (!existsSync(target) || force) {
-          copyFileSync(srcFile, target);
-          created.push(entry);
-        }
-      }
-    }
-  }
-
-  // Copy skill directories from .claude/skills/ in the framework to the project
-  const frameworkSkillsDir = join(frameworkRoot, ".claude", "skills");
-  if (existsSync(frameworkSkillsDir)) {
-    const targetSkillsDir = join(root, ".claude", "skills");
-    mkdirSync(targetSkillsDir, { recursive: true });
-    for (const entry of readdirSync(frameworkSkillsDir)) {
-      const skillDir = join(frameworkSkillsDir, entry);
-      if (existsSync(skillDir) && statSync(skillDir).isDirectory()) {
-        const targetDir = join(targetSkillsDir, entry);
-        if (!existsSync(targetDir) || force) {
-          cpSync(skillDir, targetDir, { recursive: true, force: true });
-          created.push(relative(root, targetDir));
-        }
-      }
-    }
-  }
-
-  return created;
-}
-
-/**
- * Install Tina4 context for ALL known AI tools (not just detected ones).
- */
-export function installAllAiContext(root: string = ".", force: boolean = false): string[] {
-  return installAiContext(root, {
-    tools: Object.keys(AI_TOOLS),
-    force,
-  });
-}
-
-/**
- * Generate a human-readable report of AI tool detection.
- */
-export function aiStatusReport(root: string = "."): string {
-  const tools = detectAi(root);
-  const installed = tools.filter((t) => t.status === "detected");
-  const missing = tools.filter((t) => t.status === "not-detected");
-
-  const lines: string[] = ["\nTina4 AI Context Status\n"];
-
-  if (installed.length > 0) {
-    lines.push("Detected AI tools:");
-    for (const t of installed) {
-      lines.push(`  + ${t.description} (${t.name})`);
-    }
-  } else {
-    lines.push("No AI coding tools detected.");
-  }
-
-  if (missing.length > 0) {
-    lines.push("\nNot detected (install context with `tina4nodejs ai --all`):");
-    for (const t of missing) {
-      lines.push(`  - ${t.description} (${t.name})`);
-    }
-  }
-
-  lines.push("");
-  return lines.join("\n");
-}
+export { AiTool as AiToolType };