heximon 0.7.0 → 0.8.0

package/README.md

@@ -78,7 +78,7 @@ const main = defineCommand({
 | `heximon provision` | Creates a resource your build needs an identifier for, before the build runs. |
 | `heximon migrations` | Runs `generate`, `migrate`, `status`, or `push` against your database, with no hand-written `drizzle-kit` config. |
 | `heximon workflows` | Compares a durable workflow's current shape against its committed upgrade baseline. |
-| `heximon task run <Module> <Task>` | Runs one task against the production graph of the app, prints its result as JSON, and exits. It starts no HTTP listener, no schedule timer, no polling loop, and no outbox relay (`--with-outbox-relay` starts it). It refuses a graph that needs platform bindings. `--payload` sets the event payload, and `--env-file` loads variables. |
+| `heximon task run <Module> <Task>` | Runs one task against the production graph of the app, prints its result as JSON, and exits. It starts no HTTP listener, no schedule timer, no polling loop, and no outbox relay (`--with-outbox-relay` starts it). It refuses a graph that needs platform bindings. The module can be a packed library module: the command runs the tasks that the module exports. `--payload` sets the event payload, and `--env-file` loads variables. Exit status: `0` when the task returned, `2` when the task itself threw (stdout then holds one `{"error":{"name":…,"message":…}}` line), `1` for every other failure. |
 | `heximon skills` | `add <url>` records an agent-skill source in `package.json` (`heximon.skills`) and installs it. `sync` re-installs every recorded source. |
 | `heximon complete <shell>` | Installs shell completion for `zsh`, `bash`, `fish`, `powershell`, or `fig`. |
 

package/dist/bin.mjs

@@ -3467,8 +3467,9 @@ var TaskTargetError = class extends Error {
 };
 /**
 * Picks the module class and the task class that `heximon task run <ModuleClass> <TaskClass>` names, by class
-* name, in the compiled graph. A name that matches nothing or more than one class fails with the names that
-* come close.
+* name, in the compiled graph. A packed library module is a boundary of the graph: the command reaches only the
+* tasks that it exports. A name that matches nothing or more than one class fails with the names that come
+* close.
 */
 var TaskTargetResolver = class TaskTargetResolver {
 	/** The most edits between a typed name and a suggestion. */
@@ -3478,20 +3479,24 @@ var TaskTargetResolver = class TaskTargetResolver {
 	/**
 	* @param graph - The module graph of the production compile.
 	* @param moduleName - The module class name.
-	* @param taskName - The task class name; the module must provide it.
+	* @param taskName - The task class name; the module must provide it (a library module: export it).
+	* @param boundaries - The packed library modules of the graph.
 	* @returns The module and the task.
 	* @throws {TaskTargetError} When a name matches no class, or more than one.
 	*/
-	static resolve(graph, moduleName, taskName) {
-		const modules = TaskTargetResolver.distinct(graph.modules.map((node) => node.reference), moduleName);
-		if (modules.length === 0) throw new TaskTargetError(`No module class named "${moduleName}" is in the compiled graph.` + TaskTargetResolver.suggestions(moduleName, graph.modules.map((node) => TaskTargetResolver.nameOf(node.reference)), "Modules in the graph"));
+	static resolve(graph, moduleName, taskName, boundaries = []) {
+		const moduleReferences = [...graph.modules.map((node) => node.reference), ...boundaries.map((boundary) => boundary.reference)];
+		const modules = TaskTargetResolver.distinct(moduleReferences, moduleName);
+		if (modules.length === 0) throw new TaskTargetError(`No module class named "${moduleName}" is in the compiled graph.` + TaskTargetResolver.suggestions(moduleName, moduleReferences.map((reference) => TaskTargetResolver.nameOf(reference)), "Modules in the graph"));
 		if (modules.length > 1) throw new TaskTargetError(`More than one module class is named "${moduleName}":\n` + modules.map((reference) => `  - ${reference.sourceFile}`).join("\n"));
 		const module = modules[0];
 		const nodes = graph.modules.filter((node) => TaskTargetResolver.isSame(node.reference, module));
-		const providerTokens = nodes.flatMap((node) => node.providers.map((provider) => provider.token));
-		const tasks = TaskTargetResolver.distinct(providerTokens, taskName);
-		if (tasks.length === 0) throw new TaskTargetError(`The module ${moduleName} does not provide a class named "${taskName}".` + TaskTargetResolver.otherOwner(graph, nodes, taskName) + TaskTargetResolver.suggestions(taskName, providerTokens.map((token) => TaskTargetResolver.nameOf(token)), `Providers of ${moduleName}`));
-		if (tasks.length > 1) throw new TaskTargetError(`The module ${moduleName} provides more than one class named "${taskName}":\n` + tasks.map((reference) => `  - ${reference.sourceFile}`).join("\n"));
+		const libraries = boundaries.filter((boundary) => TaskTargetResolver.isSame(boundary.reference, module));
+		const isLibrary = nodes.length === 0 && libraries.length > 0;
+		const candidates = isLibrary ? libraries.flatMap((boundary) => boundary.exports.map((exported) => exported.token)) : nodes.flatMap((node) => node.providers.map((provider) => provider.token));
+		const tasks = TaskTargetResolver.distinct(candidates, taskName);
+		if (tasks.length === 0) throw new TaskTargetError((isLibrary ? `The library module ${moduleName} does not export a class named "${taskName}". \`heximon task run\` reaches the tasks that a library module exports: export the task from the module and pack the library again.` : `The module ${moduleName} does not provide a class named "${taskName}".`) + TaskTargetResolver.otherOwner(graph, boundaries, module, taskName) + TaskTargetResolver.suggestions(taskName, candidates.map((token) => TaskTargetResolver.nameOf(token)), isLibrary ? `Exports of ${moduleName}` : `Providers of ${moduleName}`));
+		if (tasks.length > 1) throw new TaskTargetError(`The module ${moduleName} ${isLibrary ? "exports" : "provides"} more than one class named "${taskName}":\n` + tasks.map((reference) => `  - ${reference.sourceFile}`).join("\n"));
 		return {
 			module,
 			task: tasks[0]
@@ -3511,11 +3516,11 @@ var TaskTargetResolver = class TaskTargetResolver {
 		for (const reference of references) if (TaskTargetResolver.nameOf(reference) === name && !found.some((known) => TaskTargetResolver.isSame(known, reference))) found.push(reference);
 		return found;
 	}
-	/** A hint when another module of the graph provides the class. */
-	static otherOwner(graph, own, taskName) {
-		const owners = graph.modules.filter((node) => !own.includes(node) && node.providers.some((provider) => TaskTargetResolver.nameOf(provider.token) === taskName));
+	/** A hint when another module of the graph provides (or a library module exports) the class. */
+	static otherOwner(graph, boundaries, own, taskName) {
+		const owners = [...graph.modules.filter((node) => !TaskTargetResolver.isSame(node.reference, own) && node.providers.some((provider) => TaskTargetResolver.nameOf(provider.token) === taskName)).map((node) => node.reference), ...boundaries.filter((boundary) => !TaskTargetResolver.isSame(boundary.reference, own) && boundary.exports.some((exported) => TaskTargetResolver.nameOf(exported.token) === taskName)).map((boundary) => boundary.reference)];
 		if (owners.length === 0) return "";
-		return ` The class is provided by ${[...new Set(owners.map((node) => TaskTargetResolver.nameOf(node.reference)))].join(", ")}.`;
+		return ` The class is provided by ${[...new Set(owners.map((reference) => TaskTargetResolver.nameOf(reference)))].join(", ")}.`;
 	}
 	/** The "did you mean" line, or the start of the list when nothing is close. */
 	static suggestions(typed, candidates, listTitle) {
@@ -3654,6 +3659,8 @@ var RefusingInternalClient = class {
 };
 /** The failure a run reports to the caller; the message is ready to print. */
 var TaskRunFailure = class extends Error {};
+/** The task itself threw. The message is ready to print, and the thrown value is the cause. */
+var TaskRefusal = class extends TaskRunFailure {};
 /**
 * `heximon task run`: compiles the production graph into a temporary directory, boots it in this process,
 * runs one {@link Task}, prints its result as JSON, and removes the compile output.
@@ -3671,6 +3678,8 @@ var TaskRunner = class TaskRunner {
 	static drainTimeoutMilliseconds = 1e4;
 	/** The most the interrupt handler waits for the app to shut down. */
 	static interruptShutdownMilliseconds = 5e3;
+	/** The exit code of a run whose task itself threw. Every other failure exits with `1`. */
+	static refusalExitCode = 2;
 	static wiringFilePattern = /^apps\/.+\.wiring\.js$/;
 	outputDirectory;
 	app;
@@ -3688,14 +3697,17 @@ var TaskRunner = class TaskRunner {
 	/** The result of the task as one line of JSON, printed after the shutdown. */
 	serialized;
 	disposing;
+	/** How many package specifiers the run imported, for the file names of {@link ProjectModules.import}. */
+	packageImports = 0;
 	constructor(options) {
 		this.options = options;
 	}
 	/**
 	* Run the task.
 	*
-	* @returns The process exit code: `0` when the task returned, `1` for every other outcome. The reason is
-	*   already on stderr.
+	* @returns The process exit code: `0` when the task returned, `2` when the task itself threw (stdout then
+	*   holds one `{"error":{"name":…,"message":…}}` line), `1` for every other outcome. The reason is already
+	*   on stderr.
 	*/
 	async run() {
 		let interrupts = 0;
@@ -3718,9 +3730,12 @@ var TaskRunner = class TaskRunner {
 			await this.execute(target);
 		} catch (error) {
 			TaskRunner.report(error);
-			exitCode = 1;
+			if (error instanceof TaskRefusal) {
+				exitCode = TaskRunner.refusalExitCode;
+				this.serialized = TaskRunner.errorLine(error.cause);
+			} else exitCode = 1;
 		} finally {
-			if (!await this.dispose()) exitCode = 1;
+			if (!await this.dispose() && exitCode === 0) exitCode = 1;
 			this.stdout.stop();
 			if (this.serialized !== void 0) this.stdout.write(`${this.serialized}\n`);
 			process.off("SIGINT", interrupt);
@@ -3793,7 +3808,7 @@ var TaskRunner = class TaskRunner {
 	/** Pick the module and the task from the compiled graph. */
 	pickTarget(output) {
 		if (output.moduleGraph === void 0) throw new TaskRunFailure("The compile produced no module graph, so the task cannot be found.");
-		return TaskTargetResolver.resolve(output.moduleGraph, this.options.moduleName, this.options.taskName);
+		return TaskTargetResolver.resolve(output.moduleGraph, this.options.moduleName, this.options.taskName, output.boundaryNodes);
 	}
 	/** Refuse a graph that needs bindings only its platform has, before anything boots. */
 	static refuseBindings(output, platformName, outputDirectory) {
@@ -3837,15 +3852,34 @@ var TaskRunner = class TaskRunner {
 		const moduleClass = await this.importClass(target.module.sourceFile, target.module.className);
 		const taskClass = await this.importClass(target.task.sourceFile, target.task.className);
 		if (typeof taskClass.prototype.run !== "function") throw new TaskRunFailure(`${this.options.taskName} is not a task: the class has no run() method. A task extends Task.`);
-		const manager = new runtime.TaskManager(this.app, this.context, await this.seedsOf(runtime));
+		let task;
+		try {
+			task = await this.app.from(moduleClass).get(taskClass);
+		} catch (error) {
+			throw new TaskRunFailure(`The task ${this.options.taskName} could not be created:\n${TaskRunner.describe(error)}`, { cause: error });
+		}
+		const event = {
+			name: this.options.taskName,
+			...this.options.payload === void 0 ? {} : { payload: this.options.payload }
+		};
+		const seeds = await this.seedsOf(runtime);
 		let outcome;
 		try {
-			outcome = await manager.from(moduleClass).run(taskClass, {
-				name: this.options.taskName,
-				...this.options.payload === void 0 ? {} : { payload: this.options.payload }
+			outcome = await this.context.run(async () => {
+				try {
+					await seeds?.apply(event, this.context);
+				} catch (error) {
+					throw new TaskRunFailure(`The task ${this.options.taskName} did not start:\n${TaskRunner.describe(error)}`, { cause: error });
+				}
+				try {
+					return await task.run(event);
+				} catch (error) {
+					throw new TaskRefusal(`The task ${this.options.taskName} failed:\n${TaskRunner.describe(error)}`, { cause: error });
+				}
 			});
 		} catch (error) {
-			throw new TaskRunFailure(`The task ${this.options.taskName} failed:\n${error instanceof Error ? error.stack ?? error.message : String(error)}`, { cause: error });
+			if (error instanceof TaskRunFailure) throw error;
+			throw new TaskRunFailure(`The task ${this.options.taskName} did not start:\n${TaskRunner.describe(error)}`, { cause: error });
 		}
 		try {
 			this.serialized = JSON.stringify(outcome);
@@ -3863,9 +3897,13 @@ var TaskRunner = class TaskRunner {
 			throw error;
 		}
 	}
-	/** Import a class by file (or package specifier) and export name. */
+	/**
+	* Import a class by file (or package specifier) and export name. A package specifier resolves from the
+	* project, like the generated wiring, so the class is the one the app holds.
+	*/
 	async importClass(sourceFile, className) {
-		const found = (await (isAbsolute(sourceFile) ? import(pathToFileURL(sourceFile).href) : import(sourceFile)))[className];
+		this.packageImports += 1;
+		const found = (isAbsolute(sourceFile) ? await import(pathToFileURL(sourceFile).href) : await ProjectModules.import(this.outputDirectory, `project-package-${this.packageImports}.js`, `export * from ${JSON.stringify(sourceFile)};\n`))[className];
 		if (found === void 0) throw new TaskRunFailure(`${sourceFile} does not export a class named ${className}.`);
 		return found;
 	}
@@ -3916,6 +3954,26 @@ var TaskRunner = class TaskRunner {
 		});
 		process.exit(signal === "SIGINT" ? 130 : 143);
 	}
+	/** The text of a thrown value: the stack of an error, else its string form. */
+	static describe(error) {
+		return error instanceof Error ? error.stack ?? error.message : String(error);
+	}
+	/**
+	* The one stdout line of a refused run: `{"error":{"name":…,"message":…}}`. The name is the error name, or the
+	* class name when the class leaves the generic `Error` name.
+	*/
+	static errorLine(thrown) {
+		if (!(thrown instanceof Error)) return JSON.stringify({ error: {
+			name: "Error",
+			message: String(thrown)
+		} });
+		const className = thrown.constructor?.name;
+		const name = thrown.name === "Error" && className !== void 0 && className !== "" ? className : thrown.name;
+		return JSON.stringify({ error: {
+			name,
+			message: thrown.message
+		} });
+	}
 	/** Print a failure on stderr. */
 	static report(error) {
 		if (error instanceof TaskRunFailure || error instanceof TaskTargetError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heximon",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The Heximon CLI: create, develop, build, migrate, and deploy Heximon apps.",
   "keywords": [
     "cli",
@@ -38,25 +38,27 @@
   "dependencies": {
     "@bomb.sh/tab": "^0.0.22",
     "@clack/prompts": "^1.8.1",
-    "@heximon/compiler": "0.7.0",
-    "@heximon/cqrs": "0.7.0",
-    "@heximon/deploy": "0.7.0",
-    "@heximon/http": "0.7.0",
-    "@heximon/node": "0.7.0",
-    "@heximon/runtime": "0.7.0",
-    "@heximon/testing": "0.7.0",
+    "@heximon/compiler": "0.8.0",
+    "@heximon/cqrs": "0.8.0",
+    "@heximon/deploy": "0.8.0",
+    "@heximon/http": "0.8.0",
+    "@heximon/node": "0.8.0",
+    "@heximon/runtime": "0.8.0",
+    "@heximon/testing": "0.8.0",
     "citty": "^0.2.2",
     "giget": "^3.3.1",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@heximon/cloudflare": "0.7.0",
-    "@heximon/durable": "0.7.0",
-    "@heximon/integration": "0.7.0",
-    "@heximon/nitro": "0.7.0",
-    "@heximon/queue": "0.7.0",
-    "@heximon/schedule": "0.7.0",
-    "@heximon/schema": "0.7.0",
+    "@heximon/cloudflare": "0.8.0",
+    "@heximon/durable": "0.8.0",
+    "@heximon/integration": "0.8.0",
+    "@heximon/library": "0.8.0",
+    "@heximon/nitro": "0.8.0",
+    "@heximon/queue": "0.8.0",
+    "@heximon/schedule": "0.8.0",
+    "@heximon/schema": "0.8.0",
+    "@heximon/test-support": "0.0.1",
     "@types/node": "^24.19.0",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "5.0.1",