instar 0.1.0

package/tests/helpers/setup.ts

@@ -0,0 +1,209 @@
+/**
+ * Shared test utilities for instar tests.
+ *
+ * Provides temp project creation, mock session managers,
+ * mock claude scripts, and async polling helpers.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import { StateManager } from '../../src/core/StateManager.js';
+import type { Session, SessionManagerConfig, ModelTier, JobDefinition } from '../../src/core/types.js';
+
+// ── Temp Project ──────────────────────────────────────────────────
+
+export interface TempProject {
+  dir: string;
+  stateDir: string;
+  state: StateManager;
+  cleanup: () => void;
+}
+
+export function createTempProject(): TempProject {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'instar-test-'));
+  const stateDir = path.join(dir, '.instar');
+
+  // Create instar directory structure
+  fs.mkdirSync(path.join(stateDir, 'state', 'sessions'), { recursive: true });
+  fs.mkdirSync(path.join(stateDir, 'state', 'jobs'), { recursive: true });
+  fs.mkdirSync(path.join(stateDir, 'logs'), { recursive: true });
+
+  const state = new StateManager(stateDir);
+
+  return {
+    dir,
+    stateDir,
+    state,
+    cleanup: () => fs.rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+// ── Mock Session Manager ──────────────────────────────────────────
+
+export interface MockSessionManager {
+  spawnSession: (opts: {
+    name: string;
+    prompt: string;
+    model?: ModelTier;
+    jobSlug?: string;
+    triggeredBy?: string;
+  }) => Promise<Session>;
+  isSessionAlive: (tmuxSession: string) => boolean;
+  listRunningSessions: () => Session[];
+  killSession: (sessionId: string) => boolean;
+  captureOutput: (tmuxSession: string, lines?: number) => string | null;
+  sendInput: (tmuxSession: string, input: string) => boolean;
+
+  // Test controls
+  _sessions: Session[];
+  _aliveSet: Set<string>;
+  _spawnCount: number;
+}
+
+export function createMockSessionManager(): MockSessionManager {
+  const mock: MockSessionManager = {
+    _sessions: [],
+    _aliveSet: new Set(),
+    _spawnCount: 0,
+
+    spawnSession: async (opts) => {
+      mock._spawnCount++;
+      const session: Session = {
+        id: `mock-${Date.now().toString(36)}-${mock._spawnCount}`,
+        name: opts.name,
+        status: 'running',
+        tmuxSession: `test-${opts.name}`,
+        startedAt: new Date().toISOString(),
+        jobSlug: opts.jobSlug,
+        triggeredBy: opts.triggeredBy,
+        model: opts.model,
+        prompt: opts.prompt,
+      };
+      mock._sessions.push(session);
+      mock._aliveSet.add(session.tmuxSession);
+      return session;
+    },
+
+    isSessionAlive: (tmuxSession: string) => mock._aliveSet.has(tmuxSession),
+
+    listRunningSessions: () => mock._sessions.filter(s => s.status === 'running'),
+
+    killSession: (sessionId: string) => {
+      const session = mock._sessions.find(s => s.id === sessionId);
+      if (!session) return false;
+      session.status = 'killed';
+      session.endedAt = new Date().toISOString();
+      mock._aliveSet.delete(session.tmuxSession);
+      return true;
+    },
+
+    captureOutput: () => 'mock output',
+
+    sendInput: (tmuxSession: string) => mock._aliveSet.has(tmuxSession),
+  };
+
+  return mock;
+}
+
+// ── Mock Claude Script ────────────────────────────────────────────
+
+/**
+ * Create a shell script that mimics claude CLI — echoes the prompt and exits.
+ * Returns the path to the script.
+ */
+export function createMockClaude(dir: string): string {
+  const scriptPath = path.join(dir, 'mock-claude.sh');
+  fs.writeFileSync(scriptPath, `#!/bin/bash
+echo "Mock Claude session started"
+echo "Prompt: $@"
+# Sleep briefly to simulate work, then exit
+sleep 2
+echo "Session ended"
+`);
+  fs.chmodSync(scriptPath, '755');
+  return scriptPath;
+}
+
+// ── Sample Jobs ───────────────────────────────────────────────────
+
+export function createSampleJobsFile(dir: string, jobs?: JobDefinition[]): string {
+  const filePath = path.join(dir, 'jobs.json');
+  const defaultJobs: JobDefinition[] = jobs ?? [
+    {
+      slug: 'health-check',
+      name: 'Health Check',
+      description: 'Run a quick health check',
+      schedule: '0 */4 * * *',
+      priority: 'high',
+      expectedDurationMinutes: 2,
+      model: 'haiku',
+      enabled: true,
+      execute: { type: 'skill', value: 'scan' },
+      tags: ['monitoring'],
+    },
+    {
+      slug: 'email-check',
+      name: 'Email Check',
+      description: 'Check for new emails',
+      schedule: '0 */2 * * *',
+      priority: 'medium',
+      expectedDurationMinutes: 5,
+      model: 'sonnet',
+      enabled: true,
+      execute: { type: 'prompt', value: 'Check for new emails and respond' },
+    },
+    {
+      slug: 'disabled-job',
+      name: 'Disabled Job',
+      description: 'This one is off',
+      schedule: '0 0 * * *',
+      priority: 'low',
+      expectedDurationMinutes: 10,
+      model: 'opus',
+      enabled: false,
+      execute: { type: 'script', value: './scripts/heavy-task.sh' },
+    },
+  ];
+
+  fs.writeFileSync(filePath, JSON.stringify(defaultJobs, null, 2));
+  return filePath;
+}
+
+// ── Async Helpers ─────────────────────────────────────────────────
+
+/**
+ * Poll a condition until it returns true or timeout.
+ */
+export async function waitFor(
+  condition: () => boolean | Promise<boolean>,
+  timeoutMs: number = 5000,
+  intervalMs: number = 100,
+): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await condition()) return;
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  throw new Error(`waitFor timed out after ${timeoutMs}ms`);
+}
+
+// ── Tmux Cleanup ──────────────────────────────────────────────────
+
+/**
+ * Kill any tmux sessions matching a prefix. Use in afterAll for integration tests.
+ */
+export function cleanupTmuxSessions(prefix: string): void {
+  try {
+    const output = execSync('tmux list-sessions -F "#{session_name}"', { encoding: 'utf-8' });
+    const sessions = output.trim().split('\n').filter(s => s.startsWith(prefix));
+    for (const session of sessions) {
+      try {
+        execSync(`tmux kill-session -t '=${session}'`);
+      } catch { /* already dead */ }
+    }
+  } catch {
+    // No tmux server running — fine
+  }
+}

package/tests/integration/fresh-install.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Integration test — fresh project creation via `instar init <name>`.
+ *
+ * Tests the complete fresh install journey:
+ *   init with project name → directory created → all files scaffolded →
+ *   config valid → identity files present → hooks installed → git initialized
+ */
+
+import { describe, it, expect, afterAll } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { initProject } from '../../src/commands/init.js';
+
+describe('Fresh install: instar init <project-name>', () => {
+  const testBase = fs.mkdtempSync(path.join(os.tmpdir(), 'instar-fresh-'));
+  const projectName = 'test-agent';
+  const projectDir = path.join(testBase, projectName);
+
+  afterAll(() => {
+    fs.rmSync(testBase, { recursive: true, force: true });
+  });
+
+  it('creates project directory and all required files', async () => {
+    // Change cwd temporarily so init creates the project relative to testBase
+    const originalCwd = process.cwd();
+    process.chdir(testBase);
+
+    try {
+      await initProject({ name: projectName, port: 4444 });
+    } finally {
+      process.chdir(originalCwd);
+    }
+
+    // Verify project directory exists
+    expect(fs.existsSync(projectDir)).toBe(true);
+  });
+
+  it('creates CLAUDE.md at project root', () => {
+    const claudeMd = path.join(projectDir, 'CLAUDE.md');
+    expect(fs.existsSync(claudeMd)).toBe(true);
+
+    const content = fs.readFileSync(claudeMd, 'utf-8');
+    expect(content).toContain('test-agent');
+    expect(content).toContain('Agent Infrastructure');
+    expect(content).toContain('Initiative Hierarchy');
+  });
+
+  it('creates .instar directory structure', () => {
+    const stateDir = path.join(projectDir, '.instar');
+    expect(fs.existsSync(stateDir)).toBe(true);
+    expect(fs.existsSync(path.join(stateDir, 'state'))).toBe(true);
+    expect(fs.existsSync(path.join(stateDir, 'state', 'sessions'))).toBe(true);
+    expect(fs.existsSync(path.join(stateDir, 'state', 'jobs'))).toBe(true);
+    expect(fs.existsSync(path.join(stateDir, 'relationships'))).toBe(true);
+    expect(fs.existsSync(path.join(stateDir, 'logs'))).toBe(true);
+  });
+
+  it('creates AGENT.md with identity', () => {
+    const agentMd = path.join(projectDir, '.instar', 'AGENT.md');
+    expect(fs.existsSync(agentMd)).toBe(true);
+
+    const content = fs.readFileSync(agentMd, 'utf-8');
+    expect(content).toContain('# Test-agent'); // Capitalized
+    expect(content).toContain('Who I Am');
+    expect(content).toContain('My Principles');
+  });
+
+  it('creates USER.md', () => {
+    const userMd = path.join(projectDir, '.instar', 'USER.md');
+    expect(fs.existsSync(userMd)).toBe(true);
+
+    const content = fs.readFileSync(userMd, 'utf-8');
+    expect(content).toContain('Communication Preferences');
+  });
+
+  it('creates MEMORY.md', () => {
+    const memoryMd = path.join(projectDir, '.instar', 'MEMORY.md');
+    expect(fs.existsSync(memoryMd)).toBe(true);
+
+    const content = fs.readFileSync(memoryMd, 'utf-8');
+    expect(content).toContain('Memory');
+    expect(content).toContain('persists across sessions');
+  });
+
+  it('creates valid config.json', () => {
+    const configPath = path.join(projectDir, '.instar', 'config.json');
+    expect(fs.existsSync(configPath)).toBe(true);
+
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    expect(config.projectName).toBe('test-agent');
+    expect(config.port).toBe(4444);
+    expect(config.authToken).toBeTruthy();
+    expect(config.sessions.maxSessions).toBe(3);
+    expect(config.scheduler.enabled).toBe(true); // Enabled by default for fresh
+    expect(config.relationships.maxRecentInteractions).toBe(20);
+  });
+
+  it('creates jobs.json with default coherence jobs', () => {
+    const jobsPath = path.join(projectDir, '.instar', 'jobs.json');
+    expect(fs.existsSync(jobsPath)).toBe(true);
+
+    const jobs = JSON.parse(fs.readFileSync(jobsPath, 'utf-8'));
+    expect(jobs.length).toBe(3);
+
+    const slugs = jobs.map((j: any) => j.slug);
+    expect(slugs).toContain('health-check');
+    expect(slugs).toContain('reflection-trigger');
+    expect(slugs).toContain('relationship-maintenance');
+  });
+
+  it('installs behavioral hooks', () => {
+    const hooksDir = path.join(projectDir, '.instar', 'hooks');
+    expect(fs.existsSync(hooksDir)).toBe(true);
+
+    const hooks = fs.readdirSync(hooksDir);
+    expect(hooks).toContain('session-start.sh');
+    expect(hooks).toContain('dangerous-command-guard.sh');
+    expect(hooks).toContain('grounding-before-messaging.sh');
+    expect(hooks).toContain('compaction-recovery.sh');
+
+    // Verify hooks are executable
+    for (const hook of hooks) {
+      const stats = fs.statSync(path.join(hooksDir, hook));
+      expect(stats.mode & 0o111).toBeGreaterThan(0); // Has execute bit
+    }
+  });
+
+  it('creates .claude/settings.json with hook config', () => {
+    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+    expect(fs.existsSync(settingsPath)).toBe(true);
+
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    expect(settings.hooks).toBeDefined();
+    expect(settings.hooks.PreToolUse).toBeDefined();
+  });
+
+  it('creates .claude/scripts/health-watchdog.sh', () => {
+    const watchdogPath = path.join(projectDir, '.claude', 'scripts', 'health-watchdog.sh');
+    expect(fs.existsSync(watchdogPath)).toBe(true);
+
+    const stats = fs.statSync(watchdogPath);
+    expect(stats.mode & 0o111).toBeGreaterThan(0);
+  });
+
+  it('creates .gitignore with state exclusions', () => {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    expect(fs.existsSync(gitignorePath)).toBe(true);
+
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    expect(content).toContain('.instar/state/');
+    expect(content).toContain('.instar/logs/');
+  });
+
+  it('initializes a git repository', () => {
+    const gitDir = path.join(projectDir, '.git');
+    expect(fs.existsSync(gitDir)).toBe(true);
+  });
+});
+
+describe('Existing project: instar init (no project name)', () => {
+  const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'instar-existing-'));
+
+  afterAll(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('adds .instar/ to an existing directory without CLAUDE.md', async () => {
+    // Create a minimal existing project
+    fs.writeFileSync(path.join(testDir, 'index.ts'), '// existing code');
+
+    await initProject({ dir: testDir, port: 5555 });
+
+    // Verify .instar was created
+    expect(fs.existsSync(path.join(testDir, '.instar', 'config.json'))).toBe(true);
+    expect(fs.existsSync(path.join(testDir, '.instar', 'AGENT.md'))).toBe(true);
+    expect(fs.existsSync(path.join(testDir, '.instar', 'USER.md'))).toBe(true);
+    expect(fs.existsSync(path.join(testDir, '.instar', 'MEMORY.md'))).toBe(true);
+
+    // Verify existing file wasn't touched
+    const existingContent = fs.readFileSync(path.join(testDir, 'index.ts'), 'utf-8');
+    expect(existingContent).toBe('// existing code');
+
+    // Verify scheduler is disabled for existing projects (conservative default)
+    const config = JSON.parse(fs.readFileSync(path.join(testDir, '.instar', 'config.json'), 'utf-8'));
+    expect(config.scheduler.enabled).toBe(false);
+  });
+
+  it('appends to existing CLAUDE.md without overwriting', async () => {
+    const anotherDir = fs.mkdtempSync(path.join(os.tmpdir(), 'instar-existing2-'));
+    const existingContent = '# My Project\n\nThis is my project.\n';
+    fs.writeFileSync(path.join(anotherDir, 'CLAUDE.md'), existingContent);
+
+    await initProject({ dir: anotherDir });
+
+    const result = fs.readFileSync(path.join(anotherDir, 'CLAUDE.md'), 'utf-8');
+    expect(result).toContain('# My Project');
+    expect(result).toContain('This is my project.');
+    expect(result).toContain('## Agent Infrastructure');
+
+    fs.rmSync(anotherDir, { recursive: true, force: true });
+  });
+
+  it('does not re-append if already initialized', async () => {
+    const anotherDir = fs.mkdtempSync(path.join(os.tmpdir(), 'instar-existing3-'));
+    const existingContent = '# My Project\n\n## Agent Infrastructure\n\nAlready here.\n';
+    fs.writeFileSync(path.join(anotherDir, 'CLAUDE.md'), existingContent);
+
+    await initProject({ dir: anotherDir });
+
+    const result = fs.readFileSync(path.join(anotherDir, 'CLAUDE.md'), 'utf-8');
+    // Should only have one instance of Agent Infrastructure
+    const count = (result.match(/## Agent Infrastructure/g) || []).length;
+    expect(count).toBe(1);
+
+    fs.rmSync(anotherDir, { recursive: true, force: true });
+  });
+});

package/tests/integration/scheduler-basic.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Integration test — scheduler with real cron timing.
+ *
+ * Uses a fast cron (every second) and mock claude to verify
+ * the scheduler triggers jobs and tracks state.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { JobScheduler } from '../../src/scheduler/JobScheduler.js';
+import { detectTmuxPath } from '../../src/core/Config.js';
+import { SessionManager } from '../../src/core/SessionManager.js';
+import {
+  createTempProject,
+  createMockClaude,
+  cleanupTmuxSessions,
+  waitFor,
+} from '../helpers/setup.js';
+import type { TempProject } from '../helpers/setup.js';
+import type { JobDefinition } from '../../src/core/types.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const TMUX_PREFIX = 'akit-sched-';
+
+const tmuxPath = detectTmuxPath();
+const describeMaybe = tmuxPath ? describe : describe.skip;
+
+describeMaybe('JobScheduler (integration)', () => {
+  let project: TempProject;
+  let mockClaudePath: string;
+  let sm: SessionManager;
+  let scheduler: JobScheduler;
+
+  beforeAll(() => {
+    project = createTempProject();
+    mockClaudePath = createMockClaude(project.dir);
+
+    sm = new SessionManager(
+      {
+        tmuxPath: tmuxPath!,
+        claudePath: mockClaudePath,
+        projectDir: project.dir,
+        maxSessions: 5,
+        protectedSessions: [],
+        completionPatterns: ['Session ended'],
+      },
+      project.state,
+    );
+  });
+
+  afterAll(() => {
+    scheduler?.stop();
+    sm.stopMonitoring();
+    cleanupTmuxSessions(TMUX_PREFIX);
+    project.cleanup();
+  });
+
+  it('triggers a job via cron and spawns a session', async () => {
+    // Create a jobs file with a fast-firing cron (every second)
+    const fastJob: JobDefinition = {
+      slug: 'fast-test',
+      name: 'Fast Test',
+      description: 'Triggers every second for testing',
+      schedule: '* * * * * *', // Every second (croner supports seconds)
+      priority: 'medium',
+      expectedDurationMinutes: 1,
+      model: 'haiku',
+      enabled: true,
+      execute: { type: 'prompt', value: 'Quick test' },
+    };
+
+    const jobsFile = path.join(project.stateDir, 'jobs.json');
+    fs.writeFileSync(jobsFile, JSON.stringify([fastJob]));
+
+    scheduler = new JobScheduler(
+      {
+        jobsFile,
+        enabled: true,
+        maxParallelJobs: 3,
+        quotaThresholds: { normal: 50, elevated: 70, critical: 85, shutdown: 95 },
+      },
+      sm,
+      project.state,
+    );
+
+    scheduler.start();
+
+    // Wait for cron to fire and a session to be spawned
+    await waitFor(
+      () => {
+        const events = project.state.queryEvents({ type: 'job_triggered' });
+        return events.length > 0;
+      },
+      5000,
+    );
+
+    scheduler.stop();
+
+    // Verify a job_triggered event was recorded
+    const events = project.state.queryEvents({ type: 'job_triggered' });
+    expect(events.length).toBeGreaterThan(0);
+    expect(events[0].summary).toContain('fast-test');
+
+    // Verify job state was saved
+    const jobState = project.state.getJobState('fast-test');
+    expect(jobState).not.toBeNull();
+    expect(jobState!.lastRun).toBeTruthy();
+  });
+});