@nicnocquee/dataqueue 1.32.0 → 1.34.0

package/src/install-rules-command.ts

@@ -0,0 +1,233 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export interface InstallRulesDeps {
+  log?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+  exit?: (code: number) => void;
+  cwd?: string;
+  readFileSync?: (p: string, enc: BufferEncoding) => string;
+  writeFileSync?: (p: string, data: string) => void;
+  appendFileSync?: (p: string, data: string) => void;
+  mkdirSync?: (p: string, opts?: fs.MakeDirectoryOptions) => void;
+  existsSync?: (p: string) => boolean;
+  rulesSourceDir?: string;
+  /** Override for selecting the client (skips interactive prompt). */
+  selectedClient?: string;
+}
+
+const RULE_FILES = ['basic.md', 'advanced.md', 'react-dashboard.md'];
+
+interface ClientConfig {
+  label: string;
+  install: (
+    deps: Required<
+      Pick<
+        InstallRulesDeps,
+        | 'cwd'
+        | 'readFileSync'
+        | 'writeFileSync'
+        | 'appendFileSync'
+        | 'mkdirSync'
+        | 'existsSync'
+        | 'log'
+        | 'rulesSourceDir'
+      >
+    >,
+  ) => void;
+}
+
+const MARKER_START = '<!-- DATAQUEUE RULES START -->';
+const MARKER_END = '<!-- DATAQUEUE RULES END -->';
+
+/**
+ * Appends or replaces a marked section in a file.
+ *
+ * @param filePath - Path to the file to update.
+ * @param content - Content to insert between markers.
+ * @param deps - Injectable file system functions.
+ */
+export function upsertMarkedSection(
+  filePath: string,
+  content: string,
+  deps: {
+    readFileSync: (p: string, enc: BufferEncoding) => string;
+    writeFileSync: (p: string, data: string) => void;
+    existsSync: (p: string) => boolean;
+  },
+): void {
+  const block = `${MARKER_START}\n${content}\n${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: string,
+  readFileSync: (p: string, enc: BufferEncoding) => string,
+): string {
+  return RULE_FILES.map((f) =>
+    readFileSync(path.join(rulesSourceDir, f), 'utf-8'),
+  ).join('\n\n');
+}
+
+const CLIENTS: Record<string, ClientConfig> = {
+  '1': {
+    label: 'Cursor',
+    install: (deps) => {
+      const rulesDir = path.join(deps.cwd, '.cursor', 'rules');
+      deps.mkdirSync(rulesDir, { recursive: true });
+
+      for (const file of RULE_FILES) {
+        const src = deps.readFileSync(
+          path.join(deps.rulesSourceDir, file),
+          'utf-8',
+        );
+        const destName = `dataqueue-${file.replace(/\.md$/, '.mdc')}`;
+        deps.writeFileSync(path.join(rulesDir, destName), src);
+        deps.log(`  ✓ .cursor/rules/${destName}`);
+      }
+    },
+  },
+  '2': {
+    label: 'Claude Code',
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync,
+      );
+      const filePath = path.join(deps.cwd, 'CLAUDE.md');
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  ✓ CLAUDE.md`);
+    },
+  },
+  '3': {
+    label: 'AGENTS.md (Codex, Jules, OpenCode)',
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync,
+      );
+      const filePath = path.join(deps.cwd, 'AGENTS.md');
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  ✓ AGENTS.md`);
+    },
+  },
+  '4': {
+    label: 'GitHub Copilot',
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync,
+      );
+      deps.mkdirSync(path.join(deps.cwd, '.github'), { recursive: true });
+      const filePath = path.join(
+        deps.cwd,
+        '.github',
+        'copilot-instructions.md',
+      );
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  ✓ .github/copilot-instructions.md`);
+    },
+  },
+  '5': {
+    label: 'Windsurf',
+    install: (deps) => {
+      const content = getAllRulesContent(
+        deps.rulesSourceDir,
+        deps.readFileSync,
+      );
+      const filePath = path.join(deps.cwd, 'CONVENTIONS.md');
+      upsertMarkedSection(filePath, content, deps);
+      deps.log(`  ✓ CONVENTIONS.md`);
+    },
+  },
+};
+
+/**
+ * Installs DataQueue agent rules for the selected AI client.
+ *
+ * @param deps - Injectable dependencies for testing.
+ */
+export async function runInstallRules({
+  log = console.log,
+  error = console.error,
+  exit = (code: number) => process.exit(code),
+  cwd = process.cwd(),
+  readFileSync = fs.readFileSync,
+  writeFileSync = fs.writeFileSync,
+  appendFileSync = fs.appendFileSync,
+  mkdirSync = fs.mkdirSync,
+  existsSync = fs.existsSync,
+  rulesSourceDir = path.join(__dirname, '../ai/rules'),
+  selectedClient,
+}: InstallRulesDeps = {}): Promise<void> {
+  log('DataQueue Agent Rules Installer\n');
+  log('Select your AI client:\n');
+
+  for (const [key, client] of Object.entries(CLIENTS)) {
+    log(`  ${key}) ${client.label}`);
+  }
+  log('');
+
+  let choice = selectedClient;
+
+  if (!choice) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    choice = await new Promise<string>((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(`\nInstalling rules for ${client.label}...`);
+
+  try {
+    client.install({
+      cwd,
+      readFileSync,
+      writeFileSync,
+      appendFileSync,
+      mkdirSync,
+      existsSync,
+      log,
+      rulesSourceDir,
+    });
+    log('\nDone!');
+  } catch (err) {
+    error('Failed to install rules:', err);
+    exit(1);
+  }
+}

package/src/install-skills-command.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  runInstallSkills,
+  detectAiTools,
+  InstallSkillsDeps,
+} from './install-skills-command.js';
+
+describe('detectAiTools', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('detects Cursor when .cursor directory exists', () => {
+    // Setup
+    const existsSync = vi.fn((p: string) => p.endsWith('.cursor'));
+
+    // Act
+    const tools = detectAiTools('/project', existsSync);
+
+    // Assert
+    expect(tools).toEqual([{ name: 'Cursor', targetDir: '.cursor/skills' }]);
+  });
+
+  it('detects multiple AI tools', () => {
+    // Setup
+    const existsSync = vi.fn(() => true);
+
+    // Act
+    const tools = detectAiTools('/project', existsSync);
+
+    // Assert
+    expect(tools).toHaveLength(3);
+    expect(tools.map((t) => t.name)).toEqual([
+      'Cursor',
+      'Claude Code',
+      'GitHub Copilot',
+    ]);
+  });
+
+  it('returns empty array when no tools detected', () => {
+    // Setup
+    const existsSync = vi.fn(() => false);
+
+    // Act
+    const tools = detectAiTools('/project', existsSync);
+
+    // Assert
+    expect(tools).toEqual([]);
+  });
+});
+
+describe('runInstallSkills', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function makeDeps(
+    overrides: Partial<InstallSkillsDeps> = {},
+  ): InstallSkillsDeps {
+    return {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: vi.fn(),
+      cwd: '/project',
+      existsSync: vi.fn((p: string) => p.endsWith('.cursor')),
+      mkdirSync: vi.fn(),
+      copyFileSync: vi.fn(),
+      readdirSync: vi.fn(() => ['SKILL.md']),
+      skillsSourceDir: '/pkg/ai/skills',
+      ...overrides,
+    };
+  }
+
+  it('installs skills for detected AI tools', () => {
+    // Setup
+    const deps = makeDeps();
+
+    // Act
+    runInstallSkills(deps);
+
+    // Assert
+    expect(deps.mkdirSync).toHaveBeenCalledTimes(3);
+    expect(deps.copyFileSync).toHaveBeenCalledTimes(3);
+    expect(deps.log).toHaveBeenCalledWith(
+      expect.stringContaining('Done! Installed 3 skill(s)'),
+    );
+  });
+
+  it('creates .cursor/skills as default when no AI tools detected', () => {
+    // Setup
+    const deps = makeDeps({
+      existsSync: vi.fn(() => false),
+    });
+
+    // Act
+    runInstallSkills(deps);
+
+    // Assert
+    expect(deps.log).toHaveBeenCalledWith(
+      expect.stringContaining('Creating .cursor/skills/'),
+    );
+    expect(deps.mkdirSync).toHaveBeenCalled();
+  });
+
+  it('copies each SKILL.md file to the target directory', () => {
+    // Setup
+    const deps = makeDeps();
+
+    // Act
+    runInstallSkills(deps);
+
+    // Assert
+    expect(deps.copyFileSync).toHaveBeenCalledWith(
+      '/pkg/ai/skills/dataqueue-core/SKILL.md',
+      '/project/.cursor/skills/dataqueue-core/SKILL.md',
+    );
+    expect(deps.copyFileSync).toHaveBeenCalledWith(
+      '/pkg/ai/skills/dataqueue-advanced/SKILL.md',
+      '/project/.cursor/skills/dataqueue-advanced/SKILL.md',
+    );
+    expect(deps.copyFileSync).toHaveBeenCalledWith(
+      '/pkg/ai/skills/dataqueue-react/SKILL.md',
+      '/project/.cursor/skills/dataqueue-react/SKILL.md',
+    );
+  });
+
+  it('handles copy errors gracefully', () => {
+    // Setup
+    const deps = makeDeps({
+      copyFileSync: vi.fn(() => {
+        throw new Error('permission denied');
+      }),
+    });
+
+    // Act
+    runInstallSkills(deps);
+
+    // Assert
+    expect(deps.error).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to install'),
+      expect.any(Error),
+    );
+  });
+
+  it('exits with code 1 when all installs fail', () => {
+    // Setup
+    const deps = makeDeps({
+      readdirSync: vi.fn(() => {
+        throw new Error('not found');
+      }),
+    });
+
+    // Act
+    runInstallSkills(deps);
+
+    // Assert
+    expect(deps.error).toHaveBeenCalledWith('No skills were installed.');
+    expect(deps.exit).toHaveBeenCalledWith(1);
+  });
+
+  it('installs for multiple detected tools', () => {
+    // Setup
+    const deps = makeDeps({
+      existsSync: vi.fn(() => true),
+    });
+
+    // Act
+    runInstallSkills(deps);
+
+    // Assert
+    expect(deps.mkdirSync).toHaveBeenCalledTimes(9);
+    expect(deps.log).toHaveBeenCalledWith(
+      expect.stringContaining('Cursor, Claude Code, GitHub Copilot'),
+    );
+  });
+});

package/src/install-skills-command.ts

@@ -0,0 +1,124 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export interface InstallSkillsDeps {
+  log?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+  exit?: (code: number) => void;
+  cwd?: string;
+  existsSync?: (p: string) => boolean;
+  mkdirSync?: (p: string, opts?: fs.MakeDirectoryOptions) => void;
+  copyFileSync?: (src: string, dest: string) => void;
+  readdirSync?: (p: string) => string[];
+  skillsSourceDir?: string;
+}
+
+const SKILL_DIRS = ['dataqueue-core', 'dataqueue-advanced', 'dataqueue-react'];
+
+interface AiTool {
+  name: string;
+  targetDir: string;
+}
+
+/**
+ * Detects which AI tools have config directories in the project.
+ *
+ * @param cwd - Current working directory to scan.
+ * @param existsSync - Injectable fs.existsSync.
+ * @returns Array of detected AI tools with their skills target directories.
+ */
+export function detectAiTools(
+  cwd: string,
+  existsSync: (p: string) => boolean = fs.existsSync,
+): AiTool[] {
+  const tools: AiTool[] = [];
+  const checks: Array<{ name: string; indicator: string; targetDir: string }> =
+    [
+      {
+        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 (existsSync(path.join(cwd, check.indicator))) {
+      tools.push({ name: check.name, targetDir: check.targetDir });
+    }
+  }
+
+  return tools;
+}
+
+/**
+ * Installs DataQueue skill files into detected AI tool directories.
+ *
+ * @param deps - Injectable dependencies for testing.
+ */
+export function runInstallSkills({
+  log = console.log,
+  error = console.error,
+  exit = (code: number) => process.exit(code),
+  cwd = process.cwd(),
+  existsSync = fs.existsSync,
+  mkdirSync = fs.mkdirSync,
+  copyFileSync = fs.copyFileSync,
+  readdirSync = fs.readdirSync,
+  skillsSourceDir = path.join(__dirname, '../ai/skills'),
+}: InstallSkillsDeps = {}): void {
+  const tools = detectAiTools(cwd, existsSync);
+
+  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(`\nInstalling skills for ${tool.name}...`);
+
+    for (const skillDir of SKILL_DIRS) {
+      const srcDir = path.join(skillsSourceDir, skillDir);
+      const destDir = path.join(cwd, tool.targetDir, skillDir);
+
+      try {
+        mkdirSync(destDir, { recursive: true });
+
+        const files = readdirSync(srcDir);
+        for (const file of files) {
+          copyFileSync(path.join(srcDir, file), path.join(destDir, file));
+        }
+
+        log(`  ✓ ${skillDir}`);
+        installed++;
+      } catch (err) {
+        error(`  ✗ Failed to install ${skillDir}:`, err);
+      }
+    }
+  }
+
+  if (installed > 0) {
+    log(
+      `\nDone! Installed ${installed} skill(s) for ${tools.map((t) => t.name).join(', ')}.`,
+    );
+  } else {
+    error('No skills were installed.');
+    exit(1);
+  }
+}

package/src/mcp-server.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import {
+  loadDocsContent,
+  scorePageForQuery,
+  extractExcerpt,
+} from './mcp-server.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DOCS_CONTENT_PATH = path.join(__dirname, '../ai/docs-content.json');
+
+describe('loadDocsContent', () => {
+  it('loads the docs-content.json file', () => {
+    // Act
+    const pages = loadDocsContent(DOCS_CONTENT_PATH);
+
+    // Assert
+    expect(pages.length).toBeGreaterThan(0);
+    expect(pages[0]).toHaveProperty('slug');
+    expect(pages[0]).toHaveProperty('title');
+    expect(pages[0]).toHaveProperty('content');
+  });
+
+  it('throws for non-existent file', () => {
+    // Act & Assert
+    expect(() => loadDocsContent('/nonexistent/path.json')).toThrow();
+  });
+});
+
+describe('scorePageForQuery', () => {
+  it('scores title matches highest', () => {
+    // Setup
+    const page = {
+      slug: 'test',
+      title: 'Cron Jobs',
+      description: 'Schedule recurring tasks',
+      content: 'Use cron expressions.',
+    };
+
+    // Act
+    const score = scorePageForQuery(page, ['cron']);
+
+    // Assert
+    expect(score).toBeGreaterThanOrEqual(10);
+  });
+
+  it('scores description matches', () => {
+    // Setup
+    const page = {
+      slug: 'test',
+      title: 'Other Page',
+      description: 'Schedule recurring cron tasks',
+      content: 'No match in content.',
+    };
+
+    // Act
+    const score = scorePageForQuery(page, ['cron']);
+
+    // Assert
+    expect(score).toBeGreaterThanOrEqual(5);
+  });
+
+  it('scores content matches', () => {
+    // Setup
+    const page = {
+      slug: 'test',
+      title: 'Other',
+      description: 'Other',
+      content: 'Use cron for scheduling. Cron is powerful.',
+    };
+
+    // Act
+    const score = scorePageForQuery(page, ['cron']);
+
+    // Assert
+    expect(score).toBeGreaterThan(0);
+  });
+
+  it('returns 0 for no matches', () => {
+    // Setup
+    const page = {
+      slug: 'test',
+      title: 'Unrelated',
+      description: 'Nothing here',
+      content: 'No match.',
+    };
+
+    // Act
+    const score = scorePageForQuery(page, ['zzzzzzz']);
+
+    // Assert
+    expect(score).toBe(0);
+  });
+
+  it('handles multiple query terms', () => {
+    // Setup
+    const page = {
+      slug: 'test',
+      title: 'Cron Jobs',
+      description: 'Schedule tasks',
+      content: 'timeout and cron are related.',
+    };
+
+    // Act
+    const scoreMulti = scorePageForQuery(page, ['cron', 'timeout']);
+    const scoreSingle = scorePageForQuery(page, ['cron']);
+
+    // Assert
+    expect(scoreMulti).toBeGreaterThan(scoreSingle);
+  });
+});
+
+describe('extractExcerpt', () => {
+  it('extracts content around the first matching term', () => {
+    // Setup
+    const content = 'A'.repeat(200) + 'target keyword here' + 'B'.repeat(200);
+
+    // Act
+    const excerpt = extractExcerpt(content, ['target']);
+
+    // Assert
+    expect(excerpt).toContain('target keyword here');
+    expect(excerpt.length).toBeLessThanOrEqual(510);
+  });
+
+  it('returns beginning of content when no match found', () => {
+    // Setup
+    const content = 'This is the beginning of the content. More content here.';
+
+    // Act
+    const excerpt = extractExcerpt(content, ['nonexistent']);
+
+    // Assert
+    expect(excerpt).toBe(content);
+  });
+
+  it('adds ellipsis when excerpt is truncated', () => {
+    // Setup
+    const content = 'A'.repeat(300) + 'match' + 'B'.repeat(300);
+
+    // Act
+    const excerpt = extractExcerpt(content, ['match'], 200);
+
+    // Assert
+    expect(excerpt.startsWith('...')).toBe(true);
+    expect(excerpt.endsWith('...')).toBe(true);
+  });
+
+  it('respects maxLength parameter', () => {
+    // Setup
+    const content = 'A'.repeat(1000);
+
+    // Act
+    const excerpt = extractExcerpt(content, ['nonexistent'], 100);
+
+    // Assert
+    expect(excerpt.length).toBeLessThanOrEqual(100);
+  });
+});