@fulmenhq/tsfulmen 0.1.6

package/schemas/crucible-ts/observability/logging/v1.0.0/logging-policy.schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/observability/logging/logging-policy-v1.0.0.json",
+  "title": "LoggingPolicy",
+  "description": "Organizational logging policy for profile validation and governance",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Policy version identifier for compatibility tracking.",
+      "default": "1.0.0"
+    },
+    "allowedProfiles": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "SIMPLE",
+          "STRUCTURED",
+          "ENTERPRISE",
+          "CUSTOM"
+        ]
+      },
+      "uniqueItems": true,
+      "description": "Logging profiles permitted within the organization."
+    },
+    "requiredProfiles": {
+      "type": "object",
+      "patternProperties": {
+        "^[a-zA-Z][a-zA-Z0-9_-]*$": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "SIMPLE",
+              "STRUCTURED",
+              "ENTERPRISE",
+              "CUSTOM"
+            ]
+          },
+          "uniqueItems": true
+        }
+      },
+      "description": "Required profiles by application type (e.g., workhorse, service, cli). Keys follow lower-case kebab or snake case."
+    },
+    "environmentRules": {
+      "type": "object",
+      "patternProperties": {
+        "^[a-zA-Z][a-zA-Z0-9_-]*$": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "SIMPLE",
+              "STRUCTURED",
+              "ENTERPRISE",
+              "CUSTOM"
+            ]
+          },
+          "uniqueItems": true
+        }
+      },
+      "description": "Allowed profiles by deployment environment."
+    },
+    "profileRequirements": {
+      "type": "object",
+      "patternProperties": {
+        "^(SIMPLE|STRUCTURED|ENTERPRISE|CUSTOM)$": {
+          "type": "object",
+          "properties": {
+            "minEnvironment": {
+              "type": "string",
+              "enum": [
+                "development",
+                "staging",
+                "production"
+              ],
+              "description": "Minimum environment required to enable the profile."
+            },
+            "maxEnvironment": {
+              "type": "string",
+              "enum": [
+                "development",
+                "staging",
+                "production"
+              ],
+              "description": "Maximum environment where the profile is allowed."
+            },
+            "requiredFeatures": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "uniqueItems": true,
+              "description": "Features that MUST be enabled for the profile."
+            },
+            "forbiddenFeatures": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "uniqueItems": true,
+              "description": "Features that MUST NOT be enabled for the profile."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "description": "Additional per-profile requirements and restrictions."
+    },
+    "customRequirements": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Organization-specific requirements to apply when profile=CUSTOM."
+    },
+    "auditSettings": {
+      "type": "object",
+      "properties": {
+        "logPolicyViolations": {
+          "type": "boolean",
+          "default": true,
+          "description": "Emit log entries when configurations violate policy."
+        },
+        "enforceStrictMode": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, applications MUST fail fast when policy violations occur."
+        },
+        "requirePolicyFile": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, all applications MUST provide a policy file."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "allowedProfiles"
+  ],
+  "additionalProperties": false,
+  "examples": [
+    {
+      "version": "1.0.0",
+      "allowedProfiles": [
+        "SIMPLE",
+        "STRUCTURED",
+        "ENTERPRISE"
+      ],
+      "requiredProfiles": {
+        "workhorse": [
+          "ENTERPRISE"
+        ],
+        "service": [
+          "STRUCTURED",
+          "ENTERPRISE"
+        ],
+        "cli": [
+          "SIMPLE",
+          "STRUCTURED"
+        ]
+      },
+      "environmentRules": {
+        "production": [
+          "STRUCTURED",
+          "ENTERPRISE"
+        ],
+        "staging": [
+          "SIMPLE",
+          "STRUCTURED",
+          "ENTERPRISE"
+        ],
+        "development": [
+          "SIMPLE",
+          "STRUCTURED",
+          "ENTERPRISE"
+        ]
+      },
+      "profileRequirements": {
+        "ENTERPRISE": {
+          "requiredFeatures": [
+            "correlation",
+            "middleware",
+            "throttling"
+          ],
+          "minEnvironment": "staging"
+        },
+        "SIMPLE": {
+          "forbiddenFeatures": [
+            "correlation",
+            "middleware",
+            "throttling"
+          ],
+          "maxEnvironment": "development"
+        }
+      },
+      "auditSettings": {
+        "logPolicyViolations": true,
+        "enforceStrictMode": false,
+        "requirePolicyFile": false
+      }
+    },
+    {
+      "version": "1.0.0",
+      "allowedProfiles": [
+        "ENTERPRISE"
+      ],
+      "requiredProfiles": {
+        "*": [
+          "ENTERPRISE"
+        ]
+      },
+      "environmentRules": {
+        "*": [
+          "ENTERPRISE"
+        ]
+      },
+      "auditSettings": {
+        "logPolicyViolations": true,
+        "enforceStrictMode": true,
+        "requirePolicyFile": true
+      }
+    }
+  ]
+}

package/schemas/crucible-ts/observability/logging/v1.0.0/middleware-config.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/observability/logging/middleware-config-v1.0.0.json",
+  "title": "MiddlewareConfig",
+  "description": "Configuration for log event middleware (redaction, filtering, augmentation)",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "redaction",
+        "filter",
+        "augmentation",
+        "sampling",
+        "custom"
+      ],
+      "description": "Middleware type"
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether this middleware is active"
+    },
+    "priority": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Execution priority (lower runs first)"
+    },
+    "redaction": {
+      "$ref": "#/$defs/redactionConfig"
+    },
+    "filter": {
+      "$ref": "#/$defs/filterConfig"
+    },
+    "augmentation": {
+      "$ref": "#/$defs/augmentationConfig"
+    },
+    "sampling": {
+      "$ref": "#/$defs/samplingConfig"
+    }
+  },
+  "required": [
+    "type"
+  ],
+  "$defs": {
+    "redactionConfig": {
+      "type": "object",
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Regex patterns to redact (e.g., credit cards, emails)"
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Field names to redact completely"
+        },
+        "replacement": {
+          "type": "string",
+          "default": "[REDACTED]",
+          "description": "Replacement text for redacted content"
+        }
+      }
+    },
+    "filterConfig": {
+      "type": "object",
+      "properties": {
+        "minLevel": {
+          "type": "string",
+          "enum": [
+            "TRACE",
+            "DEBUG",
+            "INFO",
+            "WARN",
+            "ERROR",
+            "FATAL"
+          ],
+          "description": "Filter out events below this level (deprecated: use severityFilter for operator-based filtering)"
+        },
+        "severityFilter": {
+          "$ref": "severity-filter.schema.json",
+          "description": "Advanced severity filtering with comparison operators"
+        },
+        "exclude": {
+          "type": "object",
+          "properties": {
+            "loggers": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Logger names to exclude"
+            },
+            "components": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Components to exclude"
+            }
+          },
+          "description": "Exclusion rules"
+        }
+      }
+    },
+    "augmentationConfig": {
+      "type": "object",
+      "properties": {
+        "fields": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Fields to add to all events"
+        },
+        "dynamic": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Names of dynamic field providers (implementation-specific)"
+        }
+      }
+    },
+    "samplingConfig": {
+      "type": "object",
+      "properties": {
+        "rate": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Sampling rate (0.0 to 1.0)"
+        },
+        "byLevel": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "description": "Per-level sampling rates"
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "type": "redaction",
+      "enabled": true,
+      "priority": 10,
+      "redaction": {
+        "patterns": [
+          "\\d{16}",
+          "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
+        ],
+        "fields": [
+          "password",
+          "token",
+          "apiKey"
+        ],
+        "replacement": "[REDACTED]"
+      }
+    },
+    {
+      "type": "sampling",
+      "enabled": true,
+      "priority": 5,
+      "sampling": {
+        "rate": 0.1,
+        "byLevel": {
+          "ERROR": 1.0,
+          "FATAL": 1.0,
+          "DEBUG": 0.01
+        }
+      }
+    }
+  ]
+}

package/schemas/crucible-ts/observability/logging/v1.0.0/severity-filter.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/observability/logging/severity-filter-v1.0.0.json",
+  "title": "SeverityFilter",
+  "description": "Severity-based filtering with comparison operators for log event processing",
+  "type": "object",
+  "properties": {
+    "operator": {
+      "$ref": "definitions.schema.json#/$defs/comparisonOperator"
+    },
+    "level": {
+      "$ref": "definitions.schema.json#/$defs/severityName"
+    }
+  },
+  "required": [
+    "operator",
+    "level"
+  ],
+  "examples": [
+    {
+      "operator": "GE",
+      "level": "WARN",
+      "description": "Filter events with severity >= WARN (includes WARN, ERROR, FATAL)"
+    },
+    {
+      "operator": "LT",
+      "level": "ERROR",
+      "description": "Filter events with severity < ERROR (includes TRACE, DEBUG, INFO, WARN)"
+    },
+    {
+      "operator": "EQ",
+      "level": "ERROR",
+      "description": "Filter only ERROR events"
+    }
+  ],
+  "additionalProperties": false,
+  "$comment": "Implementation MUST convert severityName to severityLevel for numeric comparison. See definitions.schema.json#/$defs/severityMapping for canonical name→level mapping."
+}

package/schemas/crucible-ts/observability/metrics/v1.0.0/metrics-event.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/observability/metrics/v1.0.0/metrics-event.schema.json",
+  "title": "Fulmen Metrics Event",
+  "description": "Schema for basic telemetry export (counter/gauge/histogram) emitted by Fulmen helper libraries.",
+  "type": "object",
+  "properties": {
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC3339 timestamp of metric emission."
+    },
+    "name": {
+      "$ref": "../../../../config/taxonomy/metrics.yaml#/$defs/metricName",
+      "description": "Metric identifier drawn from the metrics taxonomy."
+    },
+    "value": {
+      "description": "Measurement payload (scalar counter/gauge or histogram summary).",
+      "oneOf": [
+        {
+          "type": "number",
+          "description": "Scalar measurement (e.g., counter increment, instantaneous gauge)."
+        },
+        {
+          "type": "object",
+          "description": "Histogram summary payload.",
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "sum": {
+              "type": "number"
+            },
+            "buckets": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "le": {
+                    "type": "number",
+                    "description": "Upper bound (less-than-or-equal) for the bucket."
+                  },
+                  "count": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Cumulative count up to and including this bucket."
+                  }
+                },
+                "required": [
+                  "le",
+                  "count"
+                ],
+                "additionalProperties": false
+              },
+              "description": "Ordered buckets with cumulative counts (OTLP-compatible)."
+            }
+          },
+          "required": [
+            "count",
+            "sum",
+            "buckets"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "tags": {
+      "type": "object",
+      "description": "Key/value dimensions applied to the metric event.",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "unit": {
+      "$ref": "../../../../config/taxonomy/metrics.yaml#/$defs/metricUnit",
+      "description": "Metric unit (defaults to taxonomy default when omitted)."
+    }
+  },
+  "required": [
+    "timestamp",
+    "name",
+    "value"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/pathfinder/v1.0.0/README.md

@@ -0,0 +1,104 @@
+# Pathfinder Schemas v1.0.0
+
+JSON Schemas for the Pathfinder file discovery API, ensuring consistent data structures across Go, TypeScript, Python, and other language implementations.
+
+## Schemas
+
+### find-query.schema.json
+
+**Purpose**: Query parameters for file discovery operations
+
+**Key Properties**:
+
+- `root`: Root directory to search from (required)
+- `include`: Glob patterns to include (array of strings)
+- `exclude`: Glob patterns to exclude (array of strings)
+- `maxDepth`: Maximum directory depth (integer, min 0, default 0)
+- `followSymlinks`: Whether to follow symbolic links (boolean, default false)
+- `includeHidden`: Whether to include hidden files/directories (boolean, default false)
+
+### finder-config.schema.json
+
+**Purpose**: Configuration for the Finder component
+
+**Key Properties**:
+
+- `maxWorkers`: Maximum concurrent workers (integer, min 1)
+- `cacheEnabled`: Whether caching is enabled (boolean)
+- `cacheTTL`: Cache time-to-live in seconds (integer, min 0)
+- `constraint`: Path constraint configuration (PathConstraint object)
+- `loaderType`: Type of loader to use (string)
+
+### path-result.schema.json
+
+**Purpose**: Structure of discovery results returned by Pathfinder
+
+**Key Properties**:
+
+- `relativePath`: Path relative to discovery root (string)
+- `sourcePath`: Absolute source path (string)
+- `logicalPath`: Logical mapping path (string)
+- `loaderType`: Type of loader used (string)
+- `metadata`: Additional file metadata (Metadata object)
+
+### error-response.schema.json
+
+**Purpose**: Standardized error response structure for consistent error handling
+
+**Key Properties**:
+
+- `code`: Error code identifier (string, required)
+- `message`: Human-readable error message (string, required)
+- `details`: Additional error details (object)
+- `path`: Path that caused the error (string, optional)
+- `timestamp`: When the error occurred (date-time string, optional)
+
+### path-constraint.schema.json
+
+**Purpose**: Path constraint configuration for defining safety boundaries
+
+**Key Properties**:
+
+- `root`: Root path for the constraint boundary (string, required)
+- `type`: Type of constraint - `repository`, `workspace`, or `cloud` (required)
+- `enforcementLevel`: Strictness - `strict`, `warn`, or `permissive` (required)
+- `allowedPatterns`: Additional allowed path patterns (array of strings)
+- `blockedPatterns`: Blocked path patterns (array of strings)
+
+### metadata.schema.json
+
+**Purpose**: Flexible metadata structure for path results
+
+**Key Properties**:
+
+- `size`: File size in bytes (integer)
+- `modified`: Last modification timestamp (date-time string)
+- `permissions`: File permissions (string, octal or symbolic)
+- `mimeType`: MIME type of the file (string)
+- `encoding`: Character encoding if applicable (string)
+- `checksum`: File checksum/hash (string)
+- `tags`: User-defined tags (array of strings)
+- `custom`: Custom metadata fields (object)
+
+## Usage
+
+These schemas are used across all Fulmen implementations:
+
+- `gofulmen/pathfinder`: Go implementation
+- `tsfulmen/pathfinder`: TypeScript implementation
+- `pyfulmen/pathfinder`: Python implementation (future)
+
+**Purpose**:
+
+- Validate API inputs and outputs
+- Generate type definitions and validation code
+- Ensure API consistency across languages
+- Provide documentation for API consumers
+
+## Versioning
+
+Schemas follow semantic versioning. Breaking changes will increment the major version number.
+
+## Naming Conventions
+
+All property names use **camelCase** for consistency with JSON/JavaScript conventions.

package/schemas/crucible-ts/pathfinder/v1.0.0/error-response.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/pathfinder/error-response-v1.0.0.json",
+  "title": "ErrorResponse",
+  "description": "Standardized error response structure for pathfinder operations",
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Error code identifier"
+    },
+    "message": {
+      "type": "string",
+      "description": "Human-readable error message"
+    },
+    "details": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Additional error details"
+    },
+    "path": {
+      "type": "string",
+      "description": "Path that caused the error (if applicable)"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the error occurred"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ]
+}