@mamdouh-aboammar/agentic-workflow 1.2.0

package/src/system/notifications.ts

@@ -0,0 +1,180 @@
+/**
+ * src/system/notifications.ts — CLI/Terminal Banner & Desktop Notification Engine
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import type { NotificationPayload, NotificationRecord, NotificationLevel } from './types.ts';
+
+export class NotificationEngine {
+  private projectDir: string;
+  private historyFile: string;
+  private recentDispatches: Map<string, number> = new Map();
+
+  constructor(projectDir: string = '.') {
+    this.projectDir = path.resolve(projectDir);
+    this.historyFile = path.join(this.projectDir, '.notifications.json');
+  }
+
+  private isHeadless(): boolean {
+    return !!(process.env.CI || !process.stdout.isTTY);
+  }
+
+  public renderBanner(payload: NotificationPayload): string {
+    const level = payload.level || 'INFO';
+    const timestamp = new Date(payload.timestamp || Date.now()).toLocaleTimeString();
+    const source = payload.source ? ` [${payload.source}]` : '';
+
+    let color = '\x1b[36m'; // Cyan
+    let icon = 'ℹ️';
+    switch (level) {
+      case 'SUCCESS':
+        color = '\x1b[32m'; // Green
+        icon = '✅';
+        break;
+      case 'WARN':
+        color = '\x1b[33m'; // Yellow
+        icon = '⚠️';
+        break;
+      case 'ERROR':
+      case 'CRITICAL':
+        color = '\x1b[31m'; // Red
+        icon = '🛑';
+        break;
+      case 'ANNOUNCEMENT':
+        color = '\x1b[35m'; // Magenta
+        icon = '📢';
+        break;
+    }
+
+    const reset = '\x1b[0m';
+    const bold = '\x1b[1m';
+    const titleLine = `${icon} ${bold}${color}${level}${reset}${bold}: ${payload.title}${source} (${timestamp})${reset}`;
+    const lines = payload.message.split('\n');
+
+    const width = Math.min(80, Math.max(60, payload.title.length + 20, ...lines.map(l => l.length + 6)));
+    const border = '═'.repeat(width);
+
+    return `
+${color}╔${border}╗${reset}
+  ${titleLine}
+${color}╟${border}╢${reset}
+${lines.map(l => `  ${l}`).join('\n')}
+${color}╚${border}╝${reset}
+`;
+  }
+
+  public sendDesktop(title: string, message: string, sound: boolean = true): boolean {
+    if (this.isHeadless()) return false;
+
+    const cleanTitle = title.replace(/"/g, '\\"');
+    const cleanMsg = message.replace(/"/g, '\\"');
+    const platform = os.platform();
+
+    try {
+      if (platform === 'darwin') {
+        const soundParam = sound ? 'sound name "Glass"' : '';
+        const script = `display notification "${cleanMsg}" with title "${cleanTitle}" ${soundParam}`;
+        execSync(`osascript -e '${script}'`, { stdio: 'ignore' });
+        return true;
+      } else if (platform === 'linux') {
+        execSync(`notify-send "${cleanTitle}" "${cleanMsg}"`, { stdio: 'ignore' });
+        return true;
+      }
+    } catch {
+      // Ignore desktop notification failures gracefully
+    }
+    return false;
+  }
+
+  public ringBell(): void {
+    if (!this.isHeadless()) {
+      process.stdout.write('\x07');
+    }
+  }
+
+  public send(payload: NotificationPayload): NotificationRecord {
+    const key = `${payload.level || 'INFO'}:${payload.title}:${payload.message.substring(0, 30)}`;
+    const now = Date.now();
+    const lastSent = this.recentDispatches.get(key) || 0;
+
+    // Rate-limiting deduplication: skip if identical within 3 seconds
+    if (now - lastSent < 3000) {
+      return {
+        id: payload.id || `notif_${now}`,
+        ...payload,
+        timestamp: now,
+        read: false
+      };
+    }
+    this.recentDispatches.set(key, now);
+
+    const record: NotificationRecord = {
+      id: payload.id || `notif_${now}_${Math.random().toString(36).substring(2, 6)}`,
+      title: payload.title,
+      message: payload.message,
+      level: payload.level || 'INFO',
+      source: payload.source || 'system',
+      timestamp: payload.timestamp || now,
+      sound: payload.sound !== false,
+      desktop: payload.desktop !== false,
+      terminal: payload.terminal !== false,
+      actionUrl: payload.actionUrl,
+      read: false
+    };
+
+    // 1. Terminal banner
+    if (record.terminal) {
+      console.log(this.renderBanner(record));
+    }
+
+    // 2. Audible bell
+    if (record.sound && (record.level === 'CRITICAL' || record.level === 'ERROR')) {
+      this.ringBell();
+    }
+
+    // 3. Desktop dispatch
+    if (record.desktop) {
+      this.sendDesktop(record.title, record.message, record.sound);
+    }
+
+    // 4. Save to history
+    this.saveToHistory(record);
+    return record;
+  }
+
+  public getHistory(): NotificationRecord[] {
+    try {
+      if (fs.existsSync(this.historyFile)) {
+        return JSON.parse(fs.readFileSync(this.historyFile, 'utf-8'));
+      }
+    } catch {
+      // Ignore
+    }
+    return [];
+  }
+
+  public clearHistory(): void {
+    try {
+      if (fs.existsSync(this.historyFile)) {
+        fs.unlinkSync(this.historyFile);
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  private saveToHistory(record: NotificationRecord): void {
+    try {
+      const history = this.getHistory();
+      history.unshift(record);
+      // Keep at most 50
+      const trimmed = history.slice(0, 50);
+      fs.writeFileSync(this.historyFile, JSON.stringify(trimmed, null, 2));
+    } catch {
+      // Ignore write errors
+    }
+  }
+}

package/src/system/refresher.ts

@@ -0,0 +1,207 @@
+/**
+ * src/system/refresher.ts — Refresher & Cache Invalidation Engine
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import type { RefreshOptions, RefreshReport } from './types.ts';
+
+export class Refresher {
+  private projectDir: string;
+  private homeDir: string;
+
+  constructor(projectDir: string = '.') {
+    this.projectDir = path.resolve(projectDir);
+    this.homeDir = os.homedir();
+  }
+
+  private removeDirRecursive(dirPath: string): { count: number; bytes: number } {
+    let count = 0;
+    let bytes = 0;
+    if (!fs.existsSync(dirPath)) return { count, bytes };
+
+    try {
+      const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        const full = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+          const res = this.removeDirRecursive(full);
+          count += res.count;
+          bytes += res.bytes;
+        } else {
+          try {
+            const stat = fs.statSync(full);
+            bytes += stat.size;
+            fs.unlinkSync(full);
+            count++;
+          } catch {
+            // Ignore
+          }
+        }
+      }
+      fs.rmdirSync(dirPath);
+    } catch {
+      // Ignore
+    }
+    return { count, bytes };
+  }
+
+  private clearBytecodeCaches(): { items: string[]; bytes: number } {
+    const items: string[] = [];
+    let bytes = 0;
+
+    const findPycache = (dir: string) => {
+      if (!fs.existsSync(dir)) return;
+      try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const full = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            if (entry.name === '__pycache__' || entry.name === '.pytest_cache') {
+              const res = this.removeDirRecursive(full);
+              items.push(path.relative(this.projectDir, full));
+              bytes += res.bytes;
+            } else if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+              findPycache(full);
+            }
+          }
+        }
+      } catch {
+        // Ignore
+      }
+    };
+
+    findPycache(this.projectDir);
+    return { items, bytes };
+  }
+
+  private cleanStaleLocks(): string[] {
+    const cleared: string[] = [];
+    const lockFiles = [
+      path.join(this.projectDir, '.lock'),
+      path.join(this.projectDir, '.git', 'index.lock'),
+      path.join(this.projectDir, '.git', 'refs', 'heads', 'main.lock')
+    ];
+
+    for (const lf of lockFiles) {
+      if (fs.existsSync(lf)) {
+        try {
+          const stat = fs.statSync(lf);
+          // If older than 5 minutes, consider stale
+          if (Date.now() - stat.mtimeMs > 5 * 60 * 1000) {
+            fs.unlinkSync(lf);
+            cleared.push(path.relative(this.projectDir, lf));
+          }
+        } catch {
+          // Ignore
+        }
+      }
+    }
+    return cleared;
+  }
+
+  public refresh(options: RefreshOptions = {}): RefreshReport {
+    const startTime = Date.now();
+    const clearedItems: string[] = [];
+    let freedBytes = 0;
+    const messages: string[] = [];
+    const hostsSynced: string[] = [];
+
+    // 1. Clear Bytecode
+    if (options.clearBytecode !== false) {
+      const { items, bytes } = this.clearBytecodeCaches();
+      clearedItems.push(...items);
+      freedBytes += bytes;
+      if (items.length > 0) {
+        messages.push(`✓ Cleared ${items.length} Python bytecode cache directory(ies)`);
+      }
+    }
+
+    // 2. Clean Stale Lockfiles
+    if (options.cleanLockfiles !== false) {
+      const locks = this.cleanStaleLocks();
+      clearedItems.push(...locks);
+      if (locks.length > 0) {
+        messages.push(`✓ Removed ${locks.length} stale lockfile(s)`);
+      }
+    }
+
+    // 3. Reset Risk Scores
+    if (options.resetRiskScores) {
+      const riskPath = path.join(this.projectDir, 'risk-scores.json');
+      if (fs.existsSync(riskPath)) {
+        try {
+          fs.unlinkSync(riskPath);
+          clearedItems.push('risk-scores.json');
+          messages.push(`✓ Reset predictive debugging risk scores cache`);
+        } catch {
+          // Ignore
+        }
+      }
+    }
+
+    // 4. Rebuild Skills Index
+    let skillsReindexed = false;
+    if (options.rebuildSkillsIndex !== false) {
+      try {
+        execSync('python3 core/skills_indexer.py index', { cwd: this.projectDir, stdio: 'pipe' });
+        skillsReindexed = true;
+        messages.push(`✓ Rebuilt skills-index.json and skills-index.toon`);
+      } catch (err: any) {
+        messages.push(`! Skills re-indexing notice: ${err.message}`);
+      }
+    }
+
+    // 5. Sync Integrations
+    let integrationsSynced = false;
+    if (options.syncIntegrations !== false) {
+      try {
+        const script = `from core.integrations import IntegrationInstaller; IntegrationInstaller('${this.projectDir}').provision_all()`;
+        execSync(`python3 -c "${script}"`, { cwd: this.projectDir, stdio: 'pipe' });
+        integrationsSynced = true;
+        messages.push(`✓ Synchronized supportive integrations (Ponytail, TOON, Fable, Caveman)`);
+      } catch (err: any) {
+        messages.push(`! Integrations sync notice: ${err.message}`);
+      }
+    }
+
+    // 6. Sync Host Skills
+    if (options.syncHostSkills) {
+      const hostDirs = [
+        path.join(this.homeDir, '.claude', 'skills', 'agentic-workflow'),
+        path.join(this.homeDir, '.gemini', 'config', 'skills', 'agentic-workflow'),
+        path.join(this.homeDir, '.cursor', 'skills', 'agentic-workflow'),
+        path.join(this.homeDir, '.agents', 'skills', 'agentic-workflow')
+      ];
+
+      for (const hDir of hostDirs) {
+        if (fs.existsSync(hDir)) {
+          try {
+            // Update SKILL.md and marketplace.json
+            fs.copyFileSync(path.join(this.projectDir, 'SKILL.md'), path.join(hDir, 'SKILL.md'));
+            hostsSynced.push(hDir);
+          } catch {
+            // Ignore
+          }
+        }
+      }
+      if (hostsSynced.length > 0) {
+        messages.push(`✓ Updated skill definitions across ${hostsSynced.length} host environments`);
+      }
+    }
+
+    const durationMs = Date.now() - startTime;
+    return {
+      success: true,
+      clearedItems,
+      freedBytes,
+      skillsReindexed,
+      integrationsSynced,
+      hostsSynced,
+      durationMs,
+      messages
+    };
+  }
+}

package/src/system/types.ts

@@ -0,0 +1,268 @@
+/**
+ * src/system/types.ts — Shared Type Definitions for AgenticWorkflow System Engines
+ */
+
+// 1. Auto-Updater Types
+export type UpdateStrategy = 'fast-forward' | 'stash-and-pull' | 'force-reset';
+
+export interface UpdateCheckResult {
+  hasUpdate: boolean;
+  currentCommit: string;
+  currentVersion: string;
+  remoteCommit: string;
+  remoteVersion?: string;
+  branch: string;
+  behindCount: number;
+  commits: Array<{ hash: string; message: string; date: string }>;
+  channel: 'stable' | 'beta' | 'nightly';
+}
+
+export interface UpdateOptions {
+  strategy?: UpdateStrategy;
+  force?: boolean;
+  branch?: string;
+  autoReinstall?: boolean;
+  autoRefresh?: boolean;
+}
+
+export interface UpdateResult {
+  success: boolean;
+  previousCommit: string;
+  newCommit: string;
+  message: string;
+  stashed: boolean;
+  reinstalled: boolean;
+  refreshed: boolean;
+}
+
+export interface RollbackResult {
+  success: boolean;
+  rolledBackTo: string;
+  message: string;
+}
+
+// 2. Auto-Installer Types
+export type HostPlatform = 'claude' | 'gemini' | 'cursor' | 'codex' | 'agents' | 'cli-symlink' | 'shell-profile';
+
+export interface InstallTarget {
+  name: string;
+  platform: HostPlatform;
+  path: string;
+  installed: boolean;
+}
+
+export interface InstallOptions {
+  targets?: HostPlatform[];
+  globalBin?: boolean;
+  updateShellRc?: boolean;
+  provisionTools?: boolean;
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+export interface InstallReport {
+  success: boolean;
+  installedTargets: InstallTarget[];
+  skippedTargets: InstallTarget[];
+  binLinked: string[];
+  shellConfigured: string[];
+  systemDeps: Array<{ name: string; available: boolean; version?: string }>;
+  messages: string[];
+}
+
+// 3. Refresher Types
+export interface RefreshOptions {
+  clearBytecode?: boolean;
+  clearTemp?: boolean;
+  rebuildSkillsIndex?: boolean;
+  syncIntegrations?: boolean;
+  syncHostSkills?: boolean;
+  resetRiskScores?: boolean;
+  cleanLockfiles?: boolean;
+}
+
+export interface RefreshReport {
+  success: boolean;
+  clearedItems: string[];
+  freedBytes: number;
+  skillsReindexed: boolean;
+  integrationsSynced: boolean;
+  hostsSynced: string[];
+  durationMs: number;
+  messages: string[];
+}
+
+// 4. Doctor Types
+export type DoctorSeverity = 'PASS' | 'WARN' | 'FAIL';
+
+export interface DoctorCheckItem {
+  id: string;
+  category: 'runtime' | 'cli' | 'git' | 'dependencies' | 'state' | 'hooks' | 'skills' | 'integrations' | 'security';
+  title: string;
+  status: DoctorSeverity;
+  details: string;
+  recommendation?: string;
+  fixable: boolean;
+}
+
+export interface DoctorReport {
+  passed: number;
+  warned: number;
+  failed: number;
+  total: number;
+  checks: DoctorCheckItem[];
+  overallHealthy: boolean;
+  timestamp: string;
+}
+
+export interface FixResult {
+  checkId: string;
+  remediated: boolean;
+  message: string;
+}
+
+// 5. Health Engine Types
+export type HealthGrade = 'A+' | 'A' | 'B' | 'C' | 'F';
+
+export interface SystemVitals {
+  platform: string;
+  arch: string;
+  uptimeSeconds: number;
+  memory: {
+    totalBytes: number;
+    freeBytes: number;
+    rssBytes: number;
+    usedPercentage: number;
+  };
+  disk: {
+    freeBytes?: number;
+    totalBytes?: number;
+  };
+  nodeVersion: string;
+  bunVersion?: string;
+  pythonVersion?: string;
+}
+
+export interface WorkflowVitals {
+  hasActiveWorkflow: boolean;
+  currentStep?: string;
+  circuitBreakerStatus: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+  failureStreak: number;
+  retryCount: number;
+  traceSpansCount: number;
+}
+
+export interface HealthScore {
+  score: number; // 0 - 100
+  grade: HealthGrade;
+  breakdown: {
+    runtime: number;     // max 20
+    workflow: number;    // max 25
+    security: number;    // max 20
+    dependencies: number;// max 15
+    integrity: number;   // max 20
+  };
+  warnings: string[];
+}
+
+export interface HealthReport {
+  timestamp: string;
+  score: HealthScore;
+  vitals: SystemVitals;
+  workflow: WorkflowVitals;
+  services: Record<string, 'HEALTHY' | 'DEGRADED' | 'DOWN'>;
+}
+
+// 6. Dependencies Engine Types
+export type DependencyType = 'bun-npm' | 'python' | 'supportive-tool' | 'system-binary';
+
+export interface DependencyItem {
+  name: string;
+  type: DependencyType;
+  requiredVersion?: string;
+  installedVersion?: string;
+  status: 'SATISFIED' | 'OUTDATED' | 'MISSING' | 'INCOMPATIBLE';
+  description?: string;
+  location?: string;
+}
+
+export interface DependencyAuditReport {
+  total: number;
+  satisfied: number;
+  missing: number;
+  outdated: number;
+  incompatible: number;
+  dependencies: DependencyItem[];
+  allSatisfied: boolean;
+}
+
+// 7. Notifications Engine Types
+export type NotificationLevel = 'INFO' | 'SUCCESS' | 'WARN' | 'ERROR' | 'CRITICAL' | 'ANNOUNCEMENT';
+
+export interface NotificationPayload {
+  id?: string;
+  title: string;
+  message: string;
+  level?: NotificationLevel;
+  source?: string;
+  timestamp?: number;
+  sound?: boolean;
+  desktop?: boolean;
+  terminal?: boolean;
+  actionUrl?: string;
+}
+
+export interface NotificationRecord extends NotificationPayload {
+  id: string;
+  timestamp: number;
+  read: boolean;
+}
+
+// 8. Announcement Engine Types
+export type AnnouncementCategory = 'SECURITY' | 'FEATURE' | 'UPDATE' | 'TIP' | 'MAINTENANCE';
+
+export interface AnnouncementItem {
+  id: string;
+  title: string;
+  body: string;
+  category: AnnouncementCategory;
+  date: string;
+  version?: string;
+  priority: 'low' | 'normal' | 'high' | 'urgent';
+  url?: string;
+}
+
+export interface AnnouncementState {
+  seenIds: string[];
+  lastChecked: string;
+}
+
+// 9. Version Tracker Types
+export interface ComponentVersion {
+  name: string;
+  version: string;
+  channel: string;
+  path?: string;
+}
+
+export interface VersionMatrix {
+  cliVersion: string;
+  tsEngineVersion: string;
+  pyEngineVersion: string;
+  toonProtocolVersion: string;
+  uahfHooksVersion: string;
+  gitCommit: string;
+  gitBranch: string;
+  gitClean: boolean;
+  buildDate: string;
+  components: ComponentVersion[];
+}
+
+export interface MigrationStep {
+  fromVersion: string;
+  toVersion: string;
+  name: string;
+  description: string;
+  executed: boolean;
+  timestamp?: string;
+}