@nicnocquee/dataqueue 1.33.0 → 1.34.0

package/dist/cli.js

@@ -1,7 +1,11 @@
 import { spawnSync } from 'child_process';
-import path from 'path';
+import path3 from 'path';
 import { fileURLToPath } from 'url';
-import { readFileSync, existsSync, chmodSync, writeFileSync, mkdirSync } from 'fs';
+import fs, { readFileSync, existsSync, chmodSync, writeFileSync, mkdirSync } from 'fs';
+import readline from 'readline';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
 
 // src/cli.ts
 var DEPENDENCIES_TO_ADD = [
@@ -366,7 +370,7 @@ function detectNextJsAndRouter({
   existsSyncImpl,
   readFileSyncImpl
 }) {
-  const packageJsonPath = path.join(cwd, "package.json");
+  const packageJsonPath = path3.join(cwd, "package.json");
   if (!existsSyncImpl(packageJsonPath)) {
     throw new Error("package.json not found in current directory.");
   }
@@ -379,10 +383,10 @@ function detectNextJsAndRouter({
       "Not a Next.js project. Could not find 'next' in package.json dependencies."
     );
   }
-  const srcDir = path.join(cwd, "src");
+  const srcDir = path3.join(cwd, "src");
   const srcRoot = existsSyncImpl(srcDir) ? "src" : ".";
-  const appDir = path.join(cwd, srcRoot, "app");
-  const pagesDir = path.join(cwd, srcRoot, "pages");
+  const appDir = path3.join(cwd, srcRoot, "app");
+  const pagesDir = path3.join(cwd, srcRoot, "pages");
   const hasAppDir = existsSyncImpl(appDir);
   const hasPagesDir = existsSyncImpl(pagesDir);
   if (!hasAppDir && !hasPagesDir) {
@@ -443,7 +447,7 @@ function createScaffoldFiles({
   writeFileSyncImpl,
   chmodSyncImpl
 }) {
-  const appRoutePath = path.join(
+  const appRoutePath = path3.join(
     details.cwd,
     details.srcRoot,
     "app",
@@ -453,7 +457,7 @@ function createScaffoldFiles({
     "[[...task]]",
     "route.ts"
   );
-  const pagesRoutePath = path.join(
+  const pagesRoutePath = path3.join(
     details.cwd,
     details.srcRoot,
     "pages",
@@ -462,14 +466,14 @@ function createScaffoldFiles({
     "manage",
     "[[...task]].ts"
   );
-  const queuePath = path.join(
+  const queuePath = path3.join(
     details.cwd,
     details.srcRoot,
     "lib",
     "dataqueue",
     "queue.ts"
   );
-  const cronPath = path.join(details.cwd, "cron.sh");
+  const cronPath = path3.join(details.cwd, "cron.sh");
   if (details.router === "app") {
     createFileIfMissing({
       absolutePath: appRoutePath,
@@ -532,7 +536,7 @@ function createFileIfMissing({
     log(`  [skipped] ${logPath} (already exists)`);
     return;
   }
-  mkdirSyncImpl(path.dirname(absolutePath), { recursive: true });
+  mkdirSyncImpl(path3.dirname(absolutePath), { recursive: true });
   writeFileSyncImpl(absolutePath, content);
   log(`  [created] ${logPath}`);
 }
@@ -568,21 +572,541 @@ function ensureStringMapSection(packageJson, sectionName) {
   return packageJson[sectionName];
 }
 function toRelativePath(cwd, absolutePath) {
-  const relative = path.relative(cwd, absolutePath);
+  const relative = path3.relative(cwd, absolutePath);
   return relative || ".";
 }
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path3.dirname(__filename);
+var SKILL_DIRS = ["dataqueue-core", "dataqueue-advanced", "dataqueue-react"];
+function detectAiTools(cwd, existsSync2 = fs.existsSync) {
+  const tools = [];
+  const checks = [
+    {
+      name: "Cursor",
+      indicator: ".cursor",
+      targetDir: ".cursor/skills"
+    },
+    {
+      name: "Claude Code",
+      indicator: ".claude",
+      targetDir: ".claude/skills"
+    },
+    {
+      name: "GitHub Copilot",
+      indicator: ".github",
+      targetDir: ".github/skills"
+    }
+  ];
+  for (const check of checks) {
+    if (existsSync2(path3.join(cwd, check.indicator))) {
+      tools.push({ name: check.name, targetDir: check.targetDir });
+    }
+  }
+  return tools;
+}
+function runInstallSkills({
+  log = console.log,
+  error = console.error,
+  exit = (code) => process.exit(code),
+  cwd = process.cwd(),
+  existsSync: existsSync2 = fs.existsSync,
+  mkdirSync: mkdirSync2 = fs.mkdirSync,
+  copyFileSync = fs.copyFileSync,
+  readdirSync = fs.readdirSync,
+  skillsSourceDir = path3.join(__dirname, "../ai/skills")
+} = {}) {
+  const tools = detectAiTools(cwd, existsSync2);
+  if (tools.length === 0) {
+    log("No AI tool directories detected (.cursor/, .claude/, .github/).");
+    log("Creating .cursor/skills/ as the default target.");
+    tools.push({ name: "Cursor", targetDir: ".cursor/skills" });
+  }
+  let installed = 0;
+  for (const tool of tools) {
+    log(`
+Installing skills for ${tool.name}...`);
+    for (const skillDir of SKILL_DIRS) {
+      const srcDir = path3.join(skillsSourceDir, skillDir);
+      const destDir = path3.join(cwd, tool.targetDir, skillDir);
+      try {
+        mkdirSync2(destDir, { recursive: true });
+        const files = readdirSync(srcDir);
+        for (const file of files) {
+          copyFileSync(path3.join(srcDir, file), path3.join(destDir, file));
+        }
+        log(`  \u2713 ${skillDir}`);
+        installed++;
+      } catch (err) {
+        error(`  \u2717 Failed to install ${skillDir}:`, err);
+      }
+    }
+  }
+  if (installed > 0) {
+    log(
+      `
+Done! Installed ${installed} skill(s) for ${tools.map((t) => t.name).join(", ")}.`
+    );
+  } else {
+    error("No skills were installed.");
+    exit(1);
+  }
+}
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path3.dirname(__filename2);
+var RULE_FILES = ["basic.md", "advanced.md", "react-dashboard.md"];
+var MARKER_START = "<!-- DATAQUEUE RULES START -->";
+var MARKER_END = "<!-- DATAQUEUE RULES END -->";
+function upsertMarkedSection(filePath, content, deps) {
+  const block = `${MARKER_START}
+${content}
+${MARKER_END}`;
+  if (!deps.existsSync(filePath)) {
+    deps.writeFileSync(filePath, block + "\n");
+    return;
+  }
+  const existing = deps.readFileSync(filePath, "utf-8");
+  const startIdx = existing.indexOf(MARKER_START);
+  const endIdx = existing.indexOf(MARKER_END);
+  if (startIdx !== -1 && endIdx !== -1) {
+    const before = existing.slice(0, startIdx);
+    const after = existing.slice(endIdx + MARKER_END.length);
+    deps.writeFileSync(filePath, before + block + after);
+  } else {
+    deps.writeFileSync(filePath, existing.trimEnd() + "\n\n" + block + "\n");
+  }
+}
+function getAllRulesContent(rulesSourceDir, readFileSync2) {
+  return RULE_FILES.map(
+    (f) => readFileSync2(path3.join(rulesSourceDir, f), "utf-8")
+  ).join("\n\n");
+}
+var CLIENTS = {
+  "1": {
+    label: "Cursor",
+    install: (deps) => {
+      const rulesDir = path3.join(deps.cwd, ".cursor", "rules");
+      deps.mkdirSync(rulesDir, { recursive: true });
+      for (const file of RULE_FILES) {
+        const src = deps.readFileSync(
+          path3.join(deps.rulesSourceDir, file),
+          "utf-8"
+        );
+        const destName = `dataqueue-${file.replace(/\.md$/, ".mdc")}`;
+        deps.writeFileSync(path3.join(rulesDir, destName), src);
+        deps.log(`  \u2713 .cursor/rules/${destName}`);
+      }
+    }
+  },
+  "2": {
+    label: "Claude Code",
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync
+      );
+      const filePath = path3.join(deps.cwd, "CLAUDE.md");
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  \u2713 CLAUDE.md`);
+    }
+  },
+  "3": {
+    label: "AGENTS.md (Codex, Jules, OpenCode)",
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync
+      );
+      const filePath = path3.join(deps.cwd, "AGENTS.md");
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  \u2713 AGENTS.md`);
+    }
+  },
+  "4": {
+    label: "GitHub Copilot",
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync
+      );
+      deps.mkdirSync(path3.join(deps.cwd, ".github"), { recursive: true });
+      const filePath = path3.join(
+        deps.cwd,
+        ".github",
+        "copilot-instructions.md"
+      );
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  \u2713 .github/copilot-instructions.md`);
+    }
+  },
+  "5": {
+    label: "Windsurf",
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync
+      );
+      const filePath = path3.join(deps.cwd, "CONVENTIONS.md");
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  \u2713 CONVENTIONS.md`);
+    }
+  }
+};
+async function runInstallRules({
+  log = console.log,
+  error = console.error,
+  exit = (code) => process.exit(code),
+  cwd = process.cwd(),
+  readFileSync: readFileSync2 = fs.readFileSync,
+  writeFileSync: writeFileSync2 = fs.writeFileSync,
+  appendFileSync = fs.appendFileSync,
+  mkdirSync: mkdirSync2 = fs.mkdirSync,
+  existsSync: existsSync2 = fs.existsSync,
+  rulesSourceDir = path3.join(__dirname2, "../ai/rules"),
+  selectedClient
+} = {}) {
+  log("DataQueue Agent Rules Installer\n");
+  log("Select your AI client:\n");
+  for (const [key, client2] of Object.entries(CLIENTS)) {
+    log(`  ${key}) ${client2.label}`);
+  }
+  log("");
+  let choice = selectedClient;
+  if (!choice) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    choice = await new Promise((resolve) => {
+      rl.question("Enter choice (1-5): ", (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    });
+  }
+  const client = CLIENTS[choice];
+  if (!client) {
+    error(`Invalid choice: "${choice}". Expected 1-5.`);
+    exit(1);
+    return;
+  }
+  log(`
+Installing rules for ${client.label}...`);
+  try {
+    client.install({
+      cwd,
+      readFileSync: readFileSync2,
+      writeFileSync: writeFileSync2,
+      appendFileSync,
+      mkdirSync: mkdirSync2,
+      existsSync: existsSync2,
+      log,
+      rulesSourceDir
+    });
+    log("\nDone!");
+  } catch (err) {
+    error("Failed to install rules:", err);
+    exit(1);
+  }
+}
+function upsertMcpConfig(filePath, serverKey, serverConfig, deps) {
+  let config = {};
+  if (deps.existsSync(filePath)) {
+    try {
+      config = JSON.parse(deps.readFileSync(filePath, "utf-8"));
+    } catch {
+      config = {};
+    }
+  }
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+  config.mcpServers[serverKey] = serverConfig;
+  deps.writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n");
+}
+var MCP_SERVER_CONFIG = {
+  command: "npx",
+  args: ["dataqueue-cli", "mcp"]
+};
+var MCP_CLIENTS = {
+  "1": {
+    label: "Cursor",
+    install: (deps) => {
+      const configDir = path3.join(deps.cwd, ".cursor");
+      deps.mkdirSync(configDir, { recursive: true });
+      const configFile = path3.join(configDir, "mcp.json");
+      upsertMcpConfig(configFile, "dataqueue", MCP_SERVER_CONFIG, deps);
+      deps.log(`  \u2713 .cursor/mcp.json`);
+    }
+  },
+  "2": {
+    label: "Claude Code",
+    install: (deps) => {
+      const configFile = path3.join(deps.cwd, ".mcp.json");
+      upsertMcpConfig(configFile, "dataqueue", MCP_SERVER_CONFIG, deps);
+      deps.log(`  \u2713 .mcp.json`);
+    }
+  },
+  "3": {
+    label: "VS Code (Copilot)",
+    install: (deps) => {
+      const configDir = path3.join(deps.cwd, ".vscode");
+      deps.mkdirSync(configDir, { recursive: true });
+      const configFile = path3.join(configDir, "mcp.json");
+      upsertMcpConfig(configFile, "dataqueue", MCP_SERVER_CONFIG, deps);
+      deps.log(`  \u2713 .vscode/mcp.json`);
+    }
+  },
+  "4": {
+    label: "Windsurf",
+    install: (deps) => {
+      const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+      const configFile = path3.join(
+        homeDir,
+        ".codeium",
+        "windsurf",
+        "mcp_config.json"
+      );
+      deps.mkdirSync(path3.dirname(configFile), { recursive: true });
+      upsertMcpConfig(configFile, "dataqueue", MCP_SERVER_CONFIG, deps);
+      deps.log(`  \u2713 ~/.codeium/windsurf/mcp_config.json`);
+    }
+  }
+};
+async function runInstallMcp({
+  log = console.log,
+  error = console.error,
+  exit = (code) => process.exit(code),
+  cwd = process.cwd(),
+  readFileSync: readFileSync2 = fs.readFileSync,
+  writeFileSync: writeFileSync2 = fs.writeFileSync,
+  mkdirSync: mkdirSync2 = fs.mkdirSync,
+  existsSync: existsSync2 = fs.existsSync,
+  selectedClient
+} = {}) {
+  log("DataQueue MCP Server Installer\n");
+  log("Select your AI client:\n");
+  for (const [key, client2] of Object.entries(MCP_CLIENTS)) {
+    log(`  ${key}) ${client2.label}`);
+  }
+  log("");
+  let choice = selectedClient;
+  if (!choice) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    choice = await new Promise((resolve) => {
+      rl.question("Enter choice (1-4): ", (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    });
+  }
+  const client = MCP_CLIENTS[choice];
+  if (!client) {
+    error(`Invalid choice: "${choice}". Expected 1-4.`);
+    exit(1);
+    return;
+  }
+  log(`
+Installing MCP config for ${client.label}...`);
+  try {
+    client.install({
+      cwd,
+      readFileSync: readFileSync2,
+      writeFileSync: writeFileSync2,
+      mkdirSync: mkdirSync2,
+      existsSync: existsSync2,
+      log
+    });
+    log("\nDone! The MCP server will run via: npx dataqueue-cli mcp");
+  } catch (err) {
+    error("Failed to install MCP config:", err);
+    exit(1);
+  }
+}
+var __filename3 = fileURLToPath(import.meta.url);
+var __dirname3 = path3.dirname(__filename3);
+function loadDocsContent(docsPath = path3.join(__dirname3, "../ai/docs-content.json")) {
+  const raw = fs.readFileSync(docsPath, "utf-8");
+  return JSON.parse(raw);
+}
+function scorePageForQuery(page, queryTerms) {
+  const titleLower = page.title.toLowerCase();
+  const descLower = page.description.toLowerCase();
+  const contentLower = page.content.toLowerCase();
+  let score = 0;
+  for (const term of queryTerms) {
+    if (titleLower.includes(term)) score += 10;
+    if (descLower.includes(term)) score += 5;
+    const contentMatches = contentLower.split(term).length - 1;
+    score += Math.min(contentMatches, 10);
+  }
+  return score;
+}
+function extractExcerpt(content, queryTerms, maxLength = 500) {
+  const lower = content.toLowerCase();
+  let earliestIndex = -1;
+  for (const term of queryTerms) {
+    const idx = lower.indexOf(term);
+    if (idx !== -1 && (earliestIndex === -1 || idx < earliestIndex)) {
+      earliestIndex = idx;
+    }
+  }
+  if (earliestIndex === -1) {
+    return content.slice(0, maxLength);
+  }
+  const start = Math.max(0, earliestIndex - 100);
+  const end = Math.min(content.length, start + maxLength);
+  let excerpt = content.slice(start, end);
+  if (start > 0) excerpt = "..." + excerpt;
+  if (end < content.length) excerpt = excerpt + "...";
+  return excerpt;
+}
+async function startMcpServer(deps = {}) {
+  const pages = loadDocsContent(deps.docsPath);
+  const server = new McpServer({
+    name: "dataqueue-docs",
+    version: "1.0.0"
+  });
+  server.resource("llms-txt", "dataqueue://llms.txt", async () => {
+    const llmsPath = path3.join(
+      __dirname3,
+      "../ai/skills/dataqueue-core/SKILL.md"
+    );
+    let content;
+    try {
+      content = fs.readFileSync(llmsPath, "utf-8");
+    } catch {
+      content = pages.map((p) => `## ${p.title}
+
+Slug: ${p.slug}
+
+${p.description}`).join("\n\n");
+    }
+    return { contents: [{ uri: "dataqueue://llms.txt", text: content }] };
+  });
+  server.tool(
+    "list-doc-pages",
+    "List all available DataQueue documentation pages with titles and descriptions.",
+    {},
+    async () => {
+      const listing = pages.map((p) => ({
+        slug: p.slug,
+        title: p.title,
+        description: p.description
+      }));
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(listing, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get-doc-page",
+    "Fetch a specific DataQueue doc page by slug. Returns full page content as markdown.",
+    {
+      slug: z.string().describe('The doc page slug, e.g. "usage/add-job" or "api/job-queue"')
+    },
+    async ({ slug }) => {
+      const page = pages.find((p) => p.slug === slug);
+      if (!page) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Page not found: "${slug}". Use list-doc-pages to see available slugs.`
+            }
+          ],
+          isError: true
+        };
+      }
+      const header = page.description ? `# ${page.title}
+
+> ${page.description}
+
+` : `# ${page.title}
+
+`;
+      return {
+        content: [{ type: "text", text: header + page.content }]
+      };
+    }
+  );
+  server.tool(
+    "search-docs",
+    "Full-text search across all DataQueue documentation pages. Returns matching sections with page titles and content excerpts.",
+    {
+      query: z.string().describe('Search query, e.g. "cron scheduling" or "waitForToken"')
+    },
+    async ({ query }) => {
+      const queryTerms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
+      if (queryTerms.length === 0) {
+        return {
+          content: [
+            { type: "text", text: "Please provide a search query." }
+          ],
+          isError: true
+        };
+      }
+      const scored = pages.map((page) => ({
+        page,
+        score: scorePageForQuery(page, queryTerms)
+      })).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, 5);
+      if (scored.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results for "${query}". Try different keywords or use list-doc-pages to browse.`
+            }
+          ]
+        };
+      }
+      const results = scored.map((r) => {
+        const excerpt = extractExcerpt(r.page.content, queryTerms);
+        return `## ${r.page.title} (${r.page.slug})
+
+${r.page.description}
+
+${excerpt}`;
+      });
+      return {
+        content: [{ type: "text", text: results.join("\n\n---\n\n") }]
+      };
+    }
+  );
+  const transport = deps.transport ?? new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+var isDirectRun = process.argv[1] && (process.argv[1].endsWith("/mcp-server.js") || process.argv[1].endsWith("/mcp-server.cjs"));
+if (isDirectRun) {
+  startMcpServer().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+  });
+}
 
 // src/cli.ts
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = path.dirname(__filename);
+var __filename4 = fileURLToPath(import.meta.url);
+var __dirname4 = path3.dirname(__filename4);
 function runCli(argv, {
   log = console.log,
   error = console.error,
   exit = (code) => process.exit(code),
   spawnSyncImpl = spawnSync,
-  migrationsDir = path.join(__dirname, "../migrations"),
+  migrationsDir = path3.join(__dirname4, "../migrations"),
   initDeps,
-  runInitImpl = runInit
+  runInitImpl = runInit,
+  installSkillsDeps,
+  runInstallSkillsImpl = runInstallSkills,
+  installRulesDeps,
+  runInstallRulesImpl = runInstallRules,
+  installMcpDeps,
+  runInstallMcpImpl = runInstallMcp,
+  startMcpServerImpl = startMcpServer
 } = {}) {
   const [, , command, ...restArgs] = argv;
   function printUsage() {
@@ -591,6 +1115,10 @@ function runCli(argv, {
       "  dataqueue-cli migrate [--envPath <path>] [-s <schema> | --schema <schema>]"
     );
     log("  dataqueue-cli init");
+    log("  dataqueue-cli install-skills");
+    log("  dataqueue-cli install-rules");
+    log("  dataqueue-cli install-mcp");
+    log("  dataqueue-cli mcp");
     log("");
     log("Options for migrate:");
     log(
@@ -600,24 +1128,13 @@ function runCli(argv, {
       "  -s, --schema <schema>  Set the schema to use (passed to node-pg-migrate)"
     );
     log("");
-    log("Notes:");
-    log(
-      "  - The PG_DATAQUEUE_DATABASE environment variable must be set to your Postgres connection string."
-    );
-    log(
-      "  - For managed Postgres (e.g., DigitalOcean) with SSL, set PGSSLMODE=require and PGSSLROOTCERT to your CA .crt file."
-    );
-    log(
-      "    Example: PGSSLMODE=require NODE_EXTRA_CA_CERTS=/absolute/path/to/ca.crt PG_DATAQUEUE_DATABASE=... npx dataqueue-cli migrate"
-    );
-    log("");
-    log("Notes for init:");
-    log(
-      "  - Supports both Next.js App Router and Pages Router (prefers App Router if both exist)."
-    );
+    log("AI tooling commands:");
+    log("  install-skills     Install DataQueue skill files for AI assistants");
+    log("  install-rules      Install DataQueue agent rules for AI clients");
     log(
-      "  - Scaffolds endpoint, cron.sh, queue placeholder, and package.json entries."
+      "  install-mcp        Configure the DataQueue MCP server for AI clients"
     );
+    log("  mcp                Start the DataQueue MCP server (stdio)");
     exit(1);
   }
   if (command === "migrate") {
@@ -661,6 +1178,32 @@ function runCli(argv, {
       exit,
       ...initDeps
     });
+  } else if (command === "install-skills") {
+    runInstallSkillsImpl({
+      log,
+      error,
+      exit,
+      ...installSkillsDeps
+    });
+  } else if (command === "install-rules") {
+    runInstallRulesImpl({
+      log,
+      error,
+      exit,
+      ...installRulesDeps
+    });
+  } else if (command === "install-mcp") {
+    runInstallMcpImpl({
+      log,
+      error,
+      exit,
+      ...installMcpDeps
+    });
+  } else if (command === "mcp") {
+    startMcpServerImpl().catch((err) => {
+      error("Failed to start MCP server:", err);
+      exit(1);
+    });
   } else {
     printUsage();
   }