@veryfront/ext-content-mdx 0.1.1226 → 0.1.1228

package/esm/src/extensions/contracts.js

@@ -0,0 +1,46 @@
+/**
+ * Contract registry — runtime resolution of extension-provided implementations.
+ *
+ * @module extensions/contracts
+ */
+import { MISSING_EXTENSION_ERROR } from "./errors.js";
+import { getRecommendation } from "./recommendations.js";
+import { assertCanonicalNonEmptyString } from "./runtime-validation.js";
+import { registerUnmanagedContract, resetContractRegistry, tryResolveRegisteredContract, unregisterContract, } from "./contract-registry-internal.js";
+/** Resolve path segments to an absolute path. */
+export function resolve(name) {
+    assertCanonicalNonEmptyString(name, "Contract name");
+    const impl = tryResolveRegisteredContract(name);
+    if (impl === undefined) {
+        const recommendation = getRecommendation(name);
+        throw MISSING_EXTENSION_ERROR.create({
+            message: recommendation
+                ? `Missing extension for contract "${name}". Install it with: deno add ${recommendation}`
+                : `Missing extension for contract "${name}"`,
+            detail: recommendation ? `Install it with: deno add ${recommendation}` : undefined,
+        });
+    }
+    return impl;
+}
+/** Try to resolve. */
+export function tryResolve(name) {
+    assertCanonicalNonEmptyString(name, "Contract name");
+    return tryResolveRegisteredContract(name);
+}
+/** Register. */
+export function register(name, impl) {
+    assertCanonicalNonEmptyString(name, "Contract name");
+    if (impl === undefined) {
+        throw new TypeError(`Contract "${name}" implementation must not be undefined`);
+    }
+    registerUnmanagedContract(name, impl);
+}
+/** Unregister. */
+export function unregister(name) {
+    assertCanonicalNonEmptyString(name, "Contract name");
+    unregisterContract(name);
+}
+/** Reset. */
+export function reset() {
+    resetContractRegistry();
+}

package/esm/src/extensions/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extension system error definitions.
+ *
+ * @module extensions/errors
+ */
+/** Shared missing extension error value. */
+export declare const MISSING_EXTENSION_ERROR: import("../errors/types.js").RegisteredError;
+/** Shared extension validation error value. */
+export declare const EXTENSION_VALIDATION_ERROR: import("../errors/types.js").RegisteredError;
+/** Shared circular dependency error value. */
+export declare const CIRCULAR_DEPENDENCY_ERROR: import("../errors/types.js").RegisteredError;
+/** Shared extension conflict error value. */
+export declare const EXTENSION_CONFLICT_ERROR: import("../errors/types.js").RegisteredError;
+/** Shared extension setup timeout error value. */
+export declare const EXTENSION_SETUP_TIMEOUT_ERROR: import("../errors/types.js").RegisteredError;
+//# sourceMappingURL=errors.d.ts.map

package/esm/src/extensions/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,8CAMlC,CAAC;AAEH,+CAA+C;AAC/C,eAAO,MAAM,0BAA0B,8CAMrC,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,8CAMpC,CAAC;AAEH,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB,8CAMnC,CAAC;AAEH,kDAAkD;AAClD,eAAO,MAAM,6BAA6B,8CAOxC,CAAC"}

package/esm/src/extensions/errors.js

@@ -0,0 +1,46 @@
+/**
+ * Extension system error definitions.
+ *
+ * @module extensions/errors
+ */
+import { defineError } from "../errors/types.js";
+/** Shared missing extension error value. */
+export const MISSING_EXTENSION_ERROR = defineError({
+    slug: "missing-extension",
+    category: "RUNTIME",
+    status: 500,
+    title: "Required extension not found",
+    suggestion: "Install the missing extension package and add it to your configuration",
+});
+/** Shared extension validation error value. */
+export const EXTENSION_VALIDATION_ERROR = defineError({
+    slug: "extension-validation",
+    category: "CONFIG",
+    status: 422,
+    title: "Extension validation failed",
+    suggestion: "Check that the extension exports a valid name, version, and capabilities array",
+});
+/** Shared circular dependency error value. */
+export const CIRCULAR_DEPENDENCY_ERROR = defineError({
+    slug: "extension-circular-dependency",
+    category: "CONFIG",
+    status: 422,
+    title: "Circular dependency detected between extensions",
+    suggestion: "Review the 'extends' fields in your extensions to break the cycle",
+});
+/** Shared extension conflict error value. */
+export const EXTENSION_CONFLICT_ERROR = defineError({
+    slug: "extension-conflict",
+    category: "CONFIG",
+    status: 409,
+    title: "Conflicting extensions detected",
+    suggestion: "Remove or disable one of the conflicting extensions in your configuration",
+});
+/** Shared extension setup timeout error value. */
+export const EXTENSION_SETUP_TIMEOUT_ERROR = defineError({
+    slug: "extension-setup-timeout",
+    category: "RUNTIME",
+    status: 500,
+    title: "Extension setup timed out",
+    suggestion: "Check the extension's setup() for blocking operations, or increase VF_EXTENSION_SETUP_TIMEOUT_MS",
+});

package/esm/src/extensions/first-party-import.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Resolve first-party extension implementations without making the root npm
+ * package statically depend on every extension dependency.
+ *
+ * Source and compiled-binary builds can load the workspace extension sources.
+ * npm builds should load the separate @veryfront/ext-* packages installed by
+ * the consuming service or app.
+ */
+/** Optional non-root entry point for a first-party extension import. */
+export interface FirstPartyExtensionImportOptions {
+    /**
+     * Workspace source entry below the extension's `src/` directory, without
+     * an extension. Supply it together with `packageSubpath`; both values must
+     * name the same relative entry. When both are omitted, the workspace
+     * `index` entry and npm package root are used.
+     */
+    readonly sourceEntry?: string;
+    /**
+     * Published npm package subpath, without a leading `./` or `/`.
+     * Supply it together with `sourceEntry` using the same value. When both are
+     * omitted, the package root is used.
+     */
+    readonly packageSubpath?: string;
+}
+export declare function firstPartyExtensionSourceSpecifiers(sourceDirectory: string, sourceEntry?: string): string[];
+export declare function importFirstPartyExtensionModule<TModule>(sourceDirectory: string, packageName: string, options?: FirstPartyExtensionImportOptions): Promise<TModule>;
+/**
+ * Classify a dynamic-import failure as "the extension module itself is not
+ * installed" as opposed to a real load failure inside an installed extension.
+ *
+ * Checks the stable `error.code` first and falls back to message patterns,
+ * walking the `cause` chain so wrapped errors classify like their root cause.
+ *
+ * When `expectedSpecifierFragments` is provided, package specifiers and
+ * absolute/file paths match exactly. Safe relative multi-segment path
+ * fragments match only as complete path suffixes, with an optional emitted
+ * `.ts` or `.js` extension. Every recognized missing-module error in the
+ * cause chain must agree. This keeps a broken transitive dependency (e.g.
+ * `Cannot find package 'jose'` thrown while loading an installed
+ * @veryfront/ext-auth-jwt) from being misread as "extension not installed".
+ */
+export declare function isMissingFirstPartyExtensionModule(error: unknown, expectedSpecifierFragments?: string[]): boolean;
+//# sourceMappingURL=first-party-import.d.ts.map

package/esm/src/extensions/first-party-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-party-import.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/first-party-import.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,wEAAwE;AACxE,MAAM,WAAW,gCAAgC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AASD,wBAAgB,mCAAmC,CACjD,eAAe,EAAE,MAAM,EACvB,WAAW,SAAU,GACpB,MAAM,EAAE,CAKV;AAED,wBAAsB,+BAA+B,CAAC,OAAO,EAC3D,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,OAAO,CAAC,CAqElB;AA8FD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,EACd,0BAA0B,CAAC,EAAE,MAAM,EAAE,GACpC,OAAO,CAuBT"}

package/esm/src/extensions/first-party-import.js

@@ -0,0 +1,377 @@
+/**
+ * Resolve first-party extension implementations without making the root npm
+ * package statically depend on every extension dependency.
+ *
+ * Source and compiled-binary builds can load the workspace extension sources.
+ * npm builds should load the separate @veryfront/ext-* packages installed by
+ * the consuming service or app.
+ */
+const SOURCE_EXTENSION_ROOT = "../../extensions";
+const FIRST_PARTY_ENTRY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
+const FIRST_PARTY_SOURCE_DIRECTORY_PATTERN = /^ext-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const FIRST_PARTY_PACKAGE_PATTERN = /^@veryfront\/ext-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const FIRST_PARTY_PACKAGE_SPECIFIER_PATTERN = /^@veryfront\/ext-[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*)?$/;
+const SAFE_RELATIVE_PATH_FRAGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9._-]*)+$/;
+export function firstPartyExtensionSourceSpecifiers(sourceDirectory, sourceEntry = "index") {
+    assertValidSourceDirectory(sourceDirectory);
+    assertValidEntry("source entry", sourceEntry);
+    const sourceRoot = `${SOURCE_EXTENSION_ROOT}/${sourceDirectory}/src/${sourceEntry}`;
+    return [`${sourceRoot}.ts`, `${sourceRoot}.js`];
+}
+export async function importFirstPartyExtensionModule(sourceDirectory, packageName, options = {}) {
+    assertValidSourceDirectory(sourceDirectory);
+    assertValidPackageName(packageName);
+    if (packageName !== `@veryfront/${sourceDirectory}`) {
+        throw new TypeError("First-party extension source directory and package name must identify the same extension");
+    }
+    const capturedOptions = captureImportOptions(options);
+    if (capturedOptions.hasSourceEntry !== capturedOptions.hasPackageSubpath ||
+        (capturedOptions.hasSourceEntry &&
+            capturedOptions.sourceEntry !== capturedOptions.packageSubpath)) {
+        throw new TypeError("First-party extension source entry and package subpath must be supplied together and match");
+    }
+    const sourceEntry = capturedOptions.hasSourceEntry ? capturedOptions.sourceEntry : "index";
+    const packageSubpath = capturedOptions.hasPackageSubpath
+        ? capturedOptions.packageSubpath
+        : undefined;
+    assertValidEntry("source entry", sourceEntry);
+    if (packageSubpath !== undefined) {
+        assertValidEntry("package subpath", packageSubpath);
+    }
+    const packageSpecifier = packageSubpath === undefined
+        ? packageName
+        : `${packageName}/${packageSubpath}`;
+    let sourceError;
+    for (const sourceSpecifier of firstPartyExtensionSourceSpecifiers(sourceDirectory, sourceEntry)) {
+        try {
+            return await import(sourceSpecifier);
+        }
+        catch (error) {
+            const expectedSourceSpecifier = new URL(sourceSpecifier, globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url).href;
+            if (!isMissingFirstPartyExtensionModule(error, [expectedSourceSpecifier])) {
+                throw error;
+            }
+            sourceError ??= error;
+        }
+    }
+    try {
+        return await import(packageSpecifier);
+    }
+    catch (error) {
+        const expectedPackageSpecifiers = packageSubpath === undefined
+            ? [packageName]
+            : [packageSpecifier, packageName];
+        if (!isMissingFirstPartyExtensionModule(error, expectedPackageSpecifiers)) {
+            throw error;
+        }
+        throw withMissingExtensionInstallHint(error, sourceDirectory, packageName, packageSpecifier, sourceError);
+    }
+}
+function captureImportOptions(options) {
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        return throwInvalidImportOptions();
+    }
+    let prototype;
+    let keys;
+    try {
+        prototype = Object.getPrototypeOf(options);
+        keys = Reflect.ownKeys(options);
+    }
+    catch {
+        return throwInvalidImportOptions();
+    }
+    if (prototype !== Object.prototype && prototype !== null) {
+        return throwInvalidImportOptions();
+    }
+    let sourceEntryDescriptor;
+    let packageSubpathDescriptor;
+    try {
+        for (const key of keys) {
+            if (key !== "sourceEntry" && key !== "packageSubpath") {
+                return throwInvalidImportOptions();
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(options, key);
+            if (descriptor === undefined ||
+                descriptor.enumerable !== true ||
+                !Object.prototype.hasOwnProperty.call(descriptor, "value")) {
+                return throwInvalidImportOptions();
+            }
+            if (key === "sourceEntry") {
+                sourceEntryDescriptor = descriptor;
+            }
+            else {
+                packageSubpathDescriptor = descriptor;
+            }
+        }
+    }
+    catch {
+        return throwInvalidImportOptions();
+    }
+    return Object.freeze({
+        hasSourceEntry: sourceEntryDescriptor?.value !== undefined,
+        hasPackageSubpath: packageSubpathDescriptor?.value !== undefined,
+        sourceEntry: sourceEntryDescriptor?.value,
+        packageSubpath: packageSubpathDescriptor?.value,
+    });
+}
+function throwInvalidImportOptions() {
+    throw new TypeError("Invalid first-party extension import options");
+}
+function assertValidSourceDirectory(sourceDirectory) {
+    if (typeof sourceDirectory !== "string" ||
+        !FIRST_PARTY_SOURCE_DIRECTORY_PATTERN.test(sourceDirectory)) {
+        throw new TypeError("Invalid first-party extension source directory");
+    }
+}
+function assertValidPackageName(packageName) {
+    if (typeof packageName !== "string" ||
+        !FIRST_PARTY_PACKAGE_PATTERN.test(packageName)) {
+        throw new TypeError("Invalid first-party extension package name");
+    }
+}
+function assertValidEntry(label, entry) {
+    if (typeof entry !== "string" || !FIRST_PARTY_ENTRY_PATTERN.test(entry)) {
+        throw new TypeError(`Invalid first-party extension ${label}`);
+    }
+}
+// Stable runtime error codes for unresolvable modules (preferred over message
+// text, which runtimes reword between releases).
+const MISSING_MODULE_ERROR_CODES = new Set([
+    "ERR_MODULE_NOT_FOUND", // Node ESM
+    "MODULE_NOT_FOUND", // Node CJS interop
+    "ERR_PACKAGE_PATH_NOT_EXPORTED", // Node package exports
+]);
+/**
+ * Classify a dynamic-import failure as "the extension module itself is not
+ * installed" as opposed to a real load failure inside an installed extension.
+ *
+ * Checks the stable `error.code` first and falls back to message patterns,
+ * walking the `cause` chain so wrapped errors classify like their root cause.
+ *
+ * When `expectedSpecifierFragments` is provided, package specifiers and
+ * absolute/file paths match exactly. Safe relative multi-segment path
+ * fragments match only as complete path suffixes, with an optional emitted
+ * `.ts` or `.js` extension. Every recognized missing-module error in the
+ * cause chain must agree. This keeps a broken transitive dependency (e.g.
+ * `Cannot find package 'jose'` thrown while loading an installed
+ * @veryfront/ext-auth-jwt) from being misread as "extension not installed".
+ */
+export function isMissingFirstPartyExtensionModule(error, expectedSpecifierFragments) {
+    const chain = errorChain(error);
+    const missing = chain.filter(isMissingModuleError);
+    if (missing.length === 0)
+        return false;
+    if (!expectedSpecifierFragments || expectedSpecifierFragments.length === 0) {
+        return true;
+    }
+    let matched = false;
+    for (const entry of missing) {
+        const message = errorMessage(entry);
+        const missingSpecifier = message === undefined ? undefined : reportedMissingSpecifier(message);
+        if (missingSpecifier === undefined)
+            return false;
+        if (!expectedSpecifierFragments.some((expected) => matchesExpectedSpecifier(missingSpecifier, expected))) {
+            return false;
+        }
+        matched = true;
+    }
+    return matched;
+}
+function reportedMissingSpecifier(message) {
+    for (const prefix of [
+        "[ERR_PACKAGE_PATH_NOT_EXPORTED] ",
+        "[ERR_MODULE_NOT_FOUND] ",
+    ]) {
+        if (message.startsWith(prefix)) {
+            message = message.slice(prefix.length);
+            break;
+        }
+    }
+    const unknownExport = message.match(/^Unknown export\s+["'](\.\/[^"']+)["']\s+for\s+["']([^"']+)["']$/) ?? message.match(/^Unknown export\s+["'](\.\/[^"']+)["']\s+for\s+["']([^"']+)["']\.\n {2}Package exports:(?:\n \* [^\r\n]+)+(?:\n {4}at [^\r\n]+\n?)?$/);
+    if (unknownExport) {
+        return `${unknownExport[2]}/${unknownExport[1].slice(2)}`;
+    }
+    const packageSubpath = message.match(/^Package subpath\s+["'](\.\/[^"']+)["']\s+is not defined by\s+["']exports["']\s+in\s+(?:["']([^"']+[/\\]package\.json)["']|(.+?[/\\]package\.json))(?:\s+imported from\s+.+)?$/);
+    if (packageSubpath) {
+        const packageName = packageNameFromManifestPath(packageSubpath[2] ?? packageSubpath[3]);
+        if (packageName)
+            return `${packageName}/${packageSubpath[1].slice(2)}`;
+    }
+    const bunResolveMessage = message.match(/^(?:ResolveMessage:\s+)?Cannot find module\s+["']([^"']+)["']\s+from\s+["']([^"']+)["']$/);
+    if (bunResolveMessage) {
+        const specifier = bunResolveMessage[1];
+        const importer = bunResolveMessage[2];
+        if ((specifier.startsWith("./") || specifier.startsWith("../")) &&
+            importer.startsWith("/")) {
+            try {
+                return canonicalFilePath(new URL(specifier, new URL(".", `file://${importer}`)).href);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return specifier;
+    }
+    for (const pattern of [
+        /^Cannot find module\s+["']([^"']+)["']\nRequire stack:(?:\n- [^\r\n]+)+$/,
+        /^(?:Cannot find package|Cannot find module|Module not found)\s+["']([^"']+)["'](?:(?:\s+imported from\s+.+)|\.)?$/,
+        /^Import\s+["']([^"']+)["']\s+not a dependency(?: and not in import map)?(?:\s+from\s+.+)?$/,
+        /^Unable to resolve\s+["']([^"']+)["'](?:\s+from\s+.+)?$/,
+    ]) {
+        const match = message.match(pattern);
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+function packageNameFromManifestPath(path) {
+    const normalized = path.replaceAll("\\", "/");
+    const marker = "/node_modules/";
+    const markerIndex = normalized.lastIndexOf(marker);
+    if (markerIndex < 0)
+        return undefined;
+    const segments = normalized.slice(markerIndex + marker.length).split("/");
+    if (segments[0]?.startsWith("@")) {
+        return segments[0] && segments[1] ? `${segments[0]}/${segments[1]}` : undefined;
+    }
+    return segments[0] || undefined;
+}
+function matchesExpectedSpecifier(reportedSpecifier, expectedSpecifier) {
+    if (typeof expectedSpecifier !== "string")
+        return false;
+    const expectedFilePath = canonicalFilePath(expectedSpecifier);
+    const reportedFilePath = canonicalFilePath(reportedSpecifier);
+    if (expectedFilePath !== undefined) {
+        return reportedFilePath === expectedFilePath;
+    }
+    if (FIRST_PARTY_PACKAGE_SPECIFIER_PATTERN.test(expectedSpecifier)) {
+        return FIRST_PARTY_PACKAGE_SPECIFIER_PATTERN.test(reportedSpecifier) &&
+            reportedSpecifier === expectedSpecifier;
+    }
+    const relativeFragment = expectedSpecifier.replaceAll("\\", "/");
+    if (!SAFE_RELATIVE_PATH_FRAGMENT_PATTERN.test(relativeFragment))
+        return false;
+    const normalizedReportedSpecifier = reportedSpecifier.replaceAll("\\", "/");
+    if (reportedFilePath === undefined &&
+        !normalizedReportedSpecifier.startsWith("./") &&
+        !normalizedReportedSpecifier.startsWith("../")) {
+        return false;
+    }
+    const reportedPath = reportedFilePath ?? normalizedReportedSpecifier;
+    const suffixes = relativeFragment.endsWith(".ts") ||
+        relativeFragment.endsWith(".js")
+        ? [relativeFragment]
+        : [
+            relativeFragment,
+            `${relativeFragment}.ts`,
+            `${relativeFragment}.js`,
+        ];
+    for (const suffix of suffixes) {
+        if (reportedPath === suffix || reportedPath.endsWith(`/${suffix}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function canonicalFilePath(specifier) {
+    if (/^file:/i.test(specifier)) {
+        try {
+            const url = new URL(specifier);
+            if (url.protocol !== "file:" ||
+                url.username !== "" ||
+                url.password !== "" ||
+                url.port !== "" ||
+                url.search !== "" ||
+                url.hash !== "" ||
+                /%2f|%5c/i.test(url.pathname)) {
+                return undefined;
+            }
+            const host = url.hostname === "localhost" ? "" : url.hostname;
+            let path = decodeURIComponent(url.pathname).replaceAll("\\", "/");
+            if (/^\/[A-Za-z]:\//.test(path))
+                path = path.slice(1);
+            return host ? `//${host.toLowerCase()}${path}` : normalizeAbsoluteFilePath(path);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const normalized = specifier.replaceAll("\\", "/");
+    if (!normalized.startsWith("/") &&
+        !normalized.startsWith("//") &&
+        !/^[A-Za-z]:\//.test(normalized)) {
+        return undefined;
+    }
+    return normalizeAbsoluteFilePath(normalized);
+}
+function normalizeAbsoluteFilePath(path) {
+    if (/^[A-Za-z]:\//.test(path)) {
+        return `${path[0].toLowerCase()}${path.slice(1)}`;
+    }
+    const uncPath = path.match(/^\/\/([^/]+)(\/.*)$/);
+    return uncPath ? `//${uncPath[1].toLowerCase()}${uncPath[2]}` : path;
+}
+function isMissingModuleError(error) {
+    let code;
+    try {
+        code = error?.code;
+    }
+    catch {
+        return false;
+    }
+    const message = errorMessage(error);
+    if (message === undefined)
+        return false;
+    if (typeof code === "string" && MISSING_MODULE_ERROR_CODES.has(code))
+        return true;
+    return reportedMissingSpecifier(message) !== undefined;
+}
+function errorChain(error) {
+    const chain = [];
+    let current = error;
+    while (current !== undefined && current !== null && chain.length < 8) {
+        if (chain.includes(current))
+            break;
+        chain.push(current);
+        try {
+            current = current instanceof Error ? current.cause : undefined;
+        }
+        catch {
+            break;
+        }
+    }
+    return chain;
+}
+function errorMessage(error) {
+    try {
+        if (error instanceof Error) {
+            return typeof error.message === "string" ? error.message : undefined;
+        }
+        if (typeof error === "object" && error !== null) {
+            const message = error.message;
+            return typeof message === "string" ? message : undefined;
+        }
+        return typeof error === "string" ? error : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Both the workspace source and the npm package are missing. Surface the
+ * package-resolution error (its message names the installable @veryfront/ext-*
+ * package) instead of the internal workspace source path, and append an
+ * explicit install hint for npm consumers.
+ */
+function withMissingExtensionInstallHint(error, sourceDirectory, packageName, packageSpecifier, sourceError) {
+    const message = errorMessage(error);
+    if (message === undefined)
+        return error;
+    const hint = packageSpecifier === packageName
+        ? ` First-party extension "${sourceDirectory}" is not installed; install ${packageName} alongside veryfront to enable it.`
+        : ` First-party extension entry "${packageSpecifier}" is unavailable; install or update ${packageName} alongside veryfront to enable it.`;
+    const cause = sourceError !== undefined && sourceError !== error
+        ? new AggregateError([error, sourceError], message)
+        : error;
+    return new Error(`${message}${hint}`, { cause });
+}

package/esm/src/extensions/parser/yaml-defaults.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Product-distribution default for the general YAML parser contract.
+ *
+ * Mirrors `skill-defaults.ts`: the first-party `ext-yaml` extension owns the
+ * third-party parser, and core reaches it through a dynamic import so the root
+ * package never statically depends on it. An installation without the
+ * extension simply has no default, and the call site raises the registry's
+ * missing-extension error.
+ *
+ * @module extensions/parser/yaml-defaults
+ */
+import { type YamlParserProvider } from "./yaml-parser.js";
+/**
+ * Load the product distribution's extension-owned default YAML parser.
+ *
+ * Returns undefined when the extension is not installed. A load failure
+ * *inside* an installed extension is rethrown: that is a broken installation,
+ * not an absent one, and hiding it would surface later as a confusing
+ * "install @veryfront/ext-yaml" message for an extension that is present.
+ */
+export declare function loadDefaultYamlParserProvider(): Promise<Readonly<YamlParserProvider> | undefined>;
+//# sourceMappingURL=yaml-defaults.d.ts.map

package/esm/src/extensions/parser/yaml-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-defaults.d.ts","sourceRoot":"","sources":["../../../../src/src/extensions/parser/yaml-defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAqCvF;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAC5D,QAAQ,CAAC,kBAAkB,CAAC,GAAG,SAAS,CACzC,CAoBA"}

package/esm/src/extensions/parser/yaml-defaults.js

@@ -0,0 +1,57 @@
+/**
+ * Product-distribution default for the general YAML parser contract.
+ *
+ * Mirrors `skill-defaults.ts`: the first-party `ext-yaml` extension owns the
+ * third-party parser, and core reaches it through a dynamic import so the root
+ * package never statically depends on it. An installation without the
+ * extension simply has no default, and the call site raises the registry's
+ * missing-extension error.
+ *
+ * @module extensions/parser/yaml-defaults
+ */
+import { importFirstPartyExtensionModule, isMissingFirstPartyExtensionModule, } from "../first-party-import.js";
+import { snapshotYamlParserProvider } from "./yaml-parser.js";
+const DEFAULT_YAML_SOURCE_DIRECTORY = "ext-yaml";
+const DEFAULT_YAML_EXTENSION_PACKAGE = "@veryfront/ext-yaml";
+const DEFAULT_YAML_FACTORY_EXPORT = "createYamlParser";
+function readProviderFactory(extensionModule) {
+    if (extensionModule === null ||
+        (typeof extensionModule !== "object" && typeof extensionModule !== "function")) {
+        throw new TypeError(`Invalid ${DEFAULT_YAML_EXTENSION_PACKAGE} module: expected a module namespace`);
+    }
+    let factory;
+    try {
+        factory = extensionModule.createYamlParser;
+    }
+    catch (cause) {
+        throw new TypeError(`Invalid ${DEFAULT_YAML_EXTENSION_PACKAGE} module: could not read export "${DEFAULT_YAML_FACTORY_EXPORT}"`, { cause });
+    }
+    if (typeof factory !== "function") {
+        throw new TypeError(`Invalid ${DEFAULT_YAML_EXTENSION_PACKAGE} module: export "${DEFAULT_YAML_FACTORY_EXPORT}" must be callable`);
+    }
+    return factory;
+}
+/**
+ * Load the product distribution's extension-owned default YAML parser.
+ *
+ * Returns undefined when the extension is not installed. A load failure
+ * *inside* an installed extension is rethrown: that is a broken installation,
+ * not an absent one, and hiding it would surface later as a confusing
+ * "install @veryfront/ext-yaml" message for an extension that is present.
+ */
+export async function loadDefaultYamlParserProvider() {
+    let extensionModule;
+    try {
+        extensionModule = await importFirstPartyExtensionModule(DEFAULT_YAML_SOURCE_DIRECTORY, DEFAULT_YAML_EXTENSION_PACKAGE);
+    }
+    catch (error) {
+        if (!isMissingFirstPartyExtensionModule(error, [
+            "extensions/ext-yaml/src/index",
+            DEFAULT_YAML_EXTENSION_PACKAGE,
+        ])) {
+            throw error;
+        }
+        return undefined;
+    }
+    return snapshotYamlParserProvider(readProviderFactory(extensionModule)());
+}