@fulmenhq/tsfulmen 0.1.13 → 0.2.0

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

@@ -108,7 +108,7 @@ required:
   - version
   - metrics
 additionalProperties: false
-version: "0.2.19"
+version: "0.4.8"
 defaults:
   histogram_buckets:
     ms_metrics:

package/config/crucible-ts/taxonomy/repository-categories.yaml

@@ -1,5 +1,5 @@
 # Fulmen repository category taxonomy (machine-readable source)
-version: "2025.10.2"
+version: "2026.01.1"
 categories:
   - key: cli
     summary: "Command-line utilities without long-lived servers"
@@ -112,6 +112,28 @@ categories:
     references:
       - "docs/architecture/fulmen-forge-codex-standard.md"
       - "docs/architecture/fulmen-template-cdrl-standard.md"
+  - key: missive
+    summary: "Single-page promotional/CTA sites with minimal dependencies"
+    primaryEntryPoints:
+      - "index.html"
+    typicalConsumers:
+      - "Event attendees"
+      - "Donors/supporters"
+      - "Product launch visitors"
+    constraints:
+      - "MUST be single page (or very few pages)"
+      - "MUST NOT include blog, search, or content collections"
+      - "SHOULD use vanilla HTML/CSS with zero build"
+      - "MAY use light CSS framework (Pico.css, Water.css) via CDN"
+      - "MAY use minimal SSG only when partials/reuse justified"
+    notes: >
+      Missive repositories favor vanilla HTML/CSS with zero build. Escalate to Codex when multi-page, search, or content collections are needed.
+
+    templateNaming:
+      pattern: "forge-missive-{name}"
+      note: "Naming pattern TBD - could use message/communication metaphors"
+    references:
+      - "docs/standards/repository-category/missive/README.md"
   - key: sdk
     summary: "Client SDKs targeting external services or APIs"
     primaryEntryPoints:
@@ -121,3 +143,114 @@ categories:
       - "External developers"
       - "Partner integrations"
     notes: "Ship compatibility matrix and error taxonomy"
+  - key: spec-host
+    summary: "Machine-first static hosting for self-describing specification artifacts"
+    primaryEntryPoints:
+      - "index.json (optional catalog)"
+      - "v{version}/*.schema.json"
+      - "v{version}/*.openapi.json"
+      - "v{version}/*.asyncapi.json"
+    typicalConsumers:
+      - "JSON Schema validators"
+      - "IDE language servers"
+      - "API client generators"
+      - "CI/CD pipelines"
+    constraints:
+      - "MUST resolve embedded canonical IDs ($id, x-fulmen-id) over HTTPS"
+      - "MUST host self-describing specifications with industry-standard meta-validation"
+      - "MUST use versioned paths for immutability"
+      - "MUST NOT require runtime server (static files only)"
+      - "SHOULD provide index.json catalog for discovery"
+      - "MAY provide optional human-readable index page"
+    notes: >
+      Spec-host repositories host self-describing specifications where assets contain embedded canonical IDs ($id, x-fulmen-id) that must resolve over HTTPS. Assets are validated against industry-standard meta-schemas (JSON Schema, OpenAPI, AsyncAPI). For path-addressed assets without embedded IDs, see doc-host.
+
+    templateNaming:
+      pattern: "forge-spec-host-{name}"
+      note: "Naming pattern TBD - should reflect the corpus being hosted"
+    references:
+      - "docs/standards/publishing/spec-publishing.md"
+      - "docs/standards/repository-category/spec-host/README.md"
+  - key: doc-host
+    summary: "Machine-first static hosting for path-addressed documentation and configuration"
+    primaryEntryPoints:
+      - "index.json (optional catalog)"
+      - "{module}/**/*.md"
+      - "{module}/**/*.yaml"
+      - "{module}/**/*.json"
+    typicalConsumers:
+      - "Helper library shim modules"
+      - "Documentation tools"
+      - "Configuration loaders"
+      - "CI/CD pipelines"
+    constraints:
+      - "MUST serve files at canonical paths matching publish tree structure"
+      - "MUST use module namespace in URL structure per Canonical URI Resolution Standard"
+      - "MUST NOT require runtime server (static files only)"
+      - "SHOULD use versioned paths for versioned content"
+      - "MAY provide index for asset discovery"
+    notes: >
+      Doc-host repositories host path-addressed assets where canonical URLs are derived from file paths, not embedded identifiers. No meta-validation against industry-standard specifications is required. Suitable for Markdown docs, YAML configs, and reference data. For self-describing specifications with embedded IDs, see spec-host.
+
+    templateNaming:
+      pattern: "forge-doc-host-{name}"
+      note: "Naming pattern TBD - should reflect the content being hosted"
+    references:
+      - "docs/standards/publishing/canonical-uri-resolution.md"
+      - "docs/standards/repository-category/doc-host/README.md"
+  - key: fixture
+    summary: "Test infrastructure providing real-but-test-purpose servers, clients, or datastores"
+    primaryEntryPoints:
+      - "docker compose up"
+      - "Container image"
+    typicalConsumers:
+      - "Integration test suites"
+      - "CI/CD pipelines"
+      - "Local development environments"
+    constraints:
+      - "MUST NOT contain PII (use synthetic/anonymized data only)"
+      - "MUST NOT contain NPI/MNPI (regulatory/legal exposure)"
+      - "MUST NOT provide tooling for non-public interfaces in public repos"
+      - "MUST be container-first (docker compose up as primary entry)"
+      - "SHOULD use helper library (gofulmen, tsfulmen, pyfulmen) for observability"
+      - "MUST use scenario-driven configuration (YAML/JSON, not code changes)"
+      - "MUST be stateless by default (clean slate on restart)"
+      - "SHOULD expose structured logs for test assertions"
+      - "SHOULD self-document available endpoints/behaviors"
+    modes:
+      - key: server
+        summary: "Backend APIs (REST, gRPC, GraphQL)"
+        example: "fixture-server-proving-gauntlet-001"
+      - key: client
+        summary: "Clients for server/API testing"
+        example: "fixture-client-proving-probe-001"
+      - key: datastore
+        summary: "Databases, caches, or message queues"
+        example: "fixture-datastore-utility-bucket-001"
+      - key: identity
+        summary: "IdP/authentication services (OIDC, SAML)"
+        example: "fixture-identity-proving-warden-001"
+        status: "planned-v0.4.3"
+    behavioralCategories:
+      - key: proving
+        summary: "Real execution, test-purpose data, validates caller"
+        namingTheme: "Challenge/trial names (gauntlet, sentinel, bastion)"
+      - key: utility
+        summary: "Real execution, trivial but reliable service"
+        namingTheme: "Functional/descriptive (echo, static, relay)"
+      - key: chaos
+        summary: "Real execution, deliberately unreliable/hostile"
+        namingTheme: "Mischief names (gremlin, jinx, havoc)"
+    notes: >
+      Fixtures are real implementations with test-purpose configuration, NOT mocks (simulated responses). They execute real logic with synthetic data. Security constraints are inviolate to prevent data exposure in test artifacts. All fixture names must be registered in config/taxonomy/fixture-catalog.yaml.
+
+    naming:
+      pattern: "fixture-{mode}-{category}-{name}-{variant}"
+      categoryConstraint: "^(proving|utility|chaos)$"
+      nameConstraint: "^[a-z][a-z0-9]{1,20}$"
+      variantConstraint: "^[0-9]{3}$"
+      note: "Names registered in fixture-catalog.yaml. Variant 001 = reference implementation. Category in name for discoverability at scale."
+    registry: "config/taxonomy/fixture-catalog.yaml"
+    references:
+      - "docs/architecture/fulmen-fixture-standard.md"
+      - "docs/standards/repository-category/fixture/README.md"

package/dist/appidentity/index.d.ts

@@ -28,40 +28,6 @@ declare const APP_IDENTITY_SCHEMA_ID = "config/repository/app-identity/v1.0.0/ap
  */
 declare const MAX_ANCESTOR_SEARCH_DEPTH = 20;
 
-/**
- * Application Identity Errors
- *
- * Module-specific error classes for identity operations
- */
-
-/**
- * Base error class for app identity operations
- */
-declare class AppIdentityError extends FulmenError {
-    readonly identityPath?: string;
-    constructor(message: string, identityPath?: string, cause?: Error);
-    /**
-     * Create error for identity not found
-     */
-    static notFound(searchedPaths: string[]): AppIdentityError;
-    /**
-     * Create error for schema validation failure
-     */
-    static validationFailed(path: string, diagnostics: SchemaValidationDiagnostic[]): AppIdentityError;
-    /**
-     * Create error for environment variable override pointing to missing file
-     */
-    static envOverrideMissing(envPath: string): AppIdentityError;
-    /**
-     * Create error for YAML parsing failure
-     */
-    static parseFailed(path: string, cause: Error): AppIdentityError;
-    /**
-     * Create error for file read failure
-     */
-    static readFailed(path: string, cause: Error): AppIdentityError;
-}
-
 /**
  * Application Identity Types
  *
@@ -169,6 +135,121 @@ interface LoadIdentityOptions {
     readonly skipValidation?: boolean;
 }
 
+/**
+ * Embedded Identity Registration
+ *
+ * Provides a mechanism to register embedded identity at application startup
+ * for standalone binary/package support. This allows applications to work
+ * without requiring .fulmen/app.yaml to be discoverable on the filesystem.
+ *
+ * Discovery precedence (with embedded fallback):
+ * 1. Explicit path parameter
+ * 2. FULMEN_APP_IDENTITY_PATH environment variable
+ * 3. Ancestor search from CWD
+ * 4. Embedded identity fallback (this module)
+ */
+
+/**
+ * Register embedded identity YAML that serves as fallback when
+ * runtime discovery cannot find an external app.yaml.
+ *
+ * Semantics:
+ * - First registration wins (subsequent calls throw error)
+ * - Validates against schema on registration
+ * - Stores as immutable process-level fallback
+ *
+ * @param data - YAML string or pre-parsed Identity object
+ * @throws {AppIdentityError} If already registered or validation fails
+ *
+ * @example
+ * ```typescript
+ * // From npm package entry point
+ * import { registerEmbeddedIdentity } from "@fulmenhq/tsfulmen/appidentity";
+ * import { readFileSync } from "node:fs";
+ * import { fileURLToPath } from "node:url";
+ * import { dirname, join } from "node:path";
+ *
+ * const __filename = fileURLToPath(import.meta.url);
+ * const __dirname = dirname(__filename);
+ * const embeddedPath = join(__dirname, "..", ".fulmen", "app.yaml");
+ *
+ * try {
+ *   const yaml = readFileSync(embeddedPath, "utf-8");
+ *   registerEmbeddedIdentity(yaml);
+ * } catch {
+ *   // Embedded identity not available - discovery will use filesystem
+ * }
+ * ```
+ */
+declare function registerEmbeddedIdentity(data: string | Identity): Promise<void>;
+/**
+ * Check if embedded identity has been registered
+ *
+ * @returns true if registerEmbeddedIdentity() has been called successfully
+ */
+declare function hasEmbeddedIdentity(): boolean;
+/**
+ * Get the registered embedded identity
+ *
+ * @returns Frozen identity object or null if not registered
+ */
+declare function getEmbeddedIdentity(): Identity | null;
+/**
+ * Clear embedded identity registration
+ *
+ * WARNING: For testing only. In production, embedded identity should be
+ * set once at startup and never cleared.
+ */
+declare function clearEmbeddedIdentity(): void;
+
+/**
+ * Application Identity Errors
+ *
+ * Module-specific error classes for identity operations
+ */
+
+/**
+ * Base error class for app identity operations
+ */
+declare class AppIdentityError extends FulmenError {
+    readonly identityPath?: string;
+    constructor(message: string, identityPath?: string, cause?: Error);
+    /**
+     * Create error for identity not found
+     */
+    static notFound(searchedPaths: string[]): AppIdentityError;
+    /**
+     * Create error for schema validation failure
+     */
+    static validationFailed(path: string, diagnostics: SchemaValidationDiagnostic[]): AppIdentityError;
+    /**
+     * Create error for environment variable override pointing to missing file
+     */
+    static envOverrideMissing(envPath: string): AppIdentityError;
+    /**
+     * Create error for YAML parsing failure
+     */
+    static parseFailed(path: string, cause: Error): AppIdentityError;
+    /**
+     * Create error for file read failure
+     */
+    static readFailed(path: string, cause: Error): AppIdentityError;
+    /**
+     * Create error for embedded identity already registered
+     *
+     * Uses first-wins semantics - once registered, cannot be replaced
+     */
+    static alreadyRegistered(): AppIdentityError;
+    /**
+     * Create error for embedded identity YAML parsing failure
+     */
+    static embeddedParseFailed(cause: Error): AppIdentityError;
+    /**
+     * Create error for embedded identity schema validation failure
+     */
+    static embeddedValidationFailed(diagnostics: SchemaValidationDiagnostic[]): AppIdentityError;
+}
+
 /**
  * Application Identity Helpers
  *
@@ -291,6 +372,7 @@ declare function clearIdentityCache(): void;
  * 2. Explicit path (options.path)
  * 3. Environment variable (FULMEN_APP_IDENTITY_PATH)
  * 4. Ancestor search from startDir or CWD
+ * 5. Embedded identity fallback (if registered via registerEmbeddedIdentity)
  *
  * Results are cached after first successful load unless skipCache is true.
  * Test injections are never cached.
@@ -301,4 +383,4 @@ declare function clearIdentityCache(): void;
  */
 declare function loadIdentity(options?: LoadIdentityOptions): Promise<Identity>;
 
-export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, type AppIdentity, AppIdentityError, type ConfigIdentifiers, type Identity, type IdentityMetadata, type LoadIdentityOptions, MAX_ANCESTOR_SEARCH_DEPTH, type PythonMetadata, type RepositoryCategory, buildEnvVar, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, loadIdentity };
+export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, type AppIdentity, AppIdentityError, type ConfigIdentifiers, type Identity, type IdentityMetadata, type LoadIdentityOptions, MAX_ANCESTOR_SEARCH_DEPTH, type PythonMetadata, type RepositoryCategory, buildEnvVar, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };