flowcat 1.3.0 → 1.5.0

package/core/lock.ts

@@ -0,0 +1,31 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import lockfile from "proper-lockfile";
+
+import { LOCK_DIR, LOCK_FILE } from "./constants";
+import { ensureWorkspaceLayout } from "./workspace";
+
+export const withWorkspaceLock = async <T>(
+  workspaceRoot: string,
+  fn: () => Promise<T>,
+): Promise<T> => {
+  await ensureWorkspaceLayout(workspaceRoot);
+  const lockPath = path.join(workspaceRoot, LOCK_DIR, LOCK_FILE);
+  await writeFile(lockPath, "", { flag: "a" });
+  const release = await lockfile.lock(lockPath, {
+    stale: 60_000,
+    retries: {
+      retries: 5,
+      factor: 1.5,
+      minTimeout: 50,
+      maxTimeout: 1_000,
+    },
+  });
+
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+};

package/core/plugin.ts

@@ -0,0 +1,99 @@
+import type { Task } from "./schemas/task";
+import type { TaskAction, TaskStatus } from "./types";
+
+/**
+ * Logger interface for plugins
+ */
+export type PluginLogger = {
+  debug: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+/**
+ * Context provided to all hook handlers
+ */
+export type PluginContext = {
+  /** Root path of the current workspace */
+  workspaceRoot: string;
+  /** Plugin-specific configuration from config.json */
+  config: Record<string, unknown>;
+  /** Logger for plugin output */
+  logger: PluginLogger;
+};
+
+/**
+ * Result returned from a hook handler
+ */
+export type HookResult = {
+  /** Return modified task, or omit to keep original */
+  task?: Task;
+};
+
+/**
+ * Hook event payloads for each lifecycle event
+ */
+export type HookEvents = {
+  "task:created": {
+    task: Task;
+    alias: string;
+  };
+  "task:transitioned": {
+    task: Task;
+    previousStatus: TaskStatus;
+    action: TaskAction;
+  };
+  "task:logged": {
+    task: Task;
+    message: string;
+  };
+  "task:edited": {
+    task: Task;
+    path: string;
+    previousValue: unknown;
+    newValue: unknown;
+  };
+  "pr:attached": {
+    task: Task;
+    prUrl: string;
+  };
+  "pr:refreshed": {
+    task: Task;
+    previousState?: "open" | "closed" | "merged";
+    newState: "open" | "closed" | "merged";
+  };
+};
+
+/**
+ * Hook handler function type
+ */
+export type HookHandler<K extends keyof HookEvents> = (
+  event: HookEvents[K],
+  context: PluginContext,
+) => Promise<HookResult | undefined>;
+
+/**
+ * Plugin definition
+ */
+export type FlowcatPlugin = {
+  /** Unique plugin name (e.g., "llm-pr-analyzer") */
+  name: string;
+
+  /** Semantic version */
+  version: string;
+
+  /** Human-readable description */
+  description?: string;
+
+  /** Hook handlers */
+  hooks?: {
+    [K in keyof HookEvents]?: HookHandler<K>;
+  };
+
+  /** Called once when plugin loads (optional) */
+  onLoad?: (context: PluginContext) => Promise<void>;
+
+  /** Called when plugin unloads (optional) */
+  onUnload?: (context: PluginContext) => Promise<void>;
+};

package/core/pluginErrors.ts

@@ -0,0 +1,26 @@
+export type PluginErrorCode =
+  | "PLUGIN_LOAD_FAILED"
+  | "PLUGIN_INIT_FAILED"
+  | "HOOK_EXECUTION_FAILED"
+  | "HOOK_TIMEOUT"
+  | "INVALID_PLUGIN";
+
+export class PluginError extends Error {
+  code: PluginErrorCode;
+  pluginName?: string;
+  hookName?: string;
+  cause?: Error;
+
+  constructor(
+    code: PluginErrorCode,
+    message: string,
+    options?: { pluginName?: string; hookName?: string; cause?: Error },
+  ) {
+    super(message);
+    this.name = "PluginError";
+    this.code = code;
+    this.pluginName = options?.pluginName;
+    this.hookName = options?.hookName;
+    this.cause = options?.cause;
+  }
+}

package/core/pluginLoader.ts

@@ -0,0 +1,222 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { createJiti } from "jiti";
+
+import {
+  readConfigFile,
+  resolveGlobalConfigPath,
+  resolveWorkspaceConfigPath,
+  type PluginEntry,
+} from "./config";
+import { APP_NAME, PLUGINS_DIR } from "./constants";
+import { PluginError } from "./pluginErrors";
+import type { FlowcatPlugin } from "./plugin";
+
+export type LoadedPlugin = {
+  plugin: FlowcatPlugin;
+  config: Record<string, unknown>;
+  enabled: boolean;
+};
+
+export type PluginLoadError = {
+  path: string;
+  error: Error;
+};
+
+export type PluginLoadResult = {
+  plugins: LoadedPlugin[];
+  errors: PluginLoadError[];
+};
+
+const exists = async (filePath: string): Promise<boolean> => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Resolve the global plugins directory
+ */
+export const resolveGlobalPluginsDirectory = (): string => {
+  const configHome = process.env.XDG_CONFIG_HOME ?? path.join(homedir(), ".config");
+  return path.join(configHome, APP_NAME, PLUGINS_DIR);
+};
+
+/**
+ * Resolve the plugins directory for a workspace
+ */
+export const resolvePluginsDirectory = (
+  workspaceRoot: string,
+  configOverride?: string,
+): string => {
+  if (configOverride) {
+    return path.isAbsolute(configOverride)
+      ? configOverride
+      : path.join(workspaceRoot, configOverride);
+  }
+
+  return path.join(workspaceRoot, PLUGINS_DIR);
+};
+
+/**
+ * Resolve a plugin path to an actual file
+ */
+const resolvePluginPath = async (
+  pluginPath: string,
+  pluginsDir: string,
+): Promise<string | null> => {
+  // Absolute path
+  if (path.isAbsolute(pluginPath)) {
+    if (await exists(pluginPath)) {
+      return pluginPath;
+    }
+    // Try adding extensions
+    for (const ext of ["/index.ts", "/index.js", ".ts", ".js"]) {
+      const withExt = pluginPath + ext;
+      if (await exists(withExt)) {
+        return withExt;
+      }
+    }
+    return null;
+  }
+
+  // Relative path (./plugin or ../plugin)
+  if (pluginPath.startsWith("./") || pluginPath.startsWith("../")) {
+    const resolved = path.resolve(pluginsDir, pluginPath);
+    return resolvePluginPath(resolved, pluginsDir);
+  }
+
+  // Plugin name - look in plugins directory
+  const basePath = path.join(pluginsDir, pluginPath);
+
+  // Try different extensions in order
+  const candidates = [
+    path.join(basePath, "index.ts"),
+    `${basePath}.ts`,
+    path.join(basePath, "index.js"),
+    `${basePath}.js`,
+  ];
+
+  for (const candidate of candidates) {
+    if (await exists(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Validate that an object is a valid FlowcatPlugin
+ */
+const validatePlugin = (obj: unknown, pluginPath: string): FlowcatPlugin => {
+  if (!obj || typeof obj !== "object") {
+    throw new PluginError(
+      "INVALID_PLUGIN",
+      `Plugin at ${pluginPath} must export a default FlowcatPlugin object`,
+    );
+  }
+
+  const plugin = obj as Record<string, unknown>;
+
+  if (!plugin.name || typeof plugin.name !== "string") {
+    throw new PluginError("INVALID_PLUGIN", `Plugin at ${pluginPath} must have a name`);
+  }
+
+  if (!plugin.version || typeof plugin.version !== "string") {
+    throw new PluginError("INVALID_PLUGIN", `Plugin at ${pluginPath} must have a version`);
+  }
+
+  return plugin as unknown as FlowcatPlugin;
+};
+
+/**
+ * Load a single plugin from a path using jiti
+ */
+export const loadPluginFromPath = async (
+  pluginPath: string,
+  pluginsDir: string,
+): Promise<FlowcatPlugin> => {
+  const resolvedPath = await resolvePluginPath(pluginPath, pluginsDir);
+
+  if (!resolvedPath) {
+    throw new PluginError(
+      "PLUGIN_LOAD_FAILED",
+      `Could not find plugin at ${pluginPath}`,
+    );
+  }
+
+  try {
+    const jiti = createJiti(import.meta.url);
+    const module = await jiti.import(resolvedPath);
+    const defaultExport = (module as { default?: unknown }).default;
+
+    if (!defaultExport) {
+      throw new PluginError(
+        "INVALID_PLUGIN",
+        `Plugin at ${resolvedPath} must have a default export`,
+      );
+    }
+
+    return validatePlugin(defaultExport, resolvedPath);
+  } catch (error) {
+    if (error instanceof PluginError) {
+      throw error;
+    }
+
+    throw new PluginError(
+      "PLUGIN_LOAD_FAILED",
+      `Failed to load plugin at ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error instanceof Error ? error : undefined },
+    );
+  }
+};
+
+/**
+ * Load all configured plugins for a workspace
+ */
+export const loadPlugins = async (workspaceRoot: string): Promise<PluginLoadResult> => {
+  const workspaceConfig = await readConfigFile(resolveWorkspaceConfigPath(workspaceRoot));
+  const globalConfig = await readConfigFile(resolveGlobalConfigPath());
+
+  // Get plugin entries (workspace config takes precedence)
+  const entries: PluginEntry[] =
+    workspaceConfig.plugins?.entries ?? globalConfig.plugins?.entries ?? [];
+
+  // Get plugins directory
+  const pluginsDir = resolvePluginsDirectory(
+    workspaceRoot,
+    workspaceConfig.plugins?.directory ?? globalConfig.plugins?.directory,
+  );
+
+  const plugins: LoadedPlugin[] = [];
+  const errors: PluginLoadError[] = [];
+
+  for (const entry of entries) {
+    // Skip disabled plugins
+    if (entry.enabled === false) {
+      continue;
+    }
+
+    try {
+      const plugin = await loadPluginFromPath(entry.path, pluginsDir);
+      plugins.push({
+        plugin,
+        config: entry.config ?? {},
+        enabled: true,
+      });
+    } catch (error) {
+      errors.push({
+        path: entry.path,
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+    }
+  }
+
+  return { plugins, errors };
+};

package/core/pluginManager.ts

@@ -0,0 +1,75 @@
+import { readConfigFile, resolveGlobalConfigPath, resolveWorkspaceConfigPath } from "./config";
+import type { HookEvents, HookResult } from "./plugin";
+import { loadPlugins } from "./pluginLoader";
+import { PluginRunner } from "./pluginRunner";
+
+// Cache of plugin runners per workspace
+const runners = new Map<string, PluginRunner>();
+
+/**
+ * Get or create the plugin runner for a workspace
+ * Lazy initialization - plugins are loaded on first access
+ */
+export const getPluginRunner = async (workspaceRoot: string): Promise<PluginRunner> => {
+  const existing = runners.get(workspaceRoot);
+  if (existing) {
+    return existing;
+  }
+
+  const { plugins, errors } = await loadPlugins(workspaceRoot);
+
+  // Log loading errors
+  for (const { path, error } of errors) {
+    console.warn(`[plugins] Failed to load ${path}: ${error.message}`);
+  }
+
+  const workspaceConfig = await readConfigFile(resolveWorkspaceConfigPath(workspaceRoot));
+  const globalConfig = await readConfigFile(resolveGlobalConfigPath());
+  const settings = workspaceConfig.plugins?.settings ?? globalConfig.plugins?.settings;
+
+  const runner = new PluginRunner({
+    plugins,
+    workspaceRoot,
+    settings,
+  });
+
+  await runner.initialize();
+
+  runners.set(workspaceRoot, runner);
+
+  return runner;
+};
+
+/**
+ * Emit a hook event to all plugins in a workspace
+ * Convenience function that handles runner initialization
+ */
+export const emitHook = async <K extends keyof HookEvents>(
+  workspaceRoot: string,
+  hookName: K,
+  event: HookEvents[K],
+): Promise<HookResult> => {
+  const runner = await getPluginRunner(workspaceRoot);
+  return runner.emit(hookName, event);
+};
+
+/**
+ * Clear the plugin runner cache for a workspace
+ * Useful for testing or when plugins config changes
+ */
+export const clearPluginRunner = async (workspaceRoot: string): Promise<void> => {
+  const runner = runners.get(workspaceRoot);
+  if (runner) {
+    await runner.shutdown();
+    runners.delete(workspaceRoot);
+  }
+};
+
+/**
+ * Clear all plugin runner caches
+ */
+export const clearAllPluginRunners = async (): Promise<void> => {
+  for (const [workspaceRoot] of runners) {
+    await clearPluginRunner(workspaceRoot);
+  }
+};

package/core/pluginRunner.ts

@@ -0,0 +1,217 @@
+import type { PluginSettings } from "./config";
+import type { HookEvents, HookResult, PluginContext, PluginLogger } from "./plugin";
+import { PluginError } from "./pluginErrors";
+import type { LoadedPlugin } from "./pluginLoader";
+
+export type PluginRunnerOptions = {
+  plugins: LoadedPlugin[];
+  workspaceRoot: string;
+  settings?: PluginSettings;
+};
+
+/**
+ * Expand environment variables in config values
+ * Supports ${VAR_NAME} syntax
+ */
+const expandEnvVars = (value: unknown): unknown => {
+  if (typeof value === "string") {
+    return value.replace(/\$\{(\w+)\}/g, (_, name: string) => process.env[name] ?? "");
+  }
+  if (Array.isArray(value)) {
+    return value.map(expandEnvVars);
+  }
+  if (value && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = expandEnvVars(v);
+    }
+    return result;
+  }
+  return value;
+};
+
+/**
+ * Create a logger for a plugin
+ */
+const createPluginLogger = (
+  pluginName: string,
+  logLevel: PluginSettings["logLevel"] = "info",
+): PluginLogger => {
+  const levels = ["debug", "info", "warn", "error"] as const;
+  const minLevel = levels.indexOf(logLevel);
+
+  const shouldLog = (level: (typeof levels)[number]): boolean => {
+    return levels.indexOf(level) >= minLevel;
+  };
+
+  const format = (level: string, message: string): string => {
+    return `[plugin:${pluginName}] [${level.toUpperCase()}] ${message}`;
+  };
+
+  return {
+    debug: (message) => {
+      if (shouldLog("debug")) {
+        console.debug(format("debug", message));
+      }
+    },
+    info: (message) => {
+      if (shouldLog("info")) {
+        console.info(format("info", message));
+      }
+    },
+    warn: (message) => {
+      if (shouldLog("warn")) {
+        console.warn(format("warn", message));
+      }
+    },
+    error: (message) => {
+      if (shouldLog("error")) {
+        console.error(format("error", message));
+      }
+    },
+  };
+};
+
+/**
+ * Run a function with a timeout
+ */
+const runWithTimeout = async <T>(
+  fn: () => Promise<T>,
+  timeoutMs: number,
+  description: string,
+): Promise<T> => {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new PluginError("HOOK_TIMEOUT", `${description} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    fn()
+      .then((result) => {
+        clearTimeout(timer);
+        resolve(result);
+      })
+      .catch((error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+  });
+};
+
+export class PluginRunner {
+  private plugins: LoadedPlugin[];
+  private workspaceRoot: string;
+  private settings: PluginSettings;
+  private initialized = false;
+
+  constructor(options: PluginRunnerOptions) {
+    this.plugins = options.plugins;
+    this.workspaceRoot = options.workspaceRoot;
+    this.settings = options.settings ?? {};
+  }
+
+  /**
+   * Initialize all plugins (call onLoad)
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    for (const { plugin, config } of this.plugins) {
+      if (plugin.onLoad) {
+        const context = this.createContext(plugin.name, config);
+        try {
+          await plugin.onLoad(context);
+        } catch (error) {
+          context.logger.error(`Failed to initialize: ${error}`);
+          if (this.settings.continueOnError === false) {
+            throw new PluginError(
+              "PLUGIN_INIT_FAILED",
+              `Plugin ${plugin.name} failed to initialize: ${error}`,
+              { pluginName: plugin.name, cause: error instanceof Error ? error : undefined },
+            );
+          }
+        }
+      }
+    }
+
+    this.initialized = true;
+  }
+
+  /**
+   * Emit a hook event to all plugins
+   * Returns the final modified task (if any plugin modified it)
+   */
+  async emit<K extends keyof HookEvents>(hookName: K, event: HookEvents[K]): Promise<HookResult> {
+    const timeout = this.settings.hookTimeout ?? 30000;
+    let currentEvent = { ...event };
+    let finalResult: HookResult = {};
+
+    // Run plugins sequentially in config order
+    for (const { plugin, config } of this.plugins) {
+      const handler = plugin.hooks?.[hookName];
+      if (!handler) {
+        continue;
+      }
+
+      const context = this.createContext(plugin.name, config);
+
+      try {
+        const result = await runWithTimeout(
+          () => handler(currentEvent, context),
+          timeout,
+          `${plugin.name}:${hookName}`,
+        );
+
+        // If plugin returned a modified task, use it for subsequent hooks
+        if (result?.task) {
+          currentEvent = { ...currentEvent, task: result.task };
+          finalResult = { task: result.task };
+        }
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        context.logger.error(`Hook ${hookName} failed: ${errorMessage}`);
+
+        if (this.settings.continueOnError === false) {
+          throw new PluginError(
+            "HOOK_EXECUTION_FAILED",
+            `Plugin ${plugin.name} hook ${hookName} failed: ${errorMessage}`,
+            {
+              pluginName: plugin.name,
+              hookName,
+              cause: error instanceof Error ? error : undefined,
+            },
+          );
+        }
+      }
+    }
+
+    return finalResult;
+  }
+
+  /**
+   * Shutdown all plugins (call onUnload)
+   */
+  async shutdown(): Promise<void> {
+    for (const { plugin, config } of this.plugins) {
+      if (plugin.onUnload) {
+        const context = this.createContext(plugin.name, config);
+        try {
+          await plugin.onUnload(context);
+        } catch (error) {
+          context.logger.error(`Failed to shutdown: ${error}`);
+          // Always continue during shutdown, even if continueOnError is false
+        }
+      }
+    }
+  }
+
+  private createContext(pluginName: string, config: Record<string, unknown>): PluginContext {
+    return {
+      workspaceRoot: this.workspaceRoot,
+      config: expandEnvVars(config) as Record<string, unknown>,
+      logger: createPluginLogger(pluginName, this.settings.logLevel),
+    };
+  }
+}