@fulmenhq/tsfulmen 0.2.0 → 0.2.3

package/dist/{types-BJswWpQC.d.ts → types-DdoeE7F5.d.ts}

@@ -113,7 +113,7 @@ interface SchemaRegistryOptions {
 /**
  * Schema input types
  */
-type SchemaInput = string | Buffer | Record<string, unknown>;
+type SchemaInput = string | Buffer | boolean | Record<string, unknown>;
 /**
  * Schema source information
  */

package/dist/types-Dv5TERCM.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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;
+}
+
+export type { AppIdentity as A, Identity as I, LoadIdentityOptions as L, PythonMetadata as P, RepositoryCategory as R, IdentityMetadata as a };

package/package.json

@@ -3,6 +3,7 @@
   "dependencies": {
     "@3leaps/string-metrics-wasm": "0.3.8",
     "ajv": "^8.17.1",
+    "ajv-draft-04": "^1.0.0",
     "ajv-formats": "^3.0.1",
     "archiver": "^7.0.1",
     "commander": "^14.0.1",
@@ -23,19 +24,19 @@
     "@types/node": "^22.9.0",
     "@types/picomatch": "^4.0.2",
     "@types/unzipper": "^0.10.11",
-    "@vitest/coverage-v8": "^4.0.7",
-    "@vitest/ui": "^2.1.5",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
     "fastify": "^5.2.0",
     "prettier": "^3.6.2",
     "prom-client": "^15.1.3",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.5"
+    "vitest": "^4.0.18"
   },
   "engines": {
-    "bun": "\u003e=1.0.0",
-    "node": "\u003e=20.0.0"
+    "bun": ">=1.0.0",
+    "node": ">=20.0.0"
   },
   "exports": {
     ".": {
@@ -74,6 +75,10 @@
       "import": "./dist/foundry/similarity/index.js",
       "types": "./dist/foundry/similarity/index.d.ts"
     },
+    "./fulencode": {
+      "import": "./dist/fulencode/index.js",
+      "types": "./dist/fulencode/index.d.ts"
+    },
     "./fulhash": {
       "import": "./dist/fulhash/index.js",
       "types": "./dist/fulhash/index.d.ts"
@@ -160,13 +165,13 @@
     "dev": "tsx src/index.ts",
     "lint": "make lint",
     "lint:fix": "make fmt",
-    "prepublishOnly": "bun run quality \u0026\u0026 bun run validate:all \u0026\u0026 bunx tsx scripts/prepare-wasm-package.ts",
+    "prepublishOnly": "bunx tsx scripts/release-guard-prepublish.ts && bun run quality && bun run validate:all && bunx tsx scripts/prepare-wasm-package.ts",
     "quality": "make quality",
     "test": "make test",
     "test:coverage": "make test-coverage",
     "test:watch": "make test-watch",
     "typecheck": "make typecheck",
-    "validate:all": "bun run validate:exports \u0026\u0026 bun run validate:tsup \u0026\u0026 bun run validate:source-modules \u0026\u0026 bun run validate:package \u0026\u0026 bun run validate:imports \u0026\u0026 bun run validate:types",
+    "validate:all": "bun run validate:exports && bun run validate:tsup && bun run validate:source-modules && bun run validate:package && bun run validate:imports && bun run validate:types",
     "validate:exports": "bunx tsx scripts/validate-exports.ts",
     "validate:imports": "bunx tsx scripts/validate-imports.ts",
     "validate:package": "bunx tsx scripts/validate-package-contents.ts",
@@ -179,5 +184,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.2.0"
+  "version": "0.2.3"
 }

package/schemas/crucible-ts/library/fulencode/v1.0.0/README.md

@@ -0,0 +1,37 @@
+# Fulencode Schemas (v1.0.0)
+
+These schemas define the SSOT contracts for the Fulencode module.
+
+Fulencode is an opt-in (Specialized-tier) facade that standardizes encoding/decoding, text encoding validation/detection, Unicode normalization, BOM handling, and security limits across Fulmen helper libraries.
+
+## Files
+
+- `fulencode-config.schema.json` - Module configuration (limits + defaults).
+
+Method option schemas:
+
+- `encode-options.schema.json`
+- `decode-options.schema.json`
+- `detect-options.schema.json`
+- `normalize-options.schema.json`
+
+Result payload schemas:
+
+- `encoding-result.schema.json`
+- `decoding-result.schema.json`
+- `detection-result.schema.json`
+- `normalization-result.schema.json`
+- `bom-result.schema.json`
+
+Error envelope:
+
+- `fulencode-error.schema.json`
+
+## Related SSOT (Taxonomies + Standard)
+
+- Standard: `docs/standards/library/modules/fulencode.md`
+- Encoding formats taxonomy: `schemas/taxonomy/library/fulencode/encoding-families/v1.0.0/families.yaml`
+- Normalization profiles taxonomy: `schemas/taxonomy/library/fulencode/normalization-profiles/v1.0.0/profiles.yaml`
+- Detection confidence taxonomy: `schemas/taxonomy/library/fulencode/detection-confidence/v1.0.0/levels.yaml`
+
+These schemas validate data structures produced by helper libraries and support cross-language parity fixtures.

package/schemas/crucible-ts/library/fulencode/v1.0.0/bom-result.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/bom-result.schema.json",
+  "title": "Fulencode BOM Result",
+  "description": "Result payload for fulencode BOM detection",
+  "type": "object",
+  "properties": {
+    "bom_type": {
+      "description": "Detected BOM type or null when none.",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "utf-8",
+            "utf-16le",
+            "utf-16be",
+            "utf-32le",
+            "utf-32be"
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "byte_length": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "encoding_implied": {
+      "description": "Encoding implied by the BOM when present.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "bom_type",
+    "byte_length",
+    "encoding_implied"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/decode-options.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/decode-options.schema.json",
+  "title": "Fulencode Decode Options",
+  "description": "Options for fulencode decode() operation",
+  "type": "object",
+  "properties": {
+    "verify_checksum": {
+      "type": "boolean",
+      "description": "Verify embedded checksum when present."
+    },
+    "compute_checksum": {
+      "type": "string",
+      "description": "Checksum algorithm to compute on decoded output.",
+      "enum": [
+        "xxh3-128",
+        "sha256",
+        "sha512",
+        "sha1",
+        "md5"
+      ]
+    },
+    "max_decoded_size": {
+      "type": "integer",
+      "description": "Maximum decoded output size in bytes.",
+      "minimum": 1024
+    },
+    "max_expansion_ratio": {
+      "type": "number",
+      "description": "Maximum decode expansion ratio (encoding bomb protection).",
+      "minimum": 1.0
+    },
+    "on_error": {
+      "type": "string",
+      "description": "Error handling mode.",
+      "enum": [
+        "strict",
+        "replace",
+        "ignore",
+        "fallback"
+      ]
+    },
+    "fallback_formats": {
+      "type": "array",
+      "description": "Fallback formats to attempt when on_error is fallback.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "ignore_whitespace": {
+      "type": "boolean",
+      "description": "Ignore ASCII whitespace in encoded input when supported."
+    },
+    "validate_padding": {
+      "type": "boolean",
+      "description": "Require correct padding when supported."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/decoding-result.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/decoding-result.schema.json",
+  "title": "Fulencode Decoding Result",
+  "description": "Result payload for fulencode decode()",
+  "type": "object",
+  "properties": {
+    "data": {
+      "type": "array",
+      "items": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 255
+      }
+    },
+    "format": {
+      "type": "string",
+      "enum": [
+        "base64",
+        "base64url",
+        "base64_raw",
+        "base32",
+        "base32hex",
+        "hex",
+        "utf-8",
+        "utf-16le",
+        "utf-16be",
+        "iso-8859-1",
+        "cp1252",
+        "ascii"
+      ]
+    },
+    "input_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "output_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "checksum": {
+      "type": "string"
+    },
+    "checksum_verified": {
+      "type": "boolean"
+    },
+    "checksum_algorithm": {
+      "type": "string"
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "corrections_applied": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "data",
+    "format",
+    "input_size",
+    "output_size",
+    "warnings",
+    "corrections_applied"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/detect-options.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/detect-options.schema.json",
+  "title": "Fulencode Detect Options",
+  "description": "Options for fulencode detect() operation",
+  "type": "object",
+  "properties": {
+    "max_sample_size": {
+      "type": "integer",
+      "description": "Maximum bytes to analyze.",
+      "minimum": 32
+    },
+    "min_confidence": {
+      "type": "number",
+      "description": "Minimum confidence threshold for a non-error detection result.",
+      "minimum": 0.0,
+      "maximum": 1.0
+    },
+    "recognize_multibase": {
+      "type": "boolean",
+      "description": "Recognize multibase prefixes (detection only; encoding may require extension module)."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/detection-result.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/detection-result.schema.json",
+  "title": "Fulencode Detection Result",
+  "description": "Result payload for fulencode detect()",
+  "type": "object",
+  "properties": {
+    "encoding": {
+      "description": "Detected encoding or null when unknown.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0
+    },
+    "level": {
+      "type": "string",
+      "enum": [
+        "high",
+        "medium",
+        "low"
+      ]
+    },
+    "multibase_prefix": {
+      "description": "Detected multibase prefix if present.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "encoding",
+    "confidence",
+    "level",
+    "warnings"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/encode-options.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/encode-options.schema.json",
+  "title": "Fulencode Encode Options",
+  "description": "Options for fulencode encode() operation",
+  "type": "object",
+  "properties": {
+    "padding": {
+      "type": "boolean",
+      "description": "Enable/disable padding when supported (Base64/Base32)."
+    },
+    "case": {
+      "type": "string",
+      "description": "Hex output case.",
+      "enum": [
+        "upper",
+        "lower"
+      ]
+    },
+    "line_length": {
+      "description": "Optional line wrap length for text output.",
+      "oneOf": [
+        {
+          "type": "integer",
+          "minimum": 1
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "line_ending": {
+      "type": "string",
+      "description": "Line ending to use when line wrapping.",
+      "enum": [
+        "\n",
+        "\r\n"
+      ]
+    },
+    "max_encoded_size": {
+      "type": "integer",
+      "description": "Maximum encoded output size in bytes.",
+      "minimum": 1024
+    },
+    "compute_checksum": {
+      "type": "string",
+      "description": "Checksum algorithm to compute on encoded output.",
+      "enum": [
+        "xxh3-128",
+        "sha256",
+        "sha512",
+        "sha1",
+        "md5"
+      ]
+    },
+    "embed_checksum": {
+      "type": "boolean",
+      "description": "Whether to embed checksum alongside encoded output (implementation-defined framing)."
+    },
+    "on_error": {
+      "type": "string",
+      "description": "Error handling mode when encoding text inputs.",
+      "enum": [
+        "strict",
+        "replace",
+        "ignore"
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/encoding-result.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/encoding-result.schema.json",
+  "title": "Fulencode Encoding Result",
+  "description": "Result payload for fulencode encode()",
+  "type": "object",
+  "properties": {
+    "data": {
+      "type": "string"
+    },
+    "format": {
+      "type": "string",
+      "enum": [
+        "base64",
+        "base64url",
+        "base64_raw",
+        "base32",
+        "base32hex",
+        "hex",
+        "utf-8",
+        "utf-16le",
+        "utf-16be",
+        "iso-8859-1",
+        "cp1252",
+        "ascii"
+      ]
+    },
+    "input_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "output_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "checksum": {
+      "type": "string"
+    },
+    "checksum_algorithm": {
+      "type": "string"
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "data",
+    "format",
+    "input_size",
+    "output_size",
+    "warnings"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/fulencode-config.schema.json

@@ -33,7 +33,8 @@
           "minimum": 1,
           "maximum": 100
         }
-      }
+      },
+      "additionalProperties": false
     },
     "defaults": {
       "type": "object",
@@ -66,7 +67,8 @@
           "description": "Default normalization profile",
           "default": "nfc"
         }
-      }
+      },
+      "additionalProperties": false
     },
     "detection": {
       "type": "object",
@@ -84,7 +86,9 @@
           "default": 8192,
           "minimum": 32
         }
-      }
+      },
+      "additionalProperties": false
     }
-  }
+  },
+  "additionalProperties": false
 }