@makaio/framework 1.0.0-dev-1781023871421 → 1.0.0-dev-1781034508425

package/dist/load-extensions-CESuhxma.mjs

@@ -0,0 +1 @@
+import{t as e}from"./descriptor-to-package-CY8oc2gl.mjs";import{pathToFileURL as t}from"node:url";import*as n from"node:path";import*as r from"node:fs";import{versionSatisfies as i}from"@makaio/framework/contracts";async function a(e,t){let{frameworkVersion:n,importModule:r=S}=t,i=[],a=new Map,s;for(let t of e){let{descriptor:e,extensionPath:c}=t,l=`[extensions] ${e.name}@${e.version}`;if(!u(t,n))continue;if(e.execution===`detached`){let t;try{s??=(await import(`./detached-extension-handle-Bo5Q06_g.mjs`)).createDetachedExtensionPackage,t=s(e,c)}catch(e){console.warn(`${l}: failed to synthesize detached extension package:`,e instanceof Error?e.message:e);continue}i.push(t),e.config?.defaults&&a.set(e.name,e.config.defaults);continue}if(!e.entrypoints.server){!e.entrypoints.browser&&!e.entrypoints.cli&&console.warn(`${l}: no executable entrypoint declared, skipping`);continue}let d;if(t.preloadedModule)d=t.preloadedModule;else try{let t=_(`server`,e.entrypoints.server,c);if(!t){console.warn(`${l}: server entrypoint could not be resolved within extension directory, skipping`);continue}d=await r(t)}catch(e){console.warn(`${l}: failed to import server entry:`,e instanceof Error?e.message:e);continue}let f=o(d.default,e.name,l);f&&(i.push(...f),e.config?.defaults&&a.set(e.name,e.config.defaults))}return{packages:i,configDefaults:a}}function o(e,t,n){if(Array.isArray(e)){let r=[],i=new Set;for(let t of e){if(!f(t)){console.warn(`${n}: default export array contains an invalid MakaioExtension, skipping`);return}if(i.has(t.name)){console.warn(`${n}: default export array contains duplicate package name '${t.name}', skipping`);return}i.add(t.name),r.push(t)}if(!r.some(e=>e.name===t)){console.warn(`${n}: default export array must include a package named '${t}' to match descriptor identity, skipping`);return}if(r.some(e=>e.name!==t&&!e.name.startsWith(`${t}.`))){console.warn(`${n}: default export array contains package names outside descriptor namespace '${t}', skipping`);return}return r}if(!f(e)){console.warn(`${n}: default export is not a valid MakaioExtension or MakaioExtension[], skipping`);return}if(e.name!==t){console.warn(`${n}: imported package name '${e.name}' does not match descriptor name '${t}', skipping`);return}return[e]}async function s(e,t,n){let{importModule:r=S,frameworkVersion:i}=n,a=new Map(t.map(e=>[e.name,e])),o=new Map;for(let t of e){let e=c(t,i);if(!e)continue;let n=`[extensions] ${t.descriptor.name}@${t.descriptor.version}`,s=a.get(t.descriptor.name);if(s?.cli)continue;let u=await d(t,e,n,r);if(!u)continue;if(!p(u.default)){console.warn(`${n}: default export is not a valid CliContribution, skipping`);continue}let f=t.descriptor.cli?.name??t.descriptor.name;if(u.default.name!==f){console.warn(`${n}: imported CLI contribution name '${u.default.name}' does not match descriptor CLI name '${f}', skipping`);continue}if(s){a.set(t.descriptor.name,{...s,cli:u.default});continue}if(t.descriptor.entrypoints?.server||t.descriptor.entrypoints?.browser){console.warn(`${n}: server or browser entry is present but no package was loaded, skipping CLI-only synthesis`);continue}a.set(t.descriptor.name,l(t,u.default)),t.descriptor.config?.defaults&&o.set(t.descriptor.name,t.descriptor.config.defaults)}return{packages:[...a.values()],configDefaults:o}}function c(e,t){if(u(e,t)&&e.descriptor.execution!==`detached`)return e.descriptor.entrypoints?.cli}function l(t,n){return{...e(t.descriptor),cli:n}}function u(e,t){let{descriptor:n}=e,r=`[extensions] ${n.name}@${n.version}`;try{return i(t,n.makaio.framework)?!0:(console.warn(`${r}: requires framework ${n.makaio.framework}, current is ${t}, skipping`),!1)}catch(e){return console.warn(`${r}: invalid version metadata (framework=${t}, range=${n.makaio.framework}), skipping:`,e instanceof Error?e.message:e),!1}}async function d(e,t,n,r){try{let i=_(`cli`,t,e.extensionPath);if(!i){console.warn(`${n}: cli entrypoint has no resolvable candidate within extension directory, skipping`);return}return await r(i)}catch(e){console.warn(`${n}: failed to import cli entry:`,e instanceof Error?e.message:e);return}}function f(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name==`string`&&typeof t.displayName==`string`&&typeof t.version==`string`}function p(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name!=`string`||typeof t.description!=`string`||!Array.isArray(t.subcommands)||`interactive`in t&&t.interactive!==void 0&&typeof t.interactive!=`function`?!1:t.subcommands.length===0?typeof t.interactive==`function`:t.subcommands.every(m)}function m(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name==`string`&&typeof t.description==`string`&&h(t.schema)&&typeof t.handler==`function`}function h(e){return typeof e==`object`&&!!e&&typeof e.safeParse==`function`}function g(e,t){return t===!0?e:t}function _(e,t,r){if(!n.isAbsolute(r))return;let i=g(e,t),a=x(r),o=n.resolve(r,`src`,`${i}.ts`);if(y(o,a))return o;let s=n.resolve(r,`dist`,`${i}.mjs`);if(y(s,a))return s}function v(e,t){let n=x(t);return b(x(e),n)}function y(e,t){try{return b(r.realpathSync(e),t)}catch{return!1}}function b(e,t){return e.startsWith(t+n.sep)}function x(e){let t=n.resolve(e);try{return r.realpathSync(t)}catch{return t}}async function S(e){return await import(t(e).href)}export{f as a,_ as c,u as i,g as n,v as o,p as r,a as s,s as t};

package/dist/load-extensions-t2rtaz1C.d.mts

@@ -0,0 +1,117 @@
+import { t as DiscoveredExtension } from "./extension-discovery-CffOPDvn.mjs";
+import { KernelMakaioExtension } from "@makaio/framework/kernel";
+import { CliContribution } from "@makaio/framework/kernel/cli";
+
+//#region runtimes/node/src/load-extensions.d.ts
+/**
+ * Options for {@link loadExtensions}.
+ */
+interface LoadExtensionsOptions {
+  /** Current framework version for framework range gating. */
+  readonly frameworkVersion: string;
+  /**
+   * Override for filesystem-based dynamic import — used in tests and dev hosts.
+   * @param entryPath - Absolute path to the extension entry module.
+   * @returns Module with a default export.
+   */
+  readonly importModule?: (entryPath: string) => Promise<{
+    default: unknown;
+  }>;
+}
+/**
+ * Result returned by {@link loadExtensions}.
+ */
+interface ExtensionLoadResult {
+  /** Successfully loaded packages ready for `coordinator.load()`. */
+  readonly packages: KernelMakaioExtension[];
+  /**
+   * Config defaults from descriptors, keyed by extension name.
+   *
+   * Populated from `descriptor.config.defaults` for each successfully loaded
+   * extension. Passed to `coordinator.load()` as the `configDefaults` argument
+   * so the coordinator can merge them with stored config at startup.
+   */
+  readonly configDefaults: ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+}
+/**
+ * Packages emitted by one descriptor, ordered by caller-defined source priority.
+ */
+interface DescriptorSourcePackageGroup {
+  /** Descriptor name whose executable package surface this group represents. */
+  readonly descriptorName: string;
+  /** Stable source label for diagnostics, such as `workspace-descriptors`. */
+  readonly descriptorSource: string;
+  /** Packages produced from this descriptor. */
+  readonly packages: ReadonlyArray<KernelMakaioExtension>;
+}
+/**
+ * Load extensions by importing their server entry points.
+ *
+ * For each discovered extension:
+ * 1. Check `makaio.framework` range against the current framework version
+ * 2. If `execution` is `'detached'`, synthesize a managed {@link MakaioExtension}
+ *    via {@link createDetachedExtensionPackage} and continue.
+ * 3. Resolve `entrypoints.server` to an absolute path
+ * 4. Dynamic `import()` the module
+ * 5. Validate the default export looks like a {@link MakaioExtension} or
+ *    {@link MakaioExtension} array
+ * 6. Verify the imported package identity is anchored to the descriptor name
+ *
+ * Extensions that fail any step are skipped with a warning. This function
+ * never throws — boot continues even if all extensions fail.
+ * @param discovered - Extensions found by a {@link ExtensionDiscovery}.
+ * @param options - Framework version and optional import override.
+ * @returns Successfully loaded packages and their config defaults.
+ */
+declare function loadExtensions(discovered: ReadonlyArray<DiscoveredExtension>, options: LoadExtensionsOptions): Promise<ExtensionLoadResult>;
+/**
+ * Minimal structural check for a MakaioExtension-like default export.
+ * Does not use Zod — just validates the minimum required fields exist.
+ * @param value - The default export to check.
+ * @returns Whether the value is a valid {@link MakaioExtension} shape.
+ */
+declare function isMakaioExtensionLike(value: unknown): value is KernelMakaioExtension;
+/**
+ * Minimal structural check for a {@link CliContribution}-like default export.
+ *
+ * An extension CLI contribution is only useful when it exposes executable
+ * behavior, so the validator requires at least one of:
+ * - an `interactive` handler, or
+ * - one or more executable subcommand entries.
+ * @param value - The default export to check.
+ * @returns Whether the value is a valid executable CLI contribution shape.
+ */
+declare function isCliContributionLike(value: unknown): value is CliContribution;
+/**
+ * Derive the stem string from a descriptor entrypoint declaration.
+ * `true` resolves to the surface name; a string value is already the stem.
+ * @param surface - Runtime surface name.
+ * @param entrypointValue - Descriptor entrypoint declaration (`true` or a stem string).
+ * @returns Resolved stem string.
+ */
+declare function entrypointStem(surface: string, entrypointValue: true | string): string;
+/**
+ * Resolve a descriptor entrypoint using the convention: try `src/{stem}.ts`
+ * (dev) then `dist/{stem}.mjs` (production). The first candidate that exists
+ * and passes the extension-root containment check is returned.
+ *
+ * `true` means use the surface name as the stem. A string value is a custom
+ * stem (e.g. `"cli/index"` → `src/cli/index.ts` or `dist/cli/index.mjs`).
+ * @param surface - Runtime surface name (`"server"`, `"browser"`, or `"cli"`).
+ * @param entrypointValue - Descriptor entrypoint declaration (`true` or a stem string).
+ * @param extensionPath - Absolute extension root path.
+ * @returns Absolute resolved path when a valid candidate exists, otherwise `undefined`.
+ */
+declare function resolveConventionEntrypoint(surface: string, entrypointValue: true | string, extensionPath: string): string | undefined;
+/**
+ * Check that a resolved path stays within a base directory.
+ *
+ * Prevents path traversal attacks in descriptor.json entrypoints by rejecting
+ * absolute paths, `../` sequences, or symlinks that escape the extension root.
+ * @param resolved - The fully resolved absolute path.
+ * @param baseDir - The directory the path must stay within.
+ * @returns Whether `resolved` is a descendant of `baseDir`.
+ */
+declare function isWithinDirectory(resolved: string, baseDir: string): boolean;
+//#endregion
+export { isMakaioExtensionLike as a, resolveConventionEntrypoint as c, isCliContributionLike as i, LoadExtensionsOptions as n, isWithinDirectory as o, entrypointStem as r, loadExtensions as s, DescriptorSourcePackageGroup as t };