@hivehub/rulebook 3.4.2 → 4.1.0

package/templates/services/PINO.md

@@ -0,0 +1,24 @@
+<!-- PINO:START -->
+# Pino — Structured Logging
+
+## Configuration
+- Create singleton logger instance: `const logger = pino({ level: process.env.LOG_LEVEL || 'info' })`
+- Use child loggers for request context: `req.log = logger.child({ requestId: req.id })`
+- Configure pretty print for development only: `transport: { target: 'pino-pretty' }` (only when `NODE_ENV !== 'production'`)
+
+## Log Levels
+- `error`: Unexpected errors requiring immediate attention
+- `warn`: Recoverable errors, deprecated usage, approaching limits
+- `info`: Significant state changes, important business events
+- `debug`: Detailed flow for troubleshooting (disabled in production)
+- `trace`: High-frequency diagnostic data (never in production)
+
+## Structured Fields
+- Always include: `{ service, version, requestId, userId }` in request context
+- Never log: passwords, tokens, credit cards, PII fields
+- Log all outgoing HTTP calls with: `{ method, url, statusCode, duration }`
+
+## Performance
+- Avoid `JSON.stringify()` in log calls — pino handles serialization
+- Use `logger.isLevelEnabled('debug')` before expensive debug computations
+<!-- PINO:END -->

package/templates/services/PROMETHEUS.md

@@ -0,0 +1,33 @@
+<!-- PROMETHEUS:START -->
+# Prometheus — Metrics
+
+## Setup
+```typescript
+import { Registry, collectDefaultMetrics } from 'prom-client';
+const registry = new Registry();
+collectDefaultMetrics({ register: registry });
+```
+
+Expose metrics endpoint:
+```typescript
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', registry.contentType);
+  res.end(await registry.metrics());
+});
+```
+
+## Metric Types
+- **Counter**: Monotonically increasing values (`http_requests_total`)
+- **Gauge**: Values that go up and down (`active_connections`, memory usage)
+- **Histogram**: Duration/size distributions (`http_request_duration_seconds`)
+- **Summary**: Percentile calculations (use Histogram instead when possible)
+
+## Naming Conventions
+- Format: `<namespace>_<metric_name>_<unit>` (e.g., `app_http_request_duration_seconds`)
+- Use `_total` suffix for counters
+- Include all relevant labels: `{ method, route, status_code }`
+
+## Alerting
+- Define recording rules for frequently queried expressions
+- Set alert thresholds: error rate > 5%, p99 latency > 2s, memory > 80%
+<!-- PROMETHEUS:END -->

package/templates/services/SENTRY.md

@@ -0,0 +1,23 @@
+<!-- SENTRY:START -->
+# Sentry — Error Tracking
+
+## Configuration
+- Initialize Sentry at application entry point BEFORE other imports
+- Set `dsn` from environment variable: `process.env.SENTRY_DSN`
+- Configure `environment` from `NODE_ENV`
+- Enable `tracesSampleRate: 0.1` in production (not 1.0)
+
+## Error Capture
+- Wrap route handlers with Sentry error middleware
+- Use `Sentry.captureException(err)` in catch blocks for unexpected errors
+- Add custom context: `Sentry.setContext('user', { id, email })`
+- Never log sensitive data (passwords, tokens) in Sentry context
+
+## Release Tracking
+- Set `release` using git commit SHA: `process.env.SENTRY_RELEASE`
+- Run `sentry-cli releases` in CI to associate commits with releases
+
+## Performance
+- Use `Sentry.startTransaction()` for tracking custom operations
+- Add distributed tracing headers to internal service calls
+<!-- SENTRY:END -->

package/templates/services/WINSTON.md

@@ -0,0 +1,30 @@
+<!-- WINSTON:START -->
+# Winston — Logging
+
+## Configuration
+```typescript
+const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()  // Always JSON in production
+  ),
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
+  ],
+});
+```
+
+## Log Levels
+- Use semantic levels: `error`, `warn`, `info`, `http`, `debug`
+- Set `level: 'info'` in production; `level: 'debug'` in development
+
+## Metadata
+- Include structured metadata: `logger.info('message', { userId, requestId, duration })`
+- Never log sensitive data (tokens, passwords, credit card numbers)
+
+## Custom Transports
+- Add external service transports (Datadog, Loggly) as additional transports
+- Always keep console transport as fallback
+<!-- WINSTON:END -->

package/dist/core/openspec-manager.d.ts

@@ -1,133 +0,0 @@
-import type { OpenSpecData, OpenSpecTask } from '../types.js';
-export declare class OpenSpecManager {
-    private openspecPath;
-    private changesPath;
-    private data;
-    private onLog?;
-    constructor(projectRoot: string);
-    /**
-     * Set callback for logging (used by watcher UI)
-     */
-    setLogCallback(callback: (type: 'info' | 'success' | 'warning' | 'error', message: string) => void): void;
-    /**
-     * Initialize OpenSpec directory structure (deprecated - no longer creates directories)
-     * OpenSpec is legacy; only operates on existing directories.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Load OpenSpec data from changes directory
-     */
-    loadOpenSpec(): Promise<OpenSpecData>;
-    /**
-     * Save OpenSpec data (tasks are managed in changes, so this is mostly for metadata)
-     */
-    saveOpenSpec(): Promise<void>;
-    /**
-     * Sync task status on agent start
-     * Loads all tasks and ensures the data is fresh
-     */
-    syncTaskStatus(): Promise<void>;
-    /**
-     * Load tasks from all changes directories
-     */
-    private loadTasksFromChanges;
-    /**
-     * Parse tasks from markdown content
-     */
-    private parseTasksFromMarkdown;
-    /**
-     * Get tasks ordered by priority
-     */
-    getTasksByPriority(): Promise<OpenSpecTask[]>;
-    /**
-     * Get current active task
-     */
-    getCurrentTask(): Promise<OpenSpecTask | null>;
-    /**
-     * Set current task
-     */
-    setCurrentTask(taskId: string): Promise<void>;
-    /**
-     * Update task status
-     */
-    updateTaskStatus(taskId: string, status: OpenSpecTask['status']): Promise<void>;
-    /**
-     * Mark task as complete
-     */
-    markTaskComplete(taskId: string): Promise<void>;
-    /**
-     * Update task status in markdown files
-     */
-    private updateMarkdownTaskStatus;
-    /**
-     * Update task status in markdown content
-     */
-    private updateTaskInMarkdown;
-    /**
-     * Add new task
-     */
-    addTask(task: Omit<OpenSpecTask, 'id' | 'createdAt' | 'updatedAt' | 'attempts'>): Promise<string>;
-    /**
-     * Get task by ID
-     */
-    getTask(taskId: string): Promise<OpenSpecTask | null>;
-    /**
-     * Get task dependencies
-     */
-    getTaskDependencies(taskId: string): Promise<OpenSpecTask[]>;
-    /**
-     * Check if task dependencies are satisfied
-     */
-    areDependenciesSatisfied(taskId: string): Promise<boolean>;
-    /**
-     * Get next available task
-     */
-    getNextTask(): Promise<OpenSpecTask | null>;
-    /**
-     * Increment task attempts
-     */
-    incrementTaskAttempts(taskId: string): Promise<void>;
-    /**
-     * Get task statistics
-     */
-    getTaskStats(): Promise<{
-        total: number;
-        pending: number;
-        inProgress: number;
-        completed: number;
-        failed: number;
-        skipped: number;
-    }>;
-    /**
-     * Generate ASCII dependency tree
-     */
-    generateDependencyTree(): Promise<string>;
-    /**
-     * Validate dependency graph for cycles
-     */
-    validateDependencyGraph(): Promise<{
-        valid: boolean;
-        cycles: string[][];
-    }>;
-    /**
-     * Get tasks that can be executed in parallel
-     */
-    getParallelExecutableTasks(): Promise<OpenSpecTask[][]>;
-    /**
-     * Get execution order respecting dependencies
-     */
-    getExecutionOrder(): Promise<OpenSpecTask[]>;
-    /**
-     * Check if task can be started (dependencies satisfied)
-     */
-    canStartTask(taskId: string): Promise<boolean>;
-    /**
-     * Get blocking tasks (tasks that block the given task)
-     */
-    getBlockingTasks(taskId: string): Promise<OpenSpecTask[]>;
-}
-/**
- * Create a new OpenSpecManager instance
- */
-export declare function createOpenSpecManager(projectRoot: string): OpenSpecManager;
-//# sourceMappingURL=openspec-manager.d.ts.map

package/dist/core/openspec-manager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"openspec-manager.d.ts","sourceRoot":"","sources":["../../src/core/openspec-manager.ts"],"names":[],"mappings":"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"}