instar 0.1.0

package/tests/unit/JobLoader.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { loadJobs, validateJob } from '../../src/scheduler/JobLoader.js';
+
+describe('JobLoader', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'instar-loader-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const validJob = {
+    slug: 'test-job',
+    name: 'Test Job',
+    description: 'A test job',
+    schedule: '0 */4 * * *',
+    priority: 'medium',
+    expectedDurationMinutes: 5,
+    model: 'sonnet',
+    enabled: true,
+    execute: { type: 'skill', value: 'scan' },
+  };
+
+  function writeJobsFile(jobs: unknown[]): string {
+    const filePath = path.join(tmpDir, 'jobs.json');
+    fs.writeFileSync(filePath, JSON.stringify(jobs));
+    return filePath;
+  }
+
+  describe('loadJobs', () => {
+    it('loads a valid jobs file', () => {
+      const file = writeJobsFile([validJob]);
+      const jobs = loadJobs(file);
+      expect(jobs).toHaveLength(1);
+      expect(jobs[0].slug).toBe('test-job');
+    });
+
+    it('loads empty array', () => {
+      const file = writeJobsFile([]);
+      const jobs = loadJobs(file);
+      expect(jobs).toHaveLength(0);
+    });
+
+    it('loads multiple jobs', () => {
+      const file = writeJobsFile([
+        validJob,
+        { ...validJob, slug: 'second-job', name: 'Second' },
+      ]);
+      const jobs = loadJobs(file);
+      expect(jobs).toHaveLength(2);
+    });
+
+    it('includes disabled jobs (filtering is caller responsibility)', () => {
+      const file = writeJobsFile([
+        validJob,
+        { ...validJob, slug: 'off', enabled: false },
+      ]);
+      const jobs = loadJobs(file);
+      expect(jobs).toHaveLength(2);
+      expect(jobs[1].enabled).toBe(false);
+    });
+
+    it('throws for missing file', () => {
+      expect(() => loadJobs('/nonexistent/jobs.json'))
+        .toThrow('Jobs file not found');
+    });
+
+    it('throws for non-array JSON', () => {
+      const file = path.join(tmpDir, 'bad.json');
+      fs.writeFileSync(file, JSON.stringify({ jobs: [] }));
+      expect(() => loadJobs(file))
+        .toThrow('must contain a JSON array');
+    });
+  });
+
+  describe('validateJob', () => {
+    it('accepts a valid job', () => {
+      expect(() => validateJob(validJob)).not.toThrow();
+    });
+
+    it('rejects null', () => {
+      expect(() => validateJob(null)).toThrow('must be an object');
+    });
+
+    it('rejects missing slug', () => {
+      const { slug, ...noSlug } = validJob;
+      expect(() => validateJob(noSlug)).toThrow('"slug" is required');
+    });
+
+    it('rejects empty slug', () => {
+      expect(() => validateJob({ ...validJob, slug: '  ' }))
+        .toThrow('"slug" is required');
+    });
+
+    it('rejects missing name', () => {
+      const { name, ...noName } = validJob;
+      expect(() => validateJob(noName)).toThrow('"name" is required');
+    });
+
+    it('rejects missing description', () => {
+      const { description, ...noDesc } = validJob;
+      expect(() => validateJob(noDesc)).toThrow('"description" is required');
+    });
+
+    it('rejects missing schedule', () => {
+      const { schedule, ...noSchedule } = validJob;
+      expect(() => validateJob(noSchedule)).toThrow('"schedule" is required');
+    });
+
+    it('rejects invalid priority', () => {
+      expect(() => validateJob({ ...validJob, priority: 'urgent' }))
+        .toThrow('"priority" must be one of');
+    });
+
+    it('rejects invalid cron expression', () => {
+      expect(() => validateJob({ ...validJob, schedule: 'not a cron' }))
+        .toThrow('invalid cron expression');
+    });
+
+    it('rejects non-boolean enabled', () => {
+      expect(() => validateJob({ ...validJob, enabled: 'yes' }))
+        .toThrow('"enabled" must be a boolean');
+    });
+
+    it('rejects missing execute', () => {
+      const { execute, ...noExec } = validJob;
+      expect(() => validateJob(noExec))
+        .toThrow('"execute" must be an object');
+    });
+
+    it('rejects invalid execute.type', () => {
+      expect(() => validateJob({ ...validJob, execute: { type: 'unknown', value: 'x' } }))
+        .toThrow('execute.type must be');
+    });
+
+    it('rejects empty execute.value', () => {
+      expect(() => validateJob({ ...validJob, execute: { type: 'skill', value: '' } }))
+        .toThrow('execute.value is required');
+    });
+
+    it('includes index in error message', () => {
+      expect(() => validateJob(null, 3)).toThrow('Job[3]');
+    });
+  });
+});

package/tests/unit/JobScheduler.test.ts

@@ -0,0 +1,267 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { JobScheduler } from '../../src/scheduler/JobScheduler.js';
+import { createTempProject, createMockSessionManager, createSampleJobsFile } from '../helpers/setup.js';
+import type { TempProject, MockSessionManager } from '../helpers/setup.js';
+import type { JobSchedulerConfig } from '../../src/core/types.js';
+
+describe('JobScheduler', () => {
+  let project: TempProject;
+  let mockSM: MockSessionManager;
+  let scheduler: JobScheduler;
+  let jobsFile: string;
+
+  beforeEach(() => {
+    project = createTempProject();
+    mockSM = createMockSessionManager();
+    jobsFile = createSampleJobsFile(project.stateDir);
+  });
+
+  afterEach(() => {
+    scheduler?.stop();
+    project.cleanup();
+  });
+
+  function makeConfig(overrides?: Partial<JobSchedulerConfig>): JobSchedulerConfig {
+    return {
+      jobsFile,
+      enabled: true,
+      maxParallelJobs: 2,
+      quotaThresholds: { normal: 50, elevated: 70, critical: 85, shutdown: 95 },
+      ...overrides,
+    };
+  }
+
+  function createScheduler(configOverrides?: Partial<JobSchedulerConfig>): JobScheduler {
+    scheduler = new JobScheduler(
+      makeConfig(configOverrides),
+      mockSM as any,
+      project.state,
+    );
+    return scheduler;
+  }
+
+  describe('start/stop', () => {
+    it('starts and loads jobs', () => {
+      createScheduler();
+      scheduler.start();
+
+      const status = scheduler.getStatus();
+      expect(status.running).toBe(true);
+      expect(status.jobCount).toBe(3); // 2 enabled + 1 disabled
+      expect(status.enabledJobs).toBe(2);
+    });
+
+    it('stops cleanly', () => {
+      createScheduler();
+      scheduler.start();
+      scheduler.stop();
+
+      expect(scheduler.getStatus().running).toBe(false);
+    });
+
+    it('start is idempotent', () => {
+      createScheduler();
+      scheduler.start();
+      scheduler.start(); // Should not throw
+      expect(scheduler.getStatus().running).toBe(true);
+    });
+  });
+
+  describe('triggerJob', () => {
+    it('triggers a known job', () => {
+      createScheduler();
+      scheduler.start();
+
+      const result = scheduler.triggerJob('health-check', 'test');
+      expect(result).toBe('triggered');
+      expect(mockSM._spawnCount).toBe(1);
+    });
+
+    it('throws for unknown job', () => {
+      createScheduler();
+      scheduler.start();
+
+      expect(() => scheduler.triggerJob('nonexistent', 'test'))
+        .toThrow('Unknown job: nonexistent');
+    });
+
+    it('queues when at max parallel jobs', () => {
+      createScheduler({ maxParallelJobs: 1 });
+      scheduler.start();
+
+      // First trigger succeeds
+      const r1 = scheduler.triggerJob('health-check', 'test');
+      expect(r1).toBe('triggered');
+
+      // Second trigger gets queued — at capacity
+      const r2 = scheduler.triggerJob('email-check', 'test');
+      expect(r2).toBe('queued');
+
+      expect(scheduler.getStatus().queueLength).toBe(1);
+    });
+
+    it('skips when paused', () => {
+      createScheduler();
+      scheduler.start();
+      scheduler.pause();
+
+      const result = scheduler.triggerJob('health-check', 'test');
+      expect(result).toBe('skipped');
+      expect(mockSM._spawnCount).toBe(0);
+    });
+
+    it('skips when quota callback returns false', () => {
+      createScheduler();
+      scheduler.start();
+      scheduler.canRunJob = () => false;
+
+      const result = scheduler.triggerJob('health-check', 'test');
+      expect(result).toBe('skipped');
+      expect(mockSM._spawnCount).toBe(0);
+    });
+  });
+
+  describe('queue processing', () => {
+    it('drains queue when slot opens', () => {
+      createScheduler({ maxParallelJobs: 1 });
+      scheduler.start();
+
+      // Fill the slot
+      scheduler.triggerJob('health-check', 'test');
+      expect(mockSM._spawnCount).toBe(1);
+
+      // Queue a job
+      scheduler.triggerJob('email-check', 'test');
+      expect(scheduler.getStatus().queueLength).toBe(1);
+
+      // Simulate session completion — mark the running session as completed
+      const session = mockSM._sessions[0];
+      session.status = 'completed';
+      mockSM._aliveSet.delete(session.tmuxSession);
+
+      // Process the queue
+      scheduler.processQueue();
+      expect(mockSM._spawnCount).toBe(2);
+      expect(scheduler.getStatus().queueLength).toBe(0);
+    });
+
+    it('does not dequeue duplicates', () => {
+      createScheduler({ maxParallelJobs: 1 });
+      scheduler.start();
+
+      scheduler.triggerJob('health-check', 'test');
+      scheduler.triggerJob('email-check', 'test-1');
+      scheduler.triggerJob('email-check', 'test-2'); // duplicate slug
+
+      expect(scheduler.getStatus().queueLength).toBe(1);
+    });
+
+    it('does not process queue when paused', () => {
+      createScheduler({ maxParallelJobs: 1 });
+      scheduler.start();
+
+      scheduler.triggerJob('health-check', 'test');
+      scheduler.triggerJob('email-check', 'test');
+
+      // Clear the slot
+      mockSM._sessions[0].status = 'completed';
+      mockSM._aliveSet.delete(mockSM._sessions[0].tmuxSession);
+
+      scheduler.pause();
+      scheduler.processQueue();
+      expect(mockSM._spawnCount).toBe(1); // Only the first one
+    });
+  });
+
+  describe('pause/resume', () => {
+    it('resume processes pending queue', () => {
+      createScheduler({ maxParallelJobs: 1 });
+      scheduler.start();
+
+      scheduler.triggerJob('health-check', 'test');
+      scheduler.triggerJob('email-check', 'test');
+      scheduler.pause();
+
+      // Clear the slot
+      mockSM._sessions[0].status = 'completed';
+      mockSM._aliveSet.delete(mockSM._sessions[0].tmuxSession);
+
+      scheduler.resume();
+      expect(mockSM._spawnCount).toBe(2);
+    });
+
+    it('getStatus reflects paused state', () => {
+      createScheduler();
+      scheduler.start();
+
+      expect(scheduler.getStatus().paused).toBe(false);
+      scheduler.pause();
+      expect(scheduler.getStatus().paused).toBe(true);
+      scheduler.resume();
+      expect(scheduler.getStatus().paused).toBe(false);
+    });
+  });
+
+  describe('failure tracking', () => {
+    it('increments consecutive failures on spawn error', async () => {
+      createScheduler();
+      scheduler.start();
+
+      // Make spawnSession reject
+      mockSM.spawnSession = async () => { throw new Error('tmux failed'); };
+
+      scheduler.triggerJob('health-check', 'test');
+
+      // Wait for the async rejection to be handled
+      await new Promise(r => setTimeout(r, 50));
+
+      const jobState = project.state.getJobState('health-check');
+      expect(jobState?.lastResult).toBe('failure');
+      expect(jobState?.consecutiveFailures).toBe(1);
+    });
+  });
+
+  describe('getJobs', () => {
+    it('returns loaded job definitions', () => {
+      createScheduler();
+      scheduler.start();
+
+      const jobs = scheduler.getJobs();
+      expect(jobs).toHaveLength(3);
+      expect(jobs.map(j => j.slug)).toContain('health-check');
+      expect(jobs.map(j => j.slug)).toContain('disabled-job');
+    });
+  });
+
+  describe('activity events', () => {
+    it('emits scheduler_start event', () => {
+      createScheduler();
+      scheduler.start();
+
+      const events = project.state.queryEvents({ type: 'scheduler_start' });
+      expect(events).toHaveLength(1);
+    });
+
+    it('emits job_triggered event', async () => {
+      createScheduler();
+      scheduler.start();
+      scheduler.triggerJob('health-check', 'manual');
+
+      // Wait for async spawn to complete
+      await new Promise(r => setTimeout(r, 50));
+
+      const events = project.state.queryEvents({ type: 'job_triggered' });
+      expect(events).toHaveLength(1);
+      expect(events[0].summary).toContain('health-check');
+    });
+
+    it('emits scheduler_stop event', () => {
+      createScheduler();
+      scheduler.start();
+      scheduler.stop();
+
+      const events = project.state.queryEvents({ type: 'scheduler_stop' });
+      expect(events).toHaveLength(1);
+    });
+  });
+});

package/tests/unit/Prerequisites.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Unit tests for prerequisite detection.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { checkPrerequisites } from '../../src/core/Prerequisites.js';
+
+describe('Prerequisites', () => {
+  it('returns structured results for all checks', () => {
+    const result = checkPrerequisites();
+
+    expect(result.results).toHaveLength(3);
+    expect(result.results.map(r => r.name)).toEqual(['Node.js', 'tmux', 'Claude CLI']);
+
+    // Each result has the expected shape
+    for (const r of result.results) {
+      expect(r).toHaveProperty('name');
+      expect(r).toHaveProperty('found');
+      expect(r).toHaveProperty('installHint');
+    }
+  });
+
+  it('detects Node.js version correctly', () => {
+    const result = checkPrerequisites();
+    const node = result.results.find(r => r.name === 'Node.js')!;
+
+    expect(node.found).toBe(true); // We're running tests, so Node must be available
+    expect(node.version).toMatch(/^v\d+/);
+  });
+
+  it('reports allMet based on found status', () => {
+    const result = checkPrerequisites();
+
+    // allMet should be true only if everything is found
+    const allFound = result.results.every(r => r.found);
+    expect(result.allMet).toBe(allFound);
+  });
+
+  it('missing array contains only unfound prerequisites', () => {
+    const result = checkPrerequisites();
+
+    for (const m of result.missing) {
+      expect(m.found).toBe(false);
+    }
+
+    // missing.length + found.length should equal total
+    const foundCount = result.results.filter(r => r.found).length;
+    expect(result.missing.length + foundCount).toBe(result.results.length);
+  });
+
+  it('provides install hints for all results', () => {
+    const result = checkPrerequisites();
+
+    // Missing items should have non-empty install hints
+    for (const m of result.missing) {
+      expect(m.installHint.length).toBeGreaterThan(0);
+    }
+  });
+});