proagents 1.0.0

package/proagents/config/templates/api-route.template.ts

@@ -0,0 +1,142 @@
+/**
+ * {{routeName}} API Route Template
+ *
+ * Copy this file and customize for your project.
+ * Variables available:
+ * - {{routeName}} - Route name (e.g., users, products)
+ * - {{RouteName}} - PascalCase name
+ * - {{description}} - Route description
+ */
+
+// Express example - adapt for your framework (Next.js, Fastify, etc.)
+import { Router, Request, Response, NextFunction } from 'express';
+import { z } from 'zod';
+
+const router = Router();
+
+// ==========================================
+// VALIDATION SCHEMAS
+// ==========================================
+
+const create{{RouteName}}Schema = z.object({
+  // Define your create schema
+  name: z.string().min(1).max(255),
+});
+
+const update{{RouteName}}Schema = z.object({
+  // Define your update schema
+  name: z.string().min(1).max(255).optional(),
+});
+
+const query{{RouteName}}Schema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  limit: z.coerce.number().min(1).max(100).default(20),
+  search: z.string().optional(),
+});
+
+// ==========================================
+// ROUTES
+// ==========================================
+
+/**
+ * GET /{{routeName}}
+ * List all {{routeName}}
+ */
+router.get('/', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const query = query{{RouteName}}Schema.parse(req.query);
+
+    // TODO: Implement list logic
+    const items: unknown[] = [];
+    const total = 0;
+
+    res.json({
+      data: items,
+      meta: {
+        page: query.page,
+        limit: query.limit,
+        total,
+        totalPages: Math.ceil(total / query.limit),
+      },
+    });
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * GET /{{routeName}}/:id
+ * Get single {{routeName}} by ID
+ */
+router.get('/:id', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { id } = req.params;
+
+    // TODO: Implement get by ID logic
+    const item = null;
+
+    if (!item) {
+      return res.status(404).json({
+        error: 'Not Found',
+        message: '{{RouteName}} not found',
+      });
+    }
+
+    res.json({ data: item });
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * POST /{{routeName}}
+ * Create new {{routeName}}
+ */
+router.post('/', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const data = create{{RouteName}}Schema.parse(req.body);
+
+    // TODO: Implement create logic
+    const created = { id: 'new-id', ...data };
+
+    res.status(201).json({ data: created });
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * PUT /{{routeName}}/:id
+ * Update existing {{routeName}}
+ */
+router.put('/:id', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { id } = req.params;
+    const data = update{{RouteName}}Schema.parse(req.body);
+
+    // TODO: Implement update logic
+    const updated = { id, ...data };
+
+    res.json({ data: updated });
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * DELETE /{{routeName}}/:id
+ * Delete {{routeName}}
+ */
+router.delete('/:id', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { id } = req.params;
+
+    // TODO: Implement delete logic
+
+    res.status(204).send();
+  } catch (error) {
+    next(error);
+  }
+});
+
+export default router;

package/proagents/config/templates/component.template.tsx

@@ -0,0 +1,55 @@
+/**
+ * {{ComponentName}} Component Template
+ *
+ * Copy this file and customize for your project.
+ * Variables available:
+ * - {{ComponentName}} - PascalCase name
+ * - {{componentName}} - camelCase name
+ * - {{description}} - Component description
+ */
+
+import React from 'react';
+import type { FC } from 'react';
+
+// {{#if hasStyles}}
+import styles from './{{ComponentName}}.module.css';
+// {{/if}}
+
+/**
+ * Props for {{ComponentName}}
+ */
+interface {{ComponentName}}Props {
+  /** Add your props here */
+  children?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * {{ComponentName}} - {{description}}
+ *
+ * @example
+ * ```tsx
+ * <{{ComponentName}}>
+ *   Content here
+ * </{{ComponentName}}>
+ * ```
+ */
+export const {{ComponentName}}: FC<{{ComponentName}}Props> = ({
+  children,
+  className,
+}) => {
+  return (
+    <div
+      className={className}
+      data-testid="{{component-name}}"
+    >
+      {children}
+    </div>
+  );
+};
+
+// Optional: Add displayName for debugging
+{{ComponentName}}.displayName = '{{ComponentName}}';
+
+// Optional: Default export if your project uses it
+// export default {{ComponentName}};

package/proagents/config/templates/hook.template.ts

@@ -0,0 +1,93 @@
+/**
+ * {{hookName}} Hook Template
+ *
+ * Copy this file and customize for your project.
+ * Variables available:
+ * - {{hookName}} - camelCase name (e.g., useUserData)
+ * - {{HookName}} - PascalCase without 'use' (e.g., UserData)
+ * - {{description}} - Hook description
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+
+/**
+ * Return type for {{hookName}}
+ */
+interface {{HookName}}Result {
+  /** The data returned by the hook */
+  data: unknown;
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Refetch function */
+  refetch: () => void;
+}
+
+/**
+ * Options for {{hookName}}
+ */
+interface {{HookName}}Options {
+  /** Enable/disable the hook */
+  enabled?: boolean;
+  /** Callback on success */
+  onSuccess?: (data: unknown) => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * {{hookName}} - {{description}}
+ *
+ * @param options - Hook options
+ * @returns Hook result with data, loading, and error states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = {{hookName}}();
+ *
+ * if (isLoading) return <Loading />;
+ * if (error) return <Error error={error} />;
+ * return <Display data={data} />;
+ * ```
+ */
+export function {{hookName}}(
+  options: {{HookName}}Options = {}
+): {{HookName}}Result {
+  const { enabled = true, onSuccess, onError } = options;
+
+  const [data, setData] = useState<unknown>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchData = useCallback(async () => {
+    if (!enabled) return;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // TODO: Implement data fetching logic
+      const result = await Promise.resolve(null);
+      setData(result);
+      onSuccess?.(result);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Unknown error');
+      setError(error);
+      onError?.(error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [enabled, onSuccess, onError]);
+
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: fetchData,
+  };
+}

package/proagents/config/templates/test.template.ts

@@ -0,0 +1,171 @@
+/**
+ * {{TestName}} Test Template
+ *
+ * Copy this file and customize for your project.
+ * Variables available:
+ * - {{TestName}} - PascalCase name
+ * - {{testName}} - camelCase name
+ * - {{testType}} - Type: unit | integration | e2e
+ * - {{description}} - Test description
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+// Or for Jest:
+// import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
+
+// Import the module under test
+// import { {{testName}} } from './{{testName}}';
+
+// ==========================================
+// TEST UTILITIES
+// ==========================================
+
+/**
+ * Factory function for creating test data
+ */
+function createMock{{TestName}}(overrides = {}) {
+  return {
+    id: 'test-id',
+    name: 'Test Name',
+    createdAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+// ==========================================
+// TESTS
+// ==========================================
+
+describe('{{TestName}}', () => {
+  // ----------------------------------------
+  // Setup & Teardown
+  // ----------------------------------------
+
+  beforeEach(() => {
+    // Setup before each test
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    // Cleanup after each test
+  });
+
+  // ----------------------------------------
+  // Basic Tests
+  // ----------------------------------------
+
+  describe('initialization', () => {
+    it('should initialize correctly', () => {
+      // Arrange
+      const input = createMock{{TestName}}();
+
+      // Act
+      // const result = {{testName}}(input);
+
+      // Assert
+      // expect(result).toBeDefined();
+      expect(true).toBe(true); // Placeholder
+    });
+
+    it('should handle missing optional fields', () => {
+      // Arrange
+      const input = createMock{{TestName}}({ name: undefined });
+
+      // Act & Assert
+      // expect(() => {{testName}}(input)).not.toThrow();
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+
+  // ----------------------------------------
+  // Feature Tests
+  // ----------------------------------------
+
+  describe('when [condition]', () => {
+    it('should [expected behavior]', () => {
+      // Arrange
+      const input = createMock{{TestName}}();
+
+      // Act
+      // const result = {{testName}}(input);
+
+      // Assert
+      // expect(result.property).toBe(expected);
+      expect(true).toBe(true); // Placeholder
+    });
+
+    it('should handle edge case: [description]', () => {
+      // Arrange
+      const edgeCaseInput = createMock{{TestName}}({
+        // Edge case data
+      });
+
+      // Act & Assert
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+
+  // ----------------------------------------
+  // Error Handling
+  // ----------------------------------------
+
+  describe('error handling', () => {
+    it('should throw error when input is invalid', () => {
+      // Arrange
+      const invalidInput = null;
+
+      // Act & Assert
+      // expect(() => {{testName}}(invalidInput)).toThrow('Expected error message');
+      expect(true).toBe(true); // Placeholder
+    });
+
+    it('should return error state on failure', async () => {
+      // Arrange
+      // Mock the dependency to fail
+      // vi.mocked(dependency).mockRejectedValue(new Error('Fail'));
+
+      // Act
+      // const result = await {{testName}}();
+
+      // Assert
+      // expect(result.error).toBeDefined();
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+
+  // ----------------------------------------
+  // Async Tests
+  // ----------------------------------------
+
+  describe('async operations', () => {
+    it('should fetch data successfully', async () => {
+      // Arrange
+      // Mock the API call
+      // vi.mocked(api.get).mockResolvedValue({ data: mockData });
+
+      // Act
+      // const result = await {{testName}}();
+
+      // Assert
+      // expect(result.data).toEqual(mockData);
+      expect(true).toBe(true); // Placeholder
+    });
+
+    it('should handle loading state', async () => {
+      // Arrange & Act & Assert
+      // Test loading state transitions
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+
+  // ----------------------------------------
+  // Integration Tests (if applicable)
+  // ----------------------------------------
+
+  describe('integration', () => {
+    it('should work with [dependent module]', () => {
+      // Test integration with other modules
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+});

package/proagents/config-versioning/README.md

@@ -0,0 +1,120 @@
+# Configuration Version Control
+
+Track, version, and manage configuration changes.
+
+---
+
+## Overview
+
+Configuration version control ensures all ProAgents configuration changes are tracked, reversible, and auditable.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Config Version Control                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Config Change ──► Validation ──► Version ──► Apply        │
+│       │                            │                       │
+│       ▼                            ▼                       │
+│  Change Log                    History                     │
+│       │                            │                       │
+│       └────────────────────────────┘                       │
+│                    │                                       │
+│                    ▼                                       │
+│              Rollback Available                            │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+### View Config History
+
+```bash
+# Show config change history
+proagents config history
+
+# Show specific config file history
+proagents config history --file proagents.config.yaml
+```
+
+### Rollback Config
+
+```bash
+# Rollback to previous version
+proagents config rollback
+
+# Rollback to specific version
+proagents config rollback --to v2.3.0
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Version Tracking** | Every change creates a version |
+| **Change Logging** | Reason and author recorded |
+| **Diff Support** | Compare versions |
+| **Rollback** | Revert to any previous version |
+| **Validation** | Validate before applying |
+| **Audit Trail** | Complete history for compliance |
+
+---
+
+## Documentation Files
+
+| File | Description |
+|------|-------------|
+| [versioning.md](./versioning.md) | Version tracking details |
+| [changelog.md](./changelog.md) | Config changelog |
+| [rollback.md](./rollback.md) | Rollback procedures |
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+
+config_versioning:
+  enabled: true
+
+  # Track these config files
+  tracked_files:
+    - "proagents.config.yaml"
+    - "standards/**/*.yaml"
+    - "rules/**/*.yaml"
+
+  # Version storage
+  storage:
+    path: ".proagents/config-history"
+    max_versions: 100
+
+  # Change requirements
+  changes:
+    require_reason: true
+    require_approval: false
+    validate_before_apply: true
+
+  # Notifications
+  notifications:
+    on_change: true
+    channels: ["slack:#config-changes"]
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `proagents config history` | Show version history |
+| `proagents config diff` | Compare versions |
+| `proagents config rollback` | Revert to previous |
+| `proagents config export` | Export configuration |
+| `proagents config import` | Import configuration |
+| `proagents config validate` | Validate configuration |