@maligator/cli 0.1.0-alpha.27 → 0.1.0-alpha.29

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

@@ -2,6 +2,7 @@
 
 import "./platform-api.d.ts";
 
+/** Service selections used when Intl is enabled; an empty list includes every service. */
 export type MaligatorIntlFeature =
 	| "collator"
 	| "number-format"
@@ -13,56 +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. */
+		/** Exact specifier replacements applied before module resolution. Defaults to an empty map. */
 		aliases?: Record<string, string>;
 	};
 	engine?: {
-		/**
-		 * Lock ECMAScript primordials for this entire build. Locked is the default;
-		 * mutable is intended for conformance suites and compatibility experiments.
+		/** Lock built-in objects for the entire build. Mutable is intended for compatibility experiments.
+		 * @default "locked"
 		 */
 		primordials?: "locked" | "mutable";
-		/**
-		 * `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.
+		/** 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 the Temporal global and its calendar/time-zone data. */
+		/** 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>;
 		};
 	};
 	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;
 }
 
@@ -71,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.27",
+	"version": "0.1.0-alpha.29",
 	"description": "Ahead-of-time JavaScript compiler and native runtime",
 	"license": "MIT",
 	"homepage": "https://github.com/dirkdev98/maligator#readme",
@@ -31,10 +31,14 @@
 		"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"
@@ -47,9 +51,9 @@
 		}
 	},
 	"optionalDependencies": {
-		"@maligator/cli-darwin-arm64": "0.1.0-alpha.27",
-		"@maligator/cli-darwin-x64": "0.1.0-alpha.27",
-		"@maligator/cli-linux-arm64": "0.1.0-alpha.27",
-		"@maligator/cli-linux-x64": "0.1.0-alpha.27"
+		"@maligator/cli-darwin-arm64": "0.1.0-alpha.29",
+		"@maligator/cli-darwin-x64": "0.1.0-alpha.29",
+		"@maligator/cli-linux-arm64": "0.1.0-alpha.29",
+		"@maligator/cli-linux-x64": "0.1.0-alpha.29"
 	}
 }

package/platform-api.d.ts

@@ -1,3 +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

@@ -1,20 +1,23 @@
 // Generated from src/platform/catalog.ts; edit the catalog and regenerate.
 /**
- * Application execution context. Importing this module has no externally observable
- * effects and requires no configuration switch. Unused exports and native
- * implementation dependencies are eliminated. Process arguments, environment, working
- * directory, and PID are runtime concerns outside execution.
+ * 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 = {
 		/**
@@ -36,6 +39,8 @@ declare module "maligator:process" {
 	/**
 	 * 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 = {
 		/**
@@ -48,6 +53,8 @@ declare module "maligator:process" {
 	/**
 	 * 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 = {
 		/**
@@ -70,8 +77,7 @@ declare module "maligator:process" {
 		 */
 		readonly bail: boolean;
 		/**
-		 * Default test timeout in milliseconds from --timeout. Defaults to 5000; individual
-		 * test APIs can select a different timeout.
+		 * Test callback timeout in milliseconds from --timeout. Defaults to 5000.
 		 */
 		readonly timeoutMs: number;
 		/**
@@ -85,6 +91,8 @@ declare module "maligator:process" {
 	/**
 	 * Resolved engine policies. These describe build inputs, never post-DCE native
 	 * feature inclusion.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionEngineConfig
 	 */
 	export type ExecutionEngineConfig = {
 		/**
@@ -133,9 +141,10 @@ declare module "maligator:process" {
 	};
 
 	/**
-	 * Public application policies from the selected build configuration. Excludes
-	 * build-host paths, asset declarations, output controls, and the obsolete Maligator
-	 * surface switch.
+	 * 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 = {
 		/**
@@ -173,6 +182,8 @@ declare module "maligator:process" {
 	/**
 	 * 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 = {
 		/**
@@ -208,6 +219,8 @@ declare module "maligator:process" {
 	/**
 	 * 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 &
 		(
@@ -249,16 +262,11 @@ declare module "maligator:process" {
 		);
 
 	/**
-	 * The canonical execution description, fixed before application compilation. Reads
-	 * of known own properties, import aliases and re-exports, immutable aliases and
-	 * destructuring, primitive comparisons, boolean expressions, and if/switch branches
-	 * specialize in development and full compilation. Dynamic keys and opaque calls
-	 * remain ordinary JavaScript and may retain the runtime object. The snapshot has
-	 * stable identity within an application context and deeply frozen own data
-	 * properties; reflection sees the complete shape. Static and dynamic imports return
-	 * the same export. A different command, option, configuration, target, or backend
-	 * creates a different compilation context. Profiling does not change production
-	 * intent. Importing the module does not keep unused native code alive.
+	 * 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";
@@ -267,12 +275,7 @@ declare module "maligator:process" {
 	 *   console.log("native production application");
 	 * }
 	 *
-	 * @example
-	 * import { execution } from "maligator:process";
-	 *
-	 * if (execution.command === "test") {
-	 *   console.log(execution.options.repeat);
-	 * }
+	 * @see https://maligator.ddv.tools/api/process#execution
 	 */
 	export const execution: Execution;
 }

package/test-api.d.ts

@@ -9,16 +9,22 @@ declare module "maligator:test" {
 	/**
 	 * A test or hook body. Maligator waits for a returned promise or thenable before
 	 * advancing the lifecycle.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#TestCallback
 	 */
 	export type TestCallback = () => unknown;
 
 	/**
 	 * A lifecycle hook body, with the same async completion contract as a test.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#HookCallback
 	 */
 	export type HookCallback = TestCallback;
 
 	/**
 	 * A constructable value accepted by {@link expect.any}.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#Constructor
 	 */
 	export type Constructor = abstract new (...args: Array<never>) => unknown;
 
@@ -26,6 +32,8 @@ declare module "maligator:test" {
 	 * Opaque partial-match value produced by helpers such as {@link
 	 * expect.objectContaining}. It may be nested inside `toEqual`, `toStrictEqual`, and
 	 * `toMatchObject` expectations.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#AsymmetricMatcher
 	 */
 	export type AsymmetricMatcher = {
 		readonly __maligator_asymmetric__: string;
@@ -33,6 +41,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Matchers for a synchronously received value.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#Matchers
 	 */
 	export type Matchers = {
 		/** Negate the following matcher. */
@@ -86,6 +96,8 @@ declare module "maligator:test" {
 	 * Promise-returning matcher surface exposed by {@link Matchers.resolves} and {@link
 	 * Matchers.rejects}. Await these calls so the test cannot finish before the
 	 * assertion.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#AsyncMatchers
 	 */
 	export type AsyncMatchers = {
 		/** Negate the following asynchronous matcher. */
@@ -113,6 +125,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Assertion entrypoint and Maligator-owned asymmetric matcher factories.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#ExpectFunction
 	 */
 	export type ExpectFunction = {
 		/** Create matchers for `received`. The assertion position is captured here. */
@@ -131,6 +145,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Register tests in the current suite during module evaluation.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#TestFunction
 	 */
 	export type TestFunction = {
 		/** Register a test. Returned promises are awaited by the runner. */
@@ -155,6 +171,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Register nested suites synchronously during module evaluation.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#DescribeFunction
 	 */
 	export type DescribeFunction = {
 		/** Register a suite. Suite callbacks must not return a promise. */
@@ -167,32 +185,46 @@ declare module "maligator:test" {
 
 	/**
 	 * Register a test in the current suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#test
 	 */
 	export const test: TestFunction;
 	/**
 	 * Register a nested suite in the current suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#describe
 	 */
 	export const describe: DescribeFunction;
 	/**
 	 * Create fluent matchers for a received value.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#expect
 	 */
 	export const expect: ExpectFunction;
 	/**
 	 * Run once before tests in the current suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#beforeAll
 	 */
 	export const beforeAll: (callback: HookCallback) => void;
 	/**
 	 * Run once after tests in the current suite, including after test failures.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#afterAll
 	 */
 	export const afterAll: (callback: HookCallback) => void;
 	/**
 	 * Run before every selected descendant test. Ancestor hooks run before hooks
 	 * declared by a nested suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#beforeEach
 	 */
 	export const beforeEach: (callback: HookCallback) => void;
 	/**
 	 * Run after every selected descendant test. Nested-suite hooks run before ancestor
 	 * hooks.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#afterEach
 	 */
 	export const afterEach: (callback: HookCallback) => void;
 }