@maligator/cli 0.1.0-alpha.3 → 0.1.0-alpha.30

package/application-api.d.ts

@@ -0,0 +1,23 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+/**
+ * Runtime lifecycle notifications for supervised applications. Module evaluation and
+ * application readiness are separate events; readiness means the application has
+ * finished its own startup work.
+ */
+declare module "maligator:application" {
+	/**
+	 * Notify the development supervisor that this application is ready. Repeated calls
+	 * are harmless. Returns true in a supervised application and false in a standalone
+	 * application or ordinary worker. Call after resources such as a server listener are
+	 * accepting work; this does not reserve ports or transfer traffic.
+	 *
+	 * @example
+	 * import { ready } from "maligator:application";
+	 * import { createServer } from "node:http";
+	 *
+	 * createServer((_request, response) => response.end("hello")).listen(3000, () => ready());
+	 *
+	 * @see https://maligator.ddv.tools/api/application#ready
+	 */
+	export const ready: () => boolean;
+}

package/index.d.ts

@@ -1,5 +1,8 @@
 /// <reference lib="dom" />
 
+import "./platform-api.d.ts";
+
+/** Service selections used when Intl is enabled; an empty list includes every service. */
 export type MaligatorIntlFeature =
 	| "collator"
 	| "number-format"
@@ -11,48 +14,106 @@ export type MaligatorIntlFeature =
 	| "relative-time-format"
 	| "duration-format";
 
+/**
+ * Capture a regular file or a directory tree at build time. Paths are relative to
+ * the project root. Directory patterns support *, ?, and whole-segment **;
+ * every pattern must match a regular file. Symlinks are rejected.
+ * @see https://maligator.ddv.tools/api/build#AssetInclusion
+ */
 export type AssetInclusion =
 	| { type: "file"; path: string }
 	| { type: "directory"; path: string; include: Array<string> };
 
+/** Trusted, strictly validated configuration evaluated for each CLI invocation.
+ * @see https://maligator.ddv.tools/guides/build-configuration
+ */
 export interface MaligatorBuildConfig {
+	/** Project-root-relative entry; an explicit CLI entry takes precedence. */
 	entry?: string;
+	/** Binary name; otherwise inferred from the unscoped package name or project directory. */
 	outputName?: string;
+	/** Named build-time snapshots. Requires surface.maligator; portable serialized images cannot carry these filesystem resources. */
 	assets?: Record<string, AssetInclusion>;
+	modules?: {
+		/** Exact specifier replacements applied before module resolution. Defaults to an empty map. */
+		aliases?: Record<string, string>;
+	};
 	engine?: {
-		/**
-		 * `true` embeds the runtime compiler. `false` keeps eval/Function present
-		 * but makes dynamic compilation throw at runtime. `"compile-check"` also
-		 * rejects statically visible eval/Function calls during the build.
+		/** Lock built-in objects for the entire build. Mutable is intended for compatibility experiments.
+		 * @default "locked"
+		 */
+		primordials?: "locked" | "mutable";
+		/** Control dynamic compilation. false leaves eval/Function present but makes calls throw;
+		 * true embeds the compiler; compile-check also rejects statically visible calls at build time.
+		 * @default false
+		 * @see https://maligator.ddv.tools/api/build#engine.eval
 		 */
 		eval?: boolean | "compile-check";
+		/** Include Realm support.
+		 * @default false
+		 */
 		realms?: boolean;
+		/** Include RegExp; disabling it trades compatibility for binary size.
+		 * @default true
+		 */
 		regexp?: boolean;
+		/** Include Temporal and its calendar/time-zone data.
+		 * @default false
+		 */
+		temporal?: boolean;
 		intl?: {
+			/** Include internationalization services and their native data.
+			 * @default false
+			 */
 			enabled?: boolean;
+			/** Select services. An empty list includes all services when enabled.
+			 * @default []
+			 */
 			features?: Array<MaligatorIntlFeature>;
+			/** Locale-data filtering is not implemented; only an empty list is accepted.
+			 * @default []
+			 */
 			languages?: Array<string>;
 		};
 	};
-	host?: {
-		scheduler?: "single" | "multiprocessing";
-	};
 	surface?: {
+		/** Include Web APIs and Mal.serve. Declarations alone do not enable them.
+		 * @default false
+		 */
 		webPlatform?: boolean;
+		/** Include supported node: modules; see the compatibility table for coverage.
+		 * @default false
+		 */
 		node?: boolean;
+		/** Include the mal namespace. Required for configured assets.
+		 * @default true
+		 */
 		maligator?: boolean;
 	};
 }
 
+/** Preserve the inferred config type. Validation happens when the CLI loads the config.
+ * @example
+ * import { defineBuild } from "@maligator/cli";
+ * export default defineBuild({ entry: "src/index.ts" });
+ * @see https://maligator.ddv.tools/api/build#defineBuild
+ */
 export declare function defineBuild<const Config extends MaligatorBuildConfig>(
 	config: Config,
 ): Config;
 
 export interface MaligatorMaterializeOptions {
+	/** Parent directory for the content-addressed materialization. Defaults to the OS temporary directory. */
 	baseDirectory?: string;
 }
 
 export interface MaligatorAssets {
+	/**
+	 * Atomically write a named snapshot and return its absolute file/directory path.
+	 * Completed materializations are reused by content identity. Unknown names,
+	 * invalid options, and filesystem failures throw synchronously.
+	 * @see https://maligator.ddv.tools/api/runtime#mal.assets.materialize
+	 */
 	materialize(name: string, options?: MaligatorMaterializeOptions): string;
 }
 
@@ -61,29 +122,48 @@ export interface MaligatorRuntime {
 }
 
 export interface MaligatorServeOptions {
+	/** Bind address. Defaults to 0.0.0.0; use 127.0.0.1 for a local-only listener. */
 	hostname?: string;
+	/** TCP port, 0 through 65535. Defaults to 0, which asks the OS to choose a port. */
 	port?: number;
+	/** Handle a request with a Response or an awaited response. */
 	fetch(request: Request): Response | PromiseLike<Response>;
+	/** Header deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
+	 * @default 60000 */
+	headersTimeout?: number;
+	/** Request deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
+	 * @default 300000 */
+	requestTimeout?: number;
+	/** Idle keep-alive deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
+	 * @default 5000 */
+	keepAliveTimeout?: number;
+	/** Concurrent connection limit; 0 also selects the default. Integer 0..2147483647.
+	 * @default 1024 */
+	maxConnections?: number;
 }
 
 export interface MaligatorServer {
+	/** Actual bound port, including an OS-selected port when the requested port was 0. */
 	readonly port: number;
 }
 
 export interface MaligatorWebRuntime {
+	/**
+	 * Start an HTTP listener. Requires surface.webPlatform. The current handle exposes
+	 * its bound port; it has no public stop method. Invalid timeout/connection limits throw,
+	 * as does a hostname that is not ASCII or is 64 characters or longer.
+	 * @see https://maligator.ddv.tools/api/runtime#Mal.serve
+	 */
 	serve(options: MaligatorServeOptions): MaligatorServer;
 }
 
 declare global {
-	/**
-	 * Maligator's core runtime namespace. Present when
-	 * `surface.maligator` is enabled.
+	/** Core namespace, available when surface.maligator is enabled.
+	 * @see https://maligator.ddv.tools/api/runtime#mal
 	 */
 	var mal: MaligatorRuntime;
-
-	/**
-	 * Maligator's web-host extension namespace. Present when
-	 * `surface.webPlatform` is enabled.
+	/** Web host namespace, available when surface.webPlatform is enabled.
+	 * @see https://maligator.ddv.tools/api/runtime#Mal
 	 */
 	var Mal: MaligatorWebRuntime;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@maligator/cli",
-	"version": "0.1.0-alpha.3",
+	"version": "0.1.0-alpha.30",
 	"description": "Ahead-of-time JavaScript compiler and native runtime",
 	"license": "MIT",
 	"homepage": "https://github.com/dirkdev98/maligator#readme",
@@ -30,8 +30,15 @@
 		"bin/maligator.js",
 		"index.js",
 		"index.d.ts",
+		"platform-api.d.ts",
+		"application-api.d.ts",
+		"process-api.d.ts",
+		"test-api.d.ts",
+		"workers-api.d.ts",
+		"workers-host-api.d.ts",
 		"README.md",
-		"LICENSE"
+		"LICENSE",
+		"THIRD_PARTY_NOTICES.md"
 	],
 	"bin": {
 		"maligator": "bin/maligator.js"
@@ -44,6 +51,9 @@
 		}
 	},
 	"optionalDependencies": {
-		"@maligator/cli-darwin-arm64": "0.1.0-alpha.3"
+		"@maligator/cli-darwin-arm64": "0.1.0-alpha.30",
+		"@maligator/cli-darwin-x64": "0.1.0-alpha.30",
+		"@maligator/cli-linux-arm64": "0.1.0-alpha.30",
+		"@maligator/cli-linux-x64": "0.1.0-alpha.30"
 	}
 }

package/platform-api.d.ts

@@ -0,0 +1,6 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+import "./application-api.d.ts";
+import "./workers-api.d.ts";
+import "./workers-host-api.d.ts";
+import "./process-api.d.ts";
+import "./test-api.d.ts";

package/process-api.d.ts

@@ -0,0 +1,281 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+/**
+ * Read the compile-time command, target, and resolved application configuration. No
+ * surface flag is required. Runtime arguments, environment, working directory, and
+ * PID are separate process values.
+ */
+declare module "maligator:process" {
+	/**
+	 * Profiling instrumentation: none by default; sampling for --profile; compiler for
+	 * --profile=compiler. Both profiling modes select full optimization without
+	 * selecting production application behavior.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionProfile
+	 */
+	export type ExecutionProfile = "none" | "sampling" | "compiler";
+
+	/**
+	 * The fixed platform contract of the application image.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionTarget
+	 */
+	export type ExecutionTarget = {
+		/**
+		 * Application operating-system target, not the compiler host. Native builds use
+		 * darwin or linux; WebAssembly uses wasi.
+		 */
+		readonly platform: "darwin" | "linux" | "wasi";
+		/**
+		 * Application architecture. Cross builds report the destination architecture.
+		 */
+		readonly arch: "arm64" | "x64" | "wasm32";
+		/**
+		 * Resolved target triple, including when --target was omitted; for example
+		 * aarch64-apple-darwin.
+		 */
+		readonly triple: string;
+	};
+
+	/**
+	 * Options shared by build, run, and dev. Output paths, verbosity, and compiler
+	 * scheduling are tool settings and are not exposed.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionOptions
+	 */
+	export type ExecutionOptions = {
+		/**
+		 * Selected application profiling instrumentation. Defaults to none; does not imply
+		 * execution.production.
+		 */
+		readonly profile: ExecutionProfile;
+	};
+
+	/**
+	 * Normalized test settings, fixed for the application image. Changing these values
+	 * invalidates specialized test artifacts.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#TestExecutionOptions
+	 */
+	export type TestExecutionOptions = {
+		/**
+		 * Selected test profiling instrumentation. Defaults to none; profiling preserves
+		 * command: test.
+		 */
+		readonly profile: ExecutionProfile;
+		/**
+		 * Hierarchical test-name filter from --run, or null when all discovered names are
+		 * eligible.
+		 */
+		readonly nameFilter: string | null;
+		/**
+		 * Number of requested test repetitions from --repeat; defaults to 1. This is not
+		 * the currently executing repetition.
+		 */
+		readonly repeat: number;
+		/**
+		 * Whether --bail stops the test run after its first failure. Defaults to false.
+		 */
+		readonly bail: boolean;
+		/**
+		 * Test callback timeout in milliseconds from --timeout. Defaults to 5000.
+		 */
+		readonly timeoutMs: number;
+		/**
+		 * Resolved positive shuffle seed, or null when shuffling is disabled. --shuffle
+		 * without a seed chooses it once before compilation; the same seed drives execution
+		 * and cache identity.
+		 */
+		readonly shuffleSeed: number | null;
+	};
+
+	/**
+	 * Resolved engine policies. These describe build inputs, never post-DCE native
+	 * feature inclusion.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionEngineConfig
+	 */
+	export type ExecutionEngineConfig = {
+		/**
+		 * Requested primordial mutation policy. Defaults to locked. The execution snapshot
+		 * itself is immutable in either policy.
+		 */
+		readonly primordials: "locked" | "mutable";
+		/**
+		 * Dynamic compilation policy. false (default) rejects eval/Function execution at
+		 * runtime; true enables the runtime compiler; compile-check additionally rejects
+		 * statically visible dynamic compilation calls.
+		 */
+		readonly eval: boolean | "compile-check";
+		/**
+		 * Whether additional realms are enabled. Defaults to false.
+		 */
+		readonly realms: boolean;
+		/**
+		 * Whether regular expressions are enabled. Defaults to true.
+		 */
+		readonly regexp: boolean;
+		/**
+		 * Whether Temporal and its required data are enabled. Defaults to false.
+		 */
+		readonly temporal: boolean;
+		/**
+		 * Requested Intl policy after applying configuration defaults.
+		 */
+		readonly intl: {
+			/**
+			 * Whether Intl is enabled. Defaults to false.
+			 */
+			readonly enabled: boolean;
+			/**
+			 * Requested Intl service names. An empty array selects the default complete
+			 * service set when Intl is enabled; it does not mean every service survived tree
+			 * shaking.
+			 */
+			readonly features: ReadonlyArray<string>;
+			/**
+			 * Requested locale selection. Defaults to an empty array. Unsupported locale
+			 * selections are rejected by configuration validation.
+			 */
+			readonly languages: ReadonlyArray<string>;
+		};
+	};
+
+	/**
+	 * Resolved application engine, Web/Node surface, and module policies. Excludes
+	 * build-host paths, asset declarations, and output controls.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionConfig
+	 */
+	export type ExecutionConfig = {
+		/**
+		 * Engine configuration after validation and default resolution.
+		 */
+		readonly engine: ExecutionEngineConfig;
+		/**
+		 * Global and compatibility surface policy. maligator:process requires no enable
+		 * flag.
+		 */
+		readonly surface: {
+			/**
+			 * Whether Web globals are requested. Defaults to false; native module imports are
+			 * independent of this global installation policy.
+			 */
+			readonly webPlatform: boolean;
+			/**
+			 * Whether Node compatibility, globals, and node: module resolution are requested.
+			 * Defaults to false.
+			 */
+			readonly node: boolean;
+		};
+		/**
+		 * Resolved module-resolution policy.
+		 */
+		readonly modules: {
+			/**
+			 * Exact module-specifier replacements from configuration. Defaults to an empty
+			 * object. Alias entries are immutable own data properties.
+			 */
+			readonly aliases: Readonly<Record<string, string>>;
+		};
+	};
+
+	/**
+	 * Fields shared by every execution workflow. All nested objects and arrays are
+	 * deeply frozen at runtime.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionCommon
+	 */
+	export type ExecutionCommon = {
+		/**
+		 * Explicit production application intent. True only when production was selected
+		 * for the application; independent of NODE_ENV, profiling, and optimization.
+		 * Currently --production is a build option. Defaults to false.
+		 */
+		readonly production: boolean;
+		/**
+		 * Whether the application image executes as native compiled code. A native
+		 * executable hosting an interpreted image reports false. This is fixed for the
+		 * image, not a query about the current stack frame or an eval-created function.
+		 */
+		readonly compiled: boolean;
+		/**
+		 * Actual selected frontend optimization policy. Ordinary commands currently use
+		 * development; production builds and profiling use full. Backend choice is
+		 * independent.
+		 */
+		readonly optimization: "development" | "full";
+		/**
+		 * Resolved application target. The compiler's host platform is not substituted
+		 * during a cross build.
+		 */
+		readonly target: ExecutionTarget;
+		/**
+		 * Validated configuration policies with defaults applied, captured before
+		 * compilation.
+		 */
+		readonly config: ExecutionConfig;
+	};
+
+	/**
+	 * An immutable application-image description, discriminated by command. The command
+	 * describes the workflow that prepared the image, not a transient process phase.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#Execution
+	 */
+	export type Execution = ExecutionCommon &
+		(
+			| {
+					/**
+					 * Prepared by maligator build. Remains build when the resulting executable runs
+					 * later; application statements are not executed by the build itself.
+					 */
+					readonly command: "build";
+					/**
+					 * Normalized build options relevant to application execution.
+					 */
+					readonly options: ExecutionOptions;
+			  }
+			| {
+					/**
+					 * Prepared by maligator run or maligator dev. dev denotes the watch/restart
+					 * workflow even when profiling selects native compilation.
+					 */
+					readonly command: "run" | "dev";
+					/**
+					 * Normalized run/dev options. Arguments after -- remain runtime argv and do not
+					 * specialize application compilation.
+					 */
+					readonly options: ExecutionOptions;
+			  }
+			| {
+					/**
+					 * Prepared by maligator test. Preserved for interpreted tests, profiled native
+					 * tests, and every fragment of the test application.
+					 */
+					readonly command: "test";
+					/**
+					 * Normalized test options. Narrow command to test before accessing test-only
+					 * fields.
+					 */
+					readonly options: TestExecutionOptions;
+			  }
+		);
+
+	/**
+	 * An immutable snapshot of the workflow, target, and resolved configuration, fixed
+	 * before compilation. Known property reads can specialize application branches.
+	 * Runtime arguments, environment, working directory, and PID are outside this
+	 * snapshot. Profiling does not change production intent. Static and dynamic imports
+	 * share its identity, and reflection sees the complete deeply frozen shape.
+	 *
+	 * @example
+	 * import { execution } from "maligator:process";
+	 *
+	 * if (execution.compiled && execution.production) {
+	 *   console.log("native production application");
+	 * }
+	 *
+	 * @see https://maligator.ddv.tools/api/process#execution
+	 */
+	export const execution: Execution;
+}