@holo-js/kernel 0.3.7 → 0.3.10

package/dist/index.d.ts

@@ -43,6 +43,9 @@ type HoloPluginCliContributions = {
 type HoloPluginMigrationContributions = {
     readonly publish?: string;
 };
+type HoloPluginProjectContributions = {
+    readonly prepare?: string;
+};
 type HoloPluginFrameworkTsconfigKind = 'nuxt' | 'next' | 'sveltekit';
 type HoloPluginPackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
 type HoloPluginFrameworkContribution = {
@@ -90,6 +93,7 @@ type HoloPluginContributions = {
     readonly runtime?: HoloPluginRuntimeContributions;
     readonly cli?: HoloPluginCliContributions;
     readonly migrations?: HoloPluginMigrationContributions;
+    readonly project?: HoloPluginProjectContributions;
 };
 type HoloPluginDefinition = {
     readonly id: string;
@@ -169,6 +173,110 @@ declare const DEFAULT_HOLO_PROJECT_PATHS: Readonly<HoloProjectPaths>;
 declare function normalizeHoloProjectConfig(config?: HoloProjectConfig): NormalizedHoloProjectConfig;
 declare function defineHoloProject<TConfig extends HoloProjectConfig>(config: TConfig): NormalizedHoloProjectConfig & TConfig;
 
+declare const HOLO_PROJECT_PREPARE_API_VERSION: 1;
+type HoloProjectPrepareCommand = 'prepare' | 'dev' | 'build';
+type HoloProjectPrepareChangeKind = 'created' | 'changed' | 'deleted';
+interface HoloProjectPrepareChange {
+    readonly path: string;
+    readonly kind: HoloProjectPrepareChangeKind;
+}
+type HoloProjectPrepareRun = {
+    readonly kind: 'full';
+    readonly command: HoloProjectPrepareCommand;
+    readonly reason: 'initial' | 'explicit' | 'configuration-changed' | 'dependencies-changed' | 'plugin-requested';
+} | {
+    readonly kind: 'incremental';
+    readonly command: 'dev';
+    readonly changes: readonly HoloProjectPrepareChange[];
+};
+interface HoloProjectPrepareFramework {
+    readonly id: string;
+    readonly displayName: string;
+    readonly adapterPackage: `@holo-js/${string}`;
+    readonly fluxPackage?: `@holo-js/${string}`;
+    readonly capabilities: {
+        readonly managedBroadcastAuthRoute: boolean;
+    };
+}
+interface HoloProjectPreparePlugin {
+    readonly id: string;
+    readonly name?: string;
+    readonly packageName: string;
+    readonly packageRoot: string;
+}
+interface HoloProjectPrepareLogger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+interface HoloProjectPrepareContext {
+    readonly projectRoot: string;
+    readonly generatedRoot: string;
+    readonly pluginGeneratedRoot: string;
+    readonly config: NormalizedHoloProjectConfig;
+    readonly framework?: HoloProjectPrepareFramework;
+    readonly plugin: HoloProjectPreparePlugin;
+    readonly run: HoloProjectPrepareRun;
+    readonly signal: AbortSignal;
+    readonly logger: HoloProjectPrepareLogger;
+}
+type HoloProjectArtifactContents = string | Uint8Array;
+interface HoloGeneratedProjectArtifact {
+    readonly path: string;
+    readonly contents: HoloProjectArtifactContents;
+}
+interface HoloManagedProjectArtifact {
+    readonly path: string;
+    readonly contents: HoloProjectArtifactContents;
+}
+interface HoloProjectPrepareWatch {
+    readonly roots?: readonly string[];
+    readonly excludes?: readonly string[];
+}
+interface HoloProjectPrepareSource {
+    readonly path: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+interface HoloProjectPrepareDiagnostic {
+    readonly severity: 'info' | 'warning';
+    readonly code: string;
+    readonly message: string;
+    readonly source?: HoloProjectPrepareSource;
+    readonly hint?: string;
+}
+interface HoloProjectPrepareFailure {
+    readonly code: string;
+    readonly message: string;
+    readonly source?: HoloProjectPrepareSource;
+    readonly hint?: string;
+}
+declare class HoloProjectPrepareError extends Error {
+    readonly failure: Readonly<HoloProjectPrepareFailure>;
+    constructor(failure: HoloProjectPrepareFailure);
+}
+interface HoloProjectPreparedResult {
+    readonly kind: 'prepared';
+    readonly generatedArtifacts?: readonly HoloGeneratedProjectArtifact[];
+    readonly managedArtifacts?: readonly HoloManagedProjectArtifact[];
+    readonly watch?: HoloProjectPrepareWatch;
+    readonly diagnostics?: readonly HoloProjectPrepareDiagnostic[];
+}
+interface HoloProjectPrepareFullRetry {
+    readonly kind: 'retry-full';
+    readonly reason: string;
+}
+type HoloProjectPrepareResult = HoloProjectPreparedResult | HoloProjectPrepareFullRetry;
+interface HoloProjectPreparer {
+    readonly apiVersion: typeof HOLO_PROJECT_PREPARE_API_VERSION;
+    prepare(context: HoloProjectPrepareContext): HoloProjectPrepareResult | Promise<HoloProjectPrepareResult>;
+}
+type HoloProjectPrepareModule = HoloProjectPreparer | {
+    readonly default: HoloProjectPreparer;
+} | {
+    readonly preparer: HoloProjectPreparer;
+};
+declare function defineHoloProjectPreparer<TPreparer extends HoloProjectPreparer>(preparer: TPreparer): Readonly<TPreparer>;
+
 interface HoloRedisConnectionConfig {
     readonly url?: string;
     readonly clusters?: readonly HoloRedisClusterNodeConfig[];
@@ -219,4 +327,4 @@ declare function resolveNormalizedRedisConnection(config: NormalizedHoloRedisCon
 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 };
+export { DEFAULT_HOLO_PROJECT_PATHS, DEFAULT_REDIS_CONNECTION, DEFAULT_REDIS_DB, DEFAULT_REDIS_HOST, DEFAULT_REDIS_PORT, HOLO_PROJECT_PREPARE_API_VERSION, type HoloDatabaseDriver, type HoloGeneratedProjectArtifact, type HoloManagedProjectArtifact, 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 HoloPluginProjectContributions, type HoloPluginQueueContributions, type HoloPluginRuntimeContributions, type HoloPluginRuntimeMapContributions, type HoloPluginRuntimeModule, type HoloProjectArtifactContents, type HoloProjectConfig, type HoloProjectConnectionConfig, type HoloProjectDatabaseConfig, type HoloProjectPaths, type HoloProjectPrepareChange, type HoloProjectPrepareChangeKind, type HoloProjectPrepareCommand, type HoloProjectPrepareContext, type HoloProjectPrepareDiagnostic, HoloProjectPrepareError, type HoloProjectPrepareFailure, type HoloProjectPrepareFramework, type HoloProjectPrepareFullRetry, type HoloProjectPrepareLogger, type HoloProjectPrepareModule, type HoloProjectPreparePlugin, type HoloProjectPrepareResult, type HoloProjectPrepareRun, type HoloProjectPrepareSource, type HoloProjectPrepareWatch, type HoloProjectPreparedResult, type HoloProjectPreparer, 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, defineHoloProjectPreparer, defineRedisConfig, holoRedisDefaults, loadHoloPluginBootModules, loadHoloPluginContributionModules, loadHoloPluginDefinitions, normalizeHoloPluginDefinition, normalizeHoloProjectConfig, normalizeRedisConfig, resolveHoloPluginModulePath, resolveNormalizedRedisConnection };

package/dist/index.mjs

@@ -85,7 +85,7 @@ 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);
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeString(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
@@ -123,6 +123,22 @@ function normalizeHoloPluginDefinition(value) {
   if (!isRecord(candidate) || !normalizeString(candidate.id)) {
     throw new Error("[Holo Plugins] Plugin entry must export a plugin definition with an id.");
   }
+  if (isRecord(candidate.contributes) && "project" in candidate.contributes) {
+    const project = candidate.contributes.project;
+    if (!isRecord(project)) {
+      throw new Error("[Holo Plugins] contributes.project must be an object.");
+    }
+    if ("prepare" in project && !normalizeString(project.prepare)) {
+      throw new Error("[Holo Plugins] contributes.project.prepare must be a non-empty string.");
+    }
+    return Object.freeze({
+      ...candidate,
+      contributes: Object.freeze({
+        ...candidate.contributes,
+        project: Object.freeze({ prepare: normalizeString(project.prepare) })
+      })
+    });
+  }
   return Object.freeze({ ...candidate });
 }
 function defineHoloPlugin(plugin) {
@@ -243,6 +259,20 @@ function defineHoloProject(config) {
   return normalizeHoloProjectConfig(config);
 }
 
+// src/project-prepare.ts
+var HOLO_PROJECT_PREPARE_API_VERSION = 1;
+var HoloProjectPrepareError = class extends Error {
+  failure;
+  constructor(failure) {
+    super(failure.message);
+    this.name = "HoloProjectPrepareError";
+    this.failure = Object.freeze({ ...failure });
+  }
+};
+function defineHoloProjectPreparer(preparer) {
+  return Object.freeze({ ...preparer });
+}
+
 // src/redis.ts
 var DEFAULT_REDIS_CONNECTION = "default";
 var DEFAULT_REDIS_HOST = "127.0.0.1";
@@ -402,10 +432,13 @@ export {
   DEFAULT_REDIS_DB,
   DEFAULT_REDIS_HOST,
   DEFAULT_REDIS_PORT,
+  HOLO_PROJECT_PREPARE_API_VERSION,
+  HoloProjectPrepareError,
   RuntimeLifecycle,
   createRuntimeLifecycle,
   defineHoloPlugin,
   defineHoloProject,
+  defineHoloProjectPreparer,
   defineRedisConfig,
   holoRedisDefaults,
   isHoloHttpErrorStatus,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/kernel",
-  "version": "0.3.7",
+  "version": "0.3.10",
   "description": "Holo-JS Framework - dependency-free contracts, plugins, and runtime lifecycle",
   "type": "module",
   "license": "MIT",