ultraclaude-agent 0.0.3

package/src/config.ts

@@ -0,0 +1,207 @@
+// Configuration, paths, and credential management for the sync agent daemon
+
+import { homedir, platform } from 'node:os';
+import { join, basename } from 'node:path';
+import { readFile, writeFile, mkdir, unlink, access, readdir } from 'node:fs/promises';
+import type { AgentCredentials, ProjectRegistry } from '@ultra-claude/shared';
+
+// --- Paths ---
+
+function resolveConfigDir(): string {
+  if (platform() === 'win32') {
+    // Windows: use %APPDATA%\ultraclaude-agent\
+    const appData = process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming');
+    return join(appData, 'ultraclaude-agent');
+  }
+  return join(homedir(), '.claude', 'ultra', 'dashboard');
+}
+
+const CONFIG_DIR = resolveConfigDir();
+const CREDENTIALS_FILE = join(CONFIG_DIR, 'credentials.json');
+const PID_FILE = join(CONFIG_DIR, 'daemon.pid');
+const LOG_DIR = join(CONFIG_DIR, 'logs');
+// Registry is auto-discovered from ~/.claude/projects/ — no file needed
+const PROJECT_ID_FILE = '.claude/ultra/project-id';
+
+export const paths = {
+  configDir: CONFIG_DIR,
+  credentials: CREDENTIALS_FILE,
+  pid: PID_FILE,
+  logDir: LOG_DIR,
+  claudeProjects: join(homedir(), '.claude', 'projects'),
+  projectIdFile: PROJECT_ID_FILE,
+} as const;
+
+// --- Server URL ---
+
+export function getServerUrl(credentials?: AgentCredentials | null): string {
+  return (
+    process.env.ULTRACLAUDE_DASHBOARD_URL ??
+    credentials?.serverUrl ??
+    'https://dashboard.ultra-claude.dev'
+  );
+}
+
+// --- Credentials ---
+
+export async function loadCredentials(): Promise<AgentCredentials | null> {
+  try {
+    const data = await readFile(CREDENTIALS_FILE, 'utf8');
+    return JSON.parse(data) as AgentCredentials;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveCredentials(creds: AgentCredentials): Promise<void> {
+  await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  await writeFile(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+
+// --- PID file ---
+
+export async function writePid(): Promise<void> {
+  await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  await writeFile(PID_FILE, String(process.pid));
+}
+
+export async function readPid(): Promise<number | null> {
+  try {
+    const pid = parseInt(await readFile(PID_FILE, 'utf8'), 10);
+    return Number.isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+export async function removePid(): Promise<void> {
+  try {
+    await unlink(PID_FILE);
+  } catch {
+    // Ignore if already gone
+  }
+}
+
+export function isDaemonRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- Registry (auto-discovery) ---
+
+/**
+ * Decode a Claude Code project directory name back to a real filesystem path.
+ * Claude encodes paths by replacing / with - (e.g., /home/user/my-project -> -home-user-my-project).
+ * Since hyphens also appear in real directory names, we try all possible splits
+ * and return the first path that actually exists on disk.
+ */
+async function decodeProjectPath(encoded: string): Promise<string | null> {
+  // Strip leading dash: "-home-user-project" -> "home-user-project"
+  const segments = encoded.slice(1).split('-');
+
+  // Recursively try combining segments with / or - at each position
+  async function tryResolve(idx: number, current: string): Promise<string | null> {
+    if (idx === segments.length) {
+      // Check if this path has a .claude/ultra/version.json
+      try {
+        await access(join('/', current, '.claude', 'ultra', 'version.json'));
+        return '/' + current;
+      } catch {
+        return null;
+      }
+    }
+
+    const seg = segments[idx]!;
+
+    // Try as new path segment (/)
+    const withSlash = current ? `${current}/${seg}` : seg;
+    const slashResult = await tryResolve(idx + 1, withSlash);
+    if (slashResult) return slashResult;
+
+    // Try as continuation of current segment (-)
+    if (current) {
+      const lastSlash = current.lastIndexOf('/');
+      const prefix = lastSlash >= 0 ? current.slice(0, lastSlash + 1) : '';
+      const lastSeg = lastSlash >= 0 ? current.slice(lastSlash + 1) : current;
+      const withDash = `${prefix}${lastSeg}-${seg}`;
+      return tryResolve(idx + 1, withDash);
+    }
+
+    return null;
+  }
+
+  return tryResolve(0, '');
+}
+
+/**
+ * Auto-discover Ultra Claude projects by scanning ~/.claude/projects/.
+ * A project is an Ultra Claude project if it has .claude/ultra/version.json.
+ */
+export async function loadRegistry(): Promise<ProjectRegistry> {
+  const claudeProjectsDir = join(homedir(), '.claude', 'projects');
+  const projects: ProjectRegistry['projects'] = [];
+
+  try {
+    const entries = await readdir(claudeProjectsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const realPath = await decodeProjectPath(entry.name);
+      if (realPath) {
+        // Read project name from app-context.md or fall back to directory name
+        let name = basename(realPath);
+        try {
+          const ctx = await readFile(join(realPath, '.claude', 'ultra', 'app-context.md'), 'utf8');
+          const nameMatch = ctx.match(/\*\*Name:\*\*\s*(.+)/);
+          if (nameMatch) name = nameMatch[1]!.trim();
+        } catch {
+          // Use directory name
+        }
+
+        projects.push({ path: realPath, name });
+      }
+    }
+  } catch {
+    // ~/.claude/projects/ doesn't exist
+  }
+
+  return { projects };
+}
+
+// --- Project ID ---
+
+export async function getProjectId(projectPath: string): Promise<string | null> {
+  try {
+    return (await readFile(join(projectPath, PROJECT_ID_FILE), 'utf8')).trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function writeProjectId(projectPath: string, id: string): Promise<void> {
+  const dir = join(projectPath, '.claude', 'ultra');
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(projectPath, PROJECT_ID_FILE), id, 'utf8');
+}
+
+// --- Log dir ---
+
+export async function ensureLogDir(): Promise<void> {
+  await mkdir(LOG_DIR, { recursive: true });
+}
+
+// --- File existence check ---
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/daemon.ts

@@ -0,0 +1,264 @@
+// Global daemon — manages project registry, per-project watchers, lifecycle
+
+import chokidar from 'chokidar';
+import { basename } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import {
+  paths,
+  loadCredentials,
+  loadRegistry,
+  getProjectId,
+  writeProjectId,
+  writePid,
+  removePid,
+} from './config.js';
+import { startProjectWatcher, type ProjectWatcher } from './watcher.js';
+import { createProjectOnServer, initialSync, stopSync } from './sync.js';
+import { startUsageWatcher, type UsageWatcher } from './usage-sync.js';
+import { logger } from './logger.js';
+import { ok, err, type Result } from '@ultra-claude/shared';
+import type { ProjectRegistryEntry } from '@ultra-claude/shared';
+
+/**
+ * Compare two semver-style version strings (e.g. "1.2.3").
+ * Returns negative if a < b, 0 if equal, positive if a > b.
+ */
+function compareVersions(a: string, b: string): number {
+  const partsA = a.split('.').map(Number);
+  const partsB = b.split('.').map(Number);
+  const len = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Check npm registry for a newer version. Non-blocking — network errors are silently ignored.
+ */
+export async function checkForUpdate(): Promise<void> {
+  const log = logger.child({ op: 'versionCheck' });
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    const pkgJson = JSON.parse(await readFile(pkgPath, 'utf8')) as { version: string };
+    const currentVersion = pkgJson.version;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2000);
+
+    const res = await fetch('https://registry.npmjs.org/ultraclaude-agent/latest', {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return;
+
+    const data = (await res.json()) as { version: string };
+    const latestVersion = data.version;
+
+    if (compareVersions(currentVersion, latestVersion) < 0) {
+      log.info(
+        { current: currentVersion, latest: latestVersion },
+        `Update available: ${currentVersion} → ${latestVersion}. Run: npm update -g ultraclaude-agent`,
+      );
+    }
+  } catch {
+    // Network error, timeout, or parse error — silently ignore
+  }
+}
+
+const activeWatchers = new Map<string, ProjectWatcher>();
+let registryWatcher: ReturnType<typeof chokidar.watch> | null = null;
+let usageWatcher: UsageWatcher | null = null;
+let running = false;
+
+type StartDaemonError = 'NOT_LOGGED_IN' | 'ALREADY_RUNNING';
+
+/**
+ * Start the global daemon. Watches the project registry and manages per-project watchers.
+ */
+export async function startDaemon(): Promise<Result<void, StartDaemonError>> {
+  const log = logger.child({ op: 'daemon' });
+
+  if (running) {
+    log.warn('Daemon already running in this process');
+    return err('ALREADY_RUNNING', 'Daemon already running in this process');
+  }
+
+  // Verify credentials
+  const creds = await loadCredentials();
+  if (!creds) {
+    return err('NOT_LOGGED_IN', 'Not logged in — run `ultraclaude-dashboard-agent login` first');
+  }
+
+  running = true;
+  await writePid();
+
+  // Register process-level handlers per error-handling.md §Daemon Process Lifecycle
+  const gracefulShutdown = async (exitCode: number) => {
+    await stopDaemon();
+    process.exit(exitCode);
+  };
+
+  process.on('SIGTERM', () => {
+    log.info({ signal: 'SIGTERM' }, 'Shutting down');
+    gracefulShutdown(0);
+  });
+  process.on('SIGINT', () => {
+    log.info({ signal: 'SIGINT' }, 'Shutting down');
+    gracefulShutdown(0);
+  });
+  process.on('uncaughtException', (error: Error) => {
+    logger.fatal({ err: error }, 'Uncaught exception — shutting down');
+    gracefulShutdown(1);
+  });
+  process.on('unhandledRejection', (reason: unknown) => {
+    logger.error({ err: reason }, 'Unhandled rejection in background task');
+    // Do NOT exit — log and continue. The offending promise should be fixed.
+  });
+
+  log.info('Daemon starting');
+
+  // Fire-and-forget version check — non-blocking, errors silently ignored
+  checkForUpdate().catch(() => {});
+
+  // Start global usage watcher (watches ~/.claude/ultra/ for usage-status.json and accounts/)
+  usageWatcher = startUsageWatcher();
+
+  // Load initial registry and start watchers
+  const registry = await loadRegistry();
+  log.info({ projectCount: registry.projects.length }, 'Registry loaded');
+
+  for (const entry of registry.projects) {
+    await ensureProject(entry);
+  }
+
+  // Watch ~/.claude/projects/ for new projects being opened
+  registryWatcher = chokidar.watch(paths.claudeProjects, {
+    persistent: true,
+    ignoreInitial: true,
+    depth: 0,
+  });
+
+  registryWatcher.on('addDir', async () => {
+    log.info('New Claude project directory detected — reconciling');
+    await reconcileWatchers();
+  });
+
+  log.info('Daemon running');
+  return ok(undefined);
+}
+
+/**
+ * Stop the daemon and clean up all watchers.
+ */
+export async function stopDaemon(): Promise<void> {
+  const log = logger.child({ op: 'daemon' });
+  running = false;
+
+  // Close usage watcher
+  if (usageWatcher) {
+    await usageWatcher.close();
+    usageWatcher = null;
+  }
+
+  // Close registry watcher
+  if (registryWatcher) {
+    await registryWatcher.close();
+    registryWatcher = null;
+  }
+
+  // Close all project watchers
+  const closePromises = Array.from(activeWatchers.values()).map((w) => w.close());
+  await Promise.all(closePromises);
+  activeWatchers.clear();
+
+  stopSync();
+  await removePid();
+
+  log.info('Daemon stopped');
+}
+
+/**
+ * Ensure a project has a server-side ID and start watching it.
+ */
+async function ensureProject(entry: ProjectRegistryEntry): Promise<void> {
+  const log = logger.child({ project: entry.name, path: entry.path });
+
+  // Skip if already watching
+  if (activeWatchers.has(entry.path)) return;
+
+  // Check/create project ID
+  let projectId = await getProjectId(entry.path);
+
+  if (!projectId) {
+    log.info('No project-id found — auto-creating on server');
+    const slug = entry.name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+    const result = await createProjectOnServer(entry.name, slug);
+
+    if (!result) {
+      log.error('Failed to auto-create project — will retry on next registry change');
+      return;
+    }
+
+    projectId = result.id;
+    await writeProjectId(entry.path, projectId);
+    log.info({ projectId }, 'Project created and ID written');
+  }
+
+  // Start watcher
+  const watcher = startProjectWatcher({ projectId, projectPath: entry.path });
+  activeWatchers.set(entry.path, watcher);
+
+  // Initial sync in background (wrapped in catch per error-handling standard)
+  initialSync(projectId, entry.path).catch((syncErr: unknown) => {
+    log.error({ err: syncErr }, 'Initial sync failed');
+  });
+}
+
+/**
+ * Reconcile active watchers with the current registry.
+ * Add watchers for new projects, remove watchers for removed projects.
+ */
+async function reconcileWatchers(): Promise<void> {
+  const log = logger.child({ op: 'reconcile' });
+  const registry = await loadRegistry();
+  const registryPaths = new Set(registry.projects.map((p) => p.path));
+
+  // Stop watchers for removed projects
+  for (const [path, watcher] of activeWatchers) {
+    if (!registryPaths.has(path)) {
+      log.info({ project: basename(path) }, 'Project removed from registry — stopping watcher');
+      await watcher.close();
+      activeWatchers.delete(path);
+    }
+  }
+
+  // Start watchers for new projects
+  for (const entry of registry.projects) {
+    if (!activeWatchers.has(entry.path)) {
+      log.info({ project: entry.name }, 'New project detected — starting watcher');
+      await ensureProject(entry);
+    }
+  }
+}
+
+/**
+ * Get status of all active project watchers.
+ */
+export function getDaemonStatus(): { running: boolean; usageWatcher: boolean; projects: { path: string; projectId: string }[] } {
+  return {
+    running,
+    usageWatcher: usageWatcher !== null,
+    projects: Array.from(activeWatchers.values()).map((w) => ({
+      path: w.projectPath,
+      projectId: w.projectId,
+    })),
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// @ultra-claude/agent — CLI/daemon entry point
+// Run via: ultraclaude-dashboard-agent <command>
+// See cli.ts for all commands
+
+export { startDaemon, stopDaemon, getDaemonStatus } from './daemon.js';
+export { login } from './auth.js';
+export { installService, uninstallService, isServiceInstalled } from './service.js';

package/src/logger.ts

@@ -0,0 +1,42 @@
+// Pino logger for the sync agent daemon
+
+import pino from 'pino';
+
+const REDACT_CONFIG = {
+  paths: [
+    'apiKey',
+    '*.apiKey',
+    'credentials',
+    '*.credentials',
+    'token',
+    '*.token',
+    'password',
+    '*.password',
+    'secret',
+    '*.secret',
+    'req.headers.authorization',
+    'req.headers.cookie',
+  ],
+  censor: '[REDACTED]',
+};
+
+function createLogger() {
+  const isForeground = process.argv.includes('--foreground') || process.env.NODE_ENV !== 'production';
+
+  if (isForeground) {
+    // Interactive / foreground mode: pretty-print to stderr
+    return pino({
+      level: process.env.LOG_LEVEL ?? 'info',
+      redact: REDACT_CONFIG,
+      transport: { target: 'pino-pretty', options: { colorize: true } },
+    });
+  }
+
+  // Background daemon mode: JSON to stdout (captured by systemd/launchd)
+  return pino({
+    level: process.env.LOG_LEVEL ?? 'info',
+    redact: REDACT_CONFIG,
+  });
+}
+
+export const logger = createLogger();