@fulmenhq/tsfulmen 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -14,6 +14,29 @@ _No unreleased changes._
 
 ---
 
+## [0.3.3] - 2026-06-17
+
+> **Patch — compile-safety ergonomics.** Two purely-additive API options that let `bun --compile` single-file binary consumers register a build-embedded identity and load embedded config without per-consumer workarounds — ahead of the larger v0.4.0 SSOT-asset-embedding work. No breaking changes; the existing exported `LoadConfigOptions` shape is unchanged; engine floor unchanged (`>=22.12.0`). Full details in `docs/releases/v0.3.3.md`.
+
+### Added
+
+- **`skipValidation` on `registerEmbeddedIdentity(data, options?)`** — symmetric with the existing `loadIdentity({ skipValidation })`. Lets a `bun --compile` binary register a CI-validated embedded identity without hitting the filesystem-backed schema registry (absent in a single-file binary). Parse / first-wins / deep-freeze semantics are unchanged; only schema validation is gated. New `RegisterEmbeddedIdentityOptions` type exported from `appidentity`.
+- **Inline `defaults` / `schema` on `loadConfig`** — provide a pre-parsed `defaults` object and/or an inline `schema` string instead of file paths, so consumers embedding config at build time needn't write content to a temp file just to pass a path. Exposed via a new `LoadInlineConfigOptions` shape and a `loadConfig` overload; `defaults` is `structuredClone`'d so callers' embedded objects are never mutated.
+
+### Changed
+
+- **`loadConfig` options split into path-based and inline shapes** (additive). `LoadConfigOptions` keeps `defaultsPath: string` (required) exactly as before; the new `LoadInlineConfigOptions` carries `defaults` (required). Both extend a shared `BaseLoadConfigOptions` and are mutually exclusive at the type level (`?: never`); `loadConfig` is overloaded over the two. The existing exported `LoadConfigOptions` is unchanged — patch-compatible for strict TypeScript consumers.
+- **`ConfigMetadata` diagnostics** — adds optional `defaultsSource: "path" | "inline"` and `schema.source: "path" | "inline" | null`. `defaultsPath` stays typed `string` (reports `""` for inline). Fixes a bug where, when both inline `schema` and `schemaPath` were given, `schema.path` mis-reported the unused `schemaPath` — inline now correctly reports `path: null`.
+
+## [0.3.2] - 2026-06-17
+
+> **Patch — app-identity follow-up.** Syncs the Crucible SSOT to v0.4.14 (which adds the formal `metadata.typescript` app-identity section) and promotes tsfulmen's interim custom `metadata.console_scripts` field to it. No code or behavior change; the only published delta is the refreshed bundled `crucible-ts` schemas. Full details in `docs/releases/v0.3.2.md`.
+
+### Changed
+
+- **Synced Crucible SSOT `v0.4.13 → v0.4.14`** (`.goneat/ssot-consumer.yaml` ref). Refreshes the bundled app-identity assets under `schemas/crucible-ts`, `config/crucible-ts`, and `docs/crucible-ts` — the schema now carries the optional `metadata.typescript` object (npm analogue of `metadata.python`: `package_name` + `console_scripts → package.json bin`), plus the `typescript-package` fixture and parity case.
+- **Promoted `.fulmen/app.yaml` to `metadata.typescript`** — the package's three bins (`tsfulmen-schema`, `tsfulmen-signals`, `tsfulmen-prometheus`) move from the interim custom `metadata.console_scripts` field to the first-class `metadata.typescript` section now that Crucible defines it. (`.fulmen/app.yaml` is the repo's own identity and is not in the npm `files` payload.)
+
 ## [0.3.1] - 2026-06-15
 
 > **Patch — compile-safety.** Makes tsfulmen safe to embed in `bun build --compile` single-file binaries. Fixes two blockers surfaced downstream by `forge-workhorse-tuvan`: the embedded CLIs shadowed the consumer's own program on import, and an eager WASM load crashed compiled binaries at startup. No breaking changes; Node engine floor unchanged (`>=22.12.0`). Shipped as five reviewed PRs (#13, #14, #15, #16, #17). Full details in `docs/releases/v0.3.1.md`.

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

@@ -37,6 +37,14 @@ metadata:
         entry_point: percheron.cli:main
       - name: percheron-validate
         entry_point: percheron.validation:cli
+  # TypeScript/npm packaging metadata (for npm projects — alternative to python)
+  # typescript:
+  #   # npm package name (scoped or unscoped)
+  #   package_name: "@fulmenhq/tsfulmen"
+  #   # Executable bin entries — map to package.json `bin`
+  #   console_scripts:
+  #     - name: tsfulmen-schema
+  #       entry_point: ./dist/bin/schema-cli.js
 
 # Additional custom fields allowed for extensibility
 # custom_field: value

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

@@ -0,0 +1,17 @@
+# Valid application identity exercising metadata.typescript (npm packaging)
+app:
+  binary_name: tsfulmen
+  vendor: fulmenhq
+  env_prefix: TSFULMEN_
+  config_name: tsfulmen
+  description: TypeScript Fulmen SDK with developer CLIs
+metadata:
+  license: MIT
+  repository_category: sdk
+  typescript:
+    package_name: "@fulmenhq/tsfulmen"
+    console_scripts:
+      - name: tsfulmen-schema
+        entry_point: ./dist/bin/schema-cli.js
+      - name: tsfulmen-signals
+        entry_point: ./dist/bin/signals-cli.js

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

@@ -73,6 +73,34 @@
           }
         },
         "validation_result": "pass"
+      },
+      "typescript_package": {
+        "input_file": "fixtures/valid/typescript-package.yaml",
+        "expected_output": {
+          "binary_name": "tsfulmen",
+          "vendor": "fulmenhq",
+          "env_prefix": "TSFULMEN_",
+          "config_name": "tsfulmen",
+          "description": "TypeScript Fulmen SDK with developer CLIs",
+          "metadata": {
+            "license": "MIT",
+            "repository_category": "sdk",
+            "typescript": {
+              "package_name": "@fulmenhq/tsfulmen",
+              "console_scripts": [
+                {
+                  "name": "tsfulmen-schema",
+                  "entry_point": "./dist/bin/schema-cli.js"
+                },
+                {
+                  "name": "tsfulmen-signals",
+                  "entry_point": "./dist/bin/signals-cli.js"
+                }
+              ]
+            }
+          }
+        },
+        "validation_result": "pass"
       }
     },
     "invalid": {

package/config/crucible-ts/taxonomy/metrics.yaml

@@ -121,7 +121,7 @@ required:
   - version
   - metrics
 additionalProperties: false
-version: "0.4.13"
+version: "0.4.14"
 defaults:
   histogram_buckets:
     ms_metrics:

package/dist/appidentity/index.d.ts

@@ -1,5 +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 { I as Identity, R as RegisterEmbeddedIdentityOptions, L as LoadIdentityOptions } from '../types-CHDvDRCf.js';
+export { A as AppIdentity, a as IdentityMetadata, P as PythonMetadata, b as RepositoryCategory } from '../types-CHDvDRCf.js';
 import { F as FulmenError } from '../fulmen-error-B_kX8jSC.js';
 import { b as SchemaValidationDiagnostic } from '../types-DdoeE7F5.js';
 
@@ -50,10 +50,11 @@ declare const MAX_ANCESTOR_SEARCH_DEPTH = 20;
  *
  * Semantics:
  * - First registration wins (subsequent calls throw error)
- * - Validates against schema on registration
+ * - Validates against schema on registration (unless `skipValidation`)
  * - Stores as immutable process-level fallback
  *
  * @param data - YAML string or pre-parsed Identity object
+ * @param options - Optional registration options (see {@link RegisterEmbeddedIdentityOptions})
  * @throws {AppIdentityError} If already registered or validation fails
  *
  * @example
@@ -75,8 +76,17 @@ declare const MAX_ANCESTOR_SEARCH_DEPTH = 20;
  *   // Embedded identity not available - discovery will use filesystem
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // In a `bun --compile` single-file binary, the FS-backed schema registry
+ * // is unavailable. Register a build-time-embedded, CI-validated identity
+ * // without re-validating against the (absent) schema registry:
+ * import embeddedYaml from "./app-identity.embedded.js"; // inlined at build
+ * registerEmbeddedIdentity(embeddedYaml, { skipValidation: true });
+ * ```
  */
-declare function registerEmbeddedIdentity(data: string | Identity): Promise<void>;
+declare function registerEmbeddedIdentity(data: string | Identity, options?: RegisterEmbeddedIdentityOptions): Promise<void>;
 /**
  * Check if embedded identity has been registered
  *
@@ -305,4 +315,4 @@ interface BuildRuntimeInfoOptions {
  */
 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 };
+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, RegisterEmbeddedIdentityOptions, 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

@@ -1915,10 +1915,11 @@ function deepFreeze(obj) {
   });
   return obj;
 }
-async function registerEmbeddedIdentity(data) {
+async function registerEmbeddedIdentity(data, options) {
   if (isRegistered) {
     throw AppIdentityError.alreadyRegistered();
   }
+  const skipValidation = options?.skipValidation ?? false;
   let identity;
   if (typeof data === "string") {
     let parsed;
@@ -1929,15 +1930,19 @@ async function registerEmbeddedIdentity(data) {
         error instanceof Error ? error : new Error(String(error))
       );
     }
-    const result = await validateDataBySchemaId(parsed, APP_IDENTITY_SCHEMA_ID);
-    if (!result.valid) {
-      throw AppIdentityError.embeddedValidationFailed(result.diagnostics);
+    if (!skipValidation) {
+      const result = await validateDataBySchemaId(parsed, APP_IDENTITY_SCHEMA_ID);
+      if (!result.valid) {
+        throw AppIdentityError.embeddedValidationFailed(result.diagnostics);
+      }
     }
     identity = parsed;
   } else {
-    const result = await validateDataBySchemaId(data, APP_IDENTITY_SCHEMA_ID);
-    if (!result.valid) {
-      throw AppIdentityError.embeddedValidationFailed(result.diagnostics);
+    if (!skipValidation) {
+      const result = await validateDataBySchemaId(data, APP_IDENTITY_SCHEMA_ID);
+      if (!result.valid) {
+        throw AppIdentityError.embeddedValidationFailed(result.diagnostics);
+      }
     }
     identity = data;
   }