@fulmenhq/tsfulmen 0.1.13 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/CHANGELOG.md +73 -512
  2. package/README.md +111 -28
  3. package/config/crucible-ts/agentic/roles/README.md +76 -0
  4. package/config/crucible-ts/agentic/roles/cicd.yaml +82 -0
  5. package/config/crucible-ts/agentic/roles/dataeng.yaml +104 -0
  6. package/config/crucible-ts/agentic/roles/devlead.yaml +84 -0
  7. package/config/crucible-ts/agentic/roles/devrev.yaml +105 -0
  8. package/config/crucible-ts/agentic/roles/entarch.yaml +101 -0
  9. package/config/crucible-ts/agentic/roles/infoarch.yaml +95 -0
  10. package/config/crucible-ts/agentic/roles/prodmktg.yaml +92 -0
  11. package/config/crucible-ts/agentic/roles/qa.yaml +148 -0
  12. package/config/crucible-ts/agentic/roles/secrev.yaml +101 -0
  13. package/config/crucible-ts/agentic/roles/uxdev.yaml +168 -0
  14. package/config/crucible-ts/branding/ecosystem.yaml +26 -0
  15. package/config/crucible-ts/library/foundry/exit-codes.snapshot.json +26 -0
  16. package/config/crucible-ts/library/foundry/exit-codes.yaml +28 -3
  17. package/config/crucible-ts/library/foundry/patterns.yaml +2 -2
  18. package/config/crucible-ts/library/foundry/signal-resolution-fixtures.yaml +207 -0
  19. package/config/crucible-ts/library/foundry/signals.yaml +21 -0
  20. package/config/crucible-ts/library/foundry/simplified-modes.snapshot.json +9 -1
  21. package/config/crucible-ts/library/{foundry/similarity-fixtures.yaml → similarity/fixtures.yaml} +1 -1
  22. package/config/crucible-ts/library/v1.0.0/module-manifest.yaml +1 -2
  23. package/config/crucible-ts/taxonomy/fixture-catalog.yaml +145 -0
  24. package/config/crucible-ts/taxonomy/languages.yaml +2 -2
  25. package/config/crucible-ts/taxonomy/library/foundry-catalogs/v1.1.0/catalogs.yaml +77 -0
  26. package/config/crucible-ts/taxonomy/library/platform-modules/v1.1.0/modules.yaml +722 -0
  27. package/config/crucible-ts/taxonomy/metrics.yaml +1 -1
  28. package/config/crucible-ts/taxonomy/repository-categories.yaml +134 -1
  29. package/dist/appidentity/index.d.ts +117 -35
  30. package/dist/appidentity/index.js +752 -592
  31. package/dist/appidentity/index.js.map +1 -1
  32. package/dist/config/index.js +118 -6
  33. package/dist/config/index.js.map +1 -1
  34. package/dist/crucible/index.js +118 -6
  35. package/dist/crucible/index.js.map +1 -1
  36. package/dist/errors/index.js +118 -6
  37. package/dist/errors/index.js.map +1 -1
  38. package/dist/foundry/index.d.ts +13 -676
  39. package/dist/foundry/index.js +118 -6
  40. package/dist/foundry/index.js.map +1 -1
  41. package/dist/foundry/similarity/index.d.ts +2 -2
  42. package/dist/fulhash/index.d.ts +64 -12
  43. package/dist/fulhash/index.js +292 -53
  44. package/dist/fulhash/index.js.map +1 -1
  45. package/dist/index.d.ts +2 -2
  46. package/dist/index.js +753 -593
  47. package/dist/index.js.map +1 -1
  48. package/dist/{manager-D27vrdaS.d.ts → manager-CH3fX7zO.d.ts} +1 -1
  49. package/dist/pathfinder/index.js +368 -59
  50. package/dist/pathfinder/index.js.map +1 -1
  51. package/dist/reports/license-inventory.csv +302 -0
  52. package/dist/schema/index.js +118 -6
  53. package/dist/schema/index.js.map +1 -1
  54. package/dist/signals/index.d.ts +675 -0
  55. package/dist/signals/index.js +5790 -0
  56. package/dist/signals/index.js.map +1 -0
  57. package/dist/similarity/index.d.ts +2 -0
  58. package/dist/similarity/index.js +136 -0
  59. package/dist/similarity/index.js.map +1 -0
  60. package/dist/{suggest-Cv7SVQRu.d.ts → suggest-D8LbwtPV.d.ts} +1 -1
  61. package/dist/telemetry/http/index.js +704 -591
  62. package/dist/telemetry/http/index.js.map +1 -1
  63. package/dist/telemetry/index.js +118 -6
  64. package/dist/telemetry/index.js.map +1 -1
  65. package/dist/telemetry/prometheus/index.d.ts +1 -1
  66. package/dist/telemetry/prometheus/index.js +175 -11
  67. package/dist/telemetry/prometheus/index.js.map +1 -1
  68. package/package.json +15 -6
  69. package/schemas/crucible-ts/assessment/v1.0.0/severity-definitions.schema.json +1 -1
  70. package/schemas/crucible-ts/config/fulmen-ecosystem/v1.0.0/fulmen-config-paths.schema.json +1 -1
  71. package/schemas/crucible-ts/config/repository/app-identity/v1.0.0/app-identity.schema.json +3 -3
  72. package/schemas/crucible-ts/config/repository/v1.0.0/lifecycle-phase.json +1 -1
  73. package/schemas/crucible-ts/config/repository-category/codex/v1.0.0/codex-config.schema.json +1 -1
  74. package/schemas/crucible-ts/config/standards/v1.0.0/adr-adoption-status.json +1 -1
  75. package/schemas/crucible-ts/config/standards/v1.0.0/adr-frontmatter.schema.json +3 -3
  76. package/schemas/crucible-ts/config/standards/v1.0.0/adr-lifecycle-status.json +1 -1
  77. package/schemas/crucible-ts/config/sync-keys.schema.yaml +14 -0
  78. package/schemas/crucible-ts/content/ssot-provenance/v1.0.0/ssot-provenance.schema.json +1 -1
  79. package/schemas/crucible-ts/design/README.md +159 -0
  80. package/schemas/crucible-ts/design/core/v1.0.0/component-states.schema.json +204 -0
  81. package/schemas/crucible-ts/design/core/v1.0.0/semantic-colors.schema.json +179 -0
  82. package/schemas/crucible-ts/design/core/v1.0.0/spacing-scale.schema.json +165 -0
  83. package/schemas/crucible-ts/design/core/v1.0.0/typography-roles.schema.json +195 -0
  84. package/schemas/crucible-ts/design/tui/v1.0.0/color-palette.schema.json +303 -0
  85. package/schemas/crucible-ts/design/tui/v1.0.0/component.schema.json +374 -0
  86. package/schemas/crucible-ts/design/tui/v1.0.0/layout.schema.json +272 -0
  87. package/schemas/crucible-ts/design/tui/v1.0.0/theme.schema.json +205 -0
  88. package/schemas/crucible-ts/design/tui/v1.0.0/typography.schema.json +316 -0
  89. package/schemas/crucible-ts/devsecops/lorage-central/activity/v1.0.0/activity.schema.json +1 -1
  90. package/schemas/crucible-ts/devsecops/lorage-central/credentials/v1.0.0/credentials.schema.json +1 -1
  91. package/schemas/crucible-ts/devsecops/lorage-central/policy/v1.0.0/policy.schema.json +1 -1
  92. package/schemas/crucible-ts/devsecops/lorage-central/recipe/v1.0.0/recipe.schema.json +1 -1
  93. package/schemas/crucible-ts/devsecops/lorage-central/runbooks/v1.0.0/runbook.schema.json +1 -1
  94. package/schemas/crucible-ts/devsecops/lorage-central/tenant/v1.0.0/tenant.schema.json +1 -1
  95. package/schemas/crucible-ts/devsecops/secrets/v1.0.0/secrets.schema.json +1 -1
  96. package/schemas/crucible-ts/error-handling/v1.0.0/error-response.schema.json +1 -1
  97. package/schemas/crucible-ts/library/foundry/v1.0.0/country-codes.schema.json +1 -1
  98. package/schemas/crucible-ts/library/foundry/v1.0.0/exit-codes.schema.json +1 -1
  99. package/schemas/crucible-ts/library/foundry/v1.0.0/http-status-groups.schema.json +1 -1
  100. package/schemas/crucible-ts/library/foundry/v1.0.0/mime-types.schema.json +1 -1
  101. package/schemas/crucible-ts/library/foundry/v1.0.0/patterns.schema.json +1 -1
  102. package/schemas/crucible-ts/library/foundry/v1.0.0/signal-resolution-fixtures.schema.json +140 -0
  103. package/schemas/crucible-ts/library/foundry/v1.0.0/signals.schema.json +6 -1
  104. package/schemas/crucible-ts/library/fulencode/v1.0.0/fulencode-config.schema.json +1 -1
  105. package/schemas/crucible-ts/library/fulhash/v1.0.0/checksum-string.schema.json +2 -2
  106. package/schemas/crucible-ts/library/fulhash/v1.0.0/digest.schema.json +61 -1
  107. package/schemas/crucible-ts/library/fulhash/v1.0.0/fixtures.schema.json +1 -1
  108. package/schemas/crucible-ts/library/fulpack/v1.0.0/archive-entry.schema.json +1 -1
  109. package/schemas/crucible-ts/library/fulpack/v1.0.0/archive-info.schema.json +1 -1
  110. package/schemas/crucible-ts/library/fulpack/v1.0.0/archive-manifest.schema.json +2 -2
  111. package/schemas/crucible-ts/library/fulpack/v1.0.0/create-options.schema.json +1 -1
  112. package/schemas/crucible-ts/library/fulpack/v1.0.0/extract-options.schema.json +1 -1
  113. package/schemas/crucible-ts/library/fulpack/v1.0.0/extract-result.schema.json +1 -1
  114. package/schemas/crucible-ts/library/fulpack/v1.0.0/scan-options.schema.json +1 -1
  115. package/schemas/crucible-ts/library/fulpack/v1.0.0/validation-result.schema.json +1 -1
  116. package/schemas/crucible-ts/library/module-manifest/v1.0.0/module-manifest.schema.json +1 -1
  117. package/schemas/crucible-ts/library/{foundry → similarity}/v1.0.0/similarity.schema.json +2 -2
  118. package/schemas/crucible-ts/library/{foundry → similarity}/v2.0.0/similarity.schema.json +2 -2
  119. package/schemas/crucible-ts/observability/metrics/v1.0.0/metrics-event.schema.json +1 -1
  120. package/schemas/crucible-ts/pathfinder/v1.0.0/find-query.schema.json +1 -1
  121. package/schemas/crucible-ts/pathfinder/v1.0.0/finder-config.schema.json +1 -1
  122. package/schemas/crucible-ts/pathfinder/v1.0.0/path-result.schema.json +1 -1
  123. package/schemas/crucible-ts/protocol/http/v1.0.0/error-response.schema.json +1 -1
  124. package/schemas/crucible-ts/protocol/http/v1.0.0/health-response.schema.json +1 -1
  125. package/schemas/crucible-ts/protocol/http/v1.0.0/success-response.schema.json +1 -1
  126. package/schemas/crucible-ts/protocol/http/v1.0.0/version-response.schema.json +1 -1
  127. package/schemas/crucible-ts/server/management/v1.0.0/server-management.schema.json +1 -1
  128. package/schemas/crucible-ts/standards/publishing/v1.0.0/spec-catalog.schema.json +134 -0
  129. package/schemas/crucible-ts/taxonomy/devsecops/auth-methods/v1.0.0/auth-methods-key.schema.json +1 -1
  130. package/schemas/crucible-ts/taxonomy/devsecops/auth-methods/v1.0.0/auth-methods-metadata.schema.json +1 -1
  131. package/schemas/crucible-ts/taxonomy/devsecops/geo/v1.0.0/geo-key.schema.json +1 -1
  132. package/schemas/crucible-ts/taxonomy/devsecops/geo/v1.0.0/geo-metadata.schema.json +1 -1
  133. package/schemas/crucible-ts/taxonomy/devsecops/infra-phases/v1.0.0/infra-phases-key.schema.json +1 -1
  134. package/schemas/crucible-ts/taxonomy/devsecops/infra-phases/v1.0.0/infra-phases-metadata.schema.json +1 -1
  135. package/schemas/crucible-ts/taxonomy/devsecops/infra-providers/v1.0.0/infra-providers-key.schema.json +1 -1
  136. package/schemas/crucible-ts/taxonomy/devsecops/infra-providers/v1.0.0/infra-providers-metadata.schema.json +1 -1
  137. package/schemas/crucible-ts/taxonomy/devsecops/modules/v1.0.0/devsecops-module-entry.schema.json +1 -1
  138. package/schemas/crucible-ts/taxonomy/fixture/v1.0.0/fixture-catalog.schema.json +166 -0
  139. package/schemas/crucible-ts/taxonomy/language/v1.0.0/language-key.schema.json +1 -1
  140. package/schemas/crucible-ts/taxonomy/language/v1.0.0/language-metadata.schema.json +1 -1
  141. package/schemas/crucible-ts/taxonomy/library/foundry-catalogs/v1.1.0/catalog-entry.schema.json +98 -0
  142. package/schemas/crucible-ts/taxonomy/library/fulencode/detection-confidence/v1.0.0/levels.schema.json +1 -1
  143. package/schemas/crucible-ts/taxonomy/library/fulencode/encoding-families/v1.0.0/families.schema.json +1 -1
  144. package/schemas/crucible-ts/taxonomy/library/fulencode/normalization-profiles/v1.0.0/profiles.schema.json +1 -1
  145. package/schemas/crucible-ts/taxonomy/library/fulhash/algorithms/v1.0.0/algorithms.yaml +16 -0
  146. package/schemas/crucible-ts/taxonomy/library/modules/v1.0.0/module-entry.schema.json +1 -1
  147. package/schemas/crucible-ts/taxonomy/library/modules/v1.1.0/module-entry.schema.json +436 -0
  148. package/schemas/crucible-ts/taxonomy/repository-category/v1.0.0/category-key.schema.json +16 -8
  149. package/schemas/crucible-ts/taxonomy/repository-category/v1.0.0/category-metadata.schema.json +1 -1
  150. package/schemas/crucible-ts/upstream/3leaps/PROVENANCE.md +43 -0
  151. package/schemas/crucible-ts/upstream/3leaps/agentic/v0/role-prompt.schema.json +183 -0
  152. package/schemas/crucible-ts/upstream/3leaps/ailink/v0/prompt.schema.json +204 -0
  153. package/schemas/crucible-ts/upstream/3leaps/ailink/v0/search-response.schema.json +152 -0
  154. package/schemas/crucible-ts/upstream/README.md +50 -0
  155. package/schemas/crucible-ts/web/branding/v1.0.0/site-branding.schema.json +1 -1
  156. package/schemas/crucible-ts/web/styling/v1.0.0/site-styling.schema.json +1 -1
  157. package/schemas/crucible-ts/config/goneat/README.md +0 -60
  158. package/schemas/crucible-ts/config/goneat/v1.0.0/dates.yaml +0 -234
  159. package/schemas/crucible-ts/config/goneat/v1.0.0/goneat-config.yaml +0 -344
  160. package/schemas/crucible-ts/config/goneat/v1.0.0/lifecycle-phase.json +0 -20
  161. package/schemas/crucible-ts/config/goneat/v1.0.0/release-phase.json +0 -17
  162. package/schemas/crucible-ts/config/goneat/v1.0.0/security-policy.yaml +0 -178
  163. package/schemas/crucible-ts/config/goneat/v1.0.0/version-policy.schema.yaml +0 -205
  164. package/schemas/crucible-ts/tooling/goneat-tools/v1.0.0/README.md +0 -177
  165. package/schemas/crucible-ts/tooling/goneat-tools/v1.0.0/goneat-tools-config.schema.yaml +0 -146
@@ -1,7 +1,7 @@
1
- export { F as FoundryCatalogError, f as NormalizeOptions, g as SuggestOptions, S as Suggestion, c as casefold, d as distance, e as equalsIgnoreCase, n as normalize, a as score, s as stripAccents, b as suggest } from '../suggest-Cv7SVQRu.js';
1
+ export { F as FoundryCatalogError, N as NormalizeOptions, a as SuggestOptions, S as Suggestion, c as casefold, d as distance, e as equalsIgnoreCase, n as normalize, s as score, b as stripAccents, f as suggest } from '../suggest-D8LbwtPV.js';
2
2
  import { Readable } from 'node:stream';
3
- import { B as BehaviorInfo, a as SignalInfo, b as SignalCatalog, S as SignalManager, c as SignalHandler, H as HandlerOptions, F as FallbackLogger, T as TelemetryEmitter } from '../manager-D27vrdaS.js';
4
- export { d as Behavior, e as BehaviorPhase, E as ExitCodes, L as LogLevel, O as OsMappings, P as PlatformOverrides, j as PlatformSupport, k as PlatformSupportLevel, l as Signal, m as SignalBehavior, n as SignalManagerOptions, o as TimeoutBehavior, W as WindowsFallback, p as WindowsFallbackBehavior, q as WindowsFallbackOptions, s as WindowsFallbackResult, f as createSignalManager, g as getFallbackMetadata, h as getHttpFallbackGuidance, i as handleWindowsFallback, r as requiresFallback } from '../manager-D27vrdaS.js';
3
+ export { AuthHook, AuthResult, ConfigLoader, ConfigReloadOptions, ConfigReloadResult, ConfigReloadTracker, ConfigValidationResult, ConfigValidator, DoubleTapConfig, DoubleTapState, GuardOptions, Platform, RateLimitHook, RateLimitResult, SignalEndpointOptions, SignalErrorResponse, PlatformCapabilities as SignalPlatformCapabilities, SignalRequest, SignalResponse, createBearerTokenAuth, createConfigReloadHandler, createDoubleTapTracker, createSignalEndpoint, createSimpleRateLimiter, ensurePOSIX, ensureSignalExitCodesSupported, ensureSupported, ensureWindows, getBehavior, getSignal, getSignalCatalog, getSignalNumber, getPlatformCapabilities as getSignalPlatformCapabilities, getSignalsVersion, getWindowTimeRemaining, getWindowsEvent, handleDoubleTap, isPOSIX as isSignalPOSIX, isWindows as isSignalWindows, isWithinWindow, listBehaviors, listSignals, onAnyShutdown, onEmergencyQuit, onReload, onShutdown, onUSR1, onUSR2, resetDoubleTap, supportsSignal, supportsSignalExitCodes as supportsSignalBasedExitCodes } from '../signals/index.js';
4
+ export { B as Behavior, a as BehaviorInfo, b as BehaviorPhase, E as ExitCodes, F as FallbackLogger, H as HandlerOptions, L as LogLevel, O as OsMappings, P as PlatformOverrides, e as PlatformSupport, f as PlatformSupportLevel, i as Signal, j as SignalBehavior, k as SignalCatalog, l as SignalHandler, m as SignalInfo, S as SignalManager, n as SignalManagerOptions, T as TelemetryEmitter, o as TimeoutBehavior, W as WindowsFallback, p as WindowsFallbackBehavior, q as WindowsFallbackOptions, s as WindowsFallbackResult, c as createSignalManager, g as getFallbackMetadata, d as getHttpFallbackGuidance, h as handleWindowsFallback, r as requiresFallback } from '../manager-CH3fX7zO.js';
5
5
 
6
6
  /**
7
7
  * Foundry module - TypeScript type definitions
@@ -185,6 +185,10 @@ declare const exitCodes: {
185
185
  readonly EXIT_TEST_USAGE_ERROR: 94;
186
186
  readonly EXIT_TEST_NO_TESTS_COLLECTED: 95;
187
187
  readonly EXIT_COVERAGE_THRESHOLD_NOT_MET: 96;
188
+ readonly EXIT_TIMEOUT: 124;
189
+ readonly EXIT_TIMEOUT_INTERNAL: 125;
190
+ readonly EXIT_CANNOT_EXECUTE: 126;
191
+ readonly EXIT_NOT_FOUND: 127;
188
192
  readonly EXIT_SIGNAL_HUP: 129;
189
193
  readonly EXIT_SIGNAL_INT: 130;
190
194
  readonly EXIT_SIGNAL_QUIT: 131;
@@ -276,7 +280,7 @@ declare const EXIT_CODES_VERSION = "v1.0.0";
276
280
  * }
277
281
  * ```
278
282
  */
279
- declare function supportsSignalExitCodes$1(): boolean;
283
+ declare function supportsSignalExitCodes(): boolean;
280
284
  /**
281
285
  * Get the current platform identifier
282
286
  *
@@ -293,17 +297,17 @@ declare function getPlatform(): NodeJS.Platform;
293
297
  *
294
298
  * @returns true if running on native Windows
295
299
  */
296
- declare function isWindows$1(): boolean;
300
+ declare function isWindows(): boolean;
297
301
  /**
298
302
  * Check if running on a POSIX-compliant platform
299
303
  *
300
304
  * @returns true if running on Linux, macOS, or other POSIX systems
301
305
  */
302
- declare function isPOSIX$1(): boolean;
306
+ declare function isPOSIX(): boolean;
303
307
  /**
304
308
  * Platform capabilities summary
305
309
  */
306
- interface PlatformCapabilities$1 {
310
+ interface PlatformCapabilities {
307
311
  platform: NodeJS.Platform;
308
312
  supportsSignalExitCodes: boolean;
309
313
  isPOSIX: boolean;
@@ -323,7 +327,7 @@ interface PlatformCapabilities$1 {
323
327
  * console.log(`Supports signal exit codes: ${caps.supportsSignalExitCodes}`);
324
328
  * ```
325
329
  */
326
- declare function getPlatformCapabilities$1(): PlatformCapabilities$1;
330
+ declare function getPlatformCapabilities(): PlatformCapabilities;
327
331
 
328
332
  /**
329
333
  * Simplified Exit Code Mapping
@@ -515,673 +519,6 @@ declare function listPatterns(): Promise<ReadonlyArray<Readonly<Pattern>>>;
515
519
  declare function describePattern(id: string): Promise<string | null>;
516
520
  declare function clearPatternCache(): void;
517
521
 
518
- /**
519
- * Signal Capability Detection
520
- *
521
- * Platform-aware signal support detection driven by catalog metadata.
522
- * Ensures cross-language parity by querying windows_event/fallback fields
523
- * rather than hardcoding signal names.
524
- */
525
- /**
526
- * Platform types
527
- */
528
- type Platform = "linux" | "darwin" | "win32" | "freebsd" | "unknown";
529
- /**
530
- * Platform capabilities summary
531
- */
532
- interface PlatformCapabilities {
533
- platform: Platform;
534
- isPOSIX: boolean;
535
- isWindows: boolean;
536
- supportsNativeSignals: boolean;
537
- supportsSignalExitCodes: boolean;
538
- supportedSignals: string[];
539
- unsupportedSignals: string[];
540
- mappedSignals: string[];
541
- }
542
- /**
543
- * Check if current platform is POSIX-compliant
544
- */
545
- declare function isPOSIX(): boolean;
546
- /**
547
- * Check if current platform is Windows
548
- */
549
- declare function isWindows(): boolean;
550
- /**
551
- * Check if a signal is supported on the current platform
552
- *
553
- * Uses catalog metadata (windows_event field) to determine support.
554
- * Returns true if:
555
- * - Platform is POSIX (all signals natively supported)
556
- * - Platform is Windows AND signal has non-null windows_event
557
- *
558
- * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
559
- */
560
- declare function supportsSignal(signalName: string): Promise<boolean>;
561
- /**
562
- * Check if platform supports signal-based exit codes (128+N pattern)
563
- *
564
- * Windows doesn't propagate signal numbers via exit codes in the same way
565
- * as POSIX systems. This function helps applications decide whether to
566
- * rely on signal exit codes for process monitoring.
567
- */
568
- declare function supportsSignalExitCodes(): boolean;
569
- /**
570
- * Get comprehensive platform capabilities
571
- *
572
- * Queries catalog to build a complete picture of signal support.
573
- * Useful for capability reporting, documentation generation, and testing.
574
- */
575
- declare function getPlatformCapabilities(): Promise<PlatformCapabilities>;
576
- /**
577
- * Get the signal number for the current platform
578
- *
579
- * Handles platform-specific overrides (e.g., SIGUSR1/SIGUSR2 on macOS/FreeBSD).
580
- * Returns the appropriate signal number based on platform_overrides.
581
- *
582
- * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
583
- * @returns Signal number for current platform, or null if signal not found
584
- */
585
- declare function getSignalNumber(signalName: string): Promise<number | null>;
586
- /**
587
- * Get the Windows console event name for a signal
588
- *
589
- * Returns the Windows console event that corresponds to a Unix signal,
590
- * or null if the signal is not supported on Windows.
591
- *
592
- * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
593
- */
594
- declare function getWindowsEvent(signalName: string): Promise<string | null>;
595
-
596
- /**
597
- * Signal Catalog Loader
598
- *
599
- * Loads and validates the signal handling catalog from Crucible SSOT assets
600
- * following the same pattern as other Foundry catalogs.
601
- */
602
-
603
- /**
604
- * Get the signals catalog version
605
- */
606
- declare function getSignalsVersion(): Promise<string>;
607
- /**
608
- * Get all signals
609
- */
610
- declare function listSignals(): Promise<SignalInfo[]>;
611
- /**
612
- * Get a specific signal by ID or name
613
- */
614
- declare function getSignal(identifier: string): Promise<SignalInfo | null>;
615
- /**
616
- * Get all behaviors
617
- */
618
- declare function listBehaviors(): Promise<BehaviorInfo[]>;
619
- /**
620
- * Get a specific behavior by ID
621
- */
622
- declare function getBehavior(id: string): Promise<BehaviorInfo | null>;
623
- /**
624
- * Get the complete catalog (for advanced use cases)
625
- */
626
- declare function getSignalCatalog(): Promise<SignalCatalog>;
627
-
628
- /**
629
- * Signal Handler Convenience Wrappers
630
- *
631
- * Common signal handling patterns for shutdown, reload, and custom behaviors.
632
- */
633
-
634
- /**
635
- * Register a graceful shutdown handler
636
- *
637
- * Convenience wrapper for SIGTERM and SIGINT handlers.
638
- * Automatically registers both signals to the same handler.
639
- *
640
- * @param manager - Signal manager instance
641
- * @param handler - Shutdown handler function
642
- * @param options - Handler options
643
- *
644
- * @example
645
- * ```typescript
646
- * await onShutdown(manager, async () => {
647
- * await closeDatabase();
648
- * await flushLogs();
649
- * });
650
- * ```
651
- */
652
- declare function onShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
653
- /**
654
- * Register a config reload handler
655
- *
656
- * Convenience wrapper for SIGHUP handler.
657
- * Only registers on POSIX platforms (SIGHUP not supported on Windows).
658
- *
659
- * @param manager - Signal manager instance
660
- * @param handler - Reload handler function
661
- * @param options - Handler options
662
- *
663
- * @example
664
- * ```typescript
665
- * await onReload(manager, async () => {
666
- * const newConfig = await loadConfig();
667
- * await validateConfig(newConfig);
668
- * process.exit(129); // Exit for restart
669
- * });
670
- * ```
671
- */
672
- declare function onReload(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
673
- /**
674
- * Register a custom handler for SIGUSR1
675
- *
676
- * Common use cases: toggle debug logging, reopen log files, dump statistics.
677
- *
678
- * @param manager - Signal manager instance
679
- * @param handler - Custom handler function
680
- * @param options - Handler options
681
- *
682
- * @example
683
- * ```typescript
684
- * await onUSR1(manager, async () => {
685
- * logger.info('SIGUSR1 received - reopening log files');
686
- * await reopenLogFiles();
687
- * });
688
- * ```
689
- */
690
- declare function onUSR1(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
691
- /**
692
- * Register a custom handler for SIGUSR2
693
- *
694
- * Common use cases: trigger profiling, rotate credentials, toggle verbose mode.
695
- *
696
- * @param manager - Signal manager instance
697
- * @param handler - Custom handler function
698
- * @param options - Handler options
699
- *
700
- * @example
701
- * ```typescript
702
- * await onUSR2(manager, async () => {
703
- * logger.info('SIGUSR2 received - toggling debug mode');
704
- * toggleDebugMode();
705
- * });
706
- * ```
707
- */
708
- declare function onUSR2(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
709
- /**
710
- * Register an emergency quit handler
711
- *
712
- * Convenience wrapper for SIGQUIT (immediate exit, no cleanup).
713
- *
714
- * @param manager - Signal manager instance
715
- * @param handler - Emergency quit handler
716
- * @param options - Handler options
717
- *
718
- * @example
719
- * ```typescript
720
- * await onEmergencyQuit(manager, async () => {
721
- * logger.error('SIGQUIT received - emergency exit');
722
- * process.exit(131);
723
- * });
724
- * ```
725
- */
726
- declare function onEmergencyQuit(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
727
- /**
728
- * Register handlers for all common shutdown signals
729
- *
730
- * Registers the same handler for SIGTERM, SIGINT, and SIGQUIT.
731
- * Useful for applications that want consistent shutdown behavior.
732
- *
733
- * @param manager - Signal manager instance
734
- * @param handler - Shutdown handler function
735
- * @param options - Handler options
736
- */
737
- declare function onAnyShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
738
-
739
- /**
740
- * Double-Tap Signal Handling
741
- *
742
- * Implements Ctrl+C double-tap pattern for graceful shutdown with force-quit option.
743
- * Per Crucible standard: 2-second window, immediate exit on second signal.
744
- */
745
-
746
- /**
747
- * Double-tap configuration
748
- */
749
- interface DoubleTapConfig {
750
- /**
751
- * Debounce window in milliseconds (default: 2000ms per Crucible standard)
752
- */
753
- windowMs?: number;
754
- /**
755
- * Exit code for forced double-tap exit (default: 130 for SIGINT)
756
- */
757
- exitCode?: number;
758
- /**
759
- * Message to display on first signal (default: from catalog)
760
- */
761
- hintMessage?: string;
762
- /**
763
- * Logger for double-tap events
764
- */
765
- logger?: FallbackLogger;
766
- /**
767
- * Enable test mode (prevents process.exit calls)
768
- */
769
- testMode?: boolean;
770
- }
771
- /**
772
- * Double-tap state tracker
773
- */
774
- interface DoubleTapState {
775
- firstTapTime: number | null;
776
- windowMs: number;
777
- exitCode: number;
778
- hintMessage: string;
779
- logger?: FallbackLogger;
780
- testMode: boolean;
781
- }
782
- /**
783
- * Create double-tap state tracker for a signal
784
- *
785
- * @param signalName - Signal name (typically "SIGINT")
786
- * @param config - Double-tap configuration
787
- */
788
- declare function createDoubleTapTracker(signalName: string, config?: DoubleTapConfig): Promise<DoubleTapState>;
789
- /**
790
- * Handle double-tap signal logic
791
- *
792
- * Returns true if this is the second tap (force-quit), false if first tap.
793
- * Updates state to track timing between taps.
794
- *
795
- * @param state - Double-tap state tracker
796
- * @returns true if force-quit should proceed, false if graceful shutdown
797
- */
798
- declare function handleDoubleTap(state: DoubleTapState): boolean;
799
- /**
800
- * Reset double-tap state
801
- *
802
- * Called when graceful shutdown completes before second tap.
803
- */
804
- declare function resetDoubleTap(state: DoubleTapState): void;
805
- /**
806
- * Check if currently within double-tap window
807
- *
808
- * Useful for testing and debugging.
809
- */
810
- declare function isWithinWindow(state: DoubleTapState): boolean;
811
- /**
812
- * Get time remaining in double-tap window (milliseconds)
813
- *
814
- * Returns null if not in a window, otherwise milliseconds remaining.
815
- */
816
- declare function getWindowTimeRemaining(state: DoubleTapState): number | null;
817
-
818
- /**
819
- * Signal Support Guards
820
- *
821
- * Validation functions that throw actionable errors when signals are unsupported.
822
- * Used to fail-fast with clear operational guidance.
823
- */
824
- /**
825
- * Guard options
826
- */
827
- interface GuardOptions {
828
- /**
829
- * Include platform-specific operational guidance in error message
830
- */
831
- includeGuidance?: boolean;
832
- }
833
- /**
834
- * Ensure a signal is supported on the current platform
835
- *
836
- * Throws an error with actionable guidance if the signal is not supported.
837
- * Use this as a guard at the start of signal registration functions.
838
- *
839
- * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
840
- * @param options - Guard configuration
841
- * @throws {FoundryCatalogError} If signal is not found or not supported
842
- *
843
- * @example
844
- * ```typescript
845
- * await ensureSupported("SIGHUP");
846
- * // On Windows: throws with HTTP fallback guidance
847
- * // On POSIX: passes through
848
- * ```
849
- */
850
- declare function ensureSupported(signalName: string, options?: GuardOptions): Promise<void>;
851
- /**
852
- * Ensure platform supports signal-based exit codes
853
- *
854
- * Throws an error if the platform doesn't support the POSIX 128+N exit code pattern.
855
- * Use this when exit code semantics are critical to application logic.
856
- *
857
- * @throws {FoundryCatalogError} If platform doesn't support signal exit codes
858
- *
859
- * @example
860
- * ```typescript
861
- * ensureSignalExitCodesSupported();
862
- * // On Windows: throws with guidance
863
- * // On POSIX: passes through
864
- * ```
865
- */
866
- declare function ensureSignalExitCodesSupported(): void;
867
- /**
868
- * Ensure platform is POSIX
869
- *
870
- * Throws an error if the platform is not POSIX-compliant.
871
- * Use this for functionality that strictly requires POSIX signal semantics.
872
- *
873
- * @throws {FoundryCatalogError} If platform is not POSIX
874
- */
875
- declare function ensurePOSIX(): void;
876
- /**
877
- * Ensure platform is Windows
878
- *
879
- * Throws an error if the platform is not Windows.
880
- * Use this for Windows-specific fallback testing or functionality.
881
- *
882
- * @throws {FoundryCatalogError} If platform is not Windows
883
- */
884
- declare function ensureWindows(): void;
885
-
886
- /**
887
- * HTTP Signal Endpoint Helper
888
- *
889
- * Framework-agnostic scaffold for POST /admin/signal endpoint.
890
- * Applications provide auth/rate-limiting; helper handles validation and execution.
891
- */
892
-
893
- /**
894
- * Signal request payload
895
- */
896
- interface SignalRequest {
897
- signal: string;
898
- reason?: string;
899
- correlation_id?: string;
900
- }
901
- /**
902
- * Signal response (success)
903
- */
904
- interface SignalResponse {
905
- status: "accepted";
906
- signal: string;
907
- correlation_id: string;
908
- message: string;
909
- }
910
- /**
911
- * Signal error response
912
- */
913
- interface SignalErrorResponse {
914
- status: "error";
915
- error: string;
916
- message: string;
917
- valid_signals?: string[];
918
- }
919
- /**
920
- * Authentication result
921
- */
922
- interface AuthResult {
923
- authenticated: boolean;
924
- identity?: string;
925
- reason?: string;
926
- }
927
- /**
928
- * Rate limit result
929
- */
930
- interface RateLimitResult {
931
- allowed: boolean;
932
- remaining?: number;
933
- reset_at?: number;
934
- }
935
- /**
936
- * Authentication hook function
937
- *
938
- * Applications must provide this to validate requests.
939
- * Returns authentication result with optional identity.
940
- */
941
- type AuthHook = (req: unknown) => Promise<AuthResult> | AuthResult;
942
- /**
943
- * Rate limiting hook function
944
- *
945
- * Applications may provide this to enforce rate limits.
946
- * Returns whether request is allowed and quota info.
947
- */
948
- type RateLimitHook = (identity: string, signal: string) => Promise<RateLimitResult> | RateLimitResult;
949
- /**
950
- * Signal endpoint options
951
- */
952
- interface SignalEndpointOptions {
953
- /**
954
- * Signal manager instance
955
- */
956
- manager: SignalManager;
957
- /**
958
- * Authentication hook (required)
959
- */
960
- auth: AuthHook;
961
- /**
962
- * Rate limiting hook (optional)
963
- */
964
- rateLimit?: RateLimitHook;
965
- /**
966
- * Logger for endpoint events
967
- */
968
- logger?: FallbackLogger;
969
- /**
970
- * Telemetry emitter
971
- */
972
- telemetry?: TelemetryEmitter;
973
- /**
974
- * Allowed signals (default: all catalog signals)
975
- */
976
- allowedSignals?: string[];
977
- }
978
- /**
979
- * Create a framework-agnostic signal endpoint handler
980
- *
981
- * Returns an async function that processes signal requests.
982
- * Applications wire this to their HTTP framework (Express, Fastify, etc.)
983
- *
984
- * @param options - Endpoint configuration
985
- *
986
- * @example Express
987
- * ```typescript
988
- * const handler = createSignalEndpoint({
989
- * manager,
990
- * auth: async (req) => {
991
- * const token = req.headers.authorization?.split(' ')[1];
992
- * return { authenticated: token === process.env.ADMIN_TOKEN };
993
- * },
994
- * });
995
- *
996
- * app.post('/admin/signal', async (req, res) => {
997
- * const result = await handler(req.body, req);
998
- * res.status(result.status === 'accepted' ? 202 : result.statusCode || 400)
999
- * .json(result);
1000
- * });
1001
- * ```
1002
- *
1003
- * @example Fastify
1004
- * ```typescript
1005
- * const handler = createSignalEndpoint({ manager, auth });
1006
- *
1007
- * fastify.post('/admin/signal', async (request, reply) => {
1008
- * const result = await handler(request.body, request);
1009
- * reply.status(result.status === 'accepted' ? 202 : 400).send(result);
1010
- * });
1011
- * ```
1012
- */
1013
- declare function createSignalEndpoint(options: SignalEndpointOptions): (payload: SignalRequest, req: unknown) => Promise<(SignalResponse | SignalErrorResponse) & {
1014
- statusCode?: number;
1015
- }>;
1016
- /**
1017
- * Create a simple bearer token auth hook
1018
- *
1019
- * Validates requests against a static token.
1020
- * For production, use mTLS or more robust auth.
1021
- *
1022
- * @param expectedToken - Expected bearer token
1023
- *
1024
- * @example
1025
- * ```typescript
1026
- * const auth = createBearerTokenAuth(process.env.ADMIN_TOKEN);
1027
- * const handler = createSignalEndpoint({ manager, auth });
1028
- * ```
1029
- */
1030
- declare function createBearerTokenAuth(expectedToken: string): AuthHook;
1031
- /**
1032
- * Create a simple in-memory rate limiter
1033
- *
1034
- * Tracks requests per identity with sliding window.
1035
- * For production, use Redis or distributed rate limiting.
1036
- *
1037
- * @param requestsPerMinute - Max requests per minute per identity
1038
- *
1039
- * @example
1040
- * ```typescript
1041
- * const rateLimit = createSimpleRateLimiter(10); // 10 req/min
1042
- * const handler = createSignalEndpoint({ manager, auth, rateLimit });
1043
- * ```
1044
- */
1045
- declare function createSimpleRateLimiter(requestsPerMinute: number): RateLimitHook;
1046
-
1047
- /**
1048
- * Configuration Reload Helpers
1049
- *
1050
- * Implements restart-based config reload pattern with mandatory schema validation.
1051
- * Per Crucible standard: validate before restart, reject invalid configs without disruption.
1052
- */
1053
-
1054
- /**
1055
- * Configuration validator function type
1056
- *
1057
- * Applications provide this function to validate new config against schema.
1058
- * Should return validation result with errors if invalid.
1059
- */
1060
- type ConfigValidator<T = unknown> = (config: T) => Promise<ConfigValidationResult> | ConfigValidationResult;
1061
- /**
1062
- * Configuration validation result
1063
- */
1064
- interface ConfigValidationResult {
1065
- valid: boolean;
1066
- errors?: Array<{
1067
- path: string;
1068
- message: string;
1069
- }>;
1070
- }
1071
- /**
1072
- * Configuration loader function type
1073
- *
1074
- * Applications provide this function to load new config from disk/environment.
1075
- */
1076
- type ConfigLoader<T = unknown> = () => Promise<T> | T;
1077
- /**
1078
- * Config reload options
1079
- */
1080
- interface ConfigReloadOptions<T = unknown> {
1081
- /**
1082
- * Config loader function
1083
- */
1084
- loader: ConfigLoader<T>;
1085
- /**
1086
- * Schema validator function
1087
- */
1088
- validator: ConfigValidator<T>;
1089
- /**
1090
- * Callback invoked after successful validation, before exit
1091
- * Use for cleanup, logging, etc.
1092
- */
1093
- onValidated?: (config: T) => void | Promise<void>;
1094
- /**
1095
- * Exit code for successful reload (default: 129 for SIGHUP)
1096
- */
1097
- exitCode?: number;
1098
- /**
1099
- * Logger for reload events
1100
- */
1101
- logger?: FallbackLogger;
1102
- /**
1103
- * Telemetry emitter
1104
- */
1105
- telemetry?: TelemetryEmitter;
1106
- /**
1107
- * Test mode (prevents process.exit)
1108
- */
1109
- testMode?: boolean;
1110
- }
1111
- /**
1112
- * Config reload result (for testing)
1113
- */
1114
- interface ConfigReloadResult {
1115
- reloaded: boolean;
1116
- validationErrors?: Array<{
1117
- path: string;
1118
- message: string;
1119
- }>;
1120
- error?: Error;
1121
- }
1122
- /**
1123
- * Create a config reload handler with schema validation
1124
- *
1125
- * Returns a signal handler function that implements restart-based reload:
1126
- * 1. Load new config
1127
- * 2. Validate against schema (mandatory)
1128
- * 3. If invalid: log errors, continue with current config
1129
- * 4. If valid: invoke callback, exit for restart
1130
- *
1131
- * @param options - Reload configuration
1132
- *
1133
- * @example
1134
- * ```typescript
1135
- * const reloadHandler = createConfigReloadHandler({
1136
- * loader: () => loadConfig('./config.yaml'),
1137
- * validator: (config) => validateConfigSchema(config),
1138
- * onValidated: async (config) => {
1139
- * logger.info('Config validated, restarting...');
1140
- * },
1141
- * logger: myLogger,
1142
- * });
1143
- *
1144
- * await manager.register('SIGHUP', reloadHandler);
1145
- * ```
1146
- */
1147
- declare function createConfigReloadHandler<T = unknown>(options: ConfigReloadOptions<T>): () => Promise<void>;
1148
- /**
1149
- * Three-strikes failure tracker
1150
- *
1151
- * Tracks consecutive config reload failures and triggers alerts.
1152
- * Useful for detecting persistent config source issues.
1153
- */
1154
- declare class ConfigReloadTracker {
1155
- private failures;
1156
- private lastFailureTime;
1157
- private readonly maxFailures;
1158
- private readonly logger?;
1159
- private readonly telemetry?;
1160
- constructor(options: {
1161
- maxFailures?: number;
1162
- logger?: FallbackLogger;
1163
- telemetry?: TelemetryEmitter;
1164
- });
1165
- /**
1166
- * Record a reload failure
1167
- *
1168
- * @returns true if threshold exceeded, false otherwise
1169
- */
1170
- recordFailure(): boolean;
1171
- /**
1172
- * Record a successful reload (resets counter)
1173
- */
1174
- recordSuccess(): void;
1175
- /**
1176
- * Get current failure count
1177
- */
1178
- getFailureCount(): number;
1179
- /**
1180
- * Get last failure timestamp
1181
- */
1182
- getLastFailureTime(): number | null;
1183
- }
1184
-
1185
522
  /**
1186
523
  * Foundry module - Main exports
1187
524
  *
@@ -1191,4 +528,4 @@ declare class ConfigReloadTracker {
1191
528
  */
1192
529
  declare const VERSION = "0.1.1";
1193
530
 
1194
- export { type AuthHook, type AuthResult, BehaviorInfo, type ConfigLoader, type ConfigReloadOptions, type ConfigReloadResult, ConfigReloadTracker, type ConfigValidationResult, type ConfigValidator, type DetectionOptions, type DoubleTapConfig, type DoubleTapState, EXIT_CODES_VERSION, type ExitCode, type ExitCodeInfo, type ExitCodeName, FallbackLogger, type GuardOptions, HandlerOptions, type Platform, type PlatformCapabilities$1 as PlatformCapabilities, type RateLimitHook, type RateLimitResult, SignalCatalog, type SignalEndpointOptions, type SignalErrorResponse, SignalHandler, SignalInfo, SignalManager, type PlatformCapabilities as SignalPlatformCapabilities, type SignalRequest, type SignalResponse, SimplifiedMode, TelemetryEmitter, VERSION, clearCountryCodeCache, clearHttpStatusCache, clearMimeTypeCache, clearPatternCache, createBearerTokenAuth, createConfigReloadHandler, createDoubleTapTracker, createSignalEndpoint, createSimpleRateLimiter, describePattern, detectMimeType, detectMimeTypeFromBuffer, detectMimeTypeFromFile, detectMimeTypeFromStream, ensurePOSIX, ensureSignalExitCodesSupported, ensureSupported, ensureWindows, exitCodeMetadata, exitCodes, getBehavior, getCountryByAlpha2, getCountryByAlpha3, getCountryByNumeric, getExitCodeInfo, getHttpStatus, getMimeType, getMimeTypeByExtension, getPattern, getPatternRegex, getPlatform, getPlatformCapabilities$1 as getPlatformCapabilities, getSignal, getSignalCatalog, getSignalNumber, getPlatformCapabilities as getSignalPlatformCapabilities, getSignalsVersion, getSimplifiedCodeDescription, getSimplifiedCodes, getStatusReason, getWindowTimeRemaining, getWindowsEvent, handleDoubleTap, isClientError, isInformational, isPOSIX$1 as isPOSIX, isRedirection, isServerError, isPOSIX as isSignalPOSIX, isWindows as isSignalWindows, isSuccess, isSupportedMimeType, isWindows$1 as isWindows, isWithinWindow, listBehaviors, listCountries, listHttpStatuses, listMimeTypes, listPatterns, listSignals, loadAllCatalogs, loadCountryCodeCatalog, loadHttpStatusCatalog, loadMimeTypeCatalog, loadPatternCatalog, mapExitCodeToSimplified, matchMagicNumber, matchPattern, onAnyShutdown, onEmergencyQuit, onReload, onShutdown, onUSR1, onUSR2, resetDoubleTap, supportsSignal, supportsSignalExitCodes as supportsSignalBasedExitCodes, supportsSignalExitCodes$1 as supportsSignalExitCodes };
531
+ export { type DetectionOptions, EXIT_CODES_VERSION, type ExitCode, type ExitCodeInfo, type ExitCodeName, type PlatformCapabilities, SimplifiedMode, VERSION, clearCountryCodeCache, clearHttpStatusCache, clearMimeTypeCache, clearPatternCache, describePattern, detectMimeType, detectMimeTypeFromBuffer, detectMimeTypeFromFile, detectMimeTypeFromStream, exitCodeMetadata, exitCodes, getCountryByAlpha2, getCountryByAlpha3, getCountryByNumeric, getExitCodeInfo, getHttpStatus, getMimeType, getMimeTypeByExtension, getPattern, getPatternRegex, getPlatform, getPlatformCapabilities, getSimplifiedCodeDescription, getSimplifiedCodes, getStatusReason, isClientError, isInformational, isPOSIX, isRedirection, isServerError, isSuccess, isSupportedMimeType, isWindows, listCountries, listHttpStatuses, listMimeTypes, listPatterns, loadAllCatalogs, loadCountryCodeCatalog, loadHttpStatusCatalog, loadMimeTypeCatalog, loadPatternCatalog, mapExitCodeToSimplified, matchMagicNumber, matchPattern, supportsSignalExitCodes };