@fulmenhq/tsfulmen 0.3.3 → 0.4.1

package/dist/assets/index.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Asset resolution - Types
+ *
+ * Central contract for resolving tsfulmen's bundled SSOT assets (schemas,
+ * metaschemas, foundry catalogs, taxonomy) either from the filesystem (npm /
+ * `node dist` / source) or from embedded generated modules (a `bun --compile`
+ * single-file binary, where no asset tree exists on disk).
+ *
+ * Logical paths are **package-root-relative POSIX paths**, e.g.
+ * `schemas/crucible-ts/library/foundry/v1.0.0/signals.schema.json` or
+ * `config/crucible-ts/library/foundry/signals.yaml`. Using a single namespace
+ * across both the `schemas/` and `config/` trees lets cross-tree `$ref`
+ * resolution (e.g. a schema referencing `config/.../taxonomy/metrics.yaml`)
+ * work through one resolver.
+ */
+/**
+ * How assets are resolved.
+ * - `fs`: read from the on-disk asset trees (current behavior).
+ * - `embedded`: read from generated, build-embedded manifests (compile-safe).
+ * - `auto`: prefer `fs` when the asset tree is present/readable, else `embedded`.
+ */
+type AssetMode = "fs" | "embedded" | "auto";
+/**
+ * Provenance/metadata for diagnostics and parity reporting across SDKs.
+ */
+interface AssetProvenance {
+    /** The concrete resolution mode in effect (never `auto`). */
+    readonly mode: Exclude<AssetMode, "auto">;
+    /** On-disk base directory, when resolving from the filesystem. */
+    readonly baseDir?: string;
+    /** Number of embedded assets available, when resolving from embedded modules. */
+    readonly embeddedCount?: number;
+}
+/**
+ * Resolves SSOT assets by logical path, independent of backing store.
+ */
+interface AssetResolver {
+    /** Concrete resolution mode (`fs` or `embedded`). */
+    readonly mode: Exclude<AssetMode, "auto">;
+    /**
+     * Read an asset's text content by logical path.
+     * @throws {AssetResolutionError} when the asset cannot be found/read.
+     */
+    read(logicalPath: string): Promise<string>;
+    /**
+     * Enumerate logical paths matching the given glob patterns (e.g.
+     * `["schemas/crucible-ts/** /*.schema.json"]`). Powers schema-registry
+     * discovery without a filesystem walk.
+     */
+    list(patterns: string[]): Promise<string[]>;
+    /** Whether an asset exists at the given logical path. */
+    has(logicalPath: string): Promise<boolean>;
+    /** Provenance for diagnostics / size & parity reporting. */
+    provenance(): AssetProvenance;
+}
+/**
+ * A generated, build-embedded set of assets for one domain (e.g. metaschemas,
+ * foundry catalogs). T3 codegen emits these; {@link registerEmbeddedAssets}
+ * composes them into the embedded resolver.
+ */
+interface EmbeddedAssetManifest {
+    /** Domain label for diagnostics (e.g. `"foundry"`, `"metaschema"`). */
+    readonly domain: string;
+    /** Logical path -> raw text content. */
+    readonly files: Readonly<Record<string, string>>;
+}
+
+/**
+ * Asset resolution - Embedded backend
+ *
+ * Reads SSOT assets from generated, build-embedded manifests instead of the
+ * filesystem, so loads work inside a `bun --compile` single-file binary (no
+ * asset tree on disk). T3 codegen emits per-domain {@link EmbeddedAssetManifest}
+ * modules and registers them via {@link registerEmbeddedAssets}; this resolver
+ * composes whatever has been registered.
+ *
+ * Until T3 lands, no manifests are registered, so the embedded resolver is
+ * empty — `read()` throws a clear "not found" and `list()` returns `[]`.
+ */
+
+/**
+ * Register a generated embedded-asset manifest. Idempotent per domain
+ * (re-registering a domain replaces it). Called by generated modules.
+ */
+declare function registerEmbeddedAssets(manifest: EmbeddedAssetManifest): void;
+/** Whether a specific domain has been registered. */
+declare function hasEmbeddedDomain(domain: string): boolean;
+/** Clear all registered manifests. For testing only. */
+declare function clearEmbeddedAssets(): void;
+/** Whether any embedded manifests have been registered. */
+declare function hasEmbeddedAssets(): boolean;
+declare class EmbeddedAssetResolver implements AssetResolver {
+    readonly mode: "embedded";
+    private readonly index;
+    constructor();
+    read(logicalPath: string): Promise<string>;
+    list(patterns: string[]): Promise<string[]>;
+    has(logicalPath: string): Promise<boolean>;
+    provenance(): AssetProvenance;
+}
+
+/**
+ * Asset resolution - Error handling
+ *
+ * Custom error classes for SSOT asset resolution (filesystem or embedded).
+ */
+declare class AssetResolutionError extends Error {
+    readonly assetPath?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, assetPath?: string | undefined, cause?: Error | undefined);
+    static notFound(assetPath: string, mode: string): AssetResolutionError;
+    static readFailed(assetPath: string, code: string): AssetResolutionError;
+    static baseDirUnavailable(detail: string): AssetResolutionError;
+}
+
+/**
+ * Asset resolution - Filesystem backend
+ *
+ * Reads SSOT assets from the on-disk `schemas/crucible-ts` / `config/crucible-ts`
+ * trees shipped in the npm package. This is the current (pre-v0.4.0) behavior,
+ * now centralized behind the {@link AssetResolver} contract.
+ */
+
+declare class FsAssetResolver implements AssetResolver {
+    private readonly baseDir;
+    private readonly enforceNamespace;
+    readonly mode: "fs";
+    /**
+     * @param baseDir Directory logical paths resolve against.
+     * @param enforceNamespace Restrict to the SSOT namespaces (schemas/config/docs).
+     *   Default `true` for the package's own asset tree; pass `false` when `baseDir`
+     *   is a consumer-supplied tree they scope themselves (traversal guards still apply).
+     */
+    constructor(baseDir: string, enforceNamespace?: boolean);
+    private resolve;
+    read(logicalPath: string): Promise<string>;
+    /** Cached realpath of baseDir (resolves symlinks once). */
+    private baseRealCache?;
+    private baseReal;
+    /** Whether a resolved (realpath) target stays within the resolver's baseDir. */
+    private isWithinBase;
+    list(patterns: string[]): Promise<string[]>;
+    has(logicalPath: string): Promise<boolean>;
+    provenance(): AssetProvenance;
+    /** The on-disk base directory this resolver reads from. */
+    getBaseDir(): string;
+}
+
+/**
+ * Asset resolution - Resolver factory & mode selection
+ *
+ * Chooses between the filesystem and embedded backends. Default is `auto`:
+ * prefer the filesystem when the on-disk asset tree is present/readable, else
+ * fall back to embedded generated modules (the `bun --compile` case). The mode
+ * can be forced with the `TSFULMEN_ASSET_MODE` env var or an explicit option.
+ */
+
+/**
+ * Find the package-root directory that contains the SSOT asset trees by walking
+ * upward from this module. Works for both source (`src/assets/`) and bundled
+ * (`dist/`) layouts without hard-coded depths — and returns `null` inside a
+ * `bun --compile` binary where no such directory exists on disk.
+ */
+declare function findAssetBaseDir(): string | null;
+interface ResolveAssetsOptions {
+    /** Force a mode. Precedence: explicit option > `TSFULMEN_ASSET_MODE` > `auto`. */
+    mode?: AssetMode;
+    /** Override the FS base dir (e.g. a consumer's own asset tree). Implies `fs`. */
+    baseDir?: string;
+}
+/**
+ * Build an {@link AssetResolver} for the requested (or auto-detected) mode.
+ * Stateless — callers that want a cached instance use {@link getAssetResolver}.
+ */
+declare function resolveAssets(options?: ResolveAssetsOptions): AssetResolver;
+/**
+ * Cached resolver keyed on the effective options. Most call sites should use
+ * this; pass fresh options (or different env) to rebuild.
+ */
+declare function getAssetResolver(options?: ResolveAssetsOptions): AssetResolver;
+/** Reset the cached resolver. For testing / after registering embedded assets. */
+declare function resetAssetResolver(): void;
+
+export { type AssetMode, type AssetProvenance, AssetResolutionError, type AssetResolver, type EmbeddedAssetManifest, EmbeddedAssetResolver, FsAssetResolver, type ResolveAssetsOptions, clearEmbeddedAssets, findAssetBaseDir, getAssetResolver, hasEmbeddedAssets, hasEmbeddedDomain, registerEmbeddedAssets, resetAssetResolver, resolveAssets };

package/dist/assets/index.js

@@ -0,0 +1,4 @@
+export { AssetResolutionError, EmbeddedAssetResolver, FsAssetResolver, clearEmbeddedAssets, findAssetBaseDir, getAssetResolver, hasEmbeddedAssets, hasEmbeddedDomain, registerEmbeddedAssets, resetAssetResolver, resolveAssets } from '../chunk-56F2EEAG.js';
+import '../chunk-UP2VWCW5.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/assets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}