trellis 1.0.7 → 2.0.5

package/src/vcs/types.ts

@@ -0,0 +1,213 @@
+/**
+ * TrellisVCS Type Definitions
+ *
+ * VCS-specific operation kinds, payloads, and entity types
+ * that extend the trellis-core kernel primitives.
+ */
+
+import type { KernelOp } from '../core/persist/backend.js';
+
+// ---------------------------------------------------------------------------
+// VCS Operation Kinds
+// ---------------------------------------------------------------------------
+
+export type VcsOpKind =
+  // Tier 0: File-level operations
+  | 'vcs:fileAdd'
+  | 'vcs:fileModify'
+  | 'vcs:fileDelete'
+  | 'vcs:fileRename'
+  // Tier 1: Structural operations
+  | 'vcs:dirAdd'
+  | 'vcs:dirDelete'
+  // VCS control operations
+  | 'vcs:branchCreate'
+  | 'vcs:branchDelete'
+  | 'vcs:branchAdvance'
+  | 'vcs:milestoneCreate'
+  | 'vcs:checkpointCreate'
+  | 'vcs:merge'
+  // Tier 2: AST-level semantic patches (future)
+  | 'vcs:symbolRename'
+  | 'vcs:symbolMove'
+  | 'vcs:symbolExtract'
+  | 'vcs:signatureChange'
+  // Issue tracking
+  | 'vcs:issueCreate'
+  | 'vcs:issueUpdate'
+  | 'vcs:issueStart'
+  | 'vcs:issuePause'
+  | 'vcs:issueResume'
+  | 'vcs:issueClose'
+  | 'vcs:issueReopen'
+  | 'vcs:criterionAdd'
+  | 'vcs:criterionUpdate'
+  // Issue blocking
+  | 'vcs:issueBlock'
+  | 'vcs:issueUnblock'
+  // Decision traces
+  | 'vcs:decisionRecord';
+
+// ---------------------------------------------------------------------------
+// VCS Operation Payload
+// ---------------------------------------------------------------------------
+
+export interface VcsPayload {
+  // File operations
+  filePath?: string;
+  oldFilePath?: string;
+  contentHash?: string;
+  oldContentHash?: string;
+  size?: number;
+  language?: string;
+
+  // Branch operations
+  branchName?: string;
+  targetOpHash?: string;
+  sourceBranch?: string;
+  baseBranch?: string;
+
+  // Milestone operations
+  milestoneId?: string;
+  message?: string;
+  fromOpHash?: string;
+  toOpHash?: string;
+
+  // Checkpoint operations
+  trigger?: 'green-build' | 'interval' | 'op-count' | 'manual';
+
+  // Signature
+  signature?: string;
+  signedBy?: string;
+
+  // Issue tracking
+  issueId?: string;
+  issueTitle?: string;
+  issueStatus?: 'backlog' | 'queue' | 'in_progress' | 'paused' | 'closed';
+  issuePriority?: 'critical' | 'high' | 'medium' | 'low';
+  issueLabels?: string[];
+  parentIssueId?: string;
+  issueDescription?: string;
+  issueAssignee?: string;
+  pauseNote?: string;
+  blockedByIssueId?: string;
+
+  // Decision traces
+  decisionId?: string;
+  decisionContext?: string;
+  decisionRationale?: string;
+  decisionAlternatives?: string;
+  decisionToolName?: string;
+  decisionToolInput?: string;
+  decisionToolOutput?: string;
+
+  // Acceptance criteria
+  criterionId?: string;
+  criterionDescription?: string;
+  criterionCommand?: string;
+  criterionStatus?: 'pending' | 'passed' | 'failed';
+  criterionOutput?: string;
+}
+
+/**
+ * A VcsOp mirrors KernelOp but widens `kind` to accept VCS-specific strings.
+ * We don't extend KernelOp directly because the kernel types `kind` as a
+ * narrow union; our VCS kinds are a superset.
+ */
+export interface VcsOp {
+  hash: string;
+  kind: VcsOpKind | string;
+  timestamp: string;
+  agentId: string;
+  previousHash?: string;
+  facts?: import('../core/store/eav-store.js').Fact[];
+  links?: import('../core/store/eav-store.js').Link[];
+  vcs?: VcsPayload;
+}
+
+// ---------------------------------------------------------------------------
+// File Change Events (from watcher)
+// ---------------------------------------------------------------------------
+
+export interface FileChangeEvent {
+  type: 'add' | 'modify' | 'delete' | 'rename';
+  path: string;
+  oldPath?: string;
+  contentHash?: string;
+  oldContentHash?: string;
+  size?: number;
+  timestamp: string;
+}
+
+// ---------------------------------------------------------------------------
+// Entity ID Helpers
+// ---------------------------------------------------------------------------
+
+export function fileEntityId(path: string): string {
+  return `file:${path}`;
+}
+
+export function dirEntityId(path: string): string {
+  return `dir:${path}`;
+}
+
+export function branchEntityId(name: string): string {
+  return `branch:${name}`;
+}
+
+export function milestoneEntityId(hash: string): string {
+  return `milestone:${hash}`;
+}
+
+export function checkpointEntityId(hash: string): string {
+  return `checkpoint:${hash}`;
+}
+
+export function issueEntityId(id: string): string {
+  return id.startsWith('issue:') ? id : `issue:${id}`;
+}
+
+export function criterionEntityId(issueId: string, index: number): string {
+  const bare = issueId.replace(/^issue:/, '');
+  return `criterion:${bare}:ac-${index}`;
+}
+
+export function decisionEntityId(id: string): string {
+  return id.startsWith('decision:') ? id : `decision:${id}`;
+}
+
+// ---------------------------------------------------------------------------
+// Repository Config
+// ---------------------------------------------------------------------------
+
+export interface TrellisVcsConfig {
+  /** Absolute path to the repository root. */
+  rootPath: string;
+
+  /** Glob patterns to ignore (e.g. ['node_modules', '.git', '*.log']). */
+  ignorePatterns: string[];
+
+  /** Debounce interval for file watcher in ms. */
+  debounceMs: number;
+
+  /** Name of the default branch. */
+  defaultBranch: string;
+
+  /** Path to the .trellis database file. */
+  dbPath: string;
+}
+
+export const DEFAULT_CONFIG: Omit<TrellisVcsConfig, 'rootPath'> = {
+  ignorePatterns: [
+    'node_modules',
+    '.git',
+    '.trellis',
+    'dist',
+    'build',
+    '.DS_Store',
+    '*.log',
+  ],
+  debounceMs: 300,
+  defaultBranch: 'main',
+  dbPath: '.trellis/trellis.db',
+};

package/src/vcs/vcs-middleware.ts

@@ -0,0 +1,81 @@
+/**
+ * VCS Middleware
+ *
+ * Intercepts VcsOps in the kernel middleware chain and decomposes
+ * them into primitive EAV store operations before passing to the
+ * next middleware (or the store).
+ */
+
+import type {
+  KernelMiddleware,
+  MiddlewareContext,
+  OpMiddlewareNext,
+} from '../core/kernel/middleware.js';
+import type { KernelOp } from '../core/persist/backend.js';
+import { decompose } from './decompose.js';
+import { isVcsOp } from './ops.js';
+import type { VcsOp } from './types.js';
+
+export class VcsMiddleware implements KernelMiddleware {
+  name = 'vcs';
+
+  async handleOp(
+    op: KernelOp,
+    ctx: MiddlewareContext,
+    next: OpMiddlewareNext,
+  ): Promise<void> {
+    if (!isVcsOp(op as any)) {
+      return next(op, ctx);
+    }
+
+    const vcsOp = op as unknown as VcsOp;
+    const decomposed = decompose(vcsOp);
+
+    // Apply the decomposed primitive operations to the store.
+    // We create synthetic KernelOps for each batch and pass them through.
+    if (decomposed.deleteFacts.length > 0) {
+      await next(
+        {
+          ...op,
+          kind: 'deleteFacts' as any,
+          facts: decomposed.deleteFacts,
+          links: undefined,
+        } as KernelOp,
+        ctx,
+      );
+    }
+    if (decomposed.deleteLinks.length > 0) {
+      await next(
+        {
+          ...op,
+          kind: 'deleteLinks' as any,
+          facts: undefined,
+          links: decomposed.deleteLinks,
+        } as KernelOp,
+        ctx,
+      );
+    }
+    if (decomposed.addFacts.length > 0) {
+      await next(
+        {
+          ...op,
+          kind: 'addFacts' as any,
+          facts: decomposed.addFacts,
+          links: undefined,
+        } as KernelOp,
+        ctx,
+      );
+    }
+    if (decomposed.addLinks.length > 0) {
+      await next(
+        {
+          ...op,
+          kind: 'addLinks' as any,
+          facts: undefined,
+          links: decomposed.addLinks,
+        } as KernelOp,
+        ctx,
+      );
+    }
+  }
+}

package/src/watcher/fs-watcher.ts

@@ -0,0 +1,217 @@
+/**
+ * Filesystem Watcher
+ *
+ * Monitors a directory tree for changes using Bun's fs.watch.
+ * Debounces rapid events and filters ignored paths.
+ * Emits FileChangeEvents to a callback.
+ */
+
+import { watch, type FSWatcher } from 'fs';
+import { readdir, stat, readFile } from 'fs/promises';
+import { join, relative } from 'path';
+import type { FileChangeEvent } from '../vcs/types.js';
+
+export interface FileWatcherConfig {
+  rootPath: string;
+  ignorePatterns: string[];
+  debounceMs: number;
+  onEvent: (event: FileChangeEvent) => void | Promise<void>;
+}
+
+/**
+ * Computes SHA-256 content hash for a file.
+ */
+async function hashFile(filePath: string): Promise<string> {
+  const content = await readFile(filePath);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', content);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Checks if a path matches any ignore pattern (simple glob-like matching).
+ */
+function shouldIgnore(relPath: string, patterns: string[]): boolean {
+  for (const pattern of patterns) {
+    // Simple matching: exact segment match or extension glob
+    if (pattern.startsWith('*.')) {
+      const ext = pattern.slice(1); // e.g. '.log'
+      if (relPath.endsWith(ext)) return true;
+    } else if (relPath.includes(pattern)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export class FileWatcher {
+  private config: FileWatcherConfig;
+  private watchers: FSWatcher[] = [];
+  private debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private knownFiles = new Map<string, string>(); // relPath → contentHash
+  private running = false;
+
+  constructor(config: FileWatcherConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Scans the directory tree and builds an initial map of all tracked files.
+   * Returns the list of FileChangeEvents for the initial state (all adds).
+   */
+  async scan(): Promise<FileChangeEvent[]> {
+    const events: FileChangeEvent[] = [];
+    const entries = await this.walkDir(this.config.rootPath);
+
+    for (const absPath of entries) {
+      const relPath = relative(this.config.rootPath, absPath);
+      if (shouldIgnore(relPath, this.config.ignorePatterns)) continue;
+
+      try {
+        const hash = await hashFile(absPath);
+        const stats = await stat(absPath);
+        this.knownFiles.set(relPath, hash);
+        events.push({
+          type: 'add',
+          path: relPath,
+          contentHash: hash,
+          size: stats.size,
+          timestamp: new Date().toISOString(),
+        });
+      } catch {
+        // File may have been deleted between scan and hash
+      }
+    }
+
+    return events;
+  }
+
+  /**
+   * Starts watching the directory tree for changes.
+   */
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+
+    try {
+      const watcher = watch(
+        this.config.rootPath,
+        { recursive: true },
+        (eventType, filename) => {
+          if (!filename) return;
+          const relPath = filename.toString();
+          if (shouldIgnore(relPath, this.config.ignorePatterns)) return;
+          this.debouncedHandle(relPath);
+        },
+      );
+      this.watchers.push(watcher);
+    } catch {
+      // recursive watch not supported on all platforms; fall back gracefully
+      console.warn('Recursive watch not supported; using scan-based polling.');
+    }
+  }
+
+  /**
+   * Stops all watchers.
+   */
+  stop(): void {
+    this.running = false;
+    for (const w of this.watchers) {
+      w.close();
+    }
+    this.watchers = [];
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+  }
+
+  /**
+   * Returns the current known file map (path → contentHash).
+   */
+  getKnownFiles(): Map<string, string> {
+    return new Map(this.knownFiles);
+  }
+
+  private debouncedHandle(relPath: string): void {
+    const existing = this.debounceTimers.get(relPath);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(async () => {
+      this.debounceTimers.delete(relPath);
+      await this.handleChange(relPath);
+    }, this.config.debounceMs);
+
+    this.debounceTimers.set(relPath, timer);
+  }
+
+  private async handleChange(relPath: string): Promise<void> {
+    const absPath = join(this.config.rootPath, relPath);
+    const known = this.knownFiles.get(relPath);
+
+    try {
+      const stats = await stat(absPath);
+      if (!stats.isFile()) return;
+
+      const hash = await hashFile(absPath);
+
+      if (!known) {
+        // New file
+        this.knownFiles.set(relPath, hash);
+        await this.config.onEvent({
+          type: 'add',
+          path: relPath,
+          contentHash: hash,
+          size: stats.size,
+          timestamp: new Date().toISOString(),
+        });
+      } else if (known !== hash) {
+        // Modified file
+        const oldHash = known;
+        this.knownFiles.set(relPath, hash);
+        await this.config.onEvent({
+          type: 'modify',
+          path: relPath,
+          contentHash: hash,
+          oldContentHash: oldHash,
+          size: stats.size,
+          timestamp: new Date().toISOString(),
+        });
+      }
+      // If hash is the same, no event (unchanged)
+    } catch {
+      // File doesn't exist → it was deleted
+      if (known) {
+        this.knownFiles.delete(relPath);
+        await this.config.onEvent({
+          type: 'delete',
+          path: relPath,
+          contentHash: known,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+  }
+
+  private async walkDir(dir: string): Promise<string[]> {
+    const results: string[] = [];
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        const relFromRoot = relative(this.config.rootPath, fullPath);
+        if (shouldIgnore(relFromRoot, this.config.ignorePatterns)) continue;
+
+        if (entry.isDirectory()) {
+          const sub = await this.walkDir(fullPath);
+          results.push(...sub);
+        } else if (entry.isFile()) {
+          results.push(fullPath);
+        }
+      }
+    } catch {
+      // Permission error or deleted dir
+    }
+    return results;
+  }
+}

package/src/watcher/index.ts

@@ -0,0 +1,9 @@
+/**
+ * File Watcher
+ *
+ * Monitors a directory for filesystem changes and emits FileChangeEvents.
+ * Uses Bun's built-in fs.watch for zero-dependency file monitoring.
+ */
+
+export { FileWatcher } from './fs-watcher.js';
+export { Ingestion } from './ingestion.js';

package/src/watcher/ingestion.ts

@@ -0,0 +1,116 @@
+/**
+ * Ingestion Pipeline
+ *
+ * Bridges the file watcher and the kernel: converts FileChangeEvents
+ * into VcsOps and applies them to the kernel via mutate().
+ */
+
+import type { FileChangeEvent, VcsOpKind } from '../vcs/types.js';
+import { createVcsOp } from '../vcs/ops.js';
+import type { VcsOp } from '../vcs/types.js';
+import { extname } from 'path';
+
+// Simple language detection from file extension
+const EXT_LANGUAGE: Record<string, string> = {
+  '.ts': 'typescript',
+  '.tsx': 'typescript',
+  '.js': 'javascript',
+  '.jsx': 'javascript',
+  '.py': 'python',
+  '.rs': 'rust',
+  '.go': 'go',
+  '.rb': 'ruby',
+  '.java': 'java',
+  '.c': 'c',
+  '.cpp': 'cpp',
+  '.h': 'c',
+  '.hpp': 'cpp',
+  '.cs': 'csharp',
+  '.swift': 'swift',
+  '.kt': 'kotlin',
+  '.md': 'markdown',
+  '.json': 'json',
+  '.yaml': 'yaml',
+  '.yml': 'yaml',
+  '.toml': 'toml',
+  '.html': 'html',
+  '.css': 'css',
+  '.scss': 'scss',
+  '.vue': 'vue',
+  '.svelte': 'svelte',
+};
+
+function detectLanguage(filePath: string): string | undefined {
+  const ext = extname(filePath).toLowerCase();
+  return EXT_LANGUAGE[ext];
+}
+
+export class Ingestion {
+  private agentId: string;
+  private lastOpHash: string | undefined;
+  private onOp: (op: VcsOp) => void | Promise<void>;
+
+  constructor(opts: {
+    agentId: string;
+    lastOpHash?: string;
+    onOp: (op: VcsOp) => void | Promise<void>;
+  }) {
+    this.agentId = opts.agentId;
+    this.lastOpHash = opts.lastOpHash;
+    this.onOp = opts.onOp;
+  }
+
+  /**
+   * Processes a single FileChangeEvent, producing and emitting a VcsOp.
+   */
+  async process(event: FileChangeEvent): Promise<VcsOp> {
+    let kind: VcsOpKind;
+
+    switch (event.type) {
+      case 'add':
+        kind = 'vcs:fileAdd';
+        break;
+      case 'modify':
+        kind = 'vcs:fileModify';
+        break;
+      case 'delete':
+        kind = 'vcs:fileDelete';
+        break;
+      case 'rename':
+        kind = 'vcs:fileRename';
+        break;
+    }
+
+    const op = await createVcsOp(kind, {
+      agentId: this.agentId,
+      previousHash: this.lastOpHash,
+      vcs: {
+        filePath: event.path,
+        oldFilePath: event.oldPath,
+        contentHash: event.contentHash,
+        oldContentHash: event.oldContentHash,
+        size: event.size,
+        language: detectLanguage(event.path),
+      },
+    });
+
+    this.lastOpHash = op.hash;
+    await this.onOp(op);
+    return op;
+  }
+
+  /**
+   * Processes a batch of FileChangeEvents in order.
+   */
+  async processBatch(events: FileChangeEvent[]): Promise<VcsOp[]> {
+    const ops: VcsOp[] = [];
+    for (const event of events) {
+      ops.push(await this.process(event));
+    }
+    return ops;
+  }
+
+  getLastOpHash(): string | undefined {
+    return this.lastOpHash;
+  }
+}