@fulmenhq/tsfulmen 0.1.13 → 0.2.0

package/config/crucible-ts/agentic/roles/uxdev.yaml

@@ -0,0 +1,168 @@
+# yaml-language-server: $schema=https://schemas.3leaps.dev/agentic/v0/role-prompt.schema.json
+slug: uxdev
+name: UX Developer
+description: User experience, frontend interfaces, TUI and web development
+version: 1.0.0
+author: entarch
+status: approved
+category: agentic
+tags:
+  - role
+  - frontend
+  - ux
+  - tui
+  - web
+  - accessibility
+  - user-interface
+context: |
+  Use this role for user-facing interface work across terminals and browsers.
+  The uxdev role bridges design thinking with implementation, ensuring interfaces
+  are intuitive, accessible, and performant.
+
+  Covers both:
+  - Terminal User Interfaces (TUI): tview (Go), textual (Python), ink/opentui (Node), ratatui (Rust)
+  - Web frontends: React, Vue, Svelte, vanilla JS/TS, HTMX
+
+  Key patterns:
+  - TUI: Model-View-Update, command pattern for async, viewport/resize handling
+  - Web: Component composition, controlled vs uncontrolled, optimistic updates
+  - Accessibility: Semantic HTML first, focus management, live regions, color independence
+
+  Recommended tools by language:
+  - Go TUI: tview, tcell
+  - Python TUI: textual, rich
+  - TypeScript TUI: ink, opentui
+  - Rust TUI: ratatui, crossterm
+  - Web styling: Tailwind, CSS Modules, vanilla-extract
+  - Web state: zustand (React), pinia (Vue), svelte-stores
+  - Testing: vitest, playwright, storybook
+
+  Distinct from:
+  - devlead: Focuses on backend/full-stack (uxdev specializes in user-facing layers)
+  - infoarch: Focuses on documentation (uxdev focuses on interactive interfaces)
+  - dataeng: Focuses on data pipelines (uxdev consumes APIs, doesn't design them)
+scope:
+  - Terminal user interface design and implementation
+  - Web frontend architecture and components
+  - User interaction patterns and flows
+  - Accessibility (a11y) compliance and testing
+  - Responsive design and layout systems
+  - State management patterns
+  - Component library development
+  - CSS/styling architecture (Tailwind, CSS-in-JS, vanilla CSS)
+  - Frontend performance optimization
+  - Cross-browser/cross-terminal compatibility
+mindset:
+  focus:
+    - How will users actually interact with this?
+    - Is the interface discoverable without documentation?
+    - Does this work for users with different abilities?
+    - Is the feedback immediate and clear?
+    - Does the layout scale across screen sizes/terminal dimensions?
+    - Is the state management predictable?
+  principles:
+    - User needs drive interface decisions
+    - Progressive enhancement over graceful degradation
+    - Accessibility is not optional
+    - Minimize cognitive load
+    - Consistent patterns reduce learning curve
+    - Performance is a feature
+    - Test on real devices and terminals
+responsibilities:
+  - Design and implement user interfaces (TUI and web)
+  - Ensure WCAG 2.1 AA accessibility compliance for web
+  - Implement keyboard navigation and screen reader support
+  - Create responsive layouts that adapt to viewport/terminal size
+  - Build reusable component libraries with clear APIs
+  - Optimize frontend performance (bundle size, render time, FPS)
+  - Implement proper loading states, error states, and empty states
+  - Write component tests (unit, visual regression, e2e)
+  - Document component APIs and usage patterns
+  - Coordinate with devlead on API contracts and data shapes
+escalates_to:
+  - target: devlead
+    when: API changes needed to support UI requirements
+  - target: human maintainers
+    when: Major UX pattern changes affecting user workflows
+  - target: secrev
+    when: Security-sensitive UI (auth flows, PII display, input sanitization)
+  - target: entarch
+    when: Design system decisions affecting multiple repositories
+  - target: human maintainers
+    when: Third-party dependency additions (new frameworks, component libraries)
+does_not:
+  - Skip accessibility requirements
+  - Implement custom solutions when native elements suffice
+  - Add heavy dependencies without justification
+  - Ignore loading, error, and empty states
+  - Break keyboard navigation
+  - Create interfaces that require mouse/touch (TUI must be keyboard-first)
+  - Skip visual testing for component changes
+  - Modify backend code beyond API consumption
+checklists:
+  component:
+    - "Keyboard navigable: All interactions work without mouse"
+    - "Screen reader: Proper labels, roles, and announcements"
+    - "Focus visible: Clear focus indicators on all interactive elements"
+    - "Error handling: Clear error messages with recovery guidance"
+    - "Loading states: Skeleton or spinner for async operations"
+    - "Empty states: Helpful message when no data"
+    - "Responsive: Works across viewport sizes / terminal dimensions"
+    - "Tests: Unit tests for logic, visual tests for appearance"
+  tui_specific:
+    - "Resize handling: Adapts to terminal size changes"
+    - "Exit handling: Clean shutdown on Ctrl+C, q, or Escape"
+    - "Help: Discoverable keybindings (? or F1)"
+    - "Status line: Current state and available actions visible"
+    - "Color fallback: Works in 16-color and no-color modes"
+  web_specific:
+    - "Lighthouse: Performance score > 90"
+    - "Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1"
+    - "Bundle size: Justified, code-split where possible"
+    - "SEO: Proper meta tags, semantic structure"
+    - "Progressive: Works with JS disabled (where applicable)"
+examples:
+  - type: commit
+    title: TUI component implementation
+    content: |
+      feat(cli): add interactive file picker component
+
+      Implements keyboard-navigable file picker using bubbletea
+      with filtering, preview, and multi-select support.
+
+      Changes:
+      - Add internal/tui/filepicker component
+      - Implement j/k navigation, Enter to select, / to filter
+      - Add file preview panel with syntax highlighting
+      - Handle terminal resize events
+      - Include unit tests for model updates
+
+      Tested on: iTerm2, Terminal.app, Windows Terminal, VS Code terminal
+
+      Generated by Claude Opus 4.5 via Claude Code under supervision of @3leapsdave
+
+      Co-Authored-By: Claude Opus 4.5 <noreply@3leaps.net>
+      Role: uxdev
+      Committer-of-Record: Dave Thompson <dave.thompson@3leaps.net> [@3leapsdave]
+  - type: commit
+    title: Web component implementation
+    content: |
+      feat(web): add accessible data table component
+
+      Implements sortable, filterable data table with full
+      keyboard navigation and screen reader support.
+
+      Changes:
+      - Add components/DataTable with column sorting
+      - Implement arrow key navigation between cells
+      - Add ARIA labels and live region announcements
+      - Include Storybook stories with a11y addon
+      - Add Playwright tests for keyboard navigation
+
+      Accessibility: WCAG 2.1 AA compliant, tested with VoiceOver and NVDA
+
+      Generated by Claude Sonnet via Claude Code under supervision of @3leapsdave
+
+      Co-Authored-By: Claude Sonnet <noreply@3leaps.net>
+      Role: uxdev
+      Committer-of-Record: Dave Thompson <dave.thompson@3leaps.net> [@3leapsdave]

package/config/crucible-ts/branding/ecosystem.yaml

@@ -0,0 +1,26 @@
+# Fulmen Ecosystem Brand Summary
+#
+# Accessible via helper libraries: crucible.GetBrandSummary()
+#
+# Display options (tools implement one or both):
+#   - CLI: `<binary> version --extended` or `<binary> about`
+#   - Server: GET /about endpoint
+#
+# Keep summaries factual and informative, not marketing-speak.
+$schema: "https://schemas.fulmenhq.dev/crucible/branding/v1.0.0/ecosystem.schema.json"
+version: "1.0.0"
+# One-line motto for /about and version --extended
+motto: "Fulmen - Thrive on Scale"
+# Extended motto (alternative)
+motto_extended: "Fulmen - Start Fast. Thrive on Scale."
+# Attribution line
+built_by: "Built by 3 Leaps, LLC"
+# Primary URL (will add codex URL when available)
+url: "https://3leaps.net"
+# Structured metadata for programmatic access
+metadata:
+  org: "fulmenhq"
+  maintainer: "3 Leaps, LLC"
+  url: "https://3leaps.net"
+  source: "https://github.com/fulmenhq"
+  tagline: "Thrive on Scale"

package/config/crucible-ts/library/foundry/exit-codes.snapshot.json

@@ -280,6 +280,32 @@
       "description": "Test coverage below required threshold",
       "context": "Code coverage validation, quality gate failure"
     },
+    "124": {
+      "name": "EXIT_TIMEOUT",
+      "category": "shell",
+      "description": "Command timed out before completion",
+      "context": "GNU timeout or similar utility terminated command after deadline"
+    },
+    "125": {
+      "name": "EXIT_TIMEOUT_INTERNAL",
+      "category": "shell",
+      "description": "Timeout utility itself failed",
+      "context": "Error in timeout tool before or during command execution (not command failure)"
+    },
+    "126": {
+      "name": "EXIT_CANNOT_EXECUTE",
+      "category": "shell",
+      "description": "Command found but could not be executed",
+      "context": "Permission denied, not executable, exec format error",
+      "bsd_equivalent": "EX_NOPERM (partial)"
+    },
+    "127": {
+      "name": "EXIT_NOT_FOUND",
+      "category": "shell",
+      "description": "Command not found",
+      "context": "Executable not found in PATH or specified path does not exist",
+      "bsd_equivalent": "EX_UNAVAILABLE (partial)"
+    },
     "129": {
       "name": "EXIT_SIGNAL_HUP",
       "category": "signals",

package/config/crucible-ts/library/foundry/exit-codes.yaml

@@ -285,6 +285,31 @@ categories:
         name: EXIT_COVERAGE_THRESHOLD_NOT_MET
         description: Test coverage below required threshold
         context: Code coverage validation, quality gate failure
+  - id: shell
+    name: Shell & Process Control
+    description: Exit codes from shell conventions and process control utilities (timeout, exec)
+    range:
+      min: 124
+      max: 127
+    codes:
+      - code: 124
+        name: EXIT_TIMEOUT
+        description: Command timed out before completion
+        context: GNU timeout or similar utility terminated command after deadline
+      - code: 125
+        name: EXIT_TIMEOUT_INTERNAL
+        description: Timeout utility itself failed
+        context: Error in timeout tool before or during command execution (not command failure)
+      - code: 126
+        name: EXIT_CANNOT_EXECUTE
+        description: Command found but could not be executed
+        context: Permission denied, not executable, exec format error
+        bsd_equivalent: EX_NOPERM (partial)
+      - code: 127
+        name: EXIT_NOT_FOUND
+        description: Command not found
+        context: Executable not found in PATH or specified path does not exist
+        bsd_equivalent: EX_UNAVAILABLE (partial)
   - id: signals
     name: Signal-Induced Exits
     description: |-
@@ -449,7 +474,7 @@ simplified_modes:
         maps_from: [0]
       - simplified_code: 1
         simplified_name: ERROR
-        maps_from: [1, 10, 11, 12, 13, 14, 15, 20, 21, 22, 23, 24, 30, 31, 32, 33, 34, 40, 41, 50, 51, 52, 53, 54, 60, 61, 62, 63, 70, 71, 72, 73, 80, 81, 82, 83, 84, 91, 92, 93, 94, 95, 96, 129, 130, 131, 137, 138, 140, 141, 142, 143]
+        maps_from: [1, 10, 11, 12, 13, 14, 15, 20, 21, 22, 23, 24, 30, 31, 32, 33, 34, 40, 41, 50, 51, 52, 53, 54, 60, 61, 62, 63, 70, 71, 72, 73, 80, 81, 82, 83, 84, 91, 92, 93, 94, 95, 96, 124, 125, 126, 127, 129, 130, 131, 137, 138, 140, 141, 142, 143]
       - simplified_code: 2
         simplified_name: USAGE_ERROR
         maps_from: [64]
@@ -468,10 +493,10 @@ simplified_modes:
         maps_from: [20, 21, 22, 23, 24]
       - simplified_code: 3
         simplified_name: RUNTIME_ERROR
-        maps_from: [30, 31, 32, 33, 34, 60, 61, 62, 63]
+        maps_from: [30, 31, 32, 33, 34, 60, 61, 62, 63, 124]
       - simplified_code: 4
         simplified_name: SYSTEM_ERROR
-        maps_from: [10, 11, 12, 13, 14, 15, 50, 51, 52, 53, 54, 129, 130, 131, 137, 138, 140, 141, 142, 143]
+        maps_from: [10, 11, 12, 13, 14, 15, 50, 51, 52, 53, 54, 125, 126, 127, 129, 130, 131, 137, 138, 140, 141, 142, 143]
       - simplified_code: 5
         simplified_name: SECURITY_ERROR
         maps_from: [70, 71, 72, 73]

package/config/crucible-ts/library/foundry/patterns.yaml

@@ -135,7 +135,7 @@ patterns:
     pattern: '^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$'
     description: 'JWT compact serialization (header.payload.signature).'
     examples:
-      - 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+      - 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U'
   - id: strict-iso-date
     name: ISO Date (YYYY-MM-DD)
     kind: regex
@@ -157,7 +157,7 @@ patterns:
     pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
     description: 'RFC 4122 version 4 UUID.'
     examples:
-      - '123e4567-e89b-12d3-a456-426614174000'
+      - '123e4567-e89b-42d3-a456-426614174000'
   - id: ulid
     name: ULID
     kind: regex

package/config/crucible-ts/library/foundry/signal-resolution-fixtures.yaml

@@ -0,0 +1,207 @@
+$schema: https://schemas.fulmenhq.dev/library/foundry/v1.0.0/signal-resolution-fixtures.schema.json
+description: Cross-language test vectors for signal name resolution
+version: v1.0.0
+# Origin: rsfulmen memo 2026-01-08, standardized for ecosystem-wide adoption
+# See: docs/standards/library/foundry/interfaces.md#signal-resolution
+
+resolve_signal_tests:
+  # Exact match (step 3)
+  - input: "SIGTERM"
+    expect_name: "SIGTERM"
+    description: Exact catalog name match
+  - input: "SIGINT"
+    expect_name: "SIGINT"
+    description: Exact catalog name match
+  - input: "SIGHUP"
+    expect_name: "SIGHUP"
+    description: Exact catalog name match
+  # Numeric match (step 4)
+  - input: "15"
+    expect_name: "SIGTERM"
+    description: Numeric lookup by unix_number
+  - input: "2"
+    expect_name: "SIGINT"
+    description: Numeric lookup by unix_number
+  - input: "1"
+    expect_name: "SIGHUP"
+    description: Numeric lookup by unix_number
+  - input: "9"
+    expect_name: "SIGKILL"
+    description: Numeric lookup by unix_number
+  - input: "  15  "
+    expect_name: "SIGTERM"
+    description: Numeric with whitespace trimmed
+  # Lowercase with prefix (step 5)
+  - input: "sigterm"
+    expect_name: "SIGTERM"
+    description: Lowercase full name
+  - input: "sigint"
+    expect_name: "SIGINT"
+    description: Lowercase full name
+  # Without SIG prefix - uppercase (step 5)
+  - input: "TERM"
+    expect_name: "SIGTERM"
+    description: Without SIG prefix (uppercase)
+  - input: "INT"
+    expect_name: "SIGINT"
+    description: Without SIG prefix (uppercase)
+  - input: "HUP"
+    expect_name: "SIGHUP"
+    description: Without SIG prefix (uppercase)
+  - input: "KILL"
+    expect_name: "SIGKILL"
+    description: Without SIG prefix (uppercase)
+  # Without SIG prefix - lowercase (step 5)
+  - input: "term"
+    expect_name: "SIGTERM"
+    description: Without SIG prefix (lowercase)
+  - input: "int"
+    expect_name: "SIGINT"
+    description: Without SIG prefix (lowercase)
+  - input: "kill"
+    expect_name: "SIGKILL"
+    description: Without SIG prefix (lowercase)
+  # Mixed case (step 5)
+  - input: "SigTerm"
+    expect_name: "SIGTERM"
+    description: Mixed case with prefix
+  - input: "Term"
+    expect_name: "SIGTERM"
+    description: Mixed case without prefix
+  - input: "SigInt"
+    expect_name: "SIGINT"
+    description: Mixed case with prefix
+  # Whitespace trimmed (step 1)
+  - input: "  SIGTERM  "
+    expect_name: "SIGTERM"
+    description: Leading/trailing whitespace
+  - input: "\tterm\n"
+    expect_name: "SIGTERM"
+    description: Tab and newline whitespace
+  - input: "  sigint  "
+    expect_name: "SIGINT"
+    description: Whitespace with lowercase
+  # ID fallback (step 6)
+  - input: "hup"
+    expect_name: "SIGHUP"
+    description: ID lookup fallback
+  - input: "usr1"
+    expect_name: "SIGUSR1"
+    description: ID lookup fallback
+  - input: "usr2"
+    expect_name: "SIGUSR2"
+    description: ID lookup fallback
+  - input: "quit"
+    expect_name: "SIGQUIT"
+    description: ID lookup fallback
+  - input: "pipe"
+    expect_name: "SIGPIPE"
+    description: ID lookup fallback
+  - input: "alrm"
+    expect_name: "SIGALRM"
+    description: ID lookup fallback
+  # Unknown returns null (step 7)
+  - input: "SIGFOO"
+    expect_name: null
+    description: Unknown signal name
+  - input: "FOO"
+    expect_name: null
+    description: Unknown signal without prefix
+  - input: "999"
+    expect_name: null
+    description: Unknown numeric signal
+  # Negative numbers not supported (step 4)
+  - input: "-15"
+    expect_name: null
+    description: Negative numbers not supported
+  - input: "-1"
+    expect_name: null
+    description: Negative numbers not supported
+  # Empty returns null (step 2)
+  - input: ""
+    expect_name: null
+    description: Empty string
+  - input: "   "
+    expect_name: null
+    description: Whitespace-only string
+list_signal_names_tests:
+  # Note: expect_contains verifies required signals; expect_min_count is a sanity check.
+  # If catalog grows, add new signals to expect_contains rather than bumping min_count.
+  - description: Returns all catalog signal names
+    expect_contains:
+      - "SIGTERM"
+      - "SIGINT"
+      - "SIGHUP"
+      - "SIGKILL"
+      - "SIGQUIT"
+      - "SIGPIPE"
+      - "SIGALRM"
+      - "SIGUSR1"
+      - "SIGUSR2"
+    expect_min_count: 1
+match_signal_names_tests:
+  # Wildcard all
+  - pattern: "*"
+    description: Match all signals
+    expect_equals_list_signal_names: true
+  # Prefix match
+  - pattern: "SIG*"
+    description: All signals start with SIG
+    expect_contains:
+      - "SIGTERM"
+      - "SIGINT"
+      - "SIGHUP"
+    expect_min_count: 1
+  # Suffix match
+  - pattern: "*TERM"
+    description: Suffix match for TERM
+    expect_contains:
+      - "SIGTERM"
+  # Contains match
+  - pattern: "*USR*"
+    description: Contains USR
+    expect_contains:
+      - "SIGUSR1"
+      - "SIGUSR2"
+    expect_count: 2
+  # Single char wildcard
+  - pattern: "SIG???"
+    description: SIG followed by exactly 3 characters
+    expect_contains:
+      - "SIGINT"
+      - "SIGHUP"
+    expect_not_contains:
+      - "SIGTERM"
+      - "SIGKILL"
+      - "SIGUSR1"
+  - pattern: "SIG????"
+    description: SIG followed by exactly 4 characters
+    expect_contains:
+      - "SIGTERM"
+      - "SIGKILL"
+      - "SIGQUIT"
+      - "SIGPIPE"
+      - "SIGALRM"
+    expect_not_contains:
+      - "SIGINT"
+      - "SIGHUP"
+  # Case insensitive
+  - pattern: "sig*"
+    description: Case insensitive - lowercase pattern
+    expect_contains:
+      - "SIGTERM"
+      - "SIGINT"
+    expect_min_count: 1
+  - pattern: "Sig*"
+    description: Case insensitive - mixed case pattern
+    expect_contains:
+      - "SIGTERM"
+      - "SIGINT"
+    expect_min_count: 1
+  # No match
+  - pattern: "XYZZY*"
+    description: Pattern with no matches
+    expect_empty: true
+  - pattern: "FOO???"
+    description: Pattern with no matches (single char wildcards)
+    expect_empty: true

package/config/crucible-ts/library/foundry/signals.yaml

@@ -153,6 +153,20 @@ signals:
         signal: SIGUSR2
         platform: windows
         fallback_behavior: http_admin_endpoint
+  - id: kill
+    name: SIGKILL
+    unix_number: 9
+    windows_event: null
+    description: Force immediate termination - cannot be caught, blocked, or ignored
+    default_behavior: immediate_exit
+    exit_code: 137 # 128 + 9
+    timeout_seconds: 0
+    cleanup_actions: []
+    usage_notes: |
+      SIGKILL terminates a process immediately without allowing cleanup.
+      Use only as a last resort after SIGTERM grace period expires. The process
+      has no opportunity to save state, close files, or release resources.
+      On Windows, use TerminateProcess() for single process or TerminateJobObject() for groups.
 behaviors:
   - id: graceful_shutdown
     name: Graceful Shutdown
@@ -318,12 +332,19 @@ platform_support:
     windows: unsupported
     fallback: http_admin_endpoint
     notes: Signal number varies by platform. On Windows, use HTTP POST /admin/signal with signal=USR2
+  - signal: SIGKILL
+    linux: native
+    macos: native
+    freebsd: native
+    windows: mapped
+    notes: Cannot be caught or ignored. Windows uses TerminateProcess/TerminateJobObject.
 # Exit code mappings (128+N pattern per POSIX)
 exit_codes:
   SIGTERM: 143 # 128 + 15
   SIGINT: 130 # 128 + 2
   SIGHUP: 129 # 128 + 1
   SIGQUIT: 131 # 128 + 3
+  SIGKILL: 137 # 128 + 9
   SIGPIPE: 141 # 128 + 13
   SIGALRM: 142 # 128 + 14
   SIGUSR1: 138 # 128 + 10

package/config/crucible-ts/library/foundry/simplified-modes.snapshot.json

@@ -49,6 +49,10 @@
         94,
         95,
         96,
+        124,
+        125,
+        126,
+        127,
         129,
         130,
         131,
@@ -88,7 +92,8 @@
         60,
         61,
         62,
-        63
+        63,
+        124
       ],
       "4": [
         10,
@@ -102,6 +107,9 @@
         52,
         53,
         54,
+        125,
+        126,
+        127,
         129,
         130,
         131,

package/config/crucible-ts/library/{foundry/similarity-fixtures.yaml → similarity/fixtures.yaml}

@@ -1,4 +1,4 @@
-$schema: https://schemas.fulmenhq.dev/library/foundry/v2.0.0/similarity.schema.json
+$schema: https://schemas.fulmenhq.dev/library/similarity/v2.0.0/similarity.schema.json
 version: 2025.10.3
 notes: |
   Fixture values computed by pyfulmen using Rust strsim 0.11.x (canonical)

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

@@ -166,8 +166,7 @@ languageOverrides:
       - config-path-api
       - schema-validation
       - crucible-shim
-      - foundry
-    notes: "rsfulmen planned post-logging stabilization; extensions deferred."
+    notes: "rsfulmen foundation enabled v0.2.21; codegen artifacts active."
   - language: csharp
     planned:
       - config-path-api