@nicnocquee/dataqueue 1.25.0 → 1.26.0-beta.20260223202259

package/src/cli.test.ts

@@ -22,6 +22,11 @@ function makeDeps() {
     exit: vi.fn(),
     spawnSyncImpl: vi.fn(() => makeSpawnSyncReturns(0)),
     migrationsDir: '/migrations',
+    runInitImpl: vi.fn(),
+    runInstallSkillsImpl: vi.fn(),
+    runInstallRulesImpl: vi.fn(async () => {}),
+    runInstallMcpImpl: vi.fn(async () => {}),
+    startMcpServerImpl: vi.fn(async () => ({}) as any),
   } satisfies CliDeps;
 }
 
@@ -34,20 +39,30 @@ describe('runCli', () => {
 
   it('prints usage and exits with code 1 for no command', () => {
     runCli(['node', 'cli.js'], deps);
-    expect(deps.log).toHaveBeenCalledWith(
-      'Usage: dataqueue-cli migrate [--envPath <path>] [-s <schema> | --schema <schema>]',
-    );
+    expect(deps.log).toHaveBeenCalledWith('Usage:');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli init');
     expect(deps.exit).toHaveBeenCalledWith(1);
   });
 
   it('prints usage and exits with code 1 for unknown command', () => {
     runCli(['node', 'cli.js', 'unknown'], deps);
-    expect(deps.log).toHaveBeenCalledWith(
-      'Usage: dataqueue-cli migrate [--envPath <path>] [-s <schema> | --schema <schema>]',
-    );
+    expect(deps.log).toHaveBeenCalledWith('Usage:');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli init');
     expect(deps.exit).toHaveBeenCalledWith(1);
   });
 
+  it('routes init command to runInitImpl', () => {
+    runCli(['node', 'cli.js', 'init'], deps);
+    expect(deps.runInitImpl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        log: deps.log,
+        error: deps.error,
+        exit: deps.exit,
+      }),
+    );
+    expect(deps.spawnSyncImpl).not.toHaveBeenCalled();
+  });
+
   it('calls spawnSyncImpl with correct args for migrate', () => {
     runCli(['node', 'cli.js', 'migrate'], deps);
     expect(deps.spawnSyncImpl).toHaveBeenCalledWith(
@@ -127,4 +142,65 @@ describe('runCli', () => {
     runCli(['node', 'cli.js', 'migrate'], deps);
     expect(deps.exit).toHaveBeenCalledWith(1);
   });
+
+  it('routes install-skills command to runInstallSkillsImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'install-skills'], deps);
+
+    // Assert
+    expect(deps.runInstallSkillsImpl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        log: deps.log,
+        error: deps.error,
+        exit: deps.exit,
+      }),
+    );
+  });
+
+  it('routes install-rules command to runInstallRulesImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'install-rules'], deps);
+
+    // Assert
+    expect(deps.runInstallRulesImpl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        log: deps.log,
+        error: deps.error,
+        exit: deps.exit,
+      }),
+    );
+  });
+
+  it('routes install-mcp command to runInstallMcpImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'install-mcp'], deps);
+
+    // Assert
+    expect(deps.runInstallMcpImpl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        log: deps.log,
+        error: deps.error,
+        exit: deps.exit,
+      }),
+    );
+  });
+
+  it('routes mcp command to startMcpServerImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'mcp'], deps);
+
+    // Assert
+    expect(deps.startMcpServerImpl).toHaveBeenCalled();
+  });
+
+  it('shows new commands in usage output', () => {
+    // Act
+    runCli(['node', 'cli.js'], deps);
+
+    // Assert
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli install-skills');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli install-rules');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli install-mcp');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli mcp');
+  });
 });

package/src/cli.ts

@@ -2,6 +2,14 @@
 import { spawnSync, SpawnSyncReturns } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { InitDeps, runInit } from './init-command.js';
+import {
+  runInstallSkills,
+  InstallSkillsDeps,
+} from './install-skills-command.js';
+import { runInstallRules, InstallRulesDeps } from './install-rules-command.js';
+import { runInstallMcp, InstallMcpDeps } from './install-mcp-command.js';
+import { startMcpServer } from './mcp-server.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -12,25 +20,50 @@ export interface CliDeps {
   exit?: (code: number) => void;
   spawnSyncImpl?: (...args: any[]) => SpawnSyncReturns<any>;
   migrationsDir?: string;
+  initDeps?: InitDeps;
+  runInitImpl?: (deps?: InitDeps) => void;
+  installSkillsDeps?: InstallSkillsDeps;
+  runInstallSkillsImpl?: (deps?: InstallSkillsDeps) => void;
+  installRulesDeps?: InstallRulesDeps;
+  runInstallRulesImpl?: (deps?: InstallRulesDeps) => Promise<void>;
+  installMcpDeps?: InstallMcpDeps;
+  runInstallMcpImpl?: (deps?: InstallMcpDeps) => Promise<void>;
+  startMcpServerImpl?: typeof startMcpServer;
 }
 
 export function runCli(
   argv: string[],
   {
     log = console.log,
+    error = console.error,
     exit = (code: number) => process.exit(code),
     spawnSyncImpl = spawnSync,
     migrationsDir = path.join(__dirname, '../migrations'),
+    initDeps,
+    runInitImpl = runInit,
+    installSkillsDeps,
+    runInstallSkillsImpl = runInstallSkills,
+    installRulesDeps,
+    runInstallRulesImpl = runInstallRules,
+    installMcpDeps,
+    runInstallMcpImpl = runInstallMcp,
+    startMcpServerImpl = startMcpServer,
   }: CliDeps = {},
 ): void {
   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)',
     );
@@ -38,16 +71,13 @@ export function runCli(
       '  -s, --schema <schema>  Set the schema to use (passed to node-pg-migrate)',
     );
     log('');
-    log('Notes:');
+    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(
-      '  - 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',
+      '  install-mcp        Configure the DataQueue MCP server for AI clients',
     );
+    log('  mcp                Start the DataQueue MCP server (stdio)');
     exit(1);
   }
 
@@ -89,6 +119,39 @@ export function runCli(
       { 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();
   }

package/src/cron.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { getNextCronOccurrence, validateCronExpression } from './cron.js';
+
+describe('getNextCronOccurrence', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns the next occurrence for a every-5-minutes expression', () => {
+    // Setup
+    const after = new Date('2026-01-15T10:02:00Z');
+
+    // Act
+    const next = getNextCronOccurrence('*/5 * * * *', 'UTC', after);
+
+    // Assert
+    expect(next).toEqual(new Date('2026-01-15T10:05:00Z'));
+  });
+
+  it('returns the next occurrence for a daily-at-midnight expression', () => {
+    // Setup
+    const after = new Date('2026-01-15T10:00:00Z');
+
+    // Act
+    const next = getNextCronOccurrence('0 0 * * *', 'UTC', after);
+
+    // Assert
+    expect(next).toEqual(new Date('2026-01-16T00:00:00Z'));
+  });
+
+  it('uses the current time when after is not provided', () => {
+    // Act
+    const next = getNextCronOccurrence('*/5 * * * *');
+
+    // Assert
+    expect(next).toBeInstanceOf(Date);
+    expect(next!.getTime()).toBeGreaterThan(Date.now() - 1000);
+  });
+
+  it('respects a non-UTC timezone', () => {
+    // Setup — 10:02 UTC is 19:02 in Asia/Tokyo (UTC+9)
+    const after = new Date('2026-01-15T10:02:00Z');
+
+    // Act — "0 20 * * *" = daily at 20:00 Tokyo time = 11:00 UTC
+    const next = getNextCronOccurrence('0 20 * * *', 'Asia/Tokyo', after);
+
+    // Assert
+    expect(next).toEqual(new Date('2026-01-15T11:00:00Z'));
+  });
+
+  it('returns null when expression cannot produce a future match', () => {
+    // Setup — Feb 30 never exists: "0 0 30 2 *"
+    const after = new Date('2026-01-01T00:00:00Z');
+
+    // Act
+    const next = getNextCronOccurrence('0 0 30 2 *', 'UTC', after);
+
+    // Assert
+    expect(next).toBeNull();
+  });
+
+  it('defaults to UTC timezone', () => {
+    // Setup
+    const after = new Date('2026-06-01T23:58:00Z');
+
+    // Act
+    const next = getNextCronOccurrence('0 0 * * *', undefined, after);
+
+    // Assert
+    expect(next).toEqual(new Date('2026-06-02T00:00:00Z'));
+  });
+});
+
+describe('validateCronExpression', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns true for a valid every-minute expression', () => {
+    // Act
+    const result = validateCronExpression('* * * * *');
+
+    // Assert
+    expect(result).toBe(true);
+  });
+
+  it('returns true for a valid complex expression', () => {
+    // Act
+    const result = validateCronExpression('0 9-17 * * 1-5');
+
+    // Assert
+    expect(result).toBe(true);
+  });
+
+  it('returns false for an invalid expression with too few fields', () => {
+    // Act
+    const result = validateCronExpression('* *');
+
+    // Assert
+    expect(result).toBe(false);
+  });
+
+  it('returns false for an empty string', () => {
+    // Act
+    const result = validateCronExpression('');
+
+    // Assert
+    expect(result).toBe(false);
+  });
+
+  it('returns false for a completely invalid string', () => {
+    // Act
+    const result = validateCronExpression('not a cron expression');
+
+    // Assert
+    expect(result).toBe(false);
+  });
+
+  it('returns true for an expression with step values', () => {
+    // Act
+    const result = validateCronExpression('*/15 * * * *');
+
+    // Assert
+    expect(result).toBe(true);
+  });
+});

package/src/cron.ts

@@ -0,0 +1,40 @@
+import { Cron } from 'croner';
+
+/**
+ * Calculate the next occurrence of a cron expression after a given date.
+ *
+ * @param cronExpression - A standard cron expression (5 fields, e.g. "0 * * * *").
+ * @param timezone - IANA timezone string (default: "UTC").
+ * @param after - The reference date to compute the next run from (default: now).
+ * @param CronImpl - Cron class for dependency injection (default: croner's Cron).
+ * @returns The next occurrence as a Date, or null if the expression will never fire again.
+ */
+export function getNextCronOccurrence(
+  cronExpression: string,
+  timezone: string = 'UTC',
+  after?: Date,
+  CronImpl: typeof Cron = Cron,
+): Date | null {
+  const cron = new CronImpl(cronExpression, { timezone });
+  const next = cron.nextRun(after ?? new Date());
+  return next ?? null;
+}
+
+/**
+ * Validate whether a string is a syntactically correct cron expression.
+ *
+ * @param cronExpression - The cron expression to validate.
+ * @param CronImpl - Cron class for dependency injection (default: croner's Cron).
+ * @returns True if the expression is valid, false otherwise.
+ */
+export function validateCronExpression(
+  cronExpression: string,
+  CronImpl: typeof Cron = Cron,
+): boolean {
+  try {
+    new CronImpl(cronExpression);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/db-util.ts

@@ -27,7 +27,7 @@ function loadPemOrFile(value?: string): string | undefined {
  *   }
  */
 export const createPool = (
-  config: PostgresJobQueueConfig['databaseConfig'],
+  config: NonNullable<PostgresJobQueueConfig['databaseConfig']>,
 ): Pool => {
   let searchPath: string | undefined;
   let ssl: any = undefined;