claude-code-swarm 0.3.4 → 0.3.6

package/references/opentasks/src/graph/expansion.ts

@@ -0,0 +1,364 @@
+/**
+ * Query Expansion for OpenTasks (Phase 3)
+ *
+ * Enables queries that span multiple OpenTasks locations.
+ */
+
+import type { StoredNode, StoredEdge } from '../schema/storage.js';
+import type { Storage } from '../storage/interface.js';
+import type { Connection } from '../core/connections.js';
+import type { ProviderNode } from '../providers/types.js';
+import type { LocationProvider } from '../providers/location.js';
+import type { NodeResolver } from './query.js';
+import { isOpentasksUri, parseOpentasksUri } from '../core/uri.js';
+
+/**
+ * Query expansion modes
+ */
+export type ExpansionMode =
+  | 'none' // Only current location (default)
+  | 'follow-refs' // Follow outbound edge references via providers
+  | 'connections' // Query all declared connections
+  | 'all'; // follow-refs + connections
+
+/**
+ * Expanded query result
+ */
+export interface ExpandedResult {
+  /** Results from current location */
+  local: StoredNode[];
+  /** Results from connected locations, keyed by hash */
+  connected: Record<string, ProviderNode[]>;
+  /** Edges that span across locations */
+  crossLocationEdges: StoredEdge[];
+  /** All locations queried */
+  queriedLocations: string[];
+  /** Locations that were unreachable */
+  unreachableLocations: string[];
+  /** Completeness indicator */
+  completeness: 'full' | 'partial';
+}
+
+/**
+ * Options for expanded queries
+ */
+export interface ExpansionOptions {
+  /** Expansion mode */
+  expand?: ExpansionMode;
+  /** Maximum number of locations to query (safety limit) */
+  maxLocations?: number;
+}
+
+/**
+ * Query expander for cross-location queries
+ */
+export interface QueryExpander {
+  /**
+   * Execute an expanded ready query
+   */
+  expandedReady(options?: ExpansionOptions): Promise<ExpandedResult>;
+
+  /**
+   * Execute an expanded node query
+   */
+  expandedQuery(
+    filter: { type?: string; status?: string },
+    options?: ExpansionOptions,
+  ): Promise<ExpandedResult>;
+}
+
+/**
+ * Query multiple providers in parallel using Promise.allSettled
+ */
+async function queryProvidersParallel(
+  providers: Map<string, LocationProvider>,
+  queryFn: (provider: LocationProvider) => Promise<ProviderNode[]>,
+  maxLocations: number,
+): Promise<{
+  connected: Record<string, ProviderNode[]>;
+  queriedLocations: string[];
+  unreachableLocations: string[];
+}> {
+  const entries = [...providers.entries()].slice(0, maxLocations);
+
+  const results = await Promise.allSettled(
+    entries.map(async ([hash, provider]) => {
+      const nodes = await queryFn(provider);
+      return { hash, nodes };
+    }),
+  );
+
+  const connected: Record<string, ProviderNode[]> = {};
+  const queriedLocations: string[] = [];
+  const unreachableLocations: string[] = [];
+
+  for (const result of results) {
+    if (result.status === 'fulfilled') {
+      connected[result.value.hash] = result.value.nodes;
+      queriedLocations.push(result.value.hash);
+    } else {
+      // Find the hash for this failed entry by index
+      const idx = results.indexOf(result);
+      unreachableLocations.push(entries[idx][0]);
+    }
+  }
+
+  return { connected, queriedLocations, unreachableLocations };
+}
+
+/**
+ * Identify which provider hashes are referenced by local edges
+ * via opentasks:// URIs in from_id or to_id fields.
+ */
+function getReferencedLocationHashes(edges: StoredEdge[], localHash: string): Set<string> {
+  const hashes = new Set<string>();
+
+  for (const edge of edges) {
+    for (const field of [edge.from_id, edge.to_id]) {
+      if (isOpentasksUri(field)) {
+        const parsed = parseOpentasksUri(field);
+        if (parsed?.locationHash && parsed.locationHash !== localHash) {
+          hashes.add(parsed.locationHash);
+        }
+      }
+    }
+  }
+
+  return hashes;
+}
+
+/**
+ * Find edges that reference nodes in other locations
+ */
+function findCrossLocationEdges(
+  edges: StoredEdge[],
+  localHash: string,
+  connectedHashes: Set<string>,
+): StoredEdge[] {
+  return edges.filter((edge) => {
+    for (const field of [edge.from_id, edge.to_id]) {
+      if (isOpentasksUri(field)) {
+        const parsed = parseOpentasksUri(field);
+        if (parsed?.locationHash && parsed.locationHash !== localHash) {
+          return true;
+        }
+      }
+    }
+    // Also check if from_id or to_id appears as a hash-prefixed reference
+    return false;
+  });
+}
+
+/**
+ * Statuses considered "closed" for cross-location blocker resolution
+ */
+const CLOSED_STATUSES = new Set(['closed', 'done', 'resolved', 'completed', 'cancelled']);
+
+/**
+ * Pattern for external URIs (opentasks:// or global://)
+ */
+const EXTERNAL_URI_PATTERN = /^(opentasks|global):\/\//;
+
+/**
+ * Create a query expander
+ *
+ * @param storage - Local storage
+ * @param locationHash - Current location hash
+ * @param locationProviders - Map of location hash → Provider
+ * @param nodeResolver - Optional resolver for cross-provider blocker resolution
+ */
+export function createQueryExpander(
+  storage: Storage,
+  locationHash: string,
+  locationProviders: Map<string, LocationProvider>,
+  nodeResolver?: NodeResolver,
+): QueryExpander {
+  /**
+   * Get all local edges for cross-location analysis
+   */
+  async function getLocalEdges(localNodeIds: string[]): Promise<StoredEdge[]> {
+    const allEdges: StoredEdge[] = [];
+    for (const nodeId of localNodeIds) {
+      const edges = await storage.getEdgesFrom(nodeId);
+      allEdges.push(...edges);
+    }
+    return allEdges;
+  }
+
+  /**
+   * Select providers based on expansion mode
+   */
+  function selectProviders(
+    mode: ExpansionMode,
+    referencedHashes?: Set<string>,
+  ): Map<string, LocationProvider> {
+    if (mode === 'follow-refs' && referencedHashes) {
+      // Only query locations referenced by local edges
+      const selected = new Map<string, LocationProvider>();
+      for (const hash of referencedHashes) {
+        const provider = locationProviders.get(hash);
+        if (provider) {
+          selected.set(hash, provider);
+        }
+      }
+      return selected;
+    }
+
+    if (mode === 'connections' || mode === 'all') {
+      return locationProviders;
+    }
+
+    return new Map();
+  }
+
+  return {
+    async expandedReady(options?: ExpansionOptions): Promise<ExpandedResult> {
+      const mode = options?.expand ?? 'none';
+      const maxLocations = options?.maxLocations ?? 10;
+
+      // Always query local
+      let local = await storage.getReady();
+
+      // Post-filter: exclude tasks with active cross-location blockers
+      if (nodeResolver && local.length > 0) {
+        const filtered: StoredNode[] = [];
+        for (const task of local) {
+          const blockerEdges = await storage.getEdgesTo(task.id, 'blocks');
+          let hasActiveCrossLocationBlocker = false;
+
+          for (const edge of blockerEdges) {
+            if (EXTERNAL_URI_PATTERN.test(edge.from_id)) {
+              const blocker = await nodeResolver(edge.from_id);
+              if (blocker && !blocker.archived && !CLOSED_STATUSES.has(blocker.status ?? '')) {
+                hasActiveCrossLocationBlocker = true;
+                break;
+              }
+            }
+          }
+
+          if (!hasActiveCrossLocationBlocker) {
+            filtered.push(task);
+          }
+        }
+        local = filtered;
+      }
+
+      if (mode === 'none') {
+        return {
+          local,
+          connected: {},
+          crossLocationEdges: [],
+          queriedLocations: [locationHash],
+          unreachableLocations: [],
+          completeness: 'full',
+        };
+      }
+
+      // For follow-refs, analyze local edges to find referenced locations
+      let referencedHashes: Set<string> | undefined;
+      let localEdges: StoredEdge[] = [];
+      if (mode === 'follow-refs' || mode === 'all') {
+        localEdges = await getLocalEdges(local.map((n) => n.id));
+        referencedHashes = getReferencedLocationHashes(localEdges, locationHash);
+      }
+
+      // Select providers based on mode
+      const providers = selectProviders(mode, referencedHashes);
+
+      // For 'all' mode, include all connected providers too
+      if (mode === 'all') {
+        for (const [hash, provider] of locationProviders.entries()) {
+          providers.set(hash, provider);
+        }
+      }
+
+      // Query providers in parallel
+      const { connected, queriedLocations, unreachableLocations } = await queryProvidersParallel(
+        providers,
+        (provider) => provider.ready(),
+        maxLocations,
+      );
+
+      // Identify cross-location edges
+      if (localEdges.length === 0 && mode === 'connections') {
+        localEdges = await getLocalEdges(local.map((n) => n.id));
+      }
+      const connectedHashes = new Set(queriedLocations);
+      const crossLocationEdges = findCrossLocationEdges(localEdges, locationHash, connectedHashes);
+
+      return {
+        local,
+        connected,
+        crossLocationEdges,
+        queriedLocations: [locationHash, ...queriedLocations],
+        unreachableLocations,
+        completeness: unreachableLocations.length === 0 ? 'full' : 'partial',
+      };
+    },
+
+    async expandedQuery(
+      filter: { type?: string; status?: string },
+      options?: ExpansionOptions,
+    ): Promise<ExpandedResult> {
+      const mode = options?.expand ?? 'none';
+      const maxLocations = options?.maxLocations ?? 10;
+
+      const local = await storage.queryNodes({
+        type: filter.type,
+        status: filter.status,
+      });
+
+      if (mode === 'none') {
+        return {
+          local,
+          connected: {},
+          crossLocationEdges: [],
+          queriedLocations: [locationHash],
+          unreachableLocations: [],
+          completeness: 'full',
+        };
+      }
+
+      // For follow-refs, analyze local edges to find referenced locations
+      let referencedHashes: Set<string> | undefined;
+      let localEdges: StoredEdge[] = [];
+      if (mode === 'follow-refs' || mode === 'all') {
+        localEdges = await getLocalEdges(local.map((n) => n.id));
+        referencedHashes = getReferencedLocationHashes(localEdges, locationHash);
+      }
+
+      // Select providers based on mode
+      const providers = selectProviders(mode, referencedHashes);
+
+      // For 'all' mode, include all connected providers too
+      if (mode === 'all') {
+        for (const [hash, provider] of locationProviders.entries()) {
+          providers.set(hash, provider);
+        }
+      }
+
+      // Query providers in parallel
+      const { connected, queriedLocations, unreachableLocations } = await queryProvidersParallel(
+        providers,
+        (provider) => provider.list(filter),
+        maxLocations,
+      );
+
+      // Identify cross-location edges
+      if (localEdges.length === 0 && mode === 'connections') {
+        localEdges = await getLocalEdges(local.map((n) => n.id));
+      }
+      const connectedHashes = new Set(queriedLocations);
+      const crossLocationEdges = findCrossLocationEdges(localEdges, locationHash, connectedHashes);
+
+      return {
+        local,
+        connected,
+        crossLocationEdges,
+        queriedLocations: [locationHash, ...queriedLocations],
+        unreachableLocations,
+        completeness: unreachableLocations.length === 0 ? 'full' : 'partial',
+      };
+    },
+  };
+}

package/references/opentasks/src/graph/git-graph-syncer.ts

@@ -0,0 +1,321 @@
+/**
+ * Git Graph Syncer
+ *
+ * Handles automated git operations for graph.jsonl to enable
+ * cross-machine replication of the OpenTasks graph.
+ *
+ * Supports manual sync (`opentasks sync`) and optional auto-commit/push.
+ * Delegates conflict resolution to the JSONL merge driver in
+ * `src/core/merge-driver.ts`.
+ */
+
+import { execSync } from 'node:child_process';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { installMergeDriver } from '../core/merge-driver.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface GitGraphSyncerConfig {
+  /** Path to the .opentasks/ directory */
+  opentasksPath: string;
+
+  /** Git remote name (null = no push/pull) */
+  remote?: string | null;
+
+  /** Commit after flush (default: false) */
+  autoCommit?: boolean;
+
+  /** Push after commit (default: false) */
+  autoPush?: boolean;
+
+  /** Minimum interval between pushes in ms (default: 60000) */
+  pushDebounceMs?: number;
+
+  /** Git command timeout in ms (default: 30000) */
+  timeout?: number;
+}
+
+export interface CommitResult {
+  /** Whether a commit was created */
+  committed: boolean;
+
+  /** Commit hash if created */
+  hash?: string;
+}
+
+export interface PushResult {
+  /** Whether push succeeded */
+  pushed: boolean;
+
+  /** Error message if push failed */
+  error?: string;
+}
+
+export interface PullResult {
+  /** Whether pull succeeded */
+  pulled: boolean;
+
+  /** Whether new changes were received */
+  hasChanges: boolean;
+
+  /** Error message if pull failed */
+  error?: string;
+}
+
+export interface SyncCycleResult {
+  commit: CommitResult;
+  pull: PullResult;
+  push: PushResult;
+}
+
+export interface GitGraphSyncer {
+  /** Commit graph.jsonl if it has uncommitted changes */
+  commitIfDirty(): Promise<CommitResult>;
+
+  /** Push to remote */
+  push(): Promise<PushResult>;
+
+  /** Pull from remote */
+  pull(): Promise<PullResult>;
+
+  /** Full sync cycle: commit + pull + push */
+  sync(): Promise<SyncCycleResult>;
+
+  /** Install the JSONL merge driver for this repo */
+  installMergeDriver(): void;
+
+  /** Start periodic auto-sync timer */
+  startAutoSync(): void;
+
+  /** Stop periodic auto-sync timer */
+  stopAutoSync(): void;
+
+  /** Whether auto-sync is running */
+  isAutoSyncRunning(): boolean;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Run a git command in the repo containing the .opentasks directory.
+ */
+function git(
+  repoPath: string,
+  args: string,
+  options?: { allowFailure?: boolean; timeout?: number },
+): string {
+  const timeout = options?.timeout ?? 30000;
+  try {
+    return execSync(`git -C "${repoPath}" ${args}`, {
+      encoding: 'utf-8',
+      timeout,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch (error) {
+    if (options?.allowFailure) return '';
+    throw error;
+  }
+}
+
+/**
+ * Find the git working tree root for a given .opentasks path.
+ * The .opentasks dir may be inside a repo, or the repo root itself.
+ */
+function findRepoRoot(opentasksPath: string, timeout: number): string | null {
+  try {
+    return git(opentasksPath, 'rev-parse --show-toplevel', { timeout });
+  } catch {
+    // Not inside a git repo
+    return null;
+  }
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Create a git graph syncer for the given .opentasks directory.
+ */
+export function createGitGraphSyncer(config: GitGraphSyncerConfig): GitGraphSyncer {
+  const {
+    opentasksPath,
+    remote = null,
+    autoCommit = false,
+    autoPush = false,
+    pushDebounceMs = 60000,
+    timeout = 30000,
+  } = config;
+
+  let autoSyncInterval: ReturnType<typeof setInterval> | null = null;
+  let isSyncing = false;
+  let lastPushTime = 0;
+
+  const graphFile = path.join(opentasksPath, 'graph.jsonl');
+
+  // Resolve the repo root once
+  const repoRoot = findRepoRoot(opentasksPath, timeout);
+
+  /**
+   * Get the relative path of graph.jsonl from the repo root
+   */
+  function getRelativeGraphPath(): string {
+    if (!repoRoot) return 'graph.jsonl';
+    return path.relative(repoRoot, graphFile);
+  }
+
+  return {
+    async commitIfDirty(): Promise<CommitResult> {
+      if (!repoRoot) {
+        return { committed: false };
+      }
+
+      // Check if graph.jsonl has changes
+      const status = git(repoRoot, `status --porcelain -- "${getRelativeGraphPath()}"`, {
+        allowFailure: true,
+        timeout,
+      });
+
+      if (!status.trim()) {
+        return { committed: false };
+      }
+
+      // Stage and commit
+      git(repoRoot, `add -- "${getRelativeGraphPath()}"`, { timeout });
+
+      const timestamp = new Date().toISOString();
+      const message = `opentasks: sync graph ${timestamp}`;
+      git(repoRoot, `commit -m "${message}" -- "${getRelativeGraphPath()}"`, { timeout });
+
+      // Get the commit hash
+      const hash = git(repoRoot, 'rev-parse HEAD', { allowFailure: true, timeout });
+
+      return { committed: true, hash: hash || undefined };
+    },
+
+    async push(): Promise<PushResult> {
+      if (!repoRoot || !remote) {
+        return { pushed: false, error: remote ? 'Not a git repository' : 'No remote configured' };
+      }
+
+      try {
+        // Get current branch
+        const branch = git(repoRoot, 'rev-parse --abbrev-ref HEAD', { timeout });
+        if (!branch) {
+          return { pushed: false, error: 'Could not determine current branch' };
+        }
+
+        try {
+          git(repoRoot, `push ${remote} ${branch}`, { timeout });
+        } catch {
+          // Push failed — try fetch + rebase + retry
+          try {
+            git(repoRoot, `fetch ${remote} ${branch}`, { timeout });
+            git(repoRoot, `rebase ${remote}/${branch}`, { timeout });
+            git(repoRoot, `push ${remote} ${branch}`, { timeout });
+          } catch (retryError) {
+            // Abort rebase if it's in progress
+            git(repoRoot, 'rebase --abort', { allowFailure: true, timeout });
+            return {
+              pushed: false,
+              error: `Push failed after rebase: ${(retryError as Error).message}`,
+            };
+          }
+        }
+
+        lastPushTime = Date.now();
+        return { pushed: true };
+      } catch (error) {
+        return { pushed: false, error: (error as Error).message };
+      }
+    },
+
+    async pull(): Promise<PullResult> {
+      if (!repoRoot || !remote) {
+        return {
+          pulled: false,
+          hasChanges: false,
+          error: remote ? 'Not a git repository' : 'No remote configured',
+        };
+      }
+
+      try {
+        const branch = git(repoRoot, 'rev-parse --abbrev-ref HEAD', { timeout });
+        if (!branch) {
+          return { pulled: false, hasChanges: false, error: 'Could not determine current branch' };
+        }
+
+        // Record current HEAD before pull
+        const headBefore = git(repoRoot, 'rev-parse HEAD', { allowFailure: true, timeout });
+
+        git(repoRoot, `pull --no-edit ${remote} ${branch}`, { timeout });
+
+        // Check if HEAD changed
+        const headAfter = git(repoRoot, 'rev-parse HEAD', { allowFailure: true, timeout });
+        const hasChanges = headBefore !== headAfter;
+
+        return { pulled: true, hasChanges };
+      } catch (error) {
+        return { pulled: false, hasChanges: false, error: (error as Error).message };
+      }
+    },
+
+    async sync(): Promise<SyncCycleResult> {
+      const commit = await this.commitIfDirty();
+      const pull = await this.pull();
+      const push = await this.push();
+      return { commit, pull, push };
+    },
+
+    installMergeDriver(): void {
+      if (!repoRoot) return;
+
+      // Check if graph.jsonl exists before installing
+      if (!fs.existsSync(graphFile)) return;
+
+      installMergeDriver(opentasksPath);
+    },
+
+    startAutoSync(): void {
+      if (autoSyncInterval) return;
+      if (!autoCommit && !autoPush) return;
+
+      const interval = Math.max(pushDebounceMs, 10000); // minimum 10s
+
+      autoSyncInterval = setInterval(async () => {
+        if (isSyncing) return;
+        isSyncing = true;
+
+        try {
+          if (autoCommit) {
+            await this.commitIfDirty();
+          }
+
+          if (autoPush && remote && Date.now() - lastPushTime >= pushDebounceMs) {
+            await this.push();
+          }
+        } catch {
+          // Auto-sync should be resilient — don't crash
+        } finally {
+          isSyncing = false;
+        }
+      }, interval);
+    },
+
+    stopAutoSync(): void {
+      if (autoSyncInterval) {
+        clearInterval(autoSyncInterval);
+        autoSyncInterval = null;
+      }
+    },
+
+    isAutoSyncRunning(): boolean {
+      return autoSyncInterval !== null;
+    },
+  };
+}