@perceo/observer-engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+interface ObserverEngineConfig {
+    observer: {
+        watch: {
+            paths: string[];
+            ignore?: string[];
+            debounceMs?: number;
+            autoTest?: boolean;
+        };
+        ci?: {
+            strategy?: "affected-flows" | string;
+            parallelism?: number;
+        };
+        analysis?: {
+            useLLM?: boolean;
+            llmThreshold?: number;
+        };
+        /**
+         * Optional base URL and API key for managed Observer Engine APIs.
+         * When present, bootstrap and analysis operations will be delegated
+         * to the remote service.
+         */
+        apiBaseUrl?: string;
+        apiKey?: string;
+    };
+    flowGraph?: {
+        endpoint: string;
+        database?: string;
+    };
+    eventBus?: {
+        type: "in-memory" | "redis";
+        redisUrl?: string;
+    };
+}
+interface ChangeAnalysisFile {
+    path: string;
+    status: "added" | "modified" | "deleted" | "renamed";
+}
+interface ChangeAnalysis {
+    baseSha: string;
+    headSha: string;
+    files: ChangeAnalysisFile[];
+}
+interface ImpactedFlow {
+    name: string;
+    confidence: number;
+    riskScore: number;
+    priority?: "critical" | "high" | "medium" | "low";
+}
+/**
+ * Shape aligned with the ANALYSIS_COMPLETE event described in docs/cli_architecture.md.
+ */
+interface ImpactReport {
+    changeId: string;
+    baseSha: string;
+    headSha: string;
+    flows: ImpactedFlow[];
+    changes: ChangeAnalysisFile[];
+    createdAt: number;
+}
+interface BootstrapResult {
+    projectName: string;
+    framework: string;
+    flowsInitialized: number;
+    personasInitialized: number;
+    warnings?: string[];
+}
+interface BootstrapOptions {
+    projectDir: string;
+    projectName: string;
+    framework: string;
+}
+
+interface PerceoEvent<T = any> {
+    id: string;
+    type: string;
+    timestamp: number;
+    source: "observer" | "coordinator" | "analytics" | "analyzer" | "graph";
+    data: T;
+    metadata?: {
+        userId?: string;
+        projectId?: string;
+        environment?: string;
+    };
+}
+interface EventBusLike {
+    publish<T>(event: PerceoEvent<T>): Promise<void> | void;
+}
+interface FlowGraphClientLike {
+    upsertFlows?(flows: unknown[]): Promise<void>;
+}
+interface ObserverEngineDeps {
+    eventBus?: EventBusLike;
+    flowGraph?: FlowGraphClientLike;
+}
+declare class ObserverEngine {
+    private readonly config;
+    private readonly deps;
+    private readonly apiClient;
+    constructor(config: ObserverEngineConfig, deps?: ObserverEngineDeps);
+    /**
+     * Bootstrap flows/personas for the current project.
+     *
+     * Delegates to the managed Observer API when configured, otherwise returns
+     * a fast local no-op result so init remains non-blocking.
+     */
+    bootstrapProject(options: BootstrapOptions): Promise<BootstrapResult>;
+    /**
+     * Analyze changes between two Git refs and return an ImpactReport.
+     *
+     * Uses local Git diff to build a ChangeAnalysis, then delegates to the
+     * managed Observer API when configured. If no API is configured, returns
+     * a minimal, local-only report that still captures the changed files.
+     */
+    analyzeChanges(params: {
+        baseSha: string;
+        headSha: string;
+        projectRoot: string;
+    }): Promise<ImpactReport>;
+    /**
+     * Core entry point for watch-mode integration.
+     *
+     * The CLI is expected to provide a stream of file changes; this method
+     * will wire those into the Observer pipeline and return a disposer to
+     * stop processing. The detailed implementation will be filled in when
+     * watch support is built out.
+     */
+    startWatchCore(_options: {
+        onChange: (change: {
+            path: string;
+            type: "add" | "change" | "unlink";
+        }) => void | Promise<void>;
+    }): Promise<() => Promise<void>>;
+}
+
+interface ObserverApiClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+}
+declare class ObserverApiClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    constructor(options: ObserverApiClientOptions);
+    static fromConfig(config: ObserverEngineConfig): ObserverApiClient | null;
+    bootstrapProject(options: BootstrapOptions): Promise<BootstrapResult>;
+    analyzeChanges(change: ChangeAnalysis): Promise<ImpactReport>;
+    private post;
+}
+
+export { type BootstrapOptions, type BootstrapResult, type ChangeAnalysis, type ChangeAnalysisFile, type EventBusLike, type FlowGraphClientLike, type ImpactReport, type ImpactedFlow, ObserverApiClient, type ObserverApiClientOptions, ObserverEngine, type ObserverEngineConfig, type ObserverEngineDeps, type PerceoEvent };

package/dist/index.js

@@ -0,0 +1,169 @@
+// src/client.ts
+var ObserverApiClient = class _ObserverApiClient {
+  baseUrl;
+  apiKey;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+  }
+  static fromConfig(config) {
+    const baseUrl = config.observer.apiBaseUrl;
+    if (!baseUrl) return null;
+    return new _ObserverApiClient({
+      baseUrl,
+      apiKey: config.observer.apiKey
+    });
+  }
+  async bootstrapProject(options) {
+    const res = await this.post("/observer/bootstrap", options);
+    return res;
+  }
+  async analyzeChanges(change) {
+    const res = await this.post("/observer/analyze", change);
+    return res;
+  }
+  async post(path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(`Observer API request failed (${response.status}): ${text || response.statusText}`);
+    }
+    return await response.json();
+  }
+};
+
+// src/git.ts
+import { exec as _exec } from "child_process";
+import { promisify } from "util";
+var exec = promisify(_exec);
+async function computeChangeAnalysis(projectRoot, baseSha, headSha) {
+  const { stdout } = await exec(`git diff --name-status ${baseSha}...${headSha}`, {
+    cwd: projectRoot
+  });
+  const files = stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => {
+    const [status, filePath] = line.split(/\s+/, 2);
+    return {
+      path: normalizePath(filePath),
+      status: mapStatus(status)
+    };
+  });
+  return {
+    baseSha,
+    headSha,
+    files
+  };
+}
+function mapStatus(raw) {
+  switch (raw) {
+    case "A":
+      return "added";
+    case "D":
+      return "deleted";
+    case "R":
+    case "R100":
+    case "R099":
+      return "renamed";
+    case "M":
+    default:
+      return "modified";
+  }
+}
+function normalizePath(p) {
+  if (!p) return "";
+  return p.split("\\").join("/");
+}
+
+// src/engine.ts
+var ObserverEngine = class {
+  config;
+  deps;
+  apiClient;
+  constructor(config, deps = {}) {
+    this.config = config;
+    this.deps = deps;
+    this.apiClient = ObserverApiClient.fromConfig(config);
+  }
+  /**
+   * Bootstrap flows/personas for the current project.
+   *
+   * Delegates to the managed Observer API when configured, otherwise returns
+   * a fast local no-op result so init remains non-blocking.
+   */
+  async bootstrapProject(options) {
+    if (!this.apiClient) {
+      return {
+        projectName: options.projectName,
+        framework: options.framework,
+        flowsInitialized: 0,
+        personasInitialized: 0,
+        warnings: ["Observer managed API is not configured; skipping remote bootstrap."]
+      };
+    }
+    const result = await this.apiClient.bootstrapProject(options);
+    if (this.deps.flowGraph && Array.isArray(result.flows)) {
+      await this.deps.flowGraph.upsertFlows?.(result.flows);
+    }
+    return result;
+  }
+  /**
+   * Analyze changes between two Git refs and return an ImpactReport.
+   *
+   * Uses local Git diff to build a ChangeAnalysis, then delegates to the
+   * managed Observer API when configured. If no API is configured, returns
+   * a minimal, local-only report that still captures the changed files.
+   */
+  async analyzeChanges(params) {
+    const change = await computeChangeAnalysis(params.projectRoot, params.baseSha, params.headSha);
+    let report;
+    if (this.apiClient) {
+      report = await this.apiClient.analyzeChanges(change);
+    } else {
+      report = {
+        changeId: `${params.baseSha}...${params.headSha}`,
+        baseSha: params.baseSha,
+        headSha: params.headSha,
+        flows: [],
+        changes: change.files,
+        createdAt: Date.now()
+      };
+    }
+    if (this.deps.eventBus) {
+      const event = {
+        id: report.changeId,
+        type: "observer.analysis.complete",
+        timestamp: report.createdAt,
+        source: "observer",
+        data: report
+      };
+      await this.deps.eventBus.publish(event);
+    }
+    return report;
+  }
+  /**
+   * Core entry point for watch-mode integration.
+   *
+   * The CLI is expected to provide a stream of file changes; this method
+   * will wire those into the Observer pipeline and return a disposer to
+   * stop processing. The detailed implementation will be filled in when
+   * watch support is built out.
+   */
+  async startWatchCore(_options) {
+    return async () => {
+    };
+  }
+};
+export {
+  ObserverApiClient,
+  ObserverEngine
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@perceo/observer-engine",
+  "version": "0.1.0",
+  "description": "Observer Engine core used by the Perceo CLI for flow/persona bootstrap and change impact analysis.",
+  "keywords": [
+    "perceo",
+    "observer",
+    "analysis",
+    "flows",
+    "ci"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsup": "^8.0.1",
+    "typescript": "5.9.2",
+    "@repo/typescript-config": "0.1.0"
+  },
+  "peerDependencies": {
+    "@perceo/perceo": "0.x"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "check-types": "tsc --noEmit"
+  }
+}