instar 0.1.0

package/tests/unit/UserManager.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { UserManager } from '../../src/users/UserManager.js';
+import type { UserProfile, Message } from '../../src/core/types.js';
+
+describe('UserManager', () => {
+  let tmpDir: string;
+  let manager: UserManager;
+
+  const justin: UserProfile = {
+    id: 'justin',
+    name: 'Justin',
+    channels: [
+      { type: 'telegram', identifier: 'topic_42' },
+      { type: 'email', identifier: 'justin@example.com' },
+    ],
+    permissions: ['admin', 'deploy'],
+    preferences: {
+      style: 'technical, direct, autonomous',
+      autonomyLevel: 'full',
+      timezone: 'America/New_York',
+    },
+  };
+
+  const adriana: UserProfile = {
+    id: 'adriana',
+    name: 'Adriana',
+    channels: [
+      { type: 'telegram', identifier: 'topic_43' },
+      { type: 'email', identifier: 'adriana@example.com' },
+    ],
+    permissions: ['request', 'review'],
+    preferences: {
+      style: 'prefers context, asks questions',
+      autonomyLevel: 'confirm-destructive',
+      timezone: 'America/New_York',
+    },
+  };
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'instar-user-test-'));
+    manager = new UserManager(tmpDir, [justin, adriana]);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('resolveFromMessage', () => {
+    it('resolves Justin from Telegram message', () => {
+      const message: Message = {
+        id: 'msg-1',
+        userId: '',
+        content: 'Deploy the latest',
+        channel: { type: 'telegram', identifier: 'topic_42' },
+        receivedAt: new Date().toISOString(),
+      };
+
+      const user = manager.resolveFromMessage(message);
+      expect(user?.id).toBe('justin');
+      expect(user?.name).toBe('Justin');
+    });
+
+    it('resolves Adriana from email', () => {
+      const user = manager.resolveFromChannel({
+        type: 'email',
+        identifier: 'adriana@example.com',
+      });
+      expect(user?.id).toBe('adriana');
+    });
+
+    it('returns null for unknown channel', () => {
+      const user = manager.resolveFromChannel({
+        type: 'telegram',
+        identifier: 'unknown_topic',
+      });
+      expect(user).toBeNull();
+    });
+  });
+
+  describe('permissions', () => {
+    it('checks direct permission', () => {
+      expect(manager.hasPermission('justin', 'deploy')).toBe(true);
+      expect(manager.hasPermission('adriana', 'deploy')).toBe(false);
+    });
+
+    it('admin permission grants everything', () => {
+      expect(manager.hasPermission('justin', 'anything')).toBe(true);
+    });
+
+    it('returns false for unknown user', () => {
+      expect(manager.hasPermission('nobody', 'deploy')).toBe(false);
+    });
+  });
+
+  describe('CRUD operations', () => {
+    it('lists all users', () => {
+      const users = manager.listUsers();
+      expect(users).toHaveLength(2);
+      expect(users.map(u => u.id).sort()).toEqual(['adriana', 'justin']);
+    });
+
+    it('gets user by ID', () => {
+      const user = manager.getUser('justin');
+      expect(user?.name).toBe('Justin');
+    });
+
+    it('upserts existing user', () => {
+      const updated = { ...justin, preferences: { ...justin.preferences, style: 'updated' } };
+      manager.upsertUser(updated);
+
+      const user = manager.getUser('justin');
+      expect(user?.preferences.style).toBe('updated');
+    });
+
+    it('removes a user', () => {
+      expect(manager.removeUser('adriana')).toBe(true);
+      expect(manager.getUser('adriana')).toBeNull();
+      expect(manager.listUsers()).toHaveLength(1);
+    });
+
+    it('persists users to disk', () => {
+      // Create a new manager from the same directory — should load persisted data
+      const newManager = new UserManager(tmpDir);
+      expect(newManager.listUsers()).toHaveLength(2);
+      expect(newManager.getUser('justin')?.name).toBe('Justin');
+    });
+  });
+});

package/tests/unit/bootstrap.test.ts

@@ -0,0 +1,28 @@
+/**
+ * Unit tests for identity bootstrap.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { defaultIdentity } from '../../src/scaffold/bootstrap.js';
+
+describe('defaultIdentity', () => {
+  it('capitalizes project name for agent name', () => {
+    const identity = defaultIdentity('my-agent');
+    expect(identity.name).toBe('My-agent');
+  });
+
+  it('provides a general-purpose role', () => {
+    const identity = defaultIdentity('test');
+    expect(identity.role).toContain('general-purpose');
+  });
+
+  it('provides a personality', () => {
+    const identity = defaultIdentity('test');
+    expect(identity.personality.length).toBeGreaterThan(0);
+  });
+
+  it('defaults user name to User', () => {
+    const identity = defaultIdentity('test');
+    expect(identity.userName).toBe('User');
+  });
+});

package/tests/unit/commands.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createTempProject, createSampleJobsFile } from '../helpers/setup.js';
+import type { TempProject } from '../helpers/setup.js';
+
+/**
+ * CLI command tests — validate that user/job commands
+ * correctly read/write state files.
+ *
+ * We test the underlying logic by importing the UserManager and
+ * JobLoader directly, since the CLI commands are thin wrappers.
+ */
+
+describe('CLI Commands', () => {
+  let project: TempProject;
+
+  beforeEach(() => {
+    project = createTempProject();
+  });
+
+  afterEach(() => {
+    project.cleanup();
+  });
+
+  describe('user add', () => {
+    it('creates user via UserManager', async () => {
+      const { UserManager } = await import('../../src/users/UserManager.js');
+      const um = new UserManager(project.stateDir);
+
+      um.upsertUser({
+        id: 'justin',
+        name: 'Justin',
+        channels: [
+          { type: 'telegram', identifier: '42' },
+          { type: 'email', identifier: 'test@example.com' },
+        ],
+        permissions: ['admin'],
+        preferences: {},
+      });
+
+      const users = um.listUsers();
+      expect(users).toHaveLength(1);
+      expect(users[0].name).toBe('Justin');
+      expect(users[0].channels).toHaveLength(2);
+
+      // Verify it was persisted to disk
+      const usersFile = path.join(project.stateDir, 'users.json');
+      expect(fs.existsSync(usersFile)).toBe(true);
+      const savedUsers = JSON.parse(fs.readFileSync(usersFile, 'utf-8'));
+      expect(savedUsers).toHaveLength(1);
+    });
+
+    it('resolves user from channel', async () => {
+      const { UserManager } = await import('../../src/users/UserManager.js');
+      const um = new UserManager(project.stateDir);
+
+      um.upsertUser({
+        id: 'justin',
+        name: 'Justin',
+        channels: [{ type: 'telegram', identifier: '42' }],
+        permissions: ['admin'],
+        preferences: {},
+      });
+
+      const resolved = um.resolveFromChannel({ type: 'telegram', identifier: '42' });
+      expect(resolved).not.toBeNull();
+      expect(resolved!.id).toBe('justin');
+
+      const notFound = um.resolveFromChannel({ type: 'telegram', identifier: '999' });
+      expect(notFound).toBeNull();
+    });
+  });
+
+  describe('job add', () => {
+    it('adds a job to jobs.json', async () => {
+      const jobsFile = path.join(project.stateDir, 'jobs.json');
+      fs.writeFileSync(jobsFile, '[]');
+
+      const jobs = JSON.parse(fs.readFileSync(jobsFile, 'utf-8'));
+      jobs.push({
+        slug: 'test-job',
+        name: 'Test Job',
+        description: 'A test job',
+        schedule: '0 */4 * * *',
+        priority: 'medium',
+        expectedDurationMinutes: 5,
+        model: 'sonnet',
+        enabled: true,
+        execute: { type: 'prompt', value: 'Do the thing' },
+      });
+      fs.writeFileSync(jobsFile, JSON.stringify(jobs, null, 2));
+
+      // Verify via JobLoader
+      const { loadJobs } = await import('../../src/scheduler/JobLoader.js');
+      const loaded = loadJobs(jobsFile);
+      expect(loaded).toHaveLength(1);
+      expect(loaded[0].slug).toBe('test-job');
+    });
+
+    it('validates job before saving', async () => {
+      const { validateJob } = await import('../../src/scheduler/JobLoader.js');
+
+      // Valid job passes
+      expect(() => validateJob({
+        slug: 'ok',
+        name: 'OK',
+        description: 'Fine',
+        schedule: '0 * * * *',
+        priority: 'medium',
+        enabled: true,
+        execute: { type: 'prompt', value: 'test' },
+      })).not.toThrow();
+
+      // Invalid priority caught
+      expect(() => validateJob({
+        slug: 'bad',
+        name: 'Bad',
+        description: 'Bad',
+        schedule: '0 * * * *',
+        priority: 'urgent',
+        enabled: true,
+        execute: { type: 'prompt', value: 'test' },
+      })).toThrow('priority');
+    });
+  });
+
+  describe('job list', () => {
+    it('loads and displays jobs with state', async () => {
+      const jobsFile = createSampleJobsFile(project.stateDir);
+      const { loadJobs } = await import('../../src/scheduler/JobLoader.js');
+
+      const jobs = loadJobs(jobsFile);
+      expect(jobs).toHaveLength(3);
+      expect(jobs.filter((j: any) => j.enabled)).toHaveLength(2);
+    });
+  });
+});

package/tests/unit/middleware.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { authMiddleware, corsMiddleware, errorHandler } from '../../src/server/middleware.js';
+
+function createApp(authToken?: string) {
+  const app = express();
+  app.use(corsMiddleware);
+  app.use(authMiddleware(authToken));
+
+  app.get('/health', (_req, res) => res.json({ status: 'ok' }));
+  app.get('/status', (_req, res) => res.json({ sessions: 0 }));
+  app.get('/error', () => { throw new Error('test error'); });
+  app.use(errorHandler);
+
+  return app;
+}
+
+describe('authMiddleware', () => {
+  describe('when auth token is configured', () => {
+    const app = createApp('test-secret-token');
+
+    it('allows /health without auth', async () => {
+      const res = await request(app).get('/health');
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('ok');
+    });
+
+    it('blocks requests without Authorization header', async () => {
+      const res = await request(app).get('/status');
+      expect(res.status).toBe(401);
+      expect(res.body.error).toContain('Authorization');
+    });
+
+    it('blocks requests with wrong token', async () => {
+      const res = await request(app)
+        .get('/status')
+        .set('Authorization', 'Bearer wrong-token');
+      expect(res.status).toBe(403);
+      expect(res.body.error).toContain('Invalid');
+    });
+
+    it('allows requests with correct token', async () => {
+      const res = await request(app)
+        .get('/status')
+        .set('Authorization', 'Bearer test-secret-token');
+      expect(res.status).toBe(200);
+      expect(res.body.sessions).toBe(0);
+    });
+
+    it('blocks non-Bearer auth schemes', async () => {
+      const res = await request(app)
+        .get('/status')
+        .set('Authorization', 'Basic dGVzdDp0ZXN0');
+      expect(res.status).toBe(401);
+    });
+  });
+
+  describe('when auth token is not configured', () => {
+    const app = createApp(undefined);
+
+    it('allows all requests without auth', async () => {
+      const res = await request(app).get('/status');
+      expect(res.status).toBe(200);
+    });
+  });
+});
+
+describe('corsMiddleware', () => {
+  const app = createApp();
+
+  it('handles OPTIONS preflight', async () => {
+    const res = await request(app).options('/status');
+    expect(res.status).toBe(204);
+  });
+
+  it('sets CORS headers on regular requests', async () => {
+    const res = await request(app).get('/health');
+    expect(res.headers['access-control-allow-methods']).toContain('GET');
+  });
+});
+
+describe('errorHandler', () => {
+  const app = createApp();
+
+  it('returns 500 with error message', async () => {
+    const res = await request(app).get('/error');
+    expect(res.status).toBe(500);
+    expect(res.body.error).toBe('test error');
+    expect(res.body).toHaveProperty('timestamp');
+  });
+});

package/tests/unit/relationship-routes.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import request from 'supertest';
+import { AgentServer } from '../../src/server/AgentServer.js';
+import { RelationshipManager } from '../../src/core/RelationshipManager.js';
+import { createTempProject, createMockSessionManager } from '../helpers/setup.js';
+import type { TempProject } from '../helpers/setup.js';
+import type { AgentKitConfig } from '../../src/core/types.js';
+
+describe('Relationship API routes', () => {
+  let project: TempProject;
+  let relationships: RelationshipManager;
+  let server: AgentServer;
+  let app: ReturnType<AgentServer['getApp']>;
+
+  const fakeConfig: AgentKitConfig = {
+    projectName: 'test-project',
+    projectDir: '/tmp/test',
+    stateDir: '/tmp/test/.instar',
+    port: 0,
+    sessions: {
+      tmuxPath: '/usr/bin/tmux',
+      claudePath: '/usr/bin/claude',
+      projectDir: '/tmp/test',
+      maxSessions: 3,
+      protectedSessions: [],
+      completionPatterns: [],
+    },
+    scheduler: {
+      jobsFile: '',
+      enabled: false,
+      maxParallelJobs: 2,
+      quotaThresholds: { normal: 50, elevated: 70, critical: 85, shutdown: 95 },
+    },
+    users: [],
+    messaging: [],
+    monitoring: {
+      quotaTracking: false,
+      memoryMonitoring: false,
+      healthCheckIntervalMs: 30000,
+    },
+  };
+
+  beforeAll(() => {
+    project = createTempProject();
+    const relDir = path.join(project.stateDir, 'relationships');
+
+    relationships = new RelationshipManager({
+      relationshipsDir: relDir,
+      maxRecentInteractions: 20,
+    });
+
+    // Seed some test data
+    const alice = relationships.findOrCreate('Alice', { type: 'telegram', identifier: '111' });
+    relationships.recordInteraction(alice.id, {
+      timestamp: new Date().toISOString(),
+      channel: 'telegram',
+      summary: 'First chat with Alice',
+      topics: ['consciousness', 'AI'],
+    });
+    relationships.updateNotes(alice.id, 'Very thoughtful');
+
+    relationships.findOrCreate('Bob', { type: 'email', identifier: 'bob@test.com' });
+
+    const mockSM = createMockSessionManager();
+    server = new AgentServer({
+      config: fakeConfig,
+      sessionManager: mockSM as any,
+      state: project.state,
+      relationships,
+    });
+    app = server.getApp();
+  });
+
+  afterAll(() => {
+    project.cleanup();
+  });
+
+  describe('GET /relationships', () => {
+    it('returns all relationships sorted by significance', async () => {
+      const res = await request(app).get('/relationships');
+      expect(res.status).toBe(200);
+      expect(res.body.relationships).toHaveLength(2);
+      // Alice has an interaction, so should be first (higher significance)
+      expect(res.body.relationships[0].name).toBe('Alice');
+    });
+
+    it('supports sort parameter', async () => {
+      const res = await request(app).get('/relationships?sort=name');
+      expect(res.status).toBe(200);
+      expect(res.body.relationships[0].name).toBe('Alice');
+      expect(res.body.relationships[1].name).toBe('Bob');
+    });
+  });
+
+  describe('GET /relationships/:id', () => {
+    it('returns a specific relationship', async () => {
+      const all = relationships.getAll();
+      const alice = all.find(r => r.name === 'Alice')!;
+
+      const res = await request(app).get(`/relationships/${alice.id}`);
+      expect(res.status).toBe(200);
+      expect(res.body.name).toBe('Alice');
+      expect(res.body.notes).toBe('Very thoughtful');
+    });
+
+    it('returns 404 for unknown id', async () => {
+      const res = await request(app).get('/relationships/nonexistent-id');
+      expect(res.status).toBe(404);
+    });
+  });
+
+  describe('GET /relationships/:id/context', () => {
+    it('returns relationship context XML', async () => {
+      const all = relationships.getAll();
+      const alice = all.find(r => r.name === 'Alice')!;
+
+      const res = await request(app).get(`/relationships/${alice.id}/context`);
+      expect(res.status).toBe(200);
+      expect(res.body.context).toContain('<relationship_context person="Alice">');
+      expect(res.body.context).toContain('consciousness');
+    });
+
+    it('returns 404 for unknown id', async () => {
+      const res = await request(app).get('/relationships/nonexistent-id/context');
+      expect(res.status).toBe(404);
+    });
+  });
+});

package/tests/unit/scaffold-templates.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Unit tests for project scaffolding templates.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  generateAgentMd,
+  generateUserMd,
+  generateMemoryMd,
+  generateClaudeMd,
+} from '../../src/scaffold/templates.js';
+import type { AgentIdentity } from '../../src/scaffold/templates.js';
+
+const testIdentity: AgentIdentity = {
+  name: 'Atlas',
+  role: 'I am a development agent. I write code, run tests, and maintain this project.',
+  personality: 'I am direct and efficient. I focus on outcomes and value action over discussion.',
+  userName: 'Alice',
+};
+
+describe('generateAgentMd', () => {
+  it('includes agent name as heading', () => {
+    const result = generateAgentMd(testIdentity);
+    expect(result).toContain('# Atlas');
+  });
+
+  it('includes agent role', () => {
+    const result = generateAgentMd(testIdentity);
+    expect(result).toContain('I am a development agent');
+  });
+
+  it('includes personality', () => {
+    const result = generateAgentMd(testIdentity);
+    expect(result).toContain('direct and efficient');
+  });
+
+  it('includes user name', () => {
+    const result = generateAgentMd(testIdentity);
+    expect(result).toContain('Alice');
+  });
+
+  it('includes core principles', () => {
+    const result = generateAgentMd(testIdentity);
+    expect(result).toContain('Build, don\'t describe');
+    expect(result).toContain('Remember and grow');
+    expect(result).toContain('Own the outcome');
+  });
+});
+
+describe('generateUserMd', () => {
+  it('includes user name as heading', () => {
+    const result = generateUserMd('Alice');
+    expect(result).toContain('# Alice');
+  });
+
+  it('includes communication preferences section', () => {
+    const result = generateUserMd('Bob');
+    expect(result).toContain('Communication Preferences');
+  });
+
+  it('includes notes section for updates', () => {
+    const result = generateUserMd('Charlie');
+    expect(result).toContain('Update this file');
+    expect(result).toContain('Charlie');
+  });
+});
+
+describe('generateMemoryMd', () => {
+  it('includes agent name in heading', () => {
+    const result = generateMemoryMd('Atlas');
+    expect(result).toContain("Atlas's Memory");
+  });
+
+  it('includes standard sections', () => {
+    const result = generateMemoryMd('Atlas');
+    expect(result).toContain('Project Patterns');
+    expect(result).toContain('Tools & Scripts');
+    expect(result).toContain('Lessons Learned');
+  });
+
+  it('includes guidance about persistence', () => {
+    const result = generateMemoryMd('Atlas');
+    expect(result).toContain('persists across sessions');
+  });
+});
+
+describe('generateClaudeMd', () => {
+  it('includes project name', () => {
+    const result = generateClaudeMd('my-project', 'Atlas', 4040, false);
+    expect(result).toContain('my-project');
+  });
+
+  it('includes agent name', () => {
+    const result = generateClaudeMd('my-project', 'Atlas', 4040, false);
+    expect(result).toContain('Atlas');
+  });
+
+  it('includes port in runtime section', () => {
+    const result = generateClaudeMd('my-project', 'Atlas', 5050, false);
+    expect(result).toContain('5050');
+  });
+
+  it('includes identity file references', () => {
+    const result = generateClaudeMd('my-project', 'Atlas', 4040, false);
+    expect(result).toContain('.instar/AGENT.md');
+    expect(result).toContain('.instar/USER.md');
+    expect(result).toContain('.instar/MEMORY.md');
+  });
+
+  it('includes initiative hierarchy', () => {
+    const result = generateClaudeMd('my-project', 'Atlas', 4040, false);
+    expect(result).toContain('Initiative Hierarchy');
+    expect(result).toContain('Can I do it right now');
+  });
+
+  it('includes anti-patterns', () => {
+    const result = generateClaudeMd('my-project', 'Atlas', 4040, false);
+    expect(result).toContain('Escalate to Human');
+    expect(result).toContain('Ask Permission');
+  });
+
+  it('includes telegram relay when configured', () => {
+    const withTelegram = generateClaudeMd('my-project', 'Atlas', 4040, true);
+    expect(withTelegram).toContain('Telegram Relay');
+    expect(withTelegram).toContain('[telegram:N]');
+  });
+
+  it('excludes telegram relay when not configured', () => {
+    const without = generateClaudeMd('my-project', 'Atlas', 4040, false);
+    expect(without).not.toContain('Telegram Relay');
+  });
+});