instar 0.1.0

package/src/commands/status.ts

@@ -0,0 +1,125 @@
+/**
+ * `instar status` — Show agent infrastructure status.
+ *
+ * Checks for: config, tmux, server, sessions, scheduler.
+ */
+
+import { execSync } from 'node:child_process';
+import pc from 'picocolors';
+import { loadConfig, detectTmuxPath } from '../core/Config.js';
+import { StateManager } from '../core/StateManager.js';
+
+interface StatusOptions {
+  dir?: string;
+}
+
+export async function showStatus(options: StatusOptions): Promise<void> {
+  let config;
+  try {
+    config = loadConfig(options.dir);
+  } catch (err: any) {
+    console.log(pc.red(`Not initialized: ${err.message}`));
+    console.log(`Run ${pc.cyan('instar init')} first.`);
+    return;
+  }
+
+  console.log(pc.bold(`\nInstar Status: ${pc.cyan(config.projectName)}`));
+  console.log(`  Project: ${config.projectDir}`);
+  console.log(`  State:   ${config.stateDir}`);
+  console.log();
+
+  // Server status
+  const serverSessionName = `${config.projectName}-server`;
+  const tmuxPath = detectTmuxPath();
+  let serverRunning = false;
+
+  if (tmuxPath) {
+    try {
+      execSync(`${tmuxPath} has-session -t '=${serverSessionName}' 2>/dev/null`);
+      serverRunning = true;
+    } catch {
+      // not running
+    }
+  }
+
+  console.log(pc.bold('  Server:'));
+  if (serverRunning) {
+    console.log(`    ${pc.green('●')} Running (tmux: ${serverSessionName}, port: ${config.port})`);
+
+    // Try to hit health endpoint
+    try {
+      const resp = execSync(`curl -s http://localhost:${config.port}/health`, { encoding: 'utf-8', timeout: 3000 });
+      const health = JSON.parse(resp);
+      console.log(`    Uptime: ${health.uptimeHuman}`);
+    } catch {
+      console.log(`    ${pc.yellow('Could not reach health endpoint')}`);
+    }
+  } else {
+    console.log(`    ${pc.red('●')} Not running`);
+  }
+
+  // Sessions
+  const state = new StateManager(config.stateDir);
+  const runningSessions = state.listSessions({ status: 'running' });
+  const allSessions = state.listSessions();
+
+  console.log();
+  console.log(pc.bold('  Sessions:'));
+  console.log(`    Running: ${runningSessions.length} / ${config.sessions.maxSessions} max`);
+  console.log(`    Total:   ${allSessions.length}`);
+
+  if (runningSessions.length > 0) {
+    for (const s of runningSessions) {
+      const age = timeSince(new Date(s.startedAt));
+      console.log(`    ${pc.green('●')} ${s.name} (${age}${s.jobSlug ? `, job: ${s.jobSlug}` : ''})`);
+    }
+  }
+
+  // Scheduler
+  console.log();
+  console.log(pc.bold('  Scheduler:'));
+  console.log(`    Enabled: ${config.scheduler.enabled ? pc.green('yes') : pc.dim('no')}`);
+
+  // Jobs
+  try {
+    const { loadJobs } = await import('../scheduler/JobLoader.js');
+    const jobs = loadJobs(config.scheduler.jobsFile);
+    const enabled = jobs.filter(j => j.enabled);
+    console.log(`    Jobs: ${enabled.length} enabled / ${jobs.length} total`);
+
+    if (jobs.length > 0) {
+      for (const job of jobs) {
+        const jobState = state.getJobState(job.slug);
+        const icon = job.enabled ? pc.green('●') : pc.dim('○');
+        const lastRun = jobState?.lastRun ? timeSince(new Date(jobState.lastRun)) + ' ago' : 'never';
+        console.log(`    ${icon} ${job.slug} [${job.priority}] — last: ${lastRun}`);
+      }
+    }
+  } catch {
+    console.log(`    ${pc.dim('No jobs configured')}`);
+  }
+
+  // Recent activity
+  const recentEvents = state.queryEvents({ limit: 5 });
+  if (recentEvents.length > 0) {
+    console.log();
+    console.log(pc.bold('  Recent Activity:'));
+    for (const event of recentEvents) {
+      const age = timeSince(new Date(event.timestamp));
+      console.log(`    ${pc.dim(age + ' ago')} ${event.type}: ${event.summary}`);
+    }
+  }
+
+  console.log();
+}
+
+function timeSince(date: Date): string {
+  const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}

package/src/commands/user.ts

@@ -0,0 +1,71 @@
+/**
+ * `instar user add|list` — Manage user profiles.
+ */
+
+import pc from 'picocolors';
+import { loadConfig, ensureStateDir } from '../core/Config.js';
+import { UserManager } from '../users/UserManager.js';
+import type { UserProfile, UserChannel } from '../core/types.js';
+
+interface UserAddOptions {
+  id: string;
+  name: string;
+  telegram?: string;
+  email?: string;
+  slack?: string;
+  permissions?: string[];
+}
+
+export async function addUser(options: UserAddOptions): Promise<void> {
+  const config = loadConfig();
+  ensureStateDir(config.stateDir);
+  const userManager = new UserManager(config.stateDir);
+
+  const channels: UserChannel[] = [];
+  if (options.telegram) {
+    channels.push({ type: 'telegram', identifier: options.telegram });
+  }
+  if (options.email) {
+    channels.push({ type: 'email', identifier: options.email });
+  }
+  if (options.slack) {
+    channels.push({ type: 'slack', identifier: options.slack });
+  }
+
+  const profile: UserProfile = {
+    id: options.id,
+    name: options.name,
+    channels,
+    permissions: options.permissions || ['user'],
+    preferences: {},
+  };
+
+  userManager.upsertUser(profile);
+
+  console.log(pc.green(`User "${options.name}" (${options.id}) added.`));
+  if (channels.length > 0) {
+    console.log(`  Channels: ${channels.map(c => `${c.type}:${c.identifier}`).join(', ')}`);
+  }
+  console.log(`  Permissions: ${profile.permissions.join(', ')}`);
+}
+
+export async function listUsers(_options: { dir?: string }): Promise<void> {
+  const config = loadConfig();
+  const userManager = new UserManager(config.stateDir);
+  const users = userManager.listUsers();
+
+  if (users.length === 0) {
+    console.log(pc.dim('No users configured.'));
+    console.log(`Add one: ${pc.cyan('instar user add --id justin --name Justin')}`);
+    return;
+  }
+
+  console.log(pc.bold(`Users (${users.length}):\n`));
+  for (const user of users) {
+    console.log(`  ${pc.bold(user.name)} (${pc.dim(user.id)})`);
+    if (user.channels.length > 0) {
+      console.log(`    Channels: ${user.channels.map(c => `${c.type}:${c.identifier}`).join(', ')}`);
+    }
+    console.log(`    Permissions: ${user.permissions.join(', ')}`);
+  }
+}

package/src/core/Config.ts

@@ -0,0 +1,161 @@
+/**
+ * Auto-detection and configuration management.
+ *
+ * Finds tmux, Claude CLI, and project structure automatically.
+ * Adapted from dawn-server's config.ts — the battle-tested version.
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { AgentKitConfig, SessionManagerConfig, JobSchedulerConfig } from './types.js';
+
+const DEFAULT_PORT = 4040;
+const DEFAULT_MAX_SESSIONS = 3;
+const DEFAULT_MAX_PARALLEL_JOBS = 2;
+
+export function detectTmuxPath(): string | null {
+  const candidates = [
+    '/opt/homebrew/bin/tmux',  // macOS ARM (Homebrew)
+    '/usr/local/bin/tmux',     // macOS Intel / Linux
+    '/usr/bin/tmux',           // Linux system
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  // Fallback: check PATH
+  try {
+    const result = execSync('which tmux', { encoding: 'utf-8' }).trim();
+    if (result && fs.existsSync(result)) return result;
+  } catch {
+    // tmux not found
+  }
+
+  return null;
+}
+
+export function detectClaudePath(): string | null {
+  const candidates = [
+    path.join(process.env.HOME || '', '.claude', 'local', 'claude'),
+    '/usr/local/bin/claude',
+    '/opt/homebrew/bin/claude',
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  // Fallback: check PATH
+  try {
+    const result = execSync('which claude', { encoding: 'utf-8' }).trim();
+    if (result && fs.existsSync(result)) return result;
+  } catch {
+    // claude not found
+  }
+
+  return null;
+}
+
+export function detectProjectDir(startDir?: string): string {
+  let dir = startDir || process.cwd();
+
+  // Walk up to find a directory with CLAUDE.md or .git
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'CLAUDE.md')) || fs.existsSync(path.join(dir, '.git'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return process.cwd();
+}
+
+export function loadConfig(projectDir?: string): AgentKitConfig {
+  const resolvedProjectDir = projectDir || detectProjectDir();
+  const configPath = path.join(resolvedProjectDir, '.instar', 'config.json');
+  const stateDir = path.join(resolvedProjectDir, '.instar');
+
+  // Load config file if it exists
+  let fileConfig: Partial<AgentKitConfig> = {};
+  if (fs.existsSync(configPath)) {
+    fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  }
+
+  const tmuxPath = detectTmuxPath();
+  const claudePath = detectClaudePath();
+
+  if (!tmuxPath) {
+    throw new Error('tmux not found. Install with: brew install tmux (macOS) or apt install tmux (Linux)');
+  }
+  if (!claudePath) {
+    throw new Error('Claude CLI not found. Install from: https://docs.anthropic.com/en/docs/claude-code');
+  }
+
+  const projectName = fileConfig.projectName || path.basename(resolvedProjectDir);
+
+  const sessions: SessionManagerConfig = {
+    tmuxPath,
+    claudePath,
+    projectDir: resolvedProjectDir,
+    maxSessions: fileConfig.sessions?.maxSessions || DEFAULT_MAX_SESSIONS,
+    protectedSessions: fileConfig.sessions?.protectedSessions || [`${projectName}-server`],
+    completionPatterns: fileConfig.sessions?.completionPatterns || [
+      'has been automatically paused',
+      'Session ended',
+      'Interrupted by user',
+    ],
+  };
+
+  const scheduler: JobSchedulerConfig = {
+    jobsFile: fileConfig.scheduler?.jobsFile || path.join(stateDir, 'jobs.json'),
+    enabled: fileConfig.scheduler?.enabled ?? false,
+    maxParallelJobs: fileConfig.scheduler?.maxParallelJobs ?? DEFAULT_MAX_PARALLEL_JOBS,
+    quotaThresholds: fileConfig.scheduler?.quotaThresholds || {
+      normal: 50,
+      elevated: 70,
+      critical: 85,
+      shutdown: 95,
+    },
+  };
+
+  return {
+    projectName,
+    projectDir: resolvedProjectDir,
+    stateDir,
+    port: fileConfig.port || DEFAULT_PORT,
+    sessions,
+    scheduler,
+    users: fileConfig.users || [],
+    messaging: fileConfig.messaging || [],
+    monitoring: fileConfig.monitoring || {
+      quotaTracking: true,
+      memoryMonitoring: true,
+      healthCheckIntervalMs: 30000,
+    },
+    authToken: fileConfig.authToken,
+    relationships: fileConfig.relationships || {
+      relationshipsDir: path.join(stateDir, 'relationships'),
+      maxRecentInteractions: 20,
+    },
+  };
+}
+
+/**
+ * Ensure the state directory structure exists.
+ */
+export function ensureStateDir(stateDir: string): void {
+  const dirs = [
+    stateDir,
+    path.join(stateDir, 'state'),
+    path.join(stateDir, 'state', 'sessions'),
+    path.join(stateDir, 'state', 'jobs'),
+    path.join(stateDir, 'relationships'),
+    path.join(stateDir, 'logs'),
+  ];
+
+  for (const dir of dirs) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}

package/src/core/Prerequisites.ts

@@ -0,0 +1,187 @@
+/**
+ * Prerequisite detection and installation guidance.
+ *
+ * Checks for required software (tmux, Claude CLI, Node.js)
+ * and provides clear installation instructions when something is missing.
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import pc from 'picocolors';
+import { detectTmuxPath, detectClaudePath } from './Config.js';
+
+export interface PrerequisiteResult {
+  name: string;
+  found: boolean;
+  path?: string;
+  version?: string;
+  installHint: string;
+}
+
+export interface PrerequisiteCheck {
+  allMet: boolean;
+  results: PrerequisiteResult[];
+  missing: PrerequisiteResult[];
+}
+
+/**
+ * Detect the current platform for install guidance.
+ */
+function detectPlatform(): 'macos-arm' | 'macos-intel' | 'linux' | 'unknown' {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    const arch = process.arch;
+    return arch === 'arm64' ? 'macos-arm' : 'macos-intel';
+  }
+  if (platform === 'linux') return 'linux';
+  return 'unknown';
+}
+
+/**
+ * Check if Homebrew is available (macOS).
+ */
+function hasHomebrew(): boolean {
+  try {
+    execSync('which brew', { encoding: 'utf-8', stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get tmux version if installed.
+ */
+function getTmuxVersion(tmuxPath: string): string | undefined {
+  try {
+    const output = execSync(`${tmuxPath} -V`, { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    return output.replace('tmux ', '');
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Get Claude CLI version if installed.
+ */
+function getClaudeVersion(claudePath: string): string | undefined {
+  try {
+    const output = execSync(`${claudePath} --version 2>/dev/null || echo unknown`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      timeout: 5000,
+    }).trim();
+    return output || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Get Node.js version.
+ */
+function getNodeVersion(): { version: string; major: number } {
+  const version = process.version; // e.g., "v20.11.0"
+  const major = parseInt(version.slice(1).split('.')[0], 10);
+  return { version, major };
+}
+
+/**
+ * Build install hint for tmux based on platform.
+ */
+function tmuxInstallHint(): string {
+  const platform = detectPlatform();
+  switch (platform) {
+    case 'macos-arm':
+    case 'macos-intel':
+      return hasHomebrew()
+        ? 'Install with: brew install tmux'
+        : 'Install Homebrew first (https://brew.sh), then: brew install tmux';
+    case 'linux':
+      return 'Install with: sudo apt install tmux (Debian/Ubuntu) or sudo yum install tmux (RHEL/CentOS)';
+    default:
+      return 'Install tmux: https://github.com/tmux/tmux/wiki/Installing';
+  }
+}
+
+/**
+ * Build install hint for Claude CLI based on platform.
+ */
+function claudeInstallHint(): string {
+  return 'Install Claude Code: npm install -g @anthropic-ai/claude-code\n  Docs: https://docs.anthropic.com/en/docs/claude-code';
+}
+
+/**
+ * Check all prerequisites and return a structured result.
+ */
+export function checkPrerequisites(): PrerequisiteCheck {
+  const results: PrerequisiteResult[] = [];
+
+  // 1. Node.js >= 18
+  const node = getNodeVersion();
+  results.push({
+    name: 'Node.js',
+    found: node.major >= 18,
+    version: node.version,
+    installHint: node.major < 18
+      ? `Node.js 18+ required (found ${node.version}). Update: https://nodejs.org`
+      : '',
+  });
+
+  // 2. tmux
+  const tmuxPath = detectTmuxPath();
+  results.push({
+    name: 'tmux',
+    found: !!tmuxPath,
+    path: tmuxPath || undefined,
+    version: tmuxPath ? getTmuxVersion(tmuxPath) : undefined,
+    installHint: tmuxInstallHint(),
+  });
+
+  // 3. Claude CLI
+  const claudePath = detectClaudePath();
+  results.push({
+    name: 'Claude CLI',
+    found: !!claudePath,
+    path: claudePath || undefined,
+    version: claudePath ? getClaudeVersion(claudePath) : undefined,
+    installHint: claudeInstallHint(),
+  });
+
+  const missing = results.filter(r => !r.found);
+
+  return {
+    allMet: missing.length === 0,
+    results,
+    missing,
+  };
+}
+
+/**
+ * Print prerequisite check results to console.
+ * Returns true if all prerequisites are met.
+ */
+export function printPrerequisiteCheck(check: PrerequisiteCheck): boolean {
+  console.log(pc.bold('  Checking prerequisites...'));
+  console.log();
+
+  for (const result of check.results) {
+    if (result.found) {
+      const versionStr = result.version ? ` (${result.version})` : '';
+      const pathStr = result.path ? pc.dim(` ${result.path}`) : '';
+      console.log(`  ${pc.green('✓')} ${result.name}${versionStr}${pathStr}`);
+    } else {
+      console.log(`  ${pc.red('✗')} ${result.name} — not found`);
+      console.log(`    ${result.installHint}`);
+    }
+  }
+
+  console.log();
+
+  if (!check.allMet) {
+    console.log(pc.red(`  ${check.missing.length} prerequisite(s) missing. Install them and try again.`));
+    console.log();
+  }
+
+  return check.allMet;
+}