@fulmenhq/tsfulmen 0.1.6

package/config/crucible-ts/library/v1.0.0/module-manifest.yaml

@@ -0,0 +1,179 @@
+# Fulmen helper module manifest (v2025.10.3)
+version: "2025.10.3"
+lastUpdated: "2025-10-23"
+modules:
+  - id: config-path-api
+    tier: core
+    requirement: mandatory
+    description: Platform-aware helpers for Fulmen config/data/cache directories.
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 90
+      - language: typescript
+        target: 85
+  - id: three-layer-config
+    tier: core
+    requirement: mandatory
+    description: Load configuration from defaults, user overrides, and runtime inputs.
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 90
+      - language: typescript
+        target: 85
+  - id: schema-validation
+    tier: core
+    requirement: mandatory
+    description: Schema discovery, validation helpers, and goneat integrations.
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 90
+      - language: typescript
+        target: 85
+  - id: crucible-shim
+    tier: core
+    requirement: mandatory
+    description: Accessors for embedded Crucible assets (schemas, docs, templates).
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 90
+      - language: typescript
+        target: 85
+  - id: fuldx-bootstrap
+    tier: core
+    requirement: mandatory
+    description: FulDX installation workflow and tooling manifest helpers.
+    coverage:
+      - language: go
+        target: 90
+      - language: python
+        target: 90
+      - language: typescript
+        target: 80
+  - id: ssot-sync
+    tier: core
+    requirement: mandatory
+    description: FulDX-driven sync of Crucible assets and index regeneration.
+    coverage:
+      - language: go
+        target: 90
+      - language: python
+        target: 90
+      - language: typescript
+        target: 80
+  - id: observability-logging
+    tier: core
+    requirement: mandatory
+    description: Structured logging helpers aligned with Crucible logging standards.
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 95
+      - language: typescript
+        target: 90
+  - id: foundry
+    tier: core
+    requirement: mandatory
+    description: >
+      Common reference data, patterns, and text utilities including pattern catalogs (regex/glob/literal), HTTP status groups, country codes, MIME types, text similarity (Levenshtein distance/scoring), and normalization (Unicode case folding, accent stripping).
+
+    capabilities:
+      - country_codes
+      - http_statuses
+      - mime_types
+      - patterns
+      - text_similarity
+      - text_normalization
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 95
+      - language: typescript
+        target: 95
+  - id: error-handling-propagation
+    tier: core
+    requirement: mandatory
+    description: Uniform error wrapping built on the pathfinder envelope with optional telemetry fields.
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 95
+      - language: typescript
+        target: 90
+  - id: docscribe
+    tier: core
+    requirement: mandatory
+    description: Standalone lightweight processing for markdown/YAML documentation from any source with frontmatter extraction and header parsing.
+    coverage:
+      - language: go
+        target: 90
+      - language: python
+        target: 95
+      - language: typescript
+        target: 90
+  - id: fulhash
+    tier: core
+    requirement: mandatory
+    description: Shared hashing API for block and streaming checksums supporting xxh3-128 (fast) and sha256 (secure) algorithms with consistent metadata formatting.
+    capabilities:
+      - block_hashing
+      - streaming_hashing
+      - metadata_formatting
+      - checksum_parsing
+    coverage:
+      - language: go
+        target: 95
+      - language: python
+        target: 95
+      - language: typescript
+        target: 95
+  - id: cloud-storage
+    tier: extension
+    requirement: optional
+    description: Unified helpers for S3, GCS, and Azure Blob operations.
+  - id: pathfinder
+    tier: extension
+    requirement: optional
+    description: Filesystem scanning utilities with include/exclude support.
+  - id: ascii-helpers
+    tier: extension
+    requirement: optional
+    description: Console formatting utilities (tables, boxes, progress displays).
+  - id: telemetry-metrics
+    tier: extension
+    requirement: recommended
+    description: Basic counter/histogram export aligned with the observability logging module.
+    coverage:
+      - language: go
+        target: 85
+      - language: python
+        target: 80
+      - language: typescript
+        target: 80
+languageOverrides:
+  - language: rust
+    planned:
+      - config-path-api
+      - schema-validation
+      - crucible-shim
+      - foundry
+    notes: "rsfulmen planned post-logging stabilization; extensions deferred."
+  - language: csharp
+    planned:
+      - config-path-api
+      - schema-validation
+      - crucible-shim
+      - foundry
+    unsupported:
+      - ascii-helpers
+    notes: "Console helpers rely on ANSI assumptions not yet mapped for Windows terminals."

package/config/crucible-ts/repository/app-identity/app-identity.example.yaml

@@ -0,0 +1,42 @@
+# Fulmen Application Identity - Complete Example
+# Location: .fulmen/app.yaml
+# Schema: schemas/config/repository/app-identity/v1.0.0/app-identity.schema.json
+# Documentation: docs/standards/library/modules/app-identity.md
+app:
+  # Binary/executable name (lowercase kebab-case, 2-64 chars)
+  binary_name: percheron
+  # Vendor namespace (lowercase alphanumeric, no hyphens)
+  vendor: fulmenhq
+  # Environment variable prefix (UPPERCASE, must end with underscore)
+  env_prefix: PERCHERON_
+  # Config directory name (usually matches binary_name)
+  config_name: percheron
+  # One-line description (10-200 chars)
+  description: Production-ready Python HTTP workhorse with observability
+# Optional metadata (all fields optional, extensible)
+metadata:
+  # Primary project URL
+  project_url: https://github.com/fulmenhq/forge-workhorse-percheron
+  # Support/contact email
+  support_email: support@fulmenhq.io
+  # SPDX license identifier
+  license: MIT
+  # Repository category from Fulmen taxonomy
+  repository_category: workhorse
+  # Telemetry namespace for metrics/logging (defaults to binary_name if omitted)
+  telemetry_namespace: percheron
+  # Python-specific packaging metadata (for PyPI projects)
+  python:
+    # PyPI distribution name (kebab-case allowed)
+    distribution_name: percheron
+    # Python import package name (underscores allowed)
+    package_name: percheron
+    # Console script entry points
+    console_scripts:
+      - name: percheron
+        entry_point: percheron.cli:main
+      - name: percheron-validate
+        entry_point: percheron.validation:cli
+
+# Additional custom fields allowed for extensibility
+# custom_field: value

package/config/crucible-ts/repository/app-identity/fixtures/invalid/invalid-binary-name.yaml

@@ -0,0 +1,7 @@
+# Invalid: binary_name contains uppercase (must be lowercase)
+app:
+  binary_name: MyApp
+  vendor: acmecorp
+  env_prefix: MYAPP_
+  config_name: myapp
+  description: Binary name has invalid uppercase characters

package/config/crucible-ts/repository/app-identity/fixtures/invalid/invalid-env-prefix.yaml

@@ -0,0 +1,7 @@
+# Invalid: env_prefix missing trailing underscore
+app:
+  binary_name: myapp
+  vendor: acmecorp
+  env_prefix: MYAPP
+  config_name: myapp
+  description: Environment prefix missing required trailing underscore

package/config/crucible-ts/repository/app-identity/fixtures/invalid/invalid-vendor.yaml

@@ -0,0 +1,7 @@
+# Invalid: vendor contains hyphens (must be alphanumeric only)
+app:
+  binary_name: myapp
+  vendor: acme-corp
+  env_prefix: MYAPP_
+  config_name: myapp
+  description: Vendor contains invalid hyphen characters

package/config/crucible-ts/repository/app-identity/fixtures/invalid/malformed-yaml.yaml

@@ -0,0 +1,8 @@
+# Invalid: Malformed YAML syntax
+app:
+  binary_name: myapp
+  vendor: acmecorp
+  env_prefix: MYAPP_
+  config_name: myapp
+  description: This line is missing closing quote and will cause parse error
+  invalid_key without colon

package/config/crucible-ts/repository/app-identity/fixtures/invalid/missing-required.yaml

@@ -0,0 +1,6 @@
+# Invalid: Missing required field (binary_name)
+app:
+  vendor: acmecorp
+  env_prefix: MYAPP_
+  config_name: myapp
+  description: Missing binary_name field

package/config/crucible-ts/repository/app-identity/fixtures/valid/complete.yaml

@@ -0,0 +1,20 @@
+# Complete application identity - all fields including metadata
+app:
+  binary_name: percheron
+  vendor: fulmenhq
+  env_prefix: PERCHERON_
+  config_name: percheron
+  description: Production-ready Python HTTP workhorse with observability
+metadata:
+  project_url: https://github.com/fulmenhq/forge-workhorse-percheron
+  support_email: support@fulmenhq.io
+  license: MIT
+  repository_category: workhorse
+  telemetry_namespace: percheron
+  python:
+    distribution_name: percheron
+    package_name: percheron
+    console_scripts:
+      - name: percheron
+        entry_point: percheron.cli:main
+  custom_field: allowed for extensibility

package/config/crucible-ts/repository/app-identity/fixtures/valid/minimal.yaml

@@ -0,0 +1,7 @@
+# Minimal valid application identity - bare minimum required fields
+app:
+  binary_name: myapp
+  vendor: acmecorp
+  env_prefix: MYAPP_
+  config_name: myapp
+  description: Minimal valid application identity

package/config/crucible-ts/repository/app-identity/fixtures/valid/monorepo-api.yaml

@@ -0,0 +1,10 @@
+# Identity for API server in monorepo
+app:
+  binary_name: myproject-api
+  vendor: acmecorp
+  env_prefix: MYPROJECT_API_
+  config_name: myproject-api
+  description: API server component of myproject monorepo
+metadata:
+  repository_category: service
+  telemetry_namespace: myproject_api

package/config/crucible-ts/repository/app-identity/fixtures/valid/monorepo-worker.yaml

@@ -0,0 +1,10 @@
+# Identity for worker in monorepo
+app:
+  binary_name: myproject-worker
+  vendor: acmecorp
+  env_prefix: MYPROJECT_WORKER_
+  config_name: myproject-worker
+  description: Background worker component of myproject monorepo
+metadata:
+  repository_category: service
+  telemetry_namespace: myproject_worker

package/config/crucible-ts/repository/app-identity/parity-snapshot.json

@@ -0,0 +1,125 @@
+{
+  "schema_version": "v1.0.0",
+  "description": "Canonical parity snapshot for app-identity parser behavior. All language implementations (Go, Python, TypeScript) must produce identical results for these test cases.",
+  "test_cases": {
+    "valid": {
+      "minimal": {
+        "input_file": "fixtures/valid/minimal.yaml",
+        "expected_output": {
+          "binary_name": "myapp",
+          "vendor": "acmecorp",
+          "env_prefix": "MYAPP_",
+          "config_name": "myapp",
+          "description": "Minimal valid application identity",
+          "metadata": {}
+        },
+        "validation_result": "pass"
+      },
+      "complete": {
+        "input_file": "fixtures/valid/complete.yaml",
+        "expected_output": {
+          "binary_name": "percheron",
+          "vendor": "fulmenhq",
+          "env_prefix": "PERCHERON_",
+          "config_name": "percheron",
+          "description": "Production-ready Python HTTP workhorse with observability",
+          "metadata": {
+            "project_url": "https://github.com/fulmenhq/forge-workhorse-percheron",
+            "support_email": "support@fulmenhq.io",
+            "license": "MIT",
+            "repository_category": "workhorse",
+            "telemetry_namespace": "percheron",
+            "python": {
+              "distribution_name": "percheron",
+              "package_name": "percheron",
+              "console_scripts": [
+                {
+                  "name": "percheron",
+                  "entry_point": "percheron.cli:main"
+                }
+              ]
+            },
+            "custom_field": "allowed for extensibility"
+          }
+        },
+        "validation_result": "pass"
+      },
+      "monorepo_api": {
+        "input_file": "fixtures/valid/monorepo-api.yaml",
+        "expected_output": {
+          "binary_name": "myproject-api",
+          "vendor": "acmecorp",
+          "env_prefix": "MYPROJECT_API_",
+          "config_name": "myproject-api",
+          "description": "API server component of myproject monorepo",
+          "metadata": {
+            "repository_category": "service",
+            "telemetry_namespace": "myproject_api"
+          }
+        },
+        "validation_result": "pass"
+      },
+      "monorepo_worker": {
+        "input_file": "fixtures/valid/monorepo-worker.yaml",
+        "expected_output": {
+          "binary_name": "myproject-worker",
+          "vendor": "acmecorp",
+          "env_prefix": "MYPROJECT_WORKER_",
+          "config_name": "myproject-worker",
+          "description": "Background worker component of myproject monorepo",
+          "metadata": {
+            "repository_category": "service",
+            "telemetry_namespace": "myproject_worker"
+          }
+        },
+        "validation_result": "pass"
+      }
+    },
+    "invalid": {
+      "missing_required": {
+        "input_file": "fixtures/invalid/missing-required.yaml",
+        "expected_error": {
+          "type": "ValidationError",
+          "field": "app.binary_name",
+          "message": "required field missing"
+        },
+        "validation_result": "fail"
+      },
+      "invalid_binary_name": {
+        "input_file": "fixtures/invalid/invalid-binary-name.yaml",
+        "expected_error": {
+          "type": "ValidationError",
+          "field": "app.binary_name",
+          "message": "must be lowercase"
+        },
+        "validation_result": "fail"
+      },
+      "invalid_env_prefix": {
+        "input_file": "fixtures/invalid/invalid-env-prefix.yaml",
+        "expected_error": {
+          "type": "ValidationError",
+          "field": "app.env_prefix",
+          "message": "must end with underscore"
+        },
+        "validation_result": "fail"
+      },
+      "invalid_vendor": {
+        "input_file": "fixtures/invalid/invalid-vendor.yaml",
+        "expected_error": {
+          "type": "ValidationError",
+          "field": "app.vendor",
+          "message": "must be alphanumeric only"
+        },
+        "validation_result": "fail"
+      },
+      "malformed_yaml": {
+        "input_file": "fixtures/invalid/malformed-yaml.yaml",
+        "expected_error": {
+          "type": "ParseError",
+          "message": "invalid YAML syntax"
+        },
+        "validation_result": "fail"
+      }
+    }
+  }
+}

package/config/crucible-ts/server/management/server-management.yaml

@@ -0,0 +1,141 @@
+$schema: https://schemas.fulmenhq.dev/server/management/v1.0.0/server-management.schema.json
+description: Default server management configuration for Fulmen web templates and applications
+version: v1.0.0
+# Environment variable prefix - typically derived from application identity
+# Example: FULMEN_PULSAR for Forge Codex Pulsar
+# Results in env vars like: FULMEN_PULSAR_DEV_PORT, FULMEN_PULSAR_A11Y_RANGE_MIN
+envPrefix: FULMEN_APP
+# Standard configuration classes for server orchestration
+configurations:
+  # Local development server
+  dev:
+    preferredPort: 4321
+    range:
+      min: 4321
+      max: 4322
+    healthCheck:
+      method: GET
+      path: /
+      timeout: 5000
+      retries: 3
+      interval: 1000
+    exitBehavior:
+      portInUse: 11 # EXIT_PORT_IN_USE
+      healthCheckFailed: 50 # EXIT_HEALTH_CHECK_FAILED
+      startupTimeout: 52 # EXIT_TIMEOUT
+    envOverrides:
+      - FULMEN_APP_DEV_PORT
+      - FULMEN_APP_DEV_RANGE_MIN
+      - FULMEN_APP_DEV_RANGE_MAX
+    pidFile: .server/dev.pid
+    logFile: .server/dev.log
+  # Test/CI server
+  test:
+    preferredPort: 4380
+    range:
+      min: 4380
+      max: 4389
+    healthCheck:
+      method: GET
+      path: /health
+      timeout: 3000
+      retries: 2
+      interval: 500
+    exitBehavior:
+      portInUse: 11
+      healthCheckFailed: 50
+      startupTimeout: 52
+    envOverrides:
+      - FULMEN_APP_TEST_PORT
+      - FULMEN_APP_TEST_RANGE_MIN
+      - FULMEN_APP_TEST_RANGE_MAX
+    pidFile: .server/test.pid
+    logFile: .server/test.log
+  # Accessibility testing server
+  a11y:
+    preferredPort: 4323
+    range:
+      min: 4323
+      max: 4340
+    healthCheck:
+      method: GET
+      path: /
+      timeout: 5000
+      retries: 3
+      interval: 1000
+    exitBehavior:
+      portInUse: 11
+      healthCheckFailed: 50
+      startupTimeout: 52
+    envOverrides:
+      - FULMEN_APP_A11Y_PORT
+      - FULMEN_APP_A11Y_RANGE_MIN
+      - FULMEN_APP_A11Y_RANGE_MAX
+    pidFile: .server/a11y.pid
+    logFile: .server/a11y.log
+  # Preview/staging server
+  preview:
+    preferredPort: 4341
+    range:
+      min: 4341
+      max: 4350
+    healthCheck:
+      method: GET
+      path: /health
+      timeout: 10000
+      retries: 5
+      interval: 2000
+    exitBehavior:
+      portInUse: 11
+      healthCheckFailed: 50
+      startupTimeout: 52
+    envOverrides:
+      - FULMEN_APP_PREVIEW_PORT
+      - FULMEN_APP_PREVIEW_RANGE_MIN
+      - FULMEN_APP_PREVIEW_RANGE_MAX
+    pidFile: .server/preview.pid
+    logFile: .server/preview.log
+  # Production-like server for final verification
+  prod_like:
+    preferredPort: 4351
+    range:
+      min: 4351
+      max: 4360
+    healthCheck:
+      method: HEAD
+      path: /health
+      timeout: 10000
+      retries: 5
+      interval: 2000
+    exitBehavior:
+      portInUse: 11
+      healthCheckFailed: 50
+      startupTimeout: 52
+    envOverrides:
+      - FULMEN_APP_PROD_LIKE_PORT
+      - FULMEN_APP_PROD_LIKE_RANGE_MIN
+      - FULMEN_APP_PROD_LIKE_RANGE_MAX
+    pidFile: .server/prod_like.pid
+    logFile: .server/prod_like.log
+
+# Example of additional custom configurations (must use x- prefix)
+# additionalConfigurations:
+#   x-storybook:
+#     preferredPort: 6006
+#     range:
+#       min: 6006
+#       max: 6010
+#     healthCheck:
+#       method: GET
+#       path: /
+#       timeout: 5000
+#       retries: 3
+#       interval: 1000
+#     exitBehavior:
+#       portInUse: 11
+#       healthCheckFailed: 50
+#       startupTimeout: 52
+#     envOverrides:
+#       - FULMEN_APP_STORYBOOK_PORT
+#     pidFile: .server/x-storybook.pid
+#     logFile: .server/x-storybook.log

package/config/crucible-ts/sync/README.md

@@ -0,0 +1,13 @@
+---
+title: "Sync Keys Metadata"
+description: "Canonical keys for sync manifests"
+author: "Schema Cartographer"
+date: "2025-10-03"
+last_updated: "2025-10-03"
+status: "draft"
+tags: ["sync", "config", "metadata"]
+---
+
+`sync-keys.yaml` publishes recommended keys for sync consumers. Each key describes a logical bundle of assets and carries tags (e.g., docs, schemas, language scopes) so tooling can filter appropriately.
+
+See `docs/guides/sync-producers-guide.md` for publishing guidance.

package/config/crucible-ts/sync/sync-keys.yaml

@@ -0,0 +1,74 @@
+version: "2025.10.0"
+keys:
+  - id: crucible.docs
+    description: "General documentation"
+    basePath: docs/
+    recommendedOutput: docs/crucible
+    tags: [docs]
+  - id: crucible.schemas.terminal
+    description: "Terminal schemas"
+    basePath: schemas/terminal/
+    recommendedOutput: schemas/terminal
+    tags: [schemas]
+  - id: crucible.schemas.observability.logging
+    description: "Logging schemas"
+    basePath: schemas/observability/logging/
+    recommendedOutput: schemas/observability/logging
+    tags: [schemas, logging]
+  - id: crucible.config.terminal
+    description: "Terminal config defaults"
+    basePath: config/terminal/
+    recommendedOutput: config/terminal
+    tags: [config]
+  - id: crucible.lang.go
+    description: "Go language wrapper assets"
+    basePath: lang/go/
+    recommendedOutput: lang/go
+    tags: [language, 'lang:go']
+    metadata:
+      sourceRepo: https://github.com/fulmenhq/crucible.git
+      sourcePathBase: lang/go
+  - id: crucible.lang.go.dev
+    description: "Go language wrapper assets (development convenience)"
+    basePath: lang/go
+    recommendedOutput: lang/go
+    tags: [language, 'lang:go', dev]
+    metadata:
+      sourceRepo: local
+      notes: "Use local replace directive during development; ensure CI fails if manifest references local paths."
+  - id: crucible.lang.ts
+    description: "TypeScript language wrapper assets"
+    basePath: lang/typescript/
+    recommendedOutput: lang/typescript
+    tags: [language, 'lang:ts']
+    metadata:
+      sourceRepo: https://github.com/fulmenhq/crucible.git
+      sourcePathBase: lang/typescript
+  - id: crucible.lang.ts.dev
+    description: "TypeScript language wrapper assets (development convenience)"
+    basePath: lang/typescript
+    recommendedOutput: lang/typescript
+    tags: [language, 'lang:ts', dev]
+    metadata:
+      sourceRepo: local
+      notes: "Use local path overrides during development; unit tests should prevent dev-only manifests from committing."
+  - id: crucible.content.binary-embed-manifest
+    description: "Binary embed manifest schemas"
+    basePath: schemas/content/binary-embed-manifest/
+    recommendedOutput: schemas/content/binary-embed-manifest
+    tags: [schemas, content]
+  - id: crucible.content.embed-manifest
+    description: "Advanced embed manifest schemas"
+    basePath: schemas/content/embed-manifest/
+    recommendedOutput: schemas/content/embed-manifest
+    tags: [schemas, content, advanced]
+  - id: crucible.schemas.config.repository.app-identity
+    description: "Application identity schema"
+    basePath: schemas/config/repository/app-identity/
+    recommendedOutput: schemas/config/repository/app-identity
+    tags: [schemas, config, app-identity]
+  - id: crucible.config.repository.app-identity
+    description: "Application identity config examples and fixtures"
+    basePath: config/repository/app-identity/
+    recommendedOutput: config/repository/app-identity
+    tags: [config, app-identity, fixtures]