@nicnocquee/dataqueue 1.32.0 → 1.34.0

package/dist/cli.js

@@ -1,23 +1,1126 @@
 import { spawnSync } from 'child_process';
-import path from 'path';
+import path3 from 'path';
 import { fileURLToPath } from 'url';
+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 = [
+  "@nicnocquee/dataqueue",
+  "@nicnocquee/dataqueue-dashboard",
+  "@nicnocquee/dataqueue-react"
+];
+var DEV_DEPENDENCIES_TO_ADD = [
+  "dotenv-cli",
+  "ts-node",
+  "node-pg-migrate"
+];
+var SCRIPTS_TO_ADD = {
+  cron: "bash cron.sh",
+  "migrate-dataqueue": "dotenv -e .env.local -- dataqueue-cli migrate"
+};
+var APP_ROUTER_ROUTE_TEMPLATE = `/**
+ * This end point is used to manage the job queue.
+ * It supports the following tasks:
+ * - reclaim: Reclaim stuck jobs
+ * - cleanup: Cleanup old jobs
+ * - process: Process jobs
+ *
+ * Example usage with default values (reclaim stuck jobs for 10 minutes, cleanup old jobs for 30 days, and process jobs with batch size 3, concurrency 2, and verbose true):
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/reclaim -H "Authorization: Bearer $CRON_SECRET"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/cleanup -H "Authorization: Bearer $CRON_SECRET"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/process -H "Authorization: Bearer $CRON_SECRET"
+ *
+ * Example usage with custom values:
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/reclaim -H "Authorization: Bearer $CRON_SECRET" -d '{"maxProcessingTimeMinutes": 15}' -H "Content-Type: application/json"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/cleanup -H "Authorization: Bearer $CRON_SECRET" -d '{"daysToKeep": 15}' -H "Content-Type: application/json"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/process -H "Authorization: Bearer $CRON_SECRET" -d '{"batchSize": 5, "concurrency": 3, "verbose": false, "workerId": "custom-worker-id"}' -H "Content-Type: application/json"
+ *
+ * During development, you can run the following script to run the cron jobs continuously in the background:
+ * pnpm cron
+ */
+import { getJobQueue, jobHandlers } from '@/lib/dataqueue/queue';
+import { NextResponse } from 'next/server';
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ task: string[] }> },
+) {
+  const { task } = await params;
+  const authHeader = request.headers.get('authorization');
+  if (authHeader !== \`Bearer \${process.env.CRON_SECRET}\`) {
+    return NextResponse.json({ message: 'Unauthorized' }, { status: 401 });
+  }
+
+  if (!task || task.length === 0) {
+    return NextResponse.json({ message: 'Task is required' }, { status: 400 });
+  }
+
+  const supportedTasks = ['reclaim', 'cleanup', 'process'];
+  const theTask = task[0];
+  if (!supportedTasks.includes(theTask)) {
+    return NextResponse.json(
+      { message: 'Task not supported' },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const jobQueue = getJobQueue();
+
+    if (theTask === 'reclaim') {
+      let maxProcessingTimeMinutes = 10;
+      try {
+        const body = await request.json();
+        maxProcessingTimeMinutes = body.maxProcessingTimeMinutes || 10;
+      } catch {
+        // ignore parsing error and use default value
+      }
+      const reclaimed = await jobQueue.reclaimStuckJobs(
+        maxProcessingTimeMinutes,
+      );
+      console.log(\`Reclaimed \${reclaimed} stuck jobs\`);
+      return NextResponse.json({
+        message: \`Stuck jobs reclaimed: \${reclaimed} with maxProcessingTimeMinutes: \${maxProcessingTimeMinutes}\`,
+        reclaimed,
+      });
+    }
+
+    if (theTask === 'cleanup') {
+      let daysToKeep = 30;
+      try {
+        const body = await request.json();
+        daysToKeep = body.daysToKeep || 30;
+      } catch {
+        // ignore parsing error and use default value
+      }
+      const deleted = await jobQueue.cleanupOldJobs(daysToKeep);
+      console.log(\`Deleted \${deleted} old jobs\`);
+      return NextResponse.json({
+        message: \`Old jobs cleaned up: \${deleted} with daysToKeep: \${daysToKeep}\`,
+        deleted,
+      });
+    }
+
+    if (theTask === 'process') {
+      let batchSize = 3;
+      let concurrency = 2;
+      let verbose = true;
+      let workerId = \`manage-\${theTask}-\${Date.now()}\`;
+      try {
+        const body = await request.json();
+        batchSize = body.batchSize || 3;
+        concurrency = body.concurrency || 2;
+        verbose = body.verbose || true;
+        workerId = body.workerId || \`manage-\${theTask}-\${Date.now()}\`;
+      } catch {
+        // ignore parsing error and use default value
+      }
+      const processor = jobQueue.createProcessor(jobHandlers, {
+        workerId,
+        batchSize,
+        concurrency,
+        verbose,
+      });
+      const processed = await processor.start();
+
+      return NextResponse.json({
+        message: \`Jobs processed: \${processed} with workerId: \${workerId}, batchSize: \${batchSize}, concurrency: \${concurrency}, and verbose: \${verbose}\`,
+        processed,
+      });
+    }
+
+    return NextResponse.json(
+      { message: 'Task not supported' },
+      { status: 400 },
+    );
+  } catch (error) {
+    console.error('Error processing jobs:', error);
+    return NextResponse.json(
+      { message: 'Failed to process jobs' },
+      { status: 500 },
+    );
+  }
+}
+`;
+var PAGES_ROUTER_ROUTE_TEMPLATE = `/**
+ * This end point is used to manage the job queue.
+ * It supports the following tasks:
+ * - reclaim: Reclaim stuck jobs
+ * - cleanup: Cleanup old jobs
+ * - process: Process jobs
+ *
+ * Example usage with default values (reclaim stuck jobs for 10 minutes, cleanup old jobs for 30 days, and process jobs with batch size 3, concurrency 2, and verbose true):
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/reclaim -H "Authorization: Bearer $CRON_SECRET"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/cleanup -H "Authorization: Bearer $CRON_SECRET"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/process -H "Authorization: Bearer $CRON_SECRET"
+ *
+ * Example usage with custom values:
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/reclaim -H "Authorization: Bearer $CRON_SECRET" -d '{"maxProcessingTimeMinutes": 15}' -H "Content-Type: application/json"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/cleanup -H "Authorization: Bearer $CRON_SECRET" -d '{"daysToKeep": 15}' -H "Content-Type: application/json"
+ * curl -X POST http://localhost:3000/api/dataqueue/manage/process -H "Authorization: Bearer $CRON_SECRET" -d '{"batchSize": 5, "concurrency": 3, "verbose": false, "workerId": "custom-worker-id"}' -H "Content-Type: application/json"
+ *
+ * During development, you can run the following script to run the cron jobs continuously in the background:
+ * pnpm cron
+ */
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { getJobQueue, jobHandlers } from '@/lib/dataqueue/queue';
+
+type ResponseBody = {
+  message: string;
+  reclaimed?: number;
+  deleted?: number;
+  processed?: number;
+};
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse<ResponseBody>,
+) {
+  if (req.method !== 'POST') {
+    res.setHeader('Allow', 'POST');
+    return res.status(405).json({ message: 'Method not allowed' });
+  }
+
+  const authHeader = req.headers.authorization;
+  if (authHeader !== \`Bearer \${process.env.CRON_SECRET}\`) {
+    return res.status(401).json({ message: 'Unauthorized' });
+  }
+
+  const task = req.query.task;
+  const taskArray = Array.isArray(task) ? task : task ? [task] : [];
+  if (!taskArray.length) {
+    return res.status(400).json({ message: 'Task is required' });
+  }
+
+  const supportedTasks = ['reclaim', 'cleanup', 'process'];
+  const theTask = taskArray[0];
+  if (!supportedTasks.includes(theTask)) {
+    return res.status(400).json({ message: 'Task not supported' });
+  }
+
+  try {
+    const jobQueue = getJobQueue();
+    const body = typeof req.body === 'object' && req.body ? req.body : {};
+
+    if (theTask === 'reclaim') {
+      const maxProcessingTimeMinutes = body.maxProcessingTimeMinutes || 10;
+      const reclaimed = await jobQueue.reclaimStuckJobs(maxProcessingTimeMinutes);
+      console.log(\`Reclaimed \${reclaimed} stuck jobs\`);
+      return res.status(200).json({
+        message: \`Stuck jobs reclaimed: \${reclaimed} with maxProcessingTimeMinutes: \${maxProcessingTimeMinutes}\`,
+        reclaimed,
+      });
+    }
+
+    if (theTask === 'cleanup') {
+      const daysToKeep = body.daysToKeep || 30;
+      const deleted = await jobQueue.cleanupOldJobs(daysToKeep);
+      console.log(\`Deleted \${deleted} old jobs\`);
+      return res.status(200).json({
+        message: \`Old jobs cleaned up: \${deleted} with daysToKeep: \${daysToKeep}\`,
+        deleted,
+      });
+    }
+
+    const batchSize = body.batchSize || 3;
+    const concurrency = body.concurrency || 2;
+    const verbose = body.verbose || true;
+    const workerId = body.workerId || \`manage-\${theTask}-\${Date.now()}\`;
+    const processor = jobQueue.createProcessor(jobHandlers, {
+      workerId,
+      batchSize,
+      concurrency,
+      verbose,
+    });
+    const processed = await processor.start();
+
+    return res.status(200).json({
+      message: \`Jobs processed: \${processed} with workerId: \${workerId}, batchSize: \${batchSize}, concurrency: \${concurrency}, and verbose: \${verbose}\`,
+      processed,
+    });
+  } catch (error) {
+    console.error('Error processing jobs:', error);
+    return res.status(500).json({ message: 'Failed to process jobs' });
+  }
+}
+`;
+var CRON_SH_TEMPLATE = `#!/bin/bash
+
+# This script is used to run the cron jobs for the demo app during development.
+# Run it with \`pnpm cron\` from the apps/demo directory.
+
+set -a
+source "$(dirname "$0")/.env.local"
+set +a
+
+if [ -z "$CRON_SECRET" ]; then
+  echo "Error: CRON_SECRET environment variable is not set in .env.local"
+  exit 1
+fi
+
+cleanup() {
+  kill 0
+  wait
+}
+trap cleanup SIGINT SIGTERM
+
+while true; do
+  echo "Processing jobs..."
+  curl http://localhost:3000/api/dataqueue/manage/process -X POST -H "Authorization: Bearer $CRON_SECRET"
+  echo ""
+  sleep 10 # Process jobs every 10 seconds
+done &
+
+while true; do
+  echo "Reclaiming stuck jobs..."
+  curl http://localhost:3000/api/dataqueue/manage/reclaim -X POST -H "Authorization: Bearer $CRON_SECRET"
+  echo ""
+  sleep 20 # Reclaim stuck jobs every 20 seconds
+done &
+
+while true; do
+  echo "Cleaning up old jobs..."
+  curl http://localhost:3000/api/dataqueue/manage/cleanup -X POST -H "Authorization: Bearer $CRON_SECRET"
+  echo ""
+  sleep 30 # Cleanup old jobs every 30 seconds
+done &
+
+wait
+`;
+var QUEUE_TEMPLATE = `import { initJobQueue, JobHandlers } from '@nicnocquee/dataqueue';
+
+export type JobPayloadMap = {
+  send_email: {
+    to: string;
+    subject: string;
+    body: string;
+  };
+};
+
+let jobQueue: ReturnType<typeof initJobQueue<JobPayloadMap>> | null = null;
+
+export const getJobQueue = () => {
+  if (!jobQueue) {
+    jobQueue = initJobQueue<JobPayloadMap>({
+      databaseConfig: {
+        connectionString: process.env.PG_DATAQUEUE_DATABASE,
+      },
+      verbose: process.env.NODE_ENV === 'development',
+    });
+  }
+  return jobQueue;
+};
+
+export const jobHandlers: JobHandlers<JobPayloadMap> = {
+  send_email: async (payload) => {
+    const { to, subject, body } = payload;
+    console.log('send_email placeholder:', { to, subject, body });
+  },
+};
+`;
+function runInit({
+  log = console.log,
+  error = console.error,
+  exit = (code) => process.exit(code),
+  cwd = process.cwd(),
+  readFileSyncImpl = readFileSync,
+  writeFileSyncImpl = writeFileSync,
+  existsSyncImpl = existsSync,
+  mkdirSyncImpl = mkdirSync,
+  chmodSyncImpl = chmodSync
+} = {}) {
+  try {
+    log(`dataqueue: Initializing in ${cwd}...`);
+    log("");
+    const details = detectNextJsAndRouter({
+      cwd,
+      existsSyncImpl,
+      readFileSyncImpl
+    });
+    createScaffoldFiles({
+      details,
+      log,
+      existsSyncImpl,
+      mkdirSyncImpl,
+      writeFileSyncImpl,
+      chmodSyncImpl
+    });
+    updatePackageJson({
+      details,
+      log,
+      writeFileSyncImpl
+    });
+    log("");
+    log(
+      "Done! Run your package manager's install command to install new dependencies."
+    );
+    exit(0);
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    error(`dataqueue: ${message}`);
+    exit(1);
+  }
+}
+function detectNextJsAndRouter({
+  cwd,
+  existsSyncImpl,
+  readFileSyncImpl
+}) {
+  const packageJsonPath = path3.join(cwd, "package.json");
+  if (!existsSyncImpl(packageJsonPath)) {
+    throw new Error("package.json not found in current directory.");
+  }
+  const packageJson = parsePackageJson(
+    readFileSyncImpl(packageJsonPath, "utf8"),
+    packageJsonPath
+  );
+  if (!isNextJsProject(packageJson)) {
+    throw new Error(
+      "Not a Next.js project. Could not find 'next' in package.json dependencies."
+    );
+  }
+  const srcDir = path3.join(cwd, "src");
+  const srcRoot = existsSyncImpl(srcDir) ? "src" : ".";
+  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) {
+    throw new Error(
+      "Could not detect Next.js router. Expected either app/ or pages/ directory."
+    );
+  }
+  const router = hasAppDir ? "app" : "pages";
+  return { cwd, packageJsonPath, packageJson, srcRoot, router };
+}
+function updatePackageJson({
+  details,
+  log,
+  writeFileSyncImpl
+}) {
+  const packageJson = details.packageJson;
+  const dependencies = ensureStringMapSection(packageJson, "dependencies");
+  const devDependencies = ensureStringMapSection(
+    packageJson,
+    "devDependencies"
+  );
+  const scripts = ensureStringMapSection(packageJson, "scripts");
+  for (const dependency of DEPENDENCIES_TO_ADD) {
+    if (dependencies[dependency]) {
+      log(`  [skipped] dependency ${dependency} (already exists)`);
+      continue;
+    }
+    dependencies[dependency] = "latest";
+    log(`  [added]   dependency ${dependency}`);
+  }
+  for (const devDependency of DEV_DEPENDENCIES_TO_ADD) {
+    if (devDependencies[devDependency]) {
+      log(`  [skipped] devDependency ${devDependency} (already exists)`);
+      continue;
+    }
+    devDependencies[devDependency] = "latest";
+    log(`  [added]   devDependency ${devDependency}`);
+  }
+  for (const [scriptName, scriptValue] of Object.entries(SCRIPTS_TO_ADD)) {
+    if (scripts[scriptName]) {
+      log(`  [skipped] script "${scriptName}" (already exists)`);
+      continue;
+    }
+    scripts[scriptName] = scriptValue;
+    log(`  [added]   script "${scriptName}"`);
+  }
+  writeFileSyncImpl(
+    details.packageJsonPath,
+    `${JSON.stringify(packageJson, null, 2)}
+`
+  );
+}
+function createScaffoldFiles({
+  details,
+  log,
+  existsSyncImpl,
+  mkdirSyncImpl,
+  writeFileSyncImpl,
+  chmodSyncImpl
+}) {
+  const appRoutePath = path3.join(
+    details.cwd,
+    details.srcRoot,
+    "app",
+    "api",
+    "dataqueue",
+    "manage",
+    "[[...task]]",
+    "route.ts"
+  );
+  const pagesRoutePath = path3.join(
+    details.cwd,
+    details.srcRoot,
+    "pages",
+    "api",
+    "dataqueue",
+    "manage",
+    "[[...task]].ts"
+  );
+  const queuePath = path3.join(
+    details.cwd,
+    details.srcRoot,
+    "lib",
+    "dataqueue",
+    "queue.ts"
+  );
+  const cronPath = path3.join(details.cwd, "cron.sh");
+  if (details.router === "app") {
+    createFileIfMissing({
+      absolutePath: appRoutePath,
+      content: APP_ROUTER_ROUTE_TEMPLATE,
+      existsSyncImpl,
+      mkdirSyncImpl,
+      writeFileSyncImpl,
+      log,
+      logPath: toRelativePath(details.cwd, appRoutePath)
+    });
+    log(
+      "  [skipped] pages/api/dataqueue/manage/[[...task]].ts (router not selected)"
+    );
+  } else {
+    log(
+      "  [skipped] app/api/dataqueue/manage/[[...task]]/route.ts (router not selected)"
+    );
+    createFileIfMissing({
+      absolutePath: pagesRoutePath,
+      content: PAGES_ROUTER_ROUTE_TEMPLATE,
+      existsSyncImpl,
+      mkdirSyncImpl,
+      writeFileSyncImpl,
+      log,
+      logPath: toRelativePath(details.cwd, pagesRoutePath)
+    });
+  }
+  createFileIfMissing({
+    absolutePath: cronPath,
+    content: CRON_SH_TEMPLATE,
+    existsSyncImpl,
+    mkdirSyncImpl,
+    writeFileSyncImpl,
+    log,
+    logPath: "cron.sh"
+  });
+  if (existsSyncImpl(cronPath)) {
+    chmodSyncImpl(cronPath, 493);
+  }
+  createFileIfMissing({
+    absolutePath: queuePath,
+    content: QUEUE_TEMPLATE,
+    existsSyncImpl,
+    mkdirSyncImpl,
+    writeFileSyncImpl,
+    log,
+    logPath: toRelativePath(details.cwd, queuePath)
+  });
+}
+function createFileIfMissing({
+  absolutePath,
+  content,
+  existsSyncImpl,
+  mkdirSyncImpl,
+  writeFileSyncImpl,
+  log,
+  logPath
+}) {
+  if (existsSyncImpl(absolutePath)) {
+    log(`  [skipped] ${logPath} (already exists)`);
+    return;
+  }
+  mkdirSyncImpl(path3.dirname(absolutePath), { recursive: true });
+  writeFileSyncImpl(absolutePath, content);
+  log(`  [created] ${logPath}`);
+}
+function parsePackageJson(content, filePath) {
+  try {
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("package.json must contain an object.");
+    }
+    return parsed;
+  } catch (cause) {
+    throw new Error(
+      `Failed to parse package.json at ${filePath}: ${cause instanceof Error ? cause.message : String(cause)}`
+    );
+  }
+}
+function isNextJsProject(packageJson) {
+  const dependencies = packageJson.dependencies;
+  const devDependencies = packageJson.devDependencies;
+  return hasPackage(dependencies, "next") || hasPackage(devDependencies, "next");
+}
+function hasPackage(section, packageName) {
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    return false;
+  }
+  return Boolean(section[packageName]);
+}
+function ensureStringMapSection(packageJson, sectionName) {
+  const currentValue = packageJson[sectionName];
+  if (!currentValue || typeof currentValue !== "object" || Array.isArray(currentValue)) {
+    packageJson[sectionName] = {};
+  }
+  return packageJson[sectionName];
+}
+function toRelativePath(cwd, absolutePath) {
+  const relative = path3.relative(cwd, absolutePath);
+  return relative || ".";
+}
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = path.dirname(__filename);
+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 __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,
+  installSkillsDeps,
+  runInstallSkillsImpl = runInstallSkills,
+  installRulesDeps,
+  runInstallRulesImpl = runInstallRules,
+  installMcpDeps,
+  runInstallMcpImpl = runInstallMcp,
+  startMcpServerImpl = startMcpServer
 } = {}) {
   const [, , command, ...restArgs] = argv;
   function printUsage() {
+    log("Usage:");
     log(
-      "Usage: dataqueue-cli migrate [--envPath <path>] [-s <schema> | --schema <schema>]"
+      "  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:");
+    log("Options for migrate:");
     log(
       "  --envPath <path>   Path to a .env file to load environment variables (passed to node-pg-migrate)"
     );
@@ -25,16 +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("AI tooling commands:");
+    log("  install-skills     Install DataQueue skill files for AI assistants");
+    log("  install-rules      Install DataQueue agent rules for AI clients");
     log(
-      "    Example: PGSSLMODE=require NODE_EXTRA_CA_CERTS=/absolute/path/to/ca.crt PG_DATAQUEUE_DATABASE=... npx dataqueue-cli migrate"
+      "  install-mcp        Configure the DataQueue MCP server for AI clients"
     );
+    log("  mcp                Start the DataQueue MCP server (stdio)");
     exit(1);
   }
   if (command === "migrate") {
@@ -71,6 +1171,39 @@ function runCli(argv, {
       { stdio: "inherit" }
     );
     exit(result.status ?? 1);
+  } else if (command === "init") {
+    runInitImpl({
+      log,
+      error,
+      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();
   }