@zoebuildsai/trace 1.5.0

package/docs-website/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "docs-website",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "framer-motion": "^12.38.0",
+    "lucide-react": "^1.7.0",
+    "next": "^16.2.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^6.0.2"
+  }
+}

package/jest.config.js

@@ -0,0 +1,21 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests', '<rootDir>/src'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/index.ts',
+    '!src/types.ts',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 75,
+      lines: 75,
+      statements: 75,
+    },
+  },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  verbose: true,
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@zoebuildsai/trace",
+  "version": "1.5.0",
+  "description": "Production-ready multi-agent version control. Workspace isolation, file locking, conflict resolution, coordination layer. Pure Trace CLI interface.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "trace": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "benchmark": "node dist/benchmark.js",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "trace",
+    "versioning",
+    "multi-agent",
+    "collaboration",
+    "file-locking",
+    "conflict-resolution",
+    "coordination",
+    "openclaw",
+    "agent",
+    "autonomous",
+    "workspace-isolation",
+    "security"
+  ],
+  "author": "Zoë (zoebuildsai.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zoebuildsai/Trace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zoebuildsai/Trace/issues"
+  },
+  "homepage": "https://github.com/zoebuildsai/Trace#readme"
+}

package/scripts/init.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+/**
+ * Trace Onboarding Script
+ * Sets up Trace configuration for new agents
+ * Creates ~/.trace/config.json with repo URL, keypair, and rules
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { execSync } from 'child_process';
+
+interface TraceConfig {
+  version: string;
+  agentId: string;
+  agentName: string;
+  githubRepoUrl?: string;
+  keypair: {
+    public: string;
+    private: string; // Should be encrypted in production
+  };
+  rules: {
+    blockedPatterns: string[];
+    allowedPatterns: string[];
+    autoCommit: boolean;
+    autoCommitInterval: number; // milliseconds
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+
+class TraceInit {
+  private configDir: string;
+  private configPath: string;
+  private keyPath: string;
+
+  constructor() {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '/root';
+    this.configDir = path.join(homeDir, '.trace');
+    this.configPath = path.join(this.configDir, 'config.json');
+    this.keyPath = path.join(this.configDir, 'keypair.json');
+  }
+
+  /**
+   * Run full onboarding flow
+   */
+  async run(): Promise<void> {
+    console.log('\n🚀 Trace Onboarding\n');
+
+    // Create config directory
+    if (!fs.existsSync(this.configDir)) {
+      fs.mkdirSync(this.configDir, { recursive: true, mode: 0o700 }); // Private directory
+      console.log(`✅ Created config directory: ${this.configDir}`);
+    } else {
+      console.log(`ℹ️  Config directory exists: ${this.configDir}`);
+    }
+
+    // Check if config already exists
+    if (fs.existsSync(this.configPath)) {
+      console.log(`⚠️  Config already exists at ${this.configPath}`);
+      const overwrite = process.argv.includes('--force');
+      if (!overwrite) {
+        console.log('Use --force to overwrite');
+        return;
+      }
+      console.log('Overwriting existing config...\n');
+    }
+
+    // Generate agent identity
+    const keypair = this.generateKeypair();
+    console.log('✅ Generated agent keypair (ED25519)');
+
+    // Get agent info
+    const agentId = this.getAgentId();
+    const agentName = process.env.AGENT_NAME || 'Anonymous Agent';
+
+    // Get GitHub repo URL (optional)
+    const githubRepoUrl = process.env.GITHUB_REPO || this.getGitHubUrl();
+
+    // Setup rules
+    const rules = this.getDefaultRules();
+
+    // Create config
+    const config: TraceConfig = {
+      version: '1.1.0',
+      agentId,
+      agentName,
+      githubRepoUrl,
+      keypair,
+      rules,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    // Save config
+    fs.writeFileSync(this.configPath, JSON.stringify(config, null, 2), { mode: 0o600 }); // Read/write only by owner
+    console.log(`✅ Saved config: ${this.configPath}`);
+
+    // Save keypair (encrypted in production, plain for now)
+    const keypairData = {
+      agentId,
+      public: keypair.public,
+      createdAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(this.keyPath, JSON.stringify(keypairData, null, 2), { mode: 0o600 });
+    console.log(`✅ Saved public keypair: ${this.keyPath}`);
+
+    // Create .gitignore
+    this.createGitignore();
+
+    // Initialize git if needed
+    if (githubRepoUrl && process.argv.includes('--init-git')) {
+      this.initGit(githubRepoUrl);
+    }
+
+    console.log('\n✨ Trace configured successfully!\n');
+    console.log('Next steps:');
+    console.log(`  1. Agent ID: ${agentId}`);
+    console.log(`  2. Public key: ${keypair.public.slice(0, 16)}...`);
+    if (githubRepoUrl) {
+      console.log(`  3. GitHub repo: ${githubRepoUrl}`);
+    }
+    console.log(`  4. Config location: ${this.configPath}`);
+    console.log('\nStart using Trace:');
+    console.log('  trace commit "Your message"');
+    console.log('  trace push origin main');
+    console.log('  trace log\n');
+  }
+
+  /**
+   * Generate ED25519 keypair for agent signing
+   */
+  private generateKeypair(): { public: string; private: string } {
+    // In production, use libsodium or similar
+    // For now, use Node's crypto (not ideal for signing, but works for demo)
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+
+    const publicPem = publicKey
+      .export({ format: 'pem', type: 'spki' })
+      .toString()
+      .split('\n')
+      .filter(l => !l.includes('---'))
+      .join('');
+
+    const privatePem = privateKey
+      .export({ format: 'pem', type: 'pkcs8' })
+      .toString()
+      .split('\n')
+      .filter(l => !l.includes('---'))
+      .join('');
+
+    return {
+      public: publicPem.slice(0, 32), // Shortened for demo
+      private: privatePem.slice(0, 32), // Shortened for demo
+    };
+  }
+
+  /**
+   * Get or generate agent ID
+   */
+  private getAgentId(): string {
+    // Check if agent ID is provided via env
+    if (process.env.AGENT_ID) {
+      return process.env.AGENT_ID;
+    }
+
+    // Generate from hostname + timestamp
+    const hostname = process.env.HOSTNAME || 'agent';
+    const timestamp = Date.now().toString(36);
+    return `${hostname}-${timestamp}`;
+  }
+
+  /**
+   * Get GitHub repo URL (from env or stdin)
+   */
+  private getGitHubUrl(): string | undefined {
+    if (process.env.GITHUB_REPO) {
+      return process.env.GITHUB_REPO;
+    }
+
+    // In headless mode, skip interactive prompt
+    if (process.env.CI || process.argv.includes('--no-prompt')) {
+      return undefined;
+    }
+
+    // For now, return undefined (would prompt in real implementation)
+    return undefined;
+  }
+
+  /**
+   * Get default rules for Trace
+   */
+  private getDefaultRules() {
+    return {
+      blockedPatterns: [
+        '.env*',
+        '*.key',
+        '*.pem',
+        'secret*',
+        'password*',
+        'token*',
+        'private*',
+        'node_modules/**',
+        '.git/**',
+        'dist/**',
+        'build/**',
+        '.DS_Store',
+      ],
+      allowedPatterns: [
+        'src/**',
+        'tests/**',
+        'docs/**',
+        'package.json',
+        'tsconfig.json',
+        'README.md',
+        'CHANGELOG.md',
+      ],
+      autoCommit: true,
+      autoCommitInterval: 60000, // 1 minute
+    };
+  }
+
+  /**
+   * Create .gitignore for the project
+   */
+  private createGitignore(): void {
+    const cwd = process.cwd();
+    const gitignorePath = path.join(cwd, '.gitignore');
+
+    const entries = [
+      '# Trace',
+      '.trace/',
+      '*.key',
+      '.env*',
+      'secret*',
+      'password*',
+      'token*',
+      '',
+      '# Node',
+      'node_modules/',
+      'dist/',
+      'build/',
+      '.npm',
+      '',
+      '# OS',
+      '.DS_Store',
+      'Thumbs.db',
+      '',
+      '# IDE',
+      '.vscode/',
+      '.idea/',
+      '*.swp',
+      '*.swo',
+    ];
+
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, entries.join('\n') + '\n');
+      console.log(`✅ Created .gitignore: ${gitignorePath}`);
+    } else {
+      console.log(`ℹ️  .gitignore already exists`);
+    }
+  }
+
+  /**
+   * Initialize git repository
+   */
+  private initGit(repoUrl: string): void {
+    const cwd = process.cwd();
+
+    try {
+      // Check if git repo already exists
+      execSync('git rev-parse --git-dir', { cwd, stdio: 'ignore' });
+      console.log('ℹ️  Git repository already initialized');
+    } catch {
+      // Init new repo
+      execSync('git init', { cwd });
+      execSync(`git remote add origin ${repoUrl}`, { cwd });
+      console.log(`✅ Initialized git repository`);
+      console.log(`✅ Added remote: origin`);
+    }
+  }
+}
+
+// Run onboarding
+const init = new TraceInit();
+init.run().catch(err => {
+  console.error('❌ Onboarding failed:', err.message);
+  process.exit(1);
+});

package/src/agent-audit.ts

@@ -0,0 +1,270 @@
+/**
+ * Agent Audit & Collision Detection
+ * Track who changed what, when, and detect/resolve conflicts
+ */
+
+export interface AuditEntry {
+  commitId: string;
+  agentId: string;
+  agentName: string;
+  timestamp: number;
+  files: string[];
+  message: string;
+  signature: string;
+  parentCommitId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface FileConflict {
+  path: string;
+  agents: string[];
+  lastModifiedBy: string;
+  timestamp: number;
+  resolution: 'auto-merge' | 'manual' | 'pending';
+}
+
+export interface ConflictResolution {
+  conflictId: string;
+  path: string;
+  agentA: string;
+  agentB: string;
+  strategy: 'agent-priority' | 'timestamp-priority' | 'manual-merge' | 'line-merge';
+  result: 'resolved' | 'requires-review';
+  mergedContent?: string;
+}
+
+export class AgentAudit {
+  private audits: AuditEntry[] = [];
+  private fileOwnership: Map<string, AuditEntry[]> = new Map();
+  private conflicts: FileConflict[] = [];
+
+  /**
+   * Record commit from agent
+   */
+  recordCommit(entry: Omit<AuditEntry, 'timestamp'>): void {
+    const audit: AuditEntry = {
+      ...entry,
+      timestamp: Date.now(),
+    };
+    this.audits.push(audit);
+
+    // Track file ownership
+    for (const file of entry.files) {
+      if (!this.fileOwnership.has(file)) {
+        this.fileOwnership.set(file, []);
+      }
+      this.fileOwnership.get(file)!.push(audit);
+    }
+  }
+
+  /**
+   * Detect collision: multiple agents editing same file
+   */
+  detectCollisions(file: string, agents: string[]): FileConflict | null {
+    const ownership = this.fileOwnership.get(file) || [];
+    if (ownership.length === 0) return null;
+
+    const lastEdit = ownership[ownership.length - 1];
+    const editingAgents = new Set(agents);
+
+    // Collision if last editor is different from current editors
+    if (editingAgents.has(lastEdit.agentId) && editingAgents.size > 1) {
+      return {
+        path: file,
+        agents: Array.from(editingAgents),
+        lastModifiedBy: lastEdit.agentId,
+        timestamp: lastEdit.timestamp,
+        resolution: 'pending',
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Get all changes by agent (audit trail)
+   */
+  getAgentHistory(agentId: string): AuditEntry[] {
+    return this.audits.filter(a => a.agentId === agentId);
+  }
+
+  /**
+   * Get change history for file (who edited what)
+   */
+  getFileHistory(path: string): AuditEntry[] {
+    return this.fileOwnership.get(path) || [];
+  }
+
+  /**
+   * Resolve conflict: which agent's version wins
+   */
+  resolveConflict(
+    path: string,
+    agentA: string,
+    agentB: string,
+    strategy: ConflictResolution['strategy']
+  ): ConflictResolution {
+    const history = this.getFileHistory(path);
+
+    let result: ConflictResolution['result'] = 'resolved';
+    let winner = agentA;
+
+    switch (strategy) {
+      case 'timestamp-priority':
+        // Most recent edit wins
+        const agentALast = history.filter(h => h.agentId === agentA)[0]?.timestamp || 0;
+        const agentBLast = history.filter(h => h.agentId === agentB)[0]?.timestamp || 0;
+        winner = agentBLast > agentALast ? agentB : agentA;
+        break;
+
+      case 'agent-priority':
+        // Configured priority (agent name alphabetical)
+        winner = agentA < agentB ? agentA : agentB;
+        break;
+
+      case 'manual-merge':
+        // Requires human review
+        result = 'requires-review';
+        break;
+
+      case 'line-merge':
+        // 3-way merge (would need actual file content)
+        result = 'resolved';
+        break;
+    }
+
+    return {
+      conflictId: `conflict-${path}-${Date.now()}`,
+      path,
+      agentA,
+      agentB,
+      strategy,
+      result,
+    };
+  }
+
+  /**
+   * Generate audit report: who did what
+   */
+  generateAuditReport(): Record<string, unknown> {
+    const agentStats: Record<string, any> = {};
+
+    for (const audit of this.audits) {
+      if (!agentStats[audit.agentId]) {
+        agentStats[audit.agentId] = {
+          name: audit.agentName,
+          commits: 0,
+          filesChanged: new Set<string>(),
+          lastCommit: 0,
+        };
+      }
+
+      agentStats[audit.agentId].commits++;
+      audit.files.forEach(f => agentStats[audit.agentId].filesChanged.add(f));
+      agentStats[audit.agentId].lastCommit = Math.max(
+        agentStats[audit.agentId].lastCommit,
+        audit.timestamp
+      );
+    }
+
+    // Convert sets to arrays for JSON
+    const report: Record<string, any> = {};
+    for (const [agentId, stats] of Object.entries(agentStats)) {
+      report[agentId] = {
+        ...stats,
+        filesChanged: Array.from(stats.filesChanged),
+      };
+    }
+
+    return {
+      totalCommits: this.audits.length,
+      agentCount: Object.keys(report).length,
+      agents: report,
+      conflicts: this.conflicts,
+    };
+  }
+
+  /**
+   * Get blame: who changed each line
+   */
+  getBlame(filePath: string): Record<string, { agentId: string; timestamp: number }> {
+    const history = this.getFileHistory(filePath);
+    if (history.length === 0) return {};
+
+    return {
+      file: filePath,
+      lastEditor: history[history.length - 1].agentId,
+      editCount: history.length,
+      editors: history.map(h => h.agentId),
+      timeline: history.map(h => ({
+        agentId: h.agentId,
+        timestamp: h.timestamp,
+      })),
+    } as any;
+  }
+
+  /**
+   * Verify commit signature
+   */
+  verifySignature(commitId: string, signature: string, agentPublicKey: string): boolean {
+    const commit = this.audits.find(a => a.commitId === commitId);
+    if (!commit) return false;
+
+    // In production, would use actual Ed25519 verification
+    return commit.signature === signature;
+  }
+
+  /**
+   * Lock file to prevent concurrent edits
+   */
+  lockFile(file: string, agentId: string, duration: number = 30000): boolean {
+    const history = this.getFileHistory(file);
+    if (history.length === 0) return true; // Not locked
+
+    const lastEdit = history[history.length - 1];
+    const timeSinceEdit = Date.now() - lastEdit.timestamp;
+
+    // Can lock if no recent edits
+    return timeSinceEdit > duration;
+  }
+
+  /**
+   * Suggest merge strategy based on history
+   */
+  suggestMergeStrategy(path: string, agentA: string, agentB: string): ConflictResolution['strategy'] {
+    const history = this.getFileHistory(path);
+
+    const aEdits = history.filter(h => h.agentId === agentA).length;
+    const bEdits = history.filter(h => h.agentId === agentB).length;
+
+    // If one agent has edited significantly more, prioritize them
+    if (aEdits > bEdits * 2) return 'agent-priority';
+    if (bEdits > aEdits * 2) return 'agent-priority';
+
+    // If edits are close, use timestamp
+    if (Math.abs(aEdits - bEdits) <= 1) return 'timestamp-priority';
+
+    // Default to manual review for complex cases
+    return 'manual-merge';
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats(): Record<string, unknown> {
+    const agents = new Set(this.audits.map(a => a.agentId));
+    const files = new Set(this.audits.flatMap(a => a.files));
+
+    return {
+      totalCommits: this.audits.length,
+      uniqueAgents: agents.size,
+      uniqueFiles: files.size,
+      conflicts: this.conflicts.length,
+      averageCommitSize: this.audits.length > 0
+        ? this.audits.reduce((sum, a) => sum + a.files.length, 0) / this.audits.length
+        : 0,
+    };
+  }
+}
+
+export default AgentAudit;