@fulmenhq/tsfulmen 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -12,6 +12,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _No unreleased changes._
 
+---
+
+## [0.2.4] - 2026-02-01
+
+### Infrastructure
+
+- **Automated Release Workflow** - Added GitHub Actions workflow with npm OIDC trusted publishing
+  - Automatic GitHub release creation on tag push
+  - npm package publishing via OIDC (no NPM_TOKEN secrets required)
+  - Automatic provenance attestation for supply chain security
+  - Deployment protection with manual approval gate
+  - Post-release verification (npm install + smoke test)
+  - No manual npm publish or GitHub release creation required
+
+---
+
+## [0.2.3] - 2026-01-28
+
+### Changed
+
+- **Vitest Upgrade** - Updated test framework from v2.1.9 to v4.0.18
+  - Resolves 70 Go stdlib CVEs in bundled esbuild binaries (dev/CI dependencies only)
+  - Critical vulnerabilities reduced from 6 to 0
+  - Test execution 32% faster (38s vs 56s)
+  - No breaking changes to test suite
+
+### Security
+
+- **CVE Remediation** - Eliminated critical Go 1.20.12 vulnerabilities in vite's nested esbuild
+  - Before: 94 findings (6 critical, 34 high, 54 medium)
+  - After: 24 findings (0 critical, 10 high, 14 medium)
+  - Remaining findings are recent 2025 CVEs in Go 1.25.5 (not legacy issues)
+  - **Note**: All vulnerabilities are in dev/CI tooling (esbuild binaries); production code surface has 0 findings
+
+---
+
+## [0.2.2] - 2026-01-28
+
+**Skipped** - Version number consumed by npm publish workflow reading local package.json before version bump completed. No package published to npm under this version.
+
+---
+
 ## [0.2.1] - 2026-01-27
 
 ### Changed

package/README.md

@@ -8,7 +8,7 @@ Every team writes their own HTTP status helpers, exit code enums, and country co
 - **Cross-language parity**: Same exit codes, signals, and schemas as gofulmen, rsfulmen, pyfulmen
 - **Type-safe**: Full TypeScript types with strict mode throughout
 
-**Lifecycle Phase**: `beta` | **Version**: 0.2.1 | **Test Coverage**: 71%
+**Lifecycle Phase**: `beta` | **Version**: 0.2.3 | **Test Coverage**: 71%
 
 **Install**: `bun add @fulmenhq/tsfulmen` (or `npm install @fulmenhq/tsfulmen`)
 
@@ -44,6 +44,7 @@ Every team writes their own HTTP status helpers, exit code enums, and country co
 - ✅ **Application Identity** - .fulmen/app.yaml discovery with caching and validation (93 tests)
 - ✅ **Pathfinder** - Filesystem traversal, repository root discovery with security boundaries, checksums, and observability (70 tests)
 - ✅ **Three-Layer Config Loading** - Defaults → User → Env pattern with schema validation (6 tests)
+- ✅ **Workhorse Control-Plane** - Config reload endpoint, control discovery, runtime info for service orchestration
 
 ## Installation
 
@@ -299,13 +300,13 @@ console.log(hex.checksum); // "sha256:2cf24dba..."
 
 **Supported Formats**:
 
-| Binary         | Text                                     |
-| -------------- | ---------------------------------------- |
-| base64         | utf-8                                    |
-| base64url      | utf-16le, utf-16be                       |
-| base64_raw     | iso-8859-1, ascii                        |
-| hex            |                                          |
-| base32, base32hex |                                       |
+| Binary            | Text               |
+| ----------------- | ------------------ |
+| base64            | utf-8              |
+| base64url         | utf-16le, utf-16be |
+| base64_raw        | iso-8859-1, ascii  |
+| hex               |                    |
+| base32, base32hex |                    |
 
 **Features**: Padding control, line wrapping, whitespace handling, checksum computation (sha256, xxh3-128), structured `FulencodeError` with error codes.
 

package/dist/appidentity/index.d.ts

@@ -1,3 +1,5 @@
+import { I as Identity, L as LoadIdentityOptions } from '../types-Dv5TERCM.js';
+export { A as AppIdentity, a as IdentityMetadata, P as PythonMetadata, R as RepositoryCategory } from '../types-Dv5TERCM.js';
 import { F as FulmenError } from '../fulmen-error-B_kX8jSC.js';
 import { b as SchemaValidationDiagnostic } from '../types-DdoeE7F5.js';
 
@@ -28,113 +30,6 @@ declare const APP_IDENTITY_SCHEMA_ID = "config/repository/app-identity/v1.0.0/ap
  */
 declare const MAX_ANCESTOR_SEARCH_DEPTH = 20;
 
-/**
- * Application Identity Types
- *
- * TypeScript interfaces matching the Crucible app-identity schema v1.0.0
- */
-/**
- * Repository category taxonomy from Fulmen standards
- */
-type RepositoryCategory = "cli" | "workhorse" | "service" | "library" | "pipeline" | "codex" | "sdk";
-/**
- * Python-specific packaging metadata
- * Field names use snake_case to match Crucible schema
- */
-interface PythonMetadata {
-    readonly distribution_name?: string;
-    readonly package_name?: string;
-    readonly console_scripts?: ReadonlyArray<{
-        readonly name: string;
-        readonly entry_point: string;
-    }>;
-}
-/**
- * Required application identity fields
- *
- * All fields are readonly to enforce immutability
- * Field names use snake_case to match Crucible schema
- */
-interface AppIdentity {
-    /**
-     * Lowercase kebab-case binary/executable name
-     * Pattern: ^[a-z][a-z0-9-]{0,62}[a-z0-9]$
-     */
-    readonly binary_name: string;
-    /**
-     * Lowercase alphanumeric vendor namespace (no hyphens)
-     * Pattern: ^[a-z][a-z0-9]{0,62}[a-z0-9]$
-     */
-    readonly vendor: string;
-    /**
-     * Uppercase environment variable prefix (must end with _)
-     * Pattern: ^[A-Z][A-Z0-9_]*_$
-     */
-    readonly env_prefix: string;
-    /**
-     * Filesystem-safe config directory name
-     * Pattern: ^[a-z][a-z0-9-]{0,62}[a-z0-9]$
-     */
-    readonly config_name: string;
-    /**
-     * One-line application description (10-200 chars)
-     */
-    readonly description: string;
-}
-/**
- * Optional metadata fields
- *
- * Additional properties are allowed for extensibility
- * Field names use snake_case to match Crucible schema
- */
-interface IdentityMetadata {
-    readonly project_url?: string;
-    readonly support_email?: string;
-    readonly license?: string;
-    readonly repository_category?: RepositoryCategory;
-    readonly telemetry_namespace?: string;
-    readonly registry_id?: string;
-    readonly python?: PythonMetadata;
-    readonly [key: string]: unknown;
-}
-/**
- * Complete application identity document
- */
-interface Identity {
-    readonly app: AppIdentity;
-    readonly metadata?: IdentityMetadata;
-}
-/**
- * Options for loading identity
- */
-interface LoadIdentityOptions {
-    /**
-     * Explicit path override
-     * Highest priority in discovery algorithm
-     */
-    readonly path?: string;
-    /**
-     * Test injection - bypass filesystem and discovery
-     * Never cached
-     */
-    readonly identity?: Identity;
-    /**
-     * Starting directory for ancestor search
-     * Defaults to process.cwd()
-     */
-    readonly startDir?: string;
-    /**
-     * Force reload, bypass cache
-     * Useful for testing cache behavior
-     */
-    readonly skipCache?: boolean;
-    /**
-     * Skip schema validation (dangerous)
-     * Only use for testing or when identity is pre-validated
-     */
-    readonly skipValidation?: boolean;
-}
-
 /**
  * Embedded Identity Registration
  *
@@ -383,4 +278,31 @@ declare function clearIdentityCache(): void;
  */
 declare function loadIdentity(options?: LoadIdentityOptions): Promise<Identity>;
 
-export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, type AppIdentity, AppIdentityError, type ConfigIdentifiers, type Identity, type IdentityMetadata, type LoadIdentityOptions, MAX_ANCESTOR_SEARCH_DEPTH, type PythonMetadata, type RepositoryCategory, buildEnvVar, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };
+type RuntimeName = "bun" | "node" | "unknown";
+interface RuntimeInfo {
+    service: {
+        name: string;
+        vendor?: string;
+        version?: string;
+    };
+    runtime: {
+        name: RuntimeName;
+        version?: string;
+    };
+    platform: {
+        os: NodeJS.Platform;
+        arch: string;
+    };
+}
+interface BuildRuntimeInfoOptions {
+    identity?: Identity;
+    version?: string;
+    serviceName?: string;
+    vendor?: string;
+}
+/**
+ * Build a minimal runtime info payload suitable for discovery endpoints.
+ */
+declare function buildRuntimeInfo(options?: BuildRuntimeInfoOptions): RuntimeInfo;
+
+export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, AppIdentityError, type BuildRuntimeInfoOptions, type ConfigIdentifiers, Identity, LoadIdentityOptions, MAX_ANCESTOR_SEARCH_DEPTH, type RuntimeInfo, type RuntimeName, buildEnvVar, buildRuntimeInfo, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };

package/dist/appidentity/index.js

@@ -1,3 +1,4 @@
+import addFormats from 'ajv-formats';
 import { spawn } from 'child_process';
 import { readFile, writeFile, access, mkdir } from 'fs/promises';
 import { parse, stringify } from 'yaml';
@@ -8,7 +9,6 @@ import Ajv from 'ajv';
 import Ajv2019 from 'ajv/dist/2019';
 import Ajv2020 from 'ajv/dist/2020';
 import AjvDraft04 from 'ajv-draft-04';
-import addFormats from 'ajv-formats';
 import { Readable } from 'stream';
 import picomatch from 'picomatch';
 import { suggest as suggest$1, substringSimilarity, score as score$1, normalize as normalize$1, jaro_winkler, damerau_levenshtein, osa_distance, levenshtein } from '@3leaps/string-metrics-wasm';
@@ -36,6 +36,27 @@ var init_constants = __esm({
     MAX_ANCESTOR_SEARCH_DEPTH = 20;
   }
 });
+function applyFulmenAjvFormats(ajv, options = {}) {
+  const mode = options.mode ?? "fast";
+  const formats = options.formats ?? DEFAULT_FORMATS;
+  addFormats(ajv, { mode, formats });
+  return ajv;
+}
+var DEFAULT_FORMATS;
+var init_ajv_formats = __esm({
+  "src/schema/ajv-formats.ts"() {
+    DEFAULT_FORMATS = [
+      "date-time",
+      "email",
+      "hostname",
+      "ipv4",
+      "ipv6",
+      "uri",
+      "uri-reference",
+      "uuid"
+    ];
+  }
+});
 
 // src/schema/errors.ts
 var errors_exports = {};
@@ -1591,10 +1612,7 @@ function createAjv(dialect) {
     // Enable async schema loading for YAML references
     loadSchema: loadReferencedSchema
   });
-  addFormats(ajv, {
-    mode: "fast",
-    formats: ["date-time", "email", "hostname", "ipv4", "ipv6", "uri", "uri-reference"]
-  });
+  applyFulmenAjvFormats(ajv);
   return ajv;
 }
 async function getAjv(dialect) {
@@ -1840,6 +1858,7 @@ var ajvInstances, metaschemaReady, schemaCache;
 var init_validator = __esm({
   "src/schema/validator.ts"() {
     init_telemetry();
+    init_ajv_formats();
     init_errors();
     init_registry();
     init_utils();
@@ -3799,6 +3818,224 @@ var init_capabilities2 = __esm({
   }
 });
 
+// src/foundry/signals/config-reload-endpoint.ts
+function createConfigReloadEndpoint(options) {
+  const { loader, validator, onReload: onReload2, auth, rateLimit, logger, telemetry } = options;
+  return async (payload, req) => {
+    const correlationId = payload.correlation_id ?? generateCorrelationId();
+    const authResult = await auth(req);
+    if (!authResult.authenticated) {
+      if (logger) {
+        logger.warn("Config reload endpoint: authentication failed", {
+          correlation_id: correlationId,
+          reason: authResult.reason
+        });
+      }
+      if (telemetry) {
+        telemetry.emit("fulmen.config.http_endpoint.auth_failed", {
+          correlation_id: correlationId
+        });
+      }
+      return {
+        status: "error",
+        error: "authentication_failed",
+        message: authResult.reason || "Authentication required",
+        statusCode: 401
+      };
+    }
+    const identity = authResult.identity || "unknown";
+    if (rateLimit) {
+      const rateLimitResult = await rateLimit(identity);
+      if (!rateLimitResult.allowed) {
+        if (logger) {
+          logger.warn("Config reload endpoint: rate limit exceeded", {
+            correlation_id: correlationId,
+            identity
+          });
+        }
+        if (telemetry) {
+          telemetry.emit("fulmen.config.http_endpoint.rate_limited", {
+            correlation_id: correlationId
+          });
+        }
+        return {
+          status: "error",
+          error: "rate_limit_exceeded",
+          message: "Rate limit exceeded. Please try again later.",
+          statusCode: 429
+        };
+      }
+    }
+    if (telemetry) {
+      telemetry.emit("fulmen.config.http_endpoint.reload_requested", {
+        correlation_id: correlationId
+      });
+    }
+    try {
+      const config = await loader();
+      if (validator) {
+        const validation = await validator(config);
+        if (!validation.valid) {
+          if (logger) {
+            logger.warn("Config reload endpoint: validation failed", {
+              correlation_id: correlationId,
+              error_count: validation.errors?.length ?? 0
+            });
+          }
+          if (telemetry) {
+            telemetry.emit("fulmen.config.http_endpoint.reload_rejected", {
+              correlation_id: correlationId,
+              reason: "validation_failed"
+            });
+          }
+          return {
+            status: "error",
+            error: "validation_failed",
+            message: "Configuration validation failed",
+            validation_errors: validation.errors,
+            statusCode: 422
+          };
+        }
+      }
+      if (onReload2) {
+        await onReload2(config);
+      }
+      if (telemetry) {
+        telemetry.emit("fulmen.config.http_endpoint.reload_accepted", {
+          correlation_id: correlationId
+        });
+      }
+      if (logger) {
+        logger.info("Config reload endpoint: reload accepted", {
+          correlation_id: correlationId,
+          reason: payload.reason
+        });
+      }
+      return {
+        status: "reloaded",
+        correlation_id: correlationId,
+        message: "Configuration reloaded",
+        statusCode: 200
+      };
+    } catch (error) {
+      if (logger) {
+        logger.warn("Config reload endpoint: reload failed", {
+          correlation_id: correlationId,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+      if (telemetry) {
+        telemetry.emit("fulmen.config.http_endpoint.reload_error", {
+          correlation_id: correlationId,
+          error_type: error instanceof Error ? error.constructor.name : "unknown"
+        });
+      }
+      return {
+        status: "error",
+        error: "reload_failed",
+        message: error instanceof Error ? error.message : String(error),
+        statusCode: 500
+      };
+    }
+  };
+}
+function generateCorrelationId() {
+  return `cfg-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}
+var init_config_reload_endpoint = __esm({
+  "src/foundry/signals/config-reload-endpoint.ts"() {
+  }
+});
+
+// src/appidentity/runtime.ts
+function detectRuntime() {
+  const versions = process.versions;
+  if (typeof versions.bun === "string" && versions.bun.length > 0) {
+    return { name: "bun", version: versions.bun };
+  }
+  if (typeof versions.node === "string" && versions.node.length > 0) {
+    return { name: "node", version: versions.node };
+  }
+  return { name: "unknown" };
+}
+function buildRuntimeInfo(options = {}) {
+  const runtime = detectRuntime();
+  const serviceName = options.serviceName ?? options.identity?.app.binary_name ?? "unknown-service";
+  const vendor = options.vendor ?? options.identity?.app.vendor;
+  return {
+    service: {
+      name: serviceName,
+      vendor,
+      version: options.version
+    },
+    runtime,
+    platform: {
+      os: process.platform,
+      arch: process.arch
+    }
+  };
+}
+var init_runtime = __esm({
+  "src/appidentity/runtime.ts"() {
+  }
+});
+
+// src/foundry/signals/control-discovery-endpoint.ts
+function createControlDiscoveryEndpoint(options) {
+  const { identity, version, endpoints, auth, authSummary, logger, telemetry } = options;
+  return async (req) => {
+    if (auth) {
+      const authResult = await auth(req);
+      if (!authResult.authenticated) {
+        if (logger) {
+          logger.warn("Control discovery endpoint: authentication failed", {
+            reason: authResult.reason
+          });
+        }
+        if (telemetry) {
+          telemetry.emit("fulmen.control.discovery.auth_failed", {
+            service: identity.app.binary_name
+          });
+        }
+        return {
+          status: "error",
+          error: "authentication_failed",
+          message: authResult.reason || "Authentication required",
+          statusCode: 401
+        };
+      }
+    }
+    if (telemetry) {
+      telemetry.emit("fulmen.control.discovery.served", {
+        service: identity.app.binary_name
+      });
+    }
+    const runtime = buildRuntimeInfo({ identity, version });
+    return {
+      status: "ok",
+      service: {
+        name: identity.app.binary_name,
+        vendor: identity.app.vendor,
+        version
+      },
+      runtime: {
+        name: runtime.runtime.name,
+        version: runtime.runtime.version,
+        platform: runtime.platform.os,
+        arch: runtime.platform.arch
+      },
+      auth_summary: authSummary,
+      endpoints,
+      statusCode: 200
+    };
+  };
+}
+var init_control_discovery_endpoint = __esm({
+  "src/foundry/signals/control-discovery-endpoint.ts"() {
+    init_runtime();
+  }
+});
+
 // src/foundry/signals/convenience.ts
 async function onShutdown(manager, handler, options = {}) {
   await manager.register("SIGTERM", handler, options);
@@ -4058,7 +4295,7 @@ var init_guards = __esm({
 function createSignalEndpoint(options) {
   const { manager, auth, rateLimit, logger, telemetry, allowedSignals } = options;
   return async (payload, req) => {
-    const correlationId = payload.correlation_id ?? generateCorrelationId();
+    const correlationId = payload.correlation_id ?? generateCorrelationId2();
     const authResult = await auth(req);
     if (!authResult.authenticated) {
       if (logger) {
@@ -4181,7 +4418,7 @@ function normalizeSignalName(signal) {
   }
   return `SIG${upper}`;
 }
-function generateCorrelationId() {
+function generateCorrelationId2() {
   return `sig-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
 }
 function createBearerTokenAuth(expectedToken) {
@@ -4648,6 +4885,8 @@ var init_signals = __esm({
   "src/foundry/signals/index.ts"() {
     init_capabilities2();
     init_catalog();
+    init_config_reload_endpoint();
+    init_control_discovery_endpoint();
     init_convenience();
     init_double_tap();
     init_guards();
@@ -4793,7 +5032,9 @@ __export(foundry_exports, {
   clearMimeTypeCache: () => clearMimeTypeCache,
   clearPatternCache: () => clearPatternCache,
   createBearerTokenAuth: () => createBearerTokenAuth,
+  createConfigReloadEndpoint: () => createConfigReloadEndpoint,
   createConfigReloadHandler: () => createConfigReloadHandler,
+  createControlDiscoveryEndpoint: () => createControlDiscoveryEndpoint,
   createDoubleTapTracker: () => createDoubleTapTracker,
   createSignalEndpoint: () => createSignalEndpoint,
   createSignalManager: () => createSignalManager,
@@ -5825,6 +6066,7 @@ var init_cli = __esm({
 // src/schema/index.ts
 var init_schema = __esm({
   "src/schema/index.ts"() {
+    init_ajv_formats();
     init_cli();
     init_errors();
     init_export();
@@ -5941,7 +6183,8 @@ async function getEnvVar(key, options) {
 
 // src/appidentity/index.ts
 init_loader2();
+init_runtime();
 
-export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, AppIdentityError, MAX_ANCESTOR_SEARCH_DEPTH, buildEnvVar, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };
+export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, AppIdentityError, MAX_ANCESTOR_SEARCH_DEPTH, buildEnvVar, buildRuntimeInfo, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map