@holo-js/kernel 0.3.0

package/dist/chunk-UIGMROG3.mjs

@@ -0,0 +1,105 @@
+// src/httpErrors.ts
+var httpStatuses = /* @__PURE__ */ new Set([
+  400,
+  401,
+  402,
+  403,
+  404,
+  405,
+  406,
+  407,
+  408,
+  409,
+  410,
+  411,
+  412,
+  413,
+  414,
+  415,
+  416,
+  417,
+  418,
+  421,
+  422,
+  423,
+  424,
+  425,
+  426,
+  428,
+  429,
+  431,
+  451,
+  500,
+  501,
+  502,
+  503,
+  504,
+  505,
+  506,
+  507,
+  508,
+  510,
+  511
+]);
+function isObject(value) {
+  return !!value && typeof value === "object";
+}
+function readNumber(value) {
+  return typeof value === "number" && Number.isInteger(value) ? value : void 0;
+}
+function readString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function readStatus(error) {
+  if (!isObject(error)) {
+    return void 0;
+  }
+  const directStatus = readNumber(error.status);
+  if (directStatus) {
+    return directStatus;
+  }
+  const statusCode = readNumber(error.statusCode);
+  if (statusCode) {
+    return statusCode;
+  }
+  const digest = readString(error.digest);
+  const nextHttpStatus = digest?.match(/^NEXT_HTTP_ERROR_FALLBACK;(\d{3})$/)?.[1];
+  return nextHttpStatus ? Number(nextHttpStatus) : void 0;
+}
+function readMessage(error) {
+  if (error instanceof Error && error.message.length > 0) {
+    return error.message;
+  }
+  const message = readString(error.message);
+  if (message) {
+    return message;
+  }
+  const statusText = readString(error.statusText);
+  if (statusText) {
+    return statusText;
+  }
+  return "An unexpected error occurred.";
+}
+function readCode(error) {
+  return readString(error.code);
+}
+function isHoloHttpErrorStatus(status) {
+  return httpStatuses.has(status);
+}
+function normalizeHoloHttpError(error) {
+  const status = readStatus(error);
+  if (!status || !isHoloHttpErrorStatus(status)) {
+    return void 0;
+  }
+  return {
+    status,
+    message: readMessage(error),
+    code: readCode(error),
+    cause: error
+  };
+}
+
+export {
+  isHoloHttpErrorStatus,
+  normalizeHoloHttpError
+};

package/dist/http-errors.d.ts

@@ -0,0 +1,11 @@
+type HoloHttpErrorStatus = 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511;
+type NormalizedHoloHttpError = {
+    readonly status: HoloHttpErrorStatus;
+    readonly message: string;
+    readonly code?: string;
+    readonly cause: unknown;
+};
+declare function isHoloHttpErrorStatus(status: number): status is HoloHttpErrorStatus;
+declare function normalizeHoloHttpError(error: unknown): NormalizedHoloHttpError | undefined;
+
+export { type HoloHttpErrorStatus, type NormalizedHoloHttpError, isHoloHttpErrorStatus, normalizeHoloHttpError };

package/dist/http-errors.mjs

@@ -0,0 +1,8 @@
+import {
+  isHoloHttpErrorStatus,
+  normalizeHoloHttpError
+} from "./chunk-UIGMROG3.mjs";
+export {
+  isHoloHttpErrorStatus,
+  normalizeHoloHttpError
+};

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+export { HoloHttpErrorStatus, NormalizedHoloHttpError, isHoloHttpErrorStatus, normalizeHoloHttpError } from './http-errors.js';
+
+interface RuntimeLifecycleContext {
+    readonly projectRoot: string;
+}
+interface RuntimeContribution<TContext extends RuntimeLifecycleContext = RuntimeLifecycleContext> {
+    readonly name: string;
+    readonly dependsOn?: readonly string[];
+    initialize(context: TContext): void | Promise<void>;
+    dispose?(context: TContext): void | Promise<void>;
+}
+declare class RuntimeLifecycle<TContext extends RuntimeLifecycleContext = RuntimeLifecycleContext> {
+    private readonly ordered;
+    private initialized;
+    constructor(contributions: readonly RuntimeContribution<TContext>[]);
+    initialize(context: TContext): Promise<void>;
+    dispose(context: TContext): Promise<void>;
+}
+declare function createRuntimeLifecycle<TContext extends RuntimeLifecycleContext>(contributions: readonly RuntimeContribution<TContext>[]): RuntimeLifecycle<TContext>;
+
+type HoloPluginDependencyContributions = {
+    readonly runtime?: readonly string[];
+    readonly holo?: readonly `@holo-js/${string}`[];
+};
+type HoloPluginConfigContributions = {
+    readonly files?: readonly string[];
+    readonly env?: readonly string[];
+};
+type HoloPluginRuntimeMapContributions<TKey extends 'drivers' | 'channels'> = Readonly<Record<TKey, Readonly<Record<string, {
+    readonly runtime: string;
+}>>>>;
+type HoloPluginBroadcastContributions = HoloPluginRuntimeMapContributions<'drivers'>;
+type HoloPluginCacheContributions = HoloPluginRuntimeMapContributions<'drivers'>;
+type HoloPluginQueueContributions = HoloPluginRuntimeMapContributions<'drivers'>;
+type HoloPluginMailContributions = HoloPluginRuntimeMapContributions<'drivers'>;
+type HoloPluginNotificationContributions = HoloPluginRuntimeMapContributions<'channels'>;
+type HoloPluginRuntimeContributions = {
+    readonly boot?: string;
+};
+type HoloPluginCliContributions = {
+    readonly commands?: string;
+};
+type HoloPluginMigrationContributions = {
+    readonly publish?: string;
+};
+type HoloPluginFrameworkTsconfigKind = 'nuxt' | 'next' | 'sveltekit';
+type HoloPluginPackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+type HoloPluginFrameworkContribution = {
+    readonly id: string;
+    readonly displayName: string;
+    readonly detectPackages: readonly string[];
+    readonly adapterPackage: `@holo-js/${string}`;
+    readonly fluxPackage?: `@holo-js/${string}`;
+    readonly scaffold: {
+        readonly dependencies: Readonly<Record<string, string>>;
+        readonly devDependencies: Readonly<Record<string, string>>;
+        readonly scripts: Readonly<Record<string, string>>;
+        readonly lintScript: string;
+        readonly typecheckScript: string;
+        readonly defaultUrl: string;
+        readonly tsconfig: HoloPluginFrameworkTsconfigKind;
+        readonly vscodeVueHybridMode?: boolean;
+    };
+    readonly runner: {
+        readonly commandName: string;
+        readonly buildArgs: readonly string[];
+        readonly start: readonly string[];
+        readonly startUsesFrameworkBinary: boolean;
+        readonly preloadNextRuntime: boolean;
+        readonly suppressSvelteKitOutput: boolean;
+        readonly nextDevServerConflictHandling: boolean;
+    };
+    readonly sync?: {
+        readonly commands: Readonly<Record<HoloPluginPackageManager, readonly [string, ...string[]]>>;
+        readonly errorLabel: string;
+    };
+    readonly capabilities: {
+        readonly managedBroadcastAuthRoute: boolean;
+    };
+};
+type HoloPluginContributions = {
+    readonly dependencies?: HoloPluginDependencyContributions;
+    readonly config?: HoloPluginConfigContributions;
+    readonly framework?: HoloPluginFrameworkContribution;
+    readonly broadcast?: HoloPluginBroadcastContributions;
+    readonly cache?: HoloPluginCacheContributions;
+    readonly queue?: HoloPluginQueueContributions;
+    readonly mail?: HoloPluginMailContributions;
+    readonly notifications?: HoloPluginNotificationContributions;
+    readonly runtime?: HoloPluginRuntimeContributions;
+    readonly cli?: HoloPluginCliContributions;
+    readonly migrations?: HoloPluginMigrationContributions;
+};
+type HoloPluginDefinition = {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly contributes?: HoloPluginContributions;
+};
+type LoadedHoloPluginDefinition = {
+    readonly packageName: string;
+    readonly packageRoot: string;
+    readonly entryPath: string;
+    readonly definition: HoloPluginDefinition;
+};
+type HoloPluginRuntimeModule = {
+    readonly plugin: LoadedHoloPluginDefinition;
+    readonly name: string;
+    readonly runtime: string;
+    readonly module: unknown;
+};
+type PluginLoadOptions = {
+    readonly moduleVersion?: string;
+};
+declare function normalizeHoloPluginDefinition(value: unknown): HoloPluginDefinition;
+declare function defineHoloPlugin<TPlugin extends HoloPluginDefinition>(plugin: TPlugin): Readonly<TPlugin>;
+declare function resolveHoloPluginModulePath(projectRoot: string, plugin: LoadedHoloPluginDefinition, specifier: string): string;
+declare function loadHoloPluginDefinitions(projectRoot: string, packageNames: readonly string[], options?: PluginLoadOptions): Promise<readonly LoadedHoloPluginDefinition[]>;
+declare function loadHoloPluginContributionModules(projectRoot: string, plugins: readonly LoadedHoloPluginDefinition[], scope: string, key: string, options?: PluginLoadOptions): Promise<readonly HoloPluginRuntimeModule[]>;
+declare function loadHoloPluginBootModules(projectRoot: string, plugins: readonly LoadedHoloPluginDefinition[], options?: PluginLoadOptions): Promise<readonly HoloPluginRuntimeModule[]>;
+
+type HoloDatabaseDriver = 'sqlite' | 'postgres' | 'mysql';
+interface HoloProjectPaths {
+    models: string;
+    migrations: string;
+    generatedSchema: string;
+    seeders: string;
+    observers: string;
+    factories: string;
+    commands: string;
+    jobs: string;
+    events: string;
+    listeners: string;
+    authorizationPolicies: string;
+    authorizationAbilities: string;
+}
+interface HoloProjectConnectionConfig {
+    driver?: HoloDatabaseDriver;
+    url?: string;
+    host?: string;
+    port?: number | string;
+    username?: string;
+    password?: string;
+    database?: string;
+    filename?: string;
+    schema?: string;
+    ssl?: boolean | Record<string, unknown>;
+    logging?: boolean;
+}
+interface HoloProjectDatabaseConfig {
+    defaultConnection?: string;
+    connections?: Record<string, HoloProjectConnectionConfig | string>;
+}
+interface HoloProjectConfig {
+    paths?: Partial<HoloProjectPaths>;
+    database?: HoloProjectDatabaseConfig;
+    models?: readonly string[];
+    migrations?: readonly string[];
+    seeders?: readonly string[];
+}
+interface NormalizedHoloProjectConfig {
+    readonly paths: Readonly<HoloProjectPaths>;
+    readonly database?: HoloProjectDatabaseConfig;
+    readonly models: readonly string[];
+    readonly migrations: readonly string[];
+    readonly seeders: readonly string[];
+}
+declare const DEFAULT_HOLO_PROJECT_PATHS: Readonly<HoloProjectPaths>;
+declare function normalizeHoloProjectConfig(config?: HoloProjectConfig): NormalizedHoloProjectConfig;
+declare function defineHoloProject<TConfig extends HoloProjectConfig>(config: TConfig): NormalizedHoloProjectConfig & TConfig;
+
+interface HoloRedisConnectionConfig {
+    readonly url?: string;
+    readonly clusters?: readonly HoloRedisClusterNodeConfig[];
+    readonly socketPath?: string;
+    readonly host?: string;
+    readonly port?: number | string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly db?: number | string;
+}
+interface HoloRedisClusterNodeConfig {
+    readonly url?: string;
+    readonly socketPath?: string;
+    readonly host?: string;
+    readonly port?: number | string;
+}
+interface HoloRedisConfig {
+    readonly default?: string;
+    readonly connections?: Readonly<Record<string, HoloRedisConnectionConfig>>;
+}
+interface NormalizedHoloRedisConnectionConfig {
+    readonly name: string;
+    readonly url?: string;
+    readonly clusters?: readonly NormalizedHoloRedisClusterNodeConfig[];
+    readonly socketPath?: string;
+    readonly host: string;
+    readonly port: number;
+    readonly username?: string;
+    readonly password?: string;
+    readonly db: number;
+}
+interface NormalizedHoloRedisClusterNodeConfig {
+    readonly url?: string;
+    readonly socketPath?: string;
+    readonly host: string;
+    readonly port: number;
+}
+interface NormalizedHoloRedisConfig {
+    readonly default: string;
+    readonly connections: Readonly<Record<string, NormalizedHoloRedisConnectionConfig>>;
+}
+declare const DEFAULT_REDIS_CONNECTION = "default";
+declare const DEFAULT_REDIS_HOST = "127.0.0.1";
+declare const DEFAULT_REDIS_PORT = 6379;
+declare const DEFAULT_REDIS_DB = 0;
+declare const holoRedisDefaults: Readonly<NormalizedHoloRedisConfig>;
+declare function resolveNormalizedRedisConnection(config: NormalizedHoloRedisConfig, connectionName: string, label: string): NormalizedHoloRedisConnectionConfig;
+declare function normalizeRedisConfig(config?: HoloRedisConfig): NormalizedHoloRedisConfig;
+declare function defineRedisConfig<TConfig extends HoloRedisConfig>(config: TConfig): Readonly<TConfig>;
+
+export { DEFAULT_HOLO_PROJECT_PATHS, DEFAULT_REDIS_CONNECTION, DEFAULT_REDIS_DB, DEFAULT_REDIS_HOST, DEFAULT_REDIS_PORT, type HoloDatabaseDriver, type HoloPluginBroadcastContributions, type HoloPluginCacheContributions, type HoloPluginCliContributions, type HoloPluginConfigContributions, type HoloPluginContributions, type HoloPluginDefinition, type HoloPluginDependencyContributions, type HoloPluginFrameworkContribution, type HoloPluginFrameworkTsconfigKind, type HoloPluginMailContributions, type HoloPluginMigrationContributions, type HoloPluginNotificationContributions, type HoloPluginPackageManager, type HoloPluginQueueContributions, type HoloPluginRuntimeContributions, type HoloPluginRuntimeMapContributions, type HoloPluginRuntimeModule, type HoloProjectConfig, type HoloProjectConnectionConfig, type HoloProjectDatabaseConfig, type HoloProjectPaths, type HoloRedisClusterNodeConfig, type HoloRedisConfig, type HoloRedisConnectionConfig, type LoadedHoloPluginDefinition, type NormalizedHoloProjectConfig, type NormalizedHoloRedisClusterNodeConfig, type NormalizedHoloRedisConfig, type NormalizedHoloRedisConnectionConfig, type PluginLoadOptions, type RuntimeContribution, RuntimeLifecycle, type RuntimeLifecycleContext, createRuntimeLifecycle, defineHoloPlugin, defineHoloProject, defineRedisConfig, holoRedisDefaults, loadHoloPluginBootModules, loadHoloPluginContributionModules, loadHoloPluginDefinitions, normalizeHoloPluginDefinition, normalizeHoloProjectConfig, normalizeRedisConfig, resolveHoloPluginModulePath, resolveNormalizedRedisConnection };

package/dist/index.mjs

@@ -0,0 +1,421 @@
+import {
+  isHoloHttpErrorStatus,
+  normalizeHoloHttpError
+} from "./chunk-UIGMROG3.mjs";
+
+// src/lifecycle.ts
+function orderContributions(contributions) {
+  const byName = new Map(contributions.map((contribution) => [contribution.name, contribution]));
+  if (byName.size !== contributions.length) {
+    throw new Error("[Holo Runtime] Runtime contribution names must be unique.");
+  }
+  const ordered = [];
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (contribution) => {
+    if (visited.has(contribution.name)) return;
+    if (visiting.has(contribution.name)) {
+      throw new Error(`[Holo Runtime] Circular runtime dependency at "${contribution.name}".`);
+    }
+    visiting.add(contribution.name);
+    for (const dependencyName of contribution.dependsOn ?? []) {
+      const dependency = byName.get(dependencyName);
+      if (!dependency) {
+        throw new Error(`[Holo Runtime] Contribution "${contribution.name}" requires missing contribution "${dependencyName}".`);
+      }
+      visit(dependency);
+    }
+    visiting.delete(contribution.name);
+    visited.add(contribution.name);
+    ordered.push(contribution);
+  };
+  contributions.forEach(visit);
+  return Object.freeze(ordered);
+}
+var RuntimeLifecycle = class {
+  ordered;
+  initialized = [];
+  constructor(contributions) {
+    this.ordered = orderContributions(contributions);
+  }
+  async initialize(context) {
+    if (this.initialized.length > 0) {
+      throw new Error("[Holo Runtime] Runtime lifecycle is already initialized.");
+    }
+    try {
+      for (const contribution of this.ordered) {
+        this.initialized.push(contribution);
+        await contribution.initialize(context);
+      }
+    } catch (error) {
+      try {
+        await this.dispose(context);
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "[Holo Runtime] Initialization and rollback both failed.");
+      }
+      throw error;
+    }
+  }
+  async dispose(context) {
+    const initialized = this.initialized;
+    this.initialized = [];
+    const failures = [];
+    for (const contribution of initialized.reverse()) {
+      try {
+        await contribution.dispose?.(context);
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length === 1) {
+      throw failures[0];
+    }
+    if (failures.length > 1) {
+      throw new AggregateError(failures, "[Holo Runtime] Multiple runtime contributions failed to dispose.");
+    }
+  }
+};
+function createRuntimeLifecycle(contributions) {
+  return new RuntimeLifecycle(contributions);
+}
+
+// src/plugins.ts
+import { createRequire } from "module";
+import { readFile } from "fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+import { pathToFileURL } from "url";
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function assertValidPackageName(packageName) {
+  if (!(/^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i.test(packageName) || /^[a-z0-9][a-z0-9._-]*$/i.test(packageName))) {
+    throw new Error(`[Holo Plugins] Invalid plugin package name: ${packageName}.`);
+  }
+}
+function assertPackageRelativePath(packageName, value) {
+  if (isAbsolute(value)) {
+    throw new Error(`[Holo Plugins] Plugin ${packageName} declared an absolute module path.`);
+  }
+}
+function resolvePackageJsonPath(projectRoot, packageName) {
+  assertValidPackageName(packageName);
+  try {
+    return createRequire(join(projectRoot, "package.json")).resolve(`${packageName}/package.json`);
+  } catch {
+    return join(projectRoot, "node_modules", ...packageName.split("/"), "package.json");
+  }
+}
+async function loadModule(projectRoot, modulePath, options = {}) {
+  const resolvedPath = createRequire(join(projectRoot, "package.json")).resolve(modulePath);
+  const moduleUrl = pathToFileURL(resolvedPath).href;
+  const versionedUrl = options.moduleVersion ? `${moduleUrl}?v=${encodeURIComponent(options.moduleVersion)}` : moduleUrl;
+  return await import(
+    /* webpackIgnore: true */
+    versionedUrl
+  );
+}
+function normalizeHoloPluginDefinition(value) {
+  const module = value;
+  const candidate = "default" in module ? module.default : "plugin" in module ? module.plugin : module;
+  if (!isRecord(candidate) || !normalizeString(candidate.id)) {
+    throw new Error("[Holo Plugins] Plugin entry must export a plugin definition with an id.");
+  }
+  return Object.freeze({ ...candidate });
+}
+function defineHoloPlugin(plugin) {
+  return Object.freeze({ ...plugin });
+}
+function resolveHoloPluginModulePath(projectRoot, plugin, specifier) {
+  const normalized = specifier.trim();
+  if (!normalized) throw new Error(`[Holo Plugins] Plugin ${plugin.packageName} declared an empty module specifier.`);
+  assertPackageRelativePath(plugin.packageName, normalized);
+  if (!normalized.startsWith(".")) {
+    return createRequire(join(resolve(projectRoot), "package.json")).resolve(normalized);
+  }
+  const modulePath = resolve(plugin.packageRoot, normalized);
+  const relativePath = relative(plugin.packageRoot, modulePath);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`[Holo Plugins] Plugin ${plugin.packageName} module must stay inside the package root.`);
+  }
+  return modulePath;
+}
+async function loadHoloPluginDefinitions(projectRoot, packageNames, options = {}) {
+  const root = resolve(projectRoot);
+  const loaded = [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const packageName of packageNames) {
+    const packageJsonPath = resolvePackageJsonPath(root, packageName);
+    let manifest;
+    try {
+      manifest = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    } catch (error) {
+      if (isRecord(error) && error.code === "ENOENT") throw new Error(`Cannot find module '${packageName}/package.json'`);
+      throw error;
+    }
+    if (!isRecord(manifest.holo) || !normalizeString(manifest.holo.plugin)) {
+      throw new Error(`[Holo Plugins] Plugin ${packageName} does not declare holo.plugin.`);
+    }
+    const entry = normalizeString(manifest.holo.plugin);
+    assertPackageRelativePath(packageName, entry);
+    const packageRoot = dirname(packageJsonPath);
+    const entryPath = resolve(packageRoot, entry);
+    const relativeEntry = relative(packageRoot, entryPath);
+    if (relativeEntry.startsWith("..") || isAbsolute(relativeEntry)) {
+      throw new Error(`[Holo Plugins] Plugin ${packageName} entry must stay inside the package root.`);
+    }
+    const definition = normalizeHoloPluginDefinition(await loadModule(root, entryPath, options));
+    if (ids.has(definition.id)) throw new Error(`[Holo Plugins] Duplicate plugin id "${definition.id}".`);
+    ids.add(definition.id);
+    loaded.push(Object.freeze({ packageName, packageRoot, entryPath, definition }));
+  }
+  return Object.freeze(loaded);
+}
+function contributionMap(plugin, scope, key) {
+  const contributions = plugin.definition.contributes;
+  const scopeValue = contributions?.[scope];
+  if (!isRecord(scopeValue) || !isRecord(scopeValue[key])) return Object.freeze({});
+  return Object.freeze(Object.fromEntries(Object.entries(scopeValue[key]).flatMap(([name, value]) => {
+    const runtime = isRecord(value) ? normalizeString(value.runtime) : void 0;
+    return runtime ? [[name, runtime]] : [];
+  })));
+}
+async function loadHoloPluginContributionModules(projectRoot, plugins, scope, key, options = {}) {
+  const modules = [];
+  const names = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    for (const [name, runtime] of Object.entries(contributionMap(plugin, scope, key))) {
+      if (names.has(name)) throw new Error(`[Holo Plugins] Duplicate ${scope}.${key} contribution "${name}".`);
+      names.add(name);
+      modules.push(Object.freeze({
+        plugin,
+        name,
+        runtime,
+        module: await loadModule(projectRoot, resolveHoloPluginModulePath(projectRoot, plugin, runtime), options)
+      }));
+    }
+  }
+  return Object.freeze(modules);
+}
+async function loadHoloPluginBootModules(projectRoot, plugins, options = {}) {
+  const modules = [];
+  for (const plugin of plugins) {
+    const runtimeScope = plugin.definition.contributes?.runtime;
+    const runtime = isRecord(runtimeScope) ? normalizeString(runtimeScope.boot) : void 0;
+    if (!runtime) continue;
+    modules.push(Object.freeze({
+      plugin,
+      name: "boot",
+      runtime,
+      module: await loadModule(projectRoot, resolveHoloPluginModulePath(projectRoot, plugin, runtime), options)
+    }));
+  }
+  return Object.freeze(modules);
+}
+
+// src/project.ts
+var DEFAULT_HOLO_PROJECT_PATHS = Object.freeze({
+  models: "server/models",
+  migrations: "server/db/migrations",
+  generatedSchema: ".holo-js/generated/schema.generated.ts",
+  seeders: "server/db/seeders",
+  observers: "server/db/observers",
+  factories: "server/db/factories",
+  commands: "server/commands",
+  jobs: "server/jobs",
+  events: "server/events",
+  listeners: "server/listeners",
+  authorizationPolicies: "server/policies",
+  authorizationAbilities: "server/abilities"
+});
+function normalizeHoloProjectConfig(config = {}) {
+  return Object.freeze({
+    paths: Object.freeze({ ...DEFAULT_HOLO_PROJECT_PATHS, ...config.paths ?? {} }),
+    ...config.database ? { database: { ...config.database } } : {},
+    models: Object.freeze([...config.models ?? []]),
+    migrations: Object.freeze([...config.migrations ?? []]),
+    seeders: Object.freeze([...config.seeders ?? []])
+  });
+}
+function defineHoloProject(config) {
+  return normalizeHoloProjectConfig(config);
+}
+
+// src/redis.ts
+var DEFAULT_REDIS_CONNECTION = "default";
+var DEFAULT_REDIS_HOST = "127.0.0.1";
+var DEFAULT_REDIS_PORT = 6379;
+var DEFAULT_REDIS_DB = 0;
+var holoRedisDefaults = Object.freeze({
+  default: DEFAULT_REDIS_CONNECTION,
+  connections: Object.freeze({
+    [DEFAULT_REDIS_CONNECTION]: Object.freeze({
+      name: DEFAULT_REDIS_CONNECTION,
+      host: DEFAULT_REDIS_HOST,
+      port: DEFAULT_REDIS_PORT,
+      username: void 0,
+      password: void 0,
+      db: DEFAULT_REDIS_DB
+    })
+  })
+});
+function normalizeName(value, label) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    throw new Error(`[Holo Redis] ${label} must be a non-empty string.`);
+  }
+  return normalized;
+}
+function parseInteger(value, fallback, label, minimum) {
+  if (typeof value === "undefined") {
+    return fallback;
+  }
+  const normalized = typeof value === "number" ? value : /^\d+$/.test(value.trim()) ? Number.parseInt(value.trim(), 10) : Number.NaN;
+  if (!Number.isSafeInteger(normalized)) {
+    throw new Error(`[Holo Redis] ${label} must be an integer.`);
+  }
+  if (normalized < minimum) {
+    throw new Error(`[Holo Redis] ${label} must be greater than or equal to ${minimum}.`);
+  }
+  return normalized;
+}
+function normalizeUrl(value, label) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  const normalized = normalizeName(value, label);
+  try {
+    const parsed = new URL(normalized);
+    if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+      throw new Error(`[Holo Redis] ${label} must use the redis:// or rediss:// scheme.`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("[Holo Redis]")) {
+      throw error;
+    }
+    throw new Error(`[Holo Redis] ${label} must be a valid redis:// or rediss:// URL.`);
+  }
+  return normalized;
+}
+function parseDatabaseFromUrl(url, label, allowPath) {
+  if (typeof url === "undefined") {
+    return void 0;
+  }
+  try {
+    const pathname = new URL(url).pathname.replace(/^\/+/, "");
+    if (!pathname) {
+      return void 0;
+    }
+    if (!allowPath) {
+      throw new Error(`[Holo Redis] ${label} cannot include a database path in cluster mode.`);
+    }
+    const [databaseSegment] = pathname.split("/");
+    if (!databaseSegment || !/^\d+$/.test(databaseSegment) || pathname !== databaseSegment) {
+      throw new Error(`[Holo Redis] ${label} database path must be a single integer segment.`);
+    }
+    return Number.parseInt(databaseSegment, 10);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("[Holo Redis]")) {
+      throw error;
+    }
+    return void 0;
+  }
+}
+function normalizeClusterNode(connectionName, index, config) {
+  const label = `redis connection "${connectionName}" cluster node ${index + 1}`;
+  const url = normalizeUrl(config.url, `${label} url`);
+  const socketPath = config.socketPath?.trim();
+  const hostValue = config.host?.trim();
+  if (socketPath || hostValue?.startsWith("unix://") || hostValue?.startsWith("/")) {
+    throw new Error(`[Holo Redis] ${label} cannot use socketPath in cluster mode.`);
+  }
+  parseDatabaseFromUrl(url, `${label} url`, false);
+  return Object.freeze({
+    ...typeof url === "undefined" ? {} : { url },
+    host: hostValue || DEFAULT_REDIS_HOST,
+    port: parseInteger(config.port, DEFAULT_REDIS_PORT, `${label} port`, 1)
+  });
+}
+function normalizeConnection(name, config) {
+  const url = normalizeUrl(config.url, `redis connection "${name}" url`);
+  const clusters = config.clusters?.length ? Object.freeze(config.clusters.map((node, index) => normalizeClusterNode(name, index, node))) : void 0;
+  const explicitSocketPath = config.socketPath?.trim();
+  const hostValue = config.host?.trim();
+  const socketPath = explicitSocketPath || (hostValue?.startsWith("unix://") ? hostValue.slice("unix://".length) : void 0) || (hostValue?.startsWith("/") ? hostValue : void 0);
+  const targetCount = [url, clusters, socketPath].filter((value) => typeof value !== "undefined").length;
+  if (targetCount > 1) {
+    throw new Error(`[Holo Redis] redis connection "${name}" must configure exactly one target mode: url, clusters, or socketPath.`);
+  }
+  const database = parseInteger(
+    config.db ?? parseDatabaseFromUrl(url, `redis connection "${name}" url`, true),
+    DEFAULT_REDIS_DB,
+    `redis connection "${name}" db`,
+    0
+  );
+  if (clusters && database !== 0) {
+    throw new Error(`[Holo Redis] redis connection "${name}" cannot select redis.db=${database} in cluster mode; Redis Cluster only supports database 0.`);
+  }
+  return Object.freeze({
+    name,
+    ...typeof url === "undefined" ? {} : { url },
+    ...typeof clusters === "undefined" ? {} : { clusters },
+    ...typeof socketPath === "undefined" ? {} : { socketPath },
+    host: hostValue || socketPath || DEFAULT_REDIS_HOST,
+    port: parseInteger(config.port, DEFAULT_REDIS_PORT, `redis connection "${name}" port`, 1),
+    username: config.username?.trim() || void 0,
+    password: config.password?.trim() || void 0,
+    db: database
+  });
+}
+function resolveNormalizedRedisConnection(config, connectionName, label) {
+  const connection = config.connections[connectionName];
+  if (!connection) {
+    throw new Error(`[Holo Redis] ${label} "${connectionName}" is not configured.`);
+  }
+  return connection;
+}
+function normalizeRedisConfig(config = {}) {
+  const connections = !config.connections || Object.keys(config.connections).length === 0 ? holoRedisDefaults.connections : Object.freeze(Object.fromEntries(Object.entries(config.connections).map(([name, connection]) => {
+    const normalizedName = normalizeName(name, "Redis connection name");
+    return [normalizedName, normalizeConnection(normalizedName, connection)];
+  })));
+  const connectionNames = Object.keys(connections);
+  const defaultConnection = config.default?.trim() || connectionNames[0];
+  if (!connections[defaultConnection]) {
+    throw new Error(
+      `[Holo Redis] default redis connection "${defaultConnection}" is not configured. Available connections: ${connectionNames.join(", ")}`
+    );
+  }
+  return Object.freeze({
+    default: defaultConnection,
+    connections
+  });
+}
+function defineRedisConfig(config) {
+  return Object.freeze({ ...config });
+}
+export {
+  DEFAULT_HOLO_PROJECT_PATHS,
+  DEFAULT_REDIS_CONNECTION,
+  DEFAULT_REDIS_DB,
+  DEFAULT_REDIS_HOST,
+  DEFAULT_REDIS_PORT,
+  RuntimeLifecycle,
+  createRuntimeLifecycle,
+  defineHoloPlugin,
+  defineHoloProject,
+  defineRedisConfig,
+  holoRedisDefaults,
+  isHoloHttpErrorStatus,
+  loadHoloPluginBootModules,
+  loadHoloPluginContributionModules,
+  loadHoloPluginDefinitions,
+  normalizeHoloHttpError,
+  normalizeHoloPluginDefinition,
+  normalizeHoloProjectConfig,
+  normalizeRedisConfig,
+  resolveHoloPluginModulePath,
+  resolveNormalizedRedisConnection
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@holo-js/kernel",
+  "version": "0.3.0",
+  "description": "Holo-JS Framework - dependency-free contracts, plugins, and runtime lifecycle",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./http-errors": {
+      "types": "./dist/http-errors.d.ts",
+      "import": "./dist/http-errors.mjs",
+      "default": "./dist/http-errors.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.5"
+  }
+}